zsxq-skill

name	zsxq-skill
description	知识星球 CLI 操作技能 — 浏览星球、搜索发布主题、评论回答、管理笔记、查看用户信息
version	1.0.0
author	知识星球 (Zsxq)

知识星球 (Zsxq) Skill

通过 zsxq-cli 命令行工具操作知识星球。所有命令通过 Bash 工具执行。

核心概念

概念	标识	说明
星球（Group）	group_id	知识社群单元，纯数字 ID
主题（Topic）	topic_id	星球内的内容单元。类型：talk（帖子）、q&a（提问）、task（作业）、solution（作业答案）
评论（Comment）	comment_id	主题下的回复，支持楼中楼（replied_comment_id）
笔记（Note）	note_id	独立于星球的内容单元，纯数字 ID
用户（User）	user_id	账户标识，纯数字 ID

资源层级：Group → Topic → Comment → 楼中楼 Reply

安全规则

• Token 是登录凭证，禁止明文输出或分享
• 写入/删除前必须确认用户意图：发帖、编辑、评论、回答、创建/编辑/删除笔记、提交 NPS
• 不确定 ID 时先查询再操作：用 +list / +search / +detail 确认后再执行写入或删除
• 笔记是公开内容，任何持有链接的人都可访问 —— 不要写入隐私或敏感信息

命令参考

认证

命令	用途
zsxq-cli auth status	查看当前登录账户。成功输出 ✓ Logged in as <name> (<user_id>)，exit code 0
zsxq-cli auth logout	清除本地凭据

认证登录由 WorkBuddy 自动管理，无需手动执行 auth login。如遇 401 错误，在 WorkBuddy 中重新连接 Connector 即可。

---

zsxq-cli group — 星球管理

group +list — 列出我的星球

列出当前用户加入或创建的所有星球。

zsxq-cli group +list
zsxq-cli group +list --limit 50
zsxq-cli group +list --json

参数	必填	说明
--limit <n>	否	返回数量，默认 10，最大 200
--json	否	输出完整 JSON

输出（表格）：GROUP ID / NAME

group +topics — 浏览星球主题

列出星球内最新主题，按时间倒序。

zsxq-cli group +topics --group-id 123456789
zsxq-cli group +topics --group-id 123456789 --limit 30
zsxq-cli group +topics --group-id 123456789 --json

# 翻页：用上一页返回的 next_end_time
zsxq-cli group +topics --group-id 123456789 \
  --end-time "2025-11-01T10:00:00.000+0800"

参数	必填	说明
--group-id <id>	是	星球 ID
--limit <n>	否	返回数量，默认 20，最大 30
--end-time <t>	否	分页游标，使用上一页返回的 next_end_time 原值
--json	否	输出完整 JSON

输出（表格）：TOPIC ID / TYPE / TITLE / DIGEST / CREATED AT

• TYPE：talk / q&a / task / solution

group +hashtags — 查看星球标签

zsxq-cli group +hashtags --group-id 123456789
zsxq-cli group +hashtags --group-id 123456789 --json

参数	必填	说明
--group-id <id>	是	星球 ID
--json	否	输出完整 JSON

输出（表格）：HASHTAG ID / TITLE / TOPIC COUNT

API：星球高级操作

没有对应 Shortcut 时，通过 zsxq-cli api call 调用：

# 按关键词搜索星球
zsxq-cli api call search_groups --params '{"keyword":"Go语言"}'

# 按昵称搜索星球成员
zsxq-cli api call search_group_members \
  --params '{"group_id":"123456789","keyword":"昵称","limit":20}'

# 查看某标签下的所有主题
zsxq-cli api call get_hashtag_topics \
  --params '{"hashtag_id":"333444555666","limit":20}'

# 翻页
zsxq-cli api call get_hashtag_topics \
  --params '{"hashtag_id":"333444555666","limit":20,"end_time":"2025-11-01T00:00:00.000+0800"}'

---

zsxq-cli topic — 主题操作

topic +search — 全文搜索主题

在指定星球内全文搜索，结果按相关性排序。

zsxq-cli topic +search --group-id 123456789 --query "跨境电商"
zsxq-cli topic +search --group-id 123456789 --query "AI 应用" --json

参数	必填	说明
--group-id <id>	是	星球 ID
--query <text>	是	搜索关键词，支持中英文
--json	否	输出完整 JSON

topic +detail — 查看主题详情

获取单条主题的完整信息（正文、作者、点赞数、评论数、标签等）。

zsxq-cli topic +detail --topic-id 111222333444

参数	必填	说明
--topic-id <id>	是	主题 ID
--json	否	默认即 JSON 输出

关键输出字段：topic_id、type（talk/q&a/task/solution）、title、content、create_time、digested（是否精华）、counts（comments/likes/readers）、owner、group

+detail 不含评论内容。查看评论用 api call get_topic_comments。

