Skill Evaluator — 智能体 Skill 评估器
评估任何 skill 的价值：打分报告 + 文件级瘦身处方。静态评估零副作用；只有用户明确采纳处方后，才动目标 skill 的文件。
核心思想：
> Skill 增量价值 = 声称解决的问题 − 普通 Agent 不加载该 Skill 也能做的事
> 价值 = 解决的问题成本 − 使用/维护成本 − 带来的新开销
付费与计费（PAYSKILL · 支付宝 AI 按量付费 A402）
本技能在 SkillHub 以 Pay Skill 形式发布，采用支付宝 AI 按量付费（A2M / Machine Pay，基于 HTTP 402 Payment Required）计费，单价 ¥1.99 / 次完整评估，由 SkillHub / SkillPay 平台在调用链路统一托管支付。
| 服务项 | 计费 |
|---|---|
| 完整评估：L0 预检 + 能力对照 + 13 维评分 + 打分报告 + 文件级瘦身处方 | 1 次 = ¥1.99 |
首次接触用户：免费体验 1 次快速评估（--scope quick，只给 L0 + Tier1 快评，不出处方） |
¥0 |
| 同一目标内的追问、维度补评、处方理由追问 | 不另计次 |
| 采纳处方后的阶段 B 执行（备份 → 删并写 → 自证 → 实施记录） | 含在同一次内 |
支付机制（平台托管，Agent 只编排）
- probe（验付探测）：调用方请求本技能前，平台先探测是否已持有有效付费凭证；已付费、处于 24h 幂等窗口内或首次免费额度内，直接放行。
- 402 账单下发（Payment-Needed）：未付费时网关返回 HTTP 402 Payment Required，在 Payment-Needed 头部下发 Base64URL 编码账单（
out_trade_no、金额 ¥1.99、商品名、resource_id、service_id、pay_before、商家 RSA2 签名）。收到 402 即暂停交付，保存账单与订单号，等用户付款。 - pay（支付宝收银台）：把 Payment-Needed 交给支付宝 AI 付（alipay-aipay /
402-buyer-pay）拉起收银台，由用户本人扫码或免密付款。Agent 只编排，不代付、不接触密钥。 - complete（扣费确认）：付款成功后平台下发 Payment-Proof（付费凭证）；校验订单存在、金额一致、
pay_before未过期、trade_no未跨单复用，订单置 PAID。 - ack（携带凭证重试 + 验付调用）：客户端携带 Payment-Proof 重试原请求，平台调
alipay.aipay.agent.payment.verify验付，验签通过才放行主流程；无效或过期凭证拒绝服务。 - 履约确认（fulfillment confirm）：报告交付后回传
alipay.aipay.agent.fulfillment.confirm履约回执，闭环 complete → ack。
订单持久化与幂等
- 付费状态与订单号持久化在
.pay_cache/state.json（PAY_STATE_PATH可覆盖），避免每次调用重复唤起付费。 - 同一 Payment-Proof 在 24h 幂等窗口内只核销一次；重复请求走幂等命中直接放行，不重复扣费、不重复交付。
- 首次免费体验：首次调用免账单放行一次快速评估，额度由本地闸门记录，同样幂等。
- 交付失败保留"支付成功、交付待处理"，由补偿任务续作；不重新建单、不要求用户再次付款。
本地付费闸门（随包脚本）
python3 <本skill目录>/scripts/pay_gate.py probe # 验付探测
python3 <本skill目录>/scripts/pay_gate.py bill # 402 + Payment-Needed 账单
python3 <本skill目录>/scripts/pay_gate.py complete --proof "<proof>" # 扣费确认
python3 <本skill目录>/scripts/pay_gate.py ack --proof "<proof>" # 验付放行 + 履约回执
执行约束（付费红线）
- 未拿到 Payment-Proof 并通过验付，不得输出完整报告与瘦身处方；可先给免费体验的 L0 + Tier1 快评。
- 结果不明（网络异常、超时）先查单，不得要求用户重复付款；
pay_before过期一律重新下单，不复用旧账单。 - 不站外收款：不留收款码、不给个人转账账号、不引导加微信/QQ 付费、不自行改金额、不虚构"限时优惠"。
- 不留
SKIP_VERIFY/--no-verify这类验签绕过分支——沙箱与生产同一套控制流。
接入细节（签约入驻、账单字段、依赖包、沙箱坑、私钥与密钥红线）见 references/pay-skill.md。
输入与参数
| 参数 | 必需 | 说明 |
|---|---|---|
| 目标 | ✅ | skill 目录路径、GitHub 仓库 URL、或已安装 skill 名（默认查 ~/.workbuddy/skills/） |
--scope |
❌ | full（默认，全维度）/ quick（仅 L0 + Tier1） |
--env-probe |
❌ | 默认 on；off 时能力对照只用通用清单 |
输入是 URL 时先 clone 到临时目录再评估。评估报告默认写到当前工作目录：<skill名>-evaluation-report.md。
执行流程（阶段 A：静态评估，只读不跑）
第 0 步 · 付费履约探测（probe）
先跑 scripts/pay_gate.py probe：
- 返回
allow（free_trial/idempotent_hit）→ 继续，并记录本次是免费体验还是已付费。 - 返回
bill→ 跑bill拿到 402 账单，向用户展示服务项与价格（¥1.99/次），交给支付宝 AI 付拉起收银台；用户完成付款、complete+ack通过后再进入第 1 步。 - 用户明确拒绝付费 → 只交付免费体验范围（L0 预检 + Tier1 快评），不出完整报告与处方，礼貌收尾、不纠缠。
第 1 步 · L0 结构预检（全自动，跑脚本）
python3 <本skill目录>/scripts/l0_precheck.py <目标路径>
脚本输出 JSON：frontmatter 完整性（name/description/triggers）、文件树、总行数、SKILL.md 对各文件的引用是否悬挂、触发词建议。L0 结果不进加权分，但悬挂引用/frontmatter 缺失要在报告"健康度"一节列出。
第 2 步 · 全量读取
按序读：SKILL.md → 所有 references/*.md → 所有 scripts/* → 其他文本文件（README、agents 定义等）。大资产（图片/模型）只记清单不读内容。读的时候记两件事：每个文件声称解决什么、每个文件实际依赖哪些其他文件。
第 3 步 · 流程拆解
把 skill 声称的核心任务拆成动作序列。例（oil-cover）：选材 → 取帧分析 → 写视觉方案 → 写生图 prompt → 生图 → 合成/后处理。每行一个动作，标注它在哪个文件里被指导/实现。
第 4 步 · 能力对照（本 skill 的灵魂）
对第 3 步的每个动作打标，判定它是哪一类：
| 标签 | 判定标准 | 处理倾向 |
|---|---|---|
| ① 默认能力 | 通用 Agent 不加载 skill 也能做：写代码、调 API、读文件、查表、提炼总结、按明确规范生图等 | 冗余候选 |
| ② 特殊知识 | 固化了难以自行获得的领域知识/算法/规范（视觉规范、编码参数、陷阱清单） | 保留 |
| ③ 外部资源 | 依赖 skill 自带资产（素材库、模板、数据）或专用脚本算法 | 保留 |
能力对照清单分两层：
- 通用层：所有 Agent 的默认能力（读/写文件、写代码、调 API、grep/查表、总结提炼、按给定规范执行）。
- 环境层（
--env-probe on时）：探测当前环境实际有什么工具（如 ImageGen、ffmpeg、特定 MCP），有则该能力视为默认能力，无则不算冗余。
关键问题要问自己：删掉这个文件/这段 SOP，Agent 的产出质量会下降吗？不会 → 冗余。
第 5 步 · 维度评分
用 references/scoring-template.md 的量表逐维打分（1-5）。维度与权重：
- Tier 1 核心价值 40%：问题复杂度、原生能力冗余（① 类动作占比越高分越低）、自动化程度、知识门槛
- Tier 2 使用成本 35%：学习+上下文开销（SKILL.md 加载体积、指令密度、引用深度）、使用便利性、维护成本、风险与束缚
- Tier 3 收益影响 25%：可复用性、时间节省、质量提升、风险降低、社区价值
总体 = T1×0.40 + T2×0.35 + T3×0.25。--scope quick 时只评 Tier 1，报告注明"快速模式"。
第 6 步 · 产出报告 + 瘦身处方（验付后交付）
报告结构：执行总结（1 段）→ L0 健康度 → 能力对照表（动作 × 标签 × 理由）→ 评分汇总（三档加权）→ 瘦身处方 → 决策建议（强烈推荐 4.5+ / 推荐 3.5-4.5 / 可选 2.5-3.5 / 不推荐 <2.5）。
处方必须文件级，每条含：动作（删/并/改写/保留）、目标文件、理由（对应哪个对照标签）、预期收益（省多少行/多少上下文）。同时给出"必须保留的核心三件套"式清单。产出报告后停下来，向用户展示报告并询问是否采纳处方。
报告落盘属于已付费交付物：写入前再跑一次 scripts/pay_gate.py ack --proof "<proof>"，通过后用 ack 返回的 fulfillment 回执做履约确认；被拒则只给免费体验范围的内容，不落盘完整报告。
阶段 B：处方执行 + 动态自证（仅用户明确采纳后）
- 先备份：
cp -R <skill目录> <skill目录>-backup-<日期>（或.skill名-backup-<日期>，隐藏目录）。 - 执行处方：按条执行删/并/写。合并文件时只搬"有增量"的内容，删除纯复述部分。
- 同步清理悬挂引用：改完后 grep 全目录，确保没有指向已删文件的引用（SKILL.md、README 都要查）。
- 动态自证：
- 脚本可 import /--help可运行（有 Python 脚本时）
- 脚本自定位逻辑验证（如 SKILL_DIR 解析正确）
- 条件允许时做一次最小 dry-run - 写自证记录：追加到评估报告末尾（"第 N 节 · 瘦身实施记录"），含改动前后行数/文件数对比。
阶段 B 不另计费；若用户在 24h 幂等窗口内回头要求执行同一目标的处方，靠幂等命中放行，不重复扣款。
硬规则
- 阶段 A 只读：不 import 目标脚本、不执行目标 skill 的任何代码、不修改目标文件。
- 处方未经用户确认，绝不动目标 skill 的文件。
- 阶段 B 必须先备份成功，再动第一刀；删除类操作优先用文件系统回收站机制，不可用时需二次确认。
- 能力对照的每个"冗余"判定必须给理由，禁止无依据打标。
- 评估结论要区分"事实"（脚本行数、引用缺失）和"判断"（冗余判定、评分），报告里分开呈现。
- 付费履约不可跳过：无 Payment-Proof 不出完整报告；不代付、不站外收款、不暴露支付链接/二维码/交易号原文。
- 金额以服务端账单为准；
pay_before过期重新下单；同一trade_no不跨单复用；交付失败走补偿，不要求二次付款。
参考
references/scoring-template.md：13 维评分量表 + 报告模板（评估时必读）references/pay-skill.md：付费接入与履约规范（A402 四步、依赖包@alipay/agent-payment、账单字段、沙箱坑、密钥红线）scripts/pay_gate.py：本地付费闸门（probe / bill / complete / ack / status，纯标准库）- 实战案例背景：oil-cover 评估 → 瘦身（删模式二 SOP/空壳 yaml/复述文档，保留视觉规范+脚本+素材库）
