Piracy Handler

执行目录：~/.agents/skills/piracy-handler/

1) 主流程

A. 综合页后置（推荐）

npx tsx scripts/piracy_detect.ts --task-ids <TASK_ID[,TASK_ID2,...]> --data-source <sqlite|supabase>
npx tsx scripts/piracy_create_subtasks.ts --input <DETECT_JSON_PATH>
npx tsx scripts/upsert_webhook_plan.ts --source detect --input <DETECT_JSON_PATH>

B. 一条命令全流程（兼容入口）

npx tsx scripts/piracy_pipeline.ts --task-ids <TASK_ID_1,TASK_ID_2,...>

说明：piracy_pipeline.ts 保留为兼容壳，内部复用 detect runner + create/upsert。 默认会按 --task-app com.tencent.mm --task-date Today 扫描；--task-app/--task-date 均支持 CSV 多值（例如 --task-date Today,Yesterday）。 当 --task-date 提供多个值时，处理顺序按输入优先级依次进行（如 Today 优先于 Yesterday）。--task-ids 与 --task-app/--task-date 互斥。

C. webhook 触发与补偿

npx tsx scripts/webhook.ts --mode single --task-id <TASK_ID> --data-source <sqlite|supabase>
npx tsx scripts/webhook.ts --mode reconcile --date <YYYY-MM-DD> --data-source <sqlite|supabase>

2) 职责边界

• capture_results 读取：支持 sqlite|supabase
• 任务表读取/子任务创建：当前仍走飞书任务表（TASK_BITABLE_URL）
• 剧单元数据：当前仍走飞书剧目表（DRAMA_BITABLE_URL）
• webhook 计划读写：当前仍走飞书 webhook 表（WEBHOOK_BITABLE_URL）

3) 关键脚本

• scripts/piracy_detect.ts 作用：按 TaskID（或从飞书筛选）生成 detect.json；支持 sqlite/supabase 数据源；检测仅纳入 status=success 的综合页任务结果，ratio 采用 >= 阈值判定。
• scripts/piracy_create_subtasks.ts 作用：基于 detect.json 创建子任务（个人页/合集/锚点）。
• scripts/upsert_webhook_plan.ts 作用：webhook plan 唯一入口；支持 --source detect（从 detect.json 产出计划）与 --source plan（通用计划输入）。 去重键为 BizType + Date + GroupID，按目标键精确查询历史记录，避免大表场景下重复创建。
• scripts/webhook.ts 作用：webhook 统一入口；--mode single 用于单 group 触发，--mode reconcile 用于按日期批量补偿。
• scripts/dedupe_webhook_plans.ts 作用：一次性清理 webhook 计划表中的历史重复记录（默认执行删除，--dry-run 仅预览）。 运行约束：需确保 WEBHOOK_USE_VIEW 关闭，避免视图过滤导致清理不完整。

4) 公共模块（重构后）

• scripts/shared/lib.ts 通用工具函数、时间/解析、以及 task-manager/webhook-upsert 子进程桥接。
• scripts/shared/cli.ts 通用 CLI 参数解析辅助（limit、正整数等）。
• scripts/data/result_source.ts 统一 capture_results 读取接口（sqlite/supabase）。
• scripts/data/result_source_cli.ts 统一 --data-source/--sqlite-path/--table/--page-size/--timeout-ms 解析。
• scripts/detect/task_units.ts 统一任务分组逻辑：--task-ids 与 --task-app/--task-date 互斥；缺省时按飞书筛选条件分组。
• scripts/detect/core.ts detect 聚合/阈值/summary 核心逻辑。
• scripts/detect/runner.ts 统一 detect 执行与输出路径策略。
• scripts/webhook/lib.ts webhook 计划读取、状态聚合、dispatch/reconcile 核心逻辑。

目录结构速览：scripts/README.md

5) 环境变量

变量	用途
FEISHU_APP_ID / FEISHU_APP_SECRET	飞书应用凭证
TASK_BITABLE_URL	任务状态表
DRAMA_BITABLE_URL	剧单元信息表（detect 仍依赖）
WEBHOOK_BITABLE_URL	webhook 计划表
CRAWLER_SERVICE_BASE_URL	webhook 推送与豁免检查服务
SUPABASE_URL / SUPABASE_SERVICE_ROLE_KEY	--data-source supabase 时读取 capture_results
SUPABASE_RESULT_TABLE	Supabase 结果表名（默认 capture_results）
TRACKING_STORAGE_DB_PATH	sqlite 模式默认数据库路径

6) 参考文档

• 详细命令、参数与样例：references/commands.md
• webhook ready 语义：组内任务需全部为 success|error（failed 不视为 ready）。