第 26 章

Deep Agents Code 总览

基于 Deep Agents SDK 构建的终端编码 Agent

从"手动写代码"到"AI 自主编程"的生产力飞跃

编码工具链短

你有没有试过让 AI 帮你写代码，却发现工具链不够用？

普通 AI 编码助手

  • 只能生成代码片段，不能读取和编辑项目文件
  • 无法运行测试或构建命令，没有执行能力
  • 对话一长就忘记之前说的，没有持久记忆
  • 复杂任务无法拆分，一个 Agent 搞定所有
  • 想换个模型？重启重来，不能中途切换

Deep Agents Code 的解法

  • 内置 read_file、write_file、edit_file，直接操作项目文件
  • 内置 execute 工具，运行测试、构建、部署一条龙
  • 跨会话持久记忆 + 技能系统，越用越聪明
  • 内置 task 工具生成子 Agent，并行处理复杂任务
  • 对话中随时 /model 切换，一个会话用多个模型
问题核心：当你的编码需求从"问一段代码"升级到"帮我完成一整个功能模块"时，你需要一个拥有完整工具链的自主编码 Agent。它能读文件、写文件、跑测试、查文档、管理依赖。Deep Agents Code 就是这样的 Agent。

开始之前

你需要会什么

  • 基本的命令行操作（cd、ls、cat 等）
  • 了解 LLM 的基本概念（prompt、token、tool calling）
  • 至少有一个 LLM API 密钥（OpenAI、Anthropic 或 Google）
  • 了解文件系统操作的基本概念

读完后你应该能

  • 安装并启动 Deep Agents Code
  • 理解 dcode 的核心能力和内置工具
  • 熟练使用交互模式的斜杠命令
  • 掌握非交互模式用于 CI/CD 集成
  • 配置 LangSmith 追踪进行调试

本章不会深入

  • 记忆与技能的详细配置（第 27 章）
  • 远程沙箱的具体使用（第 28 章）
  • 子 Agent 的高级编排（第 29 章）
  • 完整配置文件参考（第 31 章）
平台提示：Deep Agents Code 尚未正式支持 Windows。Windows 用户请在 WSL（Windows Subsystem for Linux） 下运行。

什么是 dcode

一个兼容任何 LLM、拥有持久记忆、可切换模型的终端编码 Agent

Deep Agents Code（dcode）是一个基于 Deep Agents SDK 构建的开源编码 Agent。它的核心特性是：

兼容任意 LLM

只要支持 tool calling，就能用。OpenAI、Anthropic、Google 默认内置，Ollama、Groq、xAI 等可选安装。

跨会话持久记忆

保留对话中学到的内容，下次启动时仍然记得你的项目约定和偏好。

可自定义技能

通过 Skills 系统扩展 Agent 能力——添加专业知识、工作流指令或自定义行为。

审批控制

敏感操作（写文件、执行命令）默认需要人工确认，安全可控。

# 脚本安装（推荐）
curl -LsSf https://langch.in/dcode | bash

# 或使用 uv 安装
uv tool install 'deepagents-code'

# 启动
dcode
可选附加组件：如果需要额外提供商（如 Fireworks、Nvidia），安装时指定： DEEPAGENTS_CODE_EXTRAS="fireworks,nvidia" curl -LsSf https://langch.in/dcode | bash 或 uv tool install 'deepagents-code[fireworks,nvidia]'

快速上手

四步从安装到运行——给 Agent 分配你的第一个任务

1. 安装并启动

curl 安装，一行命令搞定

2. 添加凭证

/auth 设置 API 密钥

3. 分配任务

自然语言描述需求

4. 审查确认

Agent 以 diff 展示更改

# 启动后，添加提供商凭证
dcode
> /auth    # 交互式引导设置 API 密钥（OpenAI、Anthropic 等）

# 给 Agent 分配任务——用自然语言描述即可
> Create a Python script that prints "Hello, World!"

# Agent 会自动：理解意图 → 调用工具生成文件 → 以 diff 展示更改 → 等待你确认
# 如果需要，它会调用 execute 工具运行 shell 命令测试代码
# 或调用 web_search 工具搜索网络获取最新信息
网络搜索：使用 Tavily 搜索。如果你看到 "Web search disabled" 提示，将 TAVILY_API_KEY=tvly-... 添加到 ~/.deepagents/.env，然后运行 /reload。

核心能力

dcode 内置了丰富的能力——文件、Shell、搜索、记忆、子 Agent 一应俱全

文件操作

读取、写入和编辑文件，Agent 能管理和修改代码与文档。

read / write / edit

Shell 执行

运行命令来执行测试、构建项目、管理依赖和版本控制。

execute

远程沙箱

在 LangSmith、Daytona、Modal 等平台运行工具，而非本地。

