pp-x-twitter

X（Twitter）— Printing Press CLI

前提条件：安装 CLI

此技能通过 x-twitter-pp-cli 二进制文件运行。**调用此技能中的任何命令前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 通过 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install x-twitter --cli-only
   

2. 验证：x-twitter-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（例如，没有 Node、处于离线状态等），请改用直接的 Go 安装方式（需要 Go 1.26.6 或更高版本）。此方式会将文件安装到 $GOPATH/bin（默认值为 $HOME/go/bin），因此请将该目录添加到 $PATH：

go install github.com/mvanhorn/printing-press-library/library/social-and-messaging/x-twitter/cmd/x-twitter-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件所在目录。在验证成功前，请勿继续执行技能命令。

此 CLI 镜像了官方 X v2 API，并增加了其他 X 工具所不具备的功能：本地 SQLite 存储，可同步一次并通过 FTS5 搜索和分组分析反复查询；适用于 Agent 的原生 --json/--select 输出；以及一个 MCP 服务，可通过节省 token 的编排和命名多步意图向 AI Agent 提供完整功能。对于粘贴链接的工作流，请从 post resolve 开始；帖子需要父帖、引用帖或回复上下文时，请使用 thread context；通过 collection save/list/export 保存持久的源材料；通过 monitor create/run/list 跟踪持续搜索；通过 brief 打包已保存的活动；通过 account snapshot 快照账户；通过 url mentions 查找发布内容或代码仓库的链接；通过 performance snapshot/backfill/analyze 跟踪帖子指标；通过 timeline export 导出账户或查询时间线；通过 thread show 离线重建已同步的对话串；通过 thread compose 根据 Markdown 撰写自我回复串；通过 articles-publish-md 根据 Markdown 撰写长篇 X Articles；还可通过 users bookmarks find 搜索已同步书签中的关键词和作者，拯救积压如山的书签——X 本身并未提供任何搜索书签的方式。

何时使用此 CLI

要查看近期帖子的排名列表，请运行 x-twitter-pp-cli top-posts --metric engagement --limit 10 --max-fetch 100 --json。此命令会读取 X 实时时间线，因此每一页都可能消耗付费 API 额度。--max-fetch 接受 1 到 1000 篇帖子；对于稀疏响应，还会额外获取少量页面。在此额度下返回的排行榜是不完整的，并且每一行 JSON 都会包含 truncated: true。--user-id 可指定数值账户 ID，无需单独查询用户名；如果未指定，命令会使用已通过身份验证的用户。JSON 行会注明实际使用的 score_metric，缺少展示量得分时会显示 null，而不是零。--dry-run 不会发出请求。

当任务涉及读取、搜索或归档 X（Twitter）数据，并且你希望结果可以离线查询，而非每次都重新获取时，请使用此 CLI——例如，构建可搜索的帖子语料库、重建对话串、快照用户近期帖子的互动情况，或增量监控提及。若 AI Agent 需要一个带有只读/破坏性操作安全提示和命名多步意图的 X 功能界面，而不是一堆原始端点调用，这也是合适的选择。只要相同数据需要查询多次，就优先使用它，而非直接调用原始 API，因为本地存储可避免每次读取都再次消耗额度。

独特功能

其他用于此 API 的工具均不具备以下功能。

可持续扩展的本地状态

• post resolve — 将任意 X 帖子 URL 或原始帖子 ID 标准化为规范的结构化记录。自动模式下会优先使用本地数据，必要时回退到公开的 v2 读取接口；结果包含数据来源（live、local 或 mixed），并给出建议的后续工作流命令。 将此命令用作 Agent 从粘贴的 X 链接启动时的第一个命令。它可以避免脆弱的 URL 解析，并为下游工作流返回稳定字段。

  x-twitter-pp-cli post resolve https://x.com/user/status/123 --agent
  x-twitter-pp-cli post resolve 123 --include author,media,links,refs,metrics --agent
  

• thread context — 解析帖子 URL 或 ID，在可用时包含父帖和引用帖，并可选择包含本地存储中的有限回复和／或近期搜索结果。

  在围绕帖子进行摘要或起草内容前使用此命令。thread show 仍是纯离线的对话重建命令；thread context 则是以 URL 为入口、可混合本地与实时数据的工作流。

  x-twitter-pp-cli thread context https://x.com/user/status/123 --agent
  x-twitter-pp-cli thread context 123 --replies --depth 3 --limit 100 --agent
  

