第 0 章 · 心智模型
在读任何一行 deepagents 代码之前，先把一件事想清楚：Deep Agent 到底是什么，它和"调用一次大模型"或者"手写一个 tool 循环"有什么本质区别？
不是"多调用几次模型"
最朴素的 agent 实现长这样：
while True:
response = llm.invoke(messages)
if response.tool_calls:
for call in response.tool_calls:
result = run_tool(call)
messages.append(tool_result_message(result))
else:
break这段代码能跑，问题是它对上下文这件事完全没有意见：每一轮工具调用的结果原封不动地塞进 messages，直到某一天 messages 太大，模型开始报错、变慢、或者干脆把早期的关键信息淹没在几万 token 的噪音里。
真实的深度任务——检索一个几十万字的知识库、核对一份长文档、跑一个需要几十轮工具调用的调查——迟早会撞到这堵墙。单次 LLM 调用没有"迟早"的问题，因为它只有一轮；手写 tool 循环有这个问题，但通常没人在第一版就去解决它，直到线上真的炸了才补救（第 4 章会讲我们自己踩的一次）。
Deep Agent = agent loop + 上下文管理 + 工具，一个都不能少
deepagents 这类框架（以及行业里同类的 harness，比如 Claude Code 自己的实现）解决的不是"怎么调用工具"，而是怎么让一个会调用工具、会运行很久的循环长期保持健康。它把三件事打包在一起：
- Agent loop —— 模型 ⇄ 工具的循环本身，
deepagents基于 LangGraph 实现，可中断、可续跑、可加中间件。 - 上下文管理 —— 什么时候该把旧内容压缩掉，什么时候该把大内容挪出上下文改成"可以再读一次的文件"，什么时候该给子任务一个全新的、干净的上下文。这是
deepagents存在的核心价值，也是本文第 2 章的重点。 - 工具 —— 不只是业务工具（比如 SourceLens 的
search_workspace），还包括框架自带的文件系统工具（ls/read_file/write_file/edit/glob/grep）、任务规划工具（write_todos）、委派工具（task）。
拿掉任何一个，你得到的都不是 Deep Agent：拿掉上下文管理，你得到一个迟早会炸的长循环；拿掉文件系统工具，模型没有地方"卸载"大内容；拿掉委派，所有工作都得挤在一个越来越长的主上下文里。
一句话主线：文件系统即外部可重读记忆
如果只能记住这份指南的一句话，记住这句：
大内容、关键内容放文件，上下文里只留工作集 + 引用。
这不是比喻，是 deepagents 的字面实现方式。它给模型一个私有的、可读写的虚拟文件系统（SourceLens 里是 FilesystemBackend(virtual_mode=True)，第 2 章会讲怎么接）。模型可以把中间结果写成文件，需要的时候再读回来；框架自己也会把超大的工具返回值主动"卸载"成文件——上下文里只留一个"这里有个文件，需要时自己去读"的存根。
这套思路的好处是：上下文的大小和任务处理过的信息总量解耦。你可以检索一个几百万字的语料库，只要每次真正进入上下文的是"当前工作集"而不是"到目前为止读过的一切"，上下文就不会随任务深度线性增长。
代价也很直接：一旦某段内容被判定为"可以再读一次"而不是"独一无二"，框架就敢把它挪出上下文甚至压缩掉。如果这个判断错了——比如把用户在聊天里手打的一段话，当成了"workspace 里随时能重新搜到的证据"——你就会遭遇本文第 4 章那种诡异的"答非所问"。这正是心智模型这一章要立住的第一个分水岭，后面每一章都会回到它。
三步循环之外，你需要知道的另一个分水岭
Deep Agent 的循环本身（模型看上下文 → 决定调用哪个工具 → 工具跑完把结果塞回上下文 → 模型再看一遍）没什么神秘的。真正决定一个 Deep Agent 系统好不好用、稳不稳、贵不贵的，是它在循环之外做的那些"看不见"的管理动作：什么时候压缩、压缩前先保护什么、什么时候卸载、子任务的上下文要不要隔离。这些动作大多通过 middleware（中间件） 实现——deepagents 的中间件不是简单的日志/埋点钩子，而是能读写整个 agent 状态（消息列表、todo 列表、文件系统）的一等公民。
第 1 章开始，我们不再抽象地谈"框架应该怎么设计"，而是真的动手搭一个——从三行代码能跑起来的最小 harness 开始，像 SourceLens 自己当初那样，一步步把它长成一个真正顶用的系统。SourceLens 会贯穿全文，但它始终是例子，不是主角；主角是"如果你也要用 deepagents 封装一个自己的工具，这条路该怎么走"。