选题雷达

概述

解决内容团队最大的时间黑洞：今天写什么。

不是给一堆数据让用户自己看，而是让接口取证、AI 给结论：

1. 选入口：关键词 / 实时热搜 / 对标账号，三种模式任选
2. 扩散：沿入口生成候选选题或主题标签
3. 取证：每个词抓一批公开文章 + 逐篇取公开互动数据
4. 建模：算需求热度、竞争度、机会分，划四象限（蓝海 / 主战场 / 红海 / 冷淡区）
5. 交付：机会矩阵图 + 蓝海 Top10 卡片 + 账号内容版图 + 内容缺口 + 可复制 Markdown 清单

核心价值不在接口调用，在评分模型、可信度处理与 AI 洞察层：被微信展示上限截断的阅读数不参与均值； 展示值（「6.2万」）与精确整数分列标注；评分公式完全公开可审计。

三种模式分别回答不同的问题：

何时使用

• 用户说「不知道写什么」「帮我找选题」「有什么能写的话题」
• 用户要评估某个领域的内容机会、找蓝海词 / 长尾词
• 新账号冷启动，需要选一条竞争较小的切入路径
• 老账号选题枯竭，需要拓展相邻话题
• 用户给了某个领域（如「少儿编程」「习惯养成」），想知道怎么切
• 用户想追热点：今天搜一搜热什么、哪些热点值得追
• 用户想做竞品/对标账号分析：几个同类型号在写什么、哪些题材数据好、自己的号缺什么
• 用户要给自己的号做内容审计：历史题材覆盖与互动效果复盘

触发后，先问用户想从哪个入口开始，不要默认直接跑关键词模式。

怎么触发

对话里怎么说

直接用大白话说需求即可，以下说法都会命中：

• 「不知道写什么，帮我找选题」
• 「习惯养成这个领域有什么蓝海词」
• 「今天有什么热点能追」
• 「帮我看看这几个对标号在写什么」
• 「给我的号做个内容审计」
• 「这个选题竞争大不大，值得写吗」

直接下命令

也可以跳过提问，把入口和参数一次说清：

# 关键词：给我一个领域词
--seed "习惯养成"

# 热点：看今天搜一搜热什么
--hot

# 账号：给我对标号的任意一篇文章链接
--account "广东教育传媒|https://mp.weixin.qq.com/s?__biz=XXX"

一句话说清三种入口的区别

接口契约（严格依据曼格云公开契约）

第 4 步原本用接口 30（完整报告 ¥0.063），已改为接口 3 的 analysis 模式。 实测两者返回的统计字段完全一致，单价只有 1/8。详见下方实测记录第 7 条。

• 认证：Header X-API-Key（勿写入前端 / 日志 / 公开仓库）
• 限额：均为 300 次/分钟、30000 次/日；脚本默认限流 4 次/秒
• 幂等：普通请求不填 Idempotency-Key；脚本仅在自行重试同一请求时复用同一个值，避免重复扣费
• 分页：接口 14 用 cursor 回传；脚本每词只取单页（limit 即每词篇数）

实测行为记录（与契约文档互补，2026-08-28 实测）

这些是实测得到的、契约文档未逐一说明的行为，脚本已做对应处理：

1. 接口 23 的 data.items[] 实际是对象数组，每项含 word / wordHighlight / reportFlag 等。 契约只声明 items 为数组未声明子字段 → 脚本防御式读取 item["word"]，取不到则跳过。 返回约 10 个推荐词。
2. 接口 14 的 items[] 除契约字段外还返回 source 对象，其中：
   • source.title = 公众号名称（契约未声明，但很关键，账号集中度要靠它算）
   • source.tag[].title = 页面展示值，如「阅读 6.2万」——属展示值不是精确值，脚本只在精确值缺失时标注显示
