@itpay/cli 2.1.41 → 2.1.44

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

@@ -1,6 +1,6 @@
 # `itpay services action`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 
@@ -16,11 +16,30 @@ itpay services action <service_execution_id> --action <action_type>
   [--actor-type <actor_type>] [--actor-id <actor_id>]
   [--status <pending|approved|rejected|expired|cancelled>]
   [--candidate <rank> | --result-item <result_item_id>]
-  [--required-before <step>] [--input <key=value> ...] [--json]
+  [--required-before <step>] [--input <key=value> ...]
+  [--input-json <file>] [--json]
 ```
 
+| 选项 | 说明 |
+|---|---|
+| `--input <key=value>` | 逐项提交 action input；值可为 JSON 字面量（对象/数组/布尔/数字），可重复。 |
+| `--input-json <file>` | UTF-8 JSON 文件；顶层必须是 object，整体作为 action input；文件不超过 256 KiB。适合嵌套结构（如订票确认的 `seat_preferences`）。**与 `--input` 互斥**：同时给出时在发起请求前返回 `service_action_invalid`。文件不存在、非合法 JSON 或顶层非 object 同样在本地报结构化错误，不发生网络写。 |
+
 普通 Agent 优先使用 `--candidate <rank>`。CLI 只从当前 Execution 的 `current_result_items` 解析 Result Item ID；Backend 再读取权威 Invocation 和 Stable Hash。Agent 不提交 Hash，也不能使用其他 Execution 或外部来源的候选。`--result-item` 只用于已持有当前 Execution 内部句柄的受控恢复，不应要求用户提供。
 
+## 规划动作（rail.progressive.v2）
+
+`services next` 的 `rail_planning.available_actions` 会给出可直接执行的完整命令。规划动作只允许以下类型，由 planning owner 校验执行归属、plan 状态与幂等键，不影响 Arazzo `human_action` 状态机或公共执行状态：
+
+| action_type | 供应商消耗 | 说明 |
+| --- | --- | --- |
+| `workflow:expand_search` | 有界新增查询 | 仅在扩展暂停（`expansion_status=paused`）时可用；必须带服务端下发的 `action_request_id`（`pa_…`）与 `expected_query_revision`，一轮一柄、用完作废。 |
+| `workflow:refine_preferences` | 无（本地重排） | 用 `--input-json` 提交偏好补丁，对已保存证据重排序。 |
+| `workflow:stop_search` | 无 | 停止未发送的扩展任务；不影响已开始或已完成的出票。 |
+| `select_journey` | 无 | 用户亲自选定用 `--actor-type human`；用户已明确委托按规则代选用 `--actor-type agent --input selection_mode=delegated`。两者都带服务端返回的 `journey_id`，仅记录选择，后续购买仍走既有报价与受保护 Checkout。 |
+
+同一 `action_request_id` 相同内容重放返回原受理结果；相同 ID 不同内容会被判冲突。过期 `expected_query_revision` 的新动作被拒绝。
+
 ## 标准输出
 
 ```json
@@ -45,6 +64,8 @@ itpay services action <service_execution_id> --action <action_type>
 
 rank 不存在、属于旧结果集或其他 Execution、action 不允许、status 非法时均不写 action；返回结构化错误并且只引导同一 Execution 的 `services next`。不得新建 Execution、重新 invoke 或构造候选 ID。相同候选重试幂等；同一结果集改选另一个候选返回冲突，不覆盖已批准事实。
 
+订票类 `workflow:confirm_booking` 动作要求嵌套输入（`passengers`、`seat_type`、逐乘客 `seat_preferences`、`draft_revision`、`notice_version` 等），一律经 `--input-json <file>` 提交完整 JSON 对象。`draft_revision` 必须等于 `services next` 投影的 `context.review.draft_revision`；服务端拒绝 `booking_review_changed` 时重新读取后重试，不得自行递增。乘客姓名、证件号等身份信息不在此提交，仍由受保护 Checkout 页收集。
+
 ## Agent Type / Host
 
-所有正式支持的 Local Agent Type 行为相同。需要人确认时 instruction 必须明确“先询问用户”，不能因 Desktop Host 自动代替用户选择。
+所有正式支持的 Local Agent Type 行为相同。真实条款同意仍需人确认；在用户已明确委托选择且规则未变时，Agent 可执行返回的委托选择动作，不得冒充 human。

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

