BytesRouter

主题

LangChain 文档版本 跟随上游 源快照 4f706af4 更新于 2026-10-08

快速开始

安装 Deep Agents Code，运行你的第一个任务，并使用交互式或非交互模式

Deep Agents Code（dcode）是构建在 Deep Agents SDK 之上的终端编码智能体。本指南涵盖安装、你的第一个任务、日常交互使用、通过管道实现自动化，以及 LangSmith 追踪。功能概览请参见 Deep Agents Code 概览。config.toml 和服务商设置请参见配置。

安装并运行你的第一个任务

Install and launch

bash
curl -LsSf https://langch.in/dcode | bash

Add provider credentials

Deep Agents Code 可与任何支持工具调用的 LLM 配合使用。OpenAI、Anthropic 和 Google 开箱即用。

使用 /auth 命令连接服务商。完整列表和凭据详情请参见服务商。

NOTE

网页搜索使用 Tavily。用 /auth 添加密钥。参见启用网页搜索。

Give the agent a task

txt
Create a Python script that prints "Hello, World!"

智能体会解读查询，并在修改文件之前以 diff 形式提出变更供你批准。如有需要，它还可以运行 shell 命令来测试代码、检查文档，或搜索网络以获取最新信息。

Enable tracing (optional)

要在 LangSmith 中记录智能体操作、工具调用和决策，请运行 /auth 并添加你的 LangSmith API key。追踪会在下次启动时启用。

关于项目命名、高级选项以及 CI 或无头环境设置，请参见使用 LangSmith 追踪。

NOTE

Deep Agents Code 在 Windows 上未获得官方支持。Windows 用户可以尝试在 Windows Subsystem for Linux (WSL) 下运行它。

交互模式

像在聊天界面中一样自然地输入。 智能体会使用其内置工具、技能和记忆来协助你完成任务。

斜杠命令

可在 Deep Agents Code 会话中使用以下命令：

  • /model：切换模型或打开交互式模型选择器。
  • /effort：为当前模型设置推理强度。
  • /agents：在预配置的智能体之间热切换，无需重新启动。相关参数请参见命令参考。
  • /auth：管理已存储的模型服务商和服务（例如 Tavily 网页搜索）的 API key。详情请参见服务商凭据。
  • /goal <objective>：根据一个可衡量的目标起草验收标准。参见目标与评分标准。
  • /rubric：为评分设置明确的验收标准。参见目标与评分标准。
  • /remember [context]：回顾对话并更新记忆与技能。可选地传入额外上下文。
  • /skill:<name> [args]：按名称直接调用某个技能。该技能的 SKILL.md 指令会连同你提供的任何参数一起注入提示词。
  • /skill-creator [task]：创建高效智能体技能的指南。
  • /offload（别名 /compact）- 通过把消息连同摘要占位符卸载到存储中，释放上下文窗口空间。智能体在需要时可以从已卸载的文件中取回完整历史。
  • /context：打开按颜色编码的上下文窗口使用报告，包含模型容量、使用类别和剩余空间。
  • /context-doctor：审计注入到会话中的上下文及其预估 token 成本。参见审计注入的上下文。
  • /tools：列出当前智能体可用的内置工具和 MCP 工具。参见列出可用工具。
  • /extensions：列出已加载的 Python 扩展、其注册项及来源路径。需要 DEEPAGENTS_CODE_EXPERIMENTAL=1。
  • /cost：显示该线程的预估成本。参见跟踪线程成本。
  • /btw：就当前对话提出一个旁问，而不打断主任务。参见提出旁问。
  • /tokens：显示当前上下文窗口的 token 使用明细。
  • /clear：开始一个新线程。
  • /force-clear：用一个新线程恢复卡住的会话。
  • /copy：把最新的助手消息复制到剪贴板。
  • /prompts：搜索、预览、复制并复用之前提交过的提示词。
  • /threads：浏览并恢复之前的对话线程。
  • /mcp [login <server> | reconnect]：显示活跃的 MCP 服务器和工具。login <server> 为某个服务器运行 OAuth 流程；reconnect 加载延迟的登录。
  • /plugins：管理插件与市场。
  • /notifications：配置启动警告偏好。
  • /reload：无需重启即可重新读取 .env 文件、刷新配置并重新发现技能。这还会重新加载插件技能和 MCP 配置。对话状态会被保留。覆盖行为请参见 DEEPAGENTS_CODE_ 前缀。
  • /theme：打开交互式主题选择器以切换配色主题。提供内置主题以及任何用户自定义主题。
  • /scrollbar：显示或隐藏聊天滚动条。
  • /line-numbers：在新的 diff 中显示或隐藏相对于文件的行号。参见Diff 行号。
  • /update：就地检查并安装 Deep Agents Code 更新。它会检测你的安装方式（uv、Homebrew、pip）并运行相应的升级命令。
  • /auto-update：打开或关闭自动更新。
  • /install：安装一个可选集成。
  • /trace：在 LangSmith 中打开当前线程。
  • /editor：在外部编辑器（$VISUAL / $EDITOR）中打开当前提示词。参见外部编辑器。
  • /restart：重启智能体服务器。
  • /timestamps：切换消息时间戳页脚。
  • /changelog：在浏览器中打开 Deep Agents Code 更新日志。
  • /docs：在浏览器中打开文档。
  • /feedback：发送反馈或报告问题。
  • /version（别名 /about）- 显示已安装的 deepagents-code 和 SDK 版本。
  • /help：显示帮助和可用命令。
  • /quit：退出应用。
