WorkBuddy 技能管家

> 一句话：技能 / 专家 / 连接器 是同一种东西——一段在需要时被加载进上下文的专业能力。
> 管家干四件事：该关的关、该用的想起来、该装的提醒你、该造的帮你造（并验证做没做对）。

🚀 30 秒上手

> 💡 你不用把下面全读懂。记住这张表就够了：想关就喊「关掉没用的」、想用就描述需求、想要没有的就喊「帮我造一个」。下面的档位、脚本、边界，用到时再翻。

一、三类资产：同一个模型，不同的可执行动作

> 必须对用户说清这张表。用户常以为"专家也能像技能一样关掉"——不能，专家的模型是"同一时刻只启用一个"，
> 所以对专家只能说"你上次召唤过 X，它在某些场景比通用能力更对口"，不能说"帮你关掉专家"。不许假装有这个能力。

二、数据源地图（先看清楚在数什么）

计数口径（必须向用户交代）：统计的是显式调用；转录会被应用清理，故"历史总次数"是下限，
近 30 天窗口才是主要依据。

三、功能一 · 清库（关闭基本不用的）

流程 AUDIT → RECONCILE → SEGMENT → ACT

Step 1｜AUDIT 扫描

python <skill_dir>/scripts/scan_usage.py --days 30 --out <工作目录>/butler_usage.json

Step 2｜RECONCILE 对齐

1. skill_management(action="list") 取权威可关闭清单（只有这个集合里的能关）。
2. 剔除插件/内置技能（source 为 plugin / builtin / connector）。
3. 标注 user-invocable-only 的技能 —— 这类计数天然偏低，必须进豁免。

Step 3｜SEGMENT 分层 + 四类豁免

判定逻辑已落成脚本，直接跑，不要凭印象判：

python <skill_dir>/scripts/segment.py --usage <工作目录>/butler_usage.json --out <工作目录>/audit_segment.json

它输出四组：keep / watch / exempted（含每条的理由）/ closable，并打印分档汇总。
--keep-threshold 可调保留门槛（默认 3）。

> E4 的松紧是这份清单可信度的关键。实测：把"被提一嘴就算被编排"放宽，豁免会从 23 涨到 99，
> 关闭清单从 91 缩到 41——豁免太松，审计就等于没做。所以 E4 只认编排语境，不认提及。

Step 4｜ACT 执行

• 先出报告，不动手。报告含：统计口径、三档分布、豁免名单及理由、候选清单、"本次未关闭任何技能"的声明。
• 等用户确认（可整批，可逐条挑）。
• 确认后调用 skill_management(action="disable", skill_names=[...]) —— 用 name 不用 display_name。
• 报告结果 + 恢复方式（技能设置里的开关）。

> 三条硬立场：① 低频 ≠ 无用；② 只关闭，绝不删除文件；③ 只用官方通道，不手改 settings.json。

四、功能二 · 唤起（描述需求 → 建议已装资产）

为什么这一条不能只靠脚本

实测：需求「我爸妈又被保健品讲座骗了」→ 关键词匹配命中不到 elder-fraud-guard
（它的触发词是"父母可能被骗 / 老人被诈骗 / 防骗"）。语义匹配是模型的活，不是词表的活。

所以按这个顺序做：

① 先读速查表（主路径）

<skill_dir>/data/digest.md   —— 全量，一行一条：`- ○ 名称 — 一句话功能`

这份文件存在的理由有两个：(a) 上下文里的技能列表会被截断（当前只展示 201/222 条，有技能模型根本看不见）；
(b) 一行一条 ≈ 34KB，扫一遍的成本远低于"漏掉一个正对口的技能"。条目多时分节读（按 category）。
若 digest.md 不存在或过期，先跑 build_inventory.py 生成。

② 脚本加速（可选）

python <skill_dir>/scripts/wake_match.py "用户的需求原话" --top 3

命中触发词时很快，用于确认而不是替代判断。

③ 输出格式（严格遵守）

💡 可唤醒 · [技能] elder-fraud-guard（life）⏳久未使用
   功能：儿女阻止父母被骗的防诈骗守护技能
   唤醒：可直接继续（模型会自动加载）

