热点监测

版本：v0.1.0 · 作者：小风、CoderPig、Awen

面向新媒体运营、内容营销和市场执行人员，常在选题会、日报会前用：给一个关键词，批量抓取微信公众号和微信视频号上的匹配内容及传播数据，交付一份按渠道分 Sheet、每行带原文链接、可直接排序透视的 Excel。

它替代的是「在微信里逐条搜索、点开、抄数据到表格」：抓 50 条人工要 1~2 小时，还容易抄错数字、漏复制链接，等数据整理好热点窗口也过了。

典型用法：选题会前查「AI教育」最近 7 天最热的公众号文章和视频号视频，拿到表格直接按阅读量、点赞排序挑选题。

能做：按关键词 + 渠道 + 时间范围 + 排序 + 条数筛选内容。阅读、点赞、分享、爱心、评论数固定带上，不能按列裁剪。可选附带每条内容的热评，直接看到真实用户反馈（另计费，需用户确认）。
不做：公众号 / 视频号以外的平台（抖音、小红书、微博等）；指定账号的历史数据分析（只做关键词搜索）；数据解读、趋势图表与分析报告（只交付原始数据表）；定时监控与推送；评论情感分析与观点归纳。

脚本 scripts/hot_monitor.py 负责向服务端询问预估消耗、创建任务、轮询、保存响应 JSON，并在本地生成 xlsx。接口契约见 references/api.md，列与字段见 references/field-mapping.md。

示例命令使用 python3。Windows 上如果没有 python3 这个命令，改用 python。

执行流程

取 API Key：读 config.json / 环境变量，缺失时引导获取。见「鉴权」。
收参数：关键词、渠道必问，其余给默认，用中文一次性问清。默认项不能只报默认值，每一项都要把可选项一并列出，用户开始任务前才知道能改什么。用户要评论内容时，先说明另计费。见「信息收集」。
确认：用最终参数跑 --quote，把服务端返回的预估消耗 ===POINTS_MAX=== 和筛选条件一起请用户确认。用户确认后才创建。用户改了参数要重新询价再确认。见「确认」。
创建并轮询：同样的参数去掉 --quote 再跑一次。进度在 stderr，只在状态变化时打一行，没有百分比。等待期间可给用户一句话进度。轮询超时（退出码 5）时自己用 --task-id 续传，不要新建。
交付回执：把 ===XLSX_PATH=== 的文件交给用户，附各渠道条数和本次实际扣点。见「结果回执」。
异常：按「退出码处理」处理。已有 ===TASK_ID=== 时一律续传或重试，不要新建。

续传（--task-id）和重试（--task-id --retry）针对的是已经创建过的任务，跳过第 2～3 步。

鉴权

Token 取「技能目录」（SKILL.md 所在目录）下 config.json 的 LY_API_KEY 字段，回退环境变量 LY_API_KEY。请求头 Authorization: <api_key>（裸 key，不带 Bearer）。没有 config.json 时，按同目录 config.json.example 新建一份，只写入密钥。config.json 形如：

{ "LY_API_KEY": "你的密钥" }

config.json 只留在本机，不要整份覆盖，也不要提交到仓库。文件不是合法 JSON 时先修好，退出码 3。

运行前先确认 key：

检查是否已有 key：读 config.json 的 LY_API_KEY 是否非空；无则看环境变量 LY_API_KEY。任一有值即就绪。
缺失则引导用户获取：例如

还没有配置 API Key。请前往 https://claw.lingyishuke.com/webapps/01claw-auth/index.html?source=workbuddy 获取后直接发给我，我写入配置后继续。收到后写入 config.json 的 LY_API_KEY 字段（保留其它内容）再继续。
鉴权失败（退出码 8）：key 失效或过期，重新获取并覆盖写 config.json 后重试，不反复用同一失效 key。
SSL 错误（CERTIFICATE_VERIFY_FAILED 等）：只有环境变量 LY_SKIP_SSL_VERIFY 的值正好是 1，或用户明确要求时加上 --insecure，才会跳过证书校验。设成 0 仍然校验。不要默认加 --insecure。

信息收集

关键词和渠道必问，其余缺省给默认，一次性问清，只问一轮。枚举字段一律用中文向用户展示，内部再映射回英文 value 传脚本。

缺关键词或渠道时，例如：

请告诉我要监测的关键词（如：AI教育），以及渠道：公众号、视频号，可多选。其他项都有默认，不需要改就说「用默认」：

