@itpay/cli 2.1.48 → 2.1.49

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

@@ -1,157 +1,16 @@
 # `itpay services invoke`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The public package provides Buyer workflows; Seller authoring source is maintained separately.
-
-## 范围与意义
-
-调用当前 phase 允许的非付费 Agent-visible capability。输入先按 capability schema 校验，校验失败不得迁移 execution 或记录 Provider 已调用。
-
-**上游：** `services start/next` 明确返回 invoke。
-**下游：** 候选结果、人工 action 或付费 Quote。此页的候选人工选择示例适用于相应的非铁路服务；铁路按 `rail-booking` 的已保存结果和委托选择合同。Provider 错误先按实际错误码和当前 execution 状态恢复，不猜新输入或自动新建。
-
-## 语法与参数
+仅在当前执行明确返回 invoke 动作时，调用该合同允许的非付费能力。正常服务使用公开 definition 的 operation 与 `services run`；本页不是另一套查询或购买教程。
 
 ```bash
 itpay services invoke <service_execution_id> --capability <capability_id>
-  [--input <key=value> ... | --input-json <file>] [--json]
-```
-
-`--input` 可重复；必填 key 来自 `input_schema.required`，值按 schema 类型解析。Agent 不猜字段名。嵌套对象使用已有 JSON 文件读取方式 `--input-json <file>`；文件必须是完整对象，与 `--input` 二选一，冲突或解析失败不会调用供应商。
-
-## 有结果输出
-
-以下是非铁路候选服务的示例。铁路使用 `services run` 和 `services read-result` 返回的范围、完整紧凑目录与当前动作；不要把这里的 `select_candidate` 人工动作套用到已授权委托的铁路选择。
-
-```json
-{
-  "status": "result_ready",
-  "result": {
-    "service_execution_id": "<id>",
-    "capability_id": "<capability_id>",
-    "items": [{ "rank": 1, "title": "<title>", "safe_payload": {} }],
-    "quota": { "remaining": 2, "limit": 3 }
-  },
-  "instruction": "用编号、名称和可公开字段向用户说明候选；若候选列表已满足目标就停止。只有用户明确选择并希望继续时，才提交对应编号；不要向用户提及 safe_payload、Execution 或内部 ID。",
-  "next": { "command": "itpay services action <id> --action <action_type> --actor-type human --status approved --candidate <rank> --json", "reason": "记录用户选择" },
-  "recovery": []
-}
-```
-
-## 无结果
-
-Provider 已收到请求但没有匹配项时，该 invocation 成功完成、提交一次真实额度消费并返回权威剩余额度。CLI 不提供可自动执行的下一步：Agent 必须展示 0 个结果并停止，不得缩短、改写或猜测输入。
-
-```json
-{
-  "status": "no_result",
-  "result": {
-    "service_execution_id": "<id>",
-    "capability_id": "company_name_suggestion",
-    "query": { "keyword": "北京赢在未来公司" },
-    "items": [],
-    "quota": { "remaining": 1, "limit": 3 }
-  },
-  "instruction": "没有找到与“北京赢在未来公司”匹配的结果。向用户展示本次为 0 个结果并停止。不要修改、缩短或猜测其他输入；只有用户明确提供新输入后，才能启动新的查询。",
-  "next": null,
-  "recovery": []
-}
+  [--input-json <file> | --input <key=value> ...] [--json]
 ```
 
