krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Integrate master agent runtime orchestration updates

Browse Source
This commit is contained in:
kris
2026-04-16 04:41:46 +08:00
parent e0c0ea1814
commit 39be49630f
81 changed files with 9283 additions and 448 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/architecture/ai_handoff_index_cn.md
View File

@@ -23,6 +23,7 @@
6. `docs/architecture/wechat_project_conversation_mapping_cn.md`
7. `docs/architecture/thread_context_budget_and_handoff_protocol_cn.md`
8. `prompts/codex_fullstack_build_and_deploy_prompt_cn.md`
9. `docs/superpowers/specs/2026-04-16-master-agent-fast-path-design.md`
## 3. 当前有效实现边界

36
docs/architecture/api_and_service_inventory_cn.md
View File

@@ -185,6 +185,11 @@
- 当前已最小接入 `ClawBackendAdapter`，但默认关闭，仅在显式配置且可用性探测通过时才参与执行
- 如果历史 `backendOverride=claw-runtime` 当前不可用，运行时会自动回退到默认后端，并把原因回给前台
- 当前仓库自带 `scripts/claw-runtime-smoke.mjs` 作为兼容 JSON 协议的 smoke runtime，可用于本地和服务器验证 `ClawBackendAdapter`
- 当前已最小接入 `Hermes Runtime`，但默认关闭，仅在显式配置且可用性探测通过时才参与执行
- 如果历史 `backendOverride=hermes-runtime` 当前不可用，运行时会自动回退到默认后端，并把原因回给前台
- 当前仓库自带 `scripts/hermes-runtime-smoke.mjs`，可用于本地和服务器验证 `Hermes Runtime`
- 当前 `master-agent` 会话已支持显式选择 `hermes-runtime`
- 当前普通单线程会话也已支持显式保存 `backendOverride=hermes-runtime`；未设置 override 时仍走原有目标设备本地线程回复链，显式设置后服务端会异步调用 `Hermes Runtime` 并把结果回写到原线程消息流
- 当前已最小接入 `OmxTeamBackendAdapter`，但默认关闭；Web 群聊详情页和原生群资料页已经可以在 `Boss Native` 与 `OMX Team` 间切换编排后端，OMX 不可用时会自动回退到默认后端并返回明确原因
- 当前仓库自带 `scripts/omx-team-smoke.mjs`，可用于本地和服务器验证 `OmxTeamBackendAdapter` 的 `dispatch_execution` JSON 协议
@@ -200,6 +205,19 @@
- `heartbeat / thread reply` 平时优先写轻量进展事件
- 首次理解、状态变薄、长时间未刷新或主 Agent 真正接手时，才补排隐藏全量理解任务
### 3.1.3 主 Agent 任务级模型策略
- 当前任务账本 `masterAgentTasks` 已支持：
- `executionModel`
- `executionReasoningEffort`
- 当前用途：
- 把 `master-agent` 会话上的 `smart*` 策略真正下发给深度任务，而不是只停留在设置页
- 让 `group_dispatch_plan / device_import_resolution / attachment_analysis` 这类深度任务可以和普通聊天使用不同模型
- 当前执行链：
- 服务端排队深度任务时写入 `executionModel / executionReasoningEffort`
- `local-agent/codex-task-runner.mjs` 执行时优先使用任务级 `executionModel`
- `executionReasoningEffort` 当前已落到任务账本，供后续继续扩到更多 Runtime / API 执行器
### 3.2 认证相关
#### `POST /api/auth/send-code`
@@ -383,6 +401,8 @@
- `kind`: `text | voice_intent | image_intent | video_intent`
- 当前行为：
- 普通单线程项目当前会在写入用户消息后，继续创建 `taskType=conversation_reply` 的主 Agent 任务
- 如果该普通单线程项目当前显式设置了 `backendOverride=hermes-runtime`，这条 `conversation_reply` 会改挂到 `master-agent-hermes / hermes-runtime`
- 如果普通单线程项目没有显式设置 `backendOverride`，仍保持原有 `local-agent -> codex exec resume` 路径不变
- 返回体会附带 `task.taskId / taskType / status`，给 Web 和原生 Android 保持等待真实回写使用
- `projectId=master-agent` 且 `kind=text` 时，会先返回 `masterReplyState + task`，真实回复随后异步回写到账本
- 当前主链路优先走 `Master Codex Node`：`task queue -> local-agent -> codex exec -> complete`
@@ -394,19 +414,21 @@
#### `GET /api/v1/projects/[projectId]/agent-controls`
- 用途：读取当前对话级别的 `modelOverride / reasoningEffortOverride / backendOverride`
- 用途：读取当前对话级别的模型、推理、后端与接管控制
- 当前约束：
- 当前只支持 `projectId=master-agent`
- `projectId=master-agent` 时支持 `modelOverride / reasoningEffortOverride / fastModelOverride / fastReasoningEffortOverride / smartModelOverride / smartReasoningEffortOverride / promptOverride / backendOverride / globalTakeoverEnabled`
- 普通单线程项目当前只会返回 `takeoverEnabled / backendOverride` 这类会话级覆盖
- 未配置时返回 `controls: null`
#### `POST /api/v1/projects/[projectId]/agent-controls`
- 用途：更新当前对话级别的 `modelOverride / reasoningEffortOverride / promptOverride / backendOverride`
- 用途：更新当前对话级别的模型、推理、后端与接管控制
- 当前约束：
- 当前只支持 `projectId=master-agent`
- 仅 `highest_admin` 可写
- `backendOverride` 当前仅支持 `claw-runtime`
- 只有在 `Claw Runtime` 可用性探测通过时才允许保存 `claw-runtime`
- `master-agent` 会话当前支持 `modelOverride / reasoningEffortOverride / fastModelOverride / fastReasoningEffortOverride / smartModelOverride / smartReasoningEffortOverride / promptOverride / backendOverride / globalTakeoverEnabled`
- 主 Agent 普通聊天回复会按 `fast*` 默认策略解析模型与推理强度，深度任务保留 `smart*` 默认策略入口；显式 `modelOverride / reasoningEffortOverride` 始终优先于 fast/smart 策略
- 普通单线程会话当前只支持 `takeoverEnabled / backendOverride`
- 普通单线程会话的 `backendOverride` 当前只允许 `hermes-runtime`，不开放 `claw-runtime`
- 只有在对应 Runtime 可用性探测通过时才允许保存对应覆盖
- 显式传 `null` 或空字符串表示清空覆盖；省略字段表示保留原值
#### `GET /api/v1/projects/[projectId]/orchestration-backend`

9
docs/architecture/current_runtime_and_deploy_status_cn.md
View File

