跳转到主要内容

​
快速开始

前提条件：在你配置 Devin 的环境之前，Devin 必须能够访问你的代码仓库。如果你还没有设置 Git 集成，请参阅开始之前了解设置步骤。Enterprise 用户还需要在 Enterprise Settings > Repository Permissions 中为每个组织授予其代码仓库的访问权限。
还在使用经典配置吗？ 你可以随时迁移到声明式配置，Devin 可以帮你完成大部分迁移工作。请参阅迁移到声明式配置 。
适合大多数用户。Devin 会分析你的项目，判断所需的工具和依赖，并为你生成蓝图。你只需审核并批准即可。
1

启动 Devin 会话

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

审核并批准

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

验证

构建完成后，启动一个新会话。Devin 会基于新的快照启动，并预先完成所有配置。你可以尝试让 Devin 运行 lint 或测试命令，确认一切正常。
本指南的其余部分将详细介绍手动配置流程。如果你使用了推荐方式，它也能帮助你理解 Devin 生成了哪些内容。

​
工作原理

声明式配置包含三个概念：
概念含义类比
蓝图一种 YAML 配置，用于描述需要安装的内容以及如何设置 Devin 的环境Dockerfile
构建运行你的 蓝图、克隆仓库并生成快照的过程docker build
Snapshot环境的冻结、可启动镜像，会话从该镜像启动Docker image
蓝图 用于描述你想要的环境。 你可以在设置界面中编写和编辑它们。 构建 会运行你的 蓝图 来生成快照。 保存 蓝图 时，构建 会自动运行；此外还会定期运行 (约每 24 小时一次) ，以保持依赖处于最新状态。 快照是会话启动的基础。 每个组织都有一个当前启用的快照。每个会话都会从一个全新的副本启动。会话中的更改不会持久保存回快照。

​
蓝图 各部分

一个 蓝图 有三个部分：
Section目的运行时机
initialize安装工具、运行时和系统软件包仅在构建期间运行。结果会保存到快照中。
maintenance安装/更新项目依赖，写入凭据配置文件在构建期间 + 在每次会话开始时
knowledge供 Devin 参考的信息 (lint、test、build 命令)不会执行。在会话开始时加载到 Devin 上下文中。
initialize 用于只需执行一次的内容：语言运行时、系统软件包和全局 CLI 工具。 maintenance 用于安装需要保持最新的依赖。它会在构建期间运行，并在拉取最新代码后于会话开始时再次运行，因此命令应尽量快速且支持增量更新 (使用 npm install，不要使用 npm ci) 。 knowledge 是参考信息，不会执行。你可以通过它告诉 Devin 正确的 lint、测试和构建命令。条目应保持简洁，并聚焦于可执行命令。
这里的 knowledge 与 Knowledge 产品功能的区别： 蓝图 中的 knowledge 部分用于存放与环境相关的简短命令参考。对于架构文档、规范和团队 工作流程，请改用独立的 Knowledge 功能。
有关完整的字段规范 (步骤类型、GitHub Actions 支持、环境变量、secrets 和文件附件) ，请参阅 蓝图 参考。

​
蓝图作用域

你可以在两个层级定义蓝图：
LevelWhere to configureWhat to put here
Organization设置 > 环境配置 > 组织级设置所有仓库共享的工具：语言运行时、包管理器、Docker 身份验证
Repository设置 > 环境配置 > [repo name]项目专用设置：npm install、lint/test/build 命令
蓝图是叠加的：仓库蓝图是在组织蓝图的基础上追加的。仓库的 maintenance 可以使用组织 initialize 中安装的工具。如果某个工具只有一个仓库需要，就把它放到该仓库的蓝图中；如果每个仓库都需要，就把它放到组织蓝图中。
**Enterprise 用户：**还有第三个层级，即企业级蓝图，它会应用于所有组织。详见 Enterprise 环境概览。

​
构建与会话

​
快照

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

​
构建的工作原理

构建会按顺序运行你的蓝图，从而创建一个新的快照： 
1. Enterprise 蓝图（如已配置，在 ~ 中运行）：
   a. initialize
   b. maintenance
2. Org 蓝图（在 ~ 中运行）：
   a. initialize
   b. maintenance
3. 克隆所有代码库（最多 10 个并发）
4. 对于每个已配置的代码库，按 Settings 中显示的顺序
   （在 ~/repos/<repo-name> 中运行）：
   a. initialize
   b. maintenance
