不用点开也能读:Hermes 网关新增 session.transcript,分页读取历史会话


你在给自己的编辑器写一个小侧栏:左边列出最近十次对话,点一下在右边显示内容。数据从 Hermes 网关拿。听起来很简单,可你很快撞上一堵墙:网关只有一个“读取”入口,叫 session.resume,而它的名字已经说明了问题——那是“恢复/打开”,不是“看”。调用它,网关会为这条会话建立起 agent、订阅事件、把它变成一条正在运行的会话。你只想显示三行标题,却启动了一整套机器,还得负责收尾。

11 月 6 日合并的这批改动把这个缺口补上了:网关多了一个真正的只读方法 session.transcript,以及 session.list 的 picker: true 选项。它属于“读取”权限,不建 agent、不订阅任何人,读完就走。这篇把三件事讲清楚:它能读到什么、游标怎么用、以及哪些坑会让你以为它坏了。

以前的困境:读一行文字,也得“打开”整个会话

这不是设计失误,而是历史包袱。session.resume 的语义是“接着聊”:它要保证会话在网关里是活的,所以它会占用会话、重建运行时、把客户端挂到事件流上。对一个“只读列表”的界面来说,代价和风险都不对等——你打开一个侧栏,可能就把用户正在用的会话抢走了。

于是很多第三方客户端干脆绕过网关,直接去读 state.db。能跑,但那是把内部实现当接口:表结构一变、行格式一换,客户端就碎。这次改动的目标很明确:把客户端从数据库文件旁边请回来,站到一个有版本的接口前面。

一个方法,三件事:列表、正文、子代理

客户端想做的事 以前 现在
列出会话,带目录、最后活跃时间、最后一句回复 session.list 只给 id、标题、首句、条数 session.list 加 picker: true,行里多出 preview、last_reply、cwd、git_branch、workspace、last_active_at、pinned
按目录过滤,只看这个仓库里的对话 没有过滤 workspace 参数,按 hermes -c 的同一套规则匹配
分页读正文,不附加 只有 session.resume(会附加) session.transcript
轮询新消息 不附加就没有 传回上一页的 next_cursor
看到压缩发生在哪 压缩交接行被从客户端结果里抹掉 每次交接都是一行 row_kind: "compaction",位置不动
读被委派的子代理记录 做不到 subagent_id 参数
知道某条子代理记录属于哪个会话 subagent.list 行里没说 行里带 child_session_id

workspace 的匹配规则值得单独说一句:它按“这条会话的第一行属于哪个目录”判断——记录里有 git 仓库根就用仓库根,没有就比 cwd。所以给 packages/webapp/ 开过会话、但仓库根在别处的情况,用仓库根去过滤才找得到。

怎么用:一次请求,一个游标

请求和回复都很朴素。默认从最早的行开始读,一页一百行:

{"method": "session.transcript", "params": {"session_id": "ses_8f21", "limit": 50}}
{
  "session_id": "ses_8f21",
  "rows": [
    {"row_kind": "message", "role": "user", "text": "the build fails on CI only"},
    {"row_kind": "message", "role": "assistant", "text": "Which stage?"},
    {"row_kind": "compaction", "role": "system", "text": "Summary of 34 earlier messages...", "compacted_messages": 34}
  ],
  "next_cursor": "c2VzXzhmMjE6MToxMjM0",
  "reset": false
}

返回的 rows 是展示行,不是每条消息的原始数据库行:一条逻辑消息出现一次,工具轮次在边缘最多带上 64 条结果,压缩交接按它当时的位置插进列表。所以客户端拿到的顺序就是用户在界面上看到的顺序。

next_cursor 不透明,别解析它,也别跨会话复用——它绑定到具体会话、具体子代理、具体排序方向。

游标不只是分页,它还是轮询

这是整个设计里最省事的一点,也是最容易用错的一点。

