@itpay/cli 2.0.3 → 2.0.5

package/docs/agent/buyer/quickstart.json

@@ -2,191 +2,68 @@
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
   "topic": "quickstart",
-  "title": "ItPay V3 CLI Buyer Quickstart",
-  "purpose": "Teach an external agent the minimal safe path for using the current V3 itpay CLI package.",
+  "title": "ItPay CLI Buyer Quickstart",
+  "purpose": "Run the shortest safe discovery, Service Execution, Checkout, delivery, and refund flow using server-returned next commands.",
   "when_to_use": [
-    "The agent has just loaded the V3 npm package.",
-    "The user wants the agent to add a catalog item to the canonical server cart or create a checkout through the current V3 CLI.",
-    "The agent needs to know which commands exist right now."
+    "The agent has just installed this CLI version.",
+    "The user asks what ItPay can do or asks to use a published service."
   ],
   "required_state": {
     "needs": [
-      "itpay CLI installed",
-      "production app at https://app.itpay.ai, or an intentional ITPAY_BACKEND_URL override",
-      "catalog item id, variant id, and offer id from `itpay catalog list`",
-      "real agent runtime type supplied through --agent-type or ITPAY_AGENT_TYPE"
+      "the real supported Agent Type",
+      "the default API or an intentional ITPAY_BACKEND_URL override"
     ],
-    "must_not_need": [
-      "admin token",
-      "claim token",
-      "provider raw payload"
-    ]
+    "must_not_need": ["Admin access", "Provider secrets", "raw payload access"]
   },
   "commands": [
     {
-      "intent": "check backend readiness",
-      "command": "itpay readyz",
-      "success_signal": "the production backend reports ready and accepts this CLI contract"
+      "intent": "verify compatibility",
+      "command": "itpay --agent-type <agent_type> readyz --json",
+      "success_signal": "status is ready and next points to catalog list"
     },
     {
-      "intent": "browse available services",
+      "intent": "discover published services",
       "command": "itpay --agent-type <agent_type> catalog list --json",
-      "success_signal": "catalog items with variants and prices are displayed"
+      "success_signal": "a compact service journey, service_id, variants and prices are returned"
     },
     {
-      "intent": "start a catalog service without hardcoding its workflow",
-      "command": "itpay --agent-type <agent_type> services start <service_id>",
-      "success_signal": "a service_execution_id and server-derived next actions are displayed"
+      "intent": "start a generic service",
+      "command": "itpay --agent-type <agent_type> services start <service_id> --json",
+      "success_signal": "one service_execution_id, one preferred capability summary and one executable next command are returned"
     },
     {
-      "intent": "recover the next step from remembered server handles",
-      "command": "itpay next --json",
-      "success_signal": "JSON includes next_actions derived from server cart, service execution, or checkout handles"
+      "intent": "continue after every step or interruption",
+      "command": "<execute the exact next.command returned by the previous CLI envelope>",
+      "success_signal": "the next envelope reports one current state and at most one preferred action"
     },
     {
-      "intent": "add one line to the canonical server cart",
-      "command": "itpay cart add --item <catalog_item_id> --variant <catalog_variant_id> --offer <offer_id> --quantity 1 --host <client> --json",
-      "success_signal": "JSON includes cart_id, cart_item_id, service_execution_id when the line is service-backed, and top-level next_actions"
-    },
-    {
-      "intent": "read the next cart or service-backed action",
-      "command": "itpay cart next --json",
-      "success_signal": "JSON includes next_actions such as services invoke, services action, services checkout, or buy"
-    },
-    {
-      "intent": "show the current canonical server cart",
-      "command": "itpay cart show",
-      "success_signal": "the CLI prints persisted server cart items and service refs when present"
-    },
-    {
-      "intent": "remove a pre-checkout line if the human changes their mind",
-      "command": "itpay cart remove --line <cart_item_id>",
-      "success_signal": "the server cart is updated; quote-locked or checkout-bound lines return a conflict"
-    },
-    {
-      "intent": "invoke an agent-visible service capability after a service-backed cart or service start",
-      "command": "itpay services invoke <service_execution_id> --capability <capability_id> --input key=value",
-      "success_signal": "JSON with redacted execution status, safe result items, and next_actions"
-    },
-    {
-      "intent": "submit a human/agent service action when required by the service contract",
-      "command": "itpay services action <service_execution_id> --action <action_type> --result-item <result_item_id>",
-      "success_signal": "JSON with redacted execution status, accepted action, and next_actions"
-    },
-    {
-      "intent": "read the next Service Execution action",
-      "command": "itpay services next <service_execution_id> --json",
-      "success_signal": "JSON includes next_actions derived from the Service Execution read model and capabilities"
-    },
-    {
-      "intent": "create checkout from a confirmed service execution and render human handoff",
-      "command": "itpay services checkout <service_execution_id> --capability <paid_capability_id> [--email <email>] --json",
-      "success_signal": "quote lock is bound to the server cart item when present; JSON includes checkout_id, display_token, checkout_url, qr_png_url, and brand_qr_local_path"
-    },
-    {
-      "intent": "recover a lost or expired service checkout handoff",
-      "command": "itpay services checkout <service_execution_id> --resume --json",
-      "success_signal": "the same checkout_id is returned with a fresh short-lived display token and QR path"
-    },
-    {
-      "intent": "create checkout from a server cart that is ready for checkout",
-      "command": "itpay buy --cart <cart_id> --host terminal --contact-email <email>",
-      "success_signal": "checkout QR/URL rendered for the host"
-    },
-    {
-      "intent": "inspect checkout state",
-      "command": "itpay checkout --id <checkout_id> --token <display_token>",
-      "success_signal": "checkout presentation with status, items, payment intents"
-    },
-    {
-      "intent": "read an order",
-      "command": "itpay order <order_id>",
-      "success_signal": "order details with items and delivery artifacts"
-    },
-    {
-      "intent": "read a protected result after the human grants temporary access",
-      "command": "itpay --agent-type <agent_type> services read-result <service_execution_id>",
-      "success_signal": "the payload for this service execution is returned while its human grant is active"
-    },
-    {
-      "intent": "list account orders (needs ITPAY_BEARER_TOKEN)",
-      "command": "itpay orders --limit 20",
-      "success_signal": "list of orders"
-    },
-    {
-      "intent": "show install instructions",
-      "command": "itpay install [claude-code|codex|terminal|telegram|feishu]",
-      "success_signal": "step-by-step instructions for the target host"
-    },
-    {
-      "intent": "browse agent documentation",
-      "command": "itpay docs list",
-      "success_signal": "list of available doc topics"
+      "intent": "recover from local handles",
+      "command": "itpay --agent-type <agent_type> next --json",
+      "success_signal": "one Service Execution, Checkout, Cart, or Catalog recovery command is returned"
     }
   ],
   "agent_rules": [
-    "Every human-facing command should include the correct --host value.",
-    "For Telegram, Feishu, and Lark, provide --target or the CLI will reject.",
-    "Use --json for machine-readable output in agent flows.",
-    "Supply the real agent runtime type on commerce commands; the CLI persists one signed device identity and registered agent instances under ~/.itpay-v3/device.",
-    "Prefer top-level next_actions over hardcoded service-specific command sequences.",
-    "Use itpay next or itpay cart next to recover after interruption; these commands read server handles and do not treat local cart files as business truth.",
-    "For service-backed catalog items, read service_execution_id from `itpay cart add --json` before invoking service capabilities.",
-    "Do not use --pay or itpay pay for the normal buyer flow; first show the ItPay checkout QR/URL so the human enters the checkout page.",
-    "If buy emits an interaction request for missing contact fields, collect values and rerun with --contact-email/--contact-phone.",
-    "For services checkout, include --email only when next_actions includes it. Explain that protected delivery uses it to send the claim link; agent-visible paid results do not require email.",
-    "Do not assume checkout implies payment succeeded; it only creates a handoff.",
-    "Payment success is confirmed by backend checkout/order state, not by QR display or buyer claim.",
-    "A human grant applies only to its service execution and expires after 15 minutes; do not claim access to other orders or executions.",
-    "Use `itpay catalog list` to browse available services before buying.",
-    "Use `itpay docs show <topic>` to get detailed instructions on a specific topic.",
-    "Server cart, quota, execution, quote, checkout, and delivery facts persist in backend Postgres. ~/.itpay-v3/cart.json only caches last ids and explicit local drafts."
+    "Use the CLI as the control surface; do not call ItPay APIs directly or hardcode a service workflow.",
+    "Treat result as current facts, instruction as how to use those facts, next as the preferred executable action, and recovery as exceptional paths.",
+    "Run one state-changing command at a time and execute the exact next.command unchanged after filling only required user data.",
+    "Start a separate Service Execution for each independent service intent; quota remains shared according to Backend identity policy.",
+    "Ask the user for required email or contact values and explain their purpose; never invent them.",
+    "Agent-visible delivery is returned by services next. Protected delivery is read only by services read-result while a human grant is active.",
+    "A human grant is scoped to one delivery, its frozen authorized Agent audience, approved fields, and a 15-minute expiry.",
+    "Normal payment uses the ItPay Checkout handoff, not itpay pay."
   ],
   "forbidden": [
-    "Do not invent variant ids, offer ids, or catalog ids.",
-    "Do not invent admin, account-management, or grant-creation commands; the human grants access in the web UI and the CLI only reads an active grant.",
-    "Do not ask users to paste secrets into chat."
+    "Do not invent catalog, variant, offer, capability, result item, order or refund IDs.",
+    "Do not dump Backend DTOs, diagnostic events, renderer internals or secrets into user chat.",
+    "Do not bypass a grant, refund lock, ownership error or compatibility gate."
   ],
   "next_docs": [
-    {
-      "condition": "Need to understand cart-first checkout in detail",
-      "topic": "cart-checkout",
-      "file": "docs/agent/buyer/cart-checkout.json"
-    },
-    {
-      "condition": "Need to browse available services",
-      "topic": "catalog-list",
-      "file": "docs/agent/buyer/catalog-list.json"
-    },
-    {
-      "condition": "Need the checkout-to-payment handoff and verification rules",
-      "topic": "payment-flow",
-      "file": "docs/agent/buyer/payment-flow.json"
-    },
-    {
-      "condition": "Need to understand host rendering and interaction",
-      "topic": "render-hosts",
-      "file": "docs/agent/buyer/render-hosts.json"
-    },
-    {
-      "condition": "Need to inspect orders or create refunds",
-      "topic": "orders-refunds",
-      "file": "docs/agent/buyer/orders-refunds.json"
-    },
-    {
-      "condition": "Need to install or configure for a specific host",
-      "topic": "install-and-setup",
-      "file": "docs/agent/buyer/install-and-setup.json"
-    }
+    { "condition": "Need service catalog language", "topic": "catalog-list" },
+    { "condition": "Need Cart and Checkout routing", "topic": "cart-checkout" },
+    { "condition": "Need payment recovery", "topic": "payment-flow" },
+    { "condition": "Need Host-specific presentation", "topic": "render-hosts" },
+    { "condition": "Need order or refund recovery", "topic": "orders-refunds" },
+    { "condition": "Need install details", "topic": "install-and-setup" }
   ],