-文本输出只包含 execution、capability、keyword、`results: 0`、quota 和同一条 instruction；不得附带 Provider raw payload、Operation ID 或调试信息。
-
-## 额度耗尽
-
-额度耗尽且需要购买时，支持通用购买的 Execution 返回 `services purchase` 完整确认；未支持的新合同不能猜测授权，已有执行保留原兼容恢复。`services quote -> cart add --quote -> buy --cart` 只用于用户明确要求把多个独立 Execution 合并付款的高级流程。
-
-```json
-{
-  "status": "quota_exhausted",
-  "result": {
-    "service_execution_id": "<id>",
-    "capability_id": "<capability_id>",
-    "items": [],
-    "quota": { "remaining": 0, "limit": 3 },
-    "checkout": {
-      "capability_id": "<paid_capability_id>",
-      "price": { "amount_minor": 10, "currency": "CNY" },
-      "delivery_email_required": false
-    }
-  },
-  "instruction": "免费额度已用完，本次没有发送到数据来源，也没有创建付款页面。只向用户说明：‘继续当前请求需要支付 0.10 CNY，是否购买？’然后停止等待。用户明确同意前，Agent 不执行 next.command，也不创建或尝试其他购买路径。",
-  "next": {
-    "command": "itpay services checkout <id> --capability <paid_capability_id> --input <key=value> --json",
-    "reason": "仅在用户明确同意支付 0.10 CNY 后执行；否则停止"
-  },
-  "recovery": []
-}
-```
-
-缺少 required input 时返回 `capability_input_invalid`，recovery 给出带占位符的同一 invoke 命令；CLI 和 Backend 都必须在 Provider 调用前拒绝，Backend 还必须在 execution/event/quota/invocation 写入前拒绝。错误调用付费 capability 时不得给出购买旁路，只能回到同一 Execution 的 `services next`；execution 状态、event、ProviderCalled 均保持不变。
-
-## Provider 请求前连接失败
-
-如果 Backend 能确认请求未发出，返回固定的终态错误，不暴露 DNS、IP、Provider URL 或凭证诊断：
-
-```json
-{
-  "status": "error",
-  "error": {
-    "code": "provider_connection_unavailable",
-    "message": "provider request was not sent; reserved quota was released"
-  },
-  "result": {
-    "service_execution_id": "<id>",
-    "provider_called": false,
-    "quota": { "remaining": 3, "limit": 3 }
-  },
-  "instruction": "告诉用户本次查询没有发送到数据来源，免费额度已保留，然后停止。不要转述技术错误、自动重试或进入付费路径；只有服务恢复且用户明确要求重新查询后才能开始新的查询。",
-  "next": null,
-  "recovery": []
-}
-```
-
-`result.quota` 是释放预留后的权威余额，不是请求前预留时的临时值。该终态不允许 CLI 猜测网络修复、重复 invoke 或转入购买。连接恢复后也不能复用失败 Execution；必须同时满足“运营已确认恢复”和“用户明确要求再次查询”，才创建新 Execution。
-
-## Provider 输入、临时和契约错误
-
-Provider 已收到请求时，Backend 返回同一 Execution 的权威调用和额度事实。CLI 不读取 raw payload，也不自行推断错误种类。
-
-明确输入错误：
-
-```json
-{
-  "status": "error",
-  "error": { "code": "provider_input_rejected", "message": "输入的名称不合法" },
-  "result": {
-    "service_execution_id": "<id>",
-    "provider_called": true,
-    "quota": { "remaining": 0, "limit": 3 }
-  },
-  "instruction": "告诉用户数据来源明确表示当前输入无效，并按 result.quota 说明额度状态，然后停止。不要转述内部错误、自行修改输入、重试或创建新查询；只有用户明确提供新输入后才能重新查询。",
-  "next": null,
-  "recovery": []
-}
-```
-
-契约错误：
-
-```json
-{
-  "status": "error",
-  "error": { "code": "provider_contract_mismatch", "message": "provider response did not match the published contract" },
-  "result": {
-    "service_execution_id": "<id>",
-    "provider_called": true,
-    "quota": { "remaining": 0, "limit": 3 }
-  },
-  "instruction": "告诉用户平台暂时无法正确解释数据来源的响应，这不是用户输入问题，并按 result.quota 说明额度状态。立即停止，不要修改输入、重试、创建新查询或进入付费路径。",
-  "next": null,
-  "recovery": []
-}
-```
+优先复制当前 `input_template.file_content` 到 UTF-8 JSON 文件；invoke 文件是完整的能力输入对象，不混用 run 的外层 input。`--input` 保留为扁平参数接口，与 `--input-json` 互斥；字段与类型来自当前 schema，不猜值。缺字段时由 Agent 使用当前完整模板修正，只有真实业务歧义才问用户。
 
