福生无量摸鱼天尊

logo
福生无量摸鱼天尊

paper2proj：DeepCode在模态转换之间的编排

2026/01/15
3
0

1. 概述

DeepCode的工作是将科学论文转化为可执行代码，它提炼出来的问题包括：

  • Specification Preservation（规范保留）: 论文中的信息分散且多模态，难以忠实地将这些片段化的规范映射到实现中。

  • Global Consistency under Partial Views（局部视角下的全局一致性）: 代码库由相互依赖的模块组成，但生成通常是逐文件进行的，在有限上下文下难以维护接口、类型和不变量的全局一致性。

  • Completion of Underspecified Designs（不完全指定设计的补全）: 论文通常只详述算法核心，而忽略实现细节和实验框架，推断这些未明确的但重要的选择极具挑战。

  • Executable Faithfulness（可执行性忠实度）: 忠实复现需要可执行系统，而非仅是貌似合理的代码。长期生成常导致包含逻辑错误、依赖冲突和脆弱管道的代码库，阻碍端到端执行。

其提出的解决思想也很鲜明：

  • 分层内容分段：不将整个文档直接输入到大语言模型中，而是首先将其解析为一种便于有针对性地访问信息的结构化表示。 我们引入了分层内容索引，它利用了学术论文和技术文档固有的结构。 具体过程如下：

    • 结构化解析：对源文档进行解析，根据章节标题等显式分隔符（例如 "3. Methodology", "3.1. Model Architecture"）识别其层次结构。 这将文档划分为一组内容块；

    • 关键词-块关联：每个块存储为一个键值对，其中标题 作为自然的、高层级的语义关键词，而是该章节对应的原始文本内容。

  • 多智能体规范分析 ：用专门的多智能体系统对文档内容进行深入且结构化的分析。 这种方法将复杂的理解任务分解为两个并行轨道，分别由概念智能体 (Concept Agent) 和算法智能体 (Algorithm Agent) 执行。 每个智能体都配备了特定的提示词，并与索引文档进行交互，以提取互补的信息层，从而在不要求同时处理整个文档的情况下确保全面的理解。

    • Concept Agent（概念代理）: 构建文档的整体高层理解，识别核心科学贡献和实验复现所需组件。通过分段阅读策略和语义广义关键词查询索引，输出结构化的概念分析模式。

    • Algorithm Agent（算法代理）: 负责细致地的所有低层技学公式、模型架构、训练过程和超参数。通过特定关键词查询索引，输出粒度化的算法实现模式。

    • Code Planning Agent（代码规划代理）: 将 Concept Agent 和 Algorithm Agent 的输出综合为一个统一的 Implementation Blueprint。它调和高层概念框架与低层技术规范，确保每个抽象组件都链接到精确的技术规范，并解决不一致之处。

  • "代码记忆系统"（CodeMem）：这个系统就像一个非常聪明的项目助理，它会实时记录每个已经完成的代码模块的关键信息—不是把完整的代码都记下来（那样会占用太多"内存"），而是提取出每个模块的核心功能、对外接口、依赖关系等关键信息，形成结构化的摘要。

  • "知识检索系统"（CodeRAG）：维护着一个庞大的代码库索引，当DeepCode遇到不确定的实现问题时，可以从这个库中找到相关的代码样例和最佳实践。比如，当需要实现某个特定的算法时，系统可以快速找到类似算法的高质量实现作为参考。

该框架通过两个连续阶段系统地识别并修复缺陷：

  • 静态分析过程以确保结构完整性和代码质量：DeepCode会检查代码中是否有语法错误、命名不规范、缺少依赖库等问题。

  • 在沙盒环境中的动态执行过程以强制实现功能正确性：DeepCode会尝试实际运行代码，看看能否正常工作，

2. Agent、Context、Prompt 是怎么串起来的（源码角度）

A）核心编排器：workflows/agent_orchestration_engine.py

无论是cli还是ui界面，都会将prompt输入到execute_chat_based_planning_pipeline(...) 。

源码位置：DeepCode/workflows/agent_orchestration_engine.py

