@itpay/cli 2.0.25 → 2.0.27

package/docs/skill-bundle-rollout/03-platform-publishing.md

@@ -1,271 +1,161 @@
-# 各平台制作、验证和上传手册
+# 各平台制作、验证、发布与回滚手册
 
-状态：发布操作手册
-规则核对日期：2026-07-21
+状态：current operational handbook。
+最后核对：2026-08-10。
 
-平台规则会变化。每次正式提交前重新打开本文链接核对，不根据旧截图操作。
+平台规则会变化。每次正式提交前必须重新核对平台官方要求；本文只固定 ItPay
+自己的安全、版本和职责边界。
 
-## 0. 共用发布前检查
+## 1. 共用发布前门禁
 
-所有平台先满足：
+- 平台存在于 [04-first-wave-platforms.md](./04-first-wave-platforms.md)；
+- manifest/Skill/MCP config 来自平台仓库，不来自 Compose 或 CLI 临时目录；
+- CLI bundle 绑定精确 npm version、integrity、source SHA；
+- 无全局 CLI、无运行时 npm、离线 smoke 通过；
+- Skill 披露网络、命令、文件和外部 ItPay 授权页面；
+- MCP OAuth Token 由平台原生客户端保管，模型/Skill/CLI 看不到；
+- Local 使用 Device Authority，Remote 使用 MCP Connection；
+- 一个任务只选一条线路，不静默 fallback；
+- 公共 MCP `tools/list` 与当前批准合同一致；
+- Buyer Vault 读取只返回授权字段；
+- 支付/退款不因 OAuth、Skill 安装或 Vault 读取获得授权；
+- `.env`、Secret、Token、私钥、Device 文件、用户数据未打包；
+- website、support、privacy、terms、数据删除/断开说明可访问；
+- 正向、负向、越权、撤销、刷新和回滚测试完成。
 
-- bundle 绑定精确 `@itpay/cli` 版本和 npm integrity。
-- Skill 写明触发条件、外部数据发送、文件/网络/命令权限和人类 Checkout 交接。
-- 不包含 `.env`、API key、OAuth client secret、用户 token、Device 私钥或 `~/.itpay-v3`。
-- 不在运行时下载 `latest` CLI。
-- 云端 Chat 路径使用 MCP OAuth；本地路径使用 Device Authority。
-- 不把 OAuth 登录、Skill 启用或 CLI Device 注册视为付款授权。
-- 支付卡、CVV、支付密码、验证码和钱包私钥不进入聊天、Skill 或 CLI 参数。
-- 准备网站、支持、隐私政策、服务条款、退款说明和公开联系方式。
-- 准备允许和禁止场景测试；禁止场景必须停止或转交人类。
+## 2. ChatGPT + Codex
 
-## 1. OpenAI：ChatGPT + Codex
+仓库：`itpay-plugin-chatgpt`。
 
-### 选择的产品形态
+### ChatGPT 云端
 
-提交 **app-plus-skills plugin**，而不是 skills-only：
+- 只走远程 MCP OAuth；
+- 平台原生保存/刷新 Token；
+- 使用批准的五个 Buyer Vault read/authorization 工具；
+- 不探测本地 HOME 或创建 Device；
+- tool annotations、CSP、OAuth metadata、domain challenge 和审核材料在
+  OpenAI 平台仓库维护；
+- 审核账号只含固定测试数据，不要求真实付款。
 
