imjszhang/js-eyes/js-x-ops-skill

js-x-ops-skill

面向 x.com / twitter.com 的 skill。v3.0 起切到 PAGE_PROFILES + Bridges + Session 架构，参考 js-reddit-ops-skill 的设计取舍：

• 数据获取：READ 数据优先走 X.com 内部 GraphQL 同源端点（/i/api/graphql/<queryId>/<op>），与浏览器同源、复用 cookie + bearer；DOM 解析（bridges/common.js::parseTweetArticle）保留为兜底
• safety 分级：READ + INTERACTIVE 已经落地；DESTRUCTIVE（reply / post / quote / thread）目前透传 v2.0.1 的 scripts/x-post.js，v3.1 拆 compose-bridge 后将走 `--confirm` + 默认 `--dry-run`

依赖与前置

• Node.js 22+、JS Eyes 2.8.5+；JS Eyes Server 已启动（js-eyes server start）
• 浏览器扩展：已安装并连上 server
• 登录态：浏览器里已经人工登录 x.com（本 skill 不做任何登录自动化）；READ 工具默认 navigateOnReuse=false / reuseAnyXTab=true，bridge 在任意 x.com / twitter.com tab 里 fetch 同源 GraphQL；用户当前 tab 不会被切走
• Raw Eval：bridge 首次注入需要宿主设置 security.allowRawEval: true；JS Eyes 2.5+ 会把该设置同步到扩展，扩展存储中的显式 false 仍可强制关闭
• Chrome：要求 135+；Chrome 138+ 还需开启浏览器控制的 Allow User Scripts

安全红线（READ / INTERACTIVE / DESTRUCTIVE）

本 skill 的所有工具都会被归入以下三档之一。审计界线按「是否改 X 业务数据」而非「是否触网」来划：

READ（默认档）

纯读，不改任何 DOM、不改 URL、不触发任何业务写操作。

• 走 fetchXGraphQL(opName, vars, features) 调 X.com 内部 GraphQL（GET，复用浏览器同源 cookie + 写死 bearer）
• DOM 路径仅作为 bridge 失败时的兜底，由 bridges/common.js::parseTweetArticle / collectTweetsFromDom 提供
• 工具：x_search_tweets / x_get_profile / x_get_post / x_get_home_feed / x_session_state

INTERACTIVE（v3.0+）

只改浏览器自己的 URL，不改 X 侧任何业务数据。实现硬约束：

• 仅 location.assign(newUrl)，禁止模拟点击任何 DOM CTA
• bridge 端 navigateLocation() 拒绝跨域 URL（必须是 *.x.com / *.twitter.com）
• 调用返回 {from, to, hint}，CLI 端 awaitBridgeAfterNav 重注 bridge + state 自校验
• skill.definition.js 里带 interactive: true / destructive: false
• 工具：x_navigate_search / x_navigate_profile / x_navigate_post / x_navigate_home

DESTRUCTIVE（v3.0 透传 v2 行为，v3.1 拆专用工具）

x_get_post 的 schema 里仍保留 --reply / --post / --quote / --thread / --image / --thread-delay / --thread-max / --reply-style 等写参数（v2.0.1 行为，CLI 透传 scripts/x-post.js），description 标 deprecated。等 v3.1 完成后：

• 拆 bridges/compose-bridge.js：DESTRUCTIVE 唯一入口
• 4 个独立工具：x_create_tweet / x_reply_tweet / x_quote_tweet / x_create_thread
• 默认 --dry-run，必须显式 --confirm 才落地
• 砍掉 x_get_post 的写参数

提供的 AI 工具

全部工具都是 optional: true（按需加载），入参详见 skill.definition.js::TOOL_DEFINITIONS。

Monitor（账号监控，5 个受控 AI 工具 + CLI）

v3.0.5 新增：周期性拉 x_get_profile → 去重 → 发 webhook 通知。完整文档见 `docs/dev/monitor.md`。

