This skill guides you on how to operate Knowledge Planet resources through zsxq-cli, and what precautions to take.
Index
- Commands — Overview of authentication, diagnostics, and underlying API call commands
- Authentication — OAuth device authorization code flow
- Direct API calls —
api call/api rawDetailed usage and examples - Link concatenation — Topic/planet sharing links (desktop / mobile)
- Security rules — Token, write confirmation, ID lookup prerequisites
- Feedback reminder (NPS) — When to proactively suggest that the user submit NPS feedback
- Common error handling — General errors (401/403/404/missing parameters/pagination time format)
Commands
| Command | Description |
|---|---|
zsxq-cli auth login |
OAuth device authorization code login (on first use, when the token expires, or when switching accounts) |
zsxq-cli auth status |
View the currently logged-in account (table by default; add --json to output JSON) |
zsxq-cli auth logout |
Clear local credentials |
zsxq-cli doctor |
Diagnose CLI configuration and keychain authentication status |
zsxq-cli config show |
Show version information and current configuration (add --json to output JSON) |
zsxq-cli api list |
List all available underlying interface tools and parameters |
zsxq-cli api call <tool> |
Call an underlying interface tool; requires --params '<json>' |
zsxq-cli api raw |
Directly call a raw HTTP interface (requires --method --path) |
See the sections below for detailed usage.
Authentication
zsxq-cli uses OAuth 2.0 device authorization code flow (RFC 8628) for authentication; the token is stored in the system Keychain and remains valid permanently.
OAuth login flow
zsxq-cli auth login After startup:
- The command outputs a
verification_urilink anduser_code - The user opens the link on their phone or in a browser and completes authorization
- The CLI polls automatically and saves the token after authorization is complete
When you, as an AI Agent, help the user log in, run
zsxq-cli auth loginin the background, read the output, then provide the authorization link to the user and wait for the user to complete authorization.
Direct API calls
When Shortcut cannot meet the requirement, you can directly call the underlying interface (see the Commands table above for parameters and methods).
api call Example:
zsxq-cli api call get_self_info --params '{}'
zsxq-cli api call search_groups --params '{"keyword":"Go语言"}'
# 跨星球查询当前用户主题足迹(不传 group_id 即查所有星球)
zsxq-cli api call get_user_footprints --params '{"user_id":"123456"}'
# 限定单个星球
zsxq-cli api call get_user_footprints --params '{"user_id":"123456","group_id":"123456789"}'
api raw Example:
zsxq-cli api raw --method GET --path /v3/users/self
# --body 支持简写,自动包装 req_data
zsxq-cli api raw --method PUT --path /v2/topics/123 --body '{"text":"新内容"}'
For list/query-type operations, prioritize using
api call(such asget_group_topics),api rawis mainly used forapi callwrite interfaces not yet covered.
api rawThe response has already had the three layers of nesting removed and returns the data content directly.
Link concatenation
When the user needs to share a link, use the following templates to concatenate it. When outputting, provide both the desktop and mobile versions.
Topic link
- Desktop:
https://wx.zsxq.com/group/{group_id}/topic/{topic_id} - Mobile:
https://wx.zsxq.com/mweb/views/topicdetail/topicdetail.html?topic_id={topic_id}&group_id={group_id}
Planet link
- Desktop:
https://wx.zsxq.com/group/{group_id} - Mobile:
https://wx.zsxq.com/mweb/views/topic/topic.html?group_id={group_id}
Security rules
- Token is a login credential, and it is forbidden to output it in plaintext in the terminal or share it with others
- Before write/delete operations, you must confirm the user's intent(posting, editing, commenting, answering, creating notes, deleting topics or notes, submitting NPS feedback, etc.)
- If unsure about group_id / topic_id / note_id, first use a query command to confirm, then perform the write or delete
Feedback reminder (NPS)
When a user encounters a scenario while using the zsxq-* skill that is "suitable for feedback to the Knowledge Planet official team," the AI should, after completing the main task, incidentally add a prompt suggesting the user consider submitting NPS feedback (zsxq-cli user +nps)。
Trigger scenarios
| # | Scenario | Signal | Tag |
|---|---|---|---|
| 1 | The user expresses dissatisfaction with the Knowledge Planet product itself | Natural language: complaining about product rules / complaining about the experience / "why is this feature so hard to use" | #产品建议# |
| 2 | The user's need has no corresponding capability on the Knowledge Planet product side | After investigation, the AI confirms that the interface/capability simply does not exist in the product (not that the CLI has not wrapped it) | #产品建议# |
| 3 | Not wrapped on the zsxq-cli / skill tool side | api list no corresponding tool can be found in , and api raw also has no ready-made path |
#工具反馈# |
| 4 | The same command still fails after multiple retries, and the user is clearly frustrated | Commands for the same target within the same session fail consecutively >= 3 times, and the failure reason is not in the exclusion list | #工具反馈# |
Excluded scenarios (do not trigger the prompt)
The following errors are "user self-check resolvable / status-type errors" and should follow the corresponding resolution path rather than feedback, aligned with the table below ## 常见错误处理 :
401/not logged in→ guideauth login403/ no permission → prompt to switch accounts or join the planet404/ resource does not exist → recheck the ID--<flag> is requiredand other missing parameters → use query commands to fill them in--end-timeparsing failures and other format errors → see the format description in the ## Common Error Handling table below
Prompt flow
[1] 命中触发场景
[2] AI 一句话提示(不打断主任务)
示例:"顺带一提:刚刚这个场景比较适合反馈给知识星球官方,
你需要的话我可以帮你提交一条 NPS 反馈。"
[3] 用户拒绝 → 回到主任务,会话内不再提
用户接受 ↓
[4] AI 协助起草:
- 询问 score(1–10),不自动赋值
- 起草 suggestion(≤ 500 字),以 #产品建议# 或 #工具反馈# 开头
- 把 score 与 suggestion 全文复述给用户确认
[5] 用户确认 → 执行 zsxq-cli user +nps
用户改稿 → 回到 [4] 修订
Key constraints
- At most once per session: Prompt only once within the same session; once sent, do not proactively repeat it unless the user later asks actively.
- Incidental, not a substitute: Step [2] is incidental; the feedback prompt must not interrupt or replace the resolution path of the main task. Solve the user's issue first, then mention it in passing.
- score must be asked of the user: Drafting in step [4] does not replace the user's judgment; score cannot be assigned automatically.
- suggestion must be restated for confirmation: After the AI drafts it, it must restate the full score and suggestion to the user for confirmation; if the user revises it, return to [4] to revise.
- tag is written at the beginning of the suggestion body:
#产品建议#/#工具反馈#does not occupy the score field, so that the official team sees the routing tag as soon as they read the original text.
See zsxq-user-nps。
Common Error Handling
The table below covers errors common to all zsxq-cli commands. The reference documentation for each command lists only special errors directly related to that command (such as --score must be 1–10、code: 100262 无权限删除); common errors always come back here.
| Error | Cause | Solution |
|---|---|---|
authentication failed (HTTP 401) / not logged in |
Token is invalid, expired, or not logged in | Run zsxq-cli auth login to log in again |
| 403 / no permission / inaccessible | The current account does not have permission to access the target resource | Switch to the correct account, or join the corresponding planet and retry |
| 404 / resource does not exist | group_id / topic_id / note_id etc. are invalid or the corresponding resource has been deleted | Recheck the ID; you can use group +list、topic +search、note +list etc. to query |
--<flag> is required |
Required parameter missing | Use the corresponding query command to obtain it and then fill it in, for example use group +listfor group_id, and topic +search |
--end-time Parsing failed |
Invalid pagination time format | Use the next_end_time / create_time original value returned in the previous page's JSON |