OpenCode ACP 技能

通过代理客户端协议（ACP）直接控制 OpenCode。

元数据

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

快速参考

启动 OpenCode

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

保存返回的会话ID- 后续所有命令都需要它。

协议基础

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

逐步工作流程

步骤 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"- 收集这些内容作为响应
• 响应：包含标识符匹配您的请求 - 当停止原因出现时停止轮询

步骤5：取消（如果需要）

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

无需响应 - 这是一个通知。

状态跟踪

对于每个OpenCode实例，跟踪：

• 进程会话ID- 来自bash工具（clawdbot的进程ID）
• opencode会话ID- 来自会话/新建响应（OpenCode的会话ID）
• 消息ID- 对您发送的每个请求递增

轮询策略

• 每2秒
• 轮询一次持续轮询，直到收到包含
• 停止原因的响应最长等待时间：
• 5分钟

常见停止原因

错误处理

示例：完整交互

1. bash(command: "opencode acp", 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会话。

第一步：列出可用会话

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

第二步：请用户选择

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

"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:"

第三步：加载选定会话

一旦用户响应（例如，“1”、“第一个”或“ses_451cd8ae...”）：

1. 启动 OpenCode ACP：

   bash(command: "opencode acp", 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", background: true, workdir: workdir)
    initialize(process)
    
    session_load(process, selectedId, workdir, mcpServers: [])
    
    notify("Session resumed. Conversation history loaded.")
    return process

重要注意事项

• 历史记录回放加载时，所有之前的消息会流式回传
• 记忆保留：代理记得完整的对话
• 进程独立：会话在OpenCode重启后依然存在

更新OpenCode

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

步骤1：检查当前版本

bash(command: "opencode --version")

返回类似以下内容：opencode 版本 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", 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在重启时会自动下载新的二进制文件
• 无数据丢失：对话历史记录在服务器端得以保留