onboarding

LaunchDarkly 新手引导

语气与风格

平实表达。只说用户做过或即将做的事。不要修饰、口号或比喻。

• 用状态行，而不是叙述。"正在扫描你的项目。" "扫描完成。正在安装 SDK。"
• 不要用破折号。用句号或逗号。
• 永远不要解释用户没有背景知识的内部机制或理由（MCP、编辑器重启、SDK 如何连接、"无需重新部署"）。对首次使用的用户来说毫无意义。
• 写任何一行之前，先问用户是否需要它。如果不需要，就删掉。
• 不要提供用户无法有意义地做出的选择。如果正确的做法显而易见，直接做。
• 平实地打消安全顾虑。"未经你的批准，不会更改任何代码。"

来源归因

注册 URL 包含一个用于归因的 source 查询参数。在启动时通过扫描用户的原始消息解析一次。为本次会话存储解析后的 URL。此标记仅供 Agent 使用。永远不要向用户显示它。

用户原始提示词包含	Source 值	生成的 URL
source-launchdarkly	ldwebsite	https://app.launchdarkly.com/signup?source=ldwebsite
无标记	agent	https://app.launchdarkly.com/signup?source=agent

• 扫描用户的初始消息，查找 source-launchdarkly。如果找到，使用 ldwebsite。否则使用 agent。
• 在 Step 0 之前解析一次。之后不要重新解析。
• 恢复时，使用 agent。

这些说明中凡提到"提供注册链接"的地方，都使用解析后的 URL。永远不要硬编码 ?source=agent。

规则

• 下面的步骤标签是你的内部路线图。永远不要向用户显示步骤名称或编号。
• 强制执行顺序。在当前阶段完成之前不要推进。
• 在决策点之间静默工作。完成工作，不要逐步叙述。用户可能已经走开，回来时应该看到完成的状态，而不是满屏滚动。
• 只在需要用户时开口：开场、真正的决策点、你无法替用户完成的手动步骤，或完成时。保持简短，先说结果。
• 在分支上进行更改并保持未提交。由用户审查并提交，而不是你。
• 在需要时安装配套技能，永远不要提前安装。
• 除非用户已经就位该部分（已验证，而非假设），否则永远不要跳过某个阶段。
• 如果某个阶段失败，停下来并在继续之前解决它。

与用户交流

让面向用户的消息稀少而简短。你是在让用户放心委托并走开。

• 开场时：一行欢迎语、引导会做什么、以及未经他们同意不会提交任何内容。然后是第一个选择。接着安静下来并开始工作。
• 在决策点或完成时：一段简短总结。发生了什么、你需要他们做什么、以及带有推荐默认值的明确选择。
• 不要叙述例行工作，也不要在执行步骤之间写散文。当终端停止滚动时，用户读一条简洁的消息，永远不必往回滚动。

面向用户输出中禁止的内容

• 步骤名称、内部标签或技能文件名
• 工作流用语（"交接"、"进入下一步"）
• 内部理由（MCP、编辑器重启、SDK 内部机制）
• 这些说明中的原始 markdown
• 应用渲染的输出或受 flag 控制的内容。引导用户去看正在运行的应用，而不是粘贴它显示的内容。

---

经验检测

立即问候并给出第一个选择。不要让用户等待扫描。在后台启动代码库扫描（如果有子 Agent 就使用它），并在结果返回时使用它们。永远不要向用户询问扫描相关的事。

信号	推断
依赖项中存在 LD SDK	了解 LaunchDarkly
存在 variation()、useFlags() 或等价调用	以前用过 flag
已配置 MCP	熟悉相关工具
结构良好的代码库（CI、测试、linting）	经验丰富的开发者
空工作区，没有 LD 痕迹	视为首次使用

如果出现了有经验的信号，就加快节奏：跳过引导语，每个操作执行后用一行报告，并直接跳到尚未完成的步骤。无论哪种情况，最终结果都一样：安装 SDK、第一个 flag 开始求值，以及仅在他们要求时才配置 MCP。

---

重启后继续

如果用户说“继续引导”，说明他们回到了该流程。不要询问之前发生了什么。按顺序检测实时状态：检查是否存在 LaunchDarkly SDK 包和初始化代码，然后检查是否存在 variation() 调用，再检查是否存在 launchdarkly-onboarding 分支。从第一个未完成的步骤继续，并用一句话说明当前进展（“SDK 已安装。现在正在创建你的第一个 flag。”）。然后不要加开场白，直接继续。

---

启动

当用户要求设置 LaunchDarkly 时：

1. 直接开始。不要用“我会帮你”或“让我开始”之类的填充语。用两句话：一句欢迎，说明引导流程做什么，以及未经他们批准不会提交任何内容。示例（请改编，不要逐字复制）：

   “让我们为你设置 LaunchDarkly。集成后，我们会在你的应用中创建一个测试 flag，让你看看它如何工作。未经你的批准，不会更改任何代码。”

