--- title: "Manifest 参考" description: "beeuni.yaml v2 的所有键，包含默认值、限制和验证规则。" --- Manifest 是平台视为项目权威配置的文件。本页列出每个 `beeuni.yaml` (v2) 键、其类型、默认值以及平台如何验证它。通俗版请参阅 [你的项目](/docs/zh/project)。 ## 两种配置界面 Beeuni 项目有两种配置界面，所有权严格分开，互不重叠。 - **Beeuni 配置** — 仓库根目录中的 `beeuni.yaml` 定义项目环境、Agent、工具、连接器和触发器。沙盒模板可以引用自定义 Dockerfile。 - **Agent 配置** — agent 文件、技能和 harness 文件。agent harness 会在沙盒中和本地读取这些内容。 | 路径 | 内容 | | --- | --- | | `beeuni.yaml` | Manifest：agents 及其可访问内容、触发器、连接器、环境变量和沙盒模板。 | | `agents/.md` | 一个 agent：frontmatter 和系统提示词。`agents..file` 指定其名称。 | | `skills//SKILL.md` | 一个技能。每个 harness 都会加载它。 | | `memory/` | 项目记忆。 | | `tools/.ts` | 项目工具，每个工具一个模块。`tools:` 声明这些工具；每个 harness 都会运行它们。请参阅[工具](/docs/zh/project/tools)。 | | `harnesses/opencode/` | 仅供标准运行器读取的文件：`opencode.jsonc`、`plugins/`、`tools/`、`commands/`。`opencode.config_dir` 指向此处。 | 2026-09 之前创建的项目会将 agents 和技能放在 `.beeuni/opencode/` 下，将记忆放在 `.beeuni/memory/` 下。Beeuni 可读取这两种布局。 两部分通过 agent 的 `.md` 文件连接。Manifest 键 `agents.` 管理 `agents..file` 指定的文件；如果省略 `file`，则管理 `agents/.md`。所有行为字段只存在于该 `.md` 文件的 frontmatter 和正文中，绝不放在 `beeuni.yaml` 中： - 系统提示词 - `model`、`mode` - `temperature`、`top_p` - `steps`、`permission` Manifest 的 `agents:` 区块仅设置治理规则：哪些 agents 可以启动，以及每个 agent 可以访问什么。验证器会强制执行这些规则。如果 v2 agent 区块包含任何行为字段，验证器就会拒绝该配置，并给出指向该 agent 自身 `.md` 文件的错误信息。 ## 位置和版本 根目录中有有效 manifest 的任何仓库都是 Beeuni 项目。`beeuni.yaml`（v2，仅限 YAML）是新项目的当前格式，由网页端“Create project”流程和 `beeuni init` 创建。`beeuni.toml`（v1）仍适用于现有项目，但平台不接受在其中使用任何新的 v2 功能。有关 v1 架构和 v1 到 v2 的迁移步骤，请参阅[旧版 TOML](/docs/zh/project/legacy-toml)。 `beeuni_version: 2` 必须使用 YAML——声明了 `beeuni_version: 2` 的 `.toml` 文件无法通过验证。声明的版本高于 `2` 的 manifest 会被直接拒绝，因此平台不会静默误读未来版本的字段。未知的顶层键会被忽略，因此你可以在文件中存放自己的元数据。 `validateManifest()` 是 `beeuni ship`、变更请求合并检查和 `beeuni validate` 背后的统一关卡。各处应用相同的规则，因此任何合并到 `main` 的内容在结构上都是有效的。架构是公开的，并由同一个软件包生成： - [`beeuni.v2.schema.json`](/schema/beeuni.v2.schema.json) - [`beeuni.v1.schema.json`](/schema/beeuni.v1.schema.json) - [`beeuni.schema.json`](/schema/beeuni.schema.json)（根据 `beeuni_version` 分发） 将 `beeuni.yaml` 指向 v2 架构，以启用编辑器验证；也可以通过 CLI 获取： ```yaml # yaml-language-server: $schema=https://beeuni.ai/schema/beeuni.v2.schema.json beeuni_version: 2 ``` ```bash beeuni schema --version 2 ``` ## 完整示例 ```yaml beeuni_version: 2 default_agent: beeuni project: name: my-project description: What this project is. env: required: [DATABASE_URL] optional: [STRIPE_API_KEY, WEBHOOK_SLACK_SECRET] sandbox: templates: - slug: ml name: ML Development dockerfile: Dockerfile.ml cpu: 4 memory: 16 opencode: config_dir: harnesses/opencode agents: beeuni: file: agents/beeuni.md connectors: all secrets: all beeuni_permissions: all skills: all release-bot: file: agents/release-bot.md sandbox: ml connectors: [github] beeuni_permissions: [project.gitops.push] secrets: [GITHUB_AGENT_TOKEN] triggers: - slug: daily-digest type: cron agent: beeuni cron: '0 0 9 * * 1-5' timezone: America/Los_Angeles prompt: | Summarize yesterday's commits. Open a CR against main. ``` ## 顶层键 | 键 | 必需 | 说明 | | --------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------ | | `beeuni_version` | 是 | 必须为 `2` | | `default_agent` | 是 | 必须指定一个已声明且已启用的 agent | | `imports` | 否 | 其他 YAML 文件或目录；其中的 `triggers`、`connectors`、`agents`、`apps` 和 `tools` 会合并到此 manifest 中。请参阅[`imports:`](#imports) | | `tools` | 否 | 每个会话都会获得的工具：工具名称 → 相对于仓库的模块路径，或表示 Beeuni 工具的 `beeuni:`。如果存在 `tools` 键，会话只能获得其中列出的 Beeuni 工具。每个 harness 都会运行这些工具。请参阅[`tools:`](#tools) | | `runtime` | 否 | `"opencode"`（默认值）或 `"pi"` — 会话在沙盒内启动的 agent harness；`pi` 会在沙盒守护进程中以进程内方式运行实验运行器，并读取相同的 agent `.md` 文件和技能。项目的 `pi_harness` 功能标志无需此行即可选择实验运行器。实验运行器 需要 `llm_gateway` 标志；若没有该标志，会话将启动标准运行器。 | | `harnesses.pi.packages` | 否 | 项目的实验运行器会话加载的实验运行器软件包。请参阅[`harnesses:`](#harnesses) | | `pi.config_dir` | 否 | `harnesses/pi`，如果存在则接着读取 `.beeuni/pi`。实验运行器 原生的 `settings.json`、`extensions/`、`skills/` 和 `prompts/`。 | | `project.name` / `project.description` | 否 | 显示元数据；平台不会读取 `project.name` 来获取项目显示名称 | | `env.required` / `env.optional` | 否 | 环境变量名称；`required` 仅供参考，不会在会话启动时强制执行 | | `sandbox` / `sandbox.templates` / `sandbox.default` | 否 | 沙盒镜像和硬件 | | `opencode.config_dir` | 否 | 默认使用 `harnesses/opencode`，然后使用旧版 `.beeuni/opencode` | | `triggers` | 否 | cron、webhook 和监控触发器列表 | | `connectors` | 否 | 连接器定义列表 | | `policy.default_mode` | 否 | `allow_all`（默认值）或 `risk`；项目级连接器审批模式 | | `agents` | 是 | 名称到区块的治理映射表；不得为空。使用 `imports` 时，映射表可以放在导入文件中 | ## `imports:` 将一个 manifest 拆分到多个 YAML 文件中。当 `beeuni.yaml` 长到无法在一个屏幕内显示时，可以使用这种方式：例如包含多行提示词的 30 个触发器、每个团队一个连接器，或每个 agent 组一个文件。 ```yaml # beeuni.yaml beeuni_version: 2 default_agent: beeuni imports: - triggers/ # a directory: every .yaml and .yml file below it - agents.yaml # a single file agents: beeuni: connectors: all ``` ```text beeuni.yaml agents.yaml triggers/ reports/ weekly.yaml monthly.yaml dockets/ freedom-forever.yaml ``` ```yaml # triggers/reports/weekly.yaml triggers: - slug: weekly-report name: Cross-Sector Weekly Report type: cron agent: galileo cron: "0 15 * * 0" prompt: |- Build the weekly report. ``` 根文件与导入文件共同组成项目配置。一个文件中的触发器可以指定另一个文件中声明的 Agent。 **规则** 1. 路径相对于仓库根目录。`..`、绝对路径和 glob 都会被拒绝。 2. 目录导入会获取其下任意深度的所有 `.yaml` 和 `.yml` 文件，并按路径排序。其他文件会被跳过。 3. 导入的文件声明 `triggers`、`connectors`、`agents`、`apps`、`tools` 和 `imports`。其他所有键（`beeuni_version`、`default_agent`、`runtime`、`project`、`env`、`opencode`、`sandbox`、`policy`、`policies`）保留在根文件中。设置其中任一键的导入文件都会验证失败。 4. 导入的文件可以继续导入更多文件。上限为 8 层和 200 个文件。循环依赖会报错。同一文件被访问两次时只合并一次。 5. 一个名称对应一个文件。在两个文件中声明同一个触发器 slug、连接器 slug、代理名称、应用名称或工具名称会报错，并指出这两个文件。不会静默覆盖。 6. 条目按顺序合并：先合并导入文件，然后按列出的顺序合并其导入项。 导入损坏会导致整个清单失败，方式与 YAML 语法错误相同。`beeuni validate`、`beeuni ship` 和变更请求合并检查都会在错误到达 `main` 之前报告它： ```text imports: triggers "weekly-report" is declared in both triggers/a.yaml and triggers/b.yaml — one name, one file ``` **编辑应写入声明该条目的文件。** 当控制面板、API 或 `beeuni triggers enable|disable|rm` 更改由导入文件声明的触发器、连接器、代理或应用时，只会写入该文件。根文件不会被重写。新条目会写入根文件。如果希望它位于导入文件中，请手动将其移入。 `imports` 需要 `beeuni.yaml`。`beeuni.toml` 清单会忽略该键。 ## `tools:` 会话按名称获取的工具。值有以下两种形式之一： | 形式 | 含义 | | --- | --- | | `beeuni:` | Beeuni 工具（`web_search`、`image_search`、`scrape_webpage`、`memory`、`show`），由 Beeuni 维护。键必须是 ``。 | | 相对于仓库的模块路径 | 项目自有的工具，可位于任意文件夹中。在 Beeuni 工具名称下，该模块会替代 Beeuni 工具。 | ```yaml tools: web_search: beeuni:web_search image_search: beeuni:image_search scrape_webpage: beeuni:scrape_webpage memory: tools/memory.ts # replaces the Beeuni memory tool lookup_order: tools/lookup_order.ts crm_note: integrations/crm/note.ts ``` 标准运行器 和实验运行器运行同一个模块。模块契约、`beeuni tools ls`、 `beeuni tools eject` 以及从 `harnesses/opencode/tools/` 的迁移说明位于 [Tools](/docs/zh/project/tools)。 **选择规则。** - 根文件和任何导入文件中都没有 `tools` 键：会话会获取全部五个 Beeuni 工具。工具列表存在之前创建的每个项目都会保留这些工具。 - 存在 `tools` 键，即使为空（`tools: {}`，或删除了所有行的 `tools:`）：会话只会获取其中列出的 Beeuni 工具，形式可以是 `beeuni:` 或模块路径。导入文件中的 `tools` 键也计算在内。 删除 `beeuni:` 行即可从所有代理中移除该工具。使用 [`agents..tools`](/docs/zh/project/tools#who-may-use-which-tool) 可限制到单个代理。 **错误。** - 名称必须使用 snake_case：`^[a-z][a-z0-9_]{0,63}$`。 - harness 工具名称（`bash`、`read`、`write`、`edit`、`apply_patch`、`glob`、`grep`、`list`、`task`、`question`、`todowrite`、`webfetch`、`websearch`、`skill`、`lsp`、`invalid`、`execute`、`plan_exit`、`pty_*`）属于错误。 - 路径必须以 `.ts`、`.js`、`.mts`、`.mjs`、`.cts` 或 `.cjs` 结尾。不得以 `/` 或 `-` 开头，也不得包含 `.` 或 `..` 段。 - 在其他键下使用 `beeuni:` 会报错。例如，在 Beeuni 工具名称下使用 `web_search: beeuni:image_search`： ```text tools.web_search: must be `beeuni:web_search` (the Beeuni tool) or a repo-relative path to a .ts or .js module (e.g. `tools/web_search.ts`) that replaces it. ``` - 对于不是 Beeuni 工具的名称使用 `beeuni:`，例如 `web_serch: beeuni:web_serch`： ```text tools.web_serch: must be a repo-relative path to a .ts or .js module (e.g. `tools/web_serch.ts`). `beeuni:` names a Beeuni tool under its own name: `web_search: beeuni:web_search`, `image_search: beeuni:image_search`, `scrape_webpage: beeuni:scrape_webpage`, `memory: beeuni:memory`, `show: beeuni:show`. ``` - `beeuni validate` 还会报告已声明但不存在的模块。`beeuni:` 值不需要文件。 **警告。**警告不会导致 `beeuni validate` 失败。 - `tools` 键未列出五个 Beeuni 工具中的任何一个： ```text tools: Sessions of this project get no Beeuni tool (web_search, image_search, scrape_webpage, memory, show). Add `: beeuni:` to keep one. ``` 它用于捕获项目添加第一个自有工具却意外移除这五个工具的情况。 - 代理的 `tools` 指定了项目未加载的 Beeuni 工具： ```text agents.beeuni.tools: "show" is a Beeuni tool this project does not load: add `show: beeuni:show` under the top-level `tools`, or remove it here. ``` ## `project:` 可选的、面向用户的元数据：`name` 和 `description`。平台不会读取此表来执行任何操作——项目的显示名称来自其自身的数据库记录。请将其视为供阅读仓库的人员参考的文档。 ## `env:` 声明会话所需的环境变量名称。值位于控制面板的 Environment variables 页面中，从不直接写入清单。平台会在会话启动时将其解密并以普通环境变量的形式注入。 ```yaml env: required: [DATABASE_URL] optional: [STRIPE_API_KEY] ``` | 字段 | 类型 | 备注 | | ---------- | ---------- | -------------------------------------------------------------------------------------------------------- | | `required` | `string[]` | 仅供参考。控制面板会提示用户填写这些变量，但缺少值不会阻止会话启动。 | | `optional` | `string[]` | 设置后可供会话使用。缺少也没关系。 | 环境变量名称必须符合 `^[A-Z_][A-Z0-9_]*$`。Secrets Manager 将名称长度限制为 64 个字符——更长的名称可以在此处解析，但永远无法获取值。以 `BEEUNI_` 开头的名称也永远无法获取值。名称请保持在 64 个字符以内，并避免使用 `BEEUNI_` 前缀。完整契约：[Secrets](/docs/zh/project/secrets)。 ## `sandbox:` 和 `sandbox.templates` 可启动的命名沙箱镜像列表。可选——没有条目时，每个会话都会启动平台的默认镜像。每个模板必须恰好指定 `dockerfile`（相对于仓库）或 `image`（公共 Docker 引用，并固定标签或摘要）之一。 ```yaml sandbox: templates: - slug: ml name: ML Development dockerfile: Dockerfile.ml cpu: 4 memory: 16 disk: 50 ``` | 字段 | 类型 | 默认值 | 说明 | | ------------ | ------ | ------------------- | --------------------------------------------------------------------------------- | | `slug` | string | — | 必填。每个项目中唯一。`default` 为保留值。 | | `name` | string | slug | 控制面板选择器中的显示标签。 | | `dockerfile` | string | — | 相对于仓库的路径。不能与 `image` 同时使用。 | | `image` | string | — | 公开的 Docker 镜像，固定到标签或摘要。不能与 `dockerfile` 同时使用。 | | `entrypoint` | string | runtime layer's own | 覆盖容器入口点。 | | `cpu` | int | provider default | vCPU 核心数。范围：1–32。 | | `memory` | int | provider default | RAM（GiB）。范围：1–128。 | | `disk` | int | provider default | 磁盘（GiB）。范围：1–500。 | | `container_runtime` | bool | `false` | 在沙箱中运行 Docker，并使用桥接和覆盖网络。参见 [Runtime](/docs/zh/work/runtime#docker-in-the-sandbox)。 | 每个值都必须是正整数。低于最小值会导致验证失败并报错。高于最大值则会通过验证并显示警告，随后在运行时截断到上限。不支持 GPU——声明 `gpu` 会产生警告，不会报错。参见 [Runtime](/docs/zh/work/runtime)，了解运行时层会在你的镜像之上注入哪些内容。 ### `sandbox.default` 在 `sandbox` 中设置 `default`，将一个模板设为项目默认模板。此后，每个会话、触发器和频道都会启动该模板，无需指定 slug。 ```yaml sandbox: default: dev templates: - slug: dev dockerfile: Dockerfile.dev ``` `default` 必须指定此清单中声明的模板，或指定保留值 `"default"`，以使用平台镜像。 智能体可以通过 `agents..sandbox` 选择其环境。该值必须指定清单或控制面板中的模板，或指定 `"default"`。 ```yaml agents: researcher: sandbox: ml ``` 会话模板按以下顺序解析： 1. 显式指定的会话 `sandbox_slug`。 2. 所选智能体的 `sandbox`。 3. 项目的 `sandbox.default`。 4. 平台的 `"default"`。 Cron 触发器、webhook 触发器、计划任务和频道使用所选智能体的模板。 更改规格（`cpu`、`memory`、`disk`、`container_runtime` 或镜像本身）会重建项目快照。新的规格会在下一个会话中生效，不会影响正在运行的会话。 ## `opencode:` 标准运行器 配置目录的位置。可选，并有默认值。 ```yaml opencode: config_dir: harnesses/opencode ``` | 字段 | 类型 | 默认值 | 说明 | | ------------ | ------ | ----------------------------------------------- | ------------------------ | | `config_dir` | string | `harnesses/opencode`，然后是 `.beeuni/opencode` | 相对于仓库的目录。 | 未设置 `config_dir` 时，Beeuni 会依次检查 `harnesses/opencode` 和 `.beeuni/opencode`，并使用第一个包含 `opencode.json` 或 `opencode.jsonc` 的目录。该目录用于存放仅供标准运行器读取的文件：`opencode.jsonc`、`plugins/`、`tools/` 和 `commands/`。智能体和技能位于仓库根目录的 `agents/` 和 `skills/` 中。`opencode.jsonc` 仍是标准运行器原生的插件、MCP 服务器、提供商和权限注册表——不要在清单中重复这些设置。参见 [Agents](/docs/zh/project/agents)。 ## `harnesses:` 各运行框架的设置。`pi.config_dir` 指向实验运行器原生配置所在的相对仓库目录（默认依次为 `harnesses/pi` 和 `.beeuni/pi`）。实验运行器 启动时会导入此目录。`pi.packages` 则单独负责为每个智能体安装清单中 `harnesses.pi.packages` 指定的软件包。目前只有一个软件包键：`pi.packages`，即此项目的每个实验运行器会话都会加载的实验运行器软件包（`runtime: pi`，或 `pi_harness` 标志）。软件包可以是 packages 中的任何内容：扩展（工具、钩子、命令），以及软件包附带的技能和提示。 ```yaml runtime: pi harnesses: pi: packages: - npm:pi-web-access@0.30.0 # pinned extension version - source: npm:pi-mcp-adapter@2.36.0 extensions: ["extensions/*.ts"] # load only these files of the package skills: [] # load none of its skills - ./harnesses/pi/audit.ts # an extension file in this repository ``` | 条目格式 | 含义 | | --- | --- | | `npm:@` | 指定确切版本的 npm 软件包。版本范围或未指定版本都会导致验证失败。 | | `./` | 此仓库中的扩展文件或软件包目录。`..` 不得用于访问仓库之外的路径。 | | `{ source, extensions, skills, prompts, themes }` | 相同来源，并使用实验运行器自带的包含/排除过滤器。省略过滤器表示全部加载；`[]` 表示不加载任何内容。 | 最多可有 20 个条目。不接受 Git 来源。 ### 按智能体设置 智能体可以添加自己的软件包，并在 `agents..harnesses` 中移除顶层软件包： ```yaml harnesses: pi: packages: [npm:pi-web-access@0.30.0] # every agent agents: researcher: harnesses: pi: packages: [npm:@juicesharp/rpiv-todo@2.11.0] # researcher only reviewer: harnesses: pi: exclude: [pi-web-access] # reviewer loads no web tools ``` - 智能体的软件包列表由顶层列表减去其 `exclude`，再加上其自己的 `packages` 组成。 - 如果智能体条目与顶层列表中的某个软件包相同，则该智能体会使用自己的条目替代顶层条目（例如使用其他版本或过滤器）。 - `exclude` 列出软件包名称（`pi-web-access`、`@scope/name`）或 `./` 路径，写法与顶层列表一致。此处不指定版本。 - 每种不同的软件包列表只构建一次。列表相同的智能体会共用构建结果。 - 软件包归启动会话的智能体所有。由另一个智能体通过 `task` 工具启动的子智能体只能使用标准工作区工具（`bash`、`read`、`write`、`edit`、`glob`、`grep`），不能使用自己的软件包或父智能体的软件包；但父智能体的扩展钩子仍会作用于子智能体的调用。要使用该智能体的软件包，请使用它启动会话。 软件包进入会话的方式： 1. 合并编辑此列表的更改请求后，会为沙箱平台构建一次软件包，并关闭安装脚本。每个扩展都会预先构建为一个压缩文件。构建会保留软件包的其他文件，但不包括该文件已有的代码、类型声明、源映射文件、根目录下的 README 和 CHANGELOG。列表相同的项目会共用构建结果。 2. 新会话或重启后的会话会在克隆仓库时下载构建结果，并直接加载每个扩展。会话不会运行 `npm install`，也不会编译软件包。 3. 无法预先构建的软件包（例如 `pi.extensions` 使用 glob 的软件包）仍可使用：会话会改为从已安装的软件包中加载，因此耗时更长。如果软件包代码会读取构建时排除的文件，请为其条目设置 `extensions` 过滤器：这样会话也会从已安装的软件包中加载它。 4. 如果会话在构建结果就绪前启动，它会在没有项目软件包的情况下启动，并开始构建；下一个会话即可使用这些软件包。 Beeuni 也会为每个实验运行器会话安装一组系统软件包。项目中的同名条目会替代系统版本。仓库还可以在 `.pi/extensions/*.ts` 中存放实验运行器原生扩展；实验运行器 无需清单条目即可加载它们。 扩展在没有终端 UI 的情况下运行：工具、钩子和命令均可正常工作；仅限终端的组件则不起作用。 ## `triggers:` Cron、webhook 和监控器定义列表。每个条目都会触发一个会话，并将 `prompt` 作为第一条消息运行。 ```yaml triggers: - slug: daily-digest type: cron cron: '0 0 9 * * 1-5' prompt: Summarize yesterday's commits. ``` | 字段 | 必填 | 默认值 | 备注 | | -------------- | --------------------- | --------------------- | ----------------------------------------------------------------------------------------------------- | | `slug` | 是 | — | `[a-z0-9][a-z0-9_-]{0,127}`，在触发器中唯一。 | | `type` | 是 | — | `cron`、`webhook` 或 `monitor`（实验性）。 | | `prompt` | 是 | — | 不能为空。支持模板化。 | | `name` | 否 | slug | 面向用户的标签。 | | `agent` | 否 | `default_agent` | 必须是 `agents:` 中的键。省略则使用 `default_agent`；不要填写字面值 `default`。 | | `enabled` | 否 | `true` | `false` 会跳过此条目。 | | `model` | 否 | 触发时解析 | 接线形式为 `provider/model`。将触发的会话固定到该模型。参见 [Models](/docs/zh/project/models)。 | | `session_mode` | 否 | `fresh` | `fresh`、`reuse`、`pinned` 或 `keyed`。 | | `session_id` | `pinned` 时必填 | — | 要重新提示的确切会话。 | Cron 触发器必须且只能指定 `cron`（6 字段表达式）或 `run_at`（一次性 ISO-8601 时间戳）之一，并指定作为 IANA 名称的 `timezone`。Webhook 触发器需要 `secret_env`，即一个密钥的名称，该密钥使用 `broker` 投递方式和 `connector` 消费者。监控触发器需要 `run`（相对于仓库的命令）和 `mode`（`poll` 或 `stream`），并且不接受任何 cron 或 webhook 字段。完整字段参考、凭据设置、负载模板化、端点和会话策略，请参见 [Triggers](/docs/zh/connect/triggers)。 ## `connectors:` 智能体可调用的外部工具列表。定义存储在 git 中；凭据存储在平台中，绝不放在清单中。概念模型请参见 [Connectors](/docs/zh/connect/connectors)。 ```yaml connectors: - slug: gmail-read name: Gmail read only provider: pipedream app: gmail authorization_strategy: user policies: - match: search_email action: always_run ``` | 字段 | 必填 | 备注 | | ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `slug` | 是 | `[a-z0-9][a-z0-9_-]{0,127}`，在连接器中唯一。 | | `provider` | 是 | `pipedream`、`mcp`、`openapi`、`postman`、`graphql`、`http` 或 `channel`。 | | `name` | 否 | 显示名称。默认使用 slug。 | | `authorization_strategy` | 否 | `project` 或 `user`。省略时默认为 `project`。项目策略使用活跃项目连接。用户策略仅使用当前操作成员的连接。 | | `enabled` | 否 | 默认使用 `true`。 | | `credential` | 否 | 仅支持 `shared`。已弃用的 `per_user` 模式会导致硬错误。 | | `sensitive` | 否 | 默认使用 `false`。`true` 会将 `require_approval` 设为未匹配操作的默认规则，包括读取操作。显式的项目和连接器规则仍会优先解析。 | 提供商专属字段： | 提供商 | 必填字段 | 备注 | | ----------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `pipedream` | `app` | `account` 可选，默认使用 slug。 | | `mcp` | `url` | `transport`：`http`（默认）或 `sse`。 | | `openapi` | `spec` | URL 或相对于仓库的路径。 | | `postman` | `spec` | Collection JSON URL 或路径、`.postman/api` 清单，或 Postman 工作区 URL。 | | `graphql` | `endpoint` | `spec` 可选（SDL）。 | | `http` | `base_url` | `spec` 可选。 | | `channel` | `platform` | `slack`、`teams`、`email` 或 `voice`。 | | `computer` | — | 由 API 管理。无法手动声明。每台已连接的 computer 都是其一个账户。参见 [Computers](/docs/zh/connect/computers)。 | `channel` 连接器很少需要手动编写条目——在仪表板中连接频道会自动创建条目。参见 [Slack & channels](/docs/zh/connect/slack)。slug `beeuni_slack`、`beeuni_teams`、`beeuni_email` 和 `computer` 由平台专用；将它们与其他提供商搭配使用会导致验证错误。首位成员连接 computer 时会创建 `computer` 连接器，因为机器 ID 是账户控制平面的身份标识，不得写入清单。 `connectors.auth`：可选，适用于 `pipedream` 以外的提供商。`type` 可以是 `bearer`、`basic`、`custom`、`api_key`、`oauth1`、`hmac`、`aws_sigv4`、`mtls` 或 `none`（默认值）。`oauth1` 仅限于 `openapi`、`postman` 和 `http` 提供商。`in` 可以是 `header`（默认值）、`query` 或 `cookie`。当 `type` 为 `custom` 或 `api_key` 时，必须设置 `name`。 `connectors.policies`：`{match, action}` 对的列表。`match` 是针对工具名称的 glob。`action` 可以是 `always_run`、`require_approval` 或 `block`。策略归属于连接器。该连接器下的每个连接都使用相同的策略。 `policy.default_mode`：一个顶层键，与 `connectors:` 分开，用于设置项目范围的连接器审批模式。它接受 `allow_all`（默认值；每个未匹配的工具都会运行）或 `risk`（对写入操作和具有破坏性的未匹配调用要求审批）。使用 `beeuni connectors policy set --default ` 设置 — 参见 [CLI](/docs/zh/cli)。 ## 通道 v2 从架构中移除了 `channels:`。通道到代理的路由（目前支持 Slack、Microsoft Teams、电子邮件和语音）属于实时运营状态，而不是声明式配置。你可以在控制面板的 Channels 页面中设置，也可以通过聊天命令设置；这与凭据不进入 git 的边界相同。连接通道仍会创建一个带有 `provider: channel` 的 `connectors` 条目，供代理调用。参见 [Slack & channels](/docs/zh/connect/slack)。v1 的 `[[channels]]` 表格详见 [Legacy TOML](/docs/zh/project/legacy-toml)。 ## `agents:` 按代理名称作为键的名称到区块映射。此映射仅用于治理——它授予代理可以接触的内容，而绝不决定代理说什么或做什么。 此区块是**两个绑定中的第二个**：主体从 Beeuni 获得角色，而代理还会携带此处声明的 Beeuni 权限。会话只能执行两者都允许的操作。参见 [One vocabulary, two bindings](/docs/zh/accounts#one-vocabulary-two-bindings)。 ```yaml default_agent: beeuni agents: beeuni: file: agents/beeuni.md connectors: all secrets: all beeuni_permissions: all skills: all release-bot: file: agents/release-bot.md connectors: [github] connectors_required: [github] beeuni_permissions: [project.gitops.push] secrets: [GITHUB_AGENT_TOKEN] ``` | 字段 | 默认值 | 说明 | | --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | _(映射键)_ | — | `[a-z0-9][a-z0-9_-]{0,127}`，每个项目中必须唯一。没有 `file` 时，它同时也是 `.md` 文件名。 | | `file` | `agents/.md` | 代理的 `.md` 相对于仓库的路径。参见 [The agent file](#the-agent-file)。 | | `enabled` | `true` | `false` 会将代理视为未声明——平台不会启动它。 | | `connectors` | `none` | 此代理可以调用的连接器 slug。`all` 表示所有连接器。 | | `connectors_required` | `none` | 已弃用：会被解析并忽略。连接器不再影响沙箱启动；调用未连接任何内容的连接器会返回带有连接链接的 `connector_not_connected`。存在时仍必须是 `connectors` 的子集。 | | `secrets` | `none` | 此代理接收为沙箱环境变量的项目机密。由 v1 的 `env` 重命名而来。 | | `beeuni_permissions` | `none` | 此代理可以通过 CLI、API 或 git 执行的 Beeuni 权限（项目操作）。`all` 表示所有项目权限，但仍受代理的上限角色限制，并且绝不包括仅限人类的权限。`beeuni_cli` 是已弃用的拼写形式：仍然接受，但会发出验证警告；如果两者被设置为不同值，则会报错。 | | `skills` | `none` | 此代理可以加载的技能。 | | `apps` | `none` | 当 App 为 `restricted` 或 `private` 时，此代理可以打开的 Beeuni App slug。`all` 表示项目中的所有 App。参见 [Agents and Apps](/docs/zh/feature-flags/apps#agents-and-apps)。 | | `tools` | `all` | 此代理可以使用的工具：harness、Beeuni 和项目工具。可以是 `all`、`none`、列表（仅限其中的工具）或 `{ exclude: [...] }`（除其中工具之外的全部工具）。早期的映射形式 `{ bash: false }` 仍然有效。与上述授权不同，省略 `tools` 表示所有工具。参见 [Who may use which tool](/docs/zh/project/tools#who-may-use-which-tool)。 | | `repository_access` | `true` | 新会话是否接收项目仓库。`false` 会禁用仓库交付以及通过会话凭据访问仓库。现有会话保留其已保存的策略。 | v2 默认拒绝：对于已声明的代理，省略 `connectors`、`secrets`、`beeuni_permissions`、`skills` 或 `apps` 时，解析为 `none`。请明确授予代理所需的每项权限，如上方 starter 的 `beeuni` 代理所示。从 v1 迁移的项目必须手动重新授予所有权限——v1 在省略时会将（机密）`env` 默认为 `all`，与 v2 相反。 `connectors_personal` 仍是 `connectors_required` 的已弃用输入别名。新清单必须使用 `connectors_required`。连接器的 `authorization_strategy` 决定授权归项目所有还是归成员所有。 `beeuni_permissions` 授权来自一组固定的项目范围权限（`project.read`、`project.gitops.push`、`project.gitops.merge`、`project.gitops.ref.any`、`project.trigger.*`、`project.secret.*`、`project.connector.*` 等）。账户范围权限——`member.*`、`billing.*`、`project.create`——永远不能授予代理。在会话中运行 `beeuni validate --scopes` 可打印当前可授予的权限列表。 ### 代理文件 `agents..file` 指定代理的 `.md`，路径相对于仓库根目录。 ```yaml agents: support: file: agents/support.md ``` - 路径必须以 `.md` 结尾。 - 路径不得以 `/` 或 `-` 开头。不得包含 `.` 或 `..` 段，也不得包含空段。 - 每个段只能使用字母、数字、`_`、`-`、`.` 和空格。 - 省略 `file` 时，Beeuni 会读取 `agents/.md`，然后读取 `.beeuni/opencode/agents/.md`。设置 `opencode.config_dir` 后，第二个路径为 `/agents/.md`。 - 控制面板保存带有 `.md` 的代理时，会写入带有该路径的 `file`。 - API 会拒绝更改 `file` 的请求（`400`，代码 `invalid_config`）。要移动代理，请移动其 `.md`，并在同一提交中更新 `beeuni.yaml` 中的 `file`。 `beeuni validate` 和变更请求合并检查会拒绝无效的 `file`，并在 `agents..file` 上报错。 ## 配置变更何时生效 - 清单、`agents/`、`skills/` 或标准运行器配置目录的编辑，只有在变更请求合并到 `main` 后才会生效。会话和触发器读取的是默认分支，而不是会话分支。 - 触发器的 cron 或 webhook 变更会在合并后数秒内由调度器读取。 - 沙盒映像或硬件变更会重建快照。新规格会在下一个会话中生效，不会影响当前会话。 - 在控制面板中更改密钥值，会在创建沙盒时解析。新值会在下一个会话中生效，不会影响正在运行的会话。 ## 往返规则 控制面板编辑会对声明该条目的文件执行读取-修改-写入操作：`beeuni.yaml`，或[导入的文件](#imports)。为确保 UI 和会话内编辑之间的差异保持简洁： 1. 将 `beeuni_version` 保持为第一个键。 2. 在触发器条目内，依次排列字段：`slug`、`name`、`type`、`agent`、`enabled`，然后是特定于类型的字段，最后是 `prompt`。 3. 如果在设置密钥之前添加 webhook 触发器，请在 `env.optional` 中列出密钥名称。在填入密钥值之前，将触发器保持为 `enabled: false`。 ### 仓库访问权限 对于不需要项目源文件的代理，将 `agents..repository_access` 设为 `false`。 它们仍可创建沙盒文件，并使用获准的工具、密钥和连接器。 对于需要访问仓库的代理，将其设为 `true`。Git 权限仍单独管理。 在代理编辑器的 **Workspace → Project repository access** 中更改此设置。 该设置适用于新会话。现有会话会保留已保存的策略，包括运行时替换后。 ```yaml agents: support: repository_access: false engineer: repository_access: true ``` 已弃用的 `workspace` 字段仍可读取：`branch` 表示 `true`，`runtime` 表示 `false`。 旧版 `read` 配置仍会阻止创建会话，直到你将该字段替换为显式布尔值。 没有只读仓库模式。旧字段与新字段冲突时会被拒绝。 编辑器和 SDK 会发送 `repository_access`。对于禁用访问的情况，API 还会将 `workspace: runtime` 存储为兼容性镜像，以便在推出或回滚期间，较旧的 API 副本也能保留此限制。API 读取时会省略该镜像。仅使用 `repository_access` 的手写清单需要更新后的 API。