• collection save/list/export — 将已解析的 X 帖子保存到持久化的具名本地集合中，然后将其导出为 Markdown、JSON、JSONL 或 CSV。此命令绝不会向 X 写入数据；它只会写入本地 SQLite 存储。

  使用集合保存研究资料库、发布提及、示例、招聘／来源材料，以及任何 Agent 在首次 API 读取后应能离线复用的内容。

  x-twitter-pp-cli collection save https://x.com/user/status/123 --collection ai-agents --note "Good framing" --agent
  x-twitter-pp-cli collection list ai-agents --agent
  x-twitter-pp-cli collection export ai-agents --format markdown
  

• monitor create/run/list — 创建具名查询、URL 或账号监控，然后借助本地水位标记和去重机制重复运行。monitor create 和 monitor run 只会写入本地 SQLite 状态；它们绝不会发布、点赞、回复、关注或更改 X 上的内容。

  使用监控跟踪发布提及、产品／客户反馈、账号，以及定期运行的 Agent 任务。--since last 使用已保存的水位标记；--preview 会获取数据，但不更新本地状态。

  x-twitter-pp-cli monitor create ai-labs --query 'from:openai OR from:anthropic' --agent
  x-twitter-pp-cli monitor create product-mentions --url https://example.com --agent
  x-twitter-pp-cli monitor run ai-labs --since last --agent
  x-twitter-pp-cli monitor list --agent
  

• brief — 根据监控结果、集合或明确指定的帖子 ID，生成有来源依据的确定性 JSON 或 Markdown 简报。它会整理链接、作者、文本和可用指标；不会臆造结论，也不会运行大模型摘要。

  当 Agent 需要每日／每周 X 活动资料包，或可粘贴到笔记、文档或 CRM 中的集合摘要时，使用此命令。

  x-twitter-pp-cli brief --monitor ai-labs --since 24h --agent
  x-twitter-pp-cli brief --collection launch-feedback --format markdown
  

• account snapshot — 为用户名或用户 ID 获取个人资料基本信息、公开指标、置顶帖子和近期帖子。此命令对 X 为只读，默认优先使用本地数据，除非设置了 --live 或 --data-source live。

  x-twitter-pp-cli account snapshot @username --recent 20 --agent
  x-twitter-pp-cli account snapshot 12345 --include recent,profile,metrics,pinned --format markdown
  

• url mentions — 搜索近期提及某个 URL、域名、代码库、文章或产品页面的帖子。可选择将结果保存到本地集合，或创建／更新本地监控以供后续运行。

  x-twitter-pp-cli url mentions https://example.com --since 7d --agent
  x-twitter-pp-cli url mentions github.com/org/repo --collection launch-feedback --monitor repo-links --agent
  

• performance snapshot/backfill/analyze — 在本地保存带时间戳的帖子指标；在认证允许时，回填账号近期帖子；并按类型、小时、媒体、是否包含链接或标签分析已保存的快照。缺失指标会保留为可空值／缺省值；CLI 不会将不可用字段视为零。快照输出包含 public_metrics、可用的非公开／自然流量指标、metric_source 和 metric_availability。

  x-twitter-pp-cli performance snapshot --ids 123,456 --label 24h --agent
  x-twitter-pp-cli performance backfill --mine --days 90 --agent
  x-twitter-pp-cli performance analyze --since 90d --group-by type,hour,has_media,has_link --agent
  

• timeline export — 将账号或查询时间线导出为 Markdown、JSON 或 JSONL。账号导出会在本地有已同步推文时使用本地数据，仅在需要或明确要求时才获取实时数据。

  x-twitter-pp-cli timeline export @username --since 30d --format markdown
  x-twitter-pp-cli timeline export --query 'ai agents' --since 7d --format jsonl
  

• thread show — 从本地已同步的帖子重建完整对话串，按顺序排列并标注深度，无需再次消耗 API 读取额度。

  当 Agent 需要了解讨论的结构（谁按什么顺序回复了谁）时，请使用此命令，而不是对搜索 API 分页并手动重新组装树状结构。

  x-twitter-pp-cli thread show 1750000000000000000 --agent
  

