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

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

6.1 技能体系概述

6.1.1 技能是什么

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

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

6.1.2 技能目录结构

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

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

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

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

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

6.1.3 加载机制

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

技能的 description 字段是匹配的核心依据——它必须同时描述做什么和何时触发，并前置触发关键词。例如 "Lightweight single-pass 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 在审查→修复循环中加载做自我检查。
  • 权限过滤：Agent 的工具权限会影响技能的可见性。如果一个 Agent 的策略拒绝了某个工具，它就无法看到依赖该工具的技能。这是通过权限配置隐式控制”廉价 flash agent 不要触发昂贵技能”的机制。

6.1.5 25 个技能的分类

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

分类 技能 定位
过程与纪律类 code-review、security-review、spec-workflow、diagnosing-bugs、simplify、remove-deadcode 审查、安全、规约、调试、简化、清理
Git 与发布类 gh-cli、git-master、git-release、resolving-merge-conflicts GitHub CLI、Git 高级操作、发布、冲突解决
探索与知识类 codemap、verify-with-docs、handoff 结构图、文档验证、会话交接
配置与维护类 opencode-config、reflect、writing-for-agents 配置编写、持续改进、Agent 文档规范
分析与领域类 codebase-design、domain-modeling、grilling、grill-with-docs、wait-what 架构词汇、领域术语、需求澄清
办公与多模态类 office-docs、vision-prep Word/Excel 读写、大图/PDF 预处理
协作与流程类 to-tickets、triage 拆解工单、Issue 分流

版本说明：本配置的技能体系经历了持续精简与扩充。v21 移除 deepwork/conventional-commits/diagnose，v23 移除 gh-skill，v38 将技能从 24 个精简到 20 个（移除 /search、/consult 相关技能），随后又陆续并入 shared-language（并入 domain-modeling）、writing-great-skills（并入 writing-for-agents）等，最终形成当前的 25 个。技能数量本身不是目标——每个技能都必须通过”无操作裁剪”测试，即删除后 Agent 行为会改变才值得保留。

6.2 技能逐一详解

6.2.1 code-review —— 代码审查

作用：轻量级单遍代码审查，按 diff/分支/PR 的有效逻辑行数缩放审查深度，报告阻塞项（critical/major）和备注（minor/nit）并附证据；绝不重写代码。

触发条件：审查变更、检查 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. 审查维度：正确性 → 安全性 → 性能 → 架构 → 可维护性 → 文档与注释 → 兼容性
  4. 严重度校准：critical / major / minor / nit，根据项目上下文（版本阶段、部署模型、仓库可见性）校准，防止严重度通胀
  5. 自怀疑检查：每条发现发布前必须通过三道反问——”我能反驳这个发现吗？”“严重度是否被夸大？”“这是真实问题还是个人偏好？”

关键设计点：

  • token 节俭：大审查结果写入文件（.opencode/review-<ref>.md），聊天中只返回摘要行和文件路径
  • 审查→修复循环（通过 /review 触发）：审查 → 最小化修复 → 验证 → 再审查，最多 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 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.4 diagnosing-bugs —— 系统化调试

作用：在提出修复前先构建一个紧密的、可复现失败的反馈环，然后复现 → 假设 → 插桩 → 修复 → 清理。防止”猜测式修复”。

触发条件：调试 bug、测试失败或意外行为，在提出修复方案之前。

核心工作流：

  1. 构建反馈环：先建立一个能快速、可靠复现失败的通道（最小复现用例、针对性测试、可重复的命令）
  2. 复现：确认能稳定复现问题，否则无法验证修复是否有效
  3. 假设：基于证据提出根因假设，而非猜测
  4. 插桩：添加日志/断点验证假设，定位真正的根因
  5. 修复：针对根因做最小修复
  6. 清理：移除调试插桩，确认修复不引入回归

关键设计点：

  • 根因优先：找到根因前绝不提出修复（Iron Law）
  • 反馈环必须足够快——如果复现一次要几分钟，先想办法缩短
  • 修复后必须用最初的复现通道验证，而非”看起来对了”

6.2.5 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.6 simplify —— 代码简化

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

触发条件：用户提到 “simplify”、”refactor”、”clean up”、”reduce complexity”、”too clever”、”hard to read”，或特性落地后代码需要打磨。通过 /simplify 命令路由到 light-orchestrator，由其先派发只读 oracle 分析、再自行应用编辑。