Shell 命令

输入 ! 进入 shell 模式，然后输入你的命令。

bash
git status
npm test
ls -la
键盘快捷键

通用

快捷键操作
Enter提交提示词
Shift+Enter、Ctrl+J、Alt+Enter 或 Ctrl+Enter插入换行
@filename自动补全文件并注入内容
@@query搜索最近的线程并插入线程引用
Shift+Tab循环切换审批模式
Ctrl+G在外部编辑器中打开提示词
Ctrl+T当存在子智能体面板时展开或折叠该面板
Ctrl+N当面板打开时查看待处理通知
Ctrl+O展开/折叠最近一次工具输出
Escape中断当前操作
Ctrl+C中断或退出
Ctrl+D退出

提示词中的文本编辑

聊天输入使用标准的 readline 风格按键绑定：

快捷键操作
Ctrl+A 或 Home将光标移到行首
Ctrl+E 或 End将光标移到行尾
Ctrl+U删除从光标到行首的内容
Ctrl+K删除从光标到行尾的内容
Ctrl+W 或 Ctrl+Backspace删除左侧的一个单词
Ctrl+Left / Ctrl+Right将光标向左/右移动一个单词

搜索提示词历史

提示词历史搜索让你无需离开聊天输入即可查找并复用之前提交的提示词。按 Ctrl+R 打开内联搜索，搜索存储在你机器上的提示词。

引用先前的线程

在聊天输入中输入 @@，即可按初始提示词、线程 ID、智能体、分支或工作目录搜索最近的线程。选择一个结果以插入 @@(thread:<thread-id>) 引用。当被引用对话的上下文与你的请求相关时，Deep Agents Code 可以检查它。

在 @@ 后添加文字以筛选结果。当建议列表打开时，按 Ctrl+R 可用相同的搜索条件浏览所有线程。在完整的线程选择器中，按 Ctrl+C 复制所选线程 ID。

NOTE

macOS Cmd+Left / Cmd+Right / Cmd+Delete

终端模拟器会在 Cmd 组合键到达正在运行的应用程序之前将其拦截，因此 Deep Agents Code 永远不会直接接收到它们。取而代之的是，终端会将其转换为上面的 readline 快捷键。

  • Ghostty： 开箱即用。默认情况下，Cmd+Left、Cmd+Right 和 Cmd+Delete 会被转换为 Ctrl+A、Ctrl+E 和 Ctrl+U。
  • iTerm2： 默认未绑定。在 Settings > Profiles > Keys > Key Mappings 下添加以下内容，类型为 Send Text with vim special chars：
    • Cmd+Left → \x01 (Ctrl+A)
    • Cmd+Right → \x05 (Ctrl+E)
    • Cmd+Delete → \x15 (Ctrl+U)
  • Terminal.app： 没有用于此重新映射的原生 UI。请直接使用基于 Ctrl 的快捷键。

按词移动（Option+Left / Option+Right）的处理方式相同：终端发送 Esc+b / Esc+f，Deep Agents Code 会将其解释为向左/向右移动一个单词。

检查上下文窗口用量

运行 /context 打开当前模型上下文窗口用量的彩色编码报告。该报告会显示模型的上下文上限、已用 token、剩余容量，并在可用时给出对话与系统提示词加工具之间的拆分。

服务商报告的总量与本地对话估算保持独立。当服务商总量不可用时，报告会将对话计数标记为估算值，并将总用量标记为不可用。若你希望在对话记录中获得文本摘要，请改用 /tokens。

