FlowSpec

FlowSpec 是面向 AI Native 研发团队的多服务交付工作区工具。它把一次交付拆成两个层次：

• Iteration：共享的分支、MR、发布、回滚和归档批次。
• Proposal：Iteration 内的一个 OpenSpec change。

一个 iteration 可以包含多个 proposal。只要某个需求需要独立合并、发布或回滚，就应创建新的同级 iteration。

协作模式

产品、研发、测试都在同一个 iteration 内协作：

• 产品在 prd/ 沉淀 PRD 文档、需求说明和验收口径。
• 研发在 iteration 内创建 proposal、实现代码，并沉淀接口契约、数据模型和发布材料。
• 测试通过 iteration-id 接手 iteration，了解改动与影响面，精准测试并编写自动化脚本和造数。

开发完成后，研发只需把 iteration-id 提供给测试，测试使用 flowspec-handoff 拉取 iteration 即可接手（见下方 Skills 分工）。

适用场景

• 多个服务围绕同一需求协作交付。
• 需要把 PRD、代码改动、接口文档、发布材料、测试数据和 MR 证据放在同一个交付目录。
• 需要让 Codex skills 按团队规则创建 proposal、准备 worktree、处理 TAPD Bug、合并 stage 分支、触发 Jenkins 和提交正式 MR。

快速接入

安装或升级：

npm install -g @qdama/flowspec@latest
flowspec update

首次配置：

flowspec setup -g \
  --code-root /path/to/code-root \
  --workspace-root /path/to/flowspec-workspace \
  --tapd-token <tapd-token> \
  --gitlab-url http://gitlab.qdama.cn/api/v4 \
  --gitlab-token <gitlab-token> \
  --jenkins-user <jenkins-user> \
  --jenkins-token <jenkins-api-token>

Windows 用户示例（路径请按本机实际值填写）：

flowspec setup -g --code-root "D:\newworkspace" --workspace-root "D:\flowspec-workspace" --tapd-token "<tapd-token>" --gitlab-url "http://gitlab.qdama.cn/api/v4" --gitlab-token "<gitlab-token>" --jenkins-user "<jenkins-user>" --jenkins-token "<jenkins-api-token>"

Token 获取路径：

• TAPD token：个人设置 > 个人 Token。
• GitLab token：Personal Access Tokens。
• Jenkins API token：Jenkins 个人安全页（把 <jenkins-user> 替换为本人 Jenkins 用户名，例如 lizhuo3）。

两个根目录的职责不同：

• code_root：本机服务仓库集合，例如 /path/to/code-root/order-service。
• workspace_root：团队共享的 FlowSpec Git 仓库，保存 catalog、iteration 和交付材料。

以 QDM 团队本机为例，code_root 目录结构大致如下：

code_root（例如 /Users/willjo/code/work/qdm）     ← 普通目录，本身不是 Git 仓库
├── account-service/                            ← 各服务目录：各自独立的 Git 仓库
├── b2b-web/
├── detect/
├── flowspec/
├── order-service/
├── ……（其余服务，各是独立 Git 仓库）
└── ai-rd-workspaces/                           ← workspace_root：团队共享 Git 仓库

• code_root 本身不是 Git 仓库，它只是按服务名定位仓库的普通目录：<code_root>/<service-name>。
• code_root 下面的每个服务目录（account-service、flowspec、order-service 等）才是各自独立的 Git 仓库。
• workspace_root（本例的 ai-rd-workspaces）是团队共享的 Git 仓库，保存 catalog、iteration 和交付材料，不承载服务代码；即便它和 code_root 位于同一父目录，职责也完全不同。

在 QDM 场景下，workspace_root 通常就是本机 ai-rd-workspaces 目录的路径。ai-rd-workspaces 通常每个团队拥有一个，并且必须是 Git 仓库；所有 workspace-level 文档、OpenSpec 提案和交付材料都会提交到这个仓库，便于后续抽取到知识库。团队统一使用同一个 workspace 仓库（http://gitlab.qdama.cn/ordering/ai-rd-workspaces），方便管理和协同。

推荐结构：

<workspace-root>/
  .git/
  catalog/services.yaml
  worktrees/<iteration-id>/
    work/<iteration-id>/
  .flowspec/worktrees/<iteration-id>/<service>/

