Skills Release Manager

一份 canon 源,按平台 profile 构建出各平台产物,上传前本地拦下所有驳回原因,上传后回写事实做对账。

铁律

只改 canon/。dist/ 是产物,禁止手改。 手改会被 status 标成 MISMATCH。
版本必须递增。 平台只接受比线上更高的 semver;canon 改了内容而版本没动,package 直接报 error。
description 是唯一触发开关。 正文在技能命中前不加载;只改正文不改描述,等于没改。
上传是手工的,但回写不是。 上传成功必须立刻 record,否则矩阵永远显示 UPLOAD。
驳回原因要沉淀回 profile,而不是改 22 个技能。

仓库结构

hub/
├── canon/<skill-id>/          事实源
│   ├── skill.yaml             元数据:四语名称与描述、version、category、触发边界
│   ├── BODY.md                正文,不含 frontmatter
│   ├── references/ scripts/ assets/
│   └── overrides/<platform>.md  仅该平台需要的追加片段
├── platforms/<platform>.yaml  平台适配器:字段白名单、上限、目录层级、打包形态
├── dist/<platform>/...        构建产物(只读)
└── release/
    ├── manifest.json          N×M 发布事实:线上版本/canon_sha/dist_sha/驳回史
    ├── packages/*.zip         上传包
    └── checklist/*.md         手工上传检查单(含表单文案)

命令

全部在 hub 仓库根运行,H="python3 <skill>/scripts/hub.py"。

| 命令 | 用途 | | --- | --- | | $H init --path DIR | 建仓库骨架 + 预置平台 profile | | $H import SRC --platform PID [--overwrite] | 从现有平台产物反向抽取 canon | | $H new SKILL_ID | 新建 canon 技能骨架 | | $H build [SKILL\|--all] [--platform all\|a,b] | canon 构建到 dist | | $H validate [SKILL\|--all] [--platform ...] | 上传前硬规则校验,error 必须清零 | | $H package [SKILL\|--all] [--platform ...] | 构建+校验+出 zip+生成检查单 | | $H bump SKILL patch\|minor\|major | 递增版本号 | | $H record SKILL --platform PID --status published\|rejected [--note 原因] | 回写上传事实 | | $H status [SKILL] | N×M 对账矩阵;平台多到挤不下时给技能名看逐平台明细 | | $H survey | 漂移 + 驳回史 + 待核实事项 + 产物残留 | | $H profiles | 打印每个平台的必填字段、白名单、上限、路径与打包规则 | | $H clean [--platform PID] | 清 dist |

矩阵状态:OK 线上一致 · DRIFT canon 已改未重建 · UPLOAD 包已就绪待上传 · FAIL 校验未过 · REJECT 被驳回 · MISMATCH 产物被手改 · skip platforms_exclude · - 未构建。

会话工作流(用户拖 zip 进来即开工)

用户的操作只有三步:拖技能 zip 唤醒 → 拖 hub 仓库 zip → 收包上传。中间全部由本技能完成。

唤醒:收到本技能 zip,解压后用 scripts/hub.py 作为唯一入口。不要重写流水线逻辑。
拿到仓库:解压用户上传的 hub zip。没有 hub 就 init + import 各平台现有产物建立 canon(工作流 A)。
先校验:validate --all。error 必须清零,不要带 error 出包 —— 出包只是把驳回提前到本地。
改与发:bump → package --all --out DIR。DIR 必须是用户能下载到的目录(沙箱里只有 output/ 下的文件用户能拿到,其他路径等于没给)。
呈现:把每个平台的 zip 与其检查单逐个展示给用户,说明上传顺序与表单字段位置。不要只说"已生成"。
等回执:用户上传后问清结果,record --status published;被驳回要照抄平台原文到 --note。
交还状态:bundle --out DIR 导出 hub-state.zip(canon + platforms + manifest + 检查单)并给用户,让他覆盖回本地 git 提交。 沙箱是临时的:manifest.json 里的发布事实不会自动留存,这一步省掉,下次会话矩阵就是空的,一切从头猜。

产物 dist/ 与 release/packages/ 不入状态包 —— 可重建,且体积大。

本技能自身也可以作为一条 canon 技能纳管(canon/skills-release-manager/),升级它就走同一条流水线:bump → package → 上传各平台 → record。

工作流

A. 首次接管已有技能(一次性迁移)

$H init --path DIR 建仓库。
对每个平台各跑一次 $H import <该平台导出的技能目录> --platform <pid>。同一技能在不同平台正文不一致时,工具不会覆盖 canon,而是写进 overrides/<platform>.md 并提示人工合并 —— 这正是各平台已漂移的证据。
$H validate --all 看每个技能缺哪些字段(canonical 迁移后最常缺 display_name_en、description_zh、trigger_boundary)。
$H record 把各平台线上现状登记进 manifest,$H survey 得到基线矩阵。

B. 日常更新一个技能

改 canon/<id>/BODY.md 或 skill.yaml。
$H bump <id> patch(措辞/修复)、minor(新增能力)、major(改名或删能力)。
$H package <id> --platform all。
打开 release/checklist/<pid>-<id>.md,把包传上平台,表单字段直接复制。
每个平台上传后:$H record <id> --platform <pid> --status published。
到平台新会话里实际触发一次该技能,确认命中。改了描述才算生效。

C. 被平台驳回

$H record <id> --platform <pid> --status rejected --note "平台原文"(原文照抄,是后续修 profile 的依据)。
判断根因属于哪一层:内容问题改 canon;规则问题改 platforms/<pid>.yaml 的 require/allow/limits/layout/checks。
修完重跑 $H package <id> --platform <pid>,并把新规则记入 references/troubleshooting.md,避免在其余技能上重复踩。

D. 接入新平台

复制一份最接近的 platforms/<pid>.yaml,改 id(必须与文件名一致)。
按 references/profile-schema.md 填 6 个维度:规范族、frontmatter、上限、布局层级、打包、提交表单。
未核实的写进 todo: 列表,survey 会一直提醒。
先拿一个技能跑 $H package <id> --platform <newpid>,解压核对目录层级与 frontmatter,再批量。

E. 巡检

$H status 看全局,$H survey 看细节。任何非 OK/skip 的单元都要给出下一步动作,不要停在"看起来都发了"。

F. 扩规模

平台数和技能数都不是常量,脚本里没有硬编码:

加技能 = canon/ 下多一个目录。矩阵自动多一行,package --all 自动覆盖。
加平台 = platforms/ 下多一个 yaml(见 D)。矩阵自动多一列,构建/校验/打包/检查单立刻生效。
临时下线某平台 = 该 profile 里 enabled: false,--platform all 会跳过它。
某技能不发某平台 = skill.yaml 的 platforms_exclude,矩阵显示 skip。
平台多到矩阵显示不下时用 $H status <skill> 看该技能的逐平台明细(线上版本、构建版本、包路径、驳回史)。
init --force 会用技能自带的模板覆盖 platforms/*.yaml,你在里面调过的白名单与上限会丢失。仓库在 git 里,改完记得提交;不需要新增平台时别用 --force。

参考资料

profile 字段含义与写法:references/profile-schema.md(接入新平台或修规则时读)
canon 元数据字段规范:references/canon-format.md(新建/迁移技能时读)
四家平台已知差异:references/platform-notes.md(动手构建前确认约束)
驳回原因与修法:references/troubleshooting.md(校验报错或平台驳回时读)