pi-x 发布：让 Pi 编码智能体通过已登录浏览器读取 X 趋势与搜索

让你的 Pi agent 拥有 X 的眼睛——热门话题、新闻，以及它们为何流行。无需 API 密钥。

pi-x 是一个 Pi 扩展，让你的编码 agent 通过 你自己已登录的浏览器会话读取 X（Twitter）——热门话题和新闻、带真实统计的关键词搜索、推文串和用户资料。无需开发者账号，无需每月 200 美元的 API 套餐，无需把 cookie 交给第三方脚本。

演示

> What's trending on X right now and why?

Trending — Worldwide
 1. #PPxSTAKE
 2. #BELTUR
 3. #PlsLoveรักได้ไหมEP4
 4. LENAMIU PLS LOVE EP4
 5. #TaşacakBuDeniz

Why it's trending (top posts per trend):

▸ #PPxSTAKE — 20 posts sampled
Stats: 20 posts over 1.1h (18.2/h) · 2026-10-02 18:03 → 2026-10-02 19:07
  likes 4.6K (median 2) · reposts 2.5K · replies 14K · views 87K
  verified authors 70%
  top voices: @pp_privatejet_2 (2, score 42K), @Junsznx (1, score 49), @aikawins (2, score 46)

这只是用 drilldown: 1 对 x_trending 的一次调用——一个真实的热门话题，真实的互动数据，从 X 实时采样。没有抓取的 HTML 转储，没有“我无法访问实时数据”。

为什么选择 pi-x

免费——运行在你已登录的 X 会话上。无需 API 密钥，无按次调用费用。
热门话题 + 新闻 + 深入挖掘——不只是热门话题列表：带热度量和时效的 X News 报道，以及一个 drilldown，它会为每个热门话题采样热门帖子，让 agent 能解释某件事为何火爆。
为 LLM 打造的统计数据——每个搜索/热门话题结果都附带一个紧凑的统计块（速度、中位数、认证用户占比、头部声音/话题标签/网站），而不是一堵原始 JSON 墙。
自愈——在运行时发现 X 的内部 API 查询 ID 和功能，并在 X 更改某些内容时回退到页面抓取，而不是直接崩溃。
多账号轮换——添加多个账号；pi-x 会轮换并在遇到速率限制时退避。
Cookie 永不离开浏览器——调用在已登录页面内部运行；pi-x 从不提取你的 cookie 或将其发送到任何地方。
默认只读——不发布、不点赞、不关注。DM 访问（读取你的收件箱、发送你确认的私信）通过 /x write on 选择启用。

pi-x 对比

	pi-x	官方 X API	Scweet	twscrape	twikit	Agent-Reach / twitter-cli
无需 API 密钥	✅	❌（搜索约每月 200 美元起）	✅	✅	✅	✅
热门话题 + 新闻	✅	—	❌	✅（仅热门话题）	✅（仅热门话题）	❌
解释为何流行	✅	—	❌	❌	❌	❌
LLM 规模的统计块	✅	—	❌	❌	❌	❌
Cookie 留在浏览器中	✅	不适用	❌（读取 `auth_token`）	❌（存储 cookie）	❌（存储 cookie）	❌（读取 cookie）
Agent 原生（Pi 工具，而非库）	✅	❌	❌	❌	❌	⚠️ CLI，非 Pi 原生

来源已对照各项目自身的代码/文档核查，截至 2026-10-01——完整调研见 docs/superpowers/specs/2026-10-01-pi-x-v1-design.md。Scweet、twscrape 和 twikit 是 Python 库；Agent-Reach 是一个多平台 CLI 路由器，对 X 而言它委托给 twitter-cli（自身没有热门话题）。架构上最接近的是 OpenCLI 的 twitter 命令，它也在已登录的浏览器页面内运行——但其热门话题仅基于 DOM，没有深入挖掘、统计数据或 Pi 集成。

安装

需要 Pi ≥ 0.99、Node ≥ 22.18（用于开发），以及 agent-browser CLI：

npm i -g agent-browser && agent-browser install

然后，在 Pi 中：

pi install npm:@hett/pi-x
# or try it once without installing:
pi -e npm:@hett/pi-x
# or track the latest main branch:
pi install git:github.com/hett-patell/pi-x

快速开始

/x login

在打开的浏览器窗口中完成登录（Google、Apple 或密码 + 2FA）——pi-x 会自行确认登录并关闭窗口。然后只需问：

What's trending on X right now, and why?

工具