-```text
-ItPay MCP App    用户 OAuth、服务端身份、账号范围工具
-ItPay Skill      工作流、触发、安全边界、本地 Codex bundle
-```
-
-一次批准发布后进入 ChatGPT 与 Codex 共用的 Plugins Directory。ChatGPT 云端调用 MCP；本地 Codex 只有在 shell/runtime 可用时使用 bundle。
-
-### 准备材料
-
-- OpenAI Platform 中已验证的个人或企业发布身份。
-- 提交者具备 Apps Management Write 权限。
-- 公开 production MCP URL。
-- MCP 域名控制权和 `/.well-known/openai-apps-challenge` challenge 响应能力。
-- OAuth 配置及无需 MFA、短信、邮件确认或内网的审核账号。
-- 每个工具准确的 `readOnlyHint`、`openWorldHint`、`destructiveHint`。
-- 精确 CSP 允许域名。
-- Skill bundle/ZIP，包含最终 `SKILL.md`、脚本、CLI bundle 和资源。
-- 5 个正向测试、3 个负向测试。
-- starter prompts、国家/地区、release notes。
-- website、support、privacy、terms 和品牌 Logo。
-
-### 制作与测试
-
-1. 生成 OpenAI repo 的精确 CLI bundle。
-2. Skill 中规定：有 ItPay MCP tool 时优先 MCP；不得为了寻找本地认证而读取任意 HOME 路径。
-3. MCP 工具返回不含 token、内部用户 ID、Device ID、debug payload 或未披露个人数据。
-4. 对创建 Checkout、退款等工具设置真实写操作 annotation 和平台确认。
-5. 使用最终文件树在 ChatGPT 和 Codex 分别测试，不用开发目录外文件。
-
-### 上传
-
-1. 打开 [OpenAI Plugin submission portal](https://platform.openai.com/plugins)。
-2. 选择 `Create plugin` -> `With MCP`。
-3. 填写 Info 和已验证 Developer Identity。
-4. 填 production MCP URL、认证、CSP，完成域名 challenge 并扫描工具。
-5. 上传最终 Skill bundle。
-6. 填 starter prompts。
-7. 提交恰好 5 个正向、3 个负向测试。
-8. 选择实际可运营的国家/地区并填 release notes。
-9. 完成 policy attestations 后 Submit for Review。
-10. 审核通过后由发布者在 portal 手动 Publish。
-
-### ItPay 特有审核点
-
-- MCP/Skill 只创建并展示外部 Checkout handoff；最终支付由用户在 ItPay/支付提供方页面确认。
-- 清楚展示商户、商品、币种、总额、ItPay 费用和退款条件。
-- 公共 Skill 不把 `pay` 或 `buy --pay` 描述成正常恢复路径。
-- 测试账号使用测试商户和限额，不要求审核人员真实付款。
-
-### 官方依据
+### 本地 Codex
 
-- [Submit plugins](https://learn.chatgpt.com/docs/submit-plugins)
-- [Plugins in ChatGPT and Codex](https://help.openai.com/en/articles/20001256)
-- [OpenAI App Developer Terms](https://openai.com/policies/developer-apps-terms/)
-- [OpenAI Commerce Policies](https://openai.com/policies/commerce-policies/)
+- 有 bundled CLI 时默认 Local Device；
+- Skill 使用 bundle 的确定入口，不调用全局 CLI；
+- 用户明确要求 MCP 才选择远程 MCP；
+- ChatGPT/Codex 共用发布仓库不代表共用凭据或运行路径。
 
-## 2. Claude Code
+验证：ChatGPT OAuth connect/refresh/revoke/Vault read；Codex fresh install、
+Device persistence、CLI Vault read、同机旧全局 CLI 隔离。
 
-### 产品形态
+## 3. WorkBuddy
 
-使用 Claude Plugin：
+仓库：`itpay-skill-workbuddy`。
 
-```text
-.claude-plugin/marketplace.json
-plugins/itpay/.claude-plugin/plugin.json
-plugins/itpay/skills/itpay/SKILL.md
-plugins/itpay/bin/itpay
-plugins/itpay/vendor/itpay-cli/
-plugins/itpay/.mcp.json（远程 MCP 上线时）
-```
+- 有持久 Shell 和 Skill bundle 时默认 CLI；
+- 用户明确连接/要求 MCP 时使用 WorkBuddy 原生 MCP OAuth；
+- CLI 持久写 `~/.itpay-v3` 前遵循 WorkBuddy 权限模型；
+- Checkout/Auth handoff 只使用官方 HTTPS URL/Action Card 和平台实际打开
+  工具；
+- 不读取任意目录，不下载/rebuild QR，不处理用户 Device lock；
+- MCP Access Token 到期必须静默 refresh；Vault window 到期只重新授权
+  Vault；
+- 上传包使用 `single-file-esm`，不含 `node_modules`。
 
-Claude Code 会将 plugin root 的 `bin/` 加入 Bash PATH，并把市场插件复制到 `~/.claude/plugins/cache`。插件不得引用目录外文件；持久数据应使用 `${CLAUDE_PLUGIN_DATA}`，但 ItPay Device Authority 仍使用用户 HOME 下的 `~/.itpay-v3`，不要写 plugin cache。
+验证：默认权限、用户拒绝权限、完全访问权限、路径空格/中文、窄内置浏览器、
+MCP 首次连接、扫码/回跳、refresh、关闭面板重连、Vault expiry/revoke。
 
-### 制作与测试
+SkillHub 上传/审核由仓库管理员执行；在官方确认前不宣称公共收录状态。
 
-1. `plugins/itpay/bin/itpay` 调用 plugin 内 vendored CLI，不调用全局 CLI。
-2. `plugins/itpay/skills/itpay/SKILL.md` 只引用 plugin 内路径或 PATH 中这个启动器。
-3. MCP 配置中的内部路径使用 `${CLAUDE_PLUGIN_ROOT}`。
-4. 执行：
+## 4. OpenClaw
 
-```bash
-claude plugin validate .
-claude --plugin-dir .
-```
+仓库：`itpay-skill-openclaw`。
 
-5. 在同时安装全局旧版 `itpay` 的机器上确认 Skill 使用 bundle 版本。
-6. 更新 plugin 后运行 `/reload-plugins` 或重启会话验证新版本。
+- 本地持久 host 使用 single-file CLI bundle；
+- 每次需要 native presentation 的命令显式传可信 `--host` 和目标上下文；
+- Telegram/Discord 等 host renderer 只负责展示，不改变业务合同；
+- 只有平台的远程 MCP OAuth 通过真实验收后才启用 MCP lane；
+- ClawHub 发布版本必须和 lock/Skill metadata 一致。
 
-### 独立分发
+验证：无全局 CLI、host/target、原生按钮/普通内容 fallback、Device 持久化、
+bundle 更新/回滚、若启用 MCP则连接/refresh/revoke。
 
-可以先用同一个 Claude 平台仓库中的 marketplace：
+## 5. Kimi Work / Kimi Code
 
-```text
-itpay-skill-claude-code/
-  .claude-plugin/marketplace.json
-  plugins/itpay/
-```
+仓库：`itpay-plugin-kimi-work`。
 
-用户执行：
+- Kimi Work 纯云端环境优先 MCP；
+- Kimi Code 有持久 Shell 和 bundle 时默认 CLI；
+- manifest/Skill 必须显式区分两个 surface；
+- extension/plugin setting 不存 OAuth Token；
+- 只有实际客户端证明的 token persistence/refresh 行为写入支持矩阵。
 
-```bash
-/plugin marketplace add itpay-ai/<marketplace-repo>
-/plugin install itpay@<marketplace-name>
-```
+验证：两个 surface 分别全新安装、线路选择、升级、Token refresh、Device 文件
+隔离和 Vault 跨平台读取。
 
-marketplace entry 使用相对 source `./plugins/itpay`。版本字段变化后用户才会收到对应更新；不要长期指向浮动未验证分支。
+## 6. Hermes Agent
 
-### 提交官方市场
+仓库：`itpay-skill-hermes`。
 
-1. 完成 README、版本策略、manifest、验证和测试。
-2. 打开以下任一官方表单：
-   - `https://claude.ai/settings/plugins/submit`
-   - `https://platform.claude.com/plugins/submit`
-3. 提交 plugin 仓库、功能、权限、数据外发、MCP 和支持信息。
-4. 根据审核反馈更新独立仓库并重新验证。
+- 本地 Skill tap 使用 single-file CLI bundle；
+- 不调用全局 CLI或 runtime npm；
+- Skills Hub/trusted 状态按真实上游结果记录；
+- 远程 MCP 仅在 Hermes 客户端完成标准 OAuth 实测后启用。
 
-Claude 官方文档没有承诺所有提交都会收录，也没有提供 Skill 原生收费通道。ItPay 收费仍通过 ItPay 账号和外部 Checkout。
+验证：tap 安装/更新/回滚、无网 bundle、Device persistence、命令输出合同、若
+启用 MCP则连接/refresh/revoke。
 
-### 官方依据
+## 7. 后续平台
 
-- [Create plugins](https://code.claude.com/docs/en/plugins)
-- [Plugins reference](https://code.claude.com/docs/en/plugins-reference)
-- [Discover plugins and official submission](https://code.claude.com/docs/en/discover-plugins)
-- [Create and distribute a marketplace](https://code.claude.com/docs/en/plugin-marketplaces)
+Claude 和 Gemini 不在当前仓库注册表。开始真实工作时才：
 
-## 3. Gemini CLI
+1. 核对当前官方 manifest/connector/auth 规则；
+2. 确认真实分发面和仓库名；
+3. 建平台仓库；
+4. 选择 CLI/MCP lane；
+5. 完成真实安装和 Token/Device 测试；
+6. 加入注册表和发布矩阵。
 
-### 产品形态
+不能根据旧文档中的“建议仓库”直接宣称已支持。
 
-使用独立 Gemini Extension 仓库：
+## 8. 发布顺序
 
 ```text
-gemini-extension.json
-skills/itpay/SKILL.md
-bin/itpay
-vendor/itpay-cli/
+Backend/MCP/Web contract accepted on Dev
+-> CLI docs and implementation accepted
+-> exact npm CLI published
+-> platform sync PRs generated
+-> each platform runs its own E2E/review
+-> platform merge/tag/store submission
+-> update actual version/status registry
 ```
 
-`gemini-extension.json` 必须位于仓库或 release archive 的绝对根目录。manifest `name` 使用小写和连字符，`version` 与 GitHub Release tag 保持一致。
+如果仅远程 MCP 变化且平台 manifest/Skill 不变，平台仍需运行 connector E2E，
+但不为了形式强制发布新 CLI bundle。
 
-### 制作
+## 9. 回滚
 
-最小 manifest 由平台仓库实施时按当时 schema 生成，核心字段：
+- Backend/MCP/Web 使用 Compose release rollback，不改变平台 Token/Device；
+- CLI 回滚发布上一个验证 bundle；
+- 平台回滚使用上一个 tag/artifact；
+- 不删除 `~/.itpay-v3`；
+- 不撤销所有 MCP Connection，除非安全事件明确要求；
+- 工具合同回滚后重新验证平台 `tools/list` 与 Backend compatibility；
+- 记录原因、版本、时间、影响平台和恢复证据。
 
-```json
-{
-  "name": "itpay",
-  "version": "2.0.14",
-  "description": "Use ItPay services through a bundled CLI and authenticated MCP workflows"
-}
-```
-
-Skill 放在 `skills/itpay/SKILL.md`。路径必须使用 `${extensionPath}`。若加入 MCP，在 `mcpServers` 中使用明确的 `command`/`args` 或平台支持的远程配置；用户 workspace 配置优先于 extension 同名 MCP，因此测试冲突行为。
-
-不要把 ItPay 用户 token设计成普通 extension setting。Gemini 会过滤未声明的环境变量，敏感 setting 也不能替代标准 OAuth。MCP 用户认证仍走任务一的 OAuth 系统。
-
-### 本地验证
-
-```bash
-gemini extensions link .
-```
+## 10. 实际发布矩阵
 
-重启 Gemini CLI，确认：
+矩阵不写死在本文，统一维护在
+[04-first-wave-platforms.md](./04-first-wave-platforms.md)。
 
-- `/extensions list` 显示 ItPay；
-- Skill 被发现；
-- bundle 版本正确；
-- 无全局 CLI 时仍可运行；
-- extension 更新后重新启动才加载新组件。
+每行至少记录：
 
-### 公开和自动收录
-
-1. 将仓库设为 public GitHub repo。
-2. 在 GitHub About 添加 topic：`gemini-cli-extension`。
-3. 确保根目录存在 `gemini-extension.json`。
-4. 创建与 manifest version 一致的 tag 和 GitHub Release。
-5. 若 release 使用 archive，确保 archive 自包含且 manifest 仍在根目录。
-6. Gemini crawler 每日扫描带 topic 的 tagged repositories；验证通过后自动进入 Extension Gallery，不需要提交 issue 或邮件。
-
-用户也可直接安装：
-
-```bash
-gemini extensions install https://github.com/itpay-ai/<repo>
+```text
+product surface
+repository
+supported lane
+CLI bundle version/integrity (if local)
+MCP contract/revision tested (if remote)
+draft/review/published/blocked
+last real acceptance date
+rollback artifact/tag
 ```
-
-### 官方依据
-
-- [Extension reference](https://geminicli.com/docs/extensions/reference/)
-- [Build extensions](https://geminicli.com/docs/extensions/writing-extensions/)
-- [Release extensions and Gallery indexing](https://geminicli.com/docs/extensions/releasing/)
-
-## 4. WorkBuddy
-
-### 已确认能力
-
-WorkBuddy 官方文档确认：
-
-- Skill 可以封装可执行脚本和工作流。
-- 用户可以在技能页面上传本地技能包。
-- 安装时会进行安全扫描。
-- 第三方 Skill 可能读取本地文件、运行系统命令并把数据发送给第三方；需要清楚披露。
-- Skill 的系统命令以用户本人身份执行；资金类操作应先小范围验证。
-- WorkBuddy 已支持 MCP 标准 OAuth，更新日志也记录了“支持带登录态调用 Skill”。
-
-### 制作与本地上传
-
-1. 生成 `itpay-skill-workbuddy` 的 `single-file-esm` Node bundle；上传包不得包含 `node_modules`，也不得在运行时执行 npm。
-2. `SKILL.md` frontmatter 提供清晰名称、描述和触发条件。
-3. 声明：执行本地命令、连接 `app.itpay.ai`、写入 owner-only `~/.itpay-v3` Device 状态、显示外部 Checkout。
-4. 不申请屏幕控制、任意目录写入或与 ItPay 无关的网络权限。
-5. 将 Skill 根目录打成 WorkBuddy 可接受的本地技能包。
-6. 在 WorkBuddy：技能 -> 添加技能 -> 上传技能，选择技能包。
-7. 检查安全扫描结果和权限提示，分别在默认权限、完全访问权限下验证；默认权限必须能够通过用户确认完成流程。
-8. 验证 macOS 和 Windows，尤其是 Node 可用性、中文用户名、路径空格、持久 HOME 和版本更新。
-9. CLI 同步 PR 若附带中心 Skill 差异，先人工合并新增业务规则并保留 WorkBuddy 权限、QR 和 sandbox 规则，通过平台测试后再把 Draft PR 标记为 ready。
-
-### SkillHub 公共发布
-
-截至核对日期，公开文档说明了 SkillHub 浏览、搜索、一键安装和本地技能包上传，但没有公开社区开发者提交入口、manifest schema 或审核表单。
-
-因此当前操作是：
-
-1. 先完成独立公开仓库、可下载技能包、本地上传和安全扫描。
-2. 通过 WorkBuddy/腾讯官方支持渠道申请 SkillHub 发布资格和最新提交规范。
-3. 取得官方 schema 后只在 WorkBuddy 仓库增加必要 manifest，不改变 CLI 主仓库。
-4. 按资金类 Skill 要求提供测试账号、外部 Checkout、权限和客服说明。
-
-在官方确认前，不对外宣称“已进入 SkillHub”或“添加 GitHub topic 即会自动收录”。
-
-### 官方依据
-
-- [WorkBuddy 技能与本地技能包上传](https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Skills-Market)
-- [WorkBuddy 更新日志：SkillHub、安全扫描、MCP OAuth](https://www.workbuddy.cn/docs/workbuddy/Changelog)
-- [WorkBuddy 权限模式](https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Permission-Modes)
-
-## 5. 发布矩阵
-
-每次发布维护下面的实际状态，不用“CLI 已发布”推断所有平台已更新：
-
-| CLI | OpenAI | Claude official | Claude own marketplace | Gemini Gallery | WorkBuddy local package | WorkBuddy SkillHub |
-| --- | --- | --- | --- | --- | --- | --- |
-| `X.Y.Z` | draft/review/published | draft/review/published | tag | indexed | artifact | pending/review/published |
-
-每个平台的用户实际拿到哪个版本，由其商店审核、tag 和更新机制决定。Backend compatibility 必须继续返回精确最低 CLI 版本，不能要求用户盲目安装 `latest`。

package/docs/skill-bundle-rollout/04-first-wave-platforms.md

@@ -1,32 +1,69 @@
-# 首批平台执行状态（2026-07-22）
+# 当前平台仓库与发布状态注册表
 
-首批按真实发布面拆成四个可落地仓库；豆包单独列为阻塞，不创建占位仓库。
+状态：current operational registry。
+最后核对：2026-08-10。
 
-| 产品面 | 仓库 | 形态 | 当前可做 | 外部阻塞 |
-| --- | --- | --- | --- | --- |
-| ChatGPT + Codex | `itpay-plugin-chatgpt` | OpenAI app-plus-skills plugin | `.codex-plugin/plugin.json`、Skill、离线 CLI、审核测试 | production MCP OAuth、域名 challenge、发布身份、legal/support URLs |
-| WorkBuddy | `itpay-skill-workbuddy` | SkillHub Skill 包 | `SKILL.md`、离线 CLI、权限/数据披露、ZIP | SkillHub 账号内上传由仓库管理员完成 |
-| OpenClaw / ClawHub | `itpay-skill-openclaw` | `@itpay/itpay@2.0.17` ClawHub Skill | 已发布单文件 CLI bundle | 首次安全审核与公开目录收录 |
-| Kimi Work / Kimi Code | `itpay-plugin-kimi-work` | `kimi.plugin.json` plugin + Skill | GitHub/Release 安装包、离线 CLI | Kimi Featured/第三方市场提交通道未公开；需桌面版实测 |
-| Hermes Agent / Skills Hub | `itpay-skill-hermes` | GitHub Skill tap | Hermes 专属 Skill、单文件 CLI bundle、自动更新 | Skills Hub 全局默认索引与 trusted 等级需上游收录 |
-| 豆包 | 暂不建仓 | 无可验证的 Skill bundle 发布面 | 保留调研记录 | 公开报道指向 2026-07-15 下线；需确认是否改为扣子、火山方舟 MCP 市场或 TRAE |
+本文件是 CLI 文档中平台集合、仓库名称和实际发布状态的唯一权威来源。
+不要在 README、bundle 合同或发布手册中维护另一份不同名单。
+
+## 当前注册表
+
+| 产品面 | 仓库 | 默认线路 | 当前形态 | 本轮发布状态 | 最近验收 | 回滚锚点 | 仍需持续验证 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| ChatGPT + Codex | `itpay-plugin-chatgpt` | ChatGPT MCP；本地 Codex CLI | OpenAI app-plus-skills plugin、MCP config、Skill、离线 CLI | blocked：Buyer Vault 候选尚未完成外部发布 | 2026-08-10 automated CI；ChatGPT/Codex 真机待验收 | pre-Vault `2b1e8a9c8030` | 当前 MCP 合同、OAuth refresh/revoke、OpenAI 审核；本地 CLI bundle pin |
+| WorkBuddy | `itpay-skill-workbuddy` | 本地 CLI；显式 MCP | SkillHub/local Skill 包、单文件 CLI、MCP OAuth | blocked：Buyer Vault 候选尚未同步 SkillHub | 2026-08-10 automated CI；WorkBuddy 真机待验收 | pre-Vault `584ebf3f8c46` | 权限模式、窄浏览器、OAuth 回跳/refresh、SkillHub 状态 |
+| OpenClaw / ClawHub | `itpay-skill-openclaw` | host-dependent CLI | ClawHub Skill、单文件 CLI | blocked：Buyer Vault 候选尚未同步 ClawHub | 2026-08-10 automated CI；OpenClaw 真机待验收 | pre-Vault `af2aa79d85c8` | 公开目录/审核状态、host renderer、更新/回滚 |
+| Kimi Work / Kimi Code | `itpay-plugin-kimi-work` | Work MCP；Code host-dependent CLI | Kimi plugin + Skill、离线 CLI | blocked：Buyer Vault 候选尚未发布；公开 release 仍为 `v2.0.17` | 2026-08-10 automated CI；两个 surface 真机待验收 | `v2.0.17` / `b8d40fe9cffd` | 两个 surface 真机、MCP Token persistence、市场状态 |
+| Hermes Agent / Skills Hub | `itpay-skill-hermes` | host-dependent CLI | GitHub Skill tap、单文件 CLI | blocked：Buyer Vault 候选尚未同步 Skills Hub | 2026-08-10 automated CI；Hermes 真机待验收 | pre-Vault `1189f25103fd` | Skills Hub/trusted 状态、更新/回滚、可选 MCP 真机 |
+
+CLI bundle 的实际版本、integrity 和 source SHA 只以各仓库
+`bundle.lock.json` 为准，不在本文复制易过期版本号。
+
+`blocked` means the repository candidate must not be presented as externally
+published. Update the status, acceptance date, and rollback anchor only after
+the named platform has real acceptance and its distribution surface is updated.
+
+## 后续目标，不是当前仓库
+
+| 平台 | 当前状态 | 加入注册表的条件 |
+| --- | --- | --- |
+| Claude / Claude Code | planned | 确认分发面和仓库，完成 manifest、CLI/MCP 路由、OAuth/Device 真机验收。 |
+| Gemini CLI | planned | 确认当前 Extension 规则，完成仓库、manifest、bundle 和真机验收。 |
+| 豆包/扣子/火山/其他 | unconfirmed | 明确具体产品面和官方第三方发布入口，不能相互代替。 |
+
+不要创建空仓库占位，也不要根据旧建议名单宣称支持。
 
 ## 统一合同
 
-- CLI 唯一真源是 npm `@itpay/cli` 的精确版本。
-- 平台仓库只存 manifest、平台 Skill、离线 vendor、`bundle.lock.json`、测试和提交材料。
-- bundle 生成器记录 npm integrity、npm `gitHead`、Node 要求和 production dependency lock hash。
-- 本地 Agent 使用 Device Authority；ChatGPT 云端使用远程 MCP OAuth，两者不共享凭据。
-- 不在运行时安装 `latest`，不回退到全局 CLI，不复制 CLI 源码继续分叉开发。
+- CLI 唯一真源是精确 npm `@itpay/cli`；
+- 平台仓库只保存 manifest、Skill、generated bundle、lock、测试和发布材料；
+- 本地使用 Device Authority，远程使用 MCP OAuth Connection；
+- 平台原生 MCP client 保管 Token；
+- 一个任务只走一条线路，不静默 fallback；
+- 不运行时下载 `latest`，不调用全局 CLI，不 patch generated bundle；
+- 同步只创建 PR，不自动发布；
+- Backend compatibility、CLI npm、平台 bundle 和 MCP contract 分别记录；
+- 跨平台 Buyer Vault 功能上线后，公共 MCP 只注册批准的五个工具。
+
+## 每次发布如何更新
 
-## CLI 更新机制
+五个平台仓库每小时错峰检查 npm `@itpay/cli` 的正式版。发现版本高于各自 `bundle.lock.json` 后，调用 CLI `main` 上的统一 reusable workflow，重建对应格式的 bundle并运行仓库测试。更新 PR 优先由最小权限 `itpay-bundle-sync` GitHub App 创建；仓库未配置 App 时回落到 `GITHUB_TOKEN` 并明确要求人工批准 PR checks。该流程禁止个人 PAT，不会自动合并或发布商店版本，同一个 CLI 版本已有有效 open PR 时不会重复 force-push。
 
-四个平台仓库每小时错峰检查 npm `@itpay/cli` 的正式版。发现版本高于各自 `bundle.lock.json` 后，调用 CLI `main` 上的统一 reusable workflow，重建对应格式的 bundle、运行仓库测试，并以平台仓库自己的 `GITHUB_TOKEN` 创建更新 PR。该流程不需要 PAT，也不会自动合并或发布商店版本。
+平台 owner 在真实验收后更新对应行或附加 release record，至少记录：
 
-## 已发现的现有资产
+```text
+tested_at
+platform package/tag
+CLI version + npm integrity (local lane)
+MCP/Backend revision (remote lane)
+positive/negative test result
+store/review status
+rollback artifact
+```
 
-`itpay-ai/skill` 是旧的多平台通用仓库，固定 CLI 2.0.11，并对 bundle 做过平台 Agent Type patch。首批独立仓库只复用其已验证的 wrapper/test 思路，不再手工 patch CLI。旧仓库在迁移完成前保留，之后再决定归档或改为索引仓库。
+“CLI 已发布”或“Backend 已部署”不能推断平台已更新。
 
-## 豆包判断
+## 历史通用仓库
 
-截至 2026-07-22，没有找到豆包官方的 `SKILL.md + 可执行 bundle` 上传或商店提交流程。公开报道显示豆包智能体功能已于 2026-07-15 下线。扣子、火山方舟 MCP 市场和 TRAE 是不同产品面，不能未经确认就用它们代替“豆包上架”。
+旧 `itpay-ai/skill` 不再作为 CLI 或平台业务真源。独立仓库迁移完成后，
+它只能归档或作为不含 bundle/业务分叉的索引仓库；不能继续手工 patch CLI。

package/docs/skill-bundle-rollout/05-sync-operations.md

@@ -0,0 +1,62 @@
+# Bundle 同步运维与事故处理
+
+## 正常状态
+
+每次同步必须在 Job Summary 中给出 published version、automation branch、同步决策、凭据模式、PR URL 和关闭的 superseded PR 数量。
+
+同步决策只有以下正常结果：
+
+- `base-current`：main 已经包含目标版本，无需更新。
+- `pr-current`：当前版本的 open PR 已包含正确 bundle，不得产生新 commit。
+- `update-required`：目标版本不存在，需要构建并创建 PR。
+- `open-pr-artifact-missing`：PR 分支缺少 lock，需要重新构建。
+- `open-pr-artifact-mismatch`：PR 中的 version、format 或 bundle directory 不符合 caller 合同，需要重新构建。
+
+## 失败分类
+
+### GitHub Actions 启动故障
+
+以下证据表示仓库代码没有运行：
+
+- run 的 `steps` 为空；
+- 失败发生在 `Set up job`；
+- `Failed to resolve action download info`；
+- Hosted Runner 长时间 queued 后被 cancelled 或 timed out。
+
+先查看 GitHub Status。官方确认恢复后重跑原 SHA；不得为了这种故障修改 bundle、测试或业务代码。
+
+### Bundle 构建或测试故障
+
+以下步骤失败才属于仓库或产物问题：
+
+- Resolve published version
+- Rebuild bundle
+- Inspect upstream Skill changes
+- Verify platform bundle
+
+保留失败分支和日志，不创建或更新 PR，不跳过 `npm test`。
+
+### `action_required`
+
+由 `GITHUB_TOKEN` 创建或更新的 PR workflow 会进入 approval-required 状态。这不是测试失败，但测试尚未执行。仓库写权限用户可以批准该 run；要求零人工同步时，必须配置最小权限 GitHub App，禁止使用个人 PAT。
+
+## 重跑规则
+
+1. 只重跑仍指向当前 head SHA 的基础设施失败。
+2. 新 commit 已存在时不重跑旧 SHA。
+3. 同一个版本第二次同步必须保持 automation PR head SHA 不变。
+4. 不把 cancelled、action-required 或旧 SHA 的 success 当作当前版本通过。
+
+## Superseded PR
+
+新版本 PR 建立并通过平台 `npm test` 后，可以关闭旧机器人同步 PR。自动关闭只允许处理带同步标记、分支符合 `automation/itpay-cli-X.Y.Z`、且所有提交均由 `itpay-bundle-bot` 产生的 PR。检测到人工提交时必须保留并在 summary 中提示。关闭时保留远程分支，不自动删除历史。
+
+## GitHub App 权限
+
+`itpay-bundle-sync` 只安装到分发仓库，权限限定为：
+
+- Metadata: read
+- Contents: read/write
+- Pull requests: read/write
+
+App 不需要 Actions、Secrets、Administration、Deployments 或 Packages 写权限。私钥只存于组织 Actions secrets，通过 reusable workflow 生成当前仓库、当前 job 有效的短期 token。