第七章：命令别名完整指南

目录

• 7.1 命令别名概述
• 7.2 命令别名完整列表
  • 7.2.1 实现类命令
  • 7.2.2 规划与分析类命令
  • 7.2.3 审查类命令
  • 7.2.4 搜索与研究类命令
  • 7.2.5 规约驱动开发命令
  • 7.2.6 前端命令
  • 7.2.7 质量与清理命令
  • 7.2.8 Git 与发布命令
  • 7.2.9 配置与管理命令
• 7.3 命令组合工作流
• 7.4 命令设计原则
• 7.5 如何自定义命令

7.1 命令别名概述

什么是命令别名

命令别名是 opencode.jsonc 中 command 字段定义的快捷入口。它本质上是一个”打字更少、意图更清晰”的路由机制——用户在聊天中输入 /命令名，OpenCode 自动匹配到对应的 Agent 并注入预设模板（template），完成意图路由和执行调度。

在 OpenCode 的 TUI 界面中，输入 / 会显示所有可用命令的自动补全列表，用户无需记忆全部命令即可快速选择。

设计理念

本配置中的 27 个命令遵循以下核心理念：

1. 减少输入：用 /deep 替代”请仔细处理这个复杂任务”，一个斜杠命令完成意图表达和路由
2. 统一入口：所有 Agent 能力通过命令别名暴露，用户无需关心内部 Agent 路由逻辑
3. 降低学习成本：命令名即意图（/review = 审查，/commit = 提交），新用户可凭直觉使用
4. 技能自动加载：需要特定技能的 Agent 在 template 中自动 Load 对应技能，用户无需手动触发
5. 模型自动匹配：Pro 模型处理深度推理、Flash 模型处理轻量查询和检索，路由时自动选择最佳模型
6. 权限边界清晰：只读 Agent（oracle、reviewer、explore、librarian）的命令不会修改文件，读写 Agent 的命令有明确的修改权限

命令分类

27 个命令按使用场景分为 9 大类：

7.2 命令别名完整列表

7.2.1 实现类命令

实现类命令是日常开发中使用频率最高的命令，处理从轻量修改到重型重构的全部编码工作。

/deep —— 重型实现

用途：处理复杂的、多文件改动、需要深度推理的实现任务。deep-worker 是本配置中能力最强的执行 Agent，遵循 AGENTS.md 的全部规则：执行而非探索、最小改动、自我验证、证据纪律。

适用场景：

• 新功能实现（涉及 3+ 文件改动）
• 复杂逻辑重构（跨模块的接口变更）
• 需要深度理解业务逻辑的 Bug 修复
• 性能优化涉及算法级改动
• 架构层面的代码调整

使用示例：

/deep 请实现用户认证模块：包含 JWT 签发、中间件校验、refresh token 轮转，需要同时修改 auth.service.ts、auth.middleware.ts、token.service.ts

/deep 把现有的 REST API 数据访问层从直接调用 Prisma 改为 Repository 模式，涉及 15 个 service 文件

注意事项：

• deep-worker 禁止研究（no research），如果任务需要探索代码库，应先用 /explore 或 /oracle 获取上下文
• deep-worker 禁止委托（no delegation），不能将子任务分派给其他 Agent
• 上下文由 orchestrator 提供，如果上下文不足，Agent 会在执行前先读取相关文件
• 提交任务时尽量提供完整的上下文信息（文件路径、改动范围、预期行为），以减少 Agent 的探索开销

/deepwork —— 审查门控分阶段执行

用途：对于特别复杂或高风险的任务，通过”审查门控”（review-gated）的方式分阶段执行。每个阶段产出耐久工件（artifact），在关键节点暂停等待人工审批，降低返工风险。

五阶段流程：

1. Plan（规划）：分析需求，编写 plan artifact（包含技术方案、改动范围、风险点、验证策略）
2. Review Gate（审查门）：暂停，等待人工审批 plan。审批不通过则回到 Plan 修订
3. Implement（实现）：按 plan 执行代码改动，保持最小变更范围
4. Verify（验证）：运行测试、检查调用链、自读全部修改文件
5. Report（报告）：产出最终报告（改动摘要、验证结果、遗留事项）

适用场景：

• 大规模重构（影响 10+ 文件）
• 涉及多个模块的架构变更
• 修改核心基础设施代码（认证、数据库 schema、配置体系）
• 需要团队达成共识的技术决策实现
• 新人接手不熟悉的模块进行大改动

使用示例：

/deepwork 请把整个项目的日志系统从 console.log 迁移到结构化日志库 pino，涉及大约 40 个文件，需要保持所有日志点的语义不变

/deepwork 将用户表的数据库迁移从手动 SQL 脚本改为 Prisma migration，同时保证生产数据零丢失。需要生成回滚方案

注意事项：

• 每个阶段产出耐久工件后必须等待人工审批才能进入下一阶段
• 如果实现阶段发现 plan 有误，Agent 会暂停请求修订 plan，不会擅自偏离
• 不适合简单任务——简单的单文件改动应该用 /quick，中等复杂度用 /deep
• 相比 /deep 增加了审查门控的开销，但大幅降低了复杂任务的返工概率

/quick —— 快速处理简单任务

用途：处理明确的、低风险的、单文件或小范围的修改任务。light-orchestrator 使用 Flash 模型，速度快、成本低，适合日常高频的轻量操作。

适用场景：

• 修改一个变量名或函数名
• 修复一个 typo 或注释错误
• 调整配置文件中的某个值
• 添加一个简单的参数校验
• 格式化代码或调整 import 顺序
• 单文件内的小范围逻辑调整