🕐 时间范围：默认最近 7 天（可选：近 1 天 / 近 7 天 / 近半年）

🔁 排序：默认最新（按发布时间倒序；可选：最热，按互动热度倒序）

🔢 每渠道条数：默认 50 条（可选：50 / 100 / 200）

💬 评论内容：默认不抓（要抓另计费，公众号 / 视频号可分开选）

先看可选项：

python3 scripts/hot_monitor.py --show-options

| 字段 | 必填 | 说明（中文为主） | | ------------------ | -- | --------------------------------------------------------------------------------------------------------------------------- | | keyword | 是 | 关键词，单个词，1–30 个字符。超长时请用户改写，不要自行截断 | | channels | 是 | 公众号(gh) / 视频号(chs)，可多选 | | time_range | 否 | 近1天(1d) / 近7天(7d，默认) / 近半年(180d) | | sort | 否 | 最新(latest，按发布时间倒序，默认) / 最热(hot，按互动热度倒序) | | count | 否 | 每个渠道的条数：50（默认）/ 100 / 200。不在档位内时请用户在这三档中重选，不要就近取 | | include_comments | 否 | 要拉评论内容的渠道，公众号(gh) / 视频号(chs)，可只选其中一个，必须是本次已选渠道。默认不拉。这是唯一可选项。与评论数不是同一件事。每条最多 20 条热评 |

向用户列默认项时，每一项必须同时列出全部可选项（可选项以 --show-options 为准）。用户看不到可选项，就无法在开始前判断要不要改——只报默认值等于替用户做了决定。可选项枚举：时间范围=近 1 天 / 近 7 天（默认）/ 近半年；排序=最新（默认）/ 最热；条数=50（默认）/ 100 / 200。

指标列固定输出，不要问用户要哪些列，也不要传字段选择参数。公众号固定有名称、标题、文章链接、发布时间、阅读量、点赞数、分享数、爱心数、评论数。视频号固定有序号、标题、视频号、认证、发布时间、时长、点赞数、分享数、爱心数、评论数、视频链接。没有「互动数」这一列。用户要求去掉某一列时，说明表格会带上全部指标，只有评论内容可以不要。

评论内容默认不采集，公众号和视频号分开决定。评论数是普通指标，默认会要，不另计评论内容的费用。用户提到要评论、热评、用户反馈时，先说明再问要哪些渠道，然后把渠道写进 --include-comments：只拉列出的渠道，每条内容最多带 20 条热评（按点赞从高到低），格式是「昵称：内容」。例如：

抓取评论内容会额外扣点，公众号和视频号可以分开选。每条内容最多附 20 条热评。要抓哪些渠道的评论？也可以都不要，只抓基础数据。

只选了一个渠道，用户说要评论：--include-comments 就写这个渠道，不必再问。
选了两个渠道，用户没说要哪边：问清楚再传。不要默认两边都拉。
只要公众号：--include-comments gh。只要视频号：--include-comments chs。两边都要：--include-comments gh,chs。
用户拒绝某个渠道时，去掉该渠道的评论，其余按已确认的方式继续，不要因此取消整个任务。

确认

本 skill 调用的是远端付费 API。采集结束后按成功拿到的条数结算。把预估消耗和筛选条件放在同一次确认里，用户同意后才创建。

用最终参数加 --quote（把同样的参数交给服务端，由接口返回这次的预估消耗。不查余额、不建任务、不扣点，也不返回单价）：

python3 scripts/hot_monitor.py --quote \
  --keyword "AI教育" --channels gh,chs \
  --time-range 7d --sort hot --count 50 \
  --include-comments gh

===POINTS_MAX=== 是服务端返回的预估消耗。只把这个总数告诉用户。不要拆成每条单价，也不要说明各部分怎么计。脚本没有本地计价，不要自己另算一套。

拿到数字后，用中文回显筛选条件并请用户确认，例如：

即将监测：关键词「AI教育」，公众号 + 视频号，最近 7 天，按最热，每个渠道 50 条。公众号附评论内容，视频号不含评论内容。按这个监测量，预估消耗 {POINTS_MAX} 点。实际按成功拿到的条数结算，通常不会高于这个数。是否继续？

回显时写明每个已选渠道要不要评论内容。两边都不要时，说「不含评论内容」。

