@manturhub/cli 0.8.2 → 0.9.1

package/README.md

@@ -15,6 +15,8 @@ manturhub login
 printf '%s' "$YOUR_MANTURHUB_KEY" | manturhub login --key-stdin
 ```
 
+CLI 默认连接生产站 `https://hub.mantur.ai`，Key 也必须在该生产站创建。`hub.mantur.cn` 是独立测试环境，其 Key 不能用于生产站。
+
 需要 Node.js ≥ 18。也可免安装运行：`npx -y @manturhub/cli <命令>`。
 
 ## 快速开始
@@ -22,24 +24,28 @@ printf '%s' "$YOUR_MANTURHUB_KEY" | manturhub login --key-stdin
 ```bash
 # 发现与查看算子无需登录
 manturhub ls --cat text
-manturhub describe op.text.commerce-copy
+manturhub describe 电商文案生成
 
 # 先查实时价格，再调用
-manturhub quote op.text.commerce-copy
-manturhub run op.text.commerce-copy --json '{"product_info":"便携榨汁杯，USB 充电，300ml","scene":"product_title","tone":"lively"}'
+manturhub quote 电商文案生成
+manturhub run 电商文案生成 --json '{"product_info":"便携榨汁杯，USB 充电，300ml","scene":"product_title","tone":"lively"}'
 ```
 
-CLI 会在付费调用前按算子实时 schema 校验未知字段、必填项、类型和枚举，校验失败不会发起 invoke。
+CLI 会在付费调用前按算子实时 schema 校验未知字段、必填项、类型和枚举，校验失败不会发起 invoke。校验通过后会显示本次预计消耗和计费依据，获得确认才调用；完成后显示实际消耗和退款。批量参数也按整批请求试算。
+
+面向用户的列表、详情、报价、确认和结算统一显示中文算子名，也可直接用中文名调用。英文算子 ID 仅保留在 `--json` 机器输出和内部 API 请求中，供 Agent 与脚本稳定使用。
+
+在 Agent 或脚本等非交互环境中，第一次运行只返回报价和 `quote_id`，不会调用或扣费；Agent 向用户确认后，使用提示中的 `--confirm <quote_id>` 执行。报价 5 分钟内有效且只能使用一次。
 
 ## 主要命令
 
 | 命令 | 说明 |
 |---|---|
 | `manturhub ls [--cat image\|video\|audio\|text\|data] [--json]` | 实时列出上线算子 |
-| `manturhub describe <算子ID> [--json]` | 查看精确入参与异步属性 |
-| `manturhub quote <算子ID> [--json]` | 查询 Java API 返回的实时计费公式 |
-| `manturhub run <算子ID> --json '{}'` | 调用算子；异步任务默认轮询到终态 |
-| `manturhub run <算子ID> --json-file params.json` | 从文件读取参数，适合长提示词和自动化 |
+| `manturhub describe <中文算子名> [--json]` | 查看精确入参与异步属性 |
+| `manturhub quote <中文算子名> [--json]` | 查询 Java API 返回的实时计费公式 |
+| `manturhub run <中文算子名> --json '{}'` | 调用算子；异步任务默认轮询到终态 |
+| `manturhub run <中文算子名> --json-file params.json` | 从文件读取参数，适合长提示词和自动化 |
 | `manturhub upload <本地文件>` | 流式上传图片、音频或视频并输出公网 URL |
 | `manturhub status <poll_url>` | 查询 `run --no-wait` 返回的异步任务 |
 | `manturhub balance [--json]` | 查询余额及美元等值（1 馒头 = $0.01 USD） |

package/bin/cli.js

