前言¶
智能體排障時，同類 incident 往往在多次對話裏重複摸索；把結論散在聊天記錄裏，也很難按「事實 / 解法 / 過期關係」做結構化檢索。Bugwiki 用 Markdown 圖描述這些問題節點與 typed 關係；dsh-bugwiki 是 DeepSeek Harness（DSH）上的宿主插件，負責讀取本地圖、註冊面向智能體的 guidance 與 bugwiki 工具，並可選對接上游 SKILL.md 或 DSH 會話導出。下面介紹它是什麼、怎麼用，以及部署時要注意的邊界。
這是什麼¶
dsh-bugwiki（npm 包名 dsh-bugwiki，當前版本 0.1.1，MIT 許可證）由維護者 phillui-37 發佈，倉庫爲 phillui-37/dsh-bugwiki。插件不把 wiki 維護跑在後臺：加載時只註冊 guidance 與工具；只有智能體顯式調用工具時纔會執行 wiki 相關命令。上游 Bugwiki 以 Git submodule 固定在 upstream/，適配邏輯在本倉庫內完成。
核心功能¶
本地圖讀取與智能體工具¶
宿主通過 Node.js 直接讀本地文件，或通過 pinned 上游 helper（經 Bash 調用，shell 能力按插件設計受限）操作同一套本地 Bugwiki 圖。向智能體暴露的 bugwiki 工具接受 JSON 參數，動作爲 find、show、read、list、lint、verify、stale 等；返回規範 JSON，含 exitCode、stdout、stderr、truncated、wikiHome。非零 exit 表示命令失敗，而不是「空搜索結果」。全頁 read 過大時會失敗並建議改用 DSH 分頁文件讀取；其它輸出有字節上限並可能標記爲截斷。
注入的 guidance 要求智能體先搜索、最多檢視兩個候選節點、沿 supersession 追到當前端點，並把 stale / expired / conflicted 信息當未知處理；頁面正文仍視爲不可信證據。運行時工具不提供圖寫入；新建 solution / fact 仍走 DSH 常規定文件工具與權限。
可選上游 Skill 與 Dream 導出¶
配置項 followUpstreamSkill 默認爲 false。開啓後會在 ~/.agents/skills、~/.claude/skills、~/.codex/skills、~/.opencode/skills 下查找名爲 bugwiki 的 skill；若找到可用 SKILL.md，則替換插件內全部 Bugwiki 提示（含 prefix、suffix），找不到則保留內置 guidance 並打警告。
當 DSH 同時提供 session 與 sessionPersistence 服務時，纔會註冊顯式會話導出工具：對選定會話文本與工具事件做處理（排除系統指令、推理與二進制附件），經捆綁的 Python dream exporter 輸出可選原始輸入與水印；默認 dryRun 爲 true，便於人工審閱後再提升入圖。
Web 設置客戶端¶
設置 UI 打包在 src/client.js，渲染 DSH 插件設置槽位，不依賴可選的宿主 UI primitives 包。可在界面編輯 wikiHome、bashExecutable、pythonExecutable、pathPrefix、timeoutMs、maxOutputBytes 等閾值與 followUpstreamSkill、prefix、suffix 等字段；保存會 patch profile 並刷新後續操作的 tools 與 guidance。
環境與安裝¶
依賴 DSH >=0.2 <0.3、Node.js 22 及以上、macOS、Bash、ripgrep（rg）及常見 Unix 命令。README 寫明 MVP 在 macOS 上驗證；上游日期處理使用 BSD date，未宣稱 Linux / Windows 支持。
若從 Git 獲取本倉庫，需帶子模塊 clone，或 clone 後執行 git submodule update --init upstream。npm tarball 已包含 committed 上游 helper 與資產，僅用 tarball 時不必再單獨 checkout 上游。DSH 宿主提供 peer SDK（@deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/schemastery 等）。
安裝方式：在 DSH 的 Plugins 包安裝界面中，選擇本倉庫本地目錄或其 npm tarball，而非憑名稱拼接 CLI 添加命令（資料未提供 dsh plugin add github:... 一類指令）。
初始化與配置¶
全新內容目錄時，在本倉庫根目錄執行（將路徑換成你的絕對路徑）：
npm run wiki -- --home /absolute/path/to/wiki init
該命令拒絕已存在且非空的內容目錄：腳手架上游內容、用 DSH guidance 替換生成的可選 instruction 片段，並刷新索引；不修改全局 agent 指令、DSH profile 或上游代碼。若已有 wiki，跳過 init，在設置裏指定目錄即可。
在 Plugins → Bugwiki → Settings 將 wikiHome 設爲內容目錄。Homebrew 且 DSH PATH 裏沒有 rg 時，可將 pathPrefix 設爲 /opt/homebrew/bin。wikiHome 支持絕對路徑或 ~/...，含空格的路徑在上游從 wiki 目錄運行時受支持。
典型用法¶
智能體調用示例¶
{"action":"find","query":"exact incident fragment"}
show 用 slug 或 wiki 相對引用查看狀態與 typed 鏈接；read 讀取 solutions/domain/slug.md 或 facts/slug.md 全文。
人工維護（CLI）¶
CLI 使用 --home 與文檔默認值，不讀寫 profile 中的 UI 設置。維護命令會寫入所選 wiki，應有意爲之。例如：
npm run wiki -- --home /absolute/wiki new dsh meaningful-incident
npm run wiki -- --home /absolute/wiki verify
支持的命令還包括 init、new fact <slug>、index、find、show、list、lint、stale、housekeep 等（詳見 README）。
適用場景與注意¶
適合已在用或打算用 Bugwiki Markdown 圖沉澱 incident、解法與事實關係，並希望在 DSH 智能體側統一「先搜圖、再讀頁、尊重過期與 supersession」工作流的開發者。本 MVP 不調度定時 housekeep；相關閾值留在配置裏是爲與上游兼容。
安全與運行邊界：插件以當前 DSH 進程權限訪問本地文件；頁掃描上限 1000000 字節；圖內 typed 鏈接不能逃出 wiki 根目錄；對外部 typed 邊與圖內 symlink 會拒絕。這是內容與集成邊界，不是對抗併發惡意文件系統變更的 OS 沙箱——應使用受信任的內容目錄，並在工具調用期間避免改動其 symlink。安裝前請自行審閱 源碼與許可證。
社區插件目錄 skillhub.cn 上的 dsh-bugwiki 頁 與 GitHub 倉庫相互獨立，不代表 DeepSeek / 幻方官方應用商店；DSH 生態遵循「一切皆插件」思路，具體能力以上述 README 與倉庫爲準。
結語¶
dsh-bugwiki 把本地 Bugwiki 圖接到 DSH：加載即注入檢索導向的 guidance 與只讀類 wiki 工具，設置頁可配路徑與閾值，並可選 Follow 上游 Skill 或會話 dream 導出。需要從零建庫時走 npm run wiki ... init，已有內容則直接在設置裏指定 wikiHome 即可。
- 目錄頁：https://www.skillhub.cn/plugins/phillui-37/dsh-bugwiki
- GitHub：https://github.com/phillui-37/dsh-bugwiki