这段代码把“Text → Web/Backend”拆成 4 个阶段（都在同一个函数里串起来）：

  1. Workspace Setup

  • 创建 deepcode_lab/ 作为工作目录

  • 为 chat 任务生成一个 chat_project_<timestamp> 的“伪 paper workspace”

  1. Chat-Based Planning

  • 调 run_chat_planning_agent(user_input, logger) 得到一份 YAML 计划（字符串）

  1. Workspace Infrastructure Synthesis

  • 将需求与计划写入一个 markdown（形如 deepcode_lab/papers/chat_project_xxx/chat_project_xxx.md）

  • 构造一个 synthetic_download_result，让后续“论文复现 pipeline”里复用的 FileProcessor/路径规范化逻辑可以工作

  • 调 synthesize_workspace_infrastructure_agent(synthetic_download_result, ...) 得到 dir_info：

    • paper_dir

    • initial_plan_path（最终会写到 paper_dir/initial_plan.txt）

    • implementation_report_path 等

  1. Code Implementation Synthesis

  • 把 plan 写入 initial_plan_path

  • 调 synthesize_code_implementation_agent(dir_info, ..., enable_indexing)

    • enable_indexing=True → CodeImplementationWorkflowWithIndex

    • enable_indexing=False → CodeImplementationWorkflow

这就是 Text2Web/Text2Backend 的“端到端骨架”。

B）Planning Agent：可执行的结构化中间表示（YAML）

Agent 创建与调用：run_chat_planning_agent(...)

源码位置：DeepCode/workflows/agent_orchestration_engine.py

关键点：

  • 通过 mcp_agent.agents.agent.Agent(...) 创建 ChatPlanningAgent

    • instruction = CHAT_AGENT_PLANNING_PROMPT

    • server_names = get_search_server_names()（按配置选择 filesystem / search 等 MCP server）

  • 挂载 LLM：attach_llm(get_preferred_llm_class())

  • 控制输出与稳定性：RequestParams(maxTokens=8192, temperature=0.2)

它实际发给模型的“用户消息”是一个薄包装：

Please analyze the following coding requirements and generate a comprehensive implementation plan:

User Requirements:
<user_input>

Please provide a detailed implementation plan that covers all aspects needed for successful development.

因此真正的 prompt engineering 主要在 CHAT_AGENT_PLANNING_PROMPT。

C）CHAT_AGENT_PLANNING_PROMPT 的工程意图

源码位置：DeepCode/prompts/code_prompts.py

它强制模型输出固定 YAML 骨架（关键片段）：

project_plan:
  title: "[Project Name]"
  description: "[Brief description]"
  project_type: "[web_app|game|academic|tool|api|other]"

  file_structure: |
    project_root/
    ...

  implementation_steps:
    1. "..."

  dependencies:
    required_packages:
      - "package==version"

  tech_stack:
    language: "..."
    frameworks: ["..."]

  main_features:
    - "..."

它的“厉害”不在文案，而在工程上的 三件事：

Feature 1：把开放式需求变成结构化中间表示（IR）

  • 生成代码前先生成一个“可检查/可持久化/可复用”的计划，后续所有 agent 都围绕 IR 工作，显著降低“直接写代码”导致的漂移。

Feature 2：计划里强制包含 file tree + 依赖 + 步骤

  • 这使得后续实现阶段可以：

    • 以文件为最小单元迭代（one-file-per-iteration）

    • 以文件树为“完成定义”（Definition of Done）

Feature 3：硬性约束复杂度：max 15 files

  • 对 Text2Web/Text2Backend 特别重要：前后端项目天生容易爆文件数量；限制文件数能显著提升“能跑起来”的概率。

而这个中间值是pipeline 的一个关键工程技巧：“把输入写成文件，统一成 paper workspace 格式”

  • 生成 deepcode_lab/papers/chat_project_xxx/chat_project_xxx.md

  • 同目录写 initial_plan.txt

  • 后续 workflow 统一使用 paper_dir 作为上下文根目录

这样做的好处：

  • 可以复用论文复现 pipeline 里大量“路径规范化、输出归档、报告落盘”的基础设施

  • agent 的上下文不仅在对话里，也在 filesystem 里（对长任务更稳）

