# @frontmcp/plugin-feature-flags 中文文档

规范地址：https://npmcn.com/package/%40frontmcp/plugin-feature-flags/

版本：1\.12\.2
npm 元数据更新时间：2026-11-14T21:10:04.867Z
中文译文更新时间：2026-11-15T15:19:02.710Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40frontmcp/plugin-feature-flags
原文对照：https://npmcn.com/package/%40frontmcp/plugin-feature-flags/?lang=original
项目主页：https://frontmcp.dev/reference/plugins/feature-flags
源码仓库：https://github.com/agentfront/frontmcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：121 kB，38 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：0 个
- peer 依赖：@frontmcp/sdk 1\.12\.2，unleash-client ^5\.0\.0 \|\| ^6\.0\.0，@splitsoftware/splitio ^10\.0\.0 \|\| ^11\.0\.0，@launchdarkly/node-server-sdk ^9\.0\.0 \|\| ^10\.0\.0
- 首次发布：2026-03-16T18:08:12.516Z
- 最新版本发布：2026-11-14T21:10:04.496Z
- 近 30 天下载量：5363（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：98（近 12 个月 98 个）

## 中文简介

FrontMCP 特性旗插件 - 特性旗后动态闸门 MCP 能力

## 安装

```sh
npm install @frontmcp/plugin-feature-flags
```

也可以使用：`pnpm add @frontmcp/plugin-feature-flags`、`yarn add @frontmcp/plugin-feature-flags`、`bun add @frontmcp/plugin-feature-flags`

## README

# @ frontmcp/plugin-feature-flags (英语)

