DeepCodeResearch-Agent 产品需求文档（PRD）

版本：v2.0
适配场景：赛题 3「DeepCodeResearch-Agent」
核心定位：将“多模态技术文档（PDF/PPT/PNG/Word）”一键转化为“可直接 git clone 运行的完整代码仓库”，实现“10分钟交付、80%单测通过、0高危漏洞、人在回路仅做Review”的研发提效目标。

一、产品概述

1.1 产品定义

DeepCodeResearch-Agent 是一款基于 LangChain+LangGraph 构建的智能研发辅助Agent，通过“多模态理解→深度研究→结构化设计→并行编码→自我修复→人机审核→自动发布”全流程自动化，解决“技术文档转代码耗时久、单测覆盖率低、多模态信息遗漏、跨工具协同复杂”等研发痛点，适用于企业级研发团队、技术文档工程师、开源项目贡献者等角色。

1.2 目标用户

用户角色	核心需求
后端研发工程师	将PRD/PDF技术方案快速转化为可运行代码，自动生成单测，减少重复编码工作
技术文档工程师	将纸质/电子技术文档（含流程图、公式）转化为结构化代码仓库，确保文档与代码一致性
开源项目维护者	基于学术论文/Paper生成开源项目脚手架，自动完成环境配置与基础功能实现
研发管理者	标准化“文档→代码”流程，通过可观测性平台监控研发效率，降低团队协作成本

1.3 解决的核心痛点

多模态信息丢失：传统工具无法有效解析PDF中的流程图、公式、图片，导致代码与文档脱节；
研发效率低下：人工将50页技术文档转化为代码需1-2天，Agent可缩短至10-15分钟；
单测与合规缺失：手动编码易遗漏单测（覆盖率常<50%），Agent可确保单测通过率≥80%且无高危漏洞；
工具协同复杂：研究、编码、评测、发布需切换多工具，Agent通过MCP协议统一集成，无需人工干预；
流程不可控：缺乏“回退、并行、审核”机制，Agent通过LangGraph状态机实现全流程可追溯。

二、目标定位

2.1 业务目标

目标类型	具体指标
效率提升	文档→代码交付时间从“1天”缩短至“≤15分钟”，研发效率提升64倍；
质量保障	生成代码单测通过率≥80%，高危漏洞检测率100%，文档信息还原率≥96%；
用户体验	人机协同仅需“审核确认”1步操作，用户等待时长≤2秒（审核响应）；
场景覆盖	支持“Paper转开源项目、PRD转微服务、UML转前端工程”3类核心场景。

2.2 技术目标

多模态理解：支持PDF/PPT/PNG/Word输入，图表召回率≥80%，公式解析准确率≥95%；
自我修复能力：单测失败后自动修复率≥75%，无需人工干预；
可扩展性：新增MCP工具集成耗时≤30分钟，支持热插拔（无需重启Agent）；
并发能力：单卡A100-80G支持4路并发，P99耗时≤18分钟，QPS≥1；
可观测性：全流程日志覆盖率100%，支持LangSmith追踪、Prometheus监控、Grafana看板。

三、核心功能模块

3.1 1. 多模态输入处理（对应LangChain Loader/Parser）

功能描述

支持多格式技术文档上传，自动解析文本、图片、公式、流程图，转化为结构化LangChain Document对象，为后续研究环节提供统一数据输入。

核心能力

格式支持：覆盖 .pdf（PyPDFLoader）、.pptx（UnstructuredPowerPointLoader）、.txt（TextLoader）、.png（UnstructuredImageLoader）、.docx（可选扩展）；
多模态解析：
- 文本：提取段落、标题、列表，保留文档结构；
- 图片：通过CLIP生成embedding，结合Qwen3-VL-MCP解析流程图/架构图内容（如“微服务调用关系”）；
- 公式：通过Mathpix API（可选MCP集成）解析LaTeX公式，转化为代码可调用的数学函数；
用户操作：前端（Chainlit）支持“拖拽上传”“批量选择”，上传后实时显示“解析进度”（如“已解析3/10页，含2张流程图”）。

技术依赖

基础组件：LangChain DocumentLoader生态、Unstructured库；
MCP工具：Qwen3-VL-MCP（多模态解析）。

3.2 2. 课程式研究规划（对应LangGraph「research」节点）

功能描述

基于多模态解析结果，自动完成“技术背景调研→方案对比→技术选型”，生成结构化研究报告，确保后续设计不偏离文档约束（遗忘率≤4%）。

