开源一个快速生成高可读业务流程图skill-easy-code-flow-skill

开源地址 gitee.com/hfqf1234/ea…

背景

AI 时代，越来越多项目文档都是 AI 生成的,它们往往很细，字段、分支、文件、接口和版本都写得很多，但对业务理解来说，颗粒度反而可能过细：组内同事看到了大量细节，却很难快速抓住真实的业务路径。随着 AI 多轮迭代继续推进，文档版本越来越多，内容越来越散，最后很容易失去实际维护和交接价值。

这正是 easy-code-flow-skill 的意义所在。它不是为了追求“越多越全”的文档，而是帮助团队重新建立一份开发者能看懂、模块边界能维护、后续 AI 修改后也能持续校准的业务流转视图。

解决什么问题

开发者接手一个陌生项目时，经常会先看到大量路由、页面、控制器、服务、接口封装、缓存读写和状态判断。代码能告诉你“怎么执行”，但不一定能快速说明“业务为什么这样流转”。

这个 Skill 用来把代码结构还原成业务理解路径，让开发者快速回答：

• 用户从哪里进入这个功能？
• 页面上发生了哪些关键交互？
• 每个交互背后调用了哪些服务、接口或本地数据能力？
• 哪些字段、枚举、状态决定了业务分支？
• 成功后数据写到哪里，失败后如何反馈？
• 整个产品或端侧有哪些业务模块，它们如何协作？

适用场景

• 新人接手陌生代码库，需要快速理解业务链路。
• AI 多轮修改后，需要反向整理当前代码真实实现。
• 产品、测试、开发需要围绕同一份业务流转文档对齐。
• 需要把某个模块、某个端侧或整个应用拆成可维护的流程文档。
• 需要同时生成 Markdown、Mermaid 源文件和可交互 HTML 预览。
• 重要子流程需要能从总览图里的节点直接点击进入，而不是只能依赖左侧导航。
• 全应用首页需要稳定的响应式布局，卡片文字不能被裁剪或横向溢出。

不适合的场景

• 只想画一张临时脑图，不需要代码依据。
• 只想描述系统架构，不关心页面交互、字段判断和业务状态。
• 只需要 API 文档，不需要用户路径和业务流转。

文件说明

skills/easy-code-flow-skill/
  README.md       # 英文项目说明
  README.zh.md    # 中文项目说明
  SKILL.md        # 英文版 Skill 主入口，供运行时加载
  SKILL.zh.md     # 中文版说明，便于组内同事阅读和维护
  example/         # 完整生成示例
  shots/           # 示例预览截图

使用方式

把 skills/easy-code-flow-skill/ 放到支持 Skills 的运行环境中，然后在任务中要求使用 easy-code-flow-skill 梳理代码业务流转。

典型提问：

使用 easy-code-flow-skill，梳理当前项目的全部业务功能。

使用 easy-code-flow-skill，梳理订单模块从列表、详情、支付到取消的业务流转。

参考当前代码，更新会员模块的流程图和 HTML 预览。

示例与截图

示例产物：双语总入口、模块卡片、可切换 Mermaid 图、源图查看和模块级 HTML 预览。

推荐产物

全应用或全端侧梳理时，推荐生成：

module-flows/<scope>/
  index.html
  README.md
  CHANGELOG.md
  <module-name>/
    index.html
    <module-name>.md
    CHANGELOG.md
    diagrams/
      01-overview.mmd
      02-<sub-flow>.mmd

其中：

• 顶层 index.html 是总入口，只展示模块地图和跳转入口。
• 每个业务模块都有自己的目录和预览页。
• .mmd 是 Mermaid 源文件，便于最小粒度维护。
• .md 解释业务背景、页面入口、字段、接口和异常。
• CHANGELOG.md 记录每次流程文档修改的原因、影响范围、代码依据和验证结果。

核心原则

• 先从代码找证据，再写业务流转。
• 先讲人能理解的业务动作，再补代码名、字段名、接口名。
• 全应用梳理必须拆模块，不把所有细节塞进一个总览页。
• 重要子流程必须能从总览图节点点击进入。
• 顶层首页必须使用稳定的响应式卡片网格，并安全换行长路由和标识符。
• 模块按业务所有权拆分，不按文件数量或接口数量机械拆分。
• 字段、枚举、状态分支和异常出口必须写清楚。
• HTML 预览必须能在浏览器中真实渲染 Mermaid 图。
• 每次改流程文档都要递增版本并写入 CHANGELOG.md。

验证要求

完成一次流程文档生成或更新后，至少确认：

• Mermaid 源文件可以渲染成 SVG。
• 模块 HTML 在浏览器运行时没有 Syntax error in text。
• .mmd、.md 和 HTML 内嵌 Mermaid 源保持一致。
• 总入口可以跳转到每个模块。
• 版本号和 CHANGELOG.md 已同步。
• 文件为 UTF-8，git diff 没有乱码或多余空白。

开源注意事项

• Skill 文档使用通用语言描述，不绑定特定业务、公司、平台或技术栈。
• 示例中的代码路径、接口名和字段名应使用通用占位或常见领域示例。
• 不要把私有接口、真实账号、内部域名、客户数据或业务机密写入 Skill 本身。

参与反馈

欢迎大家在真实项目里使用这个 Skill，也欢迎多提反馈、问题和改进建议。如果觉得不错，欢迎顺手点个 Star。