first-flag

创建第一个功能开关

SDK 已连接。现在帮助用户创建第一个功能开关，并端到端地验证其运行效果。

此技能隶属于 LaunchDarkly 入门指南；父级 第 6 步是第一个功能开关。前置步骤：应用代码更改。

可选——已安装 Flag Create 技能：如果会话中有来自 github.com/launchdarkly/ai-tooling 的 launchdarkly-flag-create 技能（使用 npx skills add launchdarkly/ai-tooling --skill launchdarkly-flag-create -y --agent <agent> 安装），你可以用它来创建功能开关，并选择与代码库匹配的评估代码。但仍必须完成默认关闭 → 验证为关闭 → 切换为开启 → 验证为开启（以下步骤 3–5）。不要要求必须安装该技能：如果缺少该技能，或仅使用 MCP 的流程与用户设置冲突，本页面仍是完整的备用方案。

安全：凭证处理

**绝不要将令牌字面值代入命令。**请改用环境变量引用：

• Shell 命令：$LAUNCHDARKLY_ACCESS_TOKEN（由 Shell 展开，不会显示在 ps 输出中）
• 在当前会话中设置变量：export LAUNCHDARKLY_ACCESS_TOKEN=<your-token>

这样可以避免令牌出现在进程列表、Shell 历史记录和屏幕录制中。

步骤 0：查阅 SDK 功能开关键指导

创建功能开关或编写评估代码之前，请查看下方的 各 SDK 的功能开关键行为表格。一些 SDK 会在应用代码中暴露功能开关键之前对其进行转换（例如，React SDK 会将 kebab-case 键转换为 camelCase）。你在 LaunchDarkly 中创建的功能开关键、SDK/框架配置，以及代码中引用的键必须彼此匹配。

• 如果 SDK 会转换键（例如，React 的 useFlags() 会将 my-first-flag 转换为 camelCase myFirstFlag）：请使用转换后的键生成评估代码。LaunchDarkly 中的功能开关键保持原样（通常使用 kebab-case）。
• 如果 SDK 保留键的原样（大多数服务端 SDK）：请在代码中使用与 LaunchDarkly 完全一致的功能开关键字符串。
• 如果 SDK 支持两种模式（例如，React 允许通过 provider 选项关闭 camelCase）：请先确定项目使用哪种模式（检查现有代码或 provider 配置），然后生成匹配的代码。

各 SDK 的功能开关键行为

SDK	键转换	my-first-flag 对应的代码键	备注
React Web（useFlags()）	默认使用 camelCase	myFirstFlag	在 provider 上设置 reactOptions: { useCamelCaseFlagKeys: false } 可关闭此行为
React Native（useFlags()）	默认使用 camelCase	myFirstFlag	同样提供 reactOptions 覆盖选项
Vue（useLDFlag()）	无（传入原始键）	'my-first-flag'
JavaScript Browser	无	'my-first-flag'
Node.js Server	无	'my-first-flag'
Python Server	无	'my-first-flag'
Go Server	无	"my-first-flag"
Java Server	无	"my-first-flag"
.NET Server	无	"my-first-flag"
Ruby Server	无	'my-first-flag'
Swift/iOS	无	"my-first-flag"
Android	无	"my-first-flag"
Flutter	无	'my-first-flag'

在以下步骤 2 中编写评估代码时，如果 SDK 会应用转换，请使用“代码键”列中的值，而不是 LaunchDarkly 的原始键。

步骤 1：创建功能开关

**REST / curl 身份验证：**将 $LAUNCHDARKLY_ACCESS_TOKEN 用作 Authorization 请求头的值（LaunchDarkly 使用原始令牌，不加 Bearer 前缀）。Shell 会展开该变量，但不会记录其值。

通过 MCP（首选）

如果 LaunchDarkly MCP 服务可用，请使用 create-feature-flag（或服务提供的等效标志创建工具）：

