Skill 发布前质量检查

对即将发布到 WorkBuddy 开发平台的 Skill 做功能回归测试 + 发布规范复核 + 量化打分 + 同类对比，
输出结构化报告，给出总分评级与"是否可发布"的综合结论。

何时使用

• 用户说「检查/审查/测试/回归/复核这个 skill 能不能发布」
• 用户上传一个 skill 压缩包或目录，要求评估发布质量
• 用户要求「发布前体检」「skill 质量把关」
• 用户要求「给这个 skill 打个分」「质量几分」「评级多少」
• 用户要求「和其他 skill 对比一下」「和 skill-creator 有什么区别」「同类 skill 对比」
• 用户问「这个 skill 好不好」「是不是好 skill」「好 skill 的标准是什么」「怎么判断一个 skill 写得好不好」
• 用户要求「优化某个/所有 skill」「自动优化」「让 skill 进化/迭代」「达尔文/darwin」——进入内置的 Darwin 自主优化引擎（第十步）
• 用户要求「提升 skill 质量」「skill review」「skill 怎么改更好」「帮我改改 skill」——先 8 维评分定位短板，再进入优化引擎
• 用户要求「看看 skill 优化历史/进化记录」——读取本 skill 目录下 results.tsv 展示历史
• 用户要求「给 skill 打优化分/结构分」「skill 八维评分」——8 维优化评分（与第五步七维发布分是两套口径，见模式路由）

模式路由（动手前先判断用户意图）

用户请求可能命中多个场景，按下列规则路由到对应执行路径，避免"一上来就全流程"：

路由优先级：optimize > check > score > package > history（意图包含"改进"类动作词时按 optimize 处理；
"检查后顺手修复"仍属 check，检查发现的问题修复完再打包）。一句话不确定时，向用户确认再动手。

检查流程（按顺序执行）

细则是按需加载的，不必一次读完：打分看 references/scoring-rubric.md，
对比看 references/peer-comparison.md，报告格式看 references/report-template.md，官方常见错误预检清单看 references/publish-errors-checklist.md，好 skill 五要素判定看 references/quality-rubric.md，自动扫描用 scripts/precheck_publish.py。
Darwin 自主优化引擎（optimize 模式）按需加载：8 维优化评分看 references/darwin-rubric.md，
优化循环/棘轮/异常表/历史日志看 references/optimize-loop.md，成果卡片生成看 references/result-card.md。

第一步：定位并解包 skill

1. 若输入是 .zip，用 Python zipfile 解压（不要用 Git Bash unzip，Windows 下中文文件名会乱码；Python 的 zipfile 能正确识别 UTF-8 EFS 标志）：
   python import zipfile zipfile.ZipFile(src).extractall(dst)
2. 确认 SKILL.md 位于包根（或顶层唯一目录）下。
3. 记录包结构：SKILL.md + 可选 scripts/ references/ assets/。

第二步：官方常见错误预检（precheck_publish.py）

目标：在功能回归与打分之前，先用确定性静态扫描主动识别「开放平台发布流程中官方记录的各类常见错误」，
把 FAIL 全部清零，避免带着已知问题进入人工检查。错误分类与每条 ID 的权威定义见
references/publish-errors-checklist.md（A–G 七大类，含触发原因、官方提示信息、修复方法）。

python scripts/precheck_publish.py <skill目录或zip>
# 或直接生成可粘贴进报告的 Markdown 预检卡片
python scripts/precheck_publish.py <skill目录> --md

