蓝图参考 - Devin Docs

这是蓝图的完整字段参考。有关蓝图的介绍以及它们如何适配 Devin 的环境，请参阅声明式环境配置。

蓝图定义了 Devin 的环境应如何配置：要安装哪些工具、如何让依赖保持最新，以及 Devin 应当识别哪些命令。

概览

一个蓝图包含三个核心顶层部分；对于组织级和企业级蓝图，还包含一个 post-build 部分；对于仓库级蓝图，还可以包含一个可选的 clone 部分：

initialize: ...   # Install tools and runtimes
maintenance: ...  # Install project dependencies
knowledge: ...    # Reference info for Devin (never executed)
post-build: ...   # （仅限 Org/企业级）在所有设置完成后运行的命令
clone: ...        # (仓库级 only) Override git-clone defaults

Section	目的	是否执行？
`initialize`	安装系统工具、语言运行时和全局 CLI	在完整构建期间以及对从头重新构建的工作区执行
`maintenance`	安装并更新项目依赖	是，在构建期间。在会话开始时向 Agent 提供 (不会自动执行) 。
`knowledge`	告诉 Devin 如何执行 lint、测试、构建，以及其他项目相关信息	否，仅供参考
`post-build`	在所有代码仓库完成克隆和设置后运行的命令 (仅限 org/Enterprise)	是，在构建期间——非零退出代码会导致构建失败
`clone`	覆盖代码仓库克隆到快照中的方式 (仅限仓库级)	在构建的 clone 步骤期间应用

所有部分都是可选的。你可以任意组合使用。 initialize 会在完整构建期间以及对从头重新构建的工作区执行。结果会保存到快照中。在差异构建中，继承的工作区会跳过 initialize，拉取最新代码，并且只运行 maintenance。请将 maintenance 编写为自包含的，使其能够在现有快照之上独立运行，而不要求必须先立即运行 initialize，也不要依赖 initialize 之前写入 $ENVRC 的环境变量。在每次会话开始时，maintenance 命令不会自动执行——而是作为上下文提供给 Agent，以便它在需要时知道应运行哪些依赖命令 (例如，在拉取最新代码后) 。这些命令仍应尽量快速，并支持增量执行。当你的蓝图发生更改时，系统会自动运行构建，也会定期运行 (约每 24 小时一次) 。

initialize

使用 initialize 安装不依赖代码具体状态的工具和运行时，例如语言运行时、系统软件包和全局 CLI。

简单写法

对于简单直接的 shell 命令，可使用块标量：

initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  apt-get update && apt-get install -y build-essential
  npm install -g pnpm

结构化格式

对于具名步骤、环境变量或 GitHub Actions，请使用列表形式：

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

  - name: "Install system packages"
    run: |
      apt-get update
      apt-get install -y libpq-dev

  - name: "Install global tools"
    run: pip install uv
    env:
      PIP_BREAK_SYSTEM_PACKAGES: "1"

两种形式可以混用。简单形式等同于一个带有 run 的单独步骤。

何时使用 initialize 与 maintenance

放在 `initialize` 中	放在 `maintenance` 中
语言运行时安装	`npm install` / `pip install`
系统软件包 (`apt-get`)	`bundle install`
全局 CLI 工具	`go mod download`
一次性配置	依赖缓存更新
GitHub Actions (`setup-python` 等)	仓库级设置脚本

这两个部分都会在完整构建期间运行。在差异构建中，继承的工作区会跳过 initialize，并在拉取最新代码后只运行 maintenance。工具和运行时放在 initialize；与代码锁文件保持同步的依赖命令放在 maintenance 中。

maintenance

使用 maintenance 执行依赖安装以及其他应在代码克隆后运行的命令。这些命令会在构建期间运行，并在会话开始时提供给 Agent，以便它在依赖发生变化时重新运行。这里适合放置 npm install、pip install、uv sync 等类似命令。

maintenance: |
  npm install
  pip install -r requirements.txt

或者用结构化形式表示：

maintenance:
  - name: "Install npm dependencies"
    run: npm install

  - name: "Install Python dependencies"
    run: uv sync
    env:
      UV_CACHE_DIR: /tmp/uv-cache

