@itpay/cli 2.1.40 → 2.1.41

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 use the existing `itpay sell` entry point.
+`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.
 
 ```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 sandbox runs may set `ITPAY_BACKEND_URL=https://sandbox.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 tests may set `ITPAY_BACKEND_URL=https://dev.itpay.ai`; every other Backend URL is rejected before network or local state access.
 
 ## Output Contract
 
@@ -54,7 +54,6 @@ 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` | 必须显式提供 |
 
@@ -68,7 +67,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 saved railway query pages or human-granted protected content.
+- `services read-result`: read one human-granted protected result.
 - `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.
@@ -91,12 +90,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`; sandbox uses `cart.sandbox.json` / `operations.sandbox.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`; dev uses `cart.dev.json` / `operations.dev.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 sandbox override; only the exact official URL `https://sandbox.itpay.ai` is accepted. Unset it for production.
+- `ITPAY_BACKEND_URL`: optional test override; only the exact official URL `https://dev.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`.
@@ -128,9 +127,3 @@ 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/dist/src/client/backend.js

@@ -5,19 +5,6 @@ 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");
     }
@@ -103,11 +90,6 @@ 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 } : {}) };
@@ -126,15 +108,6 @@ 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) });
     }
@@ -147,9 +120,8 @@ export class BackendClient {
     prepareServiceQuote(serviceExecutionID, input) {
         return this.http.post(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/quotes`, input, { replaySafe: true });
     }
-    getServiceExecution(serviceExecutionID, opts = {}) {
-        const query = opts.sinceSnapshot ? `?since_snapshot=${encodeURIComponent(opts.sinceSnapshot)}` : "";
-        return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}${query}`);
+    getServiceExecution(serviceExecutionID) {
+        return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}`);
     }
     listServiceExecutions(limit = 50) {
         return this.http.get(`/v1/service-executions?limit=${limit}`);
@@ -164,14 +136,6 @@ 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,7 +14,6 @@ export class HttpError extends Error {
     }
 }
 export class HttpClient {
-    localSimulation = false;
     static MAX_TRANSPORT_RETRIES = 2;
     baseURL;
     fetchImpl;
@@ -71,7 +70,6 @@ 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/buy.js

@@ -1,4 +1,13 @@
-import { buildCheckoutQRPlan } from "../render/checkout_plan.js";
+// 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 { operationID } from "../state/config.js";
 import { validateContext } from "../state/client_context.js";
 import { dispatchRender } from "../render/index.js";
@@ -8,7 +17,8 @@ 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 { assertCheckoutPayable, buildCheckoutHandoff, shouldPrepareLocalCheckoutImage } from "./checkout_handoff.js";
+import { buildCheckoutHandoff, isLinkOnlyBrowserAgent, shouldPrepareLocalCheckoutImage } from "./checkout_handoff.js";
+import { qualifyItPayCommand } from "../state/agent_type.js";
 export async function runBuy(backend, config, options) {
     const err = validateContext(options.host, options.target);
     if (err) {
@@ -52,15 +62,6 @@ 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,
@@ -105,7 +106,6 @@ 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 || platformKeyForHost(options.host) === "plain_chat") {
+    if (options.jsonOutput) {
         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: Boolean(options.jsonOutput), ...(options.output ? { output: options.output } : {}), ...(options.agentType ? { agentType: options.agentType } : {}) });
+        writeCommandEnvelope(envelope, { jsonOutput: true, ...(options.output ? { output: options.output } : {}) });
         return {
             kind: "checkout_rendered",
             plan,
@@ -203,7 +203,6 @@ 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 } : {}),
@@ -219,7 +218,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: [],
     };
 }
@@ -244,6 +243,49 @@ 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)}`;
@@ -285,4 +327,3 @@ 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: "仅写入本地兼容草稿，未验证目录、价格或服务合同；不要把它当作 服务端购物车。",
+        instruction: "仅写入本地兼容草稿，未验证目录、价格或服务合同；不要把它当作 canonical Cart。",
         next: { command: "itpay cart show --local", reason: "检查本地草稿" },
         recovery: [],
     };
@@ -74,10 +74,10 @@ export async function runCartAddServer(options) {
         },
         instruction: serviceExecutionID
             ? "服务型项目已创建 Service Execution；先读取其当前步骤，不要直接进入普通 buy。"
-            : "普通项目已加入 服务端购物车；先检查购物车，再创建 Checkout。",
+            : "普通项目已加入 canonical Cart；先检查购物车，再创建 Checkout。",
         next: serviceExecutionID
             ? { command: `itpay services next ${serviceExecutionID} --json`, reason: "读取服务执行的当前步骤" }
-            : { command: "itpay cart next --json", reason: "检查 服务端购物车" },
+            : { command: "itpay cart next --json", reason: "检查 canonical Cart" },
         recovery: [],
     };
     writeCommandEnvelope(envelope, {
@@ -117,13 +117,11 @@ 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, {
@@ -146,7 +144,7 @@ export function runCartRemove(session, options) {
             catalog_variant_id: options.catalogVariantID,
             offer_id: options.offerID,
         },
-        instruction: "本地兼容草稿已更新；这不代表任何 服务端购物车 或 Service Execution 已变更。",
+        instruction: "本地兼容草稿已更新；这不代表任何 canonical Cart 或 Service Execution 已变更。",
         next: { command: "itpay cart show --local --json", reason: "检查剩余本地草稿" },
         recovery: [],
     }, {
@@ -178,7 +176,7 @@ export async function runCartRemoveServer(backend, session, cartItemID, options
             cart_item_id: lineID,
             remaining_item_count: cart.items.length,
         },
-        instruction: "服务端购物车 已更新；被删除的最后一个 服务项目 对应执行会由服务端同时取消。",
+        instruction: "canonical Cart 已更新；被删除的最后一个 service-backed line 对应执行会由服务端一致性事务取消。",
         next: { command: "itpay cart next --json", reason: "检查剩余内容" },
         recovery: [],
     };
@@ -200,10 +198,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: "将普通本地草稿提交为 服务端购物车" }
+            ? { command: "itpay buy --json", reason: "将普通本地草稿提交为 canonical Cart" }
             : { command: "itpay catalog list --json", reason: "读取已发布目录" },
         recovery: [],
     };
