projects

LaunchDarkly 项目设置

你正在使用一项技能，它将指导你在代码库中设置 LaunchDarkly 项目管理。你的任务是探索代码库，了解技术栈和开发模式，评估合适的方案，从参考资料中选择正确的实施路径，执行设置，并验证其是否正常运行。

前提条件

• 环境中已配置远程托管的 LaunchDarkly MCP 服务
• 仅当你要构建用于创建项目的代码（脚本、IaC、管理工具）时，才需要具有 projects:write 权限的 API 访问令牌

核心原则

1. 先了解，再行动：探索代码库，了解技术栈和开发模式。
2. 选择合适方案：选择符合架构的方案。
3. 遵循约定：尊重现有代码风格和结构。
4. 验证集成：确认设置正常运行：Agent 执行检查并报告结果。

API 访问

自行创建或检查项目时，请使用 LaunchDarkly MCP 服务工具：create-project、get-project 和 list-projects。这些工具通过 OAuth 进行身份验证，无需令牌。

MCP 工具不会返回服务端 SDK 密钥，只会返回客户端 ID 和移动密钥。要获取应用所需的 SDK 密钥，请让用户从 项目设置 → 环境 中复制；或者，如果用户愿意，也可以让其为本次会话粘贴 API 访问令牌，然后通过 REST API 获取该密钥（快速入门）。不要在环境变量、.env 文件或 Agent/MCP 配置文件中搜索凭据。

参考指南调用 REST API，是因为它们用于构建无需 Agent 即可运行的代码。

什么是项目？

项目是 LaunchDarkly 的顶层组织容器，其中包含：

• 所有配置
• 功能标志和细分群体
• 多个环境（默认创建 Production 和 Test）

可以将项目视为独立的应用、服务或团队，它们需要各自隔离的一组配置。

项目设置工作流

第 1 步：探索代码库

在实施任何内容之前，先了解现有架构：

1. 识别技术栈：

   • 使用什么语言？（Python、Node.js、Go、Java 等）
   • 使用什么框架？（FastAPI、Express、Spring Boot 等）
   • 是否已有 LaunchDarkly 集成？

2. 检查环境管理：

   • 环境变量存储在哪里？（.env 文件、密钥管理器、配置文件）
   • 配置在哪里加载？（启动脚本、配置模块）
   • 是否已有 LaunchDarkly SDK 密钥？

3. 查找开发模式：

   • 是否已有 API 客户端或服务模块？
   • 通常如何集成外部 API？
   • 是否有 CLI、脚本目录或管理工具？

4. 了解使用场景：

   • 这是要设置一个新项目吗？
   • 是要添加到现有 LaunchDarkly 集成中吗？
   • 这是多服务架构的一部分吗？
   • 是否需要在区域或团队之间克隆项目？

第 2 步：评估情况

根据探索结果，确定合适的方案：

场景	推荐路径
新项目，尚未集成 LaunchDarkly	快速设置 - 使用 create-project 创建项目，然后保存其 SDK 密钥
已有 LaunchDarkly 使用场景	添加到现有项目 - 创建新项目或使用现有项目
多个服务/微服务	多项目 - 为每个服务创建项目
多区域或多租户	项目克隆 - 克隆模板项目
基础设施即代码（IaC）设置	自动化设置 - 使用脚本创建
需要项目管理工具	CLI/管理工具 - 构建项目管理实用工具

步骤 3：选择实现路径

选择与你的技术栈和使用场景相符的参考指南：

按语言/技术栈：

• Python 实现 - 适用于 Python 应用（FastAPI、Django、Flask）
• Node.js/TypeScript 实现 - 适用于 Node.js/Express/NestJS 应用
• Go 实现 - 适用于 Go 服务
• 多语言配置 - 适用于多语言架构

按使用场景：

• 快速入门 - 创建首个项目并获取 SDK 密钥
• 环境配置 - 将 SDK 密钥保存到 .env、密钥管理工具或配置中
• 项目克隆 - 为不同区域/团队克隆项目
• IaC/自动化 - 集成 Terraform、脚本和 CI/CD
• 管理工具 - 构建 CLI 或管理工具

步骤 4：实现集成

按照选定的参考指南实现项目管理。需要注意以下事项：

1. API 身份验证：

   • 安全存储 API 令牌
   • 遵循现有的密钥管理模式
   • 切勿将令牌提交到版本控制系统

2. 项目命名：

   • 使用一致且有描述性的名称
   • 遵循现有的命名规范
   • 项目键：使用小写字母和连字符，并以字母开头