--sandbox

网络搜索

搜索网络获取最新信息和文档，基于 Tavily API。

web_search

子 Agent

用 task 工具委派工作，并行处理复杂任务。

task

持久记忆

跨会话存储和检索信息，记住项目约定和学到的模式。

memory

其他能力：HTTP 请求（fetch_url）、任务规划与跟踪（write_todos）、上下文压缩（compact_conversation）、人在回路审批、可自定义技能、MCP 工具加载、LangSmith 追踪。
图：dcode 六大核心能力架构

内置工具

dcode 附带的完整工具集——无需配置即可使用

工具描述审批要求
ls 列出文件和目录 不需要
read_file 读取文件内容（特定模型支持多模态） 不需要
write_file 创建或覆盖文件 必需
edit_file 对现有文件进行针对性编辑 必需
glob 查找匹配模式的文件 不需要
grep 跨文件搜索文本模式 不需要
execute 在本地或远程沙箱中执行 shell 命令 必需
web_search 使用 Tavily 搜索网络 必需
fetch_url 获取网页并转换为 markdown 必需
task 将工作委派给子 Agent 并行执行 必需
ask_user 向用户提出开放式或多选问题 不需要
compact_conversation 总结较早消息，将原始内容卸载到存储，在上下文中替换为摘要 混合
write_todos 创建和管理任务列表 不需要
跳过人工审批：使用 dcode -y 或 dcode --auto-approve 自动审批所有工具调用。交互模式中可用 Shift+Tab 切换。

上下文压缩

长对话自动压缩，上下文窗口永不溢出

dcode 内置 compact_conversation 机制，当 token 使用量超过阈值时自动触发：

压缩前

  • 对话越来越长，token 开销持续增长
  • 早期对话的完整内容占据大量上下文空间
  • 最终可能触及模型上下文窗口上限

压缩后

  • 较早的消息被 LLM 自动摘要
  • 原始内容卸载到 /conversation_history/{thread_id}.md
  • 上下文中替换为摘要占位符，释放窗口空间
  • Agent 仍可从卸载文件中检索完整历史
# 手动触发上下文压缩（在交互模式中）
> /offload     # 别名：/compact，将较早消息总结并卸载

# 或让 Agent 在 token 使用量超过阈值时自动触发 compact_conversation 工具
# 压缩流程：LLM 总结较早消息 → 原始内容写入文件 → 上下文中替换为摘要
# 这样即使对话很长，Agent 仍有足够的上下文窗口处理当前任务
核心机制：压缩过程通过 LLM 总结较早消息，将原始内容弹出至存储。这确保了长时间会话中 Agent 始终有足够的上下文窗口来处理当前任务。
图：长对话自动压缩机制

命令行选项

dcode 提供丰富的命令行参数——从模型选择到沙箱配置

选项说明
-a NAME使用具名 Agent 及其独立记忆
-M MODEL使用特定模型（provider:model）
--model-params JSON传递给模型的额外参数（如 '{"temperature": 0.7}'）
--default-model [MODEL]设置默认模型
--clear-default-model清除默认模型
-r [ID]恢复会话（不传 ID 恢复最近）
-m TEXT启动时自动提交的初始提示
--skill NAME启动时调用技能
--startup-cmd CMD第一个提示之前运行的 shell 命令
-y自动审批所有工具调用（禁用人在回路）
-q / --quiet干净输出，仅输出 Agent 响应（适合管道）
--no-stream缓冲完整响应后一次性输出（非流式）
--stdin显式从 stdin 读取输入
选项说明
-n TEXT非交互模式，运行后退出
-S LISTShell 命令白名单（逗号分隔 / recommended / all）
--max-turns N限制 Agent 轮次（超出以代码 124 退出）
--sandbox TYPE远程沙箱类型
--sandbox-id ID复用现有沙箱
--sandbox-setup PATH沙箱创建后运行的设置脚本路径
--mcp-config PATH添加 MCP 配置（最高优先级）
--no-mcp禁用所有 MCP 工具加载
--trust-project-mcp信任项目级 MCP 配置（跳过审批）
--profile-override JSON覆盖模型配置文件字段
--acp作为 ACP 服务器通过 stdio 运行
--json管理子命令输出机器可读 JSON
-v / --version显示版本号
-h / --help显示帮助
 
# 常见用法
dcode --agent mybot                    # 使用特定 Agent
dcode --model anthropic:claude-opus-4-7  # 使用特定模型
dcode -y                               # 自动审批
dcode --startup-cmd "ls -la" -m "Summarize"  # 启动时先运行命令
dcode --startup-cmd "git diff --stat" -n "Review these changes"  # 非交互

管理命令

dcode 的管理子命令——Agent、技能、会话管理

