@itpay/cli 2.1.47 → 2.1.48

package/dist/src/state/config.js

@@ -1,5 +1,5 @@
-const CLI_VERSION = "2.1.47";
-const API_CONTRACT_REVISION = "sha256:3f4a94cd1755773ef7b2ff08cfca2e5adf33c0b4888af593dd832ffc52939365";
+const CLI_VERSION = "2.1.48";
+const API_CONTRACT_REVISION = "sha256:e61bd9998bddfaeee498d2306854f29a4e50c50a372acc26746b6c251c1b70f6";
 export {
   API_CONTRACT_REVISION,
   CLI_VERSION

package/docs/agent/buyer/cart-checkout.json

@@ -3,11 +3,11 @@
   "role": "buyer",
   "product_scope": "itpay is the single public Buyer CLI entry point, and $itpay is its user-facing Skill invocation. It covers services, railway planning and booking, orders, authorized purchased content and refunds.",
   "topic": "cart-checkout",
-  "title": "Canonical Cart And Checkout Routing",
-  "purpose": "Use the canonical server Cart and route service-backed lines through Service Execution without hardcoded service logic.",
+  "title": "Advanced Multi-Service Cart And Historical Checkout Recovery",
+  "purpose": "Use only for an explicitly requested multi-service cart or a historical pinned flow. Normal selected services use the Skill purchase route.",
   "when_to_use": [
-    "A catalog item or variant is ready to add.",
-    "An interrupted Cart or Checkout needs recovery."
+    "The human explicitly requests combining several services in one Cart.",
+    "An existing Cart or historical Checkout needs recovery."
   ],
   "commands": [
     {
@@ -21,12 +21,12 @@
       "success_signal": "service-backed lines route to services next; ordinary lines route to buy"
     },
     {
-      "intent": "create an ordinary Checkout",
+      "intent": "prepare an ordinary official Checkout; no payment request",
       "command": "itpay --agent-type <agent_type> buy --cart <cart_id> --json",
       "success_signal": "status is human_checkout_required and handoff contains only fields usable by the current Host"
     },
     {
-      "intent": "create or resume a service Checkout",
+      "intent": "historical pinned service Checkout compatibility",
       "command": "itpay --agent-type <agent_type> services checkout <service_execution_id> --capability <capability_id> [--input key=value] [--email <email>] --json",
       "success_signal": "one Checkout handoff is returned; rerun with --resume after output or token loss"
     }
@@ -37,7 +37,7 @@
     "Railway query and booking use distinct Service Executions for one purchase journey. Start another execution for an independent intent.",
     "Only non-rail capabilities explicitly requiring delivery email may ask its purpose and value. Railway notification contact belongs to the protected checkout page with verified account email reuse; the Agent must not guess or collect it in chat.",
     "A lost Checkout response is retried with the same Cart and persisted idempotency operation.",
-    "A single railway service checkout normally follows its booking execution; Cart is used only when the returned flow calls for it."
+    "A normal selected service follows services purchase on its original execution. Do not introduce Cart as an extra tutorial or recovery fallback."
   ],
   "forbidden": [
     "Do not call ordinary buy for a service-backed Cart line.",
@@ -61,5 +61,5 @@
     "resume",
     "contact"
   ],
-  "purchase_consent": "Candidate selection is not price approval. Service-backed quote/cart/checkout requires a current scoped approve_purchase record; use the complete server template, default false. Only genuine matching approval allows true; material price/subject/terms changes invalidate it. Restore an existing Checkout before creating anything."
+  "purchase_consent": "Advanced and historical quote/cart flows retain the current quote-bound approve_purchase template and genuine matching consent. Do not bypass its exact quote or expiry. Normal new services use the Skill purchase preparation rule instead."
 }

package/docs/agent/buyer/catalog-list.json

