{"id":"f243bf04-b9ea-4a41-b0ed-5a887adb0bf3","entityType":"agent","slug":"clawhub-yuchangxu1989-openclaw-sevo","name":"sevo-pipeline","canonicalUrl":"https://www.xpersona.co/agent/clawhub-yuchangxu1989-openclaw-sevo","canonicalPath":"/agent/clawhub-yuchangxu1989-openclaw-sevo","generatedAt":"2026-10-11T01:49:08.256Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T23:08:05.702Z","emptyReason":null},"description":"SEVO — Agent 研发流水线。14 阶段全链路交付：需求规格 → 门禁评审 → 测试用例 → 验收编写 → 架构契约 → 编码实现 → 独立审计 → 回归验证 → 发布门禁 → 部署 → 终验 → 交付账本。 Skill: sevo-pipeline Owner: yuchangxu1989-openclaw Summary: SEVO — Agent 研发流水线。14 阶段全链路交付：需求规格 → 门禁评审 → 测试用例 → 验收编写 → 架构契约 → 编码实现 → 独立审计 → 回归验证 → 发布门禁 → 部署 → 终验 → 交付账本。 Tags: latest:1.13.1 Version history: v1.13.1 | 2026-05-24T05:08:23.919Z | user 1.13.1 patch release v1.13.0 | 2026-05-24T04:39:19.388Z | user 1.13.0 release v1.12.2 | 2026-05-23T15:00:21.121Z | user 1.12.2 release v1.5.1 | 2026-05-04T07:51:52.376Z | u","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.2K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s17a59yf9b9zefwe0avdmbspmh852jzp:sevo","sourceUrl":"https://clawhub.ai/yuchangxu1989-openclaw/sevo","homepage":"https://clawhub.ai/yuchangxu1989-openclaw/skills/sevo","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/yuchangxu1989-openclaw/sevo","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/yuchangxu1989-openclaw/skills/sevo","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":62,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"SEVO — Agent 研发流水线。14 阶段全链路交付：需求规格 → 门禁评审 → 测试用例 → 验收编写 → 架构契约 → 编码实现 → 独立审计 → 回归验证 → 发布门禁 → 部署 → 终验 → 交付账本。 Skill: sevo-pipeline Owner: yuchangxu1989-openclaw "},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T23:08:05.702Z","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-10T23:08:05.702Z","emptyReason":null},"stars":null,"forks":null,"downloads":1234,"packageName":null,"latestVersion":"1.13.1","tractionLabel":"1.2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T23:08:05.639Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T23:08:05.702Z","lastCrawledAt":"2026-10-10T23:08:05.639Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T23:08:05.639Z","lastVerifiedAt":null,"highlights":[{"version":"1.13.1","createdAt":"2026-05-24T05:08:23.919Z","changelog":"1.13.1 patch release","fileCount":47,"zipByteSize":194362},{"version":"1.13.0","createdAt":"2026-05-24T04:39:19.388Z","changelog":"1.13.0 release","fileCount":46,"zipByteSize":191462},{"version":"1.12.2","createdAt":"2026-05-23T15:00:21.121Z","changelog":"1.12.2 release","fileCount":36,"zipByteSize":180111},{"version":"1.5.1","createdAt":"2026-05-04T07:51:52.376Z","changelog":"FR-22 角色-任务匹配调度约束","fileCount":12,"zipByteSize":113330},{"version":"1.5.0","createdAt":"2026-05-04T07:49:28.435Z","changelog":"FR-22 角色-任务匹配调度约束","fileCount":393,"zipByteSize":779742},{"version":"1.4.0","createdAt":"2026-05-04T05:40:54.440Z","changelog":"- Bumped version to 1.4.0 in SKILL.md. - No other content changes.","fileCount":2,"zipByteSize":493},{"version":"1.3.1","createdAt":"2026-05-04T04:09:04.696Z","changelog":"- Bumped version number from 1.3.0 to 1.3.1 in SKILL.md.","fileCount":2,"zipByteSize":492},{"version":"1.3.0","createdAt":"2026-05-04T04:06:51.204Z","changelog":"- Updated SKILL.md with a streamlined description and summary. - Changed version to 1.3.0. - Simplified and reorganized documentation for improved clarity.","fileCount":2,"zipByteSize":493}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17a59yf9b9zefwe0avdmbspmh852jzp:sevo","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"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-yuchangxu1989-openclaw-sevo/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yuchangxu1989-openclaw-sevo/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yuchangxu1989-openclaw-sevo/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-yuchangxu1989-openclaw-sevo/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-yuchangxu1989-openclaw-sevo/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-yuchangxu1989-openclaw-sevo/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-11T01:49:08.252Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yuchangxu1989-openclaw-sevo/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yuchangxu1989-openclaw-sevo/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yuchangxu1989-openclaw-sevo/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yuchangxu1989-openclaw-sevo/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":"high","updatedAt":"2026-10-10T23:08:05.702Z","emptyReason":null},"readme":"Skill: sevo-pipeline\n\nOwner: yuchangxu1989-openclaw\n\nSummary: SEVO — Agent 研发流水线。14 阶段全链路交付：需求规格 → 门禁评审 → 测试用例 → 验收编写 → 架构契约 → 编码实现 → 独立审计 → 回归验证 → 发布门禁 → 部署 → 终验 → 交付账本。\n\nTags: latest:1.13.1\n\nVersion history:\n\nv1.13.1 | 2026-05-24T05:08:23.919Z | user\n\n1.13.1 patch release\n\nv1.13.0 | 2026-05-24T04:39:19.388Z | user\n\n1.13.0 release\n\nv1.12.2 | 2026-05-23T15:00:21.121Z | user\n\n1.12.2 release\n\nv1.5.1 | 2026-05-04T07:51:52.376Z | user\n\nFR-22 角色-任务匹配调度约束\n\nv1.5.0 | 2026-05-04T07:49:28.435Z | user\n\nFR-22 角色-任务匹配调度约束\n\nv1.4.0 | 2026-05-04T05:40:54.440Z | auto\n\n- Bumped version to 1.4.0 in SKILL.md.\n- No other content changes.\n\nv1.3.1 | 2026-05-04T04:09:04.696Z | auto\n\n- Bumped version number from 1.3.0 to 1.3.1 in SKILL.md.\n\nv1.3.0 | 2026-05-04T04:06:51.204Z | auto\n\n- Updated SKILL.md with a streamlined description and summary.\n- Changed version to 1.3.0.\n- Simplified and reorganized documentation for improved clarity.\n\nv1.2.0 | 2026-05-04T01:40:21.752Z | auto\n\nVersion 1.2.0\n\n- Enhanced documentation with version info and streamlined pipeline stages.\n- Expanded description of core capabilities, including 8-stage lifecycle, automated endgame delivery, and programmable API support.\n- Added details on OKR/SMART/PDCA integration and quality auditing.\n- Updated usage and installation instructions for clarity.\n\nv0.6.1 | 2026-05-01T05:53:48.752Z | user\n\nCommercializationGate 五层商用化门禁 + 独立仓库源码化\n\nv0.6.0 | 2026-05-01T05:35:48.754Z | user\n\nCommercializationGate 五层商用化门禁\n\nv0.2.1 | 2026-04-25T19:06:30.576Z | user\n\nv0.2.1 concurrent write lock, convergence loop, gate hardening, false-trigger prevention\n\nv0.2.0 | 2026-04-25T19:00:34.092Z | user\n\n商用就绪: 34FR+8AC-D09+6NFR全实现, 并发写锁, 收敛循环, 门禁硬化, 三层路由, 陌生人UX审计通过\n\nv1.0.0 | 2026-04-20T08:52:34.606Z | user\n\nv1.0.0: Full release with complete delivery pipeline — spec, review gates, contract design, implementation, code review, regression, deployment, verification, and delivery ledger\n\nv0.1.0 | 2026-04-20T05:53:45.340Z | user\n\nInitial release: 11 pipeline stages, 346 tests, MIT license\n\nv0.0.2 | 2026-04-19T10:08:35.827Z | user\n\n更新描述至最新项目定位\n\nv0.0.1 | 2026-04-19T08:33:36.031Z | user\n\nInitial placeholder for SEVO — Agent 研发流水线 (Spec-Execute-Verify-Operate)\n\nArchive index:\n\nArchive v1.13.1: 47 files, 194362 bytes\n\nFiles: CHANGELOG.md (2322b), data/pipelines/483ef487-d7bd-4713-9f6e-92c9a9119549/state.json (3123b), data/pipelines/53705fbd-0c57-4026-a0b2-7171bd53a51c/state.json (2824b), data/pipelines/9c996279-6539-4871-9c18-0c5c22effde0/state.json (3930b), data/pipelines/a031ea32-938d-4760-a70d-f2d36b92a4ce/state.json (3001b), data/pipelines/a3b3dd4a-722b-4c34-8350-ed250fd5267b/state.json (2832b), data/pipelines/a83a4d9b-b776-4f25-92e1-103e2746fa9d/state.json (2816b), data/pipelines/bfff87b9-6149-4cf1-b515-8267f195e92f/state.json (2815b), data/pipelines/cdd75e10-f316-4791-9e48-fdc633ffbc09/state.json (2829b), data/pipelines/da778b47-2c3e-437b-91a4-4d41011513b5/state.json (2824b), data/pipelines/e4cbb30c-4029-4cc1-b957-2f8d72d73345/state.json (2833b), data/pipelines/e4d38573-938f-4d94-86fa-4c12bd6be57e/state.json (863b), docs/arc42-architecture.md (64970b), docs/architecture.md (70239b), docs/backlog-endgame-auto-fix.md (903b), docs/gap-scan-l1.json (15102b), docs/gap-scan-summary.json (16657b), docs/product-requirements.md (215668b), docs/reviews/code-review-fr13-p0-implementation.md (7452b), docs/reviews/contract-review-fr13-p0-architecture.md (8624b), docs/reviews/contract-review-ux-arch-stages.md (8786b), docs/reviews/fr13-p1-code-audit.md (7929b), docs/spec.md (28268b), docs/standalone-guide.md (14985b), docs/web-dashboard-guide.md (16327b), openclaw.plugin.json (1724b), package.json (1555b), projects/audit-test/project.json (362b), projects/demo/project.json (342b), projects/demo2/project.json (344b), projects/exam-sprint/project.json (423b), projects/sevo-endgame/specs/product-requirements.md (13141b), projects/sevo-intercept-llm-gate/project.json (355b), projects/sevo-p0-l3-verifier/project.json (426b), projects/sevo-p0-test-fix/docs/architecture/arc42-architecture.md (15b), projects/sevo-p0-test-fix/docs/product-requirements.md (23b), projects/sevo-p0-test-fix/package.json (74b), projects/sevo-p0-test-fix/pipelines/fr-sevo-p0-test-fix-20260524-001.json (3885b), projects/sevo-p0-test-fix/project.json (342b), projects/sevo-p0-test-fix/README.md (19b), projects/sevo-p0-test-fix/specs/product-requirements.md (2145b), projects/sevo/project.json (330b), README.md (11539b), sevo.json (1219b), skill-card.md (2379b), SKILL.md (2303b), _meta.json (124b)\n\nFile v1.13.1:SKILL.md\n\n---\nname: sevo\ndescription: \"SEVO — Agent 研发流水线。14 阶段全链路交付：需求规格 → 门禁评审 → 测试用例 → 验收编写 → 架构契约 → 编码实现 → 独立审计 → 回归验证 → 发布门禁 → 部署 → 终验 → 交付账本。\"\n---\n\n# SEVO — Agent 研发流水线\n\nSpec-Execute-Verify-Operate：面向 AI Agent 的软件交付生命周期。\n\n## 14 阶段流水线\n\n| # | Stage ID | 说明 |\n|---|----------|------|\n| 1 | spec | 需求规格与概念架构 |\n| 2 | spec-review-gate | 需求评审门禁 |\n| 3 | test-case-authoring | 测试用例编写（与 4/5/6 并行） |\n| 4 | ux-acceptance-authoring | UX 开箱即用验收编写（并行） |\n| 5 | commercial-acceptance-authoring | 商用验收编写（并行） |\n| 6 | contract | 架构设计、ADR、技术契约（并行） |\n| 7 | contract-review-gate | 架构评审门禁 |\n| 8 | implement | 编码实现（TDD 循环） |\n| 9 | review | 独立代码审计与安全审查 |\n| 10 | regression | 回归测试与冒烟验证 |\n| 11 | publish-generalization-gate | 发布通用化门禁 |\n| 12 | deploy | 构建打包与发布 |\n| 13 | verify | 清洁环境端到端终验 |\n| 14 | ledger | 交付账本（版本、证据、经验回写） |\n\nspec-review-gate 通过后，test-case-authoring / ux-acceptance-authoring / commercial-acceptance-authoring / contract 四路并行展开；implement 需等待 contract-review-gate 和 test-case-authoring 均通过后才激活。\n\n## 智能路由\n\n任务按复杂度自动分级：\n- L0（微小改动）：跳过 spec/contract，直接进 implement → review → regression → verify → ledger\n- L1/L2+（中大型）：走完整 14 阶段\n\n## 核心机制\n\n- 评审修复闭环（Review-Fix Loop）：评审发现问题 → 自动生成修复任务 → 修复后定向复验\n- 主动澄清：spec/contract/implement 阶段内建模糊检测，歧义就地消解\n- 终局收敛验收：逐条对照需求覆盖状态，未覆盖自动回到实现阶段补齐\n- 单 Agent 完整降级：一个 Agent 也能走完整流程\n\n## 集成\n\n- OpenClaw 插件：`scripts/init.sh` 安装\n- 独立使用：`npm install sevo-pipeline` 后通过 API 调用\n- 宿主无关：通过适配器接口与运行环境交互\n\n## 作者\n\nyuchangxu1989@gmail.com\n\nFile v1.13.1:projects/sevo-p0-test-fix/README.md\n\n# sevo-p0-test-fix\n\nFile v1.13.1:README.md\n\n# SEVO\n\n**AI Agent 写代码很快，但谁来保证写出来的东西用户真的能用？**\n\n🌐 [官网](https://agentos.site/sevo.html)\n\nAgent 生成代码越来越容易，但没有需求定义就自说自话，没有架构约束就边界失控，没有独立审计就写完算完。更要命的是——代码发布了，用户装上用不了，没人管。\n\nSEVO 是一条 18 阶段的全自动研发流水线，把 AI Agent 的产出从「能跑」推到「能用」。从需求到交付，每一步都有门禁、有证据、有人负责。\n\n---\n\n## 核心优势\n\n**主动澄清，需求不清不动手**\n用户随口一句话，SEVO 不会直接开写。它主动追问、澄清歧义、补全边界条件，把模糊意图收敛成结构化的需求规格说明书。大多数 AI Coding 工具拿到需求就开干，SEVO 先把需求搞清楚——写对比写快重要。\n\n**四方会审 + 反作弊隔离**\n架构评审由四个独立视角并行把关：产品看需求有没有承接住，开发看方案能不能落地，质量看风险和规范，体验看用户流程是否顺。四方全部通过才能进入编码。编码 Agent 对评分标准只有只读权限，看不到也改不了评估器代码，从 OS 文件权限层面杜绝「自己给自己打分」。门禁分数只升不降——一旦某个阶段达标就锁定基线，后续改动如果引入回退，流水线自动拦住。代码写完后的验证也不是跑个文件名匹配就算数：spec-to-code 映射文件记录每条需求对应哪些代码，LLM 语义验证逐条确认实现是否真的覆盖了 spec 定义的行为——两层检查，糊弄不过去。\n\n**自主收敛引擎，差距不归零就不放行**\n传统 CI/CD 跑一遍就结束——测试绿了、构建过了、发布成功了，流水线就关了。至于用户装上能不能用？没人管。SEVO 不是线性流水线，是围绕终局目标持续收敛的闭环引擎。它在关键节点自动触发差距扫描，发现问题就拆解修复任务，修完再扫描，循环直到差距归零才放行。门禁检查不通过？引擎自动进入修复状态，派出修复任务，最多重试 3 次。3 次修不好，自动回退到前一阶段重新来过——不是报个错就停在那等人，而是自己想办法。回退预算也有上限，真的收敛不了才阻断流水线等人工介入。OKR 锁定终局目标，SMART 拆解为可验证任务，PDCA 闭环驱动每一轮收敛——代码能跑不算完，陌生用户 5 分钟内感受到价值才算。\n\n**主动驱动，不等人催**\n阶段转换时自动触发门禁检查，不需要调度层记得要做什么。Spec 缺口主动发现——代码写了但 spec 没覆盖，引擎自动提醒补齐。发布后自动逐条对照 spec 做差距扫描，差距大于零就自动回环修复。OKR 达成度定期巡检，未达标的 KR 自动生成 SMART 拆解建议。整条流水线是自驱动的，不是被动等指令的。\n\n**18 阶段全自动推进**\n需求规格 → 门禁评审 → 架构契约 → 四方会审 → 编码实现 → 独立审计 → 冒烟测试 → UX 验收 → 商用评审 → 回归验证 → 商用化门禁 → 部署 → 终验 → 发布后验证 → 交付账本。阶段自动推进，门禁自动把关，评审发现问题自动派修复并定向复验。\n\n**终局交付不是发布，是收敛**\n发布成功只是收敛循环的一个检查点，不是终点。终局交付引擎在发布后自动触发：README 同步检查、语义化版本决策、多平台发布、逐条 spec 差距扫描。发现任何一条 FR 没有在运行态兑现，立即生成修复任务回环——修复、重新审计、重新发布、重新扫描，直到差距归零，流水线才真正关闭。\n\n**全链路可追溯**\n每步的输入、输出、结论都记录在案。出了问题秒级定位，交付账本串起版本、证据和经验沉淀。\n\n**一个 Agent 也能跑完整流程**\n只有一个 Agent？照样走完 18 阶段。质量降级但功能完整，随时可升级到多 Agent 协同。甚至连 OpenClaw 都没装也不会炸——安装时自动检测环境：完整环境正常注册插件，部分环境给个警告但不阻断，纯净环境静默退出不报错。装到哪都不会因为缺依赖把你的 `npm install` 搞挂。\n\n**全量测试覆盖**\n测试覆盖核心引擎、阶段状态机、门禁逻辑、CLI 命令、终局交付链、主动驱动层和端到端流程。\n\n---\n\n## 快速开始\n\n```bash\nnpm install sevo\nnpx sevo init\n```\n\n安装后在 OpenClaw 环境里执行 `init`，即可完成环境检测、OpenClaw 配置发现和角色分配。\n\n正式跑流水线前，OpenClaw 需要已配置可用的 LLM provider。`sevo demo` 不需要 LLM provider，可直接看演示。\n\n---\n\n## 30 秒快速体验\n\n```bash\nnpm install -g sevo\nsevo demo\n```\n\n`demo` 命令走完完整流水线生命周期演示——从项目创建、需求规格、门禁评审、编码实现、冒烟测试到发布后差距扫描。不需要 LLM provider，不需要改 OpenClaw 配置，装完就能看演示。\n\n---\n\n## 正式使用\n\n```bash\nnpm install -g sevo\n\nsevo init # 初始化环境，自动检测 OpenClaw、发现 Agent、分配角色\nsevo doctor # 检查配置和环境，排查问题先跑它\nsevo project create my-app --description \"项目描述\" # 创建项目\nsevo fr add my-app \"实现用户登录功能\" # 添加需求，流水线自动创建并推进\nsevo status # 随时查看进度\n```\n\n---\n\n## 四层架构\n\nSEVO 的能力分为四个域，各司其职：\n\n**Domain A — 流水线核心**\n阶段状态机、智能路由、并行阶段编排、PipelineEngine 流程引擎。任务进来后自动判定级别（微小改动走最小闭环，跨域重构走完整 18 阶段），阶段自动推进，支持暂停/恢复/取消。\n\n**Domain B — 质量门禁**\n可执行门禁评估器、混合评估模式（LLM + 规则引擎）、棘轮机制（分数只升不降）、评估-实现工作区隔离（反作弊）。门禁不是人工 review 的替代品，是自动化的质量底线。\n\n**Domain C — 可控调度**\n角色-任务匹配约束、终局交付自动推进（README 同步 → 版本决策 → 发布 → 差距扫描）、任意阶段切入（hotfix 从 implement 进、架构调整从 plan 进）、渐进式披露配置。\n\n**Domain D — 主动驱动**\n阶段转换自动触发门禁、Spec 缺口主动发现、发布后自动差距扫描与回环修复、OKR 达成度定期巡检、PDCA 循环自动驱动。引擎是触发器，调度层是执行者——引擎感知节点、推送提醒、接收确认，不等人催。\n\n---\n\n## 18 阶段流水线\n\n```\n需求规格 → 需求评审门禁 → ┬─ 测试用例编写（并行）\n ├─ UX 验收编写（并行）\n ├─ 商用验收编写（并行）\n └─ 架构契约（并行）\n ↓\n 架构评审门禁（四方会审）\n ↓\n编码实现 → 独立审计 → 冒烟测试 → ┬─ UX 验收（并行）\n └─ 商用评审（并行）\n ↓\n 回归验证 → 商用化门禁 → 部署 → 终验\n ↓\n 终局交付（README同步 + 版本决策 + 发布 + 差距扫描）\n ↓\n 交付账本\n```\n\n每个阶段都有门禁把关。评审发现问题后自动生成修复任务、按优先级排队、修复完成后定向复验。收敛循环最多 3 轮，超限升级为人工介入。\n\n---\n\n## 目标管理：OKR → SMART → PDCA\n\nSEVO 内置三层目标管理体系，把「做完了」推到「做对了」。\n\n**SMART 目标声明**\nSpecify 阶段自动要求为每个 FR 声明可验证的 SMART 目标——具体、可衡量、有时限。目标不清晰，流水线不往下走。\n\n**PDCA 自动巡检**\n配置一份 JSON，声明每个功能的 SMART 目标和 liveness probe（HTTP 端点、CLI 命令、文件存在性检查）。巡检引擎自动执行 Plan-Do-Check-Act 循环，验证每个功能在运行态是否真的可用，而不只是代码存在。\n\n**OKR 达成度定期检查**\n为 pipeline 设置终局目标和 OKR 树后，引擎定期检查 KR 达成度。未达标的 KR 自动生成 SMART 拆解建议推给调度层，所有 KR 达成时自动标记 pipeline 为 converged。\n\n**Liveness 验证门禁**\nPublish 阶段自动执行 liveness probe。P0 级探针失败直接阻断发布——代码编译通过但运行时不可用的情况，在发布前就被拦住。\n\n---\n\n## 角色匹配，任务不会派错人\n\n派需求的活给产品经理，派代码的活给开发，派审计的活给审计员。SEVO 根据任务类型自动匹配最合适的 Agent 角色，避免「让写代码的人去定需求」这类错配。角色不对，流水线直接引导。\n\n---\n\n## 智能路由\n\n任务进来后自动判定级别：\n\n- **微小改动**：跳过 spec/contract，直接进实现，走最小闭环\n- **单域中等改动**：从 spec 开始，contract 可简化，门禁不能省\n- **新系统/跨域重构**：走完整 18 阶段，执行全部门禁\n\n支持任意阶段切入——hotfix 从 implement 进，架构调整从 plan 进，不强制从头走。\n\n---\n\n## CLI 命令一览\n\n| 命令 | 说明 |\n|------|------|\n| `sevo init` | 初始化环境，自动检测 OpenClaw、注册插件、分配角色 |\n| `sevo doctor` | 检查配置完整性和环境就绪状态，遇到问题先跑它 |\n| `sevo project create ` | 创建项目和流水线 |\n| `sevo fr add ` | 添加需求，自动触发流水线 |\n| `sevo fr list ` | 列出项目下所有需求及状态 |\n| `sevo status [id]` | 查看流水线状态 |\n| `sevo advance ` | 手动推进阶段 |\n| `sevo show ` | 查看流水线详情 |\n| `sevo list` | 列出所有项目和流水线 |\n| `sevo pause ` | 暂停流水线 |\n| `sevo resume ` | 恢复流水线 |\n| `sevo cancel ` | 取消流水线 |\n| `sevo ledger ` | 查看交付账本 |\n| `sevo export [id]` | 导出流水线数据 |\n| `sevo config` | 查看/修改配置 |\n| `sevo demo` | 交互式体验 |\n| `sevo goal create` | 创建 OKR 目标 |\n| `sevo goal pdca` | 执行 PDCA 巡检 |\n\n---\n\n## 使用场景\n\n**一个人用 AI 做产品**\nAgent 是主力编码者，你是产品操盘手。SEVO 帮你管住 Agent 的产出质量——每轮改动都有目标、有边界、有交付证据。终局交付引擎自动完成版本管理、多平台发布和差距扫描，用户装上用不了的情况不会发生。\n\n**多 Agent 协同开发**\n多个 Agent 各司其职，需要统一的流程约束。SEVO 自动分配角色、编排阶段、独立审计，流水线自动推进。\n\n**从「能跑」到「能用」**\n代码能跑和产品能用之间隔着一道鸿沟。SEVO 的发布后验证门禁逐条对照 spec，确保每个承诺的功能都有对应交付物，陌生用户装上就能感受到价值。\n\n---\n\n## 文档\n\n- [GitHub](https://github.com/yuchangxu1989-Openclaw/sevo)\n- [npm](https://www.npmjs.com/package/sevo)\n\n## License\n\nMIT\n\nFile v1.13.1:_meta.json\n\n{\n \"ownerId\": \"kn71kk78dbbgtentzcetv7d1zn8536vd\",\n \"slug\": \"sevo\",\n \"version\": \"1.13.1\",\n \"publishedAt\": 1779599303919\n}\n\nFile v1.13.1:CHANGELOG.md\n\n# Changelog\n\n本文件记录 sevo-pipeline 的所有重要变更，格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/)。\n\n## [1.0.0] - 2026-05-03\n\n### 新增\n- 后端全部 27 个 FR 的验收标准（AC）100% 覆盖\n- 陌生人开箱即用验证通过（`npm install -g` → `sevo demo` 完整路径可走通）\n- 810 条测试用例，74 个测试文件\n\n### 变更\n- README 重写为营销质量标准（tagline → 痛点 → 优势 → 快速体验 → 场景）\n\n## [0.9.3] - 2026-04-30\n\n### 新增\n- 27 个 FR 全覆盖（含 FR-15 渐进式披露 L2/L3 实现）\n- 810 条测试全绿\n\n### 修复\n- `sevo demo --okr` flag 补齐（陌生人走查 P1）\n\n## [0.9.0] - 2026-04-28\n\n### 新增\n- FR-18 目标驱动 PDCA 闭环：OKR → SMART → PDCA 三层目标体系\n- 目标状态机（draft → active → achieved/missed）\n- PDCA 循环引擎（Plan → Do → Check → Act，最多 3 轮自动收敛）\n- `sevo goal` CLI 命令族（create/list/update/link/pdca）\n- 773 条测试全绿\n\n### 修复\n- TypeScript strict 模式 28 处空检查修复\n\n## [0.7.0] - 2026-04-25\n\n### 新增\n- 门禁系统：需求评审门禁、架构评审门禁（三方会审）、商用化门禁\n- 证据链：每个阶段的输入/输出/结论自动记录\n- 交付账本（Ledger）：串联版本、证据、经验沉淀，支持 `sevo ledger` 查询\n- 评审修复闭环：评审发现问题 → 自动生成修复任务 → 定向复验 → 最多 3 轮收敛\n- 智能路由：L0/L1/L2 三级自动判定，微小改动走最小闭环\n\n## [0.5.0] - 2026-04-22\n\n### 新增\n- 核心 5 阶段完整实现：Specify → Plan → Implement → Review → Release\n- PipelineEngine 流程编排引擎：阶段状态机、自动推进、暂停/恢复/取消\n- 并行阶段支持（测试用例/UX 验收/商用验收/架构契约同时执行）\n- CLI 命令体系：`sevo create`、`sevo status`、`sevo advance`、`sevo list`\n- `sevo init` 自动检测宿主环境、发现 Agent、分配角色\n- 独立审计阶段：写代码的和审代码的职责分离\n\n## [0.1.0] - 2026-04-18\n\n### 新增\n- 项目初始化，基础流水线框架\n- Spec → Contract → Implement → Review → Deploy 五阶段骨架\n- CLI 入口 `sevo`，支持 `--help` 和 `--version`\n- OpenClaw Gateway 插件适配器\n- MIT 协议\n\nFile v1.13.1:docs/arc42-architecture.md\n\n# SEVO — arc42 架构文档\n\n版本 0.1 | 2026-05-03\n\n---\n\n## 目录\n\n1. 引言与目标\n2. 约束条件\n3. 上下文与范围\n4. 解决方案策略\n\n\n\n---\n\n## §1 引言与目标\n\n### 1.1 需求概述\n\nSEVO（Spec-Execute-Verify-Operate）是面向 vibe coding 用户的 Agent 研发流水线。它将需求定义、方案约束、实现执行、独立审计、回归验证、部署发布、清洁环境验收和交付留痕收拢到同一条可追溯流水线上。\n\nSEVO 以 npm 包（`sevo`）分发，`npx sevo init` 一条命令完成环境初始化。核心流程通用化设计，可在任意宿主环境运行；宿主特有能力通过 Adapter 接入增强，但核心流程不因缺少某个宿主而断裂。\n\n### 1.2 架构目标\n\n| ID | 目标 | 优先级 | 驱动力 |\n|----|------|--------|--------|\n| AG-1 | 通用化核心流程 | 最高 | 核心阶段语义、状态机、门禁逻辑、工件交接协议不绑定任何单一宿主实现。换宿主只换 Adapter，核心不动。 |\n| AG-2 | 单包开箱即用 | 最高 | 陌生用户 `npm install -g sevo && npx sevo init` 后 5 分钟内跑通第一条 pipeline。零配置即可启动 L0 级流水线。 |\n| AG-3 | 渐进式披露 | 高 | 四级配置分层（L0 安装即用 → L1 按需配置 → L2 自定义阶段 → L3 编程控制），用户按需解锁，不被复杂度淹没。 |\n| AG-4 | 角色知识内置 | 高 | PM/UX/架构师/审计的专业标准嵌入流水线阶段（Stage-Bound Design），单 Agent 也能产出专业质量工件。 |\n| AG-5 | 工件驱动的可追溯性 | 高 | 每个阶段的输入/输出都是结构化工件，全链路可追溯到 Ledger。没有 Ledger Entry 的交付不算闭环。 |\n| AG-6 | 自动推进与自愈 | 中 | PipelineEngine 状态机驱动阶段流转，门禁失败自动触发 Review Fix Loop，Gateway 重启后自动恢复中断的 pipeline。 |\n| AG-7 | 编排引导而非直接派发 | 中 | 在 OpenClaw 宿主中，PipelineEngine 通过 hook + prompt 注入引导主会话调度，不直接调用 `sessions_spawn`。其他宿主通过 Adapter 实现等效能力。 |\n\n### 1.3 FR 映射\n\n下表将 spec 中的 16 个 FR 映射到架构关注点：\n\n| FR | 名称 | 架构关注点 |\n|----|------|-----------|\n| FR-01 | Spec | 阶段执行器 + 原则注入 + 模糊检测 |\n| FR-02 | Spec Review Gate | 门禁引擎 + 独立评审语义 |\n| FR-02a/b/c | Test Case / UX / Commercial Authoring | 并行分支编排 |\n| FR-03 | Contract | 阶段执行器 + Work Package 拆分 |\n| FR-04 | Contract Review Gate | 三方并行会审 + 门禁引擎 |\n| FR-05 | Implement | 阶段执行器 + TDD 循环 + worktree 隔离 |\n| FR-05a | Systematic Debugging | Implement 内部可选活动 |\n| FR-06 | Review | 双维度独立评审 + spec-code 覆盖检查 |\n| FR-06a | Review Fix Loop | 自动解析→生成 Fix Task→定向复验→门禁重评 |\n| FR-06b | Smoke Test | Review 后置验证 |\n| FR-06c/d | UX Acceptance / PM Commercial Review | 并行验收分支 |\n| FR-07 | Regression | 自动化回归测试 |\n| FR-08 | Deploy | 发布制品生成 |\n| FR-08a | Commercialization Gate | 五层商用化检查 |\n| FR-09 | Verify | 清洁环境独立验证 |\n| FR-10 | Ledger | 交付账本汇总 + 证据链 |\n| FR-11 | Proactive Clarification | 跨阶段模糊检测与主动澄清 |\n| FR-12 | Pipeline Create | 实例创建 + 目录初始化 + 路由判定 |\n| FR-13 | PipelineEngine | 状态机驱动 + 宿主 Adapter + 自动推进 |\n| FR-14 | Package Distribution & CLI | npm 分发 + 单包双入口 + CLI |\n| FR-15 | Progressive Disclosure | 四级配置分层 |\n| FR-16 | Onboarding Experience | demo 命令 + 首次使用引导 |\n\n### 1.4 利益相关方\n\n| 角色 | 关注点 |\n|------|--------|\n| Solo Founder / 独立产品操盘者 | 交付速度、返工成本、线上事故可控 |\n| Agent 原生开发者 | 约束 Agent 的研发流程，减少假完成 |\n| 质量与架构把关者 | 独立视角、统一工件链路、经验沉淀 |\n| 宿主平台与外部 Agent 提供方 | 通用接口、核心逻辑与运行时解耦 |\n| SEVO 维护者 | 模块边界清晰、可测试、可增量演进 |\n\n---\n\n## §2 约束条件\n\n### 2.1 技术约束\n\n| ID | 约束 | 来源 |\n|----|------|------|\n| TC-1 | npm 包分发，包名 `sevo`，TypeScript 编写，编译为 ESM | spec §2.5, FR-14 |\n| TC-2 | 单包双入口：`dist/` 提供库 API，`plugin/` 提供 OpenClaw 插件入口，`bin/` 提供 CLI | 插件分发架构方案 §2.1 |\n| TC-3 | 零运行时依赖（npm dependencies 为空），OpenClaw SDK 通过 `register(api)` 回调注入 | 插件分发架构方案 §2.2 |\n| TC-4 | OpenClaw hook 系统限制：hook 不能发起工具调用，只能注入 prompt 引导主会话调度 | 插件分发架构方案 §5 |\n| TC-5 | 状态持久化使用本地 JSON 文件，不引入外部数据库 | spec NFR-5.7 |\n| TC-6 | 插件加载路径：OpenClaw 通过 `plugins.load.paths` 或 `~/.openclaw/extensions/` 自动扫描发现插件 | 插件分发架构方案 §1.1 |\n\n### 2.2 组织约束\n\n| ID | 约束 | 来源 |\n|----|------|------|\n| OC-1 | 核心流程不绑定单一宿主，但主动复用宿主高价值能力（hooks、guards、session-guard 等）通过 Adapter 接入 | spec §6.4.1, §9.1 |\n| OC-2 | Stage-Bound Design：能力/原则/规范绑定流程阶段，不绑定特定 Agent 身份 | spec §6.6 |\n| OC-3 | 审查与实现阶段默认分离，高风险改动不能只靠实现者自证 | spec §9.1 |\n| OC-4 | 单 Agent 环境自动降级：所有角色池填入同一个 agentId，质量降级但功能完整 | spec FR-15 L0 |\n\n### 2.3 惯例约束\n\n| ID | 约束 | 来源 |\n|----|------|------|\n| CC-1 | FR 流程实例 ID 格式：`fr---` | spec §3.5 |\n| CC-2 | 同一 Project 同一时刻只允许一个 active 的 FR 流程实例 | spec §3.5 |\n| CC-3 | 标准目录结构：`docs/`、`src/`、`tests/`、`reports/`、`artifacts/`、`skill/` | spec §3.6 |\n| CC-4 | 合规模式默认 `guide`（注入流程引导），不阻断执行 | spec FR-15 L0 |\n| CC-5 | Review Fix Loop 最大轮次上限默认 3 轮，超限升级为人工介入 | spec FR-06a AC-4.24i |\n\n---\n\n## §3 上下文与范围\n\n### 3.1 业务上下文\n\n```\n ┌─────────────────────────────────────────┐\n │ SEVO Pipeline │\n │ │\n ┌──────────┐ │ ┌─────────┐ ┌──────────┐ ┌───────┐ │ ┌──────────────┐\n │ │ FR 描述 │ │ Router │→ │ Pipeline │→ │ Gate │ │ 工件 │ │\n │ 用户 │─────────→│ │ │ │ Engine │ │Engine │ │────────→│ Ledger │\n │ │ │ └─────────┘ └──────────┘ └───────┘ │ │ (交付账本) │\n └──────────┘ │ ↕ ↕ ↕ │ └──────────────┘\n ↑ │ ┌─────────────────────────────────┐ │\n │ │ │ Host Adapter │ │\n │ 状态/通知 │ │ (OpenClaw / Standalone / ...) │ │\n │ │ └──────────┬──────────────────────┘ │\n │ └─────────────┼───────────────────────────┘\n │ │\n │ ↓\n │ ┌─────────────────────────────┐\n └────────────────│ 宿主环境 │\n │ (Agent 运行 / 工具接入 / │\n │ 消息调度 / 执行沙箱) │\n └─────────────────────────────┘\n```\n\n外部参与者与 SEVO 的交互：\n\n| 参与者 | 输入 | 输出 |\n|--------|------|------|\n| 用户 | FR 描述、Project 创建、CLI 命令、手动干预（pause/resume/cancel） | Pipeline 状态、阶段工件、Ledger Entry、通知 |\n| 宿主环境 | Agent 执行能力、工具接入、消息调度 | 阶段任务执行结果、完成事件 |\n| npm Registry | — | sevo 包安装 |\n| 发布目标（npm/GitHub/ClawHub） | — | Release Artifact 发布确认 |\n\n### 3.2 技术上下文\n\n```\n ┌──────────────────────────────────────────────────────────────────┐\n │ sevo (npm 包) │\n │ │\n │ ┌──────────┐ ┌──────────────┐ ┌───────────┐ ┌────────────┐ │\n │ │ bin/ │ │ dist/ │ │ plugin/ │ │ templates/ │ │\n │ │ CLI 入口 │ │ 库 API │ │ OpenClaw │ │ 角色模板 │ │\n │ │ │ │ │ │ 插件入口 │ │ 阶段原则 │ │\n │ └────┬─────┘ └──────┬───────┘ └─────┬─────┘ └────────────┘ │\n │ │ │ │ │\n │ │ ┌──────────┴────────────────┤ │\n │ │ │ │ │\n │ ▼ ▼ ▼ │\n │ ┌──────────────┐ ┌──────────────┐ │\n │ │ Core Modules │ │ bridge.js │ │\n │ │ │◄─────────────│ (胶水层) │ │\n │ │ • Pipeline │ └──────────────┘ │\n │ │ Engine │ │ │\n │ │ • Stage │ │ register(api) │\n │ │ Runner │ ▼ │\n │ │ • Clarific. │ ┌──────────────┐ │\n │ │ Coordinator│ │ OpenClaw │ │\n │ │ • Compliance │ │ Gateway │ │\n │ │ Router │ │ (运行时注入) │ │\n │ │ • RoleKnow. │ └──────────────┘ │\n │ │ Injector │ │\n │ └──────────────┘ │\n └──────────────────────────────────────────────────────────────────┘\n │ │\n ▼ ▼\n ┌──────────────────┐ ┌──────────────────────┐\n │ 本地文件系统 │ │ 宿主 Hook 系统 │\n │ • pipeline state │ │ • before_prompt_build │\n │ • 工件目录 │ │ • subagent_ended │\n │ • sevo.config │ │ • before_tool_call │\n └──────────────────┘ └──────────────────────┘\n```\n\n### 3.3 SEVO 与相邻系统的边界\n\n| 系统 | SEVO 负责 | 对方负责 | 边界 |\n|------|----------|---------|------|\n| KIVO（知识治理） | 研发流程中的经验沉淀接口 | 知识库治理、向量化、去重 | SEVO 产出经验条目，KIVO 消费 |\n| AEO（效果运营） | 阶段效果数据输出接口 | 效果度量、运营分析 | SEVO 产出阶段数据，AEO 消费 |\n| Claw Design（设计产物） | Claw Design 自身研发时的流水线 | 设计产物生成能力 | SEVO 是研发工具，Claw Design 是被研发的产品 |\n| 宿主环境 | 阶段语义、工件语言、门禁逻辑、验收闭环 | Agent 运行、工具接入、消息调度、执行沙箱 | SEVO 定义通用流程，宿主做适配 |\n\n---\n\n## §4 解决方案策略\n\n### 4.1 编排模型：Hook + Prompt 引导\n\nSEVO 的核心设计决策是**不直接派发任务**。PipelineEngine 定义编排语义（何时推进、何时阻断、何时重试），具体的任务派发方式由宿主 Adapter 实现。\n\n在 OpenClaw 宿主中，编排通过三个 hook 实现：\n\n| Hook | 触发时机 | 职责 |\n|------|---------|------|\n| `before_prompt_build` | 主会话构建 prompt 前 | 注入「下一步该派发什么任务」的指令 + 阶段执行原则 |\n| `subagent_ended` | 子 Agent 任务完成时 | 解析完成事件 → 更新 pipeline 状态 → 设置下一阶段推进指令 |\n| `before_tool_call` | 工具调用前 | 合规检查（guide/auto-route 模式下检测未编排的开发任务） |\n\n这个模型的关键约束：hook 不能发起工具调用（OpenClaw 平台限制），只能通过 prompt 注入引导主会话做出调度决策。主会话仍然是调度者，PipelineEngine 是编排顾问。\n\n对于非 OpenClaw 宿主，Adapter 接口定义等效能力：\n\n```typescript\ninterface HostAdapter {\n // 触发阶段执行（宿主决定具体派发方式）\n triggerStage(stage: StageId, context: StageContext): Promise;\n // 监听阶段完成事件\n onStageComplete(callback: (result: StageResult) => void): void;\n // 注入阶段执行原则\n injectPrinciples(stage: StageId, principles: string): Promise;\n // 通知用户\n notify(message: string, channel?: string): Promise;\n}\n```\n\n### 4.2 合规模式\n\nSEVO 对未经编排的开发任务提供三种处理策略，通过配置切换：\n\n| 模式 | 行为 | 适用场景 |\n|------|------|---------|\n| `guide` (默认) | 在 `before_prompt_build` 中注入流程引导提示，建议用户走 SEVO 流程，但不阻断执行 | 初次接入、渐进式采纳 |\n| `auto-route` | 自动为未编排的开发任务创建 pipeline 并路由进 SEVO 流程 | 团队已全面采纳 SEVO |\n| `off` | 不干预，SEVO 只管已显式创建的 pipeline | 部分项目不走 SEVO |\n\n注意：没有「强制阻断」概念。即使在 `auto-route` 模式下，SEVO 也是创建 pipeline 并引导，不是阻断任务执行。\n\n### 4.3 角色知识内置（Stage-Bound Design）\n\nSEVO 把 PM、UX、架构师、审计等角色的专业标准嵌入流水线阶段，而非绑定到特定 Agent 身份。\n\n实现方式：PipelineEngine 在触发阶段执行时，通过 Adapter 的 `injectPrinciples()` 自动注入该阶段应遵循的执行原则模板。\n\n阶段与注入原则的映射：\n\n| 阶段 | 注入原则 | 来源 |\n|------|---------|------|\n| Spec | 用户价值优先、需求完整度校验、概念-技术阶段隔离、主动澄清 | PM 最佳实践 |\n| Contract | 通用化三问、Stage-Bound Design、Adapter 模式、最小改动原则 | 架构师最佳实践 |\n| Implement | TDD 循环、Karpathy Guidelines（最小改动、最简实现、目标驱动）、系统化调试 | 工程最佳实践 |\n| Review | spec-code 覆盖检查、AC 覆盖矩阵、独立审计、证据驱动 | 审计最佳实践 |\n| Smoke Test / UX Acceptance | 陌生用户视角、开箱即用五维度检查 | UX 最佳实践 |\n| Deploy | 五层商用化检查、敏感信息扫描、原子发布 | 发布工程最佳实践 |\n\n效果：单 Agent 用户执行 Spec 阶段时，自动获得 PM 质量的 prompt 引导；多 Agent 环境有专职 PM 角色则效果更好，但不是必须。\n\n### 4.4 状态机驱动的自动推进\n\nPipelineEngine 是 SEVO 的核心运行时。它读取路由结果中的 Stage Queue，按状态机规则自动推进：\n\n```\ncreated → active（第一个阶段开始）→ ... → completed（Ledger 通过）\n ↘ failed（不可恢复）\n```\n\n每个阶段的状态机：\n\n```\npending → active → passed → (下一阶段)\n ↓ ↗\n blocked / failed → (修复) → active\npending → skipped（路由裁剪）\n```\n\n关键行为：\n\n- 阶段完成后 30 秒内评估门禁并决定推进或阻断（AC-13.2）\n- 门禁失败自动触发 Review Fix Loop（FR-06a）\n- Gateway 重启后 60 秒内自动恢复中断的 pipeline（AC-13.8）\n- 支持并行阶段组（FR-02a/b/c 与 FR-03 并行；FR-06c 与 FR-06d 并行）\n\n### 4.5 流程路径裁剪\n\nSEVO 根据任务复杂度自动选择最短有效路径：\n\n| 级别 | 触发条件 | 必经阶段 |\n|------|---------|---------|\n| L0 | 微小改动（bug 修复、配置调整） | implement → review → smoke-test → verify → ledger |\n| L1 | 单域中等改动 | spec → spec-review-gate → contract(简化) → implement → review → smoke-test → regression → deploy → verify → ledger |\n| L2+ | 新系统、跨域重构、大范围变更 | 完整 8 阶段 + 全部门禁 + 并行验收分支 |\n\n裁剪规则由 Router 模块（`level-classifier.ts` + `stage-graph.ts`）实现，跳过的阶段记录理由，不破坏工件链的可追溯性。\n\n### 4.6 单包双入口分发策略\n\nnpm 包同时提供库 API 和 OpenClaw 插件两个入口，解决「外部用户装了包但流水线跑不起来」的问题：\n\n```\nsevo/\n├── dist/ # 库 API（PipelineEngine, GateEngine, LedgerEngine, Adapter...）\n├── plugin/ # OpenClaw 插件入口（register + hooks + bridge.js）\n├── bin/ # CLI 入口（sevo init / status / project / fr / doctor）\n├── templates/ # 角色执行原则模板\n└── package.json\n```\n\n`sevo init` 流程：检测宿主环境 → 注册插件到 `openclaw.json` → 动态发现 Agent 并分类角色 → 单 Agent 自动降级 → doctor 检查 → 输出下一步指引。\n\n`plugin/bridge.js` 是胶水层：插件通过它动态加载 `../dist/` 下的编译产物，获取 PipelineEngine 等核心能力。加载失败则降级为 no-op。\n\n### 4.7 关键架构决策摘要\n\n| 决策 | 选择 | 理由 |\n|------|------|------|\n| 编排方式 | Hook + prompt 注入引导，不直接派发 | OpenClaw hook 不能发起工具调用；保持主会话为调度者，SEVO 为编排顾问 |\n| 包结构 | 单包双入口（dist/ + plugin/） | 避免用户装两个包；OpenClaw 插件加载器期望独立目录 + `openclaw.plugin.json` |\n| 状态持久化 | 本地 JSON 文件 | 零依赖、可读、可 git 追踪；不引入外部数据库 |\n| 角色知识 | 内置到阶段（Stage-Bound Design） | 单 Agent 也能用；不假设用户有特定名称或数量的 Agent |\n| 合规模式 | guide / auto-route / off（无强制路由） | 渐进式采纳；不强制用户改变工作方式 |\n| 宿主适配 | Adapter 接口 | 核心通用 + 宿主能力通过 Adapter 接入 = 既通用又能用上所有本地优势 |\n| Agent 发现 | 命名规则 + runtime type + 显式声明三层信号 | 兼容已有命名习惯；外部用户 Agent 命名不可预测时有 fallback |\n\n## §5 构建块视图\n\n### 5.1 顶层分解\n\n```\nsevo\n├── PipelineEngine 状态机驱动的流程编排核心\n│ ├── GateEngine 门禁规则评估（PipelineEngine 内部模块）\n│ └── LedgerEngine 交付账本汇总与证据链（PipelineEngine 内部模块）\n├── StageRunner 单阶段执行器（门禁 + prompt 注入）\n├── ClarificationCoordinator 跨阶段模糊检测与主动澄清（FR-11）\n├── RoleKnowledgeInjector 角色专业标准注入\n├── ComplianceRouter 合规路由（guide / auto-route / off）\n├── CLIInterface sevo init / status / project / fr / doctor\n└── PluginAdapter OpenClaw hook 注册与事件分发\n```\n\n依赖方向：CLIInterface → PipelineEngine → StageRunner → RoleKnowledgeInjector；StageRunner → ClarificationCoordinator；PluginAdapter → PipelineEngine / StageRunner / ComplianceRouter / RoleKnowledgeInjector；ComplianceRouter 仅被 PluginAdapter 调用（不被 PipelineEngine 调用，避免循环依赖）。\n\nGateEngine 和 LedgerEngine 是 PipelineEngine 的内部模块，不作为独立顶层构建块暴露。GateEngine 负责门禁规则评估（接收 StageRunner 的阶段结果，判定 pass/fail）；LedgerEngine 负责交付账本的写入和查询（pipeline 完成时汇总全链路工件记录）。CLIInterface 的 `sevo ledger` 命令通过 PipelineEngine 间接访问 LedgerEngine。\n\n---\n\n### 5.2 PipelineEngine\n\n**职责**：SEVO 的核心运行时。管理 pipeline 实例的完整生命周期——创建 Stage Queue、按状态机规则推进阶段、评估门禁、触发 Review Fix Loop、处理并行阶段组、Gateway 重启后自动恢复。\n\n**接口**：\n\n| 方法 | 说明 |\n|------|------|\n| `createPipeline(projectSlug, frDescription, routeResult)` | 创建 pipeline 实例，生成 Stage Queue |\n| `advance(pipelineId)` | 评估当前阶段出口条件，满足则推进到下一阶段 |\n| `handleStageComplete(pipelineId, stageId, result)` | 接收阶段完成事件，更新状态，触发 advance |\n| `getPipelineState(pipelineId)` | 返回 pipeline 当前状态快照 |\n| `pause(pipelineId)` / `resume(pipelineId)` / `cancel(pipelineId)` | 生命周期控制 |\n| `recoverInterrupted()` | 启动时扫描持久化状态，恢复中断的 pipeline |\n\n**状态机**：\n\n- pipeline 级别：`created → active → completed / failed`，支持 `paused` 中间态。\n- stage 级别：`pending → active → passed / failed / blocked`，`pending → skipped`（路由裁剪）。\n- 并行阶段组（如 FR-02a/b/c + FR-03，FR-06c + FR-06d）：组内阶段同时触发，全部 passed 后组才算通过。\n\n**依赖**：\n\n- StageRunner：委托执行单个阶段。\n- 宿主 Adapter（`HostAdapter` 接口）：触发阶段执行、监听完成事件、注入原则、通知用户。\n- 本地 JSON 文件（`active-pipelines.json`）：状态持久化，支持 Gateway 重启恢复。\n\n**关键约束**：PipelineEngine 定义编排语义（何时推进、何时阻断），不直接派发任务。具体派发方式由宿主 Adapter 实现。\n\n---\n\n### 5.3 StageRunner\n\n**职责**：单阶段执行器。接收 PipelineEngine 的阶段触发指令，组装阶段上下文（输入工件 + 执行原则 + 门禁规则），通过 Adapter 触发执行，评估出口条件。\n\n**接口**：\n\n| 方法 | 说明 |\n|------|------|\n| `run(stageId, context: StageContext)` | 组装上下文 → 注入角色知识 → 通过 Adapter 触发执行 |\n| `evaluateGate(stageId, result: StageResult)` | 检查出口工件是否齐全、门禁规则是否满足 |\n\n**StageContext 结构**：\n\n```typescript\ninterface StageContext {\n pipelineId: string;\n stageId: string;\n inputArtifacts: ArtifactRef[]; // 上游阶段产出的工件引用\n principles: string; // RoleKnowledgeInjector 注入的执行原则\n gateRules: GateRule[]; // 本阶段出口门禁规则\n agentHint?: string; // 建议执行的 agent 角色\n}\n```\n\n**依赖**：\n\n- RoleKnowledgeInjector：获取阶段执行原则。\n- GateEngine（`dist/` 库模块）：评估门禁规则。\n- 宿主 Adapter：实际触发阶段执行。\n\n**关键行为**：门禁失败时返回 `{ passed: false, issues: ReviewIssue[] }` 给 PipelineEngine，由 PipelineEngine 决定是否触发 Review Fix Loop。\n\n**商用化门禁（FR-08a）**：Deploy 阶段的 Commercialization Gate 由 StageRunner 通过 GateEngine 执行。五层检查规则（代码清洁度、包完整性、文档质量、可构建性、开箱即用）作为 Deploy 阶段的门禁规则内置在 RoleKnowledgeInjector 的 `templates/deploy-principles.md` 中。GateEngine 评估时加载这些规则，执行敏感信息扫描（`.env` 文件、API key 模式匹配、密钥文件、内部配置路径）和五层完整性检查。检查规则可通过 L2 配置扩展。\n\n---\n\n### 5.4 RoleKnowledgeInjector\n\n**职责**：将 PM、UX、架构师、审计等角色的专业标准映射到流水线阶段，产出可注入的 prompt 模板。实现 Stage-Bound Design——能力绑定阶段，不绑定 Agent 身份。\n\n**接口**：\n\n| 方法 | 说明 |\n|------|------|\n| `getPrinciples(stageId): string` | 返回该阶段的执行原则模板 |\n| `getGateRules(stageId): GateRule[]` | 返回该阶段的默认门禁规则 |\n\n**阶段→原则映射**：\n\n| 阶段 | 注入原则来源 | 模板位置 |\n|------|-------------|----------|\n| Spec | PM 最佳实践（用户价值优先、完整度校验、主动澄清） | `templates/spec-principles.md` |\n| Contract | 架构师最佳实践（通用化三问、Stage-Bound Design、最小改动） | `templates/contract-principles.md` |\n| Implement | 工程最佳实践（TDD 循环、Karpathy Guidelines、系统化调试） | `templates/implement-principles.md` |\n| Review | 审计最佳实践（spec-code 覆盖、AC 矩阵、证据驱动） | `templates/review-principles.md` |\n| Smoke Test / UX Acceptance | UX 最佳实践（陌生用户视角、开箱即用五维度） | `templates/ux-principles.md` |\n| Deploy | 发布工程最佳实践（五层商用化检查、敏感信息扫描） | `templates/deploy-principles.md` |\n\n**依赖**：`templates/` 目录下的 markdown 模板文件。无外部依赖。\n\n**关键约束**：模板随 npm 包分发，用户可通过 L2 配置覆盖默认模板。\n\n---\n\n### 5.5 ComplianceRouter\n\n**职责**：对未经 SEVO 编排的开发任务进行路由判定。根据合规模式（`guide` / `auto-route` / `off`）决定处理策略。\n\n**接口**：\n\n| 方法 | 说明 |\n|------|------|\n| `evaluate(taskContext): ComplianceResult` | 判断任务是否属于 SEVO 编排范围，返回处理策略 |\n| `classifyLevel(description, codeStats?): Level` | 根据任务描述和代码统计判定 Level 0/1/2+ |\n\n**三种模式行为**：\n\n- `guide`（默认）：检测到未编排的开发任务时，在 prompt 中注入流程引导提示，建议走 SEVO 流程，不阻断执行。\n- `auto-route`：自动为未编排的开发任务创建 pipeline 并路由进 SEVO 流程。\n- `off`：不干预，SEVO 只管已显式创建的 pipeline。\n\n**依赖**：\n\n- SEVO Config：读取合规模式配置。\n\n**关键约束**：没有「强制阻断」概念。即使 `auto-route` 模式也是创建 pipeline 并引导，不阻断任务执行。ComplianceRouter 仅被 PluginAdapter 调用（在 `before_tool_call` hook 中），不被 PipelineEngine 调用。`auto-route` 模式下，ComplianceRouter 返回 `{ action: create }` 后，由 PluginAdapter 调用 `PipelineEngine.createPipeline()` 创建新 pipeline，避免 ComplianceRouter 与 PipelineEngine 之间的循环依赖。\n\n---\n\n### 5.6 CLIInterface\n\n**职责**：SEVO 的用户交互入口。提供 `bin/sevo.js` CLI，覆盖初始化、项目管理、FR 管理、状态查询和手动干预。\n\n**命令清单**：\n\n| 命令 | 说明 |\n|------|------|\n| `sevo init` | 环境检测 → 插件注册 → Agent 发现 → 角色分配 → doctor 检查 |\n| `sevo doctor` | 配置完整性和环境就绪状态检查 |\n| `sevo project create ` | 创建 Project，初始化标准目录结构 |\n| `sevo project list` | 列出所有 Project |\n| `sevo fr add ` | 添加 FR，自动触发 pipeline 创建 |\n| `sevo fr list ` | 列出 Project 下所有 FR 及 pipeline 状态 |\n| `sevo status [instance-id]` | 查看 pipeline 当前阶段、卡点、下一步 |\n| `sevo pause / resume / cancel` | pipeline 生命周期控制 |\n| `sevo ledger [project]` | 查看交付账本 |\n| `sevo demo [--dry-run]` | 首次体验引导（dry-run 用 mock 数据，无需 LLM） |\n\n**依赖**：\n\n- PipelineEngine：pipeline 创建、状态查询、生命周期控制。\n- ComplianceRouter：`sevo init` 时设置默认合规模式。\n- 宿主环境检测：`findOpenClawHome()` 定位 `openclaw.json`，计算插件路径。\n- LedgerEngine（`dist/` 库模块）：账本查询。\n\n**关键约束**：CLI 不依赖特定宿主环境，在纯 Node.js 环境中可运行。OpenClaw 特有操作（插件注册、Agent 发现）仅在检测到 OpenClaw 环境时执行。\n\n---\n\n### 5.7 PluginAdapter\n\n**职责**：OpenClaw 宿主的 Adapter 实现。通过 `register(api)` 回调注册三个 hook，将 PipelineEngine 的编排语义映射为 OpenClaw 的 prompt 注入 + 事件驱动模型。\n\n**Hook 注册**：\n\n| Hook | 触发时机 | 行为 |\n|------|---------|------|\n| `before_prompt_build` | 主会话构建 prompt 前 | 检测活跃 pipeline → 注入 `[SEVO Auto-Advance]` 指令（下一步该派发什么任务）+ 阶段执行原则 |\n| `subagent_ended` | 子 Agent 完成时 | 解析 SEVO 标签 → 调用 `PipelineEngine.handleStageComplete()` → 设置下一阶段推进指令 |\n| `before_tool_call` | 工具调用前 | 匹配 `sessions_spawn` → 注入 SEVO 标签到 label；ComplianceRouter 检查未编排任务 |\n\n**标签协议**：`sevo:::`，用于关联子 Agent 任务与 pipeline 阶段。\n\n**bridge.js 胶水层**：PluginAdapter 通过 `bridge.js` 动态加载 `../dist/` 下的编译产物（PipelineEngine、GateEngine、LedgerEngine 等）。加载失败则降级为 no-op，插件不崩溃。\n\n**依赖**：\n\n- OpenClaw Gateway API（通过 `register(api)` 注入，无 import 依赖）。\n- PipelineEngine、StageRunner、ComplianceRouter（通过 bridge.js 动态加载）。\n- RoleKnowledgeInjector（注入阶段执行原则到 prompt）。\n\n**关键约束**：hook 不能发起工具调用（OpenClaw 平台限制），只能通过 prompt 注入引导主会话做出调度决策。主会话仍然是调度者，PluginAdapter 是编排顾问的宿主侧实现。\n\n---\n\n### 5.8 ClarificationCoordinator\n\n**职责**：跨阶段模糊检测与主动澄清（FR-11）。在阶段执行过程中检测工件中的模糊信号，生成结构化澄清问题，将澄清结果回写到目标工件。\n\n**接口**：\n\n| 方法 | 说明 |\n|------|------|\n| `detectAmbiguity(stageId, artifact): AmbiguitySignal[]` | 扫描工件内容，返回检测到的模糊信号列表（8 种触发条件：未定义术语、矛盾约束、缺失边界、多义词、隐含假设、不完整场景、模糊优先级、未解决的开放问题） |\n| `generateClarification(signals): ClarificationRequest` | 根据模糊信号生成结构化澄清问题，按 6 种类型分类（纠偏/方法/决策/边界/经验/元认知） |\n| `resolveAndWriteBack(response, targetArtifact)` | 将澄清收敛结果回写到目标工件（spec/contract/实现方案），确保澄清结论不仅停留在对话中 |\n\n**触发时机**：StageRunner 在以下阶段执行过程中调用 ClarificationCoordinator：\n\n| 阶段 | 检测时机 | 澄清对象 |\n|------|---------|----------|\n| Spec | 工件输出前 | 用户或上游 Agent（通过宿主 Adapter 发起澄清问题） |\n| Contract | 架构方案输出前 | 用户或 Spec 作者 |\n| Implement | 检测到实现歧义时 | 上游阶段工件作者 |\n\n**依赖**：\n\n- RoleKnowledgeInjector：提供各阶段的模糊检测规则（内嵌在阶段执行原则模板中）。\n- 宿主 Adapter：通过 `notify()` 向用户发起澄清问题，通过 `injectPrinciples()` 将澄清结果注入后续阶段。\n- 本地文件系统：回写工件。\n\n**关键约束**：澄清流程不阻断阶段执行。检测到模糊信号时，如果模糊度低于阈值，记录但不触发澄清；超过阈值时暂停阶段执行，等待澄清完成后继续。澄清超时（默认 24h）后自动升级为人工介入。\n\n---\n\n### 5.9 模块间依赖总览\n\n```\n ┌──────────────┐\n │ CLIInterface │\n └──────┬───────┘\n │\n ▼\n┌───────────────┐ ┌──────────────────┐\n│ PluginAdapter │──▶│ PipelineEngine │\n└──┬──┬──┬──┬───┘ └────────┬─────────┘\n │ │ │ │ │\n │ │ │ │ ▼\n │ │ │ │ ┌──────────────┐\n │ │ │ └───────▶│ StageRunner │\n │ │ │ └───┬──────┬──┘\n │ │ │ │ │\n │ │ │ ▼ ▼\n │ │ │ ┌──────────────────────┐ ┌──────────────────────────┐\n │ │ └─▶│ RoleKnowledgeInjector│ │ ClarificationCoordinator │\n │ │ └──────────────────────┘ └──────────────────────────┘\n │ │\n │ ▼\n │ ┌───────────────────┐\n └─▶│ ComplianceRouter │\n └───────────────────┘\n```\n\n箭头表示调用方向。PluginAdapter 依赖 PipelineEngine、StageRunner、ComplianceRouter、RoleKnowledgeInjector 四个模块。ComplianceRouter 仅被 PluginAdapter 调用，不与 PipelineEngine 产生直接依赖。ClarificationCoordinator 被 StageRunner 调用。所有模块通过 TypeScript 接口解耦，宿主 Adapter 实现 `HostAdapter` 接口，核心模块不直接引用任何宿主 API。\n\n## §6 运行时视图\n\n本节描述 SEVO 五个关键运行时流程的交互时序。所有流程均以 OpenClaw 宿主为例；其他宿主通过 HostAdapter 实现等效行为。\n\n### 6.1 Pipeline 创建（FR-12）\n\n```\n用户 CLI PipelineEngine 文件系统\n │ │ │ │\n │ sevo fr add │ │ │\n │ │ │ │\n │──────────────────▶│ │ │\n │ │ classifyLevel() │ │\n │ │───────────────────▶│ │\n │ │ Level + stages │ │\n │ │◀───────────────────│ │\n │ │ createPipeline() │ │\n │ │───────────────────▶│ │\n │ │ │ 生成实例 ID │\n │ │ │ fr---\n │ │ │ │\n │ │ │ 检查/补全目录结构 │\n │ │ │──────────────────▶│\n │ │ │ 写 active-pipelines.json\n │ │ │──────────────────▶│\n │ │ │ │\n │ │ │ 状态: created → active\n │ │ │ 触发 advance() │\n │ │ pipeline 已创建 │ │\n │ │◀───────────────────│ │\n │ 实例 ID + 状态 │ │ │\n │◀──────────────────│ │ │\n```\n\n关键行为：\n- ComplianceRouter.classifyLevel() 根据任务描述判定 Level 0/1/2+，产出必经阶段清单。\n- 同一 Project 已有 active 实例时，createPipeline() 拒绝创建并返回错误。\n- 目录结构按 §3.6 规范补全，已有内容不覆盖。\n- 创建完成后立即调用 advance()，pipeline 自动进入第一个阶段。\n\n### 6.2 阶段推进（FR-13 PipelineEngine 核心循环）\n\n```\nPluginAdapter PipelineEngine StageRunner 主会话\n(subagent_ended) │ │ │\n │ │ │ │\n │ handleStageComplete() │ │ │\n │───────────────────────▶│ │ │\n │ │ evaluateGate() │ │\n │ │─────────────────▶│ │\n │ │ { passed: true }│ │\n │ │◀─────────────────│ │\n │ │ │ │\n │ │ stage.status = passed │\n │ │ advance() → 下一阶段 │\n │ │ │ │\n │ │ StageRunner.run(nextStage) │\n │ │─────────────────▶│ │\n │ │ │ getPrinciples()│\n │ │ │ (RoleKnowledge)│\n │ │ │ │\n │ │ │ 组装 StageContext\n │ │ │ │\n │ 设置 [SEVO Auto-Advance] 指令 │ │\n │◀──────────────────────────────────────────│ │\n │ │ │ │\n │ before_prompt_build 注入 │ │\n │──────────────────────────────────────────────────────────▶│\n │ │ │ 主会话读取指令 │\n │ │ │ 派发子 Agent │\n │ │ │ (sessions_spawn)\n```\n\n关键行为：\n- 门禁评估在阶段完成后 30 秒内完成（AC-13.2）。\n- 门禁失败时 PipelineEngine 自动触发 Review Fix Loop（FR-06a），不推进到下一阶段。\n- 并行阶段组（如 FR-06c + FR-06d）：组内阶段同时触发，全部 passed 后才推进。\n- 每一步推进决策写入持久化状态文件，支持断点恢复。\n\n门禁失败分支：\n\n```\nPipelineEngine StageRunner ReviewFixLoop\n │ │ │\n │ evaluateGate() │ │\n │─────────────────────▶│ │\n │ { passed: false, │ │\n │ issues: [...] } │ │\n │◀─────────────────────│ │\n │ │ │\n │ stage.status = blocked │\n │ triggerFixLoop(issues) │\n │────────────────────────────────────────▶│\n │ │ │ 解析问题 → 生成 Fix Task\n │ │ │ P0/P1 排入修复队列\n │ │ │ 修复完成 → 定向复验\n │ │ │ 复验通过\n │ fixLoop.resolved() │ │\n │◀────────────────────────────────────────│\n │ │ │\n │ stage.status = active │\n │ 重新评估门禁 → advance() │\n```\n\n### 6.3 sevo init 初始化流程（FR-14）\n\n```\n用户 CLI(sevo init) 文件系统 openclaw.json\n │ │ │ │\n │ npx sevo init │ │ │\n │───────────────────▶│ │ │\n │ │ │ │\n │ │ 检测宿主环境 │ │\n │ │ findOpenClawHome() │\n │ │─────────────────────────────────────▶│\n │ │ 读取 agents.list │ │\n │ │◀─────────────────────────────────────│\n │ │ │ │\n │ │ Agent 发现与角色映射 │\n │ │ 命名规则 + runtime type + 显式声明 │\n │ │ 单 Agent → 降级模式（全角色同一 ID） │\n │ │ │ │\n │ │ 生成 sevo.config.json │\n │ │─────────────────▶│ │\n │ │ │ │\n │ │ 注册插件到 openclaw.json │\n │ │ plugins.load.paths += sevo/plugin\n │ │─────────────────────────────────────▶│\n │ │ │ │\n │ │ 注入角色 SOUL.md │ │\n │ │ roles//agent/SOUL.md │\n │ │─────────────────▶│ │\n │ │ │ │\n │ │ sevo doctor │ │\n │ │ (配置完整性检查) │ │\n │ │ │ │\n │ 角色分配表 + │ │ │\n │ 下一步指引 │ │ │\n │◀───────────────────│ │ │\n```\n\n关键行为：\n- 三层 Agent 发现信号：命名规则（dev-/audit-/sa-/pm-/ux- 前缀）→ runtime type（subagent/acp）→ 显式声明（sevo.config 中手动指定）。\n- 单 Agent 环境自动降级：所有角色池填入同一个 agentId，质量降级但功能完整。\n- 非 OpenClaw 环境跳过插件注册和 Agent 发现，只生成配置文件和模板。\n- doctor 检查失败时输出逐项修复建议，不阻断 init 完成。\n\n### 6.4 合规路由（auto-route 模式，FR-13 + ComplianceRouter）\n\n```\n主会话 PluginAdapter ComplianceRouter PipelineEngine\n │ │ │ │\n │ sessions_spawn │ │ │\n │ (开发任务,无 SEVO 标签) │ │\n │─────────────────────▶│ │ │\n │ │ │ │\n │ before_tool_call │ │ │\n │ │ evaluate(task) │ │\n │ │───────────────────▶│ │\n │ │ │ 模式=auto-route │\n │ │ │ classifyLevel() │\n │ │ │ → Level 1 │\n │ │ { action: create }│ │\n │ │◀───────────────────│ │\n │ │ │ │\n │ │ createPipeline() │ │\n │ │──────────────────────────────────────▶│\n │ │ │ pipeline 已创建 │\n │ │◀──────────────────────────────────────│\n │ │ │ │\n │ │ 注入 SEVO 标签到 spawn label │\n │ │ sevo::spec:1 │\n │ │ │ │\n │ spawn 继续执行 │ │ │\n │ (带 SEVO 标签) │ │ │\n │◀─────────────────────│ │ │\n```\n\n关键行为：\n- `guide` 模式下不创建 pipeline，只在 prompt 中注入流程引导提示。\n- `off` 模式下 evaluate() 直接返回 `{ action: pass }`，不干预。\n- `auto-route` 模式下自动创建 pipeline 并注入标签，任务无感知地进入 SEVO 流程。\n- 标签协议 `sevo:::` 用于 subagent_ended hook 关联完成事件。\n\n### 6.5 澄清流程（FR-11 Proactive Clarification）\n\n```\nStageRunner ClarificationCoordinator 宿主 Adapter 用户/上游 Agent\n │ │ │ │\n │ detectAmbiguity() │ │ │\n │────────────────────────▶│ │ │\n │ signals[] │ │ │\n │◀────────────────────────│ │ │\n │ │ │ │\n │ [模糊度 > 阈值] │ │ │\n │ generateClarification() │ │ │\n │────────────────────────▶│ │ │\n │ ClarificationRequest │ │ │\n │◀────────────────────────│ │ │\n │ │ │ │\n │ 暂停阶段执行 │ │ │\n │ │ notify(澄清问题) │ │\n │ │─────────────────────▶│ │\n │ │ │ 澄清问题 │\n │ │ │────────────────▶│\n │ │ │ │\n │ │ │ 澄清回复 │\n │ │ │◀────────────────│\n │ │ 澄清回复 │ │\n │ │◀─────────────────────│ │\n │ │ │ │\n │ resolveAndWriteBack() │ │ │\n │────────────────────────▶│ │ │\n │ │ 回写工件 │ │\n │ │─────────────────────▶│ │\n │ │ │ │\n │ 恢复阶段执行 │ │ │\n │ (工件已更新) │ │ │\n```\n\n关键行为：\n- 模糊度低于阈值时，记录信号但不触发澄清，阶段继续执行。\n- 模糊度超过阈值时，暂停阶段执行，通过宿主 Adapter 向用户或上游 Agent 发起澄清。\n- 澄清回复到达后，ClarificationCoordinator 将收敛结果回写到目标工件，确保澄清结论不仅停留在对话中。\n- 澄清超时（默认 24h）后自动升级为人工介入，阶段状态转为 blocked。\n- 澄清记录作为阶段工件的一部分归档到 Ledger。\n\n---\n\n## §7 部署视图\n\n### 7.1 npm 包结构\n\nSEVO 以单个 npm 包 `sevo` 分发，包含三个入口：\n\n```\nsevo/ # npm 包根目录\n├── bin/\n│ └── sevo.js # CLI 入口（#!/usr/bin/env node）\n├── dist/ # 编译产物（ESM）\n│ ├── index.js # 库 API 主入口\n│ ├── pipeline-engine.js # PipelineEngine\n│ ├── stage-runner.js # StageRunner\n│ ├── gate-engine.js # GateEngine（门禁评估）\n│ ├── ledger-engine.js # LedgerEngine（交付账本）\n│ ├── compliance-router.js # ComplianceRouter\n│ ├── role-knowledge-injector.js\n│ ├── adapters/\n│ │ ├── host-adapter.js # HostAdapter 接口定义\n│ │ └── openclaw-adapter.js # OpenClaw 宿主适配实现\n│ └── types/ # TypeScript 类型声明（.d.ts）\n├── plugin/ # OpenClaw 插件目录\n│ ├── openclaw.plugin.json # 插件元数据（name, version, hooks）\n│ ├── index.js # register(api) 入口\n│ └── bridge.js # 胶水层：动态加载 ../dist/ 编译产物\n├── templates/ # 角色执行原则模板\n│ ├── spec-principles.md\n│ ├── contract-principles.md\n│ ├── implement-principles.md\n│ ├── review-principles.md\n│ ├── ux-principles.md\n│ └── deploy-principles.md\n├── package.json # name, bin, main, exports, files\n├── README.md\n└── LICENSE\n```\n\n分发原则：\n- npm 包只包含编译产物（dist/）+ 插件（plugin/）+ 模板（templates/）+ CLI（bin/）+ 文档。\n- TypeScript 源码不随 npm 包分发，通过 GitHub 独立仓库提供。\n- `dependencies` 为空（零运行时依赖），OpenClaw SDK 通过 `register(api)` 回调注入。\n\n### 7.2 sevo init 注册流程\n\n`sevo init` 在 OpenClaw 环境中执行以下注册操作：\n\n```\n1. 检测 OpenClaw 安装\n └─ findOpenClawHome() → 定位 ~/.openclaw/openclaw.json\n └─ 未找到 → 输出安装引导链接，跳过插件注册\n\n2. 注册插件\n └─ 计算插件绝对路径：/sevo/plugin/\n └─ 写入 openclaw.json → plugins.load.paths 追加插件路径\n └─ 不覆盖已有条目（幂等）\n\n3. Agent 发现与角色分配\n └─ 读取 openclaw.json → agents.list\n └─ 三层信号匹配：\n ├─ 命名规则：dev-* → coding, audit-* → review, sa-* → architecture, pm-* → pm, ux-* → ux\n ├─ runtime type：subagent / acp 均可分配\n └─ 显式声明：sevo.config.json 中手动指定优先\n └─ 单 Agent 环境 → 所有角色池填入同一 agentId\n\n4. 生成配置文件\n └─ /sevo.config.json\n ├─ complianceMode: \"guide\"\n ├─ roles: { developer: [...], reviewer: [...], product: [...], ux: [...] }\n ├─ stateDir: \"/.sevo/\"\n └─ templates: \"/sevo/templates/\"\n\n5. 健康检查（sevo doctor）\n └─ 插件路径可达？配置完整？Agent 角色覆盖？\n └─ 每个问题附修复建议\n\n6. 输出结果\n └─ 角色分配表 + 合规模式 + 下一步指引\n └─ 提示用户重启 Gateway 使插件生效\n```\n\n### 7.3 与 OpenClaw extensions 的关系\n\nSEVO 插件通过两种路径被 OpenClaw Gateway 加载：\n\n| 加载方式 | 路径 | 触发条件 |\n|---------|------|----------|\n| plugins.load.paths | `openclaw.json` 中显式声明的插件目录 | `sevo init` 自动注册 |\n| extensions 自动扫描 | `~/.openclaw/extensions/sevo/plugin/` | 手动 symlink 或 `npm link` |\n\n推荐方式是 `sevo init` 自动注册到 `plugins.load.paths`，无需手动操作。\n\nGateway 加载插件时调用 `plugin/index.js` 的 `register(api)` 函数，api 对象提供 hook 注册、配置读取、日志等能力。SEVO 插件通过 `bridge.js` 动态加载 `../dist/` 下的核心模块，将 PipelineEngine 的编排语义映射为 OpenClaw 的 hook 事件模型。\n\n加载失败处理：`bridge.js` 加载 `dist/` 失败时（如编译产物缺失），插件降级为 no-op——hook 注册成功但回调函数不执行任何操作，Gateway 不崩溃，用户通过 `sevo doctor` 发现问题。\n\n### 7.4 运行时文件布局\n\nSEVO 运行时在宿主 workspace 下产生以下文件：\n\n```\n/\n├── sevo.config.json # SEVO 全局配置\n├── .sevo/ # SEVO 运行时状态（gitignore）\n│ ├── active-pipelines.json # 活跃 pipeline 实例状态\n│ └── ledger.json # 交付账本\n└── projects// # 项目目录（§3.6 标准结构）\n ├── docs/\n ├── src/\n ├── tests/\n ├── reports/\n └── artifacts/\n```\n\n`.sevo/` 目录包含运行时状态，应加入 `.gitignore`。`active-pipelines.json` 是 PipelineEngine 的持久化状态文件，Gateway 重启后据此恢复中断的 pipeline（AC-13.8）。\n\n## §8 横切关注点\n\n本节描述贯穿 SEVO 所有模块和阶段的横切设计决策。\n\n### 8.1 Fail-Open 设计\n\nSEVO 作为宿主环境的插件运行，核心约束是：插件异常不能拖垮宿主。所有模块遵循 fail-open 原则——出错时降级放行，不阻塞宿主正常工作。\n\n**降级层次**：\n\n| 故障场景 | 降级行为 | 用户感知 |\n|---------|---------|----------|\n| `bridge.js` 加载 `dist/` 失败（编译产物缺失） | hook 注册成功但回调 no-op，Gateway 正常启动 | `sevo doctor` 报告问题，pipeline 不推进 |\n| PipelineEngine 状态文件损坏 | 跳过自动恢复，记录错误日志，等待 `sevo doctor` 修复 | 已有 pipeline 暂停，新 pipeline 可创建 |\n| StageRunner 门禁评估抛异常 | 门禁结果视为 `{ passed: false, issues: [内部错误] }` | pipeline 阻断在当前阶段，不会误放行 |\n| ComplianceRouter 分类失败 | 默认返回 `{ action: pass }`，不干预任务 | 任务正常执行，不进入 SEVO 编排 |\n| 宿主 Adapter hook 执行超时（>5s） | 中断 hook 执行，放行原始操作 | 当次阶段推进指令缺失，下一轮 `before_prompt_build` 补偿 |\n\n**设计原则**：\n- 门禁异常时倾向阻断（fail-closed），防止未经审查的工件流入下游。\n- 非门禁环节异常时倾向放行（fail-open），保证宿主可用性。\n- 所有降级事件写入结构化日志，`sevo doctor` 可检测并报告。\n\n### 8.2 渐进式披露 L0–L3\n\n四级配置分层对应不同用户成熟度，每级能力累加（spec FR-15）。\n\n**L0 安装即用**：\n- `sevo init` 后零配置可用。阶段定义、门禁规则、路由策略、角色执行原则全部内置。\n- 单 Agent 环境自动降级：所有角色池填入同一 agentId，功能完整但质量保证降级。\n- 合规模式默认 `guide`——注入流程引导提示，不阻断执行。\n- 配置文件 `sevo.config.json` 由 `sevo init` 自动生成，用户无需手动创建。\n\n**L1 按需配置**：\n- 用户编辑 `sevo.config.json` 调整：路由级别阈值、门禁严格度（strict/standard/relaxed）、通知渠道、发布目标、合规模式。\n- 修改任一配置不破坏 pipeline 运行——配置校验失败时回退到 L0 默认值并警告。\n- 从 L0 升级到 L1 不需要重新初始化。\n\n**L2 自定义阶段**：\n- 用户可在标准阶段序列中插入自定义阶段（如 Security Audit、Performance Test）。\n- 自定义阶段必须声明输入工件、输出工件和门禁规则，PipelineEngine 按统一状态机驱动。\n- 用户可覆盖默认角色执行原则模板。\n\n**L3 编程控制**：\n- 通过库 API 编程控制 pipeline 行为：创建、查询、门禁覆写、工件读取。\n- 支持自定义 HostAdapter（对接非 OpenClaw 宿主）。\n- 支持自定义阶段执行器（替换默认 Skill 执行）。\n\n**解锁条件**：L0 自动生效；L1 编辑配置文件即解锁；L2 在配置中声明 `customStages` 即解锁；L3 通过 `import { PipelineEngine } from 'sevo'` 编程使用即解锁。\n\n### 8.3 配置 Schema\n\n`sevo.config.json` 是 SEVO 的唯一配置文件，由 `sevo init` 生成，用户按需编辑。完整字段定义：\n\n```jsonc\n{\n // L0 默认值——sevo init 自动填充，用户无需修改\n \"complianceMode\": \"guide\", // \"guide\" | \"auto-route\" | \"off\"\n \"roles\": { // Agent 角色池，sevo init 自动发现填充\n \"coding\": [\"dev-01\"],\n \"review\": [\"audit-01\"],\n \"architecture\": [\"sa-01\"],\n \"pm\": [\"pm-01\"],\n \"ux\": [\"ux-01\"],\n \"general\": [] // 未匹配到专业角色的 Agent 归入通用池\n },\n\n // L1 按需配置\n \"routing\": {\n \"levelThresholds\": {\n \"level1MinLines\": 50, // 改动行数 ≥ 此值进入 Level 1\n \"level2MinLines\": 500, // 改动行数 ≥ 此值进入 Level 2+\n \"level2MinFiles\": 10 // 改动文件数 ≥ 此值进入 Level 2+\n }\n },\n \"gate\": {\n \"strictness\": \"standard\", // \"strict\" | \"standard\" | \"relaxed\"\n \"reviewFixMaxRounds\": 3 // Review Fix Loop 最大轮次\n },\n \"notification\": {\n \"channel\": \"none\", // \"feishu\" | \"slack\" | \"discord\" | \"none\"\n \"webhookUrl\": \"\" // 通知渠道 webhook 地址\n },\n \"publishTarget\": [], // [\"npm\", \"github\", \"clawhub\"]\n\n // L2 自定义阶段\n \"customStages\": [], // 自定义阶段声明数组\n\n // 内部状态（sevo init 写入，用户不应手动修改）\n \"hostType\": \"openclaw\", // \"openclaw\" | \"standalone\" | \"other\"\n \"pluginPath\": \"\", // 插件绝对路径（OpenClaw 环境）\n \"stateDir\": \".sevo/\", // 运行时状态目录\n \"version\": \"1.0.0\" // 配置 schema 版本\n}\n```\n\n**校验规则**：\n- `sevo doctor` 对配置做完整性校验，缺失字段用 L0 默认值补全并警告。\n- `complianceMode` 只接受三个枚举值，非法值回退到 `guide`。\n- `roles` 中引用的 agentId 必须在宿主 `agents.list` 中存在（OpenClaw 环境），不存在时 doctor 报 warning。\n- `publishTarget` 中的值必须是 `npm`、`github`、`clawhub` 之一。\n\n### 8.4 测试策略\n\nSEVO 的测试分三层，覆盖从单元到端到端的完整验证链路。\n\n**单元测试**：\n- 覆盖核心模块的纯逻辑：ComplianceRouter.classifyLevel()、GateEngine 门禁评估、PipelineEngine 状态机流转、RoleKnowledgeInjector 模板映射。\n- 测试框架：项目标准测试框架（随技术选型确定）。\n- 不依赖文件系统或宿主环境，全部通过接口 mock 隔离。\n- 覆盖目标：核心状态机路径 100%，门禁判定逻辑 100%。\n\n**集成测试**：\n- 验证模块间协作：CLI → PipelineEngine → StageRunner → GateEngine 的完整调用链。\n- 使用内存文件系统或临时目录模拟工件读写。\n- 验证 `sevo init` 在 OpenClaw 环境和 standalone 环境下的行为差异。\n- 验证 pipeline 创建 → 阶段推进 → 门禁评估 → 状态持久化的完整流程。\n- 验证并行阶段（FR-02a/b/c + FR-03；FR-06c + FR-06d）的正确编排。\n\n**端到端验证**：\n- `sevo demo --dry-run`：无 LLM 环境下用 mock 数据跑通完整 pipeline 阶段流转，验证安装正确性和工件结构。\n- `sevo demo`：有 LLM 环境下用内置示例项目跑通真实 Level 0 pipeline。\n- 陌生人走查脚本（`scripts/npm-stranger-verify.sh`）：在干净 `/tmp/` 目录中模拟无 SEVO 环境，从 `npm install` 开始验证开箱即用。\n- Gateway 重启恢复测试：创建 active pipeline → 模拟 Gateway 重启 → 验证 pipeline 在 60s 内自动恢复推进（AC-13.8）。\n\n### 8.5 安全与权限\n\n**文件系统访问范围**：\n- SEVO 的读写范围限定在三个区域：`sevo.config.json`（配置）、`.sevo/`（运行时状态）、`projects/`（项目工件）。\n- 插件注册时写入宿主 `openclaw.json`（仅 `sevo init` 阶段，运行时只读）。\n- 角色 SOUL.md 注入写入 `roles//agent/SOUL.md`（仅 `sevo init` 阶段）。\n- 运行时不访问上述范围之外的文件系统路径。\n\n**配置敏感字段处理**：\n- `sevo.config.json` 不存储任何密钥、token 或凭据。\n- 通知渠道的 webhook URL 是唯一的半敏感字段——`sevo doctor` 输出时脱敏显示（只显示域名部分）。\n- 发布凭据（npm token、GitHub token）由宿主环境管理，SEVO 通过环境变量或宿主 Adapter 间接获取，不写入自身配置。\n\n**审计独立性**（NFR-5.13）：\n- Review 阶段执行者必须与 Implement 阶段执行者不同（角色池级别隔离）。\n- 单 Agent 降级模式下，同一 Agent 执行所有阶段，但 Review 阶段的执行原则仍然注入审计视角的 prompt，确保审计思维存在。\n- Ledger 记录每个阶段的实际执行者 agentId，支持事后追溯。\n\n**商用化门禁敏感信息扫描**（FR-08a）：\n- Deploy 前的 Commercialization Gate 自动扫描待发布文件中的敏感内容：`.env` 文件、API key 模式匹配、密钥文件、内部配置路径。\n- 发现敏感内容时阻断发布并报告具体文件和行号。\n- 扫描规则可通过 L2 配置扩展。\n\nFile v1.13.1:docs/architecture.md\n\n# SEVO — arc42 架构文档\n\nClaude Code（OpenClaw ACP Agent）| 2026-04-24\n\n---\n\n## 目录\n\n1. [引言与目标](#1-引言与目标)\n2. [约束](#2-约束)\n3. [上下文与边界](#3-上下文与边界)\n4. [解决方案策略](#4-解决方案策略)\n5. [构建块视图](#5-构建块视图)\n6. [运行时视图](#6-运行时视图)\n7. [部署视图](#7-部署视图)\n8. [横切关注点](#8-横切关注点)\n9. [架构决策](#9-架构决策)\n10. [质量需求](#10-质量需求)\n11. [风险与技术债务](#11-风险与技术债务)\n12. [术语表](#12-术语表)\n\n---\n\n## 1. 引言与目标\n\n### 1.1 需求概述\n\nSEVO（Spec-Execute-Verify-Operate）是 Agent 自动研发流水线。它把散落在 AGENTS.md 的流程规则固化为代码级状态机，保障全研发生命周期产出质量——从需求定义、架构设计到验证发布全流程自动化。\n\n当前 AI Coding 工具只覆盖\"写代码\"环节。SEVO 的定位是把 Specify → Execute → Verify → Operate 四个阶段串成可编程、可审计、可自动推进的流水线，让 vibe coding 用户获得完整的研发质量保障。\n\n### 1.2 质量目标\n\n| 优先级 | 质量属性 | 目标 |\n|--------|----------|------|\n| 1 | 可控性 | 每个阶段有明确的门禁（Gate），不满足条件不放行 |\n| 2 | 可审计性 | 全流程事件追踪，Ledger 记录每次流水线执行的完整证据链 |\n| 3 | 通用性 | 核心状态机不绑死 OpenClaw，通过 Host Adapter 接入任意 Agent 宿主 |\n| 4 | 可靠性 | 插件层 fail-open，核心引擎 fail-safe；单模块故障不拖垮整条流水线 |\n| 5 | 可扩展性 | 阶段可配置（跳过/新增），门禁规则可插拔，Agent 映射可覆盖 |\n\n### 1.3 利益相关者\n\n| 角色 | 关注点 |\n|------|--------|\n| 用户（产品负责人） | 研发质量可见、进度透明、不需要手动推进流水线 |\n| OpenClaw 主会话 | 通过 hook 接收流水线事件，自动派发下一阶段任务 |\n| 子 Agent（编码/审计/架构/PM） | 接收阶段任务 prompt，产出 artifact，结果回流流水线 |\n| KIVO（知识引擎） | 消费 Ledger 产出的结构化研发记录，沉淀为可复用知识 |\n| AEO（效果运营） | 监控流水线执行指标，发现效果漂移 |\n\n---\n\n## 2. 约束\n\n### 2.1 技术约束\n\n| 约束 | 原因 |\n|------|------|\n| TypeScript 核心 + JS 插件 | 核心库（projects/sevo/src/）用 TS 编译为 JS；插件层（extensions/sevo-pipeline/）直接 JS，与 OpenClaw 插件体系一致 |\n| 核心不绑死单一宿主，但主动复用宿主高价值能力 | SOUL.md 核心设计原则：通用优先 + Host Adapter 模式 |\n| Stage-Bound Design | 能力/规范绑定流程阶段，不绑定特定 Agent 身份（AGENTS.md §核心设计原则） |\n| 单文件状态持久化（state.json） | 单 writer 模型，避免并发写冲突；事件日志 append-only（events.jsonl） |\n| 插件层 fail-open | 所有 hook handler 包裹 try-catch，错误记录但不阻断宿主调度 |\n\n### 2.2 组织约束\n\n| 约束 | 原因 |\n|------|------|\n| SEVO 流水线强制 | 新建模块、跨域改动、>500 行或 >10 文件、数据模型变更必须走完整 SEVO 流水线 |\n| 开发与审计分离 | 编码 Agent 不做自审，审计由独立 Agent 执行 |\n| 长文档分段写作 | >300 行文档必须分段派发，降低单次写入失败风险 |\n| 研发流程改进双写 | 每条改进同时落地到 AGENTS.md（L6 临时兜底）和 SEVO 产品层（L1/L2 永久固化） |\n\n### 2.3 惯例约束\n\n| 约束 | 原因 |\n|------|------|\n| 意图路由必须走 LLM | SOUL.md 术语纪律：禁止用关键词匹配实现意图理解 |\n| 文件产出强制 | 任务要求写文件时必须实际写入磁盘，只在回复中输出 = 任务失败 |\n| AC 逐条覆盖 | 编码任务必须逐条对照验收标准，审计只做质量把关不做需求补漏 |\n\n---\n\n## 3. 上下文与边界\n\n### 3.1 业务上下文\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│ 用户（产品负责人） │\n│ 提出需求 / 做重大决策 / 最终验收 │\n└──────────────────────┬───────────────────────────────────────┘\n │ 需求描述\n ▼\n┌──────────────────────────────────────────────────────────────┐\n│ OpenClaw 主会话（调度层） │\n│ 接收用户消息 → 判断意图 → 触发 SEVO → 按流水线自动推进 │\n└──────┬──────────────┬──────────────┬─────────────────────────┘\n │ │ │\n ▼ ▼ ▼\n┌────────────┐ ┌────────────┐ ┌────────────┐\n│ SEVO 核心 │ │ KIVO │ │ AEO │\n│ 研发流水线 │ │ 知识引擎 │ │ 效果运营 │\n└──────┬─────┘ └────────────┘ └────────────┘\n │\n │ 派发阶段任务 / 收集 artifact / 门禁评估\n ▼\n┌──────────────────────────────────────────────────────────────┐\n│ Agent 执行层 │\n│ PM(pm-01) | 架构师(sa-01) | 编码(cc/free-code/dev-*) │\n│ 审计(audit-01/02) | UX(ux-01) │\n└──────────────────────────────────────────────────────────────┘\n```\n\n### 3.2 技术上下文\n\n| 外部系统 | 交互方式 | 协议 |\n|----------|----------|------|\n| OpenClaw Gateway | 插件 hook（subagent_ended / before_prompt_build / before_tool_call） | JS Plugin API |\n| OpenClaw sessions_spawn | 通过 Host Adapter 派发子 Agent 任务 | Gateway RPC |\n| 文件系统 | state.json / events.jsonl / artifact 文件 | POSIX FS |\n| KIVO | Ledger 产出 → KIVO 知识入库（未来集成） | API / 文件 |\n| AEO | 流水线指标 → AEO 监控（未来集成） | API / 文件 |\n\n### 3.3 系统边界（明确不做）\n\n- 不做 Agent 调度（调度是 OpenClaw 主会话的职责，SEVO 只定义\"下一步该做什么\"）\n- 不做代码编辑/编译/测试执行（这些是 Agent 执行层的能力）\n- 不做用户认证/权限管理\n- 不做实时通信（通知通过 Host Adapter 委托宿主完成）\n- 不做知识管理（KIVO 的职责）\n\n---\n\n## 4. 解决方案策略\n\n| 策略 | 决策 | 理由 |\n|------|------|------|\n| 状态机驱动 | 12 阶段有限状态机，每个阶段有明确的状态转换规则 | 把 AGENTS.md 的文字规则变成可编程、可验证的状态约束 |\n| 三级路由 | L0（跳过）/ L1（轻量）/ L2+（完整），按任务规模自动分级 | 小改动不走完整流水线，大改动强制全流程 |\n| 规模路由 | Tier 1（直接执行）/ Tier 2（轻量含审计）/ Tier 3（完整 15 阶段） | 进一步细化路由粒度，琐碎操作不创建流水线 |\n| Gate 规则可插拔 | GateRule SPI，内置 FileExists/TypeCheck/TestPass/MinCoverage，可扩展 | 不同阶段的质量标准不同，规则需要灵活组合 |\n| Host Adapter 模式 | 核心通用 + OpenClawAdapter / StandaloneAdapter | 核心不绑死 OpenClaw，但主动复用其 hook/session/notification 能力 |\n| Spec Review 后并行分叉 | spec-review-gate 通过后，test-case-authoring 和 contract 并行启动 | 缩短流水线总耗时，两个活动无依赖 |\n| Clarification 协调 | 阶段执行中发现歧义 → 阻塞当前阶段 → 收集澄清 → 恢复 | 避免带着歧义继续执行导致返工 |\n| Ledger 审计账本 | 流水线完成后收集全部 artifact + stage record，写入不可变 Ledger | 提供完整的研发过程证据链 |\n| 事件溯源 | events.jsonl append-only，state.json 单 writer | 支持事后审计和状态重建 |\n\n---\n\n## 5. 构建块视图\n\n### 5.1 Level 1 — 系统分解\n\nSEVO 由两层组成：核心库（通用）和插件层（OpenClaw 特化）。\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ SEVO 系统 │\n│ │\n│ ┌─────────────────────────────────────────────────────────┐ │\n│ │ 核心库 (projects/sevo/src/) │ │\n│ │ │ │\n│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │ │\n│ │ │ Router │ │ Pipeline │ │ Gate │ │ Ledger │ │ │\n│ │ │ 路由器 │ │ Engine │ │ Engine │ │ Engine │ │ │\n│ │ └──────────┘ └──────────┘ └──────────┘ └─────────┘ │ │\n│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │\n│ │ │Orchestr- │ │ Context │ │Clarific- │ │ │\n│ │ │ ator │ │ Injector │ │ ation │ │ │\n│ │ └──────────┘ └──────────┘ └──────────┘ │ │\n│ │ ┌──────────────────────────────────────────┐ │ │\n│ │ │ Adapter Layer │ │ │\n│ │ │ OpenClawAdapter | StandaloneAdapter │ │ │\n│ │ └──────────────────────────────────────────┘ │ │\n│ └─────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─────────────────────────────────────────────────────────┐ │\n│ │ 插件层 (extensions/sevo-pipeline/) │ │\n│ │ │ │\n│ │ index.js ── bridge.js ── task-mapper.js ── methodology.js │ │\n│ │ label-protocol.js │ │\n│ └─────────────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n### 5.2 Level 2 — 核心库模块职责\n\n#### Router（路由器）\n\n位置：`src/router/`\n\n职责：接收任务描述，根据触发规则判定流水线级别（L0/L1/L2+），输出所需阶段列表和跳过阶段列表。\n\n核心文件：\n- `stage-router.ts` — 路由入口，组合 level-classifier 和 stage-graph\n- `level-classifier.ts` — 根据 TaskScope 判定 TaskLevel\n- `stage-graph.ts` — 定义阶段依赖图，根据 level 裁剪阶段列表\n- `stage-context.ts` — 阶段上下文信息封装\n- `router.ts` — 对外暴露的 `route()` 函数\n\n关键类型：\n```typescript\ntype TaskLevel = 'L0' | 'L1' | 'L2+';\ntype TriggerRule = 'new-module' | 'cross-domain' | 'large-change'\n | 'data-model-change' | 'governance-change'\n | 'release-target-change' | 'user-explicit';\n\ninterface RoutingResult {\n taskId: string;\n level: TaskLevel;\n requiredStages: StageId[];\n skippedStages: SkippedStage[];\n matchedRules: TriggerRule[];\n}\n```\n\n触发规则（命中任一即 L2+ 完整流水线）：\n- 从零新建模块（new-module）\n- 跨域改动（cross-domain，涉及 2+ 域）\n- 大型变更（large-change，>500 行或 >10 文件）\n- 数据模型变更（data-model-change）\n- 治理规则变更（governance-change）\n- 发布目标变更（release-target-change）\n- 用户显式要求（user-explicit）\n\n规模路由（FR-D08）：\n\nRouter 在收到需求后先评估规模，自动选择执行档位：\n\n| 档位 | 适用场景 | 阶段集 | 项目目录 |\n|------|----------|--------|----------|\n| Tier 1（直接执行） | 改配置、查状态、单文件修复 | 不创建流水线 | 不创建 |\n| Tier 2（轻量流水线） | 小功能、脚本、局部改动 | spec → implement → review → verify → ledger | 在现有目录中工作 |\n| Tier 3（完整流水线） | 新产品、新模块、跨域改动 | 完整 15 阶段 | projects/\\/ |\n\nTier 2 必须包含 review（审计），保障最低质量门禁。用户可通过 `sevo:create my-tool --tier 2` 强制指定档位。\n\n#### Pipeline Engine（流水线引擎）\n\n位置：`src/pipeline/`\n\n职责：管理流水线实例的创建、阶段状态转换、并行分叉、持久化。这是 SEVO 的核心状态机。\n\n核心文件：\n- `stage-machine.ts` — 阶段状态转换规则（有限状态机）\n- `parallel-branch.ts` — Spec Review 通过后的并行分叉逻辑\n- `pipeline-create.ts` — 流水线实例创建（FR-12）\n- `directory-init.ts` — 项目目录结构初始化\n- `instance-id.ts` — 实例 ID 生成\n\n状态转换规则：\n```\npending → active | skipped\nactive → passed | failed | blocked | clarification-blocked\nblocked → active (解除阻塞)\nclarification-blocked → active (澄清完成)\nfailed → active (修复后重试)\npassed → (终态)\nskipped → (终态)\n```\n\n12 个阶段的完整序列：\n```\nspec → spec-review-gate → [test-case-authoring ∥ contract] →\ncontract-review-gate → implement → review → regression →\npublish-generalization-gate → deploy → verify → ledger\n```\n\n其中 `∥` 表示 spec-review-gate 通过后 test-case-authoring 和 contract 并行启动。\n\n#### Gate Engine（门禁引擎）\n\n位置：`src/gate/`\n\n职责：评估阶段门禁，聚合多维度审查结论，输出 passed/conditional/rejected 裁决。\n\n核心文件：\n- `gate-engine.ts` — 门禁评估入口\n- `gate-rule.ts` — GateRule SPI 接口定义\n- `built-in-rules.ts` — 内置规则：FileExistsRule / TypeCheckRule / TestPassRule / MinCoverageRule\n- `verdict-aggregator.ts` — 多 ReviewBundle 聚合为最终裁决\n- `review-role-assigner.ts` — 根据阶段确定所需审查角色\n\n关键类型：\n```typescript\ntype GateConclusion = 'passed' | 'conditional' | 'rejected';\n\ninterface GateVerdict {\n gateId: string;\n conclusion: GateConclusion;\n blockers: { item: string; owner: string }[];\n reviewBundles: ReviewBundle[];\n}\n```\n\n门禁裁决语义：\n- `passed` — 放行，自动推进到下一阶段\n- `conditional` — 有条件通过，列出必须解决的问题，修复后重新评估\n- `rejected` — 不通过，回退到上一阶段重做\n\n#### Ledger Engine（审计账本）\n\n位置：`src/ledger/`\n\n职责：流水线完成后收集全部 artifact 和 stage record，写入不可变的 Ledger 条目，提供查询接口。\n\n核心文件：\n- `ledger-engine.ts` — Ledger 读写入口\n- `artifact-collector.ts` — 从各阶段收集 artifact 引用\n\n关键类型：\n```typescript\ninterface LedgerEntry {\n pipelineId: string;\n version: string;\n createdAt: string;\n scope: string;\n stages: StageRecord[];\n conclusion: 'delivered' | 'aborted';\n evidence: ArtifactRef[];\n clarificationRefs?: ArtifactRef[];\n}\n```\n\n#### Task Orchestrator（任务编排器）\n\n位置：`src/orchestrator/`\n\n职责：组合 Router + Pipeline Engine + Gate Engine，提供高层 API：startPipeline → evaluateAndAdvance → getPipelineStatus。\n\n核心文件：\n- `task-orchestrator.ts` — 编排入口，串联路由→创建→推进→门禁\n- `pipeline-run.ts` — 单次流水线运行的状态封装\n- `orchestrator-events.ts` — 编排器事件定义（PipelineStarted / StageEntered / GateEvaluated / StageAdvanced / PipelineCompleted / PipelineFailed）\n\n#### Context Injector（上下文注入器）\n\n位置：`src/context-injection/`\n\n职责：根据当前阶段，向 Agent 任务 prompt 注入流水线上下文（前序 artifact 路径、阶段要求、质量标准）。\n\n#### Clarification Coordinator（澄清协调器）\n\n位置：`src/clarification/`\n\n职责：阶段执行中发现歧义时，阻塞当前阶段，收集澄清问题，协调解决后恢复执行。\n\n核心文件：\n- `clarification-coordinator.ts` — 澄清流程协调\n- `clarification-record.ts` — 澄清记录持久化\n- `ambiguity-detector.ts` — 歧义检测规则\n- `clarification-manager.ts` — 澄清生命周期管理\n\n#### Adapter Layer（适配层）\n\n位置：`src/adapter/`\n\n职责：将核心库的抽象操作（派发任务、收集 artifact、发送通知）映射到具体宿主环境。\n\n```typescript\ninterface SevoHostAdapter {\n dispatchTask(stage: StageId, payload: TaskPayload): Promise;\n collectArtifacts(taskId: string): Promise;\n notifyGateResult(stage: StageId, verdict: GateVerdict): void;\n getProjectConfig(): ProjectConfig;\n analyzeRequirements?(input: RequirementAnalysisRequest): Promise;\n}\n```\n\n两个实现：\n- `OpenClawAdapter` — 通过 OpenClaw Gateway Plugin API 派发任务、收集 artifact、发送飞书通知\n- `StandaloneAdapter` — 独立运行模式，用于测试和非 OpenClaw 环境\n\n#### Stage 实现层\n\n位置：`src/stages/`\n\n职责：每个阶段的具体行为定义（输入/输出类型、执行逻辑、验收标准）。\n\n已实现的阶段：\n\n| 阶段 | 文件 | 职责 |\n|------|------|------|\n| spec | spec-stage.ts | 需求规格编写，输出 product-requirements.md |\n| contract | contract-stage.ts | 架构设计，输出 arc42 + ADR |\n| test-case | test-case-stage.ts | 测试用例编写，基于冻结 spec |\n| implement | implement-stage.ts | 编码实现，按 spec + arc42 执行 |\n| debugging | debugging-stage.ts | 调试阶段（review 发现问题后的修复循环） |\n| review | review-stage.ts | 质量审计（代码质量/安全/spec 合规） |\n| review-fix-loop | review-fix-loop.ts | 审计→修复→复验自动闭环 |\n| regression | regression-stage.ts | 回归测试执行 |\n| deploy | deploy-stage.ts | 部署执行 |\n| verify | verify-stage.ts | 部署后验证（smoke test） |\n| ledger | ledger-stage.ts | Ledger 记录写入 |\n| publish-generalization-gate | publish-generalization-gate.ts | 发布前通用化检查（FR-08a） |\n\n#### Gate 实现层\n\n位置：`src/gates/`\n\n职责：具体门禁的评估逻辑。\n\n| 门禁 | 文件 | 评估维度 |\n|------|------|----------|\n| spec-review-gate | spec-review-gate.ts | 需求完整度、FR 边界清晰度、AC 可测试性 |\n| contract-review-gate | contract-review-gate.ts | spec-架构对齐、ADR 完整性、部署可行性 |\n\n### 5.3 Level 2 — 插件层模块职责\n\n插件层是 SEVO 核心库在 OpenClaw 宿主中的运行时桥梁。\n\n#### index.js（插件入口）\n\n位置：`extensions/sevo-pipeline/index.js`（3143 行）\n\n职责：注册 3 个 OpenClaw hook，实现流水线自动推进。\n\nHook 注册：\n\n| Hook | 优先级 | 触发时机 | 行为 |\n|------|--------|----------|------|\n| subagent_ended | 200 | 子 Agent 任务完成 | 解析 SEVO label → 调用 PipelineEngine.advance() → 队列下一阶段 |\n| before_prompt_build | 850 | 主会话构建 prompt 前 | 消费 pendingAdvances 队列 → 注入下一阶段任务指令到主会话 |\n| before_prompt_build | 100 | 用户消息到达时 | 命令路由：解析 sevo:* 命令 → 执行对应 handler → 结果放入 pendingNotices |\n| before_tool_call | 800 | 工具调用前 | 路由 sessions_spawn → 注入 SEVO label 到子 Agent 参数 |\n\n运行模式：\n- 启动时检查 SEVO dist/ 是否存在\n- 存在 → active 模式，全部 hook 生效\n- 不存在 → degraded 模式，大部分 hook 变为 no-op\n- 降级模式下仍可用的命令：sevo:doctor、sevo:version、sevo:status、sevo:list（只读状态文件）\n\n#### 命令系统\n\n插件通过 `before_prompt_build`（priority 100）hook 路由用户消息中的 `sevo:*` 命令，路由到对应 handler。命令解析使用正则匹配，handler 执行结果放入 `pendingNotices` 队列，由 priority 850 的 hook 注入主会话 prompt。\n\n命令清单：\n\n| 命令 | 正则 | Handler | 降级可用 | 功能 |\n|------|------|---------|----------|------|\n| `sevo:create [\"title\"]` | `SEVO_CREATE_RE` | 创建完整流水线 | ❌ | 路由评估 → 创建 pipeline → 初始化项目目录 → 激活首阶段 |\n| `sevo:quickstart` | `SEVO_QUICKSTART_RE` | 创建 7 阶段精简流水线 | ❌ | 内置 hello-sevo 示例项目，跳过三方会审 |\n| `sevo:status [id]` | `SEVO_STATUS_RE` | 查询流水线状态 | ✅ | 无参数列出所有活跃流水线，有参数显示单个详情 |\n| `sevo:list` | `SEVO_LIST_RE` | 列出历史流水线 | ✅ | 读取 active-pipelines.json |\n| `sevo:doctor` | `SEVO_DOCTOR_RE` | 自检 | ✅ | 检查插件注册、hook、Agent 池、路径、写权限 |\n| `sevo:version` | `SEVO_VERSION_RE` | 版本查询 | ✅ | 输出 SEVO_VERSION 常量 |\n| `sevo:diagnose ` | `SEVO_DIAGNOSE_RE` | 深度诊断 | ❌ | 分析失败流水线的根因，输出结构化诊断报告 |\n| `sevo:retry [stage]` | `SEVO_RETRY_RE` | 重试失败阶段 | ❌ | 重新激活 failed 阶段，attempt 计数递增 |\n| `sevo:pause ` | `SEVO_PAUSE_RE` | 暂停流水线 | ❌ | 设置 info.status='paused'，记录 pausedAt |\n| `sevo:skip ` | `SEVO_SKIP_RE` | 跳过阶段 | ❌ | 标记阶段 skipped，自动激活下一阶段 |\n| `sevo:resume ` | `SEVO_RESUME_RE` | 恢复流水线 | ❌ | 清除 paused 状态，从暂停点继续 |\n\n命令路由流程：\n```\n用户消息 → before_prompt_build(priority 100)\n → extractUserMessage(evt)\n → 按优先级匹配正则（doctor/version 最先，create 最后）\n → 匹配成功 → 调用 handler → 结果 push 到 pendingNotices\n → before_prompt_build(priority 850) 消费 pendingNotices → 注入主会话 prompt\n```\n\n#### bridge.js（桥接层）\n\n位置：`extensions/sevo-pipeline/bridge.js`\n\n职责：懒加载 SEVO TypeScript 编译产物（dist/），提供 PipelineEngine / LedgerEngine / route 的运行时访问。\n\n特性：\n- 模块级缓存 + TTL 过期（默认 30s）\n- 文件 mtime 变化检测，自动重新加载\n- 单模块故障不影响其他模块（per-module failure isolation）\n- 加载失败后 backoff，避免频繁重试\n\n#### task-mapper.js（任务映射器）\n\n位置：`extensions/sevo-pipeline/task-mapper.js`\n\n职责：将 StageId 映射为具体的 Agent 任务描述（prompt），包含前序 artifact 引用和阶段要求。\n\n默认阶段→Agent 映射：\n\n| 阶段 | 梯队 | 默认 Agent | 超时 |\n|------|------|-----------|------|\n| spec | PM | pm-01 | 1800s |\n| spec-review-gate | 架构 | sa-01 | 1200s |\n| test-case-authoring | 审计 | audit-01 | 1200s |\n| contract | 架构 | sa-01 | 3600s |\n| contract-review-gate | 审计 | audit-01 | 1200s |\n| implement | T1 | (auto) | 1200s |\n| review | 审计 | audit-01 | 1200s |\n| regression | T1 | (auto) | 1200s |\n| publish-generalization-gate | 架构 | sa-01 | 1200s |\n| deploy | T1 | (auto) | 600s |\n| verify | 审计 | audit-01 | 600s |\n| ledger | T4 | dev-01 | 600s |\n\n映射可通过 `state/config.json` 或插件配置覆盖（Stage-Bound Design：绑定阶段不绑定 Agent 身份）。\n\n#### methodology.js（方法论模块）\n\n位置：`extensions/sevo-pipeline/methodology.js`\n\n职责：为每个流水线阶段提供方法论指导 prompt，由 task-mapper.js 在构建 task prompt 时 spread 注入。\n\n导出函数（9 个，对应 9 类阶段方法论）：\n\n| 函数 | 注入阶段 | 方法论要点 |\n|------|----------|-----------|\n| specMethodology() | spec | 批判性思维、第一性原理、概念架构隔离、Phase 隔离（禁止技术选型） |\n| contractMethodology() | contract | arc42 模板、ADR 纪律、Gate Check 7 项 |\n| specReviewGateMethodology() | spec-review-gate | 7 维发散审查、交叉审计、三档结论 + 用户体验流完整性（第 9 维度） |\n| contractReviewGateMethodology() | contract-review-gate | 三方独立视角、7 维发散审查、综合裁决 |\n| reviewMethodology() | review | OWASP Top 10:2025、git diff-aware、置信度阈值 |\n| implementMethodology() | implement | 最小改动、最简实现、目标驱动执行 |\n| testCaseAuthoringMethodology() | test-case-authoring | AC 覆盖规则、边界值、负面路径、优先级分级 |\n| smokeTestMethodology() | smoke-test | 端到端用户视角、独立验证者、证据附带 |\n| getUserJourneyTemplate() | spec + ux-acceptance | 6 阶段用户体验旅程模板 |\n\n`getUserJourneyTemplate()` 返回结构化用户旅程模板，覆盖 6 个阶段：\n\n| 阶段 ID | 名称 | 审查问题示例 |\n|---------|------|-------------|\n| discover | 发现与获取 | 用户从哪里找到产品？获取方式是什么？ |\n| install | 安装与配置 | 能一条命令完成吗？零配置能跑吗？ |\n| first-use | 首次使用 | 5 分钟内能看到第一个成功结果吗？ |\n| core-flow | 核心流程 | 主要功能的完整使用流程是什么？ |\n| error-recovery | 错误恢复 | 错误信息能指导用户修复吗？ |\n| upgrade | 升级与维护 | 升级会不会破坏已有配置？ |\n\n注入点：spec 阶段要求 PM agent 在 spec 中画出完整用户旅程；spec-review-gate 将\"用户体验流完整性\"作为硬性审查维度（缺失 = P0 阻断）；ux-acceptance 阶段要求 UX agent 按流程逐步验收。\n\n注入机制：task-mapper.js 的 `STAGE_PROMPTS` 中通过 `...specMethodology()` 等 spread 语法将方法论 string[] 追加到阶段 prompt 末尾。方法论内容集中管理，阶段 prompt 与方法论解耦。\n\n#### label-protocol.js（标签协议）\n\n位置：`extensions/sevo-pipeline/label-protocol.js`\n\n职责：编码/解码 SEVO 流水线信息到 session label。\n\n格式：`sevo::[:]`\n\n用途：子 Agent session 通过 label 携带流水线上下文，completion event 到达时据此路由回正确的流水线实例。\n\n---\n\n## 6. 运行时视图\n\n### 6.1 场景一：新建流水线（Happy Path）\n\n```\n用户 OpenClaw 主会话 SEVO 插件层 SEVO 核心\n │ │ │ │\n │ \"新建 XX 模块\" │ │ │\n │──────────────────────>│ │ │\n │ │ 判断意图 → 触发 SEVO │ │\n │ │─────────────────────────>│ │\n │ │ │ bridge.getRoute() │\n │ │ │─────────────────────>│\n │ │ │ │ route(taskScope)\n │ │ │ │ → RoutingResult\n │ │ │ │ {level: L2+,\n │ │ │ │ requiredStages: [...]}\n │ │ │<─────────────────────│\n │ │ │ getPipelineEngine() │\n │ │ │─────────────────────>│\n │ │ │ │ engine.create(routing)\n │ │ │ │ → atomicWrite(state.json)\n │ │ │ │ → appendEvent(pipeline_created)\n │ │ │ │ → activateNext() → spec=active\n │ │ │<─────────────────────│\n │ │ │ queue pendingAdvance│\n │ │ │ (spec, pm-01) │\n │ │ before_prompt_build │ │\n │ │<─────────────────────────│ │\n │ │ 注入 spec 阶段任务指令 │ │\n │ │ sessions_spawn(pm-01) │ │\n │ │─────────────────────────>│ │\n │ │ │ before_tool_call │\n │ │ │ 注入 sevo label │\n │ │ │ → sevo::spec:1 │\n │ │<─────────────────────────│ │\n │ │ 派发 pm-01 子 Agent │ │\n```\n\n关键步骤：\n1. Router 根据 TaskScope 判定 level（L0/L1/L2+），输出 requiredStages 和 skippedStages\n2. PipelineEngine.create() 原子写入 state.json，激活第一个阶段（spec）\n3. 插件层将下一阶段任务放入 pendingAdvances 队列\n4. before_prompt_build hook 消费队列，注入任务指令到主会话\n5. before_tool_call hook 在 sessions_spawn 时注入 SEVO label\n\n### 6.2 场景二：阶段推进（Stage Advance）\n\n```\npm-01 子 Agent OpenClaw Gateway SEVO 插件层 SEVO 核心\n │ │ │ │\n │ 任务完成 (spec 产出) │ │ │\n │─────────────────────────>│ │ │\n │ │ subagent_ended event │ │\n │ │─────────────────────────>│ │\n │ │ │ decode(label) │\n │ │ │ → pipelineId, │\n │ │ │ stageId=spec │\n │ │ │ engine.advance() │\n │ │ │─────────────────────>│\n │ │ │ │ record.status=passed\n │ │ │ │ activateNext()\n │ │ │ │ → spec-review-gate=active\n │ │ │<─────────────────────│\n │ │ │ queue pendingAdvance│\n │ │ │ (spec-review-gate) │\n │ │ before_prompt_build │ │\n │ │<─────────────────────────│ │\n │ │ 注入下一阶段任务 │ │\n```\n\n推进逻辑：\n1. subagent_ended hook 解码 label，识别流水线和阶段\n2. 根据 evt.status 判定 outcome（passed/failed）\n3. PipelineEngine.advance() 更新状态 + 激活后续阶段\n4. 插件层队列化下一阶段任务，等待 before_prompt_build 注入\n\n### 6.3 场景三：Gate 失败回退\n\n```\naudit-01 (review) SEVO 插件层 SEVO 核心\n │ │ │\n │ spec-review-gate │ │\n │ 结论: rejected │ │\n │─────────────────────────>│ │\n │ │ engine.advance() │\n │ │─────────────────────>│\n │ │ │ outcome=failed\n │ │ │ record.status=failed\n │ │ │ appendEvent(stage_failed)\n │ │ │ 不激活后续阶段\n │ │<─────────────────────│\n │ │ │\n │ │ pendingNotices += │\n │ │ \"[SEVO Rework Needed]│\n │ │ stage spec-review- │\n │ │ gate failed\" │\n │ │ │\n │ │ 主会话收到通知 → │\n │ │ 重新派发 spec 阶段 │\n```\n\n回退语义：\n- Gate rejected → 当前 gate 阶段标记 failed，不激活后续阶段\n- 插件层发出 rework notice，主会话据此重新派发前序阶段\n- 修复后可通过 engine.activate() 重新激活 failed 阶段（failed → active 是合法转换）\n- 重试时 attempt 计数递增，label 编码为 `sevo:::`\n\n### 6.4 场景四：并行分叉与合并\n\n```\nspec-review-gate passed\n │\n ├──────────────────────┐\n ▼ ▼\n test-case-authoring contract\n (audit-01) (sa-01)\n │ │\n │ ▼\n │ contract-review-gate\n │ (audit-01)\n │ │\n └──────────┬───────────┘\n ▼\n implement\n (需要两条分支都 passed)\n```\n\n并行规则（parallel-branch.ts）：\n- spec-review-gate passed → 同时激活 contract 和 test-case-authoring\n- contract-review-gate 只等 contract（不等 test-case-authoring）\n- implement 需要 contract-review-gate passed；如果 test-case-authoring 未完成，implement 被 shouldBlockImplement() 阻塞\n- 两条分支完全独立执行，由不同 Agent 并行处理\n\n### 6.5 场景五：澄清阻塞与恢复\n\n```\n执行中 Agent SEVO 核心 用户/主会话\n │ │ │\n │ 发现歧义 │ │\n │─────────────────────────>│ │\n │ │ scanClarifications() │\n │ │ → blocking=true │\n │ │ record.status= │\n │ │ clarification-blocked │\n │ │ appendEvent( │\n │ │ clarification_opened) │\n │ │ │\n │ │ adapter.requestClarification│\n │ │─────────────────────────────>│\n │ │ │ 用户回答\n │ │ onClarificationResponse │\n │ │<─────────────────────────────│\n │ │ resolve() → │\n │ │ record.status=active │\n │ │ appendEvent( │\n │ │ clarification_settled) │\n │ │ │\n │ 恢复执行 │ │\n │<─────────────────────────│ │\n```\n\n澄清协调器（ClarificationCoordinator）管理完整生命周期：open → resolved → settled。BlockingLevel 决定是否阻塞当前阶段。\n\n### 6.6 场景六：命令路由处理\n\n```\n用户 OpenClaw Gateway SEVO 插件层\n │ │ │\n │ \"sevo:pause sevo-abc\"│ │\n │──────────────────────>│ │\n │ │ before_prompt_build │\n │ │ (priority 100) │\n │ │─────────────────────────>│\n │ │ │ extractUserMessage(evt)\n │ │ │ SEVO_PAUSE_RE.test() match\n │ │ │ handlePauseCommand()\n │ │ │ info.status = 'paused'\n │ │ │ saveActivePipelines()\n │ │ │ appendEvent()\n │ │ │ pendingNotices.push()\n │ │ │\n │ │ before_prompt_build │\n │ │ (priority 850) │\n │ │<─────────────────────────│\n │ │ 注入 pendingNotices │\n │ \"Pipeline paused\" │ │\n │<──────────────────────│ │\n```\n\n命令优先级（从高到低）：doctor/version → quickstart → status/list → diagnose/retry/pause/skip/resume → create。降级模式下只处理 doctor/version/status/list。\n\n### 6.7 场景七：FTUE 快速启动（sevo:quickstart）\n\n```\n用户 SEVO 插件层 SEVO 核心\n │ │ │\n │ \"sevo:quickstart\" │ │\n │──────────────────────>│ │\n │ │ 内置 hello-sevo 需求 │\n │ │ route({isNewModule:true}) │\n │ │─────────────────────────────>│\n │ │ │ RoutingResult\n │ │ engine.create(routing) │\n │ │─────────────────────────────>│\n │ │ │ state.json\n │ │ 覆盖 requiredStages = │\n │ │ QUICKSTART_STAGES │\n │ │ (7 阶段精简流水线) │\n │ │ │\n │ │ 创建 projects/hello-sevo/ │\n │ │ docs/ src/ tests/ reports/ │\n │ │ │\n │ │ 激活 spec 阶段 │\n```\n\nQUICKSTART_STAGES 精简流水线（7 阶段）：\n```\nspec → spec-review-gate → implement → review → smoke-test → verify → ledger\n```\n\n跳过的阶段：test-case-authoring、contract、contract-review-gate、regression、publish-generalization-gate、deploy。完成后输出产出物清单（spec、代码、review 报告路径）。\n\n### 6.8 场景八：手动干预状态机\n\n```\n +----------+\n | active |\n +----+-----+\n sevo:pause | sevo:skip \n +----------+----------+\n v | v\n +----------+ | +----------+\n | paused | | | skipped |\n +----+-----+ | +----+-----+\n sevo:resume| | | 自动激活下一阶段\n v | v\n +----------+ | +--------------+\n | active | | | next stage |\n +----------+ | | active |\n | +--------------+\n |\n sevo:retry\n |\n +----v-----+\n | active | (attempt++)\n +----------+\n```\n\n持久化机制：\n- pause/resume：修改 `active-pipelines.json` 中 `info.status` 字段（'paused' / 'active'），记录 `pausedAt` 时间戳\n- skip：调用 `updateStageProgress()` 标记阶段为 'skipped'，自动查找 `requiredStages` 中的下一阶段并激活\n- retry：重新激活 failed 阶段，attempt 计数递增，label 编码为 `sevo:::`\n- 所有干预操作写入事件日志（type: 'manual_intervention'，action: pause/skip/resume）\n\nskip 的审计警告：跳过 review/audit 类阶段时输出 WARNING 提示质量保障降级。\n\n### 6.9 场景九：项目隔离与目录初始化\n\n`sevo:create ` 或 `sevo:quickstart` 触发时，插件自动创建隔离的项目目录：\n\n```\nprojects//\n+-- docs/\n| +-- design/ <- spec 产出\n| +-- architecture/\n| +-- decisions/ <- ADR 产出\n+-- src/ <- 编码产出\n+-- tests/ <- 测试用例\n+-- reports/ <- 审计/评审报告\n+-- scripts/ <- 验证脚本\n```\n\nprojectRoot 传递链路：\n```\nsevo:create → projectRoot = \"projects/\"\n → active-pipelines.json[pipelineId].projectRoot\n → getProjectRoot(pipelineId) 读取\n → buildTaskPrompt(stageId, state, projectSlug, projectRoot)\n → task prompt 中所有产出路径基于 projectRoot\n```\n\n多项目并行时，每个项目的产出物在独立目录中，互不干扰。projectRoot 作为参数贯穿整个任务派发链路，确保所有阶段的 artifact 路径一致。\n\n---\n\n## 7. 部署视图\n\n### 7.1 部署拓扑\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│ 宿主机 (Linux) │\n│ │\n│ ┌──────────────────────────────────────────────────────────────┐ │\n│ │ OpenClaw Gateway 进程 │ │\n│ │ │ │\n│ │ ┌─────────────────────────────────────────────────────────┐ │ │\n│ │ │ Plugin Runtime │ │ │\n│ │ │ │ │ │\n│ │ │ ┌──────────────────────────────────────┐ │ │ │\n│ │ │ │ sevo-pipeline (extensions/) │ │ │ │\n│ │ │ │ index.js + bridge.js + task-mapper │ │ │ │\n│ │ │ │ + label-protocol.js │ │ │ │\n│ │ │ └──────────────┬───────────────────────┘ │ │ │\n│ │ │ │ lazy-load (bridge.js) │ │ │\n│ │ └─────────────────┼───────────────────────────────────────┘ │ │\n│ │ │ │ │\n│ └────────────────────┼──────────────────────────────────────────┘ │\n│ │ │\n│ ▼ │\n│ ┌──────────────────────────────────────────────────────────────┐ │\n│ │ SEVO 核心 (projects/sevo/dist/) │ │\n│ │ pipeline-engine.js | gate-engine.js | ledger-engine.js │ │\n│ │ router.js | clarification-coordinator.js │ │\n│ └──────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌──────────────────────────────────────────────────────────────┐ │\n│ │ 数据层 (projects/sevo/data/) │ │\n│ │ pipelines//state.json — 流水线状态（单 writer） │ │\n│ │ pipelines//events.jsonl — 事件日志（append-only） │ │\n│ │ ledger/ — Ledger 条目 │ │\n│ └──────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌──────────────────────────────────────────────────────────────┐ │\n│ │ 插件运行态 (extensions/sevo-pipeline/state/) │ │\n│ │ config.json — 运行时配置覆盖 │ │\n│ │ active-pipelines.json — 活跃流水线追踪 │ │\n│ └──────────────────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n### 7.2 与 OpenClaw Gateway 的集成方式\n\nSEVO 插件通过 `openclaw.plugin.json` 声明式注册到 Gateway Plugin Runtime：\n\n| 集成点 | 机制 | 说明 |\n|--------|------|------|\n| 插件发现 | `openclaw.plugin.json` | Gateway 启动时扫描 extensions/ 目录，加载 plugin manifest |\n| 插件初始化 | `plugin.register(api)` | Gateway 调用 register()，传入 logger + config + hook 注册 API |\n| 事件订阅 | `api.on(hookName, handler, { priority })` | 3 个 hook 按优先级注册到 Gateway 事件总线 |\n| 子 Agent 派发 | `sessions_spawn` 工具调用 | 主会话通过 Gateway RPC 派发子 Agent，插件在 before_tool_call 注入 label |\n| 任务完成通知 | `subagent_ended` 事件 | Gateway 在子 Agent 结束时广播，插件据此推进流水线 |\n| Prompt 注入 | `before_prompt_build` 返回 `{ prependContext }` | 插件向主会话 prompt 前置注入流水线指令 |\n\n### 7.3 降级模式\n\n插件启动时检查 `dist/pipeline/pipeline-engine.js` 是否存在：\n- 存在 → active 模式，3 个 hook 全部生效\n- 不存在 → degraded 模式，所有 hook 变为 no-op，记录 `sevo_degraded` 事件\n\n降级不影响 Gateway 其他插件和主会话正常运行。\n\n### 7.4 配置解析优先级\n\n```\nplugin.register(api.config) > state/config.json > 环境变量 > 硬编码默认值\n```\n\n可配置项：workspaceRoot、sevoRoot、sevoDistPath、sevoDataPath、cacheTtlMs、stageAgentMap。\n\n---\n\n## 8. 横切关注点\n\n### 8.1 错误处理\n\n**插件层：fail-open**\n\n所有 hook handler 通过 `safeSevoHook()` 包裹：\n- 同步异常 → try-catch 捕获，记录 `sevo_hook_error` 事件，返回 null\n- 异步异常 → Promise.catch() 捕获，同样记录并返回 null\n- 单个 hook 失败不阻断 Gateway 事件总线，不影响其他插件\n\n**核心层：fail-safe**\n\n- PipelineEngine.advance() 中的状态转换通过 `assertTransition()` 强制校验，非法转换抛异常\n- 文件写入使用 `atomicWriteJson()`（write-tmp + rename），避免半写状态\n- Bridge 模块级故障隔离：PipelineEngine 加载失败不影响 LedgerEngine 和 Router\n\n**Result 类型**\n\n核心库使用 `Result` 联合类型（ok/error 二选一），避免异常穿透：\n```typescript\ntype Result = { ok: true; value: T } | { ok: false; error: E };\n```\n\n**错误诊断体系**\n\n插件层定义结构化错误码表 `SEVO_ERRORS`，每个错误码包含描述、原因、修复建议：\n\n| 错误码 | 描述 | 修复建议 |\n|--------|------|----------|\n| SEVO-E001 | No coding agent available | 等待任务完成或添加 agent |\n| SEVO-E002 | Spec file not found | 检查 spec 任务输出，sevo:retry |\n| SEVO-E003 | Stage gate failed | 修复 P0 问题，sevo:retry |\n| SEVO-E004 | Task timeout | 增加超时或拆分任务 |\n| SEVO-E005 | Pipeline state corrupted | 检查文件权限和 JSON 语法 |\n| SEVO-E006 | Agent task failed | 检查 agent 日志，sevo:retry |\n| SEVO-E007 | Hook registration missing | 运行 init.sh 重新注册 |\n| SEVO-E008 | Project directory creation failed | 检查磁盘空间和目录权限 |\n\n`formatError(code, context)` 统一格式化错误输出，包含错误码、描述、原因、修复建议，可选附加 stage/pipelineId/error 上下文。`sevo:diagnose ` 命令对失败流水线做深度诊断，分析当前阶段状态、失败原因、产出物完整性。\n\n**版本管理与状态迁移**\n\n- `SEVO_VERSION` 常量（当前 `0.2.0`）标识插件版本，`sevo:version` 命令输出\n- `CURRENT_SCHEMA_VERSION` 常量（当前 `2`）标识 active-pipelines.json 的 schema 版本\n- `migrateState(state)` 在加载状态文件时自动执行 schema 迁移：\n - v1 → v2：为每个 pipeline 条目添加 `frTracking` 默认值（`{ total: [], completed: [], remaining: [], lastUpdatedAt: null }`）\n- `loadActivePipelinesWithMigration()` 封装加载+迁移+保存的完整流程，迁移发生时写入 `sevo_state_migrated` 事件\n- 升级安全：迁移函数只做向前兼容的增量修改，不删除已有字段\n\n**配置验证（sevo:doctor）**\n\n`handleDoctorCommand()` 执行 5 项自检，输出 Errors/Warnings/OK 三级结果：\n\n| 检查项 | 通过条件 | 失败级别 |\n|--------|----------|----------|\n| 插件注册 | openclaw.json plugins 中存在且 enabled | Error |\n| Hook 注册 | 非 degraded 模式 | Warning |\n| Agent 池 | coding agent ≥1 | Error（coding）/ Warning（audit） |\n| 状态文件可写 | STATE_DIR 可写入 | Error |\n| 路径配置 | workspaceRoot 和 extensionRoot 存在 | Error |\n\n### 8.2 日志与审计\n\n**事件日志（events.jsonl）**\n\n每个流水线实例有独立的 events.jsonl，append-only 语义：\n- 事件类型：pipeline_created / pipeline_completed / stage_activated / stage_completed / stage_failed / stage_blocked / stage_skipped / artifact_registered / clarification_opened / clarification_resolved / clarification_settled\n- 每条事件包含 timestamp、pipelineId、stage、eventType、payload\n- 用于事后审计和状态重建\n\n**插件事件日志**\n\n插件层维护独立的事件日志（`logs/sevo-pipeline-events.jsonl`），记录：\n- sevo_hook_error — hook 执行异常\n- sevo_completion_received — 收到子 Agent 完成事件\n- sevo_advanced — 流水线推进\n- sevo_engine_unavailable — 核心引擎不可用\n- sevo_prompt_injected — prompt 注入\n- sevo_label_injected — label 注入\n- sevo_degraded — 降级模式激活\n\n**Ledger（审计账本）**\n\n流水线完成后，LedgerEngine 收集全部 artifact 和 stage record，写入不可变 LedgerEntry：\n- conclusion: delivered | aborted\n- evidence: 全部 artifact 引用\n- stages: 每个阶段的完整记录\n\n### 8.3 安全\n\n| 关注点 | 措施 |\n|--------|------|\n| 开发与审计分离 | 编码 Agent 不做自审；review/audit 阶段由独立 Agent 执行 |\n| 审查 Agent 工具隔离 | review/audit Agent 的工具白名单 schema-level 隔离写权限（无 Edit/Write/Bash） |\n| 状态完整性 | state.json 原子写入（write-tmp + rename），避免并发损坏 |\n| Label 注入防护 | label 编解码有严格格式校验（`sevo:` 前缀 + 结构化 decode） |\n| 插件隔离 | 插件层 fail-open，单插件故障不影响 Gateway 和其他插件 |\n| 文件路径解析 | 所有路径通过 `resolveConfiguredPath()` 规范化，防止路径穿越 |\n\n### 8.4 可测试性\n\n| 层次 | 测试策略 |\n|------|----------|\n| 核心库单元测试 | `src/__tests__/` 下覆盖 Router、Pipeline Engine、Gate Engine、Orchestrator、Adapter |\n| 阶段单元测试 | `src/stages/__tests__/` 每个阶段独立测试 |\n| Gate 单元测试 | `src/gate/__tests__/gate-engine.test.ts` |\n| E2E 测试 | `src/__tests__/e2e.test.ts` + `full-pipeline-e2e.test.ts` 全流水线端到端 |\n| StandaloneAdapter | 独立运行模式，脱离 OpenClaw 环境可测试核心逻辑 |\n| 插件层 | 通过 mock Gateway API 测试 hook 注册和事件处理 |\n\n### 8.5 持久化策略\n\n| 数据 | 文件 | 写入模式 | 一致性保证 |\n|------|------|----------|-----------|\n| 流水线状态 | `pipelines//state.json` | 单 writer + atomic write | write-tmp + rename，无半写 |\n| 事件日志 | `pipelines//events.jsonl` | append-only（O_APPEND） | 单行 JSON，断电最多丢最后一行 |\n| Ledger | `ledger/` | 不可变写入 | 写入后不修改 |\n| 活跃流水线 | `state/active-pipelines.json` | write-tmp + rename | 同 state.json |\n| 插件配置 | `state/config.json` | 手动编辑 | 读取时 try-catch 容错 |\n\n### 8.6 模块缓存与热重载\n\nBridge 层实现模块级缓存 + 自动失效：\n- 缓存 TTL 默认 30s（可通过 cacheTtlMs 配置）\n- 文件 mtime 变化检测，自动重新加载编译产物\n- 加载失败后 backoff（同 TTL 时间内不重试）\n- cache-bust 通过 URL query parameter（`?v=`）实现\n\n---\n\n## 9. 架构决策\n\n以下为 SEVO 关键架构决策摘要。完整 ADR 存放于 `docs/decisions/` 目录。\n\n### ADR-001: 状态机驱动 vs 规则引擎\n\n- Context：需要一种机制保障 12 个阶段按序执行、不跳步\n- Decision：采用有限状态机（FSM），每个阶段有明确的状态转换规则（stage-machine.ts）\n- Consequences：状态转换可形式化验证；新增阶段需修改状态图；比规则引擎更刚性但更可预测\n\n### ADR-002: 核心通用 + Host Adapter 模式\n\n- Context：SEVO 需要在 OpenClaw 内运行，但不应绑死单一宿主\n- Decision：核心库不依赖 OpenClaw API，通过 SevoHostAdapter 接口抽象宿主能力\n- Consequences：可独立测试（StandaloneAdapter）；OpenClaw 特化逻辑集中在 OpenClawAdapter；新宿主只需实现 adapter 接口\n\n### ADR-003: 三级路由（L0/L1/L2+）\n\n- Context：不是所有改动都需要走完整 12 阶段流水线\n- Decision：Router 根据 TaskScope 自动分级——L0 跳过、L1 轻量、L2+ 完整\n- Consequences：小改动快速通过；大改动强制全流程；分级规则可配置\n\n### ADR-004: Spec Review 后并行分叉\n\n- Context：test-case-authoring 和 contract 无依赖关系，串行执行浪费时间\n- Decision：spec-review-gate 通过后同时激活两条分支；implement 等待两条分支都完成\n- Consequences：缩短流水线总耗时；parallel-branch.ts 管理分叉/合并逻辑；增加了状态管理复杂度\n\n### ADR-005: 单文件状态 + 事件溯源\n\n- Context：需要持久化流水线状态，同时支持审计\n- Decision：state.json 单 writer 模型 + events.jsonl append-only\n- Consequences：无并发写冲突；事件日志支持状态重建和审计；不适合高并发场景（当前单流水线足够）\n\n### ADR-006: 插件层 fail-open\n\n- Context：插件运行在 Gateway 进程内，异常可能影响整个系统\n- Decision：所有 hook handler 包裹 safeSevoHook()，异常记录但不传播\n- Consequences：单 hook 故障不拖垮 Gateway；错误可能被静默吞掉（通过事件日志补偿可观测性）\n\n### ADR-007: GateRule SPI 可插拔门禁\n\n- Context：不同阶段的质量标准不同，需要灵活组合\n- Decision：定义 GateRule 接口，内置 FileExists/TypeCheck/TestPass/MinCoverage，支持扩展\n- Consequences：新增质量规则只需实现 GateRule 接口；规则组合通过 verdict-aggregator 聚合\n\n### ADR-008: Label Protocol 流水线上下文传递\n\n- Context：子 Agent session 需要携带流水线上下文，completion 时路由回正确实例\n- Decision：通过 session label 编码 `sevo:::`\n- Consequences：零额外通信开销；依赖 Gateway label 机制；label 格式变更需要前后兼容\n\n### ADR-009: 命令系统通过 Hook 拦截实现\n\n- Context：用户需要通过对话控制流水线（创建/暂停/跳过/查询），需要一种命令路由机制\n- Decision：在 `before_prompt_build`（priority 100）hook 中用正则匹配 `sevo:*` 命令，路由到对应 handler，结果通过 `pendingNotices` 注入主会话 prompt\n- Consequences：命令处理在 prompt 构建前完成，主会话无需感知命令解析逻辑；正则匹配足够覆盖结构化命令格式；降级模式下只读命令（doctor/version/status/list）仍可用\n\n### ADR-010: 项目产出物目录隔离\n\n- Context：多个 SEVO 项目并行时，产出物散落在 workspace 根目录会互相干扰\n- Decision：每个项目创建独立的 `projects//` 目录，所有阶段产出物路径基于 projectRoot；projectRoot 持久化到 active-pipelines.json 并贯穿整个任务派发链路\n- Consequences：多项目并行互不干扰；项目目录可直接作为独立 Git 仓库；需要在 buildTaskPrompt 中始终传递 projectRoot 参数\n\n### ADR-011: 状态 Schema 迁移策略\n\n- Context：active-pipelines.json 的数据结构随功能演进需要变更（如新增 frTracking 字段）\n- Decision：引入 `schemaVersion` 字段和 `migrateState()` 函数，加载时自动执行向前兼容的增量迁移\n- Consequences：升级无需手动干预；迁移只做增量修改不删除字段；迁移事件写入日志可追溯\n\n---\n\n## 10. 质量需求\n\n### 10.1 质量属性场景树\n\n```\n SEVO 质量属性\n │\n ┌───────────┬───────┼───────┬───────────┐\n ▼ ▼ ▼ ▼ ▼\n 可控性 可审计性 通用性 可靠性 可扩展性\n```\n\n### 10.2 质量属性场景\n\n| ID | 质量属性 | 场景 | 度量 |\n|----|----------|------|------|\n| QA-01 | 可控性 | Gate 评估为 rejected 时，流水线不放行后续阶段 | 100% 阻断率，零漏放 |\n| QA-02 | 可控性 | 非法状态转换（如 passed → active）被拒绝 | assertTransition() 抛异常，状态不变 |\n| QA-03 | 可审计性 | 任意流水线可通过 events.jsonl 重建完整执行历史 | 事件覆盖所有状态转换，无遗漏 |\n| QA-04 | 可审计性 | Ledger 记录流水线全部 artifact 和结论 | LedgerEntry 包含 stages + evidence + conclusion |\n| QA-05 | 通用性 | 核心库在无 OpenClaw 环境下可独立运行和测试 | StandaloneAdapter 通过全部单元测试 |\n| QA-06 | 通用性 | 新增宿主只需实现 SevoHostAdapter 接口 | 接口方法 ≤6 个，无隐式依赖 |\n| QA-07 | 可靠性 | 插件层单 hook 异常不影响 Gateway 和其他插件 | safeSevoHook() 100% 捕获，Gateway 事件总线不中断 |\n| QA-08 | 可靠性 | state.json 写入过程中断电不产生损坏文件 | atomic write（write-tmp + rename）保证 |\n| QA-09 | 可靠性 | Bridge 单模块加载失败不影响其他模块 | per-module failure isolation，独立 backoff |\n| QA-10 | 可扩展性 | 新增阶段只需：定义 stage 实现 + 更新 stage-graph + 注册 agent 映射 | 改动 ≤3 个文件 |\n| QA-11 | 可扩展性 | 新增门禁规则只需实现 GateRule 接口 | 零核心代码修改 |\n| QA-12 | 可扩展性 | 阶段→Agent 映射可通过 config 覆盖 | stageAgentMap 配置项，无需改代码 |\n| QA-13 | 可用性 | 用户通过 sevo:doctor 一条命令完成安装自检 | 5 项检查全覆盖，Errors/Warnings/OK 三级输出 |\n| QA-14 | 可用性 | 流水线失败时用户看到结构化错误码和修复建议 | SEVO_ERRORS 8 种错误码，formatError 统一格式 |\n| QA-15 | 可用性 | sevo:quickstart 5 分钟内跑通首个流水线 | 7 阶段精简流水线，内置示例需求 |\n| QA-16 | 可控性 | 用户可暂停/跳过/重试流水线任意阶段 | pause/skip/resume/retry 4 种干预操作，状态持久化 |\n| QA-17 | 可靠性 | 状态 schema 变更时自动迁移，无需手动干预 | migrateState 增量迁移 + 事件日志记录 |\n| QA-18 | 隔离性 | 多项目并行时产出物互不干扰 | projects/\\/ 独立目录，projectRoot 贯穿链路 |\n\n---\n\n## 11. 风险与技术债务\n\n### 11.1 已知风险\n\n| ID | 风险 | 影响 | 缓解措施 |\n|----|------|------|----------|\n| R-01 | 核心库未编译（dist/ 不存在） | 插件降级为 no-op，流水线不可用 | 降级模式 + 事件日志记录；CI 应确保 dist/ 始终可用 |\n| R-02 | 单 writer 模型在多流水线并发时可能竞争 | state.json 写入冲突 | 当前单流水线场景足够；未来需引入文件锁或数据库 |\n| R-03 | 子 Agent 超时或静默失败 | 流水线卡在某阶段不推进 | 依赖 Gateway run-watchdog 插件检测超时；需补充流水线级超时机制 |\n| R-04 | Gate 评估目前只支持 pass/fail 二元 | conditional（有条件通过）语义未在插件层实现 | 核心层已支持 conditional；插件层 TODO 标记待实现 |\n| R-05 | 澄清协调依赖宿主 adapter 实现 | StandaloneAdapter 的澄清能力有限 | 核心层接口已定义；OpenClawAdapter 需完善交互式澄清 |\n\n### 11.2 技术债务\n\n| ID | 债务 | 位置 | 优先级 |\n|----|------|------|--------|\n| TD-01 | 插件层 subagent_ended 只解析 pass/fail，未处理 conditional/rejected 门禁裁决 | index.js:284 TODO | P1 |\n| TD-02 | Bridge 模块缓存使用 URL cache-bust，依赖 Node.js ESM loader 行为 | bridge.js:131 | P2 |\n| TD-03 | 活跃流水线追踪（active-pipelines.json）与核心 state.json 存在数据冗余 | index.js:164-170 | P3 |\n| TD-04 | 插件事件日志与核心事件日志分离，缺乏统一查询接口 | index.js / pipeline-engine.ts | P2 |\n| TD-05 | KIVO 集成（Ledger → 知识入库）和 AEO 集成（指标 → 监控）尚未实现 | 架构预留，代码未写 | P2 |\n| TD-06 | 流水线级超时机制缺失，依赖外部 watchdog | pipeline-engine.ts | P1 |\n| TD-07 | ~~规模路由（FR-D08）~~ 已实现 | router / index.js | P2 |\n| TD-08 | 命令解析使用正则匹配，复杂参数场景可能需要升级为解析器 | index.js:1170-1180 | P3 |\n\n---\n\n## 12. 术语表\n\n| 术语 | 定义 |\n|------|------|\n| SEVO | Spec-Execute-Verify-Operate，Agent 自动研发流水线 |\n| SDD | Specify-Design-Develop，SEVO 的前身流程规范（AGENTS.md 中定义） |\n| Stage | 流水线阶段，12 个阶段构成完整流水线 |\n| Gate | 门禁，阶段间的质量检查点，输出 passed/conditional/rejected |\n| StageId | 阶段标识符，枚举类型（spec / spec-review-gate / ... / ledger） |\n| StageStatus | 阶段状态：pending / active / blocked / clarification-blocked / passed / failed / skipped |\n| TaskLevel | 任务级别：L0（跳过）/ L1（轻量）/ L2+（完整流水线） |\n| TriggerRule | 触发规则，决定任务是否需要完整流水线（new-module / cross-domain / large-change 等） |\n| RoutingResult | Router 输出，包含 level、requiredStages、skippedStages、matchedRules |\n| PipelineState | 流水线完整状态，持久化到 state.json |\n| StageRecord | 单个阶段的执行记录，包含 status、artifacts、attempt 等 |\n| StageTransition | advance() 的返回值，描述从哪个阶段转换到哪个阶段 |\n| GateVerdict | 门禁评估结果，包含 conclusion、blockers、reviewBundles |\n| GateRule | 门禁规则 SPI 接口，可插拔的质量检查规则 |\n| ReviewBundle | 单个审查者的审查结论，包含 reviewer、role、conclusion、issues |\n| LedgerEntry | 审计账本条目，记录流水线完整执行证据 |\n| ArtifactRef | 产物引用，包含 id、type、path、createdAt |\n| Host Adapter | 宿主适配器，将核心抽象操作映射到具体宿主环境 |\n| OpenClawAdapter | OpenClaw 宿主适配器实现 |\n| StandaloneAdapter | 独立运行适配器，用于测试和非 OpenClaw 环境 |\n| Bridge | 插件层懒加载桥梁，管理核心编译产物的加载和缓存 |\n| Label Protocol | 流水线上下文编码协议，格式 `sevo:::` |\n| pendingAdvances | 插件层内存队列，缓存待注入主会话的下一阶段任务 |\n| fail-open | 错误处理策略：异常记录但不阻断，保证系统可用性 |\n| fail-safe | 错误处理策略：异常阻断操作，保证数据一致性 |\n| atomic write | 原子写入：write-tmp + rename，避免半写状态 |\n| ClarificationCoordinator | 澄清协调器，管理歧义发现→阻塞→解决→恢复的完整生命周期 |\n| BlockingLevel | 澄清阻塞级别，决定歧义是否阻塞当前阶段执行 |\n| SEVO_ERRORS | 结构化错误码表，每个错误码包含描述、原因、修复建议 |\n| formatError | 统一错误格式化函数，输出错误码 + 描述 + 原因 + 修复建议 + 上下文 |\n| SEVO_VERSION | 插件版本常量（当前 0.2.0），sevo:version 命令输出 |\n| migrateState | 状态 schema 迁移函数，加载时自动执行向前兼容的增量迁移 |\n| QUICKSTART_STAGES | FTUE 精简流水线阶段集（7 阶段），跳过三方会审和 UX 验收 |\n| projectRoot | 项目产出物根目录（projects/\\/），贯穿整个任务派发链路 |\n| getUserJourneyTemplate | 6 阶段用户体验旅程模板函数，注入 spec 和 ux-acceptance 阶段 |\n| pendingNotices | 插件层内存队列，缓存命令执行结果，由 before_prompt_build 注入主会话 |\n| KIVO | Agent 知识迭代引擎（未来集成） |\n| AEO | Agent 效果运营平台（未来集成） |\n\nFile v1.13.1:docs/backlog-endgame-auto-fix.md\n\n# SEVO 新需求：终局扫描自动修复闭环\n\nOpenClaw（主会话）2026-05-21\n\n## 痛点\n终局差距扫描发现 P0/P1 gap 后，当前需要人工：\n1. 手动创建 SEVO 流水线\n2. 手动写 spec\n3. 手动派 implement\n4. 手动审计\n5. 手动复验\n\n整个修复链路没有自动化，违背 SEVO \"全自动研发流水线\" 的定位。\n\n## 期望能力\n- 终局扫描完成后，自动按 P0→P1 优先级生成修复任务\n- 每个修复任务自动创建 SEVO 流水线（轻量级，跳过已有 spec 的阶段）\n- 自动派发到可用 agent\n- 修复完成后自动触发复验（re-scan 对应 FR）\n- 复验通过自动关闭 gap，不通过自动重派\n\n## 与现有 FR 的关系\n- FR-29 (Tiered Endgame Gap Scan) 的自然延伸\n- FR-19 (终局交付自动推进) 的具体场景\n\n## 优先级\nP1 — 当前手动操作可行但低效，属于 SEVO 自身的 dogfooding 缺口\n\nFile v1.13.1:docs/product-requirements.md\n\n# SEVO - 产品需求规格说明书\n\nCodex（OpenClaw ACP Agent）| 2026-04-19\n\n---\n\n## 目录\n\n1. 产品愿景与定位\n2. 目标用户画像\n3. 编排入口与流程编排\n4. 功能需求（8 阶段 + 3 个验收阶段 + 2 个门禁 + 5 个跨阶段机制 + 3 个生命周期操作 + 4 个平台能力）\n5. 非功能需求\n6. 概念架构\n7. 与 Self-Evolving Harness 其他模块的边界\n8. Wave 规划\n9. 约束与假设\n\n## 1. 产品愿景与定位\n\nSEVO（Spec-Execute-Verify-Operate）是面向 vibe coding 用户的 Agent 研发流水线。它把需求定义、方案约束、实现执行、独立审计、回归验证、部署发布、清洁环境验收和交付留痕收拢到同一条可追溯流水线上，让 Agent 软件研发从“能生成代码”升级为“能稳定交付结果”。SEVO 服务的核心人群是把 AI 当研发主力的人：他们要的不是一次性生成，而是每次改动都能看清目标、边界、证据和责任。\n\nSEVO 以 npm 包（`sevo`）形式分发，`npx sevo init` 一条命令完成环境初始化，零配置即可启动第一条研发流水线。SEVO 把 PM、UX、架构师、审计等角色的专业标准内置到流水线阶段中——单 Agent 用户也能产出 PM 质量的 spec，多 Agent 环境有专职角色则效果更好，但不是必须。\n\nSEVO 运行在 OpenClaw 环境中。架构层面通过 Adapter 抽象层隔离对 OpenClaw 内部 API 的直接依赖，保持代码职责清晰和可测试性——这是代码质量约束，不是支持其他平台的产品承诺。\n\n**终局思维：以终局用户体验为目标的全自动化开发。** SEVO 流水线的终点不是「代码能跑」「测试通过」「npm 发布成功」，而是「陌生用户装上就能用、5 分钟内感受到产品的核心价值」。这是 SEVO 区别于传统 CI/CD 和 AI Coding 工具的核心差异——传统工具优化开发者体验，SEVO 优化终局用户体验。\n\n**目标驱动 PDCA 闭环：OKR→SMART→PDCA 融入现有流程。** SEVO 的运转不是线性流水线跑一遍就结束，而是围绕终局目标的持续收敛循环。OKR→SMART→PDCA 是目标管理的核心理念，它指导 SEVO 的每一次闭环，融入到现有阶段中：\n\n- **Pipeline 创建时（OKR 介入）**：SEVO 主动引导用户澄清需求的终局目标——「做完后，一个从没见过这个产品的人，装上 5 分钟内应该能做到什么？」锁定为 endStateGoal，拆解为 Objective + Key Results。这是 pipeline 的北极星。\n- **Spec 阶段（SMART 介入）**：每个 KR 转化为具体（Specific）、可度量（Measurable）、可达成（Achievable）、相关（Relevant）、有时限（Time-bound）的 FR。FR 天然带着「服务于哪个 KR → 哪个 O → 终局目标」的溯源链。\n- **Implement → Review → Verify → Deploy（PDCA 的 Do + Check）**：现有阶段不变，但每个 gate 的评估锚点升级——从「这个阶段的产出合格吗」到「这个阶段的产出在向终局目标收敛吗」。\n- **Post-Release Validation（PDCA 的 Check，目标级）**：不是查 FR 清单，是查 KR 达成了没有。差距分析的对象是终局目标，不是功能列表。\n- **差距 > 0（PDCA 的 Act）**：分析哪个 KR 未达成，重新 SMART 拆解，进入下一轮 pipeline 循环。\n- **差距 = 0**：所有 KR 达成，Objective 达成，终局目标达成，pipeline 关闭。\n\n现有 18 个阶段一个不改。加的是 pipeline 级别的目标元数据（endStateGoal、OKR 树、KR 达成度）和循环判定逻辑（差距分析 → 决定是否再来一轮）。Post-Release Validation Gate 是这条闭环的强制执行点。\n\n## 2. 目标用户画像\n\n### 2.1 Solo Founder / 独立产品操盘者\n\n- 用 Agent 推进产品、技能、自动化系统的研发。\n- 关心交付速度，也关心返工成本和线上事故。\n- 需要看到每一轮改动的目标、边界、验收标准和交付证据。\n- 上手路径：`npm install -g sevo && npx sevo init && sevo project create my-app`，5 分钟内看到第一条 pipeline 的 Spec 阶段产出。\n\n### 2.2 Agent 原生开发者\n\n- 把 AI 作为主要编码和调试执行者。\n- 需要一条能约束 Agent 的研发流程，减少“写完就算完”的假完成。\n- 需要把 Spec、Contract、Implement、Review 串起来，避免需求和代码脱节。\n- 上手路径：`npx sevo init` 自动发现已有 Agent 并分配角色，`sevo fr add \"需求描述\"` 后 pipeline 自动推进，开发者只需响应阶段任务。\n\n### 2.3 质量与架构把关者\n\n- 负责审计需求、架构、代码质量和交付完整性。\n- 需要独立视角和统一工件链路，快速判断是否通过、卡在哪里、缺什么。\n- 需要把经验沉淀回系统，而不是散落在聊天记录里。\n- 上手路径：`sevo status` 查看所有 pipeline 状态，门禁阶段自动派发审查任务，审查结论写入结构化工件。\n\n### 2.4 OpenClaw 环境管理者\n\n- 负责配置和管理 OpenClaw 环境中的 Agent 池、模型、通知渠道等基础设施。\n- 需要 SEVO 的流程能力与具体 Agent/模型/通知实现解耦，便于按需替换执行器、审计器、发布渠道。\n- 需要通过配置而非改代码来适配不同的 Agent 池规模和模型组合。\n- 上手路径：`npm install sevo`，`npx sevo init` 自动发现 OpenClaw 环境配置，核心阶段语义开箱可用。\n\n### 2.5 陌生用户首次使用旅程\n\n一个从未见过 SEVO 的用户，完整的首次体验路径：\n\n1. `npm install -g sevo` — 安装 SEVO。\n2. `npx sevo init` — 自动检测 OpenClaw 环境、注册插件、发现 Agent 并分配角色。单 Agent 环境自动降级，所有角色由同一个 Agent 承担。\n3. 重启 OpenClaw（如 `openclaw gateway restart`）使插件生效。\n4. `sevo project create my-first-project --description \"项目描述\"` — 创建第一个 Project。\n5. `sevo fr add my-first-project \"实现用户登录功能\"` — 添加第一条 FR，pipeline 自动创建并开始推进。\n6. `sevo status` — 查看 pipeline 当前走到哪个阶段、卡在哪里、下一步是什么。\n\n从步骤 1 到步骤 5 产出第一份 Spec，预计耗时不超过 5 分钟。\n\n## 3. 编排入口与流程编排\n\nSEVO 是所有涉及代码变更的任务的默认研发流程。任务进入 SEVO 后，系统根据任务复杂度自动选择最合适的流程路径——简单任务走最小闭环，复杂任务走完整流水线。区别在于流程路径的深度，不在于是否进入 SEVO。\n\n### 3.1 编排范围\n\n所有涉及代码变更的任务默认进入 SEVO 编排范围。以下条件决定流程路径的深度（Level 0/1/2+）：\n\n- 从零新建模块或系统 → Level 2+。\n- 涉及两个及以上域的边界变化 → Level 2+。\n- 预估改动超过 500 行或 10 个文件 → Level 2+。\n- 涉及数据模型变化 → Level 2+。\n- 涉及治理规则、调度逻辑、质量门禁的变化 → Level 2+。\n- 涉及发布目标或交付方式变化 → Level 1+。\n- 单域中等改动 → Level 1。\n- 微小改动（bug 修复、配置调整、小功能）→ Level 0。\n- 用户明确要求走完整流程 → Level 2+。\n- 已有项目的需求规格说明书需要改动（新增/修改/删除 FR 或 AC）→ Level 1+。\n\n查询、聊天、配置调整等不涉及代码变更的任务不进入 SEVO。\n\n**触发判断实现（双层策略）**：\n- 主路径：LLM 语义判断。系统将任务描述提交给 LLM，由 LLM 判断任务是否命中上述条件、应归入哪个 Level，返回结构化判定结果（是否触发、Level、命中条件、判定理由）。\n\n\n### 3.2 流程路径\n\nSEVO 根据任务复杂度自动选择最短有效路径：\n\n- **Level 0**：微小改动。直接进入 Implement，经过 Review、Smoke Test、Verify、Ledger 的最小闭环。\n- **Level 1**：单域中等改动。从 Spec 开始，Contract 可简化，门禁不能省。涉及 Web/UI 的任务走 UX Interaction Design；涉及前后端复杂功能/数据模型变化/多模块协作的任务走 Architecture Design。\n- **Level 2+**：新系统、跨域重构、大范围变更、治理层变更。走完整 8 阶段，执行两道门禁。涉及 Web/UI 的任务默认走 UX Interaction Design；涉及前后端复杂功能的任务默认走 Architecture Design。\n\n### 3.3 路由输出与编排启动\n\n任务进入 SEVO 后，系统产出路由结果，至少包含：\n\n- 目标 Project（project-slug）。\n- 任务级别（Level 0/1/2+）。\n- 是否需要 UX Interaction Design（布尔值 + 判定理由）。\n- 是否需要 Architecture Design（布尔值 + 判定理由）。\n- 必经阶段清单。\n- 可跳过阶段及跳过理由。\n- 当前轮次的验收重点。\n- 需要追踪的核心工件。\n\n路由结果直接驱动 PipelineEngine（FR-13）创建阶段执行队列并开始自动推进。PipelineEngine 通过状态机驱动 + OpenClaw Adapter 触发阶段执行，不需要人工干预。\n\n### 3.4 验收标准\n\n- AC-3.1：相同输入任务在同一套规则下得到稳定一致的路由结果。\n- AC-3.2：每个进入 SEVO 的任务都有清晰的阶段清单和跳过理由。\n- AC-3.3：任何被跳过的阶段都不影响最终交付可追溯性。\n- AC-3.4：路由结果直接驱动 PipelineEngine 创建阶段执行队列，不需要人工重新解释。\n- AC-3.5：每个 FR 流程实例有唯一 ID，所有阶段工件可通过实例 ID 关联。\n- AC-3.6：多个 Project 的 FR 流程实例并行运行时，工件目录互不干扰。\n- AC-3.7：FR 流程实例状态变化可追溯，任一时刻能回答“这条 FR 的 SDD 流程走到哪了”。\n- AC-3.8：pipeline 创建后，PipelineEngine 在无人工干预的情况下自动推进到第一个阶段并开始执行。\n\n### 3.5 FR 流程实例\n\nFR 流程实例是一次完整的 SDD 流程执行。每当用户把一条 FR 添加到某个 Project，且该 FR 命中触发条件（§3.1）并完成路由判定后，系统创建一个 FR 流程实例，绑定到目标 Project，分配唯一 ID。这里的生命周期起点需要钉死：Project 由用户创建，最小输入是名称和描述；FR 由用户添加到 Project 中，最小输入是需求描述；FR 一旦创建成功，就自动进入 Specify 阶段对应的流程准备态，并据此生成或挂接到一个 FR 流程实例。\n\n核心属性：\n\n- **实例 ID**：全局唯一标识，格式 `fr---`，如 `fr-sevo-20260420-001`。\n- **Project 绑定**：每个实例归属一个 Project，实例的全部工件存放在该 Project 的目录空间内。\n- **路由结果**：实例创建时确定的任务级别、必经阶段、跳过阶段。\n- **当前阶段**：实例正在执行的 SDD 流程阶段。\n- **工件索引**：各阶段产出工件的引用列表。\n\n状态模型：\n\n- **created**：实例已创建，Project 目录已初始化，尚未进入第一个阶段。\n- **active**：至少一个阶段处于 active 或 blocked 状态。\n- **paused**：用户或系统主动挂起，所有阶段暂停推进。\n- **completed**：最终阶段（Ledger）通过，交付闭环。\n- **failed**：流程因不可恢复的原因终止。\n\n状态流转：\n\n- created → active：第一个阶段开始执行。\n- active → paused：用户主动挂起或系统检测到阻断条件。\n- paused → active：恢复执行。\n- active → completed：Ledger 阶段通过。\n- active → failed：不可恢复的失败（如用户取消、关键依赖永久不可用）。\n\n生命周期：\n\n1. 任务命中触发条件，路由判定完成。\n2. 创建 FR 流程实例，绑定 Project，初始化目录结构。\n3. 按路由结果依次推进各阶段，每个阶段的工件归档到实例目录。\n4. Ledger 阶段完成后，实例状态变为 completed，交付账本条目记录实例 ID。\n\n并行规则：\n\n- 同一 Project 同一时刻只允许一个 active 的 FR 流程实例。前一个实例必须 completed 或 failed 后，才能创建新实例。\n- 不同 Project 的 FR 流程实例完全独立，可并行运行。\n\n### 3.6 Project 与标准目录结构\n\nProject 是 SEVO 管理的独立交付单元。每个 Project 拥有自己的目录空间，所有 FR 流程实例的工件在该空间内按阶段归档。\n\n标准目录结构：\n\n```\n/projects//\n├── docs/ # 过程文档\n│ ├── product-requirements.md # 需求规格\n│ ├── architecture/ # 架构文档\n│ │ ├── arc42-architecture.md # 主架构文档\n│ │ └── decisions/ # ADR（架构决策记录）\n│ ├── ux/ # UX 交互设计文档\n│ └── test-cases/ # 测试用例文档\n├── src/ # 源代码\n├── tests/ # 测试代码\n├── skill/ # Skill 定义（如有）\n├── reports/ # 评审报告、审计报告\n├── artifacts/ # 阶段产出工件（构建产物、发布包）\n├── README.md\n├── LICENSE\n├── package.json\n└── tsconfig.json\n```\n\n目录职责：\n\n- `docs/`：过程文档。需求规格、架构设计、ADR、测试用例——描述“要做什么”和“怎么设计”。\n- `src/`：源代码。实现产物——“做出来的东西”。\n- `tests/`：测试代码。自动化测试——“怎么证明做对了”。\n- `skill/`：Skill 定义文件。如果 Project 产出的是 Skill，定义文件放这里。\n- `reports/`：质量证据。评审报告、审计报告、回归报告——“谁检查过、结论是什么”。\n- `artifacts/`：阶段产出工件。构建产物、发布包、部署制品——“最终交付物”。\n\n分类：\n\n- 过程文档：`docs/`（描述意图和设计）。\n- 结果代码：`src/`（实现产物）。\n- 质量证据：`tests/` + `reports/`（验证和审计记录）。\n- 交付物：`artifacts/`（可发布的最终产物）。\n\n初始化规则：\n\n- FR 流程实例创建时（FR-12），系统自动检查 Project 目录结构是否存在。\n- 目录不存在时，按标准结构创建全部目录和占位文件。\n- 目录已存在时，只补全缺失的子目录，不覆盖已有内容。\n\n## 4. 功能需求（8 阶段 + 3 个验收阶段 + 3 个门禁 + 5 个跨阶段机制 + 3 个生命周期操作 + 4 个平台能力）\n\n### FR-01 Spec\n\n- **输入**：用户目标、业务背景、已有约束、历史参考材料。\n- **处理**：明确问题、目标用户、范围、FR、NFR、概念架构和验收标准。Spec 产出阶段必须先完成四个用户层独立章节（用户人群、痛点、原始需求、用户体验流），再展开功能需求；缺任一章不得进入 Spec Review Gate。\n- **输出**：需求规格包（Spec Package）。\n- **执行阶段**：Spec。\n- **审查阶段**：Spec Review Gate（独立评审）。\n- **验收标准**：\n - AC-4.1：规格书能说清做什么、给谁做、做到什么程度算完成。\n - AC-4.2：每个核心功能都有验收标准。\n - AC-4.3：概念架构覆盖对象类型、状态流转和阶段间数据流。\n - AC-4.4：规格书不写具体技术选型和实现细节。\n - AC-4.4a：Spec 产出时必须先写四个用户层独立章节（用户人群、痛点、原始需求、用户体验流），且必须位于「功能需求」章节之前。任一章节缺失或仅有空标题，本 FR 视为未完成，禁止流转到 Spec Review Gate。\n - AC-4.4b：四个用户层章节必须有实质内容——用户人群描述具体到使用人群、典型场景、设备形态；痛点描述用户当前如何解决该问题、卡点在哪；原始需求用用户口语描述要什么；用户体验流给出从入口到产出的完整操作步骤。占位符、TODO、单句概述均判定为未完成。\n - AC-4.4c：FR 章节中的每个 FR 必须能追溯到上述四章中至少一条用户人群、痛点或体验流条目；找不到追溯关系的 FR 视为伪需求，由 PM 删除或回到四章补齐再产 FR。\n\n### FR-02-pre Mandatory Spec Sections Pre-Gate\n\n- **输入**：需求规格包（Spec Package）的 markdown 源文件。\n- **处理**：Spec Review Gate（FR-02）启动前的硬前置子门禁。先于其他评审维度执行，以两步检查校验四个用户层独立章节：\n 1. 存在性扫描：依据 markdown H2 结构定位四章——用户人群、痛点、原始需求、用户体验流。任一章缺失或仅为空标题（章节正文为空、TODO、占位符），直接判定不通过。\n 2. 内容质量语义判定：对存在的章节调用 LLM 进行语义判定，检查内容是否回答了该章节应回答的问题（例如「用户人群」是否描述了具体使用人群和场景；「痛点」是否描述了用户当前的解决方式与卡点）。禁止用关键词匹配或正则伪装语义理解，正则仅作为章节定位辅助。\n- **输出**：Spec Sections Pre-Gate 检查报告，包含每章存在性、章节起止行号、语义判定结论（pass/fail）、不通过项的具体缺口描述。\n- **执行阶段**：Spec Review Gate 之前的硬前置子门禁。本子门禁不通过则 spec-review-gate 立即返工到 Spec 阶段（FR-01），不允许并行执行产品/技术/质量/体验四维评审，避免并行 Agent 浪费资源。\n- **门禁判定**：四章存在 + 顺序正确 + 内容语义合格三项全通过才放行；任一项不通过即阻断 Spec Review Gate 主体维度评审。\n- **验收标准**：\n - AC-4.4d：spec-review-gate 收到 spec 时，第一步必须执行 Mandatory Spec Sections Pre-Gate；该子门禁未通过前，禁止启动产品/技术/质量/体验四维度评审。\n - AC-4.4e：四章存在性扫描以 markdown H2 章节为粒度。章节标题语义可接受同义表达（如「目标用户」「用户画像」可对应「用户人群」），同义判定必须由 LLM 给出，不得仅靠静态关键词列表。\n - AC-4.4f：四章内容质量必须由 LLM 语义判定。每章产出 pass/fail + 一句话理由，理由必须指向章节具体行号或文本片段。仅靠章节字数阈值或关键词命中判定为不合规检查。\n - AC-4.4g：任一章存在性、顺序或语义判定不通过，Pre-Gate 直接返工到 FR-01 Spec 阶段，并产出明确缺口清单（缺哪章 / 哪章顺序错 / 哪章语义不达标 + 缺口描述）。返工后必须重新跑完整 Pre-Gate，不允许只复查不通过项。\n - AC-4.4h：Pre-Gate 报告作为 Spec Review Bundle 的强制前置工件留档，供后续阶段追溯；FR-02 Spec Review Gate 必须在评审包顶部引用 Pre-Gate 结论。\n - AC-4.4i：Pre-Gate 不允许由 spec 作者自审，至少由独立 Agent 调用 LLM 完成判定，与 FR-02 主体评审遵守同一禁止自审原则。\n - AC-4.4j：Mandatory Spec Sections Pre-Gate 适用对象覆盖所有 SEVO 受管项目（按 FR-14 受管项目发现规则确定，包括 aco、claw-design、exam-sprint、kivo、sevo 及未来通过 `projects/*/sevo.json` 自动纳管的新项目）的产品需求规格主文件 `docs/product-requirements.md`，不仅作用于流水线运行期产出的增量 Spec Package。检查规则：\n 1. **章节齐全**：H2 级别必须独立存在四章——用户人群（谁用、什么场景、什么设备）、痛点（用户现在怎么解决、哪里痛）、原始需求（用户要什么，用人话说）、用户体验流（完整的用户操作步骤，从打开到完成）。同义表达（如「目标用户」「用户画像」对应「用户人群」）由 LLM 语义判定接受，禁止用静态关键词列表枚举允许的标题。\n 2. **顺序正确**：四章必须出现在「功能需求」H2 章节之前。任一章节出现在功能需求之后，或散落于 FR 内部，判定不通过。\n 3. **内容有实质**：每章正文必须由 LLM 做语义判定，回答该章应回答的问题；空标题、单句概述、TODO、占位符判定不通过。\n 检查规则强制使用 LLM 语义判定，禁止用关键词匹配、字数阈值或正则伪装语义理解；正则仅作为 H2 章节定位辅助。任一项不通过则受管项目 spec-review-gate 立即打回，禁止进入产品/技术/质量/体验任一维度评审，禁止进入下一阶段（Contract、Implement 等）；返工修复后必须重新跑完整 Pre-Gate。本 AC 同样适用于 SEVO 自身的 `projects/sevo/docs/product-requirements.md`，SEVO 不豁免自身。\n - AC-4.4k：spec-review-gate 启动时，必须先按 AC-4.4j 检查项目当前的 `docs/product-requirements.md` 主文件四章合规性。主文件不合规时，无论本轮提交的是新增 FR、迭代修订还是局部优化，一律先打回补齐主文件四章，不允许「先评审本轮增量、之后再补齐主文件」。\n - AC-4.4l（用户视角端到端可验证准则）：spec 中每条 FR 必须包含一个「用户视角验证准则」子节（在 FR 定义中以明确小节出现，如「验证准则」或「用户视角验证」），内容必须明确以下三要素：\n 1. **操作者**：谁来验证（默认「陌生用户」，可根据 FR 场景明确为「首次使用者」「运维者」等）。\n 2. **操作路径与时间约束**：在什么入口（web 页面路由、CLI 命令）做什么操作，多长时间内完成。\n 3. **可观测产出**：看到什么具体、可验证、可数的内容作为「FR 通过」的依据，产出必须可量化（数量、字数、字段、状态之一）。“页面能打开”、“列表能显示”、“接口能访问”不构成可观测产出。\n 反例（页面级描述，不过关）：「FR-X 支持显示知识列表」、「FR-X 提供项目详情页」。\n 正例（用户视角终态，过关）：「陌生用户上传 PDF 后，5 分钟内在 web 端能看到至少 3 个结构化知识点，每个知识点有标题（≤ 20 字）+ 描述（≥ 50 字）+ 来源 PDF 文件名」。\n - AC-4.4m（验证准则语义判定）：FR-02-pre Pre-Gate 除检查四章外，必须额外对每条 FR 的「用户视角验证准则」做 LLM 语义判定，区分「页面级描述」与「用户视角端到端」。判定依据：是否包含明确操作者、是否包含可补充的操作路径与时间约束、是否包含可量化产出。任一要素缺失 = 页面级描述 = 未通过。禁止用关键词匹配、字数阈值、正则伪装语义理解；正则仅作为定位辅助。\n - AC-4.4n（FR 验证准则不合规的处理）：任一 FR 缺失「用户视角验证准则」子节或 LLM 判定为页面级描述时，Pre-Gate 不通过，打回 FR-01 Spec 阶段。返工产出不合规 FR 缺口清单（FR 编号 + 缺失要素 + 需补充的验证准则示例）。由 PM 角色补全验证准则后重新进入 Pre-Gate。本 AC 适用于所有受管项目主文件与 SEVO 自身主文件。\n - AC-4.4o（过渡期处理）：AC-4.4l/m/n 生效后，现有 spec 中未补全「用户视角验证准则」的 FR 登记到§9.8「待补 spec 章节（已知违反清单）」类似表格中，由后续 wave 补齐；代码实现阶段允许补齐与实现并行，但在 FR-36 Verify-With-Real-Data Gate 中涉及的受检核心 FR 必须已补齐验证准则，否则 FR-36 门禁不通过。\n\n### FR-02 Spec Review Gate\n\n- **输入**：需求规格包（Spec Package）、FR-02-pre 通过的 Pre-Gate 报告、路由结果、适用规则。\n- **处理**：先消费 FR-02-pre 输出的 Mandatory Spec Sections Pre-Gate 报告作为前置门禁结果；Pre-Gate 通过后再由多维度独立评审检查规格质量，并给出通过、有条件通过、不通过三档结论。评审维度：\n - 产品维度：spec 是否解决了用户真正的问题、需求是否完整、用户人群和痛点是否清晰。\n - 技术维度：spec 描述的功能是否技术可行、是否存在技术风险或不可实现的描述。\n - 体验维度（有 Web/UI 时）：spec 描述的交互是否合理、用户体验流是否完整、是否符合小白用户预期。纯后端/CLI 项目可省略。\n - 质量维度：规格完整性、阶段隔离、概念架构完整度、边界清晰度、验收标准质量。\n- **输出**：规格评审包（Spec Review Bundle），顶部引用 Pre-Gate 结论，包含各维度结论、问题清单、修复要求、通过条件和是否允许进入 Contract 的门禁结果。\n- **执行阶段**：Spec Review Gate。先执行 FR-02-pre Mandatory Spec Sections Pre-Gate；Pre-Gate 通过后，再并行执行产品维度、技术维度、体验维度（可选）、质量维度评审。禁止规格作者自审。\n- **门禁判定**：Pre-Gate 通过 + 各维度共同放行。Pre-Gate 任一项不通过直接返工 FR-01；Pre-Gate 通过后任一维度结论为有条件通过或不通过时阻断，直到修复并复审通过。纯后端/CLI 项目可按项目配置省略体验维度。\n- **验收标准**：\n - AC-4.5：Spec 进入 Contract 前必须先经过独立评审，默认禁止规格作者自审。\n - AC-4.5a：Spec Review Gate 至少覆盖产品、技术、质量三个维度；涉及 Web/UI 的任务必须增加体验维度。\n - AC-4.5b：任一维度结论为有条件通过或不通过时，门禁阻断，直到对应维度问题修复并复审通过。\n - AC-4.6：评审结果至少区分通过、有条件通过、不通过三档，并显式记录阻断问题。\n - AC-4.7：有条件通过和不通过都会阻断进入 Contract，直到阻断问题完成修复并复审通过。\n - AC-4.8：评审结论必须指向具体规格内容、缺口或越界点，不能只给抽象评价。\n - AC-4.9：Spec 必须包含四个独立章节，缺任一个即判定为“不通过”：\n 1. 用户人群（谁用、什么场景、什么设备）\n 2. 痛点（用户现在怎么解决这个问题、哪里痛）\n 3. 原始需求（用户要什么，用人话说）\n 4. 用户体验流（完整的用户操作步骤，从打开到完成）\n - AC-4.9a：四章节必须位于「功能需求」之前，不得散落在 FR 内部或附录中。\n - AC-4.9b：四章存在性、顺序、内容语义判定三项检查由 FR-02-pre Mandatory Spec Sections Pre-Gate 执行；本门禁必须在评审包顶部引用 Pre-Gate 报告，并以 Pre-Gate 通过作为本门禁启动主体评审的强制前提。\n - AC-4.9c：四章内容必须由 LLM 做语义质量判定，禁止用关键词匹配或字数阈值伪装语义理解。语义判定的最低标准：用户人群说清「谁、什么场景、什么设备」；痛点说清「现在怎么解决、哪里痛」；原始需求用用户口语写明「要什么」；用户体验流写明「从入口到产出的完整步骤」。任一章语义不达标判定为「不通过」。\n - AC-4.9d：Pre-Gate 任一项不通过时，spec-review-gate 直接返工 FR-01，不得进入产品/技术/质量/体验任一维度评审，避免无效消耗 Agent 资源。返工修复后必须重新跑完整 Pre-Gate + 主体评审。\n - AC-4.9e：FR 章节中的每个 FR 必须能在四章中找到至少一条来源（用户人群、痛点或体验流条目）。找不到来源的 FR，spec-review-gate 产品维度直接判定为「不通过」并标注「孤立 FR」。\n\n### FR-02a Test Case Authoring\n\n- **触发时机**：Spec Review Gate（FR-02）通过后，与 Contract（FR-03）并行启动。\n- **输入**：已通过 Spec Review Gate 的需求规格包。\n- **处理**：基于需求规格中的验收标准（AC）编写测试用例，产出独立的测试用例文档。\n- **输出**：测试用例文档（独立交付物）。\n- **执行阶段**：Test Case Authoring。\n- **并行关系**：与 FR-03 Contract 并行执行，不互相阻塞。\n- **验收标准**：\n - AC-4.8a：每个高优先级 FR 的验收标准至少有一条对应测试用例。\n - AC-4.8b：测试用例作为独立文档交付，不写入需求规格或契约包。\n - AC-4.8c：初期允许极简形态，后期可专项优化扩展。\n\n### FR-02b UX Acceptance Authoring\n\n- **触发时机**：Spec Review Gate（FR-02）通过后，与 Contract（FR-03）、Test Case Authoring（FR-02a）并行启动。\n- **输入**：已通过 Spec Review Gate 的需求规格包。\n- **处理**：由 UX 角色（ux-01）编写「用户开箱即用视角」评测用例——模拟陌生用户首次使用的完整旅程，产出 markdown 检查清单（非代码测试）。\n- **输出**：UX 开箱即用评测检查清单（独立交付物，存放于项目 docs/ 下）。\n- **执行阶段**：UX Acceptance Authoring。\n- **角色约束**：仅 UX 角色可执行，禁止开发者或产品角色代写。\n- **并行关系**：与 FR-02a Test Case Authoring、FR-03 Contract 并行执行，不互相阻塞。\n- **验收标准**：\n - AC-4.8d：检查清单覆盖零配置安装、首次运行、核心功能体验、错误提示友好度、文档可读性五个维度。\n - AC-4.8e：检查清单作为独立 markdown 文档交付，不写入需求规格或契约包。\n - AC-4.8f：检查清单中每个检查项有明确的通过/失败判定标准。\n - AC-4.8g：产出工件记录 authorRole 为 ux，可追溯到执行角色。\n\n### FR-02c Commercial Acceptance Authoring\n\n- **触发时机**：Spec Review Gate（FR-02）通过后，与 Contract（FR-03）、Test Case Authoring（FR-02a）、UX Acceptance Authoring（FR-02b）并行启动。\n- **输入**：已通过 Spec Review Gate 的需求规格包。\n- **处理**：由 PM 角色（pm-01）编写「商用视角」评测用例——验证商用就绪标准，产出 markdown 检查清单（非代码测试）。\n- **输出**：商用评测检查清单（独立交付物，存放于项目 docs/ 下）。\n- **执行阶段**：Commercial Acceptance Authoring。\n- **角色约束**：仅 Product 角色可执行，禁止开发者或 UX 角色代写。\n- **并行关系**：与 FR-02a、FR-02b、FR-03 并行执行，不互相阻塞。\n- **验收标准**：\n - AC-4.8h：检查清单覆盖 npm 包完整性、README 营销质量、依赖安全、许可证合规、发布三平台覆盖、版本号一致性六个维度。\n - AC-4.8i：检查清单作为独立 markdown 文档交付，不写入需求规格或契约包。\n - AC-4.8j：检查清单中每个检查项有明确的通过/失败判定标准。\n - AC-4.8k：产出工件记录 authorRole 为 product，可追溯到执行角色。\n\n### FR-02d UX Interaction Design\n\n- **触发条件**：任务涉及 Web 页面、用户交互界面、导航结构变更时触发；纯后端/CLI/SDK 不触发。由路由阶段自动判定。\n- **触发时机**：Spec Review Gate（FR-02）通过后，与 Contract（FR-03）、Test Case Authoring（FR-02a）、UX Acceptance Authoring（FR-02b）、Commercial Acceptance Authoring（FR-02c）并行启动。\n- **输入**：已通过 Spec Review Gate 的需求规格包。\n- **处理**：由 UX 角色站在小白用户视角设计页面交互方案——页面布局、导航结构、操作流程、状态流转、信息层级。\n- **输出**：UX 交互设计文档（存放于项目 docs/ux/ 下）。\n- **执行阶段**：UX Interaction Design。\n- **角色约束**：仅 UX 角色可执行，禁止开发者或产品角色代执行。\n- **并行关系**：与 FR-02a、FR-02b、FR-02c、FR-03、FR-02e 并行执行，不互相阻塞。\n- **完成后流向**：UX 交互设计完成后，由 PM 角色评审设计方案（评审维度：设计是否解决了 spec 定义的用户问题、操作流程是否完整、是否遗漏关键场景）。PM 评审通过后，UX 设计文档作为 Contract Review Gate（FR-04）和 Implement（FR-05）的输入。\n- **验收标准**：\n - AC-4.8l：路由阶段自动判断任务是否涉及 Web/UI，产出“是否需要 UX Interaction Design”布尔值。\n - AC-4.8m：设计必须从小白用户视角出发，覆盖完整操作流程（从打开页面到完成核心任务）。\n - AC-4.8n：UX 设计文档是 Implement（FR-05）的强制输入，编码 prompt 必须引用该文档路径。\n - AC-4.8o：与其他并行阶段不阻塞，完成后经 PM 评审通过后进入 Contract Review Gate。\n - AC-4.8p：产出工件记录 authorRole 为 ux，可追溯到执行角色。\n - AC-4.8p2：UX 交互设计完成后必须经过 PM 角色评审，PM 评审不通过则打回 UX 角色修改，修改后重新提交 PM 评审。\n\n### FR-02e Architecture Design\n\n- **触发条件**：任务涉及前后端复杂功能、数据模型变化、多模块协作、新增 API 接口时触发；单文件小改动不触发。由路由阶段自动判定。\n- **触发时机**：Spec Review Gate（FR-02）通过后，与 Contract（FR-03）、Test Case Authoring（FR-02a）、UX Interaction Design（FR-02d）并行启动。\n- **输入**：已通过 Spec Review Gate 的需求规格包 + UX 交互设计文档（如有，作为参考）。\n- **处理**：由 SA 角色产出技术架构设计——API 接口定义、数据模型、模块交互、前后端职责划分。\n- **输出**：架构详设文档（存放于项目 docs/architecture/ 下）。\n- **执行阶段**：Architecture Design。\n- **角色约束**：仅 SA 角色可执行，禁止开发者或产品角色代执行。\n- **并行关系**：与 FR-02a、FR-02b、FR-02c、FR-03、FR-02d 并行执行，不互相阻塞。如果同时有 UX Interaction Design，应参考 UX 设计文档。\n- **完成后流向**：产出的架构详设文档作为 Contract Review Gate（FR-04）的输入之一。\n- **验收标准**：\n - AC-4.8q：路由阶段自动判断任务是否涉及复杂功能/数据模型变化/多模块协作，产出“是否需要 Architecture Design”布尔值。\n - AC-4.8r：必须定义清晰的 API 接口（路径、方法、请求/响应结构、错误码）。\n - AC-4.8s：架构设计文档是 Implement（FR-05）的强制输入，编码 prompt 必须引用该文档路径。\n - AC-4.8t：如果同时有 UX Interaction Design，架构设计应参考 UX 设计文档中的页面结构和交互流程。\n - AC-4.8u：产出工件记录 authorRole 为 sa，可追溯到执行角色。\n\n### FR-03 Contract\n\n- **输入**：已通过 Spec Review Gate 的需求规格包。\n- **处理**：把需求翻译为可执行的架构方案、实现边界、阶段门禁、工作包拆分和交付顺序。\n- **输出**：契约包（Contract Package），包含架构方案、实现边界、工作包拆分（含 Task 级细粒度分解）和交付顺序。\n- **执行阶段**：Contract。\n- **审查阶段**：Contract Review Gate（四方会审）。\n- **验收标准**：\n - AC-4.9：每个高优先级 FR 都能在契约中找到对应实现承接点。\n - AC-4.10：工作包拆分后可分派、可验收、可追责。\n - AC-4.11：关键边界、风险和依赖被显式记录。\n - AC-4.12：契约包能直接驱动 Implement，不需要口头补规则。\n - AC-4.12a：每个工作包内部拆分为 Task 列表，每个 Task 粒度控制在 2-5 分钟，包含精确文件路径和预期变更描述。\n\n### FR-04 Contract Review Gate\n\n- **输入**：契约包（Contract Package）、关键架构决策、评审规则、UX 交互设计文档（如有 FR-02d 产出）、架构详设文档（如有 FR-02e 产出）。\n- **处理**：由产品视角、开发视角、质量视角、体验视角四方并行会审，检查需求承接完整度、实现可行性、决策严谨性、交互合理性、扩展边界和交付波次，并形成是否允许进入 Implement 的门禁结论。体验视角需核对契约与 UX 交互设计文档的一致性；开发视角需核对契约与架构详设文档的一致性。纯后端/CLI 项目可按项目配置省略 UX 视角，此时退化为三方会审。\n- **输出**：会审包（Contract Review Bundle），包含四方评审结论、阻断问题、修复要求、复审范围和是否允许进入 Implement 的门禁结果。\n- **执行阶段**：Contract Review Gate，四方并行评审——产品维度（需求承接完整度）、开发维度（实现可行性）、质量维度（决策严谨性与质量规范）、体验维度（交互合理性、用户流程完整性、可用性）。\n- **门禁判定**：四方共同放行。任一方结论为有条件通过或不通过时阻断，谁的问题未过审由谁继续复审，四方全部通过后方可进入 Implement。\n- **验收标准**：\n - AC-4.13：进入 Implement 前必须完成四方并行会审，缺任一评审视角都不能放行。纯后端/CLI 项目可配置省略体验视角，此时退化为三方会审。\n - AC-4.14：四方评审至少覆盖产品完整度、开发可行性、质量严谨性和交互体验四个视角。\n - AC-4.15：任一评审结论为有条件通过或不通过时，Implement 必须被阻断，直到对应问题修复并复审通过。\n - AC-4.16：会审产出必须明确记录每个问题对应的责任工件、修复项和复审责任方。\n - AC-4.17：项目配置中 hasUI=false 时，体验视角可省略，退化为三方会审。\n\n### FR-05 Implement\n\n- **输入**：契约包、工作包、阶段规则、验收标准、UX 交互设计文档（如有 FR-02d 产出，强制引用）、架构详设文档（如有 FR-02e 产出，强制引用）。\n- **处理**：按工作包逐 Task 执行实现，遵循 TDD 循环（先写覆盖目标行为的失败测试 → 实现至测试通过 → 重构），限制改动边界，记录证据，形成可审计的变更集。编码 prompt 必须引用 UX 交互设计文档和架构详设文档的路径（如有），确保实现与设计一致。\n- **输出**：实现包（Implementation Bundle），包含代码变更、执行记录、测试结果和偏差说明。\n- **执行阶段**：Implement。\n- **审查阶段**：Review（独立审查）。\n- **验收标准**：\n - AC-4.17：每个工作包都有明确输入、输出、允许改动范围和验收项。\n - AC-4.18：实现过程产出证据，不允许只交代码不交说明。\n - AC-4.19：完成判定以验收结果为准，不以 Agent 自报完成为准。\n - AC-4.20：实现结果能追溯到对应 FR 和 Contract 决策。\n - AC-4.20a：每个工作包的实现遵循 TDD 循环：先写覆盖目标行为的失败测试，再写实现使测试通过，最后重构。\n - AC-4.20b：未经测试覆盖的代码变更不允许通过 Review 阶段。\n - AC-4.20f：编码 Agent 只能实现 spec 中明确定义的 FR 和 AC。觉得某功能有价值，必须先提需求变更请求，经 Specify 阶段评审写入 spec 后才能实现。\n - AC-4.20g：当存在 FR-02d 产出的 UX 交互设计文档时，编码 prompt 必须引用该文档路径，实现必须符合 UX 设计方案中定义的页面布局、导航结构和操作流程。\n - AC-4.20h：当存在 FR-02e 产出的架构详设文档时，编码 prompt 必须引用该文档路径，实现必须符合架构设计中定义的 API 接口、数据模型和模块职责划分。\n\n### FR-05a Systematic Debugging\n\n- **触发时机**：Implement（FR-05）执行过程中或完成后发现非预期行为时触发，作为 Implement 和 Review 之间的可选活动。\n- **输入**：实现包（或部分实现结果）、失败测试、异常日志、非预期行为描述。\n- **处理**：按四阶段框架执行系统化调试——复现（在可控条件下稳定重现问题）→ 定位（缩小问题范围至具体模块或代码路径）→ 分析（确定根因，排除表面症状）→ 验证（修复后确认问题消除且未引入新问题）。\n- **输出**：调试记录（Debugging Record），包含问题描述、根因分析、修复方案和验证结果。\n- **执行阶段**：Systematic Debugging（Implement 内部可选活动）。\n- **验收标准**：\n - AC-4.20c：调试过程遵循复现→定位→分析→验证四阶段，禁止跳过复现直接猜测修复。\n - AC-4.20d：调试结论基于证据（日志、测试结果、代码路径分析），不基于主观推测。\n - AC-4.20e：修复后的验证必须覆盖原始失败场景和相关回归路径。\n\n### FR-06 Review\n\n- **输入**：实现包。审计时参考 FR-02a 产出的测试用例文档（仅做参考，不代表全部审计项）、UX 交互设计文档（如有 FR-02d 产出）、架构详设文档（如有 FR-02e 产出）。\n- **处理**：由独立审查阶段三方并行评审，审查代码质量、需求一致性、架构符合度、边界遵守情况和高风险点。\n- **输出**：评审包（Review Bundle），包含各维度结论、问题清单、修复要求和通过条件。\n- **执行阶段**：Review，三方独立评审：\n - PM/产品维度：功能完整性、需求一致性确认。\n - 质量维度：代码质量、安全性、规范遵守。\n - SA/架构维度：实现是否符合架构详设文档（如有 FR-02e 产出），API 接口是否按设计实现，数据模型是否一致。无架构详设文档的任务，架构维度自动跳过。\n- **门禁判定**：三方共同放行。任一方结论为有条件通过或不通过时阻断，直到对应问题修复并复审通过。\n- **体验验收说明**：用户体验的验收由独立的 UX Acceptance 阶段（FR-06c）负责，不在 Code Review 中重复覆盖。\n- **验收标准**：\n - AC-4.21：评审者与实现者职责分离。\n - AC-4.22：评审结果至少区分通过、有条件通过、不通过。\n - AC-4.23：每个阻断问题都能指向具体工件和修复项。\n - AC-4.24：通过结论建立在证据上，不建立在主观判断上。\n - AC-4.24k：Review 阶段必须包含 spec-code 覆盖检查——从需求规格书提取全量 AC，逐条比对实现包中的代码覆盖情况，产出 AC 覆盖矩阵（AC 编号 / 覆盖状态 / 对应代码位置）。\n - AC-4.24l：AC 覆盖矩阵中任何 AC 状态为未实现或部分实现时，Review 结论必须为不通过（blocker）。代码实现只能比需求定义多，不能比需求定义少。\n - AC-4.24m：类型定义存在不等于已实现。AC 覆盖判定必须同时检查类型定义、逻辑代码和测试三层，缺任何一层视为部分实现。\n - AC-4.24n：ImplementationReviewGate 作为 Review 阶段的程序化门禁，自动从 Spec Package 提取 AC、从 Implementation Bundle 提取覆盖证据，覆盖率低于 100% 时门禁结论为 rejected。\n - AC-4.24n2：Review 阶段必须检查：代码中每个功能模块是否都能追溯到 spec 中的 FR/AC 编号。无法追溯的代码视为伪需求，必须删除或补充 spec 定义后才能通过 Review。\n - AC-4.24n3：AC 覆盖扫描范围必须包含项目全部源码目录（src/、web/、plugin/、scripts/ 等），不能只扫部分目录。扫描范围由项目配置中的 sourceRoots 字段定义，默认值为项目根目录下所有包含源码的子目录。Review 报告中必须列出实际扫描的目录清单，遗漏目录视为 Review 不通过。\n - AC-4.24n4：当存在 FR-02e 产出的架构详设文档时，SA/架构维度必须逐项核对 API 接口实现与设计文档的一致性（路径、方法、请求/响应结构），不一致则判定为不通过。\n - AC-4.24n5：无架构详设文档的任务，SA/架构维度自动跳过，不阻断 Review 流程。\n - AC-4.24n6：Implementation Bundle 中每个 execution 的 allowedScope 必须精确到 AC 级别（如 AC-4.1、AC-4.2），不允许只声明 FR ID（如 FR-01）。仅声明 FR ID 的覆盖判定为 partial，产出 blocker finding。\n - AC-4.24n7：ImplementationReviewGate 在执行覆盖检查时，必须自动触发 L2 语义扫描（l2-ac-semantic-scanner），逐条验证 spec AC 是否有对应实现代码且逻辑正确。禁止仅依赖 allowedScope 自我声明作为覆盖证据。\n - AC-4.24n8：Review 结果必须包含 AC 覆盖矩阵，每条 AC 的覆盖判定包含三层检查：类型定义（接口/类型声明存在）、逻辑代码（业务逻辑实现存在且语义匹配 AC 描述）、测试（对应测试用例存在且覆盖核心路径）。三层全部通过才判定为 covered，缺任何一层判定为 partial。\n - AC-4.24n9：Pipeline 在 Review 阶段通过后、进入 Verify 阶段前，自动触发 Tiered Scan（L1→L2→L3 级联扫描）。扫描由 PipelineEngine 自动编排，无需编排者手动触发。\n - AC-4.24n10：Tiered Scan 任一必需层未产出明确 pass 结论时，pipeline 阻断，不允许进入 Verify 阶段。阻断条件至少包括：L2 扫描结果中 spec-code 覆盖率低于 100%、L1/L2/L3 任一层执行失败、扫描报告缺失或扫描流程异常中断。阻断时产出未覆盖 AC 清单或失败原因和修复建议，触发 Review Fix Loop（FR-06a）。\n - AC-4.24n11：当 L2 语义扫描因 LLM 不可用、超时或重试耗尽，导致全部 AC 最终状态为 `needs-review` 且 `coveredCount = 0` 时，Tiered Scan 结论必须为 `needs-review`/`failed`，不得判定为 pass，更不得放行进入 Verify。\n\n### FR-06a Review Fix Loop\n\n- **触发时机**：Review（FR-06）或 Contract Review Gate（FR-04）产出评审包且结论为有条件通过或不通过时自动触发。\n- **输入**：评审包（Review Bundle 或 Contract Review Bundle），包含问题清单。\n- **处理**：\n 1. 自动解析评审报告，提取结构化问题清单，每个问题标注严重级别（P0/P1/P2/P3）、关联的原始 FR、问题所在工件和修复建议。\n 2. P0 和 P1 问题自动生成修复任务卡片（Fix Task），关联原 FR 流程实例、评审报告和问题条目。P2/P3 问题记录待办，不阻断当前批次。\n 3. 修复任务按优先级排入待办队列（P0 优先于 P1），可被空闲 Agent 认领执行。\n 4. 修复任务完成后，自动触发原评审维度对修复范围做定向复验（Targeted Revalidation），复验范围限定为修复涉及的工件和关联影响面，不重跑全量评审。\n 5. 复验通过 → 对应问题关闭 → 系统重新评估门禁放行条件（所有 P0 关闭且 P1 关闭或豁免时放行）。复验不通过 → 问题状态回退，继续修复→复验循环。\n 6. 全链路状态（评审报告 → 问题清单 → 修复任务状态 → 复验结果）在驾驶舱实时可见。\n- **输出**：问题清单（Review Issue List）、修复任务卡片（Fix Task）、复验结论（Revalidation Result）。\n- **执行阶段**：Review Fix Loop（Review 和 Contract Review Gate 的内置子流程）。\n- **验收标准**：\n - AC-4.24a：评审结论为有条件通过或不通过时，系统在评审完成后自动解析报告并生成结构化问题清单，无需人工介入。\n - AC-4.24b：问题清单中每个条目包含严重级别（P0/P1/P2/P3）、关联 FR、问题工件定位和修复建议。\n - AC-4.24c：P0 和 P1 问题自动生成修复任务卡片，卡片关联原 FR 流程实例 ID 和评审报告引用。\n - AC-4.24d：修复任务按 P0 > P1 优先级排序进入待办队列，可被 Agent 认领执行。\n - AC-4.24e：修复任务完成后，系统自动触发原评审维度对修复范围做定向复验，复验范围不超出修复涉及的工件及其关联影响面。\n - AC-4.24f：复验通过时对应问题自动关闭；复验不通过时问题状态回退，修复→复验循环继续，直到通过或人工干预终止。\n - AC-4.24g：所有 P0 问题关闭且所有 P1 问题关闭或经人工豁免后，门禁自动重新评估并放行。\n - AC-4.24h：评审报告、问题清单、修复任务状态、复验结果的全链路状态在驾驶舱实时可见。\n - AC-4.24i：修复→复验循环有最大轮次上限（默认 3 轮），超限后升级为人工介入，防止无限循环。\n - AC-4.24j：P2/P3 问题记录为待办项，不阻断当前门禁放行，但纳入后续迭代的输入。\n\n### FR-06b Smoke Test\n\n- **触发时机**：Review（FR-06）通过后自动触发，在进入 Regression 之前执行。\n- **输入**：通过 Review 的实现包、FR-02a 产出的测试用例文档。\n- **处理**：编码 Agent 在实现环境中执行 smoke test，验证核心功能路径可用、构建产物完整、关键入口无崩溃。\n- **输出**：Smoke Test 结果（Smoke Test Result），包含测试执行记录、通过/失败状态和失败原因。\n- **执行阶段**：Smoke Test。\n- **角色约束**：由 review 角色执行。\n- **验收标准**：\n - AC-4.24o：Review 通过后，PipelineEngine 自动推进到 Smoke Test 阶段，无需主会话人肉触发。\n - AC-4.24p：Smoke Test 覆盖核心功能路径、构建产物完整性和关键入口无崩溃三个维度。\n - AC-4.24q：Smoke Test 失败时阻断后续阶段，结果中明确列出失败项和复现步骤。\n\n### FR-06c UX Acceptance\n\n- **触发时机**：Smoke Test（FR-06b）通过后自动触发，与 PM Commercial Review（FR-06d）并行执行。\n- **输入**：通过 Smoke Test 的实现包、FR-02b 产出的 UX 开箱即用评测检查清单。\n- **处理**：由 UX 角色（ux-01）按 FR-02b 产出的检查清单执行视觉验收——模拟陌生用户首次使用，逐项检查零配置安装、首次运行、核心功能体验、错误提示友好度、文档可读性。\n- **输出**：UX 验收结果（UX Acceptance Result），包含逐项通过/失败状态、截图证据和改进建议。\n- **执行阶段**：UX Acceptance。\n- **角色约束**：仅 UX 角色可执行，禁止开发者或产品角色代执行。\n- **并行关系**：与 FR-06d PM Commercial Review 并行执行，两者均通过后方可进入 Regression。\n- **验收标准**：\n - AC-4.24r：Smoke Test 通过后，PipelineEngine 自动推进到 UX Acceptance 阶段，无需主会话人肉触发。\n - AC-4.24s：UX 验收按 FR-02b 产出的检查清单逐项执行，每项有明确通过/失败判定。\n - AC-4.24t：UX 验收失败时阻断进入 Regression，结果中列出失败项和改进建议。\n - AC-4.24u：产出工件记录 authorRole 为 ux，可追溯到执行角色。\n - AC-4.24u2：UX 验收阶段的浏览器操作步骤必须产出可复用的标准操作手册（SOP），包含页面导航路径、交互步骤、预期结果和截图位置。SOP 纳入项目 docs/ 目录，后续迭代的 UX 验收可直接复用或增量更新，不需要从零编写。\n - AC-4.24u3（UX 验收自检清单）：UX 验收报告必须包含「UX 验收自检清单」专节，列出以下全部检查项及其通过与否；任一项不通过 = UX 验收不通过，阻断进入 PM Commercial Review 与 Regression：\n 1. **截图哈希独立**：UX 验收产出的所有截图文件哈希（SHA-256）必须两两不同；出现重复哈希 = 浏览器工具异常或页面未加载完成，判定为自检失败。\n 2. **浏览器 console 错误**：验收全程不得出现 ERROR 级别日志（排除项目 spec 明确允许的例外）。warning 级别不造成自检失败但需在报告中折叠列出。\n 3. **关键页面主操作可完成**：项目主要 web 页面必须能完成「陌生用户最关键的一个操作」（如 KIVO：导入 PDF → 看到知识点；SEVO Web：触发流水线 → 看到状态推进），主操作的识别以 spec 中指定的核心 FR 为准。主操作中途失败、路径中断、需要人手干预才能跳过某步，都判定为自检失败。\n 4. **页面不是空状态与默认模板**：主操作路径上的关键页面（列表页、详情页、产出页）不得以「暂无数据」「请先初始化」「demo 占位」「示例数据」作为验收通过依据；需以真实导入材料产生的内容作为验证依据（与 FR-36 Verify-With-Real-Data Gate 联动）。LLM 对截图内容做语义判定。\n 5. **交互响应可感知**：点击、提交、跳转等主要交互后 2 秒内页面状态可感知（结果加载、loading 提示、跳转发生）；点击后无任何可感知反馈超过 2 秒 = 自检失败。\n 6. **不出现 404 / 500 / 白屏**：验收路径上不得跳转到 404、500、白屏、未授权页面。\n 报告要求：UX 验收报告中明确列出「自检通过项」与「自检失败项」两部分，失败项需含具体证据（截图路径、console 日志片段、失败位置描述）。缺少「自检清单」章节或任一项检查未覆盖 = UX 验收未完成，不予通过。\n\n### FR-06d PM Commercial Review\n\n- **触发时机**：Smoke Test（FR-06b）通过后自动触发，与 UX Acceptance（FR-06c）并行执行。\n- **输入**：通过 Smoke Test 的实现包、FR-02c 产出的商用评测检查清单、README.md、package.json。\n- **处理**：由 PM 角色（pm-01）执行商用就绪评审——陌生用户开箱即用验证、spec-code 一致性检查、README 营销质量评估。\n- **输出**：PM 商用评审结果（PM Commercial Review Result），包含逐项通过/失败状态、spec-code 覆盖矩阵和改进建议。\n- **执行阶段**：PM Commercial Review。\n- **角色约束**：仅 Product 角色可执行，禁止开发者或 UX 角色代执行。\n- **并行关系**：与 FR-06c UX Acceptance 并行执行，两者均通过后方可进入 Regression。\n- **验收标准**：\n - AC-4.24v：Smoke Test 通过后，PipelineEngine 自动推进到 PM Commercial Review 阶段，无需主会话人肉触发。\n - AC-4.24w：PM 评审覆盖陌生用户开箱即用验证、spec-code 一致性、README 营销质量三个维度。\n - AC-4.24x：PM 评审失败时阻断进入 Regression，结果中列出失败项和修复建议。\n - AC-4.24y：产出工件记录 authorRole 为 product，可追溯到执行角色。\n\n### FR-06e Deployment View Review Gate（部署视图审查门禁）\n\n- **触发条件**：Review（FR-06）阶段检测到 diff 涉及以下内容时自动触发：\n - 包的 `exports` 字段变更\n - 公开 API 签名变更（函数名、参数、返回类型）\n - 包的 major/minor version bump\n- **输入**：当前 diff、项目根目录的 `consumers.json` 注册表。\n- **处理**：\n 1. 检查项目根目录是否存在 `consumers.json`。不存在则跳过本门禁（不阻断）。\n 2. 读取 `consumers.json` 中注册的所有消费者条目。\n 3. 对每个消费者执行其声明的 `loadTest` 命令，验证消费者在当前代码变更后仍能正常加载/运行。\n 4. 任何一个 loadTest 失败 = P0 阻断，Review 不通过。\n 5. 支持 `--skip-deployment-check` 参数用于紧急 hotfix 场景，跳过时必须在 review 报告中标注跳过原因。\n- **consumers.json 格式**：\n ```json\n {\n \"consumers\": [\n { \"path\": \"hooks/kivo-intent-injection/handler.js\", \"type\": \"hook\", \"loadTest\": \"node -e \\\"require('')\\\"\" },\n { \"path\": \"scripts/memory-promote.sh\", \"type\": \"cron\", \"loadTest\": \"bash -n \" }\n ]\n }\n ```\n 其中 `` 在执行时替换为消费者的实际路径。`type` 为语义标签（hook / cron / script / service 等），用于报告分类，不影响执行逻辑。\n- **输出**：部署视图审查结果，写入 review 报告的独立章节「部署视图」。\n- **执行阶段**：Review（FR-06 的内置子检查）。\n- **设计约束**：轻量实现——不做 AST 分析、不做依赖图谱、不做自动发现。注册表 + load test，仅此而已。\n- **验收标准**：\n - AC-4.24z1：`consumers.json` 不存在时，部署视图门禁自动跳过，不阻断 Review 流程。\n - AC-4.24z2：loadTest 失败时，输出具体错误信息——包含失败的消费者路径、消费者类型和命令执行的错误输出。\n - AC-4.24z3：新增消费者（hook / cron / script / service 等任何类型）时，必须同步注册到项目的 `consumers.json`。\n - AC-4.24z4：门禁结果写入 review 报告的独立章节「部署视图」，包含每个消费者的检查状态（通过/失败/跳过）。\n - AC-4.24z5：支持 `--skip-deployment-check` 参数跳过本门禁，跳过时 review 报告「部署视图」章节标注跳过原因，供审计追溯。\n\n### FR-07 Regression\n\n- **输入**：通过 Review 的实现包、FR-02a 产出的测试用例文档。\n- **处理**：执行回归检查，确认新增改动没有破坏既有功能、关键路径和基础约束。\n- **输出**：回归包（Regression Bundle）。\n- **执行阶段**：Regression。\n- **审查阶段**：Regression Review（审查回归结果完整性和覆盖度）。\n- **验收标准**：\n - AC-4.25：关键路径有明确回归检查结果。\n - AC-4.26：已修问题附带防复发验证。\n - AC-4.27：回归失败时能定位到受影响范围。\n - AC-4.28：回归结果进入后续 Deploy 与 Verify 的判断依据。\n\n### FR-08 Deploy\n\n- **输入**：通过 Regression 的交付候选版本。\n- **处理**：生成发布制品，绑定版本信息、发布说明和交付目标。\n- **输出**：发布包（Release Artifact）。\n- **执行阶段**：Deploy。\n- **审查阶段**：Deploy Review（确认发布制品与架构方案一致、版本元数据完整）。\n- **验收标准**：\n - AC-4.29：发布产物可识别版本、来源和适用范围。\n - AC-4.30：发布动作与对应 Spec、Contract、Review、Regression 结果可关联。\n - AC-4.31：发布失败不会污染已通过的候选版本。\n - AC-4.32：发布结果可被 Verify 阶段直接消费。\n\n### FR-08a Commercialization Gate（商用化门禁）\n\n- **定位**：Deploy 之前的强制阶段。当项目配置了发布目标（npm、GitHub、ClawHub）时自动触发，确保交付物达到商用级开源标准。\n- **触发条件**：项目存在 `publishTarget` 配置，且目标为 npm、ClawHub、GitHub 之一时，在进入 Deploy 前自动触发。\n- **核心原则**：GitHub 独立仓库推源码（开源可读、可构建），npm 推编译产物（开箱即用）。两条渠道并存，用户既能 `npm install` 直接用，也能 clone 源码自己 build。\n- **输入**：交付候选版本、发布目标配置、项目源码目录、README.md、package.json、tsconfig.json。\n- **处理**：按五层标准逐层检查，任一层不通过则阻断发布。\n\n**第一层：代码清洁度**\n 1. 无硬编码路径（`/root/`、`/home/`、`~/.openclaw/` 等内部路径）。\n 2. 无内部引用（内部 agent 名称、内部 API 地址、内部配置键名）。\n 3. 无调试残留（`console.log` 调试输出、TODO/FIXME/HACK 注释）。\n 4. 无敏感信息（API key、token、密钥文件、.env 文件）。\n 5. 依赖声明完整——package.json 的 dependencies 和 peerDependencies 覆盖所有 import，无遗漏无冗余。\n\n**第二层：包完整性**\n 6. package.json 必填字段完整：name、version、description、author、license、main/exports、bin（如有 CLI）。\n 7. 入口文件指向存在的文件（main/exports/bin 指向的路径必须存在）。\n 8. TypeScript 项目必须有 tsconfig.json，且 `npm run build` 能成功编译。\n 9. .gitignore 排除编译产物（根目录 .js、dist/、node_modules/）。\n 10. .npmignore 或 package.json files 字段正确配置，npm 包只包含编译产物 + 类型声明 + 文档。\n\n**第三层：文档质量**\n 11. README.md 存在且符合营销质量标准（tagline → 痛点 → 优势 → 快速体验 → 场景 → 文档链接）。\n 12. README 同时引导两类用户：npm 用户（`npm install` 快速上手）和源码用户（clone → install → build）。\n 13. 配置项有文档说明（环境变量、配置文件模板、CLI 参数）。\n 14. CHANGELOG.md 或 GitHub Releases 记录版本变更。\n 15. LICENSE 文件存在。\n\n**第四层：可构建性**\n 16. 在干净目录中 `git clone → npm install → npm run build` 能成功完成。\n 17. `npm test` 能通过（如项目有测试）。\n 18. CLI 项目：`npx <包名> --help` 能正常输出。\n\n**第五层：开箱即用**\n 19. `npm install <包名>` 能成功安装。\n 20. 每个核心功能有可验证的首次使用路径，且产出有意义的结果（不是空壳）。\n 21. 需要外部依赖（专用 API key、第三方服务）的功能，有明确的配置引导和错误提示。\n\n- **输出**：商用化门禁结果（Commercialization Gate Result），包含五层检查的逐项通过/失败状态、具体失败原因、修复建议。\n- **执行阶段**：Commercialization Gate（Deploy 前阶段）。\n- **验收标准**：\n - AC-4.32a：存在 `publishTarget` 配置时，系统在 Deploy 前自动触发商用化门禁，无需用户确认。\n - AC-4.32b：系统执行全部五层检查，不允许只做部分检查。\n - AC-4.32c：任一检查项不通过时，发布被阻断，结果中明确列出具体失败原因和修复建议。\n - AC-4.32d：用户可选择跳过该阶段，跳过决定写入 ledger，标注\"用户主动跳过商用化门禁\"。\n - AC-4.32e：不存在 `publishTarget` 配置时，该阶段完全不出现，不影响 Deploy 流程。\n - AC-4.32f：发布目标包含 GitHub 独立仓库时，门禁自动执行独立仓库同步——推送源码（排除编译产物），推送前排除 .gitignore 中定义的文件。\n - AC-4.32g：推送独立仓库前，扫描待推送文件中是否包含敏感内容（.env、API key、密钥文件、内部配置），发现则阻断推送并报告。\n - AC-4.32h：npm publish 和独立仓库同步作为原子操作执行——任一步骤失败则整体回滚。\n - AC-4.32i：GitHub 独立仓库只推源码（TypeScript），编译产物由 .gitignore 排除；npm 包只推编译产物 + 类型声明 + 文档。\n - AC-4.32j：第四层可构建性检查在干净临时目录中执行（模拟陌生用户环境），不依赖开发现场。\n - AC-4.32k：门禁结果包含五层检查的逐项状态，支持增量修复（修复后只重跑失败项，不重跑已通过项）。\n\n\n### FR-09 Verify\n\n- **输入**：发布包。\n- **处理**：在独立、清洁或最小依赖环境中验证功能、关键 NFR 和交付可用性。\n- **输出**：验证包（Verification Bundle）。\n- **执行阶段**：Verify（独立环境验证，与 Implement 阶段执行者分离）。\n- **审查阶段**：Verify Review（确认核心用户路径和交付可用性达标）。\n- **验收标准**：\n - AC-4.33：验证环境不依赖开发现场残留。\n - AC-4.34：验证覆盖核心用户路径和关键非功能指标。\n - AC-4.35：验证结论可明确区分可交付与不可交付。\n - AC-4.36：验证失败会阻断 Ledger 的通过结论。\n - AC-4.36a：Verify 阶段采用默认拒绝策略（deny by default）——没有显式验证证据的 AC 默认判定为未通过。子 Agent 正常返回但未提供验证证据时，该 AC 的验证状态为 failed，不允许因缺少失败信号而默认通过。\n - AC-4.36b：Verify 阶段的验证目标（VerifyTarget）自动从 spec AC 列表派生，每条 AC 生成对应的验证目标。编排者无需手动定义 targets，系统根据 AC 描述自动生成验证步骤和预期结果。\n - AC-4.36c：每条 AC 的验证必须包含实际运行证据——API 调用结果、浏览器截图、数据库查询结果、CLI 输出等可观测产出。tsc 编译通过、npm test 通过不算单条 AC 的验证证据，只能作为 L1 基础检查的一部分。\n - AC-4.36d：验证步骤必须使用真实数据或真实环境产生的数据。禁止使用 mock 数据、seed 数据或硬编码的预期值通过验证。验证环境可以是隔离的，但数据必须通过实际功能流程产生。\n - AC-4.36e：Tiered Scan、编译、测试或其他预检查报告只能作为 Verify 的前置筛查和补充证据，不能替代单条 AC 的运行时验证。若所有 VerifyTarget 都未产出 pass 级运行时证据，则 Verify 总结论必须为 failed。\n\n### FR-10 Ledger\n\n- **输入**：FR 流程实例 ID、Spec Package、Spec Review Bundle、Contract Package、Contract Review Bundle、Implementation Bundle、Review Bundle、Regression Bundle、Release Artifact、Verification Bundle。\n- **处理**：生成交付记录，串起版本、日期、范围、证据、问题、结论和经验沉淀。每条 Ledger Entry 必须关联到对应的 FR 流程实例 ID。\n- **输出**：交付账本条目（Ledger Entry）。\n- **执行阶段**：Ledger（系统自动汇总）。\n- **审查阶段**：Ledger Review，产品维度（确认交付范围和结论准确）和架构维度（确认证据链完整和经验沉淀质量）。\n- **验收标准**：\n - AC-4.37：账本条目能追溯到本轮所有关键工件。\n - AC-4.38：账本记录交付结论、责任边界和后续动作。\n - AC-4.39：经验沉淀可被后续任务复用。\n - AC-4.40：没有 Ledger Entry 的交付不算流程闭环。\n - AC-4.40a：Ledger Entry 中的经验沉淀（lessons learned）必须在后续 pipeline 的 Specify 阶段被自动检索和注入。PipelineEngine 在启动 Specify 阶段时，自动查询同项目历史 Ledger Entry 的经验字段，将相关经验作为上下文注入给 Specify 执行者，避免重复踩坑。注入内容按相关性排序，最多注入最近 10 条。\n\n### FR-11 Proactive Clarification\n\n- **定位**：跨阶段机制。在 Spec、Contract、Implement 三个阶段内建模糊检测与主动澄清能力，确保歧义在产生阶段就地消解，而非流入下游造成返工。\n- **触发条件**：任一阶段执行过程中，检测到以下模糊信号之一即触发澄清流程：\n - 验收标准缺失或不可验证。\n - 边界条件未定义（输入范围、异常路径、并发场景）。\n - 术语首次出现但未给出定义。\n - 依赖未声明（上游工件、外部服务、运行时假设）。\n - 接口契约不完整（参数、返回值、错误码缺失）。\n - 数据流向不明（谁产出、谁消费、格式是什么）。\n - 性能或资源约束缺失（超时、并发上限、存储配额）。\n - Spec 与 Contract 之间存在矛盾或不一致。\n- **澄清类型分类**：每个澄清问题必须标注类型，便于收敛后按知识类型沉淀：\n - 纠偏（correction）：已有描述与事实或意图不符。\n - 方法（methodology）：如何做、用什么方法。\n - 决策（decision）：多个可选方案需要取舍。\n - 边界（boundary）：范围、限制、不做什么。\n - 经验（experience）：历史教训、已知陷阱。\n - 元认知（meta）：关于流程本身的反思。\n\n#### FR-11.1 Spec 阶段澄清\n\n- **输入**：正在编写或已产出的 Spec Package。\n- **处理**：\n 1. 扫描 Spec 内容，检测模糊信号（验收标准缺失、边界未定义、术语未解释、依赖未声明）。\n 2. 对每个模糊点生成结构化澄清问题，包含：问题描述、模糊类型、影响范围、建议选项（如有）。\n 3. 将澄清问题提交给需求来源方（用户或上游 Agent）。\n 4. 收到澄清回复后，将收敛结论写回 Spec Package 对应位置。\n- **输出**：澄清记录（Clarification Record）+ 更新后的 Spec Package。\n- **验收标准**：\n - AC-4.41：Spec 产出前，所有被检测到的模糊点都已生成澄清问题或标注为已知风险。\n - AC-4.42：澄清问题包含类型标签、影响范围和上下文引用，不是孤立提问。\n - AC-4.43：澄清收敛后的结论直接写入 Spec Package，不留在对话或临时文件中。\n - AC-4.44：澄清收敛结论按知识类型沉淀（纠偏→事实、决策→ADR 候选、边界→约束条件、方法→方法论记录、经验→experience 知识（沉淀到经验库 / lessons learned）、元认知→meta 知识（沉淀到方法论 / 流程改进建议））。\n\n#### FR-11.2 Contract 阶段澄清\n\n- **输入**：正在编写或已产出的 Contract Package、关联的 Spec Package。\n- **处理**：\n 1. 扫描技术方案，检测模糊信号（接口未定义、数据流不明、性能约束缺失、模块职责重叠）。\n 2. 对每个模糊点生成结构化澄清问题。\n 3. 区分澄清对象：技术层面的模糊由架构阶段内部消解；需求层面的模糊上报给 Spec 来源方。\n 4. 收到澄清回复后，将技术决策写入 ADR，将需求澄清回写 Spec Package。\n- **输出**：澄清记录 + 更新后的 Contract Package + 相关 ADR。\n- **验收标准**：\n - AC-4.45：Contract 产出前，所有被检测到的技术模糊点都已澄清或记录为待定风险。\n - AC-4.46：需求层面的模糊上报给 Spec 来源方，不由架构阶段单方面假设。\n - AC-4.47：技术决策类澄清收敛后写入 ADR，包含替代方案和取舍理由。\n - AC-4.48：Spec 与 Contract 之间的矛盾在此阶段被检测并消解，不流入 Implement。\n\n#### FR-11.3 Implement 阶段澄清\n\n- **输入**：Contract Package、Work Package、Task 描述。\n- **处理**：\n 1. 执行前检查 Task 描述完整性（目标文件、预期变更、验证步骤是否齐全）。\n 2. 执行过程中发现 Spec/Contract 矛盾或未覆盖场景时，暂停实现并上报。\n 3. 生成结构化澄清问题，标注阻断级别（blocking：必须等回复才能继续；non-blocking：可先按默认假设推进，但需确认）。\n 4. 收到澄清回复后，更新 Task 描述或回写上游工件。\n- **输出**：澄清记录 + 更新后的 Task 描述（或上游工件修正请求）。\n- **验收标准**：\n - AC-4.49：Task 描述不完整时，执行者主动提问而非基于猜测开发。\n - AC-4.50：Spec/Contract 矛盾被发现时，实现暂停并上报，不自行决定以哪个为准。\n - AC-4.51：澄清问题标注阻断级别，blocking 类必须等回复，non-blocking 类可附默认假设先行。\n - AC-4.52：澄清结论回写到对应工件（Task 描述、Spec Package 或 Contract Package），不只留在执行日志中。\n\n#### FR-11.4 实现路径\n\n- 每个阶段的 Skill（specify/plan/implement）内置模糊检测逻辑，作为阶段执行的前置步骤或并行检查。\n- 模糊检测规则可配置、可扩展，新增检测维度不需要改代码。\n- 澄清流程通过阶段执行原则注入（参考 §6.6），绑定阶段而非 Agent 身份。\n- 澄清记录作为阶段工件的一部分，纳入 Ledger 证据链。\n- 验收标准：\n - AC-4.53：模糊检测规则可通过配置文件扩展，不需要修改 Skill 源码。\n - AC-4.54：澄清记录纳入 Ledger Entry 的证据链，可追溯每个澄清的触发点、问题、回复和收敛结论。\n - AC-4.55：澄清机制不依赖特定 Agent 身份，任何执行者进入对应阶段都自动获得澄清能力。\n\n### FR-12 Pipeline Create\n\n- **定位**：生命周期操作。研发流程的入口点，负责在用户已创建 Project、已添加 FR 之后，为该 FR 创建 FR 流程实例、初始化 Project 目录结构、生成路由结果。\n- **输入**：任务描述、Project 标识（project-slug）、FR 描述、触发条件命中结果。\n- **处理**：\n 1. 校验 Project 标识合法性（命名规范、是否已存在）。\n 2. 校验目标 FR 已被创建并归属到该 Project。\n 3. 检查同一 Project 是否已有 active 的 FR 流程实例，有则拒绝创建。\n 4. 生成实例 ID（格式见 §3.5）。\n 5. 执行路由判定（§3.2），确定任务级别和必经阶段。\n 6. 检查 Project 目录结构，按 §3.6 规范初始化或补全。\n 7. 创建 FR 流程实例记录，状态设为 created，并使该 FR 自动进入 Specify 阶段的流程准备态。\n 8. 向 PipelineEngine（FR-13）发送 pipeline-created 事件，PipelineEngine 接管后续生命周期推进。\n- **输出**：FR 流程实例（含 ID、Project 绑定、路由结果、目录结构确认）。\n- **执行阶段**：Pipeline Create（研发流程入口，在第一个业务阶段之前执行）。\n- **验收标准**：\n - AC-4.56：每个 FR 流程实例有全局唯一 ID，格式符合 `fr---` 规范。\n - AC-4.57：同一 Project 已有 active 实例时，创建请求被拒绝并返回明确错误信息。\n - AC-4.58：创建完成后，Project 目录结构符合 §3.6 规范，缺失目录已补全。\n - AC-4.59：路由结果包含任务级别、必经阶段、可跳过阶段及跳过理由。\n - AC-4.60：已有 Project 目录的内容不被覆盖，只补全缺失的子目录。\n - AC-4.61：pipeline 创建完成后，PipelineEngine 自动接管并通过 OpenClaw Adapter 触发第一个阶段的执行，用户不需要手动触发。\n\n### FR-13 PipelineEngine（流程编排引擎）\n\n- **交付状态**：已交付（v1.12.1）。\n- **定位**：SEVO 的核心运行时引擎。负责 pipeline 实例创建后的全生命周期推进——通过状态机驱动阶段流转，借助 OpenClaw Adapter 触发阶段执行，监听阶段完成事件，评估门禁条件，决定推进或阻断。PipelineEngine 定义的是编排语义（何时推进、何时阻断、何时重试），具体的任务派发方式由 OpenClaw Adapter 实现。\n- **编排模型**：PipelineEngine 不直接调度任务。在 OpenClaw 环境中，它通过 hook 注入 + prompt 引导的方式工作：`before_prompt_build` hook 向主会话注入「下一步该派发什么任务」的指令，主会话仍然是调度者，PipelineEngine 提供编排决策。`subagent_ended` hook 监听任务完成事件，更新 pipeline 状态，设置下一阶段的推进指令。\n- **角色知识内置**：PipelineEngine 在派发阶段任务时，自动注入该阶段应遵循的专业标准（§6.6）。Specify 阶段注入 PM 标准的 prompt 模板和质量门禁，Review 阶段注入审计标准，Contract 阶段注入架构设计原则。单 Agent 用户也能产出专业质量的工件，多 Agent 环境有专职角色则效果更好。\n- **输入**：FR-12 创建的 FR 流程实例（含路由结果、阶段队列）。\n- **处理**：\n 1. 接收 pipeline-created 事件，读取路由结果中的阶段队列，生成 Stage Queue。\n 2. 按 Stage Queue 顺序，通过 OpenClaw Adapter 触发当前阶段的执行。\n 3. 监听阶段完成事件。\n 4. 阶段完成后，自动评估该阶段的出口条件（工件是否齐全、门禁是否通过）。\n 5. 出口条件满足 → 自动推进到下一阶段 → 重复步骤 2。\n 6. 出口条件不满足（门禁失败）→ 自动触发 Review Fix Loop（FR-06a）→ 修复完成后重新评估。\n 7. 支持并行阶段（如 FR-02a/FR-02b/FR-02c 与 FR-03 并行；FR-06c 与 FR-06d 并行）。\n 8. 所有阶段完成 → Ledger 自动生成 → pipeline 实例状态变为 completed。\n 9. 启动时扫描持久化状态文件，检测中断的 pipeline（Gateway 重启、主会话中断、系统 OOM），自动恢复到最后已知状态并继续推进。\n 10. 多个 pipeline 竞争同一角色的 Agent 时，按先到先服务排队，不阻塞其他不竞争的阶段。用户可通过配置指定优先级。\n- **输出**：pipeline 实例的完整生命周期推进记录，包含每个阶段的触发时间、完成时间、门禁结果、推进决策。\n- **验收标准**：\n - AC-13.1：pipeline 创建后，PipelineEngine 在无人工干预的情况下自动通过 OpenClaw Adapter 触发第一个阶段的执行。\n - AC-13.2：每个阶段完成后，PipelineEngine 在 30 秒内评估门禁并决定推进或阻断。\n - AC-13.3：门禁失败时，PipelineEngine 自动触发修复流程（FR-06a），修复通过后自动恢复推进。\n - AC-13.4：并行阶段（如 UX Acceptance + PM Commercial Review）同时触发，两者均通过后才推进到下一阶段。\n - AC-13.5：pipeline 推进的每一步决策（推进/阻断/重试）都有结构化记录，可在驾驶舱查看。\n - AC-13.6：PipelineEngine 的编排语义与任务派发实现分离——它定义「何时推进、何时阻断」，具体的任务触发通过 Adapter 抽象层实现，保持代码职责清晰。\n - AC-13.7：用户可以在任意时刻查询 pipeline 当前状态：走到哪个阶段、卡在哪里、下一步是什么。\n - AC-13.8：Gateway 重启后，中断的 pipeline 在 60 秒内自动恢复推进，不需要用户手动干预。\n - AC-13.9：多个 pipeline 竞争同一角色的 Agent 时，按优先级排队，不阻塞其他不竞争的阶段。\n - AC-13.10：显式执行 `sevo:create ` 或被 dispatch-guard 自动路由到创建入口后，PipelineEngine 必须直接进入 Specify 阶段并自动派发第一条 Specify 任务，不允许停留在 created 状态等待人工二次触发。\n - AC-13.11：通过显式 CLI 创建和通过 dispatch-guard 拦截创建的 pipeline，复用同一套状态机和自动推进逻辑；两种入口的阶段队列、门禁评估和恢复行为保持一致。\n\n### FR-14 Package Distribution & CLI（包分发、初始化与命令行界面）\n\n- **定位**：SEVO 的安装入口和用户交互界面。负责 npm 包分发、CLI 入口、初始化命令、插件自动注册、环境健康检查，以及 Project 管理、FR 管理、Pipeline 状态查询和手动干预的全部命令行操作。\n- **包名**：`sevo`（统一 npm 包名）。\n- **包结构**：单包双入口——`dist/` 提供库 API（PipelineEngine、GateEngine、LedgerEngine、Adapter 等），`plugin/` 提供 OpenClaw 插件入口（register + hooks），`bin/` 提供 CLI 入口。\n- **输入**：用户执行 `npm install -g sevo` 和 CLI 命令。\n- **处理**：\n 1. npm 包包含 SEVO 核心库 + CLI 入口 + 内置 OpenClaw 插件。\n 2. `sevo init` 执行环境检测：检测 OpenClaw 环境配置 → 生成默认配置 → 自动注册插件到 `openclaw.json` → 扫描 `projects/*/sevo.json` 发现受管项目 → 动态发现 Agent 并按命名规则 + runtime type 自动分类角色 → 单 Agent 环境自动启用降级模式 → 执行 doctor 检查 → 输出角色分配表和下一步指引。\n 3. `sevo doctor` 检查配置完整性和环境就绪状态，每个问题附带修复建议。\n 4. `sevo project create [--description ]` 创建 Project。\n 5. `sevo project list` 列出所有 Project。\n 6. `sevo fr add ` 向 Project 添加 FR，自动触发 pipeline 创建。\n 7. `sevo fr list ` 列出 Project 下所有 FR 及其 pipeline 状态。\n 8. `sevo fr advance --fr ` 为已有项目中新增的 FR 触发增量实现子流程（implement → review → regression → publish），跳过 spec/contract 阶段。\n 9. `sevo status []` 查看 pipeline 当前状态。\n 10. `sevo pause ` 暂停 pipeline。\n 11. `sevo resume ` 恢复 pipeline。\n 12. `sevo cancel ` 取消 pipeline，状态设为 failed，取消原因记录到 Ledger。\n 13. `sevo ledger []` 查看交付账本。\n- **输出**：可用的 SEVO 运行环境 + 配置文件 + 插件注册 + CLI 交互能力。\n- **验收标准**：\n - AC-14.1：陌生用户执行 `npm install -g sevo` + `npx sevo init` 后，5 分钟内能创建第一个 Project 并启动第一条 pipeline。\n - AC-14.2：`sevo init` 自动检测 OpenClaw 环境配置，不需要用户手动指定。\n - AC-14.3：在 OpenClaw 环境中，`sevo init` 自动注册 SEVO 插件，用户不需要手动编辑 `openclaw.json`。\n - AC-14.4：`sevo init` 生成的默认配置足以跑通完整流水线（L0 级别），不需要额外配置。\n - AC-14.5：`sevo doctor` 能检测并报告所有配置问题，每个问题附带修复建议。\n - AC-14.6：`sevo --help` 输出所有可用命令，每个命令有一句话说明。\n - AC-14.7：`sevo project create` + `sevo fr add` 后，pipeline 自动创建并开始推进，用户不需要额外操作。\n - AC-14.8：`sevo status` 能在任意时刻回答「当前走到哪了、卡在哪里、下一步是什么」。\n - AC-14.9：所有命令的错误提示可理解、可操作（告诉用户怎么修，不只是报错码）。\n - AC-14.10：CLI 核心命令（status、ledger 等查询类）在纯 Node.js 环境中可运行，流水线执行依赖 OpenClaw 环境。\n - AC-14.11：`sevo init` 检测到 OpenClaw 未安装时，错误提示包含 OpenClaw 安装链接。\n - AC-14.12：当自动分类无法识别任何 Agent 的角色时，`sevo init` 进入交互式角色分配模式，引导用户手动指定至少一个编码角色和一个审查角色。\n - AC-14.13：`sevo init` 自动检测 OpenClaw 环境中的 ACP Agent 类型（Claude Code、Codex、OpenCode、Gemini CLI 等），为每种已检测到的 ACP 生成对应的持久化提示注入配置文件（如 `.claude/CLAUDE.md`、`codex.md`、`.opencode/agents.md`）。注入内容包含 SEVO 流程规则、角色约束和项目上下文。配置文件在后续 pipeline 执行时被 ACP Agent 自动加载，无需每次通过 task prompt 重复注入。\n - AC-14.14：SEVO 插件启动时通过文件系统扫描 `projects/*/sevo.json` 自动发现受管项目。项目根目录下存在 `sevo.json` 且内容包含 `{\"managed\": true}` 的项目自动纳入受管列表。`sevo.json` 最小有效内容为 `{\"managed\": true}`。\n - AC-14.15：`plugins.entries.sevo-pipeline.config.managedProjects` 配置项作为覆盖/补充机制保留。插件的 `loadConfig()` 函数先扫描项目目录发现 `sevo.json`，再合并 config 中的显式列表，最终生成完整的受管项目列表。显式列表中的项目即使没有 `sevo.json` 也纳入受管。\n - AC-14.16：新增项目只需在项目根目录创建 `sevo.json`（内容 `{\"managed\": true}`），无需修改全局配置即可被 SEVO 自动纳管。\n - AC-14.17：发布到 npm 的安装包必须正确注册 `sevo` CLI 入口。陌生用户通过全局安装或 `npx` 调用时，`sevo --help`、`sevo init`、`sevo project create`、`sevo fr add` 四条首用命令都可直接执行，不需要手工修复 bin 链接。\n - AC-14.18：发布包包含安装后自检路径：`postinstall` 钩子或等效机制必须验证 CLI 入口和必需资源可用；自检失败时输出可操作修复提示，禁止静默成功。\n - AC-14.19：发布包提供一键初始化脚本 `scripts/init.sh` 或等效受支持入口，用于串联安装后检查、CLI 可用性确认和 `sevo init` 首次引导；README 与 CLI 首次输出引用同一入口，避免陌生用户在多条初始化路径之间猜测。\n - AC-14.20：`sevo-pipeline` 主包仅承载 CLI、引擎、流水线编排能力，禁止打包 Web 静态资源（`web/`、`web/.next/`、`web/components/` 等子目录）。Web 驾驶舱体验由独立 npm 包 `sevo-web` 提供，发版节奏与主包解耦。`npm pack --dry-run` 输出中不得出现 Web 子目录。\n - AC-14.21：`sevo-web` 包通过 `package.json.peerDependencies` 显式声明 `sevo-pipeline` 的兼容版本范围；`sevo-web` 启动时校验已安装的 `sevo-pipeline` 引擎契约版本，不在兼容范围内时拒绝启动并输出含「升级/降级 sevo-pipeline 至 X.Y.Z」的可操作错误信息。`sevo-pipeline` 的 `sevo init` 在检测到项目声明 Web 入口时，必须主动提示安装 `sevo-web` 并附完整命令，禁止默认无声忽略。\n\n### FR-15 Progressive Disclosure（渐进式披露配置）\n\n- **定位**：SEVO 的配置与定制分层模型。定义四个披露级别，用户按需逐级解锁更多控制能力。\n- **处理**：\n\n**L0 安装即用**（由 FR-14 保证）：\n- `sevo init` 后零配置可用。默认阶段定义、默认门禁规则、默认路由策略、角色专业标准全部内置。\n- 用户只需要 `sevo project create ` + `sevo fr add ` 就能启动 pipeline。\n- 单 Agent 环境自动降级：所有角色池填入同一个 agentId，流水线所有阶段由同一个 Agent 执行，质量保证降级但功能完整。\n- 对未经编排的开发任务的默认处理策略为 `guide`（注入流程引导），不阻断执行。\n\n**L1 按需配置**：\n- 用户可以在配置中调整：\n - 默认路由级别阈值（多少行算 Level 1、多少行算 Level 2+）。\n - 门禁严格度（严格/标准/宽松）。\n - 通知渠道偏好。\n - 发布目标（npm / GitHub / ClawHub）。\n - 合规模式（`guide` 注入流程引导 / `auto-route` 自动为未编排的开发任务创建 pipeline 并路由进 SEVO 流程 / `off` 关闭）。\n\n**L2 自定义阶段**：\n- 用户可以添加自定义阶段（如 Security Audit、Performance Test）。\n- 用户可以修改阶段顺序（在约束范围内）。\n- 用户可以定义自定义门禁规则。\n\n**L3 编程控制**：\n- 用户可以通过 API 或 SDK 编程控制 pipeline 行为。\n- 支持自定义 Adapter（替换默认的通知、发布、LLM 调用实现）。\n- 支持自定义阶段执行器（替换默认的 Skill 执行）。\n\n- **验收标准**：\n - AC-15.1：L0 级别下，用户不需要编辑任何配置文件就能跑通完整 pipeline。\n - AC-15.2：L1 级别的配置项有完整的文档说明和默认值，修改任一配置不会破坏 pipeline 运行。\n - AC-15.3：L2 级别的自定义阶段可以插入到标准阶段序列中，且不破坏工件链和门禁逻辑。\n - AC-15.4：L3 级别的 API 覆盖 pipeline 创建、阶段查询、门禁覆写、工件读取等核心操作。\n - AC-15.5：每个级别的能力是累加的——L1 包含 L0 的全部能力，L2 包含 L1 的全部能力，以此类推。\n - AC-15.6：用户从 L0 升级到 L1 不需要重新初始化，只需编辑配置文件。\n - AC-15.7：Agent 自主行动按操作风险分三级——L0 级操作（文件读写、构建、测试、代码生成）无需确认直接执行；L1 级操作（配置变更、依赖安装、分支创建）执行后通知用户；L2 级操作（发布、删除、外部通信、生产环境变更）必须获得用户确认后才能执行。分级规则在 `sevo.config.j\n\nArchive v1.13.0: 46 files, 191462 bytes\n\nFiles: CHANGELOG.md (2322b), data/pipelines/483ef487-d7bd-4713-9f6e-92c9a9119549/state.json (3123b), data/pipelines/53705fbd-0c57-4026-a0b2-7171bd53a51c/state.json (2824b), data/pipelines/9c996279-6539-4871-9c18-0c5c22effde0/state.json (3930b), data/pipelines/a031ea32-938d-4760-a70d-f2d36b92a4ce/state.json (3001b), data/pipelines/a3b3dd4a-722b-4c34-8350-ed250fd5267b/state.json (2832b), data/pipelines/a83a4d9b-b776-4f25-92e1-103e2746fa9d/state.json (2816b), data/pipelines/bfff87b9-6149-4cf1-b515-8267f195e92f/state.json (2815b), data/pipelines/cdd75e10-f316-4791-9e48-fdc633ffbc09/state.json (2829b), data/pipelines/da778b47-2c3e-437b-91a4-4d41011513b5/state.json (2824b), data/pipelines/e4cbb30c-4029-4cc1-b957-2f8d72d73345/state.json (2833b), data/pipelines/e4d38573-938f-4d94-86fa-4c12bd6be57e/state.json (863b), docs/arc42-architecture.md (64970b), docs/architecture.md (70239b), docs/backlog-endgame-auto-fix.md (903b), docs/gap-scan-l1.json (15102b), docs/gap-scan-summary.json (16657b), docs/product-requirements.md (212283b), docs/reviews/code-review-fr13-p0-implementation.md (7452b), docs/reviews/contract-review-fr13-p0-architecture.md (8624b), docs/reviews/contract-review-ux-arch-stages.md (8786b), docs/reviews/fr13-p1-code-audit.md (7929b), docs/spec.md (28268b), docs/standalone-guide.md (14985b), docs/web-dashboard-guide.md (16327b), openclaw.plugin.json (1724b), package.json (1555b), projects/audit-test/project.json (362b), projects/demo/project.json (342b), projects/demo2/project.json (344b), projects/exam-sprint/project.json (423b), projects/sevo-endgame/specs/product-requirements.md (13141b), projects/sevo-intercept-llm-gate/project.json (355b), projects/sevo-p0-l3-verifier/project.json (426b), projects/sevo-p0-test-fix/docs/architecture/arc42-architecture.md (15b), projects/sevo-p0-test-fix/docs/product-requirements.md (23b), projects/sevo-p0-test-fix/package.json (74b), projects/sevo-p0-test-fix/pipelines/fr-sevo-p0-test-fix-20260524-001.json (3885b), projects/sevo-p0-test-fix/project.json (342b), projects/sevo-p0-test-fix/README.md (19b), projects/sevo-p0-test-fix/specs/product-requirements.md (2145b), projects/sevo/project.json (330b), README.md (11539b), sevo.json (1219b), SKILL.md (2303b), _meta.json (124b)\n\nArchive v1.12.2: 36 files, 180111 bytes\n\nFiles: CHANGELOG.md (2322b), data/pipelines/483ef487-d7bd-4713-9f6e-92c9a9119549/state.json (3123b), data/pipelines/53705fbd-0c57-4026-a0b2-7171bd53a51c/state.json (2824b), data/pipelines/9c996279-6539-4871-9c18-0c5c22effde0/state.json (3930b), data/pipelines/a031ea32-938d-4760-a70d-f2d36b92a4ce/state.json (3001b), data/pipelines/a3b3dd4a-722b-4c34-8350-ed250fd5267b/state.json (2832b), data/pipelines/a83a4d9b-b776-4f25-92e1-103e2746fa9d/state.json (2816b), data/pipelines/bfff87b9-6149-4cf1-b515-8267f195e92f/state.json (2815b), data/pipelines/cdd75e10-f316-4791-9e48-fdc633ffbc09/state.json (2829b), data/pipelines/da778b47-2c3e-437b-91a4-4d41011513b5/state.json (2824b), data/pipelines/e4cbb30c-4029-4cc1-b957-2f8d72d73345/state.json (2833b), data/pipelines/e4d38573-938f-4d94-86fa-4c12bd6be57e/state.json (863b), docs/arc42-architecture.md (65078b), docs/architecture.md (70239b), docs/backlog-endgame-auto-fix.md (903b), docs/gap-scan-l1.json (14132b), docs/gap-scan-summary.json (15607b), docs/product-requirements.md (192695b), docs/reviews/code-review-fr13-p0-implementation.md (7452b), docs/reviews/contract-review-fr13-p0-architecture.md (8624b), docs/reviews/contract-review-ux-arch-stages.md (8786b), docs/reviews/fr13-p1-code-audit.md (7929b), docs/spec.md (28268b), docs/standalone-guide.md (15003b), docs/web-dashboard-guide.md (16327b), openclaw.plugin.json (1724b), package.json (1513b), projects/exam-sprint/project.json (423b), projects/sevo-endgame/specs/product-requirements.md (13141b), projects/sevo-intercept-llm-gate/project.json (355b), projects/sevo-p0-l3-verifier/project.json (426b), projects/sevo/project.json (330b), README.md (11575b), sevo.json (1219b), SKILL.md (2303b), _meta.json (124b)\n\nArchive v1.5.1: 12 files, 113330 bytes\n\nFiles: CHANGELOG.md (2322b), docs/arc42-architecture.md (65060b), docs/architecture.md (70239b), docs/product-requirements.md (107799b), docs/spec.md (28268b), docs/standalone-guide.md (15003b), docs/web-dashboard-guide.md (16327b), openclaw.plugin.json (1550b), package.json (1093b), README.md (7348b), SKILL.md (2303b), _meta.json (123b)\n\nArchive v1.5.0: 393 files, 779742 bytes\n\nFiles: artifacts/implement/task-1-implementation-bundle.json (780b), CHANGELOG.md (2322b), docs/arc42-architecture.md (65060b), docs/architecture.md (70239b), docs/architecture/arc42-architecture.md (109979b), docs/architecture/decisions/ADR-001-filesystem-artifact-storage.md (1181b), docs/architecture/decisions/ADR-002-stage-state-machine.md (1361b), docs/architecture/decisions/ADR-003-declarative-gate-rules.md (1435b), docs/architecture/decisions/ADR-004-test-case-parallel-artifact.md (1774b), docs/architecture/decisions/ADR-004-web-api-style.md (2408b), docs/architecture/decisions/ADR-005-web-realtime-strategy.md (2163b), docs/architecture/decisions/ADR-006-web-frontend-framework.md (2860b), docs/architecture/decisions/ADR-010-plugin-communication-protocol.md (1853b), docs/architecture/decisions/ADR-011-prompt-injection-driven-spawn.md (1985b), docs/architecture/openclaw-plugin-design.md (16732b), docs/design/sevo-product-requirements.md (34262b), docs/phase2-inputs.md (1164b), docs/product-requirements.md (107799b), docs/spec.md (28268b), docs/standalone-guide.md (15003b), docs/test-cases-new-frs.md (6345b), docs/web-dashboard-guide.md (16327b), openclaw.plugin.json (1550b), package-lock.json (52193b), package.json (1093b), README.md (7348b), scripts/init.sh (10946b), SKILL.md (2303b), skill/contract/scripts/inject.ts (2168b), skill/contract/scripts/run.ts (3058b), skill/contract/SKILL.md (623b), skill/deploy/scripts/inject.ts (2190b), skill/deploy/scripts/run.ts (3050b), skill/deploy/SKILL.md (540b), skill/gate/scripts/inject.ts (2165b), skill/gate/scripts/run.ts (2134b), skill/gate/SKILL.md (582b), skill/implement/scripts/inject.ts (2197b), skill/implement/scripts/run.ts (3062b), skill/implement/SKILL.md (596b), skill/ledger/scripts/inject.ts (2183b), skill/ledger/scripts/run.ts (2317b), skill/ledger/SKILL.md (559b), skill/package.json (259b), skill/pipeline-create/scripts/inject.ts (2192b), skill/pipeline-create/scripts/run.ts (2786b), skill/pipeline-create/SKILL.md (636b), skill/regression/scripts/inject.ts (2183b), skill/regression/scripts/run.ts (3066b), skill/regression/SKILL.md (597b), skill/resume/scripts/inject.ts (2182b), skill/resume/scripts/run.ts (2070b), skill/resume/SKILL.md (592b), skill/review/scripts/inject.ts (3188b), skill/review/scripts/run.ts (3050b), skill/review/SKILL.md (565b), skill/specify/scripts/inject.ts (2176b), skill/specify/scripts/run.ts (3051b), skill/specify/SKILL.md (1557b), skill/status/scripts/inject.ts (2176b), skill/status/scripts/run.ts (1771b), skill/status/SKILL.md (587b), skill/tsconfig.json (218b), skill/verify/scripts/inject.ts (2167b), skill/verify/scripts/run.ts (3050b), skill/verify/SKILL.md (573b), src/__tests__/ac-gap-close.test.ts (23284b), src/__tests__/acceptance-stages.test.ts (5839b), src/__tests__/adapter.test.ts (6621b), src/__tests__/compliance-router.test.ts (9848b), src/__tests__/context-injection.test.ts (9699b), src/__tests__/e2e-full-lifecycle.test.ts (16996b), src/__tests__/e2e.test.ts (17148b), src/__tests__/facade.test.ts (4710b), src/__tests__/full-pipeline-e2e.test.ts (45826b), src/__tests__/gate.test.ts (9342b), src/__tests__/integration.test.ts (9788b), src/__tests__/orchestrator.test.ts (19003b), src/__tests__/real-pipeline-lifecycle.test.ts (24493b), src/__tests__/role-knowledge-injector.test.ts (5268b)\n\nArchive v1.4.0: 2 files, 493 bytes\n\nFiles: SKILL.md (171b), _meta.json (123b)\n\nArchive v1.3.1: 2 files, 492 bytes\n\nFiles: SKILL.md (171b), _meta.json (123b)\n\nArchive v1.3.0: 2 files, 493 bytes\n\nFiles: SKILL.md (171b), _meta.json (123b)\n\nArchive v1.2.0: 2 files, 850 bytes\n\nFiles: SKILL.md (695b), _meta.json (123b)\n\nArchive v0.6.1: 2 files, 606 bytes\n\nFiles: SKILL.md (314b), _meta.json (123b)","readmeExcerpt":"Skill: sevo-pipeline Owner: yuchangxu1989-openclaw Summary: SEVO — Agent 研发流水线。14 阶段全链路交付：需求规格 → 门禁评审 → 测试用例 → 验收编写 → 架构契约 → 编码实现 → 独立审计 → 回归验证 → 发布门禁 → 部署 → 终验 → 交付账本。 Tags: latest:1.13.1 Version history: v1.13.1 | 2026-05-24T05:08:23.919Z | user 1.13.1 patch release v1.13.0 | 2026-05-24T04:39:19.388Z | user 1.13.0 release v1.12.2 | 2026-05-23T15:00:21.121Z | user 1.12.2 release v1.5.1 | 2026-05-04T07:51:52.376Z | u","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"npm install sevo\nnpx sevo init"},{"language":"bash","snippet":"npm install -g sevo\nsevo demo"},{"language":"bash","snippet":"npm install -g sevo\n\nsevo init # 初始化环境，自动检测 OpenClaw、发现 Agent、分配角色\nsevo doctor # 检查配置和环境，排查问题先跑它\nsevo project create my-app --description \"项目描述\" # 创建项目\nsevo fr add my-app \"实现用户登录功能\" # 添加需求，流水线自动创建并推进\nsevo status # 随时查看进度"},{"language":"text","snippet":"需求规格 → 需求评审门禁 → ┬─ 测试用例编写（并行）\n ├─ UX 验收编写（并行）\n ├─ 商用验收编写（并行）\n └─ 架构契约（并行）\n ↓\n 架构评审门禁（四方会审）\n ↓\n编码实现 → 独立审计 → 冒烟测试 → ┬─ UX 验收（并行）\n └─ 商用评审（并行）\n ↓\n 回归验证 → 商用化门禁 → 部署 → 终验\n ↓\n 终局交付（README同步 + 版本决策 + 发布 + 差距扫描）\n ↓\n 交付账本"},{"language":"text","snippet":"┌─────────────────────────────────────────┐\n │ SEVO Pipeline │\n │ │\n ┌──────────┐ │ ┌─────────┐ ┌──────────┐ ┌───────┐ │ ┌──────────────┐\n │ │ FR 描述 │ │ Router │→ │ Pipeline │→ │ Gate │ │ 工件 │ │\n │ 用户 │─────────→│ │ │ │ Engine │ │Engine │ │────────→│ Ledger │\n │ │ │ └─────────┘ └──────────┘ └───────┘ │ │ (交付账本) │\n └──────────┘ │ ↕ ↕ ↕ │ └──────────────┘\n ↑ │ ┌─────────────────────────────────┐ │\n │ │ │ Host Adapter │ │\n │ 状态/通知 │ │ (OpenClaw / Standalone / ...) │ │\n │ │ └──────────┬──────────────────────┘ │\n │ └─────────────┼───────────────────────────┘\n │ │\n │ ↓\n │ ┌─────────────────────────────┐\n └────────────────│ 宿主环境 │\n │ (Agent 运行 / 工具接入 / │\n │ 消息调度 / 执行沙箱) │\n └─────────────────────────────┘"},{"language":"text","snippet":"┌──────────────────────────────────────────────────────────────────┐\n │ sevo (npm 包) │\n │ │\n │ ┌──────────┐ ┌──────────────┐ ┌───────────┐ ┌────────────┐ │\n │ │ bin/ │ │ dist/ │ │ plugin/ │ │ templates/ │ │\n │ │ CLI 入口 │ │ 库 API │ │ OpenClaw │ │ 角色模板 │ │\n │ │ │ │ │ │ 插件入口 │ │ 阶段原则 │ │\n │ └────┬─────┘ └──────┬───────┘ └─────┬─────┘ └────────────┘ │\n │ │ │ │ │\n │ │ ┌──────────┴────────────────┤ │\n │ │ │ │ │\n │ ▼ ▼ ▼ │\n │ ┌──────────────┐ ┌──────────────┐ │\n │ │ Core Modules │ │ bridge.js │ │\n │ │ │◄─────────────│ (胶水层) │ │\n │ │ • Pipeline │ └──────────────┘ │\n │ │ Engine │ │ │\n │ │ • Stage │ │ register(api) │\n │ │ Runner │ ▼ │\n │ │ • Clarific. │ ┌──────────────┐ │\n │ │ Coordinator│ │ OpenClaw │ │\n │ │ • Compliance │ │ Gateway │ │\n │ │ Router │ │ (运行时注入) │ │\n │ │ • RoleKnow. │ └──────────────┘ │\n │ │ Injector │ │\n │ └──────────────┘ │\n └──────────────────────────────────────────────────────────────────┘\n │ │\n ▼ ▼\n ┌──────────────────"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: sevo\ndescription: \"SEVO — Agent 研发流水线。14 阶段全链路交付：需求规格 → 门禁评审 → 测试用例 → 验收编写 → 架构契约 → 编码实现 → 独立审计 → 回归验证 → 发布门禁 → 部署 → 终验 → 交付账本。\"\n---\n\n# SEVO — Agent 研发流水线\n\nSpec-Execute-Verify-Operate：面向 AI Agent 的软件交付生命周期。\n\n## 14 阶段流水线\n\n| # | Stage ID | 说明 |\n|---|----------|------|\n| 1 | spec | 需求规格与概念架构 |\n| 2 | spec-review-gate | 需求评审门禁 |\n| 3 | test-case-authoring | 测试用例编写（与 4/5/6 并行） |\n| 4 | ux-acceptance-authoring | UX 开箱即用验收编写（并行） |\n| 5 | commercial-acceptance-authoring | 商用验收编写（并行） |\n| 6 | contract | 架构设计、ADR、技术契约（并行） |\n| 7 | contract-review-gate | 架构评审门禁 |\n| 8 | implement | 编码实现（TDD 循环） |\n| 9 | review | 独立代码审计与安全审查 |\n| 10 | regression | 回归测试与冒烟验证 |\n| 11 | publish-generalization-gate | 发布通用化门禁 |\n| 12 | deploy | 构建打包与发布 |\n| 13 | verify | 清洁环境端到端终验 |\n| 14 | ledger | 交付账本（版本、证据、经验回写） |\n\nspec-review-gate 通过后，test-case-authoring / ux-acceptance-authoring / commercial-acceptance-authoring / contract 四路并行展开；implement 需等待 contract-review-gate 和 test-case-authoring 均通过后才激活。\n\n## 智能路由\n\n任务按复杂度自动分级：\n- L0（微小改动）：跳过 spec/contract，直接进 implement → review → regression → verify → ledger\n- L1/L2+（中大型）：走完整 14 阶段\n\n## 核心机制\n\n- 评审修复闭环（Review-Fix Loop）：评审发现问题 → 自动生成修复任务 → 修复后定向复验\n- 主动澄清：spec/contract/implement 阶段内建模糊检测，歧义就地消解\n- 终局收敛验收：逐条对照需求覆盖状态，未覆盖自动回到实现阶段补齐\n- 单 Agent 完整降级：一个 Agent 也能走完整流程\n\n## 集成\n\n- OpenClaw 插件：`scripts/init.sh` 安装\n- 独立使用：`npm install sevo-pipeline` 后通过 API 调用\n- 宿主无关：通过适配器接口与运行环境交互\n\n## 作者\n\nyuchangxu1989@gmail.com"},{"path":"projects/sevo-p0-test-fix/README.md","content":"# sevo-p0-test-fix"},{"path":"README.md","content":"# SEVO\n\n**AI Agent 写代码很快，但谁来保证写出来的东西用户真的能用？**\n\n🌐 [官网](https://agentos.site/sevo.html)\n\nAgent 生成代码越来越容易，但没有需求定义就自说自话，没有架构约束就边界失控，没有独立审计就写完算完。更要命的是——代码发布了，用户装上用不了，没人管。\n\nSEVO 是一条 18 阶段的全自动研发流水线，把 AI Agent 的产出从「能跑」推到「能用」。从需求到交付，每一步都有门禁、有证据、有人负责。\n\n---\n\n## 核心优势\n\n**主动澄清，需求不清不动手**\n用户随口一句话，SEVO 不会直接开写。它主动追问、澄清歧义、补全边界条件，把模糊意图收敛成结构化的需求规格说明书。大多数 AI Coding 工具拿到需求就开干，SEVO 先把需求搞清楚——写对比写快重要。\n\n**四方会审 + 反作弊隔离**\n架构评审由四个独立视角并行把关：产品看需求有没有承接住，开发看方案能不能落地，质量看风险和规范，体验看用户流程是否顺。四方全部通过才能进入编码。编码 Agent 对评分标准只有只读权限，看不到也改不了评估器代码，从 OS 文件权限层面杜绝「自己给自己打分」。门禁分数只升不降——一旦某个阶段达标就锁定基线，后续改动如果引入回退，流水线自动拦住。代码写完后的验证也不是跑个文件名匹配就算数：spec-to-code 映射文件记录每条需求对应哪些代码，LLM 语义验证逐条确认实现是否真的覆盖了 spec 定义的行为——两层检查，糊弄不过去。\n\n**自主收敛引擎，差距不归零就不放行**\n传统 CI/CD 跑一遍就结束——测试绿了、构建过了、发布成功了，流水线就关了。至于用户装上能不能用？没人管。SEVO 不是线性流水线，是围绕终局目标持续收敛的闭环引擎。它在关键节点自动触发差距扫描，发现问题就拆解修复任务，修完再扫描，循环直到差距归零才放行。门禁检查不通过？引擎自动进入修复状态，派出修复任务，最多重试 3 次。3 次修不好，自动回退到前一阶段重新来过——不是报个错就停在那等人，而是自己想办法。回退预算也有上限，真的收敛不了才阻断流水线等人工介入。OKR 锁定终局目标，SMART 拆解为可验证任务，PDCA 闭环驱动每一轮收敛——代码能跑不算完，陌生用户 5 分钟内感受到价值才算。\n\n**主动驱动，不等人催**\n阶段转换时自动触发门禁检查，不需要调度层记得要做什么。Spec 缺口主动发现——代码写了但 spec 没覆盖，引擎自动提醒补齐。发布后自动逐条对照 spec 做差距扫描，差距大于零就自动回环修复。OKR 达成度定期巡检，未达标的 KR 自动生成 SMART 拆解建议。整条流水线是自驱动的，不是被动等指令的。\n\n**18 阶段全自动推进**\n需求规格 → 门禁评审 → 架构契约 → 四方会审 → 编码实现 → 独立审计 → 冒烟测试 → UX 验收 → 商用评审 → 回归验证 → 商用化门禁 → 部署 → 终验 → 发布后验证 → 交付账本。阶段自动推进，门禁自动把关，评审发现问题自动派修复并定向复验。\n\n**终局交付不是发布，是收敛**\n发布成功只是收敛循环的一个检查点，不是终点。终局交付引擎在发布后自动触发：README 同步检查、语义化版本决策、多平台发布、逐条 spec 差距扫描。发现任何一条 FR 没有在运行态兑现，立即生成修复任务回环——修复、重新审计、重新发布、重新扫描，直到差距归零，流水线才真正关闭。\n\n**全链路可追溯**\n每步的输入、输出、结论都记录在案。出了问题秒级定位，交付账本串起版本、证据和经验沉淀。\n\n**一个 Agent 也能跑完整流程**\n只有一个 Agent？照样走完 18 阶段。质量降级但功能完整，随时可升级到多 Agent 协同。甚至连 OpenClaw 都没装也不会炸——安装时自动检测环境：完整环境正常注册插件，部分环境给个警告但不阻断，纯净环境静默退出不报错。装到哪都不会因为缺依赖把你的 `npm install` 搞挂。\n\n**全量测试覆盖**\n测试覆盖核心引擎、阶段状态机、门禁逻辑、CLI 命令、终局交付链、主动驱动层和端到端流程。\n\n---\n\n## 快速开始\n\n```bash\nnpm install sevo\nnpx sevo init\n```\n\n安装后在 OpenClaw 环境里执行 `init`，即可完成环境检测、OpenClaw 配置发现和角色分配。\n\n正式跑流水线前，OpenClaw 需要已配置可用的 LLM provider。`sevo demo` 不需要 LLM provider，可直接看演示。\n\n---\n\n## 30 秒快速体验\n\n```bash\nnpm install -g sevo\nsevo demo\n```\n\n`demo` 命令走完完整流水线生命周期演示——从项目创建、需求规格、门禁评审、编码实现、冒烟测试到发布后差距扫描。不需要 LLM provider，不需要改 OpenClaw 配置，装完就能看演示。\n\n---\n\n## 正式使用\n\n```bash\nnpm install -g sevo\n\nsevo init # 初始化环境，自动检测 OpenClaw、发现 Agent、分配角色\nsevo doctor # 检查配置和环境，排查问题先跑它\nsevo project create my-app --description \"项目描述\" # 创建项目\nsevo fr add my-app \"实现用户登录功能\" # 添加需求，流水线自动创建并推进\nsevo status # 随时查看进度\n```\n\n---\n\n## 四层架构\n\nSEVO 的能力分为四个域，各司其职：\n\n**Domain A — 流水线核心**\n阶段状态机、智能路由、并行阶段编排、PipelineEngine 流程引擎。任务进来后自动判定级别（微小改动走最小闭环，跨域重构走完整 18 阶段），阶段自动推进，支持暂停/恢复/取消。\n\n**Domain B — 质量门禁**\n可执行门禁评估器、混合评估模式（LLM + 规则引擎）、棘轮机制（分数只升不降）、评估-实现工作区隔离（反作弊）。门禁不是人工 review 的替代品，是自动化的质量底线。\n\n**Domain C — 可控调度**\n角色-任务匹配约束、终局交付自动推进（README 同步 → 版本决策 → 发布 → 差距扫描）、任意阶段切入（hotfix 从 implement 进、架构调整从 plan 进）、渐进式披露配置。\n\n**Domain D — 主动驱动**\n阶段转换自动触发门禁、Spec 缺口主动发现、发布后自动差距扫描与回环修复、OKR 达成度定期巡检、PDCA 循环自动驱动。引擎是触发器，调度层是执行者——引擎感知节点、推"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn71kk78dbbgtentzcetv7d1zn8536vd\",\n \"slug\": \"sevo\",\n \"version\": \"1.13.1\",\n \"publishedAt\": 1779599303919\n}"},{"path":"CHANGELOG.md","content":"# Changelog\n\n本文件记录 sevo-pipeline 的所有重要变更，格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/)。\n\n## [1.0.0] - 2026-05-03\n\n### 新增\n- 后端全部 27 个 FR 的验收标准（AC）100% 覆盖\n- 陌生人开箱即用验证通过（`npm install -g` → `sevo demo` 完整路径可走通）\n- 810 条测试用例，74 个测试文件\n\n### 变更\n- README 重写为营销质量标准（tagline → 痛点 → 优势 → 快速体验 → 场景）\n\n## [0.9.3] - 2026-04-30\n\n### 新增\n- 27 个 FR 全覆盖（含 FR-15 渐进式披露 L2/L3 实现）\n- 810 条测试全绿\n\n### 修复\n- `sevo demo --okr` flag 补齐（陌生人走查 P1）\n\n## [0.9.0] - 2026-04-28\n\n### 新增\n- FR-18 目标驱动 PDCA 闭环：OKR → SMART → PDCA 三层目标体系\n- 目标状态机（draft → active → achieved/missed）\n- PDCA 循环引擎（Plan → Do → Check → Act，最多 3 轮自动收敛）\n- `sevo goal` CLI 命令族（create/list/update/link/pdca）\n- 773 条测试全绿\n\n### 修复\n- TypeScript strict 模式 28 处空检查修复\n\n## [0.7.0] - 2026-04-25\n\n### 新增\n- 门禁系统：需求评审门禁、架构评审门禁（三方会审）、商用化门禁\n- 证据链：每个阶段的输入/输出/结论自动记录\n- 交付账本（Ledger）：串联版本、证据、经验沉淀，支持 `sevo ledger` 查询\n- 评审修复闭环：评审发现问题 → 自动生成修复任务 → 定向复验 → 最多 3 轮收敛\n- 智能路由：L0/L1/L2 三级自动判定，微小改动走最小闭环\n\n## [0.5.0] - 2026-04-22\n\n### 新增\n- 核心 5 阶段完整实现：Specify → Plan → Implement → Review → Release\n- PipelineEngine 流程编排引擎：阶段状态机、自动推进、暂停/恢复/取消\n- 并行阶段支持（测试用例/UX 验收/商用验收/架构契约同时执行）\n- CLI 命令体系：`sevo create`、`sevo status`、`sevo advance`、`sevo list`\n- `sevo init` 自动检测宿主环境、发现 Agent、分配角色\n- 独立审计阶段：写代码的和审代码的职责分离\n\n## [0.1.0] - 2026-04-18\n\n### 新增\n- 项目初始化，基础流水线框架\n- Spec → Contract → Implement → Review → Deploy 五阶段骨架\n- CLI 入口 `sevo`，支持 `--help` 和 `--version`\n- OpenClaw Gateway 插件适配器\n- MIT 协议"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"SEVO — Agent 研发流水线。14 阶段全链路交付：需求规格 → 门禁评审 → 测试用例 → 验收编写 → 架构契约 → 编码实现 → 独立审计 → 回归验证 → 发布门禁 → 部署 → 终验 → 交付账本。 Skill: sevo-pipeline Owner: yuchangxu1989-openclaw Summary: SEVO — Agent 研发流水线。14 阶段全链路交付：需求规格 → 门禁评审 → 测试用例 → 验收编写 → 架构契约 → 编码实现 → 独立审计 → 回归验证 → 发布门禁 → 部署 → 终验 → 交付账本。 Tags: latest:1.13.1 Version history: v1.13.1 | 2026-05-24T05:08:23.919Z | user 1.13.1 patch release v1.13.0 | 2026-05-24T04:39:19.388Z | user 1.13.0 release v1.12.2 | 2026-05-23T15:00:21.121Z | user 1.12.2 release v1.5.1 | 2026-05-04T07:51:52.376Z | u","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":721,"uniquenessScore":55,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T23:08:05.702Z","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-10T23:08:05.702Z","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-11T01:49:08.256Z","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"}]}}}