copying-endpoints-across-projects

在项目间复制端点

此技能可将一个 PostHog 端点复制到同一组织中的另一个项目，或在同一项目中以新名称创建副本。端点是已保存的 HogQL 或洞察查询，并以可调用的 API 路由形式公开。

首先需要了解的一件事

服务端没有端点复制操作。功能标记有 feature-flags-copy-flags-create，实验有 experiment-copy-to-project；而端点两者都没有。复制端点意味着：

1. 使用 endpoint-get 读取完整的源配置。
2. 使用 endpoint-create 重新创建端点（在目标项目中，或在同一项目中使用新名称）。

endpoint-get 和 endpoint-create 仅对当前激活的 MCP 项目执行操作——两者都不接受项目 ID。因此，跨项目复制需要在读取（源项目）和写入（目标项目）之间切换当前项目。先读取源端点并记录配置，然后切换到目标项目并创建。如果在当前会话中无法切换项目，请告知用户，不要在错误的项目中创建副本。

何时使用此技能

• “将此端点复制到另一个项目”“复制此端点”“克隆端点”
• “将端点从暂存环境提升到生产环境”（将项目用作环境）
• “创建一个副本，这样我就可以迭代修改，而不影响线上版本”（在同一项目中使用新名称创建副本）
• 在其他工作区中复现端点的查询、变量和新鲜度配置

此技能不涵盖的内容

• 跨组织复制。 端点（及其查询）只能在你具有编辑权限的项目中重新创建；没有跨组织的复制方式。
• 编辑现有端点的版本——请参阅 managing-endpoint-versions。
• 从头设计新端点——请参阅 creating-an-endpoint（此技能假设源端点已存在且配置正确）。
• 批量复制项目中的所有端点。 请逐个复制；如果用户确实想复制全部端点，则循环执行 endpoints-get-all → 逐个复制，并告知用户你将这样做。

工作流

1. 确认源端点

你需要端点的名称和源项目。

• 如果用户提供了名称，请使用该名称。如果用户只提供了模糊描述，请在源项目中调用 endpoints-get-all，并根据名称或描述进行匹配。
• 如果用户没有说明端点所在的项目，请先询问——不要假设当前激活的 MCP 项目就是源项目。从错误的源项目复制是最常见的失误。
• 读取前，请确认当前激活的项目就是源项目（调用不带 ID 的 project-get 以查看当前激活的项目）。

2. 读取完整的源配置

使用源端点名称调用 endpoint-get。记录重新创建端点所需的所有信息：

• name
• query（完整的 HogQL/洞察查询定义——包括任何已声明的变量 / code_name）
• description
• data_freshness_seconds
• is_materialized（源状态——关于通常为何不应原样复制，请参阅步骤 5）
• tags

复制前，向用户简要说明查询返回的内容、包含的变量、新鲜度设置，以及源端点是否已物化。

3. 确定目标并检查名称是否冲突

**跨项目：**确认目标项目属于同一组织，并且用户在该项目中拥有编辑权限。副本会创建在调用 endpoint-create 时处于活动状态的项目中，因此请计划在步骤 2 和步骤 6 之间将活动项目切换到目标项目。

同一项目中的副本：新端点必须使用不同的名称——项目内的名称必须唯一，而且 URL 路径（/api/projects/{team_id}/endpoints/{name}/run）取决于该名称。与用户商定一个新名称。

无论哪种情况，都要在目标项目中运行 endpoints-get-all，检查预期名称是否已存在。如果存在，请停止并询问：在已有名称上创建端点并不是可以安全地静默执行的操作。请一开始就确定好名称——它会嵌入调用方 URL，之后也无法轻易重命名。

4. 确定目标项目中的名称

• 跨项目且用途相同：保留相同名称，以便调用方代码无需修改即可移植。
• 同一项目，或“复制后迭代”：选用明显由原名称派生的新名称（例如 weekly_active_users_v2、weekly_active_users_staging）。使用 snake_case，确保 URL 安全，以字母开头，最多 128 个字符。

5. 选择副本的物化设置（默认：关闭）

默认将副本的 is_materialized 设为 false，即使源端点已物化也一样。 原因与 copying-flags-across-projects 中的安全默认设置（保持禁用）类似：物化会按一定周期产生重新计算和存储成本，而新复制的端点在目标项目中尚无已验证的流量。先以非物化状态上线，确认它确实被调用后，再根据使用情况决定是否启用物化。

只有用户明确要求从第一天起就对副本进行物化时，才将 is_materialized 设为 true（例如，将高流量端点原样提升到生产环境）。请注意 creating-an-endpoint 中的限制：包含队列拆分或比较模式的查询，以及 Trends/Lifecycle/Retention 以外的洞察类型（例如 Funnels），无法物化——endpoint-create 会直接以非物化状态创建这些端点，无论如何设置。

除非用户希望目标项目使用不同的新鲜度，否则保持 data_freshness_seconds 不变（请记住，它也决定物化刷新周期）。

6. 创建副本

将目标项目设为活动项目后，调用 endpoint-create 并传入：

• name — 使用步骤 4 确定的名称
• query — 使用步骤 2 中原样记录的源查询（其中包含变量和 code_name）
• description — 使用源端点的描述（可选注明这是一个副本）
• data_freshness_seconds — 使用源端点的设置，除非用户已更改
• is_materialized — 使用步骤 5 确定的设置（默认为 false）
• tags — 如果用户需要，则沿用源端点的标签；删除在目标项目中没有意义的标签

7. 验证

使用具有代表性的 variables 载荷，对新端点调用 endpoint-run，并确认响应结构与源端点一致。对于跨项目提升，请检查查询引用的底层事件/属性在目标项目中是否确实存在——在测试环境中有效的查询，在分类体系不同的项目中可能返回空结果或报错。如果副本使用 HogQL，且调用方依赖 offset 分页，请注意：endpoint-run 中的 offset 仅支持 HogQL 端点（不支持洞察端点）。

8. 汇报

告知用户新端点的名称和所属项目、物化状态、新鲜度设置，以及验证运行的结果。如果你为创建副本切换了活动项目，请说明当前活动项目，以免用户下次调用时感到意外。

重要说明

• 查询是副本，不是链接。 与根据洞察创建端点类似，目标端点拥有自己的查询副本。之后对源端点的编辑不会同步到副本。
• 变量包含在 query 中。 HogQL code_name 变量声明和洞察拆解变量都位于查询定义中，因此原样复制 query 即可保留它们。请在验证运行中仔细检查副本的变量。
• 无法撤销。 endpoint-create 会创建一个新端点（如果名称已被占用，则会失败）。创建之前务必与用户确认目标名称和项目，尤其是目标为生产环境时。
• 访问权限。 用户需要拥有目标项目团队的编辑权限；否则 endpoint-create 会被拒绝。

可用工具

• endpoint-get — 读取完整的源端点配置（查询、变量、新鲜度、物化设置、标签）。支持 ?version=N。
• endpoint-create — 在当前项目中创建副本。字段：name、query、description、data_freshness_seconds、is_materialized、tags。
• endpoints-get-all — 列出当前项目中的端点；用于解析模糊的源名称，并检查目标中是否存在名称冲突。
• endpoint-run — 执行新端点，以验证副本的响应格式。
• project-get — 不带 ID 调用，以确认当前活动项目，然后再读取源端点或创建副本。