@itpay/cli 2.0.14 → 2.0.16

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

@@ -0,0 +1,279 @@
+# 核心任务二：多平台 Bundle Skill 仓库与自动同步
+
+状态：首批平台已实施
+
+## 1. Current State
+
+当前 CLI 主仓库：
+
+- npm 包名为 `@itpay/cli`，当前版本由 `package.json` 管理。
+- `npm run check` 执行类型检查、测试覆盖率和打包 smoke test。
+- main 分支 CD 在验证后发布精确 npm 版本。
+- npm 包已经包含 `bin/`、`dist/src/`、`docs/`、`skills/`、README 和 LICENSE。
+- CLI 运行依赖 Node.js 18+，并依赖 `commander`、`qrcode`。
+- `skills/itpay/SKILL.md` 是当前通用 Skill 合同，但没有四个平台各自的 manifest、目录结构和商店发布材料。
+
+只复制 npm 包 tarball 并不等于自包含 bundle，因为 npm tarball 不包含生产 `node_modules`。真正的 bundle 必须在发布时装入精确生产依赖，或者未来另行构建单文件/原生可执行文件。
+
+## 2. Target Behavior
+
+建立四个独立平台仓库。每个仓库只维护：
+
+```text
+平台 manifest 和适配说明
+平台专用 SKILL.md
+由自动化生成的 vendor/itpay-cli bundle
+bundle.lock.json
+平台测试与发布材料
+```
+
+CLI 发布后：
+
+```text
+@itpay/cli@X.Y.Z 发布成功
+  -> 各平台仓库定时读取 npm dist-tags.latest
+  -> 下载精确 X.Y.Z 和 npm integrity
+  -> 安装精确 production dependencies
+  -> 生成 bundle 和 lock
+  -> 运行无全局 CLI smoke test
+  -> 创建同步 PR
+  -> 人工审查平台差异
+  -> 合并、打 tag、按平台上传/发布
+```
+
+## 3. Scope
+
+### In scope
+
+- 四个独立仓库和平台 manifest。
+- 通用 CLI bundle 生成脚本。
+- npm 版本、integrity、源 commit 的锁定记录。
+- CLI 发布后的跨仓同步 PR。
+- 无全局 CLI、无运行时 npm 下载的测试。
+- macOS、Linux、Windows 平台适配验证。
+- 平台审核包、release notes 和回滚规则。
+
+### Out of scope
+
+- 把 CLI 源码复制到四个仓库继续开发。
+- 每个平台 fork 一套业务逻辑。
+- 运行时自动执行 `npm install -g @itpay/cli@latest`。
+- 在 CLI 发布时绕过平台审核自动公开商店版本。
+- 第一阶段引入新的单文件打包器或原生二进制工具链。
+
+## 4. 仓库布局
+
+### OpenAI
+
+```text
+itpay-skill-openai/
+  plugin metadata / submission assets
+  skills/itpay/SKILL.md
+  skills/itpay/scripts/itpay
+  skills/itpay/vendor/itpay-cli/
+  bundle.lock.json
+  tests/
+  submission/
+```
+
+ChatGPT 云端工作流优先调用远程 MCP；本地 Codex 在平台允许 shell 且 bundle 可执行时才能使用 bundled CLI。Skill 必须明确这个选择，不能在 ChatGPT 沙箱里把 `~/.itpay-v3` 当长期用户认证。
+
+### Claude Code
+
+```text
+itpay-skill-claude-code/
+  .claude-plugin/marketplace.json
+  plugins/itpay/
+    .claude-plugin/plugin.json
+    skills/itpay/SKILL.md
+    bin/itpay
+    vendor/itpay-cli/
+    .mcp.json               # 远程 MCP 上线时加入
+  bundle.lock.json
+  README.md
+```
+
+一个 Claude 平台仓库同时承载 marketplace catalog 和 ItPay plugin，不另建第五个仓库。Claude Code 会把 plugin root 的 `bin/` 加入 Bash PATH。`bin/itpay` 只负责定位本仓库内 vendor 入口，不搜索或调用全局 `itpay`。
+
+### Gemini CLI
+
+```text
+itpay-skill-gemini-cli/
+  gemini-extension.json
+  skills/itpay/SKILL.md
+  bin/itpay
+  vendor/itpay-cli/
+  bundle.lock.json
+  README.md
+```
+
+manifest 位于绝对根目录。Skill 命令使用 `${extensionPath}` 定位 bundle，不依赖安装目录名称。
+
+### WorkBuddy
+
+```text
+itpay-skill-workbuddy/
+  SKILL.md
+  scripts/itpay
+  vendor/itpay-cli/
+  bundle.lock.json
+  README.md
+```
+
+最终压缩结构以 WorkBuddy 实际上传校验结果为准。当前官方文档确认可以上传本地技能包，但未公开社区 SkillHub 提交 schema，因此不要预先创造私有 manifest。
+
+## 5. Bundle 合同
+
+### 第一阶段产物
+
+平台按审核环境选择现有的两种构建格式：
+
+```text
+npm-tree:
+  vendor/itpay-cli/package/       npm 包内容
+  vendor/itpay-cli/node_modules/  仅 production dependencies
+
+single-file-esm:
+  vendor/itpay-cli/itpay-cli.bundle.mjs
+  vendor/itpay-cli/docs/agent/buyer/
+  vendor/itpay-cli/licenses/
+```
+
+WorkBuddy 和 OpenClaw 使用 `single-file-esm`，上传包不得包含任何 `node_modules`。npm 依赖只允许出现在 CI 临时构建目录；运行时不得联网安装。宿主必须已有 Node.js 18+。如果某平台审核环境没有 Node，再单独启动“standalone executable”任务；不要在还没有失败证据时提前维护多架构二进制。
+
+### `bundle.lock.json`
+
+至少包含：
+
+```json
+{
+  "schemaVersion": 1,
+  "package": "@itpay/cli",
+  "version": "2.0.14",
+  "npmIntegrity": "sha512-...",
+  "sourceGitSha": "...",
+  "generatedAt": "2026-07-21T00:00:00Z",
+  "node": ">=18"
+}
+```
+
+不要把 token、registry credential、构建机路径或本地身份写入 lock。
+
+### 启动器规则
+
+- 只调用 bundle 内的 CLI 入口。
+- 正确转发全部参数、stdout、stderr 和 exit code。
+- 不修改 `HOME`，使本地平台继续复用真实 `~/.itpay-v3`。
+- 不回退到 PATH 中的另一个 `itpay`，避免同机双版本不确定性。
+- `itpay --version` 必须等于 `bundle.lock.json.version`。
+
+用户全局安装的 CLI 可以同时存在：终端里执行全局 `itpay` 使用全局版本；Skill 内必须调用平台 bundle 的绝对路径或 plugin PATH 中的启动器。两者共享同一 `~/.itpay-v3` Device schema，因此共享本地 Device 身份，但代码版本由调用路径明确决定。
+
+## 6. Implementation Steps
+
+### Step 1：建立 bundle 生成器
+
+位置：优先放在 CLI 主仓库 `scripts/`，四个仓库调用同一已发布脚本或复制极小且固定的生成逻辑。
+
+- 输入必须是精确 semver，拒绝 `latest`、范围和未发布版本。
+- 从 npm registry 读取版本、dist.integrity 和 gitHead。
+- 下载 tarball并验证 integrity。
+- 安装 `--omit=dev --ignore-scripts` 的精确生产依赖。
+- 删除 npm cache、测试临时文件和不需要的元数据。
+- 生成 `bundle.lock.json`。
+
+依赖：现有 npm 发布成功。
+
+### Step 2：建立四个平台仓库
+
+- 每个仓库只保留一个平台的 manifest、Skill、bundle、测试和发布说明。
+- 平台专用 Skill 从当前 `skills/itpay/SKILL.md` 派生，但认证、路径和工具选择规则允许平台差异。
+- 通用业务规则不得四处手工修改；同步器每次更新时生成或校验通用段落。
+- 支付相关公共 Skill 默认只引导外部 Checkout；operator escape hatch 不作为推荐工作流。
+
+依赖：Step 1。
+
+### Step 3：加入仓库内验证
+
+每个平台至少验证：
+
+```text
+没有全局 itpay 命令
+不允许测试过程访问 npm registry
+bundle itpay --version == lock.version
+bundle itpay skill show itpay --json 成功
+平台 manifest 可被官方 validator/CLI 读取
+启动器路径含空格时仍可运行
+bundle 不包含凭据、.env、~/.itpay-v3 或 npm token
+```
+
+本地身份与网络业务测试使用临时 HOME；不得触碰开发者真实 `~/.itpay-v3`。
+
+依赖：Step 2。
+
+### Step 4：CLI 发布后创建同步 PR
+
+CLI 主仓库在 `main` 提供 reusable workflow。各平台仓库每小时错峰运行 caller workflow，并可手动触发；npm `dist-tags.latest` 或请求的 bundle format 与当前 `bundle.lock.json` 不同时更新。平台仓库自身的 `GITHUB_TOKEN` 写入本仓库，因此不需要跨仓 PAT，也不会在 CLI 发布失败时提前同步未发布版本。
+
+检测到新版本后：
+
+- 重新生成 bundle；
+- 更新 manifest 版本、lock、changelog；
+- 跑全套测试；
+- 对启用 Skill 差异跟踪的平台，比较旧、新 `sourceGitSha` 的中心 `skills/itpay/SKILL.md`；有差异时创建 Draft PR、附 diff 和人工合并清单，但不覆盖平台 Skill；
+- 创建或刷新 `automation/itpay-cli-X.Y.Z` 分支和同步 PR；
+- PR 描述列出 CLI commit、integrity、平台测试和是否需要商店重新审核。
+
+同步 workflow 只开 PR，不合并、不打 tag、不发布平台商店版本。
+
+依赖：Step 3。
+
+### Step 5：平台发布和回滚
+
+- 合并同步 PR 后为平台仓库打与 manifest 一致的 tag。
+- OpenAI、Claude 官方市场和 WorkBuddy 按各自审核流程上传；Gemini GitHub Release 可由 tag 自动生成。
+- 保存每个平台已发布 CLI 版本矩阵。
+- 回滚通过重新发布上一个已验证 bundle 对应的平台版本，不修改或删除用户 Device 身份。
+
+依赖：Step 4。
+
+## 7. API / Data / Type Changes
+
+CLI 业务 API：无。
+
+新增发布合同：
+
+- `bundle.lock.json` schema。
+- CLI reusable workflow 与各平台 caller workflow。
+- 每个平台 manifest 和平台版本。
+
+CLI 版本和平台包版本第一阶段保持相同，减少映射成本。若以后平台仅修改说明而 CLI 未变，再引入独立的 `pluginVersion`，同时保留 `cliVersion`；现在不提前增加双版本系统。
+
+## 8. Tests / Verification
+
+### 自动化
+
+- bundle integrity、精确版本和依赖完整性。
+- 无全局 CLI、离线 smoke、路径含空格、Windows 启动。
+- Skill frontmatter/manifest 校验。
+- secret scan 和危险文件清单。
+- 发布矩阵与 npm 当前版本漂移检测。
+
+### 手动
+
+- 四个平台全新安装。
+- 同机存在全局旧版 CLI 时，Skill 仍调用 bundle 版本。
+- Skill 更新后 bundle 版本更新，但 `~/.itpay-v3/device` 未变化。
+- 平台卸载 Skill 后不删除用户已有 CLI Device 身份；是否保留平台专用缓存按平台规则处理。
+
+## 9. Risks / Uncertainties
+
+- OpenAI Skill 沙箱是否提供满足要求的 Node 运行时不能作为稳定合同；ChatGPT 路径应以远程 MCP 为主。
+- `single-file-esm` 仍依赖宿主 Node.js 18+；未来引入原生 Node addon 时需要重新验证 bundling。
+- 四个仓库意味着四套审核节奏，但不意味着四套 CLI 业务实现。
+- WorkBuddy 公共 SkillHub 提交通道未公开，自动化只能先生成可上传包。
+- 平台安全扫描可能拒绝支付或可执行 bundle；拒绝原因应反馈到相应平台仓库，不改变其他平台已通过版本。
+
+## 10. Checkpoint
+
+首批仓库、生成器和无跨仓凭据的同步 workflow 已完成。剩余 checkpoint 是各平台审核与人工发布；这些步骤不由同步 workflow 自动执行。

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

