---
title: "功能标志"
description: "为一个项目启用 Beeuni 界面，并查看每个标志控制的功能。"
---

功能标志用于为单个项目启用 Beeuni 的一项功能界面。任何功能界面都可以在标志后发布——无论是实验性、Beta 版还是完全稳定的功能。「实验性」是标志的稳定性徽章，不是系统的名称。

标志按项目设置。在一个项目中启用标志不会影响其他项目，也不会影响其他账户。

<CardGroup>
  <Card icon="app-window" title="Apps" href="/docs/zh/feature-flags/apps">将静态网站、bundles、Dockerfile 和 OCI 镜像部署到稳定的 URL。</Card>
</CardGroup>

<a id="turn-a-flag-on"></a>

## 启用标志

1. 打开 **Settings → Feature flags**。此标签页会列出平台支持的所有标志。
2. 查看该行：标志名称、稳定性徽章、一句说明，以及来源——`Default on`、`Default off` 或
   `Overridden for this project`。
3. 使用开关。更改会立即应用于当前项目。

你需要拥有项目的 `project.settings.write` 权限。其他调用者访问该路由时会收到
`403`。

<a id="from-the-cli"></a>

### 使用 CLI

脚本和代理也可以通过 `beeuni projects features` 使用相同的开关：

```bash
beeuni projects features                # every flag: key, state, origin
beeuni projects features enable reminders
beeuni projects features disable reminders
beeuni projects features reset reminders  # drop the override; follow the platform default
beeuni projects features --json          # the full catalog as JSON
```

添加 `--project <id>`，即可操作链接的项目或默认项目之外的其他项目。如果平台标记某个标志为不可用，则无论项目覆盖设置如何，该标志都会保持关闭；CLI 会将其显示为 `n/a` / `unavailable`。

:::info[标志状态不在代码仓库中]
每个项目的标志状态存储在数据库的项目行中，不会从 `beeuni.yaml` 读取。启用的标志不会随代码仓库克隆或派生而转移。
:::

<a id="stability-badges"></a>

## 稳定性徽章

徽章描述的是契约，而不是开关。`stable` 标志仍然需要主动选择启用：`apps` 是稳定的，但默认仍处于关闭状态。

| 徽章 | 含义 |
|---|---|
| Experimental | 功能界面及其契约仍可能发生变化。 |
| Beta | 功能界面可用，形式也逐渐稳定。 |
| Stable | 契约稳定。该标志仍需主动选择启用。 |

<a id="how-a-flag-is-enforced"></a>

## 标志的执行方式

每个标志都声明一种执行模式。

| 模式 | 标志关闭时服务器的行为 |
|---|---|
| `routes` | HTTP 接口会以 `403` 拒绝请求。 |
| `behavioral` | 不会发生相应行为——不会生成连接器、不会注入环境变量，也不会注册代理。 |
| `ui-only` | 服务器有意不执行检查。该标志仅隐藏客户端界面。 |

`routes` 拒绝响应在任何地方都完全相同：

```json
{
  "error": "Apps is not enabled for this project. Contact Beeuni to enable it.",
  "code": "feature_disabled",
  "feature": "apps"
}
```

`error` 字符串指的是标志列表，而不是某个特定标签页。该列表位于 Settings 的 **Experimental** 标签页。

应根据 `code` 进行分支判断，绝不要根据消息文本判断。SDK 导出了 `isFeatureDisabledError(error)` 和 `featureDisabledKey(error)`，专供此用途。

<a id="every-flag"></a>

## 所有标志

注册表顺序——与 **Settings → Feature flags** 中显示的顺序相同。

Apps 和 Backends 由 Beeuni 按项目启用。联系 Beeuni 申请开通。启用后，设置中会显示**由 Beeuni 管理**。

| 键 | 名称 | 稳定性 | 默认值 |
|---|---|---|---|
| `marketplace` | Marketplace | Beta | 开启 |
| `connectors_api_discover` | Connectors API Discover | Experimental | 关闭 |
| `agentmail_email` | AgentMail Email | Experimental | 关闭 |
| `llm_gateway` | LLM Gateway | Experimental | 开启（运维人员可以将默认值设为关闭） |
| `meta_agent` | Meta Agent | Experimental | 关闭 |
| `apps` | Apps | Stable | 关闭 |
| `monitors` | Monitors | Experimental | 关闭 |
| `reminders` | Reminders | Beta | 关闭 |
| `warm_sessions` | Warm Sessions | Beta | 开启 |
| `secrets_egress` | Network-Enforced Secrets | Experimental | 开启 |
| `pi_harness` | Pi Harness  | Experimental | 关闭 |

<a id="what-each-flag-gates"></a>

### 每个标志控制的功能

