Mp2rss Skill#

通过 Mp2rss CLI（Go 二进制 mp2rss）把 微信公众号 与 X（Twitter）账号 转成 RSS / JSON Feed 并管理订阅。本 skill 是路由入口，按用户意图分发到 references/ 子文档读取详细命令规格。

术语提示：本文档中 "X" 一律指 X（原 Twitter）平台；用作"某个公众号"占位时统一写作 <公众号名> 或具名描述，避免与 X 平台混淆。

⚠️ Agent 必读约束#

🔧 运行时前置#

所有命令通过本地 mp2rss 二进制调用， 不直接打 HTTP。Agent 不应自己拼 API 请求，统一走 CLI 子命令 + -o json 解析。

Base URL 由 CLI 自动决定（命令行 flag > 环境变量 > 配置文件 > 默认 https://mp2rss.bugcode.dev）。

🔑 凭证与登录态#

调用任何 mp2rss mp / mp2rss x 子命令前， 必须先确认登录态：

bash

mp2rss auth status -o json

返回 {"loggedIn": false} 时停止后续调用，引导用户跑 mp2rss auth login，详见 references/auth.md。

凭证优先级（高 → 低）：命令行 --api-key flag > MP2RSS_FEED_KEY 环境变量 > ~/.mp2rss/config.json 配置文件。

🔢 mpId 是 int64 / xUserId 是字符串#

两种业务键形态不同， 不要混用：

• mpId（公众号）：int64 整数。超出 JavaScript Number.MAX_SAFE_INTEGER，Agent 在 JS 环境下解析 mp list / mp articles -o json 输出时 始终把 mpId 当字符串处理： javascript

  const safe = text.replace(/"(mpId)"\s*:\s*(\d+)/g, '"$1":"$2"');
  const data = JSON.parse(safe);
  
  

• xUserId（X 账号）：API 契约即为字符串（虽然内容是数字串），原样消费即可，不必转换。

Python / Go / jq 原生支持大整数，无 mpId 精度问题。

🚫 反幻觉边界#

• 禁止编造 mpId / xUserId：所有业务键必须来自 mp list / mp search / x list 的响应，不得凭空构造
• 禁止跳过订阅参数校验： mp subscribe <url> 的 <url> 必须 是 https://mp.weixin.qq.com/s/... 文章链接；不是公众号名、不是二维码、不是公众号主页。识别不到合法文章 URL 时 反问用户索要任意一篇文章链接，不要直接尝试
• 禁止伪造执行结果：不调用 CLI 不得告诉用户「已订阅」「已删除」
• 禁止忽略 exit code：CLI 返回非 0 必须解析 stderr / JSON envelope 并报告用户
• X 订阅 / 取消订阅必须走 Web 控制台：CLI 与 API 都不暴露 X 写类端点；用户要订阅 X 账号时 只能引导到 https://mp2rss.bugcode.dev/「订阅管理 → X」，不要尝试构造 CLI 写命令

🔄 错误处理#

CLI 错误统一 JSON envelope（见 references/errors.md）：

json

{"error": {"message": "...", "code": <int>}}

Exit code 速查：

Code含义Agent 处理0成功解析 stdout1通用错误（网络 / cobra 解析层：缺参、flag 值非法，此类输出裸文本非 JSON / 限流 429 且 envelope kind: "rate_limited"）网络类报告 + 建议稍后重试；解析类修正参数；限流不要立刻重试，转告 message 里的解锁时间2参数错误（业务校验层）检查参数；若是 mp subscribe 检查 URL 格式3鉴权失败引导跑 mp2rss auth login（见 auth.md）4资源不存在mpId 错 / 文章 URL 失效 / X 账号未订阅（典型 message X account is not subscribed）5上游不可用报告 + 建议稍后重试

---

执行流程概览#

text

用户意图 → 路由匹配 → 读对应 references/xxx.md → 构造 mp2rss 子命令 → 执行 → 解析 JSON / 验证 exit code → 返回结果
                                                                                      ↓
                                                                                  exit ≠ 0 → 按错误码分支处理

关键原则

• CLI 输出是真理：所有状态以 mp2rss xxx -o json 返回为准，不依赖上下文记忆
• -o json 优先：批量 / 结构化场景统一加 -o json（除 auth login 不支持外）
• mpId 字符串化（JS 环境）；xUserId 本身就是字符串

---

指令路由表#

