@manturhub/cli 0.7.0 → 0.8.1

package/bin/cli.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
-import { saveConfig, loadConfig } from "../lib/config.js";
+import { getBaseUrl, saveConfig, loadConfig } from "../lib/config.js";
 import { apiFetch, pollJob } from "../lib/api.js";
-import { runMcpBridge } from "../lib/mcp.js";
-import { runInit, runMcpInstall } from "../lib/setup.js";
+import { runInit } from "../lib/setup.js";
 import { skillLs, skillAdd } from "../lib/skill-install.js";
 import { suiteLs, suiteInstall } from "../lib/suite-install.js";
 import { loginViaBrowser } from "../lib/login-link.js";
 import { maybeNotifyUpdate } from "../lib/update-check.js";
-import { readFileSync } from "node:fs";
+import { createReadStream, readFileSync, statSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join, basename, extname } from "node:path";
+import { parseDynamicParams, validateParams } from "../lib/params.js";
 
 // 本地文件 → MIME(presign 只接受 image/audio/video)
 const MIME_BY_EXT = {
@@ -31,8 +31,56 @@ const args = process.argv.slice(2);
 const cmd = args[0];
 
 function getFlag(name, def) {
+  const inline = args.find((arg) => arg.startsWith(`--${name}=`));
+  if (inline) return inline.slice(name.length + 3);
   const i = args.indexOf(`--${name}`);
-  return i >= 0 && args[i + 1] !== undefined ? args[i + 1] : def;
+  return i >= 0 && args[i + 1] !== undefined && !args[i + 1].startsWith("--")
+    ? args[i + 1]
+    : def;
+}
+
+const hasFlag = (name) => args.includes(`--${name}`) || args.some((arg) => arg.startsWith(`--${name}=`));
+
+function assertFlags(tokens, { value = [], boolean = [] } = {}) {
+  const valueFlags = new Set(value);
+  const booleanFlags = new Set(boolean);
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (!token?.startsWith("--")) throw new Error(`无法识别的位置参数: ${token}`);
+    const equals = token.indexOf("=");
+    const name = token.slice(2, equals > 2 ? equals : undefined);
+    if (booleanFlags.has(name)) {
+      if (equals > 2) throw new Error(`选项 --${name} 不接受值`);
+      continue;
+    }
+    if (!valueFlags.has(name)) throw new Error(`未知选项: --${name}`);
+    if (equals > 2) {
+      if (!token.slice(equals + 1)) throw new Error(`参数 --${name} 缺少值`);
+      continue;
+    }
+    const next = tokens[i + 1];
+    if (next === undefined || next.startsWith("--")) throw new Error(`参数 --${name} 缺少值`);
+    i++;
+  }
+}
+
+function assertRunControlFlags(tokens) {
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token === "--no-wait" || token.startsWith("--json=") || token.startsWith("--json-file=")) continue;
+    if (token === "--json" || token === "--json-file") {
+      const value = tokens[i + 1];
+      if (value === undefined || value.startsWith("--")) throw new Error(`参数 ${token} 缺少值`);
+      i++;
+      continue;
+    }
+    throw new Error(`未知选项: ${token}`);
+  }
+}
+
+function usdFor(dumplings) {
+  const value = Number(dumplings);
+  return Number.isFinite(value) ? `$${(value * 0.01).toFixed(2)} USD` : "-";
 }
 
 const HELP = `manturhub — ManturHub 算子广场 CLI  v${VERSION}
@@ -40,83 +88,114 @@ const HELP = `manturhub — ManturHub 算子广场 CLI  v${VERSION}
 用法:
   manturhub login                     浏览器授权登录（生成链接→登录创建 Key→自动导入，推荐）
   manturhub login --key sk-xxx        手动配置 API Key（存 ~/.manturhub/config.json）
-  manturhub ls [--cat <分类>]         列出上线算子（分类: text/image/video/audio/data）
-  manturhub describe <算子ID>         查看算子入参字段（喂参数前先看）
+  manturhub login --key-stdin         从 stdin 安全读取 API Key
+  manturhub ls [--cat <分类>] [--json]  列出上线算子（无需登录）
+  manturhub describe <算子ID> [--json]  查看算子入参字段（无需登录）
+  manturhub quote <算子ID>            查询实时计费公式（不要使用 Skill 内的历史价格）
   manturhub run <算子ID> --json '{}'  调用算子（异步算子自动轮询到出结果；--no-wait 只拿 job_id）
