多智能体编排 · session · 验证于 2026-08-28 ✓ 实测验证

deepcode

已验证 2026-08-27安装 + 持久会话冒烟实测通过；开源 Agentic 编码框架，多智能体代码生成。

开源 Agentic 编码框架：多智能体并行生成与修复代码、持久会话与目标跟踪，适合想本地跑完整编码 Agent 的开发者

详细版 → 所属问题域：多智能体编排 遇到问题？去问题空间 →

你会遇到什么

这个工具解决什么问题：DeepCode 是一个多 Agent 编码框架：你把一个任务交给它（deepcode exec "..."），它内部用多个 Agent 分工完成，带持久会话与目标管理。适合「我想要一个能自主跑编码任务的框架」，而不是「我要给 Claude/Codex 装个插件」。 什么时候用：

  • 你要跑 headless 的编码任务（exec），由框架自己编排；
  • 你要用 session/loop/schedule/automation 做长期、周期性任务；
  • 你要用它的 mcp/skill/plugin 体系扩展能力。

什么时候别用：你的工作流已经固定在某个 IDE/Agent 上、只需要插件时——DeepCode 是独立框架，不是插件。 和相邻工具的边界：与 oh-my-claudecode / agent-governance-toolkit CLI 形态实测可共存（实测记录（本地留存）：三者互不干扰，无 ~/.claude.json 写入，venv 间无交叉）；DeepCode 无 Claude Code 插件形态，不涉及 ~/.claude.json 共享面。

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

它怎么工作：pip 包 deepcode-hku 提供 deepcode CLI。首次使用先 init 生成配置，再 provider set 配置 LLM provider（跑任务的前提），之后 exec "任务" -w 工作区 就能跑一个多 Agent 编码任务。能力面：init/test/mcp/skill/plugin/provider/session/exec/loop/schedule/automation。 关键概念：

  • provider：LLM 供应商（云端需 API key；本地 provider 不需要云 API key）；
  • session：持久会话，任务上下文跨次保留；
  • exec：headless 任务执行（需要 provider 已配置）。

装完它动哪里：~/.deepcode/（deepcode_config.json 等配置与数据）。

快速修复（不想看讲解，直接跑）

note: 本环境实测路径；国内网络用清华镜像分支
pip install deepcode-hku --index-url https://pypi.tuna.tsinghua.edu.cn/simple
deepcode --version

预期输出: DeepCode 2.1.0

一步步来

第 1 步：装主包（为什么优先清华镜像：官方源实测 16s 边缘，可能触发 pip 15s 读超时）

讲解：deepcode-hku 依赖较多，国内直连 PyPI 官方实测当次预检约 16s，处于 pip 默认 15s 读超时的边缘，容易装到一半失败。清华镜像实测 40s 全量依赖装完，是更稳的路径。装完 deepcode --version 验证。

pip install deepcode-hku
deepcode --version

预期输出: DeepCode 2.1.0

国内加速分支（推荐，实测成功）：

pip install deepcode-hku --index-url https://pypi.tuna.tsinghua.edu.cn/simple
deepcode --version

预期输出: DeepCode 2.1.0

装好确认：

  • deepcode --version 输出 DeepCode 2.1.0；
  • deepcode --help 能看到 init/test/mcp/skill/plugin/provider/session/exec/loop/schedule/automation。

卡住怎么办：

  • pip 超时/装不上 → 确认 Python >= 3.12；用清华镜像分支重装；
  • 命令找不到 → venv 场景先激活 venv，确认 pip 安装路径在 PATH；
  • 源码安装（方式 B，未实测） → git clone https://github.com/HKUDS/DeepCode.git && cd DeepCode && pip install -e . && deepcode --version（命令来自上游 README）。

第 2 步：初始化 + 配 provider（跑任务的前提）

讲解：deepcode init 幂等，生成 ~/.deepcode/deepcode_config.json。然后必须配一个 LLM provider——exec 类任务没有 provider 跑不起来。命令来自 --help，本环境未实测（无 API key），本地 provider 不需要云 API key。

deepcode init

预期输出: Initialized <home>/.deepcode/deepcode_config.json（已存在时提示使用 --force）

