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

版本说明：本章基于仓库 v38+ 状态编写。相比早期版本（v23），命令体系发生了显著变化：/review-pr 已合并进 /review（PR 模式），/search、/consult 已移除，新增了 /vision、/learn；命令总数从 18 调整为实际的 17 个；/simplify 的路由从 oracle 改为 light-orchestrator（两阶段：spawn oracle 只读分析 → 自身应用编辑）。

目录

• 7.1 命令别名概述
• 7.2 命令别名完整列表
  • 7.2.1 Agent 路由命令
  • 7.2.2 操作命令
  • 7.2.3 内联命令
  • 7.2.4 规约命令
• 7.3 命令组合工作流
• 7.4 命令设计原则
• 7.5 如何自定义命令

7.1 命令别名概述

什么是命令别名

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

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

设计理念

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

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

命令分类

17 个命令按使用场景分为 4 大类：

历史沿革：早期版本（v23）将命令分为 9 大类共 18 个，包含 /search（外部搜索）、/consult（方案咨询）、/review-pr（PR 审查回帖）。v38 精简为 4 大类 17 个：/search 的能力由 explore/librarian 的只读探索覆盖，/consult 由 consultant Agent 直接路由覆盖，/review-pr 合并进 /review（带 PR ref 时自动进入 PR 审查模式）。

7.2 命令别名完整列表

7.2.1 Agent 路由命令

Agent 路由命令直接指定目标 Agent，是日常开发中使用频率最高的命令。

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

/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
• 如果任务需要先探索代码库才能确定改动范围，先用 /oracle 获取信息再来 /quick
• Flash 模型推理能力弱于 Pro，复杂逻辑（如算法级优化、架构调整）不要用 /quick

/ui —— 前端与 UI 工作

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

模型说明：ui-builder 在 v38 中从 Pro 迁移到 Flash（属于”trivial”思考层级，thinking 关闭）。前端任务多为模式化实现，Flash 足够胜任；若遇到需要深度设计判断的复杂 UI 架构，可升级到 /deep。

适用场景：

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

使用示例：

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

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

注意事项：

• 虽然 ui-builder 聚焦前端，但不限于纯 UI——也涉及前端逻辑和状态管理
• 如果任务是前后端都涉及的全栈改动，建议用 /deep 而非 /ui
• 注意区分”视觉/UI 构建”（/ui）与”多模态图像理解”（/vision）：前者是写前端代码，后者是读取图片/截图内容

/vision —— 多模态图像理解

用途：读取并理解图像、截图、图表、UI 设计稿等多模态内容。vision 使用专门的 deepseek-v4-flash-vision-exp 模型（支持图像输入），是配置中唯一能”看图”的 Agent。

适用场景：

• 读取截图中的报错信息
• 理解 UI 设计稿并转述布局
• 识别图表/流程图内容
• 分析图片中的文字、颜色、位置

使用示例：

/vision 请读取这张截图，告诉我里面报了什么错

注意事项：

• vision 是只读 Agent，只描述看到的内容，绝不臆造图片中不存在的信息
• 如果任务需要基于图像理解做代码改动，vision 会升级到 deep-worker
• 图像输入有成本上限控制（attachment.image 配置：超过 1600px / 2MB 会自动缩放），超大图片建议先用 vision-prep 技能预处理

/review —— 代码审查（本地 diff 或 PR）

用途：对当前改动进行多维度、分严重程度的代码审查。/review 是 v38 合并后的统一审查命令，支持两种模式：

• 本地 diff 模式：无 PR 参数时，审查本地改动（分支 vs 基准），按严重度分级报告
• PR 模式：参数带 PR ref/URL 时，加载 gh-cli 技能，将审查发现作为 pending GitHub review 回帖（event=COMMENT，逐行评论 + 严重度汇总）

历史沿革：早期版本（v23）将 PR 审查拆分为独立的 /review-pr 命令。v38 将其合并进 /review——通过参数是否含 PR ref 自动切换模式，减少命令数量、统一入口。

审查维度：

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

使用示例：

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

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

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

注意事项：

