dsh-code-atlas：代码图谱与认知层索引插件

前言¶

在 DSH 生态中，Agent 每次开启新会话，都需要先在仓库中“扫荡”才能了解项目结构。这种“不知道读哪个”的探索成本很高，且容易遗漏关键信息。dsh-code-atlas 旨在解决这个问题，它通过静态分析构建一份可核对的仓库地图。

插件简介¶

这是一个给 Agent 提供仓库地图的插件。它利用 tree-sitter WASM 符号索引、按重要度排的仓库地图，以及每文件一行 F/R/A/S 认知层，实现零原生编译的代码分析。索引存储在 <repo>/.dsh-code-atlas/index.json，为派生数据。

安装与启用¶

安装命令如下：

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

安装过程会自动引入 web-tree-sitter 和 tree-sitter-wasms 两个 WASM 依赖。安装完成后需重启 dsh。

注意： 桌面端的 desktop profile 不支持上述命令，需手动修改 package.json 中的 dsh.profile.bundles 配置并使用 pnpm 安装。

核心功能¶

插件提供 5 个工具，覆盖从索引构建到符号查询的全流程：

1. code_atlas_index：构建索引，支持 status 和 build 模式。
2. code_atlas_map：查看按重要度排序的仓库地图。
3. code_atlas_search：搜索符号。
4. code_atlas_symbols：查看导出符号。
5. code_atlas_fras：查看硬约束（F/R/A/S 中的 S）。

F/R/A/S 认知层¶

插件为每个文件生成一行摘要，包含四个维度：

• F (File / 职责)：文件负责什么。优先读取文件开头的注释（去掉标记），无注释则使用主要导出符号兜底。
• R (Relationship / 关系)：依赖与被依赖。解析仓内 import 语句；无法解析的相对导入单独列出，不抛异常。
• A (Access / 入口)：对外有哪些入口。记录导出符号，格式为 名字@行号。不同语言的“导出”判定规则不同（JS/TS 为 export_statement，Go 为首字母大写，Rust 为 pub，Python/Ruby/Bash 不以 _ 开头，C/C++ 非 static）。
• S (Safety / 硬约束)：不能弄错的地方。识别注释中的纪律词（必须/禁止/注意/IMPORTANT/NEVER）和危险模式（eval、child_process、rm -rf、shell:true、硬编码密钥、关 TLS 校验、777 权限）。

边界与限制¶

• 调用图：尚未实现，R 列目前只到文件级依赖。
• 索引策略：索引是全量重建，单文件上限为 512KB。不认识的扩展名不索引。
• S 的性质：S 列提供的是候选，不是结论。它只指出“有人写过规矩”或“出现了危险写法”，具体判断需人工复核。
• 扫描范围：点目录（如 .dsh_probe/）默认不扫描，以避免污染地图。

总结¶

dsh-code-atlas 通过零编译的方案，为 Agent 提供了结构化的代码视图。它不依赖复杂的编译过程，利用树解析器增强正则，适合需要快速定位代码逻辑和潜在风险的场景。

• GitHub 仓库
• 社区目录