# 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 独立 |

安装后建议执行：

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

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

#### 安装教程

**推荐两步（团队标准）**：

```bash
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）：
```bash
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`）：

```bash
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）

```bash
# 查看当前步 + 刷新单步 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）

```bash
# 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 &lt; 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`，降低网络抖动失败率