核心能力

深度研究：
- 调用Tongyi-DeepResearch-MCP获取相关论文（≤5篇）、复现脚本、技术趋势；
- 对50+页长文档，采用“小模型（1.8B）出大纲+大模型（72B）填细节”策略，避免上下文丢失；
方案输出：生成含“3个技术方案对比表”的研究报告，包含“优缺点、性能指标、依赖工具、合规性”（如“Spring Cloud vs Dubbo 选型对比”）；
用户操作：研究完成后，前端展示“研究报告预览”，支持“重新研究”“确认进入设计”操作。

技术依赖

基础组件：LangChain ReAct Agent、Prompt模板（deepcoderesearch/react）；
MCP工具：Tongyi-DeepResearch-MCP（论文调研）、ModelHub-MCP（技术合规性查询）。

3.3 3. 结构化设计生成（对应LangGraph「design」节点）

功能描述

基于研究报告，自动生成“系统架构图→模块划分→接口定义→目录结构”，确保设计符合工程化规范，为并行编码提供清晰输入。

核心能力

设计输出：
- 架构图：调用Wan2.5-Preview-MCP生成可视化架构图（PNG格式），支持“微服务、前后端分离、单机应用”3类架构；
- 模块划分：按“高内聚低耦合”原则拆分模块（如“用户服务、订单服务、支付服务”），输出模块依赖关系图；
- 接口定义：生成Swagger/OpenAPI文档，包含接口路径、参数、返回值、错误码；
- 目录结构：输出代码仓库目录树（如src/main/java/com/example/order/），明确每个文件的功能；
合规检查：调用ModelHub-MCP查询开源组件许可证（如Apache 2.0），避免合规风险。

技术依赖

基础组件：LangChain LLMChain（设计Prompt）；
MCP工具：Wan2.5-Preview-MCP（架构图生成）、ModelHub-MCP（许可证查询）。

3.4 4. 并行编码与沙箱执行（对应LangGraph「code」节点）

功能描述

基于设计方案，将“编码→单测→静态检查”拆分为3-8路并行任务，通过Docker沙箱隔离执行，大幅缩短编码耗时（提速2.7×）。

核心能力

并行任务调度：
- 按模块拆分任务（如“用户模块编码、订单模块编码、支付模块编码”），支持8路异步并发；
- 每个任务包含“代码生成（基于设计目录）→单测生成（pytest/JUnit）→静态检查（pylint/sonar）”3个子步骤；
沙箱隔离：使用DockerSandbox（python:3.11-slim/openjdk:17-slim）执行任务，避免环境依赖冲突；
结果聚合：收集所有并行任务的“代码文件、单测报告、静态检查结果”，生成“编码成果包”（含src/、tests/、requirements.txt）。

技术依赖

基础组件：LangChain 异步任务（asyncio.gather）、DockerSandbox；
MCP工具：Swift-MCP（可选，基于HumanEval微调代码生成模型，提升编码质量）。

3.5 5. 自我反思修复（对应LangGraph「fix」节点）

功能描述

针对编码阶段的“单测失败、静态检查报错”，自动分析原因并生成修复补丁，支持循环重试（直至单测通过或达到重试上限）。

核心能力

失败分析：
- 解析单测失败日志（如“NullPointerException”“断言不匹配”）、静态检查报错（如“未定义变量”“代码冗余”）；
- 调用Reflection Machine（基于LLMChain）生成“统一diff补丁”，明确修改位置、原因、代码；
循环修复：
- 应用补丁后，自动回退到“并行编码”节点重新执行单测；
- 记录修复过程（失败原因、补丁内容、重试次数）到debug_log，支持后续追溯；
重试上限：默认重试3次，仍失败则触发“人机协同修复”（提示用户介入）。

技术依赖

基础组件：LangChain LLMChain（反射修复Prompt）、difftastic（补丁生成与合并）；
MCP工具：GameCodeGym-MCP（单测结果分析、reward评分）、Eval-Scope-MCP（编码质量评测）。

3.6 6. 人机协同审核（对应LangGraph「review」节点）

功能描述

在“发布前”插入人工审核节点，支持用户“确认通过”“拒绝并回退”“评论修改”，确保生成代码符合业务预期。

核心能力

