@itpay/cli 2.1.41 → 2.1.44

package/dist/src/sell/mcp.js

@@ -0,0 +1,49 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { SELL_GUIDE, SELL_OPERATIONS, sellRequest } from './contract.js';
+import { LOCAL_ACTIONS, localAction } from './local.js';
+import { newBackendClient, loadConfig } from '../state/config.js';
+import { syncProject } from './sync.js';
+import { preview } from './preview.js';
+export async function serveSellMCP(directory) {
+    const server = new McpServer({ name: 'itpay-sell-local', version: SELL_GUIDE.version }, { instructions: 'Use itpay_seller_guide first. Local tests call Provider APIs and may incur cost; disclose side effects and obtain user approval. Never pass secret values in tool arguments. This server uses its configured project directory.' });
+    server.tool('itpay_seller_guide', 'Read the publishing guide and constraints', {}, async () => ({ content: [{ type: 'text', text: JSON.stringify({ ...SELL_GUIDE, operations: SELL_OPERATIONS }) }] }));
+    for (const action of LOCAL_ACTIONS) {
+        server.tool('itpay_seller_local_' + action.replaceAll(' ', '_').replaceAll('-', '_'), `Local ${action}. Paths are user-provided files; never scan for credentials. Confirm only after explicit user approval.`, { merchant_id: z.string().optional(), environment: z.string().optional(), service_id: z.string().optional(), url: z.string().url().optional(), file: z.string().optional(), name: z.string().optional(), provider_key: z.string().optional(), profile: z.string().optional(), version: z.string().optional(), run: z.string().optional(), confirmed: z.boolean().default(false) }, async (args) => {
+            try {
+                const result = await localAction(action, directory, { ...args, merchantId: args.merchant_id, providerKey: args.provider_key, serviceId: args.service_id, confirm: args.confirmed });
+                return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+            }
+            catch (error) {
+                return { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : 'Local action failed' }] };
+            }
+        });
+    }
+    server.tool('itpay_seller_sync', 'Upload or download the configured project after explicit user confirmation. Never pass credential values.', { action: z.enum(['push', 'pull']), merchant_id: z.string(), draft_id: z.string().optional(), bindings_file: z.string().optional(), confirmed: z.boolean().default(false) }, async (args) => {
+        try {
+            const result = await syncProject(args.action, directory, { merchantId: args.merchant_id, draftId: args.draft_id, bindings: args.bindings_file, confirm: args.confirmed });
+            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : 'Sync failed' }] };
+        }
+    });
+    let display;
+    server.tool('itpay_seller_preview', 'Open the existing Builder for this local workflow; user can then confirm through the local workflow tool.', {}, async () => { display ??= await preview(directory); return { content: [{ type: 'text', text: JSON.stringify({ url: display.url }) }] }; });
+    for (const operation of SELL_OPERATIONS) {
+        server.tool('itpay_seller_platform_' + operation.command.replaceAll(' ', '_').replaceAll('-', '_'), `${operation.description}. Input contract: ${JSON.stringify(operation.fields)}. Optional fields: ${JSON.stringify(operation.optional ?? [])}.`, { merchant_id: z.string().optional(), draft_id: z.string().optional(), library_api_id: z.string().optional(), intake_id: z.string().optional(), version_id: z.string().optional(), run_id: z.string().optional(), submission_id: z.string().optional(), input: z.record(z.unknown()).default({}), confirmed: z.boolean().default(false) }, async (args) => {
+            try {
+                if (operation.confirmation && !args.confirmed)
+                    throw new Error('Explicit user confirmation required');
+                const result = await newBackendClient(loadConfig()).sellRequest(sellRequest(operation, args, args.input));
+                return { content: [{ type: 'text', text: JSON.stringify(result ?? {}) }] };
+            }
+            catch (error) {
+                return { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : 'Platform action failed' }] };
+            }
+        });
+    }
+    process.stdin.on('end', () => display?.close());
+    await server.connect(new StdioServerTransport());
+}

package/dist/src/sell/preview.js