用户确认后，用完全相同的参数去掉 --quote 创建，然后轮询到终态再交付。用户未确认前不要发起创建。
用户改了任何参数（关键词、渠道、时间、条数、评论内容等），重新跑 --quote 再确认。
预估接口失败（退出码 10 或 11）时不要创建。告诉用户暂时拿不到预估消耗，稍后重试 --quote。
创建或重试若返回余额不足（退出码 4），这时再告诉用户点数不够，建议减小条数档位、去掉评论内容或充值。确认这一步不查余额。

运行方式

创建（确认后）：公众号 + 视频号，近 7 天，各 50 条，最新：

python3 scripts/hot_monitor.py \
  --keyword "关键词" --channels gh,chs \
  --time-range 7d --sort latest --count 50

只要公众号评论时加上 --include-comments gh；两个渠道都要评论时用 --include-comments gh,chs。只要公众号内容时 --channels gh。

续传（不重新创建）：

python3 scripts/hot_monitor.py --task-id "<task_id>"

重跑失败渠道，或补采缺失的互动数据：

python3 scripts/hot_monitor.py --task-id "<task_id>" --retry

--retry 会先查询任务：还在执行就继续等；已经成功且互动齐全就直接交付；失败、部分失败或有内容缺互动时才提交重试。stdout 的 ===RETRY_SUBMITTED=== 为 1 表示这次提交了重试，0 表示没有提交。

可选：--xlsx-out ./自定义.xlsx、--response-out、--poll-interval、--poll-timeout（默认 300 秒）。没有按列筛选的参数。

响应 JSON 默认写到系统临时目录的 hot_monitor_response.json，每次轮询都会覆盖。默认表格文件名：热点监测-{关键词}-{渠道}-{yyyyMMdd}.xlsx，渠道写成「公众号」「视频号」或「公众号+视频号」，关键词里的空白和文件名非法字符替换为 _。同名文件已存在时，在扩展名前加 _1、_2。文件落在当前目录，除非传了 --xlsx-out。某格没有值就留空，不填 0。评论内容单元格自动换行。

结果回执

stdout 各块的含义：

===TASK_ID===：任务编号，续传和重试都靠它。
===XLSX_PATH===：生成的表格。把这个文件交给用户，不要在对话里改表格内容。
===ROW_COUNTS===：各渠道条数。
===CHANNEL_STATUS===：各渠道状态（成功 / 失败），冒号后是原因或提示。
===POINTS_USED===：这一轮实际扣点，对应接口字段 round_points，扣成功才有值。为空时说「实际扣点以账户侧扣点记录为准」，不要编数字，也不要说本次未扣点。不要把接口里的 total_points（任务各轮累计）说成本次。

成功（退出码 0）

任务已完成：公众号 50 条、视频号 42 条（最近 7 天，按最热）。本次实际扣点 {POINTS_USED} 点。表格在 {XLSX_PATH}。

某渠道条数少于所选档位：如实说明，例如「该条件下视频号实际抓到 42 条（未到 50 上限），已全部输出」，这不是错误。
某渠道 0 条：表格照常生成（保留表头），并给出建议，例如「关键词「xx」在公众号最近 7 天内没有抓到内容。可以换个关键词，或把时间范围放宽到最近半年」。
互动数据没取全：===CHANNEL_STATUS=== 里出现「有 N 条没有取到互动数据」时，告诉用户这些行的阅读、点赞等是空的，问是否用 --task-id --retry 补采。补采只补这些内容的互动，不重新搜索。补采会另行扣点，需用户同意。不要拆开说明各部分怎么计。
没有新扣点的交付：下面两种情况，===POINTS_USED=== 是之前那一轮的扣点，不是这次新扣的：
- --retry 时 ===RETRY_SUBMITTED=== 为 0（任务本来就已完成）；
- --task-id 续传的任务，本对话里已经回执过扣点。
这时说「该任务此前已扣 {N} 点，这次没有新扣点」。

部分成功（退出码 13）

Excel 已经生成，成功渠道照常交付。告诉用户哪个渠道失败（看 ===CHANNEL_STATUS===），实际扣点以 ===POINTS_USED=== 为准，并询问是否只重跑失败渠道，例如：

公众号数据已生成（50 条）；视频号这次抓取失败。是否单独重试视频号？重试成功后会按视频号这次的实际采集扣点，已成功的公众号不会再采集，也不会重复扣点。

用户同意后执行 --task-id --retry。

失败（退出码 6）

