deepcode 详细指南

版本 2.1.0~2.1.0 ｜分类 session ｜安全（已审查）｜素材：项目官方文档（中文 README_ZH）+ 本市场实测（2026-08-27）
配套：站内文档（manifest + guide + 证据）｜快速版：站内文档

1. 场景：什么时候会用它

HKUDS（港大数据智能实验室）开源的 Agentic 编码框架（MIT，约 1.6 万星）：用多智能体系统推进代码生成，核心是 durable sessions / goals / verification——会话和目标是持久的，任务可以长跑、断点续跑。提供 TUI CLI 与 Desktop 两种界面，共享同一 Agent 运行时；原生支持 MCP、Skills、插件注册和论文复现（deepcode test <paper>）。

一句话：它自己就是一个"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 共享面。

2. 能力清单

能力	作用
论文复现	`deepcode test <paper>` / `--fast`（自带 eval/swebench 体系）
MCP	`deepcode mcp serve` 把 DeepCode 暴露为 MCP server；`deepcode mcp list	add	remove` 管理 MCP 客户端
Skills	`deepcode skill <command>` 管理与创建可复用技能
插件	`deepcode plugin <command>` 注册本地插件
自动化	`deepcode schedule` / `deepcode automation` 定时与常驻任务
多 Agent 编码	见 Agent 执行版 guide
持久会话/目标	见 Agent 执行版 guide

3. 快速安装

note: 本环境实测路径；国内网络用清华镜像分支

# 来源: Trove 详细指南 · 验证于 2026-08-28
pip install deepcode-hku --index-url https://pypi.tuna.tsinghua.edu.cn/simple
deepcode --version

预期输出: DeepCode 2.1.0

第 1 步：确认 CLI 与配置面

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
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 时任务会直接报错。

# 来源: Trove 详细指南 · 验证于 2026-08-28
deepcode exec "写一个 python 的 hello world 并运行" -w .

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

卡住怎么办：

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

安装变体

路径	命令	实测
主路径（实测）	`pip install deepcode-hku && deepcode --version`	✅ 本市场实测
镜像/代理	见快速版与 semi_auto_note；国内安装按 deepcode 指引	实测

半自动说明：实测命令 = pip 安装（清华镜像 --index-url，2026-08-27 本环境 venv 验证，deepcode 2.1.0，40.3s 全量依赖）；PyPI 官方当次 16s 边缘易超时，国内建议 --index-url https://pypi.tuna.tsinghua.edu.cn/simple（见指南安装段地区分支）；Python 3.12+；agent 跑通需先 deepcode init + deepcode provider 配置 LLM key

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。

4. 为什么会这样（机制与共享面）

它怎么工作：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 等配置与数据）。

实测命令 = pip 安装（清华镜像 --index-url，2026-08-27 本环境 venv 验证，deepcode 2.1.0，40.3s 全量依赖）；PyPI 官方当次 16s 边缘易超时，国内建议 --index-url https://pypi.tuna.tsinghua.edu.cn/simple（见指南安装段地区分支）；Python 3.12+；agent 跑通需先 deepcode init + deepcode provider 配置 LLM key

5. 常用操作

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

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
pip install deepcode-hku
deepcode --version

预期输出: DeepCode 2.1.0

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
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。

# 来源: Trove 详细指南 · 验证于 2026-08-28
deepcode init

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
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）。

# 来源: Trove 详细指南 · 验证于 2026-08-28
deepcode exec "写一个 python 的 hello world 并运行" -w .

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

装好确认：

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

卡住怎么办：

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

启动与入口

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

常用操作

操作一：查看命令清单

# 来源: Trove 详细指南 · 验证于 2026-08-28
deepcode --help

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

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
deepcode init

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

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
deepcode provider set openai --api-key <你的 key>

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

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
deepcode exec "写一个 python 的 hello world 并运行" -w .

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

数据与目录

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

6. 冲突逐条（摘要）

与工具页矩阵同源，共 19 对（7 实测兼容 / 12 推断可能兼容 / 0 推断可能冲突）；完整对子、状态与证据见冲突对子（共装矩阵）。

7. 排障速查

症状：pip 安装超时（PyPI 直连不稳）
症状：git clone 连接被重置（源码安装路径）
症状：curl 证书报错（--ssl-no-revoke）
症状：旧 Python 装不上（requires-python）
症状：MCP client 起不来（Brave MCP WinError 2 / npx 未跑起来）
症状：装完跑 agent 无响应（需 init + provider 配置）