使用示例：

/quick 把 config.ts 第 42 行的 timeout 从 3000 改成 5000

/quick 在 user.controller.ts 的 createUser 方法里加一个邮箱格式校验

/quick 修复 src/utils/date.ts 里 formatDate 函数的拼写错误：把 "formated" 改成 "formatted"

注意事项：

• light-orchestrator 同样禁止研究和委托，任务必须明确且自包含
• 如果任务涉及 3 个以上文件或有隐含的跨文件影响，应当使用 /deep
• 如果任务需要先探索代码库才能确定改动范围，先用 /explore 获取信息再来 /quick
• Flash 模型推理能力弱于 Pro，复杂逻辑（如算法级优化、架构调整）不要用 /quick

7.2.2 规划与分析类命令

规划与分析类命令用于”思考型”工作——在动手写代码之前，先理清方向、诊断问题、比较方案。

/plan —— 制定技术方案

用途：针对复杂需求制定结构化的技术方案，包括架构设计、模块划分、接口定义、变更范围、风险评估和实施步骤。planner 具备读写权限，可以将计划写入文件。

适用场景：

• 新功能的技术方案设计（从需求到实施计划）
• 系统架构变更的评估和规划
• 大范围重构的步骤拆解
• 技术选型的方案对比
• 需要输出文档的设计决策

使用示例：

/plan 设计一个文件上传模块的技术方案。需求：支持分片上传、断点续传、秒传检测，存储后端需兼容 S3 和本地文件系统。输出到 docs/design/upload-module.md

/plan 分析当前项目从 REST API 迁移到 GraphQL 的可行性和分步计划

注意事项：

• planner 聚焦于”做什么”和”为什么”，不负责具体实现
• 制定计划后会等待人工审批（特别是在 /deepwork 流程中）
• 如果只是讨论方案（不需要输出正式文档），建议用 /consult 代替

/oracle —— 深度分析与问题溯源

用途：对代码进行深度分析、根因诊断、问题溯源。oracle 是只读 Agent，不能修改任何文件，专注于理解和分析。当遇到难以定位的 Bug 时，oracle 可以加载 diagnose 技能进行 6 阶段结构化调试。

适用场景：

• 定位难以复现的 Bug 根因
• 分析性能瓶颈的代码级原因
• 理解一段复杂遗留代码的逻辑和意图
• 安全漏洞的代码级分析
• 数据不一致问题的追踪

使用示例：

/oracle 用户反馈订单状态在某些场景下会从"已支付"回退到"待支付"，请分析 order.service.ts 中状态机的所有可能路径，找出根因

/oracle 分析 src/engine/renderer.ts 的性能瓶颈，重点关注循环内的内存分配和重复计算

注意事项：

• oracle 是只读 Agent，不会修改任何代码。如果分析后需要修改，请用 /deep 并将分析结果作为上下文传递
• oracle 不能做外部搜索（那是 librarian 的职责），专注于在已有代码中寻找答案
• 分析类任务请描述清楚问题现象、复现条件和预期行为，帮助 oracle 缩小分析范围

/consult —— 方案讨论与最佳实践建议

用途：提供多角度方案对比、最佳实践建议和技术决策参考。有别于 planner（制定具体计划）和 oracle（分析代码根因），consultant 更像是”技术顾问”——给出选项、对比利弊、推荐方向。

适用场景：

• 技术选型讨论（如”用 Zustand 还是 Redux Toolkit”）
• 架构模式的优缺点对比
• 代码组织方式的讨论
• 最佳实践咨询
• “我应该怎么做”类的问题

使用示例：

/consult 我们的 React 项目状态管理目前混用了 Context 和 props drilling，正在考虑引入状态管理库。请对比 Zustand、Jotai、Redux Toolkit 在 bundle size、学习曲线、TypeScript 支持方面的优劣，给出推荐

/consult 数据库查询性能优化：我们有一个 500 万行的订单表，查询越来越慢。请分析索引策略、分区方案和读写分离三种方案的适用场景和 trade-off

注意事项：

• 如果讨论之后需要制定正式计划，用 /plan 承接讨论结论
• consultant 的建议基于通用最佳实践，不包含对当前项目的深度分析（那是 oracle 的职责）
• 如果问题需要查阅外部文档，先用 /search 获取上下文，再把结论带给 consultant

7.2.3 审查类命令

审查类命令覆盖代码审查的三种典型场景：本地 diff 审查、审查修复循环、PR 线上审查。

/review —— 多维度代码审查

用途：对当前 diff（分支 vs 基准，或指定的 PR/文件集）进行多维度、分严重程度的代码审查。reviewer 加载 code-review 技能，按变更规模自动调整审查深度，覆盖的维度包括但不限于：正确性、安全性、性能、可维护性、一致性、可读性。

审查维度：

• 正确性：逻辑是否有误、边界条件是否覆盖、异常路径是否处理
• 安全性：注入风险、敏感信息暴露、权限检查遗漏
• 性能：不必要的内存分配、N+1 查询、阻塞操作
• 可维护性：命名是否清晰、职责是否单一、是否有隐式依赖
• 一致性：是否遵循项目既有模式、是否违反 AGENTS.md 规则
• 可读性：嵌套深度、变量命名、注释质量

使用示例：

/review 审查当前分支相对于 main 的全部改动

/review 审查 src/services/ 目录下本次改动的所有文件

注意事项：

