auditing-warehouse-source-health

审计数据仓库源健康状况

此技能会对数据仓库流水线中源和同步部分进行项目范围的审计，包括源连接、同步架构和 webhook 推送通道。当用户想了解导入出了什么问题的概况，而不是深入调查某次同步时，请使用此技能。单项故障的深入调查请使用 diagnosing-failed-warehouse-syncs；此技能会扫描问题，告诉用户应该先从哪里着手。

同一个底层端点（data-warehouse-data-health-issues-retrieve）也会报告物化视图、批量导出目标和转换问题。物化视图由 auditing-warehouse-view-health 负责。目标（批量导出）和转换由其他产品负责——如果发现此类问题，请指出并转交给相关团队，而不要在此处进行诊断。

何时使用此技能

• “为什么我的导入会失败？”/“我的数据源出了什么问题？”
• “为什么我的数据仓库数据过时了？”
• 用户刚加入某个项目，想了解自己接手了哪些数据源以及它们的健康状况
• 每周或每月审查源和同步的健康状况
• 仪表板数据过时，用户不确定是哪个数据源出了问题

可用工具

工具	用途
data-warehouse-data-health-issues-retrieve	一次性获取：整个流水线中的所有失败或降级项
external-data-sources-list	所有数据源及其状态和最新错误
external-data-schemas-list	所有架构及其状态、last_synced_at、最新错误
external-data-sources-webhook-info-retrieve	检查每个数据源的 webhook 状态（data-health-issues 未涵盖）

data-health-issues 端点会汇总整个流水线的数据——这是获取概况最快的途径。本次审计仅筛选结果中的 source 和 external_data_sync 类型。若需要比概况更详细的上下文（行数、未失败的项目、架构级详情），请使用列表端点。

哪些情况算作 source/sync“问题”

在数据健康端点返回的数据中，本次审计关注五个类别中的两个：

type	触发条件	紧急程度
source	ExternalDataSource.status = Error —— 整个 source 连接中断	高
external_data_sync	架构处于 Failed 或 BillingLimitReached 状态（数据健康端点分别返回 status: "failed" 或 status: "billing_limit"）	中至高

每个条目都包含 id、name、type、status、error、failed_at、url 和 source_type。

端点返回的其他类别不在此技能的范围内：

• materialized_view → auditing-warehouse-view-health
• destination（批量导出）→ 由批量导出／数据管道产品负责
• transformation（HogFunction）→ 由 CDP／数据摄取侧负责

请注意，数据健康端点只报告_当前活动的故障_。对于 source/sync 健康状况，它不会标记：

• 用户暂停的架构（should_sync = false）
• 速度较慢或数据过时、但技术上仍处于 Completed 状态的架构
• **sync_type: "webhook" 架构上的 Webhook 问题。**批量同步的安全网可能成功运行，但 Webhook 推送通道可能已悄然失效（已注销、在远程端已禁用、签名验证失败）。 这些问题不会显示在 data-health-issues 中——请使用 webhook-info-retrieve 检查各个 source。

如果用户询问数据过时或未使用的项目，请超出此端点的范围进行检查——参见步骤 4。

工作流

步骤 1 — 一次性拉取

调用 data-warehouse-data-health-issues-retrieve，并保留 source 和 external_data_sync 条目。

如果没有 source/sync 问题，请告知用户其 sources 状况良好，然后停止。不要凭空捏造问题。

步骤 2 — 分组并确定优先级

1. **优先处理处于 Error 状态的 Sources。**source 故障会连带影响其下的每个架构——在 source 重新连接前，这些架构实际上都已失效。优先修复这些问题。
2. 接着处理同步架构，顺序如下：
   • status: "billing_limit" 条目（计费问题，非技术问题——标记并转给计费团队）
   • 使用频繁的表上的 Failed 状态（用户询问时／必要时通过 schemas-list 检查行数）
   • 使用较少的表上的 Failed 状态

步骤 3 — 展示审计结果

生成一份按优先级排序的报告。不要直接贴出原始 JSON——每个类别都使用便于阅读的表格：

## Data warehouse source health — 4 issues

