---
name: toolhub
description: 搜索和调用 ToolHub 远程 AI 工具（图片生成、图片拼接等）。当用户需要生成图片、调用远程 AI 工具、或查询可用工具时使用。
---

# ToolHub 远程工具库

ToolHub 托管了各种 AI 工具（图片生成、拼接、风格迁移等），通过 CLI 调用 `http://43.106.118.91:8001`。

**自包含：** 本 skill 目录下 `toolhub.py` 是独立脚本，不依赖 `cyber-agent` 安装，只需 `pip install httpx`。
如需 OSS 上传能力（见下表），额外装 `cyber_sdk`。

## 用法

```bash
# 检查服务状态
python /Users/sunlit/.claude/skills/toolhub/toolhub.py health

# 搜索可用工具（不填 keyword 返回全量）
python /Users/sunlit/.claude/skills/toolhub/toolhub.py search --keyword=image

# 调用工具
python /Users/sunlit/.claude/skills/toolhub/toolhub.py call \
  --tool_id=flux_gen --params='{"prompt":"a cat sitting on the moon"}'
```

## 图片参数

### 输入（给 ToolHub）

`params` 中的 `image` / `image_url` / `mask_image` / `pose_image` / `reference_image`（单值）和
`images` / `image_urls` / `reference_images`（数组）都可以传**本地路径 *或* URL**：

- 传 URL（`https://...` / `data:...`）→ 原样透传给 ToolHub 服务
- 传本地路径 → `_maybe_upload_local` 先把文件上传 OSS，拿到 CDN URL 再传给服务

```bash
# 示例：传入本地图片（自动 OSS 上传）
python /Users/sunlit/.claude/skills/toolhub/toolhub.py call \
  --tool_id=image_stitcher \
  --params='{"images":["/path/to/a.png","/path/to/b.png"],"direction":"horizontal"}'
```

### 输出（ToolHub 返回）

每张产出图会同时生成三种形态：

| 形态 | 位置 / 字段 | 用途 |
|------|-----------|------|
| 本地文件 | `<cwd>/.cache/toolhub_outputs/{trace_id}/` + `saved_files` | 用户归档、后续工具链按路径引用 |
| CDN URL | 输出 JSON 里的 `cdn_urls` | **上下文压缩后 LLM 可回看** / 工具 A→B 直接用 URL 串接 |
| base64（不出现在 CLI JSON） | `ToolResult.images` 给 agent runtime | 当前轮多模态 LLM 直接"看到"图做推理 |

输出目录不存在会自动创建。

## cyber_sdk 依赖矩阵

| 场景 | 需要 `cyber_sdk`？ | 未装会发生什么 |
|------|------------------|---------------|
| 输入只传 URL | ❌ 不需要 | 正常 |
| 输入传本地路径 | ✅ **必需** | `_upload_to_oss` 失败返回 None → 本地路径原样传给服务 → ToolHub 服务无法 GET → **工具调用失败** |
| 输出获取 `cdn_urls` | ⚠️ 可选 | 静默跳过 OSS 上传，`cdn_urls` 为空；本地 `saved_files` 和多模态 base64 都不受影响 |
| 只调 `health` / `search` | ❌ 不需要 | 正常 |

简言之：**"我要传本地图进去"就必须装 `cyber_sdk`；只消费输出的场景可以不装**。

## trace_id 会话管理

trace_id 控制图片输出子目录，优先级：

1. `--trace_id=xxx`（CLI 参数）
2. `TRACE_ID` 环境变量
3. 自动生成（`cli-xxxxxxxx`）

```bash
export TRACE_ID=my-session-001
python /Users/sunlit/.claude/skills/toolhub/toolhub.py call --tool_id=flux_gen --params='{"prompt":"..."}'
# 图片保存到 <cwd>/.cache/toolhub_outputs/my-session-00/
```

## 注意

- 调用前先用 `search` 查询目标工具的 tool_id 和参数定义
- 图片生成类工具可能耗时数分钟（GPU 冷启动）
- 部分工具有生命周期分组（如 RunComfy），需按 search 返回的 `usage_order` 顺序调用
- 输出为 JSON：`{"trace_id": "...", "output": "...", "error": "...", "metadata": {...}}`