catbus/docs/upstream-map.md

# 上游移植对照（references/ → catbus）

移植某个平台时查这份文档：上游的鉴权、登录、API 方法、要复制的 JS 资产、游客态和长连接的代码位置。

- 行号是写这份文档时的位置，只用来定位。动手前以 `src/platforms/<p>/UPSTREAM` 记录的 commit 为准，重新核对一遍。
- catbus 的规范见 [AGENTS.md](../AGENTS.md)，能力矩阵见 [capabilities.md](capabilities.md)。
- 「上游凭证来源」只用于理解上游代码和在本机跑上游对比；catbus 不读这些位置。

## 1. 通用

- 10 个上游都是 Python。
  - HTTP 以 `curl_cffi` 为主，用来模拟 Chrome 的 TLS / JA3 与 HTTP/2 指纹。
  - Weibo、Xianyu、Taobao 用的是 `requests`。
- 签名 JS 在上游里有两种调用方式：
  - `subprocess` 调 `node`；
  - `PyExecJS`，共三处：XHS 的 `xhs_creator_util.py`、Xianyu 的 `utils/goofish_utils.py`、Taobao 的 `utils/taobao_utils.py`。

  catbus 里统一改成 `node:vm` 执行（见 AGENTS.md 7.4）。
- 上游 JS 实际 `require` 的第三方 npm 模块只有三个，其余都是 Node 内置模块：
  - `jsdom`：JD；
  - `crypto-js`：XHS；
  - `@napi-rs/canvas`：JD；KS 的 `kwf_oracle.js` 里是 try/catch 的可选依赖。

### 1.1 Python → TS 替换对照

| 上游 Python | catbus |
|---|---|
| `curl_cffi`、`requests` | wreq-js（`core/http.ts`） |
| `websockets`、`websocket-client` | wreq-js 的 WebSocket（`core/stream.ts`） |
| `protobuf` + pb2 | protobufjs |
| `blackboxprotobuf`（无 schema 解码） | protobufjs 的 Reader |
| `onnxruntime` | onnxruntime-web |
| `opencv`、`scikit-image`、`scipy`、`numpy` | @techstark/opencv-js，其余手工移植 |
| `opencv` 的视频探测（`cv2.VideoCapture` 取帧率、帧数、宽高） | `core/mp4.ts` 读 MP4 / MOV 的盒子（xhs、tiktok）；截帧要解码，不做 |
| `Pillow` | @napi-rs/canvas |
| `ddddocr` | 移植到 onnxruntime-web 上 |
| `pydantic` | zod |
| `loguru` | catbus 的 stderr logger |
| `subprocess node x.js`、`PyExecJS` | `node:vm`（见 AGENTS.md 7.4） |
| `qrcode` | qrcode |

### 1.2 游客态生成

对应 AGENTS.md 5.2 的 `guest.json`。

| 平台 | 生成位置 | 内容 |
|---|---|---|
| xhs | `xhs_utils/common_util.py:34` `generate_a1`、`:42` `generate_web_id` | `a1`、`webId` |
| douyin | `dy_apis/login_api.py:861` `register_ttwid`；`utils/dy_util.py:107` `generate_msToken`、`:185` `generate_webid`；`utils/mstoken.py:308` | `ttwid`、`msToken`、`webid` |
| tiktok | 没有生成器，`msToken` 来自 cookie（`builder/auth.py:156`） | 游客态需要在 catbus 里补 |
| bilibili | `builder/auth.py:52` `BiliAuth.anonymous`；`utils/device.py` | `buvid3` / `buvid4` 等 |
| kuaishou | `ks_apis/login_api.py:732` `bootstrap_device_fingerprint` | 设备指纹 cookie |
| weibo | 上游没有：`WeiboMobileApis` 不带 cookie 访问 m.weibo.cn | 现在不带 cookie 会被 302 到访客页。catbus 访问 m.weibo.cn 时用新浪访客系统 `genvisitor2` 下发的访客 SUB / SUBP（登录后也是，登录 cookie 属于 .weibo.com）；这只是 m.weibo.cn 的访问方式，web 端没有游客态 |
| xianyu | `utils/build_cookies.py:52` `build_initial_cookies` | 先调一次 mtop 拿 `_m_h5_tk`，再调一次拿 `cookie2`；含 `tfstk` |
| taobao | `taobao_apis.py:29` `get_token` | `_m_h5_tk` |
| jd | `utils/device_token.py:112` `get_device_fields` | 设备字段 |
| x | `builder/auth.py:26` `GUEST_ACTIVATE_URL` = `https://api.x.com/1.1/guest/activate.json`，`:87` `XAuth.guest_token` 惰性换取 | guest token，约 3 小时有效。上游的读接口并不带它；web 端不支持游客态，catbus 没有移植 |

### 1.3 长连接

对应 `live listen` / `msg listen`。

| 用途 | 位置 | 地址 |
|---|---|---|
| douyin 私信 | `dy_apis/douyin_recv_msg.py:42` | `wss://frontier-im.douyin.com/ws/v2` |
| douyin 直播 | `dy_live/server.py:178` | `wss://webcast100-ws-web-hl.douyin.com/webcast/im/push/v2/` |
| tiktok 私信 | `api/tiktok_chat.py:21` | `wss://im-ws.tiktok.com/ws/v2` |
| tiktok 直播 | `api/tiktok_web.py:5597` | `wss://webcast-ws.tiktok.com/webcast/im/ws_proxy/` |
| xhs 直播 | `apis/xhs_live.py:31` | `wss://apppush-rws.xiaohongshu.com/rwp` |
| kuaishou 直播 | `ks_apis/live_api.py:1169`、`ks_apis/live_ws.py` 的 `LiveDanmakuClient` | 由接口下发 |
| xianyu 私信 | `goofish_live.py:18` | `wss://wss-goofish.dingtalk.com/` |
| taobao 私信 | `taobao_live.py:19` | `wss://wss-cntaobao.dingtalk.com/` |
| jd 客服 | `jd_apis/jd_chat_ws.py:5` | `wss://ws1-dd.jd.com/` |

---

## 2. 各仓库

