本项目是一款Vibe Coding的辅助工具，目前完美支持Claude Code，能用自然语言或在图上直接画模块来驱动 AI 修改代码。具体效果可见图。 此工具既可使非专业编程人员在利用vibe coding创作自己的代码作品时，以方便理解的流程图视角，而非文件夹以及晦涩的代码，了解自己作品的各种运行方式，并方便快速地进行修改；
也可使用户想修改自身作品时 无需费尽心思 构思复杂的提示词 来界定AI vibe coding的行为以及边界，避免过度修改； 而是直观地图形地精确修改产品，或准确的增加新功能。这省去了大量开发者构思提示词的时间。
这使得Vibe Coding编程时 不再要求用户的文字文字功底。
四张视图，读懂 AI 写的代码
AI 写完一堆代码，你不知道它实现了什么。这个工具把项目自动转成四张图：用户流程、功能总览、页面流程、数据流。每个节点点开都有自然语言说明、逻辑伪代码、对应的真实源码文件和行号。开发者模式另提供技术关系图（文件夹 → 文件 → 导入关系）。
在图上画模块，驱动 AI 改代码
纯文字 vibe coding 的问题：你要用精确的文字描述需求，描述能力差就得到错误结果，一句话塞太多逻辑 AI 容易理解偏。这个工具让你在图上直接表达：拖出一个新模块，写上它做什么，连线到已有环节，注明触发关系，点确认。AI 拿到的不只是文字，还有现有代码的具体位置，去实现它。表达方式从"写作文"变成"画流程图"。
数据流图辅助发现业务安全问题
数据流视图能看出数据从哪来、经过哪些处理、到哪里去。没有校验的环节、未鉴权的路径，在图上比在成千上万行代码里好找得多。
增量同步
chokidar 监听文件变化。你在另一个终端让 Claude Code 改代码，这边的视图自动更新，只重新分析变化的部分。
修改全程可控
自然语言或图上画模块都能触发修改。流程：AI 生成计划 → 展示影响范围 → 真实 diff → 自动跑测试并区分"本来就挂的"和"这次改挂的" → 一键接受或回滚。全程 Git 保护。
场景 A：看懂 AI 写的东西
你用 Claude Code vibe 出一个小应用，但不确定它到底实现了什么。导入项目，打开用户流程图，点开每个节点看大白话说明，顺手能跳到对应源码行号。
场景 B：想加功能但描述不清楚
你想加个每日签到，但不知道怎么用一句话说清楚要改哪些地方。在用户流程图上新建一个"每日签到"模块，连线到"进入主菜单"节点，注明"进入时检查今天是否签到"，点确认，AI 带着主菜单对应的源码位置去实现。
场景 C：怀疑项目有安全问题
打开数据流视图，发现用户输入直接流向了数据库节点，中间没有校验环节，一眼定位问题所在。
- Node.js >= 20
- AI 功能需要本机安装 Claude Code CLI（
claude命令可用即可，使用你现有的订阅） - 无需数据库，无需 Docker
- 可选：OpenAI 兼容 API（仅用于解释和问答，不支持代码修改）
git clone <仓库地址>
cd vibeflow
npm install工具分前端和后端两部分：后端（server/，端口 5177）负责解析代码、调用 AI、读写数据、跑 git；前端（client/）是浏览器里看到的流程图和面板，所有数据都向后端请求。据此有两种启动方式。
只是想用这个工具（推荐）——生产模式：
npm run build # 把前端打包成静态文件（首次，或每次 git pull 更新后跑一次）
npm start # 只起后端 5177，它顺带把打包好的前端一起发出去浏览器打开 http://localhost:5177。此模式只有一个端口、一个进程。
要改 VibeFlow 自身的界面代码——开发模式：
npm run dev # 同时起后端 5177 和 Vite 前端 5173浏览器打开 http://localhost:5173。前端源码改动会自动热更新，Vite 会把 /api 请求代理转发到 5177 的后端，所以你只面对 5173 一个地址。
两种模式打开对应端口后，在首页输入目标项目文件夹的绝对路径即可导入。空文件夹也支持，开始写代码后视图会自动生成。
开发模式 npm run dev |
生产模式 npm start |
|
|---|---|---|
| 浏览器打开 | 5173 | 5177 |
| 进程数 | 2（前后端分开） | 1（后端兼发前端） |
| 前端形态 | 源码实时编译，改动自动刷新 | 预先打包为静态文件 |
| 适合 | 开发本工具 | 使用本工具 |
让 Claude Code 直接查询项目地图（找功能、查文件角色、分析影响范围等），而不是重新扫描代码：
claude mcp add vibeflow -- npx -y tsx <本仓库路径>/server/mcp.ts接入后 Claude Code 可以使用以下只读查询工具：list_projects、get_project_summary、find_feature、get_node_source、get_file_role、get_impact。
还有一个 open_webui 工具：在项目的 Claude Code 窗口里说一句「打开 webui」，它会自动启动本地服务（若未运行）、导入当前项目、并在浏览器直接打开指向该项目的可视化界面。适合一边用 Claude Code 写代码、一边看流程图的场景。
| 环境变量 | 默认值 | 说明 |
|---|---|---|
PORT |
5177 |
服务端口 |
HOST |
127.0.0.1 |
绑定地址，仅本地访问 |
OPENAI_BASE_URL |
— | OpenAI 兼容 API 地址 |
OPENAI_API_KEY |
— | OpenAI 兼容模式 API Key（存服务端，不下发前端） |
默认只绑 127.0.0.1，分析在本机完成，不向外部发送代码。
注意：如果使用第三方API，如中转站等，请选择支持第三方的API分组，否则无法使用。
server/ Express + chokidar + web-tree-sitter (WASM) + simple-git
parser/ tree-sitter 提取 imports / 符号 / 调用 / 路由
resolver ts.resolveModuleName + Python 相对导入启发式
analyzer 全量 / 增量分析（内容 hash 判变）
views 静态事实 → LLM 翻译 → zod 校验 → sourceRef 落地校验
modify 计划 → AI 改码 → git diff → 测试 → accept / rollback
mcp.ts MCP Server（6 个只读查询工具 + open_webui）
client/ Vite + React 19 + @xyflow/react + @dagrejs/dagre
shared/ 数据模型 + zod schema
几个设计决策：
- 静态分析零 LLM 成本：tree-sitter (WASM 运行，无 native 编译依赖) 提取所有结构信息；模块路径解析复用 typescript 包的
ts.resolveModuleName。支持 TS/TSX/JS/JSX 深度分析，Python 基础分析。 - AI 输出强校验：zod schema 约束结构，sourceRef 落地校验（对照实际文件列表），禁止 AI 编造不存在的文件路径。
- AI 引擎可替换：默认用本机
claudeCLI（headless 模式），可切换为任意 OpenAI 兼容 API，Key 存服务端不进浏览器。 - 解释缓存：按代码内容 hash 缓存，代码没变不重复调用 LLM。惰性生成：点开节点才触发，多节点批量合进一次调用。
- 数据存目标项目
.vibeflow/目录（JSON），通过.git/info/exclude忽略，不污染用户的.gitignore。 - 本地优先：服务默认绑
127.0.0.1，分析在本机完成。
- Python 为基础级分析（import / 函数 / 类 / FastAPI 路由），跨文件调用链深度以 TS/JS 为准
- 大型项目（>1000 文件）的事实摘要会截断低重要度文件的符号细节
- OpenAI 兼容模式仅支持解释和问答，不支持代码修改，也无成本统计
- 修改前要求工作区干净（未提交的改动需先快照或暂存）
- 业务视图不随代码自动重生成，代码变化后会标"刚变化"提醒，需手动点"重新生成地图"
- 界面目前仅中文
欢迎提 Issue 和 PR。提 PR 前请先运行 npm run typecheck && npm run lint && npm test。
MIT © VibeFlow contributors