向导
交互式任务规格向导 — 一个轻量编排器,基于 discovery 与 consilium,将粗略的任务简述转化为结构化规格及图产物。
什么是向导
向导将线性的 discovery → /dr-prd 链路转变为引导式、一次一问的访谈,操作者可以分支、暂停并重新界定范围。它的存在是为了通过与操作者共同撰写 PRD,消除「智能体误读任务意图」的问题。
它是一个轻量编排器:它组合了现有的 discovery 技能(一次一问引擎)和 consilium(按需小组)——它从不重新实现它们的提示逻辑——并通过确定性的状态引擎持久化每一步。
四项能力
- 嵌套下钻与自动上下文捕获。操作者可以在侧线程中深入探究一个困难的子问题,并将结论拉回主线程,而无需手动携带会话标识符。状态锚定于任务 ID;捕获的上下文是一个持久化的下钻帧,持有对先前答案的引用而非副本——它在弹出时解析,结论作为父问题的答案写回。
- 按需 consilium。对于困难决策,通过
consilium技能召集小组,并将裁决记录为决策图节点及一条「resolves」边。 - 流程中重新界定范围。添加或修订需求,或更改目标,会设置 research-dirty 或 plan-dirty 标志。在 v1 中,实际的重新研究和重新规划仍由操作者确认——仅跟踪 dirty 标志,无自动触发循环。
- 知识/依赖图输出。访谈中浮现的概念、需求和决策作为图节点和边输出到侧产物,供图接收端使用。
状态模型
状态是一个仅追加的 JSONL 事件日志;当前状态是对事件的投影(折叠)。这正是访谈可恢复、可分支的原因:
- 恢复——重放日志;重新运行
/dr-wizard会继续,而非重新开始。 - 分支——派生的下钻栈(push / pop)加上父链接。
- 幂等性——投影时每个问题 ID 的最新事件胜出。
- 每个事件携带模式版本和单调递增的序列号。
- 终止性的「finalized」事件关闭访谈;打开的下钻帧作为已放弃弹出。
/dr-prd仅消费已终结的产物——半完成的访谈永远不具有权威性。
文件位于被 gitignore 的运行时树中:datarim/wizard/{TASK-ID}.wizard.jsonl 保存访谈事件日志(类型:meta、question、answer、drill push、drill pop、flag、finalized)。
引擎 API
消费者引入状态库并调用其公共函数——init、add question、answer、get answer、drill push、drill pop、re-scope、flags、finalize、status、validate、graph node、graph edge。引擎是正确性的唯一保证点:在任何消费者信任日志之前先运行验证。它检查 push 与 pop 是否平衡、序列是否单调、事件类型和模式版本是否已知,以及每条图边是否引用现有节点。验证会拒绝——它从不尽力修复。
图产物
datarim/wizard/{TASK-ID}.graph.jsonl 是图接收端有文档记录的摄取契约——每行一个 JSON 对象:一个 meta 头,然后是节点(类型化概念、需求或决策)和边(关系:dependency、refines 或 resolves)。
图是向外流动的,因此节点标签在接收端边界处被脱敏(令牌形态、持有者凭证、私钥块、用户-密码-主机形式、家目录路径、私有范围地址)后才写入。本地访谈日志保留原始文本。丰富、合并和查询语义属于图接收端——此技能仅按契约输出;它不构建接收端。
与 /dr-prd 的组合
/dr-prd 获得一个单一、非侵入式的钩子:如果任务存在已终结的向导产物,它消费该产物的需求摘要和图,而非运行普通的 discovery 访谈。该钩子是幂等的——重新运行会重读同一产物,绝不重复消费。当不存在向导产物时,普通 discovery 路径保持不变。这保持了一个访谈引擎、两种入口体验,避免了第二次漂移的 discovery 过程。
安全态势
由引擎而非文字强制:注入门转义反斜杠、引号和制表符,同时拒绝换行、回车、其他 C0 控制字符和 DEL;对问题 ID、节点 ID、类别 slug 以及封闭的类型/关系枚举使用允许列表;路径包含采用严格的任务 ID 模式,拒绝符号链接目标,并在锁下追加;以及出站图接收端的脱敏。
何时停止
与 discovery 相同的契约:所有分支已解决(无打开的下钻帧),完成标准已定义,没有遗留任何答案会改变方法的问题。然后终结、验证并输出需求摘要。不要过度访谈——一词确认意味着范围清晰;收尾。