知识星球帖子抓取助手

从指定知识星球抓取最新帖子内容，支持全部帖子、精华过滤、关键词搜索、单帖详情、日期范围、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 是否已设置。

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。

Zsxq Post Fetch

知识星球帖子抓取助手

认证与环境

默认官方 CLI 认证

legacy HTTP fallback

依赖安装

配置文件

`{baseDir}/config.json`

`{baseDir}/groups.json`

Prompt 使用说明

意图识别

推荐 Prompt 示例

Agent 输出要求

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

1. 获取帖子列表

2. 获取精华帖

3. 按关键词搜索并下载

4. 获取指定帖子详情

5. 按日期范围抓取帖子

6. 列出已加入的星球

附件下载行为

错误处理

1059 说明

详细 API 参考

Zsxq Post Fetch

知识星球帖子抓取助手

认证与环境

默认官方 CLI 认证

legacy HTTP fallback

依赖安装

配置文件

{baseDir}/config.json

{baseDir}/groups.json

Prompt 使用说明

意图识别

推荐 Prompt 示例

Agent 输出要求

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

1. 获取帖子列表

2. 获取精华帖

3. 按关键词搜索并下载

4. 获取指定帖子详情

5. 按日期范围抓取帖子

6. 列出已加入的星球

附件下载行为

错误处理

1059 说明

详细 API 参考

`{baseDir}/config.json`

`{baseDir}/groups.json`

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