Changelog¶

所有版本变更记录。格式基于 Keep a Changelog。

[Unreleased]¶

Planned¶

CLI 剩余业务 action：user 补齐（profile / followers / following / follow / unfollow / edit / set-avatar / set-banner）、search 补齐（people / media / lists）、settings set 系列、posts reply、upload video
F3 maturin pip bundle 方案（需要研究 bundle_bin 或 post-install hook，A0 POC 已证明 --features cli,python 不能共存）
D4 docs/cli/reference.md 从 twitter-cli output-schema 自动生成
aarch64-unknown-linux-gnu 预编译（需配置 Cross.toml pre-build 钩子安装 cmake/nasm）
Node 20 → Node 24 action 升级（2026-06-02 GitHub 强制切换前完成）

[1.0.13] - 2026-04-28¶

Fixed¶

ClientTransaction 初始化失败：无法提取 KEY_BYTE indices （src/common/transaction/client.rs:60）—— X.com 重新混淆 ondemand.s 后，承载 key byte 索引的临时变量名从 n[..] 变为 t[..]，导致旧正则 n\[(\d{1,2})\],16 在新 JS 中无任何匹配，所有走 GraphQL 的接口（get_about_account / get_profile / create_tweet / search 等）在创建 Twitter 客户端阶段直接 panic。改用 \(\w\[(\d{1,2})\],\s*16\) 通配单字母变量名并锚定到完整的 (X[N],16) 形态以避免误匹配，与上游 iSarabjitDhiman/XClientTransaction 最新策略保持一致。新版 JS 抽出 indices [1, 24, 28, 42] （row_index=1, key_bytes_indices=[24, 28, 42]）

Tests¶

cargo test --lib test_extract_key_byte_indices_from_js 单元测试 fixture 为带括号格式 (n[7],16)，新正则向后兼容
cargo test --test integration_user test_get_about_account -- --ignored 实证通过（@elonmusk → rest_id=44196397）

[1.0.12] - 2026-04-21¶

Fixed¶

Posts 发帖长度校验误判 (src/x/posts/client.rs:468)：params.text.len() 返回 UTF-8 字节数而非字符数，导致含中文/emoji 的推文被误判超过 280 限制（单个中文占 3 字节 → 93 个中文就会触发假超限）。改为按 Twitter 官方 twitter-text 库的加权规则计数：URL 固定 23、CJK/emoji/全角标点每字符 2、 Basic Latin 每字符 1。新增 twitter_weighted_length() 函数 + TWITTER_URL_LENGTH=23 常量并从 src/x/posts/mod.rs 导出
DM 私信长度校验同类 bug：
Rust 业务层 src/x/dm/client.rs 的 validate_message / validate_message_with_media / validate_batch_messages 3 处 text.len() 改为 text.chars().count()，匹配 Twitter DM 的 10000 字符（非字节）限制
Python 绑定层 src/python/dm/client.rs 共 6 个发送方法（send_message / send_message_v2 / send_batch / send_batch_v2 / send_batch_with_custom_texts / send_batch_with_custom_texts_v2）全部同步修复
修复前中文 DM 用户实际可发送字符数被压缩至 ~3333（10000 字节 / 3 字节每字符），修复后恢复到 10000 中文字符
4 处 __repr__ UTF-8 字节索引 panic bug：src/python/inbox/types.rs:177,546、 src/python/dm/types.rs:213、src/python/posts/types.rs:64 使用 &self.text[..30] 按字节切片，遇中文/emoji 落在多字节 UTF-8 字符中间时 Rust panic。Python 侧调 repr() 或打印对象含 11 个以上中文即稳定触发（posts 阈值为 7 个中文）。改用新增 common::text::truncate_preview() 按 Unicode codepoint 安全截断
src/common/auth.rs:240 的 ct0 日志截断虽实际安全（CSRF token 是 ASCII hex）但为避免未来误用，顺手改用同一辅助函数

Added¶

