第 12 章

Quest 模式

Spec 驱动的自主委派，把长任务端到端交给 AI

给 AI 一份蓝图，它自己规划、执行、验证、交付

权限是安全网。这一章是 Qoder CLI 区别于普通 AI 助手的标志性能力 —— Spec 驱动的自主委托，把端到端任务整体交给 AI。

全程盯着

复杂任务里，你和 AI 像在玩乒乓球

一步一确认太累

一个有十几个步骤的需求（如"加一个完整的用户注册流程"），每一步都要你确认，你成了 AI 的操作员，反而被它拴住。

AI 走偏了才发现

对话式推进，AI 走到一半你才发现方向错了——前面的工作白做，缺乏整体规划。

验证全靠你

AI 说"改好了"，到底好不好、测试过没有、有没有破坏别处——全靠你手动核查。

Quest 模式解决的就是"端到端委派"：你给 AI 一份清晰的需求蓝图（Spec），它自己规划步骤、执行、跑测试验证、修复问题，最后交付结果——你只在关键节点介入，而不是全程盯着。

什么是 Quest

定义、白话、和普通对话的区别

Quest 是 Qoder CLI 的Spec 驱动自主委派模式。你用自然语言描述一个完整需求，AI 先把它结构化成一份 Spec（规格说明），经你确认后，自主完成规划、执行、验证、修复的全流程。

说白了，普通对话是你和 AI 一起写代码，Quest 是你把一个项目外包给 AI——你给需求文档，它交成品。你从"操作员"变成"甲方"。

普通对话模式

  • 你指挥一步，AI 做一步
  • 每步基本都要确认
  • 缺乏整体规划
  • 验证靠你手动
  • 适合小任务、探索

Quest 模式

  • 你给需求，AI 自主推进
  • 只在关键节点介入
  • 先 Spec 规划再执行
  • 自动跑测试验证
  • 适合完整功能、长任务

Spec 驱动

Quest 的核心：先规划，后执行

Quest 之所以可靠，关键在Spec——在动手之前，AI 先把你的需求翻译成一份结构化的规格说明：

图：Quest 的 Spec 驱动流程

Spec 通常包含：

  • 目标：要达成什么
  • 步骤：拆解成可执行的子任务
  • 涉及文件：会改动哪些代码
  • 验收标准：怎么算完成（通常是测试）
Spec 是你和 AI 的"契约"。你 review 这份 Spec，确认方向对了，AI 才开始执行——避免走偏才发现。

启动 Quest

两种方式触发一个 Quest

方式一：斜杠命令

直接用 /quest 命令，然后描述你的需求：

/quest 给项目加一个用户注册功能，
要求：邮箱注册、密码加密存储、
注册成功发欢迎邮件、写单元测试

方式二：自然语言触发

在对话中描述一个完整需求，AI 识别后主动建议进入 Quest：

> 我想重构整个认证模块，迁移到 JWT，
保持向后兼容，要有完整测试

（AI 识别这是大任务，建议用 Quest）
启动后第一件事不是写代码，而是生成 Spec。AI 会先分析项目、理解需求、产出一份计划给你确认。这是 Quest 和普通对话最显著的区别。

执行流程

Spec 确认后，AI 自主跑完四个阶段

阶段AI 做什么你的角色
1. 规划 按 Spec 拆解步骤，安排执行顺序 （已在 Spec 确认时参与）
2. 执行 读写文件、运行命令、调用子代理 关键操作可能仍需确认（看权限模式）
3. 验证 自动跑测试、检查验收标准 可随时查看进度
4. 修复 测试失败时自主定位并修复 失败严重时可能介入
"验证—修复"是闭环：测试不过，AI 自己分析失败原因、改代码、再跑——循环直到通过或确实无法解决。这大幅减轻了你的验证负担。

进度追踪

Quest 跑起来后，怎么知道它干到哪了

Quest 是长任务，你不能干等。Qoder CLI 提供几种方式追踪进度：

实时日志

TUI 里会实时显示 AI 当前在做什么——读哪个文件、跑什么命令、遇到什么问题。随时可看。

任务列表

用 /tasks 查看后台运行的 Quest，包括状态（进行中/已完成/失败）和当前步骤。

中断与恢复

Quest 可以中断（比如你要下班了），下次用 /resume 恢复继续。不会丢失进度。