@@ -1,12 +1,20 @@
 # `itpay services checkout`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
+
+## 服务报价的批准边界
+
+服务支持的 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 next` 返回的 `prepare_quote` capability 和已验证输入。
+未注册/未登录用户不要求先执行 `itpay auth login`（Path B）：官方 checkout 页内完成必要的钱包认证、创建或复用账号并取得页面权限；人在页面上确认旅客、通知联系方式和最终报价后付款。支付确认沿用既有设备绑定机制，不再独立绑定。checkout 内完成账号认证不等于账号已通过手机号验证；钱包显示名、账号手机号与乘车人身份互相独立。
+
+**通知联系方式（铁路单）：** 订单级联系策略要求至少一个可用通道——邮箱，或在 checkout 页内经验证的大陆手机号（order-contact 验证码只校验收件人，不创建/合并登录身份）。有效邮箱即可独立完成 checkout；SMS 不是必填项，SMS 能力未配置时不得阻塞邮箱通道。该策略仅适用于铁路订单，企知道等既有服务的联系策略不变。乘客证件手机号、账号登录手机号与通知收件人是三个独立事实，互不替代。
+
+**上游：** `services next` 返回的 `prepare_quote` capability 和已验证输入。铁路购票执行必须先通过 `workflow:confirm_booking` review（见 `services next` 的 `booking_review_required`），后端才生成可支付报价；review 开放期间不创建 Checkout。
 **下游：** 人完成 Checkout，随后 `checkout` 或 `services next`。
 
 ## 语法与参数
@@ -84,6 +92,7 @@ itpay services checkout <service_execution_id> --resume
 | `claude-code-cli` | `handoff={url}`；普通文本模式在用户可见终端渲染二维码。 |
 | `workbuddy` | `handoff={url,agent_action}`；原样执行一次 `present_files(files=[url])` 打开完整渲染的 HTML Card Link，然后停止；不得检查或生成本地文件。 |
 | `zcode` | `handoff={url}`；立即用 ZCode 内置浏览器打开，然后停止；只有浏览器不可用时才展示同一个可点击链接。 |
+| `doubao-work` | `handoff={url,qr_image_url}`；在当前对话中展示手机直达收银台链接和官方二维码图片链接，说明金额后停止。 |
 | `kimi-code` | `handoff={url}`；复用标准 CLI 终端展示。 |
 | `openclaw` | 必须显式传 Host；Telegram 还必须传 OpenClaw 原生 Target，并返回必须原样执行的 `message` action；其他入口返回标准 `url,qr_image_url`。 |
 
@@ -99,6 +108,12 @@ ZCode 的准确 instruction 语义必须完整包含：
 Backend 尚未确认付款。立即用 ZCode 内置浏览器打开 handoff.url，让用户完成付款；确认已发起打开后说明金额，然后停止等待。不要只粘贴文字链接，不要下载、解析或重建二维码，不要创建新 Checkout、Payment Intent 或 Execution。只有内置浏览器明确不可用时，才展示同一个可点击 handoff.url。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。
 ```
 
+Doubao Work 的准确 instruction 语义必须完整包含：
+
+```text
+Backend 尚未确认付款。在当前豆包工作对话中展示两个有标签的官方入口：将 handoff.url 标为“手机直接打开收银台”，将 handoff.qr_image_url 标为“二维码图片（保存或用另一台设备扫码）”。说明金额后停止等待。不要解析或单独输出 URL credential，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。
+```
+
 `--locale` 默认 `zh-CN`，可显式使用 `--locale en`。语言只影响 Card 渲染，不改变 Checkout、付款或恢复状态。
 
 OpenClaw 的 Host/Target 校验必须发生在读取 execution 后、创建 Checkout 前；校验失败不能调用 Checkout 创建接口。Telegram `agent_action.arguments.presentation` 只使用 `blocks.buttons`，其中 `📱 手机点这儿支付` 使用扁平 `url`，`📋 已授权给我读` 使用 `value=itp:grant_confirmed:<checkout_id>`。准确 instruction 必须要求 Agent 立即用原生 `message` tool 原样执行 `handoff.agent_action`，不得改写 Presentation、换工具或用普通回复冒充按钮已发送。收到该 callback 表示用户声明已在收银台授权读取；Agent 立即执行 `next.command` 查询同一 Checkout，再只按 Backend 返回的 `next.command` 进入同一 Execution grant 流程。callback 不包含 display token，也不证明付款或 grant active；Backend 未返回 `grant_active` 前不得读取结果。

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

