技能介绍

它解决什么问题

在中国大陆网络下，Hermes Agent 的官方安装脚本默认从 GitHub 拉代码、从 Electron 官方渠道下载二进制，直连基本都会超时。macOS（Apple Silicon）上即便侥幸装完，后续 hermes desktop 构建桌面客户端时还会连环踩坑：Electron 二进制静默缺失（npm 包装上不等于下载成功）、npm 重装把 cross-env 权限重置为 644、tsc 找不到、WorkBuddy 沙箱拦截清空 dist。更隐蔽的是，客户端重装可能清空 venv，导致 hermes 命令报 No module named 'yaml'；或者 bootstrap marker 缺失，客户端每次启动都提示重新安装。这个技能把上述症状整理成一张「先看症状再动手」的诊断表，每条症状对应明确的原因章节。

核心能力与关键步骤

镜像化更新：代码仓库 origin 固定到 cnb.cool 国内镜像，hermes update 走 GitHub 失败时从镜像拉取；镜像变量固化在 ~/.hermes/.env 与 ~/.zshrc，所有命令前先 source 即可。
桌面客户端构建：先确认 node_modules/electron/dist 真正存在，构建前修复 bin 权限、用 Python 绕过沙箱清空 dist，且必须在沙箱外执行 --build-only。
venv 与 bootstrap 修复：重建被清空的虚拟环境，按当前 git HEAD 写入 .hermes-bootstrap-complete marker，并用模拟桌面判定逻辑做校验。
验证清单：从 hermes --version、DeepSeek 状态、marker 格式到桌面产物路径逐项检查，全绿才算正常。

适用边界与注意点

本手册针对 macOS arm64 + 中国大陆网络这一组合，Intel Mac 或其他网络环境需自行调整。可选依赖如 faster-whisper 走 lazy-install 机制，装失败不影响核心功能；不要使用 --all-extras 全量安装 Python 依赖（钉钉 SDK 在 arm64 上构建必失败）；构建产物生成后，用户在自己终端跑 hermes desktop 可直接复用，不必重复构建。