Databrain Opinion Hotposts

Databrain · Opinion Hotposts (每日热帖日报)

按订阅游戏，每日定时生成「过去 24h 各平台热帖榜单」，分平台展示 Top N，输出 markdown / html 供推送或网页展示。

架构：脚本取数 → 你填 spec → 校验 → 脚本渲染 → 原样展示

make_daily_digest.py --json   →  候选帖 JSON（脚本取数，确定性）
        ↓
你（agent）填 digest_spec.json  →  去重裁断 / AI 摘要 / 热议话题 / 选帖（智能）
        ↓
validate_digest.py            →  schema 校验，不过就改了重填
        ↓
render_digest.py --format ... →  markdown / html（版式由代码锁死）
        ↓
原样展示渲染产物

分工：脚本做「算得出的」（取数 + 格式）；你做「算不出的」（摘要语义 / 同事件判断 / 话题归纳）。这些智能产物不影响版式——版式 100% 由渲染器保证。

🚨 首要硬规则（必须遵守）

1. 禁止手写最终推送正文。 不要自己拼 📰...━━━... 这类文本或 HTML。
2. 必须走完整流程：⓪ 调 report_log.py 打点 ① 跑取数脚本 ② 按 schema 填 digest_spec.json ③ 跑 validate_digest.py 通过 ④ 跑 render_digest.py 生成目标格式 ⑤ 原样返回/展示渲染产物，不增删一字 ⑥ 跑 publish_digest.py 投递：AI Gallery 默认自动上传免批准；企业微信仅在用户已提供 webhook 时推送，否则只产出预览，不强推。
3. 你只在 digest_spec.json 里填「算不出的」字段（标题取原文、摘要、情感词、去重后的选帖、话题）。版式相关（分隔线 / emoji / 万粉换算 / 时间 / 千分位 / 标题截断 / 空平台隐藏）交给渲染器，不要自己做。

执行流程

Step 0：打点（每次请求开始时调一次）

每次用户发起热帖请求，先调一次打点 CLI 记录本次调用（-m 传用户原始问题）：

python scripts/report_log.py -m "<用户原始问题>"

best-effort：DATABRAIN_TOKEN 缺失或网络失败都会静默跳过，不影响后续流程，也无需重试。打点只在此处做一次（取数时），后续渲染/投递不再重复打点。

Step 1：取数（脚本）

python scripts/make_daily_digest.py --game_name "PUBG Mobile" --out_file /tmp/candidates.json
# 可选：--game_id（跳过自动查询）/ --platforms reddit,x,youtube / --top_n 5 / --hours 24

输出 candidates.json 结构：

{
  "params": {"game_id": "...", "game_name": "PUBG Mobile", "hours": 24, "top_n": 5, "digest_time": "2026-04-22 09:00"},
  "summary_data": {"sentiment": {"pos": 0.33, "neu": 0.42, "neg": 0.25}},
  "platforms": [
    {"key": "reddit", "display": "🔥 Reddit", "candidates": [ {帖子...}, ... ], "candidate_total": 15, "skipped": false, "error": null}
  ]
}

每个候选帖含：author / followers / time / engagement / sentiment_rating / sentiment / url / snippet / title(空) / language / country。候选数 = top_n × 3，已按互动量降序，留给你去重后补位。

Step 2：你做 4 件智能活，产出 digest_spec.json

schema 权威定义见 references/digest_schema.md。逐平台处理候选：

① 去重（§4.3.3）

读每条候选的 title（若空用 snippet）+ snippet，判断哪些是「同一事件」。

判同事件的判据（满足任一即同事件，跨语种同样适用）：

• 指向同一具体对象/事件：同一角色、同一卡池/banner、同一活动/复刻、同一版本更新、同一 bug/事故、同一官方公告。
• 标题措辞不同 / 标题党改写 / 翻译成不同语言，只要指向同一具体事件 → 同事件。

不算同事件：

• 同一对象但不同侧面：同一角色「技能数值」vs「皮肤外观」→ 不同话题。
• 泛泛吐槽/讨论 vs 具体事件。

正例（应合并）：