• reviewer 是只读 Agent，不会修改代码。如果审查发现的问题需要修复，请手动使用 /deep 或 /quick 处理
• scope-first 门控：如果 diff 很大（>500 有效行）或过于琐碎，reviewer 会先报告一个审查计划并停止，而不是盲目深审——避免在超大 diff 上浪费 Pro token
• PR 模式永远不会自动批准 PR（Never auto-approve — leave the verdict to a human）
• PR 模式需要已认证的 gh CLI（gh auth status 确认登录状态），token 需有 repo scope
• 严重程度分级会校准到项目威胁模型（如安全问题是 critical，命名问题是 minor）

/plan —— 制定技术方案

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

模型说明：planner 在 v38 中从 Pro 迁移到 Flash，但通过 options 重新启用了 thinking 并设置 reasoningEffort: low（属于”mid”思考层级）。规划任务需要一定推理但不必达到 Pro 的深度，Flash + 低推理强度是成本与质量的平衡点。

适用场景：

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

使用示例：

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

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

注意事项：

• planner 聚焦于”做什么”和”为什么”，不负责具体实现
• 制定计划后会等待人工审批
• 如果只是讨论方案（不需要输出正式文档），可直接让 orchestrator 路由到 consultant

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

用途：对代码进行深度分析、根因诊断、问题溯源。oracle 是只读 Agent，不能修改任何文件，专注于理解和分析。

适用场景：

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

使用示例：

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

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

注意事项：

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

7.2.2 操作命令

操作命令覆盖日常的 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）

/reflect —— 配置反思与优化

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

反思范围：

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

适用场景：

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

使用示例：

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

注意事项：

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

/handoff —— 会话交接

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

交接文档包含：

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

适用场景：

• 长会话接近 token 上限，需要换一个新会话继续
• 想把当前进展交接给同事

使用示例：

/handoff

注意事项：

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

7.2.3 内联命令

内联命令用于在会话中快速执行特定操作——生成结构图、沉淀经验、简化代码、清理死代码。

/codemap —— 生成仓库结构图

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

生成内容：

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

适用场景：

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

使用示例：

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

注意事项：

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

/learn —— 沉淀会话经验到 AGENTS.md

用途：分析当前会话，把非显然的经验沉淀到目录级 AGENTS.md 文件。AGENTS.md 可以存在于任意目录层级——当 Agent 读取文件时，父目录的 AGENTS.md 会自动加载进上下文。/learn 让知识沉淀贴近相关代码，而非堆在根目录。

沉淀内容（仅非显然发现）：

• 隐藏的依赖关系
• 与代码表象不同的实际执行路径
• 非显然的配置/环境变量/标志
• 调试突破
• API/工具怪癖
• README 中没有的构建/测试命令
• 架构决策
• 必须一起修改的文件

排除内容：显然的事实、标准框架行为、已在 AGENTS.md 中的内容、冗长解释、会话特定细节。

适用场景：

• 完成一次复杂的调试后，把根因沉淀下来
• 发现某个 API 的隐藏行为，记录下来避免下次踩坑
• 项目有多个模块，希望经验贴近代码存放

使用示例：

/learn 把这次会话中发现的 GDAL 坐标系转换坑沉淀到 AGENTS.md

注意事项：

• 每条经验保持 1-3 行，简洁可执行
• 经验放在离相关代码最近的 AGENTS.md（根/包/特性级）
• 完成后会汇报创建/更新了哪些 AGENTS.md 及每条文件的经验数

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

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

路由说明：/simplify 在 v38 中从 oracle 改为 light-orchestrator，采用两阶段流程：light-orchestrator 先 spawn 一个只读的 oracle 子代理分析目标文件并产出简化方案（精确的 oldString→newString），再由 light-orchestrator 自己应用这些编辑并验证行为保持。oracle 只分析不编辑，light-orchestrator 只编辑不分析——职责分离。

简化模式：

• 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 重写复杂的东西使其更简洁

/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 验证引用关系，保证不误删
• 不改变代码行为——只做清理，不做重构
• 清理后必须验证构建/测试仍然通过

7.2.4 规约命令

规约驱动开发（spec-workflow）的两个核心命令——起草变更提案和按清单实施。