@@ -1,6 +1,6 @@
 # `itpay services events`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay services get`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 
@@ -57,9 +57,11 @@ itpay services get <service_execution_id> [--json]
 
 `timeline` 只保留最近 20 个公开节点；超过时增加 `timeline_truncated: true`。它不返回 event ID 或 `redacted_summary`。交付存在时可增加 `delivery_mode`；退款锁存在时增加 `access_locked` 和退款 ID/status，并优先返回锁定 instruction。
 
+订票类 Execution 的 `workflow:confirm_booking` 待确认/待修订状态不在 timeline 中展开细节——行程、`seat_options` 与当前 `draft_revision` 一律通过 `services next` 的 `booking_review_required` 投影读取；`get` 只用于确认执行仍处于可继续状态。
+
 ## 异常处理
 
-默认不返回原始 events、Provider metadata、内部 bindings、graph projection、capability schema、candidate hash、client context 或完整 payload。需要完整但仍经服务端脱敏的事件时才运行 `services events`。
+默认不返回原始 events、Provider metadata、内部 bindings、Arazzo workflow、capability schema、candidate hash、client context 或完整 payload。需要完整但仍经服务端脱敏的事件时才运行 `services events`。
 
 execution 不存在或不属于当前身份时保留不透明 `not_found`，只恢复到 `itpay services list --json`；不得通过错误差异探测其他账号。
 

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

@@ -1,6 +1,6 @@
 # `itpay services`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Seller-published workflows enter the same Buyer execution, Checkout, delivery, and refund state machine as ItPay services.
 
 ## 命令范围
 
@@ -11,7 +11,7 @@
 
 ## 核心不变量
 
-- 一个 Execution 表示一个独立服务意图；多个意图分别执行、分别交付，但各自的 Quote 可以进入同一 Cart。
+- Execution 的边界由服务合同决定；铁路查询和购票使用不同 Execution，已有执行的等待与恢复保持原 ID。其他独立服务分别执行，其 Quote 可进入同一 Cart。
 - 任何 capability 输入都必须在状态写入、锁价、订单创建和 Provider 调用前通过 schema 校验。
 - `invoke` 只运行当前阶段允许且不需付款的 Agent-visible capability。
 - 依赖候选的付费 capability 必须继续来源 Execution；`action --candidate` 不能跨 Execution 搬运候选。
@@ -22,6 +22,7 @@
 ## 子命令
 
 - [`start`](start.md)
+- [`run`](run.md)
 - [`invoke`](invoke.md)
 - [`action`](action.md)
 - [`quote`](quote.md)
@@ -40,7 +41,7 @@
 itpay services --help
 ```
 
-输出十个子命令及一句选择规则：正常推进使用 `next`，深度诊断才使用 `get/events`。未知子命令返回参数错误和本 help，不创建 Execution。
+输出十一个子命令及一句选择规则：运行已发布服务使用 `run`，正常推进使用 `next`，深度诊断才使用 `get/events`。未知子命令返回参数错误和本 help，不创建 Execution。
 
 ## Agent Type / Host
 

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

@@ -1,25 +1,27 @@
 # `itpay services invoke`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 
 调用当前 phase 允许的非付费 Agent-visible capability。输入先按 capability schema 校验，校验失败不得迁移 execution 或记录 Provider 已调用。
 
 **上游：** `services start/next` 明确返回 invoke。
-**下游：** 候选结果、人工 action 或付费 Quote。一次 invoke 没有结果或返回 Provider 错误时必须停止；只有用户之后明确提供新输入，才启动新的 execution。
+**下游：** 候选结果、人工 action 或付费 Quote。此页的候选人工选择示例适用于相应的非铁路服务；铁路按 `rail-booking` 的已保存结果和委托选择合同。Provider 错误先按实际错误码和当前 execution 状态恢复，不猜新输入或自动新建。
 
 ## 语法与参数
 
 ```bash
 itpay services invoke <service_execution_id> --capability <capability_id>
