> ## 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.

# 蓝图参考

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

<Info>
  这是蓝图的完整字段参考。有关蓝图的介绍以及它们如何适配 Devin 的环境，请参阅[声明式环境
  配置](/zh/onboard-devin/environment/blueprints)。
</Info>

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

<div id="overview">
  ## 概览
</div>

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

```yaml theme={null}
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` 会在完整构建期间以及对从头重新构建的工作区执行。结果会保存到快照中。在[差异构建](/zh/onboard-devin/environment/differential-builds)中，继承的工作区会跳过 `initialize`，拉取最新代码，并且只运行 `maintenance`。请将 `maintenance` 编写为自包含的，使其能够在现有快照之上独立运行，而不要求必须先立即运行 `initialize`，也不要依赖 `initialize` 之前写入 `$ENVRC` 的环境变量。在每次会话开始时，`maintenance` 命令**不会自动执行**——而是作为上下文提供给 Agent，以便它在需要时知道应运行哪些依赖命令 (例如，在拉取最新代码后) 。这些命令仍应尽量快速，并支持增量执行。当你的蓝图发生更改时，系统会自动运行构建，也会定期运行 (约每 24 小时一次) 。

<div id="initialize">
  ## initialize
</div>

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

<div id="simple-form">
  ### 简单写法
</div>

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

```yaml theme={null}
initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  apt-get update && apt-get install -y build-essential
  npm install -g pnpm
```

<div id="structured-form">
  ### 结构化格式
</div>

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

```yaml theme={null}
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` 的单独步骤。

<div id="when-to-use-initialize-vs-maintenance">
  ### 何时使用 initialize 与 maintenance
</div>

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

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

<div id="maintenance">
  ## maintenance
</div>

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

```yaml theme={null}
maintenance: |
  npm install
  pip install -r requirements.txt
```

或者用结构化形式表示：

```yaml theme={null}
maintenance:
  - name: "Install npm dependencies"
    run: npm install

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

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

<div id="knowledge">
  ## knowledge
</div>

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

```yaml theme={null}
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 在验证工作结果时会参考这些名称。你也可以添加任意其他使用自定义名称的知识条目：

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

<div id="post-build">
  ## post-build
</div>

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

由于它会在构建后期、整个环境已完整就绪时运行，`post-build` 步骤可以访问每个已克隆的代码仓库，以及企业、组织和代码仓库蓝图安装的所有工具。

```yaml theme={null}
post-build: |
  # 验证环境是否正常运行
  node --version
  python --version
  test -d ~/repos/my-service
```

或者以结构化形式表示：

```yaml theme={null}
post-build:
  - name: "Verify toolchain"
    run: |
      node --version
      uv --version

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

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

<Info>
  `post-build` 步骤与 `initialize` 和 `maintenance` 使用相同的[步骤类型](#step-types) (shell `run` 命令和 GitHub Actions `uses`) ，并且从主目录 (`~`) 运行。
</Info>

<div id="clone">
  ## clone
</div>

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

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

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

<div id="step-types">
  ## 步骤类型
</div>

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

<div id="shell-commands-run">
  ### Shell 命令 (`run`)
</div>

在 bash 中执行任意 Shell 命令：

```yaml theme={null}
- name: "Install dependencies"
  run: |
    npm install
    pip install -r requirements.txt
```

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

**执行详情：**

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

<div id="github-actions-uses">
  ### GitHub Actions (`uses`)
</div>

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

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

<Warning>仅支持**基于 Node.js 的** GitHub Actions。不支持复合 action 和基于 Docker 的 action。</Warning>

**`with` 值的作用方式：**

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

```yaml theme={null}
with:
  python-version: "3.12"
  check-latest: true
  cache: "pip"
```

**操作如何传递更改：**

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

<div id="run-vs-uses-which-to-use">
  ### `run` 与 `uses`：该用哪个
</div>

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

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

<div id="environment-variables-and-secrets">
  ## 环境变量和 secrets
</div>

<div id="step-level-environment-variables">
  ### 步骤级环境变量
</div>

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

```yaml theme={null}
- run: pip install -r requirements.txt
  env:
    PIP_INDEX_URL: "https://pypi.example.com/simple/"
    PIP_BREAK_SYSTEM_PACKAGES: "1"
```

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

<div id="cross-step-environment-variables-envrc">
  ### 跨步骤环境变量 (`$ENVRC`)
</div>

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

```yaml theme={null}
- 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`，这样
后续步骤和仓库级蓝图就能找到该二进制文件：

```yaml theme={null}
- 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` 更改都会丢失。

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

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

<script src="/anchor-scroll-fix.js" />

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

在 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。

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

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

<div id="file-attachments">
  ### 文件附件
</div>

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

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

变量名根据文件名生成：全部大写，将非字母数字字符替换为下划线，并添加 `FILE_` 前缀。

在 蓝图 的步骤中使用文件附件：

```yaml theme={null}
maintenance:
  - name: "Configure Maven"
    run: |
      mkdir -p ~/.m2
      cp "$FILE_SETTINGS_XML" ~/.m2/settings.xml
```

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

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

<div id="complete-example">
  ## 完整示例
</div>

<Info>
  有关蓝图如何跨层级 (企业 → 组织 → 仓库) 组合、构建状态、仓库状态，以及哪些因素会触发重建，请参阅“声明式配置”页面中的[构建和
  会话](/zh/onboard-devin/environment/blueprints#builds-and-sessions)。
</Info>

<div id="org-wide-blueprint">
  ### 组织级蓝图
</div>

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

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

<div id="repo-level-blueprint">
  ### 仓库级蓝图
</div>

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

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