Agentmap Skill：让 AI 编程 Agent 不再读错文件的编译器级方案

Agentmap Skill：让 AI 编程 Agent 不再读错文件的编译器级方案

Agentmap 是一个专为 TypeScript/JavaScript 代码库设计的 AI Agent 导航工具，核心解决一个问题：你的 AI 编程助手在找到正确代码之前，已经烧掉了大量上下文 token，而且找到的还可能是错的。它通过编译器级（ts-morph）的导入/符号图谱，以一次查询替代传统 grep 的盲目搜索，实现 100% 精度的「谁依赖这个文件」「这个符号在哪里定义」等结构化问题回答。在 Next.js、zod、taxonomy 等真实仓库上的评测显示：比 grep 减少 98.3% 的上下文 token 使用量，同时精度从 59.9% 提升到 100%。

功能与原则

Agentmap 的设计原则是「精度优先，省 token 是副产品」。

核心能力包括：

• blast radius 分析（--relates）：给定一个文件，返回所有真正依赖它的文件列表。grep 会漏掉 40%，agentmap 实测 100% 精度。
• 符号查找（--find）：快速定位函数、类、变量定义所在位置，支持 top-1/top-3 结果返回。
• 代码库概览（--map）：在 token 预算内输出分级的仓库结构摘要，适合会话启动时的快速定向。
• PageRank 枢纽文件检测（--hubs）：识别仓库中的核心 Hub 文件（如 lib/utils.ts 类型的高连接度文件）。
• 智能路由（--any）：自动判断最合适的查询路径，不需要用户指定命令。

认可度

• GitHub Star：截至 2026-09-05 约 45 stars（创建于 2026-06-13，约 2.5 个月）
• Fork：11
• 最新更新：2026-08-22（持续维护中）
• 分发渠道：已在 ClaudePluginHub、ClaudeAtlas、LobeHub、SkillsMP 等多个平台上线
• Trending：在 aidev-index 的 AI coding 相关分类中标记为 live ↗，属于近期有热度的项目
• 许可证：MIT

链接

GitHub：https://github.com/raymondchins/agentmap

原作者

raymondchins（GitHub @raymondchins），自述为「Genesis 的关键观察者，频繁的逆向思考者」，目前索引有 1 个项目，专注于代码智能工具开发。

介绍

每个 AI 编程任务的第一步都是隐藏的：找到相关的代码。Agentmap 对这一步做了系统性优化。

传统方案依赖 grep 或让 Agent 暴力读取整个仓库——前者精度只有 60%（漏掉未匹配到的导入路径，或误报无关字符串），后者 token 消耗巨大。在一个 154 文件的 Next.js 真实仓库（vercel/ai-chatbot）上，7 个常见任务的 token 消耗对比如下：

原理上，agentmap 使用 ts-morph（基于真实 TypeScript 编译器）构建导入图的持久缓存（.claude/agentmap/map.json），支持增量更新——无未提交改动时直接读缓存，有改动时静默重建，始终反映当前工作区状态。输出结果经过 PageRank 排序，高相关度文件排在前面。

特点

• 编译器级精度：使用 ts-morph（真实的 TypeScript 编译器 API）解析 import/export，而非字符串正则，精度有保障
• ~98% token 节省：以 zod（367 文件）和 taxonomy（125 文件）实测，综合节省 98.3%，单任务最高节省 646 倍
• 完全本地运行：无网络请求，无遥测，数据不离开本机；.claude/agentmap/ 目录缓存（已加入 .gitignore）
• MCP 协议支持：提供 stdio 模式的 MCP Server，可接入 Claude Code、Cursor 等主流 AI 编程工具
• 无额外依赖：唯一运行时依赖是 ts-morph（~10MB，已打包），不需要向量数据库或 embedding API
• 可复现评测：benchmark 脚本在 pinned commit 上运行，EVAL.md 记录了评测方法，任何人都可以重跑验证

使用方法

安装（npx，无需安装）：

npx @raymondchins/agentmap --any "formatCurrency"

全局安装：

npm i -g @raymondchins/agentmap

Claude Code 集成：

agentmap --install-hooks   # 自动安装 post-commit 钩子 + PreToolUse grep 提示

MCP 配置（在 claude_desktop_config.json 或 Cursor MCP 配置中）：

{
  "mcpServers": {
    "agentmap": {
      "command": "npx",
      "args": ["@raymondchins/agentmap", "--mcp"]
    }
  }
}

常用命令：

agentmap --any "helper function"   # 智能路由，自动选择最佳查询路径
agentmap --find formatCurrency     # 找符号定义
agentmap --relates src/lib/auth.ts # 分析改动影响范围
agentmap --map --tokens 400        # token 受限的仓库概览
agentmap --hubs                    # 找出 PageRank 最高的枢纽文件

Agent Skill 形态（在支持 SKILL.md 的平台上）：

Use agentmap for TypeScript/JavaScript codebase navigation — symbol lookup,
blast radius, reuse checks, and repo orientation. Prefer agentmap before
serial grep when exploring imports, exports, or where a symbol lives.

使用场景与人群

适用场景：
– 在大型 TypeScript/JavaScript 仓库中工作时，需要了解代码结构和依赖关系
– 修改某个文件前，想确认「改它会影响哪些地方」，避免引入隐性 bug
– 会话开始时快速了解陌生项目结构
– 检查是否存在可复用的工具函数/组件，避免重复造轮子

目标用户：
– 使用 Claude Code、Cursor、Codex CLI、OpenCode 等 AI 编程工具的开发者
– 维护中大型 TS/JS 仓库（50 文件以上）的团队
– 对 token 成本敏感、需要高效上下文管理的 AI 工程实践者

输入与输出案例

案例 1：改动影响分析

输入：agentmap --relates src/lib/auth.ts

输出：
relates: src/lib/auth.ts (pr 0.073744)
dependents (21): src/lib/types.ts, src/lib/utils.ts,
 src/lib/db/queries.ts, components/chat/message.tsx,
 app/(chat)/api/chat/route.ts, …

（21 个文件真正依赖 auth.ts，grep 会漏掉约 8 个）

案例 2：符号定位

输入：agentmap --find ChatMessage

输出：
定义位置：src/components/chat/Message.tsx:3
被引用位置（top-5）：
  - src/lib/types.ts:15
  - src/app/chat/page.tsx:8
  - src/hooks/useChat.ts:22
精度：top-1 100%，top-3 100%（vs grep 的 32%/80%）

案例 3：token 受限的仓库概览

输入：agentmap --map --tokens 2000

输出：
agentmap: 154 files | 4 features | top hub: lib/utils.ts (deg 52, pr 0.105)
（token 消耗 1,127 vs 直接读取全库的 150,281）

GitHub: https://github.com/raymondchins/agentmap