LangChain 如何用 Deep Agents 让文档代码示例自己跑测试

LangChain：Blog·2026-04-16 01:05· 2026-04-16AI 评分52

我们如何让文档自我测试

AI 导读

LangChain 团队把文档中内联代码示例迁移为可测试代码，通过 Deep Agents CLI 加载 SKILL.md 技能，代理自动完成提取代码、补 setup/teardown、加 :snippet-start: 标记、运行测试等步骤。

正文

过时的代码示例是一个普遍的文档问题。每个发布教程、API 指南或集成示例的团队最终都会看到示例随着依赖变化和 API 演进而失效。这个问题并非我们独有，但我们的产品——以及更广泛的 AI 和 LLM 领域——变化之快加剧了它。新模型、更新的 SDK 以及不断变化的最佳实践意味着上个月还能用的东西今天可能就不行了。

让代码示例可测试可以解决这个问题。这意味着在 CI 中运行它们，断言它们能正确执行，并在它们失效时让构建失败。但让代码示例可测试并非易事，需要一些前期投入。这种设置成本可能让人望而生畏，以至于项目永远不会启动。

把这项工作交给代理是完美的解决方案。

问题：无法测试的不完整内联代码

内联代码示例写起来很方便。你测试代码，复制相关片段，粘贴到 markdown 文件（或其他文档文件）中，然后发布。问题是它们是静态的，当 API 发生变化时，如果代码示例使用了该 API，你可能会忘记更新它。

理想情况下，你想知道代码示例何时停止工作。你需要持续集成测试。适用于应用程序代码的同一原则——自动化检查、捕获变更和回归、在出问题时让构建失败——也适用于文档：把代码示例当作必须通过测试的代码。要让文档中的代码示例可测试，手动流程如下：

将内联代码提取到独立文件中。
添加 setup 和 teardown 代码。
添加标记以指定代码片段。
使用工具提取代码片段。
将提取的代码片段作为可复用的 snippets 包含在文档中。
使用 CI 定期运行独立代码片段，并在示例变更时运行。

在 LangChain，我们使用 Deep Agents CLI 来外包迁移工作流。无需编码。

解决方案：Deep Agents + Skills：写一次指令，委托其余工作

Deep Agents CLI 是一个可以与之对话的命令行代理。它的能力之一是使用技能中的信息来执行任务。技能是可复用的指令，当任务与技能描述匹配时，代理会加载它们。这些技能可以像写给可能执行这些任务的同事的分步指令一样编写。这正是我们所做的。我们为代理写下了要执行的每一步：

将代码移入独立文件，放在 src/code-samples/{product} 下，按产品领域组织。
添加 setup 和 teardown，使代码片段成为完整可运行的示例。
对代码进行 lint，使用配置好的 linter。
添加标记，使用 :snippet-start: 和 :snippet-end: 标签定义代码片段。如果片段中有需要移除的代码，可以用 :remove-start: 和 :remove-end: 排除。
运行代码示例以测试它们。
生成片段，基于标记生成，并将生成的文件包含在文档中。

这是流程中代理化的部分，除此之外，我们还需要一个 GitHub action，定期运行测试，并在测试失败时创建工单。

这个技能位于我们文档仓库的隐藏文件夹中：.agents/skills/docs-code-samples/SKILL.md。设置完成后，任何人都可以在文档仓库内打开 Deep Agents CLI，并要求智能体将文档中的一个或多个代码示例变为可测试的。当你要求 Deep Agent“将 `streaming.mdx` 中的内联代码迁移为可测试的代码示例”时，它就会使用这个技能。智能体会创建正确的文件、添加正确的标签、运行正确的命令，并将代码片段包含在文档文件中。

SKILL.md

docs-code-samples 技能位于 .agents/skills/docs-code-samples/SKILL.md。其 frontmatter 包含一个 `description`，用于告诉智能体何时使用它：

---
name: docs-code-samples
description: Use this skill when migrating inline code samples from LangChain docs (MDX files) into external, testable code files that are extracted with Bluehawk and used as Mintlify snippets. Applies when extracting code blocks from documentation, creating runnable code samples, using snippet delineators, or wiring Bluehawk output into MDX includes.
---

技能正文包含供智能体使用的完整上下文：

何时使用该技能
目录结构和文件布局
分步迁移说明
要运行的命令及顺序
约定（命名、标签、导入）

你可以在我们的 GitHub 仓库中查看完整的 SKILL.md 文件。

快速开始

这只是如何在你的仓库中将 skills 与 deep agents 结合使用的一个示例。

要开始使用 Deep Agents CLI，请查看 CLI 文档。

来源：LangChain：Blog · langchain.com