### xhs — Spider_XHS

- **鉴权**
  - `xhs_utils/xhs_auth.py` 的 `XHSUnifiedAuth` 包含两个子鉴权：`.pc` 为 `XHSPcAuth`，`.creator` 为 `XHSCreatorAuth`，都继承自 `xhs_core/auth.py` 的 `XHSAuth`。
  - 构造方式：`from_qrcode_login`、`from_phone_login`、`from_cookie`。
  - 必需的 cookie 是 `a1` 和 `web_session`，按 host 分域存储。创作者中心对应 catbus 的 `creator` scope。
- **登录**：`apis/xhs_pc_login_apis.py` 的 `XHSLoginApi` 和 `apis/xhs_creator_login_apis.py` 的 `XHSCreatorLoginApi`，都有 `qrcode_login`、`phone_login`。
- **上游凭证来源**：`.env` 的 `COOKIES`。
- **API**（实例方法）
  - `apis/xhs_pc_apis.py` 的 `XHS_Apis`：`get_note_info(url)`、`get_user_info`、`get_user_me`、`get_user_all_notes`、`get_user_all_like_note_info`、`get_user_all_collect_note_info`、`search_note`（`note_time` 对应 `--time`）、`search_some_note`、`search_user`、`get_search_keyword`、`get_note_all_comment`、`get_homefeed_recommend`、`get_unread_message`、`get_all_metions`、`get_note_no_water_video/img`
  - `apis/xhs_creator_apis.py` 的 `XHS_Creator_Apis`：`post_note`、`upload_media`、`get_all_posted_notes`。视频的时长、宽高、帧率上游用 opencv（`extract_video_cover_and_metadata`），catbus 读 MP4 盒子算出同样的值；首帧封面要解码，catbus 不做，视频发布要 `--cover`
  - 直播与私信：`apis/xhs_live.py` 的 `XHSLiveAPI`（HTTP：直播间、`get_chats` / `get_group_chats`、`get_message_history` / `get_group_message_history`、`get_following`、已读 / 撤回 / 删除）和 `XHSWebSocket`（RWP 长连：私信收发、直播间事件、`send_room_text` 发弹幕）
    - `msg send` 先走长连（`send_private_message`），等发送回执最多 10 秒（上游只发不等）；长连没发出去（连不上、握手失败）才走 HTTP 短链 `send_short_link_message`。帧已发出却没等到回执时报 `NETWORK`（`detail.sent` 为 true），不重发，免得对方收到两条。`live send` 的长连退路同样处理
  - 创作者中心的登录态由主站会话桥接（`xhs_utils/xhs_auth.py` 的 `XHSUnifiedAuth.creator_auth` → `XHSCreatorAuth.from_pc_auth`）：catbus 存进 `creator` scope 复用，失效时自动重新桥接一次。桥接在凭证副本上做，全部成功后才写回，中途失败时凭证不变
  - `item publish --poi-name [--poi]`：上游按地点名搜索后取第一个；catbus 按 `--poi-name` 搜，给了 `--poi` 时取 id 相同的那个，否则取名称完全相同的，都没有时报 `USAGE`（按 id 搜不到地点，所以 `--poi` 不能单独用）
  - 蒲公英 `apis/xhs_pugongying_apis.py`、千帆 `apis/xhs_qianfan_apis.py`：不移植（AGENTS 4.12）
- **JS 资产**（npm 依赖 `crypto-js`）
  - `xhs_utils/xhs_core/js/`：`sign.js`、`xs_common.js`、`b1.js`、`mns.js`、`websectiga_cli.js`、`websectiga_env.js`，以及 mns keystream 的 JSON
  - `xhs_utils/xhs_pc/js/`：`sign.js`、`xs_common.js`、`b1.js`、`mns.js`、`rap.js`、`rap_cli.js`、`rap_crypto.js`、`web_ssk.js`、`aes_encrypt.js`、`aes_decrypt.js`、`deflate.js`、`profile.js`，以及模板 / profile 的 JSON
  - `xhs_utils/xhs_creator/js/`：`xhs_creator_sign.js`、`xhs_creator_signature.js`、`profile.js`，以及指纹 / profile 的 JSON
- **注意**：拿笔记详情需要 `xsec_token`，所以优先传 URL；catbus 输出的 xhs `url` 都带上它。

### douyin — DouYin_Spider

- **鉴权**
  - `builder/auth.py` 的 `DouyinAuth.perepare_auth(cookieStr, web_protect_, keys_)`（方法名原文如此拼写）。
  - 私信签名还需要 `ticket`、`ts_sign`、`client_cert`、`private_key`。catbus 里放在凭证文件的 `tokens` / `device`。
  - 写接口和 passport 请求带 `x-tt-session-dtrait`：外层由 `utils/dtrait.py` 按请求 path 现算，内层是绑定设备的特征 blob。上游 `DouyinAuth.session_dtrait_header` 取内层的顺序是 `DY_DTRAIT_BLOB`（抓到的 blob）> 设备档案（`DY_DTRAIT_PROFILE` 指定的，否则是随包的 `utils/dtrait_profile.json`，由 `utils/dtrait_features.py` 的 `build_blob` 现算）。默认档案来自上游 `fix-dtrait-blob` 分支（还没合进 master，catbus 以它为基线，见 `UPSTREAM`），是从 Chrome 153 DevTools 取证固化的。
  - 哪些请求必须按 path 现算（上游 `Header.with_session_dtrait`，`strict=True`、`allow_static=False`：缺素材就报错，不用成品头）：发布（`create_v2`）、评论（`publish_comment` 的 `with_bd(require_dtrait=True)`）、收藏（`collect_aweme`）、收藏夹移动（`move_collect_aweme` / `remove_collect_aweme`）。`digg` 仍是算得出就带（成品头也行）。catbus 对应 `Douyin.withSessionDtrait`、`withBd(..., { requireDtrait: true })`。
  - catbus 对应：凭证 `device` 里的 `dtrait_blob`、`dtrait_profile`（都可选，用 `--cookie` 的 JSON 对象导入），没有时用 `static/douyin/dtrait_profile.json`；`build_blob` 移植在 `web/dtrait.ts`。Math 指纹的入参全是字面常量，直接写 Chrome 的结果：Node 24 自带的 V8 在 `atanh(0.5)`、`log(3)`、`expm1(1)` 上与 Chrome 差 1 ULP（实测），macOS 的 libm 在 `tan(-1e300)` 上与 V8 差 1 ULP（对拍脚本把它固定成 V8 的值）。