审核内容展示：前端（Chainlit）展示“编码成果包预览”“单测报告”“修复日志”“架构图”，支持在线查看代码文件；
审核操作：
- 通过：进入发布阶段；
- 拒绝：选择回退节点（如“设计阶段”“编码阶段”），并填写拒绝原因（如“接口参数缺失”）；
- 评论：在具体代码行添加评论（如“这里需要增加日志打印”），Agent会优先处理评论中的修改需求；
响应时效：审核请求推送后，前端弹窗提醒，用户操作后Agent在2秒内响应。

技术依赖

基础组件：Chainlit前端、LangGraph条件分支（审核结果触发不同流向）；
存储：RedisChatMessageHistory（保存审核记录）。

3.7 7. 自动部署与发布（对应Hook「pre_publish」）

功能描述

审核通过后，自动将代码仓库推送到Git平台（如GitHub/GitLab），并生成部署配置（docker-compose.yml/helm/），支持一键启动服务。

核心能力

Git推送：调用Git API创建仓库（如“deepcode-research-demo”），推送代码文件、单测、文档；
部署配置生成：
- 生成docker-compose.yml（含服务依赖、端口映射、环境变量）；
- 生成Helm Chart（含Deployment、Service、HPA配置，支持CPU>70%或GPU>80%时自动扩缩容）；
发布通知：推送“发布成功”消息到用户（含Git仓库地址、部署命令），支持“一键复制”git clone命令。

技术依赖

基础组件：GitPython、Helm SDK；
MCP工具：ModelHub-MCP（推送代码到模型/数据集仓库）。

3.8 8. MCP工具集成（统一协议层）

功能描述

基于ModelScope MCP协议，统一集成“研究、设计、编码、评测、发布”全流程工具，支持工具热插拔（无需修改Agent核心代码）。

核心能力

工具管理：
- 配置化接入：在values.yaml中添加工具Endpoint（如tongyi-deepresearch: ${MCP_REGISTRY}/tongyi-deepresearch/mcp），即可完成集成；
- 认证支持：兼容APIKey、OAuth2、JWT三种认证方式，配置在mcp.yaml中；
工具调用：通过mcp.call(tool_name, params)统一调用，自动处理超时重试（默认重试2次，超时30秒）、限流（IP 100 req/min，用户1000 req/min）；
常用工具列表：

工具名称	功能	调用场景
Tongyi-DeepResearch-MCP	论文调研、技术趋势分析	研究阶段
Qwen3-VL-MCP	多模态文档解析（图片/流程图）	输入处理阶段
GameCodeGym-MCP	单测评测、reward评分	编码/修复阶段
Eval-Scope-MCP	代码质量评测（MBPP/HumanEval）	修复阶段
Wan2.5-Preview-MCP	架构图/时序图生成	设计阶段
ModelHub-MCP	许可证查询、代码仓库推送	设计/发布阶段

技术依赖

基础组件：ModelScope-Agent-MCP SDK（pip install modelscope-agent[mcp]）；
配置文件：mcp.yaml（工具Endpoint、认证、超时重试配置）。

3.9 9. 记忆管理（长短期统一）

功能描述

通过“向量存储+图存储+会话存储”实现长短期记忆管理，支持断点续跑、跨项目知识复用（复用率≥68%）。

核心能力

短期记忆：
- 会话存储：用RedisChatMessageHistory保存用户会话、审核记录、任务状态，支持“断点续跑”（如Agent重启后从上次失败节点继续）；
- 状态存储：用RedisSaver（LangGraph Checkpoint）保存AgentState（session_id/files/research/code等）；
长期记忆：
- 向量存储：用Chroma存储研究报告、设计方案的embedding，支持相似问题检索（如“历史订单模块设计”）；
- 图存储：用Neo4j存储“失败案例→修复方案”的关联关系（边权重=修复成功率），优先复用高成功率方案；
知识沉淀：自动将“修复日志、优质设计方案”转化为Few-shot样本，提升后续Agent决策质量。

技术依赖

基础组件：Redis、Chroma、Neo4j、LangGraph Checkpoint；
嵌入模型：BAAI/bge-small-zh（文本）、clip-ViT-B/32（图片）。

3.10 10. 可观测与Hook扩展

功能描述

提供全流程可观测能力，并支持通过Hook注入自定义逻辑（如私有知识库加载、安全审计），满足企业级扩展需求。

核心能力

