mp2rss-x

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

mp2rss-x Skill

通过 Mp2rss CLI 管理 X（Twitter）信息源的只读访问 —— 列出已订阅 X 账号、按 xUserId 拉推文与长文。

Provides read-only access to X (Twitter) feeds through the Mp2rss CLI — list subscribed X accounts and fetch posts and long-form articles by xUserId.

Prerequisites

```
mp2rss
```
二进制已安装（参考
```
mp2rss-auth
```
的 Prerequisites）

已登录：

mp2rss auth status

显示

loggedIn: true

（首次使用先跑

mp2rss auth login

）

要操作的 X 账号已在 Web 控制台订阅（CLI 不支持
```
subscribe
```
）

The
```
mp2rss
```
binary is installed (see the Prerequisites for
```
mp2rss-auth
```
)

You are logged in:

mp2rss auth status

displays

loggedIn: true

(run

mp2rss auth login

before first use)

The X account you want to work with has already been subscribed to via the Web console (the CLI does not support
```
subscribe
```
)

范围边界（重要）

Scope boundaries (important)

操作	CLI 是否支持	去哪里做
`x list` —— 列已订阅 X 账号	✅	本 skill
`x posts` —— 拉推文流	✅	本 skill
`x articles` —— 拉长文流	✅	本 skill
`x subscribe` —— 订阅新 X 账号	❌	https://mp2rss.bugcode.dev Web 控制台
`x remove` —— 取消订阅 X 账号	❌	https://mp2rss.bugcode.dev Web 控制台
`x search` —— 搜索 X 账号	❌	https://mp2rss.bugcode.dev Web 控制台

用户说「订阅这个 X 账号」/「把 X 上的 xxx 加进来」/「搜一下 X 上的 xxx」时，不要尝试构造
mp2rss x subscribe
之类的命令（不存在），直接告诉用户去 Web 控制台操作。

Operation	Supported by CLI	Where to do it
`x list` — List subscribed X accounts	✅	This skill
`x posts` — Fetch the post feed	✅	This skill
`x articles` — Fetch the long-form article feed	✅	This skill
`x subscribe` — Subscribe to a new X account	❌	https://mp2rss.bugcode.dev Web console
`x remove` — Unsubscribe from an X account	❌	https://mp2rss.bugcode.dev Web console
`x search` — Search for X accounts	❌	https://mp2rss.bugcode.dev Web console

When users say “Subscribe to this X account” / “Add xxx from X” / “Search for xxx on X,” do not attempt to construct commands such as
mp2rss x subscribe
(they do not exist); simply tell the user to use the Web console.

Commands

List subscribed X accounts

mp2rss x list [-q <keyword>] [-p <page>] [--page-size <n>] [-o json]

Flag	Default	Description
`-q, --query`	—	按 displayName / username 模糊搜索（仅 server 支持时生效；不支持时退化为客户端筛 X 项）
`-p, --page`	1	页码
`--page-size`	20	每页条数（最大 50）
`-o, --output`	table	`table` / `json`

bash

mp2rss x list
mp2rss x list -q claude
mp2rss x list -p 2 --page-size 50
mp2rss x list -o json | jq '.items[].xDisplayName'

底层调

GET /open-api/subscriptions?sourceType=x

；若 server 不识别

sourceType

，CLI 客户端会兜底剔除 mp 项。

JSON shape:

json

{
  "items": [
    {
      "sourceType": "x",
      "xUserId": "44196397",
      "xUsername": "elonmusk",
      "xDisplayName": "Elon Musk",
      "xAvatarUrl": "https://...",
      "xVerified": true,
      "xLastItemAt": 1705000050000,
      "createdAt": 1705000000000
    }
  ],
  "total": 12,
  "page": 1,
  "pageSize": 20
}

mp2rss x list [-q <keyword>] [-p <page>] [--page-size <n>] [-o json]

Flag	Default	Description
`-q, --query`	—	Fuzzy search by displayName / username (only effective when supported by the server; otherwise, it falls back to filtering X items on the client)
`-p, --page`	1	Page number
`--page-size`	20	Number of items per page (maximum 50)
`-o, --output`	table	`table` / `json`

bash

mp2rss x list
mp2rss x list -q claude
mp2rss x list -p 2 --page-size 50
mp2rss x list -o json | jq '.items[].xDisplayName'

Calls

GET /open-api/subscriptions?sourceType=x

internally; if the server does not recognize

sourceType

, the CLI client falls back to removing mp items.

JSON shape:

json

{
  "items": [
    {
      "sourceType": "x",
      "xUserId": "44196397",
      "xUsername": "elonmusk",
      "xDisplayName": "Elon Musk",
      "xAvatarUrl": "https://...",
      "xVerified": true,
      "xLastItemAt": 1705000050000,
      "createdAt": 1705000000000
    }
  ],
  "total": 12,
  "page": 1,
  "pageSize": 20
}

List posts (推文流)

List posts (post feed)

mp2rss x posts <xUserId> [-p <page>] [--page-size <n>] [-o json]

