技能推荐官 · 每周 AI 技能精选（Skill 规范 v3.0.0）

> v3.0 是一次修复版升级：v2.4 的门禁存在「假绿」，且文档承诺的 G5 流程有一半脚本不在包里。
> 本版把判据收成单点（rules.py）、把数量与分类交给用户偏好、把去重变成硬闸门，
> 并让 SKILL.md 里出现的每一个命令都真实存在且实测可跑。

触发条件

用户说「技能推荐官」「每周 AI 技能精选」「本周 AI 技能」或要求生成/更新该周报时触发。
「定时运行」「每周自动推荐」时见文末的自动化配置。

用户偏好（先读这一节）

偏好全部落在 preferences.json，用自然语言说一句就行，也可以手改。

数量规则：total 必须等于 days × per_day，且落在 schema.json 给的合法区间内
（days 1–7、per_day 1–10、total 3–40）。不再固定 21。

偏好是否生效：respect_preferences.enabled
- true -> G6 闸门强制：入选技能的分类必须在启用清单内
- false -> 按全量抓取，G6 跳过分类校验

preferences.categories[].weight 决定检索阶段的配额（不是硬性配额），
python dedupe.py --plan 会按 weight 用最大余额法算出本周每类应找几个，合计恰好等于 total。

硬性闸门（HARD GATES）—— 优先级高于一切

> 以下 7 条是发布红线。违反即视为发布事故，不论产物是否已生成。
>
> ### 强制机制（双保险，判据同源）
> 1. generate.py 生成前校验：调 rules.validate_week()，违反抛 RuleError 中断，不出 MD/HTML。
> 2. test_validate.py 发布前门禁：每次更新数据必跑，1 项失败 = 禁止发布。
>
> [!] 两条路径调用的是同一个 rules.py。v2.4 的致命缺陷是两处各写一份判据，
> 一处宽一处严，实测出现「generate 产出 -> test 事后才判违规」的分裂。禁止再各写一份。

G1｜热度字段 = 可溯源的数字/榜单指标（结构化强制）

校验：rules.validate_popularity() · test_g1_popularity_all()

每个技能必须显式声明：

禁止：
- [X] 审稿/未决语境：改为…、待确认、待复核、或保留、技术报告口径、不引用 —— 移入 editor_note
- [X] 纯文字描述：新晋热门、持续迭代、办公效率新锐、Agent 总榜第一
- [X] 无数字，或数字无量纲（v2 版本、更新于 2026-09-19 这类噪音数字不算指标）

诚实出口：确实没有公开热度指标时，用 popularity_metric: "none_public"，
文案里写明「未公开可用热度指标」，且不得出现任何数字（防止拿无关数字伪装热度）。
> 这条比强迫编一个数字更重要 —— 详见「为什么 G1 要允许 none_public」。

踩坑史：v2.4 的 G1 是「禁止词黑名单 + 必须含数字」的正则，实测可被任意数字绕过：
连续迭代 3 次、v2 版本、共 5 个功能 全部放行。结果真实数据里 4/21 条热度字段装的是审稿意见
（如 改为「MiniMax Speech 系列…」—— 去除未核实的 ELO 1153…待复核），
并且已经渲染进产物（output/post.md:425），而门禁 16 项全绿。

G2｜下载链接 = 域名信任层判定 + 显式声明官方性

校验：rules.validate_download_url() · test_g2_download_url_all()

• 必须 https:// 开头
• 域名经 sources.json 的信任层判定为 official 或 third_party，默认拒绝（未登记域名一律拦）
• github.com 必须是 /<org>/<repo>（≥2 段），裸组织地址不算官方仓库
• 必须显式声明 download_url_ack ∈ (official, third_party)，且与实际域名层级一致

为什么要求显式 ack：第三方榜单站（如 skillselion.com）可以作热度来源，
但 v2.4 会把它静默标注成「官方排行榜」，与 G2 要防的「拿非官方页当下载入口」是同一个问题。
本版不禁止使用，但必须被人工确认过，渲染时会标注为「（第三方榜单页）」。

踩坑史：v2.4 的正则未锚定，实测 https://github.com.evil.com/x、https://totally-fake-site.com
全部放行，而真官方域名 https://www.gov.cn/policy 反被拦 —— 风险方向完全反了。
本版改为 urlsplit().netloc 精确匹配 + 显式白名单，并补了 *.gov.cn / *.edu.cn / *.org.cn。

