前言¶

在 DSH 裏接倉庫、問 agent「這塊需求現在怎麼實現的」，常見結果是等研發翻代碼，或 agent 根據片段猜一個「大概是這樣」。產品經理要的是能點、能轉發、且每句話都能對回索引的材料，而不是另一份口頭說明。

dsh-repotruth（npm 包名 dsh-plugin-repotruth，當前版本 v0.3.0）由 SilasSolivagus 維護，歸類爲 工作流 插件。它只讀本機構建好的內容尋址索引，產出兩類 HTML：系統現狀（這個倉裏有什麼）與 需求走查（這件事落到哪些節點、哪裏要問研發）。結論遵守「讀不到 / 沒找到 / 待確認」不混寫一條的紀律。

這是什麼¶

插件定位：把代碼倉庫變成能被代碼覈實的話。主產物之一是三欄需求走查頁——左爲流程節點，中爲頁面結構或時序骨架，右爲索引能證明的標註與「待研發確認」槽位。材料是單文件 HTML，可內嵌面板、新窗口打開或直接發到羣裏，離線也能看；地址可加 #node=<節點id> 直達某個節點。

它不跑語義理解、不改遠端代碼、不執行倉庫腳本；檢索當前以詞面匹配和固定中英詞表爲主，查不到會明確說查不到，不生成空的三欄頁。

兩份產物：別混着讀¶

共同點：都只讀本機索引；都寫「沒找到 ≠ 不存在」。

核心能力¶

接入、索引與覆蓋率¶

一條鏈路大致分五步（面板與後臺協作）：

1. 接入倉庫：克隆爲 bare 鏡像到 mirrors/<倉名>.git，之後只 fetch。
2. 建索引：按內容尋址寫入 index/<倉名>.json；同一內容塊只解析一次（README 實測：98 文件倉首輪約 4.5 秒，同 HEAD 第二輪約 100 ms、0 解析）。
3. 說需求：在 DSH 聊天框用中文描述需求，由 agent 調用 repotruth_material。
4. 看材料：生成 materials/<id>.html，默認用系統瀏覽器打開。
5. 配置與盤點：面板管理代碼源、倉庫與覆蓋率；產出 coverage.json。

克隆與建索引在獨立子進程中執行，帶硬超時；宿主不等子進程，界面仍可用。

索引跳過 vendor/、third_party/、testdata/、測試文件及生成代碼等，並在覆蓋率表裏分列「已索引」與「跳過生成」。頁面統計口徑統一走 lib/scan.js，demo 與索引不會給出兩個頁面數。

走查頁的欄位規則¶

• 左欄：命中文件按頁面與目錄區域歸併爲節點。
• 中欄（有頁面）：模塊結構卡；讀不到則寫原因，不畫假截圖。
• 中欄（無頁面）：時序骨架（參與者限於固定詞表），並標明「不是從代碼裏讀出來的流程」。
• 右欄：規模、波及面、以及明確的「待研發確認（未證實）」。
• 沒命中：面板與命令行均只返回「沒能在已索引的代碼裏找到與「X」相關的地方」，不生成空頁。

作爲 DSH 插件的界面能力¶

• 登記 GitHub / GitLab / 通用代碼源，測試只讀連接並列可見倉庫數。
• 接入、同步（clone --mirror 後 git fetch --prune）、移除（刪本機鏡像與索引）。
• 需求只從 DSH 聊天框進入，插件側不再單獨提供需求輸入框。
• 界面文案爲中文；健康檢查示例：GET http://127.0.0.1:60425/api/repo-truth/health（桌面掛上後期望 200）。

命令行（與面板同實現）¶

適合腳本、CI 或羣消息：

npx dsh-plugin-repotruth material vue-admin-template --question "用戶登錄頁面是怎麼做的？" --out ./examples

生成系統現狀且本次不帶頁腳署名（meta 仍保留）：

npx dsh-plugin-repotruth demo <倉地址> --no-attribution

配置與署名¶

config.json 頂層示例：

{ "version": 1, "attribution": false, "hosts": [] }

attribution: false 可關頁腳「由 repotruth 生成 · … · v0.3.0」；<meta name="generator"> 不可關，便於從 HTML 辨認生成版本。

安裝與啓用¶

運行環境：node >= 22，peer 依賴 @deepseek-ai/cordis ~4.0.5，許可證 MIT。

桌面版 desktop profile 由 Electron 獨佔，不能用 CLI dsh plugin 直接裝，需在倉庫根目錄執行 README 中的 link 步驟：備份 ~/.dsh/profiles/desktop 的 package.json 與 cordis.patch.yml，寫入 dsh-plugin-repotruth 的 link: 依賴並加入 bundles，再 ln -sfn 到 node_modules。dsh-hmr 熱重組，一般無需重啓應用。卸載按 README 恢復備份並刪除符號鏈接即可。

若不想動桌面 app，可自建 profile（README「方式二」）；截斷處之後的具體命令以 GitHub README 爲準。

典型用法¶

界面走查：在聊天框寫一句需求，例如「分享頁要支持未登錄下載但只有會員能下」，點「生成走查材料」→ 讀索引按名歸節點 → 瀏覽器打開三欄頁，點左側節點切換中間結構與右側標註。

盤點現狀：接入倉庫並完成索引後，在覆蓋率頁查看「接進來 / 看得見 / 看不見」及跳過原因分項；用 demo 或面板查看單倉長文現狀。

問一句（現狀檢索）：例如「用戶登錄頁面是怎麼做的？」——返回相關頁面名、引用波及、最近改動與顯式限界；檢索爲詞面 + 中文二元組 + 約 50 條中英詞表，偏產品常用詞（登錄、訂單等），生僻說法可能找不到。

適用場景與注意¶

適合：產品/項目在評審前要把「現在怎麼走」落成可轉發材料；接手新倉先做覆蓋率與頁面規模賬；研發與產品要對齊「哪裏是索引證明、哪裏必須問研發」。

邊界（README 明確）：只有只讀 git 操作；不 push、不在用戶工作區跑 git clean；不做 AST、不讀路由聲明、不做跨倉索引複用；誰能打開 DSH 界面誰就能看到配置（令牌掩碼）；配置與索引僅本機，無多用戶同步。

安全與合規：插件以當前 DSH 進程權限訪問令牌、克隆與讀倉；安裝前請自行審閱 源碼與許可證。企業內部分發可走 attribution: false 去掉頁腳外鏈。

結尾¶

dsh-repotruth 把「接倉 → 內容尋址索引 → 現狀 / 走查 HTML」收成一條工作流，並把「沒讀到、沒找到、待確認」拆開寫死，減少評審會上用空頁或猜測冒充現狀的情況。

• 社區目錄頁：skillhub.cn/plugins/SilasSolivagus/dsh-repotruth
• 源碼與完整安裝說明：github.com/SilasSolivagus/dsh-repotruth