@itpay/cli 2.1.7 → 2.1.9

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

@@ -0,0 +1,67 @@
+# `itpay services page`
+
+> **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.
+
+## 范围与意义
+
+读取已保存 Result Item 的同版本分页。分页来自 Backend 存储的当前结果版本，不重新调用 Provider、不消耗查询额度，也不产生新的 Execution。
+
+**上游：** `services run`、`services next` 返回的分页提示（`catalog_page.next_offset`）。  
+**下游：** 继续翻下一页，或在用户明确选择后用 `booking_offer` 承接购票。
+
+本命令不接受 Buyer token、capability 或服务输入，不返回原始 Backend DTO 之外的额外事实；Agent 不向用户暴露 `safe_payload`、Execution 或内部 ID。
+
+## 语法与参数
+
+```bash
+itpay services page <service_execution_id> <result_item_id> [--offset <offset>] [--limit <limit>] [--json]
+```
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `service_execution_id` | 是 | 产生该结果集的 Execution ID。 |
+| `result_item_id` | 是 | `services next` 或分页响应中的 `service_capability_result_item_id`。 |
+| `--offset` | 否 | 从零开始的候选偏移；默认 `0`，必须是非负整数。 |
+| `--limit` | 否 | 页大小，`1` 到 `20` 的整数；默认 `5`。 |
+| `--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": 5,
+    "total": 63,
+    "count": 5,
+    "next_offset": 5,
+    "page": { "catalog_page": { "...": "..." }, "candidates": [ { "title": "<title>" } ] }
+  },
+  "instruction": "读取的是已保存结果的同版本分页，不重新查询、不消耗额度。用普通语言向用户说明本页候选；铁路应付与地面估算费用分开表述；不要提及 safe_payload、Execution 或内部 ID。",
+  "next": { "command": "itpay services page <id> <item_id> --offset 5 --json", "reason": "读取同版本结果的下一页" },
+  "recovery": []
+}
+```
+
+`next_offset` 为 `null` 时 `next` 为 `null`；`offset > 0` 时 `recovery` 提供回到第一页的命令。页内候选可携带 `booking_offer`，承接方式与 `services next` 结果一致。
+
+## 异常处理
+
+`--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/run.md

@@ -21,7 +21,7 @@ itpay services run <service_id>
 | 参数 | 说明 |
 | --- | --- |
 | `service_id` | Catalog 返回的服务 ID。恢复时必须与 Execution 所属服务一致。 |
-| `--input-json` | UTF-8 JSON 文件；顶层必须是 object，并符合服务发布的 input schema。 |
+| `--input-json` | UTF-8 JSON 文件；顶层必须是 object，并符合服务发布的 input schema；文件不超过 256 KiB。文件不可读、非合法 JSON 或顶层非 object 时在本地报 `workflow_input_invalid`，不发生网络写。 |
 | `--execution` | 恢复同一 Execution。不得用它切换服务或绕过原状态。 |
 | `--timeout` | 本次等待 workflow 状态变化的秒数，默认 120，范围 0–600；超时只返回当前状态。 |
 | `--host` / `--target` | Host 展示上下文，不是业务输入或 Buyer 身份。 |
@@ -60,6 +60,86 @@ itpay services run <service_id> --execution <execution_id> --json
 
 只恢复当前状态。交付、Vault 授权和退款继续使用 `services next`、`services read-result`、`vault` 与 `refund` 的既有合同。
 
+## 免费试用额度与 `login_required`
+
+铁路查询类服务对未登录设备提供按服务独立计数的免费试用（`itpay-rail-exact` 与 `itpay-rail-smart` 各 2 次，互不共享）。额度在查询产生供应商副作用前由服务端原子记账：地点确认、内部多阶段、轮询和已保存结果分页不重复扣次；参数校验失败且未执行查询时不扣次。
+
+试用耗尽时，查询在供应商调用**之前**被暂停，Execution 不失败，已提交的输入服务端保留：
+
+```json
+{
+  "status": "login_required",
+  "result": {
+    "service_execution_id": "<execution_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": "该服务的免费查询次数已用完（exact 2/2，smart 仍剩 2/2）。请用户在官方页面完成登录后继续免费查询；本次查询输入已保留，登录后恢复同一执行即可，不要新建执行或让用户重述行程。smart 额度属于另一类服务，不能拿它顶替 exact 查询。",
+  "next": {
+    "command": "itpay auth login --json",
+    "reason": "完成官方登录绑定后继续免费查询"
+  },
+  "recovery": [
+    {
+      "command": "itpay services run itpay-rail-exact --execution <execution_id> --json",
+      "when": "auth_bound",
+      "reason": "登录绑定完成后恢复同一查询执行"
+    }
+  ]
+}
+```
+
+`query_quota` 如实报告两类额度各自用量，一类为零不得宣称"四次全部用完"。第四次查询的结果先正常交付，下一次新查询才需要授权。
+
+登录绑定完成后，再次运行同一条 `services run <service> --execution <id> --json`（不带输入文件）：服务端重新读取当前设备绑定身份，被暂停的 Execution 从额度节点继续，不重放已成功的供应商调用，不要求重新输入。`failed`、`recovery_required` 或已完成付款的 Execution 不能以这种方式恢复。
+
+## `rate_limited`
+
+已注册账号查询不设累计次数上限，但受正常每分钟限流：
+
+```json
+{
+  "status": "rate_limited",
+  "result": {
+    "service_execution_id": "<execution_id>",
+    "service_id": "<service_id>",
+    "admission": "rate_limited",
+    "retry_after_ms": 42000
+  },
+  "instruction": "触发正常限流；等待后恢复同一执行，不要新建查询。",
+  "next": {
+    "command": "itpay services run <service_id> --execution <execution_id> --json",
+    "after_ms": 42000,
+    "reason": "限流窗口过后继续同一查询"
+  },
+  "recovery": []
+}
+```
+
+限流不是收费、不是试用耗尽、不需要重新登录。等待中不得重复扣试用或发起新的供应商请求。
+
+## 已选车次的购票输入（selection）
+
+对 `itpay-rail-booking`，输入支持两种等价方式。优先使用查询结果里服务端签发的购买承接：
+
+```json
+{
+  "passengers": 1,
+  "selection": {
+    "token": "<查询结果项中的 booking_offer.selection_token>",
+    "seat_type": "O"
+  }
+}
+```
+
+`selection.token` 绑定一次具体查询结果快照与其中的班次/方案；服务端校验归属、快照版本、时效后推导权威 `legs` 并实时核价。Agent 只提交用户选定的承接、`seat_type`（必要时）与乘客人数，**绝不手工拼装 `legs`、站码、时刻或供应商形状**。显式 `legs` 输入仍然有效，字段即购票服务发布的 `input_schema`（`passengers` 为 1–5 整数人数，不是乘客身份数组）。
+
+相同 selection 重复提交恢复同一购票执行，不会重复核价或建单。
+
 ## 终态和异常
 
 - 成功、付款、交付、授权、退款锁等状态使用既有命令的标准信封，不额外包装 Seller 专用格式。

package/docs/cli-reference/index.md

@@ -88,6 +88,7 @@ Commander 自动提供的 `itpay help [command]` 与 `itpay <group> help [subcom
   - [`itpay services list`](commands/services/list.md)
   - [`itpay services get`](commands/services/get.md)
   - [`itpay services next`](commands/services/next.md)
+  - [`itpay services page`](commands/services/page.md)
   - [`itpay services read-result`](commands/services/read-result.md)
   - [`itpay services events`](commands/services/events.md)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.1.7",
+  "version": "2.1.9",
   "description": "The ItPay CLI for services, orders, and human-authorized purchased content.",
   "type": "module",
   "bin": {

package/skills/itpay/SKILL.md

@@ -31,6 +31,25 @@ purchase. If a request such as "查京东" could mean either old content or a ne
 query, ask which one the human wants before calling ItPay. Do not spend quota,
 request authorization, or start a purchase while the intent is ambiguous.
 
+## Railway Services
+
+Three services, three different jobs — pick by the human's input, never merge them:
+
+| Human has | Service |
+| --- | --- |
+| Exact departure AND arrival station names | `itpay-rail-exact` (direct query) |
+| City/area/address, or wants transfer planning | `itpay-rail-smart` (location resolution + planning) |
+| Chose a train/seat and wants to buy | `itpay-rail-booking` (quote → protected checkout → issuance) |
+
+Query results carry a server-issued `booking_offer.selection_token` on bookable
+options; for a purchase submit that token plus passenger count — never
+reconstruct train legs by hand. Passenger names, ID numbers and phone numbers
+belong only on the protected checkout page, never in chat. Each query service
+has its own free trial count (2+2, not a shared pool); `login_required` pauses
+the query, it is not a failure — resume the same execution after `itpay auth
+login`. For the full input contract and states, load the rail-booking topic via
+`itpay docs search rail-booking --json`.
+
 ## Follow One Envelope
 
 For each JSON response: