apply

应用代码更改（SDK 安装）

执行集成计划。安装 SDK，并添加初始化每个已跟踪端所需的最少代码。

此技能嵌套在 LaunchDarkly SDK Install (onboarding) 下；父级的步骤 3 是应用。上一步：生成集成计划。下一步：启动应用程序。

双 SDK：如果已批准的计划是双 SDK（计划：双 SDK 集成），则必须为两个轨道完成步骤 1-3——清单中有两个软件包、运行（或以等效方式执行）两条安装命令、在需要时提供两行凭据，并按照配方在不同的入口点进行两次初始化。不得在未实际安装和初始化第二个 SDK 的情况下声称已完成设置。如果计划只列出一个轨道，但用户要求两个轨道，请停止并返回计划——不要凭记忆编造另一半。

**凭据时机：**这是第一个需要向用户索取 SDK 密钥 / 客户端 ID / 移动密钥（或征得用户同意后获取 / 写入这些凭据）的嵌套步骤。不会一开始就询问账户状态——如果 MCP 已配置，则通过 MCP OAuth 提前推断；如果用户还没有账户，则在此处的 D7（选项 4）中提示（见父级前提条件）。

步骤 1：安装 SDK 依赖项

使用你已在 SDK 配方中匹配的 SDK 条目所指定的准确软件包或模块名称和安装命令，并使用项目的包管理器。不要从其他地方复制通用安装命令——每个配方都会指定正确的构件。

双 SDK：先运行轨道 A 的安装命令，再运行轨道 B 的安装命令（均来自计划）。确认 package.json / requirements.txt / 锁文件中包含两个软件包名称（或各语言对应的正确软件包清单）。计划要求双 SDK 时，不能跳过第二次安装。

安装完成后，验证依赖项已出现在锁文件或依赖项清单中（计划中的所有 LaunchDarkly 软件包都应包含在内）。

更改其他依赖项前需获得许可

无需额外询问即可进行（除常规的仓库编辑许可外）：仅安装此集成的配方中指定的 LaunchDarkly SDK 软件包（例如，一个服务端 SDK，或双 SDK 方案中列出的确切的服务端 + 客户端组合——两者均属于许可范围内的 LD 安装）。使用各配方指定的最低限度安装内容（确切的软件包名称）。

**运行任何命令或编辑清单前，均需获得用户明确批准：**任何超出上述范围的更改，包括但不限于：

• 升级、降级、固定版本或添加非 LaunchDarkly软件包（修复 peer dependency、npm install X@latest、yarn upgrade、pnpm update、升级 React/Node 类型、传递依赖导致的锁文件变更等）
• 运行 npm audit fix、批量更新，或为满足 SDK 要求而替换项目的包管理器解析策略
• 更改 engine / packageManager 字段、resolutions / overrides 或 workspaces 条目，除非是为了添加 LD 依赖项

如果包管理器报告 peer 冲突或安装失败：

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

• question: "安装报告了 [specific error]。要修复此问题，我需要 [specific changes to non-LD packages]。是否继续进行这些额外更改？"
• options:
  • "是，进行这些更改"
  • "否，仅保留 LaunchDarkly 软件包——我会自行解决冲突"
  • "先给我看具体命令"
• **停止。**不要将问题以文本形式写出。不要默默升级旧仓库来“匹配最新 SDK 的依赖项”。在用户选择选项之前，不得继续。

如果用户拒绝更广泛的更改：尽可能仅添加 LD 软件包，记录冲突，并使用占位符或手动步骤继续。

步骤 2：将 SDK 密钥添加到环境配置中

绝不要在应用程序源文件中硬编码 SDK 密钥、客户端 ID 或移动密钥（只能通过环境变量引用这些值）。

在处理密钥前征求许可

D7 -- 阻塞性（强制执行 -- 不得跳过）： 立即调用结构化提问工具。此决策点出于安全合规要求而设立——用户必须明确选择如何处理密钥。跳过此步骤，未经同意就写入密钥，属于严重失误。

• question: "SDK 需要一个适用于你环境的 SDK 密钥（或客户端 ID / 移动端密钥）。你希望如何设置此密钥？"
• options:
  • "我会告诉你把它放在哪里"
  • "我会自行设置密钥——只需告诉我该使用哪个变量名"
  • "替我将它写入 .env 文件"
  • "我还没有账号——帮我注册" -> 指引用户前往已解析的注册 URL（参见 来源归属），写入占位符并继续（实际密钥等账号准备就绪后再设置）