完成通知

配合第 09 章的 Hook，Quest 完成时自动通知（语音、桌面通知），你不必一直盯屏。

适合 Quest

什么任务值得用 Quest 而不是普通对话

完整功能开发

"加一个用户注册流程""实现商品搜索+筛选""做一个数据导出功能"——边界清晰、可测试的完整需求。

大规模重构

"把所有 class 组件改成 hooks""迁移到 TypeScript"——步骤多但模式统一的批量改造。

带验证标准的任务

"修复这个 bug，确保所有现有测试通过"——有明确验收标准，AI 能自己判断完成度。

探索性原型

"做个 demo 验证这个想法"——容错度高，适合放手让 AI 试。

不适合 Quest

这些场景，普通对话反而更合适

以下情况别用 Quest：

需求模糊

你自己都没想清楚要什么，Spec 也写不明白。先用对话探索清楚，再考虑 Quest。

高风险操作

涉及生产数据库、支付逻辑、不可逆操作。这类要全程人工把控，不适合自主委派。

小修小补

改一个 typo、调一个样式——启动 Quest 的规划成本比直接做还高，用对话更快。

需要大量决策

每一步都要你拍板的设计决策——Quest 的自主性反而成累赘，对话更灵活。

判断标准：任务足够大、足够清晰、足够可验证，三者同时满足，Quest 才划算。否则普通对话更高效。

权限配合

Quest 的自主性建立在权限护栏之上

Quest 让 AI 自主跑很多步，权限配置就格外重要——这是你能放心委派的底气。

推荐：accept_edits + 精确 Bash allow

文件编辑自动批准（流畅），shell 命令只允许安全集合（npm test、git status），危险命令 deny。

敏感项目：default + Hook 拦截

每步都确认 + PreToolUse 钩子扫描敏感操作。安全最高，但参与度也高。

实验环境：bypass_permissions

完全放手。但仅限可信沙盒，比如一次性 demo 项目。

CI 自动 Quest：auto + 精确规则

结合第 11 章的 CI 权限配置，让 Quest 在流水线里自主跑，失败就 fail-closed。

Quest + 权限 = 自主又可控。权限圈定了 AI 能做什么，Quest 让 AI 在圈内自主完成。两者配合，才是"放心委派"的正确姿势。

排错指南

Quest 相关的高频问题

Quest 走偏了方向

原因：Spec 阶段你没仔细 review，或需求描述不够清晰。修复：中断 Quest，重新描述需求；务必在 Spec 确认环节把方向校准。

卡在验证循环出不来

原因：测试一直失败，AI 修不好。修复：人工介入看失败原因；可能是测试本身有问题，或任务超出 AI 能力，降级为对话逐步推进。

Quest 中途没响应

原因：可能在等权限确认，或网络波动。修复：检查是否有待确认操作；用 /tasks 看状态；必要时中断恢复。

Credits 消耗过快

原因：Quest 是长任务，token 消耗大。修复：用 /usage 监控；复杂 Quest 选高峰外时段（折扣）；拆成多个小 Quest。

动手练习

用一个真实需求体验端到端委派

练习 1：选一个合适的任务

  • 在你的项目里找一个边界清晰、可测试的功能
  • 比如"给某个工具函数加输入校验和单元测试"

练习 2：启动 Quest 并 review Spec

  • 用 /quest 描述需求
  • 仔细看 AI 生成的 Spec，必要时让它调整
  • 确认方向无误后才让它执行

练习 3：观察自主执行

  • 看 AI 如何规划、执行、验证
  • 观察"验证—修复"闭环
  • 完成后 review 它的改动，体会效率提升

本章回顾

带走的三个核心认知

Quest 是端到端委派

给蓝图，AI 自己规划、执行、验证、修复、交付。

Spec 是契约

先规划后执行，你 review Spec 把关方向，避免走偏。

权限是护栏

Quest 的自主性建立在权限圈定的安全边界内。

核心结论：Quest 模式是 Qoder CLI 区别于普通 AI 助手的标志性能力——它让你从"和 AI 一起干活"升级到"指挥 AI 干活"。配合权限系统，这是目前最接近"AI 同事"的体验。

控制篇结束。接下来进入工程化篇——第 14 章，让 CLI 走出终端，进入 CI/CD 流水线。

延伸阅读

继续本课程

官方资源