第六章：技能体系与插件生态

技能是 OpenCode 框架中可复用的能力模块。Agent 是角色（”谁来做”），技能是工具箱（”怎么做”）。本章完整覆盖本配置中全部 18 个自定义技能和 2 个插件生态，逐一详解每个技能的作用、触发条件、核心工作流和关键设计点。

6.1 技能体系概述

6.1.1 技能是什么

在 OpenCode 中，技能是一种按需加载的能力模块。每个技能是一个独立的 SKILL.md 文件，包含该技能的完整工作流指令、检查清单和约束规则。技能通过原生 skill 工具触发加载——Agent 只在需要时才将技能内容注入上下文，平时不占用任何 token 预算。

这种设计与传统 AI 编码助手中”把所有能力塞进 system prompt”的做法截然不同：技能是上下文惰性加载的，一个典型的编码会话可能只加载 2-3 个技能，而不是让所有 32 个技能的全部指令始终占据上下文窗口。

6.1.2 技能目录结构

skills/
├── <skill-name>/
│   └── SKILL.md

每个技能一个目录，目录名与技能名一致（kebab-case）。文件必须命名为 SKILL.md（大写）。技能的 YAML frontmatter 中必须包含 name（与目录名匹配）和 description（需前置关键词以提升触发准确度）。

多个来源的技能会自动发现和合并：

• {skill,skills}/**/SKILL.md — 配置目录下的本地技能（本项目中的 18 个自定义技能）
• .agents/skills/**/SKILL.md — 项目级或全局级技能
• superpowers 插件路径 — 插件提供的 14 个过程型技能

同名技能的覆盖规则：最后注册的生效，这意味着本地技能可以覆盖内置技能。

6.1.3 加载机制

Orchestrator 在每次收到用户请求后，根据请求内容在可用的技能列表中做语义匹配。匹配成功的技能通过 skill 工具加载，其完整指令被注入到当前 Agent 的上下文中。

技能的 description 字段是匹配的核心依据——它必须同时描述做什么和何时触发，并前置触发关键词。例如 "Token-frugal, multi-dimension code review for a diff/branch/PR. Use when reviewing changes..." 这种格式，让模型在”审查代码”时能精准命中。

6.1.4 技能与 Agent 的关系

• Agent 是角色：每个 Agent 有自己的系统提示词（system prompt），定义其职责边界和决策风格。例如 oracle 是只读分析角色，deep-worker 是重度实现角色。
• 技能是可复用能力模块：技能独立于具体 Agent，可以被任何 Agent 加载使用。同一个 code-review 技能可以被 reviewer Agent 加载做正式审查，也可以被 deep-worker Agent 在 /review-loop 中加载做自我检查。
• 权限过滤：Agent 的工具权限会影响技能的可见性。如果一个 Agent 的策略拒绝了某个工具，它就无法看到依赖该工具的技能。这是通过权限配置隐式控制”廉价 flash agent 不要触发昂贵技能”的机制。

6.1.5 18 个技能的分类

本配置中的 18 个自定义技能按其核心用途分为五大类：

6.2 技能逐一详解

6.2.1 code-review —— 代码审查

作用：Token 高效的多维度代码审查，按有效逻辑行数缩放审查深度，覆盖 7 个审查维度，支持审查→修复循环。

触发条件：审查变更、检查 PR、审查→修复循环，或用户提到 “code review”、”review my changes”、”review this PR”、”找 bug”、”审查代码”。

核心工作流：

1. Step 0 — 按有效规模确定范围（不是原始行数）：先用 git diff --stat 确立变更集，然后对文件按类别加权——生成文件/机械变更权重 0×，数据/配置文件 0.25×，测试文件 0.5×，逻辑代码 1×。有四种路径：
   • ≤8 个逻辑文件且 ≤300 有效行 → 简化审查（默认），单次聚焦审视
   • 超过阈值 → 完整审查，逐维度审视，结果写入文件
   • 高风险覆盖（认证/授权、数据库迁移/模式、并发/锁、公共 API）→ 强制完整审查
2. 熵扫描（维度审查前）：快速 30 秒扫描重复代码块（6+ 行）、模式偏差、命名不一致、死导入
3. 7 个审查维度：正确性 → 安全性 → 性能 → 架构 → 可维护性 → 文档与注释 → 兼容性
4. 严重度校准：critical / major / minor / nit，根据项目上下文（版本阶段、部署模型、仓库可见性）校准，防止严重度通胀
5. 自怀疑检查：每条发现发布前必须通过三道反问——”我能反驳这个发现吗？”“严重度是否被夸大？”“这是真实问题还是个人偏好？”

关键设计点：