3. 接口 1 的 title / accountName 经常返回空字符串。 → 标题与账号名必须取自接口 14，接口 1 只用于补数据。这是最容易踩的坑。
4. 接口 1 可直接吃接口 14 返回的 doc_url（带 chksm、scene=7#rd 也能解析）， 无需先做短链解析，省一道调用。
5. 接口 1 的 consumption 在当前账户实测为 0（平台侧对已有近期快照的文章免单）。 实测 3 次运行 × 80 篇文章，240 次接口 1 调用全部 consumption=0。 → 这是当前 API Key 所属账户的计费特性，不具备普遍性，换账户、换时间都可能恢复收费。 → 因此一切成本估算与方案选型均以契约单价为准，不得把免单计入考量。 → 脚本按响应里的 consumption 累计，实际花多少以输出为准。
6. 只保留匹配 ^https://mp\.weixin\.qq\.com/s(?:/|\?|$) 的链接才调接口 1/3， 其余类型（视频号、小程序等）直接跳过，避免浪费额度。
7. 接口 3 的 format=analysis 可完全替代接口 30 的内容统计，单价 ¥0.008 vs ¥0.063。 同一篇文章实测，data.content 与接口 30 的 contentAnalysis 逐字段相同 （characterCount / chineseCharacterCount / latinWordCount / paragraphCount / estimatedReadMinutes / fingerprintSha256）， data.media 与 mediaSummary 相同（imageCount / videoCount / audioCount / linkCount / externalLinkCount / linkedDomains）。 → 本 skill 只需要内容规格，接口 30 打包的 article / engagement / job 全是冗余， 因此选接口 3。需要文章身份或互动字段时再回头用接口 30。

扩展能力：实时热搜榜（接口 20）

接口 20「搜一搜搜索引导」在 query 留空时，返回微信搜一搜当前的实时热搜榜， POST /openapi/wechat-native-search-guide/search/guide，¥0.10/次。 这是除「种子词扩散」之外的第二条候选词来源，适合追热点的场景。

实测返回结构（契约只声明了 query / data / source，以下为实测补充，按防御式读取）：

data.count        —— 热词条数（实测 8）
data.items[]      —— 热词列表，每项含 word / id / operationType / source
data.items[].id   —— 格式 "{排名}-hotscore-{热词}"，可直接取排名
data.groups[]     —— 分组，实测只有一组，title = "搜索发现"
data.guideSource  —— 实测 "page-store"

热搜榜 ≠ 选题清单，这是最容易踩的坑。 热词多为新闻事件（讣告、赛事、案件）， 直接拿原词去搜，往往样本极少、时效性过强，评分不可信。 正确做法是先由 AI 把热词转译成可长期搜索的选题角度，再用转译后的词跑分析：

同时要主动判断哪些不能碰：时政案件、安全事故、讣告类——追热点的风险高于收益。 这类价值判断应由 AI 层给出，脚本本身不做判断。

前置条件

• 曼格云 API Key（--api-key 或环境变量 MANGE_API_KEY）；没有 Key 时前往 https://api.we-media.cn?source=clawhub 注册并创建
• Python 3.10+（脚本仅依赖标准库，无需安装第三方包）
• 报告中的机会矩阵为内联 SVG，无需联网即可打开，导出 PDF/图片也不会掉内容

工作流程

第 0 步：让用户选模式

触发后不要直接跑脚本。先问：

「你想从哪个入口找选题？

1. 给关键词，我帮你扩散蓝海长尾词；
2. 看今天热搜，我帮你筛能追的角度；
3. 给对标公众号，我帮你分析它们的内容版图和缺口。」

根据答案进入对应模式。

模式 A：关键词模式 --seed

适合：已有领域方向，想找细分蓝海词。

# 标准用法（推荐，按单价计约 ¥1.9）
python scripts/topic_radar.py \
    --api-key "YOUR_API_KEY" \
    --seed "习惯养成" \
    --output 选题雷达_习惯养成.html \
    --markdown 选题雷达_习惯养成.md

# 全面模式：二级扩散 + 每词 12 篇 + 5 个深度采样（按单价计约 ¥7）
python scripts/topic_radar.py --api-key "$KEY" --seed "私域运营" \
    --expand 2 --extra-words 15 --per-word 12 --deep 5 \
    --output radar.html --json raw.json

# 只想看近一周的机会
python scripts/topic_radar.py --api-key "$KEY" --seed "AI 写作" \
    --publish-time week --output radar.html

模式 B：热点模式 --hot

适合：追今天搜一搜热搜，找能写的角度。

