launchdarkly-metric-create

LaunchDarkly 指标创建

你正在使用一项技能，它将指导你创建 LaunchDarkly 指标。对于自定义指标，首先要确保事件开始流入，然后才能创建指标。你的任务是确定合适的指标类型；如果事件尚未流入，就为其添加埋点（包括 SDK 设置和环境配置）；检查是否存在重复项；提出指标配置方案；获取明确确认；然后创建并验证指标。

前提条件

此技能要求你在环境中配置远程托管的 LaunchDarkly MCP 服务。

必需的 MCP 工具：

• create-metric — 创建指标
• get-metric — 创建后验证指标
• get-environment — 添加埋点时获取客户端 SDK 密钥

可选的 MCP 工具（可增强工作流）：

• list-metrics — 检查是否存在具有相同事件键的指标，并了解命名惯例
• list-metric-events — 在确定事件键之前，查找近期有活动的事件键（仅适用于自定义指标）

两种不同的“项目”——切勿混淆

用户会使用两个完全不同的事物，而它们都被称为“项目”。你必须始终将它们区分开来：

	它是什么	用户如何称呼它	你如何处理
LaunchDarkly 项目	用户的 LD 账户中将创建指标的项目	通常听起来像环境或团队名称：my-app、anthony-agent-dev-5000、production	在所有 MCP 工具调用中作为 projectKey 传递
本地代码库	开发者磁盘上的应用，你将在其中添加 track() 调用	通常是文件夹名、仓库名或应用名：checkout_proj、frontend、my-react-app	用于查找和编辑源文件

根据用户输入判断两者的规则：

• 如果用户说 “我的应用在 X”、“我的代码库” 或 “我的仓库” → 指的是本地代码库。X 是文件夹路径或项目名称，而不是 LaunchDarkly 密钥。
• 如果用户说 “将它添加到 X”、“在 LaunchDarkly 中” 或 “我的 LD 项目” → 指的是 LaunchDarkly 项目。X 是 API 调用所用的 projectKey。
• 用户的本地代码库可以命名为 checkout_proj，而他们的 LaunchDarkly 项目可以命名为 anthony-agent-dev-5000。两者互不相关。
• **切勿假定本地代码库名称就是 LaunchDarkly 项目密钥。**如果不确定两者分别是什么，请直接询问：“确认一下——你的 LaunchDarkly 项目密钥是什么？（它与本地应用名称不同，你可以在 LD UI 的 Account Settings > Projects 下找到。）”

如果两者都需要（例如自定义指标需要添加埋点），请在继续之前分别确认。

工作流

第 1 步：确定指标类型

LaunchDarkly 有三种指标类型。首先要选择正确的类型，再进行其他操作。

类型	事件如何收集	要求
custom	开发者在代码中调用 ldClient.track(eventKey)	eventKey
pageview	用户访问匹配的 URL 时自动触发——无需调用 SDK	urls（URL 匹配规则）
click	用户点击匹配 URL 上的 CSS 选择器时自动触发——无需调用 SDK	urls + selector

选择规则：

• 用户说“跟踪有人查看页面/访问 URL” → pageview（优先选择——无需添加埋点）
• 用户说“跟踪有人点击按钮/链接” → click
• 用户说“跟踪自定义事件”或提到了 track() 调用 → custom

如果 pageview 或 click 可行，建议优先使用，而不是 custom——它们无需更改代码。

第 2 步：确定数据源

对于 pageview 和 click 指标：

• 询问要匹配的 URL。确认 URL 匹配规则的 kind：
  • substring — URL 包含此字符串（最常见）
  • exact — URL 必须完全匹配
  • canonical — 匹配规范 URL
  • regex — 完整的正则表达式模式
• 对于 click 指标，还需询问 CSS 选择器（例如 .checkout-btn、#submit）。
• 跳过 list-metric-events — 这些指标不使用事件键。
• 跳到第 3 步。

对于 custom 指标 — 先检查事件，如有需要则进行埋点：

