better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/developer-guide/web-search-provider-plugin.md

@@ -0,0 +1,260 @@
+---
+sidebar_position: 12
+title: "网页搜索提供商插件"
+description: "如何为 Hermes Agent 构建网页搜索/提取/爬取后端插件"
+---
+
+# 构建网页搜索提供商插件
+
+网页搜索提供商插件注册一个后端，用于处理 `web_search`、`web_extract` 以及（可选的）深度爬取工具调用。内置提供商——Firecrawl、SearXNG、Tavily、Exa、Parallel、Brave Search（免费层）和 DDGS——均以插件形式存放于 `plugins/web/<name>/` 目录下。你可以在该目录旁新建一个目录来添加新提供商，或覆盖已有的内置提供商。
+
+:::tip
+网页搜索是 Hermes 支持的多种**后端插件**之一。其他插件（各有其 ABC）包括：[图像生成提供商插件](/developer-guide/image-gen-provider-plugin)、[视频生成提供商插件](/developer-guide/video-gen-provider-plugin)、[记忆提供商插件](/developer-guide/memory-provider-plugin)、[上下文引擎插件](/developer-guide/context-engine-plugin)和[模型提供商插件](/developer-guide/model-provider-plugin)。通用工具/hook/CLI 插件请参阅[构建 Hermes 插件](/developer-guide/plugins)。
+:::
+
+## 发现机制
+
+Hermes 在三个位置扫描网页搜索后端：
+
+1. **内置** — `<repo>/plugins/web/<name>/`（以 `kind: backend` 自动加载，始终可用）
+2. **用户** — `~/.hermes/plugins/web/<name>/`（通过 `plugins.enabled` 或 `hermes plugins enable <name>` 按需启用）
+3. **Pip** — 声明了 `hermes_agent.plugins` 入口点的包
+
+每个插件的 `register(ctx)` 函数调用 `ctx.register_web_search_provider(...)` ——将实例注册到 `agent/web_search_registry.py` 中的注册表。各能力的活跃提供商由配置决定：
+
+| 能力 | 配置键 | 回退至 |
+|---|---|---|
+| `web_search` | `web.search_backend` | `web.backend` |
+| `web_extract` | `web.extract_backend` | `web.backend` |
+| `web_extract` 内的深度爬取模式 | `web.extract_backend` | `web.backend` |
+
+若两个键均未设置，Hermes 将根据环境中存在的 API key/URL 自动检测后端。`hermes tools` 会引导用户完成选择。
+
+## 目录结构
+
+```
+plugins/web/my-backend/
+├── __init__.py     # register() 入口点
+├── provider.py     # WebSearchProvider 子类
+└── plugin.yaml     # 包含 kind: backend 和 provides_web_providers 的清单文件
+```
+
+`brave_free/` 和 `ddgs/` 是代码库中最小的参考实现——`brave_free` 是需要 API key 的纯搜索提供商，`ddgs` 是无需 key 且懒加载 SDK 的提供商。
+
+## WebSearchProvider ABC
+
+继承 `agent.web_search_provider.WebSearchProvider`。唯一必须实现的成员是 `name`、`is_available()`，以及你所实现的 `search()` / `extract()` / `crawl()` 中的相应方法。
+
+```python
+# plugins/web/my-backend/provider.py
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List
+
+from agent.web_search_provider import WebSearchProvider
+
+
+class MyBackendWebSearchProvider(WebSearchProvider):
+    """Minimal search-only provider against the My Backend HTTP API."""
+
+    @property
+    def name(self) -> str:
+        # Stable id used in web.search_backend / web.extract_backend / web.backend
+        # config keys. Lowercase, no spaces; hyphens permitted.
+        return "my-backend"
+
+    @property
+    def display_name(self) -> str:
+        # Human label shown in `hermes tools`. Defaults to `name`.
+        return "My Backend"
+
+    def is_available(self) -> bool:
+        # Cheap check — env var present, optional dep importable, etc.
+        # MUST NOT make network calls (runs on every `hermes tools` paint).
+        return bool(os.getenv("MY_BACKEND_API_KEY", "").strip())
+
+    def supports_search(self) -> bool:
+        return True
+
+    def supports_extract(self) -> bool:
+        return False
+
+    def search(self, query: str, limit: int = 5) -> Dict[str, Any]:
+        import httpx
+
+        api_key = os.environ["MY_BACKEND_API_KEY"]
+        try:
+            resp = httpx.get(
+                "https://api.example.com/search",
+                params={"q": query, "count": max(1, min(int(limit), 20))},
+                headers={"Authorization": f"Bearer {api_key}"},
+                timeout=15,
+            )
+            resp.raise_for_status()
+            data = resp.json()
+        except httpx.HTTPError as exc:
+            return {"success": False, "error": str(exc)}
+
+        # Response shape is fixed — see "Response shape" below.
+        return {
+            "success": True,
+            "data": {
+                "web": [
+                    {
+                        "title": item.get("title", ""),
+                        "url": item.get("url", ""),
+                        "description": item.get("snippet", ""),
+                        "position": idx + 1,
+                    }
+                    for idx, item in enumerate(data.get("results", []))
+                ],
+            },
+        }
+```
+
+```python
+# plugins/web/my-backend/__init__.py
+from plugins.web.my_backend.provider import MyBackendWebSearchProvider
+
+
+def register(ctx) -> None:
+    """Plugin entry point — called once at load time."""
+    ctx.register_web_search_provider(MyBackendWebSearchProvider())
+```
+
+## plugin.yaml
+
+```yaml
+name: web-my-backend
+version: 1.0.0
+description: "My Backend web search — Bearer-auth REST API"
+author: Your Name
+kind: backend
+provides_web_providers:
+  - my-backend
+requires_env:
+  - MY_BACKEND_API_KEY
+```
+
+| 键 | 用途 |
+|---|---|
+| `kind: backend` | 将插件路由至后端加载路径 |
+| `provides_web_providers` | 该插件注册的提供商 `name` 列表——在 `register()` 运行之前，加载器即可通过此字段在 `hermes tools` 中公示插件 |
+| `requires_env` | 在 `hermes plugins install` 期间进行交互式凭据提示（富格式说明参见[构建 Hermes 插件](/developer-guide/plugins#gate-on-environment-variables)） |
+
+## ABC 参考
+
+完整契约位于 `agent/web_search_provider.py`。可覆盖的方法如下：
+
+| 成员 | 必须 | 默认值 | 用途 |
+|---|---|---|---|
+| `name` | ✅ | — | 在 `web.*_backend` 配置中使用的稳定 id |
+| `display_name` | — | `name` | 在 `hermes tools` 中显示的标签 |
+| `is_available()` | ✅ | — | 轻量可用性检查——环境变量、可选依赖等 |
+| `supports_search()` | — | `True` | `web_search` 路由的能力标志 |
+| `supports_extract()` | — | `False` | `web_extract` 路由的能力标志 |
+| `search(query, limit)` | 条件必须 | 抛出异常 | 当 `supports_search()` 返回 `True` 时必须实现 |
+| `extract(urls, **kwargs)` | 条件必须 | 抛出异常 | 当 `supports_extract()` 返回 `True` 时必须实现 |
+
+提供商可以在单个类中声明多种能力——Firecrawl、Tavily、Exa 和 Parallel 均实现了搜索和提取两种能力。Brave Search 和 DDGS 仅支持搜索；SearXNG 也仅支持搜索，并有文档说明的"与提取提供商配对使用"工作流。
+
+## 响应格式
+
+工具包装器期望固定的响应信封（envelope），以避免在不同后端之间进行转换。
+
+**搜索成功：**
+
+```python
+{
+    "success": True,
+    "data": {
+        "web": [
+            {"title": str, "url": str, "description": str, "position": int},
+            ...
+        ],
+    },
+}
+```
+
+**提取成功：**
+
+```python
+{
+    "success": True,
+    "data": [
+        {
+            "url": str,
+            "title": str,
+            "content": str,
+            "raw_content": str,
+            "metadata": dict,    # optional
+            "error": str,        # optional, only on per-URL failure
+        },
+        ...
+    ],
+}
+```
+
+**任意能力，失败时：**
+
+```python
+{"success": False, "error": "human-readable message"}
+```
+
+`search()` 和 `extract()` 均可定义为 `async def`——调度器通过 `inspect.iscoroutinefunction` 检测协程函数并相应地进行 await。对于小型后端，执行阻塞 I/O（HTTP、SDK 调用）的同步实现也完全可行；调度器会处理线程调度。
+
+## 能力标志
+
+Hermes 根据 `supports_*` 标志将调用路由至正确的提供商。一种常见的多提供商配置：
+
+```yaml
+# ~/.hermes/config.yaml
+web:
+  search_backend: "brave-free"     # 纯搜索，速度快，每月免费 2k 次
+  extract_backend: "firecrawl"     # 提取 + 爬取，付费配额
+```
+
+当 `web.search_backend` 或 `web.extract_backend` 未设置时，均回退至 `web.backend`。若该项也未设置，Hermes 将根据环境变量的存在情况，选取第一个支持所请求能力的可用提供商。
+
+如果你的提供商只支持一种能力，将其他标志保持默认值（`False`）即可，注册表会在对应工具调用时跳过它——当用户仅将 X 用于搜索而要求 agent 进行提取时，不会看到误导性的"提供商 X 失败"错误。
+
+## Hermes 如何将其接入工具
+
+`web_search` 和 `web_extract` 工具位于 `tools/web_tools.py`。调用时执行以下步骤：
+
+1. 读取相关配置键（`web_search` 对应 `web.search_backend`，`web_extract` 对应 `web.extract_backend`）
+2. 向注册表查询具有该 `name` 的提供商
+3. 检查 `is_available()` 及对应的 `supports_*()` 标志
+4. 调度至 `search()` / `extract()` / `crawl()`，若方法为协程则进行 await
+5. 将响应信封 JSON 序列化后返回给 LLM
+
+错误以工具结果的形式呈现；LLM 决定如何解释。若没有提供商被注册（或所有可用提供商均未通过能力检查），工具将返回一条指向 `hermes tools` 的友好错误信息。
+
+## 懒加载可选依赖
+
+如果你的提供商封装了第三方 SDK（如 DDGS 封装了 `ddgs` 包），请勿在模块顶层 `import`。在 `is_available()` 或 `search()` 内部使用 `tools.lazy_deps.ensure(...)` ——Hermes 将在首次使用时安装该包，并受 `security.allow_lazy_installs` 控制。安全模型详见[构建 Hermes 插件 → 懒加载](/developer-guide/plugins#lazy-install-optional-python-dependencies)。
+
+## 参考实现
+
+- **`plugins/web/brave_free/`** — 小型、需要 API key 的纯搜索 HTTP 提供商。适合作为起始模板。
+- **`plugins/web/ddgs/`** — 无需 key、懒加载 SDK 的提供商。适用于封装 Python 包的后端。
+- **`plugins/web/firecrawl/`** — 完整的多能力提供商（搜索 + 提取 + 爬取），支持多种格式模式。
+- **`plugins/web/searxng/`** — 自托管、通过 URL 配置、无需认证的后端。
+- **`plugins/web/xai/`** — 通过 Grok 服务端 `web_search` 工具实现的 LLM 驱动搜索。展示了如何复用现有的 OAuth/环境变量凭据（`tools/xai_http.py`）而无需新增环境变量，以及如何编写遵守无网络调用约定的轻量 `is_available()`。
+
+## 通过 pip 分发
+
+```toml
+# pyproject.toml
+[project.entry-points."hermes_agent.plugins"]
+my-backend-web = "my_backend_web_package"
+```
+
+`my_backend_web_package` 必须暴露顶层 `register` 函数。完整配置说明参见通用插件指南中的[通过 pip 分发](/developer-guide/plugins#distribute-via-pip)。
+
+## 相关页面
+
+- [网页搜索](/user-guide/features/web-search) — 面向用户的功能文档及各后端配置说明
+- [插件概览](/user-guide/features/plugins) — 所有插件类型一览
+- [构建 Hermes 插件](/developer-guide/plugins) — 通用工具/hook/斜杠命令指南

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/getting-started/installation.md

@@ -0,0 +1,204 @@
+---
+sidebar_position: 2
+title: "安装"
+description: "在 Linux、macOS、WSL2、原生 Windows 或通过 Termux 在 Android 上安装 Hermes Agent"
+---
+
+# 安装
+
+使用一行安装命令，两分钟内即可启动并运行 Hermes Agent。
+
+## 快速安装
+
+### 一行安装命令（Linux / macOS / WSL2）
+
+基于 git 的安装方式，跟踪 `main` 分支，可立即获取最新变更：
+
+```bash
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+```
+
+### Windows（原生，PowerShell）
+
+原生 Windows 无需 WSL 即可运行 Hermes——CLI、gateway、TUI 和工具均可原生运行。（原生安装与 WSL2 安装可干净共存；唯一仅限 WSL2 的功能见下方功能说明。）遇到 bug 请[提交 issue](https://github.com/NousResearch/hermes-agent/issues)。
+
+打开 PowerShell 并运行：
+
+```powershell
+iex (irm https://hermes-agent.nousresearch.com/install.ps1)
+```
+
+安装程序处理**一切**：`uv`、Python 3.11、Node.js 22、`ripgrep`、`ffmpeg`，**以及一个便携式 Git Bash**（PortableGit——一个自包含的 Git-for-Windows 发行版，附带 `bash.exe` 和 Hermes 用于 shell 命令的完整 POSIX 工具链；在 32 位 Windows 上安装程序会回退到 MinGit，后者缺少 bash，终端工具和 agent 浏览器功能将被禁用）。它将仓库克隆到 `%LOCALAPPDATA%\hermes\hermes-agent`，创建虚拟环境，并将 `hermes` 添加到**用户 PATH**。安装完成后请重启终端（或打开新的 PowerShell 窗口）以使 PATH 生效。
+
+**Git 的处理方式：**
+
+1. 如果 `git` 已在你的 PATH 中，安装程序将使用现有安装。
+2. 否则，它会下载便携式 **PortableGit**（约 50MB，来自官方 `git-for-windows` GitHub 发布页）并解压到 `%LOCALAPPDATA%\hermes\git`。无需管理员权限，完全隔离——不会干扰任何系统 Git 安装，无论其状态如何。（在 32 位 Windows 上会回退到 MinGit，因为 PortableGit 仅提供 64 位和 ARM64 资产；依赖 bash 的 Hermes 功能在 32 位主机上无法使用。）
+
+**为什么不使用 winget？** 早期设计通过 `winget install Git.Git` 自动安装 Git，但当系统 Git 安装处于部分损坏状态时，winget 会严重失败（而这恰恰是用户最需要安装程序正常工作的时候）。便携式 Git 方案绕过了 winget、Windows 安装程序注册表以及任何现有系统 Git。如果 Hermes 的 Git 安装本身出现问题，执行 `Remove-Item %LOCALAPPDATA%\hermes\git` 并重新运行安装程序即可——对系统无影响，无需卸载操作。
+
+安装程序还会将 `HERMES_GIT_BASH_PATH` 设置为找到的 `bash.exe` 路径，以便 Hermes 在新 shell 中确定性地解析它。
+
+如果你偏好 WSL2，上方的 Linux 安装程序可在其中运行；原生安装和 WSL 安装可以共存而不冲突（原生数据位于 `%LOCALAPPDATA%\hermes`，WSL 数据位于 `~/.hermes`）。
+
+**桌面安装程序（替代方案）：** 也提供一个轻量 GUI 安装程序——下载 Hermes Desktop，运行 `.exe`，首次启动时它会在后台调用 `install.ps1` 来配置 Python（通过 `uv`）、Node、PortableGit 及其余依赖。桌面应用和 PowerShell 安装的 CLI 共享相同的安装目录和数据目录，可以单独或同时使用。详见 [Windows（原生）指南](../user-guide/windows-native#desktop-installer-alternative)。
+
+### Android / Termux
+
+Hermes 现在也提供 Termux 感知的安装路径：
+
+```bash
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+```
+
+安装程序会自动检测 Termux 并切换到经过测试的 Android 流程：
+
+- 使用 Termux `pkg` 安装系统依赖（`git`、`python`、`nodejs`、`ripgrep`、`ffmpeg`、构建工具）
+- 使用 `python -m venv` 创建虚拟环境
+- 自动导出 `ANDROID_API_LEVEL` 以用于 Android wheel 构建
+- 优先使用较宽泛的 `.[termux-all]` extra，若首次编译失败则回退到较小的 `.[termux]` extra（最终回退到基础安装）
+- 默认跳过未经测试的浏览器 / WhatsApp 引导
+
+如需完整的显式步骤，请参阅专门的 [Termux 指南](./termux.md)。
+
+:::note Windows 功能对等性
+
+除基于浏览器的 dashboard 聊天终端外，其余功能均可在 Windows 上原生运行：
+
+- **CLI（`hermes chat`、`hermes setup`、`hermes gateway` 等）** — 原生，使用默认终端
+- **Gateway（Telegram、Discord、Slack 等）** — 原生，作为后台 PowerShell 进程运行
+- **Cron 调度器** — 原生
+- **浏览器工具** — 原生（通过 Node.js 使用 Chromium）
+- **MCP 服务器** — 原生（stdio 和 HTTP 传输均支持）
+- **Dashboard `/chat` 终端面板** — **仅限 WSL2**（使用 POSIX PTY（伪终端），原生 Windows 无等效实现）。Dashboard 的其余部分（会话、任务、指标）可原生运行——仅嵌入式 PTY 终端标签页受限。
+
+如果遇到编码相关的 bug 并希望回退到旧版 cp1252 stdio 路径（用于问题定位），请在环境中设置 `HERMES_DISABLE_WINDOWS_UTF8=1`。
+:::
+
+### 安装程序做了什么
+
+安装程序自动处理一切——所有依赖（Python、Node.js、ripgrep、ffmpeg）、仓库克隆、虚拟环境、全局 `hermes` 命令配置以及 LLM 提供商配置。完成后即可开始聊天。
+
+#### 安装目录结构
+
+安装程序的存放位置取决于你是以普通用户还是 root 身份安装：
+
+| 安装方式                                | 代码位置                       | `hermes` 二进制                          | 数据目录                              |
+| --------------------------------------- | ------------------------------ | ---------------------------------------- | ------------------------------------- |
+| 用户级（git 安装程序）                  | `~/.hermes/hermes-agent/`      | `~/.local/bin/hermes`（符号链接）        | `~/.hermes/`                          |
+| Root 模式（`sudo curl … \| sudo bash`） | `/usr/local/lib/hermes-agent/` | `/usr/local/bin/hermes`                  | `/root/.hermes/`（或 `$HERMES_HOME`） |
+
+Root 模式的 **FHS 布局**（`/usr/local/lib/…`、`/usr/local/bin/hermes`）与其他系统级开发工具在 Linux 上的安装位置一致。适用于共享机器部署场景，一次系统安装可服务所有用户。每个用户的个人配置（认证、技能、会话）仍位于各自的 `~/.hermes/` 或显式指定的 `HERMES_HOME` 下。
+
+### 安装后
+
+重新加载 shell 并开始聊天：
+
+```bash
+source ~/.bashrc   # 或：source ~/.zshrc
+hermes             # 开始聊天！
+```
+
+如需稍后重新配置单项设置，使用以下专用命令：
+
+```bash
+hermes model          # 选择 LLM 提供商和模型
+hermes tools          # 配置启用的工具
+hermes gateway setup  # 配置消息平台
+hermes config set     # 设置单个配置项
+hermes setup          # 或运行完整的设置向导一次性配置所有内容
+```
+
+:::tip 最快路径：Nous Portal
+一个订阅涵盖 300+ 个模型以及 [Tool Gateway](/user-guide/features/tool-gateway)（网络搜索、图像生成、TTS、云端浏览器）。无需逐一管理各工具的密钥：
+
+```bash
+hermes setup --portal
+```
+
+该命令一次性完成登录、设置 Nous 为提供商并开启 Tool Gateway。
+:::
+
+---
+
+## 前置条件
+
+**Git 安装程序：** 唯一的前置条件是 **Git**。安装程序自动处理其余一切：
+
+- **uv**（快速 Python 包管理器）
+- **Python 3.11**（通过 uv，无需 sudo）
+- **Node.js v22**（用于浏览器自动化和 WhatsApp 桥接）
+- **ripgrep**（快速文件搜索）
+- **ffmpeg**（TTS 的音频格式转换）
+
+:::info
+你**无需**手动安装 Python、Node.js、ripgrep 或 ffmpeg。安装程序会检测缺失的依赖并自动安装。只需确保 `git` 可用（`git --version`）。
+:::
+
+:::tip Nix 用户
+如果你使用 Nix（在 NixOS、macOS 或 Linux 上），有专门的配置路径，包含 Nix flake、声明式 NixOS 模块和可选容器模式。请参阅 **[Nix & NixOS 配置](./nix-setup.md)** 指南。
+:::
+
+---
+
+## 手动 / 开发者安装
+
+如果你想克隆仓库并从源码安装——用于贡献代码、从特定分支运行或完全控制虚拟环境——请参阅贡献指南中的[开发环境配置](../developer-guide/contributing.md#development-setup)章节。
+
+---
+
+## 非 Sudo / 系统服务用户安装
+
+支持以专用非特权用户身份运行 Hermes（例如 `hermes` systemd 服务账户，或任何没有 `sudo` 权限的用户）。安装路径中真正需要 root 权限的只有 Playwright 的 `--with-deps` 步骤，该步骤通过 `apt` 安装 Chromium 所需的共享库（`libnss3`、`libxkbcommon` 等）。安装程序会检测 sudo 是否可用，并在不可用时优雅降级——它会将 Chromium 二进制安装到服务用户自己的 Playwright 缓存中，并打印管理员需要单独运行的确切命令。
+
+**推荐的分步方式（Debian/Ubuntu）：**
+
+1. **一次性操作，以具有 sudo 权限的管理员用户身份**，安装 Chromium 所需的系统库：
+
+   ```bash
+   sudo npx playwright install-deps chromium
+   ```
+
+   （可在任意位置运行——`npx` 会自动获取 Playwright。）
+
+2. **以非特权服务用户身份**，运行常规安装程序。它会检测到缺少 sudo，跳过 `--with-deps`，并将 Chromium 安装到用户本地的 Playwright 缓存中：
+
+   ```bash
+   curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+   ```
+
+   如果想完全跳过 Playwright 步骤——例如在无头环境中运行且不需要浏览器自动化——传入 `--skip-browser`：
+
+   ```bash
+   curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser
+   ```
+
+3. **使 `hermes` 对服务用户的 shell 可用。** 安装程序将启动器写入 `~/.local/bin/hermes`。系统服务账户通常具有不包含 `~/.local/bin` 的最小 PATH。可以将其添加到用户环境，或将启动器符号链接到系统位置：
+
+   ```bash
+   # 方案 A — 添加到服务用户的 profile
+   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+
+   # 方案 B — 系统级符号链接（以管理员身份运行）
+   sudo ln -s /home/hermes/.hermes/hermes-agent/venv/bin/hermes /usr/local/bin/hermes
+   ```
+
+4. **验证：** `hermes doctor` 现在应能正常运行。如果出现 `ModuleNotFoundError: No module named 'dotenv'`，说明你在用系统 Python 调用仓库源码中的 `hermes` 文件（`~/.hermes/hermes-agent/hermes`），而非 venv 启动器（`~/.hermes/hermes-agent/venv/bin/hermes`）——请修正步骤 3。
+
+同样的方式适用于 Arch（安装程序使用 pacman，具有相同的 sudo 检测逻辑）、Fedora/RHEL 和 openSUSE——这些发行版完全不支持 `--with-deps`，因此管理员始终需要单独安装系统库。安装程序会打印相应的 `dnf`/`zypper` 命令。
+
+---
+
+## 故障排查
+
+| 问题                        | 解决方案                                                                           |
+| --------------------------- | ---------------------------------------------------------------------------------- |
+| `hermes: command not found` | 重新加载 shell（`source ~/.bashrc`）或检查 PATH                                    |
+| `API key not set`           | 运行 `hermes model` 配置提供商，或 `hermes config set OPENROUTER_API_KEY your_key` |
+| 更新后配置丢失              | 运行 `hermes config check`，然后运行 `hermes config migrate`                       |
+
+如需更多诊断信息，运行 `hermes doctor`——它会告诉你确切缺少什么以及如何修复。
+
+## 安装方式自动检测
+
+Hermes 会自动检测安装方式（git 安装程序、Docker 或 NixOS），`hermes update` 会打印对应路径的更新命令。无需设置任何环境变量——检测基于安装目录结构（`~/.hermes/hermes-agent/` 检出、Docker 镜像标记或 Nix store 路径）。`hermes doctor` 也会在其环境摘要中显示检测到的安装方式。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/getting-started/learning-path.md

@@ -0,0 +1,154 @@
+---
+sidebar_position: 3
+title: '学习路径'
+description: '根据您的经验水平和目标，选择适合您的 Hermes Agent 文档学习路径。'
+---
+
+# 学习路径
+
+Hermes Agent 功能丰富——CLI 助手、Telegram/Discord 机器人、任务自动化、强化学习训练等。本页帮助您根据自身经验水平和目标，确定从哪里开始、阅读哪些内容。
+
+:::tip 从这里开始
+如果您尚未安装 Hermes Agent，请先阅读[安装指南](/getting-started/installation)，然后完成[快速入门](/getting-started/quickstart)。以下内容均假设您已完成安装。
+:::
+
+## 如何使用本页
+
+- **已知自己的水平？** 跳转至[按经验水平](#by-experience-level)表格，按照对应层级的阅读顺序进行。
+- **有明确目标？** 跳至[按使用场景](#by-use-case)，找到匹配的场景。
+- **随便浏览？** 查看[主要功能](#key-features-at-a-glance)表格，快速了解 Hermes Agent 的全部能力。
+
+## 按经验水平
+
+| 水平 | 目标 | 推荐阅读 | 预计时间 |
+|---|---|---|---|
+| **初级** | 快速上手，进行基本对话，使用内置工具 | [安装](/getting-started/installation) → [快速入门](/getting-started/quickstart) → [CLI 用法](/user-guide/cli) → [配置](/user-guide/configuration) | 约 1 小时 |
+| **中级** | 搭建消息机器人，使用记忆、cron 任务、技能等高级功能 | [会话](/user-guide/sessions) → [消息](/user-guide/messaging) → [工具](/user-guide/features/tools) → [技能](/user-guide/features/skills) → [记忆](/user-guide/features/memory) → [Cron](/user-guide/features/cron) | 约 2–3 小时 |
+| **高级** | 构建自定义工具、创建技能、使用强化学习训练模型、参与项目贡献 | [架构](/developer-guide/architecture) → [添加工具](/developer-guide/adding-tools) → [创建技能](/developer-guide/creating-skills) → [强化学习训练](/user-guide/features/rl-training) → [贡献指南](/developer-guide/contributing) | 约 4–6 小时 |
+
+## 按使用场景
+
+选择与您目标匹配的场景，每个场景均按推荐顺序链接到相关文档。
+
+### "我想要一个 CLI 编程助手"
+
+将 Hermes Agent 用作交互式终端助手，用于编写、审查和运行代码。
+
+1. [安装](/getting-started/installation)
+2. [快速入门](/getting-started/quickstart)
+3. [CLI 用法](/user-guide/cli)
+4. [代码执行](/user-guide/features/code-execution)
+5. [上下文文件](/user-guide/features/context-files)
+6. [技巧与窍门](/guides/tips)
+
+:::tip
+通过上下文文件将文件直接传入对话。Hermes Agent 可以读取、编辑并运行您项目中的代码。
+:::
+
+### "我想要一个 Telegram/Discord 机器人"
+
+将 Hermes Agent 部署为您常用消息平台上的机器人。
+
+1. [安装](/getting-started/installation)
+2. [配置](/user-guide/configuration)
+3. [消息概览](/user-guide/messaging)
+4. [Telegram 配置](/user-guide/messaging/telegram)
+5. [Discord 配置](/user-guide/messaging/discord)
+6. [语音模式](/user-guide/features/voice-mode)
+7. [在 Hermes 中使用语音模式](/guides/use-voice-mode-with-hermes)
+8. [安全](/user-guide/security)
+
+完整项目示例请参阅：
+- [每日简报机器人](/guides/daily-briefing-bot)
+- [团队 Telegram 助手](/guides/team-telegram-assistant)
+
+### "我想自动化任务"
+
+调度周期性任务、运行批处理作业，或将多个 agent 动作串联起来。
+
+1. [快速入门](/getting-started/quickstart)
+2. [Cron 调度](/user-guide/features/cron)
+3. [批处理](/user-guide/features/batch-processing)
+4. [委派](/user-guide/features/delegation)
+5. [Hooks](/user-guide/features/hooks)
+
+:::tip
+Cron 任务让 Hermes Agent 按计划执行任务——每日摘要、定期检查、自动报告——无需您在场。
+:::
+
+### "我想构建自定义工具/技能"
+
+通过自定义工具和可复用技能包扩展 Hermes Agent。
+
+1. [插件](/user-guide/features/plugins)
+2. [构建 Hermes 插件](/developer-guide/plugins)
+3. [工具概览](/user-guide/features/tools)
+4. [技能概览](/user-guide/features/skills)
+5. [MCP（模型上下文协议）](/user-guide/features/mcp)
+6. [架构](/developer-guide/architecture)
+7. [添加工具](/developer-guide/adding-tools)
+8. [创建技能](/developer-guide/creating-skills)
+
+:::tip
+对于大多数自定义工具的创建，建议从插件开始。[添加工具](/developer-guide/adding-tools)页面面向 Hermes 核心内置开发，而非常规用户/自定义工具路径。
+:::
+
+### "我想训练模型"
+
+使用强化学习（RL）通过 Hermes Agent 内置的 RL 训练流水线对模型行为进行微调。
+
+1. [快速入门](/getting-started/quickstart)
+2. [配置](/user-guide/configuration)
+3. [强化学习训练](/user-guide/features/rl-training)
+4. [Provider 路由](/user-guide/features/provider-routing)
+5. [架构](/developer-guide/architecture)
+
+:::tip
+强化学习训练在您已了解 Hermes Agent 如何处理对话和工具调用的基础上效果最佳。如果您是新手，请先完成初级路径。
+:::
+
+### "我想将其作为 Python 库使用"
+
+以编程方式将 Hermes Agent 集成到您自己的 Python 应用中。
+
+1. [安装](/getting-started/installation)
+2. [快速入门](/getting-started/quickstart)
+3. [Python 库指南](/guides/python-library)
+4. [架构](/developer-guide/architecture)
+5. [工具](/user-guide/features/tools)
+6. [会话](/user-guide/sessions)
+
+## 主要功能一览
+
+不确定有哪些功能？以下是主要功能的快速目录：
+
+| 功能 | 说明 | 链接 |
+|---|---|---|
+| **工具** | Agent 可调用的内置工具（文件 I/O、搜索、Shell 等） | [工具](/user-guide/features/tools) |
+| **技能** | 可安装的插件包，用于添加新能力 | [技能](/user-guide/features/skills) |
+| **记忆** | 跨会话的持久化记忆 | [记忆](/user-guide/features/memory) |
+| **上下文文件** | 将文件和目录传入对话 | [上下文文件](/user-guide/features/context-files) |
+| **MCP** | 通过模型上下文协议连接外部工具服务器 | [MCP](/user-guide/features/mcp) |
+| **Cron** | 调度周期性 agent 任务 | [Cron](/user-guide/features/cron) |
+| **委派** | 生成子 agent 以并行处理工作 | [委派](/user-guide/features/delegation) |
+| **代码执行** | 运行以编程方式调用 Hermes 工具的 Python 脚本 | [代码执行](/user-guide/features/code-execution) |
+| **浏览器** | 网页浏览与抓取 | [浏览器](/user-guide/features/browser) |
+| **Hooks** | 事件驱动的回调与中间件 | [Hooks](/user-guide/features/hooks) |
+| **批处理** | 批量处理多个输入 | [批处理](/user-guide/features/batch-processing) |
+| **强化学习训练** | 使用强化学习微调模型 | [强化学习训练](/user-guide/features/rl-training) |
+| **Provider 路由** | 在多个 LLM provider 之间路由请求 | [Provider 路由](/user-guide/features/provider-routing) |
+
+## 下一步阅读
+
+根据您当前所处阶段：
+
+- **刚完成安装？** → 前往[快速入门](/getting-started/quickstart)，运行您的第一次对话。
+- **完成了快速入门？** → 阅读 [CLI 用法](/user-guide/cli)和[配置](/user-guide/configuration)，自定义您的设置。
+- **已熟悉基础？** → 探索[工具](/user-guide/features/tools)、[技能](/user-guide/features/skills)和[记忆](/user-guide/features/memory)，释放 agent 的全部能力。
+- **为团队部署？** → 阅读[安全](/user-guide/security)和[会话](/user-guide/sessions)，了解访问控制与对话管理。
+- **准备好开发了？** → 进入[开发者指南](/developer-guide/architecture)，了解内部机制并开始贡献。
+- **想要实际示例？** → 查看[指南](/guides/tips)部分，获取真实项目案例和技巧。
+
+:::tip
+您无需阅读所有内容。选择与您目标匹配的路径，按顺序跟随链接，即可快速上手。随时可以回到本页寻找下一步。
+:::