读 Octop 源码(4):9 个中间件,9 个被踩出来的坑

文章目录

第 5 篇写 _start_agent 的时候,第 ⑦ 步我写的是「_post_start_agent:注入 gateway 工具、清洗 MCP 工具名、同步技能」,一句就过去了。

其实那一步里藏着整个项目我最喜欢的一部分:9 个中间件。

它们合计不到 900 行,每个都很小,但每一个都对应一个具体的、真实发生过的问题。

版本锚点:本文基于 octop v1.0.2(commit dd9dce4)、langchain 的 AgentMiddleware(langchain-core 1.6.12)。infra/agents/middleware/ 共 875 行,8 个文件。

环境准备

读中间件要先知道它们能挂在哪,否则看不懂为什么这么写。

第一步,看 LangChain 给了哪些钩子。

cd ~/WorkBuddy/Claw/octop
.venv/bin/python -c "
from langchain.agents.middleware import AgentMiddleware
print([m for m in dir(AgentMiddleware) if not m.startswith('_')])
"

输出(同步/异步成对):

['aafter_agent', 'aafter_model', 'abefore_agent', 'abefore_model',
 'after_agent', 'after_model', 'awrap_model_call', 'awrap_tool_call',
 'before_agent', 'before_model', 'wrap_model_call', 'wrap_tool_call',
 'name', 'state_schema', 'trace_policy', 'transformers']

六组钩子,按触发粒度从粗到细:

钩子什么时候跑能干什么
before_agent / after_agent整轮前后检查配额、注入上下文
before_model / after_model每次模型调用前后改消息、记用量
wrap_model_call包住模型调用换模型、重试、降级
wrap_tool_call包住工具调用改参数、拦截、改结果
transformers消息流变换脱敏、裁剪
state_schema扩展状态字段存中间状态

第二步,看这个项目挂了哪些。 8 个文件,加上知识库那边贡献的 1 个,一共 9 个:

ls src/octop/infra/agents/middleware/
# binary_read_guard.py  browser_profile.py  model_failover.py
# octop_ui_offload.py   reasoning.py        thread_artifacts.py
# token_quota.py        workspace_image.py

流程

一、中间件是 Octop 侵入 harness 的唯一合法接口

先看边界。_post_start_agent 里那段装配代码,注释把归属划得很清楚:

# FilesystemGuard + ModelSettings live in octop-harness (auto-mounted).
# BinaryReadGuard stays Octop-specific (inbound/attachment product policy).
# ThreadArtifacts writes workspace paths onto threads after successful tools.
# WorkspaceImageMaterialize expands path-only vision refs at model-call time.
# OctopUiOffload stays innermost so every outer middleware observes the
# slimmed content consistently; it only touches octop_ui plugin envelopes,
# disjoint from the file-tool results ThreadArtifacts cares about.

FilesystemGuard 和 ModelSettings 是 harness 自动挂的,不用 Octop 管。 前者管文件访问边界,后者管模型参数——两者都是"运行时该负责的事"。

剩下 9 个全是 Octop 自己的产品逻辑:

  • BinaryReadGuard:产品策略(我们的产品不允许用 read_file 读 PDF)
  • ThreadArtifacts:产品数据(把产物路径记到 threads 表)
  • OctopUiOffload:产品协议(我们自定义的 octop_ui 工具信封)

这个分法很关键。“运行时该负责的"和"产品想强加的"必须分开,否则 harness 会被产品逻辑污染,变成一个只能服务这一个产品的库。

而中间件就是这条分界线上的接口:harness 提供钩子,Octop 往里塞自己的东西,双方不需要互相 import。

二、9 个中间件,9 个具体问题

我把每个的 docstring 抄了出来,因为每一句都是一个需求:

中间件docstring行数
token_quotaReject agent turns when the acting user has exhausted their token quota.48
reasoningApply per-turn provider-specific reasoning request parameters.50
browser_profileForce browser tool calls onto the current user’s isolated profile.71
workspace_imageEphemeral workspace-image rematerialization for model calls (plan B).88
octop_ui_offloadOffload oversized octop_ui tool payloads onto ToolMessage.artifact.88
binary_read_guardBlock read_file on binary inbound attachments (PDF, Office, …).128
thread_artifactsRecord workspace file paths onto threads.artifacts after successful tool calls.199
model_failoverHealth-aware and context-safe model failover for AUTO-routed turns.203
knowledge_search_hint(在 infra/knowledge/hint.py)在合适的时机提示模型去查知识库—