按

postedAt DESC

分页拉某个已订阅 X 账号的推文。

Flag	Default	Description
`-p, --page`	1	页码
`--page-size`	20	每页条数（最大 50）
`-o, --output`	table	`table` / `json`

bash

mp2rss x posts 44196397
mp2rss x posts 44196397 -p 2 --page-size 50
mp2rss x posts 44196397 -o json | jq '.items[].content'

JSON shape:

json

{
  "items": [
    {
      "postId": "1234567890",
      "content": "推文正文",
      "media": [{"url": "https://...", "type": "image"}],
      "retweetedPost": null,
      "quotedPost": null,
      "threadPosts": [],
      "postedAt": 1705000000000
    }
  ],
  "total": 87,
  "page": 1,
  "pageSize": 20
}

字段说明：

```
media
```
—— 推文附带的图片 / 视频，
```
type
```
取值如
```
image
```
/
```
video
```
```
retweetedPost
```
/
```
quotedPost
```
—— 原始推文的嵌套对象（可能为
```
null
```
）
```
threadPosts
```
—— 同一作者的线程后续推文（可能为空数组）
未订阅的
```
xUserId
```
返回 404
```
X account is not subscribed
```
（exit code
```
4
```
）

mp2rss x posts <xUserId> [-p <page>] [--page-size <n>] [-o json]

Retrieves the post feed of a subscribed X account in pages, sorted by

postedAt DESC

Flag	Default	Description
`-p, --page`	1	Page number
`--page-size`	20	Number of items per page (maximum 50)
`-o, --output`	table	`table` / `json`

bash

mp2rss x posts 44196397
mp2rss x posts 44196397 -p 2 --page-size 50
mp2rss x posts 44196397 -o json | jq '.items[].content'

JSON shape:

json

{
  "items": [
    {
      "postId": "1234567890",
      "content": "推文正文",
      "media": [{"url": "https://...", "type": "image"}],
      "retweetedPost": null,
      "quotedPost": null,
      "threadPosts": [],
      "postedAt": 1705000000000
    }
  ],
  "total": 87,
  "page": 1,
  "pageSize": 20
}

Field descriptions:

```
media
```
— Images or videos attached to the post;
```
type
```
can be a value such as
```
image
```
/
```
video
```
```
retweetedPost
```
/
```
quotedPost
```
— Nested objects for the original post (may be
```
null
```
)
```
threadPosts
```
— Follow-up posts by the same author in the same thread (may be an empty array)
An unsubscribed
```
xUserId
```
returns 404
```
X account is not subscribed
```
(exit code
```
4
```
)

List articles (长文流)

List articles (X Articles feed)

mp2rss x articles <xUserId> [-p <page>] [--page-size <n>] [-o json]

按

publishedAt DESC

分页拉某个已订阅 X 账号的长文（X Articles）。

Flag	Default	Description
`-p, --page`	1	页码
`--page-size`	20	每页条数（最大 50）
`-o, --output`	table	`table` / `json`

bash

mp2rss x articles 44196397
mp2rss x articles 44196397 -p 2 --page-size 50
mp2rss x articles 44196397 -o json | jq '.items[].title'

JSON shape:

json

{
  "items": [
    {
      "url": "https://x.com/.../article/...",
      "title": "长文标题",
      "description": "长文摘要",
      "contentMarkdown": "# Markdown 正文（可能为 null）",
      "coverUrl": "https://...",
      "publishedAt": 1705000000000
    }
  ],
  "total": 3,
  "page": 1,
  "pageSize": 20
}

未订阅的
```
xUserId
```
返回 404
```
X account is not subscribed
```
（exit code
```
4
```
）
```
contentMarkdown
```
是上游推送的 markdown 原文，可能为
```
null
```

mp2rss x articles <xUserId> [-p <page>] [--page-size <n>] [-o json]

Retrieves the long-form article feed (X Articles) of a subscribed X account in pages, sorted by

publishedAt DESC

Flag	Default	Description
`-p, --page`	1	Page number
`--page-size`	20	Number of items per page (maximum 50)
`-o, --output`	table	`table` / `json`

bash

mp2rss x articles 44196397
mp2rss x articles 44196397 -p 2 --page-size 50
mp2rss x articles 44196397 -o json | jq '.items[].title'

JSON shape:

json

{
  "items": [
    {
      "url": "https://x.com/.../article/...",
      "title": "长文标题",
      "description": "长文摘要",
      "contentMarkdown": "# Markdown 正文（可能为 null）",
      "coverUrl": "https://...",
      "publishedAt": 1705000000000
    }
  ],
  "total": 3,
  "page": 1,
  "pageSize": 20
}

An unsubscribed
```
xUserId
```
returns 404
```
X account is not subscribed
```
(exit code
```
4
```
)
```
contentMarkdown
```
is the original Markdown content supplied by the upstream provider and may be
```
null
```

Agent Usage Notes

