跳转到主要内容

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.

​
快速开始

前提条件：在你配置 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 小时一次) ，以保持依赖处于最新状态。 快照是会话启动的基础。 每个组织都有一个当前启用的快照。每个会话都会从一个全新的副本启动。会话中的更改不会持久保存回快照。

​
蓝图 各部分

一个 蓝图 有三个部分，此外代码仓库级别的蓝图还可以包含一个可选的 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 和文件附件) ，请参阅 蓝图 参考。

​
蓝图作用域

你可以在两个层级定义蓝图：
LevelWhere to configureWhat 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 小时后超时。

​
会话如何运作

每个会话都会启动该快照的全新副本。当会话结束时，所有更改都会被丢弃。在会话开始时：
  1. 系统会拉取相关 代码仓库 的最新代码。
  2. maintenance 命令 (Enterprise、组织和 代码仓库) 会作为上下文提供给 Agent —— 不会自动执行。如果 Agent 检测到自上次构建以来依赖已发生变化，它可能会重新运行这些命令。
  3. 该 代码仓库 的 Knowledge 条目会加载到 Devin 上下文中。
Knowledge 按 代码仓库 单独管理。 如果你配置了 5 个 代码仓库，Devin 只会看到它当前正在处理的那个 代码仓库 的 Knowledge 条目。

​
哪些情况会触发构建

TriggerDescription
保存蓝图创建、更新或删除蓝图
添加或移除仓库仓库列表发生任何变更
添加仓库 secrets新增 secrets 后，需要重建才能生效
手动触发在 UI 中点击 Build snapshot
定期刷新自动进行，大约每 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。在蓝图编辑器的 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 的蓝图

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

​
构建问题排查

​
初始化步骤失败

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

​
仓库克隆失败

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

​
维护步骤失败

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

​
构建超时

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

​
迭代修复

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

​
后续步骤

蓝图中的 GitHub Actions

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

工作区与 monorepo

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

蓝图参考

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

模板库

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

从经典设置迁移

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

企业环境管理

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