cartographer

Cartographer 是一个本地优先的软件架构导航系统，以 Cursor 插件加从仓库构建的 CLI 形式分发。它针对的问题是：大型代码库本质上是伪装成文件夹的图：打开一个文件就会丢失周围的架构。 核心理念：`cartographer index` 勘察仓库，并在 `.cartographer/` 下写入持久化 Atlas——一个 SQLite 数据库（`atlas.db`），包含文件、符号、关系、领域和派生地图层，以及可选的 JSON 用于地标、旅程和探索状态。所有其他界面都读取这一个 Atlas 门面，而不是构建第二张图。 旗舰输出是 Living Atlas Briefing，由 `index`、`brief`、`whereami` 和 `tour` 打印。它报告勘察计数（文件、符号、边）、带置信度分数的领域 Mini Atlas、针对 file:line 的 YOU ARE HERE 面包屑、顶级走廊（例如 API → Domain → Data）、枢纽与桥梁，以及 START HERE 建议。 命令界面包括：`index`（带 `--incremental`、`--no-brief`）、`brief`、`whereami`/`where`（带 `--compact`）、`goto`、`route` 和 `explain-route`（用于符号之间的走廊感知路径）、带深度的 `upstream`/`downstream` 邻域查询、`territories`、`hubs`、`corridors`、`landmarks`（添加固定到 file:line 的命名地点，并在重新索引时进行漂移检查）、`journeys`、`tour`、用于战争迷雾前沿的 `unexplored`、`search`、用于本地 Git 考古的 `history`，以及用于健康、覆盖率和完整性的 `status`/`doctor`。大多数命令接受 `--json`。 语言适配器是确定性的，不需要原生 tree-sitter 二进制：TypeScript/JavaScript（包括 TSX）、Python（Flask/FastAPI、Click）、Go（handlers、Cobra）和 Rust（Axum/Actix、Clap/Tauri）。适配器提取符号、导入、调用和入口点；跨文件链接、领域推断、枢纽和走廊在核心中运行。 MCP 服务器向代理暴露相同的 Atlas 工具（brief、whereami、goto、route、upstream、downstream、territories、hubs、search、unexplored、tour、doctor、status、index），通过 `mcp.json` 配置以运行构建后的 `dist/mcp/index.js`。Cursor 插件还附带斜杠命令、技能、代理角色、规则和钩子。 设置需要 Node.js 20+（推荐 22/24），并使用内置的 `node:sqlite`。安装方式是 clone → `npm install` → `npm run build`，可选 `npm link`。项目声明它不是 npm registry 包。配置可通过 `.cartographer/config.toml`（索引排除项、文件大小上限、探索开关、Git 历史开关）以及 `.cartographerignore` 可选进行。 隐私姿态是本地优先：无遥测，核心导航不需要 API 密钥或云账户，Atlas 数据存储在本地，Git 历史仅在本地读取。README 指出 `.cartographer/` 可能镜像代码库中的路径和符号名称。 许可值得注意：项目自称是源码可得的专有软件，生产、再分发和商业部署需要书面商业许可或收购；评估在 LICENSE 文件下被允许。还包括贡献指南、安全政策、考虑方向的路线图，以及资助链接（GitHub Sponsors、thanks.dev）。