ClawHub

Zsxq Fetch

API key required
Data & APIs

知识星球帖子抓取助手 — 自动抓取指定星球的最新帖子，支持全部/仅精华两种筛选模式，支持通过帖子链接或 ID 获取单条帖子详情，支持多星球配置，支持图片和文件附件自动下载到可配置目录。本 Skill 应在用户需要查看、汇总或检索知识星球内容时使用。

Install

openclaw skills install zsxq-post-fetch

知识星球帖子抓取助手

从指定知识星球抓取最新帖子内容，支持全部帖子与仅精华两种筛选模式，支持通过帖子链接或 ID 查看单条帖子详情，支持多星球配置管理，支持图片和文件附件自动下载到指定目录。所有输出使用中文。

认证与环境

必需环境变量

export ZSXQ_TOKEN="你的token值"

执行前必须检查 $ZSXQ_TOKEN 是否已设置。 未设置时提示：

请先设置知识星球 Token：export ZSXQ_TOKEN="your_token" 获取方式：浏览器打开 wx.zsxq.com → 登录 → F12 → Application → Cookies → 复制 zsxq_access_token 的值。

依赖安装

无第三方依赖，仅需 Node.js >= 18。首次使用运行一次即可：

bash {baseDir}/install.sh

配置文件

{baseDir}/config.json — 附件下载配置（新增）

{
  "attachment_dir": "~/.openclaw/workspace/zsxq",
  "download_attachments": true
}

字段说明：

  • attachment_dir：附件与 Markdown 保存根目录（附件按 group_id/YYYY-MM-DD/ 自动组织子目录）
  • download_attachments：是否开启自动下载（true | false）

也可通过环境变量覆盖附件与 Markdown 保存根目录：

export ZSXQ_ATTACHMENT_DIR="~/.openclaw/workspace/zsxq"

优先级：ZSXQ_ATTACHMENT_DIR → ATTACHMENT_DIR → config.json 的 attachment_dir。

{baseDir}/groups.json — 多星球配置

[
  {
    "group_id": "YOUR_GROUP_ID",
    "name": "星球名称",
    "scope": "digests",
    "max_topics": 20
  }
]

字段说明：

  • group_id：从星球 URL wx.zsxq.com/group/{group_id} 获取
  • name：星球名称（展示用）
  • scope：digests（仅精华）| all（全部），推荐 digests
  • max_topics：每个星球最多抓取的帖子数

Prompt 使用说明

当用户的请求与知识星球内容获取、汇总、检索、导出或附件下载有关时使用本 Skill。默认假设用户希望读取其 ZSXQ_TOKEN 对应账号有权限访问的内容，不要尝试绕过权限、猜测 token、读取仓库中的凭证文件或输出完整认证信息。

意图识别

  • 用户说“看看知识星球最新内容”“汇总星球更新”“最近有什么值得看”：读取 groups.json，按每个星球的 scope 和 max_topics 抓取并汇总。
  • 用户说“只看精华”“精华帖”“高价值内容”：优先使用 digests 或 scope=digests。
  • 用户说“全部帖子”“不要只看精华”：使用 topics <group_id> <count> all。
  • 用户给出 wx.zsxq.com/topic/... 链接或纯 topic_id：使用 topic <group_id> <topic_id_or_url> 查询单条帖子；如果缺少 group_id，先从 groups.json 查找，仍无法确定时询问用户。
  • 用户给出日期、时间范围或“本周/今天/昨天/某天”：换算成 YYYY-MM-DD 后使用 topics-by-date；相对日期要按当前环境日期解释。
  • 用户要求“保存”“导出 Markdown”“下载附件”“整理到本地”：在对应命令后追加 --markdown，并说明保存路径。
  • 用户不确定星球 ID、想看“我加入了哪些星球”：使用 groups 子命令，但要提醒该操作会暴露当前账号加入的星球列表。

推荐 Prompt 示例

用户可以这样提问：

帮我汇总知识星球最近 20 条精华帖，按星球分组。

抓取 YOUR_GROUP_ID 从 2026-06-01 到 2026-06-13 的帖子，导出 Markdown 并下载附件。

查看这个帖子详情：https://wx.zsxq.com/topic/82811454228448260

列出我当前账号加入的知识星球，帮我找到对应 group_id。

