Integrate master agent runtime orchestration updates

2026-04-16 04:41:46 +08:00
parent e0c0ea1814
commit 39be49630f
81 changed files with 9283 additions and 448 deletions
--- a/docs/architecture/ai_handoff_index_cn.md
+++ b/docs/architecture/ai_handoff_index_cn.md
@@ -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. 当前有效实现边界

--- a/docs/architecture/api_and_service_inventory_cn.md
+++ b/docs/architecture/api_and_service_inventory_cn.md
@@ -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`
--- a/docs/architecture/current_runtime_and_deploy_status_cn.md
+++ b/docs/architecture/current_runtime_and_deploy_status_cn.md
@@ -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 或匹配登录会话
--- a/docs/architecture/hermes_runtime_接入与运维指南_cn.md
+++ b/docs/architecture/hermes_runtime_接入与运维指南_cn.md
@@ -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
+
--- a/docs/architecture/hermes_对_boss_主agent长期融合评估_cn.md
+++ b/docs/architecture/hermes_对_boss_主agent长期融合评估_cn.md
@@ -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”。
--- a/docs/superpowers/plans/2026-04-14-android-chat-status-row-plan.md
+++ b/docs/superpowers/plans/2026-04-14-android-chat-status-row-plan.md
@@ -0,0 +1,112 @@
+# Android Chat Status Row Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Render `conversationTasks` and `executionWarnings` as a compact inline status row beneath each message on the Android chat page, dedupe grouped warnings per message, and keep realtime patches scoped to the affected message.
+
+**Architecture:** Add a reusable status-row builder in `BossUi` and wire `ProjectDetailActivity.buildMessageView` to compute grouped tasks/warnings, append the status row under each bubble, and compare a fingerprint during realtime patches so only impacted views re-render.
+
+**Tech Stack:** Android/Java UI (`ProjectDetailActivity.java`, `BossUi.java`) and Node-powered source-verification tests (`tests/android-chat-incremental-realtime-append.test.ts`, `tests/android-chat-local-realtime-patch.test.ts`).
+
+---
+
+### Task 1: Fail on missing inline status row in realtime append test
+
+**Files:**
+- Modify: `tests/android-chat-incremental-realtime-append.test.ts`
+- Test: `npm test tests/android-chat-incremental-realtime-append.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+```ts
+assert.match(
+  source,
+  /wrapper\.addView\(BossUi\.buildMessageStatusRow\(/,
+  "expected every message bubble to append BossUi.buildMessageStatusRow",
+);
+assert.match(
+  source,
+  /List<JSONObject> messageWarnings = collectMessageWarnings\(projectMessagesPayload, messageId\);/,
+  "expected the new status row builder to source grouped warnings per message",
+);
+assert.match(
+  source,
+  /String statusFingerprint = buildStatusFingerprint\(messageId, projectMessagesPayload\);/,
+  "expected realtime patches to compute a fingerprint before replacing a message view",
+);
+```
+- [ ] **Step 2: Run it to prove failure**
+Run: `npm test tests/android-chat-incremental-realtime-append.test.ts`
+Expected: FAIL because `BossUi.buildMessageStatusRow` and the new helper functions do not yet exist.
+- [ ] **Step 3: Re-run after implementation to confirm success**
+Run: `npm test tests/android-chat-incremental-realtime-append.test.ts`
+Expected: PASS.
+
+### Task 2: Fail on missing helper signatures in realtime patch test
+
+**Files:**
+- Modify: `tests/android-chat-local-realtime-patch.test.ts`
+- Test: `npm test tests/android-chat-local-realtime-patch.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+```ts
+assert.match(
+  source,
+  /LinearLayout statusRow = buildMessageStatusRow\(this, message, conversationTask, messageWarnings\);/,
+  "expected buildMessageStatusRow to be invoked when each message is rendered",
+);
+assert.match(
+  source,
+  /List<JSONObject> buildMessageWarnings\(JSONObject payload, String messageId\);/,
+  "expected a helper that returns grouped warnings keyed by message id",
+);
+assert.match(
+  source,
+  /if \(!TextUtils\.equals\(currentFingerprint, nextFingerprint\)\) \{ replaceMessageViewById\(/,
+  "expected realtime patch to compare status fingerprint before rerendering",
+);
+```
+- [ ] **Step 2: Run it to prove failure**
+Run: `npm test tests/android-chat-local-realtime-patch.test.ts`
+Expected: FAIL because helper signatures and fingerprint comparisons are missing.
+- [ ] **Step 3: Re-run after implementation to confirm success**
+Run: `npm test tests/android-chat-local-realtime-patch.test.ts`
+Expected: PASS.
+
+### Task 3: Add BossUi helper for compact status row
+
+**Files:**
+- Modify: `android/app/src/main/java/com/hyzq/boss/BossUi.java`
+- Test: `npm test tests/android-chat-incremental-realtime-append.test.ts`
+- Test: `npm test tests/android-chat-local-realtime-patch.test.ts`
+
+- [ ] **Step 1: Implement `buildMessageStatusRow`**
+Add a method that accepts `(Context context, String statusLabel, String detailText, boolean outgoing)` and returns a horizontal `LinearLayout` with spaced pills and body text, using rounded background colors and `TextView` ellipsizing. Keep it compact (max height) and re-usable for both warnings and conversation task summaries.
+- [ ] **Step 2: Run targeted tests**
+Run: `npm test tests/android-chat-incremental-realtime-append.test.ts tests/android-chat-local-realtime-patch.test.ts`
+Expected: PASS after the helper is referenced by `ProjectDetailActivity`.
+
+### Task 4: Wire ProjectDetailActivity to the new status row
+
+**Files:**
+- Modify: `android/app/src/main/java/com/hyzq/boss/ProjectDetailActivity.java`
+- Test: `npm test tests/android-chat-incremental-realtime-append.test.ts`
+- Test: `npm test tests/android-chat-local-realtime-patch.test.ts`
+
+- [ ] **Step 1: Add helper methods for grouped warnings/tasks and fingerprinting**
+Implement `List<JSONObject> collectMessageWarnings(JSONObject payload, String messageId)`, `@Nullable JSONObject findConversationTask(String messageId)`, and `private String buildStatusFingerprint(String messageId, JSONObject payload)` that concatenates task/w warning summaries so the realtime patch can detect status changes without re-rendering unchanged rows.
+- [ ] **Step 2: Update `buildMessageView` to append a status row**
+Inside `buildMessageView`, compute `List<JSONObject> messageWarnings` and `JSONObject messageTask`, then call `BossUi.buildMessageStatusRow(this, description, detail, outgoing)` and add it directly beneath the bubble instead of the previous warning card logic. Use the grouped data to deduplicate identical warnings (e.g., map by `warningId` or `title+summary`).
+- [ ] **Step 3: Update realtime patch logic**
+In `tryPatchRealtimeExecutionWarnings`, compute `String currentFingerprint = buildStatusFingerprint(messageId, currentRenderedProjectPayload)` and `String nextFingerprint = buildStatusFingerprint(messageId, projectMessagesPayload)`; only call `replaceMessageViewById` when they differ. Ensure `currentRenderedProjectPayload` is updated once per patch and that `renderNearBottom`/`setRefreshing` behavior stays the same.
+- [ ] **Step 4: Run regression tests**
+Run: `npm test tests/android-chat-incremental-realtime-append.test.ts tests/android-chat-local-realtime-patch.test.ts`
+Expected: PASS.
+
+### Task 5: Final verification
+
+**Files:**
+- Test: all above tests
+
+- [ ] **Step 1: Run the two test files together**
+Run: `npm test tests/android-chat-incremental-realtime-append.test.ts tests/android-chat-local-realtime-patch.test.ts`
+Expected: PASS with no additional failures.
--- a/docs/superpowers/plans/2026-04-14-hermes-backend-mvp.md
+++ b/docs/superpowers/plans/2026-04-14-hermes-backend-mvp.md
@@ -0,0 +1,318 @@
+# Hermes Backend MVP Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 为 Boss 新增一个默认关闭、可显式启用的 `hermes-runtime`，让 `master-agent` 可通过 Hermes CLI 返回回复。
+
+**Architecture:** 复用现有 `claw-runtime` 的接入形态，在 `src/lib/execution/backends/` 下新增 Hermes 配置、runner 与 backend adapter，再把 selector、主 Agent 路由与前台控制接上。第一批只开放给 `master-agent`，不碰群聊编排和 Android 独立设置页。
+
+**Tech Stack:** Next.js App Router, TypeScript, Node child_process, Node test runner
+
+---
+
+### Task 1: 补 Hermes 后端底座测试
+
+**Files:**
+- Create: `tests/hermes-backend-config.test.ts`
+- Create: `tests/hermes-runner.test.ts`
+- Create: `tests/hermes-backend.test.ts`
+- Modify: `tests/execution-backend-selector.test.ts`
+
+- [ ] **Step 1: 写配置与 selector 的失败测试**
+
+```ts
+test("Hermes backend 默认关闭且 selector 不会主动选中", () => {
+  const backends = listExecutionBackendChoices({
+    primary: { provider: "master_codex_node", status: "ready" },
+    backups: [{ provider: "openai_api", status: "ready" }],
+    requestKind: "master_agent_reply",
+  });
+
+  assert.deepEqual(backends.map((item) => item.backendId), [
+    "master-codex-node",
+    "openai-api",
+  ]);
+});
+```
+
+- [ ] **Step 2: 写 runner 参数拼装失败测试**
+
+```ts
+test("Hermes runner 会拼 chat -q -Q --source tool 与可选模型参数", async () => {
+  const result = await runHermesCommandForTesting({
+    config: {
+      enabled: true,
+      command: process.execPath,
+      args: [scriptPath],
+      timeoutMs: 30_000,
+      defaultModel: "gpt-5.4",
+      sourceTag: "tool",
+    },
+    payload: {
+      executionPrompt: "请输出链路正常",
+      model: "gpt-5.5",
+    },
+  });
+
+  assert.equal(result.status, "completed");
+  assert.equal(result.output, "Hermes smoke completed");
+});
+```
+
+- [ ] **Step 3: 跑测试确认当前失败**
+
+Run:
+
+```bash
+npx tsx --test tests/hermes-backend-config.test.ts tests/hermes-runner.test.ts tests/hermes-backend.test.ts tests/execution-backend-selector.test.ts
+```
+
+Expected:
+
+- FAIL，提示 Hermes 相关模块不存在或 selector 还不认识 `hermes-runtime`
+
+---
+
+### Task 2: 实现 Hermes config / runner / backend
+
+**Files:**
+- Create: `src/lib/execution/backends/hermes-config.ts`
+- Create: `src/lib/execution/backends/hermes-runner.ts`
+- Create: `src/lib/execution/backends/hermes-backend.ts`
+- Create: `scripts/hermes-runtime-smoke.mjs`
+
+- [ ] **Step 1: 实现 Hermes 配置读取与可用性检查**
+
+实现点：
+
+- `BOSS_HERMES_ENABLED`
+- `BOSS_HERMES_COMMAND`
+- `BOSS_HERMES_ARGS`
+- `BOSS_HERMES_WORKDIR`
+- `BOSS_HERMES_TIMEOUT_MS`
+- `BOSS_HERMES_DEFAULT_MODEL`
+- `BOSS_HERMES_TOOLSETS`
+- `BOSS_HERMES_SKILLS`
+
+- [ ] **Step 2: 实现 runner**
+
+固定执行形态：
+
+```text
+<command> <prefix args> chat -q <executionPrompt> -Q --source tool
+```
+
+可选追加：
+
+- `-m <model>`
+- `-t <toolsets>`
+- `-s <skills>`
+
+解析 quiet 模式结尾的：
+
+```text
+session_id: xxx
+```
+
+但只把正文回给 Boss。
+
+- [ ] **Step 3: 实现 backend adapter**
+
+能力保持与 Claw 一致：
+
+- backendId: `hermes-runtime`
+- 仅支持 `master_agent_reply` / `thread_reply`
+- `describe()` 返回稳定描述
+
+- [ ] **Step 4: 跑测试确认转绿**
+
+Run:
+
+```bash
+npx tsx --test tests/hermes-backend-config.test.ts tests/hermes-runner.test.ts tests/hermes-backend.test.ts tests/execution-backend-selector.test.ts
+```
+
+Expected:
+
+- PASS
+
+---
+
+### Task 3: 把 Hermes 接入 selector 与主 Agent 控制面
+
+**Files:**
+- Modify: `src/lib/execution/backend-selector.ts`
+- Modify: `src/lib/boss-data.ts`
+- Modify: `src/app/api/v1/projects/[projectId]/agent-controls/route.ts`
+- Modify: `src/app/api/v1/projects/[projectId]/prompt-profile/route.ts`
+- Modify: `src/app/me/master-agent/page.tsx`
+- Modify: `src/components/master-agent-prompt-memory-client.tsx`
+- Modify: `tests/master-agent-chat-controls.test.ts`
+
+- [ ] **Step 1: 扩展 `backendOverride` 合法值**
+
+把：
+
+```ts
+backendOverride?: "claw-runtime";
+```
+
+扩为：
+
+```ts
+backendOverride?: "claw-runtime" | "hermes-runtime";
+```
+
+并同步更新 `parseBackendOverride()`。
+
+- [ ] **Step 2: 扩展路由校验**
+
+保存 `agent-controls` / `prompt-profile` 时：
+
+- 允许 `hermes-runtime`
+- 若 Hermes 当前不可选，直接返回 400 和原因
+
+- [ ] **Step 3: 扩展 Web 控制面**
+
+主 Agent 提示词页的执行后端下拉新增：
+
+- `Hermes Runtime`
+
+并显示 Hermes 的可用性提示。
+
+- [ ] **Step 4: 跑控制面测试**
+
+Run:
+
+```bash
+npx tsx --test tests/master-agent-chat-controls.test.ts
+```
+
+Expected:
+
+- PASS，且 `backendOverride: "hermes-runtime"` 可读写
+
+---
+
+### Task 4: 接上 `boss-master-agent` 执行链
+
+**Files:**
+- Modify: `src/lib/boss-master-agent.ts`
+- Modify: `tests/master-agent-message-queue.test.ts`
+
+- [ ] **Step 1: 写 Hermes 主 Agent 执行失败测试**
+
+新增与 Claw 对齐的测试：
+
+- 显式选择 `hermes-runtime`
+- Hermes 返回结果后能写回主 Agent 会话
+- 不可用时会回退或返回明确失败
+
+- [ ] **Step 2: 实现 `replyViaHermesBackend` 与 `enqueueHermesMasterAgentReply`**
+
+保持与 Claw 同一层级：
+
+- 同步模式直接执行并回写
+- enqueue 模式先排任务，再异步执行 Hermes
+- Hermes 失败时按当前主链回退到 API / Master Node
+
+- [ ] **Step 3: 在 selector 结果里接入 Hermes 分支**
+
+在：
+
+- `replyToMasterAgentUserMessage()`
+
+里新增：
+
+- `selectedBackend.backendId === HERMES_BACKEND_ID`
+
+对应处理。
+
+- [ ] **Step 4: 跑消息链路测试**
+
+Run:
+
+```bash
+npx tsx --test tests/master-agent-message-queue.test.ts
+```
+
+Expected:
+
+- PASS，`master-agent` 显式选 Hermes 时会通过 Hermes 返回
+
+---
+
+### Task 5: 全量验证与文档收口
+
+**Files:**
+- Modify: `docs/architecture/current_runtime_and_deploy_status_cn.md`
+- Modify: `docs/architecture/api_and_service_inventory_cn.md`
+
+- [ ] **Step 1: 更新运行时文档**
+
+补充：
+
+- `HermesBackendAdapter` 已最小接入
+- 默认关闭
+- 当前只对 `master-agent` 开放
+
+- [ ] **Step 2: 运行相关测试**
+
+Run:
+
+```bash
+npx tsx --test tests/hermes-backend-config.test.ts tests/hermes-runner.test.ts tests/hermes-backend.test.ts tests/execution-backend-selector.test.ts tests/master-agent-chat-controls.test.ts tests/master-agent-message-queue.test.ts
+```
+
+Expected:
+
+- PASS
+
+- [ ] **Step 3: 运行基础验证**
+
+Run:
+
+```bash
+npm run build
+npm run lint
+```
+
+Expected:
+
+- `build` PASS
+- `lint` 若失败，只能是仓库已知外来大文件噪音，不能是本批新增文件
+
+- [ ] **Step 4: 提交**
+
+```bash
+git add docs/superpowers/specs/2026-04-14-hermes-backend-mvp-design.md \
+  docs/superpowers/plans/2026-04-14-hermes-backend-mvp.md \
+  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 \
+  src/lib/boss-data.ts \
+  src/lib/boss-master-agent.ts \
+  src/app/api/v1/projects/[projectId]/agent-controls/route.ts \
+  src/app/api/v1/projects/[projectId]/prompt-profile/route.ts \
+  src/app/me/master-agent/page.tsx \
+  src/components/master-agent-prompt-memory-client.tsx \
+  scripts/hermes-runtime-smoke.mjs \
+  tests/hermes-backend-config.test.ts \
+  tests/hermes-runner.test.ts \
+  tests/hermes-backend.test.ts \
+  tests/execution-backend-selector.test.ts \
+  tests/master-agent-chat-controls.test.ts \
+  tests/master-agent-message-queue.test.ts \
+  docs/architecture/current_runtime_and_deploy_status_cn.md \
+  docs/architecture/api_and_service_inventory_cn.md
+git commit -m "feat: add hermes runtime backend for master agent"
+```
+
+---
+
+## Self-Review
+
+- 这份计划只覆盖 `master-agent`，没有把群聊编排、Android 独立配置页和 Hermes session 持久化一起卷进来
+- 所有代码改动都围绕现有 `claw-runtime` 接入形态做最小差异实现
+- 第一批验收点是“能选、能跑、能回退”，不是“把 Hermes 全部接满”
--- a/docs/superpowers/specs/2026-04-14-android-chat-status-row-design.md
+++ b/docs/superpowers/specs/2026-04-14-android-chat-status-row-design.md
@@ -0,0 +1,36 @@
+# Android chat status row spec
+
+## Goal
+Surface `conversationTasks` and `executionWarnings` as a single compact status row under each Android chat bubble so owners can see backend work without stacking multiple cards, while keeping realtime patches minimal.
+
+## Motivation
+- The current Android chat preview renders separate warning cards below every message and keeps an expensive list of `executionWarnings` separately, which duplicates the tap area and height of the chat list.
+- The Web page already summarizes tasks and warnings inline: we should match that on Android while keeping real-time patches restrictive, only rejiggering views for the affected message.
+- Requirements from the user: group warnings per message, deduplicate statuses, update only affected message on realtime patches, no web/backend changes.
+
+## Architecture
+1. Extend `BossUi.buildMessageBubble` (or its wrapper) to accept a reusable compact status row view that can show a grouped warning count and task status.
+2. When building a message view in `ProjectDetailActivity.buildMessageView`, gather all conversation task summaries and execution warnings that match the message ID. Deduplicate them by warning ID or Task ID and render them inside the status row.
+3. Create helper methods to compute a `StatusRowView` (a `LinearLayout`) that displays:
+   - If there is an active `conversationTask`, show a row with the backend status label and session/task info.
+   - If there are warnings, show badge summaries with title and summary text but limit to one line (maybe ellipsized) and collapse duplicates by grouping warnings that share the same title+summary pair.
+4. `buildMessageView` will add the status row view directly under the existing bubble but before any other attachments.
+5. The realtime warning patch logic already replaces a specific `messageId` view; ensure it reconstructs the same minimal status row and only rerenders when the status content changes. To do that, we may need to compute a canonical string for the combined task/warnings and store/compare to avoid redundant replacements.
+
+## Implementation details
+- Introduce new helper methods in `ProjectDetailActivity`:
+  - `private LinearLayout buildStatusRow(JSONObject message, List<ConversationTaskSummary> tasks, JSONArray warnings)`
+  - `private boolean hasStatusChangesForMessage(...)` to allow realtime patch to compare old vs new statuses without rerender unless necessary.
+- `BossUi` may need a new method such as `public static LinearLayout buildMessageStatusRow(Context context, String label, String detail, int tintColor)` to standardize the UI.
+- Update `ProjectDetailActivity.appendContent(buildMessageView(message))` loops to clear prior warning cards and add the new status row once.
+- Keep logic around `findExecutionWarningForMessage` but adjust to return grouped data instead of each warning separately.
+- Update `currentRenderedProjectPayload` handling to consider the grouped warning/task text, ensuring `hasSameExecutionWarningForMessage` returns `true` when summaries and counts match.
+
+## Testing approach (TDD)
+1. Add a new or expand existing Android tests that read `ProjectDetailActivity.java` source to assert the presence of status row construction, grouped warnings, and realtime patch logic (e.g., `tests/android-chat-incremental-realtime-append.test.ts` and `tests/android-chat-local-realtime-patch.test.ts`).
+2. Write a failing test first that expects a new helper like `buildMessageStatusRow` or `getStatusTextForMessage` to exist and to be used under each message.
+3. Update tests referencing warning cards to expect the new inline status row and ensure patch logic still references the helper to rerender targeted messages only when necessary.
+4. Manually run `npm test android-chat-incremental-realtime-append.test.ts` and `npm test android-chat-local-realtime-patch.test.ts` after implementing.
+
+## Validation
+- After receiving user approval on this spec, proceed with the implementation plan using TDD. Use test file names to focus runs, and keep the Android changes confined to `ProjectDetailActivity.java`, `BossUi.java`, and the corresponding tests.
--- a/docs/superpowers/specs/2026-04-14-hermes-backend-mvp-design.md
+++ b/docs/superpowers/specs/2026-04-14-hermes-backend-mvp-design.md
@@ -0,0 +1,271 @@
+# Boss `HermesBackendAdapter` 最小接入设计
+
+## 1. 背景
+
+Boss 现在已经有一层稳定的执行底座：
+
+- `ExecutionBackend`
+- `ExecutionBackendSelector`
+- `PromptAssembler`
+- `PermissionPolicy`
+- `RemoteRuntimeAdapter`
+
+并且已经接过两个外部项目：
+
+- `ClawBackendAdapter` 负责单次执行候选
+- `OmxTeamBackendAdapter` 负责编排候选
+
+`hermes-agent` 的最新上游形态更像“重型 agent runner”，而不是 Boss 的产品层替代物。它的价值主要集中在：
+
+- 成熟的单次 agent loop
+- CLI / Gateway / ACP 多入口
+- 丰富的 toolset 体系
+- 内建 skills / memory / session / search / delegation
+
+结论不是“把 Hermes 整体搬进 Boss”，而是把它当成新的**执行后端候选**接进 Boss 现有底座。
+
+---
+
+## 2. 第一批目标
+
+第一批只做一件事：
+
+> 在不改变 Boss 当前生产主链默认行为的前提下，为 `master-agent` 新增一个默认关闭、可显式启用的 `hermes-runtime`。
+
+用户能在 Boss 现有的主 Agent 对话控制里选择 `Hermes Runtime`，然后让当前 `master-agent` 的回复通过 Hermes CLI 完成。
+
+这批做完后，Boss 获得的是：
+
+- 一个新的可选执行后端
+- 一个可继续升级的 Hermes 适配点
+- 对现有 `claw-runtime` / API / Master Codex Node 主链零破坏
+
+---
+
+## 3. 明确不做
+
+这一批明确不做：
+
+- 不把 Hermes 的 gateway、Telegram、Discord、Slack、WhatsApp、Signal 接进 Boss
+- 不把 Hermes 的 Honcho memory 直接并入 Boss 的 `threadStatusDocuments / threadProgressEvents`
+- 不让 Boss 前台直接理解 Hermes 的 sessions、slash commands、toolsets 内部结构
+- 不接 Hermes 的多平台消息收发
+- 不接 Hermes 的 cron / ACP / editor integration
+- 不改 Boss 群聊编排链路
+- 不把 Hermes 当成新的 OrchestrationBackend
+
+这一批的定位非常明确：**只加一个执行后端，不加一个新产品子系统。**
+
+---
+
+## 4. 为什么 Hermes 值得接
+
+### 4.1 对主 Agent 的意义
+
+对 Boss 的主 Agent 来说，Hermes 的参考价值主要有三层：
+
+1. **成熟的一次性 agent loop**
+   - `hermes chat -q ... -Q` 已经提供了可脚本化的单次非交互执行入口。
+   - 这正好适合 Boss 当前 `ExecutionBackend` 的“单次请求 -> 单次结果”契约。
+
+2. **比 Claw 更完整的 agent runtime**
+   - Hermes 不只是命令封装，而是完整的 agent runner、tool registry、toolsets、skills、memory、delegation 体系。
+   - 这意味着它对复杂任务的“自己调工具完成”的能力更强，适合作为 Boss 主 Agent 的增强执行候选。
+
+3. **未来跨端能力的扩展面更大**
+   - Hermes 天然有 CLI / Gateway / ACP 三个入口。
+   - 这对 Boss 未来做“同一 agent 内核，挂不同入口”很有参考价值，但第一批先不展开。
+
+### 4.2 对 Boss 整体业务流程的意义
+
+Hermes 对 Boss 的真正价值不在 UI，而在**执行层的替换与对照实验**：
+
+- 同一条 Boss 产品链
+- 同一组项目、线程、审批、导入、群聊数据
+- 不同执行后端并行存在
+
+这样 Boss 可以把“产品层稳定”与“执行层可替换”真正做实。
+
+---
+
+## 5. 第一批接入方案
+
+### 5.1 接入位置
+
+Hermes 第一批接在：
+
+- `src/lib/execution/backends/`
+- `ExecutionBackendSelector`
+- `master-agent` 对话控制
+
+不接：
+
+- `OrchestrationBackend`
+- `local-agent` dispatch_execution
+- Android 独立配置页
+
+### 5.2 运行方式
+
+Boss 不直接 import Hermes Python 代码，也不把 Hermes vendoring 进仓库。
+
+Boss 通过外部命令调用 Hermes：
+
+```text
+<configured command> <configured prefix args> chat -q "<executionPrompt>" -Q --source tool
+```
+
+按需追加：
+
+- `-m <model>`
+- `-t <toolsets>`
+- `-s <skills>`
+
+这样做的原因：
+
+- 上游升级成本最低
+- Boss 与 Hermes 保持进程边界
+- 可以像 `claw-runtime` 一样通过命令 / workdir / args 做显式配置
+- 出问题时可直接回退，不污染主链
+
+### 5.3 输入输出契约
+
+Boss -> Hermes：
+
+- `executionPrompt`
+- `modelOverride`
+- `reasoningEffortOverride`（第一批只透传给 Boss 自身记录，不强行映射到 Hermes CLI 参数）
+- 可选 `toolsets`
+- 可选 `skills`
+
+Hermes -> Boss：
+
+- `stdout` 主体内容作为最终回复
+- quiet mode 末尾的 `session_id: ...` 只做解析，不写回会话正文
+
+如果 Hermes 非零退出、超时、输出为空或结构不可解析，统一转成：
+
+- `ExecutionImmediateFailedResult`
+
+---
+
+## 6. 配置设计
+
+新增环境变量：
+
+- `BOSS_HERMES_ENABLED`
+- `BOSS_HERMES_COMMAND`
+- `BOSS_HERMES_ARGS`
+- `BOSS_HERMES_WORKDIR`
+- `BOSS_HERMES_TIMEOUT_MS`
+- `BOSS_HERMES_DEFAULT_MODEL`
+- `BOSS_HERMES_TOOLSETS`
+- `BOSS_HERMES_SKILLS`
+
+设计约束：
+
+- 默认关闭
+- `enabled=true` 时若未显式设置 `BOSS_HERMES_COMMAND`，默认尝试 `hermes`
+- 可执行入口不存在、工作目录不存在、前置脚本不存在时，前台不允许选择
+
+---
+
+## 7. Boss 内部改动点
+
+### 7.1 新增文件
+
+- `src/lib/execution/backends/hermes-config.ts`
+- `src/lib/execution/backends/hermes-runner.ts`
+- `src/lib/execution/backends/hermes-backend.ts`
+- `scripts/hermes-runtime-smoke.mjs`
+
+### 7.2 修改文件
+
+- `src/lib/execution/backend-selector.ts`
+- `src/lib/boss-data.ts`
+- `src/lib/boss-master-agent.ts`
+- `src/app/api/v1/projects/[projectId]/agent-controls/route.ts`
+- `src/app/api/v1/projects/[projectId]/prompt-profile/route.ts`
+- `src/app/me/master-agent/page.tsx`
+- `src/components/master-agent-prompt-memory-client.tsx`
+
+### 7.3 测试
+
+新增或扩展：
+
+- `tests/hermes-backend-config.test.ts`
+- `tests/hermes-runner.test.ts`
+- `tests/hermes-backend.test.ts`
+- `tests/execution-backend-selector.test.ts`
+- `tests/master-agent-chat-controls.test.ts`
+- `tests/master-agent-message-queue.test.ts`
+
+---
+
+## 8. 关键取舍
+
+### 8.1 第一批不做 session 级复用
+
+Hermes quiet mode 会回 `session_id`，但 Boss 第一批不把它纳入正式状态模型。
+
+原因：
+
+- Boss 现有 `ExecutionImmediateResult` 没有 session 归档职责
+- 当前目标是先把“后端切换可用”做通
+- 先引入 session 绑定会把 `thread/session` 关联、恢复、清理都一起带进来，范围会失控
+
+第一批策略：
+
+- 解析但不持久化 `session_id`
+- 先跑通 stateless one-shot backend
+
+### 8.2 第一批不把 Boss PermissionPolicy 动态映射成 Hermes toolsets
+
+Hermes 的 toolsets 很强，但 Boss 现在没有现成的“工具级权限 -> Hermes CLI 参数”双向映射层。
+
+第一批策略：
+
+- 只支持静态环境变量指定 `toolsets` / `skills`
+- Boss 自己仍保留顶层产品审批与后端选择权
+
+这样虽然不够极致，但风险最小。
+
+### 8.3 第一批只开放给 `master-agent`
+
+这是刻意收口，不是能力缺陷。
+
+原因：
+
+- 当前 Boss 的后端 override UI 只在主 Agent 对话控制里成熟
+- `dispatch_execution` 牵涉群聊编排与设备执行链，接 Hermes 会把范围扩大到第二批
+- 先让主 Agent 对话用起来，收益最大、回归面最小
+
+---
+
+## 9. 验收标准
+
+满足以下条件才算第一批完成：
+
+1. 未启用 `BOSS_HERMES_*` 时，Boss 行为与当前完全一致
+2. 启用且配置正确后，`master-agent` 对话控制中可选择 `Hermes Runtime`
+3. 选择 `Hermes Runtime` 后，主 Agent 单次回复能通过 Hermes CLI 返回结果
+4. Hermes 不可用时，保存接口会拒绝选择，并返回明确原因
+5. 历史保存了 `hermes-runtime` 但当前不可用时，运行时会自动回退到默认后端，并给出人类可读说明
+6. `npm run build`
+7. `npm run lint`（当前需排除仓库外来大文件噪音后）
+8. 相关测试通过
+
+---
+
+## 10. 第二批预留方向
+
+第一批完成后，再考虑第二批：
+
+- Hermes session 级复用与 Boss 项目线程关联
+- Boss 权限策略到 Hermes toolsets 的映射
+- `thread_reply` 正式挂接
+- Android 主 Agent 设置页显示 Hermes 可用性
+- `dispatch_execution` 是否引入 Hermes 作为编排前执行候选
+
+第一批的成功标准不是“把 Hermes 接满”，而是：
+
+> 让 Boss 在现有产品层完全不变的情况下，稳定多出一个可选择、可回退、可继续升级的重型 agent 执行后端。
--- a/docs/superpowers/specs/2026-04-16-master-agent-fast-path-design.md
+++ b/docs/superpowers/specs/2026-04-16-master-agent-fast-path-design.md
@@ -0,0 +1,101 @@
+# 主 Agent Fast Path 设计
+
+更新时间：`2026-04-16`
+
+## 1. 背景
+
+主 Agent 当前同时承担两类请求：
+
+- 需要深度理解、规划、协调的慢路径问题
+- 只需要读取本地状态、快速执行配置变更的快路径问题
+
+在原实现里，只有少量模型切换命令会本地直答。大量高频问题，例如“你现在是什么大模型”“当前后端是什么”，仍会落入主推理链，导致：
+
+- 回复延迟明显偏高
+- 消耗不必要的 token
+- 用户需要记忆更机械的命令句式
+
+## 2. 设计目标
+
+- 把“状态查询 / 配置操作 / 枚举类问题”从主推理链中剥离出来
+- 对高频确定性问题提供本地直答，不进入异步队列
+- 保持自然语言容错，不要求用户输入完全标准化命令
+- 为后续继续扩展快路径意图提供统一入口
+
+## 3. 方案
+
+### 3.1 Fast Path Router
+
+在 `src/lib/boss-master-agent.ts` 中新增主 Agent 快路径路由层：
+
+- 统一先构造 `MasterAgentFastIntentContext`
+- 上下文内聚合：
+  - 当前登录用户作用域下的 `agentControls`
+  - 可见模型列表
+  - 可用模型列表
+  - 当前聊天意图的实际模型策略
+  - 深度任务意图的实际模型策略
+  - 当前 runtime 主控来源
+- `replyToMasterAgentUserMessage()` 在进入主链前先尝试 `tryHandleMasterAgentFastIntent()`
+
+### 3.2 第一批接入意图
+
+- 模型列表查询
+  - 例：“有哪些模型可以用”
+- 模型切换
+  - 例：“把快模型切到 gpt5.4mini”
+- 当前模型状态查询
+  - 例：“你现在是什么大模型”
+  - 例：“当前主模型是什么”
+  - 例：“快模型是什么”
+  - 例：“强模型是什么”
+- 当前后端状态查询
+  - 例：“当前后端是什么”
+
+### 3.3 自然语言归一化
+
+模型名解析新增轻量归一化：
+
+- 忽略 `- / _ / 空格 / .`
+- 兼容 `gpt5.4`、`gpt 5.4`、`gpt_5_4`
+- 仍然会回落到系统当前可选模型列表做映射
+
+## 4. 展示规则
+
+主 Agent 快路径回复的发送者名称改成：
+
+- `主Agent·<当前模型名>`
+
+Android 主 Agent 会话页顶部标题同步显示：
+
+- `主Agent·<当前模型名>`
+
+如果当前拿不到显式模型，则退回：
+
+- `主Agent`
+
+## 5. 当前收益
+
+- “查状态 / 查配置 / 改模型”这一类问题能直接秒回
+- 主 Agent 不再因为低价值查询进入慢路径
+- 用户不用死记标准句式
+- 后续扩展更多快路径意图时，只需要继续往 router 中追加 handler
+
+## 6. 后续扩展建议
+
+下一批适合继续接入 Fast Path 的问题：
+
+- 当前绑定设备 / 在线设备查询
+- 当前会话 / 当前线程运行状态查询
+- GUI / CLI 默认执行模式查询
+- 当前接管开关状态查询
+- 最近活跃项目 / 最近活跃线程查询
+
+## 7. 验证基线
+
+本次落地至少要求以下验证通过：
+
+- `npx tsx --test tests/master-agent-message-queue.test.ts tests/master-agent-chat-controls.test.ts`
+- `npm run build`
+- `./gradlew :app:compileDebugJavaWithJavac :app:assembleDebug`
+- 真机安装并验证主 Agent 名称与模型查询行为