@@ -10,6 +10,7 @@ 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";
+import { confirmCharge, formatMantou, printBillingResult } from "../lib/billing-confirm.js";
 
 // 本地文件 → MIME(presign 只接受 image/audio/video)
 const MIME_BY_EXT = {
@@ -67,8 +68,8 @@ function assertFlags(tokens, { value = [], boolean = [] } = {}) {
 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") {
+    if (token === "--no-wait" || token.startsWith("--json=") || token.startsWith("--json-file=") || token.startsWith("--confirm=")) continue;
+    if (token === "--json" || token === "--json-file" || token === "--confirm") {
       const value = tokens[i + 1];
       if (value === undefined || value.startsWith("--")) throw new Error(`参数 ${token} 缺少值`);
       i++;
@@ -83,6 +84,37 @@ function usdFor(dumplings) {
   return Number.isFinite(value) ? `$${(value * 0.01).toFixed(2)} USD` : "-";
 }
 
+const CAT_LABELS = {
+  text: "文本",
+  image: "图片",
+  video: "视频",
+  audio: "音频",
+  data: "数据",
+};
+
+function catLabel(cat) {
+  return CAT_LABELS[cat] || cat || "其他";
+}
+
+// Human commands accept either the stable operator ID or its Chinese display name.
+// Machine-facing --json responses keep IDs unchanged for automation compatibility.
+async function resolveOperator(ref) {
+  const direct = await apiFetch(`/api/v1/operators/${encodeURIComponent(ref)}`, { auth: "optional" });
+  if (direct.ok) return direct.json.operator || direct.json;
+  if (direct.status !== 404) throw new Error(`算子信息获取失败（HTTP ${direct.status}）`);
+
+  const listed = await apiFetch("/api/v1/operators?status=online", { auth: "optional" });
+  if (!listed.ok) throw new Error(`算子列表获取失败（HTTP ${listed.status}）`);
+  const operators = listed.json.operators || listed.json || [];
+  const matches = operators.filter((item) => item?.name === ref);
+  if (matches.length === 0) throw new Error(`未找到算子“${ref}”`);
+  if (matches.length > 1) throw new Error(`算子名称“${ref}”不唯一，请联系平台处理`);
+
+  const detail = await apiFetch(`/api/v1/operators/${encodeURIComponent(matches[0].id)}`, { auth: "optional" });
+  if (!detail.ok) throw new Error(`算子信息获取失败（HTTP ${detail.status}）`);
+  return detail.json.operator || detail.json;
+}
+
 const HELP = `manturhub — ManturHub 算子广场 CLI  v${VERSION}
 
 用法:
@@ -90,10 +122,10 @@ const HELP = `manturhub — ManturHub 算子广场 CLI  v${VERSION}
   manturhub login --key sk-xxx        手动配置 API Key（存 ~/.manturhub/config.json）
   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 describe <中文算子名> [--json]  查看算子入参字段（无需登录）
+  manturhub quote <中文算子名>            查询实时计费公式（不要使用 Skill 内的历史价格）
+  manturhub run <中文算子名> --json '{}'  试算并确认费用后调用（异步算子自动轮询到出结果）
+  manturhub run <中文算子名> --json-file x.json  从文件读参数（prompt 来自配方/用户时更安全）
   manturhub upload <本地文件>         上传图片/音频/视频 → 公网 URL（喂算子前先转换本地文件）
   manturhub status <poll_url>         查异步任务状态（配合 run --no-wait）
   manturhub balance                   查询馒头余额
@@ -161,7 +193,14 @@ async function main() {
           `✓ Key 已验证并保存。账号: ${r.json.email || "-"}   余额: ${usdFor(r.json.balance)}（${r.json.balance ?? "-"} 馒头）`
         );
       } else {
-        console.error(`Key 验证失败（HTTP ${r.status}），未修改本地配置。请确认 key 是否正确、是否已激活。`);
+        const base = getBaseUrl();
+        const productionHint = new URL(base).hostname === "hub.mantur.ai"
+          ? " 对外用户请在 https://hub.mantur.ai 创建生产 Key；hub.mantur.cn 的测试 Key 不能用于生产。"
+          : "";
+        console.error(
+          `Key 验证失败（HTTP ${r.status}），未修改本地配置。当前连接：${base}。` +
+          `Key 必须由这个站点创建，请确认 Key 是否正确、是否已激活。${productionHint}`
+        );
         process.exit(1);
       }
       break;
@@ -198,9 +237,9 @@ async function main() {
       }
       console.log(`ManturHub 上线算子（${ops.length} 个）:\n`);
       for (const o of ops) {
-        console.log(`  ${o.id.padEnd(26)} ${o.name}   [${o.cat}]`);
+        console.log(`  ${o.name}   [${catLabel(o.cat)}]`);
       }
-      console.log(`\n用 \`manturhub describe <算子ID>\` 查入参，\`manturhub run <算子ID> --json '{...}'\` 调用`);
+      console.log(`\n用 \`manturhub describe <中文算子名>\` 查入参，\`manturhub run <中文算子名> --json '{...}'\` 调用`);
       break;
     }
 
@@ -217,17 +256,18 @@ async function main() {
         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}`);
+      let o;
+      try {
+        o = await resolveOperator(op);
+      } catch (error) {
+        console.error(error.message);
         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 || "-"}`);