A "New 5-star kit leak shows insane scaling"     互动 2150
B "新キャラのスキル倍率がぶっ壊れ"                互动 1980
C "leak: upcoming banner character is broken"     互动 900
→ 同一「新角色数值泄露」事件：保留 A、B（互动最高 2 条），C 被挤出由下一候选补位；
  merged_note: "同一话题 3 条相关讨论已合并展示 2 条"

反例（不合并）：

A "新卡池抽卡体验吐槽"   ← 卡池付费/出货
B "新角色皮肤展示"       ← 外观
→ 不同话题，各自占位

处理规则：

• 同平台同事件最多保留 2 条（互动最高的 2 条）；被挤出的位置由下一位候选补齐到 Top N。
• 该平台若发生合并，在 platforms[].merged_note 写：同一话题 N 条相关讨论已合并展示 2 条（N = 该事件候选总数）。
• 候选很多时可先用粗筛工具减少比对量：库函数 dedup.fingerprint（标题前缀指纹，python scripts/dedup.py --self_test 可验证）；最终裁断仍以你的语义判断为准。

② 标题（§4.4.1）

• title 填原文标题全文，不翻译（feeds 无独立标题，从 snippet 提炼一句作标题；保持原文语种）。
• 不要自己截断——超长截断（超 20 中文字等效宽度显示 ...）由渲染器按显示宽度处理。

③ AI 一句话摘要（§4.4.2）

• 基于「标题 + 正文 snippet（已按信息量归一：中文≈200字 / 拉丁≈400字符）」生成，≤30 字中文，概括帖子主题。
• 只描述内容，禁止评价/观点。
• 原文非中文 → 摘要直接输出中文。
• 生成不了/失败 → summary 填 null（渲染器自动不显示摘要行，不要硬塞正文）。

④ 热议话题（§4.5）

• 通读所有平台入选帖，归纳 Top 3 话题标签 + 命中帖数，填 summary.topics：[["新卡池", 7], ["剧情更新", 4], ["外观皮肤", 3]]。
• 归纳不出/无文本 → 省略 topics（该行不渲染）。

其余字段：sentiment 直接用候选里的 sentiment 词（正面/中性/负面）；summary.sentiment 用 candidates.summary_data.sentiment；game_name / digest_time 用 params。热帖总数与各平台计数不用填，渲染器自动算。

时区约定：feeds 的 comment_time 实为 UTC+8 墙钟（入库被误标 +00，实测最新帖时间贴合上海当前时刻）。故 post.time 原样回填、勿做时区换算；digest_time 由取数脚本按同一时区（utcnow + 8）生成，二者同基准，渲染器 naive 比对算「Xh 前」。SQL 时间窗也以 +8 锚点卡「过去 24h」。需改时区设 env DIGEST_TZ_OFFSET_HOURS（默认 8）。

Step 3：校验

python scripts/validate_digest.py --input /tmp/spec.json --top_n 5

不通过会列出错误（缺字段 / sentiment 非三词 / url 非法 / 超 top_n / 同事件 >2）。按提示修正 spec 后重跑，直到通过。

Step 4：渲染并原样展示

python scripts/render_digest.py --input /tmp/spec.json --format markdown    # 企微/飞书/Slack/WorkBuddy
python scripts/render_digest.py --input /tmp/spec.json --format html        # AI Gallery / 内部网页

把渲染产物原样交给下游渠道，不要再加工。

Step 5：投递（自己网站 + 企业微信）

publish_digest.py 把一份 spec 同时投递到两条渠道：使用当前用户 DATABRAIN_TOKEN 上传 HTML 到 AI Gallery（visibility=self），回读链接写回底部 查看完整列表，并把 markdown 推送到企业微信机器人。

# 双渠道：上传网站 + 推企微（webhook 可多个，用 ; 分隔）
python scripts/publish_digest.py --input /tmp/spec.json \
  --webhook_url "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"

# 只预览渲染结果（不上传、不推送）
python scripts/publish_digest.py --input /tmp/spec.json --preview_only