当用量增长快于预期时，运行 /context-doctor 将 token 归属到每个注入的组件：基础系统提示词、记忆文件、技能索引、内置工具 schema 以及 MCP 工具 schema。要确认智能体当前可以调用哪些工具，请运行 /tools。要查看线程的实时成本估算，请运行 /cost；同一数字也会出现在状态栏中。参见诊断与审计会话。

外部编辑器

按 Ctrl+G 或输入 /editor，在外部编辑器中撰写提示词。Deep Agents Code 依次检查 $VISUAL、$EDITOR，然后回退到 vi（macOS/Linux）或 notepad（Windows）。GUI 编辑器（VS Code、Cursor、Zed 等）会自动收到 --wait 标志，因此 Deep Agents Code 会阻塞直到你关闭该文件。

bash
# Set in your shell profile (~/.zshrc, ~/.bashrc, etc.)
export VISUAL="code"    # GUI editor (--wait auto-injected)
export EDITOR="nvim"    # Terminal fallback

非交互模式与管道

使用 -n 可在不启动交互式 UI 的情况下运行单个任务：

bash
dcode -n "Write a Python script that prints hello world"

每次非交互式运行都会启动一个全新的线程——对话历史不会在多次调用之间延续。基于文件的状态（记忆、技能、配置）会持久保留。

你也可以通过 stdin 管道输入。当输入通过管道传入时，Deep Agents Code 会自动以非交互方式运行：

bash
echo "Explain this code" | dcode
cat error.log | dcode -n "What's causing this error?"
git diff | dcode -n "Review these changes"
git diff | dcode --skill code-review -n 'summarize changes'

当你将管道输入与 -n 或 -m 结合使用时，管道内容会出现在前面，随后是你传给该标志的文本。

NOTE

管道输入的最大大小为 10 MiB。

在非交互模式下，shell 执行默认处于禁用状态。使用 -S/--shell-allow-list 启用特定命令（例如 -S "pytest,git,make"），使用 recommended 获得安全的默认值，或使用 all 允许任何命令。

限制回合数

CI/CD 流水线中长时间运行或行为异常的智能体可能会无限循环。--max-turns N 为运维人员提供了一个硬性上限，而无需改动 SDK 内部：

bash
dcode -n "fix the failing tests" --max-turns 10

N 必须是正整数，并会覆盖原本用于限制失控循环的内部安全默认值。超出预算时退出码为 124（与 GNU timeout 一致），因此 CI 可以将预算超限与一般性失败区分开来。需要 -n 或管道传入的 stdin；否则退出码为 2。

若要用基于时间的限制替代（或附加于）回合数限制，参见用 --timeout 限制实际耗时。

限制实际耗时

--timeout SECONDS 会对非交互式运行施加硬性的实际耗时限制。它以基于时间的预算补充 --max-turns（回合数）——先触及哪个限制就先取消智能体。

bash
# Fail fast in CI if the task takes more than 2 minutes
dcode -n "run the test suite and summarise failures" --timeout 120

# Combine with --max-turns—whichever limit is hit first stops the agent
dcode -n "refactor auth module" --timeout 300 --max-turns 20

到期时智能体会被取消，进程退出码为 124，与 --max-turns 使用的退出码相同，因此 CI 可以统一处理这两种预算超限。需要 -n 或管道传入的 stdin；否则退出码为 2。

干净的输出与缓冲

使用 -q 获得适合管道传入其他命令的干净输出，使用 --no-stream 在写入 stdout 之前缓冲完整响应（而不是流式输出）：

bash
dcode -n "Generate a .gitignore for Python" -q > .gitignore
dcode -n "List dependencies" -q --no-stream | sort

在非交互模式下，会指示智能体做出合理假设并自主推进，而不是提出澄清性问题。它还偏好非交互式的命令变体（例如 npm init -y、apt-get install -y）。

Shell 执行示例
bash
# Allow specific commands (validated against the list)
dcode -n "Run the tests and fix failures" -S "pytest,git,make"

# Use the curated safe-command list
dcode -n "Build the project" -S recommended

# Allow any shell command
dcode -n "Fix the build" -S all

WARNING

请谨慎使用。

-S all（或 --shell-allow-list all）允许智能体在无人工确认的情况下执行任意 shell 命令。

使用 LangSmith 追踪

启用 LangSmith 追踪，以在 LangSmith 项目中查看智能体操作、工具调用和决策。

运行 /auth 并添加你的 LangSmith API 密钥。追踪会在下次启动时启用，并在各会话间持久保留。有关凭据管理器的详细信息，参见服务商凭据。

要自定义项目名称，或在没有 TUI 的情况下配置追踪，请将键添加到 ~/.deepagents/.env，这样无需逐 shell 导出即可在每个会话中启用追踪：

