@chenguangyao/devflow-kit 0.1.43

package/docs/tooling-overview.md

@@ -0,0 +1,774 @@
+# devflow-kit 功能、命令与流程说明
+
+本文按当前实现说明 `devflow-kit` 的功能边界、命令体系、流程步骤、工具思想来源，以及每一步为什么存在。它面向第一次接手本项目的人，也面向想把 devflow 用进自己仓库的开发者。
+
+## 1. 项目定位
+
+`devflow-kit` 是一套文件优先的开发工作流 CLI + Skills 套件。它不直接调用 LLM，也不绑定某个企业内网系统，而是把一次开发任务固化成可读、可审计、可继续接手的本地文件和状态。
+
+核心命令:
+
+```bash
+devflow <command>
+dfk <command>
+```
+
+核心原则:
+
+- 阶段之间传文件，不传聊天摘要。
+- CLI 负责机械动作:建目录、写模板、维护状态、跑测试、检查闸门、调用 provider。
+- Skills 负责协作纪律:如何澄清需求、写设计、拆计划、按 TDD 实现、审查、验证、归档。
+- 外部系统都走 provider，核心流程在没有内网依赖的裸 git 仓库里也能跑。
+
+## 2. 当前流程总览
+
+标准流程从入口材料开始，最终归档为长期规格和知识。
+
+```mermaid
+flowchart TD
+  A["入口材料或想法"] --> B{"有外部材料?"}
+  B -->|Wiki / Issue / incident / markdown| C["devflow ingest"]
+  B -->|只有想法或 slug| D["devflow new"]
+  C --> E["proposal.md"]
+  D --> E
+  E --> F["complexity-grading skill<br/>L0 / L1 / L2 / L3"]
+  F --> G["devflow requirement<br/>requirement.md"]
+  G --> H["devflow design<br/>design.md<br/>tests.md / delta 按需"]
+  H --> I["devflow plan<br/>plan.md"]
+  I --> J["devflow apply<br/>task worktree + state"]
+  J --> K["devflow review --round<br/>review.md"]
+  K -->|MUST > 0| J
+  K -->|pass| Q["verify_start checkpoint"]
+  Q --> L["devflow test / report<br/>reports/test-report.md"]
+  L --> M["devflow verify finalize<br/>verify.md"]
+  M --> N["devflow deploy 可选<br/>deploy report"]
+  N --> O["devflow deliver<br/>PR/MR / notify"]
+  O --> P["devflow archive<br/>specs + knowledge + archive"]
+```
+
+当前默认路径模型:
+
+```text
+<repo>/devflow/
+├── config.json              # 项目配置、工程画像、项目概览引用
+├── providers.json           # 可选，项目级 provider 覆盖
+└── specs/                   # 长期规格真源
+
+~/.devflow/workspace/
+├── changes/<slug>/          # 当前 change 过程文件
+├── archive/<date>-<slug>/   # 已归档 change
+└── knowledge/<category>/    # 长期知识库
+
+<repo>/.devflow-worktrees/
+└── <slug>/<task-id>/        # apply task 隔离工作区
+```
+
+兼容说明:读取时仍兼容旧的 `<repo>/devflow/changes/`、`<repo>/devflow/archive/`、`<repo>/devflow/knowledge/`，但新写入默认走 `~/.devflow/workspace/`。
+
+文档输出原则:CLI 生成的面向用户文档默认使用中文；默认只生成核心链路文件，`tests.md`、`delta/`、`reports/` 等按风险级别、命令参数和证据需要懒生成，避免空模板和无内容报告。
+
+## 3. 吸收了哪些工具的功能
+
+`devflow-kit` 不是照搬某一个工具，而是把几类成熟实践拼成一条可落地的本地工作流。
+
+| 来源 | 吸收的功能 | 为什么吸收 | 在 devflow-kit 中的落点 | 优点 |
+| --- | --- | --- | --- | --- |
+| arb-workflow-kit | 全生命周期阶段、复杂度分级、PRD 驱动、review/verify/交付闸门、知识沉淀 | 企业研发任务很少只是“写代码”，需要从需求到上线后资产沉淀的完整链路 | `requirement`、`design`、`plan`、`review`、`verify`、`deliver`、`archive` 命令和阶段 skills | 避免从 PRD 直接跳编码；让每个阶段都有可审计产物 |
+| Superpowers / Anthropic Skills | brainstorming、TDD、worktree 隔离、并行 agent、系统化调试、完成前验证 | AI 协作容易跳步骤、过早实现、缺少 fresh verification | `brainstorm`、`plan`、`apply`、`code-review`、`verify` skills；`.devflow-worktrees/` | 把“好习惯”变成流程约束，降低上下文漂移和并行冲突 |
+| OpenSpec | change folder、规格 delta、archive 合并长期 spec | 每次需求既要改代码，也可能改变系统能力定义 | `delta/added|modified|removed`、`devflow/specs/`、`archive` | 已上线能力有单一事实源，后续需求能基于 specs 继续演进 |
+| 契约消费者影响追踪 | URL/query/redirect/callback/API 字段/枚举/状态变化时追踪消费者 | 很多返工不是提供方实现错，而是前端页面、调用方、轮询页、缓存 key 等消费者没有同步设计 | `requirement-analysis` 的消费者侦察、`tech-spec` 的契约消费者影响矩阵、`test-spec` / `plan` 的消费者用例和任务 | 避免“returnUrl 不带参数后前端轮询页无 key”这类跨项目细节漏到联调才暴露 |
+| 企业内网桥接经验 | Wiki/Issue/CI/通知/知识库 provider 抽象、凭证集中管理 | 不同公司系统不同，不能把 Confluence、Jenkins、WeKnora 等写死进核心流程 | `src/providers/*`、`devflow provider *`、`~/.devflow/providers.json` | 核心零内网依赖；需要接系统时按 driver 插入 |
+| 结构化测试报告实践 | 测试输出解析、覆盖率发现、YAML frontmatter 报告 | “我跑过测试”不够，需要可复查的测试证据 | `devflow test <kind>`、`devflow report self-test`、`reports/test-report.md` | verify 和 deliver 可以基于报告判闸，PR 描述也能复用 |
+
+## 4. 为什么这样设计
+
+### 4.1 文件优先
+
+原因:AI 对话容易丢上下文，团队协作也不能依赖某个聊天窗口。  
+做法:每个阶段都落 markdown，状态落 `state.json`，长期规格落 `devflow/specs/`，知识沉淀落 `knowledge/`。  
+优点:任何人或 agent 都能从文件恢复上下文，review 和归档也有证据。
+
+### 4.2 CLI 与 Skill 分工
+
+原因:CLI 擅长确定性动作，LLM/agent 擅长读材料和起草文本。混在一起会让工具不可测、不可审计。  
+做法:CLI 只做创建、记录、校验、解析、调用 provider；复杂判断由 skills 约束上层 agent。  
+优点:命令可测试，流程可复用，不把 LLM 行为硬编码进 Node.js。
+
+更准确地说，流程控制应该从自然语言约定迁移到结构化状态机。Skill 继续保留，但降级为策略层；真正的门禁、确认、下一步、风险和证据，应该由 `devflow` CLI 统一管理。
+
+| 事项 | 应由 CLI 管理 | 应由 Skill 管理 |
+| --- | --- | --- |
+| 阶段推进 | 当前 phase、可进入的下一个 phase、是否允许越级 | 解释为什么建议进入或暂缓某个阶段 |
+| 用户确认 | `checkpoint` 创建、选项、默认动作、resolve/cancel 审计 | 用业务语言说明用户需要确认什么 |
+| 下一步卡片 | 结构化渲染 `nextAction`、可执行命令、阻塞原因 | 帮 agent 选择更合适的下一步建议 |
+| 风险和证据 | 风险接受记录、测试报告路径、review/verify 状态 | 判断风险是否充分暴露、证据是否可信 |
+| 并行执行 | task 状态、worktree、冲突和完成记录 | 判断哪些 task 适合拆给子 agent |
+
+这样分工以后，agent 说错话或少说一句，不会直接改变流程真实状态；IDE、CLI、自动化脚本也能读取同一个 `state.json`，看到一致的卡点、选项和证据。
+
+这种分工的额外好处:
+
+- 可测试:CLI 的 phase gate、checkpoint、报告检查都能用单元测试覆盖，不依赖某次 agent 输出是否稳定。
+- 可恢复:换一个 agent、换一个 IDE、甚至隔天人工接手，都能从 `state.json` 和 markdown 产物恢复到同一流程位置。
+- 可审计:用户确认、force 绕过、风险接受和证据路径都有记录，后续 review/复盘能知道当时为什么继续。
+- 可集成:CI、IDE 插件、企业平台可以读取同一套结构化状态，而不是解析聊天文本。
+- 可降级:没有 LLM 或 skill 没安装时，CLI 仍能维护基本流程和硬闸；skill 只增强质量，不决定事实。
+- 可演进:后续要加问题卡、项目确认、风险接受、verify gate，只需要扩展 checkpoint schema 和 phase gate，不必重写每个 skill 的自然语言话术。
+
+这个分工是正确的，但边界要守住:CLI 负责确定性状态和硬约束，不负责替人理解业务；Skill 负责策略、解释、判断质量和指导 agent 行为，但不应该成为流程真实状态的唯一来源。也就是说，CLI 是流程账本和门禁系统，Skill 是专家操作手册。
+
+当前仍是混合控制：`requirement.md`、`design.md`、代码侦察和测试策略主要由 agent/skill 产出；`state.json.level`、phase、checkpoint、review/verify gate、报告缺失检查等事实由 CLI 记录和判定。设计方向是继续把“能否进入下一阶段”从自然语言 skill 迁移到 CLI gate，避免 agent 把聊天里的“继续”误当成流程确认。
+
+### 4.3 分级驱动
+
+原因:一行文案改动和跨服务架构改造不该走同样重量的流程。  
+做法:通过 L0/L1/L2/L3 决定文档深度、测试报告、review 尺度和归档要求。  
+优点:小改动不被流程拖慢，大改动不会漏掉设计、测试和回滚。
+
+### 4.4 Provider 可插拔
+
+原因:PRD、Issue、CI、通知、知识库在不同环境里差异很大。  
+做法:抽象 `intake`、`issue`、`vcs`、`ci`、`notify`、`kb` 六类 provider。  
+优点:核心流程可离线运行，企业接入时只扩 driver。
+
+### 4.5 Worktree 并行
+
+原因:多 task、多 agent 并行时，直接在同一工作区改代码容易互相污染。  
+做法:`apply` / `worktree` 按 task 创建 `.devflow-worktrees/<slug>/<task-id>/`。  
+优点:任务边界清楚，冲突显性化，主工作区更干净。
+
+### 4.6 Workflow Kernel 与 Checkpoint
+
+原因:完整流程不能只靠 skill 文档提醒 agent "该问用户"。问题卡、项目确认、复杂度分级、plan 审查、review 返工和风险接受都属于用户决策点；如果这些点只留在对话里，agent 可能漏问，用户也容易不知道下一步。  
+做法:新增 `checkpoint` 内核，把决策点写入 `state.json.checkpoints[]`，由 CLI 统一渲染下一步卡片。`devflow status` 会展示最新 pending checkpoint。  
+优点:流程停顿有结构化原因、选项和命令；后续 phase gate 可以检查 unresolved checkpoint，避免越级推进；IDE 也可以按同一 schema 渲染问题卡和下一步卡。
+
+当前已接入的硬闸:
+
+- `intake -> requirement`：`devflow new/ingest` 创建 `problem_card` checkpoint，`devflow requirement` 在该 checkpoint 未确认时会阻塞并展示下一步卡片。
+- `requirement -> design`：`devflow requirement` 自动路由项目后创建 `project_confirmation` checkpoint，`devflow design` 在该 checkpoint 未确认时会阻塞并展示下一步卡片。
+- `plan -> apply`：`devflow plan` 创建 `plan_review` checkpoint，`devflow apply` 在该 checkpoint 未确认时会阻塞并展示下一步卡片。
+- `review -> apply/verify`：`devflow review --round` 遇到 MUST 会创建 `review_fix`；达到最大轮次仍有 MUST 会创建 `review_blocked`。`devflow apply` 会记录接受返工，review 通过或强制通过会解析对应 checkpoint，并创建 `verify_start` checkpoint。
+- `review -> verify`：`devflow verify` 在 `verify_start` 未确认时会阻塞；用户先执行 `devflow checkpoint resolve --id=<checkpoint-id> --decision=start-verify` 解除闸门，再单独触发 `devflow verify --slug=<slug>`。不得把 resolve 和 verify 串成一条命令，也不得复用早前"继续/按推荐"作为确认。
+- `verify -> deliver`：`devflow verify finalize` 缺报告时创建 `verification_evidence`；`devflow deliver` 会拒绝带着未解决的 review/evidence/risk checkpoint 交付。
+
+紧急情况可 `devflow <phase> --force --reason="..."` 审计绕过；没有 reason 会被拒绝。
+
+IDE 集成可以使用 `devflow checkpoint show --json` 获取最新 pending checkpoint，避免解析自然语言输出。JSON 输出包含 `checkpoint_confirmation_surface`、`pending`、`confirmationCard` 和 `nextAction`；其中 `confirmationCard.primaryAction` / `secondaryActions` 可以直接渲染成确认按钮。`workflow_policy` 会使用 `workflow_policy_confirm` 卡片，并把 `accept-risk` 作为主操作。
+
+如果 IDE 需要渲染整个当前 change 页面，优先调用 `devflow status --slug=<slug> --json`。它返回 `change_status_surface`，聚合 change 基本信息、phases 进度、artifacts 产物、apply task 摘要、review 轮次、verify 报告缺口、risk signals、workflow check、workflow actions、pending checkpoint、checkpoint confirmation card、primaryPanel、blockingReason、availableActions 和 nextAction。UI 主操作区应优先渲染 `primaryPanel`，用 `blockingReason` 展示阻塞原因，并把 `availableActions` 渲染成按钮。字段 contract 见 `schemas/status-surface.schema.json`。
+
+迁移方向:
+
+- 自然语言提示只负责解释，不再作为唯一门禁。
+- 每个需要用户拍板的节点都落成 `checkpoint`。
+- 每个阶段命令先读结构化状态，再决定是否继续、阻塞或审计绕过。
+- 每个风险接受、测试证据和 review 结论都尽量落到可查询字段或报告文件。
+- Skill 产出的建议应尽量指向 CLI 命令，而不是只在聊天里写“请继续”。
+
+## 5. 命令体系
+
+### 5.1 主流程命令
+
+| 阶段 | 命令 | 主要产物 | 作用 |
+| --- | --- | --- | --- |
+| 初始化 | `devflow init` | `devflow/config.json`、workspace 骨架 | 在项目里接入 devflow |
+| 外部入口 | `devflow ingest <url|issue-id|incident:id>` | `refs/*.md`、`proposal.md`、`state.json` | 拉取或导入需求材料 |
+| 想法入口 | `devflow new <slug>` | `proposal.md`、`state.json` | 没有外部材料时创建 change |
+| 极简入口 | `devflow new <slug> --micro` / `--level=L0` | `plan.md`、`state.json(level=L0, mode=micro)` | L0 改动直接从 plan 开始 |
+| 立项 | `devflow propose` | `proposal.md` | 补齐问题背景、目标、范围 |
+| 需求 | `devflow requirement` | `requirement.md` | 形成业务契约和验收口径 |
+| 设计 | `devflow design [--with-tests] [--with-spec]` | 默认 `design.md`；`--with-tests` 生成 `tests.md`；`--with-spec` 生成 `delta/` | 技术方案，按需生成测试策略和规格增量 |
+| 计划 | `devflow plan` | `plan.md` | 拆成 TDD task |
+| 实现记录 | `devflow apply --task=N --start|--done|--skip|--fail` | `state.json`、worktree | 记录 task 状态和隔离工作区 |
+| 审查 | `devflow review --round` | `review.md`、rounds | 按 MUST/SHOULD/NIT 判定是否打回 |
+| 测试 | `devflow test <kind>` | `reports/test-report.md#<kind>` | 执行并解析测试，写入聚合测试报告 |
+| 自测 | `devflow report self-test` | `reports/test-report.md#self-test` | 生成提测自测材料 |
+| 报告聚合 | `devflow report compact [--remove-split]` | `reports/test-report.md` | 把历史零散报告合入一份测试报告 |
+| 验证 | `devflow verify` / `devflow verify finalize` | `verify.md` | 检查 review 和必备报告 |
+| 部署 | `devflow deploy <env> --project=<name>` | `reports/test-report.md#deploy` | 触发 Jenkins 部署 |
+| 交付 | `devflow deliver --mode=<pr|merge|keep|discard>` | PR/MR、submit report | 交付 change，可选通知 |
+| 归档 | `devflow archive` | specs、archive、knowledge | 合并规格、沉淀知识、归档 change |
+
+### 5.2 子系统命令
+
+| 子系统 | 命令 | 说明 |
+| --- | --- | --- |
+| Provider | `devflow provider setup` | 交互式配置常用 provider |
+| Provider | `devflow provider list|status|add|remove|relogin|rotate|logout|audit` | 管理 provider 生命周期和凭证 |
+| Provider | `devflow provider import publish-code --from=<file.json>` | 导入项目/Jenkins profile 到 `projects.json` |
+| Knowledge | `devflow knowledge init|query|deposit|sync|validate|migrate|reparse` | 知识库初始化、检索、沉淀、同步、迁移和重解析 |
+| Skills | `devflow skills install|status|migrate|uninstall` | 安装和维护 IDE skills |
+| Checkpoint | `devflow checkpoint show|add|resolve|cancel` | 管理结构化用户确认点和下一步卡片 |
+| Worktree | `devflow worktree create|list|cleanup` | 手动管理 task worktree |
+| 状态 | `devflow status set-level <L0|L1|L2|L3> --reason="..."` | 调整复杂度级别；micro 升级后回到标准路由 |
+| 风险信号 | `devflow status risk <add|resolve|accept|list> <type> --reason="..."` | 记录前端/依赖/安全/CI 等专项风险,供 verify/deliver 硬闸读取 |
+| 项目设置 | `devflow update|uninstall|sync|switch|enable|disable` | 更新 marker、卸载、同步项目概览、开关能力 |
+| 体检 | `devflow status` / `devflow doctor` | 查看 change 状态和健康检查 |
+
+## 6. 每一步怎么跑
+
+### 6.1 初始化
+
+```bash
+devflow init [--ide=auto|full|minimal|none] [--with-ci=gitlab|github]
+```
+
+作用:
+
+- 创建 `devflow/` 和 workspace 目录。
+- 自动检测语言、构建工具、默认分支、remote、Jenkins job 候选。
+- 寻找项目概览文件，如 `AGENTS.md`、`README.md`。
+- 准备 `~/.devflow/providers.json`，权限收紧到 0600，并生成 `providers.example.json` 示例。
+- 根据 `--ide` 写或跳过 IDE marker。
+
+输出:
+
+- `<repo>/devflow/config.json`
+- `<repo>/devflow/specs/`
+- `~/.devflow/workspace/changes/`
+- `~/.devflow/workspace/archive/`
+- `~/.devflow/workspace/knowledge/`
+
+价值:让通用 skill 能读取项目专属上下文，同时避免每个项目重复安装大量静态 workflow 文档。
+
+### 6.2 入口材料
+
+```bash
+devflow ingest https://wiki.example.com/pages/123
+devflow ingest SCRUM-15803
+devflow ingest incident:42
+devflow ingest ./prd.md
+devflow ingest https://wiki.example.com/pages/123 --follow-links
+devflow new coupon-grant-api
+devflow new typo-fix --micro
+devflow new typo-fix --level=L0
+devflow ingest ./prd.md --project-root=/path/to/project-a,/path/to/project-b
+devflow new coupon-grant-api --project-root=/path/to/project-a
+```
+
+作用:
+
+- `ingest` 根据输入类型调用 `intake` 或 `issue` provider。
+- 保存原始材料到 `refs/`。
+- 使用 `--follow-links` 时，额外抓入口页中的一层同域 Wiki 链接或本地 markdown/txt 链接，保存到 `refs/linked-*.md`，并写 `refs/link-index.md`。
+- 保存图片附件到 `refs/assets/`。
+- 渲染 `proposal.md`。
+- 初始化 `state.json`。
+- `devflow new --micro` 和 `devflow new --level=L0` 是例外入口：CLI 直接写入 `state.level=L0`、`state.mode=micro`、`currentPhase=plan`，生成轻量 `plan.md`，并把 `requirement`、`design`、`archive` 标记为 skipped。
+- 如果传入 `--project-root`，会在创建 change 前确认项目，使用第一个项目的 git branch 生成 `<branch>-<slug>`，并把项目 root、角色、branch 写入 `state.projects`。
+- 同时写入 `project-roots.json`，作为当前 change 的项目路径清单；多个项目不在同一个父目录时，后续阶段直接读这个文件，不再依赖当前 shell 目录重新搜索。
+
+输出:
+
+```text
+~/.devflow/workspace/changes/<slug>/
+├── refs/
+│   ├── linked-*.md            # --follow-links 时按需生成
+│   └── link-index.md          # --follow-links 时记录抓取/跳过原因
+├── proposal.md
+├── project-roots.json        # 已确认项目路径清单，按需生成
+├── requirement.md
+├── design.md
+├── plan.md
+├── review.md
+├── verify.md
+├── reports/                 # 按需
+├── tests.md                 # 按需
+├── delta/                   # 按需
+└── state.json
+```
+
+价值:保留“需求来源”，避免后续只看 agent 总结而丢掉原文。
+
+### 6.3 复杂度分级
+
+复杂度分级由 `complexity-grading` skill 执行，写入 `state.json.level`。CLI 当前不会自动替用户拍板。
+
+`state.json` 中会记录本次确认过的级别和审计信息，例如：
+
+```json
+{
+  "level": "L2",
+  "levelSetAt": "<ISO timestamp>",
+  "levelSource": "complexity-grading",
+  "problemCardConfirmedAt": "<ISO timestamp>",
+  "projectConfirmationAt": "<ISO timestamp>",
+  "levelAudit": []
+}
+```
+
+```text
+L0: 极简改动，范围极小，改法已确定
+L1: 小 diff、低风险、无契约变化
+L2: 多文件、接口或业务契约变化，默认级别
+L3: 跨服务、性能、安全、合规、迁移或回滚风险
+```
+
+不同 level 不是完全相同的流程：
+
+| Level | 流程形态 | 使用 skill 重量 |
+| --- | --- | --- |
+| `L0` | 极简路径：`plan -> apply -> review -> verify(unit) -> deliver` | 最少；通常不走完整 `requirement-analysis` / `tech-spec` / `test-spec` / `archive` |
+| `L1` | 标准路径轻量版 | 需求和设计可短，测试策略可内联到 `plan.md` |
+| `L2` | 默认标准路径 | 双轮需求澄清、标准设计、测试计划、review、verify |
+| `L3` | 加强版标准路径 | 更深代码侦察、更完整设计、e2e/性能/回归/回滚/监控要求更高 |
+
+L0/micro 的路由由 CLI 硬控制，不只写在 skill 说明里。`df-orchestrator` 负责识别“极简 / 不要文档 / 直接写 / 就改一行”等意图，然后调用 `devflow new <slug> --micro` 或 `devflow new <slug> --level=L0`；真正的状态落地由 CLI 完成。后续 `requirement`、`design` 会同时检查 `state.mode=micro` 和 `state.level=L0`，旧 change 只有 `level=L0` 也会拒绝进入文档阶段；`archive` 看到 micro 或 L0 也会拒绝。如果 apply 过程中发现范围扩大，先升级再补标准产物：
+
+```bash
+devflow status set-level L1 --slug=<slug> --reason="micro scope expanded"
+devflow requirement
+devflow design
+devflow plan
+```
+
+apply 的并行执行由 plan 自动推导：plan 审查确认后，`devflow apply` / `/df:apply` 就是按 plan 执行的授权；如果 ready wave 中有 ≥2 个互不依赖 task，agent 应自动使用 subagent + worktree 并行分派。用户不需要每次显式说"并行"，只在想覆盖默认策略时说明"直接做"、"不用子 agent"或"强制并行/不并行"。
+
+价值:让流程重量跟风险匹配。拿不准时按 L2 处理，后续发现风险扩大再升级。
+
+> 新的 skill 编排能力见 [Workflow Orchestration](workflow-orchestration.md)。`level` 只表示风险和验证强度；每个 change 的实际 skill 路径由 `devflow flow recommend/draft/confirm` 生成的 `state.workflow.steps` 决定。
+
+### 6.4 需求分析
+
+```bash
+devflow requirement
+devflow requirement --project-root=/path/to/project-a,/path/to/project-b
+devflow requirement --search-root=/path/to/multi-project-root
+```
+
+作用:
+
+- 创建或补齐 `requirement.md`。
+- 由 `requirement-analysis` skill 引导 agent 把 proposal/refs 变成业务契约。
+- 在入口命令已通过 `--project-root` 选过项目时复用 `state.projects`；如果需要补选或覆盖，可在本阶段传 `--project-root`。
+- 在多项目目录下执行 project routing：发现候选项目、按需求证据评分，并把推荐写入 `state.projects`。
+
+输出关注点:
+
+- 功能目标
+- 范围内/范围外
+- 验收标准
+- 业务规则
+- 异常路径
+- 契约消费者影响:URL、query、redirect、callback、接口字段、枚举、状态语义变化时，列出前端、调用方、轮询页、网关、缓存 key 等消费者
+- 未决问题
+
+价值:把“材料描述”转成“可验收契约”，防止设计和实现阶段各自理解。
+
+### 6.5 技术设计与测试设计
+
+```bash
+devflow design
+devflow design --with-tests
+devflow design --with-tests --with-spec
+```
+
+作用:
+
+- 默认只创建 `design.md`。
+- 传 `--with-tests` 时创建 `tests.md`；L1/L2 可以把测试策略内联在 `plan.md` 的 task 里。
+- 传 `--with-spec` 或确有长期能力变化时准备 `delta/added|modified|removed`。
+- 由 `tech-spec` 和 `test-spec` skills 约束方案内容。
+
+输出关注点:
+
+- 改动点和影响面
+- 模块边界
+- 数据和接口契约
+- 契约消费者影响矩阵:同时写清提供方改动、消费者适配、旧依赖方式、新状态来源、兼容和迁移策略
+- 异常处理
+- 灰度、回滚、兼容
+- 测试策略
+- 对长期规格的影响
+
+价值:把需求翻译成可实施方案，并把会影响长期能力的内容通过 delta 留给 archive 合并。
+
+契约消费者影响矩阵用于处理跨项目细节遗漏。典型场景是旧签约 `returnUrl` 带订单参数，新接入方只支持无参数回跳；此时 design 必须说明前端签约结果/轮询页的轮询 key 来源，以及刷新、直达、返回、老链接兼容，而不能只写后端回跳 URL 怎么生成。矩阵中的每一项后续都要进入 `tests.md` 或 `plan.md`，形成可执行的 consumer / frontend / e2e / integration 验证项。
+
+### 6.6 计划拆分
+
+```bash
+devflow plan
+```
+
+作用:
+
+- 创建 `plan.md`。
+- 由 `plan` skill 把设计拆成 30-60 分钟粒度的 TDD task。
+
+每个 task 应包含:
+
+- 文件范围
+- 行为变化
+- 先写什么失败测试
+- 最小实现
+- 验证命令
+- 提交意图
+
+价值:让实现阶段有清晰边界，方便 worktree 并行和 reviewer 对照检查。
+
+### 6.7 Apply 与实现记录
+
+```bash
+devflow apply --task=1 --start --note="kick off"
+devflow apply --task=1 --done --note="unit pass"
+devflow apply --task=2 --skip --note="covered by task 1"
+devflow worktree list
+devflow worktree cleanup --keep-branch
+```
+
+作用:
+
+- 为 task 创建 `.devflow-worktrees/<slug>/<task-id>/`。
+- 创建 task 分支，默认命名 `devflow/<slug>/<task-id>`。
+- 记录 task 状态、worktree、branch、note、时间。
+
+重要边界:`apply` 不写业务代码，代码由人或 agent 在对应工作区完成。
+
+价值:让实现动作可追踪，也给多 agent 并行提供明确隔离边界。
+
+#### 子 agent 并行实现
+
+当前 CLI 不内置 LLM runtime，也不会自己启动子 agent。子 agent 并行实现是 **skill / IDE agent 层协议**:
+
+- `devflow apply` 负责创建 worktree、记录 task 状态、写 `state.json`。
+- 父 agent/controller 负责读取 `plan.md`，计算哪些 task 可以并行。
+- 实现子 agent 在各自 worktree 里写测试、实现、跑测试、commit。
+- reviewer 子 agent 做 apply 阶段的 pre-review。
+- controller 最后执行 `devflow apply --task=N --done --note="<commit sha>"`。
+
+`skills/apply/SKILL.md` 里的规则是:只要 `plan.md` 中 task 数量 ≥ 2，父 agent 不应自己顺序写完多个 task，而应按依赖关系分 wave 派发子 agent。同一批 ready task 里如果有 ≥ 2 个互不依赖、没有共享文件的 task，应并行启动。
+
+```mermaid
+flowchart TD
+  A["controller 读取 plan.md"] --> B["计算 ready wave"]
+  B --> C{"wave 内是否有多个独立 task?"}
+  C -->|是| D["并行启动多个实现子 agent"]
+  C -->|否| E["启动单个实现子 agent"]
+  D --> F["每个子 agent 在独立 worktree TDD + commit"]
+  E --> F
+  F --> G["规格合规 reviewer 子 agent"]
+  G --> H{"通过?"}
+  H -->|否| F
+  H -->|是| I["代码质量 reviewer 子 agent"]
+  I --> J{"通过?"}
+  J -->|否| F
+  J -->|是| K["controller 执行 apply --done"]
+  K --> L{"还有 ready wave?"}
+  L -->|有| B
+  L -->|无| M["devflow review --round"]
+```
+
+这个设计的原因是:多 task 场景下，父 agent 连续实现多个 task 容易污染上下文，也容易把一个 task 的隐含假设带到另一个 task。worktree + 子 agent 让任务边界、diff、测试证据和 pre-review 都更清楚。
+
+### 6.8 Code Review
+
+```bash
+devflow review --round
+devflow review --round --must=0 --should=2 --nit=3
+devflow review --force-pass --reason="verified offline"
+```
+
+规则:
+
+- `MUST = 0`:通过。
+- `MUST > 0`:打回 apply。
+- 第 3 轮仍有 MUST:blocked。
+- 继续第 4 轮需要 `--continue-rounds`。
+- 强行通过必须写 `--reason`。
+
+通过不等于直接开始 verify。review 通过或强制通过会创建 `verify_start` checkpoint；`devflow verify` 会先检查这个 checkpoint，未确认时只展示下一步卡片，不会继续验证。用户确认命令是 `devflow checkpoint resolve --id=<checkpoint-id> --decision=start-verify`，确认后再单独运行 `devflow verify --slug=<slug>`；需要应急绕过时使用 `devflow verify --force --reason="..."` 留痕。
+
+价值:把 review 从“看过了”变成可计数、可打回、可审计的闭环。
+
+### 6.9 测试、部署与验证
+
+```bash
+devflow test unit
+devflow test integration --cmd="npm run test:integration"
+devflow test contract --cmd="npm run test:contract"
+devflow test remote --preflight --api-base-url=https://test-api.example.com --cmd="npm run test:remote"
+devflow test joint --preflight --cmd="npm run test:e2e" --backend-url=http://localhost:8080 --frontend-url=http://localhost:3000
+devflow test smoke --cmd="curl -fsS http://localhost:3000/health"
+devflow report self-test
+devflow verify
+devflow verify finalize
+```
+
+测试类型:
+
+```text
+unit, integration, contract, e2e, joint, remote, smoke, regression, perf
+```
+
+`unit` 支持自动检测；其他类型通常需要 `--cmd`。如果维护了 `~/.devflow/projects.json`，可按项目 profile 解析命令:
+
+```bash
+devflow provider import publish-code --from=./publish-code-config.json
+devflow deploy test --project=go-rocket-push-agent --tag=v1.9.29
+devflow test smoke --project=go-rocket-push-agent --env=test
+```
+
+`devflow deploy` 默认把部署证据写入 `reports/test-report.md#deploy`，不再额外生成 `deploy-<env>.md`，也不自动刷新 self-test，避免一次部署额外制造多份报告。`devflow deploy test` 会检查当前分支:已经在 `test` 分支时直接触发 Jenkins；在 feature/dev 分支时交互询问是否合入 `test` 并推送后触发。Jenkins job 候选会按 git group/project、环境名、deploy/test 命名习惯做智能排序，覆盖 `group-project-test`、`project-test`、`project-test2`、`deploy/project`、`project-<env>` 等常见格式。非交互脚本使用 `--merge-to=test` 显式启用；需要本地编译闸门时加 `--preflight` 或在项目 profile 的 `deploy.<env>.preflight` 配置命令。确实希望把部署证据同步写进自测材料时，显式加 `--update-self-test`。
+
+这些报告文件不是让每个需求都“无脑生成一套”。人看的材料默认收敛成 `reports/test-report.md` 一份；每类测试只是其中一个 section，供 verify 判闸、失败回流和审计追溯使用。只有显式加 `--split-report` 时才额外生成兼容旧工具的零散 markdown 文件。历史 change 已经有 `unit-test.md` / `smoke-test.md` 等散文件时，运行 `devflow report compact` 可合入聚合报告；确认不再需要散文件时加 `--remove-split` 清理。
+
+| 文件 | 由什么命令生成 | 证明什么 | 什么时候需要 |
+| --- | --- | --- | --- |
+| `test-report.md#unit` | `devflow test unit` | 单元级行为、函数/模块逻辑、覆盖率 | 几乎所有代码改动都需要，是最基础报告 |
+| `test-report.md#integration` | `devflow test integration --cmd=...` 或项目 profile | 模块间、服务间、DB/缓存/队列等集成路径 | L2/L3 或任何涉及接口、数据层、外部依赖的改动 |
+| `test-report.md#contract` | `devflow test contract --cmd=...` | 调用链一致性:提供方/调用方字段、枚举、状态语义、回调、redirect/query、traceId/requestId、YAPI/OpenAPI 契约 | 有接口契约、回调、跳转、前后端/跨服务消费者时 |
+| `test-report.md#e2e` | `devflow test e2e --cmd=...` | 从用户/API 入口到下游依赖的完整链路 | L3、跨服务、核心链路、端到端风险较高时 |
+| `test-report.md#joint` | `devflow test joint --cmd=... --backend-url=... --frontend-url=...` | 前后端联调，记录后端/前端地址、浏览器操作步骤、截图、失败详情 | 有前端页面或跨项目消费者适配时；参考 arb-workflow-kit 的 test-executor 联调模式 |
+| `test-report.md#remote` | `devflow test remote --cmd=... --api-base-url=...` | 已部署测试环境上的真实 API 验收，记录请求/响应和失败详情 | 纯后端已部署到测试环境，需要绕过本地 Mock 直接验接口时 |
+| `test-report.md#smoke` | `devflow test smoke --cmd=...` 或项目 profile | 部署后关键入口是否可用 | L1/L2/L3 都建议有；小改动也至少做冒烟 |
+| `test-report.md#self-test` | `devflow report self-test` | 人工提测自测、灰度观察、回归说明 | L2/L3 必备；需要提测通知或 PR 说明时很有用 |
+
+`remote` / `joint` 支持 `--preflight`。`remote` 会先检查 `--api-base-url` 是否可达；`joint` 会按 agent-browser → chrome-devtools-mcp → playwright 探测浏览器自动化工具，并检查 `--backend-url`、`--frontend-url` 可达性。预检失败会写 `status: blocked`、`failureType: env_error`，测试命令失败会写 `failureType: code_error`。`verify finalize` 遇到 fail/blocked 报告会阻塞，并根据 failureType 提示是回 apply 修代码还是先处理环境。
+
+接口契约和日志证据走 provider：`api.yapi` 用于 `devflow sync yapi --file=<openapi.json|api.md>`，把设计产出的 OpenAPI/Swagger 或接口说明同步到 YAPI；`observability.sls` / `observability.oss` 用于 `devflow logs query --trace-id=<id>`、`--request-id=<id>` 或 `--query=<keyword>`，把 SLS/OSS 检索结果作为 `#contract`、`#remote`、`#self-test` 的辅助证据。核心流程只定义 provider 和报告形状，不把内网 SDK 或 token 写进仓库。
+
+风险信号是 level 之外的 CLI 硬闸。agent / 人类在发现专项风险时用 `devflow status risk add <type> --reason="..."` 写入 `state.json.riskSignals[]`;`verify finalize` 和 `deliver` 只看这个结构化状态,不依赖聊天记忆。
+
+| 风险信号 | 典型来源 | verify 额外要求 | deliver 行为 |
+| --- | --- | --- | --- |
+| `frontend_change` | React/Vue/Next/Vite/CSS/UI/页面/轮询页 | 必须有 `test-report.md#joint` 或 `#e2e` | open 时阻止交付 |
+| `dependency_change` | package/go module/maven/python 依赖或 lockfile | 必须有 `#unit` + `#integration` | open 时阻止交付 |
+| `security_sensitive` | 支付/鉴权/权限/隐私/回调/上传/OSS/SLS/token/cookie | 必须有 contract/integration/e2e/self-test 中的安全验证证据 | open 时阻止交付 |
+| `ci_failure` | Jenkins/GitHub Actions/GitLab CI required check 失败 | 不由 verify 自动关闭,需要修复后 resolve 或审计 accept | open 时阻止交付 |
+
+常用命令:
+
+```bash
+devflow status risk add frontend_change --slug=<slug> --reason="UI diff touched"
+devflow status risk resolve frontend_change --slug=<slug> --evidence=reports/test-report.md#joint
+devflow status risk accept ci_failure --slug=<slug> --reason="known baseline accepted by release owner"
+```
+
+是否有必要生成这么多，取决于 level:
+
+- L0:通常只要 `test-report.md#unit`。极简文案/配置类改动如果没有可跑单测，需要在 `verify.md` 写明替代验证；若改动部署后才可见，再补 `#smoke`。
+- L1:通常只要 `#unit` + `#smoke`。小改动没必要硬凑 integration/e2e。
+- L2:需要 `#unit`、`#integration`、`#smoke`、`#self-test`，因为已经涉及多文件或契约变化；涉及调用方/回调/跳转链路时补 `#contract`。
+- L3:需要 `#unit`、`#integration`、`#e2e`、`#smoke`、`#self-test`，并按风险补 contract/perf/regression。
+
+也就是说，报告数量不是流程炫技，而是为了让 verify 能回答一个具体问题:“这次改动在对应风险层级上，有没有足够证据可以交付？”如果某类测试对当前改动没有意义，应该在 `verify.md` 或自测报告里说明原因，而不是生成空报告凑数。
+
+`verify finalize` 按 level 检查报告:
+
+| Level | 必备报告 |
+| --- | --- |
+| L0 | `test-report.md#unit` |
+| L1 | `test-report.md#unit`、`#smoke` |
+| L2 | `test-report.md#unit`、`#integration`、`#smoke`、`#self-test`；链路契约变化补 `#contract` |
+| L3 | `test-report.md#unit`、`#integration`、`#e2e`、`#smoke`、`#self-test`；跨服务链路补 `#contract` |
+
+价值:交付前不只说“已测试”，而是留下结构化报告和验证证据。
+
+### 6.10 交付
+
+```bash
+devflow deliver --mode=pr
+devflow deliver --mode=pr --notify
+devflow deliver --mode=keep
+```
+
+前置闸门:
+
+- `review.status = completed`
+- `verify.status = completed`
+- `doctor.audit(change, git, cred)` 无 error
+
+跳过 doctor:
+
+```bash
+devflow deliver --skip-doctor --reason="..."
+```
+
+当前 mode:
+
+- `pr`:通过 `vcs` provider 创建 PR/MR。
+- `merge`:当前为人工辅助入口。
+- `keep`:保留 change，稍后再交付。
+- `discard`:当前为人工辅助入口。
+
+`--notify` 会生成两份提测材料：`reports/submit.md` 作为邮件正文和本地提测单，包含基本信息、变更内容、库表变更、测试重点和自测概览；库表变更从 `design.md` 的 DDL / 数据层章节和根目录 `ddl.sql` 抽取，优先整理为"新建表 / 新增字段 / 修改字段 / 删除字段"表格；`reports/test-report.md` 作为默认唯一测试附件，合并 unit / integration / e2e / joint / remote / smoke / self-test / deploy 等报告，并参考 arb-workflow-kit 的联调测试格式整理"环境信息、执行结果、用例执行详情、失败详情"。邮件正文不再包含本地 markdown 链接，默认也不附 requirement/design/plan 和多个原始测试报告；如果测试需要技术方案和任务拆解，可显式加 `--attach-design-plan` 只附 `design.md` / `plan.md`；确实需要全部原始文档或报告时，可显式加 `--attach-docs` / `--attach-reports` / `--attach=<path>`。收件人优先使用命令行 `--notify-to/--to`、`--notify-cc/--cc`；未传时读取 `notify.smtp` provider 的 `config.defaults.to` / `config.defaults.cc`，这些默认值可在 `devflow provider setup` 中配置。发送前会展示 Subject、To、Cc、附件和正文预览。发送结果只声明 SMTP/MTA 是否接受消息：直连外部 SMTP 时输出 `accepted by SMTP server`，本机 `localhost:25` / sendmail / postfix 只输出 `queued by local SMTP/MTA` 并提示检查队列，不再把本机入队说成真实送达。
+
+L0/micro change 在 deliver 时默认按 `--notify=test-report` 处理：生成 `reports/submit.md` 和 `reports/test-report.md`，有非本地 notify provider 时发送测试结果通知；没有 provider 时只保留本地报告并跳过发送。deliver 完成后直接终止流程，不进入 archive。
+
+价值:把 PR/MR 描述、提测自测、报告附件和凭证检查放在一个交付闸门里。
+
+### 6.11 归档
+
+```bash
+devflow archive
+devflow archive --dry-run
+devflow archive --force
+```
+
+作用:
+
+- 合并 `delta/**/*.md` 到 `<repo>/devflow/specs/`。
+- 沉淀 change 中可复用知识到 workspace knowledge。
+- 配置 KB provider 时同步到远端 KB 或创建知识库 MR。
+- 移动 change 到 `~/.devflow/workspace/archive/<date>-<slug>/`。
+
+价值:一次需求结束后，不只留下代码，还把“系统能力变化”和“经验教训”转成长期资产。
+
+## 7. Provider 体系
+
+Provider 类型:
+
+```text
+intake, issue, vcs, ci, notify, kb, api, observability
+```
+
+配置合并顺序:
+
+```text
+<repo>/devflow/providers.json > ~/.devflow/providers.json > local fallback
+```
+
+当前内置 driver:
+
+| 类型 | Driver | 主要用途 |
+| --- | --- | --- |
+| `intake` | `confluence`、`local` | 拉取 Wiki/PRD 或读取本地材料 |
+| `issue` | `local` | Issue 兜底 |
+| `ci` | `jenkins`、`local` | 触发 Jenkins job |
+| `api` | `yapi` | YAPI / OpenAPI 契约同步 |
+| `observability` | `sls`、`oss` | SLS / OSS 日志检索 |
+| `notify` | `smtp`、`local` | 提测通知 |
+| `kb` | `weknora`、`git`、`local` | 知识库同步或 MR |
+| `vcs` | `local` | PR/MR 兜底接口 |
+
+常用命令:
+
+```bash
+devflow provider setup
+devflow provider list
+devflow provider status
+devflow provider add intake.confluence --type=intake --driver=confluence
+devflow provider rotate kb.weknora --config-token='${env:WEKNORA_TOKEN}'
+devflow provider audit
+```
+
+凭证要求:
+
+- 用户级配置放 `~/.devflow/providers.json`。
+- 示例配置放 `~/.devflow/providers.example.json`，公共地址会预填，个人凭证保留 `${env:VAR}` 占位。
+- `notify.smtp` 支持 `config.defaults.to` / `config.defaults.cc` 作为提测邮件默认收件人和抄送人。
+- 文件权限应为 0600。
+- token 推荐写 `${env:VAR}`。
+- 不把 token 写入 `reports/`、`proposal.md`、PR 描述或日志。
+
+## 8. Knowledge 体系
+
+当前知识库是 4 个领域组、10 个扁平分类目录，目录名也是远端 KB tag 名:
+
+| 领域组 | slug | 目录/tag |
+| --- | --- | --- |
+| domain | `concepts` | `领域概念` |
+| domain | `rules` | `业务规则` |
+| domain | `scenarios` | `业务场景` |
+| system | `contracts` | `接口契约` |
+| system | `decisions` | `架构决策` |
+| system | `services` | `服务信息` |
+| ops | `environments` | `环境配置` |
+| ops | `incidents` | `故障复盘` |
+| ops | `runbooks` | `运维手册` |
+| archive | `solutions` | `解决方案` |
+
+同步流程:
+
+```mermaid
+flowchart LR
+  A["knowledge/*.md"] --> B["计算 sha256"]
+  B --> C["读取 .meta.json"]
+  C --> D{"本地与 meta 一致?"}
+  D -->|一致| E["noop"]
+  D -->|新文件| F["provider.upload"]
+  D -->|内容变化| G["provider.update"]
+  D -->|meta 有 uuid 但文件删除| H["provider.delete"]
+  F --> I["写 uuid / sha / tag"]
+  G --> I
+  H --> I
+```
+
+常用命令:
+
+```bash
+devflow knowledge query "keyword"
+devflow knowledge deposit --slug=<slug>
+devflow knowledge deposit --mr
+devflow knowledge sync --provider=kb.weknora
+devflow knowledge sync --all
+devflow knowledge reparse --provider=kb.weknora
+```
+
+默认行为:`knowledge sync` 只同步当前 change 的 `knowledge/`；`--all` 才扫描全局 workspace knowledge 和所有 active change。
+
+## 9. Skills 体系
+
+当前仓库有 17 个 skill:12 个核心流程 skill 加 5 个可选扩展 skill。核心流程 skill 维持主干 phase;扩展 skill 按 diff、level、CI 状态和风险信号触发。
+
+```text
+devflow-df-orchestrator
+devflow-brainstorm
+devflow-complexity-grading
+devflow-requirement-analysis
+devflow-tech-spec
+devflow-test-spec
+devflow-plan
+devflow-apply
+devflow-code-review
+devflow-verify
+devflow-deliver
+devflow-archive
+```
+
+可选扩展:
+
+```text
+devflow-frontend-quality
+devflow-ci-fix
+devflow-dependency-upgrade
+devflow-handoff-resume
+devflow-security-hardening
+```
+
+详细说明见 [marketplace-skills.md](/Users/chenguangyao/personal/workspace/node/devflow-kit/docs/marketplace-skills.md)。
+
+用户级安装路径:
+
+```text
+~/.devflow/skills/devflow-kit/          # 实体目录
+~/.cursor/skills/devflow-kit  -> ~/.devflow/skills/devflow-kit
+~/.claude/skills/devflow-kit  -> ~/.devflow/skills/devflow-kit
+~/.agents/skills/devflow-kit  -> ~/.devflow/skills/devflow-kit
+```
+
+项目级 `devflow init` 不使用软链，仍在当前仓库 `.cursor/skills/devflow-kit/`、`.claude/skills/devflow-kit/` 和 `.agents/skills/devflow-kit/` 下复制实体文件，便于仓库自包含。
+
+CLI 和 skill 的配合关系:
+
+| CLI 做什么 | Skill 做什么 |
+| --- | --- |
+| 写模板和状态 | 判断内容质量和阶段是否满足 |
+| 管理 checkpoint、phase gate 和下一步卡片 | 说明确认点背后的业务/技术含义 |
+| 创建 worktree | 要求 TDD、task 边界、必要验证 |
+| 统计 review 计数 | 指导 reviewer 查问题、分 MUST/SHOULD/NIT |
+| 检查报告是否存在 | 要求完成前必须有 fresh evidence |
+| 归档 delta 和 knowledge | 约束哪些经验应该沉淀 |
+
+原则上，Skill 不应该成为流程状态的唯一事实源。它可以建议“需要用户确认项目范围”，但是否真的卡住、有哪些选项、用户选了什么、什么时候解除，都应该写入 CLI 管理的状态。这样做的好处是:同一套流程可以被不同 IDE、不同 agent、CI 脚本和人工命令行共同使用，而不会依赖某一次对话是否把卡片展示完整。
+
+## 10. 当前边界
+
+- `devflow-kit` 不直接调用 LLM。
+- `apply` 不写业务代码，只维护 task、worktree、branch、state 和 note。
+- `merge`、`discard` 在 deliver 中仍偏人工辅助。
+- VCS 当前只有 local fallback，真实 PR/MR 需要后续 driver 或外部 CLI 集成。
+- `provider add` 的 hints 包含一些未来 driver 字段，但 loader 只会加载当前存在的 `src/providers/drivers/<type>-<driver>.js`。
+- README 和本文以当前源码为准；历史 RFC 或迁移文档里的旧路径、旧知识库分类需要重新核对后再使用。