--- name: soia-meta-skill-release description: 域仓正式发版（dev→main、tag、Release、notes、CHANGELOG）与发布收尾：市场 pin 刷新、客户端更新、旧名清理、WorkBuddy 专家安装、dev 快照试装。触发：「正式发版」「发布技能」「更新插件」「技能发布收尾」「装到 WorkBuddy」「试装 dev」 version: 5.2.0 created_at: 2026-07-22 21:26:01 updated_at: 2026-08-06 17:30:00 created_by: gpt-5.6-terra updated_by: claude-fable-5 dependencies: optional: [soia-meta-sync-skills] --- # soia-meta-skill-release 在技能 PR 已 merge 后完成本机发布收尾：安装或更新变更技能、清理旧名、补全 Codex 链接、同步消费者目录，并用 lock 与版本进行独立对账。触发词：**「发布技能」**、**「发布 X」**、**「技能发布收尾」**、**「release skill」**。 ## 客户可读说明 ### 这个技能可以做什么 | 客户想要 | 技能会做 | 客户能看到 | | --- | --- | --- | | 发布 merge 后的一个或多个技能 | 安装、更新、软链同步并核对 lock/版本 | 六列发布回执 | | 重命名或删除旧技能 | 移除旧安装与全部受管目录残留 | 已清理数量与零残留验证 | ### 客户如何使用 先确认目标技能已 merge 到远端仓库；本技能不执行 git、PR、merge、push 或发布远端状态。再提供仓库、技能名单和可选旧名： ```bash python3 skills/soia-meta-skill-release/scripts/release_skills.py \ --repo \ --skills \ --removed \ --dry-run ``` 复核 dry-run 后，移除 `--dry-run` 执行。默认面向 `claude-code,codex`，可用 `--agents` 覆盖。版本核对按以下顺序解析本地 checkout： 1. `--repo-dir ` 显式路径； 2. 当前进程的 `SOIA_SKILL_REPOS_ROOT/`； 3. 私有 YAML：`--config` → `SOIA_META_SKILL_RELEASE_CONFIG_FILE` → `~/.config/soia-skills/soia-meta-skill-release/config.yml` 中的 `env.SOIA_SKILL_REPOS_ROOT`； 4. v1 私有配置目录只读回退（会向 stderr 输出建议的 `mv` 迁移命令）； 5. 旧版维护者本地目录约定，仅作弃用中的向后兼容回退。 仓库内部仍须采用 `skills//SKILL.md` 布局。对未来新增仓库，只要 `--repo` 提供对应的任意 `/`，无需修改脚本。 ### 依赖与安装 ```bash claude plugin marketplace add soia-team/soia-open-skills ``` ```bash claude plugin install soia-meta@soia ``` 只要这一个技能时，可用 npx 路线。注意技能会落进共享真源 `~/.agents/skills`；若同时装了插件，同一技能会出现两份索引且各自漂移，建议二选一： ```bash npx skills add soia-team/soia-open-skills -g -a '*' -s soia-meta-skill-release -y ``` | 依赖 | 类型 | 用途 | 缺失时怎么处理 | | --- | --- | --- | --- | | `npx skills` | 强依赖 | 安装、移除、更新并维护 lock | 停止并报告失败步骤 | | `soia-meta-sync-skills` | 可选依赖 | 仅 `npx` 模式第 5 步用它同步 SOIA 与 WorkBuddy 软链；默认的 `plugin` 模式不调用 | 走 `npx` 模式时先安装该技能再重试；`plugin` 模式无影响 | | Python 3 | 强依赖 | 执行发布脚本 | 安装 Python 3 后重试 | | PyYAML | 可选依赖 | 读取私有 `config.yml` | 传 `--repo-dir` 或使用当前进程环境变量 | ### 私密信息与中间数据 按本仓 `DATA_STORAGE_SPEC.md`，本技能只读写各 AI 技能安装目录及 `~/.agents/.skill-lock.json`；可选读取仅含本地 checkout 根目录的私有 v2 `config.yml`。复制 [路径配置模板](assets/config.example.yml) 后再填写；不要为了这一个设置修改 `.zprofile`，也不读取或保存凭据、缓存或中间文件。终端回执只显示技能名、版本、链接状态和失败步骤。 ### 日志与完成回执 每一步失败即停止，并输出已到达的步骤和下列六列回执： | 技能 | 动作 | 仓库版本 | 装机版本 | 软链(三处) | 结果 | | --- | --- | --- | --- | --- | --- | | `` | install/update/remove | `` | `` | agents / claude / codex | ok / removed / failed | ## 工作流 交付走插件市场，`--install-mode` 默认 `plugin`。**默认不会向 `~/.agents/skills` 安装任何技能**——那样会与插件副本并存，同一技能出现两份索引且各自漂移。 ### `plugin` 模式（默认） 1. 有 `--removed` 时清理 `.agents`、`.claude`、`.soia`、`.workbuddy`、`.codex`、`.pi/agent` 六处同名残留。改名清理在两种模式下都执行：残留的旧名副本会盖过插件更新继续应答。 2. 读取仓库版本填入回执；装机版本记 `-`，软链记 `plugin`，结果记 `published`。 3. 打印用户实际收到改动还需要的步骤：bump 双份 `plugin.json` 的 version → 元仓重生成市场清单并提 PR 合并 → 客户端 `plugin update` → `plugin details` 验证。 ### `ask` 模式（`--install-mode ask`，交互式选择） 需要交互终端。执行时询问客户是否安装到本地：输入 `y` 则按 `--agents` 指定的目标走 npx 安装（可现场覆盖 agents 列表，如 `claude-code,pi`）；输入 `n`/回车则等同 `plugin` 模式，只发布不安装。非交互环境（agent 执行脚本）下使用 `ask` 会报错并提示改用 `plugin`/`npx`。 ### `npx` 模式（`--install-mode npx`，显式 opt-in） > ⚠️ **2026-08-06 规范定稿后的边界**：各 agent 技能空间一律**实体安装**且必须 > **可再现**（lock 登记来源）。由此：本模式只允许逐技能窄命令 > `npx skills add -g -a --copy -s -y`（多技能用重复 `-s`， > 逗号列表会被当成单个名字；qwen 的 id 是 `qwen-code`）；**第 3 步的全量 > `npx skills update -g -y` 已禁用**——它对 lock 内全部技能向所有 agent 目录 > 广播重装，等效被禁的 `-a '*'`；第 4/5 步的软链同步与实体规范冲突，一并停用。 > `release_skills.py` 尚未按此改造，改造完成前不要使用其批量步骤。 1. 逐项执行 `npx skills add -g -a --copy -s -y`；`--agents` 支持任意 `npx skills -a` agent id，如 `claude-code`、`codex`、`pi`（Pi 安装到 `~/.pi/agent/skills`）、`qwen-code`。 2. 有 `--removed` 时执行同参 `npx skills remove`，并清理五处残留。 3. ~~执行 `npx skills update -g -y`~~（已禁用，见上方警告；更新改为对目标技能重跑第 1 步）。 4. ~~软链补齐 Codex~~（已停用；Codex 走插件市场）。 5. ~~调用 `soia-meta-sync-skills` 同步 soia,workbuddy~~（已停用；WorkBuddy 走 `install_workbuddy_experts.py`）。 6. 对账 `~/.agents/.skill-lock.json`：所有新技能必须来自 `--repo`，旧名必须零残留。 7. 按 `--repo-dir` → 进程环境 → 私有 v2 config → 只读 v1 config 回退 → 旧版兼容目录的顺序解析 checkout，并对比每项 `SKILL.md` version 与装机 version。 ## 正式发版（dev 分支制） > **执行前置：必须有客户当次的明确授权。** 正式发版是对外动作——tag、Release、 > 发版 PR、市场 pin 刷新都会改变外部用户收到的内容。客户要求修 bug 或加功能 > **不等于**要求发版：改动合进 `dev` 即算交付完成，报告「已进 dev，待你决定 > 是否发版」并停下。多 AI 并行时未经协调的发版会把他人未完成的工作一并送出 > （2026-08-03 实际发生过）。仅 `--dry-run` 预演无需授权。 域仓采用双通道：`dev` 承接日常合并（版本带 `-SNAPSHOT` 声明下个目标，期间不变， 状态身份用 commit SHA）；`main` 永远等于最新正式版。客户说**「正式发版 X」**时执行： ```bash python3 skills/soia-meta-skill-release/scripts/formal_release.py \ --repo soia-team/<域仓> --repo-dir <本地路径> --summary "<一句话摘要>" --dry-run ``` 复核 dry-run 计划后去掉 `--dry-run` 执行。脚本按序完成五步，每步失败即停： 1. 定稿 PR → dev：各 manifest（claude/codex/codebuddy 独立轨道）摘掉 `-SNAPSHOT`， 并把 Release Notes **前插 `CHANGELOG.md`**——发版即更新、与 GitHub Release 同源， CHANGELOG 跟着插件缓存走，装了插件的用户离线可读 2. **快进推送 dev → main**：`git push origin :refs/heads/main`， main 与 dev 指向同一提交 3. `v` tag 打在该提交并推送 4. `gh release create`（标题 `<插件名> v`） 5. 重开列车 PR → dev：各 manifest **+patch** 进入 `-SNAPSHOT` 随后继续本技能既有的 pin 刷新与客户端更新流程（下节）。 ### 版本号怎么定 重开列车默认 **+patch**（1.11.0 → `1.11.1-SNAPSHOT`）——刚发完版还不知道下一版 是修 bug 还是加技能，默认 +minor 等于预判「必有新功能」，实证会虚高：v1.11.0 实 际只修了一个显示缺陷，按语义应是 1.10.1。与 Maven release 惯例一致。 **发版前按内容确认版本**：加了新技能/新能力 → 手工把 dev 改成 minor（如 `1.12.0-SNAPSHOT`）；有破坏性变更 → major。改完再跑发版，脚本以 dev 的版本为准。 **技能自身版本要单独 bump**：`plugin.json` 是插件（交付单元）的版本，每个 `skills//SKILL.md` 的 frontmatter `version` 是该技能自己的版本，两者独立。 改了某个技能的正文或脚本，就要 bump 那个技能的 `version` 和 `updated_at`—— CI 的 `check_skill_versions.py` 会拦（2026-08-03 漏过一次：改了 skill-release 的 脚本与正文，技能版本却停在 4.1.0）。 ### 三条不可回退的发版约束（都由事故推导，勿改） 1. **dev→main 用快进推送，不走 PR 合并**。PR 的三种合并方式都会在 main 上造出 dev 没有的提交——squash 连祖先关系都断（下次发版必冲突，2026-08-03 pkm/media 实际发生）、merge 留个 merge 提交、rebase 重写 SHA。只有快进能让 **main 与 dev 指向同一提交**，分叉在结构上不可能发生。 - 前提一：`main` 必须是 `dev` 的祖先。脚本发版前校验，不满足即中止并要求先 sync main→dev（有人绕过流程直接改 main、或历史上走过 merge/squash 时会不满足）。 - 前提二：dev HEAD 的 `audit` 结论必须是 success。脚本显式查 check-runs—— **快进不是跳过检查**，推上去的就是那个已通过检查的提交。 - 仓库设置：`main` 的 `enforce_admins` 需关闭，否则受保护分支拒绝直接推送。 其余保护（PR 要求、`audit` 必过）对普通改动照常生效。 2. **定稿与重开列车之间是不变量破窗期**：第 1 步摘掉 dev 的 `-SNAPSHOT` 后，直到 第 5 步重开前，dev 都处于违规状态。中断在此区间会静默留下「dev 停在正式版本 号」。脚本收尾有断言兜底，但**人工介入或中断后必须自查**。 3. **发布门禁**：元仓 `generate_marketplaces.py` 读取待 pin 提交的 manifest，含 `-SNAPSHOT` 直接拒绝生成清单——SNAPSHOT 结构上到不了任何客户端。 ### 全生态批量发版实测补充（2026-08-06，10 仓一次发齐踩出来的） 1. **元仓自己发版时，定稿 PR 必须同步带上派生物刷新**。域仓 main 先发、元仓后发， 元仓定稿 PR 的 `audit` 会依次撞 marketplace freshness 与 skill-pages freshness （实测连撞两次 CI）。正确做法：在定稿分支上补跑 `generate_marketplaces.py`、 `generate_router_index.py`、`generate_skill_pages.py`，且 push 前把 audit 的 全部检查步骤在本地预跑一遍绿了再推。 2. **域仓默认分支必须是 main**。soia-private-corp 曾默认指 dev，codex `marketplace add` 按默认分支拉清单，装出 `-SNAPSHOT`。用 `gh repo edit --default-branch main` 修正后重装即恢复正式版。 3. **WorkBuddy 正式安装前，所有域仓本地 checkout 必须切到 main**。 `install_workbuddy_experts.py` 复制的是 checkout 当前分支；发版后 dev 已开 下一班列车（SNAPSHOT），停在 dev 会把 SNAPSHOT 装成专家。 4. **发版后重建 dev（客户要求「删 dev 从 main 重拉」时）**：开源仓 dev 保护 禁删也禁强推，流程是 GET 保护配置存档 → PUT `allow_force_pushes=true` → 强推 main+新列车 → 立即 PUT 关回 → 验证远程 sha 一致且保护恢复。免费版 私有仓无 classic protection API（GET 返回 403），说明本就无保护，直接删/推。 5. **zsh 手动推 refspec 的坑**：`"$sha:refs/heads/main"` 里的 `:r` 会被 zsh 当作修饰符吞掉，产生损坏的 refspec；必须写 `"${sha}:refs/heads/main"`。 6. **含 feat 的仓发版前把列车提为 next-minor**（本节上文已有规则）：批量场景 先按 `git log main..origin/dev` 统计各仓 feat 提交数分组，一次脚本完成 6 仓 minor bump 再逐仓跑 `formal_release.py`，比逐仓临时判断稳。 ### 体检：随时可跑，盘点必跑 ```bash python3 scripts/generate_marketplaces.py --help >/dev/null # 元仓 checkout 内 python3 scripts/check_version_trains.py --repos-root <各仓父目录> ``` 查两件事：①版本列车不变量（dev 带 `-SNAPSHOT`、main 不带）②下次发版能否干净 合并。**报告生态状态时必须验这两个不变量，不能只抄版本号**——2026-08-03 的两次 漏判都源于「只看数值对不对，没验规则成不成立」。 ## 试装 dev（本地验证快照版） 触发词：**「试装 dev」**、**「本地装 dev 版」**。dev 快照只做本地验证，绝不常驻安装。 - **Claude Code（推荐，会话级）**：`claude --plugin-dir <域仓本地路径>` 启动会话， 当前检出（dev 时即 SNAPSHOT 版）被加载为插件，退出即卸、不污染安装态；可叠加 多个 `--plugin-dir`。只验证不开会话时用 `claude --plugin-dir <路径> plugin details <插件名>`（`--plugin-dir` 必须在 `plugin` 子命令之前）。 - **WorkBuddy**：本地 checkout 切到 dev 后运行 `install_workbuddy_experts.py <插件名>`——脚本复制本地 checkout，装出的专家即 SNAPSHOT 版，界面版本号可直接分辨。 - **Codex**：无会话级机制，**禁止**把 dev/SNAPSHOT 常驻安装——SNAPSHOT 会进入 客户端版本比较路径，这正是发布门禁在市场侧拦截的场景。 ## 插件发布与更新流程（域仓改动后） 技能改动合并到域仓 main 后，插件用户不会立即拿到——市场清单里的 sha pin 仍指向旧提交。执行以下步骤完成发布。 ### 1. 确认域仓改动已合并 ```bash gh api repos/soia-team/<域仓>/commits/main --jq '.sha' ``` ### 2. 在元仓重新生成市场清单 元仓 main 受分支保护（必须走 PR + `audit` 必过 + `enforce_admins`），因此刷新只能以 PR 形式提交，不能直推。在元仓 checkout 中执行： ```bash git checkout main && git pull && git checkout -b chore/refresh-marketplace ``` ```bash python3 scripts/generate_marketplaces.py && python3 scripts/generate_router_index.py ``` 两个脚本重新拉取各域仓 main 的最新 sha，改写 `.claude-plugin/marketplace.json`、`.agents/plugins/marketplace.json` 与路由索引。若 `git status` 无变化，说明清单已是最新，跳到第 5 步。 ### 3. 提交 PR 并合并 ```bash git add -A && git commit -m "chore(marketplace): refresh sha pins" && git push -u origin chore/refresh-marketplace ``` ```bash gh pr create --title "chore(marketplace): refresh sha pins" --body "刷新 sha pin 至各域仓最新提交。" --repo soia-team/soia-open-skills ``` 等 `audit` 检查通过后合并： ```bash gh pr checks --repo soia-team/soia-open-skills ``` ```bash gh pr merge --squash --delete-branch --repo soia-team/soia-open-skills ``` `audit` 中的 marketplace freshness 检查会独立重算一次清单，两边不一致即失败——这道门保证发布出去的 pin 确实指向域仓当前 main。 ### 4. 核对 sha pin 已更新 ```bash gh api repos/soia-team/soia-open-skills/contents/.claude-plugin/marketplace.json --jq '.content' | base64 -d | python3 -c "import json,sys;print({p['name']:str(p.get('source',{}).get('sha',''))[:12] for p in json.load(sys.stdin)['plugins']})" ``` 与第 1 步的域仓 sha 对比，一致即表示清单已是最新。 > 不要用 `gh workflow run refresh-marketplace.yml`：CI 的 `GITHUB_TOKEN` 无法直推受保护的 main，它建的 PR 也不会触发 `audit` 检查（GitHub 为防递归而抑制），两条路都走不通。市场刷新是发布动作的一部分，由本流程显式完成。 ### 5. 指导客户端更新 Claude Code：**先记录安装清单**，收尾要对账——`plugin update` 对未安装的插件会直接失败，卸载重装类操作也容易漏装： ```bash claude plugin list | grep soia > /tmp/claude-soia-before.txt && cat /tmp/claude-soia-before.txt ``` ```bash claude plugin marketplace update soia ``` ```bash claude plugin update <域插件名>@soia ``` 收尾对账，缺失的逐个 `plugin install` 补回： ```bash claude plugin list | grep soia | diff /tmp/claude-soia-before.txt - ``` 更新后需重启 Claude Code 生效。已开启 `autoUpdate` 的用户会在下次启动时自动完成这两步。 > `claude plugin details <名>` 对私有市场的插件要带市场后缀（`<名>@<市场>`），不带会报「not installed」，容易误判成插件丢失。核对安装状态用 `plugin list` 更可靠。 Codex：**先记录当前安装清单**——下面要删缓存，删错粒度会连带卸掉同市场的其他插件： ```bash codex plugin list | grep '@soia' > /tmp/soia-installed-before.txt && cat /tmp/soia-installed-before.txt ``` **只删市场暂存**（`marketplace add` 会复用旧克隆，不删就拉不到新增的资源文件）： ```bash rm -rf ~/.codex/.tmp/marketplaces/soia ``` **插件缓存只删目标那一个**，`soia` 是市场名不是插件名，`rm -rf ~/.codex/plugins/cache/soia` 会把该市场下**全部 8 个插件**一起删掉： ```bash rm -rf ~/.codex/plugins/cache/soia/<域插件名> ``` ```bash codex plugin marketplace add soia-team/soia-open-skills ``` ```bash codex plugin add <域插件名>@soia ``` **收尾比对安装清单**，确认没有连带损失；有缺失就逐个 `plugin add` 补回： ```bash codex plugin list | grep '@soia' | diff /tmp/soia-installed-before.txt - ``` Codex 无自动更新机制，必须手动执行。跳过删暂存这一步会出现「命令报成功、内容还是旧的」——2026-07-27 实际踩过：corp 市场的暂存停在没有 `assets/icon.svg` 的旧版本，`composerIcon` 指向不存在的文件，界面回退成通用图标，排查时误判为路径写错。 ### 6. WorkBuddy 专家（客户在用 WorkBuddy 时才做） WorkBuddy 是 Electron 桌面端，**没有 CLI**——不存在 `workbuddy plugin install`， 也没有能指向我们 GitHub 的市场通道。所以这一步由脚本代劳，不要去找对等命令： ```bash python3 skills/soia-meta-skill-release/scripts/install_workbuddy_experts.py --dry-run ``` 确认计划后执行（不带参数装全部，也可只给要装的插件名）： ```bash python3 skills/soia-meta-skill-release/scripts/install_workbuddy_experts.py ``` 脚本把域仓 checkout 复制进 `my-experts/plugins/<插件名>`，再调 WorkBuddy 官方 `register_expert.py` 注册。三条实测约束决定了只能这么做： | 约束 | 实测结论 | |---|---| | 目录 | 自建专家只认硬编码的 `my-experts`，应用内出现 38 处；别处放了不显示 | | 软链 | 不行。官方 `validate_expert.py` 对路径 `resolve()`，穿透后判定「不在专家目录下」 | | 远端 | 市场条目 `source` 只能是路径字符串，没有 sha pin 层；`expert/install` 深链要 `sharecode`，走官方云 | 装完**必须让客户重启 WorkBuddy**，否则新专家不出现在【专家·技能·连接器 → 我的专家】。 验证：召唤该专家后问「你有多少个可用技能」，该域技能应全部在场；不召唤时不在场。 ### 7. 回收旧版本缓存 两家客户端在 `plugin update` 后都只新增版本目录，**不回收旧的**；Claude 的 `.in_use` 标记也不可靠（实测同一插件新旧两个版本都带这个文件）。不清理会线性堆积，并干扰排查——用 `find` 找资源会匹配到多个版本目录，`ls` 统计技能数会得出离谱结果。 ```bash python3 skills/soia-meta-skill-release/scripts/prune_plugin_cache.py ``` 预演确认无误后执行： ```bash python3 skills/soia-meta-skill-release/scripts/prune_plugin_cache.py --apply ``` 按语义化版本取最高值保留，其余删除；非语义化版本目录（如官方插件的 `latest`）一律跳过。缓存随时可由市场重新拉取，删错也只是多下一次。 ### 8. 验证 ```bash claude plugin list ``` ```bash codex plugin list ``` 确认目标插件版本已变化、状态为 enabled。 ### 域仓与插件对照 | 域仓 | 插件名 | |---|---| | soia-open-dev-skills | soia-dev | | soia-open-dev-design-skills | soia-dev-design | | soia-open-pkm-vault-skills | soia-pkm-vault | | soia-open-media-content-skills | soia-media-content | | soia-open-cwork-office-skills | soia-cwork-office | | soia-open-edu-course-skills | soia-edu-course | | soia-open-env-skills | soia-env | | soia-open-skills | soia-meta | ## 边界与验证 - 只做 merge 后的本机收尾；发布前 merge 由调用方完成。 - `--dry-run` 不执行任何命令或文件写入，只输出计划回执。 - 前向测试应在临时 HOME 中 mock `subprocess`，覆盖命令顺序、失败即停、五处旧名清理、Codex 补链、lock 分支与 dry-run。 ### 发版前置：跨仓安装章节体检 各域仓的 `audit_skills.py` 互不相同，`private-skills` 甚至没有该脚本，因此 「安装章节覆盖三个一等宿主」这条**无法在各仓 CI 内统一校验**。门户仓 CI 只用 `--self` 检查自己那几个技能。 发版前在本机跑一次全量（需要各域仓的工作副本在同一父目录下）： ```bash python3 /scripts/check_install_sections.py --repos-root <各仓的父目录> ``` 它扫 `/skills/*` 与 `/*/skills/*`（覆盖 private-skills 的 `workspace/` 与 `harness/` 子仓目录），非零退出即有技能缺一等宿主。