opencode-acp-control

OpenCode ACP 技能

通过 Agent Client Protocol（ACP）直接控制 OpenCode。

元数据

• ACP 协议文档（适用于 Agent/大模型）：https://agentclientprotocol.com/llms.txt
• GitHub 仓库：https://github.com/bjesuiter/opencode-acp-skill
• 如果此技能遇到问题，请在此处提交 issue 工单：https://github.com/bjesuiter/opencode-acp-skill/issues

快速参考

操作	方法
启动 OpenCode	bash(command: "opencode acp --cwd /path/to/project", background: true)
发送消息	process.write(sessionId, data: "<json-rpc>\n")
读取响应	process.poll(sessionId) - 每 2 秒重复一次
停止 OpenCode	process.kill(sessionId)
列出会话	bash(command: "opencode session list", workdir: "...")
恢复会话	列出会话 → 询问用户 → session/load
检查版本	bash(command: "opencode --version")

启动 OpenCode

bash(
  command: "opencode acp --cwd /path/to/your/project",
  background: true,
  workdir: "/path/to/your/project"
)

保存返回的 sessionId——后续所有命令都会用到它。

协议基础

• 所有消息均采用 JSON-RPC 2.0 格式
• 消息以 换行符分隔（每条消息以 \n 结尾）
• 维护一个从 0 开始的 消息 ID 计数器

分步工作流

第 1 步：初始化连接

启动 OpenCode 后立即发送：

{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{"fs":{"readTextFile":true,"writeTextFile":true},"terminal":true},"clientInfo":{"name":"clawdbot","title":"Clawdbot","version":"1.0.0"}}}

轮询响应。预期会得到 result.protocolVersion: 1。

第 2 步：创建会话

{"jsonrpc":"2.0","id":1,"method":"session/new","params":{"cwd":"/path/to/project","mcpServers":[]}}

轮询响应。保存 result.sessionId（例如，"sess_abc123"）。

第 3 步：发送提示词

{"jsonrpc":"2.0","id":2,"method":"session/prompt","params":{"sessionId":"sess_abc123","prompt":[{"type":"text","text":"Your question here"}]}}

每 2 秒轮询一次。你会收到：

• session/update 通知（流式内容）
• 包含 result.stopReason 的最终响应

第 4 步：读取响应

每次轮询可能会返回多行。将每行解析为 JSON：

• 通知：method: "session/update"——收集这些内容作为响应
• 响应：包含与请求匹配的 id——出现 stopReason 后停止轮询

第 5 步：取消（如有需要）

{"jsonrpc":"2.0","method":"session/cancel","params":{"sessionId":"sess_abc123"}}

无需等待响应——这是一个通知。

需要跟踪的状态

对于每个 OpenCode 实例，跟踪：

• processSessionId——来自 bash 工具（clawdbot 的进程 ID）
• opencodeSessionId——来自 session/new 响应（OpenCode 的会话 ID）
• messageId——每发送一个请求就递增一次

轮询策略

• 每 2 秒 轮询一次
• 持续轮询，直到收到包含 stopReason 的响应
• 最长等待时间：5 分钟（150 次轮询）
• 如果没有响应，则视为操作超时

常见停止原因

stopReason	含义
end_turn	Agent 已完成响应
cancelled	你取消了提示词
max_tokens	已达到 Token 限制

错误处理

问题	解决方案
轮询响应为空	继续轮询——Agent 正在思考
解析错误	跳过格式错误的行并继续
进程已退出	重启 OpenCode
5 分钟后仍无响应	终止进程，然后重新启动

示例：完整交互

1. bash(command: "opencode acp --cwd /home/user/myproject", background: true, workdir: "/home/user/myproject")
   -> processSessionId: "bg_42"

2. process.write(sessionId: "bg_42", data: '{"jsonrpc":"2.0","id":0,"method":"initialize",...}\n')
   process.poll(sessionId: "bg_42") -> initialize response

3. process.write(sessionId: "bg_42", data: '{"jsonrpc":"2.0","id":1,"method":"session/new","params":{"cwd":"/home/user/myproject","mcpServers":[]}}\n')
   process.poll(sessionId: "bg_42") -> opencodeSessionId: "sess_xyz789"

4. process.write(sessionId: "bg_42", data: '{"jsonrpc":"2.0","id":2,"method":"session/prompt","params":{"sessionId":"sess_xyz789","prompt":[{"type":"text","text":"List all TypeScript files"}]}}\n')
   
5. process.poll(sessionId: "bg_42") every 2 sec until stopReason
   -> Collect all session/update content
   -> Final response: stopReason: "end_turn"

6. When done: process.kill(sessionId: "bg_42")

---

恢复会话

让用户从可用会话中选择，以恢复之前的 OpenCode 会话。

第 1 步：列出可用会话