• 必须说明"怎么唤醒"：状态是 auto → "可直接继续"；manual → "需点名：说「用 XXX」"（这是最容易被忽略的一步）。
• 最多 3 条。没有对口的就直说没有，不要硬凑。
• 优先提示"⏳久未使用"的 —— 这正是"装了却忘了"的解法。

④ 清单重建（内容变了才需要）

python <skill_dir>/scripts/build_inventory.py --usage <工作目录>/butler_usage.json

五、功能三 · 补货（SkillHub 有、你没装）

① 官方通道（首选，不用管网络）

search_and_install_skills(action="search", keywords=["播客 转录", "语音转文字"])

返回的是尚未安装的候选。把候选列给用户（必须带 display_name），
用户点头后再 search_and_install_skills(action="install", skill_names=[...])。
不得未经确认就安装。

② 需要下载量/评分等市场数据时

python <skill_dir>/scripts/hub_gap.py --need "把英文播客转录成中文" --terms "播客,转录"
python <skill_dir>/scripts/hub_gap.py --trending --top 20

• 结果写进 data/hub_gap.json，再跑一次 build_inventory.py，缺口会出现在《资产清单》的「市场缺口」区。
• 若命令通道连不上外网（表现为 [warn] 检索失败 … timed out）：让 Agent 用自身网页抓取能力
  取回 https://api.skillhub.cn/api/v1/search?q=<词>&limit=20 的 JSON 存成文件，改用
  --from-json <文件>。不要因此谎称"SkillHub 上没有"。

③ 输出格式

🛒 市场缺口 · 你的需求「把英文播客转录并翻译成中文」
   已装能做的：chenlin-youtube-transcript（转录）、chenlin-podcast-transcript-publish（转录+翻译）
   更合适但没装的：播客音频生成（下载 231）、播客压缩知识库（下载 177）…
   要装哪个？（说编号即可）

先看已装能不能做——能做的就不要再推荐装新的。这条比"多推荐几个"重要。

六、功能四 · 调度（Dispatch）—— 你只管需求+验收，中间我负责

> 这是 v2.0 的核心增量，也是你提出的核心诉求：让技能更有效流动，让用户把注意力放在"把需求描述清楚、把验收定清楚"，中间环节由管家负责。

触发

用户说"帮我做 X""这个需求怎么落地""从 github 做个技能""调研 github 看有没有现成方案"，
或描述一个具体目标并给出验收标准。进入调度。

为什么需要它（呼应你的核心诉求）

技能是普通人最好的资产，但资产再多，痛点不在"有没有"，而在三层断层 + 一层"做完做没对"：

1. 装了想不起（功能二解决）
2. 有更合适的没装（功能三解决）
3. 连市场都没有，但 GitHub 上有现成方案（功能四新增：造货）
4. 做完 ≠ 做对（功能四的 VERIFY 验收循环解决）

调度层把这四层串成一条链：用户只在两端出力——把需求说清、把验收标准给清；
中间的 路由 / 推荐 / 创建 / 验证 全交给管家。

两种节奏：极速模式 / 标准模式

为了避免"确认弹窗刷屏"，调度分两档——

• 极速模式（默认，低风险）：当需求能由已装的 auto 技能直接满足，或只是要"调研 / 推荐"时，管家把「路由结论 + 执行意图」合并成一次确认，你点一下就跑，不再逐步追问。
• 标准模式（仅高风险）：一旦涉及关闭技能 / 发布到 SkillHub / 连接外部账号 / 删除文件这类不可逆动作，自动切回逐步确认——每一步先问你，确认才动。

> 一句话：可逆的动作能快就快，不可逆的动作该慢就慢。你永远可以在任意一步喊停。

流程 DISPATCH → ROUTE → RECOMMEND → PROVISION → VERIFY

Step 1｜DISPATCH 接收「需求 + 验收」