可观测性：
- 日志追踪：集成LangSmith，记录“每个节点输入输出、工具调用参数、LLM响应”，支持按session_id回溯；
- 监控指标：通过Prometheus暴露“任务成功率、单测通过率、修复率、耗时”等指标，Grafana看板可视化；
- 告警：配置“任务超时（>30分钟）、修复失败（≥3次）”告警，支持邮件/钉钉推送；
Hook扩展：支持6大生命周期Hook，用户可注入自定义代码（如Python/Rust/TS）：

Hook名称	注入位置	用途示例
pre_plan	进入research前	加载企业私有知识库（如内部API文档）
post_plan	research→design	补充内部WebSearch结果
pre_exec	design→code	执行安全审计（如敏感信息检查）
post_exec	code→fix	上报评测数据到企业BI平台
on_error	fix内部循环	自动创建OPA策略（拦截相似错误）
pre_publish	review通过后	推送代码到企业私有Git仓库

技术依赖

基础组件：LangSmith、Prometheus、Grafana、OPA（Open Policy Agent）；
扩展机制：WASM（Hook代码编译为WASM，支持在线热更新）。

四、用户流程

4.1 主流程（正常链路）

graph TD
    A[用户上传多模态文档<br>（PDF/PPT/PNG）] --> B[多模态解析<br>（生成结构化Document）]
    B --> C[课程式研究<br>（生成研究报告）]
    C --> D[用户确认研究报告]
    D --> E[结构化设计<br>（生成架构图+目录）]
    E --> F[并行编码与沙箱执行<br>（8路并发，生成代码包）]
    F --> G[自我反思修复<br>（单测失败→生成补丁→重试）]
    G --> H[人工审核<br>（查看成果→确认通过）]
    H --> I[自动发布<br>（推Git+生成部署配置）]
    I --> J[用户接收发布通知<br>（Git地址+部署命令）]

4.2 关键分支流程

研究报告拒绝：用户拒绝研究报告→回退到“多模态解析”节点，重新上传文档或调整研究参数；
审核拒绝：用户拒绝编码成果→选择回退节点（如“设计阶段”）→修改设计方案后重新进入编码；
修复失败：重试3次仍未修复→触发“人机协同修复”→用户手动修改代码后，Agent继续执行后续流程。

五、非功能需求

需求类型	具体要求
性能	1. 单任务耗时：15页PDF→代码仓库≤11分钟，40页Word→微服务≤9分钟； 2. 并发能力：单卡A100-80G支持4路并发，P99≤18分钟，QPS≥1； 3. 响应速度：审核操作响应≤2秒，前端页面加载≤1秒。
可靠性	1. 任务成功率≥95%（不含人工拒绝场景）； 2. 断点续跑：Agent重启后可从上次失败节点继续，数据不丢失； 3. 失败重试：MCP工具调用失败自动重试2次，超时时间30秒。
安全性	1. 沙箱隔离：编码任务在Docker容器内执行，无主机权限； 2. 认证授权：MCP工具调用支持OAuth2/JWT，APIKey加密存储； 3. 数据安全：用户文档、代码包加密存储（AES-256），日志不含敏感信息。
可扩展性	1. 工具扩展：新增MCP工具耗时≤30分钟，支持热插拔； 2. 资源扩展：通过Helm HPA实现CPU/GPU自动扩缩容； 3. 功能扩展：Hook支持多语言（Python/Rust/TS），无需修改核心代码。
兼容性	1. 文档格式：支持PDF（1.7+）、PPTX、PNG、TXT、Word（.docx）； 2. 开发语言：支持Python（3.8-3.11）、Java（11-17）、Go（1.19+）； 3. 部署环境：支持Docker、K8s（1.24+）、Linux（CentOS 7+/Ubuntu 20.04+）。

六、交付物清单

交付物类型	具体内容
可执行脚手架	GitHub模板仓库（含Agent核心代码、配置文件、示例脚本），支持“一键fork”使用；
部署配置	1. `docker-compose.yml`（单机部署，含Redis/Chroma/Agent服务）； 2. Helm Chart（K8s部署，含HPA、Ingress、监控配置）； 3. 部署文档（含环境准备、启动命令、常见问题）。
监控组件	1. Prometheus配置文件（指标采集规则）； 2. Grafana看板JSON（任务状态、性能指标、工具调用统计）； 3. LangSmith项目配置（追踪规则、日志保留策略）。
文档与样例	1. 产品手册（用户操作指南）； 2. 技术文档（架构设计、MCP集成指南、Hook开发指南）； 3. 样例包（输入文档+预期输出代码仓库，支持离线验证）。
测试报告	1. 功能测试报告（覆盖所有核心模块，通过率100%）； 2. 性能测试报告（单任务耗时、并发能力、修复率）； 3. 安全测试报告（漏洞扫描、权限测试结果）。
前端组件	Chainlit前端代码（含文件上传、审核界面、日志展示、结果预览功能）。

