技能包发布前体检（SKILL.md frontmatter）
何时用
- 要把 SKILL.md 打包发布到任意技能平台（SkillPie、SkillHub 等）之前。
- 平台报「未能解析技能元数据 / SKILL.md 缺少 name 或 description」，但你打开文件明明看到这两个字段。
- 批量发布多个技能，需要在上传前统一筛掉不合格的包。
核心认知：报错是假象
平台前端的解析流程几乎都是：
正则抠 frontmatter → YAML 解析 → if (!obj || !obj.name || !obj.description) 报错
关键在于——YAML 解析抛异常会被 catch 吞掉，然后和"真的缺字段"走同一个报错分支：
let m = text.match(/^---[\t ]*\r?\n([\s\S]*?)\r?\n---[\t ]*(?:\r?\n|$)/);
if (m) { try { return yaml.load(m[1]); } catch { return null; } } // ← 异常被吞
...
if (!i || !i.name || !i.description) {
console.warn("SKILL.md frontmatter缺少必填字段(name或description)"); // ← 误导性提示
return null;
}
所以：看到"缺少字段"的报错，第一反应不是补字段，而是查 YAML 是否能解析。
三类致命错误（按出现频率）
| # | 错误 | 触发写法 | js-yaml 报错 |
|---|---|---|---|
| 1 | 重复键 | 适配脚本"追加"而非"替换"字段，导致 display_name 出现两次 |
duplicated mapping key (11:1) |
| 2 | 未加引号的值含半角 : |
description: ...with correct assertions: check the... |
bad indentation of a mapping entry / mapping values are not allowed in this context |
| 3 | Tab 缩进 | frontmatter 里用 Tab 排版 | bad indentation of a mapping entry |
陷阱：全角 vs 半角
中文文案里写「说明：xxx」用的是全角冒号 ：，YAML 完全合法。
但中英混排时很容易混入半角冒号 + 空格（如 assertions: check），这个必炸。
判断标准：值里只要出现半角 : 就加引号，不要去数后面有没有空格。
陷阱：自研适配脚本反而制造问题
为了适配平台去"补字段"时，若实现成追加而不是替换，就会引入重复键（第 1 类错误）。
实测：本来只是 tags 格式不同的包，被"适配脚本"修完反而全部发布失败。
宁可不适配，也不要追加式适配。
排查方法：本地复现平台解析器
不要靠猜，把平台的解析逻辑搬到本地跑一遍。
第 1 步：拿到平台真实的解析代码（可选但最准）
浏览器打开发布页 → F12 → Network → 找到页面 JS chunk → 搜 frontmatter 或 SKILL.md，能直接看到正则与校验逻辑。
第 2 步：用同一套正则 + 同一 YAML 库验证
const RE = /^---[\t ]*\r?\n([\s\S]*?)\r?\n---[\t ]*(?:\r?\n|$)/;
const m = RE.exec(text);
try {
const o = yaml.load(m[1]);
if (!o || !o.name || !o.description) console.log('缺字段');
} catch (e) {
console.log('真正的病根: ' + e.message); // ← 真相在这里
}
第 3 步：对照实验定位到"内容问题"还是"结构问题"
拿一个确认能成功的 SKILL.md 内容，塞进失败的 zip 结构里重新打包上传：
- 成功 → 是 SKILL.md 内容问题
- 仍失败 → 是 zip 结构 / 打包方式问题
用法
检查（只读，不改文件）
python scripts/fm_preflight.py check <SKILL.md | 技能目录 | skill.zip> ...
退出码 0 = 全部可发布，2 = 存在问题。
修正（原地规范化，自动备份 .bak_<时间戳>）
python scripts/fm_preflight.py fix <技能目录> ...
修正动作：
- 去重（首次出现的为准），按固定键序重排
- 风险值用 json.dumps 加双引号（YAML 双引号标量兼容 JSON 转义）
- tags 块序列 → 行内数组 [a, b, c]（对极简解析器更友好）
- 正文一字不改
打包
python scripts/fm_preflight.py pack <技能目录> <输出目录>
自动排除 .bak_*、__pycache__、.git、node_modules。
权威交叉验证（需 js-yaml）
npm i js-yaml # 装在任意 workspace
node scripts/fm_xcheck.js 路徑/SKILL.md ...
frontmatter 安全写法速查
---
name: my-skill # 小写连字符，唯一
display_name: 我的技能 / My Skill
description: "中英混排时必须加引号，尤其值里出现半角冒号: 像这样"
summary_zh: 一句话中文简介
summary_en: One-line English summary
version: 1.0.0
category: automation
tags: [alpha, beta, gamma] # 行内数组，别用块序列
---
规则：
1. 值里出现半角冒号 / # / 引号 / 反引号 → 一律加双引号。
2. 每个键只出现一次。 补字段用替换，不用追加。
3. 缩进只用空格。
4. tags 用行内数组。
5. name 与 description 是各平台通用的两个必填项，其余字段看平台。
踩坑速查
- 报"缺少字段"但字段都在 → 十有八九是 YAML 解析异常被吞，先跑
check或 js-yaml 验一遍。 - 改完 BOM / CRLF / 压缩方式都没用 → 方向错了，问题在 frontmatter 内容本身，不在编码。
- 适配脚本跑完反而全挂 → 检查是否追加了重复键。
- 平台列表接口返回某字段 null 但页面显示正常 → 可能只是列表接口没回显该字段，去看公开详情页确认，别急着改。
- 抓发布请求体：multipart 时 Playwright 的
request.postData()常为空，改用page.addInitScript劫持FormData.prototype.append记录键名；想只抓包不落库就配合page.route(... route.abort())。 - 响应体别截断：抓 API 响应时
slice(0, 700)会让JSON.parse失败，进而把"成功"误判成"失败"。 - 平台没有更新接口：
PATCH/PUT /api/skills/{id}常返回 405，说明只能整包重发；重发前先确认会不会产生同名重复条目。
相关技能
- 需要真实登录态才能上传 →
headless-browser-cdp-automation（DPAPI 解密 cookie 注入无头实例，不打断用户浏览器）
