Cartograph

Cartograph

Cartograph 为编码 Agent 提供面向任务的代码库上下文。它包含一个命令行工具、一个 MCP 服务、适用于 Claude Code 和 OpenClaw 的用户级安装适配器，以及面向文档密集型工作流的打包 Agent 资源。

• npm：@anthony-maio/cartograph
• MCP Registry：io.github.anthony-maio/cartograph
• 快速入门：cartograph.making-minds.ai

Cartograph 不会把整个代码库都塞进上下文，而是为相关文件排序、梳理依赖关系、缓存结构化产物，让下一个工具或 Agent 可以接着使用这些产物。

主要工作流如下：

1. 使用 analyze 映射代码库
2. 使用 packet 准备工作
3. 使用 context --static 加载与任务匹配的文件，无需调用模型

wiki、主机安装和基准测试都是围绕这条核心路径构建的次要功能。

安装

npm install
npm run build

通过 npm 全局使用：

npm install -g @anthony-maio/cartograph

通过官方 Registry 发现 MCP 主机：

• io.github.anthony-maio/cartograph
• Registry 列表

从此公开代码库安装 Claude Code 插件：

/plugin marketplace add anthony-maio/cartograph
/plugin install cartograph@making-minds-tools

从本地检出版本全局使用：

npm install -g .

开发工作流请参阅 CONTRIBUTING.md，漏洞报告请参阅 SECURITY.md。

运行完整示例

npm 包附带一个小型刷新令牌示例。在新的工作目录中运行：

npm init -y
npm install @anthony-maio/[email protected]
npx cartograph analyze ./node_modules/@anthony-maio/cartograph/examples/auth-refresh --static
npx cartograph packet ./node_modules/@anthony-maio/cartograph/examples/auth-refresh --type bug-fix --task "fix refresh token expiry"
npx cartograph context ./node_modules/@anthony-maio/cartograph/examples/auth-refresh --task "fix refresh token expiry" --static --json
node --test ./node_modules/@anthony-maio/cartograph/examples/auth-refresh/tests/auth-refresh.test.js

该任务包应指向 src/auth/refresh.js 和 tests/auth-refresh.test.js。上下文包会包含时钟辅助工具，并排除无关的账单和目录文件。三项行为检查都应通过。请参阅调查演练，了解预期结果以及如何在自己的代码库中应用相同流程。

Claude Code 插件

此代码库也可作为 Claude Code 插件市场。cartograph 插件包含：

• 插件级 Cartograph MCP 服务
• 斜杠命令：/cartograph:analyze、/cartograph:context、/cartograph:wiki
• use-cartograph 和 repo-surveyor 技能
• 文档 Agent 套件：repo-scout、dependency-tracer、context-picker、api-surface-writer 和 wiki-writer

安装方式：

/plugin marketplace add anthony-maio/cartograph
/plugin install cartograph@making-minds-tools

主要工作流

如果你只记住一件事，请记住：

cartograph analyze <repo> --static
cartograph packet <repo> --type <type> --task "<task>"
cartograph context <repo> --task "<task>" --static --json

• analyze 会映射代码库，并指出哪些内容最重要。
• packet 会将具体任务转化为可复用的工作产物。
• context --static 会选出与任务匹配的文件及其附近的依赖和测试，并附上文件内容。它使用本地启发式方法，无需 API 密钥。

单独的模型驱动上下文工作流会在省略 --static 时运行；使用前请先配置提供方。两种模式都无法证明所选文件中包含该错误。

命令概览

cartograph analyze <repo> [options]
cartograph packet <repo> --type <type> --task "<task>" [--changed <paths...>]
cartograph context <repo> --task "<task>" [options]
cartograph wiki <repo> [options]
cartograph export <run-id> --to <path> [--artifact <name>]
cartograph install <claude|openclaw|mcp>
cartograph uninstall <claude|openclaw|mcp>
cartograph doctor [target] [--json]
cartograph mcp

仍支持旧版兼容用法：

cartograph <repo> --static
cartograph <repo> -c "trace auth flow"

命令行用法

# Map the repo
cartograph analyze ./my-project --static

# Prepare a concrete job
cartograph packet ./my-project --type bug-fix --task "fix auth refresh bug" --changed src/auth/service.ts tests/auth/service.test.ts

# Load the minimum file set for that job
cartograph context ./my-project --task "add user authentication" --static --json

# Force embedded snippets when you really want them
cartograph analyze ./my-project --static --json --include-contents

# Full wiki output
cartograph wiki ./my-project -p gemini -k $CARTOGRAPH_API_KEY -o wiki.md

# Export a cached artifact to an explicit path
cartograph export run-abc123 --to ./artifacts/wiki.md

# Run the MCP server directly
cartograph mcp

对于小型代码库，analyze --static --json 现在默认输出紧凑结果，而不是嵌入顶级文件的内容。这样可让小型代码库保持易读，并使直接读取文件比生成庞大的 JSON 内容更省资源。如果明确需要嵌入代码片段，请使用 --include-contents。

analyze --static 默认的 Markdown 输出以人为阅读为先：它会突出重要内容、展示依赖枢纽，并推荐后续命令，而不是一开始就倾倒原始文件内容。

提供方

• gemini
• openai
• openrouter
• ollama

