@itpay/cli 2.1.6 → 2.1.8

package/dist/src/client/backend.js

@@ -123,8 +123,9 @@ export class BackendClient {
     advanceServiceExecution(id, input, idempotencyKey) {
         return this.http.post(`/v1/service-executions/${encodeURIComponent(id)}/advance`, { input, idempotency_key: idempotencyKey });
     }
-    createRailPhoneLink() {
-        return this.http.post("/v1/rail/phone-links", {});
+    getServiceExecutionResultItemPage(serviceExecutionID, resultItemID, offset, limit) {
+        const qs = new URLSearchParams({ offset: String(offset), limit: String(limit) });
+        return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/result-items/${encodeURIComponent(resultItemID)}?${qs}`);
     }
     invokeServiceCapability(serviceExecutionID, capabilityID, input) {
         return this.http.post(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/capabilities/${encodeURIComponent(capabilityID)}/invoke`, input, { replaySafe: Boolean(input.idempotency_key) });

package/dist/src/commands/services.js

@@ -57,18 +57,28 @@ const WORKFLOW_STEP_GUIDANCE = {
     input: { meaning: "输入校验", hint: "对照服务声明的输入契约补齐字段后重新发起" },
     quota: { meaning: "额度检查", hint: "免费额度或限流未通过；登录或稍后重试" },
     geo: { meaning: "位置解析", hint: "检查 origin/destination 是否为真实地名；可附 origin_city 或坐标对象提示" },
+    geo_confirm: { meaning: "确认后位置解析", hint: "用户确认的地点仍未解析成功；重新执行并让用户从候选项中按名称+坐标选择" },
+    resolved: { meaning: "位置解析复核", hint: "位置解析未满足继续条件；检查 origin/destination 后新建执行重试" },
+    resolved_after_confirm: { meaning: "位置确认复核", hint: "确认后的位置仍未通过复核；重新执行并核对用户所选候选项" },
     search: { meaning: "供应商车次检索", hint: "最常见是字段名错误（必须是 travel_date）或站名不存在；按 itpay docs show rail-booking 核对输入" },
     catalog: { meaning: "可行车次计算", hint: "位置已解析但无可行车次；换日期或换站点重试" },
     recommend: { meaning: "方案推荐", hint: "候选集无法产出推荐；放宽条件或换日期重试" },
     delivery: { meaning: "交付", hint: "结果组装失败；稍后重试或联系运营" },
 };
-function failedWorkflowStep(steps) {
+function failedWorkflowStep(steps, errorCode) {
     if (!steps)
         return undefined;
     for (const [step, status] of Object.entries(steps)) {
         if (status === "failure" && step !== "failure")
             return step;
     }
+    // Only a backend-recorded condition_unmet proves a false branch routed to failure.
+    if (errorCode === "condition_unmet") {
+        for (const [step, status] of Object.entries(steps)) {
+            if (status === "false" && step !== "failure")
+                return step;
+        }
+    }
     return undefined;
 }
 export async function runServicesStart(backend, serviceID, options = {}) {
@@ -186,14 +196,13 @@ export async function runServicesInvoke(backend, config, serviceExecutionID, cap
     catch (error) {
         if (!(error instanceof HttpError) || error.code !== "verified_phone_required")
             throw error;
-        const link = await backend.createRailPhoneLink();
         writeCommandEnvelope({
             status: "human_action_required",
-            result: { service_execution_id: serviceExecutionID, ...link },
-            instruction: "请用户打开 verification_url，在 ItPay 网页验证手机号并确认连接当前 Agent。CLI 不接收手机号或验证码；等待用户完成后再重试查询。",
-            next: null,
-            recovery: [{ command: `itpay services invoke ${serviceExecutionID} --capability ${capabilityID}${formatInputOptions(input)} --json`, reason: "仅在用户完成网页验证后重试" }],
-        }, { ...options, plainResult: [`手机号验证：${link.verification_url}`] });
+            result: { service_execution_id: serviceExecutionID, error_code: "verified_phone_required" },
+            instruction: "需要在官方页面完成手机号验证后当前执行才能继续。运行 itpay auth login 打开官方登录页，完成手机号验证并绑定本设备后重试原命令；CLI 不接收手机号或验证码。",
+            next: { command: "itpay auth login --json", reason: "完成官方手机号验证并绑定当前设备" },
+            recovery: [{ command: `itpay services invoke ${serviceExecutionID} --capability ${capabilityID}${formatInputOptions(input)} --json`, reason: "仅在完成手机号验证与设备绑定后重试" }],
+        }, { ...options, plainResult: ["手机号验证：itpay auth login"] });
         return;
     }
     const envelope = invokedEnvelope(response, requestedCapability, readModel.capabilities, input);
@@ -760,6 +769,51 @@ export async function runServicesNext(backend, serviceExecutionID, options = {})
         plainResult: servicesNextPlainResult(envelope.result),
     });
 }
