dp-worker 0.1.28 → 0.1.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -192,6 +192,17 @@ export const BirdTweet = z.object({
192
192
  /** 引用推(带自己评论的转发)—— 这个算自己的内容,指标也是自己的。 */
193
193
  is_quote: z.boolean().default(false),
194
194
  media_count: z.number().default(0),
195
+ /**
196
+ * 媒体直链(最多 4 张;视频取封面)。
197
+ *
198
+ * 「配图占比 23%」是形态结论,回答不了「它的图长什么样」—— 而那是配图这件事上
199
+ * 唯一可模仿的部分。数据本来就在 worker 解析 media_kind 时走的那个数组里,
200
+ * 只是以前没取出来,所以这是零额外请求。
201
+ *
202
+ * 老版本 worker 不带这个字段 —— default([]) 保证前后兼容,空数组表示
203
+ * 「这个 worker 还不会传」而不是「这条推没有图」(后者看 media_count)。
204
+ */
205
+ media_urls: z.array(z.string()).default([]),
195
206
  /**
196
207
  * 以下三个字段都是为了回答「这个号**为什么**做得好」。
197
208
  *
@@ -312,6 +323,14 @@ export const BirdJobCreate = z.object({
312
323
  /** 账号矩阵审计:选一批 worker,每号一次抓取。 */
313
324
  export const BirdAuditRequest = z.object({
314
325
  worker_ids: z.array(z.string().min(1)).min(1).max(200),
326
+ /**
327
+ * 给这一次起个名字。
328
+ *
329
+ * 「3 个号 · 统计 07-31 ~ 08-06」说的是**跑了什么**,而人回头找的是**为什么跑** ——
330
+ * "活动上线前基线"、"KOL 那批"、"周报"。让发起的人自己写一句,比我们从参数拼一个
331
+ * 标题准得多。不写就退回按号数和区间拼。
332
+ */
333
+ label: z.string().max(60).optional(),
315
334
  /** 统计窗口(天)。默认 7 —— 「一周发帖数/一周活动量」。给了 since/until 时忽略。 */
316
335
  window_days: z.number().int().positive().max(90).default(7),
317
336
  /** 固定区间(YYYY-MM-DD,含首尾)。人工汇报常常要的是「7 月这一整月」。 */
@@ -376,7 +395,14 @@ export const BirdSettingsPatch = z.object({
376
395
  enable_metrics_backfill: z.boolean().optional(),
377
396
  enable_follow_targets: z.boolean().optional(),
378
397
  health_alert_worker_id: z.string().nullable().optional(),
379
- health_interval_min: z.number().int().min(15).max(1440).optional(),
398
+ /** 0 = 关掉自检。除此之外至少 15 分钟 —— 探得比这还勤只是白花额度。 */
399
+ health_interval_min: z
400
+ .number()
401
+ .int()
402
+ .min(0)
403
+ .max(1440)
404
+ .refine((v) => v === 0 || v >= 15, { message: "要么填 0(关闭),要么至少 15 分钟" })
405
+ .optional(),
380
406
  signal_window_days: z.number().int().min(1).max(30).optional(),
381
407
  retention_days: z.number().int().min(1).max(365).optional(),
382
408
  });
@@ -505,6 +531,29 @@ export const BirdAuditReport = z.object({
505
531
  }),
506
532
  /** 还没跑完的号数 —— 前端据此显示进度而不是假装已完成。 */
507
533
  pending: z.number(),
534
+ /**
535
+ * 这次**没抓到**的号。
536
+ *
537
+ * ── 为什么这一段必须存在 ──────────────────────────────────────────────────
538
+ * 报告原来只有 `rows`,一个没抓到的号有两种下场,两种都在说谎:
539
+ * · 它有更早的快照 → 顶着「下面是这一次跑的结果」的横幅显示几天前的数字;
540
+ * · 它从来没有过快照 → 从表里**整个消失**,而「账号数」也跟着少,
541
+ * 于是一次只成功了 13/78 的审计看起来像一次成功的 13 个号审计。
542
+ *
543
+ * 现网 2026-08-10 两种都发生了:13 个当天的 + 3 个 08-06 的 = 界面上的 16。
544
+ * 那 3 行的数字是四天前的。
545
+ *
546
+ * 一个我们没抓到的号,不该长得像抓到了。
547
+ */
548
+ missed: z.array(z.object({
549
+ worker_id: z.string(),
550
+ worker_name: z.string().nullable(),
551
+ handle: z.string().nullable(),
552
+ /** 人话原因,从作业的 error_code 翻译。作业也没有就是 null。 */
553
+ reason: z.string().nullable(),
554
+ /** 有没有更早的快照可看 —— 有的话前端可以给一个「看历史」的入口。 */
555
+ last_seen_on: z.string().nullable(),
556
+ })),
508
557
  });
509
558
  /**
510
559
  * Bird 的健康状态。
@@ -574,6 +623,29 @@ export const BirdAnalyzedPost = BirdAuditPost.extend({
574
623
  media_kind: z.enum(["photo", "video", "animated_gif"]).nullable().default(null),
575
624
  has_link: z.boolean().default(false),
576
625
  reply_to: z.string().nullable().default(null),
626
+ /**
627
+ * ── 爆款归因 ──────────────────────────────────────────────────────────────
628
+ * 「这条是同形态中位的 8.8 倍」说明它超常,说不了**为什么**超常。如果原因是
629
+ * 某个百万粉账号引用了它,那这条的写法根本不是它火的理由 —— 而榜单上
630
+ * 「内容赢来的」和「被大号推起来的」长得一模一样。
631
+ *
632
+ * quote_checked_at 是判据,不是 quotes_seen:**没查过**和**查过、确认没人转**
633
+ * 是完全不同的两件事,而两者的 quotes_seen 都可能是 0/null。
634
+ */
635
+ quote_checked_at: z.string().nullable().default(null),
636
+ quotes_seen: z.number().nullable().default(null),
637
+ /** 引用它的人里粉丝最多的那个。判断"是不是外部放大"只需要知道最大的推手有多大。 */
638
+ top_amplifier: z.string().nullable().default(null),
639
+ top_amplifier_followers: z.number().nullable().default(null),
640
+ /**
641
+ * 评论区查过没有。
642
+ *
643
+ * 跟归因同一条道理:**没查过**和**查过、一条评论都没有**是完全不同的两件事,
644
+ * 而两者的评论条数都是 0。
645
+ */
646
+ replies_fetched_at: z.string().nullable().default(null),
647
+ /** 媒体直链(最多 4 张;视频取封面)。空数组 = 没图**或**这个 worker 版本还不传。 */
648
+ media_urls: z.array(z.string()).default([]),
577
649
  });
