用途：针对某个具体 PostHog 端点做深度诊断，产出可执行的优化建议。它是 auditing-endpoints（负责发现候选端点）的深入版。适用场景包括端点变慢或超时、触及成本上限、是否该物化某端点，以及从审计中浮现的失败物化或高成本调用方。若问题是项目级清理，应先用 auditing-endpoints。
主要能力与工具：endpoint-get 获取完整配置（查询、当前版本、data_freshness_seconds、物化状态）；endpoint-versions 查看版本历史与当前版本；endpoint-materialization-status 查看物化资格、状态、上次运行与错误；endpoints-materialization-preview 预览物化查询及不合格原因；endpoints-last-execution-times 做端点级活跃度检查；execute-sql 查询 query_log 获取调用频率与单次耗时/字节。另有受 endpoints-ai-materialization-fix 特性门控的 endpoint-materialization-suggestion 与 endpoint-materialization-conditions，特性关闭时不出现在工具目录中，第 3 步不依赖它们。
决策顺序（先命中者即最便宜的修复）：1）是否已缓存：看 data_freshness_seconds，它同时决定缓存 TTL 与物化刷新频率；TTL 为默认 24h 且数据无需更新则无需改动；处于 900s 下限且调用频繁则提高 TTL，这通常是最便宜的第一步（枚举值 900、1800、3600、21600、43200、86400、604800，无低于 15 分钟的值）；若因数据必须实时而处于下限，则跳过缓存。变量形态也影响缓存效果。2）是否应物化：调用 endpoints-materialization-preview，合格且转换干净是强候选；不合格会给出原因；合格但转换复杂则收益可能有限。启用后调用方必须传全部物化变量，否则请求被拒。3）查询是否需重写：按拒绝原因处理，常见情况包括 cohort 分解/compare 模式被拒、JOIN 与变量组合被拒（应把变量过滤下推到子查询/CTE）、缺少变量或无界扫描、HogQL 使用 * 或非确定性函数等；原因列表不穷尽，应以原始拒绝原因为准，部分原因无等价重写（如 OR {variables.x} = 'all' 可选变量写法）。可查 endpoint-versions 判断是否近期改动导致回退。若 AI 重写工具可用，可让 PostHog 起草重写并校验，ok 仅表示通过检查与变量、输出列一致性，语义等价是模型声明而非证明，应用前需用相同变量值对比原查询与重写结果，再用 endpoint-update 应用并确认。4）慢版本是否真被调用：默认只运行最新版本，旧版本仅在调用方固定 ?version=N 时运行；可查各版本 last_executed_at。
工作流：按名称识别端点（URL 形如 /api/projects/{team_id}/endpoints/{name}/run）；依次调用 endpoint-get、endpoint-materialization-status、endpoint-versions；有具体症状则走决策树，否则列出四个检查点询问；最后给出具体建议（提高 TTL、物化、重写或回滚）并在应用前确认。
限制与注意：缓存几乎总是首选，免费、可即时回滚且不改变数据语义；物化有存储、刷新计算和变量必传等隐藏成本；未经用户同意不要重写查询，因为会产生新版本并可能破坏调用方；三种使用信号仅统计个人 API Key 调用，单版本活跃度可能稀疏，判定版本废弃前需与用户确认；正确修复取决于 SLA 而非查询本身，推荐物化前必须询问可接受的陈旧度；若诊断遇到产品限制，可通过 agent-feedback 反馈。