LayerMap

LayerMap

English · 中文

LayerMap 可让编码 Agent 一次调用就知道哪些地方调用了某个函数，以及修改它会影响哪些内容，直至 HTTP 路由。 在最多 15 次请求的情况下，Agent 使用 LayerMap 能找到 97.9% 的受影响端点，而不使用时为 58.8%；在不限请求次数的情况下，Claude Code 在 0.1.5 版本的复测中成本降低了 33%（基准测试）。

解析结果由各语言的编译器或类型检查器确定，而不是由 tree-sitter 根据名称猜测： 对于 TypeScript、JavaScript、Go、Python 和 Java，通过接口、基类、模板和装饰器进行的调用都会按照编译器的解析方式关联。

_{在 Miniflux 上重放的一次真实 Claude Code 会话：一次映射调用就找到所有端点，随后 Agent 在源代码中确认了它们。}

为编码 Agent 提供代码库的分层映射。LayerMap 为 Claude Code、Codex、CodeBuddy Code、Pi、DeepSeek Harness 和其他 MCP 客户端提供只读工具，一次调用即可回答 Agent 原本需要通过数十次搜索才能弄清的问题：

• 哪些地方调用了它？修改后会影响什么？ 最多向上追踪 8 层调用方，直至它们所依赖的 HTTP 路由、处理程序、任务和命令。
• 它调用了什么？ 最多向下追踪 8 层被调用方。
• 这里有什么？ 模块、每个文件中的声明，以及某个符号的所有用法。
• 我的编辑影响了什么？ 未提交更改会影响到的路由、任务和命令，以及与它们相关的现有测试。

它使用各语言自己的编译器映射 TypeScript、JavaScript、Go、Python 和 Java，因此，通过接口、基类、模板和装饰器进行的调用都能按照编译器的解析方式确定，包括文本搜索会遗漏的调用。在微信小程序中，它还会将各页面和组件的模板（.wxml）关联到其绑定的方法和展示的组件，并将组件发出的每个事件关联到页面绑定的处理程序，让调用方追溯到页面。

示例

在 Miniflux 中，对 Storage.MarkFeedAsRead 调用一次，就能找到请求到达该函数的全部四种方式及各自的路由：

DECLARATION internal/storage/entry.go: Storage.MarkFeedAsRead m656-680 exported
  ← called by internal/api/feed.go: handler.markFeedAsRead m140-155 @149
  ← called by internal/fever/handler.go: handler.handleWriteFeeds m492-519 @508
  ← called by internal/googlereader/handler.go: handler.markAllAsReadHandler m1261-1338 @1311
  ← called by internal/ui/feed_mark_as_read.go: handler.markFeedAsRead m14-30 @24
[1] internal/api/feed.go: handler.markFeedAsRead m140-155
  ← used as value by internal/api/api.go: Serve f25-84 @61 "PUT /v1/feeds/{feedID}/mark-all-as-read"
[1] internal/googlereader/handler.go: handler.markAllAsReadHandler m1261-1338
  ← used as value by internal/googlereader/handler.go: Serve f44-64 @62 "POST /reader/api/0/mark-all-as-read"
[1] internal/ui/feed_mark_as_read.go: handler.markFeedAsRead m14-30
  ← used as value by internal/ui/ui.go: Serve f18-180 @77 "POST /feed/{feedID}/mark-all-as-read"
… (the Fever API, then on down to main.go: main)

m 和 f 分别标记方法和函数，并显示其行号；@ 表示调用所在的行，而引号中的路由是其注册时使用的路由：HTTP 方法和完整路径，其中 /v1 前缀由其子路由器添加。在 Java、Python 和 TypeScript 中，路由会显示在处理程序本身上，例如 @GetMapping("/{id}") route "GET /api/tasks/{id}"。

结果

在公开的 Go、Python 和 Java 项目中，针对影响范围问题（“更改会影响哪些 HTTP 端点？”）进行盲测，并根据各语言自己的工具链交叉核对真实结果集后评分：

	使用 LayerMap	不使用
找到的端点，最多 15 次请求（gpt-5.5，6 个任务 × 3 次运行）	97.9%	58.8%
Claude Code / Codex 未经提示主动使用（已安装插件，两轮）	12 次中 12 次 / 12 次中 12 次	—
找到的端点，不限制请求次数（Claude Code / Codex，0.1.5）	100% / 100%	99.0% / 100%
Claude Code 成本，不限制请求次数（0.1.5 重测；第一轮 −32%）	−33%
Codex 输入 token，不限制请求次数（当前默认设置）	+14%
耗时，不限制请求次数（Claude Code / Codex）	+25% / +20%
更改检查列出的失败测试（Go / Python，令函数故意失败）	100% / 94–98%	—
连带影响任务：其他功能的测试仍通过的运行次数（Codex / Claude Code，使用时 4 个任务 × 6 次运行，不使用时 × 3 次）	24 次中 23 次 / 24 次中 11 次	12 次中 3 次 / 12 次中 4 次
日常任务，无需影响分析：正确完成数 / 耗时（Claude Code 和 Codex，8 个任务 × 2 次运行）	32 次中 32 次 / +12–31%	32 次中 32 次