立即调用 list-metric-events 查看哪些事件键已经在上报：

list-metric-events(projectKey, environmentKey?)

情况 A — 事件键已在列表中： 与用户确认该键，然后继续第 3 步。无需埋点。

情况 B — 事件键不在列表中： 没有事件，该指标就无法度量任何内容。在创建指标之前，现在就对该事件进行埋点。 不要只是警告并询问是否继续 — 将埋点视为默认的下一步操作。

按照下方的埋点子工作流执行，然后重新检查 list-metric-events，确认事件已在上报，再进入第 3 步。只有当用户明确表示想先创建指标、之后再接入事件时，才跳过埋点 — 在这种情况下，最后要提醒他们：在事件被追踪之前，该指标不会产生任何数据。

第 2b 步：对事件进行埋点（当事件未上报时）

此子工作流会将一个 track() 调用加入代码库，并将应用连接到正确的 LaunchDarkly 环境。在返回主工作流之前，请完成所有步骤。

1. 在代码库中找到正确的位置。 定位事件自然发生的函数或处理程序（例如结算提交处理程序、表单提交回调）。在做出更改之前，阅读相关源文件以了解现有结构。

2. 确定事件键。 如果用户尚未指定，请提出一个描述性的 kebab-case 键，与代码所做的事情相匹配（例如 checkout-completed、signup-submitted）。在使用之前与用户确认。

3. 获取客户端 SDK 密钥。 询问用户想连接到哪个环境（例如 "test"、"production"、"staging"）— 只需环境名称。然后调用：

get-environment(projectKey, environmentKey)

使用响应中的 clientSideId。

4. 写入环境文件。 检查是否已存在 .env 文件（或等效文件 — .env.local、.env.development 等）。

• 如果该文件不存在，则创建它。
• 如果该文件存在且已包含该键（例如 VITE_LD_CLIENT_SIDE_ID），请将存储的值与 get-environment 返回的 clientSideId 进行比较。如果它们不同，请向用户指出这一差异：

  "你的 .env 中已有 VITE_LD_CLIENT_SIDE_ID=<old>，但 get-environment 为 <env> 环境返回的是 <new>。需要我更新它吗？" 不要默默地保留旧值 — 客户端 ID 不匹配意味着事件会被发送到错误的项目或环境。

• 如果文件存在但缺少该键，则添加它，不要改动其他值。

使用适合项目构建工具的变量名（例如 Vite 用 VITE_LD_CLIENT_SIDE_ID，CRA 用 REACT_APP_LD_CLIENT_SIDE_ID，Next.js 用 NEXT_PUBLIC_LD_CLIENT_SIDE_ID）。

4b. 如果用户不在 app.launchdarkly.com 上，则设置 SDK 基础 URL。 SDK 默认将所有流量发送到 app.launchdarkly.com。如果用户使用的是不同的 LaunchDarkly 部署（例如 catamorphic 这样的内部 staging 环境，或专用实例），事件和标志评估会悄无声息地发送到错误的主机。

通过检查 MCP API 响应中的任何 _links 或 UI URL 来检测这一点 — 如果它们指向 app.launchdarkly.com 以外的主机，则说明你处于非生产部署上。如有疑问，请询问：

"你是连接到 app.launchdarkly.com 还是其他的 LaunchDarkly 实例？（例如内部或 staging 环境）" 如果使用的是非标准主机，请在 .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：

asyncWithLDProvider({
  clientSideID,
  context: { kind: 'user', anonymous: true },
  options: {
    baseUrl: import.meta.env.VITE_LD_BASE_URL,
    streamUrl: import.meta.env.VITE_LD_STREAM_URL,
    eventsUrl: import.meta.env.VITE_LD_EVENTS_URL,
  },
})

如果使用的是 app.launchdarkly.com，则完全省略 options 块——默认值正确，无需额外配置。

