Skip to content

README-Windows.md

Latest commit

 

History

History
105 lines (80 loc) · 5.01 KB

README-Windows.md

File metadata and controls

105 lines (80 loc) · 5.01 KB
Raw

Hermes Command Code Provider — Windows 安装与使用指南

本项目原版只支持 macOS/Linux（install.sh 和 bin/hermes-commandcode 是 bash 脚本）。这个版本做了完整的 Windows 适配，并由 GitHub Actions 自动打包：

组件 说明
commandcode_proxy.exe 本地桥（PyInstaller 打包，无需安装 Python）。已修复三个 Windows 问题：curl 子进程显式 UTF-8 解码（否则中文系统按 GBK 解码 API 响应会乱码）；curl 配置文件里的临时文件路径转正斜杠（反斜杠会被当转义符）；curl 缺失时报清晰错误
hermes-commandcode.exe 启动器：自动后台拉起桥（无窗口），就绪后调用 hermes，参数全部透传
install.ps1 / install.cmd Windows 安装器（等价于 install.sh），优先安装 exe，没有 exe 时回退到 .py 源码模式
plugins/model-providers/commandcode/ Hermes provider 插件（Hermes 用自己的解释器加载，保持 .py/.yaml 原样）
scripts/*.py 配置与兼容性补丁脚本（--configure 时使用，需要 Python 和 PyYAML）

前提条件

  • Windows 10 1803 及以上（系统自带 curl.exe，桥靠它发请求）
  • 已安装 Hermes Agent（hermes --version 能输出版本）
  • Command Code 账户有可用额度，并完成以下任一认证：
    • 设置环境变量 COMMANDCODE_API_KEY（推荐；"系统属性 → 高级 → 环境变量"里永久设置）
    • 或已有 %USERPROFILE%\.commandcode\auth.json（Command Code CLI 登录生成）
  • 仅在使用 --configure 时需要：Python 3 在 PATH 中、已安装 PyYAML （python -m pip install pyyaml）

安装

从 Release 下载 hermes-commandcode-provider-windows.zip，解压后进入 hermes-commandcode-provider-windows 目录，二选一：

:: 方式一：双击 install.cmd（只装文件，不改配置）
install.cmd

:: 方式二：命令行（推荐，自动配置 Hermes）
install.cmd --configure

等价于：

powershell -NoProfile -ExecutionPolicy Bypass -File install.ps1 --configure

--configure 会额外做三件事：更新 %USERPROFILE%\.hermes\config.yaml（先自动 备份）、给 Hermes 的模型选择器和 doctor 打兼容性小补丁（补丁失败只会警告，不 影响安装；只在匹配到对应 Hermes 版本源码时才生效）。

安装后的文件位置：

%USERPROFILE%\.hermes\commandcode_proxy.exe
%USERPROFILE%\.hermes\plugins\model-providers\commandcode\__init__.py
%USERPROFILE%\.hermes\plugins\model-providers\commandcode\plugin.yaml
%USERPROFILE%\.local\bin\hermes-commandcode.exe

使用

先把 %USERPROFILE%\.local\bin 加进 PATH（设置 → 搜索"环境变量" → 编辑用户 变量 Path），之后：

hermes-commandcode -z "Reply with exactly OK."
hermes-commandcode --provider commandcode -m moonshotai/Kimi-K2.5
hermes-commandcode --provider commandcode -m deepseek/deepseek-v4-flash

启动器会自动在后台拉起本地桥（http://127.0.0.1:8788/v1，无控制台窗口）， 桥已就绪时直接复用，然后把你给的所有参数原样传给 hermes。

如果你不用启动器、直接跑 hermes，需要自己先启动桥（保持窗口开着，或用 start /b 等方式后台运行）：

%USERPROFILE%\.hermes\commandcode_proxy.exe --host 127.0.0.1 --port 8788

桥的管理

  • 日志：%USERPROFILE%\.hermes\commandcode_proxy.log
  • 进程号：%USERPROFILE%\.hermes\commandcode_proxy.pid
  • 停止桥：taskkill /F /PID <pid文件里的数字>
  • 详细请求日志：设置环境变量 COMMANDCODE_PROXY_VERBOSE=1 后重启桥
  • 换端口/地址：环境变量 COMMANDCODE_PROXY_PORT / COMMANDCODE_PROXY_HOST （注意同时改 ~/.hermes/config.yaml 里的 base_url）

卸载

删除上面"安装后的文件位置"里列出的文件即可；config.yaml 的改动可从安装时 生成的 config.yaml.before-commandcode-* 备份恢复，两个补丁在对应文件旁也有 *.before-commandcode-* 备份。

常见问题

  • 杀毒软件误报：PyInstaller 单文件 exe 偶尔被误报，属于常见现象；介意的 话可以加白名单，或用源码模式（删掉 exe 后安装器会回退到 .py）。
  • 报 insufficient credits：桥已正常工作，是 Command Code 账户额度不足， 充值/确认订阅状态后即可。
  • 报 curl executable not found：PATH 里没有 curl.exe。Win10 1803+ 自带于 C:\Windows\System32\curl.exe，检查 PATH 是否包含 System32。
  • hermes 找不到：确认 hermes 在 PATH 中；特殊情况可设置环境变量 HERMES_BIN 指向 hermes.exe 的完整路径。
  • 补丁提示 skipped：你的 Hermes 版本源码里没有对应标记，属于正常现象， 不影响使用。Hermes 源码不在默认位置时，可设置 HERMES_AGENT_DIR 指向 hermes-agent 目录（里面应有 hermes_cli\doctor.py）。补丁脚本会按顺序查找： HERMES_AGENT_DIR → ~/.hermes/hermes-agent → %LOCALAPPDATA%\hermes\hermes-agent。