SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场supsub-mp

supsub-mp

通用与其它

查看项目

更新于 10-16 04:41

技能介绍

supsub-mp 是 SupSub 体系中的微信公众号发现技能，用于在用户想查找或发现一个微信公众号「本身」时使用，典型目的是拿到 mpId 后订阅它。它匹配「搜公众号 X」「找 X 这个公众号」「查 X 公众号」「想订阅 X 公众号但不知道 ID」，以及 discover / find a WeChat MP account 等表述。

【用途】 该技能解决的是「找到某个公众号并获取其标识」的问题。搜索返回的是一批候选公众号，而不是精确匹配的单条结果，因此需要把候选列给用户挑选确认。拿到 mpId 后，下一步是订阅，命令为 supsub sub add --mp-id <mpId>（见 supsub-sub skill）。

【主要能力】

  1. 搜索公众号：supsub mp search <name>，<name> 为公众号名称关键词，建议加引号。命令内部先创建异步任务得到 searchId，CLI 每 2 秒轮询一次任务状态，最多 30 秒；后端在多次轮询中逐条返回候选公众号，CLI 自动累计并按 mpId 去重；收到 finished=true 后一次性输出全部候选。每个候选字段为 mpId、name、img、description、isSubscribed。
  2. 取消搜索任务：supsub mp search-cancel <searchId>，<searchId> 来自上一次搜索在超时分支返回的错误数据。任务不存在或已取消时以 TASK_NOT_FOUND 错误退出。

【使用方式】 前置条件：

  • 安装：curl -fsSL https://raw.githubusercontent.com/SupSub-AI/supsub-cli/master/scripts/install.sh | bash（native 安装，装到 ~/.local、支持后台自动更新）；或使用包管理器 npm i -g @supsub/cli / pnpm add -g @supsub/cli。
  • 已登录：supsub auth status 显示 Authenticated，首次使用先 supsub auth login。
  • 未授权（exit 2 / UNAUTHORIZED）时不要止步于「你未登录」，直接运行 supsub auth login 为用户打开浏览器授权，该命令会自动打开浏览器并阻塞等待授权，请用足够长的超时（如 10 分钟），用户只需在浏览器点确认，无需在终端输入任何内容；授权成功后重试原命令。无浏览器 / 无头环境再回退为提示用户 SUPSUB_NO_BROWSER=1 supsub auth login。

常用命令示例：

  • 同步搜索：supsub mp search "机器之心"
  • JSON 输出：supsub mp search "机器之心" -o json
  • 取消任务：supsub mp search-cancel sid_abc123
  • 取消任务 JSON：supsub mp search-cancel sid_abc123 -o json

JSON 形态：成功时为 {"success":true,"data":[{"mpId":"...","name":"...","img":"...","description":"...","isSubscribed":false}, ...]}；取消成功时为 {"success":true,"data":{"message":"已取消"}}。

搜索到订阅的链路示例：

  1. 列出候选：supsub mp search "机器之心" -o json | jq -r '.data[] | "(.mpId)\t(.isSubscribed)\t(.name)"'。
  2. 与用户确认选中哪一个后，用 --mp-id 订阅：supsub sub add --mp-id "MzA3MzI4MjgzMw==" --group 1166（可顺带 --group <gid> 一步入组）。

【适用场景】

  • 用户想订阅某个公众号但不知道其 ID。
  • 用户想查找或发现某个公众号本身。
  • 需要先获取 mpId 再进入订阅流程的场景。

【限制与注意事项】

  • 搜索返回的是一批候选，不是精确匹配的单条。实测「机器之心」返回 10 条、「阮一峰」返回 5 条，其中可能包含近名号或完全无关的号。绝不要直接取第一条，必须把候选（name + description + isSubscribed）列给用户挑选，确认后再订阅；同名 / 近名多于一条时尤其不能替用户决定。
  • 不要把 mpId 当成 --source-id：mp search 返回的 mpId 是微信原生 base64 字符串（如 MzkyNTYzODk0NQ==），而 supsub sub add --source-id 期望的是 supsub 内部正整数 sourceId（来自 supsub search / sub list），两者属于不同 ID 空间。统一走 --mp-id。
  • isSubscribed 字段可直接用于跳过已订阅的号；若某后端版本缺该字段，再回退到比对 sub list。
  • 轮询参数固定：间隔 2 秒、总时长 30 秒，CLI 不暴露调参 flag。实测一次真实搜索耗时约 15-30 秒（「机器之心」27.4s、「阮一峰」14.7s），因此调用时要把工具超时设到 60 秒以上，并在发起前告知用户这一步约需半分钟。
  • 超时处理：CLI 不提供恢复型查询命令，超时后只有两条路径——重新运行 supsub mp search <name>，或调用 supsub mp search-cancel <searchId> 取消孤儿任务后再试。
  • 未找到时以 MP_NOT_FOUND 错误退出；超时以 MP_SEARCH_TIMEOUT 错误退出，错误体带 data.searchId。
  • Exit codes：0 表示 OK；超时 / 未找到 / 任务不存在等业务错误（后端 4xx）为 1；2 为 UNAUTHORIZED，10 为网络错误，11 为服务端错误（5xx）。
  • 解析结果统一用 -o json；成功时 data 是 Mp[]，失败时走标准 ErrorEnvelope（code、message、可选 data.searchId）。
  • 该技能只负责发现公众号，不负责订阅本身。