• reviewer 是只读 Agent，不会修改代码。如需自动修复审查发现的问题，请使用 /review-loop
• 如果审查 PR 并需要将结果回帖到 GitHub，请使用 /review-pr
• code-review 技能会根据 diff 规模自动调整深度：小 diff 快速扫描关键维度，大 diff 系统性审查全维度
• 严重程度分级会校准到项目威胁模型（如安全问题是 critical，命名问题是 minor）

/review-loop —— 审查→修复循环

用途：将审查和修复结合成一个自动化循环——审查发现问题 → 修复问题 → 再次审查确认，直到 diff 干净或达到 5 轮上限。这是保障代码质量的”清扫模式”。

工作流程：

1. 审查当前 diff，列出所有发现
2. 逐个修复（每次修复后 self-verify）
3. 修复完成后重新审查
4. 如果发现新问题，回到步骤 2
5. 直到审查无发现（或达到 5 轮上限），输出最终报告

适用场景：

• 提交前的最后一次质量检查
• 发现审查报告有多个问题需要一次性清理
• 集成第三方代码后的质量对齐
• 重构后确保代码风格和规范一致性

使用示例：

/review-loop 在提交前对我的改动做一轮清扫，重点检查命名一致性和错误处理

注意事项：

• 循环上限为 5 轮，防止陷入无限修复。5 轮后未解决的问题会在报告中列出
• 每轮只做行为保持的修复——不会改变代码逻辑，只处理命名、格式、注释、死代码等质量问题
• 如果发现需要改动逻辑的深层问题，Agent 会暂停并报告，不会擅自修改

/review-pr —— 审查 PR 并自动回帖

用途：审查指定的 GitHub Pull Request，将审查发现作为完整的 GitHub Review 回帖到 PR 页面。支持逐行评论（per-line comments）定位到具体代码行。

技术细节：

• 使用 gh api 直接调用 GitHub Reviews API（而非 gh pr review），因为后者不支持逐行评论
• 评论格式为 event=COMMENT（pending review），不会自动批准
• body 携带严重程度汇总，comments 数组包含每条发现对应的文件和行号

适用场景：

• 审查同事提交的 PR
• 自动化 CI 中的代码审查步骤
• 开源项目的 PR triage

使用示例：

/review-pr 审查 PR #42，仓库是 znlgis/my-opencode-deepseek-config

/review-pr 审查当前仓库的 PR #128，重点关注安全相关的改动

注意事项：

• 永远不会自动批准 PR（Never auto-approve — leave the verdict to a human）
• 需要使用已认证的 gh CLI（gh auth status 确认登录状态）
• 逐行评论需要 gh api 权限，确保 token 有 repo scope
• 如果只是想看审查结果而不回帖到 GitHub，使用 /review 即可

7.2.4 搜索与研究类命令

搜索与研究类命令用于”获取信息”——在动手之前搞清楚代码现状、API 接口和外部知识。

/search —— 外部搜索与信息检索

用途：执行外部搜索，查找文档、API 参考、技术文章、最新信息。librarian 使用 Flash 模型，适合快速检索任务——从网页搜索到文档查阅，不修改任何文件。

适用场景：

• 查询某个库的最新 API 用法
• 查找某个错误信息的解决方案
• 研究某个技术概念或模式
• 获取最新版本的变化（changelog、migration guide）
• 查找开源项目的使用示例

使用示例：

/search React 19 的 useOptimistic hook 怎么用？请给出完整示例和 API 签名

/search Prisma v5 到 v6 的迁移指南，特别是 relation 模式的变化

/search 2025 年 Node.js 后端项目的最佳日志方案对比

注意事项：

• librarian 是只读 Agent，仅返回信息，不进行代码改动
• Flash 模型速度快但分析深度有限，如果搜索结果需要深度分析和判断，可以将结果带到 /oracle 或 /consult
• 如果需要核对特定库的 API 签名（编码前验证），用 /docs 更精确

/docs —— 编码前核对 API 文档

用途：在编码前核对特定库或框架的 API 文档，防止凭记忆写出错误的 API 调用。verify-with-docs 技能的核心原则是”检索优先”（retrieval-first）——必须从官方文档或挂载的 reference 源获取信息，禁止凭记忆回答。

工作流程：

1. 识别项目中使用的确切包名和版本（从 package.json 等锁定文件确认）
2. 获取该版本的官方文档（或使用 references 配置的本地文档源）
3. 提取准确的 API 签名、参数类型、返回值
4. 输出可供实现 Agent 直接使用的验证后信息
5. 引用来源 URL 或文件路径

适用场景：

• 使用不熟悉的库 API
• 升级库版本后确认 API 变化
• 快速变化的框架（如 Next.js、React 的最新版本）
• 多版本共存的 API 差异确认
• 怀疑 AI 记忆中的 API 签名可能是旧版本的

使用示例：

/docs 查一下我们项目中使用的 zod v4 的 .pipe() 方法的准确签名和用法

/docs 确认 Next.js 15 的 generateStaticParams 返回值类型是否正确，我们项目用的是 15.2.x

注意事项：

• 与 /search 的区别：/search 做开放式信息检索，/docs 做精确的 API 签名验证
• 如果项目配置了 references（如 opencode-docs），Agent 会优先使用本地挂载的文档源
• 输出结果应包含确切的签名和调用示例，可直接交给 /deep 或 /quick 使用

/explore —— 代码库探索与提案前研究