G3｜论文与下载链接彻底分离

校验：rules.validate_paper_separated() · rules.is_paper_project()

• 论文只出现在 references（type: "paper"），标注 direct / foundational / related
• download_url 不得等于任何 paper reference 的 url
• 唯一豁免：is_paper_project() —— 存在一条 type=paper 且 url 与 download_url 完全相同
  且 verified_source=true 的 reference（即「项目本身即论文、无独立产品页」）

> [!] 豁免判据只此一处。v2.4 把它在 generate 与 test 里各写了一遍，
> 一处不要求 URL 相同、一处要求 —— 实测 generate 放行、产物落地、test 事后才拦。

G4｜底部结构：无论文汇总表，有技术趋势小结

校验：generate.assert_bottom_structure() · test_g4_bottom_structure()

• [X] 禁止独立论文汇总表（含「论文汇总」标题，或表格里出现 arXiv: 编号）
• [OK] 必须保留「本周技术趋势小结」
• [OK] Markdown 反引号必须成对

G5｜数据闭环：格式 + 数据 双重 verified

校验：test_g5_all_verified() · apply_verify.py 闭环自检 · verify_pending.py

1. 所有技能 verified: true，无 false 残留
2. 每个技能至少有一个 references 项满足 type ∈ (official, github, docs) 且 verified_source: true
3. popularity 符合 G1 且出处可溯源
4. download_url 符合 G2

核验流程（发布前必做，两步脚本都真实存在）：

python verify_pending.py      # ① 扫描数据，产出 verify_report.todo.json（待办清单 + 每项要核什么）
#    由 Agent 联网逐项核验，把结果填回 verify_report.filled.json
python apply_verify.py --report verify_report.filled.json   # ② 回填 + 闭环自检（缺项即退出码非 0）

特殊裁决规则（写死，不临时决策）：

G6｜用户偏好一致性（v3.0 新增）

校验：rules.validate_week() 的 cats_allowed 分支 · test_g6_preference_consistency()

• 结构数量必须等于 preferences.weekly 的 days / per_day / total
• 当 respect_preferences.enabled = true 时，每个技能的 category
  必须 ∈ 启用分类清单（枚举来自 categories.json）
• 需要临时忽略偏好时用 generate.py --all-categories（不改配置文件）

G7｜跨周不重复（v3.0 新增）

校验：rules.check_repeats() · dedupe.py --check

• history.json 登记每个已推荐技能的 canonical_key（github org/repo > host+path > 小写名）
• 若本周技能出现在最近 novelty.avoid_repeat_weeks（默认 12）周的历史里 -> 禁止发布
• 同一周自比较不算重复（重跑同一周是幂等再生成）
• 候选不足 novelty.shortage_ratio（默认 70%）时，可 --allow-repeat 显式接受，
  此时正文会自动输出「往期回顾」区块

python dedupe.py --check 2026-W39          # 出刊前对账，有重复退出码 1
python dedupe.py --commit 2026-W39          # 发布后登记入表
python dedupe.py --candidates cand.json     # 检索阶段先预检候选
python dedupe.py --plan                     # 按偏好输出本周配额
python dedupe.py --list                     # 查看历史登记

每周更新流程（完整可跑）

# ① 看偏好与配额（先决定本周找什么）
python prefs.py
python dedupe.py --plan

# ② 按配额联网检索候选 -> 写成 cand.json 后先预检去重
python dedupe.py --candidates cand.json

# ③ 把通过预检的技能写入新一周数据
cp data/2026-W38.json data/2026-WXX.json
#   编辑：week / cutoff / publish_date / trends / days（数量按 preferences）

# ④ G5 数据核验（两步）
python verify_pending.py
python apply_verify.py --report verify_report.filled.json

# ⑤ 生成产物（内含 G1–G6 断言的生成前校验；文件名由脚本按实际数量生成）
python cover.py --cutoff "数据截至 2026-XX-XX"
python generate.py --week 2026-WXX

# ⑥ 门禁：全绿才可发布
python test_validate.py

# ⑦ 去重对账 + 登记
python dedupe.py --check 2026-WXX
python dedupe.py --commit 2026-WXX

