读 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 行在解决一个比想象中更土的问题。

版本锚点:本文基于 octop v1.0.2(commit dd9dce4)、octop-harness 1.0.4、langgraph 1.2.16。process/stream_project.py 269 行,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": "你好"}。

这层翻译不是简单的字段改名,它要处理三件麻烦事:

  1. 工具调用的参数是流式的:模型不是一个完整的 JSON 吐出来,而是 {"pa、th": "、a.txt"} 一片片出来。投影层要缓冲拼装(tool_name_buf、tool_started)。
  2. 同一个工具调用可能有多段:tool_call_chunk 有 id,要按 id 归并。
  3. 历史会被重放(下一节展开)。

所以它有一个专门的状态对象:

@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)

三个分支各自处理一种"一轮对话怎么结束":

  1. 正常结束(else):更新活跃时间、记用量、落历史。
  2. 抛异常(except):记错误、落半截历史、标记 failure_saved、给前端发错误帧。
  3. 既没正常结束也没抛异常(finally 里的第一个条件):比如生成器被 aclose() 掉了,或者 hitl_paused 为真导致 else 没进去。这种"不告而别"的情况也要落历史。

failure_saved 这个标志位就是为了防止 except 和 finally 各落一次。 没有它,一次失败会写出两条半截记录。

同时注意 hitl_paused 被当成一种"合法的未完成"——暂停等审批,不是失败,但也不能算完成。所以 _finish_history(completed=False) 和 _persist_incomplete_turn 之间的区分很清楚。

这三路加起来,覆盖了"一轮对话可能有几种死法"。 写对话产品的人一开始只会处理成功那一条,上线后被用户关页面、被模型超时、被进程 kill 教育过之后,才会补出 finally 那一段。

总结

对话链路这一层,四句话:

  1. 投影层不是转发,是翻译。 269 行把 LangGraph 的事件流翻译成前端认识的帧,同时要拼装流式工具参数、按 tool_call_id 归并、处理历史重放。
  2. 它最难的活是幂等。 Overwrite(full_history) 会把历史重放一遍,不做去重用户就会看到旧图片重新加载。三个记账字段(saw_tool_call / emitted_media_ids / emitted_tool_error_ids)合起来解决这件事。教训是:上游语义正确 ≠ 下游体验正确,转换责任只能由转换层承担。
  3. HITL 那 315 行的 format.py 是在"没有 UI 的地方做交互设计"。 企业微信里弹不出复选框,只能列 a/b/c 再把回复解析回来——分隔符要同时认 , , 、 / 和空白,因为用户用什么标点看输入法心情。
  4. 收尾必须三路,缺一路就丢数据。 成功、抛异常、以及"不告而别"(生成器被关掉 / HITL 暂停)——failure_saved 标志位防止重复落库。

顺带一个结构性观察:hitl/ 的 pending 全在进程内存里、30 分钟 TTL、重启即丢。这是第 2 篇"单进程,用进程状态换简单"的又一个例子——能接受丢失的东西就别存库,存了反而要处理"重启后这份状态还算不算数"。

下一篇按编号写 技能、知识库与插件:三个扩展层,三种完全不同的挂载方式,以及 27 个内置插件到底在干什么。

参考链接