@@ -0,0 +1,70 @@
+import { createServer } from 'node:http';
+import { randomBytes, createHash } from 'node:crypto';
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { resolve, extname } from 'node:path';
+import { project } from './local.js';
+export async function preview(directory) {
+    const packaged = fileURLToPath(new URL('../../../assets/sell-preview/', import.meta.url));
+    const assets = existsSync(packaged) ? packaged : fileURLToPath(new URL('../../assets/sell-preview/', import.meta.url));
+    if (!existsSync(resolve(assets, 'index.html')))
+        throw new Error('CLI preview assets are missing; install the complete CLI package');
+    const token = randomBytes(24).toString('hex');
+    const server = createServer((req, res) => {
+        res.setHeader('Cache-Control', 'no-store');
+        res.setHeader('Referrer-Policy', 'no-referrer');
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        if (req.method !== 'GET' || !req.url?.startsWith('/' + token + '/')) {
+            res.writeHead(404).end();
+            return;
+        }
+        try {
+            const path = req.url.slice(token.length + 2).split('?')[0] ?? '';
+            if (path === 'document') {
+                const p = project(directory);
+                const versions = JSON.parse(readFileSync(resolve(p.state, 'versions.json'), 'utf8'));
+                const version = versions.versions.find((v) => v.version_id === versions.selected);
+                res.setHeader('Content-Type', 'application/json');
+                const actualHash = 'sha256:' + createHash('sha256').update(p.yaml).digest('hex');
+                let run;
+                const marker = resolve(p.state, 'last-run.json');
+                if (existsSync(marker)) {
+                    const id = JSON.parse(readFileSync(marker, 'utf8')).run_id;
+                    if (typeof id === 'string' && /^[A-Za-z0-9_-]+$/.test(id) && existsSync(resolve(p.state, 'runs', id, 'meta.json'))) {
+                        const dir = resolve(p.state, 'runs', id), meta = JSON.parse(readFileSync(resolve(dir, 'meta.json'), 'utf8'));
+                        const traces = existsSync(resolve(dir, 'nodes.json')) ? JSON.parse(readFileSync(resolve(dir, 'nodes.json'), 'utf8')) : [];
+                        const report = existsSync(resolve(dir, 'report.json')) ? JSON.parse(readFileSync(resolve(dir, 'report.json'), 'utf8')).report : undefined;
+                        const configHash = 'sha256:' + createHash('sha256').update(JSON.stringify(p.config)).digest('hex');
+                        const stale = meta.hash !== actualHash || meta.config_hash !== configHash;
+                        const fixtures = p.config.fixtures ?? [];
+                        run = { status: stale ? 'stale' : report?.status ?? 'running', issues: report?.issues ?? [], validation: { fixture_runs: fixtures.map((f) => ({ ...f, nodes: traces.filter((t) => t.record_type === 'node' && t.fixture_id === f.fixture_id) })), api_recognitions: [], side_effect_operations: [] } };
+                    }
+                }
+                res.end(JSON.stringify({ document: p.yaml, version: version?.hash === actualHash ? version.name : 'Unsaved', hash: actualHash, pricing: p.config.pricing, run }));
+                return;
+            }
+            const file = resolve(assets, path || 'index.html');
+            if (!file.startsWith(resolve(assets) + '/')) {
+                res.writeHead(404).end();
+                return;
+            }
+            const types = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript', '.css': 'text/css', '.svg': 'image/svg+xml', '.woff2': 'font/woff2' };
+            res.setHeader('Content-Type', types[extname(file)] ?? 'application/octet-stream');
+            res.end(readFileSync(file));
+        }
+        catch {
+            res.writeHead(404).end();
+        }
+    });
+    return new Promise((done, fail) => {
+        server.on('error', fail);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (!address || typeof address === 'string') {
+                fail(new Error('Preview address unavailable'));
+                return;
+            }
+            done({ url: `http://127.0.0.1:${address.port}/${token}/`, close: () => server.close() });
+        });
+    });
+}

package/dist/src/sell/sync.js

