docs(i18n): add zh-Hans Tool Gateway, image gen, and Windows WSL guide

Made-with: Cursor
2026-05-13 03:52:00 +00:00 · 2026-04-18 02:09:06 +08:00 · 2026-04-18 02:09:06 +08:00 · 74e4f5f97a
commit 74e4f5f97a
parent a321874ab4
7 changed files with 444 additions and 2 deletions
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/image-generation.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/image-generation.md
@ -0,0 +1,153 @@
+---
+title: 文生图（Image Generation）
+description: 通过 FAL.ai 文生图；支持 8 个模型，含 FLUX 2、GPT-Image、Nano Banana Pro、Ideogram、Recraft V4 Pro 等，可用 hermes tools 切换。
+sidebar_label: 文生图
+sidebar_position: 6
+---
+
+# 文生图（Image Generation）
+
+Hermes Agent 通过 FAL.ai 根据文字提示生成图像。默认内置 8 个模型，在速度、画质与成本上各有取舍。当前模型可通过 `hermes tools` 配置，并持久化在 `config.yaml`。
+
+## 支持的模型
+
+| 模型 | 速度 | 特点 | 参考价格 |
+|------|------|------|----------|
+| `fal-ai/flux-2/klein/9b` *（默认）* | `<1s` | 快、文字清晰 | $0.006/MP |
+| `fal-ai/flux-2-pro` | ~6s | 棚拍级写实 | $0.03/MP |
+| `fal-ai/z-image/turbo` | ~2s | 中英双语，6B | $0.005/MP |
+| `fal-ai/nano-banana-pro` | ~8s | Gemini 3 Pro、推理与文字渲染 | $0.15/张（1K） |
+| `fal-ai/gpt-image-1.5` | ~15s | 强指令遵循 | $0.034/张 |
+| `fal-ai/ideogram/v3` | ~5s | 排版最佳 | $0.03–0.09/张 |
+| `fal-ai/recraft/v4/pro/text-to-image` | ~8s | 设计 / 品牌系统 / 可交付生产 | $0.25/张 |
+| `fal-ai/qwen-image` | ~12s | 偏 LLM 式、复杂文字 | $0.02/MP |
+
+价格为撰写时的 FAL 官方口径；最新计费请以 [fal.ai](https://fal.ai/) 为准。
+
+## 配置
+
+:::tip Nous 订阅用户
+若你持有付费 [Nous Portal](https://portal.nousresearch.com) 订阅，可通过 **[Tool Gateway](tool-gateway.md)** 使用文生图，**无需** `FAL_KEY`。模型选择在「直连 FAL」与「订阅网关」两条路径下保持一致。
+
+若托管网关对某一模型返回 `HTTP 4xx`，通常表示该模型尚未在 Portal 侧代理——智能体会给出处理建议（例如配置 `FAL_KEY` 直连，或换用其他模型）。
+:::
+
+### 获取 FAL API Key
+
+1. 在 [fal.ai](https://fal.ai/) 注册  
+2. 在控制台生成 API Key  
+
+### 配置并选择模型
+
+执行：
+
+```bash
+hermes tools
+```
+
+进入 **🎨 Image Generation**，选择后端（Nous Subscription 或 FAL.ai），随后在表格中用方向键选择模型，回车确认：
+
+```
+  Model                          Speed    Strengths                    Price
+  fal-ai/flux-2/klein/9b         <1s      Fast, crisp text             $0.006/MP   ← currently in use
+  fal-ai/flux-2-pro              ~6s      Studio photorealism          $0.03/MP
+  fal-ai/z-image/turbo           ~2s      Bilingual EN/CN, 6B          $0.005/MP
+  ...
+```
+
+选择会写入 `config.yaml`：
+
+```yaml
+image_gen:
+  model: fal-ai/flux-2/klein/9b
+  use_gateway: false            # 使用 Nous Subscription 时为 true
+```
+
+### GPT-Image 画质档位
+
+`fal-ai/gpt-image-1.5` 的请求画质固定为 `medium`（约 1024×1024 下 $0.034/张）。面向用户**不开放** `low` / `high` 档位，以便 Nous Portal 侧计费在全体用户间更可预期（档位价差约 22×）。若需要更便宜的 GPT-Image 路线，请换其他模型；若追求更高画质，可考虑 Klein 9B 或同类 Imagen 系模型。
+
+## 使用方式
+
+对智能体暴露的 schema 刻意保持简单——具体行为由你在本机的配置决定：
+
+```
+Generate an image of a serene mountain landscape with cherry blossoms
+```
+
+```
+Create a square portrait of a wise old owl — use the typography model
+```
+
+```
+Make me a futuristic cityscape, landscape orientation
+```
+
+## 宽高比
+
+从智能体视角，三个宽高比词对所有模型通用；内部会映射到各模型原生参数：
+
+| 智能体输入 | image_size（flux/z-image/qwen/recraft/ideogram） | aspect_ratio（nano-banana-pro） | image_size（gpt-image） |
+|---|---|---|---|
+| `landscape` | `landscape_16_9` | `16:9` | `1536x1024` |
+| `square` | `square_hd` | `1:1` | `1024x1024` |
+| `portrait` | `portrait_16_9` | `9:16` | `1024x1536` |
+
+该映射在 `_build_fal_payload()` 中完成，智能体代码无需了解各模型 schema 差异。
+
+## 自动超分（Upscale）
+
+是否启用 FAL **Clarity Upscaler** 按模型区分：
+
+| 模型 | 超分？ | 原因 |
+|---|---|---|
+| `fal-ai/flux-2-pro` | ✓ | 历史兼容（选择器出现前的默认） |
+| 其他 | ✗ | 亚秒级模型若再超分会失去速度优势；高分辨率模型本身已足够清晰 |
+
+超分启用时的主要参数：
+
+| 项 | 值 |
+|---|---|
+| 放大倍数 | 2× |
+| Creativity | 0.35 |
+| Resemblance | 0.6 |
+| Guidance scale | 4 |
+| Inference steps | 18 |
+
+若超分失败（网络、限流等），会自动回退为返回原始图像。
+
+## 内部流程概要
+
+1. **模型解析** — `_resolve_fal_model()` 读取 `config.yaml` 的 `image_gen.model`，否则看 `FAL_IMAGE_MODEL` 环境变量，再否则默认 `fal-ai/flux-2/klein/9b`。  
+2. **构造请求体** — `_build_fal_payload()` 将 `aspect_ratio` 转为各模型枚举或字面量，合并默认参数与调用方覆盖，并按 `supports` 白名单过滤非法字段。  
+3. **提交** — `_submit_fal_request()` 根据凭据走直连 FAL 或 Nous 托管网关。  
+4. **超分** — 仅当模型元数据标记 `upscale: True` 时执行。  
+5. **交付** — 最终图像 URL 返回给智能体，并发出 `MEDIA:<url>`，由各平台适配器转为原生媒体消息。  
+
+## 调试
+
+打开调试日志：
+
+```bash
+export IMAGE_TOOLS_DEBUG=true
+```
+
+日志写入 `./logs/image_tools_debug_<session_id>.json`，包含每次调用的模型、参数、耗时与错误信息。
+
+## 各平台展示
+
+| 平台 | 行为 |
+|---|---|
+| **CLI** | 图像 URL 以 Markdown `![](url)` 打印，可点击打开 |
+| **Telegram** | 以图片消息发送，附提示词为说明 |
+| **Discord** | 嵌入消息 |
+| **Slack** | URL 由 Slack 展开预览 |
+| **WhatsApp** | 媒体消息 |
+| **其他** | 纯文本中的 URL |
+
+## 限制
+
+- **需要 FAL 凭据**（直连 `FAL_KEY` 或 Nous 订阅网关）  
+- **仅文生图** — 不支持局部重绘、图生图或编辑类工作流  
+- **临时 URL** — FAL 托管链接会在数小时至数天后过期；请自行落盘保存  
+- **按模型能力裁剪** — 部分模型不支持 `seed`、`num_inference_steps` 等；`supports` 会静默丢弃不支持的参数，属预期行为