前言¶

在 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