Qoder 其他实用能力——Plan、Commands 与 Hooks

前八章覆盖了 Qoder 的五大核心能力（Agent、Skill、Rule、Memory、MCP）。但日常使用中，还有三个高频接触的「小功能」值得单独讲一下——它们不属于核心架构的范畴，却能在合适场景下大幅提升效率。

Plan 模式——先规划，再执行

这不是一个独立模式

Plan 模式不是 Qoder 的"第六种模式"，而是Agent 模式的内置规划阶段。它没有独立的模式切换入口，而是通过 /plan 命令触发，或在复杂任务中由 Agent 自动启用。

它解决了什么问题

Agent 默认是"你说一句，它干一步"——你给出指令，它直接开始改代码。这在简单改动（修正拼写、重命名变量）上很高效，但在中大型任务中容易出现问题：

• 改到一半发现方向偏了
• 改了三个文件后发现方案不对
• 中间想调整需求，没有断点

Plan 模式的核心价值是：在执行代码之前，先输出一份实施方案让你审阅。你可以确认、调整、甚至完全推翻，确认没问题了再让 Agent 按计划逐步执行。每一步都有状态跟踪，你可以随时暂停、要求调整、再继续。

工作流全景

描述任务 → 生成计划 → 审阅调整 → 启动执行 → 过程调整 → 收尾回顾
         ↑           ↑            ↑            ↑
       NL描述     输出方案   可编辑/可对话   有存档有记录

1. 描述任务：像给同事派任务那样说明需求——变更目标、限制条件、涉及的文件路径
2. 生成计划：Agent 分析需求后输出结构化的实施方案，包含目标、技术方案、实施步骤。此阶段不修改任何文件
3. 审阅调整：你可以直接编辑方案内容，或者通过自然语言对话让它调整
4. 启动执行：确认后启动，聊天底部会显示待办清单，每项的状态实时更新（未开始/进行中/已完成）
5. 过程调整：执行中途有新想法？随时暂停，说明新要求，Agent 会更新计划后继续
6. 收尾回顾：执行完毕后，Agent 按步骤总结完成的工作，结合 diff 视图做最终确认

什么时候用

场景	推荐方式
修正一个拼写错误	直接用 Agent，无需 Plan
重命名一个变量	直接用 Agent
跨多个文件的功能开发	使用 Plan
重构涉及核心路径的改动	默认使用 Plan
接口调整、架构变更	必须使用 Plan
不确定方案是否正确的任务	先走 Plan，确认后再执行

一个简单的判断标准：如果你不确定改完之后会不会出问题，就应该先用 Plan。

最佳实践

• 描述清晰：像给同事派任务一样写提示词，说清楚范围、限制条件、验收标准
• 步长控制：好的待办事项应该能在较小的 diff 中看清影响范围。如果一步改了 20 个文件，说明粒度太粗了
• 迭代优化：第一版计划不满意？直接让它调整，不用勉强接受

本书中的应用：在第三部分的"架构设计专题"中，我们会看到 Plan 模式如何辅助架构决策；在第四部分的"架构演进管理"中，Plan 模式结合 Memory 记录决策上下文，形成完整的架构变更管理链路。

---

Commands——斜杠命令快捷启动

是什么

Commands（指令）的本质很简单：把一段提示词封装成一个斜杠命令。在对话框中输入 / 就能看到可用的命令列表，选中即可执行。

比如你每次提交代码都要说一段固定的提示词——"请检查代码风格，确认符合项目规范，然后按 conventional commit 格式提交"。与其每次打字，不如把它封装成 /git-push，输入两个斜杠就搞定。

两种作用范围

类型	作用范围	存储路径
用户级	当前用户的所有项目	~/.qoder/commands/
项目级	仅当前项目	.qoder/commands/（可 Git 共享）

用户级适合通用任务（代码审查、生成单元测试），项目级适合项目专属任务（检查 API 规范、校验配置格式）。项目级的指令可以通过 Git 在团队中共享。

