VibeFlow

English

让 AI 开发的项目，不至于变成一座难以维护的屎山。

VibeFlow 强制 AI 先计划好程序的大概架构再进行开发，并自动根据程序真实代码逻辑生成可直接查阅的标准程序流程图，以便开发者直观了解程序各部分的真实结构逻辑，而不是根据 AI 可能失真的表述来猜测。VibeFlow强制 AI 遵守高内聚、低耦合、小文件、小函数、显式流程边和可检查契约。AI 仍然可以高速开发，但每一轮修改都必须回到可视化、可校验、可运行的流程图里。

为什么需要 VibeFlow 🧯

LLM 很擅长快速写代码，也很擅长在多轮修改后悄悄制造这些问题：

• 一个函数越长越长，最后没人敢动。
• 新功能绕过旧结构，隐式依赖越来越多。
• 修 bug 变成局部补丁，根因留在系统里。
• 项目架构逐渐混乱臃肿，最后ai自己也弄不清。

最终代码还能跑，但结构已经无法审查，功能难以加入，bug没人能修。

VibeFlow 的愿景是把这些风险前移：在 AI 写代码之前就给它一套可执行的项目纪律，让结构、契约、流程和产物都能被机器检查。

一句话 🧭

VibeFlow 把项目约束成一张可运行、可检查、可视化的标准流程图。

terminal start -> io input -> process -> decision -> process -> io output -> terminal end

AI 仍然负责写业务代码，但它必须按流程图开发：每个节点小而清晰，控制流只来自配置，运行前必须通过健康检查。

效果展示 ✨

下面是 integration sandbox 中一个完整示例导出的 SVG 流程图。整个 AI 开发过程中，开发者随时可以查看 reports/ 目录下生成的最新流程图来了解项目当前的逻辑结构，以用最小的精力随时保持对项目整体状态的了解。

适合谁 👥

• 使用 OpenCode、Codex、Claude Code 等 vibe coding 工具长期开发项目的人。
• 想让 AI 参与开发，但不想让项目结构失控的人。
• 希望业务流程能被 Mermaid / ASCII / SVG 图审查的人。
• 希望每次运行前都有自动结构检查、契约检查和质量检查的人。

使用方式 🚀

VibeFlow 面向发布包使用。

1. 到 GitHub Releases 下载最新发布包。
2. 解压到你的工作目录。
3. 用任意 vibe coding 软件在该目录创建或打开项目，例如 OpenCode、Codex、Claude Code。
4. 让 AI 先按 AGENTS.md 生成 planned 流程图，确认结构后再逐步实现业务 node、base_lib、plugin 和 JSONC config。

发布包根目录会带有 AGENTS.md。支持项目指令的 AI 工具会自动读取它，并理解：

• 哪些目录可以改。
• 哪些内核文件不能改。
• 如何新增 node、nodeset、plugin。
• 如何运行 validate、run、quality、diagram 命令。
• 运行前必须满足哪些健康检查。
• 如何先设计 planned nodeset，导出流程图给人审核，再逐层实现。

你不需要先理解完整内核源码，也不需要手工配置复杂工程。把发布包当成一个带规则的 AI 开发工作目录即可。

发布包中的典型结构 📦

AGENTS.md         # 给 AI 的项目规则，可按项目定制
README.md        # 项目说明，可按项目定制
run.py            # 项目入口
kernel/
  vibeflow-kernel.zip
  MANIFEST.sha256
  README.md
  docs/           # 内核说明，可读但不作为项目内容修改
  tools/
    mermaid-renderer/
  THIRD_PARTY_NOTICES.md
project/
  nodes/          # 业务 node
  base_lib/       # 纯函数 helper
  plugins/        # 可选策略和运行插件
  configs/        # JSONC 流程配置
  registry.py     # 节点注册
runs/
reports/

常用命令形态：

python run.py validate --config project/configs/main.jsonc
python run.py run --config project/configs/main.jsonc --run-root runs
python run.py mermaid --config project/configs/main.jsonc --output reports/graph.mmd
python run.py ascii --config project/configs/main.jsonc --output reports/graph.txt
python run.py svg --config project/configs/main.jsonc --output reports/graph.svg
python run.py svg --config project/configs/main.jsonc --expand-nodesets --output reports/graph.expanded.svg
python run.py quality --path project

run 会在 runs/<run_id>/ 自动写出快速图 graph.svg 和详细审查图 graph.expanded.svg。svg 导出会为 Mermaid CLI 传入放大的渲染配置；普通图默认 maxTextSize=200000，--expand-nodesets 默认 maxTextSize=500000。超大图仍可用 --mermaid-max-text-size 和 --mermaid-max-edges 覆盖。 展开 SVG 会固定使用确定性的 review-columns composer：主流程保持在左侧，右侧依次展示 plugins、base_lib 和按顶层调用顺序排列的展开 nodeset。nodeset 详情使用递归 detail-panel：叶子 nodeset 横向展示；包含子 nodeset 的父图保持 collapsed call-site 和原始连边，右侧按调用顺序纵向展示直接子 nodeset。审查图默认把单个片段显示宽度限制为 3200px，可用 --review-fragment-max-width 调整。 graph.expanded.mmd 只是 Mermaid 源码调试产物，不要直接用 Mermaid CLI/mmdc 转成 SVG；详细审查 SVG 必须通过 run.py svg --expand-nodesets 生成。 SVG 渲染不要求系统预装 Google Chrome；正常 npm install 后会优先使用 Puppeteer 自己安装/缓存的浏览器。/snap/bin/chromium 会被跳过，因为它在 Puppeteer/mermaid-cli 下常见 profile lock 启动失败。 在发布包中首次使用 SVG 前，到 kernel/tools/mermaid-renderer/ 执行 npm install。发布包不内置 .gitignore，项目可以自行决定是否忽略 kernel/tools/mermaid-renderer/node_modules/、runs/、reports/ 等产物。

