Skip to content

方案模板、审查与批准 ​

文档导航 · 任务路由 · 写入范围

方案审查用于核对目标、风险、实施范围与验收安排。独立审查器的意见与人工实施批准是不同事实。本页主要描述完整方案路径;简单低风险路由可直接获得策略授权,无需把自查伪装成人工批准。

规划产物与模板 ​

新任务创建时冻结路由和规划契约,先生成 prd.md,选路由后才准备其余必要产物。默认完整方案集中在 PRD,包含目标、需求、设计、范围与验收;其余文档按实际需要补充。完整流程不要求重复维护多份文档。

项目可用 .agents/rules/planning.json 声明完整方案要求和原始模板:

json
{
  "schemaVersion": 1,
  "required": ["prd.md", "research/findings.md", "implementation-spec.md"],
  "templates": {
    "research/findings.md": ".agents/templates/research.md",
    "implementation-spec.md": ".agents/templates/implementation-spec.md"
  }
}

模板文件需真实存在,内容由项目维护。任务保存原始模板快照,在需要该产物时按原文生成;未填写的原样模板不能满足就绪要求。支持的规划文档为 PRD、design、implement、implementation-spec 和 research/findings。

新配置不会改写已有任务的冻结要求。没有路由快照的旧任务沿用兼容流程,不因新默认路由自动获得简化授权。研究说明与正式方案绑定有区别:普通研究或运行记录更新不撤销实施资格,正式 PRD/选中的方案内容改变会使旧授权失效。

就绪反馈 ​

wenext_create/start/update_artifacts/current 的 details 返回派生的:

text
planning: { ready, missingArtifacts,
  missingSections: [{id, headings}], nextAction, message }

这不是新的批准凭证。合法草稿保存成功与 ready=false 可以同时存在。PRD 至少有有效的目标、需求/范围和验收标准;接受 1–6 级标题、中英文同义标题和“目标与范围”合并标题。空节、TBD、待定不算已完成,也不能借用后续同级章节的内容。

评估时产物不完整返回 planning_incomplete 及缺失项,不启动审查器、不消耗执行重试。根据反馈补文档后再评估;反复 start 或自报通过不能代替补齐。

智能体工具 ​

wenext_plan_review 是模型工具,不是斜杠命令。

action参数行为
runassessment 字段,可选 writePaths推荐入口;内部评估、启动和等待,返回进度、结论及完整方案页面
resolveresolutions: [{finding, resolution, reference}],可选 writePaths将修订方案绑定原始反馈,返回 addressed,不启动新审查器
assesscomplexity、risk、factors、rationale、selfCheck,可选 writePaths返回 self_checked 或 required 及绑定摘要
start可选 writePaths启动实际审查器 Run;必须先启动任务并完成评估
status可选 writePaths返回当前状态、结论和 current;无记录为 not_assessed
wait可选 timeoutMs,0–30000,默认 1000返回终态或当前状态,短轮询超时不取消 Run
cancel无取消并等待清理,保留 blocked 事实
preview无导出完整方案 HTML,未评估或受阻时也可读取
human无取消活动评审后请求真实人工接管

assessment 的 complexity 为 simple/complex/unknown,risk 为 low/medium/high/unknown;未传视为 unknown。rationale、selfCheck 各需 1–4000 字符。风险因子为 cross_boundary、public_contract、persistent_data、security、destructive、uncertain。

工具输入错误使用 isError: true 和 details.error: true;实际评审执行受阻用 status=blocked 与 diagnostic 表达。调用方不能传入 verdict: approved 冒充真实 Run。

审查策略与绑定 ​

默认策略对简单、低风险、无因子、范围明确的完整方案允许自查;复杂度非 simple、风险非 low、有因子、writePaths 包含 . 或多于 5 项时要求独立审查。该规则作用于需要方案审查的路径,不等于所有 quick/small 任务都要人审。

hooks.plan.review.enabled=true 或 --hook plan.review=on 强制独立审查。false/off 只取消强制,不取消风险驱动的要求。节点配置见配置指南。

审查绑定规范化项目根、任务、正式方案摘要和字面 writePaths。未传范围依次复用现有评估、批准范围或空列表;空列表只批准计划,不授予项目写入权限。include/exclude 归属复核未改变 writePaths 时可复用审查。评估是智能体的判断,不保证自动发现所有业务风险,因此完整理由、范围和意见供人工复核。

同一方案普通修正使用一次集中评审:

text
run → 收到 changes_requested → 修订方案 → resolve → 人工批准 → 实施

resolve 用零起始 finding 编号记录每个 blocking 意见的处理和新引用,拒绝空说明、重复/越界编号、未变化的方案、范围变化和不完整的审查器执行。addressed 保留原 changes_requested、Run 和冻结输入,另行绑定修订后摘要,不标为 AI 已批准。语义是否充分由人工审阅。

已有 changes_requested 时重复 run 返回修正指导,不因更新文档就自动再评审。实质目标/范围变化或用户明确要求再审,才重新 assess/run。正式方案批准后改变仍需要重新评估和批准。人工接管不把失败改写为 AI 成功;重新评估可复用既有重试许可,但不重置任务累计三轮上限。取消或未批准的人工接管不产生许可。

审查器运行 ​

