📄 本页由源文件
skills/dev-flow/flowchart/versions/v5_2026-07-22/flowchart.md自动投影生成(单一权威源)。请勿直接编辑本页。
流程图 v5 2026-07-22
静态 Mermaid 版本,可在 GitHub / IDE 中直接渲染预览。 交互式版本(支持点击跳转到源文件):flowchart.html
v4 → v5 核心变更(2026-07-22)
交互体验与自检体系完善:v5 在 v4 执行层硬化基础上,新增交互式菜单命令
dev:ask、帮助一致性检查dev:help --check,以及 dev-flow 自身盲区清单。
核心变更点:
dev:ask/dev:guide交互式菜单:全功能分类菜单入口,支持状态感知(活跃流程/已完成上下文/git 仓库检测),覆盖所有 dev-flow 功能,不进入步骤流程dev:help --check帮助一致性检查:命令行脚本对比help.md与权威源(SKILL.md / mode-matrix.md / step-router.md)的一致性- 源文件索引更新:新增
branch-recommendation.md、menu.md、help-consistency.sh等文件
1. 入口触发与模式路由
v5 更新:新增
dev:ask/dev:guide交互式菜单、dev:help --check帮助一致性检查。
命令速查(v5 当前有效命令):
| 命令 | 快捷 | 说明 |
|---|---|---|
dev-flow / dev: / /dev-flow | — | 进入统一流程 |
dev:sync | dev:s2 | 流程内全量文档同步(不生成 commit,完成后回原步骤) |
dev:fix --drift | — | 显式触发需求漂移(三步固定动作 + dev:sync 同步下游文档 + 门控校验) |
dev:fix --iteration | — | 显式触发迭代修复(调 iteration-fix-classify.sh) |
dev:status | dev:st | 工作上下文进度概览 |
dev:status --trace | — | 实时观测(Token/红牌/步骤耗时) |
dev:kb | dev:k | 知识库管理 |
dev:metrics | dev:m | 度量查看(支持 --all/--trend/--dashboard) |
dev:onboard | dev:ob | 知识库平台 profile 生成/刷新 |
dev:flowchart | dev:chart | 生成/更新 dev-flow 流程图 |
dev:ask | dev:guide | 交互式功能菜单(全功能分类入口,状态感知,不进入步骤流程) |
dev:help | dev:h | 显示帮助信息;--check 运行一致性检查 |
--fast | — | 精简交互修饰层(可与任意命令组合) |
--micro | — | 显式启动 micro-fix 模式(≤3 文件 + ≤10 行/文件 + 对称修改) |
v5 触发原则:dev-flow 仅由显式命令触发或活跃流程相关恢复触发。AI 不得基于关键词主观判断自动触发。 新增命令:
dev:ask/dev:guide交互式分类菜单(加载references/menu.md,含状态感知 4 项检测)、dev:help --check帮助一致性检查(对比 help.md 与权威源)。 热启动增强:恢复时先跑health-check.sh(≤3 秒),检测到状态不一致时追加警告。
2. 统一流程总览(阶段 0 + 0.5 + 步骤 1~10)
v5 无变更:产出物真实性原则(证伪式标注 + 极简模式准入)+ 交互式选项一致性
interactive_progression_shown字段均为 v4 已引入。
流程总览表(步骤名称以 step-router.md 为准):
| 步骤 | 名称 | 加载文件 | 核心产出 | 执行深度 |
|---|---|---|---|---|
| 0 | 需求理解 | use_skill("requirement-intake") | 需求确认 + 分支告知收集(仅 user_specified) | 全部 |
| 0.5 | 项目画像轻量注入 | 本地 _profile.md(0 MCP) | project_profile 或 skipped | 本地 profile 存在时 |
| 1 | 研究与定位 | steps/step-1-research.md | 相关文件表格 | 全部 |
| 2 | 确认范围 | steps/step-2-scope.md | 影响范围报告 + 用户确认 | 全部 |
| 3 | 制定方案 | steps/step-3-plan.md | 执行计划表格(极简/完整) | 全部 |
| 4 | 方案汇报与用户决策 | steps/step-4-decision.md | 评估卡片+执行深度选择+分支定稿+文档决策 | 全部 |
| 4.5 | 环境检查 | steps/step-4.5-env-check.md | 分支确认(主干拦截) | 全部 |
| 5 | 执行修改 | steps/step-5-execute.md | 代码改动 | 全部 |
| 5.5 | 编码后置钩子 | steps/step-5.5-post-coding.md | L1审查+文档同步+ESLint自检+新鲜度校验 | 全部 |
| 6 | 质量验证 | steps/step-6-verify.md | 验证报告(6A/6B/6C) | 全部 |
| 7 | 清理+Commit | steps/step-7-commit.md | L2审查+commit+devlog+knowledge(标准)或 L2审查(完整裁剪) | 全部 |
| 8 | L3 代码审查 | steps/step-8-10-full.md | L3多视角深度审查 | 仅完整执行 |
| 9 | 反思与学习 | steps/step-8-10-full.md | 度量报告+经验提炼 | 仅完整执行 |
| 10 | 归档与交付 | steps/step-8-10-full.md | commit+devlog+knowledge+交付报告 | 仅完整执行 |
★ = 仅完整执行时执行的步骤。步骤 0~7 为所有需求共享。 v4 产出物真实性原则:产出长度由事实决定,不由模板决定。简单任务允许极简产出,但必须基于充分研究。空项须证伪式标注("无 + 理由"),禁止静默省略。 交互式选项一致性:每个完成标记 JSON 必须含
interactive_progression_shown: true(精简模式豁免流转除外),由post-step.sh机械校验。 步骤 6→7 回归修复:步骤 6 通过后用户追加修复 → 强制重走 5.5→6→7 完整链路,精简模式不豁免。
3. 模式矩阵(5 种基础模式 + 1 种专项模式 + 1 种修饰层)
v5 无变更:micro-fix 升级(≤3 文件 + 对称修改 + 5 项 safe defaults)+ 文档平台 × 模式处理策略矩阵均为 v4 已引入。
基础模式全景矩阵
| 模式 | 触发条件 | 阶段0 | 0.5 | 1 | 2 | 3 | 4 | 4.5 | 5 | 5.5 | 6 | 7 | 8-10 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| standard | 默认 + 步骤4选 execute_standard | ✅ | 🔹 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅结束 | — |
| full | 步骤4选 execute_full | ✅ | 🔹 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅裁剪 | ✅ |
| micro-fix | --micro + ≤3文件 + ≤10行/文件 + 对称修改 | ✅精简 | ❌ | ❌ | ❌ | ❌ | ❌ | 🔹主干检测 | ✅ | 🔹L1极简 | ✅lint | ⚡极简收尾 | — |
| iteration-fix | 活跃.flow + 迭代意图 | 🔹简化 | ❌ | 🔹增量 | 🔹增量 | 🔹增量 | — | ✅ | ✅ | ✅ | ✅ | ✅ | — |
| batch | 步骤4选 execute_batched | ✅ | 🔹 | ✅ | ✅ | ✅ | ✅ | ✅循环 | ✅循环 | ✅循环 | ✅循环 | ✅循环 | 最后批 |
| cross-project | 步骤2检测到 workspace 外修改 | ✅ | 🔹 | ✅ | ✅跨 | ✅跨 | ✅ | ✅ | ✅ | ✅ | ✅跨 | ✅跨 | — |
✅ 执行 / ❌ 跳过 / 🔹 按需触发 / 循环 = 批次循环 / 裁剪 = 步骤7仅A~G
v4 micro-fix 升级:触发条件从 ≤1 文件放宽到 ≤3 文件,新增
symmetric_change_required(多文件须对称修改——每个文件做相同结构的修改,仅文件名/变量名等局部差异)。5 项 safe defaults 自动代劳:read_lints必走、commit 必须确认、L1 极简审查必走、knowledge 漂移检测必走、自动降级机制。
模式切换决策树
文档平台 × 模式处理策略矩阵(v4 新增)
| 模式 | 步骤 4 · 文档决策 | 步骤 7 H.3+ | 步骤 10.3.5 |
|---|---|---|---|
standard | ✅ 硬性必走 | docid 非空即触发 | — |
full | ✅ 硬性必走 | ↩️ 推迟至 §10.3.5 | ✅ docid 非空即触发 |
iteration-fix | 仅首轮走;后续按 action_history 继承 | 命中阈值时触发 | 按首轮决策派生 |
batch | 仅 Batch 1 走;后续自动继承 | 仅最后一批 | 仅最后一批(若 full) |
cross-project | A 项目侧按其 mode 走 | 同左 | 同左 |
跨模式继承规则:
action_history是权威历史证据链;首轮 skip 具有"吸附性"(后续自动继承);首轮已发布具有"提醒性";用户逃生通道永远有效(显式说"生成 文档平台"可覆盖任何继承规则)。
4. 步骤 4:方案汇报与用户决策(4 个环节)
v5 无变更:产出物真实性原则影响步骤 3 产出的形态(简单任务允许 1 句话方案,但须通过机校验准入清单)。
环节速查:
| 环节 | 执行时机 | 是否必走 | 交互方式 |
|---|---|---|---|
| 环节 1 · 评估输出 | 方案汇报末尾自动 | ✅ 必走 | 输出展示,无弹窗 |
| 环节 2 · 执行深度决策 | 第 1 次弹窗 | ✅ 必走 | ask_followup_question |
| 环节 3 · 文档决策 | 第 2 次弹窗(仅执行类选项进入) | ✅ 硬性必走 | ask_followup_question |
| 环节 4 · 决策落地 | 串行三步:§4.1 分支定稿 → §4.2 plan.md 写盘 → §4.3 文档平台 执行 | ✅ 必走 | 仅 §4.1 特定场景弹窗 |
步骤 4 决策后顺序锚点:环节 4 严格按 §4.1 → §4.2 → §4.3 串行执行。§4.1 分支名定稿发生在 plan.md 写盘前。 文档决策必走:除
user_decision为 modify/change_plan/pause/cancel 外,必须执行 文档平台 空间探测并输出决策。 文档平台 × 模式策略:首轮决策写入action_history,后续迭代/批次自动继承,用户显式覆盖始终有效。
5. 步骤 7:收尾流程(closeout-flow.md)— 调用方 × 环节矩阵
v5 无变更:环节 K(dev-logs 完整性自检)已在 v3 引入。v4 新增 5.5b 新鲜度物理兜底(
freshness-lint.sh在步骤 5.5 执行而非步骤 7)。
环节清单(A~K,标准执行全部 11 环):
| 环节 | 内容 | standard-7 | full-7 | micro-fix-7 | batch-7(非末批) |
|---|---|---|---|---|---|
| A | Diff 分析 + 预期外变更处理 | ✅ | ✅ | ✅极简 | ✅ |
| B | 清理调试代码 | ✅ | ✅ | ✅限改动行 | ✅ |
| C | 可选链检查 | ✅ | ✅ | ❌ | ✅ |
| D | 即时验证 | ✅ | ✅ | ❌ | ✅ |
| E | TODO 检查 | ✅ | ✅ | ❌ | ✅ |
| F | 改动汇总 | ❌ | ❌ | ❌ | ❌ |
| G | L2 审查 | ✅ | ✅ 到此结束 | ❌ | ✅ |
| H | Commit+Devlog+Knowledge | ✅ | ❌ 推迟到步骤10 | ✅极简 | ✅精简 |
| I | 数据驱动反思 | ✅ | ❌ | ❌ | ❌ |
| J | 经验快检(3问) | ✅ | ❌ | ✅静默 | ❌ |
| K | dev-logs 完整性自检 | ✅ | ❌ 推迟到步骤10 | ❌ | ❌ |
四种调用方:
caller=standard-7:标准执行步骤 7,执行 A~K 全部 11 环,流程结束caller=full-7:完整执行步骤 7,仅执行 A~G(到 G 结束),H~K 推迟到步骤 10caller=micro-fix-7:极简收尾,A 仅 diff stat + B 限改动行 + H 极简 + J 静默 + 跳过 C/D/E/G/I/Kcaller=batch-7(非末批):A~G 正常 + H 精简(仅 H.1+H.2 增量),跳过 I/J/K 环节 H 子步骤:H.1 生成 Commit Message(smart-commit)→ H.2 生成/追加开发日志(tech-doc)→ H.3 知识沉淀(knowledge-loop)→ H.3+ 文档平台 兜底对账(docid 非空时强制执行)
6. 阶段 0:需求理解
v5 无变更:分支推荐仍唯一定稿在步骤 4 §4.1。产出物以需求确认为核心,极简任务允许精简输出。
所有需求(无论大小)都必须经过阶段 0。迭代修复场景下,阶段 0 执行增量理解而非全量理解。 分支推荐唯一定稿在步骤 4 §4.1,阶段 0 只做记录。
7. 阶段 0.5:项目画像轻量注入 + 步骤 1~4.5 子流程
阶段 0.5:项目画像轻量注入
步骤 1:研究与定位
v4 充分性校验:步骤 1 末尾执行
sufficiency_check,不通过 → 禁止进入步骤 2,必须补充搜索。防止"伪装简化"(描述简短但实际中等复杂)。
步骤 2:确认范围
步骤 3:制定方案
v4 极简模式准入:不再是 AI 自由选择。须满足机器可校验准入清单(基于步骤 1/2 JSON 产出),任一条件不满足 → 自动禁用极简模式。
步骤 4.5:环境检查
硬性规则:主干分支下不可进入步骤 5,交互选项中不允许"跳过检查"。 步骤 4.5 推进选项:正常场景(分支一致且非主干)标准模式下仅弹一次推进选项,精简模式一行摘要静默推进。
8. 步骤 5~6 子流程
步骤 5:执行修改
编码前置硬卡点 4 项校验:① 工作上下文文件存在 ②
.flow锁文件 current_step ≥ 4.5 ③ 步骤 4 user_decision 非空 ④ 步骤 2/4 交互记录存在。micro-fix 模式有独立分流规则。
步骤 5.5:编码后置钩子
v4 5.5b 新鲜度物理兜底:
freshness-lint.sh校验工作上下文新鲜度(步骤清单状态与实际产出时间戳一致性),过时 → 阻断推进,必须先执行dev:sync。 5.5 不可跳过:每轮编码(含迭代修复)完成后必须执行 5.5a L1 审查 + 5.5b 文档同步 + 5.5c ESLint 自检。 静默累计 ≥3 次未执行 dev:sync → 物理层必弹提醒(由 post-step.sh 维护silent_55_count)。
步骤 6:质量验证(6A + 6B + 6C)
v4 6→7 回归修复规则:步骤 6 通过后、步骤 7 加载前用户追加修复 → 修复完成后必须重走 5.5→6→7 完整链路(每个步骤独立 loading + JSON + validate-output.sh)。精简模式不豁免本规则。步骤 7 的
.step-7.validated是流程结束的唯一合法标志。
9. 完整执行独有步骤(8~10)
以下步骤仅在用户选择「完整执行」时执行。标准执行在步骤 7 结束。
步骤 8:L3 代码审查
步骤 9:反思与学习(数据驱动,4 个子步骤)
步骤 10:归档与交付
10.6 校验项:① Commit已确认 ② devlog已生成 ③ knowledge已沉淀 ④ 交付报告已输出 ⑤ 规则归档已处理。 10.3.5 文档平台 归档同步前必须通过
doc-platform-doc-lint(6 项文档质量检查),失败则阻断。
10. 特殊流程
迭代修复机制
v4 增强:新增
dev:fix --iteration显式触发 + 热启动健康检查(health-check.sh)+ 24h+ 跨天对账。
v4 热启动增强:恢复前先跑
health-check.sh(≤3 秒),输出exit 1(阻断级警告)或exit 2(非阻断警告)时追加提示。 24h+ 跨天对账:last_active > 24h时一行命令检查 HEAD 是否变化(git rev-parse --short HEAD),不一致时追加 ⚠️ 提示。
分批执行流程
跨项目协作
需求漂移子流程
v4 新增:
dev:fix --drift显式命令入口,跳过关键词匹配直接执行三步固定动作。
显式命令
dev:fix --drift:直接触发需求漂移,跳过 doc-sync-rules §路由分流的 B/C/D 关键词匹配。完成后自动调用dev:sync刷新下游文档。
6→7 回归修复规则(v4 新增)
不可豁免:精简交互模式不豁免本规则。即使
--fast,步骤 7 的完整执行(A~J 环节)仍然强制。 禁止跳过:禁止以"修复已验证通过"为由跳过步骤 7 的任何环节。禁止不调用validate-output.sh。
物理检查点与门控系统
v4 交互式选项硬化:完成标记 JSON 必须含
interactive_progression_shown: true(精简模式豁免流转除外),由post-step.sh机械校验。缺失时等价于红牌 #13。
工具门禁(红牌 R7)
11. 文档同步体系(dev:sync)
dev:sync是流程内文档同步入口,任意步骤可召唤,完成后回原步骤。复用closeout-flow.md §H.0~H.3+的文档同步子集。 v4 增强:热启动恢复时自动跑health-check.sh检测状态一致性。
dev:sync — 流程内同步(caller=in-flow-sync)
AI 主动弹框(2 个场景)
| 场景 | 条件 | 行为 |
|---|---|---|
| A · 5.5 静默累计 ≥3 | post-step.sh 检测 silent_55_count ≥3 | ask_followup_question 必弹 |
| B · 完整模式真空期追加改动 | caller=full-7 完成后 git diff vs last_sync_diff_sha 非空 | ask_followup_question 必弹 |
防退化条款:dev:sync ≠ 5.5b 替代品。5.5b 是日常必做(含 freshness-lint 物理硬阻断),dev:sync 是累计静默≥3的兜底。
12. 交互模式(精简交互 + 口语意图消歧 + 交互式菜单)
v5 新增:
dev:ask/dev:guide交互式菜单——提供全功能分类入口,含状态感知(活跃流程/已完成上下文/git 仓库检测),覆盖所有 dev-flow 功能,不进入步骤流程。
交互模式风险分级
口语意图消歧规则(v4 新增)
映射表(直接命中,不弹窗):
--fast/少问我/你决定就好/别老问我→interaction_mode: streamlined;每步都问我/我要确认/多问我→interaction_mode: standard。 模糊口语(必须弹窗):"精简一下"/"简单点"/"快一点"/"详细一些"/"深入一点"/"重头来"/"回到上一步"。 反绕过:不直接命中映射表 → 禁止凭推测"语义解码";禁止把 streamlined 与 micro-fix 等同;修改 YAML 头部前必须先确认维度。
步骤流转推进规则
13. Prompt Chaining 架构 + 程序化执行层
v4 升级:新增
health-check.sh(热启动健康检查)、freshness-lint.sh(5.5b 新鲜度兜底)。 完善post-step.sh的interactive_progression_shown机械校验。 v5 新增:help-consistency.sh(帮助一致性检查)。
v5 程序化执行层组件:
- health-check.sh(热启动):热启动恢复前 ≤3 秒状态一致性检测,退出码 1(阻断)/ 2(警告)/ 0 或 3(静默)
- freshness-lint.sh(5.5b):物理事实校验工作上下文新鲜度,过时 → 阻断推进
- help-consistency.sh(帮助一致性):对比 help.md 与权威源的一致性
- post-step.sh 增强:新增
interactive_progression_shown机械校验 + freshness-lint 集成
14. 源文件索引
| 文件 | 说明 |
|---|---|
SKILL.md | 主入口,触发规则+全局配置+命令速查+流程加载指令 |
flow.md | 开发流程详细指引(L0 路由层,阶段0+0.5+步骤1~10+热启动+多活跃流程+口语消歧) |
steps/step-router.md | 步骤路由器(执行协议+门控+物理检查点+红牌+交互规则+模式白名单+口语消歧) |
steps/README.md | 步骤规范目录导航 |
steps/step-1-research.md | 步骤1:研究与定位(含充分性校验) |
steps/step-2-scope.md | 步骤2:确认范围 |
steps/step-3-plan.md | 步骤3:制定方案(极简模式机校验准入) |
steps/step-4-decision.md | 步骤4:方案汇报与用户决策(4环节+智能评估+文档平台+分支定稿) |
steps/step-4.5-env-check.md | 步骤4.5:环境检查(主干分支拦截) |
steps/step-5-execute.md | 步骤5:执行修改(编码前置硬卡点+TDD) |
steps/step-5.5-post-coding.md | 步骤5.5:编码后置钩子(L1审查+文档同步+ESLint+freshness-lint) |
steps/step-6-verify.md | 步骤6:质量验证(6A自动化+6B验收+6C联调+熔断+6→7回归规则) |
steps/step-7-commit.md | 步骤7:清理+Commit(加载 closeout-flow.md) |
steps/step-8-10-full.md | 步骤8~10:完整执行扩展(L3审查+反思+归档) |
references/closeout-flow.md | 收尾子流程规范(A~K 11环节制,5种调用方共享) |
references/_index.md | 参考文件加载索引 + 条件激活矩阵 |
references/mode-matrix.md | 模式矩阵(5基础+1专项+1修饰层+切换决策树+文档平台×mode策略) |
references/menu.md | dev:ask/dev:guide 交互式功能菜单(状态感知+双重展示,不进入步骤流程) |
references/help.md | 帮助命令单一权威源(dev:help/dev:h 加载) |
references/gate-validator.md | 门控校验规范(物理检查点+lint+hooks+交互式选项+freshness兜底) |
references/working-context.md | 工作上下文规则(命名+创建+更新+项目缩写映射+跨项目预检) |
references/active-flows.md | 活跃流程注册目录(.flow v3 schema+智能恢复网关+并发抢占+health-check) |
references/iteration-fix.md | 迭代修复机制(场景分类+差异处理+快车道+文档平台继承+轮次管理) |
references/rollback.md | 回退对照表(单一真相源) |
references/drift-handling.md | 需求漂移处理子流程(三步固定动作+反模式+dev:fix --drift显式入口) |
references/cross-project-flow.md | 跨项目联调主索引(触发检测+衔接+集成+分析+单.flow架构) |
references/micro-fix-light.md | micro-fix 轻量保留版执行规范(5个环节执行边界+三道防线+5项safe defaults) |
references/figma-flow.md | Figma 设计稿处理流程(两级策略) |
references/tech-proposal-flow.md | 技术方案文档生成/更新流程 |
references/in-flow-sync.md | 流程内文档同步(dev:sync 完整流程+health-check集成+弹框场景) |
references/code-safety-rules.md | 代码安全规则(lint验证+自检清单) |
references/user-acceptance.md | 用户验收流程(步骤6B) |
references/integration-flow.md | 联调流程(步骤6C) |
references/interaction-mode.md | 交互模式(standard/streamlined风险分级+豁免清单+口语消歧) |
references/branch-recommendation.md | 分支命名推荐输出模板与命名约束(步骤4 §4.1 细节下沉) |
references/token-management.md | 对话窗口 Token 管理策略 |
references/conversation-quality.md | 对话质量守卫(长对话预警+压缩+收尾) |
references/devlog-rules.md | 开发日志生成规范 |
references/doc-sync-rules.md | 文档同步规则(三模式通用+路由分流) |
references/metrics-rules.md | 流程度量机制(数据模型+采集+报告+仪表盘) |
references/core-principles.md | 核心原则详细说明(§1~§18) |
references/shared-rules.md | 共享规则单一真相源(Commit/沉淀/并行/分支/Hook) |
references/remote-knowledge.md | 知识库平台 节点信号触达(5信号+项目映射+Token策略+噪声过滤) |
references/onboard-flow.md | dev:onboard 命令流程与 profile 生命周期 |
references/output-schemas.md | 步骤完成标记 JSON 统一模板定义(含 interactive_progression_shown) |
references/schemas/all-steps.schema.json | 所有步骤完成标记 JSON 的机器可校验 Schema |
references/env-tools.md | 环境与工具信息(含 Git Worktrees) |
references/tdd-mode.md | TDD 测试驱动开发模式 |
references/react.md | React 开发专项规范 |
references/component-library.md | 组件库使用规范 |
references/flow-graph.md | 流程图定义(流转路径表) |
references/flow-retrospective.md | 流程回顾报告(步骤9) |
references/skill-full.md | SKILL.md 完整备份(P0 精简前的边界情况) |
references/no-dev-flow-mode.md | 无 dev-flow 时的简化质量检查规范 |
references/cross-project/handoff.md | 跨项目衔接 prompt(B 项目入口规范) |
config/gates.yaml | 门控规则单一权威源(物理检查点+lint+hooks+状态机+工具门禁+freshness) |
config/hooks.json | Hook 注册表 |
scripts/ | 程序化执行层(含 health-check.sh/freshness-lint.sh/help-consistency.sh + 65+个脚本) |