LangChain 中文文档

外观

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

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

安装并启动 ​

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

添加提供商凭据 ​

    Deep Agents Code 适用于任何支持工具调用的大语言模型。OpenAI、Anthropic 和 Google 开箱即用。

    使用 `/auth` 命令连接提供商。完整列表与凭据详情请参见 [提供商](/oss/deepagents/code/providers)。

INFO

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

给智能体一个任务 ​

txt
Create a Python script that prints "Hello, World!"
    智能体理解你的请求，并会在修改文件前以 diff 形式提出修改建议供你审批。如有需要，它还可以运行 shell 命令来测试代码、查阅文档或搜索网络以获取最新信息。

启用追踪（可选） ​

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

    关于项目命名、高级选项以及 CI 或无头（headless）环境配置，参见 [使用 LangSmith 追踪](#trace-with-langsmith)。

INFO

Deep Agents Code 官方不支持在 Windows 上运行。Windows 用户可以尝试在 适用于 Linux 的 Windows 子系统 (WSL) 下运行。

交互式模式 ​

像在聊天界面中一样自然输入即可。 智能体使用其内置的工具、技能与记忆来帮助你完成任务。

斜杠命令 ​

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

    - `/model`：切换模型，或打开交互式模型选择器。
    - `/effort`：设置当前模型的推理努力程度（reasoning effort）。
    - `/agents`：无需重启即可在预配置的智能体之间热切换。相关标志请参见 [命令参考](/oss/deepagents/code/cli-reference#command-line-options)。
    - `/auth`：管理模型提供商与服务（例如 Tavily 网络搜索）的已存储 API 密钥。详情参见 [提供商凭据](/oss/deepagents/code/credentials)。
    - `/goal <objective>`：根据可量化的目标起草验收标准。参见 [目标与评分标准](/oss/deepagents/code/goals-and-rubrics)。
    - `/rubric`：设置明确的验收标准用于评分。参见 [目标与评分标准](/oss/deepagents/code/goals-and-rubrics)。
    - `/remember [context]`：回顾对话并更新记忆与技能。可选择性传入额外上下文。
    - `/skill:<name> [args]`：按名称直接调用技能。该技能的 `SKILL.md` 指令会连同你提供的参数一起注入提示词。
    - `/skill-creator [task]`：创建有效智能体技能的引导。
    - `/offload`（别名 `/compact`）——通过把消息卸载到存储并用摘要占位符替代，释放上下文窗口空间。如有需要，智能体可从卸载的文件中取回完整历史。
    - `/tokens`：显示当前上下文窗口的 token 用量明细。
    - `/clear`：清除对话历史并开始新的会话线程。
    - `/force-clear`：停止当前工作、清空聊天并开始新的线程。
    - `/copy`：将最新的助手消息复制到剪贴板。
    - `/threads`：浏览并恢复之前的对话线程。
    - `/mcp [login <server> | reconnect]`：显示当前活动的 MCP 服务器与工具。`login <server>` 为某个服务器运行 OAuth 流程；`reconnect` 加载延后登录的会话。
    - `/plugins`：管理 [插件与市场](/oss/deepagents/code/plugins)。
    - `/notifications`：配置启动警告偏好。
    - `/reload`：无需重启即可重新读取 `.env` 文件、刷新配置并重新发现技能。同时也会重新加载插件技能与 MCP 配置。对话状态会保留。覆盖行为参见 [`DEEPAGENTS_CODE_` 前缀](/oss/deepagents/code/configuration#deepagents_code_-prefix)。
    - `/theme`：打开交互式主题选择器以切换配色主题。内置主题以及任意[用户自定义主题](/oss/deepagents/code/configuration#themes)均可用。
    - `/scrollbar`：显示或隐藏聊天滚动条。
    - `/update`：就地检查并安装 Deep Agents Code 更新。自动检测你的安装方式（uv、Homebrew、pip）并运行相应的升级命令。
    - `/auto-update`：切换自动更新开关。
    - `/install`：安装可选集成。
    - `/trace`：在 LangSmith 中打开当前线程。
    - `/editor`：在外部编辑器（`$VISUAL` / `$EDITOR`）中打开当前提示词。参见 [外部编辑器](#external-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` | 自动补全文件并注入内容 |
    | `Shift+Tab` 或 `Ctrl+T` | 在手动与自动[审批模式](/oss/deepagents/code/approval-modes)之间切换 |
    | `Ctrl+X` | 在外部编辑器中打开提示词 |
    | `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` | 光标向左/向右移动一个单词 |

INFO

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： 没有用于此重映射的原生界面。请直接使用基于 Ctrl 的快捷键。

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

外部编辑器 ​

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

bash
# 在你的 shell 配置文件中设置（~/.zshrc、~/.bashrc 等）
export VISUAL="code"    # GUI 编辑器（自动注入 --wait）
export EDITOR="nvim"    # 终端回退

非交互式模式与管道 ​

使用 -n 在不开交互式界面的情况下运行单个任务：

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 结合使用时，管道内容会先出现，随后是你传给标志的文字。

INFO

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

在非交互模式下，shell 执行默认被禁用。使用 -S/--shell-allow-list 启用特定命令（例如 -S "pytest,git,make"），使用 recommended 启用安全的默认集合，或使用 all 允许任意命令。

限制轮次（turn）数量 ​

    在 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` 限制墙钟时间](#non-interactive-mode-and-piping)。

限制墙钟时间 ​

    `--timeout SECONDS` 对非交互式运行施加硬性的墙钟时间上限。它以基于时间的预算补充 `--max-turns`（轮次计数）——哪个限制先被触发，智能体就会被取消。
bash
# 如果任务耗时超过 2 分钟，在 CI 中快速失败
dcode -n "run the test suite and summarise failures" --timeout 120

# 与 --max-turns 结合使用——哪个限制先被触发，智能体就停止
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
# 允许特定命令（对照列表进行验证）
dcode -n "Run the tests and fix failures" -S "pytest,git,make"

# 使用精选的安全命令列表
dcode -n "Build the project" -S recommended

# 允许任意 shell 命令
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  # Deep Agents Code 自身追踪的项目；默认为 "deepagents-code"

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

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

对于 CI、无头运行或临时覆盖，可以改为设置 shell 环境变量。shell 导出总是优先于 .env 值：

bash
export LANGSMITH_TRACING=false

将智能体追踪与应用追踪分离 ​

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

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

要把 Deep Agents Code 自身的追踪发送到专用项目，请设置 `DEEPAGENTS_CODE_LANGSMITH_PROJECT`：
bash
# 示例值；使用你想要的任何 LangSmith 项目名称。
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_` 前缀](/oss/deepagents/code/configuration#deepagents_code_-prefix)将 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，它可监控你的追踪、检测问题并提出修复建议。

另请参阅 ​