# 1. 拉取实时热搜榜，输出可转译的热词 JSON
python scripts/topic_radar.py --api-key "$KEY" --hot \
    --json hot_words.json

# 2. 人工/AI 挑选并转译出 2-5 个可写选题词，一次性跑分析
python scripts/topic_radar.py --api-key "$KEY" \
    --seeds "扶老人反被索赔,好人被讹,见义勇为法律风险" \
    --output 热点_扶老人.html

热点模式分两步：

1. --hot 只拉榜单，花 ¥0.10，输出 hot_words.json。
2. 由 AI 判断哪些热词值得转译、哪些不能碰（时政、事故、讣告类通常建议弃用）， 再用转译后的词跑关键词模式。

不要把热搜原词直接当 --seed 跑分析。新闻事件往往样本太少、时效太短，评分不可信。

模式 C：账号模式 --account

适合：对标竞品号、做自审、找内容缺口。

# 输入 2-3 个公众号的文章链接（每号可命名，命名在前用 | 分隔）
python scripts/topic_radar.py --api-key "$KEY" \
    --account "广东教育传媒|https://mp.weixin.qq.com/s?__biz=XXX" \
    --account "学前洞见|https://mp.weixin.qq.com/s?__biz=YYY" \
    --pages 2 --max-articles 20 --topics 8 \
    --output 内容版图_教育号.html --markdown 内容版图_教育号.md

# 只审计一个号（自审）
python scripts/topic_radar.py --api-key "$KEY" \
    --account "https://mp.weixin.qq.com/s?__biz=ZZZ" \
    --pages 3 --max-articles 40 --topics 10 \
    --output 我的号内容审计.html

账号参数：

• --account 可重复多次；链接支持普通文章 URL 或 gh_ 开头的原始 ID
• 建议加命名：名称|URL，因为接口不一定能取到账号名
• --pages 每号翻页数；接口 4 每页最多 20 篇
• --max-articles 每号最多分析的篇数
• --topics 每号提取的主题标签数

账号模式输出：

• 每个账号的阅读中位数、互动率、高频主题、代表作
• 内容缺口：某账号高频做、其他账号完全没碰的主题

第 N 步：注入 AI 洞察，把数据变成结论

脚本只负责采集与计算，不会「读」数据，也不会替你写标题、给执行顺序。 想让报告真正变成「可直接照着做」的产品，建议加一层 AI 解读：

# 第一步：采集 + 落 JSON（关键词/账号模式均适用）
python scripts/topic_radar.py --api-key "$KEY" --seed "习惯养成" \
    --json raw.json --output radar.html

# 第二步：Agent 读 raw.json，产出 summary.json
# 参考示例：本项目工作区 out/ai_summary_习惯养成.json

# 第三步：用已有数据 + summary 重新渲染，不调用接口、不扣费
python scripts/topic_radar.py --from-json raw.json --summary summary.json \
    --output radar_with_ai.html --markdown radar_with_ai.md

AI 洞察 JSON 结构：

{
  "headline": "一句话结论（放在报告顶部 AI 结论区）",
  "verdict": "怎么读这张图（支持 **加粗**，会渲染成 HTML）",
  "picks": [
    {
      "word": "选题词",
      "tag": "最推荐 / 竞争最低 / 机会分第一，但要挑打法",
      "why": "机会原因：为什么值得做，必须带数据判据",
      "audience": "目标读者：谁来读、他们此刻的需求是什么",
      "angle": "推荐角度：用哪种内容形态切进去",
      "competition": "竞争程度：高/中/低，凭什么敢这么判断",
      "action": "具体怎么做：篇幅、形态、发布建议",
      "titles": ["标题1", "标题2", "标题3"],
      "outline": ["大纲1", "大纲2", "大纲3"]
    }
  ],
  "avoid": [
    {"word": "别碰的词", "reason": "为什么别碰"}
  ],
  "sequence": "推进顺序建议"
}

字段里有两个不能由 AI 编造：

• 证据充分度：由脚本根据实际采集的有效样本数自动渲染，不由 AI 生成
• 参考内容篇数：同样取自实际样本，避免 hallucination

参考示例：

• 关键词模式：out/ai_summary_习惯养成.json
• 账号模式：out/ai_summary_内容版图.json