-  "search_terms": [
-    "quickstart",
-    "start",
-    "buyer flow",
-    "v3 cli",
-    "how to use",
-    "怎么用",
-    "开始",
-    "快速开始"
-  ]
+  "search_terms": ["quickstart", "service", "next", "recovery", "delivery", "refund"]
 }

package/docs/agent/buyer/render-hosts.json

@@ -2,78 +2,64 @@
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
   "topic": "render-hosts",
-  "title": "Host Rendering And Interaction Requests",
-  "purpose": "Teach the agent how the current V3 CLI renders checkout handoff and missing-data interaction prompts for each host.",
+  "title": "Agent Type And Checkout Handoff Rendering",
+  "purpose": "Use only the handoff fields returned for the current Agent Type and make the human Checkout visible on that surface.",
   "when_to_use": [
-    "The agent needs to choose the right --host value.",
-    "The agent needs to explain what the user will see in terminal, Trae/Codex, Telegram, or Feishu/Lark.",
-    "The flow emits an interaction request instead of immediate checkout."
+    "buy, services checkout, checkout, or pay returned a human handoff.",
+    "The human cannot see the QR image or Checkout link."
   ],
-  "required_state": {
-    "needs": [
-      "correct host selection"
-    ],
-    "optional": [
-      "target for Telegram / Feishu / Lark"
-    ]
-  },
-  "commands": [
+  "host_contracts": [
+    {
+      "agent_type": "codex-desktop",
+      "default_host": "codex",
+      "responsibility": "attach handoff.qr_local_path and show handoff.url or the returned markdown in the current desktop conversation"
+    },
     {
-      "intent": "render checkout for terminal",
-      "command": "itpay buy --host terminal --item <catalog_item_id> --variant <catalog_variant_id> --offer <offer_id>",
-      "success_signal": "terminal summary, links, Branded QR local path + mirrors, and an ATTACH block with status=downloaded are printed"
+      "agent_type": "codex-cli",
+      "default_host": "terminal",
+      "responsibility": "render only in a terminal the human is actually watching and show the Checkout URL"
     },
     {
-      "intent": "render checkout or interaction request for Trae / Codex style chat",
-      "command": "itpay buy --host trae --item <catalog_item_id> --variant <catalog_variant_id> --offer <offer_id> --require-contact email,phone",
-      "success_signal": "markdown with one inline data: image, an [ATTACH] IDE image reference block, and a structured itpay_input_request block is printed"
+      "agent_type": "claude-code-desktop",
+      "default_host": "claude-code",
+      "responsibility": "attach handoff.qr_local_path and show handoff.url or the returned markdown in the current desktop conversation"
     },
     {
-      "intent": "render chat-native buttons for Telegram",
-      "command": "itpay buy --host telegram --target <chat_id> --item <catalog_item_id> --variant <catalog_variant_id> --offer <offer_id>",
-      "success_signal": "openclaw_message and presentation payload plus presentation.ide_image_attach (status, local_path, mirrors, must_render_reason) are printed"
+      "agent_type": "claude-code-cli",
+      "default_host": "terminal",
+      "responsibility": "render only in a terminal the human is actually watching and show the Checkout URL"
     },
     {
-      "intent": "render interactive card output for Feishu or Lark",
-      "command": "itpay buy --host feishu --target <open_id_or_chat_id> --item <catalog_item_id> --variant <catalog_variant_id> --offer <offer_id>",
-      "success_signal": "interactive card JSON plus message.ide_image_attach (status, local_path, mirrors, must_render_reason) is printed"
+      "agent_type": "workbuddy",
+      "default_host": "plain-chat",
+      "responsibility": "send the returned Checkout URL and any usable image attachment to the current chat"
+    }
+  ],
+  "commands": [
+    {
+      "intent": "confirm the current Agent Type contract",
+      "command": "itpay install <agent_type> --json",
+      "success_signal": "the exact default Host and presentation responsibility are returned"
+    },
+    {
+      "intent": "recover a Checkout handoff",
+      "command": "itpay checkout --id <checkout_id> --token <display_token> --json",
+      "success_signal": "only handoff fields usable by the current Host are returned"
     }
   ],
   "agent_rules": [
-    "Use --host terminal only when the human is directly watching a terminal.",
-    "Use --host trae in Trae chat; it normalizes to the codex-style markdown renderer.",
-    "Telegram, Feishu, and Lark require --target.",
-    "Current V3 CLI can emit structured interaction requests, but Trae itself does not show a native popup unless a host adapter consumes that block.",
-    "Terminal can render images as ASCII when an image URL is available.",
-    "Telegram and Feishu/Lark can emit selector or input metadata for host-native adapters.",
-    "If an interaction request is emitted, collect the requested values and rerun the relevant command with those values rather than inventing them.",
-    "After buy/checkout/order output, the IDE image attach contract must be honoured: read the file at brand_qr_local_path (or any of brand_qr_mirrors) with the IDE's Read tool so the human sees the QR in the chat window. Do not declare success unless brand_qr_status is \"downloaded\" and the image is visible."
+    "Agent Type is stable identity; Host is presentation and may be explicitly overridden.",
+    "A local QR path is not visible until the Agent attaches or renders that file on the human-facing surface.",
+    "Do not claim the handoff was shown until both a usable payment image or QR and the Checkout URL are visible.",
+    "IM Hosts that require a target must receive --target; the initial five Agent Types currently default to desktop, terminal, or plain-chat Hosts."
   ],
   "forbidden": [
-    "Do not claim Trae currently has a built-in native popup if only markdown is printed.",
-    "Do not handwrite Telegram buttons when the CLI already returns a native presentation payload.",
-    "Do not drop required --target fields for IM hosts."
+    "Do not expose display tokens separately from the tokenized Checkout handoff.",
+    "Do not print base64 images, mirror lists, renderer debug state, or provider QR URLs.",
+    "Do not claim a desktop attachment exists when only a filesystem path was printed."
   ],
   "next_docs": [
-    {
-      "condition": "Need the overall start sequence",
-      "topic": "quickstart",
-      "file": "docs/agent/buyer/quickstart.json"
-    },
-    {
-      "condition": "Need cart-first handoff details",
-      "topic": "cart-checkout",
-      "file": "docs/agent/buyer/cart-checkout.json"
-    }
+    { "condition": "Need payment verification rules", "topic": "payment-flow" }
   ],
-  "search_terms": [
-    "render",
-    "host",
-    "telegram",
-    "trae",
-    "codex",
-    "interaction request",
-    "selector",
-    "输入框"
-  ]
+  "search_terms": ["host", "agent type", "QR", "markdown", "terminal", "desktop", "workbuddy"]
 }

