Back to Details

zsxq-shared

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

zsxq-cli 共享规则

zsxq-cli Sharing Rules

本技能指导你如何通过 zsxq-cli 操作知识星球资源，以及有哪些注意事项。
This skill guides you on how to operate Knowledge Planet resources via zsxq-cli and what precautions to take.

认证

Authentication

zsxq-cli 使用 OAuth 2.0 设备授权码流程（RFC 8628） 认证，token 存储在系统 Keychain 中，永久有效。
zsxq-cli uses OAuth 2.0 Device Authorization Grant Flow (RFC 8628) for authentication. The token is stored in the system Keychain and is permanently valid.

登录

Login

bash
undefined
bash
undefined

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

Initiate login (an authorization link will be output; users open and authorize it on mobile/browser)

zsxq-cli auth login

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

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

Login process:
1. The command outputs a `verification_uri` link and `user_code`
2. Users open the link on mobile or browser and complete authorization
3. The CLI automatically polls, and saves the token automatically after authorization is completed

> When you help users log in as an AI Agent, run `zsxq-cli auth login` in the background, read the output, provide the authorization link to the user, and wait for the user to complete authorization.

查看认证状态

View Authentication Status

bash
zsxq-cli auth status        # 表格显示当前登录账户
zsxq-cli auth status --json # JSON 格式输出
bash
zsxq-cli auth status        # Display current logged-in account in table format
zsxq-cli auth status --json # Output in JSON format

退出登录

Logout

bash
zsxq-cli doctor             # 诊断配置和认证是否正常
bash
zsxq-cli doctor             # Diagnose whether configuration and authentication are normal

配置诊断

Configuration Diagnosis

bash
zsxq-cli doctor             # 检查 CLI 配置和 keychain 认证状态
zsxq-cli config show        # 显示版本信息和当前配置
zsxq-cli config show --json # JSON 格式
bash
zsxq-cli doctor             # Check CLI configuration and keychain authentication status
zsxq-cli config show        # Display version information and current configuration
zsxq-cli config show --json # In JSON format

直接调用 API

Direct API Calls

当 Shortcut 无法满足需求时，可以直接调用底层 MCP 工具：
bash
zsxq-cli api list                           # 列出所有可用 MCP 工具及参数
zsxq-cli api call <tool> --params '<json>'  # 调用指定工具
zsxq-cli api raw --method GET --path /v3/users/self
示例：
bash
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"}'
When Shortcuts cannot meet your needs, you can directly call the underlying MCP tools:
bash
zsxq-cli api list                           # List all available MCP tools and parameters
zsxq-cli api call <tool> --params '<json>'  # Call the specified tool
zsxq-cli api raw --method GET --path /v3/users/self
Examples:
bash
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 子命令

Recommendation: Use the explicit-parameter raw subcommand for general HTTP APIs

zsxq-cli api raw --method GET --path /v2/groups/123456789/topics --query '{"count":10}'
undefined
zsxq-cli api raw --method GET --path /v2/groups/123456789/topics --query '{"count":10}'
undefined

安全规则

Security Rules

  • Token 是登录凭证，禁止在终端明文输出或分享给他人
  • 写入/删除操作前必须确认用户意图（发帖、评论、创建笔记等）
  • 不确定 group_id / topic_id 时，先用查询命令确认，再执行写入
  • Token is the login credential, it is prohibited to output it in plaintext in the terminal or share it with others
  • Must confirm user intent before performing write/delete operations (posting, commenting, creating notes, etc.)
  • When unsure about group_id / topic_id, use query commands to confirm first, then execute write operations

常见错误处理

Common Error Handling

错误原因解决方案
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
ErrorCauseSolution
authentication failed (HTTP 401)
Token is invalid or expiredRe-run 
zsxq-cli auth login
not logged in
Login not completedRun 
zsxq-cli auth login
--group-id is required
Missing required parameterFirst query group_id with 
zsxq-cli group +list
--topic-id is required
Missing required parameterFirst query topic_id with 
zsxq-cli group +topics
or 
topic +search