对于仓库级蓝图，maintenance 命令需在仓库根目录中运行。对于组织级蓝图，这些命令需在主目录 (~) 中运行。

knowledge

knowledge 部分不会执行。它提供 Devin 在你的项目中工作时会用到的参考信息。你可以通过这一部分告诉 Devin 用于 lint、测试、构建以及其他项目特定工作流程的正确命令。

knowledge:
  - name: lint
    contents: |
      Run linting with:
      npm run lint

      For auto-fix:
      npm run lint -- --fix

  - name: test
    contents: |
      Run the full test suite:
      npm test

      Run a single test file:
      npm test -- path/to/test.ts

  - name: build
    contents: |
      npm run build

      Build output goes to dist/

每个知识条目都包含：

字段	类型	说明
`name`	string	此知识条目的标识符 (例如 `lint`、`test`、`build`)
`contents`	string	包含命令、指示或备注的自由文本

name 字段是一个标签。按照惯例，lint、test 和 build 是标准名称。Devin 在验证工作结果时会参考这些名称。你也可以添加任意其他使用自定义名称的知识条目：

knowledge:
  - name: lint
    contents: ...
  - name: test
    contents: ...
  - name: build
    contents: ...
  - name: deploy
    contents: |
      Deploy to staging:
      npm run deploy:staging
  - name: database
    contents: |
      Run migrations:
      npm run db:migrate

      Seed test data:
      npm run db:seed

post-build

post-build 部分仅在组织级和企业级蓝图中可用 (仓库级蓝图不支持) 。其中的步骤会在构建过程中运行，即在所有代码仓库都已克隆，且其 initialize 和 maintenance 步骤均已完成之后，但会在健康检查和创建快照镜像之前执行。因此，这里非常适合执行需要完整环境就绪后才能进行的跨代码仓库验证和健康检查。由于它会在构建后期、整个环境已完整就绪时运行，post-build 步骤可以访问每个已克隆的代码仓库，以及企业、组织和代码仓库蓝图安装的所有工具。

post-build: |
  # 验证环境是否正常运行
  node --version
  python --version
  test -d ~/repos/my-service

或者以结构化形式表示：

post-build:
  - name: "Verify toolchain"
    run: |
      node --version
      uv --version

  - name: "Smoke-test the workspace"
    run: ~/repos/my-service/scripts/healthcheck.sh

post-build 步骤会在退出码非零时使构建失败。如果某个 post-build 步骤以非零退出码结束，该构建会被标记为失败，并且不会生成快照镜像。你可以用它通过健康检查来控制是否生成快照——但请确保这些命令足够可靠，以免不稳定的检查阻塞构建。

post-build 步骤与 initialize 和 maintenance 使用相同的步骤类型 (shell run 命令和 GitHub Actions uses) ，并且从主目录 (~) 运行。

clone

对于仓库级蓝图，可选的 clone 部分会覆盖 Devin 将代码仓库克隆到快照中时使用的默认设置。每个字段都是可选的；未设置时，会回退到合理的默认值，以保持当前行为不变。

clone:
  path: my-project        # 克隆目标路径，位于 ~/repos/ 下（默认值：代码仓库短名称）
  ref: develop            # 要检出的分支或标签（默认值：代码仓库的默认分支）
  depth: 1                # 0 = 完整历史记录，N = --depth N（默认值：0）
  tags: false             # 值为 false 时传入 --no-tags（默认值：true）
  submodules: recursive   # true / false / "recursive"（默认值：true）
  lfs: false              # 值为 false 时在克隆期间设置 GIT_LFS_SKIP_SMUDGE=1（默认值：true）

字段	类型	默认值	说明
`path`	string	代码仓库简称	覆盖 `~/repos/` 下的克隆目标目录。在同一快照中的各代码仓库之间必须唯一。
`ref`	string	代码仓库的默认分支	克隆后要检出的分支或标签。此处不支持 commit SHA。
`depth`	int	`0`	克隆深度。`0` 表示克隆完整历史；任意正值都会传入 `--depth N` 以执行浅克隆。
`tags`	bool	`true`	当为 `false` 时，会传入 `--no-tags` 以跳过获取 git 标签。
`submodules`	bool or `"recursive"`	`true`	`true` 或 `"recursive"` 会传入 `--recurse-submodules`。`false` 则会完全跳过子模块。
`lfs`	bool	`true`	当为 `false` 时，会设置 `GIT_LFS_SKIP_SMUDGE=1`，以在克隆期间跳过下载 Git LFS 对象。

