热点提取智能体

⚠️ 铁律（不可违反）

1. 数据源需要登录时，必须返回人工确认，不得私自降级或跳过采集。
• 如果任何一个数据源在采集过程中遇到登录要求、验证码、人机验证等情况，必须立即暂停该源的当前采集路径，并在结果中明确标记"该源需要人工登录确认"。
• 禁止行为：自动跳过该源、用备用源替代后不告知、将降级视为正常完成、在报告中隐藏该源的失败状态。
• 正确做法：将该源标记为 status: login_required，在最终交付报告中醒目提示人工介入，其他数据源正常采集不受影响。
2. 任何被拦截或采集量为 0 条的数据源，必须按 A→B→C 顺序处理，不得直接跳过。
• A：先执行配置中的备用路径 / 备用 API / fallback 数据源。 如果备用源成功，记录本次降级事实，并继续后续流程。
• B：A 仍无数据时，改用 Chrome 桥接 / 浏览器登录态采集。 如果需要登录、验证码或人工操作，必须按第 1 条返回人工确认。
• C：A+B 仍无采集量时，最多探索 3 个新的候选数据源。 3 个候选源都没有采集结果后，才允许停止该数据源本轮采集，并继续后面的流水线步骤；不得阻塞整体流程。
• 停止该源前必须在运行报告中写明：主路径结果、A/B/C 尝试记录、3 个候选源名称/URL、失败原因。
• "status=ok + 0 条"的组合一律视为异常，必须触发本规则。
3. 探索成功的新数据源必须加入数据源库，作为下一次常规采集源。
• 成功标准：可稳定返回非空结果，字段至少包含标题和来源；最好包含热度/排名/链接。
• 必须更新 config/platforms.yaml、references/data-sources.md 以及 collector 代码，并在报告中说明新增源名称、URL、解析方式、适用平台。
4. 采集结果必须如实反映每个数据源的真实状态，不得隐瞒失败、降级、拦截、登录要求或 0 条异常。

执行命令

cd ~/.qclaw/workspace-agent-43c8c1ee && \
  HOTSPOT_CHROME_BRIDGE=1 SKIP_DEGRADED_CHECK=1 python3 scripts/main.py

输出文件：queue/hot_topics_YYYYMMDD.json

数据源（9个，全部必须跑）

详细采集策略见 references/data-sources.md。

Chrome桥接：wait=12s，limit=30，全局串行锁。HOTSPOT_CHROME_BRIDGE=0 可关闭全部Chrome桥接。

image_urls 覆盖率总结

评分算法

详细算法说明见 references/algorithm.md。

五维加权评分

Score = (0.35×HGR_norm + 0.25×CPRI/100 + 0.15×置信度 + 0.15×content_fit + 0.10×timing_match) × 100 × 文化适配

辅助指标

• EMA：α=0.4，预测下一时刻热度
• 历史相似度：Jaccard similarity ≥ 0.7 → 额外加权
• 文化适配：国际话题 ×（普世1.0 / 中等0.7 / 高距离0.4）
• 时机阶段：萌芽0-6h / 成长6-24h / 成熟24-48h / 衰退>48h

流水线步骤

1. 采集：collector.py 并发抓取13个数据源（含 image_urls 提取）
2. 标准化：normalizer.py 统一数据模型（含 image_urls 透传）
3. 去重：deduplicator.py 余弦相似度≥0.85合并
4. 关键词过滤：keyword_filter.py 三层过滤（基础→必须→过滤）
5. 评分：predictor.py 五维加权评分
6. 质量门：quality_check.py 剔除不合格话题
7. 交付：写入 JSON + 7天旧文件自动清理

详细流程见 references/pipeline.md。

质量门规则

交付前检查：

• [ ] 过滤词未命中（政治/暴力/谣言/广告）
• [ ] 24h内未重复交付
• [ ] 至少一个官方/可信来源
• [ ] 时效窗口为成长期或成熟期有差异化角度
• [ ] degraded源不超过50%（阈值从30%调整，避免3/9降级就全拒）
• [ ] 无 login_required 状态的数据源（如有，必须已通知人工确认）

