@chenguangyao/devflow-kit 0.1.43

package/README.md

@@ -0,0 +1,539 @@
+# @chenguangyao/devflow-kit
+
+`devflow-kit` 是一套文件优先的开发工作流 CLI + Skills 套件。它把一次需求从入口材料、需求分析、技术设计、计划拆分、实现记录、审查、验证、交付到归档，压成一组可读、可审计、可被 IDE agent 继续接手的本地文件。
+
+- 包名: `@chenguangyao/devflow-kit`
+- CLI: `devflow`，短别名 `dfk`
+- 运行时: Node.js 20+
+- 实现风格: CommonJS，低依赖，核心流程不绑定内网系统
+
+## 它解决什么问题
+
+AI 协作开发最容易丢三样东西:上下文、阶段边界、完成证据。`devflow-kit` 的设计目标是让这些东西都落文件，而不是只留在聊天记录里。
+
+- **文件优先**:阶段间靠 markdown 和 `state.json` 传递，不靠摘要记忆。
+- **入口统一**:从 Wiki、Issue、incident、本地 markdown 或一个 slug 开始，最后都汇入 `proposal.md`。
+- **分级驱动**:L0/L1/L2/L3 决定文档深度、测试种类和验证强度。
+- **契约消费者追踪**:URL、query、redirect、callback、接口字段、枚举或状态语义变化时，必须追踪前端、调用方、轮询页等消费者影响。
+- **并行友好**:`apply` 按 task 创建 worktree，适合多 agent 或多人并行。
+- **闸门可审计**:review、verify、deliver、archive 都有状态和跳过原因。
+- **外部系统可插拔**:Wiki、CI、通知、知识库等通过 provider 接入，核心命令可在裸 git 仓库运行。
+
+## 当前实现一眼过
+
+```text
+入口材料或想法
+  -> proposal.md
+  -> project-roots.json (按需，已确认项目路径)
+  -> requirement.md
+  -> design.md
+     (tests.md / delta/ 按级别和参数懒生成)
+  -> plan.md
+  -> apply worktree + state.json
+  -> review.md
+  -> reports/test-report.md
+  -> verify.md
+  -> deliver
+  -> archive + specs/ + knowledge/
+```
+
+## Workflow Kernel（进行中）
+
+devflow-kit 正在把关键流程控制从"只写在 skill 里的自然语言约束"迁移到结构化 Workflow Kernel。原因是实际使用中，完整流程不只会遇到编译测试空转，还会遇到更整体的问题：问题卡漏展示、plan 后没等用户审查、review/apply 轮次结束后没有下一步、风险和证据散落在不同输出里。
+
+当前已经引入第一块内核能力：**checkpoint / 下一步卡片**。
+
+```bash
+devflow checkpoint add --slug=<slug> \
+  --type=plan_review \
+  --phase=plan \
+  --summary="plan.md 已生成 3 个 task" \
+  --question="是否接受计划并进入 apply？" \
+  --options="accept=devflow apply;revise=devflow plan --edit"
+
+devflow checkpoint show --slug=<slug>
+devflow checkpoint show --slug=<slug> --json
+devflow checkpoint resolve --slug=<slug> --id=<checkpoint-id> --decision=accept
+```
+
+`devflow status` 会展示最新 pending checkpoint 的标准下一步卡片。这样做的好处是：
+
+- **用户确认点更稳**：复杂度分级、项目确认、plan 审查、review 返工等都可以逐步变成结构化 checkpoint。
+- **下一步更清楚**：停在任何阶段时，CLI 能统一渲染"为什么停、可选项、下一条命令"。
+- **agent 更不容易越级**：后续 phase gate 可以检查 unresolved checkpoint，避免只靠模型记住规则。
+- **风险和证据可沉淀**：baseline failure、review finding、测试报告可以逐步接入同一套 `risks` / `evidence` 字段。
+
+详细设计见 [`docs/RFC-002-workflow-kernel.md`](docs/RFC-002-workflow-kernel.md)。
+
+当前已经接入的硬闸：
+
+- `devflow new` / `devflow ingest` 会创建 `problem_card` checkpoint，要求先确认问题卡、默认复杂度和初始项目范围。
+- `devflow requirement` 如果发现 `problem_card` 仍是 pending，会拒绝继续；确认后才会生成/更新 `requirement.md`。
+- `devflow requirement` 在自动路由出项目候选后，会创建 `project_confirmation` checkpoint，要求确认涉及项目。
+- `devflow design` 如果发现 `project_confirmation` 仍是 pending，会拒绝继续，避免侦察或设计错误仓库。
+- `devflow plan` 会创建 `plan_review` checkpoint，提示用户先审查任务拆分、范围和执行模式。
+- `devflow apply` 如果发现 `plan_review` 仍是 pending，会拒绝启动并展示下一步卡片。
+- `devflow review --round` 如果发现 MUST，会创建 `review_fix` 或 `review_blocked` checkpoint，明确下一步是回到 apply 修复、继续审查还是强制通过。
+- `devflow review --round` 通过或 `--force-pass` 通过后，会创建 `verify_start` checkpoint，要求用户确认进入验证阶段；确认命令只解除闸门，不会自动串联执行 `devflow verify`；`devflow verify` 在该 checkpoint 未确认时会阻塞。
+- `devflow verify finalize` 如果缺少必需报告，会创建 `verification_evidence` checkpoint；补齐报告或使用 `--force --reason` 接受缺失证据风险后才会继续。
+- `devflow deliver` 会检查未解决的 review / evidence / risk checkpoint，避免带着未处理风险交付。
+- `devflow new --micro` 是 L0 的 CLI 真源：直接写入 `state.level=L0`、`state.mode=micro`、`currentPhase=plan`，并把 `requirement`、`design`、`archive` 标记为 skipped。
+- 紧急情况可以使用 `devflow <phase> --force --reason="..."` 审计绕过；没有 reason 会被拒绝。
+
+主目录分成三块:
+
+```text
+<repo>/
+├── devflow/
+│   ├── config.json              # 项目设置、工程画像、项目概览引用
+│   ├── specs/                   # 长期规格真源，archive 时由 delta 合入
+│   └── providers.json           # 可选，项目级 provider 覆盖
+├── .devflow-worktrees/          # apply task 的隔离 worktree
+└── ...
+
+~/.devflow/workspace/
+├── changes/<slug>/              # 当前 change 默认过程文件
+├── archive/<date>-<slug>/       # 已归档 change
+└── knowledge/<category>/        # 用户级长期知识库
+
+~/.devflow/
+├── providers.json               # 用户级 provider，chmod 0600
+├── providers.example.json       # 带公共地址的示例，个人凭证用 ${env:VAR}
+└── projects.json                # Jenkins / 项目 profile，chmod 0600
+```
+
+为了兼容老项目，CLI 仍会读取 `<repo>/devflow/changes/<slug>/` 和 `<repo>/devflow/archive/`，但当前默认写入 workspace。
+
+文档产物默认走精简策略：核心链路只保证 `proposal.md`、`requirement.md`、`design.md`、`plan.md`、`review.md`、`verify.md`。`tests.md`、`delta/`、`reports/` 等按风险级别、命令参数和实际证据需要生成，避免空模板凑数。CLI 生成的面向用户文档默认使用中文。
+
+多项目需求会额外写 `project-roots.json`，保存已确认的 primary / dependency 项目路径、branch、置信度和证据。后续阶段优先读取这个文件和 `state.json#projects`，多个项目不在同一个父目录时也不需要反复到当前目录扫描。
+
+## 安装
+
+```bash
+npm i -g @chenguangyao/devflow-kit
+```
+
+安装后可选做一次全局初始化:
+
+```bash
+devflow skills install --scope=user
+devflow provider setup
+```
+
+然后在每个项目里接入:
+
+```bash
+cd <your-project>
+devflow init
+devflow ingest <wiki-url|issue-id|incident:id>
+```
+
+`devflow init` 会:
+
+- 建 `devflow/`、workspace changes/archive/knowledge 骨架。
+- 写 `devflow/config.json`，包含语言、构建工具、默认分支、remote、项目概览引用。
+- 确保 `~/.devflow/providers.json` 存在并设为 0600，同时生成 `providers.example.json` 示例。
+- 按 `--ide` 策略写或跳过 IDE marker。
+- 在没有用户级 skills 时安装项目级 skills。
+
+常用选项:
+
+```bash
+devflow init --ide=auto                  # 默认，检测到用户级 skill 时跳过项目 IDE 文件
+devflow init --ide=full                  # 强制写 .claude / .cursor / AGENTS marker
+devflow init --ide=minimal               # 只写 devflow 配置，不写 IDE 文件
+devflow init --with-ci=gitlab            # 可选安装 CI 模板
+devflow update --ide-clean               # 清理旧 marker 段
+```
+
+## 快速工作流
+
+```bash
+# 1. 从外部材料启动
+devflow ingest https://wiki.example.com/pages/123 --follow-links
+
+# 或者从一个想法/slug 启动
+devflow new coupon-grant-api
+
+# 极简改动:CLI 直接写入 level=L0、mode=micro，并从 plan 开始
+devflow new typo-fix --micro
+# 等价写法
+devflow new typo-fix --level=L0
+
+# 2. 需求、设计、计划
+devflow requirement
+devflow design
+# 需要独立测试清单或规格增量时再加:
+# devflow design --with-tests --with-spec
+devflow plan
+
+# 3. 实现阶段只记录 task 和 worktree，代码由人或 agent 完成
+devflow apply --task=1 --start --note="start api contract"
+devflow apply --task=1 --done --note="tests pass"
+
+# 4. 审查与验证
+devflow review --round
+# review 通过后先确认 verify_start checkpoint，确认后再单独启动 verify:
+# devflow checkpoint resolve --id=<checkpoint-id> --decision=start-verify
+# devflow verify --slug=<slug>
+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
+
+# 5. 交付与归档
+devflow deliver --mode=pr --notify
+devflow archive
+```
+
+## 命令总览
+
+### 入口
+
+| 命令 | 作用 | 主要产物 |
+| --- | --- | --- |
+| `devflow ingest <url|issue-id|incident:id>` | 从 URL、Issue、incident、本地 markdown 启动 | `refs/*.md`、`proposal.md`、`state.json` |
+| `devflow new <slug>` | 没有外部材料时创建 change | `proposal.md`、`state.json` |
+| `devflow new <slug> --micro` / `--level=L0` | L0 极简改动，跳过文档 phase，直接从 plan 开始 | `plan.md`、`state.json(level=L0, mode=micro)` |
+| `devflow propose` | 生成或补齐 proposal | `proposal.md` |
+
+`ingest` 会按输入类型选择 provider:
+
+- `http://`、`https://`、`file://`、`.md` 路径: `intake`
+- `SCRUM-15803` 这类 ID: `issue`
+- `incident:<id>` / `alert:<id>`: `intake`
+
+Wiki 或本地 markdown 中经常会引用接口文档、业务规则页。默认只抓入口页；需要把入口页中的一层链接也纳入分析时，加 `--follow-links`：
+
+```bash
+devflow ingest https://wiki.example.com/pages/viewpage.action?pageId=123 --follow-links
+devflow ingest ./prd.md --follow-links --max-links=10
+```
+
+`--follow-links` 只抓入口页正文里的同域 Wiki 链接或本地 markdown/txt 链接，最大深度固定为 1 层，默认最多 10 个、硬上限 20 个。抓到的页面会写入 `refs/linked-*.md`，并生成 `refs/link-index.md` 记录已抓取和跳过原因；后续 `requirement` 会读取这些 refs 一起分析。
+
+### 生命周期
+
+| 阶段 | 命令 | 产物 | 说明 |
+| --- | --- | --- | --- |
+| 需求 | `devflow requirement` | `requirement.md` | 把 proposal/refs 整理成业务契约 |
+| 设计 | `devflow design [--with-tests] [--with-spec]` | 默认 `design.md`；`--with-tests` 生成 `tests.md`；`--with-spec` 生成 `delta/` | 生成技术方案，按需生成测试清单和规格增量 |
+| 计划 | `devflow plan` | `plan.md` | 拆成 30-60 分钟 TDD task |
+| 实现记录 | `devflow apply --task=N --start|--done|--skip|--fail` | `state.json`、worktree | 自动创建 `.devflow-worktrees/<slug>/task-N`;多 task 时由上层 agent 按 skill 协议分派子 agent |
+| 审查 | `devflow review --round` | `review.md`、review rounds | 统计 MUST/SHOULD/NIT，最多 3 轮硬闸 |
+| 测试 | `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 <test|staging> --project=<name>` | `reports/test-report.md#deploy` | 通过 Jenkins provider 触发 job |
+| 交付 | `devflow deliver --mode=<pr|merge|keep|discard>` | PR/MR 或状态记录 | PR 模式会走 VCS provider |
+| 归档 | `devflow archive` | `specs/`、archive、knowledge | 合并 delta，沉淀知识，迁移 change |
+
+### 契约消费者影响追踪
+
+当一次需求改变跨项目契约时，devflow 不只要求设计提供方怎么改，还要求追踪消费者怎么适配。这里的契约包括接口请求/响应字段、枚举、错误码、状态语义，也包括 `returnUrl`、`redirect`、`callback`、query 参数和轮询 key 这类页面/服务间传递信息。
+
+阶段分工：
+
+- `requirement-analysis`：在 L2/L3 代码侦察时搜索消费者，发现前端页面、调用方、网关、轮询页、缓存 key、`location.search` / `route.query` / `URLSearchParams` 等依赖，并把疑似新增受影响项目带回项目范围确认。
+- `tech-spec`：在 `design.md` 写“契约消费者影响矩阵”，同时说明提供方改动、消费者页面/调用方改动、旧依赖方式、新状态来源、兼容和迁移策略。
+- `test-spec` / `plan`：把矩阵里的消费者影响转成测试和 TDD task，覆盖无参数回跳、老链接兼容、轮询 key 来源、刷新/直达等场景。
+
+典型例子：旧签约 `returnUrl` 会带订单参数，新接入方只支持无参数回跳。此时不能只改后端回跳 URL，还要重新设计前端签约结果/轮询页从哪里获得轮询 key，并说明页面刷新、直达、返回、老链接的兼容策略。
+
+### 流程控制边界
+
+devflow 当前是 CLI + agent/skill 的混合控制，但真实流程状态以 CLI 写入的文件为准：
+
+| 事项 | CLI 负责 | agent / skill 负责 |
+| --- | --- | --- |
+| 真实状态 | `state.json`、phase、checkpoint、audit log | 读取状态并解释下一步含义 |
+| 能否进入下一阶段 | phase gate、checkpoint gate、报告缺失检查 | 判断业务/技术上是否建议推进 |
+| 文档内容 | 创建模板、记录路径和状态 | 读材料、澄清、侦察代码、写 `requirement.md` / `design.md` |
+| 验证证据 | `reports/test-report.md`、`verify.md`、必备 section 检查 | 选择测试策略、执行测试、解释失败原因 |
+
+目标是：**CLI 做流程账本和硬闸门，agent 做智能判断和文档生产**。agent 可以建议下一步，但不能把聊天里的“继续”当成流程事实；是否已确认、是否能进入下一阶段，最终看 `state.json` 和 checkpoint。
+
+### Checkpoint / 下一步卡片
+
+Checkpoint 是 Workflow Kernel 的结构化用户确认点，写入当前 change 的 `state.json.checkpoints[]`。它用于表达"流程为什么停、需要用户确认什么、确认后跑什么命令"。
+
+| 命令 | 作用 |
+| --- | --- |
+| `devflow checkpoint show --slug=<slug>` | 展示当前 pending checkpoint 的下一步卡片 |
+| `devflow checkpoint show --slug=<slug> --json` | 输出机器可读 checkpoint，供 IDE 渲染问题卡 |
+| `devflow checkpoint add ...` | 创建一个待确认 checkpoint |
+| `devflow checkpoint resolve --id=<id> --decision=<option>` | 标记用户已确认 |
+| `devflow checkpoint cancel --id=<id> --reason=<reason>` | 取消已过期或被替代的 checkpoint |
+
+这是从文档型流程走向产品化状态机的第一步。短期内它先服务于问题卡、项目确认、plan 审查、review 返工、verify 启动确认和风险接受；后续会继续把更多证据模型接进 `review` / `verify` / `deliver`。
+
+当前 `intake -> requirement`、`requirement -> design`、`plan -> apply`、`review -> apply/verify`、`verify -> deliver` 已接入硬闸：`devflow new/ingest` 会创建 `problem_card`；`devflow requirement` 会创建 `project_confirmation`；`devflow plan` 会创建 `plan_review`；`devflow review --round` 会按结果创建 `review_fix` / `review_blocked` / `verify_start`；`devflow verify` 会等待 `verify_start` 确认；`devflow verify finalize` 会创建 `verification_evidence`。用户确认、补证据或审计绕过后，下一阶段才会继续。这样能避免问题卡没展示、项目没确认、plan 刚生成就被自动 apply，也能避免 review 通过后自动进入 verify。
+
+### 测试报告
+
+支持的 `kind`:
+
+```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
+```
+
+当前解析器覆盖 Jest、Vitest、Mocha、Tap、Node test、Go test、Pytest、JUnit XML 和通用输出。报告会写入当前 change 的 `reports/`，并带 YAML frontmatter。
+
+`contract` 用于调用链一致性验证：检查接口提供方、调用方、回调、redirect/query、traceId/requestId、YAPI/OpenAPI 契约和测试用例是否一致。接口契约需要同步到 YAPI 时运行 `devflow sync yapi --file=<openapi.json|api.md> [--dry-run]`；联调或提测后需要查日志时运行 `devflow logs query --trace-id=<id>` 或 `--request-id=<id>`，通过 SLS/OSS provider 取证。
+
+`deploy` 会触发已配置的 Jenkins job，并把部署证据写入 `reports/test-report.md#deploy`。执行 `devflow deploy test` 时会先检查当前分支:如果已经在 `test` 分支则直接触发 Jenkins；如果在 feature/dev 分支且是交互终端，会主动询问是否执行 `feature -> test` 合并、推送后再触发。Jenkins job 候选会按 git group/project、环境名、deploy/test 命名习惯做智能排序，支持 `group-project-test`、`project-test`、`project-test2`、`deploy/project`、`project-<env>` 等常见格式。非交互脚本可显式加 `--merge-to=test`。配合 `--preflight` 会按项目语言自动做编译预检（Go: `go build ./...`，Java: `mvn compile -q -DskipTests`）。只有显式加 `--update-self-test` 时才刷新 `reports/test-report.md#self-test`。
+
+这些报告按风险级别懒生成，不是每个 change 都硬凑一套。默认只维护一份 `reports/test-report.md`，每类测试写入自己的 section；如果确实需要兼容旧工具，可对 `devflow test <kind>` / `devflow report self-test` 加 `--split-report` 额外落单独的 `<kind>-test.md` / `self-test.md`。已有 change 里如果已经生成了旧散文件，运行 `devflow report compact` 会合入 `test-report.md`，确认无误后可加 `--remove-split` 清掉旧文件。`unit` 证明基础逻辑，`integration` 证明模块/服务/数据层集成，`contract` 证明调用链/API 契约一致，`e2e` 证明完整链路，`joint` 证明前后端联调路径；`remote` 证明已部署测试环境上的真实 API 验收；`smoke` 证明部署后关键入口可用，`self-test` 记录人工提测自测和灰度说明。
+
+`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 会据此提示是回 apply 修代码还是先处理环境。
+
+### Provider
+
+Provider 配置合并顺序:
+
+```text
+<repo>/devflow/providers.json  >  ~/.devflow/providers.json  >  local fallback
+```
+
+常用命令:
+
+```bash
+devflow provider setup
+devflow provider list
+devflow provider status [<name>]
+devflow provider add <name> --type=<type> --driver=<driver>
+devflow provider import publish-code --from=<file.json>
+devflow provider rotate <name> --config-token=<new-value>
+devflow provider audit
+```
+
+企业集成能力的补充说明见 [docs/enterprise-integration-supplement.md](docs/enterprise-integration-supplement.md)。
+
+当前仓库内置 driver:
+
+| Provider 类型 | 内置 driver | 用途 |
+| --- | --- | --- |
+| `intake` | `confluence`、`local` | 拉取 Wiki/PRD 或读取本地材料 |
+| `issue` | `local` | Issue 兜底 |
+| `ci` | `jenkins`、`local` | 触发 Jenkins 部署或构建 |
+| `api` | `yapi` | 同步 YAPI / OpenAPI 接口契约 |
+| `observability` | `sls`、`oss` | 查询 SLS / OSS 日志证据 |
+| `notify` | `smtp`、`local` | 发送提测通知 |
+| `kb` | `weknora`、`git`、`local` | 同步或提交知识库 |
+| `vcs` | `local` | PR/MR 兜底接口 |
+
+`provider setup` 会引导配置 `intake.confluence`、`notify.smtp`、`kb.weknora`、`kb.git`、`ci.jenkins`、`api.yapi`、`observability.sls`、`observability.oss`。凭证建议写成 `${env:VAR}`，避免明文 token 进入配置文件。配置 `notify.smtp` 时也可以填写默认 `defaults.to` / `defaults.cc`，后续 `devflow deliver --notify` 没有传 `--to/--cc` 时会自动使用这些收件人，并在发送前预览确认。提测邮件正文来自 `reports/submit.md`，会从 `design.md` 的 DDL / 数据层章节和根目录 `ddl.sql` 提取库表变更，列出新建表、新增字段、修改字段、删除字段；默认只附一份汇总后的 `reports/test-report.md`，正文不再塞本地文档链接；需要把技术方案和任务拆解交给测试同学时显式加 `--attach-design-plan`，需要全部原始材料时加 `--attach-docs`、`--attach-reports` 或 `--attach=<path>`。`test-report.md` 会合并各类测试报告，并按联调测试的环境、结果、用例详情和失败详情整理前后端联调证据。发送结果只表示外部 SMTP 已接受，或本机 sendmail/postfix 已入队；本机入队不等于真实投递成功。
+
+### Knowledge
+
+当前知识库采用扁平分类目录，目录名也是远端 KB tag 名:
+
+```text
+~/.devflow/workspace/knowledge/
+├── 领域概念/
+├── 业务规则/
+├── 业务场景/
+├── 接口契约/
+├── 架构决策/
+├── 服务信息/
+├── 环境配置/
+├── 故障复盘/
+├── 运维手册/
+└── 解决方案/
+```
+
+常用命令:
+
+```bash
+devflow knowledge init
+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 validate
+devflow knowledge migrate --from=arb-7 --to=improved-9
+devflow knowledge reparse --provider=kb.weknora
+```
+
+`knowledge sync` 默认同步当前 change 的 `knowledge/`；传 `--all` 才扫描 workspace 全局知识库和所有 active change。存在多个 KB provider 且未传 `--provider` 时，交互式环境会让用户选择，非交互环境会阻塞并提示显式指定。
+
+### Skills
+
+仓库提供 17 个 skill:12 个核心流程 skill 加 5 个可选扩展 skill。核心流程 skill 负责 phase 编排和闸门;扩展 skill 只在对应风险出现时触发,不把 L0/L1 硬拉成重流程。
+
+```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
+```
+
+扩展 skill 的触发条件和接入点见 [docs/marketplace-skills.md](/Users/chenguangyao/personal/workspace/node/devflow-kit/docs/marketplace-skills.md)。
+
+维护命令:
+
+```bash
+devflow skills install --scope=user
+devflow skills install --scope=user --copy
+devflow skills install --scope=project --target=cursor,claude,agents
+devflow skills status
+devflow skills migrate --scope=user
+devflow skills uninstall --scope=project
+```
+
+用户级默认只保存一份实体文件，然后把各 IDE 的 namespace 目录软链过去:
+
+```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
+```
+
+`--copy` 用于不希望使用软链的环境。项目级安装仍然复制实体文件到当前仓库，避免项目依赖用户全局目录。
+
+## 分级与验证
+
+复杂度分级由 `complexity-grading` skill 初判并等用户确认，确认后写入当前 change 的 `state.json`。典型字段：
+
+```json
+{
+  "level": "L2",
+  "levelSetAt": "2026-05-13T00:00:00.000Z",
+  "levelSource": "complexity-grading",
+  "problemCardConfirmedAt": "2026-05-13T00:00:00.000Z",
+  "projectConfirmationAt": "2026-05-13T00:00:00.000Z",
+  "levelAudit": []
+}
+```
+
+后续 phase 都以 `state.json.level` 调整流程重量。CLI 的 `verify finalize` 也按 level 检查必备报告:
+
+| Level | 典型场景 | 必备报告 |
+| --- | --- | --- |
+| `L0` | 极简改动、范围极小、改法已确定 | `test-report.md#unit` |
+| `L1` | 小 diff、低风险、无契约变化 | `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` |
+
+如果是无法跑单测的 L0 文案/配置改动，需要在 `verify.md` 写明替代验证；若改动部署后才可见，再补 `test-report.md#smoke`。未知 level 当前按 L2 兜底。
+
+level 之外还有一层 CLI 风险信号,用于防止 agent 虽然走了流程、但漏掉专项风险证据:
+
+```bash
+devflow status risk add frontend_change --slug=<slug> --reason="UI diff touched"
+devflow status risk add dependency_change --slug=<slug> --reason="package-lock changed"
+devflow status risk add security_sensitive --slug=<slug> --reason="callback signature changed"
+devflow status risk add ci_failure --slug=<slug> --reason="required Jenkins check failed"
+devflow status risk resolve frontend_change --slug=<slug> --evidence=reports/test-report.md#joint
+devflow status risk accept ci_failure --slug=<slug> --reason="release owner accepted known baseline"
+```
+
+`verify finalize` 会读取 `state.json.riskSignals[]`:前端改动必须补 `#joint` 或 `#e2e`;依赖升级必须补 `#unit` + `#integration`;安全敏感改动必须补 contract/integration/e2e/self-test 中的安全相关证据。缺证据会创建 `risk_acceptance` checkpoint。`deliver` 会拒绝带着 open risk signal 交付,除非显式 `--force --reason` 审计接受。
+
+分级不是四套完全不同的产品，而是同一条流程按风险调重量：
+
+- `L0` 是极简路径，使用更少 skill：通过 `devflow new <slug> --micro` 或 `devflow new <slug> --level=L0` 进入，由 CLI 写入 `level=L0` 和 `mode=micro`，通常跳过完整 `requirement-analysis`、`tech-spec`、`test-spec`、`archive`，直接走轻量 `plan -> apply -> review -> verify(unit) -> deliver`。后续 `requirement` / `design` 会同时检查 `mode=micro` 和 `level=L0`，旧状态缺少 `mode` 也会被拦住。
+- `L1` 走标准骨架的轻量版：需求/设计可以短，测试策略可内联到 `plan.md`。
+- `L2` 是默认标准流：需求澄清、设计、测试计划、review、verify 都按标准要求执行。
+- `L3` 是加强版标准流：跨服务/架构/合规/迁移场景要更深侦察、更完整设计、更严格验证和回滚预案。
+
+如果 L0 apply 过程中发现范围扩大，比如超过单文件、出现 DDL 或接口契约变化，先升级再补标准文档：
+
+```bash
+devflow status set-level L1 --slug=<slug> --reason="micro scope expanded"
+devflow requirement
+devflow design
+devflow plan
+```
+
+并行执行也不是每次都需要用户显式指定。plan 审查确认后，`devflow apply` 本身就是按 plan 执行的授权；如果 `plan.md` 的 ready wave 中有多个互不依赖 task，agent 应自动使用 subagent + worktree 并行分派。用户只有在想覆盖默认策略时才需要明确说"直接做"、"不用子 agent"或"强制并行/不并行"。
+
+## Review 与交付闸门
+
+`devflow review --round` 会读取 `review.md` 中的 `MUST`、`SHOULD`、`NIT`:
+
+- `MUST > 0`:打回 apply。
+- `MUST = 0`:review 完成。
+- 第 3 轮仍有 MUST:进入 blocked。
+- 超过 3 轮继续审查需要 `--continue-rounds`。
+- 强行通过需要 `--force-pass --reason="..."`，原因写入 audit log。
+
+review 完成不会直接放行 verify。CLI 会创建 `verify_start` checkpoint，用户需要执行 `devflow checkpoint resolve --id=<checkpoint-id> --decision=start-verify` 明确确认；这个命令只解除闸门，不应和 `devflow verify` 串联。确认后再单独运行 `devflow verify --slug=<slug>`；紧急情况可用 `devflow verify --force --reason="..."` 留痕绕过。
+
+`devflow verify` 默认要求 review 已完成；跳过需 `--skip-review-gate --reason="..."`。
+
+`devflow deliver` 默认要求:
+
+- `verify.status = completed`
+- `review.status = completed`
+- `devflow doctor --scope change,git,cred` 无 error
+
+跳过 doctor 需 `--skip-doctor --reason="..."`。
+
+## Go 测试约定
+
+Go 项目里，devflow 的 plan/apply skill 默认建议把新增黑盒、接口、联调、回归测试放在项目根目录 `test/` 下，避免业务 package 旁散落 `_test.go`。只有必须访问未导出符号、受 `internal` import 限制，或项目已有明确同目录测试约定时，才在业务源码同目录新增 `*_test.go`，并在 `plan.md` 写明理由。
+
+推荐命令:
+
+```bash
+go test ./test/... ./...
+```
+
+## 当前边界
+
+- CLI 不直接调用 LLM。LLM 行为由 IDE skills 和上层 agent 承担。
+- `apply` 不写代码，只创建/记录 task、worktree、状态和笔记。
+- `merge`、`keep`、`discard` 等 deliver mode 在 v0.1.x 仍偏人工辅助。
+- VCS 默认是 local fallback；真实 GitHub/GitLab PR/MR 需要后续 driver 或外部 CLI 集成。
+- README 中的能力以当前源码为准；roadmap 和历史 RFC 里的能力需要重新确认后再使用。
+
+## 本仓库开发
+
+```bash
+npm test
+npm run pack:dry
+node bin/devflow.js help
+```
+
+遵循本仓库 `AGENTS.md`:
+
+- 不在 `main/master` 直接编码。
+- 文档与代码同 PR 评审。
+- RFC 类变更先动 `docs/RFC-*.md`。
+- 不把 token、cookie、密码写入日志、报告或 PR 描述。

package/bin/devflow.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/* eslint-disable */
+'use strict';
+
+require('../src/cli/index.js').main(process.argv.slice(2)).catch((err) => {
+  const log = require('../src/utils/log.js');
+  log.error(err && err.stack ? err.stack : String(err));
+  process.exit(err && err.exitCode ? err.exitCode : 1);
+});