- **登录**：`dy_apis/login_api.py` 的 `DYLoginApi`：`qrcode_login`、`send_sms_code`、`phone_login`、`save_credential`、`get_login_auth`。
  - 短信默认走 passport-web（`/passport/web/send_code`、`sms_login`）；`DY_PHONE_LOGIN_PROFILE=sso` 时改走 `login.douyin.com` 页的 SSO 链（`bootstrap_phone_auth`、`_send_sms_code_sso` → `/send_activation_code/v2/`、`_phone_login_sso` → `/quick_login/v2/`）。上游把它当显式开关，不是失败后的退路；catbus 对应 `auth login --method sms --sso`。
- **上游凭证来源**：`.env` 的 `DY_COOKIES`、`DY_LIVE_COOKIES`、`DY_TICKET`、`DY_TS_SIGN`、`DY_CLIENT_CERT`、`DY_PRIVATE_KEY`、`DY_DTRAIT_BLOB`、`DY_DTRAIT_PROFILE`（设备档案的路径）、`DY_SESSION_DTRAIT`（成品头，只用于非严格的请求，如 `digg`；发布、评论、收藏、收藏夹移动不接受）。
- **API**（静态方法，第一个参数为 `auth`）
  - `dy_apis/douyin_api.py` 的 `DouyinAPI`：`get_work_info(url)`、`get_user_info(user_url)`、`get_user_all_work_info`、`get_work_all_comment`、`search_general_work`（五个筛选值 `sort_type` / `publish_time` / `filter_duration` / `search_range` / `content_type` 作为紧凑 JSON 放进 `filter_selected`，`content_type` 2 是图文 → `--type image`；`search_source` 为 `tab_search`）、`search_video_work`（视频频道，筛选值进 query，→ `item search --type video`）、`search_user`（`douyin_user_fans` / `douyin_user_type`）、`search_live`、`get_user_favorite`、`get_collect_list`（上游只取 `cursor=0` 的第一页；catbus 按响应的 `cursor` / `has_more` 翻页，`--folder` 也逐页找）、`move_collect_aweme` / `remove_collect_aweme`（→ `item collect / uncollect --folder`）、`get_user_follower_list/following`、`get_notice_list`（`notice_group` → `notice list --group`）、`get_feed`、`get_live_info`、`digg`、`publish_comment`、`collect_aweme`、`create_conversation`、`send_msg/image/video/file`、`send_share_aweme/share_photos/share_web/user_card`（→ `msg send --share`）
  - 直播：`get_live_room_enter`（→ `live get`，其中的 `stream_url` → `live media`）、`get_webcast_detail`（im/fetch，带回的最近 15 条 → `live history`）、`get_live_contribution_rank` / `get_live_thousand_ticket_rank`（→ `live rank --ranking`）、`diggLiveRoom`（`count` → `live like --count`）、`sendMsgInRoom`
  - 商品：`get_live_production` / `get_all_live_production`（直播间商品）、`get_live_production_detail`（→ `product get`）、`get_product_comments`（→ 商品评价，需要 `product_id` 和 `shop_id`；`tag_id` 来自 `get_product_comment_counter`，→ `--label`）
  - `dy_apis/douyin_creator_api.py` 的 `DouyinCreatorAPI`：`post_images`、`post_video`（`poi` / `mix_id` / `hot_spot` / `allow_download` / 图集 `cover_index`、`cover_uri`）、`get_preview_video_list`（work_list → `item list`）
  - TOS 上传：创作者中心的 `upload_video_direct` / `upload_video_parts` 与私信的 `_upload_source` 流程相同，catbus 合成一份 `web/tos.ts`；两边上游的差别（origin / referer、`content-crc32` 头的位置、uploadid 是否 quote、成功码的宽严）作为两套预设保留
  - `dy_apis/douyin_im_media.py` 的 `DouyinIMMedia`：`upload_image` / `upload_video` / `upload_file`，以及卡片的 `build_share_aweme_content` / `build_share_photos_content` / `build_share_web_content` / `build_user_card_content`
  - 没有移植：`send_sticker`（表情的 CDN 元数据要调用方给，上游没有取表情列表的接口）、`send_audio`（PC 端没有语音上传协议）、`get_conversation_list`、`get_live_pk_*`（AGENTS 4.12）
- **JS 与 proto 资产**（无第三方 npm 依赖）
  - `static/{Live,PK,Request,Response}.proto`，旁边是对应的 pb2
  - `utils/acrawler_runtime/`：`ac_vm.js`、`run_ac_node.js`、`browser_window_shape.json`、`canvas_actual_exact.json`
  - `utils/challenge_template_runner.js`
  - `utils/challenge_profile.json`、`utils/mstoken_common_profile.json`、`utils/mstoken_profile.json`、`utils/dtrait_profile.json`
- **注意**：`newsign/package.json` 声明了 `jsdom`、`canvas`、`sdenv`、`jsrsasign`，但没有任何代码引用，是遗留文件，不用管。

### tiktok — TiktokApis

- **鉴权**
  - `builder/auth.py` 的 `TiktokAuth.from_cookie(cookie_str)`。
  - 以存在 `sessionid`、`sid_tt` 或 `multi_sids` 之一判断已登录。
