Harness
一个会话运行一个智能体 Harness：标准运行器 或实验运行器。本页面介绍项目如何选择其中一个，以及各自支持的功能。
Harness 是会话沙箱中的 agent 运行时。它运行模型循环、调用工具并生成对话记录。Beeuni 有两个 harness：标准运行器（默认）和 实验运行器。每个会话恰好运行一个。
两个 harness 读取相同的项目内容：beeuni.yaml、agents/ 中的 agent 文件、skills/ 中的技能、根目录 AGENTS.md，以及 memory/。各客户端（Web、CLI、TUI、移动端、SDK）通过同一个会话 API 读取两者。区别在于下方矩阵所列的会话功能，以及每个 harness 读取的自身配置文件。
会话如何选择 harness
Beeuni 会在会话启动、重启或恢复时做出决定。在此之前，运行中的会话会一直使用原来的 harness。
| 规则（按顺序） | Harness |
|---|---|
项目的 llm_gateway 标志为关闭 |
标准运行器 |
项目的 pi_harness 标志为开启 |
实验运行器 |
beeuni.yaml 将 runtime: pi 设为相应值 |
实验运行器 |
| 其他情况 | 标准运行器 |
-实验运行器只能通过 Beeuni LLM 网关调用模型。llm_gateway 关闭的项目会启动标准运行器，无论标志或清单如何设置。请参阅模型。
runtime是beeuni_version: 2清单键。旧版beeuni.toml项目无法设置此键。请参阅清单参考。pi_harness是按项目设置的功能标志，默认关闭。请参阅功能标志。
要查看会话运行的是哪个 harness，请读取沙箱守护进程的 GET /beeuni/health 响应中的 harness.id：opencode 或 pi。
各 harness 支持的功能
Harness 会在 GET /beeuni/health 的 capabilities 数组中列出其提供的可选会话功能。如果会话的 capabilities 中没有相应 ID，客户端就会隐藏该控件。SDK 中的检查项是 runtimeSupports。
两个 harness 均支持
| 功能 | 标准运行器 | 实验运行器 |
|---|---|---|
| 聊天轮次、流式传输、停止 | 是 | 是 |
Agent .md：提示词、model、variant、mode、permission、temperature、top_p、steps |
是 | 是。实验运行器 不应用 options（provider 选项）。 |
按 agent 设置工具访问权限（beeuni.yaml 中的 agents.<name>.tools：all、none、列表、exclude） |
是 | 是 |
按 agent 设置 permission 规则和权限请求 |
是 | 是 |
问题（question 工具） |
是 | 是 |
项目的根目录 AGENTS.md 规则文件；如果根目录中没有 AGENTS.md，则使用 CLAUDE.md |
是。标准运行器 也会读取 /workspace 的父目录中的文件，并在运行配置发布时读取 /workspace。 |
是，仅根目录文件。它是会话和每个子 agent 系统提示词的一部分。启用配置发布时，实验运行器 读取发布副本。 |
子 agent（task 工具）、session.subagents |
是 | 是：general、explore（只读），以及每个带有 mode: subagent 或 all 的项目 agent。子 agent 不能再启动其他子 agent。 |
技能（skills/ 和受管理的 beeuni-* 技能），受 agent 的 skills 授权控制 |
是。Agent 使用 skill 工具加载技能。 |
是。系统提示词会列出每个获授权的技能；agent 会读取对应文件。 |
Beeuni 工具：web_search、image_search、scrape_webpage、memory、show。如果 beeuni.yaml 中没有 tools: 键，则五个工具全部启用；如果有，则启用其中列为 beeuni:<name> 的工具 |
是 | 是 |
项目工具（beeuni.yaml 中的 tools:） |
是 | 是 |
配置发布、config.release.v1 |
是 | 是 |
按需或在模型上下文窗口接近上限时自动精简（总结）对话，session.compact |
是 | 是。模型请求超出窗口时会精简上下文并重试一次。 |
项目斜杠命令，session.commands |
是，来自标准运行器配置目录中的 commands/。 |
是，来自实验运行器配置目录和实验运行器包中的 prompts/ 提示词模板。实验运行器 不读取标准运行器的 commands/。 |
| 沙箱中的终端（PTY） | 是 | 是 |
bash、read、write、edit、glob、grep 工具；Shell 中的密钥；beeuni CLI |
是 | 是 |
Beeuni 工具和项目工具与 harness 无关](/docs/zh/project/tools)：沙箱守护进程为两个 harness 的每种工具运行同一个模块，名称、参数和输出均相同。实验运行器 在守护进程的进程中调用这些工具；标准运行器 则通过守护进程编写的插件调用。两个 harness 获取相同的工具列表：如果项目的 tools: 键未列出某个 Beeuni 工具，两个 harness 都不会启用该工具。项目中如果 harnesses/opencode/tools/ 仍留有 Beeuni 工具的副本，标准运行器 会继续保留这些副本，直到项目将其删除。
两个 harness 上的 Web 工具都遵循 websearch（web_search、image_search）和 webfetch（scrape_webpage）权限键。在标准运行器中，这些工具无法请求权限：ask 规则会拒绝它们。在实验运行器中，ask 规则会发起权限请求。在实验运行器中，修改文件的 memory 命令遵循 edit，而 view 遵循 read；在标准运行器中，只有 memory 规则会控制该工具。
AGENTS.md 在实验运行器中
实验运行器 会将项目根目录中的 AGENTS.md 作为一个章节放入系统提示词中，位置在 agent 提示词之后，即 <project_instructions path="AGENTS.md">。如果根目录中没有 AGENTS.md，则会像标准运行器一样改用 CLAUDE.md。实验运行器 不读取子目录或父目录中的任何 AGENTS.md。
- **来源。**关闭配置发布时，实验运行器 读取
/workspace/AGENTS.md。启用后，实验运行器 读取发布中的副本，不会读取/workspace中的文件：在/workspace中的更改要合并到基分支后才会对会话生效。启用配置发布但没有可用的发布版本（config.source: image-default）时，实验运行器 不读取任何AGENTS.md，就像它不会读取任何项目技能一样。 - **时机。**实验运行器 会在运行时启动、配置重新加载（新发布版本、
/beeuni/env推送）以及仓库刷新后读取此文件。它不会在每轮对话前读取。新发布版本无需重启即可在下一轮生效；正在进行的轮次仍使用旧文件。 - **跳过的文件。**空文件、非普通文件，以及解析到仓库外部的符号链接都不会产生任何内容。后两种情况会在守护进程日志中写入一条警告。
- **检查。**守护进程
GET /beeuni/health中的harness.details.agentsMd会列出实验运行器加载的文件：source（release或workspace）、path、bytes和sha（其 sha256 的前 12 个十六进制字符）。如果实验运行器未加载任何文件，则为null。
目前仅标准运行器支持
| 功能 | 能力 | 标准运行器 | 实验运行器 |
|---|---|---|---|
| 回退到某条消息并恢复。编辑后重新发送会使用回退功能。 | session.rewind |
是 | 否 |
MCP 服务器（opencode.jsonc 中的 mcp） |
session.mcp |
是 | 否。没有 MCP 客户端。连接器可通过 beeuni connectors CLI 在两个 harness 上使用。 |
待办列表（todowrite 工具）和计划卡片 |
session.todo |
是 | 否。计划卡片保持为空。 |
连接 harness 自带的终端客户端（beeuni connect、TUI Alt+o） |
session.attach |
是 | 否。请参阅TUI。 |
运行时配置文档（/global/config） |
session.config |
是 | 否。两个 harness 的 agent 和模型都来自项目。 |
| 在某条消息处分叉会话 | session.fork |
是 | 否 |
| 作为一个轮次运行 Shell 命令 | session.shell |
是 | 否 |
| 不通过 LLM 网关的模型提供方 | — | 是 | 否。实验运行器 需要开启 llm_gateway。 |
实验运行器 会通过 501 feature_not_supported 响应它不提供的功能请求；如果请求的是它没有的文档（/global/config），则会返回 404。它不会忽略该请求。
Harness 配置文件
每个 harness 都有一个专用目录，存放仅由该 harness 读取的文件。
| 标准运行器 | 实验运行器 | |
|---|---|---|
| 目录 | harnesses/opencode/，或 opencode.config_dir |
harnesses/pi/，或 pi.config_dir |
| 旧版目录 | .beeuni/opencode/ |
.beeuni/pi/ |
| 内容 | opencode.jsonc、plugins/、tools/、commands/ |
settings.json、extensions/、skills/、prompts/ |
| 扩展 | 该目录中的插件和仅供标准运行器使用的工具 | harnesses.pi.packages 中的 实验运行器 包，以及 extensions/ 中的扩展文件 |
实验运行器 会话不会读取 opencode.jsonc、plugins/、tools/ 或 commands/。标准运行器 会话不会读取实验运行器目录。两个 harness 都需要的工具应是项目工具，并在 beeuni.yaml 中声明，而不是放在任一目录中的文件。
实验运行器 包来自 packages。包可以为实验运行器添加原本不具备的工具，例如 MCP 适配器或待办工具。Beeuni 会加载该包，但不会测试第三方包。