通过 HTTP API 远程操作 OpenCode 服务器。用于管理远程 OpenCode 实例的会话、监控状态和执行任务。 核心功能： 1. 管理多个"主session"（每个有独立的四词短名、endpoint、任务） 2. 向 session 发送消息（默认不指定agent，延续之前使用） 3. 自动监控：发...
通过 HTTP API 与远程 OpenCode 服务器交互，实现多 session 管理、状态监控和任务执行。
每个主 session 有：
csbx, kumo, hetc）| 短名 | Endpoint | Session ID | 任务 |
|---|---|---|---|
| csbx | acf3108.ece.ust.hk:4096 | ses_36c5b7b5effe3AHLnYQJGbgDr7 | OpenCode Web 集成 |
| kumo | acf3108.ece.ust.hk:9004 | ses_34857e78affew0nYs8DQWml3q8 | k8s macOS 部署 |
| hetc | acf3108.ece.ust.hk:35457 | ses_33c2542cbffe2GO3tL5tHTaiRT | HETC 项目开发 |
curl -s http://<host>:<port>/global/health | jq
curl -s http://<host>:<port>/session | jq
# 基本信息
curl -s http://<host>:<port>/session/<sessionID> | jq
# 消息记录
curl -s http://<host>:<port>/session/<sessionID>/message | jq
# 待办事项（最准确的状态检查）
curl -s http://<host>:<port>/session/<sessionID>/todo | jq
默认不指定 agent：除非用户明确要求，否则不设置 agent 字段，让系统使用默认 agent 或延续之前使用的 agent。
每次发送消息后，必须完整重复发送的内容给用户确认：
以下是我发送给 <session_name> 的完整 prompt：
[完整的 prompt 内容，保持原样]
示例：
以下是我发送给 csbx 的完整 prompt：
做一下 git pull，然后看一下 commit message，看看最近 git 里的人都在干啥。
为什么重要：
同步发送（等待 AI 响应）：
POST /session/{id}/message
异步发送（立即返回 204）：
POST /session/{id}/prompt_async
# ✅ 不指定 agent（推荐）
curl -s -X POST http://<host>:<port>/session/<sessionID>/message \
-H "Content-Type: application/json" \
-d '{
"parts": [{"type": "text", "text": "prompt内容"}],
"model": {"providerID": "openai", "modelID": "gpt-5.4"}
}'
# 发送后向用户报告：
# "以下是我发送给 csbx 的完整 prompt："
# "prompt内容"
先调用 GET /agent 获取完整列表，常用 primary agents：
Sisyphus (Ultraworker) - 主要工作 agentHephaestus (Deep Agent) - 深度分析Prometheus (Plan Builder) - 规划构建Atlas (Plan Executor) - 规划执行build, plan, general, explore - subagents每当向一个 session 发送消息后，必须自动设置监控：
当监测到 session 从 active/running 状态变为 stopped/completed 时：
📋 <session_name> 会话已结束
**最后输出**：
[完整的最后一条或几条 assistant 消息，包含所有 text 内容]
**任务总结**：
- 完成状态：✅ 完成 / ❌ 失败
- Todo 进度：X/Y 完成
- 建议：取消监控 / 继续观察
如何检测会话结束：
info.time.completed 不为 nullcompleted 状态running 变为 stopped示例检测逻辑：
# 获取最新消息状态
LATEST=$(curl -s http://host:port/session/ID/message?limit=1 | jq '.[0]')
COMPLETED=$(echo $LATEST | jq '.info.time.completed')
if [ "$COMPLETED" != "null" ]; then
# 会话已结束，提取完整输出
TEXT=$(echo $LATEST | jq -r '.parts[] | select(.type == "text") | .text')
echo "会话已结束，最后输出：$TEXT"
fi
如果用户同时监控多个 session，合并为一个定时任务：
⏰ 监控多个主 session 状态（每5分钟）
1. csbx (ses_xxx) @ host:port
2. kumo (ses_xxx) @ host:port
3. hetc (ses_xxx) @ host:port
查询每个 session 的 todo 状态并汇总汇报
# 使用 cron 创建每5分钟监控
cron add \
--name "monitor-main-sessions" \
--schedule "every 5 minutes" \
--command "查询所有主session的todo状态并汇报"
创建新 session 时，必须先询问用户：
"您想用哪个 agent 创建新 session？可用选项：
- Sisyphus (Ultraworker) - 主要工作
- Hephaestus (Deep Agent) - 深度分析
- 其他 subagents: build, plan, general, explore
或者使用默认 agent（不推荐）？"
curl -s -X POST http://<host>:<port>/session \
-H "Content-Type: application/json" \
-d '{"title": "新 session 标题"}'
创建后记录到 opencode-sessions.md：
## 主 Session 列表
| 短名 | Endpoint | Session ID | 任务 | 创建时间 |
|------|----------|------------|------|----------|
| xxx | host:port | ses_xxx | 任务描述 | 2026-03-07 |
方法一：优先检查 todo 列表（最准确）
curl -s http://<host>:<port>/session/<sessionID>/todo | jq '
group_by(.status) | map({status: .[0].status, count: length})
'
方法二：检查多条消息判断会话结束
# ✅ 检查最新消息是否已完成
curl -s http://<host>:<port>/session/<sessionID>/message?limit=1 | jq '
.[0] | {completed: .info.time.completed, text: .parts[] | select(.type == "text") | .text[:200]}
'
方法三：对比消息 ID 变化
# 记录上次消息 ID，对比是否变化
错误做法：
# ❌ 不要只查单条消息！
curl .../message?limit=1 | jq '.[0] | {completed}'
错误做法：
# ❌ 不要指定不存在的 agent
"agent": "main" # 不存在，会导致 agent.variant 错误
错误做法：
# ❌ 发送后不向用户确认
# 必须重复发送的内容给用户
# 列出所有 sessions
python3 scripts/opencode_client.py --url http://<host>:<port> list
# 查看 session 状态
python3 scripts/opencode_client.py --url http://<host>:<port> status <sessionID>
# 查看消息
python3 scripts/opencode_client.py --url http://<host>:<port> messages <sessionID>
# 发送消息
python3 scripts/opencode_client.py --url http://<host>:<port> send <sessionID> "prompt"
详见 references/api_reference.md
ZIP package — ready to use