Carto 实战：给 AI 编程工具装上代码架构感知层
AI 编程工具在过去两年里的进步有目共睹——从自动补全代码到自主完成功能开发，从单文件编辑到跨文件重构。但你有没有发现一个奇怪的现象：Claude Code 或 Cursor 在大型项目中经常跑偏？它明明能看到所有文件，却总是猜错你应该改哪个模块。
这不是模型不够聪明，而是信息不对称——AI 工具看到的是文件，但人类开发者心里装的是架构：这个路由属于 AUTH 域、改这个文件会影响 7 个下游模块、类似的中间件模式已经写在 payment 模块里了。AI 没有这些「架构感知」，只能 grep + 盲猜。
Carto 就是来解决这个问题的——它是一个开源的代码结构智能层（Structural Intelligence Layer），通过 MCP 协议为 AI 编程工具提供代码库的架构级理解。安装它之后，AI 不再是问一个文件答一个文件，而是能理解整个项目域、影响范围和依赖图。
一句话说清 Carto 做了什么
传统模式下，当你让 AI「给 /api/users 加限流」，它做的是：
grep -r "users" src/ → 找到 12 个文件 → 随机挑 3 个 → 靠猜写代码 → 可能把不该改的模块改了
有了 Carto 后，同样的请求会变成：
get_change_plan("给 /api/users 加限流") → 返回：
- 路由所在文件：src/routes/users.ts
- 影响范围：7 个依赖文件（含 blast radius）
- 所属域：AUTH
- 已有类似模式：src/middleware/rate-limit.ts
AI 的回答从「我觉得是这样」变为「架构上应该这样做」。
安装和上手
Carto 安装极其简单——一条命令：
npm install -g carto-md cd your-project carto init
carto init 做三件事：
- 解析代码库——用 tree-sitter 解析导入关系和符号，用 Babel 解析路由和模型定义，用 Leiden+CPM 图聚类自动检测域（Domains），所有数据存入本地 SQLite
- 生成 AGENTS.md——在每个 AI 工具都读取的项目根目录生成架构概要文件
- 自动缝合 MCP——检测你已安装的所有 AI 编程工具（Cursor、Claude Code、Claude Desktop、VS Code Copilot、Windsurf、JetBrains、Zed），自动配置 MCP Server
重启你的 AI 工具，它现在就有了架构感知能力。
实测一个包含 6,259 个 TypeScript 文件的 Supabase 仓库，首次解析只需 4.8 秒，后续增量同步仅 751ms。完全不会拖慢你的开发流程。
如果想实时感知文件变更，可以开一个 watch 模式：
carto watch
每次按 Ctrl+S 保存文件，Carto 在 50ms 内完成增量解析。
16 个 MCP 工具：AI 的架构望远镜
Carto 通过 MCP 协议暴露了 16 个工具，AI 会在合适的时机自动调用它们。下面是几个最实用的：
| MCP 工具 | 返回内容 |
|---|---|
get_architecture() | 项目概览：域、入口点、技术栈、关键模式（第一个调用它） |
get_change_plan(intent) | 给定需求 → 要改的文件、影响的域、影响范围、已有相似模式 |
get_blast_radius(file) | 修改某个文件会影响的完整文件列表（含跳数） |
get_context(file) | 关于一个文件的所有信息：域、影响范围、邻居、路由、模型 |
get_similar_patterns(file) | 同域、同路由型的文件——写新代码前先看已有模式 |
get_routes() | 所有 API 端点及对应文件 |
get_structure() | 导入图、入口点、高影响文件、技术栈 |
get_domain(name) | 某个域下的所有路由、模型、函数 |
get_cross_domain() | 跨域依赖边——重构前必查 |
所有这些查询的响应时间都在 5ms 以内——AI 调它们完全不会增加感知延迟。
域检测：自动发现项目的架构边界
域检测可能是 Carto 最核心的能力。它不是说「我给你预设好三个域」，而是用图聚类算法自动发现你的代码库里存在哪些逻辑域。
比如微服务 vscode 仓库（7,567 个文件），Carto 自动检测出了 CORE、AUTH、DATABASE、EVENTS、NOTIFICATIONS 等域。而在 zed（Rust 仓库）中同样检测出了类似的架构分组。
你也可以在 carto.config.json 中手动指定域名映射规则：
{
"domains": {
"EDITOR": ["editor", "monaco", "text"],
"WORKBENCH": ["workbench", "layout", "panel"]
}
}
ACP Agent 模式：不只是 MCP 服务器
除了作为被动的 MCP 服务器，Carto 还可以作为主动的 ACP Agent 运行——像一个具备架构意识的独立编码 Agent，适用于 Zed、JetBrains 和 VS Code：
carto agent
在这个模式下，用户下发需求后，Carto 自动查询自己的 SQLite 数据库获取架构上下文，构建包含结构信息的 Prompt，然后发送到你配置的 LLM（支持 Anthropic、OpenAI、Gemini、Ollama、OpenRouter、Groq 等主流提供商），最后将回答和 diff 流式返回给编辑器。
多语言和框架支持
Carto 的导入图分析支持 TypeScript、Python、Go、Rust、Java、C/C++、C#、Ruby 等主流语言。路由提取则是框架感知的：
- JavaScript/TypeScript：Express、Next.js、tRPC、React Router
- Python：FastAPI、Flask、Django
- Go：Gin、Echo、Chi
- Rust：Actix-web、Axum、Rocket
- Java：Spring MVC、JAX-RS
- C#：ASP.NET Core
- Ruby：Rails、Sinatra
模型/ORM 层同样支持 Prisma、Pydantic、SQLAlchemy、JPA @Entity、EF Core 等主流框架。
实际体验：用 Carto 做一次代码变更
让 Claude Code 配合 Carto 做一个跨域变更——给用户创建流程加上邮箱验证。没有 Carto 时，Claude 需要反复读文件、确认依赖，耗时且可能出错。有了 Carto 后，它直接调用 get_change_plan 获取完整的变更计划，然后按图索骥完成修改。开发者只需要审核 diff 确认即可。
如果你的编辑器不支持 ACP Agent 模式，单纯使用 MCP 模式也已经够用——AI 工具会在需要时自动调用 Carto 的 16 个工具，你不需要在对话中额外提示它「去查一下架构」。
安全与隐私
Carto 承诺三不：不发送代码（所有处理在本地 SQLite 完成）、不写入密钥（.cartoignore 默认排除 .env 和凭据文件）、不收费（MIT 许可证）。
总结
Carto 解决的是一个被大多数 AI 编程工具忽视的问题：AI 只能看到文件和文本，却看不到代码库的结构和架构。当一个项目从几十个文件增长到几百甚至几千个文件时，这种「结构盲区」会成为 AI 编码质量的最大瓶颈。
16 个 MCP 工具覆盖了从架构概览到变更影响分析的完整链路，Leiden+CPM 的域检测让任何项目都能获得自动化的架构边界识别，5ms 以内的查询延迟确保了 AI 的交互流畅性。如果你正在用 Cursor、Claude Code 或 Copilot 开发中型以上的项目，Carto 是目前最值得安装的 MCP 工具之一。