shield_lock
JinDaGe
← Back to skills
extension
Category: Data & AnalyticsAPI key required

Zsxq Post Fetch

知识星球帖子抓取助手 — 默认通过官方 zsxq-cli OAuth/Keychain 登录态抓取用户已授权账号可访问的帖子，支持全部/精华筛选、关键词搜索、单帖详情、日期范围导出、多星球配置、Markdown 和附件整理。本 Skill 应在用户需要查看、汇总、检索或导出知识星球内容时使用。

personAuthor: wufulinhubclawhub
open_in_newRepositorydownloadDownload package

知识星球帖子抓取助手

从指定知识星球抓取最新帖子内容，支持全部帖子、精华过滤、关键词搜索、单帖详情、日期范围、Markdown 导出和附件下载。所有自然语言输出使用中文。

默认后端是官方 zsxq-cli，认证由 zsxq-cli auth login 完成。旧的 ZSXQ_TOKEN + 私有 HTTP API 仅作为显式 legacy fallback。

认证与环境

默认官方 CLI 认证

执行前优先检查：

zsxq-cli auth status

如果未登录，提示用户运行：

zsxq-cli auth login

不要读取、导出或展示官方 CLI 存入 Keychain 的 token。

legacy HTTP fallback

只有当用户明确要求 legacy HTTP，或环境/配置已设置以下任一项时，才使用旧 HTTP 路径：

export ZSXQ_BACKEND=http

{
  "backend": "http"
}

该路径才需要：

export ZSXQ_TOKEN="your_zsxq_access_token"

不要把真实 ZSXQ_TOKEN 写入仓库文件、聊天回复、日志或发布包。

依赖安装

首次使用运行：

bash {baseDir}/install.sh

安装脚本会检测 Node.js 和 zsxq-cli；缺失 zsxq-cli 时会尝试 npm install -g zsxq-cli。安装脚本不会自动登录。

配置文件

{baseDir}/config.json

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

字段说明：

  • backend：默认 cli；只有显式设置为 http 才使用 legacy HTTP fallback
  • attachment_dir：附件与 Markdown 保存根目录，按 group_id/YYYY-MM-DD/ 组织
  • download_attachments：是否开启自动下载

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

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：星球 ID
  • name：星球名称，展示用
  • scope：digests 或 all
  • max_topics：每个星球最多抓取的帖子数

Prompt 使用说明

当用户请求知识星球内容获取、汇总、检索、导出或附件下载时使用本 Skill。默认假设用户希望通过官方 zsxq-cli 读取其已授权账号可访问的内容。

不要尝试绕过权限、伪造官方客户端、伪造 TLS/header 指纹、猜测 token、读取仓库中的凭证文件或输出完整认证信息。

意图识别

  • “看看知识星球最新内容”“汇总星球更新”“最近有什么值得看”：读取 groups.json，按每个星球的 scope 和 max_topics 抓取并汇总。
  • “只看精华”“精华帖”“高价值内容”：优先使用 digests 或 topics <group_id> <count> digests。
  • “全部帖子”“不要只看精华”：使用 topics <group_id> <count> all。
  • 用户要求“搜索某个关键词”“找包含某主题的帖子”“下载某关键词相关附件”：使用 search <group_id> <keyword> [count] --markdown --download-attachments；若缺少 group_id，先从 groups.json 查找，仍无法确定时询问用户。
  • 用户给出 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 子命令，并提醒该操作会暴露当前账号加入的星球列表。
  • 用户明确要求旧 Cookie 方式或需要验证 legacy 行为：设置 ZSXQ_BACKEND=http 后再使用命令，并检查 ZSXQ_TOKEN 是否已设置。

推荐 Prompt 示例

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

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

搜索 YOUR_GROUP_ID 里和 SpaceX IPO 相关的帖子，导出 Markdown 并下载附件。

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

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

Agent 输出要求

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

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

1. 获取帖子列表

