@itpay/cli 2.1.34 → 2.1.41

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

@@ -1,71 +0,0 @@
-# `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/run.md

@@ -1,156 +0,0 @@
-# `itpay services run`
-
-## 范围与意义
-
-运行 Catalog 中已发布的通用 Buyer workflow。CLI 只提交服务声明要求的输入，并复用现有 Service Execution、Checkout、交付和退款命令；它不解释或执行 Seller 提供的任意命令文本。
-
-没有提供输入且未指定现有 execution 时，本命令创建一次 Execution，返回已发布的 JSON input schema，并要求 Agent 继续同一 Execution。已有 Execution 必须通过 `--execution` 恢复，不能创建替代 Execution。
-
-## 语法与参数
-
-```bash
-itpay services run <service_id>
-  [--input-json <file>]
-  [--execution <service_execution_id>]
-  [--timeout <seconds>]
-  [--host <host>]
-  [--target <target>]
-  [--json]
-```
-
-| 参数 | 说明 |
-| --- | --- |
-| `service_id` | Catalog 返回的服务 ID。恢复时必须与 Execution 所属服务一致。 |
-| `--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 身份。 |
-| `--json` | 输出稳定 JSON 信封。 |
-
-## 缺少输入
-
-```json
-{
-  "status": "input_required",
-  "result": {
-    "service_execution_id": "<execution_id>",
-    "service_id": "<service_id>",
-    "input_schema": { "type": "object", "required": ["<field>"] }
-  },
-  "instruction": "根据服务声明填写输入，然后继续同一服务执行。",
-  "next": {
-    "command": "itpay services run <service_id> --execution <execution_id> --input-json <file> --json",
-    "reason": "提交买家输入"
-  },
-  "recovery": []
-}
-```
-
-Agent 必须展示 schema 所需信息并等待用户提供真实输入；不得猜值，也不得为补输入创建新 Execution。
-
-铁路 Smart 新版 schema 使用 `endpoints.origin` / `endpoints.destination`，每端独立填写区域 `area`、具体地点 `place` 或准确车站 `station` 与原文 `text`；类型未确定可省略 `kind`。区域、地点和车站的九种组合共用这一输入。以当前执行返回的 `input_schema` 为准：旧 v4 执行仍使用旧字段；新版不可混填旧 `origin` / `destination`、坐标或锁站布尔值。地点/日期实质变更发起关联新查询，沿已保存结果返回的 `new_query_template` 填写真实变化；偏好、人数和期限在相同端点/日期下使用已有 `refine_preferences` 动作。
-
-## 执行与付款
-
-提供输入后，CLI 使用稳定 idempotency key 向同一 Execution 提交一次。`queued` 或 `running` 只轮询该 Execution。进入付款步骤时，CLI 调用现有 `services checkout`，返回其标准 `human_checkout_required` 输出和 Host handoff；不会实现第二套付款逻辑。
-
-付款完成后即使 CLI 已退出，Backend 仍继续该 workflow。再次运行：
-
-```bash
-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` 如实报告各查询服务自己的 `used`、`limit`、`remaining`。是否暂停只以本次服务端 `admission` 为准；已有结果先正常交付，不把另一服务的额度当作本次授权。
-
-登录绑定完成后，再次运行同一条 `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 专用格式。
-- 既有 Checkout、身份、兼容性和网络错误保持原错误码、instruction 与 recovery；`services run` 不得覆盖可执行的邮箱、登录、升级或状态恢复指令。
-- 如果创建 Execution 后未收到完整响应，返回 `workflow_start_outcome_unknown`，只允许先执行 `itpay services list --json` 查找刚创建的 Execution；不得直接重跑 `services run` 创建替代 Execution。
-- `recovery_required` 或 `failed` 返回当前 workflow step，`next: null`，并明确禁止重建 Execution 或重放结果未知的 Provider 请求。
-- service 不匹配、输入文件不是 JSON object、timeout 越界或 Backend 错误返回 `workflow_run_failed`。
-- `--timeout` 到期不是失败，只返回同一 Execution 当前可恢复状态。
-
-## Agent Type / Host
-
-所有 Local Agent Type 共享同一状态机和 JSON 事实。Host 只改变付款链接、二维码或附件的展示方式，不改变身份、价格、workflow 或交付权限。

