Sumeru 🏔️：Agent House

作者：星月 | 2026-06-16
芥子纳须弥 —— 一粒芥子里装一座须弥山

一句话介绍

Sumeru 是一个 agent house——一个 HTTP 服务，为同一运行环境内的多个 Agent 提供统一的「收发室」。不管底层是 Hermes、Claude Code 还是别的 Agent，对外都是同一套 HTTP 接口；所有交互通过 OCAS 全量记录、可搜索、可回放、可导出。

为什么需要 Sumeru？

家族的每个小队节点上都跑着不同的 Agent——这台装了 Hermes，那台装了 Claude Code，配置各不相同。当你想让别的程序（比如 uwf）去调用「某个节点上的某个 agent」时，会撞到三个麻烦：

每种 Agent 的接口都不一样 —— 怎么启动、怎么 resume 会话、怎么捞对话历史，Hermes 和 Claude Code 完全不同。调用方得为每种 agent 写一套对接逻辑。
会话状态散落各处 —— Hermes 有自己的 session ID，Claude Code 有自己的，调用方要记一堆 native ID，还得知道每种 agent 怎么续接。
交互没有留痕 —— Agent 做了什么、产出了什么，过后想复盘、想搜索、想导出给别人看，没有统一的记录。

Sumeru 把这三件事收拢到一个 HTTP 服务后面：统一接口、统一会话管理、全量记录。调用方只跟 Sumeru 的 HTTP endpoint 打交道，永远不接触底层 agent 的 native 细节。

核心概念

Sumeru 的命名延续了家族「设备是房子，住户是 agent」的隐喻：

Instance（房子）

一个 Sumeru 进程 = 一个运行环境的 agent 管理层，对外暴露一个 endpoint URL。不管底层是本机、Docker 容器还是远程服务器，对外都是同一个 HTTP 接口。

sumeru@neko  →  https://oc-neko.shazhou.work/sumeru
sumeru@kuma  →  https://oc-kuma.shazhou.work/sumeru
sumeru@raku  →  https://oc-raku.shazhou.work/sumeru

Gateway（住户）

一个 Instance 内可以有多个 gateway，每个 gateway 对应一个 agent。Gateway 是配置声明的，每个声明自己的 capabilities（支持 resume？支持 streaming？），告诉调用方它能做什么。

yaml

# sumeru.yaml — 实例配置
name: sumeru@neko

gateways:
  hermes:
    adapter: hermes
    capabilities:
      resume: true
      streaming: true

  claude-code:
    adapter: claude-code
    config:                         # adapter 专属配置，原样转发
      sendTimeoutMs: 1800000        # 30 min — 杀掉卡死的 send
      maxTurns: 120
    capabilities:
      resume: true
      streaming: true

Session（会话）

归属于某个 gateway，是一次 agent 对话。Session ID 由 Sumeru 统一管理（ses_ + ULID），内部维护到 agent native session ID 的映射——调用方永远不接触 native ID。Session 支持 resume：多次 message 在同一 conversation history 内延续。

Adapter（agent 适配器）

每类 agent 一个 adapter 包，实现统一的契约：createSession / send / close / getTurns。不同 agent 的差异（怎么启动、怎么 resume、怎么捞 turns）被 adapter 抹平，Sumeru 核心层不关心。

Adapter	包名	后端
hermes	`@sumeru/adapter-hermes`	Hermes Agent
claude-code	`@sumeru/adapter-claude-code`	Claude Code CLI

HTTP API

所有响应使用 OCAS envelope 格式 { type, value }。

GET    /                                      → 实例信息
GET    /gateways                              → 列出所有 gateway
GET    /gateways/:name                        → 单个 gateway 详情
POST   /gateways/:name/sessions               → 创建 session（201）
GET    /gateways/:name/sessions/:id           → 查看 session
DELETE /gateways/:name/sessions/:id           → 关闭 session（204）
POST   /gateways/:name/sessions/:id/messages  → 发消息（SSE 流式返回）
GET    /sessions?q=keyword&gateway=hermes     → FTS5 全文搜索
POST   /gateways/:name/sessions/:id/export    → 导出为 tar.gz

发消息走 Server-Sent Events，请求体 { "content": "你的消息" }，事件流包含：