用途：在做出正式提案之前，对代码库进行无风险的探索性研究。这是 spec-workflow 的第一步——探索现有的代码结构、勾勒可能的技术方案、识别开放问题，但不产生任何正式承诺。

关键原则：

• “no-stakes thinking pass”（无风险思考轮）：不创建正式文件，不锁定方向
• 可以使用并行探索（glob、grep 同时多路发射）快速了解代码结构
• 如果需要持久化探索发现，写入 openspec/explorations/<topic>.md，但不创建 openspec/changes/<change-id>/

适用场景：

• 接到新需求后，先了解相关模块的现状
• 不确定改动范围时，先探索再决定方向
• 多个候选方案时，先探索各方案的实现难度
• 作为 spec-workflow 中 /propose 的前置步骤

使用示例：

/explore 我想给用户模块加 OAuth 登录，先探索一下现有的 auth 相关代码结构和登录流程

/explore 分析一下如果要给所有 API 加 rate limiting，现有的 middleware 架构是怎么组织的，有哪些切入点

注意事项：

• explore 是只读 Agent，不会修改代码
• 如果探索结论非常明确，可以直接 /propose 开始 formal proposal
• 如果探索发现需要深度分析某个模块的代码逻辑，转用 /oracle
• Flash 模型适合快速广度搜索，但如果是复杂逻辑的深度阅读，建议用 Pro 模型的 /oracle

/codemap —— 生成仓库结构图

用途：为当前项目生成带注释的层级结构图，用于快速了解项目布局。输出包括目录树（深度 3 层）、关键目录的功能描述、以及项目元数据（语言、框架、构建/测试命令）。

生成内容：

• 目录树：自动排除 node_modules、.git、dist、build、.next、coverage 等非源码目录
• 目录注释：每个关键目录一行功能描述
• 项目元数据：语言、框架、运行时环境、构建命令、测试命令
• 整体限制 200 行以内

适用场景：

• 刚 clone 一个新项目，快速了解结构
• 加入新团队时熟悉项目布局
• 在大项目中找到特定功能的代码位置
• 作为团队文档的补充

使用示例：

/codemap 生成当前项目的结构图

注意事项：

• 如果 .opencode/codemap.md 已存在且较新，Agent 会增量更新而非全量重建
• codemap 是快速概览工具，不适合深度的模块依赖分析（那是 oracle 的职责）
• 可以配合 /explore 使用：先用 /codemap 了解大局，再用 /explore 深入特定区域

7.2.5 规约驱动开发命令

这组命令实现了完整的 spec-workflow（规约驱动变更工作流）生命周期，遵循 explore → propose → apply → archive 的标准流程，并支持中途的 update 修订。

/propose —— 起草变更提案

用途：为一次变更创建正式的规约提案。产出完整的 spec-workflow 工件集：proposal.md（WHY + WHAT）、tasks.md（实施清单）、delta specs（delta 规格说明），以及必要时的 design.md（HOW——仅在复杂变更需要技术设计时创建）。

生成的工件：

openspec/changes/<change-id>/
├── proposal.md      # 变更提案：动机、目标、影响范围、成功标准
├── tasks.md         # 实施清单：有序的 checkbox 列表，每个任务可独立验证
├── design.md        # 技术设计（可选）：仅在变更足够复杂时生成
└── specs/           # delta specs：相对于 openspec/specs/ 的增删改

关键原则：

• 聚焦 WHY 和 WHAT，而非 HOW（除非需要 design.md）
• 必须先研究现有代码和 openspec/specs/ 中的已有规格
• 提案完成后即停止——不开始实现
• 等待人工审查批准后才能进入 /apply

适用场景：

• 需要正式记录的变更（功能、重构、架构调整）
• 多人协作时确保方向对齐
• 需要团队 review 才能开始的重要改动
• 变更影响多个模块，需要提前规划

使用示例：

/propose 为用户系统添加 OAuth 2.0 第三方登录支持（Google + GitHub）。变更范围：auth 模块、用户模型、session 管理。change-id: add-oauth-login

注意事项：

• /propose 之前建议先用 /explore 了解代码现状
• 提案需要人工 review 后才能进入实施阶段
• change-id 建议使用 kebab-case，语义明确（如 add-oauth-login、fix-session-race-condition）
• delta specs 使用 ADDED/MODIFIED/REMOVED/RENAMED 标记，归档时会合并到主规格文件

/apply —— 按清单实施变更

用途：按照给定的 spec-workflow 提案，逐项执行 tasks.md 中的实施清单。每次完成一个 checklist 项后标记 - [x]，直到全部完成或遇到阻塞。

工作流程：

1. 读取 proposal.md、design.md（如有）、delta specs
2. 从 tasks.md 的第一个未完成项开始
3. 在当前会话中实施该任务
4. 完成后标记 [x]，继续下一项
5. 如果某个任务被阻塞或 design 被证明有误，暂停并请求人工决策
6. 全部完成后，执行验证（构建、测试、自读所有修改文件）

适用场景：

• 审批通过后的提案实施
• 需要严格按照规划执行的复杂变更
• 变更涉及多个步骤且顺序有依赖关系

使用示例：

/apply 按 openspec/changes/add-oauth-login/ 的提案实施

注意事项：

• 必须先有经过审批的提案（/propose 生成），否则没有 tasks.md 可执行
• 如果实施过程中发现 design 有问题，Agent 会暂停并提议更新 design，不会擅自偏离
• 每个任务完成后都会做 self-verify（遵循 AGENTS.md 规则）
• 如果构建/测试失败，Agent 会暂停并报告