• token 节俭：大审查结果写入文件（.opencode/review-<ref>.md），聊天中只返回摘要行和文件路径
• 审查→修复循环（/review-loop）：审查 → 最小化修复 → 验证 → 再审查，最多 5 轮迭代。每轮追踪发现的类型（NEW / RECURRING / REGRESSION），基于新颖度收敛而非无限循环
• PR 发布：gh pr review 发布顶层评审意见，行级评论通过 REST API 的 comments[] 数组附加。每个发现携带稳定的哈希 ID（<!-- cr:xxx -->），支持后续修补时去重

6.2.2 spec-workflow —— 规约驱动变更

作用：轻量级规约驱动的变更工作流。通过持久的、git 可追踪的产物（proposal → specs → design → tasks → archive）管理从 Why/What 到完成归档的完整链路。

触发条件：非平凡的特性或行为变更（适合跨文件/跨会话的变更），或用户提到 “spec”、”proposal”、”propose a change”、”spec-driven”、”openspec”、”design doc”、”requirements”、”tasks checklist”。不适用于单行修复或纯问答。

核心工作流（6 个动作，按需使用而非锁定的阶段）：

1. explore（可选）：预提案的思考探索，不创建 changes/<change-id>/ 目录。方向模糊时先做探索，避免过早锁定方案
2. propose：创建提案目录结构——proposal.md（Why + What，1-2 页） + tasks.md（checkbox 清单） + 增量规格文件（delta specs）+ 必要时 design.md
3. apply：按 tasks.md 逐条实现，勾选复选框，遇阻则更新产物而非静默偏离
4. update：在提案已建立但未归档时修改已有提案。范围增长 <30% 在原地更新，≥30% 创建新提案
5. verify（归档前）：三重检查——所有任务已完成 ✓、每条 ADDED/MODIFIED 需求有对应实现、提案声明与实际一致
6. archive：合并 delta specs 到真相源 → 移动变更到 archive → 验证一致性 → 提交

关键设计点：

• 产物是真相源：计划以 markdown 文件存在于仓库中而非聊天历史，跨会话持久化且可 grep
• 推动器而非门控：产物依赖关系（proposal → specs → design → tasks）展示可做下一步而非必须做的事——中途发现设计错了，更新 design.md 继续前进
• 增量规格：使用 ADDED / MODIFIED / REMOVED / RENAMED 操作描述变更，归档时按操作类型合并到真相源
• 场景格式严格：Scenario 必须用精确 4 个 # 标题（#### Scenario:），3 个 # 或纯 bullet 形式会被静默忽略

6.2.3 deepwork —— 审查门控执行

作用：为涉及 3+ 文件的复杂任务提供审查门控的分阶段执行规范。创建持久化产出物（plan、verify、report），支持跨会话追踪。

触发条件：3+ 文件非平凡变更、涉及大规模重构、跨切面关注点（认证、数据库模式、共享类型），或用户提到 “deep work”、”complex refactor”、”multi-phase”、”staged rollout”。不适用于单文件编辑、拼写修复、配置调整。

核心工作流（3 阶段）：

1. Phase 1: Plan（.opencode/deepwork/<task>.plan.md）：先读后写。输出 Goal（一句话）、Scope（触碰和不触碰的文件）、Approach（逐步可勾选的清单）、Risks（可能破坏什么）、Verification（验证命令）。计划需经 Orchestrator 审查批准后才可进入实现
2. Phase 2: Implement（审查门控）：按计划逐步实现，每步打勾。每个文件修改后：端到端重读 → 检查调用者 → 运行可用的测试/格式化器/linter。中途发现计划错误则暂停更新计划并重新呈现，严禁静默偏离
3. Phase 3: Verify + Report：执行计划中所有验证命令 → 检查每个修改过的函数至少有一个调用者 → 检查遗留 TODO/调试打印/死代码 → 输出 .opencode/deepwork/<task>.done.md

关键设计点：

• 门控是不可跳过的：计划必须被审查和批准才能落地代码——这是防止失控的硬约束
• 计划简洁：~50 行上限，是检查清单而非设计文档
• 报告格式标准化：## Done: <task> + 完成日期 + 文件数 + 验证结果 + 备注

6.2.4 diagnose —— 结构化调试

作用：6 阶段结构化调试循环，核心理念是”紧反馈环比阅读代码更快找到根因”。作为 superpowers 的 systematic-debugging 的补充，提供更紧密的执行循环。

触发条件：遇到难以修复的 bug、性能问题，或用户提到 “diagnose”、”debug”、”trace”、”find root cause”、”排查”、”诊断”。

核心工作流（6 阶段）：