- **登录**：`api/tiktok_login.py` 的 `TiktokLoginAPI` 只有占位，调用即抛 `NotImplementedError`。所以只支持 cookie 登录。
- **上游凭证来源**：`demo.py` 读 `TIKTOK_COOKIE`。
- **API**：`api/tiktok.py` 的 `TiktokAPI`，继承自 `api/tiktok_web.py` 的 `TiktokWebAPI`，方法接收 `cookies_str`：
  - `get_user_posted(secUid)`、`get_user_info(user_url)`、`get_video_detail(video_url)`、`get_all_comments`、`post_comment`
  - 商城：`get_shop_product_detail`（→ `product get`）、`get_shop_product_reviews` / `get_all_shop_product_reviews`（→ 商品评价）
  - 其他：收藏、关注与粉丝列表、`post_item_digg`、`post_follow_user`、私信（`api/tiktok_chat.py`）、`creator_publish`、`creator_publish_photos`
  - 收藏夹：`post_collection_create` / `post_collection_modify_info` 的 `collection_status` 是网页 IDL 的 `CollectionStatus`（1 私密、3 公开），上游默认 1；`post_collection_modify_items`（→ `folder add`）只能加入，`commitIds` 一次一个；`post_collection_move_items` 是在收藏夹之间移动（AGENTS 4.12 不提供）；`get_collection_candidate_item_list` 只是网页「加入收藏夹」对话框的候选列表，不单独做命令
  - 通知：`get_notice_multi` 默认 group 500（动态：赞 / 评论 / @ / 关注），`get_inbox_notice_list` 默认 group 661（网页收件箱的系统通知 All，`template_notice` 结构），都 → `notice list`
  - 直播：`enter_live_room`、`check_live_rooms` 用于只给房间号的 `live get` / `like` / `rank` / `send` / `media`；拉流地址上游不解析，catbus 读 `liveRoom.streamData` 或房间对象的 `stream_url`
- **不移植**：`_prepare_creator_media` 里用 ffmpeg 读任意容器、截首帧（catbus 要求 `--cover`，只读 MP4）；`get_following_request_list`；旧版私信 WS；直播页的活动 / 游戏 / podcast 等辅助接口
- **JS 与 proto 资产**
  - `static/Tiktok_Request_pb2.py`：只有 pb2，没有 .proto。需要从 pb2 里的序列化 descriptor 导出 schema 给 protobufjs。
  - `signing/env/`：`env_core.js`、`sign.js`
  - `signing/source/`：`webmssdk.js`、`webmssdk_ex.js`、`webmssdk_legacy.js`
  - `signing/sdk_config.json`
  - `reverse/tiktok_shop_bsid/env/`：7 个 JS，商城签名用
  - 要移植成 TS 的 Python 签名：`signing/` 下的 `aws_v4.py`、`live_wire.py`、`protobuf.py`、`pure.py`、`shop_bsid.py`、`ticket_guard.py`
- **注意**：上游用了 `protobuf3_to_dict`，移植后用 protobufjs 的 `toObject` 代替。

### bilibili — BilibiliApis

- **鉴权**
  - `builder/auth.py` 的 `BiliAuth`：`from_cookie`、`from_qrcode_login`、`from_sms_login`、`from_session(path)`（读 session.json，支持自动刷新）、`anonymous`。
  - `is_login` 看 `SESSDATA`，csrf 取自 `bili_jct`。
- **登录**：`apis/bili_login_apis.py` 的 `BiliLoginApi`：`qrcode_login`、`sms_login`、`password_login`、`refresh_cookies`、`logout`。
  - `refresh_cookies` 对应 catbus 的自动刷新；`logout` 对应 `auth logout` 的服务端登出（10 个平台里有服务端登出的只有 B 站和快手）。
- **上游凭证来源**：仓库根目录的 `session.json`（`utils/session.py` 写入），`cookies.txt` 是兼容镜像。
- **API**（静态方法，第一个参数为 `auth`）
  - `apis/bili_apis.py` 的 `BiliApi`：`get_nav`、`search_type`、`get_video_info(bvid/aid)`、`get_video_detail`、`get_play_url`、`get_player_info`、`get_danmaku_seg`、`get_replies(oid)`、`get_user_info(mid)`、`get_user_videos`、`get_all_user_videos`、`get_rcmd_feed`、`get_popular`、`report_heartbeat`
  - `apis/bili_creator_apis.py`：`post_video`、`submit_archive`（转载来源、同步动态、禁止转载）、`delete_archive`、`get_my_archives`、`post_dynamic`、`remove_dynamic`、`save_article_draft`、`submit_article`、`get_article_draft`、`delete_article_draft`
  - `apis/bili_interact_apis.py`：`like`、`add_coin(also_like)`、`favour(add_media_ids, del_media_ids)`、`triple`、`add_reply(type_, root, parent)`、`delete_reply(type_)`、`send_danmaku(color, fontsize, mode)`
  - `apis/bili_live_apis.py`：`get_room_init`、`get_room_by_mid`、`get_room_info`、`send_gift`、`send_danmaku(color, mode, reply_mid, reply_uname)`、`start_live`、`stop_live`
- **catbus 的对应**（不直观的几处）
  - `item related` 取 `get_video_detail` 返回的 `Related`；`item search --type article` 是 `search_type(search_type='article')`。
  - 评论区类型按参数识别：稿件 1、专栏（cv 号）12、动态 17。动态只对纯文字和转发动态成立：图文动态的评论区是 type 11 + 相簿 rid，专栏动态是 type 12 + cv 号，从动态 ID 换过去要动态详情接口，上游没有，所以 `comment list / add / delete` 标 ◐。
  - `item subtitles` 用 `get_player_info` 返回的 `subtitle.subtitles[].subtitle_url` 下载字幕 JSON；上游的 `get_subtitle_view` 返回 protobuf，没有用。
  - `folder items` 是非上游的：上游没有收藏夹内容接口，按网页端补的 `x/v3/fav/resource/list`（`api.favResources`），没有对拍。`item uncollect` 不带 `--folder` 时，用 `get_fav_folders` 多带 `type=2&rid=<aid>` 的请求（非上游，`api.favFoldersOf`）按 `fav_state` 找收着它的收藏夹，没有 `fav_state` 时从全部收藏夹移出。
  - `article publish`：上游的 `save_article_draft` / `submit_article` 把 `banner_url` 固定为空串，没有专栏封面，所以没有 `--cover`。
  - upos 上传：上游四段都走 `http_util.request`，cookie 是整份 B 站 cookie，发往 upos 节点（bilivideo.com）时也带，catbus 照做。
  - 直播间参数传主播时，先用 `get_room_by_mid` 换房间号。
  - 推荐流翻页时，把上一批的 `av_<aid>`（已关注为 `av_n_<aid>`）作为 `last_showlist` 带上；格式见 bilibili-API-collect，上游只给了参数。
  - 长连接 `live/server.py`：op 3 的人气值和没有专门映射的 cmd 都输出为 Event `other`。
  - `delete_archive` 需要极验结果（`validate` / `seccode` / `challenge`），上游没有自动过验证，catbus 的 `item delete` 标 ◐，不带验证时报 `RISK_CONTROL`。
