@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 决定文档深度、测试种类和验证强度。
• 并行友好:apply 按 task 创建 worktree，适合多 agent 或多人并行。
• 闸门可审计:review、verify、deliver、archive 都有状态和跳过原因。
• 外部系统可插拔:Wiki、CI、通知、知识库等通过 provider 接入，核心命令可在裸 git 仓库运行。

当前实现一眼过

入口材料或想法
  -> proposal.md
  -> requirement.md
  -> design.md / tests.md / delta/
  -> plan.md
  -> apply worktree + state.json
  -> review.md
  -> reports/*.md
  -> verify.md
  -> deliver
  -> archive + specs/ + knowledge/

主目录分成三块:

<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。

安装

npm i -g @chenguangyao/devflow-kit

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

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 时安装项目级 skills。

常用选项:

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

# 或者从一个想法/slug 启动
devflow new coupon-grant-api

# 2. 需求、设计、计划
devflow requirement
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
devflow test unit
devflow test integration --cmd="npm run test:integration"
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 propose | 生成或补齐 proposal | proposal.md |

ingest 会按输入类型选择 provider:

• http://、https://、file://、.md 路径: intake
• SCRUM-15803 这类 ID: issue
• incident:<id> / alert:<id>: intake

生命周期

| 阶段 | 命令 | 产物 | 说明 | | --- | --- | --- | --- | | 需求 | devflow requirement | requirement.md | 把 proposal/refs 整理成业务契约 | | 设计 | devflow design [--with-tests] [--with-spec] | design.md、tests.md、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/<kind>-test.md | 运行命令、解析输出、落结构化报告 | | 自测 | devflow report self-test | reports/self-test.md | 提测自测材料 | | 验证 | devflow verify / devflow verify finalize | verify.md | 检查 review 和必备报告 | | 部署 | devflow deploy <test|staging> --project=<name> | reports/deploy-<env>.md | 通过 Jenkins provider 触发 job | | 交付 | devflow deliver --mode=<pr|merge|keep|discard> | PR/MR 或状态记录 | PR 模式会走 VCS provider | | 归档 | devflow archive | specs/、archive、knowledge | 合并 delta，沉淀知识，迁移 change |

测试报告

支持的 kind:

unit, integration, e2e, 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。

deploy 会触发已配置的 Jenkins job 并写 reports/deploy-<env>.md。执行 devflow deploy test 时会先检查当前分支:如果已经在 test 分支则直接触发 Jenkins；如果在 feature/dev 分支且是交互终端，会主动询问是否执行 feature -> test 合并、推送后再触发。非交互脚本可显式加 --merge-to=test。配合 --preflight 会按项目语言自动做编译预检（Go: go build ./...，Java: mvn compile -q -DskipTests）。部署完成后会复用现有报告体系刷新 reports/self-test.md，把 deploy-<env>.md 和已有 smoke-test.md 等报告串成提测自测证据。

这些报告按风险级别生成，不是每个 change 都硬凑一套。unit-test.md 证明基础逻辑，integration-test.md 证明模块/服务/数据层集成，e2e-test.md 证明完整链路，smoke-test.md 证明部署后关键入口可用，self-test.md 记录人工提测自测和灰度说明。L0 通常只需要 unit；L1 通常只需要 unit + smoke；L2 需要 unit + integration + smoke + self-test；L3 才需要再加 e2e，并按风险补 perf/regression。

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

当前仓库内置 driver:

| Provider 类型 | 内置 driver | 用途 | | --- | --- | --- | | intake | confluence、local | 拉取 Wiki/PRD 或读取本地材料 | | issue | local | Issue 兜底 | | ci | jenkins、local | 触发 Jenkins 部署或构建 | | notify | smtp、local | 发送提测通知 | | kb | weknora、git、local | 同步或提交知识库 | | vcs | local | PR/MR 兜底接口 |

provider setup 会引导配置 intake.confluence、notify.smtp、kb.weknora、kb.git、ci.jenkins。凭证建议写成 ${env:VAR}，避免明文 token 进入配置文件。

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

仓库提供 12 个 skill:1 个 orchestrator 加 11 个阶段 skill。

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 skills install --scope=user
devflow skills install --scope=project --target=cursor,claude,agents
devflow skills status
devflow skills migrate --scope=user
devflow skills uninstall --scope=project

用户级安装会放到:

~/.cursor/skills/devflow-kit/
~/.claude/skills/devflow-kit/
~/.agents/skills/devflow-kit/

分级与验证

复杂度分级由 complexity-grading skill 处理，并写入 state.json.level。CLI 的 verify finalize 按 level 检查必备报告:

| Level | 典型场景 | 必备报告 | | --- | --- | --- | | L0 | 极简改动、范围极小、改法已确定 | unit-test.md | | L1 | 小 diff、低风险、无契约变化 | unit-test.md、smoke-test.md | | L2 | 多文件、接口或业务契约变化 | unit-test.md、integration-test.md、smoke-test.md、self-test.md | | L3 | 跨服务、性能、安全、合规、迁移风险 | unit-test.md、integration-test.md、e2e-test.md、smoke-test.md、self-test.md |

如果是无法跑单测的 L0 文案/配置改动，需要在 verify.md 写明替代验证；若改动部署后才可见，再补 smoke-test.md。未知 level 当前按 L2 兜底。

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。

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 描述。