x-api-rs

X/Twitter Web 私有 API 的 Rust 核心库、Python 绑定和 CLI 工具。

当前架构

本仓库已经拆分为 Rust workspace：

src/core  # x-api-core：真实业务实现
src/py    # x-api-py：Python 绑定
src/cli   # x-api-cli：命令行工具，二进制名 x-api

核心协议边界统一放在 x_api_core::web。XChat 是 Web 协议下的复杂子域，位于 web::xchat。

Rust 用法

use x_api_core::web::{WebClient, WebProfile};

#[tokio::main]
async fn main() -> x_api_core::Result<()> {
    let cookies = "ct0=xxx; auth_token=yyy; twid=u%3D123456789";
    let client = WebClient::builder()
        .cookies(cookies)
        .profile(WebProfile::default_latest())
        .build()
        .await?;

    let result = client.dm().send_message("123456789", "hello", None).await?;
    println!("{result:?}");
    Ok(())
}

Python 用法

from x_api_rs.web import Client, WebProfile

client = await Client.create(
    cookies,
    proxy_url=None,
    profile=WebProfile.default_latest(),
)

# 只有 auth_token、还没有完整 cookies 时，先换取 cookies 再创建客户端：
res = await Client.auth_token_to_cookies(auth_token, proxy_url=None)
client = await Client.create(res.cookies)  # res.cookies 含 auth_token + ct0 + twid

Web 环境快照

WebEnvironmentSnapshot 可把 cookies、CSRF、auth token、user id、代理、WebProfile、UA/请求头策略、ClientTransaction 材料和可选 XChat keystore 材料导出为 JSON，适合存入数据库后下次离线还原客户端。

快照是明文敏感数据，包含可直接恢复账号会话的 cookies/token，启用 XChat 时还可能包含私钥材料。生产环境应由调用方使用数据库加密、KMS 或应用层加密后存储。

let snapshot_json = client.export_environment()?.to_json()?;
let restored = WebClient::restore_environment(WebEnvironmentSnapshot::from_json(&snapshot_json)?)?;

snapshot_json = client.export_environment_json()
restored = Client.restore_environment_json(snapshot_json)

CLI 用法

x-api --cookies-file cookies.txt dm send --user-id 123 --text "hello"
x-api --cookies-file cookies.txt environment export --allow-plaintext-secrets > state.jsonl
x-api environment restore-check --state-file state.json
x-api auth token-to-cookies --token <auth_token> --allow-plaintext-secrets
x-api version-full
x-api output-schema

CLI 输出保持 JSONL envelope，适合 agent、脚本和管道消费。

验证命令

cargo check --workspace --all-features
cargo test -p x-api-core --all-features --no-run
cargo test -p x-api-cli --all-features

Python wheel 构建需要安装 maturin：

python3 -m maturin build --manifest-path src/py/Cargo.toml --features "dm upload inbox user posts communities settings search xchat"