clone 仅适用于仓库级蓝图——它控制该代码仓库如何克隆到快照中。在组织级或企业级蓝图中，它不起作用。

步骤类型

initialize、maintenance 或 post-build 中的每个步骤都属于以下两种类型之一：shell 命令 (run) 或 GitHub Actions (uses) 。

Shell 命令 (`run`)

在 bash 中执行任意 Shell 命令：

- name: "Install dependencies"
  run: |
    npm install
    pip install -r requirements.txt

字段	类型	说明
`name`	string (optional)	便于人类阅读的步骤标签
`run`	string	要执行的 shell 命令
`env`	map (optional)	此步骤的额外环境变量

执行详情：

命令在 bash 中运行。如果多行脚本中的任一命令失败，整个步骤会立即停止。
组织级蓝图在主目录 (~) 中执行。
仓库级蓝图在克隆后的仓库根目录中执行。
每个步骤的超时时间为 1 小时。
secrets 会自动作为环境变量提供。

GitHub Actions (`uses`)

在你的蓝图中直接运行基于 Node.js 的 GitHub Actions：

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

字段	类型	说明
`name`	string (optional)	该步骤的便于阅读的标签
`uses`	string	GitHub Action 的引用
`with`	map (optional)	该 Action 的输入参数
`env`	map (optional)	此步骤的额外环境变量

Action 引用格式：

github.com/<owner>/<repo>@<ref>
github.com/<owner>/<repo>/<subpath>@<ref>

github.com/ 前缀和 @<ref> 后缀都必填。ref 通常是类似 v5 这样的版本标签。 常用 action：

Action	目的	示例 `with`
`github.com/actions/setup-python@v5`	安装 Python	`python-version: "3.12"`
`github.com/actions/setup-node@v4`	安装 Node.js	`node-version: "20"`
`github.com/actions/setup-go@v5`	安装 Go	`go-version: "1.22"`
`github.com/actions/setup-java@v4`	安装 Java/JDK	`java-version: "21"`, `distribution: "temurin"`
`github.com/gradle/actions/setup-gradle@v4`	安装 Gradle	(无)
`github.com/ruby/setup-ruby@v1`	安装 Ruby	`ruby-version: "3.3"`

仅支持基于 Node.js 的 GitHub Actions。不支持复合 action 和基于 Docker 的 action。

with 值的作用方式： 通过 with 传入的值会作为该 action 的输入，遵循与 GitHub Actions 工作流程相同的规范。所有值都会被转换为字符串。

with:
  python-version: "3.12"
  check-latest: true
  cache: "pip"

操作如何传递更改： 操作可以修改后续步骤所处的环境。例如，setup-python 会将 Python 可执行文件添加到 PATH 中，因此之后的所有步骤以及 maintenance 中都可以继续使用它。

`run` 与 `uses`：该用哪个

在以下情况使用 `run`…	在以下情况使用 `uses`…
安装系统软件包 (`apt-get`)	设置语言运行时 (Python、Node、Go、Java、Ruby)
运行项目专用脚本	你需要的功能已有官方 GitHub Action
配置文件或环境	你希望自动管理版本并启用缓存
命令简单且可独立完成	你会在 GitHub Actions 工作流程中使用同一个 Action

实际上，大多数配置都会对语言运行时使用 uses，其余情况则使用 run。

环境变量和 secrets

步骤级环境变量

任何步骤都可以通过 env 字段定义额外的环境变量：

- run: pip install -r requirements.txt
  env:
    PIP_INDEX_URL: "https://pypi.example.com/simple/"
    PIP_BREAK_SYSTEM_PACKAGES: "1"

这些变量仅在该步骤内生效，不会延续到后续步骤。

跨步骤环境变量 (`$ENVRC`)

如需在不同步骤之间传递环境变量，请将其写入 $ENVRC 文件：

