声明式配置 - Devin Docs

快速开始

前提条件：在你配置 Devin 的环境之前，Devin 必须能够访问你的代码仓库。如果你还没有设置 Git 集成，请参阅开始之前了解设置步骤。Enterprise 用户还需要在 Enterprise Settings > Repository Permissions 中为每个组织授予其代码仓库的访问权限。

还在使用经典配置吗？ 你可以随时迁移到声明式配置，Devin 可以帮你完成大部分迁移工作。请参阅迁移到声明式配置。

让 Devin 代劳（推荐）
手动设置

适合大多数用户。Devin 会分析你的项目，判断所需的工具和依赖，并为你生成蓝图。你只需审核并批准即可。

启动 Devin 会话

打开一个新会话，并让 Devin 配置该代码仓库。例如：“为这个代码仓库设置环境。“

审核并批准

Devin 会提出一个蓝图。你会在时间线中看到建议卡片。审核后点击 Approve。

验证

构建完成后，启动一个新会话。Devin 会基于新的快照启动，并预先完成所有配置。你可以尝试让 Devin 运行 lint 或测试命令，确认一切正常。

如果你非常清楚环境需要什么，或想完全掌控每一步，这种方式最合适。如果你已经准备好了相关命令，手动设置会更快。

前往环境配置

前往你的组织侧边栏中的 Settings > Environment > Blueprints。如果你没有看到此选项，你的组织可能仍在使用经典设置。请参阅迁移到声明式配置开始迁移。

添加代码仓库

在 Repositories 部分点击 Add。选择你希望 Devin 使用的代码仓库，然后确认。在这里添加的代码仓库会在每次构建时克隆到 Devin 的环境中。你可以随时继续添加。

编写蓝图

点击某个代码仓库以打开其蓝图编辑器。下面是一个简单示例：

initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh

maintenance: |
  uv sync

knowledge:
  - name: lint
    contents: uv run ruff check .
  - name: test
    contents: uv run pytest

更多语言和模式示例，请参阅模板库。

保存并构建

点击 Save。系统会自动开始构建 (通常需要 2–10 分钟) 。你可以在 Settings > Environment > Snapshots 中的 Current build 下查看进度。

验证

当构建显示 Success 后，启动一个新的 Devin 会话。Devin 会基于新的快照启动，并预先完成所有配置。你可以尝试让 Devin 运行 lint 或测试命令，以验证环境是否正常。

本指南的其余部分将详细介绍手动配置流程。如果你使用了推荐方式，它也能帮助你理解 Devin 生成了哪些内容。

工作原理

声明式配置包含三个概念：

概念	含义	类比
蓝图	一种 YAML 配置，用于描述需要安装的内容以及如何设置 Devin 的环境	Dockerfile
构建	运行你的蓝图、克隆仓库并生成快照的过程	`docker build`
Snapshot	环境的冻结、可启动镜像，会话从该镜像启动	Docker image

蓝图用于描述你想要的环境。 你可以在设置界面中编写和编辑它们。 构建会运行你的蓝图来生成快照。 保存蓝图时，构建会自动运行；此外还会定期运行 (约每 24 小时一次) ，以保持依赖处于最新状态。 快照是会话启动的基础。 每个组织都有一个当前启用的快照。每个会话都会从一个全新的副本启动。会话中的更改不会持久保存回快照。

蓝图各部分

一个蓝图有三个部分，此外代码仓库级别的蓝图还可以包含一个可选的 clone 块：

Section	目的	运行时机
`initialize`	安装工具、运行时和系统软件包	仅在构建期间运行。结果会保存到快照中。
`maintenance`	安装/更新项目依赖，写入凭据配置文件	在构建期间运行。在会话开始时向 Agent 展示 (不会自动执行)。
`knowledge`	供 Devin 参考的信息 (lint、test、build 命令)	不会执行。在会话开始时加载到 Devin 上下文中。
`clone`	覆盖代码仓库的 git clone 默认设置 (仅限代码仓库级别)	在构建的 clone 步骤期间应用。

