adder-factory/cartograph

🖼️ Gallery — open each screen as a still

Focused symbol — neighborhood graph, health / centrality / coverage, source, callers



Project overview — hub-centred core graph of this repository



Agent trace — full-page timeline of a recorded MCP session, with per-step detail and graph-link chips



Live — MCP tool calls streaming in as an agent works, with the active-session card and tool mix



Health dashboard — project score, findings, risk hotspots, index coverage



System overview — project status, feature-readiness meters, and LLM backend reachability

## 为什么选择 Cartograph 编程 agent 会将其大部分预算花费在反复阅读文件上，以回答结构性的问题：*它是在哪里实现的？谁调用了它？如果我修改它会破坏什么？哪些测试覆盖了它？* 对于大型代码库而言，反复扫描源码不仅速度慢、token 消耗大，而且很容易出错。 Cartograph 为你的代码库构建了一个本地知识图谱，并通过精确的查询将其暴露出来。agent（或开发者）可以准确请求其所需的符号、邻近范围、影响集或分析结果，并在无需将整个文件加载到上下文的情况下，获得紧凑且结构化的答案。 | agent 询问 | Cartograph 的回答 | |---|---| | “这是在哪里实现的？” | 名称、正则表达式、环境变量和 SQL 引用搜索，以及对已索引图谱的可选语义和意图搜索 | | “如果我编辑这个会破坏什么？” | 调用者、被调用者、影响半径、相关符号、共同变更历史以及受影响的测试 | | “这有风险吗？” | 生物标志物和代码健康度发现、热点、代码流失、覆盖率关联、依赖审计以及信任检查 | | “我应该先阅读什么？” | 来自 `cartograph context --format plan` 的路线规划，然后仅在需要的地方提供精确的源码 | | “我的修改涉及了什么？” | 交接前通过 `cartograph compare-to-ref` 获得的结构和发现差异 | 核心图谱功能不需要 LLM，并且在安装依赖项后即可离线工作。可选的 OpenAI 兼容 LLM 层级增加了摘要、embedding、语义搜索、`ask` 和重排序功能 —— 这些可由本地后端（llama.cpp、Ollama、Apple MLX、LM Studio）或云提供商（OpenAI、OpenRouter）提供服务。 ## 开始使用 只需安装一次 `cartograph` 二进制文件，然后在每个项目内运行安装程序 —— 安装和设置是一体化的流程。 ### 1. 安装 CLI 这行命令会获取适用于你平台的预构建独立二进制文件，并在安装前将其与发行版的 `SHA256SUMS` 进行校验（设置 `CARTOGRAPH_SKIP_CHECKSUM=1` 可跳过校验）： ``` curl -fsSL https://raw.githubusercontent.com/adder-factory/cartograph/main/install.sh | sh ``` PowerShell 等效脚本 (`install.ps1`) 以及由 agent 驱动的安装流程已在 [Agent 辅助安装](docs/AGENT-INSTALL.md) 中记录。 更倾向于从源码运行？需要 [Bun](https://bun.sh) `>= 1.3`： ``` git clone https://github.com/adder-factory/cartograph.git cd cartograph bun install bun link ``` `bun link` 会将 `cartograph` 添加到你的 `PATH` 中。使用 `cartograph --version` 进行验证。 以后若要更新源码安装版本： ``` cartograph upgrade # check how far behind the checkout is cartograph upgrade --apply # fast-forward + bun install, with safety guards ``` `cartograph update` 是一个别名。如果工作树不干净、分支已偏离其上游，或者 HEAD 处于分离状态，更新将被拒绝（不会进行任何更改）。之后请重启所有正在运行的 MCP 会话，以便它们加载新代码。 ### 2. 设置你的项目 ``` cd /path/to/your/project cartograph install --yes --location=local ``` 更喜欢交互式提示？运行普通的 `cartograph`（或 `cartograph install`）体验相同流程的交互式版本 —— 它会主动帮你把二进制文件链接到 `PATH`，让你选择 agent 和位置，并且在修改 git hooks 之前会进行询问。 SQLite 是零配置的默认选项；无需其他要求即可开始查询： ``` cartograph status --verbose cartograph find "SymbolName" --mode fuzzy ``` 从这里开始，你可以在[本地查看器](#local-viewer)中直观地探索已索引的图谱 —— 这是 Cartograph 的主要功能之一（`cartograph viewer .`，完整指南见 [docs/VIEWER.md](docs/VIEWER.md))。 要在*不*触碰任何 agent 配置的情况下为项目建立索引，请使用 `cartograph index .`（仅包含 init + index + 就绪检查；前身为 `quickstart`，目前仍作为别名有效）。 ### 3. 可选：LLM 功能 核心图谱不需要 LLM。若要添加摘要、语义搜索、`ask` 和重排序功能，请运行设置向导 —— 它会检测你环境中正在运行的本地后端（Ollama、llama-server、MLX、LM Studio）和云端密钥，并推荐一个预设： ``` cartograph llm setup # interactive wizard cartograph admin llm-apply --preset cloud-openrouter # or apply one directly ``` 设置了 `OPENROUTER_API_KEY` 后，一个密钥即可支持数百种托管模型的聊天层级 —— 在默认模型上，每处理一千个符号的批量摘要只需几分钱。而本地 GGUF 设置则保持完全离线。请参阅[配置](docs/CONFIGURATION.md)了解每个预设和层级。 应用预设会立即生效：正在运行的 MCP 服务器会实时获取 `.cartograph/config.json` 的更改，无需重启。