核心工作流：

  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.7 gh-cli —— GitHub CLI 操作

作用：为 Agent 提供 GitHub CLI（gh v2.100.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 类型系统：--type Bug|Feature|Task、父子关系 --parent、阻塞关系 --blocked-by/--blocking、关闭为重复 --duplicate-of
  • Discussions：列表/查看/创建/编辑/评论的完整命令组
  • Projects V2：19 个子命令，覆盖项目 CRUD + 条目管理 + 自定义字段 + 视图
  • Agent Skills：gh skill 命令组——搜索、预览、安装、更新、发布
  • AI 集成：gh copilot（内置 Copilot）、gh agent-task（委托编码任务给 GitHub 编码 Agent）
  • 仓库文件读取：gh repo read-file / gh repo read-dir——无需克隆即可读取仓库内容
  • 发布验证：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.8 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.9 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.10 resolving-merge-conflicts —— 冲突解决

作用：解决 git merge/rebase 冲突。通过查找一手来源（提交信息、PR、Issue）理解原始意图，尽量保留双方意图，绝不发明新行为，绝不 --abort。

触发条件：解决 git merge/rebase 冲突时。

核心工作流：

  1. 理解双方意图：对每个冲突 hunk，查找一手来源（相关提交信息、PR、Issue）理解双方各自想做什么
  2. 保留双方意图：能同时保留就同时保留；冲突通常源于双方对同一区域的不同修改，而非互斥目标
  3. 绝不发明新行为：不引入冲突双方都没有的第三种行为
  4. 绝不 --abort：放弃解决会丢失已完成的合并工作

关键设计点：

  • 冲突是信息，不是障碍——它标记了双方都关心的代码区域
  • 解决后运行测试验证合并结果行为正确

6.2.11 opencode-config —— OpenCode 配置管理

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

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

核心内容：

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

关键设计点：

  • 必须验证 $schema（https://opencode.ai/config.json）——不要猜测键名
  • 三模型约束是绝对的：只允许 deepseek/deepseek-v4-pro、deepseek/deepseek-v4-flash 和 deepseek/deepseek-v4-flash-vision-exp
  • 修改配置后保持 README.md 同步——Agent 表、技能表、命令表、仓库结构树和迭代日志必须与实际配置一致

6.2.12 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.13 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.14 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.15 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.2.16 writing-for-agents —— Agent 文档规范

作用：指导编写或编辑 Agent 消费的文档——技能、AGENTS.md/CLAUDE.md、或任何通过指针到达的文档。确保文档对 Agent 可执行、无歧义、token 高效。

触发条件：编写或编辑 Agent 消费的文档时。触发词包括 “write a skill”、”improve this doc”、”agent instructions”。对于 opencode 配置机制细节使用 opencode-config 技能。

核心规范：

  1. 无操作裁剪（最关键）：对文档中每句话执行测试——”如果删除这句话，Agent 的行为会改变吗？”如果答案是否定的，立即删除。Agent 已经知道默认行为，每句保留的话必须通过此测试
  2. 正向措辞：只说 Agent 应该做什么，从不说它不应该做什么。否定表述（”不要跳过”、”避免忘记”）反而使禁止行为更易被模型触及
  3. 完成标准：文档中每一步必须有可观测、可检查的完成条件。没有完成标准的步骤会导致 Agent 过早声明”已完成”——完成条件是任何人都能检查的条件：”文件存在于路径 X”、”grep 返回 0 匹配”、”输出包含字符串 Y”
  4. 信息层级：步骤内内容（Agent 执行该步必须知道的）→ 文档内参考（Agent 可能需要知道的背景）→ 外部参考（Agent 按需获取的文档链接）。尽可能推到外部参考，步骤内内容保持最少

关键设计点：

  • 写 Agent 文档就是应用于过程文档的 TDD：让子代理在没有文档时失败（RED）→ 写文档 → 证明已规范（GREEN）→ 闭合漏洞（REFACTOR）
  • 该技能融合了 Conventional Commits 标准作为内嵌参考，并吸收了原 writing-great-skills 技能的核心规范

6.2.17 codebase-design —— 架构词汇表

作用：设计架构、选择模块边界、审查代码库结构是否合理时使用的共享词汇表。提供模块/接口/深度/接缝/适配器/杠杆/局部性等术语的统一理解。

触发条件：设计架构、选择模块边界、审查代码库结构是否合理时。

