在 LaunchDarkly…

当需要为实验或发布创建可衡量用户行为的指标（页面浏览、点击、转化、延迟、错误率等）时，先确定指标类型、必要时完成事件埋点，再创建并验证指标。

适用场景

解决思路

1. 先确定指标类型：custom（需在代码中调用 ldClient.track(eventKey)）、pageview（用户访问匹配 URL 时自动触发，无需 SDK 调用）、click（用户在匹配 URL 上点击 CSS 选择器时自动触发，无需 SDK 调用）。
2. 按用户意图选择类型：说“跟踪页面浏览/访问 URL”用 pageview；说“跟踪按钮/链接点击”用 click；说“跟踪自定义事件”或提到 track() 调用用 custom。能用 pageview 或 click 时优先建议它们，因为无需改代码。
3. 区分两个“项目”概念：LaunchDarkly project（作为 projectKey 传给 MCP 工具调用）与本地代码库（用于查找和编辑源文件）。用户说“我的应用/代码库/仓库”指本地代码库；说“加到 X / 在 LaunchDarkly 中 / 我的 LD 项目”指 LaunchDarkly project。不确定时直接询问 LaunchDarkly project key（可在 LD UI 的 Account Settings > Projects 找到）。
4. 对 pageview 和 click 指标：询问要匹配的 URL，并确认 URL 匹配规则类型（substring 最常见、exact、canonical、regex）；click 指标还要询问 CSS 选择器（如 .checkout-btn、#submit）；跳过 list-metric-events，直接进入检查已有指标步骤。
5. 对 custom 指标：立即调用 list-metric-events(projectKey, environmentKey?) 查看哪些事件键已在流动。若事件键已在列表中，与用户确认后继续；若不在列表中，默认先完成埋点再创建指标，而不是仅警告后询问是否继续。
6. 埋点前先在代码库中找到事件自然发生的函数或处理器（如结账提交处理器、表单提交回调），阅读相关源文件了解现有结构。
7. 若用户未指定事件键，提议一个描述性的 kebab-case 键（如 checkout-completed、signup-submitted），使用前与用户确认。
8. 询问用户要连接哪个环境（如 test、production、staging），然后调用 get-environment(projectKey, environmentKey)，从响应中取 clientSideId。
9. 检查 .env 文件（或 .env.local、.env.development 等）是否存在：不存在则创建；已存在且含该键时，将存储值与 get-environment 返回的 clientSideId 比较，若不同则向用户指出差异并询问是否更新，不要静默保留旧值；已存在但缺少该键时直接添加，不改动其他值。变量名按构建工具选择（Vite 用 VITE_LD_CLIENT_SIDE_ID，CRA 用 REACT_APP_LD_CLIENT_SIDE_ID，Next.js 用 NEXT_PUBLIC_LD_CLIENT_SIDE_ID）。
10. 若用户不在 app.launchdarkly.com 上，需设置 SDK base URL：通过 MCP API 响应中的 _links 或 UI URL 判断主机是否为非生产部署，不确定时直接询问。若是非标准主机，在 .env 中添加 VITE_LD_BASE_URL=https://<their-host>、VITE_LD_STREAM_URL=https://clientstream.<their-host-domain>、VITE_LD_EVENTS_URL=https://events.<their-host-domain>，并在 SDK 初始化时通过 options 传入 baseUrl、streamUrl、eventsUrl；若在 app.launchdarkly.com 上则完全省略 options 块。
11. 若 SDK 尚未安装，检查 package.json 等依赖文件，按技术栈安装：React 用 launchdarkly-react-client-sdk，浏览器 JS 用 launchdarkly-js-client-sdk，Node.js 服务端用 @launchdarkly/node-server-sdk；在应用入口初始化（如用 LDProvider 包裹 React 根节点、在服务端入口配置 LDClient.init()），传入环境文件中的 client-side ID，默认使用匿名用户/上下文，除非应用已管理用户上下文。
12. 在步骤 1 找到的位置添加 track() 调用：计数/发生类用 ldClient.track('event-key')，数值类用 ldClient.track('event-key', null, numericValue)；客户端代码中客户端可能尚未初始化时使用可选链 ldClient?.track(...)。
13. 埋点改动完成后，提醒用户运行应用并至少触发一次事件，然后再次调用 list-metric-events 确认该键出现，再进入指标创建。
14. 创建前用 list-metrics 扫描项目：检查是否有相同事件键、URL 模式或相似名称的重复指标（若有则标记并询问是否复用）；学习现有命名约定（kebab-case 还是 snake_case、常见标签模式）并保持一致；了解已有标签分类（如 team:growth、area:checkout、type:guardrail）并据此建议相关标签。
15. 确定度量类型：事件可重复发生时（点击、加购、浏览页面等）必须询问用户是要测“总共发生多少次”（count）还是“多少比例的用户至少触发一次”（occurrence）。结合场景提问：实验场景中转化目标常用 occurrence，参与度/量级目标常用 count；受保护发布/发布策略中错误率护栏常用 occurrence，绝对量护栏常用 count；用户明确说“用户百分比/转化率”用 occurrence，说“次数/总事件数”用 count。仅当意图明确时才跳过询问（如“API 延迟”用 value、“错误率”用 count、“注册转化”用 occurrence）。
16. 确定成功标准：越高越好用 HigherThanBaseline（转化率、收入、参与度），越低越好用 LowerThanBaseline（延迟、错误率、跳出率）。
17. 意图明确时使用常见模板作为默认：页面访问/浏览率 → pageview + occurrence + HigherThanBaseline；按钮/链接点击率 → click + occurrence + HigherThanBaseline；API 延迟/页面加载时间 → custom + value（average）+ LowerThanBaseline + 单位 ms；注册/转化率 → custom + occurrence + HigherThanBaseline；错误数/错误率 → custom + count + LowerThanBaseline；每用户收入 → custom + value（sum）+ HigherThanBaseline + 单位 USD。
18. 创建前用纯语言展示提议的配置（Key、Name、Kind、URLs/eventKey/selector、Measure type、Success criteria），然后停下等待用户明确确认（如“yes”“looks good”“proceed”），不得静默调用 API；若配置有歧义（如 sum 与 average 之争、事件键名称），在提议中一并提问并等待回答。
19. 用户确认后调用 create-metric(projectKey, key, name, kind, eventKey?, urls?, selector?, measureType, successCriteria, valueAggregation?, unit?, description?, tags?)。该工具内部处理 measureType 到 API 字段的转换，无需直接传 isNumeric 或 unitAggregationType。
20. 用 get-metric 验证创建结果：Key 和 Name 是否匹配、kind 是否正确（custom/pageview/click）、measureType 是否正确（读回 measureType 字段而非只看 isNumeric）、eventKey/urls/selector 是否为预期值、successCriteria 是否正确。
21. 向用户展示摘要，包含 create-metric 响应中的 _links.ui 字段作为查看链接，始终使用该值，绝不硬编码 app.launchdarkly.com。
22. 记住关键约束：事件键区分大小写（checkout-completed 与 Checkout-Completed 是不同事件）；没有事件的 custom 指标不产生数据；指标键创建后不可更改；指标按项目隔离，确保 projectKey 与实验或标志所在项目一致；附加到实验时明确它是主指标还是次要指标。

适用边界 · 注意事项

• 需要先配置远程托管的 LaunchDarkly MCP 服务器（含 create-metric、get-metric、get-environment 等工具），未配置时无法使用。
• 不适用于非 LaunchDarkly 的实验或指标平台。
• 若用户只想创建指标而明确表示稍后再接事件，可跳过埋点，但需在最后提醒该指标在事件被跟踪前不会产生数据。