- **JS 资产**
  - `tools/sc_encrypt_bridge.js`：`apis/bili_gaia_apis.py:662` 调用，做风控指纹的加密上报。
  - 它还需要 `_gt/bili-sc-sdk.js`（`bili_gaia_apis.py:67`）。这是从 CDN 下载的第三方 SDK，上游不入库，多数环境里不存在。缺它时上游只发明文上报，已实证写接口照样成功。
  - catbus 的做法：只移植明文上报这一路，不复制 `sc_encrypt_bridge.js`。
- **验证码**：极验点选，`tools/geetest_solve.py`、`utils/geetest_hybrid.py`、`utils/geetest_metric.py`、`utils/geetest_ocr.py`，依赖 ddddocr、scipy、numpy、Pillow。
  - catbus 的对应：`web/geetest.ts`（`utils/geetest_w.py` 的 w 加密，`geetest_solve.py` 的 fetch / auto / _post_ajax / _refresh / solve），`web/geetest-vision.ts`（geetest_ocr / geetest_metric / geetest_hybrid，匈牙利算法照抄 scipy 的 rectangular_lsap），`web/ddddocr.ts`（ddddocr 1.6.1 的检测与识别，模型在 `@cv-cat/catbus-assets-ocr`，PIL 的 LANCZOS 与转灰度重写成 TS），`web/geetest-manual.ts`（`tools/geetest_helper.py` 的 serve：自动识别失败时在终端里改为本地页面手动验证）。
  - RSA 段（PKCS#1 v1.5）的随机填充改从 `core/rand.ts` 取，对拍时 gen.py 把上游的 `rsa_encrypt_key` 换成用框架随机字节的同一套填充。
  - `geetest_vision.prepare()` 只是把切图落盘给人看，不影响请求，没有移植。

### kuaishou — KuaiShou-Spider

- **鉴权**
  - `builder/auth.py` 的 `KuaishouAuth`：`prepare_auth(cookie_str)`、`initialize()`。
  - `kwscode` / `kwssectoken` 只有 6 分钟有效期，每次使用时现算，不落盘。
  - cookie 分三个站点：www、cp（创作者）、live。发布需要 `kuaishou.web.cp.api_st` 和 `kuaishou.web.cp.api_ph`。
- **登录**：`ks_apis/login_api.py` 的 `KuaishouLoginAPI`：`login_by_qr`、`request_mobile_code`、`login_by_mobile_code`、`sts_login`、`pass_token_login`、`login_browser_session`。
  - `sts_login` / `pass_token_login` 用来换取子站点凭证，登录时一并完成。
- **服务端登出**：`ks_apis/live_api.py` 的 `logout_session`（passport `login/logout` → `/live_api/baseuser/userLogout`）+ `builder/auth.py` 的 `apply_live_logout`。上游只放行一个写死的房间页 Referer。
- **上游凭证来源**：`.env` 的 `KS_COOKIES`。
- **API**
  - `ks_apis/kuaishou_api.py` 的 `KuaishouAPI`：`get_feed_hot`（new-reco 推荐流 → `feed list --kind recommend`）、`get_work_info`、`get_video_detail`、`get_comment_list`、`get_all_comment`、`get_sub_comment_list`、`get_profile`、`get_profile_feed`、`get_user_all_work`、`search_feed`、`search_user`、`get_relation`、`get_liked_list`、`get_collect_list`、`get_history_list`、`graphql`
  - 直播：`ks_apis/live_api.py` 的 `KuaishouLiveAPI`（礼物：`gift_list` 首屏与 `sort_type=0` 的“更多礼物”，`emoji_all_gifts` 完整礼物字典）；弹幕：`ks_apis/live_ws.py` 的 `LiveDanmakuClient`
  - 发布：`ks_apis/publish_api.py` 的 `KuaishouPublishAPI`；发布后 `video_photo_list(query_type=2, post_publish=True)` 取 publishId，`video_publish_refresh` 取发布状态
  - 翻页（catbus 补充）：`get_feed_hot` 每页都回 `pcursor="1"`，catbus 的游标写成 `<pcursor>:<已取页数>`，请求时只用 pcursor；`video_photo_list` 的时间范围服务端限一年，`item list` 在一年窗口里按 `nextCursor` 翻，翻完把窗口前移一年（游标 `<cursor>:<窗口终点>`），某个窗口没有作品时停止
  - 不在 `_LIVE_CURRENT_PATHS` 放行名单里的直播接口（`comment_add`、`comment_like`、`profile_like`、`liveroom_status` 等）上游运行时直接拒绝发包，不移植
