opencode-acp-control

核心用法

OpenCode ACP Skill 是一套纯文档型的协议控制指南，旨在通过 Agent Client Protocol (ACP) 实现对 OpenCode 的完整程序化控制。该 Skill 不提供可执行代码，而是详细规定了通过 JSON-RPC 2.0 协议与 OpenCode CLI 通信的标准流程。

使用时，首先需要通过 bash 工具在后台启动 OpenCode ACP 服务（opencode acp --cwd /path），获取进程会话 ID。随后通过 process.write 发送 JSON-RPC 消息进行初始化（initialize）、创建新会话（session/new）或加载已有会话（session/load）。发送提示（session/prompt）后，需以 2 秒为间隔轮询（process.poll）接收流式响应，直至收到包含 stopReason 的最终响应。整个交互过程严格遵循请求-响应模式，支持会话的持久化存储与恢复。

显著优点

协议标准化：采用通用的 JSON-RPC 2.0 格式，消息结构清晰，便于与各类编程语言和工具集成。会话管理能力：支持完整的会话生命周期管理，包括创建、恢复、取消操作，且会话数据在 OpenCode 服务端持久保存，进程重启后可通过 session/load 恢复历史对话。自动化友好：详细的轮询策略（2秒间隔、5分钟超时）和错误处理指南（空响应、解析错误、进程退出），为构建可靠的自动化工作流提供了坚实基础。版本管理：内置 OpenCode 自动更新检查机制，通过比对当前版本与 GitHub Releases 最新版本，可触发自动更新流程。

潜在缺点与局限性

外部依赖严格：该 Skill 本质上是"使用说明书"，完全依赖用户预装 OpenCode CLI 工具，若环境未安装 opencode 命令则无法使用。交互模式繁琐：采用轮询（polling）机制而非回调或 WebSocket，需要手动管理消息 ID 计数器、维护轮询循环，增加了集成复杂度。纯文档限制：作为无代码执行的文档型 Skill，它不能自动处理协议细节，所有 JSON 消息构造、会话状态跟踪、错误重试逻辑都需要调用方自行实现。来源可信度：作者为个人开发者（T3 来源），虽代码透明但缺乏组织级维护保障。

适合的目标群体

主要面向需要将 OpenCode 集成到自有工作流中的开发者和DevOps 工程师，特别是构建 CLI 工具、IDE 插件或自动化脚本的场景。适合熟悉进程管理、理解 JSON-RPC 协议、具备一定错误处理能力的开发人员。对于希望实现"用 AI 控制 AI"（即通过 LLM Agent 控制 OpenCode Agent）的高级用户，该 Skill 提供了必要的协议规范。不推荐无开发背景的普通终端用户直接使用。

使用风险

进程管理风险：需要手动管理后台进程（启动、轮询、杀死），若未正确处理 process.kill 可能导致僵尸进程残留。超时与挂起：文档建议最大等待 5 分钟（150 次轮询），但在复杂代码生成任务中可能超出此时限，导致误判为超时。版本兼容性：依赖特定版本的 OpenCode CLI，若 ACP 协议版本变更可能导致通信失败。路径注入：虽然示例中的 bash 命令参数固定，但在实际集成时若直接将用户输入拼接到 cwd 参数，可能存在路径遍历风险，需确保路径校验。网络依赖：检查更新功能依赖 webfetch 访问 GitHub，在网络受限环境可能失败。