bash
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_...
DEEPAGENTS_CODE_LANGSMITH_PROJECT=deepagents-code  # Project for Deep Agents Code's own traces; defaults to "deepagents-code"

使用 DEEPAGENTS_CODE_LANGSMITH_PROJECT 命名接收 Deep Agents Code 自身追踪的项目。它的作用域仅限于 Deep Agents Code，因此不受项目 .env 中设置的 LANGSMITH_PROJECT 影响（后者会路由该项目的应用程序追踪；参见下文将智能体追踪与应用追踪分离）。

要为特定的工作目录覆盖该项目，请将 DEEPAGENTS_CODE_LANGSMITH_PROJECT 添加到该目录下的 .env 中。有关完整的加载顺序，参见环境变量。

对于 CI、无头运行或临时覆盖，请改为设置 shell 环境变量。Shell 导出始终优先于 .env 中的值：

bash
export LANGSMITH_TRACING=false
将智能体追踪与应用追踪分离

Deep Agents Code 可以产生两种 LangSmith 追踪：

  • Agent traces 是 Deep Agents Code 自身的模型调用、工具调用、编排和中间件。
  • Shell-command traces 是 Deep Agents Code 在 shell 中为你运行的代码所发出的追踪，例如测试、脚本或本地的 LangGraph 应用。

要将 Deep Agents Code 自身的追踪发送到专用项目，请设置 DEEPAGENTS_CODE_LANGSMITH_PROJECT：

bash
# Example value; use any LangSmith project name you want.
DEEPAGENTS_CODE_LANGSMITH_PROJECT=deepagents-code

然后为你的应用程序追踪配置 LANGSMITH_PROJECT：

bash
LANGSMITH_PROJECT=customer-support-agent

例如，假设你让 Deep Agents Code 调试一个失败的 LangGraph 测试：

bash
uv run pytest tests/test_escalation_flow.py

如果该测试在启用 LangSmith 追踪的情况下运行你的应用，那么这些应用追踪由 shell 进程创建，并会被发送到 customer-support-agent。Deep Agents Code 自身的推理和工具使用追踪则会发送到 deepagents-code。

你还可以使用 DEEPAGENTS_CODE_ 前缀将 LangSmith 凭据限定到 Deep Agents Code（例如 DEEPAGENTS_CODE_LANGSMITH_API_KEY）。

将追踪双重写入第二个项目

要将智能体追踪镜像到第二个 LangSmith 项目，请设置 DEEPAGENTS_CODE_LANGSMITH_REPLICA_PROJECTS。这对于将相同的追踪同时发送到个人项目和共享团队项目很有用。

bash
DEEPAGENTS_CODE_LANGSMITH_REPLICA_PROJECTS=team-shared

当设置了该变量且追踪处于活动状态时，每次智能体运行都会同时写入主项目（DEEPAGENTS_CODE_LANGSMITH_PROJECT，默认为 deepagents-code）和此处指定的项目。保持该变量未设置即可像往常一样只写入单个项目。

配置完成后，Deep Agents Code 会显示一行状态，其中包含指向 LangSmith 项目的链接。在支持的终端中，点击该链接即可直接打开。你也可以使用 /trace 打印该 URL 并在浏览器中打开。

sh
✓ LangSmith tracing: 'my-project'

TIP

我们还建议你设置 LangSmith Engine，它可以监控你的追踪、检测问题并提出修复建议。

另请参阅

友情链接

  • Agents.md面向 AI 编码助手的仓库说明文件规范
  • LangChainLangChain 是一个开放的Agent平台
  • LangSmithAgent 工程平台：可观测与评估、部署、Fleet、Engine 等
  • EmbabelEmbabel 是一个JVM平台Agent框架
  • SpringAISpringAI 是一个基于 Spring 的 AI 框架
  • MCPModel Context Protocol，连接 AI 应用与外部数据/工具的开放标准
  • LangChain4jJava 生态的 LLM 应用开发框架
  • LlamaIndex把数据接入 LLM 的框架与文档平台
  • LlamaParse智能体式 OCR 文档解析：把 PDF、扫描件变成 LLM 可用的文本与结构化数据
  • LiteParse本地优先、轻量的文档解析库，不需要 API key
  • CrewAI多智能体编排框架：以 Crew/Flow 组织自主协作的 AI Agent
  • MAFMicrosoft Agent Framework，企业级 .NET/Python 智能体框架

BytesRouter 是社区翻译站点，所有译文仅供参考，一切以官方英文原文为准。

© 2026 BytesRouter · 译文采用 CC BY 4.0 许可