diff-intake

diff-intake

请按步骤遵循此技能。 你负责分析埋点工作流的第 1 步。请生成一份简洁的 YAML 变更概要，供下游技能（discover-event-surfaces、 instrument-events）使用。输出必须机器可读且精确——YAML 块之外不要添加说明文字。

步骤 1：收集变更文件并分类

从来源获取变更文件列表，然后逐一分类。

获取变更

• PR URL gh pr view <number-or-url> gh pr view <pr-number> --json files --jq '.files[] | "\(.path)\t+\(.additions) -\(.deletions)\t"'
• 分支比较 git log <main|master>..<branch> git diff --stat <main|master>..<branch>
• 提及不明确（PR 编号、分支名称）：推断正确形式并直接获取，无需询问，除非授权失败。

文件分类

根据文件路径将每个文件分配到一个类别：

• 核心逻辑：应用程序源代码（例如 src/auth/login.py、database/models.ts）
• 生成文件：路径中包含 generated 的任何文件
• 测试：测试文件
• 配置／依赖项：package.json、docker-compose.yml 等
• 文档：README、docs/
• 杂项：锁文件、.svg、自动生成的迁移文件

对每个文件记录：路径、类别、变更类型（Added / Modified / Deleted）以及分析可能性（1–5）。

步骤 2：构建文件摘要映射

读取每一个核心逻辑文件，并创建文件摘要映射。 仅处理并纳入核心逻辑文件。

获取详细差异

• PR gh pr view <number-or-url> --json baseRefOid,headRefOid 使用响应获取详细差异 git diff <baseRefOid>...<headRefOid> -- <file1> <file2> <file_n>
• 分支比较 git diff main..feature/foo -- <file1> <file2> <file_n>

对每个文件记录

• summary — 用 2 行概述变更内容
• stack — frontend、backend 或 shared

同时推导面向用户的变更和涉及的界面

阅读差异和变更文件时，同时生成事件发现下游所需的高层信号：

• user_facing_changes — 描述对用户、PM 或分析人员有影响的具体行为变更的扁平列表。每项应说明用户现在可以做什么、看到什么，或体验上有何不同。省略纯内部重构。
• surfaces.components — 直接涉及这些面向用户变更的 UI 组件、路由、页面、处理程序或其他交互界面。优先选择可能的埋点位置，而不是底层辅助程序。

对每个界面记录：

• name — 组件、路由、页面、钩子或界面名称
• file — 仓库相对路径
• change — added、modified 或 deleted

如果变更仅涉及后端，或没有明确的交互界面，则省略 surfaces.components，不要凭空编造。

步骤 3：对整体变更分类

推断变更类型和分析范围：

类型	分析影响
feat	高 — 新界面可能需要埋点
fix	低–中 — 可能影响现有事件的触发条件
refactor	低 — 埋点路径可能发生变化，存在回归风险
perf	低 — 通常不会影响埋点
revert	中 — 需要检查哪些埋点已丢失
style / docs / test / build / ci / chore	无 — 跳过分析

analytics_scope = 影响最高的范围：

• none — 仅包含无影响类型
• low — 仅包含 perf/refactor
• medium — 包含 fix
• high — 包含任何功能或能力新增

如果 analytics_scope 为 none，则输出概要，并注明无需使用下游技能。

第 4 步：输出 YAML 摘要

仅输出 YAML 块——前后都不要添加文字。严格遵循此格式。 在 file_summary_map 中逐个列出文件（不要使用通配符）。

change_brief:
  classification:
    primary: feat           # dominant conventional commit type
    types: [feat, fix]      # all types detected
    analytics_scope: high   # none | low | medium | high
    stack: frontend         # frontend | backend | fullstack
  summary: "One sentence describing the overall change"
  user_facing_changes:
    - "Users can now upload an avatar with drag-and-drop and preview it before saving."
  surfaces:
    components:
      - name: "AvatarUpload"
        file: "src/components/AvatarUpload.tsx"
        change: modified
  file_summary_map:         # each entry includes a layer field
    - file: "src/components/AvatarUpload.tsx"
      summary: "New component for avatar upload with drag-and-drop and preview"
      layer: frontend       # frontend | backend | shared
    - file: "src/api/upload.ts"
      summary: "Upload endpoint handler, validates file type and persists to S3"
      layer: backend