suggesting-path-cleaning-rules

建议路径清理规则

许多团队从未配置路径清理规则，因此 Web 分析细分结果会散落在数千个近乎相同的 URL 中。此功能会主动建议规则，适用于 Web 分析预计算队列：每周为每个团队采样真实路径，请大模型生成 {regex, alias} 规则，根据团队自己的路径验证规则，并存储起来以供审核。

此功能只提供建议，绝不会自动应用。应用规则会重写每张已清理图表中的历史数据，因此这应由人工决定（通过现有设置界面，或审核后使用下方的 --apply 标志）。如需手动编写或直接应用规则，请使用 managing-path-cleaning-rules 技能。

架构

• 核心：products/web_analytics/backend/path_cleaning_suggestions/service.py
  • sample_pathnames / count_distinct_pathnames — 通过 HogQL 获取按浏览量排序的前 $pathname。
  • call_llm_for_rules — 通过大模型网关发起单次调用（ get_llm_client(product="web_analytics", team_id=...)，模型为 WEB_ANALYTICS_PATH_CLEANING_SUGGESTIONS_MODEL，默认值为 claude-haiku-4-5）。
  • validate_and_annotate_rules — 使用 re2 编译每条正则表达式（这是 ClickHouse replaceRegexpAll 使用的引擎），并在采样路径上测试应用。无法编译或 无匹配项的规则会被丢弃；其余规则会获得紧凑的 order、match_count，以及保存在内存中的 前后对比 examples（由管理命令打印，绝不存储 — 健康问题 载荷只需 health_issue:read 权限即可读取，因此不得泄露真实路径）。这就是技能中的“保存前测试”步骤，此处已自动完成。
  • generate_suggestions_for_team — 通过门控逻辑（见下文）协调以上步骤；只生成规则，不存储。
  • apply_suggestions_to_team — 将规则合并到 path_cleaning_filters 中，绝不覆盖（按正则表达式去重，并延续 order）。
• 存储：path_cleaning_suggestions 健康问题（HealthIssue，严重程度为 info）— 无专用模型。每个团队有一个处于活动状态的问题（hash_keys=[]）；payload 包含 rules、model、sampled_path_count、distinct_path_count。应用规则（或手动配置规则）后，该问题会在下一次检查运行时解决；通过健康问题的 dismissed 标志来表示已忽略。
• 计划：PathCleaningSuggestionsCheck （products/web_analytics/backend/temporal/health_checks/path_cleaning_suggestions.py），基于共享健康检查框架的健康检查，每周运行一次（周一 06:23 UTC），采用较小的顺序批次，因为每个符合条件的团队都会产生一次大模型调用。已有活动建议的团队会重新输出建议，不会再次调用大模型。
• 队列：WEB_ANALYTICS_PATH_CLEANING_SUGGESTIONS_TEAM_IDS，默认使用预计算的入选团队列表 WEB_ANALYTICS_LAZY_PRECOMPUTE_TEAM_IDS。

门控逻辑（团队被跳过的原因）

generate_suggestions_for_team 会返回以下状态：

• skipped_inactive — 团队在 visited_within_days（默认 30 天）内未发送 $pageview；我们只为正在使用 Web 分析的团队提供建议。使用 --ignore-visit-gate 可跳过此门控。
• skipped_configured — 团队已经配置了路径清理规则（可通过 include_configured 覆盖）。
• skipped_low_cardinality — 不同路径的数量低于 min_distinct_paths（默认 50）；清理无法带来价值，因此不会消耗令牌。
• skipped_no_paths — 此时间窗口内没有页面浏览量。
• generated — 已生成规则（如果路径已经干净，规则列表可能为空；空的生成结果绝不会存储，因此不会遮蔽可执行的建议）。
• error — 采样或大模型调用失败；错误会按团队捕获，不会中止整个队列扫描。

用户如何查看和应用建议

• 设置横幅：PathCleaningSuggestionsBanner 在 /settings/project#path_cleaning 上将最新的 suggested 行显示为正则表达式 → 别名预览，并附带匹配数量；“Apply all”（仅限项目管理员）会合并规则，关闭按钮则会将其隐藏。由 pathCleaningSuggestionsLogic 驱动。
• 引导步骤：在 Web 分析引导流程中，OnboardingWebAnalyticsPathCleaningStep（stepKey 为 path_cleaning）会显示相同的横幅。
• API（products/web_analytics/backend/api/web_analytics_path_cleaning_suggestions.py）： POST /api/projects/:id/web_analytics_path_cleaning_suggestions/generate/ 会按需生成并存储一条新建议；GET .../{issue_id}/preview/ 会将规则应用于团队热门路径的最新样本，并返回应用前后的配对结果（读取范围，按需计算，从不存储——这是横幅“在你的路径上预览”弹窗的数据来源）；POST .../{issue_id}/apply/ 会合并规则并解决问题（仅限项目管理员——与团队 API 对 path_cleaning_filters 采用相同的限制）。 列出和隐藏建议通过通用健康问题 API 进行 （GET /api/projects/:id/health_issues/?kind=path_cleaning_suggestions&status=active&dismissed=false， PATCH .../health_issues/{id}/，请求体为 {"dismissed": true}）。
• 健康页面：此检查会与其他 Web 分析检查一起显示在 /web/health 上，并为用户和 Agent 提供修复指导。
• PostHog AI (Max)：生成和应用功能通过 products/web_analytics/mcp/tools.yaml 中的 MCP 工具开放（web-analytics-path-cleaning-suggestions-{generate,apply}），因此用户可以通过对话让 Max 建议并应用路径清理规则。应用操作属于 destructive（会改变历史图表中的数字），因此需要通过 MCP 确认关卡。

运行

# Default cohort, print suggestions, store health issues:
python manage.py suggest_path_cleaning_rules

# Specific teams, dry run (nothing stored):
python manage.py suggest_path_cleaning_rules --teams 2,19279 --no-store

# Generate AND apply for one reviewed team (merges, never overwrites):
python manage.py suggest_path_cleaning_rules --teams 2 --apply

实用参数：--days（回溯天数）、--limit（采样的热门路径数量上限）、--min-distinct-paths、--include-configured、--no-store、--apply。

与其他健康检查一样，也可以通过健康问题 refresh 端点或管理界面，按团队触发此健康检查。

审查建议

读取团队的活跃建议：

HealthIssue.objects.filter(team_id=team_id, kind="path_cleaning_suggestions", status="active").first()

payload["rules"] 中的每条规则都包含 regex、alias、order、reason 和 match_count——这些信息应展示给决定是否应用规则的用户。真实路径的应用前后示例仅由管理命令在生成时打印；它们会有意排除在存储的 payload 之外。

扩展

• 添加展示渠道（应用内通知、设置横幅、引导向导步骤）：读取团队活跃的 path_cleaning_suggestions 健康问题，并渲染其 payload["rules"]。应用操作应保持手动。
• 更改模型：必须在 services/llm-gateway/src/llm_gateway/products/config.py 中为 web_analytics 产品加入允许名单。
• Agentic 替代方案——signals-scout-web-analytics-path-cleaning scout——已在设计说明中勾勒；对于预计算队列，优先使用专用任务，因为它针对的正是该队列，并会提供结构化、经过验证的行，而不是 Signals 收件箱中的发现。