原则：会对第三方通知渠道产生副作用的动作永远只走 CLI / 外部调度器，AI 只能做配置管理 + READ 验证。

内部踩点 CLI（不进 skill.definition.js，仅供本仓库开发者排查）

下面两条只在 CLI 暴露、不暴露给 AI tool 列表，用于改版后定位 DOM 结构变化或抓 XHR 形态：

CLI

cd /path/to/js-eyes/skills/js-x-ops-skill
npm install
 
# 通路 + 登录态 + bridge 注入 + probe + state 一站诊断
node index.js doctor
 
# READ：搜索
node index.js search "AI agent" --sort latest --max-pages 3
node index.js search "MCP" --since 2025-01-01 --until 2025-06-30 --min-likes 10
 
# READ：用户时间线
node index.js profile elonmusk --max-pages 5
node index.js profile karpathy --include-replies --max-pages 3
node index.js profile elonmusk --request-timeout 1800   # bridge / execute_script 超时（秒；默认 1800）
 
# READ：推文详情
node index.js post https://x.com/user/status/123 --with-thread
node index.js post https://x.com/user/status/123 --with-replies 50 --pretty
node index.js post https://x.com/user/status/123 --download-media [--out-dir ./media]
node index.js post <id1> <id2> <id3> --pretty    # PR-2.5+：多 positional 走 lib/api.js::getPost 批量路径
 
# READ：首页推荐
node index.js home --feed foryou --max-pages 3
node index.js home --feed following --max-pages 3
 
# READ：登录态
node index.js session-state
 
# INTERACTIVE：仅 location.assign，不模拟点击
node index.js navigate-search "AI agent"
node index.js navigate-profile elonmusk
node index.js navigate-post https://x.com/user/status/123
node index.js navigate-home --feed following
 
# DESTRUCTIVE（v2.0.1 行为透传，v3.1 拆专用工具）：
node index.js post --post "新帖内容"                                           # 发新帖
node index.js post --post "看看这张图" --image path/to/image.png                # 附带图片
node index.js post https://x.com/user/status/123 --reply "回复内容"             # 回复
node index.js post https://x.com/user/status/123 --reply "回复" --reply-style thread
node index.js post --post "评论" --quote https://x.com/user/status/123          # Quote
node index.js post --thread "段1" "段2" "段3" --thread-delay 2000               # 串推
node index.js post --post "test" --dry-run                                     # 不实际发送
 
# 内部踩点（仅本仓库开发者用）
node index.js dom-dump --anchors --limit 80
node index.js xhr-log --filter "i/api/graphql/" --limit 200
 
# 业务脚本（README + 业务结果落 docs/_data/）
node scripts/aggregate-profile.js elonmusk --limit 20 --with-replies
node scripts/batch-search.js --query "AI agent|top|2" --query "MCP|latest|1"
 
# 也可通过 js-eyes 统一入口
js-eyes skill run js-x-ops-skill doctor
 
# DOM 探针（开发者）：关键选择器存活检测
node scripts/_dev-probe-dom.js --page search

官方 X API v2 通道

READ 工具默认仍走浏览器同源 GraphQL；官方 REST API 只作为 CLI / scripts/x-post.js --via auto|api 的可选通道。端点统一使用 https://api.x.com。

凭证从 console.x.com 的 App 页面获取：

• X_BEARER_TOKEN：只读请求优先使用；适用于 api status / api timeline / api tweets / `api search-all` / `api search-recent`
• X_API_KEY / X_API_SECRET / X_ACCESS_TOKEN / X_ACCESS_TOKEN_SECRET：OAuth 1.0a 用户上下文四元组；发帖、回复、Quote、媒体上传、Article 草稿/发布必须配置

CLI 会从当前目录和 skill 目录向上查找 .env，并只填充尚未存在的环境变量；真实环境变量优先级高于 .env。

Official API 代理（Node 出站）