• users bookmarks find — 按关键词和／或作者离线搜索已同步的书签。X 不支持书签搜索，其 API 也不提供书签时间戳，因此书签会越积越多、无人查阅；此命令通过本地存储重建缺失的检索层。此命令为只读，同步后可免费重复运行——X 读取额度只在同步时消耗一次，而非每次查询都消耗。

  用于解决“我收藏过相关内容，但找不到了”的问题。只需同步一次书签，之后便可让 Agent 检索并处理这些内容（总结、起草帖子串、聚类）——离线存储就是 Agent 的工作集，而不是每次查询都要消耗 API 额度。

  # one-time populate (personal read — needs X_OAUTH2_USER_TOKEN); add author field + users for --from
  x-twitter-pp-cli sync --resources bookmarks --param tweet.fields=author_id,created_at
  x-twitter-pp-cli sync --resources users
  
  x-twitter-pp-cli users bookmarks find "rust async" --agent
  x-twitter-pp-cli users bookmarks find "llm" --from @karpathy --limit 20 --agent
  

编写工作流

• thread compose — 将 Markdown 文件拆分为编号的自回复串，每条推文最多 280 个字符；默认仅打印，只有使用 --post 才会发布。

  以确定性的方式根据文档编写串文；默认的试运行模式可让 Agent 在写入前预览确切的推文。

  x-twitter-pp-cli thread compose ./update.md
  

• articles-publish-md — 将带有 YAML frontmatter 的 Markdown 文件解析为 Draft.js content_state JSON，这是 X 的 Articles 编辑器所接受的格式；默认预览；--draft 创建新草稿，--update 编辑现有草稿，--post 公开发布。

  这是通过编程方式根据文档撰写长篇 X Article 的唯一方法；使用预览、--draft 和 --update 可确保内容保持私密，直到你明确使用 --post。

  转换器支持段落、#/## 标题（### 及更深层级会降级为 ##）、列表、引用块、围栏代码块、表格、分隔线、图片行（![alt](path)）、独立推文 URL（原生嵌入）、粗体/斜体/代码行内样式（包括引用块内的样式），以及 [text](url) 行内链接；这些链接会转换为真正的 LINK 实体（可用的超链接）。作为 HTML 注释的行（``）会被剥离，不会作为文章文本发布。

  x-twitter-pp-cli articles-publish-md ./post.md
  x-twitter-pp-cli articles-publish-md ./post.md --update 1750000000000000000
  

• articles update-md — 根据 Markdown 文件原地更新现有 X Article 草稿：标题（frontmatter）、正文、链接和新增的行内图片，只需一条命令。使用 articles list --agent 查找文章 ID。

  编辑 Markdown，然后重新运行一条命令。不会产生重复草稿：草稿会保留其 ID，因此编辑 URL 和任何已保存状态仍然有效。

  x-twitter-pp-cli articles update-md ./post.md --article-id 1750000000000000000 --agent
  

  警告 — 替换正文： articles update-md 会替换目标草稿的整个正文。任何在 X 撰写器中手动添加、且 Markdown 转换器无法还原的内容都会在更新时被删除。该命令会预先检查草稿的 content_state；如果发现转换器输出范围之外的实体类型（LINK、MARKDOWN、MEDIA、TWEET、DIVIDER），则会拒绝更新；只有确实要覆盖这些内容时才传入 --replace-unknown-entities。使用 Markdown 编写的内容可以完整往返转换；如果草稿包含仅由撰写器支持的嵌入内容或其他手动添加的内容，请改用撰写器进行编辑。

  默认仅适用于草稿：除非传入 --republish，否则已发布的文章会被拒绝；该参数会依次执行 Unpublish -> UpdateContent -> Publish（文章会短暂取消发布）。使用 --dry-run 可预览转换后的载荷，而不调用 API。

命令参考

account-activity — 与检索和管理 AAA 订阅相关的端点

• x-twitter-pp-cli account-activity create-subscription — 为用户和指定的 webhook 创建 Account Activity 订阅。
• x-twitter-pp-cli account-activity delete-subscription — 删除指定 webhook 和用户 ID 对应的 Account Activity 订阅。
• x-twitter-pp-cli account-activity get-subscription-count — 获取当前处于活动状态的 Account Activity 订阅数量。
• x-twitter-pp-cli account-activity get-subscriptions — 获取指定 webhook 的所有活动订阅列表。
• x-twitter-pp-cli account-activity validate-subscription — 检查用户针对指定 webhook 的 Account Activity 订阅。

activity — 管理活动

• x-twitter-pp-cli activity create-subscription — 为 X 活动事件创建订阅
• x-twitter-pp-cli activity delete-subscription — 删除 X 活动事件的订阅
• x-twitter-pp-cli activity delete-subscriptions-by-ids — 根据 ID 删除多个 X 活动事件订阅
• x-twitter-pp-cli activity get-subscriptions — 获取 XAA 的活动订阅列表
• x-twitter-pp-cli activity update-subscription — 更新 X 活动事件的订阅