1. Phase 1: 构建反馈环：必须存在 pass/fail 信号才能开始。选项（从快→慢）：失败测试→curl/HTTP 脚本→CLI 调用→无头浏览器脚本→git bisect。硬规则：在反馈环存在之前形成理论 = 猜测
2. Phase 2: 复现 + 最小化：确认反馈环复现了确切症状。逐一裁剪输入/调用者/配置/数据/步骤，每次裁剪后重新运行。停止条件：每个剩余元素都承担因果负载
3. Phase 3: 假设：生成 3-5 个排序的可证伪假设。格式：”如果 是原因，那么 <改 Y=""> 会让 bug 消失 / <改 Z=""> 会让它更严重"。展示给用户前排序——领域知识可能立即重新排序
4. Phase 4: 打点：每次只改变一个变量。优先级：调试器 > 定向日志 > 禁止”全部日志+grep”。所有调试日志加唯一前缀 [DEBUG-xxxx]——清理阶段一条 grep 搞定
5. Phase 5: 修复 + 回归测试：先写回归测试再修（前提是有适当的接缝）。如无接缝则记录缺口
6. Phase 6: 清理 + 复盘：删除所有 [DEBUG-...] 打点、验证原始问题不再复现、正确的假设记录在提交信息中、追问”什么可以防止这个问题？”

6.2.5 security-review —— 安全审查

作用：合并前安全审查，提供 12 项威胁清单和信任边界追踪方法论，按具体利用路径评估严重度。

触发条件：审查 diff/PR、加固代码，或用户提到 “security”、”injection”、”XSS”、”SSRF”、”secrets”、”auth”、”deserialization”、”path traversal”、”is this safe?”。

核心工作流：

1. 12 项威胁清单：注入 → XSS → 认证/授权 → 密钥 → 路径穿越/文件访问 → SSRF → 反序列化/解析 → 加密（弱算法、硬编码 IV、ECB 模式、缺失 TLS 验证、可预测随机数）→ 敏感数据暴露 → 依赖（新包信誉、已知 CVE、typosquat）→ 资源与 DoS → 竞态条件/TOCTOU
2. 信任边界追踪：识别不可信输入的入口点 → 追踪每个被污染的值从源到汇 → 评估是否到达危险汇（DB/Shell/文件系统/网络/HTML）而未经验证/编码/参数化
3. 报告格式：[severity: high|medium|low] <title> + location + issue + impact + fix

关键设计点：

• 只审查 diff（变更行及其直接调用的代码），必要时才拓宽范围
• 只标记能证明具体利用路径的发现，不做推测性噪音
• 无发现有价值的发现时，明确声明而非强行填充

6.2.6 remove-deadcode —— 死代码清理

作用：安全查找并删除可证明不可达的代码——未使用的文件、导出、函数、变量和导入。每次删除前通过 LSP 验证，防止误删。

触发条件：用户提到 “dead code”、”unused code”、”remove slop”、”clean up”、”prune”、”delete unused”、”orphaned files”，或重构后留下残留代码。

核心工作流（4 阶段）：

1. Phase 1: 扫描（并行）：并发运行编译器/检查器未使用标志 + 孤立文件检测 + 未使用导出检测 + LSP 引用检查。大型代码库委托给 explore 子代理并行搜索
2. Phase 2: 逐个验证（删除前）：每个候选对象必须通过反证测试——如果满足以下任意一条则保留：被 barrel/index 重导出、被测试/夹具/快照引用、是框架/工具入口点（路由处理器、CLI 命令、迁移、插件钩子、main、序列化器）、通过反射/动态导入/字符串键/DI 容器到达、是发布的公共 API 表面
3. Phase 3: 分批删除：按文件分组——同一文件的删除放在同一批次。同时删除符号本身和其现在无用的导入。精确暂存：git add <specific files> 禁止 git add -A
4. Phase 4: 证明安全：构建/类型检查 → 运行测试套件 → 重新运行未使用符号检测器（计数应下降而非上升）。构建或测试失败则回滚该批次

关键设计点：

• 证明它是死的再删——这是铁律。”看起来无用”的符号常常通过 barrel 导出、测试、反射或框架入口点被引用
• 每次编辑前重新运行 LSP “查找所有引用”——依赖图可能因之前删除而改变
• 反模式：批量删除整个目录（”看起来没用”）、删除测试引用的代码后也删除测试（掩盖回归）

6.2.7 simplify —— 代码简化

作用：行为保持的代码简化——在不改变代码行为的前提下减少复杂度、提高可读性。每次一个改动，每次改动后测试验证。

触发条件：用户提到 “simplify”、”refactor”、”clean up”、”reduce complexity”、”too clever”、”hard to read”，或特性落地后代码需要打磨。分配给 oracle agent 做编辑前深度分析。

核心工作流：

1. 减少嵌套：early return 替代 if (x) { ...整个函数... }、guard clause 前置、只在提取能澄清意图时才提取深层嵌套为函数
2. 移除不必要抽象：内联单调用者函数、删除单实现接口、去除薄包装、消除过度泛化的工具函数
3. 减少变量数量：内联单次使用变量、消除冗余”解释性”临时变量
4. 简化条件：三元替代 if/else 赋值、去除冗余 else、布尔表达式替代 if/else 返回布尔值
5. 减少表面积：不导出模块外部未使用的符号、删除未使用的参数