event: turn —— 一个完整的 Turn 对象 { index, role, content, timestamp, hash }
event: heartbeat —— 保活
event: done —— 完成，附带 { turnCount, tokens, durationMs }
event: error —— 错误

支持 Last-Event-ID header 断点续传。

Scene：Agent 行为观察实验室

除了做收发室，Sumeru 还有一层定位——观察 Agent 行为的受控实验室。

一个 scene 是一个可复现的实验场景：预设好工作目录、可用工具、预装的 skill / memory（或者故意留空），再给一个任务。把它丢给某个 agent 跑，全程交互被 OCAS 记下来，事后可以精确分析「这个 agent 在没有任何先验知识时，是怎么一步步摸索的」。

yaml

# scenes/first-uwf-usage/scene.yaml
name: first-uwf-usage
description: 新用户首次使用 uwf。没有预装任何 skill 或 memory，从零开始摸索工具。

tools: [uwf, git, node]
knowledge:
  skills: []      # 故意留空——观察冷启动行为
  memory: []

task: |
  你是一个开发者 agent，刚接到一个新的开发环境。
  请使用 uwf 工具完成：
  1. 了解 uwf 是什么、怎么用
  2. 完成 uwf 的初始化设置
  3. 创建一个 code-review workflow
  4. 成功执行一次 workflow

这让我们可以做一些过去做不了的事：对比不同 agent 在同一场景下的表现、验证一份新写的 skill 到底有没有帮助、复盘某次失败到底卡在哪一步。Agent 的行为第一次变得可观测、可对比、可回归。

三个项目怎么咬合

Sumeru 不是孤立的，它和家族另外两个项目构成一条链：

United Workforce  ──（uwf-sumeru adapter，HTTP/SSE）──▶  Sumeru
   工作流编排                                              agent house
        │                                                      │
        └──────────── 都把数据记到 ─────────────────────────────┘
                              ▼
                            OCAS
                       不可变数据层

OCAS 是底座——Sumeru 的每一个 turn、每一次 session 都作为不可变节点存进 OCAS，所以才能搜索、回放、导出。
United Workforce 是上层——通过 uwf-sumeru adapter，uwf 可以把某一步的执行「外包」给网络上某个 Sumeru 实例里的某个 agent，而不必在本机安装那个 agent。

换句话说：OCAS 管「数据怎么存」，Sumeru 管「agent 怎么接入和记录」，uwf 管「多个 agent 怎么按流程协作」。

架构

Monorepo，packages 如下：

packages/
├── core/              # @sumeru/core — 核心类型定义（Adapter、Turn、Session）
├── server/            # @sumeru/server — HTTP 服务（Instance/Gateway/Session 管理）
├── adapter-hermes/    # @sumeru/adapter-hermes — Hermes Agent 适配器
├── adapter-claude-code/ # @sumeru/adapter-claude-code — Claude Code 适配器
└── cli/               # @sumeru/cli — sumeru 命令行（sumeru start）

快速上手

bash

# 1. 创建实例配置
cat > sumeru.yaml << 'EOF'
name: sumeru@local
gateways:
  hermes:
    adapter: hermes
    capabilities:
      resume: true
      streaming: true
EOF

# 2. 启动服务
sumeru start -c sumeru.yaml -p 7900

# 3. 验证
curl http://127.0.0.1:7900/
# → {"type":"@sumeru/instance","value":{"name":"sumeru@local",...}}

设计哲学

统一收发室 —— 不同 agent 的接口差异由 adapter 抹平，对外永远是同一套 HTTP API。调用方不关心底层是谁。
会话归 Sumeru 管 —— 调用方只用 Sumeru 的 ses_ ID，native session ID 被完全封装。续接、关闭都走统一接口。
全量记录 —— 所有交互通过 OCAS 持久化，不可变、可搜索、可导出。Agent 做过的事永远有据可查。
可观测的实验场 —— scene 让 agent 行为变成可复现、可对比的实验。这是把 agent 从「黑盒执行者」变成「可研究对象」的基础设施。

Sumeru 🏔️：Agent House ​

一句话介绍 ​

为什么需要 Sumeru？ ​

核心概念 ​

Instance（房子） ​

Gateway（住户） ​

Session（会话） ​

Adapter（agent 适配器） ​

HTTP API ​

Scene：Agent 行为观察实验室 ​

三个项目怎么咬合 ​

架构 ​

快速上手 ​

设计哲学 ​

相关链接 ​