---
title: "旧版 beeuni.toml"
description: "支持状态以及从 v1 beeuni.toml 迁移到 v2 beeuni.yaml 的路径。"
---

本页介绍 v1 清单（`beeuni.toml`、`beeuni_version: 1`）。如需查看当前清单，请参阅 [清单参考](/docs/zh/project/manifest)。

<a id="support-status"></a>

## 支持状态

Beeuni 仍支持 v1 清单。平台按以下顺序解析项目清单：`beeuni.yaml`，然后是 `beeuni.yml`，最后是 `beeuni.toml`。当前的入门模板会创建 `beeuni_version: 2` `beeuni.yaml`。v1 项目可以继续正常运行，无需强制升级。

v1 支持 TOML 或 YAML 语法。版本 2 仅支持 YAML。使用 TOML 编写的 v2 清单无法通过验证。

<a id="migrate-to-v2"></a>

## 迁移到 v2

1. 在仓库根目录创建 `beeuni.yaml`。设置 `beeuni_version: 2`。

2. 将 `[[agents]]` 转换为 `agents:` 映射，并以代理名称作为键。

3. 将每个代理的 `env` 字段重命名为 `secrets`。列出代理所需的全部密钥——v2 默认不会授予密钥。

4. 添加 `default_agent`，指定默认运行的代理。

5. 删除 `[[channels]]`。在控制面板中重新连接各个频道。

6. 如果使用 `[sandbox]` 或 `[[sandboxes]]`，请将每个图像定义移到 `sandbox.templates` 下。

7. 对 `beeuni.yaml` 运行 `beeuni validate`。修复报告的所有错误。

8. 删除 `beeuni.toml`。

代理行为——系统提示、`model`、`mode`、`temperature` 等——永远不会迁移。在 v1 和 v2 中，它们都已存在于每个代理的 `.md` frontmatter 中的 `.beeuni/opencode/agents/` 下。请参阅 [代理](/docs/zh/project/agents)。

使用 `beeuni validate --file beeuni.yaml` 检查结果。使用 `beeuni schema --version 2` 获取完整的 v2 架构。有关这两个命令，请参阅 [CLI 参考](/docs/zh/cli)。

<a id="key-differences"></a>

## 主要差异

| v1 (`beeuni_version: 1`) | v2 (`beeuni_version: 2`) | 变更 |
|---|---|---|
| `[[agents]]`（数组） | `agents:`（以名称为键的映射） | 将每个数组项转换为一个映射条目。 |
| `[[agents]].env` | `agents.<name>.secrets` | 重命名。默认值从 `all` 变为 `none`——请参阅下方提示。 |
| `[[agents]].model` | 已移除 | 在 v1 中无实际作用（会被解析，但不会应用）。代理行为始终来自代理的 `.md` frontmatter。 |
| `[[agents]].file` | `agents.<name>.file` | 在 v1 中无实际作用（会被解析，但不会应用）。在 v2 中，它指定代理的 `.md`。 |
| 无 `default_agent` | `default_agent`（必填） | 必须指定已声明且启用的代理。 |
| `[[channels]]` | 已移除 | 频道路由由控制面板管理。已连接的频道会显示为包含 `provider: channel` 的 `connectors:` 条目。 |
| `[sandbox]`（单数，图像键直接位于其下） | `sandbox.templates`（列表） | 将每个图像移入一个模板条目。 |
| `[[sandboxes]]` | `sandbox.templates` | 重命名。 |

:::warning[v2 中密钥默认不授予]
  在 v1 中，没有 `env` 字段的代理默认会获得项目的所有密钥。在 v2 中，没有 `secrets` 字段的代理不会获得任何密钥。迁移时，请列出每个代理所需的全部密钥——代理可能会因悄然失去某个密钥而在任务中途失败。
:::

在 v1 中，少数 `beeuni_permissions` 操作可作为旧版行为容许（`project.session.exec`、`project.gateway.routing.edit`、`project.schedule.read`、`project.schedule.write`、`project.webhook.read`、`project.webhook.write`、`channel.read`、`channel.connect`、`channel.send`、`channel.disconnect`）——平台会发出警告，但仍允许这些操作。在 v2 中，相同操作会导致硬错误。迁移前，请从任何代理的 `beeuni_permissions` 授权中移除这些操作。