@@ -0,0 +1,145 @@
+import { HttpError } from "../client/http.js";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { newBackendClient, loadConfig } from '../state/config.js';
+import { companion, project, localDependencies } from './local.js';
+const encode = encodeURIComponent;
+const hash = (value) => 'sha256:' + createHash('sha256').update(value).digest('hex');
+function read(path) { return JSON.parse(readFileSync(path, 'utf8')); }
+function save(path, value) { writeFileSync(path, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 }); }
+function platformWorkflow(draft) {
+    const document = draft.arazzo?.arazzo_document;
+    if (typeof document !== 'string' || !document.trim())
+        throw new Error('Platform response is missing the workflow document');
+    return document;
+}
+export async function syncProject(action, directory, options) {
+    const p = project(directory), cloudPath = join(p.state, 'cloud.json');
+    let cloud = existsSync(cloudPath) ? read(cloudPath) : {};
+    const merchant = options.merchantId ?? cloud.merchant_id ?? p.config.merchant_id;
+    if (!merchant)
+        throw new Error('--merchant-id is required');
+    if (cloud.merchant_id && cloud.merchant_id !== merchant)
+        throw new Error('Project is bound to a different merchant');
+    const api = newBackendClient(loadConfig()), org = '/v1/seller/organizations/' + encode(merchant);
+    const call = async (method, path, body) => await api.sellRequest({ method, path, ...(body !== undefined ? { body } : {}) });
+    if (action === 'pull') {
+        const draftID = options.draftId ?? cloud.draft_id;
+        if (!draftID)
+            throw new Error('--draft-id is required');
+        if (!options.confirm)
+            throw new Error('Pull replaces local workflow/settings; inspect changes and confirm first');
+        const bundle = await call('GET', `${org}/service-drafts/${encode(draftID)}/bundle`);
+        const backup = join(p.state, 'backups', String(Date.now()));
+        mkdirSync(backup, { recursive: true, mode: 0o700 });
+        writeFileSync(join(backup, 'workflow.yaml'), p.yaml);
+        save(join(backup, 'service.json'), p.config);
+        const draft = bundle.draft;
+        writeFileSync(join(p.root, 'workflow.yaml'), platformWorkflow(draft));
+        save(join(p.root, 'service.json'), { ...p.config, service_id: draft.service_id, public_name: draft.public_name, pricing: draft.pricing, policy: draft.policy, fixtures: bundle.fixtures.fixtures });
+        save(join(p.state, 'platform-dependencies.json'), bundle.dependencies);
+        cloud = { merchant_id: merchant, draft_id: draftID, revision: draft.semantic_revision, hash: draft.semantic_hash };
+        save(cloudPath, cloud);
+        return { cloud, backup, next: 'Save a new local version. Platform credentials were not downloaded.' };
+    }
+    const versions = read(join(p.state, 'versions.json'));
+    const version = versions.versions.find((v) => v.version_id === versions.selected);
+    const confirmation = existsSync(join(p.state, 'confirmation.json')) ? read(join(p.state, 'confirmation.json')) : {};
+    if (!version || version.hash !== hash(p.yaml) || version.config_hash !== hash(JSON.stringify(p.config)) || confirmation.version_id !== version.version_id || confirmation.hash !== version.hash || confirmation.config_hash !== version.config_hash)
+        throw new Error('Save and confirm the exact current version before uploading');
+    const validation = (await companion({ action: 'validate', dependencies: localDependencies(p.state), document: p.yaml, pricing: p.config.pricing, policy: p.config.policy })).find(event => event.type === 'validation')?.value;
+    if (!validation?.result?.valid)
+        throw new Error('Workflow does not pass validation');
+    if (!options.confirm)
+        return { local_version: version, cloud, pricing: p.config.pricing, instruction: 'Review the service package and platform API calls, then confirm upload. Platform verification is a separate explicit action.' };
+    if (!cloud.draft_id) {
+        const drafts = await call('GET', `${org}/service-drafts`);
+        const existing = drafts.drafts?.find((d) => d.service_id === p.config.service_id);
+        if (existing)
+            throw new Error('Service ID already exists. Pull that draft explicitly before updating it.');
+        const draft = await call('POST', `${org}/service-drafts`, { service_id: p.config.service_id, public_name: p.config.public_name });
+        cloud = { merchant_id: merchant, draft_id: draft.draft_id, revision: draft.semantic_revision, operation_bindings: {} };
+        save(cloudPath, cloud);
+    }
+    const base = `${org}/service-drafts/${encode(cloud.draft_id)}`;
+    let current = await call('GET', base + '/workflow');
+    if (current.semantic_revision !== cloud.revision)
+        throw new Error('Remote draft changed; pull and review before retrying');
+    if (cloud.local_version_id === version.version_id && cloud.hash === current.semantic_hash && cloud.version_id) {
+        const saved = await call('GET', base + '/workflow/versions');
+        if (saved.versions.some((item) => item.version_id === cloud.version_id)) {
+            const fixtureState = await call('GET', base + '/fixtures');
+            if (fixtureState.revision !== cloud.fixture_revision)
+                throw new Error('Remote test inputs changed; pull and review before retrying');
+            return { cloud, already_uploaded: true, next: 'Read the platform Guide and verify the saved version' };
+        }
+    }
+    const sources = join(p.state, 'sources');
+    cloud.operation_bindings ??= {};
+    if (existsSync(sources))
+        for (const file of readdirSync(sources)) {
+            const source = read(join(sources, file));
+            const imported = await call('POST', `${org}/api-intakes`, { provider_key: source.provider_key, document: source.original, media_type: 'application/yaml' });
+            for (const local of source.operations) {
+                const remote = imported.operations.find((operation) => operation.operation_key === local.operation_key && operation.method === local.method && operation.path === local.path);
+                if (!remote)
+                    throw new Error('Platform import differs from the local API contract');
+                if (remote.operation_hash !== local.operation_hash)
+                    throw new Error('Platform API contract changed; download and review the imported contract');
+                cloud.operation_bindings[local.provider_operation_version_id] = remote.provider_operation_version_id;
+            }
+            save(cloudPath, cloud);
+        }
+    const credentials = options.bindings ? read(resolve(options.bindings)) : {};
+    const document = validation.document;
+    for (const workflow of document.workflows)
+        for (const step of workflow.steps) {
+            const meta = step['x-itpay-operation'];
+            if (meta?.type === 'api_call') {
+                meta.providerOperationVersionId = cloud.operation_bindings[meta.providerOperationVersionId] ?? meta.providerOperationVersionId;
+                if (credentials[meta.credentialProfileId])
+                    meta.credentialProfileId = credentials[meta.credentialProfileId];
+            }
+        }
+    // Each durable boundary is recorded. On an ambiguous write, pull explicitly;
+    // never retry a guessed revision or overwrite another editor's changes.
+    current = await call('PUT', base + '/workflow', { expected_revision: cloud.revision, public_name: p.config.public_name, arazzo: document });
+    cloud.revision = current.semantic_revision;
+    save(cloudPath, cloud);
+    current = await call('PUT', base + '/pricing', { expected_revision: cloud.revision, pricing: p.config.pricing, policy: p.config.policy });
+    cloud.revision = current.semantic_revision;
+    save(cloudPath, cloud);
+    let fixtures;
+    try {
+        fixtures = await call('GET', base + '/fixtures');
+    }
+    catch (error) {
+        if (error instanceof HttpError && error.status === 404)
+            fixtures = { revision: 0 };
+        else
+            throw error;
+    }
+    const savedFixtures = await call('PUT', base + '/fixtures', { expected_revision: fixtures.revision, fixtures: p.config.fixtures });
+    const existingVersions = await call('GET', base + '/workflow/versions');
+    const saved = existingVersions.versions.find((item) => item.name === version.name && item.arazzo_document === platformWorkflow(current)) ?? await call('POST', base + '/workflow/versions', { name: version.name, source: 'current', expected_revision: cloud.revision, arazzo_document: platformWorkflow(current) });
+    cloud.version_id = saved.version_id;
+    cloud.fixture_revision = savedFixtures.revision;
+    cloud.local_version_id = version.version_id;
+    cloud.hash = current.semantic_hash;
+    save(cloudPath, cloud);
+    await call('POST', base + '/workflow/validate', {});
+    return { cloud, platform_verified: false, next: { command: 'itpay sell verify', input: { workflow_version_id: cloud.version_id, expected_semantic_revision: cloud.revision, expected_fixture_revision: cloud.fixture_revision } }, instruction: 'Review and confirm platform verification before any real API calls. Local test success is not platform evidence.' };
+}
+export function registerSync(sell) {
+    for (const action of ['push', 'pull'])
+        sell.command(action).option('--project <directory>', 'Project directory', '.').option('--merchant-id <id>').option('--draft-id <id>').option('--bindings <file>', 'Local profile ID to platform credential profile ID map').option('--confirm').option('--json').action(async (options) => {
+            try {
+                process.stdout.write(JSON.stringify({ status: 'ok', result: await syncProject(action, options.project, options) }, null, 2) + '\n');
+            }
+            catch (error) {
+                process.exitCode = 1;
+                process.stdout.write(JSON.stringify({ status: 'error', message: error instanceof Error ? error.message : 'Sync failed' }) + '\n');
+            }
+        });
+}