Agent 输出要求

  • 所有自然语言回复使用中文。
  • 汇总多个帖子时优先输出要点，而不是直接贴出超长原文；必要时保留帖子链接和 topic_id 方便追溯。
  • 明确标注抓取范围：星球名称或 group_id、all/digests、数量、日期范围、是否导出 Markdown。
  • 若写入 Markdown 或下载附件，输出实际保存路径和失败附件数量。
  • 不输出 ZSXQ_TOKEN、Cookie、临时下载签名 URL 或其他认证材料。
  • 单个星球、单个帖子或附件失败时，继续处理其他结果，并在最后列出失败项和原因。

数据抓取脚本 {baseDir}/fetch_topics.js

提供四个子命令：

1. 获取帖子列表

node {baseDir}/fetch_topics.js topics <group_id> [count] [scope]
  • group_id：星球 ID
  • count：帖子数，默认 500
  • scope：all（全部）| digests（精华），默认 all
  • 请求间隔 1 秒（翻页限速）
  • 帖子正文截取前 20000 字
  • 若 config.json 中 download_attachments 为 true，自动下载帖子中的图片和文件附件
  • 加 --markdown 时导出 Markdown，按日期保存到 <attachment_dir>/<group_id>/<YYYY-MM-DD>.md

输出格式（stdout）：

{
  "group_id": "123456",
  "scope": "digests",
  "count": 5,
  "topics": [
    {
      "topic_id": "789",
      "type": "talk",
      "title": "",
      "text": "帖子内容...",
      "create_time": "2026-03-01T10:30:00.000+0800",
      "owner": { "user_id": "111", "name": "作者" },
      "likes_count": 10,
      "comments_count": 5,
      "reading_count": 200,
      "readers_count": 180,
      "digested": true,
      "image_count": 2,
      "file_count": 1,
      "images": [
        {
          "image_id": "xxx",
          "type": "jpg",
          "large": { "url": "https://...", "width": 1200, "height": 800 },
          "thumbnail": { "url": "https://..." }
        }
      ],
      "files": [
        {
          "file_id": "xxx",
          "name": "report.pdf",
          "size": 1024000,
          "url": "https://..."
        }
      ],
      "attachments_local": [
        {
          "type": "image",
          "filename": "789_image_1.jpg",
          "path": "/Users/.../zsxq-attachments/123456/2026-03-01/789_image_1.jpg",
          "size": 125000
        }
      ]
    }
  ]
}

2. 获取精华帖（快捷方式）

node {baseDir}/fetch_topics.js digests <group_id> [count]

等价于 topics <group_id> [count] digests。 加 --markdown 时同样导出 Markdown。

3. 获取指定帖子详情

node {baseDir}/fetch_topics.js topic <group_id> <topic_id_or_url>

支持两种输入形式：

  • 纯帖子 ID：node fetch_topics.js topic YOUR_GROUP_ID 82811454228448260
  • 完整链接：node fetch_topics.js topic YOUR_GROUP_ID https://wx.zsxq.com/topic/82811454228448260

通过翻页帖子列表匹配目标 topic_id，最多搜索最近 300 条，文本截断上限 5000 字。 加 --markdown 时导出到该帖发布时间对应的日期 Markdown 文件。

4. 按日期范围抓取帖子（新增）

node {baseDir}/fetch_topics.js topics-by-date <group_id> <start_date> [end_date] [count]
  • start_date：开始日期，YYYY-MM-DD
  • end_date：结束日期，YYYY-MM-DD（可选，默认今天）
  • count：最多抓取数量（可选，默认不限制）
  • 帖子按时间倒序，遇到早于 start_date 的帖子自动停止翻页
  • 请求间隔 1 秒（翻页限速）
  • 支持附件自动下载（若 config.json 中 download_attachments 为 true）
  • 加 --markdown 时按帖子日期切分成多个 Markdown 文件

示例：

# 抓取 2026-06-01 到 2026-06-13 的所有帖子
node fetch_topics.js topics-by-date YOUR_GROUP_ID 2026-06-01 2026-06-13

# 只抓取 2026-06-01 当天的帖子（最多 50 条）
node fetch_topics.js topics-by-date YOUR_GROUP_ID 2026-06-01 2026-06-01 50

# 抓取并导出 Markdown
node fetch_topics.js topics-by-date YOUR_GROUP_ID 2026-06-01 2026-06-13 50 --markdown

输出格式：