安装程序写入了什么（MCP 配置、git hooks、卸载）

- 为检测到的 agent 提供 **MCP 服务器配置及 agent 指令**（前提是目标支持）。支持的目标包括：Claude Code、Cursor、Codex CLI、GitHub Copilot CLI、CodeBuddy、CodeWhale、Zed、opencode、Hermes、Gemini CLI、Antigravity、Kiro、Factory Droid、Rovo Dev、Qoder CLI、IBM Bob、Kimi Code、Pi Agent 和 Reasonix。可以使用 `--target=` 显式指定。 - **托管的 git hooks**（`post-merge`、`post-checkout`、`post-rewrite`），确保在拉取、切换分支和变基时保持索引为最新。使用 `--no-hooks` 跳过；之后可使用 `cartograph install-hooks [--remove]` 进行管理。 - 如果 `cartograph` 无法在 `PATH` 中解析，安装程序会自动将绝对路径锁定到生成的配置中；使用 `--command ` 可覆盖此设置。 - 使用 `--location=global` 时，MCP 配置只需为所有项目写入一次，并且会跳过项目本地的步骤（init、index、hooks）—— 改为在每个项目中运行 `cartograph index .`。 为 `--location=local`（项目级 MCP 条目和指令文件）写入的配置会被添加到 `.gitignore` 中，因为它可能包含绝对的检出路径和个人的 agent 规则。以后若要从已安装的 agent 中删除 Cartograph 的 MCP 条目： ``` cartograph uninstall # global entries (default) cartograph uninstall --location local ``` 请参阅 [Agent 辅助安装](docs/AGENT-INSTALL.md)获取一个可直接粘贴的提示词，让编程 agent 执行整个设置过程，以及 PowerShell 的变体。