用户意图 / 自然语言角色详细文档「装 mp2rss」「升级 mp2rss」「mp2rss 配置在哪」⚙️ 安装/配置references/install.md「登录」「登出」「我的 Feed Key 是什么」「我登录了吗」🔐 认证references/auth.md「订阅这个公众号 https://mp.weixin.qq.com/s/...」📡 公众号订阅references/mp.md「我订阅了哪些公众号」「列一下我的公众号 RSS」📋 公众号列表references/mp.md「搜一下我订阅的财经类公众号」🔍 公众号搜索references/mp.md「取消订阅 <公众号名>」「把 <公众号名> 从订阅里删了」🗑️ 公众号取消订阅references/mp.md「<公众号名> 最近发了什么」「拉一下 <公众号名> 的文章」📰 公众号文章references/mp.md「我订阅了哪些 X 账号」「列一下我的 X 订阅」🐦 X 列表references/x.md「<X 账号> 最近发了啥」「@xxx 的推文」🐦 X 推文references/x.md「<X 账号> 的长文 / Articles」🐦 X 长文references/x.md「订阅一个 X 账号 / 取消订阅 X」🐦 ⚠️ Web 控制台references/x.md错误码 / JSON envelope / exit code 处理🚨 错误references/errors.md

---

自然语言路由（细分 trigger）#

text

包含 mp.weixin.qq.com/s/ URL              → mp subscribe（参数 = 该 URL）
「订阅」+ 任何 URL 形态                    → 先校验是不是 mp.weixin.qq.com/s/...，否则反问
「订阅了哪些 公众号」「我的公众号」          → mp list
「订阅了哪些 X / Twitter 账号」「我的 X 订阅」 → x list
「搜公众号」「找一下带 关键词 的公众号」      → mp list -q <kw> 或 mp search <kw>
「取消订阅 <公众号名>」「删了 <公众号名>」    → 先 mp list -q <名> 确认 mpId，再 mp remove <mpId>
「<公众号名> 最近发的文章 / 历史文章」        → mp articles <mpId>（先列表确认 mpId）
「@elonmusk 最近的推文」「<X 账号名> 发了啥」  → 先 x list 拿到 xUserId，再 x posts <xUserId>
「<X 账号名> 的长文 / Articles」              → 先 x list，再 x articles <xUserId>
「订阅 / 取消订阅一个 X 账号」               → 引导用户去 Web 控制台「订阅管理 → X」，不要走 CLI
「登录」「授权」                            → auth login（参考 auth.md 选三种登录模式之一）
「我的 Key」「登录了吗」「状态」              → auth status -o json
「登出」「退出登录」                         → auth logout

决策原则：

• 有 mp.weixin.qq.com/s/ URL → 直接 mp subscribe
• 用户给的是 公众号名而非 URL → 反问索要文章 URL，不要先 mp search（搜索是用于在已订阅源里找，不会订阅新号）
• 取消订阅公众号前 先用 mp list -q / mp search 拿到准确 mpId，避免误删
• 用户给 X 账号是 @handle 或显示名 → 先 x list -o json 找 xUserId，不要把 handle 直接传给 x posts / x articles
• 用户想 添加 X 订阅 → 不要尝试 CLI，直接引导 https://mp2rss.bugcode.dev/「订阅管理 → X」

---

API 路由（CLI 子命令总表）#

子命令用途详细文档mp2rss auth login [-k <key>] [--no-browser]登录（三种模式）auth.mdmp2rss auth status [-o json]查询登录态auth.mdmp2rss auth logout登出auth.mdmp2rss mp subscribe <article-url> [-o json]订阅公众号mp.mdmp2rss mp list [-q <kw>] [-p <page>] [--page-size <n>] [-o json]列出公众号订阅mp.mdmp2rss mp search <keyword> [-o json]搜索已订阅公众号mp.mdmp2rss mp remove <mpId> [-y] [-o json]取消订阅公众号mp.mdmp2rss mp articles <mpId> [-p <page>] [--page-size <n>] [-o json]查公众号文章mp.mdmp2rss x list [-q <kw>] [-p <page>] [--page-size <n>] [-o json]列出已订阅 X 账号x.mdmp2rss x posts <xUserId> [-p <page>] [--page-size <n>] [-o json]拉 X 推文流x.mdmp2rss x articles <xUserId> [-p <page>] [--page-size <n>] [-o json]拉 X 长文流x.mdmp2rss update [--check] [--skip-skills]升级 CLIinstall.mdmp2rss skills sync [--global] / status / list同步 / 查看 Agent Skills（CLI ≥ 1.2.0）install.md

X 写类（搜索 / 订阅 / 取消订阅） 不存在对应 CLI 命令，仅 Web 控制台提供，详见 x.md。

---

全局 flag#

所有子命令都支持：

Flag等价环境变量说明-o, --output <table|json>—输出格式，默认 table``--api-key <feed-key>``MP2RSS_FEED_KEY覆盖 Feed Key--api-url <url>``MP2RSS_API_URL覆盖 API 地址

优先级（高 → 低）：CLI flag > env > 配置文件 > 默认。