{
  "group_id": "YOUR_GROUP_ID",
  "date_range": { "start": "2026-06-01", "end": "2026-06-13" },
  "count": 15,
  "topics": [ ... ]
}

5. 列出已加入的星球

node {baseDir}/fetch_topics.js groups

返回当前账号已加入的所有星球信息（group_id、名称、成员数、帖子数等）。

附件下载行为

  • 图片和文件按 attachment_dir/group_id/YYYY-MM-DD/ 目录结构存放
  • 附件文件名会加 topic_id 前缀，例如 789_image_1.jpg、789_report.pdf，避免同一天不同帖子附件重名
  • 文件附件优先使用已有 download_url/url；若只有 file_id，先请求 /v2/files/{file_id}/download_url 获取临时签名链接后再下载
  • 已存在的文件自动跳过（幂等）
  • 下载限速 500ms/文件（避免触发限流）
  • 下载失败记录到 attachments_local 的 error 字段
  • 未配置 config.json 或 download_attachments 为 false 时，不下载附件，保持 v1.0.0 兼容行为

Markdown 导出行为

  • 通过 --markdown 显式开启，默认仍输出 JSON 到 stdout
  • Markdown 按帖子日期切分，保存到 <attachment_dir>/<group_id>/<YYYY-MM-DD>.md
  • 已下载图片使用 ![filename](YYYY-MM-DD/filename) 相对路径引用
  • 已下载文件使用 [filename](YYYY-MM-DD/filename) 相对路径引用
  • 未下载但有远程 URL 的附件会回退为远程 URL 引用
  • JSON 结果中会增加 markdown_paths 字段，列出本次写入的 Markdown 文件

执行流程

场景一：汇总多个星球最新帖子

步骤 1：检查环境

  • 验证 $ZSXQ_TOKEN 已设置
  • 读取 {baseDir}/config.json（附件下载配置）
  • 读取 {baseDir}/groups.json（星球配置）

步骤 2：抓取帖子

对 groups.json 中每个星球，按配置的 scope 和 max_topics 执行：

node {baseDir}/fetch_topics.js topics <group_id> <max_topics> <scope>

多个星球依次抓取，间隔 1.5 秒。

步骤 3：输出摘要

按星球分组，每条帖子输出：

  • 作者、发布时间
  • 内容摘要（核心观点 1-2 句）
  • 互动数据（阅读 / 点赞 / 评论）
  • 帖子链接：https://wx.zsxq.com/topic/{topic_id}
  • 附件信息（图片数、文件数、本地保存路径）

场景二：查看指定帖子详情

当用户提供帖子链接或 ID 时，直接执行：

node {baseDir}/fetch_topics.js topic <group_id> <topic_id_or_url>

输出帖子完整内容，包括作者、时间、正文、互动数据、附件列表及本地保存路径。

场景三：查找可用星球

当用户不确定 group_id 时，执行：

ZSXQ_TOKEN=xxx node {baseDir}/fetch_topics.js groups

列出账号已加入的所有星球供用户选择。

错误处理

错误场景检测方式处理
Token 未设置$ZSXQ_TOKEN 为空提示用户设置并说明获取方法
Token 过期HTTP 401提示重新获取 token
未加入星球HTTP 403提示用户需先加入该星球
API 限流HTTP 429自动重试（指数退避 2s/4s/8s）
非官方客户端风控API 错误码 1059脚本已携带浏览器化请求头；若仍触发，提示可能需要真实浏览器上下文（如 Playwright）请求
星球不存在API 返回 succeeded=false跳过该星球，报告中标注
帖子不存在API 返回 succeeded=false返回 topic_not_found 错误
附件下载失败文件写入/网络错误记录到 attachments_local.error 字段，不中断主流程

原则：部分失败不中断整体流程。 单个星球失败或附件下载失败仍处理其他星球/帖子。

请求头与 1059 缓解

API 和附件下载请求统一使用接近 Chrome 浏览器的请求头，包括 sec-ch-ua、Sec-Fetch-*、Accept-Language、Origin、Referer、动态 X-Timestamp、X-Request-Id 等。

这不能保证完全消除 1059。若知识星球继续返回非官方客户端风控错误，说明服务端可能还检查浏览器/TLS 指纹或网页端动态参数，应升级为真实浏览器上下文请求方案。

详细 API 参考

如需了解 API 完整参数、响应结构、错误码等，参阅 {baseDir}/references/api-reference.md。

More in Data & APIs