initialize 用于只需执行一次的内容：语言运行时、系统软件包和全局 CLI 工具。 maintenance 用于安装需要保持最新的依赖。它会在构建期间运行，并在会话开始时向 Agent 展示，以便在依赖发生变化时重新运行这些步骤 (例如，拉取最新代码后) 。这些命令不会在会话开始时自动执行，但仍应尽量快速且支持增量更新 (使用 npm install，不要使用 npm ci) 。 knowledge 是参考信息，不会执行。你可以通过它告诉 Devin 正确的 lint、测试和构建命令。条目应保持简洁，并聚焦于可执行命令。 clone (仅限代码仓库级别) 会覆盖 Devin 在将代码仓库克隆到快照时使用的默认设置——例如，检出非默认分支 (ref)、更改克隆目标位置 (path)，或跳过子模块或 LFS 对象。每个字段都是可选的。完整字段列表请参阅蓝图参考 → clone。

这里的 knowledge 与 Knowledge 产品功能的区别： 蓝图中的 knowledge 部分用于存放与环境相关的简短命令参考。对于架构文档、规范和团队工作流程，请改用独立的 Knowledge 功能。

多文档 YAML： 蓝图编辑器支持使用 --- 分隔符的多文档 YAML。这让你可以在单个编辑器中将复杂的蓝图组织为逻辑部分。

有关完整的字段规范 (步骤类型、环境变量、secrets 和文件附件) ，请参阅蓝图参考。

蓝图作用域

你可以在两个层级定义蓝图：

Level	Where to configure	What to put here
Organization	设置 > Environment > Blueprints > 组织级设置	所有仓库共享的工具：语言运行时、包管理器、Docker 身份验证
Repository	设置 > Environment > Blueprints > [repo name]	项目专用设置：`npm install`、lint/test/build 命令

蓝图是叠加的：仓库蓝图是在组织蓝图的基础上追加的。仓库的 maintenance 可以使用组织 initialize 中安装的工具。如果某个工具只有一个仓库需要，就把它放到该仓库的蓝图中；如果每个仓库都需要，就把它放到组织蓝图中。

**Enterprise 用户：**还有第三个层级，即企业级蓝图，它会应用于所有组织。详见 Enterprise 环境概览。

构建与会话

快照

你的组织有 一个活动快照：一个预装了你的工具、仓库和依赖的虚拟机镜像。所有已配置的仓库都会在这一个镜像中完成克隆和设置。每个会话都会从一个全新副本启动。

构建的工作原理

构建会按顺序运行你的蓝图，从而创建一个新的快照：

1. 企业蓝图, if configured (runs in ~):
   a. initialize
   b. maintenance
2. 组织蓝图 (runs in ~):
   a. initialize
   b. maintenance
3. 克隆所有代码库（最多 10 个并发）。
   每个代码仓库的蓝图可通过 `clone` 块覆盖克隆默认值
   （branch/tag、depth、submodules、LFS 等）。
4. For each configured repo, in the order shown in Settings
   (runs in ~/repos/<repo-name>):
   a. initialize
   b. maintenance
5. Health check, then snapshot is saved

各层是可叠加的：仓库级命令可以使用由组织或企业蓝图安装的工具。较低层级不能覆盖较高层级已设置的内容。构建通常需要 5–15 分钟。单个步骤会在 1 小时后超时。

会话如何运作

每个会话都会启动该快照的全新副本。当会话结束时，所有更改都会被丢弃。在会话开始时：

系统会拉取相关代码仓库的最新代码。
maintenance 命令 (Enterprise、组织和代码仓库) 会作为上下文提供给 Agent —— 不会自动执行。如果 Agent 检测到自上次构建以来依赖已发生变化，它可能会重新运行这些命令。
该代码仓库的 Knowledge 条目会加载到 Devin 上下文中。

Knowledge 按代码仓库单独管理。 如果你配置了 5 个代码仓库，Devin 只会看到它当前正在处理的那个代码仓库的 Knowledge 条目。

