@itpay/cli 2.1.41 → 2.1.45

package/README.md

@@ -4,7 +4,7 @@ The official V3 CLI and the single ItPay entry point for services, purchases, ac
 
 ## One Entry Point, Several Human Intents
 
-`itpay` is the only public CLI entry point, and `$itpay` is its user-facing Skill invocation. The Agent first distinguishes a new service request, previously purchased content, order history, or a refund. Seller workflows will use the same entry point later and are not implemented yet.
+`itpay` is the only public CLI entry point, and `$itpay` is its user-facing Skill invocation. The Agent first distinguishes a new service request, previously purchased content, order history, or a refund. Seller workflows use the existing `itpay sell` entry point.
 
 ```bash
 npm install -g @itpay/cli
@@ -25,7 +25,7 @@ Official Agent install prompt（可直接复制给 Agent）：
 Use a separate test prompt to set the exact official Dev Backend. Never put a
 Dev override in the public install prompt.
 
-The CLI defaults to the production Backend `https://app.itpay.ai`. Explicit tests may set `ITPAY_BACKEND_URL=https://dev.itpay.ai`; every other Backend URL is rejected before network or local state access.
+The CLI defaults to the production Backend `https://app.itpay.ai`. Explicit sandbox runs may set `ITPAY_BACKEND_URL=https://sandbox.itpay.ai`; every other Backend URL is rejected before network or local state access.
 
 ## Output Contract
 