### 🔴 Sources (1)
- Stripe — authentication failed (failed 2h ago). All 8 tables under it are currently dead.
  → `diagnosing-failed-warehouse-syncs` on this source

### 🟠 Sync schemas (3)
- postgres_prod.orders (Failed 6h ago) — column "updated_at" does not exist
- postgres_prod.invoices (Failed 6h ago) — column "updated_at" does not exist
- hubspot.contacts (BillingLimitReached) — team quota exceeded

Recommended order:
1. Stripe auth (everything under it is dead)
2. Schema-drift on postgres_prod.orders / invoices — looks like upstream renamed a column
3. Billing limit on hubspot

具体格式不那么重要，关键是：按优先级排序、分组清晰、可采取行动，并指出合适的后续技能。

第 4 步 — 深入检查活跃故障之外的问题（按需）

如果用户想了解的不只是“当前有哪些问题”——例如“我还应该检查什么？”——请交叉核对：

过时但状态为“Completed”的架构： 调用 external-data-schemas-list，查找 last_synced_at 相对于 sync_frequency 已过时的架构。 如果某个架构的同步频率为 1hour，但上次同步是在 3 天前，那么即使状态显示为 Completed，实际上也已失效。

没有同步活动的来源： 所有架构都满足 should_sync: false 或 status = Paused 的来源。这些来源曾经设置过，之后却被弃用—— 可以考虑通过 external-data-sources-destroy 清理。

Webhook 类型架构的 Webhook 故障： 遍历包含任何 sync_type: "webhook" 架构的来源（可通过 external-data-schemas-list 查看）。对于 每个来源，调用 external-data-sources-webhook-info-retrieve({source_id})：

• 当架构为 sync_type: "webhook" 时，exists: false → Webhook 从未注册，或已被删除。推送 通道已失效；只有批量回退机制仍在摄取数据。
• 存在 external_status.error → 远程服务报告了问题（权限已撤销，或其控制面板上的端点已 删除）。
• external_status.status 不为 "enabled" → 远程服务已禁用该端点（通常是由于多次投递 失败）。

请将这些问题与主要审计结果分开报告——它们与同步失败的类型不同，修复方式也不同（diagnosing-failed-warehouse-syncs 场景 I，或 setting-up-a-data-warehouse-source 第 5.5 步）。

只有在用户明确要求进行更全面的审计时，才执行这些额外检查——它们需要调用更多工具，并依赖启发式判断。

第 5 步 — 提供后续步骤

审计结束时，明确交接后续处理：

• “要我深入调查 Stripe 故障吗？” → 交接给 diagnosing-failed-warehouse-syncs
• “要我修复 orders 上的架构漂移吗？” → 交接给 tuning-incremental-sync-config
• “要我停用达到计费上限的架构吗？” → 通过 external-data-schemas-partial-update 一键处理

审计期间绝不要自主开始应用修复——审计的任务是报告和提出建议，而不是修复问题。 执行任何修复前，都应先明确征得确认。

重要说明

• 审计是只读的。 绝不要在审计流程中调用破坏性工具。应交接给诊断／调优 技能——它们会在执行操作前再次确认。
• 没有问题 = 健康。 不要为了充实空审计结果而假设存在问题。“未发现来源问题”就是一个很好的答复。
• 来源故障会产生连锁影响。 报告状态为 Error 的来源时，也要说明其下受影响的架构（或这些架构下次尝试同步时将受到的影响）。 用户需要了解影响范围。
• 计费限制不是技术问题。 请指出这些限制，但应引导用户讨论计费／配额，而不是采取恢复操作。
• data-health-issues 只会显示活跃故障。 对于数据陈旧或已弃用的来源，需要交叉核对列表端点。只有在用户明确要求深入审计时，才这样做。
• Webhook 健康状态与架构健康状态相互独立。 data-health 端点不了解 Webhook 状态。 当用户的请求提到“实时”、“Stripe webhook”或“为什么 Webhook 来源的数据会落后数小时”时，请直接调用 webhook-info-retrieve，而不要根据架构状态进行推断。
• 物化视图、目标位置和转换不在此范围内。 它们共用 data-health 端点，但属于其他审计／产品范畴——应转交处理，而不是在此诊断。