• 先让用户把两件事讲清：
• (a) 想达成什么（需求，尽量具体）
• (b) 怎么算"做好了"（验收标准：可观测的指标 / 文件 / 结果，例如"生成一份 Markdown 报告并存到 X 路径""退出码为 0 且包含 N 条记录"）
• 验收标准缺失时，主动追问 1–3 个关键判据，不替用户拍板"什么叫完成"。
• 把需求 + 验收标准记到 <工作目录>/dispatch_<ts>.json，后续步骤都引用它。

Step 2｜ROUTE 路由已装资产（优先，零成本）

• 先走功能二的速查表（data/digest.md，缺失则 build_inventory.py 生成），语义判断最对口的 1–3 个已装技能。
• 命中且状态 auto → 直接通过 Skill 工具唤起该技能，把用户需求 + 验收标准一并交给它。
• 命中但 manual（仅手动点名）→ 显式点名"用 XXX"；若该技能本应常用，建议用户把它改回自动可调用
  （参考 v1.0 已落地的做法：把 user-invocable-only 从 settings.json 的 skillOverrides 移除即可恢复默认自动）。
• 借鉴 技能路由枢纽(skill-router-xiaoz) 的分桶 + 历史降权思路：高频被路由命中的技能优先；
  连续失败（VERIFY 不达标）的技能降权。可在 data/route_history.json 记录（可选，不强制）。

Step 3｜RECOMMEND 推荐未装（已装不够时）

• 已装无对口 → 调 find-skills（clawhub_root）或 hub_gap.py 在 SkillHub 搜对口技能。
• 只推荐未安装的；已装能做的绝不再推新的（功能三铁律）。
• 给出 display_name + 下载量 + 一句话功能 + 安装入口；用户点头才装，不自作主张。
• 这一步直接兑现你的需求②：让普通人知道"有没装过但能帮上忙的技能"。

Step 4｜PROVISION 造货（市场也没有时）

走八阶段管道（Scout→Filter→Reader→Extractor→Scorer→Generator→Reviewer→Publisher），
核心是"调研 GitHub → 缺则创建 → 发布 SkillHub"：

1. Scout（调研 GitHub）：用 gh search repos 或 WebSearch 在 GitHub 找该需求的现成实现
   （关键词 + 同义改写，中英都试）。可借 scripts/provision.py 跑 Scout→Filter→Scorer 的半自动判定。
2. Filter：筛掉过期（>2 年未更新）/ 无人维护 / 许可证不兼容的；保留 2–3 个候选。
3. Scorer（判断值得做成 Skill 吗）：
   - 若 GitHub 有成熟方案 → 推荐安装 / 改造为本地 Skill（用 skillcreator 脚手架，注明出处与许可）；
   - 若 GitHub 也没有合适方案 → 触发新建 Skill：用 skillcreator 生成 SKILL.md 骨架，
   把需求 + 验收标准写进 when_to_use / description。
   - 置信度 > 0.85 视为"可直接复用"；否则进入新建。
4. Generator ≠ Reviewer（防自动化垃圾）：生成由 skillcreator 完成；
   审查必须独立（换一次对话 / 换人），防止"自己审自己"产出 slop。
5. Publisher（发布需签收）：用户签收后，用 skillhub-publish-helper 发布到 SkillHub
   （先 dry-run 再发）。发布是显式动作，需确认——只提交，不自动合并进用户主环境。

这一步兑现你的需求①：先调研 GitHub，再看 SkillHub 有没有类似，没有就创建一个发布。

Step 5｜VERIFY 验收循环

• 用 Step 1 的验收标准真实验证产出（跑命令看退出码、看产物文件、对照指标），而非"应该没问题"。
• 不达标 → 回到 Step 2 换技能 / 回到 Step 4 修正 Skill / 或交回用户升级（卡住超过 N 次）。
• 达标 → 向用户交付，并可选把本次"需求 → 技能 → 验收"沉淀为新技能 / 规则
  （呼应"自我增殖能力库"：做完一次就固化，下次直接复用）。

Scope Gate（不可绕过的边界）

• 关闭技能、发布到 SkillHub、连接外部账号、删除文件 = 不可逆 / 有副作用，必须显式确认后才执行；
  确认靠工具 / 策略强制，不靠提示里写"请小心"。