package/docs/cli-reference/agent-types.md

@@ -0,0 +1,45 @@
+# Agent Type And Host Contract
+
+`--agent-type` 表示谁在运行 CLI，用于设备登记、Agent 实例归属和定制 instruction。`--host` 表示输出展示在哪里，用于选择二维码、链接或消息的渲染方式。两者不可混用。
+
+## 首批支持类型
+
+| Agent Type | 默认 Host | 初始 instruction 差异 |
+|---|---|---|
+| `codex-desktop` | `codex` | 返回可在 Codex 桌面对话中展示的本地二维码图片和付款链接，要求 Agent 将图片实际发到当前对话。 |
+| `codex-cli` | `terminal` | 在用户可见终端渲染二维码并输出付款链接；若用户不看该终端，要求改用正确 Host。 |
+| `claude-code-desktop` | `claude-code` | 返回桌面对话可展示的 Markdown 图片和付款链接，要求先展示再等待。 |
+| `claude-code-cli` | `terminal` | 在用户可见终端输出二维码和链接，不声称已在桌面对话展示。 |
+| `workbuddy` | `plain-chat` | 初期返回清晰付款链接和通用图片附件信息；原生卡片细节后续补充。 |
+
+## 通用规则
+
+- commerce 命令必须传 `--agent-type` 或设置 `ITPAY_AGENT_TYPE`。
+- Agent Type 必须稳定；同一运行时不得临时换名。
+- 显式 `--host` 覆盖默认 Host，但不改变已登记的 Agent Type。
+- Host 只影响 `instruction` 和 `handoff`，不得改变金额、订单、权限、quota 或交付状态。
+- 非展示命令在五种 Agent Type 下返回相同业务结果，只允许 instruction 措辞不同。
+
+## Checkout Handoff 最小合同
+
+```json
+{
+  "status": "human_checkout_required",
+  "result": {
+    "checkout_id": "<checkout_id>",
+    "amount": "<amount> <currency>"
+  },
+  "handoff": {
+    "url": "<checkout_url>",
+    "qr_local_path": "<optional_local_path>",
+    "markdown": "<optional_host_ready_markdown>"
+  },
+  "instruction": "<agent-type-specific instruction>",
+  "next": {
+    "command": "itpay checkout --id <checkout_id> --token <display_token> --json"
+  },
+  "recovery": []
+}
+```
+
+只返回当前 Host 能使用的 `handoff` 字段，不返回镜像路径列表、渲染器内部状态或重复的 action 描述。

