前言¶

DSH 的理念是「一切皆插件」，插件的作用是把某類具體能力接進 agent 的工作流，而不是替 agent 重寫推理。gov-hub（songzhou666/gov-hub）就是這類插件的典型：它解決的問題是 agent 每開一個新會話都要重新付一遍的「發現成本」——列目錄、全文搜索、讀一堆無關文件，最後才找到那一份權威文檔，token 燒在導航上，還經常讀錯文件。

已有做法是靠 glob / grep 在目錄裏蠻力翻找。gov-hub 的做法是把「某個結論、規範、報告在哪個文件」預先記錄進工作區裏的 registry.yaml，之後 agent 用一條 lookup 命令直達權威文件。它做的是文件級導航（該讀哪份文檔），不做代碼符號索引，查函數和類仍要用宿主自帶的 grep。

本文介紹這個插件的定位、命令、安裝方式和使用邊界。

這是什麼¶

gov-hub 是一個工作流類 DSH 插件，同時也可作爲通用 Agent Skill 單獨使用，維護者爲 songzhou666（README 中的署名爲 songzhou）。核心是一個只依賴 PyYAML 的 Python CLI（govhub.py），加上工作區裏的三份普通文件：

• registry.yaml，人可讀的登記表：路徑、關鍵詞、「這條能回答什麼」、權威級別；
• gov-hub.yaml，範圍聲明：agent 只在聲明的目錄內活動，越界不靜默擴界；
• .govhub/index.json，可隨時重建的檢索索引，是生成物，永遠不作爲權威引用。

狀態爲 0.3.0，許可證 MIT，Python 要求 ≥ 3.9。插件以 dsh.bundle 形式聲明在 package.json 中，當前目錄頁顯示星標爲 0。

核心功能¶

命令只有三條主鏈路，配套命令若干。關鍵設計是：該不該啓用、要不要向用戶提問，由命令的輸出決定，而不是交給模型自由裁量。

lookup 的打分邏輯是：標題匹配、關鍵詞匹配、條目聲明的「能回答什麼」匹配、路徑匹配，四層各自打分，相等得滿分、包含得半分。

配套命令包括：

• init，範圍確認加登記表骨架；
• check，登記表與磁盤一致性機檢；
• status，四段健康燈體檢；
• suggest，從查詢軌跡裏提煉該補的條目；
• attach / detach，在 AGENTS.md 裏寫或刪自己的標記塊，塊外內容不動；
• install / uninstall，安裝與卸載。

四段健康燈分別對應供給（登記表一致性）、執行、產出、回灌四端，各自綁定機檢。loose 檔默認零假設、只讀治理，mapped 檔聲明容器映射後才啓用後三段掃描。

安裝與啓用¶

倉庫提供了一鍵安裝腳本，不依賴插件市場：

# 1. 獲取源碼
git clone https://github.com/songzhou666/gov-hub.git
cd gov-hub
pip install pyyaml                          # 唯一第三方依賴

# 2. 一鍵安裝：技能文件進發現根 + AGENTS.md 入口塊 + 自檢
python govhub.py install                    # 用戶級（推薦），所有會話生效
python govhub.py install --scope project    # 或僅當前項目（.dsh/skills/）

# 3. 卸載：完全可逆，工作區裏的地圖數據不會被刪
python govhub.py uninstall

在非 DSH 宿主（如 Claude Code）上，用 --skill-dir 顯式指定技能目錄，入口塊用 attach --file 寫入該宿主的入口文件：

python govhub.py install   --skill-dir <宿主技能目錄>        # 如 Claude Code：~/.claude/skills
python govhub.py attach    --root <工作區> --file <工作區>/CLAUDE.md

安裝完成後即全自動。在任何會話裏問「登錄的測試結論在哪個文件？」，agent 會先 ensure 判斷該不該用地圖，再 lookup 命中權威文件，作答後順手把新讀到的文件 add 回地圖。不需要用戶記命令。

無網絡、無虛擬環境要求，唯一依賴是 PyYAML，沒有降級路徑。倉庫自帶兩個虛構示例工作區（loose / mapped 檔），可以直接跑通驗證：

python govhub.py check  --root seeds/sample-workspace   # 結果：通過 ✅（6 條）
python govhub.py lookup 賬期 --root seeds/sample-workspace
# [  7.0] rule.billing-cycle · canonical · rules/03_賬期對賬規則.md

典型用法¶