Chrome 桥接图片提取

chrome_bridge.py 实现了双重回退机制，MAX_IMAGES_PER_TOPIC=10 控制每个话题最多配图数：

图片分配策略：

• 1:1 对应：页面上提取的图片按顺序1:1分配给话题
• YouTube 多分辨率扩展：从1张缩略图URL提取video_id，构造maxresdefault/hqdefault/sddefault/mqdefault/default共5张
• 其他平台：页面级提取，通常1张/话题

1. AppleScript JS（_extract_page_image_urls）：在 Chrome 标签页执行 JS 提取 DOM 图片
• ⚠️ 需要用户手动开启 Chrome "允许 Apple 事件中的 JavaScript"
• macOS 安全策略限制，无法通过脚本自动开启
2. CDP（_extract_image_urls_via_cdp）：通过 Chrome DevTools Protocol 执行 JS
• 需要 Chrome 以 --remote-debugging-port=9222 启动：open -a 'Google Chrome' --args --remote-debugging-port=9222
• main.py 启动时自动检测 CDP 端口（_check_cdp_available），不可用时优雅降级跳过图片提取
• 依赖 Node.js + ws 模块（全局安装）
• Node.js 路径：/Users/kelly/Library/Application Support/QClaw/openclaw/config/bin/node
• NODE_PATH：/Users/kelly/Library/Application Support/QClaw/npm-global/lib/node_modules

各平台 CDP CSS 选择器：

• YouTube: ytd-rich-item-renderer img[src*="vi/"]
• TikTok: img[src*="tiktokcdn.com"]
• 小红书: img[src="xhscdn"], img[src="sns-webpic-qc"]
• Twitter: img[src*="pbs.twimg.com"]

交付 JSON 字段

{
  "run_id": "uuid",
  "run_at": "ISO8601",
  "domestic_top2": [
    {
      "title": "话题标题",
      "source_platform": "baidu",
      "heat_score": 123456,
      "image_urls": ["https://...", "https://..."],  // 1-10张配图
      "score": 55.27,
      "content_type": "资讯",
      "tone": "理性客观",
      "audience": "泛大众",
      "suggested_angles": ["事件梳理", "深度分析"],
      "content_description": "..."
    }
  ],
  "international_top2": [...],
  "alerts": {"red": [], "yellow": []},
  "source_health": {"weibo": "ok", ...},
  "stats": {"raw_count": 352, "normalized_count": 324, "scored_count": 324}
}

目录结构

~/.qclaw/workspace-agent-43c8c1ee/
├── scripts/
│   ├── main.py          # 主流水线（含关键词过滤 + 7天文件清理）
│   ├── collector.py     # 13个数据源采集（含 image_urls + fallback）
│   ├── chrome_bridge.py # Chrome桥接 + CDP图片提取
│   ├── predictor.py     # 五维评分算法
│   ├── normalizer.py    # 数据标准化（含去重 + image_urls 透传）
│   └── quality_check.py # 质量检查（degraded阈值0.5）
├── config/
│   ├── platforms.yaml   # 平台配置
│   ├── thresholds.yaml  # 算法阈值
│   └── frequency_words.txt # 关键词规则
├── queue/               # 交付JSON
├── data/                # 中间数据（7天自动清理）
└── memory/              # 运行记录

管理命令

• 定时任务：openclaw cron list / edit --enabled false / run
• 手动执行：cd ~/.qclaw/workspace-agent-43c8c1ee && python3 scripts/main.py
• 关闭Chrome桥接：HOTSPOT_CHROME_BRIDGE=0 python3 scripts/main.py
• 跳过降级检查：SKIP_DEGRADED_CHECK=1 python3 scripts/main.py
• 单测桥接：python3 scripts/chrome_bridge.py --platform youtube_trending --wait 7 --limit 12 --pretty