+  manturhub run <算子ID> --json-file x.json  从文件读参数（prompt 来自配方/用户时更安全）
   manturhub upload <本地文件>         上传图片/音频/视频 → 公网 URL（喂算子前先转换本地文件）
   manturhub status <poll_url>         查异步任务状态（配合 run --no-wait）
   manturhub balance                   查询馒头余额
   manturhub init                      装「ManturHub 使用 skill」+ 写 agent 引导（推荐：让 agent 会用算子）
   manturhub skill ls                  列出平台 Skill（业务成品流程，如爆款复刻）
-  manturhub skill add <slug>          安装 Skill 到 ~/.claude/skills/<slug>/
+  manturhub skill add <slug> [--client claude-code|codex|all]
+                                      安装 Skill 到指定 Agent
   manturhub suite ls                  列出 Agent 套件（多角色团队工作区，给 Agent 配一整个团队）
-  manturhub suite install <slug>      安装套件为工作目录 ./<slug>/（自动写入 API Key，任意 Agent 打开即用）
+  manturhub suite install <slug>      安装套件为工作目录 ./<slug>/（不复制 API Key）
   manturhub recipe [关键词] [--cat x] 搜配方（已验证创作的效果+可复现参数；分类 video/image/script）
   manturhub recipe get <配方ID>       看配方提示词模板与调用参数（换掉 {占位符} 即可复刻）
-  manturhub mcp [--scope <域>]        启动 stdio MCP server（可选，给 MCP 原生客户端）
-  manturhub mcp-install [--client x]  把 MCP 接进客户端（可选：claude-code/codex/cursor/claude-desktop/all）
   manturhub help | --version
 
 环境变量:
   MANTURHUB_KEY    API Key（优先于配置文件）
-  MANTURHUB_BASE   网关地址（默认 https://hub.mantur.cn）
+  MANTURHUB_BASE   网关地址（默认 ${getBaseUrl()}）
 
-推荐接入（CLI + skill，最稳，无需 MCP）:
+推荐接入（CLI + Skill）:
   npm i -g @manturhub/cli