安全协议：简化前运行全部测试 → 一次只做一个简化 → 每个简化后运行测试 → 失败立即回滚 → 用 LSP “查找所有引用”确认真才做

关键设计点：

• 行为完全不变——这是硬约束。不趁便做”while I’m here”改进、不改变 API 表面
• 不简化的代码：性能关键代码（有意为之的”聪明”）、框架样板（路由定义、DI 注册）、错误处理路径、公共 API 签名、故意详尽的测试代码
• 报告格式标准化：## Simplified: <file>:<section> → Before/After → Tests 结果

6.2.8 gh-cli —— GitHub CLI 操作

作用：为 Agent 提供 GitHub CLI（gh v2.96.0+）的权威调用模式参考。覆盖结构化输出、分页、仓库定位、搜索 vs 列表、Issue 类型/子问题、Discussions、Projects V2、Rulesets、Agent Skills、AI 命令（Copilot、agent-task）、仓库文件读取、API 回退等全部功能。

触发条件：任何涉及 GitHub 的操作——PR、Issue、Release、Gist、Actions、fork、克隆、审查。

核心内容：

• 交互策略：非 TTY 自动跳过分页器、去除 ANSI 颜色、快速报错。关键环境变量：GH_PROMPT_DISABLED=1、GH_PAGER=cat、GH_NO_UPDATE_NOTIFIER=1
• JSON 解析：--json field1,field2,... 结构化输出、--jq 内联过滤、--template Go 模板（支持 tablerow、timeago、truncate 等辅助函数）
• 分页：-L N 限制列表结果，gh api --paginate 自动翻页，--slurp 合并多页为单个数组
• Issue 2.0（v2.94.0+）：类型系统——--type Bug|Feature|Task、父子关系——--parent、阻塞关系——--blocked-by / --blocking、关闭为重复——--duplicate-of
• Discussions（v2.94.0 预览）：列表/查看/创建/编辑/评论的完整命令组
• Projects V2：19 个子命令，覆盖项目 CRUD + 条目管理 + 自定义字段 + 视图
• Agent Skills（v2.94.0+）：gh skill 命令组——搜索、预览、安装、更新、发布
• AI 集成：gh copilot（内置 Copilot）、gh agent-task（委托编码任务给 GitHub 编码 Agent）
• 仓库文件读取（v2.95.0 预览）：gh repo read-file / gh repo read-dir——无需克隆即可读取仓库内容
• 发布验证（v2.75.0+）：gh release verify——Sigstore 供应链验证

关键设计点：

• 搜索 qualifier 是各自的裸 token——gh search issues repo:cli/cli is:open 工作，但 gh search issues "repo:cli/cli is:open" 失败
• gh pr review 只有顶层意见，无线内评论标志——这是一个常见 Agent 错误。行级评论必须通过 REST API 的 comments[] 数组
• 非交互运行必须显式标志：gh pr merge 需 --squash/--merge，gh release create 需 --notes/--generate-notes

6.2.9 gh-skill —— Agent 技能管理

作用：通过 gh skill 命令搜索、预览、安装、更新和发布 Agent 技能，让 Agent 自我管理其可用的技能生态。

触发条件：使用 gh skill 命令操作技能时。

核心工作流：

1. 搜索：gh skill search <query> 全文搜索，支持 --owner 限制、--json 结构化输出
2. 预览（安装前）：gh skill preview <owner>/<repo> <skill-name> 查看 SKILL.md 内容
3. 安装：gh skill install <owner>/<repo> <skill-name> --agent opencode --pin <ref> 精确安装。关键标志：--agent 指定目标宿主、--scope project|user 控制作用域、--pin 锁定版本
4. 更新：gh skill update --all 刷新全部已安装技能，--unpin 取消锁定跟进最新版
5. 发布：gh skill publish --tag v1.0.0 将仓库发布为可发现的技能源。发布流程：添加 agent-skills topic → 打标签 → 创建 GitHub Release
6. 删除：gh skill uninstall <owner>/<repo> 卸载技能

关键设计点：

• gh skill install --agent opencode 将技能安装到 ~/.config/opencode/skills/<name>/SKILL.md
• 发布前用 gh skill publish --dry-run 验证，用 --fix 自动清除安装注入的元数据
• gh CLI 官方发布了自身的 agent skill：gh skill install cli/cli gh --agent opencode——这个与本地 gh-cli 技能二选一，不要同时安装

6.2.10 git-master —— 高级 Git 操作

作用：覆盖基本 add/commit/push 之外的高级 Git 模式——原子提交、rebase、squash、fixup、blame、bisect、reflog、代码考古（git log -S/-G）以及 worktree 管理。

