前言¶
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。
核心功能¶
命令只有三条主链路，配套命令若干。关键设计是：该不该启用、要不要向用户提问，由命令的输出决定，而不是交给模型自由裁量。
| 命令 | 作用 |
|---|---|
ensure |
入口闸门：已启用返回 [OK]，先查表；用户已拒绝返回 [MUTED]，静默；未声明则打印欢迎说明加 [NEXT]，由 agent 问一次 |
lookup "<关键词或整句问法>" |
分层打分（标题、关键词、能回答什么、路径，相等满分、包含半分），同分按权威级别排序，返回权威文件路径 |
add <文件> --keywords ... --answers "..." |
回灌：任何「靠翻找才找到」的权威文件，一条命令登记并同步索引 |
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 个来自登记表的真实高频词做对照，两条路径都包含「读目标文件」的成本，差值纯粹是「找到该读哪个文件」：
| 指标 | 蛮力导航 | 项目地图 | 差距 |
|---|---|---|---|
| 单查询导航成本 | 9,901 ~ 140,949 chars | 276 ~ 719 chars | 最高约 376 倍 |
10 查询累计（中性高频词，bench_lookup.py 可复现） |
624,262 chars（约 37.5 万 tokens） | 4,173 chars（约 2,500 tokens） | 降低 99.3% |
| 10 查询累计（早期业务词，同口径另一组） | 110,758 chars（约 6.6 万 tokens） | 3,617 chars（约 2,200 tokens） | 降低 96.7% |
端到端在约 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