转换工具、资源、资源模板、提示、技能和代理 [前线MCP](https://frontmcp.dev/) 服务器 打开和关闭带有特征标记。 给出条目 `featureFlag: 'bulk-export'`而当那面旗子被关闭 呼叫者, 条目被从每个列表中忽略出来,并在被调用时被拒绝,这样您就可以在之前将一个能力发送给一些用户 每个人。 旗帜来自固定值、 启动暗中、 分拆、 解脱或您的适配器, 并分别被评价 来电 在你的密码里, `this.featureFlags` 读取一面旗帜.

[![npm](https://img.shields.io/npm/v/@frontmcp/plugin-feature-flags.svg)](https://www.npmjs.com/package/@frontmcp/plugin-feature-flags) [![License](https://img.shields.io/npm/l/@frontmcp/plugin-feature-flags.svg)](https://github.com/agentfront/frontmcp/blob/main/LICENSE)

## 安装

```bash
npm install @frontmcp/plugin-feature-flags
```

插件运行在 FrontMCP 服务器内, 因此您的应用程序需要 `@frontmcp/sdk`,与本软件包同版本,以及 节点.js 24或后.

旗下服务的SDK是可选的对等依赖. 为您使用的适配器安装 :

| `adapter` | 安装 |
| --- | --- |
| `'launchdarkly'` | `@launchdarkly/node-server-sdk` (9个、10个) |
| `'splitio'` | `@splitsoftware/splitio` (10,11) (中文(简体) ) |
| `'unleash'` | `unleash-client` (第5、6段) |

没有它, 服务器无法启动错误, 如 `LaunchDarkly SDK not found. Install it: npm install @launchdarkly/node-server-sdk`编辑 `'static'` 财务报告和审定财务报表 `'custom'` 适配器不需要别的.

## 使用量

注册插件为 `FeatureFlagPlugin.init()`门条目 `featureFlag`数字 :

```ts
import { FeatureFlagPlugin } from '@frontmcp/plugin-feature-flags';
import { App, FrontMcp, Tool, ToolContext, z } from '@frontmcp/sdk';

@Tool({
  name: 'bulk_export',
  description: 'Export every ticket as CSV',
  inputSchema: {},
  featureFlag: 'bulk-export',
})
class BulkExportTool extends ToolContext {
  async execute() {
    return { csv: 'id,title\nT-1,Cannot log in' };
  }
}

@Tool({ name: 'search_tickets', description: 'Search support tickets', inputSchema: { query: z.string() } })
class SearchTicketsTool extends ToolContext {
  async execute({ query }: { query: string }) {
    const ranking = (await this.featureFlags.isEnabled('semantic-search', false)) ? 'semantic' : 'keyword';
    return { query, ranking, tickets: ['T-1'] };
  }
}

@App({ id: 'help-desk', name: 'Help Desk', tools: [SearchTicketsTool, BulkExportTool] })
class HelpDeskApp {}

@FrontMcp({
  info: { name: 'help-desk', version: '1.0.0' },
  apps: [HelpDeskApp],
  plugins: [
    FeatureFlagPlugin.init({
      adapter: 'static',
      flags: { 'bulk-export': false, 'semantic-search': true },
    }),
  ],
})
export default class Server {}
```

给 `bulk_export` 被删除 `tools/list`被拒绝 `Tool "bulk_export" is disabled by feature flag "bulk-export"` 代码 `FEATURE_FLAG_DISABLED`。 。 。 .

注册于 `@FrontMcp`,插件打开每个应用程序的条目。 登记在 `@App`它的大门 应用的条目, 以及任何没有自身特性旗插件的应用程序。 如果一个条目宣布 `featureFlag` 没有地标 插件到达它,服务器不会启动.

## 这个 `featureFlag` 选项

该插件添加 `featureFlag` 改为 `@Tool`, (中文(简体) ), `@Resource`, (中文(简体) ), `@ResourceTemplate`, (中文(简体) ), `@Prompt`, (中文(简体) ), `@Skill` 财务报告和审定财务报表 `@Agent`数字 :

| 表单 | 含义 |
| --- | --- |
| `'key'` | 由国旗标注 `key`。当适配器没有答案时,条目即关闭,除非插件 `gateDefaultValue` 实值 `true`。 。 。 . |
| `{ key, defaultValue }` | 同样,除了 `defaultValue` 决定适配器何时对旗帜没有答案,或扔出. 适配器的一面旗子就停了. |

## 选项

`adapter` 选择旗帜来自何处,以及它需要哪些其他选项:

| `adapter` | 所需经费 | 旗帜来自 |
| --- | --- | --- |
| `'static'` | `flags: Record<string, boolean | FeatureFlagVariant>` | 你给的价值. |
| `'launchdarkly'` | `config: { sdkKey }` | 发射黑暗. |
| `'splitio'` | `config: { apiKey }` | 分开. |
| `'unleash'` | `config: { url, appName, apiKey? }` | 释出. |
| `'custom'` | `adapterInstance: FeatureFlagAdapter` | 你的适应器. |

每个适配器还需要:

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `defaultValue` | `boolean` | `false` | 什麽 `this.featureFlags.isEnabled()` 返回,当调用不通过默认时,指向未知的旗帜或错误. |
| `gateDefaultValue` | `boolean` | `false` | 哪些列表和大门回答未知的旗帜, 或适配器错误, 当条目是 `featureFlag` 没有 `defaultValue`。 。 。 . `true` 无法打开 . |
| `cacheStrategy` | `'session' | 'request' | 'none'` | `'none'` | 缓冲 `this.featureFlags.isEnabled()` 结果。 列表和大门从不缓存 . |
| `cacheTtlMs` | `number` | `30000` | 缓存结果持续多久, 以毫秒计 . |
| `userIdResolver` | `(ctx: FrontMcpContext) => string | undefined` | 签名用户 | 这个 `userId` 适配器评估旗帜。 一个匿名电话商没有. |
| `attributesResolver` | `(ctx: FrontMcpContext) => Record<string, unknown>` | `{}` | 瞄准属性,如租户或计划. |

`FeatureFlagPlugin.init()` 没有支持 `adapter` 丢出一个 `FeatureFlagConfigurationError`。 。 。 .

```ts
FeatureFlagPlugin.init({
  adapter: 'launchdarkly',
  config: { sdkKey: process.env.LAUNCHDARKLY_SDK_KEY! },
  attributesResolver: (ctx) => ({ plan: ctx.authInfo?.extra?.['plan'] }),
});
```

### 自己的适配器

传递任何执行对象 `FeatureFlagAdapter` 作为 `adapterInstance`此处 `flagService` 代表你的旗帜 服务的客户端 :

```ts
import { FeatureFlagPlugin, type FeatureFlagAdapter } from '@frontmcp/plugin-feature-flags';

const flagAdapter: FeatureFlagAdapter = {
  async isEnabled(flagKey, context) {
    return (await flagService.isOn(flagKey, context.userId)) === true;
  },
  async getVariant(flagKey, context) {
    const enabled = (await flagService.isOn(flagKey, context.userId)) === true;
    return { name: enabled ? 'on' : 'off', value: enabled, enabled };
  },
  async evaluateFlags(flagKeys, context) {
    const results = new Map<string, boolean>();
    for (const flagKey of flagKeys) {
      const answer = await flagService.isOn(flagKey, context.userId);
      if (answer !== undefined) results.set(flagKey, answer);
    }
    return results;
  },
};

FeatureFlagPlugin.init({ adapter: 'custom', adapterInstance: flagAdapter });
```

-   `evaluateFlags()` 名单、大门和 `this.featureFlags.isEnabled()` 电话 留个钥匙 你什么都不知道 约,所以打电话者 `defaultValue` 应用; 回答 `false` 为了一面旗子的关闭.
-   `getVariant()` 服务 `this.featureFlags.getVariant()`。 。 。 . `isEnabled()` 需要,尽管插件不叫它.
-   可选 `initialize()` 服务器启动时运行,以及 `destroy()` 当被处理.
-   可选 `subscribe(listener)` 电话 `listener` 当旗帜可能已经更改并返回停止的函数时 这个 用它,旗子翻转发送连接的客户端 `list_changed` 上面有你们的旗门 斯普利特.io号, 暗地发射和Unleash适配器执行.

内置适配器也导出: `StaticFeatureFlagAdapter`, (中文(简体) ), `LaunchDarklyFeatureFlagAdapter`, (中文(简体) ), `SplitioFeatureFlagAdapter` 财务报告和审定财务报表 `UnleashFeatureFlagAdapter`。 。 。 .

### 旗帜为 `enabled`

`featureFlagSource(adapter, ref)` 作为SDK的旗帜 `EnabledSource`,用于 `enabled` 工具、资源、模板 或迅速。 给插件一个相同的适配器。 SDK 然后过滤列表, 拒绝该条目 `FEATURE_OFF` 补救措施 `Turn on the feature flag "beta".`发送 `list_changed` 当适配器报告变化时。 这个 一个适配器的源在 SDK 客户端上共享一个收听器 :

```ts
import { FeatureFlagPlugin, featureFlagSource, UnleashFeatureFlagAdapter } from '@frontmcp/plugin-feature-flags';

const flags = new UnleashFeatureFlagAdapter({ url: 'https://unleash.example.com/api', appName: 'my-mcp-server' });

@Tool({ name: 'beta_report', inputSchema: {}, enabled: featureFlagSource(flags, 'beta-reports') })
class BetaReportTool extends ToolContext {}

FeatureFlagPlugin.init({ adapter: 'custom', adapterInstance: flags });
```

## `this.featureFlags`

`this.featureFlags` 可用工具、资源和提示,并评估当前呼叫者的旗帜:

| 方法 | 回返 | 说明 |
| --- | --- | --- |
| `isEnabled(flagKey, defaultValue?)` | `Promise<boolean>` | 国旗价值. 对于未知的旗帜,或适配器错误: `defaultValue`,否则插件的,否则 `false`。 。 。 . |
| `getVariant(flagKey)` | `Promise<FeatureFlagVariant>` | 旗帜的变体, `{ name, value, enabled }`。适配器错误被抛出. |
| `evaluateFlags(flagKeys)` | `Promise<Map<string, boolean>>` | 在一个适配器呼叫中几面旗帜. 适配器错误被抛出 . |
| `resolveRef(ref)` | `Promise<boolean>` | A 的价值 `featureFlag` 参考:密钥,或 `{ key, defaultValue }`。 。 。 . |

`this.get(FeatureFlagAccessorToken)` 返回同一个访问器,并且 `this.tryGet(FeatureFlagAccessorToken)` 返回它 或者说 `undefined` 在未安装插件的地方.

## 当国旗服务失败时

| 何处 | 适配器抛出时会发生什么 |
| --- | --- |
| 名单,例如 `tools/list` | 裁判 `defaultValue`,否则插件的 `gateDefaultValue`,则 `false`在日志中发出警告。 余所表已讫. |
| 一个大门,比如 `tools/call` | 裁判 `defaultValue`,否则插件的 `gateDefaultValue`,则 `false`。 。 。 . |
| `this.featureFlags.isEnabled()` | 电话是 `defaultValue`,否则插件的 `defaultValue`,则 `false`。 。 。 . |
| `getVariant()`, (中文(简体) ), `evaluateFlags()` | 错误被丢入您的代码 . |

最多 1.11.2 个列表因适配器出错而失败(`-32603`),并且没有应用默认值.

## 文档

-   [特性旗插件引用](https://frontmcp.dev/reference/plugins/feature-flags):每个选项,每个适配器, 瞄准目标 排除出问题.
-   [打开和关闭特性](https://frontmcp.dev/learn/turning-features-on-and-off):分步向导.

## 相关软件包

-   [`@frontmcp/sdk`](https://www.npmjs.com/package/@frontmcp/sdk): FrontMCP 框架 此插件运行在其中 .
-   [`@frontmcp/plugin-approval`](https://www.npmjs.com/package/@frontmcp/plugin-approval): 拒绝工具直到 批准情况为打电话者记录.

## 捐款

资料来源: [`plugins/plugin-feature-flags`](https://github.com/agentfront/frontmcp/tree/main/plugins/plugin-feature-flags)问题 欢迎抽取请求;见 [捐款额](https://github.com/agentfront/frontmcp/blob/main/CONTRIBUTING.md)。 。 。 .

## 许可证

阿帕奇2.0 (英语). 见 [自由主义](https://github.com/agentfront/frontmcp/blob/main/LICENSE)。 。 。 .

## 常见问题

### @frontmcp/plugin-feature-flags 是什么？

FrontMCP 特性旗插件 - 特性旗后动态闸门 MCP 能力

### 如何安装 @frontmcp/plugin-feature-flags？

在项目目录运行 npm install @frontmcp/plugin-feature-flags，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@frontmcp/sdk（1\.12\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @frontmcp/plugin-feature-flags 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @frontmcp/plugin-feature-flags 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @frontmcp/plugin-feature-flags 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @frontmcp/plugin-feature-flags 可以商用吗？

@frontmcp/plugin-feature-flags 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @frontmcp/plugin-feature-flags 的下载量有多少？

根据 npm 官方下载统计，@frontmcp/plugin-feature-flags 在 2026/10/16 – 2026/11/14 这 30 天内被下载 5,363 次，日均约 179 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @frontmcp/plugin-feature-flags 还在维护吗？

最新版本 1\.12\.2 发布于 2026/11/15（1 天前）；至今共发布 98 个版本，其中过去 12 个月发布了 98 个；首次发布于 2026/03/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。