topic +create — 发布帖子

在指定星球内发布一条 talk 类型主题。⚠️ 仅支持 talk 类型。

# 纯文本帖子
zsxq-cli topic +create --group-id 123456789 --text "帖子正文"

# 带附件（逗号分隔路径）
zsxq-cli topic +create --group-id 123456789 \
  --text "帖子正文" --files photo.jpg,report.pdf

# 获取新建的 topic_id
zsxq-cli topic +create --group-id 123456789 --text "帖子正文" --json

参数	必填	说明
--group-id <id>	是	目标星球 ID
--text <text>	是	正文内容，支持 \n 换行
--files <paths>	否	附件路径，逗号分隔
--json	否	输出含 topic_id、create_time

⚠️ 执行前必须确认： 目标星球 + 发布内容。写入失败即原子回滚。

topic +edit — 编辑帖子

编辑自己发布的主题。只能编辑自己的。

zsxq-cli topic +edit --topic-id 111222333444 --text "修改后的内容"
zsxq-cli topic +edit --topic-id 111222333444 --files new-photo.jpg
zsxq-cli topic +edit --topic-id 111222333444 --clear-files

参数	必填	说明
--topic-id <id>	是	主题 ID
--text <text>	否	新正文（不传则保留）
--files <paths>	否	新附件，替换原有
--clear-files	否	清除所有附件
--json	否	输出 JSON

⚠️ 执行前必须确认： 主题当前内容 + 修改后内容。写入失败即原子回滚。

topic +reply — 发表评论

对主题发表评论，支持楼中楼。

# 顶层评论
zsxq-cli topic +reply --topic-id 111222333444 --text "评论内容"

# 楼中楼：回复某条评论
zsxq-cli topic +reply --topic-id 111222333444 \
  --text "回复内容" --reply-to 222333444555

# 带附件
zsxq-cli topic +reply --topic-id 111222333444 \
  --text "评论" --files screenshot.png

参数	必填	说明
--topic-id <id>	是	主题 ID
--text <text>	是	评论内容
--reply-to <id>	否	被回复的评论 ID（楼中楼），省略为顶层评论
--files <paths>	否	附件路径，逗号分隔
--json	否	输出含 comment_id、create_time

⚠️ 执行前必须确认： 目标主题 + 评论内容。写入失败即原子回滚。

topic +answer — 回答提问

对 q&a 类型主题发布官方回答。每题只能回答一次，不可修改。

zsxq-cli topic +answer --topic-id 111222333466 --text "回答内容"
zsxq-cli topic +answer --topic-id 111222333466 \
  --text "回答内容" --files diagram.png

参数	必填	说明
--topic-id <id>	是	主题 ID（必须是 q&a 类型）
--text <text>	是	回答正文
--files <paths>	否	附件路径，逗号分隔
--json	否	输出 JSON

⚠️ 执行前必须确认： 问题内容 + 回答全文。+answer 与 +reply 不同：前者是官方回答（仅一次），后者是普通评论（可多次）。

删除主题

通过原始 HTTP 调用删除。不可恢复。

zsxq-cli api raw --method DELETE --path /v2/topics/<topic_id>

⚠️ 执行前必须确认： 主题内容和删除意图。特有错误：code: 100262（无权限）、code: 100002（不存在）。

API：主题高级操作

# 查看主题评论列表
zsxq-cli api call get_topic_comments \
  --params '{"topic_id":"111222333444","limit":30}'

# 设置/取消精华（星主权限）
zsxq-cli api call set_topic_digested \
  --params '{"topic_id":"111222333444","digested":true}'

# 设置标签
zsxq-cli api call set_topic_tags \
  --params '{"topic_id":"111222333444","titles":["标签1","标签2"]}'

# 查看自己发起的提问（unanswered / answered）
zsxq-cli api call get_self_question_topics \
  --params '{"topic_filter":"unanswered","count":20}'

# 查看别人向我发起的提问
zsxq-cli api call get_self_answer_topics \
  --params '{"topic_filter":"unanswered","count":20}'

---

zsxq-cli user — 用户信息

user +info — 查看个人资料

zsxq-cli user +info

输出当前用户的 user_id、name、unique_id、avatar_url、identity_status（实名认证状态）、subscribed_wechat、第三方账户绑定等。

user +footprints — 跨星球足迹

查看自己在所有星球最近发过的主题，按时间倒序。

zsxq-cli user +footprints
zsxq-cli user +footprints --limit 30
zsxq-cli user +footprints --json

# 翻页（用上一页最后一条的 create_time）
zsxq-cli user +footprints \
  --end-time "2025-11-01T00:00:00.000+0800"

参数	必填	说明
--limit <n>	否	返回条数，默认 20，最大 30
--end-time <t>	否	分页游标，传入上一页最后一条的 create_time
--json	否	输出完整 JSON

