Hermes Agent

备注（2026-06-01）：这个文件最早由 Hermes 用 write_file 直接创建（手写风格），后来用 vault-keeper add project_note 写过若干条目。2026-06-01 vault-keeper 的 add 有一个 bug 把文件覆盖过一次（详见 bug_fix 条目），恢复后由 Hermes 直接重写本文件。

UI-TARS Computer Use 集成调研 — 2026-06-01

目标

补齐 Hermes Agent 在 Windows 上的 computer use 能力（cua-driver 是 macOS 专属，Windows 平台缺 computer use）。

调研结果（via Reasonix deepseek-v4-flash）

UI-TARS 主仓库（bytedance/UI-TARS, Apache 2.0, 10.8k stars）：模型 + Python SDK（pip install ui-tars）
UI-TARS-desktop（bytedance/UI-TARS-desktop）：Electron 桌面应用，无 HTTP/IPC/CLI 接口，只能人在 GUI 里打字用，不可被 Hermes 编程调用
@ui-tars/sdk（npm）：可编程的 Node.js SDK，GUIAgent + NutJSOperator 截图→推理→执行
@ui-tars/cli / Agent TARS CLI：交互式 stdin/stdout，无 one-shot 模式，不适合子进程集成

IDA PC GPU 情况

GeForce GT 640 / 2GB VRAM / Fermi 2012 架构 — 完全无法本地跑 7B（FP16 要 14GB，4-bit 量化 4-5GB）
CUDA 11.1
唯一选项：云端 API（VolcEngine doubao-1.5-ui-tars 付费 / HF Inference Endpoints 按小时付费）

关键文件

Skill: ~/.hermes/skills/productivity/reasonix/（Reasonix ACP 接入 skill）
脚本: ~/.hermes/scripts/reasonix_review_uitars.py（Reasonix 调 ACP 的 Python 模板，本任务中修复了 --preset → --model 兼容性 bug）
调研产出: 见同日 decisions/decision-log.md “UI-TARS Windows computer-use 方案搁置” 决策

Reasonix ACP v0.41 兼容性 Bug — `--preset` 已弃用

症状

python3 reasonix_review_uitars.py "<prompt>" 启动 Reasonix 后立即 EOFError: reasonix stdout closed。

根因

Reasonix CLI v0.41+ 改了参数：

旧版：reasonix acp --preset flash
新版：reasonix acp --model deepseek-v4-flash

--preset 在 v0.41 已经是 unknown option，导致 reasonix 进程一启动就 exit，stdout pipe 立刻关闭 → Python 端 readline() 拿到空行抛 EOFError。

验证

$ reasonix acp --help
Usage: reasonix acp [options]
Options:
  -m, --model <id>     DeepSeek 模型 ID（例如 deepseek-v4-flash）
  --dir <path>
  --effort <level>     推理强度 — low|medium|high|max
  --budget <usd>       会话美元上限
  ...
$ echo '' | reasonix acp --preset flash
error: unknown option '--preset'

修复

~/.hermes/scripts/reasonix_review_uitars.py：

ALLOWED_PRESETS → ALLOWED_MODELS = {deepseek-v4-flash, flash, auto}
FORBIDDEN_PRESETS → FORBIDDEN_MODELS = {deepseek-v4-pro, pro, deepseek-v3-pro, deepseek-r1}
validate_preset() → validate_model()（同时兼容 cfg.model 和 cfg.preset 两个 key）
Reasonix.__init__ 构造命令：--preset {preset} → --model {model}
修后 ping 测试成功：reasonix_review_uitars.py "test ping" → 回复 ‘pong’ ✓

教训

CLI 升级要把脚本里所有 hard-coded 参数重新核验，不能假设旧 flag 还在
v0.41 是 Reasonix 重要 breaking change（preset 概念被 model 名取代）
升级 Reasonix 后第一件事：reasonix acp --help 对比脚本用的 flags

vault-keeper `add` 子命令补完 + 数据丢失 bug 修复 — 2026-06-01

症状

skill 文档说 python vault-keeper.py add <category> <title> <content> [project] [skill_name] 可以手动加知识条目，但脚本实际只有 --fallback flag，没有 add 子命令。验证：

$ python vault-keeper.py add decision "X" "Y"
usage: vault-keeper.py [-h] [--fallback]
vault-keeper.py: error: unrecognized arguments: add decision X Y

