deepcode国内使用教程

deepcode国内使用教程

本文面向国内网络环境/国内模型接口的使用场景，整理了从 GitHub 克隆 DeepCode 后，为了“能跑起来 + 更稳定 + 更快写代码进文件”需要做的关键修改点与原因。

说明：本文不会写入任何真实 API Key，请按自己的密钥/代理环境替换。

1. 从 GitHub 获取代码

gitclone https://github.com/HKUDS/DeepCode.gitcdDeepCode

2. 运行环境准备（Windows 建议）

• Python：建议 3.10+（仓库 README 里写了 3.13，但国内环境常用 3.10/3.11 也可跑；以本机可装依赖为准）
• Node.js：用于 MCP 的npx/node运行（尤其是brave/filesystem这类 MCP server）
• （可选）uv：更快的 Python 环境/依赖管理

安装依赖（任选其一）：

pipinstall-r requirements.txt

或（如果你用 uv）：

uv venv uv pipinstall-r requirements.txt

3. 国内大模型配置（DeepSeek / OpenAI-Compatible）

DeepCode 的模型配置分两份文件：

• mcp_agent.secrets.yaml：放 API Key、base_url（敏感信息）
• mcp_agent.config.yaml：放默认 provider、默认模型、token 策略（非敏感）

3.1 配置mcp_agent.secrets.yaml

把里面的 key/base_url 按实际情况填好，示例（请替换占位符）：

openai:api_key:"你的Key"base_url:"https://api.deepseek.com"# 或你的 OpenAI-compatible 网关地址anthropic:api_key:""google:api_key:""

3.2 配置mcp_agent.config.yaml

推荐的国内可用配置如下（也可按需调整）：

• 选择 provider：llm_provider: "openai"（走 OpenAI-compatible）
• 选择模型：openai.default_model: "deepseek-chat"（示例）
• token 上限保护：把base_max_tokens / retry_max_tokens收敛到 8000，避免部分兼容接口返回Invalid max_tokens。

mcp_agent.config.yaml中应体现这套策略（重点行：llm_provider、openai.*）。

4. Windows 下 Brave MCP 报错（WinError 2）为什么不影响结果？如何处理？

如果日志里出现过：

• brave: Lifecycle task encountered an error: [WinError 2] 系统找不到指定的文件

原因通常是：Windows 环境下npx @modelcontextprotocol/server-brave-search没跑起来（Node 安装/全局包路径/权限/网络问题）。

4.1 为什么它不一定影响最终产出？

因为brave 搜索是“可选增强”能力：搜索失败时系统会继续执行（日志里常见Attempting to continue），后续核心的code-implementation仍然可以写文件，因此仍可能正常产出代码。

4.2 推荐处理方式（2选1）

方案A：不用 Brave，改用bocha-mcp（更适合国内）

1. 在mcp_agent.config.yaml里设置：

default_search_server:bocha-mcp

2. 在mcp_agent.config.yaml的bocha-mcp.env中填好BOCHA_API_KEY。

方案B：继续用 Brave，但用 Windows 的 node 绝对路径启动

在mcp_agent.config.yaml的brave段落里，把 Windows 相关的注释配置改成可用配置（示例）：

mcp:servers:brave:command:nodeargs:-C:/Users/<你>/AppData/Roaming/npm/node_modules/@modelcontextprotocol/server-brave-search/dist/index.jsenv:BRAVE_API_KEY:"你的BRAVE_API_KEY"

关键点：路径要以本机npm -g root输出为准。

5. 写代码进文件“越来越慢”的优化：启用批量写入

如果日志里大量出现单次write_file，每次都要走一次 LLM → tool call → 写盘，整体吞吐会偏低。

项目已加入“批量写入（一次写 2~5 个文件）”的加速改动，核心思路：

• 减少 LLM 往返次数
• 减少 MCP tool call 次数
• 一次性把同一模块/同一层级的多个文件写进去

5.1 涉及哪些文件（加速相关）

A) 让系统“知道可以批量写”

• config/mcp_tool_definitions.py
• config/mcp_tool_definitions_index.py

已启用：

• write_multiple_files（批量写入工具）

B) 让智能体“愿意批量写”

已在以下文件里加入“优先使用write_multiple_files”的提示与引导：

• prompts/code_prompts.py
• workflows/code_implementation_workflow.py
• workflows/code_implementation_workflow_index.py

效果：后续实现阶段会更倾向于一次写 2~5 个文件，通常能显著提升写入速度。

6. 启动方式（Web / CLI）

6.1 Web（Streamlit）

streamlit run ui/streamlit_app.py

6.2 CLI

python cli/main_cli.py

7. “从 GitHub 下载后，我到底需要改哪里？”一页清单

只想完成“最小可用改动”，按下面做：

• 必改（国内模型）

  • mcp_agent.secrets.yaml：填openai.api_key+openai.base_url（DeepSeek/网关地址）
  • mcp_agent.config.yaml：确认llm_provider: "openai"+openai.default_model合适

• 建议改（Windows 搜索可用/不报错）

  • 要么：default_search_server: bocha-mcp并填BOCHA_API_KEY
  • 要么：把braveMCP server 改成 Windows 下node + 绝对路径

• 可选（提速）

  • 如果已启用：write_multiple_files+ 对应提示词引导，则无需额外修改；否则按第5节启用。

8. 常见问题排查（速查）

• Q：为什么日志里有 ERROR 但还能继续？
  **A：**多智能体流程里有些阶段是可选增强（搜索/索引/结构生成）。失败会记录 error，但主流程会继续执行，尤其是代码写入不依赖这些服务时。

• Q：Windows 下 Brave 一直 WinError 2？
  **A：**优先用bocha-mcp；或按本文第4节用 node 绝对路径启动。

• Q：DeepSeek 报 max_tokens 之类参数错误？
  **A：**保持mcp_agent.config.yaml里base_max_tokens/retry_max_tokens在较小安全值（如 8000）并用max_tokens_policy: adaptive。