• Key：my-first-flag（或使用与用户项目相关的名称）
• Name："我的第一个标志"
• Kind：boolean
• Variations：true / false
• Temporary：true

通过 LaunchDarkly API

curl -s -X POST \
  "https://app.launchdarkly.com/api/v2/flags/PROJECT_KEY" \
  -H "Authorization: $LAUNCHDARKLY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Flag",
    "key": "my-first-flag",
    "kind": "boolean",
    "variations": [
      {"value": true},
      {"value": false}
    ],
    "temporary": true
  }'

通过 ldcli

ldcli flags create \
  --access-token "$LAUNCHDARKLY_ACCESS_TOKEN" \
  --project PROJECT_KEY \
  --data '{"name": "My First Flag", "key": "my-first-flag", "kind": "boolean", "temporary": true}'

创建后，该标志的 targeting 为 OFF，会向所有人提供关闭变体（false）。已知项目 key 后，将用户引导至该标志的控制面板页面：https://app.launchdarkly.com/projects/{projectKey}/flags/my-first-flag（替换为实际的项目 key）。

步骤 2：添加标志评估代码

在应用中添加评估标志的代码。将其放在适合用户功能的位置。

服务端示例

// Node.js (@launchdarkly/node-server-sdk) -- ldClient is your initialized server client after waitForInitialization
const context = { kind: 'user', key: 'example-user-key', name: 'Example User' };
const showFeature = await ldClient.boolVariation('my-first-flag', context, false);

if (showFeature) {
  console.log('Feature is ON');
} else {
  console.log('Feature is OFF');
}

# Python (launchdarkly-server-sdk) -- client is ldclient.get() after set_config
from ldclient import Context

context = Context.builder("example-user-key").name("Example User").build()
show_feature = client.variation("my-first-flag", context, False)

if show_feature:
    print("Feature is ON")
else:
    print("Feature is OFF")

// Go
context := ldcontext.NewBuilder("example-user-key").Name("Example User").Build()
showFeature, _ := ldClient.BoolVariation("my-first-flag", context, false)

if showFeature {
    fmt.Println("Feature is ON")
} else {
    fmt.Println("Feature is OFF")
}

客户端示例

// React — useFlags() camelCases keys: "my-first-flag" → myFirstFlag (see Step 0 table)
import { useFlags } from 'launchdarkly-react-client-sdk';

function MyComponent() {
  const { myFirstFlag } = useFlags();

  return (
    <div>
      {myFirstFlag ? <p>Feature is ON</p> : <p>Feature is OFF</p>}
    </div>
  );
}

React SDK 的 useFlags() hook 默认会将 kebab-case 标志 key 转换为 camelCase，因此 my-first-flag 会变成 myFirstFlag。如果项目在 provider 上通过 reactOptions: { useCamelCaseFlagKeys: false } 禁用了此行为，请改用原始 key 字符串。选择使用哪种形式前，务必检查项目的 provider 配置——参见上文的标志 key 行为表。

步骤 3：验证默认值

当 targeting 为 OFF 时，标志的评估结果应为 false。运行应用并确认：

Feature is OFF

步骤 4：开启标志

通过 MCP

LaunchDarkly MCP 服务提供 update-feature-flag（JSON Patch），而不是名为 toggle-flag 的工具——请使用 MCP 服务列出的工具名称。

最简单的方式： 如果只需开启一次标志，优先使用下方的 ldcli 或 LaunchDarkly API 部分。

如果使用 update-feature-flag： 调用时传入 projectKey、featureFlagKey 和作为 JSON Patch 数组的 PatchWithComment.patch。通常通过对该环境的 on 字段执行 replace 操作来为某个环境开启标志（如有需要，请根据你账户的 get-feature-flag 结果确认确切路径）：

