Manifest 参考

beeuni.yaml v2 的所有键，包含默认值、限制和验证规则。

Manifest 是平台视为项目权威配置的文件。本页列出每个 beeuni.yaml (v2) 键、其类型、默认值以及平台如何验证它。通俗版请参阅 你的项目。

两种配置界面

Beeuni 项目有两种配置界面，所有权严格分开，互不重叠。

• Beeuni 配置 — 仓库根目录中的 beeuni.yaml 定义项目环境、Agent、工具、连接器和触发器。沙盒模板可以引用自定义 Dockerfile。
• Agent 配置 — agent 文件、技能和 harness 文件。agent harness 会在沙盒中和本地读取这些内容。

2026-09 之前创建的项目会将 agents 和技能放在 .beeuni/opencode/ 下，将记忆放在 .beeuni/memory/ 下。Beeuni 可读取这两种布局。

两部分通过 agent 的 .md 文件连接。Manifest 键 agents.<name> 管理 agents.<name>.file 指定的文件；如果省略 file，则管理 agents/<name>.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。

beeuni_version: 2 必须使用 YAML——声明了 beeuni_version: 2 的 .toml 文件无法通过验证。声明的版本高于 2 的 manifest 会被直接拒绝，因此平台不会静默误读未来版本的字段。未知的顶层键会被忽略，因此你可以在文件中存放自己的元数据。

validateManifest() 是 beeuni ship、变更请求合并检查和 beeuni validate 背后的统一关卡。各处应用相同的规则，因此任何合并到 main 的内容在结构上都是有效的。架构是公开的，并由同一个软件包生成：

• beeuni.v2.schema.json
• beeuni.v1.schema.json
• beeuni.schema.json（根据 beeuni_version 分发）

将 beeuni.yaml 指向 v2 架构，以启用编辑器验证；也可以通过 CLI 获取：

# yaml-language-server: $schema=https://beeuni.ai/schema/beeuni.v2.schema.json
beeuni_version: 2

beeuni schema --version 2

完整示例

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.

顶层键

imports:

将一个 manifest 拆分到多个 YAML 文件中。当 beeuni.yaml 长到无法在一个屏幕内显示时，可以使用这种方式：例如包含多行提示词的 30 个触发器、每个团队一个连接器，或每个 agent 组一个文件。

# 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

beeuni.yaml
agents.yaml
triggers/
  reports/
    weekly.yaml
    monthly.yaml
  dockets/
    freedom-forever.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 之前报告它：

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:

会话按名称获取的工具。值有以下两种形式之一：

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。

选择规则。

• 根文件和任何导入文件中都没有 tools 键：会话会获取全部五个 Beeuni 工具。工具列表存在之前创建的每个项目都会保留这些工具。
• 存在 tools 键，即使为空（tools: {}，或删除了所有行的 tools:）：会话只会获取其中列出的 Beeuni 工具，形式可以是 beeuni:<name> 或模块路径。导入文件中的 tools 键也计算在内。

删除 beeuni:<name> 行即可从所有代理中移除该工具。使用 agents.<name>.tools 可限制到单个代理。

错误。

• 名称必须使用 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:<name> 会报错。例如，在 Beeuni 工具名称下使用 web_search: beeuni:image_search：

  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:<name>，例如 web_serch: beeuni:web_serch：

  tools.web_serch: must be a repo-relative path to a .ts or .js module (e.g. `tools/web_serch.ts`). `beeuni:<name>` 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 工具中的任何一个：

  tools: Sessions of this project get no Beeuni tool (web_search, image_search, scrape_webpage, memory, show). Add `<name>: beeuni:<name>` to keep one.

  它用于捕获项目添加第一个自有工具却意外移除这五个工具的情况。

• 代理的 tools 指定了项目未加载的 Beeuni 工具：

  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 页面中，从不直接写入清单。平台会在会话启动时将其解密并以普通环境变量的形式注入。

env:
  required: [DATABASE_URL]
  optional: [STRIPE_API_KEY]

