ThreadState 详解

ThreadState 是 DeerFlow 代理系统在 LangGraph 图中流转的核心状态容器。定义在 backend/packages/harness/deerflow/agents/thread_state.py:111，继承自 langchain 的 AgentState。它一共 11 个字段（3 继承 + 8 新增），贯穿代理运行的整个生命周期。

全貌

AgentState
├─ messages           Required  add_messages reducer       ← LangGraph 对话核心
├─ jump_to            NotRequired  Ephemeral (不持久化)     ← 图内控制流跳转
└─ structured_response  NotRequired  OmitFromInput         ← 类型化输出扩展点

ThreadState (extends AgentState)
├─ sandbox            merge_sandbox reducer     ← 代码执行沙箱
├─ thread_data        NotRequired               ← 文件系统路径映射
├─ title              NotRequired               ← 线程标题
├─ artifacts          merge_artifacts reducer   ← 输出文件累积
├─ todos              merge_todos reducer       ← Plan 模式任务列表
├─ uploaded_files     NotRequired               ← 当前消息上传文件
├─ viewed_images      merge_viewed_images reducer ← LLM 视觉图片缓存
└─ promoted           merge_promoted reducer    ← 延迟工具激活白名单

一、继承字段（来自 AgentState）

1. messages — Required，add_messages reducer

messages: Required[Annotated[list[AnyMessage], add_messages]]

2. jump_to — EphemeralValue + PrivateStateAttr

jump_to: NotRequired[Annotated[JumpTo | None, EphemeralValue, PrivateStateAttr]]

更新示例：

# TodoMiddleware.after_model
if unfinished_todos andnot has_tool_calls:
return {"jump_to": "model"}  # 强制回到模型节点继续执行

3. structured_response — OmitFromInput

structured_response: NotRequired[Annotated[ResponseT, OmitFromInput]]

二、sandbox — 代码执行沙箱

classSandboxState(TypedDict):
    sandbox_id: NotRequired[str | None]

sandbox: Annotated[NotRequired[SandboxState | None], merge_sandbox]

字段含义

沙箱是代理执行 bash/Python 等代码的隔离环境。sandbox 状态追踪当前线程绑定的沙箱实例 ID。

Reducer 语义：merge_sandbox

defmerge_sandbox(existing, new):
if new isNone:  return existing          # 没有新信息，不动
if existing isNone:  return new           # 首次写入
if existing_id == new_id:  return existing # 幂等——同一沙箱多写
raise ValueError(...)                      # 冲突——不同沙箱 ID，fail-closed

为什么是"冲突抛错"而不是"选一个"？
多个工具并发惰性初始化沙箱，理论上它们都拿到同一个 sandbox_id——这是幂等情况。如果出现不同 ID，说明沙箱生命周期/隔离出 bug，静默选择一个会掩盖严重问题，所以故意 fail-closed。

更新时序

线程首次启动
  │
  ├─ before_agent  ─── SandboxMiddleware（eager 模式）
  │   创建沙箱 → 写入 {"sandbox": {"sandbox_id": "sbox_abc123"}}
  │
  ├─ [模型多轮对话]
  │   │
  │   ├─ wrap_tool_call  ─── SandboxMiddleware（lazy 模式）
  │   │   检测到 sandbox 为 None → 创建沙箱
  │   │   → 写入 Command(update={"sandbox": {"sandbox_id": "sbox_abc123"}})
  │   │
  │   └─ wrap_tool_call  ─── ToolOutputBudgetMiddleware（读取）
  │       读取 sandbox → 用于外部化大工具输出
  │
  └─ after_agent  ─── SandboxMiddleware（读取后释放）
      读取 sandbox_id → provider.release(sandbox_id)
      注意：释放沙箱资源，但不清除 state 中的 sandbox 字段

三、thread_data — 文件系统路径映射

classThreadDataState(TypedDict):
    workspace_path: NotRequired[str | None]  # 工作目录
    uploads_path: NotRequired[str | None]     # 上传文件目录
    outputs_path: NotRequired[str | None]     # 输出文件目录

thread_data: NotRequired[ThreadDataState | None]

字段含义

代理和 LLM 通过虚拟路径（如 /mnt/user-data/workspace）引用文件，而工具需要真实的主机路径来执行指令。thread_data 就是这张映射表，每个线程有独立的工作区。

设计要点

• • 无 reducer：每次 before_agent 全量覆盖写入，因为每个线程的路径是确定的，不存在并发写入冲突。
• • 最先执行：ThreadDataMiddleware 在中间件链中排第 0 位，确保后续所有工具和中间件都能读取到路径。
• • 线程隔离：不同线程（对话）有独立的 workspace/upload/output 目录。

