@manturhub/cli 0.2.0 → 0.3.0

package/bin/cli.js

@@ -37,6 +37,7 @@ const HELP = `manturhub — ManturHub 算子广场 CLI  v${VERSION}
 用法:
   manturhub login --key sk-xxx        配置 API Key（存 ~/.manturhub/config.json）
   manturhub ls [--cat <分类>]         列出上线算子（分类: text/image/video/audio/data）
+  manturhub describe <算子ID>         查看算子入参字段（喂参数前先看）
   manturhub run <算子ID> --json '{}'  调用算子（异步算子自动轮询到出结果；--no-wait 只拿 job_id）
   manturhub upload <本地文件>         上传图片/音频/视频 → 公网 URL（喂算子前先转换本地文件）
   manturhub status <poll_url>         查异步任务状态（配合 run --no-wait）
@@ -109,7 +110,38 @@ async function main() {
       for (const o of ops) {
         console.log(`  ${o.id.padEnd(26)} ${o.name}   [${o.cat}]`);
       }
-      console.log(`\n用 \`manturhub run <算子ID> --json '{...}'\` 调用，参数见 ${"https://hub.mantur.cn"}/marketplace/<算子ID>`);
+      console.log(`\n用 \`manturhub describe <算子ID>\` 查入参，\`manturhub run <算子ID> --json '{...}'\` 调用`);
+      break;
+    }
+
+    case "describe":
+    case "show": {
+      const op = args[1];
+      if (!op || op.startsWith("--")) {
+        console.error("用法: manturhub describe <算子ID>   (查看入参字段)");
+        process.exit(1);
+      }
+      const r = await apiFetch(`/api/v1/operators/${encodeURIComponent(op)}`);
+      if (!r.ok) {
+        console.error(`获取失败（HTTP ${r.status}）: ${op}`);
+        process.exit(1);
+      }
+      const o = r.json.operator || r.json;
+      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);
+      if (ps && Array.isArray(ps.fields) && ps.fields.length) {
+        console.log(`\n入参:`);
+        for (const f of ps.fields) {
+          const req = f.required ? "必填" : "可选";
+          const en = f.enum ? ` {${f.enum.join("|")}}` : "";
+          console.log(`  ${String(f.name).padEnd(14)} ${String(f.type || "").padEnd(7)} ${req}${en}  ${f.desc || ""}`);
+        }
+        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调用: manturhub run ${o.id} --json '{...}'`);
       break;
     }
 

package/lib/setup.js

@@ -48,7 +48,7 @@ export function runInit() {
   // 1) 装全局「ManturHub 使用 skill」(Claude Code 用,让 agent 会用算子、少踩坑)
   const skillFile = installSkill();
   console.log(`✓ 已装 ManturHub 使用 skill：${skillFile}`);
-  console.log(`  (教 agent:先 manturhub ls 查字段、本地文件先 upload、异步 run 自动等结果、别重复调用)\n`);
+  console.log(`  (教 agent:先 manturhub ls 找算子、describe 查字段、本地文件先 upload、异步 run 自动等结果、别重复调用)\n`);
   // 2) 写项目级 agent 引导
   const targets = ["AGENTS.md", "CLAUDE.md", ".cursorrules"];
   console.log("写入项目 agent 引导（幂等，可重复运行）：");

package/lib/skill.js

@@ -19,6 +19,7 @@ description: 调用 ManturHub 算子广场的 AI 能力(文生图/视频生成/
 | 命令 | 用途 |
 |---|---|
 | \`manturhub ls [--cat image\\|video\\|audio\\|text\\|data]\` | 列出全部算子(ID / 名称 / 分类)——不确定用哪个,先跑它 |
+| \`manturhub describe <算子ID>\` | 查算子精确入参字段(必填/可选/枚举/说明)——**填参数前先跑它,别猜字段名** |
 | \`manturhub run <算子ID> --json '{...}'\` | 调用算子。**异步算子(图 / 视频 / 语音)会自动轮询到出结果**,直接拿最终 JSON |
 | \`manturhub upload <本地文件>\` | 本地图片 / 音频 / 视频 → 公网 URL(喂算子前必做;输出就是那个 URL) |
 | \`manturhub status <poll_url>\` | 查异步任务(仅当你用了 \`run --no-wait\`) |
@@ -26,7 +27,7 @@ description: 调用 ManturHub 算子广场的 AI 能力(文生图/视频生成/
 
 ## 五条铁律(不照做就会踩坑)
 
-1. **先 \`manturhub ls\` 摸清能力** —— 某算子的精确入参字段见 https://hub.mantur.cn/marketplace/<算子ID> 。**字段名必须精确,拼错会被静默忽略、结果就不对。**
+1. **先 \`manturhub ls\` 摸清能力,再 \`manturhub describe <算子ID>\` 查精确入参** —— **字段名必须精确,拼错会被静默忽略、结果就不对**,所以填参数前一定先 describe 看字段,别凭记忆猜。
 2. **本地文件先 \`manturhub upload <文件>\`** 换成公网 URL,再把 URL 填进 run 的参数。算子不接受本地路径,只接受公网 URL。
 3. **异步算子直接等 \`run\` 返回** —— \`run\` 已自动轮询到 succeeded 才返回最终结果,**不要重复 run(会重复扣费 + 重复出活)**。视频可能要几分钟,耐心等。真想后台拿 \`job_id\` 用 \`--no-wait\`,之后 \`manturhub status <poll_url>\` 查。
 4. **花钱心里有数** —— 每次 run 扣馒头;余额不足报 \`INSUFFICIENT_BALANCE\`(去 https://hub.mantur.cn 充值);异步任务失败平台自动退费,无需自己处理退费。先 \`manturhub balance\` 看余额。
@@ -34,11 +35,11 @@ description: 调用 ManturHub 算子广场的 AI 能力(文生图/视频生成/
 
 ## 典型流程
 
-1. \`manturhub ls\`(或 \`--cat image\`)找到算子 → 看 marketplace 页确认入参字段
+1. \`manturhub ls\`(或 \`--cat image\`)找到算子 → \`manturhub describe <算子ID>\` 确认入参字段
 2. 有本地图片 / 视频 / 音频 → \`manturhub upload 文件\` 拿到公网 URL
 3. \`manturhub run <算子ID> --json '{...}'\` → 异步会自动等到出结果 → 从返回 JSON 取结果 URL
 
-## 19 个算子(按域速查;入参以 \`manturhub ls\` / marketplace 为准)
+## 19 个算子(按域速查;入参以 \`manturhub describe <算子ID>\` 为准)
 
 - **图像**:\`image2\`(文生图 / 图生图)
 - **视频**:\`op.video.generate\`(生成)· \`op.video.compose\`(合成拼接)· \`op.video.understand-v2\`(视频理解)· \`op.video.upscale\`(超分)· \`op.video.subtitle-remover\`(擦字幕)
@@ -47,7 +48,7 @@ description: 调用 ManturHub 算子广场的 AI 能力(文生图/视频生成/
 - **短剧 / 拉片**:\`op.drama.search / episodes / download / adapt / insight\` · \`op.distill.list / shotscript / get-script\`
 
 > 例:\`manturhub run image2 --json '{"prompt":"a red fox in snow","n":1}'\`(异步,run 自动等到出图)。
-> 字段拼不准就 \`manturhub ls\` 或看 marketplace 页,别凭记忆猜。
+> 字段拼不准就 \`manturhub describe <算子ID>\`,别凭记忆猜。
 `;
 
 // 装到用户级 ~/.claude/skills/manturhub/SKILL.md —— 装一次,所有 Claude Code 项目可用。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manturhub/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "ManturHub 算子广场 CLI：命令行直调 AI 算子 + 给 Claude Code / Codex / Cursor 等当 stdio MCP server",
   "type": "module",
   "bin": {