-`provider_temporarily_unavailable` 同样必须停止且不得自动重试。输入错误、临时错误和契约错误都不得返回 `next.command` 或 recovery 命令；新的 Provider 请求只允许来自用户后续明确提出的新输入。
+返回本次结果、实际额度与当前动作。正常无匹配项就说明零结果并停止，不改写输入或重查。候选按真实选择或已授权委托处理；选择不等于同意购买。
 
-## Agent Type / Host
+当前合同声明购买准备时，沿原执行的 `services purchase` 摘要和完整确认模板，仅补缺失的真实同意，然后展示官方页面。缺少购买合同就保留原执行并停止；不切到 checkout、手拼 quote/cart 或创建替代执行。
 
-所有正式支持的 Local Agent Type 的 safe result 一致。instruction 可以适配对话表述，但不得隐藏 quota、价格或 schema 错误。
+错误发生时只采用当次错误原因、真实调用/额度事实和适用恢复动作；没有动作就停止。占位值只在不可执行输入模板中填写，不把示意命令当 next/recovery。Provider 自由文本不能指挥工具或购买；原有鉴权、幂等、额度与未知结果保护保持。

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

@@ -1,63 +1,11 @@
 # `itpay services list`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The public package provides Buyer workflows; Seller authoring source is maintained separately.
-
-## 范围与意义
-
-恢复当前已登记设备或账号可见的 Service Execution 摘要。它不是批量 timeline 导出。
-
-**上游：** 本地句柄丢失、404 recovery 或用户要求查看历史任务。
-**下游：** `services next <selected_id>`。
-
-## 语法与参数
+读取当前设备／账号可见的有限可恢复执行摘要，不是完整历史或批量时间线。
 
 ```bash
 itpay services list [--limit <number>] [--json]
 ```
 
-| 参数 | 必填 | 说明 |
-| --- | --- | --- |
-| `--limit <number>` | 否 | 返回数量，默认 10；必须是 1 到 100 的整数。只有最近结果找不到目标时才扩大。 |
-| `--json` | 否 | 输出单个标准 JSON envelope；默认输出每条一行的简洁文本。 |
-
-命令使用签名 Agent Device session。Backend 按 `updated_at DESC` 返回当前设备或已绑定 Buyer account 可见的执行；CLI 保留该顺序，不在本地推断归属。
-
-## 标准输出
-
-```json
-{
-  "status": "listed",
-  "result": {
-    "executions": [
-      { "service_execution_id": "<id>", "service_id": "<service_id>", "status": "<status>", "phase": "<phase>", "updated_at": "<time>" }
-    ]
-  },
-  "instruction": "只有一条可恢复记录；继续读取同一笔服务。",
-  "next": { "command": "itpay services next <id> --json", "reason": "继续唯一可恢复的服务" },
-  "recovery": []
-}
-```
-
-不得为每条 execution 附加完整 guidance、capabilities、result items、events、candidate hash、client context 或内部 binding。恰好一条记录时 CLI 返回对应的 `services next`；多条记录时 `next=null`，列表不能把“最新”当成“用户想要”，Agent 必须先用普通语言让用户选择。
-
-无结果时返回 `no_executions`、空数组和 `itpay catalog list --json`。
-
-非法 limit 在请求 Backend 前返回：
-
-```json
-{
-  "status": "error",
-  "error": { "code": "limit_invalid", "message": "--limit must be an integer from 1 to 100" },
-  "instruction": "使用 1 到 100 的整数 limit；本次未读取服务端列表。",
-  "next": null,
-  "recovery": [
-    { "command": "itpay services list --limit 10 --json", "reason": "使用默认上限重试" }
-  ]
-}
-```
-
-身份或 Backend 错误保留服务端错误码，只建议 `readyz` 和重新读取列表；不得猜测 ID。
-
-## Agent Type / Host
+`--limit` 默认10，范围1–100整数。结果保留服务端 updated_at 降序，返回 executions、limit、returned_count、scope 和 completeness=unknown；每项附当前 reader。文本和 JSON 表达相同事实，不返回凭据或完整内部DTO。
 