四段式全文（症状→原因→解法→验证证据）：站内文档

8. 卸载与残留检查

# 来源: Trove 详细指南 · 验证于 2026-08-28
pip uninstall -y deepcode-hku || true

note: pip 方式卸载；配置目录 ~/.deepcode 为用户数据不自动删除；最后一行验证零残留

# 来源: Trove 详细指南 · 验证于 2026-08-28
pip uninstall -y deepcode-hku || true
command -v deepcode >/dev/null 2>&1 && echo "deepcode 仍存在" || echo "deepcode removed: OK"

预期输出: deepcode removed: OK

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
rm -rf ~/.deepcode

9. FAQ

运行环境预检（需 Python >= 3.12；输出包含 Python 版本号即通过）
官方形态 = pip 安装 PyPI 包 deepcode-hku（本环境实测通过）；最后一步为验证命令
每条操作 = 一个命令块 + 预期输出；init/provider 为首次使用必经步骤，exec/loop 需要 LLM provider
pip 方式卸载；配置目录 ~/.deepcode 为用户数据不自动删除；最后一行验证零残留
Python 必须 3.12+；预检在 3.14.4 上安装、init、help 全部通过

问：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 模板）；项目自身问题请向作者仓库反馈。

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

10. 出处

条目签名：HKUDS/DeepCode（MIT，原样收录 v2.1.0）

实测：实测记录（本地留存）（2026-08-27，CLI 冒烟：version/help/init）。
未实测：provider 配置与 exec 任务（无 API key）——命令来自 --help，如实标注；方式 B 源码安装（命令来自上游 README）。

外部教学（来源未实测）

第三方教学未逐条实测，仅供学习；有出入以本页与官方文档为准。

官方 README：Quick Start CLI（uv 安装 / init / provider 连接 / 进入仓库） [官方文档 · deepcode 官方 · 2026-08-30（v2.1.0 README）]
CLI 安装与初始化——`uv tool install --python 3.12 deepcode-hku`（要求 Python 3.12+，显式选版本避免回退旧包；uv 缺失时 Windows 用 winget 装 astral-sh.uv）→ `deepcode init`（建 ~/.deepcode/ 最小配置，凭据单独存用户私有存储，不进 Session 历史）→ `deepcode provider set <name> --template ... --api-key`（创建模型连接，--api-key 为非回显提示）→ `deepcode provider models <name> --refresh` → `deepcode provider test <name> --model <id>` → `cd <项目> && deepcode` 进入交互式 Agent；pipx/pip 安装同样支持（Python 3.12+）
官方 README：命令面与 Sessions（TUI 斜杠命令表） [官方文档 · deepcode 官方 · 2026-08-30（v2.1.0 README）]
`deepcode` 默认进交互式 TUI；斜杠命令表——/resume（会话恢复）、/model（改模型）、/effort（思考强度）、/permissions（工具权限）、/skill（技能）、/goal（持久目标）、/queue（排队指令）、/stop、/retry、/compact、/transcript、/rename、/delete；Session 单一写者（Desktop 与 CLI 同时持有互斥，拒绝时提示持有者）；存档隐藏不删历史
官方 README：Skills / Local Plugins / MCP（扩展能力三件套） [官方文档 · deepcode 官方 · 2026-08-30（v2.1.0 README）]
Skills——/skills 发现、/skill <name> 选择；项目技能 .agents/skills 随仓库走、用户技能 ~/.agents/skills 跨项目可用；$skill-creator 创建。Local Plugins——deepcode plugin add <path> 注册本地插件（Agent Plugins 1.0.0 清单 + 固定 skills/ 布局），不下载 Marketplace、不执行插件 hooks/Apps。MCP——deepcode mcp CLI（serve/list/presets/test/login/logout/enable/disable/add/remove），配置在 deepcode_config.json 顶层 mcpServers；stdio/SSE/Streamable HTTP 都支持

收录来源（已合并）

本页内容由多篇来源文章按哈希去重、实测验证、AI 重写后合并而来——来源不散落，全部挂在这一个页面上。

暂无已合并来源：本页为本地实测与多来源重写的沉淀；来源与验证细节见站内对应方案页。

← 返回 deepcode 方案页｜多智能体编排问题域