更新时序

线程每次 agent run 启动
  │
  └─ before_agent  ─── ThreadDataMiddleware（第0位）
      计算三个路径 → 写入 {"thread_data": {"workspace_path": "...", ...}}

贯穿整个 agent run
  │
  ├─ wrap_tool_call  ─── ToolOutputBudgetMiddleware（读取 outputs_path）
  ├─ 工具内部  ─── present_file_tool（读取 outputs_path 做路径校验）
  ├─ 工具内部  ─── view_image_tool（读取 outputs_path 做路径掩码）
  ├─ 工具内部  ─── task_tool（读取后传给子 agent）
  └─ 工具内部  ─── sandbox/tools.py 各 helper 函数

四、title — 线程标题

title: NotRequired[str | None]

字段含义

由 LLM 自动生成的对话标题，显示在对话列表、搜索等 UI 中。用户也可通过 API 手动覆盖。

更新时序

首轮用户消息 → 模型回复 → after_model 触发
  │
  ├─ 检查条件：
  │  1. title 当前为 None（未生成过）
  │  2. 配置启用标题生成
  │  3. 已有 1 条用户消息 + ≥1 条助手消息
  │
  └─ 条件满足 → TitleMiddleware.after_model
      调用 LLM 异步生成标题
      → 返回 {"title": "如何使用 Python 生成报表"}

关键行为：一旦 title 存在，永不再生成。用户通过 PATCH /{thread_id}/state 手动修改 title 后，也会同步到 ThreadMetaStore，确保搜索立即可见。

五、artifacts — 输出文件累积

artifacts: Annotated[list[str], merge_artifacts]

Reducer 语义

defmerge_artifacts(existing, new):
if existing isNone: return new or []
if new isNone: return existing
returnlist(dict.fromkeys(existing + new))  # 合并去重，existing 在前

字段含义

代理在对话中生成的产出文件路径列表（HTML、图片、报告等）。累积式收集——每次 present_files 工具调用追加新路径，不会覆盖旧路径。

更新时序

模型调用 present_files 工具
  │
  └─ wrap_tool_call  ─── present_files 工具执行
      标准化文件路径 → 追加到 artifacts
      → Command(update={"artifacts": ["report.html", "chart.png"]})

      注意：不直接追加到旧列表，而是发一个新列表
      merge_artifacts reducer 自动合并去重

为什么用 reducer？
同一 graph step 可能并发调用多次 present_files，每个都有自己的输出——reducer 确保不丢文件。

设计问答：如果 artifacts 不用 Reducer 会怎样？

会丢文件，而且是静默丢失。

原因出在 LangGraph 的并行工具执行。present_file_tool 每次被调用时，它只知道自己要输出的文件，不知道别的并行工具也在输出文件：

# present_file_tool 的典型调用
Command(update={"artifacts": ["report.html"]})

如果 artifacts 是普通字段（无 reducer），同一 graph step 中两个并行的 present_files 调用会互相覆盖：

同一 step，模型并行调用两个 present_files：

Tool A: Command(update={"artifacts": ["report.html"]})
Tool B: Command(update={"artifacts": ["chart.png"]})

无 reducer → 两次写入都是全量覆盖
write(artifacts=["report.html"])  →  artifacts = ["report.html"]
write(artifacts=["chart.png"])    →  artifacts = ["chart.png"]  ← 上一个被吞了
最终 artifacts = ["chart.png"]    → report.html 永远丢了

有 reducer → 每次追加，累积合并：

merge_artifacts(None, ["report.html"]) → ["report.html"]
merge_artifacts(["report.html"], ["chart.png"]) → ["report.html", "chart.png"]
最终 artifacts = ["report.html", "chart.png"]  ✓

更阴险的是这个问题在单工具调用场景下完全不可见——只在并发工具调用时才出现。而且前端不会报任何错，用户只会发现"生成的文件少了"。

本质原因：LangGraph 的 Command(update={}) 对普通字段是全量覆盖，不是合并。Reducer 是 LangGraph 提供给你自定义"怎么合并"的机制。没有 reducer，就是最后写入者胜出。

六、todos — Plan 模式任务列表

todos: Annotated[list | None, merge_todos]

Reducer 语义

defmerge_todos(existing, new):
if new isNone: return existing    # 没碰 todos，保持原样
return new                          # 显式写入（即使是空列表），全量替换

为什么是全量替换而不是增量合并？
LLM 通过 write_todos 工具一次性写入完整列表——它不是追加"完成了一个任务"，而是"现在任务列表是这个"。语义上就是全量替换。

