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/内网机） | | 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 锁定版本。

安装教程

1. 进入你要开发的项目目录
2. 安装：pnpm add -D sdd-flow-kit 检查是否安装（Cursor 用户看 .cursor，不是 .claude）：
   • ls .cursor/skills/sdd-flow-kit/SKILL.md
   • ls docs/adi-doc-skill/SKILL.md（adInsight 应为 adi，不是 oms）
   • Claude Code 用户：ls .claude/skills/sdd-flow-kit/SKILL.md

若在 adInsight-web/frontend 等子目录安装，工具会向上识别仓库名；仍不对时：SDD_FLOW_KIT_PROJECT=ADI pnpm add -D sdd-flow-kit 或 npx sdd-flow-kit install --project ADI -y

3. 若 skill 未生成，执行手动兜底：
   • node ./node_modules/sdd-flow-kit/dist/postinstall.js（轻量，秒级）
   • 或 npx sdd-flow-kit install -y（完整环境）
4. （可选）预演安装：npx sdd-flow-kit install --dry-run --plan-json
5. （可选）环境健检：npx sdd-flow-kit doctor --agent claude-code
6. 完成后，直接在 Cursor / Claude Code / Codex / OpenClaw 中用自然语言发起需求，例如：开发 ADI 2.3.2 需求

可通过环境变量覆盖安装时默认项目类型：SDD_FLOW_KIT_PROJECT=ADI npm i -D sdd-flow-kit

安装失败排查（推荐复制执行）

当安装后没有生成 .cursor/skills/sdd-flow-kit/SKILL.md 时，按以下顺序处理：

1. 检查包是否已安装：pnpm list sdd-flow-kit --depth 0
2. 若出现 ERR_PNPM_UNEXPECTED_STORE，先对齐 store（示例）：
   • pnpm config set store-dir /Users/<your-user>/Library/pnpm/store/v10 --global
3. 重新触发脚本：pnpm rebuild sdd-flow-kit
4. 若仍未生成，执行手动兜底（100%触发初始化）：
   • node ./node_modules/sdd-flow-kit/dist/postinstall.js
