x-api-rs 3.0.1__tar.gz

x_api_rs-3.0.1/.cargo/config.toml

@@ -0,0 +1,10 @@
+# 使 cargo 使用系统 git CLI 拉取 git 依赖，而非内置 libgit2。
+#
+# 原因：juicebox_sdk@0.3.4 的子模块 artifacts 在其 .gitmodules 中使用
+# SCP 风格 URL (`git@github.com:juicebox-systems/juicebox-sdk-artifacts.git`)，
+# libgit2 不接受这种格式（"relative URL without a base"），但系统 git 接受。
+#
+# 配合 `git config --global url."https://github.com/".insteadOf "git@github.com:"`
+# 把 SSH URL 重写为 HTTPS，避免 CI 上无 SSH key 拉不到子模块。
+[net]
+git-fetch-with-cli = true

x_api_rs-3.0.1/.claude/commands/update-docs.md

@@ -0,0 +1,68 @@
+# 文档更新命令
+
+自动检测代码变更并同步更新所有相关文档，确保无遗漏。
+
+## 执行流程
+
+### Step 1: 确定更新类型
+
+询问用户更新类型：
+1. **新增模块** - 新增了功能模块（如 communities）
+2. **API 变更** - 修改了现有 API（如构造函数变更）
+3. **其他** - 用户指定具体更新内容
+
+### Step 2: 读取检查清单
+
+读取 `docs/development/doc-update-checklist.md` 获取完整的更新规则。
+
+### Step 3: 调用 docs-architect agent
+
+使用 Task 工具调用 docs-architect agent 执行批量文档更新：
+
+```
+Task(
+  subagent_type="docs-architect",
+  prompt="根据以下变更更新文档：<变更描述>，参考 docs/development/doc-update-checklist.md 中的规则确保所有文件都被更新"
+)
+```
+
+### Step 4: 验证更新
+
+**新增模块验证命令**：
+```bash
+MODULE="<module_name>"
+grep -n "$MODULE" README.md docs/index.md docs/README.md docs/api/README.md docs/examples/README.md
+ls docs/api/${MODULE}.md docs/examples/${MODULE}_demo.md
+```
+
+**API 变更验证命令**：
+```bash
+grep -rn "<旧API模式>" docs/ README.md
+# 结果应为空
+```
+
+## 必须更新的文件清单
+
+### 新增模块（全部必须）
+
+| 文件 | 内容 |
+|------|------|
+| `README.md` | 功能模块表格 |
+| `docs/index.md` | 功能模块表格 |
+| `docs/README.md` | API 参考导航 |
+| `docs/api/README.md` | 文档列表 + 快速导航 |
+| `docs/examples/README.md` | 示例分类表格 |
+| `docs/api/<module>.md` | 新建 API 文档 |
+| `docs/examples/<module>_demo.md` | 新建示例文档 |
+
+### API 变更（全局搜索替换）
+
+```
+README.md
+docs/**/*.md
+```
+
+## 客户端创建规范
+
+正确：`client = await Twitter.create(cookies)`
+禁止：`client = Twitter(cookies)`

x_api_rs-3.0.1/.claude/memory/MEMORY.md