字段含义

Plan 模式下，LLM 自主通过 write_todos 工具管理待办事项。仅在 plan_mode=True 时激活。

更新时序

Plan 模式下的 agent run

before_agent
  └─ 清理之前运行残留的 completion_reminders

before_model（每轮 LLM 调用前）
  ├─ 检查：todos 中有未完成任务 AND write_todos 调用已滚出上下文
  └─ 是 → 注入 todo_reminder 消息提醒模型

after_model（每轮 LLM 回复后）
  ├─ LLM 调用了 write_todos → TodoListMiddleware（父类）拦截
  │   → 解析参数 → 写入 {"todos": [...]}
  │
  └─ LLM 想结束对话但还有未完成任务
      → 注入完成提醒 → 写入 {"jump_to": "model"} 强制回去

after_agent
  └─ 清理当前运行的 completion_reminders

七、uploaded_files — 当前消息上传文件

uploaded_files: NotRequired[list[dict] | None]

字段含义

当前消息中用户上传的文件元数据列表（路径、名称、大小、MIME 类型）。不是累积列表——每次新的 agent run 覆盖写入。

更新时序

用户发送带文件的消息
  │
  └─ before_agent  ─── UploadsMiddleware
      从 HumanMessage.additional_kwargs.files 提取
      → 写入 {"uploaded_files": [
          {"path": "/.../report.pdf", "name": "report.pdf", ...}
        ]}
      同时格式化后注入到消息内容（<uploaded_files> 块）

设计注意：uploaded_files 只存当前消息的新文件。历史文件通过扫描 uploads 目录获取，不写入此字段。

设计问答：为什么是 NotRequired 而不是带 Reducer 的 Annotated？

因为 uploaded_files只有单一写入者，且在单一时刻写入一次。

before_agent  →  UploadsMiddleware  →  写入 uploaded_files
                          ↓
                   只运行一次，非并发

整个 agent run 生命周期中，只有 UploadsMiddleware.before_agent 会写 uploaded_files。不是从工具并发写入的，不存在多写入者互相覆盖的问题。

语义是"当前消息的文件"，不是"累积历史" —— 这是关键：

用户消息1：上传了 report.pdf  → uploaded_files = [report.pdf]
用户消息2：上传了 chart.png   → uploaded_files = [chart.png]    ← 覆盖，不累积

如果用带 reducer 的累积合并（像 artifacts 那样），会发生：

merge 行为 → uploaded_files = [report.pdf, chart.png]
→ 前端会认为用户当前消息上传了两个文件，而实际上第二个消息没有 report.pdf
→ 历史文件信息通过扫描 uploads 目录获取，不应该混在这个字段里

所以不用 reducer 是对的 —— 每次覆盖恰好表达了"当前消息的文件"这个语义。

为什么是 NotRequired 而不是 Required？ 新线程启动时没有上传文件 → None。不是每条消息都有附件 → None。NotRequired 精确表达了"这个字段可能不存在"的语义。如果设为 Required，每个新线程初始时都必须显式设为空列表，增加无意义的默认值维护成本。

什么时候需要改成 Annotated + Reducer？ 当且仅当出现多个中间件或工具需要在同一 agent run 中并发写入上传文件信息时。当前架构中不存在这种情况——uploads 是一个单一职责的中间件。如果未来架构变了，再加 reducer 也不迟：NotRequired 到 Annotated 的迁移是向后兼容的。

八、viewed_images — LLM 视觉图片缓存

classViewedImageData(TypedDict):
    base64: str# base64 编码的图像数据
    mime_type: str# 如 "image/png"

viewed_images: Annotated[dict[str, ViewedImageData], merge_viewed_images]

Reducer 语义

defmerge_viewed_images(existing, new):
if existing isNone:  return new or {}
if new isNone:  return existing
iflen(new) == 0:  return {}          # 空字典 = 清空缓存！
return {**existing, **new}             # 合并，新值覆盖同路径

巧妙的"脏标记"设计：空字典 {} 不是"无变化"，而是**"全部清除"**。ViewImageMiddleware 在成功将图片注入 LLM 上下文后，通过 Command(update={"viewed_images": {}}) 清空缓存，防止下一轮调用重复看到同一批图片。

字段含义

代理调用 view_image 工具"看"图片时，工具将图片 base64 编码后缓存到这里。中间件在 LLM 调用前检测到有缓存图片，注入含图片数据的 HumanMessage，让多模态 LLM 真正"看到"图片。

更新时序