@@ -31,6 +31,10 @@
- 当前 `claw-code` 已以最小 `ClawBackendAdapter` 形式接入执行底座，但默认关闭；只有显式配置 `BOSS_CLAW_*` 且可用性探测通过时，`master-agent` 当前对话中才会出现并允许选择 `claw-runtime`
- 如果历史上已经保存过 `backendOverride=claw-runtime`，但当前 `Claw Runtime` 不可用，运行时会自动回退到默认后端，并在 Web/Android 前台给出明确原因
- 当前仓库已自带 `scripts/claw-runtime-smoke.mjs` 作为本地 smoke runtime；在没有真实 `claw-code` 可执行文件时，可先用 `BOSS_CLAW_COMMAND=node` 与 `BOSS_CLAW_ARGS=scripts/claw-runtime-smoke.mjs` 验证整条链
- 当前 `hermes-agent` 已以最小 `Hermes Runtime` 形式接入执行底座，但默认关闭；只有显式配置 `BOSS_HERMES_*` 且可用性探测通过时，`master-agent` 当前对话中才会出现并允许选择 `hermes-runtime`
- 如果历史上已经保存过 `backendOverride=hermes-runtime`，但当前 `Hermes Runtime` 不可用，运行时会自动回退到默认后端，并在 Web 前台给出明确原因
- 当前仓库已自带 `scripts/hermes-runtime-smoke.mjs` 作为本地 Hermes smoke runtime；在没有真实 `hermes` 可执行文件时，可先用 `BOSS_HERMES_COMMAND=node` 与 `BOSS_HERMES_ARGS=scripts/hermes-runtime-smoke.mjs` 验证整条链
- 当前普通单线程会话也已支持对话级 `backendOverride=hermes-runtime`；未显式设置时仍走原有 `local-agent -> codex exec resume` 回复链，显式设置后会由服务端异步调用 `Hermes Runtime` 执行普通线程回复，并直接通过 `completeMasterAgentTask` 回写到原线程会话
- 当前 `oh-my-codex` 已以最小 `OmxTeamBackendAdapter` 形式接入执行底座，但默认关闭；当前已经接到 Web 群聊详情页 / 原生群资料页的编排后端选择卡，可在 `Boss Native` 与 `OMX Team` 间切换，OMX 不可用时会自动回退到默认后端并明确提示原因
- 当前仓库已自带 `scripts/omx-team-smoke.mjs` 作为本地 OMX smoke runtime；在没有真实 `oh-my-codex` 可执行文件时，可先用 `BOSS_OMX_COMMAND=node` 与 `BOSS_OMX_ARGS=scripts/omx-team-smoke.mjs` 验证 `dispatch_execution` 的真实执行 contract
- 当前主 Agent 对活跃线程的理解已经升级成“线程状态文档 + 最近进展事件 + 关键时刻深拉”：`projectUnderstanding` 不再是唯一输入，`threadStatusDocuments / threadProgressEvents` 已进入主 Agent prompt 主链
@@ -158,8 +162,9 @@ cd /Users/kris/code/boss
- `POST /api/v1/accounts/[accountId]/validate` 当前对 `master_codex_node` 不再只看 `nodeId`，还会同时校验绑定设备是否在线；设备离线时返回 `degraded` 和清晰的人类可读提示
- 主 Agent 当前真实对话链路已验证通过：`Boss Web -> /api/v1/projects/master-agent/messages -> master-agent task queue -> local-agent -> codex exec -> /complete -> 项目消息账本`
- 主 Agent 单聊当前已改成“快速入队 + 异步回流”：`POST /api/v1/projects/master-agent/messages` 会先返回 `masterReplyState + task`，真实回复随后再回写消息账本
- 当前对话级 `agentControls` 已经生效：`master-agent` 会话支持 `modelOverride / reasoningEffortOverride`，并会优先作用到实际 OpenAI 回复和 Master Codex Node 执行 prompt
- 当前对话级 `agentControls` 也已支持 `backendOverride`：`master-agent` 会话可在 `Claw Runtime` 可用时显式选择 `claw-runtime`，由 `ExecutionBackendSelector` 在当前对话里优先尝试对应后端；不可用时保存接口会直接拒绝，并返回人类可读原因
- 当前对话级 `agentControls` 已经生效：`master-agent` 会话支持 `modelOverride / reasoningEffortOverride` 强制覆盖，也支持 `fastModelOverride / fastReasoningEffortOverride / smartModelOverride / smartReasoningEffortOverride` 这组策略默认值；主 Agent 普通对话默认按 fast 档选模型，深度任务可按 smart 档选模型，手动强制覆盖仍然优先级最高
- 当前 `group_dispatch_plan / device_import_resolution / attachment_analysis` 三类深度任务已经会把 `smart*` 策略下发到任务队列，并随任务持久化 `executionModel / executionReasoningEffort`；local-agent 执行这类任务时会优先吃任务级模型，不再只依赖本机固定默认模型
- 当前对话级 `agentControls` 也已支持 `backendOverride`：`master-agent` 会话可在 `Claw Runtime` 或 `Hermes Runtime` 可用时显式选择 `claw-runtime / hermes-runtime`，普通单线程会话当前只开放 `hermes-runtime`；不可用时保存接口会直接拒绝，并返回人类可读原因
- 原生 Android 当前会把 `master-agent` 的等待态保留在消息流里：发送后常驻显示“主 Agent 思考中”，超时后改成“主 Agent 回复超时 + 重试等待”，收到新回复后会自动清掉，不再只靠 toast 提示
- `GET /api/v1/app-logs` 当前已支持登录态分页查询
- `POST /api/v1/app-logs`、`POST /api/v1/devices/[deviceId]/skills`、`POST /api/v1/workers/[workerId]/thread-context` 当前都要求有效设备 token 或匹配登录会话

472
docs/architecture/hermes_runtime_接入与运维指南_cn.md Normal file
View File