src/common/text.rs 新增 truncate_preview(s, max_chars) 辅助函数——按 Unicode codepoint 数安全截断字符串，附 7 个单元测试（ASCII / CJK / emoji / 混合 / 零长度 / 字节边界回归）

Tests¶

src/x/posts/types.rs 新增 7 个 length_tests 单元测试：ASCII / CJK / 全角标点 / URL 固定 23 / 混合文本 / 真实中文长推回归 / emoji
src/x/dm/client.rs 新增 2 个 CJK 回归测试：9999 中文字符应通过、 10001 中文字符应拒绝
测试总数 177 → 193，全部通过

Changed¶

Docker 构建从 ~80min 降至 ~15min：cli-docker.yml 重写为 matrix 并行双 runner 原生编译（amd64 on ubuntu-latest + arm64 on ubuntu-24.04-arm GitHub 免费 ARM64 runner）+ push-by-digest + manifest 合并模式。砍掉 QEMU 用户态模拟（单架构慢 3-5 倍）+ 双架构串行叠加的双重损失。参考 Docker 官方 multi-platform 最佳实践

CI / Infrastructure¶

修复 PyPI 发版门禁 403 bug：build-and-release.yml 的 wait-for-cli-pipelines job 调 gh api 查询 workflow 状态时， GITHUB_TOKEN 缺少 actions: read 权限导致 403，门禁 job 自己 crash 并误触发"失败阻止 PyPI"假阳性（1.0.11 CHANGELOG 声称 "已验证工作"实际是假阳性）。已补齐权限
github-release job 新增 wait-for-cli-pipelines 依赖：与 PyPI 发布约束对齐，防止 GitHub Release 创建了含 wheel 的 artifact 包但 CLI binary / Docker 实际失败的半成品状态

Removed¶

停止支持 Intel macOS 预编译产物（源码安装仍可用）
cli-release.yml：删除 x86_64-apple-darwin / macos-13 matrix 条目
build-and-release.yml：macOS PyPI wheel 从 universal2 （x86_64+arm64 合体）降级为 aarch64-apple-darwin（纯 Apple Silicon）， MACOSX_DEPLOYMENT_TARGET 10.13 → 11.0
原因：GitHub 免费 Intel macOS runner 池从 2025 年起严重短缺， 1.0.12 首次发版时 macos-13 runner 排队 10h+ 未分配，永久卡住整条 CLI release 流水线。Apple 已于 2023 年停产 Intel Mac
影响：Intel Mac 用户需通过 cargo install x-api-rs --features cli 或 pip install x-api-rs（sdist 源码构建）使用本项目

[1.0.11] - 2026-04-20¶

1.0.11 是 1.0.9 / 1.0.10 的补丁重发——前两版 PyPI wheel 已发布成功但 Release twitter-cli（binary 预编译）和 Build & Push twitter-cli Docker 两个 workflow 都失败，导致 CLI 组件缺失。由于 PyPI 同版本号不可重传，本版累积前两版的全部功能 + 所有 CI 修复。

Added¶

twitter-cli 21 个 action 全部可用（1.0.9 功能：dm / posts / user / search / upload / settings / 诊断命令 + shell 补全；见下方 1.0.9 [yanked] 条目）
PyPI 发版门禁：build-and-release.yml 新增 wait-for-cli-pipelines job，PyPI 上传前强制等待 cli-release.yml + cli-docker.yml 全部 success。任一 CLI 流水线失败则阻止 PyPI 发布（防止 1.0.9/1.0.10 类型的 "版本号存在但 CLI 组件缺失"破损状态）
CLAUDE.md 新增"🚨 发版失败必须删除重试"小节，文档化 PyPI 占位规则与 gh release delete --cleanup-tag 标准恢复流程

Fixed¶