LLM 调用 view_image("/path/to/chart.png")
  │
  └─ wrap_tool_call  ─── view_image_tool
      读取图片 → base64 编码 → 写入 viewed_images
      → Command(update={
            "viewed_images": {"/path/to/chart.png": {"base64": "...", "mime_type": "image/png"}}
        })

下一轮 before_model
  │
  ├─ ViewImageMiddleware 检测到 viewed_images 非空
  ├─ 检查消息中是否已有 "Here are the images you've viewed" 标记 → 避免重复注入
  ├─ 构建含 base64 图片数据的 HumanMessage → 注入到消息列表
  └─ 注入完成后 → Command(update={"viewed_images": {}})  ← 清空缓存

限制：

• • 单张图片 ≤ 20 MiB
• • 仅允许访问 /mnt/user-data/workspace、/mnt/user-data/uploads、/mnt/user-data/outputs 下的图片
• • 仅在 feat.vision is not False 时生效

设计问答：用空字典 {} 表示"清空"是否是一个好的设计？

是务实的设计，但不是优雅的设计。

好在哪

零额外开销。 不需要新字段、不需要 sentinel 对象、不需要改动数据结构。一行判断搞定：

iflen(new) == 0:
return {}

语义在 reducer 内部完全自洽。 读取 state 的代码（ViewImageMiddleware.before_model）只需要 state.get("viewed_images") —— 它不需要知道"清空"的特殊语义，因为清空前它已经读取完数据了，清空后它拿到空字典也正确（没有图片可注入）。

糟在哪

隐式约定。 只看类型定义的人，永远不知道 {} 和 {"a": ...} 有完全不同的语义差异。写工具代码的人可能无意中传入空字典，触发非预期的"清空"：

# 某天有人写了类似的工具：
defsome_new_image_tool(...):
    images = load_images()  # 返回空字典因为没找到图片
return Command(update={"viewed_images": images})  # 意外清空了已有缓存！

虽然当前代码没有这个问题（只有 view_image_tool 写入，且 ViewImageMiddleware 写入 {} 是显式的），但这种隐式约定是潜在的 bug 来源。

有什么更好的替代方案？

方案 A：sentinel 对象

_CLEAR = object()

defmerge_viewed_images(existing, new):
if new is _CLEAR:
return {}
    ...

语义清晰明确。但 _CLEAR 需要放进 Command(update={}) 并经过 checkpointer 序列化（pickle/json）—— 自定义 object 在序列化/反序列化后身份可能丢失，导致 new is _CLEAR 失效。

方案 B：独立 boolean channel

viewed_images: Annotated[dict, merge_viewed_images]
_clear_viewed_images: Annotated[bool, ...]   # 独立的"脏标记" channel

语义清晰，两个字段各司其职。但增加了复杂度：两个字段需要协调—— before_model 读完 viewed_images 后设置 _clear_viewed_images = True，下一个 reducer 检测到后清空。

方案 C：不清空，靠消息标记防重复

ViewImageMiddleware 已经在检查"图片是否已经注入过"（_should_inject_image_message 遍历消息找标记）。可以完全不使用 {} 清空，纯靠这个检查防止重复注入。

但问题在于：base64 图片数据会持久化到 checkpointer。一张图片几百 KB 的 base64 存在 checkpoint 里，线程关闭再打开还在——这是不必要的数据膨胀。

结论

当前设计是一个工程权衡：牺牲一点语义纯粹性，换取零额外复杂度的数据清理。评分 7/10 —— 能用，文档写清楚了，但不够自解释。如果要改进，倾向方案 C + 不回写 viewed_images 到 checkpointer（如果 LangGraph 支持某字段不持久化的话），但从目前 LangGraph 的机制来看做不到这一点。

核心洞察：当前设计本质上是一个"用完即弃"的内存标记 —— 使用 {} 清空是为了在正确的时刻把它从持久化状态中删掉，避免 base64 图片数据污染 checkpoint 存储。

九、promoted — 延迟工具激活白名单

classPromotedTools(TypedDict):
    catalog_hash: str# 工具目录 SHA256 前16位
    names: list[str]      # 已激活的工具名称

promoted: Annotated[PromotedTools | None, merge_promoted]

字段含义

MCP 工具数量可能上百，全部暴露给 LLM 会炸上下文窗口 + 引发幻觉调用。解决思路：MCP 工具默认"延迟"（deferred），只暴露名字不暴露 schema。LLM 必须通过 tool_search 工具主动查询后，该工具才被"promote"（激活），后续可见可调用。

Reducer 语义