挑几个最有意思的说。

workspace_image 的 docstring 里有个 “plan B” —— 这个词说明前面有个 plan A 挂了。它的作用是"在模型调用时把只有路径的图片引用临时重建出来”。也就是说:Agent 在历史里只看到 ![img](/path.png) 这样的文本引用,真正调模型前才把文件读成 image content 塞进去。为什么?因为如果一开始就把图片塞进消息,历史会越存越大、每次都重传。

model_failover 的两定语是 “Health-aware” 和 “Context-safe” —— 不是简单的 try/except 换模型。前者要维护模型健康状态(哪个挂了、挂多久),后者要保证换了模型之后上下文还放得下(不同模型的 context window 不同,换之前得算)。

thread_artifacts 199 行是第二大的,因为它要做的事比看上去复杂:判断工具的返回值里哪个字段是文件路径、路径是否在工作区内、是否已经记过、多文件怎么去重。文件工具、代码执行、图片生成,每个工具的返回结构都不一样。

三、顺序为什么不能换

装配顺序是这样的:

agent_middleware: list[Any] = [
    *plugin_middleware,                       # 插件贡献的,最外层
    TokenQuotaMiddleware(...),                # 配额
    ReasoningRequestMiddleware(),             # 模型参数
    KnowledgeSearchHintMiddleware(),          # 知识库提示
    BrowserProfileMiddleware(),               # 浏览器隔离
    BinaryReadGuardMiddleware(),              # 二进制拦截
    WorkspaceImageMaterializeMiddleware(...), # 图片重建
    ThreadArtifactsMiddleware(...),           # 产物记录
    OctopUiOffloadMiddleware(),               # 最内层
]

注释只解释了最后一个的位置:

OctopUiOffload stays innermost so every outer middleware observes the slimmed content consistently; it only touches octop_ui plugin envelopes, disjoint from the file-tool results ThreadArtifacts cares about.

翻译:OctopUiOffload 必须最内层,因为它负责"把超大工具返回值换成引用"。它必须离工具最近,先把大 payload 瘦身,这样外面所有中间件看到的都是瘦身后的版本。

而它和 ThreadArtifacts 又不冲突——因为一个只碰 octop_ui 的信封,另一个只关心文件工具的返回,两边的数据类型不相交。

这个顺序里藏着一个通用的设计原则:越靠内层的中间件,越接近"原始数据",越应该做"物理层"的事(换模型、裁剪载荷);越靠外层的,越应该做"策略层"的事(配额、权限、审计)。

如果 TokenQuota 放最内层会怎样?配额检查发生在每次工具调用时,一轮对话里有 20 次工具调用就查 20 次数据库,而它其实只需要在轮次开始时查一次。

如果 OctopUiOffload 放最外层呢?它拿到的是已经被其它中间件处理过的数据,可能已经不是它认识的格式了。

四、两个最值得抄的实现

第一个:browser_profile,fail closed 的样本。

_BROWSER_TOOL = "browser_use"
_MISSING_USER = (
    "browser_use blocked: the current turn has no Octop user id, "
    "so a browser profile cannot be isolated."
)

def _bind_browser_profile(request: ToolCallRequest) -> ToolCallRequest | ToolMessage:
    tool_call = request.tool_call
    if str(tool_call.get("name") or "") != _BROWSER_TOOL:
        return request

    configurable = dict(get_config().get("configurable") or {})
    user_id = parse_octop_user_id(configurable.get("user"))
    if user_id is None:
        logger.warning("browser_use blocked: configurable.user is missing or invalid")
        return ToolMessage(
            content=_MISSING_USER,
            tool_call_id=str(tool_call.get("id") or ""),
            status="error",
        )

    raw_args = tool_call.get("args")
    args = dict(raw_args) if isinstance(raw_args, dict) else {}
    args["profile"] = user_browser_profile(user_id)
    return request.override(tool_call={**tool_call, "args": args})

四点值得学:

  1. 只拦自己关心的工具,第一个 if 直接放行其它工具,不做多余判断。
  2. 拿不到用户就直接拒绝执行,还返回一个说明原因的 ToolMessage(status="error")。不是抛异常(会中断整轮),也不是放行(会造成串号),而是"让模型知道这件事做不了"。
  3. 强制覆盖参数,不是"建议",是 args["profile"] = ... 直接改。
  4. request.override(tool_call=...) —— 用不可变的方式产出新请求,不改原对象。

