需要管理 LaunchDarkly 自定义业务指标时，用…

在已接入 LaunchDarkly 的项目中，为配置或代理业务指标建立从定义、上报到查询和清理的完整闭环。

适用场景

解决思路

1. 优先自动检测 LaunchDarkly API key：读取 ~/.claude/config.json，查找 mcpServers.launchdarkly.env.LAUNCHDARKLY_API_KEY；若不存在，依次检查环境变量 LAUNCHDARKLY_API_KEY、LAUNCHDARKLY_API_TOKEN、LD_API_KEY；全部失败再提示用户输入。
2. 按完整生命周期操作：Create 用 API 定义 metric；Track 用 SDK 发送事件；Get 用 API 读取 metric 定义/数据；Update 用 API 修改 metric 属性；Delete 用 API 删除 metric。
3. 创建 numeric custom metric 时，向 https://app.launchdarkly.com/api/v2/metrics/{project_key} 发 POST，payload 包含 key、name、kind="custom"、isNumeric=True、eventKey（默认与 metric_key 相同）；numeric custom metric 还必须包含 unit 和 successCriteria，否则 API 返回 400 Bad Request；description 可选。
4. 创建 metric 时设置 headers：Authorization=API_TOKEN、Content-Type=application/json；处理 201 创建成功、409 已存在、400 缺少 numeric 必填字段及其他错误。
5. 创建 metric 时选择 kind：custom 跟踪任意事件（代理指标最常用）、pageview 跟踪页面浏览、click 跟踪点击事件。
6. numeric metric 的 successCriteria 选择 HigherThanBaseline（越高越好，如 revenue、satisfaction）或 LowerThanBaseline（越低越好，如 errors、latency）。
7. 常用 unit 选择 count（通用计数）、milliseconds（时长）、percent（百分比）、dollars（货币）。
8. 通过 SDK 上报事件前先初始化：ldclient.set_config(Config("your-sdk-key"))，ld_client = ldclient.get()。
9. 用 Context.builder(user_id).build() 创建 context，然后调用 ld_client.track(metric_key, context, data=data, metric_value=value) 上报事件。
10. 跟踪转化/收入模式：调用 track("business.conversion", context, data={"configKey": config_key, "category": "electronics"}, metric_value=amount)。
11. 跟踪任务成功/失败模式：调用 track("task.success_rate", context, data={"taskType": task_type}, metric_value=1.0 if success else 0.0)。
12. 跟踪满意度模式：调用 track("user.satisfaction", context, data={"feedbackType": feedback_type}, metric_value=score)，score 为 0-100；若 score < 50，额外调用 track("user.negative_feedback", context, metric_value=1.0) 用于告警。
13. 跟踪收入模式：用 Context.builder(user_id).set("tier", "premium").build() 设置 context；若 revenue > 0，调用 track("revenue.impact", context, data={"source": source}, metric_value=revenue)。
14. 获取单个 metric：GET https://app.launchdarkly.com/api/v2/metrics/{project_key}/{metric_key}，headers 含 Authorization；200 时读取 key、name、kind、isNumeric、eventKey；404 表示不存在。
15. 列出 metrics：GET https://app.launchdarkly.com/api/v2/metrics/{project_key}，可传 params={"limit": limit}；200 时从 items 读取并打印 key、kind、numeric 状态。
16. 更新 metric：PATCH https://app.launchdarkly.com/api/v2/metrics/{project_key}/{metric_key}，headers 含 Authorization 和 Content-Type=application/json，body 为 JSON Patch 操作列表，如 [{"op": "replace", "path": "/name", "value": "New Name"}]；处理 200、404 及其他错误。
17. 重命名 metric：构造 updates 包含 replace /name；若提供 new_description，再追加 replace /description；调用 update_metric。
18. 删除 metric：DELETE https://app.launchdarkly.com/api/v2/metrics/{project_key}/{metric_key}，headers 含 Authorization；204 表示删除成功，404 表示不存在。
19. 完整工作流：设置 API_TOKEN、SDK_KEY、PROJECT_KEY；初始化 SDK；先 create_metric 创建 "ai.task.completion"；再用 ld_client.track 发送 1.0、1.0、0.0 等事件并调用 ld_client.flush()；然后 get_metric；再用 rename_metric 改名；再 list_metrics；不再需要时 delete_metric。
20. 使用 SessionMetricsTracker 跟踪会话：start_session(user_id, session_id) 存储 user_id、start_time、interactions=0、successful_tasks=0。
21. track_interaction(session_id, success) 增加 interactions；success 为真时同时增加 successful_tasks。
22. end_session(session_id) 计算 duration = time.time() - start_time；用 Context.builder(user_id).build()；调用 track("session.duration", context, data={"interactions": interactions}, metric_value=duration)；若 interactions > 0，计算 success_rate = successful_tasks / interactions，并调用 track("session.success_rate", context, metric_value=success_rate * 100)；返回包含 session 数据和 duration 的结果并删除内存中的 session。
23. 命名约定使用点号层级，如 quality.accuracy、quality.relevance、user.satisfaction、user.engagement、revenue.conversion、task.success_rate、session.duration、ai.task.completion、ai.recommendation.conversion。
24. 最佳实践：先创建 metric 再 track；聚合场景使用 numeric metric，设置 isNumeric=True；create_metric() 和 ld_client.track() 使用一致 key；关闭前始终 flush（Node 中 await），短生命周期脚本和长期服务都适用；不要对每次按键都 track，遵守限流。
25. 查看 metrics：在 LaunchDarkly UI 的 Metrics 页面、配置的 Monitoring tab，或通过 API 的 get_metric()/list_metrics() 查看。

适用边界 · 注意事项

• 没有 LaunchDarkly 账号、server SDK，或没有具 `writer` 角色的 API token 时无法使用。
• 不向 LaunchDarkly 发送或存储指标数据，或使用其他可观测性平台时，应改用该平台方案。
• 只需要内置 agent metrics（tokens、duration、cost）时，优先查看 built-in-metrics，而不是本自定义指标流程。