workspace_root 必须是自己的 Git 工作树。FlowSpec 不会在 iteration 内创建 .git，也不会切换或污染可写服务的 canonical checkout。

Codex 在 active iteration 内只能处理当前 worktrees/<iteration-id>/work/<iteration-id>/ 和 AGENTS 明确允许的服务链接；不得读取、扫描或修改同级其他 iteration 目录。

更完整的接入步骤见 快速开始 和 安装说明。

日常使用

1. 创建 iteration

flowspec iteration create integrate-log-platform --title "接入日志平台"
cd /path/to/flowspec-workspace/worktrees/integrate-log-platform-20260723153045/work/integrate-log-platform-20260723153045

或在 Codex 中使用：

$flowspec-iteration 创建一个迭代 integrate-log-platform，标题是“接入日志平台”

Codex 后续继续开发这个需求时，工作目录要选到实际 iteration 入口：

<workspace-root>/worktrees/<iteration-id>/work/<iteration-id>

flowspec iteration create 和 $flowspec-iteration 都会输出带时间戳的实际 iteration_id 以及最终目录。进入这个目录后，Codex 会读取当前 iteration 的 AGENTS.md、manifest.json 和 .codex/skills，并只处理该 iteration 允许的服务链接。忘记入口时，可用已知 iteration_id 恢复并打印路径：

flowspec iteration worktree prepare <iteration-id>

如果已经在有效未归档 iteration 内，普通新需求继续在当前 iteration 沉淀 PRD、design、tasks 和验收口径；不要调用 stock $openspec-propose 自动生成提案。只有需要独立合并、发布或回滚时，才创建同级的新 iteration。

2. 添加服务

flowspec service add order-service -w
flowspec service add b2b-web -r
flowspec service worktree prepare --all

• 可写服务会使用 managed Git worktree。
• 只读服务使用 -r，可写服务使用 -w 或 -rw。
• 服务范围写入当前 iteration 的 manifest.json 和 catalog/services.yaml。

3. 沉淀需求材料并实现

在 active iteration 内：

$flowspec-prd 生成日志平台 MCP 接入的开发交付 PRD
$openspec-apply-change 开始实现这个提案

推荐完整流程是：按需沉淀 PRD 或验收口径，创建 OpenSpec proposal/design/tasks，在设计阶段同步补接口契约和数据模型，再实现、验证、补 MR/测试/发布证据，最后归档。这个流程是导航，不是瀑布锁；小需求、Bug 和纯技术修复可以没有 PRD。

$flowspec-prd 只负责 PRD；proposal/design/tasks 必须按 FlowSpec 受控规则维护，不要使用 stock $openspec-propose 自动生成。Proposal ID 在同一 iteration 内永久不可复用，包括已归档 proposal。

4. 维护交付材料

交付目录保持 iteration 级扁平结构；服务级目录按需创建，不提前生成空目录：

prd/
architecture/api/frontend/
architecture/api/client/
architecture/api/third-party/
architecture/data-model/
deployment/<service>/sql/
deployment/<service>/nacos/
deployment/<service>/mq/
test-data/<service>/

prd/ 只放产品 PRD 文档、需求说明和验收口径，且按需推荐、不默认强制。接口契约写入 architecture/api/<audience>/；表结构、字段、索引、迁移和历史数据处理写入 architecture/data-model/；最终生产 SQL、Nacos/config 或 MQ 材料才写入 deployment/<service>/ 下对应类型目录，且这些目录只在确有对应上线变更时创建。旧 api-integration/ 会继续兼容读取，但新材料不再推荐写入这里。不要创建 proposal-id 子目录。Proposal 的 design 和 tasks 直接引用这些共享路径。

5. 检查状态和发布准备

flowspec doctor --json
flowspec delivery status --json
flowspec delivery instructions api-contract --json
flowspec iteration status --json
flowspec iteration validate --json
flowspec iteration validate --release --json

flowspec delivery status --json 输出非锁死 artifact graph、下一步建议、warning 和 delivery-ready blocker。这里的 delivery-ready 只表示交付材料、服务状态和证据可收口，不表示 Jenkins stage/prod 发布已触发。

正式交付检查可用：

$flowspec-delivery 检查当前迭代是否具备交付条件

需要为开发生成 Markdown PRD，并按需附加 HTML 演示标注稿和影响面清单时可用：

