@harrylabsj/kiwi 0.7.15 → 0.7.17

package/dist/cli.d.ts

@@ -51,6 +51,10 @@ interface ParsedArgs {
     relogin: boolean;
     qrScale: number;
     noQr: boolean;
+    domain?: string;
+    check: boolean;
+    caddyfile?: string;
+    file?: string;
 }
 /** 导出供测试（审查 P2-L：--a2a flag 解析回归锁定）。 */
 export declare function parseArgs(argv: string[]): ParsedArgs;

package/dist/cli.js

@@ -27,7 +27,9 @@
  *   kiwi init|up|status|logs|down --dir <instance-dir>
  *                                           Managed-local product lifecycle.
  */
-import { existsSync, realpathSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { startA2aNode } from "./a2a/node.js";
@@ -55,11 +57,12 @@ 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 { 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 { merchantPublish } from "./product-publish.js";
 import { catalogServe } from "./product-catalog.js";
+import { extractPublicDomain, runMerchantSetupPublic, SetupPublicError, validatePublicDomain } from "./product-setup-public.js";
 const USAGE = `kiwi ${PRODUCT_VERSION} — commerce negotiation agent runtime
 
 Usage:
@@ -93,6 +96,8 @@ Usage:
 Product layer (product-strategy rev1.1 §10/§19):
   kiwi buyer --help                       Kiwi Buyer command tree
   kiwi merchant --help                    Kiwi Merchant command tree
+  kiwi setup-hermes                       One-click: wire kiwi-buyer-mcp into Hermes
+                                          (hermes mcp add + skills install)
   kiwi network --help                     Kiwi Network command tree
   kiwi demo [a|b]                         One-command local multi-merchant demo
                                           (Issue 13; 1 buyer + catalog + 3 merchants
@@ -155,6 +160,10 @@ export function parseArgs(argv) {
     let relogin = false;
     let qrScale = 1;
     let noQr = false;
+    let domain;
+    let check = false;
+    let caddyfile;
+    let file;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === "--profile") {
@@ -268,6 +277,18 @@ export function parseArgs(argv) {
         else if (arg === "--no-qr") {
             noQr = true;
         }
+        else if (arg === "--domain") {
+            domain = argv[++i];
+        }
+        else if (arg === "--check") {
+            check = true;
+        }
+        else if (arg === "--caddyfile") {
+            caddyfile = argv[++i];
+        }
+        else if (arg === "--file") {
+            file = argv[++i];
+        }
         else if (arg !== undefined && arg.startsWith("--profile=")) {
             profile = arg.slice("--profile=".length);
         }
@@ -289,6 +310,15 @@ export function parseArgs(argv) {
         else if (arg !== undefined && arg.startsWith("--data-dir=")) {
             dataDir = arg.slice("--data-dir=".length);
         }
+        else if (arg !== undefined && arg.startsWith("--domain=")) {
+            domain = arg.slice("--domain=".length);
+        }
+        else if (arg !== undefined && arg.startsWith("--caddyfile=")) {
+            caddyfile = arg.slice("--caddyfile=".length);
+        }
+        else if (arg !== undefined && arg.startsWith("--file=")) {
+            file = arg.slice("--file=".length);
+        }
         else if (arg !== undefined && !arg.startsWith("-")) {
             command.push(arg);
         }
@@ -311,6 +341,7 @@ export function parseArgs(argv) {
         relogin,
         qrScale,
         noQr,
+        check,
     };
     if (profile !== undefined)
         out.profile = profile;
@@ -354,6 +385,12 @@ export function parseArgs(argv) {
         out.port = port;
     if (catalogDb !== undefined)
         out.catalogDb = catalogDb;
+    if (domain !== undefined)
+        out.domain = domain;
+    if (caddyfile !== undefined)
+        out.caddyfile = caddyfile;
+    if (file !== undefined)
+        out.file = file;
     if (catalogHost !== undefined)
         out.catalogHost = catalogHost;
     return out;
@@ -370,6 +407,20 @@ function requireProfile(args) {
     }
     return loadProfile(args.profile);
 }
+/**
+ * 读取 profile：`--profile` 优先；缺省回退 `KIWI_DEFAULT_PROFILE` env 或
+ * `DEFAULT_PROFILE_PATH`（`kiwi merchant init` 写入的默认路径）。文件不存在 →
+ * fail-closed 提示先 init。供商家命令（start/publish/setup-public）参数化使用，
+ * 让第 4-5 步不带 `--profile`。
+ */
+function requireProfileOrDefault(args) {
+    if (args.profile)
+        return loadProfile(args.profile);
+    const fallback = process.env.KIWI_DEFAULT_PROFILE ?? DEFAULT_PROFILE_PATH;
+    if (existsSync(fallback))
+        return loadProfile(fallback);
+    throw new ProfileError(`未找到商家配置（${fallback}）——先运行 kiwi merchant init，或用 --profile <file> 指定`);
+}
 function printReportJsonl(report) {
     process.stdout.write(`${JSON.stringify(report)}\n`);
 }
@@ -555,11 +606,12 @@ export function resolveServeDataDir(dataDir, agentId) {
     return dataDir ?? path.resolve(".kiwi", "agents", agentId);
 }
 async function cmdAgentServe(args) {
-    const profile = requireProfile(args);
+    const profile = requireProfileOrDefault(args);
     if (profile.role !== "merchant") {
         process.stderr.write("kiwi agent serve 需要 merchant profile（role: merchant）\n");
         return EXIT.CONFIG;
     }
+    loadMerchantCredentials(); // 加载 init 写入的 credentials.env（KIWI_MERCHANT_TOKEN）
     const catalog = args.catalog ?? process.env.KIWI_CATALOG_URL ?? DEFAULT_CATALOG_URL;
     const merchantToken = process.env.KIWI_MERCHANT_TOKEN || "";
     // 审查 P1-09：serve 的初始 A2A 节点必须用稳定 dataDir——此前初始节点缺省走
@@ -567,11 +619,13 @@ async function cmdAgentServe(args) {
     // negotiation 可重开、已发 conditional offer 返回 offer_unknown。稳定目录
     // 让重启可恢复状态（resolveServeDataDir 见上）。
     const serveDataDir = resolveServeDataDir(args.dataDir, profile.agent_id);
+    const profilePublicUrl = profile.merchant_public?.public_url;
     let node = await startA2aNode({
         profile,
         catalog,
-        preferredPort: args.port,
+        preferredPort: args.port ?? profile.merchant_public?.a2a_port,
         dataDir: serveDataDir,
+        ...(profilePublicUrl ? { publicBaseUrl: `https://${profilePublicUrl}` } : {}),
         ...(merchantToken ? { ownerToken: merchantToken } : {}),
         ownerTokenSecret: process.env.KIWI_CATALOG_OWNER_TOKEN_SECRET,
     });