578
650
  /**
579
651
  * 一个账号的打法画像。
@@ -609,8 +681,34 @@ export const BirdAccountAnalysis = z.object({
609
681
  /** 24 格发帖分布(按配置时区折算)。 */
610
682
  by_hour: z.array(z.number()),
611
683
  by_weekday: z.array(z.number()),
684
+ /**
685
+ * 168 格的发帖分布(周几 × 小时,索引 = weekday*24 + hour,周日 = 0)。
686
+ *
687
+ * by_hour 和 by_weekday 各自都丢掉了另一维:「19 点发得多」看不出是工作日还是周末。
688
+ * 而「该几点发」的真实答案往往是「工作日晚上」—— 那是个二维结论。
689
+ */
690
+ by_slot: z.array(z.number()).default([]),
691
+ /**
692
+ * 同样 168 格,但装的是那一格的**中位互动**。
693
+ *
694
+ * by_slot 回答的是「它什么时候发」,而运营真正要问的是「什么时候发有效」——
695
+ * 这两件事经常不一致:发得最密的时段常常是运营上班的时间,不是受众在线的时间。
696
+ *
697
+ * 样本极少的格子(一格只有 1 条)的"中位数"就是那一条本身,不能当规律看,
698
+ * 所以 by_slot 的计数要一起给出来,让界面把 n<2 的格子灰掉。
699
+ */
700
+ by_slot_engagement: z.array(z.number()).default([]),
612
701
  /** 贡献了一半发帖量的最小连续时段 —— 「该把发帖排在几点到几点」。 */
613
702
  peak_hours: z.object({ from: z.number(), to: z.number() }).nullable(),
703
+ /**
704
+ * 互动最好的时段(至少 2 条样本的格子里,按中位互动排前几)。
705
+ *
706
+ * 跟 peak_hours 并排看才有意义:两者错开 = 它把内容发在了自己方便的时间,
707
+ * 而不是受众活跃的时间 —— 这是个可以直接抄的空子。
708
+ */
709
+ best_slots: z
710
+ .array(z.object({ weekday: z.number(), hour: z.number(), n: z.number(), median_engagement: z.number() }))
711
+ .default([]),
614
712
  /** 每种形态的量和**中位**互动。中位而不是平均:一条爆款会把平均值拉到没有意义。 */