$flowspec-prd 生成本次需求的 Markdown 开发交付 PRD

6. 提交正式 MR

代码验证完成并推送源分支后，优先用 delivery skill：

$flowspec-delivery 为 order-service 提交到 release 的正式 MR，并指派给 lizhuo

等价 CLI：

flowspec mr create --repo services/order-service --target-branch release --assignee lizhuo

FlowSpec 会把 MR 映射写入：

flowspec/mrs/<service>-<iid>.json

这份文件是 iteration 交付证据的一部分。

TAPD Bug 修复

QDM 团队的 TAPD Web/API URL、workspace、状态映射和 Jenkins stage URL 已有默认值。日常只需要配置个人 TAPD token、GitLab token 和 Jenkins API token。

TAPD token 获取路径：个人设置 > 个人 Token。

在 iteration 目录用 flowspec/tapd.yaml 绑定 TAPD 迭代：

tapd:
  iteration_id: "1163602049001002112"
  iteration_name: "07v22特殊迭代【日志服务】"

常用流程：

flowspec fix scan --assigned
flowspec fix claim --work-item <tapd-bug-id-or-url>
flowspec fix diagnose --work-item <tapd-bug-id-or-url> --status actionable --summary "日志确认 ..."
flowspec fix resolve --work-item <tapd-bug-id-or-url> --summary "修复摘要" --service order-service ...

也可以直接让 Codex 执行：

$flowspec-fix 从 TAPD 拉取指派给我的 bug 并开始修复

该流程不创建单 Bug MR，不等待 Jenkins 或 K8s 结果，也不替代测试人员在 TAPD 中的验证闭环。

Stage 发布

$flowspec-stage-merge 将当前分支合并到 k8s02_stage
$flowspec-trigger-stage-jenkins 只触发当前项目的 k8s02-stage Jenkins job
$flowspec-stage-publish 提交后发布当前项目

等价 CLI：

flowspec stage publish [project-name-or-path]
flowspec stage release --trigger [project-name-or-path]

生命周期

Iteration 生命周期固定为：

• empty：没有 active/archived proposal，也没有 archive snapshot。
• active：存在 active proposal，或尚未满足发布归档条件。
• archive_ready：没有 active proposal、至少有一个 archived proposal、release validation 通过，并且可写 worktree 干净。
• archived：archive snapshot 存在且没有漂移。
• invalid：结构损坏、proposal ID 重复、归档后发生漂移或新增 proposal。

归档顺序：

flowspec iteration validate --release
flowspec iteration archive

FlowSpec 只创建不可覆盖的 archive snapshot，不移动 OpenSpec proposal 目录，也不会自动删除 service worktree。

Skills 分工

• flowspec-iteration：创建、查看、校验和归档 iteration。
• flowspec-workspace：setup、服务范围、managed worktree 和结构修复。
• flowspec-handoff：通过 iteration-id 接手同事已有 iteration，并自动准备 workspace/service worktree 与接手报告。典型用法：开发完成后研发把 iteration-id 交给测试，测试用 flowspec iteration handoff <iteration-id> 拉取迭代，了解改了哪些服务、影响面多大，从而更精准地测试、写自动化脚本和造数据。
• flowspec-prd：生成代码取证的 Markdown 交付 PRD，并按需附加 HTML 演示标注稿和影响面清单。
• flowspec-delivery：delivery artifact graph、MR、证据、发布准备和归档输入。
• flowspec-fix：TAPD Bug 修复、stage 合并、Jenkins 触发和 TAPD 回写。
• flowspec-stage-merge：合并当前分支到 k8s02_stage。
• flowspec-trigger-stage-jenkins：只触发、打开或查询 Jenkins k8s02-stage job。
• flowspec-stage-publish：推送源分支、合并 stage、触发 Jenkins 的完整链路。
• stock openspec-propose：不要在 FlowSpec 交付流程中调用它自动生成 proposal、design、specs 和 tasks。
• openspec-apply-change：实现 proposal tasks。
• flowspec-qdm-assistant-design: 实现移动端页面样式交互规范

开发验证

npm test
npm run check
npm run build
npm run smoke
npm pack --dry-run

更多说明见 docs/：

• 快速开始
• 安装说明
• 工作区初始化
• 发布流程
• 校验规则
• 交付证据
• Skills 分工
• Skill 设计基线
• FlowSpec 术语表