账号模式的 AI 洞察重点不同：

• headline：给出各账号的「路子」对比（如行政渠道 vs 实操内容）
• verdict：解释阅读与互动的倒挂、主题差异、可借鉴的打法
• sequence：建议先补哪个缺口、先学哪个号、避免什么方向
• picks / avoid 可省略，也可用来推荐具体选题方向

趋势快照 --snapshot

关键词模式支持跨运行对比。每次真实采集（--from-json / --self-test 不会写入） 都会把该种子词的指标追加到快照文件，下次运行自动与上一次比较。

# 第一次：创建快照
python scripts/topic_radar.py --api-key "$KEY" --seed "习惯养成" \
    --snapshot radar_snap.json --output radar.html

# 一周后重跑：报告里每个词会显示「较 08-22：机会分 +5.2 · 阅读 −300」
python scripts/topic_radar.py --api-key "$KEY" --seed "习惯养成" \
    --snapshot radar_snap.json --output radar.html

快照文件是本地 JSON，按种子词分桶，每个词保留最近 24 次记录。 首次运行时趋势显示为「首次扫描，暂无趋势基准」——没有对比基准就不编造变化量。

Excel 导出 --excel

Excel 用标准库手写（zip + XML），不引入 openpyxl 等第三方依赖， 避免让使用者先装环境才能导出表格。

python scripts/topic_radar.py --api-key "$KEY" --seed "习惯养成" \
    --output radar.html --markdown radar.md --excel radar.xlsx

关键词模式 6 个 Sheet：

账号模式 6 个 Sheet：账号概览 / 主题标签 / 文章样本 / 内容缺口 / AI 洞察 / 费用明细。

费用明细只呈现真实累计值，不按预计调用数反推。

参数说明

展示结果

• 用 present_files 展示 HTML 报告。
• 关键词模式汇报：候选词数、扫描文章数、本次实际消费与余额、蓝海 Top5 及理由。
• 热点模式汇报：热搜条数、建议转译的词、不能碰的词。
• 账号模式汇报：账号数、每号主题与代表作、内容缺口数、本次实际消费与余额。

资源文件

scripts/topic_radar.py

主脚本，结构：

• Client — 全局限流（默认 4 req/s）+ 失败重试（复用 Idempotency-Key）+ 成本累计
• fetch_suggestions() — 接口 23，防御式取 word
• fetch_search() — 接口 14，过滤非文章链接，提取 source.title 与展示阅读值
• fetch_metrics() / fetch_report() — 接口 1 / 30，失败返回 None 不中断
• fetch_account_articles() — 接口 4 + 接口 1，抓账号历史文章与互动数据
• fetch_hot_words() — 接口 20，拉取实时热搜榜
• extract_topics() — 标题 n-gram + 最长公共串扩展的本地主题聚类
• compute_gaps() — 多账号主题交叉，输出「某号高频做、其他号没做」的内容缺口
• score_word() — 评分模型（见下）
• pick_angle() — 按互动结构给出切入角度建议
• build_html() / build_markdown() — 关键词模式报告
• build_account_html() / build_account_markdown() — 账号模式报告
• self_test_dataset() — 内置示例数据，--self-test 时不联网不扣费

评分模型（本地启发式，非平台官方指标）

必须向用户说明这是本地计算的排序参考，不是平台指标。

需求热度 = 100 × (0.35 × 词位次 + 0.40 × 互动热度 + 0.25 × 新鲜度)
    词位次    —— 该词在搜索联想结果中的相对位置，越靠前说明联想越常见（0~1）
    互动热度  —— 样本互动率基点（ratesBps.engagement）中位数，批内 log10 相对归一
    新鲜度    —— 近 90 天文章占样本比例

竞争度 = 100 × (0.50 × 头部水位 + 0.30 × 账号集中度 + 0.20 × 大号占比)
    头部水位 —— 样本阅读中位数，批内 log10 相对归一
    账号集中度 —— 1 − 不同账号数 / 样本数，越高说明被少数号把持
    大号占比 —— 阅读 ≥ 1 万 的样本占比