环境变量名称必须符合 ^[A-Z_][A-Z0-9_]*$。Secrets Manager 将名称长度限制为 64 个字符——更长的名称可以在此处解析，但永远无法获取值。以 BEEUNI_ 开头的名称也永远无法获取值。名称请保持在 64 个字符以内，并避免使用 BEEUNI_ 前缀。完整契约：Secrets。

sandbox: 和 sandbox.templates

可启动的命名沙箱镜像列表。可选——没有条目时，每个会话都会启动平台的默认镜像。每个模板必须恰好指定 dockerfile（相对于仓库）或 image（公共 Docker 引用，并固定标签或摘要）之一。

sandbox:
  templates:
    - slug: ml
      name: ML Development
      dockerfile: Dockerfile.ml
      cpu: 4
      memory: 16
      disk: 50

每个值都必须是正整数。低于最小值会导致验证失败并报错。高于最大值则会通过验证并显示警告，随后在运行时截断到上限。不支持 GPU——声明 gpu 会产生警告，不会报错。参见 Runtime，了解运行时层会在你的镜像之上注入哪些内容。

sandbox.default

在 sandbox 中设置 default，将一个模板设为项目默认模板。此后，每个会话、触发器和频道都会启动该模板，无需指定 slug。

sandbox:
  default: dev
  templates:
    - slug: dev
      dockerfile: Dockerfile.dev

default 必须指定此清单中声明的模板，或指定保留值 "default"，以使用平台镜像。

智能体可以通过 agents.<name>.sandbox 选择其环境。该值必须指定清单或控制面板中的模板，或指定 "default"。

agents:
  researcher:
    sandbox: ml

会话模板按以下顺序解析：

1. 显式指定的会话 sandbox_slug。
2. 所选智能体的 sandbox。
3. 项目的 sandbox.default。
4. 平台的 "default"。

Cron 触发器、webhook 触发器、计划任务和频道使用所选智能体的模板。

更改规格（cpu、memory、disk、container_runtime 或镜像本身）会重建项目快照。新的规格会在下一个会话中生效，不会影响正在运行的会话。

opencode:

标准运行器 配置目录的位置。可选，并有默认值。

opencode:
  config_dir: harnesses/opencode

未设置 config_dir 时，Beeuni 会依次检查 harnesses/opencode 和 .beeuni/opencode，并使用第一个包含 opencode.json 或 opencode.jsonc 的目录。该目录用于存放仅供标准运行器读取的文件：opencode.jsonc、plugins/、tools/ 和 commands/。智能体和技能位于仓库根目录的 agents/ 和 skills/ 中。opencode.jsonc 仍是标准运行器原生的插件、MCP 服务器、提供商和权限注册表——不要在清单中重复这些设置。参见 Agents。

harnesses:

各运行框架的设置。pi.config_dir 指向实验运行器原生配置所在的相对仓库目录（默认依次为 harnesses/pi 和 .beeuni/pi）。实验运行器 启动时会导入此目录。pi.packages 则单独负责为每个智能体安装清单中 harnesses.pi.packages 指定的软件包。目前只有一个软件包键：pi.packages，即此项目的每个实验运行器会话都会加载的实验运行器软件包（runtime: pi，或 pi_harness 标志）。软件包可以是 packages 中的任何内容：扩展（工具、钩子、命令），以及软件包附带的技能和提示。

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

最多可有 20 个条目。不接受 Git 来源。

按智能体设置

智能体可以添加自己的软件包，并在 agents.<name>.harnesses 中移除顶层软件包：

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 作为第一条消息运行。

triggers:
  - slug: daily-digest
    type: cron
    cron: '0 0 9 * * 1-5'
    prompt: Summarize yesterday's commits.

Cron 触发器必须且只能指定 cron（6 字段表达式）或 run_at（一次性 ISO-8601 时间戳）之一，并指定作为 IANA 名称的 timezone。Webhook 触发器需要 secret_env，即一个密钥的名称，该密钥使用 broker 投递方式和 connector 消费者。监控触发器需要 run（相对于仓库的命令）和 mode（poll 或 stream），并且不接受任何 cron 或 webhook 字段。完整字段参考、凭据设置、负载模板化、端点和会话策略，请参见 Triggers。

