miltonian/cartographer

## 问题所在 你通过构建心智模型来理解代码库——不是文件，而是行为：当用户注册时会发生什么，支付如何流转，哪里可能出现故障。那个模型只存在于你的脑海中。每次都要从头开始重建。它无法被分享、检查或查询。 **Cartographer 将该模型外化。** 它赋予了 Claude Code 关于你代码库行为和结构的持久记忆——以源代码证据为基础，可作为地图导航，并且对工程师和非工程师都易于访问。 ## 它的作用 ``` You: "explore this codebase" Claude traces the system's key behaviors end-to-end. Entities emerge from the flows — not from directory structure. Boundaries form around concerns that break together. The map shows what the system DOES, not how files are organized. Each fact links back to the exact source code that proves it. Open localhost:3847 to see the map. Click a boundary to zoom in (semantic zoom). Select a behavior flow to see the path light up. Ask Claude questions — answers cite the stored model. ``` ## 入门指南 ### 前置条件 - [Node.js](https://nodejs.org/) 20+ - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI ### 通过插件市场安装 ``` /plugin marketplace add miltonian/cartographer /plugin install cartographer@cartographer ``` ### 从源码安装 ``` git clone https://github.com/miltonian/cartographer.git cd cartographer npm install npm run build:ui claude --plugin-dir ./plugin ``` ### 使用 ``` /cartographer explore # Deep autonomous exploration /cartographer analyze # Guided analysis (or focused: analyze auth) /cartographer review-pr 123 # Overlay a PR on the map /cartographer map # Open browser UI /cartographer status # Model statistics /cartographer snapshot # Save a backup /cartographer restore # Restore from backup /cartographer reset # Start fresh ``` ## 工作原理 ### 三个组成部分 ``` ┌──────────────────────────┐ │ Claude Code + Plugin │ Agent. Traces behaviors, records findings. │ │ MCP (stdio) │ ├──────────┼───────────────┤ │ Local Service │ Backbone. Stores world-model, serves API. │ │ HTTP + WS │ ├──────────┼───────────────┤ │ Browser UI │ Map. Renders projections, navigable depth. └──────────────────────────┘ ``` ### 行为优先分析 Cartographer 首先关注**发生了什么**，而不是存在什么。Agent： 1. 识别系统的关键行为（“这个系统做的最重要的事情是什么？”） 2. 在代码中端到端地追踪每个行为 3. 记录在流程中遇到的实体 4. 让边界从实体的聚集方式中自然显现 结构源于行为，而非目录。 ### 本体论 | 实体类型 | 代表什么 | |---|---| | `boundary` | 一个关注点——会一起发生故障的事物 | | `capability` | 系统可以执行的操作 | | `actor` | 外部意图进入的地方 | | `entity` | 持久化或转换的状态 | | `side-effect` | 边界之外可观察到的结果 | | `invariant` | 必须成立的规则 | | `failure-point` | 系统可能发生故障的地方 | ### 证据而非幻觉 每个事实都带有源代码证据和置信度级别： | 置信度 | 含义 | |---|---| | `proven` | 在源代码中直接观察到的 | | `high` | 距离观察到的事实一步推理 | | `medium` | 综合多次观察得出的结论 | | `low` | 有根据的猜测 | | `speculative` | 假设，尚未验证 | 地图在视觉上区分了所有级别。你始终能知道哪些是已证实的，哪些是推断出来的。 ### 行为流 流是理解的基本单位——一条贯穿系统的命名路径： ``` Customer checkout: Cart validation → Payment processing → Order creation → Confirmation email ``` 在 UI 面板中选择一个流，即可在地图上看到其高亮显示。每个步骤都有编号。未参与的节点会变暗。 ### 视角 从多个角度查看同一个代码库。视角是一个命名的透镜——聚焦于实体子集的视图。 - **默认**——所有内容（卫星视图） - **Agent 创建的**——聚焦于某个关注点（“auth”、“data pipeline”） - **边界派生的**——通过语义缩放（点击某个边界）创建 每个视角都有其独立的布局。通过 URL 参数，可以在多个浏览器标签页中打开不同的视角。 ### 语义缩放 点击边界即可进入。其子项将成为整个世界。面包屑导航显示你的路径：`Overview › Service › WorldModelStore`。点击可返回。Agent 可以根据请求创建更深的层级。 ### PR 审查 ``` /cartographer review-pr 123 ``` 在地图上将 PR 作为变更集进行叠加：绿色（已添加）、琥珀色（已修改）、红色（已移除）、灰色（受影响）。一眼就能看出更改的空间影响。 ### 快照 ``` /cartographer snapshot before-refactor /cartographer snapshots /cartographer restore ``` 在执行破坏性操作之前自动创建快照。可随时创建手动快照。保留最近 10 个快照。 ## MCP 工具 | 工具 | 目的 | |---|---| | `cartographer_set_project` | 设置项目根目录 | | `cartographer_write_entity` | 记录带有证据的实体 | | `cartographer_write_relationship` | 记录关系 | | `cartographer_write_slice` | 记录行为流或 PR 变更集 | | `cartographer_create_perspective` | 创建命名透镜 | | `cartographer_switch_perspective` | 切换活动透镜 | | `cartographer_query` | 搜索实体/关系 | | `cartographer_get_entity` | 获取完整实体详情 + 证据 | | `cartographer_get_summary` | 获取模型统计信息 | | `cartographer_snapshot` | 保存备份 | | `cartographer_restore` | 从备份恢复 | | `cartographer_open_map` | 打开浏览器 UI | | `cartographer_clear` | 重置世界模型 | ## 架构 有关完整的系统图，请参阅 [`docs/architecture.md`](docs/architecture.md)。 关键约束： - **行为优先**——追踪发生的事情，让结构自然显现 - **代理优先**——Claude Code 是控制平面 - **基于证据**——每个声明都可追溯到源代码 - **与语言无关**——本体论不涉及 TypeScript 或 React - **UI 是一种投影**——React Flow 的概念不会泄漏到存储的模型中 ## 路线图 - [ ] 过期实体检测（标记源代码已更改的实体） - [ ] 从浏览器 UI 进行用户纠正（编辑描述，移动边界） - [ ] 能力包（可选的 AST 提取器，用于提供更高置信度的事实） - [ ] 流动画（逐步回放） - [ ] 变更影响分析 - [ ] 大型代码库优化 - [ ] 多项目支持 - [ ] 可共享的模型 ## 理念 大多数代码工具向你展示的是代码说了什么。Cartographer 向你展示的是代码意味着什么。 理解就是行为预测。当你能够预测在发生变更时会出现什么情况，你就理解了这个系统。这需要一个包含流、边界、状态、不变量和故障模式的模型——而不仅仅是一个文件树。 地图不是疆域。但一张好的地图能让疆域变得可导航。 ## 许可证 [MIT](LICENSE) ## 贡献 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。目前最有价值的贡献是在你的代码库上尝试它，并告诉我们缺少了什么。

_{使用 Claude Code 构建。}

标签：Agent, AI编程助手, Claude插件, DLL 劫持, GNU通用公共许可证, MITM代理, Node.js, TypeScript, 世界模型, 云安全监控, 代码可视化, 代码地图, 代码库分析, 代码搜索, 代码文档生成, 代码理解, 大语言模型, 威胁情报, 安全插件, 实体提取, 开发者工具, 心智模型, 持久化记忆, 数据管道, 系统架构, 自动化分析, 行为追踪, 证据溯源, 跨站脚本, 软件工程, 静态分析