@itpay/cli 2.1.19 → 2.1.29

package/docs/skill-bundle-rollout/01-mcp-authentication.md

@@ -1,134 +0,0 @@
-# Local Device 与远程 MCP OAuth 边界
-
-状态：current boundary；服务端实现以 `itpay-ai/compose` 为准。
-最后核对：2026-08-10。
-
-## 1. 本文负责什么
-
-本文只定义 CLI/平台包必须遵守的身份选择和凭据保管规则。
-
-服务端 OAuth 协议、Connection、workload delegation、Buyer 和 Vault 数据
-模型由 Compose 仓库的 V3 文档、Schema、OpenAPI 和代码负责。CLI 仓库不再
-维护一份重复的 OAuth Server 实施计划。
-
-## 2. Local Device Authority
-
-本地 CLI 使用：
-
-```text
-~/.itpay-v3/device/device-private.pem
-~/.itpay-v3/device/identity.json
-```
-
-`src/state/device_authority.ts`：
-
-- 生成/保存本地 Ed25519 私钥；
-- 按 Backend base URL 保持独立 Device registration；
-- 按显式 Agent Type 解析 exact Agent Instance；
-- 用 challenge 签名取得短期 Device Session；
-- 对受保护请求签名并防重放；
-- 只对可恢复 session 执行一次续期和同请求重放；
-- 不静默替换被吊销 Device。
-
-这些文件表示本地工作负载，不表示网页登录 Token，也不能被复制进平台
-bundle。
-
-## 3. 远程 MCP OAuth
-
-云端 MCP 客户端使用标准 OAuth Connection：
-
-```text
-MCP client
--> Authorization Code + PKCE
--> ItPay login/consent
--> client stores Access/Refresh Token
--> ItPay MCP validates token
--> exact MCP Connection
--> Buyer-less workload delegation to Backend
-```
-
-平台客户端负责 Token 持久化、刷新和断线重连。以下位置都不能保存或打印
-OAuth Token：
-
-- CLI；
-- `~/.itpay-v3`；
-- Skill / Plugin；
-- `bundle.lock.json`；
-- 模型提示、tool 参数或 tool 输出；
-- Git 仓库；
-- Backend 普通 API 日志。
-
-十分钟 Access Token 到期应由 Refresh Token 自动续期，不得让用户每十分钟
-重新扫码。Vault 短期授权到期是独立事件，只重新请求 Vault 授权。
-
-## 4. 两条线路不能混用
-
-| 属性 | Local CLI | Remote MCP |
-| --- | --- | --- |
-| caller | Device + exact Agent Instance | exact MCP Connection |
-| credential owner | 用户本机 CLI | MCP client/platform |
-| Authorization | `ItPayDevice` + signed headers | OAuth Bearer at MCP resource |
-| server hop | CLI -> Backend | Platform -> MCP -> delegated Backend |
-| durable revoke | Device/Agent | Connection/Grant |
-| Buyer relationship | explicit Device binding | OAuth Connection binding |
-
-互斥规则：
-
-- Backend Device middleware 不接受 MCP Bearer；
-- MCP resource 不接受 Device Session；
-- CLI 不读取 MCP Token；
-- MCP 不读取 `~/.itpay-v3`；
-- 撤销一个通道不删除另一个通道；
-- 两个通道可指向同一 Buyer，但 Vault 临时授权按 exact audience 分开。
-
-## 5. 平台路由
-
-平台 Skill 在开始业务动作前选择线路：
-
-```text
-persistent local shell and bundled CLI and no explicit MCP -> CLI
-pure cloud -> MCP
-explicit MCP request -> MCP
-explicit CLI request -> CLI
-```
-
-同一任务不能：
-
-- 同时调用两条线路；
-- 在失败后静默 fallback；
-- 用 email、昵称、Agent Type 或平台名推断 Buyer；
-- 用 Device/MCP 重连重置免费额度或资源归属。
-
-## 6. 跨平台 Buyer Vault 读取
-
-Local Device 与 MCP Connection 可以读取同一 Buyer Vault，但必须分别完成：
-
-1. durable caller authentication；
-2. exact-audience temporary Vault window；
-3. 对需要首次揭示的工件完成 artifact-specific consent。
-
-CLI/MCP 连接不等于持续读取授权，OAuth 登录也不等于首次揭示或退款授权。
-
-最终产品、API、Schema 和测试合同由 Compose 文档
-`V3_CROSS_PLATFORM_BUYER_VAULT_READ_IMPLEMENTATION_PLAN.md` 负责。
-
-## 7. 平台不兼容时
-
-如果平台不能安全完成标准 OAuth 或保存/刷新 Token：
-
-- 有本地 Shell 时使用 bundled CLI；
-- 没有本地 Shell 时标记 MCP 不支持；
-- 不接受静态 personal bearer；
-- 不要求用户在聊天中粘贴 Token；
-- 不把 Token做成普通 Skill setting。
-
-## 8. 验证门禁
-
-- CLI 升级前后 Device ID 和私钥 hash 不变；
-- MCP 连接/刷新/撤销不修改 Local Device 文件；
-- Device 与 MCP auth scheme 互相拒绝；
-- 两个 Connection 与两个 Agent Instance 的 Vault audience 相互隔离；
-- Access Token 刷新无需用户或模型参与；
-- Vault window 到期不会销毁 OAuth/Device durable identity；
-- 日志、bundle、tool output 和 repo secret scan 无凭据；
-- 平台失败时没有静默线路切换。

package/docs/skill-bundle-rollout/02-platform-bundle-repositories.md

@@ -1,210 +0,0 @@
-# 多平台仓库与 CLI Bundle 合同
-
-状态：current。
-最后核对：2026-08-10。
-
-## 1. 原则
-
-每个真实发布面可以有独立仓库，但所有仓库消费同一 MCP 和同一
-`@itpay/cli`。独立仓库解决 manifest、安装、提示、审核和发布节奏差异，
-不制造平台业务 fork。
-
-```text
-itpay-ai/compose
-  Backend / OAuth / MCP / Web / Buyer / Vault
-
-itpay-ai/cli
-  @itpay/cli source / command docs / bundle generator
-
-platform repository
-  manifest / platform Skill / exact CLI bundle / tests / submission
-```
-
-## 2. 当前仓库注册表
-
-具体发布状态只在
-[04-first-wave-platforms.md](./04-first-wave-platforms.md) 维护。
-
-| 产品面 | 仓库 | 本地 CLI | 远程 MCP |
-| --- | --- | --- | --- |
-| ChatGPT + Codex | `itpay-plugin-chatgpt` | local Codex | ChatGPT/cloud |
-| WorkBuddy | `itpay-skill-workbuddy` | default when shell is available | explicit connection |
-| OpenClaw | `itpay-skill-openclaw` | supported host-dependent | only after real client acceptance |
-| Kimi Work / Kimi Code | `itpay-plugin-kimi-work` | Kimi Code host-dependent | Kimi Work/remote host-dependent |
-| Hermes Agent | `itpay-skill-hermes` | supported host-dependent | only after real client acceptance |
-
-Claude 和 Gemini 属于待开始支持目标；没有真实仓库、manifest 和验收前不放入
-当前注册表。
-
-## 3. 平台仓库最小内容
-
-```text
-platform manifest / connector config
-platform-specific SKILL.md
-bin or scripts launcher                     # only for local-capable hosts
-vendor/itpay-cli/                           # generated, not edited
-bundle.lock.json
-tests/
-README / submission / release notes
-```
-
-平台仓库不得包含：
-
-- CLI 源码副本或手工 Agent Type patch；
-- Backend/MCP/Vault 状态机；
-- OAuth client secret、Access/Refresh Token；
-- `.env`、用户 HOME、Device 私钥/session；
-- 运行时 `npm install` 或 `latest`；
-- 全局 CLI fallback。
-
-## 4. Bundle 格式
-
-优先复用现有已验证格式：
-
-```text
-npm-tree
-  vendor/itpay-cli/package/
-  vendor/itpay-cli/node_modules/       production only
-
-single-file-esm
-  vendor/itpay-cli/itpay-cli.bundle.mjs
-  vendor/itpay-cli/docs/
-  vendor/itpay-cli/licenses/
-```
-
-WorkBuddy/OpenClaw/Hermes 等上传型 Skill 优先使用 `single-file-esm`，不包含
-`node_modules`。只有真实平台证明 Node runtime 不可用时，才启动 standalone
-executable 工作；不提前维护多架构二进制。
-
-## 5. `bundle.lock.json`
-
-至少包含：
-
-```json
-{
-  "schemaVersion": 1,
-  "package": "@itpay/cli",
-  "version": "X.Y.Z",
-  "format": "single-file-esm",
-  "npmIntegrity": "sha512-...",
-  "sourceGitSha": "...",
-  "generatedAt": "<RFC3339>",
-  "node": ">=18",
-  "bundleDirectory": "vendor/itpay-cli",
-  "dependencyLockSha256": "<64 lowercase hex characters>"
-}
-```
-
-`format` is `single-file-esm` or `npm-tree`. `bundleDirectory` is the
-repository-relative Skill bundle directory, and `dependencyLockSha256` is the
-raw lowercase SHA-256 hex digest emitted by `build-platform-bundle.mjs` (without
-a `sha256:` prefix). The reusable synchronization workflow consumes these exact
-field names.
-
-不得包含 Token、registry credential、本机路径或 Device 状态。
-
-## 6. 启动器规则
-
-- 只调用 bundle 内入口；
-- 转发全部参数、stdout、stderr、signal 和 exit code；
-- 不修改 `HOME`；
-- 不搜索 PATH 中其他 `itpay`；
-- `itpay --version` 必须等于 lock version；
-- 临时测试使用临时 HOME，不能触碰开发者真实 Device；
-- 路径含空格和中文用户名仍可运行。
-
-## 7. 平台 Skill 允许差异
-
-允许：
-
-- manifest 和安装路径；
-- MCP 配置语法；
-- Agent Type / host 选择；
-- 平台工具名和浏览器/文件展示方式；
-- 权限说明和审核材料；
-- CLI/MCP 路由提示；
-- 平台特有的安全限制。
-
-不允许：
-
-- 改变 CLI 命令参数和 JSON 合同；
-- 改变 MCP 工具 Schema；
-- 改变 Buyer/Vault/支付/退款规则；
-- 保存 OAuth Token；
-- 自动猜测并切换线路；
-- 修改生成的 CLI bundle 业务代码。
-
-## 8. Bundle 生成
-
-生成器只接受精确 semver：
-
-```text
-resolve exact npm version
--> fetch tarball metadata
--> verify npm integrity
--> install exact production dependencies with scripts disabled
--> remove cache/test/temp files
--> create requested bundle format
--> generate lock
--> secret/dangerous-file scan
--> offline smoke
-```
-
-拒绝 `latest`、范围、未发布版本和 integrity 不匹配。
-
-## 9. CLI 发布后的同步
-
-```text
-@itpay/cli X.Y.Z published
--> platform repo detects version drift
--> invoke reusable bundle workflow
--> rebuild and verify
--> update lock/manifest/release notes
--> create or refresh sync PR
--> platform owner reviews tests and Skill differences
--> merge/tag/publish separately
-```
-
-CLI 主仓库在 `main` 提供 reusable workflow。各平台仓库每小时错峰运行 caller workflow，并可手动触发；npm `dist-tags.latest` 或请求的 bundle format 与当前 `bundle.lock.json` 不同时更新。同步优先使用只安装到分发仓库、只拥有 Contents/Pull requests 写权限的 `itpay-bundle-sync` GitHub App 短期 token；未配置 App 时回落到平台仓库自己的 `GITHUB_TOKEN`，但该模式创建的 PR checks 需要仓库写权限用户批准。禁止使用个人 PAT。
-
-同步决策同时读取 main 和当前版本的 open automation PR。目标版本、format 和 bundle directory 已存在于 open PR 时必须返回 `pr-current`，不得每小时重建、提交或 force-push 同一产物。
-
-- 优先使用最小权限 GitHub App 短期 token；
-- fallback 只使用平台仓库自己的 `GITHUB_TOKEN`；
-- 禁止个人 PAT；
-- 不自动合并；
-- 不自动打 tag；
-- 不自动提交商店；
-- CLI 发布失败时不生成平台发布。
-
-- 重新生成 bundle；
-- 更新 manifest 版本、lock、changelog；
-- 跑全套测试；
-- 对启用 Skill 差异跟踪的平台，比较旧、新 `sourceGitSha` 的中心 `skills/itpay/SKILL.md`；有差异时创建 Draft PR、附 diff 和人工合并清单，但不覆盖平台 Skill；
-- 创建或刷新 `automation/itpay-cli-X.Y.Z` 分支和同步 PR；同版本的后续计划任务必须为 no-op；
-- PR 描述列出 CLI commit、integrity、dependency lock、同步 run、平台测试和是否需要商店重新审核；
-- 新版本 PR 验证成功后，只关闭没有人工提交的旧机器人同步 PR；保留远程分支用于审计和恢复。
-
-## 10. Repository tests
-
-每个平台必须证明：
-
-- 无全局 CLI；
-- 测试期间禁止 npm 网络下载；
-- bundle version/integrity/source SHA 正确；
-- manifest 能被平台 validator 读取；
-- platform Skill 只选择一个 CLI/MCP lane；
-- MCP Token 不进入配置、prompt、tool 或 bundle；
-- Device 文件不被打包或打印；
-- 同机旧全局 CLI 不影响 bundled CLI；
-- 升级/回滚不删除 `~/.itpay-v3`；
-- 平台声称支持 MCP 时完成真实连接、刷新、重连和撤销测试。
-
-## 11. 版本与回滚
-
-第一阶段平台包版本跟随 CLI 版本，避免双版本映射。只有平台仅修改 manifest/
-说明且真实需要独立发布节奏时，才增加 `pluginVersion`，同时保留
-`cliVersion`。
-
-回滚发布上一个通过验证的 bundle/manifest，不修改 Buyer、MCP Connection 或
-Device 状态。

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