5. 健康检查，然后保存快照
各层是可叠加的：仓库级命令可以使用由组织或企业蓝图安装的工具。较低层级不能覆盖较高层级已设置的内容。构建通常需要 5–15 分钟。单个步骤会在 1 小时后超时。

​
会话如何运作

每个会话都会启动该快照的全新副本。当会话结束时，所有更改都会被丢弃。在会话开始时：
  1. Enterprise 和组织范围内的 maintenance 会运行 (在 ~ 中) 。
  2. 系统会拉取相关 repo 的最新代码。
  3. 该 repo 的 maintenance 会再次运行，以捕获自上次构建以来的依赖变更。
  4. 该 repo 的 Knowledge 条目会加载到 Devin 上下文中。
Knowledge 按 repo 单独管理。 如果你配置了 5 个 repo，Devin 只会看到它当前正在处理的那个 repo 的 Knowledge 条目。

​
哪些情况会触发构建

TriggerDescription
保存蓝图创建、更新或删除蓝图
添加或移除仓库仓库列表发生任何变更
添加仓库 secrets新增 secrets 后，需要重建才能生效
手动触发在 UI 中点击 Build 或 Rebuild
定期刷新自动进行，大约每 24 小时一次
Devin 建议Devin 在会话期间建议更改蓝图
同一时间只能运行一个构建。新的触发会取消所有排队中的构建，并重新开始。

​
构建状态

状态含义
Success所有步骤均已完成。快照已就绪。
Partial某些仓库级别的步骤失败，但快照仍可用。成功的仓库可正常工作；失败的仓库则需要修复其蓝图。
Failed发生关键故障 (组织或企业级设置失败) 。快照不可用。
Cancelled已被较新的构建取代，或被手动取消。
Partial 构建仍会生成可用的快照。如果五个仓库中有一个的蓝图损坏，其余四个仍可完全正常使用。
构建失败？ 请参阅构建故障排查，获取分步骤调试指南。

​
管理环境

​
仓库状态

仓库在 Environment 设置中会显示为三种状态：
StateMeaning
Configured具有包含 initialize/maintenance/knowledge 的蓝图。已在快照中完成完整设置。
已包含已克隆到快照中，但没有自定义蓝图。Devin 可以访问代码。
Available已连接到 org，但尚未添加到环境中。未克隆。
已包含 vs. Configured： “已包含”的 repo 已被克隆，因此 Devin 可以访问代码，但没有自定义设置命令。“Configured”的 repo 则具有明确的 initialize/maintenance/knowledge 指示。

​
Secrets

使用 $VARIABLE_NAME 语法引用 secrets。在 Settings > Secrets 中添加。 
maintenance:
  - name: Configure private registry
    run: npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN
secrets 在构建和会话期间会作为环境变量提供。在保存快照之前，它们会被移除；但如果某个命令在 initialize 期间将敏感值写入配置文件，该值就会保留在快照中。请始终在 maintenance 中写入凭据。 有关 secret 作用域和行为的详细信息，请参阅 Blueprint 参考。

​
多个仓库

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

​
Monorepo

对于 monorepo，请编写一份涵盖所有子项目的统一蓝图。使用 subshell 在子目录中运行命令： 
maintenance:
  - name: Frontend deps
    run: (cd packages/frontend && pnpm install)
  - name: Backend deps
    run: (cd packages/backend && uv sync)
圆括号 (cd ... && ...) 会在子 shell 中执行，因此工作目录会在下一步恢复。

​
固定与自动更新

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

​
基于 Git 的蓝图

目前尚不支持基于 Git 的蓝图，该功能即将推出。届时，你将能够将蓝图存储在代码仓库中，并在其发生变更时自动触发构建。目前， 请通过 UI 配置蓝图。

​
构建问题排查

​
初始化步骤失败

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

​
仓库克隆失败

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

​
维护步骤失败

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

​
构建超时

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

​
迭代修复

  1. 检查构建日志，找出失败原因
  2. 更新相关 蓝图
  3. 保存 (会自动激活新的构建)
  4. 查看新构建的日志
  5. 重复上述步骤，直到构建成功
你不必等失败的构建完成。保存新配置会取消所有已排队的构建，并从头开始新的构建。

​
后续步骤

蓝图参考

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

模板库

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

从经典设置迁移

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

企业环境管理

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