触发条件：需要 rebase、squash、bisect、blame、reflog、fixup、查找已删除代码、追踪提交历史、清理分支或恢复丢失的工作。

核心内容：

• 原子提交：一个逻辑变更一个提交。git add -p 交互式暂存，git diff --cached 审查准提交内容
• 历史重写：git rebase -i 交互式变基、git commit --fixup <sha> + --autosquash 自动修复、git commit --amend 修改未推送的最后提交
• 代码考古：git blame path/file -L 40,60 行级溯源、git log -S "string" 字符串出现/消失追踪（pickaxe）、git log -G "regex" 正则匹配追踪、git log --all --full-history -- "**/deleted-file.ts" 查找删除文件的提交
• 恢复丢失工作：git reflog 捕获所有 HEAD 移动（变基、重置、检出、甚至删除的分支——保留 30 天），git branch recovered HEAD@{5} 恢复”丢失”的提交为新分支
• 二分查找：git bisect start → git bisect bad HEAD → git bisect good v1.2.0 → 逐次标记 → 自动化：git bisect run npm test
• Worktree：git worktree add ../feature-x feature-branch 并行分支工作，无需 stash 或再次 clone

关键设计点：

• 安全原则：永远不强制推送到共享分支（--force-with-lease 是更安全但仍有风险的替代）、修改前检查作者身份、破坏性操作前先 git status + git log --oneline -5 确认位置
• reflog 是终极安全网——几乎所有操作失误都可以通过 reflog + checkout 恢复

6.2.11 git-release —— 发布管理

作用：将一组已合并的变更转化为一个干净、标签化的发布——收集变更内容、选择正确的版本号、生成可直接复制粘贴的 git tag 和 gh release create 命令。

触发条件：准备发布、起草 changelog、版本号升级，或用户提到 “release”、”changelog”、”version bump”、”tag”、”publish a new version”。

核心工作流（5 步）：

1. 建立基线：git fetch --tags --force → git describe --tags --abbrev=0 最近标签 → git log <last-tag>..HEAD --oneline 标签间提交
2. 决定版本（SemVer）：检查 Conventional Commits 类型——BREAKING CHANGE → major、有 feat → minor、仅 fix/perf/refactor/docs → patch
3. 起草发布说明：按类型分组（Features / Fixes / Docs），链接 PR/Issue。gh release create v1.4.0 --generate-notes --draft 让 GitHub 生成初稿
4. 打标签并发布：git tag -a v1.4.0 -m "v1.4.0" → git push origin v1.4.0 → gh release create v1.4.0 --generate-notes
5. 验证：gh release view v1.4.0 → gh release list --limit 5

关键设计点：

• 预发布（alpha/beta/rc）使用 --prerelease 和 SemVer 预发布标签：v2.0.0-beta.1
• 发布前用 --draft 先查看，用 gh release view --json 再检查再发布
• 安全约束：永远不重用或移动已存在的标签、保持标签/changelog 标题/清单版本一致

6.2.12 opencode-config —— OpenCode 配置管理

作用：指导 OpenCode 配置文件（opencode.json、agents/*.md、skills/*/SKILL.md、commands、permissions）的编写和修改。验证 $schema 防止无效键，遵循 agent/skill 文件格式约定。

触发条件：编辑 opencode.json、添加/修改 Agent、编写技能或命令、调整模型路由/权限，或用户提到 “opencode config”、”agent prompt”、”SKILL.md”、”command”、”permission”。

核心内容：

• 仓库布局约定：opencode.json（全局配置）→ AGENTS.md（全局规则）→ agents/<name>.md（自定义 Agent）→ skills/<name>/SKILL.md（按需技能）
• Agent 文件格式：frontmatter 键名规范——name（kebab-case）、description（驱动路由和 @-菜单）、mode（primary/subagent）、model、steps、temperature、color、hidden、permission。只读 Agent 必须设置 edit: deny 和 write: deny
• 技能文件格式：name 和 description 必须包含触发关键词——前载条件让模型准确匹配
• 命令格式：slash-command 别名，路由到指定 Agent，template 可内联实时 Shell 输出（! 前缀）
• 权限配置：默认允许 + 拒绝危险的基线：deny 读取 .env*（除 .env.example）、ask 破坏性 bash（rm -rf、git push -f、git reset --hard）

关键设计点：

• 必须验证 $schema（https://opencode.ai/config.json）——不要猜测键名
• anomalyco/opencode 使用 plugins/snapshots（复数），本配置使用 plugin/snapshot（单数 sst 风格），禁止混用
• 两模型约束是绝对的：只允许 deepseek/deepseek-v4-pro 和 deepseek/deepseek-v4-flash
• 修改配置后保持 README.md 同步——Agent 表、技能表、命令表、仓库结构树和迭代日志必须与实际配置一致