七、验收标准

7.1 功能验收（逐项对标赛题评审维度）

评审维度	验收场景	合格标准
多模态理解	上传含“3张流程图+2个公式”的10页PDF，执行解析。	流程图内容解析准确率≥80%，公式转化为LaTeX准确率≥95%，无文本丢失。
深度研究	基于“微服务架构设计”PDF，触发研究环节。	生成3个技术方案对比表，引用≥3篇相关论文，技术选型理由明确。
代码生成	基于“用户管理微服务”PRD，生成代码仓库。	目录深度≥3，单测覆盖率≥80%，静态检查（pylint）无高危报错，支持`docker-compose up`启动。
自我反思	故意在设计中植入“单测断言错误”，观察修复流程。	Agent自动识别错误原因，生成正确补丁，重试后单测通过率≥90%。
人机协同	审核时选择“拒绝并回退到设计阶段”，填写原因“接口缺失token参数”。	Agent回退到设计阶段，修改接口定义后重新编码，最终生成含token参数的接口。
扩展性	新增“代码翻译MCP工具”，配置Endpoint后调用。	集成耗时≤30分钟，工具调用成功，返回正确的代码翻译结果。
工具协议	提供“代码扫描”OpenAPI文档，自动生成MCP stub。	生成的stub可正常调用，支持OAuth2认证，符合MCP协议规范。

7.2 性能验收

单任务耗时：在A100-80G环境下，15页PDF（含2张图表）→代码仓库耗时≤11分钟；
并发能力：同时提交4个不同任务（混合PDF/Word输入），P99耗时≤18分钟，无任务失败；
修复率：选取10个含单测失败的场景，Agent自动修复率≥75%。

7.3 交付物验收

所有交付物完整，无缺失（参考“交付物清单”）；
docker-compose up一键启动成功，前端可正常上传文件、执行任务；
样例包离线验证通过（输入样例文档，输出与预期代码仓库一致）。

八、核心约束与依赖

环境依赖：需GPU支持（最低NVIDIA V100，推荐A100-80G），内存≥64GB，存储≥100GB；
MCP依赖：需接入ModelScope MCP生态（需注册ModelScope账号，获取APIKey/OAuth2凭证）；
网络依赖：MCP工具调用需公网访问（或配置私有MCP-Registry）；
权限依赖：部署时需Docker/K8s权限，Git推送需仓库写入权限。

FilesExpand file tree

prd.md.md

Latest commit

History

prd.md.md

File metadata and controls

DeepCodeResearch-Agent 产品需求文档（PRD）

一、产品概述

1.1 产品定义

1.2 目标用户

1.3 解决的核心痛点

二、目标定位

2.1 业务目标

2.2 技术目标

三、核心功能模块

3.1 1. 多模态输入处理（对应LangChain Loader/Parser）

功能描述

核心能力

技术依赖

3.2 2. 课程式研究规划（对应LangGraph「research」节点）

功能描述

核心能力

技术依赖

3.3 3. 结构化设计生成（对应LangGraph「design」节点）

功能描述

核心能力

技术依赖

3.4 4. 并行编码与沙箱执行（对应LangGraph「code」节点）

功能描述

核心能力

技术依赖

3.5 5. 自我反思修复（对应LangGraph「fix」节点）

功能描述

核心能力

技术依赖

3.6 6. 人机协同审核（对应LangGraph「review」节点）

功能描述

核心能力

技术依赖

3.7 7. 自动部署与发布（对应Hook「pre_publish」）

功能描述

核心能力

技术依赖

3.8 8. MCP工具集成（统一协议层）

功能描述

核心能力

技术依赖

3.9 9. 记忆管理（长短期统一）

功能描述

核心能力

技术依赖

3.10 10. 可观测与Hook扩展

功能描述

核心能力

技术依赖

四、用户流程

4.1 主流程（正常链路）

4.2 关键分支流程

五、非功能需求

六、交付物清单

七、验收标准

7.1 功能验收（逐项对标赛题评审维度）

7.2 性能验收

7.3 交付物验收

八、核心约束与依赖