@manturhub/cli 0.9.5 → 0.9.7

package/README.md

@@ -31,7 +31,7 @@ manturhub quote 电商文案生成
 manturhub run 电商文案生成 --json '{"product_info":"便携榨汁杯，USB 充电，300ml","scene":"product_title","tone":"lively"}'
 ```
 
-CLI 会在付费调用前按算子实时 schema 校验未知字段、必填项、类型和枚举，校验失败不会发起 invoke。校验通过后会显示本次预计消耗和计费依据，获得确认才调用；完成后显示实际消耗和退款。批量参数也按整批请求试算。
+CLI 会在付费调用前按算子实时 schema 校验未知字段、必填项、类型、枚举和长度/数值范围，校验失败不会发起 invoke。校验通过后会显示本次预计消耗和计费依据，获得确认才调用；完成后在最终 JSON 的 `_billing` 返回实际消耗和退款，并同步显示到终端。批量参数按整批请求试算；多次调用应逐笔汇总 `charged_dumplings` 和 `refunded_dumplings`，不得自行估算。
 
 面向用户的列表、详情、报价、确认和结算统一显示中文算子名，也可直接用中文名调用。英文算子 ID 仅保留在 `--json` 机器输出和内部 API 请求中，供 Agent 与脚本稳定使用。
 
@@ -44,7 +44,7 @@ CLI 会在付费调用前按算子实时 schema 校验未知字段、必填项
 | `manturhub ls [--cat image\|video\|audio\|text\|data] [--json]` | 实时列出上线算子 |
 | `manturhub describe <中文算子名> [--json]` | 查看精确入参与异步属性 |
 | `manturhub quote <中文算子名> [--json]` | 查询 Java API 返回的实时计费公式 |
-| `manturhub run <中文算子名> --json '{}'` | 调用算子；异步任务默认轮询到终态 |
+| `manturhub run <中文算子名> --json '{}' [--confirm <quote_id>] [--no-wait]` | 调用算子；非交互确认传报价 ID，异步任务默认轮询到终态 |
 | `manturhub run <中文算子名> --json-file params.json` | 从文件读取参数，适合长提示词和自动化 |
 | `manturhub upload <本地文件>` | 流式上传图片、音频或视频并输出公网 URL |
 | `manturhub status <poll_url>` | 查询 `run --no-wait` 返回的异步任务 |

package/bin/cli.js

@@ -99,14 +99,16 @@ function catLabel(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}）`);
+  if (String(ref).startsWith("op.")) {
+    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);
+  const matches = operators.filter((item) => item?.name === ref || item?.id === ref);
   if (matches.length === 0) throw new Error(`未找到算子“${ref}”`);
   if (matches.length > 1) throw new Error(`算子名称“${ref}”不唯一，请联系平台处理`);
 