修复 #1：补全 `add` 子命令

D:\scripts\vault-keeper\vault-keeper.py 加 cmd_add() 函数 + 重写 __main__ 块用 parse_known_args 区分 add 子命令 vs cron --fallback 路径。cmd_add 复用现有的 sync_to_vault(entries) 逻辑。

验证：

$ python vault-keeper.py add decision "test" "body"
Appended decision: test
[VaultKeeper] add → synced=1, skipped=0

修复 #2：project_note 路径的「无 marker 文件覆盖」bug

严重数据丢失事件 —— 第一次跑 add project_note ... 时，sync_to_vault 走以下分支：

if marker not in existing:
    header = f"# {proj.replace('-', ' ').title()}\n\n<!-- PROJECT NOTES DO NOT EDIT BELOW -->\n"
    f.write(header + new_entry)   # BUG: existing 整个被吞了

症状：本文件（projects/hermes-agent.md，5269 字节，含完整的 UI-TARS 调研 + Reasonix bug fix 内容）被 add project_note "smoke test" ... 一次性覆盖成 116 字节（只剩 header + smoke test），所有原有内容丢失。

根因：sync_to_vault 设计假设 “marker 不存在 = 文件不存在或没有 vault-keeper 内容”，直接覆盖。但手写内容 / 早期非 vault-keeper 路径写入的内容也没有 marker，会被误判为可覆盖。

修复（line 408-414）：

if marker not in existing:
    # 改为 header + existing + new_entry
    f.write(header + existing + new_entry)

教训

改 sync / 写文件类工具前必须先读完整文件——我只看了 30 行就动手，没看到 f.write(header + new_entry) 这行
修改前必须备份：我应该先把 projects/hermes-agent.md 备份到 C:\Users\IDA\uitars-test\obsidian-backup\
测试要在副本上跑：第一次 add 跑的是真实数据，不是测试 fixture
恢复路径：用 write_file 完整重写（本文件即是）。今后用 add 走 vault-keeper

备份位置

C:\Users\IDA\uitars-test\obsidian-backup\20260601-235547-pre-restore-hermes-agent.md（恢复前的 123 字节空壳）

免费方案调研结论 — 2026-06-01

追加调研（via Reasonix）：用户不接受付费云端后，调研所有 100% 免费 + 本地的 Windows GUI agent 替代方案。

调研对象 + 结论

ShowUI-2B（Apache-2.0, 1.85k stars, 2B params）：唯一可能装进 2GB VRAM 的模型，有 GGUF Q4_K_M 版（localattention/ShowUI-2B-Q4_K_M-GGUF）≈ 1.3-1.6GB。勉强可能但 OOM 风险高
Aguvis（无 License, 392 stars, 7B）：❌ 无 License 法律风险 + 7B 远超 2GB
SeeClick（Apache-2.0, 482 stars, 9.66B）：❌ BF16 9GB，Q4 也要 4-5GB
CogAgent-9B（Apache-2.0, 1.18k stars）：❌ BF16 29GB，INT4 8GB
OmniParser（MIT/AGPL, 24.8k stars, Microsoft）：❌ 需 GPT-4V 付费 + icon_detect AGPL copyleft
HuggingFace Inference API 免费 tier：$0.10/月 credits，等于不存在
OpenInterpreter（AGPL-3.0）：框架可用但无视觉 grounding 能力
GPT4All / LM Studio：无专门 GUI agent

硬天花板

VRAM：GT 640 / 2GB / Fermi 2012 架构，没有 INT8 tensor core
Agent loop：所有候选模型都只输出坐标，无桌面控制 agent loop
CPU 推理速度：2B Q4 模型单次推理 20-60 秒

真正可行的方案

没有。 100% 免费 + 本地 + Windows GUI agent 在 2GB VRAM 上不存在。

解锁条件（任一）

升级硬件：GTX 1060 6GB（≈¥300 二手）即可跑 ShowUI-2B Q4 + Qwen2.5-VL-3B Q4
出现新的 ≤2B 视觉 GUI agent 模型（带 agent loop）
接受付费云端（VolcEngine doubao-1.5-ui-tars）

备选：放弃视觉 agent，改用 accessibility tree

用 uiautomation（Windows 原生，PyPI 可装）+ 轻量 LLM 提取 UI 元素结构，无视觉模型也能完成基础自动化任务。但不是真正的”看屏幕”型 agent。