defmerge_promoted(existing, new):
ifnot new:  return existing                      # 没新查询，不动
if existing isNoneor hash_mismatch:              # 首次 或 catalog 已过期
return {"catalog_hash": new["catalog_hash"],
"names": list(dict.fromkeys(new["names"]))}    # 全量替换
# hash 相同 → 同类 catalog → 累积合并
return {"catalog_hash": existing["catalog_hash"],
"names": list(dict.fromkeys(existing["names"] + new["names"]))}

catalog_hash 的安全价值

场景——checkpointer 恢复时的"僵尸工具"问题：

1. 1. 线程 A 激活了 send_email → promoted: {catalog_hash: "abc123", names: ["send_email"]} → 持久化
2. 2. 用户关闭线程，MCP 配置更新，send_email 变成了不同的实现
3. 3. 用户重新打开线程，checkpointer 恢复 → promoted.names 里还躺着 "send_email"
4. 4. 如果没 hash 校验 → _promoted() 直接放行这个"已改名"的工具
5. 5. 有 hash 校验 → 恢复时的 catalog_hash 与当前不匹配 → _promoted() 返回空集 → 工具重新被过滤

更新时序

LLM 决定查找工具：tool_search("github")
  │
  └─ wrap_tool_call  ─── tool_search 工具
      查询匹配 → 返回结果 + 写入 promoted
      → Command(update={
            "promoted": {"catalog_hash": "abc123...", "names": ["github_search_repos", "github_create_issue"]}
        })

下一轮 before_model 和 wrap_model_call
  │
  ├─ DeferredToolFilterMiddleware._promoted(state) 读取 promoted
  │   → hash 匹配 → 返回激活工具名集合
  │
  ├─ _hidden(state) → 所有 deferred 工具 - 已激活工具 = 仍需隐藏的
  │
  ├─ wrap_model_call → 从 bind_tools 中移除隐藏工具的 schema
  │   LLM 现在能看到 github_search_repos 和 github_create_issue 的完整 schema ✓
  │
  └─ wrap_tool_call → 如果有人试图直接调用未激活的工具
      → 返回错误 ToolMessage: "Tool 'X' is deferred. Call tool_search first"

双重防线：

• • 第一道（before_model）：LLM 根本看不到未激活工具的 schema，正常不会调用
• • 第二道（before_tool）：即使 LLM 幻觉或状态不一致尝试调用，也返回错误拦截

完整生命周期时序

按一次完整 agent run 的时间线，展示所有字段的读写窗口：

┌── 线程启动，LangGraph 从 checkpointer 恢复 state ──────────────────┐
│  messages 有历史，viewed_images 为空，promoted 可能已持久化      │
└──────────────────────────────────────────────────────────────────┘

▼  before_agent
   thread_data     ◀── ThreadDataMiddleware 写入（第 0 位，最先执行）
   sandbox         ◀── SandboxMiddleware 写入（eager 模式）
   uploaded_files  ◀── UploadsMiddleware 写入（从当前消息提取）

▼  before_model（第一次 LLM 调用）
   todos           ◀── TodoMiddleware 读取（上下文丢失检查）
   viewed_images   ◀── ViewImageMiddleware 读取 → 有缓存则注入图片消息 → 写入 {} 清空
   promoted        ◀── DeferredToolFilterMiddleware 读取 → 决定隐藏哪些工具
   wrap_model_call  ◀── DeferredToolFilterMiddleware 过滤工具 schema

▼  模型节点 → LLM 输出 AIMessage（可能含 tool_calls + write_todos 工具调用）
   messages        ◀── AIMessage 通过 add_messages 追加

▼  工具节点 → 执行 tool_calls
   sandbox         ◀── SandboxMiddleware lazy 创建（如果需要）
   artifacts       ◀── present_file_tool 写入新文件路径
   viewed_images   ◀── view_image_tool 写入 base64 图片缓存
   promoted        ◀── tool_search 写入激活工具列表
   todos           ◀── TodoListMiddleware（父类）拦截 write_todos 写入
   messages        ◀── ToolMessage 通过 add_messages 追加

▼  after_model
   title           ◀── TitleMiddleware 条件写入（首次对话后）
   todos           ◀── TodoMiddleware 读取 → 未完成则强制 jump_to: model

▼  （可能的多轮 "before_model → 模型 → 工具 → after_model" 循环）

▼  after_agent
   sandbox         ◀── SandboxMiddleware 读取 sandbox_id → 释放资源
   todos           ◀── TodoMiddleware 清理提醒

▼  持久化到 checkpointer ─────────────────────────────────────
   messages, sandbox, title, artifacts, todos, viewed_images, promoted
   注意：jump_to 不持久化（EphemeralValue）

汇总表

设计哲学总结