用途
zsxq-smart-publish 用于在知识星球（zsxq.com）发布和管理内容，支持通过 API 或浏览器自动化两种方式操作。
主要能力
支持的内容类型包括：
- 话题（Talk）：topic_type 为 talk，字符上限 50,000，可包含文字、图片和文件。
- 问答（Q&A）：topic_type 为 q&a，字符上限 50,000，星主可回答。
- 作业（Task）：topic_type 为 task，字符上限 50,000，可设置截止时间。
- 长文章（Article）：字符上限 100,000，仅支持网页端，使用富编辑器并支持 Markdown，需通过浏览器发布，不能使用 topics API。
此外还支持文件与图片上传、获取话题列表、设置精华（仅星主）、获取用户群组列表以及标签管理。
使用方式
认证
需要有效的 zsxq_access_token cookie。获取方式：在浏览器打开 https://wx.zsxq.com，通过微信扫码登录，打开开发者工具 → Application → Cookies → 找到 zsxq_access_token。然后设置环境变量：export ZSXQ_ACCESS_TOKEN="your_token"，或存入配置文件。Token 会过期，当 API 返回 401 时需重新扫码。
快速开始
发布话题：
python3 scripts/publish.py --type talk
--group-id GROUP_ID
--text "Hello from AI agent!"
--tags "AI,自动化"
--image /path/to/image.png
发布问答：
python3 scripts/publish.py --type qa
--group-id GROUP_ID
--text "如何使用API批量发帖？"
--tags "API,教程"
发布作业：
python3 scripts/publish.py --type task
--group-id GROUP_ID
--text "完成本周阅读任务\n\n阅读《AI未来》第3-5章"
--deadline "2026-03-25 23:59"
发布长文章（需要浏览器）：
python3 scripts/publish_article.py
--group-url "https://wx.zsxq.com/group/GROUP_ID"
--title "AI Agent开发指南"
--text-file article.md
--image /path/to/cover.png
上传文件或图片：
python3 scripts/upload.py
--group-id GROUP_ID
--file /path/to/report.pdf
--text "本周研报"
发布流程
发布前检查：确认 ZSXQ_ACCESS_TOKEN 有效（python3 scripts/publish.py --check-auth）；确认 GROUP_ID（从 URL wx.zsxq.com/group/{GROUP_ID} 获取）；准备符合字符限制的内容；添加相关标签（每帖最多 3 个标签）；按需附加图片（JPG/PNG，建议每张 ≤ 5MB，最多 9 张）。
发布后：确认帖子出现在群组中；按需设为精华（仅星主，通过 API 或浏览器）；添加到合适的话题分类。
API 参考
基础 URL：https://api.zsxq.com
创建话题（Talk/Q&A/Task）：
POST /v2/groups/{group_id}/topics Content-Type: application/json Cookie: zsxq_access_token={token}
{ "req_data": { "topic": { "type": "talk|q&a|task", "title": "optional title", "text": "post content (supports limited Markdown)", "image_count": 1, "images": [{"file_size": 12345, "width": 800, "height": 600}], "file": {"file_key": "xxx"} }, "task": { "owner_user_id": 0, "dead_line": "2026-03-25 23:59" } } }
上传图片：
POST /v2/files/{group_id}/images Content-Type: multipart/form-data Cookie: zsxq_access_token={token}
file: (binary)
返回：{"resp_data": {"upload_key": "xxx", "width": 800, "height": 600}}
上传文件：
POST /v2/files/{group_id}/files Content-Type: multipart/form-data Cookie: zsxq_access_token={token}
file: (binary)
返回：{"resp_data": {"file": {"file_key": "xxx", "name": "file.pdf"}}}
获取话题列表：
GET /v1.10/groups/{group_id}/topics?scope=all&count=20 Cookie: zsxq_access_token={token}
scope 选项：all|digests|questions|tasks
设为精华：
POST /v2/topics/{topic_id}/digest Cookie: zsxq_access_token={token}
获取群组列表：
GET /v2/groups Cookie: zsxq_access_token={token}
内容格式
支持的 Markdown：粗体、斜体；# 标题（仅长文章）；code、``` 代码块；有序/无序列表；链接 text（仅长文章）；表格（仅长文章）。
不支持：通过 Markdown 嵌入图片（需使用 API 上传）；HTML 标签；数学公式；Mermaid 图表。
图片规格：格式 JPG、PNG、GIF；建议每张 ≤ 5MB；每帖最多 9 张；长文章通过编辑器插入，数量不限。
文件规格：最大 200MB；支持 PDF、DOCX、XLSX、PPTX、ZIP、MP3、MP4；音频建议 MP3，最长 30 分钟。
浏览器发布（长文章）
长文章无法通过 API 创建，需使用 scripts/publish_article.py：导航到群组页面、点击“长文章”按钮、填写标题和内容、上传封面图、发布。需要 Playwright：pip install playwright && playwright install chromium。
模板
assets/ 目录下提供内容模板：assets/talk-template.md（标准话题）、assets/qa-template.md（问答格式）、assets/task-template.md（作业/任务）、assets/article-template.md（长文章结构）。
错误处理
401：Token 过期，重新登录获取新 token。403：无权限，检查用户是否为群组成员/星主。429：触发限流，等待冷却后重试。500：服务器错误，使用指数退避重试。
适用场景
适合需要在知识星球批量或自动化发布话题、问答、作业和长文章的用户，以及需要上传文件、管理标签和设置精华的星主或管理员。
限制
长文章仅支持浏览器发布，不能通过 API 创建。Token 会过期，需重新扫码。部分操作（如设置精华）仅星主可用。内容格式对 Markdown 的支持有限，不支持 HTML、数学公式和 Mermaid 图表。图片和文件有大小与数量限制。