读 Octop 源码(4):9 个中间件,9 个被踩出来的坑
第 5 篇写 _start_agent 的时候,第 ⑦ 步我写的是「_post_start_agent:注入 gateway 工具、清洗 MCP 工具名、同步技能」,一句就过去了。
其实那一步里藏着整个项目我最喜欢的一部分:9 个中间件。
它们合计不到 900 行,每个都很小,但每一个都对应一个具体的、真实发生过的问题。
版本锚点:本文基于
octopv1.0.2(commitdd9dce4)、langchain的AgentMiddleware(langchain-core1.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_quota | Reject agent turns when the acting user has exhausted their token quota. | 48 |
reasoning | Apply per-turn provider-specific reasoning request parameters. | 50 |
browser_profile | Force browser tool calls onto the current user’s isolated profile. | 71 |
workspace_image | Ephemeral workspace-image rematerialization for model calls (plan B). | 88 |
octop_ui_offload | Offload oversized octop_ui tool payloads onto ToolMessage.artifact. | 88 |
binary_read_guard | Block read_file on binary inbound attachments (PDF, Office, …). | 128 |
thread_artifacts | Record workspace file paths onto threads.artifacts after successful tool calls. | 199 |
model_failover | Health-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 在历史里只看到  这样的文本引用,真正调模型前才把文件读成 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_uiplugin 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})
四点值得学:
- 只拦自己关心的工具,第一个
if直接放行其它工具,不做多余判断。 - 拿不到用户就直接拒绝执行,还返回一个说明原因的
ToolMessage(status="error")。不是抛异常(会中断整轮),也不是放行(会造成串号),而是"让模型知道这件事做不了"。 - 强制覆盖参数,不是"建议",是
args["profile"] = ...直接改。 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 的会话路由,普通工具函数拿不到这些上下文。
同一个能力,根据它需要的上下文深度,选择挂成"工具"还是"中间件"。 这是个挺细的判断。
总结
中间件这一层,四句话:
- 它是 Octop 侵入 harness 的唯一合法接口。 harness 自动挂运行时的(
FilesystemGuard、ModelSettings),Octop 挂产品的(9 个),双方不用互相 import。这个分法保护了 harness 的可复用性。 - 9 个中间件对应 9 个真实问题,没有一个是为架构而架构。 读二进制附件、浏览器 profile 串号、模型挂了切换、工具返回撑爆上下文、产物路径要记录——每个 docstring 都是一句需求描述。
workspace_image那个 “plan B” 还留着上一版方案失败的味道。 - 顺序按"物理层在内、策略层在外"排。 配额在最外(一轮查一次就够),载荷瘦身在最内(必须先于所有人看到原始数据)。插件贡献的中间件也放最外,否则它能绕过瘦身。
browser_profile是最值得抄的一段。 拿不到用户就 fail closed 返回ToolMessage(status="error"),不抛异常也不放行,还顺手告诉模型原因。顺便它是第 8 篇结论的反例——这个项目在"后果严重"处做硬隔离,在"后果可控"处选自律。
下一篇是 (5)Agent 运行时(它其实更基础,建议先读那篇),再往后是 (6)对话链路:project_stream 那 269 行怎么把 harness 的原始事件投影成前端认识的帧,以及 HITL 那 1,393 行在解决什么。
参考链接
- 仓库:https://github.com/TencentCloud/Octop(MIT)
- 本文主读文件:
src/octop/infra/agents/middleware/(8 个文件,875 行)src/octop/infra/agents/manager.py第 3855–3905 行(装配段)src/octop/infra/knowledge/hint.py(KnowledgeSearchHintMiddleware)
- 钩子来源:
langchain.agents.middleware.AgentMiddleware - 前一篇:(3)配置、目录布局和那个「先不建库」的判定 · (5)一个数据库行怎么变成活着的 Agent