chat — 管理聊天

• x-twitter-pp-cli chat add-group-members — 向现有的加密 Chat 群组对话添加一名或多名成员，并轮换对话密钥。
• x-twitter-pp-cli chat create-conversation — 代表已通过身份验证的用户创建新的加密 Chat 群组对话。
• x-twitter-pp-cli chat get-conversation — 返回 Chat 对话的元数据，包括类型、静音状态和群组详情。使用 chat_conversation。
• x-twitter-pp-cli chat get-conversation-events — 获取特定 Chat 对话中的消息和密钥更改事件，并支持分页。
• x-twitter-pp-cli chat get-conversations — 获取已通过身份验证的用户收件箱中的 Chat 对话列表。
• x-twitter-pp-cli chat initialize-conversation-keys — 初始化 Chat 对话的加密密钥。
• x-twitter-pp-cli chat initialize-group — 初始化新的 XChat 群组对话并返回唯一的对话 ID。
• x-twitter-pp-cli chat mark-conversation-read — 代表已通过身份验证的用户将特定 Chat 对话标记为已读。
• x-twitter-pp-cli chat media-download — 从 XChat 对话下载加密媒体字节。响应正文包含原始二进制字节。
• x-twitter-pp-cli chat media-upload-append — 向 XChat 上传会话追加媒体数据。
• x-twitter-pp-cli chat media-upload-finalize — 完成 XChat 媒体上传会话。
• x-twitter-pp-cli chat media-upload-initialize — 初始化 XChat 媒体上传会话。
• x-twitter-pp-cli chat send-message — 向特定 Chat 对话发送加密消息。
• x-twitter-pp-cli chat send-typing-indicator — 代表已通过身份验证的用户向特定 Chat 对话发送正在输入指示。

communities — 管理社区

• x-twitter-pp-cli communities get-by-id — 根据 ID 获取特定社区的详情。
• x-twitter-pp-cli communities search — 获取符合指定搜索查询的社区列表。

compliance — 与确保系统中的 X 数据符合规范相关的端点

• x-twitter-pp-cli compliance create-jobs — 为指定的作业类型创建新的合规作业。
• x-twitter-pp-cli compliance get-jobs — 获取按作业类型和可选状态筛选的合规作业列表。
• x-twitter-pp-cli compliance get-jobs-by-id — 根据 ID 获取特定合规作业的详情。

connections — 与流式连接相关的端点

• x-twitter-pp-cli connections delete-all — 终止已通过身份验证的应用程序的所有活动流式连接。
• x-twitter-pp-cli connections delete-by-endpoint — 终止已通过身份验证的应用程序中指定端点 ID 的所有流式连接。
• x-twitter-pp-cli connections delete-by-uuids — 根据 UUID 终止已通过身份验证的应用程序中的多个流式连接。
• x-twitter-pp-cli connections get-history — 返回已通过身份验证的应用程序的活动和历史流式连接及其断开连接原因。

dm-conversations — 管理私信对话

• x-twitter-pp-cli dm-conversations create-direct-messages-by-participant-id — 根据参与者 ID 向特定参与者发送新的私信。
• x-twitter-pp-cli dm-conversations create-direct-messages-conversation — 与指定参与者发起新的私信对话。
• x-twitter-pp-cli dm-conversations get-direct-messages-events-by-participant-id — 获取特定对话的私信事件。
• x-twitter-pp-cli dm-conversations media-download — 下载附加到旧版私信的媒体。

dm-events — 管理私信事件

• x-twitter-pp-cli dm-events delete-direct-messages-events — 按 ID 删除指定的私信事件（前提是该事件属于已认证用户）。
• x-twitter-pp-cli dm-events get-direct-messages-events — 获取所有会话中的近期私信事件列表。
• x-twitter-pp-cli dm-events get-direct-messages-events-by-id — 按 ID 获取指定私信事件的详细信息。

evaluate-note — 管理评估笔记

• x-twitter-pp-cli evaluate-note — 评估社区笔记的端点。

insights — 管理洞察

• x-twitter-pp-cli insights get-historical — 获取指定时间范围内特定帖子历史互动指标。
• x-twitter-pp-cli insights get-insights28-hr — 获取指定帖子过去 28 小时内的互动指标。