6.2.13 reflect —— 持续改进

作用：回顾近期工作，识别反复出现的摩擦模式，提出对 opencode 配置（Agent、技能、命令、规则）的最小化、持久化改进。将经验机制化为配置。

触发条件：用户说 “reflect”、”what can we improve”、”review our setup”、”optimize the config”，或一系列关联会话揭示了值得编纂的模式。

核心工作流（3 步）：

1. 收集信号：回顾当前会话和近期历史——哪些 Agent 被派发了？有失败或升级吗？哪些技能被加载了？有请求但缺失的吗？AGENTS.md 哪些规则被违反或误解了？有冗余的 token 消耗吗（大文件读取代探索、顺序读取代并行）？
2. 识别模式：寻找低成本高回报修复——Flash Agent 对同一类别升级到 Pro 3+ 次 → 调整 Agent 描述或路由规则；技能触发但 Agent 忽略 → 技能 description 太模糊，加触发关键词；重复的风格违规 → 在 AGENTS.md 或 Agent 提示里加明确规则
3. 提出变更：以 checklist 形式呈现——发现的模式 → 建议的变更 → token 节省预估 → 不建议的变更（及其理由）

关键设计点：

• 只提议有证据支撑的变更（至少 2 个会话中出现的模式）
• 不做一次性修复——reflect 找的是反复出现的摩擦
• 修改 Agent 提示时优先收紧（更具体的触发）而非放宽（模糊触发导致更多误路由）
• 编辑 Agent/Skill/Commands 时遵循 opencode-config 技能的规范

6.2.14 codemap —— 仓库结构图

作用：生成带标注的仓库结构图，帮助任何 Agent 快速了解代码库包含什么、关键文件在哪。一张好的 codemap 可替代几十次探索性质的 glob 和 read 调用。

触发条件：首次进入不熟悉的仓库或子目录、用户问 “what’s in this project”、”show me the project structure”、需要了解全局再决定从哪搜索。

核心工作流（4 步）：

1. 生成原始树：使用平台合适的文件列表命令——Windows 用 Get-ChildItem -Recurse -Depth 3 -Name，Unix 用 find . -maxdepth 3。排除 node_modules、.git、dist、build、.next、coverage 等噪音目录
2. 标注关键目录：每个目录一行注释，只标注名称不足以表明用法的目录。跳过名称显而易见的（tests/、docs/、public/）
3. 添加快速参考元数据：语言、运行时、框架、数据库、包管理器、测试运行器、lint/format 工具、构建命令、测试命令
4. 保存（可选）：写入 .opencode/codemap.md，后续会话直接读取而非重新生成

关键设计点：

• 保持简洁——整个 map 控制在 200 行以内；标注是一行行语句而非段落
• 突出意外——非明显的模式：”config 在 src/lib/config.ts 而非根目录”
• 提及关键配置文件——这些是 Agent 通常最先需要读取的文件

6.2.15 conventional-commits —— 规范提交

作用：按 Conventional Commits 标准生成提交信息和 PR 标题，使历史可机器读取、changelog 和版本号升级可自动化。

触发条件：提交变更、起草提交信息、squash、命名 PR，需要正确的 type、scope、breaking-change 标记和祈使语气的主题行时。

核心工作流：

• 格式：<type>(<optional scope>): <imperative subject> + 可选 body（~72 列折行，解释 what/why） + 可选 footer（BREAKING CHANGE:、Closes #123）
• 类型表：feat（minor）→ fix（patch）→ docs/style/refactor（无版本变化）→ perf（patch）→ test/build/ci/chore/revert（无版本变化）
• 规则：主题祈使语气（add 而非 added/adds）、无尾随句号、scope 可选的受影响区域名、breaking change 用 ! 标记或 BREAKING CHANGE: 脚注

关键设计点：

• 微小单文件调整不需要过度工程化——单行 type: subject 足够，body 只在”为什么”不明显于 diff 时才需要
• 先检查仓库现有提交风格：git log --oneline -20——如果仓库使用不同约定（如 [fix] subject 或模块前缀），遵循已有风格而非规范

6.2.16 handoff —— 会话交接

作用：将当前会话压缩为交接文档，供下个 Agent 会话无缝接续。通过路径引用已有产物而非复制内容，保存到 OS 临时目录。

触发条件：结束有未完成工作的会话、任务提到 “handoff”、”交接”、”hand over”、”continue in next session”、上下文过大需要保留当前状态。

核心工作流：

1. 收集已有产物的路径（spec、plan、PR、diff）
2. 摘要剩余状态：目标、进展、阻塞点、待解决问题
3. 记录关键决策和被拒绝的替代方案及理由
4. 添加 建议技能 部分——列出下个会话应加载的技能
5. 写入 OS 临时目录——Windows 为 $env:TEMP\opencode-handoff-YYYY-MM-DD-HHmm.md，Unix 为 $TMPDIR/opencode-handoff-YYYY-MM-DD-HHmm.md

