extract-flows

name	extract-flows
description	当需要理解模块的业务流程、状态转换、时序关系、或异常处理方式时使用。读取结构地图，逐模块提取流程文档。

Extract Flows — 业务流程提取

读取结构地图，逐模块提取流程文档。

`{KB_DATA_ROOT}/raw//_map.md` 必须存在（由 scan 技能产出）。如果没有，先调用 scan 技能。

输入

参数	必填	默认值	说明
--target <path>	是	-	目标代码库路径
--project <name>	是	-	项目名称
--module <name>	否	全量	只分析指定模块
--kb-data-root <path>	否	插件 data 目录绝对路径	数据根目录

前置条件

• {KB_DATA_ROOT}/raw/<project>/_map.md 必须存在

输出

• {KB_DATA_ROOT}/raw/<project>/flows/_index.md（带 frontmatter 的索引）
• {KB_DATA_ROOT}/raw/<project>/flows/modules/<module>.md（每个模块一份流程文档）

反模式

想法	问题
"只画正常路径就够了"	异常路径是流程分析的核心价值。缺少异常处理文档 = 上线后靠猜排障
"状态转换用文字描述就行"	文字无法表达分支和并发。状态图是状态机的唯一可靠表达方式
"超时和重试是运维关心的事"	超时和重试是流程设计的一部分，影响数据一致性和用户体验，必须从代码中提取
"一个流程一张图就够了"	复杂流程需要流程图 + 序列图 + 状态图互补，单一视角必然遗漏关键信息

执行流程

1. 读取 _map.md，获取模块清单和流程入口点
2. 如果指定了 --module，只分析该模块；否则分析所有模块
3. 对每个模块： a. 识别流程入口（API handler、消息消费者、定时任务、事件监听器） b. 跟踪调用链（函数调用、服务间通信、异步消息） c. 识别状态转换（状态字段变更、状态机定义、生命周期钩子） d. 提取异常处理（catch 块、错误码返回、降级逻辑、死信队列） e. 提取超时/重试（超时配置、重试策略、退避算法、熔断机制） f. 识别并发控制（锁、事务隔离级别、乐观锁/悲观锁、幂等键） g. 生成 Mermaid 图（流程图 + 序列图 + 状态图） h. 按必含章节写入 flows/modules/<module>.md
4. 生成 flows/_index.md（流程清单 + 跨模块流程总图 + frontmatter）

_index.md frontmatter

---
project: <project>
dimension: flows
date: YYYY-MM-DD
status: unprocessed
tags: [...]
---

模板

每份流程文档必须包含以下章节：流程概述（触发条件 + 参与者 + 分类）、流程清单（表格：流程名 | 类型 | 触发方式 | 关键性）、流程详情（Mermaid 图 + 异常路径 + 后置状态）、状态机（转换表 + Mermaid 状态图）。

关键原则

• 从入口跟踪： 流程必须从明确的入口点开始，不能从中间步骤切入，否则无法保证完整性
• 异常路径不可省略： 每个流程必须包含异常路径和错误处理，否则文档无法支撑排障
• 状态图和流程图互补： 流程图描述步骤顺序，状态图描述状态转换，两者缺一不可

质量约束

• 每个模块文档至少 3 张 Mermaid 图（流程图 + 序列图 + 状态图）
• 必须包含异常路径（每个流程至少 1 个异常路径）
• 状态机必须覆盖所有转换
• 每个模块文档至少 1 张对比表格

验收标准

交付前逐项勾选，P0 未满足必须补充：

P0 — 必含章节

• 流程概述（触发条件 + 参与者 + 分类）
• 流程清单（表格：流程名 | 类型 | 触发方式 | 关键性）
• 流程详情（Mermaid 图 + 异常路径 + 后置状态）
• 状态机（转换表 + Mermaid 状态图）

P1 — 深度

• ≥ 3 张 Mermaid 图
• 异常路径覆盖
• ≥ 1 张对比表格