文章目录前言1. dcode 到底是个啥2. main.py那个 6000 多行的总指挥2.1 cli_main()第一道门2.2 parse_args()你的命令先被扒光2.3 配置与凭证启动前的一堆灵魂拷问3. 三岔路口程序启动之后去哪3.1 ACP给别的机器人留个窗口3.2 Headless闭嘴干活模式3.3 Interactive主线剧情在这4. run_textual_cli_async()跨过那条界4.1 app.pyTUI 不是 Agent5. 为什么要拆 Client 和 Server5.1 LangGraph Server真正干活的地方5.2 make_graph()Graph 的出生地5.3 create_cli_agent()组装车间5.4 create_deep_agent()站在巨人肩膀上6. 完整调用链一张图搞定7. 阅读顺序别从上往下读8. 四层分界线9. 后续怎么读10. 总结P.S. 无意间发现了一个巨牛的人工智能教程非常通俗易懂对AI感兴趣的朋友强烈推荐去看看 传送门https://blog.csdn.net/H1727548前言看源码这件事跟相亲是一个套路第一眼全是优点第二眼全是细节第三眼你已经分不清谁是谁了。今天要拆的是 Deep Agents Code。很多人一上来就冲着那个 6000 多行的 main.py 去了心想从头读到尾总能把这家伙拿下。读了两天半一行没落别人问它怎么跑起来的你只能憋出一句跑起来了而且跑得很复杂。这种状态源码圈有个专业称呼局部清醒整体昏迷。所以正确的打开方式不是硬啃而是先搞到一张地图。本文就是把这张地图给你画出来。1. dcode 到底是个啥先说个扎心的真相你在终端敲的dcode既不是 Python 自带的命令也不是一个独立的 py 文件。dcode它其实是deepagents-code这个包通过pyproject.toml注册出来的一个 CLI 入口。机制上就是一行配置[project.scripts] dcode deepagents_code.main:main翻译成人话装完包之后系统给你造了个快捷键。就像家里装了智能音箱你喊开灯灯就亮但你没道理去拆音箱找灯丝。所以读源码的时候别傻乎乎找dcode.py这文件压根不存在。你要找的是deepagents_code里对应的入口函数。Windows 上装完你会看到.venv/Scripts/dcode.exeLinux/macOS 上则是.venv/bin/dcode。一个 exe、一个裸文件长得不一样干的事一模一样把你敲的命令转手递给 Python深藏功与名。2. main.py那个 6000 多行的总指挥main.py 6000 多行不是因为作者话多而是因为它是个 Orchestrator——总指挥。它不写业务不写 Agent 能力只负责把各种组件按正确的顺序喊起床。很像你家周末的家长自己不起床但能把全家都喊醒而且喊得理直气壮。整个启动流程可以抽象成dcode └─ cli_main() ├─ CLI 参数解析 ├─ 配置加载 ├─ Credentials 凭证 ├─ Model 配置 ├─ MCP 配置 ├─ Sandbox 配置 └─ Runtime 检查所以记住main.py 是应用启动层不是 Agent 核心实现层。别在里面找 Agent它只是负责把 Agent 叫醒的那个闹钟。2.1 cli_main()第一道门所有事情从cli_main()开始def cli_main() - None: ...它干的事非常多解析参数、初始化环境、加载配置、检查凭证、选运行模式、起 TUI、兜住异常、最后还负责打扫卫生。比入职第一天还忙——入职至少还管顿饭。你可以把它理解为整个程序的 Bootstrap启动引导入口办卡、签合同、领工位一套流程走完才开始干活。2.2 parse_args()你的命令先被扒光用户敲的每一句话第一站都是parse_args()args parse_args()你敲dcode --model xxx、dcode --sandbox xxx全都会被解析成结构化的args。model sandbox sandbox_id resume_thread initial_prompt mcp_config no_mcp yolo auto_approve interpreter ...这一步的本质是把人话翻译成程序话。用户说我要用那个模型程序听到的是 modelxxx。翻译过来就是你说的都对但我只认结构化数据。2.3 配置与凭证启动前的一堆灵魂拷问真正创建 Agent 之前程序要先回答一连串问题用什么模型 用什么 API Key 开不开 MCP 用哪个 Sandbox 当前工作目录是啥 要不要恢复历史 Session 允不允许自动执行这些问题不回答清楚Agent 根本起不来。很多人排查Agent 启动失败排查了半天 Agent最后发现挂在配置阶段。就跟你半夜想吃火锅检查了半天锅结果发现是插座没电。锅很委屈你也很委屈。3. 三岔路口程序启动之后去哪初始化完成cli_main()会根据参数把程序送上三条路之一cli_main() ├─ ACP 模式 ├─ Headless 模式 └─ Interactive 模式3.1 ACP给别的机器人留个窗口dcode --acp走的是 ACP 模式让其他 Agent Client 能和 Deep Agents Code 做标准化交互。听着很高端翻译成人话就是给别的机器人留了个客服窗口。如果你主要研究的是普通 Coding Agent 的 TUI这条支线可以先放一放。不是不重要是你现在真没空。3.2 Headless闭嘴干活模式dcode -n 帮我分析当前项目走 Headless 模式不启动终端 UI直接执行任务。适合自动化脚本、CI/CD、批处理。说白了就是闭嘴干活模式不废话干完拉倒。很多打工人做梦都想要这种模式可惜领导不给配。3.3 Interactive主线剧情在这直接敲dcode通常进入 Interactive 模式接着进 Textual TUI。这是本文最重要的一条源码阅读路线。记住这条线dcode → Interactive → Textual TUI。4. run_textual_cli_async()跨过那条界Interactive 模式最终会走到run_textual_cli_async()。这一跳非常关键因为它意味着CLI 启动层 → TUI 应用层正式切换。后面你就要进app.py了。4.1 app.pyTUI 不是 Agent很多人第一次读源码会犯一个错误以为 TUI 就是 Agent。不是。TUI 只是 Agent 的客户端负责接收输入、展示输出、展示工具调用、展示流式输出、展示审批请求、管理 Session。它跟 Agent 的关系就像餐厅服务员和后厨服务员不炒菜厨师不见客。你要是让服务员去颠勺菜就糊了让厨师出来点单客人就跑光了。5. 为什么要拆 Client 和 Server这是读这个项目时最重要的架构概念。Deep Agents Code 不是TUI 直接连 Agent而是ClientTUI→ 通信 → ServerLangGraph AgentClient 管交互Server 管干活。拆开的好处很直白界面崩了不影响 Agent 继续跑。相当于服务员摔了一跤后厨的锅还能继续炒。5.1 LangGraph Server真正干活的地方TUI 不会在自己的进程里跑完整 Agent它会连接一个 LangGraph ServerTextual TUI → RemoteAgent → LangGraph Server → Agent Graph所以读源码要分清两个问题main.py → app.py → RemoteAgent 用户怎么和 Agent 交互 server_graph.py → agent.py → graph.py Agent 本身怎么构造一个是前台的事一个是后厨的事别混。5.2 make_graph()Graph 的出生地进入 Server 侧第一个要记住的函数是server_graph.py里的make_graph()。LangGraph Server → make_graph() → 读取配置 → 创建 Agent → 返回 Graph记住这个分界点就像记住过了这个收费站就进高速不然你会在省道上绕到怀疑人生。5.3 create_cli_agent()组装车间make_graph()继续往下进入agent.py最值得关注的是create_cli_agent()。到这里代码才开始真正把 Coding Agent 的能力拼起来create_cli_agent() ├─ Model ├─ Tools ├─ Middleware ├─ Filesystem / Shell / MCP └─ Skills / Context / HITL ...这已经不是调一个 LLM那么简单了这是在组装一个完整的 Agent Harness运行框架。相当于你不是在买一辆车而是在造一条生产线。5.4 create_deep_agent()站在巨人肩膀上create_cli_agent()继续往下进入libs/deepagents包核心函数是create_deep_agent()。这里有个重要的架构思想Deep Agents 并没有从零造一套 Agent Runtime它是站在 LangChain Agent 和 LangGraph Runtime 肩膀上的。这就是传说中的站在巨人的肩膀上区别是巨人本人可能都不知道自己被人站了。它真正干的事是加料Middleware、Backend、Tools、Skills、Subagents把底层能力包成一个更完整的 Harness。6. 完整调用链一张图搞定现在把整个启动过程串起来dcode → cli_main() → parse_args() → Config / Credentials → Runtime 初始化 → Interactive → run_textual_cli_async() → app.py (TUI) → RemoteAgent → LangGraph Server → server_graph.make_graph() → create_cli_agent() → create_deep_agent() → LangChain create_agent() → LangGraph Agent Runtime这张图就是整个 Deep Agents Code 源码的第一张地图。建议截图保存不然下次你还是会迷路。7. 阅读顺序别从上往下读有了地图就别再按文件目录从上往下读了。更高效的方式是按运行时调用链读① main.py → cli_main() ② main.py → parse_args() ③ main.py → run_textual_cli_async() ④ app.py / TUI → Client / RemoteAgent ⑤ server_graph.py → make_graph() ⑥ agent.py → create_cli_agent() ⑦ deepagents/graph.py → create_deep_agent() ⑧ LangChain → create_agent() ⑨ LangGraph → Agent Runtime这样读的好处是每进一个新文件你都知道我为什么会来到这里。而不是在一个 6000 多行的 main.py 里活成一座孤岛。8. 四层分界线整个项目可以粗暴地分成四层第一层CLI / Applicationmain.py —— 程序怎么启动 第二层Client / TUIapp.py、RemoteAgent —— 用户怎么交互 第三层Coding Agentserver_graph.py、agent.py —— Agent 怎么组装 第四层Deep Agent Harnesslibs/deepagents/—— 能力怎么组织记住这四层你在源码里就不会再脸盲了。9. 后续怎么读本文只解决一个问题Deep Agents Code 到底是怎么启动的。接下来可以沿着主线继续深挖main.py 配置系统、Textual TUI、LangGraph Server、Middleware、Backend、Tools、Skills、Subagents、完整 Agent Loop。全程围绕一个问题用户输入的一句话到底经过哪些组件最终变成一次 Tool Call这条链捋清楚了源码里的细节会自己归位。就像你记住了一个人住哪栋楼以后再见到他就不用满小区喊了。10. 总结Deep Agents Code 不是简单的dcode → LLM → Tool而是一套完整的 Coding Agent Runtime。最核心的三个入口main.py → cli_main() 应用启动 server_graph.py → make_graph() Agent Graph 创建 agent.py → create_cli_agent() Coding Agent 组装再往下create_deep_agent()进入 Deep Agents 的核心 Harness。所以读这个项目最有效的姿势不是从某个 Tool 开始硬啃而是先拿到这张调用链地图再逐层深入。毕竟读源码最怕的不是代码难而是你读了半天发现自己连门都没找对——就像排了两个小时队最后发现排的是隔壁奶茶店。P.S. 无意间发现了一个巨牛的人工智能教程非常通俗易懂对AI感兴趣的朋友强烈推荐去看看传送门https://blog.csdn.net/H1727548