关键设计点：

• 交接是路标而非回放——控制在 100 行以内
• 绝不包含：完整文件或大代码块（引用路径）、密钥、已捕获在产物中的内容、与会话无关的闲聊
• 路径引用而非内容粘贴——避免重复消耗 token

6.2.17 verification-planning —— 验证规划

作用：在实现代码前先回答”这个变更如何被证明正确？”选择最小成本的验证路径，定义单一可观测的”已验证”条件。

触发条件：实现任何非平凡变更前（2+ 文件、逻辑变更、新特性）、AGENTS.md 要求验证计划时、在 /deep 或 /apply 之前。

核心工作流（3 步）：

1. 选择最窄验证路径：从构建检查 → Lint → 单元测试 → 集成测试 → 手动命令 → 文件存在检查 → Oracle 审查 → 完整套件，从最窄开始，只在窄路径无法证明正确性或风险要求时才扩大
2. 声明证据阈值：定义一个可观测条件表示”已验证”——”构建零类型错误通过”、”curl /api/users 返回 200 及预期 JSON 模式”、”测试 should reject invalid email 通过”
3. 运行验证，报告结果：实施了选择的验证路径 → 报告检查了什么、观察到什么、为什么足够 → 验证失败则修复并重新验证，不可跳过

关键设计点：

• 绝不因”文件改了”就跑完整测试套件——验证范围匹配变更范围
• 从不满口声称完成却不带证据——”看起来正确”不是验证
• 验证失败时修复的是代码，不是验证标准——绝不降低证据标准

6.2.18 verify-with-docs —— 文档验证

作用：在基于具体库/框架/API 编码前，先检索当前文档验证签名——检索优先，永远不从记忆猜测。防止幻觉签名和版本漂移。

触发条件：基于命名的依赖库实现代码（特别是快速演进的库）、需要精确签名/选项名/返回形状/配置键、用户提到 “which version”、”latest API”、”did this change”、”check the docs”、”SDK”。

核心工作流（5 步循环）：

1. 确定确切版本：先读实际使用的版本再读文档——JS/TS：package.json + lockfile（node_modules/<pkg>/package.json 是真相源）；Python：pyproject.toml / pip show <pkg>；Go：go.mod；Rust：Cargo.toml / Cargo.lock
2. 去主源：偏好顺序——官方文档（匹配版本）→ 库自身仓库（匹配版本的 tag/branch）→ 随包分发的类型定义（.d.ts、stubs、godoc）→ 信誉良好的参考。跳过博客和 Q&A 找签名
3. 只提取需要的：精确签名、必需 vs 可选参数、返回类型、错误模式、安装版本与记忆假设之间的 breaking change 说明
4. 报告已验证事实并附引用：每个返回的签名必须附带源 URL 或文件路径
5. 然后才实现——基于检索到的 API 而非记忆中的 API

关键设计点：

• 对于频繁查阅的库，挂载为 OpenCode Reference（本地版本锁定的副本），避免每次会话重新抓取文档——更便宜且离线安全
• 反模式：先写调用再”事后检查”——验证在写之前；引用与安装版本不匹配的文档版本；粘贴整页文档而非相关几行

6.3 插件体系

OpenCode 支持通过 opencode.json 中的 plugin 字段引入外部插件，扩展框架能力。本配置使用了两个插件。

6.3.1 superpowers 插件

来源：obra/superpowers（https://github.com/obra/superpowers）

定位：提供 14 个过程型技能，覆盖从需求探索到代码交付的完整软件开发流程。这些技能侧重于方法论和流程规范——如何思考、如何规划、如何协作——与本地 18 个自定义技能的”具体工具操作”定位互补。

14 个过程型技能：

自动注入机制：using-superpowers 技能作为 bootstrap 自动注入到每一个会话中。它的核心指令是：在做出任何响应（包括澄清问题）之前，必须先检查并调用适用技能。这意味着所有 superpowers 技能的触发规则在每一步交互中都被强制评估。

与本地技能的关系：superpowers 的技能侧重于”如何管理流程”，本地 18 个技能侧重于”如何执行具体操作”。例如，systematic-debugging 定义调试的思考框架（先提出假设还是先构建反馈环），而 diagnose 提供具体的 6 阶段执行循环。两者互补而非重复。

6.3.2 DCP 插件

来源：@tarquinen/opencode-dcp（OpenCode Dynamic Context Pruning）

定位：自主上下文裁剪和去重插件，解决长会话中上下文窗口被冗余内容填满的问题。DCP 管理上下文，而非让原生 compaction 独自处理。

配置位置：~/.config/opencode/dcp.jsonc

工作原理：

DCP 基于双阈值机制智能压缩上下文：