5. 验证产物：
   • ls .cursor/skills/sdd-flow-kit/SKILL.md
   • ls .claude/skills/sdd-flow-kit/SKILL.md
   • ls docs/*-doc-skill/SKILL.md

团队推荐安装命令（稳妥）：

pnpm add -D sdd-flow-kit

postinstall 仅做轻量初始化（写入 skill / Cursor 规则 / docs-skill / .opsx/config.json），不会交互提问，也不会跑 npx opsx-workflow（避免 pnpm i 卡住）。
完整环境（分支切换 + opsx-workflow）请另执行：npx sdd-flow-kit install -y
跳过 postinstall：SDD_FLOW_KIT_SKIP_POSTINSTALL=1 pnpm add -D sdd-flow-kit

pnpm add 后依赖全被删掉（Packages: +1 -932）

原因：pnpm 会按当前 package.json 同步 node_modules。若 manifest 里只剩 sdd-flow-kit（或文件被误保存成几行空壳），就会卸载其它所有包——不是 pnpm add 单独删包，而是 manifest 已不完整。

恢复（在业务仓如 adInsight-web/frontend）：

1. 用 Git 恢复完整 package.json：git checkout -- package.json
2. 重装：pnpm install
3. 再装 kit（建议 ≥ 1.1.2，且必须在有完整 package.json 的目录执行）：
   • cd frontend && pnpm add -D [email protected]
   • 或本地联调：pnpm add -D file:../../sdd-flow-kit

v1.1.2+ 防护：repairOpsxDeliveryScripts 仅合并 scripts，写入前检查依赖条数与文件体积；postinstall 不再改 package.json，且必须有 INIT_CWD 才运行。

pnpm v10 构建脚本：若出现 Ignored build scripts: sdd-flow-kit，执行 pnpm approve-builds 选中 sdd-flow-kit，或安装后手动：node ./node_modules/sdd-flow-kit/dist/postinstall.js

使用说明

安装根：cd 到哪，装到哪（v1.2+）

默认 installRoot = 你执行命令时的当前目录（process.cwd()），也可用 --project-root / SDD_FLOW_KIT_INSTALL_ROOT 指定。

| 你 cd 到 | 会安装到 | |----------|----------| | adInsight-web/frontend | frontend/package.json、.cursor/skills、.opsx、pnpm run opsx:delivery-pipeline | | adInsight-web（仓库根） | 仓库根（需根目录也有 package.json，否则会失败） |

cd /path/to/adInsight-web/frontend
npx sdd-flow-kit install --project ADI -y
npx sdd-flow-kit run --product ADI --version 2.3.2 -y

PRD / gate 的 --project-root：与安装根相同；若 openspec/ 在上级目录，工具会向上查找已有 openspec/PRD（不把安装写到上级）。

旧行为（在仓库根执行时自动落到 frontend/）：设置 SDD_FLOW_KIT_LEGACY_MONOREPO=1。

脚本门禁（v1.1+，不依赖自然语言）

run 会在 openspec/PRD/<runId>/NEXT.md 写入必须按顺序执行的命令。AI 与人都以 exit code 为准：失败则不得进入下一阶段、不得改 src/。

# 门禁（失败 exit 1）
npx sdd-flow-kit gate --project-root . --run-id <runId> --expect prd-fetched
npx sdd-flow-kit gate --project-root . --run-id <runId> --expect docs-closed      # 检测 git 是否误改 src
npx sdd-flow-kit gate --project-root . --run-id <runId> --expect propose-ready --change <name>
npx sdd-flow-kit gate --project-root . --run-id <runId> --expect impl-allowed --change <name>
npx sdd-flow-kit gate --project-root . --run-id <runId> --expect shipped --change <name>

# 阶段推进（更新 .session-state.json + NEXT.md）
npx sdd-flow-kit phase advance --project-root . --run-id <runId> --to after-prd
npx sdd-flow-kit phase advance --project-root . --run-id <runId> --to docs-done
npx sdd-flow-kit phase advance --project-root . --run-id <runId> --to propose-done --change <name>
npx sdd-flow-kit phase advance --project-root . --run-id <runId> --to impl --change <name>
npx sdd-flow-kit phase advance --project-root . --run-id <runId> --to shipped --change <name>

# 提案 / 交付
npx sdd-flow-kit propose --project-root . --run-id <runId> --change <name>
npx sdd-flow-kit deliver --project-root . --run-id <runId> --change <name>

docs-closed 会在 git 仓库中扫描 src/、frontend/src/ 等路径；文档阶段若已有实现层改动，gate 失败。

需求澄清：用户无需背提示词

install 会写入 .cursor/rules/sdd-flow-kit-gates.mdc 与触发 Skill（已改为脚本优先）。
用户粘贴确认点后：先更新 01/02/03/04，再执行 gate docs-closed → phase advance --to docs-done；禁止跳过 gate 直接改代码。

/opsx-apply 与 TDD + Playwright 检查机制

| 环节 | 实现 | 说明 | |------|------|------| | 安装时 | postinstall（light） | 只写 sdd skill/rule；不自动跑 opsx-workflow（避免 pnpm i 卡住） | | 完整安装 | npx sdd-flow-kit install -y | 缺什么跑什么 → ensureOpsxWorkflow → npx @lixin5257xxx/opsx-workflow setup | | Apply 前 | npx sdd-flow-kit ensure-opsx -y | 阶段 D 第 0 步；doctor 加 --fix 等价修复 | | Apply 时 | Cursor 读 skill 链 + pnpm run opsx:delivery-pipeline | 由 AGENTS.md / 06-agent-skill 约束 AI，非 Node 自动执行 |

npx sdd-flow-kit ensure-opsx --agent cursor -y   # /opsx-apply 前
npx sdd-flow-kit doctor --agent cursor --fix     # 检查并尝试修复

常见遗漏：只 pnpm add sdd-flow-kit 未跑 ensure-opsx；或 AI 跳过 skill 直接改代码。

1. install（等价 setup）：提示选择开发环境（cursor/claude-code/codex/openclaw，默认 claude-code）与开发分支（无则自动创建），并检测/安装 openspec+superpower 基础环境，同时写入项目级 Skill 与 Cursor 门禁规则
2. 安装完成后，本工具主要负责“流程环境与模板”落地；业务需求由你在目标 AI 工具中自然语言驱动
3. start/run/invoke 属于进阶能力（脚本化或一键编排时使用）
4. doctor：检查 git/npx/agent CLI/openspec/tool 目录，输出可机读诊断结果

当前自动化边界

• 已支持：跨工具统一目录结构、提示词、报告模板、NEXT.md 脚本清单
• 已支持：gate / phase / propose / deliver 命令（exit code 机械门禁）
• 已支持：ensure-opsx + openspec status 校验 apply-ready
• 未支持：在 Cursor 内全自动跑完全流程（Cursor adapter 仍为 manual）；可选 SDD_FLOW_KIT_ENABLE_CLAUDE_AUTORUN=1 给 Claude Code

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

版本升级建议：

1. 修改版本号：npm version patch（或 minor / major）
2. 重新执行构建与发布步骤
3. 在 README.md 或变更记录中补充本次升级说明

参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

特技

1. 使用 Readme_XXX.md 来支持不同的语言，例如 Readme_en.md, Readme_zh.md
2. Gitee 官方博客 blog.gitee.com
3. 你可以 https://gitee.com/explore 这个地址来了解 Gitee 上的优秀开源项目
4. GVP 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
5. Gitee 官方提供的使用手册 https://gitee.com/help
6. Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 https://gitee.com/gitee-stars/