Deep Code

Why this agent

Deep Code 是开源的终端 AI 编程助手,专为 DeepSeek-V4 模型家族适配,支持深度思考、推理强度 控制、Agent Skills,并原生支持 MCP(见 docs/mcp_en.md)。 配置文件 ~/.deepcode/settings.json,MCP 服务在 mcpServers.<name>.{ command, args, env} 字段里(标准 Claude-Code 形态)。这份配置文件 跟 Deep Code VS Code 扩展 共用。

Prerequisites

• 已装 Node.js 18+。
• Deep Code CLI 已装:npm install -g @vegamo/deepcode-cli; deepcode --version 能跑。
• espctl 已安装在磁盘上某个稳定位置。
• (可选,用于远程构建)Aegis 构建服务器地址 + MCP_AUTH_SECRET。

Install snippet (or alternative)

改 ~/.deepcode/settings.json,把 mcpServers 跟你现有的 DeepSeek 模型配置合到一起:

{
  "env": {
    "MODEL": "deepseek-v4-pro",
    "BASE_URL": "https://api.deepseek.com",
    "API_KEY": "sk-..."
  },
  "thinkingEnabled": true,
  "reasoningEffort": "max",
  "mcpServers": {
    "espctl": {
      "command": "/path/to/espctl",
      "args": ["mcp", "serve"],
      "env": {
        "CONTROL_BASE_URL": "https://esphome.cloud",
        "MCP_AUTH_SECRET": "your-access-key"
      }
    }
  }
}

替换:

• /path/to/espctl —— 你电脑上 espctl 的完整路径。
• CONTROL_BASE_URL —— 你的 Aegis 构建服务器地址。
• MCP_AUTH_SECRET —— 构建服务器给你的访问密钥。

或者只拿 mcpServers 块的预填片段:

读取 install://deep-code 资源。

First-run verification

cd /path/to/your/esp-idf/project
deepcode

进入 Deep Code 后:

/mcp

预期:/mcp 面板显示 espctl 服务 Connected,工具数 ~40。 工具按 Deep Code 命名约定暴露成 mcp__espctl__<tool_name>。

Troubleshooting

• /mcp 显示 espctl not connected —— 确认 /path/to/espctl 是绝对路径,且在你 shell 用户下可执行。Deep Code 不在 $PATH 里搜 stdio 命令路径。
• 工具列出来了但每次调用返回 “auth required” —— MCP_AUTH_SECRET 缺失或已失效。回到控制面重新签发一份访问密钥再填进配置。
• command 是 npx 时工具加载失败 —— Deep Code 对 npx 命令 自动加 -y。我们这边的 espctl 是直接调二进制,所以这条不适用; 从别的 MCP 文档手抄过来的话记得删掉显式 -y。
• VS Code 扩展和终端 CLI 行为不一致 —— 它们共用 ~/.deepcode/settings.json。CLI 改了,扩展下次 reload 时生效; 扩展改了,重启 deepcode。

Tested as-of 2026-05-19

Deep Code 特有注意事项

• Deep Code 专攻 DeepSeek-V4(用 deepseek-v4-pro / deepseek-v4-flash)。MCP 传输本身跟模型无关 —— BASE_URL 指向任意 OpenAI 兼容端点(比如火山方舟 Coding Plan),同一份 MCP 配置照常工作。
• Agent Skills 存放在 ~/.agents/skills/<name>/SKILL.md(用户级) 或 ./.deepcode/skills/<name>/SKILL.md(项目级)。Skills 和 MCP 工具是正交的,同一会话里两个 surface 都在。
• MCP 工具名 mcp__espctl__<tool> 是 Deep Code 特有(双下划线)。 其他 agent 用 mcp.espctl.<tool>(Hermes)或者完全没前缀(Claude Code)。