/archive —— 归档已完成变更

用途：将已完成的变更归档。将 delta specs 合并到主规格文件，然后把整个变更目录移入存档。

归档步骤：

1. 读取 openspec/changes/<change-id>/specs/ 中的 delta specs
2. 将 ADDED/MODIFIED/REMOVED/RENAMED 标记的内容合并到 openspec/specs/<capability>/spec.md
3. 移动变更目录到 openspec/changes/archive/YYYY-MM-DD-<change-id>/
4. 确认 openspec/specs/ 反映当前实际状态

适用场景：

• 变更已合并到 main 分支后
• 变更已部署到生产环境
• 确认不再需要回退到变更前的状态

使用示例：

/archive openspec/changes/add-oauth-login/

注意事项：

• 仅在变更完成且确认无误后执行
• 归档后 delta specs 已合并到主规格，变更目录移入 archive 保留历史
• Flash 模型适合这个轻量级的文件操作任务

/update —— 修订已有提案

用途：在提案已被创建但尚未完成实施时，对提案进行修订。修订可能源于审查反馈、新发现的需求、或实施过程中暴露的设计缺陷。

适用场景：

• 审查反馈要求修改提案
• 需求在实施前发生了变化
• 实施过程中发现提案需要补充边界情况
• 拆分或合并任务项

使用示例：

/update openspec/changes/add-oauth-login/ 根据审查反馈：1) 在 tasks.md 中增加 session 迁移的步骤；2) 更新 delta specs 增加 session 表的字段变更

注意事项：

• 仅适用于尚未 /archive 的活跃提案
• 修订后需要重新审批（如果有审批流程的话）
• planner 负责修订规划和设计，不涉及代码实现

7.2.6 前端命令

/ui —— 前端与 UI 工作

用途：专用于前端和 UI 相关的任务——组件开发、样式调整、布局设计、交互实现。ui-builder 具备前端领域的专业能力，了解现代前端框架（React、Vue、Next.js 等）和 CSS 方案（Tailwind CSS、CSS Modules、styled-components 等）的最佳实践。

适用场景：

• 创建新的 UI 组件
• 调整页面布局和响应式设计
• 修改样式和主题
• 实现交互动效
• 前端状态管理和数据流

使用示例：

/ui 在 dashboard 页面加一个数据概览卡片组件，包含图表、趋势箭头和加载骨架屏。使用项目已有的 shadcn/ui 组件

/ui 把 settings 页面的表单布局从单列改为双列响应式，移动端自动切换为单列

注意事项：

• 虽然 ui-builder 聚焦前端，但不限于纯 UI——也涉及前端逻辑和状态管理
• 如果任务是前后端都涉及的全栈改动，建议用 /deep 而非 /ui
• ui-builder 使用 Pro 模型，适合需要设计判断的复杂 UI 任务

7.2.7 质量与清理命令

/rmslop —— 清理 AI Slop 和死代码

用途：清理当前改动中的 AI slop（AI 生成的冗余内容）和死代码。remove-deadcode 技能通过 LSP 验证确保每次删除都是安全的——被删除的代码必须确认未被引用。

清理内容：

• Filler comments：仅重述代码内容的注释（// increment i 在 i++ 上面）
• Bolerplate docstrings：自动生成的无信息量文档字符串
• Commented-out code：被注释掉的旧代码（git 历史已有记录）
• Needless defensive wrappers：不必要的防御性包装（如对确定非 null 值的 null check）
• Dead code：LSP 验证未被引用的函数、变量、导入

适用场景：

• 完成功能实现后清理开发过程中产生的冗余
• AI 辅助生成代码后的质量检查
• 代码审查后统一清理注释掉的代码
• 定期维护时清理累积的死代码

使用示例：

/rmslop 清理我最新 commit 中的 AI slop，特别注意那些显而易见的注释和注释掉的代码

注意事项：

• 严格遵循 AGENTS.md 的 Comment Discipline：注释解释 WHY 而非 WHAT
• 每次删除前通过 LSP 验证引用关系，保证不误删
• 不改变代码行为——只做清理，不做重构
• 清理后必须验证构建/测试仍然通过

/simplify —— 行为保持的代码简化

用途：对指定代码进行行为保持的简化——减少复杂度而不改变代码行为。simplify 技能提供了结构化的简化模式，每种模式都会验证行为等价性。

简化模式：

• Early returns：用提前返回替代深层嵌套的 if-else
• Inline single-use variables：将只使用一次的变量内联到使用点
• Remove single-caller functions：移除只有一个调用者的函数，将其逻辑合并到调用处
• Simplify conditionals：简化复杂的条件表达式（如德摩根定律、冗余分支）
• Reduce nesting：通过合并守卫条件减少缩进层级
• Remove unnecessary abstraction：移除过度抽象（不必要的接口、包装类）

适用场景：

• 代码审查中发现某段逻辑过于复杂
• 重构遗留代码中的深层嵌套
• 清理过度设计的抽象层
• 提升代码可读性而不改变功能

使用示例：

/simplify src/services/order.service.ts 里的 processRefund 方法，嵌套太深了

/simplify 简化 utils/validation.ts 中的条件逻辑，现在有 5 层嵌套的 if

注意事项：

• 不改变公共 API 签名（函数名、参数、返回值类型不变）
• 不删除错误处理逻辑（只简化表达方式）
• 每次简化后验证行为等价性
• 与 /rmslop 的区别：/rmslop 删除无用的东西，/simplify 重写复杂的东西使其更简洁

