代理

Agent 是由会话运行器运行的 Markdown 文件；清单仅控制其访问权限。

代理是一个 Markdown 文件，用于定义运行时在会话中的行为。本页介绍代理文件、技能，以及会话如何选择代理。

每个会话都会运行一个运行时

每个会话都会运行一个代理运行时：标准运行器（默认）或实验运行器。 运行时列出了项目如何选择运行时，以及各运行时支持的功能。

两者都会从 agents/ 读取项目的代理，从 skills/ 读取项目的技能。标准运行器 还会从 harnesses/opencode/ 读取仅供它使用的文件。实验运行器 则从 harnesses/pi/ 读取自己的文件。

2026-09 之前创建的项目会将代理和技能保存在 .beeuni/opencode/ 下。Beeuni 同时支持这两种目录结构。

代理由两个文件组成

每个代理包含两部分：

• 行为 — 一个 Markdown 文件，默认为 agents/<name>.md。其 frontmatter 用于设置模型、模式和权限规则，正文则是系统提示词。
• 治理 — beeuni.yaml 的 agents 映射中的一条记录，以代理名称为键。它设置代理可以访问的内容：连接器、密钥、技能、Apps、Beeuni 权限和工具。其 file 字段指定行为文件。 此映射可以放在清单通过 imports: 列出的文件中；default_agent 保留在 beeuni.yaml 中。

清单不会设置提示词或模式。.md 文件不会设置平台访问权限。有关所有治理字段，请参阅清单参考。

代理文件的位置

agents:
  support:
    file: agents/support.md

• file 是相对于仓库的路径，必须以 .md 结尾。
• 路径不得以 / 开头，也不得包含 . 或 .. 段。
• 如果没有 file，Beeuni 会先读取 agents/<name>.md，再读取 .beeuni/opencode/agents/<name>.md。
• 当仪表板保存带有 .md 的代理时，会将该路径写入 file。
• API 不允许更改 file。要移动代理，请移动其 .md，并在同一次提交中更新 beeuni.yaml 中的 file。

完整路径规则请参阅清单参考。

治理默认拒绝访问

如果代理没有 connectors、secrets、skills、apps 或 beeuni_permissions 键，就不会获得相应访问权限。apps 列出代理在 App 受限或设为私有时可以打开的 Beeuni Apps。这是两项绑定中的第二项：代理还持有 service_account 主体的角色，即其权限上限；会话只能执行两者都允许的操作。请参阅代理权限和一种术语，两项绑定。将字段设为 all 可授予完整访问权限，也可以列出具体名称。在 beeuni.yaml 中，default_agent 指定未请求代理时会话启动的代理。

在仪表板中设置每项授权：Customize → Agents → 代理，然后在 Access 栏中为每组授权打开对应页面：Skills、Connectors、Secrets、Apps、Beeuni permissions；也可以通过 CLI 使用 beeuni agents scope <agent>（--secrets、--connectors、--apps）。只有当项目启用了 Apps 功能标志时，才会显示 Apps 页面。无论通过哪种方式设置，都会在 beeuni.yaml 中写入相同的 agents.<name> 块。

旧版 beeuni.toml（v1）项目会在数组而非映射中列出代理，并默认授予完整访问权限。要限制访问，请设置具体授权。请参阅清单参考。

技能为代理提供专业知识

技能是位于 skills/<name>/SKILL.md 的 Markdown 文件。 运行时会按需加载技能——Beeuni 不会将技能正文注入每条提示词。在标准运行器中，代理会调用 skill 工具。在实验运行器中，系统提示词会列出每项技能的名称和描述，代理再读取文件。代理在 beeuni.yaml 中的 skills 授权决定它可以加载哪些技能。

会话如何选择代理

创建会话时可以提供 agent_name。Beeuni 会为该会话启动指定代理。如果省略 agent_name，Beeuni 会使用项目的 default_agent。可通过仪表板、API 或 SDK 设置默认代理。每种方式都会将 default_agent 写入 beeuni.yaml，并将更改提交到项目的默认分支。

代理始终以自身身份行事：无论由谁运行，它都使用自身在权限上限角色范围内的 Beeuni 权限。启动会话不会将你的角色授予代理。请参阅代理权限。

新增或更改的代理和技能，只有在变更请求将其合并到默认分支后，才会应用于后续会话。代理使用外部工具之前，请先连接这些工具；请参阅连接器。