预算紧张时，这张映射图能找到更多受影响的代码，token 用量约增加 24%。不限制请求次数时，两种 Agent 无论是否使用映射图，都几乎能找到所有内容。使用映射图后，Claude Code 的成本降低了三分之一。Codex 当前的默认设置本就能精简搜索，因此映射图不再为它节省 token；第一轮测试中，推理力度设为 max 时，节省了 55%。使用映射图的 Agent 会探索更广，因此耗时更长。对于那些明显的更改会导致其他功能出问题的请求，更改检查帮助 Codex 将改动限制在请求的功能范围内。Claude Code 能看到自己改动了其他功能的哪些测试，但往往仍会有意保留更广泛的改动，因此没有明显差异。在小型本地任务中，映射图没有改变结果，但时间和费用约增加五分之一。这些测试样本较少，任务由 LayerMap 的作者编写。 报告介绍了测试设置、已发布的任务和局限性。

LayerMap 有何不同

其他工具只能为 Agent 提供其中一部分。LayerMap 将编译器精度与完整调用链追踪整合在一张本地映射图中：

	Tree-sitter 代码图（codegraph、GitNexus 等）	语言服务器和 IDE（Claude Code 的 LSP 工具、Serena、JetBrains）	向量嵌入搜索（Claude Context、Augment）	LayerMap
如何关联调用	根据名称、导入和框架规则进行匹配，通常附带置信度分数	由编译器自行解析	不建立关联；检索相似代码	由各语言的编译器或类型检查器解析
追踪调用方到路由和处理函数	多种工具支持，深度不一	每次请求追踪一级（JetBrains：默认 5 级）	—	一次调用最多追踪 8 级
是否保留为映射图	是，支持监视文件变化	否，由运行中的服务实时响应	代码块索引	是，每次调用时都会更新
是否在本机运行	是；某些工具会发送匿名遥测数据	是	通常使用云端向量嵌入	是，且不会发送任何数据

如果你需要以下功能，其他工具可能更合适：

• 更多语言，因为 tree-sitter 代码图支持 30 种或更多语言；
• 来自语言服务器的重命名和重构功能；
• 来自向量嵌入搜索的语义搜索；
• 使用 Sourcegraph 搜索多个代码仓库。

安装

Claude Code

/plugin marketplace add coffeecoproject/layermap
/plugin install layermap@layermap

Codex

codex plugin marketplace add coffeecoproject/layermap
codex plugin add layermap@layermap

CodeBuddy Code

codebuddy plugin marketplace add coffeecoproject/layermap
codebuddy plugin install layermap@layermap

Pi

pi install npm:layermap

DeepSeek Harness

npx layermap setup dsh

这会将 LayerMap 添加到每个 dsh 配置文件中。每个会话都会映射启动 dsh 的项目，而 npx layermap remove dsh 可撤销此操作。

在每个 Agent 中，在 Git 仓库中启动新会话，然后照常提问。LayerMap 会告知 Agent 何时地图能派上用场。即使会话在包含多个仓库的文件夹中启动，或随后切换到另一个仓库，也同样适用：每次调用地图工具时，都会映射其路径名所指向的仓库。会话首次启动某个版本的 LayerMap 时，npm 会将固定版本的 layermap 包安装到 LayerMap 的缓存中；此后即使离线，也会从缓存启动。

Claude Code 会在项目中每次运行地图工具前询问一次。选择“不要再询问”，或运行 npx layermap allow claude，即可允许插件在任何位置使用只读工具。

编辑后。 Agent 更改代码后，project_check_changes 会列出该更改影响的内容：能够到达已更改函数的路由、作业和命令，地图无法看到的内容，以及与该更改相关的现有测试。当更改的代码服务于多个区域（软件包或模块）时，它会逐一列出这些区域及其测试，并列出 diff 重写的现有测试，避免原本针对某个功能的更改悄然影响其他功能。环境变量和配置键仅按名称关联，编译器无法识别这些关联，因此当 diff 从某个文件中移除其中一项时，检查会列出仍在读取或设置旧名称的文件。同样，当更改涉及某个路由的处理程序或重命名路由时，它会列出请求该路径的代码和模板：前端的 fetch、生成的 API 客户端、重定向或链接。当更改在项目概览中的两个模块之间添加导入时，它会列出该导入，并说明这两个模块是否因此相互依赖；这种依赖方向是否符合项目的分层设计，由 Agent 判断。当更改添加的声明与项目已有代码几乎相同时，它会同时列出两者，以便 Agent 使用现有代码，而不是复制一份。当更改移除了某个声明的最后一次调用时，例如新代码替换了旧代码，它会列出该声明，以便 Agent 删除更改留下的内容。它绝不会编写或运行测试。在 Claude Code 和 CodeBuddy Code 中，插件会在 Agent 完成之前询问一次，要求对每个已编辑代码且自上次检查以来尚未检查的仓库运行此检查；无论代码是通过编辑工具还是 shell 命令修改，都会计入命令所指明的代码文件 （同一工作树中的其他会话所做的更改不计入）；Pi 扩展也会在 Agent 自己进行编辑后执行相同操作。设置 LAYERMAP_STOP_CHECK=0 即可关闭此功能。Codex 和 DeepSeek Harness 会收到运行此检查的指示。

