skill-inventory · 办公型 Agent 通用的技能库盘点与效能体检

English docs：SKILL.en.md（本文件中文版）· README.en.md。报告与文档语言均可由用户选择，见下方「语言设置」。 中英双版内容对等：英文版字符数不少于中文版（v1.4.0 实测 SKILL 14,460 vs 10,722、README 14,505 vs 7,261）， 章节数与 FAQ 条目一一对应。 维护者文档（发布清单 / 触发词归档）保留在 GitHub 仓库的 references/，不随平台分发包分发。

办公型 Agent（WorkBuddy、千问办公、百度搭子、天禧AI 等，均经 generic 模式支持；天禧等沙箱默认无关闭通道）装得多不等于能力强。 技能清单（name + description）每一轮对话都进模型上下文——装 54 个技能约等于每轮白烧 5,000+ tokens。

1. 适用场景

触发短语示例（匹配 description 自动挂载或显式调用）：

• 「盘点我装了哪些技能」「技能库太多了帮我看看哪些能关」
• 「哪些技能可以关闭/合并」「技能占了多少上下文」「帮我瘦身一下技能库」
• 「关闭 XX 前先看影响」（--impact）
• 「自测一下你的解析器」（--selftest）
• 「帮我找找技能装在哪」（--probe）
• 「把报告语言换成英文/中文」「语言设置改成 auto」
• 「百度的技能目录在哪」「通用平台怎么扫技能」（--agent baidu / --agent generic --root <dir>）

不触发：写周报、发邮件、代码生成等与技能库治理无关的任务——本技能只做技能库的 盘点、体检与关闭前评估。

2. 语言设置（auto / zh / en）

• 查看：--show-lang 打印当前设置、三个选项及说明、切换方式。
• 保存：--set-lang auto|zh|en 写入偏好文件 ~/.workbuddy/skill-inventory.json（仅此一处， 仅在你显式运行该命令时写入），切换后立即对后续运行生效；--set-lang auto 或删除该文件即恢复默认。
• 单次覆盖：--lang zh|en 只影响本次运行，不改动已保存设置。
• 优先级：--lang（本次）＞ 已保存设置（zh/en）＞ auto 回落链。
• auto 不是锁定：它是「用户尚未表达偏好时的回落」，不是强制——随时可用 --set-lang 固定为 zh/en，或用 --lang 单次覆盖；不选语言的用户看到中文报告纯属默认，不是被强制。
• 恒定不变：四档分类标识恒为英文（used / protected / closeable / manual-review）， --json 输出恒为英文键——程序化消费不受语言设置影响。
• 零参数路径：多数环境无需手写任何路径——直接跑 python scripts/skill_inventory.py 即自动 探测已知平台；陌生宿主用 --probe 让工具自己找技能目录，仅在 --probe 也找不到时才退回 --root <目录> 手填。

3. 输入材料

权限边界（与脚本头部的机器可读声明一致）：

• 读取：技能目录、用量日志、自动化/Hook/路由/插件配置
• 写入（两处目标 + 一份备份工件，均需显式授权）：
  1. ~/.workbuddy/settings.json 的 skillOverrides 键——仅当你显式传 --apply --yes（写前自动备份）；
  2. ~/.workbuddy/skill-inventory.json 的语言偏好——仅当你显式传 --set-lang；
  3. 备份工件——执行 --apply --yes 时，在 settings.json 旁生成 settings.json.bak.<时间戳> 安全副本（惰性副本、路径打印给你、不会被回读）。
• 网络：无　子进程：无

纯本地静态分析，零网络依赖、零子进程（沙箱红线天然合规）。

4. 输出结果

1. 盘点报告（默认）：技能总数 / 市场与自建占比 / 清单 token 占用估算 / 逐技能表格，四档分类：
   • used 有使用记录：确实用过（可信）。
   • closeable 可关闭候选：无使用记录 且 超过 30 天没改过。仍须人工逐条确认。
   • manual-review 需人工确认：无使用记录但近期改过，或本平台无遥测——别急着关。
   • protected 受保护：不会自动建议关闭（本工具自身 / protected: true / 安全审计类 / 被引用锁定 / 用户追加）。
2. 影响预览：每个被引用锁定的技能，列出「关闭将断掉 N 处引用」——[来源类型] 完整路径 + 命中的技能名；单技能深查 --impact <名称>。
3. 重复/跨区提示：真·多份激活、激活+禁用副本、同名技能。
4. 机器可读 JSON（--json）：四档清单、结构化 referenced_by、telemetry_scope（t1-only/none），英文键。

5. 执行步骤

规范写法：python scripts/skill_inventory.py [flags]。常用 flags 组合：

流程：auto 探测平台 → 失败回落 generic 通用档。通用档优先用 --probe 自动找技能目录（找不到再退回 --root <目录> 手填）；无用量日志自动降级为「不判任何技能可关闭」；--refs 可补充反向依赖扫描根。