@@ -56,8 +56,7 @@
     },
     {
       "condition": "Non-rail Buyer selected a service and wants to purchase",
-      "topic": "cart-checkout",
-      "file": "docs/agent/buyer/cart-checkout.json"
+      "topic": "quickstart"
     }
   ],
   "search_terms": [
@@ -69,6 +68,5 @@
     "what to buy",
     "有哪些",
     "服务列表"
-  ],
-  "purchase_consent": "Candidate selection is not price approval. Service-backed quote/cart/checkout requires a current scoped approve_purchase record; use the complete server template, default false. Only genuine matching approval allows true; material price/subject/terms changes invalidate it. Restore an existing Checkout before creating anything."
+  ]
 }

package/docs/agent/buyer/payment-flow.json

@@ -6,13 +6,13 @@
   "title": "Human Checkout Handoff And Payment Verification",
   "purpose": "Show the ItPay Checkout to the human and recover authoritative payment state without creating duplicate payment resources.",
   "when_to_use": [
-    "buy or services checkout returned human_checkout_required.",
+    "services purchase, buy or historical services checkout returned an official human handoff.",
     "The agent restarted or lost the Checkout output before payment was confirmed."
   ],
   "commands": [
     {
       "intent": "present the Checkout handoff",
-      "command": "<execute the exact command returned by buy or services checkout>",
+      "command": "<show the already-returned official handoff on the current Host>",
       "success_signal": "the returned official URL and/or QR supported by the actual Host is visible to the human"
     },
     {
@@ -22,12 +22,12 @@
     },
     {
       "intent": "recover a service Checkout handoff",
-      "command": "itpay services checkout <service_execution_id> --resume --json",
+      "command": "itpay services purchase <service_execution_id> --resume --json",
       "success_signal": "the same unpaid Checkout is reused with a fresh short-lived handoff"
     }
   ],
   "agent_rules": [
-    "Normal buyer flow opens the ItPay Checkout page; itpay pay and buy --pay are operator escape hatches.",
+    "Normal preparation generates an official filling/payment page; it does not call payment or charge. The human completes actual payment on that page.",
     "Use only handoff fields returned for the current Host and make them actually visible to the human.",
     "Obtain only missing required agreement or material price/term changes. Reuse a valid explicit confirmation for unchanged terms; never invent it.",
     "For a railway journey, show one official checkout for all legs: one total/payment, separate issuance. The page shares its authoritative payment_deadline_at/server_now/payment_remaining_seconds; reaching zero requires reading current status, not declaring cancellation.",
@@ -66,6 +66,5 @@
     "付款后",
     "不要重复付款",
     "支付确认"
-  ],
-  "purchase_consent": "Candidate selection is not price approval. Service-backed quote/cart/checkout requires a current scoped approve_purchase record; use the complete server template, default false. Only genuine matching approval allows true; material price/subject/terms changes invalidate it. Restore an existing Checkout before creating anything."
+  ]
 }

package/docs/agent/buyer/quickstart.json

@@ -45,7 +45,7 @@
     "Use --target only for a Host presentation destination. Use --input key=value only for simple scalars; nested objects use a small JSON file with the existing --input-json command.",
     "For non-rail delivery that explicitly requires email, ask only that missing value and explain its purpose. Railway identity and notification contact are handled on the protected official checkout page; never guess them.",
     "Explain useful service facts in ordinary language; never ask the human to run commands or learn internal IDs.",
-    "Normal payment uses the returned ItPay Checkout handoff.",
+    "Normal selected service purchase uses its complete services purchase confirmation template, then the returned official handoff; no manual quote/cart/buy chain.",
     "A railway query execution and its separate booking execution may serve one purchase intent; keep both references."
   ],
   "forbidden": [
@@ -67,7 +67,7 @@
       "topic": "purchased-content"
     },
     {
-      "condition": "Need Cart and Checkout routing",
+      "condition": "Explicit multi-service Cart or historical Cart recovery",
       "topic": "cart-checkout"
     },
     {
@@ -108,5 +108,5 @@
     "input"
   ],
   "reading_results": "Read normal CLI text directly, or parse the complete --json envelope with the host file reader. If saving stdout to a file, first check the command exit code, then read the whole file with cat or the existing file tool. Keep stderr separate; do not use head, tail, regex or a custom script to recover truncated results. Write complex input as a small JSON file and use --input-json.",