xUserId
是字符串（X 平台原生数字 ID，序列化为 string），不要按 number 解析；
```
mp2rss mp
```
那边的
```
mpId
```
才是 int64
解析批量输出统一加
```
-o json
```
时间字段均为 unix 毫秒数（number）：
```
createdAt
```
/
```
xLastItemAt
```
/
```
postedAt
```
/
```
publishedAt
```

字段命名统一 camelCase：

xUserId

xUsername

xDisplayName

xAvatarUrl

xVerified

xLastItemAt

sourceType

postId

coverUrl

contentMarkdown

不存在的子命令：
```
x subscribe
```
/
```
x remove
```
/
```
x search
```
—— 用户提相关需求时直接引导去 Web 控制台 https://mp2rss.bugcode.dev，不要去 CLI 里找替代命令
```
x posts
```
/
```
x articles
```
都带分页元数据（
```
total
```
/
```
page
```
/
```
pageSize
```
）—— 这一点与
```
mp articles
```
（无分页字段）不同，按
```
total
```
判断是否还有下一页即可
```
--page-size
```
三个命令一致上限 50；超过会返回
```
参数错误
```
（exit code
```
2
```
）
限流：与 mp 命令共用每个 Feed Key 60 次/分钟的额度；CLI 自动间隔 ≥ 1.2s 并按
```
Retry-After
```
等待重试一次，仍被拒时 envelope 带
```
"kind":"rate_limited"
```
，不要立刻重试
```
x list -q <kw>
```
的
```
-q
```
走服务端模糊搜索 displayName / username；若服务端不识别，CLI 会退化为按
```
sourceType=x
```
客户端过滤（即
```
-q
```
失效，但不会报错）

拿到

xUserId

的常规链路：先跑

mp2rss x list -o json

从

items[].xUserId

取，再喂给

x posts

x articles

错误 JSON 形态：
```
{"error":{"message":"...","code":<int>}}
```
；
```
code
```
优先用 HTTP 状态码（来自上游），否则回退到 CLI exit code（参数 / 鉴权类错误）
Exit codes：
```
0
```
成功；
```
1
```
通用错误（网络）；
```
2
```
参数错误（含
```
--page-size
```
越界）；
```
3
```
鉴权失败 → 引导用户跑
```
mp2rss auth login
```
（参考
```
mp2rss-auth
```
skill）；
```
4
```
资源不存在（
```
xUserId
```
未订阅或不存在）；
```
5
```
上游不可用

xUserId
is a string (the native numeric ID on the X platform, serialized as a string); do not parse it as a number.
```
mpId
```
on the
```
mp2rss mp
```
side is int64
Use
```
-o json
```
consistently when parsing bulk output
All time fields are Unix timestamps in milliseconds (number):
```
createdAt
```
/
```
xLastItemAt
```
/
```
postedAt
```
/
```
publishedAt
```

Field names consistently use camelCase:

xUserId

xUsername

xDisplayName

xAvatarUrl

xVerified

xLastItemAt

sourceType

postId

coverUrl

contentMarkdown

Nonexistent subcommands:
```
x subscribe
```
/
```
x remove
```
/
```
x search
```
— when users request these actions, direct them to the Web console at https://mp2rss.bugcode.dev; do not look for alternatives in the CLI
Both
```
x posts
```
and
```
x articles
```
include pagination metadata (
```
total
```
/
```
page
```
/
```
pageSize
```
). This differs from
```
mp articles
```
(which has no pagination fields); use
```
total
```
to determine whether another page exists
```
--page-size
```
has a maximum of 50 across all three commands; exceeding it returns
```
参数错误
```
(exit code
```
2
```
)
Rate limiting: the x and mp commands share a quota of 60 requests per minute per Feed Key. The CLI automatically spaces requests by at least 1.2 seconds and waits according to
```
Retry-After
```
for one retry. If the request is still rejected, the envelope contains
```
"kind":"rate_limited"
```
; do not retry immediately
For
```
x list -q <kw>
```
,
```
-q
```
performs a server-side fuzzy search by displayName / username. If the server does not recognize it, the CLI falls back to client-side filtering by
```
sourceType=x
```
(meaning
```
-q
```
has no effect, but no error is reported)
Standard flow for obtaining an
```
xUserId
```
: first run
```
mp2rss x list -o json
```
, retrieve
```
items[].xUserId
```
, and then pass it to
```
x posts
```
/
```
x articles
```
Error JSON shape:
```
{"error":{"message":"...","code":<int>}}
```
; prioritize the HTTP status code for
```
code
```
when supplied by the upstream service, and otherwise fall back to the CLI exit code (parameter / authentication errors)
Exit codes:
```
0
```
success;
```
1
```
generic error (network);
```
2
```
invalid parameters (including an out-of-range
```
--page-size
```
);
```
3
```
authentication failure → direct the user to run
```
mp2rss auth login
```
(see the
```
mp2rss-auth
```
skill);
```
4
```
resource not found (
```
xUserId
```
is unsubscribed or does not exist);
```
5
```
upstream service unavailable