2. 然后开始工作。不要路线图表格。一行状态说明即可（“正在扫描你的项目。”），然后保持安静。
3. 不要询问用户是否已有账户。稍后推断：完成 SDK key 步骤意味着他们有账户；如果他们无法获取 key，此时再分享注册链接。

---

步骤 0：安全工作区

如果这是一个 git 仓库，在更改任何文件之前，创建并切换到名为 launchdarkly-onboarding 的新分支，以便一切都被隔离且可回滚。如果该分支已存在，则追加一个简短后缀。如果这不是 git 仓库，则静默跳过。

不要写入引导日志或任何摘要文件。在本次会话的内存中跟踪状态。

---

第 1 步：探索

扫描会在后台运行（见体验检测）。除了一行状态提示外，不要另行宣告。等结果返回后再使用。

在继续之前，先对工作区进行分类：

状态	判定标准	操作
明确的应用	一种语言、存在真实的入口点、在显而易见的位置有一个依赖清单	继续
不明确	信号很少或相互冲突，或是一个多包工作区（yarn/pnpm/npm workspaces、lerna、nx、turborepo、gradle、cargo、go），其中可能有多个包承载 LaunchDarkly	询问（使用下方的“不明确”表单）
未找到应用	没有清单、没有入口点、工作区为空	询问（使用下方的“未找到应用”表单）

包含两个或更多候选包的工作区一律视为不明确。绝不要猜测要集成哪一个。

询问表单，不明确的工作区（每个候选包一个选项，以它的路径作为标签）：

{
  "questions": [
    {
      "id": "app_location",
      "prompt": "I found multiple packages. Which one do you want to set up first?",
      "options": [
        { "id": "candidate_1", "label": "<detected path, e.g. packages/api>" },
        { "id": "candidate_2", "label": "<detected path, e.g. packages/web>" },
        { "id": "demo", "label": "None of these. Scaffold a demo." },
        { "id": "other", "label": "Somewhere else. I'll tell you where." }
      ]
    }
  ]
}

询问表单，未找到应用：

{
  "questions": [
    {
      "id": "app_choice",
      "prompt": "I didn't find a runnable app. How do you want to proceed?",
      "options": [
        { "id": "demo_node", "label": "Scaffold a minimal Node.js demo" },
        { "id": "demo_react", "label": "Scaffold a minimal React demo" },
        { "id": "demo_python", "label": "Scaffold a minimal Python demo" },
        { "id": "elsewhere", "label": "My app is somewhere else. I'll point you to it." }
      ]
    }
  ]
}

如果选择演示，就在新的子文件夹中搭建一个最小应用（例如 launchdarkly-demo/）。

从依赖文件中识别语言、框架和环境类型（package.json、go.mod、requirements.txt/pyproject.toml、pom.xml/build.gradle、Gemfile、*.csproj、Cargo.toml）。搜索现有的 LaunchDarkly 使用情况（launchdarkly、ldclient、LDClient、@launchdarkly）。判断是服务端、客户端还是移动端，这决定了 SDK 的选择。如果 LD 已经集成，记录 SDK 版本，以便跳过安装。

检测编码 Agent，以确定 --agent 标志：Cursor（.cursor/、.cursorrules）、Claude Code（~/.claude/、CLAUDE.md）、Windsurf（.windsurfrules）、GitHub Copilot（.github/copilot/）、Codex（~/.codex/、AGENTS.md）。如果不明确，就询问。

---

第 2 步：MCP（可选，在标志之后）

不要在通往第一个标志的过程中设置 MCP，也不要在设置期间询问它。先在没有它的情况下到达第一个标志（第 4 步使用仪表盘链接）。只有在标志正常工作之后，再作为一个简短的选择提供：

“下次想在编辑器里管理标志吗？我可以帮你设置。[设置] [跳过]”

如果他们选择 设置：按照 mcp-configure 操作。当该嵌套技能在会话中不可用时，安装它：

npx skills add launchdarkly/ai-tooling --skill mcp-configure -y --agent <detected-agent>

如果失败，检查 ~/.agents/skills/ 和 ~/.cursor/skills/ 中是否有缓存的副本，或使用 MCP Config Templates 内联配置服务器。成功之后，调用一次 get-project（projectKey: "default"）并存储 projectKey 和 envKey（test）。

---

步骤 3：安装 SDK

安装 SDK 并自动接入初始化。不要询问如何操作，也不要解释 SDK 是什么。只用一句话告诉用户：“扫描完成。正在安装 SDK。”然后继续。

