@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 仓库运行。

当前实现一眼过

入口材料或想法
  -> 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 / 下一步卡片。

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。

当前已经接入的硬闸：

• 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 会被拒绝。

主目录分成三块:

<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，多个项目不在同一个父目录时也不需要反复到当前目录扫描。

安装

推荐全局安装，这样 devflow / dfk 命令会进入 npm 的全局 bin 目录:

npm i -g @chenguangyao/devflow-kit

如果只是普通本地安装:

npm i @chenguangyao/devflow-kit

shell 里不会直接出现全局 devflow 命令。可以用:

npx devflow provider setup
./node_modules/.bin/devflow provider setup

如果已经用了 npm i -g 但 zsh 仍然提示 command not found: devflow，先检查 npm 全局 bin 是否在 PATH:

npm config get prefix
which devflow
which dfk

常见修复是把 npm 全局 bin 加到 ~/.zshrc。例如 prefix 是 /opt/homebrew 时:

export PATH="/opt/homebrew/bin:$PATH"

如果 prefix 是 ~/.npm-global，则加:

export PATH="$HOME/.npm-global/bin:$PATH"

安装后可选做一次全局初始化:

devflow skills install --scope=user
devflow provider setup

然后在每个项目里接入:

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 时安装到 ~/.codex/skills、~/.claude/skills、~/.cursor/skills，不把 skill 复制进业务仓。

常用选项:

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 段

快速工作流

# 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：

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:

unit, integration, contract, e2e, joint, remote, smoke, regression, perf

unit 会尝试自动检测测试框架和命令；其他类型通常需要 --cmd。如果维护了 ~/.devflow/projects.json，也可以通过项目 profile 解析命令:

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 配置合并顺序:

<repo>/devflow/providers.json  >  ~/.devflow/providers.json  >  local fallback

常用命令:

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。

当前仓库内置 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 名:

~/.devflow/workspace/knowledge/
├── 领域概念/
├── 业务规则/
├── 业务场景/
├── 接口契约/
├── 架构决策/
├── 服务信息/
├── 环境配置/
├── 故障复盘/
├── 运维手册/
└── 解决方案/

常用命令:

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 硬拉成重流程。

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

可选扩展:

devflow-frontend-quality
devflow-ci-fix
devflow-dependency-upgrade
devflow-handoff-resume
devflow-security-hardening

扩展 skill 的触发条件和接入点见 docs/marketplace-skills.md。

维护命令:

devflow skills install --scope=user
devflow skills install --scope=user --copy
devflow skills install --scope=project --target=cursor,claude
devflow skills status
devflow skills migrate --scope=user
devflow skills uninstall --scope=project

用户级默认只保存一份实体文件，然后把各 IDE 的 namespace 目录软链过去:

~/.devflow/skills/devflow-kit/          # 实体目录
~/.codex/skills/devflow-kit   -> ~/.devflow/skills/devflow-kit
~/.cursor/skills/devflow-kit  -> ~/.devflow/skills/devflow-kit
~/.claude/skills/devflow-kit  -> ~/.devflow/skills/devflow-kit

--copy 用于不希望使用软链的环境。devflow init 默认使用用户级安装，避免把 skill 复制进业务仓；项目级安装只在显式 --scope=project 或 --skills-target 时使用。

分级与验证

复杂度分级由 complexity-grading skill 初判并等用户确认，确认后写入当前 change 的 state.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 虽然走了流程、但漏掉专项风险证据:

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 或接口契约变化，先升级再补标准文档：

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 写明理由。

推荐命令:

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 里的能力需要重新确认后再使用。

本仓库开发

npm test
npm run pack:dry
node bin/devflow.js help

遵循本仓库 AGENTS.md:

• 不在 main/master 直接编码。
• 文档与代码同 PR 评审。
• RFC 类变更先动 docs/RFC-*.md。
• 不把 token、cookie、密码写入日志、报告或 PR 描述。