⚡ SigMap — 面向 AI 编码代理的确定性代码落地层

一句话概括

SigMap 是一个开源命令行工具，能够构建你所见即所得的、可验证的代码库索引——它不依赖 LLM、嵌入技术或向量数据库，每次对同一仓库都会生成完全相同（字节级稳定）的"签名与证据图"。这能帮助 AI 编码代理（Claude、Cursor、Aider 等）快速找到正确的文件、符号和行号，并验证 AI 的答案是否真实基于代码，而不是凭空捏造。

它想解决的问题

• 传统的"代理式 grep"循环不可复现，且 AI 在不了解实际代码的情况下常常幻想出文件或函数名
• 嵌入/向量数据库的方式需要维护额外的设施（向量库、索引管线），而且结果不确定
• SigMap 用一个零依赖、离线、确定性的替代方案来解决：不用向量库，只靠文本签名 + TF-IDF 排序；不用重跑索引管线，重新生成只需一条命令 npx sigmap

它是如何工作的（流水线）

Ask → Rank → Context → Validate → Judge → Learn

1. Ask — CLI 指令，如 sigmap ask "Where is auth handled?"，返回按相关性排名的文件列表
2. Rank — TF-IDF 算法对代码库中的每个文件与查询向量打分
3. Context — 将紧凑的符号签名写入 AI 的上下文文件（如 CLAUDE.md、.cursorrules）
4. Validate — 确认哪些文件在范围内
5. Judge — 对 AI 回答的"扎根性"（groundedness）进行评分
6. Learn — sigmap weights 可让反复为你解决问题的文件获得更高权重

它号称支持 38 种语言（TypeScript、Python、Go、Rust 等），且全部零外部依赖。

旗舰功能：sigmap verify

这是它的招牌功能（也被描述为 "grounding flagship"）：

sigmap verify answer.md      # 会报告哪些是编造的
sigmap verify answer.md --json   # 机器可读报告，有问题时退出码为 1（用于 CI 门禁）

例如输出：

L12  [Fake file]    src/auth/session-store.js does not exist
L27  [Fake symbol]  authorize() — did you mean authenticate()?

它能逐行标记 AI 答案中的不真实文件、导入、导入名、符号、测试、npm 脚本——且它同时索引了仓库和当前实际安装的第三方库。

与代理的集成

• 支持生成不同的适配器上下文：copilot(默认)、claude、cursor、windsurf、openai、gemini、codex 等
• 提供 MCP 服务器（22 个按需工具），让 Claude Code / Cursor 在会话中实时调用：search_signatures、get_lines、verify_suggestion、get_diff_context、query_knowledge_map 等
• Evidence Pack：确定性 JSON 制品（也能输出 Markdown），替代"把这段粘到 prompt 里"的手动操作，CI 或代理可直接读取
• IDE 扩展：VS Code、JetBrains、Neovim

与"为什么不用嵌入"对比

	Embeddings	SigMap
需要向量库	✅	❌
需要基础设施	✅	❌
结果确定	❌	✅
离线可用	❌	✅

基准（README 声称的数据）

文档中给出的指标（均声称来自 benchmarks/latest.json，非手写）：

• 命中@5（hit@5）80.4%（检索语料库，18 个仓库）
• 单次 grep 基线对比：92.8% vs 40% —— 2.32× 提升
• 生成的 map 比全仓库平均小 95.7%
• 任务成功率代理指标 61.9%（基于检索等级模型化）
• 每个任务提示数从 2.84 降至 1.58（减少 44.4% 的重试，模型化）

作者也诚实说明：并非所有 38 种语言都做到同样的深度——分为 AST 完整解析层、锚定正则层、以及无锚定的逐行列表层（后者的格式在 KNOWN_LIMITATIONS.md 中有说明）。

注：以上描述均仅基于该 README 自述内容，未经独立验证。

涉及领域与评价

这是面向 LLM/agent 编程工作流的确定性代码索引与验证工具——属于 LLM 应用层的实用基建，核心不在训练/推理，而在"让 AI 在生产代码上可信任"。它的价值主张（无嵌入、无向量库、确定性、离线、零依赖）real 且具有差异性，README 对基准方法和局限的诚实态度也加分。作为单职业开发者维护零依赖项目，其工程完成度（CLI、MCP、IDE 扩展、benchmark 套件）相当完善。