connectors:

智能体可调用的外部工具列表。定义存储在 git 中；凭据存储在平台中，绝不放在清单中。概念模型请参见 Connectors。

connectors:
  - slug: gmail-read
    name: Gmail read only
    provider: pipedream
    app: gmail
    authorization_strategy: user
    policies:
      - match: search_email
        action: always_run

提供商专属字段：

channel 连接器很少需要手动编写条目——在仪表板中连接频道会自动创建条目。参见 Slack & channels。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 <risk|allow_all> 设置 — 参见 CLI。

通道

v2 从架构中移除了 channels:。通道到代理的路由（目前支持 Slack、Microsoft Teams、电子邮件和语音）属于实时运营状态，而不是声明式配置。你可以在控制面板的 Channels 页面中设置，也可以通过聊天命令设置；这与凭据不进入 git 的边界相同。连接通道仍会创建一个带有 provider: channel 的 connectors 条目，供代理调用。参见 Slack & channels。v1 的 [[channels]] 表格详见 Legacy TOML。

agents:

按代理名称作为键的名称到区块映射。此映射仅用于治理——它授予代理可以接触的内容，而绝不决定代理说什么或做什么。

此区块是两个绑定中的第二个：主体从 Beeuni 获得角色，而代理还会携带此处声明的 Beeuni 权限。会话只能执行两者都允许的操作。参见 One vocabulary, two bindings。

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]

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.<name>.file 指定代理的 .md，路径相对于仓库根目录。

agents:
  support:
    file: agents/support.md

• 路径必须以 .md 结尾。
• 路径不得以 / 或 - 开头。不得包含 . 或 .. 段，也不得包含空段。
• 每个段只能使用字母、数字、_、-、. 和空格。
• 省略 file 时，Beeuni 会读取 agents/<name>.md，然后读取 .beeuni/opencode/agents/<name>.md。设置 opencode.config_dir 后，第二个路径为 <config_dir>/agents/<name>.md。
• 控制面板保存带有 .md 的代理时，会写入带有该路径的 file。
• API 会拒绝更改 file 的请求（400，代码 invalid_config）。要移动代理，请移动其 .md，并在同一提交中更新 beeuni.yaml 中的 file。

beeuni validate 和变更请求合并检查会拒绝无效的 file，并在 agents.<name>.file 上报错。

配置变更何时生效

• 清单、agents/、skills/ 或标准运行器配置目录的编辑，只有在变更请求合并到 main 后才会生效。会话和触发器读取的是默认分支，而不是会话分支。
• 触发器的 cron 或 webhook 变更会在合并后数秒内由调度器读取。
• 沙盒映像或硬件变更会重建快照。新规格会在下一个会话中生效，不会影响当前会话。
• 在控制面板中更改密钥值，会在创建沙盒时解析。新值会在下一个会话中生效，不会影响正在运行的会话。

往返规则

控制面板编辑会对声明该条目的文件执行读取-修改-写入操作：beeuni.yaml，或导入的文件。为确保 UI 和会话内编辑之间的差异保持简洁：

1. 将 beeuni_version 保持为第一个键。
2. 在触发器条目内，依次排列字段：slug、name、type、agent、enabled，然后是特定于类型的字段，最后是 prompt。
3. 如果在设置密钥之前添加 webhook 触发器，请在 env.optional 中列出密钥名称。在填入密钥值之前，将触发器保持为 enabled: false。

仓库访问权限

对于不需要项目源文件的代理，将 agents.<name>.repository_access 设为 false。 它们仍可创建沙盒文件，并使用获准的工具、密钥和连接器。 对于需要访问仓库的代理，将其设为 true。Git 权限仍单独管理。 在代理编辑器的 Workspace → Project repository access 中更改此设置。 该设置适用于新会话。现有会话会保留已保存的策略，包括运行时替换后。

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。