npx aicode2flow：一行命令，让任何代码瞬间变成架构图

当读代码的痛苦超过了写代码的快乐，说明你需要换个角度看世界。

想象一个场景：

你接手了一个三个月没人维护的项目。文档？不存在。架构图？上一任说"还没来得及画"。你打开 src/ 目录，里面有 47 个文件，你挨个打开，在脑子里拼图一样还原调用关系。

这种痛苦，每个开发者都经历过。

传统的解决方案是什么？

1. 手绘架构图— 代码改了，图没改，两周就过期
2. PlantUML / Graphviz— 需要写声明文件，维护成本不低
3. 现有代码可视化工具— code2flow 停更了，js2flowchart 只支持 JS，而且都要求先安装

有没有一种方式，能做到零安装、零配置、一行命令出图？

有。这就是我今天要分享的项目 ——aicode2flow。

零安装体验：npx 即用

不卖关子，先看效果：

# 一行命令，零安装npx aicode2flow ./main.go

输出：

```mermaidflowchart TDmain(["⭐ main"])greet("greet")validate("validate")processUser("processUser")saveUser("saveUser")processUser --> greetprocessUser --> validateprocessUser --> saveUsermain --> processUser```

aicode2flow

把这段 Mermaid 粘贴到 GitHub 的 Markdown 里，自动渲染成流程图。

真正的零安装— 不需要 git clone，不需要 npm install，不需要 pip install。你的电脑只需要有 Node.js，其他什么都不用装。

# 扫描整个项目，自动分析所有文件npx aicode2flow ./# 指定语言范围npx aicode2flow ./ --language go# 输出为 SVG 图片npx aicode2flow ./main.go -o diagram.svg

这是这个项目最核心的设计理念：语言差异 = 数据，不是代码。

目前支持：

Go / Python / JavaScript / TypeScript / Rust / Java / C / C++

添加一门新语言需要几步？两步：

第一步：JSON 配置文件