AI 开发工作流 🛠️

描述需求
  -> AI 抽象成粗粒度标准流程图
  -> 用 planned nodeset 写入 JSONC
  -> 导出 Mermaid 或 SVG 给人审核
  -> 审核通过后逐层展开 nodeset
  -> 实现 node/base_lib/plugin/config
  -> validate / quality / run
  -> 继续迭代

重大结构变更也走同一模式：先 planned、先出图、先审核，再实现。尚未确定的部分保留为 status: "planned"，VibeFlow 会允许它用于设计审查，但不会让它伪装成可运行程序。

VibeFlow 不阻止你 vibe coding。它只是让每一轮 vibe 都必须回到可检查的结构里。

原理简述 ⚙️

VibeFlow 的核心是一个严格的流程图运行时：node 负责局部纯计算，JSONC config 负责声明控制流，compiler 负责把流程编译成可执行图，health checker 负责在运行前拦截结构漂移和契约错误。

它把“项目架构”从口头约定变成机器可以执行的检查。

核心能力 🧩

标准流程图约束

每个 node 都必须声明标准 flow_kind：

• terminal：开始 / 结束。
• process：普通处理。
• decision：判断 / 路由。
• io：输入 / 输出动作。
• predefined：预定义过程 / nodeset。
• data_store：数据存储请求或引用。
• document：文档生成或文档结构。
• preparation：准备 / 初始化。

这让 AI 写出的代码不只是“能跑”，还必须能放回一张可审查的流程图里。

显式流程边

程序控制流只来自 JSONC 配置里的 pipeline.edges。

requires / provides 只是数据契约，不会被偷偷推导成控制流或图上的理论数据边。这样可以避免项目在多轮 AI 修改后出现隐式路径和隐藏依赖。

Health 会在显式 edge 中推断同步主线、data bypass 和 async 相关边：主线 edge 负责调度并在 SVG/Mermaid 加粗，data bypass 只投递数据不触发目标并显示虚线，async edge 连接显式 async node/nodeset。

配置调用点使用 id 和 type_used：type_used 指向 Python node 的 NodeInfo.type_key、独立 nodeset JSONC 的 type_key 或系统类型。数据契约使用严格结构化写法：provides 声明唯一 key、逻辑 type 和 display_name，requires 按 type、cardinality 和 display_name 消费。运行时通过 node inbox / edge payload 传递 envelope，不支持跨多跳从全局 Context 偷读早期输出；最终结果只保留 pipeline.outputs 声明的内容。

小 node 和纯逻辑

业务 node 默认必须是纯函数：

• 不读写文件。
• 不访问网络。
• 不连数据库。
• 不启动浏览器或外部进程。
• 不读取环境变量。
• 不直接调用其他 node。

真实 IO 通过 io、data_store、document 等流程图节点建模；第三方或外部维护代码用 NodeInfo.external=True 标记。

运行前健康检查

VibeFlow 会在运行前检查：

• 节点元数据是否完整。
• 输入输出契约是否清晰。
• 流程是否从 start 可达并能到达 end。
• 同步分支是否能解释为 mainline、data bypass、async 或显式 join_policy: "all" 汇合。
• 普通 graph / nodeset 内部是否存在显式环路；真实循环必须使用一等 while loop。
• node 是否违反纯函数和结构规则。
• 配置、插件、nodeset 是否破坏项目边界。

检查失败就拒绝运行，并输出可追踪的原因。

可视化产物

同一份配置可以导出：

• Mermaid 流程图。
• ASCII 终端流程图。
• SVG 图形文件。

这让人类可以审查整体结构，也让 AI 更容易理解当前项目边界。

仓库文档 📚

• docs/kernel_target_vision.md：目标愿景。
• docs/developer_guide.md：使用者开发指南。
• docs/kernel_development_guide.md：VibeFlow 自身维护指南。
• docs/strict_flowchart_kernel_redesign.md、docs/11_*.md、docs/12_*.md、docs/13_*.md：历史设计记录和阶段计划，不作为当前公开接口规范。
• distribution/kernel_development_pack/：发布包模板。

许可证 📄

VibeFlow 使用 GNU Affero General Public License v3.0（AGPLv3）授权。详见 LICENSE。

项目状态 🚧

VibeFlow 仍在快速演进中。当前重点是把 AI 协同开发中的结构纪律、流程图表达、运行前检查、训练/批处理运行性能和发布包体验打磨稳定。

如果你相信未来的软件会越来越多由人和 AI 一起维护，那么项目需要的不只是更强的生成能力，还需要更硬的结构边界。

VibeFlow 就是这层边界。