知识星球帖子抓取助手#

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

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

---

认证与环境#

默认官方 CLI 认证#

执行前优先检查：

bash

zsxq-cli auth status

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

bash

zsxq-cli auth login

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

legacy HTTP fallback#

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

bash

export ZSXQ_BACKEND=http

json

{
  "backend": "http"
}

该路径才需要：

bash

export ZSXQ_TOKEN="your_zsxq_access_token"

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

依赖安装#

首次使用运行：

bash

bash {baseDir}/install.sh

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

---

配置文件#

{baseDir}/config.json#

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：是否开启自动下载

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

bash

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

优先级： ZSXQ_ATTACHMENT_DIR -> ATTACHMENT_DIR -> config.json.attachment_dir。

{baseDir}/groups.json#

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 示例#

text

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

text

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

text

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

text

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

text

列出我当前账号加入的知识星球，帮我找到对应 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. 获取帖子列表#

bash

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. 获取精华帖#

bash

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

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

3. 按关键词搜索并下载#

bash

node {baseDir}/fetch_topics.js search <group_id> <keyword> [count] [--markdown] [--download-attachments]

• 默认通过官方 MCP tool search_topics 搜索主题：

bash

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. 获取指定帖子详情#

bash

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

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

bash

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

5. 按日期范围抓取帖子#

bash

node {baseDir}/fetch_topics.js topics-by-date <group_id> <start_date> [end_date] [count] [--markdown]

• 日期格式： YYYY-MM-DD
• 帖子按时间倒序，遇到早于 start_date 的帖子自动停止翻页
• 支持附件自动下载和 Markdown 导出

6. 列出已加入的星球#

bash

node {baseDir}/fetch_topics.js groups

默认执行：

bash

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_errorlegacy HTTP token 未设置仅在 ZSXQ_BACKEND=http 时提示设置 ZSXQ_TOKENlegacy HTTP 429指数退避并加入随机抖动附件下载失败记录错误并继续

1059 说明#

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

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

bash

unset ZSXQ_BACKEND
zsxq-cli auth login

---

详细 API 参考#

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