-  "purchase_consent": "Candidate selection is not price approval. Service-backed quote/cart/checkout requires a current scoped approve_purchase record; use the complete server template, default false. Only genuine matching approval allows true; material price/subject/terms changes invalidate it. Restore an existing Checkout before creating anything."
+  "purchase_consent": "Follow the same-package Skill purchase preparation rule: current complete review → reuse matching real consent or ask only what is missing → write flat file_content → services purchase → show the official entry. This step does not request payment."
 }

package/docs/agent/buyer/rail-booking.json

@@ -13,7 +13,7 @@
     "query_vs_booking": "Exact/Smart returns a query execution and saved evidence. Booking creates a separate execution from a server-issued selection; it is not a repeated search.",
     "comparison": "If the human only asked to compare, answer within the searched scope and stop without a buy-or-not question. Reuse already-read unchanged Skill/docs in this context; do not repeat install/readyz/docs at each step. A clear purchase delegation permits selection under their rules, subject to required human terms.",
     "public_entry": "One public service itpay-rail declares query_exact, query_smart and prepare_purchase. Query, booking, Checkout and order remain separate identities. Legacy IDs are only for recovering their pinned historical executions.",
-    "price_approval": "Choosing a candidate or confirming seat/whole-journey terms is not approving price. Read the current scoped approve_purchase template after quote; record true only for genuine matching exact-price or capped-budget approval, or an explicitly authorized official-page confirmation. Reuse matching approval; never fabricate it."
+    "price_approval": "Use the complete purchase review and price policy under the formal Skill consent rule; one confirmation covers the actual itinerary, party, price policy and terms. Selection alone is not consent. The coordinator compares the real supplier quote; changed material conditions cannot reuse narrower approval."
   },
   "flow_at_a_glance": [
     {
@@ -49,13 +49,13 @@
     {
       "step": "review",
       "command": "itpay services next <booking_execution_id> --json",
-      "returns": "current review revision, material terms and a non-executable confirm_booking input_template",
-      "next": "submit the returned actor-type agent template only after genuine consent; reuse an unchanged explicit consent for code-only correction"
+      "returns": "complete purchase summary, current server reference and flat purchase confirmation file",
+      "next": "reuse genuine matching consent, ask only missing conditions, then execute the returned services purchase input template"
     },
     {
       "step": "checkout",
-      "command": "use the returned next or handoff for the same booking execution",
-      "returns": "an official protected payment entry",
+      "command": "itpay services purchase <booking_execution_id> --input-json <purchase-confirmation.json> --json",
+      "returns": "one original official page, or original progress with a bounded purchase --resume action; no payment requested",
       "next": "show the official entry using the current host immediately before optional memory/log writing, then stop; retain necessary safety/permissions, do not infer paid or issued"
     },
     {
@@ -125,7 +125,7 @@
     "whole_journey": "Use the returned complete ticket plan booking_template: ordered selections (2–3 legs) from one owner/snapshot/revision/plan, or selection for one leg. One booking, one refreshed whole quote, one checkout, one order and one payment; each leg issues separately without connection or joint-seat guarantees. Raw legs are single-leg compatibility only; never hand-compose multi-leg legs when complete selections are missing or expired. Do not combine different plans or choose per-leg payment by default. Historical details without a whole-journey template do not prove whole-journey support."
   },
   "review_and_checkout": {
-    "review": "Copy the returned complete interaction.input_template.file_content (input is the identical compatibility alias), current revision and notice. For a whole journey, each ordered leg has its own seat_type and an object preference per passenger; default auto, never null/string arrays. Use known choices and confirm only missing genuine terms consent or material changes. Set accept_non_guaranteed=true only after real consent; delegation or choosing a train alone is not terms consent. The false default is protection, not a broken template; if consent is missing, ask the returned review.consent_question once. Seat/berth placement requests differ from the whole-journey separate-issuance and partial-outcome terms; use the current notice.",
+    "review": "Read every ordered leg, seat class, party size, whole-journey terms and current price policy in the purchase summary. Copy the complete flat file_content, preserving server review_ref/request_key. Use the formal Skill rule to reuse genuine unchanged consent or ask only missing conditions. The coordinator applies the original railway review template and checks the real supplier quote; do not separately assemble confirm_booking, approve_purchase, cart or buy.",
     "equivalent_correction": "If only seat code spelling changes while train, actual seat class, party, price and terms are identical, reuse an existing explicit human approval. Material draft changes or missing approval require human confirmation. Reuse accepted original endpoints, no-seat, overnight and incomplete-coverage facts when unchanged; never silently substitute the destination.",
     "checkout": "Present the complete itinerary, total and single official handoff: one payment, separate issuance. The human enters one passenger set on that page; verified account notification email is reused there and can be changed for this order. Do not ask or guess traveler identity/email in chat. Use the returned checkout payment deadline, not an estimated duration. Handoff is not payment, and payment is not all legs issued."
   },
@@ -170,9 +170,9 @@
   "saved_followup": "Use returned refine_preferences with expected_query_revision for arrival/departure times, passengers, seat preference or priority; rerank uses existing facts. Only endpoints/date/new scope require a new query. Profiles compare within one journey, not the whole catalog. Fares and service fees are whole-journey totals for the stated people; observed available is not proof of ample inventory. Page limit is 1-20; follow next_offset exactly, never infer full-catalog optimality from the visible page. Byte-limited pages may contain fewer rows than limit. Area station candidates are not guaranteed nearest; transfer wait/minimum are facts, not a low-risk guarantee.",
   "actor_conventions": {
     "location_confirmation": "Use the returned human template only for the user's real place choice; no delegated human action.",
-    "journey_terms": "workflow:confirm_booking and booking_review_invalid recovery accept agent-reported genuine consent; default false, never infer from purchase delegation.",
+    "journey_terms": "Normal preparation uses the purchase confirmation file and real user_answer. Historical workflow:confirm_booking recovery retains its original agent-reported genuine consent rule; default false.",
     "ordinary_human_action": "Use its published actor rule; do not generalize railway permission.",
-    "price_approval": "approve_purchase uses actor-type agent with the unchanged server-scoped approval template and genuine matching approval; candidate choice is not price approval."
+    "price_approval": "Historical approve_purchase keeps its exact server-scoped quote binding and actor-type agent; it is not the new default route."
   },
   "consent_template_semantics": "Template false means approval is not recorded, not that the human must answer again. When user_answer_required is absent, check explicit chat or recorded consent for the current scope, party, price and terms; reuse it unchanged, ask only for missing consent or material differences, and never invent approval."
 }

package/docs/agent/buyer/rail-fast-checkout.json

@@ -22,7 +22,7 @@
       "command": "Use the current result’s booking_template and returned next action",
       "notes": [
         "Select under the buyer’s unchanged rules. Required human terms still require real consent. Continue the same booking execution.",
-        "Copy the complete plan template into one booking; raw legs are single-leg compatibility only, multi-leg purchases require the complete selections template; one whole quote and official payment entry, separate issuance. Use the returned full review JSON; only missing real agreement requires asking."
+        "Copy the complete ordered plan template into one booking. Its complete purchase review leads to one services purchase confirmation and official entry; reuse genuine unchanged consent. Separate leg issuance remains, not separate payments."
       ]
     },
     {

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

@@ -6,7 +6,7 @@
   "title": "Agent Type And Human Handoff Rendering",
   "purpose": "Use only the handoff fields returned for the current Agent Type and make Checkout or read authorization genuinely visible on that surface.",
   "when_to_use": [
-    "buy, services checkout, checkout, pay, or vault access returned a human handoff.",
+    "services purchase or an existing Checkout/authorization reader returned a human handoff.",
     "The human cannot see a Checkout or authorization QR image or link."
   ],
   "host_contracts": [
@@ -33,7 +33,7 @@
     {
       "agent_type": "workbuddy",
       "default_host": "plain-chat",
-      "responsibility": "execute handoff.agent_action exactly once to open the fully rendered handoff.url with present_files, then send handoff.mobile_url as a clickable link that jumps straight into Alipay or WeChat Pay on a phone; show the amount and stop"
+      "responsibility": "If present_files is already available, execute the returned agent_action once; otherwise show the original official URL in this turn. Show mobile_url when present and the amount, then stop."
     },
     {
       "agent_type": "zcode",
@@ -57,7 +57,7 @@
       "native_hosts": [
         "telegram"
       ],
-      "responsibility": "pass the native OpenClaw entry target explicitly; for Telegram execute handoff.agent_action unchanged, then treat itp:grant_confirmed callbacks only as permission to query the same Checkout and follow Backend grant state; otherwise show the returned HTTPS QR image and Checkout URL"
+      "responsibility": "Preserve the trusted native Host/target. Use the returned message action only if its tool is available now; otherwise show the official URL in this turn. Callbacks only permit reading the same state, never prove payment."
     }
   ],
   "commands": [
@@ -75,7 +75,7 @@
   "agent_rules": [
     "Agent Type is stable identity; Host is presentation and may be explicitly overridden. Once the official handoff is available, show it on this host before optional memory/log work; retain necessary safety and permissions.",
     "A local QR path is not visible until a desktop Agent attaches or renders that file on the human-facing surface; WorkBuddy Checkout handoff uses its returned Card Link and mobile URL; auth login may separately return a local QR path.",
-    "For workbuddy with plain-chat, execute handoff.agent_action exactly once; it calls present_files with handoff.url as the only files element and opens the rendered Card Link in the right-side browser, then send handoff.mobile_url so phone users can tap straight into Alipay or WeChat Pay.",
+    "For WorkBuddy, use present_files once only if already available; otherwise show the original handoff.url immediately. Send mobile_url when present. Do not research or install a tool before delivering the entry.",
     "For zcode with plain-chat, open handoff.url in the built-in browser and also send handoff.mobile_url as the phone entry; do not only paste text, download or rebuild a QR, or invent a private browser-tool payload; when the built-in browser is unavailable show both clickable links.",
     "For doubao-work with plain-chat, show two labeled official links: handoff.mobile_url for direct same-phone opening and handoff.qr_image_url for saving or scanning on another device; do not parse credentials, download or rebuild the QR, or create an alternative resource.",
     "If the WorkBuddy action fails, send the original handoff.url and handoff.mobile_url, report that it did not auto-open, and stop without creating another payment resource.",
@@ -83,7 +83,8 @@
     "Do not claim a handoff was shown until the official entry supported by this Host is genuinely visible. A link-only Host does not require a QR.",
     "IM Hosts that require a target must receive --target before Checkout creation. OpenClaw has no default Host; Kimi Code uses terminal.",
     "OpenClaw Telegram uses flat url/value buttons for deployed-version compatibility. A grant_confirmed callback carries only the Checkout ID, never a display token, and never proves payment or an active grant.",
-    "Business flow is the same across hosts. Vault grants apply only to protected purchased-content access, not every railway step."
+    "Business flow is the same across hosts. Vault grants apply only to protected purchased-content access, not every railway step.",
+    "Image preparation has a short budget. A failed or slow image does not invalidate an already verified, currently payable official URL; show that URL in the same turn, without creating another Checkout."
   ],
   "forbidden": [
     "Do not expose display tokens separately from the tokenized Checkout handoff.",

package/docs/cli-reference/commands/services/checkout.md

@@ -6,9 +6,9 @@
 
 服务支持的 Quote/Cart/Checkout 共用服务端范围校验。缺少有效价格批准时返回完整 `approve_purchase` 模板，默认 `user_approved:false`；Agent 只在真实会话已同意当前主体、内容、价格或预算和条款时提交 true。选择候选或完成席别 review 不代替价格批准。同条件有效批准复用，已有 Checkout/未知付款先恢复原单，不补事后批准或创建替代订单。
 
-## 范围与意义
+## 历史合同兼容与高级入口
 
-为单个 Service Execution 快速创建或恢复 Checkout，并按 Host 向人交接付款入口。它是 `services quote -> cart add --quote -> buy --cart` 的单项快捷方式，必须复用相同的 Quote、Cart 和 Checkout Use Case。
+普通新服务使用 `services purchase` 完整确认与官方入口。此命令保留历史合同和高级兼容，为单个 Service Execution 创建或恢复 Checkout，并按 Host 向人交接付款入口。它是 `services quote -> cart add --quote -> buy --cart` 的单项快捷方式，必须复用相同的 Quote、Cart 和 Checkout Use Case。
 
 未注册/未登录用户不要求先执行 `itpay auth login`（Path B）：官方 checkout 页内完成必要的钱包认证、创建或复用账号并取得页面权限；人在页面上确认旅客、通知联系方式和最终报价后付款。支付确认沿用既有设备绑定机制，不再独立绑定。checkout 内完成账号认证不等于账号已通过手机号验证；钱包显示名、账号手机号与乘车人身份互相独立。
 

package/docs/cli-reference/commands/services/index.md

@@ -15,8 +15,8 @@
 - 任何 capability 输入都必须在状态写入、锁价、订单创建和 Provider 调用前通过 schema 校验。
 - `invoke` 只运行当前阶段允许且不需付款的 Agent-visible capability。
 - 依赖候选的付费 capability 必须继续来源 Execution；`action --candidate` 不能跨 Execution 搬运候选。
-- `services quote` 只创建 Quote Lock；`cart add --quote` 聚合交易；`buy --cart` 创建一次 Checkout。
-- `services checkout` 是单项快捷方式，内部复用 Quote、Cart 和 Checkout 的相同规则。
+- 普通已选服务使用 `services purchase` 读取完整确认、提交真实同意并交付官方页面；此操作不请求支付。
+- `services quote`、`cart add --quote`、`buy --cart` 保留为用户明确要求多服务组合的高级路径；旧 `services checkout` 保留已有执行兼容。
 - `agent_visible_result` 从 `services next` 读取；`vault_artifact` 只有人授权后才能 `read-result`。
 
 ## 子命令
@@ -26,6 +26,7 @@
 - [`invoke`](invoke.md)
 - [`action`](action.md)
 - [`quote`](quote.md)
+- [`purchase`](purchase.md)
 - [`checkout`](checkout.md)
 - [`list`](list.md)
 - [`get`](get.md)
@@ -41,7 +42,7 @@
 itpay services --help
 ```
 
-输出十一个子命令及一句选择规则：运行已发布服务使用 `run`，正常推进使用 `next`，深度诊断才使用 `get/events`。未知子命令返回参数错误和本 help，不创建 Execution。
+输出当前子命令：运行已发布服务使用 `run`，查询推进使用 `next`，选定后的完整购买确认使用 `purchase`，深度诊断才使用 `get/events`。未知子命令返回参数错误和本 help，不创建 Execution。
 
 ## Agent Type / Host
 

package/docs/cli-reference/commands/services/invoke.md

@@ -61,7 +61,7 @@ Provider 已收到请求但没有匹配项时，该 invocation 成功完成、
 
 ## 额度耗尽
 
-额度耗尽时，普通单 Execution 流程返回完整的 `services checkout` 单项快捷命令；`services quote -> cart add --quote -> buy --cart` 只用于用户明确要求把多个独立 Execution 合并付款的高级流程。
+额度耗尽且需要购买时，支持通用购买的 Execution 返回 `services purchase` 完整确认；未支持的新合同不能猜测授权，已有执行保留原兼容恢复。`services quote -> cart add --quote -> buy --cart` 只用于用户明确要求把多个独立 Execution 合并付款的高级流程。
 
 ```json
 {

package/docs/cli-reference/commands/services/next.md

@@ -250,7 +250,7 @@ itpay services next <service_execution_id> [--timeout <seconds>] [--since-snapsh
 
 - 每段保留相连行程、对应席别、每位乘客偏好；不要恢复固定单腿 scalar 模板。
 - `booking_review_changed` 重新读取当前服务端 revision，不自行递增、不重放旧 revision。
-- 候选/条款确认不等于价格批准；实时报价后使用完整有范围 approve_purchase 模板，仅真实匹配批准允许 true。
+- 候选选择不等于真实同意。正常流程使用返回的 `services purchase` 完整模板，服务端核对准备同意与实际 quote 后才生成原有价格批准；旧执行的 approve_purchase 模板仅按原范围兼容恢复。
 - 未付且允许修改时修订同一 booking 重新报价；支付已在途/完成、结果未知或退款锁定时按原单读取，不新建替代购买。
 - 乘客身份、电话、邮箱修改只在保护页完成，不在聊天或 workflow 输入收集。
 

package/docs/cli-reference/commands/services/purchase.md

@@ -0,0 +1,21 @@
+# `itpay services purchase`
+
+## 当前执行的官方页面准备
+
+选定服务后读取完整购买摘要；仅补缺失的真实同意。CLI沿原业务确认、供应商报价与服务端范围校验准备一个官方填写与付款页面。本步骤不请求支付、不扣款，不代表出票或交付。
+
+```bash
+itpay services purchase <service_execution_id> --json
+itpay services purchase <service_execution_id> --input-json <purchase-confirmation.json> --json
+itpay services purchase <service_execution_id> --resume --json
+```
+
+输入文件原样使用当前模板的完整 `file_content`，不包外层 `input`。保留 `review_ref`、`request_key`，填写真实 `user_answer`；真实同意覆盖对象、人数、价格策略和条款时才设 `user_approved:true`。已有明确同意未变就复用；未知价格不能默认选择官方页面确认。
+
+价格策略为当前服务器模板的 exact（amount_minor）、capped（maximum_minor），或用户明确允许的 confirm_on_official_page；均带 currency。不得添加 quote_id 或自己拼业务字段。本地格式错误返回未发送，不当作未知写入。
+
+`--timeout` 默认60秒，范围大于0且不超过120秒；服务器保存原确认的累计120秒自动等待预算，恢复不重置。running交回真实阶段和原执行的恢复动作；不重查、不换单。`--host`、`--target`按实际宿主填写；`--locale`控制展示语言。
+
+成功返回已核验官方URL、当前期限和 effects：payment_requested=false、charged=false。图片不可用不阻塞同轮链接交付。人完成官方页面操作后再读取原 Checkout/Order；不能用二维码或人的付款陈述替代后端支付事实。
+
+旧合同未声明此能力时保留原执行，使用其公开的历史恢复路径；不能绕过兼容检查、创建替代单或改身份。

package/docs/cli-reference/commands/services/run.md

@@ -136,7 +136,7 @@ itpay services run itpay-rail --operation query_exact --input-json query.json --
 
 旧 `itpay-rail-exact/smart/booking` ID 仅用于已有执行和历史模板的兼容恢复；新公共模板与旧凭据共用原购买去重。存在或未知购买先恢复，过期库存不等于能新建购买。
 
-候选选择和席别条款确认不等于价格批准。实时报价返回完整有范围的 `approve_purchase` JSON，默认 `user_approved:false`。仅已有真实、匹配价格/上限/条款/主体同意才改 true；内容未变可复用。付款与出票事实仍由后端及官方页确认。
+候选选择不等于价格和条款同意。正常流程读取返回的 `services purchase` 完整确认；已有真实、匹配价格/上限/条款/主体的同意可复用，缺失或实质变化才补确认。服务端核对实际报价并衔接原有批准；旧执行的 approve_purchase 模板保留原范围保护。付款与出票事实仍由后端及官方页确认。
 
 ## 终态和异常
 

package/docs/cli-reference/index.md

@@ -85,6 +85,7 @@ Commander 自动提供的 `itpay help [command]` 与 `itpay <group> help [subcom
   - [`itpay services start`](commands/services/start.md)
   - [`itpay services invoke`](commands/services/invoke.md)
   - [`itpay services action`](commands/services/action.md)
+  - [`itpay services purchase`](commands/services/purchase.md)
   - [`itpay services quote`](commands/services/quote.md)
   - [`itpay services checkout`](commands/services/checkout.md)
   - [`itpay services list`](commands/services/list.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.1.47",
+  "version": "2.1.48",
   "description": "The ItPay CLI for services, orders, and human-authorized purchased content.",
   "type": "module",
   "bin": {
@@ -72,6 +72,7 @@
     "docs/cli-reference/commands/services/list.md",
     "docs/cli-reference/commands/services/next.md",
     "docs/cli-reference/commands/services/page.md",
+    "docs/cli-reference/commands/services/purchase.md",
     "docs/cli-reference/commands/services/quote.md",
     "docs/cli-reference/commands/services/read-result.md",
     "docs/cli-reference/commands/services/run.md",
@@ -141,5 +142,5 @@
     "url": "git+https://github.com/itpay-ai/cli.git"
   },
   "itpayBundleFormat": "buyer-esm-v1",
-  "gitHead": "826e26ae63175ff5b3933c688118349f71d83c61"
+  "gitHead": "5165ffbbcac542b4348996deebcad10280e3e88c"
 }

package/skills/itpay/SKILL.md

@@ -98,10 +98,27 @@ Apply the human's existing choices and approvals within their scope. Ask only
 for missing choices, permissions or materially changed terms. Service-specific
 rules determine when delegated selection is allowed. Never invent human
 consent, identity data, payment, ticket issuance or refund success. An Agent
-may select under the human's delegation, but must not record itself as a human. Candidate selection is not approval of price. Use the server scoped approve_purchase
-template only for genuine matching exact-price, capped-budget or explicitly authorized
-official-page confirmation; its default remains false. Restore an existing checkout first.
-Choosing a candidate is not acceptance of additional material terms. Ask the current service consent question once when genuinely missing, leaving an unaccepted default false. For railway workflow:confirm_booking (including its recovery) and scoped approve_purchase, submit conversation approval as actor-type agent: it reports the human answer and does not prove official-page confirmation. Location-confirmation workflow actions retain the returned human template, only after a real user choice; ordinary human_action actions retain their published actor rule and must not be converted to agent. Actor values never create missing consent.
+may select under the human's delegation, but must not record itself as a human.
+Candidate selection is not price or material-terms approval.
+
+For a normal selected service, read its complete purchase review. Write the
+returned flat confirmation file, preserving its server reference and request key.
+Use existing genuine consent covering the object, quantity, price policy and
+terms; ask once only for missing consent or material changes. Run the returned
+`services purchase --input-json` command to prepare one official page. The CLI
+coordinates the original business confirmation, real quote and Checkout; do not
+manually assemble quote → approve → cart → buy. Unknown price never implies
+permission to confirm later on the official page. Exact price, capped budget or
+that page-confirmation policy must reflect the human's explicit authorization.
+A running response resumes the same purchase with its persisted waiting budget;
+never restart the query or create another purchase. Page preparation does not
+request payment or prove payment, issuance or delivery.
+
+Cart/buy remain advanced paths for an explicitly requested multi-service cart or
+an older pinned contract that supplies those actions. Their original quote-bound
+approval protection remains. Ordinary human_action nodes retain their published
+actor rule; purchase preparation does not permit arbitrary Agent signatures.
+Location choice still requires the real choice and its returned actor template.
 
 ## Show the human