扫描项（每条对应清单 ID，覆盖 30+ 条已知发布错误）：
- A 类 硬性校验（A01–A11）：SKILL.md 存在、frontmatter 合法、name/description 必填且符合 kebab-case/长度 ≤64/无尖括号、无非法 frontmatter 字段。
- D 类 命名与描述（D01–D04）：目录名 == name、name 非泛化、description 含触发场景与充足触发词。
- G 类 双语字段（G01–G04）：display_name / display_name_en / description_zh / description_en 齐全（quick_validate 不查，但上架必填）。
- E 类 包结构（E01–E05）：两级目录无真实三级嵌套、无构建产物残留、references 无嵌套/断链、脚本 py_compile 通过。
- F 类 环境编码（F01–F02）：无 UTF-8 BOM、无真实用户绝对路径泄漏。
- C 类 安全审核（C01–C03）：无密钥硬编码、无境外平台引用、无不安全代码（verify=False / shell=True / os.system 拼接）。

判定与处置：
- 退出码 0 = 无 FAIL（WARN 也通过，可继续）；1 = 存在 FAIL（须先修复再发布）；2 = 参数/路径错误。
- FAIL 与 quick_validate 失败、20 项必填项未满足同源——都直接喂给第五步 D4 规范合规维度打分与一票否决，发布前必须清零。
- WARN 不阻塞发布，但属「上线后可能被驳回 / 触发不准」的隐患，建议顺手修（如 E02 构建产物残留、C02/C03 安全提示）。

第三步：功能回归测试

目标：以真实用户操作方式覆盖核心功能。先读 SKILL.md 与 run_all.py/入口脚本，搞清有哪几种模式、哪些 CLI 参数，再逐类测试。

三类用例：

1. 正常流程：SKILL.md 宣称的每个模式/功能，逐一端到端跑通，验证产物文件与关键输出字段正确。
2. 边界条件：空输入、单元素输入、特殊文件名（中文/空格/括号）、可选参数、外部配置文件等。
3. 异常输入：参数缺失、文件不存在、非法枚举值、非目标格式文件、损坏文件、重复触发、缺失依赖配置等。

每类用例都记录：执行步骤 → 预期结果 → 实际结果 → 通过/失败。

关键测试点（务必覆盖）：
- 各模式的正常产出（报告/修复稿/对比结果等）
- 异常输入的退出码是否正确（argparse 错误应为 2）
- 是否抛出未捕获 Traceback（这属于体验缺陷，记 P1）
- 文档承诺的功能是否真的实现（对照 SKILL.md 与实际代码行为；缺实现记 P1）
- 语义自洽（自指一致性）（与第 4 条分工：第 4 条查「宣称的功能有没有实现」=功能缺失，本条查「宣称与自身实践自相矛盾」=自打脸，第 3 类对照聚焦命名/参数一致性）：文档宣称与自身实践是否自相矛盾——典型反例：把「curl 到未知 URL」列为安全红旗、自身却在 SKILL.md 示范/要求 curl 外联；声称「零依赖/零配置」却要求外部服务或隐藏前置；宣称的模式/参数/输出与 scripts 实际 CLI 不符。逐条对照红旗规则 ↔ 自身示范、声明 ↔ 实际依赖、文档模式 ↔ 脚本 argparse，发现矛盾记 P1（发布前须澄清），引用具体行号作证据。纯流程回归容易漏掉此类问题，务必单列核查。

第四步：发布要求逐条复核

> 本步骤的多数硬性项（A/D/G/E/F 类、C 类安全扫描）已由第二步 precheck_publish.py 自动扫描，
> 此处侧重人工复核、证据记录与 #21 两级目录核验；若第二步有 FAIL，优先回到对应 skill 修复后再继续。

对照官方 skill-creator 插件的规范逐条核验。该插件随客户端安装，路径为客户端安装目录下的
resources/app.asar.unpacked/resources/plugins/workbuddy-builtin/skills/skill-creator/
（Windows 通常为 %ProgramFiles%\WorkBuddy\resources\app.asar.unpacked\resources\plugins\workbuddy-builtin\skills\skill-creator\，
找不到时用 Glob 全局搜 **/skill-creator/SKILL.md 定位）：

务必用官方脚本权威校验：

python quick_validate.py <skill_dir>

目录层级上限（两级结构，强制 · 检查 #21）

