@tunnelbox/hermes 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +97 -82
  2. package/dist/index.mjs +1485 -52
  3. package/package.json +40 -36
package/README.md CHANGED
@@ -1,82 +1,97 @@
1
- # @tunnelbox/hermes
2
-
3
- tunnelbox 的 **Hermes Agent 适配器**（B 类，独立进程，Python 框架/CLI 桥接）：手机远程驱动电脑上的 Hermes Agent（会话/流式/中止/删除），复用 `@tunnelbox/core`（RelayClient/状态/二维码）。
4
-
5
- ```
6
- 手机 PWA ──WSS──► relay ──WSS──► 本适配器（电脑上常驻 Node 进程）
7
- └─ hermes chat -q "<text>"（每消息一次子进程）
8
- ```
9
-
10
- ## 前置条件
11
-
12
- - Node.js ≥ 22；
13
- - 本机已安装 **Hermes Agent**（NousResearch/hermes-agent）并完成登录/模型配置：
14
- `curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash`（或各平台安装方式），
15
- `hermes setup` / `hermes portal` 可用，`hermes chat -q "hi"` 能正常应答。
16
- - CLI 非交互单轮模式：`hermes chat -q "…"`（`--model/--provider/--toolsets/--query-file`）。
17
-
18
- ## 构建与运行
19
-
20
- ```bash
21
- cd plugin && npm install # workspaces 根（含 hermes）
22
- cd hermes && npm run build
23
- node dist/index.mjs # 或 npm start
24
- ```
25
-
26
- ## 配置
27
-
28
- | 环境变量 | 默认 | 说明 |
29
- |---|---|---|
30
- | `TUNNELBOX_RELAY_URL` | state 保存地址 | 中继地址 |
31
- | `TUNNELBOX_CWD` | `process.cwd()` | 默认工作区 |
32
- | `TUNNELBOX_HERMES_MODEL` | hermes 默认 | `--model` |
33
- | `TUNNELBOX_HERMES_PROVIDER` | hermes 默认 | `--provider`（如 nous/openrouter） |
34
- | `TUNNELBOX_HERMES_TOOLSETS` | hermes 默认 | `--toolsets`（逗号分隔） |
35
- | `TUNNELBOX_HERMES_VERBOSE` | 关 | `--verbose` |
36
- | `TUNNELBOX_HERMES_BIN` | `hermes` | hermes 可执行名/绝对路径 |
37
-
38
- ```bash
39
- TUNNELBOX_RELAY_URL=wss://chat.example.com TUNNELBOX_HERMES_MODEL="anthropic/claude-sonnet-4" node dist/index.mjs
40
- ```
41
-
42
- ## 能力位
43
-
44
- | 能力 | 值 | 说明 |
45
- |---|---|---|
46
- | streaming | true | `hermes chat -q` stdout 增量剥离 ANSI 后按到达转发 delta |
47
- | thinking | false | `-q` 无结构化推理部件 |
48
- | permission | **false** | 无审批回调；工具集/授权由 hermes 自身安全策略决定 |
49
- | commands | true | `/new` `/help` |
50
- | abort | true | kill 子进程（SIGTERM → SIGKILL） |
51
-
52
- ## 会话模型
53
-
54
- - 会话 = 本地镜像（`~/.config/opencode/hermes-sessions/<uuid>/`）：每个流式部件/用户消息即时落一行，供列表/历史/删除。
55
- - 续聊：尽力从输出解析 hermes session id（形如 `20260225_143052_a1b2c3`，`meta.resumeId`）→ 后续消息用 `--resume <id>`；解析不到则该会话每次为独立问答（连续上下文受限）。
56
- - 状态文件：`~/.config/opencode/remote-state.hermes.json`。
57
-
58
- ## 官方 Hermes 插件（native-plugin）
59
-
60
- 本包同时提供符合 Hermes 官方插件体系的 **Native 插件**（`native-plugin/`，Python，`plugin.yaml` + `register(ctx)`），
61
- 在本机 Hermes 会话内使用（工具 `tunnelbox_pair`/`tunnelbox_status`、`/tunnelbox` 命令、打包技能 + 实验性回合级手机桥）——
62
- 功能主体仍由本 headless 桥承担。安装/配置/局限见 [`native-plugin/README.md`](./native-plugin/README.md)。
63
-
64
- ## 目录结构
65
-
66
- ```
67
- plugin/hermes/
68
- ├── package.json / tsconfig.json
69
- ├── scripts/build.mjs / smoke.mjs
70
- ├── native-plugin/ # ★ Hermes 官方 Native 插件（Python，本机会话内配对/状态 + 回合级桥实验）
71
- └── src/
72
- ├── index.ts # env 解析 + 连接中继
73
- ├── bridge.ts # relay/配对/消息路由/回合/镜像写入
74
- ├── runner.ts # hermes chat -q 子进程（stdout 增量 + ANSI 剥离 + session id 采集 + kill）
75
- ├── mirror.ts # 会话镜像存储（列表/历史/删除/meta）
76
- └── globals.d.ts
77
- ```
78
-
79
- ## 备注
80
-
81
- - 未验证项（需装有 hermes 实测校正）：`hermes chat -q` 在 stdout 的确切输出（是否 ANSI/分批/进度行）、`chat -q` 下 `--resume` 参数位置与语义、session id 是否出现在 `-q` 输出中、`--toolsets/--provider` 参数名。解析集中在 `runner.ts`。
82
- - 安全：hermes 工具执行/命令授权由其自身策略（config/安全文档）管理，本适配器不自动放行；请勿在不受信目录运行时不受限工具集。
1
+ # @tunnelbox/hermes
2
+
3
+ tunnelbox 的 **Hermes Agent 适配器**（B 类，独立进程，Python 框架/CLI 桥接）：手机远程驱动电脑上的 Hermes Agent（会话/流式/中止/删除），复用 `@tunnelbox/core`（RelayClient/状态/二维码）。
4
+
5
+ ```
6
+ 手机 PWA ──WSS──► relay ──WSS──► 本适配器（电脑上常驻 Node 进程）
7
+ └─ hermes chat -q "<text>"（每消息一次子进程）
8
+ ```
9
+
10
+ ## 前置条件
11
+
12
+ - Node.js ≥ 22；
13
+ - 本机已安装 **Hermes Agent**（NousResearch/hermes-agent）并完成登录/模型配置：
14
+ `curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash`（macOS/Linux/WSL）；Windows PowerShell：`iex (irm https://hermes-agent.nousresearch.com/install.ps1)`，
15
+ `hermes setup` / `hermes portal` 可用，`hermes chat -q "hi"` 能正常应答。
16
+ - CLI 非交互单轮模式：`hermes chat -q "…"`（`--model/--provider/--toolsets/--query-file`）。
17
+
18
+ ## 构建与运行
19
+
20
+ ```bash
21
+ cd plugin && npm install # workspaces 根（含 hermes）
22
+ cd hermes && npm run build
23
+ node dist/index.mjs # 或 npm start
24
+ ```
25
+
26
+ ## 配置
27
+
28
+ | 环境变量 | 默认 | 说明 |
29
+ |---|---|---|
30
+ | `TUNNELBOX_RELAY_URL` | state 保存地址 | 中继地址 |
31
+ | `TUNNELBOX_CWD` | `process.cwd()` | 默认工作区 |
32
+ | `TUNNELBOX_HERMES_MODEL` | hermes 默认 | `--model` |
33
+ | `TUNNELBOX_HERMES_PROVIDER` | hermes 默认 | `--provider`（如 nous/openrouter） |
34
+ | `TUNNELBOX_HERMES_TOOLSETS` | hermes 默认 | `--toolsets`（逗号分隔） |
35
+ | `TUNNELBOX_HERMES_VERBOSE` | 关 | `--verbose` |
36
+ | `TUNNELBOX_HERMES_BIN` | `hermes` | hermes 可执行名/绝对路径 |
37
+ | `TUNNELBOX_HERMES_APPROVAL` | `on` | 手机审批开关：`on`/`off`。开启后经 Hermes `pre_tool_call` hook 把工具请求推到手机审批卡（**实验**，见「手机审批」） |
38
+ | `TUNNELBOX_HERMES_HOOK_PORT` | `18791` | 本地审批 HTTP 服务端口（hook 子进程与适配器通信用） |
39
+
40
+ ```bash
41
+ TUNNELBOX_RELAY_URL=wss://chat.example.com TUNNELBOX_HERMES_MODEL="anthropic/claude-sonnet-4" node dist/index.mjs
42
+ ```
43
+
44
+ ## 能力位
45
+
46
+ | 能力 | 值 | 说明 |
47
+ |---|---|---|
48
+ | streaming | true | `hermes chat -q` stdout 增量剥离 ANSI 后按到达转发 delta |
49
+ | thinking | false | `-q` 无结构化推理部件 |
50
+ | permission | **true**（`TUNNELBOX_HERMES_APPROVAL=on`，默认） | 经 Hermes `pre_tool_call` hook 推送到手机审批卡；HTTP 服务不可达→放行 no-op，请求已接受但离线/超时/异常→fail-closed 拒绝（**实验**） |
51
+ | commands | true | `/new` `/help` |
52
+ | abort | true | kill 子进程（SIGTERM → SIGKILL） |
53
+
54
+ ## 手机审批（实验）
55
+
56
+ Hermes 的 `pre_tool_call` hook（shell，CLI/Gateway 均运行，见 [hermes-agent.nousresearch.com/docs/user-guide/features/hooks](https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks)）在工具执行前触发。本适配器据此实现手机审批：
57
+
58
+ - 适配器启动时把 `pre_tool_call` shell hook 幂等注入 `~/.hermes/config.yaml` 的 `hooks.pre_tool_call`（`node "<入口>" --hook-pre-tool-call`，写前备份 `config.yaml.tunnelbox.bak`，解析失败仅告警不覆盖）；
59
+ - Hermes 每次工具调用前触发该 hook → hook 把请求 POST 到适配器本地 HTTP（`127.0.0.1:18791`）→ 适配器经中继推送 `permission.request` 到手机权限卡；
60
+ - 手机 allow/deny 回填后 hook 写回 Hermes：deny → block JSON + exit 2（Hermes 拦截工具）；allow → 空输出（no-op，放行）；
61
+ - **语义**：HTTP 服务不可达（适配器未运行 / `approval=off`）→ hook no-op 放行（等同无 hook，不误拦）；请求已被接受但手机离线 / 超时（120s）/ 异常 → fail-closed 拒绝。
62
+
63
+ ⚠️ **实验性**：Hermes 官方未明确 `hermes chat -q`（single-query）是否运行 config shell hooks、`pre_tool_call` 的 block 输出 schema、hook 首次使用同意提示等，均需装 hermes CLI 后实测校正。另注意 Hermes 内置审批系统（`approvals.mode`、`single_query_mode`：`-q` 下危险命令默认 `deny`、可配 `approve` 自动放行）与本 hook 相互独立。如遇异常可 `TUNNELBOX_HERMES_APPROVAL=off` 关闭（此时注入的 hook 因服务不可达自动放行，恢复无 hook 行为）。
64
+
65
+ ## 会话模型
66
+
67
+ - 会话 = 本地镜像（`~/.tunnelbox/hermes-sessions/<uuid>/`）：每个流式部件/用户消息即时落一行，供列表/历史/删除。
68
+ - 续聊：尽力从输出解析 hermes session id（形如 `20260225_143052_a1b2c3`，`meta.resumeId`）→ 后续消息用 `--resume <id>`；解析不到则该会话每次为独立问答（连续上下文受限）。
69
+ - 状态文件：`~/.tunnelbox/remote-state.hermes.json`。
70
+
71
+ ## 官方 Hermes 插件（native-plugin）
72
+
73
+ 本包同时提供符合 Hermes 官方插件体系的 **Native 插件**（`native-plugin/`，Python，`plugin.yaml` + `register(ctx)`），
74
+ 在本机 Hermes 会话内使用（工具 `tunnelbox_pair`/`tunnelbox_status`、`/tunnelbox` 命令、打包技能 + 实验性回合级手机桥）——
75
+ 功能主体仍由本 headless 桥承担。安装/配置/局限见 [`native-plugin/README.md`](./native-plugin/README.md)。
76
+
77
+ ## 目录结构
78
+
79
+ ```
80
+ plugin/hermes/
81
+ ├── package.json / tsconfig.json
82
+ ├── scripts/build.mjs / smoke.mjs
83
+ ├── native-plugin/ # ★ Hermes 官方 Native 插件（Python，本机会话内配对/状态 + 回合级桥实验）
84
+ └── src/
85
+ ├── index.ts # env 解析 + 连接中继 + --hook-pre-tool-call 子进程入口
86
+ ├── bridge.ts # relay/配对/消息路由/回合/镜像写入 + 审批接线
87
+ ├── approval.ts # 手机审批桥（HTTP 服务 + config.yaml hook 安装 + hook 子进程）
88
+ ├── runner.ts # hermes chat -q 子进程（stdout 增量 + ANSI 剥离 + session id 采集 + kill）
89
+ ├── mirror.ts # 会话镜像存储（列表/历史/删除/meta）
90
+ └── globals.d.ts
91
+ ```
92
+
93
+ ## 备注
94
+
95
+ - 未验证项（需装有 hermes 实测校正）：`hermes chat -q` 在 stdout 的确切输出（是否 ANSI/分批/进度行）、`chat -q` 下 `--resume` 参数位置与语义、session id 是否出现在 `-q` 输出中、`--toolsets/--provider` 参数名。解析集中在 `runner.ts`。
96
+ - **手机审批待实测**：`-q` 是否运行 config shell hooks、`pre_tool_call` block 输出 schema、hook 首次使用同意提示、`approval=off` 时 hook 放行语义——相关实现集中在 `approval.ts`。
97
+ - 安全：hermes 工具执行/命令授权由其自身策略（config/安全文档）管理，本适配器不自动放行；请勿在不受信目录运行时不受限工具集。