蓝图参考

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

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

概览

一个蓝图包含三个顶层部分：

initialize: ... # 安装工具和运行时
maintenance: ... # 安装项目依赖
knowledge: ... # 供 Devin 参考的信息（从不执行）

Section	目的	是否执行？
`initialize`	安装系统工具、语言运行时和全局 CLI	是，在每次构建期间
`maintenance`	安装并更新项目依赖	是，在构建期间 + 在每次会话开始时
`knowledge`	告诉 Devin 如何执行 lint、测试、构建，以及其他项目相关信息	否，仅供参考

这三个部分都是可选的。你可以任意组合使用。 initialize 仅在构建期间运行。结果会保存到快照中。maintenance 会在构建期间 (位于 initialize 之后) 以及拉取最新代码后的每次会话开始时运行，因此其中的命令应尽量快速，并支持增量执行。当你的蓝图发生更改时，系统会自动运行构建，也会定期运行 (约每 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 中。

维护

使用 maintenance 执行依赖安装以及其他应在代码克隆后运行的命令。这里适合放置 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

步骤类型

initialize 或 maintenance 中的每个步骤都属于以下两种类型之一：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 类似。

Secrets

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

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

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

maintenance 会在构建期间和会话开始时运行。如果某个 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 的蓝图

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

完整示例

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

组织级蓝图

供组织中每个 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

Get Started

Essential Guidelines

Onboarding Devin

Working with Devin

Product Guides

Integrations

Admin

概览

initialize

简单写法

结构化格式

何时使用 initialize 与 maintenance

维护

knowledge

步骤类型

Shell 命令 (`run`)

GitHub Actions (`uses`)

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

环境变量和 secrets

步骤级环境变量

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

Secrets

文件附件

基于 Git 的蓝图

完整示例

组织级蓝图

仓库级蓝图

Get Started

Essential Guidelines

Onboarding Devin

Working with Devin

Product Guides

Integrations

Admin

​概览

​initialize

​简单写法

​结构化格式

​何时使用 initialize 与 maintenance

​维护

​knowledge

​步骤类型

​Shell 命令 (run)

​GitHub Actions (uses)

​run 与 uses：该用哪个

​环境变量和 secrets

​步骤级环境变量

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

​Secrets

​文件附件

​基于 Git 的蓝图

​完整示例

​组织级蓝图

​仓库级蓝图

概览

initialize

简单写法

结构化格式

何时使用 initialize 与 maintenance

维护

knowledge

步骤类型

Shell 命令 (`run`)

GitHub Actions (`uses`)

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

环境变量和 secrets

步骤级环境变量

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

Secrets

文件附件

基于 Git 的蓝图

完整示例

组织级蓝图

仓库级蓝图