+export async function runServicesPage(backend, serviceExecutionID, resultItemID, options = {}) {
+    const offset = options.offset ?? 0;
+    const limit = options.limit ?? 5;
+    if (!Number.isInteger(offset) || offset < 0) {
+        throw new CommandContractError("offset_invalid", "--offset must be a non-negative integer", "offset 必须是非负整数；本次未读取服务端分页。", [{ command: `itpay services page ${serviceExecutionID} ${resultItemID} --json`, reason: "从第一页重新读取" }]);
+    }
+    if (!Number.isInteger(limit) || limit < 1 || limit > 20) {
+        throw new CommandContractError("limit_invalid", "--limit must be an integer from 1 to 20", "limit 必须是 1 到 20 的整数；本次未读取服务端分页。", [{ command: `itpay services page ${serviceExecutionID} ${resultItemID} --offset ${offset} --json`, reason: "用默认页大小重试" }]);
+    }
+    const response = await backend.getServiceExecutionResultItemPage(serviceExecutionID, resultItemID, offset, limit);
+    const page = response.page;
+    const container = (page.result ?? page);
+    const catalogPage = (container.catalog_page ?? {});
+    const nextOffset = typeof catalogPage.next_offset === "number" ? catalogPage.next_offset : null;
+    const candidates = Array.isArray(container.candidates) ? container.candidates : [];
+    const envelope = {
+        status: candidates.length > 0 ? "result_page" : "result_page_end",
+        result: {
+            service_execution_id: response.service_execution_id,
+            service_capability_result_item_id: response.service_capability_result_item_id,
+            offset: catalogPage.offset ?? offset,
+            limit: catalogPage.limit ?? limit,
+            total: catalogPage.total ?? candidates.length,
+            count: catalogPage.count ?? candidates.length,
+            next_offset: nextOffset,
+            page,
+        },
+        instruction: "读取的是已保存结果的同版本分页，不重新查询、不消耗额度。用普通语言向用户说明本页候选（车次、席别、时刻、费用口径），铁路应付与地面估算费用分开表述；不要提及 safe_payload、Execution 或内部 ID。",
+        next: nextOffset !== null
+            ? { command: `itpay services page ${serviceExecutionID} ${resultItemID} --offset ${nextOffset} --json`, reason: "读取同版本结果的下一页" }
+            : null,
+        recovery: offset > 0
+            ? [{ command: `itpay services page ${serviceExecutionID} ${resultItemID} --json`, reason: "回到第一页" }]
+            : [],
+    };
+    writeCommandEnvelope(envelope, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+        plainResult: candidates.map((candidate) => {
+            const c = candidate;
+            const title = typeof c.title === "string" ? c.title : JSON.stringify(c);
+            return `${title}`;
+        }),
+    });
+}
 export async function runServicesList(backend, options = {}) {
     const limit = options.limit ?? 10;
     if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
@@ -995,12 +1049,57 @@ function servicesNextEnvelope(model) {
                 recovery: [],
             };
         }
+        if (state === "quota_paused") {
+            const login = model.workflow?.error_code !== "rate_limited";
+            const resume = { command: `itpay services run ${execution.service_id} --execution ${id} --json`, reason: "登录或限流窗口后继续同一执行" };
+            const quota = model.quota ? { bucket: model.quota.bucket, subject_type: model.quota.subject_type, limit: model.quota.limit, remaining: model.quota.remaining } : undefined;
+            return {
+                status: login ? "login_required" : "rate_limited",
+                result: { service_execution_id: id, service_id: execution.service_id, ...(quota ? { quota } : {}) },
+                instruction: login ? "匿名免费额度已用完。使用 itpay auth login 完成官方登录并绑定当前 Agent，然后继续同一执行；不要重新发起查询，不需要付款。" : "已达到登录账号每分钟查询上限。请等到下一分钟后继续同一执行，不要连续重试。",
+                next: login ? { command: "itpay auth login --json", reason: "登录后继续同一查询执行" } : resume,
+                recovery: [resume],
+            };
+        }
         if (state === "human_action" && model.workflow?.human_action) {
+            const action = model.workflow.human_action;
+            const requiredFields = requiredInputFields(action.input_schema);
+            const rawPlaces = action.context?.places;
+            // Only the location-confirmation action carries origin/destination places;
+            // every other human action keeps the generic envelope.
+            const isLocationConfirmation = !!rawPlaces && typeof rawPlaces === "object" &&
+                ("origin" in rawPlaces || "destination" in rawPlaces);
+            if (isLocationConfirmation) {
+                const places = rawPlaces;
+                const sides = ["origin", "destination"].map((side) => {
+                    const place = places[side];
+                    const candidates = Array.isArray(place?.resolution_candidates) ? place.resolution_candidates : [];
+                    const name = (item) => item.poi_name ?? item.query ?? item.formatted_address;
+                    return {
+                        side,
+                        status: place?.resolution_status,
+                        ...(place?.resolution_status === "resolved"
+                            ? { resolved_place: { name: name(place), location: place.location } }
+                            : {}),
+                        ...(candidates.length
+                            ? { candidates: candidates.slice(0, 5).map((item) => ({ name: name(item), location: item.location })) }
+                            : {}),
+                    };
+                });
+                return {
+                    status: "confirmation_required",
+                    result: { service_execution_id: id, service_id: execution.service_id, human_action: action,
+                        required_fields: requiredFields, sides },
+                    instruction: "向用户展示 sides 中 status=needs_confirmation 一端的候选（名称+坐标），请用户选定后按 required_fields 逐项各传一个 --input：名称取候选 name，坐标取候选 location 的 [lng,lat]；已 resolved 的一端把其 resolved_place 原样填入。继续同一执行，不重新查询；这一步不是购买确认。",
+                    next: { command: `itpay services action ${id} --action ${action.action_type} --actor-type human --status approved${requiredFields.map((field) => ` --input ${field}=<值>`).join("")} --json`, reason: "用户确认后继续当前查询" },
+                    recovery: [],
+                };
+            }
             return {
                 status: "confirmation_required",
-                result: { service_execution_id: id, service_id: execution.service_id, human_action: model.workflow.human_action },
-                instruction: "请展示待确认的位置，请用户明确确认后，按 input_schema 填写 --input 字段。继续同一执行，不重新查询；这一步不是购买确认。",
-                next: { command: `itpay services action ${id} --action ${model.workflow.human_action.action_type} --actor-type human --status approved --input <key=value> --json`, reason: "用户确认后继续当前查询" },
+                result: { service_execution_id: id, service_id: execution.service_id, human_action: action },
+                instruction: "请展示待确认的内容，请用户明确确认后，按 input_schema 填写 --input 字段。继续同一执行，不重新查询；这一步不是购买确认。",
+                next: { command: `itpay services action ${id} --action ${action.action_type} --actor-type human --status approved${requiredFields.map((field) => ` --input ${field}=<值>`).join("")} --json`, reason: "用户确认后继续当前查询" },
                 recovery: [],
             };
         }