7.2.8 Git 与发布命令

/commit —— 生成规范提交信息

用途：分析当前的 git 状态和 diff，生成符合 Conventional Commits 规范的提交信息，并自动执行 git add 和 git commit。

产出格式：

<type>[optional scope]: <description — WHY, from user's perspective>

[optional body — WHAT changed and WHY]

[optional footer(s) — breaking changes, issue references]

支持的 type：feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert

适用场景：

• 每次完成一个逻辑单元的工作后提交
• 需要规范提交信息以配合自动化工具（semantic-release、changesets）
• 不确定如何描述本次改动时让 Agent 生成

使用示例：

/commit

注意事项：

• Agent 会自动运行 git status 和 git diff HEAD 来分析改动
• 只 stage 相关文件，不会把所有改动无脑添加
• 提交信息以 WHY 为主（而非 WHAT），例如 fix: prevent race condition in session renewal 而非 fix: add mutex
• 不会 push——提交后需要手动 push 或另行操作
• Flash 模型足够胜任这个分析→生成的轻量任务

/release —— 准备 Tag 发布

用途：准备一个完整的带 tag 的版本发布。自动分析自上次 tag 以来的变更，生成发布说明，推断 SemVer 版本号，并输出可复制的 gh release 命令。

发布流程：

1. 分析自上次 tag 以来的 commits 和 merged PRs
2. 按 Conventional Commits 的类型自动推断 SemVer 版本号（MAJOR/MINOR/PATCH）
3. 生成发布说明（release notes）：按类型分组（新功能、修复、破坏性变更等）
4. 输出完整的 gh release create 命令供人工执行
5. 不会自动执行发布——最终确认权在用户

适用场景：

• 定期版本发布（如每周/每两周发版）
• 热修复版本的快速发布
• 首个版本的正式发布

使用示例：

/release

/release 这是一个 patch 版本，只包含 3 个 bug fix

注意事项：

• Agent 会提出版本号建议，但用户可以覆盖
• 生成 gh release 命令后不会自动执行，需要人工确认
• 确保 gh CLI 已认证且仓库权限正确
• 版本号推断基于 Conventional Commits 的类型（feat→MINOR，fix→PATCH，BREAKING CHANGE→MAJOR）

7.2.9 配置与管理命令

配置与管理命令用于持续改进 OpenCode 配置本身——知识沉淀、会话交接、技能管理、验证规划。

/reflect —— 配置反思与优化

用途：回顾近期的会话记录，识别反复出现的摩擦点，并提出最小化的配置改进建议。reflect 技能遵循严格的纪律：一个摩擦点 → 一个根因 → 一个最小修复。禁止大范围重写或引入新模型。

反思范围：

• Agent prompt 中的冗余或模糊指令
• AGENTS.md 中需要增强或修正的规则
• 技能（skills）中需要调整的流程
• 命令（commands）中不合理的路由
• 模型中不匹配的任务分配

适用场景：

• 在多个会话后，感觉 Agent 反复犯同样的错误
• 团队使用一段时间后，希望配置”进化”以适应项目特点
• 发现某个 Agent 的路由策略不合理（如总是把轻量任务发给 Pro 模型）
• 发现 AGENTS.md 的某条规则经常被误用

使用示例：

/reflect 回顾最近 5 个会话，看看 deep-worker 是不是经常做了应该由 oracle 做的探索性工作，有没有配置层面的改进空间

注意事项：

• 遵循”一个摩擦点 → 一个根因 → 一个最小修复”的纪律
• 不会做大范围重写——如果问题根因需要大幅改动，会先报告并请求确认
• reflector 的输出是改进建议，不是自动执行——需要人工审批后才能应用

/learn —— 沉淀项目知识

用途：回顾当前会话，将持久的、非显而易见的项目事实沉淀到 AGENTS.md 中，帮助未来的会话更好地理解项目。只写入真正可复用的、长期有效的事实——不写入任务特定的、临时的笔记，不写入密钥和敏感信息。

沉淀内容：

• 项目特有的编码约定（如”这个项目所有的 API 错误都用 AppError 类包装”）
• 非显而易见的”坑”（如”User.findById 在事务外调用会返回过期数据”）
• 构建/测试命令的特殊参数（如”测试必须加 --runInBand 否则时序依赖会失败”）
• 模块间的结构关系（如”auth.middleware.ts 依赖 redis.service.ts 的 session store”）

不沉淀的内容：

• 临时任务上下文
• 显而易见的事实（如”这是 React 项目”）
• 密钥、token、密码
• 一次性的调试发现

适用场景：

• 在会话中发现了项目特有的隐蔽约定或陷阱
• 新项目启动后逐步建立团队知识库
• 每次重要发现后让 Agent 记录

使用示例：

/learn

注意事项：

• Agent 会判断是否有值得沉淀的内容——如果没有，会明确说明并跳过
• 内容追加到 AGENTS.md 的适当章节，保持文件结构清晰
• 条目保持简洁（通常 1-3 行），不展开长篇说明
• 如果 AGENTS.md 中已存在类似内容，Agent 会更新而非重复

/handoff —— 会话交接

用途：将当前会话压缩为一份交接文档，保存到系统临时目录。下一个会话可以读取这份文档无缝接续工作。文档引用已有工件（specs、plans、diffs）的路径而非复制内容，避免 token 浪费。

交接文档包含：

• 当前任务的上下文和进度
• 已完成的步骤和待办事项
• 关键决策和未解决的问题
• 建议下一个会话加载的技能
• 相关文件路径（引用，不复制内容）
• 脱敏处理后的必要信息

