better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/guides/xai-grok-oauth.md

@@ -0,0 +1,243 @@
+---
+sidebar_position: 16
+title: "xAI Grok OAuth（SuperGrok / X Premium+）"
+description: "使用 SuperGrok 或 X Premium+ 订阅登录，在 Hermes Agent 中使用 Grok 模型——无需 API 密钥"
+---
+
+# xAI Grok OAuth（SuperGrok / X Premium+）
+
+Hermes Agent 通过基于浏览器的 OAuth 登录流程支持 xAI Grok，认证服务器为 [accounts.x.ai](https://accounts.x.ai)，支持 **SuperGrok 订阅**（[grok.com](https://x.ai/grok)）或 **X Premium+ 订阅**（已关联的 X 账号）。无需 `XAI_API_KEY`——登录一次后，Hermes 会在后台自动刷新会话。
+
+当你使用拥有 Premium+ 的 X 账号登录时，xAI 会自动将订阅状态关联到你的 xAI 会话，因此 OAuth 流程与直接 SuperGrok 订阅者的体验完全相同。
+
+该传输层复用 `codex_responses` 适配器（xAI 暴露了 Responses 风格的端点），因此推理、工具调用、流式传输和 prompt（提示词）缓存无需任何适配器改动即可正常工作。
+
+同一 OAuth bearer token 也会被 Hermes 中所有直连 xAI 的功能复用——TTS、图像生成、视频生成和转录——因此单次登录即可覆盖全部四项功能。
+
+## 概览
+
+| 项目 | 值 |
+|------|-------|
+| Provider ID | `xai-oauth` |
+| 显示名称 | xAI Grok OAuth (SuperGrok / X Premium+) |
+| 认证类型 | 浏览器 OAuth 2.0 设备代码 |
+| 传输层 | xAI Responses API（`codex_responses`） |
+| 默认模型 | `grok-4.6` |
+| 端点 | `https://api.x.ai/v1` |
+| 认证服务器 | `https://accounts.x.ai` |
+| 需要环境变量 | 否（此 provider 不使用 `XAI_API_KEY`） |
+| 订阅要求 | [SuperGrok](https://x.ai/grok) 或 [X Premium+](https://x.com/i/premium_sign_up)——见下方说明 |
+
+## 前提条件
+
+- Python 3.9+
+- 已安装 Hermes Agent
+- 你的 xAI 账号拥有有效的 **SuperGrok** 订阅，**或**你登录所用的 X 账号拥有 **X Premium+** 订阅（xAI 会自动关联订阅）
+- 任意可打开打印出的验证 URL 的浏览器
+
+:::warning xAI 可能按套餐限制 OAuth API 访问
+xAI 的后端对 OAuth API 接口维护自己的白名单，已有记录显示即使应用内订阅处于激活状态，标准 SuperGrok 订阅者也会收到 `HTTP 403`（见 issue [#26847](https://github.com/NousResearch/hermes-agent/issues/26847)）。如果浏览器中 OAuth 登录成功但推理返回 403，请设置 `XAI_API_KEY` 并切换到 API 密钥路径（`provider: xai`）——该接口目前不受相同限制。
+:::
+
+## 快速开始
+
+```bash
+# 启动 provider 和模型选择器
+hermes model
+# → 从 provider 列表中选择 "xAI Grok OAuth (SuperGrok / X Premium+)"
+# → Hermes 打开或打印 accounts.x.ai 验证 URL
+# → 如有提示，输入显示的代码，然后在浏览器中批准访问
+# → 选择模型（grok-4.6 在列表顶部）
+# → 开始对话
+
+hermes
+```
+
+首次登录后，凭据存储在 `~/.hermes/auth.json` 中，并在过期前自动刷新。
+
+## 手动登录
+
+你可以不经过模型选择器直接触发登录：
+
+```bash
+hermes auth add xai-oauth
+```
+
+### 远程 / 无头会话
+
+在没有浏览器的服务器、容器、仅限浏览器的远程控制台（Cloud Shell、Codespaces、EC2 Instance Connect）或 SSH 会话中，Hermes 会打印 xAI 验证 URL 和用户代码。在笔记本电脑或云控制台的任意浏览器中打开该 URL，如有提示则输入代码，Hermes 会持续轮询直到 xAI 批准登录。无需 SSH 隧道或本地回调监听器。
+
+```bash
+hermes auth add xai-oauth --no-browser
+# 在浏览器中打开打印出的验证 URL。
+```
+
+Web 仪表盘和桌面应用使用相同的设备代码流程：显示验证 URL 和用户代码，并在你批准访问后在后台轮询。
+
+## 登录流程说明
+
+1. Hermes 向 `auth.x.ai` 请求设备代码。
+2. 你打开验证 URL，登录，如有提示则输入显示的代码，并批准访问。
+3. Hermes 轮询 xAI 直到批准，然后将 token 保存到 `~/.hermes/auth.json`。
+4. 此后，Hermes 在后台刷新 access token——你将保持登录状态，直到执行 `hermes auth logout xai-oauth` 或在 xAI 账号设置中撤销访问。
+
+## 检查登录状态
+
+```bash
+hermes doctor
+```
+
+`◆ Auth Providers` 部分将显示每个 provider 的当前状态，包括 `xai-oauth`。
+
+## 切换模型
+
+```bash
+hermes model
+# → 选择 "xAI Grok OAuth (SuperGrok / X Premium+)"
+# → 从模型列表中选择（grok-4.6 固定在顶部）
+```
+
+或直接设置模型：
+
+```bash
+hermes config set model.default grok-4.6
+hermes config set model.provider xai-oauth
+```
+
+## 配置参考
+
+登录后，`~/.hermes/config.yaml` 将包含：
+
+```yaml
+model:
+  default: grok-4.6
+  provider: xai-oauth
+  base_url: https://api.x.ai/v1
+```
+
+### Provider 别名
+
+以下所有别名均解析为 `xai-oauth`：
+
+```bash
+hermes --provider xai-oauth        # 规范名称
+hermes --provider grok-oauth       # 别名
+hermes --provider x-ai-oauth       # 别名
+hermes --provider xai-grok-oauth   # 别名
+```
+
+## 直连 xAI 工具（TTS / 图像 / 视频 / 转录 / X 搜索）
+
+通过 OAuth 登录后，每个直连 xAI 的工具都会自动复用同一 bearer token——**无需单独配置**，除非你更倾向于使用 API 密钥。
+
+为每个工具选择后端：
+
+```bash
+hermes tools
+# → Text-to-Speech       → "xAI TTS"
+# → Image Generation     → "xAI Grok Imagine (image)"
+# → Video Generation     → "xAI Grok Imagine"
+# → X (Twitter) Search   → "xAI Grok OAuth (SuperGrok / X Premium+)"
+```
+
+如果 OAuth token 已存储，选择器会确认并跳过凭据提示。如果既没有 OAuth 也没有设置 `XAI_API_KEY`，选择器会提供三选一菜单：OAuth 登录、粘贴 API 密钥或跳过。
+
+:::note 视频生成默认关闭
+`video_gen` 工具集默认禁用。在 `hermes tools` → `🎬 Video Generation`（按空格键）中启用后，agent 才能调用 `video_generate`。否则 agent 可能回退到内置的 ComfyUI 技能，该技能同样标记为视频生成。
+:::
+
+:::note 配置 xAI 凭据后 X 搜索自动启用
+只要配置了 xAI 凭据（SuperGrok / X Premium+ OAuth token 或 `XAI_API_KEY`），`x_search` 工具集就会自动启用。如不需要，请通过 `hermes tools` → `🐦 X (Twitter) Search`（按空格键）显式禁用。该工具通过 xAI 内置的 `x_search` Responses API 路由——支持 **SuperGrok / X Premium+ OAuth 登录**或付费 `XAI_API_KEY`，两者同时配置时优先使用 OAuth（消耗订阅配额而非 API 费用）。未配置任何 xAI 凭据时，无论工具集是否启用，工具 schema 都对模型隐藏。
+:::
+
+### 模型
+
+| 工具 | 模型 | 说明 |
+|------|-------|-------|
+| 对话 | `grok-4.6` | 默认；固定在 OAuth 选择器顶部 |
+| 对话 | `grok-build-0.1` | 面向编程的 Grok Build 模型 |
+| 对话 | `grok-4.3` | 之前的默认 |
+| 对话 | `grok-4.20-0309-reasoning` | 推理变体 |
+| 对话 | `grok-4.20-0309-non-reasoning` | 非推理变体 |
+| 对话 | `grok-4.20-multi-agent-0309` | 多 agent 变体 |
+| 图像 | `grok-imagine-image` | 默认；约 5–10 秒 |
+| 图像 | `grok-imagine-image-2.0` | 版式/排版感知；最强画质；约 10–20 秒 |
+| 图像 | `grok-imagine-image-quality` | 更高保真度；约 10–20 秒 |
+| 视频 | `grok-imagine-video` | 文本转视频 |
+| 视频 | `grok-imagine-video-1.5-preview` | 图像转视频；日期别名 `grok-imagine-video-1.5-2026-05-30` |
+| TTS | （默认音色） | xAI `/v1/tts` 端点 |
+
+对话模型目录从磁盘上的 `models.dev` 缓存实时获取；缓存刷新后，新的 xAI 模型会自动出现。`grok-4.6` 始终固定在列表顶部。
+
+## 环境变量
+
+| 变量 | 作用 |
+|----------|--------|
+| `XAI_BASE_URL` | 覆盖默认的 `https://api.x.ai/v1` 端点（极少需要）。 |
+
+要将 xAI 设为活跃 provider，请在 `config.yaml` 中设置 `model.provider: xai-oauth`（使用 `hermes setup` 进行引导配置），或在单次调用时传入 `--provider xai-oauth`。
+
+## 故障排查
+
+### Token 过期——未自动重新登录
+
+Hermes 在每次会话前刷新 token，并在收到 401 时响应式地再次刷新。如果刷新因 `invalid_grant` 失败（刷新 token 被撤销或账号已轮换），Hermes 会显示类型化的重新认证消息，而不是崩溃。
+
+当刷新失败是终态时（HTTP 4xx、`invalid_grant`、授权被撤销等），Hermes 将刷新 token 标记为失效并在本地隔离——后续调用跳过注定失败的刷新尝试，而不是反复重放同一个 401。agent 显示一条"需要重新认证"消息，并在你再次登录前保持等待。
+
+**修复方法：** 再次运行 `hermes auth add xai-oauth` 开始全新登录。下次成功交换后隔离状态自动清除。
+
+### 授权超时
+
+设备代码批准有有限的过期窗口（xAI 在设备代码响应中设置 `expires_in`，通常为数十分钟量级）。如果你未在时限内批准登录，Hermes 会抛出超时错误。
+
+**修复方法：** 重新运行 `hermes auth add xai-oauth`（或 `hermes model`）。流程重新开始。
+
+### 从远程服务器登录
+
+在 SSH 或容器会话中，Hermes 打印验证 URL 和用户代码，而不是打开浏览器。在笔记本电脑或云控制台的浏览器中打开该 URL——xAI Grok OAuth 无需 SSH 端口转发。
+
+```bash
+hermes auth add xai-oauth --no-browser
+```
+
+回环重定向类 provider（Spotify、MCP 服务器）请参阅 [OAuth over SSH / Remote Hosts](./oauth-over-ssh.md)。
+
+### 登录成功后 HTTP 403（套餐 / 权限问题）
+
+浏览器中 OAuth 完成，token 已保存，但推理或 token 刷新返回 `HTTP 403`，消息类似于 *"The caller does not have permission to execute the specified operation"*。
+
+这**不是** token 过期问题——重新运行 `hermes model` 不会改变结果。xAI 的后端已被观察到将 OAuth API 访问限制在特定 SuperGrok 套餐，即使应用内订阅处于激活状态（issue [#26847](https://github.com/NousResearch/hermes-agent/issues/26847)）。
+
+**修复方法：** 设置 `XAI_API_KEY` 并切换到 API 密钥路径：
+
+```bash
+export XAI_API_KEY=xai-...
+hermes config set model.provider xai
+```
+
+或在 [x.ai/grok](https://x.ai/grok) 升级订阅（如果必须使用 OAuth 路径）。
+
+### 运行时出现"No xAI credentials found"错误
+
+auth 存储中没有 `xai-oauth` 条目，也未设置 `XAI_API_KEY`。你尚未登录，或凭据文件已被删除。
+
+**修复方法：** 运行 `hermes model` 并选择 xAI Grok OAuth provider，或运行 `hermes auth add xai-oauth`。
+
+## 退出登录
+
+删除所有已存储的 xAI Grok OAuth 凭据：
+
+```bash
+hermes auth logout xai-oauth
+```
+
+这会清除 `auth.json` 中的单例 OAuth 条目以及 `xai-oauth` 的所有凭据池行。如果只想删除单个池条目，请使用 `hermes auth remove xai-oauth <index|id|label>`（运行 `hermes auth list xai-oauth` 查看列表）。
+
+## 另请参阅
+
+- [OAuth over SSH / Remote Hosts](./oauth-over-ssh.md) — 如果 Hermes 与浏览器不在同一台机器上，必读
+- [AI Providers 参考](../integrations/providers.md)
+- [环境变量](../reference/environment-variables.md)
+- [配置](../user-guide/configuration.md)
+- [语音与 TTS](../user-guide/features/tts.md)

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/index.mdx

@@ -0,0 +1,117 @@
+---
+slug: /
+sidebar_position: 0
+title: "Hermes Agent 文档"
+description: "由 Nous Research 构建的自我改进 AI 智能体。内置学习循环，从经验中创建技能，在使用过程中持续改进，并跨会话保持记忆。"
+hide_table_of_contents: true
+displayed_sidebar: docs
+---
+
+import Link from "@docusaurus/Link";
+
+# Hermes Agent
+
+由 [Nous Research](https://nousresearch.com) 构建的自我改进 AI 智能体。唯一内置学习循环的智能体——它从经验中创建技能，在使用过程中持续改进，主动提示自身持久化知识，并在会话间不断深化对你的建模。
+
+<div
+  style={{
+    display: "flex",
+    gap: "1rem",
+    marginBottom: "2rem",
+    flexWrap: "wrap",
+  }}
+>
+  <Link
+    to="/getting-started/installation"
+    style={{
+      display: "inline-block",
+      padding: "0.6rem 1.2rem",
+      backgroundColor: "#FFD700",
+      color: "#07070d",
+      borderRadius: "8px",
+      fontWeight: 600,
+      textDecoration: "none",
+    }}
+  >
+    快速开始 →
+  </Link>
+  <a
+    href="https://github.com/NousResearch/hermes-agent"
+    style={{
+      display: "inline-block",
+      padding: "0.6rem 1.2rem",
+      border: "1px solid rgba(255,215,0,0.2)",
+      borderRadius: "8px",
+      textDecoration: "none",
+    }}
+  >
+    在 GitHub 上查看
+  </a>
+</div>
+
+## 安装
+
+**Linux / macOS / WSL2**
+
+```bash
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+```
+
+**Windows（原生，PowerShell）** — _早期测试版，[详情 →](/user-guide/windows-native)_
+
+```powershell
+iex (irm https://hermes-agent.nousresearch.com/install.ps1)
+```
+
+**Android（Termux）** — 与 Linux 相同的 curl 一行命令；安装程序会自动检测 Termux。
+
+请参阅完整的 **[安装指南](/getting-started/installation)**，了解安装程序的具体操作、按用户与 root 的目录布局以及 Windows 相关说明。
+
+## Hermes Agent 是什么？
+
+它不是绑定在 IDE 上的编程副驾驶，也不是对单一 API 的聊天机器人封装。它是一个**自主智能体**，运行时间越长，能力越强。它可以部署在任何地方——5 美元的 VPS、GPU 集群，或者闲置时几乎零成本的 serverless 基础设施（Daytona、Modal）。在 Telegram 上与它对话，同时让它在你从未亲自 SSH 登录的云端虚拟机上工作。它不依赖你的本地电脑。
+
+## 快速链接
+
+|                                                                       |                                                                    |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| 🚀 **[安装](/getting-started/installation)**                          | 在 Linux、macOS、WSL2 或原生 Windows（早期测试版）上 60 秒完成安装 |
+| 📖 **[快速入门教程](/getting-started/quickstart)**                    | 第一次对话及值得尝试的核心功能                                     |
+| 🗺️ **[学习路径](/getting-started/learning-path)**                     | 根据你的经验水平找到合适的文档                                     |
+| ⚙️ **[配置](/user-guide/configuration)**                              | 配置文件、提供商、模型及选项                                       |
+| 💬 **[消息网关](/user-guide/messaging)**                              | 配置 Telegram、Discord、Slack、WhatsApp、Teams 等平台              |
+| 🔧 **[工具与工具集](/user-guide/features/tools)**                     | 70+ 内置工具及其配置方式                                           |
+| 🧠 **[记忆系统](/user-guide/features/memory)**                        | 跨会话持续增长的持久记忆                                           |
+| 📚 **[技能系统](/user-guide/features/skills)**                        | 智能体创建并复用的程序性记忆                                       |
+| 🔌 **[MCP 集成](/user-guide/features/mcp)**                           | 连接 MCP 服务器、过滤其工具，并安全扩展 Hermes                     |
+| 🧭 **[在 Hermes 中使用 MCP](/guides/use-mcp-with-hermes)**            | 实用的 MCP 配置模式、示例与教程                                    |
+| 🎙️ **[语音模式](/user-guide/features/voice-mode)**                    | 在 CLI、Telegram、Discord 及 Discord 语音频道中进行实时语音交互    |
+| 🗣️ **[在 Hermes 中使用语音模式](/guides/use-voice-mode-with-hermes)** | Hermes 语音工作流的实操配置与使用模式                              |
+| 🎭 **[个性与 SOUL.md](/user-guide/features/personality)**             | 通过全局 SOUL.md 定义 Hermes 的默认风格                            |
+| 📄 **[上下文文件](/user-guide/features/context-files)**               | 影响每次对话的项目上下文文件                                       |
+| 🔒 **[安全](/user-guide/security)**                                   | 命令审批、授权与容器隔离                                           |
+| 💡 **[技巧与最佳实践](/guides/tips)**                                 | 快速上手，充分发挥 Hermes 的潜力                                   |
+| 🏗️ **[架构](/developer-guide/architecture)**                          | 底层工作原理                                                       |
+| ❓ **[常见问题与故障排查](/reference/faq)**                           | 常见问题及解决方案                                                 |
+
+## 核心功能
+
+- **闭环学习循环** — 智能体管理的记忆，配合定期提示、自主技能创建、使用中的技能自我改进、基于 FTS5 的跨会话召回与 LLM 摘要，以及 [Honcho](https://github.com/plastic-labs/honcho) 辩证式用户建模
+- **随处运行，不限于本地** — 6 种终端后端：本地、Docker、SSH、Daytona、Singularity、Modal。Daytona 和 Modal 提供 serverless 持久化——环境闲置时休眠，几乎零成本
+- **在你所在的地方** — CLI、Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost、Email、SMS、DingTalk、Feishu、WeCom、Weixin、QQ Bot、Yuanbao、BlueBubbles、Home Assistant、Microsoft Teams、Google Chat 等——通过一个网关支持 20+ 平台
+- **由模型训练者构建** — 由 [Nous Research](https://nousresearch.com) 创建，该实验室是 Hermes、Nomos 和 Psyche 背后的团队。支持 [Nous Portal](https://portal.nousresearch.com)、[OpenRouter](https://openrouter.ai)、OpenAI 或任意端点
+- **定时自动化** — 内置 cron，可向任意平台投递
+- **委托与并行** — 派生隔离的子智能体以并行处理多个工作流。通过 `execute_code` 实现程序化工具调用，将多步骤流水线压缩为单次推理调用
+- **开放标准技能** — 兼容 [agentskills.io](https://agentskills.io)。技能可移植、可共享，并通过 Skills Hub 接受社区贡献
+- **完整的 Web 控制** — 搜索、提取、浏览、视觉、图像生成、TTS
+- **MCP 支持** — 连接任意 MCP 服务器以扩展工具能力
+- **研究就绪** — 批处理、轨迹导出、基于 Atropos 的 RL 训练。由 [Nous Research](https://nousresearch.com) 构建——该实验室是 Hermes、Nomos 和 Psyche 模型背后的团队
+
+## 面向 LLM 和编程智能体
+
+本文档的机器可读入口：
+
+- **[`/llms.txt`](/llms.txt)** — 每个文档页面的精选索引，附简短描述。约 17 KB，可安全加载到 LLM 上下文中。
+- **[`/llms-full.txt`](/llms-full.txt)** — 所有文档页面拼接为单一 markdown 文件，支持一次性摄取。约 1.8 MB。
+
+两个文件同样可通过 `/docs/llms.txt` 和 `/docs/llms-full.txt` 访问。每次部署时全新生成。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/integrations/buzz.md

@@ -0,0 +1,57 @@
+---
+sidebar_position: 4
+title: "Buzz 集成"
+description: "将 Hermes Agent 连接到 Buzz（Block 基于 Nostr 的人机协作工作区）的全部三种方式"
+---
+
+# Buzz 集成
+
+[Buzz](https://github.com/block/buzz) 是 Block 开源、可自托管的工作区，人类和 AI agent 共享同一批频道。它构建在 Nostr 之上：每条消息都是你自己中继上的签名事件，每个参与者——无论人类还是 agent——都是一个密钥对。
+
+Hermes 有三种方式与 Buzz 集成。根据 Hermes 运行的位置和你的需求选择：
+
+| | ① Desktop 运行时 | ② 中继桥接（ACP） | ③ 原生网关平台 |
+|---|---|---|---|
+| **是什么** | Buzz Desktop 在本地将 Hermes 作为托管 harness 启动 | Buzz 的 `buzz-acp` 通过 stdio 将频道桥接到 `hermes acp` | Hermes 网关将 Buzz 作为一等消息平台加入 |
+| **Hermes 运行在** | 你的桌面，由 Buzz 启动 | 服务器，由 `buzz-acp` 启动 | 你自己的网关，与 Telegram/Discord 等并列 |
+| **适合** | 零配置在 Buzz Desktop 中试用 Hermes | 由 Buzz 掌管传输的托管 agent 身份 | 完整 Hermes：记忆、技能、审批、cron、会话 |
+| **入站** | ACP stdio | ACP stdio（经中继 WebSocket） | NIP-42 认证的 Nostr WebSocket（轮询兜底） |
+| **设置** | 自动发现 | `buzz-acp` 环境变量 | `hermes gateway setup` → Buzz |
+
+## ① Buzz Desktop 托管运行时
+
+Buzz Desktop 将 Hermes 作为预设运行时提供。按常规方式安装 Hermes 后，打开 **Settings → Runtimes**，Hermes 会自动出现——发现机制在登录 shell 的 PATH 上解析 `hermes-acp` 启动器，安装器会将其写入 `~/.local/bin`（较旧安装由 `hermes update` 自动补齐）。
+
+完整设置、故障排查和安全注意事项（Buzz 会自动批准工具权限——请保持 agent 为 owner-only）：**[ACP 宿主集成 → Buzz Desktop](/user-guide/features/acp#buzz-desktop)**
+
+## ② 中继桥接（buzz-acp + ACP）
+
+适合托管的 Hermes 身份加入 Buzz *频道*，由 Buzz 自己的 harness 掌管传输：
+
+```text
+Buzz relay <-- WebSocket --> buzz-acp <-- ACP over stdio --> Hermes Agent
+```
+
+被启动的 Hermes 使用该主机上相同的配置、凭据、记忆和技能。密钥铸造、频道发现、所有者遥测（`BUZZ_ACP_RELAY_OBSERVER`）和无头权限指南：**[ACP 宿主集成 → Buzz 频道（中继桥接）](/user-guide/features/acp)**
+
+## ③ 原生网关平台（完整 Hermes 推荐）
+
+内置的 `buzz` 平台插件让 Buzz 成为普通的 Hermes 消息平台——频道、私信、提及门控、话题回复、表情回应、图片和 cron 投递（`deliver=buzz`），同时保留 Hermes 自己的审批、记忆和会话管理。入站通过持久的 NIP-42 认证 Nostr WebSocket（无依赖 BIP-340 签名）到达，自动兜底到 CLI 轮询；出站通过 `buzz` CLI。
+
+```bash
+hermes gateway setup   # 选择 Buzz
+```
+
+完整配置参考（环境变量、config.yaml、传输模式、访问控制）：**[消息平台 → Buzz](/user-guide/messaging/buzz)**
+
+## 该选哪一个？
+
+- **Buzz Desktop 用户，只是探索** → ① 开箱即用。
+- **运营社区中继，想要由 Buzz 托管的 agent 身份** → ②。
+- **已把 Hermes 作为你的 agent，想把 Buzz 作为又一个频道** → ③。这是最深度的集成，保留 Hermes 的全部能力。
+
+①/② 与 ③ 使用不同的身份和传输；请为 ③ 铸造专用的 Nostr 密钥对。适配器会对 relay+pubkey 组合加作用域锁，因此两个 Hermes profile 不会意外驱动同一个 Buzz 身份。
+
+## 致谢
+
+Buzz 集成由社区共同构建：@SHL0MS（PATH 启动器 + Desktop 安全审计）、@NYTEMODEONLY（中继桥接文档）、@rob-coco（平台适配器）、@ScaleLeanChris（Nostr WebSocket 传输 + NIP-42/BIP-340 签名）、@jethac（多 agent 验证）。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/integrations/index.md

@@ -0,0 +1,100 @@
+---
+title: "集成"
+sidebar_label: "概览"
+sidebar_position: 0
+---
+
+# 集成
+
+Hermes Agent 可连接外部系统，用于 AI 推理、工具服务器、IDE 工作流、程序化访问等。这些集成扩展了 Hermes 的能力边界与运行环境。
+
+## AI 提供商与路由
+
+Hermes 开箱即支持多个 AI 推理提供商。使用 `hermes model` 进行交互式配置，或在 `config.yaml` 中直接设置。
+
+- **[AI 提供商](/user-guide/features/provider-routing)** — OpenRouter、Anthropic、OpenAI、Google 以及任何兼容 OpenAI 的端点。Hermes 会自动检测每个提供商的能力，包括视觉、流式传输和工具调用。
+- **[提供商路由](/user-guide/features/provider-routing)** — 精细控制哪些底层提供商处理你的 OpenRouter 请求。通过排序、白名单、黑名单和显式优先级排序，在成本、速度或质量之间优化。
+- **[备用提供商](/user-guide/features/fallback-providers)** — 当主模型遇到错误时，自动故障转移到备用 LLM 提供商。包括主模型回退，以及用于视觉、压缩和网页提取的独立辅助任务回退。
+
+## 工具服务器（MCP）
+
+- **[MCP 服务器](/user-guide/features/mcp)** — 通过 Model Context Protocol 将 Hermes 连接到外部工具服务器。无需编写原生 Hermes 工具，即可访问来自 GitHub、数据库、文件系统、浏览器栈、内部 API 等的工具。支持 stdio 和 SSE 两种传输方式、按服务器过滤工具，以及具备能力感知的资源/prompt 注册。
+
+## 网页搜索后端
+
+`web_search` 和 `web_extract` 工具支持四个后端提供商，通过 `config.yaml` 或 `hermes tools` 配置：
+
+| 后端 | 环境变量 | 搜索 | 提取 | 爬取 |
+|---------|---------|--------|---------|-------|
+| **Firecrawl**（默认） | `FIRECRAWL_API_KEY` | ✔ | ✔ | ✔ |
+| **Parallel** | `PARALLEL_API_KEY` | ✔ | ✔ | — |
+| **Tavily** | `TAVILY_API_KEY` | ✔ | ✔ | ✔ |
+| **Exa** | `EXA_API_KEY` | ✔ | ✔ | — |
+
+快速配置示例：
+
+```yaml
+web:
+  backend: firecrawl    # firecrawl | searxng | brave-free | ddgs | tavily | exa | parallel | xai
+```
+
+若未设置 `web.backend`，后端将根据可用的 API key 自动检测。也支持通过 `FIRECRAWL_API_URL` 使用自托管的 Firecrawl。
+
+## 浏览器自动化
+
+Hermes 内置完整的浏览器自动化功能，提供多种后端选项，用于网站导航、表单填写和信息提取：
+
+- **Browserbase** — 托管云端浏览器，具备反机器人工具、CAPTCHA 解决和住宅代理
+- **Browser Use** — 备选云端浏览器提供商
+- **本地 Chromium 系 CDP** — 使用 `/browser connect` 连接正在运行的 Chrome、Brave、Chromium 或 Edge 浏览器
+- **本地 Chromium** — 通过 `agent-browser` CLI 使用无头本地浏览器
+
+详见[浏览器自动化](/user-guide/features/browser)的配置与使用说明。
+
+## 语音与 TTS 提供商
+
+跨所有消息平台的文字转语音与语音转文字：
+
+| 提供商 | 质量 | 费用 | API Key |
+|----------|---------|------|---------|
+| **Edge TTS**（默认） | 良好 | 免费 | 无需 |
+| **ElevenLabs** | 优秀 | 付费 | `ELEVENLABS_API_KEY` |
+| **OpenAI TTS** | 良好 | 付费 | `VOICE_TOOLS_OPENAI_KEY` |
+| **MiniMax** | 良好 | 付费 | `MINIMAX_API_KEY` |
+| **NeuTTS** | 良好 | 免费 | 无需 |
+
+语音转文字支持六个提供商：本地 faster-whisper（免费，设备端运行）、本地命令封装器、Groq、OpenAI Whisper API、Mistral 和 xAI。语音消息转录支持 Telegram、Discord、WhatsApp 及其他消息平台。详见[语音与 TTS](/user-guide/features/tts) 和[语音模式](/user-guide/features/voice-mode)。
+
+## IDE 与编辑器集成
+
+- **[IDE 集成（ACP）](/user-guide/features/acp)** — 在兼容 ACP 的编辑器（如 VS Code、Zed 和 JetBrains）中使用 Hermes Agent。Hermes 作为 ACP 服务器运行，在编辑器内渲染聊天消息、工具活动、文件差异和终端命令。
+
+## 程序化访问
+
+- **[API 服务器](/user-guide/features/api-server)** — 将 Hermes 暴露为兼容 OpenAI 的 HTTP 端点。任何支持 OpenAI 格式的前端——Open WebUI、LobeChat、LibreChat、NextChat、ChatBox——均可连接并将 Hermes 作为后端使用，享有其完整工具集。
+
+## 记忆与个性化
+
+- **[内置记忆](/user-guide/features/memory)** — 通过 `MEMORY.md` 和 `USER.md` 文件实现持久化、精选记忆。Agent 维护有界的个人笔记和用户画像数据存储，跨会话保留。
+- **[记忆提供商](/user-guide/features/memory-providers)** — 接入外部记忆后端以实现更深度的个性化。支持八个提供商：Honcho（辩证推理）、OpenViking（分层检索）、Mem0（云端提取）、Hindsight（知识图谱）、Holographic（本地 SQLite）、RetainDB（混合搜索）、ByteRover（基于 CLI）和 Supermemory。
+
+## 消息平台
+
+Hermes 可作为 gateway（网关）机器人运行于 19+ 个消息平台，均通过同一 `gateway` 子系统配置：
+
+- **[Telegram](/user-guide/messaging/telegram)**、**[Discord](/user-guide/messaging/discord)**、**[Slack](/user-guide/messaging/slack)**、**[WhatsApp](/user-guide/messaging/whatsapp)**、**[Signal](/user-guide/messaging/signal)**、**[Matrix](/user-guide/messaging/matrix)**、**[Mattermost](/user-guide/messaging/mattermost)**、**[Email](/user-guide/messaging/email)**、**[SMS](/user-guide/messaging/sms)**、**[DingTalk](/user-guide/messaging/dingtalk)**、**[Feishu/Lark](/user-guide/messaging/feishu)**、**[WeCom](/user-guide/messaging/wecom)**、**[WeCom Callback](/user-guide/messaging/wecom-callback)**、**[Weixin](/user-guide/messaging/weixin)**、**[BlueBubbles](/user-guide/messaging/bluebubbles)**、**[QQ Bot](/user-guide/messaging/qqbot)**、**[Yuanbao](/user-guide/messaging/yuanbao)**、**[Home Assistant](/user-guide/messaging/homeassistant)**、**[Microsoft Teams](/user-guide/messaging/teams)**、**[Webhooks](/user-guide/messaging/webhooks)**
+
+平台对比表和配置指南详见[消息 Gateway 概览](/user-guide/messaging)。
+
+## 家庭自动化
+
+- **[Home Assistant](/user-guide/messaging/homeassistant)** — 通过四个专用工具（`ha_list_entities`、`ha_get_state`、`ha_list_services`、`ha_call_service`）控制智能家居设备。配置 `HASS_TOKEN` 后，Home Assistant 工具集将自动激活。
+
+## 插件
+
+- **[插件系统](/user-guide/features/plugins)** — 无需修改核心代码，通过自定义工具、生命周期 hook（钩子）和 CLI 命令扩展 Hermes。插件从 `~/.hermes/plugins/`、项目本地 `.hermes/plugins/` 以及通过 pip 安装的入口点自动发现。
+- **[构建插件](/developer-guide/plugins)** — 创建包含工具、hook 和 CLI 命令的 Hermes 插件的分步指南。
+
+## 训练与评估
+
+- **[批处理](/user-guide/features/batch-processing)** — 并行跨数百个 prompt（提示词）运行 Agent，生成结构化的 ShareGPT 格式轨迹数据，用于训练数据生成或评估。