@@ -1011,7 +1110,7 @@ function servicesNextEnvelope(model) {
         if (state === "input_required")
             command = `itpay services run ${execution.service_id} --execution ${id} --input-json <file> --json`;
         const guidance = railServiceGuidance(execution.service_id);
-        const failedStep = recovery ? failedWorkflowStep(model.workflow?.steps) : undefined;
+        const failedStep = recovery ? failedWorkflowStep(model.workflow?.steps, model.workflow?.error_code) : undefined;
         const failedStepGuidance = failedStep ? WORKFLOW_STEP_GUIDANCE[failedStep] : undefined;
         const failedInvocation = recovery
             ? [...model.provider_invocations].reverse().find((item) => typeof item.status === "string" && item.status.startsWith("failed"))
@@ -1100,6 +1199,31 @@ function servicesNextEnvelope(model) {
             safe_payload: item.safe_payload,
         }));
         const selection = model.allowed_actions?.find((action) => action.type === "select_candidate");
+        const railCatalog = currentItems.some((item) => {
+            const container = (item.safe_payload?.result ?? item.safe_payload);
+            return container?.catalog_page !== undefined || container?.cost_semantics !== undefined;
+        });
+        const pageRecovery = currentItems.flatMap((item) => {
+            const container = (item.safe_payload?.result ?? item.safe_payload);
+            const catalogPage = container?.catalog_page;
+            const nextOffset = catalogPage?.next_offset;
+            return typeof nextOffset === "number"
+                ? [{ command: `itpay services page ${execution.service_execution_id} ${item.service_capability_result_item_id} --offset ${nextOffset} --json`, reason: "读取已保存结果的同版本下一页，不重新查询、不消耗额度" }]
+                : [];
+        });
+        const railCostGuidance = "铁路应付只含票价加服务费（quoted_total_minor）；地面接驳是单独估算（estimated_ground_minor），两者相加是已知估算（estimated_door_to_door_minor），不是收款额。";
+        const instruction = (delivery?.order_id
+            ? appendFeedbackPostmortemInstruction(items.length > 0
+                ? selection
+                    ? "搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才执行 next.command；不要提及 safe_payload。"
+                    : "这一步的结果已经可用。用普通语言解释可公开字段并停止；不要提及 Arazzo、safe_payload 或内部 ID。"
+                : "告诉用户本次查询得到 0 个结果并停止。Agent 不读取其他交付、不重放当前查询、修改输入或创建新查询。", "delivered")
+            : items.length > 0
+                ? selection
+                    ? "搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才执行 next.command；不要提及 safe_payload。"
+                    : "这一步的结果已经可用。用普通语言解释可公开字段并停止；不要提及 Arazzo、safe_payload 或内部 ID。"
+                : "告诉用户本次查询得到 0 个结果并停止。Agent 不读取其他交付、不重放当前查询、修改输入或创建新查询。")
+            + (railCatalog && items.length > 0 ? ` ${railCostGuidance}` : "");
         return {
             status: items.length > 0 ? "result_ready" : "no_result",
             result: {
@@ -1109,22 +1233,12 @@ function servicesNextEnvelope(model) {
                 delivery_mode: deliveryMode,
                 items,
             },
-            instruction: delivery?.order_id
-                ? appendFeedbackPostmortemInstruction(items.length > 0
-                    ? selection
-                        ? "搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才执行 next.command；不要提及 safe_payload。"
-                        : "这一步的结果已经可用。用普通语言解释可公开字段并停止；不要提及 Arazzo、safe_payload 或内部 ID。"
-                    : "告诉用户本次查询得到 0 个结果并停止。Agent 不读取其他交付、不重放当前查询、修改输入或创建新查询。", "delivered")
-                : items.length > 0
-                    ? selection
-                        ? "搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才执行 next.command；不要提及 safe_payload。"
-                        : "这一步的结果已经可用。用普通语言解释可公开字段并停止；不要提及 Arazzo、safe_payload 或内部 ID。"
-                    : "告诉用户本次查询得到 0 个结果并停止。Agent 不读取其他交付、不重放当前查询、修改输入或创建新查询。",
+            instruction,
             next: selection ? {
                 command: `itpay services action ${execution.service_execution_id} --action select_candidate --actor-type human --status approved --candidate <rank> --json`,
                 reason: "仅在用户明确选择后锁定来源候选",
             } : null,
-            recovery: [],
+            recovery: pageRecovery,
         };
     }
     if (deliveryMode === "vault_artifact") {
@@ -1453,6 +1567,7 @@ export async function runServicesRun(backend, config, serviceID, input, options
             const started = await backend.startServiceExecution({
                 service_id: serviceID,
                 client_context: { host: options.host ?? "terminal", ...(options.target ? { target: options.target } : {}) },
+                ...(input !== undefined ? { input } : {}),
             });
             id = started.execution.service_execution_id;
             if (!started.workflow_entry) {
@@ -1470,6 +1585,9 @@ export async function runServicesRun(backend, config, serviceID, input, options
         if (input !== undefined) {
             model = await backend.advanceServiceExecution(id, input, `workflow-input:${id}`);
         }
+        else if (model.workflow?.status === "quota_paused") {
+            model = await backend.advanceServiceExecution(id, undefined, `workflow-resume:${id}`);
+        }
         const until = Date.now() + (options.timeoutSeconds ?? 120) * 1000;
         const sleep = options.sleep ?? ((milliseconds) => new Promise(resolve => setTimeout(resolve, milliseconds)));
         const paid = () => model.payment_bindings.some((binding) => binding.status === "payment_verified") || model.checkout_bindings.some((binding) => binding.status === "payment_verified");

package/dist/src/main.js

@@ -29,7 +29,7 @@ import { runInstall } from "./commands/install.js";
 import { runSkillShow } from "./commands/skill.js";
 import { runNext } from "./commands/next.js";
 import { runVaultAccess, runVaultList, runVaultRead } from "./commands/vault.js";
-import { collectOption, parseKeyValueList, runServicesAction, runServicesCheckout, runServicesEvents, runServicesGet, runServicesInvoke, runServicesList, runServicesNext, runServicesReadResult, runServicesQuote, runServicesStart, } from "./commands/services.js";
+import { collectOption, parseKeyValueList, runServicesAction, runServicesCheckout, runServicesEvents, runServicesGet, runServicesInvoke, runServicesList, runServicesNext, runServicesPage, runServicesReadResult, runServicesQuote, runServicesStart, } from "./commands/services.js";
 const program = new Command();
 program
     .name("itpay")
@@ -1267,6 +1267,35 @@ services
         });
     }
 });