这个中间件是第 8 篇那个"隔离只有一层真边界"结论的反例。 文件系统默认没有边界,但浏览器 profile 是按用户硬隔离的——因为 Chrome 的用户数据目录一旦共用,cookie、登录态就串了,后果比文件被读严重得多。

也就是说:这个项目在"后果严重"的地方做了真隔离,在"后果可控"的地方选择了自律。 这个取舍比一刀切的做法成熟。

第二个:binary_read_guard,白名单 + 黑名单的样本。

_READ_FILE_TOOL = "read_file"
_BLOCKED_EXTENSIONS = frozenset({
    ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx",
    ".zip", ".bin", ".gif", ".webp", ".jpg", ".jpeg", ".png",
})
_TEXT_EXTENSIONS = frozenset({".txt", ".md", ".markdown", ...})

为什么要拦?因为 read_file 是把内容当文本塞进 prompt 的。PDF 的二进制进 prompt 会变成一堆乱码,既浪费 token 又让模型彻底混乱——更糟的是它会"自信地"对这些乱码做出解释。

正确路径是走知识库的解析流水线(parse → chunk → 索引),而不是当文本读。所以这个中间件的作用不只是"防错",还是把工具用错的路径堵死,逼着走对的那条。

用 _BLOCKED 而不是 _ALLOWED_TEXT 做主要判断,是个务实的选择:未知扩展名(比如 .xyz)默认放行,因为用户可能有自定义文本格式。黑名单防已知坏情况,白名单留给需要严格控制的场景(OCR 解析那边)。

五、插件也能往这条链里加东西

装配列表第一行是 *plugin_middleware:

plugin_middleware = PluginRegistry().build_middleware_chain(
    global_enabled=effective_plugins
)

插件可以贡献自己的中间件,并且排在最外层。

放最外层是对的:插件的逻辑应该最先看到请求、最后看到结果,因为它是最"外围"的扩展。如果插件中间件塞在最内层,它就能看到工具原始返回值,绕过了 OctopUiOffload 的瘦身——上下文照样会爆。

这个细节说明作者想过"扩展点该在哪一层"这个问题,而不是随便往列表里 append。

六、工具也是三层拼起来的

顺带记一下工具侧的合并顺序,因为和中间件是配套的:

merged_tools: list[Any] = []
if cron_tools:
    merged_tools.extend(cron_tools)
merged_tools.extend(knowledge_tools)
merged_tools.extend(mobile_tools)
merged_tools.extend(plugin_tools)
# agent_list / ask_agent: PeerAgentMiddleware (team_enabled=True), not config.tools.

四类工具:定时任务、知识库、远程手机、插件。

最后那行注释是个有意思的例外:agent_list / ask_agent 这两个"跨 Agent 协作"的工具不是普通工具,而是由 PeerAgentMiddleware 提供。因为它们需要访问 team 状态、需要处理跨 Agent 的会话路由,普通工具函数拿不到这些上下文。

同一个能力,根据它需要的上下文深度,选择挂成"工具"还是"中间件"。 这是个挺细的判断。

总结

中间件这一层,四句话:

  1. 它是 Octop 侵入 harness 的唯一合法接口。 harness 自动挂运行时的(FilesystemGuard、ModelSettings),Octop 挂产品的(9 个),双方不用互相 import。这个分法保护了 harness 的可复用性。
  2. 9 个中间件对应 9 个真实问题,没有一个是为架构而架构。 读二进制附件、浏览器 profile 串号、模型挂了切换、工具返回撑爆上下文、产物路径要记录——每个 docstring 都是一句需求描述。workspace_image 那个 “plan B” 还留着上一版方案失败的味道。
  3. 顺序按"物理层在内、策略层在外"排。 配额在最外(一轮查一次就够),载荷瘦身在最内(必须先于所有人看到原始数据)。插件贡献的中间件也放最外,否则它能绕过瘦身。
  4. browser_profile 是最值得抄的一段。 拿不到用户就 fail closed 返回 ToolMessage(status="error"),不抛异常也不放行,还顺手告诉模型原因。顺便它是第 8 篇结论的反例——这个项目在"后果严重"处做硬隔离,在"后果可控"处选自律。

下一篇是 (5)Agent 运行时(它其实更基础,建议先读那篇),再往后是 (6)对话链路:project_stream 那 269 行怎么把 harness 的原始事件投影成前端认识的帧,以及 HITL 那 1,393 行在解决什么。

参考链接