+      console.log(`\n${o.name || "未命名算子"}   [${catLabel(o.cat)}] · ${o.status || "-"}`);
       if (o.description) console.log(o.description);
       const ps = o.params_schema || (o.meta && o.meta.params_schema);
       if (ps && Array.isArray(ps.fields) && ps.fields.length) {
@@ -239,9 +279,9 @@ async function main() {
         }
         if (ps.async) console.log(`\n异步算子：run 默认自动轮询到出结果（--no-wait 只拿 task_id）`);
       } else {
-        console.log(`\n（该算子未声明入参 schema，详见 ${getBaseUrl()}/marketplace/${o.id}）`);
+        console.log(`\n（该算子未声明入参 schema，请在 ManturHub 算子广场查看详情）`);
       }
-      console.log(`\n调用: manturhub run ${o.id} --json '{...}'`);
+      console.log(`\n调用: manturhub run '${o.name}' --json '{...}'`);
       break;
     }
 
@@ -257,7 +297,14 @@ async function main() {
         console.error(error.message);
         process.exit(1);
       }
-      const r = await apiFetch(`/api/v1/operators/${encodeURIComponent(op)}/quote`, { auth: "optional" });
+      let operator;
+      try {
+        operator = await resolveOperator(op);
+      } catch (error) {
+        console.error(error.message);
+        process.exit(1);
+      }
+      const r = await apiFetch(`/api/v1/operators/${encodeURIComponent(operator.id)}/quote`, { auth: "optional" });
       if (!r.ok) {
         console.error(`查询价格失败（HTTP ${r.status}）: ${JSON.stringify(r.json)}`);
         process.exit(1);
@@ -272,7 +319,7 @@ async function main() {
           )
         );
       } else {
-        console.log(`${r.json.operatorId || op}: ${r.json.formula || "详见算子页"}`);
+        console.log(`${operator.name}: ${r.json.formula || "详见算子页"}`);
         if (r.json.floor !== undefined) console.log(`最低扣费: ${usdFor(r.json.floor)}（${r.json.floor} 馒头）`);
       }
       break;
@@ -325,12 +372,14 @@ async function main() {
           process.exit(1);
         }
       }
-      const detail = await apiFetch(`/api/v1/operators/${encodeURIComponent(op)}`, { auth: "optional" });
-      if (!detail.ok) {
-        console.error(`参数校验前无法读取算子 schema（HTTP ${detail.status}），已停止调用避免误扣费`);
+      let operator;
+      try {
+        operator = await resolveOperator(op);
+      } catch (error) {
+        console.error(`${error.message}，已停止调用避免误扣费`);
         process.exit(1);
       }
-      const operator = detail.json.operator || detail.json;
+      const operatorId = operator.id;
       const schema = operator.params_schema || operator.meta?.params_schema;
       try {
         body = validateParams(body, schema, { coerceStrings: !jsonArg && !jsonFile });
@@ -338,9 +387,47 @@ async function main() {
         console.error(`参数校验失败: ${error.message}`);
         process.exit(1);
       }
+      let quoteId = getFlag("confirm");
+      if (!quoteId) {
+        const quote = await apiFetch(`/api/v1/operators/${encodeURIComponent(operatorId)}/quote`, {
+          method: "POST",
+          body,
+        });
+        if (!quote.ok) {
+          console.error(`本次费用试算失败（HTTP ${quote.status}）: ${JSON.stringify(quote.json)}`);
+          process.exit(1);
+        }
+        const estimated = Number(quote.json?.estimated_dumplings);
+        quoteId = quote.json?.quote_id;
+        if (Number.isFinite(estimated) && estimated > 0) {
+          if (process.stdin.isTTY && process.stderr.isTTY) {
+            if (!(await confirmCharge({ ...quote.json, operator_name: operator.name }))) {
+              console.error("已取消，未调用算子、未扣费。");
+              process.exit(2);
+            }
+          } else {
+            console.error(JSON.stringify({
+              error: "CONFIRMATION_REQUIRED",
+              operator_name: operator.name,
+              message: `本次预计消耗 ${formatMantou(estimated)}，请先取得用户确认`,
+              estimated_dumplings: estimated,
+              balance: quote.json?.balance,
+              formula: quote.json?.formula,
+              quote_id: quoteId,
+              retry_with: `--confirm ${quoteId}`,
+            }, null, 2));
+            process.exit(3);
+          }
+        }
+      }
       const r = await apiFetch(
-        `/api/v1/operators/${encodeURIComponent(op)}/invoke`,
-        { method: "POST", body, timeoutMs: 120000 }
+        `/api/v1/operators/${encodeURIComponent(operatorId)}/invoke`,
+        {
+          method: "POST",
+          body,
+          timeoutMs: 120000,
+          headers: quoteId ? { "X-Mantur-Quote-Id": quoteId } : {},
+        }
       );
       // 异步算子(返回 poll_url)默认自动轮询到出结果;--no-wait 只拿 job_id。
       const pollUrl = r.ok && r.json && r.json.poll_url;
@@ -355,10 +442,12 @@ async function main() {
             ),
         });
         console.log(JSON.stringify(final, null, 2));
