DeepCode — 架构与原理

30 秒导读： DeepCode 把「一篇论文 / 一段需求 / 一个 URL」喂进去，吐出一个完整、能跑的代码库。它不是一个会聊天的编码助手，而是一条固定 10 个阶段的多智能体流水线：先把输入消化成一份冻结的复现计划，再让一个实现 agent 逐个文件地写代码。最值得学的是它处理「上下文爆炸」的招：每写完一个文件就把对话历史清空，只保留计划 + 一份累积的代码摘要。

1. 这是什么(零基础也能懂)

一句话定义。 DeepCode(HKUDS 出品)是一个开源的「研究到代码」自动化系统:你给它一篇论文(或一句话需求),它自动产出一整个可运行的项目。

解决什么问题 / 给谁用。 想象你是个研究员,读到一篇很棒的论文,想复现它的算法——通常要花几天到几周读公式、搭环境、调代码。DeepCode 想把这件事自动化:论文进,代码库出。它面向三类活:

场景	输入	输出
Paper2Code	一篇算法/ML 论文(PDF/URL)	复现该算法的完整代码库
Text2Web	一段自然语言描述	前端网页代码
Text2Backend	一段需求描述	后端服务代码

它能做什么(功能)。

解析 PDF/DOCX/URL/纯文本输入,转成 markdown。
把论文/需求规划成一份结构化的复现计划(文件树 + 每个文件干什么)。
(可选)上网搜相关 GitHub 仓库、下载、建索引,实现时当参考。
一个文件一个文件地生成代码,自带循环检测、进度跟踪、记忆压缩。
提供 CLI、Streamlit Web UI、和飞书机器人(nanobot)三种入口。

用起来什么样。 最直接的一条命令行路径(见 deepcode.py:595 的 launch_paper_test):

# 启动 Web UI(Streamlit)
python deepcode.py

# 或跑一个论文复现测试任务
python deepcode.py --paper-test <paper_name>

跑起来后你会在终端看到一串 📊 Progress: 25% - Input Acquisition … 一路到 100% - Finalization,最终代码落在某个任务目录的 generate_code/ 下。

一句话直觉/类比。 把它想成一个自动化的「读论文→写代码」流水线工厂,而不是一个对话机器人:

