better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/windows-wsl-quickstart.md

@@ -0,0 +1,332 @@
+---
+title: "Windows (WSL2) 指南"
+description: "通过 WSL2 在 Windows 上运行 Hermes Agent —— 安装配置、Windows 与 Linux 之间的文件系统访问、网络设置及常见问题"
+sidebar_label: "Windows (WSL2)"
+sidebar_position: 2
+---
+
+# Windows (WSL2) 指南
+
+Hermes Agent 现已同时支持原生 Windows 和 WSL2。本页介绍 WSL2 路径；如需原生 PowerShell 安装方式，请参阅专属的 **[Windows（原生）指南](./windows-native.md)**。
+
+**何时选择 WSL2 而非原生：**
+- 你想使用 dashboard 内嵌终端（`/chat` 标签页）—— 该面板需要 POSIX PTY（伪终端），仅 WSL2 支持。
+- 你在进行大量 POSIX 相关的开发工作，希望 Hermes 会话与开发工具共享同一文件系统和路径。
+- 你已有 WSL2 环境，不想维护第二套安装。
+
+**何时原生更合适（甚至更好）：**
+- 交互式聊天、gateway（Telegram/Discord 等）、cron 调度器、浏览器工具、MCP 服务器以及大多数 Hermes 功能均可在 Windows 上原生运行。
+- 你不想在每次引用文件或打开 URL 时都考虑跨越 WSL↔Windows 边界的问题。
+
+在 WSL2 中，实际上有两台"计算机"同时运行：你的 Windows 宿主机，以及由 WSL 管理的 Linux 虚拟机。大多数困惑都源于不清楚自己当前处于哪一侧。
+
+本指南涵盖这种分离中专门影响 Hermes 的部分：安装 WSL2、在 Windows 与 Linux 之间传输文件、双向网络配置，以及实际遇到的常见问题。
+
+:::info 简体中文
+最小安装路径的中文说明维护在本页 —— 通过右上角的**语言**菜单切换，选择**简体中文**即可查看。
+:::
+
+## 为什么选择 WSL2（而非原生 Windows）
+
+原生 Windows 安装直接运行在 Windows 上：使用 Windows 终端（PowerShell、Windows Terminal 等）、Windows 文件系统路径（`C:\Users\…`）和 Windows 进程。Hermes 使用 Git Bash 执行 shell 命令，这也是 Claude Code 等 agent 目前处理 Windows 的方式 —— 无需完整重写即可绕过 POSIX 与 Windows 的差异。
+
+WSL2 在轻量级虚拟机中运行真实的 Linux 内核，因此其中的 Hermes 与在 Ubuntu 上运行几乎完全相同。当你需要真正的 POSIX 环境时，这非常有价值：`fork`、`/tmp`、UNIX socket、信号语义、PTY 支持的终端、`bash`/`zsh` 等 shell，以及 `rg`、`git`、`ffmpeg` 等在 Linux 上行为一致的工具。
+
+WSL2 的实际影响：
+
+- Hermes CLI、gateway、会话、内存、技能和工具运行时均位于 Linux 虚拟机内部。
+- Windows 程序（浏览器、原生应用、带登录 profile 的 Chrome）位于虚拟机外部。
+- 每次需要两者通信时 —— 共享文件、打开 URL、控制 Chrome、访问本地模型服务器、将 Hermes gateway 暴露给手机 —— 都需要跨越一道边界。这些边界正是本指南要讲的内容。
+
+## 安装 WSL2
+
+在**管理员 PowerShell** 或 Windows Terminal 中执行：
+
+```powershell
+wsl --install
+```
+
+在全新的 Windows 10 22H2+ 或 Windows 11 上，此命令会安装 WSL2 内核、虚拟机平台功能以及默认的 Ubuntu 发行版。按提示重启。重启后 Ubuntu 会打开并要求设置 Linux 用户名和密码 —— 这是一个**全新的 Linux 用户**，与你的 Windows 账户无关。
+
+验证你确实在使用 WSL2（而非旧版 WSL1）：
+
+```powershell
+wsl --list --verbose
+```
+
+应显示 `VERSION  2`。如果某个发行版显示 `VERSION  1`，请转换：
+
+```powershell
+wsl --set-version Ubuntu 2
+wsl --set-default-version 2
+```
+
+Hermes 在 WSL1 上无法可靠运行 —— WSL1 会动态转译 Linux 系统调用，某些行为（procfs、信号、网络）与真实 Linux 存在偏差。
+
+### 发行版选择
+
+我们以 Ubuntu（LTS）为测试基准。Debian 同样可用。Arch 和 NixOS 也有人在用，但一键安装脚本假设使用基于 Debian 的 `apt` 系统 —— 如需其他路径，请参阅 [Nix 安装指南](/getting-started/nix-setup)。
+
+### 启用 systemd（推荐）
+
+Hermes gateway（以及任何你希望持续运行的服务）在 systemd 下更易管理。在现代 WSL 上，在发行版内执行一次即可启用：
+
+```bash
+sudo tee /etc/wsl.conf >/dev/null <<'EOF'
+[boot]
+systemd=true
+
+[interop]
+enabled=true
+appendWindowsPath=true
+
+[automount]
+options = "metadata,umask=22,fmask=11"
+EOF
+```
+
+然后在 PowerShell 中执行：
+
+```powershell
+wsl --shutdown
+```
+
+重新打开 WSL 终端。`ps -p 1 -o comm=` 应输出 `systemd`。
+
+上面的 `metadata` 挂载选项很重要 —— 没有它，`/mnt/c/...` 上的文件无法存储真实的 Linux 权限位，这会导致在 Windows 路径下对脚本执行 `chmod +x` 等操作失效。
+
+### 在 WSL 内安装 Hermes
+
+打开 WSL2 shell 后执行：
+
+```bash
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+source ~/.bashrc
+hermes
+```
+
+安装程序将 WSL2 视为普通 Linux —— 无需任何 WSL 专属配置。完整目录结构请参阅[安装说明](/getting-started/installation)。
+
+## 文件系统：跨越 Windows ↔ WSL2 边界
+
+这是最容易让人踩坑的部分。存在**两套文件系统**，文件放在哪里至关重要 —— 影响性能、正确性以及哪些工具能访问到它。
+
+### 两个方向
+
+| 方向 | 内部路径 | 使用的路径 |
+|---|---|---|
+| Windows 磁盘，从 WSL 访问 | `C:\Users\you\Documents` | `/mnt/c/Users/you/Documents` |
+| WSL 磁盘，从 Windows 访问 | `/home/you/code` | `\\wsl$\Ubuntu\home\you\code`（较新版本为 `\\wsl.localhost\Ubuntu\...`） |
+
+两者都是真实存在的，都可以使用，但它们**不是同一个文件系统** —— 底层通过 9P 网络协议桥接。这带来了真实的性能和语义差异。
+
+### Hermes 和项目应放在哪里
+
+**经验法则：将所有 Linux 相关内容保留在 Linux 文件系统内。**
+
+- 你的 Hermes 安装目录（`~/.hermes/`）—— Linux 侧。安装程序已自动处理。
+- 你在 WSL 中开发的 git 仓库 —— Linux 侧（`~/code/...`、`~/projects/...`）。
+- 你的模型、数据集、venv —— Linux 侧。
+
+遵循此规则的好处：
+
+- **I/O 速度快。** 对 `/mnt/c/...` 的操作需经过 9P，比原生 ext4 慢 10–100 倍。在 `~/code` 下感觉瞬间完成的 `git status`（10k 文件仓库），在 `/mnt/c` 下可能需要 15 秒以上。
+- **权限正确。** Linux 权限位在 `/mnt/c` 上只是尽力模拟。`ssh` 因"权限不当"拒绝密钥，或 `chmod +x` 静默失败，都是常见问题。
+- **文件监听可靠。** 跨 9P 的 inotify 不稳定 —— 文件监听器（开发服务器、测试运行器）在 `/mnt/c` 上经常漏报变更。
+- **无大小写敏感问题。** Windows 路径默认不区分大小写；Linux 区分大小写。同时包含 `Readme.md` 和 `README.md` 的项目在两侧行为不同。
+
+只有当你**确实需要**文件存在于 Windows 侧时，才将其放在 `/mnt/c` 下 —— 例如需要从 Windows GUI 应用打开，或 Windows Chrome 的 DevTools MCP 需要当前目录是 Windows 可访问的路径。
+
+### 在两侧之间传输文件
+
+**从 Windows → 传入 WSL：** 最简单的方式是打开资源管理器，在地址栏输入 `\\wsl.localhost\Ubuntu`，然后拖放到 `\home\<you>\...`。或者在 PowerShell 中：
+
+```powershell
+wsl cp /mnt/c/Users/you/Downloads/file.pdf ~/incoming/
+```
+
+**从 WSL → 传入 Windows：** 复制到 `/mnt/c/Users/<you>/...`，Windows 资源管理器会立即看到：
+
+```bash
+cp ~/reports/output.pdf /mnt/c/Users/you/Desktop/
+```
+
+**在 Windows 应用中打开 WSL 文件**（GUI 编辑器、浏览器等）：使用 `explorer.exe` 或 `wslview`：
+
+```bash
+sudo apt install wslu     # 安装一次 —— 提供 wslview、wslpath、wslopen 等工具
+wslview ~/reports/output.pdf    # 用 Windows 默认程序打开
+explorer.exe .                  # 在 Windows 资源管理器中打开当前 WSL 目录
+```
+
+**在两个世界之间转换路径：**
+
+```bash
+wslpath -w ~/code/project        # → \\wsl.localhost\Ubuntu\home\you\code\project
+wslpath -u 'C:\Users\you'        # → /mnt/c/Users/you
+```
+
+### 行尾符、BOM 与 git
+
+如果你在 Windows 侧用 Windows 编辑器编辑文件，可能会产生 `CRLF` 行尾符。当 Linux 侧的 `bash` 或 Python 读取这些文件时，shell 脚本会报错 `bad interpreter: /bin/bash^M`，带 BOM 的 `.env` 文件也可能导致 Python 失败。
+
+解决方法是在 WSL 内（而非 Windows 上）配置合理的 git 设置：
+
+```bash
+git config --global core.autocrlf input
+git config --global core.eol lf
+```
+
+对于已有 CRLF 的文件：
+
+```bash
+sudo apt install dos2unix
+dos2unix path/to/script.sh
+```
+
+### "在 WSL 内 clone 还是在 `/mnt/c` 上 clone？"
+
+在 WSL 内 clone。始终如此，除非有特殊原因。典型的 Hermes 工作流（`hermes chat`、调用 `rg`/`ripgrep` 搜索仓库的工具、文件监听器、后台 gateway）在 `~/code/myrepo` 下会比在 `/mnt/c/Users/you/myrepo` 下快得多，也更可靠。
+
+一个例外：**启动 Windows 二进制文件的 MCP bridge。** 如果你通过 `cmd.exe` 使用 `chrome-devtools-mcp`（参见 [MCP 指南：WSL → Windows Chrome](/guides/use-mcp-with-hermes#wsl2-bridge-hermes-in-wsl-to-windows-chrome)），当 Hermes 的当前工作目录是 `~` 时，Windows 可能会报 `UNC` 警告。此时请从 `/mnt/c/` 下的某个目录启动 Hermes，以便 Windows 进程拥有一个带盘符的工作目录。
+
+## 网络：WSL ↔ Windows
+
+WSL2 在轻量级虚拟机中运行，拥有独立的网络栈。这意味着 WSL 内的 `localhost` 与 Windows 上的 `localhost` **并不相同** —— 从网络角度看，它们是两台独立的主机。对于每个服务，你需要确定流量方向，并选择正确的桥接方式。
+
+以下两种情况最为常见。
+
+### 情况一 —— WSL 中的 Hermes 访问 Windows 上的服务
+
+最常见的场景：你在 **Windows 上运行 Ollama、LM Studio 或 llama-server**，而 WSL 内的 Hermes 需要访问它。
+
+此场景的权威说明在 providers 指南中：**[WSL2 本地模型网络配置 →](/integrations/providers#wsl2-networking-windows-users)**
+
+简要说明：
+
+- **Windows 11 22H2+：** 启用镜像网络模式（在 `%USERPROFILE%\.wslconfig` 中设置 `networkingMode=mirrored`，然后执行 `wsl --shutdown`）。之后 `localhost` 在两侧均可互通。
+- **Windows 10 或旧版本：** 使用 Windows 宿主机 IP（WSL 虚拟网络的默认网关），并确保 Windows 上的服务绑定到 `0.0.0.0` 而非仅 `127.0.0.1`。通常还需要在 Windows 防火墙中为该端口添加规则。
+
+完整表格（Ollama / LM Studio / vLLM / SGLang 绑定地址、防火墙规则一行命令、动态 IP 辅助工具、Hyper-V 防火墙解决方案）请点击上方链接 —— 此处不再重复。
+
+### 情况二 —— Windows（或局域网）上的设备访问 WSL 中的 Hermes
+
+这是反向情况，其他地方较少记录，但以下场景需要用到：
+
+- 从 Windows 浏览器使用 Hermes **Web Dashboard**。
+- 从 Windows 侧工具使用 **OpenAI 兼容 API 服务器**（当 `API_SERVER_ENABLED=true` 时由 `hermes gateway` 暴露）。参见 [API Server 功能页](/user-guide/features/api-server)。
+- 测试**消息 gateway**（Telegram、Discord 等），平台会向本地 webhook URL 发送请求 —— 通常建议使用 `cloudflared`/`ngrok` 而非原始端口转发。
+
+#### 子情况 2a：从 Windows 宿主机本身访问
+
+在**启用了镜像模式的 Windows 11 22H2+** 上，无需任何额外操作。WSL 中绑定到 `0.0.0.0:8080`（甚至 `127.0.0.1:8080`）的进程，可直接从 Windows 浏览器通过 `http://localhost:8080` 访问。WSL 会自动将绑定发布回宿主机。
+
+在 **NAT 模式**（Windows 10 / 旧版 Windows 11）下，WSL2 默认的"localhost 转发"通常会将 Linux 侧的 `127.0.0.1` 绑定转发到 Windows 的 `localhost`，因此以 `--host 127.0.0.1` 启动的 Hermes 服务通常可从 Windows 通过 `http://localhost:PORT` 访问。如果无法访问：
+
+- 在 WSL 内显式绑定到 `0.0.0.0`。
+- 用 `ip -4 addr show eth0 | grep inet` 获取 WSL 虚拟机的 IP，然后从 Windows 直接访问该 IP。
+
+#### 子情况 2b：从局域网中的其他设备访问（手机、平板、另一台 PC）
+
+这才是真正麻烦的地方。流量路径为 **局域网设备 → Windows 宿主机 → WSL 虚拟机**，你需要分别配置两段：
+
+1. **在 WSL 内绑定所有网络接口。** 监听 `127.0.0.1` 的进程永远无法从虚拟机外部访问。请使用 `0.0.0.0`。
+
+2. **配置 Windows → WSL 虚拟机的端口转发。** 镜像模式下自动完成。NAT 模式下需要在管理员 PowerShell 中手动配置，每个端口单独设置：
+
+   ```powershell
+   # 获取 WSL 虚拟机当前 IP（NAT 模式下每次重启 WSL 都会变化）
+   $wslIp = (wsl hostname -I).Trim().Split(' ')[0]
+
+   # 将 Windows 端口 8080 转发到 WSL:8080
+   netsh interface portproxy add v4tov4 `
+     listenaddress=0.0.0.0 listenport=8080 `
+     connectaddress=$wslIp connectport=8080
+
+   # 在 Windows 防火墙中放行该端口
+   New-NetFirewallRule -DisplayName "Hermes WSL 8080" `
+     -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow
+   ```
+
+   之后可用以下命令删除：`netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8080`。
+
+3. **让局域网设备访问 `http://<windows-lan-ip>:8080`。**
+
+由于 NAT 模式下 WSL 虚拟机 IP 在每次重启后都会变化，一次性配置的规则在下次 `wsl --shutdown` 后即失效。如需持久化，要么启用镜像模式，要么将端口代理步骤写入 Windows 登录时自动运行的脚本。
+
+对于来自云端消息服务商的 webhook（Telegram `setWebhook`、Slack 事件等），不建议折腾端口转发 —— 请使用 `cloudflared` 隧道。参见 [webhook 指南](/user-guide/messaging/webhooks)。
+
+## 在 Windows 上长期运行 Hermes 服务
+
+Hermes 的 [Tool Gateway](/user-guide/features/tool-gateway) 和 API 服务器都是长期运行的进程。在 WSL2 中，有以下几种方式保持它们持续运行。
+
+### 在 WSL 内使用 systemd（推荐）
+
+如果你按照上面的安装步骤启用了 systemd，`hermes gateway` 和 API 服务器的使用方式与任何 Linux 机器上完全相同。使用 gateway 设置向导：
+
+```bash
+hermes gateway setup
+```
+
+它会提示是否安装 systemd 用户单元，以便在 WSL 启动时自动拉起 gateway。
+
+### 让 WSL 在 Windows 登录时自动启动
+
+WSL 虚拟机只在有进程使用时保持运行。若要在没有终端窗口的情况下保持 gateway 可访问，可通过任务计划程序在 Windows 登录时启动一个 WSL 进程：
+
+- **触发器：** 用户登录时（你的账户）。
+- **操作：** 启动程序
+  - 程序：`C:\Windows\System32\wsl.exe`
+  - 参数：`-d Ubuntu --exec /bin/sh -c "sleep infinity"`
+
+这样可以保持虚拟机存活，使 systemd 管理的 gateway 持续运行。在 Windows 11 上，较新的 `wsl --install --no-launch` + 自动启动流程也可以实现；`sleep infinity` 方案是兼容性最好的版本。
+
+## GPU 直通（本地模型）
+
+WSL2 自 WSL 内核 5.10.43+ 起原生支持 **NVIDIA** GPU —— 在 Windows 上安装标准 NVIDIA 驱动（**不要**在 WSL 内安装 Linux NVIDIA 驱动），WSL 内的 `nvidia-smi` 即可识别 GPU。之后，CUDA 工具链、`torch`、`vllm`、`sglang` 和 `llama-server` 均可正常使用真实 GPU。
+
+AMD ROCm 和 Intel Arc 在 WSL2 内的支持仍在发展中，不在 Hermes 的测试范围内 —— 使用当前驱动可能可以工作，但我们暂无推荐方案。
+
+如果你运行的是**原生 Windows** 本地模型服务器（Windows 版 Ollama、LM Studio），它已通过 Windows 驱动使用 GPU，则完全不需要 WSL GPU 直通 —— 只需按照上面的情况一，从 WSL 通过网络访问即可。
+
+## 常见问题
+
+**连接 Windows 上的 Ollama / LM Studio 时报"Connection refused"。**
+参见 [WSL2 网络配置](/integrations/providers#wsl2-networking-windows-users)。九成情况是服务绑定在 `127.0.0.1` 上，需要改为 `0.0.0.0`（Ollama：`OLLAMA_HOST=0.0.0.0`），或者缺少防火墙规则。
+
+**`git status` / `hermes chat` 在仓库中极慢。**
+你很可能在 `/mnt/c/...` 下工作。将仓库移到 `~/code/...`（Linux 侧），速度会有数量级的提升。
+
+**脚本报错 `bad interpreter: /bin/bash^M`。**
+Windows 编辑器产生的 CRLF 行尾符。执行 `dos2unix script.sh`，并在 WSL git 配置中设置 `core.autocrlf input`。
+
+**通过 MCP 启动 Windows 二进制文件时出现"UNC paths are not supported"警告。**
+Hermes 的工作目录在 Linux 文件系统内，Windows `cmd.exe` 无法识别。在该会话中从 `/mnt/c/...` 下启动 Hermes，或使用一个在调用 Windows 可执行文件前先 `cd` 到 Windows 可访问路径的包装脚本。
+
+**休眠/睡眠后时钟漂移。**
+宿主机从睡眠恢复后，WSL2 的时钟可能滞后数分钟，导致所有基于证书的操作失败（OAuth、HTTPS API）。按需修复：
+
+```bash
+sudo hwclock -s
+```
+
+或安装 `ntpdate` 并在登录时运行。
+
+**启用镜像模式后或连接 VPN 时 DNS 停止工作。**
+镜像模式会将宿主机网络设置代理到 WSL —— 如果 Windows DNS 有问题（VPN 分流隧道、企业解析器），WSL 会继承这些问题。解决方法：手动覆盖 `resolv.conf`（在 `/etc/wsl.conf` 中设置 `generateResolvConf=false`，然后手动编写 `/etc/resolv.conf`，填入 `1.1.1.1` 或你的 VPN DNS）。
+
+**运行安装程序后找不到 `hermes` 命令。**
+安装程序通过 `~/.bashrc` 将 `~/.local/bin` 添加到 shell 的 PATH 中。需要执行 `source ~/.bashrc`（或打开新终端）才能在当前会话中生效。
+
+**Windows Defender 对 WSL 文件扫描很慢。**
+Defender 通过 9P 桥接扫描从 Windows 访问的文件，这会放大 `/mnt/c` 风格跨边界访问的延迟。如果你只在 WSL 内部访问 WSL 文件，则不受影响。如果你频繁使用 Windows 工具访问 `\\wsl$\...`，可考虑将 WSL 发行版路径排除在实时扫描之外。
+
+**磁盘空间不足。**
+WSL2 将虚拟机磁盘存储为 `%LOCALAPPDATA%\Packages\...` 下的稀疏 VHDX 文件。它会自动增长，但删除文件后不会自动收缩。回收空间的方法：执行 `wsl --shutdown`，然后在管理员 PowerShell 中运行 `Optimize-VHD -Path <path-to-ext4.vhdx> -Mode Full`（需要 Hyper-V 工具），或使用 WSL 文档中记录的更简单的 `diskpart` 方式。
+
+## 下一步
+
+- **[安装说明](/getting-started/installation)** —— 实际安装步骤（Linux/WSL2/Termux 均使用同一安装程序）。
+- **[集成 → Providers → WSL2 网络配置](/integrations/providers#wsl2-networking-windows-users)** —— 本地模型服务器网络配置的权威深度说明。
+- **[MCP 指南 → WSL → Windows Chrome](/guides/use-mcp-with-hermes#wsl2-bridge-hermes-in-wsl-to-windows-chrome)** —— 从 WSL 中的 Hermes 控制你已登录的 Windows Chrome。
+- **[Tool Gateway](/user-guide/features/tool-gateway)** 和 **[Web Dashboard](/user-guide/features/web-dashboard)** —— 你最常需要从 WSL 暴露到网络其他部分的长期运行服务。

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

@@ -0,0 +1,10 @@
+---
+title: 用户故事与使用案例
+description: 来自 Hermes Agent 社区的真实故事——人们实际在构建的内容，来源涵盖 X、GitHub、Reddit、Hacker News、YouTube、博客和播客。
+hide_title: true
+hide_table_of_contents: true
+---
+
+import UserStoriesCollage from '@site/src/components/UserStoriesCollage';
+
+<UserStoriesCollage />