万象-技能市场搜索与安装

何时用

• 用户要装技能：「装个 XX 技能」「有没有做 X 的」。
• 任务卡在缺外部能力上：需要某个外部服务、授权或第三方数据，现有工具够不着 → 荐连接器。
• 任务需要专业判断：单一角色的回答明显不够（尽调、合规、投研、诊断）→ 荐专家。
• 用户要看清市场结构（不是找一个技能）：「排行榜里都有什么」「哪些方向饱和了」「我该往哪做」→ §2.6 规模采样。

不适用：技能包已到手之后的进库审查、命名、位次（→ 万象-技能打包与库治理）；纯事实检索（→ 直接检索）。

§0 三条铁律

1. 只用平台工具，不自己造网络请求。 三条线各自的入口工具是唯一通道；禁止构造 HTTP、拼接 URL、处理 token/cookie/Authorization。鉴权全部由宿主完成 —— 你去处理鉴权，就等于把用户凭证放进了对话与日志。
2. 推荐一律用卡片，不用文本列表。 卡片是用户可点的授权入口；文本列表看起来像推荐，实际什么也装不了。
3. 不许猜 id，也不许猜版本。 技能 id、插件 id 只能来自本轮检索结果；版本新旧只读工具给的字段，不自己做字符串比较。

§1 三线路由（先判走哪条）

判定口诀：用户说「装/安装」→ 技能市场；说「接进来/连上/同步」→ 连接器；说「谁来帮我做/找个人」→ 专家。

第四形态 · 插件（容器）。 上面三条都是「能力」，插件是装能力的容器（可同时带技能 / hook / agent / MCP / PATH 工具 / 默认设置）。判据：

> ⚠️ 插件与技能不是一回事：技能是 SKILL.md，插件是带 .codebuddy-plugin/plugin.json 的目录。
> 用户说「装」时先判它是哪一个 —— 判错的代价是「装完了但没生效」。

> ⚠️ 同一条回复里只出一张卡。 连接器与专家共用荐装卡入口，且每条回复最多一次调用；这张卡一旦发出，其余推荐留到下一轮，不要并行发两张。

§2 技能市场：检索与安装

2.1 关键词怎么取

2.2 结果分支（判定顺序不能调）

2.3 命中后的三分支

• 未安装 → 直接安装。
• 已装且无新版 → 「已是最新版本 v\<版本\>，无需重复安装」，停下。
• 已装且有新版 → 问「已装 v\<旧\>，最新 v\<新\>，是否更新？」，同意后再装。

> ⚠️ 不要自己用字符串相等判断版本新旧 —— 工具已用语义化版本算好，读字段即可；自己比较会把 1.10.0 判成比 1.9.0 旧。

2.4 安装后的动作

• 成功 → 直接把工具返回的 message 转给用户（不要自己拼路径），可附一句「在【技能管理】面板里能看到它」。
• 不要替用户启用该技能，也不要接着调用它的工具 —— 启用是用户的动作。
• 失败 → 按错误前缀处置：

2.5 库外寻源：GitHub / 全网（2026-09-21 立）

> 来源：视频号博主「林旬的AI笔记」《Codex 必装 6 个 Skills》（2026-09-19）｜台账 §128。
> 吸纳的是他检索与筛选的维度；他点名的 6 个 skill（Skill Creator / Fine Skills / Super Powers /
> GS Tech Skills / UIUS Pro Max / 保育 Skills）未逐一验证，仅作名称登记，不得当依赖、不得当背书。

三步：① 把需求拆成关键词 → ② 按「分类 + 星数 + 更新时间」三维筛 → ③ 命中后先看分发形态再决定能拿什么。

🔴 分发形态决定能拿什么（本库硬判据，先于一切）：

边界：找到 ≠ 收编。外部寻源的产物进库，唯一通道是 omni-skill-forge 的
§B11 净室转生 ／ §B13 两道审查。本节只负责找到，不负责收编。

2.6 市场规模采样与功能台账（2026-10-07 立）

> 判据全文：references/市场规模采样与功能台账.md｜脚本：scripts/skh_rank_*.py

什么时候走这一路：用户要的不是「一个技能」，而是看清市场结构 ——
「按评分排的榜单里都有什么」「哪些方向饱和了」「我该往哪做」。这是整体观测，不是单件取用。

一条命令链（零依赖，全部标准库）：