lists — 与获取和管理列表相关的端点

• x-twitter-pp-cli lists create — 为已认证用户创建新列表。
• x-twitter-pp-cli lists delete — 按 ID 删除已认证用户拥有的指定列表。
• x-twitter-pp-cli lists get-by-id — 按 ID 获取指定列表的详细信息。
• x-twitter-pp-cli lists update — 按 ID 更新已认证用户拥有的指定列表的详细信息。

media — 与媒体相关的端点

• x-twitter-pp-cli media append-upload — 向媒体上传请求追加数据。
• x-twitter-pp-cli media create-metadata — 为媒体文件创建元数据。
• x-twitter-pp-cli media create-subtitles — 为指定媒体文件创建字幕。
• x-twitter-pp-cli media delete-subtitles — 删除指定媒体文件的字幕。
• x-twitter-pp-cli media finalize-upload — 完成媒体上传请求。
• x-twitter-pp-cli media get-analytics — 获取媒体分析数据。
• x-twitter-pp-cli media get-by-key — 按媒体密钥获取指定媒体文件的详细信息。
• x-twitter-pp-cli media get-by-keys — 按媒体密钥获取媒体文件的详细信息。
• x-twitter-pp-cli media get-upload-status — 按 ID 获取媒体上传状态。
• x-twitter-pp-cli media initialize-upload — 初始化媒体上传。
• x-twitter-pp-cli media upload — 上传媒体文件，以便用于帖子或其他内容。

news — 获取新闻报道的端点

• x-twitter-pp-cli news get — 按 ID 获取新闻报道。
• x-twitter-pp-cli news search — 获取符合指定搜索查询的新闻报道列表。

notes — 管理笔记

• x-twitter-pp-cli notes create-community — 创建供大模型使用的社区笔记端点。
• x-twitter-pp-cli notes delete-community — 删除社区笔记。
• x-twitter-pp-cli notes search-community-written — 返回用户撰写的所有社区笔记。
• x-twitter-pp-cli notes search-eligible-posts — 返回所有符合社区笔记条件的帖子。

openapi-json — 管理 OpenAPI JSON

• x-twitter-pp-cli openapi-json — 以 JSON 格式获取完整的 OpenAPI 规范。（参见 https://github。

spaces — 与获取和管理 Spaces 相关的端点

• x-twitter-pp-cli spaces get-by-creator-ids — 获取指定用户 ID 创建的 Spaces 的详细信息。
• x-twitter-pp-cli spaces get-by-id — 按 ID 获取指定 Space 的详细信息。
• x-twitter-pp-cli spaces get-by-ids — 按 ID 获取多个 Spaces 的详细信息。
• x-twitter-pp-cli spaces search — 获取符合指定搜索查询的 Spaces 列表。

trends — 管理趋势

• x-twitter-pp-cli trends <woeid> — 获取由 WOEID 标识的特定位置的热门话题。

tweets — 与获取、搜索和修改推文相关的端点

• x-twitter-pp-cli tweets create-posts — 为已认证用户创建一条新帖子；如果提供了 edit_options，则编辑现有帖子。
• x-twitter-pp-cli tweets create-webhooks-stream-link — 创建一个链接，将 FilteredStream 事件发送到指定的 webhook。
• x-twitter-pp-cli tweets delete-posts — 如果指定帖子归已认证用户所有，则按 ID 删除该帖子。
• x-twitter-pp-cli tweets delete-webhooks-stream-link — 删除从 FilteredStream 事件指向指定 webhook 的链接。
• x-twitter-pp-cli tweets get-posts-analytics — 获取指定帖子在指定时间范围内的分析数据。
• x-twitter-pp-cli tweets get-posts-by-id — 按 ID 获取特定帖子的详细信息。
• x-twitter-pp-cli tweets get-posts-by-ids — 按 ID 获取多个帖子的详细信息。
• x-twitter-pp-cli tweets get-posts-counts-all — 获取完整归档中符合搜索查询的帖子数量。
• x-twitter-pp-cli tweets get-posts-counts-recent — 获取过去 7 天内符合搜索查询的帖子数量。
• x-twitter-pp-cli tweets get-rule-counts — 获取筛选流当前规则集中的规则数量。
• x-twitter-pp-cli tweets get-rules — 获取筛选流的当前规则集或其中一部分规则。
• x-twitter-pp-cli tweets get-webhooks-stream-links — 获取与筛选流规则集关联的 webhook 链接列表。
• x-twitter-pp-cli tweets search-posts-all — 获取完整归档中符合搜索查询的帖子。
• x-twitter-pp-cli tweets search-posts-recent — 获取过去 7 天内符合搜索查询的帖子。
• x-twitter-pp-cli tweets update-rules — 在筛选流的当前规则集中添加或删除规则。