5. 安装并初始化 SDK（如果尚未安装）。 检查 package.json（或相应的依赖文件），确认是否已存在 LD SDK。如果没有，请根据项目技术栈安装合适的 SDK：

• React → launchdarkly-react-client-sdk
• Browser JS → launchdarkly-js-client-sdk
• Node.js server → @launchdarkly/node-server-sdk

在应用的入口点初始化 SDK（例如，用 LDProvider 包装 React 根节点，在服务端入口配置 LDClient.init() 等）。传入环境文件中的客户端 ID。除非应用已管理用户上下文，否则默认使用匿名用户／上下文。

6. 添加 track() 调用。 在步骤 1 确定的位置，于操作完成之前或之后立即添加调用：

• 计数／发生次数指标：ldClient.track('event-key')
• 数值指标：ldClient.track('event-key', null, numericValue)

在可能尚未初始化客户端的客户端代码中，使用可选链（ldClient?.track(...)）。

7. 验证事件是否正常流入。 完成埋点更改后，提醒用户运行应用并至少触发一次该事件。然后再次调用 list-metric-events，确认该键已出现，再继续创建指标。

第 3 步：检查现有指标

创建任何内容之前，使用 list-metrics 扫描项目：

1. 检查重复项。 搜索具有相同事件键、URL 模式或相似名称的指标。避免创建衡量相同内容的第二个指标；应指出现有指标，并询问用户是否要重复使用。
2. 了解命名约定。 指标键使用 kebab-case 还是 snake_case？是否存在常见的标签模式？遵循现有约定。
3. 了解标签分类体系。 可能已有 team:growth、area:checkout 或 type:guardrail 等标签。根据用户的描述，推荐相关标签。

第 4 步：提出指标配置

调用任何 API 之前，先用通俗语言向用户说明拟议的配置，让用户确认或修改。

确定度量类型。 正确的选择取决于用户想了解什么，以及如何使用该指标——用于实验、受保护的发布，还是发布策略。不要自行假设。 如果事件是用户可以重复执行的操作（点击、加入购物车、查看页面等），提出建议前务必先询问：

“您想衡量此事件总共发生了多少次（count），还是触发过此事件的用户所占百分比（occurrence）？”

结合用户的上下文提问：

• 实验 — 对于转化目标，常用 occurrence（处理是否让更多用户执行了某项操作？）；对于参与度或数量目标，count 更合适（处理是否带来了更多总操作量？）
• 受保护的发布／发布策略 — 对于错误率防护指标，通常使用 occurrence（有多少比例的用户遇到了错误？）；对于绝对数量防护指标，使用 count（错误事件总数）
• 如果用户明确说“用户百分比”或“转化率” → occurrence
• 如果用户明确说“次数”或“事件总数” → count

只有当上下文能明确表达意图时，才可以跳过询问（例如，“API 延迟” → value，“错误率” → count，“注册转化” → occurrence）。

用户想要衡量的内容	度量类型	含义
事件发生的总次数	count	每个分析单位的原始事件计数
每个用户是否触发过该事件	occurrence	转化／二元结果（是否发生？）
与事件关联的数值	value	延迟、收入、分数等

确定成功标准：

• 越高越好 → HigherThanBaseline（转化率、收入、参与度）
• 越低越好 → LowerThanBaseline（延迟、错误率、跳出率）

当用户意图明确时，使用常见模板作为默认值：

用户意图	kind	度量类型	成功标准	单位
页面访问／查看率	pageview	occurrence	HigherThanBaseline	—
按钮／链接点击率	click	occurrence	HigherThanBaseline	—
API 延迟／页面加载时间	custom	value（平均值）	LowerThanBaseline	ms
注册／转化率	custom	occurrence	HigherThanBaseline	—
错误数量／错误率	custom	count	LowerThanBaseline	—
每位用户的收入	custom	value（总和）	HigherThanBaseline	USD

创建前先展示拟议的配置——不要悄悄调用 API：