@@ -126,6 +128,8 @@ const HELP = `manturhub — ManturHub 算子广场 CLI  v${VERSION}
   manturhub quote <中文算子名>            查询实时计费公式（不要使用 Skill 内的历史价格）
   manturhub run <中文算子名> --json '{}'  试算并确认费用后调用（异步算子自动轮询到出结果）
   manturhub run <中文算子名> --json-file x.json  从文件读参数（prompt 来自配方/用户时更安全）
+  manturhub run <中文算子名> ... --confirm <quote_id>  使用非交互试算返回的报价确认 ID 调用
+  manturhub run <中文算子名> ... --no-wait  提交异步任务后立即返回 poll_url，不自动轮询
   manturhub upload <本地文件>         上传图片/音频/视频 → 公网 URL（喂算子前先转换本地文件）
   manturhub status <poll_url>         查异步任务状态（配合 run --no-wait）
   manturhub balance                   查询馒头余额
@@ -436,6 +440,7 @@ async function main() {
           `⏳ 异步任务 ${r.json.job_id || ""} 已提交，轮询结果中（预计 ${r.json.estimated_seconds || "?"}s；加 --no-wait 可只拿 job_id）…\n`
         );
         const final = await pollJob(pollUrl, {
+          initialBilling: r.json._billing,
           onTick: (j) =>
             process.stderr.write(
               `   ${j.status || "?"}${j.elapsed_ms ? " " + Math.round(j.elapsed_ms / 1000) + "s" : ""}\n`
@@ -517,6 +522,7 @@ async function main() {
       }
       const r = await apiFetch(pu);
       console.log(JSON.stringify(r.json, null, 2));
+      printBillingResult(r.json);
       if (!r.ok) process.exit(1);
       break;
     }

package/lib/api.js

@@ -65,16 +65,31 @@ export async function apiFetch(
 // 异步算子:轮询 invoke 返回的 poll_url 直到任务出终态(succeeded/failed/…),返回最终 json。
 // 未知 shape(无 status 字段)按终态处理,直接返回让上层打印。
 const ACTIVE = new Set(["queued", "running", "pending", "processing", "in_progress"]);
-export async function pollJob(pollUrl, { intervalMs = 8000, maxMs = 1200000, onTick } = {}) {
+export function retainBilling(result, fallbackBilling) {
+  if (!fallbackBilling || !result || typeof result !== "object" || Array.isArray(result)) return result;
+  return result._billing ? result : { ...result, _billing: fallbackBilling };
+}
+
+export async function pollJob(
+  pollUrl,
+  { intervalMs = 8000, maxMs = 1200000, onTick, initialBilling } = {}
+) {
   const start = Date.now();
   let last = null;
+  let lastBilling = initialBilling || null;
   while (Date.now() - start < maxMs) {
     const r = await apiFetch(pollUrl, { timeoutMs: 30000 });
     last = r.json;
+    if (r.json?._billing) lastBilling = r.json._billing;
     const s = r.json && r.json.status;
     if (onTick) onTick(r.json);
-    if (!r.ok || !s || !ACTIVE.has(s)) return r.json; // 终态(或报错/未知 shape)→ 返回
+    if (!r.ok || !s || !ACTIVE.has(s)) {
+      return retainBilling(r.json, lastBilling); // 终态(或报错/未知 shape)→ 返回
+    }
     await new Promise((res) => setTimeout(res, intervalMs));
   }
-  return { ...(last || {}), status: (last && last.status) || "timeout", _timeout: true };
+  return retainBilling(
+    { ...(last || {}), status: (last && last.status) || "timeout", _timeout: true },
+    lastBilling
+  );
 }

package/lib/params.js

@@ -83,6 +83,27 @@ export function validateParams(body, schema, { coerceStrings = false } = {}) {
         `参数 ${name} 类型错误：需要 ${expectedTypes.join(" 或 ")}，收到 ${typeName(checked)}`
       );
     }
+    if (typeof checked === "string") {
+      const length = Array.from(checked).length;
+      const minLength = field.minLength == null ? Number.NaN : Number(field.minLength);
+      const maxLength = field.maxLength == null ? Number.NaN : Number(field.maxLength);
+      if (Number.isFinite(minLength) && length < minLength) {
+        throw new Error(`参数 ${name} 长度不能少于 ${minLength} 个字符`);
+      }
+      if (Number.isFinite(maxLength) && length > maxLength) {
+        throw new Error(`参数 ${name} 长度不能超过 ${maxLength} 个字符`);
+      }
+    }
+    if (typeof checked === "number") {
+      const minimum = field.minimum == null ? Number.NaN : Number(field.minimum);
+      const maximum = field.maximum == null ? Number.NaN : Number(field.maximum);
+      if (Number.isFinite(minimum) && checked < minimum) {
+        throw new Error(`参数 ${name} 不能小于 ${minimum}`);
+      }
+      if (Number.isFinite(maximum) && checked > maximum) {
+        throw new Error(`参数 ${name} 不能大于 ${maximum}`);
+      }
+    }
     if (Array.isArray(field.enum) && !field.enum.includes(checked)) {
       throw new Error(`参数 ${name} 只能是: ${field.enum.join(" | ")}`);
     }

package/lib/setup.js

@@ -17,6 +17,7 @@ function guideBlock() {
 - 列出可用算子：\`manturhub ls\`（按类：\`manturhub ls --cat image|video|audio|text|data\`）
 - 查实时价格：\`manturhub quote <算子ID>\`（不要在 Skill / 文档里写死价格）
 - 调用算子：优先把参数写入 JSON 文件，再运行 \`manturhub run <算子ID> --json-file params.json\`；简短可信参数也可用 \`--json '{...}'\`（异步算子会轮询到结果，**别重复调用以免重复扣费**）
+- 统计费用：只读取每次最终 JSON 的 \`_billing.charged_dumplings\` / \`refunded_dumplings\`，多次调用逐笔求和；禁止自行估算
 - 上传本地文件：\`manturhub upload <文件>\` → 公网 URL（算子只接受公网 URL，本地路径非法）
 - 查余额：\`manturhub balance\`
 - 查某算子的精确入参字段：\`manturhub describe <算子ID>\`

package/lib/skill.js

@@ -31,13 +31,14 @@ description: 调用 ManturHub 算子广场的 AI 能力与行业数据(文生图
 | \`manturhub suite ls\` | 列出 Agent 套件(多角色团队工作区,如小说→短剧制作团队) |
 | \`manturhub suite install <slug> [目录]\` | 安装套件为工作目录；Key 仍保存在 CLI 用户级配置中 |
 
-## 五条铁律(不照做就会踩坑)
+## 六条铁律(不照做就会踩坑)
 
 1. **先 \`manturhub ls\` 摸清能力,再 \`manturhub describe <算子ID>\` 查精确入参** —— CLI 会在付费调用前校验字段、类型和枚举，填参数仍应以实时 schema 为准。
 2. **本地文件先 \`manturhub upload <文件>\`** 换成公网 URL,再把 URL 填进 run 的参数。算子不接受本地路径,只接受公网 URL。
 3. **异步算子直接等 \`run\` 返回** —— \`run\` 已自动轮询到 succeeded 才返回最终结果,**不要重复 run(会重复扣费 + 重复出活)**。视频可能要几分钟,耐心等。真想后台拿 \`job_id\` 用 \`--no-wait\`,之后 \`manturhub status <poll_url>\` 查。
 4. **花钱心里有数** —— 每次 run 前先 \`manturhub quote <算子ID>\`;余额不足时去当前 ManturHub 站点的 \`/pricing\`;异步任务失败平台自动退费。
 5. **能用平台 Skill 就别手搓流程** —— 完整业务(如「FPV 运镜视频」「短剧改编」)平台常有现成 Skill 模板,优先用,省得自己一步步编排还踩坑。
+6. **费用只认返回值，禁止估算** —— 每次 run 完成后读取最终 JSON 的 \`_billing.charged_dumplings\` 和 \`_billing.refunded_dumplings\`;多次或批量调用逐笔求和。最终报告必须写真实合计，不能按文件数、时长或余额印象自行估算。
 
 ## 典型流程
 

package/package.json

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