package/dist/src/services/adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/src/services/presentation.js

@@ -0,0 +1,198 @@
+import { serviceAdapter } from "./registry.js";
+import { refundStateEnvelope } from "./shared/refund.js";
+import { appendFeedbackPostmortemInstruction, isTerminalServiceExecutionStatus } from "./shared/envelope.js";
+import { terminalExecutionEnvelope, serviceDeliveryMode, normalizeGrantStatus, paidContinuation, purchaseConfirmationInstruction, serviceAllowedActionCommand } from "./shared/platform.js";
+export function servicesNextEnvelope(model) {
+    const execution = model.execution;
+    const adapter = serviceAdapter(execution);
+    const currentDelivery = model.current_delivery ?? model.delivery_bindings.at(-1);
+    const lockedRefund = model.refunds.find((refund) => refund.access_locked);
+    if (lockedRefund) {
+        const refundState = refundStateEnvelope(lockedRefund, "delivery_locked");
+        return { ...refundState, result: { ...refundState.result, service_execution_id: execution.service_execution_id, refund: { refund_request_id: lockedRefund.refund_request_id, status: lockedRefund.status, ...(lockedRefund.failure_class ? { failure_class: lockedRefund.failure_class } : {}) } },
+            next: refundState.next ? { command: `itpay refund get ${lockedRefund.refund_request_id} --json`, reason: "读取同一退款权威状态" } : null };
+    }
+    const unsettledPayment = model.payment_bindings.some(binding => typeof binding.status === "string" && ["pending", "outcome_unknown", "unknown", "processing"].includes(binding.status));
+    if (unsettledPayment)
+        return { status: "payment_outcome_pending", result: { service_execution_id: execution.service_execution_id, payment_state: "unsettled", checkout_ids: model.checkout_bindings.map(binding => binding.checkout_id) }, instruction: "原付款结果尚未确认。保留同一执行、Checkout和订单，只核对权威事实；不创建新报价、购物车、付款入口或购买，也不宣称已付款或服务已完成。", next: null, recovery: [{ command: `itpay services get ${execution.service_execution_id} --json`, reason: "仅用户要求或平台恢复后核对同一付款事实" }] };
+    // Terminal facts take priority unless the locked adapter supports same-execution recovery.
+    if (!(adapter.preservesTerminalRecovery(model)) && isTerminalServiceExecutionStatus(execution.status) && !["completed", "delivery_completed"].includes(execution.status)) {
+        // Preserve the registered adapter's safe failure facts even at execution terminal.
+        const failedWorkflow = execution.status === "failed" && model.workflow?.status === "failed" ? adapter.workflow(model) : undefined;
+        if (failedWorkflow)
+            return { ...failedWorkflow, next: null };
+        const terminal = terminalExecutionEnvelope(model);
+        if (terminal)
+            return terminal;
+    }
+    const latestRun = model.execution_requests?.filter((request) => request.execution_kind === "service.execution.run").at(-1);
+    if (latestRun && ["pending", "started"].includes(latestRun.status) && model.workflow?.status !== "failed") {
+        return {
+            status: "running",
+            result: { service_execution_id: execution.service_execution_id, execution_request_id: latestRun.execution_request_id },
+            instruction: "任务仍在排队或执行中，稍后读取同一任务。不要重新查询、重复提交输入或把等待状态当作零结果。",
+            next: { command: `itpay services next ${execution.service_execution_id} --json`, reason: "稍后读取同一任务状态" },
+            recovery: [],
+        };
+    }
+    const businessState = adapter.projectState(model);
+    if (businessState)
+        return businessState;
+    if (latestRun && ["failed", "cancelled"].includes(latestRun.status) && !model.workflow_entry) {
+        return {
+            status: latestRun.status,
+            result: { service_execution_id: execution.service_execution_id },
+            instruction: "本次任务未完成，需要检查同一任务的处理记录；这不表示没有结果。不要自动重新发起。",
+            next: null,
+            recovery: [{ command: `itpay services events ${execution.service_execution_id} --json`, reason: "读取同一任务的处理记录" }],
+        };
+    }
+    if (!adapter.supported)
+        return { status: "presentation_contract_unavailable", result: { service_execution_id: execution.service_execution_id, service_id: execution.service_id, service_contract_version_id: execution.service_contract_version_id, public_binding: execution.public_binding }, instruction: "当前锁定呈现合同不受本候选支持；保留执行与已有结果并停止，取得兼容CLI后读取同一执行，不猜模式或启动新购买。", next: null, recovery: [] };
+    const workflowEnvelope = adapter.workflow(model);
+    if (workflowEnvelope)
+        return workflowEnvelope;
+    const terminalEnvelope = terminalExecutionEnvelope(model);
+    if (terminalEnvelope)
+        return terminalEnvelope;
+    const currentItems = model.current_result_items ?? [];
+    const savedRailResult = adapter.savedResult(model);
+    if (savedRailResult)
+        return savedRailResult;
+    const delivery = currentDelivery;
+    const deliveryMode = serviceDeliveryMode(model);
+    const candidateSelection = model.allowed_actions?.find((action) => action.type === "select_candidate");
+    if (candidateSelection && currentItems.length > 0) {
+        const paidCapability = delivery?.capability_id
+            ? model.capabilities.find((capability) => capability.capability_id === delivery.capability_id && capability.requires_payment)
+            : undefined;
+        return {
+            status: "candidate_selection_available",
+            result: {
+                service_execution_id: execution.service_execution_id,
+                ...(delivery?.capability_id ? { capability_id: delivery.capability_id } : {}),
+                ...(deliveryMode ? { delivery_mode: deliveryMode } : {}),
+                items: currentItems.map((item) => ({
+                    rank: item.rank,
+                    title: item.display_title,
+                    safe_payload: item.safe_payload,
+                })),
+            },
+            instruction: paidCapability
+                ? "付费搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才提交 interaction 中的对应编号；不要提及 safe_payload 或自动购买后续服务。"
+                : "用编号、名称和可公开字段向用户说明候选；若候选列表已满足目标就停止。只有用户明确选择并希望继续时才提交对应编号；不要提及 safe_payload、Execution 或内部 ID。",
+            next: null,
+            interaction: candidateInteraction(execution.service_execution_id),
+            recovery: [],
+        };
+    }
+    if (deliveryMode === "agent_visible_result") {
+        const items = currentItems.map((item) => ({
+            rank: item.rank,
+            title: item.display_title,
+            safe_payload: item.safe_payload,
+        }));
+        const selection = model.allowed_actions?.find((action) => action.type === "select_candidate");
+        const deliveryGuidance = adapter.deliveryGuidance(model);
+        const instruction = (delivery?.order_id
+            ? appendFeedbackPostmortemInstruction(items.length > 0
+                ? selection
+                    ? "搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才提交 interaction 中的对应编号；不要提及 safe_payload。"
+                    : "这一步的结果已经可用。用普通语言解释可公开字段并停止；不要提及 Arazzo、safe_payload 或内部 ID。"
+                : "告诉用户本次查询得到 0 个结果并停止。Agent 不读取其他交付、不重放当前查询、修改输入或创建新查询。", "delivered")
+            : items.length > 0
+                ? selection
+                    ? "搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才提交 interaction 中的对应编号；不要提及 safe_payload。"
+                    : "这一步的结果已经可用。用普通语言解释可公开字段并停止；不要提及 Arazzo、safe_payload 或内部 ID。"
+                : "告诉用户本次查询得到 0 个结果并停止。Agent 不读取其他交付、不重放当前查询、修改输入或创建新查询。")
+            + (deliveryGuidance?.instruction && items.length > 0 ? ` ${deliveryGuidance.instruction}` : "");
+        return {
+            status: items.length > 0 ? "result_ready" : "no_result",
+            result: {
+                service_execution_id: execution.service_execution_id,
+                ...(delivery?.capability_id ? { capability_id: delivery.capability_id } : {}),
+                ...(delivery?.order_id ? { order_id: delivery.order_id, aftercare: { optional: true, command: `itpay feedback submit --order ${delivery.order_id} --json`, reason: "结果答复后按需复盘；不猜评分" } } : {}),
+                delivery_mode: deliveryMode,
+                items,
+            },
+            instruction,
+            next: null,
+            ...(selection ? { interaction: candidateInteraction(execution.service_execution_id) } : {}),
+            recovery: deliveryGuidance?.recovery ?? [],
+        };
+    }
+    if (deliveryMode === "vault_artifact") {
+        const grantStatus = normalizeGrantStatus(delivery?.grant_status);
+        const grantActive = grantStatus === "active";
+        const grantPending = grantStatus === "pending";
+        return {
+            status: grantActive ? "grant_active" : grantPending ? "result_preparing" : "human_authorization_required",
+            result: {
+                service_execution_id: execution.service_execution_id,
+                ...(delivery?.capability_id ? { capability_id: delivery.capability_id } : {}),
+                delivery_mode: deliveryMode,
+                grant_status: grantStatus,
+                ...(delivery?.preparation ? { preparation: delivery.preparation } : {}),
+                ...(grantActive && delivery?.grant_expires_at ? { grant_expires_at: delivery.grant_expires_at } : {}),
+            },
+            instruction: grantActive
+                ? "先告诉用户付费内容已经准备好且当前读取授权有效；立即读取并只解释授权字段，遵守范围与到期时间。"
+                : grantPending
+                    ? "告诉用户：授权已经完成，付费结果仍在同一订单下准备，不需要再次付款或授权。然后只执行 next.command 查询同一笔服务；Agent 不创建新服务、付款页面或数据请求，也不提前读取。"
+                    : "先告诉用户付费内容已经归入当前订单，但需要本人确认一次读取授权；请用户在订单页面授权，未授权前不要读取或猜测内容。",
+            next: grantPending ? {
+                command: `itpay services next ${execution.service_execution_id} --json`,
+                reason: "等待同一 Execution 的交付准备完成",
+            } : {
+                command: `itpay services read-result ${execution.service_execution_id} --json`,
+                reason: grantActive ? "读取当前有效 grant 的结果" : "仅在用户确认授权后执行",
+            },
+            recovery: [],
+        };
+    }
+    const allowedActions = model.allowed_actions ?? [];
+    const preferred = allowedActions[0];
+    if (preferred?.type === "prepare_quote") {
+        const continuation = paidContinuation(model, preferred, {});
+        if (continuation) {
+            return {
+                status: execution.status,
+                result: {
+                    service_execution_id: execution.service_execution_id,
+                    service_id: execution.service_id,
+                    phase: execution.phase,
+                    checkout: continuation.checkout,
+                },
+                instruction: purchaseConfirmationInstruction(execution.status === "quota_exhausted" ? "quota_exhausted" : "candidate_selected", continuation.price, continuation.capability.delivery_email_required, continuation.capability.delivery_email_purpose),
+                next: continuation.next,
+                recovery: [],
+            };
+        }
+    }
+    const next = preferred ? serviceAllowedActionCommand(model, preferred) : null;
+    return {
+        status: execution.status,
+        result: {
+            service_execution_id: execution.service_execution_id,
+            service_id: execution.service_id,
+            phase: execution.phase,
+            allowed_actions: allowedActions.map((action) => ({
+                type: action.type,
+                ...(action.capability_id ? { capability_id: action.capability_id } : {}),
+                requires_human: action.requires_human,
+            })),
+        },
+        instruction: preferred?.type === "resume_checkout"
+            ? "这笔服务已经有付款页面。只执行 next.command 恢复并展示同一个入口；Agent 不创建新的报价、购物车、付款页面或服务。"
+            : preferred?.type === "wait"
+                ? "告诉用户付款和订单已经确认，结果仍在同一笔服务中处理，不需要再次付款；如果最终无法交付，将从原订单检查退款路径。稍后只执行 next.command；Agent 不创建新服务、付款页面或数据请求，也不承诺退款结果。"
+                : preferred?.requires_human
+                    ? "当前下一步需要用户明确选择；先展示必要信息并等待确认。"
+                    : preferred ? "执行服务端返回的唯一首选动作；不要猜测其他 capability。" + adapter.locationInstruction(model.capabilities.find((item) => item.capability_id === preferred.capability_id)?.input_schema) : "当前没有后续动作。",
+        next,
+        recovery: [{ command: `itpay services get ${execution.service_execution_id} --json`, reason: "仅在当前动作异常时检查时间线" }],
+    };
+}
+function candidateInteraction(id) {
+    return { schema_version: "itpay.interaction.v1", stage: "candidate_selection_required", input_template: { command: `itpay services action ${id} --action select_candidate --actor-type human --status approved --candidate <rank> --json`, required_input: ["rank"], executable: false } };
+}