Dockerfile.cli：新增 git 依赖——boring-sys2 的 ensure_patches_applied() 调 git init 初始化 BoringSSL 源码目录并 apply patch；rust:1-slim-bookworm 默认不含 git
Dockerfile.cli：补齐 cmake / nasm / ninja-build / build-essential 依赖，移除不稳定的 stub 预热层
cli-release.yml：macOS sha256sum 命令不存在，改为 shasum -a 256 fallback（macOS + Linux 通用）
cli-release.yml：macOS 加 brew install cmake nasm ninja、 Linux 加 apt-get install nasm ninja-build、Windows 加 choco install nasm
cli-check.yml：clippy 从 -D warnings 放宽到 -D clippy::correctness，避免历史代码的 style/pedantic 风格 lint 污染 CI。CLI 核心 API 设计 lint（clippy::result_large_err）通过 src/cli/mod.rs 顶部 #![allow] 抑制
cli-check.yml：新增 Install build deps step 补充 nasm/ninja-build
cargo fmt --all --check：24 个历史文件批量 rustfmt 统一（主要是 src/x/search、src/x/settings、src/cli 等模块的格式漂移），纯风格调整无功能变化
cargo clippy --fix：自动修复 5 处 lint（io::Error::other 简化、 redundant_closure、needless_borrow 等）

Changed¶

.github/workflows/cli-release.yml：暂时移除 aarch64-unknown-linux-gnu cross 编译 target——cross 默认镜像缺 cmake/nasm/git 构建依赖，需维护 Cross.toml 的 pre-build 钩子。作为已知 TODO 保留在 [Unreleased]

[1.0.10] - 2026-04-20 [YANKED]¶

⚠️ 此版本已作废：CLI binary 预编译 + Docker 镜像构建失败，GitHub Release 和 GHCR 均无有效 artifact，仅 PyPI wheel 成功上传。请使用 1.0.11。

PyPI 因同版本号占位规则无法删除，此版号永久保留。

[1.0.9] - 2026-04-18 [YANKED]¶

⚠️ 此版本已作废：CLI binary 预编译 + Docker 镜像构建失败，CLI 组件缺失。请使用 1.0.11。

PyPI 因同版本号占位规则无法删除，此版号永久保留。

Added¶

Phase B1 剩余 action：twitter-cli dm send-batch 三段式 BatchLine 输出（header + items + summary）+ twitter-cli dm inbox --max N
Phase B 只读批次：
twitter-cli user get --screen-name <NAME> / user get-by-id --rest-id <ID>
twitter-cli search top --query <Q> / search latest --query <Q>（均支持 --cursor）
twitter-cli settings get（合并 sensitive + account 两组设置）
Phase B 写操作批次：
twitter-cli posts create --text <S> [--media-ids <IDS>] [--reply-to <ID>]
twitter-cli posts {delete,like,unlike,retweet,unretweet} --id <ID>
twitter-cli upload image --file <PATH> [--category tweet-image|dm-image|banner-image]
Phase B9 诊断命令（5 个，全部无需认证或仅需 cookies）：
twitter-cli doctor 综合诊断（cookies + API 连通性 + 版本），返回 api_latency_ms
twitter-cli auth-check 仅校验 cookies 解析
twitter-cli version-full 详细版本（cli / schema / lib / git_sha / target）
twitter-cli output-schema 完整 JSON Schema（12 ErrorCode + 13 退出码 + 递归 clap Command 树）
twitter-cli example <module> <action> 打印硬编码 JSONL 示例
Phase G5 shell 补全：twitter-cli completion bash|zsh|fish|powershell|elvish，通过 clap_complete::generate 自动派生
CLI 完整文档体系（docs/cli/，11 文件 3018 行）：README / getting-started / output-schema / 6 份模块文档 / llms.txt / llms-full.txt
Phase E 测试基础设施：
tests/cli/integration_cli.rs 10 个黑盒集成测试（assert_cmd + predicates）
tests/cli/integration_cli_snapshot.rs 5 个 insta 快照测试（锁定 Envelope / BatchLine / ErrorCode 输出格式）
Phase F 分发流水线：
.github/workflows/cli-release.yml 5 平台预编译 matrix（macOS x86_64/arm64、Linux x86_64/aarch64 via cross、Windows x86_64）+ 自动 GitHub Release + SHA256 校验和
.github/workflows/cli-docker.yml distroless 镜像，多平台 linux/amd64 + linux/arm64 推送到 ghcr.io/open-luban/x-api-rs/twitter-cli
.github/workflows/cli-check.yml fmt + clippy -D warnings + 全测试集 + cargo publish --dry-run
Dockerfile.cli 多阶段构建（rust:1-slim-bookworm → distroless/cc-debian12）
README 新增"twitter-cli — 面向 AI agent 的命令行"独立段落，补全 search / settings 到功能模块表

