WorkBuddy&Skillhub 技能上传审核（workbuddy-skillhub-upload-review）
对任意 Skill 目录做可复现的机检评审，再按处方优化整改，最后复审出前后对比。
规则全部来自实战踩坑：技能商店两轮驳回（name 格式 / 目录层级）、TRACE 评分扣分点（缺 FAQ、提示技术化、失败静默）、多 skill 并行开发纪律。
> ## 📌 30 秒看懂（评测 / 新手都先看这个框）
> 这是什么：你写完或改完一个 Skill，在准备上架、或收到低分 / 驳回反馈时，一键机检出「还差哪几处、每处怎么修」，并能直接打出合规上传包。
> 一句话触发（复制任意一句发给我，Agent 就会加载本技能进入评审）：
> - 上架前体检：「帮我上传审核这个技能」／「技能体检一下」／「上架前检查」
> - 收到低分 / 驳回：「按评分整改」／「评分太低了帮我改」／「收到驳回反馈，按处方修」
> - 一键出包：「一键评审并打包」
> 最适合：准备上架或想提 SkillHub 评分，想快速知道短板与修法。
> 不适合：① 业务逻辑对不对、Skill 真实任务做得好不好（这类靠你实测 + 用户反馈，本工具只给机检「体检值」）；② 来路不明 Skill 的安全性预检（请先人工过一遍其测试代码）。
何时用
| 场景 | 动作 |
|---|---|
| 上架技能商店前 | 全量评审 + pack.py 打包 |
| 收到评分/驳回反馈 | 把扣分点对进报告 → 按处方整改 → 复审 |
| 日常体检 | 只跑评审，出报告不动代码 |
触发话术（用户这么说就触发）
不知道该发什么？照下面任意一句发即可，Agent 会加载本技能并进入评审流程：
| 你想做的事 | 直接说 |
|---|---|
| 上架前体检 | 「帮我上传审核这个技能」「技能体检一下」「上架前检查」 |
| 收到驳回 / 低分 | 「按评分整改」「评分太低了帮我改」「收到驳回反馈，按处方修」 |
| 一键评审 + 打包 | 「一键评审并打包」「跑 review 出报告再 pack」 |
| 多 skill 一起 | 「评审整个项目根」「把项目里所有 skill 都体检一遍」 |
能力边界（适用 / 不适用）
| 类别 | 说明 |
|---|---|
| ✅ 能审 | 商店硬规则（name kebab-case、两级目录、必填 frontmatter、图标）；文档要素（触发词 / FAQ / 已知限制 / 文档地图 / 快速上手 / 示例）；代码健康（语法 / 密钥 / 跨包 import / 事件订阅 / 宿主分支 / 静默 except）；测试是否可执行 |
| ❌ 不审 | 业务逻辑对不对、skill 实际任务做没做对——R/E 维的"真实有效性"靠 Agent 实测 + 用户反馈，本工具只给机检"体检值"；来路不明 skill 的 selftest 安全性（评审前请人工过一遍其测试代码） |
| 🎯 最适合 | 你写完 / 改完一个 skill，准备上架或收到评分反馈，想快速知道"还差哪几处、怎么修" |
文档地图（想看什么去哪）
| 你想了解 | 看这里 |
|---|---|
| 每一步怎么敲命令 | 本文件「三步工作流」 |
| 每个发现 R01~R16 的具体修法 | references/playbook.md |
| 改了什么 / 踩了什么 | CL.md（append-only 过程记录） |
| 自检是否正常 | scripts/selftest.py |
三步工作流
第 1 步 · 评审（机检，只读目标目录）
python scripts/review.py <skill目录或项目根> --out <报告.md>
# 例：多 skill 项目根会自动找出每个含 SKILL.md 的子目录，按字分节出报告
产出：TRACE 评分卡（T/R/A/C/E + 总分）+ 发现清单（P0/P1/P2 分级、文件:行号证据、处方编号 R01~R16）。
退出码：0 = 无 P0；1 = 有 P0（必须整改）；2 = 没找到 skill。
第 2 步 · 优化（Agent 按处方执行）
- 读报告，按 P0 → P1 → P2 顺序处理；
- 每个发现按编号查
references/playbook.md的具体修法（R01 name、R03 压平目录、R06 失败可观测、R07 已知限制表、R11 简介限长、R14 修复记录分条、R15 版本升级清单……）； - 每修一类就复跑 selftest / review.py，不要攒一批再验；
- 留修复记录：按 skill 分条写进该 skill 的 CL.md（跨字公共内容单独成条），不合并成大表。
第 3 步 · 复审 + 打包
python scripts/review.py <skill目录> --out <复审报告.md> # 必须给出前后对比
python scripts/pack.py <skill目录> --out <输出目录> # 校验不过直接拒绝打包
pack.py 内置商店双规则（name kebab-case + 目录深度 ≤2）与必填 frontmatter / icon 校验，
产出 <name>-v<version>.zip（包内顶层文件夹 = name）。校验失败不许 --force 硬打。
评审报告样例（真实跑出来的，不是示意）
对本技能包（2.2.0）实际跑 review.py 的真实输出：
## 总览
| Skill | T | R | A | C | E | 总分 | P0 | P1 | P2 | 测试 |
|---|---|---|---|---|---|---|---|---|---|---|
| workbuddy-skillhub-upload-review | 5.0 | 5.0 | 5.0 | 5.0 | 5.0 | 5.0 | 0 | 0 | 0 | selftest -> exit=0 (5/5) |
## workbuddy-skillhub-upload-review
无发现 ✅
当目标 skill 有问题时，发现清单长这样（每行都带证据 + 处方编号）：
| 级别 | 代码 | 问题 | 证据 | 处方 |
|---|---|---|---|---|
| P2 | STORE_NAME | 文件夹名≠name（包内顶层文件夹应与 name 一致） | <技能目录> | R02 |
| P2 | DOC_MAP | 缺「文档地图」 | SKILL.md | R08 |
> 说明：这就是「带证据 + 带处方」的写法：每个发现你都知道它在哪（证据）、为什么、照 Rxx 怎么修，不用猜。
真实前后对比：某 skill 首评出 DOC_MAP / DOC_EXAMPLES / DOC_BOUNDARY 三个 P2（C 维被扣到 4.7）→ 补上「文档地图 / 示例 / 已知限制」三节后复跑，P2 清零、C 维回到 5.0。下面是新手最常撞的 3 个发现，30 秒就能修，不用跳文档：
| 发现代码 | 现象 | 30 秒修法（不用翻 playbook） |
|---|---|---|
R02 目录名≠name |
pack.py 报 STORE_NAME，说顶层文件夹不对 |
包内顶层文件夹必须是 name 字段值（kebab-case）；pack.py 已自动用 name 当顶层，本地文件夹名随便起，但上架包以 name 为准 |
R03 目录超两级 |
评审报「目录深度 >2」 | 把深嵌套压平：<skill>/scripts/、<skill>/references/，别搞 <skill>/a/b/c/ |
R11 简介超限 |
描述 >100 字符 | 把 description_zh 压到 ≤100 字，只留「做什么 + 提分/提通过率」价值点 |
纪律（违反 = 返工）
- 目标目录在评审阶段只读；优化阶段只改用户指明的 skill；改完即验，验完再改下一处。
- 破坏性操作（删文件 / git reset）前工作区必须先干净：先提交，再测试。
- 不代删用户桌面/下载目录的任何文件；产出物放用户指定位置。
- 版本号变更不是改一个数字：按 R15 的全量清单逐项过，历史记录里的旧版本按史实保留。
- 多 skill 并行时 git 提交按文件夹圈定（
git add <目录>），禁用add -A卷入他人的进行中改动。
常见问题（FAQ）
| 问题 | 回答 |
|---|---|
| 机检分和商店评分什么关系？ | 机检覆盖 T/C 维的硬规则与 R 维的测试执行；商店评分里的 A/E 维（易用性、真实有效性）靠 Agent 实测补齐——报告是体检值，不是名次。 |
--force 什么时候能用？ |
几乎不用。它只应在「明知不合规但确有理由」时使用（如内部试用包）；上架包一律先修到校验通过。 |
| 评审会不会改坏我的 skill？ | 评审阶段只读（唯一例外：执行目标 skill 自己的 selftest）；所有写动作发生在你明确进入优化阶段之后。 |
| 多 skill 项目一次评审？ | 直接给项目根路径，引擎自动找每个含 SKILL.md 的子目录，报告按 skill 分节。 |
| 评测说「图标简陋 / 稍显简陋」怎么办？ | 换一张更精致的高清图标（≥256×256 PNG，主题贴合「审核/盾牌/对勾」）放进 icon.png 重打包即可；功能不受影响，仅视觉分。 |
| 我改了版本号，为什么评测分没变？ | 评测分看的是文档与体验，不是版本号；版本号只按 R15 纪律随内容升级而变，单独改号不涨分。 |
review.py 报 P2 但我认为是误报，能忽略吗？ |
可以。P2 是建议项不是阻塞项；但若你拿不准，去 references/playbook.md 对应 Rxx 看一眼再决定，别凭感觉跳过。 |
技能文件夹要不要跟 name 一样？ |
建议一致：文件夹名用 kebab-case、与 name 相同，可避免 R02 / STORE_NAME 提示（本技能自身已按此规范命名）。包内顶层文件夹 pack.py 始终用 name，与本地文件夹名无关。 |
> ## 📘 新手必读（照这 3 步走，不会踩坑）
> 1. 先评审再改：跑 review.py 拿到带证据 + 处方的报告，别凭感觉动手。
> 2. 改一处验一处：每修一类发现就复跑 review.py / selftest，别攒一批——定位成本翻倍。
> 3. 打包前必须绿：pack.py 校验过了才传；过不了就回头按处方修，别用 --force 硬打。
⚠️ 反模式（常见错误，千万别踩）
- 不做
--force硬打包：校验没过就强打，上架照样被驳回；先修到pack.py绿了再传。 - 不攒一批再验：每修一类就复跑
review.py/selftest，别改完十个发现再一起测——定位成本翻倍。 - 不代删用户文件：桌面 / 下载目录一律不动；产出物放用户指定位置。
- 不跨包 import 同级 skill：多 skill 并行时走宿主适配层，否则
CODE_CROSSIMPORT直接 P1。 - 不在评审阶段写目标目录：评审只读，所有写动作发生在你明确进入优化阶段之后。
- 不只改版本号想涨分：版本号只随内容升级而变（R15），单独改号评测分不会动。
- 不忽略 P2 凭感觉：P2 是建议项，但拿不准先去
references/playbook.md对应 Rxx 看一眼，别跳过。 - 不漏记 CL.md：每次整改按 skill 分条写修复记录，跨字公共内容单独成条，方便回看与复现。
故障排查（出错怎么办）
| 现象 | 一句话原因 | 怎么修 |
|---|---|---|
review.py 报 P0 且 exit 1 |
有必须整改项（name / 目录 / 密钥 / 语法） | 看报告「处方」列，去 references/playbook.md 对应 Rxx 修 |
pack.py 输出 ❌ 校验未通过 |
商店双规则没过 | 先跑 review.py 拿处方整改，再 pack.py；别用 --force |
| 测试 exit≠0 | selftest 有用例没过 | 读 selftest 输出定位用例，修实现或同步夹具，复跑 |
| 评审卡住 / 超时 | 目标 skill 的 selftest 太慢 | python scripts/review.py <目录> --timeout 600 调大 |
PermissionError / 磁盘满 |
输出目录不可写或空间不足 | 换 --out 到有权限、有空间的目录 |
已知限制与局限（诚实声明）
- 机检是静态启发：T/C 维可机检为主，R/E 维（易用性、真实任务有效性）最终靠 Agent 实测与用户反馈；报告分数应视为"体检值"不是"名次"。
review.py会执行目标 skill 的 selftest（这是测试的本意）——评审来路不明的 skill 前先人工过一遍其测试代码。- 边界类 grep（订阅/宿主分支）会有注释误报，报告里已标「需人工确认」。