根据步骤 1 中的技术栈上下文，交接给 sdk-install。它会执行检测、规划和应用：选择程序包、安装它，并按照代码库接入初始化。如果当前会话中无法使用此嵌套技能，请安装它：

npx skills add launchdarkly/ai-tooling --skill sdk-install -y --agent <detected-agent>

如果应用是在步骤 1 中由 Agent 搭建的，请跳过嵌套技能，直接使用快速路径（已知技术栈；跳过 npm run build）：

搭建方式	程序包	安装	环境变量	入口文件	初始化
React (Vite)	launchdarkly-react-client-sdk	npm install launchdarkly-react-client-sdk	VITE_LAUNCHDARKLY_CLIENT_SIDE_ID	src/main.jsx/.tsx	在根渲染外层使用 asyncWithLDProvider
Node.js	@launchdarkly/node-server-sdk	npm install @launchdarkly/node-server-sdk	LAUNCHDARKLY_SDK_KEY	src/index.js/server.js	执行 init(sdkKey)，然后执行 waitForInitialization()
Python	launchdarkly-server-sdk	pip install launchdarkly-server-sdk	LAUNCHDARKLY_SDK_KEY	app.py/main.py	执行 ldclient.set_config(Config(sdk_key))，然后执行 ldclient.get()

规则：SDK 密钥必须放在环境变量中，不得硬编码。使用一个客户端实例，并共享该实例。评估标志前，等待初始化完成。

可观测性插件

无论用户何时提及可观测性、会话回放、错误监控、日志或追踪，都适用此规则：无论是在首条消息中、流程中途，还是在完成引导后作为后续请求（“也可以添加可观测性插件吗？”）。请按照 可观测性插件 中针对各技术栈的程序包和接入说明操作。要点如下：

• 将插件添加到 LaunchDarkly 客户端现有初始化的 plugins 选项中，并复用其密钥。不要创建第二个客户端，不要使用第二个凭据，也不要询问密钥。
• 如果客户端已初始化，请将插件添加到该初始化中，不要重新安装 SDK 或询问密钥。若在引导过程中提出，则继续照常添加第一个标志。若在引导完成后作为后续请求提出，则用一句话确认并停止：不要重新启动引导，也不要添加新的第一个标志。
• 如果用户要求会话回放但未指定隐私级别，请使用最严格的设置（浏览器中使用 privacySetting: 'strict'）。
• 如果已安装的 SDK 版本过旧，不支持 plugins，且修复方法需要升级主版本或更换程序包，请先询问用户，并用一句话说明版本问题。
• 如果该技术栈没有可观测性插件，请用一句话说明，并继续使用功能标志。不要改用 OpenTelemetry 或其他程序包。

SDK 密钥

SDK 需要密钥。MCP 已连接时，默认代用户获取密钥；否则提供直接链接，让用户粘贴密钥。只有无法确定路径时才询问：

{
  "questions": [
    {
      "id": "sdk_key_setup",
      "prompt": "Do you have a LaunchDarkly account?",
      "options": [
        { "id": "yes", "label": "Yes" },
        { "id": "no_account", "label": "Not yet" }
      ]
    }
  ]
}

• 已连接 MCP 的账户：通过 get-environments 获取密钥，将密钥写入 .env，并确保 .env 已加入 gitignore。绝不输出密钥值。
• 未连接 MCP 的账户：提供直接链接，让用户粘贴密钥。https://app.launchdarkly.com/projects/{projectKey}/settings/environments/{envKey}/keys
• 没有账户：提供解析后的注册链接。写入占位环境变量，确保代码可以编译，然后继续。

密钥类型必须与集成方式匹配：服务端 SDK 使用 SDK 密钥，浏览器／客户端 SDK 使用 客户端 ID，移动端使用 移动密钥。环境变量名称和打包工具规则见应用代码更改。

初始化验证完成前，不要继续。

---

步骤 4：创建第一个标志

创建标志，将其接入应用，并让用户亲眼看到它开启。

• 创建标志。 如果已连接 MCP，请调用 create-flag（如果遇到重复键冲突，请调用 get-flag 并使用已有标志；不要先调用 list-flags）。如果未连接 MCP，请提供一个打开创建表单且已预填标志键的控制台链接，让用户自行创建：https://app.launchdarkly.com/projects/{projectKey}/flags/new?key={flagKey}
• 添加受标志控制的横幅。 在应用的主页面顶部插入一个简洁的小横幅，由标志控制。关闭状态：显示中性横幅，文字为 “LaunchDarkly test banner (flag is off)”，并附上一个用于在 LaunchDarkly 中查看标志的链接。开启状态：横幅切换为明显不同的样式（例如绿色背景），文字为 “LaunchDarkly test banner (flag is on)”。让它看起来像精心设计的界面，而不是调试输出。请在现有应用中添加，不要重写应用。对于没有渲染页面的应用，请添加一个等效的可见输出（端点或启动时输出的行），让它随标志状态变化。
• 在空闲端口上启动开发服务器（先检查 lsof -ti :3000,4000,5173）。在用户看到标志开启之前，让服务器持续运行。不要提前停止服务器。
• 让用户亲自开启标志。 提供本地 URL，并给出一种开启方式：