6. 实际输出长什么样

跑一次 python scripts/skill_inventory.py 后，终端会按以下结构打印（节选，WorkBuddy 档、中文）：

ℹ  遥测口径：用量日志只覆盖「显式调用」（T1）。自动挂载 / 定时任务 / Hook / 专家内部
   调用（T2–T6）不计入——「有使用记录」≠「只被显式用过」，「无使用记录」也不等于
   「没在用」（反向依赖扫描只兜住可发现的配置根）。

平台                          WorkBuddy
技能总数                        59    （市场安装 29 / 自建或自改 30）
有使用记录                       27
受保护（不关）                     6
可关闭候选                       19    （仍须人工逐条确认）
需人工确认                        7
                            19665 字符  ≈ 6912 tokens / 每轮对话

目录                                      行      KB      来源        最后改    用        最后用
----------------------------------------------------------------------------------------
agnes-ai                            ⚠   537    23.9      自建 2026-10-09   0          —
ai-weekly                               168  2734.0      自建 2026-10-09  1 2026-10-05
skill-publish-gate                      211   324.7      自建 2026-10-09  2 2026-10-09
skill-inventory                     🔒    91    52.1      自建 2026-09-28   0          —
office-token-booster                    375   653.2      自建 2026-09-25  4 2026-08-21
skill-creator                           356   52.6      市场 2026-06-30  17 2026-08-27

🔻 可关闭候选：无使用记录 且 超过 30 天没改过（19 个）
   ⚠ 仅建议，未经你显式确认不得关闭；先确认无关键词/专家触发依赖。
  bug-fixing                                667 行   2026-08-04
  log-analyzer                              501 行   2026-08-04
  code-fix                                  262 行   2026-08-04

🔒 受保护（不关）：6 个
  skill-inventory                     （本工具自身，永不进候选）
  skill-clean-audit                   （安全/审计类启发式命中）
  security-audit                      （名称含 security）
  ⋯

各图例含义：⚠ = 近期改过但无使用记录（进「需人工确认」）；🔒 = 受保护（永不进候选）； — = 无使用记录；行/KB = 该技能目录的 SKILL.md 行数与体积。

机器可读（--json）：加 --json 时输出一个 JSON 对象，顶层键恒为英文（不受语言设置影响）：

{
  "agent": "workbuddy",
  "can_close": true,
  "rows": [
    { "name": "office-token-booster", "lines": 375, "kb": 653.2,
      "from_market": false, "last_modified": "2026-09-25", "last_used": "2026-08-21",
      "uses": 4, "protected": false, "locked": false, "referenced_by": [] }
  ],
  "buckets": { "protected": [ "skill-inventory" ], "keep": [ "⋯" ],
               "cleanup": [ "bug-fixing" ], "review": [ "⋯" ] },
  "telemetry_gap": false,
  "telemetry_scope": "t1-only",
  "cannot_close": false
}

buckets 四档：protected（受保护，不关）/ keep（有使用记录，保留）/ cleanup（可关闭候选，仍须人工确认）/ review（需人工确认）。telemetry_gap=true 时表示 无遥测、报告不含可关闭项。

自测（--selftest）：校验内置回退解析器与 PyYAML 的块标量语义是否一致，离线可跑：

[selftest] frontmatter block-scalar semantics 块标量语义
  用例 8 通过 / 0 失败（对照源：PyYAML）
  [OK] SKILL.md 回退解析：version=1.5.1、description 1390 字符

7. 数据源优先级

1. 平台用量日志（最高置信）：只覆盖「显式调用」（T1）；自动挂载 / 定时任务 / Hook / 专家内部调用（T2–T6）在日志里不可见——报告会常显这一口径。
2. 反向依赖扫描（兜底盲区）：扫描自动化 / Hook / 路由状态 / 插件清单等配置里的技能引用，凡被引用即锁定为受保护。
3. 最后修改时间（最低置信）：仅当无遥测时作参考，不可单独作为关闭依据。
4. 用户确认（最终裁决）：任何「可关闭候选」动刀前必须经用户逐条确认。

8. 用户确认点

行为契约全文见 README.md §🔒 行为契约（8 条，先读再信任）。此处只列关闭前必须确认的 三点（SKILL 侧技术要点，不与 README 重复）：

• 本工具不会自行关闭任何技能。 关闭写路径需你显式授权——在可关平台上 --overrides --apply --yes 会先自动备份 settings.json 再合并进 skillOverrides；缺 --yes 仅 dry-run； 不可关平台直接拒绝 --apply。
• 优先引导宿主自带开关（/skills 菜单、客户端启用开关）；通用档无关闭通道，只给候选清单。
• 可关闭候选动刀前先看影响预览（--impact <名称>），确认无关键词触发器 / 专家组件 / 自动化依赖（referenced_by 为空）。

9. 风险边界