核心内容：

  • 模块：内聚的单元，有清晰目的、通过明确定义的接口通信
  • 接口：模块对外暴露的契约，隐藏实现细节
  • 深度：好接口隐藏大量实现复杂度（深接口），坏接口暴露过多细节（浅接口）
  • 接缝：可以替换实现而不改变调用方的点
  • 适配器：转换一个接口为另一个接口的模块
  • 杠杆：小改动带来大收益的设计
  • 局部性：相关代码在物理上靠近，减少认知负担

关键设计点：

  • 用共享词汇讨论架构，避免”这个模块太乱”这类模糊表述
  • 每个单元应能回答：它做什么、怎么用、依赖什么

6.2.18 domain-modeling —— 领域建模

作用：当项目领域语言模糊、术语使用不一致、术语漂移、同一概念跨会话反复解释时使用。维护 CONTEXT.md 术语表（共享领域词汇），仅在必要时提供 ADR。

触发条件：项目领域语言模糊、术语不一致、术语漂移、同一概念反复解释、需要决定是否记录架构决策。

核心工作流：

  1. 扫描：Agent 在推理代码库前先扫描 .opencode/CONTEXT.md——已知术语直接使用一行定义，不重新解释或展开
  2. 创建/更新：当某个概念需要 3+ 句话才能传达时，在会话结束后添加条目；每次设计讨论后捕获决策作为术语条目
  3. 格式约束：每个条目 - \\`: <一句话定义>`，严格单行。不写段落、不写示例、不写"进一步阅读"

关键设计点：

  • 该技能吸收了原 shared-language 技能——共享语言文档是 token 倍增器：一个术语定义在后续会话中被引用时，每次节省数十句重复解释的 token
  • 条目保持一句话——如果增长，说明它应该是设计文档而非术语
  • 仅在架构决策值得长期记录时才提供 ADR

6.2.19 grilling —— 需求澄清

作用：当需求模糊、在规划或实现前需要澄清时使用——一次只问一个问题，优先多选，直到意图清晰。

触发条件：需求模糊、需要澄清问题。触发词包括 “grill”、”interview”、模糊需求、澄清问题。

核心工作流：

  1. 一次只问一个问题：避免一次抛多个问题让用户负担过重
  2. 优先多选：给出 A/B/C/D 选项让用户选择，比开放式问题更快收敛
  3. 持续追问：直到意图清晰、可以开始规划或实现

关键设计点：

  • 澄清是投资——在错误方向上花一小时比花一分钟澄清贵得多
  • 当需求模糊且领域语言也模糊时，使用 grill-with-docs 组合技能

6.2.20 grill-with-docs —— 组合澄清

作用：当需求模糊且领域语言模糊时，组合 grilling 和 domain-modeling 技能，在收敛意图的同时锐化术语。

触发条件：需求模糊且领域语言模糊——需要同时澄清意图和术语。

核心工作流：

  1. 用 grilling 的方法一次问一个问题澄清需求
  2. 同时用 domain-modeling 的方法记录和锐化领域术语
  3. 两者交替进行，直到需求和术语都清晰

6.2.21 wait-what —— 意图确认

作用：当用户消息令人困惑或无法落地时，用一句话复述以确认后再行动。防止误解。

触发条件：用户消息令人困惑、请求不明确、指令有歧义。触发词包括 “wait what”、不清晰的请求、模糊指令。

核心工作流：

  1. 用一句话复述你对用户意图的理解
  2. 请求确认后再行动

关键设计点：

  • 复述比猜测安全——误解后重做比确认多花一次往返贵得多
  • 只用于真正模糊的情况，不要对清晰请求过度确认

6.2.22 office-docs —— 办公文档读写

作用：读写 Microsoft Word（.docx）和 Excel（.xlsx）文件，通过转换为纯文本或 Markdown 实现。纯 Python 实现（内置脚本），无需 MS Office 或 MCP。

触发条件：读取 Word/Excel 文档、从 .docx/.xlsx 提取文本、创建 .docx/.xlsx，或用户提到 “读 Word”、”读 Excel”、”生成 docx”、”写 xlsx”。

核心工作流：

  1. 用内置 Python 脚本将 .docx/.xlsx 转换为纯文本或 Markdown
  2. 处理转换后的文本
  3. 需要输出时用脚本将 Markdown/文本转回 .docx/.xlsx

关键设计点：

  • 纯 Python 实现，跨平台可用
  • 无需安装 MS Office 或配置 MCP 服务器