python scripts/skh_rank_fetch.py   --pages 50 --page-size 100 --cat-counts --out <数据目录>
python scripts/skh_rank_analyze.py --raw <数据目录>
python scripts/skh_rank_ledger.py  --raw <数据目录>     # 11 功能族 + 逐条归类
python scripts/skh_rank_report.py  --raw <数据目录> --out <报告.html>

🔴 四条最贵判据（踩过才知道，勿凭直觉改）：

🔴 两条会得出相反结论的口径坑（10-07 追加）：

• score 是按响应批次归一化的，不是全局分 —— 同一技能两次查询可得 50,114 / 40,024，每页批次最大值恒为 100,000。
  ⇒ 只能用于同批内排序；跨批比较一律改用 downloads / installs / stars。
• 头部样本的中位数不能当基线 —— 该样本本身是精选集合。全站下载中位 ≈160，头部样本中位 ≈1,792，差一个数量级。两个数都要给。

收费技能判定：用 labels.pricing_type（paid＝微信支付｜alipay＝支付宝 AI 付），不是 category=pay-skill
（后者是跨类目筛选面，命中项的 category 仍是其功能类目）。

查自家技能：keyword=<品牌词> → 按 namespace.canonicalName 里的 handle 过滤；必取 created_at 做年龄说明。

可发现性检验（10-07 追加 · 本路最高价值的一步）：给每部自家技能配 3 个「用户会输入的功能词」（不用品牌词），
跑 scripts/skh_discoverability.py 实测能否检出、排第几。
🔴 必须同时测 limit=20 与 limit=50 —— 真正的失败模式常常是「刚好被截断在 20 名之外」，
只测一档会把「边缘」误判成「不存在」，结论方向就反了。三种模式处置不同：
A 黑话命名（0 命中）→ 改名；B 边缘截断（12–24 位）→ 改名＋描述抢前排＋外部导流三件一起做；C 真无供给 → 机会位。
配套产出 scripts/skh_optimize_{report,md}.py（优化参考依据 HTML／行动清单 MD）。

付费定价（10-07 追加）：价格两条通道位置不同 —— 支付宝通道在列表接口 channelPricing.price，微信通道在详情接口 pricing.pricePerCall（该字段响应不稳定，不可作统计依据）。实测中位 1.00 元/次、均值 2.79、区间 0.01–100；定价与传播量基本无关；🔴 企业认证主体做付费但几乎不公开标价（头部付费 96 条中 72 条有认证，公开标价的 445 条中认证者为 0）。详见参考档 §10。
竞品价格对标（10-07 追加）：以自家技能的二级类目为匹配键，取该子类下载量前列的收费技能做同域对标；同时给「该子类价格中位」与「收费供给量（稀缺度）」，按四象限给策略。🔴 两个统计陷阱：① 区间占比会掩盖精确价格点（真相是 1.00 元整占 38%，不是「1–2 元占 43%」）；② 分箱边界 p < 1 会把 p == 1.0 吃进「1–2 元」箱 ⇒ 必须单独给众数价。详见参考档 §10.8。

口径纪律：downloads＝曝光代理、installs＝采纳代理、stars＝认可度。
报告必须写明覆盖率与上架时长；上架过短的只能说「尚未起量」，不能判「已失败」。
改版效果以同一脚本复跑的命中率验收，不以感觉验收。

不做：拿榜单名次当质量背书推荐给用户；用 slug 去重；高频轮询；把本路当成 §2 的替代。

2.7 平台官方回评通道与全站九面（2026-10-07 立）

> 判据全文：references/平台官方反馈通道与全站结构.md｜脚本：scripts/skh_sitemap_*.py

什么时候走这一路：① 要说清自己技能在平台眼里好在哪、差在哪；② 审核被驳且理由指向安全；③ 要看榜单之外的曝光位与资产形态。

三条官方命令（一条一份）：

skillhub skill reports    <slug> --namespace <handle> --json   # 双实验室安全报告
skillhub skill evaluation <slug> --namespace <handle> --json   # 5 维 11 子项质量评测
skillhub skill rankings   --type all                           # 六个展示位一次取全

🔴 三条最贵判据

全站共九个面（此前只掌握榜单面）：榜单／展示位（6 个）／检索／详情／类目／套装（meta-skill）／人设（soul）／组织 registry／开放平台。
其中 newest 展示位是「零互动也有位」的口子（下载中位仅 16），paid 展示位当前为空。