deepcode provider set openai --api-key <你的 key>

预期输出: provider 配置成功提示（本地 provider 不需要云 API key）

装好确认：

  • init 后配置文件存在；
  • provider set 后再次 --help 或任务前检查 provider 列表能看到已配置项。

卡住怎么办：

  • init 提示已存在 → 加 --force 重来（会覆盖配置，慎用）；
  • 跑任务报没有 provider → 回到本步补配置；本地 provider 不需要云 API key。

第 3 步：跑第一个编码任务（需先完成第 2 步）

讲解：deepcode exec "..." -w . 是 headless 任务入口，多 Agent 编码系统会自行拆解执行。命令来自 --help，本环境未实测（无 provider/key）。

deepcode exec "写一个 python 的 hello world 并运行" -w .

预期输出: headless 任务运行过程与最终结果（多 Agent 编码系统执行）

装好确认：

  • 任务正常结束且输出结果文件；
  • 工作区里出现任务产物。

卡住怎么办：

  • 提示 provider 缺失 → 回到第 2 步；
  • 任务中途失败 → 看日志定位（框架会输出执行过程），先确认工作区路径正确。

怎么确认修好了

第 1 步：确认 CLI 与配置面

讲解：deepcode --version 确认版本；deepcode init 后检查 ~/.deepcode/deepcode_config.json 存在，说明初始化链路通了。

deepcode --version
ls ~/.deepcode/deepcode_config.json 2>/dev/null && echo "config: OK" || echo "config: MISSING"

预期输出: DeepCode 2.1.0；config: OK

卡住怎么办：

  • config 缺失 → 跑 deepcode init（幂等，已存在时提示 --force）；
  • 命令找不到 → venv 场景先激活 venv，确认 pip 安装路径在 PATH。

第 2 步：确认任务链路（需先配 provider）

讲解：能跑通一个最小编码任务并看到结果文件，说明 provider + 工作区链路都正常；无 provider 时任务会直接报错。

deepcode exec "写一个 python 的 hello world 并运行" -w .

预期输出: headless 任务运行过程与最终结果（本环境无 API key 未实测，命令来自 --help）

卡住怎么办：

  • 提示 provider 缺失 → 回到「一步步来」第 2 步补 provider set；
  • 任务中途失败 → 看日志定位，先确认工作区路径正确。

其它环境的表现（常见变体）

  • Python 版本：要求 >= 3.12；依赖多，安装窗口大，国内务必用清华镜像分支。
  • Windows / macOS：pip 安装与初始化命令一致（仍建议镜像）；配置同样写 ~/.deepcode/。
  • venv / conda：命令找不到时先激活虚拟环境；卸载只删 pip 包，用户数据 ~/.deepcode/ 默认保留。
  • 源码安装（方式 B）：git clone + pip install -e .，本环境未实测，命令来自上游 README。
  • 与其它工具共装：与 oh-my-claudecode / agent-governance-toolkit CLI 形态实测共存（实测记录（本地留存）），不写 ~/.claude.json。

日常使用

启动与入口

CLI 直接调用，入口 deepcode --help；无常驻服务。

常用操作

操作一：查看命令清单

deepcode --help

预期输出: 以 Usage: 开头，含 init/test/mcp/skill/plugin/provider/session/exec/loop/schedule/automation

操作二：初始化配置（首次使用必经，幂等，本环境实测）

deepcode init

预期输出: Initialized <home>/.deepcode/deepcode_config.json（已存在时提示使用 --force）

操作三：配置 LLM provider（agent 跑通前提；命令来自 --help，本环境未实测——无 API key）

deepcode provider set openai --api-key <你的 key>

预期输出: provider 配置成功提示（本地 provider 不需要云 API key）

操作四：最小编码任务（需先完成操作三；命令来自 --help，本环境未实测）

deepcode exec "写一个 python 的 hello world 并运行" -w .

预期输出: headless 任务运行过程与最终结果（多 Agent 编码系统执行）

数据与目录

  • 配置：~/.deepcode/deepcode_config.json；
  • 会话/任务数据：~/.deepcode/ 下（默认）。

