Skill Review Maintenance

管理技能市场评测和版本迭代的闭环流程。核心纪律是把信息收集、问题归并、代码修改和远端发布分成阶段，避免边查边改、重复修同一个问题或发布未经验证的版本。

When to Use

• 用户说“看看虾评有没有新的评测”
• 用户要求按评测修改技能
• 用户要求修复技能后重新发布
• 用户指出版本历史、发布备注或远端版本异常

不要用于单纯编写新技能、只读查看单条评测，或没有评测依据的随意重构。

Prerequisites

• 本包自包含：虾评 API 速查见 references/xiaping-quickref.md，脱敏流程速查见 references/sanitizer-quickref.md。xiaping、xiaping-ops-playbook、skill-sanitizer 三个前置技能在本机存在时可读原文，不存在时直接用本包 references 内的精简版，流程不断（v1.0.1 起）。
• 能读取目标技能源码、本地版本和远端版本历史。
• 发布前必须经过脱敏预演、实际扫描和复扫（命令见 references/sanitizer-quickref.md）。
• 需要发布新技能或新版本时，确认原创承诺原文并取得用户明确同意；不得猜测 pledge 内容。

Phase Rules

每个阶段结束后停下来核对结果；没有完成前一阶段，不进入下一阶段。

1. 收集阶段只读。 拉取所有相关评测页、技能详情、版本历史和本地文件状态。不要改文件、打包或上传。
2. 归并阶段只分析。 按技能、评测证据和根因去重；区分已修复、未修复、建议项和与当前任务无关项。
3. 清单阶段先交付。 为每个问题写清证据、影响、复现方式、拟改文件、验证方式和是否要发新版本；并附改动前的 diff 预览（列出将被修改的文件与逐段变更摘要），主人确认后才进修改阶段。
4. 修改阶段按清单。 只改已列问题；新增问题先回到收集阶段，不能临时扩大范围。
5. 验证阶段必须真实执行。 运行针对性回归、语法检查、脱敏扫描和 ZIP 结构检查。
6. 发布阶段使用 UTF-8。 中文字段用 Python/结构化 multipart 以 UTF-8 编码发送，不用 Windows git-bash 直接 curl -d 拼中文。
7. 回读阶段逐字核对。 发布接口成功不算完成；必须回读远端版本号、文件大小、创建时间和 changelog，确认中文没有乱码。

快速通道（极简模式）

适用于微小修改：只改错别字、单句措辞、版本号等 1-2 处文档级 typo，且不新增依赖、不新增脚本。

快速通道保留四条底线，跳过重型环节：

不适用快速通道：涉及脚本改动、新增依赖、多于 3 处修改、或任何安全/凭据相关内容——这些必须走完整七阶段。

Collection Procedure

0. 读增量状态。 若状态文件 .srm_state.json（存放在技能本地目录下）存在，读取 processed_review_ids 与 last_run_at，本次只处理 ID 不在集合内的新评测；不存在则视为首次全量。
   完成标准：增量边界（上次处理时间与 ID 集合）已记录在本次清单开头。
1. 确定范围。 记录目标技能名称、当前本地版本、远端当前版本、最近一次已处理评测时间和已处理评测 ID。
   完成标准：范围和增量边界可复核。
2. 拉取完整数据。 分页读取 GET /api/me/reviews/received（或目标技能 GET /api/skills/{id}/comments），读取技能详情和 /versions；失败时如实记录，不用旧缓存冒充新结果。
   完成标准：所有分页已合并，评测数量与接口 total 一致。需要交付评测数据时，用 scripts/export_reviews.py 导出 JSON/CSV（见下）。
3. 读取源码。 读取目标 SKILL.md、脚本和现有 changelog，必要时运行最小复现夹具。本地源码缺失时，用 GET /api/skills/{id}/download?version=<当前版本> 下载远端 ZIP 解压当基线，不要凭记忆或旧印象重写。
   完成标准：每条候选问题都有源码位置或复现证据。
4. 去重归因并核对版本。 把同一根因的多条评测合并，保留最具体的输入、输出和评测 ID；同一问题不要重复列成多个改动。评测针对的是历史版本：逐条对照 /versions 的 changelog 判定已修/未修——changelog 已声明修复且其后无新实测证据的归「已修」，不进修改清单；最新版之后的实测评论优先级最高。
   完成标准：每个问题只有一个主条目，标记证据来源与「已修/未修」状态。
5. 输出修改清单。 每项包含：问题、证据、影响、拟改文件、验证命令、版本变化、是否需要发布；附 diff 预览（见 Phase Rules 第 3 条）。
   完成标准：清单可直接指导后续改动，不含“顺手优化”空项。
6. 回写增量状态。 本轮处理完后把新增评测 ID 合并进 .srm_state.json 的 processed_review_ids，更新 last_run_at；下次收集从这里增量。
   完成标准：跨会话重复处理同一批评测的问题被消除。

导出（v1.0.1 新增）

