sdd-flow-kit

介绍

跨工具（Cursor Claude Code / OpenClaw / Codex 等）的“SDD 需求分析 + 产物编排”自动化工程骨架。

它把你的 5 步流程拆成可复用的“流程引擎 + 产物模板 + Adapter 适配层”，并在目标项目下生成固定结构的产物文件。

注意：不同 AI 工具在“真正执行 LLM/写入报告”的能力不同；因此当前版本会把第 2 步 SDD 提示词、产物模板与调用指引打通，让你在 Cursor/Claude/Codex/OpenClaw 中直接执行提示词完成内容生成。

软件架构

软件架构说明

Node 版本（14.16 / 18 / 20 均可）

| 组件 | 要求 | |------|------| | sdd-flow-kit CLI（install / run / doctor / postinstall） | Node >= 14.16.0（engines 已声明；兼容老 CI/内网机） | | Playwright E2E 自动安装 | Node >= 18 才 add @playwright/test；Node 14 跳过、不报错 | | openspec CLI、opsx-workflow | 以各自包文档为准；建议 18+ | | 目标业务仓（如 adInsight frontend） | 按该仓 package.json engines，与 kit 独立 |

安装后建议执行：

node -v   # 应 >= v14.16.0
npx sdd-flow-kit doctor --agent cursor

若 doctor 报 node-version 失败，请升级到 14.16+，或在该仓使用 .nvmrc 锁定版本。

安装教程

推荐两步（团队标准）：

cd <你的项目目录>                    # cd 到哪，装到哪
pnpm add -D sdd-flow-kit             # ① postinstall 自动轻量写入 skill
pnpm add -D sdd-flow-kit@latest 或者 yarn add sdd-flow-kit@latest
npx sdd-flow-kit install --project <类型> -y   # ② 全量 OPSX（按需）

Monorepo 项目自动检测：

如果你的项目是 monorepo 结构（如 adInsight-web/frontend、operation-web/frontend），工具会自动检测并定位到实际的前端代码目录：

• 根目录无 package.json + 存在 frontend/package.json：自动使用 frontend/ 目录
• 根目录有 package.json：使用根目录
• 直接在 frontend 目录执行：使用当前目录

支持的子目录名称：frontend、packages/frontend、apps/frontend、client

示例（adInsight-web monorepo）：

cd /path/to/adInsight-web              # 在仓库根目录
npx sdd-flow-kit guard "开发 ADI V2.3.4 版本" -y
# ✅ 自动检测到 frontend/ 并在其中创建配置，而非在根目录创建

<类型> 按项目选择：ADI | OMS | 欢盟 | AD Tools（工具会按目录名自动推断，不对时用 --project 覆盖）。

| 项目示例 | --project | docs skill 目录 | |----------|-------------|-----------------| | adInsight-web | ADI | docs/adi-doc-skill/ | | operation-web | OMS | docs/oms-doc-skill/ | | 欢盟 | 欢盟 | docs/huan-doc-skill/ |

安装后验证（Cursor 用户看 .cursor，不是 .claude）：

