> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 基于 Git 的蓝图

> 将蓝图以 .devin/blueprint.yaml 的形式存储在代码仓库中，并通过 API 或 UI 同步。

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

基于 Git 的蓝图让你可以将环境配置直接存储在代码仓库中的 `.devin/blueprint.yaml` 文件里。你可以通过 API 或 UI 将该文件同步到 Devin，然后触发一次快照构建来应用这些更改。

这样一来，你就可以沿用管理应用程序代码时的同一套工作流程：在 IDE 中编辑、发起拉取请求、接受审查、完成合并，然后通过 CI 步骤或 UI 进行同步和构建。

| 方式             | 蓝图所在位置                         | 编辑方式            | 更改如何生效                            |
| -------------- | ------------------------------ | --------------- | --------------------------------- |
| **数据库 (默认) **  | Devin 的设置界面                    | 在浏览器中编辑         | 点击后立即保存                           |
| **Git-backed** | 代码仓库中的 `.devin/blueprint.yaml` | 在 IDE 中编辑并合并 PR | 调用同步 API (或在 UI 中点击 Sync) ，然后触发构建 |

<Info>
  基于 Git 的蓝图使用与 UI 编辑器相同的 YAML 格式。完整字段规范请参阅[蓝图参考](/zh/onboard-devin/environment/blueprint-reference)。
</Info>

<div id="getting-started">
  ## 快速开始
</div>

<div id="1-create-the-blueprint-file">
  ### 1. 创建蓝图文件
</div>

在你的代码仓库根目录下添加 `.devin/blueprint.yaml` 文件：

```
my-repo/
  .devin/
    blueprint.yaml
  src/
  package.json
  ...
```

该文件使用的 YAML 格式与 UI 中的编辑器相同：

```yaml theme={null}
initialize:
  - name: Install Node.js 22
    uses: github.com/actions/setup-node@v4
    with:
      node-version: "22"

maintenance:
  - name: Install dependencies
    run: npm install

knowledge:
  - name: lint
    contents: npm run lint
  - name: test
    contents: npm test
```

<div id="2-push-to-the-default-branch">
  ### 2. 推送到默认分支
</div>

将 `.devin/blueprint.yaml` 提交并推送到你的代码仓库默认分支 (通常是 `main` 或 `master`) 。

如果该代码仓库已连接到 Devin 的环境，你需要触发一次同步 (通过 API 或 UI 中的 Sync 按钮) ，Devin 才能读取到该文件。如果这是你第一次添加该代码仓库，初始自动发现会从 Git 读取该蓝图。

<div id="3-verify-in-the-ui">
  ### 3. 在 UI 中验证
</div>

前往 **Settings > Environment > Blueprints**，然后点击相应的代码仓库。编辑器会显示来自 Git 的蓝图内容，来源指示器会显示提供商名称 (例如“GitHub”) 以及已同步的提交 SHA 值。

<div id="how-sync-works">
  ## 同步如何运作
</div>

同步是指从代码仓库 默认分支的 HEAD 拉取 `.devin/blueprint.yaml`，并更新 Devin 中已存储蓝图版本的过程。同步**不会**在 push 时自动进行——需要你显式触发：