+services
+    .command("page")
+    .description("Read one page of a saved service result set (same stored version, no re-query, no quota)")
+    .argument("<service_execution_id>")
+    .argument("<result_item_id>")
+    .option("--offset <offset>", "zero-based candidate offset", Number, 0)
+    .option("--limit <limit>", "page size (1-20)", Number, 5)
+    .option("--json", "output JSON")
+    .action(async (serviceExecutionID, resultItemID, options) => {
+    const config = loadConfig();
+    const backend = newBackendClient(config);
+    try {
+        await runServicesPage(backend, serviceExecutionID, resultItemID, {
+            offset: options.offset,
+            limit: options.limit,
+            jsonOutput: Boolean(options.json),
+        });
+    }
+    catch (error) {
+        reportCLIError(error, {
+            jsonOutput: Boolean(options.json),
+            code: "service_page_failed",
+            instruction: "分页读取的是已保存的同版本结果；不要重新发起查询或新建 execution。",
+            recovery: [
+                { command: `itpay services next ${serviceExecutionID} --json`, reason: "读取当前结果页与合法动作" },
+            ],
+        });
+    }
+});
 services
     .command("start")
     .description("Start a contract-backed service execution")

package/dist/src/state/account_auth.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import { dirname, resolve } from 'node:path';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, rmSync } from 'node:fs';
+import { writeLocalPNG } from '../render/qr.js';
 export function sellerAuthPath(baseURL, env = process.env, purpose = "seller") {
     return resolve(env.HOME || homedir(), '.itpay-v3', `${purpose}-${createHash('sha256').update(baseURL).digest('hex').slice(0, 16)}.json`);
 }
@@ -37,7 +38,13 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
     if (backend) {
         const current = await backend.agentAccountStatus();
         if (current.status === 'authenticated')
-            return current;
+            return {
+                status: 'authenticated',
+                result: { bound: true, phone_verified: current.phone_verified === true },
+                instruction: '设备已绑定账号，可继续之前的查询或购买；登录不附带任何额外授权。',
+                next: { command: 'itpay services run <service_id> --execution <pending_execution_id> --json', reason: '恢复被额度暂停的原执行' },
+                recovery: [],
+            };
     }
     async function request(path, init = {}) {
         const response = await fetcher(baseURL + path, { ...init, redirect: 'error', signal: AbortSignal.timeout(15000) });
@@ -46,7 +53,28 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
         return response;
     }
     if (action === 'login') {
-        const response = await request('/v1/dashboard/auth-sessions', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ provider: 'alipay', return_to: backend ? '/' : '/seller' }) });
+        if (backend) {
+            const open = read(baseURL, env, purpose);
+            if (open?.sessionID && open.pollToken && open.startToken) {
+                try {
+                    const current = await (await request(`/v1/dashboard/auth-sessions/${encodeURIComponent(open.sessionID)}?poll_token=${encodeURIComponent(open.pollToken)}`)).json();
+                    if (['created', 'waiting_provider', 'email_verification_required', 'merge_confirmation_required'].includes(current.status)) {
+                        const url = open.authURL ?? '';
+                        const qr = url ? await writeLocalPNG(url).catch(() => undefined) : undefined;
+                        return {
+                            status: 'auth_pending',
+                            result: { dashboard_auth_session_id: open.sessionID, expires_at: current.expires_at, methods: ['phone', 'email', 'alipay', 'wechat'] },
+                            handoff: { url, ...(qr ? { qr_local_path: qr.filePath, markdown: `![ItPay 官方授权二维码](${qr.filePath})` } : {}) },
+                            instruction: '已有进行中的官方授权请求，沿用同一链接或二维码；不要生成新请求。用户在页面内选择手机号验证码、邮箱或钱包完成登录。',
+                            next: { command: 'itpay auth status --json', reason: '用户完成页面登录后确认绑定', poll_after_ms: 5000 },
+                            recovery: [],
+                        };
+                    }
+                }
+                catch { /* fall through to a fresh request */ }
+            }
+        }
+        const response = await request('/v1/dashboard/auth-sessions', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ return_to: backend ? '/' : '/seller' }) });
         const result = await response.json();
         const url = new URL(result.start_url, baseURL);
         const sameOrigin = url.origin === new URL(baseURL).origin;