Agent 管理

命令说明
dcode agents list列出所有 Agent
dcode agents reset --agent NAME清除 Agent 记忆并重置
dcode agents reset --agent NAME --target SOURCE从另一个 Agent 复制记忆

技能管理

命令说明
dcode skills list列出所有技能
dcode skills create NAME创建新技能（SKILL.md 模板）
dcode skills info NAME显示技能详情
dcode skills delete NAME删除技能

会话管理

命令说明
dcode threads list列出会话（默认 20 条）
dcode threads delete ID删除指定会话
dcode mcp login NAMEMCP OAuth 登录
dcode update检查并安装更新
安全机制：破坏性命令（agents reset、skills delete、threads delete）支持 --dry-run 预览操作而不实际执行。所有管理子命令支持 --json 获取机器可读输出。

配置结构

所有配置统一存储在 ~/.deepagents/ 目录下

路径用途
~/.deepagents/config.toml 模型和 Agent 默认设置、提供商配置、主题、更新设置
~/.deepagents/.env 全局 API 密钥和密钥（如 OPENAI_API_KEY）
~/.deepagents/hooks.json 生命周期事件钩子（会话开始/结束、任务完成等）
~/.deepagents/<agent_name>/ 每个 Agent 的记忆、技能和对话线程
.deepagents/（项目根目录） 项目特定的记忆和技能，在 git 仓库内运行时加载 
# 列出所有已配置的 Agent
dcode agents list

# 添加 API 密钥
# 方式一：交互模式中使用 /auth
dcode
> /auth

# 方式二：直接写入 .env 文件
echo "OPENAI_API_KEY=sk-..." >> ~/.deepagents/.env
配置详情：完整的 config.toml 结构、提供商参数、配置文件覆盖和钩子配置，请参阅 第 31 章：配置参考。
图：配置文件目录层级

交互模式

像聊天一样使用——斜杠命令是提升效率的关键

常用斜杠命令

命令说明
/model切换模型或打开选择器
/auth管理 API 密钥
/agents热切换 Agent
/remember回顾并更新记忆
/offload压缩对话释放上下文（别名 /compact）
/tokens查看 token 使用量
/clear清除对话开启新线程

工具与调试命令

命令说明
/threads浏览和恢复历史对话
/mcp显示活跃 MCP 服务器
/reload重载配置和技能
/trace在 LangSmith 打开追踪
/theme切换颜色主题
/update检查并安装更新
/auto-update开启或关闭自动更新
/skill:NAME直接调用技能
/skill-creator创建新技能的向导
/editor在外部编辑器中打开当前提示
/changelog在浏览器中打开更新日志
/docs在浏览器中打开文档
/feedback打开 GitHub Issues 提交反馈
/version显示已安装版本号
/help显示帮助和可用命令
/quit退出 Deep Agents Code
效率技巧：使用 @filename 自动补全文件并注入内容；使用 /skill:NAME 按名称调用技能并传入参数；使用 /skill-creator 向导创建新技能。

Shell 与快捷键

Shell 模式和键盘快捷键——高效操控你的编码 Agent

Shell 模式

输入 ! 进入 shell 模式，然后输入命令：

! git status
! npm test
! ls -la

命令在 Agent 环境外独立执行，适合快速检查项目状态。

键盘快捷键

快捷键操作
Enter提交提示
Shift+Enter / Ctrl+J / Alt+Enter / Ctrl+Enter插入换行
Ctrl+A选择输入框中的所有文本
@filename自动补全文件并注入内容
Shift+Tab / Ctrl+T切换自动审批
Ctrl+U删除至行首
Ctrl+X在外部编辑器中打开提示
Ctrl+O展开/折叠最近的工具输出
Escape中断当前操作
Ctrl+C中断或退出
Ctrl+D退出
外部编辑器：设置 $VISUAL 或 $EDITOR 环境变量后，Ctrl+X 会在外部编辑器中打开当前提示，适合编辑长文本。

非交互模式

CI/CD 管道中的编码 Agent——单次运行，自动退出

交互模式

  • 启动 UI，持续对话
  • 人工审批敏感操作
  • 随时切换模型、Agent
  • 适合日常开发

非交互模式

  • -n 运行单个任务后退出
  • Shell 执行默认禁用
  • 使用 -S 白名单启用命令
  • 适合 CI/CD、脚本、自动化
# 基本非交互用法：-n 指定任务，运行完自动退出
dcode -n "Write a Python script that prints hello world"

# 管道输入：stdin 内容自动注入为上下文（自动进入非交互模式）
echo "Explain this code" | dcode
git diff | dcode -n "Review these changes"       # 让 Agent 审查代码差异
cat error.log | dcode -n "What's causing this error?"  # 分析错误日志

