@itpay/cli 2.0.14 → 2.0.15

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

@@ -0,0 +1,270 @@
+# 各平台制作、验证和上传手册
+
+状态：发布操作手册
+规则核对日期：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` 的自包含 Node bundle。
+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 和版本更新。
+
+### 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/README.md

@@ -0,0 +1,98 @@
+# ItPay MCP 认证与多平台 Bundle Skill 落地方案
+
+状态：拟定，等待实施
+最后核对：2026-07-21
+
+## 目标
+
+下一阶段只做两个核心任务：
+
+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)
+
+## 已确认的当前状态
+
+当前 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 公共上架，直到取得官方发布入口和审核规则。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.0.14",
+  "version": "2.0.15",
   "description": "The single ItPay CLI entry point for buy workflows and future sell workflows.",
   "type": "module",
   "bin": {

package/skills/itpay/SKILL.md

@@ -19,7 +19,7 @@ Use the CLI as the only ItPay control surface. Never recreate API calls or hardc
 
 ## Critical Rules
 
-- The production CLI Backend is fixed to `https://app.itpay.ai`. Never use an environment variable, alternate launcher, or recovery path to redirect it.
+- The CLI defaults to production `https://app.itpay.ai`. Only an explicit test may use the exact prefix `ITPAY_BACKEND_URL=https://dev.itpay.ai`; never use another Backend. While testing dev, execute every returned command unchanged so that prefix is preserved.
 - Keep one honest Agent Type, one CLI/Node launcher, and one Host-approved permission context for the whole flow. Supported types: `codex-desktop`, `codex-cli`, `claude-code-desktop`, `claude-code-cli`, `workbuddy`.
 - WorkBuddy: before any ItPay Bash command that persists `~/.itpay-v3`, set the Shell tool parameter `dangerouslyDisableSandbox` to `true`. If the human denies that permission, the command did not run: stop and report it.
 - Windows, tasks, chats, processes, and model sessions are not new Agents. Never rotate Agent Type or identity to reset quota.
@@ -45,11 +45,11 @@ If `backend_contract_incompatible` returns `result.required_cli_version`, stop e
 ## Identity And Sessions
 
 - One local Ed25519 private key represents this ItPay installation. Never expose, copy, or rotate it to recover quota.
-- The CLI uses one production Device registration at `https://app.itpay.ai` with one Agent Instance per `agent_type`. Different windows and chats of the same type reuse it; different types get separate instances under that registration.
+- The CLI uses one local signing key with separate official Backend registrations. Each registration has one Agent Instance per `agent_type`; different windows and chats of the same type reuse it.
 - Every commerce command must keep the explicit `--agent-type` returned in `next` and `recovery`, or use one stable `ITPAY_AGENT_TYPE`. Never fall back to another type previously used on the machine.
 - The CLI renews an expired or rejected device session and retries the same request exactly once. If that retry still fails, stop and report it; do not loop, create a new identity, or switch Agent Type.
 - A revoked v2 device is not replaced automatically. It requires an explicit operator recovery path.
-- If an operator confirms that the `https://app.itpay.ai` Device registration database was reset, use `device recover --confirm-backend-reset`. This preserves the private key; never use it for ordinary session expiry or revocation.
+- If an operator confirms that the current official Backend registration database was reset, use the complete returned `device recover --confirm-backend-reset` command. This preserves the private key and other Backend registration; never use it for ordinary session expiry or revocation.
 - `--host` selects presentation. `--target` is only the destination chat/channel/open ID required by some Hosts. Neither is business input or identity.
 
 ## Envelope Rule