@@ -60,7 +88,25 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
             : url.searchParams.get('start_token') || fragment.get('start_token');
         if (!startToken || !result.poll_token || !result.dashboard_auth_session_id)
             throw new Error('Incomplete authorization response');
-        save({ baseURL, sessionID: result.dashboard_auth_session_id, pollToken: result.poll_token, startToken }, env, purpose);
+        save({ baseURL, sessionID: result.dashboard_auth_session_id, pollToken: result.poll_token, startToken, authURL: url.href }, env, purpose);
+        if (backend) {
+            const qr = await writeLocalPNG(url.href).catch(() => undefined);
+            return {
+                status: 'auth_pending',
+                result: {
+                    dashboard_auth_session_id: result.dashboard_auth_session_id,
+                    expires_at: result.expires_at,
+                    methods: ['phone', 'email', 'alipay', 'wechat'],
+                },
+                handoff: {
+                    url: url.href,
+                    ...(qr ? { qr_local_path: qr.filePath, markdown: `![ItPay 官方授权二维码](${qr.filePath})` } : {}),
+                },
+                instruction: '把官方授权页或二维码交给用户。用户在页面内选择手机号验证码、邮箱或钱包完成登录；不要替用户输入手机号或验证码，start_token 不要写入聊天记录。',
+                next: { command: 'itpay auth status --json', reason: '用户完成页面登录后确认绑定', poll_after_ms: 5000 },
+                recovery: [],
+            };
+        }
         return { status: 'authorization_required', authorization_url: url.href, instruction: `Complete ItPay login in the browser, then run ${command}.` };
     }
     const state = read(baseURL, env, purpose);
@@ -77,14 +123,50 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
         return { status: 'login_required' };
     const path = `/v1/dashboard/auth-sessions/${encodeURIComponent(state.sessionID)}`;
     const progress = await (await request(`${path}?poll_token=${encodeURIComponent(state.pollToken)}`)).json();
-    if (progress.status !== 'completed')
+    if (progress.status !== 'completed') {
+        if (backend) {
+            if (progress.status === 'expired') {
+                rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
+                return {
+                    status: 'auth_expired',
+                    result: { dashboard_auth_session_id: state.sessionID },
+                    instruction: '授权请求已过期。重新运行 itpay auth login 生成新请求；之前的查询输入在服务端保留，可恢复。',
+                    next: { command: 'itpay auth login --json', reason: '重新发起官方授权' },
+                    recovery: [],
+                };
+            }
+            if (progress.status === 'failed' || progress.status === 'cancelled' || progress.status === 'denied') {
+                rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
+                return {
+                    status: progress.status === 'failed' ? 'auth_denied' : `auth_${progress.status}`,
+                    result: { dashboard_auth_session_id: state.sessionID },
+                    instruction: '官方授权未通过或被取消。重新运行 itpay auth login 生成新请求。',
+                    next: { command: 'itpay auth login --json', reason: '重新发起官方授权' },
+                    recovery: [],
+                };
+            }
+            return {
+                status: 'auth_pending',
+                result: { dashboard_auth_session_id: state.sessionID },
+                instruction: '用户仍在官方页面完成登录；保留当前 handoff，不要生成新二维码或新请求。',
+                next: { command: 'itpay auth status --json', reason: '轮询同一授权请求', poll_after_ms: 5000 },
+                recovery: [],
+            };
+        }
         return { status: progress.status, instruction: 'Finish login and email verification in the browser.' };
+    }
     if (backend) {
         const result = await backend.bindAgentAccount({ dashboard_auth_session_id: state.sessionID, start_token: state.startToken });
         if (result.status !== 'authenticated')
             throw new Error('Agent binding did not complete');
         rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
-        return result;
+        return {
+            status: 'authenticated',
+            result: { bound: true, phone_verified: result.phone_verified === true },
+            instruction: '登录与绑定已完成，告知用户可继续之前的查询；已注册账号查询不消耗试用次数，仍受正常限流。',
+            next: { command: 'itpay services run <service_id> --execution <pending_execution_id> --json', reason: '恢复被额度暂停的原查询' },
+            recovery: [],
+        };
     }
     const claimed = await request(`${path}/claim?start_token=${encodeURIComponent(state.startToken)}`, { method: 'POST' });
     const token = /(?:^|[, ]+)itpay_buyer_session=([^;]+)/.exec(claimed.headers.get('set-cookie') ?? '')?.[1];