## 功能 所有功能界面及深入了解的途径： | | 功能 | 深入了解 | |---|---|---| | 🔎 | **搜索** —— 按符号名称搜索（精确、模糊、语义、意图），正则表达式内容搜索，环境变量读取，以及 SQL 表引用 | [搜索与导航](docs/CLI-REFERENCE.md#search-and-navigation) | | 🕸️ | **图谱导航** —— 调用者、被调用者、影响半径、多跳遍历、最短路径以及 embedding 相似度的同类节点 | [搜索与导航](docs/CLI-REFERENCE.md#search-and-navigation) | | 🧪 | **影响与测试** —— 针对已更改文件的受影响测试、各符号的覆盖率关联，以及包脚本验证命令 | [变更与测试选择](docs/CLI-REFERENCE.md#change-and-test-selection) | | 🩺 | **代码健康度** —— 生物标志物和代码健康度发现、代码流失 × 中心性的热点、死代码候选者以及依赖审计 | [审查与风险](docs/CLI-REFERENCE.md#review-and-risk) | | 🕰️ | **历史记录** —— 符号级别的 git blame 和共同变更信号 | [历史与重构](docs/CLI-REFERENCE.md#history-and-refactors) | | ✅ | **审查** —— diff 驱动的上下文、语义邻近内容、组合风险分拣以及就绪状态自检 | [审查与风险](docs/CLI-REFERENCE.md#review-and-risk) | | 🧭 | **上下文计划** —— 针对任务范围的路线规划，会在阅读任何源码之前建议下一步的查询 | [MCP 用法](docs/MCP-USAGE.md) | | 🚪 | **入口点** —— 跨越多种框架的路由、CLI 命令、MCP 工具和公共导出 | [支持矩阵](docs/SUPPORT-MATRIX.md) | | 🗺️ | **交互式查看器** —— 具备节点形状语言、健康度边框、枢纽光晕、影响/路径/对比工具的本地 Web UI | [查看器指南](docs/VIEWER.md) | | 📡 | **Agent 可观测性** —— 观看 agent 实时遍历图谱（按会话的信息流），并利用图谱链接芯片回放完整的工具调用时间线 | [查看器指南](docs/VIEWER.md) | | 📤 | **导出** —— 将图谱快照导出为 JSON、DOT、Mermaid 和 Cytoscape 格式 | [导出格式](docs/GRAPH-EXPORT-FORMATS.md) | | 🤖 | **MCP 服务器** —— 配置文件、加载预算、低 token 模式，以及为每个主要 agent 提供的客户端代码片段 | [MCP 用法](docs/MCP-USAGE.md) | | 🧩 | **LLM 层级（可选）** —— 通过本地后端（Ollama、llama.cpp、MLX）或云端（OpenAI、OpenRouter）提供摘要、embedding、语义搜索、提问和重排序 | [配置](docs/CONFIGURATION.md) | | 🗄️ | **存储** —— 零配置的 SQLite 或可选的 PostgreSQL 18+；两者均内置了向量搜索（sqlite-vec + HNSW，或原生 pgvector）—— 无需单独的向量数据库 | [存储后端](docs/STORAGE-BACKENDS.md) | Cartograph 支持 **73 种语言模式**，并能识别跨越 JavaScript / TypeScript、Python、PHP、Ruby、JVM、Go、Rust、C#、Dart、Swift 和 Salesforce 生态系统的框架感知信号（路由、控制器、组件、schema、DI 绑定）。诸如 Zod、Pydantic、GraphQL SDL、Prisma 和 SQL 等嵌入式 DSL 会贡献结构化节点和引用边。请查看[支持矩阵](docs/SUPPORT-MATRIX.md)获取完整列表。 ## 用法 ### 从 MCP agent 运行 直接运行服务器，或者让 `cartograph install` 将其连接到你的客户端： ``` cartograph serve --mcp # default 'core' profile cartograph serve --mcp --profile full # full tool surface cartograph serve --mcp --no-daemon # standalone (CI / test isolation) ``` 默认情况下，`serve --mcp` 作为共享的**每个项目守护进程**运行 —— 每个项目一个写入器 —— 这样多个在同一个项目上工作的 agent 可以共享一个单一的索引写入器，而不是同时重新建立索引并互相破坏；stdio 进程会代理到该守护进程。传递 `--no-daemon` 可使用独立的进程内服务器。请参阅 [MCP 用法](docs/MCP-USAGE.md)了解守护进程模型。 Cartograph 注册了 **34 个 MCP 工具**（均带有 `cartograph_` 前缀）。默认的 `core` 配置文件只公布 14 个最常用的编程 agent 工具，以保持已加载工具集的精简；`full` 配置文件公开所有内容，而 `read-only` 和 `review` 配置文件则属于特定作用域的子集。一个典型的编辑会话链如下： ``` cartograph_context({ task: "", format: "plan" }) → follow the suggested next action → cartograph_affected({ includeCommands: true }) → cartograph_compare_to_ref({ findingsDelta: true }) ``` 请参阅 [MCP 用法](docs/MCP-USAGE.md)了解配置文件、启动时的加载预算、低 token 模式以及客户端配置片段。 ### CLI 运行 ``` # 查找和检查代码 cartograph find "AuthService" --by name --mode fuzzy cartograph graph AuthService --direction impact cartograph node AuthService --include-callers --include-tests # 检查文件和结构 cartograph files . --format tree cartograph files --format symbols --file src/auth/service.ts # 审查当前工作 cartograph review context --diff "$(git diff)" cartograph affected --include-commands cartograph compare-to-ref --findings-delta ``` CLI 一对一地镜像了 MCP 的工具表面。请参阅 [CLI 参考](docs/CLI-REFERENCE.md)了解所有的命令和标志。 ### 从 TypeScript 运行 ``` import Cartograph from '@adder-factory/cartograph'; const cg = await Cartograph.open('/path/to/project'); // ... query the graph, then cg.close() ``` MCP 服务器也可以从 `@adder-factory/cartograph/mcp` 子路径导入。 ### 本地查看器 ``` cartograph viewer . # 打开 http://localhost:8765/ ``` 该查看器强制仅绑定到回环地址的 HTTP，在本地托管其浏览器资产，并读取与 CLI 和 MCP 服务器相同的图谱索引。配置的 PostgreSQL 或 LLM 端点可能仍然是远程的；System 会探测这些 LLM 端点，而 Ask 会将其选择的上下文发送到配置的聊天后端。节点形状编码了符号种类（圆形代表可调用对象，菱形代表契约，六边形代表路由，桶形代表数据存储），边框编码了代码健康度，而中心性缩放的光晕则让枢纽符号更加显眼。Rails 可按种类、健康度、边种类以及按项目的文件范围进行过滤；内置工具涵盖了影响分析、最短路径、与 HEAD 对比、保存的视图以及 PNG/SVG/JSON 导出。 图谱之外：**Agent 追踪**选项卡将记录的 MCP 会话作为全页时间线回放（包含每次调用的时间、参数、结果，以及可从追踪步骤跳转至其所涉符号的图谱链接芯片），**Live** 选项卡在 agent 工作时实时流式传输工具调用，而 **System** 选项卡则汇集了**概览**状态页面（项目计数、数据库大小、版本、同步状态、功能就绪情况和 LLM 后端可达性）、**健康度**仪表板（项目得分、发现的问题和风险热点），以及一个用于 `.cartograph/config.json` 的**设置**编辑器。会话严格按项目划分（一个数据库 = 一个查看器），每个浏览器标签页都以其项目名称命名，而 `cartograph viewer --session ` 可为单个 agent 提供其独立的隔离窗口。请参阅 [docs/VIEWER.md](docs/VIEWER.md) 获取完整指南。 ## 语言和存储 ### 语言 Cartograph 支持 **73 种语言模式**，包括 TypeScript / JavaScript / ArkTS、Python、Go、Rust、Java / Kotlin / Scala / Groovy、C / C++ / C# / CUDA、Swift / Objective-C、PHP、Ruby、Salesforce Apex 及其他数十种语言，并辅以框架感知信号和嵌入式 DSL 提取。[支持矩阵](docs/SUPPORT-MATRIX.md)是从注册表生成的，是权威列表。 ### 存储 SQLite 是默认选项，无需任何配置即可立即工作。它是最快的本地单写入器后端，并通过 Bun 嵌入的 SQLite 运行时进行能力检查。向量搜索也是内置的：语义查询在 sqlite-vec 和 USearch HNSW 索引上运行 —— 没有单独的向量数据库需要安装或操作。 PostgreSQL 18+ 是可选的，用于共享或外部存储、托管备份、运营级数据库控制，以及用于在服务器端进行相同向量搜索的原生 pgvector： ``` cartograph admin init -i \ --database-provider postgres \ --database-url postgres://cartograph:cartograph@localhost:5432/cartograph \ --database-schema cartograph \ --database-pgvector auto ``` 现有的图谱支持**双向**在后端之间迁移 —— 从 SQLite 迁移到 PostgreSQL 并可回迁，无需重新建立索引 —— 可通过 `cartograph admin storage-migrate` 完成。 请参阅 [存储后端](docs/STORAGE-BACKENDS.md)了解 PostgreSQL 的最低要求、pgvector 模式、生产环境授权、托管 TLS 说明、迁移细节以及本地基准测试。 ## Cartograph 不是什么 | 期望 | 现实 | |---|---| | 托管的 SaaS | 本地优先；默认情况下图谱存在于本地 SQLite 中，或者存在于你自己的 PostgreSQL 实例中 | | 测试替代品 | 它会揭示受影响的测试和风险；你的测试套件仍然是事实的来源 | | 纯 LLM 审查器 | 审查和风险工具首先依赖确定性的图谱查询；LLM 功能是可选的 | | 云端依赖 | 核心索引和图谱查询在安装依赖项后即可离线运行 | ## 文档 | 主题 | 文档 | |---|---| | Agent 辅助安装（可粘贴的提示词，PowerShell） | [docs/AGENT-INSTALL.md](docs/AGENT-INSTALL.md) | | CLI 命令参考 | [docs/CLI-REFERENCE.md](docs/CLI-REFERENCE.md) | | MCP 设置、配置文件、加载预算、客户端片段 | [docs/MCP-USAGE.md](docs/MCP-USAGE.md) | | 查看器指南（形状、过滤器、工具、快捷键） | [docs/VIEWER.md](docs/VIEWER.md) | | PostgreSQL、pgvector、迁移、存储基准测试 | [docs/STORAGE-BACKENDS.md](docs/STORAGE-BACKENDS.md) | | 配置和高级选项 | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | | 语言和框架支持矩阵 | [docs/SUPPORT-MATRIX.md](docs/SUPPORT-MATRIX.md) | | 图谱导出工件格式 | [docs/GRAPH-EXPORT-FORMATS.md](docs/GRAPH-EXPORT-FORMATS.md) | | 添加一种语言 | [docs/ADDING-A-LANGUAGE.md](docs/ADDING-A-LANGUAGE.md) | | 故障排除 | [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | ## 许可证 [MIT](https://opensource.org/licenses/MIT)

如果 Cartograph 为你的 agent 节省了 token，一颗 ⭐ 能帮助其他人发现它。 [报告 Bug](https://github.com/adder-factory/cartograph/issues) · [请求功能](https://github.com/adder-factory/cartograph/issues)

标签：AI编程助手, MCP, Petitpotam, SOC Prime, TypeScript, 云安全监控, 代码智能, 安全插件, 开发工具, 测试用例, 自动化攻击, 静态分析