6.2.23 vision-prep —— 视觉预处理

作用：在发送给视觉模型前预处理大图和 PDF 页面。DeepSeek 视觉模型将每张图缩放到约 800×800 并拒绝 PDF 输入，因此大图必须切片、PDF 必须先栅格化。

触发条件：读取大图、小字截图、PDF 页面，或用户提到 “大图看不清”、”PDF 里的图片”、”识别 PDF”、”图片文字太小”。

核心工作流：

  1. 大图切片：将超过约 800×800 的图切成多个瓦片，每个瓦片单独发送
  2. PDF 栅格化：将 PDF 页面渲染为图片后再发送
  3. 发送处理后的瓦片/图片给视觉模型

关键设计点：

  • DeepSeek 视觉模型内部将图缩放到约 800×800，超大图只浪费 base64 字节
  • 与 attachment.image 配置（auto_resize、max_width/height 1600、max_base64_bytes 2MB）配合使用

6.2.24 to-tickets —— 拆解工单

作用：将规格或计划拆分为可追踪的 GitHub Issue。每个可独立完成的单元一个 Issue，带验收标准。

触发条件：计划/规格需要拆分为工作项，或用户提到 “tickets”、”工单”、”break into issues”、”分解任务”。

核心工作流：

  1. 分析规格/计划，识别可独立完成的单元
  2. 为每个单元创建一个 Issue，带清晰的验收标准
  3. 通过 gh 创建 Issue

关键设计点：

  • 每个 Issue 必须可独立完成——有明确边界和验收标准
  • 避免创建过小的 Issue（碎片化）或过大的 Issue（无法追踪）

6.2.25 triage —— Issue 分流

作用：基于标签的 Issue 分流工作流。当一批 Issue 需要按优先级/类型排序时使用。

触发条件：一批 Issue 需要按优先级/类型排序，或用户提到 “triage”、”分流”、”prioritize issues”、”label”。

核心工作流：

  1. 拉取 Issue 批次
  2. 按优先级/类型分类
  3. 通过 gh 应用标签/分配负责人

6.3 插件体系

OpenCode 支持通过 opencode.jsonc 中的 plugin 字段引入外部插件，扩展框架能力。本配置使用了两个插件，且都固定了版本以保证可复现性。

6.3.1 superpowers 插件

来源：obra/superpowers（https://github.com/obra/superpowers），固定 tag #v6.3.0

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

14 个过程型技能：

技能 核心原则 触发场景
brainstorming 设计未批准前绝不写代码（HARD-GATE） 任何创造性工作——构建功能、添加组件、修改行为
systematic-debugging 找到根因前绝不提出修复（Iron Law） 任何 bug、测试失败或意外行为
test-driven-development 没看到测试失败就不确定它测试了正确的东西 实现任何特性或 bug 修复前
dispatching-parallel-agents 每个独立问题域一个子代理，并发执行 2+ 个不共享状态的独立任务
executing-plans 加载计划、批判性审查、执行全部任务、完成时报告 有写好的实现计划需要在独立会话中执行时
finishing-a-development-branch 验证测试→检测环境→呈现选项→执行选择→清理 实现完成、所有测试通过、需要决定如何集成
receiving-code-review 验证后再实现、询问而非假设、技术正确性优于社交舒适 收到代码审查反馈、特别是反馈不清晰或有技术疑问时
requesting-code-review 尽早审查、频繁审查 完成子代理驱动开发中的每个任务后、完成主要特性后、合并前
subagent-driven-development 每个任务一个全新子代理 + 每次后审查 + 最终全分支审查 执行有独立任务的实现计划时
using-git-worktrees 检测现有隔离→优先原生工具→回退 git worktree 启动需要与当前工作区隔离的特性工作时
using-superpowers 强制技能优先原则——在做出任何响应前必须先检查并调用适用技能 自动注入到每个会话，作为 bootstrap
writing-plans 零上下文假设 + 坏品味防御 + 每个任务告诉该碰哪些文件 有规格或需求的多步骤任务但尚未触码时
writing-skills 写技能就是 TDD 应用于过程文档——让子代理在没有技能时失败（RED）→写技能→证明已规范（GREEN）→闭合漏洞（REFACTOR） 创建新技能、编辑已有技能、部署前验证
verification-before-completion 证据先于断言，永远如此（Iron Law） 即将声称工作完成/修复/通过时，提交或创建 PR 前

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

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

