读 Octop 源码(6):流式投影层,和「在纯文本 IM 里做单选题」
第 1 篇画链路的时候,画到这一行就收住了:
async for ev in project_stream(agent_manager, agent_id, request, ...):
yield ev
当时我说「project_stream 是这里的分界线:往里是 harness 的地盘,往外是 Octop 的地盘」。这篇把它拆开。
顺带把 HITL(human-in-the-loop)也读了——那 1,393 行在解决一个比想象中更土的问题。
版本锚点:本文基于
octopv1.0.2(commitdd9dce4)、octop-harness1.0.4、langgraph1.2.16。process/stream_project.py269 行,gateway/hitl/1,393 行。
环境准备
这篇的东西都在运行时才能看到,所以要抓真实帧。
第一,起服务抓 WS 帧。 最直接的办法是打开浏览器开发者工具看 Network → WS,但更可控的是用 CLI 聊天,同时看日志:
cd ~/WorkBuddy/Claw/octop
./octop.sh cli chats repl # 交互式聊天
tail -f .home/.octop/logs/octop.log | grep -E "chunk|tool"
第二,看前端认识哪些帧类型。 直接搜 dashboard 侧的类型定义:
grep -rn "tool_call_chunk\|tool_result" dashboard/src --include="*.ts*" | head -10
帧类型大致是这几类(不是完整清单,是我在代码里见到的):
| type | 含义 |
|---|---|
token | 文本增量 |
tool_call_chunk | 模型决定调用某个工具(含参数增量) |
tool_result | 工具返回 |
attachment | 产物(图片、文件) |
thread | 会话绑定/切换 |
turn.ended | 本轮结束 |
error | 出错 |
第三,看 HITL 那套的文件划分。 hitl/ 五个文件,职责很清楚:
coordinator.py 646 行 协调器,决定什么时候暂停、怎么恢复
store.py 322 行 pending 记录的存储(进程内 + TTL)
format.py 315 行 把问题渲染成 IM 能看懂的文本,再把回复解析回来
stream_compat.py 86 行 harness 侧兼容垫片
__init__.py 24 行
format.py 315 行这个体量,在一堆"序列化/反序列化"里显得特别——它解决的是个产品问题,不是技术问题。
流程
一、投影层做的不是转发,是翻译
stream_project.py 269 行,主函数 project_stream 在 217 行。它做的事用一句话说:把 LangGraph 的原始事件流,翻译成前端认识的帧序列。
原始事件长什么样?大概是:
{'event': 'on_chat_model_stream', 'data': {'chunk': AIMessageChunk(content='你好')}}
{'event': 'on_tool_start', 'name': 'read_file', 'data': {'input': {...}}}
{'event': 'on_tool_end', 'name': 'read_file', 'data': {'output': '...'}}
而前端要的是扁平的、带类型标记的 {"type": "token", "content": "你好"}。
这层翻译不是简单的字段改名,它要处理三件麻烦事:
- 工具调用的参数是流式的:模型不是一个完整的 JSON 吐出来,而是
{"pa、th": "、a.txt"}一片片出来。投影层要缓冲拼装(tool_name_buf、tool_started)。 - 同一个工具调用可能有多段:
tool_call_chunk有 id,要按 id 归并。 - 历史会被重放(下一节展开)。
所以它有一个专门的状态对象:
@dataclass
class _ToolProjectionState:
current_node: str | None = None
tool_name_buf: dict[str, str] = field(default_factory=dict)
tool_started: set[str] = field(default_factory=set)
active_tool_idx: str | None = None
saw_tool_call: bool = False
emitted_media_ids: set[str] = field(default_factory=set)
emitted_tool_error_ids: set[str] = field(default_factory=set)
二、投影层最难的其实是幂等
_ToolProjectionState 后面三个字段,每个都对应一句注释,而每句注释都是一个线上事故:
# True once we've seen at least one tool_call_chunk in this stream.
# Media events are only emitted when a tool was actually called this turn;
# historical tool results (replayed via PatchToolCallsMiddleware / Overwrite)
# must not trigger re-sends.
saw_tool_call: bool = False
# Track tool_call_ids whose media we've already emitted to prevent
# re-emission when PatchToolCallsMiddleware emits Overwrite(full_history).
emitted_media_ids: set[str] = field(default_factory=set)
emitted_tool_error_ids: set[str] = field(default_factory=set)
翻译一下这个坑是怎么来的:
LangGraph 的中间件(这里是 PatchToolCallsMiddleware)在某些情况下会发一个 Overwrite(full_history) 事件——把完整的历史消息重新推一遍。这在图的状态管理上是对的,但对流式转发是灾难:
- 前面 20 轮里生成过的 8 张图片,会作为"历史工具结果"再流一遍
- 如果投影层老实地转发,前端就会看到这 8 张图重新加载一遍
- 用户视角:聊天记录突然自己抖了一下,滚动位置跳了,图片闪烁
所以投影层必须自己维护"我已经发过什么":
saw_tool_call:本轮真的调用过工具吗?没调用就不许发媒体事件(因为那必然是历史)emitted_media_ids:按tool_call_id记账,发过的不再发emitted_tool_error_ids:错误同理
这三个字段合起来是在做"投影层的幂等"。
这件事有个更一般的教训:上游的"语义正确"不等于下游的"体验正确"。 LangGraph 重放历史,从状态机角度完全正确——它只是要求你把同一份数据重新渲染。但用户已经看过的东西,不该再看一遍。这一层的转换责任,只能由投影层自己承担,因为只有它知道"已经发出去了"。
顺带说,这也是为什么投影层要独立成一个 269 行的文件,而不是塞进 GlobalProcessor(已经上千行了)。它有自己的一套状态机,混进业务逻辑里就没人看得懂了。
三、工具名要按语言和用户翻译
投影层里有个小函数,做的是很产品的事:
def enrich_tool_stream_chunk(chunk, locale, *, agent_manager=None, agent_id=None, user_id=None):
"""Add ``display_name`` to harness tool stream chunks for dashboard clients."""
if chunk.get("type") not in ("tool_call_chunk", "tool_result"):
return chunk
name = chunk.get("name")
...
out["display_name"] = agent_manager.resolve_tool_display_name_for_chat(
agent_id=agent_id, user_id=user_id, tool_name=name, locale=str(locale),
)
模型调用的工具叫 read_file,但界面上要显示「读取文件」(中文)/「Read file」(英文)。
为什么不直接在前端做映射表?因为工具名是动态的:
- 内置工具有 20 多个
- 插件工具可以自定义名字(27 个内置插件,每个都能加工具)
- MCP 工具的名字是外部服务器起的
- 同一个工具在不同语言下叫法不同
所以映射必须在服务端做,而且要知道"哪个 Agent、哪个用户、什么语言"——因为插件工具的显示名可能来自插件自己的元数据。
这是"i18n 不是替换字符串"的一个具体例子。 一个工具帧从产生到显示,要经过:工具名 → 插件元数据 → 用户语言偏好 → 前端渲染。中间任何一环硬编码,都会在某个插件上翻车。
四、HITL:在纯文本 IM 里做单选题
这部分是我读这个项目笑得最多的地方。
HITL 的意思是"人机协同":Agent 干到一半需要人确认(“我要删这 30 个文件,确定吗?"),暂停等人回答。
hitl/format.py 的第一行常量就说明了一切:
ASK_USER_TOOL_NAME = "ask_user_question"
模型调用 ask_user_question 工具,带上问题和选项。问题来了:在企业微信、飞书、钉钉里,你没地方弹一个带复选框的对话框。
唯一的界面就是纯文本消息。
所以 format.py 干的事是:把结构化的问题渲染成一段带 a/b/c 的文本,发给用户;用户回复"1"或者"b"或者"b,d”,再把这段文本解析回选择。
选项用的是字母:
_OPTION_KEYS = string.ascii_lowercase
解析用的是个不算简单的正则:
_SELECTION_RE = re.compile(r"^[0-9a-z]+(?:[,,、/\s]+[0-9a-z]+)*$")
注意这个正则里的分隔符:,(英文逗号)、,(中文逗号)、、(顿号)、/、空白。五个。 因为用户在微信里回复的时候,用什么标点完全看输入法当时的心情。
这就是为什么 format.py 要 315 行——它不是在写序列化,它在模拟一个 UI:
- 渲染:问题、选项、编号规则、允许"以上都不是"吗、允许自由输入吗
- 解析:数字还是字母?多选怎么分隔?用户打了句废话怎么办?
- 容错:认不出来的时候要重问一遍,还得说得让人不烦
“在没有 UI 的渠道上做交互设计”,这是 IM Agent 平台最不性感但最必要的活。 光这一块 315 行,而且每一行都是被真实用户回复训练出来的。
五、pending 记录存在进程内存里,30 分钟过期
store.py 322 行,第一句就交代了性质:
class HitlPendingStore:
"""Session-scoped pending HITL records (process-local, TTL-gc)."""
ttl_seconds: float = _DEFAULT_TTL_SECONDS # 30 * 60
进程内、按 session 作用域、TTL 回收。 不落库。
这个选择很值得说,因为它有明确的代价:
好处:简单。HITL 的 pending 是"一个正在等待的对话",它天然和内存里的运行时状态绑定,存库反而要处理"服务重启了这些 pending 怎么办"。
代价:服务重启,所有 pending 就丢了。 用户回来看到的是"上次那个问题没了",Agent 那边图还停在 interrupt 上。
为什么能接受?因为 30 分钟 TTL 本来就会让它们过期。一个需要审批的操作等了半小时还没人理,重启后丢掉和过期丢掉,对用户来说差别不大——都得重来。
store.py 的方法列表能看出要支持哪些查询:
register / get / get_pending
resolve_for_session / resolve_pending_for_thread
list_pending_for_session / pending_thread_ids
expire_pending_for_thread / mark_resolved / append_ask_answer / _gc
注意 pending_thread_ids(*, agent_id, user_id)——要能按 Agent + 用户查"这个人有哪些对话在等我审批",前端才能在侧边栏打红点。
append_ask_answer 是给"追问"用的:一个问题答完之后又追加了一个问题,答案要能挂回同一条 pending。
六、收尾三路:成功、异常、和"都不是"
第 1 篇提过这段,这里补完整,因为它是我读这个项目时最认可的一处工程细节。
try:
async for ev in project_stream(...):
yield ev
stream_ok = True
hitl_paused = projection_state.hitl_paused
except Exception as exc:
await self._record_stream_error(...)
await self._persist_incomplete_turn(thread_id, history_tracker, title_source=msg.text)
failure_saved = True
yield MessageEvent.error_event(message)
else:
if stream_ok and not hitl_paused:
self._touch_thread_after_turn(thread_id, msg.text)
self._record_turn_usage(...)
await self._record_turn_history(thread_id, history_tracker)
finally:
if not failure_saved and (not stream_ok and not hitl_paused):
await self._persist_incomplete_turn(...)
elif not failure_saved:
await self._finish_history(history_tracker, completed=stream_ok and not hitl_paused)
三个分支各自处理一种"一轮对话怎么结束":
- 正常结束(
else):更新活跃时间、记用量、落历史。 - 抛异常(
except):记错误、落半截历史、标记failure_saved、给前端发错误帧。 - 既没正常结束也没抛异常(
finally里的第一个条件):比如生成器被aclose()掉了,或者hitl_paused为真导致else没进去。这种"不告而别"的情况也要落历史。
failure_saved 这个标志位就是为了防止 except 和 finally 各落一次。 没有它,一次失败会写出两条半截记录。
同时注意 hitl_paused 被当成一种"合法的未完成"——暂停等审批,不是失败,但也不能算完成。所以 _finish_history(completed=False) 和 _persist_incomplete_turn 之间的区分很清楚。
这三路加起来,覆盖了"一轮对话可能有几种死法"。 写对话产品的人一开始只会处理成功那一条,上线后被用户关页面、被模型超时、被进程 kill 教育过之后,才会补出 finally 那一段。
总结
对话链路这一层,四句话:
- 投影层不是转发,是翻译。 269 行把 LangGraph 的事件流翻译成前端认识的帧,同时要拼装流式工具参数、按
tool_call_id归并、处理历史重放。 - 它最难的活是幂等。
Overwrite(full_history)会把历史重放一遍,不做去重用户就会看到旧图片重新加载。三个记账字段(saw_tool_call/emitted_media_ids/emitted_tool_error_ids)合起来解决这件事。教训是:上游语义正确 ≠ 下游体验正确,转换责任只能由转换层承担。 - HITL 那 315 行的
format.py是在"没有 UI 的地方做交互设计"。 企业微信里弹不出复选框,只能列 a/b/c 再把回复解析回来——分隔符要同时认,,、/和空白,因为用户用什么标点看输入法心情。 - 收尾必须三路,缺一路就丢数据。 成功、抛异常、以及"不告而别"(生成器被关掉 / HITL 暂停)——
failure_saved标志位防止重复落库。
顺带一个结构性观察:hitl/ 的 pending 全在进程内存里、30 分钟 TTL、重启即丢。这是第 2 篇"单进程,用进程状态换简单"的又一个例子——能接受丢失的东西就别存库,存了反而要处理"重启后这份状态还算不算数"。
下一篇按编号写 技能、知识库与插件:三个扩展层,三种完全不同的挂载方式,以及 27 个内置插件到底在干什么。
参考链接
- 仓库:https://github.com/TencentCloud/Octop(MIT)
- 本文主读文件:
src/octop/infra/gateway/process/stream_project.py(269 行)src/octop/infra/gateway/hitl/(coordinator.py646 /store.py322 /format.py315 /stream_compat.py86)src/octop/infra/gateway/process/processor.py第 880–945 行(收尾三路)
- 前一篇:(5)一个数据库行怎么变成活着的 Agent · (1)先摊开地图
