dev-dominick/catchdrift

# CatchDrift CatchDrift 是一个用于解决归因失效问题的付费媒体控制回路：检测漂移、将其与运营变更关联、量化风险敞口、指导调查、管理行动，并在活跃支出产生不可用的营销活动数据之前验证恢复情况。 ## 30 秒概述 - 线上 URL: https://catchdrift.media/ - 代码库: https://github.com/dev-dominick/catchdrift - 演示路径: 首页 -> 运行 AI 辅助回放 -> 检测到归因失效 -> 量化风险敞口 -> 提供有据可查的响应路径 -> 在事件页面验证恢复情况 ## 昂贵的运营问题 在落地页或跟踪机制发生变更后，付费营销活动可能会在归因质量悄然下降的同时继续消耗预算。团队通常会在仪表盘中稍后才发现性能异常症状，但往往不够及时，无法将以下要素联系起来： - 支出持续活跃时面临风险的金额； - 可能的运营变更； - 应该优先检查的内容； - 恢复是否真正完成。 CatchDrift 专注于这一特定的失效模式，因为尽早发现一次高消耗事件即可证明该系统的价值。预期买家的核心结论很直接：不要等到明天才发现今天的营销活动数据在预算持续消耗时已经不可用了。 ## AI 辅助的价值，确定性的控制 CatchDrift 以 AI 辅助调查为主导，而非 AI 控制的运营操作。确定性规则会判定是否存在事件、显示何种风险敞口范围、哪个部署是最强有力的证据，以及恢复是否已得到验证。AI 的作用仅限于根据持久化的结构化证据按需生成调查简报。 如果模型配置不可用或输出验证失败，CatchDrift 将回退到确定性指导机制。 ## 演示结果与财务风险敞口 来自确定性回放配置文件的示例： - 活跃风险支出：$900/小时 - 预估风险敞口费率：$230-$310/小时 - 自动检测窗口：3 个性能下降区间，从部署到检测约 15 分钟 - 用于对比的预期手动发现延迟：90 分钟 - 自动检测前累积的风险敞口（费率 x 15 分钟）：$57-$77 - 90 分钟手动发现的反事实情况（费率 x 90 分钟）：$344-$465 - 在延迟的手动发现之前浮现的额外风险敞口（费率 x 75 分钟）：$287-$387 - 潜在的全天风险敞口预测（费率 x 24 小时）：$5,509-$7,432 演示估算基于受控的回放场景。反事实和预测数值是预估的风险敞口信号，并非已确认节省的金额。 ## 工作流运作方式 CatchDrift 会持续评估营销活动遥测数据和部署事件，并在所有必要条件持续满足时开启一个确定性事件： - 支出保持实质性活跃； - 点击到会话的损失超过阈值； - 归因下降超过阈值； - 性能下降持续达到必要的区间数； - 必要的数据源是新鲜的（对陈旧数据源的抑制可防止做出不安全的决策）。 一旦触发，CatchDrift 将记录不可变的事件证据： - 基线指标； - 阈值要求； - 性能下降窗口信号； - 确定性部署关联得分； - 确定性风险敞口范围。 随后，它会跟踪从“已检测”到“已恢复/已解决”的生命周期状态转换，并使用明确的指标标准来验证恢复情况。 ## 为什么这对 It's Today Media 至关重要 It's Today Media 在多个渠道开展高频媒体采买，在这些渠道中，落地页、跟踪完整性和归因质量直接影响支出效率。CatchDrift 填补了运营跟踪失效与采买人员通过延迟报告发现该问题之间的空档。 首次生产环境部署将会根据 It's Today Media 的营销活动体量、报告延迟、部署节奏以及可接受的误报率来校准阈值。 ## 运行在线演示 1. 打开 `/`。 2. 点击 `Run the AI-assisted tracking failure replay`。 3. 观察恢复前的活跃事件状态。 4. 从事件页面生成 AI 调查简报或确定性回退方案。 5. 保持事件详情页面开启，并观察状态更新为“已恢复”。 CLI 等效操作： - `pnpm demo:reset` - `pnpm demo:replay` ## 下一步开发计划 1. 进行运营人员发现访谈，以校准检测阈值和警报疲劳容忍度。 2. 实现从真实广告、归因和部署系统的 Connector 摄取。 3. 通过 Slack/工单系统进行渠道分发，并带有确认回执闭环。 4. 为转化路径完整性变体添加额外的确定性规则。 5. 针对检测时间、确认时间和预估浮现的风险敞口添加结果监控埋点。 ## 真实环境与受控回放对比 真实环境： - 摄取 API 契约； - 持久化、幂等性、修订处理； - worker 队列 + 重试； - 确定性规则与风险敞口逻辑； - 确定性关联与恢复跟踪； - 异步回放运行状态契约 (202/200/409/429)； - 跨事件状态的 UI 工作流。 受控回放： - 用于回放的营销活动遥测源数值； - 用于回放的部署事件源输入； - 外部广告平台 connectors。 ## 架构 ``` flowchart LR A[Ingestion APIs] --> B[(PostgreSQL)] B --> C[Durable Jobs] C --> D[Worker Evaluator] D --> E[Rule Evaluations] D --> F[Incidents + Evidence] F --> G[Incident UI] F --> H[Constrained AI Investigation Brief] I[Demo Replay Orchestrator] --> B I --> C I --> J[Demo Run State API] ``` 运行时详情： - 正常的摄取使用持久化的队列任务和 worker。 - 评审演示回放仅内联处理其隔离的演示任务，而不依赖单独调度的 worker。 - 两种路径都使用相同的持久化评估和事件逻辑。 - 技术部署说明：Railway 在自定义域名背后提供生产源站服务。 ## 安全边界 CatchDrift 确保所有财务和事件决策均为确定性决策。 AI 是可选的，且仅限于根据持久化的结构化证据生成调查简报。AI 可以总结不同的解释并优先安排检查步骤，但 AI 不能： - 创建事件； - 更改严重性或置信度； - 修改风险敞口值； - 断言因果关系； - 控制营销活动支出。 如果模型配置不可用或输出无效，CatchDrift 将回退到确定性指导机制。 ## GitHub 代码库元数据 推荐的代码库设置： - 描述: 针对活跃广告营销活动的 AI 辅助跟踪失效检测，提供确定性事件证据、风险敞口预估和恢复验证。 - 网站: https://catchdrift.media/ - 主题: advertising, attribution, campaign-monitoring, ai, nextjs, postgresql, incident-response, media-buying, demo ## 本地设置 1. 安装依赖: `pnpm install` 2. 启动 PostgreSQL: `docker compose up -d` 3. 复制 env: `cp .env.example .env` 4. 运行迁移: `pnpm db:migrate` 5. 启动 worker + web: - `pnpm start:worker` - `pnpm dev` ## 环境变量 必需： - `DATABASE_URL` - `INGESTION_TOKEN` - `WORKER_ID` - `NODE_ENV` - `APP_BASE_URL` 可选（AI 简报）： - `OPENAI_API_KEY` - `OPENAI_MODEL` (默认: `gpt-4.1-mini`) ## 验证 - 类型检查: `pnpm typecheck` - Lint: `pnpm lint` - 单元测试: `pnpm test:unit` - 集成测试: `pnpm test:integration` - 单元 + 集成测试组合: `pnpm test` - E2E: `pnpm test:e2e` - 完整自动化套件: `pnpm test:all` - 评审验证门槛: `pnpm verify` `pnpm verify` 运行：类型检查、lint、单元测试、集成测试、生产构建以及 E2E。 ## 技术说明 - 规则标识: `tracking_integrity_failure@1` - 必需的陈旧数据源抑制机制是基于当前时间和数据源延迟预期推导出来的，而非信任持久化的 `freshness_state`。 - 事件关联是最强证据关联，而非根本原因证明。 - 风险敞口是确定性的，并标记为预估值。 - 回放和重置 endpoint 强制执行争用和限流语义： - `202` 回放已接受； - `200` 状态轮询响应； - `409` 争用冲突； - `429` 冷却/速率限制； - 安全的 `5xx` 运营故障（带有公开参考 ID）。

标签：人工智能, 广告技术, 归因监测, 故障检测, 测试用例, 用户模式Hook绕过, 自动化攻击, 营销数据分析, 请求拦截, 风险控制