- **`marketplace`** — 从社区和供应商注册表浏览并安装技能。
- **`connectors_api_discover`** — 在 托管 OAuth 应用旁浏览直接 API、MCP、GraphQL、CLI 和 Postman 功能界面。参见 [Connectors](/docs/zh/connect/connectors)。
- **`agentmail_email`** — 分配 AgentMail 收件箱连接，让收到的邮件能够启动并继续会话。
- **`llm_gateway`** — 通过 Beeuni 托管的 LLM 网关路由项目请求。参见 [Models](/docs/zh/project/models)。
- **`meta_agent`** — 添加由平台管理的协调代理，以启动和管理专用会话。
- **`apps`** — 将静态网站、bundles、Dockerfile 和 OCI 镜像部署到稳定的无服务器 URL。参见 [Apps](/docs/zh/feature-flags/apps)。
- **`monitors`** — 从代码仓库运行全天候监视器，并将触发事件发送到会话。参见 [Triggers](/docs/zh/connect/triggers)。
- **`reminders`** — 计划签到，用于向一个会话重新发送提示，可执行一次或重复执行。关闭后，提醒路由会返回 `feature_disabled`，现有提醒也不会触发。参见 [Reminders](/docs/zh/connect/reminders)。
- **`warm_sessions`** — 项目打开期间保持一个沙盒运行，以便新会话无需冷启动即可开始。
- **`secrets_egress`** — 为密钥启用网络强制执行：沙盒持有一个句柄，Beeuni 只会在请求经过批准的主机时替换为真实值。参见 [Secrets](/docs/zh/project/secrets)。
- **`pi_harness`** — 在普通会话沙盒（`BEEUNI_HARNESS=pi`）内，使用 pi 代理运行时来运行此项目的会话。开启时，无论清单中如何设置，每个新会话或重启的会话都会启动 pi。关闭时，由清单决定——`runtime: pi` 仍会启动 pi，其他设置则会启动 默认运行时。pi 只能通过 LLM 网关调用模型：关闭 `llm_gateway` 后，无论此标志或清单如何设置，每个会话都会启动 默认运行时。两种模式使用相同的代码仓库布局、代理和技能；运行中的会话会继续使用当前运行时，直到重启或恢复。pi 支持子代理：代理使用 `task` 工具将任务委派给 `general`、`explore`（只读），或在其 `.md` 中带有 `mode: subagent` 的任何项目代理；对话记录会在原位置显示每个子代理的步骤。pi 会话也会加载 pi.dev 软件包：参见 [`harnesses:`](/docs/zh/project/manifest#harnesses)。pi 并不支持 默认运行时 提供的所有会话功能：参见 [Harnesses](/docs/zh/work/harnesses#what-each-harness-supports) 中的对照表。

<a id="graduated-flags"></a>

### 已普及的标志

已普及的功能会对所有项目启用，且没有开关。

- **Agents as principals** 是无开关的标准行为。代理会话会以代理本身的身份运行——无论由谁启动，它在 Beeuni 中的权限都受其角色上限限制。参见 [Agent permissions](/docs/zh/project/permissions)。
- **Review Center** 已脱离标志系统。每个项目都会显示 Review 页面、侧边栏中的 Review 行和命令面板中的对应行；`project.review.read` 和 `project.review.act` 权限仍然适用。`review_center` 不再是标志键：`PATCH /v1/projects/:id/features` 会返回 `400` `Unknown feature flag`，而 `beeuni projects features enable review_center` prints that error and exits `1`。普及之前存储的覆盖设置不再生效。
- **Computers** 已脱离标志系统。每位成员都可以从项目侧边栏连接自己的计算机；平台的 `TUNNEL_ENABLED` 设置是唯一门控。`agent_tunnel` 不再是标志键：`PATCH /v1/projects/:id/features` 会返回 `400` `Unknown feature flag`。参见 [Computers](/docs/zh/connect/computers)。
- **Microsoft Teams** 已脱离标志系统。每个项目都可以通过 **Connectors → Channels** 连接 Teams；租户管理员仍需授权一次，或者项目可以使用自己的机器人。`teams` 不再是标志键：`PATCH /v1/projects/:id/features` 会返回 `400` `Unknown feature flag`。普及之前存储的覆盖设置不再生效。参见 [Microsoft Teams](/docs/zh/connect/teams)。

<a id="side-effects-of-a-toggle"></a>

## 切换开关的副作用

部分标志会在写入提交后使平台状态趋于一致。

| 标志 | 切换后的效果 |
|---|---|
| `agentmail_email` | Beeuni 会重新执行频道连接器的生成操作，因此连接器会随标志启用或消失。 |
| `llm_gateway` | Beeuni 会将新的提供方模式传播到活动沙盒。 |

这些效果属于状态收敛工作，不是切换操作成功的一部分。API 响应不会等待它们完成。每项效果都会重试一次，其背后的协调器具有幂等性，并会在定期扫描时重新运行。

<a id="read-and-set-a-flag-from-code"></a>

## 在代码中读取和设置标志

通过项目详情或 React hook 读取项目的有效状态：

```tsx
import { useFeatureFlag } from '@beeuni/sdk/react';

function AppsNavItem({ projectId }: { projectId: string }) {
  const apps = useFeatureFlag(projectId, 'apps');
  if (!apps.enabled) return null;
  return <Link href={`/projects/${projectId}/apps`}>Apps</Link>;
}
```

只有当服务器准确返回 `true` 时，`enabled` 才为 `true`。项目 ID 缺失、查询进行中以及查询出错时，结果均为 `false`。门控应采用默认关闭策略。

使用客户端设置项目覆盖：

```ts
const p = beeuni.project(projectId);

await p.updateFeatureFlag('apps', true);   // turn it on for this project
await p.updateFeatureFlag('apps', null);   // clear the override, inherit the default
```

`updateFeatureFlag` 会调用 `PATCH /v1/projects/:id/features`。`feature` 是 `FEATURE_FLAG_KEYS` 之一，导出自 `@beeuni/sdk`，类型为 `FeatureFlagKey`。参见 SDK 参考文档。

通过代码处理功能已禁用的情况，而不是依赖消息文本：

```ts
import { featureDisabledKey, isFeatureDisabledError } from '@beeuni/sdk';

try {
  await beeuni.project(projectId).apps.list();
} catch (error) {
  if (isFeatureDisabledError(error)) {
    console.log(`${featureDisabledKey(error)} is off for this project`);
  }
}
```