bash(command: "opencode session list", workdir: "/path/to/project")

示例输出：

ID                                  Updated              Messages
ses_451cd8ae0ffegNQsh59nuM3VVy      2026-01-11 15:30     12
ses_451a89e63ffea2TQIpnDGtJBkS      2026-01-10 09:15     5
ses_4518e90d0ffeJIpOFI3t3Jd23Q      2026-01-09 14:22     8

第 2 步：询问用户选择

向用户展示列表，并询问要恢复哪个会话：

"Which session would you like to resume?
 
1. ses_451cd8ae... (12 messages, updated 2026-01-11)
2. ses_451a89e6... (5 messages, updated 2026-01-10)
3. ses_4518e90d... (8 messages, updated 2026-01-09)

Enter session number or ID:"

第 3 步：加载所选会话

用户回复后（例如，“1”、“第一个”或“ses_451cd8ae...”）：

1. 启动 OpenCode ACP：

   bash(command: "opencode acp --cwd /path/to/project", background: true, workdir: "/path/to/project")
   

2. 初始化：

   {"jsonrpc":"2.0","id":0,"method":"initialize","params":{...}}
   

3. 加载会话：

   {"jsonrpc":"2.0","id":1,"method":"session/load","params":{"sessionId":"ses_451cd8ae0ffegNQsh59nuM3VVy","cwd":"/path/to/project","mcpServers":[]}}
   

注意：session/load 需要 cwd 和 mcpServers 参数。

加载时，OpenCode 会将完整对话历史流式传回。

恢复工作流摘要

function resumeSession(workdir):
    # List available sessions
    output = bash("opencode session list", workdir: workdir)
    sessions = parseSessionList(output)
    
    if sessions.empty:
        notify("No previous sessions found. Starting fresh.")
        return createNewSession(workdir)
    
    # Ask user to choose
    choice = askUser("Which session to resume?", sessions)
    selectedId = matchUserChoice(choice, sessions)
    
    # Start OpenCode and load session
    process = bash("opencode acp --cwd " + workdir, background: true, workdir: workdir)
    initialize(process)
    
    session_load(process, selectedId, workdir, mcpServers: [])
    
    notify("Session resumed. Conversation history loaded.")
    return process

重要说明

• 重放历史记录：加载时，所有先前消息都会流式传回
• 保留记忆：Agent 会记住完整对话
• 独立于进程：即使 OpenCode 重启，会话也会保留

---

更新 OpenCode

OpenCode 会在重启时自动更新。使用此工作流检查并触发更新。

步骤 1：检查当前版本

bash(command: "opencode --version")

返回类似：opencode version 1.1.13

提取版本号（例如 1.1.13）。

步骤 2：检查最新版本

webfetch(url: "https://github.com/anomalyco/opencode/releases/latest", format: "text")

重定向 URL 包含最新版本标签：

• 重定向至：https://github.com/anomalyco/opencode/releases/tag/v1.2.0
• 从 URL 路径中提取版本号（例如 1.2.0）

步骤 3：比较并更新

如果最新版本 > 当前版本：

1. 停止所有正在运行的 OpenCode 进程：

   process.list()  # Find all "opencode acp" processes
   process.kill(sessionId) # For each running instance
   

2. 重启实例（OpenCode 启动时会自动下载新二进制文件）：

   bash(command: "opencode acp --cwd /path/to/project", background: true, workdir: "/path/to/project")
   

3. 重新初始化每个实例（初始化 + 对现有会话执行 session/load）

步骤 4：验证更新

bash(command: "opencode --version")

如果版本仍与最新版本不一致：

• 告知用户：“OpenCode 自动更新可能失败。当前版本：X.X.X，最新版本：Y.Y.Y”
• 建议手动更新：curl -fsSL https://opencode.dev/install | bash

更新工作流摘要

function updateOpenCode():
    current = bash("opencode --version")  # e.g., "1.1.13"
    
    latestPage = webfetch("https://github.com/anomalyco/opencode/releases/latest")
    latest = extractVersionFromRedirectUrl(latestPage)  # e.g., "1.2.0"
    
    if semverCompare(latest, current) > 0:
        # Stop all instances
        for process in process.list():
            if process.command.includes("opencode"):
                process.kill(process.sessionId)
        
        # Wait briefly for processes to terminate
        sleep(2 seconds)
        
        # Restart triggers auto-update
        bash("opencode acp", background: true)
        
        # Verify
        newVersion = bash("opencode --version")
        if newVersion != latest:
            notify("Auto-update may have failed. Manual update recommended.")
    else:
        notify("OpenCode is up to date: " + current)

重要说明

• 会话会保留：opencodeSessionId 在重启后仍有效 — 使用 session/load 恢复会话
• 自动更新：OpenCode 重启时会自动下载新二进制文件
• 不会丢失数据：对话历史会在服务端保留