• 停止。不要将问题作为文本写出。用户尚未选择选项前，不要从 LaunchDarkly 获取密钥，也不要将真实值写入仓库。不要根据上下文或先前对话推断答案——始终提供此选项。

如果用户选择选项 1（“告诉我把它放在哪里”）：

1. 询问他们希望将密钥写入何处（文件路径、密钥管理器等）
2. 询问他们希望如何提供密钥：粘贴密钥，还是由 Agent 通过 MCP/API 获取
3. 仅将密钥写入用户指定的位置
4. 不要创建 .env，也不要修改任何其他文件

如果用户选择选项 2（“我会自行设置”）：

1. 告知他们需要设置的变量名（见下表）
2. 提供正确的控制面板页面链接。已知项目密钥和环境密钥时：https://app.launchdarkly.com/projects/{projectKey}/settings/environments/{envKey}/keys。仅已知项目密钥时：https://app.launchdarkly.com/projects/{projectKey}/settings/environments，并告知他们选择环境。两者都未知时：https://app.launchdarkly.com/projects，并告知他们前往 Settings > Environments 查找密钥。
3. 等待用户确认密钥已设置后，再继续第 3 步
4. 完全不要获取、写入或处理密钥值

如果用户选择选项 3（“替我将它写入 .env 文件”）：

1. 询问他们希望如何提供密钥：粘贴密钥，还是由 Agent 通过 MCP/API 获取
2. 按照下方的 写入 .env 部分操作
3. 写入任何真实值前，确保 .env 已列入 .gitignore

如果用户选择选项 4（“我还没有账号”）：

1. 指引用户前往已解析的注册 URL（参见 来源归属）
2. 说明设置 SDK 密钥需要账号——他们可以在注册后完成设置
3. 写入前确保 .env 已列入 .gitignore（检查方式与选项 3 / 写入 .env 相同）
4. 将占位变量名写入 .env（不含真实值），以便代码编译
5. 继续执行第 3 步（初始化代码），使用占位环境变量引用。实际密钥设置前，应用无法连接到 LaunchDarkly，这是预期行为。
6. 在引导日志中注明密钥设置仍待账号创建后完成

通过 MCP 获取密钥

当用户要求 Agent 获取密钥（通过上面的选项 1 或 3）时，使用 get-environments MCP 工具（如果已配置）。调用时传入项目密钥 — 响应包含每个环境的 SDK 密钥、客户端 ID 和 移动端密钥。如果 get-environments 已返回这些密钥，不要另行调用 API 获取单个密钥。

get-environments({ request: { projectKey: "PROJECT_KEY" } })

安全：将包含密钥的 MCP 响应视为敏感信息。 只将密钥写入用户选择的位置，不要在聊天回复中完整复述密钥值。Agent 对话历史或日志中的密钥可能会在会话结束后继续留存。

请根据响应中匹配的环境选择正确的密钥类型（见下表）。如果未配置 MCP，请引导用户前往 LaunchDarkly 控制面板获取密钥：https://app.launchdarkly.com/projects/{PROJECT_KEY}/settings/environments/{ENV_KEY}/keys。

变量名及其值的来源

SDK 类型	变量名（常见）	LaunchDarkly 中的来源
服务端	LAUNCHDARKLY_SDK_KEY	get-environments 响应 → 环境 → SDK 密钥
客户端	逻辑名称 / 打包工具前缀名称（见下文）	get-environments 响应 → 环境 → 客户端 ID
移动端	LAUNCHDARKLY_MOBILE_KEY	get-environments 响应 → 环境 → 移动端密钥

客户端（浏览器）项目： LaunchDarkly 提供的值仍然是客户端 ID。在 .env 中，使用打包工具会向客户端代码公开的变量名：

技术栈	.env 键	代码中的读取方式
Create React App	REACT_APP_LAUNCHDARKLY_CLIENT_SIDE_ID	process.env.REACT_APP_LAUNCHDARKLY_CLIENT_SIDE_ID
Vite	VITE_LAUNCHDARKLY_CLIENT_SIDE_ID	import.meta.env.VITE_LAUNCHDARKLY_CLIENT_SIDE_ID
Next.js	NEXT_PUBLIC_LAUNCHDARKLY_CLIENT_SIDE_ID	process.env.NEXT_PUBLIC_LAUNCHDARKLY_CLIENT_SIDE_ID