使用 --key 或 CARTOGRAPH_API_KEY 设置 API 密钥。Ollama 无需密钥。

缓存模型

默认情况下，Cartograph 会将成功运行的结果写入用户缓存：

• Windows：%USERPROFILE%\\.cartograph\\cache
• POSIX：~/.cartograph/cache

每次运行都会生成一个清单和多个命名产物，从而让 Agent 交接更轻量，并使 cartograph export 具有确定性。

主机安装

Cartograph 采用明确的混合安装模式。安装软件包不会自动修改 Claude Code、OpenClaw 或 MCP 主机配置。

请改为只安装你需要的集成：

cartograph install claude
cartograph install openclaw
cartograph install mcp

各目标安装的内容：

• claude：安装用户级技能，以及打包的文档 Agent，位于 ~/.claude
• openclaw：安装用户级技能包，位于 ~/.openclaw
• mcp：在 ~/.cartograph/mcp 下安装 Cartograph MCP 配置片段

随时检查状态：

cartograph doctor
cartograph doctor --json

选择使用方式

• CLI：当你需要确定性的本地分析和明确的产物时，这是最佳默认方式。
• Claude Code 插件：当你需要安装插件、打包的技能、斜杠命令和插件级 MCP 服务时，这是最佳选择。
• OpenClaw 技能：当你想在以 OpenClaw 技能为先的环境中使用相同的 Cartograph 工作流时，这是最佳选择。
• MCP Registry：当你的主机更倾向于配置工具而非运行 shell 命令时，这是最佳选择。

MCP 服务

Cartograph 的 MCP 服务可将静态仓库分析直接提供给更倾向于使用 MCP 而非 shell 命令的主机。

工具：

• analyze_repo：为本地仓库或 GitHub URL 中的文件评分、映射依赖关系，并返回精简的分析结果或嵌入的顶部文件内容
• get_file_contents：分析后获取指定文件的完整内容
• build_task_packet：返回类型化的任务包，其中包含关键文件、依赖中心、验证目标、风险和任务专属详情

如果你提供 --changed 或 changed_files，错误修复包会经过调整，以确保重点明确：它们会明确呈现变更范围，优先列出精确的验证目标，并倾向于关注共享依赖，而非外围工具脚本。

如果你想使用 Cartograph 打包的 MCP 片段，请运行：

cartograph install mcp

这会写入一个可复用的配置文件，其中包含指向以下内容的配置：

{
  "mcpServers": {
    "cartograph": {
      "command": "cartograph",
      "args": ["mcp"]
    }
  }
}

MCP Registry

Cartograph 已以服务名称 io.github.anthony-maio/cartograph 发布到官方 MCP Registry。

• 查看注册表条目

仓库侧的元数据位于：

• package.json 中的 mcpName 字段
• 用于注册表元数据的 server.json

当前发布到 npm 的安装产物为：

• @anthony-maio/cartograph

为便于重复发布到注册表，本仓库还包含一个 GitHub Actions 工作流： publish-mcp.yml。该工作流已配置为通过 GitHub Actions 使用 npm 可信发布，然后通过 GitHub OIDC 向 MCP Registry 进行身份验证并发布 server.json。

打包的 Agent 资源

当前软件包包含：

• 两个 Claude 技能：use-cartograph 和 repo-surveyor
• 五个 Claude 文档 Agent：repo-scout、dependency-tracer、context-picker、api-surface-writer 和 wiki-writer
• 两个 OpenClaw 技能：use-cartograph 和 repo-surveyor
• 两个 OpenClaw 技能中打包的 OpenProse 模板，适用于仓库文档和任务上下文工作流

技能职责：

• use-cartograph：CLI 或 MCP 服务可用时优先使用工具的方式
• repo-surveyor：Cartograph 不可用或需要验证时的手动备用方式

这两项技能都旨在生成相同的下游契约：

• 关键文件
• 依赖中心
• 最小化任务上下文
• 可直接用于文档的摘要

这些资源旨在让各步骤之间传递运行 ID 和产物路径，而不是将大量说明性文字复制到主上下文中。

本仓库中的 Claude 插件市场提供相同的技能和 Agent，此外还包含插件优先的斜杠命令和打包的 Cartograph MCP 服务。

任务包基准测试

此仓库包含一套公开的任务包基准测试，位于 benchmarks/task-packets。

可使用它，通过一组稳定的任务提示词，比较大型公开仓库中的任务包质量：

npm run benchmark:task-packets -- --list
npm run benchmark:task-packets -- --case llama-cpp-bug-fix --dry-run

基准测试运行器会将任务包产物写入 benchmarks/task-packets/output/，该目录已加入 gitignore。

精选评分卡和公开产物链接也发布在网站上：

• cartograph.making-minds.ai/examples/benchmarks.html

示例产物

已跟踪的示例位于 docs/examples：

• llama-cpp-task-packet.md
• llama-cpp-task-packet.json
• llama-cpp-deepwiki.md
• task-packet-benchmark-scorecards.md

如果你想了解针对大型公开代码库的聚焦型 Bug 修复任务包和精选仓库简介是什么样的，这些示例会很有帮助。

开发

npm install
npm test
npm run check
npm run build
npm run pack:smoke

许可证

MIT