前言¶
在 DSH（DeepSeek Harness）裏讓智能體讀懂一個代碼庫，常見做法是反覆掃目錄、貼片段，或依賴會把倉庫內容傳到外部的在線文檔服務。前者難沉澱成可檢索的敘事文檔，後者與「數據不出本機」的目標衝突。社區插件目錄裏也有若干「地圖 / 引用 / 圖」類方案，但要麼缺分頁正文，要麼依賴第二套工具鏈或停更。
dsh-wiki（@acfufu/dsh-wiki）面向同一類需求：在本地由 agent 讀懂倉庫，生成帶 路徑:行號 證據的分頁 wiki，並構建可離線瀏覽的單文件站點，全程不上傳、不發起網絡請求。下面介紹它是什麼、如何安裝與使用，以及使用時需要注意的邊界。
這是什麼¶
dsh-wiki 是維護者 Acfufu 發佈的 DSH 社區插件，在 SkillHub 分類爲「記憶」。當前 package 版本爲 0.1.2，許可證 MIT，兼容 DSH >=0.2.0-rc.1（README 寫明 peer 覆蓋 ^0.1.1-rc.1 || ^0.2.0-rc.1，並在 0.2.2-rc.1 實測通過）。
裝好插件後，你會得到四類入口：
| 入口 | 形式 | 作用 |
|---|---|---|
dsh-wiki 技能 |
runtime skill | 對話中說「給這個倉庫生成 wiki」等，走盤點 → 配置 → 語言判定 → 頁面樹 → 逐頁寫作 → build + selfcheck |
/wiki 命令 |
slash command | generate / view / list |
| 側欄 Wiki 面板 | 左欄全局面板 | 列出已構建 wiki，應用內嵌閱讀 |
| Wiki 按鈕 | 會話頭部槽位 | 獨立窗口打開本機索引頁 |
生成結果落在各倉庫內的 .dsh-wiki/（目錄名可通過配置修改），主要包括：
wiki.json：分頁結構與內嵌 markdown（schemarepo-wiki-local/1）pages/<id>.md：每頁導出副本，便於 diffgeneration-meta.json：生效配置與字段來源site/index.html：單文件自包含站點（目錄樹、全文搜索、深淺主題、mermaid 離線渲染等）
正文中的 `path:line` 引用會經 selfcheck 機檢：文件須存在、行號須在範圍內，否則生成失敗。站點還會做零外鏈機檢，避免外鏈腳本、字體等泄露出網。
核心功能¶
本地生成與機檢¶
智能體在本地完成倉庫理解與 wiki 寫作，不把倉庫內容上傳。構建器爲純 Python 3.7+ 標準庫實現，README 寫明無需 pip 安裝第三方依賴。
證據引用¶
與「只有引用沒有正文」或「只有圖」的方案不同，dsh-wiki 強調敘事正文與強制機檢的 路徑:行號 證據並存；越界引用會導致生成失敗，而不是 silently 壞鏈。
離線站點¶
site/index.html 爲自包含單頁：搜索、雙主題、窄屏適配、內聯 SVG 淨化等。可在 DSH 桌面宿主的本機迴環路由下瀏覽，也可通過側欄或獨立窗口打開。
發現與遷移¶
插件從會話事件記住工作目錄，持久化在 <profile home>/dsh-wiki/registry.json，並掃描已知目錄的同級目錄以發現已有 site/index.html。可選 config.wikiRoots 補充掃描根路徑。從 ZCode 存量 wiki（~/.zcode/v2/repo-wiki/<hash>）可通過 import-legacy 導入，格式與 zcode-repo-wiki 兼容。
安裝與啓用¶
前置：DSH Desktop 或 web profile（dsh-base + dsh-web-app）、python3 ≥ 3.7。
路線 A（GUI）：側欄「插件」→ 添加插件 → 填寫本倉庫路徑或 https://github.com/Acfufu/dsh-wiki → 安裝並啓用。desktop profile 爲 patchReload: live，裝完刷新頁面即可。
路線 B（CLI）：README 給出的示例如下（macOS 桌面應用內 CLI 路徑；Linux 用戶需改爲你本機 dsh 可執行文件路徑）：
CLI="/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh"
"$CLI" plugin --profile desktop add github:Acfufu/dsh-wiki
"$CLI" plugin --profile desktop list
安裝前建議自行查看 GitHub 源碼與 MIT 許可證；插件在 DSH 宿主進程權限下運行，與其它社區插件一樣，宜配合來源審查（README 提及可配合 @jieai/dsh-plugin-vet 自查）。
典型用法¶
在 DSH 會話中使用斜槓命令：
/wiki generate # 爲當前工作區生成完整 wiki（fork 子代理執行技能）
/wiki generate /path/repo # 指定倉庫路徑
/wiki view # 輸出當前倉庫站點的本機 URL
/wiki list # 列出所有已知 wiki
本機路由（桌面宿主迴環）包括：
/dsh-wiki/— wiki 索引頁/dsh-wiki/site?path=<倉庫>/.dsh-wiki— 打開某個站點/dsh-wiki/api/status— JSON 狀態
也可以在對話中直接說「給這個倉庫生成 wiki」，由 dsh-wiki 技能接管流程。
配置要點¶
插件行 config（GUI 可改）示例：
- id: dsh-wiki
config:
wikiDirName: .dsh-wiki # 各倉庫內 wiki 目錄名
wikiRoots: [] # 額外掃描的絕對路徑數組
生成側另有四層合併：內置默認 → ~/.dsh/dsh-wiki/config.json → <倉庫>/.dsh-wiki/config.json → --set k=v。預設含 compact / standard / deep / legacy，可調語言、頁數、粒度、圖表密度、引用檔位（relaxed / strict）等。具體字段以倉庫文檔爲準。
適用場景與注意¶
適合誰：希望在 DSH 工作流裏把「讀懂倉庫」固化爲可搜索、可離線打開的本地 wiki，且要求正文帶來源行證據、數據不出網的團隊或個人。
與雲端 DeepWiki 的區別（README FAQ）：雲端 DeepWiki 需把倉庫交給託管服務；dsh-wiki 使用本機會話中的模型，產物爲本地 HTML。
profile 限制：README 寫明 headless / tui 下技能與 /wiki view|list 可用；/wiki generate 與本機站點路由依賴帶 webServer 的 web 桌面宿主。
隱私邊界：不上傳倉庫與 Git 對象內容；不發起生成/圖表相關網絡請求；宿主路由僅迴環 Host、目錄名須等於 wikiDirName、只讀單文件服務。可選例外：可選用 git log --oneline -15 作摘要。
同類對照（摘自 README 對比表）：相對 dsh-openwiki 無需外掛 CLI；相對 dsh-plugin-codemap 具備分頁敘事正文；相對 archify 除圖外還有正文與自包含站點。維護狀態以各上游倉庫爲準，dsh-wiki 在 README 中標註爲活躍。
結尾¶
dsh-wiki 把「本地 agent 讀庫 → 帶證據的分頁 wiki → 單文件離線站點」收進一個 DSH bundle，分類上可歸入記憶與文檔沉澱。若要查插件摘要與分類，可打開 SkillHub 目錄頁；安裝、命令與配置細節以 GitHub 倉庫 README 爲準。