@@ -54,6 +54,7 @@ Normative per-command contracts: [CLI Command Reference](docs/cli-reference/inde
 | `claude-code-cli` | `terminal` |
 | `workbuddy` | `plain-chat` |
 | `zcode` | `plain-chat` |
+| `doubao-work` | `plain-chat` |
 | `kimi-code` | `terminal` |
 | `openclaw` | 必须显式提供 |
 
@@ -67,7 +68,7 @@ The local installation keeps one Ed25519 private key and a separate registration
 - `services start/invoke/action/checkout/next`: generic Service Execution flow.
 - `cart add/show/remove/clear/next`, `buy`: canonical Cart and ordinary Checkout flow.
 - `checkout`: authoritative payment and fulfillment recovery.
-- `services read-result`: read one human-granted protected result.
+- `services read-result`: read saved railway query pages or human-granted protected content.
 - `order`, `orders`: exact order and account order views.
 - `vault list/access/read`: find and read previously purchased content after time-limited human authorization.
 - `refund create/list/get/watch/cancel`: Refund Owner flow.
@@ -90,12 +91,12 @@ itpay --agent-type <agent_type> services checkout <service_execution_id> --resum
 itpay checkout --id <checkout_id> --token <display_token> --json
 ```
 
-The local `~/.itpay-v3` directory stores one owner-only signing key, Backend-scoped Device registrations and Agent instances, idempotency operations, and recovery handles. Production uses `cart.json` / `operations.json`; dev uses `cart.dev.json` / `operations.dev.json`. Backend state remains authoritative. Do not delete or rotate this identity to recover quota.
+The local `~/.itpay-v3` directory stores one owner-only signing key, Backend-scoped Device registrations and Agent instances, idempotency operations, and recovery handles. Production uses `cart.json` / `operations.json`; sandbox uses `cart.sandbox.json` / `operations.sandbox.json`. Backend state remains authoritative. Do not delete or rotate this identity to recover quota.
 
 ## Environment
 
 - `ITPAY_AGENT_TYPE`: stable alternative to global `--agent-type`.
-- `ITPAY_BACKEND_URL`: optional test override; only the exact official URL `https://dev.itpay.ai` is accepted. Unset it for production.
+- `ITPAY_BACKEND_URL`: optional sandbox override; only the exact official URL `https://sandbox.itpay.ai` is accepted. Unset it for production.
 - `ITPAY_BEARER_TOKEN`: optional account-scoped browser session for legacy account reads. Local Agents normally use signed Device Authority plus the time-limited human authorization returned by `vault access`.
 - `ITPAY_CART_SESSION_PATH`: local recovery-state path override.
 - `ITPAY_CURRENCY`: ordinary Cart currency, default `CNY`.
@@ -127,3 +128,9 @@ Source boundaries:
 - `src/state`: local Device Authority, idempotency journal, and recovery handles.
 - `docs/cli-reference`: normative command contracts.
 - `docs/agent/buyer`: packaged progressive workflow guidance.
+
+### Run a published service
+
+Use `itpay services run <service_id> --input-json ./input.json --json` for a published workflow. The input file must contain a JSON object matching the service input schema. With no input file, the CLI reports required fields and a command to continue the same execution.
+
+Use `itpay services run <service_id> --execution <execution_id> --json` to resume. At payment, the CLI uses the existing Checkout QR/card handoff. The backend continues after verified payment even if the CLI exits. `--timeout <seconds>` controls initial status polling (default 120, maximum 600). Use existing order/refund commands for refund requests; an application is not a successful refund until its final status confirms success.

package/assets/sell-preview/index.html

@@ -0,0 +1,6 @@
+<!doctype html>
+<html lang="zh-CN"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>ItPay 工作流预览</title>
+<style>body{max-width:1000px;margin:40px auto;padding:0 24px;font:16px/1.6 system-ui;color:#17212b;background:#fafbfc}pre{padding:20px;background:white;border:1px solid #dde3e8;border-radius:8px;overflow:auto;white-space:pre-wrap}small{color:#52616e}h2{margin-top:32px}</style>
+<h1>工作流预览</h1><p id="status" role="status">正在读取本地项目…</p><small>只读本地预览。正式发布仍需平台验证、审核和 Canary。</small>
+<h2>工作流</h2><pre id="document"></pre><h2>价格配置</h2><pre id="pricing"></pre><h2>最近测试</h2><pre id="run"></pre>
+<script src="preview.js"></script></html>

package/assets/sell-preview/preview.js

@@ -0,0 +1,9 @@
+fetch('document', {cache:'no-store'}).then(response => {
+  if (!response.ok) throw new Error('请先初始化项目并保存工作流版本。');
+  return response.json();
+}).then(data => {
+  document.getElementById('status').textContent = `版本：${data.version} · ${data.hash}`;
+  document.getElementById('document').textContent = data.document;
+  document.getElementById('pricing').textContent = JSON.stringify(data.pricing, null, 2);
+  document.getElementById('run').textContent = data.run ? JSON.stringify(data.run, null, 2) : '尚无本地测试记录';
+}).catch(error => { document.getElementById('status').textContent = error.message; });

package/dist/src/client/backend.js

@@ -5,6 +5,19 @@ export class BackendClient {
     constructor(http) {
         this.http = http;
     }
+    get localSimulation() { return this.http.localSimulation; }
+    // Called only through the fixed Sell operation contract, never arbitrary Agent URLs.
+    sellRequest(request) {
+        if (!request.path.startsWith("/v1/seller/organizations") && !request.path.startsWith("/v1/library/"))
+            throw new Error("Invalid Sell route");
+        return this.http.request(request.path, { method: request.method, ...(request.body !== undefined ? { body: request.body } : {}) });
+    }
+    agentAccountStatus() {
+        return this.http.get('/v1/agent-device-account-bindings');
+    }
+    bindAgentAccount(input) {
+        return this.http.post('/v1/agent-device-account-bindings', input);
+    }
     readyz() {
         return this.http.get("/v1/readyz");
     }
@@ -90,6 +103,11 @@ export class BackendClient {
     readBuyerVaultArtifact(artifactRef, sections) {
         return this.http.post(`/v1/vault/artifacts/${encodeURIComponent(artifactRef)}/reads`, sections.length ? { sections } : {});
     }
+    listRailAftercare(orderID) { return this.http.get(`/v1/orders/${encodeURIComponent(orderID)}/rail-aftercare`); }
+    createRailAftercare(orderID, input, idempotencyKey) { return this.http.post(`/v1/orders/${encodeURIComponent(orderID)}/rail-aftercare`, input, { idempotencyKey }); }
+    getRailAftercare(id) { return this.http.get(`/v1/rail-aftercare/${encodeURIComponent(id)}`); }
+    respondRailAftercare(id, input) { return this.http.post(`/v1/rail-aftercare/${encodeURIComponent(id)}/respond`, input); }
+    cancelRailAftercare(id, input) { return this.http.post(`/v1/rail-aftercare/${encodeURIComponent(id)}/cancel`, input); }
     // --- Refund ---
     createRefund(orderID, input, bearer, idempotencyKey) {
         const options = { ...(bearer ? { bearer } : {}), ...(idempotencyKey ? { idempotencyKey } : {}) };
@@ -108,6 +126,15 @@ export class BackendClient {
     startServiceExecution(input) {
         return this.http.post("/v1/service-executions", input);
     }
+    advanceServiceExecution(id, input, idempotencyKey) {
+        return this.http.post(`/v1/service-executions/${encodeURIComponent(id)}/advance`, { input, idempotency_key: idempotencyKey });
+    }
+    getServiceExecutionResultItemPage(serviceExecutionID, resultItemID, offset, limit, view) {
+        const qs = new URLSearchParams({ offset: String(offset), limit: String(limit) });
+        if (view)
+            qs.set("view", view);
+        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) });
     }
@@ -120,8 +147,9 @@ export class BackendClient {
     prepareServiceQuote(serviceExecutionID, input) {
         return this.http.post(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/quotes`, input, { replaySafe: true });
     }
-    getServiceExecution(serviceExecutionID) {
-        return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}`);
+    getServiceExecution(serviceExecutionID, opts = {}) {
+        const query = opts.sinceSnapshot ? `?since_snapshot=${encodeURIComponent(opts.sinceSnapshot)}` : "";
+        return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}${query}`);
     }
     listServiceExecutions(limit = 50) {
         return this.http.get(`/v1/service-executions?limit=${limit}`);
@@ -136,6 +164,14 @@ export class BackendClient {
     getGrantedServiceResult(serviceExecutionID) {
         return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/granted-result`);
     }
+    getRailPlanningCatalog(serviceExecutionID, snapshotID) {
+        const query = snapshotID ? `?snapshot=${encodeURIComponent(snapshotID)}` : "";
+        return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/rail-planning/catalog${query}`);
+    }
+    getRailJourneyDetail(serviceExecutionID, journeyID, snapshotID) {
+        const query = snapshotID ? `?snapshot=${encodeURIComponent(snapshotID)}` : "";
+        return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/rail-planning/journeys/${encodeURIComponent(journeyID)}${query}`);
+    }
 }
 // --- SSE streaming helper ---
 async function streamSSE(url, onEvent, signal) {

package/dist/src/client/http.js

@@ -14,6 +14,7 @@ export class HttpError extends Error {
     }
 }
 export class HttpClient {
+    localSimulation = false;
     static MAX_TRANSPORT_RETRIES = 2;
     baseURL;
     fetchImpl;
@@ -70,6 +71,7 @@ export class HttpClient {
                     ...(options.signal ? { signal: options.signal } : {}),
                 });
                 text = await response.text();
+                this.localSimulation = response.headers.get("X-ItPay-Environment") === "local_simulation";
             }
             catch (error) {
                 if (options.signal?.aborted)

package/dist/src/commands/aftercare.js

@@ -0,0 +1,12 @@
+import { serviceAdapter } from "../services/registry.js";
+import { CommandContractError } from "../services/shared/envelope.js";
+function adapter(identity) {
+    const capability = serviceAdapter(identity).aftercare;
+    if (!capability)
+        throw new CommandContractError("aftercare_unsupported", "Locked service does not support this aftercare operation", "使用原服务声明的售后入口，不套用其他业务规则。", []);
+    return capability;
+}
+export async function runAftercareList(backend, orderID) { const value = await backend.listRailAftercare(orderID); return adapter(value.execution_identity).directory(value, orderID); }
+export async function runAftercareGet(backend, id) { const value = await backend.getRailAftercare(id); return adapter(value.execution_identity).present(value); }
+export async function runAftercareCreate(backend, config, orderID, input) { const value = await backend.listRailAftercare(orderID); return adapter(value.execution_identity).create(backend, config, orderID, input); }
+export async function runAftercareRespond(backend, id, input, cancel = false) { const value = await backend.getRailAftercare(id); return adapter(value.execution_identity).respond(backend, id, input, cancel); }

package/dist/src/commands/buy.js

@@ -1,13 +1,4 @@
-// V3 `buy` flow:
-//   1. validate client context (host/target)
-//   2. create cart via POST /v1/carts
-//   3. create checkout via POST /v1/checkouts (consumes the cart)
-//   4. build a checkout_qr render plan + dispatch to host renderer
-//   5. [--pay] create payment intent → render payment QR → optionally SSE wait
-//   6. [--json] output JSON instead of terminal text
-//
-// The display token is passed to the renderer and persisted in the local cart
-// session so a restarted agent can resume the same checkout.
+import { buildCheckoutQRPlan } from "../render/checkout_plan.js";
 import { operationID } from "../state/config.js";
 import { validateContext } from "../state/client_context.js";
 import { dispatchRender } from "../render/index.js";
@@ -17,8 +8,7 @@ import { localizeCardURL, normalizeCardLocale } from "../render/locale.js";
 import { buildAgentChatHandoff } from "../render/markdown.js";
 import { formatMoney } from "../render/output.js";
 import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
-import { buildCheckoutHandoff, isLinkOnlyBrowserAgent, shouldPrepareLocalCheckoutImage } from "./checkout_handoff.js";
-import { qualifyItPayCommand } from "../state/agent_type.js";
+import { assertCheckoutPayable, buildCheckoutHandoff, shouldPrepareLocalCheckoutImage } from "./checkout_handoff.js";
 export async function runBuy(backend, config, options) {
     const err = validateContext(options.host, options.target);
     if (err) {
@@ -62,6 +52,15 @@ export async function runBuy(backend, config, options) {
         ...(options.contact ? { delivery_contact: options.contact } : {}),
     };
     const checkout = await backend.createCheckout(checkoutRequest, idempotencyKey);
+    const authoritative = checkout.display_token
+        ? await backend.getCheckoutPresentation(checkout.checkout.checkout_id, checkout.display_token)
+        : undefined;
+    assertCheckoutPayable(checkout, authoritative, cart.cart_id, latestLine?.service_execution_id);
+    const current = authoritative?.checkout ?? checkout.checkout;
+    // Only the returned checkout's items are authoritative for the handoff.
+    if (!authoritative)
+        throw new Error("checkout presentation unavailable");
+    cart = { ...cart, items: authoritative.items, amount_minor: current.amount_minor, currency: current.currency };
     options.cartSession.rememberCheckout({
         checkoutID: checkout.checkout.checkout_id,
         displayToken: checkout.display_token,
@@ -106,6 +105,7 @@ export async function runBuy(backend, config, options) {
     }
     // --- Build render plan (after payment if --pay) ---
     const planInput = {
+        localSimulation: backend.localSimulation,
         host: options.host,
         checkoutID,
         checkoutURL,
@@ -135,7 +135,7 @@ export async function runBuy(backend, config, options) {
         });
     }
     // --- Output ---
-    if (options.jsonOutput) {
+    if (options.jsonOutput || platformKeyForHost(options.host) === "plain_chat") {
         const envelope = buildBuyEnvelope({
             cart,
             checkoutID,
@@ -148,7 +148,7 @@ export async function runBuy(backend, config, options) {
             ...(options.agentType ? { agentType: options.agentType } : {}),
             ...(options.target ? { target: options.target } : {}),
         });
-        writeCommandEnvelope(envelope, { jsonOutput: true, ...(options.output ? { output: options.output } : {}) });
+        writeCommandEnvelope(envelope, { jsonOutput: Boolean(options.jsonOutput), ...(options.output ? { output: options.output } : {}), ...(options.agentType ? { agentType: options.agentType } : {}) });
         return {
             kind: "checkout_rendered",
             plan,
@@ -203,6 +203,7 @@ function buildBuyEnvelope(input) {
     const presentationHandoff = buildCheckoutHandoff({
         platform,
         url: input.plan.linkOnlyURL ?? input.checkoutURL,
+        mobileUrl: input.checkoutURL,
         amount,
         plan: input.plan,
         ...(input.agentType ? { agentType: input.agentType } : {}),
@@ -218,7 +219,7 @@ function buildBuyEnvelope(input) {
         result,
         handoff: presentationHandoff.handoff,
         instruction: presentationHandoff.instruction,
-        next: { command: input.plan.afterActionCommand ?? `itpay checkout --id ${input.checkoutID} --token ${input.displayToken} --json`, reason: "稍后查询同一笔 Checkout 状态" },
+        next: { command: input.plan.afterActionCommand ?? `itpay checkout --id ${input.checkoutID} --token ${input.displayToken} --json`, reason: "仅用户完成付款或要求查询时，读取同一笔Checkout权威状态" },
         recovery: [],
     };
 }
@@ -243,49 +244,6 @@ async function waitForPaymentSSE(backend, checkoutID, displayToken, timeoutSec)
         });
     });
 }
-// --- checkout QR plan ---
-export function buildCheckoutQRPlan(input) {
-    const summary = `Scan the QR or open ${input.checkoutURL} to start the human checkout flow.`;
-    const isPayment = input.paymentIntentID != null;
-    const afterCommand = qualifyItPayCommand(`itpay checkout --id ${input.checkoutID} --token ${input.displayToken}${input.locale === "en" ? " --locale en" : ""} --json`, input.agentType);
-    const platform = {
-        text: summary,
-        links: [
-            { label: "打开付款页面", url: input.checkoutURL },
-        ],
-        buttons: [
-            { label: "打开收银台", kind: "url", url: input.checkoutURL },
-            ...(input.checkoutID
-                ? [{ label: "查询 Checkout 状态", kind: "callback", intent: "check_checkout_status", ref: input.checkoutID }]
-                : []),
-        ],
-        blocks: [],
-        ...(input.qrPNGURL ? { media: [{ url: input.qrPNGURL, label: "Branded QR", mimeType: "image/png" }] } : {}),
-    };
-    const plan = {
-        kind: isPayment ? "payment_qr" : "checkout_qr",
-        host: input.host,
-        summary,
-        url: input.qrPayload,
-        ...(isLinkOnlyBrowserAgent(input.agentType, platformKeyForHost(input.host)) && input.cardURL ? { linkOnlyURL: input.cardURL } : {}),
-        preferredQRSources: [input.qrPNGURL ?? input.qrPayload],
-        checkoutID: input.checkoutID,
-        platform,
-        afterActionCommand: afterCommand,
-        afterActionLabel: "扫码或点击链接完成支付后，执行以下命令查询状态：",
-    };
-    if (input.orderItems)
-        plan.orderItems = input.orderItems;
-    if (input.orderCurrency)
-        plan.orderCurrency = input.orderCurrency;
-    if (input.paymentMethod)
-        plan.paymentMethod = input.paymentMethod;
-    if (input.paymentStatus)
-        plan.paymentStatus = input.paymentStatus;
-    if (input.paymentIntentID)
-        plan.paymentIntentID = input.paymentIntentID;
-    return plan;
-}
 function fallbackCardURL(baseURL, checkoutID, displayToken) {
     const root = baseURL.replace(/\/$/, "");
     return `${root}/v1/checkouts/${encodeURIComponent(checkoutID)}/card?display_token=${encodeURIComponent(displayToken)}`;
@@ -327,3 +285,4 @@ function absolutePublicURL(baseURL, value) {
         return value;
     }
 }
+export { buildCheckoutQRPlan } from "../render/checkout_plan.js";

package/dist/src/commands/cart.js

@@ -21,7 +21,7 @@ export function runCartAdd(session, options) {
             offer_id: item.offerID,
             quantity: item.quantity,
         },
-        instruction: "仅写入本地兼容草稿，未验证目录、价格或服务合同；不要把它当作 canonical Cart。",
+        instruction: "仅写入本地兼容草稿，未验证目录、价格或服务合同；不要把它当作 服务端购物车。",
         next: { command: "itpay cart show --local", reason: "检查本地草稿" },
         recovery: [],
     };
@@ -74,10 +74,10 @@ export async function runCartAddServer(options) {
         },
         instruction: serviceExecutionID
             ? "服务型项目已创建 Service Execution；先读取其当前步骤，不要直接进入普通 buy。"
-            : "普通项目已加入 canonical Cart；先检查购物车，再创建 Checkout。",
+            : "普通项目已加入 服务端购物车；先检查购物车，再创建 Checkout。",
         next: serviceExecutionID
             ? { command: `itpay services next ${serviceExecutionID} --json`, reason: "读取服务执行的当前步骤" }
-            : { command: "itpay cart next --json", reason: "检查 canonical Cart" },
+            : { command: "itpay cart next --json", reason: "检查 服务端购物车" },
         recovery: [],
     };
     writeCommandEnvelope(envelope, {
@@ -117,11 +117,13 @@ export async function runCartAddQuoteServer(options) {
         status: "quote_added",
         result: {
             cart_id: cart.cart_id,
+            service_quote_lock_id: options.serviceQuoteLockID,
+            service_execution_id: line.service_execution_id,
             item_count: cart.items.length,
             total: formatMoney(cart.amount_minor, cart.currency),
         },
         instruction: "付费服务报价已加入同一 Cart；每个项目仍保持独立 Execution 和交付。",
-        next: { command: `itpay buy --cart ${cart.cart_id} --json`, reason: "确认项目齐全后创建一次合并付款" },
+        next: { command: `itpay buy --cart ${cart.cart_id} --json`, reason: "仅已有购买授权且项目齐全时创建一次合并付款" },
         recovery: [{ command: "itpay cart show --json", reason: "检查当前合并 Cart" }],
     };
     writeCommandEnvelope(envelope, {
@@ -144,7 +146,7 @@ export function runCartRemove(session, options) {
             catalog_variant_id: options.catalogVariantID,
             offer_id: options.offerID,
         },
-        instruction: "本地兼容草稿已更新；这不代表任何 canonical Cart 或 Service Execution 已变更。",
+        instruction: "本地兼容草稿已更新；这不代表任何 服务端购物车 或 Service Execution 已变更。",
         next: { command: "itpay cart show --local --json", reason: "检查剩余本地草稿" },
         recovery: [],
     }, {
@@ -176,7 +178,7 @@ export async function runCartRemoveServer(backend, session, cartItemID, options
             cart_item_id: lineID,
             remaining_item_count: cart.items.length,
         },
-        instruction: "canonical Cart 已更新；被删除的最后一个 service-backed line 对应执行会由服务端一致性事务取消。",
+        instruction: "服务端购物车 已更新；被删除的最后一个 服务项目 对应执行会由服务端同时取消。",
         next: { command: "itpay cart next --json", reason: "检查剩余内容" },
         recovery: [],
     };
@@ -198,10 +200,10 @@ export function runCartShow(session, options = {}) {
         status: items.length > 0 ? "shown_local" : "local_empty",
         result: { currency: snap.currency, items },
         instruction: items.length > 0
-            ? "这是未验证的本地兼容草稿，只能用于明确的普通商品流程；不要把它当作 canonical Cart。"
+            ? "这是未验证的本地兼容草稿，只能用于明确的普通商品流程；不要把它当作 服务端购物车。"
             : "本地兼容草稿为空；从已发布目录重新选择项目。",
         next: items.length > 0
-            ? { command: "itpay buy --json", reason: "将普通本地草稿提交为 canonical Cart" }
+            ? { command: "itpay buy --json", reason: "将普通本地草稿提交为 服务端购物车" }
             : { command: "itpay catalog list --json", reason: "读取已发布目录" },
         recovery: [],
     };
@@ -215,7 +217,7 @@ export async function runCartShowServer(backend, session, options = {}) {
         writeCommandEnvelope({
             status: "cart_handle_missing",
             result: {},
-            instruction: "本地没有 canonical Cart 句柄；不要把本地草稿默认为服务端 Cart。",
+            instruction: "本地没有 服务端购物车 句柄；不要把本地草稿默认为服务端 Cart。",
             next: { command: "itpay catalog list --json", reason: "读取已发布目录" },
             recovery: [{ command: "itpay cart show --local --json", reason: "仅在明确需要时检查本地兼容草稿" }],
         }, {
@@ -241,7 +243,7 @@ export async function runCartShowServer(backend, session, options = {}) {
         },
         instruction: items.length > 0
             ? "使用 line 或 execution 句柄继续；不要使用内部 quote lock ID。"
-            : "canonical Cart 当前为空；从已发布目录选择项目。",
+            : "服务端购物车 当前为空；从已发布目录选择项目。",
         next: items.length > 0
             ? { command: "itpay cart next --json", reason: "取得当前首选动作" }
             : { command: "itpay catalog list --json", reason: "读取已发布目录" },
@@ -278,7 +280,7 @@ export async function runCartAbandonServer(backend, session, options = {}) {
         writeCommandEnvelope({
             status: "cart_handle_missing",
             result: {},
-            instruction: "本地没有 canonical Cart 句柄；未修改任何 Backend 或本地资源。",
+            instruction: "本地没有 服务端购物车 句柄；未修改任何 Backend 或本地资源。",
             next: { command: "itpay next --json", reason: "检查其他可恢复句柄" },
             recovery: [{ command: "itpay cart clear --local --json", reason: "仅在明确放弃本地草稿和句柄时执行" }],
         }, {
@@ -292,7 +294,7 @@ export async function runCartAbandonServer(backend, session, options = {}) {
     const envelope = {
         status: "abandoned",
         result: { cart_id: cart.cart_id, server_abandoned: true },
-        instruction: "canonical Cart 已放弃；Backend 已在同一事务中软删除 active lines，并取消其未付款 Service Execution。",
+        instruction: "服务端购物车 已放弃；服务端已清空有效项目，并取消关联的未付款服务执行。",
         next: { command: "itpay catalog list --json", reason: "仅在用户提出新需求时重新选择" },
         recovery: [],
     };
@@ -308,7 +310,7 @@ export async function runCartNext(backend, session, options = {}) {
         writeCartNextEnvelope({
             status: "cart_handle_missing",
             result: {},
-            instruction: "本地没有 canonical Cart 句柄；先恢复已有资源，不要创建重复 Cart。",
+            instruction: "本地没有 服务端购物车 句柄；先恢复已有资源，不要创建重复 Cart。",
             next: { command: "itpay next --json", reason: "检查其他可恢复句柄" },
             recovery: [{ command: "itpay services list --json", reason: "从服务端恢复当前设备的执行" }],
         }, options);
@@ -325,7 +327,7 @@ export async function runCartNext(backend, session, options = {}) {
                 cart_status: cart.status,
                 service_execution_id: unquotedServiceLine.service_execution_id,
             },
-            instruction: "该 Cart 包含 service-backed line；继续 Service Execution，不要从 Cart 猜 capability。",
+            instruction: "该 Cart 包含 服务项目；继续 Service Execution，不要从 Cart 猜 capability。",
             next: {
                 command: `itpay services next ${unquotedServiceLine.service_execution_id} --json`,
                 reason: "读取服务端最新执行状态",
@@ -355,7 +357,7 @@ export async function runCartNext(backend, session, options = {}) {
             instruction: cart.items.some((item) => item.service_quote_lock_id)
                 ? "服务报价已锁定输入和价格；确认项目齐全后使用同一 Cart 创建一次 Checkout。"
                 : "该 Cart 是普通购买流程；使用同一 Cart 创建 Checkout，不要重复添加商品。",
-            next: { command: `itpay buy --cart ${cart.cart_id} --json`, reason: "继续 canonical Cart 结算" },
+            next: { command: `itpay buy --cart ${cart.cart_id} --json`, reason: "仅已有购买授权时继续服务端购物车结算" },
             recovery: [],
         };
     }

package/dist/src/commands/catalog.js

@@ -1,7 +1,7 @@
 import { writeCommandEnvelope } from "./guidance.js";
 export async function runCatalogList(backend, options = {}) {
     const manifest = await backend.getCatalogManifest();
-    const services = manifest.manifest.items.map(summarizeService);
+    const services = manifest.manifest.items.map(item => summarizeService(item, options.locale ?? "zh-CN"));
     const firstServiceID = manifest.manifest.items.find((item) => item.service_id)?.service_id;
     const empty = services.length === 0;
     const jsonFlag = options.jsonOutput ? " --json" : "";
@@ -9,30 +9,40 @@ export async function runCatalogList(backend, options = {}) {
         status: empty ? "catalog_empty" : "listed",
         result: { catalog_version: manifest.version, services },
         instruction: empty
-            ? "当前没有已发布服务；稍后重试，不要猜测 service_id。"
-            : "向用户解释主服务、辅助步骤和价格；得到用户意图后再启动对应 service_id。",
-        next: empty
-            ? { command: `itpay catalog list${jsonFlag}`, reason: "稍后重新读取已发布目录" }
-            : {
-                command: `itpay services start ${services.length === 1 && firstServiceID ? firstServiceID : "<service_id>"}${jsonFlag}`,
-                reason: "启动用户选择的服务",
-            },
+            ? "当前没有已发布服务；本次目录读取结束，不猜测服务或自动重试。"
+            : options.locale === "en" ? "Explain the service, its operations and pricing; start only the declared operation matching the human request." : "向用户解释主服务、辅助步骤和价格；得到用户意图后再启动对应 service_id。",
+        next: services.length === 1 && firstServiceID
+            ? { command: `itpay services start ${firstServiceID}${jsonFlag}`, reason: "仅当当前服务符合用户请求时读取输入合同；不表示购买同意" }
+            : null,
         recovery: [],
     }, {
         ...options,
         plainResult: catalogPlainLines(manifest.version, services),
     });
 }
-function summarizeService(item) {
+function summarizeService(item, locale) {
+    const definition = item.service_definition;
+    if (definition) {
+        if (definition.schema_version !== "itpay.service-definition.v1")
+            return { service_id: item.service_id, title: item.title, description: "服务定义版本不受支持；升级CLI后读取，不猜操作。" };
+        return {
+            service_id: definition.service_id, title: definition.display_names[locale] ?? item.title,
+            entry: `itpay services start ${definition.service_id} --json`, definition_version: definition.definition_version,
+            ...(definition.guide ? { guide: `itpay docs show ${definition.guide.topic}` } : {}),
+            operations: definition.operations.map(op => ({ operation_id: op.id, title: op.display_names[locale], role: op.role, price: op.billing_mode === "dynamic" ? (locale === "en" ? (definition.adapter_key === "rail.v1" ? "Live quote; free queries do not mean free tickets" : "Live quote; confirm the locked amount") : (definition.adapter_key === "rail.v1" ? "实时报价；免费查询不等于免费车票" : "实时报价，以锁定报价为准")) : op.billing_mode === "free" ? (locale === "en" ? "Free query" : "免费查询") : typeof op.price_amount_minor === "number" && op.price_currency ? formatProductMoney(op.price_amount_minor, op.price_currency) : (locale === "en" ? "Fixed price missing; stop purchase preparation" : "固定价格事实缺失；停止准备购买"), requires_continuation: op.requires_continuation ?? false })),
+        };
+    }
     const flow = item.service_flow;
+    const offer = item.variants?.[0];
     return {
         service_id: item.service_id ?? null,
+        ...(item.service_id ? { entry: `itpay services start ${item.service_id} --json` } : {}),
         title: item.title,
         description: item.description ?? "",
         ...(flow ? {
             discovery: {
                 title: flow.discovery.title,
-                description: flow.discovery.description,
+                description: flow.discovery.description ?? "",
                 ...(flow.discovery.free_quota_limit !== undefined ? { free_quota: flow.discovery.free_quota_limit } : {}),
                 ...(flow.discovery.paid_continuation ? {
                     paid_price: formatProductMoney(flow.discovery.paid_continuation.amount_minor, flow.discovery.paid_continuation.currency),
@@ -40,9 +50,15 @@ function summarizeService(item) {
             },
             primary_offer: {
                 title: flow.primary_service.title,
-                description: flow.primary_service.description,
+                description: flow.primary_service.description ?? "",
                 price: formatProductMoney(flow.primary_service.amount_minor, flow.primary_service.currency),
             },
+        } : offer ? {
+            primary_offer: {
+                title: offer.title || item.title,
+                description: item.description ?? "",
+                price: formatProductMoney(offer.amount_minor, offer.currency),
+            },
         } : {}),
     };
 }
@@ -51,19 +67,28 @@ function catalogPlainLines(version, services) {
     for (const service of services) {
         lines.push(`service: ${String(service.title)}`);
         lines.push(`  service_id: ${String(service.service_id ?? "unavailable")}`);
+        if (service.entry)
+            lines.push(`  entry: ${String(service.entry)}`);
+        if (service.guide)
+            lines.push(`  guide: ${String(service.guide)}`);
         if (service.description)
             lines.push(`  description: ${String(service.description)}`);
+        if (Array.isArray(service.operations))
+            for (const op of service.operations)
+                lines.push(`  operation: ${String(op.operation_id)} — ${String(op.title)}; ${String(op.price)}`);
         const discovery = service.discovery;
         if (discovery) {
             const quota = discovery.free_quota !== undefined ? `; free_quota: ${String(discovery.free_quota)}` : "";
             const paid = discovery.paid_price ? `; paid_price: ${String(discovery.paid_price)}` : "";
             lines.push(`  discovery: ${String(discovery.title)}${quota}${paid}`);
-            lines.push(`    ${String(discovery.description)}`);
+            if (discovery.description)
+                lines.push(`    ${String(discovery.description)}`);
         }
         const primary = service.primary_offer;
         if (primary) {
             lines.push(`  primary_offer: ${String(primary.title)}; price: ${String(primary.price)}`);
-            lines.push(`    ${String(primary.description)}`);
+            if (primary.description)
+                lines.push(`    ${String(primary.description)}`);
         }
     }
     return lines;