**不使用插件：**运行 npx layermap setup claude 或 npx layermap setup codex。Setup 会执行三项操作：

• 注册服务；
• 允许只读工具在不显示提示词的情况下运行；
• 在 Agent 的指令文件中添加一句带标记的句子。

Setup 适用于单台机器；若要供整个团队使用，请让每位成员安装插件。npx layermap remove … 可撤销设置。对于其他 MCP 客户端，请在仓库中将 npx -y layermap mcp 作为 stdio 服务运行。

要求：

• Node.js 22.22 或更高版本。
• macOS 或 Linux（x64 或 arm64）；Windows（x64 或 arm64）为实验性支持。
• Git 仓库。
• 对于 Java 项目，需要 JDK 21 或更高版本。

工作原理

在某个仓库中首次调用时，会构建该仓库的映射：小型项目需要几秒钟，大型项目需要几分钟。之后的调用只会重新分析发生变化的部分，因此映射始终与工作树保持一致。

映射保存在用户缓存中（~/Library/Caches/layermap、~/.cache/layermap 或 LAYERMAP_CACHE），不会保存在仓库中。LayerMap 完全在你的计算机上运行，不会向任何地方发送数据（隐私， 安全）。

工具	用途
project_explore_map	查看目录、文件，或某个声明的调用方和被调用方（direction 为 INCOMING 或 OUTGOING，depth 最大为 8）。
project_search_map	根据声明名称、路径或文档中的词语查找声明。
project_find_references	查找当前源码中编译得到的某个声明的所有用法。
project_check_changes	检查未提交的更改（或自 base 以来的更改）会影响什么：更改和删除的声明、这些声明关联到的路由、任务和命令、共享了更改代码的区域、被删除但仍被其他文件使用的环境变量和配置键、请求受影响路由的代码和模板、模块间新增的依赖关系及由此闭合的循环、重复现有代码的新代码、需要手动检查的内容，以及相关测试。若提供 tests，还会列出这些测试文件都未调用、也未通过路由请求的已更改代码，以及其上层入口点。

命令行中也可以使用相同功能：

npx layermap explore src/api/users.ts --name createUser --direction INCOMING --depth 8
npx layermap search "invoice total"
npx layermap refs src/billing/tax.ts calculateTax
npx layermap check --base main
npx layermap check test/billing.test.ts   # also: what of the change this test does not run

常见问题

首次构建映射需要多长时间？ 在较新的 Mac 上：

• Miniflux（400 个 Go 文件）：约 3 秒。
• Polar 的服务端（1,900 个 Python 文件）：约 1 分钟。
• Conductor（1,500 个 Java 文件和 1,300 个 TypeScript 文件）：不到 2 分钟。

它无法识别什么？ 编译器无法静态解析的调用：依赖注入、未知的框架路由、反射和动态计算的名称。工具会指出追踪在哪里停止；缺少某种关系并不能证明该关系不存在。

Windows 呢？ 目前仍处于实验阶段。LayerMap 的测试可以在 Windows 上通过，但尚未在实际的 Windows 计算机上与 Claude Code 或 Codex 一起测试，因此请先在自己的项目中进行测试，并报告遇到的问题。Claude Code 插件的钩子需要 Git for Windows（它们在 Git Bash 中运行）；没有它，映射工具仍可使用，但会话开始提示和任务结束检查不会运行。

Claude Code 的打印模式（claude -p）呢？ 从 Claude Code 2.1 开始，打印模式不会启动已安装插件附带的服务，因此其中无法使用映射工具，但插件的钩子仍会运行。请自行传入服务：

claude -p "..." --mcp-config '{"mcpServers":{"layermap":{"command":"npx","args":["-y","layermap","mcp"]}}}'

如何移除它？

• Claude Code：/plugin uninstall layermap@layermap。
• Codex：codex plugin remove layermap@layermap。
• CodeBuddy Code：codebuddy plugin uninstall layermap@layermap。
• Pi：pi remove npm:layermap。
• 然后删除缓存目录。

开发

你需要 pnpm、Go 1.24 和 JDK 21+。如果缺少某种工具链，对应语言将不会被分析。

运行 pnpm install。首次安装时，pnpm 会询问允许哪些依赖运行构建脚本；只允许 esbuild，因为 SQLite 包附带预构建的二进制文件：

pnpm approve-builds esbuild '!@photostructure/sqlite'

然后运行 pnpm test、pnpm typecheck 或 pnpm lint。

pnpm package 会构建 npm 包。

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。