{
  "questions": [
    {
      "id": "flip_method",
      "prompt": "Your app is running at <url> and the flagged element is off. Turn the flag on to watch it change. How do you want to flip it?",
      "options": [
        { "id": "ld_ui", "label": "I'll flip it in LaunchDarkly" },
        { "id": "agent", "label": "Flip it for me" }
      ]
    }
  ]
}

• 如果用户选择 我会在 LaunchDarkly 中开启：提供标志的直达链接并等待。https://app.launchdarkly.com/projects/{projectKey}/flags/{flagKey}/targeting?env={envKey}
• 如果用户选择 替我开启：通过 toggle-flag（MCP）或 REST API 开启，使用已配置的方式。如果两者都未配置，则改为提供控制台链接。
• 仅当 MCP 或 API 令牌确实已配置时，才提供 替我开启 选项。否则只显示 LaunchDarkly 选项。

不要在聊天中打印页面或横幅文字。请引导用户前往浏览器：服务器仍在运行时，<url> 上的横幅会实时切换。这就说明标志已正常工作。

收尾

控制在几行内：

• 标志已启用。在 LaunchDarkly 中查看：https://app.launchdarkly.com/projects/{projectKey}/flags/{flagKey}/targeting?env={envKey}
• 没有提交任何内容。你的更改位于 launchdarkly-onboarding 分支上，可以自行查看、保留或丢弃。
• 提供一个后续操作选项。如果在设置期间添加了插件，则移除可观测性选项。

{
  "questions": [
    {
      "id": "explore_next",
      "prompt": "Want to explore more of LaunchDarkly?",
      "options": [
        { "id": "experimentation", "label": "Experimentation: test changes and measure impact" },
        { "id": "observability", "label": "Observability: monitor flags and errors in production" },
        { "id": "ai_configs", "label": "AI Configs: manage AI models and prompts" },
        { "id": "done", "label": "Not now" }
      ]
    }
  ]
}

---

重定向偏离流程

如果用户要求跳过某个步骤，或在流程中途跳到后续步骤，你的第一条回复必须在编写代码或跳过步骤前，依次完成以下三件事：

1. 用用户自己的话回应其请求。
2. 用一句话说明跳过的具体后果。明确指出会出什么问题（例如：“安装 SDK 前，标志调用无法运行”）。说清楚实际故障，不要含糊其辞。
3. 提供选择：先完成这个快速步骤，或按用户的方式继续。

“我明白，你想现在就要标志代码。没有安装 SDK，这些调用就无法运行。设置大约需要两分钟。你想先让我完成设置，还是直接给你代码，之后再自行接入？”

不要不说明取舍就直接输出代码，也不要僵化地拒绝。如果用户坚持，请尊重其选择，说明跳过了哪些步骤，用一句话重申风险，然后继续。

---

技能仓库

仓库	技能	用途
launchdarkly/ai-tooling	onboarding、sdk-install、mcp-configure	设置
launchdarkly/ai-tooling	launchdarkly-flag-create 及相关技能	标志管理

边缘情况

• 已安装 SDK： 跳过第 3 步。用一行说明你发现了什么以及位置，然后转到第 4 步。不要重新解释 SDK，也不要运行安装命令。如果用户要求可观测性，仍应先将插件添加到现有客户端（可观测性插件）。
• 已配置 MCP： 使用现有配置。跳过第 2 步的提议。调用 get-project 来存储密钥并继续。
• 发现已弃用的 mcp/aiconfigs 或 mcp/fm： 两者都已弃用。迁移到统一的 mcp/launchdarkly 服务前，先征求用户同意。不要自动迁移。
• 未检测到受支持的 Agent： 直接询问。必要时提供手动配置。
• 无法使用 npx： 提供手动安装技能的方法（克隆仓库，复制技能目录）。
• 用户只想进行部分设置： 尊重用户的选择。说明缺少哪些内容，以及这会带来哪些限制。
• 安装或编译 SDK 需要更改非 LaunchDarkly 依赖项（提升 peer-dep 版本、导致锁文件变更）：须先征得用户明确同意，详见应用代码更改。

参考资料

• mcp-configure 和 MCP Config Templates — 第 2 步
• sdk-install — 第 3 步（检测、规划、应用）
• SDK recipes 和 SDK snippets — 各 SDK 的安装和初始化详情
• Observability plugin — 第 3 步，用户要求可观测性或会话回放时使用