package/docs/sell.md

@@ -1,84 +0,0 @@
-# Sell Agent guide
-
-The railway acceptance release `2.1.2` is published under npm's `next` tag,
-not `latest`. Install this explicit version for dev acceptance and set
-`ITPAY_BACKEND_URL=https://dev.itpay.ai` on every command. Its API contract requires
-the matching dev backend release; do not use it against the older production
-backend. Promote the npm latest tag only after production compatibility is verified.
-
-`itpay sell` is the Seller command namespace. Buyer `services` commands remain separate. Read `itpay sell guide --json` first, authenticate with `itpay sell auth login` and complete the standard ItPay browser login, then run `itpay sell auth status`, then use `sell status` to select the user's existing merchant. An unverified merchant must finish KYB and payout setup in the dashboard.
-
-## Local-first workflow
-
-1. `sell init --project <directory> --service-id <id> --name <name>` creates a local project. `sell config --file <json>` sets price, policy and explicit test fixtures. Never invent prices or required API inputs.
-2. `sell library search/get` reads platform sources. `sell sources add --file <OpenAPI> --provider-key <key>` compiles local contracts with the platform importer. `sell workflow import --file <workflow.yaml>` preserves the submitted workflow and reports unsupported semantics. Read `sell workflow catalog` for supported node configuration.
-3. Generate or modify `workflow.yaml` in the user's Agent using the exact source contracts. Bind `providerOperationVersionId`, credential profile and input/output mappings explicitly. The first workflow ID must equal the service ID. Missing mappings, incompatible schema, unsupported content types or unsupported workflow semantics block execution. Do not remove unknown fields to conceal a compatibility error.
-4. `sell credentials bind --profile <id> --file <bindings.json>` accepts field-to-environment-variable mappings, never secret values. `sell credentials upload` uploads those environment values directly to the authenticated merchant after approval; values must not appear in chat, workflow files or generated docs. Platform-managed secrets cannot be downloaded.
-5. `sell workflow validate`, then `sell workflow versions save --name <name>`. Runs never create saved versions. `sell test run --confirm` performs actual Provider calls on this machine, with simulated payment/refund/delivery gates. `sell test get --run <id>` reads results. `sell test resume` never blindly replays an unknown request.
-6. `sell workflow preview` serves the existing Builder on loopback only. Review its exact YAML, price and version; then use `sell workflow confirm --confirm` only after user agreement.
-7. `sell push --merchant-id <id> --bindings <profile-map.json> --confirm` uploads the confirmed package. Profile map values are platform profile IDs, not secrets. Optimistic revisions prevent overwriting another editor. An ambiguous write requires explicit pull/reconciliation, never guessed retries.
-8. Inspect platform-imported operations and perform any required `sell sources probe` with explicit test inputs. Follow the backend Guide and the upload's returned version/revision fields to run `sell verify`. Disclose and confirm API side effects, including the exact risk hash if the platform returns an additional confirmation barrier.
-9. `sell submission preview` returns the workflow, price, policy and current agreements. After user approval, `sell submission submit` sends the exact revision, terms version and required confirmations. This requests review; it does not publish or approve.
-10. Use `sell submission get` and `sell services list/get` to follow the actual outcome. Rejected/withdrawn/taken-down services can be edited and resubmitted through the same process. Once published, verify with buyer `catalog list`.
-
-All platform operations accept `--input-json <file>` for their declared fields and `--merchant-id`/`--draft-id` where appropriate. Run each command's `--help`; do not invent options. `sell guide --merchant-id <id> --input-json <file>` with `{"draft_id":"..."}` returns server-derived next actions.
-
-## MCP
-
-`itpay sell mcp --stdio --project <directory>` exposes local creation, import, versioning, testing, preview, sync and platform actions. It reuses the local CLI identity. Remote MCP exposes only platform actions and cannot read paths on the user's machine. Use the local server for real local tests and file access. New remote grants require the appropriate `itpay.seller.read/write/test/submit` scopes; old buyer grants do not gain Seller authority.
-
-## Invariants
-
-- The current runtime accepts bounded, acyclic, single-entry workflows with multiple API nodes. Free queries can use quota and explicit human confirmation; paid workflows use one payment node and either fixed per-call pricing or a trusted pre-payment dynamic quote. Prepaid balance billing remains unsupported.
-- Protected railway fulfillment resumes through the platform booking Owner only after verified payment and Web passenger confirmation. A standalone API probe cannot supply a payment identity or passenger records. Follow the server Guide for actual acceptance and publication blockers; local graph validation is not live ticket-issuance evidence.
-- Local reports are diagnostics, not platform approval evidence. Platform verification is required; existing valid evidence may be reused. Admin approval never repeats Provider calls.
-- Every visual view reads the same YAML. Layout is presentation only.
-- Disclosure/confirmation binds the version being acted on. Do not turn `--confirm` into blanket permission for later changes.
-- Never approve real submissions or perform real payments in automated development tests.
-
-## Local recovery and packaging
-
-The local `.itpay-sell` directory contains private fixtures, reports and the encrypted run journal's local key. Exclude it from Git and shared artifacts. A terminated process may leave `runner.lock`; inspect the journal and ensure no runner is active before manual recovery. A request with an unknown outcome is never automatically replayed.
-
-Local reports never substitute for the platform verification gate. Repeated upload of an unchanged saved version reuses its cloud version; a changed cloud revision or fixture revision requires explicit pull/review.
-
-For CLI repository builds, run `node scripts/fetch-sell-runtime.mjs` to obtain the exact checksummed native runtime in `seller-runtime.lock.json`, then `npm run test:package`. The committed `assets/sell-preview` directory supplies the local Builder. Packaging rejects missing native binaries or preview assets; do not substitute an arbitrary local binary for the locked release.
-
-Example local MCP configuration (use the existing authenticated CLI account):
-
-```json
-{
-  "mcpServers": {
-    "itpay-sell": {
-      "command": "itpay",
-      "args": ["sell", "mcp", "--stdio", "--project", "/absolute/path/to/service"],
-      "env": {"ITPAY_BACKEND_URL": "https://sandbox.itpay.ai"}
-    }
-  }
-}
-```
-
-## Seller login and dev
-
-Use `ITPAY_BACKEND_URL=https://dev.itpay.ai itpay sell auth login` to receive the normal ItPay authorization link. After browser login and required email verification, run `ITPAY_BACKEND_URL=https://dev.itpay.ai itpay sell auth status`. The CLI claims its own account session through the standard API and stores it in an owner-only file; never copy tokens or browser cookies. `itpay sell auth logout` revokes this session. Keep the same backend prefix on subsequent commands; production, dev, and sandbox state are isolated. Agent device enrollment does not grant Seller organization access.
-
-## Private dev live checkout acceptance
-
-`itpay sell tests start-checkout --merchant-id <merchant> --draft-id <draft> --input-json <file> --confirm --json`
-
-Requires the dev server in live Provider mode, an account-scoped platform admin session,
-and an active enrolled Agent already bound to the same buyer. The JSON contains
-`expected_revision` and `agent_instance_id`. Save exactly one success fixture first.
-This queues a private canary execution; it does not publish a service or pay for a ticket.
-Disclose the live query side effects before using `--confirm`.
-
-Resume the returned `service_execution_id` using the normal workflow commands through
-that Agent. The user confirms the route and submits passenger details in the protected
-Checkout page. Only a verified payment callback permits supplier creation/payment.
-
-`itpay sell tests accept-checkout --merchant-id <merchant> --draft-id <draft> --execution-id <execution> --confirm --json`
-
-Records server-observed completed delivery and issued tickets for the exact frozen
-workflow, fixture and dependency hashes. Pending, partial, manual-recovery, unpaid or
-changed tests cannot pass. No payment or issuance assertions are accepted as input.
-Then use the normal submission and admin review flow; this test alone is not publication.