@@ -1,161 +0,0 @@
-# 各平台制作、验证、发布与回滚手册
-
-状态：current operational handbook。
-最后核对：2026-08-10。
-
-平台规则会变化。每次正式提交前必须重新核对平台官方要求；本文只固定 ItPay
-自己的安全、版本和职责边界。
-
-## 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、数据删除/断开说明可访问；
-- 正向、负向、越权、撤销、刷新和回滚测试完成。
-
-## 2. ChatGPT + Codex
-
-仓库：`itpay-plugin-chatgpt`。
-
-### ChatGPT 云端
-
-- 只走远程 MCP OAuth；
-- 平台原生保存/刷新 Token；
-- 使用批准的五个 Buyer Vault read/authorization 工具；
-- 不探测本地 HOME 或创建 Device；
-- tool annotations、CSP、OAuth metadata、domain challenge 和审核材料在
-  OpenAI 平台仓库维护；
-- 审核账号只含固定测试数据，不要求真实付款。
-
-### 本地 Codex
-
-- 有 bundled CLI 时默认 Local Device；
-- Skill 使用 bundle 的确定入口，不调用全局 CLI；
-- 用户明确要求 MCP 才选择远程 MCP；
-- ChatGPT/Codex 共用发布仓库不代表共用凭据或运行路径。
-
-验证：ChatGPT OAuth connect/refresh/revoke/Vault read；Codex fresh install、
-Device persistence、CLI Vault read、同机旧全局 CLI 隔离。
-
-## 3. WorkBuddy
-
-仓库：`itpay-skill-workbuddy`。
-
-- 有持久 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`。
-
-验证：默认权限、用户拒绝权限、完全访问权限、路径空格/中文、窄内置浏览器、
-MCP 首次连接、扫码/回跳、refresh、关闭面板重连、Vault expiry/revoke。
-
-SkillHub 上传/审核由仓库管理员执行；在官方确认前不宣称公共收录状态。
-
-## 4. OpenClaw
-
-仓库：`itpay-skill-openclaw`。
-
-- 本地持久 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。
-
-## 5. Kimi Work / Kimi Code
-
-仓库：`itpay-plugin-kimi-work`。
-
-- Kimi Work 纯云端环境优先 MCP；
-- Kimi Code 有持久 Shell 和 bundle 时默认 CLI；
-- manifest/Skill 必须显式区分两个 surface；
-- extension/plugin setting 不存 OAuth Token；
-- 只有实际客户端证明的 token persistence/refresh 行为写入支持矩阵。
-
-验证：两个 surface 分别全新安装、线路选择、升级、Token refresh、Device 文件
-隔离和 Vault 跨平台读取。
-
-## 6. Hermes Agent
-
-仓库：`itpay-skill-hermes`。
-
-- 本地 Skill tap 使用 single-file CLI bundle；
-- 不调用全局 CLI或 runtime npm；
-- Skills Hub/trusted 状态按真实上游结果记录；
-- 远程 MCP 仅在 Hermes 客户端完成标准 OAuth 实测后启用。
-
-验证：tap 安装/更新/回滚、无网 bundle、Device persistence、命令输出合同、若
-启用 MCP则连接/refresh/revoke。
-
-## 7. 后续平台
-
-Claude 和 Gemini 不在当前仓库注册表。开始真实工作时才：
-
-1. 核对当前官方 manifest/connector/auth 规则；
-2. 确认真实分发面和仓库名；
-3. 建平台仓库；
-4. 选择 CLI/MCP lane；
-5. 完成真实安装和 Token/Device 测试；
-6. 加入注册表和发布矩阵。
-
-不能根据旧文档中的“建议仓库”直接宣称已支持。
-
-## 8. 发布顺序
-
-```text
-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
-```
-
-如果仅远程 MCP 变化且平台 manifest/Skill 不变，平台仍需运行 connector E2E，
-但不为了形式强制发布新 CLI bundle。
-
-## 9. 回滚
-
-- Backend/MCP/Web 使用 Compose release rollback，不改变平台 Token/Device；
-- CLI 回滚发布上一个验证 bundle；
-- 平台回滚使用上一个 tag/artifact；
-- 不删除 `~/.itpay-v3`；
-- 不撤销所有 MCP Connection，除非安全事件明确要求；
-- 工具合同回滚后重新验证平台 `tools/list` 与 Backend compatibility；
-- 记录原因、版本、时间、影响平台和恢复证据。
-
-## 10. 实际发布矩阵
-
-矩阵不写死在本文，统一维护在
-[04-first-wave-platforms.md](./04-first-wave-platforms.md)。
-
-每行至少记录：
-
-```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
-```

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

@@ -1,70 +0,0 @@
-# 当前平台仓库与发布状态注册表
-
-状态：current operational registry。
-最后核对：2026-08-10。
-
-本文件是 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 状态 |
-| 豆包工作 | `itpay-ai/cli` | 云电脑内的本地 CLI | 官方 npm CLI；`doubao-work` Agent Type | candidate：CLI 合同与自动化测试完成后待豆包工作真机验收 | 待本轮 automated CI 与真机验收 | 发布前 CLI tag | 云电脑安装/持久化、本机直达链接、二维码备用链接 |
-| 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、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 只注册批准的五个工具。
-
-## 每次发布如何更新
-
-五个平台仓库每小时错峰检查 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。
-
-平台 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
-```
-
-“CLI 已发布”或“Backend 已部署”不能推断平台已更新。
-
-## 历史通用仓库
-
-旧 `itpay-ai/skill` 不再作为 CLI 或平台业务真源。独立仓库迁移完成后，
-它只能归档或作为不含 bundle/业务分叉的索引仓库；不能继续手工 patch CLI。

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

@@ -1,62 +0,0 @@
-# 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。