对应的结构化路径信息由 synthesize_workspace_infrastructure_agent(...) 产出：

  • paper_dir

  • reference_path

  • initial_plan_path

  • implementation_report_path

  • ...

D）Code Implementation：工具驱动 + 迭代循环 + 上下文清理

源码位置：

  • DeepCode/workflows/code_implementation_workflow.py（CodeImplementationWorkflow）

  • DeepCode/workflows/code_implementation_workflow_index.py（CodeImplementationWorkflowWithIndex）

它们都做两件事：

Feature 1：create_file_structure(plan_content, target_directory)

  • 创建 StructureGeneratorAgent

  • instruction = STRUCTURE_GENERATOR_PROMPT

  • server_names=["command-executor"]

  • 让模型生成 mkdir/touch 并通过 execute_commands 执行

Feature 2：implement_code_pure(plan_content, target_directory, code_directory)

  • 初始化 LLM client（OpenAI/Anthropic/Google 三选一，见 1.7）

  • 初始化 MCP agent（server_names=["code-implementation", "code-reference-indexer"] 之类）

  • 关键：把 MCP 的 workspace 指向 paper_dir/generate_code（通过 set_workspace）

  • 进入 _pure_code_implementation_loop(...)，循环调用 LLM → 解析 tool_calls → 执行 tool_calls

注意：这里的 “pure_code_mode=True” 明确偏向“把代码生成出来”，不是强制跑测试/跑实验（对 Text2Web/Text2Backend 很现实）。

E）Context / Memory Engineering：清空历史 + 保留计划 + 追踪文件

DeepCode 做了非常激进、但很实用的“上下文清理”策略。

Feature 1：关键组件：ConciseMemoryAgent

源码位置：DeepCode/workflows/agents/memory_agent_concise.py

它维护三类关键信息：

  • 不可压缩的核心：initial_plan（永远保留）

  • 进度状态：已实现文件列表 / 未实现文件列表（从 plan 或目录抽取）

  • 本轮工具结果：把必要的 tool 输出挂回给模型，形成闭环

Feature 2：触发机制：以 write_file 为“回合边界”

核心逻辑：

  • 一旦检测到 write_file 被调用，标记 should_clear_memory_next=True

  • 在下一轮对话里，直接把 messages 历史大幅裁剪，只保留：

    • 系统提示（system prompt）

    • 初始计划（plan）

    • 已实现/未实现文件列表

    • 本轮必要工具结果

源码里对应：

  • record_tool_result(...)：检测 write_file → 触发清理标记

  • should_trigger_memory_optimization(...)：只在 write_file 后触发

  • apply_memory_optimization(...)：调用 create_concise_messages(...) 生成“干净上下文”

  • get_unimplemented_files(...)：用“文件列表”定义完成度，而不是依赖模型一句“done”

这个策略对 Text2Web/Text2Backend 很关键：

  • 前后端项目实现周期长、文件多，直接堆对话很容易“丢上下文/中段遗忘”

  • 用“计划 + 文件清单”作为记忆载体，比依赖自然语言对话更稳

Feature 3：role-aware summary / sliding window

源码位置：DeepCode/prompts/code_prompts.py

相关提示词体现了他们对“长会话退化”的预期：

  • CONVERSATION_SUMMARY_PROMPT：强调 role-aware（区分 user 指令 vs assistant 决策）

  • SLIDING_WINDOW_SYSTEM_PROMPT：定义滑窗策略与触发条件

即使你最终不用“总结型压缩”（因为他们改成更激进的 clear-slate），这些 prompt 仍体现了工程目标：
避免长上下文导致的角色混淆、指令漂移、实现进度丢失。

3. 端到端数据流（数据角度）

A）端到端数据流

以 Text2Web 为例（Text2Backend 同理，只是需求内容不同）：

1.需求摄取（direct/guided）

  • direct：直接把需求当作 user_input

  • guided：先用 RequirementAnalysisAgent 生成问题、收集答案、汇总成“更结构化的需求文档”

    • 位置：DeepCode/workflows/agents/requirement_analysis_agent.py

    • 特点：这个 agent server_names=[]，只用 LLM，不依赖工具

