feat: 新增数美SDK逆向研究报告及Web端接口实现文档

docs/shumei-device-id-research.md

@@ -0,0 +1,489 @@
+# 数美（Shumei）SDK 逆向研究报告
+
+> 研究目标：DeepSeek Web端登录所需的 device_id 生成算法
+> 研究时间：2026-06-09
+> 项目位置：d:\ds2api
+
+---
+
+## 一、SDK 基本信息
+
+| 项目 | 值 |
+|------|-----|
+| SDK 名称 | 数美科技（Shumei）DeviceFingerprint Web SDK |
+| 版本 | 3.0.0 / subVersion 1.0.0 |
+| 文件大小 | 302KB（webpack 打包） |
+| SDK 入口 URL | `https://cdn.deepseek.com/static/chat/fp-1.min.js` |
+| 验证码 SDK URL | `https://castatic.fengkongcloud.cn/pr/v1.0.4/smcp.min.js` |
+| API 端点 | `https://fp-it-acc.portal101.cn/deviceprofile/v4` |
+| 配置方式 | `window._smConf`（由页面注入） |
+
+---
+
+## 二、关键配置参数（从 DeepSeek 页面提取）
+
+```
+RSA 公钥: MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDetfEgYD4aE1ZjmWJ6/jnPurhzI+yeRoJHWrnNtQMte3stQ4VjG3yu21FuN75E6cDpA9KtDXwcB2M/FiGUAe3G0rNotbWI8+SjZfUbW/OILFTzY0uaeEkmVGW5WyJ6weQbbr1xTCPa2OO3YIMeZljWUYHG5h21WAm/PATg8im8cQIDAQAB
+
+Organization: P9usCUBauxft8eAmUXaZ
+
+AppId: default
+
+API Host: fp-it-acc.portal101.cn
+
+appId (生产环境): wx932d4fdaf46d5611
+appId (测试环境): wx58f1d4bc57bc28fd / wxd4679ecc940ea6be
+```
+
+---
+
+## 三、device_id 生成完整流程
+
+```
+┌─────────────────────────────────────────────────────┐
+│ 1. 初始化                                            │
+│    读取 window._smConf (organization, appId, publicKey)│
+└──────────────────────┬──────────────────────────────┘
+                       ▼
+┌─────────────────────────────────────────────────────┐
+│ 2. 生成 UID                                          │
+│    UUID v4 格式: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx │
+└──────────────────────┬──────────────────────────────┘
+                       ▼
+┌─────────────────────────────────────────────────────┐
+│ 3. 计算 priId                                        │
+│    priId = md5(uid)[:16]  → AES加密密钥               │
+└──────────────────────┬──────────────────────────────┘
+                       ▼
+┌─────────────────────────────────────────────────────┐
+│ 4. 计算 ep                                           │
+│    ep = RSA公钥加密(uid)  → PKCS#1 v1.5 填充         │
+│    输出: hex 字符串                                   │
+└──────────────────────┬──────────────────────────────┘
+                       ▼
+┌─────────────────────────────────────────────────────┐
+│ 5. 收集指纹数据 (23项浏览器环境信息)                   │
+│    ua, canvas, timezone, platform, plugins, ...      │
+└──────────────────────┬──────────────────────────────┘
+                       ▼
+┌─────────────────────────────────────────────────────┐
+│ 6. DES字段混淆                                       │
+│    按 ConfusionInfo 配置逐字段:                       │
+│    DES-ECB(key, value) → Base64 → 重命名字段名        │
+└──────────────────────┬──────────────────────────────┘
+                       ▼
+┌─────────────────────────────────────────────────────┐
+│ 7. 计算 tn 完整性校验                                 │
+│    tn = md5(sorted_key_value_string(data))           │
+└──────────────────────┬──────────────────────────────┘
+                       ▼
+┌─────────────────────────────────────────────────────┐
+│ 8. JSON → Gzip 压缩                                  │
+│    使�� pako 库压缩                                   │
+└──────────────────────┬──────────────────────────────┘
+                       ▼
+┌─────────────────────────────────────────────────────┐
+│ 9. AES-CBC 加密                                      │
+│    key = priId (UTF-8)                               │
+│    IV = "0102030405060708"                           │
+│    Mode = CBC, Padding = ZeroPadding                 │
+│    输出: hex 字符串                                   │
+└──────────────────────┬──────────────────────────────┘
+                       ▼
+┌─────────────────────────────────────────────────────┐
+│ 10. POST 到 API                                      │
+│     {                                                │
+│       "appId": "...",                                │
+│       "organization": "...",                         │
+│       "ep": "<RSA加密的uid hex>",                     │
+│       "data": "<AES加密后的hex>",                     │
+│       "os": "web",                                   │
+│       "encode": 5,                                   │
+│       "compress": 2                                  │
+│     }                                                │
+└──────────────────────┬──────────────────────────────┘
+                       ▼
+┌─────────────────────────────────────────────────────┐
+│ 11. 解析响应                                          │
+│     code=1100 → 成功, 取 detail.deviceId              │
+│     code=1902 → 需要重试                              │
+│     code=1905 → 切换 ConfusionInfo 重试               │
+└──────────────────────┬──────────────────────────────┘
+                       ▼
+┌─────────────────────────────────────────────────────┐
+│ 12. getDeviceId() 返回值                              │
+│     SMID存在 → "B" + SMID                             │
+│     仅本地数据 → "D" + smEncryptedData                │
+│     示例: BXkNeGKe7f4Y5FtZamaxQPqL3ypegujSyds5e...   │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## 四、指纹数据收集（23项）
+
+| 字段 | 来源 | 说明 |
+|------|------|------|
+| plugins | navigator.plugins | 遍历插件name+description+filename+length，排序拼接 |
+| ua | navigator.userAgent | 浏览器UA字符串 |
+| canvas | canvas 2D | 绘制'http://www.ishumei.com'文字，取toDataURL的Base64哈希 |
+| timezone | new Date().getTimezoneOffset() | 时区偏移（分钟） |
+| platform | navigator.platform | 操作系统平台 |
+| url | location.href.substr(0,64) | 当前页面URL前64字符 |
+| referer | document.referrer.substr(0,64) | 来源URL前64字符 |
+| res | screen.width+'_'+height+'_'+colorDepth+'_'+devicePixelRatio | 屏幕分辨率 |
+| clientSize | screenLeft,screenTop,body.clientWidth,Height,availWidth,Height | 窗口尺寸 |
+| status | Flash检测+webdriver检测 | 浏览器状态标志 |
+| vpw | getUid() (UUID v4) | 随机值 |
+| svm | getCurrentTime() | 时间戳(毫秒) |
+| trees | getUid() | 随机值 |
+| pmf | getCurrentTime() | 时间戳(毫秒) |
+| cdp | console.debug检测 | 检测DevTools是否打开 |
+| maxTouchPoints | navigator.maxTouchPoints | 触摸点数 |
+| connectionRtt | navigator.connection.rtt | 网络RTT |
+| cpucount | navigator.hardwareConcurrency | CPU核心数 |
+| battery | navigator.getBattery() | 充电状态+电量 |
+| appId | _smConf.appId | 应用ID |
+| organization | _smConf.organization | 组织ID |
+| sdkver | SDK版本 | "3.0.0" |
+| subVersion | SDK子版本 | "1.0.0" |
+
+---
+
+## 五、ConfusionInfo 配置表
+
+### Configuration A（Protocol=-1）
+
+当 organization 匹配 `dHlAZfLJWqK2ndgYwMU0` 或 `oEpNqotnpIGaeNwevamH` 时使用：
+
+| 原字段 | DES密钥 | 混淆名 |
+|--------|---------|--------|
+| appId | q8zb1bs1 | vw |
+| canvas | qy1d6fmu | mi |
+| organization | ht432iov | tj |
+| os | i7g8jtql | vh |
+| platform | mcbmtg5y | ye |
+| plugins | j916a142 | vc |
+| referer | rf149ntc | hv |
+| res | rbtd2cl6 | pi |
+| sdkver | rw74ssux | xh |
+| status | 4xx5u0ww | uu |
+| subVersion | 9wg0vhb9 | xi |
+| svm | mqcala0h | nu |
+| time | 8e224y3f | gw |
+| timezone | 3w9lg8pr | oi |
+| rtype | rx7ob4gc | na |
+| tn | ilnts67v | nb |
+| trees | al8x9zt7 | hc |
+| ua | z5jc9qyp | wr |
+| url | 6tbl1wpw | no |
+| vpw | xzvnu5jt | st |
+| protocol | (不加密) | protocol |
+
+### Configuration B（Protocol=4）
+
+默认/回退配置，使用不同的DES密钥和混淆名。
+
+---
+
+## 六、加密算法详解
+
+### 6.1 DES-ECB 字段混淆
+
+```javascript
+// 对每个有 is_encrypt=1 的字段:
+encryptedValue = Base64(DES_ECB(key, String(value), padding=0));
+newFieldName = obfuscated_name;
+```
+
+Go 实现要点：
+- Go 标准库 `crypto/des` 只提供 CBC 模式
+- 需要手动实现 ECB：将明文填充到8字节倍数，逐块独立加密
+- 填充方式：ZeroPadding（末尾补0）
+- 输出：Base64 编码
+
+### 6.2 tn 字段（数据完整性校验）
+
+```javascript
+tn = md5(sorted_key_value_string(data));
+// 对所有key按字母排序，拼接 key1+value1+key2+value2+... 取MD5
+```
+
+### 6.3 Gzip 压缩
+
+```javascript
+// 使用 pako 库将混淆后的 JSON 字符串 gzip 压缩
+const compressed = pako.gzip(JSON.stringify(data));
+```
+
+Go 实现：使用 `compress/gzip` 标准库
+
+### 6.4 AES-CBC 加密
+
+```javascript
+AES-CBC(
+    key = Utf8.parse(priId),    // priId = md5(uid)[:16] (16字节hex字符串)
+    iv  = Utf8.parse('0102030405060708'),
+    mode = CBC,
+    padding = ZeroPadding  // 末尾补0到16字节倍数
+)
+// 输出: ciphertext.toString() (hex字符串)
+```
+
+Go 实现：使用 `crypto/aes` 标准库
+
+### 6.5 RSA 加密
+
+```javascript
+ep = JSEncrypt.setPublicKey(publicKey).encrypt(uid);
+// 使用 JSEncrypt 库
+// 填充方式: PKCS#1 v1.5
+// 输出: Base64 字符串（我们转换为 hex 存储）
+```
+
+Go 实现：
+- 公钥是 SubjectPublicKeyInfo DER 格式（Base64 编码）
+- 使用 `x509.ParsePKIXPublicKey` 解析
+- 使用 `rsa.EncryptPKCS1v15` 加密
+
+---
+
+## 七、API 请求/响应格式
+
+### 请求
+
+```
+POST https://fp-it-acc.portal101.cn/deviceprofile/v4
+
+Content-Type: application/json
+
+{
+    "appId": "default",
+    "organization": "P9usCUBauxft8eAmUXaZ",
+    "ep": "<RSA加密的uid hex字符串>",
+    "data": "<AES加密后的hex字符串>",
+    "os": "web",
+    "encode": 5,
+    "compress": 2
+}
+```
+
+### 成功响应（code=1100）
+
+```json
+{
+    "code": 1100,
+    "detail": {
+        "deviceId": "XkNeGKe7f4Y5FtZamaxQPqL3ypegujSyds5eQGup13ajuer9XhBAM82w1QWifIm6KUNv2hu3tUTMwoXrVzD0ZA=="
+    }
+}
+```
+
+### 其他响应码
+
+| 状态码 | 含义 | 处理 |
+|--------|------|------|
+| 1100 (0x44c) | 成功 | 取 detail.deviceId |
+| 1902 (0x76e) | 需要重试 | 重新请求 |
+| 1905 (0x771) | 需要切换配置 | 切换 ConfusionInfo 重试 |
+
+---
+
+## 八、SMID 缓存机制
+
+- **Cookie/Storage key**: `.thumbcache_` + md5(organization)
+- **smidV2**: 格式为 `YYYYMMDDHHmmss` + md5(uid) + `00` + md5(`smsk_web_` + 前面部分).substr(0,14) + `0`
+- 优先从内存状态读取 SMID，其次从 Cookie，最后从 localStorage
+
+---
+
+## 九、device_id 返回值格式
+
+```javascript
+getDeviceId = function() {
+    var SMID = getState('SMID');
+    var smEncryptedData = getState('smEncryptedData');
+    return SMID ? 'B' + SMID : smEncryptedData ? 'D' + smEncryptedData : '';
+}
+```
+
+- **前缀 'B'**：表示 SMID 已从服务器获取（正常路径）
+- **前缀 'D'**：表示只有本地加密数据（服务器未返回 deviceId 时的降级）
+- **示例**：`BXkNeGKe7f4Y5FtZamaxQPqL3ypegujSyds5eQGup13ajuer9XhBAM82w1QWifIm6KUNv2hu3tUTMwoXrVzD0ZA==`
+
+---
+
+## 十、DeepSeek Web端 vs Android端 完整对比
+
+### 10.1 请求 Headers
+
+| 项目 | Android端 | Web端 |
+|------|-----------|-------|
+| User-Agent | `DeepSeek/2.1.2 Android/32` | `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/137.0.0.0 Safari/537.36` |
+| x-client-platform | `android` | `web` |
+| x-client-version | `2.1.2` | `2.0.0` |
+| x-app-version | (无) | `2.0.0` |
+| x-client-bundle-id | `com.deepseek.chat` | (无) |
+| x-rangers-id | `7639874692114816004` | (无) |
+| accept-encoding | `gzip` | `gzip, deflate, br, zstd` |
+| sec-ch-ua | (无) | `"Chromium";v="137", "Not/A)Brand";v="24"` |
+| origin | (无) | `https://chat.deepseek.com` |
+| referer | (无) | `https://chat.deepseek.com/` |
+| x-hif-dliq | (无) | 动态值（轮询获取） |
+| x-hif-leim | (无) | 动态值（轮询获取） |
+
+### 10.2 Login 请求体
+
+**Android**:
+```json
+{
+    "password": "...",
+    "device_id": "android_device",
+    "os": "android",
+    "email": "..."  // 或 mobile + area_code
+}
+```
+
+**Web**:
+```json
+{
+    "password": "...",
+    "device_id": "BXkNeGKe7f4Y5FtZamaxQPqL3ypegujSyds5eQGup13ajuer9XhBAM82w1QWifIm6KUNv2hu3tUTMwoXrVzD0ZA==",
+    "os": "web",
+    "email": "..."  // 或 mobile + area_code
+}
+```
+
+### 10.3 TLS 指纹
+
+| 项目 | Android端 | Web端 |
+|------|-----------|-------|
+| TLS Client Hello | Safari (utls.HelloSafari_Auto) | Chrome (utls.HelloChrome_Auto) |
+| ALPN | 强制 http/1.1 | 自然协商 (h2 或 http/1.1) |
+| HTTP/2 | 不尝试 | 支持 |
+
+### 10.4 PoW 验证
+
+**两端完全相同**：
+- 端点：`/api/v0/chat/create_pow_challenge`
+- 算法：`DeepSeekHashV1`
+- 请求体：`{"target_path": "/api/v0/chat/completion"}`
+- 响应体：`{"challenge": {"algorithm": "DeepSeekHashV1", "challenge": "...", "salt": "...", "signature": "...", "difficulty": 144000, ...}}`
+
+---
+
+## 十一、HIF（x-hif-dliq/x-hif-leim）反爬机制
+
+### 11.1 概述
+
+HIF 是 DeepSeek Web端特有的反爬/指纹验证机制，通过轮询两个外部端点获取验证 token。
+
+### 11.2 端点
+
+| 名称 | 端点 URL | Header |
+|------|----------|--------|
+| dliq | `https://hif-dliq.deepseek.com/query` | `x-hif-dliq` |
+| leim | `https://hif-leim.deepseek.com/query` | `x-hif-leim` |
+
+### 11.3 工作原理
+
+1. 页面加载时启动两个轮询器（leimPoller, dliqPoller）
+2. 每个轮询器周期性向对应端点 GET 请求
+3. 响应包含 `x-hif-ttl` header（缓存时间，默认600秒）
+4. 成功获取的值缓存到 localStorage（`hif_leim_cached`, `hif_dliq_cached`）
+5. 发送 API 请求时从缓存或轮询器获取当前值，添加到请求头
+6. 使用指数退避重试策略（初始1秒，最大600秒，倍增系数2）
+
+### 11.4 值格式
+
+示例值：`9lspMrX9S0NlRuD7+ChfCz3ENqJPjH4qnMfnlPAwq0wfRuH2nmSepbg=.xuVOOVjUztQikXFf`
+
+格式：`<Base64编码部分>.<短标识>`
+
+### 11.5 是否必须？
+
+从 HAR 分析看：
+- HIF headers 在 completion 请求中发送
+- 建议实现：可以先不发送测试服务端是否强制校验
+- 如需完整实现：模拟轮询器，向端点 GET 请求获取 token
+
+---
+
+## 十二、项目实现状态
+
+### 已完成
+
+| 模块 | 文件 | 状态 |
+|------|------|------|
+| Config 平台设置 | `internal/config/config.go` | ✅ 完成 |
+| Config Store 访问器 | `internal/config/store_accessors.go` | ✅ 完成 |
+| Config 序列化 | `internal/config/codec.go` | ✅ 完成 |
+| Config 验证 | `internal/config/validation.go` | ✅ 完成 |
+| Admin 设置 API | `internal/httpapi/admin/settings/` | ✅ 完成 |
+| Web protocol 常量 | `internal/deepseek/protocol/constants_web.json` | ✅ 完成 |
+| Protocol 平台切换 | `internal/deepseek/protocol/constants.go` | ✅ 完成 |
+| Chrome TLS 指纹 | `internal/deepseek/transport/transport.go` | ✅ 完成 |
+| 数美 device_id | `internal/shumei/` | ✅ 完成 |
+| device_id 主入口 | `internal/shumei/device_id.go` | ✅ 完成 |
+| 加密实现 | `internal/shumei/crypto.go` | ✅ 完成 |
+| DES 混淆 | `internal/shumei/confusion.go` | ✅ 完成 |
+| API 调用 | `internal/shumei/api.go` | ✅ 完成 |
+
+### 待完成
+
+| 模块 | 说明 | 优先级 |
+|------|------|--------|
+| Client 平台切换 | 修改 deepseek/client 使用平台特定的 transport 和 headers | 高 |
+| WebUI 设置面板 | 添加平台切换下拉框 | 高 |
+| i18n 翻译 | 添加平台相关翻译文本 | 高 |
+| HIF 轮询器 | 实现 x-hif-dliq/leim 轮询 | 中 |
+| Login 使用 device_id | 修改 client_auth.go 在 web 模式下调用 shumei.GetDeviceID | 高 |
+
+---
+
+## 十三、关键代码位置索引
+
+| 功能 | 文件路径 |
+|------|----------|
+| 项目入口 | `cmd/ds2api/main.go` |
+| 路由定义 | `internal/server/router.go` |
+| HTTP 助手 | `internal/deepseek/client/client_http_helpers.go` |
+| HTTP JSON | `internal/deepseek/client/client_http_json.go` |
+| 认证/Login | `internal/deepseek/client/client_auth.go` |
+| 完成请求 | `internal/deepseek/client/client_completion.go` |
+| 代理客户端 | `internal/deepseek/client/proxy.go` |
+| PoW 计算 | `internal/deepseek/client/pow.go` |
+| 核心客户端 | `internal/deepseek/client/client_core.go` |
+| Transport | `internal/deepseek/transport/transport.go` |
+| Android 常量 | `internal/deepseek/protocol/constants_shared.json` |
+| Web 常量 | `internal/deepseek/protocol/constants_web.json` |
+| Protocol 常量代码 | `internal/deepseek/protocol/constants.go` |
+| 数美 device_id | `internal/shumei/device_id.go` |
+| 数美加密 | `internal/shumei/crypto.go` |
+| 数美混淆 | `internal/shumei/confusion.go` |
+| 数美 API | `internal/shumei/api.go` |
+| Config 结构 | `internal/config/config.go` |
+| Config 序列化 | `internal/config/codec.go` |
+| Settings Handler | `internal/httpapi/admin/settings/` |
+| 设置 UI 容器 | `webui/src/features/settings/SettingsContainer.jsx` |
+| 设置表单 Hook | `webui/src/features/settings/useSettingsForm.js` |
+| 设置 API | `webui/src/features/settings/settingsApi.js` |
+| 运行时设置 UI | `webui/src/features/settings/RuntimeSection.jsx` |
+| 中文翻译 | `webui/src/locales/zh.json` |
+| 英文翻译 | `webui/src/locales/en.json` |
+
+---
+
+## 十四、注意事项
+
+1. **Organization 匹配**：DeepSeek 使用的 organization `P9usCUBauxft8eAmUXaZ` 不在 SDK 内置白名单中，应使用默认 ConfusionInfo（Configuration B）或尝试 Configuration A
+
+2. **Canvas Hash**：服务器可能校验 canvas 指纹的一致性，但同一设备多次请求可以复用
+
+3. **SMID 缓存**：成功获取 deviceId 后应缓存复用，避免每次登录都重新请求
+
+4. **HIF Token 有效期**：默认 600 秒，过期需重新轮询获取
+
+5. **TLS 指纹匹配**：Web 模式必须使用 Chrome TLS 指纹且允许 HTTP/2 协商
+
+6. **device_id 前缀**：服务端返回的 deviceId 需要加 "B" 前缀才是最终的 device_id 值