平台硬性规则：Skill 包仅支持两级目录结构（根目录 / 二级目录 / 文件）。
- 根目录 = 包文件夹本身（名称须等于 frontmatter 的 name）
- 二级目录 = 根目录下的直接子目录（如 scripts/ references/ assets/）
- 文件可位于根目录，或位于任意二级目录下
- 三级及以上嵌套一律违规（如 scripts/__pycache__/），上传会直接报
「目录层级超限 — Skill 包仅支持两级目录结构（根目录/二级目录/文件），请移除子目录嵌套」

最常见诱因：本地跑过 scripts/*.py 后残留的 __pycache__/*.pyc 被一起打进 zip。
自动检查（配套脚本，支持目录与 zip，支持 JSON 输出）：

python scripts/check_package_structure.py <skill目录或zip> [--clean] [--json]

• 不加 --clean：只检测，列出所有三级及以上嵌套目录（构建产物会标注"可 --clean 清理"）。
• 加 --clean：自动删除安全构建产物（__pycache__/ *.pyc .DS_Store Thumbs.db）；
  目录输入原地清理，zip 输入生成 <原名>-clean.zip（不覆盖原包）。
  仅清理构建产物，用户自建的真实嵌套目录不会被删除，需人工展平后重新打包。

修复原则：
- 构建产物（__pycache__ 等）：直接删，可随时重建，无害。
- 真实业务子目录：把内容移入根目录或既有二级目录（references/ assets/ scripts/），
删除该子目录后重新用 zipfile 打包（务必用 Python，勿用 Git Bash unzip 以免中文名乱码）。

开放平台的中英文双语字段（quick_validate.py 不查，务必自行核验）

官方 quick_validate.py 只查 name/description/命名，不校验开放平台上架时要求的中英文双语字段，
缺了会在发布时直接报错。须确认 SKILL.md frontmatter 含以下双语字段（display_name / display_name_en /
description_zh / description_en；若包内含 manifest.yaml，两处取值须完全一致）：

核验要点：
1. 三个双语字段（display_name_en / description_zh / description_en）一个都不能缺，缺了平台会分别报「英文描述」「中文描述」「英文名称」类错误。
2. SKILL.md frontmatter 与 manifest.yaml 两处的双语字段取值要完全一致。
3. 参考其他必填字段一并核对：name、version、author、category、license。

第五步：七维度质量打分

目标：把定性结论换算成可复现、可跨版本对比的量化分数。细则见 references/scoring-rubric.md。

七个维度与权重：D1 功能完整性 15% / D2 功能正确性 20% / D3 健壮性 20% / D4 规范合规 15% /
D5 文档质量 12% / D6 工程规范 10% / D7 安全与隐私 8%。

打分要点：
1. D1–D4 有换算公式，直接由用例通过率与复核结果算出（部分通过按 0.5 计）。
2. D5–D7 是清单式打分，逐条对照检查项给分。
3. 每个维度必须能在测试用例或复核清单中指到具体依据，禁止凭印象给分。
4. 七项分数须齐全——缺失维度会触发"评分不完整否决"，防止漏打分蒙混过关。

必须用脚本算分，不要心算加权平均：

python scripts/score_skill.py --input scores.json --md

脚本输出加权总分、A–F 评级、发布建议、Markdown 评分卡片；
并应用四条一票否决（P0 否决封顶 5.9 / 核心维度否决封顶 6.9 / 合规必填项否决封顶 6.9 /
评分不完整否决封顶 6.9）。退出码 0=可发布，1=不可发布，2=参数错误。

第六步：同类 Skill 功能对比

目标：说明本 skill 在本机同类工具中的位置。方法论见 references/peer-comparison.md。

1. 找候选：扫描用户级 ~/.workbuddy/skills/、内置插件 workbuddy-builtin/skills/、
   市场缓存 ~/.workbuddy/plugins/cache/workbuddy-builtin/ 三个目录的 SKILL.md，
   按能力关键词筛选，再按作用对象过滤（只保留同样处理"可分发的 AI 能力包"的），保留 2–4 个。
2. 核能力：按统一的 16 项能力维度（C1 初始化脚手架 … C16 作用对象）逐项核对，
   标记 ✅完整 / ⚠️部分 / ❌不支持 / —不适用。
   以实际读到的 SKILL.md 与脚本为准，没读到的一律记 ❌，不得凭名称推测。
3. 写结论：输出对比矩阵 + 差异化分析（独有优势 / 能力空白 / 重叠区 / 路由建议）+ 一句话定位。

关键认知：skill-creator 只做"能不能打包"，不做"好不好用"——quick_validate.py 不查断链、
路径泄漏、功能是否真实现。两者是上下游而非竞争：
skill-creator 创建 → 本 skill 检查 → skill-creator 打包。对比时须写明这层互补关系。

本机无同类 skill 时，报告中写一句"未发现同类 skill，跳过横向对比"即可，不要强行对比。

第七步：Skill 五要素质量评估（好 skill 判定）

目标：回答"这个 skill 是不是一个好 skill"。判定标准是五要素：定场景、立目标、理规划、给示例、划边界——
好 skill 的本质是目标明确、步骤具体、示例充分、边界清楚。细则见 references/quality-rubric.md。

对 SKILL.md 逐项评估（每项必须引用 SKILL.md 具体段落作证据，禁止凭印象）：

评分锚点：2 = 充分且可直接执行；1 = 部分具备、需补充细节；0 = 缺失或含糊。

判定规则：
- 目标明确 + 步骤具体 + 示例充分 + 边界清楚四项均 ≥1 分，且定场景 ≥1 分 → 判定为「好 skill」。
- 存在 0 分项 → 记 P1 问题，按缺失要素给出补写建议（该要素缺失会直接影响下游 Agent 的触发准确性与执行成功率）。
- 五要素评估结果写进第八步测试报告（第七章），与七维度打分互补：五要素回答"是不是好 skill"，七维度回答"能不能发布"。

第八步：输出测试报告

报告结构（详见 references/report-template.md）：
1. 测试范围
2. 测试用例清单（步骤/预期/实际/状态）
3. 发现的问题（现象/复现步骤/根因/严重程度 P0-P2/修复建议）+ P0/P1/P2 数量统计
4. 发布要求逐条复核（满足项/未满足项/必填项未满足清单）
5. 质量评分（评分卡片 + 分数解读 + 解除封顶的修复建议）
6. Skill 五要素质量评估（定场景/立目标/理规划/给示例/划边界逐项证据与得分 + 好 skill 判定）
7. 同类 Skill 功能对比（对比对象 / 能力矩阵 / 差异化分析 / 一句话定位）
8. 综合结论（是否达到可发布状态，须与评级一致）
9. Darwin 八维优化评分与改进建议（仅 optimize / 点名要"优化分/八维"的 score 模式）——输出 O1–O8 逐维分数、最低分维度定位、建议改进方向；若已执行优化循环，附 Before→After 对比与结果卡

第九步：打包为可上传 zip

目标：在检查 / 打分 / 对比 / 修复全部完成后，直接产出一个可上传开放平台的干净 zip，省去用户手工打包。

python scripts/package_for_release.py <skill目录> --out <输出目录>
# 可选：打包前原地清理 __pycache__ 等构建产物；--skip-validate 跳过官方校验
python scripts/package_for_release.py <skill目录> --out <输出目录> --clean

脚本行为（详见 scripts/package_for_release.py docstring）：
1. 读取 SKILL.md frontmatter 的 name / version，zip 命名为 <name>-v<version>.zip，包内顶层目录 = name（不含版本号后缀）。
2. 两级目录上限检查：复用 scripts/check_package_structure.py，发现真实三级及以上嵌套直接拒绝打包并提示人工展平（构建产物 __pycache__ 等会被自动剔除，不触发该错误）。
3. 自动剔除 __pycache__/ *.pyc .DS_Store Thumbs.db 等构建产物——规避官方 package_skill.py 把它们一起打进包导致上传「三级目录层级超限」。
4. 写入后 zipfile.testzip() 校验完整性；可选地跑官方 quick_validate.py 给出权威结论。
5. 退出码 0=成功、1=结构违规或校验失败、2=参数/路径错误。

交付：把生成的 <name>-v<version>.zip 作为最终产物交给用户，并建议其在开放平台连接器管理页对该 skill 点「信任」后上传。

第十步：Darwin 自主优化引擎（optimize 模式，可选）

> 由 darwin-skill 整合而来。目标：当用户要求"优化 skill / 自动改进 / 提升质量"时，
> 以 8 维评分定位短板 → 逐轮改进 → 独立实测 → 棘轮保留/回滚 → 生成成果卡片。
> 详规见 references/optimize-loop.md（流程与异常表）、references/darwin-rubric.md（八维评分细则）、
> references/result-card.md（成果卡片）。此处只列执行骨架。

1. 确认范围与前置
   - 目标 skill 目录（单个或全部，默认 ~/.workbuddy/skills/*/SKILL.md）
   - 目标目录建议在 git 仓库（不在则按异常表用 .bak 文件备份兜底）
   - 初始化 results.tsv（本 skill 目录下，9 列含 eval_mode）；读历史了解过往优化