@@ -217,7 +215,7 @@ export async function runCartShowServer(backend, session, options = {}) {
         writeCommandEnvelope({
             status: "cart_handle_missing",
             result: {},
-            instruction: "本地没有 服务端购物车 句柄；不要把本地草稿默认为服务端 Cart。",
+            instruction: "本地没有 canonical Cart 句柄；不要把本地草稿默认为服务端 Cart。",
             next: { command: "itpay catalog list --json", reason: "读取已发布目录" },
             recovery: [{ command: "itpay cart show --local --json", reason: "仅在明确需要时检查本地兼容草稿" }],
         }, {
@@ -243,7 +241,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: "读取已发布目录" },
@@ -280,7 +278,7 @@ export async function runCartAbandonServer(backend, session, options = {}) {
         writeCommandEnvelope({
             status: "cart_handle_missing",
             result: {},
-            instruction: "本地没有 服务端购物车 句柄；未修改任何 Backend 或本地资源。",
+            instruction: "本地没有 canonical Cart 句柄；未修改任何 Backend 或本地资源。",
             next: { command: "itpay next --json", reason: "检查其他可恢复句柄" },
             recovery: [{ command: "itpay cart clear --local --json", reason: "仅在明确放弃本地草稿和句柄时执行" }],
         }, {
@@ -294,7 +292,7 @@ export async function runCartAbandonServer(backend, session, options = {}) {
     const envelope = {
         status: "abandoned",
         result: { cart_id: cart.cart_id, server_abandoned: true },
-        instruction: "服务端购物车 已放弃；服务端已清空有效项目，并取消关联的未付款服务执行。",
+        instruction: "canonical Cart 已放弃；Backend 已在同一事务中软删除 active lines，并取消其未付款 Service Execution。",
         next: { command: "itpay catalog list --json", reason: "仅在用户提出新需求时重新选择" },
         recovery: [],
     };
@@ -310,7 +308,7 @@ export async function runCartNext(backend, session, options = {}) {
         writeCartNextEnvelope({
             status: "cart_handle_missing",
             result: {},
-            instruction: "本地没有 服务端购物车 句柄；先恢复已有资源，不要创建重复 Cart。",
+            instruction: "本地没有 canonical Cart 句柄；先恢复已有资源，不要创建重复 Cart。",
             next: { command: "itpay next --json", reason: "检查其他可恢复句柄" },
             recovery: [{ command: "itpay services list --json", reason: "从服务端恢复当前设备的执行" }],
         }, options);
@@ -327,7 +325,7 @@ export async function runCartNext(backend, session, options = {}) {
                 cart_status: cart.status,
                 service_execution_id: unquotedServiceLine.service_execution_id,
             },
-            instruction: "该 Cart 包含 服务项目；继续 Service Execution，不要从 Cart 猜 capability。",
+            instruction: "该 Cart 包含 service-backed line；继续 Service Execution，不要从 Cart 猜 capability。",
             next: {
                 command: `itpay services next ${unquotedServiceLine.service_execution_id} --json`,
                 reason: "读取服务端最新执行状态",
@@ -357,7 +355,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: "仅已有购买授权时继续服务端购物车结算" },
+            next: { command: `itpay buy --cart ${cart.cart_id} --json`, reason: "继续 canonical Cart 结算" },
             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(item => summarizeService(item, options.locale ?? "zh-CN"));
+    const services = manifest.manifest.items.map(summarizeService);
     const firstServiceID = manifest.manifest.items.find((item) => item.service_id)?.service_id;
     const empty = services.length === 0;
     const jsonFlag = options.jsonOutput ? " --json" : "";
@@ -9,40 +9,30 @@ export async function runCatalogList(backend, options = {}) {
         status: empty ? "catalog_empty" : "listed",
         result: { catalog_version: manifest.version, services },
         instruction: empty
-            ? "当前没有已发布服务；本次目录读取结束，不猜测服务或自动重试。"
-            : 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,
+            ? "当前没有已发布服务；稍后重试，不要猜测 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: "启动用户选择的服务",
+            },
         recovery: [],
     }, {
         ...options,
         plainResult: catalogPlainLines(manifest.version, services),
     });
 }
-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 })),
-        };
-    }
+function summarizeService(item) {
     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),
@@ -50,15 +40,9 @@ function summarizeService(item, locale) {
             },
             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),
-            },
         } : {}),
     };
 }
@@ -67,28 +51,19 @@ 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}`);
-            if (discovery.description)
-                lines.push(`    ${String(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)}`);
-            if (primary.description)
-                lines.push(`    ${String(primary.description)}`);
+            lines.push(`    ${String(primary.description)}`);
         }
     }
     return lines;