> [!] ④ 的 apply_verify.py 不可跳过 —— 数据核验是 G5 的实质要求，
> 不是走过场。脚本会用 schema.json 重新扫一遍，任何未闭环项都让退出码非 0。

核心产出

文件职责

依赖：见 requirements.txt（markdown、Pillow）—— v2.4 没有声明任何依赖，换机即失败。

字段清单

字段以 schema.json 为准（不再在文档、脚本里各写一份，v2.4 三处不一致）。
必填项：

id / name / subtitle / category
popularity / popularity_metric / popularity_source_url
release_date / release_status / type / stars / rating
one_line / features / value / cases / cmd
download_url / download_label / download_url_ack
recommend_reason / references

可选项：verified / editor_note（不参与渲染，存数据备注）/ is_third_party

参考来源分类

定时运行（每周自动推荐）

配套的每周自动化会按下面的顺序跑，用户无需干预：

prefs/dedupe --plan -> 检索候选 -> dedupe --candidates -> 写 data -> verify_pending -> apply_verify
-> cover -> generate -> test_validate -> dedupe --check -> dedupe --commit

自动化提示词里已写明：数量与分类以 preferences.json 为准；
任何一项门禁非 0 退出都不发布，并在汇报里说明卡在哪一条闸门。

为什么 G1 要允许 none_public

这是本版一个刻意的设计选择，值得写下来：

v2.4 的 G1 要求「热度必须有数字」。对确实没有公开指标的成熟产品（Midjourney、TRAE），
这条规则会逼着人编一个数字，或者塞一个无关数字（v7、2026）来骗过正则 ——
两个结果都比「如实写没有」更糟。

所以 v3.0 给它开了一个受约束的出口：popularity_metric = none_public
必须在文案里明示「未公开可用热度指标」，并且禁止出现任何数字。
这样「没有公开指标」成为一个能被机器识别的合法状态，而不是一个需要撒谎才能通过的检查点。

> 判断一个风控规则好坏的标准：它是否让「诚实」比「欺骗」更容易。
> 只靠黑名单的规则会让诚实的人被罚、让投机的人过关 —— 那是最烂的一种风控。

已知边界（不适用场景 · 诚实清单）

写清楚做不到的事，比多写一个功能更有用：

1. 热度数字的「当前正确性」需要人来核。本 skill 能强制「每个热度数字必须有可声明
   的 metric 和可点的出处」，也能把没有人核对过的项列成待办（verify_pending.py），
   但它自己不联网。真正的核验由使用者在每周流程第 6 步完成。
   .py 脚本无法替你判断一个数字是否仍然成立 —— 只能保证它不会悄悄溜过去。
2. none_public 是诚实，不是完备。对 Midjourney / TRAE 这类不公开指标的成熟产品，
   本 skill 会如实标注「未公开可用热度指标」而不编造数字。这意味着这一类条目在
   「热度可比性」上天然弱于有公开 Star / 安装量的项目。
3. 跨周去重只认 canonical_key（GitHub org/repo 优先，其次 host+path，最后小写名）。
   同一产品换了官方域名或仓库迁移，会被判成两个不同技能；反之，两个不同产品恰好同址也会被判重复。
4. 分类配额是「指导」不是「配额制」。weight 只用于算出建议名额（dedupe.py --plan），
   闸门 G6 只强制「入选分类必须在启用清单内」，不强制每类必须凑满。
5. 不自动发布。所有产物落在 output/，是否发布由使用者决定；本 skill 只保证
   门禁不过就不出产物。

作者与联系方式

本 skill 由「七仔的AI工具箱」维护。欢迎就技能使用、问题反馈与二次分享交流：

• 微信公众号：七仔的AI工具箱
• 抖音号：七仔的AI工具箱
• CSDN 博客：七仔的AI工具箱

版权与署名

本 skill 为原创工具，可免费使用与二次分享；转载请注明出处「七仔的AI工具箱」。

• 本 skill 不包含任何第三方受版权保护的原文摘录；正文中的技能介绍均基于各项目的
  官方页面（GitHub 仓库 / 官方文档 / 官方发布页）与公开榜单数据，并在每张卡的
  「参考来源」中逐条标注出处与关联强度。
• 内置的「发布闸门 + 反例回归测试」工程方法论，参考了公开社区实践。
• 示例周报中的技能名称、商标与产品名归各自所有者所有，此处仅作事实性介绍与推荐。