package/docs/cli-reference/commands/buy.md

@@ -0,0 +1,167 @@
+# `itpay buy`
+
+## 范围与意义
+
+为普通 Catalog 项目或已绑定 Service Quote 的 canonical Cart 创建一个 ItPay Checkout，并按当前 Agent Type 把付款入口交给用户。命令只创建或恢复 ItPay Checkout，不把“用户说已付款”当作付款成功。
+
+未报价的 service-backed line 不可购买；命令停止并转向 `services next`。已通过 `cart add --quote` 锁定输入和价格的服务行可以合并结算，每个 Order Item 仍映射回独立 Execution、Capability 和交付路径。
+
+**直接上游：**
+
+- `cart add` 创建的 canonical Cart；
+- `cart add --local` 创建的本地兼容草稿；
+- Catalog 返回的一组完整 `item / variant / offer`；
+- 已知的普通 canonical `cart_id`。
+
+**直接下游：** `checkout` 查询同一 Checkout 的权威状态。付款确认后，再按其返回的 `next` 进入订单或服务履约。
+
+## 语法
+
+```bash
+itpay buy [--json]
+
+itpay buy --cart <cart_id> [--json]
+
+itpay buy \
+  --item <catalog_item_id> \
+  --variant <catalog_variant_id> \
+  --offer <offer_id> \
+  [--quantity <positive_integer>] [--json]
+```
+
+通用选项：
+
+```text
+--ref <client_reference_id>
+--contact-email <email>
+--contact-phone <phone>
+--require-contact <email,phone>
+--host <host>
+--target <target>
+--qr-format <unicode|utf8|ansi|terminal>
+--qr-file <path>
+--pay
+--method <alipay|wechatpay>
+--no-wait
+--timeout <positive_seconds>
+--json
+```
+
+## 参数合同
+
+| 参数 | 必填 | 规则 |
+|---|---:|---|
+| `--cart` | 条件必填 | 使用一个已存在的普通或全量已报价 canonical Cart。不能和 inline 三元组同时使用。 |
+| `--item` | 条件必填 | Inline 购买时必须与 `--variant`、`--offer` 一起提供。只能使用 Catalog 返回值。 |
+| `--variant` | 条件必填 | 同上。 |
+| `--offer` | 条件必填 | 同上。 |
+| `--quantity` | 否 | 正整数，默认 `1`；只用于 inline 项目。 |
+| `--ref` | 否 | 调用方自己的业务引用；不承担幂等职责。 |
+| `--contact-email` | 条件必填 | 普通 Cart 或兼容旧 Quote 缺少所需邮箱时使用，值必须来自用户；新版 Service Quote 会自动携带已确认邮箱。 |
+| `--contact-phone` | 条件必填 | `--require-contact` 包含 `phone` 时必填，值必须来自用户。 |
+| `--require-contact` | 否 | 只接受 `email`、`phone`；缺失时先询问用户，禁止 Agent 编造。 |
+| `--host` | 否 | 默认由 `--agent-type` 推导；只改变 handoff 展示，不改变交易事实。 |
+| `--target` | 条件必填 | 只有要求目标会话的 IM Host 才需要；当前首批五种 Agent Type 无需提供。 |
+| `--qr-format` | 否 | 非 JSON 的终端渲染选项。 |
+| `--qr-file` | 否 | 非 JSON handoff 的明确二维码文件路径。 |
+| `--pay` | 否 | 创建 Payment Intent 的集成/运维入口；普通 Agent 流程只展示 Checkout。 |
+| `--method` | 否 | 只接受 `alipay` 或 `wechatpay`，默认 `alipay`；仅随 `--pay` 生效。 |
+| `--no-wait` | 否 | 只能与 `--pay` 一起使用。 |
+| `--timeout` | 否 | 等待付款事件的正整数秒数，默认 `120`。 |
+| `--json` | 否 | 输出本文定义的紧凑机器合同，不输出字符二维码或图片二进制。 |
+
+不传 `--cart` 或 inline 三元组时，命令使用本机保存的 active canonical Cart；若没有，则使用本地普通草稿创建 canonical Cart。两者都没有时返回 `cart_empty`。
+
+## 标准 JSON 输出
+
+### 等待用户付款
+
+```json
+{
+  "status": "human_checkout_required",
+  "result": {
+    "checkout_id": "<checkout_id>",
+    "payment": "pending",
+    "amount": "<amount> <currency>",
+    "item_count": 1
+  },
+  "handoff": {
+    "url": "<tokenized_checkout_url>",
+    "qr_local_path": "<optional_host_ready_file>",
+    "markdown": "<desktop_only_optional_markdown>",
+    "qr_image_url": "<plain_chat_only_optional_url>"
+  },
+  "instruction": "<current_host_instruction>",
+  "next": {
+    "command": "itpay checkout --id <checkout_id> --token <display_token> --json",
+    "reason": "稍后查询同一笔 Checkout 状态"
+  },
+  "recovery": []
+}
+```
+
+`handoff` 只保留当前 Host 可以使用的字段。不得返回二维码 base64、镜像路径数组、renderer 状态、原始后端 DTO 或重复的 `agent_action`。
+
+**Instruction：** 先把 handoff 中的付款入口实际展示给用户，再等待用户操作；不要创建第二个 Checkout。
+
+### `--pay` 已观察到付款事件
+
+```json
+{
+  "status": "payment_event_observed",
+  "result": {
+    "checkout_id": "<checkout_id>",
+    "payment": "verified",
+    "amount": "<amount> <currency>",
+    "item_count": 1,
+    "payment_intent_id": "<payment_intent_id>",
+    "payment_intent_status": "<provider_status>"
+  },
+  "instruction": "已观察到付款确认事件；读取同一 Checkout 的权威完成状态，不要再次付款。",
+  "next": {
+    "command": "itpay checkout --id <checkout_id> --token <display_token> --json",
+    "reason": "读取订单和履约句柄"
+  },
+  "recovery": []
+}
+```
+
+事件观察不是订单 DTO。Agent 必须执行 `next.command`，不能自行宣称履约完成。
+
+## 幂等与中断恢复
+
+- CLI 在本机 operation journal 中为 `checkout.create:<cart_id>` 保存稳定幂等键。
+- HTTP 请求通过 `Idempotency-Key` 提交该键。
+- Checkout 响应丢失时，重跑同一命令会复用已保存的 canonical Cart 和同一幂等键。
+- 后端返回同一个待处理 Checkout，并轮换新的交接 token；不会创建第二笔订单。
+- Service Quote Cart 的联系信息由 Quote Lock 汇总；正常流程无需在 `buy` 重复传邮箱，旧 Quote 可显式补充。
+- Checkout 成功保存后，active Cart 句柄被清除，只保留 Checkout（以及可选 Service Execution）恢复句柄。
+- 不确定命令执行到哪一步时，先运行 `itpay next --json`，不得重新拼一笔购买。
+
+## 异常处理
+
+| 错误码 | 含义 | Agent 处理 |
+|---|---|---|
+| `buy_source_invalid` | Inline 三元组不完整，或与 `--cart` 混用。 | 从 Catalog 重新读取完整 ID，或只保留 `--cart`。 |
+| `cart_empty` | 没有本地草稿或 active canonical Cart。 | 执行 `catalog list`，不要猜 ID。 |
+| `missing_contact` | 缺少调用方声明的 required contact。 | 向用户询问后重跑同一命令；禁止编造。 |
+| `contact_field_invalid` | `--require-contact` 包含不支持字段。 | 只使用 `email`、`phone`。 |
+| `payment_method_invalid` | 付款方式不是允许值。 | 使用 `alipay` 或 `wechatpay`。 |
+| `buy_parameter_invalid` | quantity/timeout 非正整数，或 `--no-wait` 未配 `--pay`。 | 修正参数；本次不创建资源。 |
+| `service_quote_required` | Cart 含尚未绑定 Quote 的 Service Execution。 | 原样执行返回的 `services next <id> --json`；不要绕过 Quote 输入校验。 |
+| `idempotency_conflict` | 同一幂等操作被用于不同请求。 | 保留句柄并执行 `itpay next --json`，不要换键重建。 |
+| `buy_failed` | 网络或未知后端错误。 | 先执行 `itpay next --json` 或 `cart next --json` 恢复现有资源。 |
+
+所有参数错误都必须在 HTTP 和本地 Cart 变更前被拒绝。服务 Cart 只有每条 service-backed line 都绑定有效 Quote 时才能创建 Checkout；付款后 Backend 按 Order Item 分别推进 Execution。
+
+## Agent Type / Host
+
+| Agent Type | 默认 Host | JSON handoff | Instruction |
+|---|---|---|---|
+| `codex-desktop` | `codex` | `url`、可用时 `qr_local_path` 和 `markdown` | 把 `handoff.markdown` 原样发到当前 Codex 对话，确认二维码和链接可见后等待。 |
+| `codex-cli` | `terminal` | `url`、可用时 `qr_local_path` | 非 JSON 模式在用户可见终端渲染二维码；始终保留付款链接。 |
+| `claude-code-desktop` | `claude-code` | `url`、可用时 `qr_local_path` 和 `markdown` | 把 Markdown handoff 发到当前桌面对话，不能只输出本地路径。 |
+| `claude-code-cli` | `terminal` | `url`、可用时 `qr_local_path` | 在用户可见终端展示；不能声称桌面对话已收到图片。 |
+| `workbuddy` | `plain-chat` | `url`、可用时 `qr_local_path` 和 `qr_image_url` | 发送链接和可用图片附件，不虚构原生卡片。 |
+
+显式 `--host` 可以覆盖展示方式，但不会改变 Agent Type、设备身份、金额、权限或交易状态。