简体中文 | English

基于 opencode 的自动驾驶 agent 集群 —— 遵循 TDD 纪律的自主开发工具包。

OpenCode 很强大，但开箱即用只是单轮助手 —— 你提问、它回答，上下文随之消失。把一个功能从想法变成合入代码，需要几十轮手动交互和持续的盯盘。

opencode-toolbox 填补了这个空白：结构化的自动驾驶工作流，从 .scratch/ 目录中取出一个充分定义好的 issue，派遣 TDD 驱动的 implementer agent，经过 reviewer 审查，循环直到代码可以合入 —— 全程自主运行，每步都有清晰可审计的报告。

基于 mattpocock/skills 构建，并根据日常深度使用中的个人习惯做了补充扩展。

• 已安装 OpenCode CLI
• Bun（OpenCode 内部使用 Bun 安装和运行插件，必须安装）
• 熟悉 .scratch/ issue 目录结构（详见 AGENTS.md）

git clone https://github.com/MatthewYe/opencode-toolbox.git
cd opencode-toolbox && bun install && bun run build

然后在你项目的 opencode.json 或 opencode.jsonc 中添加本地路径（项目根目录为项目级配置，~/.config/opencode/opencode.json 为全局配置）：

{ "plugin": ["/path/to/opencode-toolbox"] }

插件自动注册 skills、agents 和 /autopilot 命令。

启动 OpenCode，确认以下两个信号：

1. 输入 /aut 能看到 /autopilot 命令补全
2. 问 "列出当前可用的 skills"，应出现 tdd、diagnose、triage 等

首先初始化工程技能的上下文：

# 0. 初始化 —— 配置 issue tracker、triage 标签等，所有工程技能的运行前提
/setup-matt-pocock-skills

完整流水线 —— 从想法到 ready-for-agent：

# 1. 拷问 —— 对照领域文档和决策记录，压力测试你的想法
/grill-with-docs "Add user authentication with OAuth"

# 2. 规格化 —— 将结论固化为 PRD
/to-prd

# 3. 切片 —— 将 PRD 拆分为可独立领取的 issues
/to-issues

# 4. 分流 —— 将每个 issue 走完状态机，推进到 ready-for-agent
/triage

当 issue 状态为 ready-for-agent 后：

# 5. 自动驾驶 —— implementer → reviewer，自主 TDD 循环
/autopilot                          # 处理第一个就绪 issue
/autopilot .scratch/feat/issues/01-add-login  # 处理指定 issue

flowchart LR
    I[".scratch/ issue<br/>(Status: ready-for-agent)"] --> IM["implementer<br/>读取 AGENT-BRIEF<br/>TDD red-green-refactor"]
    IM --> SR["self-review / 自审查"]
    SR --> RV["reviewer<br/>四维审查（只读）"]
    RV -->|"VERDICT: MERGE"| DONE(["代码就绪"])
    RV -->|"VERDICT: RETRY"| IM
    RV -->|"VERDICT: BLOCKED"| HUMAN(["needs-info → 人工介入"])

报告可被机器解析 —— 编排器读取 IMPLEMENTER_REPORT: 和 REVIEWER_REPORT: 块来决定下一步。

最多 3 轮（初始 + 2 次重试）。若第 3 轮仍 RETRY，issue 进入 needs-info 等待人工处理。

关于 issue 结构、TDD 纪律规则和 agent 行为的完整细节，详见 AGENTS.md。

工具箱默认注册三个 agent：

argus 默认使用 Kimi 多模态模型。如果你的 provider 配置中 Kimi 名称不同，在 opencode.json/opencode.jsonc 中覆盖：

{
  "agent": {
    "argus": {
      "model": "my-kimi-provider/my-kimi-model"
    }
  }
}

无需图像分析 agent 时，也可以直接禁用：

{ "agent": { "argus": { "disabled": true } } }

当前状态：稳定 —— 每日个人工作流中使用，autopilot 循环功能完备。

已知局限：

• 插件自身无 CI/测试套件（tsconfig.json 仅用于编辑器支持，无 lint/typecheck 命令）
• Reviewer 只读，不能自动修复发现的问题
• 仅支持 .scratch/ 目录约定的 issue 存储方式

下一步：

• 扩展 issue 来源（直接对接 GitHub Issues）
• 并行 issue 处理（同时派遣多个 implementer）

环境搭建、PR 规范和 upstream 同步策略详见 CONTRIBUTING.md。

简述：

• bun install && bun run build 启动开发
• 不要修改 upstream/ 中的文件 —— 它们是 mattpocock/skills 的压缩子树，下次同步会覆盖
• 本地技能放 skills/，本地 agent 放 agents/，本地命令放 commands/

• mattpocock/skills —— 构成本工具箱基础的工程与生产力技能。由衷感谢 Matt 开创了 skill-as-agent-instruction 这一模式。
• opencode —— 让自主 agent 工作流成为可能的 CLI 工具。

MIT —— 详见 LICENSE。