{
  "projectKey": "PROJECT_KEY",
  "featureFlagKey": "my-first-flag",
  "PatchWithComment": {
    "patch": [
      {
        "op": "replace",
        "path": "/environments/ENVIRONMENT_KEY/on",
        "value": true
      }
    ],
    "comment": "Onboarding: turn on my-first-flag"
  }
}

将 ENVIRONMENT_KEY 替换为目标环境的环境 key（例如 test、production）。

通过 LaunchDarkly API

curl -s -X PATCH \
  "https://app.launchdarkly.com/api/v2/flags/PROJECT_KEY/my-first-flag" \
  -H "Authorization: $LAUNCHDARKLY_ACCESS_TOKEN" \
  -H "Content-Type: application/json; domain-model=launchdarkly.semanticpatch" \
  -d '{
    "environmentKey": "ENVIRONMENT_KEY",
    "instructions": [
      {"kind": "turnFlagOn"}
    ]
  }'

通过 ldcli

ldcli flags toggle-on \
  --access-token "$LAUNCHDARKLY_ACCESS_TOKEN" \
  --project PROJECT_KEY \
  --environment ENVIRONMENT_KEY \
  --flag my-first-flag

步骤 5：验证切换

开启标志后，应用现在应显示：

Feature is ON

对于使用流式传输的服务端 SDK（默认方式），更改应会在数秒内生效。对于客户端 SDK，更改会在下一次页面加载时生效，或在 SDK 轮询更新时生效。

步骤 6：添加交互式演示

标志正常工作后，添加一个可见的交互式元素，让用户能看到标志实际生效，而不只是查看控制台日志。这样能带来令人惊喜的体验，也能为用户提供可展示给他人的直观证明。

根据检测到的应用类型选择合适的演示：

应用类型	要添加的内容	用户体验
前端（React、Vue、SPA）	由标志控制的横幅、徽章或按钮	在控制面板中切换标志 → 刷新页面 → 元素显示/消失
后端 API（Node、Python、Go 等）	返回标志状态 JSON 的 /launchdarkly-demo 端点	用 curl 请求端点 → 切换标志 → 再次用 curl 请求 → 响应发生变化
全栈（Next.js SSR、Rails 等）	同时添加 API 端点和显示标志状态的 UI 元素	切换标志 → 查看 API 和 UI 是否都反映了更改
CLI / 脚本	--feature-demo 标志或独特的输出模式	运行脚本 → 切换标志 → 再次运行 → 输出发生变化

前端演示示例（React）

添加一个在标志开启时一目了然的组件或元素：

// Add to an existing page component
import { useFlags } from 'launchdarkly-react-client-sdk';

function FeatureFlagDemo() {
  const { myFirstFlag } = useFlags();

  if (!myFirstFlag) return null;

  return (
    <div style={{
      padding: '12px 20px',
      backgroundColor: '#405BFF',
      color: 'white',
      borderRadius: '8px',
      margin: '16px 0',
      fontWeight: 500
    }}>
      LaunchDarkly is working — this banner is controlled by a feature flag
    </div>
  );
}

将其放在醒目的位置（例如主页顶部或控制面板/页眉区域）。

后端演示示例（Node.js/Express）

添加一个返回标志状态的端点：

// Add to your Express app (or equivalent for other frameworks)
app.get('/launchdarkly-demo', async (req, res) => {
  const context = { kind: 'user', key: 'demo-user' };
  const flagValue = await ldClient.boolVariation('my-first-flag', context, false);
  
  res.json({
    flag: 'my-first-flag',
    enabled: flagValue,
    message: flagValue 
      ? 'LaunchDarkly is working — the flag is ON'
      : 'LaunchDarkly is working — the flag is OFF'
  });
});

告诉用户使用以下命令进行测试：curl http://localhost:PORT/launchdarkly-demo

后端演示示例（Python/Flask）