usage — 管理用量

• x-twitter-pp-cli usage — 获取指定天数内的帖子用量统计信息。

users — 与获取用户信息、管理用户关系相关的端点

• x-twitter-pp-cli users get-by-id — 按 ID 获取特定用户的详细信息。
• x-twitter-pp-cli users get-by-ids — 按 ID 获取多个用户的详细信息。
• x-twitter-pp-cli users get-by-username — 按用户名获取特定用户的详细信息。
• x-twitter-pp-cli users get-by-usernames — 按用户名获取多个用户的详细信息。
• x-twitter-pp-cli users get-me — 获取已认证用户的详细信息。
• x-twitter-pp-cli users get-public-keys — 返回指定用户的公钥和 Juicebox 配置。
• x-twitter-pp-cli users get-reposts-of-me — 获取转发已认证用户内容的帖子列表。
• x-twitter-pp-cli users get-trends-personalized-trends — 获取已认证用户的个性化热门话题。
• x-twitter-pp-cli users bookmarks find [query] — 按关键词和／或作者搜索本地同步的书签，不会额外读取 API。
• x-twitter-pp-cli users likes post <user_id> --tweet-id <tweet_id> — 代表已认证用户为帖子点赞。
• x-twitter-pp-cli users likes unlike-post <user_id> <tweet_id> — 代表已认证用户取消对帖子的点赞。
• x-twitter-pp-cli users search — 获取符合搜索查询的用户列表。

webhooks — 管理 webhook

• x-twitter-pp-cli webhooks create — 创建新的 webhook 配置。
• x-twitter-pp-cli webhooks create-replay-job — 创建重放任务，以检索过去最多 24 小时内已发送或尝试发送的所有事件
• x-twitter-pp-cli webhooks delete — 删除现有的 webhook 配置。
• x-twitter-pp-cli webhooks get — 获取与客户端应用关联的 webhook 配置列表。
• x-twitter-pp-cli webhooks validate — 对指定 webhook 触发 CRC 检查。

查找合适的命令

当你知道要做什么，却不知道哪个命令能实现时，直接询问 CLI：

x-twitter-pp-cli which "<capability in your own words>"

which 会根据自然语言描述的功能查询，从此 CLI 精选的功能索引中找到最匹配的命令。退出码 0 表示至少找到一个匹配项；退出码 2 表示没有足够可靠的匹配项——请改用 --help 或缩小查询范围。

使用示例

归档某个主题，然后离线查询

x-twitter-pp-cli sync --resources tweets --since 24h && x-twitter-pp-cli search "ai agents" --type tweets --limit 50

同步一次到 SQLite 后，即可随意运行离线全文搜索查询，无需再读取 API。

精简大型响应，提取适合 Agent 的字段

x-twitter-pp-cli search "openai" --type tweets --agent --select id,text,author_id,public_metrics.like_count

帖子包含大型嵌套负载；--agent + --select 可将响应精简为 Agent 所需的字段，从而降低上下文成本。

离线重建对话线程

x-twitter-pp-cli thread show 1750000000000000000 --agent

通过 conversation_id 和 referenced_tweets 关联已同步的帖子，并按顺序构建带深度标记的树——无需调用 API。

根据文档编写自回复线程（默认试运行）

x-twitter-pp-cli thread compose ./release-notes.md

将 Markdown 拆分为按编号排列、每条不超过 280 个字符的自回复线程并打印出来；添加 --post 即可实际发布。

身份验证设置

X 身份验证分为三个独立通道。不要根据一个通道推断另一个通道；请运行 x-twitter-pp-cli doctor --json 并检查 auth_lanes，再选择命令。

