用途：该技能引导在 PostHog 中创建配置正确的端点。端点把已保存的 HogQL 或 insight 查询暴露为可调用的 HTTP 路由，创建时的配置选择决定成本、延迟与调用方接入方式。物化细节见 references/materializing.md，当物化决策不明确时查阅。
适用触发：为某查询创建端点、把洞察暴露为 API、把 HogQL 变成可调用端点，或新调用方（移动端、客户仪表盘、下游管道）需要 PostHog 数据时。
按序决策：
- 是否该做成端点。合适：外部系统调用、查询稳定非探索性、形状可复用。不合适：内部仪表盘直接用 insight；一次性分析用 execute-sql 或 SQL 编辑器。重聚合不是避免端点的理由，高频重聚合恰是开启物化的最佳场景。
- 命名。URL 安全字符，字母开头，最多 128 字符，项目内唯一。倾向描述性、snake_case、不带版本、不带 endpoint 字样。名称出现在 /api/projects/{team_id}/endpoints/{name}/run，事后改名困难。
- 查询类型。HogQL（HogQLQuery）为用户手写 SQL，变量用 {variables.x} 按 code_name 匹配，需精确列形状时推荐。Insight 包装已有洞察，TrendsQuery、LifecycleQuery、RetentionQuery 支持物化，Trends 与 Retention 的 breakdown 可作变量（Lifecycle 无 breakdown）。FunnelsQuery 等只能内联运行、不能物化、不暴露 breakdown 变量，需要时改写为 HogQL。
- 变量。应随调用方变化者设为变量，其余硬编码。HogQL 变量在查询 payload 中以 code_name、type、default 声明，调用传 {"variables":{"<code_name>":value}}。常见：时间窗口、身份过滤、分页。insight 端点用 breakdown 属性作变量；date_from/date_to 仅在非物化 insight 端点可作变量。避免改变结果形状的变量，禁止暴露 where_clause 之类可注入任意 SQL 的变量。
- data_freshness_seconds 兼作缓存 TTL 与物化刷新频率，取值为固定枚举：900、1800、3600、21600、43200、86400（默认）、604800，无低于 15 分钟选项。逐档给出选择建议，除非用户明确需要更新鲜数据，否则偏高。
- 首日物化。高频、延迟敏感、可容忍等于刷新间隔的陈旧度时建议物化；低频、探索性、新鲜度关键则跳过。不确定先不物化，稳定后再加 is_materialized: true。
工作流：确认用例→商定名称→确认查询与列形状→确定变量并把声明语法展示给用户→依据新鲜度选 data_freshness_seconds→做物化判断→调用 endpoint-create→用样本 payload 调 endpoint-run 验证响应形状→若用户要接客户端代码则转交 consuming-endpoints-from-client-code。
重要提示：名称写进 URL，改需迁移调用方；默认用 HogQL；无默认值的变量在调用时会失败，创建时务必设默认值；物化端点要求传入全部变量，缺参会被拒绝（安全考虑，防止返回未过滤数据），部分变量是已知限制；不满足条件的查询不要开物化，先用 endpoints-materialization-preview 确认资格；查询变更会自动生成新版本，旧版本经 ?version=N 访问，data_freshness_seconds 与物化按版本设置；建议调用方固定版本号而非 latest；遇到摩擦可用 agent-feedback 反馈。