-所有正式支持的 Local Agent Type 返回相同列表格式；Agent instance 权限决定可见范围。本命令没有 Host handoff。
+`next=null`：一条记录不能证明唯一任务，空列表不能证明超时创建未发生。按原任务已知ID或权威关联选 reader；没有关联就停止，不自动选最新、不自动重发或新建。参数由 Agent 修正；认证、兼容和外部故障采用当次专门说明，不把 readyz 或重装当业务恢复。

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

@@ -1,278 +1,17 @@
-# `itpay services next`
+# itpay services next
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The public package provides Buyer workflows; Seller authoring source is maintained separately.
-
-## 范围与意义
-
-读取一笔 Service Execution 的当前状态，并只返回一个首选下一步。若交付模式允许 Agent 直接读取，本命令同时返回完整 safe result。
-
-**上游：** `services start`、`invoke`、`action`、`checkout`，或一次中断恢复。  
-**下游：** 一个可执行命令、需要用户完成的候选选择或授权，或 Arazzo workflow 真正到达终态。
-
-本命令不返回原始 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> [--timeout <seconds>] [--since-snapshot <snapshot_id>] [--json]
+```sh
+itpay services next <execution_id> --timeout 60 --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 或服务输入。
+读取同一执行及其当前适用动作。--timeout 为0–120秒，默认0；已有有用结果、真人操作或终态会提前返回。跨命令累计自动等待最多120秒，耗尽时 next=null，recovery仅在用户明确要求时执行。仍处理中不是零结果。
 
-## 非铁路服务的候选选择
-
-免费或付费候选已经产生、Arazzo workflow 允许继续选择时，恢复输出必须包含当前 Result Set 的安全候选：
-
-```json
-{
-  "status": "candidate_selection_available",
-  "result": {
-    "service_execution_id": "<id>",
-    "items": [
-      { "rank": 1, "title": "<title>", "safe_payload": { "<public_field>": "<value>" } }
-    ]
-  },
-  "instruction": "用编号、名称和可公开字段向用户说明候选；若候选列表已满足目标就停止。只有用户明确选择并希望继续时，才提交对应编号；不要向用户提及 safe_payload、Execution 或内部 ID。",
-  "next": {
-    "command": "itpay services action <id> --action select_candidate --actor-type human --status approved --candidate <rank> --json",
-    "reason": "仅在用户明确选择后锁定来源候选"
-  },
-  "recovery": []
-}
-```
-
-该列表来自 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 结果
-
-```json
-{
-  "status": "result_ready",
-  "result": {
-    "service_execution_id": "<id>",
-    "capability_id": "<capability_id>",
-    "delivery_mode": "agent_visible_result",
-    "items": [
-      {
-        "rank": 1,
-        "title": "<title>",
-        "safe_payload": { "<public_field>": "<value>" }
-      }
-    ]
-  },
-  "instruction": "付费搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才执行 next.command；不要提及 safe_payload 或自动购买后续报告。",
-  "next": {
-    "command": "itpay services action <id> --action select_candidate --actor-type human --status approved --candidate <rank> --json",
-    "reason": "仅在用户明确选择候选并要求继续时执行"
-  },
-  "recovery": []
-}
-```
+结果目录/详情/分页及购买输入由当次返回直接给出。照完整模板读写，不手写解析器、不重查、不串联旧下单命令。查询和购买同意遵循正式 Skill 与 rail-booking。
 
-只有 Arazzo workflow 允许继续选择时才返回上述 `next`。若结果本身就是最终交付，instruction 要求用普通语言解释可公开字段并停止，且 `next: null`。文本输出可以保留 Agent 执行所需的 Execution 与 `delivery_mode`，但 Agent 不向用户暴露这些内部词、Result Item ID、Invocation ID 或 Hash。
-
-## Vault 交付
-
-未授权时不返回 result item 或 protected payload：
-
-```json
-{
-  "status": "human_authorization_required",
-  "result": {
-    "service_execution_id": "<id>",
-    "capability_id": "<capability_id>",
-    "delivery_mode": "vault_artifact",
-    "grant_status": "none"
-  },
-  "instruction": "这是当前 Arazzo step 对应的交付；请用户在订单页面授权，未授权前不要读取或猜测内容。",
-  "next": {
-    "command": "itpay services read-result <id> --json",
-    "reason": "仅在用户确认授权后执行"
-  },
-  "recovery": []
-}
-```
-
-用户已经授权、但服务端仍在按已发布执行图准备 Vault 交付时，必须只轮询同一 Execution：
-
-```json
-{
-  "status": "result_preparing",
-  "result": {
-    "service_execution_id": "<id>",
-    "capability_id": "<capability_id>",
-    "delivery_mode": "vault_artifact",
-    "grant_status": "pending",
-    "preparation": {
-      "status": "running",
-      "total_nodes": 4,
-      "completed_nodes": 2,
-      "succeeded_nodes": 2,
-      "failed_nodes": 0
-    }
-  },
-  "instruction": "告诉用户：授权已经完成，付费结果仍在同一订单下准备，不需要再次付款或授权。然后只执行 next.command 查询同一笔服务；Agent 不创建新服务、付款页面或数据请求，也不提前读取。",
-  "next": {
-    "command": "itpay services next <id> --json",
-    "reason": "等待同一 Execution 的交付准备完成"
-  },
-  "recovery": []
-}
-```
-
-付款确认后仍处于 `wait`/Provider running 时，instruction 必须说明订单和付款已保留、用户不需要再次付款；若 Execution 最终失败，Agent 应恢复同一订单及退款状态，不能自动创建新购买或承诺退款。终态 `failed` 只允许说明本次服务没有正常完成，并读取现有事件用于诊断；不得把技术错误直接归咎于用户。
-
-有效 grant 存在时：
-
-```json
-{
-  "status": "grant_active",
-  "result": {
-    "service_execution_id": "<id>",
-    "capability_id": "<capability_id>",
-    "delivery_mode": "vault_artifact",
-    "grant_status": "active",
-    "grant_expires_at": "<RFC3339 time>"
-  },
-  "instruction": "这是当前 Arazzo step 对应的交付；用户授权有效，立即读取并遵守字段范围与到期时间。",
-  "next": {
-    "command": "itpay services read-result <id> --json",
-    "reason": "读取当前有效 grant 的结果"
-  },
-  "recovery": []
-}
-```
-
-额度耗尽或候选已确认并进入付费 continuation 时，`services next` 必须重复价格、用户确认原话、停止条件和禁止动作；普通单 Execution 的 next 使用 `services checkout`，不暴露 Quote/Cart/Buy 编排。
-
-已有 Checkout 时，Backend 返回 `resume_checkout`，CLI 只能恢复同一 Checkout：
-
-```json
-{
-  "status": "checkout_pending",
-  "result": {
-    "service_execution_id": "<id>",
-    "service_id": "<service_id>",
-    "phase": "checkout",
-    "allowed_actions": [{ "type": "resume_checkout", "requires_human": true }]
-  },
-  "instruction": "当前 Execution 已经有一笔 Checkout。不要创建新的 Quote、Cart、Checkout 或 Execution。现在只执行 next.command，恢复并展示同一 Checkout 的付款入口。",
-  "next": { "command": "itpay services checkout <id> --resume --json", "reason": "恢复同一 Checkout，不创建第二笔" },
-  "recovery": []
-}
-```
-
-付款已确认但 Provider 尚在履约时只能等待并再次读取同一 Execution；不得新建 Execution、Checkout 或再次付款。其他执行阶段只返回 Execution、service、phase、类型化 `allowed_actions` 和一个服务端状态导出的命令。CLI 只把 Backend 的动作类型渲染成命令，不执行 Publication 中的任意 shell 文本。完成或空结果后不得建议重放已失效的 invoke。
-
-## 退款访问锁
-
-订单存在 active 或永久退款锁时，该状态优先于 Agent-visible、Vault 和 grant guidance，不返回交付结果，也不再要求用户授权：
-
-```json
-{
-  "status": "delivery_locked",
-  "result": {
-    "service_execution_id": "<id>",
-    "access_locked": true,
-    "refund": {
-      "refund_request_id": "<refund_id>",
-      "status": "<refund_status>"
-    }
-  },
-  "instruction": "告诉用户退款仍在处理，原交付已按政策冻结。然后读取同一退款的权威状态；Agent 不读取交付、不创建授权或重复申请。",
-  "next": {
-    "command": "itpay refund get <refund_id> --json",
-    "reason": "读取退款权威状态"
-  },
-  "recovery": []
-}
-```
-
-`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。
-- 候选选择不等于真实同意。正常流程使用返回的 `services purchase` 完整模板，服务端核对准备同意与实际 quote 后才生成原有价格批准；旧执行的 approve_purchase 模板仅按原范围兼容恢复。
-- 未付且允许修改时修订同一 booking 重新报价；支付已在途/完成、结果未知或退款锁定时按原单读取，不新建替代购买。
-- 乘客身份、电话、邮箱修改只在保护页完成，不在聊天或 workflow 输入收集。
-
-## 异常处理
-
-execution 不存在或不属于当前设备/账号时返回错误信封，并仅建议：
+## 当前参数
 
 ```text
-itpay services get <service_execution_id> --json
+--since-snapshot <snapshot_id>  delta read: suppress the journey payload when
+--timeout <seconds>             wait up to 120 seconds for a useful result on
+--json                          output JSON instead of terminal text
 ```