卸载与清理

note: pip 方式卸载；配置目录 ~/.deepcode 为用户数据不自动删除；最后一行验证零残留
pip uninstall -y deepcode-hku || true
command -v deepcode >/dev/null 2>&1 && echo "deepcode 仍存在" || echo "deepcode removed: OK"

预期输出: deepcode removed: OK

如需彻底清理（用户数据，默认保留）：

rm -rf ~/.deepcode

依赖警告

  • 版本：[2.1.0, 2.1.0] 锁定（收录实测版本）。
  • 环境：Python >= 3.12；依赖多，安装窗口大（建议镜像）。
  • 网络：PyPI 官方直连实测 16s 边缘（可能触发 15s 读超时），清华镜像 40s 全量成功。
  • 写面：~/.deepcode/（配置与数据）；不写 ~/.claude.json。
  • 共装：与 oh-my-claudecode / agent-governance-toolkit CLI 形态实测共存（实测记录（本地留存））。

FAQ（常见问题）

  • 问：pip 安装超时/装不上？答：确认 Python >= 3.12；国内网络用安装段方式 A 的国内分支命令（清华镜像实测 40s 成功）。
  • 问：deepcode 命令找不到？答：检查 venv 是否激活（venv 场景需在 venv 内执行安装与命令）；确认 pip 安装路径在 PATH。
  • 问：跑任务报没有 provider？答：先 deepcode init，再 deepcode provider set <厂商> --api-key <key>；本地 provider 不需要云 API key。
  • 问：和 oh-my-claudecode / agent-governance-toolkit 能一起装吗？答：CLI 模式实测可共存（见 实测记录（本地留存）：三者互不干扰，无 ~/.claude.json 写入，venv 间无交叉）；DeepCode 无 Claude Code 插件形态，不涉及 ~/.claude.json 共享面。
  • 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口（usage-report 模板）；项目自身问题请向作者仓库反馈。
验证证据
  • 实测：实测记录（本地留存）（2026-08-27，CLI 冒烟：version/help/init）；实测复现日志（2026-08-30）（venv + 清华源装 deepcode-hku 成功、--help 命令面核对、写面 ~/.deepcode 观察）。
  • 未实测：provider 配置与 exec 任务（无 API key）——命令来自 --help，如实标注；方式 B 源码安装（命令来自上游 README）。

引用：deepcode · 验证于 2026-08-28 · v2.1.0~2.1.0

相关问题（问题域）

出问题了？排障方案

排障手册：deepcode（L34 批次 1）

症状 → 原因 → 解法 → 验证证据 四段结构。
素材来源：L33 分源记录（CSDN/知乎/B站）+ 本市场实测（2026-08-27/28 隔离 venv 安装/卸载闭环 + 镜像对比）。
采集纪律：零账号匿名检索；不破解反爬；未碰 GitHub。check-words HARD 0。

基本信息

  • 条目名称：deepcode（HKUDS/DeepCode，MIT，v2.1.0 收录）
  • L33 分源信号：CSDN=5 / 掘金=0 / 知乎=1 / B站=1（中）
  • §14 角色：anchor；分类：session
  • 定位：开源 Agentic 编码框架——多智能体代码生成、持久会话与目标（论文复现）
  • 本市场安装路径：PyPI 包 deepcode-hku（CLI 名 deepcode），清华镜像加速
  • 主要安装形态：pip（PyPI）/ 源码（git clone）/ MCP server / TUI 交互

症状 → 原因 → 解法 → 验证证据

1. pip 安装超时（PyPI 直连不稳）

症状

pip install deepcode-hku 长时间卡住或报 timeout/连接错误。

原因

依赖树大（60+ 包，含 aiohttp/cryptography/pillow 等），PyPI 官方源在国内直连不稳定，容易中途超时。

解法

  1. 镜像源加速：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple deepcode-hku。
  2. 失败重试加长超时：--timeout 60。
  3. 隔离安装：python3 -m venv <dir> 后装进 venv，避免污染系统 Python（本市场实测方式）。