• auth_lanes.app_only_api：来自 X 开发者控制台的仅应用 X API Bearer token。用于公开的只读 API 访问，例如推文／用户查询、近期搜索、列表和 Spaces。使用 x-twitter-pp-cli auth set-bearer-token <token> 存储，或导出 X_BEARER_TOKEN。
• auth_lanes.oauth2_user_context：X_OAUTH2_USER_TOKEN，或通过 x-twitter-pp-cli auth oauth2-login / auth import-oauth2 存储的 OAuth2 访问令牌。/2/users/me、写入操作、书签、个人数据读取、私信、关注、点赞、转发和用户上下文分析均需要此通道。如果此通道状态为 missing 或 invalid，不要改用仅应用 Bearer token 重试；请运行 OAuth2 授权码 + PKCE 流程，或明确导入真实的用户上下文令牌。
• auth_lanes.x_articles_cookie：通过 x-twitter-pp-cli auth login --chrome 捕获的浏览器 Cookie。此通道仅用于 X Articles / x.com 浏览器会话端点。它不会创建 X_OAUTH2_USER_TOKEN，也不能验证 v2 API 用户上下文命令。

设置步骤：

1. 在 X 开发者控制台中将应用关联到一个 Project。
2. 需要发布内容或执行其他变更操作时，将应用权限设置为 Read and write。
3. 复制应用 Bearer Token，并运行 x-twitter-pp-cli auth set-bearer-token <bearer-token>，以便仅应用模式读取公开数据。环境变量替代方式：在 Shell 或运行时密钥管理器中设置 X_BEARER_TOKEN。
4. 启用 OAuth2，并配置适当的作用域，例如 tweet.read、tweet.write、users.read、offline.access、bookmark.read、like.read、like.write、follows.read 和 follows.write。在 X 开发者应用中添加 http://127.0.0.1:8787/callback 作为 OAuth2 重定向 URI，然后运行 x-twitter-pp-cli auth oauth2-login --client-id <oauth2-client-id>，完成授权码 + PKCE 浏览器流程。已有令牌时的非交互式替代方式：x-twitter-pp-cli auth import-oauth2 --client-id <oauth2-client-id> --access-token <oauth2-access-token> --refresh-token <oauth2-refresh-token> --scopes tweet.read,tweet.write,users.read,offline.access,bookmark.read,like.read,like.write,follows.read,follows.write。环境变量替代方式：在 Shell 或运行时密钥管理器中设置 X_OAUTH2_USER_TOKEN。
5. 仅在使用 articles ... 命令时，另行运行 x-twitter-pp-cli auth login --chrome。

由于“token”在 X 中含义不明确，auth set-token 已弃用。它仍作为 auth set-bearer-token 的兼容别名保留，不得用于 OAuth2 用户上下文令牌。交互式 OAuth2 浏览器流程请使用 auth oauth2-login；已有令牌时请使用 auth import-oauth2。

doctor --json 是可供机器读取的预检命令。它会报告 selected_profile、各通道状态、/2/users/me 探测结果、返回的已验证用户身份、已存储的作用域、缺失的工作流作用域、令牌过期时间、刷新令牌是否存在，以及 X Articles Cookie 状态，且不会打印机密信息。

当 X 返回 Unsupported Authentication 和 Application-Only is forbidden 时，说明该命令需要 OAuth2 用户上下文身份验证。请修复 auth_lanes.oauth2_user_context；Cookie 身份验证和仅应用 Bearer 身份验证都无法满足该端点的要求。

原始 API 备用通道

仅在调试新的 X 端点、认证通道行为或 API 错误，且尚无合适的生成命令时使用 raw。它接受相对 API 路径或允许列表中的 HTTPS X 绝对 URL、可重复的查询参数和标头，以及来自 --body、--body-file 或 --body @- 的 JSON 请求体。

x-twitter-pp-cli raw GET /2/users/me --agent
x-twitter-pp-cli raw GET /2/tweets --param ids=123,456 --json
x-twitter-pp-cli raw POST /2/tweets --body '{"text":"hello"}' --dry-run --agent

常规工作流仍首选生成命令，因为它们包含端点专属的验证、分页、来源信息、响应封装和工作流提示。raw 会保留上游响应正文，同时使用与其他命令相同的认证通道：仅应用的公开读取仍需要 X_BEARER_TOKEN；用户上下文读取和写入仍需要 X_OAUTH2_USER_TOKEN 或导入的 OAuth2 用户上下文令牌。

Agent 模式

在任意命令中添加 --agent。该参数会展开为：--json --compact --no-input --no-color --yes。

• 可管道传输 — JSON 输出到标准输出，错误输出到标准错误

• 可筛选 — --select 保留字段子集。点分路径可深入嵌套结构；数组会逐元素遍历。对于冗长 API，这对精简上下文至关重要：

  x-twitter-pp-cli communities search --query example-value --agent --select id,name,status
  