审查器是真实只读 Pi 子会话,复用智能体/Run 队列和项目限额。首次使用全新会话,不加载父对话、扩展、技能、AGENTS 或状态目录;父级提供冻结输入,审查器可按相关路径读取项目代码和规范。不存在 Shell、写入、批准或再次委派工具。

完整计划、风险、范围及最近最多 8 份结论冻结到 input。审查器通过 wenext_read_input 分块读取,宿主确认全部字节已交付后才接受结果。单个本地 input/状态最多 128 KiB,不能截断后当作完整审查;读取完成也不证明模型理解正确。

模型默认沿用当前物理模型;显式 provider/model 必须可用,不静默回退。认证使用父 ModelRegistry,不复制凭据。Run 默认超时 120 秒,无固定工具调用或模型回合数上限;约 80 秒提供收束提示。普通读文件错误可纠正,越权或未读完整输入仍阻断。

结果为无 Markdown fence 的 JSON,最多 16000 字节:

json
{
  "schemaVersion": 1,
  "verdict": "approved",
  "summary": "方案与范围一致,验收步骤完整",
  "findings": []
}

verdict 为 approved、changes_requested 或 blocked。summary 最多 4000 字符;findings 最多 20 项,格式为 {severity, message, reference},severity 为 info/warning/blocking,message 与 reference 分别最多 1500 和 500 字符且非空。approved 不能包含 blocking 意见。

只接受身份、父子会话、任务和原始输出匹配的成功、非截断 Run。普通研究智能体的旧结论不能代替此次冻结方案审查。

超时与人工接管 ​

每个任务累计最多三轮独立评审,包括成功后重新评审、超时重试、方案修订和重启。旧任务从事件链推导次数,不重写历史。尚有剩余轮数时,超时可获得恢复许可;只有冻结输入、会话身份和读过的路径指纹未变时才复用审查器会话。无论是否复用,仍需读取当前冻结全文。

达到三轮后不再提供继续 AI 评审,显示打开页面、人工审查未完成执行、要求修订或暂缓。实质分歧汇总给用户,不能自动批准。human 可提前接管未完成执行;未达三轮的继续 AI 只授予重试许可,打开页面不授予批准。

wenext_approve({humanReview:true}) 请求 UI,不能由参数直接批准。真实确认记录 human_approved 与 aiIncomplete=true,不伪造 AI verdict。已成功产出 changes_requested 的业务意见应修订和 resolve,不能作为执行不完整绕过。质量、阶段、范围与完成门禁仍然有效。

人工阅读与批准 ​

保存规划文档或 preview 可生成离线 HTML。批准或扩围时生成新的范围绑定快照,包含完整方案、研究、范围、归属、风险、意见和修正说明。页面只供阅读;返回原 CLI/RPC 会话确认才构成批准。

原生选择器提供打开、批准和暂缓;Esc 暂缓。SSH 用户可复制 HTML 阅读后回到原会话确认。浏览器打开失败保留路径,没有 UI 的宿主不能批准。用户阅读期间方案、指针、范围或审查变化会拒绝迟到确认。

HTML 使用不可变摘要文件名,原文安全转义,外部资源、脚本、表单和不安全链接被限制;无 CDN 依赖。Mermaid 和代码围栏以可读代码显示。预览是派生展示,不是权威批准记录,也没有浏览器批准 API。

持久化与失效 ​

text
<task>/plan-review/
  state.json
  events/<uuid>.json
  inputs/<uuid>.json
  previews/<html-hash>.html

评估前页面位于 <task>/plan-previews/。状态核对事件、输入和正文摘要;批准证据绑定任务、正式方案与原范围。缺失或损坏不能退回旧兼容逻辑,也不能通过重新 assess 静默清除门禁。

取消扩围可保留未被撤销的原范围批准;新范围仍无权写。同一绑定复审、正式方案变化或证据失效则不能复用。沿历史恢复原批准时最多核验 512 事件,循环、缺失或超限明确拒绝。

同一已批准方案的必要实现路径补充可通过带理由的 wenext_scope,不必为补测重新运行整套审查;它仍改变质量输入。目标、公共契约或质量要求变化必须修订方案,不能用扩围掩盖。

starting 状态先落盘;崩溃后保留 blocked,显式请求才重试。运行 owner 退出标记 interrupted,不自动重放。切换任务后的迟到结果只保留历史。旧手填 review 文件不构成新宿主的批准证据。

运行边界 ​

父会话 Bash/PowerShell 直接使用原生执行器,无命令语法或逐条写入预检。它不等于只读,也不绕过后续范围与完成核验;审查器不拥有 Shell。工作流约束不是操作系统沙箱。

审查指标按真实 run ID 去重。status/wait 进度只在状态变化时记录;工具操作数不是独立评审次数。遥测不含完整方案、风险说明、模型输出或凭据。

避免重复确认与重复预览 ​

已展示当前方案预览链接后,原生用户明确回复“按这个方案执行”,且任务、范围和方案摘要未变时,wenext_approve 可复用对话授权,不重复弹窗。工具输出、模型声称已同意、单独“好”、疑问或附带修改要求不算该授权;认领已有改动和接管不完整评审仍使用具体 UI。

新任务的摘要忽略 CRLF/LF 和文件末尾空行差异,正文及 Markdown 硬换行保留;旧任务沿用旧摘要。相同方案、范围和评审状态复用同一预览文件,真正变更仍保存新快照。