zsxq-cli 共享规则

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

认证

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

登录

# 发起登录（会输出一个授权链接，用户在手机/浏览器中打开并授权）
zsxq-cli auth login

登录流程：

1. 命令输出一个 verification_uri 链接和 user_code
2. 用户在手机或浏览器中打开链接，完成授权
3. CLI 自动轮询，授权完成后自动保存 token

当你作为 AI Agent 帮用户登录时，在后台运行 zsxq-cli auth login，读取输出后将授权链接提供给用户，等待用户完成授权。

查看认证状态

zsxq-cli auth status        # 表格显示当前登录账户
zsxq-cli auth status --json # JSON 格式输出

退出登录

zsxq-cli doctor             # 诊断配置和认证是否正常

配置诊断

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"}'

# 推荐：对通用 HTTP API 使用显式参数的 raw 子命令
zsxq-cli api raw --method GET --path /v2/groups/123456789/topics --query '{"count":10}'

安全规则

• 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	缺少必填参数	先用 zsxq-cli group +topics 或 topic +search 查询 topic_id