order: "oldest"(默认值)时,next_cursor 永远不会是 null。读完最后一页(返回空 rows)之后不要丢掉游标,继续拿它去请求,你就只会拿到“游标之后新写入的行”。换句话说,一个看着像分页的东西,同时也是一个增量订阅——不需要长连接,不需要事件回调,定时轮询就行。

order: "latest" 是另一种用法:从最新的行往前翻,翻到头时 next_cursor 才是 null。适合做“打开就在底部”的阅读器。

reset: true 不是报错,是“把缓存清掉重来”

如果你只想要新消息,最容易踩的坑就是忽略 reset。

游标记的不只是“读到哪里”,还记了它覆盖的那些行的状态。只要中途发生的是纯追加(新消息、新的工具结果),下一页就接着游标往下走,reset: false。但只要发生别的任何事——原地压缩、轮转出一个新段、回退、改写、删除——回复会直接带 reset: true,并且从第一页重新给你。这时候正确的动作只有一个:丢掉本地缓存,用这一页替换。

对阅读器来说这是好事:你不会出现“上半段是旧版本、下半段是新版本”的错位。对写代码的人来说这是必须处理的正常分支,不是错误分支。没带游标的回复也一律是 reset: true。

子代理的记录,也能这样读

带 subagent_id 就切换成读一个被委派的子代理,回复里多三个字段:subagent_id、available、running、child_session_id。

这里有几个刻意设下的小门:

  • 会话必须在本网关上是活的,否则 not_found。
  • 正在跑的子代理必须在这条会话的活体名册里(嵌套子代理也算)。
  • 已经结束的子代理,靠生成时打在行上的 _subagent_id 找,而且只有它的父链能通过委派或压缩续接追回这条会话才算数——分支出去的会话不会把自己的子代理借给你。
  • 别人的、不存在的子代理,回你 available: false、rows: []、next_cursor: null、reset: true。不报错,也不泄露。

另外 subagent.list 的行现在带 child_session_id,于是“这条子代理记录属于哪个会话”不用再猜。

边界:一页最多 500 行、2 MiB,超大的行会被截断

几个明确的限额,写客户端时按它来设计:

  • limit 范围 1–500,默认 100,压缩交接行也算在里面。
  • 一页最多 2 MiB 的 JSON,切在工具组之间,所以不会把一次工具调用和它的结果拆开。
  • 单行超过这个体积时,只保留角色、类型、时间、id 和文本开头,并标 truncated: true。
  • 图片默认只显示成 [image],除非显式传 inline_images: true。

权限方面它和 session.resume 的读检查一致(profile、所有者或 operator),并且跑在网关的并发读通道上——所以你正在跑一轮对话时,另一个客户端的阅读请求不会排在它后面。

现在能用吗

还不能从正式版装上就用。这批提交在 main 上(11 月 6–7 日合并,PR #150102,其中并入了 #140477 的子代理记录读法),不在 v0.23.0 的标签里(那个标签是 11 月 5 日的)。用运行时的能力声明来判断最稳:支持它的网关会在 runtime.describe.capabilities 里报 session-transcript-v1,列表选项报 session-list-picker-v1。看到就放心用,看不到就退回老办法。

更新(2026-11-10):这批改动已随 v0.23.1 发布(2026-11-09),hermes update 升级即可用。上文「不在 v0.23.0 里」仍然成立,v0.23.1 把缺口补上了。

如果你现在就想在网关外面看会话,站内这两篇是同一条线上的内容:把会话导出成文件 解决“带走一份”,会话的边界与续接 解释为什么一条对话会分成好几段——理解了分段,你才看得懂 session.transcript 为什么要把压缩交接单独列成一行。至于 session.resume 本身那些“打开就接管”的行为,Chat C 的那篇 讲得比我这里细。

一句话总结

session.transcript 把“读”和“打开”分开了一件很久以来被绑在一起的事:客户端现在可以只看不走、只读不接管,用一个游标既做分页又做轮询,并且在会话被压缩、被回退时收到明确的 reset 而不是一堆猜不透的差异。如果你的客户端还在直接摸 state.db,这就是搬回接口的理由。