-  manturhub login --key sk-xxx
+  manturhub login
   manturhub init                       # 装使用 skill + 写引导，之后 agent 直接用 manturhub run/ls/upload 调算子
 `;
 
 async function main() {
   maybeNotifyUpdate(VERSION);
+  if (cmd && !["help", "--help", "-h"].includes(cmd) && args.slice(1).some((arg) => arg === "--help" || arg === "-h")) {
+    console.log(HELP);
+    return;
+  }
   switch (cmd) {
     case "login": {
-      const key = getFlag("key");
+      try {
+        assertFlags(args.slice(1), { value: ["key"], boolean: ["key-stdin"] });
+      } catch (error) {
+        console.error(error.message);
+        process.exit(1);
+      }
+      if ((hasFlag("key") && !getFlag("key")) || (hasFlag("key-stdin") && getFlag("key-stdin"))) {
+        console.error("用法: manturhub login --key sk-xxx   或   manturhub login --key-stdin");
+        process.exit(1);
+      }
+      const keyFromFlag = getFlag("key");
+      const useKeyStdin = hasFlag("key-stdin");
+      const keyFromStdin = useKeyStdin ? readFileSync(0, "utf8").trim() : null;
+      if (useKeyStdin && !keyFromStdin) {
+        console.error("stdin 中没有 API Key");
+        process.exit(1);
+      }
+      if (keyFromFlag && keyFromStdin) {
+        console.error("--key 和 --key-stdin 只能使用一个");
+        process.exit(1);
+      }
+      const key = keyFromFlag || keyFromStdin;
       if (!key) {
         // 无 --key → 浏览器授权流:生成链接,登录创建 key 后自动导入
         await loginViaBrowser();
         break;
       }
-      const cfg = loadConfig();
-      cfg.key = key;
-      saveConfig(cfg);
       const r = await apiFetch("/api/v1/me", { key });
       if (r.ok) {
+        const cfg = loadConfig();
+        cfg.key = key;
+        saveConfig(cfg);
         console.log(
-          `✓ Key 已保存。账号: ${r.json.email || "-"}   余额: ${r.json.balance ?? "-"} 馒头`
+          `✓ Key 已验证并保存。账号: ${r.json.email || "-"}   余额: ${usdFor(r.json.balance)}（${r.json.balance ?? "-"} 馒头）`
         );
       } else {
-        console.log(
-          `✓ Key 已保存，但验证失败（HTTP ${r.status}）。请确认 key 是否正确、是否已激活。`
-        );
+        console.error(`Key 验证失败（HTTP ${r.status}），未修改本地配置。请确认 key 是否正确、是否已激活。`);
+        process.exit(1);
       }
       break;
     }
 
-    case "mcp": {
-      await runMcpBridge({ scope: getFlag("scope", "manturhub") });
-      break;
-    }
-
     case "init": {
       runInit();
       break;
     }
 
-    case "mcp-install": {
-      runMcpInstall(getFlag("client"));
-      break;
-    }
-
     case "ls": {
+      try {
+        assertFlags(args.slice(1), { value: ["cat"], boolean: ["json"] });
+      } catch (error) {
+        console.error(error.message);
+        process.exit(1);
+      }
       const cat = getFlag("cat");
-      const r = await apiFetch("/api/v1/operators?status=online");
+      const cats = new Set(["text", "image", "video", "audio", "data"]);
+      if (cat && !cats.has(cat)) {
+        console.error(`未知分类: ${cat}（可选: ${[...cats].join(" | ")}）`);
+        process.exit(1);
+      }
+      const r = await apiFetch("/api/v1/operators?status=online", { auth: "optional" });
       if (!r.ok) {
         console.error(`列表获取失败（HTTP ${r.status}）`);
         process.exit(1);
       }
       let ops = r.json.operators || r.json || [];
       if (cat) ops = ops.filter((o) => o.cat === cat);
+      if (hasFlag("json")) {
+        console.log(JSON.stringify({ operators: ops }, null, 2));
+        break;
+      }
       console.log(`ManturHub 上线算子（${ops.length} 个）:\n`);
       for (const o of ops) {
         console.log(`  ${o.id.padEnd(26)} ${o.name}   [${o.cat}]`);
@@ -132,12 +211,22 @@ async function main() {
         console.error("用法: manturhub describe <算子ID>   (查看入参字段)");
         process.exit(1);
       }
-      const r = await apiFetch(`/api/v1/operators/${encodeURIComponent(op)}`);
+      try {
+        assertFlags(args.slice(2), { boolean: ["json"] });
+      } catch (error) {
+        console.error(error.message);
+        process.exit(1);
+      }
+      const r = await apiFetch(`/api/v1/operators/${encodeURIComponent(op)}`, { auth: "optional" });
       if (!r.ok) {
         console.error(`获取失败（HTTP ${r.status}）: ${op}`);
         process.exit(1);
       }
       const o = r.json.operator || r.json;
+      if (hasFlag("json")) {
+        console.log(JSON.stringify(o, null, 2));
+        break;
+      }
       console.log(`\n${o.id}  ${o.name || ""}   [${o.cat || "-"}] · ${o.status || "-"}`);
       if (o.description) console.log(o.description);
       const ps = o.params_schema || (o.meta && o.meta.params_schema);
@@ -150,12 +239,45 @@ async function main() {
         }
         if (ps.async) console.log(`\n异步算子：run 默认自动轮询到出结果（--no-wait 只拿 task_id）`);
       } else {
-        console.log(`\n（该算子未声明入参 schema，详见 https://hub.mantur.cn/marketplace/${o.id}）`);
+        console.log(`\n（该算子未声明入参 schema，详见 ${getBaseUrl()}/marketplace/${o.id}）`);
       }
       console.log(`\n调用: manturhub run ${o.id} --json '{...}'`);
       break;
     }
 