6.3.2 DCP 插件

来源：@tarquinen/opencode-dcp（OpenCode Dynamic Context Pruning），固定版本 @3.1.15

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

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

工作原理：

DCP 基于双阈值机制智能压缩上下文。关键设计是使用绝对 token 值而非百分比——因为 DeepSeek V4 实际有 1M 上下文窗口（不是 128K），若用百分比（60%≈600K、30%≈300K），普通会话（20K-200K）永远达不到，DCP 就永远不会触发压缩。因此改用绝对 token 值恢复预期的 ~77K/38K 主动压缩，与模型窗口解耦：

  • 强力推阈值（77K tokens）：maxContextLimit: 77000——当上下文达到约 77K tokens 时，DCP 开始强力推压缩
  • 温和提醒阈值（38K tokens）：minContextLimit: 38000——当上下文压缩到约 38K tokens 时停止
  • 按模型成本分层：modelMaxLimits/modelMinLimits 让 pro 比 flash 更早压缩——pro 输入成本是 flash 的 3 倍（0.66 vs 0.22 每 1M），所以 pro 会话在 55K/26K 就触发压缩，以削减昂贵的窗口；flash/vision 保持全局 77K/38K 基线
  • 压缩模式：采用 range 模式——将连续的对话范围压缩为高保真摘要，而非逐条裁剪
  • 摘要缓冲：summaryBuffer: true——压缩摘要不计入上下文限制，充分利用窗口容量

关键特性：

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

设计哲学：主动压缩优于被动溢出。DCP 不是等到窗口满了再截断，而是在上下文增长过程中持续注入压缩提醒，让模型自主决定何时压缩。这比原生的硬截断更智能——模型知道哪些内容值得保留、哪些可以概括。原生 compaction 处理自动触发 + prune（opencode.jsonc 中 compaction.prune: true），DCP 处理主动去重 + 压缩阈值——两层互补而非重叠。

6.4 技能与 Agent 的协作模式

6.4.1 宿主编排

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

Agent 最常搭配的技能 典型场景
orchestrator spec-workflow、handoff 编排复杂工作流、管理会话交接
planner brainstorming、spec-workflow、writing-plans 需求分析、规划分解
deep-worker code-review（loop 模式）、remove-deadcode 重度实现、自我审查
reviewer code-review、security-review 代码审查、安全审计
oracle simplify、systematic-debugging、diagnosing-bugs 深度分析、简化、根因定位
light-orchestrator codemap、simplify、handoff 轻量任务、快速操作、简化执行
explore codemap、verify-with-docs 仓库探索、文档验证
librarian verify-with-docs 外部文档检索
consultant brainstorming、grilling 决策分析、方案评估
vision vision-prep 多模态识别、图像预处理

6.4.2 技能链

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

特性开发全流程：

brainstorming → spec-workflow (propose) → writing-plans → verification-before-completion
→ code-review → git-release

Bug 修复流程：

systematic-debugging / diagnosing-bugs → test-driven-development → verification-before-completion

代码质量提升循环：

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

仓库认知流程：

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

需求澄清流程：

wait-what → grilling → domain-modeling (术语模糊时用 grill-with-docs)

6.4.3 命令驱动技能加载

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

// 示例：/review 命令
"command": {
  "review": {
    "description": "Route to reviewer for code review (local diff or PR)",
    "agent": "reviewer",
    "template": "Load the code-review skill. If a PR ref or URL is present in the arguments, also load the gh-cli skill and post findings as a pending GitHub review per its 'Reviewing PRs' section (event=COMMENT, never auto-approve). Otherwise scope the local diff and scale depth to its effective size, then review and report findings by severity. Scope-first gate: if the diff is large (>500 effective lines) or trivial, report a scoped plan and stop rather than deep-reviewing. Do not modify code."
  }
}

当用户输入 /review 时：

  1. OpenCode 路由到 reviewer Agent
  2. reviewer 根据 template 中的指令识别出需要加载 code-review 技能（PR 场景还加载 gh-cli）
  3. 通过 skill 工具加载技能内容，开始执行审查

类似的链路贯穿整个命令体系：/spec-propose → spec-workflow、/spec-apply → spec-workflow、/release → git-release + gh-cli、/simplify → simplify（light-orchestrator 派发 oracle 分析后自行应用）。

6.4.4 技能发现与覆盖

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

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

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

6.5 小结

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

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

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

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