1. **API 同步** —— 调用 v3 同步端点 (参见下方的 [通过 API 同步](#sync-via-the-api)) 。这是 CI/CD 流水线的推荐方式。
2. **UI 同步** —— 在蓝图编辑器中点击 **Sync** 按钮。如果内容发生变化，这还会触发一次快照构建。
3. **将代码仓库 添加到环境时** —— 如果默认分支上存在 `.devin/blueprint.yaml`，系统会在初始自动发现期间自动从 Git 获取该蓝图。

同步具有幂等性：如果文件内容自上次同步以来没有变化，则不会创建新版本。

<div id="sync-vs-build">
  ### 同步与构建
</div>

同步和构建是两个独立的操作：

* **同步**会从 Git 拉取最新的 `.devin/blueprint.yaml`，并保存为一个新的蓝图版本。
* **构建**会基于当前的蓝图版本创建一个新的快照镜像。

UI 中的同步按钮会通过一次操作完成这两个步骤。v3 API 则将它们分开，让你可以完全掌控流程——先调用同步，再触发构建。

<div id="sync-via-the-api">
  ## 通过 API 同步
</div>

保持蓝图同步的推荐方式，是在将对 `.devin/blueprint.yaml` 的更改合并后调用 v3 API。通常这是通过 CI/CD 流水线完成的 (例如，作为 GitHub Actions 中的合并后步骤) 。

<div id="end-to-end-flow">
  ### 端到端流程
</div>

```mermaid theme={null}
sequenceDiagram
    participant Dev as Developer
    participant Git as Git Provider
    participant CI as CI/CD Pipeline
    participant API as Devin API
    Dev->>Git: Push/merge .devin/blueprint.yaml
    Git->>CI: Trigger post-merge workflow
    CI->>API: POST /v3/organizations/{org_id}/snapshot-setup/sync
    API-->>CI: 200 OK (repo_name)
    CI->>API: POST /v3/organizations/{org_id}/snapshot-setup/builds
    API-->>CI: 201 Created (build_id, status)
    CI->>API: GET /v3/organizations/{org_id}/snapshot-setup/builds/{build_id}
    API-->>CI: 200 OK (status: succeeded)
```

<div id="step-1-sync-the-blueprint">
  ### 步骤 1：同步蓝图
</div>

从默认分支拉取最新的 `.devin/blueprint.yaml`：

```bash theme={null}
curl -X POST https://api.devin.ai/v3/organizations/{org_id}/snapshot-setup/sync \
  -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_name": "owner/repo"}'
```

响应：

```json theme={null}
{"repo_name": "owner/repo"}
```

`repo_name` 字段对于 GitHub 接受 `owner/repo` 格式；对于其他托管服务，则接受完整的提供商 URL (例如 `https://gitlab.com/org/repo`) 。

<div id="step-2-trigger-a-build">
  ### 步骤 2：触发构建
</div>

同步后，触发一次快照构建，以应用新的蓝图：

```bash theme={null}
curl -X POST https://api.devin.ai/v3/organizations/{org_id}/snapshot-setup/builds \
  -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

响应：

```json theme={null}
{
  "build_id": "sbj-abc123",
  "status": "running",
  "trigger": "api",
  "created_at": 1718000000,
  "updated_at": 1718000000
}
```

<div id="step-3-poll-build-status-optional">
  ### 步骤 3：轮询构建状态 (可选)
</div>

若要等待 CI 中的构建完成：

```bash theme={null}
curl https://api.devin.ai/v3/organizations/{org_id}/snapshot-setup/builds/{build_id} \
  -H "Authorization: Bearer $DEVIN_API_TOKEN"
```

`status` 字段的状态会按以下方式变化：`running` → `succeeded` 或 `failed`。

<div id="enterprise-wide-sync">
  ### 企业范围内同步
</div>

对于在多个组织之间共享同一代码仓库的企业，有一个企业级端点，可通过与该代码仓库的连接在所有组织之间进行同步：

```bash theme={null}
curl -X POST https://api.devin.ai/v3/enterprise/snapshot-setup/sync \
  -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_name": "owner/repo"}'
```

响应中包含已同步的 orgs 数量：

```json theme={null}
{"repo_name": "owner/repo", "org_count": 3}
```

<div id="example-github-actions-workflow">
  ### 示例：GitHub Actions 工作流程
</div>

每次向默认分支推送且涉及蓝图文件时，自动执行同步和构建：

```yaml theme={null}
# .github/workflows/sync-blueprint.yml
name: Sync Devin Blueprint

on:
  push:
    branches: [main]
    paths:
      - '.devin/blueprint.yaml'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Sync blueprint
        run: |
          curl -sf -X POST \
            "https://api.devin.ai/v3/organizations/${{ secrets.DEVIN_ORG_ID }}/snapshot-setup/sync" \
            -H "Authorization: Bearer ${{ secrets.DEVIN_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{"repo_name": "${{ github.repository }}"}'

      - name: Trigger build
        run: |
          curl -sf -X POST \
            "https://api.devin.ai/v3/organizations/${{ secrets.DEVIN_ORG_ID }}/snapshot-setup/builds" \
            -H "Authorization: Bearer ${{ secrets.DEVIN_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{}'
```

<Info>
  你需要一个[服务用户](/zh/api-reference/overview)或具有环境写权限的个人访问令牌。将该令牌保存为 `DEVIN_API_TOKEN`，并将你的 org ID 保存为 `DEVIN_ORG_ID`，存储在你的代码仓库 secrets 中。
</Info>

<div id="editing-git-backed-blueprints">
  ## 编辑基于 Git 的蓝图
</div>

当蓝图基于 Git 时，UI 中的编辑器会变为只读，无法直接保存。要进行更改，可通过以下两种方式：

<div id="create-a-pr-from-the-editor">
  ### 在编辑器中创建 PR
</div>

1. 在 **Settings > Environment > Blueprints** 中打开蓝图编辑器
2. 在编辑器中编辑 YAML
3. 点击 **创建 PR**
4. Devin 会在你的代码仓库中创建一个拉取请求，以更新 `.devin/blueprint.yaml`
5. 审查、批准并合并 PR
6. 下次同步时会识别这一更改并触发构建

这让你无需离开 Devin UI 就能快速完成编辑。

<div id="edit-directly-in-your-repository">
  ### 直接在你的代码仓库中编辑
</div>

1. 在你的 IDE 或 Git 提供商上编辑 `.devin/blueprint.yaml`
2. 提交并推送到默认分支 (或创建 PR 并将其合并)
3. 通过 API 触发同步，或在 UI 中点击 Sync

这是实行基础架构即代码管理的团队的标准工作流程。可结合一个 CI 步骤来自动同步 (请参阅[通过 API 同步](#sync-via-the-api)) 。

<div id="devin-suggestions">
  ### Devin 建议
</div>

当 Devin 在 session 期间提出蓝图修改建议时 (例如，在分析你的项目后) ，系统会通过创建一个针对 `.devin/blueprint.yaml` 的 PR 来应用该建议，而不是直接保存到数据库中。你只需像处理其他代码更改一样审查并合并该 PR。

<div id="monorepos-and-workspaces">
  ## monorepo 和工作区
</div>

对于包含多个软件包的 monorepo，你可以使用 `includes` 指令为每个工作区定义单独的蓝图。每个工作区都会在各自的子目录下拥有自己的 `.devin/blueprint.yaml` 文件。

<div id="root-blueprint-with-includes">
  ### 使用 includes 的根蓝图
</div>

根 `.devin/blueprint.yaml` 声明了哪些工作区拥有各自的蓝图：

```yaml theme={null}
# my-repo/.devin/blueprint.yaml
includes:
  - packages/frontend
  - packages/backend

initialize: |
  npm install -g pnpm

maintenance: |
  pnpm install
```

<div id="workspace-blueprints">
  ### 工作区蓝图
</div>

每个已包含的工作区都有各自的 `.devin/blueprint.yaml`：

```yaml theme={null}
# my-repo/packages/frontend/.devin/blueprint.yaml
maintenance: |
  pnpm build

knowledge:
  - name: lint
    contents: pnpm lint
  - name: test
    contents: pnpm test
```

```yaml theme={null}
# my-repo/packages/backend/.devin/blueprint.yaml（后端蓝图）
maintenance: |
  pip install -r requirements.txt

knowledge:
  - name: lint
    contents: ruff check .
  - name: test
    contents: pytest
```

<div id="include-rules">
  ### include 规则
</div>

* 每个 `includes` 条目都是一个子目录路径 (例如 `packages/frontend`) 。Devin 会在该目录下查找 `.devin/blueprint.yaml`。
* 你也可以使用完整路径：`packages/frontend/.devin/blueprint.yaml`。
* 只有根蓝图可以包含 `includes`。不允许嵌套 include (即已包含的蓝图自身再声明 `includes`) 。
* 每个工作区路径在 `includes` 中只能出现一次。
* 如果代码仓库中缺少某个已包含的文件，则对应工作区会被视为已删除，其蓝图也会被清理。

<div id="switching-between-git-and-database-modes">
  ## 在 Git 模式与数据库模式之间切换
</div>

<div id="switch-to-git">
  ### 切换到 Git
</div>

如果你已有一个由数据库管理的蓝图，并且想切换到 Git：

1. 在你的代码仓库中创建 `.devin/blueprint.yaml`，并写入所需内容
2. 推送到默认分支
3. 在蓝图编辑器中，点击来源下拉菜单并选择你的 Git 提供商 (例如“GitHub”)
4. Devin 会从 Git 同步该文件，并切换到基于 Git 的模式

<div id="switch-to-database">
  ### 切换到数据库
</div>

如果你想停止使用 Git 模式，并改为在 UI 中管理蓝图：

1. 在蓝图编辑器中，点击来源下拉菜单并选择 **Database**
2. 当前内容会被保留，但之后再推送到 `.devin/blueprint.yaml` 将不再更新该蓝图
3. 你现在可以直接在 UI 中编辑并保存

<Warning>
  将根蓝图切换为数据库模式时，该代码仓库中的所有工作区蓝图也会一并切换为数据库模式，因为同步是在代码仓库级别进行的。
</Warning>

<div id="detached-workspaces">
  ### 已分离的工作区
</div>

你可以将单个工作区蓝图从 Git 分离，同时让根目录保持为基于 Git 的模式。已分离的工作区可在 UI 中编辑，并且在同步时会被跳过。当某个工作区需要临时覆盖设置而又不影响仓库的其余部分时，这种方式就很有用。

要重新附加已分离的工作区，请在来源下拉菜单中将其来源切回 Git。

<div id="version-history">
  ## 版本历史
</div>

每次同步都会在蓝图的历史记录中创建一个新版本，并带有以下标记：

* **Source**：由同步创建的版本标记为 `git_sync`，在 UI 中创建的版本标记为 `manual`
* **Commit SHA**：同步所基于的默认分支提交 (链接到你的 Git 提供商上的该提交)

你可以在蓝图编辑器的 **Version history** 选项卡中查看完整的版本历史和 diff。

<div id="multi-document-yaml">
  ## 多文档 YAML
</div>

与 UI 编辑器一样，`.devin/blueprint.yaml` 也支持使用 `---` 分隔符的多文档 YAML。这使你可以在单个文件中定义平台专用的配置：

```yaml theme={null}
# Linux 配置（默认）
initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh

maintenance: |
  uv sync
---
runs-on: windows

initialize: |
  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

maintenance: |
  uv sync
```

有关多平台蓝图的详情，请参阅[Windows 支持](/zh/onboard-devin/environment/windows-support)。

<div id="troubleshooting">
  ## 故障排查
</div>

<div id="blueprint-not-syncing">
  ### 蓝图未同步
</div>

* **文件路径是否正确？** 文件必须位于代码仓库根目录下的 `.devin/blueprint.yaml` (对于已包含的工作区，则应为 `<workspace>/.devin/blueprint.yaml`) 。
* **你是否触发了同步？** push 后不会自动同步。请调用同步 API 端点，或点击 UI 中的 **Sync** 按钮。
* **代码仓库是否已添加到 Devin 的环境中？** 要运行同步，必须先在 **Settings > Environment > Blueprints** 中添加该代码仓库。
* **是否已启用基于 Git 的模式？** 只有在基于 Git 的模式下 (而非数据库模式) ，同步才能更新该蓝图。

<div id="invalid-yaml-errors">
  ### 无效 YAML 错误
</div>

如果 `.devin/blueprint.yaml` 包含无效的 YAML，或不符合蓝图架构，同步就会报错并失败。请在默认分支上修复该文件，然后再次同步。UI 中的蓝图编辑器会验证架构，并在你创建 PR 之前显示错误，帮助你在问题进入默认分支之前发现它们。

<div id="blueprint-shows-database-after-pushing">
  ### 推送后 Blueprint 显示“Database”
</div>

如果你已推送 `.devin/blueprint.yaml`，但编辑器中的来源仍显示为“Database”，则该蓝图可能尚未切换到基于 Git 的模式。使用来源下拉菜单切换到你的 Git 提供商，这会触发首次同步。