@@ -824,6 +878,9 @@ async function cmdBuyerInit(args) {
         ...(args.force ? { force: true } : {}),
     });
     printJson(report);
+    if (report.ok) {
+        process.stdout.write("✓ 商家配置完成。下一步：`kiwi merchant up` 上线（需先装 Caddy、DNS 指向服务器）；或 `kiwi merchant setup-public` 查看公网配置。\n");
+    }
     return report.ok ? EXIT.OK : EXIT.CONFIG;
 }
 /** `kiwi buyer search`（D4）：Product-first 搜索（M3 链路）。 */
@@ -890,6 +947,10 @@ async function routeMerchant(sub, args) {
         return await cmdMerchantInit(args);
     if (sub === "publish")
         return await cmdMerchantPublish(args);
+    if (sub === "setup-public")
+        return await cmdMerchantSetupPublic(args);
+    if (sub === "up")
+        return await cmdMerchantUp(args);
     if (sub === "listings")
         return notImplementedProduct("kiwi merchant listings", "D2");
     if (sub === "status")
@@ -921,9 +982,15 @@ async function cmdMerchantInit(args) {
     // --merchant-id / --name flag 优先，env 回退；TTY 下交互提示，缺省自动派生。
     let merchantId = args.merchantId ?? process.env.KIWI_MERCHANT_ID ?? "";
     let name = args.merchantName ?? process.env.KIWI_MERCHANT_NAME ?? "";
+    let publicUrl = "";
+    let merchantToken = "";
     if (process.stdin.isTTY) {
         merchantId = await promptLine(`merchant_id（回车自动生成${name !== "" ? `，建议 ${slugifyMerchantId(name)}` : ""}）: `, merchantId);
         name = await promptLine(`商家名称（回车用缺省）: `, name);
+        publicUrl = await promptLine("公网域名（可选，回车跳过；如 merchant.example.com）: ", "");
+        if (publicUrl !== "")
+            publicUrl = publicUrl.trim().toLowerCase();
+        merchantToken = await promptLine("商家令牌（从商家后台获取，可稍后设置；直接回车跳过）: ", "");
         // TTY 下可全回车：merchant_id 自动生成（避免固定名碰撞）。
         if (merchantId === "")
             merchantId = `merchant-${Math.random().toString(36).slice(2, 8)}`;
@@ -945,6 +1012,8 @@ async function cmdMerchantInit(args) {
     const report = await merchantInit({
         merchantName: name,
         ...(merchantId !== "" ? { merchantId } : {}),
+        ...(publicUrl !== "" ? { publicUrl } : {}),
+        ...(merchantToken !== "" ? { merchantToken } : {}),
         shoppingCliUrl: process.env.SHOPPING_CLI_URL ?? "http://127.0.0.1:8765",
         shoppingCliDb: process.env.SHOPPING_DB_PATH,
         catalogUrl: args.catalog ?? process.env.KIWI_CATALOG_URL ?? DEFAULT_CATALOG_URL,
@@ -965,27 +1034,35 @@ async function cmdMerchantInit(args) {
  * fail-closed：任一步失败 → 非零退出 + 分步报告，不假装全成功。
  */
 async function cmdMerchantPublish(args) {
-    const profile = requireProfile(args);
+    const profile = requireProfileOrDefault(args);
     if (profile.role !== "merchant") {
         process.stderr.write("kiwi merchant publish 需要 merchant profile（role: merchant）\n");
         return EXIT.CONFIG;
     }
-    const shoppingCliDb = args.shoppingCliDb ?? process.env.SHOPPING_DB_PATH;
-    if (!shoppingCliDb) {
-        process.stderr.write("--shopping-cli-db <path>（或 SHOPPING_DB_PATH）是必需的：shopping-cli 的 SQLite 数据库路径\n");
-        return EXIT.CONFIG;
+    loadMerchantCredentials(); // 加载 init 写入的 credentials.env（KIWI_MERCHANT_TOKEN）
+    // 缺省路径与 shopping-cli 的 DEFAULT_DB_PATH 一致——商家无需设置 SHOPPING_DB_PATH。
+    const shoppingCliDb = args.shoppingCliDb ?? process.env.SHOPPING_DB_PATH ?? DEFAULT_SHOPPING_DB_PATH;
+    // `--file <csv>`：先导入商品（shopping-cli import-csv-excel）再发布。
+    if (args.file !== undefined && args.file !== "") {
+        const imp = spawnSync("shopping-cli", ["import-csv-excel", "--file", args.file, "--merchant", profile.agent_id, "--format", "json"], { env: { ...process.env, SHOPPING_DB_PATH: shoppingCliDb }, stdio: "inherit" });
+        if (imp.status !== 0) {
+            process.stderr.write(`商品导入失败（shopping-cli import-csv-excel 退出码 ${imp.status ?? "?"}）——请检查 CSV 格式\n`);
+            return EXIT.CONFIG;
+        }
+        process.stdout.write(`已导入商品：${args.file}\n`);
     }
     if (!existsSync(shoppingCliDb)) {
-        process.stderr.write(`shopping-cli 数据库不存在：${shoppingCliDb}\n`);
+        process.stderr.write(`shopping-cli 数据库不存在：${shoppingCliDb}（先运行 shopping-cli import-csv-excel 导入商品）\n`);
         return EXIT.CONFIG;
     }
     const ownerTokenSecret = process.env.KIWI_CATALOG_OWNER_TOKEN_SECRET;
-    const merchantToken = process.env.KIWI_MERCHANT_TOKEN || "";
+    const merchantTokenEnv = profile.merchant_public?.merchant_token_env;
+    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 ?? 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,
@@ -1033,6 +1110,225 @@ async function cmdDemo(args) {
         return EXIT.TRANSIENT;
     }
 }
+/**
+ * `kiwi merchant setup-public`（D3）——公网 A2A 暴露引导向导。
+ * 检测公网 IP、检查域名 DNS、生成 Caddy 反代配置、输出启动与验证命令。
+ * well-known 文件由跑着的 `kiwi merchant start` 节点自动生成，商家无需手写。
+ */
+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 缺省一致
+    // 单一来源：--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) ?? "";
+    if (domain === "" && process.stdin.isTTY) {
+        domain = await promptLine("公网域名（如 merchant.example.com，TLS 证书就用它）: ", "");
+    }
+    if (domain === "") {
+        process.stderr.write("--domain <公网域名> 必填（TTY 下可交互输入）。例：kiwi merchant setup-public --domain merchant.example.com\n");
+        return EXIT.CONFIG;
+    }
+    let normalized;
+    try {
+        normalized = validatePublicDomain(domain);
+    }
+    catch (err) {
+        if (err instanceof SetupPublicError) {
+            process.stderr.write(`${err.message}\n`);
+            return EXIT.CONFIG;
+        }
+        throw err;
+    }
+    const caddyfilePath = args.caddyfile ?? "Caddyfile.kiwi";
+    try {
+        const report = await runMerchantSetupPublic({
+            domain: normalized,
+            port,
+            caddyfilePath,
+            merchantAgentId: profile.agent_id,
+            profilePath: args.profile,
+            checkNow: args.check,
+        });
+        process.stdout.write(`merchant ${report.merchantAgentId} · 端口 ${report.port} · 域名 ${report.domain}\n`);
+        process.stdout.write(`公网 IP：${report.publicIp ?? "（未能自动检测，请手动确认）"}\n`);
+        const dnsMsg = {
+            ok: `DNS 已指向本机（${report.dns.resolved}）`,
+            mismatch: `DNS 解析到 ${report.dns.resolved}，与公网 IP ${report.dns.expected} 不一致——请到域名服务商把 ${report.domain} 的 A 记录指向 ${report.dns.expected}`,
+            unresolved: `域名 ${report.domain} 当前无法解析——请先到域名服务商添加 A 记录指向服务器公网 IP`,
+            skipped: `无法对比 DNS（未检测到公网 IP），请手动确认 ${report.domain} 的 A 记录指向本机`,
+        };
+        process.stdout.write(`DNS：${dnsMsg[report.dns.status]}\n`);
+        process.stdout.write(`已写入 ${report.caddyfilePath}：\n${report.caddyfile}`);
+        for (const line of report.instructions)
+            process.stdout.write(`${line}\n`);
+        if (report.check !== null) {
+            const status = report.check.httpStatus;
+            process.stdout.write(`\n--check：${status === 200 ? "✓" : status === null ? "✗ 无法连接" : `✗ HTTP ${status}`} ${report.check.url}\n`);
+        }
+        return EXIT.OK;
+    }
+    catch (err) {
+        if (err instanceof SetupPublicError) {
+            process.stderr.write(`${err.message}\n`);
+            return EXIT.CONFIG;
+        }
+        throw err;
+    }
+}
+/**
+ * `kiwi merchant up`（D3）——一条命令上线：setup-public（生成 Caddyfile）→ 起 Caddy
+ * 反代（子进程）→ 起 A2A 节点 → 退出时清理 Caddy。把第 4 步三命令合成一个。
+ */
+async function cmdMerchantUp(args) {
+    const profile = requireProfileOrDefault(args);
+    if (profile.role !== "merchant") {
+        process.stderr.write("kiwi merchant up 需要 merchant profile（role: merchant）\n");
+        return EXIT.CONFIG;
+    }
+    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) ?? "";
+    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 caddyfilePath = args.caddyfile ?? "Caddyfile.kiwi";
+    // ── setup-public：检测 IP / DNS 检查 / 生成 Caddyfile（幂等）──
+    await runMerchantSetupPublic({
+        domain,
+        port,
+        caddyfilePath,
+        merchantAgentId: profile.agent_id,
+        profilePath: args.profile,
+    });
+    process.stdout.write(`[merchant up] 域名 ${domain} · 端口 ${port} · Caddyfile ${caddyfilePath}\n`);
+    // ── 检查 Caddy 是否安装（fail-closed）──
+    const caddyOk = spawnSync("caddy", ["version"], { stdio: "ignore" }).status === 0;
+    if (!caddyOk) {
+        process.stderr.write("未检测到 Caddy（反代 + TLS）。请先安装：`brew install caddy`（或 https://caddyserver.com/download），然后重试。\n");
+        return EXIT.CONFIG;
+    }
+    // ── 起 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 merchantToken = process.env.KIWI_MERCHANT_TOKEN || "";
+    const serveDataDir = resolveServeDataDir(args.dataDir, profile.agent_id);
+    let node = await startA2aNode({
+        profile,
+        catalog,
+        preferredPort: port,
+        dataDir: serveDataDir,
+        ...(domain ? { publicBaseUrl: `https://${domain}` } : {}),
+        ...(merchantToken ? { ownerToken: merchantToken } : {}),
+        ownerTokenSecret: process.env.KIWI_CATALOG_OWNER_TOKEN_SECRET,
+    });
+    process.stdout.write(`[merchant up] A2A server: ${node.agentCardUrl}（local ${node.url}）· catalog: ${node.catalogAgentId ?? "?"}\n`);
+    process.stdout.write("[merchant up] 已上线 — Ctrl+C to stop（会同时停掉 Caddy 与节点）\n");
+    const shutdown = async () => {
+        await node?.stop().catch(() => undefined);
+        node = null;
+        caddy.kill(); // SIGTERM → Caddy 优雅退出
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    await new Promise(() => { });
+    return EXIT.OK;
+}
+/**
+ * `kiwi setup-hermes`（买家侧）——一键把 Kiwi 买家连接器接入 Hermes：
+ * 配置 kiwi-buyer-mcp MCP server + 安装 kiwi-buyer skill。之后 Hermes 重启
+ * 即可调用 9 个采购工具。等价于手动执行：
+ *   hermes mcp add kiwi-buyer-mcp --command node --args <cli> mcp serve ...
+ *   hermes skills install <SKILL.md URL>
+ */
+async function cmdSetupHermes() {
+    // 1. 检查 Hermes CLI
+    const hermesOk = spawnSync("hermes", ["--version"], { stdio: "ignore" }).status === 0;
+    if (!hermesOk) {
+        process.stderr.write("未检测到 Hermes CLI（hermes）——请先安装 Hermes，再运行本命令。\n");
+        return EXIT.CONFIG;
+    }
+    // 2. 本机 kiwi cli 路径（dist/cli.js）、principal、db 路径、skill 落盘路径
+    const cliPath = fileURLToPath(import.meta.url);
+    let username = "";
+    try {
+        username = userInfo().username;
+    }
+    catch {
+        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 skillPath = path.join(homedir(), ".hermes", "skills", "kiwi-buyer", "SKILL.md");
+    const configured = [];
+    const already = [];
+    // 3. MCP server：已存在则跳过，否则添加（避免 overwrite 交互提示）
+    const mcpList = spawnSync("hermes", ["mcp", "list"], { encoding: "utf-8" });
+    const mcpExists = (mcpList.stdout ?? "").includes("kiwi-buyer-mcp");
+    if (mcpExists) {
+        already.push("MCP server kiwi-buyer-mcp");
+    }
+    else {
+        process.stdout.write("[setup-hermes] 配置 kiwi-buyer-mcp MCP server ...\n");
+        const mcp = spawnSync("hermes", [
+            "mcp",
+            "add",
+            "kiwi-buyer-mcp",
+            "--command",
+            "node",
+            "--args",
+            cliPath,
+            "mcp",
+            "serve",
+            "--db",
+            dbPath,
+            "--principal",
+            `hermes:${username}`,
+            "--agent",
+            "buyer-agent:hermes",
+        ], { stdio: "inherit" });
+        if (mcp.status !== 0) {
+            process.stderr.write(`hermes mcp add 失败（退出码 ${mcp.status ?? "?"}）\n`);
+            return EXIT.CONFIG;
+        }
+        configured.push("MCP server kiwi-buyer-mcp");
+    }
+    // 4. kiwi-buyer skill：已存在则跳过；否则 hermes install（失败则直接 fetch 落盘兜底）
+    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");
+            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. 报告
+    for (const item of already)
+        process.stdout.write(`  ✓ ${item} 已配置，跳过\n`);
+    for (const item of configured)
+        process.stdout.write(`  ✓ ${item} 已配置\n`);
+    process.stdout.write("✓ Kiwi 已接入 Hermes。请重启 Hermes（或开新会话），然后直接说出采购需求（如「帮我买 200 个 USB-C 扩展坞，7 天内到」）。\n");
+    return EXIT.OK;
+}
 function notImplementedProduct(name, target) {
     process.stderr.write(`${name} 尚未实现（产品层完成定义 ${target}，见 docs/kiwi-product-layer-refactor-rev1.1.md §19）。\n`);
     return EXIT.CONFIG;
@@ -1087,6 +1383,8 @@ export async function main(argv = process.argv.slice(2)) {
             return await routeBuyer(sub, args);
         if (cmd === "merchant")
             return await routeMerchant(sub, args);
+        if (cmd === "setup-hermes")
+            return await cmdSetupHermes();
         if (cmd === "network")
             return await routeNetwork(sub);
         if (cmd === "demo")