# 代理

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

Canonical page: https://beeuni.ai/docs/zh/project/agents

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

<a id="a-harness-runs-every-session"></a>

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

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

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

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

<a id="an-agent-is-two-files"></a>

## 代理由两个文件组成

每个代理包含两部分：

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

清单不会设置提示词或模式。`.md` 文件不会设置平台访问权限。有关所有治理字段，请参阅[清单参考](/docs/zh/project/manifest)。

<a id="where-the-agent-file-lives"></a>

### 代理文件的位置

```yaml
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`。

完整路径规则请参阅[清单参考](/docs/zh/project/manifest#the-agent-file)。

<a id="governance-is-deny-by-default"></a>

## 治理默认拒绝访问

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

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

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

<a id="skills-give-an-agent-know-how"></a>

## 技能为代理提供专业知识

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

<a id="how-a-session-picks-its-agent"></a>

## 会话如何选择代理

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

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

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