验证证据

  • 网页案例：CSDN（pip 超时 → 镜像源加速，2026-04）。
  • 本市场实测：清华镜像全量依赖 40.3s 成功；官方 PyPI 当次 16s 属边缘；闭环 2026-08-28 再次复测通过。

2. git clone 连接被重置（源码安装路径）

症状

git clone https://github.com/HKUDS/DeepCode.git 反复报连接被重置 / 超时。

原因

国内直连 GitHub 不稳定；本地配置了失效的 Git 代理也会导致重置。

解法

  1. 清代理：git config --global --unset http.proxy（与 https.proxy），或检查系统代理环境变量。
  2. 换网络/热点重试；错峰重试。
  3. 只想用工具：直接用 pip 安装（路径 1），不需要 clone 源码。

验证证据

  • 网页案例：CSDN（git clone 连接被重置 → 清 Git 代理/换热点，2026-06）。
  • 本市场实测：收录走 PyPI 路径（不需要 clone）；国内 GitHub 直连风险在连通性记录中标注。

3. curl 证书报错（--ssl-no-revoke）

症状

Windows 下用 curl 下载/安装相关脚本时报证书错误（SSL certificate problem / revocation 相关）。

原因

Windows 证书吊销检查（revocation）在部分网络/代理环境下失败；自签名或代理证书不被 curl 信任。

解法

  1. 安装脚本场景加 --ssl-no-revoke（Windows curl 参数）。
  2. 或改用 pip 路径安装（pip 的 truststore 处理证书更稳）。
  3. 建议在虚拟环境内操作，避免系统级改动。

验证证据

  • 网页案例：CSDN（curl 证书报错 → --ssl-no-revoke + 虚拟环境，2026-01）。
  • 本市场实测：Linux/WSL 环境无此问题；Windows curl 场景如实标注未实测。

4. 旧 Python 装不上（requires-python）

症状

Python 3.8 等旧版本 pip install deepcode-hku 报找不到匹配版本。

原因

包要求 Python >= 3.10（新版依赖如 pydantic 2.x 不支持 3.8）；pip 按 requires-python 过滤后无可用版本。

解法

  1. 升级 Python 到 3.10+（本市场实测 3.14.4 正常）。
  2. 多版本共存用 pyenv/conda 管理，不要动系统默认。

验证证据

  • 网页案例：CSDN（Python>=3.10，3.8 下载不了 deepcode 包，2025-08）。
  • 本市场实测：Python 3.14.4 安装成功（+ 闭环日志）。

5. MCP client 起不来（Brave MCP WinError 2 / npx 未跑起来）

症状

配置 MCP 客户端（如 Brave Search MCP）后 deepcode mcp 报 WinError 2 / 找不到命令；npx 没跑起来。

原因

MCP 客户端靠 npx/Node 环境启动；Node 不在 PATH、或 npx 首次下载超时都会导致启动失败。

解法

  1. 确认 Node/npx 可用：npx --version。
  2. 手动先跑一次 npx 预下载（npx -y <mcp包>），再配置到 deepcode。
  3. Windows 下注意 PATH 与 cmd 权限；服务类 MCP 用完整路径配置。

验证证据

  • 网页案例：CSDN（Brave MCP WinError 2 / npx 未跑起来，2026-01）。
  • 本市场实测：deepcode mcp 命令面存在；MCP client 实跑需 Node 生态与外部服务，未实测。

6. 装完跑 agent 无响应（需 init + provider 配置）

症状

deepcode 启动后交互无响应，或 agent 任务报错；deepcode loop/goal 不工作。

原因

首次使用需要初始化与 LLM 配置：deepcode init（生成 ~/.deepcode）+ deepcode provider 配置模型 key；没配 LLM 时 agent 链路空转。

解法

  1. deepcode init 初始化。
  2. deepcode provider 配置 LLM 连接与模型。
  3. 想无 key 快速验证：deepcode exec '简单任务' 看报错定位；或 deepcode --help 确认命令面。

验证证据

  • 本市场实测：--version/--help 正常；init/provider 属交互配置面，需 LLM key，未实测（manifest semi_auto_note 已标注）。

本市场实测安装 / 卸载（2026-08-28）

