lumiorchid-alt/weibo-scrape

---

name: weibo description: Use when the user wants to fetch Weibo (微博) content — a specific user's posts, a single post with comments, search posts by keyword, a user profile, or all comments of a post. Images can optionally be downloaded and OCR'd to text locally.

weibo — 微博抓取

通过本地 weibo CLI 抓微博。每条命令输出单个三态 JSON(status: ok|partial|error),直接读 stdout。

前置检查(首次使用或命令报错时)

第一次用本 skill、或 weibo 命令找不到 / 抓取异常时,先跑一次自检:

weibo doctor

• 返回 all_ok: true → 直接用下面的命令。
• 返回 all_ok: false(或提示 command not found: weibo)→ 按各 check 的 hint 修;绝大多数情况是回仓库根目录跑 ./install.sh(它会装依赖 + Chromium headless shell + OCR 模型,并把 skill 装到 ~/.claude/skills/weibo)。修好再继续。

正常使用时无需每次自检——仅在首次或遇到 DependencyMissing / command not found 时检查。

命令

命令	用途
weibo user <uid>	用户资料(uid 是数字 uid)
weibo user-posts <uid> [--pages N] [--with-comments] [--no-images]	某用户的微博
weibo post <bid> [--comments] [--no-article] [--no-images]	单条微博(bid 是 base62 短码);文章帖自动补全正文
weibo article <id>	直接按文章 id 或 weibo.com/ttarticle/p/show?id=<id> URL 拉正文
weibo comments <post_id> [--max-pages N]	某微博全部评论(翻页;post_id 用数字 id)
weibo search <query> [--filter <f>] [--pages N] [--no-images]	关键词搜索微博
weibo search-users <name> [--verified] [--pages N]	按昵称搜真人账号;--verified 只留认证(蓝/金 V)号
weibo doctor	环境自检
weibo clean [--all]	清理媒体缓存:无参=仅超上限(默认 256MB)时 LRU 裁剪(未超则零删除);--all=全清
weibo config get / weibo config set cache-limit <size>	看/改媒体缓存上限(如 512MB/1GB);默认 256MB,持久化到 config.json

全局开关(可前置或后置于子命令):--detail compact|full、--quiet(静音 OCR 的 stderr 加载日志,不影响 stdout 的 JSON)。

--detail compact|full(默认 compact)对所有返回帖/评论/用户的命令一致生效:

• compact(默认):精简集,够日常内容任务用。
• full:在 compact 上补元数据/调试字段——帖的 source(发布客户端)、图片的 path(本地文件路径)/has_text(可由 text_coverage 推)、评论的 created_at_raw、用户的扩展资料(简介/性别/地区等)。retweeted/嵌套评论随父档同级。
• 想任取字段投影(--fields a,b,c)见 v2,本版未做。

用法要点

• 图片默认下载+本地 OCR。 输出里图片带 ocr_text/text_coverage;先读 ocr_text,仅当 text_coverage 为 none/low 且确需看像素时,再加 --detail full 取每图 path、用 Read 工具加载该本地图片(compact 不含 path/has_text)。

  • 加 --no-images 关闭下载/OCR(宽泛快扫、或深翻多页在乎延迟时);此时仍输出 media.image_count + 每图 url,可对单帖再 --images 补抓。
  • 务必保持默认开的场景:单帖深读、正文可能在图里、存档语料、短正文。

• 文章全文(头条文章):post 命中文章帖时自动多一跳补 article.content(剥成纯文,约 1.2 万字/篇——预算上下文,快扫用 --no-article 只取 {id, title})。--detail full 下 article.is_paid 为真表示付费墙(compact 档不含该字段),正文可能被截断。也可 weibo article <id> 直接拉某篇文章。仅最外层帖补全;转发里的内层文章不补。文章那一跳失败 → partial + warnings:[{type:"article_fetch_failed"}],主帖仍返回。

