Skip to main content
声明式配置 (蓝图) 是新一代的环境配置方式：支持版本控制、可组合，并可自动更新。本指南将引导你从经典的交互式向导迁移过来。

​
为什么要迁移？

使用经典设置向导时，Devin 的环境是一个手动配置的快照，随着时间推移可能会逐渐偏离预期。依赖会老化，配置变更需要重新运行向导，而且没有版本历史。声明式配置可以解决这些问题：
  • 自动更新：当你的仓库发生变化时，蓝图会自动重建，因此依赖始终保持最新
  • 版本受控：你的环境配置与代码一同存放，并保留完整的历史记录
  • 可组合：企业、组织和仓库蓝图可以清晰地分层组合
  • 可复现：每次构建都会基于同一个蓝图生成相同的结果
  • 更快的会话：快照会预先构建好，仓库已克隆、依赖已安装，因此会话启动后即可开始工作
我们建议你在准备好后迁移到声明式配置。在此期间，你的经典设置仍可继续使用。

​
开始前

在 Machine Configuration 页面 (经典设置页面) 查找是否有一条横幅提示，内容为 “切换到 Devin 的新 v2 环境”。如果你看到了，就说明你的组织符合条件。如果你没有看到这条横幅提示，说明你的组织尚未启用声明式配置。该功能正在逐步推出。请联系你的企业管理员或支持团队。
迁移需要 组织管理员 权限 (ManageOrgSettings) 。如果你不是组织管理员，你会在迁移页面看到“需要管理员权限”的提示。
可以。你现有的快照会被完整保留。你可以随时回退，你的组织会立即切换回之前的快照。不会丢失任何内容。

​
迁移步骤

​
1. 前往迁移页面

前往 设置 > 环境迁移，或点击“Machine Configuration”页面横幅上的 Get started。

​
2. 启用声明式配置

点击 为组织启用。这会将你的组织切换为在新会话中使用基于 蓝图 的快照。
这不会影响你现有的快照。系统会保留该快照，以便你在需要时回退。

​
3. 让 Devin 生成你的蓝图

Devin 会替你完成这些工作。 点击 开始迁移，然后选择你想先迁移的代码仓库。你不需要一次性迁移所有内容。先从你最常用的代码仓库开始。 开始迁移后，Devin 会创建 两个会话：
  • 一个在新的声明式环境中运行的主会话，负责编写蓝图
  • 一个在你现有快照中运行的辅助会话，Devin 用它来检查当前已安装的内容 (语言版本、系统软件包、正在运行的服务等)
Devin 会检查你现有的快照，识别其中已安装的工具和依赖，并生成对应的蓝图配置。结果会显示在你的 环境配置 页面上。
你现有的快照就像一个“黑盒”，包含了你长期以来配置的所有内容。Devin 会检查该快照，梳理已安装的内容，并自动将其整理为可复现的蓝图。

​
4. 检查并调整

在 Devin 生成蓝图后：
  1. 前往 Settings > 环境配置 查看已生成的内容
  2. 检查构建状态，确认显示为 Success。
  3. 启动一个测试会话，验证一切是否正常：
    • 确认 repos 已克隆，且依赖已安装
    • 尝试运行你的 lint、test 和 build 命令
    • 验证任何自定义工具或运行时是否可用
如果缺少某些内容，请直接编辑蓝图。你可以添加 initialize 步骤、maintenance 命令或 knowledge 条目。

​
回滚

如果出现问题，可随时回退：
  1. 前往 设置 > 环境迁移
  2. 点击 恢复为经典设置
  3. 你的组织会立即切换回之前的快照
你现有的快照会被完整保留，不会丢失任何内容。准备好后，你可以随时再次尝试迁移。

​
将经典设置步骤映射到蓝图

如果你更愿意手动编写蓝图 (或想了解各项是如何对应的) ，下面是经典向导步骤与蓝图的对应关系：
经典设置步骤蓝图中的对应项说明
Git pull自动蓝图会自动处理 git clone 和 pull
SecretsUI 中的 Secrets 面板在 设置 > 环境配置 中进行配置
安装依赖initialize一次性设置：语言运行时、系统软件包、全局工具
维护依赖maintenance每个会话都要重复执行的设置：npm install、pip install 等
Lintknowledge (name: lint)仅供参考，不会在构建期间执行
Testknowledge (name: test)仅供参考，不会在构建期间执行
运行应用knowledge (name: dev-server)仅供参考，不会在构建期间执行
其他说明knowledge供 Devin 使用的自由格式条目

​
示例

经典设置：
  • 安装依赖：nvm use 20 && npm install
  • 更新依赖：npm install
  • 代码检查：npm run lint
  • 测试：npm test
  • 运行应用：npm run dev
对应的蓝图： 
initialize: |
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
  source ~/.bashrc
  nvm install 20

maintenance: |
  npm install

knowledge:
  - name: lint
    contents: npm run lint
  - name: test
    contents: npm test
  - name: dev-server
    contents: npm run dev

​
故障排查

检查构建日志中的具体报错。常见原因：
  • 某个命令在经典设置终端中可用，但在构建上下文中无法运行 (例如需要加上 -y 标志的交互式提示)
  • 缺少 secrets (请确保已在 蓝图 编辑器的 secrets 面板中配置好 secrets)
  • 将你的 蓝图 命令与原始命令进行对比，找出差异
请确保你的 maintenance 部分包含与经典 Maintain Dependencies 步骤相同的依赖安装命令。像 npm install 或 pip install -r requirements.txt 这样的命令 应该放在 maintenance 中，而不是 initialize。
检查你的 knowledge 部分是否包含名为 lint 和 test 的条目，并且命令正确。Devin 在验证工作结果时会查找这些名称。
如果你的经典设置修改了 ~/.bashrc、~/.profile 或其他 shell 配置，请将这些内容移到 initialize 中：
initialize: |
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
  echo 'export NODE_ENV=development' >> ~/.bashrc
Blueprints 会在构建期间自动处理 git clone。如果 repos 没有被克隆，请检查它们是否已添加到 环境配置 页面，并确认 Devin 已通过你的 Git integration 获得访问权限。