Browser / GraphQL READ 仍走 Chrome 自身代理；Official API 的 Node fetch 默认直连。若本机需代理才能访问 api.x.com，配置 HTTP(S) 或 SOCKS5 代理：

• 支持 http:// / https://（如 Clash mixed-port）与 socks5:// / socks:// / socks5h://
• 不支持 socks4://
• api status 输出含 proxy.enabled / proxy.host / proxy.protocol（不含密码）
• 无代理且请求失败时，access.hint 会提示设置 JS_X_OPS_PROXY

# HTTP 代理示例
JS_X_OPS_PROXY=http://127.0.0.1:7890 node index.js api status --pretty
 
# SOCKS5 示例（仅 SOCKS 端口时）
JS_X_OPS_PROXY=socks5://127.0.0.1:1080 node index.js api status --pretty

# 官方 API 状态与只读
node index.js api status --pretty
node index.js api timeline --max-pages 2 --pretty
node index.js api tweets 1234567890 --pretty
 
# 官方 API 写入（按 X API pay-per-use 计费）
node index.js api tweet "新帖内容"
node index.js api reply 1234567890 "回复内容"
node index.js api upload-media path/to/image.png --alt "图片说明"
node index.js api tweet "带图新帖" --media-id 1880028106020515840
 
# 官方 API 扩展读/写
node index.js api mentions --max-pages 2 --pretty
node index.js api trends --woeid 1 --woeid 23424977 --pretty
node index.js api delete 1234567890
node index.js trends --woeid 1 --pretty
 
# 官方 API 搜索（Archive，按量计费；全库通常需 Pay-per-use Bearer）
node index.js api search-all "AI agent" --start-time 2020-01-01T00:00:00Z --max-pages 3 --pretty
node index.js api search-recent "MCP" --since 2026-07-01 --until 2026-07-14 --from someuser --min-likes 10 --pretty
node index.js api search-all "AI lang:en" --sort-order recency --raw   # --raw 输出 v2 原始对象
 
# 官方 API Article（长文，draft-first；发布通常需 X Premium）
node index.js api article-draft "文章标题" --body-file ./article.md --cover ./cover.jpg
node index.js api article-publish <article_id>
node index.js api article "文章标题" --body-file ./article.md --publish   # 显式 --publish 才发布
node index.js api article-draft "标题" --body "# Hello" --fetch-remote-images   # 远程 https 图 opt-in
 
# READ：带 wall-clock 预算的推文详情
node index.js post https://x.com/user/status/123 --budget-ms 120000 --with-replies 50

注意：api quote 使用官方 quote_tweet_id 参数；X API 文档标注 Quote-posting 需要 Enterprise 计划，自助按量付费账号可能返回 403。媒体上传已使用 X API v2 的 POST /2/media/upload 和 POST /2/media/metadata。

Official API 搜索（Archive）与浏览器搜索对比

AI 工具 x_search_archive 参数：keyword（必填）、scope（all|recent，默认 all）、maxPages / maxResults、startTime / endTime、sortOrder、from / since / until / lang / 互动数过滤等，与 CLI 操作符一致。403 通常表示账号无全库搜索权限。

参考：X Search API 文档

Official API Articles（长文发布）

Markdown 支持：#/##/### 标题、-/* 无序列表、1. 有序列表、> 引用、**bold**/*italic*/~~strike~~、[link](url)、本地 ![alt](./path.png)、@mention、#hashtag。

内嵌推文：

{{tweet:1234567890}}
![post](https://x.com/user/status/1234567890)

远程图片：Markdown 中 https:// 图片默认跳过；CLI 加 --fetch-remote-images 或 AI 工具 fetchRemoteImages=true 才会下载上传。

AI 工具：

• x_create_article：title + bodyMarkdown/bodyFile；publish=true 时必须 confirm=true
• x_publish_article：articleId + confirm=true

参考：X Articles API

READ 调度：readMode、visual 与重放（v3.2）