- **上游基线**：当前移植的是 `feat/fix-slider-fingerprint-http2` 分支的 552cf60（还没合进上游 master），比 master d4fcfd0 多一个提交：刷新验证码指纹、gdfp 接受 HTTP/1.1。
- **浏览器档案**：`utils/fingerprint.py` 的 `get_profile()`（UA、平台、语言、时区、CPU、WebGL、屏幕 / 可用区 / 内外窗口几何）→ catbus `web/profile.ts` 的 `PROFILE`。请求头、gdfp manMachine 载荷、`captchaExtraParam` 都从它取值，不各自写死。
- **滑块验证码**：`KuaishouAPI._post` / `_get` / `graphql` 遇到 400002（GraphQL 是 `errors` + `data.captcha.url`）时调 `_pass_captcha` 过一次滑块，再重新序列化同一条 Cookie 线序重发。
  - `builder/auth.py` 的 `prepare_captcha_context`：验证码 iframe 以 `verification-captcha` 产品名单独引导 webweapon，Cookie 线序 `captcha`（`kwpsecproductname` 出现两次）
  - `utils/captcha.py`：`find_gap_x`（cv2 边缘图 + 带掩码的模板匹配，catbus 用 @techstark/opencv-js）、`build_trajectory`、`SlidingCaptcha`
  - `utils/captcha_fp.py`（`gpuInfo` / `captchaExtraParam`；key35 / key36 是稳定的浏览器哈希，只有 key18–key26 每次现算）、`utils/gdfp_manmachine.py`（SDK_INIT → core / whole `/n/a/b`）、`utils/sign/captcha_crypto.py`（三路 LFSR + 32 字节头）
  - 对应 catbus 的 `web/captcha.ts`、`gap.ts`、`captcha-fp.ts`、`gdfp.ts`、`captcha-crypto.ts`
  - **未移植**：`KuaishouAuth.set_captcha_fingerprint`（传给 `SlidingCaptcha` 的 `fingerprint`，用浏览器现抓的 `gpuInfo` / `captchaExtraParam` 代替随包默认值）：只有 Python API，没有 CLI 入口。catbus 始终用 `captcha-fp.ts` 的默认值。
- **HTTP 版本检查**：上游对 gdfp（`/s/w/c`、manMachine、vision、gameLive）检查协商出的协议，现在默认接受 HTTP/1.1，设 `KS_STRICT_GDFP_HTTP2=1` 才只认 HTTP/2；`utils/transport.py` 的 `_curl_http_version_value` 也接受字符串形式的枚举值。catbus 不查协议版本（wreq-js 拿不到协商出的协议），与上游的默认行为一致。
- **JS 与 proto 资产**
  - `reverse/bundles/weapon/`：21 个 JS（kwf，以及 kws-0 到 kws-19）
  - `reverse/js/cp-kwf.js`
  - `reverse/tools/`：`kwf_oracle.js`、`kws_oracle.js`、`like_token_oracle.js`
  - `reverse/fixtures/live_ws_proto.json`：直播 proto，可直接作为 protobufjs `Root.fromJSON` 的输入
  - `reverse/fixtures/live_ws_maps.json`：`utils/live_proto.py` 用到的映射表
- **Python 侧签名**：`utils/sign/weapon_oracle.py`、`like_token.py`，要移植成 TS。

### weibo — WeiboApis

- **鉴权**：没有鉴权对象，各方法直接接收 `cookies_str`。
- **登录**：上游没有，只支持 cookie 登录。
- **上游凭证来源**：无。仓库另带一个 FastAPI 服务 `app.py`，不移植。
- **API**
  - `apis/weibo_apis.py` 的 `WeiboApis`：`get_self_info`、`getUserInfo`、`getUserPosted`、`getWordComments`、`getWorkInfo`、`searchSome`、`get_user_all_posted`
  - `apis/weibo_mobile_apis.py` 的 `WeiboMobileApis`（m.weibo.cn，上游不带 cookie；catbus 带访客 cookie，见 1.2）：`getWorkInfo`（`item get`，`comment list` 缺作者 uid 时也用它查）、`searchSome`（`item search`：访客从第二页起是登录墙，只取第一页）。
  - `apis/weibo_creator_apis.py` 的 `WeiboCreaterApis.post_weibo`。`type`（请求里的 `visible`）：0 公开、1 仅自己、6 朋友圈（互相关注）、10 粉丝，对应 `--visibility public / private / friends / fans`
- **没有移植的**
  - `WeiboApis.getWorkInfo(url)`：请求 `weibo.com/<uid>/<mblogid>`，只取页面里的 `window.$CONFIG`。现在的 weibo.com 是单页应用，页面只是一个壳，`$CONFIG` 是全站配置（登录时多一个当前用户 `user`，`get_self_info` 取的就是它），没有微博正文；正文由前端另外请求 `/ajax/statuses/show`，上游没有这个接口。上游自己的 `app.py` 取详情也走 `WeiboMobileApis.getWorkInfo`。
  - `WeiboApis.searchSome`：只发请求，解析被注释掉，永远返回 None。
- **JS 资产**：`static/weibo.js` 存在，但 Python 里没有引用，不复制。

### xianyu — XianYuApis

- **鉴权**：没有独立的鉴权类。`build_initial_cookies()` 生成初始 cookie（含 `tfstk`，扫码登录前用），`XianyuApis(cookies, device_id)` 直接接收 cookie 字典；mtop 签名用 `_m_h5_tk`。
- **登录**：`goofish_apis.py` 里的函数 `qrcode_login()`。
- **上游凭证来源**：无。
- **API**
  - `goofish_apis.py` 的 `XianyuApis`：`get_token`（私信长连的 accessToken）、`refresh_token`（`mtop.taobao.idlemessage.pc.loginuser.get`：cookie 登录的校验、`auth status`、`user get me`，以及 `msg listen` 每 10 分钟的续期，对应上游 `user_alive`）、`get_item_info(item_id)`、`upload_media`、`get_public_channel`（按标题和图片推荐类目，`public` 内部调用）、`get_default_location`、`public`（发布商品；`price.original_price` → 私有选项 `--original-price`）
  - 私信：`goofish_live.py` 的 `XianyuLive`（async WebSocket）：`create_chat`（`item_id` 默认 `891198795482`，→ `msg send --to`；`--to` 加 `--item` 时用指定商品）、`send_msg`、`list_all_conversations(cid)`（→ `msg history`：同一条连接上按 nextCursor 翻页，结果从旧到新；`--limit` 截在一页中间时游标为 `<这一页的起始游标>+<已输出条数>`，续翻时重取这一页、跳过已输出的）、`main` / `heart_beat`（→ `msg listen`）
  - 连接、注册、ack、心跳、翻页与淘宝逐行相同，catbus 共用 `src/platforms/_shared/impaas.ts`