- name: "Set shared variables"
  run: |
    echo "DATABASE_URL=postgresql://localhost:5432/myapp" >> $ENVRC
    echo "APP_ENV=development" >> $ENVRC

写入 $ENVRC 的变量会自动导出，并可在所有后续步骤和由当前构建生成的 Devin 会话中使用。这与 GitHub Actions 中的 $GITHUB_ENV 类似。这也适用于 PATH。如果你将工具安装到非标准目录 (即 /usr/bin 或 /usr/local/bin 之外的任何位置) ，请将其追加到 $ENVRC，这样后续步骤和仓库级蓝图就能找到该二进制文件：

- name: "Install latest direnv"
  run: |
    curl -sfL https://direnv.net/install.sh | bash
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> $ENVRC

在 run: 块中直接使用 export PATH=... 只会影响该步骤的 shell。每个步骤都会启动一个新的 shell 进程，因此，未写入 $ENVRC 的 PATH 更改都会丢失。

uses: action (例如 actions/setup-node) 会自动将其对 PATH 的添加传播到 $ENVRC —— 你只需要为 run: 步骤手动执行此操作。

$ENVRC 会在每次构建开始时重置，包括差异构建。某次构建期间写入的值在下一次构建中不可用。尤其是，继承的工作区只运行 maintenance，因此不能依赖父构建中 initialize 写入 $ENVRC 的 PATH 或其他变量。请在 maintenance 内部配置 maintenance 所需的任何环境。

Secrets

在 Devin UI 中配置的 Secrets (通过各蓝图编辑器中的 Secrets 选项卡) 会自动注入为环境变量。你无需在蓝图中声明它们，只需按名称引用即可 (例如 $MY_SECRET) 。在构建期间，每个步骤运行前都会注入 Secrets，并且会在每次会话开始时再次注入。Secrets 不会保留在快照镜像本身中，因此凭据绝不会被写入已保存的机器镜像。

组织级 Secrets：在组织中所有蓝图的每个步骤里，都可作为环境变量使用。在组织级蓝图编辑器的 Secrets 选项卡中设置。
Enterprise Secrets：会与组织 Secrets 合并 (如果名称冲突，则以组织 Secrets 为准) 。在所有组织中都可用。
仓库 Secrets：会写入每个 repo 对应的文件 /run/repo_secrets/{owner/repo}/.env.secrets。在构建期间，该 repo 的蓝图步骤运行前，会自动 source 该 repo 的 Secrets。在会话期间，Devin 在该 repo 中工作时也会 source 它们。在该代码仓库的蓝图编辑器的 Secrets 选项卡中配置这些 Secrets。

仅构建 Secrets：标记为 “build only” 的 Secrets 在快照构建期间可用，但会在快照保存前移除。对于仅在构建时需要的凭据，请使用这类 Secrets (例如，在 initialize 期间下载私有构件) 。

maintenance 会在构建期间运行。在会话开始时，maintenance 命令会呈现给 Agent (不会自动执行) ，因此 Agent 可在需要时重新运行这些命令。如果某个 maintenance 步骤将 Secrets 写入配置文件 (例如 ~/.m2/settings.xml、~/.npmrc) ，这些文件就会被保存在快照中。应将写入凭据的步骤放在 maintenance 中 (而不是 initialize) ，以便它们在定期构建期间刷新；但请注意，写入后的文件仍会保留在镜像中。为获得最高安全性，请使用环境变量或 $ENVRC，而不要将凭据写入磁盘。

文件附件

你可以通过蓝图编辑器上传文件 (如 .npmrc、settings.xml、配置文件) 。上传的文件会写入 ~/.files/，并会为每个文件设置一个指向其路径的环境变量：

$FILE_SETTINGS_XML    -> /home/ubuntu/.files/settings.xml
$FILE_NPMRC           -> /home/ubuntu/.files/.npmrc

变量名根据文件名生成：全部大写，将非字母数字字符替换为下划线，并添加 FILE_ 前缀。在蓝图的步骤中使用文件附件：

maintenance:
  - name: "Configure Maven"
    run: |
      mkdir -p ~/.m2
      cp "$FILE_SETTINGS_XML" ~/.m2/settings.xml

由 Git 管理的蓝图