任务没有成功行。实际扣点以 ===POINTS_USED=== 为准，没有这个数就说以账户侧扣点记录为准。对用户说可以稍后用 --task-id --retry 重试，或换个关键词。重试的渠道成功后会按实际采集扣点。不要把后端原始错误码整段甩给用户。

轮询超时（退出码 5）

这轮等待结束，任务还在跑，服务端单个任务最长可跑约 25 分钟。条数多、带评论时常见，不是失败。

先告诉用户「任务还在采集，继续等待」，然后自己用 --task-id 续传，最多再续 2 次。
仍未结束时，把 ===TASK_ID=== 交给用户，说明稍后可以让你用这个编号继续取结果。
不要重新创建，否则同一关键词会采集并扣点两次。完成前 ===POINTS_USED=== 可能还是空的；续传看到终态后再按上面的情况回执。

退出码处理

| 码 | 含义 | 处理 | | -- | ---------- | -------------------------------------------------------------------------------------------------------------- | | 0 | 成功 | 按「结果回执 · 成功」交付。--quote 返回 0 表示服务端已给出预估消耗，进入确认。 | | 1 | 未分类的异常 | 把 stderr 里的短原因告诉用户。已有 ===TASK_ID=== 时用 --task-id 续传，不要新建。 | | 2 | 缺 API Key | 引导去 https://claw.lingyishuke.com/webapps/01claw-auth/index.html?source=workbuddy 取 key，写入 config.json 后重试。 | | 3 | 参数非法 | 按 stderr 修正关键词、渠道、时间、排序或条数后重试。--count abc 这类类型错误也是 3。config.json 不是合法 JSON 时同样是 3，先修好文件。 | | 4 | 余额不足 | 创建或重试时服务端拒绝。告知点数不够，建议减小条数档位、去掉评论内容后重新确认，或前往充值。确认步骤本身不会因为余额退出。 | | 5 | 轮询超时 | 按「结果回执 · 轮询超时」自己续传，不要重新创建。 | | 6 | 任务失败 | 按「结果回执 · 失败」处理。 | | 8 | 401 key 无效 | 重新获取并覆盖 config.json 后重试。 | | 9 | 404 | 任务不存在，或 key 与任务不匹配。先问用户是否用当前 key 重新创建。重新创建是一笔新任务，要重新询价并确认。 | | 10 | 其他 4xx | 按 stderr 的 message 修正。创建返回「当前监测任务较多」时稍后重试，不要连着新建，创建未成功则未扣点。重试返回「任务还在执行」时改用 --task-id 续传。 | | 11 | 5xx 或网络失败 | 服务端 5xx 的具体文案不会透传，只说「服务暂时不可用」。分三种情况：①已有 ===TASK_ID===：用 --task-id 续传，不要新建。②--retry 失败：可以直接再跑一次 --retry，脚本会先查询，重试已生效时只会继续等待。③创建阶段失败且没有 ===TASK_ID===：任务可能建了也可能没建，先告诉用户，等用户同意后再创建。同一账号、同一组参数如果还有进行中的任务，服务端会返回那一笔，不会再采集一次；上一笔已经完成或失败时才会新建。 | | 13 | 部分渠道失败 | 按「结果回执 · 部分成功」处理。 | | 22 | 写盘失败 | 检查输出路径和权限。响应 JSON 仍在 --response-out（或默认临时文件）。 |

注意事项

数据口径：阅读量、点赞、爱心等以数据源为准，可能与微信客户端展示存在差异。公众号「爱心」对应在看，视频号「爱心」对应拇指赞。
稳定性：数据来自微信生态实时搜索，受平台风控影响可能出现个别渠道失败或字段缺失，不承诺每次 100% 成功；失败时如实告知并引导重试，不要编造数据。
时效性：结果反映抓取当时的数据，传播数据会随时间变化。
对话用中文，参数用英文：与用户沟通只说公众号、视频号、最新、最热、最近 7 天等中文名，不暴露 gh、latest 这类内部值；传给脚本用 --show-options 里的英文 value。
续传优先于重建：有 ===TASK_ID=== 就续传或重试，避免同一关键词采集两次。
评论内容按渠道关闭：没有用户明确同意，不加 --include-comments。同意时只传用户点名的渠道，不要把另一个渠道一并打开。评论数默认包含。
引用 reference 用相对于 SKILL.md 的路径。
表格以脚本写出的 xlsx 为准，agent 不要手改单元格。