@harrylabsj/kiwi 0.7.22 → 0.9.0

package/dist/cli.js

@@ -28,7 +28,8 @@
  *                                           Managed-local product lifecycle.
  */
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync, } from "node:fs";
 import { homedir, userInfo } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -52,19 +53,86 @@ import { runTui } from "./operator/tui.js";
 import { runInit } from "./supervisor/init.js";
 import { runMcpServe } from "./mcp/cli.js";
 import { runHttpServe } from "./http/cli.js";
+import { runGatewayServe } from "./merchant-gateway/cli.js";
+import { DEFAULT_MERCHANT_MCP_HOST, DEFAULT_MERCHANT_MCP_PATH, DEFAULT_MERCHANT_MCP_PORT, startMerchantMcpServer, } from "./mcp/merchant-server.js";
+import { assertMerchantMcpAuthPolicy, CompositeMerchantMcpVerifier, PairedCredentialVerifier, resolveMerchantMcpVerifier, } from "./mcp/merchant-auth.js";
+import { resolveMerchantMcpDirs } from "./mcp/merchant-dirs.js";
+import { MerchantOAuthServer, MerchantOAuthStore } from "./auth/merchant-oauth.js";
+import { MerchantOAuthVerifier } from "./auth/merchant-authorization.js";
+import { isLoopbackHost } from "./a2a/client/url-policy.js";
+import { MerchantRuntimeManager } from "./merchant-runtime/manager.js";
+import { buildRuntimeServiceSpecs } from "./merchant-runtime/services.js";
+import { collectMerchantHealth } from "./merchant-runtime/health.js";
+import { MerchantJobs, standardMerchantJobs } from "./merchant-runtime/jobs.js";
+import { runBackup } from "./merchant-runtime/backup.js";
+import { MerchantCoreService } from "./merchant-core/service.js";
+import { MerchantPolicyRuntime } from "./merchant-core/policy-runtime.js";
+import { buildMerchantPresentationResources } from "./mcp/merchant-resources.js";
+import { merchantAdminSurface } from "./merchant-admin/pending-page.js";
+import { MerchantAdminSessions, writeAdminCredentials } from "./auth/merchant-sessions.js";
+import { createPairingCode, revokePairedCredential } from "./auth/merchant-pairing.js";
+import { MerchantOperationStore } from "./merchant-core/operations.js";
+/** 读能力探测落盘记录的 listing_pause（F08 接线；记录缺失/损坏 → undefined 不判定）。 */
+function probeCapabilitiesListingPause(dataDir) {
+    try {
+        const probe = JSON.parse(readFileSync(path.join(dataDir, "capability-probe.json"), "utf8"));
+        return probe.capabilities?.listing_pause;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readRegistrationStatus(dataDir) {
+    try {
+        const value = JSON.parse(readFileSync(path.join(dataDir, "registration.json"), "utf8"));
+        return {
+            ok: value.ok === true,
+            ...(typeof value.error === "string" ? { error: value.error } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function countPendingMerchantCommands(dataDir) {
+    try {
+        const db = new DatabaseSync(path.join(dataDir, "state.sqlite"));
+        try {
+            const row = db
+                .prepare("SELECT COUNT(*) AS count FROM action_candidates WHERE status = 'pending_approval'")
+                .get();
+            return typeof row?.count === "number" ? row.count : 0;
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+import { agentDirName, DEFAULT_AGENTS_ROOT, ensurePathsForDir, openAgentDatabase } from "./agent/agent-db.js";
+import { writeFileAtomic } from "./fs/atomic-write.js";
+import { WriteApprovalCandidateStore } from "./agent/merchant/action-candidate.js";
+import { ProfileCredentialBroker } from "./agent/merchant/credential-broker.js";
+import { FakeMerchantClient, fakeMerchantProduct } from "./agent/merchant/fake-merchant-client.js";
+import { HttpMerchantClient } from "./agent/merchant/merchant-client.js";
+import { DefaultMerchantIntelligenceBackend } from "./agent/merchant/intelligence/default-backend.js";
+import { MemoryStore } from "./agent/memory/store.js";
+import { PrivateVault } from "./agent/memory/vault.js";
 import { runDown, runStatus, runUp, SupervisorError } from "./supervisor/manage.js";
 import { parseLogLines, runLogs } from "./supervisor/logs.js";
 import { StackConfigError } from "./supervisor/stack-config.js";
 import { cmdProductDoctor, productHelp, PRODUCT_VERSION, DEFAULT_CATALOG_URL, DEFAULT_PROFILE_PATH, } from "./product-cli.js";
 import { cmdWeixin, weixinUsage } from "./weixin/cli-weixin.js";
-import { DEFAULT_SHOPPING_DB_PATH, loadMerchantCredentials, merchantInit, slugifyMerchantId } from "./product-init.js";
+import { DEFAULT_SHOPPING_DB_PATH, loadMerchantCredentials, merchantInit, slugifyMerchantId, } from "./product-init.js";
 import readline from "node:readline";
 import { buyerInit, buyerSearch, buyerTasks } from "./product-buyer.js";
-import { supplierList, supplierPause, supplierPrefer, supplierRemove, supplierSave, supplierWatch, } from "./product-supplier.js";
+import { supplierList, supplierMetrics, supplierPause, supplierPrefer, supplierRemove, supplierSave, supplierWatch, } from "./product-supplier.js";
 import { merchantStats } from "./product-merchant.js";
 import { merchantPublish } from "./product-publish.js";
 import { catalogServe } from "./product-catalog.js";
-import { extractPublicDomain, runMerchantSetupPublic, SetupPublicError, validatePublicDomain } from "./product-setup-public.js";
+import { extractPublicDomain, runMerchantSetupPublic, SetupPublicError, validatePublicDomain, } from "./product-setup-public.js";
 const USAGE = `kiwi ${PRODUCT_VERSION} — commerce negotiation agent runtime
 
 Usage:
@@ -652,10 +720,12 @@ async function cmdTui(args) {
  * 覆盖 Agent Card / UCP / catalog 注册广告的公网地址（配合 Caddy/Nginx 反代）。
  */
 /** 审查 P1-09：agent serve 的 A2A 状态目录。缺省用稳定路径
- *  `<cwd>/.kiwi/agents/<agent_id>`（与 operator 路径共用同一缺省）——重启后
- *  Ledger/幂等/终态可恢复；显式 --data-dir 覆盖。绝不回退到临时目录。 */
+ *  `<cwd>/.kiwi/agents/<消毒后 agent_id>`——与写端（merchant mcp serve 的
+ *  policy-overrides / agent-db）同一消毒口径（审查 P2：此前读端用原始
+ *  agent_id、写端消毒，非 ASCII agent_id 下策略热更新对 A2A 静默不生效）；
+ *  重启后 Ledger/幂等/终态可恢复；显式 --data-dir 覆盖。绝不回退到临时目录。 */
 export function resolveServeDataDir(dataDir, agentId) {
-    return dataDir ?? path.resolve(".kiwi", "agents", agentId);
+    return dataDir ?? path.resolve(DEFAULT_AGENTS_ROOT, agentDirName(agentId));
 }
 async function cmdAgentServe(args) {
     const profile = requireProfileOrDefault(args);
@@ -671,12 +741,20 @@ async function cmdAgentServe(args) {
     // negotiation 可重开、已发 conditional offer 返回 offer_unknown。稳定目录
     // 让重启可恢复状态（resolveServeDataDir 见上）。
     const serveDataDir = resolveServeDataDir(args.dataDir, profile.agent_id);
+    // BUG-07：A2A 进程的策略读端——与 MCP 写端共享 <dataDir>/policy-overrides.json，
+    // 每次报价 stat 文件 mtime，变化才重载（策略热更新跨进程立即生效）。
+    const policyRuntime = new MerchantPolicyRuntime({
+        basePolicy: profile.merchant_policy,
+        file: path.join(serveDataDir, "policy-overrides.json"),
+        now: () => new Date().toISOString(),
+    });
     const profilePublicUrl = profile.merchant_public?.public_url;
     let node = await startA2aNode({
         profile,
         catalog,
         preferredPort: args.port ?? profile.merchant_public?.a2a_port,
         dataDir: serveDataDir,
+        merchantPolicy: () => policyRuntime.current().policy,
         ...(profilePublicUrl ? { publicBaseUrl: `https://${profilePublicUrl}` } : {}),
         ...(merchantToken ? { ownerToken: merchantToken } : {}),
         ownerTokenSecret: process.env.KIWI_CATALOG_OWNER_TOKEN_SECRET,
@@ -700,6 +778,7 @@ async function cmdAgentServe(args) {
                 catalog,
                 preferredPort: args.port,
                 dataDir: serveDataDir,
+                merchantPolicy: () => policyRuntime.current().policy,
                 ...(merchantToken ? { ownerToken: merchantToken } : {}),
                 ownerTokenSecret: process.env.KIWI_CATALOG_OWNER_TOKEN_SECRET,
             });
@@ -741,7 +820,14 @@ async function cmdAgentServe(args) {
     process.on("SIGTERM", shutdown);
     console.log("[agent serve] A2A server + 内置对话（/quit 退出整个进程）");
     try {
-        return await runChatTui({ kernel, input: process.stdin, output: process.stdout, reload, a2aNode, catalog });
+        return await runChatTui({
+            kernel,
+            input: process.stdin,
+            output: process.stdout,
+            reload,
+            a2aNode,
+            catalog,
+        });
     }
     finally {
         await a2aNode.stop();
@@ -961,7 +1047,10 @@ async function cmdBuyerSupplier(args) {
                 return EXIT.CONFIG;
             }
             if (action === "save") {
-                printJson({ ok: true, relationship: await supplierSave({ ...base, merchantId: id, catalogUrl: catalog }) });
+                printJson({
+                    ok: true,
+                    relationship: await supplierSave({ ...base, merchantId: id, catalogUrl: catalog }),
+                });
             }
             else if (action === "watch") {
                 const intervalSeconds = args.interval !== undefined ? Number(args.interval) : undefined;
@@ -978,6 +1067,7 @@ async function cmdBuyerSupplier(args) {
                         ...(args.query !== undefined ? { query: args.query } : {}),
                         ...(args.region !== undefined ? { region: args.region } : {}),
                         ...(intervalSeconds !== undefined ? { intervalSeconds } : {}),
+                        ...(args.expires !== undefined ? { expires: args.expires } : {}),
                         ...consent,
                     }),
                 });
@@ -1002,6 +1092,10 @@ async function cmdBuyerSupplier(args) {
             printJson({ ok: true, count: relationships.length, relationships });
             return EXIT.OK;
         }
+        if (action === "metrics") {
+            printJson({ ok: true, metrics: await supplierMetrics(base) });
+            return EXIT.OK;
+        }
         if (action === "pause" || action === "remove") {
             if (id === undefined || id === "") {
                 process.stderr.write(`supplier ${action} 需要 <relationship-id>\n`);
@@ -1013,7 +1107,7 @@ async function cmdBuyerSupplier(args) {
             printJson({ ok: true, relationship });
             return EXIT.OK;
         }
-        process.stderr.write(`unknown supplier command: ${action ?? ""}（save|watch|prefer|list|pause|remove）\n`);
+        process.stderr.write(`unknown supplier command: ${action ?? ""}（save|watch|prefer|list|metrics|pause|remove）\n`);
         return EXIT.CONFIG;
     }
     catch (err) {
@@ -1098,6 +1192,10 @@ async function routeMerchant(sub, args) {
     }
     if (sub === "start")
         return await cmdAgentServe(args);
+    if (sub === "mcp")
+        return await cmdMerchantMcp(args);
+    if (sub === "runtime")
+        return await cmdMerchantRuntime(args);
     if (sub === "init")
         return await cmdMerchantInit(args);
     if (sub === "publish")
@@ -1117,6 +1215,482 @@ async function routeMerchant(sub, args) {
     process.stderr.write(`unknown merchant command: ${sub}\n`);
     return EXIT.CONFIG;
 }
+/**
+ * `kiwi merchant runtime start|stop|status|health`：Merchant 实例运行时管理
+ * （V2 阶段一 src/merchant-runtime/）。A2A 接待服务与 MCP 管理服务作为受管
+ * 子进程，异常退出自动重启（退避）；停止 A2A 后本管理入口可重启它。
+ *
+ *   kiwi merchant runtime start [--profile <file>] [--data-dir <dir>]   前台监控（Ctrl+C 停全部）
+ *   kiwi merchant runtime stop                                          停全部受管服务
+ *   kiwi merchant runtime status                                        进程状态（JSON）
+ *   kiwi merchant runtime health                                        分项健康报告（JSON）
+ */
+async function cmdMerchantRuntime(args) {
+    const action = args.command[2];
+    if (action === undefined || !["start", "stop", "status", "health"].includes(action)) {
+        process.stderr.write("usage: kiwi merchant runtime <start|stop|status|health> [--profile <file>] [--data-dir <dir>]\n");
+        return EXIT.CONFIG;
+    }
+    const profile = requireProfileOrDefault(args);
+    if (profile.role !== "merchant") {
+        process.stderr.write("kiwi merchant runtime 需要 merchant profile（role: merchant）\n");
+        return EXIT.CONFIG;
+    }
+    const dirs = resolveMerchantMcpDirs({
+        ...(args.dataDir !== undefined ? { dataDir: args.dataDir } : {}),
+        agentId: profile.agent_id,
+    });
+    const cliEntry = fileURLToPath(import.meta.url);
+    const profileArgs = args.profile !== undefined ? ["--profile", args.profile] : [];
+    const manager = new MerchantRuntimeManager({
+        dir: dirs.merchantDataDir,
+        // BUG-04：子进程显式携带统一 --data-dir 与确定 cwd（三槽位解析结果）。
+        services: buildRuntimeServiceSpecs({ dirs, cliEntry, profileArgs }),
+    });
+    if (action === "status") {
+        process.stdout.write(`${JSON.stringify(manager.status(), null, 2)}\n`);
+        return EXIT.OK;
+    }
+    if (action === "health") {
+        const registration = readRegistrationStatus(dirs.merchantDataDir);
+        const pendingCommands = countPendingMerchantCommands(dirs.merchantDataDir);
+        const report = collectMerchantHealth({
+            dataDir: dirs.merchantDataDir,
+            services: manager.status(),
+            ...(registration !== undefined ? { registration } : {}),
+            ...(pendingCommands !== undefined ? { pendingCommands } : {}),
+        });
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        return report.ok ? EXIT.OK : EXIT.TRANSIENT;
+    }
+    if (action === "stop") {
+        for (const state of [...manager.status()].reverse()) {
+            await manager.stop(state.name);
+        }
+        process.stdout.write("[merchant runtime] 全部受管服务已停止\n");
+        return EXIT.OK;
+    }
+    // start：前台监控，异常退出自动重启；Ctrl+C 优雅关闭全部。
+    // 周期任务（V2 阶段四 + BUG-05）：健康轮询先**实时**执行能力探测（不只读
+    // 启动时落盘的旧记录），再产出健康报告；持续备份。
+    // fake provider（离线演示）无真实上游：探测写 ok 桩并注明。
+    const probeClient = isFakeProvider(profile)
+        ? undefined
+        : new HttpMerchantClient(profile.commerce.base_url, new ProfileCredentialBroker(profile));
+    const probePath = path.join(dirs.merchantDataDir, "capability-probe.json");
+    const jobs = new MerchantJobs();
+    for (const job of standardMerchantJobs({
+        healthPoll: async () => {
+            if (probeClient !== undefined) {
+                await probeClient.probeCapabilities({ persistPath: probePath });
+            }
+            else {
+                writeFileAtomic(probePath, `${JSON.stringify({ ok: true, version: "fake", probed_at: new Date().toISOString(), verdict: "compatible", capabilities: { catalog_read: true, catalog_write: true, inventory_write: true, listing_pause: true, resolve_review: true } }, null, 2)}\n`, { mode: 0o600 });
+            }
+            const registration = readRegistrationStatus(dirs.merchantDataDir);
+            const pendingCommands = countPendingMerchantCommands(dirs.merchantDataDir);
+            const report = collectMerchantHealth({
+                dataDir: dirs.merchantDataDir,
+                services: manager.status(),
+                ...(registration !== undefined ? { registration } : {}),
+                ...(pendingCommands !== undefined ? { pendingCommands } : {}),
+            });
+            // 审查 P2：原子写（health.json 被监控/一次性命令并发读，防撕裂读假告警）。
+            writeFileAtomic(path.join(dirs.merchantDataDir, "runtime", "health.json"), `${JSON.stringify(report, null, 2)}\n`, { mode: 0o600 });
+        },
+        backupHook: async () => {
+            runBackup({
+                dataDir: dirs.merchantDataDir,
+                backupsDir: path.join(dirs.merchantDataDir, "backups"),
+            });
+        },
+        healthIntervalMs: 60_000,
+        backupIntervalMs: 5 * 60_000,
+    })) {
+        jobs.register(job);
+    }
+    jobs.start();
+    // Node.js 在没有活动 I/O 句柄时会退出；runtime manager 的受管子进程
+    // 使用 detached + unref，单靠下面的 never-resolving Promise 不能维持
+    // systemd 主进程。显式保活，确保 7×24 监控/备份/自动重启持续运行。
+    const keepAlive = setInterval(() => undefined, 60_000);
+    console.log("[merchant runtime] 监控 a2a + mcp（异常退出自动重启；健康轮询 + 持续备份；Ctrl+C 停全部）");
+    await manager.supervise();
+    const shutdown = async () => {
+        clearInterval(keepAlive);
+        jobs.stop();
+        await manager.shutdown();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    await new Promise(() => { });
+    return EXIT.OK;
+}
+/**
+ * `kiwi merchant mcp serve`：Merchant Workbench 标准远程 MCP server
+ * （WorkBuddy Buddy 应用开发计划 阶段二；官方 @modelcontextprotocol/sdk
+ * streamableHttp，独立端口/路径，不复用 A2A 端点）。
+ *
+ * 单商家一服务（MVP）：租户 = profile.owner_id。认证 = Bearer token
+ * （merchant_mcp.token_env 指向的环境变量，缺省 KIWI_MERCHANT_MCP_TOKEN）；
+ * fail-closed：非 loopback 监听且未配置 token 时拒绝启动。
+ *
+ * 审批闭环（阶段四）：draft 候选的执行钩子是进程级的——本进程生成的候选
+ * 直接可批准执行；启动时为库内遗留的 draft_product_change 候选重建钩子
+ * （recoverPendingDrafts），其他工具的遗留候选按 expireForRecovery 语义失效。
+ *
+ *   kiwi merchant mcp serve [--profile <file>] [--host <host>] [--port N] [--data-dir <dir>]
+ */
+async function cmdMerchantMcp(args) {
+    // `kiwi merchant mcp admin-passwd`：初始化/重置管理员口令（BUG-01 账户来源：
+    // 单商家实例管理员 = 本实例 principal）。新口令只从环境变量读取
+    // （KIWI_MERCHANT_ADMIN_PASSWORD），绝不出现在命令行/日志；落盘为 scrypt 哈希。
+    if (args.command[2] === "admin-passwd") {
+        const profile = requireProfileOrDefault(args);
+        if (profile.role !== "merchant") {
+            process.stderr.write("kiwi merchant mcp admin-passwd 需要 merchant profile\n");
+            return EXIT.CONFIG;
+        }
+        const password = (process.env.KIWI_MERCHANT_ADMIN_PASSWORD ?? "").trim();
+        if (password === "") {
+            process.stderr.write("请通过环境变量 KIWI_MERCHANT_ADMIN_PASSWORD 提供新口令（至少 8 位；不要写在命令行）\n");
+            return EXIT.CONFIG;
+        }
+        const dirs = resolveMerchantMcpDirs({
+            ...(args.dataDir !== undefined ? { dataDir: args.dataDir } : {}),
+            agentId: profile.agent_id,
+        });
+        try {
+            writeAdminCredentials(dirs.merchantDataDir, {
+                principalId: profile.agent_id,
+                merchantId: profile.owner_id,
+                password,
+                force: args.force,
+            });
+        }
+        catch (err) {
+            process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+            return EXIT.CONFIG;
+        }
+        process.stdout.write("管理员口令已设置（哈希落盘 admin-credentials.json，0600）\n");
+        return EXIT.OK;
+    }
+    // `kiwi merchant mcp pair`：生成一次性配对码（§8.4 第二期）。商家把它填进
+    // 商家连接器网关的绑定页，网关据此兑换内部凭据——不必把长期令牌贴进表单。
+    if (args.command[2] === "pair") {
+        const profile = requireProfileOrDefault(args);
+        if (profile.role !== "merchant") {
+            process.stderr.write("kiwi merchant mcp pair 需要 merchant profile（role: merchant）\n");
+            return EXIT.CONFIG;
+        }
+        const dirs = resolveMerchantMcpDirs({
+            ...(args.dataDir !== undefined ? { dataDir: args.dataDir } : {}),
+            agentId: profile.agent_id,
+        });
+        const { code, expiresAt } = createPairingCode(dirs.merchantDataDir);
+        const publicUrl = profile.merchant_mcp?.public_url?.replace(/\/+$/, "");
+        const port = args.port ?? profile.merchant_mcp?.port ?? DEFAULT_MERCHANT_MCP_PORT;
+        const mcpUrl = publicUrl !== undefined ? `${publicUrl}/mcp` : `http://127.0.0.1:${port}/mcp`;
+        const ttlMinutes = Math.max(1, Math.round((Date.parse(expiresAt) - Date.now()) / 60000));
+        process.stdout.write([
+            "一次性配对码已生成（本码只显示一次，用完或过期即失效）：",
+            "",
+            `  实例 MCP 地址：${mcpUrl}`,
+            `  配对码：       ${code}`,
+            `  有效期：       约 ${ttlMinutes} 分钟（至 ${expiresAt}）`,
+            "",
+            "在商家连接器网关的实例绑定页（https://<网关域名>/instance）选择「用配对码绑定」，",
+            "填入上面的地址与配对码即可；网关会用它兑换一份**新签发的**配对凭据"
+                + "（由本实例生成并持有，重配对即轮换），并加密保存。",
+            "配对码只证明「你在实例所在机器上」，商家身份仍以网关侧的目录 OAuth 连接为准。",
+            "",
+        ].join("\n"));
+        return EXIT.OK;
+    }
+    // `kiwi merchant mcp unpair`：吊销配对凭据（网关随后的调用会 401，直到重新配对）。
+    if (args.command[2] === "unpair") {
+        const profile = requireProfileOrDefault(args);
+        if (profile.role !== "merchant") {
+            process.stderr.write("kiwi merchant mcp unpair 需要 merchant profile（role: merchant）\n");
+            return EXIT.CONFIG;
+        }
+        const dirs = resolveMerchantMcpDirs({
+            ...(args.dataDir !== undefined ? { dataDir: args.dataDir } : {}),
+            agentId: profile.agent_id,
+        });
+        const revoked = revokePairedCredential(dirs.merchantDataDir);
+        process.stdout.write(revoked
+            ? "已吊销配对凭据：网关侧需重新配对才能继续调用本实例。\n"
+            : "没有已签发的配对凭据（无需吊销）。\n");
+        return EXIT.OK;
+    }
+    if (args.command[2] !== "serve") {
+        process.stderr.write("usage: kiwi merchant mcp serve [--profile <file>] [--host <host>] [--port N] [--data-dir <dir>]\n" +
+            "       kiwi merchant mcp pair [--profile <file>] [--data-dir <dir>]\n" +
+            "       kiwi merchant mcp unpair [--profile <file>] [--data-dir <dir>]\n" +
+            "       kiwi merchant mcp admin-passwd [--profile <file>] [--data-dir <dir>]\n");
+        return EXIT.CONFIG;
+    }
+    const profile = requireProfileOrDefault(args);
+    if (profile.role !== "merchant") {
+        process.stderr.write("kiwi merchant mcp serve 需要 merchant profile（role: merchant）\n");
+        return EXIT.CONFIG;
+    }
+    loadMerchantCredentials(); // 加载 init 写入的 credentials.env（KIWI_MERCHANT_TOKEN）
+    const mcpConfig = profile.merchant_mcp;
+    if (mcpConfig?.enabled === false) {
+        process.stderr.write("profile merchant_mcp.enabled=false：MCP server 未启用\n");
+        return EXIT.CONFIG;
+    }
+    // 正式 WorkBuddy Connector 省略 auth_mode 即走 OAuth；显式 token 仅保留给
+    // 过渡连接器。无 public_url 时的 OAuth 默认只监听 loopback，避免意外把
+    // 未配置公网 issuer 的服务暴露在 0.0.0.0。
+    const authMode = mcpConfig?.auth_mode ?? "oauth";
+    const host = args.catalogHost ??
+        mcpConfig?.host ??
+        (authMode === "oauth" && mcpConfig?.public_url === undefined
+            ? "127.0.0.1"
+            : DEFAULT_MERCHANT_MCP_HOST);
+    const port = args.port ?? mcpConfig?.port ?? DEFAULT_MERCHANT_MCP_PORT;
+    const mcpPath = mcpConfig?.path ?? DEFAULT_MERCHANT_MCP_PATH;
+    // 数据目录接线（V2 §5.1）：merchant/principal/transportSessionId 显式注入，
+    // 路径是 (dataDir, agentId) 的纯函数——重启稳定，传输会话不影响目录。
+    const dirs = resolveMerchantMcpDirs({
+        ...(args.dataDir !== undefined ? { dataDir: args.dataDir } : {}),
+        agentId: profile.agent_id,
+    });
+    // 认证模式（V2）：oauth = 自建 OAuth 2.1 授权服务器（正式）；
+    // token = V1 静态 Bearer（过渡）。fail-closed 判定见下。
+    let oauth;
+    let oauthDb;
+    let oauthStore;
+    let verifier;
+    // 会话与一次性确认凭证的存储**与认证模式无关**：写操作确认页（/admin/*）
+    // 在两种模式下都挂载——网关路由形态要求实例接受静态内部令牌（token 模式），
+    // 而商家仍必须能批准写候选，否则 prepare_* 只能等到期。
+    {
+        // 数据目录可能尚未创建（例如从未跑过 admin-passwd）：先建 0700，再预建库文件。
+        mkdirSync(dirs.merchantDataDir, { recursive: true, mode: 0o700 });
+        const oauthDbPath = path.join(dirs.merchantDataDir, "oauth.sqlite");
+        // 审查 P2：先以 0600 预建空文件再打开，消除「库已建、chmod 未执行」的
+        // 短暂默认权限窗口。
+        if (!existsSync(oauthDbPath)) {
+            writeFileSync(oauthDbPath, "", { mode: 0o600 });
+        }
+        oauthDb = new DatabaseSync(oauthDbPath);
+        chmodSync(oauthDbPath, 0o600);
+        oauthStore = new MerchantOAuthStore({ db: oauthDb });
+    }
+    if (authMode === "oauth") {
+        // issuer：public_url（生产 https）优先；loopback 开发推导为 http://127.0.0.1:<port>。
+        const issuer = mcpConfig?.public_url ?? (isLoopbackHost(host) ? `http://127.0.0.1:${port}` : undefined);
+        if (issuer === undefined) {
+            process.stderr.write("merchant_mcp.auth_mode=oauth 且监听非 loopback 地址时必须配置 merchant_mcp.public_url（https）作为 OAuth issuer\n");
+            return EXIT.CONFIG;
+        }
+        // 授权码/token/客户端注册同样落 oauth.sqlite（上面已按 0600 打开）。
+        oauth = new MerchantOAuthServer({
+            store: oauthStore,
+            issuer,
+            resource: `${issuer}${mcpPath}`,
+            connectorSource: "kiwi-merchant",
+            merchantName: profile.name ?? profile.owner_id,
+            merchantId: profile.owner_id,
+        });
+        verifier = new MerchantOAuthVerifier({
+            store: oauthStore,
+            expectedMerchantId: profile.owner_id,
+        });
+    }
+    else {
+        verifier = resolveMerchantMcpVerifier(mcpConfig?.token_env);
+        // token 模式（含网关路由形态：实例只接受网关的静态内部令牌）下，写操作
+        // 确认页同样挂载，商家在 /admin/pending 批准候选。
+        process.stderr.write("ℹ️ [kiwi] merchant_mcp.auth_mode=token：/mcp 使用静态内部令牌认证" +
+            "（网关路由形态的推荐配置）；写操作确认页仍挂载在 /admin/*，\n" +
+            "  需先 `kiwi merchant mcp admin-passwd` 设置管理员口令。\n");
+    }
+    let authWarning;
+    try {
+        // 策略按**静态 / OAuth** 校验器判定：组合校验器恒存在，若拿它判定会让
+        // 「非 loopback 且未配置任何凭据」的实例误判为已受保护而启动。
+        authWarning = assertMerchantMcpAuthPolicy(host, verifier);
+    }
+    catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        return EXIT.CONFIG;
+    }
+    if (authWarning !== undefined)
+        process.stderr.write(`${authWarning}\n`);
+    // 配对凭据（§8.4 第二期，最小授权）：由本实例签发、网关持有；与静态令牌
+    // 并存，任一通过即放行。商家重配对即轮换，`unpair` 即吊销。
+    verifier = new CompositeMerchantMcpVerifier([
+        ...(verifier !== undefined ? [verifier] : []),
+        new PairedCredentialVerifier(dirs.merchantDataDir),
+    ]);
+    // 依赖装配与 chat kernel 同一套：agent data dir + state.sqlite + 审批候选 store。
+    // 审批候选与对话内核共享同一 DB——MCP 生成的 draft 候选在内核侧 /pending 可见。
+    const paths = ensurePathsForDir(dirs.merchantDataDir);
+    const db = openAgentDatabase(paths.db);
+    const now = () => new Date().toISOString();
+    const store = new MemoryStore({ db, vault: new PrivateVault(), now });
+    const principal = store.ensurePrincipal({
+        principal_id: profile.agent_id,
+        owner_id: profile.owner_id,
+        role: profile.role,
+    });
+    store.bindPrincipal(principal.principal_id);
+    const approvals = new WriteApprovalCandidateStore({
+        db,
+        principalId: principal.principal_id,
+        now,
+    });
+    // 执行钩子是进程级的：重启后遗留的 pending 候选无法被本进程执行。按
+    // expireForRecovery 语义把非本服务可恢复的候选先失效（防虚报死候选）；
+    // draft_product_change 候选的参数在库内、钩子可确定性重建，留给
+    // service.recoverPendingDrafts() 恢复（阶段四审批闭环）。
+    for (const candidate of approvals.listPending()) {
+        if (candidate.tool !== "draft_product_change")
+            approvals.expireCandidate(candidate.candidate_id);
+    }
+    // merchantClient：fake provider 走离线 Fake，否则真实网关（同 kernel-builder）。
+    let merchantClient;
+    if (isFakeProvider(profile)) {
+        merchantClient = new FakeMerchantClient({ products: [fakeMerchantProduct()] });
+    }
+    else {
+        const broker = new ProfileCredentialBroker(profile);
+        const httpClient = new HttpMerchantClient(profile.commerce.base_url, broker);
+        merchantClient = httpClient;
+        // 能力探测（V2 阶段一/P0-5；协议协商升级）：结果落盘供版本组合锁定。
+        // verdict=incompatible（网关通告不含 Kiwi 需要的协议版本）→ 硬拒绝启动；
+        // indeterminate/unhealthy（不可达/协商不可用且不可判定/健康未过）→ 警示
+        // 但不阻塞（网关可能仍在启动，报价路径本身 fail-closed，不产生报价）。
+        const probe = await httpClient.probeCapabilities({
+            persistPath: path.join(dirs.merchantDataDir, "capability-probe.json"),
+        });
+        if (probe.verdict === "incompatible") {
+            process.stderr.write(`[kiwi] shopping-cli 协议不兼容，拒绝启动：${probe.error ?? "未知原因"}。\n` +
+                "升级或更换 shopping-cli 网关（需支持 shopping.negotiation/0.1）后重试。\n");
+            return EXIT.CONFIG;
+        }
+        if (!probe.ok) {
+            process.stderr.write(`⚠️ [kiwi] shopping-cli 能力探测未通过：${probe.error ?? "未知原因"}；` +
+                "相关读取/报价在上游恢复前 fail-closed。\n");
+        }
+    }
+    const intelligence = profile.merchant_experience?.enabled === true &&
+        profile.merchant_experience.intelligence !== false
+        ? new DefaultMerchantIntelligenceBackend({
+            merchant_id: profile.owner_id,
+            data_dir: paths.dir,
+            // presentation context 的 principalId 用 owner_id（商家读取口径）——
+            // backend 的 principal 校验键与之对齐（MCP 服务侧统一 owner 口径）。
+            principal_id: profile.owner_id,
+            merchant_client: merchantClient,
+            approvals,
+            now,
+        })
+        : undefined;
+    // BUG-07：运行中策略提供器（覆盖层 <merchantDataDir>/policy-overrides.json）。
+    // 本进程（MCP）为写端：校验 patch + 原子写完整生效策略；A2A 子进程为读端：
+    // 按文件 mtime 读取——策略变更跨进程立即生效，不再只落盘不生效。
+    const policyRuntime = new MerchantPolicyRuntime({
+        basePolicy: profile.merchant_policy,
+        file: path.join(dirs.merchantDataDir, "policy-overrides.json"),
+        now,
+    });
+    // 共享业务入口（V2 阶段二）：merchant-core 包装 V1 facade（facade 语义不变），
+    // MCP 工具层经 core 调用；私密读取审计目录落 merchantDataDir/private-audit。
+    const service = new MerchantCoreService({
+        profile,
+        merchantClient,
+        approvals,
+        // MCP 写工具一律 force_pending 只产候选，mode 不影响执行安全；固定 supervised。
+        mode: () => "supervised",
+        now,
+        // 商家 A2A 节点 ledger 基础目录（LedgerStore 会再拼 /ledger）。
+        a2aLedgerDir: path.join(paths.dir, "a2a"),
+        ...(intelligence !== undefined ? { intelligence } : {}),
+        auditDir: path.join(dirs.merchantDataDir, "private-audit"),
+        // 命令记录授权主体 = 审批 store principal（批准/拒绝主体一致性校验）。
+        commandPrincipalId: principal.principal_id,
+        // BUG-02：一次性确认凭证存储（OAuth 模式；execute/reject 必须携带有效凭证）。
+        ...(oauthStore !== undefined ? { confirmations: oauthStore } : {}),
+        // 长任务 operation store（与命令记录同一 state.sqlite，单 owner 写）。
+        operations: new MerchantOperationStore({ db, now }),
+        // F08 能力接线：能力探测落盘记录中 listing_pause=false 时 fail-closed「不可得」。
+        ...(probeCapabilitiesListingPause(dirs.merchantDataDir) !== undefined
+            ? { capabilities: { listing_pause: probeCapabilitiesListingPause(dirs.merchantDataDir) } }
+            : {}),
+        // F17/BUG-07 策略热更新：经 MerchantPolicyRuntime 校验 + 原子写完整生效
+        // 策略（版本/digest 回执进命令记录）；A2A 进程按同一文件 mtime 读取生效。
+        applyPolicyOverride: (patch) => policyRuntime.apply(patch),
+        // 运行中策略读取：执行器硬策略（底价兜底）按当前生效策略校验。
+        currentPolicy: () => policyRuntime.current().policy,
+    });
+    // 审批闭环（阶段三推广版）：恢复全部已注册写工具的 pending 命令（覆盖 V1
+    // recoverPendingDrafts 语义）；未注册工具的死候选标 expired。
+    const recovered = service.recoverPendingCommands();
+    // 七类 presentation → MCP 资源（V2 阶段二；私密类不进资源）。
+    const presentations = buildMerchantPresentationResources({
+        context: {
+            profile,
+            // presentation 的 enrich 以 principalId 作为商家读取口径（目录/intelligence
+            // 都按 merchant_id 校验）——用 owner_id，不用进程 principal（agent_id）。
+            principalId: profile.owner_id,
+            merchantClient,
+            approvals,
+            ...(intelligence !== undefined ? { intelligence } : {}),
+        },
+    });
+    // 配对兑换：两种认证模式都挂载——凭据由本实例在兑换时新签，不依赖环境变量。
+    const handle = await startMerchantMcpServer({
+        service,
+        host,
+        port,
+        path: mcpPath,
+        pairing: {
+            dir: dirs.merchantDataDir,
+            instance: () => ({
+                ownerId: profile.owner_id,
+                principalId: profile.agent_id,
+            }),
+        },
+        ...(verifier !== undefined ? { auth: verifier } : {}),
+        ...(oauth !== undefined ? { oauth } : {}),
+        presentations,
+        // 配套商家确认页面（BUG-01/03）：cookie 会话 + 一次性确认凭证，两种认证
+        // 模式下都挂载（会话/凭证存 oauth.sqlite，与 OAuth 授权服务器同库不同表）。
+        ...(oauthDb !== undefined && oauthStore !== undefined
+            ? {
+                admin: {
+                    merchantName: profile.name ?? profile.owner_id,
+                    surface: merchantAdminSurface(service),
+                    sessions: new MerchantAdminSessions({ db: oauthDb }),
+                    store: oauthStore,
+                    adminDir: dirs.merchantDataDir,
+                    secureCookies: (mcpConfig?.public_url ?? "").startsWith("https://"),
+                },
+            }
+            : {}),
+        serverInfo: { name: "kiwi-merchant", version: PRODUCT_VERSION },
+    });
+    console.log(`[merchant mcp] merchant ${profile.agent_id} MCP server: ${handle.url}` +
+        `（auth: ${verifier?.name ?? "none（loopback-only）"}${authMode === "oauth" ? "，OAuth 端点已挂载" : ""}；kiwi_merchant_* 工具 + 展示资源）` +
+        (recovered.recovered > 0 ? `；恢复 ${recovered.recovered} 个待批准写命令` : ""));
+    const shutdown = async () => {
+        await handle.close().catch(() => undefined);
+        oauthDb?.close();
+        db.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    await new Promise(() => { });
+    return EXIT.OK;
+}
 /**
  * `kiwi merchant stats`：商家侧运营统计（本地数据，不上报）——
  * 多少个不同的买家联系过我、讨论了哪些 SKU。数据由 merchant A2A 节点
@@ -1248,12 +1822,17 @@ async function cmdMerchantPublish(args) {
     }
     const ownerTokenSecret = process.env.KIWI_CATALOG_OWNER_TOKEN_SECRET;
     const merchantTokenEnv = profile.merchant_public?.merchant_token_env;
-    const merchantToken = (merchantTokenEnv ? process.env[merchantTokenEnv] : undefined) || process.env.KIWI_MERCHANT_TOKEN || "";
+    const merchantToken = (merchantTokenEnv ? process.env[merchantTokenEnv] : undefined) ||
+        process.env.KIWI_MERCHANT_TOKEN ||
+        "";
     if (!merchantToken && !ownerTokenSecret) {
         process.stderr.write("需要 KIWI_MERCHANT_TOKEN（随机 token，推荐）或 KIWI_CATALOG_OWNER_TOKEN_SECRET（legacy HMAC）\n");
         return EXIT.CONFIG;
     }
-    const catalog = args.catalog ?? profile.merchant_public?.catalog_url ?? process.env.KIWI_CATALOG_URL ?? DEFAULT_CATALOG_URL;
+    const catalog = args.catalog ??
+        profile.merchant_public?.catalog_url ??
+        process.env.KIWI_CATALOG_URL ??
+        DEFAULT_CATALOG_URL;
     const report = await merchantPublish({
         profile,
         catalogBaseUrl: catalog,
@@ -1264,9 +1843,7 @@ async function cmdMerchantPublish(args) {
         ...(args.shoppingCliMerchant !== undefined
             ? { shoppingCliMerchant: args.shoppingCliMerchant }
             : {}),
-        ...(args.allowEmptyProjectionReconcile
-            ? { allowEmptyProjectionReconcile: true }
-            : {}),
+        ...(args.allowEmptyProjectionReconcile ? { allowEmptyProjectionReconcile: true } : {}),
     });
     printJson(report);
     return report.ok ? EXIT.OK : EXIT.CONFIG;
@@ -1308,10 +1885,15 @@ async function cmdDemo(args) {
  */
 async function cmdMerchantSetupPublic(args) {
     const profile = requireProfileOrDefault(args); // 无 --profile 时回退缺省 ~/.kiwi/kiwi.yaml
-    const port = args.port ?? profile.merchant_public?.a2a_port ?? (Number(process.env.KIWI_A2A_PORT ?? "") || 9000); // 与 startA2aNode 缺省一致
+    const port = args.port ??
+        profile.merchant_public?.a2a_port ??
+        (Number(process.env.KIWI_A2A_PORT ?? "") || 9000); // 与 startA2aNode 缺省一致
     // 单一来源：--domain 显式 > profile.merchant_public.public_url（init 引导写入）>
     // KIWI_A2A_PUBLIC_URL env 提取；TTY 下再交互提示。
-    let domain = args.domain ?? profile.merchant_public?.public_url ?? extractPublicDomain(process.env.KIWI_A2A_PUBLIC_URL) ?? "";
+    let domain = args.domain ??
+        profile.merchant_public?.public_url ??
+        extractPublicDomain(process.env.KIWI_A2A_PUBLIC_URL) ??
+        "";
     if (domain === "" && process.stdin.isTTY) {
         domain = await promptLine("公网域名（如 merchant.example.com，TLS 证书就用它）: ", "");
     }
@@ -1378,12 +1960,17 @@ async function cmdMerchantUp(args) {
     }
     loadMerchantCredentials(); // 加载 init 写入的 credentials.env（KIWI_MERCHANT_TOKEN）
     // ── 域名 / 端口 / Caddyfile（profile 兜底）──
-    const domain = args.domain ?? profile.merchant_public?.public_url ?? extractPublicDomain(process.env.KIWI_A2A_PUBLIC_URL) ?? "";
+    const domain = args.domain ??
+        profile.merchant_public?.public_url ??
+        extractPublicDomain(process.env.KIWI_A2A_PUBLIC_URL) ??
+        "";
     if (domain === "") {
         process.stderr.write("需要公网域名——先 `kiwi merchant init` 填公网域名，或 --domain <域名>\n");
         return EXIT.CONFIG;
     }
-    const port = args.port ?? profile.merchant_public?.a2a_port ?? (Number(process.env.KIWI_A2A_PORT ?? "") || 9000);
+    const port = args.port ??
+        profile.merchant_public?.a2a_port ??
+        (Number(process.env.KIWI_A2A_PORT ?? "") || 9000);
     const caddyfilePath = args.caddyfile ?? "Caddyfile.kiwi";
     // ── setup-public：检测 IP / DNS 检查 / 生成 Caddyfile（幂等）──
     await runMerchantSetupPublic({
@@ -1403,7 +1990,10 @@ async function cmdMerchantUp(args) {
     // ── 起 Caddy 反代（子进程，日志透传）──
     const caddy = spawn("caddy", ["run", "--config", caddyfilePath], { stdio: "inherit" });
     // ── 起 A2A 节点（与 merchant start --no-chat 同一路径）──
-    const catalog = args.catalog ?? profile.merchant_public?.catalog_url ?? process.env.KIWI_CATALOG_URL ?? DEFAULT_CATALOG_URL;
+    const catalog = args.catalog ??
+        profile.merchant_public?.catalog_url ??
+        process.env.KIWI_CATALOG_URL ??
+        DEFAULT_CATALOG_URL;
     const merchantToken = process.env.KIWI_MERCHANT_TOKEN || "";
     const serveDataDir = resolveServeDataDir(args.dataDir, profile.agent_id);
     let node = await startA2aNode({
@@ -1431,7 +2021,7 @@ async function cmdMerchantUp(args) {
 /**
  * `kiwi setup-hermes`（买家侧）——一键把 Kiwi 买家连接器接入 Hermes：
  * 配置 kiwi-buyer-mcp MCP server + 安装 kiwi-buyer skill。之后 Hermes 重启
- * 即可调用 9 个采购工具。等价于手动执行：
+ * 即可调用 13 个采购工具。等价于手动执行：
  *   hermes mcp add kiwi-buyer-mcp --command node --args <cli> mcp serve ...
  *   hermes skills install <SKILL.md URL>
  */
@@ -1452,7 +2042,8 @@ async function cmdSetupHermes() {
         username = process.env.USER ?? "user";
     }
     const dbPath = path.join(homedir(), ".kiwi", "buyer.sqlite");
-    const skillUrl = "https://raw.githubusercontent.com/harrylabsj/kiwi/main/integrations/hosts/hermes/SKILL.md";
+    const skillUrl = "https://raw.githubusercontent.com/harrylabsj/kiwi/main/skills/kiwi-buyer/SKILL.md";
+    const bundledSkillPath = fileURLToPath(new URL("../skills/kiwi-buyer/SKILL.md", import.meta.url));
     const skillPath = path.join(homedir(), ".hermes", "skills", "kiwi-buyer", "SKILL.md");
     const configured = [];
     const already = [];
@@ -1487,29 +2078,45 @@ async function cmdSetupHermes() {
         }
         configured.push("MCP server kiwi-buyer-mcp");
     }
-    // 4. kiwi-buyer skill：已存在则跳过；否则 hermes install（失败则直接 fetch 落盘兜底）
+    // 4. kiwi-buyer skill：优先使用 npm 包内置版本，避免依赖网络；否则从公共 URL 安装
     if (existsSync(skillPath)) {
         already.push("skill kiwi-buyer");
     }
     else {
         process.stdout.write("[setup-hermes] 安装 kiwi-buyer skill ...\n");
-        const skill = spawnSync("hermes", ["skills", "install", skillUrl, "--yes"], { stdio: "inherit" });
-        if (skill.status !== 0 || !existsSync(skillPath)) {
-            // 兜底：直接 fetch SKILL.md 写入 ~/.hermes/skills/kiwi-buyer/（Hermes skills 为 local 存储）
-            process.stdout.write("[setup-hermes] hermes skills install 不可用，改用直接写入 ...\n");
+        if (existsSync(bundledSkillPath)) {
+            process.stdout.write("[setup-hermes] 使用 npm 包内置 skill ...\n");
             try {
-                const res = await fetch(skillUrl, { signal: AbortSignal.timeout(15000) });
-                if (!res.ok)
-                    throw new Error(`HTTP ${res.status}`);
-                const content = await res.text();
                 mkdirSync(path.dirname(skillPath), { recursive: true, mode: 0o700 });
-                writeFileSync(skillPath, content, { mode: 0o600 });
+                copyFileSync(bundledSkillPath, skillPath);
+                chmodSync(skillPath, 0o600);
             }
             catch (err) {
                 process.stderr.write(`安装 kiwi-buyer skill 失败：${err instanceof Error ? err.message : String(err)}\n`);
                 return EXIT.CONFIG;
             }
         }
+        else {
+            const skill = spawnSync("hermes", ["skills", "install", skillUrl, "--yes"], {
+                stdio: "inherit",
+            });
+            if (skill.status !== 0 || !existsSync(skillPath)) {
+                // 兜底：直接 fetch SKILL.md 写入 ~/.hermes/skills/kiwi-buyer/（Hermes skills 为 local 存储）
+                process.stdout.write("[setup-hermes] hermes skills install 不可用，改用直接写入 ...\n");
+                try {
+                    const res = await fetch(skillUrl, { signal: AbortSignal.timeout(15000) });
+                    if (!res.ok)
+                        throw new Error(`HTTP ${res.status}`);
+                    const content = await res.text();
+                    mkdirSync(path.dirname(skillPath), { recursive: true, mode: 0o700 });
+                    writeFileSync(skillPath, content, { mode: 0o600 });
+                }
+                catch (err) {
+                    process.stderr.write(`安装 kiwi-buyer skill 失败：${err instanceof Error ? err.message : String(err)}\n`);
+                    return EXIT.CONFIG;
+                }
+            }
+        }
         configured.push("skill kiwi-buyer");
     }
     // 5. 报告
@@ -1556,6 +2163,11 @@ export async function main(argv = process.argv.slice(2)) {
     if (argv[0] === "buyer-api" && argv[1] === "serve") {
         return await runHttpServe(argv.slice(2));
     }
+    // `kiwi merchant gateway serve`：商家连接器远程入口，独立 flag 集
+    // （--public-url / --catalog-url / --source / --tls-* 等，见 merchant-gateway/cli.ts）。
+    if (argv[0] === "merchant" && argv[1] === "gateway") {
+        return await runGatewayServe(argv.slice(2));
+    }
     let args;
     try {
         args = parseArgs(argv);