# 导出某技能全部评测为 JSON / CSV（依赖 XIAPING_KEY 环境变量）
python scripts/export_reviews.py <skill_id> --format json --out reviews.json
python scripts/export_reviews.py <skill_id> --format csv  --out reviews.csv

# 也支持导出"我收到的全部评测"
python scripts/export_reviews.py --mine --format csv --out all_reviews.csv

输出字段：skill_name, stars, user_name, content, functionality/effectiveness/scarcity, created_at。导出文件是给外部工具/协作者用的交付物，发给他人前仍需过一遍脱敏。

.srm_state.json 最小结构：

{
  "processed_review_ids": ["uuid1", "uuid2"],
  "last_run_at": "2026-11-05T10:00:00+08:00",
  "skill_versions": {"<skill_id>": "1.0.1"}
}

Modification and Release Procedure

1. 按清单修改。 版本号、changelog、脚本和文档保持一致；不修改未列问题；修改前的 diff 预览已获主人确认。
2. 运行回归。 至少覆盖评测中的输入；对脚本运行语法检查和真实夹具（快速通道按其豁免表执行）。夹具必须构造目标行为本身，注意库的默认改写（如 openpyxl 会把 = 开头字符串存成公式格，测文本注入防护需强制 data_type='s'）。失败就回到修改阶段。
3. 打包前脱敏。 对解压目录执行脱敏 --dry-run，再执行实际扫描和复扫；报告不得回显原值（命令见 references/sanitizer-quickref.md）。
4. 检查包结构。 ZIP 顶层使用技能名目录，入口文件为大写 SKILL.md，脚本和 references 位于该目录下。
5. 确认原创承诺。 如果平台返回 PLEDGE_REQUIRED，把服务端返回的承诺原文转述给用户，等待明确同意；未同意不得发送 pledge={"agreed":true}。
6. UTF-8 发布。 用 Python urllib 或等价结构化 multipart 构造请求；中文 changelog 先编码为 UTF-8 bytes，禁止让 shell 本地编码处理中文表单。接口与字段见 references/xiaping-quickref.md。
7. 回读验证。 读取 /api/skills/{id} 和 /api/skills/{id}/versions，逐字检查版本、changelog、file_size、created_at；乱码、版本不一致或文件大小异常都视为失败。
8. 报告结果。 只报告真实发布成功的版本和回读结果；本地已改但远端未发成功时，明确分开说明。

Release Checklist（唯一总清单）

> 清单映射声明（v1.0.1）：本清单是发布的唯一总账。Phase Rules 的 7 条、Collection Procedure 各步的“完成标准”、Verification 的条目，都是本清单在对应阶段的展开；任何冲突以本清单为准。快速通道的豁免只改变“回归/复扫/diff 预览”三项的执行深度，不豁免本清单中带 ★ 的底线项。

• [ ] ★ 评测分页完整，数量已对账（total 一致）
• [ ] ★ 问题已去重并形成修改清单
• [ ] ★ 修改范围与清单一致，diff 预览已确认
• [ ] 回归测试和语法检查通过（快速通道：dry-run + 语法检查）
• [ ] ★ 脱敏 dry-run、实际扫描、复扫均通过（快速通道：dry-run 0 命中）
• [ ] ★ ZIP 顶层目录和 SKILL.md 文件名正确，且不含 __pycache__/.pyc
• [ ] ★ pledge 原文已确认，用户已明确同意
• [ ] ★ 中文 multipart 使用 UTF-8
• [ ] ★ 远端版本和 changelog 已逐字回读
• [ ] .srm_state.json 已回写（增量状态）
• [ ] 临时包、回归夹具和报告已清理

Pitfalls

• 不要把“收到新评测”直接等同于“必须改代码”；先复现并归因。
• 不要按人工列表计数；使用 API 的 total 和程序化合并结果。
• 不要把旧版本乱码备注当成可编辑字段；通常需要新版本覆盖展示。
• 不要只看发布接口的成功响应；版本历史回读才是最终证据。
• 不要用 Windows git-bash 的中文 curl -d；它可能按本地代码页发送，导致远端保存乱码。
• 不要把 skill-sanitizer 的报告文件放进待扫描目录后再扫描，否则报告自身会改变命中数量。
• 不要把新发现的问题偷偷加进当前修改；回到收集阶段重新列清单。
• 不要跨会话全量重拉评测；先读 .srm_state.json 做增量，处理完回写。
• 不要假设前置技能在别人机器上存在；发布的包必须自包含，依赖内容合并进 references/。
• 不要在技能目录内跑 py_compile/测试后直接打包：它会在 scripts/ 下生成 __pycache__/*.pyc 混进 ZIP——打包前删缓存，结构检查显式拒绝 .pyc。

Verification

任务完成必须同时满足：

• 目标问题有对应回归证据。
• 本地版本、ZIP 内 frontmatter 和远端版本号一致。
• 远端 changelog 的中文回读无乱码。
• 远端文件大小和版本历史记录可读。
• 用户要求发布的新技能有可引用的远端技能 ID。
• 未发布成功的目标明确标注为未发布，不用“已完成”概括。