Enola 完全指南：用确定性架构图为 AI Agent 重建代码认知

AI 编码 Agent（Claude Code、Cursor、Codex）越来越擅长写代码，但有一个根本问题一直没解决——它们不理解你的代码架构。Agent 读的是文件，不是架构。它看到 handler.go 里的一个函数，但不知道这个函数在整个系统中的角色、被哪些模块调用、依赖哪些服务。

现有的解决思路是让 Agent 自己「读文件来理解」，但 LLM 对代码架构的理解本质上是猜测——它根据文件和目录名推断结构，而不是从源码的导入关系、路由注册、类型引用中提取精确的依赖图。结果就是：重构时 Agent 容易遗漏受影响的代码，集成新功能时可能打破已有的架构约束。

Enola（Apache-2.0，C 语言实现）用完全不同的方式解决这个问题——它不是让 LLM 去猜，而是用静态分析从源码中精确提取架构图，然后通过 MCP（Model Context Protocol）把这些架构信息变成 Agent 可以直接调用的工具。

Enola 的核心概念：从「猜架构」到「确定性地提取架构」

Enola 的核心理念在名字里就写明了——确定性。它不是让 LLM 分析代码后告诉你架构是什么样的，而是用静态分析器从源码中提取：

1. 模块和类型：包、类、接口、结构体、函数签名
2. 依赖关系：谁导入谁、谁调用谁、谁继承谁
3. 路由和端点：HTTP 路由注册、gRPC 服务定义
4. 跨仓库依赖：多个仓库之间的调用关系

所有这些信息被组织成一个有向图，存放在 .enola/ 目录下。每次生成快照后，Agent 通过 MCP 工具查询这个图——不是让 LLM 重新分析源码，而是直接在图上做图遍历（BFS/DFS 等确定性计算）。

关键区别：传统的「Agent 读源码」是 O(n) 扫描（读每个文件），Enola 的图查询是 O(1) 或 O(log n)——只要图建立好了，impact_analysis 立刻给出变更影响范围，不需要 Agent 重新读任何文件。

安装与配置

一行命令安装

curl -fsSL https://raw.githubusercontent.com/enola-labs/enola/main/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

安装后只有一个二进制文件（C 语言编译），体积小、无运行时依赖。

连接到 Agent

Claude Code：

claude mcp add enola enola

Cursor / VS Code（添加到 .vscode/mcp.json）：

{
  "servers": {
    "enola": { "command": "enola" }
  }
}

GitHub Copilot（添加到 .vscode/mcp.json）：

{
  "servers": {
    "enola": { "command": "enola" }
  }
}

配置（可选）

Enola 无需配置文件即可使用——它会自动索引当前目录。需要自定义时（如忽略特定目录、只启用部分解析器），从仓库下载配置模板：

curl -fsSL https://raw.githubusercontent.com/enola-labs/enola/main/mcp-arch.yaml -o mcp-arch.yaml

配置示例（多仓库模式）：

repositories:
  - path: /path/to/backend
  - path: /path/to/frontend
  - path: /path/to/auth-service

核心功能详解

Enola 暴露了 13 个 MCP 工具，按使用场景分为四组。

第一组：快照管理

generate_snapshot — 生成或刷新架构快照。这是第一个要调用的工具。支持 append 参数添加更多仓库：

"Generate an architectural snapshot of /path/to/my/project"
"Generate a snapshot of /path/to/go-service with append mode"

快照生成在毫秒级完成，即使是大项目也可接受。Enola 会缓存每个语言的分析结果，只有变更过的文件才重新解析。

snapshot_receipt — 查看快照的完整元数据：版本、git ref、快照 ID、输出哈希、提取质量指标。用于验证快照是否来自正确的代码版本。

compare_receipts — 比较两个快照是否可比。在 diff 操作之前先检查兼容性，防止比较不同基线。

第二组：架构查询

explore — 模块/文件/符号的引导式浏览：

"Based on the snapshot, give me a tour: the main modules, how they relate"

query_facts — 精确查询所有路由、接口、外部依赖：