v0.16.0 “The Surface Release” 调研 + 桌面 app 启动 — 2026-06-06

来源：Telegram session 20260606_222957_108ee384 (22:29-23:27 MYT) 状态：升级决策已确定 (skip)；桌面 app 启动结果 defer (下次 cron)

0.16.0 changelog 摘要 (Hermes-agent v2026.6.5)

发布时间: 2026-06-05/06, PyPI + GitHub
自 v0.15.2 起: 874 commits / 542 PRs / 170 contributors
4 大新功能:
1. Hermes Desktop — Electron + React 桌面 app (apps/desktop/)
2. 远程连接 — 从外部设备连回本机 Hermes
3. Web dashboard admin — 浏览器端管理面板
4. Quick Setup portal — --portal 快速配置入口
其他改进: /undo [N] 命令、Fuzzy picker、default skill 砍掉一批、CVE 补丁、简体中文翻译
PyPI: hermes-agent==0.16.0, wheel 7.5MB

升级路径全卡 — 决定跳过 0.16.0 ✅ (user 2026-06-06 23:18 “可以”)

根因 (本机架构):

本机是 dev source 模式 (D:\hermes-agent\pyproject.toml line 7 version = "0.15.1", uv 创建的 editable install)
不是 pip wheel client, 升级不能 pip install --upgrade
路径: PyPI timeout / GitHub cache proxy 截断大包 / git fetch 全卡
但 v0.15.1 源码已含 0.16.0 几乎所有功能 (桌面 app / /undo / --portal / admin dashboard 全在源码里)

User decision: “可以” — 确认跳过升级, 保留 v0.15.1 dev source

桌面 app 启动 — 关键发现 (npm workspace hoist 坑)

问题: cd apps/desktop && npm install 只装 5 个包, electron/react 全部 missing 根因: D:\hermes-agent\package.json 有 workspaces: ["apps/*"] — npm 11 workspace 模式把所有依赖 hoist 到根 node_modules/ 误导性占位: apps/desktop/node_modules/ 只有 5 个 stub, 真实依赖在根

实测 (2026-06-06):

根 node_modules/electron@40.9.3 已装 (6/1 装过)
node-pty@1.1.0 + Windows ConPTY native build 在
@assistant-ui/{core,react,react-streamdown} 在
react@19.2.5 在
electron . 启动 (PID 25936) — 进程在跑, 无 crash, 但没收到窗口是否出现 (等 user 确认)
.bin/electron 是 sh 脚本, Windows 上不能直接 exec, 必须用 electron\dist\electron.exe 全路径

备份 (uncommitted 改动)

文件	位置
`changes.patch` 5.4KB	`C:\Users\IDA\Desktop\hermes-upgrade\diff-backup-2026-06-06\`
`hermes_cli/tools_config.py.bak`	同上
`tools/computer_use/tool.py.bak`	同上
`nul` + `document.body.innerText` (untracked)	同上

Defer (下次 cron 再写)

桌面 app 窗口是否出现 — user 👍 后 assistant 还在等 user 确认, 是 mid-Q&A 状态
是否要 npm run build (TS/Vite 编译 renderer) 后再 electron .
v0.16.0 实际升级时机 — 等 PyPI/GitHub 网络恢复后再议

decision-log (本会话决策条目)
hermes-agent-install (待整理, dev source 模式 + 升级策略)

Desktop app 启 backend 用哪个 .env — 两个独立 Hermes 部署 (2026-06-07 13:30)

来源: 续 Telegram session 20260606_222957_108ee384 (23:00 之前的 0.16.0 调研 → 13:30 desktop UI 报”没 deepseek api” debug) 状态: 根因已找到 + 修复已应用 (user 提供了真 key, 写到 %LOCALAPPDATA%\hermes\.env); A/B/C 收尾方向仍 mid-Q&A

根因 (100% 确认)

本机同时存在两个独立的 Hermes 部署目录, 互不通信:

部署	路径	谁在用	.env 内容
CLI / Telegram	`C:\Users\IDA\.hermes\`	`hermes` CLI 命令 + Telegram bot 后台进程	`TELEGRAM_BOT_TOKEN` / `MINIMAX_API_KEY` / `API_SERVER_*` / `HF_TOKEN` 等
Desktop UI	`C:\Users\IDA\AppData\Local\hermes\`	双击 “Hermes Agent” .lnk 启的 Electron 进程	之前只有 `OPENAI_BASE_URL=https://api.deepseek.com/v1`, 没有 DEEPSEEK_API_KEY