- **JS 资产**（catbus 原样复制到 `static/xianyu/`）
  - `static/goofish_js_version_2.js`：`utils/goofish_utils.py` 经 PyExecJS 调用的 `generate_sign`、`generate_mid`、`generate_uuid`、`generate_device_id`、`decrypt`（base64 + MessagePack）
  - `utils/gen_tfstk.js` + `utils/et_f.js`：生成 cookie `tfstk`（上游起 node 子进程）
  - `static/goofish_js_origin_version_2.js`、`static/goofish_js_version_1.js` 上游没有用到，没有复制
- **注意**：上游用相对 CWD 的路径读 JS。catbus 从 `static/xianyu/` 按包内路径加载，不受 CWD 影响。

### taobao — TaoBaoApis

与闲鱼同属阿里系，结构几乎一致：mtop 签名 + 钉钉 wss 私信。

- **鉴权**：没有独立的鉴权类，`TaobaoApis(cookies, device_id)` 直接接收 cookie 字典。`get_token()` 调 `mtop.taobao.login.token.get.h5`，签名用 `_m_h5_tk`。
- **登录**：上游没有，只支持 cookie 登录。
- **上游凭证来源**：无。
- **API**
  - `taobao_apis.py` 的 `TaobaoApis`：`get_token`、`get_goods_uid_encrypt_uid(goods_url)`（从商品页 HTML 里取卖家 `uid` / `encrypt_uid`，供 `msg send --item` 与 `user get <商品链接>` 用；上游没有按用户 ID 查询的接口）、`upload_media`
  - 私信：`taobao_live.py` 的 `taobaoLive(cookies_str)`（async WebSocket）：`list_all_conversations(cid)`（→ `msg history`：同一条连接上按 nextCursor 翻页，结果从旧到新；`--limit` 截断时的游标同闲鱼）、`create_chat`、`send_msg`（`sender_nick` 是 cookie `_nk_` 的原值，不解码）、`main` / `heart_beat`（→ `msg listen`）
  - 连接、注册、ack、心跳、翻页与闲鱼逐行相同，catbus 共用 `src/platforms/_shared/impaas.ts`
  - `utils/taobao_utils.py`：`generate_sign`、`generate_mid`、`generate_uuid`、`generate_device_id`、`decrypt`（实际是 base64 + MessagePack，由上游 JS 解码；import 了 blackboxprotobuf 但没用）、`trans_cookies`
- **JS 资产**：`static/taobao_js_20260407.js`
- **注意**
  - 上游**没有商品详情和商品搜索接口**。`item_detail_url` 字段是从闲鱼代码带过来的，没有使用。矩阵里 `item get` / `item search` 是 ○。
  - 与闲鱼一样，上游用相对 CWD 的路径读 JS；catbus 按包内路径加载。

### jd — JdApis

- **鉴权**
  - `builder/auth.py` 的 `JdAuth`：`is_login` 要求有登录票据 `thor`（PC 扫码下发）或 `pt_key`（M 端），再加上 `pin`（依次取 `pin`、`pt_pin`、`_pst`）。
  - 按 origin 保存 localStorage，catbus 里放在凭证文件的 `device`。
  - `update_cookies(persist=)`、`flush()`。
- **登录**：`jd_apis/jd_login_api.py` 的 `JdLoginAPI.qr_login`，以及 `jd_apis/jd_sms_login_api.py` 的 `JdSmsLoginAPI.login`。
- **上游凭证来源**：`default_auth_path()`，可用 `JDAPIS_AUTH_FILE` 覆盖。
  - Windows：`%LOCALAPPDATA%/JdApis/auth.json`
  - macOS：`~/Library/Application Support/JdApis/auth.json`
  - Linux：`$XDG_STATE_HOME/JdApis/auth.json`
- **API**：`jd_apis/jd_api.py` 的 `JdAPI`
  - `get_product_detail(sku)`、`get_product_comments`、`search`、`search_wares`、`get_browse_history`、`get_follow_products`、`get_cart_num`、`check_session`、`diagnose`
  - `get_order_list`（`:1348`，→ 扩展 `order list`）、`get_recommend_coupon(sku)`（`:929`，→ 扩展 `coupon list`）
  - 客服：聊天相关方法，以及 `jd_apis/jd_chat_ws.py` 的 `JdChatWS`
  - 参数对应：各接口的 `area` → 私有选项 `--area`；`get_order_list(date_range)` 的 `1` / `2` / 年份 → `order list --range 3m|this_year|<年份>`；`get_product_comments(count)` → `comment list --limit`；`get_chat_info` / `send_hello` / `send_text` 的 `order_id` → `msg send --order`；短信登录 `login(area_code)` 的国家码 → 从 `--phone` 的 `+` / `00` 前缀识别
  - `diagnose`（`:800`）：业务接口重试后仍 403 空 body 时只跑第一步 `check_session`，失效报 `AUTH_EXPIRED`，仍登录报 `RISK_CONTROL`（`rate_limit`）；不再发 hotwords / getCartNum 探针
  - `call_api` 命中 `_read_disposal`（`:413`，处置常常只在 `x-rp-content` 响应头里，body 为空、状态码 200）时照样返回原始结果：catbus 把解开的处置挂到结果上，报 `RISK_CONTROL`（`captcha`）
  - 上游只返回原始 JSON、不判业务失败。catbus 的映射：非 JSON 响应、网关错误 `{code, echo}`（如 601）、`success: false` → `UPSTREAM`；登录墙（code 3、购物车的 `pin is null`、浏览历史的 `resultCode: -100`）→ `AUTH_EXPIRED`。`code` 非 0 只对核对过正常值的接口（hotwords、getAidInfo、getChatSessionLog）判失败，其余接口正常响应里 code 的含义没核对过（getRecommendCoupon 会回只有 `{"code":"1"}` 的响应）
  - 没有移植：`get_diviner`（`:942`）的首请求要 `securityToken`，分页变体要「类目 `p`」和 `shopId`，上游注释要求传浏览器抓包值、没有调用处，也没有从详情接口推出 `p` 的方法，所以 `item related` 仍用 relsearch 的相关词搜索
