managing-endpoint-versions

管理端点版本

本技能是端点版本管理的实用指南，涵盖当前工作流，其中有一些容易踩坑的地方，值得明确说明。

何时使用本技能

• “如何回滚到 v3？”
• “我想在更改上线前先进行测试。”
• “如何更新特定版本的描述 / data_freshness_seconds？”
• “我可以在不影响 v5 的情况下禁用 v4 吗？”
• 用户不确定更改查询是否会创建新版本

版本管理模型 — 需要了解的内容

行为	实际情况
查询更改	会自动创建新版本。 保存对查询的任何编辑都会创建新版本，并递增当前版本号
设置更改（描述、data_freshness_seconds、物化方式）	不会创建新版本。会就地更新指定版本
“当前”版本	始终是版本号最高的版本——无法将其指针移回较早版本
不带 ?version=N 调用	运行最新版本。因此，未固定版本的调用方始终会访问最新版本
禁用整个端点	使用 endpoint-update 并设置 is_active: false（不指定 version），会一次性将所有版本下线
禁用单个版本	使用 endpoint-update，并设置 version + is_active: false，即可停用一个版本而不影响其他版本

该模型只能向前推进。目前没有“重新将 v3 设为默认版本”的操作。实际上，这意味着要“回滚”，必须创建一个新的最高版本并重新使用旧查询，或者将调用方固定到 ?version=N。

可用工具

工具	用途
endpoint-versions	列出端点的所有版本，最新版本在前
endpoint-get	获取完整配置；支持使用 ?version=N 获取特定版本
endpoint-update	核心工具——支持使用 version 请求体参数指定目标版本
endpoint-run	通过 ?version=N 直接执行某个版本（不会影响其他调用方访问的版本）

工作流

发布前预览草稿

该模型中没有“草稿”概念。编辑查询会立即提交为新版本。要安全地预览：

1. 先使用 execute-sql 工具（或 SQL 编辑器）测试新查询——不要在在线端点上测试
2. 准备就绪后，更新端点——这会自动创建新版本
3. 使用 endpoint-run 和 ?version=N 确认新版本返回的结果符合预期
4. 旧调用方仍会访问最新版本（也就是你的新版本）——没有“软启动”机制

如果用户需要真正的暂存端点，目前唯一的变通方法是创建一个名称带 _v2 或 _staging 后缀的同级端点。请如实说明——产品中没有暂存流程。

回滚到较早的版本

这种只能向前的模型意味着，“回滚”需要通过分叉实现：

1. 调用 endpoint-versions，找到查询正常的版本（例如 v3）
2. 使用 ?version=3 调用 endpoint-get，获取该版本的查询 JSON
3. 将 v3 的查询作为新查询调用 endpoint-update——这会创建一个新版本（例如 v6），其查询与 v3 相同
4. 所有未指定 ?version=N 的调用方现在都会访问 v6（其查询与 v3 相同）

旧版本（v5，即有问题的版本）仍然存在，也仍可通过 ?version=5 调用，直到被明确停用。

如果你能更改所有调用方，更快的缓解方法是让它们固定使用 ?version=3，直到真正的修复准备就绪。相比创建新版本，这种方法影响更小。

更新特定版本的设置

endpoint-update 接受请求正文中的 version 字段。设置该字段后，设置更新只会应用于该版本，不会创建新版本。适用于以下情况：

• 调整某个仍有调用方固定使用的旧版本的 data_freshness_seconds
• 修改历史版本的描述，使其更清晰
• 按版本更改物化状态（物化本来就是按版本设置的）

重要提示：同时传入 query 和 version 会被拒绝——查询更改始终会创建一个新的顶层版本，不会修改历史记录。version 参数只影响设置。

停用单个版本

要停用 v3，同时保留 v4 和 v5 的可调用状态：

endpoint-update {name: "...", version: 3, is_active: false}

这会仅将 v3 的 is_active 设为 false。固定使用 ?version=3 的调用方会开始收到错误；其他调用方不受影响。

要重新启用：使用相同的调用，并将 is_active 设为 true。

整个端点的 is_active 字段（不带 version）是单独的开关，会一次性停用所有版本。要精确停用单个版本，请使用限定版本的形式。

清理未使用的版本

随着时间推移，旧版本会不断累积。要找出哪些版本已不再使用，请调用 endpoint-versions 并查看各版本的 last_executed_at：该值为 null 或已过时很久的版本，近期都没有被调用。已物化但不再使用的版本成本较高——使用 endpoint-update、version 和 is_materialized: false 停用其物化，并将 is_active 设为 false，表明该版本已退役。

退役版本前请先与用户确认：last_executed_at 只统计个人 API 密钥发起的调用，而且只记录启用该跟踪功能后的运行记录（因此，即使某个版本已被使用，该值仍可能为 null）；此外，调用方可能固定使用 ?version=N。完整的审计流程请参阅 auditing-endpoints。

交互示例

User: "I shipped a broken query last night, v5. How do I roll back?"

Agent:
- endpoint-versions <name> → v5 (latest), v4, v3, v2, v1
- endpoint-get <name> ?version=4 → query JSON for v4
- "Rolling back means creating v6 with v4's query. v5 stays as a
   historical version but nobody hits it unless they explicitly
   pass ?version=5. Sound right?"
- User confirms
- endpoint-update <name> {query: <v4 query>} → creates v6
- endpoint-run <name> ?version=6 to confirm shape
- "Done. v6 is live with v4's query. Want me to also deactivate v5
   so it's clear it's defunct?"
- User: "Yes"
- endpoint-update <name> {version: 5, is_active: false}

重要说明

• 没有指针切换。“回滚”会创建一个新版本。版本号始终递增。如果用户对由此产生的历史记录噪声感到不适，这是合理的顾虑——请如实说明。
• **查询变更总会创建一个新版本。**在旁边更新设置不会。如果用户想修改 v5 描述中的拼写错误，但不想升到 v6，请使用 version 参数。
• **停用单个版本只会阻止该版本。**它不会改变默认运行的版本——默认始终是版本号最高的版本。
• **物化是按版本进行的。**每个版本都有自己的物化视图，名为 {endpoint_name}_v{version}。在某个版本上停用物化不会影响其他版本。
• **固定版本是安全网——推动调用方使用它。**固定到 ?version=N 的调用方不会受查询编辑影响；未固定版本的调用方始终会命中最新版本，可能会被新版本打个措手不及。鼓励使用方固定版本、验证新版本，然后再主动更新固定版本。
• CLI 也能管理版本。posthog-cli exp endpoints {pull,push,diff} 可让用户将端点定义以 YAML 形式保存在版本控制中，并在推送前审查变更——当查询变更需要审查时，这比直接编辑线上内容的工作流更整洁。
• **激活旧版本目前还不是产品功能。**如果用户反复提出这种需求——切换指针而不是分叉——请将其作为功能缺口反馈（并通过 agent-feedback 提醒团队）。不要假装 endpoint-update 能做到这一点。