关键代码引用 (apps/desktop/electron/main.cjs):

line 4459: desktop 启的 backend 命令是 dashboard --no-open --host 127.0.0.1 --port <port> (就是 hermes dashboard CLI 子命令)
line 4485-4488 注释 (verbatim): “Windows 下我们 default 是 %LOCALAPPDATA%\hermes, 跟 C:\Users\<u>\.hermes 不一样. Mismatch would split config / sessions / .env / logs across two directories”
line 4489: spawn env 里显式 pin HERMES_HOME 传给子进程, 强制它走 %LOCALAPPDATA%
line 4466-4468: if (activeProfile) dashboardArgs.unshift('--profile', activeProfile) — profile-aware 启动

为什么 `electron .` (从 terminal 跑) 之前能调通 DeepSeek

apps/desktop/electron/main.cjs 走 hermes dashboard 子进程, 走 Python get_hermes_home():

从 bash terminal 跑 electron . → bash 父进程环境变量里有 DEEPSEEK_API_KEY (因为 terminal session 启动时 source ~/.bashrc 或类似 load 了 ~/.hermes/.env) → 子进程通过 env var 继承 拿到 key → 工作
从 .lnk 双击启 → Windows 启动器完全不知道 ~/.hermes/.env 在哪 → 它只 spawn Electron 进程, 子进程从 %LOCALAPPDATA%\hermes\.env 找 key → 文件里没有 → 报”没 deepseek api”

这就是同一个 desktop app 两种启法的差异。不是 bug, 是设计 (两个 HERMES_HOME 部署)。

修复 (已应用, 2026-06-07 13:42)

在 %LOCALAPPDATA%\hermes\.env 追加一行:

DEEPSEEK_API_KEY=sk-f84...76ea

(完整 key 是 user 私有的, 不写入 vault)

现在 %LOCALAPPDATA%\hermes\.env 内容:

OPENAI_BASE_URL=https://api.deepseek.com/v1
DEEPSEEK_API_KEY=sk-f84...76ea

重启 desktop app (双击 .lnk) → UI 内的 agent 应该能调通 DeepSeek → LLM 回复正常。

三种解法 (user 还在选 — mid-Q&A, 14:50 助手刚发完问题)

解法	操作	好处	风险
A. 统一目录	把 `%LOCALAPPDATA%\hermes` 重命名成 `%LOCALAPPDATA%\hermes.disabled`, 强制 desktop 走 `~/.hermes/`	一次配置, 两边用	`install.ps1` reinstall 时可能重建 `%LOCALAPPDATA%`
B. 同步配置 (symlink / junction)	`.env` + `config.yaml` 共享, 其他 (memory/sessions/skills) 还是分叉	稳	部分配置还是会分叉
C. 接受现状	重要的 key 改两遍; memory / session 各管各的	0 工作量	每次换 desktop 要重填

助手推荐 C: user 的使用模式是 “Telegram + CLI 为主, desktop UI 备用”, 同步两个目录 ROI 太低。

最激进选项: 干脆放弃 desktop UI, 用 Telegram + CLI 就够 (v0.16.0 才把 desktop 正式 GA, 之前是 alpha, bug 多)。

Defer (等 user 选 A/B/C)

user 选 A → 改 desktop 启动配置 (rename %LOCALAPPDATA%\hermes)
user 选 B → 写 junction 脚本 (mklink /J Windows 命令) 同步关键文件
user 选 C → 文档化 “desktop app 启动前检查清单” 提醒自己改两次 key
user 选 “放弃 desktop” → 卸 desktop 进程, 释放 RAM, 文档化 “为什么不用 desktop”

Key 安全提醒

%LOCALAPPDATA%\hermes\.env 是明文, 只对 IDA 可见 (Windows 文件权限). 但任何能物理接触电脑的人都能读. 如果怀疑泄露 → https://platform.deepseek.com/api_keys regenerate.

decision-log (0.16.0 skip 决策 + (待加) 这次 A/B/C 选择)
workflow (3h cron = same deferral 状态持续)
hermes-agent-install (待整理: 这次发现应该并入: 两个 HERMES_HOME 部署, .env 双写)

HS Knowledge Vault

探索

hermes-agent