• 生成与审查分离：造货时 Generator ≠ Reviewer。

与现有技能的关系（采用而非重建）

七、脚本与交付物

生成物（技能自身数据落在 <skill_dir>/data/，审计/调度结论落在工作目录）：

八、异常与边界

❌ 不用于

• 删除技能/专家/连接器的文件
• 直接编写某个具体技能的内容正文（用 skillcreator 等；管家只做"编排调用"，不写技能正文）
• 跨外部 Agent（Claude Code / Cursor / Codex）的技能目录同步

九、常见问题（FAQ）

Q1：你会不会误关我重要的技能？
不会。四类豁免（应急 / 新装 / 配置受限 / 被编排）会挡住"低频但有价值"的技能；且关闭前一定先出清单等你确认，绝不自动动手。

Q2：你会不会偷偷给我装技能 / 发到 SkillHub？
不会。推荐 ≠ 安装，发布 ≠ 自动合并。任何安装、发布都需你明确点头；连接外部账号更是显式确认。

Q3：我随口说个需求，你能接住吗？
能。直接描述"我想把家里老照片按年份整理""帮我写周报"这种大白话即可，管家做语义匹配，不需要你记得技能叫什么。

Q4：网络不好 / GitHub 连不上怎么办？
本地功能（清库 / 唤起 / 清单）完全不联网；联网功能（SkillHub 缺口、GitHub 调研）失败时都会降级——换官方工具或 WebSearch 手动取数，不会编造"市场没有"的结论。

Q5：调度一定要多轮确认吗？
不一定。低风险需求走极速模式一次确认就跑；只有关闭 / 发布 / 连账号这类不可逆动作才逐步确认。

十、脚本报错自查表

配套参考

• references/data-sources.md —— 本机数据源与权威接口地图（含实测过的 API 端点与请求头）
• references/assets-model.md —— 三类资产统一模型 + 可执行动作矩阵
• references/methodology.md —— 审计方法论、分档阈值依据、豁免词表
• references/landscape.md —— 同类项目与市场竞品对比（含 SkillHub 已有的路由/推荐类技能）

版本变更历史

• v2.1.0（2026-10-07）：针对 TRACE 评测（综合 4.6）做针对性迭代——① 新增「极速模式 / 标准模式」双节奏，降低调度确认繁琐度；② 放宽调度触发词，明确"大白话也行"，补随口描述需求的例子（修 A·触发方式 4.5）；③ 新增「常见问题 FAQ」与「脚本报错自查表」（修 C·反模式与FAQ 4.5、R·异常处理 4.3）；④ 加固 provision.py/hub_gap.py 容错：捕获未预期异常并降级写错误 JSON、改进网络报错中文提示（修 R·运行稳定性 4.0）；⑤ 顶部加「你不用全读懂」引导，降低新手理解门槛。
• v2.0.0（2026-10-07）：新增功能四·调度（Dispatch）——用户给「需求+验收标准」，管家负责中间：
  路由已装 → 推荐未装(SkillHub) → 调研 GitHub 造货并发布 → 按验收标准验证的闭环。
  落实用户两条核心诉求：① 先调研 GitHub、再看 SkillHub、没有就创建发布；② 推荐未安装但有助的技能。
  明确"采用而非重建"立场：自动调用借鉴 技能路由枢纽、发现安装复用 find-skills、
  创建复用 skillcreator、发布复用 skillhub-publish-helper，管家只新建编排中间层。
  新增 scripts/provision.py（造货流水线 Scout→Filter→Scorer）。allowed-tools 增补 Skill/WebSearch/WebFetch。
• v1.0.0（2026-10-07）：首版。合并并取代 skill-usage-auditor（技能使用审计器）与 skill-waker（技能唤醒器），
  范围从"技能"扩展到"技能 + 专家 + 连接器"。
  实测基础：1221 份本地会话转录、1402 次真实技能调用、261 个技能 + 5 个专家 + 4 个连接器。
  功能二的设计转向：语义匹配由模型扫 digest.md 完成，关键词脚本只做加速。