一个总编排器(像工厂调度)按固定工序走 10 个工位;
每个工位是一个专职 agent(解析、规划、搜参考、建索引、写代码);
工位之间不靠记忆传话,靠落盘的文件传话(initial_plan.txt、indexes/*.json、implement_code_summary.md)。

这个「靠文件而非靠对话历史传递状态」的设计,是理解整个项目的钥匙。

2. 顶层全景(它大概怎么转)

本节讲「大盘」:输入进来后,经过哪些工位,产出哪些文件。

怎么读下面这张图: 从上到下是时间顺序的 10 个 Phase。左边是阶段名,中间是干活的函数(都在 workflows/agent_orchestration_engine.py),右边是这一步落盘的产物——下一步靠读这些文件继续,而不是靠对话上下文。

输入(论文 PDF / URL / 一段需求)
   │
   ▼
┌─────────────────────────────────────────────────────────────────────┐
│  execute_multi_agent_research_pipeline()   ← 主入口,串起全部 10 个 Phase │
│  agent_orchestration_engine.py:1739                                   │
└─────────────────────────────────────────────────────────────────────┘
   │
   ├─ Phase 0+1  准备工作区(无 LLM)        prepare_workflow_environment   →  task_dir/
   ├─ Phase 2    获取输入(下载/转 markdown)  acquire_input_artifact         →  *.md
   ├─ Phase 3    搭工作区基础设施              synthesize_workspace_*         →  目录结构
   ├─ Phase 4    文档分段(可选)              orchestrate_document_preproc*  →  segments/
   ├─ Phase 5    ★ 代码规划                   orchestrate_code_planning      →  initial_plan.txt
   │             (plan review 闸门,可选)     run_plan_review_gate
   ├─ Phase 6    参考分析(indexing 模式)     orchestrate_reference_intel*   →  reference.txt
   ├─ Phase 7    下载相关仓库(indexing 模式) automate_repository_acq*       →  code_base/
   ├─ Phase 8    ★ 给仓库建索引(CodeRAG)     orchestrate_codebase_intel*    →  indexes/*.json
   ├─ Phase 9    ★ 逐文件实现代码             synthesize_code_implementation →  generate_code/
   └─ Phase 10   收尾汇总                      (内联)                        →  返回 status dict

部件一句话职责。

部件	干什么	在哪(文件:符号)
编排主入口	串起 10 个 Phase,管进度/状态/异常	`workflows/agent_orchestration_engine.py:1739` `execute_multi_agent_research_pipeline`
规划器	把论文压成 `initial_plan.txt`,带重试与降级	同文件 `:591` `run_code_analyzer`
实现工作流	800 轮主循环,逐文件写代码	`workflows/code_implementation_workflow.py:363` `_pure_code_implementation_loop`
简洁记忆 agent	write_file 后清空对话,只留计划+摘要	`workflows/agents/memory_agent_concise.py:27` `ConciseMemoryAgent`
实现 agent	执行 MCP 工具调用、拦截 read_file	`workflows/agents/code_implementation_agent.py:33` `CodeImplementationAgent`
CodeRAG 索引器	分析下载的仓库,产出关系索引	`tools/code_indexer.py:68` `CodeIndexer`
MCP 工具服务器	提供 write_file/read_code_mem/execute_* 等工具	`tools/code_implementation_server.py`

主线走一遍(高层,不进代码)。 输入 →(转 markdown)→ 规划成一份冻结的计划文件 →(可选:搜+下+索引参考仓库)→ 实现 agent 拿着计划,一个文件一个文件地写,每写完一个就清空对话历史、把要点存进摘要文件 → 全部文件实现完 → 返回。

注意两个「★」标的阶段(规划、实现)和一个核心机制(write_file 触发记忆清零)是全项目工程含量最高的地方,后面四章逐个拆。

3. 阅读地图(建议顺序)

这是个大项目(编排引擎 2300+ 行、记忆 agent 2200+ 行)。建议这样读:

01-orchestration-pipeline.md —— 先看主线:10 个 Phase 各干什么、enable_indexing 开关怎么砍掉一半阶段、状态/异常怎么收口。读完你能讲清「DeepCode 大概怎么转」。
02-planning.md —— 规划阶段:怎么把论文压成 initial_plan.txt,为什么要分段、为什么计划要「冻结」、规划失败时的多级降级。这是「研究 → 可执行计划」的关键。
03-implementation-loop.md —— 实现主循环:800 轮的 while、单文件粒度、循环检测/进度跟踪、退出条件(凭 unimplemented_files 空了才算完)。
04-memory-and-coderag.md —— 两个最妙的机制:① write_file 触发的「干净起点」记忆(把上下文压到常数级);② read_file → read_code_mem 拦截 + CodeRAG 参考检索。这是读者要带走的精华。

如果你只有 10 分钟:读本页 §2 + 第 04 章的「write_file 记忆清零」一节。

4. 一句话总结它的取舍

DeepCode 赌的是:复杂代码生成的瓶颈不是模型能力,而是「上下文管理 + 工作流脚手架」(README 的实验结论原话:同样用 Claude Sonnet 4.5 / GPT-5,DeepCode 在 PaperBench 上比 Cursor/Claude Code 高 +26%)。

所以它把赌注全压在结构上:固定流水线、冻结的中间产物、激进的记忆清零。代价是不灵活——它不是给你边聊边改的助手,而是一条「投料→出货」的产线。详见各章「边界与局限」。

1. 这是什么(零基础也能懂)​

2. 顶层全景(它大概怎么转)​

3. 阅读地图(建议顺序)​

4. 一句话总结它的取舍​

1. 这是什么(零基础也能懂)

2. 顶层全景(它大概怎么转)

3. 阅读地图(建议顺序)

4. 一句话总结它的取舍