better-dsh 0.2.5 → 0.3.0-a

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

@@ -1,260 +0,0 @@
----
-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

@@ -1,204 +0,0 @@
----
-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

@@ -1,154 +0,0 @@
----
-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
-您无需阅读所有内容。选择与您目标匹配的路径，按顺序跟随链接，即可快速上手。随时可以回到本页寻找下一步。
-:::