package/dist/src/state/config.js

@@ -15,8 +15,8 @@ import { OperationJournal } from "./operation_journal.js";
 export const DEFAULT_BASE_URL = "https://app.itpay.ai";
 export const DEV_BASE_URL = "https://dev.itpay.ai";
 export const SANDBOX_BASE_URL = "https://sandbox.itpay.ai";
-export const CLI_VERSION = "2.1.6";
-export const API_CONTRACT_REVISION = "sha256:42659989d533d5a43c4ab92eb2455bcbbc6456e799fa4c2b6587de77f06b95f7";
+export const CLI_VERSION = "2.1.8";
+export const API_CONTRACT_REVISION = "sha256:66a95bbc5ec9d7b35747cf87206c63dd45983f26de21afab582d8dd63bf198f7";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";

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

@@ -1,19 +1,21 @@
 {
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
-  "product_scope": "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_scope": "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 use the same entry point via itpay sell.",
   "topic": "rail-booking",
   "title": "Railway Query, Planning, and Ticket Booking",
-  "purpose": "Choose the right railway service for the buyer's situation, submit the exact input contract each service expects, and follow the protected booking flow without inventing field names.",
+  "purpose": "Choose the right railway service for the buyer's situation, submit the exact input contract each service expects, bridge a chosen train into booking via the server-issued selection, and follow the protected checkout flow without inventing field names.",
   "when_to_use": [
     "The buyer wants train schedules, routes, or tickets.",
     "A railway service execution fails at the geo, search, catalog, or recommend step.",
     "The buyer only knows a city or fuzzy location rather than a station name.",
-    "The buyer asks about seat preferences, refunds, or ticket issuance status."
+    "The buyer asks about seat preferences, refunds, or ticket issuance status.",
+    "A query returned login_required or rate_limited."
   ],
   "service_selection": {
     "itpay-rail-exact": "Use when the buyer knows BOTH the exact departure and arrival railway station names (e.g. 古镇 → 广州南). Direct train query, fastest path. Do NOT use it with only a city or fuzzy location.",
     "itpay-rail-smart": "Use when the buyer has a city name, an area, an address, or wants transfer planning and recommendations. The platform resolves locations to stations itself; never silently convert a city into its namesake station.",
+    "itpay-rail-booking": "Purchase service — use ONLY after the buyer explicitly chose a train and seat from a query result. Starts quote → protected checkout → payment → asynchronous issuance on one execution. Never queried for schedules.",
     "svc_qizhidao_company_lookup": "Not a railway service; do not mix intents."
   },
   "input_contract": {
@@ -43,13 +45,41 @@
         "max_transfers": "Integer 0-2, allowed transfer count."
       },
       "example": {"origin": "中山古镇", "destination": "广州南", "travel_date": "2026-09-19", "priority": "fastest"}
+    },
+    "itpay-rail-booking": {
+      "preferred": {
+        "passengers": "Integer 1-5: number of passengers, NOT passenger identity records.",
+        "selection": {
+          "token": "The booking_offer.selection_token carried on the chosen result item.",
+          "seat_type": "Seat code when the user picked a specific class, e.g. O."
+        }
+      },
+      "explicit_legs": {
+        "passengers": "Integer 1-5.",
+        "legs": "Array of 1-3 legs, each: from_station_code, to_station_code, travel_date, train_code, departure_time (HH:MM), arrival_time (HH:MM), arrival_days (int 0-7), seat_type. Only use when no booking_offer is available; never guess these values."
+      },
+      "boundary": "Identity fields (names, ID numbers, phones) never belong in this input; they are collected on the protected checkout page."
     }
   },
+  "selection_flow": [
+    "Exact results carry per-train candidates; smart results carry journeys. Bookable options carry booking_offer with a server-signed selection_token.",
+    "The token binds the stored result snapshot and the chosen option. Submit it with passengers (and seat_type when the user picked a class); the server derives the authoritative legs and re-quotes live. Do NOT hand-build legs JSON from the visible result.",
+    "An expired or foreign token returns a clear error; recover by running a fresh query or by explicit legs — never by guessing token contents.",
+    "Repeating the same selection restores the same booking execution instead of creating a second one."
+  ],
+  "trial_and_login": {
+    "policy": "itpay-rail-exact and itpay-rail-smart each allow 2 anonymous queries per enrolled device lineage — independent counters, not a shared pool of 4.",
+    "login_required": "Trial for that service is exhausted. The query is paused BEFORE provider calls; the execution keeps its input. Offer itpay auth login; after binding, resume the SAME execution with services run --execution <id> (no input file). Do not start a new execution, do not make the user re-describe the trip, and do not burn the other service's quota to dodge the gate.",
+    "rate_limited": "Registered accounts have no cumulative search cap but normal per-minute limits apply; wait retry_after_ms and resume the same execution.",
+    "fourth_result": "The 4th result is delivered first; only the next new query requires authorization.",
+    "purchase_after_trial": "Selecting a saved option and buying it does not consume search quota and works even when trial is exhausted."
+  },
   "flow": [
     "services start <service> --json returns input_required plus the guidance block for rail services.",
     "Submit input with services run <service> --execution <id> --input-json <file> --json on the SAME execution.",
     "itpay-rail-smart may stop at a location confirmation step; show the candidate places to the buyer, then continue the same execution after the human confirms.",
-    "After a train and seat are chosen, the booking flow moves to a protected checkout page: passenger identity data is entered by the human on that page, never through the CLI.",
+    "After the buyer explicitly picks a train/seat, run itpay-rail-booking with the selection token (preferred) or explicit legs.",
+    "The booking execution reaches a protected checkout: passenger identity data is entered by the human on that page, never through the CLI. Account authentication may happen inside checkout — do not force a separate auth login first (Path B).",
     "Payment success does not mean the ticket is issued. Issuance is asynchronous; keep reading the same execution with services next.",
     "If seat details are still syncing after issuance, advise the buyer to verify the itinerary on 12306 instead of repeating the query."
   ],
