快速入门 - Docs by LangChain中文

Deep Agents Code (dcode) 是一个基于 Deep Agents SDK 构建的终端编码代理。本指南涵盖安装、你的第一个任务、日常交互使用、通过管道进行自动化以及 LangSmith 追踪。功能概述请参阅 Deep Agents Code 概览。关于 config.toml 和提供程序设置，请参阅配置。

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

安装并启动

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

添加提供程序凭据

Deep Agents Code 可与任何支持工具调用的 LLM 配合使用。开箱即用支持 OpenAI、Anthropic 和 Google。使用 /auth 命令连接提供程序。完整列表和凭据详情请参阅提供程序。

网络搜索使用 Tavily。通过 /auth 添加密钥。详情请参阅启用网络搜索。

给代理一个任务

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

代理会解释查询并提出更改方案（包含差异），在你批准后再修改文件。如果需要，它可以运行 shell 命令来测试代码、检查文档或搜索网络以获取最新信息。

启用追踪（可选）

要在 LangSmith 中记录代理的操作、工具调用和决策，请运行 /auth 并添加你的 LangSmith API 密钥。追踪将在下次启动时启用。关于项目命名、高级选项以及 CI 或无头模式设置，请参阅使用 LangSmith 追踪。

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

交互模式

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

斜杠命令

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

/model：切换模型或打开交互式模型选择器。
/effort：为当前模型设置推理努力程度。
/agents：在不重新启动的情况下热切换预配置的代理。相关标志请参阅命令参考。
/auth：管理为模型提供程序和服务（如 Tavily 网络搜索）存储的 API 密钥。详情请参阅提供程序凭据。
/goal <objective>：从一个可衡量的目标起草验收标准。请参阅目标和评分标准。
/rubric：为评分设置明确的验收标准。请参阅目标和评分标准。
/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：管理插件和市场。
/notifications：配置启动警告偏好设置。
/reload：重新读取 .env 文件，刷新配置，并重新发现技能，无需重启。这也会重新加载插件技能和 MCP 配置。对话状态被保留。覆盖行为请参阅 DEEPAGENTS_CODE_ 前缀。
/theme：打开交互式主题选择器以切换颜色主题。提供内置主题以及任何用户自定义主题。
/scrollbar：显示或隐藏聊天滚动条。
/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 模式，然后输入你的命令。

git status
npm test
ls -la

键盘快捷键

通用

快捷键	操作
`Enter`	提交提示
`Shift+Enter`, `Ctrl+J`, `Alt+Enter`, 或 `Ctrl+Enter`	插入新行
`@filename`	自动补全文件并注入内容
`Shift+Tab` 或 `Ctrl+T`	在手动和自动批准模式之间切换
`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`	将光标左/右移动一个单词

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 将其解释为向左/向右移动一个单词。

外部编辑器

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

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

非交互模式与管道

使用 -n 运行单个任务，而不启动交互式界面：

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

每次非交互式运行都会启动一个新线程——对话历史不会在调用之间延续。基于文件的状态（记忆、技能、配置）会持久保存。你也可以通过 stdin 管道输入。当输入是管道时，Deep Agents Code 会自动以非交互方式运行：

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

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

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

限制轮次计数

在 CI/CD 管道中，长时间运行或行为异常的代理可能会无限循环。--max-turns N 为操作员提供了一个硬上限，而无需接触 SDK 内部：

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

N 必须是正整数，并且会覆盖内部安全默认值（否则用于限制失控的循环）。当预算耗尽时以退出码 124（与 GNU timeout 一致）退出，因此 CI 可以区分预算耗尽和通用失败。需要 -n 或管道的 stdin；否则以退出码 2 退出。如果需要基于时间的限制（除了轮次计数限制之外或替代它），请参阅使用 --timeout 限制墙钟时间。

限制墙钟时间

--timeout SECONDS 对非交互式运行强制执行严格的墙钟时间限制。它用基于时间的预算来补充 --max-turns（轮次计数）——哪个限制先达到就会取消代理。

# 在 CI 中，如果任务耗时超过 2 分钟则快速失败
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 之前缓冲完整响应（而不是流式传输）：

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 执行示例

# 允许特定命令（根据列表进行验证）
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

谨慎使用。-S all（或 --shell-allow-list all）允许代理执行任意 shell 命令，无需人工确认。

使用 LangSmith 追踪

启用 LangSmith 追踪，以在 LangSmith 项目中查看代理的操作、工具调用和决策。运行 /auth 并添加你的 LangSmith API 密钥。追踪将在下次启动时启用，并跨会话持续存在。凭据管理器详情请参阅提供程序凭据。要自定义项目名称或在没有 TUI 的情况下配置追踪，请将密钥添加到 ~/.deepagents/.env，这样追踪在每个会话中都会启用，而无需为每个 shell 导出：

~/.deepagents/.env

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 的影响（后者会路由该项目的应用程序追踪；参见下面的将代理追踪与应用程序追踪分离）。要为特定工作目录覆盖项目，请在该目录的 .env 文件中添加 DEEPAGENTS_CODE_LANGSMITH_PROJECT。完整的加载顺序请参阅环境变量。对于 CI、无头运行或临时覆盖，请改为设置 shell 环境变量。shell 导出总是优先于 .env 值：

export LANGSMITH_TRACING=false

将代理追踪与应用程序追踪分离

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

代理追踪 是 Deep Agents Code 自身的模型调用、工具调用、编排和中间件。
Shell 命令追踪 是由 Deep Agents Code 为你在 shell 中运行的代码（如测试、脚本或本地 LangGraph 应用）发出的追踪。

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

~/.deepagents/.env

# 示例值；使用你想要的任何 LangSmith 项目名称。
DEEPAGENTS_CODE_LANGSMITH_PROJECT=deepagents-code

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

.env

LANGSMITH_PROJECT=customer-support-agent

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

uv run pytest tests/test_escalation_flow.py

如果该测试在启用了 LangSmith 追踪的情况下运行你的应用，那么这些应用程序追踪由 shell 进程创建并发送到 customer-support-agent。Deep Agents Code 自身的推理和工具使用追踪则发送到 deepagents-code。你也可以使用 DEEPAGENTS_CODE_ 前缀（例如，DEEPAGENTS_CODE_LANGSMITH_API_KEY）将 LangSmith 凭据的作用域限定为 Deep Agents Code。

双写追踪到第二个项目

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

~/.deepagents/.env

DEEPAGENTS_CODE_LANGSMITH_REPLICA_PROJECTS=team-shared

设置后且追踪处于活动状态时，每次代理运行都会同时写入主项目（DEEPAGENTS_CODE_LANGSMITH_PROJECT，默认为 deepagents-code）和你在此处命名的项目。不设置此变量则照常只写入单个项目。

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

✓ LangSmith tracing: 'my-project'

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

另请参阅

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

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

​交互模式

​外部编辑器

​非交互模式与管道

​使用 LangSmith 追踪

​另请参阅

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

交互模式

外部编辑器

非交互模式与管道

使用 LangSmith 追踪

另请参阅