先初始化，登記表中的候選目錄需要人工確認後才固化：

python govhub.py init --root <工作區>

# 登記一條資產（自動機檢 + 同步索引）
python govhub.py add docs/登錄測試報告.md --root <工作區> \
  --keywords 登錄,驗證碼,測試結論 --answers "登錄驗證碼的測試結論與證據"

# 檢索
python govhub.py lookup "登錄 驗證碼 結論" --root <工作區>

# 機檢 / 體檢 / 補條目提案
python govhub.py check   --root <工作區>
python govhub.py status  --root <工作區>
python govhub.py suggest --root <工作區>

# 把入口塊寫進 AGENTS.md（冪等；detach 只移除標記塊，塊外不動）
python govhub.py attach --root <工作區> --scope project
python govhub.py detach --root <工作區> --scope project

登記紀律：同一主題下有多份獨立文件（如各子端各一份清單）時每份一條，不要合併成總表。地圖裏不記錄數量或統計值，數量現數即可，寫進地圖必然過期。

查找失敗時的處理流程：如實說「地圖上沒有」，用普通方式查找，找到權威文件後立刻 add，下次就命中；suggest 會把高頻未命中詞提成待辦。

效果數據與出處¶

以下數據來自倉庫自帶的 bench/bench_lookup.py、bench/RESULTS.md 與 docs/PERFORMANCE.md，口徑先看說明再看數字。

微基準在真實項目資產區（36 個 Markdown 文件、167 條登記表）上，用 10 個來自登記表的真實高頻詞做對照，兩條路徑都包含「讀目標文件」的成本，差值純粹是「找到該讀哪個文件」：

端到端在約 5.7 萬個文件的真實工作區上，同一句「登錄驗證碼那裏發現了什麼問題？」：無地圖時 141s+、40 次調用未答完；回灌 3 條後第二問 40s、5 次調用答完（快 3.5 倍、調用減少 8 倍）。命中組穩定在 23~75s / 4~10 次調用，蠻力組 93~230s / 15~40 次調用，最懸殊一對 tokens 差約 6.8 倍。

口徑與邊界：

• 微基準未計蠻力路徑的試錯重試、誤讀返工與上下文污染，數字偏保守；
• token 按 chars × 0.6 粗估，只看量級；
• 端到端樣本量小（每組 2~4 輪）、單工作區、單日，問題不完全相同，量級可比、非精確比值。

還有一條容易踩坑的實測結論：裝了不等於立刻省錢。空表首日仍會走蠻力（實測 43 次調用），收益在回灌 2~3 輪、覆蓋高頻問題後才兌現，所以 add 纔是這套東西的核心循環。

適用場景與注意¶

適用：有長期積累的文檔、規範、報告、測試證據，且 agent 需要反覆回答「某結論在哪、什麼時候做過什麼」的工作區。

不適用：寫業務功能代碼、檢索代碼符號（用宿主自帶 grep 更快）、問「上次我們聊了什麼」（地圖不含對話內容）、工作區裏沒有任何權威文檔。

讓位條款：若項目已有自己的查詢協議（如 AGENTS.md 裏定義了 lookup 工具、自有 _registry.yaml），以項目協議爲準，本技能整體忽略、不邀請初始化。

隱私與硬邊界：

• 純本地，所有命令不發起網絡請求、不上傳任何數據、不收集統計；
• 只新增，除顯式執行的 install / attach / init / add 外不寫任何工作區文件；
• 完全可逆，detach 只移除自己的標記塊，uninstall 撤銷安裝；
• 地圖只索引路徑與關鍵詞，不復制文件內容，.govhub/ 刪掉即消失；
• 換電腦地圖還在，地圖數據都在工作區裏跟着倉庫走，技能重新 install 即可。

另外提一句：插件在運行時以當前 DSH 進程權限執行命令，init、add、attach 都會寫入工作區文件，安裝前建議先檢查源碼與許可證（MIT）。

結尾¶

gov-hub 的價值在於把「哪個文件是權威」這份知識從模型的臨時推斷搬進工作區裏的普通文本文件，讓 agent 每次會話不再重新翻一遍目錄。它的效果數據來自倉庫自帶的實驗腳本，能不能兌現取決於有沒有持續回灌——空表不會自動省錢，add 纔是循環的關鍵。

目錄頁：https://www.skillhub.cn/plugins/songzhou666/gov-hub
GitHub：https://github.com/songzhou666/gov-hub