2.规划：Text → YAML Plan（结构化 IR）

  • ChatPlanningAgent + CHAT_AGENT_PLANNING_PROMPT

  • 输出包含：项目类型、文件树、依赖与步骤

3.落盘与工作区规范化

  • 把需求与计划写进 deepcode_lab/papers/chat_project_xxx/...

  • 生成 initial_plan.txt，作为实现阶段的“不可压缩事实源”

4.实现：Plan → Files（工具驱动迭代）

  • 设置 MCP workspace = generate_code/

  • 循环：

    • LLM 选择“下一文件”

    • 通过 write_file 写入该文件

    • 记录结果与进度

    • 触发 clear-slate，把上下文重置为：计划 + 文件清单 + 本轮结果

5.完成判定

  • 不是靠模型说“done”，而是靠 ConciseMemoryAgent.get_unimplemented_files() 为空

B）机制上的agent/context/prompt

Feature 1：结构化中间表示（YAML Plan）把不确定性前置收敛

在 LLM coding 里，“直接从需求写代码”最大的风险是：

  • 缺文件、漏依赖、实现顺序乱

  • 中途需求漂移导致“越写越偏”

DeepCode 用 CHAT_AGENT_PLANNING_PROMPT 强制先产出 plan，相当于：

  • 把需求 → 可执行 spec

  • 把 spec → 文件级任务队列

这让后续实现阶段可以更像“执行计划”，而不是“边想边写”。

Feature 2：工具集最小化（tool budget reduction）提升可控性与稳定性

实现阶段默认只给 write_file（带索引时也只加一个 search_code_references）：

  • 这在工程上是非常强的约束：减少 agent 行为自由度，换取更高的可控性

  • 同时也让“上下文工程”更简单：tool 输出结构更统一、更容易压缩

Feature 3：以 write_file 为边界的“清空上下文”策略，解决长会话退化

这套策略的核心不是“更聪明的摘要”，而是：

  • 把长期记忆落盘到计划与文件清单里

  • 每写完一个文件就清空对话历史

它对真实工程任务（尤其 web/backend 多文件）非常有效：

  • 不怕 token 爆

  • 不怕 lost-in-the-middle

  • 不怕角色混淆（plan 是事实源）

Feature 4：跨模型/SDK 的 tool-call 兼容层（schema 适配 + JSON 修复）

工具调用一旦不稳，agent 就会“卡死在解释而不执行”。

DeepCode 在实现阶段把 tool-call 做成“工程系统”，而不是“prompt 祈祷”：

  • Gemini：schema 转换 + 禁用自动 function calling + 手动解析 function_call

  • OpenAI：tool args JSON 修复与重试

这类工程投入往往比“换更强的模型”更能提升端到端成功率。

Feature 5：需求澄清 agent（guided mode）把“需求缺口”变成可交互的结构化补全

Text2Web/Text2Backend 任务常见失败原因不是写不出代码，而是：

  • 需求缺关键信息（技术栈、部署、鉴权、数据库、页面结构等）

RequirementAnalysisAgent 先提问再汇总，等于把“隐藏变量”显式化，从源头提升计划质量。

4. 价值最高的源码

  1. DeepCode/workflows/agent_orchestration_engine.py

    • chat pipeline 的端到端实现（Text2Web/Text2Backend 在这里落地）

  2. DeepCode/prompts/code_prompts.py

    • CHAT_AGENT_PLANNING_PROMPT（计划 IR）

    • GENERAL_CODE_IMPLEMENTATION_SYSTEM_PROMPT（实现策略）

    • CONVERSATION_SUMMARY_PROMPT/SLIDING_WINDOW_SYSTEM_PROMPT（上下文策略）

  3. DeepCode/workflows/code_implementation_workflow_index.py

    • 最多“工程黑魔法”集中处：provider 适配、tool-call 解析、JSON 修复、工具过滤

  4. DeepCode/workflows/agents/memory_agent_concise.py

    • clear-slate 上下文工程的核心实现

  5. DeepCode/tools/code_implementation_server.py / DeepCode/tools/code_reference_indexer.py

    • 真实工具边界与安全边界（workspace 限制、路径校验等）

参考文献：