安装（manifest install.cmd，隔离 venv /tmp/l34-dc/venv，Python 3.14.4）：

# 来源: Trove 排障手册 · 验证于 2026-08-28
[install] pip install -i https://pypi.tuna.tsinghua.edu.cn/simple deepcode-hku && deepcode --version
依赖：aiohttp/cryptography/pillow/mcp/mcp-server-git/openai/anthropic/google-genai 等 60+ 包
DeepCode 2.1.0
[install] exit=0

卸载（manifest uninstall.cmd + verify）：

# 来源: Trove 排障手册 · 验证于 2026-08-28
[uninstall] pip uninstall -y deepcode-hku → Successfully uninstalled deepcode-hku-2.1.0
[uninstall] 验证: deepcode removed: OK（fresh shell，verify exit=0）
  • 完整日志：实测记录（本地留存）。
  • CLI 冒烟：实测记录（本地留存）（DeepCode 2.1.0；命令面完整）。
  • 共装实测：实测记录（本地留存）（omc/agt）+ coexist-herdr/logfire（2026-08-28）。
  • 未能实测：TUI 交互、MCP client 实跑、agent 任务（需 LLM key）。

冲突标注

  • possible-compatible（实测 CLI 面）：oh-my-claudecode / agent-governance-toolkit（实测记录（本地留存））；herdr / logfire 共装实测。
  • possible-compatible（推断态）：其余收录条目（矩阵对子）——deepcode 写面 = ~/.deepcode（可重定位 $DEEPCODE_HOME），无端口 daemon（MCP 按需）。
  • 注意：配置目录 ~/.deepcode 为用户数据，卸载不自动删除。

名称混淆

  • 三套名字：PyPI 包 deepcode-hku / CLI 命令 deepcode / 项目名 HKUDS/DeepCode——安装/卸载用包名，日常用命令名。
  • 与 DeepSeek（模型）、DeepCode（其它同名代码分析工具）区分：本项目 = HKUDS/DeepCode 开源 Agentic 编码框架。

判据（验证状态）

  • 症状清单：
  • [x] git clone 连接被重置 → 清 Git 代理/换热点（CSDN 2026-06；走 PyPI 路径规避）
  • [x] curl 证书报错 → --ssl-no-revoke + 虚拟环境（CSDN 2026-01；Windows 场景未实测）
  • [x] Python>=3.10（3.8 下载不了 deepcode 包）（CSDN 2025-08；3.14.4 实测）
  • [x] pip 超时 → 镜像源加速（CSDN 2026-04；清华镜像实测 40.3s）
  • [x] Brave MCP WinError 2 / npx 未跑起来（CSDN 2026-01；命令面确认，实跑未测）
  • [x] 装完 agent 无响应 → init + provider（manifest 配置面标注）
  • 实测步骤：
  • [x] 安装验证（manifest install.cmd：清华镜像 60+ 包 → DeepCode 2.1.0 exit 0）
  • [x] 卸载验证（manifest uninstall.cmd：pip uninstall → verify 零残留 exit 0）
  • [x] 网络/镜像场景（清华镜像 vs 官方 PyPI 对比；）
  • [x] 未能实测项：TUI 交互、MCP client 实跑、agent 任务（需 LLM key）

验收

  • [x] 症状 → 原因 → 解法 → 验证证据 四段齐全（6 症状）
  • [x] 名称混淆已点名（包名 deepcode-hku vs 命令 deepcode；与 DeepSeek/其它 DeepCode 区分）
  • [x] check-words HARD 0
  • [x] validate 通过
  • [x] 未碰 GitHub / 未用任何账号

所属组合包 （3）

  • combo-auto-test — 自动化测试闭环（静态分析 → 沙箱执行 → 浏览器 E2E）
  • combo-cicd-quality — CI/CD 质量门禁（swe-rex + deepcode + code-review-graph）
  • combo-memory-session — 单会话记忆治理栈（claude-mem + deepcode + code-review-graph）

矩阵暂无该工具对子。

← 返回工具货架 ｜ 遇到其它问题？去 问题空间 提交求助卡 ｜ 预检与证据记录由维护流程本地留存，仅公开结论与来源