node {baseDir}/fetch_topics.js topics <group_id> [count] [scope] [--markdown]
  • 默认后端命令：zsxq-cli group +topics --group-id <group_id> --limit <1-30> --json
  • scope：all 或 digests，默认 all
  • 文本截断上限 20000 字
  • 若 download_attachments 为 true，自动整理图片和文件附件
  • 加 --markdown 时导出 Markdown 到 <attachment_dir>/<group_id>/<YYYY-MM-DD>.md

2. 获取精华帖

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

CLI 后端会按 digested / is_digested 字段过滤。如果官方 CLI 输出不包含精华标记，返回 digests_unavailable_from_cli。

3. 按关键词搜索并下载

node {baseDir}/fetch_topics.js search <group_id> <keyword> [count] [--markdown] [--download-attachments]
  • 默认通过官方 MCP tool search_topics 搜索主题：
zsxq-cli api call search_topics --params '{"group_id":"123456","query":"SpaceX IPO"}' --format json
  • 当前官方 CLI 未文档化 search_topics 的分页参数，count 只作为客户端截断
  • 搜索命中后使用 topic +detail 补全正文、图片和文件字段
  • --download-attachments 会强制下载匹配帖子的附件
  • --markdown 会按日期写入 Markdown

4. 获取指定帖子详情

node {baseDir}/fetch_topics.js topic <group_id> <topic_id_or_url> [--markdown]

支持纯帖子 ID 或完整链接。保留 group_id 参数用于兼容旧接口；CLI 后端实际执行：

zsxq-cli topic +detail --topic-id <topic_id> --json

5. 按日期范围抓取帖子

node {baseDir}/fetch_topics.js topics-by-date <group_id> <start_date> [end_date] [count] [--markdown]
  • 日期格式：YYYY-MM-DD
  • 帖子按时间倒序，遇到早于 start_date 的帖子自动停止翻页
  • 支持附件自动下载和 Markdown 导出

6. 列出已加入的星球

node {baseDir}/fetch_topics.js groups

默认执行：

zsxq-cli group +list --json --limit 200 --scope all

返回当前账号已加入的所有星球信息。

附件下载行为

  • 图片和文件按 attachment_dir/group_id/YYYY-MM-DD/ 目录结构存放
  • 附件文件名会加 topic_id 前缀，例如 789_image_1.jpg、789_report.pdf
  • 已存在文件自动跳过
  • 下载失败记录到 attachments_local.error，不中断主流程
  • CLI 返回可下载 URL 时直接下载；若只有 file_id，legacy HTTP 下载 URL 查询可能需要 ZSXQ_TOKEN

错误处理

| 错误场景 | 处理 | | --- | --- | | 未安装 zsxq-cli | 返回 zsxq_cli_missing，提示 npm install -g zsxq-cli | | 官方 CLI 未登录 | 返回 zsxq_cli_not_authenticated，提示 zsxq-cli auth login | | 官方 CLI 非 JSON 输出 | 返回 zsxq_cli_non_json | | 官方 CLI 命令失败 | 返回 zsxq_cli_failed 并保留截断后的 stderr/stdout | | 精华标记缺失 | 返回 digests_unavailable_from_cli，不自动切换 HTTP | | 单帖详情补全失败 | 搜索命中仍保留，结果中记录 detail_error | | legacy HTTP token 未设置 | 仅在 ZSXQ_BACKEND=http 时提示设置 ZSXQ_TOKEN | | legacy HTTP 429 | 指数退避并加入随机抖动 | | 附件下载失败 | 记录错误并继续 |

1059 说明

默认路径使用官方 zsxq-cli，避免继续与知识星球对非官方客户端访问的 1059 风控对抗。本 Skill 不实现伪造官方客户端或绕过风控的逻辑。

如显式启用 legacy HTTP fallback 并遇到 code: 1059，应回到默认 CLI 后端：

unset ZSXQ_BACKEND
zsxq-cli auth login

详细 API 参考

如需了解 CLI 命令、输出归一化、legacy HTTP fallback 和错误码，参阅 {baseDir}/references/api-reference.md。