@@ -0,0 +1,76 @@
+# x-api-rs 项目记忆
+
+## 用户工作流偏好
+- **采访式需求收集** — 技术决策由我做（遵从 Rust 理念），业务决策问用户；用户不懂 Rust，不要问技术选型问题
+- **计划文件工作流** — 计划存 `.claude/plans/`（中文文件名），完成移至 `completed/`，待测移至 `pending-test/`
+- **不执行直到被告知** — 用户说"开始执行"前只做分析和计划，不修改代码
+
+## SDK 设计原则
+- [SDK 配置必须暴露给上层](feedback_sdk_config_extensibility.md) — HTTP/性能/可用性参数（timeout/retry/proxy/pool/JA3）必须 ClientConfig 化，不能硬编码；默认值"非幂等操作安全为先"
+- [文档同步优先级提升](feedback_docs_sync_priority.md) — 代码改动必须同 commit 更新 docs/，bug 修复/新配置项/API 变更必须当次完成（CHANGELOG + API doc）
+
+## rquest 5.x 关键行为
+- `.json()` 和 `.multipart()` 均使用 `or_insert` 设置 Content-Type — 已有则不覆盖
+- header builder 中不应手动设置 Content-Type，交给 rquest body 方法自动管理
+- **Emulation default_headers 合并陷阱** — `execute_request()` 会将 Client 的 default_headers 补充到 per-request headers 中（缺失的 key 自动补回）。`headers.remove()` 在 per-request HeaderMap 上无效，必须在 ClientBuilder 层清除：`.emulation(X).default_headers(HeaderMap::new())`
+- **Emulation 注入的 Upgrade-Insecure-Requests** — 仅适用于导航请求，API/XHR 请求不应携带，已通过清空 default_headers 解决
+- 源码: `~/.cargo/registry/src/index.crates.io-*/rquest-5.1.0/src/client/`
+- **`http2_max_retry_count` 默认 = 2** — H2 收到 RST_STREAM(REFUSED_STREAM) 或 GOAWAY(NO_ERROR) 自动重发。Twitter 限流会先处理请求再发 RST_STREAM，导致非幂等写操作（DM/Posts）重复。已在 `RquestClient::build_client` 设为 0。源码: `src/client/http.rs:225, 2367-2396`
+
+## Burp Suite 代理限制
+- Burp 作为 TLS MITM 会破坏 JA3 指纹模拟 → Twitter 看到 Burp 的指纹 → 触发 226
+- 大文件 multipart 上传 (>~100KB) 通过 Burp 会失败："Stream failed to close correctly"
+- 测试代理通过 `TEST_PROXY` 环境变量控制，默认无代理直连
+
+## CI / 发版流水线
+- [wheel runner 迁移方案](ci_wheel_runner_migration.md) — x86_64 慢=QEMU模拟根因；迁 ubuntu-latest + aarch64迁ubuntu-24.04-arm + macOS留Mac mini；硬约束：必须留manylinux容器(PyPI拒裸linux_x86_64)/需libclang/不改job名
+
+## 已知架构债务
+- `user/client.rs` 用 `as_any()` downcast 绕过 HttpClient trait
+
+## 已完成的重构
+- `build_upload_headers` 已删除，替换为 `UploadClient::upload_headers()`（仅含 Host + Referer）
+- `build_twitter_headers` 不再设置 Content-Type，由 rquest body 方法自动管理
+- Chrome 指纹数据扩展至 144 版本，支持新旧 sec-ch-ua 格式
+- upload INIT 阶段 media_type 自动检测（magic bytes: JPEG/PNG/GIF/WebP）
+
+## 业务功能要点
+- [拉黑→解除拉黑 = 强制清除粉丝](feature_block_unblock_force_remove_follower.md) — block 强制对方取消关注，unblock 不会恢复
+
+## REST 端点实现
+- [必须走 HttpClient::post trait](x_rest_endpoints_need_httpclient_trait.md) — `.client().post()` 直链会绕过 csrf 头注入，导致 "Bad Authentication data"
+
+## 提交规范
+- [提交时包含计划文件](feedback_commit_plan_files.md) — git commit 时不要遗漏 .claude/plans/ 下的文件
+
+## 开发流程
+- [必须运行真实集成测试](feedback_must_run_integration_tests.md) — 开发完成后必须 `cargo test <模块> -- --ignored --nocapture`，不能只跑本地参数校验
+- [子代理完成报告必须实证](feedback_subagent_completion_verify.md) — Agent 返回成功后主 session 必须独立跑 cargo 验证，不能直接采信子代理摘要
+- [字符串长度校验用字符数而非字节数](feedback_string_length_charcount.md) — `text.len()` 是 UTF-8 字节数，中文场景会误判；DM 用 `chars().count()`，Posts 用 `twitter_weighted_length()`
+- **CLI 无条件必须** — 任何暴露给外部的新功能（含调试工具、辅助接口），必须同时实现 CLI 子命令；不得以"调试用途"为由跳过。CLAUDE.md Phase 2.6 旧文本"若 CLI 已发布"已删除，现为无条件强制。
+
+## Twitter GraphQL
+- query ID 会不定期轮换，过期返回 404 → 从 [vladkens/twscrape](https://github.com/vladkens/twscrape) 获取最新值
+- 搜索 API 并发请求易触发限流（404），需单独验证失败的测试
+
+## ClientTransaction 调试
+- [ondemand.s 混淆变量名会变化](feedback_x_obfuscation_var_names.md) — 报 "无法提取 KEY_BYTE indices" 时先查变量名是否从 `n[..]` 变了，正则要用 `\w` 通配
+
+## 测试
+- `cargo test --lib` — 可靠的单元测试（193 tests，含 settings 和清理类功能模块）
+- `cargo test` 包含 doctest，因 crate 名称问题全部失败（已知，非回归）
+- 集成测试代理: `TEST_PROXY=127.0.0.1:8080 cargo test ... -- --ignored --nocapture`
+
+## 2026-06-01 抓包：content warning / disclosure 协议
+- [content warning / disclosure 协议字段](x_content_warning_protocol_2026_06_01.md) — `media/metadata/create.json` 设置图片级：`sensitive_media_warning:[adult_content|graphic_violence|other]` + `self_reported_ai_generated:"true"` + `grok_actions.block_grok_edit:"true"`（全字符串）。CreateTweet 的 `content_disclosure.ai_generated_disclosure` 设置帖子级 Made with AI。两个 AI 字段独立
+
+## 2026-05-27 抓包：CreateTweet 协议快照
+- [CreateTweet 协议变更](x_create_tweet_protocol_2026_05_27.md) — queryId 轮换为 `H-t2v_HvFR07ZBP9aOeKoA`；variables 新增 `semantic_annotation_options:{source:"UniversalLink"}`、移除 `dark_request`；features 38 项含 5 项新增 / 2 项移除 / 2 项值变更；content warning(Nudity/AI) 字段待带图场景补抓
+
+## 2026-05-08 抓包：清理类功能 GraphQL queryId（已验证）
+- `BookmarksAllDelete: skiACZKC1GDYli-M8RzEPQ` — body `{variables:{}, queryId}`
+- `ListUnsubscribe: -diULb6PX5grQ_MvItGiJQ` — body `{variables:{listId}, features:{6项固定}, queryId}`
+- `ListSubscribe: Gpws7iVbAR7ebO3qCCYmPw` — 同上结构
+- `ListsManagementPageTimeline: MZPMTf6uAC8bCYZmoiqVVg` — GET，30+ features
+- `DeleteRetweet: ZyZigVsNiFO6v1dEks1eWg`（旧 `iQtK4dl5hBmXewYZuEOKVw` 仍有效）
+- chrome-devtools 抓包技巧：先 `fetch main.js` regex 提取 operationName↔queryId 映射；动态 chunk 需访问对应页面触发加载（如 /i/bookmarks → bundle.Bookmarks.js）

x_api_rs-3.0.1/.claude/memory/ci_wheel_runner_migration.md

@@ -0,0 +1,28 @@
+---
+name: ci-wheel-runner-migration
+description: build-and-release.yml 三个 wheel job 的 runner 迁移方案与约束（QEMU根因/manylinux必需/成本）
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: e9324e28-4626-4b22-9fcc-51dd5db5ccb0
+---
+
+build-and-release.yml 的三个 wheel job 当前全跑在一台 self-hosted Apple Silicon Mac mini（`[self-hosted, macOS, ARM64]`）。x86_64 wheel 用 `docker run --platform linux/amd64 ... maturin build --manylinux 2_28` = **QEMU/Rosetta 模拟 amd64**，是 2h+ 卡死 / `libwriteable-*.rlib: failed to open object file` 报错的根因（不是 nasm、不是 juicebox 网络问题）。
+
+**迁移方案（2026-06-03 已实施并合并到 master）**：
+- x86_64 → `ubuntu-latest`（托管原生 amd64，1× 计费）—— 已合并 commit a1840dd，分支实测 7.4min（原 QEMU 2h+ 卡死）
+- aarch64 → `ubuntu-24.04-arm`（托管原生 ARM64，私有仓 2026-01-29 起可用、2 vCPU、占套餐免费分钟非无限免费；cli-docker.yml 已用此 label）—— 已合并，分支实测 6.3min
+- docs.yml（文档部署）→ 也迁到 `ubuntu-latest`（PR #6 / commit 4e522a8），原因同样是 Mac mini 网络反复让 `mike` 推 gh-pages 失败；Python 从 uv 换 actions/setup-python；master 已实测全绿（mike+cloudflare）
+- macOS wheel → **仍保留 Mac mini**（物理需 Apple 硬件 + 托管 macOS 是 10× 倍率 $0.062/min 最贵）。⚠️ 这是发版唯一的自托管单点：Mac mini 排查中反复网络抖动/接不了单，下次发版若它离线 macOS wheel 会卡住整条发布。待定：稳住 Mac mini，或 macOS 也迁 `macos-14` 托管（10×）
+- ⚠️ wheel 流水线只在 tag/release/dispatch 触发，迁移后 master 自身尚未端到端跑过（仅分支 workflow_dispatch 验证过 Linux 两 job），下次正式发版自然验证
+
+**硬约束（违反会回归）**：
+1. PyPI 拒收裸 `linux_x86_64` wheel → 迁移后**必须仍在 manylinux 容器内构建**（保留 `--manylinux 2_28`），不能裸 `maturin build`。
+2. boring-sys2 4.15.15 用 bindgen → **需要 libclang**；stock manylinux_2_28 不预装。若用 maturin-action 公开镜像，`before-script-linux` 必须装 `cmake clang clang-libs llvm-devel openssl-devel perl-IPC-Cmd` + `LIBCLANG_PATH=/usr/lib64`。**Linux 不需要 nasm**（仅 Windows）。
+3. 只改 `runs-on`，**绝不改 job 名 / artifact 名**——`github-release`/`pypi-publish` 的 needs 链 + release body 硬编码了 job 名和文件名 `cp38-abi3-manylinux_2_28_{arch}`（由 abi3-py38+容器决定，与 runner 无关，名字不变则链接不失效）。
+
+**最小改动做法（Option 0，推荐先做）**：保留现有 `docker run BUILDER_IMAGE ... maturin build` 命令一字不改，只换 host（`--platform` 在原生 host 上变无开销），保留 docker login GHCR（拉私有镜像），删 self-hosted 专属的"清理残留产物"步骤。比改用 maturin-action 风险低（复用已验证镜像，免手维护依赖清单）。
+
+成本：open-luban = Org Free = 2000 免费分钟/月，按当前发版频率三件套 ≈100min/月，现金成本 ≈$0。验证用 `test-v*` tag（跳过 CLI 门禁）+ `curl -I` 校验下载链接。
+
+相关：[[feedback_must_run_integration_tests]]（迁移后需真实跑一轮验证）

x_api_rs-3.0.1/.claude/memory/feature_block_unblock_force_remove_follower.md

@@ -0,0 +1,11 @@
+---
+name: 拉黑→解除拉黑 = 强制清除粉丝
+description: block→unblock 组合可强制对方取消关注当前账号；当前 SDK 只暴露原子 block/unblock，组合逻辑在 CLI/示例层完成
+type: project
+originSessionId: 48d12030-f020-438e-b6d4-5a79505022a3
+---
+「强制清除粉丝」语义通过 `user.block(uid)` → `user.unblock(uid)` 组合实现。
+
+**Why:** 拉黑会强制对方取消关注当前账号；解除拉黑只解锁双向交互，不会自动恢复关注关系。这是 Twitter 的固有行为，不是 SDK 设计。
+
+**How to apply:** SDK 层只提供原子 `block` / `unblock` 方法（`src/x/user/client.rs`）。CLI 没有 `--force-remove-follower` 一键 flag — 用户需自行 `&&` 串联两条命令。Python 示例 `examples/python/user/block_unblock.py` 演示了完整组合逻辑。

x_api_rs-3.0.1/.claude/memory/feedback_commit_plan_files.md

@@ -0,0 +1,11 @@
+---
+name: 提交时不要遗漏计划文件
+description: git commit 时必须包含 .claude/plans/ 下的计划文件，不要只提交代码
+type: feedback
+---
+
+提交功能代码时，必须同时提交对应的 `.claude/plans/` 计划文件（包括 pending-test/ 中的）。
+
+**Why:** 用户发现第一次提交遗漏了计划文件，需要额外补一次提交。计划文件是开发成果的一部分。
+
+**How to apply:** 在 `git add` 阶段检查是否有 `.claude/plans/` 下的新增或移动文件需要一并提交。

x_api_rs-3.0.1/.claude/memory/feedback_docs_sync_priority.md

@@ -0,0 +1,19 @@
+---
+name: 文档同步优先级提升
+description: 公共 API 变更必须代码+文档同一 commit；breaking change 有专属检查清单；不许分两次提交
+type: feedback
+originSessionId: 37625ac9-2a59-469c-81ef-5a1b0b82f074
+---
+代码改动必须**同次工作**完成对应文档更新，不能拖到下次。优先级：🔴 bug 修复 > 🟡 新配置项 > 🟢 重构/优化。
+
+**Why（2026-05-09）：** 修复 rquest H2 重试 bug 后，Rust trait/Python docstring 都改了，但 docs/api/dm.md、CHANGELOG、configuration.md 没有同步，文档漂移。
+
+**Why（2026-06-04，加强）：** settings 模块 breaking change（删除 20 个方法）完成后，代码先提交、文档后提交，中间存在不一致窗口。用户要求加强约束，增加了两条规则。
+
+**How to apply：**
+
+**规则 B（门控）：** 涉及新增/删除/重命名公共 API 时，代码 commit 和文档 commit 必须是同一个 commit。不允许先提交代码再提交文档，哪怕相差几分钟。提交前口诀：有没有删/加公共 API？→ 有 → docs/api、docs/cli、llms-full.txt、CHANGELOG 都改了吗？→ 没改完 → 不许提交。
+
+**规则 C（breaking change 清单）：** 删除/重命名已发布公共 API 时，逐项勾选：CHANGELOG Breaking Changes 节、docs/api/<module>.md 完全重写、docs/cli/<module>.md 完全重写、llms-full.txt 段落替换、cli/llms-full.txt 段落替换、版本号 major bump 确认、删除类型已从文档移除。
+
+具体映射表和完整清单见 `CLAUDE.md` 的"📚 文档同步原则 / 任务完成门控 / Breaking Change 专属检查清单"章节。

x_api_rs-3.0.1/.claude/memory/feedback_must_run_integration_tests.md

@@ -0,0 +1,11 @@
+---
+name: 必须运行真实集成测试
+description: 开发完成后必须运行真实 API 调用的集成测试，不能只跑本地参数校验
+type: feedback
+---
+
+开发完成后必须运行真实调用集成测试（`cargo test <模块> -- --ignored --nocapture`），不能只跑本地验证测试就标记完成。
+
+**Why:** 2026-04-07 搜索模块开发中，只运行了 4 个本地参数校验测试就标记完成，用户指出必须运行真实 API 调用测试验证功能可用。
+
+**How to apply:** 每次新功能开发的测试阶段，必须在文档更新之前运行 `cargo test <模块> -- --ignored --nocapture` 执行真实集成测试，并报告测试结果。

x_api_rs-3.0.1/.claude/memory/feedback_sdk_config_extensibility.md

@@ -0,0 +1,11 @@
+---
+name: SDK 配置必须暴露给上层
+description: 本项目是 SDK，HTTP/性能/可用性类配置必须通过 ClientConfig 暴露，不能硬编码
+type: feedback
+originSessionId: 37625ac9-2a59-469c-81ef-5a1b0b82f074
+---
+SDK 层只设置"安全默认值"，所有可调 HTTP/性能/可用性参数（timeout、retry、proxy、pool、JA3、并发数）必须通过 `ClientConfig` 暴露给上层使用方。
+
+**Why:** 用户明确指出本项目是 SDK 不是 end-user app。2026-05-09 修 rquest `http2_max_retry_count` 重复发 DM 的 bug 时，第一反应是直接硬编码 `0`，被用户纠正：应该让外层可配置 + 文档说明，而不是 SDK 写死。SDK 写死意味着每个集成方都得 fork 才能调整，违背 SDK 的可扩展性本质。
+
+**How to apply:** 任何在 `src/common/` 或基础设施层添加配置项时，先问"这是 Twitter 协议常量还是 HTTP/性能参数"——前者可硬编码（如 GraphQL queryId、`MAX_MESSAGE_LENGTH`、Bearer Token），后者必须走 `ClientConfig`。设计默认值时遵循"对非幂等操作安全为先"（如 retry 默认 0）。同时在 `docs/api/` 文档中说明每个配置的默认值、风险、何时该改。紧急 hotfix 可以先硬编码止血，但下个 minor 版本必须重构为可配置。

x_api_rs-3.0.1/.claude/memory/feedback_string_length_charcount.md

@@ -0,0 +1,30 @@
+---
+name: Rust 字符串长度校验必须用字符数而非字节数
+description: 对 Twitter API 文本字段做长度上限校验时，禁止使用 String::len()（UTF-8 字节数），中文/emoji 会被误判超限
+type: feedback
+originSessionId: d67384aa-3051-4fc6-81a8-c6505550a524
+---
+Rust 中 `String::len()` 和 `&str::len()` 返回 **UTF-8 字节数**，而非字符数。
+对 Twitter API 的文本长度做上限校验时：
+
+- **DM 私信（10000 字符限制）**：用 `text.chars().count()`
+- **Posts 发帖（280 限制）**：Twitter 用加权计数（CJK/emoji=2, URL=23, Latin=1），
+  使用 `src/x/posts/types.rs::twitter_weighted_length()` 函数
+
+**Why**：2026-04-20 在 `posts/client.rs:468` 和 `dm/client.rs` 发现字节数校验
+bug——中文每字符占 3 字节，导致 Posts 93 个中文即被误判超过 280 限制（实际
+Twitter 加权计数仅 186）、DM 约 3333 个中文即触发 10000 字节超限。Python 绑定层
+`src/python/dm/client.rs` 还有 6 处相同 bug 的重复校验代码。
+
+已修复版本：release-v1.0.12（commit 2ad5030）。
+
+**How to apply**：
+- 任何 `if text.len() > LIMIT` 或 `if text.len() >= LIMIT` 的长度比较都是可疑
+  signal，必须复核：上限是字符数还是字节数？
+- Twitter 的文本字段一律是字符/加权单位，不是字节。默认用 `chars().count()` 或
+  加权函数
+- 审计新模块时搜索 `\.len\(\) > [A-Z_]+LENGTH` 和 `\.len\(\) > \d+` 两种模式
+- 只有对明确的字节语义限制（如文件大小、HTTP body 字节数、charset 字节约束）
+  才允许用 `.len()`
+- Python 绑定层如果重复做长度校验（Rust 业务层已经做了一遍），要么同步修，
+  要么考虑删除 Python 层的重复校验让 Rust 兜底

x_api_rs-3.0.1/.claude/memory/feedback_subagent_completion_verify.md

@@ -0,0 +1,14 @@
+---
+name: feedback-subagent-completion-verify
+description: "子代理自报\"测试/编译通过\"必须用主 session 实证，不能直接采信"
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: 9647dc95-2033-4599-9400-4c51ccaa6d23
+---
+
+子代理报告任务完成时，必须用主 session 独立跑一遍验证命令并核对输出。
+
+**Why:** 2026-05-12 rust-pro 在 x-api-rs 项目报告"receive 测试通过"，实际只跑了 receive，send 仍卡在 NotEnrolled 直到主 session 主动跑才暴露。子代理上下文受限，可能漏测、误读输出、或选择性报告。
+
+**How to apply:** Agent 工具返回成功后，针对它声称"已验证"的命令至少抽样跑一条，比对实际 stdout 与子代理摘要。差异处优先信 cargo/pytest 输出。

x_api_rs-3.0.1/.claude/memory/feedback_x_obfuscation_var_names.md

@@ -0,0 +1,16 @@
+---
+name: ondemand.s 混淆变量名会随版本变化
+description: 修复 ClientTransaction "无法提取 KEY_BYTE indices" 错误的诊断思路
+type: feedback
+originSessionId: 6b073450-afb2-41d6-a7f8-64867e736789
+---
+排查 `ClientTransaction` 报 `无法提取 KEY_BYTE indices` 时，先怀疑 X.com 的 `ondemand.s` JS 混淆变量名换了，而非算法变了。
+
+**Why:** X.com 不定期重新混淆前端 JS，承载 key byte 索引的临时变量名会变化（已观察到从 `n[..]` 变成 `t[..]`），但语义形态 `(变量[数字],16)` 保持稳定。本项目和上游 iSarabjitDhiman/XClientTransaction 都踩过这个坑——上游已用 `\w` 通配单字母变量名。
+
+**How to apply:**
+1. 用 chrome-devtools 抓 `https://abs.twimg.com/responsive-web/client-web/ondemand.s.<hash>.js`
+2. `grep -oE '\(\w\[[0-9]+\], ?16\)' /tmp/<file>` 验证至少 4 个匹配
+3. 如果命中但变量名不是 `n`，只需放宽 `src/common/transaction/client.rs:KEY_BYTE_INDICES_REGEX` 中字母约束
+4. 如果完全没匹配 `(X[N],16)` 形态，才考虑算法变更（参考 `iSarabjitDhiman/XClientTransaction` 仓库的最新代码）
+5. `cargo test --lib test_extract_key_byte_indices_from_js` 单元测试 fixture 已使用带括号格式 `(n[7],16)`，向后兼容

x_api_rs-3.0.1/.claude/memory/x_content_warning_protocol_2026_06_01.md

@@ -0,0 +1,83 @@
+---
+name: x-content-warning-protocol-2026-06-01
+description: "2026-06-01 抓包确认的 Twitter content warning / disclosure 协议：分布在 media/metadata/create.json 与 CreateTweet 两处，且存在两个独立的\"AI\"字段"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: f332723c-c191-40c8-b2ce-0e9ab6f8fefd
+---
+
+抓包时间：2026-06-01（chrome-devtools，UI 流程：上传图片 → Edit media → Content warning 勾选 Nudity + Generated with AI → 返回 → Content disclosure 开启 Made with AI → 发帖）。
+
+## 字段分布在两个请求中
+
+**Nudity / Violence / Sensitive / 图片级 AI / Block-Grok** → `POST /1.1/media/metadata/create.json`（每个 media_id 一个请求，在 CreateTweet 之前调用，Content-Type: application/json，需要 Bearer + csrf）：
+
+```json
+{
+  "media_id": "<media_id>",
+  "sensitive_media_warning": ["adult_content", "graphic_violence", "other"],  // 数组，按需多选
+  "allow_download_status": {"allow_download": "true"},                         // 字符串 "true"
+  "self_reported_ai_generated": {"self_reported_ai_generated": "true"},        // 字符串 "true"，对应"Content warning → Generated with AI"
+  "grok_actions": {"block_grok_edit": "true"}                                  // 字符串 "true"，对应"Block modifications by Grok"
+}
+```
+
+字段映射：
+- Nudity → `sensitive_media_warning: "adult_content"`
+- Violence → `sensitive_media_warning: "graphic_violence"`
+- Sensitive → `sensitive_media_warning: "other"`
+- "Generated with AI"（在 Content warning 面板，图片级）→ `self_reported_ai_generated`
+- "Block modifications by Grok"（在 Content warning 面板）→ `grok_actions.block_grok_edit`
+- `allow_download_status`：UI 无独立控件，似乎默认始终带 `"true"`
+
+字段值类型全部是**字符串 "true"**（不是 bool），`sensitive_media_warning` 是字符串数组。响应体为空（HTTP 200 + empty body）。
+
+**帖子级 "Made with AI"** → `POST /i/api/graphql/CreateTweet` 的 `variables` 新增：
+
+```json
+"content_disclosure": {
+  "ai_generated_disclosure": {
+    "has_ai_generated_media": true,
+    "ai_generated_detection_source": "UserDeclared"
+  }
+}
+```
+
+## 两个 AI 字段独立
+
+- "Content disclosure → Made with AI" 顶层 toggle → CreateTweet 的 `content_disclosure.ai_generated_disclosure`（帖子级声明）
+- "Content warning → Generated with AI" 在媒体编辑器 → media/metadata/create.json 的 `self_reported_ai_generated`（图片级声明）
+
+二者不互相联动，用户可以单独开任一边。
+
+## 服务端回响（CreateTweet response 中的回显字段）
+
+```json
+"sensitive_media_warning": {
+  "graphic_violence": true,    // bool 而非字符串
+  "other": true
+}
+"possibly_sensitive_editable": true   // tweet 顶层
+```
+
+注意：响应里的 `sensitive_media_warning` 是 **object/bool**（`{"graphic_violence": true}`），不是发送时的字符串数组。
+
+## 待补抓
+
+- "Paid partnership" toggle 对应的 CreateTweet/metadata 字段（本次未开启）
+- 多张图片各自不同 warning 时的请求形态（应该是多次 metadata/create.json 调用）
+
+## 抓包样本路径
+
+- `.claude/captures/create_tweet_with_warning.network-request` — CreateTweet body
+- `.claude/captures/media_metadata_create.network-request` — media/metadata body
+- 测试 tweet text: "test capture content warning"，media_id: 2061431868747309056
+
+## SDK 实现建议
+
+在 `src/x/posts/` 新增：
+1. `PostsParams` 增加 `ai_generated_disclosure: bool`（帖子级）
+2. 新增 `MediaWarning` 入参（每张图片可独立配置 Nudity/Violence/Sensitive + 图片级 AI），实际调用顺序：upload FINALIZE → media/metadata/create.json（若有 warning）→ CreateTweet
+3. `media/metadata/create.json` 走 HttpClient::post + Bearer + csrf，body 为 JSON
+4. CreateTweet 在 `client.rs:76-115` 构造 variables 时按需注入 `content_disclosure` 字段

x_api_rs-3.0.1/.claude/memory/x_create_tweet_protocol_2026_05_27.md

@@ -0,0 +1,76 @@
+---
+name: x-create-tweet-protocol-2026-05-27
+description: 2026-05-27 chrome-devtools 抓包获取的 CreateTweet 最新协议参数与当前代码差异
+metadata: 
+  node_type: memory
+  type: reference
+  originSessionId: 8a2ef1de-5940-4767-af0d-533d198c617f
+---
+
+# CreateTweet 协议快照(2026-05-27)
+
+抓包来源:chrome-devtools 实测 hedda44673 账号在 x.com/home 发纯文本帖,reqid=570。
+
+## 端点
+
+- URL: `https://x.com/i/api/graphql/H-t2v_HvFR07ZBP9aOeKoA/CreateTweet`
+- **queryId 已从 `Ah3G_byjEDs_HSlgU0PyZw` → `H-t2v_HvFR07ZBP9aOeKoA`**
+- Method: POST, Content-Type: application/json
+
+## Variables(纯文本帖最小集)
+
+```json
+{
+  "tweet_text": "...",
+  "media": { "media_entities": [], "possibly_sensitive": false },
+  "semantic_annotation_ids": [],
+  "disallowed_reply_options": null,
+  "semantic_annotation_options": { "source": "UniversalLink" }
+}
+```
+
+### 与 src/x/posts/client.rs 的差异
+
+- ➕ **新参数** `semantic_annotation_options: {"source": "UniversalLink"}` — 当前代码缺失
+- ➖ **已移除** `dark_request: false` — 当前代码多余字段,Twitter 已不再要求
+- 🟡 reply / attachment_url 在纯文本帖中不出现(条件字段,需补抓 reply/quote 场景验证)
+
+## Features(38 项实测,与当前代码差异)
+
+### 新增(代码必须补)
+- `rweb_cashtags_enabled: true`
+- `rweb_cashtags_composer_attachment_enabled: true`
+- `rweb_conversational_replies_downvote_enabled: false`
+- `content_disclosure_indicator_enabled: true` — 内容披露总开关
+- `content_disclosure_ai_generated_indicator_enabled: true` — AI 生成披露开关
+
+### 已移除(代码需删)
+- `responsive_web_enhance_cards_enabled`
+- `tweet_awards_web_tipping_enabled`
+
+### 值变更
+- `responsive_web_grok_community_note_auto_translation_is_enabled`: false → **true**
+- `longform_notetweets_inline_media_enabled`: true → **false**
+
+## Content Warning(待补抓)
+
+UI 中"Content warning"对话框包含 Nudity / Violence / Sensitive / Generated with AI / Block modifications by Grok 五项,**字段不在纯文本帖里**。
+
+- features 里 `content_disclosure_*_enabled` 已开启,说明协议支持
+- 真实字段路径与值需在**带图发布 + 勾选 Nudity + 勾选 Generated with AI** 的场景下抓包确认
+- 推测挂载位置:`media.media_entities[i]` 内,或顶层新增 `content_warning` / `disclosure` 字段
+
+## Headers(已被项目 build_twitter_headers 覆盖,无需改动)
+
+`authorization`(Bearer)、`x-csrf-token`、`x-twitter-auth-type: OAuth2Session`、`x-twitter-active-user: yes`、`x-twitter-client-language`、`x-client-transaction-id`、`referer: https://x.com/home`、`origin: https://x.com`
+
+## 测试痕迹
+
+- 测试账号: hedda44673(u=2039411983011790848)
+- 已发布 tweet_id: `2059542161897763324`
+- 链接: https://x.com/hedda44673/status/2059542161897763324
+
+## 相关
+
+- [[feedback_must_run_integration_tests]] — 修改 queryId/features 后必须跑真实集成测试验证
+- [[feedback_docs_sync_priority]] — 同步更新 docs/api/twitter-api.md 端点表

x_api_rs-3.0.1/.claude/memory/x_rest_endpoints_need_httpclient_trait.md

@@ -0,0 +1,11 @@
+---
+name: REST 端点必须走 HttpClient::post trait
+description: 直接调用 .client().post() 会绕过 auth/csrf 头注入导致 "Bad Authentication data"
+type: feedback
+originSessionId: 48d12030-f020-438e-b6d4-5a79505022a3
+---
+新增 REST 端点（如 `blocks/create.json`、`account/remove_profile_image.json`）时，必须走 `HttpClient::post(...)` trait 方法，而非 `.as_any().downcast::<RquestClient>().client().post(...)` 直链。
+
+**Why:** trait `post` 会自动用 `build_twitter_headers()` 注入 Authorization / x-csrf-token / x-twitter-active-user 等 Twitter API 必需头。直接调用 rquest builder 只发 cookies，导致 `api.x.com/1.1/blocks/create.json` 返回 400 "Bad Authentication data"（即使 ct0 cookie 在域内也不行 — Twitter 严格校验 x-csrf-token 头）。
+
+**How to apply:** 用 `client.post(url, &[], None, RequestBody::Form(...) | RequestBody::Empty, None).await?`，第三参数 `None` 触发自动头生成。`UserClient::post_form_action` / `post_empty_action` 已封装好这两种情况。已废弃的反例：`src/x/user/client.rs::follow/unfollow` 用了 downcast 直链（仅因 friendships/create.json 域为 x.com 走 cookie 同源认证侥幸可用）— 待后续迁回 trait。

x_api_rs-3.0.1/.claude/plans/20260511-160000-XChat-v3-/346/200/273/350/247/210/344/270/216/351/207/207/350/256/277/347/273/223/350/256/272.md

@@ -0,0 +1,133 @@
+# XChat v3 总览与采访结论
+
+> **目标**：在 `src/x/xchat/` 新增模块，实现 X 官方新版 XChat 端到端加密私信完整链路（与 web 客户端 wire 兼容），SDK 发版号跳跃至 **v2.0.0**。
+> **范围**：完整 E2E（含 AES-GCM 加密 + Juicebox PIN 备份） + 1v1 + 群组 + 文本/图片/视频/附件 + 发送 + 接收解密。
+> **预计工时**：14-21 工作日，拆 4 phase 递交。
+> **状态**：📋 规划完成，等待用户「开始执行」指令。
+
+---
+
+## 总待办（4 个 phase）
+
+- [ ] **Phase 1 — 基础设施**（[计划](./20260511-160001-XChat-v3-Phase1-基础设施.md)，预计 3-4 天）
+- [ ] **Phase 2 — Enrollment**（[计划](./20260511-160002-XChat-v3-Phase2-Enrollment.md)，预计 4-5 天）
+- [ ] **Phase 3 — 1v1 加密发收**（[计划](./20260511-160003-XChat-v3-Phase3-1v1发收.md)，预计 4-5 天）
+- [ ] **Phase 4 — 群组与媒体**（[计划](./20260511-160004-XChat-v3-Phase4-群组媒体.md)，预计 5-7 天）
+
+每个 phase 完成后：
+1. 调 `code-reviewer` agent 审查该 phase 变更（**必办事件**）
+2. 跑该 phase 集成测试（用 `tests/fixtures/xchat_e2e_evidence/cookies_20260511.json` + PIN）
+3. 更新本 phase 计划文件顶部 TODO 为已完成
+4. 移动到 `.claude/plans/pending-test/`
+5. 等待用户审批
+6. 用户审批后移到 `.claude/plans/completed/`，方可启动下一 phase
+
+---
+
+## 关键决策汇总（来自采访）
+
+| 决策点 | 选择 | 理由 |
+|---|---|---|
+| 核心目标 | **完整 E2E**（加密+签名+备份+收发） | 与官方 web 客户端完全兼容 |
+| 模块归属 | **新建 `src/x/xchat/`** | 与 dm/v1/v2 独立，不破坏现有 |
+| 发版号 | **v2.0.0**（主版本跳跃） | 新增大量依赖 + 新模块面积 |
+| Enrollment 模式 | **仅 CustomPin** | 与官方 web 一致，依赖 Juicebox |
+| 加密策略 | **双方均 enrolled 时自动加密**，否则明文签名 | 与官方一致 |
+| 收件人未 enroll | 返回 `DMResult { warning: 'recipient_not_enrolled' }` 仍发送 | 与官方一致 |
+| Conversation key | **SDK 内部自动管理** | 用户无感知 |
+| 接收 | **实现完整发+收** | E2E 闭环 |
+| 群组 | **1v1 + 创建群 + 群内发消息** | 含 ratchet tree |
+| 媒体 | **文本 + 图片 + 视频 + 其他附件** | 含 InitializeXChatMediaUpload 链路 |
+| Franking | **不实现** | 服务端不强制；放弃举报能力 |
+| 密钥存储 | **JSON 文件 + 用户传入路径** | SDK 提供工具方法首次生成 |
+| PIN 输入 | **API 参数明文传入** | `client.xchat.enroll(pin="8527")` |
+| 错误模型 | **新增 `XChatError`**，与 `TwitterError` 透传 | 不污染现有错误枚举 |
+| 重试 | **不重试** | 与 v1.0.15 修复一致（非幂等保护） |
+| 批量 | **send_batch + send_batch_with_custom_texts** | 与 dm v1/v2 一致 |
+| Python API | **`client.xchat.send_message(user_id, text)`** | 与现有 client.dm/posts/user 一致 |
+| 状态查询 | **`is_enrolled()` / `xchat_status()`** | 让上层判断 |
+| Juicebox 实现 | **依赖 `juicebox-sdk` Rust crate**，必要时 fork | 节省 5 天 |
+| 密码学栈 | **RustCrypto 生态**（p256, aes-gcm, sha2, hmac, hkdf, x509-cert） | 纯 Rust，maturin 友好 |
+| 集成测试 | **用 `@mamadoufri23588` 真实账号** | 已 enrolled，PIN=8527 |
+| 测试消息清理 | **不删**，留作证据 | 与 CLAUDE.md 一致 |
+| 文档 | **`docs/api/xchat.md` + `examples/python/xchat/` + mkdocs nav + `llms-full.txt`** | 全套 |
+| CLAUDE.md | 加 XChat 模块专章 | 让未来 AI agent 同步 |
+| 阶段交接 | **每 phase 都 code-reviewer + 集成测试 + 用户审批** | 安全优先 |
+| 验证复用 | **`validate_message` 抽到 `src/common/text_validation.rs`** | 跨模块共享 |
+
+---
+
+## 不在 v3 范围内（明确排除）
+
+- ❌ ManagedPin / SelfCustody enrollment（仅 CustomPin）
+- ❌ Franking HMAC 生成
+- ❌ ReportFrankedMessageMutation
+- ❌ XChatGrokSearchMutation
+- ❌ DmAvPermissions / Voice / Video call E2EE（AvCallE2eePipelines）
+- ❌ Screen capture blocking
+- ❌ Mute / Disable / TTL / Disappearing messages
+- ❌ Welcome message
+- ❌ Group invite links
+- ❌ 自动重试（用户显式选择不要）
+
+如需扩展，放 v3.x minor 版本迭代。
+
+---
+
+## 依赖增量预估（Cargo.toml）
+
+```toml
+# 新增
+p256 = { version = "0.13", features = ["ecdh", "ecdsa", "pkcs8"] }
+aes-gcm = "0.10"
+sha2 = "0.10"
+hmac = "0.12"
+hkdf = "0.12"
+x509-cert = "0.2"     # for SPKI encoding
+spki = "0.7"
+pkcs8 = "0.10"
+zeroize = "1.7"        # 安全擦除密钥
+juicebox-sdk = "0.3"   # 待评估，必要时 fork
+rand_core = "0.6"
+```
+
+---
+
+## 风险与缓解
+
+| 风险 | 概率 | 缓解 |
+|---|---|---|
+| `juicebox-sdk` crate 与 X 的 realm 不兼容 | 中 | Phase 2 开始时先做 1 天 spike，必要时 fork |
+| 测试账号被 X 检测为异常并冻结 | 低 | 使用真实 cookies + 不批量调用敏感接口 |
+| Thrift Binary 还有隐藏字段差异 | 中 | Phase 1 用抓包做字节级 diff 验证 |
+| `ratchet_tree_change` 算法逆向不完整 | 高 | Phase 4 可降级为「仅文本群发」如果群密钥逆向卡壳 |
+| 媒体上传加密细节缺失（需要 Phase 4 抓包补充） | 高 | Phase 4 第一步重新抓包补全 |
+| RustCrypto 与官方 web 实现微小不一致（如签名编码差异） | 低 | Phase 1 用 capture 做 byte-for-byte 验证 |
+
+---
+
+## 整体里程碑
+
+```
+Phase 1 ────► 基础设施（无 Twitter 调用） ────► code-review ────► pending-test ────► 用户审批
+                                                                                      │
+Phase 2 ◄──── 真实 enroll + Juicebox 联调 ◄──── 真实 GetPublicKeys ◄──── 用户审批 ◄──┘
+   │
+   └─► code-review ─► pending-test ─► 用户审批 ─► Phase 3
+
+Phase 3 ────► 真实 1v1 加密发收 ────► code-review ────► pending-test ────► 用户审批
+                                                                              │
+Phase 4 ◄──── 群+媒体（依赖前 3）◄──── 用户审批 ◄────────────────────────────┘
+   │
+   └─► code-review ─► pending-test ─► 用户审批 ─► v2.0.0 发版
+```
+
+---
+
+## 参考资料
+
+- 逆向文档：[`docs/architecture/xchat-e2e-reverse-engineering.md`](../../docs/architecture/xchat-e2e-reverse-engineering.md)
+- 抓包证据：[`tests/fixtures/xchat_e2e_evidence/`](../../tests/fixtures/xchat_e2e_evidence/)（gitignored）
+- 复盘报告：`tests/fixtures/xchat_e2e_evidence/findings_20260511.md`
+- RFC 9420 (MLS)：https://www.rfc-editor.org/rfc/rfc9420.html
+- Juicebox SDK：https://github.com/juicebox-systems/juicebox-sdk