Supercoder

Skills 和子代理工具包，自动注入到你的 OpenCode 会话中，构建完整的软件开发生命周期。

工作原理

插件在每个会话启动时自动注入角色提示：

• 主代理会话（agent 字段为空）→ 注入 .opencode/prompts/main-agent.md，包含人设、Skill 纪律、tool mapping、协调-only 规则、question 工具强制
• 子代理会话（agent 字段非空）→ 注入 .opencode/prompts/subagent.md，包含不联系用户、不派遣子代理、结构化状态上报等通用约束

两类提示文件不是 skill，不进入 skill 列表，由插件读取后直接注入上下文。每个 session 只注入一次。

当你开始构建某个功能时，agent 不会直接跳入写代码。它会：

1. 通过 头脑风暴 skill 澄清真实需求、识别糟糕前提
2. 需要技术选型时，派遣 @调研工程师 子代理系统化调研现成方案
3. 把讨论压缩成可执行的功能文档（docs/<类别>/<功能名>/README.md）
4. 按 TDD 实现，复杂工作通过 子代理协调 并行调度子代理执行
5. 完成后通过 @评审工程师 子代理做代码审查

快速安装

在你的项目根目录运行：

npx supercoder init

这条命令会自动完成所有配置：

1. 复制 agents 到 .opencode/agents/
2. 复制 skills 到 .opencode/skills/
3. 复制角色提示文件到 .opencode/prompts/
4. 复制脚本文件到 .opencode/scripts/
5. 复制插件到 .opencode/plugins/
6. 在 opencode.json 中写入子代理模型配置

重启 OpenCode，完成。

验证安装

开始新会话，说"帮我规划这个功能"或"让我们调试这个问题"。agent 应该自动调用相关 skills。

子代理

| 子代理 | 触发场景 | |--------|---------| | @爬虫工程师 | 读取已知 URL 的网页内容（JS 渲染页面、知乎、搜索结果页等） | | @调研工程师 | 技术选型、build-vs-buy、第三方库比较 | | @开发工程师 | 代码实现（TDD 模式） | | @验收工程师 | 功能合规审核 | | @质量工程师 | 代码质量审核 | | @评审工程师 | 生产就绪性验证 | | @项目讲解师 | 项目背景扫描 / 当前进展概览 |

@爬虫工程师 vs @调研工程师 的区别：

• URL 已知、需要读取页面内容 → @爬虫工程师（通过本地 Playwright 渲染，支持 JS 动态页面）
• 需要先发现候选方案、做技术选型 → @调研工程师（通过 Context7 / GitHub API / npm / PyPI）
• 两者互不替代，也不互相调用

注意： @爬虫工程师 需要本地预装 playwright npm 包（可选运行时依赖，不是 supercoder 内置依赖）：

npm install playwright

@爬虫工程师 还会读取项目根目录 .env 中的 SUPERCODER_BROWSER_PATH 来确定使用哪个本机浏览器。首次调用时若该变量缺失，脚本会自动检测默认浏览器并写入 .env（仅 Windows v1 支持自动检测；非 Windows 平台需手动在 .env 中设置 SUPERCODER_BROWSER_PATH，当前实现无 Playwright 管理浏览器的自动回退）。已存在的值不会被覆盖。

子代理公共规则（不联系用户、不派遣子代理、结构化状态上报）由插件自动注入 .opencode/prompts/subagent.md。

@调研工程师 通过内置工具完成生态调研，不依赖任何 MCP，默认来源分层：

• Context7 HTTP API（首轮发现 + serious candidates 文档检索主路径）：先 GET /api/v2/libs/search 首轮搜索，再 GET /api/v2/context 拉文档；Context7 无结果时退回 webfetch
• GitHub 公开 API（repo 元数据补充验证）：api.github.com/search/repositories、api.github.com/repos/...；无需 gh CLI
• npm / PyPI 官方 API（包元数据来源）：registry.npmjs.org、api.npmjs.org、pypi.org/pypi/<name>/json
• webfetch（最终兜底）：上述 API 无结果或内容不足时拉官方文档页
• Google / 知乎等搜索/社区站不进入默认工作流（反爬、登录墙、噪音高）
• 只对进入 shortlist 的候选项深查文档，控制上下文预算

Skills 列表

核心工作流

• 头脑风暴 — 需求澄清 → 功能文档 → 直达实现
• 子代理协调 — 主代理协调：依赖分析、并行批次调度、双阶段审核
• 测试驱动开发 — RED-GREEN-REFACTOR 循环
• 完成开发分支 — 合并/PR 决策工作流

调试

• 系统性调试 — 4 阶段根本原因分析
• 验收前验证 — 提交前验证

协作

• 请求代码审查 — 派遣 @评审工程师 子代理做代码审查
• 接收代码审查 — 处理外部审查反馈

元

• 项目状态概览 — 快速获取当前项目进展
• 编写Skill — 创建新 skills

功能文档

每次头脑风暴后，生成 docs/<类别>/<功能名>/README.md，包含：

• 设计结论、动机、设计决策
• 变更历史（日期/变更/原因）
• 坑 / 注意事项、待办

再次头脑风暴同一功能时，更新原有文档，不新建文件。

贡献

Skills 在 .opencode/skills/ 目录下。贡献方式：

1. Fork 仓库
2. 按功能创建分支
3. 遵循 编写Skill skill 来创建和测试新 skills
4. 提交 PR（详见 .github/PULL_REQUEST_TEMPLATE.md）

许可证

MIT — 详见 LICENSE 文件