Proposed metric:
  Key:              checkout-page-viewed
  Name:             Checkout Page Viewed
  Kind:             pageview (fires automatically on URL visit — no code change needed)
  URLs:             substring match on "/checkout"
  Measure type:     occurrence (did each user visit the page?)
  Success criteria: HigherThanBaseline

Proceed, or would you like to change anything?

在此处停止。 不要调用任何 API。不要继续第 5 步。等待用户明确确认后再进行任何操作。调用 create-metric 前，用户必须明确批准（例如“是”“看起来不错”“继续”）。如果拟议配置存在任何歧义——例如选择 sum 还是 average，或事件键名称——请在方案中提出问题，并等待用户回答后再继续。

第 5 步：创建指标

只有在用户明确确认了第 4 步中拟议的配置后，才能继续。 如果尚未收到确认，请返回并等待。

用户确认后，调用 create-metric。该工具会处理从 measureType 到底层 API 字段的转换——你无需直接传入 isNumeric 或 unitAggregationType。

create-metric(
  projectKey,
  key,
  name,
  kind,              // "custom" | "pageview" | "click"
  eventKey?,         // only for kind="custom"
  urls?,             // only for kind="pageview" or "click": [{ kind, url }]
  selector?,         // only for kind="click": CSS selector string
  measureType,       // "count" | "occurrence" | "value"
  successCriteria,   // "HigherThanBaseline" | "LowerThanBaseline"
  valueAggregation?, // only for measureType="value": "average" (default) or "sum"
  unit?,             // display label: "ms", "USD", etc.
  description?,
  tags?
)

第 6 步：验证

使用 get-metric 确认指标已按正确配置创建：

1. 键和名称与请求一致。
2. kind 正确——custom、pageview 或 click。
3. measureType 正确——请读取 measureType 字段再次确认，而不只是查看 isNumeric。
4. eventKey / urls / selector 已设为预期值。
5. successCriteria 正确。

向用户提供摘要：

✓ Metric created: checkout-page-viewed
  Kind:     pageview (auto-tracked on URL visit)
  URLs:     substring "/checkout"
  Measures: occurrence (conversion rate)
  Goal:     Higher is better

View in LaunchDarkly: {_links.ui from the create-metric response}

create-metric 工具会返回 _links.ui 字段，其中包含当前环境对应的正确 URL。始终使用该值，绝不要将 app.launchdarkly.com 写死。

测量类型参考

create-metric 工具会在内部将 measureType 转换为 LD API 字段。你无需直接设置 isNumeric 或 unitAggregationType。

measureType	isNumeric	unitAggregationType	适用场景
count	false	sum	原始事件计数——错误率、点击次数
occurrence	false	average	转化——用户是否执行了该操作？
value（average）	true	average	用户平均值——平均延迟、平均会话时长
value（sum）	true	sum	用户总量——总收入、购买商品总数

对于 value 指标，valueAggregation 默认为 "average"。对于收入或累积总量，请传入 valueAggregation: "sum"。

重要背景

• 尽可能优先使用 pageview 和 click，而不是 custom。 它们不需要 SDK 埋点，并且能在浏览器环境中自动生效。
• 事件键区分大小写。 checkout-completed 和 Checkout-Completed 是不同的事件。请确保键与 track() 调用中显示的完全一致。
• 没有事件的自定义指标不会产生数据。 只有当其事件键已在生产环境（或相关环境）中主动跟踪时，自定义指标才有用。如果你在为事件添加埋点之前就创建了指标，请提醒用户。
• 指标键不可变。 创建后，无法更改指标的键。请谨慎选择。
• 指标的作用范围为项目级。 在一个项目中创建的指标在其他项目中不可见。请确保 projectKey 与实验或标志所在位置一致。
• 每个实验只有一个主要指标。 将此指标关联到实验时，请说明它是主要指标（用于判定成功或失败）还是次要指标（用于监控护栏或提供辅助信号）。有关实验设置，请参阅 LaunchDarkly 文档。