• 温和提醒阈值（35K tokens）：当上下文达到约 35K tokens 时，DCP 开始温和提醒模型可以压缩，让 Agent 提前感知上下文压力
• 强力推阈值（75K tokens）：当上下文达到约 75K tokens 时，DCP 开始强力推压缩，为 DeepSeek V4 的 128K 窗口保留充足缓冲空间
• 压缩模式：采用 range 模式——将连续的对话范围压缩为高保真摘要，而非逐条裁剪
• 摘要缓冲：压缩摘要不计入上下文限制，充分利用窗口容量

关键特性：

• 轮次保护：保留最近 4 轮对话不被裁剪（turnProtection），确保当前讨论不会因压缩而丢失
• 受保护工具：task、skill、todowrite、todoread 的输出在压缩时被保护——这些是关键的结构化信息，不可丢失
• 去重策略：相同的 tool + args 调用只保留最新输出，自动移除陈旧重复结果
• 错误清理：3 轮后移除错误工具调用的输入体（保留错误信息），回收 token
• 受保护文件模式：操作 opencode.json、AGENTS.md、.env*、.opencode/** 的内容不被裁剪
• 提醒频率：每 3 个 LLM 请求提醒一次压缩（比默认 5 更频繁），从第 12 条消息后开始注入压缩提醒
• 子代理豁免：DCP 不为子代理会话启用——子代理是短生命周期，Orchestrator 管理上层上下文
• 通知样式：minimal 模式——只显示压缩摘要，不内联展开详情

设计哲学：主动压缩优于被动溢出。DCP 不是等到窗口满了再截断，而是在上下文增长过程中持续注入压缩提醒，让模型自主决定何时压缩。这比原生的硬截断更智能——模型知道哪些内容值得保留、哪些可以概括。

6.4 技能与 Agent 的协作模式

6.4.1 宿主编排

技能没有任何”归属”Agent——它们是共享的。但不同的 Agent 在实际工作流中与不同技能形成了自然的”最佳拍档”关系：

6.4.2 技能链

多个技能可以串联形成完整的工作流管道。以下是最常见的技能链模式：

特性开发全流程：

brainstorming → spec-workflow (propose) → writing-plans → deepwork (Plan→Implement→Verify) 
→ verification-before-completion → code-review → conventional-commits → git-release

Bug 修复流程：

systematic-debugging → diagnose → test-driven-development → verification-planning 
→ verification-before-completion

代码质量提升循环：

code-review → simplify / remove-deadcode → security-review → verification-before-completion

仓库认知流程：

codemap → verify-with-docs → explore (深入具体文件)

6.4.3 命令驱动技能加载

技能可以通过 OpenCode 的 slash-command 系统隐式触发，形成”命令→Agent→技能”的三层路由：

// 示例：/review-loop 命令
"command": {
  "review-loop": {
    "description": "审查当前 diff 并修复发现的问题",
    "agent": "deep-worker",
    "template": "在当前分支运行完整的 code-review → fix → re-review 循环..."
  }
}

当用户输入 /review-loop 时：

1. OpenCode 路由到 deep-worker Agent
2. deep-worker 根据 template 中的指令识别出需要加载 code-review 技能
3. 通过 skill 工具加载技能内容，开始执行循环

类似的链路贯穿整个命令体系：/deep → deepwork、/propose → spec-workflow、/archive → spec-workflow、/release → git-release + gh-cli。

6.4.4 技能发现与覆盖

技能发现遵循明确的优先级链：

1. 插件技能（superpowers 的 14 个技能）——最先注册
2. 全局/用户技能（~/.config/opencode/skills/ 下的技能）——覆盖同名插件技能
3. 项目技能（.agents/skills/ 下的技能）——覆盖同名全局技能

这意味着一个项目可以拥有自己的 code-review 技能，其规则将完全覆盖全局版本。这种机制允许团队根据项目特性定制审查维度和严重度校准标准。

6.5 小结

本章覆盖了 my-opencode-deepseek-config 中完整的技能与插件生态：

• 18 个自定义技能 提供从代码审查到 GitHub 操作、从调试到发布的全面工具覆盖，每项技能都是经过实战打磨的精确指令集
• 14 个 superpowers 技能 提供软件开发的方法论基础设施——强制设计先行、根因分析先行、测试先行、证据先行
• 2 个插件（superpowers + DCP）扩展框架边界——superpowers 注入流程规范，DCP 自主管理上下文窗口

这套技能体系的设计哲学是 “不加载就不花钱”：32 个技能中，一个典型会话通常只加载 2-5 个，其余的在文件系统中静默等待——这正是 OpenCode 相比传统将所有能力塞进 system prompt 的方案的核心优势。

下一章将深入命令别名系统，展示如何通过一行 slash-command 串联起本章介绍的 Agent 和技能。