前言¶
在 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 個工具，覆蓋從索引構建到符號查詢的全流程：
code_atlas_index：構建索引，支持status和build模式。code_atlas_map：查看按重要度排序的倉庫地圖。code_atlas_search：搜索符號。code_atlas_symbols：查看導出符號。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 提供了結構化的代碼視圖。它不依賴複雜的編譯過程，利用樹解析器增強正則，適合需要快速定位代碼邏輯和潛在風險的場景。
