SigMap 实战：让 AI 编码 Agent 拥有可验证的代码记忆地图

使用 Cursor、Claude Code 或 Codex 的开发者应该都遇到过这种场景：你让 Agent 修改某个模块的认证逻辑，它却跑去编辑了一个完全无关的文件，或者虚构了一个不存在的 API 签名。根因在于——AI 编码 Agent 对代码库的理解是”猜测式”的，它依赖 LLM 的语义模糊匹配，而非真实的文件结构和符号定义。

SigMap 正是为解决这个问题而生的开源工具（MIT, 585⭐）。它构建一份确定性、可审计的代码签名地图——不是向量嵌入，不是 LLM 生成的摘要，而是纯算法的 TF-IDF 索引。同样的代码库每次输出相同的地图，零依赖，完全离线，可在 CI 中 diff 验证。

一分钟上手

不需要安装任何东西，直接在项目目录下运行：

npx sigmap

这会在项目根目录生成 .context/ 文件夹，包含一份完整的代码签名索引和适配你编辑器的上下文文件。SigMap 支持所有主流 AI 编码工具的适配器格式：copilot（写 .github/copilot-instructions.md）、claude（写 CLAUDE.md）、cursor（写 .cursorrules），以及 openai、gemini、codex 等多种适配器。

sigmap --adapter claude

在 AI 编码 Agent 的会话中，这份上下文文件就像一个”代码索引目录”——告诉 Agent 哪个文件处理什么逻辑、函数的签名是什么、依赖关系如何。

核心功能：不仅仅是索引

sigmap ask：自然语言问代码

sigmap ask "认证逻辑在哪里处理的？"

返回按 TF-IDF 相似度排序的文件列表，每一行都附带实际的行号锚点。不是 LLM 猜测，是纯算法确定的排名。

sigmap verify：验证 AI 的回答

这是 SigMap 最独特的功能——验证 AI 编码 Agent 的输出是否”锚定”在真实的代码上：

sigmap verify answer.md

如果 AI 回答中引用了不存在的文件、虚构的导入、或拼错的函数名，verify 会逐行标记。这对使用 Agent 做代码审查或生成代码变更的场景特别有价值。

sigmap evidence：生成证据包

sigmap evidence "如何实现速率限制" --markdown

生成一个结构化的证据包（Evidence Pack），包含排名文件、符号锚点、Token 预算和接地摘要。Agent 不再需要”粘贴代码片段”，而是直接消费一个机器可读的上下文包。

sigmap validate + sigmap judge：验证与评分

sigmap validate --query "auth login token"
sigmap judge --response response.txt --context .context/query-context.md

validate 确认正确的文件在作用域内，judge 给 AI 回答的接地程度打分。

MCP 集成：让 Agent 动态查询

SigMap 为 Claude Code、Cursor 等 Agent 提供 MCP 服务器，启动后暴露 19 个 MCP 工具：

sigmap --mcp
sigmap mcp install claude

Agent 可以在会话过程中动态查询代码地图——search_signatures 搜索符号声明、get_lines 读取具体行号、get_diff_context 获取变更文件的签名和影响范围。还有一个独特的 squeeze_output 工具，可以在 Agent 的中途压缩冗长的堆栈跟踪或 JSON 输出，减少 Token 消耗。

Benchmark：数据说话

SigMap 在 21 个仓库、90 个编程任务上的基准测试结果：

• Hit@5：87.8%（基线 13.6%）——最相关的文件排在前 5 名
• Token 缩减：97.0%——平均每个仓库减少 97% 的上下文 Token
• 任务成功率：67.8%（基线 10%）——Agent 完成任务的成功率提升近 7 倍
• Prompt 数缩减：49.2%——每任务从 2.84 次减少到 1.44 次

这些数据完全可复现——SigMap 不使用 LLM API，每次运行的基准测试产生相同的结果。

在 Claude Code 中的工作流

sigmap mcp install claude

SigMap 还支持 sigmap create 全流程：scaffold（脚手架）→ verify-plan（验证计划）→ verify-ai-output（验证输出）→ review-pr（PR 审查）——一条命令完成从设计到验证的完整循环。

为什么不用向量嵌入？

SigMap 的签名索引就是纯文本文件，可以被版本控制、在 CI 中 diff 验证，且永远不需要”重新索引”——npx sigmap 即是全部。

总结

SigMap 不是一个”AI 搜索代码”工具——它是一个确定性接地层，让 AI 编码 Agent 不再靠猜测理解代码库。如果你正在使用 Claude Code、Cursor 或 Codex 进行日常开发，npx sigmap 值得在你的每一个项目里跑一次。

相关链接：GitHub | 文档 | npm