Harmonist代码地图原理零依赖 repomap 如何用 ast sqlite3 替代 grep 扫描完整指南【免费下载链接】harmonistPortable AI agent orchestration with mechanical protocol enforcement. 186 agents, zero runtime dependencies.项目地址: https://gitcode.com/gh_mirrors/ha/harmonist️Harmonist 代码地图repomap是一个零依赖的本地代码索引工具它只用 Python 标准库的ast、re和sqlite3三个模块就把整个项目的函数、类和文件间依赖关系预建好让 AI 编程助手直接查地图而不是反复用 grep 盲扫文件。无需 tree-sitter、无需 Node、无需任何原生编译。一、为什么 AI 编程助手不能靠 grep 反复扫描如果你用过 Cursor、Claude Code 这类 AI 编码助手多半见过这个场景每次新开会话助手都要先摸索一遍陌生代码库——grep 关键字、glob 找文件、Read 读内容再 grep……Harmonist 的 README.md 把这个痛点说得很直白agent 在陌生代码库上消耗的大部分预算都花在了重新发现代码上grep、glob、Read、repeat。而查结构而不是扫文件正是代码地图要解决的问题。传统上实现这种代码智能需要重型依赖tree-sitter 解析器、Node 运行时、数据库服务……而 Harmonist 的立身之本是零运行时依赖186 个 agent、纯 Markdown 标准库 Python bash。于是它给出了自己的解法agents/scripts/repomap.py——一个 850 行的单文件代码地图把结构问答变成毫秒级的本地查询。二、repomap 的三件套纯标准库构建的代码地图打开 repomap.py你会发现它的导入区干净得惊人——全部是 Python 标准库astresqlite3—— 没有 tree-sitter、没有 Node、没有原生构建macOS / Linux / Windows 全平台通吃。astPython 代码的精确解析对 Python 文件repomap 不做任何正则猜测而是直接调用 CPython 自带的语法分析器见 _extract_python函数 / 类定义从 AST 节点里精确提取名称、起止行号并用ast.unparse还原出完整函数签名如def calc_fee(amount)import 语句同时记录模块名和相对导入的层级level为后续解析文件到底引了哪个文件打下基础。正则做不到这一点它分不清import x是标准库还是本地模块也还原不了函数签名。ast 把 Python 这一语言做到了解析级精度。re其余 17 种语言的轻量提取对 JavaScript、TypeScript、Go、Rust、Java、Ruby、PHP、C/C、Swift、Kotlin、Scala、Dart、Lua 等语言repomap 采用按行的正则模式符号定义模式表提取函数、类、接口、trait、模块等符号并按语言配置了对应的 import 解析模式。这是典型的尽力而为best-effort策略——和所有基于名称的索引器一样够用且极快但精度不如 Python 的 ast 路径。sqlite3本地索引零服务、零网络所有提取结果写进一个本地 SQLite 数据库默认放在项目/.cursor/repomap/graph.db已被 gitignore。数据库表结构只有 4 张表表存什么files每个源文件的路径、语言、sha256 内容哈希、大小、符号数symbols符号名、类型、所在文件、行号、签名edges文件间的 import 依赖边谁引了谁meta构建时间等元信息关键在索引symbols(name)、symbols(lower(name))、symbols(file)和edges(src)、edges(dst)上各建了 B-tree 索引——这正是查询能做到毫秒级的原因。三、一次建图增量刷新build / refresh / status 用法python3 .cursor/repomap/repomap.py build # 全量索引符号 import 依赖图 python3 .cursor/repomap/repomap.py refresh # 增量刷新只重建内容哈希变化的文件 python3 .cursor/repomap/repomap.py status # 检查索引是否过期pending 文件数增量逻辑build 函数很讲究每个文件比对sha256 哈希没变的直接跳过刷新零成本文件被删除时连带清掉它的符号和依赖边有一个容易忽略的细节只要文件集合本身变了新增/删除文件未变化的文件也会重新解析依赖边——因为新模块可能成为某个 import 的新解析目标跳过它们会留下过期边。四、五类结构查询从 search 到 affected建好图之后repomap 提供一组结构问答命令这是它替代 grep 的核心search / explore秒级定位符号search 符号名精确或模糊匹配返回文件 行号 签名explore 关键词...把一句话或一堆词切分、打分精确匹配 3 分、模糊 1 分返回按文件分组的相关符号。这就是给 repo-scout 准备的一次调用回答侦察问题的答案——拿到分组结果后只需 Read 地图指出的那几个文件。deps / dependents依赖双向图deps 文件这个文件下游引了谁dependents 文件这个文件上游被谁引用。impact / affected传递闭包算出爆炸半径最强大的两个命令impact 文件...沿依赖边反向做 BFSimpact 实现找出传递地引用了这些文件的所有文件——即改动它们的完整影响面affected 文件...在 impact 结果上再按 测试文件识别模式 过滤回答这次改动可能弄坏哪些测试文件——于是回归测试只跑真正相关的部分。五、repomap 对比 grep原理级差异维度grep 扫描repomapast sqlite3工作方式每次查询都全文重扫一次性预索引查询走 B-tree结果粒度文本行含注释、字符串误报结构化符号名称/类型/行号/签名依赖关系需要多次 grep 人工推理一条 SQLedges表的图查询影响面分析基本做不到传递闭包impact一个命令给出依赖项—纯 Python 标准库无第三方包增量成本无缓存概念sha256 哈希比对未变文件零开销一句话概括grep 回答这个词在哪repomap 回答这个结构是什么、谁依赖谁、动了它会发生什么。六、融入 Harmonist 的机械强制门这才是它的真正价值代码地图本身只是工具Harmonist 把它接进了强制执行链路形成闭环repo-scout 先查图再读文件repo-scout.md 明确规定Query the Repo Map FIRST (dont grep blindly)——侦察阶段先explore/search/dependents只对地图指出的文件做 Readbg-regression-runner 只跑受影响的测试bg-regression-runner.md 用git diff --name-only HEAD | repomap.py affected --stdin直接得到该跑的测试清单stop 门强制校验在.cursor/hooks/config.json里打开require_affected_tests: true后改动文件的爆炸半径内的测试没跑完回合不允许结束sessionStart 过期提醒会话开始时自动检测地图是否过期repomap_staleness_warn避免拿旧地图做判断。建图环节也被自动化了integrate.py 集成项目时会自动执行build步骤step_9_repomap开箱即用无需手动维护。七、如何在你自己的项目里用起来 三步即可需要 Python 3.9建图python3 .cursor/repomap/repomap.py build集成 Harmonist 时已自动完成查询explore 订单结算或search calc_fee拿文件与行号保鲜日常用refresh增量刷新status查看是否有待更新文件。行为正确性由 test_repomap.sh 守护——用fee ← billing ← checkout的 Python 导入链 JS 相对导入链两个微型夹具项目覆盖 build / search / explore / deps / dependents / impact / affected / 增量刷新共 7 组断言。八、总结repomap 的设计哲学和 Harmonist 一脉相承用最少的依赖把约定变成机制。ast让 Python 解析精确到签名级正则覆盖其余 17 种语言sqlite3把全文扫描变成带索引的毫秒查询哈希增量刷新让索引常新接入 stop 门后该跑的测试不再是 prompt 里的客气话而是一道绕不过去的检查点。对新手来说它的意义也在于此你不需要懂图数据库或 LSP一条命令就能让 AI 助手从grep 循环切换到查地图——这正是零依赖框架能带来的、干净利落的代码智能。【免费下载链接】harmonistPortable AI agent orchestration with mechanical protocol enforcement. 186 agents, zero runtime dependencies.项目地址: https://gitcode.com/gh_mirrors/ha/harmonist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考