适用场景：

• 长会话接近 token 上限，需要换一个新会话继续
• 想把当前进展交接给同事
• 计划中断工作，后续恢复时快速回到状态
• 使用 /deepwork 后，将阶段性成果传递给下一阶段

使用示例：

/handoff

注意事项：

• 文档保存到 OS 临时目录（/tmp 或 %TEMP%），路径会在输出中显示
• 已有机密信息自动脱敏
• 引用已有工件路径而非复制内容（路径引用是 token 高效的关键策略）
• 包含 suggested-skills 部分，帮助下一个会话快速加载正确的技能

/skill —— 管理 Agent 技能

用途：管理 Agent 技能的完整生命周期——搜索、预览、安装、更新、发布。gh-skill 是 GitHub 官方提供的技能管理工具，支持通过 GitHub 生态发现和分享技能。

支持的操作：

• 搜索：在 GitHub 上搜索可用的 Agent 技能
• 预览：查看某个技能的详细内容和用法
• 安装：安装远程技能到本地 skills/ 目录
• 更新：更新已安装的技能到最新版本
• 发布：将本地技能发布到 GitHub 供他人使用

适用场景：

• 发现社区贡献的新技能
• 安装适用于特定技术栈的技能（如 React、Python、Rust）
• 更新已有技能到最新版本以获取新功能和修复
• 将自己团队开发的技能分享到社区

使用示例：

/skill search react testing

/skill install github.com/someone/react-testing-skill

/skill update code-review

注意事项：

• 需要 GitHub CLI 认证
• 安装技能前建议先用 preview 查看内容
• 本配置的 18 个技能已覆盖常见场景，安装额外技能前确认是否与现有技能重叠

/verify-plan —— 实现前规划验证路径

用途：在开始实现之前，规划最优（最窄）的验证路径。verification-planning 技能帮助确定：需要运行哪些测试、检查哪些调用链、覆盖哪些边界条件——用最小的验证成本保证改动正确性。

规划内容：

• 需要运行的单元测试和集成测试
• 受影响的调用链（callers）清单
• 需要手动验证的边界条件
• 无需验证的安全区域（未被改动的代码路径）
• 推荐的验证顺序（先快后慢，先关键后次要）

适用场景：

• 复杂改动的实现前准备
• 不确定改动影响范围时先规划验证
• 作为 /deepwork Plan 阶段的验证部分
• 团队 code review 前确认验证覆盖

使用示例：

/verify-plan 我准备重构 src/services/payment.ts 的支付流程，先帮我规划一下验证路径，确保不遗漏任何调用链

注意事项：

• 这是实现前的规划步骤，不会执行改动
• 规划结果可以作为 /deep 或 /deepwork 实现时的验证清单
• 如果项目没有测试框架，Agent 会规划手动验证步骤

7.3 命令组合工作流

单个命令解决单个问题，组合命令构成完整工作流。以下是几个经过验证的高效命令组合模式：

开发新功能（规约驱动）

/explore    → 探索相关模块现状，了解改动范围和切入点
/propose    → 起草正式提案（proposal.md + tasks.md）
/apply      → 按 tasks.md 清单逐项实现
/review     → 审查改动，输出分级报告
/archive    → 归档变更，合并 delta specs 到主规格

在 /review 发现问题后，可以插入 /review-loop 做自动修复循环，然后再 /archive。

排查 Bug

/oracle     → 分析代码根因，不做任何修改
/deep       → 根据 oracle 的分析结论实施修复
/rmslop     → 清理修复过程中产生的冗余注释和死代码
/commit     → 生成规范的 fix 类型提交信息

如果 Bug 难以复现，在 /oracle 之前可以用 /search 查找类似问题的社区讨论。

代码审查工作流

# 场景A：审查 PR 并回帖到 GitHub
/review-pr  → 审查 PR diff、生成 review 报告、逐行评论回帖

# 场景B：本地审查修复循环
/review     → 审查本地改动
/review-loop → 自动修复审查发现的问题（最多5轮）

/review-pr 不回帖自动审核通过与拒绝（Never auto-approve），最终审核决定由人工控制。

探索与分析（无代码改动）

/explore    → 广度探索代码库结构
/oracle     → 对关键模块做深度分析
/consult    → 基于分析结果讨论方案选项
/plan       → 将讨论结论转化为正式计划
/deep       → 执行计划

这个流程全程只读直到 /deep，适合需要大量前期调研的复杂需求。

知识沉淀

/learn      → 将会话中的重要发现沉淀到 AGENTS.md
/reflect    → 回顾多会话的摩擦点，提出配置优化
/commit     → 提交 AGENTS.md 的更新

建议定期（如每周）运行一次 /reflect，保持配置持续进化。

版本发布流程

/review     → 发布前最后审查
/rmslop     → 清理 slop 和死代码
/commit     → 提交最终改动（如果还有未提交的）
/release    → 准备 tag 发布：生成发布说明 + 推断版本号

7.4 命令设计原则

本配置中的 27 个命令遵循以下设计原则，理解这些原则有助于你自定义命令或评估新命令的合理性：

1. 一个命令只做一件事（Single Responsibility）

每个命令聚焦一个明确的意图，不混合不相关的功能：

• /review 只审查不修改，/review-loop 审查并修复。两者职责分明
• /deep 实现，/deepwork 实现加门控。复杂度分层，不合并

2. 命令名反映意图（Intention-Revealing Names）