完整行为契约（默认只读、两处受控写 + 一份备份工件、无自动驻留、受保护永不进候选、遥测缺口 不判死、反向依赖扫描）见 README.md §🔒 行为契约。此处只列技术边界（SKILL 侧，不与 README 重复全文）：

• 写路径（均需显式授权并在输出中标注）：① --overrides --apply --yes 写 ~/.workbuddy/settings.json 的 skillOverrides（先备份）；② --set-lang 写语言偏好文件 ~/.workbuddy/skill-inventory.json（单键）；③ --apply --yes 生成 settings.json.bak.<时间戳> 惰性备份副本（路径打印、不回读、可手动删除）。
• 读边界：技能目录、用量日志、自动化/Hook/路由/插件配置；网络无、子进程无。
• 遥测口径：用量日志只覆盖 T1 显式调用；T2–T6（自动挂载/定时任务/Hook/专家内部）无痕， 靠反向依赖扫描 + 用户确认双层兜底。
• 重复检测是近似比对（名称/描述/体积），非语义级去重；仅覆盖可发现配置根。

10. 应避免的错误用法

以下 6 类是真实使用中最常踩的坑，本工具设计上不鼓励这些做法：

设计取向：宁可少报，不可误杀。 工具永远不会替你决定「可以关闭」——它只输出候选与影响， 每一笔写操作都需要你显式授权并打印备份路径。

11. 常见问题（FAQ）

Q1：为什么我的技能被标成「需人工确认」，而不是「可关闭候选」？ 只有「无使用记录」且「超过 30 天没改过」的技能才会进可关闭候选。出现「需人工确认」有四种原因： ① 无遥测（用量日志缺失或读不了）——本工具宁可少报也不误杀；② 最近 30 天内被改过；③ 所属平台没有 程序化关闭通道（如千问、通用档）；④ 命中受保护规则。用 --usage-log <路径> 补上日志、把确认过的 技能用 --protect 追加保护，能把噪声压下去。

Q2：「有使用记录」就等于「只被显式用过」吗？ 不等于。用量日志只记录显式调用（T1）。自动挂载（T2）、关键词路由（T3）、定时任务（T4）、 钩子（T5）、专家/连接器内部调用（T6）在日志里完全无痕。所以「有记录」不代表只被显式用过， 「无记录」也不等于没用——后者才是需要人工确认的原因。

Q3：报告说「遥测缺口」，我该怎么补？ 这表示用量日志读不到，报告只能基于「最后修改时间」，不会给出可关闭项。两种补法：① 该平台有日志 时用 --usage-log <路径> 指定（如 ~/.qwenworkcn/skill-usage.json）；② 没有日志就靠反向依赖扫描 （--refs 指定自动化 / Hook / 配置根）+ 人工确认兜底，此时工具会一直保持保守输出。

Q4：会不会误关被自动任务或关键词触发器调用的技能？ 护栏有三层：① 反向依赖扫描发现被自动化 / Hook / 路由 / 插件引用即锁定进受保护桶；② 安全审计类关键词 与本工具自身永不进候选；③ 任何候选都要你逐条确认。但护栏不能穷尽——T2 自动挂载与描述性关键词 引用扫不到，所以关闭前请先看影响预览：--impact <名称>。

Q5：关闭到底写入了什么？能不能撤销？ 只写一处：~/.workbuddy/settings.json 的 skillOverrides 键（把候选标成 off）。落笔前自动生成 settings.json.bak.<时间戳> 备份副本，路径打印在输出里，可用 os.replace 原子替换，不会留下半截配置。 撤销有三条路：把备份文件改回去、在宿主 /skills 菜单改回、或直接删掉 skillOverrides 里对应条目。

Q6：为什么千问 / 百度 / 通用档不给我「关闭」动作？ 不同宿主的关闭能力不同：can_close=False 的平台没有「关闭单个技能」的程序化通道，本工具按能力感知 分叉——只给盘点与候选清单，把动刀留给宿主开关或手动移除，避免给出你根本执行不了的建议。

Q7：报告里的「疑似重复」准吗？ 是近似比对（名称 / 描述 / 体积），不是语义级去重：会把同名的市场版与自建版标成疑似重复，也会漏掉 描述完全不同但功能重叠的。拿它当线索，别当结论。

Q8：报错里的 [E-LOG] / [E-CONF] 是什么意思？ 稳定的错误码，便于检索与反馈：

Q9：报告没列出「可关闭候选」，是我的技能没问题吗？ 不一定——很可能没有遥测（Q1/Q3）。工具的设计取向是「宁可少报，不可误杀」：看不到使用记录时它不会 替你做关闭决定，但会明确告诉你缺口在哪。

附：平台档位一览

原则：能力感知——平台能不能「程序化关闭」决定工具产出什么。不可关平台不产出关闭动作， 只做体检与候选清单，把「动刀」留给宿主与用户。

零参数路径：通用档优先 --probe 让工具自己找技能目录，多数环境无需手写路径； 仅在探测失败时才退回 --root <目录> 手填。