# 只上传网站 / 只推企微
python scripts/publish_digest.py --input /tmp/spec.json --no_webhook
python scripts/publish_digest.py --input /tmp/spec.json --no_gallery \
  --webhook_url "$WEBHOOK_URL"

网站投递走 publish_gallery_html.py，默认使用当前用户的 DATABRAIN_TOKEN，作品归属当前用户账号并保持 visibility=self。投递降级而不阻断：Gallery 失败保留本地 HTML 链接并继续推企微；企微推送超 4096 字自动分段。

渠道与凭证（两条渠道权限模型不同，agent 需遵守）：

• AI Gallery（当前用户账号）= 自动、免批准：HTML 渲染好之后默认使用当前用户的 DATABRAIN_TOKEN 上传，并保持 visibility=self。发布出的作品归属当前用户账号；若用户 token 没有 Gallery 创建/访问权限，自动降级为本地 HTML 链接。
• 企业微信 = 用户自己设置：webhook 不随 skill 预置，必须是用户提供的 --webhook_url 或环境变量 WEBHOOK_URLS。推送前必须先拿到用户提供的 webhook；没有就只产出 markdown 预览（--preview_only 或省略 --webhook_url），不要伪造、猜测或在未确认的情况下用别的 webhook 强推。

两种输出格式对应渠道

设计要点

• 时间锚点：以「调用时刻」为锚点向前回溯（默认 24h），不做「自然日 00:00–24:00」（避免割裂跨零点的热度）。
• 分榜呈现：每平台一个榜，平台间互动量不可比（Reddit 1k 已爆款 / X 1k 中等），不做全局总榜。
• 入榜门槛：各平台独立配置（见 platforms.yaml），避免冷门时段堆出「互动 50 的 Top 5」。
• 去重：同事件最多 2 条 + 后裔补位 + 合并提示（你裁断，spec 落实）。
• 空平台隐藏：0 帖平台整块跳过，两种 format 同步生效（渲染器负责）。
• 链接安全：渲染器自动过滤非 http(s) 的恶意 url。

环境变量

Token 为空时引导用户前往 https://databrain.woa.com/v2/user-center/personal-tokens-center 获取，设置 DATABRAIN_TOKEN 环境变量（不加 Bearer）。外网用 https://databrain-global.intlgame.com/...。

模块结构

platforms.yaml 入榜门槛（§4.3.1）

Steam 不在产品 §4.3.1 门槛表内，为本 skill 扩展项，默认关闭以避免 PC/移动游戏返回大量低质 Steam 评论；通过 yaml overrides 按 game_id 启用。 channel_name 已通过 PUBG Mobile / NIKKE 实测；查不到数据自动 skip + stderr 提示。

按 game 覆盖：

overrides:
  ufc454d9b1af70b40588e2a6fa4da4a8b:
    platforms:
      reddit:
        min_engagement: 50      # 该游戏 reddit 社区小，调低门槛
    defaults:
      top_n: 3

不联网自检

python scripts/make_daily_digest.py --self_test   # 取数 + JSON 结构
python scripts/render_digest.py    --self_test    # markdown/html + 宽度截断
python scripts/validate_digest.py  --self_test    # spec 校验
python scripts/game_search.py      --self_test
python scripts/query_executor.py   --self_test
python scripts/dedup.py            --self_test    # 可选粗筛工具
python scripts/publish_gallery_html.py --self_test  # 网站上传（tags/url 构造）
python scripts/publish_digest.py   --self_test    # 投递编排（SSRF 白名单/分段/链接注入）

与其他 skill 的关系

• 依赖：无。
• 数据源同源：与 databrain-opinion-metrics 共享 feeds 表，遵循同样的 EdgeOne 黑名单约束。
• 投递自带：scripts/publish_digest.py 直接把热帖投递到当前用户账号下的 AI Gallery（visibility=self）+ 企业微信，无需借用其他 skill。渲染产物也可手动喂飞书/Slack/WorkBuddy 或嵌内部网页。

参考

• digest_spec 产出契约：references/digest_schema.md
• SQL 模板与字段：references/sql_templates.md
• feeds 表字段权威表（含 EdgeOne 黑名单详情）：databrain-opinion-metrics/references/feeds_templates.md