命令名即用户意图的最短表达，不需要记忆映射关系：

• 看到 /commit 就知道是提交，看到 /release 就知道是发布
• 使用动词（/apply、/propose）和动名词（/review、/search）
• 避免缩写和内部代号（如 /dw、/r1）

3. 自动加载所需技能（Auto Skill Loading）

命令不应要求用户手动加载技能。所有技能依赖在 template 中通过 Load the xxx skill 自动触发：

"/review": {
    "agent": "reviewer",
    "template": "Load the code-review skill. ..."
}

4. 模型自动匹配（Auto Model Selection）

Agent 绑定了模型，命令通过 Agent 间接绑定模型：

• Pro 模型（deep-worker、planner、oracle、reviewer、consultant、ui-builder）用于推理密集型任务
• Flash 模型（light-orchestrator、explore、librarian）用于检索和轻量执行

路由时无需用户关心模型选择，只要选对命令即可。

5. 权限边界清晰（Clear Permission Boundaries）

只读 Agent 的命令不会意外修改文件：

• 只读命令：/review、/review-pr、/oracle、/search、/docs、/explore、/codemap
• 读写命令：/deep、/deepwork、/quick、/ui、/apply、/rmslop、/simplify、/commit、/release

6. Template 即指令（Template as Instruction）

命令的 template 字段不是简单的描述文本，而是可执行的指令：

• 包含明确的动作动词（Load、Scope、Review、Implement）
• 包含约束条件（Do not modify code、Do not push、Never auto-approve）
• 可以嵌入 shell 命令（!git status --short、!git diff HEAD）

7. 命令覆盖但不重复（Coverage Without Overlap）

每个使用场景都有对应命令，但同一场景不提供多个等价命令造成选择困难：

7.5 如何自定义命令

你可以根据自己的项目需求，在 opencode.jsonc 的 command 字段中添加、修改或删除命令。

命令的 JSON 结构

每个命令是一个 JSON 对象，包含三个字段：

"<命令名>": {
    "description": "<命令的用途说明，显示在 TUI 命令列表中>",
    "agent": "<路由到的 Agent 名称>",
    "template": "<注入给 Agent 的具体指令模板>"
}

字段说明：

自定义命令示例

示例一：添加一个”代码格式化”命令

"format": {
    "description": "运行 Prettier 和 ESLint 自动格式化当前改动的文件",
    "agent": "light-orchestrator",
    "template": "Run the project's code formatter on the changed files:\n\nChanged files:\n!git diff --name-only HEAD\n\nFor each changed file: run prettier --write, then eslint --fix. Report which files were formatted and any remaining lint errors."
}

示例二：添加一个”生成测试”命令

"test-gen": {
    "description": "为当前 diff 中新增或修改的函数生成单元测试",
    "agent": "deep-worker",
    "template": "Load the test-driven-development skill. Review the current diff for new or modified functions. For each untested public function, write unit tests covering: happy path, edge cases, error handling. Follow the project's existing test patterns and naming conventions."
}

示例三：添加一个”依赖审计”命令

"audit": {
    "description": "审计项目依赖：检查过期、已知漏洞和替代方案",
    "agent": "librarian",
    "template": "Audit the project's dependencies:\n\nPackage.json:\n!cat package.json\n\n1. List all dependencies with their current and latest versions\n2. Check npm audit / GitHub advisory for known vulnerabilities\n3. Flag packages that are unmaintained or have better alternatives\n4. Recommend a prioritized upgrade plan"
}

示例四：修改现有命令的 template

如果觉得某个命令的默认行为不够精确，可以直接修改其 template。例如，让 /commit 使用中文提交信息：

"commit": {
    "description": "使用中文 Conventional Commits 格式提交",
    "agent": "light-orchestrator",
    "template": "Load the conventional-commits skill. Here is the current state:\n\nStatus:\n!git status --short\n\nDiff (staged + unstaged):\n!git diff HEAD\n\nStage the relevant changes and write a single Conventional Commits message in Chinese. The subject should explain WHY from the user's perspective. Body (if needed) should explain WHAT changed. Do not push."
}

命名规范建议

1. 使用 kebab-case：/test-gen 而非 /testGen 或 /test_gen
2. 名称反映动作：动词优先（/review、/search、/commit），名词用于查询类（/docs、/codemap）
3. 避免过短的缩写：/c 不清晰，/commit 清晰（即使输入多几个字符，TUI 的自动补全也只需 /co + Tab）
4. 保持与已有命令风格一致：查看本章已有命令的命名，选择相似的风格
5. 不要创建”超级命令”：一个命令只做一件事。如果新需求需要多步操作，设计为多个命令的组合而非一个命令

删除命令

直接移除 command 块中对应的条目即可。删除前确认：

• 是否有团队成员依赖该命令
• 该命令的功能是否已被其他命令覆盖
• 删除后是否需要更新团队文档

调试自定义命令

如果自定义命令不工作，按以下步骤排查：

1. Agent 名称正确：确认 agent 字段的值与 agent 配置块中定义的名称完全匹配
2. Template 语法正确：确认 JSON 中的特殊字符正确转义（\n、\" 等）
3. 技能存在：如果 template 中有 Load the xxx skill，确认 skills/xxx/SKILL.md 文件存在
4. 重启 OpenCode：修改 opencode.jsonc 后需要重启 OpenCode 会话才能生效
5. 查看日志：如果命令执行但结果异常，检查 OpenCode 的日志输出

命令速查表

下一章：第八章：配置文件完全参考