Changed¶

单元测试总数 233 → 243（含诊断命令 clap 解析和内部测试）
CLI 现支持 21 个 action：15 业务 + 6 诊断/自省

Fixed¶

（无 bug 修复，纯功能迭代）

[1.0.8] - 2026-04-17¶

Added¶

twitter-cli 命令行二进制：面向 AI agent 的 Twitter API 工具，Phase A 基础设施 + Phase B 高频 action 实装
Phase A0：cdylib + [[bin]] 链接兼容性 POC 通过（macOS arm64），cli 单独构建路径完全可用
Phase A1：新增 cli feature，级联全部 8 业务模块 + clap / clap_complete / dirs / toml / libc 可选依赖
Phase A3：输出包络 Envelope<T>（带 meta.schema_version）、BatchLine<T> 三段式（header / item / summary）、12 变体 ErrorCode（穷尽匹配 TwitterError，禁止 _ => Unknown 兜底）、ErrorInfo 扩展字段（docs_url / recovery_actions / retry_after_secs / issue_url）、JsonlWriter 线程安全写入器
Phase A4：四源认证链（--cookies-file > stdin[5s 超时] > X_API_COOKIES_FILE env > ~/.x-api/config.toml[version=1 校验]）+ cookies 文件权限检查（>0o644 拒绝、>0o600 warn）+ proxy URL sanitize 防凭据泄漏
Phase A5：stderr tracing 初始化（--log-level + --log-format json|compact）、SIGPIPE 恢复默认处理避免 panic=abort 产生 core dump
dm 模块：send / send-batch（三段式 BatchLine）/ inbox
posts 模块：create / delete / like / unlike / retweet / unretweet
user 模块：get --screen-name / get-by-id --rest-id
search 模块：top / latest（含 --cursor 分页）
upload 模块：image（含 tweet-image / dm-image / banner-image 三种 category）
settings 模块：get（合并 sensitive + account 两组设置）
CLI 文档体系（docs/cli/）：
README.md CLI 索引
getting-started.md 安装与认证入门（4 种认证方式）
output-schema.md Envelope / BatchLine / ErrorCode / 退出码完整规范
6 份模块命令文档（dm / posts / user / search / upload / settings）
llms.txt / llms-full.txt AI 可读参考
CLI 单元测试 56 条（参数解析 / Envelope 序列化 / ErrorCode 映射 / 认证链 / 权限检查）
CLAUDE.md 新模块接入 SOP 新增 CLI 绑定步骤（第 4.5 步）和 Phase 2.6 检查项

Changed¶

单元测试总数 177 → 233（CLI feature 启用时）
Cargo.toml 引入 [[bin]] twitter-cli 声明，required-features = ["cli"] 隔离

[1.0.7] - 2026-04-08¶

Added¶

新增 Search（搜索采集）模块，支持热门、最新、用户、媒体、Lists 五种搜索类型
补全 TweetInfo 的 media_urls 字段解析（图片/视频/GIF）
搜索结果支持 cursor 分页
Search 模块 Python 绑定（client.search.search_top() 等）
Search 模块 API 文档和示例文档
TweetInfo 新增 10 个字段：lang、possibly_sensitive、views_count、conversation_id_str、is_quote_status、quoted_status_id_str、author_display_name、author_profile_image_url、author_is_blue_verified、author_followers_count
TweetResult 新增 tweet_info: Option<TweetInfo> 字段，create_tweet 成功时自动填充完整推文信息
通用响应 dump 工具（DUMP_RESPONSES 环境变量开关，调试用）

Fixed¶