3. SDK 密钥管理：

   • 提取并存储各环境的 SDK 密钥
   • 将应用使用的密钥保存为 LD_SDK_KEY。Python 和 Node.js AI SDK 会读取此变量，并在首次调用 AI 时进行初始化。它们不会读取 LAUNCHDARKLY_SDK_KEY。
   • 在代码库中采用与其他密钥相同的处理方式
   • 考虑为测试/预发布/生产环境分别使用密钥

4. 错误处理：

   • 妥善处理项目已存在的情况（409 冲突）
   • 提供清晰的错误消息
   • 不要静默失败

步骤 5：验证配置

创建项目后，验证其是否正常工作：

1. 获取项目以确认其存在。 调用 get-project MCP 工具，并检查项目是否包含其环境。无法访问 MCP 的代码可以改为调用 REST API：

   curl -X GET "https://app.launchdarkly.com/api/v2/projects/{projectKey}?expand=environments" \
     -H "Authorization: {api_token}"
   

   不要将响应直接传入 .environments.items[] 这类 jq 筛选器。 environments 的结构会因 expand 参数而异，有时是 {items: [...]}，有时是裸数组；手动编写的筛选器会因 Cannot index array with string "items" 而失败。先运行 jq -e . 检查实际结构，或使用 jq '.environments | if type == "object" then .items else . end' 以兼容这两种结构。

2. 测试 SDK 集成： 将密钥作为 LD_SDK_KEY 放入 .env，然后在项目目录中初始化 AI SDK。Python 需要运行 pip install launchdarkly-server-sdk launchdarkly-ai-server python-dotenv：

   import asyncio
   from dotenv import load_dotenv
   from launchdarkly_ai_server import init_client, get_client, shutdown
   
   load_dotenv()
   
   async def main():
       await init_client()
       print("SDK initialized:", get_client().is_initialized())
       # shutdown() flushes pending events before closing the connection.
       await shutdown()
   
   asyncio.run(main())
   

   Node.js 需要运行 npm install @launchdarkly/ai-node dotenv：

   import 'dotenv/config';
   import { initClient, shutdown } from '@launchdarkly/ai-node';
   
   // Resolves once connected; throws LDTimeoutError if the key is invalid
   await initClient();
   console.log('SDK initialized: true');
   await shutdown();
   

   有效密钥会输出 SDK initialized: True（Python）或 true（Node.js）。密钥无效时，Python 会记录 HTTP error 401 (invalid SDK key) 并输出 False，Node.js 则会在 10 秒后抛出 LDTimeoutError。未提供密钥时，两者都会报错并提示设置 LD_SDK_KEY。

3. 报告结果：

   • ✓ 项目存在且包含环境
   • ✓ SDK 密钥已设置且有效
   • ✓ SDK 可以初始化（或指出任何问题）

项目键最佳实践

项目键必须遵循以下规则：

✓ Good examples:
  - "support-ai"
  - "chat-bot-v2"
  - "internal-tools"

✗ Bad examples:
  - "Support_AI"     # No uppercase or underscores
  - "123-project"    # Must start with letter  
  - "my.project"     # No dots allowed

命名建议：

• 键应简短且具有描述性
• 使用团队/服务/用途作为命名方案
• 在整个组织内保持一致

常见的组织方式

按团队

platform-ai       → Platform Team Agent
customer-ai       → Customer Success Team Agent
internal-ai       → Internal Tools Team Agent

按应用/服务

mobile-ai         → Mobile App configs
web-ai            → Web App configs
api-ai            → API Service configs

按区域/部署

ai-us             → US Region
ai-eu             → Europe Region
ai-apac           → Asia-Pacific Region

边缘情况

情况	操作
项目已存在	检查是否为正确的项目；使用该项目，或使用不同的键创建项目
需要多个项目	为每个服务／区域／团队分别创建项目
多个服务共享配置	使用同一个项目，并按 SDK 上下文区分
令牌缺少权限	申请 projects:write 权限，或使用 MCP 服务
项目名称冲突	键必须唯一，名称可以相似

不要这样做

• 未先了解使用场景就创建项目
• 将 API 令牌或 SDK 密钥提交到版本控制中
• 在测试／开发环境中使用生产环境 SDK 密钥
• 不必要地创建重复项目
• 跳过探索阶段

后续步骤

设置好项目后：

1. 创建配置 - 使用 configs-create 技能
2. 设置 SDK 集成 - 使用 sdk-install 技能
3. 配置定向 - 使用 configs-targeting 技能

相关技能

• configs-create - 在项目中创建配置
• sdk-install - 在应用中集成 SDK
• configs-targeting - 配置配置定向
• configs-variations - 管理配置变体

参考资料

• Python 实现
• Node.js 实现
• Go 实现
• 快速入门指南
• 环境配置
• 项目克隆
• IaC／自动化
• 管理工具