• 可预览 — --dry-run 会显示请求而不发送。在 --agent 模式下，变更操作的试运行会返回 JSON，其中包含 sent:false、方法/路径/请求体、选定的配置文件、认证通道、变更分类，以及已知时的公开操作。

• 适合离线使用 — 同步/搜索命令在本地 SQLite 存储可用时可以使用它

• 非交互式 — 从不提示；所有输入都通过标志传入

• 显式重试 — 仅当已存在的创建操作应视为成功时使用 --idempotent；仅当缺失的删除目标应视为成功时使用 --ignore-missing

响应封装

从本地存储或 API 读取数据的命令会将输出封装在来源信息中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并查看 .meta.source 判断数据来自实时来源还是本地来源。只有当标准输出连接到终端，且未设置机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会将人类可读的 N results (live) 摘要输出到标准错误；管道/Agent 使用方和显式格式运行会在标准输出中获得纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有不妥之处时，请记录下来：

x-twitter-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
x-twitter-pp-cli feedback --stdin < notes.txt
x-twitter-pp-cli feedback list --json --limit 10

条目会保存在本地 ~/.local/share/x-twitter-pp-cli/feedback.jsonl。除非设置了 X_TWITTER_FEEDBACK_ENDPOINT，且传入了 --send 或设置了 X_TWITTER_FEEDBACK_AUTO_SEND=true，否则绝不会发送 POST 请求。默认行为仅保存到本地。

记录让你感到意外的地方，而不是提交错误报告。简短、具体，写成一行：这才是能够不断累积价值的部分。

输出交付

每个命令都接受 --deliver <sink>。输出会发送到指定目标，同时输出到标准输出，或取代标准输出，因此 Agent 无需手动通过管道即可路由命令结果。支持以下三个目标：

目标	效果
stdout	默认；仅写入标准输出
file:<path>	将输出原子性地写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到 URL（当使用 --compact 时，内容类型为 application/json 或 application/x-ndjson）

遇到未知方案时会拒绝处理，并返回一条结构化错误，指出支持的方案。Webhook 请求失败时会返回非零状态，并在标准错误中记录 URL 和 HTTP 状态。

命名配置文件

配置文件是一组已保存的标志值，可在多次调用中重复使用。如果定时运行的 Agent 每次都以相同配置调用同一命令，可使用它——就像 HeyGen 的 “Beacon” 模式一样。

x-twitter-pp-cli profile save briefing --json
x-twitter-pp-cli --profile briefing communities search --query example-value
x-twitter-pp-cli profile list --json
x-twitter-pp-cli profile show briefing
x-twitter-pp-cli profile delete briefing --yes

显式标志始终优先于配置文件中的值；配置文件中的值优先于默认值。agent-context 会在 available_profiles 下列出所选存储中的配置文件。默认情况下，即使 --config 指向其他凭据文件，已保存的配置文件仍存放在 ~/.x-twitter-pp-cli/profiles.json。保存、列出、应用或查找另一组标志预设时，请始终传入 --profile-store <path>。此选择器不能保存在配置文件中，也不会更改凭据或 SQLite 存储。

异步任务

对于提交长时间运行任务的端点，生成器会检测「提交后轮询」模式（响应中包含 job_id/task_id/operation_id 字段，且存在对应的状态端点），并为提交命令添加三个额外标志：

标志	用途
--wait	阻塞直到任务达到终态，而不是立即返回任务 ID
--wait-timeout	最大等待时长（默认 10m，0 表示不设超时）
--wait-interval	初始轮询间隔（默认 2s；采用指数退避逐渐延长，最长为 30s）

如果希望提交后不等待结果，请在异步提交时不使用 --wait；如果希望用一条命令返回已完成的产物，请使用 --wait。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	请求过于频繁（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 x-twitter-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 请参阅上文的先决条件
3. 其他情况 → 直接使用（将其作为带有 --agent 的 CLI 命令执行）

MCP 服务安装

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/social-and-messaging/x-twitter/cmd/x-twitter-pp-mcp@latest
   

2. 在 Claude Code 中注册：

   claude mcp add x-twitter-pp-mcp -- x-twitter-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which x-twitter-pp-cli 如果未找到，请提供安装选项（请参阅本技能顶部的先决条件）。
2. 根据用户查询，从上文的独特功能和命令参考中选择最合适的命令。
3. 使用 --agent 标志执行：

   x-twitter-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，请查看子命令帮助：x-twitter-pp-cli <command> --help。