{"name": "rust","extensions": [".rs"],"grammar": "tree-sitter-rust","entryPoints": [{ "pattern": "main", "match": "full" }],"nodeTypes": {"function": { "query": "function", "shape": "round" }}

第二步：Tree-sitter 查询文件

; 函数定义(function_itemname: (identifier) @namebody: (block) @body) @function; 函数调用(call_expressionfunction: (identifier) @callee) @call

就这两步。不需要改动一行 TypeScript 代码。

因为项目的分析引擎是配置驱动的 —— 它读取 JSON 配置，加载对应的 Tree-sitter 语法，执行 SCM 查询，提取函数定义和调用关系。语言之间的差异被完全抽象成了数据文件。

这就是元编程（Metaprogramming）的实践：与其为每种语言写一遍分析逻辑，不如写一份通用的分析引擎，然后用数据描述每种语言的差异。

技术架构：为什么 Tree-sitter 是核心选择？

项目的技术栈非常精简：

源代码 → Tree-sitter AST → 配置驱动的查询引擎 → Mermaid 流程图

选择 Tree-sitter 而不是正则表达式或自定义解析器，原因有三：

1. 增量解析 + 容错能力

Tree-sitter 的核心优势是容错解析。即使代码有语法错误，它仍然能生成 AST。这对于快速原型和工具链开发来说至关重要。

相比如 python -m ast 或 clang -ast-dump，Tree-sitter 不需要编译、不需要完整的项目环境，直接解析源码文本。

2. 同一套 API 覆盖所有语言

// 伪代码：分析引擎的核心逻辑function analyze(source: string, config: LanguageConfig) {// 1. 加载语言对应的 Tree-sitter 语法const lang = loadGrammar(config.grammar)// 2. 解析源码为 ASTconst tree = parser.parse(source)// 3. 从配置文件读取 SCM 查询const query = new Query(lang, config.querySource)// 4. 在 AST 上执行查询，提取函数和调用const matches = query.matches(tree.rootNode)// 5. 输出结构化结果return { nodes, edges }}

不管你是 Go、Python 还是 Rust，核心逻辑一模一样。区别只在于 JSON 配置和 SCM 查询数据。

3. SCM 查询语言

Tree-sitter 的 SCM（S-expression Pattern Matching）是一种声明式的 AST 匹配语法：

; 匹配 Python 函数定义(function_definitionname: (identifier) @namebody: (block) @body) @function; 匹配 JavaScript 箭头函数(arrow_functionbody: (_) @body) @function

每个 @name、@body、@callee 都是捕获标记，引擎通过它们提取信息。

深入：调用链的跨文件合并

单文件分析不难，真正的挑战是全项目扫描。

当用户执行 npx aicode2flow ./ 时，引擎实际上在做什么？

// 伪代码：全项目扫描的核心逻辑async function scanProject(dir: string) {// 1. 递归遍历目录，收集所有支持的文件const files = walkDirectory(dir, supportedExtensions)// 2. 逐个分析每个文件const results = []for (const file of files) {results.push(analyzeFile(file))// 3. 合并结果：去重 + 跨文件连接const merged = {// 同名函数合并，调用列表合并nodes: deduplicate(results.flatMap(r => r.nodes)),// 跨文件调用边：只要目标节点存在就连线edges: resolveCrossFileEdges(mergedNodes, allCalls)return merged}

关键细节：

• 去重策略：同名函数（如 main）只保留一个节点，合并它的 calls 列表
• 跨文件连接：文件 A 中调用了 validate()，如果文件 B 中定义了 validate，跨文件也能连线
• 智能跳过：自动忽略 node_modules、.git、dist、__pycache__ 等目录

特性

aicode2flow

code2flow

js2flowchart

零安装 npx

❌ pip install

❌ npm i -g

多语言

✅ 8种

✅ Python/JS

❌ JS only

Mermaid 输出

✅ GitHub原生

❌ Graphviz

❌ SVG only

全项目扫描

跨文件合并

SVG/PNG 输出

持续维护

✅ 活跃

⚠️ 2023停更

⚠️ 2022停更

AI 增强：下一步的想象空间

项目预留了 --ai 参数接口。当前的规划是：

不依赖 AI 时，流程图展示的是代码结构（谁调用了谁）。

启用 AI 后，流程图展示的是业务语义—— 比如 LLM 分析后告诉你：

• validateEmail() → 不是"调用 validateEmail"，而是"验证用户邮箱格式"
• saveToDB() → 不是"调用 saveToDB"，而是"持久化用户数据到 MySQL"
• 整个流程从"函数调用图"变成"业务流程图"

这个功能的实现逻辑大致是：

// 伪代码：AI 语义增强async function aiEnhance(result: AnalysisResult): Promise {// 1. 收集函数源码上下文const contexts = result.nodes.map(n => extractSourceContext(n))// 2. 调用 LLM 生成语义标签const semanticLabels = await callLLM(contexts, {prompt: "用中文简短描述每个函数的核心业务逻辑"// 3. 替换节点标签return {...result,nodes: result.nodes.map((n, i) => ({...n,semanticLabel: semanticLabels[i]}

注意：AI 增强功能目前是 开发中，需要 API Key 支持。纯本地分析不需要网络。

整个项目的文件结构极其精简：

config/languages/    ← JSON 数据：每种语言的 AST 映射go.json / python.json / javascript.json / ...queries/             ← SCM 数据：AST 查询模式go.scm / python.scm / javascript.scm / ...src/engine/registry.ts        — 读取 JSON 配置analyzer.ts        — 通用分析引擎（配置驱动，无语言分支）template.ts        — Mermaid 模板渲染src/cli.ts           — CLI 入口，不到 200 行

核心哲学：加语言 = 加数据文件，不是加代码。

aicode2flow 是一个还在快速迭代的项目，但它已经证明了几个事情：

1. Tree-sitter 作为多语言代码分析基础设施的可行性— 同一套引擎覆盖 8 种语言，未来可以覆盖 20+ 种
2. 配置驱动架构的价值— 语言扩展的成本降到了最低，社区贡献的门槛也降到了最低
3. npx 生态的威力— 零安装体验让工具的传播成本趋近于零

如果你感兴趣，可以现在就体验：

npx aicode2flow ./你的项目目录

不需要安装任何东西。

项目地址：https://github.com/peterfei/aicode2flow

如果觉得有用，欢迎 Star、Fork、提 Issue。后续规划包括 VSCode 插件、在线 Playground、更多语言支持。

读代码不应该是件痛苦的事。