-  [--input <key=value> ...] [--json]
+  [--input <key=value> ... | --input-json <file>] [--json]
 ```
 
-`--input` 可重复；必填 key 来自 `input_schema.required`，值按 schema 类型解析。Agent 不猜字段名。
+`--input` 可重复；必填 key 来自 `input_schema.required`，值按 schema 类型解析。Agent 不猜字段名。嵌套对象使用已有 JSON 文件读取方式 `--input-json <file>`；文件必须是完整对象，与 `--input` 二选一，冲突或解析失败不会调用供应商。
 
 ## 有结果输出
 
+以下是非铁路候选服务的示例。铁路使用 `services run` 和 `services read-result` 返回的范围、完整紧凑目录与当前动作；不要把这里的 `select_candidate` 人工动作套用到已授权委托的铁路选择。
+
 ```json
 {
   "status": "result_ready",

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

@@ -1,6 +1,6 @@
 # `itpay services list`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,34 +1,36 @@
 # `itpay services next`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 
 读取一笔 Service Execution 的当前状态，并只返回一个首选下一步。若交付模式允许 Agent 直接读取，本命令同时返回完整 safe result。
 
 **上游：** `services start`、`invoke`、`action`、`checkout`，或一次中断恢复。  
-**下游：** 一个可执行命令、需要用户完成的候选选择或授权，或 Graph 真正到达终态。
+**下游：** 一个可执行命令、需要用户完成的候选选择或授权，或 Arazzo workflow 真正到达终态。
 
-本命令不返回原始 Backend DTO、capability 列表、内部 result ID/hash、graph、binding 或重复 guidance。
+本命令不返回原始 Backend DTO、capability 列表、内部 result ID/hash、Arazzo workflow、binding 或重复 guidance。
 
 Backend 会根据当前 capability 选择 `current_delivery`；完整 `delivery_bindings` 仅是历史记录。CLI 不按数组位置猜测当前交付，同一 Execution 后续产生的新交付会取代旧交付成为默认结果。
 
 ## 语法与参数
 
 ```bash
-itpay services next <service_execution_id> [--json]
+itpay services next <service_execution_id> [--timeout <seconds>] [--since-snapshot <snapshot_id>] [--json]
 ```
 
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
 | `service_execution_id` | 是 | `services start` 或后续命令返回的 execution ID。 |
+| `--timeout <seconds>` | 否 | 同一执行上的有界只读等待，0–120 秒，默认 0；查询等待中的推荐命令使用 120。已有业务结果、真实用户动作或终态会提前返回。 |
+| `--since-snapshot <snapshot_id>` | 否 | rail.progressive.v2 增量读：传上次看到的 `snapshot_id`，未变化时只回扩展状态与 `result_not_updated`，不重复下发 journey 负载；永远不触发供应商调用。 |
 | `--json` | 否 | 输出稳定 JSON 信封；未指定时输出相同事实的简洁文本。 |
 
 需要有效 Agent Device session。命令不接受 Buyer token、capability 或服务输入。
 
-## 候选选择
+## 非铁路服务的候选选择
 
-免费或付费候选已经产生、Graph 允许继续选择时，恢复输出必须包含当前 Result Set 的安全候选：
+免费或付费候选已经产生、Arazzo workflow 允许继续选择时，恢复输出必须包含当前 Result Set 的安全候选：
 
 ```json
 {
@@ -48,9 +50,9 @@ itpay services next <service_execution_id> [--json]
 }
 ```
 
-该列表来自 Backend 的 `current_result_items`，CLI 不缓存或合并其他 Execution 的候选。
+该列表来自 Backend 的 `current_result_items`，CLI 不缓存或合并其他 Execution 的候选。铁路 Exact 的正常返回改走 `read-result` 已保存车次行及逐行 `detail.command`；Smart 的委托选票用 `select_delegated`（actor-type agent），只有用户亲自选定才用 `select_user_chosen`（actor-type human）。
 
-## Agent-visible 结果
+## 非铁路服务的 Agent-visible 结果
 
 ```json
 {
@@ -76,7 +78,7 @@ itpay services next <service_execution_id> [--json]
 }
 ```
 
-只有 Graph 允许继续选择时才返回上述 `next`。若结果本身就是最终交付，instruction 要求用普通语言解释可公开字段并停止，且 `next: null`。文本输出可以保留 Agent 执行所需的 Execution 与 `delivery_mode`，但 Agent 不向用户暴露这些内部词、Result Item ID、Invocation ID 或 Hash。
+只有 Arazzo workflow 允许继续选择时才返回上述 `next`。若结果本身就是最终交付，instruction 要求用普通语言解释可公开字段并停止，且 `next: null`。文本输出可以保留 Agent 执行所需的 Execution 与 `delivery_mode`，但 Agent 不向用户暴露这些内部词、Result Item ID、Invocation ID 或 Hash。
 
 ## Vault 交付
 
@@ -91,7 +93,7 @@ itpay services next <service_execution_id> [--json]
     "delivery_mode": "vault_artifact",
     "grant_status": "none"
   },