ls .cursor/skills/sdd-flow-kit/SKILL.md
ls docs/*-doc-skill/SKILL.md
# Claude Code 用户：
ls .claude/skills/sdd-flow-kit/SKILL.md

如果找不到，则执行下面的命令

node ./node_modules/sdd-flow-kit/dist/postinstall.js

当前自动化边界

• 已支持：跨工具统一目录结构、提示词、报告模板、单步 NEXT.md（+ 排障用 FLOW-MAP.md）
• 已支持：gate / phase / propose / deliver / chain / session mode / status / resume 命令（exit code 机械门禁）
• 已支持：断点续传 — status / resume 刷新当前步；Agent 每步只读 .session-state.json + NEXT.md
• 已支持：ensure-opsx + openspec status 校验 apply-ready
• 未支持：在 Cursor 内全自动跑完全流程（Cursor adapter 仍为 manual）；可选 SDD_FLOW_KIT_ENABLE_CLAUDE_AUTORUN=1 给 Claude Code

断点续传（status / resume）

# 查看当前步 + 刷新单步 NEXT（禁止通读全流程说明书）
npx sdd-flow-kit status --project-root . --run-id <runId>
npx sdd-flow-kit status --project-root . --run-id <runId> --json

# 续传：同一 run，禁止 guard 重开
npx sdd-flow-kit resume --project-root . --run-id <runId>
npx sdd-flow-kit resume --project-root . --run-id <runId> --exec   # 仅 kind=cli 执行第一条

Agent 协议：每步 status/resume → 只读 session + NEXT → 只做本步 → 再 status。mayStop=false 时禁止「后续待办」式收工。

环境变量配置

| 环境变量 | 说明 | 默认值 | |---------|------|--------| | SDD_FLOW_KIT_INSTALL_ROOT | 强制指定安装根目录（绝对路径） | process.cwd() | | SDD_FLOW_KIT_PROJECT | 强制指定项目类型 | 自动推断 | | SDD_FLOW_KIT_LEGACY_MONOREPO | 使用旧版 monorepo 模式（需手动设置 1） | 自动检测 | | SDD_FLOW_KIT_ENABLE_CLAUDE_AUTORUN | Claude Code 自动执行修复 | 0 | | SDD_OPSX_WORKFLOW_PACKAGE | 自定义 opsx-workflow 包路径 | npm 默认版本 | | CONFLUENCE_DEBUG | 输出 Confluence 搜索调试日志 | 0 | | OPSX_SKIP_VALIDATE_REVIEW | 跳过 validate 独立 review subagent | 未设置 | | OPSX_VALIDATE_REVIEW_REQUIRED | 审查不可用/无 RESULT 时硬拦 validate | 未设置（软跳过） |

Monorepo 自动检测说明：

• 新版（v1.3.28+）：默认启用智能检测，无需设置环境变量
• 旧版兼容：设置 SDD_FLOW_KIT_LEGACY_MONOREPO=1 回退到旧行为

npm 发包流程

1. 发布前检查：npm whoami（确认已登录正确 npm 账号）
2. 构建产物：npm run build
3. 本地打包检查：npm pack（确认 tar 包内容包含 dist/、src/templates/、README.md）
4. （可选）在目标项目验证安装：npm i -D ./sdd-flow-kit-<version>.tgz，并执行 npx sdd-flow-kit install --dry-run --plan-json
5. 正式发布：
   • 首次发布 scoped 包：npm publish --access public
   • 非 scoped 或后续版本：npm publish
6. 发布后验证：在任意项目执行 npm i -D sdd-flow-kit，再执行 npx sdd-flow-kit install

快速开始（v1.5.0）

# 1. 安装
cd <你的项目目录>
pnpm add -D sdd-flow-kit
npx sdd-flow-kit install --project ADI -y

# 2. 启动需求开发
npx sdd-flow-kit guard "开发 ADI V2.5.0 版本" -y --agent cursor

# 3. 补全 PRD 细节层（⭐ 新增步骤）
npx sdd-flow-kit prd-enrich --run-id <runId>
# → 在 AI 工具中执行生成的提示词，创建 PRD-details/*.md

# 4. 检查细节层完整性
npx sdd-flow-kit gate --run-id <runId> --expect prd-details-complete

# 5. 查看生成的产物
ls openspec/PRD/<runId>/
# 会看到：01-需求分析.md, 02-改动清单.md, 03-待确认.md, 
#        04-技术文档.md, 05-验收清单.md, source/PRD-details/

# 6. 文档闭合
npx sdd-flow-kit gate --run-id <runId> --expect docs-closed
npx sdd-flow-kit phase advance --run-id <runId> --to docs-done

# 7. 后续流程不变（propose → apply → validate → deliver）

变更记录

1.7.23 — validate 独立 Review Subagent（审查与实现分离）

• ✨ validate 在机械门禁前派发 validate-review（新进程、只审不修）
• ✨ review 专用 prompt：禁止改 src/**/e2e/**；强制 RESULT.md/RESULT.json 合约
• ✨ 开放 P0/P1 → validate 硬失败；产物 .validate-review.json + .subagents/validate-review/
• 跳过：OPSX_SKIP_VALIDATE_REVIEW=1；必选硬拦：OPSX_VALIDATE_REVIEW_REQUIRED=1

1.7.6 — 演示保真复查硬循环（实现后 → 交付前）

• ✨ 新命令：demo-fidelity-review --auto（对照演示源码/16 合约 vs 生产：字段·布局·交互；有开放项则 remediate 再验，默认 ≤5 轮）
• ✨ 产物：17-演示保真复查报告.md、.demo-fidelity-report.json、17-演示保真复查提示词.md
• ✨ 新门禁：gate --expect demo-fidelity-ready；纳入 deliver / chain / delivery-pipeline 硬失败
• ✨ 原则：开放 P0/P1「不一致」未清零不得 deliver（不像 prd-review 强制放行）
• 跳过：OPSX_SKIP_DEMO_FIDELITY=1 或 DEMO_REFERENCE_EXEMPT

1.7.5 — 演示布局合约（截图 → 分析 → 实现前硬闸）

• ✨ 新命令：demo-layout-capture / demo-layout-analyze
• ✨ 产物：16-演示布局合约.md、16-演示布局分析提示词.md、visual-baseline/demo/
• ✨ 新门禁：gate --expect layout-contract-ready；phase --to impl 与 impl-allowed 强制校验
• ✨ 原则固化：结构跟演示、控件跟仓库 UI 库（组件映射表）
• 跳过：OPSX_SKIP_DEMO_LAYOUT_CONTRACT=1 或 DEMO_REFERENCE_EXEMPT

1.7.4 — 提案演示审查报告硬门禁（impl-allowed / delivery）

• ✨ gate --expect impl-allowed 新增 propose-review-report：缺通过态 10-提案演示审查报告.md 则 FAIL
• ✨ 缺报告时默认自动 propose-remediate 续跑修复（不立刻中断）；仍失败才硬拦
• ✨ 新命令：ensure-propose-review（delivery-pipeline / 手工补齐）
• ✨ opsx-delivery-pipeline full 链路新增 step_propose_review
• 跳过：OPSX_SKIP_PROPOSE_REVIEW_REPORT=1；仅检查不自动修：OPSX_SKIP_PROPOSE_REVIEW_AUTO=1 或 ensure-propose-review --no-auto

1.7.2 — 03 待确认问题清单结构门禁（doc03-structure）

• ✨ gate questions-open 新增 doc03-structure：五章段落版、4.1–4.6、代码路径引用、P0/P1/P2 总结；拦截 Q1–Q10 简表
• 📚 基准样例与规则：docs/DOC03-QUALITY-GATE.md、src/tests/fixtures/doc03-golden-adi-v234.md
• 🔧 gate --auto-remediate 支持 doc03-structure 修复提示
• 跳过：OPSX_SKIP_DOC03_QUALITY=1

1.7.1 — 提案演示 1:1 自动审查 + 自动修复闭环

• ✨ 新命令：propose-remediate（gate propose-ready + ac-ready --auto-remediate，通过后才允许 Apply）
• ✨ ac-ready / propose-ready 支持 --auto-remediate（与 docs-closed 同机制）
• ✨ 新门禁：demo-proposal-consistency（对照演示 App.vue + 结构模式，拦截 ReportPage/ImportHistoryDrawer/缺 Tab 声明等壳层偏差）
• 🔧 changeHasUiScenarios 识别 ### Requirement: 与 design 演示章节，不再误跳过演示门禁
• 🔧 phase advance --to propose-done 默认开启 ac-ready 自动修复（SDD_PROPOSE_AUTO_REMEDIATE=0 可关）
• 📄 产物：10-提案演示审查报告.md、gate-remediate-*-第N轮.md

1.6.8 — 质量三板斧落地（PRD 原子覆盖率 + AC 断言绑定 + 争议闭环）

• ✨ docs-closed：自动生成 .prd-review-atoms.json 并校验 prd-ac-coverage（前端原子 ≥95%）+ 五层 AC 门禁 + .ac-source-trace.json
• ✨ ac-metrics：汇总 AC Coverage / Fidelity / Source Trace，写入 .ac-metrics.json
• ✨ 新增 sync-disputes：汇总 03/05/08/12 → 13-争议闭环登记册.md
• ✨ 新增 gate dispute-closed（已含于 ac-signed）
• 📚 新增 docs/QUALITY_TRIAD.md 全流程指引
• 🧪 单测：src/tests/disputeClosureGate.test.ts

1.6.1 — 未配置 baseline 时自动推断项目 UI 风格

• ✨ docs-closed：扫描 src/components / views / pages 等高频表格 import，幂等写入 04 §2.4.2 与 .ui-style-inferred.json
• ✨ prd-coverage：无 baseline 且表格组件出现 ≥3 次时，列表类生产文件须引用推断组件（inferred-table-style）
• 📚 04 模板补充自动扫描说明
• 跳过：OPSX_SKIP_UI_STYLE_INFER=1

1.6.0 — 通用 UI/交互门禁（防假绿交付）

• ✨ docs-closed：ui-ac-criteria-quality（UI P0 须写壳层/交互原语，禁止仅接口权限验收）
• ✨ docs-closed：visual-ac-priority（有原型图时 visual 须 P0/P1，禁止仅 P2）
• ✨ docs-closed / propose / ac-ready：demo-signal-quality、demo-mapping-granularity、design-demo-not-weaker
• ✨ prd-coverage：可选 openspec/ui-engineering-baseline.json 列表组件基线（如 wTable，项目配置、不写死业务）
• 🔧 VISUAL_REGRESSION_EXEMPT 须可审计原因；有原型图时豁免不能省略 visual AC
• 📚 模板：03/04/05、演示迁移 skill、分层测试策略同步
• 🧪 单测：src/tests/uiInteractionGate.test.ts
• 紧急跳过：OPSX_SKIP_UI_INTERACTION_GATE=1、OPSX_SKIP_UI_BASELINE=1

1.5.0 — PRD 分层架构（方案一实施）

• ✨ 新增：prd-enrich 命令，从完整 PRD 提取结构化细节层
• ✨ 新增：gate --expect prd-details-complete 门禁，检查细节层完整性
• ✨ 新增：source/PRD-details/ 目录结构（字段定义、状态机、导出规范、交互规范、边界场景）
• 🔧 增强：PRD 原子数从 146 提升至 300+，覆盖度提升 106%
• 🔧 增强：支持字段级、状态机级、导出字段级细节验证
• 📚 新增：完整的 PRD 细节提取提示词模板
• 📚 文档：CHANGELOG-v1.5.0-prd-layered-architecture.md
• ✅ 向后兼容：未使用新功能的项目不受影响

1.4.0 — 大任务拆分 + 上下文压缩 + 待确认项管理

• ✨ 新增：大任务自动拆分与 Subagent 编排（analyze-task）
• ✨ 新增：上下文自动压缩机制（≥75%/150K 触发，汇总压缩至约 30% 保留，AC-ID 全文保留，compress-context）
• ✨ 新增：待确认项系统化管理（sync-confirmations, list-confirmations）
• ✨ 新增：临时标记机制（allow-gate-pass）
• ✨ 新增：最终交付汇总报告（10-待确认项最终汇总.md）
• 🔧 增强：gate 命令集成待确认项检查
• 🔧 增强：session state 扩展（向后兼容旧版）
• 📚 新增：7 个 CLI 命令支持新功能
• 📚 文档：完整使用示例（docs/COMPLETE_EXAMPLE_v1.4.0.md）

1.3.29 — Monorepo 智能检测（无需环境变量）

• 智能检测 monorepo 结构：自动识别 frontend/、packages/frontend/、apps/frontend/、client/ 等子目录
• 优先级逻辑：
  1. 环境变量 SDD_FLOW_KIT_INSTALL_ROOT（强制覆盖）
  2. 当前目录有 package.json → 使用当前目录
  3. 检测到 monorepo 子目录（含 package.json + 前端特征文件）→ 自动使用子目录
  4. 使用传入的 projectRoot
• 前端特征检测：src/、public/、vite.config.ts、webpack.config.js、tsconfig.json
• 修复问题：在 adInsight-web/ 根目录执行时，不再在根创建无用配置，自动定位到 frontend/ 目录
• 向后兼容：保留 SDD_FLOW_KIT_LEGACY_MONOREPO=1 环境变量用于旧版行为
• API 变更：resolveInstallRoot 改为异步函数，返回 Promise<string>

1.3.13 — 执行模式拆分 + 回合结束约束 + chain 机械串联

• 新增 executionMode：full-chain（默认）与 staged-confirm（分阶段确认），正交于 strictCommands
• 兼容「严格SOP，不可替代」→ staged-confirm + strictCommands
• 模板写入回合结束条件，禁止待办清单式提前收尾
• 新增 chain、session mode CLI；invoke 自动解析执行模式

1.3.11 — PRD 自动修复改为「每项最多 3 次」

• 每轮只修 prd-diff 仍失败的剩余项；8 项已修好则下轮只盯剩下 2 项
• 单项重试时 prompt 附「上次错误代码 + 错误描述」摘要，避免重复同样错误
• 状态持久化：.prd-remediate-state.json；单项 3 次仍失败 → 写入 08 待人工确认

1.3.10 — PRD 自动修复支持多 Agent

• prd-remediate 按项目安装环境自动选择 Cursor / Claude Code / Codex / OpenClaw
• Claude Code 安装（.claude/skills）时默认用 claude -p 执行修复，不限于 Cursor
• 可用 --agent claude-code 或 SDD_FLOW_KIT_ENABLE_*_AUTORUN=0 控制

1.3.12 — Confluence 关键字搜索稳定性（dosearchsite 主路径）

• confluence-doc.py：每个关键词优先打开 dosearchsite.action?queryString=... 专用搜索页（不再依赖 #all-updates 顶栏搜索）
• 匹配放宽：标题命中或 URL 路径命中 均可得分（score_link_match 原已支持，增强前缀匹配与 ADI 加权）
• run_search_dosearch：处理 ERR_ABORTED、搜索结果页导航重试；顶栏搜索降为兜底
• 新增 CONFLUENCE_DEBUG=1 输出选择器解析日志
• 更新 01-adi-doc-skill-指引 / doc-skill.SKILL：关键字搜索为主，pageId 直链为可选兜底

1.3.9 — PRD 不一致自动修复循环（最多 3 次）

• 新增 prd-remediate：prd-diff 失败 → 按 09 生成修复指引 → 调 AI 工具 /opsx-apply 修代码 → 再 prd-diff（每项最多 3 次）
• 3 次仍失败：自动写入 08「待人工确认汇总」，状态 待人工确认（自动修复3次未果）
• validate 内置上述循环；escalated 后 needUserConfirm=true

1.3.8 — PRD 脚本语义 diff + 全量测试覆盖门禁

• 新增 prd-diff：机械提取 PRD 字面量，在 src//e2e/ 中搜索，生成 09-PRD语义diff报告.md
• gate prd-coverage 增强：校验 08 证据路径真实存在、08 结论与脚本 diff 一致、可验证 PRD 须有自动化测试 + E2E
• 解决「08 看起来合规但实际对比不准」：08 标「一致」但代码无 PRD 字面量 → gate 失败
• 解决「E2E 只覆盖主路径」：所有 ui-verifiable / behavior-verifiable PRD 原子须在测试中引用 PRD-ID 或字面量，且须有 E2E
• 所有声明 e2e 类型的 AC（含 P1/P2 边缘场景）均须有 e2e/ 下测试

1.3.7 — 强制验收与 PRD 一致性复查

• validate 强制 E2E：Node ≥ 18 且缺 Playwright 时自动安装 @playwright/test + chromium；Node < 18 跳过安装且不报错（E2E 需 nvm use 18+ 后再装）
• 新增 gate prd-coverage：最细粒度 PRD 原子全覆盖 + 08 报告合规 + P0 AC 测试映射
• 新增 prd-review 命令与 08-PRD一致性复查报告.md / 提示词（禁止揣摩、禁止兜底，不一致按 PRD 修复）
• deliver 前必须通过 prd-coverage 门禁

1.3.3 — Confluence PRD 拉取修复（ADI 长标题页）

• confluence-doc.py：匹配时统一 -/_；ADI 增加 ADI_V*结算 关键词
• ADI 需求页无「PRD」面包屑时按 ADI_V* / 结算开票回款标题识别
• 支持 CONFLUENCE_PAGE_ID 直链（如 V2.3.4 → 109609740）
• dosearchsite 搜索改用 domcontentloaded，降低网络抖动失败率