/spec-propose —— 探索代码并起草变更提案

用途：探索现有代码库和规约，为一次变更创建正式的规约提案。产出完整的 spec-workflow 工件集：proposal.md（WHY + WHAT）、tasks.md（实施清单）、delta specs，以及必要时的 design.md。

生成的工件：

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

关键原则：

• 先探索代码现状，再起草提案
• 聚焦 WHY 和 WHAT，而非 HOW（除非需要 design.md）
• 提案完成后即停止——不开始实现
• 等待人工审查批准后才能进入 /spec-apply
• 若已有 scope 重叠 >50% 的变更，执行 update 动作而非新建

适用场景：

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

使用示例：

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

注意事项：

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

/spec-apply —— 按 tasks.md 逐一实施并自动归档

用途：按照给定的 spec-workflow 提案，逐项执行 tasks.md 中的实施清单。每次完成一个 checklist 项后标记 - [x]，全部完成后自动归档 delta specs。

工作流程：

1. 读取 proposal.md、design.md（如有）、delta specs
2. 从 tasks.md 的第一个未完成项开始
3. 在当前会话中实施该任务
4. 完成后标记 [x]，继续下一项
5. 如果某个任务被阻塞或 design 被证明有误，更新工件而非擅自偏离
6. 全部完成后，自动归档：合并 delta specs 到主规格，移动变更到 archive

适用场景：

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

使用示例：

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

注意事项：

• 必须先有经过审批的提案（/spec-propose 生成），否则没有 tasks.md 可执行
• 如果实施过程中发现 design 有问题，Agent 会更新工件，不会擅自偏离
• 每个任务完成后都会做 self-verify（遵循 AGENTS.md 规则）
• 全部完成后自动归档，无需额外执行归档命令

7.3 命令组合工作流

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

开发新功能（规约驱动）

/spec-propose → 探索代码并起草正式提案（proposal.md + tasks.md）
/spec-apply   → 按 tasks.md 清单逐项实现，完成后自动归档
/review       → 审查改动，输出分级报告

排查 Bug

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

代码审查工作流

# 场景A：审查 PR 并回帖到 GitHub
/review #42 → 带 PR ref，自动进入 PR 模式，逐行评论回帖（event=COMMENT）

# 场景B：本地审查
/review     → 审查本地改动，输出分级报告
/deep       → 根据审查报告手动修复发现的问题

/review 的 PR 模式不会自动批准 PR（Never auto-approve），最终审核决定由人工控制。

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

/codemap    → 生成仓库结构图，快速了解项目布局
/oracle     → 对关键模块做深度分析
/plan       → 将分析结论转化为正式计划
/deep       → 执行计划

这个流程全程只读直到 /deep，适合需要大量前期调研的复杂需求。若需外部资料检索，可让 orchestrator 路由到 librarian/explore。

配置优化

/reflect    → 回顾多会话的摩擦点，提出配置优化
/handoff    → 压缩会话为交接文档（方便跨会话接续）

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

版本发布流程

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

7.4 命令设计原则

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

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

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

• /review 只审查不修改，审查发现的问题由用户手动通过 /deep 修复
• /deep 实现重型任务，/quick 处理轻量任务。复杂度分层，不合并

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

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

• 看到 /commit 就知道是提交，看到 /release 就知道是发布
• 使用动词（/spec-apply、/spec-propose）和动名词（/review、/learn）
• 避免缩写和内部代号（如 /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、oracle、reviewer、solo）用于推理密集型任务
• Flash 模型（orchestrator、planner、light-orchestrator、consultant、ui-builder、explore、librarian）用于路由、规划、检索和轻量执行
• Flash-Vision 模型（vision）用于多模态图像理解

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

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

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

• 只读命令：/review、/oracle、/vision、/codemap
• 读写命令：/deep、/quick、/ui、/plan、/rmslop、/simplify、/commit、/release、/spec-propose、/spec-apply、/reflect、/handoff、/learn

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": "Stage the relevant changes and write a single commit message following Conventional Commits."
}

命名规范建议

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

删除命令

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

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

调试自定义命令

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

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

命令速查表

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