机会分 = 需求热度 − 竞争度（区间 −100 ~ +100，越高越蓝海）
四象限：以全体词的需求、竞争中位数为轴切分
    蓝海 = 高需求低竞争   主战场 = 高需求高竞争
    红海 = 低需求高竞争   冷淡区 = 低需求低竞争

机会分只说明「样本呈现出的形态」，不说明这个形态有多可信。
实测：同样的阅读量与互动率，2 篇和 12 篇样本会算出完全一样的机会分。

因此引入「证据充分度」与「可信分」：

- **证据充分度**：有效样本数 ≥6 篇为「高」、3–5 篇为「中」、<3 篇为「低」，单独显示，不混入机会分
- **可信分** = 机会分 ×（0.45 + 0.55 × 有效样本数 / 6）
  - 默认排序按可信分进行，避免 2 篇样本的词凭运气占据榜首
  - 机会分本身不做修改，保持「需求 − 竞争」的定义纯粹可审计

为什么用批内相对归一而不是绝对区间：实测同批次候选词的阅读中位数可能只有 4453187， 若硬编码「1000100000」这样的绝对区间，多数词会被压成 0，竞争度完全失去区分度。 不同领域（金融大号 vs 小众教育号）的阅读水位本身不可比，而用户要的答案是 「这批词里哪个相对更蓝海」，本质是批内排序问题，因此按本批次分布拉开到 [0.1, 0.9]。

防御机制：若批内极差不足 2 倍（log10 跨度 < 0.3），说明差异可能是噪声， 一律给中性值 0.5，避免把微小差异放大成虚假分差。

可信度处理（这是产品与裸数据的分界线）：

• readCapped=true 的样本只计数、不参与阅读中位数计算（真实值不可知，只是上限投影）
• readNum 为 null 的样本不参与数值计算
• 搜索结果里的「阅读 6.2万」是展示值，仅在精确整数缺失时显示，并标注「（展示值）」
• commentNum 为 null 时不参与切入角度判断（契约：null 与 0 含义不同）

切入角度判定（基于 ratesBps 子项占比，本地启发式）：

成本参考

成本一律按契约单价计算，不把任何账户级免单计入考量。

关键词模式

默认参数（10 个候选词 × 每词 8 篇 + 3 次深度采样）单次运行：

热点模式

• 拉榜一次：接口 20，¥0.10
• 转译后每分析一个词：按关键词模式单词成本约 ¥0.16（接口 14 1 次 + 接口 1 8 次）
• 追 3 个转译词约 ¥0.58

账号模式

按 --pages 2 --max-articles 20（每号 2 页共 40 篇，但最多取 20 篇有效）示例：

3 个对标号约 ¥1.10；若 --max-articles 40，每号约 ¥0.67，3 号约 ¥2.00。

账户实测附注（仅供参考，不得作为设计或预算依据）： 当前 API Key 下接口 1 的部分调用 consumption 为 0，实际可能低于上表。 这是该账户的计费特性，换账户或换时间都可能恢复收费。

省钱要点（按单价口径）

• 关键词模式：优化重点在 --per-word（接口 1 占 64%），8 篇是准确度与成本的平衡点； 降到 6 篇可省 ¥0.30，但样本量减少会削弱评分稳定性
• 不要无脑 --expand 2：词数从 11 涨到 26，接口 14 与接口 1 成本同步翻倍（约 ¥7）
• --deep 加深几乎不花钱（接口 3 只要 ¥0.008/次），是性价比极高的增强项， 默认 3 篇/词已经能让「建议篇幅」取到中位数；--deep 0 只能省 4%，不划算
• 账号模式：按页调接口 4 时把每页 limit 拉满 20，不要小分页
• 跑批前可用接口 9（账户余额，免费）先查一次余额

注意事项

• API Key 属敏感信息，勿写入前端代码、日志或公开仓库。
• 报告里不出现接口路径、内部服务名等实现细节。
• 评分是本地启发式模型，权重可调；结论应结合人工判断，不要当成精确决策依据。
• 搜索结果只反映该词当下的公开检索结果，不等于全平台真实需求量。
• 报告引用的文章链接来自公开搜索结果，引用时请遵守平台规则与版权要求。
• 若某个词样本数过少（如 <3），其分数置信度低，报告中会标注有效样本数，使用时留意。