哪些情况会触发构建

Trigger	Description
保存蓝图	创建、更新或删除蓝图
添加或移除仓库	仓库列表发生任何变更
添加仓库 secrets	新增 secrets 后，需要重建才能生效
手动触发	在 UI 中点击 Build snapshot
定期刷新	自动进行，大约每 24 小时一次
Devin 建议	Devin 在会话期间建议更改蓝图

同一时间只能运行一个构建。新的触发会取消所有排队中的构建，并重新开始。

构建状态

状态	含义
Success	所有步骤均已完成。快照已就绪。
Partial	某些仓库级别的步骤失败，但快照仍可用。成功的仓库可正常工作；失败的仓库则需要修复其蓝图。
Failed	发生关键故障 (组织或企业级设置失败) 。快照不可用。
Cancelled	已被较新的构建取代，或被手动取消。

Partial 构建仍会生成可用的快照。如果五个仓库中有一个的蓝图损坏，其余四个仍可完全正常使用。

构建失败？ 请参阅构建故障排查，获取分步骤调试指南。

管理环境

仓库状态

仓库在 Environment 设置中会显示为三种状态：

State	Meaning
Configured	具有包含 initialize/maintenance/knowledge 的蓝图。已在快照中完成完整设置。
已包含	已克隆到快照中，但没有自定义蓝图。Devin 可以访问代码。
Available	已连接到 org，但尚未添加到环境中。未克隆。

已包含 vs. Configured： “已包含”的 repo 已被克隆，因此 Devin 可以访问代码，但没有自定义设置命令。“Configured”的 repo 则具有明确的 initialize/maintenance/knowledge 指示。

Secrets

使用 $VARIABLE_NAME 语法引用 secrets。在蓝图编辑器的 Secrets 选项卡中添加。

maintenance:
  - name: Configure private registry
    run: npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN

secrets 在构建和会话期间会作为环境变量提供。在保存快照之前，它们会被移除；但如果某个命令在 initialize 期间将敏感值写入配置文件，该值就会保留在快照中。将写入凭据的步骤放在 maintenance 中，以便在定期构建期间刷新。有关 secret 作用域和行为的详细信息，请参阅蓝图参考。

多个仓库

每个仓库都有自己的蓝图。在构建过程中，所有仓库都会在同一个快照中完成设置，并克隆到各自独立的目录中，依赖也会分别安装。如果两个仓库安装了同一全局工具的不同版本，或修改了共享文件 (如 ~/.bashrc) ，则以后运行的那个为准。为避免冲突，请将共享工具的安装放在组织级蓝图中。

GitHub Actions

你无需编写 shell 脚本来安装工具和运行环境，而是可以直接在你的蓝图中引用 GitHub Actions。Devin 会在构建过程中下载并运行该 Action，方式与 GitHub 的 CI 运行器执行 Action 步骤时相同。

initialize:
  - name: Install Python 3.12
    uses: github.com/actions/setup-python@v5
    with:
      python-version: "3.12"

这对于 setup-python、setup-node 和 setup-go 这类用于设置语言环境的操作尤其有用，因为它们会自动处理版本管理和 PATH 配置。有关语法细节、示例和限制，请参阅蓝图中的 GitHub Actions。

Monorepos

你可以使用 subshells 在子目录中运行命令，或者为单个软件包创建专用于对应 workspace 的蓝图。Devin 也支持按软件包分别设置的 Knowledge 条目，因此每个 workspace 都可以有各自的 lint、test 和 build 命令。请参阅 Workspaces 和 monorepos 了解设置说明和示例。

固定与自动更新

默认情况下，Devin 使用最新成功构建的快照。固定可让你锁定到某个特定构建的快照。当新构建引入回归问题，或你想为一批会话冻结环境时，这会很有用。 **固定方法：**前往 Settings > Environment > Snapshots，找到相应构建 (必须为 success 或 partial，且创建时间不超过 7 天) ，然后点击 Pin。固定后，系统会跳过定期刷新，且 UI 会显示 Auto-updates paused。 **取消固定：**点击 Resume auto-updates。Devin 会切换到最新成功构建。

