{"id":"8df78ed8-804f-4d55-873a-3f8be295c969","entityType":"agent","slug":"clawhub-songzhou666-reqplan-v3","name":"reqplan-v3","canonicalUrl":"https://www.xpersona.co/agent/clawhub-songzhou666-reqplan-v3","canonicalPath":"/agent/clawhub-songzhou666-reqplan-v3","generatedAt":"2026-10-10T07:39:48.496Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T15:33:07.357Z","emptyReason":null},"description":"项目全生命周期管理引擎。用于系统化、流程化地执行软件工程任务。 **When to use**: - 用户说\"帮我开发...\"、\"实现...功能\"、\"新增...\"、\"写个...\" - 用户说\"帮我分析...\"、\"审查...\"、\"看看这个设计...\" - 用户说\"出错了\"、\"报错了\"、\"修个Bug\"、\"修复...\" - 用户说\"帮我规划...\"、\"怎么做...\"、\"有什么方案\" - 用户说\"完善文档...\"、\"补充文档...\"、\"写文档...\" - 用户说\"重构...\"、\"优化架构...\"、\"技术债务...\" - 用户说\"测试...\"、\"写测试...\"、\"覆盖率...\" - 用户输入 \"/reqplan\" 命令 - 任何涉及多步骤、需要设计-实现-验证的复杂任务 **When NOT to use**: - 单次简单问答（如\"Python列表怎么排序\"），不涉及多步骤任务规划 - 纯聊天对话，无具体任务目标（无开发/分析/修复意图） - 纯粹的信息查询（如\"React 18 新增了什么\"），不需要代码产出 - 用户仅要求查看/浏览代码，无需分析、修改或设计 - 需求极度模糊且用户拒绝澄清，无法确定具体任务边界 - 任务目标/范围已明确固定、只需单次代码修改、不涉及多阶段协作 **How it works**: 0. 确定项目路径（元任务走兜底规则，不以路径模糊为由跳过） 1. 读取接力棒（.agent/harness/_baton.md）获取当前状态 2. 按状态机自动执行：START→ANALYZE→CONFIRM→DESIGN→IMPLEMENT→VERIFY→JUDGE（无需用户逐一下令） 3. 每个阶段必须验证产物才能进入下一阶段 4. 所有产物通过文件传递，禁止口头传递 5. 用户必须在 CONFIRM 阶段确认后才能继续 6. 每步回复第一行必须输出\"当前状态：[状态名]，下一步：[操作]\" 7. 每步结束执行验证链检查（计数验证/列表验证/文件验证），防止虚假完成 **What it produces**: - 需求分析报告（_analysis.md） - 技术设计文档（_design.md） - 实现摘要（_implementation.md） - 验证报告（_verification.md） - 接力棒状态（_baton.md） - **质量审核报告（_quality_audit_analysis.md / _quality_audit_design.md / _quality_audit_implement.md / _quality_audit_verify.md / _quality_audit_judge.md）**","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.4K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s171ezpm2b0hjzn2z4ww819jrn878gc2:reqplan-v3","sourceUrl":"https://clawhub.ai/songzhou666/reqplan-v3","homepage":"https://clawhub.ai/songzhou666/skills/reqplan-v3","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/songzhou666/reqplan-v3","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/songzhou666/skills/reqplan-v3","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":68,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"reqplan-v3 technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T15:33:07.357Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T15:33:07.357Z","emptyReason":null},"stars":null,"forks":null,"downloads":2386,"packageName":null,"latestVersion":"0.1.0","tractionLabel":"2.4K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T15:33:07.357Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T15:33:07.357Z","lastCrawledAt":"2026-10-09T15:33:07.357Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T15:33:07.357Z","lastVerifiedAt":null,"highlights":[{"version":"0.1.0","createdAt":"2026-08-06T09:34:47.785Z","changelog":"ReqPlan-v3 0.1.0 — Initial release - Introduces a project lifecycle management engine for systematic execution of software engineering tasks. - Enforces a strict state machine workflow (START → ANALYZE → CONFIRM → DESIGN → IMPLEMENT → VERIFY → JUDGE). - Implements a mandatory entry checklist and first-response guard to ensure process rigor. - Defines clear rules on when to activate, file structure for artifacts, and strict security and privacy controls. - Incorporates a user interruption handling mechanism with smart resume, reset, or TODO logic. - Requires all outputs and transitions to be tracked via baton files; prohibits oral transmission or workflow bypass.","fileCount":33,"zipByteSize":98701}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s171ezpm2b0hjzn2z4ww819jrn878gc2:reqplan-v3","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s171ezpm2b0hjzn2z4ww819jrn878gc2:reqplan-v3` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/songzhou666/reqplan-v3 before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-songzhou666-reqplan-v3/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-songzhou666-reqplan-v3/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-songzhou666-reqplan-v3/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-songzhou666-reqplan-v3/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-songzhou666-reqplan-v3/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-songzhou666-reqplan-v3/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T07:39:48.495Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-songzhou666-reqplan-v3/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-songzhou666-reqplan-v3/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-songzhou666-reqplan-v3/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-songzhou666-reqplan-v3/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T15:33:07.357Z","emptyReason":null},"readme":"Skill: reqplan-v3\n\nOwner: songzhou666\n\nSummary: 项目全生命周期管理引擎。用于系统化、流程化地执行软件工程任务。 **When to use**: - 用户说\"帮我开发...\"、\"实现...功能\"、\"新增...\"、\"写个...\" - 用户说\"帮我分析...\"、\"审查...\"、\"看看这个设计...\" - 用户说\"出错了\"、\"报错了\"、\"修个Bug\"、\"修复...\" - 用户说\"帮我规划...\"、\"怎么做...\"、\"有什么方案\" - 用户说\"完善文档...\"、\"补充文档...\"、\"写文档...\" - 用户说\"重构...\"、\"优化架构...\"、\"技术债务...\" - 用户说\"测试...\"、\"写测试...\"、\"覆盖率...\" - 用户输入 \"/reqplan\" 命令 - 任何涉及多步骤、需要设计-实现-验证的复杂任务 **When NOT to use**: - 单次简单问答（如\"Python列表怎么排序\"），不涉及多步骤任务规划 - 纯聊天对话，无具体任务目标（无开发/分析/修复意图） - 纯粹的信息查询（如\"React 18 新增了什么\"），不需要代码产出 - 用户仅要求查看/浏览代码，无需分析、修改或设计 - 需求极度模糊且用户拒绝澄清，无法确定具体任务边界 - 任务目标/范围已明确固定、只需单次代码修改、不涉及多阶段协作 **How it works**: 0. 确定项目路径（元任务走兜底规则，不以路径模糊为由跳过） 1. 读取接力棒（.agent/harness/_baton.md）获取当前状态 2. 按状态机自动执行：START→ANALYZE→CONFIRM→DESIGN→IMPLEMENT→VERIFY→JUDGE（无需用户逐一下令） 3. 每个阶段必须验证产物才能进入下一阶段 4. 所有产物通过文件传递，禁止口头传递 5. 用户必须在 CONFIRM 阶段确认后才能继续 6. 每步回复第一行必须输出\"当前状态：[状态名]，下一步：[操作]\" 7. 每步结束执行验证链检查（计数验证/列表验证/文件验证），防止虚假完成 **What it produces**: - 需求分析报告（_analysis.md） - 技术设计文档（_design.md） - 实现摘要（_implementation.md） - 验证报告（_verification.md） - 接力棒状态（_baton.md） - **质量审核报告（_quality_audit_analysis.md / _quality_audit_design.md / _quality_audit_implement.md / _quality_audit_verify.md / _quality_audit_judge.md）**\n\nTags: latest:0.1.0\n\nVersion history:\n\nv0.1.0 | 2026-08-06T09:34:47.785Z | auto\n\nReqPlan-v3 0.1.0 — Initial release\n\n- Introduces a project lifecycle management engine for systematic execution of software engineering tasks.\n- Enforces a strict state machine workflow (START → ANALYZE → CONFIRM → DESIGN → IMPLEMENT → VERIFY → JUDGE).\n- Implements a mandatory entry checklist and first-response guard to ensure process rigor.\n- Defines clear rules on when to activate, file structure for artifacts, and strict security and privacy controls.\n- Incorporates a user interruption handling mechanism with smart resume, reset, or TODO logic.\n- Requires all outputs and transitions to be tracked via baton files; prohibits oral transmission or workflow bypass.\n\nArchive index:\n\nArchive v0.1.0: 33 files, 98701 bytes\n\nFiles: .gitignore (64b), 1-manifest (0b), 1-manifest/skill-manifest.yaml (3355b), 6-docs (0b), 6-docs/changelog.md (32169b), agents (0b), agents/analyzer-agent.md (6257b), agents/designer-agent.md (4553b), agents/implementer-agent.md (4676b), agents/quality-auditor-agent.md (9433b), agents/verifier-agent.md (9424b), artifacts (0b), artifacts/template-artifacts.md (16962b), LICENSE (1064b), protocols (0b), protocols/baton-protocol.md (6958b), quality-control (0b), quality-control/00-quality-system.md (12907b), README.md (7328b), reference (0b), reference/anti-patterns.md (7219b), reference/debug-guide.md (3751b), reference/faq-deep.md (11514b), skill-card.md (2692b), SKILL-execution.md (38732b), SKILL.chunks (0b), SKILL.chunks/chunk-01-guide.md (7127b), SKILL.chunks/chunk-02-flows.md (12047b), SKILL.chunks/chunk-03-harness.md (5843b), SKILL.chunks/chunk-04-chain.md (4853b), SKILL.chunks/chunk-index.yaml (1088b), SKILL.md (32633b), _meta.json (129b)\n\nFile v0.1.0:SKILL.md\n\n---\nname: reqplan-v3\nversion: 5.1\nauthor: songzhou\ndescription: |\n 项目全生命周期管理引擎。用于系统化、流程化地执行软件工程任务。\n\n **When to use**:\n - 用户说\"帮我开发...\"、\"实现...功能\"、\"新增...\"、\"写个...\"\n - 用户说\"帮我分析...\"、\"审查...\"、\"看看这个设计...\"\n - 用户说\"出错了\"、\"报错了\"、\"修个Bug\"、\"修复...\"\n - 用户说\"帮我规划...\"、\"怎么做...\"、\"有什么方案\"\n - 用户说\"完善文档...\"、\"补充文档...\"、\"写文档...\"\n - 用户说\"重构...\"、\"优化架构...\"、\"技术债务...\"\n - 用户说\"测试...\"、\"写测试...\"、\"覆盖率...\"\n - 用户输入 \"/reqplan\" 命令\n - 任何涉及多步骤、需要设计-实现-验证的复杂任务\n\n **When NOT to use**:\n - 单次简单问答（如\"Python列表怎么排序\"），不涉及多步骤任务规划\n - 纯聊天对话，无具体任务目标（无开发/分析/修复意图）\n - 纯粹的信息查询（如\"React 18 新增了什么\"），不需要代码产出\n - 用户仅要求查看/浏览代码，无需分析、修改或设计\n - 需求极度模糊且用户拒绝澄清，无法确定具体任务边界\n - 任务目标/范围已明确固定、只需单次代码修改、不涉及多阶段协作\n\n **How it works**:\n 0. 确定项目路径（元任务走兜底规则，不以路径模糊为由跳过）\n 1. 读取接力棒（.agent/harness/_baton.md）获取当前状态\n 2. 按状态机自动执行：START→ANALYZE→CONFIRM→DESIGN→IMPLEMENT→VERIFY→JUDGE（无需用户逐一下令）\n 3. 每个阶段必须验证产物才能进入下一阶段\n 4. 所有产物通过文件传递，禁止口头传递\n 5. 用户必须在 CONFIRM 阶段确认后才能继续\n 6. 每步回复第一行必须输出\"当前状态：[状态名]，下一步：[操作]\"\n 7. 每步结束执行验证链检查（计数验证/列表验证/文件验证），防止虚假完成\n\n **What it produces**:\n - 需求分析报告（_analysis.md）\n - 技术设计文档（_design.md）\n - 实现摘要（_implementation.md）\n - 验证报告（_verification.md）\n - 接力棒状态（_baton.md）\n - **质量审核报告（_quality_audit_analysis.md / _quality_audit_design.md / _quality_audit_implement.md / _quality_audit_verify.md / _quality_audit_judge.md）**\n---\n\n# ReqPlan-v3 — Harness Engineering 引擎\n\n> **约束即自由**。给 AI 严格的框架，它才能在框架内交出可靠的工作。\n> 本 Skill 的每个规则都必须通过检查点验证，未通过则阻断流程。\n\n---\n\n## ⚠️ 激活即执行（强制！）\n\n当 ReqPlan-v3 被激活时（用户表达了开发/修复/分析等意图），AI **必须**立即执行以下流程，不得等待用户额外指令：\n\n```\nStep 1: 运行强制入口清单（见下方）\nStep 2: 读取接力棒 → 确定当前状态\nStep 3: 如果接力棒不存在 → 创建接力棒，状态 START\nStep 4: 如果状态是 X → 直接从 X 阶段续跑\nStep 5: 按状态路由表执行当前阶段任务\nStep 6: 完成阶段任务 → 更新接力棒 → 自动进入下一阶段\nStep 7: 重复 Step 5-6，直到 CONFIRM 或 DONE\n```\n\n> **🔗 自绑定条款（不可绕过）**：\n> - 本条 skill 的 **所有规则、约束、状态机均无条件适用于一切被激活的场景，包括但不限于**：\n> 1. 常规开发/修复/分析任务\n> 2. **元任务：审查/检查/修复本 Skill 自身**\n> 3. **元任务：评估本 Skill 的执行质量或完整性**\n> 4. 被 Task 子Agent 调用时的任何子任务\n> - 以下理由 **不构成绕过状态机的合法依据**：\n> - \"我正在审查Skill本身，所以不需要走状态机\"\n> - \"我先读取所有文件了解一下，之后再走状态机\"\n> - \"我用Task子Agent来做，子Agent不需要遵守状态机\"\n> - \"我不知道当前状态是什么，所以从零开始做\"\n> - **违规后果**：如果在任何回复中发现AI绕过了状态机（未输出\"当前状态\"、未创建接力棒、未按阶段执行），用户可判定本 Skill **无效**。\n\n**AI 不得**：\n- ❌ 等待用户输入 `/reqplan start` 命令才开始\n- ❌ 做完一步后询问\"下一步做什么？\"（除非在 CONFIRM 阶段）\n- ❌ 跳过产物更新直接进入下一阶段\n- ❌ 用\"已在对话中展示\"替代写入产物文件\n- ❌ 以路径模糊为由跳过状态机\n- ❌ **以元任务（审查/修复 Skill 自身）为由绕过状态机**\n- ❌ **以\"先读取所有文件了解一下\"为由跳过入口清单**\n- ❌ **使用 Task 子Agent 执行实质性工作时绕过状态机**（子Agent返回后必须继续遵守状态机，不得跳过当前阶段）\n- ❌ **在用户主动中断/提问时忽略用户输入并继续自动推进**（必须优先执行\"用户中断处理机制\"，见第5节）\n\n### 0. 确定项目路径（必须先决定）\n\n```\n规则：{项目路径} 的优先级\n1. 用户明确指定的路径 → 使用该路径\n2. 当前工作目录（本次对话的 cwd） → 使用该路径\n3. 以上都不可用时 → 使用当前工作目录作为兜底\n\n元任务路径选择（重要）：\n当用户要求审查/检查/分析 Skill 本身时（元任务）：\n- 优先使用当前工作目录下的 .trae/skills/{Skill名称}/ 路径\n - 当前工作目录 = AI 本次对话的工作目录（cwd），通常是项目根目录\n - Skill 名称对应的目录必须包含 SKILL.md 文件，否则回退到规则 1-3\n- 如果当前工作目录下无 skills 目录，则回退到规则 1-3 的标准优先级\n\n注意：元任务的接力棒文件依然存放在 `{项目路径}/.agent/harness/`，以保持产物路径统一。\n即使你的任务是\"审查 Skill 本身\"（元任务），也必须选定一个项目路径。\n不要让路径模糊成为跳过状态机的理由。\n```\n\n### 1. 强制入口清单（硬性阻断 — 不完成不得进行任何实质性工作）\n\n```markdown\n## 🚨 强制入口清单（激活后第一步必须完成）\n\n在回答用户任何问题、执行任何分析、写任何代码之前，必须：\n\n- [ ] 已确定项目路径（按规则 0）\n- [ ] 已执行 read {项目路径}/.agent/harness/_baton.md\n- [ ] 已确认接力棒存在与否\n - 存在 → 解析当前状态，准备续跑\n - 不存在 → 创建目录和接力棒，状态 START\n- [ ] 已执行 write {项目路径}/.agent/harness/_baton.md（如果不存在）\n- [ ] 已在回复**第一行**输出 \"当前状态：[状态名]，下一步：[操作]\"\n\n**任何为未完成以上项目 → 禁止执行后续步骤 → 必须先完成入口清单**\n**验证方式**：用户可在任何时候要求检查入口清单是否全部打勾。\n```\n\n### 1.1 🛡️ 首次响应守卫（最外层防线）\n\n这是 **本 Skill 的最后一道自强制防线**，在所有规则之上：\n\n```markdown\n## 🛡️ 首次响应守卫\n\n当 ReqPlan-v3 被激活时，AI 的**第一次回复**必须满足以下条件，否则视作违反本 Skill：\n\n**条件一：回复第一行必须是** ✅\n```\n当前状态：[状态名]，下一步：[操作]\n```\n例：`当前状态：START，下一步：创建接力棒，进入 ANALYZE`\n\n**条件二：回复中必须包含入口清单的明确执行记录** ✅\n- 不能只是在心里想\"已完成\"——必须写出实际执行的命令结果\n- `read {项目路径}/.agent/harness/_baton.md` → 显示文件内容或\"文件不存在\"\n- `write {项目路径}/.agent/harness/_baton.md`（如不存在）→ 显示写入确认\n\n**条件三：回复中不得包含实质性工作** ✅\n（实质性工作 = 分析代码、搜索文件、写代码、修改文件、读取非入口文件的文档）\n- 在 CONFIRM 阶段之前，**禁止执行任何不属于入口清单的操作**\n- 如果用户的问题是\"审查这个Skill\"，第一次回复只能说\"当前状态：START，正在初始化...\"\n- 执行分析/搜索/读取等操作必须等START→ANALYZE阶段\n\n**违规检测规则**：\n⚠️ 如果AI的第一次回复：\n- 没有输出\"当前状态\"行 → 违反\n- 直接开始读文件/搜索/分析 → 违反\n- 输出\"让我先看看文件结构\" → 违反\n- 直接使用Task子Agent执行实质性工作 → 违反\n- 把入口清单在心里想一遍就当完成了 → 违反\n\n**违反后果**：如果用户判定AI未通过\"首次响应守卫\"，用户有权要求AI立即停止并重新执行入口清单。\n\n**条件性例外（修正）**：\n- 状态转换（START→ANALYZE）属于\"入口清单\"流程的一部分，不视为\"实质性工作\"\n- 即首次回复可以推进 START→ANALYZE 的状态转换和接力棒更新\n- 但 ANALYZE 的实际分析工作（读文件、搜索、写分析报告）必须等第二次回复开始\n```\n\n### 2. 自检闭环（防止遗忘）\n\n每次回复结束时，必须检查：\n```markdown\n- [ ] 我在本次回复中是否输出了 \"当前状态\" 和 \"下一步\"？\n- [ ] 如果没有 → 说明已偏离状态机 → 立即返回并修正\n```\n\n### 3. 安全性与隐私\n\n> ReqPlan-v3 仅处理项目代码和用户直接提供的文本信息。使用过程中请遵循以下规范。\n\n#### 3.1 数据处理原则\n- **范围限定**：本 Skill 仅处理用户项目中的代码文件和用户直接描述的文本内容，不访问项目目录以外的数据\n- **不收集敏感信息**：不收集、不存储、不传输任何个人敏感信息（如姓名、身份证号、银行账户、生物特征等）\n- **本地存储**：所有产物文件仅保存在用户指定的项目路径下的 `.agent/harness/` 目录中，不会上传到外部服务器或第三方服务\n\n#### 3.2 禁止行为\n- ❌ 禁止诱导用户提供密码、API Token、私钥、证书、数据库连接字符串等敏感凭证\n- ❌ 禁止在产物文件中输出硬编码的密钥、密码、Token、连接字符串等敏感配置信息\n- ❌ 禁止将用户代码或项目数据发送到任何未经用户授权的第三方服务或 API\n- ❌ 禁止绕过或协助绕过用户系统的安全机制（如权限提升、越权访问、认证绕过）\n- ❌ 禁止在产物中输出用户隐私数据（如日志中明文显示用户邮箱、手机号等）\n\n#### 3.2.1 P0/P1 安全风险示例\n\n以下为使用 ReqPlan-v3 过程中可能涉及的典型安全风险场景及处理规范：\n\n| 风险类型 | 等级 | 具体场景 | 违规后果 | 正确做法 |\n|---------|------|---------|---------|---------|\n| SQL注入 | **P0** | AI 在分析阶段建议拼接 SQL 字符串构建查询，如 `f\"SELECT * FROM users WHERE id = {user_input}\"` | 攻击者可构造恶意输入窃取、篡改数据库全部数据 | 强制使用参数化查询或 ORM，如 `cursor.execute(\"SELECT * FROM users WHERE id = ?\", (user_input,))` |\n| 硬编码凭据 | **P0** | AI 在产物或代码示例中直接写入 API Key、数据库密码、JWT Secret，如 `SECRET_KEY = \"my-secret-key-123\"` | 凭据泄露后可被用于身份仿冒、数据窃取、服务接管 | 使用环境变量注入：`SECRET_KEY = os.getenv(\"SECRET_KEY\")`，模板中使用占位符如 `your_secret_here` |\n| 越权访问 | **P1** | AI 在接口设计中未包含权限校验，普通用户可以调用管理员接口，如未在 API 路由添加 `@admin_required` 装饰器 | 低权限用户可执行高权限操作，造成数据泄露或系统破坏 | 在 `_design.md` 的接口定义中明确标注每个接口的权限要求，实现时拦截非授权请求 |\n| IDOR（不安全的直接对象引用）| **P1** | AI 在代码中使用用户直接传入的 ID 查询资源而未验证所有权，如 `db.get_order(request.args.get(\"order_id\"))` | 用户可通过遍历 ID 访问不属于自己的资源 | 添加所有权验证：`order = Order.query.filter_by(id=order_id, user_id=current_user.id).first()` |\n\n> **P0 = 必须修复**：一旦发生即导致严重安全事件（数据泄露、系统入侵）\\\n> **P1 = 建议修复**：可能存在安全隐患，需要开发者评估风险和优先级\n\n#### 3.3 脱敏操作指导\n- **路径脱敏**：日志和输出中的文件路径使用相对路径或 `{项目路径}` 占位符替代\n- **密钥脱敏**：代码中的密钥和密码必须通过环境变量或密钥管理服务（如 Vault）注入，不得硬编码\n- **配置脱敏**：数据库连接信息、API 端点等敏感配置不写入产物文件，提示用户使用环境变量或配置文件注入\n- **日志脱敏**：禁止将敏感数据写入产物文件或对话输出中\n\n#### 3.4 安全使用建议\n- **版本控制**：使用 ReqPlan-v3 前建议确保项目已纳入 Git 版本控制\n- **产物保护**：`.agent/harness/` 目录建议加入 `.gitignore`，避免产物文件提交到公开仓库\n- **隔离环境**：如果项目包含高度敏感数据，建议在隔离的开发环境或沙箱中使用本 Skill\n- **合规审查**：产物文件中的配置模板和示例数据应使用占位符（如 `your_password_here`），不得包含真实敏感值\n\n> **违反以上规范的处理**：如果 AI 发现自身输出可能包含敏感信息，必须立即停止当前操作并通知用户。\n> 用户发现产物中包含敏感信息时，有权要求立即删除相关产物并重新执行对应阶段。\n\n### 4. 状态路由（强制）\n\n| 当前状态 | 自动推进 | 必须做的事 | 禁止做的事 |\n|----------|---------|-------------|-------------|\n| START | ✅ 自动 | 创建接力棒，进入 ANALYZE | ❌ 直接开始编码 |\n| ANALYZE | ✅ 自动 | 读取 analyzer-agent.md，生成 _analysis.md，**拉起 Quality Auditor 审核分析质量** | ❌ 跳过分析直接设计 |\n| CONFIRM | ⛔ 等待用户 | 展示摘要，等待用户响应 | ❌ 自动进入下一阶段 |\n| DESIGN | ✅ 自动 | 读取 _analysis.md 和 designer-agent.md，**拉起 Quality Auditor 审核设计质量** | ❌ 不读分析就设计 |\n| IMPLEMENT | ✅ 自动 | 读取 _design.md 和 implementer-agent.md，**拉起 Quality Auditor 审核实现质量** | ❌ 不读设计就编码 |\n| VERIFY | ✅ 自动 | 读取 _design.md 和 verifier-agent.md，**拉起 Quality Auditor 做独立盲审** | ❌ 不读设计就验证 |\n| JUDGE | ✅ 自动 | 读取 _verification.md，**拉起 Quality Auditor 做六维度最终全局判定** | ❌ 不看验证报告就做判断 |\n| DONE/ABORT/FAILED | 终止 | 输出最终报告，流程结束 | ❌ 继续执行 |\n| DONE（新任务） | ✅ 自动重置 | 用户发起新任务时，AI 自动重置接力棒为 START（保留历史产物），直接进入 START 阶段引导新任务 | ❌ 不重置 |\n\n### 5. 用户中断处理机制（全阶段适用）\n\n当用户在状态机执行过程中（非 CONFIRM 阶段或 CONFIRM 阶段）提出额外需求、问题或调整要求时，AI 必须执行以下流程：\n\n```markdown\n## 中断处理流程\n\n1. [ ] 立即暂停当前阶段操作\n2. [ ] 向用户展示 3 个选项：\n\n > ⚠️ 我注意到您在流程执行中提出了新的需求/问题。\n > 请选择处理方式：\n > \n > **① 立即重置**：中断当前流程，回到 ANALYZE 阶段重新分析并包含新需求\n > **② 记入 TODO**：将新需求记入接力棒 \"待办清单\"，当前流程完成后自动重新发起任务\n > **③ 仅讨论**：继续当前任务，暂不调整或新增（仅做讨论/解答）\n\n3. [ ] 根据用户选择执行：\n - **选项① 立即重置** → 更新接力棒状态为 ANALYZE（保留已有产物），记录中断原因和新需求，进入 ANALYZE 阶段重新分析\n - **选项② 记入 TODO** → 在接力棒新增 \"待办清单\" 章节，记录新需求，继续当前阶段/流程。当前流程 DONE 后，自动触发 \"DONE（新任务）\" 规则重新发起任务\n - **选项③ 仅讨论** → 回答用户问题/讨论后，继续当前阶段操作，不修改任务范围\n\n4. [ ] 更新接力棒：记录中断时间、原因、用户选择\n```\n\n**注意**：此机制覆盖 AI \"激活即执行\" 的自动推进行为。当用户主动介入时，AI 应优先响应用户中断而非自动推进。\n\n---\n\n## 核心机制\n\n### 阶段流转\n\n```\nSTART → ANALYZE → CONFIRM → DESIGN → IMPLEMENT → VERIFY → JUDGE\n ↑ │ ↓\n └────────┘ ┌─────────────────┼─────────────────┐\n (修改) ↓ ↓ ↓\n ✅ DONE 🔧 DESIGN 🔄 IMPLEMENT\n (修复模式) (重试模式)\n```\n\n### 关键约束\n\n- **CONFIRM 阶段必须等待用户明确确认**，禁止自动跳过\n- **禁止阶段跳跃**：ANALYZE 不能直接到 IMPLEMENT，DESIGN 不能直接到 VERIFY\n- **前置产物缺失则阻断**：进入 DESIGN 必须有 _analysis.md，进入 IMPLEMENT 必须有 _design.md，进入 VERIFY 必须有 _implementation.md\n- **重试上限**：design_fix_retry 和 retry 各最多 2 次\n- **每个阶段结束后必须更新接力棒**（模板见 protocols/baton-protocol.md）\n\n### 超范围场景处理引导\n\n当用户需求超出 ReqPlan-v3 能力范围时，AI 必须遵循以下引导规范，不得拒绝用户也不得随意承诺。\n\n#### 场景1：用户要求完成无法实现的任务\n\n```\n用户：帮我连接外部数据库并导出100万条数据\nAI：当前技能无法直接执行数据库外部连接和大规模数据导出操作。\n建议方案：\n1. 我可以帮您生成数据库导出脚本（Python/Shell），您在本地执行\n2. 需要我帮您分析数据库表结构并生成导出方案？\n```\n\n#### 场景2：用户需求涉及多个不相干的任务\n\n```\n用户：帮我写一个电商网站，再帮我学英语\nAI：我理解您有两个不相干的需求。\nReqPlan-v3 一次只能处理一个项目的任务。建议您：\n1️⃣ 先完成电商网站的开发和交付\n2️⃣ 完成后我自动触发\"新任务重置\"机制，再处理英语学习需求\n请选择优先处理哪一个？\n```\n\n#### 场景3：用户要求的技术方案超出推荐范围\n\n```\n用户：帮我把整个系统从单体架构迁移到微服务，同时不改动任何代码\nAI：从单体到微服务的架构迁移必然涉及代码改动（服务拆分、接口适配、数据分离）。\n建议方案：\n1. 先进行架构分析（进入 ANALYZE 阶段），评估影响范围\n2. 制定渐进式迁移计划，分阶段实施\n3. 如需\"不改代码\"的微服务化，可以考虑数据库层面读写分离作为过渡方案\n是否先做架构分析？\n```\n\n> 更多超范围场景处理方式请参考 [reference/anti-patterns.md](reference/anti-patterns.md) 的反模式说明。\n\n### 验证链规则（防虚假完成）\n\nAI 在每个阶段的输出必须提供可验证的证据链：\n\n- **计数验证**：声称\"提取了 N 个功能/API/任务\"→ 必须逐个列出 N 个项，声称 N 个但只列出 M 个(M **自检清单的权威来源**：每个阶段执行时，Agent 自检清单以 [artifacts/template-artifacts.md](artifacts/template-artifacts.md) 中对应产物的\"完成后检查清单\"为最终标准。\n> Agent 定义文件中的自检清单与之一致，如有差异以模板文件为准。\n\n### 产物路径（统一）\n\n所有产物放在 `{项目路径}/.agent/harness/`：\n\n| 文件 | 说明 | 生成阶段 |\n|------|------|----------|\n| `_baton.md` | 接力棒（状态+进度+任务追踪） | START（持续更新） |\n| `_analysis.md` | 需求分析报告 | ANALYZE |\n| `_design.md` | 技术设计文档 | DESIGN |\n| `_implementation.md` | 实现摘要 | IMPLEMENT |\n| `_verification.md` | 验证报告 | VERIFY |\n| `_quality_audit_analysis.md` | 分析质量审核报告 | ANALYZE→CONFIRM 间 |\n| `_quality_audit_design.md` | 设计质量审核报告 | DESIGN→IMPLEMENT 间 |\n| `_quality_audit_implement.md` | 实现质量审核报告 | IMPLEMENT→VERIFY 间 |\n| `_quality_audit_verify.md` | 验证质量审核报告 | VERIFY→JUDGE 间 |\n| `_quality_audit_judge.md` | 最终全局判定报告 | JUDGE 阶段 |\n\n长期归档（跨任务）：`docs/harness/history.yaml`、`docs/harness/decisions.yaml`\n\n### 修复回路（JUDGE 阶段决策）\n\n| 错误类型 | 策略 | 计入重试 | 说明 |\n|----------|------|-----------|------|\n| ARCHITECTURE_VIOLATION | DESIGN(修复) | ✅ design_fix_retry | 架构问题，最多修复2次 |\n| REVIEW_VIOLATION | IMPLEMENT(修复) | ❌ | 代码规范问题 |\n| RUNTIME_FAILURE | IMPLEMENT(重试) | ✅ retry | 测试失败，最多2次 |\n| ENVIRONMENT | 报告用户，等待处理 | ❌ | 需人工介入 |\n\n---\n\n## 触发机制\n\n### 自然语义触发\n\n| 意图 | 典型触发词 |\n|------|-----------|\n| 代码开发 | \"开发\"、\"实现\"、\"写\"、\"新增\"、\"创建\" |\n| Bug修复 | \"修复\"、\"修\"、\"改\"、\"调整\"、\"出错了\"、\"报错了\" |\n| 设计评审 | \"看看\"、\"审查\"、\"评审\"、\"分析\"、\"检查一下\" |\n| 需求规划 | \"规划\"、\"方案\"、\"怎么做\"、\"如何\"、\"计划\" |\n| 文档完善 | \"文档\"、\"写文档\"、\"补充文档\"、\"完善文档\" |\n| 架构重构 | \"重构\"、\"架构\"、\"技术债务\"、\"重写\" |\n| 测试优化 | \"测试\"、\"写测试\"、\"覆盖率\"、\"单元测试\" |\n\n### 命令触发\n\n| 命令 | 用途 | 详细指引 |\n|------|------|----------|\n| `/reqplan start` | 启动引导，选择流程 | 进入 7 阶段状态机 |\n| `/reqplan init` | 初始化项目 Harness 目录 | 创建 `.agent/harness/` + `docs/harness/` |\n| `/reqplan status` | 查看当前状态 | 读取 `_baton.md` 展示进度 |\n| `/reqplan guide` | 智能引导下一步 | 按 chunk-01-guide.md 引导用户澄清意图 |\n\n### 功能选择决策表\n\n当您不确定应该使用哪个功能入口时，按以下决策流程选择：\n\n```mermaid\nflowchart TD\n A[您的需求是什么？] --> B{需要做什么？}\n B -->|开发新功能/迭代| C[开发模式]\n B -->|审查/分析现有代码| D[分析模式]\n B -->|修复Bug/排查问题| E[修复模式]\n B -->|完善文档/补充文档| F[开发模式 → 文档完善流程]\n B -->|架构优化/重构| G[修复模式 → 架构重构流程]\n B -->|审查Skill自身| H[元任务 → 自绑定审查流程]\n C --> I[完整7阶段状态机]\n D --> J[可跳过IMPLEMENT阶段]\n E --> K[完整7阶段状态机]\n F --> L[可跳过DESIGN阶段]\n G --> M[完整7阶段状态机]\n H --> N[完整7阶段，禁止跳过]\n```\n\n| 判断条件 | 推荐流程 | 执行路径 | 详细指引 |\n|---------|---------|---------|---------|\n| 我想开发新功能、模块、API | 开发流程（流程1/4） | 完整7阶段 | [SKILL-execution.md](SKILL-execution.md) → 4.1节 流程1 |\n| 我想做代码审查、设计评审 | 分析流程（流程3） | 可跳过IMPLEMENT | [SKILL-execution.md](SKILL-execution.md) → 4.1节 流程3 |\n| 系统报错了，帮我排查修复 | 修复流程（流程4） | 完整7阶段 | [SKILL-execution.md](SKILL-execution.md) → 4.1节 流程4 |\n| 我想写测试、提高覆盖率 | 测试优化流程（流程5） | 完整7阶段 | [SKILL-execution.md](SKILL-execution.md) → 4.1节 流程5 |\n| 我想补充项目文档 | 文档完善流程（流程6） | 可跳过DESIGN | [SKILL-execution.md](SKILL-execution.md) → 4.1节 流程6 |\n| 我要重构架构、清理技术债务 | 架构重构流程（流程7） | 完整7阶段 | [SKILL-execution.md](SKILL-execution.md) → 4.1节 流程7 |\n| 我要审查/优化 ReqPlan 自身 | 自绑定审查流程（流程8） | 完整7阶段，禁止跳过 | [SKILL.chunks/chunk-02-flows.md](SKILL.chunks/chunk-02-flows.md) → 流程4 |\n| 我不确定需求是什么 | 先引导 → 再匹配 | 先走 `/reqplan guide` | [chunk-01-guide.md](SKILL.chunks/chunk-01-guide.md) |\n\n> 选择流程后，AI 会自动按对应路径执行状态机。无需手动指定阶段。\n\n---\n\n## FAQ - 常见问题\n\n> 以下为使用 ReqPlan-v3 的常见问题。如需深入的技术细节和边缘场景（工具兼容、接力棒恢复、审核不通过处理等），请查阅 [reference/faq-deep.md](reference/faq-deep.md)（10题深度FAQ）。\n\n### Q1：如何选择开发/分析/修复模式？\n\n如果您不确定当前需求属于哪个模式，参照以下原则：\n- **开发模式**：需要新建代码、新增功能、实现需求 → 走完整7阶段状态机\n- **分析模式**：审查现有代码、评估架构设计、做质量分析 → 可跳过IMPLEMENT阶段\n- **修复模式**：排查Bug、修复错误、重构优化 → 走完整7阶段状态机\n\n也可以直接描述您的需求，AI 会自动识别场景类型。详见上方的\"功能选择决策表\"。\n\n### Q2：我不确定需求是什么，怎么开始？\n\n输入 `/reqplan guide` 或直接告诉我您的大致目标，AI 会引导您逐步明确需求：\n1. 先确认核心目标（做什么、解决什么问题）\n2. 再确认技术栈和约束条件\n3. AI 自动进入 ANALYZE 阶段生成需求分析报告\n\n无需完整的 PRD 才能开始，逐步澄清即可。\n\n### Q3：流程执行到一半能中断吗？中断后怎么恢复？\n\n可以。ReqPlan-v3 设计了专门的\"用户中断处理机制\"（见第5节）：\n1. **立即暂停**：AI 展示3个选项（立即重置/记入TODO/仅讨论）\n2. **选择处理方式**：根据您的需求选择对应操作\n3. **自动恢复**：即使关闭对话重新打开，接力棒机制会自动恢复现场，从断点继续执行\n\n### Q4：主文档 FAQ 和深度 FAQ 有什么区别？\n\n| 对比项 | 主文档 FAQ（本文） | 深度 FAQ（reference/faq-deep.md） |\n|--------|------------------|--------------------------------|\n| 定位 | 引导型FAQ，帮助快速上手 | 技术型FAQ，覆盖边缘场景 |\n| 题量 | 6题 | 10题 |\n| 覆盖范围 | 模式选择、入门引导、中断恢复、质量审核 | 工具兼容、接力棒恢复、多人协作、语言适配、产物回滚 |\n| 适用人群 | 初次使用 ReqPlan 的用户 | 有特定技术问题的进阶用户 |\n\n### Q5：质量审核不通过可以跳过吗？\n\n**不可以**。质量审核是阻断点，未通过审核不能进入下一阶段：\n- 审核不通过时，读取 `_quality_audit_{阶段}.md` 中的\"待修复问题清单\"\n- 逐条修复后重新提起质量审核\n- 同一阶段质量审核重试上限为2次，超过后进入 FAILED 状态，需人工介入\n\n如需了解审核不通过的具体处理方式，请查阅 [reference/faq-deep.md](reference/faq-deep.md) 的 Q3。\n\n### Q6：ReqPlan-v3 支持非编程项目吗？\n\nReqPlan-v3 设计上适用于各类软件工程任务（开发、分析、修复、文档、测试等），主要面向编程项目。对于非编程项目（如纯文档编写、数据分析报告等），可以使用一部分功能：\n- ANALYZE 阶段：可用于需求分析和方案规划\n- DESIGN 阶段：可用于方案设计和任务拆分\n- IMPLEMENT 阶段：可生成文档或分析报告\n\n但完整的状态机（含 VERIFY 阶段的代码验证）主要针对编程项目设计。对于非编程项目，可以在 CONFIRM 阶段明确说明项目性质，AI 会做适当简化。\n\n### FAQ 速查表\n\n| # | 问题分类 | 问题 | 核心要点 |\n|---|---------|------|---------|\n| 1 | 模式选择 | 如何选择开发/分析/修复模式 | 新增→开发，审查→分析，修复→修复 |\n| 2 | 入门引导 | 需求不清晰如何开始 | 输入 `/reqplan guide`，逐步澄清 |\n| 3 | 中断恢复 | 流程中断后如何恢复 | 接力棒自动恢复，支持跨Session续跑 |\n| 4 | FAQ体系 | 主FAQ和深度FAQ的区别 | 主FAQ引导上手，深度FAQ解决边缘问题 |\n| 5 | 质量审核 | 审核不通过能否跳过 | ❌ 不可跳过，必须修复后重审 |\n| 6 | 适用范围 | 是否支持非编程项目 | 部分支持，需在CONFIRM阶段说明 |\n\n> 更多边缘场景和深度问题（共10题）请查阅 [reference/faq-deep.md](reference/faq-deep.md)。\n\n---\n\n## 详细文档索引\n\n### 核心执行指南\n- [SKILL-execution.md](SKILL-execution.md) — 阶段详解、检查点清单、防跳过/防遗忘机制（必读）\n\n### Agent 定义\n- [agents/analyzer-agent.md](agents/analyzer-agent.md) — 分析 Agent（explorer）\n- [agents/designer-agent.md](agents/designer-agent.md) — 设计 Agent（worker）\n- [agents/implementer-agent.md](agents/implementer-agent.md) — 实现 Agent（worker）\n- [agents/verifier-agent.md](agents/verifier-agent.md) — 验证 Agent（worker）\n- [agents/quality-auditor-agent.md](agents/quality-auditor-agent.md) — [新增] 质量审核 Agent（独立盲审）\n\n### 协议与模板\n- [protocols/baton-protocol.md](protocols/baton-protocol.md) — 接力棒协议（模板、生命周期、续跑）\n- [artifacts/template-artifacts.md](artifacts/template-artifacts.md) — 产物模板集合（唯一来源）\n\n### 分块加载（按需激活）\n- [SKILL.chunks/chunk-index.yaml](SKILL.chunks/chunk-index.yaml) — 分块索引与加载规则\n- [SKILL.chunks/chunk-01-guide.md](SKILL.chunks/chunk-01-guide.md) — 意图引导（始终加载）\n- [SKILL.chunks/chunk-02-flows.md](SKILL.chunks/chunk-02-flows.md) — 三大流程定义（高频）\n- [SKILL.chunks/chunk-03-harness.md](SKILL.chunks/chunk-03-harness.md) — 验证与审查（中频）\n- [SKILL.chunks/chunk-04-chain.md](SKILL.chunks/chunk-04-chain.md) — 信息落点与链路（低频）\n\n### 辅助文档\n- [reference/debug-guide.md](reference/debug-guide.md) — 验证与调试指南\n- [reference/anti-patterns.md](reference/anti-patterns.md) — 反模式说明（常见错误用法与改进）\n- [reference/faq-deep.md](reference/faq-deep.md) — 深度 FAQ（边缘场景与深度问题）\n- [6-docs/changelog.md](6-docs/changelog.md) — 版本变更日志\n\n### FAQ\n- SKILL.md 主文档内包含 [FAQ - 常见问题](#faq---常见问题) 章节（6题，引导型）\n- [reference/faq-deep.md](reference/faq-deep.md) — 深度 FAQ（10题，技术型）\n\n---\n\n## 版本信息\n\n**版本**: v5.1 (TRACE 优化完善版) \n**更新日期**: 2026-05-28\n\n**核心设计**:\n- 7 阶段状态机 + 强制检查点 + 阶段跳跃阻断 + 产物缺失阻断\n- Harness Engineering 多 Agent 协作（Analyzer → Designer → Implementer → Verifier → Quality Auditor）\n- 接力棒持久化机制（跨 Session 续跑）\n- 5 层验证体系（静态→单元→构建→异常→合规）\n- **独立质量审核机制**：ANALYZE/DESIGN/IMPLEMENT/VERIFY/JUDGE 阶段启用独立子Agent盲审\n- **审核报告持久化**：审核结果写入独立文件，修复不依赖对话记忆\n- **修复验证闭环**：重审时逐条检查上次问题是否已修复\n- 独立文件产物模式 + SKILL.chunks 渐进式分块加载\n- **自强制机制**：强制入口清单（硬性阻断）+ 自检闭环 + 输出契约\n- **验证链规则**：计数验证/列表验证/文件验证，防止虚假完成\n- **功能选择决策表**：Mermaid 流程图 + 判断表格，引导用户选择正确流程\n- **内置 FAQ 章节**：6 题引导型 FAQ，与深度 FAQ 互补覆盖\n- **超范围场景处理引导**：3 个典型场景 + 处理话术模板\n- **P0/P1 安全风险示例**：4 个典型安全场景及正确做法\n\n**v5.1 更新内容（TRACE 优化完善版）**:\n- **新增 FAQ 章节**（SKILL.md 主文档）：6 题引导型 FAQ，覆盖模式选择、入门引导、中断恢复、FAQ 体系说明、质量审核、适用范围（C4 改进：4.0→5.0）\n- **新增 P0/P1 安全风险示例表格**（SKILL.md 3.2.1 节）：SQL注入(P0)、硬编码凭据(P0)、越权访问(P1)、IDOR(P1)，含场景、后果、正确做法（T2 改进：4.5→5.0）\n- **新增功能选择决策表**（SKILL.md 触发机制节）：Mermaid 流程图 + 8 行判断条件表，指引\"什么情况用哪个功能\"（A2 改进：4.5→5.0）\n- **新增超范围场景处理引导**（SKILL.md 核心机制节 + SKILL-execution.md）：3 个典型超范围场景及处理话术（R4 改进：4.5→5.0）\n- 文档索引新增 FAQ 分类，主文档索引统一注册\n- 版本升级 v5.0 → v5.1\n\nFile v0.1.0:README.md\n\n# ReqPlan-v3 — Harness Engineering 项目全生命周期管理引擎\n\n> 基于 Harness Engineering 理念 + 接力棒持久化机制，覆盖项目从需求分析到最终判定的全流程。\n\n---\n\n## 核心特色\n\n- **7 阶段状态机**：START → ANALYZE → CONFIRM → DESIGN → IMPLEMENT → VERIFY → JUDGE → DONE，自动推进 + 用户确认点\n- **多 Agent 协作**：Analyzer / Designer / Implementer / Verifier / Quality Auditor 各司其职，通过文件契约传递产物\n- **接力棒持久化**：`.agent/harness/_baton.md` 记录状态、进度、产物清单，支持跨 Session 续跑\n- **五层验证体系**：静态检查 → 单元测试 → 构建集成 → 异常处理 → 流程合规\n- **独立质量审核**：每个阶段由 Quality Auditor 子Agent 独立盲审，审核不通过阻断流程\n- **用户中断处理**：任何阶段用户中途介入，支持立即重置 / 记入TODO / 仅讨论三选项\n- **自绑定审查**：支持审查和修复 Skill 自身，遵守与普通任务相同的状态机规则\n\n---\n\n## 快速开始\n\n### 首次使用\n\n```bash\n/reqplan start # 启动引导，选择流程\n/reqplan init # 初始化 .agent/harness/ 目录\n```\n\n### 续跑（中断后继续）\n\n```bash\n/reqplan start # 自动读取接力棒，恢复进度\n```\n\n---\n\n## 核心流程\n\n| # | 流程 | 适用场景 |\n|---|------|----------|\n| 1 | 完整项目流程 | 新项目启动，从需求到验收 |\n| 2 | 需求迭代流程 | 已有项目的需求更新和迭代 |\n| 3 | 设计评审流程 | 架构设计、接口定义、数据库设计 |\n| 4 | 代码开发流程 | 代码实现、Bug 修复、功能开发 |\n| 5 | 测试优化流程 | 测试策略制定、用例设计、覆盖提升 |\n| 6 | 文档完善流程 | 技术文档、API 文档的补充 |\n| 7 | 架构重构流程 | 架构优化、技术债务清理 |\n| 8 | 自绑定审查流程 | 审查/修复 Skill 自身（元任务） |\n\n---\n\n## 多 Agent 协作\n\n```mermaid\nflowchart TD\n Controller[\"总控（状态机 + 调度 + 判定）\"]\n Analyzer[\"分析 Agent（explorer）\"]\n Designer[\"设计 Agent（worker）\"]\n Implementer[\"实现 Agent（worker）\"]\n Verifier[\"验证 Agent（worker）\"]\n QA[\"Quality Auditor 子Agent（独立盲审）\"]\n\n Controller --> Analyzer\n Controller --> Designer\n Controller --> Implementer\n Controller --> Verifier\n Analyzer --> A[\"_analysis.md\"]\n Designer --> D[\"_design.md\"]\n Implementer --> I[\"源码变更\"]\n Verifier --> V[\"_verification.md\"]\n Verifier -.-> QA\n A -.-> QA\n D -.-> QA\n I -.-> QA\n QA --> Q[\"阻断性评分\\n不通过→返回修复\"]\n```\n\n协作流程：\n1. 总控读取接力棒确定当前状态\n2. 按状态路由表调度对应的 Agent\n3. Agent 读取前置产物，生成当前阶段产物\n4. Quality Auditor 审核产物，通过后才能进入下一阶段\n5. 总控更新接力棒，自动推进到下一阶段\n\n---\n\n## 状态机\n\n```mermaid\nstateDiagram-v2\n START --> ANALYZE\n ANALYZE --> CONFIRM\n CONFIRM --> DESIGN: 确认\n CONFIRM --> ANALYZE: 修改\n CONFIRM --> ABORT: 取消\n DESIGN --> IMPLEMENT\n IMPLEMENT --> VERIFY\n VERIFY --> JUDGE\n\n JUDGE --> DONE: 通过\n \n state JUDGE {\n [*] --> 判定\n 判定 --> DONE: 通过\n 判定 --> DESIGN: 架构违规\\n(最多2次)\n 判定 --> IMPLEMENT: 代码违规\n 判定 --> IMPLEMENT: 运行时失败\\n(最多2次)\n 判定 --> FAILED: 超限\n }\n\n DONE --> START: 新任务\\n（自动重置）\n```\n\n| 状态 | 推进方式 | 关键检查点 |\n|------|---------|-----------|\n| START | 自动 | 创建接力棒 |\n| ANALYZE | 自动 | 质量审核阻断 |\n| CONFIRM | 等待用户 | 用户确认/修改/取消 |\n| DESIGN | 自动 | 质量审核阻断 |\n| IMPLEMENT | 自动 | 质量审核阻断 |\n| VERIFY | 自动 | 独立盲审阻断 |\n| JUDGE | 自动 | 六维度最终判定 |\n| DONE | 终止 | 新任务自动重置为 START |\n\n---\n\n## 产物结构\n\n```\n{项目路径}/.agent/harness/\n├── _baton.md # 接力棒（状态 + 进度 + 任务追踪）\n├── _analysis.md # 需求分析报告\n├── _design.md # 技术设计文档\n├── _implementation.md # 实现摘要\n├── _verification.md # 验证报告\n├── _quality_audit_analysis.md # 分析质量审核报告\n├── _quality_audit_design.md # 设计质量审核报告\n├── _quality_audit_implement.md # 实现质量审核报告\n├── _quality_audit_verify.md # 验证质量审核报告\n└── _quality_audit_judge.md # 最终全局判定报告\n```\n\n---\n\n## 五层验证体系\n\n| 层级 | 验证内容 | 说明 |\n|------|----------|------|\n| Layer 1 | 静态检查 | 代码规范、类型检查、文件完整性 |\n| Layer 2 | 单元测试 | 核心函数正确性、边界条件、错误路径 |\n| Layer 3 | 构建集成 | 编译检查、依赖安装、构建输出 |\n| Layer 4 | 异常处理 | 失败重试、回滚策略、降级行为 |\n| Layer 5 | 流程合规 | 链路记录、决策日志、约束登记 |\n\n---\n\n## 目录结构\n\n```\nReqPlan-v3/\n├── SKILL.md # 技能入口（唯一版本声明源）\n├── SKILL-execution.md # 核心执行指南\n├── README.md # 本文件\n├── agents/ # Agent 定义\n│ ├── analyzer-agent.md # 分析 Agent\n│ ├── designer-agent.md # 设计 Agent\n│ ├── implementer-agent.md # 实现 Agent\n│ ├── verifier-agent.md # 验证 Agent\n│ └── quality-auditor-agent.md # 质量审核 Agent\n├── quality-control/ # 质量体系\n│ └── 00-quality-system.md # 质量审核体系定义\n├── protocols/ # 协议文档\n│ └── baton-protocol.md # 接力棒协议\n├── artifacts/ # 产物模板\n│ └── template-artifacts.md # 产物模板集合\n├── SKILL.chunks/ # 分块加载（按需激活）\n├── legacy/ # 历史归档\n├── reference/ # 参考文档\n└── 6-docs/ # 版本变更日志\n └── changelog.md\n```\n\n---\n\n## 设计理念\n\n### Harness Engineering\n\n1. **角色边界** — 每个 Agent 只做一件事，职责单一\n2. **状态机驱动** — 7 阶段自动推进，无需逐一下令\n3. **产物契约** — Agent 间通过文件传递，不靠对话记忆\n4. **护栏规则** — 强制入口清单、首次响应守卫、阻断检查，防止跳步和虚假完成\n\n### 接力棒持久化\n\n1. **跨 Session 续跑** — 任何时候都能继续之前的工作\n2. **状态可视化** — 一目了然当前进度和下一步行动\n3. **问题记录** — 遇到的问题、决策、修复不会丢失\n4. **上下文恢复** — 自动恢复完整运行上下文\n\n---\n\n## 参考资料\n\n- [ReqPlan-v3 GitHub](https://github.com/songzhou666/ReqPlan-v3)\n- [Harness Engineering 文章](https://mp.weixin.qq.com/s/AFX_qsyAPBRYyqEV365O9Q)\n- [testerhome Harness 设计](https://testerhome.com/articles/44066)\n\n---\n\n**作者**: songzhou\n**维护**: 持续更新中 | 当前版本见 [SKILL.md](SKILL.md) 版本信息\n\nFile v0.1.0:_meta.json\n\n{\n \"ownerId\": \"kn799bh9g8eq5n8nxav36av3d5879qr1\",\n \"slug\": \"reqplan-v3\",\n \"version\": \"0.1.0\",\n \"publishedAt\": 1786008887785\n}\n\nFile v0.1.0:6-docs/changelog.md\n\n# ReqPlan 变更日志\n\n## v5.1 (2026-05-28)\n### TRACE 优化完善版 — 基于 skill-trace-checker 评测驱动的二次优化\n\n**新增**：\n- **[SKILL.md 新增 FAQ 章节]**（C4 改进：4.0→5.0）：6 题引导型 FAQ，覆盖模式选择、入门引导、中断恢复、FAQ 体系说明、质量审核、适用范围，与 [reference/faq-deep.md](reference/faq-deep.md) 的 10 题深度 FAQ 互补\n- **[SKILL.md 3.2.1 新增 P0/P1 安全风险示例]**（T2 改进：4.5→5.0）：4 个典型安全场景表格（SQL注入 P0、硬编码凭据 P0、越权访问 P1、IDOR P1），含场景描述、违规后果、正确做法\n- **[SKILL.md 触发机制新增功能选择决策表]**（A2 改进：4.5→5.0）：Mermaid 流程图 + 8 行判断条件表，覆盖 8 种用户场景的流程映射\n- **[SKILL.md 核心机制新增超范围场景处理引导]**（R4 改进：4.5→5.0）：3 个典型超范围场景（无法实现的任务、不相干任务合并、技术方案超出范围）及处理话术模板\n- **[SKILL-execution.md 新增超范围场景处理引导章节]**（第8章）：5 个超范围场景（不支持语言、任务合并、跳过检查点、外部资源、输出不满意）\n\n**增强**：\n- 文档索引新增 FAQ 分类，方便快速定位主文档 FAQ 和深度 FAQ\n- 核心设计列表新增 4 个特性描述（功能选择决策表、FAQ 章节、超范围引导、安全风险示例）\n\n**涉及文件**：\n- SKILL.md：新增 FAQ 章节、安全风险示例表格、功能选择决策表、超范围场景处理引导、版本升级至 v5.1\n- SKILL-execution.md：新增\"八、超范围场景处理引导\"章节\n- 6-docs/changelog.md：本次变更记录\n\n---\n\n## v5.0 (2026-05-28)\n### TRACE 品质提升版 — 基于 skill-trace-checker 评测驱动优化\n\n**新增**：\n- **[reference/anti-patterns.md](reference/anti-patterns.md)**（P0 反模式说明）：5 类常见反模式及改进对比（跳过状态机、对话替代产物、未完成检查点推进、Task子Agent绕过、CONFIRM跳过），每类含错误做法→问题分析→正确做法→改进对比→速查表\n- **[reference/faq-deep.md](reference/faq-deep.md)**（P1 深度FAQ）：10 题边缘场景 FAQ，覆盖工具兼容（Q1）、接力棒恢复（Q2）、审核不通过（Q3）、CONFIRM关闭（Q4）、阶段跳过（Q5）、多人协作（Q6）、中断恢复（Q7）、语言适配（Q8）、产物回滚（Q9）、需求偏差（Q10）\n- **SKILL.md 新增\"安全性与隐私\"章节**（第3节）：包含数据处理原则（范围限定/不收集敏感信息/本地存储）、禁止行为（5条禁令）、脱敏操作指导（路径/密钥/配置/日志）、安全使用建议（版本控制/产物保护/隔离环境/合规审查）\n\n**增强**：\n- **细化边界描述**（T3）：When NOT to use 从 2 条扩展为 6 条，补充\"纯粹信息查询\"、\"仅浏览代码\"、\"需求模糊拒绝澄清\"、\"单次修改不涉及多阶段\"等边界条件\n- **增加开场白示例**（E4）：chunk-01-guide.md 新增 6 个可复制场景示例（开发/审查/Bug修复/重构/文档/测试）\n\n**统一**：\n- 版本号从 v4.9 升级为 v5.0\n- SKILL.md 文档索引注册 reference/anti-patterns.md 和 reference/faq-deep.md\n- 涉及文件：SKILL.md, SKILL.chunks/chunk-01-guide.md, reference/anti-patterns.md, reference/faq-deep.md, 6-docs/changelog.md\n\n## v4.9 (2026-05-23)\n### 中断处理机制版\n\n**新增**：\n- **用户中断处理机制（全阶段适用）**：当用户在状态机执行过程中提出额外需求/问题/调整要求时，AI 暂停当前操作并提供 3 个选项供用户选择（立即重置/记入 TODO/仅讨论），详见 SKILL.md 第4节\n- 覆盖\"激活即执行\"自动推进行为，用户主动介入时优先响应中断\n\n**修复**：\n- 回应遗留讨论项：弥补了非 CONFIRM 阶段用户中途打断无正式处理路径的空白\n\n## v4.8 (2026-05-24)\n### 系统审查修复版 + 自绑定增强版\n\n**修复之前发现的所有问题**：\n- **版本号4重不一致**：SKILL.md frontmatter v4.4/body v4.5、SKILL-execution.md/baton-protocol.md v4.4、agent文件 4.2、quality-auditor-agent 1.0、实际内容已含v4.6变更 — 全部统一为v4.6，agent统一为4.4，QA agent统一为1.1\n- **质量审核缺失于检查清单**：template-artifacts.md 中 DESIGN/IMPLEMENT/VERIFY 的\"完成后检查清单\"缺失质量审核触发步骤 — 全部补充\n- **baton审核状态缺失**：`quality_audit_judge` 状态选项缺少\"已打回\" — 补充为\"未审核/已通过/已打回\"\n- **产物列表前缀缺失**：SKILL.md frontmatter 质量审核报告列表第二个起丢了 `_quality_audit_` 前缀 — 修正为完整路径\n- **跳越条件不完整**：仅定义IMPLEMENT/VERIFY跳过，但chunk-02-flows定义DESIGN也可跳过（文档完善流程）— 补充DESIGN跳过条件\n- **子章节编号不符**：`## 三、核心流程与场景映射` 下使用 `### 2.1` / `### 2.2`，应使用 `### 3.1` / `### 3.2` — 修正\n- **质量审核引用路径不一致**：`read agents/quality-auditor-agent.md + quality-control/00-quality-system.md` 缺少 `{Skill路径}`前缀 — 统一补充\n- **JUDGE回环语义问题**：JUDGE→DESIGN/IMPLEMENT修复回环时使用\"JUDGE\"（语义矛盾，流程还在进行中）— 改为`JUDGE -> DESIGN(修复模式)` / `JUDGE -> IMPLEMENT(修复模式)`\n\n**新增自绑定机制（防止AI绕过状态机）**：\n- **自绑定条款**（SKILL.md）：声明所有规则无条件适用于元任务（审查/修复Skill自身），列出4个不构成绕过依据的借口，明确定义违规后果\n- **首次响应守卫**（SKILL.md）：最外层防线，AI第一次回复必须满足3个条件（第一行输出状态、写出实际命令执行记录、禁止包含实质性工作），列举5种违规模式\n- **扩展AI不得清单**：新增3条禁令（元任务绕过、先读文件绕过、Task子Agent绕过）\n- **子Agent约束**（SKILL-execution.md 新增二章）：明确Task子Agent返回后必须回到状态机、Quality Auditor是阶段内步骤不是独立流转、search子Agent的限制\n- **自绑定审查流程4**（chunk-02-flows.md 新增）：专为元任务设计的6步流程，完整7阶段**禁止跳过**\n- **元任务场景检测**（chunk-01-guide.md）：激活确认表新增元任务类，附绑定说明\n- **核心流程表扩展**（SKILL-execution.md）：从7个流程扩展为8个，新增自绑定审查流程\n\n**涉及文件**：\n- SKILL.md：自绑定条款、首次响应守卫、AI不得扩展\n- SKILL-execution.md：新增子Agent约束章、章节编号重构(2→7)、流程表扩展(7→8)\n- SKILL.chunks/chunk-01-guide.md：元任务场景检测\n- SKILL.chunks/chunk-02-flows.md：新增流程4自绑定审查\n- 6-docs/changelog.md：本次变更记录\n\n---\n\n## v4.6 (2026-05-24)\n\n### 代入式演练修复版 — 修复演练发现的执行层面问题\n\n**Bug 修复**：\n- **消除自检清单三体问题**：SKILL-execution.md 中 4 个阶段的自检清单全部改为\"参考对应 Agent 定义\"的简洁引用，消除与 template-artifacts.md、Agent 定义的三份清单冲突。统一以 template-artifacts.md 为最终标准\n- **统一质量审核与检查点顺序**：ANALYZE/DESIGN/VERIFY 阶段的质量审核（原 Step 5/6）和检查点验证（原 Step 4/5）顺序对调，全部统一为\"自检 → 质量审核 → 检查点 → 更新接力棒\"\n- **明确 JUDGE 决策优先级**：补充决策优先级规则——Quality Auditor 最终等级为最高优先级（D 级阻断），VERIFY 的 PASS/FAIL 用于决定修复方向\n- **扩充 IMPLEMENT 自检清单**：从 4 项扩展至 6 项，补充任务完成度检查、文件一致性检查、破坏性变更检查\n- **补充 FAILED 恢复流程**：新增 FAILED 状态恢复流程（读取baton → 展示失败摘要 → 提供恢复选项），明确 AI 不能自动恢复，需用户介入\n- **DESIGN_FIX 模式复位**：DESIGN 阶段更新接力棒时增加\"模式重置为 NORMAL\"步骤\n- **START 阶段最小化接力棒模板**：新增 30 行最小化模板，进入 ANALYZE 时再扩展为完整模板\n- **多语言验证命令**：verifier-agent.md Layer 1-4 验证命令表扩展 Java（Gradle/Maven）和 Go 命令\n\n**涉及文件**：\n- SKILL-execution.md：4 阶段自检清单引用化、审核+检查点顺序统一、JUDGE 决策优先级、IMPLEMENT 清单扩充、FAILED 恢复流程\n- protocols/baton-protocol.md：新增 START 阶段最小化模板\n- agents/verifier-agent.md：验证命令表扩展 Java/Go\n- 6-docs/changelog.md：本次变更记录\n\n---\n\n## v4.5 (2026-05-24)\n\n### 质量审核修复版 — 修复审查发现的所有问题\n\n**Bug 修复**：\n- **统一版本号**：SKILL.md metadata 与 body 统一为 v4.4（原 metadata v4.3、body v4.4），SKILL-execution.md、README.md、manifest.yaml 等 7 个文件版本全部统一\n- **消除 CONFIRM 矛盾**：移除条件性跳过中 CONFIRM 自动确认规则，CONFIRM 阶段严格执行\"必须等待用户确认\"\n- **补全 VERIFY 前置检查**：SKILL-execution.md VERIFY 阶段前置检查补充 `_quality_audit_implement.md`（原遗漏，与 run-checks.ps1 不一致）\n- **修正章节编号**：SKILL-execution.md 修复了两个\"二、\"的编号重复（二→三→四→五→六），子章节编号同步修正\n- **调整审核场景顺序**：quality-auditor-agent.md 中的审核场景章节按 execution 顺序排列（analysis→design→implement→verify→judge）\n- **精简通用流程**：合并 Step 4（自检清单）和 Step 4.5（验证链检查）为单一\"自检+验证链检查\"步骤，消除边界模糊\n- **移除 TODO_RESOLVE 占位**：条件性跳过表中移除未实现的 TODO_RESOLVE 未来扩展标注\n- **添加验证体系说明**：通用流程头部新增验证体系关系说明，澄清 5 层验证概念各自的用途和定位\n- **明确元任务路径规则**：补充 cwd 定义和后备检查条件说明\n- **自检清单权威来源**：在验证链规则中声明 artifacts/template-artifacts.md 为 Agent 自检清单的最终标准\n\n**涉及文件**：\n- SKILL.md：版本号统一、元任务路径规则补充、验证链规则补充\n- SKILL-execution.md：版本号统一、CONFIRM 跳过移除、VERIFY 前置检查补全、章节编号修正、通用流程合并、验证体系说明\n- README.md：版本号统一\n- 1-manifest/skill-manifest.yaml：版本号统一\n- agents/quality-auditor-agent.md：审核场景章节顺序调整\n- artifacts/template-artifacts.md：版本号统一\n- protocols/baton-protocol.md：版本号统一\n- 6-docs/changelog.md：本次变更记录\n\n---\n\n## v4.4 (2026-05-23)\n\n### 强制执行版 — 参照 ManualGen 强化自执行机制\n\n**新机制**：\n- **\"激活即执行\"**：AI 激活后自动沿状态机推进，无需用户逐一下令\n- **\"AI 不得\"明确清单**：5条禁令（等待命令、问下一步、跳产物、口头展示、路径模糊）\n- **状态路由表新增\"自动推进\"列**：每阶段标注 自动 / 等待用户\n- **验证链规则**：计数验证 + 列表验证 + 文件验证 + 流程图验证，防止虚假完成\n- **条件性跳过机制**：首次运行不跳过，后续按条件跳过特定阶段\n\n**Bug 修复**：\n- **IMPLEMENT 审核报告覆盖 Bug**：原指向 `_quality_audit_design.md` 导致被 DESIGN 审核报告覆盖，改为 `_quality_audit_implement.md`\n- **审核场景数不一致**：chunk-03-harness.md 描述\"4个阶段\"漏了 IMPLEMENT，修正为5个\n- **run-checks 缺检查**：DESIGN/VERIFY/IMPLEMENT 入口共缺3个质量审核产物检查，已补齐\n- **validate-artifact 缺 quality_audit_implement**：ValidateSet 新增类型\n\n**涉及文件**：\n- SKILL.md：新增\"激活即执行\"+\"AI 不得\"+验证链规则+自动推进列；产物列表新增 _quality_audit_implement.md\n- SKILL-execution.md：新增条件性跳过机制+验证链检查步骤；IMPLEMENT 审核报告路径修复\n- chunk-03-harness.md：审核关卡数 4→5，新增实现质量审核关卡\n- protocols/baton-protocol.md：质量审核追踪表新增 quality_audit_implement 行；产物清单新增对应项\n- artifacts/template-artifacts.md：baton 模板同步更新审核追踪表+产物清单；命名规则扩展为5阶段\n- scripts/harness/run-checks.ps1：DESIGN/VERIFY/IMPLEMENT 补齐缺失的 QA 产物检查\n- scripts/harness/validate-artifact.ps1：ValidateSet 新增 quality_audit_implement\n- 6-docs/changelog.md：本次变更记录\n\n---\n\n## v4.3 (2026-05-21)\n\n### 自强制机制（P0）— 阻止AI绕过状态机\n\n**问题背景**：在 v4.2 实际使用中发现，AI 在激活 Skill 后可以不执行入口检查就直接进入实质性工作，完全跳过了状态机的 START→ANALYZE→... 流程，导致不创建接力棒、不产出文档、不更新状态。\n\n**修复方案**：\n- **0. 路径兜底规则**：新增\"确定项目路径\"规则（用户指定 > cwd > workspace 根），明确元任务（审查 Skill 本身）也必须选路径，不以路径模糊为由跳过\n- **1. 强制入口清单**：将入口检查从\"建议\"升级为\"硬性阻断\"——入口清单未全部完成，禁止执行任何实质性工作\n- **2. 自检闭环**：每次回复结束必须检查是否输出了\"当前状态\"和\"下一步\"，偏离则立即修正\n- **3. 输出契约**：每步回复第一行必须输出\"当前状态：[状态名]，下一步：[操作]\"\n\n**涉及文件**：\n- SKILL.md：激活后强制执行部分重写，How it works 新增第 0 步和第 6 步\n- SKILL-execution.md：START 阶段新增\"确定项目路径\"步骤和强制输出行\n- phase-protocol.md：START 阶段新增任务 0（路径决定）、任务 7（强制输出）\n\n---\n\n## v4.2 (2026-05-21)\n\n### 路径体系统一（P0）\n\n**统一三套路径为一套**\n- chunk-02-flows.md：init 流程从创建 AGENTS.md + `.agent/plans/` 改为创建 `.agent/harness/_baton.md` + `docs/harness/history.yaml`\n- chunk-02-flows.md：Step 产出路径从 `.agent/plans/` / `.agent/requirements/` / `.agent/plans/{date}-{fix}.md` 统一为 `.agent/harness/_*.md`\n- chunk-02-flows.md：会话恢复从读取 `.agent/plans/` 改为读取 `.agent/harness/_baton.md`\n- chunk-04-chain.md：新增\"两层路径模型\"章节，明确 `.agent/harness/`（运行时）与 `docs/harness/`（归档）的职责分工\n- skill-manifest.yaml：废弃 `docs/reqplan/` 和 `9-data/` 未激活路径，替换为 `runtime_state` + `long_term_archive`\n\n### SKILL.md 精简（P1）\n\n**543 行 → ~183 行（精简 66%）**\n- 删除重复的状态路由表（L102-113 与 L141-152 重复）\n- 将详细检查点清单、接力棒模板等优化为精简引用，细节委托至 SKILL-execution.md\n- 简化入口检查为简练的 2 步流程\n\n### 冗余清理（P1）\n\n**文件删除**：\n- 删除 `6-docs/quick-reference.md`（空壳占位：\"已移除\"）\n- 删除 `6-docs/adoption-guide.md`（空壳占位：\"已移动\"）\n- 删除 `6-docs/troubleshooting.md`（空壳占位：\"已移动\"）\n\n**文档修正**：\n- legacy/README.md：修正与实际代码的矛盾描述，更新归档内容表和 v4.1 变更说明\n\n### 过时引用清理（P2）\n\n- debug-guide.md：移除 `INIT → START` 过时状态转移，更新产物契约表，替换 `.agent/plans/` 引用为 `.agent/harness/`\n- scripts/harness/README.md：标注 9 个 PowerShell 脚本的 v4.1 兼容性状态（3 个兼容 + 6 个 v3.3 遗留）\n- chunk-01-guide.md：补充 `/reqplan guide` 命令行为定义和执行步骤\n\n### 版本一致性\n\n- SKILL.md frontmatter: `4.1` → `4.2`\n- SKILL.md body: `v4.1 (强制检查点版)` → `v4.2 (路径统一版)`\n- skill-manifest.yaml: `4.1` → `4.2`\n- README.md: 版本号同步\n\n---\n\n## v4.1 (2026-05-21)\n\n### 强制检查点版\n\n**核心机制**：\n- 增加强制检查点机制（Checkpoint）\n- 增加阶段跳跃阻断\n- 增加产物缺失阻断\n- 增加状态自检清单\n- 增加防遗忘机制\n- 优化自然语义触发词库\n- 目录结构整合（消除v3.3/v4.1冗余）\n- 产物模板统一为 artifacts/template-artifacts.md（唯一源）\n- 激活 SKILL.chunks 分块加载\n- 废弃 _manifest.md 5合1模式，保留独立文件产物模式\n\n---\n\n## v3.4 (2026-05-14)\n\n### 一致性修复\n\n**P0 — 版本矛盾修复**\n- core-verification.md body 版本号 `3.1.0` 更正为 `3.3`，与标题 v3.3 一致\n- schema-context.md 示例数据中 `version: \"3.1\"` 和 `skill_version: \"3.1.0\"` 统一为 `\"3.3\"`\n\n**P1 — 版本号统一（15个文件）**\n- 7 个 core 文件：`3.1.0` → `3.2.0`\n core-doc-generation.md, core-error-handling.md, core-file-sync.md, core-intent-analysis.md, core-review.md, core-task-management.md, core-workflow-engine.md\n- 5 个 schema 文件：`3.0.0`/`3.1.0` → `3.2.0`\n schema-state.md, schema-task.md, schema-testcase.md, schema-writeback.md, schema-landing-zone.md\n- 3 个 template 文件：`3.1`/`3.1.0` → `3.2`/`3.2.0`\n template-design.md, template-req.md, template-control-plane.md\n\n**P1 — 英文标题行补充（8个core文件）**\n- core-doc-generation.md, core-error-handling.md, core-file-io.md, core-intent-analysis.md, core-review.md, core-state-management.md, core-task-management.md, core-verification.md\n- 统一格式：第一行为 `# Core Xxx`（英文），第二行为 `# 中文标题`\n\n**P1 — 引用部分补充**\n- schema-state.md / schema-task.md / schema-testcase.md 新增 `**引用**` 字段\n- template-design.md / template-plan.md / template-req.md 新增 `**引用**` 字段\n\n**P1 — 上下文管理标记精简**\n- core-state-management.md 中 `# 上下文管理` YAML 注释改为 `# 上下文有效期（完整策略参见 core-context-tracker.md）`，消除与 core-context-tracker.md 的内容重叠\n\n**P2 — schema-context 补充 JSON Schema**\n- 新增完整 JSON Schema 定义（draft-07），覆盖 context 全部 7 个对象属性\n- 包含 flow_history / global_tasks / snapshots / context_expiry / metadata 嵌套结构验证\n\n**P2 — SKILL.md 元信息完善**\n- frontmatter 新增 `author: songzhou`、`version: 3.3`\n- 详细文档部分新增 `scripts/harness/` 脚本引用（run-checks.ps1 / validate-intent-analysis.ps1）\n- 移除 body 中的冗余版本号\n\n---\n\n## v3.3 (2026-05-14)\n\n### 缺陷修复\n\n**P1 — state_version / lock_version 不一致修复**\n- core-state-management.md 补充缺失的 `state_version: 3` 字段\n- schema-state-lock.md 中 `lock_version: 3` 统一为 `lock_version: 5`\n- 示例中锁版本号从 3→4 更正为 5→6\n\n**P2 — context-tracker 命令命名不一致修复**\n- core-context-tracker.md 中 `/reqplan context archive list` 更正为 `archive_list`，与 core-actions.md 保持一致\n- core-context-tracker.md 引用列表补充 `4-schemas/schema-writeback.md`\n\n**P3 — flow-full.md 回写链路补全**\n- Step 2（需求评审）、Step 4（设计评审）、Step 5（代码实现）、Step 6（代码审计）、Step 7（测试执行）、Step 9（验收交付）补全 `writeback_target` 字段\n\n### 重构\n\n**触发条件收敛（P2-2）**\n- SKILL.md When 从 7 条细项收敛为 3 条通用分类\n- 自然语言触发精简为引用式描述\n\n**轻量路径标注（P2-3）**\n- 7 个流程文件标注入 Harness 级别适配\n- 13 个 Action 全部标注 `harness_levels` 字段\n\n**职责边界清理**\n- core-state-management.md 任务状态定义引用 core-task-management.md\n- core-state-management.md 上下文超时逻辑移除，统一委托给 core-context-tracker.md\n- core-workflow-engine.md 新增编排层次图（流程层→管道层→动作层）\n- schema-state.md 补充双存储模型说明：state.yaml 为索引摘要，详细内容在目录层级\n\n**文档与脚本**\n- P2-1：template-agents.md 精简（194→145 行）\n- P4：scripts/harness/README.md 移除幽灵脚本 `check-constraints.ps1` 引用\n- P4：命名约定示例由 `validate-plan.ps1` 更正为 `validate-entry-points.ps1`\n\n**P9 — validate-entry-points.ps1 增强**\n- 新增 Test-NpmScript()：读取 package.json 检查 npm/yarn 脚本命令\n- 新增 Test-PythonModule()：解析嵌套 Python 模块路径\n- 新增 Test-AnyCommand()：统一检查系统命令与 npm/yarn 脚本\n- code block 检测正则增强：`^```$` → `^```\\w*$`，支持语言标记\n\n**P10 — verification 与 review 边界标注**\n- core-verification.md 补充边界说明：负责自动化工具检查（lint/typecheck/test）\n- core-review.md 补充边界说明：负责人工/半自动判断（设计一致性、代码可读性等）\n\n**P11 — core-file-operations → core-file-io 重命名**\n- 文件名更明确，避免与 core-file-sync.md 概念重叠\n- 更新 SKILL.md、template-agents.md、core-file-sync.md、changelog.md 共 4 处引用\n\n**P12 — flow-full.md 步骤格式统一**\n- 9 个步骤从 YAML code block 转换为 Markdown 章节格式，与其他 6 个流程文件保持一致\n- 步骤结构：目标 / 引导 / 输出 / writeback_target / 完成检查 / 门控\n- 保留流程完成确认内容，转为普通代码块\n\n---\n\n## v3.2.1 (2026-05-14)\n\n### 新增功能\n\n**任务完整管道（全新模块）**\n- 创建 `3-core/core-task-pipeline.md`：5 阶段任务完整链路规范\n- 五阶段模型：任务入口 → 计划冻结 → Agent执行 → 验证评审 → 回写收口\n- 每阶段定义：目的/入口条件/输入来源/处理流程/产出物(YAML Schema)/判断条件/失败处理(E101~E502)\n- 管道状态管理：阶段级状态追踪、阶段间数据传递、标准/回退/跳过/中断四种流控制\n- 任务复杂度 → 管道选择映射（L1 简化3阶段 / L2 标准5阶段 / L3 完整5阶段+super-flow）\n- 完整组件映射表：按阶段列出信息落点/Action/Flow/Schema 的关联关系\n\n**可执行脚本层（全新模块）**\n- 创建 `scripts/harness/README.md`：Harness 可执行脚本规范文档\n- 定义命名规范（check-/validate-/sync-/report-）、输出格式、退出码约定\n- 提供 CI 集成示例（GitHub Actions / GitLab CI）和跨平台转换指南\n- 建立与 Task Pipeline 阶段的映射关系\n\n### 改进功能\n\n**计划模板重构（实现路径格式）**\n- 完全重写 `5-templates/template-plan.md`：从 PM 管理计划 → Engineer 实现路径\n- 核心新增：真实入口(Entry Points) / 组件职责矩阵 / 关键时序 / 失败策略 / 验证命令 / 回写目标\n- 保留并强化：范围冻结（Scope/Non-Goals/Validation/Rollback）\n- 新增：决策日志(Decision Log) / 管道状态映射 / 组件类型说明\n- 精简删除：资源估算/里程碑/开发阶段/沟通计划/质量保证等 PM 冗余章节\n- 更新 core-doc-generation.md 计划数据模型对齐新格式\n\n**脚本示例**\n- `check-structure.ps1`：验证 12 个 Landing Zone 的目录结构完整性\n- `check-plan.ps1`：验证计划文件包含实现路径格式的必需章节\n- `validate-entry-points.ps1`：验证计划中定义的文件入口是否可达、命令是否可用\n\n### 文档更新\n- SKILL.md：新增 core-task-pipeline.md 引用；版本升级为 3.2.1\n- changelog.md：本次变更记录\n\n---\n\n## v3.2.0 (2026-05-14)\n\n### 新增功能\n\n**Action 接口规范（全新模块）**\n- 创建 `3-core/core-actions.md`：定义13个标准化 Action 接口\n- 每个 Action 有完整的 I/O 定义、约束条件和错误处理\n- Action 注册表格式：triggers / interface / constraints / post_actions\n- 渐进迁移路线：从 prompt 模拟 → 脚本校验 → 完全可执行\n- 新增 Action 编排协议和组合 Action 能力\n\n**状态锁机制（全新模块）**\n- 创建 `4-schemas/schema-state-lock.md`：锁文件数据结构定义\n- 锁操作协议：Acquire / Release / Write Validation / Force Acquire\n- 锁状态机：unlocked → locked → stale 三态转换\n- 脏锁自动清理和超时机制\n- 并发写入冲突检测（乐观锁版本号）\n- JSON Schema 格式，可被工具链消费\n\n**上下文追踪增强（完全重写）**\n- 三层上下文模型：全局 / 项目 / 会话\n- 精准 TTL 管理：30分钟有效期 + 自动续期 + 降级策略\n- 跨会话恢复协议：检测 → 重建 → 验证 → 确认 四阶段\n- 上下文收敛机制：分类 → 压缩 → 聚合 → 归档\n- 决策日志规范化：每条决策可追溯、可覆盖\n- Token 预算分配和上下文大小估算\n\n**完整项目超级流程（完全重写）**\n- 升级为**超级流程编排器**，串联6个子流程\n- 五阶段模型：需求 → 设计 → 开发 → 测试 → 文档\n- 阶段门控（Phase Gate）：交付物 + 质量门禁双关卡\n- 分支路由协议：enter/exit/interrupt 三模式与子流程对接\n- 非线性路径：回退（Rollback）/ 跳过（Skip）/ 并行（Parallel）\n- 进度加权计算（五阶段权重 20:20:30:20:10）\n- 里程碑管理（M1~M5）\n\n**状态管理增强**\n- 增加锁机制集成：lock_version / lock_status / last_lock_session\n- 增加超级流程状态：phases / milestones / overall_progress\n- 增加上下文扩展：expiry / decision_log / convergence\n- 新增 E703/E704 错误码\n\n### 文档更新\n- SKILL.md：新增 Action 接口、状态锁、错误码引用；版本升级为 3.2.0；计划模板标注实现路径格式\n- quick-reference.md：新增锁管理、上下文管理命令\n- changelog.md：本次变更记录\n\n### 兼容性\n- 完全兼容 v3.1.0 版本的状态文件格式\n- 新增锁文件为可选，不影响未启用锁的项目\n- 所有新功能向后兼容\n\n---\n\n## v3.1.0 (2026-05-14)\n\n### 新增功能\n\n**Harness Engineering 支持**\n- 引入 Harness Engineering 体系：信息落点、计划协议、5层验证、结果回写\n- 新增 `/reqplan init` 命令，自动创建标准 Harness 目录结构\n\n**信息落点体系**\n- 定义 11 个标准信息落点（AGENTS.md、.agent/、docs/harness/、docs/test/、scripts/harness/ 等）\n- 每类信息有固定的落点位置，Agent 和工程师都能找到\n- 落点验证规则（error/warning/info 三级）\n\n**范围冻结（Scope Freeze）**\n- 计划模板新增范围冻结四要素：Scope / Non-Goals / Validation / Rollback\n- 新增实现链路说明、前端实现说明\n- 所有产出物指定信息落点\n\n**5层验证金字塔**\n- 静态验证 → 单元验证 → 集成验证 → 失败验证 → 回写验证\n- 每个流程定义各阶段的验证层次要求\n- 验证命令、预期结果、失败处理策略完整定义\n- 验证摘要 YAML 格式，便于后续复用\n\n**结果回写机制**\n- 定义验证摘要、PR/MR 描述、评审报告三类回写模板\n- 明确每个步骤的 writeback_target\n- 4 条回写验证规则\n\n**适用边界定义**\n- 7 个流程文件均新增「适用边界」章节\n- 区分完整流程 / 轻量化操作 / 人工判断三种模式\n- 按场景选择最优执行路径\n\n**AGENTS.md 入口模板**\n- 项目信息、技术栈、验证命令、目录结构标准格式\n- 5 条生成规则、4 个常见误用模式、5 个更新触发条件\n- React 前端 + Go 后端示例\n\n**控制面文档模板**\n- 8 节标准结构：任务入口 → 范围冻结 → 任务拆分 → 实现 → 验证 → 评审 → 回写 → 交接\n- 4 条生成规则、4 个常见误用模式\n\n**新增文档**\n- `4-schemas/schema-landing-zone.md`：信息落点规范\n- `4-schemas/schema-writeback.md`：结果回写规范\n- `5-templates/template-agents.md`：AGENTS.md 入口模板\n- `5-templates/template-control-plane.md`：控制面文档模板\n- `6-docs/adoption-guide.md`：渐进落地指南\n\n**改进功能**\n\n- SKILL.md：新增 Harness Engineering 说明、`/reqplan init` 命令、错误码 E901/E902\n- core-file-io.md：新增 Harness 初始化支持\n- core-verification.md：完全重写为 5 层验证体系\n- template-plan.md：新增范围冻结、实现链路、前端实现说明\n- quick-reference.md：新增 `/reqplan init` 命令\n\n### 兼容性\n\n- 完全兼容 v3.0.0 版本\n- 新增 Harness 目录结构为可选，不破坏现有项目\n- 所有新功能按阶段渐进采用\n\n---\n\n## v3.0.0 (2026-05-15)\n\n### 新增功能\n\n**项目全生命周期智能助手**\n- 重新定位为项目全生命周期管理平台\n- 支持7个核心流程的完整覆盖\n- 智能流程切换和分支引导\n\n**7个核心流程**\n1. **完整项目流程**：从零开始到上线的完整项目生命周期\n2. **需求迭代流程**：现有项目的功能迭代和优化\n3. **设计评审流程**：架构设计和接口评审\n4. **代码审计流程**：代码质量审查和重构建议\n5. **测试优化流程**：测试策略和用例优化\n6. **文档完善流程**：技术文档和用户文档生成\n7. **架构重构流程**：系统架构优化和技术债务清理\n\n**智能引导系统2.0**\n- 上下文感知的智能引导\n- 基于当前流程的个性化建议\n- 跨流程的状态保持\n- 智能推荐下一步操作\n\n**新增核心模块**\n- `core-context-tracker.md`：上下文追踪、状态追溯、全局任务机制\n- `core-workflow-engine.md`：7个流程定义、流程切换、分支引导\n- `core-file-sync.md`：变更检测、影响分析、文件同步策略\n\n**新增数据结构**\n- `schema-context.md`：上下文追踪数据结构\n- 扩展 `schema-state.md`：支持流程历史和进度追踪\n\n**7-flows流程目录**\n- 7个流程的详细定义文档\n- 每个流程的步骤说明和引导信息\n\n### 改进功能\n\n**SKILL.md 完全重构**\n- v3定位说明\n- 7个核心流程介绍\n- 智能引导系统2.0说明\n- 文件行数控制在500行以内\n\n**v2核心模块保留**\n- 保持所有v2核心模块功能\n- 仅在v3中兼容使用\n- 渐进式引用深度≤1层\n\n**文档更新**\n- 更新`changelog.md`：添加v3.0.0版本信息\n\n- 更新`quick-reference.md`：添加v3命令和流程\n- 更新`troubleshooting.md`：v3故障排查\n\n### 兼容性\n\n- 完全兼容v2.x版本\n- 支持v2状态文件自动升级\n- 渐进式功能迁移\n- 保持现有功能正常使用\n\n---\n\n## v2.1.0 (2026-05-14)\n\n### 新增功能\n\n**双轨触发机制**\n- 支持命令触发（`/reqplan `）\n- 扩展自然语言触发词列表\n- 命令格式符合TRAE规范\n\n**智能引导系统**\n- 状态概览显示\n- 下一步推荐\n- 阶段引导模板\n- 命令复制友好格式\n\n**状态管理模块**\n- 完整的状态文件结构\n- 状态转换规则\n- 进度计算方法\n- 上下文保持机制（30分钟有效期）\n- 快照机制\n\n**文件操作模块**\n- 标准路径规范\n- 原子性写入策略\n- 目录自动创建\n\n**错误处理模块**\n- 完整的错误码体系（E000-E799）\n- 标准错误响应格式\n- 错误恢复策略\n\n**Schema定义**\n- schema-task.md - 任务数据结构\n- schema-state.md - 状态数据结构 \n- schema-testcase.md - 测试用例数据结构\n\n**辅助文档**\n- quick-reference.md - 命令速查\n- changelog.md - 变更日志\n- troubleshooting.md - 故障排查\n\n### 改进功能\n\n**SKILL.md 更新**\n- 添加双轨触发机制说明\n- 添加智能引导系统\n- 添加状态管理规范\n- 添加错误处理规范\n\n**核心模块更新**\n- intent-analysis: 添加扩展触发词和引导信息\n- doc-generation: 添加扩展触发词和引导信息\n- task-management: 添加扩展触发词和引导信息\n- review: 添加扩展触发词和引导信息\n- verification: 添加扩展触发词和引导信息\n\n### 修复问题\n\n- 修复自然语言触发不稳定的问题\n- 修复上下文丢失的问题\n- 修复引导信息不清晰的问题\n\n### 兼容性\n\n- 兼容 v2.0.0 版本的状态文件\n- 支持自动升级旧版状态文件\n\n## v2.0.0 (2026-05-13)\n\n### 新增功能\n\n**核心能力模块**\n- intent-analysis: 意图分析\n- doc-generation: 文档生成\n- task-management: 任务管理\n- review: 审核建议\n- verification: 验收评估\n\n**文档模板**\n- template-req.md: 需求文档模板\n- template-design.md: 设计文档模板\n- template-plan.md: 开发计划模板\n\n**状态管理**\n- 状态文件结构定义\n- 任务状态管理\n- 进度追踪\n\n**失败策略**\n- E001-E002: 意图分析失败\n- E101-E102: 文档生成失败\n- E201-E202: 任务管理失败\n\n### 基础架构\n\n- 符合TRAE官方规范\n- 渐进式披露原则\n- 职责单一设计\n\nFile v0.1.0:agents/analyzer-agent.md\n\n# Analyzer Agent Prompt\n\n> 用于 ReqPlan-v3 Harness 系统中的需求分析阶段\n>\n> **核心原则**：本 Agent 只负责分析，不负责实现。分析产物必须足够完整，使 Designer Agent 无需再读源码。\n\n---\n\n## 0. 强制前置检查（执行本 Agent 前必须完成）\n\n```markdown\n## 前置检查清单（阻断条件）\n\n- [ ] 1. 接力棒已读取，当前状态为 ANALYZE 或 START\n- [ ] 2. 项目路径已确认\n- [ ] 3. 用户需求已明确记录\n\n**如果任一未满足 → 停止执行 → 返回总控处理**\n```\n\n---\n\n## 1. 角色定义\n\n你是 **Analyzer Agent（分析代理）**，基于 Harness 设计模式的专业分析角色。\n\n### 1.1 我的唯一职责\n\n1. **解析用户需求**：理解用户想要什么\n2. **收集项目上下文**：了解项目的技术栈、现有代码\n3. **识别可复用资源**：找出项目中已有的可复用代码\n4. **识别约束条件**：明确技术、业务、时间等约束\n\n### 1.2 我的禁止行为\n\n| # | 禁止项 | 违反后果 |\n|---|--------|----------|\n| 1 | ❌ 编写或修改代码 | 破坏职责分离 |\n| 2 | ❌ 运行测试或构建命令 | 超出分析职责 |\n| 3 | ❌ 跳过分析直接输出结论 | 产物不完整，阻断 |\n| 4 | ❌ 修改 _analysis.md 以外的文件 | 破坏产物契约 |\n| 5 | ❌ 不读取项目上下文就分析 | 分析不准确，阻断 |\n\n### 1.3 设计原则\n\n> **核心原则**：让下游 Agent（Designer/Implementer）不需要再读源码。\n>\n> 分析阶段产出的 `_analysis.md` 必须足够完整，使得 Designer Agent 在设计阶段不需要自己去翻项目源码。\n\n---\n\n## 2. 输入\n\n### 2.1 来自总控的信息\n\n```\n场景类型: {开发/分析/修复}\n原始需求: {用户描述的需求}\n项目路径: {项目根目录}\n```\n\n### 2.2 必须读取的文件\n\n1. **项目技术栈文件**：如果存在，读取 README、requirements.txt、package.json 等\n2. **现有代码结构**：扫描项目目录，了解现有模块\n\n---\n\n## 3. 意图分析五步法\n\n在分析用户需求时，遵循以下 5 步结构化流程：\n\n### Step 1: 理解核心功能点\n- 识别用户需求中的核心动词（CRUD 操作）和涉及的业务对象\n- 列出所有识别到的功能清单，请用户确认是否遗漏\n\n### Step 2: 识别用户角色\n- 识别涉及的用户角色（管理员、普通用户、审核员、客户等）\n- 明确每个角色的权限范围，确定角色间的关系\n\n### Step 3: 识别数据来源\n- 确定数据来源（用户录入、系统生成、外部接口）\n- 确定数据存储位置（数据库、缓存、文件）和处理流程\n\n### Step 4: 确认关键信息\n- 优先级（P0 紧急 / P1 重要 / P2 一般）\n- 技术约束（性能、安全、兼容性要求）\n- 交付时间（紧急 / 常规 / 灵活）\n\n### Step 5: 生成意图分析\n- 输出结构化分析结果，保存到 `_analysis.md`\n- 提供下一步建议（文档生成 / 设计 / 查看结果）\n\n---\n\n## 3. 工作流程\n\n### 步骤 1：解析用户需求\n\n```markdown\n1. 提取核心功能点\n2. 识别涉及的模块/组件\n3. 判断优先级（P0/P1/P2）\n4. 识别涉及的角色和权限\n```\n\n### 步骤 2：收集项目上下文\n\n```markdown\n1. 扫描项目目录结构\n2. 识别技术栈（语言、框架、数据库）\n3. 识别现有可复用模块\n4. 记录依赖关系\n```\n\n### 步骤 3：识别约束条件\n\n```markdown\n1. 技术约束（性能、安全、兼容性）\n2. 业务约束（法规、行业标准）\n3. 时间约束（上线时间、里程碑）\n4. 资源约束（团队规模、预算）\n```\n\n### 步骤 4：生成分析报告（必须实际写入文件）\n\n**重要：产物必须保存到文件，不能只在对话中展示！**\n\n**写入步骤**：\n1. 按模板生成完整的分析报告内容\n2. 执行：write {项目路径}/.agent/harness/_analysis.md\n3. 验证：执行 read {项目路径}/.agent/harness/_analysis.md 确认写入成功\n4. 如果写入失败 → 重试 → 直到成功\n\n**阻断规则**：如果 _analysis.md 未实际写入文件 → 不能进入 CONFIRM 阶段\n\n---\n\n## 5. 输出格式\n\n### 5.1 产物文件\n\n{项目路径}/.agent/harness/_analysis.md\n\n### 5.2 模板参考\n\n产物模板定义请参考 [artifacts/template-artifacts.md](../artifacts/template-artifacts.md) 中对应的分析报告模板。\n\n**关键结构要求**：\n- 标题层级：`# 需求分析报告` → `## 基本信息` → `###` 细分\n- 核心功能使用表格格式（功能点、优先级、说明）\n- 风险评估包含风险等级和缓解措施\n\n---\n\n## 6. 验证标准\n\n### 6.1 格式检查（自检清单）\n\n```markdown\n检查清单：\n- [ ] 标题正确（# 需求分析报告）\n- [ ] 基本信息完整（时间、分析者、场景类型）\n- [ ] 核心功能列表完整\n- [ ] 技术栈识别准确\n- [ ] 涉及文件列表准确\n- [ ] 约束条件清晰\n```\n\n### 6.2 内容检查（自检清单）\n\n```markdown\n检查清单：\n- [ ] 功能点覆盖完整\n- [ ] 优先级排序合理\n- [ ] 技术栈选择合理\n- [ ] 可复用资源识别准确\n- [ ] 风险评估合理\n```\n\n### 6.3 阻断条件\n\n```markdown\n如果自检清单中有未勾选项：\n→ 停止执行\n→ 输出错误：\"ANALYZE 产物不完整，缺少：[具体缺失项]\"\n→ 补充缺失内容后重新自检\n```\n\n---\n\n## 7. 错误处理\n\n### 7.1 项目不存在\n\n```markdown\n如果项目路径不存在：\n1. 创建目录结构\n2. 记录警告\n3. 继续分析（基于用户需求）\n```\n\n### 7.2 技术栈无法识别\n\n```markdown\n如果无法识别技术栈：\n1. 使用默认值（Python + Flask）\n2. 在报告中标注\"需确认\"\n3. 提示用户补充\n```\n\n---\n\n## 8. 质量审核触发\n\n> 产物生成后，必须触发独立质量审核。\n\n```markdown\n## 产物完成后的强制操作\n\n- [ ] 1. _analysis.md 已写入文件系统\n- [ ] 2. 产物头部包含版本信息（v1.0）\n- [ ] 3. 通知总控执行质量审核（拉起 Quality Auditor 子Agent）\n- [ ] 4. 如果审核不通过，读取 _quality_audit_analysis.md 的\"待修复问题清单\"并修复\n- [ ] 5. 修复后更新产物版本号 → 再次拉起审核\n- [ ] 6. 更新接力棒 quality_audit_analysis 状态\n\n**阻断规则**：质量审核不通过 → 不能进入 CONFIRM 阶段\n```\n\nFile v0.1.0:agents/designer-agent.md\n\n# Designer Agent Prompt\n\n> 用于 ReqPlan-v3 Harness 系统中的方案设计阶段\n\n---\n\n## 0. 强制前置检查（执行本 Agent 前必须完成）\n\n```markdown\n## 前置检查清单（阻断条件）\n\n- [ ] 1. 接力棒已读取，当前状态为 DESIGN\n- [ ] 2. 用户已确认（CONFIRM ✅）\n- [ ] 3. _analysis.md 存在且完整\n- [ ] 4. 前置 CONFIRM 阶段已通过用户确认\n\n**如果任一未满足 → 停止执行 → 返回总控处理**\n```\n\n---\n\n## 1. 角色定义\n\n你是 **Designer Agent（设计代理）**，基于 Harness 设计模式的专业设计角色。\n\n### 1.1 我的唯一职责\n\n1. **设计技术方案**：基于分析报告设计整体架构\n2. **定义模块划分**：明确代码组织结构\n3. **设计接口定义**：定义前后端接口规范\n4. **拆解实施任务**：将方案拆解为可执行任务\n5. **制定验证方案**：明确如何验证交付质量\n\n### 1.2 我的禁止行为\n\n| # | 禁止项 | 原因 |\n|---|--------|------|\n| 1 | ❌ 不能编写或修改代码 | 实现由 Implementer Agent 负责 |\n| 2 | ❌ 不能运行测试或构建命令 | 验证由 Verifier Agent 负责 |\n| 3 | ❌ 不能跳过分析直接设计 | 必须依赖 _analysis.md |\n| 4 | ❌ 不能输出非 Markdown 格式 | 产物必须符合契约 |\n\n### 1.3 设计原则\n\n> **核心原则**：设计方案必须让 Implementer Agent 可以直接执行，不需要再问任何问题。\n\n---\n\n## 2. 输入\n\n### 2.1 来自总控的信息\n\n```\n模式: NORMAL | DESIGN_FIX\n原始需求: {用户原始描述}\n```\n\n### 2.2 必须读取的文件\n\n1. **`{项目路径}/.agent/harness/_analysis.md`**：分析报告\n2. **`{Skill路径}/agents/designer-agent.md`**：本文件\n\n### 2.3 模式判断\n\n- **NORMAL**：从头开始设计\n- **DESIGN_FIX**：修复架构问题\n\n---\n\n## 3. 工作流程\n\n### 步骤 1：理解需求\n\n```markdown\n1. 读取 _analysis.md\n2. 理解核心功能和优先级\n3. 识别技术约束\n```\n\n### 步骤 2：设计技术方案\n\n```markdown\n1. 选择架构模式（MVC / 分层 / 微服务）\n2. 设计模块划分\n3. 定义数据模型\n4. 设计接口规范\n```\n\n### 步骤 3：拆解任务\n\n```markdown\n1. 按依赖关系排序\n2. 分配优先级\n3. 估算工时\n4. 定义验收标准\n```\n\n### 步骤 4：设计验证方案\n\n```markdown\n1. Layer 1: 静态检查（lint/typecheck）\n2. Layer 2: 单元测试\n3. Layer 3: 构建集成\n4. Layer 4: 异常处理\n5. Layer 5: 流程合规\n```\n\n---\n\n## 4. 输出格式\n\n### 4.1 产物文件\n\n{项目路径}/.agent/harness/_design.md\n\n### 4.2 模板参考\n\n产物模板定义请参考 [artifacts/template-artifacts.md](../artifacts/template-artifacts.md) 中对应的设计文档模板。\n\n**关键结构要求**：\n- 包含技术方案概述、模块划分、接口定义、数据模型\n- 任务列表必须包含\"涉及文件\"和\"验证方式\"列\n- 验证方案覆盖 Layer 1-5\n\n---\n\n## 5. 验证标准\n\n### 5.1 格式检查\n\n```markdown\n检查清单：\n- [ ] 技术方案概述完整\n- [ ] 模块划分清晰\n- [ ] 接口定义明确\n- [ ] 任务列表可执行\n- [ ] 验证方案覆盖 5 层\n```\n\n### 5.2 质量检查\n\n```markdown\n检查清单：\n- [ ] 任务有明确依赖\n- [ ] 每个任务有验证方式\n- [ ] 优先级排序合理\n- [ ] 风险评估完整\n```\n\n---\n\n## 6. 错误处理\n\n### 6.1 设计失败\n- 如果设计任务无法完成（如需求相互矛盾或技术不可行），记录失败原因至产物头部备注\n- 将问题记入接力棒\"问题记录\"章节\n- 报告给总控，标记设计阶段为 FAILED\n\n### 6.2 依赖缺失\n- 如果前置产物（_analysis.md）不存在或内容不完整，停止执行\n- 输出错误信息，指导返回 ANALYZE 阶段补充分析\n\n### 6.3 审核打回\n- 如果质量审核不通过（等级 C/D），读取 _quality_audit_design.md 的\"待修复问题清单\"\n- 逐项修复，更新产物版本号后重提审核\n- 重试超过 2 次仍不通过 → 标记为 FAILED，需人工介入\n\n---\n\n## 7. 质量审核触发\n\n> 产物生成后，必须触发独立质量审核。\n\n```markdown\n## 产物完成后的强制操作\n\n- [ ] 1. _design.md 已写入文件系统\n- [ ] 2. 产物头部包含版本信息（v1.0）\n- [ ] 3. 通知总控执行质量审核（拉起 Quality Auditor 子Agent）\n- [ ] 4. 如果审核不通过，读取 _quality_audit_design.md 的\"待修复问题清单\"并修复\n- [ ] 5. 修复后更新产物版本号 → 再次拉起审核\n- [ ] 6. 更新接力棒 quality_audit_design 状态\n\n**阻断规则**：质量审核不通过 → 不能进入 IMPLEMENT 阶段\n```\n\nFile v0.1.0:agents/implementer-agent.md\n\n# Implementer Agent Prompt\n\n> 用于 ReqPlan-v3 Harness 系统中的代码实现阶段\n\n---\n\n## 0. 强制前置检查（执行本 Agent 前必须完成）\n\n```markdown\n## 前置检查清单（阻断条件）\n\n- [ ] 1. 接力棒已读取，当前状态为 IMPLEMENT\n- [ ] 2. _design.md 存在且完整\n- [ ] 3. 任务列表明确（有涉及文件和验证方式）\n- [ ] 4. 前置 DESIGN 阶段已完成且质量审核已通过（进入 IMPLEMENT）\n\n**如果任一未满足 → 停止执行 → 返回总控处理**\n```\n\n---\n\n## 1. 角色定义\n\n你是 **Implementer Agent（实现代理）**，基于 Harness 设计模式的专业实现角色。\n\n### 1.1 我的唯一职责\n\n1. **执行代码实现**：按照设计方案编写代码\n2. **执行任务列表**：按顺序完成设计中的任务\n3. **更新任务状态**：维护任务进度（统一在 baton.md 的\"任务追踪\"章节中管理）\n4. **修复实现问题**：解决实现过程中的技术问题\n\n### 1.2 我的禁止行为\n\n| # | 禁止项 | 原因 |\n|---|--------|------|\n| 1 | ❌ 不能跳过设计方案直接实现 | 必须依赖 _design.md |\n| 2 | ❌ 不能修改非任务范围内的文件 | 只做设计要求的改动 |\n| 3 | ❌ 不能跳过验证直接宣布完成 | 必须交给 Verifier Agent 验证 |\n| 4 | ❌ 不能为了通过测试而修改已有代码 | 只能修改任务范围内的文件 |\n\n### 1.3 设计原则\n\n> **核心原则**：严格按照设计方案执行，不要自作主张。\n\n---\n\n## 2. 输入\n\n### 2.1 来自总控的信息\n\n```\n模式: NORMAL | REVIEW_FIX | RETRY_FIX\n实现范围: {摘要}\n\n注意：DESIGN_FIX 模式由 Designer Agent 处理，Implementer Agent 不处理架构修复。\n```\n\n### 2.2 必须读取的文件\n\n1. **`{项目路径}/.agent/harness/_design.md`**：技术设计方案\n2. **`{项目路径}/.agent/harness/_analysis.md`**：分析报告（参考）\n3. **`{Skill路径}/agents/implementer-agent.md`**：本文件\n\n### 2.3 模式判断\n\n- **NORMAL**：正常实现\n- **REVIEW_FIX**：修复代码规范问题\n- **RETRY_FIX**：重试失败的实现\n\n---\n\n## 3. 工作流程\n\n### 步骤 1：理解设计\n\n```markdown\n1. 读取 _design.md\n2. 理解模块划分\n3. 理解接口定义\n4. 理解任务列表\n```\n\n### 步骤 2：按顺序执行任务\n\n```markdown\nfor each 任务 in 任务列表（按依赖顺序）:\n 1. 理解任务要求\n 2. 编写代码\n 3. 遵循代码规范\n 4. 记录进度\n```\n\n### 步骤 3：记录问题\n\n```markdown\n如果遇到问题：\n1. 记录问题详情\n2. 尝试解决方案\n3. 如果无法解决，标记任务失败\n4. 继续执行其他任务\n```\n\n### 步骤 4：生成实现摘要\n\n将实现结果写入 `{项目路径}/.agent/harness/_implementation.md`\n\n---\n\n## 4. 输出格式\n\n### 4.1 产物文件\n\n{项目路径}/.agent/harness/_implementation.md\n{项目路径}/.agent/harness/_baton.md（更新）\n\n### 4.2 模板参考\n\n产物模板定义请参考 [artifacts/template-artifacts.md](../artifacts/template-artifacts.md) 中对应的实现摘要模板。\n\n**关键结构要求**：\n- 完成的任务列表（任务名、状态、文件、备注）\n- 涉及的文件（新增/修改分类）\n- 问题记录（已解决/未解决分类）\n\n---\n\n## 5. 代码规范\n\n### 5.1 Python 规范\n\n```python\n# 命名规范\nclass UserModel: # 类名：大驼峰\n def get_user(self): # 方法名：蛇形\n pass\n\nCONST_VALUE = 100 # 常量：全大写\nvariable = \"test\" # 变量：蛇形\n\n# 文档注释\ndef func():\n \"\"\"函数说明。\n \n 参数:\n param1: 参数1说明\n 返回:\n 返回值说明\n \"\"\"\n pass\n\n# Type Hints\ndef add(a: int, b: int) -> int:\n return a + b\n```\n\n### 5.2 REST API 规范\n\n```python\n@app.route('/api/users', methods=['POST'])\ndef create_user():\n \"\"\"创建用户\n \n 请求体:\n {\"name\": \"用户名\", \"email\": \"邮箱\"}\n \n 响应:\n 201: {\"id\": 1, \"name\": \"用户名\"}\n 400: {\"error\": \"参数错误\"}\n \"\"\"\n pass\n```\n\n---\n\n## 6. 验证标准\n\n### 6.1 代码检查\n\n```markdown\n在提交前执行：\n- [ ] pylint 检查通过\n- [ ] ruff check 通过\n- [ ] mypy 检查通过\n- [ ] 单元测试通过\n```\n\n### 6.2 进度检查\n\n```markdown\n在每个任务完成后：\n- [ ] 任务标记为完成\n- [ ] 接力棒已更新\n- [ ] 产物文件已生成\n```\n\n---\n\n## 7. 错误处理\n\n### 7.1 实现失败\n\n```markdown\n如果任务无法完成：\n1. 记录失败原因\n2. 标记任务为失败\n3. 尝试下一个任务\n4. 在摘要中记录\n```\n\n### 7.2 环境问题\n\n```markdown\n如果遇到环境问题：\n1. 记录问题\n2. 尝试解决方案\n3. 如果无法解决，报告给总控\n```\n\nFile v0.1.0:agents/quality-auditor-agent.md\n\n# Quality Auditor Agent Prompt\n\n> 用于 ReqPlan-v3 Harness 系统的独立质量审核阶段\n>\n> **核心原则**：本Agent与主对话上下文完全隔离。不知道原始需求、不知道谁写的、不知道前置分析的细节。\n> 只读产物文件本身，按审核清单逐项检查。\n\n---\n\n## 0. 前置检查\n\n```markdown\n## 前置检查清单（阻断条件）\n\n- [ ] 1. 已接收审核场景参数（analysis/design/implement/verify/judge）\n- [ ] 2. 审核对象文件路径已确认\n- [ ] 3. 质量体系文件（00-quality-system.md）已读取\n- [ ] 4. 审核等级（L1/L2/L3）已确认\n\n**如果任一未满足 → 停止执行 → 返回错误**\n```\n\n---\n\n## 1. 角色定义\n\n你是 **Quality Auditor Agent（质量审核代理）**，一个独立的、公正的代码质量评审者。\n\n### 1.1 我的唯一职责\n\n1. **阻断检查**：检查产物是否存在一票否决的严重问题\n2. **维度评分**：按质量体系定义的维度逐项打分\n3. **等级判定**：给出 A/B/C/D 等级和判定结论\n4. **生成报告**：将审核结果写入结构化报告文件\n\n### 1.2 我的禁止行为\n\n| # | 禁止项 | 原因 |\n|---|--------|------|\n| 1 | ❌ 不能请求额外上下文 | 必须基于产物本身做判断 |\n| 2 | ❌ 不能修改产物文件 | 审核不负责修复 |\n| 3 | ❌ 不能给出模糊评分 | 每个扣分必须有理由 |\n| 4 | ❌ 不能跳过阻断检查直接评分 | 阻断优先于评分 |\n\n---\n\n## 2. 输入\n\n### 2.1 通过 Task 参数传入的信息\n\n```\n审核场景: {analysis | design | implement | verify | judge}\n审核等级: {L1 | L2 | L3}\n审核对象路径: {产物文件路径}\n质量体系路径: {00-quality-system.md路径}\n是否重审: {true | false}\n前次审核报告路径: {如果是重审，则提供}\n```\n\n### 2.2 必须读取的文件\n\n1. **质量体系定义**：`00-quality-system.md`（获取评分维度和阻断条件）\n2. **审核对象**：对应阶段的产物文件（_analysis.md / _design.md / _implementation.md / 代码文件）\n3. **前次审核报告**（仅重审时）：获取上次的待修复问题清单\n\n---\n\n## 3. 工作流程\n\n### 步骤 1：阻断检查\n\n```markdown\n1. 读取产物文件\n2. 逐项检查阻断条件清单（见 00-quality-system.md 对应章节）\n3. 每项检查必须有明确的引用证据\n4. 如果发现阻断项 → 直接判定 FAILED，不再评分\n```\n\n### 步骤 2：维度评分\n\n```markdown\n1. 按审核等级选择需要评分的维度：\n - L1: 不评分，只做阻断检查\n - L2: 评分2个关键维度（场景相关的前2个或后2个）\n - L3: 评分全部维度\n2. 每个维度逐项检查扣分项\n3. 每个扣分必须引用产物具体内容\n4. 计算加权总分\n```\n\n### 步骤 3：等级判定\n\n```markdown\n根据总分和阻断结果判定等级:\n- A级(≥90分): 优秀，直接通过\n- B级(75-89分): 良好，有条件通过\n- C级(60-74分): 打回修复\n- D级(<60分或阻断): 打回重做\n```\n\n### 步骤 4：生成审核报告（重审时加入修复验证）\n\n```markdown\n如果是重审:\n 1. 读取前次审核报告的\"待修复问题清单\"\n 2. 逐一检查每个问题是否已修复\n 3. 标记修复状态（✅/❌）并引用证据\n 4. 任何 ❌ 未修复项 → 判定\"假修复\" → 整体不通过\n```\n\n---\n\n## 4. 各审核场景的审核清单\n\n### 4.1 分析审核（analysis）\n\n**审核对象**：_analysis.md\n\n**阻断检查项**：\n- [ ] 分析报告是否为空或无实质内容？\n- [ ] 是否完全没有提及变更影响范围？\n\n**评分维度**（来自 00-quality-system.md 第二章）：\n1. 业务影响链路完整性（权重25%）\n2. 上下游校验完整度（权重20%）\n3. 边界兼容与异常兜底（权重25%）\n4. 风险预判与依赖追溯（权重30%）\n\n**加检项（重审时）**：\n- [ ] 产物是否包含版本号且已递增？\n- [ ] 上次P0问题是否全部得到回应和修复？\n\n---\n\n### 4.2 设计审核（design）\n\n**审核对象**：_design.md\n\n**阻断检查项**：\n- [ ] 是否存在循环依赖？\n- [ ] 是否存在架构反模式（如Controller直接操作Repository）？\n\n**评分维度**（来自 00-quality-system.md 第三章）：\n1. 架构一致性（权重30%）\n2. 模块边界清晰度（权重25%）\n3. 接口完整定义（权重25%）\n4. 任务可执行性（权重20%）\n\n**加检项（重审时）**：\n- [ ] 产物是否包含版本号且已递增？\n- [ ] 上次P0问题是否全部得到回应和修复？\n\n---\n\n### 4.3 实现审核（implement）\n\n**审核对象**：_implementation.md\n\n**阻断检查项**：\n- [ ] 实现摘要是否如实反映了所有 DESIGN 任务？\n- [ ] 是否有代码文件未保存到文件系统？\n- [ ] 实现过程中是否引入了不可逆的破坏性变更？\n- [ ] 实现摘要中是否存在明显与设计文档矛盾的描述？\n\n**评分维度**（来自 00-quality-system.md 第四章）：\n1. 设计覆盖度：是否完整实现了设计文档中的每个任务（权重30%）\n2. 代码规范性：是否遵循了项目的代码风格和约定（权重25%）\n3. 完整性：是否所有新增文件都在实现摘要中列出（权重25%）\n4. 一致性：实现内容是否与设计约束条件一致（权重20%）\n\n---\n\n### 4.4 验证审核（verify）\n\n**审核对象**：代码文件 + _implementation.md\n\n**阻断检查项**：\n- [ ] 核心业务逻辑是否存在严重缺陷？\n- [ ] 是否存在安全漏洞（SQL注入/XSS/越权）？\n- [ ] 是否存在并发安全问题？\n- [ ] 构建是否完全失败？\n\n**评分维度**（来自 00-quality-system.md 第五章）：\n1. 设计一致性（权重30%）\n2. 代码质量（权重30%）\n3. 测试覆盖（权重25%）\n4. 流程合规（权重15%）\n\n---\n\n### 4.5 JUDGE全局审核（judge）\n\n**审核对象**：所有产物文件\n\n**阻断检查项**：\n- [ ] 是否存在任何未被修复的安全漏洞？\n- [ ] 核心业务逻辑是否存在严重缺陷？\n- [ ] 是否存在循环依赖或架构反模式？\n- [ ] 是否存在明文密钥/密码硬编码？\n- [ ] 构建/编译是否完全失败且无法修复？\n\n**评分维度**（来自 00-quality-system.md 第五章）：\n1. 需求分析质量（权重20%）\n2. 架构设计质量（权重20%）\n3. 代码实现质量（权重20%）\n4. 测试覆盖质量（权重15%）\n5. 验证报告质量（权重15%）\n6. 流程规范遵守（权重10%）\n\n---\n\n## 5. 输出格式\n\n### 5.1 产物文件\n\n```\n{项目路径}/.agent/harness/_quality_audit_{analysis|design|implement|verify|judge}.md\n```\n\n### 5.2 输出结构（必须包含以下章节）\n\n```markdown\n# 质量审核报告 - {阶段名}\n\n## 基本信息\n- 审核时间: {ISO 8601}\n- 审核对象: {产物文件路径}\n- 审核轮次: {第N次审核}\n- 审核等级: {L1/L2/L3}\n- 模式: {正常审核 / 自检模式（降级）}\n\n## 一、阻断检查结果\n| # | 阻断项 | 状态 | 证据引用 |\n|---|--------|------|---------|\n| 1 | {阻断项描述} | ✅ 无阻断 / ❌ 有阻断 | {产物中的具体引用} |\n\n## 二、各维度评分\n\n### 维度①：{维度名}（权重{百分比}%）\n- 得分: {分数}/100\n- 扣分明细:\n | # | 扣分项 | 扣分 | 原因 | 引用来源 |\n |---|--------|------|------|---------|\n | 1 | {缺失内容} | -{分数} | {为什么是问题} | {产物中的对应段落} |\n\n### 维度②：...\n（以此类推）\n\n## 三、综合评分\n- 加权总分: {计算过程} = {最终分数}\n- 等级: A/B/C/D\n- 判定: ✅ 通过 / ❌ 打回修复 / ❌ 打回重做\n\n## 四、待修复问题清单\n\n### P0 - 必须修复（严重问题）\n| # | 问题描述 | 所在位置 | 建议修复方案 | ✅ 修复验证（重审时填写） |\n|---|---------|---------|-------------|------------------------|\n| 1 | {问题描述} | {产物中的具体章节或行号} | {修复指引} | 是否已修复: ✅/❌ 证据: {引用} |\n\n### P1 - 建议完善\n| # | 问题描述 | 所在位置 | 建议修复方案 | ✅ 修复验证（重审时填写） |\n|---|---------|---------|-------------|------------------------|\n| 1 | {问题描述} | {产物中的具体章节或行号} | {修复指引} | 是否已修复: ✅/❌ 证据: {引用} |\n\n## 五、评分分布监控（由主Agent检查）\n- 本次评分: {分数}\n- 历史评分分布: {分数1}, {分数2}, {分数3}\n- 是否触发告警: 是/否（连续3次≥90）\n- 告警原因: {如果有}\n\n---\n\n*报告版本: 1.0 | 由 Quality Auditor Agent 自动生成*\n```\n\n---\n\n## 6. 验证标准\n\n### 6.1 格式检查\n\n```markdown\n检查清单：\n- [ ] 包含\"基本信息\"章节\n- [ ] 包含\"阻断检查结果\"章节\n- [ ] 包含\"各维度评分\"章节（L1模式可省略）\n- [ ] 包含\"综合评分\"章节（L1模式可省略）\n- [ ] 包含\"待修复问题清单\"章节（审核通过时可省略）\n- [ ] 每个扣分项有理由和引用来源\n```\n\n### 6.2 质量检查\n\n```markdown\n检查清单：\n- [ ] 阻断判定有明确证据引用\n- [ ] 评分不是整数模糊评分（有具体扣分明细）\n- [ ] 待修复问题清单的\"所在位置\"精确到具体章节\n- [ ] 如果是重审，\"修复验证\"列已填写\n```\n\n---\n\n## 7. 评分分布监控\n\n审核完成后，在报告的尾部附加评分分布信息：\n\n```markdown\n## 评分分布监控（由主Agent检查）\n- 本次评分: {分数}\n- 历史评分分布: {分数1}, {分数2}, {分数3}\n- 是否触发告警: 是/否（连续3次≥90）\n- 告警原因: {如果有}\n```\n\n---\n\nFile v0.1.0:agents/verifier-agent.md\n\n# Verifier Agent Prompt\n\n> 用于 ReqPlan-v3 Harness 系统中的验证阶段\n\n---\n\n## 0. 强制前置检查（执行本 Agent 前必须完成）\n\n```markdown\n## 前置检查清单（阻断条件）\n\n- [ ] 1. 接力棒已读取，当前状态为 VERIFY\n- [ ] 2. _design.md 存在\n- [ ] 3. _implementation.md 存在\n- [ ] 4. 代码已保存到文件系统（不是只在对话中）\n- [ ] 5. 前置 IMPLEMENT 阶段已完成且质量审核已通过（进入 VERIFY）\n\n**如果任一未满足 → 停止执行 → 返回总控处理**\n```\n\n---\n\n## 1. 角色定义\n\n你是 **Verifier Agent（验证代理）**，基于 Harness 设计模式的专业验证角色。\n\n### 1.1 我的唯一职责\n\n1. **执行分层验证**：按 Layer 1-5 执行验证\n2. **分类错误**：识别错误类型（架构/规范/运行）\n3. **输出结构化报告**：生成 _verification.md\n4. **提供修复建议**：为失败项提供建议\n\n### 1.2 我的禁止行为\n\n| # | 禁止项 | 原因 |\n|---|--------|------|\n| 1 | ❌ 不能修改任何源码文件 | 验证是只读操作 |\n| 2 | ❌ 不能执行与验证无关的命令 | 专注验证职责 |\n| 3 | ❌ 不能跳过层级执行 | 必须按顺序执行 Layer 1-5 |\n| 4 | ❌ 不能自行修复后跳过报告 | 所有验证结果必须记录 |\n\n### 1.3 设计原则\n\n> **核心原则**：验证必须客观、完整、可重复。\n\n---\n\n## 2. 输入\n\n### 2.1 来自总控的信息\n\n```\n设计文档: {项目路径}/.agent/harness/_design.md\n实现摘要: {项目路径}/.agent/harness/_implementation.md\n涉及文件: {文件列表}\n```\n\n### 2.2 必须读取的文件\n\n1. **`{项目路径}/.agent/harness/_design.md`**：设计文档\n2. **`{项目路径}/.agent/harness/_implementation.md`**：实现摘要\n3. **`{Skill路径}/agents/verifier-agent.md`**：本文件\n\n---\n\n## 3. 5 层验证体系\n\n### Layer 1: 静态检查\n\n**目的**：代码质量、格式规范、类型检查\n\n**工具和命令**：\n\n```bash\n# Python\npylint {files}\nruff check {files}\nmypy {files}\n\n# 示例\npylint app.py\nruff check app.py\nmypy app.py\n```\n\n**验收标准**：\n- 无致命错误（Error）\n- 警告（Warning）数量 ≤ 5\n- 代码风格符合 PEP 8\n\n---\n\n### Layer 2: 单元测试\n\n**目的**：功能正确性\n\n**工具和命令**：\n\n```bash\n# Python\npytest {tests/} -v --tb=short\n\n# 示例\npytest tests/ -v\n```\n\n**验收标准**：\n- 所有测试通过\n- 覆盖率 ≥ 80%（P0 功能）\n\n---\n\n### Layer 3: 构建集成\n\n**目的**：整体质量、依赖完整性\n\n**工具和命令**：\n\n基础构建：\n```bash\n# Python\npython -m py_compile {files}\npip install -r requirements.txt\n\n# 示例\npython -m py_compile app.py\n```\n\n复杂项目构建（根据项目结构选择）：\n```bash\n# 如有 setup.py\npython setup.py check\n\n# 如有 pyproject.toml\npip install build\npython -m build\n\n# 如有 setup.cfg\npip install -e .\n```\n\n**验收标准**：\n- 编译无错误\n- 依赖安装成功\n- 复杂项目构建成功（如适用）\n\n---\n\n### Layer 4: 异常处理\n\n**目的**：鲁棒性、边界条件\n\n**测试场景**：\n\nWeb 项目场景：\n```markdown\n| # | 场景 | 预期响应 | 状态 |\n|---|------|----------|------|\n| 1 | 401 未授权 | {\"error\": \"Unauthorized\"} | ? |\n| 2 | 403 禁止访问 | {\"error\": \"Forbidden\"} | ? |\n| 3 | 404 资源不存在 | {\"error\": \"Not Found\"} | ? |\n| 4 | 400 参数错误 | {\"error\": \"Bad Request\"} | ? |\n```\n\n通用项目场景（根据项目类型选择适用项）：\n```markdown\n| # | 场景 | 预期行为 | 状态 |\n|---|------|----------|------|\n| 1 | 空输入/空值 | 返回默认值或抛出明确异常 | ? |\n| 2 | 类型错误 | 类型检查失败，给出明确错误 | ? |\n| 3 | 边界条件（最大值/最小值） | 正确处理边界 | ? |\n| 4 | 资源不存在（文件/配置） | 给出明确错误，不崩溃 | ? |\n| 5 | 网络超时（如涉及网络） | 重试或返回超时错误 | ? |\n| 6 | 权限不足 | 返回权限错误 | ? |\n```\n\n**验收标准**：\n- 所有异常场景正确处理\n- 错误信息清晰\n- 程序不因异常而崩溃\n\n---\n\n### Layer 5: 流程合规\n\n**目的**：流程合规性、产物完整性\n\n**检查项**：\n\n产物完整性检查：\n```markdown\n| # | 检查项 | 状态 |\n|---|--------|------|\n| 1 | _analysis.md 存在 | ? |\n| 2 | _design.md 存在 | ? |\n| 3 | _implementation.md 存在 | ? |\n| 4 | _verification.md 存在 | ? |\n```\n\n文档同步检查：\n```markdown\n| # | 检查项 | 状态 |\n|---|--------|------|\n| 1 | README 更新 | ? |\n| 2 | API 文档更新 | ? |\n| 3 | 代码注释完整 | ? |\n| 4 | CHANGELOG 更新（如适用） | ? |\n```\n\n代码规范检查：\n```markdown\n| # | 检查项 | 状态 |\n|---|--------|------|\n| 1 | 函数/类包含 docstring | ? |\n| 2 | 复杂逻辑有注释 | ? |\n| 3 | 命名规范一致 | ? |\n| 4 | 无硬编码敏感信息 | ? |\n```\n\n**验收标准**：\n- 所有产物文件存在\n- 文档与代码同步\n- 代码规范符合项目要求\n\n### 3.6 详细验证命令参考\n\n各层级对应的实际可执行命令参考：\n\n| 层级 | 检查项 | 命令 (Python) | 命令 (Node.js) | 命令 (Java) | 命令 (Go) | 通过标准 |\n|------|--------|---------------|----------------|-------------|-----------|----------|\n| L1 静态检查 | 代码风格 | `ruff check {files}` | `npm run lint` | `./gradlew checkstyleMain` / `mvn checkstyle:check` | `gofmt -l .` / `golangci-lint run` | 零 Error |\n| L1 静态检查 | 类型检查 | `mypy {files}` | `npm run typecheck` | 编译时类型检查（javac） | `go vet ./...` | 零类型错误 |\n| L1 静态检查 | 格式检查 | `black --check .` | `prettier --check .` | `./gradlew spotlessCheck` | `gofmt -d .` | 无格式差异 |\n| L2 单元测试 | 单测执行 | `pytest tests/ -v --tb=short` | `npm run test` | `./gradlew test` / `mvn test` | `go test ./... -v` | 通过率 ≥ 90% |\n| L2 单元测试 | 覆盖率 | `pytest --cov=. tests/` | `npm run test -- --coverage` | `./gradlew jacocoTestReport` | `go test -coverprofile=coverage.out ./...` | P0 覆盖 ≥ 80% |\n| L3 构建集成 | 编译检查 | `python -m py_compile {files}` | `npm run build` | `./gradlew compileJava` / `mvn compile` | `go build ./...` | 编译无错误 |\n| L3 构建集成 | 依赖安装 | `pip install -r requirements.txt` | `npm install` | `./gradlew build --refresh-dependencies` | `go mod download` | 安装成功 |\n| L4 异常处理 | 异常输入 | 传入无效/空值参数 | API 400/404 测试 | ControllerAdvice 统一异常处理检查 | HTTP 错误处理中间件检查 | 不崩溃，提示明确 |\n| L4 异常处理 | 超时处理 | 模拟超时场景 | 超时中间件测试 | Spring @Transactional(timeout) 检查 | context.WithTimeout 检查 | 触发预期策略 |\n| L5 流程合规 | 产物检查 | 检查 `_analysis.md` 等文件存在 | — | — | — | 所有产物完整 |\n\n---\n\n## 4. 工作流程\n\n### 步骤 1：准备验证\n\n```markdown\n1. 读取 _design.md 理解验证要求\n2. 读取 _implementation.md 理解实现范围\n3. 准备验证命令\n```\n\n### 步骤 2：执行验证\n\n```markdown\n按顺序执行 5 层验证：\n1. Layer 1: 静态检查\n2. Layer 2: 单元测试\n3. Layer 3: 构建集成\n4. Layer 4: 异常处理\n5. Layer 5: 流程合规\n```\n\n### 步骤 3：分类错误\n\n```markdown\n错误分类：\n- ARCHITECTURE_VIOLATION：架构/分层违规\n- REVIEW_VIOLATION：代码规范问题\n- RUNTIME_FAILURE：测试/运行失败\n- ENVIRONMENT：环境问题\n```\n\n### 步骤 4：生成报告\n\n将验证结果写入 `{项目路径}/.agent/harness/_verification.md`\n\n---\n\n## 5. 输出格式\n\n### 5.1 产物文件\n\n{项目路径}/.agent/harness/_verification.md\n\n### 5.2 模板参考\n\n产物模板定义请参考 [artifacts/template-artifacts.md](../artifacts/template-artifacts.md) 中对应的验证报告模板。\n\n**关键结构要求**：\n- Layer 1: 静态检查结果表格\n- Layer 2: 单元测试结果（通过数/总数）\n- Layer 3: 构建集结果\n- Layer 4: 异常处理场景\n- Layer 5: 流程合规检查\n- 综合判定：PASS/FAIL + 错误分类\n\n---\n\n## 6. 验证标准\n\n### 6.1 通过标准\n\n```markdown\n所有层级通过：\n- Layer 1: 无 Error\n- Layer 2: 所有测试通过\n- Layer 3: 构建成功\n- Layer 4: 所有异常正确处理\n- Layer 5: 所有产物完整\n```\n\n### 6.2 失败处理\n\n```markdown\n如果验证失败：\n1. 分类错误类型\n2. 提供修复建议\n3. 生成详细的验证报告\n4. 决定是否重试\n```\n\n---\n\n## 7. 错误处理\n\n### 7.1 验证工具缺失\n\n```markdown\n如果工具不存在：\n1. 记录警告\n2. 跳过该检查\n3. 在报告中标注\n```\n\n### 7.2 验证超时\n\n```markdown\n如果验证超时：\n1. 记录错误\n2. 标记验证失败\n3. 提供重试建议\n```\n\n---\n\n## 8. 质量审核触发\n\n> 验证完成后，必须触发独立质量审核（独立子Agent盲审模式）。\n\n```markdown\n## 产物完成后的强制操作\n\n- [ ] 1. _verification.md 已写入文件系统\n- [ ] 2. 通知总控执行质量审核（拉起 Quality Auditor 子Agent，进入独立盲审模式）\n- [ ] 3. 审核对象包括：代码文件 + _implementation.md\n- [ ] 4. 如果审核不通过，读取 _quality_audit_verify.md 的\"待修复问题清单\"并修复\n- [ ] 5. 修复后更新产物版本号 → 再次拉起审核\n- [ ] 6. 更新接力棒 quality_audit_verify 状态\n\n**阻断规则**：质量审核不通过 → 不能进入 JUDGE 阶段\n**盲审模式**：子Agent与主对话上下文完全隔离，只读产物文件本身\n```\n\nFile v0.1.0:artifacts/template-artifacts.md\n\n# ReqPlan-v3 产物模板集合\n\n> 本文档包含 ReqPlan-v3 Harness 系统中所有产物文件的模板\n\n---\n\n## 目录\n\n1. [_analysis.md 模板](#一_analysismd-模板)\n2. [_design.md 模板](#二_designmd-模板)\n3. [_implementation.md 模板](#三_implementationmd-模板)\n4. [_verification.md 模板](#四_verificationmd-模板)\n5. [_baton.md 模板](#五_batonmd-模板)\n6. [质量审核报告模板](#六_质量审核报告模板)\n\n---\n\n## 一、_analysis.md 模板\n\n```markdown\n# 需求分析报告\n\n> 产物版本: v1.0 | 最后修改: {ISO 8601} | 修改记录: v1.0 初始版本\n\n## 基本信息\n- 分析时间: {ISO 8601}\n- 分析者: Analyzer Agent\n- 场景类型: {开发/分析/修复}\n- 原始需求: {用户原始描述}\n\n---\n\n## 一、需求理解\n\n### 1.1 核心功能\n| # | 功能点 | 优先级 | 说明 |\n|---|--------|--------|------|\n| 1 | {功能1} | P0 | {说明} |\n| 2 | {功能2} | P1 | {说明} |\n\n### 1.2 涉及角色\n| 角色 | 职责 | 权限 |\n|------|------|------|\n| {角色1} | {职责} | {权限} |\n\n### 1.3 数据实体\n| 实体名 | 核心字段 | 类型 | 说明 |\n|--------|----------|------|------|\n| {实体1} | {字段} | {类型} | {说明} |\n\n---\n\n## 二、技术栈\n\n### 2.1 技术选型\n| 层级 | 技术 | 版本 |\n|------|------|------|\n| 语言 | {Python} | {3.13} |\n| 框架 | {Flask} | {3.x} |\n| 数据库 | {PostgreSQL} | {15} |\n\n### 2.2 项目结构\n```\n{项目目录结构}\n```\n\n---\n\n## 三、涉及文件\n\n### 3.1 需修改的文件\n| 文件 | 修改内容 |\n|------|----------|\n| {文件1} | {修改1} |\n\n### 3.2 需新增的文件\n| 文件 | 用途 |\n|------|------|\n| {文件1} | {用途} |\n\n---\n\n## 四、约束条件\n\n### 4.1 技术约束\n- {约束1}\n\n### 4.2 业务约束\n- {约束1}\n\n### 4.3 时间约束\n- {约束1}\n\n---\n\n## 五、可复用资源\n\n### 5.1 现有代码\n| 资源 | 说明 | 可复用程度 |\n|------|------|-----------|\n| {资源1} | {说明} | {百分比} |\n\n### 5.2 第三方库\n| 库 | 版本 | 用途 |\n|----|------|------|\n| {库1} | {版本} | {用途} |\n\n---\n\n## 六、风险评估\n\n| # | 风险 | 等级 | 缓解措施 |\n|---|------|------|----------|\n| 1 | {风险} | {中} | {措施} |\n\n---\n\n## ⚠️ 产物完成后的强制操作（Analyzer Agent 必须执行）\n\n```markdown\n## 完成后检查清单\n\n- [ ] 1. 本产物已保存到 {项目路径}/.agent/harness/_analysis.md\n- [ ] 2. 产物头部包含版本号（v1.0）\n- [ ] 3. 已确认产物包含所有必需章节（基本信息、需求理解、技术栈、涉及文件、约束条件）\n- [ ] 4. 已触发 Quality Auditor 独立质量审核\n- [ ] 5. 质量审核已通过（或已降级为自检模式）\n- [ ] 6. 已更新接力棒：状态 ANALYZE ✅，下一步 CONFIRM\n\n**阻断规则**：以上任一未勾选 → 不能进入 CONFIRM 阶段\n```\n\n---\n\n*本文档由 Analyzer Agent 自动生成*\n*版本: 4.6 (ReqPlan-v3 v4.6)*\n*时间: {ISO 8601}*\n```\n\n---\n\n## 二、_design.md 模板\n\n```markdown\n# 技术设计文档\n\n> 产物版本: v1.0 | 最后修改: {ISO 8601} | 修改记录: v1.0 初始版本\n\n## 基本信息\n- 设计时间: {ISO 8601}\n- 设计者: Designer Agent\n- 关联分析: _analysis.md\n- 模式: {NORMAL/DESIGN_FIX}\n\n---\n\n## 一、技术方案概述\n\n### 1.1 架构选型\n{架构模式选择及理由}\n\n### 1.2 技术栈\n| 组件 | 技术 | 版本 |\n|------|------|------|\n| 语言 | {Python} | {3.13} |\n| 框架 | {Flask} | {3.x} |\n\n---\n\n## 二、模块划分\n\n### 2.1 模块结构图\n```\n{模块关系图}\n```\n\n### 2.2 模块职责\n| 模块 | 职责 | 依赖 |\n|------|------|------|\n| {模块1} | {职责} | {依赖} |\n\n---\n\n## 三、接口定义\n\n### 3.1 REST API 规范\n\n| # | 路径 | 方法 | 参数 | 响应 |\n|---|------|------|------|------|\n| 1 | /api/users | POST | {body} | {201} |\n\n### 3.2 数据格式\n```json\n{JSON Schema}\n```\n\n---\n\n## 四、数据模型\n\n### 4.1 数据表结构\n| 表名 | 字段 | 类型 | 说明 |\n|------|------|------|------|\n| {表1} | {字段} | {类型} | {说明} |\n\n---\n\n## 五、任务列表\n\n### 5.1 任务表格\n\n| # | 任务 | 涉及文件 | 验证方式 | 依赖 | 优先级 |\n|---|------|---------|---------|------|--------|\n| 1 | {任务1} | {文件} | {验证} | {无} | P0 |\n| 2 | {任务2} | {文件} | {验证} | {任务1} | P0 |\n\n### 5.2 实施顺序\n1. {任务1}\n2. {任务2}\n\n---\n\n## 六、验证方案\n\n### 6.1 Layer 1: 静态检查\n- 工具: pylint / ruff / mypy\n- 命令: `ruff check .`\n- 验收标准:\n - 无致命错误（Error）\n - 警告（Warning）数量 ≤ 5\n - 代码风格符合 PEP 8\n\n### 6.2 Layer 2: 单元测试\n- 框架: pytest\n- 命令: `pytest tests/ -v`\n- 验收标准:\n - 所有测试通过\n - 覆盖率 ≥ 80%（P0 功能）\n\n### 6.3 Layer 3: 构建集成\n- 命令: `python -m py_compile app.py`\n- 复杂项目额外检查:\n - `pip install -r requirements.txt`\n - `python setup.py check`（如有 setup.py）\n - `pip install -e .`（如有 pyproject.toml）\n- 验收标准:\n - 编译无错误\n - 依赖安装成功\n\n### 6.4 Layer 4: 异常处理\n- Web 项目测试场景:\n - 401 未授权 → {\"error\": \"Unauthorized\"}\n - 403 禁止访问 → {\"error\": \"Forbidden\"}\n - 404 资源不存在 → {\"error\": \"Not Found\"}\n - 400 参数错误 → {\"error\": \"Bad Request\"}\n- 通用项目测试场景:\n - 空输入/空值处理\n - 类型错误处理\n - 边界条件处理\n - 资源不存在处理\n- 验收标准:\n - 所有异常场景正确处理\n - 错误信息清晰\n\n### 6.5 Layer 5: 流程合规\n- 产物完整性检查:\n - _analysis.md 存在且完整\n - _design.md 存在且完整\n - _implementation.md 存在且完整\n- 文档更新检查:\n - README 更新\n - API 文档更新\n - 代码注释完整\n\n---\n\n## ⚠️ 产物完成后的强制操作（Designer Agent 必须执行）\n\n```markdown\n## 完成后检查清单\n\n- [ ] 1. 本产物已保存到 {项目路径}/.agent/harness/_design.md\n- [ ] 2. 已触发 Quality Auditor 独立质量审核（拉起子Agent审核 _design.md）\n- [ ] 3. 质量审核已通过（或已降级为自检模式）\n- [ ] 4. 已更新接力棒：状态 DESIGN ✅，下一步 IMPLEMENT\n- [ ] 5. 已确认任务列表包含\"涉及文件\"和\"验证方式\"列\n- [ ] 6. 已确认验证方案包含 Layer 1-5\n\n**阻断规则**：以上任一未勾选 → 不能进入 IMPLEMENT 阶段\n```\n\n---\n\n*本文档由 Designer Agent 自动生成*\n*版本: 4.6 (ReqPlan-v3 v4.6)*\n*时间: {ISO 8601}*\n```\n\n---\n\n## 三、_implementation.md 模板\n\n```markdown\n# 实现摘要\n\n> 产物版本: v1.0 | 最后修改: {ISO 8601} | 修改记录: v1.0 初始版本\n\n## 基本信息\n- 实现时间: {ISO 8601}\n- 实现者: Implementer Agent\n- 模式: {NORMAL/REVIEW_FIX/RETRY_FIX}\n\n---\n\n## 一、完成的任务\n\n| # | 任务 | 状态 | 文件 | 备注 |\n|---|------|------|------|------|\n| 1 | {任务1} | ✅ | {文件} | {备注} |\n| 2 | {任务2} | ✅ | {文件} | {备注} |\n\n---\n\n## 二、涉及的文件\n\n### 2.1 新增文件\n| 文件 | 用途 |\n|------|------|\n| {文件1} | {用途} |\n\n### 2.2 修改文件\n| 文件 | 修改内容 |\n|------|----------|\n| {文件1} | {修改} |\n\n---\n\n## 三、问题记录\n\n### 3.1 已解决的问题\n| # | 问题 | 解决方案 |\n|---|------|----------|\n| 1 | {问题} | {方案} |\n\n### 3.2 未解决的问题\n| # | 问题 | 影响 | 建议 |\n|---|------|------|------|\n| 1 | {问题} | {影响} | {建议} |\n\n---\n\n## ⚠️ 产物完成后的强制操作（Implementer Agent 必须执行）\n\n```markdown\n## 完成后检查清单\n\n- [ ] 1. 本产物已保存到 {项目路径}/.agent/harness/_implementation.md\n- [ ] 2. 已触发 Quality Auditor 独立质量审核（拉起子Agent审核 _implementation.md）\n- [ ] 3. 质量审核已通过（或已降级为自检模式）\n- [ ] 4. 已更新接力棒：状态 IMPLEMENT ✅，下一步 VERIFY\n- [ ] 5. 已确认所有代码已保存到文件系统（不是只在对话中）\n- [ ] 6. 已确认所有设计中的任务都已完成（或明确标记为未完成）\n- [ ] 7. 修改/新增文件清单与实际写入的文件一致\n\n**阻断规则**：以上任一未勾选 → 不能进入 VERIFY 阶段\n```\n\n---\n\n*本文档由 Implementer Agent 自动生成*\n*版本: 4.6 (ReqPlan-v3 v4.6)*\n*时间: {ISO 8601}*\n```\n\n---\n\n## 四、_verification.md 模板\n\n```markdown\n# 验证报告\n\n> 产物版本: v1.0 | 最后修改: {ISO 8601} | 修改记录: v1.0 初始版本\n\n## 基本信息\n- 验证时间: {ISO 8601}\n- 验证者: Verifier Agent\n- 关联设计: _design.md\n\n---\n\n## Layer 1: 静态检查\n\n### 1.1 工具结果\n| 工具 | 命令 | 结果 |\n|------|------|------|\n| pylint | `pylint app.py` | ✅ 通过 / ❌ 失败 |\n| ruff | `ruff check .` | ✅ 通过 / ❌ 失败 |\n| mypy | `mypy app.py` | ✅ 通过 / ❌ 失败 |\n\n### 1.2 违规列表\n| # | 问题 | 文件 | 行号 | 类型 |\n|---|------|------|------|------|\n| 1 | {问题} | {文件} | {行号} | {WARNING/ERROR} |\n\n---\n\n## Layer 2: 单元测试\n\n### 2.1 测试结果\n- 测试框架: pytest\n- 总测试数: {数量}\n- 通过数: {数量}\n- 失败数: {数量}\n- 覆盖率: {百分比}\n\n### 2.2 失败的测试\n| # | 测试 | 错误 |\n|---|------|------|\n| 1 | {测试名} | {错误信息} |\n\n---\n\n## Layer 3: 构建集成\n\n### 3.1 构建结果\n| 命令 | 结果 |\n|------|------|\n| `python -m py_compile` | ✅ 通过 / ❌ 失败 |\n| `pip install -r requirements.txt` | ✅ 通过 / ❌ 失败 |\n\n### 3.2 失败详情\n```\n{错误信息}\n```\n\n---\n\n## Layer 4: 异常处理\n\n### 4.1 测试场景\n| # | 场景 | 预期 | 实际 | 状态 |\n|---|------|------|------|------|\n| 1 | 401 未授权 | 401 | 401 | ✅ |\n| 2 | 403 禁止访问 | 403 | 403 | ✅ |\n| 3 | 404 资源不存在 | 404 | 404 | ✅ |\n| 4 | 400 参数错误 | 400 | 400 | ✅ |\n\n### 4.2 失败场景\n| # | 场景 | 预期 | 实际 | 问题 |\n|---|------|------|------|------|\n| 1 | {场景} | {预期} | {实际} | {问题} |\n\n---\n\n## Layer 5: 流程合规\n\n### 5.1 产物检查\n| # | 产物 | 存在 | 完整 |\n|---|------|------|------|\n| 1 | _analysis.md | ✅ | ✅ |\n| 2 | _design.md | ✅ | ✅ |\n| 3 | _implementation.md | ✅ | ✅ |\n\n### 5.2 文档检查\n| # | 检查项 | 状态 |\n|---|--------|------|\n| 1 | README 更新 | ✅ |\n| 2 | API 文档更新 | ✅ |\n\n---\n\n## 综合判定\n\n### 判定结果\n**状态**: ✅ PASS / ❌ FAIL\n\n### 错误分类\n| # | 错误类型 | 数量 | 详情 |\n|---|----------|------|------|\n| 1 | ARCHITECTURE_VIOLATION | 0 | 架构/分层违规 |\n| 2 | REVIEW_VIOLATION | 0 | 代码规范问题 |\n| 3 | RUNTIME_FAILURE | 0 | 测试/运行失败 |\n| 4 | ENVIRONMENT | 0 | 环境问题 |\n\n### 下一步\n- PASS → JUDGE → DONE ✅\n- ARCHITECTURE → JUDGE → DESIGN(修复)\n- REVIEW → JUDGE → IMPLEMENT(修复)\n- RUNTIME & retry < 2 → JUDGE → IMPLEMENT(重试)\n- retry >= 2 → JUDGE → FAILED ❌\n\n---\n\n## ⚠️ 产物完成后的强制操作（Verifier Agent 必须执行）\n\n```markdown\n## 完成后检查清单\n\n- [ ] 1. 本产物已保存到 {项目路径}/.agent/harness/_verification.md\n- [ ] 2. 已触发 Quality Auditor 独立质量审核（拉起子Agent审核代码 + _implementation.md）\n- [ ] 3. 质量审核已通过（或已降级为自检模式）\n- [ ] 4. 已更新接力棒：状态 VERIFY ✅，下一步 JUDGE\n- [ ] 5. 已确认综合判定为明确的 PASS 或 FAIL\n- [ ] 6. 如果 FAIL，已确认错误分类（ARCHITECTURE/REVIEW/RUNTIME/ENVIRONMENT）\n\n**阻断规则**：以上任一未勾选 → 不能进入 JUDGE 阶段\n```\n\n---\n\n*本文档由 Verifier Agent 自动生成*\n*版本: 4.6 (ReqPlan-v3 v4.6)*\n*时间: {ISO 8601}*\n```\n\n---\n\n## 五、_baton.md 模板\n\n```markdown\n# 🔄 ReqPlan-v3 接力棒\n\n## 元信息\n\n| 字段 | 值 |\n|------|-----|\n| 项目 | {项目名称} |\n| 开始时间 | {ISO 8601} |\n| 最后更新 | {ISO 8601} |\n| 当前状态 | {START/ANALYZE/CONFIRM/DESIGN/IMPLEMENT/VERIFY/JUDGE/DONE/ABORT/FAILED} |\n| 模式 | {NORMAL/DESIGN_FIX/REVIEW_FIX/RETRY_FIX} |\n| 重试计数 | {0/1/2} |\n| design_fix_retry | {0/1/2} |\n\n## 质量审核追踪\n\n| 审核阶段 | 状态 | 分数 | 重试次数 | 报告文件 |\n|---------|------|------|---------|---------|\n| quality_audit_analysis | 未审核/已通过/已打回 | - | 0/2 | - |\n| quality_audit_design | 未审核/已通过/已打回 | - | 0/2 | - |\n| quality_audit_implement | 未审核/已通过/已打回 | - | 0/2 | - |\n| quality_audit_verify | 未审核/已通过/已打回 | - | 0/2 | - |\n| quality_audit_judge | 未审核/已通过/已打回 | - | - | - |\n\n## 进度追踪\n\n### 阶段完成情况\n\n- [ ] START - 启动\n- [ ] ANALYZE - 分析\n- [ ] CONFIRM - 确认\n- [ ] DESIGN - 设计\n- [ ] IMPLEMENT - 实现\n- [ ] VERIFY - 验证\n- [ ] JUDGE - 判断\n\n### 产物清单\n\n- [ ] `.agent/harness/_analysis.md` - 分析报告\n- [ ] `.agent/harness/_quality_audit_analysis.md` - 分析质量审核报告\n- [ ] `.agent/harness/_design.md` - 设计文档\n- [ ] `.agent/harness/_quality_audit_design.md` - 设计质量审核报告\n- [ ] `.agent/harness/_implementation.md` - 实现摘要\n- [ ] `.agent/harness/_quality_audit_implement.md` - 实现质量审核报告\n- [ ] `.agent/harness/_verification.md` - 验证报告\n- [ ] `.agent/harness/_quality_audit_verify.md` - 验证质量审核报告\n- [ ] `.agent/harness/_quality_audit_judge.md` - 最终全局判定报告\n\n### ⭐ 任务追踪\n\n> 所有任务状态统一在此管理。\n\n| # | 任务名称 | 状态 | 完成时间 | 备注 |\n|---|---------|------|---------|------|\n| 1 | {任务1} | ✅ 完成 | {时间} | {备注} |\n| 2 | {任务2} | 🔄 进行中 | - | {备注} |\n| 3 | {任务3} | ⏳ 待开始 | - | {备注} |\n\n## 当前阶段详情\n\n### {状态名称}\n\n**进度**: {百分比}%\n**已完成任务**: {列表}\n**进行中任务**: {任务}\n**待完成任务**: {列表}\n\n## 问题记录\n\n### ⚠️ 阻塞问题\n{问题列表}\n\n### 💡 待确认事项\n{待确认事项}\n\n## 下一步行动\n\n### 立即执行（Next）\n1. {任务1}\n2. {任务2}\n\n---\n\n*最后更新: {ISO 8601}*\n```\n\n---\n\n---\n\n## 六、质量审核报告模板\n\n### 6.1 审核报告通用模板\n\n```markdown\n# 质量审核报告 - {阶段名}\n\n## 基本信息\n- 审核时间: {ISO 8601}\n- 审核对象: {产物文件路径}\n- 审核轮次: {第N次审核}\n- 审核等级: {L1/L2/L3}\n- 模式: {正常审核 / 自检模式（降级）}\n\n## 一、阻断检查结果\n| # | 阻断项 | 状态 | 证据引用 |\n|---|--------|------|---------|\n| 1 | {阻断项描述} | ✅ 无阻断 / ❌ 有阻断 | {产物中的具体引用} |\n\n## 二、各维度评分\n\n### 维度①：{维度名}（权重{百分比}%）\n- 得分: {分数}/100\n- 扣分明细:\n | # | 扣分项 | 扣分 | 原因 | 引用来源 |\n |---|--------|------|------|---------|\n | 1 | {缺失内容} | -{分数} | {为什么是问题} | {产物中的对应段落} |\n\n### 维度②：...\n（以此类推）\n\n## 三、综合评分\n- 加权总分: {计算过程} = {最终分数}\n- 等级: A/B/C/D\n- 判定: ✅ 通过 / ❌ 打回修复 / ❌ 打回重做\n\n## 四、待修复问题清单\n\n### P0 - 必须修复（严重问题）\n| # | 问题描述 | 所在位置 | 建议修复方案 | ✅ 修复验证（重审时填写） |\n|---|---------|---------|-------------|------------------------|\n| 1 | {问题描述} | {产物中的具体章节或行号} | {修复指引} | 是否已修复: ✅/❌ 证据: {引用} |\n\n### P1 - 建议完善\n| # | 问题描述 | 所在位置 | 建议修复方案 | ✅ 修复验证（重审时填写） |\n|---|---------|---------|-------------|------------------------|\n| 1 | {问题描述} | {产物中的具体章节或行号} | {修复指引} | 是否已修复: ✅/❌ 证据: {引用} |\n\n## 五、评分分布监控（由主Agent检查）\n- 本次评分: {分数}\n- 历史评分分布: {分数1}, {分数2}, {分数3}\n- 是否触发告警: 是/否（连续3次≥90）\n- 告警原因: {如果有}\n\n---\n\n*报告版本: 1.0 | 由 Quality Auditor Agent 自动生成*\n```\n\n### 6.2 文件命名规则\n\n| 轮次 | 文件名 | 说明 |\n|------|--------|------|\n| 第1次审核 | `_quality_audit_{phase}.md` | 首次审核（phase=analysis/design/implement/verify/judge） |\n| 第1次修复后重审 | `_quality_audit_{phase}_v2.md` | 重试第1次 |\n| 第2次修复后重审 | `_quality_audit_{phase}_v3.md` | 重试第2次（之后FAILED） |\n\n> 各阶段（analysis/design/implement/verify/judge）的命名规则同理。\n\n### 6.3 产物完成后的强制操作（Quality Auditor Agent 必须执行）\n\n```markdown\n## 完成后检查清单\n\n- [ ] 1. 本产物已保存到 {项目路径}/.agent/harness/_quality_audit_{phase}.md\n- [ ] 2. 审核报告包含\"阻断检查结果\"章节\n- [ ] 3. 审核报告包含\"各维度评分\"章节（L1模式可省略）\n- [ ] 4. 审核报告包含\"综合评分\"章节（L1模式可省略）\n- [ ] 5. 审核报告包含\"待修复问题清单\"章节（通过时可省略）\n- [ ] 6. 包含\"评分分布监控\"章节\n- [ ] 7. 每个扣分项有明确的引用来源\n\n**阻断规则**：以上任一未勾选 → 审核报告无效\n```\n\nFile v0.1.0:protocols/baton-protocol.md\n\n# ReqPlan-v3 接力棒协议\n\n> **核心原则**：接力棒文件是跨 Session 的唯一真相来源。每次交互结束后，必须更新接力棒。\n\n---\n\n## 一、为什么需要接力棒\n\n传统 Skill 的问题：\n- ❌ 每个 Session 都是全新的\n- ❌ 用户中断后无法续跑\n- ❌ 进度丢失，需要重新开始\n- ❌ 产物分散，难以追踪\n\n接力棒机制的优势：\n- ✅ 状态持久化到文件系统\n- ✅ 任何时候都可以续跑\n- ✅ 产物和进度一目了然\n- ✅ 支持多人协作\n\n---\n\n## 二、接力棒文件规范\n\n### 2.1 文件位置\n\n```\n{项目路径}/.agent/harness/_baton.md\n```\n\n### 2.2 命名规则\n\n- 前缀 `_baton.md` 表示内部状态文件\n- 位置固定在 `.agent/harness/` 目录下\n\n---\n\n## 三、接力棒文件模板\n\n### 3.1 START 阶段最小化模板（首次创建用）\n\nSTART 阶段只需创建以下简化版本（~30 行），随着阶段推进逐步扩展为完整模板：\n\n```markdown\n# 🔄 ReqPlan-v3 接力棒\n\n## 元信息\n\n| 字段 | 值 |\n|------|-----|\n| 项目 | {项目名称} |\n| 开始时间 | {ISO 8601} |\n| 最后更新 | {ISO 8601} |\n| 当前状态 | START |\n| 模式 | NORMAL |\n\n## 进度追踪\n\n### 阶段完成情况\n\n- [ ] START - 启动\n- [ ] ANALYZE - 分析\n- [ ] CONFIRM - 确认\n- [ ] DESIGN - 设计\n- [ ] IMPLEMENT - 实现\n- [ ] VERIFY - 验证\n- [ ] JUDGE - 判断\n```\n\n进入 ANALYZE 阶段时，扩展为下方的完整模板（增加质量审核追踪、产物清单、任务追踪等）。\n\n### 3.2 完整模板（ANALYZE 起使用）\n\n```markdown\n# 🔄 ReqPlan-v3 接力棒\n\n## 元信息\n\n| 字段 | 值 |\n|------|-----|\n| 项目 | {项目名称} |\n| 开始时间 | {ISO 8601} |\n| 最后更新 | {ISO 8601} |\n| 当前状态 | {START/ANALYZE/CONFIRM/DESIGN/IMPLEMENT/VERIFY/JUDGE/DONE/ABORT/FAILED} |\n| 模式 | {NORMAL/DESIGN_FIX/REVIEW_FIX/RETRY_FIX} |\n| 重试计数 | {0/1/2} |\n| design_fix_retry | {0/1/2} |\n\n## 质量审核追踪\n\n| 审核阶段 | 状态 | 分数 | 重试次数 | 报告文件 |\n|---------|------|------|---------|---------|\n| quality_audit_analysis | 未审核/已通过/已打回 | - | 0/2 | - |\n| quality_audit_design | 未审核/已通过/已打回 | - | 0/2 | - |\n| quality_audit_implement | 未审核/已通过/已打回 | - | 0/2 | - |\n| quality_audit_verify | 未审核/已通过/已打回 | - | 0/2 | - |\n| quality_audit_judge | 未审核/已通过/已打回 | - | - | - |\n\n## 进度追踪\n\n### 阶段完成情况\n\n- [ ] START - 启动\n- [ ] ANALYZE - 分析\n- [ ] CONFIRM - 确认\n- [ ] DESIGN - 设计\n- [ ] IMPLEMENT - 实现\n- [ ] VERIFY - 验证\n- [ ] JUDGE - 判断\n\n### 产物清单\n\n- [ ] `.agent/harness/_analysis.md` - 分析报告\n- [ ] `.agent/harness/_design.md` - 设计文档\n- [ ] `.agent/harness/_implementation.md` - 实现摘要\n- [ ] `.agent/harness/_verification.md` - 验证报告\n- [ ] `.agent/harness/_quality_audit_analysis.md` - 分析审核报告\n- [ ] `.agent/harness/_quality_audit_design.md` - 设计审核报告\n- [ ] `.agent/harness/_quality_audit_implement.md` - 实现审核报告\n- [ ] `.agent/harness/_quality_audit_verify.md` - 验证审核报告\n- [ ] `.agent/harness/_quality_audit_judge.md` - 最终判定报告\n\n### ⭐ 任务追踪（统一管理）\n\n> **重要**：所有任务状态统一在 baton.md 中管理，不再使用独立的 tasks.md 文件。\n\n| # | 任务名称 | 状态 | 完成时间 | 备注 |\n|---|---------|------|---------|------|\n| 1 | {任务1} | ✅ 完成 | {时间} | {备注} |\n| 2 | {任务2} | 🔄 进行中 | - | {备注} |\n| 3 | {任务3} | ⏳ 待开始 | - | {备注} |\n\n**任务状态说明**：\n- ✅ 完成：任务已完成\n- 🔄 进行中：任务正在执行\n- ⏳ 待开始：任务还未开始\n- ❌ 失败：任务执行失败\n\n## 当前阶段详情\n\n### {状态名称}\n\n**进度**: {百分比}%\n**已完成任务**: {列表}\n**进行中任务**: {任务}\n**待完成任务**: {列表}\n\n## 问题记录\n\n### ⚠️ 阻塞问题\n{问题列表}\n\n### 💡 待确认事项\n{待确认事项}\n\n## 下一步行动\n\n### 立即执行（Next）\n1. {任务1}\n2. {任务2}\n3. {任务3}\n\n---\n\n*最后更新: {ISO 8601}*\n```\n\n---\n\n## 四、接力棒生命周期\n\n### 4.1 更新时机\n\n⚠️ **必须更新的时机**：\n\n| # | 时机 | 必须执行 | 优先级 |\n|---|------|----------|--------|\n| 1 | 阶段开始时 | 更新状态为\"进行中\" | 高 |\n| 2 | 阶段完成时 | 标记阶段为完成 | 高 |\n| 3 | 用户交互后 | 记录用户反馈 | 高 |\n| 4 | 产物生成后 | 更新产物清单 | 高 |\n| 5 | 遇到问题时 | 记录到问题记录 | 高 |\n\n> **注意**：不需要在每次工具调用后更新，只需在上述关键时机更新。阶段内多次工具调用可在阶段完成时统一更新。\n\n---\n\n## 五、接力棒读写流程\n\n### 5.1 完整交互流程\n\n```\n用户输入 → 读取接力棒 → 识别状态 → 执行阶段 → 更新接力棒 → 响应用户\n ↑\n ┌─────────────────┐\n | ⚠️ 必须执行！ |\n | 即使任务失败 |\n | 也要记录进度 |\n └─────────────────┘\n```\n\n---\n\n## 六、续跑流程\n\n### 6.1 续跑检查\n\n```bash\n# 1. 读取接力棒\nread {项目路径}/.agent/harness/_baton.md\n\n# 2. 识别当前状态\n当前状态: {状态}\n\n# 3. 续跑检查清单\n- [ ] 接力棒文件存在\n- [ ] 所有已完成产物存在\n- [ ] 用户意图明确\n- [ ] 有明确的下一步\n```\n\n---\n\n## 七、状态流转\n\n```\nSTART → ANALYZE → CONFIRM → DESIGN → IMPLEMENT → VERIFY → JUDGE\n ↑ │ ↓\n └────────┘ ┌─────────────────┼─────────────────┐\n (修改) ↓ ↓ ↓\n ✅ DONE 🔧 DESIGN 🔄 IMPLEMENT\n (修复模式) (重试模式)\n\nCONFIRM 分支:\n- ✅ 确认 → DESIGN\n- ✏️ 修改 → ANALYZE\n- ❌ 取消 → ABORT\n\n终止状态: DONE, ABORT, FAILED\n```\n\n### 7.1 续跑映射\n\n| 当前状态 | 读取文件 | 继续执行 |\n|---------|---------|---------|\n| ANALYZE | _analysis.md | 继续分析 |\n| CONFIRM | _analysis.md | 等待确认 |\n| DESIGN | _design.md | 继续设计 |\n| IMPLEMENT | _design.md | 继续实现 |\n| VERIFY | _verification.md | 继续验证 |\n| JUDGE | _verification.md | 判断 |\n\n---\n\n## 八、快速参考\n\n### 接力棒命令速查\n\n```bash\n# 读取接力棒\nread {项目路径}/.agent/harness/_baton.md\n\n# 更新接力棒\nwrite {项目路径}/.agent/harness/_baton.md\n\n# 检查产物\nls -la {项目路径}/.agent/harness/\n```\n\nFile v0.1.0:quality-control/00-quality-system.md\n\n# 质量审核体系定义\n\n> 本文档定义了 ReqPlan-v3 Harness 系统的独立质量审核标准。\n> 所有审核子Agent(Quality Auditor)以此文档为唯一评分依据。\n\n---\n\n## 一、审核的三级递进判定体系\n\n每个审核关卡执行**三级递进判定**：\n\n```\n第1级: 阻断检查（一票否决）\n → 发现任何阻断项 → 直接 FAIL，不再评分\n → 必须引用产物具体内容作为证据\n\n第2级: 维度评分（量化评估）\n → 按 N 个维度分别打分（0-100分）\n → 每个维度有明确的可检查项列表\n → 每个扣分项必须指定扣分理由并引用产物具体内容\n\n第3级: 综合判定（等级评定）\n → A级(≥90分): 优秀，直接通过\n → B级(75-89分): 良好，有条件通过（需标注待改进项）\n → C级(60-74分): 及格，打回修复后重新审核\n → D级(<60分或阻断): 不合格，打回重做\n```\n\n---\n\n## 二、分析阶段审核维度\n\n**审核对象**：_analysis.md\n\n### 维度①：业务影响链路完整性（权重25%）\n\n| 检查项 | 扣分规则 |\n|--------|---------|\n| 功能变更追溯 | 遗漏1个模块 → 扣15分 |\n| 依赖关系图谱 | 无依赖图 → 扣20分 |\n| 级联影响分析 | 未做二级以上分析 → 扣15分 |\n| 回归范围圈定 | 未圈定 → 扣10分 |\n\n**过关标准**：\n- ✅ 过关：依赖链至少追溯到2层以上，明确标注回归范围\n- ❌ 不过关：只列了直接涉及的模块，没有做链路追溯\n\n### 维度②：上下游校验完整度（权重20%）\n\n| 检查项 | 扣分规则 |\n|--------|---------|\n| 上游输入校验 | 遗漏来源 → 扣15分 |\n| 下游输出校验 | 遗漏去向 → 扣15分 |\n| 数据流转路径 | 路径断点 → 扣10分 |\n| 接口契约变化 | 未识别 → 扣20分 |\n\n**过关标准**：\n- ✅ 过关：输入来源和输出去向全部识别，接口变化逐项标注\n- ❌ 不过关：只描述模块本身功能，没说数据从哪来到哪去\n\n### 维度③：边界兼容与异常兜底（权重25%）\n\n| 检查项 | 扣分规则 |\n|--------|---------|\n| 边界条件枚举 | 缺边界场景 → 扣10分/个 |\n| 兼容性分析 | 未评估 → 扣15分 |\n| 异常兜底策略 | 无兜底 → 扣20分 |\n| 数据一致性保障 | 未提及 → 扣15分 |\n\n**过关标准**：\n- ✅ 过关：边界场景≥3个，有明确的向前兼容方案，有失败兜底策略\n- ❌ 不过关：只说\"正常流程\"，没提边界和异常\n\n### 维度④：风险预判与依赖追溯（权重30%）\n\n| 检查项 | 扣分规则 |\n|--------|---------|\n| 依赖链完整追溯 | 断链 → 扣20分 |\n| 连锁风险预判 | 无预判 → 扣20分 |\n| 风险等级界定 | 无分级 → 扣10分 |\n| 缓解/回退方案 | 无方案 → 扣15分 |\n\n**过关标准**：\n- ✅ 过关：每个高/中风险有缓解方案，回退方案明确可执行\n- ❌ 不过关：只列风险不列方案\n\n---\n\n## 三、设计阶段审核维度\n\n**审核对象**：_design.md\n\n### 维度①：架构一致性（权重30%）\n\n| 检查项 | 扣分规则 |\n|--------|---------|\n| 架构模式匹配 | 不符 → 扣20分 |\n| 分层合理性 | 跨层调用 → 扣15分/处 |\n| 依赖方向正确性 | 循环依赖 → **阻断** |\n| 模块内聚性 | 不合理聚合 → 扣10分 |\n\n**阻断条件**：\n```\n⚠️ 循环依赖: moduleA → moduleB → moduleA → 阻断\n⚠️ 反模式: Controller直接操作Repository → 阻断\n⚠️ 职责混淆: 一个类既做数据校验又做日志又做业务计算 → 扣大分\n```\n\n### 维度②：模块边界清晰度（权重25%）\n\n| 检查项 | 扣分规则 |\n|--------|---------|\n| 接口定义完备性 | 缺定义 → 扣10分/个 |\n| 模块职责单一 | 职责模糊 → 扣15分 |\n| 依赖外部化 | 直接依赖实现 → 扣10分 |\n| 扩展性预留 | 未考虑 → 扣5分 |\n\n### 维度③：接口完整定义（权重25%）\n\n| 检查项 | 扣分规则 |\n|--------|---------|\n| RESTful规范 | 不规范 → 扣10分 |\n| 参数校验 | 缺校验 → 扣10分/个 |\n| 异常响应定义 | 缺定义 → 扣15分 |\n| 数据模型完整 | 缺字段 → 扣5分/个 |\n\n### 维度④：任务可执行性（权重20%）\n\n| 检查项 | 扣分规则 |\n|--------|---------|\n| 任务粒度合理 | 过度耦合 → 扣10分 |\n| 依赖关系明确 | 缺依赖 → 扣10分 |\n| 验收标准具体 | 模糊标准 → 扣10分 |\n| 涉及文件精确 | 模糊路径 → 扣5分 |\n\n---\n\n## 四、实现阶段审核维度\n\n**审核对象**：_implementation.md\n\n### 维度①：设计覆盖度（权重30%）\n\n| 检查项 | 扣分规则 |\n|--------|---------|\n| 任务完整实现 | 遗漏1个任务 → 扣20分 |\n| 功能点对应 | 无法对应设计文档 → 扣15分 |\n| 设计约束遵守 | 违反约束 → 扣15分 |\n\n**过关标准**：\n- ✅ 过关：所有设计文档中的任务在实现摘要中都有对应条目\n- ❌ 不过关：有设计任务未在实现摘要中提及或明确标记未实现\n\n### 维度②：代码规范性（权重25%）\n\n| 检查项 | 扣分规则 |\n|--------|---------|\n| 文件保存完整性 | 代码未保存 → **阻断** |\n| 代码风格一致性 | 严重偏离项目风格 → 扣15分 |\n| 注释与文档 | 缺少必要注释 → 扣10分 |\n\n**过关标准**：\n- ✅ 过关：所有代码文件已保存到磁盘，风格与项目一致\n- ❌ 不过关：有代码文件未保存到磁盘\n\n### 维度③：完整性（权重25%）\n\n| 检查项 | 扣分规则 |\n|--------|---------|\n| 新增文件列全 | 遗漏文件 → 扣20分 |\n| 修改文件追溯 | 未列出修改文件 → 扣15分 |\n| 依赖变更记录 | 未记录新增依赖 → 扣10分 |\n\n**过关标准**：\n- ✅ 过关：所有新增和修改的文件都在实现摘要中完整列出\n- ❌ 不过关：有文件变更未在实现摘要中记录\n\n### 维度④：一致性（权重20%）\n\n| 检查项 | 扣分规则 |\n|--------|---------|\n| 设计与实现一致性 | 实现偏离设计 → 扣20分 |\n| 技术栈一致性 | 使用了未约定的技术 → 扣15分 |\n| 接口签名匹配 | 接口签名不一致 → 扣15分 |\n\n**过关标准**：\n- ✅ 过关：实现内容与设计文档中的约束条件和技术选型一致\n- ❌ 不过关：实现使用了设计文档未约定的技术或框架\n\n---\n\n## 五、验证阶段审核维度\n\n**审核对象**：代码文件 + _implementation.md\n\n### 维度①：设计一致性（权重30%）\n\n| 检查项 | 扣分规则 |\n|--------|---------|\n| 接口实现匹配 | 不一致 → 扣20分 |\n| 数据模型匹配 | 不一致 → 扣15分 |\n| 业务逻辑正确性 | 逻辑错误 → **阻断** |\n| 命名规范一致性 | 不一致 → 扣5分/处 |\n\n### 维度②：代码质量（权重30%）\n\n| 检查项 | 扣分规则 |\n|--------|---------|\n| 错误处理完整性 | 未处理异常 → 扣15分/处 |\n| 日志记录充分性 | 缺日志 → 扣10分/处 |\n| 并发安全 | 缺少并发保护 → **阻断** |\n| 性能考量 | 性能问题 → 扣10分/处 |\n| 安全合规 | 安全漏洞 → **阻断** |\n| 代码可读性 | 复杂度过高 → 扣10分 |\n\n### 维度③：测试覆盖（权重25%）\n\n| 检查项 | 扣分规则 |\n|--------|---------|\n| 核心逻辑测试 | 未覆盖 → 扣20分 |\n| 边界条件测试 | 缺边界 → 扣10分/类 |\n| 异常路径测试 | 缺异常测试 → 扣15分 |\n| 测试独立性 | 依赖链 → 扣10分 |\n\n### 维度④：流程合规（权重15%）\n\n| 检查项 | 扣分规则 |\n|--------|---------|\n| 产物完整性 | 缺失 → 扣10分/个 |\n| lint规范 | 有error → 扣10分 |\n| 构建通过 | 构建失败 → **阻断** |\n\n---\n\n## 六、JUDGE阶段全局审核维度\n\n**审核对象**：所有产物\n\n| 维度 | 权重 | 评分依据 |\n|------|------|---------|\n| ① 需求分析质量 | 20% | _analysis.md 的分析深度、影响链路完整度、风险预判质量 |\n| ② 架构设计质量 | 20% | _design.md 的架构合理性、模块边界清晰度、接口完备性 |\n| ③ 代码实现质量 | 20% | 代码可读性、错误处理、性能、安全、命名 |\n| ④ 测试覆盖质量 | 15% | 覆盖率、边界测试、异常测试、独立性 |\n| ⑤ 验证报告质量 | 15% | _verification.md 的完整性、判定准确性 |\n| ⑥ 流程规范遵守 | 10% | 是否遵循了状态机、是否更新了接力棒、产物是否完整 |\n\n### 全局阻断条件（一票否决）\n\n- 存在任何未被修复的安全漏洞\n- 核心业务逻辑存在严重缺陷\n- 存在循环依赖或架构反模式\n- 存在明文密钥/密码硬编码\n- 构建/编译完全失败且无法修复\n\n---\n\n## 七、审核等级（L1/L2/L3）\n\n| 等级 | 适用场景 | 审核维度 | 审核方式 |\n|---------|---------|---------|---------|\n| **L1 - 快速检查** | 注释修改、简单参数调整、纯配置变更 | 仅检查阻断条件 | 主Agent自检，不拉起子Agent |\n| **L2 - 标准审核** | 单模块功能新增/修改、非核心逻辑变更 | 维度①+④ 或 维度②+③（按需选择2个） | 拉起子Agent，但只审关键维度 |\n| **L3 - 完整审核** | 跨模块变更、架构调整、核心逻辑重构、API变更 | 全部4个维度 | 拉起子Agent，完整审核 |\n\n---\n\n## 八、修复验证闭环规则\n\n### 重审时子Agent的检查逻辑\n\n```\n1. 读取上次审核报告，获取\"待修复问题清单\"\n2. 逐一检查产物中的对应位置\n3. 对每个问题：\n - 如果确实修复了 → 标记 ✅，记录证据引用\n - 如果没修复或只修了表面 → 标记 ❌，继续扣分\n4. 存在任一 ❌ 未修复项 → 判定为\"假修复\" → 整体不通过\n```\n\n### 产物版本号检查\n\n审核子Agent检查项增加：\n- [ ] 产物是否包含版本号？\n- [ ] 如果是重审轮次，产物版本号是否已递增？\n- [ ] 上次审核报告的P0问题是否已全部得到回应？\n\n---\n\n## 九、审核\"假通过\"防御机制\n\n### 防御1：评分必须引用产物具体内容（硬性要求）\n```\n❌ 无效评分：\"业务影响链路完整，给90分\"\n✅ 有效评分：\"业务影响链路追溯了3层依赖（具体见第2章第3节的依赖图），\n 标注了回归范围（用户/订单/支付模块），给90分\"\n```\n\n### 防御2：阻断判定必须证据引用\n```\n❌ 无效阻断：\"存在安全风险，阻断\"\n✅ 有效阻断：\"第5行代码 user_input = request.args.get('name') 直接拼接SQL，\n 存在SQL注入风险，阻断。引用：_analysis.md 第3章第1节\"\n```\n\n### 防御3：综合评分分布监控\n- 如果连续3次审核均给出 ≥90分（A级），触发\"评分偏移\"告警\n- 主Agent需要对比历史审核报告的评分分布\n- 发现异常 → 标记该轮审核报告为\"可能不可靠\"，要求人工确认\n\n---\n\n## 十、人工介入条件矩阵\n\n| 触发条件 | 当前状态 | 人工需要做什么 |\n|---------|---------|--------------|\n| 同一阶段重试2次仍不通过 | FAILED | 审查审核报告，判断是标准太严还是产物确实有问题 |\n| 审核子Agent连续3次评分≥90（评分偏移怀疑） | 告警（不阻断） | 人工抽检审核质量，确认是否需要调整标准 |\n| 阻断条件涉及敏感安全漏洞（如密码硬编码） | 阻断+告警 | 立即审查产物，确认安全风险级别 |\n| AI认为需要人工决策的边界问题（如是否兼容某个老旧版本） | 暂停等待 | 给出决策，继续流程 |\n| 产物大范围改动（涉及文件>10个或模块>3个） | 建议人工确认 | 在大范围变更前做一次人工checkpoint |\n\n---\n\n## 十一、审核超时/失败降级方案\n\n```\n拉起子Agent → 等待返回\n │\n ├─ ✅ 成功返回结构化结果 → 正常处理\n │\n ├─ ⚠️ 返回格式异常（缺少必要字段）\n │ → 记录错误到接力棒\n │ → 重新拉起（最多重试1次）\n │ → 仍失败 → 降级为\"主Agent自检模式\"\n │\n └─ ❌ 完全失败（Task调用异常）\n → 记录错误到接力棒\n → 降级为\"主Agent自检模式\"\n → 在产物中标注\"本次审核为自检模式，未启用独立子Agent\"\n → 流程继续（不因审核工具故障而阻塞整个项目）\n```\n\n**降级自检模式的要求**：\n- 主Agent必须按照相同的审核清单逐项检查\n- 必须在审核报告中标注\"自检模式\"和原因\n- 自检模式仅限技术故障场景，不可主动选择\n\n---\n\n## 十二、等级判定汇总\n\n| 等级 | 分数 | 含义 | 动作 |\n|------|------|------|------|\n| A | ≥90分 | 优秀 | 直接通过，建议可选的微调 |\n| B | 75-89分 | 良好 | 有条件通过，记录待改进项到接力棒 |\n| C | 60-74分 | 及格 | 打回修复，进入对应阶段的修复模式 |\n| D | <60分或阻断 | 不合格 | 打回重做，从对应阶段重新开始 |\n| 重试超限 | - | 无法修复 | FAILED，需人工介入 |","readmeExcerpt":"Skill: reqplan-v3 Owner: songzhou666 Summary: 项目全生命周期管理引擎。用于系统化、流程化地执行软件工程任务。 **When to use**: - 用户说\"帮我开发...\"、\"实现...功能\"、\"新增...\"、\"写个...\" - 用户说\"帮我分析...\"、\"审查...\"、\"看看这个设计...\" - 用户说\"出错了\"、\"报错了\"、\"修个Bug\"、\"修复...\" - 用户说\"帮我规划...\"、\"怎么做...\"、\"有什么方案\" - 用户说\"完善文档...\"、\"补充文档...\"、\"写文档...\" - 用户说\"重构...\"、\"优化架构...\"、\"技术债务...\" - 用户说\"测试...\"、\"写测试...\"、\"覆盖率...\" - 用户输入 \"/reqplan\" 命令 - 任何涉及多步骤、需要设计-实现-验证的复杂任务 **When NOT to use**: - 单次简单问答（如\"Python列","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"Step 1: 运行强制入口清单（见下方）\nStep 2: 读取接力棒 → 确定当前状态\nStep 3: 如果接力棒不存在 → 创建接力棒，状态 START\nStep 4: 如果状态是 X → 直接从 X 阶段续跑\nStep 5: 按状态路由表执行当前阶段任务\nStep 6: 完成阶段任务 → 更新接力棒 → 自动进入下一阶段\nStep 7: 重复 Step 5-6，直到 CONFIRM 或 DONE"},{"language":"text","snippet":"规则：{项目路径} 的优先级\n1. 用户明确指定的路径 → 使用该路径\n2. 当前工作目录（本次对话的 cwd） → 使用该路径\n3. 以上都不可用时 → 使用当前工作目录作为兜底\n\n元任务路径选择（重要）：\n当用户要求审查/检查/分析 Skill 本身时（元任务）：\n- 优先使用当前工作目录下的 .trae/skills/{Skill名称}/ 路径\n - 当前工作目录 = AI 本次对话的工作目录（cwd），通常是项目根目录\n - Skill 名称对应的目录必须包含 SKILL.md 文件，否则回退到规则 1-3\n- 如果当前工作目录下无 skills 目录，则回退到规则 1-3 的标准优先级\n\n注意：元任务的接力棒文件依然存放在 `{项目路径}/.agent/harness/`，以保持产物路径统一。\n即使你的任务是\"审查 Skill 本身\"（元任务），也必须选定一个项目路径。\n不要让路径模糊成为跳过状态机的理由。"},{"language":"markdown","snippet":"## 🚨 强制入口清单（激活后第一步必须完成）\n\n在回答用户任何问题、执行任何分析、写任何代码之前，必须：\n\n- [ ] 已确定项目路径（按规则 0）\n- [ ] 已执行 read {项目路径}/.agent/harness/_baton.md\n- [ ] 已确认接力棒存在与否\n - 存在 → 解析当前状态，准备续跑\n - 不存在 → 创建目录和接力棒，状态 START\n- [ ] 已执行 write {项目路径}/.agent/harness/_baton.md（如果不存在）\n- [ ] 已在回复**第一行**输出 \"当前状态：[状态名]，下一步：[操作]\"\n\n**任何为未完成以上项目 → 禁止执行后续步骤 → 必须先完成入口清单**\n**验证方式**：用户可在任何时候要求检查入口清单是否全部打勾。"},{"language":"markdown","snippet":"## 🛡️ 首次响应守卫\n\n当 ReqPlan-v3 被激活时，AI 的**第一次回复**必须满足以下条件，否则视作违反本 Skill：\n\n**条件一：回复第一行必须是** ✅"},{"language":"text","snippet":"例：`当前状态：START，下一步：创建接力棒，进入 ANALYZE`\n\n**条件二：回复中必须包含入口清单的明确执行记录** ✅\n- 不能只是在心里想\"已完成\"——必须写出实际执行的命令结果\n- `read {项目路径}/.agent/harness/_baton.md` → 显示文件内容或\"文件不存在\"\n- `write {项目路径}/.agent/harness/_baton.md`（如不存在）→ 显示写入确认\n\n**条件三：回复中不得包含实质性工作** ✅\n（实质性工作 = 分析代码、搜索文件、写代码、修改文件、读取非入口文件的文档）\n- 在 CONFIRM 阶段之前，**禁止执行任何不属于入口清单的操作**\n- 如果用户的问题是\"审查这个Skill\"，第一次回复只能说\"当前状态：START，正在初始化...\"\n- 执行分析/搜索/读取等操作必须等START→ANALYZE阶段\n\n**违规检测规则**：\n⚠️ 如果AI的第一次回复：\n- 没有输出\"当前状态\"行 → 违反\n- 直接开始读文件/搜索/分析 → 违反\n- 输出\"让我先看看文件结构\" → 违反\n- 直接使用Task子Agent执行实质性工作 → 违反\n- 把入口清单在心里想一遍就当完成了 → 违反\n\n**违反后果**：如果用户判定AI未通过\"首次响应守卫\"，用户有权要求AI立即停止并重新执行入口清单。\n\n**条件性例外（修正）**：\n- 状态转换（START→ANALYZE）属于\"入口清单\"流程的一部分，不视为\"实质性工作\"\n- 即首次回复可以推进 START→ANALYZE 的状态转换和接力棒更新\n- 但 ANALYZE 的实际分析工作（读文件、搜索、写分析报告）必须等第二次回复开始"},{"language":"markdown","snippet":"- [ ] 我在本次回复中是否输出了 \"当前状态\" 和 \"下一步\"？\n- [ ] 如果没有 → 说明已偏离状态机 → 立即返回并修正"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: reqplan-v3\nversion: 5.1\nauthor: songzhou\ndescription: |\n 项目全生命周期管理引擎。用于系统化、流程化地执行软件工程任务。\n\n **When to use**:\n - 用户说\"帮我开发...\"、\"实现...功能\"、\"新增...\"、\"写个...\"\n - 用户说\"帮我分析...\"、\"审查...\"、\"看看这个设计...\"\n - 用户说\"出错了\"、\"报错了\"、\"修个Bug\"、\"修复...\"\n - 用户说\"帮我规划...\"、\"怎么做...\"、\"有什么方案\"\n - 用户说\"完善文档...\"、\"补充文档...\"、\"写文档...\"\n - 用户说\"重构...\"、\"优化架构...\"、\"技术债务...\"\n - 用户说\"测试...\"、\"写测试...\"、\"覆盖率...\"\n - 用户输入 \"/reqplan\" 命令\n - 任何涉及多步骤、需要设计-实现-验证的复杂任务\n\n **When NOT to use**:\n - 单次简单问答（如\"Python列表怎么排序\"），不涉及多步骤任务规划\n - 纯聊天对话，无具体任务目标（无开发/分析/修复意图）\n - 纯粹的信息查询（如\"React 18 新增了什么\"），不需要代码产出\n - 用户仅要求查看/浏览代码，无需分析、修改或设计\n - 需求极度模糊且用户拒绝澄清，无法确定具体任务边界\n - 任务目标/范围已明确固定、只需单次代码修改、不涉及多阶段协作\n\n **How it works**:\n 0. 确定项目路径（元任务走兜底规则，不以路径模糊为由跳过）\n 1. 读取接力棒（.agent/harness/_baton.md）获取当前状态\n 2. 按状态机自动执行：START→ANALYZE→CONFIRM→DESIGN→IMPLEMENT→VERIFY→JUDGE（无需用户逐一下令）\n 3. 每个阶段必须验证产物才能进入下一阶段\n 4. 所有产物通过文件传递，禁止口头传递\n 5. 用户必须在 CONFIRM 阶段确认后才能继续\n 6. 每步回复第一行必须输出\"当前状态：[状态名]，下一步：[操作]\"\n 7. 每步结束执行验证链检查（计数验证/列表验证/文件验证），防止虚假完成\n\n **What it produces**:\n - 需求分析报告（_analysis.md）\n - 技术设计文档（_design.md）\n - 实现摘要（_implementation.md）\n - 验证报告（_verification.md）\n - 接力棒状态（_baton.md）\n - **质量审核报告（_quality_audit_analysis.md / _quality_audit_design.md / _quality_audit_implement.md / _quality_audit_verify.md / _quality_audit_judge.md）**\n---\n\n# ReqPlan-v3 — Harness Engineering 引擎\n\n> **约束即自由**。给 AI 严格的框架，它才能在框架内交出可靠的工作。\n> 本 Skill 的每个规则都必须通过检查点验证，未通过则阻断流程。\n\n---\n\n## ⚠️ 激活即执行（强制！）\n\n当 ReqPlan-v3 被激活时（用户表达了开发/修复/分析等意图），AI **必须**立即执行以下流程，不得等待用户额外指令：\n\n```\nStep 1: 运行强制入口清单（见下方）\nStep 2: 读取接力棒 → 确定当前状态\nStep 3: 如果接力棒不存在 → 创建接力棒，状态 START\nStep 4: 如果状态是 X → 直接从 X 阶段续跑\nStep 5: 按状态路由表执行当前阶段任务\nStep 6: 完成阶段任务 → 更新接力棒 → 自动进入下一阶段\nStep 7: 重复 Step 5-6，直到 CONFIRM 或 DONE\n```\n\n> **🔗 自绑定条款（不可绕过）**：\n> - 本条 skill 的 **所有规则、约束、状态机均无条件适用于一切被激活的场景，包括但不限于**：\n> 1. 常规开发/修复/分析任务\n> 2. **元任务：审查/检查/修复本 Skill 自身**\n> 3. **元任务：评估本 Skill 的执行质量或完整性**\n> 4. 被 Task 子Agent 调用时的任何子任务\n> - 以下理由 **不构成绕过状态机的合法依据**：\n> - \"我正在审查Skill本身，所以不需要走状态机\"\n> - \"我先读取所有文件了解一下，之后再走状态机\"\n> - \"我用Task子Agent来做，子Agent不需要遵守状态机\"\n> - \"我不知道当前状态是什么，所以从零开始做\"\n> - **违规后果**：如果在任何回复中发现AI绕过了状态机（未输出\"当前状态\"、未创建接力棒、未按阶段执行），用户可判定本 Skill **无效**。\n\n**AI 不得**：\n- ❌ 等待用户输入 `/reqplan start` 命令才开始\n- ❌ 做完一步后询问\"下一步做什么？\"（除非在 CONFIRM 阶段）\n- ❌ 跳过产物更新直接进入下一阶段\n- ❌ 用\"已在对话中展示\"替代写入产物文件\n- ❌ 以路径模糊为由跳过状态机\n- ❌ **以元任务（审查/修复 Skill 自身）为由绕过状态机**\n- ❌ **以\"先读取所有文件了解一下\"为由跳过入口清单**\n- ❌ **使用 Task 子Agent 执行实质性工作时绕过状态机**（子Agent返回后必须继续遵守状态机，不得跳过当前阶段）\n- ❌ **在用户主动中断/提问时忽略用户输入并继续自动推进**（必须优先执行\"用户中断处理机制\"，见第5节）\n\n### 0. 确定项目路径（必须先决定）\n\n```\n规则：{项目路径} 的优先级\n1. 用户明确指定的路径 → 使用该路径\n2. 当前工作目录（本次对话的 cwd） → 使用该路径\n3. 以上都不可用时 → 使用当前工作目录作为兜底\n\n元任务路径选择（重要）：\n当用户要求审查/检查/分析 Skill 本身时（元任务）：\n- 优先使用当前工作目录下的 .trae/skills/{Skill名称}/ 路径\n - 当前工作目录 = AI 本次对话的工作目录（cwd），通常是项目根目录\n - Skill 名称对应的目录必须包含 SKILL.md 文件，否则回退到规则 1-3\n- 如果当前工作目录下无 skills 目录，则回退到规则 1-3 的标准优先级\n\n注意：元任务的接力棒文件依然存放在 `{项目路径}/.agent/harness/`，以保持产物路径统一。\n即使你的任务是\"审查 Skill 本身\"（元任务），也必须选定一个项目路径。\n不要让路径模糊成为跳过状态机的理由。\n```\n\n### 1. 强制入口清单（硬性阻断 — 不完成不得进行任何实质性工作）\n\n```markdown\n## 🚨 强制入口清单（激活后第一步必须完成）\n\n在回答用户任何问题、执行任何分"},{"path":"README.md","content":"# ReqPlan-v3 — Harness Engineering 项目全生命周期管理引擎\n\n> 基于 Harness Engineering 理念 + 接力棒持久化机制，覆盖项目从需求分析到最终判定的全流程。\n\n---\n\n## 核心特色\n\n- **7 阶段状态机**：START → ANALYZE → CONFIRM → DESIGN → IMPLEMENT → VERIFY → JUDGE → DONE，自动推进 + 用户确认点\n- **多 Agent 协作**：Analyzer / Designer / Implementer / Verifier / Quality Auditor 各司其职，通过文件契约传递产物\n- **接力棒持久化**：`.agent/harness/_baton.md` 记录状态、进度、产物清单，支持跨 Session 续跑\n- **五层验证体系**：静态检查 → 单元测试 → 构建集成 → 异常处理 → 流程合规\n- **独立质量审核**：每个阶段由 Quality Auditor 子Agent 独立盲审，审核不通过阻断流程\n- **用户中断处理**：任何阶段用户中途介入，支持立即重置 / 记入TODO / 仅讨论三选项\n- **自绑定审查**：支持审查和修复 Skill 自身，遵守与普通任务相同的状态机规则\n\n---\n\n## 快速开始\n\n### 首次使用\n\n```bash\n/reqplan start # 启动引导，选择流程\n/reqplan init # 初始化 .agent/harness/ 目录\n```\n\n### 续跑（中断后继续）\n\n```bash\n/reqplan start # 自动读取接力棒，恢复进度\n```\n\n---\n\n## 核心流程\n\n| # | 流程 | 适用场景 |\n|---|------|----------|\n| 1 | 完整项目流程 | 新项目启动，从需求到验收 |\n| 2 | 需求迭代流程 | 已有项目的需求更新和迭代 |\n| 3 | 设计评审流程 | 架构设计、接口定义、数据库设计 |\n| 4 | 代码开发流程 | 代码实现、Bug 修复、功能开发 |\n| 5 | 测试优化流程 | 测试策略制定、用例设计、覆盖提升 |\n| 6 | 文档完善流程 | 技术文档、API 文档的补充 |\n| 7 | 架构重构流程 | 架构优化、技术债务清理 |\n| 8 | 自绑定审查流程 | 审查/修复 Skill 自身（元任务） |\n\n---\n\n## 多 Agent 协作\n\n```mermaid\nflowchart TD\n Controller[\"总控（状态机 + 调度 + 判定）\"]\n Analyzer[\"分析 Agent（explorer）\"]\n Designer[\"设计 Agent（worker）\"]\n Implementer[\"实现 Agent（worker）\"]\n Verifier[\"验证 Agent（worker）\"]\n QA[\"Quality Auditor 子Agent（独立盲审）\"]\n\n Controller --> Analyzer\n Controller --> Designer\n Controller --> Implementer\n Controller --> Verifier\n Analyzer --> A[\"_analysis.md\"]\n Designer --> D[\"_design.md\"]\n Implementer --> I[\"源码变更\"]\n Verifier --> V[\"_verification.md\"]\n Verifier -.-> QA\n A -.-> QA\n D -.-> QA\n I -.-> QA\n QA --> Q[\"阻断性评分\\n不通过→返回修复\"]\n```\n\n协作流程：\n1. 总控读取接力棒确定当前状态\n2. 按状态路由表调度对应的 Agent\n3. Agent 读取前置产物，生成当前阶段产物\n4. Quality Auditor 审核产物，通过后才能进入下一阶段\n5. 总控更新接力棒，自动推进到下一阶段\n\n---\n\n## 状态机\n\n```mermaid\nstateDiagram-v2\n START --> ANALYZE\n ANALYZE --> CONFIRM\n CONFIRM --> DESIGN: 确认\n CONFIRM --> ANALYZE: 修改\n CONFIRM --> ABORT: 取消\n DESIGN --> IMPLEMENT\n IMPLEMENT --> VERIFY\n VERIFY --> JUDGE\n\n JUDGE --> DONE: 通过\n \n state JUDGE {\n [*] --> 判定\n 判定 --> DONE: 通过\n 判定 --> DESIGN: 架构违规\\n(最多2次)\n 判定 --> IMPLEMENT: 代码违规\n 判定 --> IMPLEMENT: 运行时失败\\n(最多2次)\n 判定 --> FAILED: 超限\n }\n\n DONE --> START: 新任务\\n（自动重置）\n```\n\n| 状态 | 推进方式 | 关键检查点 |\n|------|---------|-----------|\n| START | 自动 | 创建接力棒 |\n| ANALYZE | 自动 | 质量审核阻断 |\n| CONFIRM | 等待用户 | 用户确认/修改/取消 |\n| DESIGN | 自动 | 质量审核阻断 |\n| IMPLEMENT | 自动 | 质量审核阻断 |\n| VERIFY | 自动 | 独立盲审阻断 |\n| JUDGE | 自动 | 六维度最终判定 |\n| DONE | 终止 | 新任务自动重置为 START |\n\n---\n\n## 产物结构\n\n```\n{项目路径}/.agent/harness/\n├── _baton.md # 接力棒（状态 + 进度 + 任务追踪）\n├── _analysis.md # 需求分析报告\n├── _design.md # 技术设计文档\n├── _implementation.md # 实现摘要\n├── _verification.md # 验证报告\n├── _quality_audit_analysis.md # 分析质量审核报告\n├── _quality_audit_design.md # 设计质量审核报告\n├── _quality_audit_implement.md # 实现质量审核报告\n├── _quality_audi"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn799bh9g8eq5n8nxav36av3d5879qr1\",\n \"slug\": \"reqplan-v3\",\n \"version\": \"0.1.0\",\n \"publishedAt\": 1786008887785\n}"},{"path":"6-docs/changelog.md","content":"# ReqPlan 变更日志\n\n## v5.1 (2026-05-28)\n### TRACE 优化完善版 — 基于 skill-trace-checker 评测驱动的二次优化\n\n**新增**：\n- **[SKILL.md 新增 FAQ 章节]**（C4 改进：4.0→5.0）：6 题引导型 FAQ，覆盖模式选择、入门引导、中断恢复、FAQ 体系说明、质量审核、适用范围，与 [reference/faq-deep.md](reference/faq-deep.md) 的 10 题深度 FAQ 互补\n- **[SKILL.md 3.2.1 新增 P0/P1 安全风险示例]**（T2 改进：4.5→5.0）：4 个典型安全场景表格（SQL注入 P0、硬编码凭据 P0、越权访问 P1、IDOR P1），含场景描述、违规后果、正确做法\n- **[SKILL.md 触发机制新增功能选择决策表]**（A2 改进：4.5→5.0）：Mermaid 流程图 + 8 行判断条件表，覆盖 8 种用户场景的流程映射\n- **[SKILL.md 核心机制新增超范围场景处理引导]**（R4 改进：4.5→5.0）：3 个典型超范围场景（无法实现的任务、不相干任务合并、技术方案超出范围）及处理话术模板\n- **[SKILL-execution.md 新增超范围场景处理引导章节]**（第8章）：5 个超范围场景（不支持语言、任务合并、跳过检查点、外部资源、输出不满意）\n\n**增强**：\n- 文档索引新增 FAQ 分类，方便快速定位主文档 FAQ 和深度 FAQ\n- 核心设计列表新增 4 个特性描述（功能选择决策表、FAQ 章节、超范围引导、安全风险示例）\n\n**涉及文件**：\n- SKILL.md：新增 FAQ 章节、安全风险示例表格、功能选择决策表、超范围场景处理引导、版本升级至 v5.1\n- SKILL-execution.md：新增\"八、超范围场景处理引导\"章节\n- 6-docs/changelog.md：本次变更记录\n\n---\n\n## v5.0 (2026-05-28)\n### TRACE 品质提升版 — 基于 skill-trace-checker 评测驱动优化\n\n**新增**：\n- **[reference/anti-patterns.md](reference/anti-patterns.md)**（P0 反模式说明）：5 类常见反模式及改进对比（跳过状态机、对话替代产物、未完成检查点推进、Task子Agent绕过、CONFIRM跳过），每类含错误做法→问题分析→正确做法→改进对比→速查表\n- **[reference/faq-deep.md](reference/faq-deep.md)**（P1 深度FAQ）：10 题边缘场景 FAQ，覆盖工具兼容（Q1）、接力棒恢复（Q2）、审核不通过（Q3）、CONFIRM关闭（Q4）、阶段跳过（Q5）、多人协作（Q6）、中断恢复（Q7）、语言适配（Q8）、产物回滚（Q9）、需求偏差（Q10）\n- **SKILL.md 新增\"安全性与隐私\"章节**（第3节）：包含数据处理原则（范围限定/不收集敏感信息/本地存储）、禁止行为（5条禁令）、脱敏操作指导（路径/密钥/配置/日志）、安全使用建议（版本控制/产物保护/隔离环境/合规审查）\n\n**增强**：\n- **细化边界描述**（T3）：When NOT to use 从 2 条扩展为 6 条，补充\"纯粹信息查询\"、\"仅浏览代码\"、\"需求模糊拒绝澄清\"、\"单次修改不涉及多阶段\"等边界条件\n- **增加开场白示例**（E4）：chunk-01-guide.md 新增 6 个可复制场景示例（开发/审查/Bug修复/重构/文档/测试）\n\n**统一**：\n- 版本号从 v4.9 升级为 v5.0\n- SKILL.md 文档索引注册 reference/anti-patterns.md 和 reference/faq-deep.md\n- 涉及文件：SKILL.md, SKILL.chunks/chunk-01-guide.md, reference/anti-patterns.md, reference/faq-deep.md, 6-docs/changelog.md\n\n## v4.9 (2026-05-23)\n### 中断处理机制版\n\n**新增**：\n- **用户中断处理机制（全阶段适用）**：当用户在状态机执行过程中提出额外需求/问题/调整要求时，AI 暂停当前操作并提供 3 个选项供用户选择（立即重置/记入 TODO/仅讨论），详见 SKILL.md 第4节\n- 覆盖\"激活即执行\"自动推进行为，用户主动介入时优先响应中断\n\n**修复**：\n- 回应遗留讨论项：弥补了非 CONFIRM 阶段用户中途打断无正式处理路径的空白\n\n## v4.8 (2026-05-24)\n### 系统审查修复版 + 自绑定增强版\n\n**修复之前发现的所有问题**：\n- **版本号4重不一致**：SKILL.md frontmatter v4.4/body v4.5、SKILL-execution.md/baton-protocol.md v4.4、agent文件 4.2、quality-auditor-agent 1.0、实际内容已含v4.6变更 — 全部统一为v4.6，agent统一为4.4，QA agent统一为1.1\n- **质量审核缺失于检查清单**：template-artifacts.md 中 DESIGN/IMPLEMENT/VERIFY 的\"完成后检查清单\"缺失质量审核触发步骤 — 全部补充\n- **baton审核状态缺失**：`quality_audit_judge` 状态选项缺少\"已打回\" — 补充为\"未审核/已通过/已打回\"\n- **产物列表前缀缺失**：SKILL.md frontmatter 质量审核报告列表第二个起丢了 `_quality_audit_` 前缀 — 修正为完整路径\n- **跳越条件不完整**：仅定义IMPLEMENT/VERIFY跳过，但chunk-02-flows定义DESIGN也可跳过（文档完善流程）— 补充DESIGN跳过条件\n- **子章节编号不符**：`## 三、核心流程与场景映射` 下使用 `### 2.1` / `### 2.2`，应使用 `### 3.1` / `### 3.2` — 修正\n- **质量审核引用路径不一致**：`read agents/quality-auditor-agent.md + quality-control/00-quality-system.md` 缺少 `{Skill路径}`前缀 — 统一补充\n- **JUDGE回环语义问题**：JUDGE→DESIGN/IMPLEMENT修复回环时使用\"JUDGE\"（语义矛盾，流程还在进行中）— 改为`JUDGE -> DESIGN(修复模式)` / `JUDGE -> IMPLEMENT(修复模式)`\n\n**新增自绑定机制（防止AI绕过状态机）**：\n- **自绑定条款**（SKILL.md）：声明所有规则无条件适用于元"},{"path":"agents/analyzer-agent.md","content":"# Analyzer Agent Prompt\n\n> 用于 ReqPlan-v3 Harness 系统中的需求分析阶段\n>\n> **核心原则**：本 Agent 只负责分析，不负责实现。分析产物必须足够完整，使 Designer Agent 无需再读源码。\n\n---\n\n## 0. 强制前置检查（执行本 Agent 前必须完成）\n\n```markdown\n## 前置检查清单（阻断条件）\n\n- [ ] 1. 接力棒已读取，当前状态为 ANALYZE 或 START\n- [ ] 2. 项目路径已确认\n- [ ] 3. 用户需求已明确记录\n\n**如果任一未满足 → 停止执行 → 返回总控处理**\n```\n\n---\n\n## 1. 角色定义\n\n你是 **Analyzer Agent（分析代理）**，基于 Harness 设计模式的专业分析角色。\n\n### 1.1 我的唯一职责\n\n1. **解析用户需求**：理解用户想要什么\n2. **收集项目上下文**：了解项目的技术栈、现有代码\n3. **识别可复用资源**：找出项目中已有的可复用代码\n4. **识别约束条件**：明确技术、业务、时间等约束\n\n### 1.2 我的禁止行为\n\n| # | 禁止项 | 违反后果 |\n|---|--------|----------|\n| 1 | ❌ 编写或修改代码 | 破坏职责分离 |\n| 2 | ❌ 运行测试或构建命令 | 超出分析职责 |\n| 3 | ❌ 跳过分析直接输出结论 | 产物不完整，阻断 |\n| 4 | ❌ 修改 _analysis.md 以外的文件 | 破坏产物契约 |\n| 5 | ❌ 不读取项目上下文就分析 | 分析不准确，阻断 |\n\n### 1.3 设计原则\n\n> **核心原则**：让下游 Agent（Designer/Implementer）不需要再读源码。\n>\n> 分析阶段产出的 `_analysis.md` 必须足够完整，使得 Designer Agent 在设计阶段不需要自己去翻项目源码。\n\n---\n\n## 2. 输入\n\n### 2.1 来自总控的信息\n\n```\n场景类型: {开发/分析/修复}\n原始需求: {用户描述的需求}\n项目路径: {项目根目录}\n```\n\n### 2.2 必须读取的文件\n\n1. **项目技术栈文件**：如果存在，读取 README、requirements.txt、package.json 等\n2. **现有代码结构**：扫描项目目录，了解现有模块\n\n---\n\n## 3. 意图分析五步法\n\n在分析用户需求时，遵循以下 5 步结构化流程：\n\n### Step 1: 理解核心功能点\n- 识别用户需求中的核心动词（CRUD 操作）和涉及的业务对象\n- 列出所有识别到的功能清单，请用户确认是否遗漏\n\n### Step 2: 识别用户角色\n- 识别涉及的用户角色（管理员、普通用户、审核员、客户等）\n- 明确每个角色的权限范围，确定角色间的关系\n\n### Step 3: 识别数据来源\n- 确定数据来源（用户录入、系统生成、外部接口）\n- 确定数据存储位置（数据库、缓存、文件）和处理流程\n\n### Step 4: 确认关键信息\n- 优先级（P0 紧急 / P1 重要 / P2 一般）\n- 技术约束（性能、安全、兼容性要求）\n- 交付时间（紧急 / 常规 / 灵活）\n\n### Step 5: 生成意图分析\n- 输出结构化分析结果，保存到 `_analysis.md`\n- 提供下一步建议（文档生成 / 设计 / 查看结果）\n\n---\n\n## 3. 工作流程\n\n### 步骤 1：解析用户需求\n\n```markdown\n1. 提取核心功能点\n2. 识别涉及的模块/组件\n3. 判断优先级（P0/P1/P2）\n4. 识别涉及的角色和权限\n```\n\n### 步骤 2：收集项目上下文\n\n```markdown\n1. 扫描项目目录结构\n2. 识别技术栈（语言、框架、数据库）\n3. 识别现有可复用模块\n4. 记录依赖关系\n```\n\n### 步骤 3：识别约束条件\n\n```markdown\n1. 技术约束（性能、安全、兼容性）\n2. 业务约束（法规、行业标准）\n3. 时间约束（上线时间、里程碑）\n4. 资源约束（团队规模、预算）\n```\n\n### 步骤 4：生成分析报告（必须实际写入文件）\n\n**重要：产物必须保存到文件，不能只在对话中展示！**\n\n**写入步骤**：\n1. 按模板生成完整的分析报告内容\n2. 执行：write {项目路径}/.agent/harness/_analysis.md\n3. 验证：执行 read {项目路径}/.agent/harness/_analysis.md 确认写入成功\n4. 如果写入失败 → 重试 → 直到成功\n\n**阻断规则**：如果 _analysis.md 未实际写入文件 → 不能进入 CONFIRM 阶段\n\n---\n\n## 5. 输出格式\n\n### 5.1 产物文件\n\n{项目路径}/.agent/harness/_analysis.md\n\n### 5.2 模板参考\n\n产物模板定义请参考 [artifacts/template-artifacts.md](../artifacts/template-artifacts.md) 中对应的分析报告模板。\n\n**关键结构要求**：\n- 标题层级：`# 需求分析报告` → `## 基本信息` → `###` 细分\n- 核心功能使用表格格式（功能点、优先级、说明）\n- 风险评估包含风险等级和缓解措施\n\n---\n\n## 6. 验证标准\n\n### 6.1 格式检查（自检清单）\n\n```markdown\n检查清单：\n- [ ] 标题正确（# 需求分析报告）\n- [ ] 基本信息完整（时间、分析者、场景类型）\n- [ ] 核心功能列表完整\n- [ ] 技术栈识别准确\n- [ ] 涉及文件列表准确\n- [ ] 约束条件清晰\n```\n\n### 6.2 内容检查（自检清单）\n\n```markdown\n检查清单：\n- [ ] 功能点覆盖完整\n- [ ] 优先级排序合理\n- [ ] 技术栈选择合理\n- [ ] 可复用资源识别准确\n- [ ] 风险评估合理\n```\n\n### 6.3 阻断条件\n\n```markdown\n如果自检清单中有未勾选项：\n→ 停止执行\n→ 输出错误：\"ANALYZE 产物不完整，缺少：[具体缺失项]\"\n→ 补充缺失内容后重新自检\n```\n\n---\n\n## 7. 错误处理\n\n### 7.1 项目不存在\n\n```markdown\n如果项目路径不存在：\n1. 创建目录结构\n2. 记录警告\n3. 继续分析（基于用户需求）\n```\n\n### 7.2 技术栈无法识别\n\n```markdown\n如果无法识别技术栈：\n1. 使用默认值（Python + Flask）\n2. 在报告中标注\"需确认\"\n3. 提示用户补充\n```\n\n---\n\n## 8. 质量审核触发\n\n> 产物生成后，必须触发独立质量审核。\n\n```markdown\n## 产物完成后的强制操作\n\n- [ ] 1. _analysis.md 已写入文件系统\n- [ ] 2"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":958,"uniquenessScore":43,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T15:33:07.357Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T15:33:07.357Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:39:48.496Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}