krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
39be49630f7068daa1c92db5e5c9b00399f61da4
boss/docs/superpowers/plans/2026-04-14-hermes-backend-mvp.md

8.0 KiB
Raw Blame History

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 的失败测试

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 参数拼装失败测试
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:

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

固定执行形态：

<command> <prefix args> chat -q <executionPrompt> -Q --source tool

可选追加：

  • -m <model>
  • -t <toolsets>
  • -s <skills>

解析 quiet 模式结尾的：

session_id: xxx

但只把正文回给 Boss。

  • Step 3: 实现 backend adapter

能力保持与 Claw 一致：

  • backendId: hermes-runtime

  • 仅支持 master_agent_reply / thread_reply

  • describe() 返回稳定描述

  • Step 4: 跑测试确认转绿

Run:

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 合法值

把：

backendOverride?: "claw-runtime";

扩为：

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:

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:

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:

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:

npm run build
npm run lint

Expected:

  • build PASS

  • lint 若失败，只能是仓库已知外来大文件噪音，不能是本批新增文件

  • Step 4: 提交

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 全部接满”