@@ -58,6 +88,7 @@
     "geo": "Location resolution failed: check origin/destination are real place names, or attach origin_city/coordinate hints, then start a NEW execution (a failed execution is terminal).",
     "search": "Supplier query failed: most commonly a wrong field name (must be travel_date) or a nonexistent station name; recheck input against this doc.",
     "catalog_or_recommend": "Location resolved but no feasible trains: change the date or stations.",
+    "login_required_is_not_failure": "login_required / rate_limited pause the execution; they are NOT failures and never justify a replacement execution.",
     "general_rule": "Never replay a failed execution and never guess different field names; correct the input and start a new execution of the same service."
   },
   "seat_preferences": {
@@ -66,15 +97,17 @@
     "boundary": "Never claim a preference was fulfilled before supplier confirmation; check the issued seat in the order/status output."
   },
   "agent_rules": [
-    "Pick the service by the buyer's input precision: exact station names → itpay-rail-exact; anything fuzzier → itpay-rail-smart.",
+    "Pick the service by the buyer's input precision: exact station names → itpay-rail-exact; anything fuzzier → itpay-rail-smart; explicit purchase intent after a selection → itpay-rail-booking.",
     "Never invent input field names. If the guidance block or this doc does not list a field, do not send it.",
     "Never ask the buyer for passenger names, ID numbers, or phone numbers in chat; those are collected only on the protected checkout page.",
+    "Never reconstruct provider-shaped legs JSON when a booking_offer.selection_token is available; submit the token plus passengers.",
+    "login_required and rate_limited are pauses, not failures: resume the same execution, never spawn a replacement.",
     "Do not repeat or replay a failed execution; correct the input and start a new one.",
     "Do not claim payment equals ticket issuance; issuance is asynchronous and confirmed only by the issued seat status."
   ],
   "human_language": {
-    "prefer": ["车次", "出发站", "到达站", "出行日期", "座位", "余票", "出票中", "已出票"],
-    "avoid": ["workflow", "execution", "provider", "seat_source", "candidate_id"]
+    "prefer": ["车次", "出发站", "到达站", "出行日期", "座位", "余票", "出票中", "已出票", "登录后继续免费查询"],
+    "avoid": ["workflow", "execution", "provider", "seat_source", "candidate_id", "token", "quota"]
   },
   "search_terms": ["rail", "railway", "train", "ticket", "火车", "火车票", "高铁", "车票", "车次", "seat", "booking", "rail-booking"]
 }

package/docs/cli-reference/commands/auth.md

@@ -1,9 +1,93 @@
 # Account login
 
-Use `itpay auth login --json` to enroll the current Agent and open the official ItPay Web login. After the user finishes login and email verification, run `itpay auth status --json` to bind this enrolled Agent to the account. Keep declaring the actual `--agent-type` on both commands.
+`itpay auth` binds the enrolled Agent Device to a real ItPay account through an official authorization handoff. It is used by Path A (trial exhausted → log in → keep querying) and any time a command returns `login_required`. Path B purchases do **not** require running `itpay auth login` first — account authentication can happen inside the protected checkout instead.
 
-For dev, keep `ITPAY_BACKEND_URL=https://dev.itpay.ai` on every command. Login state and device registration are isolated from production.
+## Syntax
 
-Railway exact and smart query services each allow two anonymous queries after enrollment. After login, queries remain free within the published per-minute limits. On `login_required`, finish login and start a new query. On `rate_limited`, wait until the next minute; do not clear device state or retry in a loop.
+```bash
+itpay auth login  [--json]
+itpay auth status [--json]
+```
 