@@ -0,0 +1,472 @@
# Hermes Runtime 接入与运维指南
更新时间：`2026-04-14`
## 1. 文档目标
这份文档只回答一个问题：
- Boss 当前已经接入的 `hermes-runtime`，本地和服务器应该怎么配、怎么验、怎么运维
它面向两类人：
- 开发者：想先在本机把 Hermes 链路跑通
- 运维：想把 Hermes 作为 Boss 的一个可选执行后端部署到稳定环境
这不是长期架构文档。长期方向请看：
- `docs/architecture/hermes_对_boss_主agent长期融合评估_cn.md`
## 2. 当前实现边界
当前 Boss 对 Hermes 的接入边界很明确：
- Hermes 现在是 `ExecutionBackend` 下的一个可选后端，`backendId=hermes-runtime`
- 当前接入方式是外部 CLI 调用，不直接 import Hermes Python 代码
- 当前支持的请求类型只有：
- `master_agent_reply`
- `thread_reply`
- 当前不支持：
- `dispatch_execution`
- 群聊编排
- 会话级 session resume
- Honcho / ACP / API server 深融合
Boss 当前对 Hermes 的固定调用形态是：
```text
<command> <prefix args> chat -q <executionPrompt> -Q --source <sourceTag>
```
可选追加：
- `-m <model>`
- `-t <toolsets>`
- `-s <skills>`
Boss 会自动剥掉 Hermes quiet 输出末尾的：
```text
session_id: ...
```
只把正文写回 Boss 对话账本。
## 3. 环境变量说明
当前 Hermes 接入读取以下环境变量。
### 3.1 核心开关
#### `BOSS_HERMES_ENABLED`
- 含义：是否启用 Hermes Runtime
- 可选值：`true | false`
- 默认值：`false`
只有为 `true` 时，Boss 才会把 Hermes 纳入可选后端探测。
#### `BOSS_HERMES_COMMAND`
- 含义：启动 Hermes 的主命令
- 默认值：`hermes`
常见写法：
- `hermes`
- `uv`
- `python3`
- `node`
说明：
- 如果你已经把 Hermes 安装成全局命令，直接用 `hermes`
- 如果你用 `uv run ...` 启动 Hermes，就把命令写成 `uv`
- 如果你通过脚本入口启动，就把命令写成对应运行时，例如 `python3` 或 `node`
#### `BOSS_HERMES_ARGS`
- 含义：追加在 `BOSS_HERMES_COMMAND` 后、`chat -q ...` 前面的前缀参数
- 默认值：空
例子：
```bash
BOSS_HERMES_ARGS="run --directory /opt/hermes-agent hermes"
```
最终实际执行会变成：
```bash
uv run --directory /opt/hermes-agent hermes chat -q "..." -Q --source tool
```
如果你是脚本入口，也可以这样写：
```bash
BOSS_HERMES_COMMAND=python3
BOSS_HERMES_ARGS="/opt/hermes-agent/cli.py"
```
### 3.2 运行目录与超时
#### `BOSS_HERMES_WORKDIR`
- 含义：Hermes 运行时工作目录
- 默认值：未设置
推荐：
- 本地开发：设置成 Boss 工作区或 Hermes 工作区
- 服务器：显式设置，不依赖 `process.cwd()`
#### `BOSS_HERMES_TIMEOUT_MS`
- 含义：单次 Hermes CLI 调用的超时毫秒数
- 默认值：`120000`
建议：
- 本地 smoke：`5000` 到 `15000`
- 日常开发：`30000` 到 `120000`
- 生产服务：不要无限拉长，先用 `60000` 到 `120000`
### 3.3 模型、toolsets、skills
#### `BOSS_HERMES_DEFAULT_MODEL`
- 含义：当前对话未显式覆盖模型时，Boss 传给 Hermes 的默认模型名
- 默认值：无
#### `BOSS_HERMES_TOOLSETS`
- 含义：逗号分隔的 Hermes toolsets
- 示例：`web,terminal`
Boss 会转成：
```bash
-t web,terminal
```
#### `BOSS_HERMES_SKILLS`
- 含义：逗号分隔的 Hermes skills
- 示例：`boss-dev,github`
Boss 会转成：
```bash
-s boss-dev,github
```
#### `BOSS_HERMES_SOURCE_TAG`
- 含义：传给 Hermes 的 `--source` 标记
- 默认值：`tool`
通常保持默认即可。
## 4. 可用性探测规则
Boss 当前对 Hermes 的可用性探测是保守模式。
它会检查：
1. `BOSS_HERMES_ENABLED=true`
2. `BOSS_HERMES_COMMAND` 可执行
3. 如果设置了 `BOSS_HERMES_WORKDIR`，目录必须存在
4. 如果命令是脚本运行时：
- `node`
- `tsx`
- `bun`
- `deno`
- `python`
- `python3`
那么 `BOSS_HERMES_ARGS` 的第一个参数会被视为脚本路径，并检查该脚本是否存在
因此有两个实践建议：
- 用全局 `hermes` 命令时，最省心
- 用脚本入口时，第一段参数一定要是真实脚本路径，不要把不存在的包装路径塞进去
## 5. 本地 Smoke 验证
这是当前最推荐的第一步，因为它不依赖真实 Hermes 环境。
### 5.1 环境变量
在 Boss 工作区里设置：
```bash
export BOSS_HERMES_ENABLED=true
export BOSS_HERMES_COMMAND=node
export BOSS_HERMES_ARGS=scripts/hermes-runtime-smoke.mjs
export BOSS_HERMES_WORKDIR=/Users/kris/code/boss
export BOSS_HERMES_TIMEOUT_MS=5000
```
### 5.2 启动 Boss
```bash
cd /Users/kris/code/boss
npm run build
npm start
```
### 5.3 验证方式
验证点有三层：
1. `GET /api/v1/projects/master-agent/agent-controls`
- 应该能看到 `hermesAvailability.selectable=true`
2. 在 `master-agent` 会话里保存 `backendOverride=hermes-runtime`
3. 给 `master-agent` 或普通单线程会话发消息
- 应该看到任务进入 `queued`
- 随后回写 smoke 内容
如果只想测后端契约，不测前端，也可以直接跑测试：
```bash
npx tsx --test tests/hermes-backend-config.test.ts tests/hermes-runner.test.ts tests/hermes-backend.test.ts
```
## 6. 真实 Hermes CLI 接入
当前推荐两种方式。
### 6.1 方式 A：系统里已经有 `hermes` 命令
适合：
- 已经通过官方推荐方式安装 Hermes
- `PATH` 里直接能找到 `hermes`
示例：
```bash
export BOSS_HERMES_ENABLED=true
export BOSS_HERMES_COMMAND=hermes
export BOSS_HERMES_WORKDIR=/opt/hermes-workspace
export BOSS_HERMES_TIMEOUT_MS=60000
export BOSS_HERMES_DEFAULT_MODEL=gpt-5.4
export BOSS_HERMES_TOOLSETS=web,terminal
```
优点：
- 配置最简单
- 可用性探测最稳定
缺点：
- 依赖系统环境已经正确安装 Hermes
### 6.2 方式 B：通过 `uv run` 进入 Hermes 仓库
适合：
- 不想做全局安装
- 希望固定某个 Hermes checkout 或虚拟环境
示例：
```bash
export BOSS_HERMES_ENABLED=true
export BOSS_HERMES_COMMAND=uv
export BOSS_HERMES_ARGS="run --directory /opt/hermes-agent hermes"
export BOSS_HERMES_WORKDIR=/opt/hermes-workspace
export BOSS_HERMES_TIMEOUT_MS=60000
export BOSS_HERMES_DEFAULT_MODEL=gpt-5.4
```
优点：
- 上游版本更可控
- 不污染全局命令
缺点：
- `uv` 自身必须已安装
- `BOSS_HERMES_ARGS` 更容易配错
## 7. 服务器侧推荐做法
Boss 当前服务器是：
- 主机：`106.53.170.158`
- 代码路径：`/opt/boss`
如果要在服务器上给 Boss 打开 Hermes，推荐这样做。
### 7.1 目录分离
不要把 Hermes 仓库直接塞进 Boss 仓库里。
推荐：
- Boss 代码：`/opt/boss`
- Hermes 代码：`/opt/hermes-agent`
- Hermes 工作目录：`/opt/hermes-workspace`
原因：
- 便于各自升级
- 避免把 Boss 构建、部署、权限模型和 Hermes 混在一起
### 7.2 运行用户一致
Boss 当前服务是 `ubuntu` 用户启动。
Hermes 也尽量用同一运行用户准备环境，避免：
- `boss-web.service` 能启动 Boss，但找不到 Hermes 环境
- `uv` 或虚拟环境只在 root 下可用
- 工作目录权限错乱
### 7.3 systemd 环境显式注入
如果是服务器长期运行，不要只靠 shell profile。
推荐把以下变量写进 `boss-web.service` 的环境或 `.env.server`：
```bash
BOSS_HERMES_ENABLED=true
BOSS_HERMES_COMMAND=uv
BOSS_HERMES_ARGS=run --directory /opt/hermes-agent hermes
BOSS_HERMES_WORKDIR=/opt/hermes-workspace
BOSS_HERMES_TIMEOUT_MS=60000
```
### 7.4 先做 smoke，再切真实 runtime
推荐顺序：
1. 先用 `scripts/hermes-runtime-smoke.mjs` 验证 Boss 侧链路
2. 再切到真实 Hermes CLI
3. 再让 `master-agent` 选择 `hermes-runtime`
4. 最后再放开普通线程的小范围试用
不要一上来就在服务器上直接切真实 Hermes，然后把问题混在：
- Boss 路由
- 环境变量
- Hermes 安装
- 模型配置
- toolsets
- 权限问题
## 8. 不建议的做法
当前阶段，明确不建议以下做法。
### 8.1 不建议把 Hermes 当 Boss 的主运行真相
不要把这些直接交给 Hermes：
- 会话账本
- 群聊成员真相
- 审批状态
- 设备导入状态
- 项目/线程业务归属
这些必须继续留在 Boss。
### 8.2 不建议直接依赖 Hermes SQLite 或 ACP 会话作为 Boss 会话真相
原因：
- Boss 的项目/线程/群聊模型和 Hermes session 模型不是一回事
- 当前 Boss 还没有 session binding 抽象
- ACP 会话也不是 Boss 的业务真相
### 8.3 不建议第一批就打开高风险 toolsets
如果只是验证 Hermes 接入，不要一开始就把所有工具都打开。
先用最小集合：
- 可只开基础聊天
- 如果确实要工具，先开低风险 toolsets
原因：
- 当前 Boss 还没有完整的 `PermissionPolicy -> runtime policy` 映射
- 先验证后端链路，再扩大能力面更稳
### 8.4 不建议把 Hermes 和 local-agent 混成同一执行器
当前普通线程默认路径仍然是：
```text
Boss -> queue conversation_reply -> local-agent -> codex exec resume -> complete
```
只有显式设置 `backendOverride=hermes-runtime` 时，才会切到 Hermes 占位任务路径。
不要把这两条链未经抽象就揉成一个执行器，否则后面很难排查问题。
## 9. 推荐排障顺序
如果 `Hermes Runtime` 在前台不可选，按这个顺序查。
### 9.1 先查可用性
看接口返回：
- `GET /api/v1/projects/master-agent/agent-controls`
- `GET /api/v1/projects/master-agent/prompt-profile`
重点字段：
- `hermesAvailability.status`
- `hermesAvailability.reason`
- `hermesAvailability.reasonLabel`
### 9.2 再查命令本身能不能跑
例如：
```bash
hermes --help
```
或：
```bash
uv run --directory /opt/hermes-agent hermes --help
```
### 9.3 再查 Boss 最终会拼成什么命令
当前 Boss 固定会在你的前缀后补：
```bash
chat -q "<executionPrompt>" -Q --source tool
```
所以要确认你的命令前缀真的兼容这种拼法。
### 9.4 最后查任务回写
如果前台已经能选 Hermes，但消息没有回流：
- 查 `masterAgentTasks`
- 查 `/api/v1/master-agent/tasks/[taskId]/complete`
- 查 Boss 日志里是否是 Hermes 执行失败后回退到别的后端
## 10. 当前推荐结论
如果你现在要让 Boss 用 Hermes，推荐顺序是：
1. 先用 `scripts/hermes-runtime-smoke.mjs` 验证 Boss 契约
2. 再接真实 Hermes CLI
3. 先只给 `master-agent` 打开
4. 再按项目给普通单线程会话灰度打开 `backendOverride=hermes-runtime`
5. 群聊编排、session resume、Honcho、ACP、API server 后续再做
当前阶段最稳的定位仍然是：
- Boss 负责产品真相
- Hermes 负责可替换执行 runtime