package/dist/src/services/rail/actions.js

@@ -0,0 +1,51 @@
+import { shellArgument } from "../shared/envelope.js";
+// Never copy server shell text. Known action facts select a fixed local CLI form.
+export function railAvailableActions(plan, executionID) {
+    return (plan.available_actions ?? []).map(action => {
+        const target = action.target;
+        const se = shellArgument(executionID);
+        const snapshot = target?.snapshot_id ?? plan.catalog_snapshot_id ?? plan.snapshot_id;
+        const snap = snapshot ? shellArgument(snapshot) : undefined;
+        let command;
+        let input;
+        if (!target || target.service_execution_id === executionID) {
+            switch (action.type) {
+                case "read_updates":
+                    command = `itpay services next ${se}${snap ? ` --since-snapshot ${snap}` : ""} --json`;
+                    break;
+                case "read_saved_page":
+                    if (snap)
+                        command = `itpay services page ${se} ${snap} --json`;
+                    break;
+                case "read_catalog":
+                    if (snap)
+                        command = `itpay services read-result ${se} --snapshot ${snap} --json`;
+                    break;
+                case "read_journey":
+                    if (snap && target?.journey_id)
+                        command = `itpay services read-result ${se} --snapshot ${snap} --journey ${shellArgument(target.journey_id)} --json`;
+                    break;
+                case "select_journey":
+                    if (target?.journey_id)
+                        command = `itpay services action ${se} --action select_journey --actor-type human --status approved --input ${shellArgument(`journey_id=${target.journey_id}`)} --json`;
+                    break;
+                case "expand_search": {
+                    const facts = action.input;
+                    if (typeof facts?.action_request_id === "string" && typeof facts.expected_query_revision === "number" && typeof facts.snapshot_id === "string") {
+                        input = { action_request_id: facts.action_request_id, expected_query_revision: facts.expected_query_revision, snapshot_id: facts.snapshot_id };
+                        command = `itpay services action ${se} --action workflow:expand_search --actor-type human --status approved --input-json <file> --json`;
+                    }
+                    break;
+                }
+                case "refine_preferences":
+                    input = action.input_example;
+                    command = `itpay services action ${se} --action workflow:refine_preferences --actor-type human --status approved --input-json <file> --json`;
+                    break;
+                case "stop_search":
+                    command = `itpay services action ${se} --action workflow:stop_search --actor-type human --status approved --json`;
+                    break;
+            }
+        }
+        return { type: action.type, provider_effect: action.provider_effect, ...(action.when ? { when: action.when } : {}), ...(command ? { command, ...(input ? { input_template: { input, executable: false }, ...(action.input_schema ? { input_schema: action.input_schema } : {}), ...(action.type === "refine_preferences" ? { instruction: "仅填用户改变的偏好，保留 expected_query_revision；rerank 复用已存事实，不新增查车。示例不是用户选择，端点/日期改变须新查询。" } : {}) } : {}) } : { instruction: "缺少当前动作的结构化合同事实；保留原执行，不执行服务器命令文本。" }) };
+    });
+}