由 Git 管理的蓝图

你可以将蓝图直接以 .devin/blueprint.yaml 文件的形式存储在代码仓库中。合并更改后，调用 sync API (或在 UI 中点击 Sync) 更新蓝图，然后触发构建。这样，你就能像处理应用程序代码一样使用相同的代码审查工作流程，并通过 CI 步骤自动完成同步。有关设置指示和详细信息，请参阅 Git-backed blueprints。

构建问题排查

初始化步骤失败

常见原因： shell 命令中有拼写错误、软件包不可用、网络超时、GitHub Action 引用不正确。 修复： 查看构建日志中的具体错误。更新你的蓝图中的 initialize 并保存。保存后会自动触发新的构建。

仓库克隆失败

常见原因： Devin 无法访问该仓库、仓库已被重命名/移动/删除，或出现了临时性网络问题。 修复： 在你的 Git 提供商设置中确认仓库访问权限。如果仓库已被重命名，请先移除再重新添加。

维护步骤失败

**常见原因：**依赖冲突、缺少系统库、磁盘空间耗尽、锁文件不同步。 **修复：**检查失败的包或命令的日志。更新 maintenance 或 initialize 以安装缺失的依赖，或者修复你的代码仓库中的锁文件。

构建超时

每个步骤的超时时间均为 1 小时。常见原因包括：从源码编译大型原生依赖 (请使用预编译二进制文件) 、下载大型构建产物，以及命令因等待输入而卡住 (所有命令都必须为非交互式) 。

迭代修复

检查构建日志，找出失败原因
更新相关蓝图
保存 (会自动激活新的构建)
查看新构建的日志
重复上述步骤，直到构建成功

你不必等失败的构建完成。保存新配置会取消所有已排队的构建，并从头开始新的构建。

后续步骤

差异构建

仅重建蓝图发生变更的工作区，以加快构建速度。

蓝图中的 GitHub Actions

使用 GitHub Actions 安装语言、工具和 SDK，无需编写 shell 脚本。

工作区与 monorepo

面向多包代码仓库的 subshell、工作区作用域和 Knowledge 条目。

蓝图参考

完整字段参考：步骤类型、环境变量、secrets 和文件附件。

模板库

适用于 Python、Node.js、Go、Java、Ruby、Rust 和高级模式的蓝图，可直接复制粘贴。

由 Git 管理的蓝图

将蓝图存储为代码仓库中的 .devin/blueprint.yaml，并通过 API 或 UI 同步。

从经典设置迁移

逐步指导你从交互式向导迁移到声明式蓝图。

企业环境管理

企业范围的环境管理：三级层级结构、secrets 和跨组织配置。

​快速开始

​工作原理

​蓝图 各部分

​蓝图作用域

​构建与会话

​快照

​构建的工作原理

​会话如何运作

​哪些情况会触发构建

​构建状态

​管理环境

​仓库状态

​Secrets

​多个仓库

​GitHub Actions

​Monorepos

​固定与自动更新

​由 Git 管理的蓝图

​构建问题排查

​初始化步骤失败

​仓库克隆失败

​维护步骤失败

​构建超时

​迭代修复

​后续步骤

差异构建

蓝图中的 GitHub Actions

工作区与 monorepo

蓝图参考

模板库

由 Git 管理的蓝图

从经典设置迁移

企业环境管理

快速开始

工作原理

蓝图各部分

蓝图作用域

构建与会话

快照

构建的工作原理

会话如何运作

哪些情况会触发构建

构建状态

管理环境

仓库状态

Secrets

多个仓库

GitHub Actions

Monorepos

固定与自动更新

由 Git 管理的蓝图

构建问题排查

初始化步骤失败

仓库克隆失败

维护步骤失败

构建超时

迭代修复

后续步骤