口径纪律：平台评测分数是质量判据，不是榜单名次，不得当排名向用户推销。
domestic / scan 满分只说明「国内友好 + 安全」，不等于「内容专业」。

不做：拿评测分数当排名；用 keyword= 调 /api/v1/search 并相信结果；凭猜改包规避安全驳回。

§3 连接器推荐

只在「任务确实需要外部服务且现有工具无法完成」时触发 —— 不是每轮都推。

1. 检索时把用户原话（或轻度改写）放进意图字段；关键词只在确有用时才加。
2. 只保留能直接推进当前任务、且当前未连接的候选。
3. 最多选 3 个，id 必须逐字来自本轮检索结果。
4. 出一次卡片，多个候选放进同一次调用。

§4 专家推荐

1. 先确认当前会话未选专家：已选则立即停止，不检索、不推荐、不替换。
2. 检索后从候选里对齐当前任务，个体专家与专家团合计最多 3 个。
3. 出一次卡片；卡片类型与 id 逐字取自检索结果。
4. 检索结果若提示已选专家，立即回到原任务，不再推荐。

> 会话内只能启用一个专家或专家团 —— 这是产品约束，不是建议。

§5 推荐的取舍判据（避免噪声）

§6 本机实测坑

1. 卡片与文本列表的差别是硬差别：文本列表不会被渲染成可操作入口，等于没有推荐。
2. 重复调用荐装卡会被拦（同一回复只允许一次），并行发两张同样算两次。
3. 安装成功 ≠ 可用：技能需要用户启用后才生效；已装但未启用的技能，用起来照样报找不到。
4. 不要替用户做授权决定：任何安装/连接/授权都必须由用户从卡片发起。
5. 推荐不该变成打断：判定「本次任务是否真的缺外部能力」，缺才推；否则就是纯打扰。
6. 查平台规格的第一手来源，是本机自带的官方文档 —— 不是网搜、也不是模型记忆：<安装目录> 里已解包那一层的 cli/dist/web-ui/docs/cn/cli/（368 篇，含 plugins.md / hooks.md / skills.md / settings.md / plugin-marketplaces.md）。拿不准字段名就先来这里查。
7. 官方文档写 ~/.codebuddy/...，本机实盘是 ~/.workbuddy/... —— 照抄文档里的路径会静默找不到文件。字段名信文档，路径信实盘。
8. 🔴 /api/v1/search 的参数名是 q —— 传 keyword 被静默忽略且不报错，恒返回默认榜首 10 条；且无匹配时回落而非返回空，所以「条数」永远 ≥1，不能用来判有无命中。（CLI 源码 skills_store_cli.py:1585）
9. 🔴 /api/v1/categories 的 subCategories 恒为空 —— 二级类目只能从技能条目聚合，不是类目接口给的。
10. 🔴 详情接口是查询串式：/api/v1/skills/<slug>?namespace=<handle>；路径式 /api/v1/skills/<handle>/<slug> 返回 405 而非 404 ⇒ 405 表示「路径形态不对」，不是「不存在」。
11. 🔴 同一份安全报告两个键名：详情接口 securityReports.sanbu ＝ CLI reports.yunding（同一云鼎实验室），解析器两种都要兼容。

§7 能力边界与反例

能做：三线路由判定、关键词取法、检索结果分支处理、版本新旧判读、错误前缀处置、候选筛选与卡片出法、市场规模采样与功能台账（§2.6）、平台官方回评通道与全站九面（§2.7）。

不做：

常见误用与常见问题（FAQ）

常见误用（反模式）

常见问题

• Q：走哪条线？ A：见「§1 三线路由（先判走哪条）」—— 技能市场／连接器推荐／专家推荐。
• Q：关键词怎么取？ A：见「§2.1」；结果分支的判定顺序不能调（§2.2）。
• Q：怎么减少推荐噪声？ A：见「§5 推荐的取舍判据（避免噪声）」。
• Q：库外怎么找？ A：见「§2.5 库外寻源：GitHub／全网」。
• Q：能做市场规模采样吗？ A：能，见「§2.6 市场规模采样与功能台账」与「§2.7 平台官方回评通道与全站九面」。
• Q：本技能不覆盖什么？ A：见「§7 能力边界与反例」。

附 · 来源交代