+    case "quote": {
+      const op = args[1];
+      if (!op || op.startsWith("--")) {
+        console.error("用法: manturhub quote <算子ID>");
+        process.exit(1);
+      }
+      try {
+        assertFlags(args.slice(2), { boolean: ["json"] });
+      } catch (error) {
+        console.error(error.message);
+        process.exit(1);
+      }
+      const r = await apiFetch(`/api/v1/operators/${encodeURIComponent(op)}/quote`, { auth: "optional" });
+      if (!r.ok) {
+        console.error(`查询价格失败（HTTP ${r.status}）: ${JSON.stringify(r.json)}`);
+        process.exit(1);
+      }
+      if (args.includes("--json")) {
+        const floor = Number(r.json.floor);
+        console.log(
+          JSON.stringify(
+            Number.isFinite(floor) ? { ...r.json, floor_usd: floor * 0.01 } : r.json,
+            null,
+            2
+          )
+        );
+      } else {
+        console.log(`${r.json.operatorId || op}: ${r.json.formula || "详见算子页"}`);
+        if (r.json.floor !== undefined) console.log(`最低扣费: ${usdFor(r.json.floor)}（${r.json.floor} 馒头）`);
+      }
+      break;
+    }
+
     case "run": {
       const op = args[1];
       if (!op || op.startsWith("--")) {
@@ -164,7 +286,31 @@ async function main() {
       }
       let body = {};
       const jsonArg = getFlag("json");
-      if (jsonArg) {
+      const jsonFile = getFlag("json-file");
+      if ((hasFlag("json") && !jsonArg) || (hasFlag("json-file") && !jsonFile)) {
+        console.error("--json / --json-file 需要非空值");
+        process.exit(1);
+      }
+      if (jsonArg && jsonFile) {
+        console.error("--json 和 --json-file 只能使用一个");
+        process.exit(1);
+      }
+      if (jsonArg || jsonFile) {
+        try {
+          assertRunControlFlags(args.slice(2));
+        } catch (error) {
+          console.error(error.message);
+          process.exit(1);
+        }
+      }
+      if (jsonFile) {
+        try {
+          body = JSON.parse(readFileSync(jsonFile, "utf8"));
+        } catch (e) {
+          console.error(`--json-file 读取失败或不是合法 JSON：${e.message}`);
+          process.exit(1);
+        }
+      } else if (jsonArg) {
         try {
           body = JSON.parse(jsonArg);
         } catch {
@@ -172,15 +318,29 @@ async function main() {
           process.exit(1);
         }
       } else {
-        for (let i = 2; i < args.length; i += 2) {
-          if (args[i] && args[i].startsWith("--") && args[i + 1] !== undefined) {
-            body[args[i].slice(2)] = args[i + 1];
-          }
+        try {
+          body = parseDynamicParams(args.slice(2));
+        } catch (error) {
+          console.error(error.message);
+          process.exit(1);
         }
       }
+      const detail = await apiFetch(`/api/v1/operators/${encodeURIComponent(op)}`, { auth: "optional" });
+      if (!detail.ok) {
+        console.error(`参数校验前无法读取算子 schema（HTTP ${detail.status}），已停止调用避免误扣费`);
+        process.exit(1);
+      }
+      const operator = detail.json.operator || detail.json;
+      const schema = operator.params_schema || operator.meta?.params_schema;
+      try {
+        body = validateParams(body, schema, { coerceStrings: !jsonArg && !jsonFile });
+      } catch (error) {
+        console.error(`参数校验失败: ${error.message}`);
+        process.exit(1);
+      }
       const r = await apiFetch(
         `/api/v1/operators/${encodeURIComponent(op)}/invoke`,
-        { method: "POST", body }
+        { method: "POST", body, timeoutMs: 120000 }
       );
       // 异步算子(返回 poll_url)默认自动轮询到出结果;--no-wait 只拿 job_id。
       const pollUrl = r.ok && r.json && r.json.poll_url;
@@ -210,6 +370,12 @@ async function main() {
         console.error("用法: manturhub upload <本地文件>   (图片/音频/视频 → 公网 URL)");
         process.exit(1);
       }
+      try {
+        assertFlags(args.slice(2));
+      } catch (error) {
+        console.error(error.message);
+        process.exit(1);
+      }
       const mime = mimeFromFile(file);
       if (!mime) {
         console.error(
@@ -217,16 +383,17 @@ async function main() {
         );
         process.exit(1);
       }
-      let buf;
+      let stat;
       try {
-        buf = readFileSync(file);
+        stat = statSync(file);
+        if (!stat.isFile()) throw new Error("不是普通文件");
       } catch (e) {
         console.error(`读不到文件: ${file}（${e.message}）`);
         process.exit(1);
       }
       const p = await apiFetch("/api/v1/uploads/presign", {
         method: "POST",
-        body: { filename: basename(file), size: buf.length, mime },
+        body: { filename: basename(file), size: stat.size, mime },
       });
       if (!p.ok || !p.json || !p.json.put_url) {
         console.error(`presign 失败（HTTP ${p.status}）: ${JSON.stringify(p.json)}`);
@@ -234,8 +401,10 @@ async function main() {
       }
       const put = await fetch(p.json.put_url, {
         method: "PUT",
-        headers: { "Content-Type": mime },
-        body: buf,
+        headers: { "Content-Type": mime, "Content-Length": String(stat.size) },
+        body: createReadStream(file),
+        duplex: "half",
+        signal: AbortSignal.timeout(10 * 60 * 1000),
       });
       if (!put.ok) {
         console.error(`上传到存储失败（HTTP ${put.status}）`);
@@ -251,30 +420,59 @@ async function main() {
         console.error("用法: manturhub status <poll_url>   (poll_url 来自 run --no-wait 的返回)");
         process.exit(1);
       }
-      const r = await apiFetch(pu.startsWith("/") ? pu : "/" + pu);
+      try {
+        assertFlags(args.slice(2));
+      } catch (error) {
+        console.error(error.message);
+        process.exit(1);
+      }
+      const r = await apiFetch(pu);
       console.log(JSON.stringify(r.json, null, 2));
       if (!r.ok) process.exit(1);
       break;
     }
 
     case "balance": {
+      try {
+        assertFlags(args.slice(1), { boolean: ["json"] });
+      } catch (error) {
+        console.error(error.message);
+        process.exit(1);
+      }
       const r = await apiFetch("/api/v1/me");
       if (!r.ok) {
         console.error(`查询失败（HTTP ${r.status}）`);
         process.exit(1);
       }
       console.log(
-        `馒头余额: ${r.json.balance ?? "-"}   账号: ${r.json.email || "-"}`
+        hasFlag("json")
+          ? JSON.stringify({ ...r.json, balance_usd: Number(r.json.balance) * 0.01 }, null, 2)
+          : `余额: ${usdFor(r.json.balance)}（${r.json.balance ?? "-"} 馒头）   账号: ${r.json.email || "-"}`
       );
       break;
     }
 
     case "skill": {
       const sub = args[1];
-      if (sub === "ls" || sub === "list") await skillLs();
-      else if (sub === "add" || sub === "install") await skillAdd(args[2]);
+      if (sub === "ls" || sub === "list") {
+        try {
+          assertFlags(args.slice(2), { boolean: ["json"] });
+        } catch (error) {
+          console.error(error.message);
+          process.exit(1);
+        }
+        await skillLs({ json: hasFlag("json") });
+      } else if (sub === "add" || sub === "install") {
+        try {
+          assertFlags(args.slice(3), { value: ["client"] });
+        } catch (error) {
+          console.error(error.message);
+          process.exit(1);
+        }
+        await skillAdd(args[2], getFlag("client", "claude-code"));
+      }
       else {
-        console.error("用法: manturhub skill ls   |   manturhub skill add <slug>");
+        console.error("用法: manturhub skill ls   |   manturhub skill add <slug> [--client claude-code|codex|all]");
         process.exit(1);
       }
       break;
@@ -283,8 +481,22 @@ async function main() {
     case "suite":
     case "suites": {
       const sub = args[1];
-      if (sub === "ls" || sub === "list" || sub === undefined) await suiteLs();
-      else if (sub === "install" || sub === "add") await suiteInstall(args[2], args[3]);
+      if (sub === "ls" || sub === "list" || sub === undefined) {
+        try {
+          assertFlags(args.slice(sub === undefined ? 1 : 2), { boolean: ["json"] });
+        } catch (error) {
+          console.error(error.message);
+          process.exit(1);
+        }
+        await suiteLs({ json: hasFlag("json") });
+      }
+      else if (sub === "install" || sub === "add") {
+        if (args.length > 4 || args[3]?.startsWith("--")) {
+          console.error("用法: manturhub suite install <slug> [目录]");
+          process.exit(1);
+        }
+        await suiteInstall(args[2], args[3]);
+      }
       else {
         console.error("用法: manturhub suite ls   |   manturhub suite install <slug> [目录]");
         process.exit(1);
@@ -301,36 +513,54 @@ async function main() {
           console.error("用法: manturhub recipe get <配方ID>");
           process.exit(1);
         }
-        const r = await apiFetch(`/api/v1/recipes/${encodeURIComponent(slug)}`);
+        try {
+          assertFlags(args.slice(3), { boolean: ["json"] });
+        } catch (error) {
+          console.error(error.message);
+          process.exit(1);
+        }
+        const r = await apiFetch(`/api/v1/recipes/${encodeURIComponent(slug)}`, { auth: "optional" });
         if (!r.ok) {
           console.error(`获取失败（HTTP ${r.status}）: ${slug}`);
           process.exit(1);
         }
         const d = r.json;
+        if (args.includes("--json")) {
+          console.log(JSON.stringify(d, null, 2));
+          break;
+        }
         console.log(`\n${d.title}  [${d.cat}] · 复刻 ${d.cost_estimate}`);
         console.log(`${d.summary}\n`);
         if (d.sample_url) {
           const su = d.sample_url.startsWith("http")
             ? d.sample_url
-            : `https://hub.mantur.cn${d.sample_url}`;
+            : `${getBaseUrl()}${d.sample_url}`;
           console.log(`效果样片: ${su}`);
         }
-        console.log(`配方页:   https://hub.mantur.cn/recipes/${d.slug}\n`);
+        console.log(`配方页:   ${getBaseUrl()}/recipes/${d.slug}\n`);
         if (d.prompt_template) console.log(`提示词模板:\n${d.prompt_template}\n`);
-        console.log("调用（把 {占位符} 换成用户内容后执行）:");
-        console.log(`manturhub run ${d.operator_id} --json '${JSON.stringify(d.params_json || {})}'`);
+        console.log("结构化参数（把 {占位符} 换成用户内容）:");
+        console.log(JSON.stringify(d.params_json || {}, null, 2));
+        console.log("\n安全执行：将每步 params 写入 JSON 文件，再运行 `manturhub run <算子ID> --json-file <文件>`。");
         if (d.sample_text) console.log(`\n效果节选:\n${d.sample_text}`);
         break;
       }
       // manturhub recipe [ls|search] [关键词] [--cat video|image|script]
-      const kwArg =
-        sub && !["ls", "list", "search"].includes(sub) && !sub.startsWith("--")
-          ? sub
-          : args[2] && !args[2].startsWith("--")
-            ? args[2]
-            : "";
+      const listArgs = args.slice(1);
+      let cursor = ["ls", "list", "search"].includes(listArgs[0]) ? 1 : 0;
+      const kwArg = listArgs[cursor] && !listArgs[cursor].startsWith("--") ? listArgs[cursor++] : "";
       const cat = getFlag("cat");
-      const r = await apiFetch(`/api/v1/recipes${cat ? `?cat=${encodeURIComponent(cat)}` : ""}`);
+      try {
+        assertFlags(listArgs.slice(cursor), { value: ["cat"], boolean: ["json"] });
+      } catch (error) {
+        console.error(error.message);
+        process.exit(1);
+      }
+      if (cat && !new Set(["video", "image", "script"]).has(cat)) {
+        console.error(`未知配方分类: ${cat}（可选: video | image | script）`);
+        process.exit(1);
+      }
+      const r = await apiFetch(`/api/v1/recipes${cat ? `?cat=${encodeURIComponent(cat)}` : ""}`, { auth: "optional" });
       if (!r.ok) {
         console.error(`配方列表获取失败（HTTP ${r.status}）`);
         process.exit(1);
@@ -342,12 +572,16 @@ async function main() {
           `${x.title}${x.summary}${(x.tags || []).join(",")}`.toLowerCase().includes(k)
         );
       }
+      if (hasFlag("json")) {
+        console.log(JSON.stringify({ recipes: list }, null, 2));
+        break;
+      }
       console.log(`ManturHub 配方（${list.length} 个）:\n`);
       for (const x of list) {
         console.log(`  ${x.slug.padEnd(32)} [${x.cat}] ${x.title} · 复刻 ${x.cost_estimate}`);
       }
       console.log(
-        `\n用 \`manturhub recipe get <配方ID>\` 看提示词模板与调用参数；挑选体验更好的网页版: https://hub.mantur.cn/recipes`
+        `\n用 \`manturhub recipe get <配方ID>\` 看提示词模板与调用参数；挑选体验更好的网页版: ${getBaseUrl()}/recipes`
       );
       break;
     }

package/lib/api.js

@@ -1,21 +1,56 @@
 import { getKey, getBaseUrl } from "./config.js";
 
-// Thin REST client against the ManturHub gateway. Every call carries x-api-key.
-export async function apiFetch(path, { method = "GET", body, key } = {}) {
-  const apiKey = key || getKey();
-  if (!apiKey) {
+// Thin REST client against the ManturHub gateway. Public discovery calls may omit auth.
+export async function apiFetch(
+  path,
+  { method = "GET", body, key, auth = "required", timeoutMs = 30000 } = {}
+) {
+  const apiKey = key === undefined ? getKey() : key;
+  if (auth === "required" && !apiKey) {
     throw new Error(
-      "未配置 API Key。运行 `manturhub login --key sk-xxx`，或设置环境变量 MANTURHUB_KEY。"
+      "未配置 API Key。运行 `manturhub login`，或设置环境变量 MANTURHUB_KEY。"
     );
   }
-  const res = await fetch(getBaseUrl() + path, {
-    method,
-    headers: {
-      "x-api-key": apiKey,
-      ...(body ? { "Content-Type": "application/json" } : {}),
-    },
-    body: body ? JSON.stringify(body) : undefined,
-  });
+  const base = new URL(getBaseUrl());
+  const url = new URL(path, base.href.endsWith("/") ? base.href : base.href + "/");
+  if (url.origin !== base.origin) {
+    throw new Error(`拒绝向 ManturHub 之外的地址发送请求: ${url.origin}`);
+  }
+  const request = (includeKey) =>
+    fetch(url, {
+      method,
+      headers: {
+        ...(includeKey && apiKey ? { "x-api-key": apiKey } : {}),
+        ...(body ? { "Content-Type": "application/json" } : {}),
+      },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  const requestWithRetry = async (includeKey) => {
+    const attempts = method === "GET" ? 2 : 1;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+      try {
+        const response = await request(includeKey);
+        const retryable = [429, 502, 503, 504].includes(response.status);
+        if (!retryable || attempt === attempts) return response;
+        const retryAfterHeader = response.headers.get("retry-after");
+        const retryAfter = retryAfterHeader === null ? Number.NaN : Number(retryAfterHeader);
+        await response.body?.cancel();
+        await new Promise((resolve) =>
+          setTimeout(resolve, Number.isFinite(retryAfter) ? Math.min(retryAfter * 1000, 10000) : 250)
+        );
+      } catch (error) {
+        if (attempt === attempts) throw error;
+        await new Promise((resolve) => setTimeout(resolve, 250));
+      }
+    }
+  };
+  let res = await requestWithRetry(true);
+  // An expired local key must not block public discovery. Retry only safe optional GETs.
+  if (auth === "optional" && method === "GET" && apiKey && res.status === 401) {
+    await res.body?.cancel();
+    res = await requestWithRetry(false);
+  }
   const text = await res.text();
   let json;
   try {
@@ -33,7 +68,7 @@ export async function pollJob(pollUrl, { intervalMs = 8000, maxMs = 1200000, onT
   const start = Date.now();
   let last = null;
   while (Date.now() - start < maxMs) {
-    const r = await apiFetch(pollUrl);
+    const r = await apiFetch(pollUrl, { timeoutMs: 30000 });
     last = r.json;
     const s = r.json && r.json.status;
     if (onTick) onTick(r.json);