> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 声明式配置

> 在 YAML 蓝图中定义你的环境。系统会自动构建并生成快照，每个会话都会从该快照启动。

<div id="getting-started">
  ## 快速开始
</div>

<Info>
  **前提条件**：在你配置 Devin 的环境之前，Devin 必须能够访问你的代码仓库。如果你还没有设置 Git 集成，请参阅[开始之前](/zh/onboard-devin/environment#before-you-start)了解设置步骤。Enterprise 用户还需要在 **Enterprise Settings > Repository Permissions** 中为每个组织授予其代码仓库的访问权限。
</Info>

<Info>
  **还在使用经典配置吗？** 你可以随时迁移到声明式配置，Devin 可以帮你完成大部分迁移工作。请参阅[迁移到声明式配置
  ](/zh/onboard-devin/environment/migration)。
</Info>

<Tabs>
  <Tab title="让 Devin 代劳（推荐）">
    适合大多数用户。Devin 会分析你的项目，判断所需的工具和依赖，并为你生成蓝图。你只需审核并批准即可。

    <Steps>
      <Step title="启动 Devin 会话">
        打开一个新会话，并让 Devin 配置该代码仓库。例如：*"为这个代码仓库设置环境。"*
      </Step>

      <Step title="审核并批准">Devin 会提出一个蓝图。你会在时间线中看到**建议卡片**。审核后点击 **Approve**。</Step>

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

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

    <Steps>
      <Step title="前往环境配置">
        前往你的组织侧边栏中的 **Settings > Environment > Blueprints**。

        如果你没有看到此选项，你的组织可能仍在使用经典设置。请参阅[迁移到声明式配置](/zh/onboard-devin/environment/migration)开始迁移。
      </Step>

      <Step title="添加代码仓库">
        在 Repositories 部分点击 **Add**。选择你希望 Devin 使用的代码仓库，然后确认。

        在这里添加的代码仓库会在每次构建时克隆到 Devin 的环境中。你可以随时继续添加。
      </Step>

      <Step title="编写蓝图">
        点击某个代码仓库以打开其蓝图编辑器。下面是一个简单示例：

        ```yaml theme={null}
        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
        ```

        更多语言和模式示例，请参阅[模板库](/zh/onboard-devin/environment/templates)。
      </Step>

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

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

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

<div id="how-it-works">
  ## 工作原理
</div>

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

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

**蓝图 用于描述你想要的环境。** 你可以在设置界面中编写和编辑它们。

**构建 会运行你的 蓝图 来生成快照。** 保存 蓝图 时，构建 会自动运行；此外还会定期运行 (约每 24 小时一次) ，以保持依赖处于最新状态。

**快照是会话启动的基础。** 每个组织都有一个当前启用的快照。每个会话都会从一个全新的副本启动。会话中的更改不会持久保存回快照。

<div id="blueprint-sections">
  ### 蓝图 各部分
</div>

一个 蓝图 有三个部分，此外代码仓库级别的蓝图还可以包含一个可选的 `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](/zh/onboard-devin/environment/blueprint-reference#clone)。

<Info>
  **这里的 knowledge 与 Knowledge 产品功能的区别：** 蓝图 中的 `knowledge` 部分用于存放与环境相关的简短命令参考。对于架构文档、规范和团队
  工作流程，请改用独立的 [Knowledge](/zh/product-guides/knowledge) 功能。
</Info>

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

有关完整的字段规范 (步骤类型、环境变量、secrets 和文件附件) ，请参阅 [蓝图 参考](/zh/onboard-devin/environment/blueprint-reference)。

<div id="blueprint-scope">
  ### 蓝图作用域
</div>

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

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

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

<Info>
  \*\*Enterprise 用户：\*\*还有第三个层级，即企业级蓝图，它会应用于所有组织。详见 [Enterprise 环境概览](/zh/enterprise/environment-management/overview)。
</Info>

<div id="builds-and-sessions">
  ## 构建与会话
</div>

<div id="the-snapshot">
  ### 快照
</div>

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

<div id="how-builds-work">
  ### 构建的工作原理
</div>

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

```
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 小时后超时。

<div id="how-sessions-work">
  ### 会话如何运作
</div>

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

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

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

<div id="what-triggers-a-build">
  ### 哪些情况会触发构建
</div>

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

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

<div id="build-statuses">
  ### 构建状态
</div>

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

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

<Tip>**构建失败？** 请参阅[构建故障排查](#troubleshooting-builds)，获取分步骤调试指南。</Tip>

<div id="managing-your-environment">
  ## 管理环境
</div>

<div id="repository-states">
  ### 仓库状态
</div>

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

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

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

<div id="secrets">
  ### Secrets
</div>

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

```yaml theme={null}
maintenance:
  - name: Configure private registry
    run: npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN
```

secrets 在构建和会话期间会作为环境变量提供。在保存快照之前，它们会被移除；但如果某个命令在 `initialize` 期间将敏感值写入配置文件，该值就会保留在快照中。将写入凭据的步骤放在 `maintenance` 中，以便在定期构建期间刷新。

有关 secret 作用域和行为的详细信息，请参阅 [蓝图参考](/zh/onboard-devin/environment/blueprint-reference#environment-variables-and-secrets)。

<div id="multiple-repositories">
  ### 多个仓库
</div>

每个仓库都有自己的蓝图。在构建过程中，所有仓库都会在同一个快照中完成设置，并克隆到各自独立的目录中，依赖也会分别安装。

如果两个仓库安装了同一全局工具的不同版本，或修改了共享文件 (如 `~/.bashrc`) ，则以后运行的那个为准。为避免冲突，请将共享工具的安装放在组织级蓝图中。

<div id="github-actions">
  ### GitHub Actions
</div>

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

```yaml theme={null}
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](/zh/onboard-devin/environment/github-actions)。

<div id="monorepos">
  ### Monorepos
</div>

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

请参阅 [Workspaces 和 monorepos](/zh/onboard-devin/environment/workspaces) 了解设置说明和示例。

<div id="pinning-and-auto-updates">
  ### 固定与自动更新
</div>

默认情况下，Devin 使用最新成功构建的快照。**固定**可让你锁定到某个特定构建的快照。当新构建引入回归问题，或你想为一批会话冻结环境时，这会很有用。

\*\*固定方法：\*\*前往 **Settings > Environment > Snapshots**，找到相应构建 (必须为 `success` 或 `partial`，且创建时间不超过 7 天) ，然后点击 **Pin**。固定后，系统会跳过定期刷新，且 UI 会显示 **Auto-updates paused**。

\*\*取消固定：\*\*点击 **Resume auto-updates**。Devin 会切换到最新成功构建。

<div id="git-backed-blueprints">
  ### 由 Git 管理的蓝图
</div>

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

有关设置指示和详细信息，请参阅 [Git-backed blueprints](/zh/onboard-devin/environment/git-backed-blueprints)。

<div id="troubleshooting-builds">
  ## 构建问题排查
</div>

<div id="initialize-step-failed">
  ### 初始化步骤失败
</div>

**常见原因：** shell 命令中有拼写错误、软件包不可用、网络超时、GitHub Action 引用不正确。

**修复：** 查看构建日志中的具体错误。更新你的 蓝图 中的 `initialize` 并保存。保存后会自动触发新的构建。

<div id="repository-clone-failed">
  ### 仓库克隆失败
</div>

**常见原因：** Devin 无法访问该仓库、仓库已被重命名/移动/删除，或出现了临时性网络问题。

**修复：** 在你的 Git 提供商设置中确认仓库访问权限。如果仓库已被重命名，请先移除再重新添加。

<div id="maintenance-step-failed">
  ### 维护步骤失败
</div>

\*\*常见原因：\*\*依赖冲突、缺少系统库、磁盘空间耗尽、锁文件不同步。

\*\*修复：\*\*检查失败的包或命令的日志。更新 `maintenance` 或 `initialize` 以安装缺失的依赖，或者修复你的代码仓库中的锁文件。

<div id="build-timeout">
  ### 构建超时
</div>

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

<div id="iterating-on-fixes">
  ### 迭代修复
</div>

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

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

<div id="next-steps">
  ## 后续步骤
</div>

<CardGroup cols={2}>
  <Card title="差异构建" icon="bolt" href="/zh/onboard-devin/environment/differential-builds">
    仅重建蓝图发生变更的工作区，以加快构建速度。
  </Card>

  <Card title="蓝图中的 GitHub Actions" icon="github" href="/zh/onboard-devin/environment/github-actions">
    使用 GitHub Actions 安装语言、工具和 SDK，无需编写 shell 脚本。
  </Card>

  <Card title="工作区与 monorepo" icon="folder-tree" href="/zh/onboard-devin/environment/workspaces">
    面向多包代码仓库的 subshell、工作区作用域和 Knowledge 条目。
  </Card>

  <Card title="蓝图参考" icon="book" href="/zh/onboard-devin/environment/blueprint-reference">
    完整字段参考：步骤类型、环境变量、secrets 和文件附件。
  </Card>

  <Card title="模板库" icon="copy" href="/zh/onboard-devin/environment/templates">
    适用于 Python、Node.js、Go、Java、Ruby、Rust 和高级模式的蓝图，可直接复制粘贴。
  </Card>

  <Card title="由 Git 管理的蓝图" icon="code-branch" href="/zh/onboard-devin/environment/git-backed-blueprints">
    将蓝图存储为代码仓库中的 `.devin/blueprint.yaml`，并通过 API 或 UI 同步。
  </Card>

  <Card title="从经典设置迁移" icon="arrow-right" href="/zh/onboard-devin/environment/migration">
    逐步指导你从交互式向导迁移到声明式蓝图。
  </Card>

  <Card title="企业环境管理" icon="building" href="/zh/enterprise/environment-management/overview">
    企业范围的环境管理：三级层级结构、secrets 和跨组织配置。
  </Card>
</CardGroup>