- **JS 资产**（npm 依赖 `jsdom`、`@napi-rs/canvas`）
  - `static/`：`h5st5_env.js`、`h5st5_lib.js`、`h5st5_server.js`、`pc_tk_lib.js`、`pc_tk_server.js`、`summer_cryptico_runner.js`
  - `static/webm/env/run.js`、`static/webm/run/jdwebm-riskhandle.js`
  - `static/jcap/env/`：`env_core.js`、`run.js`；网络桥 `http_bridge.py` 移植为 `src/platforms/jd/web/jcap/helper.ts` 的 `bridge`
  - `static/jcap/run/`：`jcap_ujb96b.js`；图像求解 `captcha_solver.py` 移植为 `jcap/solver.ts`（由 `helper.ts` 的 `solve` 调用）。run.js 起这两个 Python 子进程的地方由预加载的 `jcap/host.ts` 换成 `helper.js`
  - `static/jcap/run/models/`：`orientation_model_v2_0.9882.onnx`、`u2netp.onnx`，共约 81 MB，放进 `@cv-cat/catbus-assets-jd`，不复制到 `static/`
  - 调用这些 JS 的 Python：`utils/h5st5.py`、`utils/device_token.py`、`utils/jcap_solver.py`、`utils/summer_cryptico.py`、`utils/webm.py`
- **注意**：上游 JS 用 `createRequire(<项目根>/package.json)` 解析 npm 模块。catbus 在 vm 里注入的 `require` 指向自己的 `node_modules`（见 AGENTS.md 7.4）。
- **验证码**：JCAP，依赖 onnxruntime、opencv、scikit-image、scipy。

### x — XApis

- **鉴权**
  - `builder/auth.py` 的 `XAuth.prepare_auth(cookies_str)`，需要 `auth_token` 和 `ct0`。
  - 支持 guest token（见 1.2），web 端不支持游客态，不移植；`prepare_auth` 未登录时本地生成 ct0 的分支同样不移植。
- **登录**：`x_apis/login_api.py`
  - `XLoginApi.login_by_password`
  - `XJetfuelLoginApi`：`login_by_password`、`login_by_password_pure`，后者需要 Castle profile。
  - **账密登录不移植**（依赖 Castle token）：catbus 只支持从浏览器导入 cookie。
- **上游凭证来源**：`.env` 的 `X_COOKIES`、`X_USERNAME`、`X_PASSWORD`、`X_PROXY`，以及 Castle profile 的 `CASTLE_PURE_RL_FILE`、`CASTLE_PURE_ONLY`。
- **API**（静态方法，第一个参数为 `auth`）
  - `x_apis/x_api.py` 的 `XAPI`：`get_work_info`、`get_work_comments`、`get_all_work_comments`、`search_work`、`get_user_info(user_name)`、`get_user_post_note`、`get_user_all_post_note`、`get_home_timeline`、`get_viewer`
    - `search_work` 的 `product`：`Top` / `Latest` 对应 `item search --sort general|latest`，`People` 对应 `user search`，`Media` 对应 `item search --type video|image`（结果里图片和视频混在一起，catbus 按 `Item.kind` 过滤）；`Lists` 不做。
  - `x_apis/x_write_api.py` 的 `XWriteAPI`：`post_tweet`（正文权重超过 280 时走 `create_note_tweet`，即 CreateNoteTweet 长推）、`post_thread`、`delete_tweet`、`favorite`、`retweet`、`bookmark`、`follow/unfollow`
    - 权重算法在 `utils/x_util.py` 的 `tweet_weight`（twitter-text v3）。
    - `create_tweet` 的 `quote_url` 对应 `item publish --quote`，`post_thread` 对应 `item publish --thread`。`comment add` 也走 `post_tweet`（带 `reply_to`，同 `main.py post --reply-to`），超长时同样自动长推。
    - `_rest_post`（关注）的业务拒绝（158 / 160 / 161 / 162）是 HTTP 403 + `errors`，catbus 先按错误码映射，没有错误码的 401 / 403 才当作登录态失效。
  - `x_apis/x_article_api.py` 的 `XArticleAPI`（文章，Premium 长文）：`create_draft`、`update_title`、`update_content`、`update_cover`、`publish`、`delete`、`list_articles`、`upload_image`，编排入口 `post_article`
    - 对应扩展命令 `article publish`（`post_article` 的 publish=True）、`article delete`；`list_articles`（草稿 / 已发布列表）没有暴露。
    - Markdown → Draft.js content_state 在 `utils/article_util.py`，catbus 移植到 `web/article.ts`。
    - 正文插图的相对路径按 `base_dir`（`main.py` 传 Markdown 文件所在目录）解析：catbus 用 `--text @file` 的文件目录（dispatch 记在 `textFile`）。上游的封面也按 `base_dir` 解析，catbus 的 `--cover` 是命令行参数，按当前目录。
    - `extract_tweet_id`（发布时生成的文章推文）：catbus 在 stderr 提示这条推文的链接，输出仍是文章的 `{id url}`。
  - 媒体上传：`x_apis/x_media_api.py` 的 `XMediaAPI.upload`（`with_metadata=False` 时不登记元数据，文章图片用）
  - 私信：`x_apis/x_dm_api.py` 的 `XChatAPI`：`get_initial_chat_page`（`msg list`）、`get_conversation_page`（`msg history`）、`get_users_by_ids`（`msg list` 补对方资料）
    - `get_initial_chat_page` 的 `max_local_sequence_id` / `message_pull_version` 是增量同步的水位（取某个序号之后的新消息事件），不是翻页游标。翻更早的会话要 `GetInboxPageRequestQuery`（`continue_cursor`），上游没有，所以 `msg list` 只取首页。
- **JS 资产**（账密登录不移植，Castle 与 ui_metrics 不复制）
  - `static/castle/`：`castle.js`、`castle.umd-BneRArir.js`、`env_core.js`、`rolldown-runtime-XXLRXQBO.js`、`run.js`、`castle_meta.json`、`chromium_zlib.meta.json`
  - `static/ui_metrics.js`
  - `static/graphql.json`（GraphQL 操作表）、`static/transaction_l1.json`
  - 调用这些 JS 的 Python：`utils/castle_token.py`、`utils/ui_metrics.py`