unnoo/zsxq-skill/zsxq

知识星球操作指南（CLI / MCP 双通道）

本 Skill 覆盖通过 zsxq-cli（CLI 通道）或底层接口工具 call_zsxq_api（MCP 通道）操作知识星球的所有场景：认证、星球管理、主题管理、用户信息、笔记管理，以及 Skill Pay 微信支付。

默认假设 zsxq-cli 已安装且已登录，无需每次主动检查。只在命令执行报错时才按需处理（见 `references/auth-errors.md`）。

本 Skill 所有示例中的 ID、订单号、支付码等标识均为模拟数据，不对应真实资源。执行操作时必须通过查询结果或用户输入取得并核对真实标识，不得直接复用示例值。

执行通道

本 Skill 的所有能力有两条执行通道，先判定通道再路由：

1. 宿主可执行 zsxq-cli → CLI 通道（优先；shortcut 有参数校验与本地编排，行为最可控）
2. 否则宿主工具列表中存在 call_zsxq_api → MCP 通道
3. 两者都没有 → 停止并提醒用户：安装 CLI（见 `references/auth-errors.md`）或在宿主中接入知识星球 MCP（密钥管理页创建 api-key 后复制链接接入），由用户选择

• 通道判定是一次性环境探测；选定后一致使用，不混用。仅当某操作标注「仅 CLI 通道」/「仅 MCP 通道」时，对该操作单独切换或告知用户。
• MCP 通道下所有调用都通过底层接口工具 call_zsxq_api（参数 {method, path, query?, body?}）；不得臆造未文档化的 method/path——能力底表见 `references/endpoint-catalog.md`，未覆盖即视为不支持。
• 「执行模式」路由（场景 → 原子 → 探索）在两条通道下相同；通道只决定各 reference「## 命令」节使用哪一组调用块。

执行模式

按以下顺序路由用户请求，命中即执行，不再往下走：

1. 场景模式 — 请求命中已注册场景：读场景入口文档，按流程编排原子操作
2. 原子操作 — 请求明确对应一个常用操作：读对应 reference，直接调用推荐命令
3. 探索模式 — 都未命中：按 `references/cli-exploration.md` 通过 CLI 帮助和 API 列表发现能力

原子操作和场景执行时不得预先运行无关的 doctor、--help 或 api list。仅在能力不匹配或调用失败时回退到探索模式。

快速索引

根据用户意图，直接跳转到对应小节或 reference：

资源关系

User (user_id) — 已登录账户
│
├── Group (group_id) — 星球/社群
│   ├── Topic (topic_id) — talk / q&a / task / solution
│   │   ├── Comment (comment_id)
│   │   │   └── 楼中楼 Reply (replied_comment_id)
│   │   ├── Answer — q&a 类型专属
│   │   └── Hashtag 标签
│   ├── Scheduled Job (job_id) — 定时发布主题/回答，每星球上限 10
│   └── Hashtag (hashtag_id)
│       └── Topic 列表
│
└── Note (note_id) — 公开笔记，不属于任何星球

核心概念

• 星球（Group）：知识星球的社群单元，由 group_id（纯数字）唯一标识。用户可以是创建者或成员。
• 主题（Topic）：星球内的内容单元，类型：talk（帖子）、q&a（提问）、task（作业）、solution（作业答案）。
• 笔记（Note）：独立于星球的内容单元，公开可见，任何持有链接的人都能访问 —— 不是私密备忘录。
• 评论（Comment）：主题下的回复，支持楼中楼（replied_comment_id）。
• 精华（Digested）/ 置顶（Sticky）：有管理权限（星主 / 管理员 / 合伙人）可将主题设为精华或置顶，改变其在星球内的展示。
• 定时任务（Scheduled Job）：主题或回答可以定时在未来某个时间点自动发布（14 天窗口内），每星球上限 10 个。

安全规则

• 禁止输出或传播认证 token —— token 是登录凭证，不在终端明文输出，不分享给他人
• 写入/删除操作前必须确认用户意图（发帖、编辑、评论、回答、定时发布、设置精华/置顶、修改星球资料、创建笔记、删除主题或笔记、取消定时任务、提交 NPS 反馈等）
• Skill Pay 仅支持 WorkBuddy 且宿主必须提供官方 `weixinpay_pay`；任一条件不满足时，必须在创建订单前说明不支持并停止，不得调用 call_zsxq_api 创建订单
• 创建订单前必须按原子 reference 查询或计算价格，并确认类型、对象与实际应付金额；固定价格不得由用户改写，支付必须由用户本人授权；PAYMENT_REQUIRED 即使返回 success: false 也只表示待支付，不代表失败或支付成功，禁止自动重试创建订单
• 不确定 group_id / topic_id / comment_id / note_id 时，先用查询命令确认，再执行写入或删除
• 笔记是公开内容，任何持有链接的人均可访问 —— 涉及隐私或敏感信息不要写进笔记
• api raw 写入不得绕过原子操作的安全约束；探索模式发现的写入接口同样需要用户确认
• 各写入/删除 reference 的 > [!CAUTION] 块列出该操作特有的确认项
• 通道选定后一致使用不混用；MCP 通道不得臆造未在 reference 或 endpoint-catalog 中文档化的 method/path

场景（Scenarios）

场景表达业务目标，由多个原子操作编排而成。SKILL.md 只链接场景入口，流程细节见入口文档。

Skill Pay

处理 Skill Pay 购买意图时，读取购买场景进行编排；创建订单、价格、支付授权和安全恢复的参数与错误语义只以原子 reference 为准。

• 购买场景：`scenarios/purchase-with-skill-pay.md`
• 创建订单原子操作：`wechat-order-create.md`

星球管理（group）

API（`zsxq-cli api call`）：

原始 HTTP 调用：

成员列表的 expired_time 仅付费星球星主/管理员可见。主题的专栏归属为主题维度操作，见主题管理的原始 HTTP 调用。

反例（不要做）

主题管理（topic）