前言¶

在 DSH 裏跑智能體，上下文往往散在多個 Git 倉庫、AGENTS.md、.agents/、skills、工具目錄和各類知識文件裏。手工對賬「該放哪、有沒有重複、指針是否失效、憑證是否登記」成本高，且一改目錄結構就容易出現 copy drift 和孤兒知識。Guster 是 Lumos-789 維護的可分發智能體插件，定位是智能體上下文的控制面：發現資產、做策略診斷、用可審查的計劃改結構，並在需要時腳手架一個輕量 Guster Hub 作爲可選的數據面。它不替代 Hub，而是發現、校驗並幫助保持 Hub 與機器側上下文一致。

這是什麼¶

Guster 審計並演進整臺機器上的智能體上下文：項目、指令文件、skills、工具、知識、項目狀態、證據與憑證引用；也可爲尚未有數據面的用戶腳手架輕量 Hub。維護者爲 Lumos-789，在 SkillHub 目錄中分類爲工作流。CLI 爲 Python 3.9+，無第三方 Python 依賴；DSH 側通過 package.json 與 cordis.patch.yml 接入，skills 位於 skills/guster 與 skills/guster-hub。

核心功能¶

下面按 README 中已說明的能力歸納，不做超出資料的擴展。

發現與登記

• 發現 Git 根、AGENTS.md / CLAUDE.md、.agents/、skills、工具、知識、狀態、證據與憑證位置。
• guster scan 寫入 registry.json。

診斷與評分

• guster doctor 做策略檢查並寫入 findings.json：resident 預算、skill 元數據預算、copy drift、重複 canonical 源、孤兒知識、斷鏈指針、錯放任務目錄、陳舊狀態、canonical 根外的 inline token 與憑證等。
• guster score 計算指標與 CHI（Context Health Index）儀表盤；七個維度加權：SSR、RBR、PCR、ICR、FRS、PHR、SIR。紅線問題（如憑證進 git、resident 指針斷裂等）會覆蓋分數。

計劃與應用

• guster plan findings / plan move / plan init 將發現轉爲可審查的 JSON 計劃。
• guster apply <plan> 默認 dry-run；僅 --yes 時寫入，並提供備份與回滾路徑。

初始化與 Hub

• guster init 爲新項目或新機器初始化標準 .agents/ 佈局。
• guster hub init 創建 lite Hub 並掛到本地配置；hub attach、hub status、hub validate 管理已有 Hub。
• Lite Hub 目錄結構包含 AGENTS.md、hub.yaml、knowledge/、projects/、tools/ 等；hub init 對非空目標會拒絕，先寫可審查計劃再 attach 到 ~/.agents/guster/config.json。

範圍（Scopes）

• 機器：guster doctor
• Hub：guster doctor --scope hub
• 多倉庫：guster doctor --root A --root B
• 單項目：guster doctor --root <repo>

範圍運行結果寫入 ~/.agents/guster/scoped/<hash>/；不同 scope 下進入 CHI 的維度不同，README 中有明確表格說明。

憑證與導出

• 讀取 ~/.agents/credentials/registry.md，檢查未登記憑證文件與已登記但路徑缺失；guster credentials 按 company / personal 列出（不存取值）。
• guster export 導出脫敏 Markdown/JSON 報告；guster link 檢查上下文指針；guster upgrade 檢查 Codex/ZCode/包清單版本。

八個平面（Eight planes）

Truth、Instruction、Capability、Knowledge、State、Evidence、Runtime、Secret——用於理解掃描與治理邊界，Secret 平面只處理引用，不持久化或打印憑證值。

安全默認

• 默認只讀；寫操作限於 apply、init --yes、hub init --yes、hub attach。
• 不自動 git add / commit / push / deploy；計劃與備份分別位於 ~/.agents/guster/plans/ 與 ~/.agents/guster/backups/。

安裝與啓用¶

DSH 安裝方式以 README 原文爲準：從本地 checkout 添加 bundle，而不是憑倉庫名拼接遠程 add 命令。

dsh plugin add /path/to/guster

插件 hosts 中 DSH 的 manifest 爲 package.json + cordis.patch.yml，與 Codex、ZCode 的 plugin.json 一樣指向 skills/。若需把 CLI 穩定放在 PATH，可在 clone 後的目錄執行：

ln -s "$(pwd)/bin/guster" ~/.local/bin/guster

當前 package 版本爲 0.5.4，許可證 MIT（見倉庫 package.json）。

額外 skill 根目錄可通過環境變量注入（不改變發佈源碼）：

export GUSTER_EXTRA_SKILL_ROOTS="name=/path/to/skills:other=/another/path"

默認還會掃描 ~/.agents/skills、~/.codex/skills、~/.dsh/skills、~/.claude/skills。

典型用法¶

Quick start 來自官方 README，路徑需替換爲實際 checkout 與 Hub 目錄。

cd <checkout>
./bin/guster init --home --yes
./bin/guster hub init --path <hub> --yes
./bin/guster scan
./bin/guster doctor
./bin/guster score --write

創建 Hub 時可自定義三個核心根（相對 Hub、且須在 Hub 內），並寫入 hub.yaml 的 paths：

guster hub init --path <hub> --knowledge notes --projects work --tools scripts --yes

常用命令一覽：

適用場景與注意¶

適合誰

• 在一臺機器或多個倉庫上維護大量 AGENTS 指令、skills、知識與項目狀態時，需要可重複的掃描、doctor 與 CHI 評分。
• 希望用可審查的 plan + --yes 應用來改 .agents/ 或 Hub 結構，而不是直接手改一堆路徑。
• 尚未有統一知識/項目卡片存儲，想用 lite Hub 腳手架數據面並與 ~/.agents/guster/config.json 關聯。

注意

• 插件在 當前 DSH 進程權限 下運行，會讀取機器與倉庫內的路徑；安裝前應自行審查 GitHub 源碼 與 MIT 許可證，確認符合你的安全與合規要求。
• 憑證值不會被掃描結果持久化或打印；仍應保證 registry.md 與真實 secret 文件位置一致。
• SkillHub 社區目錄是獨立站點，與 DeepSeek / 幻方無官方從屬關係；DSH 生態理念是「一切皆插件」，Guster 是其中面向上下文治理的工作流插件之一。

結尾¶

Guster 把「發現 → 診斷 → 評分 → 計劃 → 可選應用」串成一條可復現流水線，並可選腳手架 Guster Hub 作爲 durable knowledge 與 project state 的數據面。目錄頁與源碼：

• SkillHub：https://www.skillhub.cn/plugins/Lumos-789/guster
• GitHub：https://github.com/Lumos-789/guster