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

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

把这项工作交给智能体是完美的解决方案。

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

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

__wf_reserved_inherit

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

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

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

解决方案：Deep Agents + Skills：编写一次指令，其余交给智能体

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

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

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

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

__wf_reserved_inherit

SKILL.md

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

---name:docs-code-samplesdescription:当将LangChain文档（MDX文件）中的内联代码示例迁移为外部的、可测试的代码文件时，使用此skill，这些文件通过Bluehawk提取并作为Mintlify片段使用。适用于从文档中提取代码块、创建可运行的代码示例、使用片段分隔符，或将Bluehawk输出接入MDXinclude 时。---skill 的主体包含供智能体使用的完整上下文：何时使用该 skill

目录结构和文件布局

  • 分步迁移说明
  • 要运行的命令及顺序
  • 约定（命名、标记、导入）
  • Commands to run and in what order
  • Conventions (naming, tagging, imports)

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

快速开始

这只是你如何在仓库中使用技能配合深度智能体的一个示例。

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