-The Agent receives no general account bearer token. This binding reuses the existing stable device-account ownership mechanism; switching account owners is not supported. Seller authoring continues to use `itpay sell auth` separately.
+Both commands require an enrolled Agent Device and use the current `--agent-type` and Backend (`ITPAY_BACKEND_URL`). The Agent never receives an account bearer token; binding reuses the stable device-account ownership mechanism.
+
+## `itpay auth login`
+
+Creates one official authorization request bound to this Backend, Device and Agent Instance, then stops. Repeating `auth login` while a valid request is open returns the same request — it does not rotate the QR code or create parallel sessions.
+
+```json
+{
+  "status": "auth_pending",
+  "result": {
+    "dashboard_auth_session_id": "das_...",
+    "expires_at": "2026-09-20T12:34:56Z",
+    "methods": ["phone", "email", "alipay", "wechat"]
+  },
+  "handoff": {
+    "url": "https://dev.itpay.ai/signin?dashboard_auth_session_id=das_...&start_token=...",
+    "qr_local_path": "...",
+    "qr_image_url": "...",
+    "markdown": "..."
+  },
+  "instruction": "把官方授权页或二维码交给用户。用户在页面内选择手机号验证码、邮箱或钱包完成登录；不要替用户输入手机号或验证码。",
+  "next": {
+    "command": "itpay auth status --json",
+    "reason": "用户完成页面登录后确认绑定",
+    "poll_after_ms": 5000
+  },
+  "recovery": []
+}
+```
+
+- `handoff.url` is the official sign-in page carrying this authorization request. The page offers phone-code verification, email verification, and wallet options — the user chooses; the Agent must not deep-link a single wallet and call it universal authorization.
+- The URL's `start_token` is valid only inside the official page handoff. Never log it, echo it in chat, or send it to another host.
+- When the user already finished login before `auth login` runs, the command returns `authenticated` directly.
+
+## `itpay auth status`
+
+Polls the open authorization request, then performs the device binding. Safe to run repeatedly and concurrently: only the requester Device/Instance can complete the binding.
+
+```json
+{
+  "status": "auth_pending",
+  "result": { "dashboard_auth_session_id": "das_...", "expires_at": "..." },
+  "instruction": "用户仍在官方页面完成登录；保留当前 handoff，不要生成新二维码。",
+  "next": { "command": "itpay auth status --json", "poll_after_ms": 5000 },
+  "recovery": []
+}
+```
+
+```json
+{
+  "status": "authenticated",
+  "result": {
+    "buyer_id": "buyer_...",
+    "bound": true,
+    "query_quota": [
+      { "service_id": "itpay-rail-exact", "policy": "free_registered", "remaining": null },
+      { "service_id": "itpay-rail-smart", "policy": "free_registered", "remaining": null }
+    ]
+  },
+  "instruction": "登录与绑定已完成，告知用户可继续之前的查询；已注册账号查询不消耗试用次数，仍受正常限流。",
+  "next": { "command": "itpay services run <service_id> --execution <pending_execution_id> --json", "reason": "恢复被额度暂停的原查询" },
+  "recovery": []
+}
+```
+
+Terminal and error states:
+
+| `status` | Meaning | Agent action |
+| --- | --- | --- |
+| `authenticated` | Device bound to a real account | Resume the original intent (a quota-blocked execution, the user's request) unchanged |
+| `auth_pending` | User has not finished the page | Keep the same handoff; poll with `poll_after_ms` |
+| `auth_expired` | Session expired before completion | Offer to start `itpay auth login` again; prior query input is still preserved server-side |
+| `login_required` | No open request, not bound | Run `itpay auth login` |
+| `auth_cancelled` / `auth_denied` | User declined or closed the page | Respect the refusal; do not silently re-open; the pending query stays resumable |
+
+## Rules
+
+- The human's phone number and SMS code are entered only on the official page — never through chat or CLI input. A `buyer_id`, a typed phone string, or a passenger phone is **not** proof of phone verification.
+- Login never grants Vault content, passenger history, or another Agent's authority. Other devices/platforms enroll and authorize separately.
+- After `authenticated`, server-side identity is re-read; an anonymous execution blocked at the quota step resumes with `services run <service> --execution <id> --json` — no new execution, no re-asked itinerary.
+- Refusing or cancelling login deletes nothing: saved results and purchase options remain usable.
+- Seller authoring uses `itpay sell auth` separately.

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

@@ -6,6 +6,8 @@
 
 为单个 Service Execution 快速创建或恢复 Checkout，并按 Host 向人交接付款入口。它是 `services quote -> cart add --quote -> buy --cart` 的单项快捷方式，必须复用相同的 Quote、Cart 和 Checkout Use Case。
 
+未注册/未登录用户不要求先执行 `itpay auth login`（Path B）：官方 checkout 页内完成必要的钱包认证、创建或复用账号并取得页面权限；人在页面上确认旅客、通知邮箱和最终报价后付款。支付确认沿用既有设备绑定机制，不再独立绑定。checkout 内完成账号认证不等于账号已通过手机号验证；钱包显示名、账号手机号与乘车人身份互相独立。
+
 **上游：** `services next` 返回的 `prepare_quote` capability 和已验证输入。
 **下游：** 人完成 Checkout，随后 `checkout` 或 `services next`。
 

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

@@ -197,6 +197,58 @@ itpay services next <service_execution_id> [--json]
 
 `succeeded` 退款改为“交付永久关闭”，并返回 `next: null`。取消、拒绝或确定未产生资金影响的失败退款不再阻塞，但旧 grant 不会复活；用户必须重新授权。
 
+## 额度暂停（试用/限流）
+
+查询 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"
+  }
+}
+```
+
+用户明确选择某班次/席别并要求购买时，用该 token 开启购票执行：
+
+```bash
+itpay services run itpay-rail-booking --input-json booking.json --json
+# booking.json: {"passengers": 1, "selection": {"token": "<selection_token>", "seat_type": "O"}}
+```
+
+`booking_offer` 只是受条件约束的可选承接：查询完成本身已满足查询目标，不自动购买；过期 token 返回明确错误，恢复方式是按 `services run` 输入合同重新查询或显式提供 `legs`。
+
 ## 异常处理
 
 execution 不存在或不属于当前设备/账号时返回错误信封，并仅建议：

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

@@ -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.6",
+  "version": "2.1.8",
   "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: