turning-engineering-analytics-into-insights

将工程分析转化为洞察和订阅

工程分析仪表板和 MCP 工具（pull-requests、workflow-health、pr-lifecycle、engineering-analytics-broken-tests、……） 会在内部运行经过整理的 HogQL：界面或工具输出中都不会提及底层表， 这些端点本身也无法保存为洞察或供用户订阅。 不过，可以通过两个数据底层直接查询这些数据：

• 原始数仓表 — <prefix>github_pull_requests、<prefix>github_workflow_runs、 <prefix>github_workflow_jobs、<prefix>github_reviews 和 <prefix>github_teams / <prefix>github_team_members（组织团队成员关系——作者→团队映射）——可使用 HogQL 查询的普通团队范围表。
• 三个名称固定的精选数仓视图 — engineering_analytics_job_costs、 engineering_analytics_ci_job_history、engineering_analytics_ci_failures——根据已连接的 GitHub 来源为每个团队 配置。 非物化：在查询时计算，始终保持最新，可像任何表一样为洞察和订阅提供数据支持。

这些视图存在的唯一原因，是将产品代码转化为 SQL——运行器层级成本模型、失败指纹生成规则、作业↔运行的提交归属规则——如果手工实现，这些逻辑会悄然偏离；代码变更时，系统会将逻辑重新生成到团队的视图中。其他一切都只是表数据，纯 HogQL 查询原始表始终足够：切勿为工程分析数据创建额外的数仓视图，也切勿在 SQL 中重新推导这三个视图已经编码的内容。

产品展示的内容	数据的实际位置	能否为洞察提供数据支持？
PR 列表、合并时间、CI 状态、工作流健康状况	数仓表 <prefix>github_pull_requests、<prefix>github_workflow_runs	可以（对这些表运行 SQL 洞察）
审查和批准	<prefix>github_reviews	可以
团队级 PR 指标（作者→团队归属）	<prefix>github_team_members，与 PR 作者进行半连接	可以（仅支持团队聚合）
作业时长、排队时间、运行器层级	<prefix>github_workflow_jobs	可以
CI 成本（运行器层级价格梯度）	engineering_analytics_job_costs 视图	可以（查询该视图，切勿重新计算成本）
包含提交归属信息的逐作业 CI 历史	engineering_analytics_ci_job_history 视图	可以
分组后的（带指纹的）CI 失败日志行	engineering_analytics_ci_failures 视图（读取 Logs 产品，保留时间较短）	可以，但仅适用于近期的短时间窗口
PR 或运行对应的精简 CI 失败日志	Logs 产品（service_name = 'github-ci-logs'）+ 精简逻辑	不可以（按需使用 MCP 工具）
不稳定测试排行榜、失败测试分诊、团队 CI 健康状况	CI 跟踪跨度 + 产品代码中的排名/分类逻辑	不可以（按需使用 MCP 工具）
因此，任务可以明确划分为两部分：
由数仓支持的指标（原始表或三个视图）转化为 SQL 洞察（然后是仪表板，再然后是订阅）；
所有由产品逻辑在请求时计算的内容都保留在 MCP 工具中，如有需要，通过 AI 订阅定期发送。

步骤 1：查找团队的表

数仓表名带有用户自选前缀，因此切勿将其硬编码。 调用 engineering-analytics-sources MCP 工具：每个已连接的 GitHub 源都会返回其 id、repo 和 prefix。 表名包括 <prefix>github_pull_requests、<prefix>github_workflow_runs、<prefix>github_workflow_jobs、<prefix>github_reviews 和 <prefix>github_teams / <prefix>github_team_members； 前缀为空时，表名就是普通的 github_* 名称。 如果有多个源，请询问用户指的是哪个仓库；每个源对应一个仓库。

三个 engineering_analytics_* 视图无需查找：它们的名称固定（没有前缀），并且会一次性涵盖团队的所有 GitHub 源——按 repo_owner / repo_name（job_costs、ci_job_history）或 repo（ci_failures，它读取的是 Logs 产品，而不是每个源对应的表）筛选，即可限定到单个仓库。

步骤 2：编写保留精选语义的 HogQL

首先检查三个视图中是否已有视图能回答问题——成本、单个任务的历史记录和提交归因、带指纹的失败行——如果有，就直接查询该视图；以下规则适用于原始表。

原始表会原样写入 GitHub 的 JSON，因此，简单的 SELECT 会导致领域规则处理错误。 复制 references/hogql-recipes.md 中的基础子查询（它们与产品自身的精选构建器一致），并遵循以下规则：

• 时间戳是字符串。 比较或求差之前，务必先使用 parseDateTimeBestEffort(created_at) 等进行转换。
• 嵌套 JSON 是 Nullable。 在使用 JSONExtractArrayRaw / splitByChar 之前，先用 ifNull(...) 解包：ClickHouse 不接受 Nullable 中嵌套 Array。
• CI ↔ PR 归因按 PR 编号进行（即运行记录的 pull_requests 关联），绝不能按 head SHA 进行：PR 快照只保留当前 head，因此 SHA 联接会悄悄丢弃除最新一次之外的所有推送。head SHA 仅用于判断 PR 的_当前_ CI 状态（每个 (head_sha, workflow_name) 的最新运行）。
• 机器人检测：author_handle LIKE '%[bot]' OR author_handle IN ('dependabot', 'github-actions', 'posthog-bot', 'renovate')。默认在吞吐量 / 合并时间指标中排除机器人和草稿 PR。
• 如实命名。 merged_at - created_at 是 open_to_merge_seconds（它混合了草稿和评审时间）；切勿将洞察称为“周期时间”或“评审时间”。
• 结论可能过时。 运行记录同步时以 created_at 为水位；较晚完成的运行可能会显示过时的结论。仅使用 status = 'completed' 的行计算比率。
• 评审按 pr_number 联接。 在 github_reviews 中，state 的值为 APPROVED / CHANGES_REQUESTED / COMMENTED / DISMISSED（同步时会丢弃尚未提交的草稿），注入的 pr_number 与 PR 表的 number 联接。
• 作者到团队的归属使用成员资格半联接。 根据 github_team_members 中的 member_handle 筛选 author_handle IN (SELECT member_handle FROM …)（参见团队查询示例）——产品自身的团队合并趋势也采用这种方式。一个人可能属于多个 GitHub 团队，因此普通 JOIN 会导致其 PR 在多个团队中重复计数；而且查询输出的只能是团队级聚合结果，绝不能包含单个成员的数据。

保存前，请使用 execute-sql MCP 工具（或 SQL 编辑器）测试查询。

第 3 步：将其保存为洞察

使用带有 SQL 洞察的 insight-create：

{
  "name": "Weekly PR open→merge time (hours)",
  "query": {
    "kind": "DataVisualizationNode",
    "source": { "kind": "HogQLQuery", "query": "<tested SQL>" }
  }
}

display（一个 ChartDisplayType，例如 ActionsLineGraph）和 chartSettings（xAxis / yAxis 列）可将表格转换为图表； 如果不确定，就先保存，并让用户在 UI 中选择可视化方式，同时提供返回的洞察 URL 链接。 在 SQL 中加入相对时间范围（>= now() - INTERVAL 90 DAY）； 请注意，硬编码的日期筛选意味着仪表板的日期覆盖设置不会应用于此图块。 使用 dashboard-create 将多个洞察组合在一起。

第 4 步：订阅

洞察（或仪表板）保存后，接下来就是常规的订阅操作：按照 managing-subscriptions 技能设置 subscriptions-create 载荷、渠道、频率和 AI 摘要选项。

对于“当 X 发生时通知我”（这是一个条件，而不是日程安排）：警报需要趋势洞察，因此目前无法对 SQL 洞察设置警报。 请改为提供定时订阅，或在提示词类型的 AI 订阅中进行阈值检查。

不要在 SQL 中重建的内容

不稳定测试排名、失败测试分类、团队 CI 健康汇总和失败日志精简都是基于洞察无法访问的数据（CI 跟踪跨度、原始日志正文）的产品逻辑； 手动编写的 SQL 版本会悄然偏离仪表板所显示的内容。 如果要定期报告这些内容，请创建提示词类型的 AI 订阅（请参阅 creating-ai-subscription 技能），并在提示词中要求每期读取相关工程分析数据， 或者按需调用 MCP 工具（engineering-analytics-flaky-tests、engineering-analytics-broken-tests、engineering-analytics-team-ci-health、engineering-analytics-ci-failure-logs、engineering-analytics-run-failure-logs）。

CI 成本不在该列表中，因为其产品逻辑已呈现在 engineering_analytics_job_costs 视图中（该视图已通过与产品自身模型的对比测试，并会在模型 更改时重新生成），因此成本洞察只需基于此视图编写普通 SQL；成本 MCP 工具（engineering-analytics-pr-cost、 engineering-analytics-workflow-runner-costs）读取的也是同一条呈现后的 SELECT，因此数值一致。不过，切勿 自行根据 runner 标签重新计算美元成本。

每个洞察都必须附带的注意事项

请在洞察描述中列出以下内容，以便后续读者了解这些限制： open_to_merge_seconds 是粗略数据（草稿和审查合并计算）； CI 结论可能会延迟，直到运行的 webhook 处理完成； estimated_cost_usd 为 NULL 表示不可计费或仍在运行，而不是零——请通过 provider 和 completed_at 加以区分； ci_failures 仅统计 pytest 且仅统计失败，因此其计数是绝对信号，不是比率； 排除了机器人和草稿（或没有排除：请说明具体情况）。 切勿创建按作者划分的排行榜或跨作者排名；对开发者进行监控明确不属于产品目标。 如果需要按团队拆分，请通过 github_team_members 成员关系半连接进行分组。