# 限制轮次防止 Agent 陷入无限循环（CI/CD 中强烈推荐）
dcode -n "fix the failing tests" --max-turns 10

# 干净输出 + 缓冲模式（适合管道处理和脚本集成）
dcode -n "Generate a .gitignore" -q > .gitignore        # -q 仅输出结果
dcode -n "List dependencies" -q --no-stream | sort       # --no-stream 等完整响应后输出
管道输入限制：最大大小为 10 MiB。非交互模式下 Agent 被指示自主推进而非提出澄清问题，倾向使用非交互式命令变体（如 npm init -y）。

Shell 白名单

在非交互模式中精确控制 Agent 能执行哪些命令

指定命令列表

只允许特定命令，按列表严格验证。

dcode -n "Run tests" -S "pytest,git,make"

推荐安全列表

使用 recommended 获取策划的安全命令集合。

dcode -n "Build project" -S recommended

允许所有命令

all 允许任意 shell 命令——请谨慎使用。

dcode -n "Fix the build" -S all
安全警告：-S all 允许 Agent 在无需人工确认的情况下执行任意 shell 命令。仅在你完全信任任务和环境的场景下使用。
环境变量方式：你也可以通过 DEEPAGENTS_CODE_SHELL_ALLOW_LIST 环境变量设置白名单，适合在 CI/CD 中统一配置。

LangSmith 追踪

启用追踪后在 LangSmith 中查看 Agent 的每一步操作和决策

# 方式一：写入 .env 文件（推荐，每次会话自动启用）
cat >> ~/.deepagents/.env << 'EOF'
LANGSMITH_TRACING=true                    # 开启追踪
LANGSMITH_API_KEY=lsv2_...               # LangSmith API 密钥
LANGSMITH_PROJECT=optional-project-name  # 项目名称，默认 "deepagents-code"
EOF

# 方式二：shell 环境变量（适合临时覆盖或 CI/CD）
export LANGSMITH_TRACING=false

# 配置后，dcode 启动时会显示追踪状态
# ✓ LangSmith tracing: 'my-project'

项目级覆盖

在项目目录的 .env 文件中设置相同变量，可覆盖全局设置。Shell 导出始终优先于 .env 值。

分离追踪

使用 DEEPAGENTS_CODE_LANGSMITH_PROJECT 将 dcode 追踪发送到专用项目，与应用追踪分离。也可用 DEEPAGENTS_CODE_ 前缀限定所有凭证。

# 将 dcode 的追踪发送到专用项目（与父应用追踪分离）
DEEPAGENTS_CODE_LANGSMITH_PROJECT=my-deep-agent-execution

# 父应用的追踪使用独立项目
LANGSMITH_PROJECT=my-app-traces

# 也可用 DEEPAGENTS_CODE_ 前缀限定凭证，避免与父应用凭证冲突
DEEPAGENTS_CODE_LANGSMITH_API_KEY=lsv2_...
典型场景：当你在 LangChain 应用中以编程方式调用 dcode（如非交互模式子进程）时，应用和 dcode 都会产生追踪。通过 DEEPAGENTS_CODE_LANGSMITH_PROJECT 将 Agent 追踪路由到独立项目，既保持应用级可观测性整洁，又能捕获 Agent 内部执行细节。
快速查看追踪：使用 /trace 命令在浏览器中打开当前线程的追踪。dcode 启动后会显示指向 LangSmith 项目的链接，支持的终端可直接点击。

本章回顾

到这里，你已经掌握了 Deep Agents Code 的全貌

你学到了什么

  • Deep Agents Code 是一个终端编码 Agent，兼容任意支持 tool calling 的 LLM
  • 内置12 个工具：文件操作、Shell 执行、网络搜索、子 Agent 等
  • 两种运行模式：交互模式（日常开发）和非交互模式（CI/CD）
  • 持久记忆 + 技能系统，跨会话保持上下文
  • 上下文自动压缩，长对话不爆窗口
  • LangSmith 追踪提供完整的可观测性

后续章节预告

  • 记忆与技能（第 27 章）：深入理解记忆存储和技能创建
  • 远程沙箱（第 28 章）：在云端运行 Agent 工具
  • 子 Agent（第 29 章）：并行任务委派的高级用法
  • 提供商（第 30 章）：配置 Ollama、Groq 等额外模型
  • 配置参考（第 31 章）：config.toml 的完整结构
  • MCP 工具（第 32 章）：集成外部工具服务器
核心结论：dcode 不只是"代码补全"——它是一个拥有完整工具链、持久记忆、上下文管理和安全控制的自主编码 Agent。从日常开发到 CI/CD 自动化，都能胜任。

延伸阅读

继续本课程

官方资源

相关章节