输出（表格）：TOPIC ID / TYPE / TITLE / DIGEST / GROUP / CREATED AT

+footprints 跨星球 vs group +topics 单星球。查"我最近发过什么"用 +footprints。

user +nps — 提交 NPS 反馈

向知识星球官方提交推荐分数和建议。

zsxq-cli user +nps --score 9 --suggestion "希望增加更多互动功能"

参数	必填	说明
--score <n>	是	1–10 整数（1=不推荐，10=极力推荐）
--suggestion <text>	是	文字建议，最长 500 字。建议以 #产品建议# 或 #工具反馈# 开头
--json	否	输出 JSON

⚠️ 执行前必须确认： 分数 + 建议全文。特有错误：--score must be 1–10、--suggestion exceeds 500 chars。需 zsxq-cli ≥ 0.4.6。

---

zsxq-cli note — 笔记管理

笔记是独立于星球的公开内容，任何持有链接的人都能访问。

note +create — 创建笔记

zsxq-cli note +create --text "笔记内容"
zsxq-cli note +create --text "第一行\n第二行"
zsxq-cli note +create --text "带图笔记" --files photo.jpg
zsxq-cli note +create --text "内容" --json  # 获取 note_id

参数	必填	说明
--text <text>	是	笔记内容，支持 \n 换行
--files <paths>	否	附件路径，逗号分隔（仅图片）
--json	否	输出含 note_id、create_time

⚠️ 执行前必须确认： 笔记内容（笔记是公开的，勿写入隐私）。

note +list — 笔记列表

zsxq-cli note +list
zsxq-cli note +list --limit 30
zsxq-cli note +list --json

# 翻页
zsxq-cli note +list --end-time "2025-11-01T00:00:00.000+0800"

参数	必填	说明
--limit <n>	否	返回条数，默认 20，最大 30
--end-time <t>	否	分页游标，传入上一页最后一条的 create_time
--json	否	输出完整 JSON

输出（表格）：NOTE ID / CONTENT（截断） / CREATED AT

note +detail — 笔记详情

zsxq-cli note +detail --note-id 444555666777

note +edit — 编辑笔记

zsxq-cli note +edit --note-id 444555666777 --text "新内容"
zsxq-cli note +edit --note-id 444555666777 --files new-photo.jpg
zsxq-cli note +edit --note-id 444555666777 --clear-files

参数	必填	说明
--note-id <id>	是	笔记 ID
--text <text>	否	新内容（不传则保留）
--files <paths>	否	新附件，替换原有（仅图片）
--clear-files	否	清除所有附件
--json	否	输出 JSON

⚠️ 只能编辑自己的笔记。执行前必须确认修改内容。

note +delete — 删除笔记

zsxq-cli note +delete --note-id 444555666777

⚠️ 不可恢复。执行前必须确认笔记内容和删除意图。

---

链接拼接

当用户需要分享链接时，同时提供电脑端和手机端：

主题链接：

• 电脑：https://wx.zsxq.com/group/{group_id}/topic/{topic_id}
• 手机：https://wx.zsxq.com/mweb/views/topicdetail/topicdetail.html?topic_id={topic_id}&group_id={group_id}

星球链接：

• 电脑：https://wx.zsxq.com/group/{group_id}
• 手机：https://wx.zsxq.com/mweb/views/topic/topic.html?group_id={group_id}

---

常见错误处理

错误	原因	处理
authentication failed (HTTP 401) / not logged in	Token 过期或未登录	在 WorkBuddy 中重新连接 Connector
403 / 无权限	无访问目标资源权限	确认登录账户正确，或联系星主
404 / 资源不存在	ID 无效或资源已删除	用 +list / +search 重新获取 ID
--<flag> is required	缺少必填参数	先用查询命令补齐
--end-time 解析失败	分页时间格式错误	使用上一页返回的 next_end_time / create_time 原值
问题已回答	q&a 主题已有官方回答	每题只能回答一次，改用 +reply
code: 100262	无权限删除（非作者/星主）	确认身份
code: 100002	主题不存在或已删除	核对 topic_id

反例（不要做）

❌ 不要做	✅ 应该做
按关键词找内容时用 +topics 逐条翻页筛选	用 topic +search 全文搜索
查"自己最近发过什么"时逐个星球跑 +topics	用 user +footprints 一次跨星球查询
用户只给星球名称时凭记忆猜 group_id	先 group +list 或 api call search_groups 查到 ID
名称命中多个相似星球时默认取第一个	列出候选让用户确认
把 search_group_members 当成员列表、调大 limit 遍历全员	它是关键词搜索，只用于按昵称定位
把笔记当私密备忘录写入敏感信息	笔记是公开内容，勿写入隐私
对非 q&a 主题使用 +answer	用 +reply 发普通评论
不确定 topic_id / note_id 就直接执行写入/删除	先用 +detail 确认内容再操作