-  "instruction": "这是当前 Graph 步骤对应的交付；请用户在订单页面授权，未授权前不要读取或猜测内容。",
+  "instruction": "这是当前 Arazzo step 对应的交付；请用户在订单页面授权，未授权前不要读取或猜测内容。",
   "next": {
     "command": "itpay services read-result <id> --json",
     "reason": "仅在用户确认授权后执行"
@@ -141,7 +143,7 @@ itpay services next <service_execution_id> [--json]
     "grant_status": "active",
     "grant_expires_at": "<RFC3339 time>"
   },
-  "instruction": "这是当前 Graph 步骤对应的交付；用户授权有效，立即读取并遵守字段范围与到期时间。",
+  "instruction": "这是当前 Arazzo step 对应的交付；用户授权有效，立即读取并遵守字段范围与到期时间。",
   "next": {
     "command": "itpay services read-result <id> --json",
     "reason": "读取当前有效 grant 的结果"
@@ -195,7 +197,62 @@ itpay services next <service_execution_id> [--json]
 }
 ```
 
-`succeeded` 退款改为“交付永久关闭”，并返回 `next: null`。取消、拒绝或确定未产生资金影响的失败退款不再阻塞，但旧 grant 不会复活；用户必须重新授权。
+`succeeded` 退款改为“交付永久关闭”，并返回 `next: null`。取消、拒绝或确定未产生资金影响的失败退款不再阻塞，但旧 grant 不会复活；是否需要新的交付授权由当前 owner 状态与返回动作决定。
+
+## 额度暂停（试用/限流）
+
+查询 Execution 因免费试用耗尽或限流被暂停时，状态为 `login_required` 或 `rate_limited`（不是 `failed`）。Execution 保留输入，可用同一 `services run <service> --execution <id> --json` 恢复——登录后或限流窗口过后从额度节点继续，不重放已完成阶段，不要新建 Execution 或重述行程。
+
+```json
+{
+  "status": "login_required",
+  "result": {
+    "service_execution_id": "<id>",
+    "service_id": "itpay-rail-exact",
+    "admission": "login_required",
+    "query_quota": [
+      { "service_id": "itpay-rail-exact", "used": 2, "limit": 2, "remaining": 0 },
+      { "service_id": "itpay-rail-smart", "used": 0, "limit": 2, "remaining": 2 }
+    ]
+  },
+  "instruction": "如实告知该服务的免费试用次数与剩余；请用户登录后继续，原查询无需重新输入。",
+  "next": { "command": "itpay auth login --json", "reason": "官方登录绑定后继续免费查询" },
+  "recovery": [
+    { "command": "itpay services run itpay-rail-exact --execution <id> --json", "when": "auth_bound" }
+  ]
+}
+```
+
+`rate_limited` 只等待 `retry_after_ms` 后恢复同一执行；不需要登录、不扣试用。
+
+## 查询结果中的购买承接
+
+铁路查询结果项可携带服务端签发的购票承接 `booking_offer`：
+
+```json
+{
+  "rank": 1,
+  "title": "C6908 二等座 11:48→12:20",
+  "safe_payload": { "...": "..." },
+  "booking_offer": {
+    "service_id": "itpay-rail-booking",
+    "selection_token": "sel_...",
+    "expires_at": "2026-09-20T04:00:00Z"
+  }
+}
+```
+
+有购买委托时，读取所选完整行程详情，使用其返回的 `itpay-rail --operation prepare_purchase` 完整模板；保留 continuation 的原 execution/snapshot 与完整 selections。上面的 booking_offer 是历史兼容事实，不将它改造成新公共承接或手拼多腿。
+
+## 整程订票确认与价格批准
+
+当前 `booking_review_required` 返回完整整程 review、每段席别代码/名称、人数、偏好词表、notice_version 与 draft_revision。直接读写返回的完整 JSON，不需要解析脚本；模板的 accept_non_guaranteed 默认 false。只补用户尚未明确同意的实质内容；仅修席别代码而车次、实际席别、人数、价格、条款未变时沿用原真实确认。
+
+- 每段保留相连行程、对应席别、每位乘客偏好；不要恢复固定单腿 scalar 模板。
+- `booking_review_changed` 重新读取当前服务端 revision，不自行递增、不重放旧 revision。
+- 候选/条款确认不等于价格批准；实时报价后使用完整有范围 approve_purchase 模板，仅真实匹配批准允许 true。
+- 未付且允许修改时修订同一 booking 重新报价；支付已在途/完成、结果未知或退款锁定时按原单读取，不新建替代购买。
+- 乘客身份、电话、邮箱修改只在保护页完成，不在聊天或 workflow 输入收集。
 
 ## 异常处理
 
@@ -210,3 +267,12 @@ itpay services get <service_execution_id> --json
 ## Agent Type / Host
 
 所有正式支持的 Local Agent Type 返回完全相同的状态、safe payload、instruction 和 next。本命令不渲染二维码，也不包含 Host handoff。
+
+## 渐进规划（rail.progressive.v2）
+
+智能铁路规划服务在执行读模型上附带 `rail_planning` 投影：`readiness`（pending/ready/expired）、`search.expansion_status`（queued/running/paused/complete/cancelled/failed/expired）、`recommendation` 与 `alternatives` 行程卡片、以及服务端给出的完整 `available_actions` 命令。
+
+- `running`/`queued`：稍后按 `next.command` 增量轮询同一执行；不要重新发起查询。
+- `paused`：首批结果已就绪、扩展暂停等待用户意图；`expand_search` 是唯一会再消耗供应商配额的动作。
+- `complete`：扩展收敛；比较任务已满足就展示推荐并停止，购买委托则按明确规则选择。
+- 选票走 `select_journey` 动作：卡片的 `select_delegated` 供已授权委托的 Agent 选择，`select_user_chosen` 仅用于用户亲自选定；乘车人身份信息永远只在受保护 Checkout 页面填写。

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

@@ -0,0 +1,71 @@
+# `itpay services page`
+
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
+
+## 范围与意义
+
+读取已保存 Result Item 的同版本分页。分页来自 Backend 存储的当前结果版本，不重新调用 Provider、不消耗查询额度，也不产生新的 Execution。
+
+**上游：** `services run`、`services next` 返回的分页提示（`catalog_page.next_offset`）。  
+**下游：** 继续翻下一页，或在用户明确选择后用 `booking_offer` 承接购票。
+
+本命令不接受 Buyer token、capability 或服务输入；CLI 可把已有保存车次投影成便于比较的业务行和购买模板，不增加供应商事实。Agent 不向用户暴露 `safe_payload`、Execution 或内部 ID。
+
+## 语法与参数
+
+```bash
+itpay services page <service_execution_id> <result_item_id> [--offset <offset>] [--limit <limit>] [--cursor <rcur_n>] [--json]
+
+rail.progressive.v2 中 `<result_item_id>` 也可以是规划快照 ID（`rps_…`，见 `services next` 返回的 `snapshot_id`）：分页读取该不可变快照内的 journey 卡片，`--cursor` 使用上一页返回的 `rcur_<offset>` 不透明游标。
+```
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `service_execution_id` | 是 | 产生该结果集的 Execution ID。 |
+| `result_item_id` | 是 | `services next` 或分页响应中的 `service_capability_result_item_id`。 |
+| `--offset` | 否 | 从零开始的候选偏移；默认 `0`，必须是非负整数。 |
+| `--limit` | 否 | 页大小，`1` 到 `20` 的整数；默认 `20`。 |
+| `--json` | 否 | 输出稳定 JSON 信封；未指定时输出本页候选标题的简洁文本。 |
+
+需要有效 Agent Device session。
+
+## 分页信封
+
+有候选返回 `result_page`，读尽返回 `result_page_end`：
+
+```json
+{
+  "status": "result_page",
+  "result": {
+    "service_execution_id": "<id>",
+    "service_capability_result_item_id": "<item_id>",
+    "offset": 0,
+    "limit": 20,
+    "total": 63,
+    "count": 20,
+    "next_offset": 20,
+    "page": { "catalog_page": { "...": "..." }, "candidates": [ { "title": "<title>" } ] }
+  },
+  "instruction": "读取的是已保存结果的同版本分页，不重新查询、不消耗额度。用普通语言向用户说明本页候选；铁路应付与地面估算费用分开表述；不要提及 safe_payload、Execution 或内部 ID。",
+  "next": { "command": "itpay services page <id> <item_id> --offset 20 --json", "reason": "读取同版本结果的下一页" },
+  "recovery": []
+}
+```
+
+`next_offset` 为 `null` 时 `next` 为 `null`；`offset > 0` 时 `recovery` 提供回到第一页的命令。页内候选可携带 `booking_offer`，承接方式与 `services next` 结果一致。
+
+铁路 Exact 对已保存的单条车次使用 `--offset <result_offset> --limit 1 --json`，返回 `exact_train_detail`、当前席别代码与名称、库存/报价事实和 `booking_template`。模板中的 `selection.token` 来自服务端，`seat_type` 只能选当前返回的可购代码；人数按用户需求填写。查询价格不等于锁价。
+
+## 异常处理
+
+`--offset` 非负整数、`--limit` 必须在 `1`–`20` 内，否则在发起请求前返回 `offset_invalid` / `limit_invalid` 信封，不消耗服务端分页。execution 或 result item 不存在、不属于当前设备/账号时返回错误信封，并仅建议：
+
+```text
+itpay services next <service_execution_id> --json
+```
+
+分页读取的是已保存的同版本结果；不要重新发起查询或新建 execution 来"刷新"分页。
+
+## Agent Type / Host
+
+所有正式支持的 Local Agent Type 返回完全相同的状态、分页事实、instruction 和 next。本命令不渲染二维码，也不包含 Host handoff。

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

@@ -1,6 +1,6 @@
 # `itpay services quote`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 
@@ -8,9 +8,9 @@
 
 本命令是多 Execution 合并付款的高级入口。普通单 Execution 流程应使用 `services checkout`，不要把 `services quote` 当作 Checkout 失败后的替代路径。
 
-**上游：** 用户明确要求合并多个独立 Execution，且每个 Execution 的 Graph 当前都允许 `prepare_quote`。
+**上游：** 用户明确要求合并多个独立 Execution，且每个 Execution 的 Arazzo workflow 当前都允许 `prepare_quote`。
 
-**下游：** `cart add --quote`。多个独立 Execution 的 Quote 可以加入同一 Cart。
+**下游：** 读取当前服务器返回的有范围 `approve_purchase` 完整 JSON，默认 false；仅已有真实匹配批准时置 true 并记录。批准成功后再 `cart add --quote`，多个已批准 Quote 可加入同一 Cart。候选选择不等于价格批准。
 
 ## 语法与参数
 
@@ -57,7 +57,7 @@ itpay services quote <service_execution_id> --capability <capability_id>
 - `capability_input_invalid`：缺少 required input；不创建 Quote、Cart 或 Checkout。
 - `delivery_email_required`：先说明邮箱用于交付 claim link，再询问用户；禁止代填。
 - 候选未确认、来自其他 Execution、Quote 已存在冲突：Backend 拒绝且不改变 Execution。
-- `service_quote_not_allowed`：当前 Graph 不允许从当前 Execution 状态购买该 capability；不得换 capability、新建 Execution 或尝试其他购买命令，只回到同一 Execution 的 `services next`。
+- `service_quote_not_allowed`：当前 Arazzo workflow 不允许从当前 Execution 状态购买该 capability；不得换 capability、新建 Execution 或尝试其他购买命令，只回到同一 Execution 的 `services next`。
 - Backend 不支持当前交易合同时返回 `backend_contract_incompatible`，必须停止，不能改用 `services checkout`、`cart`、`buy` 或 `pay` 绕过。
 
 ## Agent Type / Host

package/docs/cli-reference/commands/services/read-result.md

@@ -1,25 +1,36 @@
 # `itpay services read-result`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 
-使用当前 Agent Device Authority，在用户创建的有效、未过期且范围匹配的 grant 内读取 Vault 保护结果。它不适用于 `agent_visible_result`。
+同一命令读取三种已保存结果：铁路 Exact 车次按页读取为紧凑业务行、铁路 Smart 快照分页紧凑车次目录，或持有效 grant 读取 Vault 保护内容。铁路读取免费、只读且不重新调用供应商。
 
-**上游：** `services next` 返回 `vault_artifact`，且用户已在订单页面授权。  
-**下游：** Agent 仅在 grant scope 和 TTL 内使用返回字段；没有自动后续命令。
+**上游：** 铁路查询的已保存结果入口，或 `services next` 返回 `vault_artifact` 且用户已在订单页面授权。
+**下游：** 铁路紧凑行中使用逐行 `detail.command` 读取购买条件；Vault 仅在 grant scope 和 TTL 内使用返回字段。
 
 ## 语法与参数
 
 ```bash