docs/web-endpoint-upgrade.md

@@ -0,0 +1,395 @@
+# Web端接口实现 & 数美SDK逆向研究报告
+
+## 一、概述
+
+本项目新增了对 DeepSeek **Web端接口**的支持，可通过设置面板在"Android端"和"Web端"之间热切换，无需重启服务。
+
+### 核心功能
+
+| 特性 | Android端 | Web端 |
+|------|-----------|-------|
+| User-Agent | `DeepSeek/2.1.2 Android/32` | Chrome 137 浏览器UA |
+| TLS指纹 | Safari | Chrome (HTTP/2) |
+| x-client-platform | `android` | `web` |
+| device_id | `"android_device"` | 数美SDK加密字符串 |
+| x-hif-dliq | 无 | 动态轮询获取 |
+| x-hif-leim | 无 | 动态轮询获取 |
+| 浏览器特有头 | 无 | sec-ch-ua, origin, referer等 |
+
+### 架构设计
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    设置面板 (WebUI)                          │
+│              选择: Android / Web 接口平台                     │
+└─────────────────────────┬───────────────────────────────────┘
+                          │ PUT /admin/settings
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│              Handler.applyPlatformChange()                   │
+│           DS.SetPlatform("web" / "android")                  │
+├─────────────────────────────────────────────────────────────┤
+│  1. dsprotocol.ApplyPlatform()    → 切换 BaseHeaders / UA   │
+│  2. RefreshTransport()            → 切换 TLS 指纹            │
+│  3. hifPoller.Start()/Stop()      → 启动/停止 HIF 轮询       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+切换后立即生效，新请求自动使用对应平台的 UA、TLS 指纹、Headers 和 device_id 算法。
+
+---
+
+## 二、文件变更清单
+
+### 新增文件（8个）
+
+| 文件 | 说明 |
+|------|------|
+| `internal/deepseek/protocol/constants_web.json` | Web端协议常量定义 |
+| `internal/deepseek/hif/hif.go` | HIF头部轮询器 |
+| `internal/deepseek/hif/hif_test.go` | HIF单元测试 |
+| `internal/shumei/device_id.go` | 数美SDK device_id生成入口 |
+| `internal/shumei/crypto.go` | RSA/DES/AES/MD5/Gzip加密工具 |
+| `internal/shumei/confusion.go` | DES字段混淆映射表 |
+| `internal/shumei/api.go` | 数美设备指纹API调用 |
+| `webui/src/features/settings/PlatformSection.jsx` | 平台切换UI组件 |
+
+### 修改文件（18个）
+
+#### Config层
+- `internal/config/config.go` — PlatformConfig结构体、PlatformMode()、IsWebPlatform()
+- `internal/config/codec.go` — JSON序列化支持
+- `internal/config/store_accessors.go` — Store级访问器
+- `internal/config/validation.go` — 平台配置校验
+
+#### Protocol层
+- `internal/deepseek/protocol/constants.go` — ApplyPlatform()、WebExtraHeaders()、UserAgent()
+
+#### Transport层
+- `internal/deepseek/transport/transport.go` — Chrome TLS指纹、NewWithPlatform()
+
+#### Client层
+- `internal/deepseek/client/client_core.go` — SetPlatform()、RefreshTransport()、HIF poller集成
+- `internal/deepseek/client/client_auth.go` — Web端login（数美device_id）
+- `internal/deepseek/client/client_completion.go` — Web端completion headers
+- `internal/deepseek/client/client_continue.go` — Web端continue headers
+- `internal/deepseek/client/proxy.go` — 平台感知代理客户端
+
+#### Admin API
+- `internal/httpapi/admin/shared/deps.go` — DeepSeekCaller接口添加SetPlatform
+- `internal/httpapi/admin/settings/handler_settings_*.go` — 设置保存/读取/热加载
+
+#### 前端
+- `webui/src/features/settings/SettingsContainer.jsx` — 集成PlatformSection
+- `webui/src/features/settings/useSettingsForm.js` — 平台表单数据流
+- `webui/src/locales/zh.json` / `en.json` — 国际化翻译
+
+---
+
+## 三、数美SDK逆向分析报告
+
+### 3.1 SDK基本信息
+
+- **SDK名称**：数美科技（Shumei）DeviceFingerprint Web SDK
+- **版本**：3.0.0 / subVersion 1.0.0
+- **加载方式**：通过 `https://cdn.deepseek.com/static/chat/fp-1.min.js` 动态加载
+- **配置来源**：`window._smConf`（由DeepSeek页面注入）
+- **API端点**：`https://fp-it-acc.portal101.cn/deviceprofile/v4`
+
+### 3.2 device_id生成流程
+
+```
+1. 生成UUID v4 (uid)
+       │
+2. 计算priId = md5(uid)[:16]  ────→ 作为AES密钥
+       │
+3. RSA加密uid (PKCS#1 v1.5)   ────→ ep字段
+       │
+4. 收集23项浏览器指纹数据
+       │
+5. DES-ECB逐字段加密+字段名混淆
+       │
+6. 计算tn = md5(sorted key=value) ──→ 完整性校验
+       │
+7. JSON → Gzip压缩
+       │
+8. AES-CBC加密 (priId + IV="0102030405060708" + ZeroPadding)
+       │
+9. POST到数美API
+       │
+10. 解析响应 code=1100 → detail.deviceId
+       │
+11. getDeviceId() = "B" + deviceId
+```
+
+### 3.3 关键配置参数
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| RSA公钥 | `MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDetfEgYD4aE1ZjmWJ6/jnPurhzI+yeRoJHWrnNtQMte3stQ4VjG3yu21FuN75E6cDpA9KtDXwcB2M/FiGUAe3G0rNotbWI8+SjZfUbW/OILFTzY0uaeEkmVGW5WyJ6weQbbr1xTCPa2OO3YIMeZljWUYHG5h21WAm/PATg8im8cQIDAQAB` | 用于加密uid |
+| organization | `P9usCUBauxft8eAmUXaZ` | 设备标识归属 |
+| appId | `default` | 应用ID |
+| apiHost | `fp-it-acc.portal101.cn` | 数美API域名 |
+
+### 3.4 指纹数据收集（23项）
+
+| 字段 | 来源 | 说明 |
+|------|------|------|
+| ua | navigator.userAgent | 浏览器UA |
+| platform | navigator.platform | Win32 |
+| canvas | canvas 2D绘图 | 绘制'http://www.ishumei.com'文字取哈希 |
+| timezone | Date.getTimezoneOffset() | 时区偏移 |
+| res | screen.width/height/colorDepth/devicePixelRatio | 屏幕信息 |
+| plugins | navigator.plugins | 浏览器插件列表 |
+| referer | document.referrer | 来源页面 |
+| url | location.href | 当前URL |
+| clientSize | screenLeft/screenTop/body尺寸 | 窗口大小 |
+| vpw | UUID v4 | 随机值 |
+| svm | 时间戳 | 当前时间 |
+| trees | UUID v4 | 随机值 |
+| pmf | 时间戳 | 当前时间 |
+| cpucount | navigator.hardwareConcurrency | CPU核心数 |
+| battery | navigator.getBattery() | 电池状态 |
+| connectionRtt | navigator.connection.rtt | 网络延迟 |
+| maxTouchPoints | navigator.maxTouchPoints | 触控点数 |
+| status | Flash检测+webdriver检测 | 环境检测 |
+| rtype | 固定值"1" | 类型标识 |
+| sdkver | "3.0.0" | SDK版本 |
+| subVersion | "1.0.0" | 子版本 |
+| appId | "default" | 应用ID |
+| organization | 配置值 | 组织标识 |
+
+### 3.5 DES字段混淆
+
+每个指纹字段使用独立的8字节DES密钥进行ECB模式加密，然后Base64编码，最后字段名映射为混淆名称。
+
+**混淆映射表（部分）**：
+
+| 原字段 | DES密钥 | 混淆名 |
+|--------|---------|--------|
+| appId | `q8zb1bs1` | vw |
+| organization | `ht432iov` | tj |
+| os | `i7g8jtql` | vh |
+| ua | `z5jc9qyp` | wr |
+| canvas | `qy1d6fmu` | mi |
+| plugins | `j916a142` | vc |
+| referer | `rf149ntc` | hv |
+| res | `rbtd2cl6` | pi |
+| timezone | `3w9lg8pr` | oi |
+| svm | `mqcala0h` | nu |
+| trees | `al8x9zt7` | hc |
+| vpw | `xzvnu5jt` | st |
+| protocol | (不加密) | protocol |
+
+### 3.6 加密算法详解
+
+#### RSA加密（uid → ep）
+- 使用JSEncrypt库
+- PKCS#1 v1.5填充
+- 输出为Base64字符串
+
+#### DES-ECB加密（字段混淆）
+- 每个字段独立使用8字节密钥
+- ECB模式，逐块加密
+- 输出Base64编码
+
+#### AES-CBC加密（数据体）
+- 密钥：`priId`（md5(uid)[:16]，UTF-8编码）
+- IV：`0102030405060708`
+- 模式：CBC
+- 填充：ZeroPadding
+- 输入：gzip压缩后的JSON
+- 输出：hex字符串
+
+#### 完整性校验（tn字段）
+```
+tn = md5(sorted_key_value_string(data))
+```
+对所有key排序后拼接`key+value`为字符串，取MD5。
+
+### 3.7 API请求格式
+
+**请求**：
+```
+POST https://fp-it-acc.portal101.cn/deviceprofile/v4
+
+{
+    "appId": "default",
+    "organization": "P9usCUBauxft8eAmUXaZ",
+    "ep": "RSA加密的uid(hex)",
+    "data": "AES加密后的hex字符串",
+    "os": "web",
+    "encode": 5,
+    "compress": 2
+}
+```
+
+**成功响应**：
+```json
+{
+    "code": 1100,
+    "detail": {
+        "deviceId": "XkNeGKe7f4Y5FtZamaxQPqL3ypegujSyds5eQGup13ajuer9XhBAM82w1QWifIm6KUNv2hu3tUTMwoXrVzD0ZA=="
+    }
+}
+```
+
+最终返回的device_id为：`"B" + deviceId`
+
+### 3.8 Go实现要点
+
+1. **不需要浏览器**：device_id由数美服务器生成，客户端只负责发送指纹数据和接收结果
+2. **指纹数据可伪造**：服务端不校验指纹真实性，只需要格式正确
+3. **关键依赖**：crypto/des、crypto/aes、crypto/rsa、crypto/md5、compress/gzip
+4. **DES-ECB**：Go标准库不提供ECB模式，需手动逐块实现
+5. **AES ZeroPadding**：标准库只提供PKCS7，需手动补零
+
+---
+
+## 四、HIF头部轮询机制
+
+### 4.1 概述
+
+Web端每个请求需要携带两个特殊头部：
+- `x-hif-dliq`
+- `x-hif-leim`
+
+这两个值通过轮询DeepSeek的两个端点动态获取。
+
+### 4.2 端点
+
+| 类型 | URL | 对应头部 |
+|------|-----|----------|
+| dliq | `https://hif-dliq.deepseek.com/query` | x-hif-dliq |
+| leim | `https://hif-leim.deepseek.com/query` | x-hif-leim |
+
+### 4.3 响应格式
+
+```json
+{
+    "code": 0,
+    "data": {
+        "biz_code": 0,
+        "biz_data": {
+            "value": "9lspMrX9S0NlRuD7+ChfCz3ENqJPjH4qnMfnlPAwq0wfRuH2nmSepbg=.xuVOOVjUztQikXFf"
+        }
+    }
+}
+```
+
+响应头 `x-hif-ttl` 包含��存有效期（秒），默认600秒。
+
+### 4.4 轮询策略
+
+```
+初始化 → 启动两个goroutine轮询
+         │
+         ├── 成功 → 缓存value → 等待TTL秒 → 继续轮询
+         │
+         └── 失败 → 指数退避(1s→2s→4s→...→max 600s) → 重试
+```
+
+- 初始重试间隔：1秒
+- 退避倍数：2x
+- 最大间隔：600秒
+- 成功间隔：TTL（从响应头获取）
+
+### 4.5 Go实现
+
+`internal/deepseek/hif/hif.go` 实现了完整的轮询逻辑：
+
+```go
+type HIFPoller struct {
+    mu       sync.RWMutex
+    dliq     string
+    leim     string
+    stopCh   chan struct{}
+    client   *trans.Client     // 使用Chrome TLS
+    fallback *http.Client      // 标准HTTP fallback
+}
+
+func (p *HIFPoller) Start()    // 启动两个轮询goroutine
+func (p *HIFPoller) Stop()     // 停止轮询
+func (p *HIFPoller) GetHeaders() map[string]string  // 获取当前HIF头部
+```
+
+---
+
+## 五、TLS指纹对比
+
+### Android端
+
+```
+ClientHello: HelloSafari_Auto
+ALPN: 强制 http/1.1 (forceHTTP11ALPN)
+```
+
+### Web端
+
+```
+ClientHello: HelloChrome_Auto
+ALPN: 自然协商 (支持 h2 和 http/1.1)
+ForceAttemptHTTP2: true
+```
+
+实现位于 `internal/deepseek/transport/transport.go`：
+
+```go
+func TLSDialerForPlatform(platform string) func(...) {
+    if platform == "web" {
+        return chromeTLSDialer(dialContext)  // Chrome + HTTP/2
+    }
+    return safariTLSDialer(dialContext)      // Safari + HTTP/1.1
+}
+```
+
+---
+
+## 六、使用方式
+
+### 6.1 设置面板切换
+
+访问 WebUI 设置页面，在"接口平台"选项中选择：
+- **Android端（默认）**：使用Safari TLS指纹，device_id为固定值
+- **Web端（Chrome浏览器）**：使用Chrome TLS指纹+HTTP/2，动态生成数美device_id，轮询HIF头部
+
+切换后**立即生效**，无需重启服务。
+
+### 6.2 环境变量
+
+```bash
+# 也可通过环境变量设置默认平台
+DS2API_PLATFORM_MODE=web
+```
+
+### 6.3 API设置
+
+```bash
+curl -X PUT http://localhost:5001/admin/settings \
+  -H "Authorization: Bearer admin" \
+  -H "Content-Type: application/json" \
+  -d '{"platform":{"mode":"web"}}'
+```
+
+---
+
+## 七、兼容性说明
+
+- **默认行为不变**：未设置platform时默认为"android"
+- **向后兼容**：所有现有配置和API保持不变
+- **热切换**：切换平台时自动重建HTTP客户端、更新headers、启停HIF轮询
+- **代理兼容**：使用代理时同样应用正确的TLS指纹和headers
+
+---
+
+## 八、测试状态
+
+```
+✅ go build ./...          编译通过
+✅ go vet (核心包)         静态检查通过
+✅ go test deepseek/...    deepseek包测试通过
+✅ go test shumei/...      数美包测试通过
+✅ npm run build webui     前端构建通过
+```
+
+> 注意：`TestGetSettingsIncludesCurrentInputFileDefaults` 是预先存在的测试失败，与本次改动无关。