@@ -0,0 +1,271 @@
+# 各平台制作、验证和上传手册
+
+状态：发布操作手册
+规则核对日期：2026-07-21
+
+平台规则会变化。每次正式提交前重新打开本文链接核对，不根据旧截图操作。
+
+## 0. 共用发布前检查
+
+所有平台先满足：
+
+- 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 参数。
+- 准备网站、支持、隐私政策、服务条款、退款说明和公开联系方式。
+- 准备允许和禁止场景测试；禁止场景必须停止或转交人类。
+
+## 1. OpenAI：ChatGPT + Codex
+
+### 选择的产品形态
+
+提交 **app-plus-skills plugin**，而不是 skills-only：
+
+```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` 描述成正常恢复路径。
+- 测试账号使用测试商户和限额，不要求审核人员真实付款。
+
+### 官方依据
+
+- [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/)
+
+## 2. Claude Code
+
+### 产品形态
+
+使用 Claude Plugin：
+
+```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 上线时）
+```
+
+Claude Code 会将 plugin root 的 `bin/` 加入 Bash PATH，并把市场插件复制到 `~/.claude/plugins/cache`。插件不得引用目录外文件；持久数据应使用 `${CLAUDE_PLUGIN_DATA}`，但 ItPay Device Authority 仍使用用户 HOME 下的 `~/.itpay-v3`，不要写 plugin cache。
+
+### 制作与测试
+
+1. `plugins/itpay/bin/itpay` 调用 plugin 内 vendored CLI，不调用全局 CLI。
+2. `plugins/itpay/skills/itpay/SKILL.md` 只引用 plugin 内路径或 PATH 中这个启动器。
+3. MCP 配置中的内部路径使用 `${CLAUDE_PLUGIN_ROOT}`。
+4. 执行：
+
+```bash
+claude plugin validate .
+claude --plugin-dir .
+```
+
+5. 在同时安装全局旧版 `itpay` 的机器上确认 Skill 使用 bundle 版本。
+6. 更新 plugin 后运行 `/reload-plugins` 或重启会话验证新版本。
+
+### 独立分发
+
+可以先用同一个 Claude 平台仓库中的 marketplace：
+
+```text
+itpay-skill-claude-code/
+  .claude-plugin/marketplace.json
+  plugins/itpay/
+```
+
+用户执行：
+
+```bash
+/plugin marketplace add itpay-ai/<marketplace-repo>
+/plugin install itpay@<marketplace-name>
+```
+
+marketplace entry 使用相对 source `./plugins/itpay`。版本字段变化后用户才会收到对应更新；不要长期指向浮动未验证分支。
+
+### 提交官方市场
+
+1. 完成 README、版本策略、manifest、验证和测试。
+2. 打开以下任一官方表单：
+   - `https://claude.ai/settings/plugins/submit`
+   - `https://platform.claude.com/plugins/submit`
+3. 提交 plugin 仓库、功能、权限、数据外发、MCP 和支持信息。
+4. 根据审核反馈更新独立仓库并重新验证。
+
+Claude 官方文档没有承诺所有提交都会收录，也没有提供 Skill 原生收费通道。ItPay 收费仍通过 ItPay 账号和外部 Checkout。
+
+### 官方依据
+
+- [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)
+
+## 3. Gemini CLI
+
+### 产品形态
+
+使用独立 Gemini Extension 仓库：
+
+```text
+gemini-extension.json
+skills/itpay/SKILL.md
+bin/itpay
+vendor/itpay-cli/
+```
+
+`gemini-extension.json` 必须位于仓库或 release archive 的绝对根目录。manifest `name` 使用小写和连字符，`version` 与 GitHub Release tag 保持一致。
+
+### 制作
+
+最小 manifest 由平台仓库实施时按当时 schema 生成，核心字段：
+
+```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 .
+```
+
+重启 Gemini CLI，确认：
+
+- `/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>
+```
+
+### 官方依据
+
+- [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

@@ -0,0 +1,32 @@
+# 首批平台执行状态（2026-07-22）
+
+首批按真实发布面拆成四个可落地仓库；豆包单独列为阻塞，不创建占位仓库。
+
+| 产品面 | 仓库 | 形态 | 当前可做 | 外部阻塞 |
+| --- | --- | --- | --- | --- |
+| 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.16` 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 唯一真源是 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` 的正式版。发现版本高于各自 `bundle.lock.json` 后，调用 CLI `main` 上的统一 reusable workflow，重建对应格式的 bundle、运行仓库测试，并以平台仓库自己的 `GITHUB_TOKEN` 创建更新 PR。该流程不需要 PAT，也不会自动合并或发布商店版本。
+
+## 已发现的现有资产
+
+`itpay-ai/skill` 是旧的多平台通用仓库，固定 CLI 2.0.11，并对 bundle 做过平台 Agent Type patch。首批独立仓库只复用其已验证的 wrapper/test 思路，不再手工 patch CLI。旧仓库在迁移完成前保留，之后再决定归档或改为索引仓库。
+
+## 豆包判断
+
+截至 2026-07-22，没有找到豆包官方的 `SKILL.md + 可执行 bundle` 上传或商店提交流程。公开报道显示豆包智能体功能已于 2026-07-15 下线。扣子、火山方舟 MCP 市场和 TRAE 是不同产品面，不能未经确认就用它们代替“豆包上架”。

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

@@ -0,0 +1,99 @@
+# ItPay MCP 认证与多平台 Bundle Skill 落地方案
+
+状态：首批平台仓库与 bundle 同步已实施
+最后核对：2026-07-22
+
+## 目标
+
+下一阶段只做两个核心任务：
+
+1. 为远程 MCP 建立独立的用户 OAuth 认证通道，同时保留现有 CLI Device Authority，不让两套身份互相覆盖。
+2. 为 OpenAI、Claude Code、Gemini CLI、WorkBuddy 分别维护发布仓库；每个 Skill/Plugin 自带固定版本的 CLI bundle，并在 CLI 发布后自动发起同步更新。
+
+具体文件：
+
+- [任务一：MCP 认证系统](./01-mcp-authentication.md)
+- [任务二：多平台 Bundle Skill 仓库与同步](./02-platform-bundle-repositories.md)
+- [各平台制作、验证和上传手册](./03-platform-publishing.md)
+- [首批平台执行状态（2026-07-22）](./04-first-wave-platforms.md)
+
+## 已确认的当前状态
+
+当前 CLI 的身份不是网页登录用户，而是本机设备身份：
+
+```text
+~/.itpay-v3/device/device-private.pem  Ed25519 私钥，0600
+~/.itpay-v3/device/identity.json       Device、Agent Instance、短期 session
+```
+
+`src/state/device_authority.ts` 为受保护请求生成：
+
+```text
+Authorization: ItPayDevice <session>
+X-ItPay-Agent-Instance-ID: <id>
+X-ItPay-Agent-Type: <type>
+X-ItPay-Agent-Signature: <signature>
+```
+
+它适合 Codex CLI、Claude Code、Gemini CLI、WorkBuddy 等本地运行时，但不能作为 ChatGPT 等云端会话的稳定用户身份。CLI 还支持通过 `ITPAY_BEARER_TOKEN` 执行账号范围命令，但目前没有面向 MCP 平台连接的完整 OAuth 生命周期。
+
+## 目标身份模型
+
+```text
+本地 Agent
+  -> CLI Device Authority
+  -> device principal / agent instance
+  -> ItPay Backend
+
+云端 Chat 平台
+  -> ItPay MCP OAuth
+  -> user principal / OAuth client connection
+  -> ItPay Backend
+
+两条通道
+  -> 可关联到同一 ItPay account
+  -> 共用订单、套餐和授权政策
+  -> 不共用私钥、session、token 文件或认证 Header
+```
+
+`~/.itpay-v3` 只能表示某个本地安装；ItPay 后端的稳定 `user_id` 才表示收费用户。
+
+## 发布仓库建议
+
+以下名称是建议值，创建仓库时可按组织规范调整：
+
+| 平台 | 建议仓库 | 公开形态 |
+| --- | --- | --- |
+| OpenAI | `itpay-skill-openai` | MCP App + bundled Skill Plugin |
+| Claude Code | `itpay-skill-claude-code` | Claude Plugin，含 `skills/`、`bin/`、可选 `.mcp.json` |
+| Gemini CLI | `itpay-skill-gemini-cli` | Gemini Extension，含 `gemini-extension.json` 和 `skills/` |
+| WorkBuddy | `itpay-skill-workbuddy` | 可上传技能包；公共 SkillHub 发布待平台确认 |
+
+不要把四个平台适配器放回 CLI 主仓库，也不要让平台仓库成为 CLI 源码的第二份手工副本。CLI 主仓库发布 npm 版本；平台仓库只消费一个精确版本并保存可验证的 bundle。
+
+## 执行顺序
+
+1. 完成任务一的 OAuth 最小闭环：登录、回调、刷新、撤销、MCP 鉴权和账号映射。
+2. 先建立 Claude Code 和 Gemini CLI 仓库，验证本地 bundle 与现有 Device Authority。
+3. 建立 OpenAI 仓库，把同一 Plugin 中的 MCP OAuth 路径和本地 Codex bundle 路径分开。
+4. 建立 WorkBuddy 技能包并完成本地上传验证；取得 SkillHub 发布入口后再公开。
+5. 在 CLI npm 发布成功后触发四个仓库的同步 PR。
+6. 各平台分别审核、发布和回滚，不从 CLI 发布工作流直接绕过平台审核。
+
+## 统一完成标准
+
+- 本地 CLI 升级前后的 Device ID、私钥和 quota lineage 不被 MCP 登录修改。
+- MCP token 不能用于 `ItPayDevice` Header；Device session 也不能访问 MCP 用户端点。
+- 同一 ItPay 用户可以从不同平台 OAuth 登录，并看到其有权访问的账号范围数据。
+- 每个平台包内记录 CLI 版本、npm integrity 和 CLI 源提交。
+- bundle 在无全局 `itpay`、无运行时 npm 下载的干净环境中通过 smoke test。
+- Skill 不读取或打印 `~/.itpay-v3` 中的私钥、session、Bearer token。
+- 支付仍使用外部 Checkout 和人类确认；MCP/Skill 不采集银行卡、CVV、支付密码或钱包私钥。
+
+## 当前不做
+
+- 不建立第二套 ItPay 用户数据库。
+- 不把 ChatGPT、Claude 或 Gemini 平台账号 ID 当作 ItPay 主账号。
+- 不用 Git submodule、运行时 `npm install -g` 或 `latest` 保持同步。
+- 不自动提交或发布未经人工确认的平台商店版本。
+- 不承诺 WorkBuddy SkillHub 公共上架，直到取得官方发布入口和审核规则。