@manturhub/cli 0.6.0 → 0.8.0

package/README.md

@@ -1,68 +1,55 @@
 # @manturhub/cli
 
-ManturHub 算子广场命令行工具。两件事:
+ManturHub 算子广场的统一 Agent 调用通道。CLI 通过 REST 实时发现和调用全部上线算子，也可浏览配方、安装平台 Skill 和 Agent 套件；新算子上线后无需更新 CLI 即可发现。
 
-1. **命令行直调算子** —— 不写代码、不碰 MCP,终端一行调用 AI 算子。
-2. **stdio MCP server** —— 给 Claude Code / Codex / Cursor / Claude Desktop 等当本地 MCP server。stdio 是所有 AI 客户端都稳定支持的传输,装上这个 CLI 就一行接入,绕开各家对远程传输支持参差的坑。
-
-## 安装
+## 安装与登录
 
 ```bash
 npm install -g @manturhub/cli
-# 或免安装直接用: npx -y @manturhub/cli <命令>
+manturhub login
 ```
 
-需要 Node.js ≥ 18。
-
-## 上手三步
+`login` 默认打开浏览器授权，API Key 只保存在 `~/.manturhub/config.json`（权限 `600`）。无浏览器环境可设置 `MANTURHUB_KEY`，或通过 stdin 导入，避免进入 shell history：
 
 ```bash
-# 1. 配 Key（去 https://hub.mantur.cn/dashboard 拿）
-manturhub login --key sk-你的key
-
-# 2. 验证（列出全部上线算子）
-manturhub ls
-
-# 3. 调一个算子试试
-manturhub run op.text.commerce-copy --json '{"product_info":"便携榨汁杯,USB充电,300ml","scene":"product_title","tone":"lively"}'
+printf '%s' "$YOUR_MANTURHUB_KEY" | manturhub login --key-stdin
 ```
 
-## 把算子接进你的 AI（stdio，一行搞定）
+需要 Node.js ≥ 18。也可免安装运行：`npx -y @manturhub/cli <命令>`。
 
-**Codex** — `~/.codex/config.toml`:
-```toml
-[mcp_servers.manturhub]
-command = "manturhub"
-args = ["mcp"]
-env = { MANTURHUB_KEY = "sk-你的key" }
-```
+## 快速开始
 
-**Claude Desktop / Cursor / Cline**:
-```json
-{ "mcpServers": { "manturhub": { "command": "manturhub", "args": ["mcp"] } } }
-```
+```bash
+# 发现与查看算子无需登录
+manturhub ls --cat text
+manturhub describe op.text.commerce-copy
 
-装好后,AI 就能直接 `list_operators` 看平台能力、`run_operator` 调用算子。只想要某个业务域?加 `--scope`:
-```toml
-args = ["mcp", "--scope", "drama"]   # 只暴露剧本域算子
+# 先查实时价格，再调用
+manturhub quote op.text.commerce-copy
+manturhub run op.text.commerce-copy --json '{"product_info":"便携榨汁杯，USB 充电，300ml","scene":"product_title","tone":"lively"}'
 ```
-域可选: `manturhub`(全部) · `drama`(剧本) · `production`(制片) · `ecom-video`(电商视频)。
 
-## 命令
+CLI 会在付费调用前按算子实时 schema 校验未知字段、必填项、类型和枚举，校验失败不会发起 invoke。
+
+## 主要命令
 
 | 命令 | 说明 |
 |---|---|
-| `manturhub login --key sk-xxx` | 配置并验证 API Key（存 `~/.manturhub/config.json`,600 权限） |
-| `manturhub mcp [--scope <域>]` | 启动 stdio MCP server（被 AI 客户端作为子进程拉起） |
-| `manturhub ls [--cat <分类>]` | 列出上线算子 |
-| `manturhub run <算子ID> --json '{}'` | 调用算子（也支持 `--字段 值` 形式） |
-| `manturhub balance` | 查询馒头余额 |
-
-环境变量: `MANTURHUB_KEY`(API Key,优先于配置文件) · `MANTURHUB_BASE`(网关地址)。
-
-## 它是怎么工作的
-
-`manturhub mcp` 不重新实现 MCP server,而是把客户端的 stdio JSON-RPC 消息转发到 ManturHub 已标准化的 Streamable HTTP MCP 端点(`/api/v1/mcp/<域>/mcp`),再把响应写回 stdout。工具发现、调用、计费全部在服务端完成,CLI 只做可靠的 stdio↔HTTP 桥接 —— 等于一个官方、可控的 mcp-remote。
-
----
-ManturHub 算子广场 · https://hub.mantur.cn
+| `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 upload <本地文件>` | 流式上传图片、音频或视频并输出公网 URL |
+| `manturhub status <poll_url>` | 查询 `run --no-wait` 返回的异步任务 |
+| `manturhub balance [--json]` | 查询余额及人民币等值（1 馒头 = ¥0.1） |
+| `manturhub skill ls [--json]` / `skill add <slug> --client codex` | 浏览和安装业务 Skill |
+| `manturhub recipe [关键词]` / `recipe get <ID>` | 搜索并查看已验证配方 |
+| `manturhub suite ls [--json]` / `suite install <slug>` | 安装多角色 Agent 套件，不复制 API Key |
+| `manturhub init` | 给当前项目写入 Agent 使用引导 |
+
+机器消费输出可在支持的查询命令上加 `--json`。进度和提示写入 stderr，JSON 结果写入 stdout。
+
+环境变量：`MANTURHUB_KEY`（优先于配置文件） · `MANTURHUB_BASE`（测试或私有部署覆盖，默认 `https://hub.mantur.ai`）。
+
+ManturHub 算子广场：https://hub.mantur.ai