@itpay/cli 2.1.5 → 2.1.6

package/dist/src/commands/services.js

@@ -12,6 +12,65 @@ import { renderTerminalQR } from "../render/qr.js";
 import { buildCheckoutQRPlan } from "./buy.js";
 import { appendFeedbackPostmortemInstruction, CommandContractError, isTerminalServiceExecutionStatus, writeCommandEnvelope, } from "./guidance.js";
 const serviceActionStatuses = new Set(["pending", "approved", "rejected", "expired", "cancelled"]);
+const RAIL_SERVICE_GUIDANCE = {
+    "itpay-rail-exact": {
+        when_to_use: "出发和到达都是明确的火车站名时使用本服务（直达查询，最快）。只有城市、模糊位置或想要方案推荐时改用 itpay-rail-smart。",
+        input_fields: [
+            { name: "origin", required: true, description: "出发火车站名（如'古镇'），不能是城市或地址", example: "古镇" },
+            { name: "destination", required: true, description: "到达火车站名（如'广州南'）", example: "广州南" },
+            { name: "travel_date", required: true, description: "出行日期 YYYY-MM-DD；字段名必须是 travel_date，'date' 等别名无效", example: "2026-09-19" },
+        ],
+        input_example: { origin: "古镇", destination: "广州南", travel_date: "2026-09-19" },
+        notes: [
+            "本服务只接受这三个字段，多传字段会被供应商拒绝",
+            "站名不确定就改用 itpay-rail-smart 先解析位置，不要在两个服务之间反复试错",
+        ],
+    },
+    "itpay-rail-smart": {
+        when_to_use: "只有城市名、模糊位置或需要中转规划与方案推荐时使用本服务；平台负责把位置解析到车站。",
+        input_fields: [
+            { name: "origin", required: true, description: "出发地：已知最完整的位置名或区域（城市/区县/地址均可）", example: "中山古镇" },
+            { name: "destination", required: true, description: "目的地：与 origin 同样的位置规则", example: "广州南" },
+            { name: "travel_date", required: true, description: "出行日期 YYYY-MM-DD；字段名必须是 travel_date", example: "2026-09-19" },
+        ],
+        optional_fields: [
+            { name: "origin_city", description: "出发地城市提示，辅助位置解析" },
+            { name: "destination_city", description: "目的地城市提示" },
+            { name: "origin_location", description: "已知坐标对象（高德 GCJ-02）" },
+            { name: "destination_location", description: "目的地坐标对象" },
+            { name: "depart_after", description: "不早于该时间出发" },
+            { name: "arrive_before", description: "不晚于该时间到达" },
+            { name: "priority", enum: "balanced|fastest|cheapest|safest|flexible", description: "方案偏好" },
+            { name: "max_transfers", description: "允许中转次数，0-2" },
+        ],
+        input_example: { origin: "中山古镇", destination: "广州南", travel_date: "2026-09-19", priority: "fastest" },
+        notes: [
+            "位置有歧义时会进入位置确认步骤，请用户选定后继续同一执行",
+            "推荐结果含每趟车的席别与余票；购票在后续受保护流程完成",
+        ],
+    },
+};
+function railServiceGuidance(serviceID) {
+    return RAIL_SERVICE_GUIDANCE[serviceID];
+}
+const WORKFLOW_STEP_GUIDANCE = {
+    input: { meaning: "输入校验", hint: "对照服务声明的输入契约补齐字段后重新发起" },
+    quota: { meaning: "额度检查", hint: "免费额度或限流未通过；登录或稍后重试" },
+    geo: { meaning: "位置解析", hint: "检查 origin/destination 是否为真实地名；可附 origin_city 或坐标对象提示" },
+    search: { meaning: "供应商车次检索", hint: "最常见是字段名错误（必须是 travel_date）或站名不存在；按 itpay docs show rail-booking 核对输入" },
+    catalog: { meaning: "可行车次计算", hint: "位置已解析但无可行车次；换日期或换站点重试" },
+    recommend: { meaning: "方案推荐", hint: "候选集无法产出推荐；放宽条件或换日期重试" },
+    delivery: { meaning: "交付", hint: "结果组装失败；稍后重试或联系运营" },
+};
+function failedWorkflowStep(steps) {
+    if (!steps)
+        return undefined;
+    for (const [step, status] of Object.entries(steps)) {
+        if (status === "failure" && step !== "failure")
+            return step;
+    }
+    return undefined;
+}
 export async function runServicesStart(backend, serviceID, options = {}) {
     const host = options.host ?? "terminal";
     const response = await backend.startServiceExecution({
@@ -23,7 +82,8 @@ export async function runServicesStart(backend, serviceID, options = {}) {
         },
     });
     if (response.workflow_entry) {
-        writeCommandEnvelope({ status: "input_required", result: { service_execution_id: response.execution.service_execution_id, service_id: serviceID, input_schema: response.workflow_entry.input_schema }, instruction: "根据服务声明填写输入，然后继续同一服务执行。", next: { command: `itpay services run ${serviceID} --execution ${response.execution.service_execution_id} --input-json <file> --json`, reason: "提交买家输入" }, recovery: [] }, { ...options });
+        const guidance = railServiceGuidance(serviceID);
+        writeCommandEnvelope({ status: "input_required", result: { service_execution_id: response.execution.service_execution_id, service_id: serviceID, input_schema: response.workflow_entry.input_schema, ...(guidance ? { guidance } : {}) }, instruction: guidance ? "按 result.guidance 逐项填写输入（when_to_use 说明本服务适用场景、input_fields 是必填契约、input_example 可直接照抄），然后继续同一服务执行。不要臆造字段名。" : "根据服务声明填写输入，然后继续同一服务执行。", next: { command: `itpay services run ${serviceID} --execution ${response.execution.service_execution_id} --input-json <file> --json`, reason: "提交买家输入" }, recovery: [] }, { ...options });
         return;
     }
     const capability = response.capabilities.find((item) => item.phase === response.execution.phase && !item.requires_payment);
@@ -950,6 +1010,21 @@ function servicesNextEnvelope(model) {
             command = `itpay services checkout ${id} --json`;
         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 failedStepGuidance = failedStep ? WORKFLOW_STEP_GUIDANCE[failedStep] : undefined;
+        const failedInvocation = recovery
+            ? [...model.provider_invocations].reverse().find((item) => typeof item.status === "string" && item.status.startsWith("failed"))
+            : undefined;
+        const errorDetail = typeof failedInvocation?.error_message === "string" && failedInvocation.error_message ? failedInvocation.error_message : undefined;
+        const providerErrorCode = typeof failedInvocation?.error_code === "string" && failedInvocation.error_code ? failedInvocation.error_code : undefined;
+        const failedInstruction = recovery
+            ? failedStepGuidance
+                ? `执行在「${failedStepGuidance.meaning}」步失败：${failedStepGuidance.hint}${errorDetail ? `。供应商返回：${errorDetail}` : ""}。本执行已终止不能续用；修正后用同一服务新建执行重试，不要盲目重放。`
+                : state === "failed"
+                    ? `执行已失败${failedStep ? `（失败步骤：${failedStep}）` : ""}且不可续用；修正输入后用同一服务新建执行重试。`
+                    : "执行未完成，请按步骤错误处理；不要重建执行或重复调用。"
+            : undefined;
         return {
             status: state,
             result: {
@@ -957,14 +1032,25 @@ function servicesNextEnvelope(model) {
                 service_id: execution.service_id,
                 workflow: model.workflow,
                 ...(state === "input_required" ? { input_schema: model.workflow_entry.input_schema } : {}),
+                ...(guidance && state === "input_required" ? { guidance } : {}),
+                ...(failedStep ? { failed_step: failedStep, ...(failedStepGuidance ? { failed_step_meaning: failedStepGuidance.meaning } : {}) } : {}),
+                ...(providerErrorCode ? { provider_error_code: providerErrorCode } : {}),
+                ...(errorDetail ? { error_detail: errorDetail } : {}),
+                ...(recovery ? { retryable: state === "failed" } : {}),
             },
-            instruction: recovery
-                ? "执行未完成，请按步骤错误处理；不要重建执行或重复调用。"
-                : state === "payment"
+            instruction: failedInstruction
+                ?? (state === "payment"
                     ? "服务已到付款步骤，使用现有 Checkout 完成扫码付款。"
-                    : "继续读取同一执行；缺少输入时按服务声明补齐。",
+                    : guidance
+                        ? "按 result.guidance 的字段契约填写输入后继续同一服务执行；不要臆造字段名。"
+                        : "继续读取同一执行；缺少输入时按服务声明补齐。"),
             next: recovery ? null : { command, reason: "继续当前流程" },
-            recovery: [],
+            recovery: recovery && state === "failed"
+                ? [
+                    { command: `itpay services start ${execution.service_id} --json`, reason: "修正输入后重新发起（本执行已终止不能续用）" },
+                    ...(guidance ? [{ command: "itpay docs show rail-booking --json", reason: "查看本服务输入字段契约与示例" }] : []),
+                ]
+                : [],
         };
     }
     const terminalEnvelope = terminalExecutionEnvelope(model);

package/dist/src/state/config.js

@@ -15,7 +15,7 @@ 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.5";
+export const CLI_VERSION = "2.1.6";
 export const API_CONTRACT_REVISION = "sha256:42659989d533d5a43c4ab92eb2455bcbbc6456e799fa4c2b6587de77f06b95f7";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";

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

@@ -0,0 +1,80 @@
+{
+  "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.",
+  "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.",
+  "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."
+  ],
+  "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.",
+    "svc_qizhidao_company_lookup": "Not a railway service; do not mix intents."
+  },
+  "input_contract": {
+    "itpay-rail-exact": {
+      "required": {
+        "origin": "Departure railway station name only, e.g. 古镇. Not a city or an address.",
+        "destination": "Arrival railway station name only, e.g. 广州南.",
+        "travel_date": "Travel date in YYYY-MM-DD. The field name must be exactly travel_date; aliases like date are rejected."
+      },
+      "optional": "None. additionalProperties is false — extra fields are rejected by the provider.",
+      "example": {"origin": "古镇", "destination": "广州南", "travel_date": "2026-09-19"}
+    },
+    "itpay-rail-smart": {
+      "required": {
+        "origin": "Fullest known departure location: city, district, area, or address is all acceptable.",
+        "destination": "Fullest known arrival location, same rule as origin.",
+        "travel_date": "Travel date in YYYY-MM-DD. The field name must be exactly travel_date."
+      },
+      "optional": {
+        "origin_city": "Departure city hint that helps location resolution.",
+        "destination_city": "Arrival city hint.",
+        "origin_location": "Known coordinate object (AMap GCJ-02).",
+        "destination_location": "Destination coordinate object.",
+        "depart_after": "Do not depart before this time.",
+        "arrive_before": "Do not arrive after this time.",
+        "priority": "One of balanced | fastest | cheapest | safest | flexible.",
+        "max_transfers": "Integer 0-2, allowed transfer count."
+      },
+      "example": {"origin": "中山古镇", "destination": "广州南", "travel_date": "2026-09-19", "priority": "fastest"}
+    }
+  },
+  "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.",
+    "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."
+  ],
+  "failure_handling": {
+    "failed_step": "The CLI reports failed_step and failed_step_meaning in the result when a workflow fails.",
+    "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.",
+    "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": {
+    "meaning": "A buyer's seat-letter preference may be planned per leg before payment. The plan is submitted to the supplier when encodable; unsupported combinations fall back to automatic assignment.",
+    "letters": "Evidence-backed letters only: O=ABCDF (second class), M=ACDF (first class), 9=ACF (business class). Other layouts auto-assign.",
+    "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.",
+    "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.",
+    "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"]
+  },
+  "search_terms": ["rail", "railway", "train", "ticket", "火车", "火车票", "高铁", "车票", "车次", "seat", "booking", "rail-booking"]
+}

package/package.json

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