copying-flags-across-projects

在项目间复制功能标记

此技能将指导你如何在同一个 PostHog 组织内，将功能标记从源项目复制到一个或多个目标项目。

何时使用此技能

• 用户要求“将标记复制到另一个项目”“复制此标记”或“在项目间同步标记”
• 用户想将标记从暂存项目发布到生产项目（或反向操作）
• 用户想在其他工作区中复制标记配置，并保留群组依赖关系
• 用户通过将项目用作环境，来弥补缺少真正环境的问题

此技能不涵盖的内容

• 不支持跨组织复制。此端点要求源项目和目标项目属于同一个组织。
• 批量复制项目中的所有标记。此工具每次只复制一个标记。要批量复制，请遍历标记键；每次调用彼此独立。
• 清理旧的或过时的标记——请改用 cleaning-up-stale-feature-flags 技能。

工作流

1. 确定源标记

你需要标记的键和源项目的 ID。

• 如果用户提供了标记键和项目 ID，请直接使用。
• 如果用户提供了标记名称（例如“新的定价标记”），请在源项目中调用 posthog:feature-flag-get-all，查找匹配的标记并读取其 key。
• 如果用户只提供了标记，却没有提供项目，请询问该标记所在的项目。不要假定是当前 MCP 项目——从错误的源项目复制是常见的失误。

2. 确定目标项目 ID

目标项目必须与源项目属于同一个组织。调用 posthog:projects-get 列出可用项目，并在执行复制前确认其组织归属。

对于多目标复制，单次调用最多可接受 50 个目标项目 ID。每个目标的成功和失败都会单独报告，因此部分失败不会阻止其余操作。

3. 预览源标记及其依赖项

对源标记调用 posthog:feature-flag-get-definition。然后务必调用 posthog:feature-flags-copy-dependencies-check，并传入 feature_flag_key、from_project 和 target_project_ids，不要尝试先检测依赖项——该调用不会复制任何内容；如果标记没有依赖项，则会返回空结果且没有警告，因此每次复制时都执行此调用成本很低，也绝不会漏掉真实依赖项。

can_copy_dependencies 为 false 并不总是意味着复制会受阻。如果没有可复制的内容，它也会是 false。只有当 warnings 非空时，才报告问题。

复制前，向用户简要说明以下内容：

• 源项目中的标记键、名称和启用状态
• 筛选条件组（发布比例、属性筛选条件、变体拆分）
• filters.groups[].properties[] 中的任何群组引用——这些引用会在服务器端重新映射，但用户应了解目标项目中是否已有匹配的群组
• 标记是否包含加密负载（has_encrypted_payloads），或是否为远程配置（is_remote_configuration）
• 是否存在计划变更（用户可在步骤 4 中选择复制这些变更）
• 依赖项检查的 copied_dependency_keys（复制时将在目标中创建的依赖项）、reused_dependency_keys（目标中已满足的依赖项）以及任何 warnings

4. 确认复制选项

一次确认涵盖全部三个选项。默认采用最安全的组合，只有用户明确希望采用其他行为时才询问是否覆盖默认设置：

• disable_copied_flag: true — 复制到目标项目的标记处于禁用状态。默认建议采用此设置；在新项目中启用标记应当是经过审慎考虑并确认的操作。
• copy_schedule: false — 不复制计划变更。默认建议采用此设置；计划通常因项目而异。
• copy_dependencies: false — 不复制依赖项标记。只有用户批准复制步骤 3 检查报告中的键时，才将其设为 true。

如果用户说“原样推送”或“在生产环境中启用”，请将 disable_copied_flag 改为 false。如果用户说“包含发布计划”或“连同计划发布一起”，请将 copy_schedule 改为 true。

5. 执行复制

调用 posthog:feature-flags-copy-flags-create，并提供：