"List every API endpoint and its handler"

query_insights — 获取分析发现的结果——未使用的路由、循环依赖、上帝类（God Class）：

"Are there cyclic dependencies or layer violations?"

show_symbol — 直接跳转到某个符号的源码：

"Show me the AuthService implementation"

第三组：图遍历（核心价值）

traverse — 沿依赖图正向或反向遍历：

"What does the payment module depend on?"
"What modules depend on the database layer?"

find_path — 找到两个点之间的最短调用链：

"How does the HTTP handler reach the repository layer?"

impact_analysis — 变更影响分析（最重要的工具）：

"If I refactor internal/server, what breaks?"

impact_analysis 计算传递闭包——找出所有直接和间接依赖于要修改代码的模块，按距离（几跳）分组。这是 Enola 的核心价值：不再让 Agent 猜变更影响范围，而是精确给出受影响的完整代码集。

覆盖报告的检查（可选）：初次使用后调用 coverage_report，看 Enola 成功解析了多少跨仓库边。识别真正的叶子服务与覆盖盲区。

第四组：变更验证

set_baseline — 在开始编辑前固定一个架构基线：

"Remember the architecture as it is now"

diff_snapshot — 修改后比较架构差异：

"What did my change actually do?"

diff_snapshot 只报告真正发生变化的部分——新增的耦合、移除的符号、新发现的问题。不报告已有的模式（原本就存在的循环依赖不会重复报警），让你专注在本次修改引入的变化上。

完整的变更验证流程：generate_snapshot → set_baseline → 编辑代码 → generate_snapshot → diff_snapshot。

实战：从加入新项目到完成重构

场景 1：新成员了解项目结构

加入一个不熟悉的代码库后，先用 Enola 生成架构快照，然后问：

"基于快照，给我一个项目导览：主要模块、它们之间的关系、从哪开始读代码。"

Agent 会利用 explore 和 query_facts 给出模块级视图，而不是逐文件列目录树。

场景 2：添加新功能前的架构预检

要给后端添加用户偏好 API 端点前：

"我需要添加用户偏好的 API 端点。影响哪些包？按什么顺序修改？"

Agent 用 impact_analysis 和 find_path 预判影响范围，给出从 handler 到 repository 的完整修改路径。

场景 3：重构后的架构验证

重构完成后，用 diff 验证：

"生成快照，保存基线，我改完代码后再生成一次，告诉我架构变化。"

流程：generate_snapshot → set_baseline → 修改 → generate_snapshot → diff_snapshot。

注意事项

1. 超大型项目：Linux 内核级别的超大仓库，首次冷索引可能超过 MCP 客户端的超时时间。解决方案：(a) 设置 MCP_TOOL_TIMEOUT=600000（10 分钟）；(b) 或从 shell 预生成：enola --generate ，之后 MCP 服务端启动时自动加载缓存的快照，后续增量更新仅重新解析变更文件。

1. Agent 撤回与重试：Enola 的工具调用是幂等的——同一个查询多次调用返回相同结果。如果 Agent 撤回工具调用再重试，结果一致。

1. 多语言支持：目前支持 Go、JavaScript、TypeScript、Python、Java、Kotlin。其他语言的文件会被略过但不会报错。

1. 跨仓库快照：快照默认包含当前目录。用 append 模式添加更多仓库后，Enola 将所有仓库链接成一个跨仓库依赖图，可以回答「如果修改 auth 服务，哪些前端仓库受影响？」这样的问题。

总结

Enola 解决了一个根本问题：AI 编码 Agent 对代码架构的「理解」应该是确定的，而不是猜测的。通过静态分析 + 图遍历 + MCP 工具的组合，它让 Agent 在做任何修改前就知道代码的精确结构，在修改后就知道做了什么改变。免费开源（Apache-2.0），一行命令安装，适用于 Go/JS/TS/Python/Java/Kotlin 项目。

相关链接：

• Enola GitHub
• ARCHITECTURE.md — 全部工具参数和配置参考
• MCP 协议规范