package/dist/src/services/rail/adapter.js

@@ -0,0 +1,36 @@
+import { railAftercareOrder, railAftercareList, railAftercareEnvelope, railAftercareCreate, railAftercareRespond } from "./aftercare.js";
+import { railInputTemplate, railServiceGuidance, RAIL_ENDPOINT_BRIEF, locationInputInstruction, railOverviewInstruction } from "./guide.js";
+import { railShouldWait, railPollAfter } from "./wait.js";
+import { railInvocationProjection } from "./invocation.js";
+import { railInputRecoveryInstruction, railRunError, railActionError } from "./recovery.js";
+import { railWorkflowEnvelope } from "./review.js";
+import { railPlanningEnvelope } from "./results.js";
+import { railBookingEnvelope } from "./fulfillment.js";
+import { railSavedResultEnvelope, railSavedDeliveryGuidance } from "./saved.js";
+import { railCheckoutItinerary } from "./checkout.js";
+import { renderRailResultPage } from "./page.js";
+import { readSavedResult } from "./reading.js";
+export const railAdapter = {
+    entryInstruction: RAIL_ENDPOINT_BRIEF + "按 result.guidance 逐项填写输入（when_to_use 说明本服务适用场景、input_fields 是必填契约、input_example 是待填示意，必须替换用户真实值），然后继续同一服务执行。不要臆造字段名。",
+    supported: true, inputTemplate: railInputTemplate, inputInstruction: railInputRecoveryInstruction,
+    guidance: railServiceGuidance, requiresGuidance: id => id === "itpay-rail-smart",
+    overviewInstruction: railOverviewInstruction, locationInstruction: locationInputInstruction,
+    invocation: railInvocationProjection, shouldWait: railShouldWait, pollAfter: railPollAfter,
+    preservesTerminalRecovery: model => model.workflow?.human_action?.context?.quote_recovery === true,
+    projectState: model => model.rail_booking ? railBookingEnvelope(model) : model.rail_planning ? railPlanningEnvelope(model) : null,
+    workflow: railWorkflowEnvelope, savedResult: railSavedResultEnvelope, deliveryGuidance: railSavedDeliveryGuidance,
+    extraFacts: model => model.rail_booking ? { rail_booking: model.rail_booking } : {},
+    runError: railRunError, actionError: railActionError, readResult: readSavedResult,
+    renderPage: (...args) => { renderRailResultPage(...args); return true; },
+    checkout: async (backend, model, id, token) => railCheckoutItinerary(model, await backend.getCheckoutPresentation(id, token)),
+};
+const bookingAdapter = {
+    ...railAdapter,
+    aftercare: { order: railAftercareOrder, directory: railAftercareList, present: railAftercareEnvelope, create: railAftercareCreate, respond: railAftercareRespond },
+};
+export function railAdapterFor(identity) {
+    const booking = identity.public_binding
+        ? identity.public_binding.operation_id === "prepare_purchase"
+        : identity.service_id === "itpay-rail-booking";
+    return booking ? bookingAdapter : railAdapter;
+}

