代码图谱索引 qlheric/dsh-code-atlas

dsh-code-atlas

给智能体一张能核对的仓库地图。

tree-sitter 符号索引（走 WASM，不用装编译器）+ 按重要度排的仓库地图 + 每文件一行 F/R/A/S。

起因：智能体每开个新会话，都得先到处翻文件才知道这仓长什么样。翻的代价不在「读」，在「不知道读哪个」。

装

dsh plugin --profile <你的 profile> add github:qlheric/dsh-code-atlas

两个 WASM 依赖（web-tree-sitter、tree-sitter-wasms）会跟着装上。装完重启 dsh。

桌面端的 desktop profile 同样不认这条命令，那边改 package.json 的 dsh.profile.bundles + pnpm。

跑出来什么样

拿本机一个真实工作区跑的：

252 个文件 · 2723 个符号 · 0.82 秒 （tree-sitter 252 个文件，正则兜底 0 个）

_research/dsh-cron-upstream/lib/logger.js :: F:Unified logging wrapper for dsh-cron (#204) | 被依赖 15 | 导出 2 | 关键符号 setLogger@7 logger@17
_research/dsh-cron-upstream/lib/channels.js :: F:Delivery channels and router (#26, #20, …) | 被依赖 9 | 导出 16 | 关键符号 CHANNEL_IDS@14 resolveChannels@31 …

五个工具：code_atlas_index（status / build）、code_atlas_map、code_atlas_search、code_atlas_symbols、code_atlas_fras。

索引写在 <repo>/.dsh-code-atlas/index.json，纯派生数据，删了会重建。

F/R/A/S 是什么

| | 含义 | 从哪来的（都能核） |
| F | 这文件负责啥 | 文件开头的注释（去掉标记），带行号；没注释就用主要导出兜底 |
| R | 谁依赖我 / 我依赖谁 | 仓内解析出的 import；解析不了的相对导入单独列出来，不抛异常 |
| A | 对外有哪些入口 | 导出符号 名字@行号，「导出」的定义按语言定（下表） |
| S | 不能弄错的地方 | 注释里的纪律词（必须/禁止/注意/IMPORTANT/NEVER）和危险模式（eval、child_process、rm -rf、shell:true、硬编码密钥、关 TLS 校验、777），每条带行号 |

S 只给候选，不是结论。它只负责指出「这里有人写过规矩」或「这里出现了危险写法」，判断交给你。这样它不会编，也不会装懂。

几处刻意的地方

解析器是增强，不是单点。 拿不到语法文件（版本变了、扩展名不在表里）就退回正则层，索引照常出，每条符号标了 source: tree-sitter|regex。解析器出问题不该毁掉整次索引。

「导出」按语言各按各的规矩，写死在 isExported() 里：

| 语言 | 怎么看 |
| JS/TS | 祖先里有 export_statement |
| Go | 首字母大写 |
| Rust | pub / visibility_modifier |
| Python / Ruby / Bash | 不以 _ 开头就算公开 |
| C / C++ | 不是 static 就算 |

点目录默认不扫。 这条是踩出来的：第一版把 .dsh_probe/ 下克隆来参考的几个仓库也扫进去了，1094 个文件、9.46 秒；加了这条线之后 252 个文件、0.82 秒。不设这道线，别人的仓库就会污染你的地图。

只读。 除了那个派生缓存，不写任何东西；不跟符号链接（junction 带不出工作区）。

开发

pnpm install # 就两个 WASM 依赖
node --test # 19 个用例

干净 profile 里启动应该看到 [dsh-code-atlas] 已注册 5 个工具：…，stderr 干净。

边界

调用图还没做（R 列只到文件级依赖）。索引现在是全量重建，单文件上限 512KB，不认识的扩展名不索引（不瞎猜语法）。S 是启发式的，要精确判定就按它给的行号去读原文。

许可

MIT