diff --git a/scripts/release.py b/scripts/release.py index d749b30a71..95bf5eda81 100755 --- a/scripts/release.py +++ b/scripts/release.py @@ -97,6 +97,7 @@ AUTHOR_MAP = { "binhnt.ht.92@gmail.com": "binhnt92", "johnny@Jons-MBA-M4.local": "acesjohnny", "1581133593@qq.com": "liu-collab", + "haidaoe@proton.me": "haidao1919", # Matrix parity salvage batch (April 2026) "sr@samirusani": "samrusani", "angelclaw@AngelMacBook.local": "angel12", diff --git a/website/docs/user-guide/windows-wsl-quickstart.md b/website/docs/user-guide/windows-wsl-quickstart.md new file mode 100644 index 0000000000..7500694121 --- /dev/null +++ b/website/docs/user-guide/windows-wsl-quickstart.md @@ -0,0 +1,22 @@ +--- +title: "Windows (WSL2) Quick Start" +description: "Run Hermes Agent on Windows using WSL2 — supported path for CLI and Tool Gateway" +sidebar_label: "Windows (WSL2)" +sidebar_position: 2 +--- + +# Windows (WSL2) Quick Start + +Hermes Agent is developed and tested on **Linux** and **macOS**. On Windows, the supported setup is **WSL2** (Windows Subsystem for Linux), not legacy native Windows shells. + +:::info Full guide in Chinese +The detailed checklist (WSL2, `uv`, repo clone, gateway tips) is maintained in **简体中文**. Use the **language** menu (top right) and select **简体中文**, then open this same page again. +::: + +## Minimum path + +1. Install [WSL2](https://learn.microsoft.com/windows/wsl/install) and a recent Ubuntu (or another supported distro). +2. Open your WSL terminal and follow [Installation](/getting-started/installation) inside that environment. +3. Run `hermes model` / `hermes tools` from WSL so paths, process isolation, and the Tool Gateway match upstream expectations. + +For Tool Gateway and image tooling behavior, see [Tool Gateway](/user-guide/features/tool-gateway) and [Image Generation](/user-guide/features/image-generation). diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index 551242b758..6d6904d6cb 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -24,7 +24,16 @@ const config: Config = { i18n: { defaultLocale: 'en', - locales: ['en'], + locales: ['en', 'zh-Hans'], + localeConfigs: { + en: { + label: 'English', + }, + 'zh-Hans': { + label: '简体中文', + htmlLang: 'zh-Hans', + }, + }, }, themes: [ @@ -34,7 +43,7 @@ const config: Config = { /** @type {import("@easyops-cn/docusaurus-search-local").PluginOptions} */ ({ hashed: true, - language: ['en'], + language: ['en', 'zh'], indexBlog: false, docsRouteBasePath: '/', // Disabled: appends ?_highlight=... to URLs (before the #anchor), @@ -104,6 +113,10 @@ const config: Config = { label: 'Skills', position: 'left', }, + { + type: 'localeDropdown', + position: 'right', + }, { href: 'https://hermes-agent.nousresearch.com', label: 'Home', diff --git 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 new file mode 100644 index 0000000000..29b22d972e --- /dev/null +++ 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:`，由各平台适配器转为原生媒体消息。 + +## 调试 + +打开调试日志： + +```bash +export IMAGE_TOOLS_DEBUG=true +``` + +日志写入 `./logs/image_tools_debug_.json`，包含每次调用的模型、参数、耗时与错误信息。 + +## 各平台展示 + +| 平台 | 行为 | +|---|---| +| **CLI** | 图像 URL 以 Markdown `![](url)` 打印，可点击打开 | +| **Telegram** | 以图片消息发送，附提示词为说明 | +| **Discord** | 嵌入消息 | +| **Slack** | URL 由 Slack 展开预览 | +| **WhatsApp** | 媒体消息 | +| **其他** | 纯文本中的 URL | + +## 限制 + +- **需要 FAL 凭据**（直连 `FAL_KEY` 或 Nous 订阅网关） +- **仅文生图** — 不支持局部重绘、图生图或编辑类工作流 +- **临时 URL** — FAL 托管链接会在数小时至数天后过期；请自行落盘保存 +- **按模型能力裁剪** — 部分模型不支持 `seed`、`num_inference_steps` 等；`supports` 会静默丢弃不支持的参数，属预期行为 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/tool-gateway.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/tool-gateway.md new file mode 100644 index 0000000000..e561641571 --- /dev/null +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/tool-gateway.md @@ -0,0 +1,187 @@ +--- +title: "Nous Tool Gateway（工具网关）" +description: "通过 Nous 订阅统一使用网页搜索、文生图、语音合成与浏览器自动化，无需单独申请 Firecrawl、FAL、OpenAI、Browser Use 等 API Key" +sidebar_label: "Tool Gateway" +sidebar_position: 2 +--- + +# Nous Tool Gateway（工具网关） + +:::tip 快速开始 +Tool Gateway 包含在付费 Nous Portal 订阅中。**[管理订阅 →](https://portal.nousresearch.com/manage-subscription)** +::: + +**Tool Gateway** 让已付费的 [Nous Portal](https://portal.nousresearch.com) 用户通过同一份订阅，直接使用网页搜索、文生图、语音合成（TTS）与浏览器自动化，而**不必**再分别注册 Firecrawl、FAL、OpenAI、Browser Use 等服务的 API Key。 + +## 包含能力 + +| 工具 | 作用 | 若不用网关，可改用 | +|------|------|---------------------| +| **网页搜索与抓取** | 通过 Firecrawl 搜索并抽取页面内容 | `FIRECRAWL_API_KEY`、`EXA_API_KEY`、`PARALLEL_API_KEY`、`TAVILY_API_KEY` | +| **文生图** | 通过 FAL 生成图像（8 个模型：FLUX 2 Klein/Pro、GPT-Image、Nano Banana Pro、Ideogram、Recraft V4 Pro、Qwen、Z-Image） | `FAL_KEY` | +| **语音合成** | 通过 OpenAI TTS 将文字转为语音 | `VOICE_TOOLS_OPENAI_KEY`、`ELEVENLABS_API_KEY` | +| **浏览器自动化** | 通过 Browser Use 控制云端浏览器 | `BROWSER_USE_API_KEY`、`BROWSERBASE_API_KEY` | + +上述四类能力均计入 Nous 订阅计费。你可以按需组合——例如网页与文生图走网关，TTS 仍使用自己的 ElevenLabs Key。 + +## 资格与账号 + +Tool Gateway 仅对 **[付费](https://portal.nousresearch.com/manage-subscription)** Nous Portal 订阅开放；免费档不可用——请 [升级订阅](https://portal.nousresearch.com/manage-subscription) 后解锁。 + +检查当前状态： + +```bash +hermes status +``` + +在输出中找到 **Nous Tool Gateway** 小节：会标明哪些工具经订阅网关启用、哪些使用直连 Key、哪些尚未配置。 + +## 如何启用 Tool Gateway + +### 在模型配置流程中 + +运行 `hermes model` 并选择 Nous Portal 作为提供商时，Hermes 会主动询问是否启用 Tool Gateway： + +``` +Your Nous subscription includes the Tool Gateway. + + The Tool Gateway gives you access to web search, image generation, + text-to-speech, and browser automation through your Nous subscription. + No need to sign up for separate API keys — just pick the tools you want. + + ○ Web search & extract (Firecrawl) — not configured + ○ Image generation (FAL) — not configured + ○ Text-to-speech (OpenAI TTS) — not configured + ○ Browser automation (Browser Use) — not configured + + ● Enable Tool Gateway + ○ Skip +``` + +选择 **Enable Tool Gateway** 即可。 + +若 `.env` 中已有部分直连 API Key，提示会相应变化：可为全部工具启用网关（直连 Key 仍保留在 `.env` 但运行时不用）、仅为未配置项启用，或完全跳过。 + +### 通过 `hermes tools` + +也可在交互式工具配置中逐项启用： + +```bash +hermes tools +``` + +选择工具类别（Web、Browser、Image Generation、TTS），再将提供商选为 **Nous Subscription**。这会在配置里把对应工具的 `use_gateway` 设为 `true`。 + +### 手动编辑配置 + +在 `~/.hermes/config.yaml` 中直接设置 `use_gateway`： + +```yaml +web: + backend: firecrawl + use_gateway: true + +image_gen: + use_gateway: true + +tts: + provider: openai + use_gateway: true + +browser: + cloud_provider: browser-use + use_gateway: true +``` + +## 工作原理 + +当某工具的 `use_gateway: true` 时，运行时会把 API 调用路由到 Nous Tool Gateway，而不是使用直连 Key： + +1. **网页工具** — `web_search` / `web_extract` 走网关的 Firecrawl 端点 +2. **文生图** — `image_generate` 走网关的 FAL 端点 +3. **TTS** — `text_to_speech` 走网关的 OpenAI Audio 端点 +4. **浏览器** — `browser_navigate` 等走网关的 Browser Use 端点 + +网关使用 Nous Portal 凭据认证（在 `hermes model` 完成后写入 `~/.hermes/auth.json`）。 + +### 优先级 + +每个工具都会先看 `use_gateway`： + +- **`use_gateway: true`** → 强制走网关，即使 `.env` 里仍有直连 Key +- **`use_gateway: false`**（或未设置）→ 若有直连 Key 则优先直连；仅在没有直连凭据时才回退到网关 + +因此你可以在网关与直连之间切换，而无需删除 `.env` 中的旧 Key。 + +## 切回直连 Key + +对单个工具停用网关： + +```bash +hermes tools # 选择该工具 → 选直连提供商 +``` + +或在配置中设 `use_gateway: false`： + +```yaml +web: + backend: firecrawl + use_gateway: false # 此时使用 .env 中的 FIRECRAWL_API_KEY +``` + +在 `hermes tools` 中选择非网关提供商时，`use_gateway` 会自动设为 `false`，避免配置自相矛盾。 + +## 查看状态 + +```bash +hermes status +``` + +**Nous Tool Gateway** 小节示例： + +``` +◆ Nous Tool Gateway + Nous Portal ✓ managed tools available + Web tools ✓ active via Nous subscription + Image gen ✓ active via Nous subscription + TTS ✓ active via Nous subscription + Browser ○ active via Browser Use key + Modal ○ available via subscription (optional) +``` + +标记为 “active via Nous subscription” 的即经网关路由；带自有 Key 的会显示当前激活的提供商。 + +## 进阶：自建网关 + +若使用自建或自定义网关，可在 `~/.hermes/.env` 中用环境变量覆盖端点： + +```bash +TOOL_GATEWAY_DOMAIN=nousresearch.com # 网关路由基础域名 +TOOL_GATEWAY_SCHEME=https # http 或 https（默认 https） +TOOL_GATEWAY_USER_TOKEN=your-token # 鉴权 Token（通常由程序自动填充） +FIRECRAWL_GATEWAY_URL=https://... # 单独覆盖 Firecrawl 端点 +``` + +这些变量与订阅状态无关，始终可在配置中看到，便于自建基础设施。 + +## 常见问题 + +### 需要删掉已有的 API Key 吗？ + +不需要。`use_gateway: true` 时运行时会跳过直连 Key 并走网关；Key 仍保留在 `.env`。之后若关闭网关，会自动恢复使用直连 Key。 + +### 能否部分工具走网关、部分走直连？ + +可以。`use_gateway` 按工具独立配置。例如：网页与文生图走网关，TTS 用 ElevenLabs，浏览器用 Browserbase。 + +### 订阅到期会怎样？ + +经网关路由的工具会停止工作，直到你 [续订](https://portal.nousresearch.com/manage-subscription) 或通过 `hermes tools` 改回直连 Key。 + +### 与「消息网关」（各聊天平台）是否冲突？ + +不冲突。Tool Gateway 作用于**工具运行时**的 API 路由，与 CLI、Telegram、Discord 等入口无关。 + +### Modal 算在 Tool Gateway 里吗？ + +Modal（无服务器终端后端）可作为 Nous 订阅的可选附加能力，但**不会**由 Tool Gateway 安装向导一并打开——请单独通过 `hermes setup terminal` 或在 `config.yaml` 中配置。 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/windows-wsl-quickstart.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/windows-wsl-quickstart.md new file mode 100644 index 0000000000..a058fc0cc2 --- /dev/null +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/windows-wsl-quickstart.md @@ -0,0 +1,65 @@ +--- +title: "Windows 用户快速上手（WSL2）" +description: "在 Windows 上通过 WSL2 安装 uv、Hermes 与 Tool Gateway 的推荐路径与常见坑" +sidebar_label: "Windows（WSL2）" +sidebar_position: 2 +--- + +# Windows 用户快速上手（WSL2） + +上游开发与 CI 以 **Linux / macOS** 为主；在 Windows 上，**官方推荐路径是 WSL2**，而不是在「旧版原生 CMD/PowerShell」里直接跑完整 Hermes 栈。本页给出从 0 到可跑 `hermes` + Tool Gateway 的最短闭环。 + +## 1. 安装 WSL2 与发行版 + +1. 以管理员打开 PowerShell，安装 WSL 与默认 Ubuntu（具体命令以 [微软文档](https://learn.microsoft.com/zh-cn/windows/wsl/install) 为准）： + ```powershell + wsl --install + ``` +2. 重启后完成 Ubuntu 首次用户名/密码设置。 +3. 在 Microsoft Store 或 `wsl --list --online` 中可选用较新 Ubuntu LTS，便于获得较新的 `glibc` 与 Python 工具链。 + +:::caution 关于「原生 Windows」 +若你只在 PowerShell 里装 Python/uv，可能遇到路径、子进程、网关单例与 Token 缓存等与上游假设不一致的问题。**请优先在 WSL 终端内**完成安装与日常使用。 +::: + +## 2. 在 WSL 内安装 `uv` + +在 **WSL 的 Bash** 中执行（勿混用 Windows 路径）： + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +将 `uv` 加入当前 shell 的 `PATH`（安装脚本结尾会提示），然后： + +```bash +uv --version +``` + +## 3. 获取 Hermes Agent + +在 WSL 里 clone 本仓库（或你的 fork），进入目录后按 [安装说明](/getting-started/installation) 使用 `uv sync` / 文档中的推荐命令安装依赖。 + +:::tip 路径与权限 +Hermes 默认配置目录为 `~/.hermes/`（在 WSL 内即 Linux 家目录）。请勿把 WSL 项目放在会被 Windows 杀毒实时深度扫描的极慢盘符上；推荐放在 WSL 文件系统（例如 `~/projects/...`）而非 `/mnt/c/...` 下的重度 IO 路径。 +::: + +## 4. 模型与 Tool Gateway + +1. 在 WSL 内运行 `hermes model`，按提示绑定 **Nous Portal**（或其他提供商）。 +2. 付费订阅用户可启用 **[Tool Gateway](/user-guide/features/tool-gateway)**，用于网页搜索、文生图、TTS、浏览器自动化等，而无需单独配置 `FAL_KEY` / Firecrawl 等（详见该页）。 +3. 文生图模型列表与计费说明见 **[文生图](/user-guide/features/image-generation)**。 + +## 5. 常见故障速查 + +| 现象 | 建议 | +|------|------| +| 网关相关进程重复 / 端口占用 | 确认是否同时在 Windows 侧与 WSL 侧各启动了一份 agent；同一机器上只保留**一个**常驻会话。 | +| `hermes` 找不到 | 确认 `uv run hermes` 或按安装文档将 CLI 暴露到 `PATH`；命令应在 **WSL** 内执行。 | +| 图像工具 4xx | 可能是 Portal 尚未代理该 FAL 模型；可换模型或配置直连 `FAL_KEY`（见文生图文档）。 | + +## 6. 下一步 + +- 英文摘要页（默认语言）：仍保留轻量说明，便于非中文读者理解 WSL2 要求。 +- 深入 CLI：见 [CLI 界面](/user-guide/cli)。 +- 全局配置项：见 [配置说明](/user-guide/configuration)。 diff --git a/website/sidebars.ts b/website/sidebars.ts index a24366474e..96ea3d6179 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -23,6 +23,7 @@ const sidebars: SidebarsConfig = { items: [ 'user-guide/cli', 'user-guide/tui', + 'user-guide/windows-wsl-quickstart', 'user-guide/configuration', 'user-guide/configuring-models', 'user-guide/sessions',