package/dist/src/services/rail/aftercare.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { operationID } from "../../state/config.js";
+import { CommandContractError } from "../shared/envelope.js";
+const target = z.object({ leg_index: z.number().int().nonnegative(), passenger_index: z.number().int().nonnegative() }).strict();
+const inputSchema = z.object({ operation: z.enum(["refund", "change"]), targets: z.array(target).min(1).max(15), reason: z.string().trim().min(1).max(1000), scope_revision: z.literal(1), user_confirmed_scope: z.literal(true), change: z.object({ travel_date: z.string().optional(), departure_after: z.string().optional(), arrival_before: z.string().optional(), seat_type: z.string().optional(), train_code: z.string().optional(), constraints: z.string().min(1).max(1000) }).strict().optional() }).strict();
+const responseSchema = z.object({ expected_revision: z.number().int().positive(), proposal_revision: z.number().int().positive().optional(), user_approved: z.boolean().optional(), additional_information: z.string().max(1000).optional(), reason: z.string().max(1000).optional() }).strict();
+export function railAftercareList(directory, orderID) {
+    return { status: "aftercare_directory", result: { ...directory }, instruction: directory.instruction + "段/乘客索引从0起，按返回事实选目标；明确‘第二段’用leg_index:1。整程模板列全部可用目标，指定范围则仅保留对应目标，不手填票价/供应商单号。范围已明确只说明后提交；不重新询问整程选择。", next: null, recovery: [], interaction: { schema_version: "itpay.interaction.v1", stage: "input_required", input_templates: Object.fromEntries(Object.entries(directory.input_templates).map(([operation, input]) => [operation, { command: `itpay aftercare create --order ${orderID} --input-json <file> --json`, input, executable: false, required_input: ["file", "targets", "reason", "user_confirmed_scope"] }])) } };
+}
+export function railAftercareEnvelope(view) {
+    const c = view.case;
+    const instruction = c.status === "awaiting_confirmation" ? "展示当前具体改签方案、旧新对应、差价和条件；旧购买委托不是新方案/费用批准。没有真实回答保持false并等待；本轮费用由人工协调，没有自动支付链接。"
+        : c.status === "needs_input" ? "展示管理员要求补充的内容，只补缺失事实；保留原申请范围。"
+            : c.status === "completed" ? "人工受理已完成；分别说明供应商核验结果与平台退款金额/状态。未退段仅报告权威已知事实，不保证仍可乘；不恢复平台内容访问锁。"
+                : c.status === "processing" ? "原申请正在人工办理或财务处理中；没有最终事实不说退票、改签或到账成功，不重试未知资金、不取消已发生操作。"
+                    : ["cancelled", "rejected"].includes(c.status) ? "说明原申请已取消或被拒绝及原因；没有撤销已发生供应商操作，也不自动创建替代购买。"
+                        : "已提交人工受理，尚未确认供应商退票/改签或钱款到账。先交付申请状态入口，再按用户意愿查询原申请，不循环轮询。";
+    const cancellation = view.can_cancel ? { cancel_template: { command: `itpay aftercare cancel ${c.case_id} --input-json <file> --json`, input: { expected_revision: c.revision, reason: "" }, executable: false, required_input: ["file"] } } : {};
+    const needsReply = ["awaiting_confirmation", "needs_input"].includes(c.status);
+    return { status: c.status, result: { ...view }, instruction, next: needsReply || ["completed", "cancelled", "rejected"].includes(c.status) ? null : { command: `itpay aftercare get ${c.case_id} --json`, reason: "按用户要求读取同一人工申请" }, recovery: [], ...((needsReply || view.can_cancel) ? { interaction: { schema_version: "itpay.interaction.v1", stage: c.status === "awaiting_confirmation" ? "consent_required" : "input_required", ...cancellation, ...(needsReply ? { input_template: { command: `itpay aftercare respond ${c.case_id} --input-json <file> --json`, input: { expected_revision: c.revision, ...(c.status === "awaiting_confirmation" ? { proposal_revision: c.proposal_revision, user_approved: false } : { additional_information: "" }) }, executable: false, required_input: ["file"] } } : {}) } } : {}) };
+}
+export async function railAftercareCreate(backend, config, orderID, raw) {
+    const parsed = inputSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new CommandContractError("rail_aftercare_input_invalid", "Aftercare input fields or genuine scope confirmation are missing", "Agent读取当前完整模板修正技术字段；只问缺失的真实范围/改签意向，不让用户填技术JSON。", [{ command: `itpay aftercare list --order ${orderID} --json`, reason: "读取当前行程、目标和完整模板" }]);
+    const value = parsed.data;
+    const change = value.change;
+    const input = { operation: value.operation, targets: value.targets, reason: value.reason, scope_revision: value.scope_revision, user_confirmed_scope: value.user_confirmed_scope, ...(change ? { change: { constraints: change.constraints, ...(change.travel_date !== undefined ? { travel_date: change.travel_date } : {}), ...(change.departure_after !== undefined ? { departure_after: change.departure_after } : {}), ...(change.arrival_before !== undefined ? { arrival_before: change.arrival_before } : {}), ...(change.seat_type !== undefined ? { seat_type: change.seat_type } : {}), ...(change.train_code !== undefined ? { train_code: change.train_code } : {}) } } : {}) };
+    return railAftercareEnvelope(await backend.createRailAftercare(orderID, input, await operationID(config, `aftercare.create:${orderID}:${JSON.stringify(input)}`)));
+}
+export async function railAftercareGet(backend, id) { return railAftercareEnvelope(await backend.getRailAftercare(id)); }
+export async function railAftercareRespond(backend, id, raw, cancel = false) {
+    const parsed = responseSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new CommandContractError("rail_aftercare_input_invalid", "Current revision or response fields are missing", "使用原申请当前返回模板；实质方案变化须重新取得明确同意。", [{ command: `itpay aftercare get ${id} --json`, reason: "读取同一申请当前方案和版本" }]);
+    const value = parsed.data;
+    const input = { expected_revision: value.expected_revision, ...(value.proposal_revision !== undefined ? { proposal_revision: value.proposal_revision } : {}), ...(value.user_approved !== undefined ? { user_approved: value.user_approved } : {}), ...(value.additional_information !== undefined ? { additional_information: value.additional_information } : {}), ...(value.reason !== undefined ? { reason: value.reason } : {}) };
+    return railAftercareEnvelope(await (cancel ? backend.cancelRailAftercare(id, input) : backend.respondRailAftercare(id, input)));
+}
+export async function railAftercareOrder(backend, order, envelope) {
+    if (!["paid", "delivery_pending", "delivered", "partially_refunded", "refunded"].includes(order.status))
+        return envelope;
+    const directory = await backend.listRailAftercare(order.order_id);
+    return { ...envelope, result: { ...envelope.result, journey: directory.journey, aftercare_cases: directory.cases }, instruction: (order.status === "partially_refunded" ? "订单为部分退款；仅本次选中票的供应商/金额事实已变化，不能说全程已退。" : "按原订单读取票段与人工售后事实。") + " 平台内容锁保持；脱敏剩余票段状态是合法只读事实，不保证历史已出票仍可乘坐。", next: { command: `itpay aftercare list --order ${order.order_id} --json`, reason: "读取原行程、剩余票段、申请目标及完整售后模板" } };
+}