• 搜索精筛 search --filter <f>(默认 comprehensive)——按"何时用"选值:

  --filter	含义	何时用
  comprehensive(默认)	综合排序(相关性+热度+时间混合)	不确定时的安全默认
  time	按时间倒序、实时	要最新动态、追踪事件进展
  hot	按热度(高互动)	找最火/出圈/高转评赞
  original	仅原创(排除转发)	不要转发噪音
  video	仅视频帖	只要视频
  pic	仅图片帖	只要带图
  media	type=2 杂项 tab——实测既不保证带图/视频,也不限媒体机构号(含非认证个人号),与 comprehensive 高度重叠	基本别用;要图/视频用 pic/video

  单选互斥:容器只有一个 tab 槽,--filter 不可组合(对齐 app 单 tab 模型)。要"原创且带图"这类复合条件 → 选主条件当 --filter(如 original),再用输出里 media.image_count(>0=带图)等字段自己客户端二次筛。注:结果按所选 tab 的口径返回(非保证严格排序);每帖带 counts.{reposts,comments,attitudes}(转/评/赞),需自定义排序可据此客户端再排。

• search-users --verified 在抓取后过滤,与 --pages 组合时结果数可能远少于页容量(先抓 N 页再筛认证号)。

• 话题流:无独立命令,直接把 #话题# 当 query 搜——weibo search "#人工智能#" --filter time(配 time 看实时流)。

• 列表长文会截断:search/user-posts 返回的长文帖正文是节选(实测约 200 字 vs 全文 500+),不是完整全文。帖上 is_long_text: true 标出哪些被截断。要某帖全文 → 用该帖的 bid(列表每项都带 id 和 bid,post 收 bid)单独 weibo post <bid>(每条一次额外请求);本版无批量展开开关。

• 无时间增量/区间:无原生时间游标,只能 --pages 从最新页往回翻;没有 --since,别承诺增量同步。按日期范围精筛需登录态,本版不支持。

• 响应信封形状: 列表类命令(user-posts/search/search-users/comments)数据在 data.posts/data.users/data.comments(数组);单条命令包在 data 下的单数键——post 在 data.post,article 在 data.article,user 直接在 data。别拿列表的 data.posts[] 解析路径套单条 post(会取到空)。

• 评论数有访客上限: 帖的 counts.comments 是总数,但访客态 comments 翻页通常只拿得到前 ~16–20 条,len(comments) ≠ counts.comments(非 bug,访客天花板)。

• --with-comments 串行慢,默认不展开;需要时显式加。

• status 必看: error 表示抓取失败(不是"没结果")。partial 表示主数据可用但有需留意的 warnings,分两类:① 部分子项(如某些图)下载/OCR 失败;② 空结果——user-posts/comments/search 没抓到任何条目时返回 partial + warnings:[{type:"empty_result"}](底层对"真没数据"与"id 错/被删/被限流"不可区分,故不武断报 error,也不静默当 ok)。因此空结果是 partial 而非 ok;ok 仅用于确有数据返回(user/search-users 例外:它们空结果仍可能为 ok)。读到 empty_result 时:若确信该 id/词应有数据,优先怀疑 id 写错/内容被删/被限流。

• 首次运行会自动用 Playwright 抓访客 cookie(~4.8s),之后复用磁盘 cookie(~0.4s)。若报 DependencyMissing,先跑 weibo doctor 按 hint 修。

• 转发微博的内容/图片在 retweeted 字段下。

• 视频:media.video_url 给单条最低清晰度 stream_url 直链(带 Expires/ssig 时效),media.has_video 标是否有视频;v1 只暴露直链、不下载视频内容。

• 评论时间不可靠: comments 的 created_at 异构——近期评论是相对串("刚刚"/"3分钟前"),较老的是 MM-DD(无年份),不能用于绝对时序(--detail full 另带同值的 created_at_raw,仅调试用)。

• 列表项含数字 id: search/user-posts 返回的每条都带非空数字 id,可直接 weibo comments <id>,无需先 weibo post;也用作去重主键。(B4)

• 跨页去重: search --pages N 跨页约 ~16% 重复,按 bid 去重。(E1)

• 列表 bid 可能已不可达: 列表命中的 bid 在详情抓取时可能已被删/限流,此时返回 error 三态——属正常,别误判为"没数据"。(E2)