+        printBillingResult(final, process.stderr, operator.name);
         const st = final && final.status;
         if (st === "failed" || st === "error" || (final && final._timeout)) process.exit(1);
       } else {
         console.log(JSON.stringify(r.json, null, 2));
+        printBillingResult(r.json, process.stderr, operator.name);
         if (!r.ok) process.exit(1);
       }
       break;

package/lib/api.js

@@ -3,7 +3,7 @@ import { getKey, getBaseUrl } from "./config.js";
 // 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 } = {}
+  { method = "GET", body, key, auth = "required", timeoutMs = 30000, headers = {} } = {}
 ) {
   const apiKey = key === undefined ? getKey() : key;
   if (auth === "required" && !apiKey) {
@@ -22,6 +22,7 @@ export async function apiFetch(
       headers: {
         ...(includeKey && apiKey ? { "x-api-key": apiKey } : {}),
         ...(body ? { "Content-Type": "application/json" } : {}),
+        ...headers,
       },
       body: body ? JSON.stringify(body) : undefined,
       signal: AbortSignal.timeout(timeoutMs),

package/lib/billing-confirm.js

@@ -0,0 +1,36 @@
+import { createInterface } from "node:readline/promises";
+
+export function formatMantou(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? `${number} 馒头（$${(number * 0.01).toFixed(2)} USD）` : "未知";
+}
+
+export async function confirmCharge(quote, { input = process.stdin, output = process.stderr } = {}) {
+  if (quote.operator_name) output.write(`\n算子：${quote.operator_name}\n`);
+  output.write(`\n⚠️  本次预计消耗：${formatMantou(quote.estimated_dumplings)}\n`);
+  if (quote.formula) output.write(`计费依据：${quote.formula}\n`);
+  if (Number.isFinite(Number(quote.balance))) output.write(`当前余额：${quote.balance} 馒头\n`);
+  const rl = createInterface({ input, output });
+  try {
+    const answer = (await rl.question("是否继续？[y/N] ")).trim().toLowerCase();
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+export function printBillingResult(result, output = process.stderr, operatorName = null) {
+  const billing = result?._billing;
+  if (!billing) return;
+  const estimated = Number(billing.estimated_dumplings);
+  const charged = Number(billing.charged_dumplings);
+  const refunded = Number(billing.refunded_dumplings);
+  if (billing.final) {
+    if (operatorName) output.write(`\n算子：${operatorName}\n`);
+    output.write(`\n✓ 本次实际消耗：${formatMantou(charged)}\n`);
+    if (Number.isFinite(refunded) && refunded > 0) output.write(`  已退款：${formatMantou(refunded)}\n`);
+    if (Number.isFinite(estimated) && estimated !== charged) output.write(`  调用前预计：${formatMantou(estimated)}\n`);
+  } else {
+    output.write(`\n⏳ 已预扣：${formatMantou(charged)}，任务完成后以最终结算为准\n`);
+  }
+}

package/lib/params.js

@@ -85,6 +85,14 @@ export function parseDynamicParams(tokens) {
   for (let i = 0; i < tokens.length; i++) {
     const token = tokens[i];
     if (token === "--no-wait") continue;
+    if (token === "--confirm") {
+      if (tokens[i + 1] === undefined || tokens[i + 1].startsWith("--")) {
+        throw new Error("参数 --confirm 缺少值");
+      }
+      i++;
+      continue;
+    }
+    if (token?.startsWith("--confirm=")) continue;
     if (!token?.startsWith("--")) throw new Error(`无法识别的参数: ${token}`);
     const equals = token.indexOf("=");
     if (equals > 2) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manturhub/cli",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "ManturHub 算子广场 CLI：通过 REST 发现和调用 AI 算子、浏览配方，并安装 Skill 与 Agent 套件",
   "type": "module",
   "bin": {