工具	关键参数	功能
`x_trending`	`location?`、`tab?`（trending/news/sports/entertainment）、`include_news?`、`limit?`、`drilldown?`（0–5）	排名热门话题 + X News 报道；`drilldown` 为每个热门话题采样热门帖子以解释其为何流行。标记自上次检查以来 `NEW` 的热门话题。
`x_search`	`query`、`type?`（Latest/Top/Media）、`limit?`（≤300）、`from`/`to`/`mentions`、`since`/`until`、`lang`、`min_likes`/`min_retweets`/`min_replies`、`has`、`exclude`、`verified_only`、`near`/`within`、`cursor`	带分页和统计块（速度、中位数、认证用户占比、头部声音/话题标签/网站、最早的重要帖子）的筛选搜索。
`x_tweet`	`id_or_url`、`replies?`（0–100）	读取一条帖子及其完整互动 + 引用链；使用 `replies` 时，还会读取作者的推文串和按互动量排序的热门回复。
`x_user`	`username`、`posts?`（0–100）	个人资料（简介、关注者、认证状态、加入时间）；包含`posts`、其近期帖子及统计数据。
`x_doctor`	—	逐账号实时登录检查、API 发现报告、精确修复方案。如果发现任何异常，请先运行此项。
`x_dm_inbox`	`account?`	你近期的 1:1 私信对话：对方是谁、最后一条消息、未读状态。需要 `/x write on`。
`x_dm`	`to`、`text`、`account?`	发送一条私信。需要 `/x write on`；你需在 Pi UI 中确认每一条消息。仅发送一次，仅从一个账号发出——绝不轮换或重试。

命令

命令	功能说明
`/x status`	账号、登录状态、轮换、趋势位置
`/x login [account]`	连接一个 X 账号（打开浏览器窗口）
`/x logout [account]`	断开连接并删除该账号的浏览器配置文件
`/x add <name>`	添加另一个 X 账号槽位
`/x remove <account>`	移除一个账号（浏览器配置文件保留在磁盘上）
`/x use <account\|auto>`	固定工具使用的账号（`auto` = 轮换）
`/x enable <account>`	将某账号纳入轮换
`/x disable <account>`	将某账号排除出轮换
`/x proxy <account> [url\|off]`	设置或清除某账号的代理
`/x import-chrome <account>`	为某账号复用你桌面版 Chrome 的登录状态
`/x location [place\|default]`	`x_trending` 的默认区域
`/x write on\|off [--no-confirm]`	允许私信访问：读取收件箱 + 发送（默认关闭）。`--no-confirm` 跳过逐条消息确认提示，例如用于无头模式
`/x doctor`	完整健康检查并附带修复方案
`/x backup [account]`	将账号的登录状态保存到文件（0600）
`/x restore [account]`	恢复已保存的登录状态
`/x close`	关闭所有 pi-x 浏览器窗口
`/x help`	显示所有命令

示例提示词

“X 上现在有什么热门话题，为什么？”
“今天印度有什么热门话题？” （按地点名称或 WOEID 查询位置趋势）
“X 上有什么新闻？” （tab: "news"）
“人们对新 iPhone 有什么看法，主要抱怨是什么？”
“在 X 上搜索‘AI agents’，热门帖子，最少 20 个赞”
“查找关于地震的近期帖子，排除转推，最近 24 小时”
“总结这个帖子串：https://x.com/user/status/12345” （含回复反应）
“人们怎么看待这个帖子的回复？”
“查一下 @someaccount——他们是可信来源吗？”
“pi-x 的 X 会话是不是失效了？运行一次诊断。”

工作原理

 agent calls x_trending / x_search / x_tweet / x_user
                      │
                      ▼
        ┌─────────────────────────┐
        │  in-page X API engine   │  runs fetch() inside your logged-in
        │  (xapi.ts + page.ts)    │  x.com tab — cookies never leave it
        └────────────┬────────────┘
                      │ needs a query ID / feature flag it hasn't seen?
                      ▼
        ┌─────────────────────────┐
        │  runtime API discovery  │  finds the current GraphQL query ID
        │                         │  from X's own loaded JS, caches it
        └────────────┬────────────┘
                      │ X changed the page layout, discovery fails?
                      ▼
        ┌─────────────────────────┐
        │   DOM scrape fallback   │  reads the rendered page instead
        │        (dom.ts)         │  of calling the API at all
        └─────────────────────────┘

 rate limit / lock on one account → back off, rotate to the next enabled account

账号轮换默认采用最近最少使用原则（/x use <account> 可固定某一个）；每个账号的锁可防止两个工具争抢同一个浏览器标签页。

不支持多个 Pi 实例同时针对同一个 X 账号运行：锁是按进程隔离的，退出其中一个 Pi 会关闭其他实例正在使用的 pi-x 浏览器会话。

隐私与安全