-itpay services read-result <service_execution_id> [--json]
+itpay services read-result <service_execution_id> [--snapshot <snapshot_id>] [--journey <journey_id>] [--offset <offset>] [--limit <limit>] [--all] [--json]
 ```
 
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
-| `service_execution_id` | 是 | Vault 交付对应的 execution ID。 |
+| `service_execution_id` | 是 | 铁路查询或 Vault 交付对应的 execution ID。 |
+| `--journey <journey_id>` | 否 | rail.progressive.v2 规划明细：读取指定 journey 的分段与席别选项；票计划按页返回。免费、属主校验、不触发供应商调用。 |
+| `--snapshot <snapshot_id>` | 否 | 单独使用时读取该 Smart 已提交快照的紧凑线路页；与 `--journey` 配合时读取该线路详情页。 |
+| `--offset <offset>` | 否 | Exact / Smart 保存结果从零开始的页偏移；不改变快照或重新查询。 |
+| `--limit <limit>` | 否 | 保存结果当前页条数，1–20；Exact默认20条，Smart默认3条完整线路或3个票计划；必要时按最终输出字节缩小整行页。 |
+| `--all` | 否 | 显式兼容读取 Exact / Smart 保存目录全量；输出可能很大，常规读取应沿当前页的 next.command。 |
 | `--json` | 否 | 输出稳定 JSON 信封；未指定时输出相同事实的简洁文本。 |
 
+Exact 执行按 offset/limit 读取已保存车次，返回 total、offset、count 和同一 read-result 的续页入口；不会把前100条冒充完整范围。Smart 使用 `--snapshot` 读取固定快照的默认小页，或用 `--journey` 读一条线路的票计划页；按返回的 next.command 续读同快照。这些读取不走 Vault grant。其他服务不带选择器时保持原授权路径。
+
+Smart 保存目录按本次主推荐、其他合格线路、不可用或资格未知的诊断线路排列；`total` 仍是全部已保存时刻组合数，`qualification_counts` 分别说明当前合格、不合格、未知数。诊断线路保留车次、时刻和 `qualification_reasons`，其 `detail.command` 用于查看事实与原因，不表示可以购买。只有 `qualification_status=eligible` 且逐段票方案完整时，才给当前购买入口。历史快照缺资格字段按未知展示。`--all` 仍读取全部事实，不会重新查询铁路。
+
+进度中的“保存组合”是具体车次与时刻组合数，不是不同站序数；“合格线路”按组合去重，profile 是同一组合下可推荐的席别及接驳选项数。模型实际调用和看到的合格组合以快照 coverage 为准；未穷尽范围不能称全网最优。推荐说明只披露当前方案实际涉及的地面交通、无座、跨日和分段票限制。
+
 CLI 使用已登记设备的签名 session，不接受 Checkout token、Buyer token、`agent_device_id` 参数或开发者凭证。
 
 CLI 直接请求 Backend 的当前有效 Grant。历史 `delivery_bindings` 不作为访问判断；Backend 负责验证当前 Vault、Agent instance、Buyer、scope、TTL 和退款锁。