你可以将蓝图直接以 .devin/blueprint.yaml 文件的形式存储在你的代码仓库中，然后通过 API 或 UI 进行同步。有关设置指示和详细信息，请参阅由 Git 管理的蓝图。

完整示例

有关蓝图如何跨层级 (企业 → 组织 → 仓库) 组合、构建状态、仓库状态，以及哪些因素会触发重建，请参阅“声明式配置”页面中的构建和会话。

组织级蓝图

供组织中每个 repo 使用的共享工具。它会最先运行 (在任何 Enterprise 蓝图之后) ，并在主目录中执行。

initialize:
  - name: "Install Node.js 20"
    uses: github.com/actions/setup-node@v4
    with:
      node-version: "20"

  - name: "Install Python 3.12 and uv"
    run: |
      curl -LsSf https://astral.sh/uv/install.sh | sh

  - name: "Install shared tools"
    run: |
      npm install -g pnpm turbo
      apt-get update && apt-get install -y jq ripgrep

  - name: "Configure private registry"
    run: |
      echo "//npm.corp.example.com/:_authToken=$NPM_REGISTRY_TOKEN" >> ~/.npmrc

仓库级蓝图

适用于 Node.js + Python monorepo 的项目级设置。它会在组织级蓝图之后，在仓库目录中运行。

initialize:
  - name: "Install Playwright browsers"
    run: npx playwright install --with-deps chromium

  - name: "Set up project environment variables"
    run: |
      echo "DATABASE_URL=postgresql://localhost:5432/myapp_dev" >> $ENVRC
      echo "REDIS_URL=redis://localhost:6379" >> $ENVRC
      echo "APP_ENV=development" >> $ENVRC

maintenance:
  - name: "Install frontend dependencies"
    run: |
      cd frontend
      pnpm install

  - name: "Install backend dependencies"
    run: |
      cd backend
      uv sync

  - name: "Run database migrations"
    run: |
      cd backend
      uv run alembic upgrade head
    env:
      DATABASE_URL: "postgresql://localhost:5432/myapp_dev"

knowledge:
  - name: lint
    contents: |
      Frontend:
      cd frontend && pnpm lint

      Backend:
      cd backend && uv run ruff check .

      Auto-fix:
      cd frontend && pnpm lint --fix
      cd backend && uv run ruff check --fix .

  - name: test
    contents: |
      Frontend unit tests:
      cd frontend && pnpm test

      Backend unit tests:
      cd backend && uv run pytest

      E2E tests (requires dev server running):
      cd frontend && pnpm test:e2e

  - name: build
    contents: |
      Frontend:
      cd frontend && pnpm build

      Backend:
      cd backend && uv run python -m build

  - name: dev-server
    contents: |
      Start the full development stack:
      cd backend && uv run uvicorn main:app --reload &
      cd frontend && pnpm dev

      Frontend: http://localhost:3000
      Backend API: http://localhost:8000
      API docs: http://localhost:8000/docs

  - name: database
    contents: |
      Run migrations:
      cd backend && uv run alembic upgrade head

      Create a new migration:
      cd backend && uv run alembic revision --autogenerate -m "description"

      Reset the database:
      cd backend && uv run alembic downgrade base && uv run alembic upgrade head

​概览

​initialize

​简单写法

​结构化格式

​何时使用 initialize 与 maintenance

​maintenance

​knowledge

​post-build

​clone

​步骤类型

​Shell 命令 (run)

​GitHub Actions (uses)

​run 与 uses：该用哪个

​环境变量和 secrets

​步骤级环境变量

​跨步骤环境变量 ($ENVRC)

​Secrets

​文件附件

​由 Git 管理的蓝图

​完整示例

​组织级蓝图

​仓库级蓝图

概览

initialize

简单写法

结构化格式

何时使用 initialize 与 maintenance

maintenance

knowledge

post-build

clone

步骤类型

Shell 命令 (`run`)

GitHub Actions (`uses`)

`run` 与 `uses`：该用哪个

环境变量和 secrets

步骤级环境变量

跨步骤环境变量 (`$ENVRC`)

Secrets

文件附件

由 Git 管理的蓝图

完整示例

组织级蓝图

仓库级蓝图