创建与管理

三种方式创建：

1. 在 Qoder 设置中进入指令页面，点击"添加"
2. 在对话框中输入 / 后选择创建
3. 直接在 .qoder/commands/ 目录中手写配置文件

指令支持按文件夹分类组织，便于管理日益增长的命令库。

典型用例：/git-push

我最常使用的指令就是 /git-push。它封装了提交推送的全流程——检查变更状态、生成提交信息、执行提交、推送到远端。

一个小技巧：养成大模型提交的习惯

为什么不让 AI 来做提交？因为 LLM 会自动检测所有变更内容，分析每个文件改了什么，然后写出一份详细的提交日志。

对比一下：

对比维度	自己写 commit message	LLM 生成
变更感知	凭记忆，容易遗漏	逐文件对比 diff，全覆盖
描述粒度	笼统的 "fix bug"	精确到每个文件改了哪里、为什么改
格式一致性	看心情	始终按 conventional commit 规范
排查变更记录	得靠 git log 回看代码	日志本身就是详细的变更说明

人做不到每改一行代码都写清楚"为什么改"，但模型可以。养成让 AI 提交的习惯后，翻变更记录几乎不需要看代码——提交信息本身就是一份可读的变更文档。这对排查历史问题、做代码审计来说，价值非常大。

Commands 与 Skill 的关系

Commands 和 Skill 的共同点是：都可以通过提示词创建，把高频操作标准化。

区别在于：

对比维度	Commands	Skill
本质	纯提示词封装	结构化流程（提示词 + Agent 指令 + 步骤）
复杂度	单一任务，一段话搞定	多步骤，可含子任务、决策点
触发方式	对话框输入 /xxx	Skill 机制自动匹配或手动触发
适用场景	快速执行一个确定动作	需要多步骤自动化的复杂流程

选哪个的原则很简单：如果一段提示词能搞定的事情，用 Commands；如果需要多步骤、有分支判断、需要 Agent 自主决策，用 Skill。

补充：Plan 模式也是通过命令触发的——/plan 本质上就是一个内置的 Commands 指令。

---

Hooks——编辑器级事件钩子

Hooks 是 Qoder IDE 中的一种扩展机制：在编辑器执行的关键节点插入自定义逻辑，无需修改任何代码。你只需要编辑 JSON 配置文件，配合 Shell 脚本，就能实现一些确定性行为。

严格来说，Hooks 与 AI 无关——它是编辑器自身的能力，不是 AI 能力。很多现代编辑器（VS Code、JetBrains）都有类似的钩子机制。

它能做什么

场景	触发时机	说明
拦截危险命令	工具执行前	拦截 rm -rf、DROP TABLE 等危险操作
自动 Lint	写文件后	每次保存后自动执行 ESLint/Prettier
日志审计	工具执行后	记录 Agent 的所有操作
桌面通知	Agent 完成时	耗时任务完成后弹出系统通知

实现方式

Hooks 的配置结构很轻：

1. 编写脚本：在 ~/.qoder/hooks/ 下写 Shell 脚本
2. 注册配置：在 settings.json 中配置 hooks 字段，指定事件类型和对应脚本
3. 自动生效：事件触发时，Qoder 自动执行对应脚本

一句话总结

如果你需要 Agent 每次写文件后自动跑 Lint，或者想 拦截一切包含 rm -rf 的命令，Hooks 是最直接的方式。否则，不需要主动配置它。

---

知识延伸：Plan 与 Commands 的底层实现原理

如果你已经深入使用 Qoder，可能会好奇：Plan 模式和 Commands 背后到底是怎么实现的？它们不是 Qoder 特有的魔法，而是 Agent 编排领域的两大经典模式——工作流引擎和装饰器管道。下面用微软 AI Agent 框架的实现来拆解它们的本质。

Plan 的底层本质：工作流引擎

Qoder 的 Plan 模式在框架层面对应工作流引擎（Workflow Engine）：

