@itpay/cli 2.1.34 → 2.1.41

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

@@ -0,0 +1,210 @@
+# 多平台仓库与 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

@@ -0,0 +1,161 @@
+# 各平台制作、验证、发布与回滚手册
+
+状态：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

@@ -0,0 +1,69 @@
+# 当前平台仓库与发布状态注册表
+
+状态：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 状态 |
+| 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

@@ -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。

package/docs/skill-bundle-rollout/README.md

@@ -0,0 +1,151 @@
+# ItPay 平台 Skill / Plugin 与 CLI Bundle 文档入口
+
+状态：current。
+Authority：CLI 与平台发布边界入口。
+最后核对：2026-08-10。
+
+本目录只管理 CLI 和平台发布合同，不管理 Backend、OAuth Server、Buyer、
+Vault 或授权状态机。
+
+跨平台 Buyer Vault 读取的权威开发计划在 `itpay-ai/compose`：
+
+```text
+docs/v3/V3_CROSS_PLATFORM_BUYER_VAULT_READ_IMPLEMENTATION_PLAN.md
+```
+
+远程 MCP OAuth 与 Local Device Authority 的权威实现记录在：
+
+```text
+docs/v3/V3_MCP_OAUTH_AND_LOCAL_DEVICE_AUTH_IMPLEMENTATION_PLAN.md
+```
+
+## 文档路由
+
+| 文件 | 负责内容 |
+| --- | --- |
+| [01-mcp-authentication.md](./01-mcp-authentication.md) | CLI Device 与远程 MCP OAuth 的边界、Token 保管、CLI/MCP 路由。 |
+| [02-platform-bundle-repositories.md](./02-platform-bundle-repositories.md) | 平台独立仓库、bundle、lock、同步 PR 和禁止复制核心代码。 |
+| [03-platform-publishing.md](./03-platform-publishing.md) | 平台制作、验证、发布、回滚的通用手册和平台差异。 |
+| [04-first-wave-platforms.md](./04-first-wave-platforms.md) | 当前真实平台仓库注册表和发布状态；平台集合只以此文件为准。 |
+| [05-sync-operations.md](./05-sync-operations.md) | Bundle 同步 GitHub App、fallback、幂等、事故处理和人工恢复。 |
+
+## 当前身份边界
+
+```text
+本地 Agent
+-> bundled @itpay/cli
+-> ~/.itpay-v3 Device Authority
+-> exact Agent Instance
+-> ItPay Backend
+
+云端 Chat 平台
+-> 原生 MCP OAuth
+-> exact MCP Connection
+-> ItPay MCP
+-> short workload delegation
+-> ItPay Backend
+```
+
+两条通道可以关联同一 Buyer 并读取同一 Buyer Vault，但不共享：
+
+- Device 私钥或 Device Session；
+- OAuth Access/Refresh Token；
+- Agent Instance 或 MCP Connection；
+- 临时 Vault 授权窗口；
+- 工件首次揭示授权。
+
+## 仓库职责
+
+### CLI 仓库
+
+负责：
+
+- `@itpay/cli` 源码；
+- Device Authority；
+- 命令、参数和标准输出；
+- 通用 Agent Type/host renderer；
+- bundle 生成与可复现性合同；
+- CLI 命令文档和测试。
+
+不负责：
+
+- MCP OAuth Token 保存；
+- Buyer/Vault 业务状态机；
+- 平台商店 manifest；
+- 平台专属业务逻辑。
+
+### 平台仓库
+
+只负责：
+
+```text
+manifest / MCP config
+平台专属 Skill 与 CLI/MCP 路由
+精确 CLI bundle（本地平台）
+bundle.lock.json
+平台测试、审核和发布材料
+```
+
+不复制 CLI 源码，不实现 OAuth/Vault/支付，不在运行时下载 `latest`。
+
+## 当前平台集合
+
+当前发布面只以
+[04-first-wave-platforms.md](./04-first-wave-platforms.md) 为准：
+
+- ChatGPT + Codex；
+- WorkBuddy；
+- OpenClaw；
+- Kimi Work / Kimi Code；
+- Hermes Agent。
+
+Claude 与 Gemini 是后续支持目标，不在没有真实实现和验收时创建占位仓库或
+写成“首批已实施”。
+
+## 一个任务只走一条线路
+
+```text
+有持久本地 Shell + bundled CLI + 用户未指定 MCP -> CLI
+纯云端平台 -> MCP
+用户明确指定 MCP -> MCP
+用户明确指定 CLI -> CLI
+```
+
+选定后禁止静默 fallback。Device 被吊销不能自动改走 MCP；MCP OAuth 失败
+不能自动创建本地 Device。
+
+## CLI 文档先行
+
+任何命令变更必须遵守：
+
+```text
+先更新 command reference
+-> 冻结参数/状态/JSON/instruction/next/recovery
+-> 再改代码
+-> 自动测试
+-> 构建真实 CLI
+-> 临时 HOME + 真实 Backend 执行
+-> 实际输出逐字段对照文档
+```
+
+JSON 模式 stdout 只能有一个标准 envelope；不能追加调试、进度或提示文本。
+
+## 统一发布门禁
+
+- npm 精确版本、integrity、source SHA 可验证；
+- 平台 bundle 版本等于 `bundle.lock.json`；
+- 无全局 CLI、无运行时 npm、离线 smoke 通过；
+- Skill/bundle 不含 `.env`、Token、私钥、Device 文件或用户数据；
+- 平台原生客户端保管和刷新 OAuth Token；Skill/CLI/模型看不到 Token；
+- 同步只开 PR，不自动合并、打 tag 或发布商店；
+- 每个平台分别保存实际已发布版本和回滚版本；
+- Backend compatibility 返回精确最低 CLI 版本，不指导盲目安装 `latest`。
+
+## 当前不做
+
+- 不为每个平台部署一套 MCP Backend；
+- 不建立第二套 Buyer 数据；
+- 不把平台账号 ID 当 ItPay Buyer；
+- 不为不兼容 OAuth 的平台发明模型可见固定 Token；
+- 不为尚未开始的平台创建空仓库；
+- 不在这个 CLI 文档目录重复服务端 Schema/API/Owner 设计。