On first use or when encountering an authentication error (401 / token expired /
not logged in), first read../zsxq-shared/SKILL.mdto learn the login and API call conventions. There is no need to re-read it every time during routine calls with an already logged-in account.
Core Concepts
- Planet (Group): the community unit of Knowledge Planet, uniquely identified by
group_id(pure digits). A user can be the creator (owner) or a member (member). - Topic: a content unit within a planet, including posts (talk), questions (q&a), tasks (task), task solutions (solution), etc., uniquely identified by
topic_id. - Hashtag: a category tag within a planet, identified by
hashtag_id, which can be attached to topics.
Resource Relationships
Group (group_id)
├── Topic (topic_id) — talk / q&a / task / solution
│ ├── Comment (comment_id)
│ │ └── 楼中楼 Reply (replied_comment_id)
│ ├── Answer(q&a 类型专属)
│ └── Hashtag 标签
└── Hashtag (hashtag_id)
└── Topic 列表
Shortcuts (prefer using these first)
A Shortcut is a high-level wrapper for common operations (zsxq-cli group +<verb> [flags]). For operations that have a Shortcut, use it first.
| Shortcut | Description |
|---|---|
+list |
List all planets the current user has joined or created, outputting a table of group_id and name |
+topics |
List the latest topics in a planet, supporting a pagination cursor, outputting a table of topic_id / type / title / time |
+hashtags |
List all tags in a planet and the number of topics |
API (called directly via zsxq-cli api call )
Advanced operations not covered by Shortcuts:
| Tool | Parameter | Description |
|---|---|---|
search_groups |
keyword |
Search planets by keyword |
search_group_members |
group_id, keyword, limit |
Search planet members |
get_hashtag_topics |
hashtag_id, limit, end_time |
List topics under a tag (paginated) |
Counterexamples (do not do)
| ❌ Do not do | ✅ Should do |
|---|---|
When finding content by keyword, use +topics to paginate and manually filter item by item |
Use zsxq-topic 's +search full-text search |
When checking "what I recently posted," run +topics |
Use zsxq-user 's +footprints to get cross-planet activity in one go |
| When the user only gives a planet name, ask the user to provide the group_id themselves or guess the ID from memory | First use group +list(for planets you have joined) or search_groups(public search) to find the ID before continuing |
| When a name matches multiple similar planets, take the first one by default | List the candidates (group_id + name) and let the user confirm |
Treat search_group_members as a member-list interface and increase limit to iterate through all members |
It is a keyword search, used only to locate a specific member by nickname |