2. 测试 prompt 设计（Phase 0.5）
   - 为每个目标 skill 设计 2-3 个典型用户 prompt，存 {skill}/test-prompts.json
   - 展示给用户，确认后再评估（prompt 质量决定优化方向）

3. 基线八维评分（Phase 1）
   - 结构维度 O1-O7 主 agent 打分；效果维度 O8 spawn 独立子 agent 跑测试
     （带 skill vs 不带 skill 的 baseline 对比；子 agent 不可用则干跑并标注 dry_run）
   - 汇总加权总分（Σ 维度分 × 权重 / 10），展示评分卡，暂停等用户确认

4. 优化循环（Phase 2，每 skill ≤3 轮）
   - 每轮：诊断最低分维度 → 生成 1 个改进方案 → 编辑 SKILL.md + git commit
     → 独立重评 → 新分 > 旧分 ? keep : git revert 回滚并终止该 skill
   - 每轮只改一个维度；优化后体积 ≤ 原 × 150%
   - 每个 skill 完成后展示 diff + 分数变化 + 测试输出对比，等用户确认再继续下一个
   - 连续 2 个 skill 首轮涨不动 → 征得用户同意后做"探索性重写"（stash → 重写 → 对比）

5. 汇总与成果卡（Phase 3）
   - 汇总报告：优化数/实验次数/保留率/回滚数/实测方式 + Before→After 分数表
   - 按 references/result-card.md 用 templates/*.html + scripts/screenshot.mjs 生成成果卡片 PNG

与检查流程的关系：optimize 模式是 check 的延伸而非替代——"发布前体检 + 改进"时先跑
第一~九步定位可发布性，再进入本引擎做质量进化；优化后用第五步七维分复测，确认发布分未回退。
本 skill 自身的优化历史记入本目录 results.tsv（已被 .gitignore 排除，不打进发布包）。

严重程度分级

• P0：崩溃、数据丢失、隐私泄漏、核心功能不可用 —— 阻塞发布
• P1：功能与文档不符、异常处理鲁棒性差、体验明显受损 —— 建议修复
• P2：报告可读性瑕疵、冗余工作、细节不一致 —— 可留待后续版本

关键经验（务必遵守）

1. Windows 中文文件名：解压 zip 用 Python zipfile，勿用 unzip。
2. 退出码：用 echo $? 无管道方式验证真实退出码；| tail 会掩盖成 0。
3. 文档 vs 实现：SKILL.md 宣称的功能（如 --mode all 三步）必须实际跑一遍核对，不能只信文档。
4. 断链引用：grep 出 SKILL.md 里的 assets/ scripts/ references/ 路径，逐个 os.path.exists 校验。
5. 官方校验的盲区：quick_validate.py 只查 name/description/命名，不查断链、泄漏路径、版本一致性、异常处理、功能是否真实现——这些需自行补测。
6. 打分不要心算：七维度加权求和与四条否决封顶一律交给 scripts/score_skill.py，避免算错加权平均或漏用否决规则。
7. 对比不要臆测：同类 skill 的每一项 ✅/❌ 都要能指到具体脚本或 SKILL.md 段落；读到什么写什么，读不到的记 ❌ 并注明"未找到对应实现"。
8. 结论与评级必须一致：评级 D/F 时结论只能是"需修复后发布/不可发布"，不得出现"B 级但不可发布"这类自相矛盾的表述。
9. YAML 冒号隐藏雷：frontmatter 字段值里若含 :（尤其英文描述如 loop: five...），YAML 会报 mapping values are not allowed here 导致解析失败。含冒号的值必须用双引号包裹。反之，键: 值 的冒号后要空一格，且值里尽量不用裸冒号。
10. 目录层级上限（两级）：Skill 包仅允许「根目录/二级目录/文件」，禁止三级嵌套。头号诱因是本地跑脚本残留的 scripts/__pycache__/*.pyc 被打进 zip——用 scripts/check_package_structure.py <包> --clean 可一键清理并产出 <原名>-clean.zip。重新打包务必用 Python zipfile（勿用 Git Bash unzip，中文名会乱码），且顶层目录名须等于 frontmatter name（不要带版本号后缀）。
11. 一键打包交付：终态产物用 scripts/package_for_release.py <目录> --out <输出> 生成 <name>-v<version>.zip，它会自动剔除构建产物并做两级检查，比官方 package_skill.py 更适配上传（官方会把 __pycache__ 一并打进包）。
12. 预检先行：发布任意 skill 前先跑 scripts/precheck_publish.py <目录> 把 FAIL 清零（覆盖 A–G 七大类共 30+ 条官方已知错误）。FAIL 与 quick_validate 失败、20 项必填项未满足同源，直接进 D4 规范合规维度打分与一票否决；WARN（如构建产物残留、境外平台引用提示）不阻塞但建议顺手修。
13. 五要素要有证据：评估"是不是好 skill"时，定场景/立目标/理规划/给示例/划边界每项都要引用 SKILL.md 具体段落，不能凭印象；出现 0 分项记 P1 并给补写建议。五要素评估是七维度打分的补充而非替代——前者判"好不好用"，后者判"能否发布"。
14. 三套评分不混用：七维发布分（scoring-rubric.md，判能否发布）、五要素（quality-rubric.md，判是否好 skill）、八维优化分（darwin-rubric.md，判往哪改）口径不同，禁止合并公式或互相折算；同一次任务里可并存展示，但各自按各自口径打分与纵向对比。
15. 棘轮回滚用 git revert：optimize 模式下保留/回滚一律 git revert HEAD（新 commit），禁用 git reset --hard；目标目录不在 git 仓库时先建议 git init，拒绝则用 SKILL.md.bak.<时间戳> 文件备份兜底。效果维度评分必须由独立子 agent 或干跑验证完成，不能在同一上下文"改完直接评"。
16. 本 skill 自身工作文件不入发布包：results.tsv、backups/ 已被 .gitignore 排除；对本 skill 自身打包时用 python scripts/package_for_release.py . --out <目录> --exclude backups results.tsv _user_meta.json（若打包脚本已支持 --exclude），或先移走这些目录再打包。
17. 成果卡模板勿直接改原件：填充 templates/result-card*.html 前先复制到临时文件，按 data-field 占位符替换；截图为 PNG 用 scripts/screenshot.mjs（Windows 已适配：自动探测 playwright-core，找不到时用 npx playwright screenshot 回退）。