• feature_flag_key：源标记的键
• from_project：源项目 ID
• target_project_ids：已解析的目标项目 ID 列表
• disable_copied_flag：步骤 4 中的设置（默认 true）
• copy_schedule：步骤 4 中的设置（默认 false）
• copy_dependencies：步骤 4 中的设置（默认 false）。即使用户已批准复制依赖项，省略此参数也会静默跳过依赖项复制。

6. 报告各目标的结果

响应包含一个 success 数组（每个复制的标记对应一项）和一个 failed 数组（按目标列出错误）。请同时说明两者：

• 对于每项成功结果：提供目标项目 ID、新标记的 ID，以及该标记在目标项目中的 active 状态。
• 对于每项失败结果：提供目标项目 ID 和错误消息。常见原因包括缺少目标团队的编辑权限，或目标项目中已存在不可覆盖的资源标记。

如果有任何目标失败，请询问用户是重试失败的目标、跳过它们，还是先解决根本问题（例如授予访问权限后重试）。

重要说明

• 队列会自动重新映射。 如果源标记引用了队列，端点会在每个目标项目中创建或复用等效队列，并重写标记的筛选条件，使其指向目标项目中的队列 ID。你无需处理此事，但要告知用户正在进行此操作，以便他们了解目标项目中可能出现的新队列。
• 加密载荷会保留。 复制带有加密载荷的远程配置标记时，会保留其加密状态；载荷会使用目标项目的密钥重新加密。
• 复制计划变更时也会重新映射队列。 如果 copy_schedule: true，任何计划中的队列引用都会像实时筛选条件一样重新映射。
• 身份验证要求。 用户的 API 密钥必须包含明确的 feature_flag:write（或 feature_flag:*）作用域。仅包含 * 的密钥会被拒绝——此端点受 INTERNAL 视图集限制，* 授权无法满足要求。团队范围的密钥也无法访问此端点；必须使用组织范围或无范围限制的密钥。
• 源项目的编辑权限。 用户必须至少拥有源标记所属团队的编辑级别权限。端点会在复制前通过 PostHog 的访问控制进行验证。
• 目标项目的访问权限。 用户无法查看的目标会从结果中静默移除；用户可以查看但没有编辑权限的目标，则会在 failed 数组中显示权限错误。
• 无法撤销。 复制会在目标项目中创建新标记（或覆盖具有相同键的现有标记）。发起复制前务必先向用户确认，尤其是在目标为生产项目时。

示例交互

用户： 将项目 12345 中的 new-checkout 标记复制到项目 67890。

Agent： 正在查看项目 12345 中的源标记。

(调用 posthog:feature-flag-get-definition)

项目 12345 中的 new-checkout 标记目前是布尔类型，按 25% 的比例逐步发布，没有队列筛选条件或计划变更。我会将其作为已禁用标记复制到项目 67890，且不复制计划变更——这是更安全的默认设置。确认吗？

用户： 确认，但请在目标项目中启用它。

Agent： 明白——正在目标项目中启用。

(调用 posthog:feature-flags-copy-flags-create，并设置 disable_copied_flag: false、copy_schedule: false)

完成。在项目 67890 中创建了标记 ID 99887（active: true）。没有失败的目标项目。

可用工具

• posthog:feature-flags-copy-flags-create — 执行复制。必填字段：feature_flag_key、from_project、target_project_ids。可选字段：disable_copied_flag、copy_schedule、copy_dependencies。
• posthog:feature-flags-copy-dependencies-check — 预览复制标记会对其传递标记依赖项产生什么影响。不会复制任何内容。每次复制前都要调用；如果标记没有依赖项，则返回空结果。
• posthog:feature-flag-get-all — 当用户只提供了易读名称时，按键名或名称在指定项目中查找标记。
• posthog:feature-flag-get-definition — 获取完整的源标记（筛选条件、变体、队列引用、加密标记），以便在复制前进行预览。
• posthog:projects-get — 列出当前组织中的项目，用于解析和验证目标项目 ID。