zsxq-shared

Name: zsxq-shared
Author: unnoo

知识星球 CLI 共享基础：认证登录（auth login/logout）、查看认证状态、诊断配置。当用户需要首次登录、退出登录、查看认证状态、或遇到认证错误时触发。

INSTALLATION

npx skills add https://github.com/unnoo/zsxq-skill --skill zsxq-shared

Run in your project or agent environment. Adjust flags if your CLI version differs.

SKILL.md

zsxq-cli 共享规则

本技能指导你如何通过 zsxq-cli 操作知识星球资源，以及有哪些注意事项。

认证

zsxq-cli 使用 OAuth 2.0 设备授权码流程（RFC 8628） 认证，token 存储在系统 Keychain 中，永久有效。

查看认证状态

zsxq-cli auth status        # 表格显示当前登录账户

zsxq-cli auth status --json # JSON 格式输出

退出登录

zsxq-cli auth logout        # 清除本地凭据

配置诊断

zsxq-cli doctor             # 检查 CLI 配置和 keychain 认证状态

zsxq-cli config show        # 显示版本信息和当前配置

zsxq-cli config show --json # JSON 格式

直接调用 API

当 Shortcut 无法满足需求时，可以直接调用底层 MCP 工具：

zsxq-cli api list                           # 列出所有可用 MCP 工具及参数

zsxq-cli api call <tool> --params '<json>'  # 调用指定工具

zsxq-cli api raw --method GET --path /v3/users/self

示例：

zsxq-cli api call get_self_info --params '{}'

zsxq-cli api call search_groups --params '{"keyword":"Go语言"}'

zsxq-cli api call get_user_footprints --params '{"user_id":"123456","group_id":"123456789"}'

# 当 MCP 工具未覆盖某个接口时，使用 raw 子命令直接调用 HTTP API

# --body 支持简写，自动包装 req_data

zsxq-cli api raw --method PUT --path /v2/topics/123 --body '{"text":"新内容"}'

列表/查询类操作请优先使用 api call（如 get_group_topics），api raw 主要用于 MCP 工具尚未封装的写入接口。

api raw 响应已去除三层嵌套，直接返回数据内容。

链接拼接

当用户需要分享链接时，使用以下模板拼接。输出时同时提供电脑端和手机端两个版本。

主题链接

电脑端：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}

安全规则

Token 是登录凭证，禁止在终端明文输出或分享给他人

写入/删除操作前必须确认用户意图（发帖、评论、创建笔记等）

不确定 group_id / topic_id 时，先用查询命令确认，再执行写入

常见错误处理

错误

原因

解决方案

authentication failed (HTTP 401)

Token 无效或过期

重新运行 zsxq-cli auth login

not logged in

未完成登录

运行 zsxq-cli auth login

--group-id is required

缺少必填参数

先用 zsxq-cli group +list 查询 group_id

--topic-id is required