@app.route('/launchdarkly-demo')
def launchdarkly_demo():
    context = Context.builder("demo-user").build()
    flag_value = ld_client.variation("my-first-flag", context, False)
    
    return jsonify({
        "flag": "my-first-flag",
        "enabled": flag_value,
        "message": "LaunchDarkly is working — the flag is ON" if flag_value 
                   else "LaunchDarkly is working — the flag is OFF"
    })

全栈演示

对于同时包含服务端和客户端的应用（例如 Next.js、Remix、带前端的 Rails）：

1. 添加 API 端点（见上方后端示例）
2. 添加一个 UI 组件，用于调用该端点或直接使用客户端 SDK
3. 用户可以验证这两种方式是否都能正常工作

指南

1. 遵循现有模式——使用与应用其他部分相同的路由风格、组件约定和代码风格
2. 一目了然——使用颜色、位置或文字，清楚地表明这是 LaunchDarkly 演示
3. 便于移除——添加简短注释，例如 // LaunchDarkly demo - safe to remove，让用户知道之后可以将其删除（也可以保留为模板）
4. 不要过度设计——这是演示，不是生产功能；理想情况下只需几行代码

带领用户完成操作

添加演示元素后：

1. 告诉用户你将其添加到了哪里，以及如何查看（URL、页面位置或命令）
2. 请他们验证显示的是当前标志状态
3. 请他们在控制面板中切换标志（提供深层链接：https://app.launchdarkly.com/projects/{projectKey}/flags/my-first-flag）
4. 请他们刷新页面或重新运行，以查看变化
5. 庆祝集成成功

恭喜

用户已成功：

1. 安装 LaunchDarkly SDK
2. 将其连接到 LaunchDarkly
3. 创建功能标志
4. 在代码中评估该标志
5. 切换标志并查看结果
6. 添加了一个可向他人展示的交互式演示

这是“验证成功”的关键时刻——用户已经拥有一个可实时切换的功能标志。演示元素让这一切变得直观且便于分享。

**鼓励用户学习下一项技能：**建议他们从 github.com/launchdarkly/ai-tooling 安装或启用 launchdarkly-flag-create 技能（npx skills add launchdarkly/ai-tooling --skill launchdarkly-flag-create -y --agent <agent>），这样今后的工作——创建符合仓库约定的标志、封装功能并验证接线情况——就有专门的操作指南。如果他们不确定如何添加，可以提出协助。

错误处理

授权错误

如果任何步骤返回 401 或 403：

**D9——阻塞：**立即调用结构化提问工具。

• question: "我收到授权错误（[specific status code and message]）。需要你采取操作才能解决——我无法自动重试。"
• options:
  • "我会重新进行身份验证——运行 ldcli login 或刷新我的令牌"
  • "让我检查访问令牌，然后重试"
  • "我没有账户——请帮我注册"
  • "项目或环境不存在——请帮我创建"
• 停止。不要将问题作为文本写出。不要自动重试授权错误——这些错误始终需要用户采取操作。在用户选择一个选项之前，不要继续。

其他错误

对于非身份验证错误（标志创建失败、SDK 密钥不匹配、标志返回回退值等），请根据错误输出、应用日志以及你对项目的了解来诊断问题。

建议的后续步骤：

• 如果尚未安装，请从 github.com/launchdarkly/ai-tooling 安装 launchdarkly-flag-create——此引导流程仅涵盖创建第一个布尔标志；该技能会指导你根据现有代码模式创建适用于实际场景的标志（需要满足该技能的前置条件：使用 LaunchDarkly MCP）。
• 使用同一分发包中的 launchdarkly-flag-targeting 来设置百分比发布和定向规则
• 阅读 LaunchDarkly 文档，了解上下文、实验和指标等高级主题

---

完成后，请继续阅读： 引导摘要 和 编辑器规则与技能（父级引导技能中的默认后续步骤——不是 MCP 设置，后者是第 4 步）。如需安装或排查 MCP，请使用 mcp-configure 和 MCP 配置模板。