-
-不要创建替代 execution 来掩盖归属或状态错误。
-
-## 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

@@ -29,43 +29,10 @@ rail.progressive.v2 中 `<result_item_id>` 也可以是规划快照 ID（`rps_
 
 需要有效 Agent Device session。
 
-## 分页信封
+## 当前分页输出
 
-有候选返回 `result_page`，读尽返回 `result_page_end`：
+返回同快照的 total、offset、count、下一偏移及完整业务行；页大小受最终输出字节预算约束，不截断一条线路。读尽 next=null；有后页只在还需比较时使用当次完整分页命令，不无意义翻完所有页。诊断或不可用方案保留原因，不把它们当可购买结果。
 
-```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
+Exact 单车详情使用保存的 result_offset 和 limit=1，给出席别代码／名称、库存与当前完整购买模板。Smart 详情沿返回的同快照入口读取完整多段票计划。当前价格不等于锁价，凭据不自行拼接；完整输入和 continuation 从该详情原样承接。
 
-所有正式支持的 Local Agent Type 返回完全相同的状态、分页事实、instruction 和 next。本命令不渲染二维码，也不包含 Host handoff。
+参数、归属、快照或读取错误按当次真实原因恢复；保存结果读取不触发供应商、不消耗查询额度，不用新查询“刷新”分页。所有宿主使用相同事实。

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

@@ -18,4 +18,4 @@ itpay services purchase <service_execution_id> --resume --json
 
 成功返回已核验官方URL、当前期限和 effects：payment_requested=false、charged=false。图片不可用不阻塞同轮链接交付。人完成官方页面操作后再读取原 Checkout/Order；不能用二维码或人的付款陈述替代后端支付事实。
 
-旧合同未声明此能力时保留原执行，使用其公开的历史恢复路径；不能绕过兼容检查、创建替代单或改身份。
+当前合同未声明购买能力时保留原执行并停止；不能绕过兼容检查、创建替代单或改身份。首次读取摘要失败可按返回动作重读；确认提交后响应丢失、恢复失败或官方入口展示读取失败，按返回的原执行 `--resume` 恢复，复用已保存的同意，不重新发送确认。权限、合同或明确过期等错误按实际原因停止。