修复 SearchTimeline GraphQL query ID 过期问题（404）
修复 Media 搜索解析：适配 grid 布局（search-grid entry + items 数组）
修复 Lists 搜索解析：适配 module 布局（list-search entry + items 数组）

1.0.6 - 2026-03-29¶

Added¶

Settings 模块：新增账号隐私设置功能
账号敏感内容设置（nsfw_user、display_sensitive_media）
搜索安全设置（optInFiltering、optInBlocking）
查询当前设置状态
完整的 Python 绑定和强类型响应
code-docs-guardian 文档守护 skill（被动监控 + 主动审查两种模式）
Settings 模块完整文档和示例

Fixed¶

mkdocs.yml 导航菜单补全 Settings 模块

1.0.5 - 2026-03-24¶

Fixed¶

更新 Followers/Following GraphQL query ID（适配 Twitter API 变更）
新增批量采集 followers/following 测试

Added¶

llms.txt 和 llms-full.txt（AI 可读的 API 文档）
Cloudflare Pages 配置 /llms.txt 根路径重定向

Changed¶

补充文档网站维护规范和 DM v2 注意事项
修复文档与实际 API 不一致的问题

1.0.4 - 2026-03-18¶

Changed¶

Transaction 模块适配 webpack manifest 新格式，拆分提取逻辑

1.0.3 - 2026-03-13¶

Added¶

DM v2 接口：实现私信 v2 发送（send_message_v2、send_batch_v2、send_batch_with_custom_texts_v2）
DM v2 支持纯图片发送（text 为空 + media_id）
DM v2 GraphQL API 支持媒体附件发送
XChat 对话列表接口（get_conversations）
多账号批量发送 + 收件箱验证测试

Changed¶

统一异步并发模式，修复多项 async 问题
代码质量优化两轮（clippy 修复、DRY、性能改进），达到 A- 标准
DM 客户端按 Rust 最佳实践重构
标记 get_user_updates 为弃用，改用 get_conversations

Fixed¶

GraphQL DM 响应解析，正确提取 event_id
GraphQL API 域名改为 api.x.com
补全 inbox 新类型的 Python 导出和类型存根
关注用户功能实现

1.0.2 - 2026-02-14¶

Fixed¶

CreateTweet 226 反爬检测及多图上传问题
rquest 5.x multipart 请求的 Content-Type 问题
Emulation default_headers 合并陷阱（清空 default_headers 解决）

Changed¶

Python 导出方式重构以符合社区惯例
CI/CD 流水线迁移到组织 self-hosted runner
PyPI 发布迁移到 ubuntu-latest
macOS 构建按需安装 cmake

1.0.1 - 2026-01-23¶

Added¶

Communities 模块：社区搜索和加入功能
search_communities() 方法，支持分页
join_community() 方法
Community、CommunitySearchResult、JoinCommunityResult 强类型
User 模块：新增用户资料获取、编辑、头像/Banner 更换
Transaction 模块：动态生成 X-Client-Transaction-Id
Twitter 类构造函数改为异步 create() 方法
跨平台编译支持（Linux Docker 构建）

Changed¶

UserClient 构造函数改为异步创建方法
HTTP 客户端和请求头生成逻辑重构
移除批量发送私信时的 client_transaction_ids 参数

1.0.0 - 2026-01-15¶

Added¶

DM 模块：Twitter 私信发送核心功能
单条私信发送
批量并发发送
批量自定义文案发送（send_batch_with_custom_texts）
Upload 模块：三阶段图片上传（INIT -> APPEND -> FINALIZE）
批量上传（MD5 扰动获取多个独立 media_id）
支持带图片的私信
Posts 模块：发帖、删帖、点赞功能
Inbox 模块：收件箱功能
User 模块：用户资料获取
Fingerprint 模块：浏览器指纹随机化
基于 Cookies 的认证机制
rquest HTTP 客户端（JA3/JA4 指纹模拟）
完全异步的 Python 绑定（PyO3）
模块化 Python API（client.dm.send_message() 风格）
GitHub Actions 构建与发布工作流
macOS universal2 + Linux aarch64 wheels 构建