Cookie 保留在 ~/.pi/agent/pi-x/profiles 下的浏览器配置文件中（目录 0700），pi-x 绝不会提取或将其发送到任何地方。页面内代码仅在页面内部读取 X 的 ct0 CSRF 令牌，用于授权 X 自身的请求，与 x.com 的行为完全一致。
/x backup 会将账号的登录状态（含 Cookie）写入 ~/.pi/agent/pi-x/state/<account>.json——位于 0700 目录内的 0600。请妥善保管该文件；任何持有它的人都能使用你的 X 会话。
配置（~/.pi/agent/pi-x/config.json）写入 0600。
代理凭据在每条消息、日志和工具输出中均被遮蔽。
默认只读：不发布、不点赞、不关注，私信不受影响。/x write on 允许 x_dm_inbox 读取你的私信，x_dm 允许发送私信。每次发送都会显示收件人和文本供你批准（除非你选择了 --no-confirm），仅从一个账号发出，且绝不重试——因此不会出现重复消息或来自错误账号的消息。
如果你不放心连接主账号，请使用备用/小号 X 账号。
你有责任遵守 X 的服务条款和速率限制——pi-x 会在遇到速率限制时自动退避，但不会绕过它们。

从 0.x 升级

pi-x 1.0 是一次完全重写。首次运行时，它会自动迁移你的配置，从 ~/.pi/x-insights.json 迁移到 ~/.pi/agent/pi-x/config.json——无需任何操作。有几点需要了解：

SocialData 已移除。 x_search 和 x_user 现在使用你已登录的浏览器会话，而不是付费密钥。任何 SOCIALDATA_API_KEY 或已保存的密钥都不再使用，可以删除。
x_scrape_topic 已合并到 x_search —— 请改用带过滤器的 x_search。
/x setkey / /x clearkey 已移除；如果你运行它们，pi-x 会提示你。
如果你之前手动复制了旧扩展，请删除 ~/.pi/agent/extensions/x-insights.ts，以免它遮蔽已安装的包。

故障排除

错误	修复
`browser_missing`	`npm i -g agent-browser && agent-browser install`
`chrome_missing`	`agent-browser install`（Linux：`agent-browser install --with-deps`）
`profile_busy`	该账户的个人资料已在另一个 Chrome 窗口中打开 —— 请关闭它（或 `/x close`）后重试
`not_logged_in`	`/x login <account>`
`account_locked`	在普通浏览器中为该账户打开 x.com，完成 X 的解锁验证，然后 `/x login <account>`
`rate_limited`	等待几分钟，降低 `limit`，或添加另一个账户（`/x add <name>`，然后 `/x login <name>`）
`timeout`	重试；如果持续发生，`/x doctor`（网络或代理慢？）
`aborted`	已取消 —— 无需操作
`not_found`	检查 ID/handle —— 该帖子或账户可能已被删除、设为受保护或已停用
`api_changed`	X 更改了其内部 API。运行 `x_doctor`；工具会尽可能回退到页面抓取
`dom_changed`	X 更改了其页面布局。运行 `x_doctor`，更新 pi-x（`pi update`），或在 https://github.com/hett-patell/pi-x/issues 报告问题
`invalid_input`	修正参数后重试
`network`	检查你的连接/代理并重试

开发

npm install
npm test        # unit tests against recorded fixtures
npm run check   # tsc -p .
npm run smoke   # live smoke test against real X — needs a logged-in account

项目结构：

extensions/pi-x/
  index.ts         tool registration (x_trending, x_search, x_tweet, x_user, x_dm, x_dm_inbox, x_doctor), /x wiring
  commands.ts      /x command handling, SUBCOMMANDS, status footer, login watcher
  deps.ts          builds the shared ToolDeps (lazy agent-browser runner, sessions, engine, locks)
  config.ts        config load/save, 0.x migration, account validation, managed-profile check
  accounts.ts      account lookup/rotation order, proxy/secret masking
  browser.ts       spawns agent-browser (only module that does), sessions, per-account locks
  page.ts          page-side code (String.raw, runs inside the logged-in tab)
  xapi.ts          in-page X GraphQL engine + runtime query-ID discovery
  dom.ts           DOM-scrape fallback when the API engine can't be used
  normalize.ts     parse X payloads into Tweet / XUser / Trend / Place
  score.ts         engagement score, dedupe, search filters → query, stats
  format.ts        compact text rendering + OUTPUT_BUDGET fitting
  errors.ts        XErrorCode, FIXES, XError
  util.ts          clamp, unique, abortable sleep
  tools/           context.ts (shared deps, account rotation, pagination) + one module per tool
                   (trending, search, tweet, user, doctor)
skills/pi-x/       SKILL.md — how an agent should route requests and write insights
test/              unit tests + recorded fixtures
scripts/smoke.ts   live smoke script (npm run smoke)

免责声明

pi-x 自动化你自己的浏览器会话，代表你读取公开可见的 X 内容。它不会发帖、点赞、关注或向任何人发送消息。你有责任遵守 X 的服务条款和你所在司法管辖区的适用法律。与 X Corp. 无关联，也未获其认可。

许可证

MIT