finding-deleted-feature-flags

查找最近删除的功能标志

此技能会列出用户指定时间范围内在当前项目中软删除的功能标志，以及每个标志的删除者和删除时间。

何时使用此技能

• 用户询问“上周 / 过去 N 天删除了哪些标志？”
• 用户想审计近期的标志删除情况（谁、何时、删除了什么）
• 用户想查找特定标志何时被删除，或由谁删除
• 任何以“最近删除的功能标志”为主题的请求

不要将此技能用于清理仍处于活动状态的过期标志——此类任务应使用 cleaning-up-stale-feature-flags。此技能用于已被删除的标志。

让这件事变得复杂的陷阱

system.feature_flags 将 deleted 作为布尔值公开，但不会公开 deleted_at、updated_at 或 last_modified_at。无法通过单条 SQL 查询按删除时间筛选软删除的标志——尝试使用这些列会返回 Unable to resolve field。

实际删除时间戳位于每个标志的活动日志中，只能通过 posthog:feature-flags-activity-retrieve 获取（每个标志 ID 调用一次）。没有批量活动日志接口。

因此，工作流程分为两个阶段：先用 SQL 列出候选项，再并行查询活动日志，查找每个标志的删除事件。

工作流程

1. 时间范围含糊时先澄清

“上周”存在歧义——可能指从现在起往前推 7 天，也可能指上一个日历周（周一至周日）。如果用户没有明确说明，请先询问，或在最终报告中同时呈现这两种解释。

始终以 UTC 计算截止时间，并在心中另行记录用户对时间范围的本地理解。

2. 通过 SQL 列出软删除的标志

查询当前项目中 deleted = true 的 system.feature_flags，并按 created_at DESC 排序：

SELECT id, key, created_at
FROM system.feature_flags
WHERE team_id = <team_id> AND deleted = true
ORDER BY created_at DESC
LIMIT 100

按 created_at DESC 排序，是因为根据经验，删除时间通常集中在创建时间附近——大多数标志会在创建后的几天内被删除——因此优先检查最近创建的候选项，能更快找到近期删除的标志。但这只是启发式方法，并非保证：最近删除的旧标志不会排在列表顶部。报告时请明确说明这一限制。

team_id 默认指向当前项目，但为清楚起见，请显式包含它。

3. 并行分发活动日志查询

对每个候选 ID，调用 posthog:feature-flags-activity-retrieve，并设置 limit: 5, page: 1。在同一条消息中发出所有调用，使其并发运行——顺序调用会慢得多。

call feature-flags-activity-retrieve {"id": <flag_id>, "limit": 5, "page": 1}

建议的批量大小：

• “过去 7 天”→ 最多检查 20–25 个候选项
• “过去 30 天”→ 最多检查 50 个候选项
• “过去 90 天”→ 遍历全部约 100 个候选项

如果检查的候选项少于总数，请在报告中说明，并表示可以后续继续检查其余候选项。

4. 从每条响应中提取删除事件

在每条响应中，找到 activity == "deleted" 的条目。该条目的 created_at 是实际删除时间，user.email / user.first_name 可用于识别删除者。这些字段在所有删除路径中都可靠。

大多数标志恰好只有一个删除事件。如果某个标志曾多次被删除并恢复，请选取时间范围内最近的一条 activity: deleted 事件。

5. 恢复原始键并生成报告

软删除的功能标志如果仍在其他地方被引用（例如已停止的实验），其名称会改为 <original>:deleted:<flag_id>——基于 ID 的后缀可释放原始键以供重用。不要尝试从活动日志本身的字段中恢复原始键：detail.changes 仅在通过 UI/ORM 删除时记录重命名（通过 API/MCP/程序化方式删除时通常为空，或缺少 key 条目），而 detail.name 只会反映当前键的值，无论该键是否已被墓碑化。

请改用 scripts/strip_deleted_suffix.py 确定性地去除后缀。一次调用时，将步骤 2 中的整个候选列表以 JSON 格式传入，不要为每个标志分别调用：

echo '[{"id": 1001, "key": "example-banner:deleted:1001"}]' | python3 scripts/strip_deleted_suffix.py
# prints the same array back (pretty-printed), each object gaining an "original_key" field:
# "original_key": "example-banner"

筛选收集到的删除事件，只保留 created_at 落在请求时间范围内的事件。以表格形式呈现，并在“键”列中使用恢复后的原始键（而非原始墓碑化形式）：

| 标志 ID | 键 | 删除时间（UTC） | 删除者 |

在报告中说明你的方法（遍历了多少个候选项，以及软删除标志的总数），让用户知道检查了哪些内容、哪些内容没有检查。

注意事项

• 临界情况：如果删除时间距时间范围的截止点约 1 小时以内，应标记为临界情况，而不是直接略过。
• 不要将 created_at 当作删除时间的替代指标：标志可能创建于 2024 年，但直到上周才被删除。活动日志才是唯一可信来源。
• 键被重命名很常见：键为 foo:deleted:12345 的标志原本的键是 foo——请参阅步骤 5 了解如何恢复。
• 可以遍历所有候选项，但速度较慢：并行调用约 100 次活动日志查询是可行的。对于较短的时间范围，应将其作为后续选项，而不是默认做法。

示例对话

用户：“上周删除了哪些标志？”

1. 如有需要，先澄清；或说明两种解释：“以现在为结束时间的滚动 7 天（UTC），在当前项目中”

2. 运行 SQL 枚举，获取最多 100 个按 created_at DESC 排序的软删除候选项

3. 并行查询排名前约 25 个候选项的活动日志

4. 提取 activity: deleted 条目；筛选 created_at >= now - 7 days 的条目

5. 使用 scripts/strip_deleted_suffix.py 恢复原始键并生成报告。 以下值仅为示例，并非真实项目数据：

   Found 2 feature flags deleted in the last 7 days (rolling, ending 2026-08-14 09:30 UTC):
   
   | Flag ID | Key                     | Deleted at (UTC)     | Deleted by  |
   |---------|-------------------------|----------------------|-------------|
   | 1001    | example-banner          | 2026-08-13 15:12     | Jane D.     |
   | 1002    | example-checkout-test   | 2026-08-09 21:48     | John S.     |
   
   Methodology: walked the activity log for the 25 most-recently-created soft-deleted flags.
   The step 2 query hit its 100-row cap, so the project may have more soft-deleted flags than that.
   The other 75 returned candidates were created before late June 2026 and were not checked.
   Want me to walk the rest?
   

相关工具

• posthog:execute-sql：在步骤 2 中用于从 system.feature_flags 枚举软删除候选项
• posthog:feature-flags-activity-retrieve：在步骤 3 中用于查找每个候选项实际发生删除的事件
• posthog:feature-flag-get-definition：如果用户随后想查看已删除标志的外观，此工具会很有用

脚本

• scripts/strip_deleted_suffix.py：恢复原始标志键——请参阅步骤 5。