772
docs/architecture/hermes_对_boss_主agent长期融合评估_cn.md Normal file
View File

@@ -0,0 +1,772 @@
# Hermes 对 Boss 主 Agent / 业务流的长期融合评估
更新时间：`2026-04-14`
## 1. 文档目标
这份文档回答四个问题：
1. Hermes 对 Boss 主 Agent 的长期参考价值是什么
2. 哪些能力值得抽象进 Boss 内核，哪些不要借
3. 第二阶段与第三阶段建议路线
4. 风险、边界和升级策略
这不是一份“把 Hermes 整体接进 Boss”的实施说明，而是一份长期架构判断文档。结论基于以下输入：
- Boss 当前运行真相与既有融合策略：
- `docs/architecture/boss_external_runtime_fusion_strategy_cn.md`
- `docs/architecture/current_runtime_and_deploy_status_cn.md`
- `docs/architecture/api_and_service_inventory_cn.md`
- `docs/superpowers/specs/2026-04-14-hermes-backend-mvp-design.md`
- Boss 当前 Hermes MVP 实现：
- `src/lib/execution/backends/hermes-config.ts`
- `src/lib/execution/backends/hermes-runner.ts`
- `src/lib/execution/backends/hermes-backend.ts`
- `src/lib/execution/backend-selector.ts`
- 对应 Web 控制与测试文件
- Hermes 官方公开文档：
- README: `https://raw.githubusercontent.com/NousResearch/hermes-agent/main/README.md`
- Quickstart: `https://hermes-agent.nousresearch.com/docs/getting-started/quickstart/`
- Architecture: `https://hermes-agent.nousresearch.com/docs/developer-guide/architecture/`
- Session Storage: `https://hermes-agent.nousresearch.com/docs/developer-guide/session-storage/`
- Tools & Toolsets: `https://hermes-agent.nousresearch.com/docs/user-guide/features/tools/`
- ACP: `https://hermes-agent.nousresearch.com/docs/user-guide/features/acp/`
- API Server: `https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server/`
- Security: `https://hermes-agent.nousresearch.com/docs/user-guide/security/`
- Honcho Memory: `https://hermes-agent.nousresearch.com/docs/user-guide/features/honcho/`
## 2. 证据边界
本次评估有一个必须显式写清楚的边界：
- 用户指定优先阅读的 `/tmp/hermes-agent/README.md`、`/tmp/hermes-agent/docs/acp-setup.md`、`/tmp/hermes-agent/docs/honcho-integration-spec.md` 在当前工作机上不存在，未能读取。
- 因此，本文对 Hermes 的判断以 Boss 仓库内已落地的 Hermes MVP 实现，加上 Hermes 官方公开文档为主。
- 这意味着本文对“上游最近几次提交中的未发布细节”不做强判断，只对已经稳定公开、且确实会影响 Boss 长期架构边界的能力做判断。
换句话说，这份文档适合指导 Boss 第二阶段、第三阶段的融合方向，但不应被当成对 Hermes 私有或未发布能力的最终定论。
## 3. 当前状态判断
### 3.1 Boss 侧当前已经做了什么
Boss 已经不是“讨论要不要接 Hermes”的阶段，而是已经完成了一个最小接入：
- 在 `src/lib/execution/` 下已经形成稳定执行底座
- Hermes 当前以 `hermes-runtime` 的形式进入 `ExecutionBackend`
- 接入范围目前只覆盖 `master-agent` 的执行后端选择
- 运行方式是外部命令调用，不 import Hermes Python 代码
- 当前契约本质上仍是 one-shot：
- Boss 组装 prompt
- 调用 Hermes CLI
- 读取 stdout
- 去掉 `session_id`
- 将正文作为回复写回 Boss
这说明 Boss 当前的判断是对的：先把 Hermes 放在执行层适配器位置，而不是把它当成 Boss 产品层替代物。
### 3.2 Hermes 上游真正强在哪里
基于官方文档，Hermes 的强项不是 Boss 已经做得好的产品域，而是以下几层：
- 成熟 agent loop
- Hermes 官方架构文档明确把核心对话循环、工具注册、provider 解析、session 存储、gateway、ACP 都做成了一套统一 runtime。
- 丰富的工具与 toolset 体系
- 官方架构文档写明 Hermes 当前注册了 47 个工具、19 个 toolset，terminal 工具支持 6 种 backend；官方工具文档同时说明这些能力可以按平台启停，并支持 MCP 动态扩展。
- 持久 session 与可检索历史
- 官方 session storage 文档说明 Hermes 用 SQLite + FTS5 持久化会话元数据、消息历史和 lineage。
- 多入口但共享同一运行时
- CLI、gateway、ACP、API server 共用 provider / tool / state 基础设施；其中 API server 还可以把 Hermes 暴露成 OpenAI-compatible HTTP endpoint。
- 安全和审批模型
- 官方 security 文档明确有危险命令审批、容器隔离、MCP 凭据过滤、context file 扫描。
- 长期记忆体系
- 官方 Honcho 文档说明 Hermes 不只有本地 memory 文件，还有 memory provider plugin；Honcho 以插件形式提供更深的用户建模和跨 session 结论归纳。
- 子代理与并行执行
- README 和工具文档都把 delegation、code execution、cron 作为一等能力。
因此，Hermes 对 Boss 的长期价值，主要不是“多一个能跑的 CLI”，而是“提供一套已经在执行层、会话层、工具层、权限层成型的 agent runtime 参考系”。
## 4. 总结论
一句话结论：
- Hermes 对 Boss 主 Agent 的长期参考价值很高
- 但它更适合作为 Boss 的“执行内核候选 + 运行时能力参考系”
- 不适合作为 Boss 的“产品骨架、业务状态源或编排真相”
进一步展开：
### 4.1 Hermes 的长期参考价值是什么
Hermes 对 Boss 的长期价值主要有五层。
#### 第一层：验证 Boss 的执行抽象方向是对的
Boss 已经抽出了 `ExecutionBackend / PromptAssembler / PermissionPolicy / RemoteRuntimeAdapter / OrchestrationBackend`。Hermes 官方架构恰好证明了这条路是对的：
- provider 解析可以独立
- tool registry 可以独立
- session persistence 可以独立
- UI / gateway / ACP 只是不同入口，不应倒逼业务层重塑
这意味着 Boss 继续把“业务层稳定、运行时可替换”做深，是有上游现实参照的。
#### 第二层：给 Boss 主 Agent 提供更强的执行上限
Boss 当前默认主链仍偏“Boss 产品逻辑 + 外部执行通道”。Hermes 提供的是一个更完整的 agent runtime：
- 工具选择能力更强
- 文件 / 终端 / 浏览器 / MCP / delegation 能力更全
- 记忆、session search、skills、approval 都在一个 runtime 内
对 Boss 主 Agent 来说，这意味着未来可以把复杂任务逐步从“Boss 先做大量业务编排，再找后端执行一句 prompt”提升到“Boss 给出业务边界，Hermes 在边界内自主完成更多工作”。
#### 第三层：帮助 Boss 定义“会话级执行”的中间层
Boss 当前 Hermes MVP 还是 one-shot，但 Hermes 官方文档显示它天然具备：
- session 持久化
- lineage
- ACP 会话管理
- API server
- gateway 统一 routing
这对 Boss 很重要，因为 Boss 以后一定会遇到“主 Agent 到底是一次性回答，还是持续工作中的 agent session”这个问题。Hermes 不能直接成为 Boss 的 session 真相，但它是一个很好的 session 能力参考实现。需要额外注意的是，官方 ACP 文档明确说明 ACP 的 `list/load/resume/fork` 只在当前 ACP server 进程存活期间有效，这再次证明它更适合作为执行入口参考，而不是 Boss 的长期会话真相。
#### 第四层：为 Boss 的工具能力治理提供成熟参照
Hermes 的 toolset 分组、审批、安全边界、terminal backend 分层都很成熟。Boss 不一定要照搬工具名和实现，但值得吸收它的治理模型：
- 工具不是平铺权限，而是按风险级别和运行场景分层
- 本地、容器、SSH、云执行是同一工具能力的不同 backend
- 审批与持久 allowlist 是 runtime 级能力，而不是前台零散开关
这正是 Boss 后续把主 Agent 从“能说”升级到“能稳定干活”时最需要的部分。
#### 第五层：提供“可升级外部 runtime”的实际样板
Hermes 不只是功能点集合，它还是一个活跃上游。Boss 如果能把 Hermes 视作“外部 runtime 插件族”之一，而不是一次性集成项目，那么 Boss 未来可以用相同方法吸收：
- Hermes
- Claw
- OMX
- 其他 ACP / API / CLI agent runtime
这会让 Boss 逐步形成自己的执行生态，不再被某一个上游实现绑死。
## 5. 哪些能力值得抽象进 Boss 内核
这里的原则不是“哪个能力厉害就搬哪个”，而是：
- 只抽象 Boss 必须长期拥有主导权的层
- 只抽象对多个 runtime 都成立的层
- 只抽象不会把 Boss 业务真相外包给 Hermes 的层
### 5.1 值得抽象进 Boss 内核的能力
#### 5.1.1 Runtime Capability Profile
Boss 现在已经有 backend selectable / availability，但还不够系统。应该继续抽象成统一的 runtime capability profile，例如：
- 是否支持 one-shot
- 是否支持 session resume
- 是否支持 delegation
- 是否支持 toolsets
- 是否支持 structured approval
- 是否支持 remote terminal backend
- 是否支持 memory provider
- 是否支持 MCP
原因：
- 这是 Boss 做“后端选择、灰度、回退、UI 呈现”的稳定基础
- 这层应该由 Boss 控制，不应把 Hermes 的内部概念直接泄漏到前台
#### 5.1.2 Session Binding Interface
Boss 现在把 Hermes `session_id` 去掉是对的，但长期不能永远停在这里。应该抽象一层通用 session binding interface，而不是 Hermes 专用字段：
- `createSession`
- `resumeSession`
- `closeSession`
- `sessionMetadata`
原因：
- 未来不止 Hermes 会有 session
- Boss 需要控制“哪个业务项目/线程绑定哪个 runtime session”
- 但 session 的生命周期必须由 Boss 业务事件驱动，而不是由 Hermes 自己的 SQLite 状态反向决定
#### 5.1.3 Tool Capability Registry
Boss 现在有 `ToolRegistry` 雏形，但后续应该升级成“工具能力注册表”，重点不是工具实现，而是能力治理：
- 能力类别
- 风险等级
- 是否需要审批
- 哪些 runtime 支持
- 哪些业务场景允许
原因：
- Hermes 的 toolsets 给了很好的上游样板
- Boss 必须把“业务权限”与“runtime 工具能力”中间再插一层自己的治理
#### 5.1.4 Permission Policy 到 Runtime Policy 的映射层
Hermes security 文档说明审批、安全扫描、allowlist 是 runtime 一等能力。Boss 也需要形成自己的 policy mapping 层：
- Boss 业务策略：
- 这个项目允许不允许写文件
- 当前群聊是否允许直接 dispatch
- 当前设备是否允许远程终端
- Runtime 执行策略：
- Hermes toolsets 开哪些
- Hermes terminal backend 用本地还是 SSH
- 需要哪些审批模式
原因：
- 这是 Boss 产品真相和 Hermes runtime 真相之间最关键的隔离层
#### 5.1.5 记忆分层接口
Boss 不应该直接吃 Hermes 的记忆文件或 Honcho 结构，但应该把“Boss 业务记忆”和“外部 runtime 记忆能力”拆分成两层：
- Boss 业务记忆：
- 项目目标
- 项目记忆
- 线程状态文档
- 最近进展事件
- 用户级主 Agent 偏好
- 外部 runtime 记忆：
- Hermes local memory
- session search
- Honcho profile / context
Boss 内核需要的是统一接口，而不是固定供应商实现。
#### 5.1.6 Runtime Health / Fallback / Telemetry
Hermes 当前已经接入 availability 与 fallback，但长期应升级成统一能力：
- 启动健康探测
- capability 探测
- 最近失败原因
- 版本信息
- smoke 测试结果
- 自动回退规则
原因：
- 这决定 Boss 是否能安全地长期吸收外部 runtime 的升级成果
### 5.2 有条件再考虑、但现在不该内核化的能力
#### 5.2.1 Delegation / Subagent Contract
Hermes 的 delegation 很强，但 Boss 现在不该直接把“子代理体系”写死进内核。更合理的做法是：
- 第二阶段只把它视为 runtime capability
- 第三阶段再评估是否需要 Boss 自己定义统一 subagent contract
因为一旦定义过早，就容易被某个 runtime 的行为模型绑死。
#### 5.2.2 Memory Provider Plugin
Hermes 已经有 memory provider plugin 和 Honcho。Boss 长期可以参考“memory provider 可插拔”这个方向，但不建议在第二阶段就把 Boss 记忆系统插件化。当前 Boss 的项目理解、线程状态文档、进展事件还在快速演化，过早插件化会锁死模型。
## 6. 哪些能力不要借，或者只可作为外部能力存在
这里是最重要的边界。Hermes 很强，但 Boss 不能被 Hermes 反向塑形。
### 6.1 不要借来当 Boss 产品骨架的能力
#### 6.1.1 Gateway / 多平台消息入口
Hermes 有 CLI、Telegram、Discord、Slack、WhatsApp、Signal、Email、API server、ACP 等多入口能力，但 Boss 不应该把这些入口当作自己的前台路线。
原因：
- Boss 已经有 Web / Android / local-agent / 群聊 / 审批 / 设备导入等产品主链
- 如果把 Hermes gateway 当成 Boss 主入口，产品模型会被即时通讯平台语义反向塑形
判断：
- 可以作为外部执行入口参考
- 不应该成为 Boss 主业务入口
#### 6.1.2 Hermes 的 SQLite Session Store
Hermes 官方 session storage 很成熟，但 Boss 不能把它当成业务真相库。
原因：
- Boss 的真相不是“agent 对话历史”这么简单
- Boss 还有项目、线程、设备、审批、群聊、导入、记忆、账本、投影视图
- 一旦让 Hermes state.db 成为真实会话源，Boss 会失去对业务生命周期的主导权
判断：
- 可以参考 schema 和 lineage 思路
- 不能作为 Boss 核心账本或主状态库
#### 6.1.3 Honcho 用户建模作为 Boss 主记忆
Honcho 的优势是跨 session、跨设备、跨 peer 的用户建模，但 Boss 不能直接拿它替代自己的主 Agent 记忆体系。
原因：
- Boss 关心的是业务记忆，不只是人格/偏好/沟通风格
- Honcho 适合“用户画像 + 深层偏好”
- Boss 更需要“项目事实、线程事实、设备事实、审批事实”
判断：
- 可以作为外部补充记忆源
- 不能成为 Boss 记忆主真相
#### 6.1.4 ACP Session Manager 语义
Hermes ACP 文档明确说 ACP 会话只在 ACP server 进程存活期间有效，`list/load/resume/fork` 也限定在该 server 生命周期内。
这对 Boss 来说只能作为编辑器集成参考，不能直接拿来做主 Agent 长期会话模型。
原因：
- Boss 会话生命周期是业务驱动，不是 editor server 驱动
- ACP 进程级 session manager 太短命
#### 6.1.5 Cron 与平台投递系统
Hermes 自带 cron 调度和任意平台投递，但 Boss 当前不应该把这部分纳入主 Agent 内核。
原因：
- Boss 当前最核心的问题是执行层、业务状态、审批和项目理解，不是调度器丰富度
- 过早接入 cron 会把“任务调度”和“业务执行”耦合
判断：
- 可作为未来运维或后台任务参考
- 不应进入第二阶段主线
### 6.2 不要照搬的设计风格
#### 6.2.1 不要把 Hermes 的工具名和 slash command 暴露成 Boss UI 概念
Boss 前台不应该出现：
- `toolsets`
- `session_search`
- `honcho_profile`
- `delegate_task`
- `allow once / allow always`
这类原生 Hermes 概念可以存在于适配层和运维界面，但不应直接成为 Boss 面向用户的产品语言。
#### 6.2.2 不要让 Hermes 的 context files 决定 Boss 提示词层级
Hermes 有自己的 context files / skills / memory 注入方式。Boss 不能因此削弱现有的：
- 管理员全局主提示词
- 用户私有主提示词
- 当前对话附加提示词
- 项目记忆
- 线程状态文档
Boss 的提示词优先级必须继续由 Boss 掌控。
## 7. 第二阶段建议路线
第二阶段的关键词不是“接更多功能”，而是“把 Hermes 从最小可用后端升级成可长期运营的受控后端”。
### 7.1 第二阶段目标
目标应收敛为三件事：
1. 把 Hermes 从 demo 级 one-shot backend 升级为受控运行时后端
2. 让 Boss 对 Hermes 的能力感知、配置、回退、观测更完整
3. 仍然不让 Hermes 进入 Boss 编排层与业务真相层
### 7.2 第二阶段建议任务
#### 7.2.1 补齐 Runtime Capability Profile
为 Hermes 增加稳定 capability 描述，而不是只暴露 `selectable / reasonLabel`：
- `supportsOneShot`
- `supportsSessionResume`
- `supportsDelegation`
- `supportsToolsets`
- `supportsMemoryProvider`
- `supportsMcp`
- `supportsApprovalBridge`
- `supportsRemoteTerminal`
这样 Boss 后续前台、策略、实验、灰度都能统一处理。
#### 7.2.2 引入最小 Session Metadata 捕获，但不直接业务化
建议第二阶段开始捕获 Hermes `session_id`，但只作为内部诊断元数据，不立刻绑定业务主链：
- 记录最近一次执行返回的 `session_id`
- 记录 Hermes command/model/toolsets/skills
- 记录运行耗时、退出码、fallback 原因
不做：
- 不做 Boss 项目线程到 Hermes session 的强绑定
- 不做 resume 主链
这样能为第三阶段做准备，但不会过早扩大范围。
#### 7.2.3 做一层 Boss -> Hermes policy mapping
把 Boss 的业务约束映射成 Hermes 运行时约束：
- 项目级只读 / 可写
- 是否允许 terminal
- 是否允许 web / browser
- 是否允许 delegation
- 是否允许外部 MCP
第二阶段可以先从静态配置开始，不必一开始就做动态全量映射。
#### 7.2.4 建立 Hermes 专属 smoke / health / version 检查
当前 availability 只检查命令、cwd、脚本存在。第二阶段应该加入：
- `hermes --version` 或等价 version check
- 最小真实 prompt smoke
- toolset 启动 smoke
- provider 可用性检查
- 可选的 API server / ACP 旁路探测
这会把“能选”升级成“可运营”。
#### 7.2.5 限定场景开展 A/B 对照实验
第二阶段只建议在主 Agent 的少数高价值场景做 Hermes 对照：
- 长提示词理解
- 需要文件/终端/浏览器联动的问题
- 需要多步工具执行的问题
- 需要更强自主探索的问题
不要一上来把所有主 Agent 请求默认切到 Hermes。
### 7.3 第二阶段明确不做
- 不接 `dispatch_execution`
- 不接群聊编排
- 不接设备导入审核链
- 不接 Honcho 作为 Boss 默认记忆
- 不接 ACP 成为 Boss 主前台
- 不把 Hermes API server 暴露成 Boss 对外 API 主链
## 8. 第三阶段建议路线
第三阶段的关键词是“选择性深化”，不是“全面融合”。
### 8.1 第三阶段前提
只有在第二阶段满足以下条件后，才建议进入第三阶段：
- Hermes 后端运行稳定
- fallback 和 kill switch 可靠
- Boss 已形成 capability / policy / telemetry 的统一抽象
- 已明确哪些任务在 Hermes 上明显优于当前默认后端
### 8.2 第三阶段可以做什么
#### 8.2.1 引入 Session-Aware Backend Contract
如果第二阶段观察证明 Hermes 在持续任务里明显更有优势，第三阶段可以升级为 session-aware backend：
- Boss 为项目或线程保存 runtime session binding
- 支持显式 resume / compact / close
- 主 Agent 在少数项目上变成“持续运行的工作线程”
但必须坚持：
- Boss 决定何时创建、恢复、关闭
- Hermes 不直接拥有业务生命周期
#### 8.2.2 选择性开放 Delegation
第三阶段可以考虑让 Hermes delegation 进入 Boss，但只作为受限能力：
- 只在主 Agent 内部使用
- 只对特定项目开放
- 必须经过 Boss policy 层约束
- 子代理产物回写必须标准化
换句话说，Boss 可以借 Hermes 的“多步执行能力”，但不能把 Boss 的编排主权交给 Hermes。
#### 8.2.3 引入可插拔 Memory Provider Adapter
第三阶段可以评估把 Honcho 或其他 memory provider 作为外部补充记忆源接入：
- 用于用户偏好、工作习惯、长期画像
- 不用于项目事实和审批真相
Boss 应保持“双层记忆”：
- Boss 事实记忆
- 外部推理型记忆
#### 8.2.4 评估 ACP / API Server 作为受控旁路入口
如果未来 Boss 需要编辑器直连、桌面 IDE 集成或本地私有 agent service，第三阶段可以评估：
- ACP 作为开发态集成通道
- Hermes API server 作为受控本地后端
但必须保持：
- Boss 是业务真相层
- ACP / API server 只是执行入口
### 8.3 第三阶段仍然不要做什么
- 不让 Hermes 替代 Boss 群聊编排
- 不让 Hermes 替代 Boss 审批流
- 不让 Hermes 替代 Boss 设备导入逻辑
- 不让 Hermes state.db 替代 Boss 状态账本
- 不让 Hermes gateway 替代 Boss Web / Android 产品层
## 9. 风险与边界
### 9.1 最大风险：上下文主权混乱
Boss 有自己的 prompt、memory、project understanding、thread status。Hermes 也有：
- system prompt
- skills
- MEMORY / USER
- Honcho
- context files
- session search
如果不加边界，很容易出现：
- Boss 明明要求 A
- Hermes 自己的 memory / skill / context file 又暗示 B
- 最终输出谁在主导不清楚
所以必须坚持：
- Boss 决定业务上下文主权
- Hermes 只在 Boss 明确授权的范围内做 agentic 执行
### 9.2 第二大风险：权限模型不一致
Boss 的审批流是业务审批，Hermes 的 approval 是 runtime 审批。这两者不是一回事。
如果直接混用，会出现：
- Boss 以为“已批准执行”
- 但 Hermes 还在等危险命令批准
或者：
- Hermes 因本地 allowlist 放过了命令
- Boss 却并未允许该业务动作
因此必须分层：
- Boss 负责业务许可
- Hermes 负责运行时危险动作许可
- 中间靠 policy mapping 对齐
### 9.3 第三大风险：状态与观测割裂
如果 Hermes 执行内部发生：
- 自动记忆写入
- session 压缩
- subagent delegation
- tool 失败重试
但 Boss 只能看到最终一段 stdout，那么 Boss 无法做审计、归因和用户解释。
因此长期必须补：
- 最小运行元数据
- 最小工具活动摘要
- 明确失败分类
但这不等于把 Hermes 全量内部日志搬进 Boss。
### 9.4 第四大风险：运维依赖扩张
Hermes 引入的是一整套 Python runtime、provider 凭据、tool dependencies、MCP、optional extras。对 Boss 来说，这会带来：
- 安装复杂度增加
- 服务器镜像和本地设备环境差异
- 版本升级不一致
- provider 凭据与 Boss 账号配置割裂
所以 Hermes 长期必须维持“可选、可探测、可回退”，不能成为 Boss 单点依赖。
### 9.5 第五大风险：成本和上下文膨胀
Hermes 的强项也是风险点：
- 更强工具调用
- 更多记忆注入
- session search
- Honcho
- delegation
这些能力如果没有边界，会直接带来更高 token 成本和更长响应尾延迟。Boss 当前主 Agent 的部分场景并不需要这么重。
## 10. 升级策略
### 10.1 采用“能力 checkpoint”而不是“整仓跟随”
不要用“Boss 跟随 Hermes 最新版”这种策略，而要用能力 checkpoint：
1. 选定一个 Hermes 版本
2. 验证一组 Boss 关心的能力：
- CLI one-shot
- model/provider 解析
- toolsets
- approvals
- session metadata
- optional MCP
3. 通过后才升级 Boss 适配层
这能避免 Boss 被 Hermes 高频演进拖着走。
### 10.2 维持严格的单向边界
推荐长期坚持以下边界：
- Boss -> Hermes：
- `ExecutionRequest`
- policy 映射后的 runtime config
- 明确的 prompt 与 memory 注入
- Hermes -> Boss：
- 标准化结果
- 最小 session metadata
- 最小 telemetry
不要让 Boss 直接依赖：
- Hermes 内部 SQLite schema
- Hermes 内部 Python 类
- Hermes 内部工具注册过程
### 10.3 先扩可观察性，再扩能力
每一次升级顺序都应是：
1. 先补 health / telemetry / fallback
2. 再开放新能力
例如：
- 想接 session resume，先能看见 session 元数据
- 想接 delegation，先能看见子任务摘要和失败分类
- 想接 Honcho，先定义 Boss 侧的记忆归属边界
### 10.4 始终保留 kill switch
Hermes 长期必须是可关闭的：
- 配置级关闭
- 项目级关闭
- 运行时自动回退
- 前台明确提示回退原因
这是 Boss 能放心吸收外部 runtime 的前提。
### 10.5 用受控试点项目推进，而不是全局切换
升级节奏建议：
- 只在 `master-agent` 的少量项目启用
- 先对复杂任务启用
- 按项目或账号白名单试点
- 保留默认后端作对照
Boss 不应该出现“大版本直接切 Hermes 为默认”的动作。
## 11. 最终判断
### 11.1 长期定位
Hermes 在 Boss 中的长期定位应是：
- 第一身份：执行 runtime 候选
- 第二身份：运行时抽象设计参考
- 第三身份：未来 session-aware agent backend 候选
而不是：
- Boss 产品层替代者
- Boss 编排层替代者
- Boss 状态账本替代者
### 11.2 值得吸收的核心东西
Boss 最值得从 Hermes 吸收的，不是某个具体命令，而是这四个长期结构：
- runtime capability 分层
- tool / approval / backend 的统一治理
- session-aware agent runtime 的中间层设计
- 业务真相与外部 runtime 分离的架构纪律
### 11.3 不该动摇的 Boss 主权
Boss 必须继续自己掌握：
- 会话与项目模型
- 群聊与审批
- 设备导入
- 业务记忆与线程状态文档
- 用户可见产品语言
- 账本与聚合投影视图
Hermes 可以把 Boss 主 Agent 变强，但不应该把 Boss 变成 Hermes 的 UI 外壳。
## 12. 建议的下一步
建议按优先级做三件事。
### 12.1 先做一份第二阶段实施设计
主题应收敛为：
- `Hermes Runtime Capability / Policy / Telemetry 第二阶段设计`
只覆盖：
- capability profile
- session metadata 捕获
- policy mapping
- smoke / health / version 探测
- telemetry 与 fallback
不扩大到 dispatch、群聊、Honcho。
### 12.2 补齐真实上游证据
等 `/tmp/hermes-agent` 可用后，重新核对：
- `README.md`
- `docs/acp-setup.md`
- `docs/honcho-integration-spec.md`
重点看是否存在与官方公开文档不一致、且会影响 Boss 边界判断的实现细节。
### 12.3 建一个 Hermes 受控试点矩阵
至少分三类任务做对照：
- 纯问答型主 Agent 任务
- 多步工具执行任务
- 需要较强上下文整合的复杂任务
用实际结果决定 Hermes 在 Boss 中应该停留在“高级可选后端”，还是继续推进到“session-aware 主 Agent runtime”。