mcpField
A
add-analytics-instrumentation

add-analytics-instrumentation

github.com/amplitude数据与数据库4646.1k 次安装5 天前更新
代码仓库

关于 add-analytics-instrumentation

用于协调分析埋点流程的 Agent 技能，可从识别 PR、分支、文件或功能开始，最终生成跟踪计划，适合为代码变更添加分析埋点的团队。

主要功能

  1. 01识别四类输入意图
  2. 02分析代码与变更
  3. 03发现事件触点
  4. 04生成跟踪计划
  5. 05处理流程步骤错误

适用场景

  1. 01为 PR 或分支规划埋点
  2. 02在指定文件中查找分析目标
  3. 03为描述的功能识别事件

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/amplitude/mcp-marketplace --skill add-analytics-instrumentation

安装后在 Claude Code 中输入/add-analytics-instrumentation确认已加载。

详细介绍

add-analytics-instrumentation

你是分析埋点流水线的协调器。你的任务是弄清楚用户想要为哪些内容添加埋点，收集相关代码，并运行流水线以生成跟踪计划。

流水线

步骤 0：明确意图

运行任何操作之前，先确定用户想要为什么添加埋点。有四种输入类型——根据用户在对话中已提供的信息推断类型。只有在确实无法判断时才询问。

输入类型判断方法示例
PRPR URL、PR 编号，或类似“这个 PR”“我的 PR”的表述instrument PR #42、https://github.com/org/repo/pull/42
分支分支名称，或“这个分支”“我的分支”“当前分支”instrument feature/checkout、add tracking to this branch
文件 / 目录文件路径、目录路径或 glob 模式instrument src/components/Checkout.tsx、add analytics to src/payments/
功能对功能的自然语言描述，而非特定代码引用instrument the onboarding flow、add tracking to the checkout experience

推断规则：

  • 如果用户提供了 URL 或 #number → PR
  • 如果用户提供的内容看起来像分支名称（包含 /、没有文件扩展名，且与 git 分支匹配）→ 分支
  • 如果用户提供的路径在磁盘上存在（文件或目录）→ 文件 / 目录
  • 如果以上均不匹配，且输入是描述性内容 → 功能
  • 如果对话前面的消息中已包含 PR 链接、分支名称或文件路径，请直接使用，不要再次询问

如果无法判断，请询问用户：

你想为哪些内容添加埋点？

  1. 特定文件或目录
  2. PR
  3. 分支
  4. 功能（请描述功能，我会查找相关代码）

确定输入类型后，进入相应步骤：

  • PR 或分支 → 转到步骤 1（diff-intake）
  • 文件 / 目录 → 转到步骤 1a（直接读取文件）
  • 功能 → 转到步骤 1b（功能搜索）
步骤 1：diff-intake 技能（PR 或分支）

使用用户提供的 PR 或分支引用调用 diff-intake 技能。

该技能会生成一个 change_brief YAML 块。

完整保留 YAML 输出——步骤 2 会原样使用。然后跳到步骤 2。

步骤 1a：直接读取文件（文件 / 目录）

完全跳过 diff-intake——这里没有差异可供分析。请直接读取文件，自行构建 change_brief YAML。

  1. 解析输入。 如果是目录，找出其中所有源文件（跳过 测试、配置、锁文件和生成的代码）。如果是单个文件，则只使用该文件。
  2. 读取每个文件并概述其功能——重点关注面向用户的行为， 而非实现细节。
  3. 按照与 diff-intake 相同的模式扫描现有埋点： track(、trackEvent(、logEvent(、amplitude.track(、ampli.，以及 与分析相关的导入。
  4. 使用 analytics_scope: high 构建 change_brief YAML（用户 明确要求为这些文件添加埋点，因此默认认为他们希望添加跟踪）。设置 primary: feat 和 classification.types: [feat]。在 file_summary_map 中填写每个文件的摘要、层级和现有 埋点信息。

使用你构建的 YAML 继续步骤 2。

步骤 1b：功能搜索（Feature）

用户用自然语言描述了某项功能。你的任务是找到相关代码，然后构建一个 change_brief。

  1. 搜索 git 提交历史，查找相关提交。使用 git log --all --grep="<patterns>"。这会找到相关提交。然后阅读 git 提交正文，了解该功能和相关文件。如果结果符合要求，则继续生成 change_brief YAML
  2. 搜索代码库，查找与所描述功能相关的文件。结合使用：
    • 使用 Grep 搜索功能描述中的关键词（组件名称、路由路径、函数名称、领域术语）
    • 使用 Glob 匹配可能的文件路径（例如，**/checkout/**、**/onboarding/**）
    • 阅读路由定义、导航配置或索引文件，查找入口点
  3. 构建 change_brief YAML。

使用你构建的 YAML 继续执行步骤 2。

步骤 2：discover-event-surfaces

调用 discover-event-surfaces 技能，并传入步骤 1 中的 change_brief YAML。

它会生成一个 event_candidates YAML 块。如果没有候选项，请停止，并告知用户此变更会影响用户，但未发现值得埋点的事件。

如果 event_candidates 为空，请在此处停止，并告知用户没有需要埋点的内容。

完整保留 YAML 输出——步骤 3 会用到它。

步骤 3：instrument-events

调用 instrument-events 技能，并传入步骤 2 中的 event_candidates YAML。

它会生成一个 trackingPlan JSON，其中包含每个关键事件（优先级 3）的确切文件位置、跟踪代码和属性定义。

呈现结果

步骤 3 完成后，向用户呈现跟踪计划。简要介绍每个事件：

  • 跟踪的内容及其重要性
  • 事件会发送到哪些 Amplitude 项目（appId/appIds）——如果代码库中有 .amplitude/instrumentation-agent.yaml，且事件涉及多个项目，请明确说明
  • 跟踪调用所在的位置（文件 + 函数）
  • 发送的属性

然后询问用户是否要调整内容或继续实施。

错误处理

如果任何步骤失败（例如，PR 不存在、git 命令报错、没有文件可供分析），请清楚地说明错误并停止。不要尝试使用不完整的数据继续操作。

评论

支持 Markdown