Plan 模式概念       →   工作流引擎抽象
----------------------------------------
生成计划（待办清单） →   WorkflowBuilder 构建有向图
逐步执行           →   Executor 按拓扑顺序遍历节点
边/依赖关系         →   Edge（顺序边/条件边/消息边）
存档/断点续传       →   Checkpoint 持久化会话状态

工作流引擎的核心是图模型——每个节点是一个 Agent，边定义流转规则。支持五种模式：

1. 顺序执行：Agent 按顺序依次执行
2. 分支选择：根据条件走不同路径（如审查通过→发布，不通过→返工）
3. 并行执行：多个 Agent 同时工作，等全部完成再合并
4. 循环：审查不通过就返回修改，通过才放行
5. 子工作流：一个节点内部可以是一个完整的工作流，实现模块化复用

// 工作流引擎的核心——构建器+执行器
var workflow = new WorkflowBuilder()
    .AddAgent("需求分析", requirementAgent)
    .AddAgent("设计审查", designReviewAgent)
    .AddAgent("代码审查", codeReviewAgent)
    .AddAgent("测试", testAgent)
    .AddEdge("需求分析", "设计审查")
    .AddEdge("设计审查", "代码审查")
    .AddEdge("代码审查", "测试")
    .Build();

var result = await executor.ExecuteAsync(workflow, request);

这段代码看起来是不是很眼熟？对，就是你在做的 create-需求分析 → review-设计 → review-code → test-code。这套流程的本质就是顺序工作流 + 子工作流——每个步骤是一个独立 Agent 节点，边是顺序边。

拆开的好处在哪里？框架层面的答案很明确：

• 每个节点独立：可以单独执行、单独审查，不互相绑架
• 自由组合：中间加一步、减一步、换一步，改一条边就行
• 粒度可控：出错了只重试单个节点，不用整个流程重来
• 状态隔离：每一步都有独立的状态空间，不会串数据

这就是图模型的核心价值——可组合性（composability）。Plan 模式把所有步骤揉在一个会话里自动走完，适合"确定性的完整流程"；你拆成独立节点，适合"灵活的编排——每一步都可以独立调用、独立组合"。两种方式各有用武之地。

Commands 的底层本质：前缀匹配装饰器

Commands 的实现其实比前面涉及的简单得多。它的核心逻辑就是一个前缀匹配：

你在对话框输入 /git-push
  → 装饰器检测到 / 前缀
    → 从指令注册表中查到 /git-push 对应的提示词
      → 把提示词拼到你的输入前面
        → 组装后的完整提示词发给 LLM 执行

简单说就是一句话：判断用户的输入是否以 / 开头，如果是，就找到对应的提示词，拼到前面去。

# 核心逻辑就这么简单
def process_input(user_input: str):
    if user_input.startswith("/"):
        cmd_name = extract_command(user_input)
        prompt = commands_registry[cmd_name]  # 查表
        full_input = prompt + "\n" + user_input  # 拼上去
    return send_to_llm(full_input)

它不涉及 FunctionInvocation（那是工具调用的装饰器），也不需要 AITool/AIFunction 那套复杂的声明-执行分离。Commands 就是在 LLM 收到请求之前，多做了一步"前缀匹配 + 提示词拼接"。

三者的关系

层次	对应概念	粒度	本质
Commands	提示词模板	最轻量	前缀匹配 + 文本拼接
Tools	原子操作	单步骤	AIFunction 注册的可调用函数
Skills	组合流程	多步骤	结构化流程 + 子任务

Commands 是在最外层做文本替换，Tools 在 LLM 层做函数调用，Skills 在中间层编排多步骤流程。你说的"Commands 可以用 Skill 替代"是准确的——Skill 是更高层次的抽象，适合需要多步骤自动化的场景。

---

这三项功能不属于 Qoder 的五大核心能力，但如果你把它们用好——Plan 模式让你敢于接大任务，Commands 让小操作快如闪电，Hooks 在背后默默守住安全底线——它们就是日常效率的加速器。