其他技术栈可能使用不同的前缀，或使用不带前缀的 LAUNCHDARKLY_CLIENT_SIDE_ID —— 请使用项目现有的公开环境变量命名方式。

写入 .env（用户同意后）

文件路径应使用集成根目录（仓库根目录，或 monorepo 中的目标包 — 参见检测仓库技术栈）。

1. 创建或更新 .env： 如果 .env 不存在，则创建该文件。如果文件已存在，则追加或更新 LaunchDarkly 相关行 — 不要删除无关变量。
2. 添加集成所需的内容：
   • 仅服务端：LAUNCHDARKLY_SDK_KEY=...
   • 客户端/浏览器：在正确的打包工具前缀键下填写客户端 ID（例如 VITE_LAUNCHDARKLY_CLIENT_SIDE_ID=...）。
   • 全栈或混合型（例如 Next.js、SSR + 客户端）： 如果同时使用两种 SDK，则同时添加服务端 SDK 密钥和客户端 ID 两行。
   • 移动端：适用时添加 LAUNCHDARKLY_MOBILE_KEY=...。
3. .gitignore： 确保 .env 已列入创建 .env 时所在根目录的 .gitignore（或 monorepo 中最近的相关忽略文件）。如果缺少该条目，则添加 — 仅在用户同意修改仓库后添加（权限范围与写入 .env 相同）。不要提交包含真实密钥的文件。
4. .env.example / .env.sample： 如果项目使用其中任一文件，只添加占位符条目（不要填写真实密钥），以便团队成员了解需要设置哪些变量。

如果项目不使用 dotenv，而是依赖配置模块或托管密钥，请改用现有模式 — 写入任何文件中的真实值之前，仍需遵守上述 D7 同意要求。

第 3 步：添加 SDK 初始化代码

初始化方式取决于检测和规划期间选择的 SDK。此技能不提供各 SDK 的复制粘贴示例——使用错误的代码片段（例如，配方针对 Node 服务，却使用 React Web 代码片段）会造成误导。

权威信息来源（按顺序使用；双 SDK 时对每个轨道重复执行）：

1. SDK 配方——本轨道所用 SDK 对应的行：安装步骤见上方第 1 步；初始化则遵循其中列出的 SDK 详情／文档链接。
2. snippets/ 下的 SDK 详情文件（当配方中提供链接时）——精选链接，以及许多 SDK 的完整入门示例，这些示例与相应 SDK 保持一致。
3. 该 SDK 的 LaunchDarkly 官方文档（配方或详情文件中的 URL）——遵循其入口点和异步模式（例如，React Web：React Web SDK）。

使用第 2 步配置凭证：服务端 SDK 使用 LAUNCHDARKLY_SDK_KEY；客户端／浏览器 SDK 使用客户端 ID，并在适用时使用第 2 步中的带打包工具前缀的环境变量名称。

在该轨道的应用程序入口点中添加导入和初始化代码（单体仓库中则添加到目标包的入口点——参见检测仓库技术栈）。双 SDK：服务端初始化代码放在计划指定的服务端入口点中；客户端／Provider 初始化代码放在客户端入口点中——切勿使用一个共享代码块假装同时覆盖两者，除非该技术栈的官方文档明确规定两者共用一种模式。

关键原则

1. 在文件顶部与其他导入语句一同导入
2. 在相应运行环境（Node 服务端或浏览器）的应用生命周期早期进行初始化
3. 如果 SDK 支持，在计算功能标志前等待初始化完成
4. 处理错误——记录失败，但不要导致应用程序崩溃
5. 遵循现有代码风格——使用与代码库其余部分相同的模式（async/await、回调、CommonJS 与 ESM 模块）
6. 根据不同使用场景采用正确模式——服务端代码使用服务端配方进行服务端初始化；客户端代码使用客户端配方进行客户端／Provider 初始化。不要在两条轨道中重复使用同一代码片段，也不要在计划包含双 SDK 时跳过第二条轨道的初始化。

第 4 步：验证代码能否编译

完成修改后：

1. 运行项目的构建或编译步骤
2. 如果配置了代码检查工具，则运行它
3. 修复导入错误或类型问题，不要升级无关依赖，除非用户已批准此范围（更改其他依赖前需获得许可）

如果代码无法编译，请勿继续下一步。

---

完成后：启动应用程序