615
713
  formats: z.array(z.object({
616
714
  key: BirdFormatKey,
@@ -624,11 +722,36 @@ export const BirdAccountAnalysis = z.object({
624
722
  median_engagement: z.number(),
625
723
  median_views: z.number().nullable(),
626
724
  engagement_rate: z.number().nullable(),
725
+ /**
726
+ * 互动 ÷ **粉丝数**(用中位互动算)。跟上面那个 ÷浏览量 的必须并排看。
727
+ *
728
+ * ÷浏览量 回答「看到的人里有多少动了手」,÷粉丝数 回答「这个号的盘子有多少人还在听」。
729
+ * 一个号可能 ÷浏览量 很低但 ÷粉丝数 很高 —— 那说明它被算法大量推给了圈外人,
730
+ * 圈外人不互动是正常的,不是内容差。只看一个口径必然误判其中一种情况。
731
+ *
732
+ * 业内(Socialinsider 等)两个都给,因为 ÷粉丝数 是**跨号唯一可比**的那个:
733
+ * 浏览量的口径受算法分发影响太大,而粉丝数是个稳定的分母。
734
+ */
735
+ engagement_rate_by_followers: z.number().nullable(),
627
736
  /** 一条推的浏览量 / 粉丝数。>1 = 出圈了;远小于 1 = 连自己粉丝都没覆盖到。 */
628
737
  reach_per_follower: z.number().nullable(),
629
738
  /** 跟互动率放一起看能识破买量:粉丝天天涨而互动率贴地板,那些粉丝多半不是真的。 */
630
739
  follower_growth_per_day: z.number().nullable(),
631
- hashtags: z.array(z.object({ term: z.string(), n: z.number() })),
740
+ /**
741
+ * 按天:那天发了几条、那天的中位互动是多少。
742
+ *
743
+ * 回答「发得多是不是把互动稀释了」—— 这个问题只能按天看,汇总指标里它是隐形的。
744
+ * 只含真的发过帖的那些天(没发帖的天不占位,否则折线会被一串 0 拉平)。
745
+ */
746
+ by_day: z.array(z.object({ date: z.string(), n: z.number(), median_engagement: z.number() })).default([]),
747
+ /**
748
+ * 标签的频次**和有效性**。
749
+ *
750
+ * 只给频次会让人把"用得多"读成"有用"—— 而这两件事经常相反:挂得最勤的那个
751
+ * 品牌标签往往出现在最例行公事的公告里。median_engagement 是带这个标签的推的
752
+ * 中位互动,拿它跟全局中位比才知道这个标签值不值得挂。
753
+ */
754
+ hashtags: z.array(z.object({ term: z.string(), n: z.number(), median_engagement: z.number().default(0) })),
632
755
  terms: z.array(z.object({ term: z.string(), n: z.number() })),
633
756
  /** 开头句式 —— 最容易直接抄的一件事,而汇总指标完全看不见它。 */
634
757
  openers: z.array(z.object({ term: z.string(), n: z.number() })),
@@ -640,6 +763,18 @@ export const BirdRival = z.object({
640
763
  kind: z.enum(["rival", "kol", "official", "other"]),
641
764
  enabled: z.boolean(),
642
765
  note: z.string().nullable(),
766
+ /** 谁把它加进名单的。同一个 handle 只会有一行(handle 上有 UNIQUE),所以这里
767
+ * 记的是**最早加的那个人** —— 后来者的重复添加只更新分类,不抢归属。 */
768
+ added_by_email: z.string().nullable(),
769
+ added_at: z.string().nullable(),
770
+ /**
771
+ * 临时对标 —— 为了「跟这个号比一下」临时抓的,不是我们要长期盯的竞品。
772
+ *
773
+ * 分析必须读 bird_post_metrics,而那张表按 rival_id 归属,所以任意外部号也**必须**
774
+ * 在这张表里落一行 —— 绕不过去。用这一列把它跟正式名单分开:不进主表、不进
775
+ * 行业基准样本(基准只取 enabled=1)、不被定时同步捞到。
776
+ */
777
+ ad_hoc: z.boolean().default(false),
643
778
  last_synced_at: z.string().nullable(),
644
779
  last_error: z.string().nullable(),
645
780
  /* 最新快照带出来的展示字段 */
@@ -660,6 +795,13 @@ export const BirdRivalConfig = z.object({
660
795
  cron: z.string(),
661
796
  timezone: z.string(),
662
797
  posts_per_sync: z.number(),
798
+ /**
799
+ * 按天抓:抓到覆盖最近这么多天为止。0 = 按条数(默认)。
800
+ *
801
+ * 请求数不可预测 —— 一个日更 20 条的号翻 30 天就是 30 次请求。所以有硬上限,
802
+ * 而且界面上标成「一般别用」。
803
+ */
804
+ days_back: z.number(),
663
805
  auto_teardown: z.boolean(),
664
806
  /** 竞品发出爆款时告警。「蹭热点」的正确触发方式 —— 一条已经在这个受众里验证过的
665
807
  * 选题,比定时搜关键词精准得多。 */
@@ -678,6 +820,7 @@ export const BirdRivalConfigPatch = z.object({
678
820
  cron: z.string().max(120).optional(),
679
821
  timezone: z.string().max(64).optional(),
680
822
  posts_per_sync: z.number().int().min(20).max(200).optional(),
823
+ days_back: z.number().int().min(0).max(90).optional(),
681
824
  auto_teardown: z.boolean().optional(),
682
825
  alert_outliers: z.boolean().optional(),
683
826
  alert_multiple: z.number().min(2).max(50).optional(),
@@ -700,7 +843,58 @@ export const BirdRivalTeardown = z.object({
700
843
  why: z.string(),
701
844
  how: z.string(),
702
845
  })),
846
+ /**
847
+ * 五个维度各 1-10 分 + 一句理由。
848
+ *
849
+ * 为什么要有分:五个竞品摆在一起,「该优先学谁」是个必须能一眼看出来的问题,
850
+ * 而三段文字比不出高下。分数不是给账号排名用的,是给**我们分配注意力**用的。
851
+ */
852
+ scores: z
853
+ .array(z.object({ key: z.string(), label: z.string(), score: z.number(), why: z.string() }))
854
+ .default([]),
855
+ /** 别学什么。只说好的等于默认它全对 —— 而抽奖帖、日更 11 条这类做法照抄会出事。 */
856
+ avoid: z.array(z.object({ title: z.string(), why: z.string() })).default([]),
857
+ /** 爆款配方:火的那几条有什么共同点,以及照着做一条要满足什么。 */
858
+ recipe: z
859
+ .object({
860
+ pattern: z.string(),
861
+ ingredients: z.array(z.string()),
862
+ caveat: z.string(),
863
+ })
864
+ .nullable()
865
+ .default(null),
866
+ /**
867
+ * 选题支柱 —— 它翻来覆去在讲的那几件事。
868
+ *
869
+ * 形态分析("配图推互动高")回答的是**怎么写**,回答不了**写什么**。而后者
870
+ * 通常是更值钱的那个:形态可以一天学会,选题决定了这个号在受众心里是干什么的。
871
+ *
872
+ * ── 分工:归类交给模型,算术留给我们 ──────────────────────────────────
873
+ * 模型只回「第 3、7、12 条属于『新币上线』」,n / 占比 / 中位互动全部由服务端
874
+ * 按这些编号回算。理由跟 prompt 里那句"这些是算术结果,不要重新计算"一样:
875
+ * 模型算的百分比没法验证,而按编号回算的每一个数都能点回具体那几条推。
876
+ */
877
+ pillars: z
878
+ .array(z.object({
879
+ name: z.string(),
880
+ why: z.string(),
881
+ n: z.number(),
882
+ share: z.number(),
883
+ median_engagement: z.number(),
884
+ /** 归到这一类的推(编号是喂给模型的那份列表里的序号,从 1 开始)。 */
885
+ post_ids: z.array(z.string()).default([]),
886
+ }))
887
+ .default([]),
703
888
  error: z.string().nullable(),
889
+ /**
890
+ * pending = 排队中,running = 模型正在跑,done = 有结果了(成功或失败看 error)。
891
+ *
892
+ * 为什么要有这个状态:拆解要一到两分钟,既不能压在 HTTP 请求里(转圈两分钟、
893
+ * 刷新就白花),也不能丢进 waitUntil(实测连失败记录都写不出来)。
894
+ * 所以点击只排队,真正的调用交给每分钟的 cron —— 而界面要能区分
895
+ * 「在排队」「在跑」「跑完了」,不然又变成一个不知道在不在动的转圈。
896
+ */
897
+ status: z.enum(["pending", "running", "done"]).default("done"),
704
898
  });
705
899
  /**
706
900
  * 行业基准 —— 同一类竞品的中位数。
@@ -724,6 +918,44 @@ export const BirdBenchmark = z.object({
724
918
  follower_growth_per_day: z.number().nullable(),
725
919
  format_share: z.array(z.object({ key: BirdFormatKey, share: z.number() })),
726
920
  });
921
+ /**
922
+ * 声量份额。
923
+ *
924
+ * ── 它回答基准回答不了的那个问题 ────────────────────────────────────────────
925
+ * 基准说的是「典型同行做到什么程度」(中位数),份额说的是「注意力被谁拿走了」。
926
+ * 一个号可以各项指标都在基准之上,同时份额在掉 —— 因为别人涨得更快。业内
927
+ * (Sprout Social、Brandwatch)把 share of voice 当竞品分析的头号指标就是这个原因:
928
+ * 它是唯一一个**此消彼长**的指标,不会所有人一起变好看。
929
+ *
930
+ * ── 口径必须说清楚:这是「牌桌内份额」不是全网份额 ──────────────────────────
931
+ * 分母是「我们已跟踪的竞品 + 我们自己被审计过的号」在这个区间里的总量,不是
932
+ * 全行业。加一个竞品进名单,所有人的百分比都会变 —— 这是这个口径的固有性质,
933
+ * 不是 bug,但界面上必须写出来,否则会被当成"我们在全行业占 12%"来汇报。
934
+ *
935
+ * 真·全网份额要按品牌词搜全网(每个词 1-2 次请求,且要长期跑才有趋势),
936
+ * 是另一个成本量级,不在这里。
937
+ */
938
+ export const BirdShareOfVoice = z.object({
939
+ since: z.string(),
940
+ until: z.string(),
941
+ /** 分母:参与这次计算的账号数(竞品 + 我们的号)。 */
942
+ accounts: z.number(),
943
+ totals: z.object({ posts: z.number(), engagement: z.number(), views: z.number() }),
944
+ rows: z.array(z.object({
945
+ key: z.string(),
946
+ label: z.string(),
947
+ /** 'ours' = 我们的号,其余是竞品的 kind。 */
948
+ side: z.enum(["ours", "rival"]),
949
+ kind: z.string(),
950
+ posts: z.number(),
951
+ engagement: z.number(),
952
+ views: z.number(),
953
+ /** 三个份额各自加总 = 1(浏览量缺失的号会被排除在浏览份额之外,见实现)。 */
954
+ post_share: z.number(),
955
+ engagement_share: z.number(),
956
+ view_share: z.number().nullable(),
957
+ })),
958
+ });
727
959
  /**
728
960
  * 受众重合 —— 竞品的粉丝跟我们的关系。
729
961
  *
@@ -736,14 +968,59 @@ export const BirdAudienceOverlap = z.object({
736
968
  sampled: z.number(),
737
969
  /** 其中是我们自己账号的。 */
738
970
  ours: z.number(),
739
- /** 我们已经关注过的 —— 说明选人方向跟它一致。 */
740
- already_followed: z.number(),
741
- /** 可挖的。 */
971
+ /**
972
+ * 我们已经关注过的。**null = 不知道**,不是 0。
973
+ *
974
+ * 这个数来自 bird_follow_edges —— 我们自己账号的关注列表。如果从没同步过图谱,
975
+ * 那张表是空的,于是每个人都"没被我们关注过",重合度算出来是 0.0% ——
976
+ * 而正确的答案是「我们不知道」。
977
+ *
978
+ * 这两件事导向完全相反的动作:0% 会让人放心去挖(以为是一整片新池子),
979
+ * 而真相可能是这批人我们早就全关注过了。所以宁可显示"不知道"。
980
+ */
981
+ already_followed: z.number().nullable(),
982
+ /** 可挖的。图谱没同步时它等于"未被排除的",不等于"确定没关注过的"。 */
742
983
  untapped: z.number(),
743
- /** 重合度。高 = 我们和它在抢同一批人,内容要做差异化;低 = 一整片没碰过的池子。 */
744
- overlap_rate: z.number(),
984
+ /** 重合度。高 = 我们和它在抢同一批人;低 = 一整片没碰过的池子。null = 图谱没同步,判断不了。 */
985
+ overlap_rate: z.number().nullable(),
986
+ /** 我们自己账号的关注图谱同步过没有 —— 上面两个 null 的原因。 */
987
+ graph_synced: z.boolean().default(false),
988
+ /**
989
+ * 采样到但被粉丝数门槛筛掉的。
990
+ *
991
+ * 「采样 100、可挖 37」中间少的那 63 个必须有交代 —— 不写出来的话,
992
+ * 这个筛选就是一次静默的数据丢弃,而看的人会以为 100 里只有 37 个符合条件。
993
+ */
994
+ filtered_low_followers: z.number().default(0),
995
+ /** 上面那个门槛是多少。 */
996
+ min_followers: z.number().default(0),
997
+ /** 名单里疑似批量注册号的数量 —— 「竞品粉丝 = 精准受众」这个前提成不成立,看这个数。 */
998
+ junk: z.number().default(0),
999
+ /**
1000
+ * **全部采样**里疑似批量注册号的占比 —— 这个竞品的粉丝含水量。
1001
+ *
1002
+ * 分母是采样总数而不是过滤后的名单:批量号绝大多数在"粉丝不足 50"那一批里,
1003
+ * 用过滤后的数算会严重低估。
1004
+ *
1005
+ * 这是受众采样的第二个用途,而且可能比选人更值钱 —— 粉丝数是所有对标里最容易
1006
+ * 被当成事实的数字,而它恰恰是最容易买的。
1007
+ */
1008
+ junk_rate: z.number().nullable().default(null),
745
1009
  /** 这次灌进互关候选池多少个。 */
746
1010
  ingested: z.number(),
1011
+ /**
1012
+ * 灌进池子之后**会不会真的有人用**。
1013
+ *
1014
+ * 池子 → 分配给 worker → 任务 prompt 里的 `{{bird.follow_targets}}` 被替换成名单
1015
+ * → agent 照着去关注。这条链上有两道闸:`enable_follow_targets` 开关,以及
1016
+ * 至少要有一个任务的 prompt 里写了那个 token。
1017
+ *
1018
+ * 两道任意一道没开,「灌进候选池」的实际效果就是**往一张没人读的表里写几百行**。
1019
+ * 按钮不能长得像一个会产生后果的动作,而实际上什么都不会发生。
1020
+ */
1021
+ pool_enabled: z.boolean().default(false),
1022
+ /** 有几个定时任务的 prompt 真的引用了名单 token。0 = 灌了也没人取。 */
1023
+ pool_consumers: z.number().default(0),
747
1024
  top: z.array(z.object({
748
1025
  handle: z.string(),
749
1026
  name: z.string().nullable(),
@@ -751,6 +1028,8 @@ export const BirdAudienceOverlap = z.object({
751
1028
  is_blue: z.boolean().nullable(),
752
1029
  bio: z.string().nullable(),
753
1030
  score: z.number(),
1031
+ /** 像不像批量注册号(0..1)。不做静默丢弃 —— 标出来,让人自己判断。 */
1032
+ junk: z.number().default(0),
754
1033
  })),
755
1034
  });
756
1035
  /* ============================================================================
@@ -767,6 +1046,9 @@ export const BirdFollowConfig = z.object({
767
1046
  /** 在做互关任务的 worker。 */
768
1047
  worker_ids: z.array(z.string()),
769
1048
  cron: z.string(),
1049
+ /** 多久派一次关注任务。跟上面那个 cron(多久找一次人)是两个节奏。 */
1050
+ follow_cron: z.string().default("0 10,15,20 * * *"),
1051
+ follow_last_fire_at: z.string().nullable().default(null),
770
1052
  timezone: z.string(),
771
1053
  /** 每个号每轮给几个目标。 */
772
1054
  per_run: z.number(),
@@ -778,13 +1060,64 @@ export const BirdFollowConfig = z.object({
778
1060
  max_followers: z.number(),
779
1061
  require_blue: z.boolean(),
780
1062
  graph_ttl_hours: z.number(),
1063
+ /**
1064
+ * 关注图谱首次同步翻多少页(一页 50 人)。
1065
+ *
1066
+ * 这个数直接决定「差集准不准」:一个已经关注了 2000 人的号,如果只翻 10 页
1067
+ * (500 人),剩下 1500 会被当成「还没关注过」重新派一遍 —— agent 打开一看
1068
+ * 早就关注了,白花一次 profile 访问。那正是这套东西要消灭的浪费。
1069
+ */
1070
+ graph_max_pages: z.number(),
1071
+ /**
1072
+ * 一个号一天最多派出去多少个关注目标。
1073
+ *
1074
+ * per_run 管「一次几个」,这个管「一天几个」—— 两者之间隔着**关注任务自己的
1075
+ * 排期**,而那个排期不在 bird 这边。任务配成每小时一次就是 24 × per_run,
1076
+ * 所以必须有这一道兜底,否则量会被一个看不见的乘法带飞。
1077
+ */
1078
+ daily_cap: z.number(),
1079
+ /**
1080
+ * 候选池见底时自动再去互关意向帖的评论区找人。
1081
+ *
1082
+ * 探查原本只在 cron 到点(默认一天一次)或手动时发生,而一轮最多带回 100 个
1083
+ * 评论者、去重去已关注之后更少。需求是 daily_cap × 号数 —— 10 个号就是
1084
+ * 200/天,一天一轮池子中午就见底,然后所有任务被静默跳过到第二天。
1085
+ */
1086
+ auto_refill: z.boolean(),
1087
+ /** 可用候选低于这个数就补货。 */
1088
+ refill_min_pool: z.number(),
1089
+ /** 上次补货时间 —— 限速用(一轮探查要几十秒才有结果落库)。 */
1090
+ last_refill_at: z.string().nullable(),
1091
+ /**
1092
+ * 上次「给谁都补不出名单」的时刻。
1093
+ *
1094
+ * 派单那条查询要扫整个候选池(每个号一次)。池子够用时这是有回报的,
1095
+ * 干涸时就是**付全部代价拿零结果,而且每分钟重复一次** —— D1 按 rows_read 计费,
1096
+ * 1 万人的池子 × 20 个号 = 每天 2.88 亿行,全花在"什么都没发生"上。
1097
+ *
1098
+ * 有这个时间戳之后,只要一行索引查询就能判断「池子长新人没有」,没长就整轮跳过。
1099
+ */
1100
+ assign_dry_at: z.string().nullable(),
1101
+ /** 一轮挖几条互关帖 / 每条取几条回复 —— 供给量 = 两者相乘。 */
1102
+ hub_posts: z.number(),
1103
+ replies_per_hub: z.number(),
1104
+ /**
1105
+ * 滤不滤疑似批量注册号。
1106
+ *
1107
+ * 只求涨粉时**该关**:批量号恰恰是回关率最高的一批,它们存在的目的就是互关。
1108
+ * 滤掉是在用回关率换粉丝质量 —— 质量不是目标时那是纯损失。做品牌号时再打开。
1109
+ */
1110
+ filter_junk: z.boolean(),
781
1111
  last_run_at: z.string().nullable(),
782
1112
  last_status: z.string().nullable(),
783
1113
  });
784
1114
  export const BirdFollowConfigPatch = z.object({
785
1115
  enabled: z.boolean().optional(),
786
1116
  worker_ids: z.array(z.string()).max(200).optional(),
1117
+ /** 多久找一次人(+ 同步关注图谱)。 */
787
1118
  cron: z.string().max(120).optional(),
1119
+ /** 多久派一次关注任务 —— 跟上面那个是两个节奏,别混。 */
1120
+ follow_cron: z.string().max(120).optional(),
788
1121
  timezone: z.string().max(64).optional(),
789
1122
  per_run: z.number().int().min(1).max(50).optional(),
790
1123
  max_fanout: z.number().int().min(1).max(50).optional(),
@@ -793,6 +1126,67 @@ export const BirdFollowConfigPatch = z.object({
793
1126
  max_followers: z.number().int().min(1).max(100_000_000).optional(),
794
1127
  require_blue: z.boolean().optional(),
795
1128
  graph_ttl_hours: z.number().int().min(1).max(720).optional(),
1129
+ graph_max_pages: z.number().int().min(1).max(200).optional(),
1130
+ daily_cap: z.number().int().min(1).max(500).optional(),
1131
+ auto_refill: z.boolean().optional(),
1132
+ refill_min_pool: z.number().int().min(0).max(5000).optional(),
1133
+ hub_posts: z.number().int().min(1).max(20).optional(),
1134
+ replies_per_hub: z.number().int().min(5).max(100).optional(),
1135
+ filter_junk: z.boolean().optional(),
1136
+ });
1137
+ /**
1138
+ * 一张关注任务卡片。
1139
+ *
1140
+ * ── 为什么从单行配置改成卡片 ────────────────────────────────────────────────
1141
+ * 单行配置意味着全站只有一套「哪些号 / 一轮几个 / 多久关注一次」。而实际要的是
1142
+ * 新号慢慢养、老号放开跑;从竞品 A 灌的那批只给同赛道的号;某一批想单独停一阵
1143
+ * 而不是把整个功能关掉 —— 单行配置一件都做不到。
1144
+ *
1145
+ * 卡片只管**派发**。「去哪找人 / 多久找一次 / 图谱怎么同步」仍在全局配置里:
1146
+ * 一个号只有一份关注图谱,全站只有一个候选池,把关键词复制进每张卡看着更灵活,
1147
+ * 实际是三张卡把同一个搜索发三遍。
1148
+ */
1149
+ export const BirdFollowCard = z.object({
1150
+ id: z.string(),
1151
+ name: z.string(),
1152
+ enabled: z.boolean(),
1153
+ worker_ids: z.array(z.string()),
1154
+ /** 挑哪种来源的候选(rival / manual / hub)。空 = 整个池子。 */
1155
+ source_kinds: z.array(z.string()),
1156
+ per_run: z.number(),
1157
+ /**
1158
+ * 这张卡给一个号一天最多派多少。
1159
+ *
1160
+ * **跟 `BirdFollowConfig.daily_cap` 取小** —— 后者是账号级硬顶。
1161
+ * 一个号可以同时在多张卡里,只看卡片额度的话三张卡就是三倍的量,
1162
+ * 而风控是按账号算的,不按卡片算的。
1163
+ */
1164
+ daily_cap: z.number(),
1165
+ follow_cron: z.string(),
1166
+ timezone: z.string(),
1167
+ min_followers: z.number(),
1168
+ max_followers: z.number(),
1169
+ require_blue: z.boolean(),
1170
+ filter_junk: z.boolean(),
1171
+ last_fire_at: z.string().nullable(),
1172
+ /** 谁建的。admin 和创建者能改能删。迁移来的默认卡是 null —— 只有 admin 能动。 */
1173
+ created_by: z.string().nullable(),
1174
+ created_at: z.string(),
1175
+ updated_at: z.string(),
1176
+ });
1177
+ export const BirdFollowCardInput = z.object({
1178
+ name: z.string().min(1).max(60).optional(),
1179
+ enabled: z.boolean().optional(),
1180
+ worker_ids: z.array(z.string()).max(200).optional(),
1181
+ source_kinds: z.array(z.enum(["rival", "manual", "hub"])).max(3).optional(),
1182
+ per_run: z.number().int().min(1).max(50).optional(),
1183
+ daily_cap: z.number().int().min(1).max(500).optional(),
1184
+ follow_cron: z.string().max(120).optional(),
1185
+ timezone: z.string().max(64).optional(),
1186
+ min_followers: z.number().int().min(0).max(10_000_000).optional(),
1187
+ max_followers: z.number().int().min(1).max(100_000_000).optional(),
1188
+ require_blue: z.boolean().optional(),
1189
+ filter_junk: z.boolean().optional(),
796
1190
  });
797
1191
  /** 候选池里的一个人。 */
798
1192
  export const BirdFollowCandidate = z.object({
@@ -811,6 +1205,23 @@ export const BirdFollowCandidate = z.object({
811
1205
  discovered_at: z.string(),
812
1206
  /** 已经派给了几个我们的号。 */
813
1207
  assigned_to: z.number(),
1208
+ /**
1209
+ * 到底派给了**哪些**号,以及那个号跑出来什么结果。
1210
+ *
1211
+ * 光有个数字答不了「这批人到底有没有用」:同一个数字 3 可能是三个号都关注上了,
1212
+ * 也可能是三个号打开一看全都早就关注过(那说明这批人是重复挖回来的)。
1213
+ * 而这两种情况对应的动作完全相反 —— 一个是继续往这挖,一个是别再挖了。
1214
+ */
1215
+ assigned_detail: z
1216
+ .array(z.object({
1217
+ /** 派给了谁(@handle,没有就退回 worker 名)。 */
1218
+ worker: z.string(),
1219
+ /** ok / already / failed / skipped;agent 没回报过就是 null。 */
1220
+ result: z.string().nullable(),
1221
+ /** 关注图谱里确认关注上了 —— 唯一可信的「成了」。 */
1222
+ confirmed: z.boolean(),
1223
+ }))
1224
+ .default([]),
814
1225
  });
815
1226
  /** 派给某个号的一个目标。 */
816
1227
  export const BirdFollowTarget = z.object({
@@ -834,9 +1245,19 @@ export const BIRD_FOLLOW_TOKEN = "{{bird.follow_targets}}";
834
1245
  export const BirdAuditBatch = z.object({
835
1246
  batch_id: z.string(),
836
1247
  started_at: z.string(),
1248
+ finished_at: z.string().nullable(),
837
1249
  accounts: z.number(),
838
1250
  jobs: z.number(),
839
1251
  failed: z.number(),
1252
+ running: z.number(),
840
1253
  source: z.string(),
1254
+ /** 发起时自己起的名字。没起就是 null,界面退回「N 个号」。 */
1255
+ label: z.string().nullable(),
1256
+ /** 这一批当时跑的统计区间 —— 打开它的报告要用它自己的窗口,不是页面上当前选的。 */
1257
+ window_since: z.string().nullable(),
1258
+ window_until: z.string().nullable(),
1259
+ window_days: z.number().nullable(),
1260
+ requested_by: z.string().nullable(),
1261
+ requested_by_email: z.string().nullable(),
841
1262
  });
842
1263
  //# sourceMappingURL=bird-contracts.js.map