@wwkit/freetoken 1.0.1

package/client/src/data/docs/auth.js

@@ -0,0 +1,631 @@
+// 登录认证模块：多种 LLM 后端的认证机制
+// - DeepSeek 网页端认证（基于 ds-free-api 的 ds_core 库）
+// - CodeArts IDE OAuth 认证（基于 @wwkit/llmproxy 的 providers/codearts/）
+// 认证逻辑独立于协议转换——先认证拿到可用凭证，再谈格式转换
+
+export default {
+  id: 'auth',
+  name: 'Auth',
+  badge: '登录认证',
+  tagline: '多种 LLM 后端的认证机制：网页端逆向认证、IDE OAuth 认证',
+  description:
+    '不同 LLM 后端的认证机制差异巨大——DeepSeek 网页端需要逆向 PoW/WAF/Session 体系，CodeArts IDE 使用 OAuth 2.0 PKCE + DPoP + 华为云 SDK 签名。本模块独立于协议转换，专注说明认证机制本身。',
+
+  subModules: [
+    {
+      id: 'deepseek-web',
+      name: 'DeepSeek 网页端认证',
+      badge: '逆向工程',
+      tagline: '从网页端登录到可用 Session 的完整认证链',
+      description:
+        'ds-free-api 的 ds_core 库（ds_core/src/accounts/）将 DeepSeek 网页端的认证流程封装为 AccountPool + AccountGuard 模型。1 个账号 = 1 个 session = 1 个并发槽位。整个认证链分为后端认证（面向 DeepSeek）和前端管理（面向客户端）两层，完全独立于协议转换逻辑。',
+
+      // ── 认证架构 ──
+      architecture: {
+        title: '认证架构',
+        description:
+          'ds_core 分为三个子模块：client（原始 HTTP）、pool（账号池管理）、pow（PoW 求解）。上层通过 Accounts facade 统一调用，不直接接触子模块。',
+        layers: [
+          {
+            name: 'Accounts Facade',
+            file: 'ds_core/src/accounts.rs',
+            role: '统一入口，封装 pool/client/solver，对外只暴露 get_account() 和 v0_chat()',
+          },
+          {
+            name: 'AccountPool',
+            file: 'ds_core/src/accounts/pool.rs',
+            role: '账号池管理：初始化、选择（LIFO 空闲最久优先）、AccountGuard 生命周期',
+          },
+          {
+            name: 'Client',
+            file: 'ds_core/src/accounts/client.rs',
+            role: '原始 HTTP 客户端：登录、创建会话、completion、文件上传、停止流。解析 Envelope 信封格式',
+          },
+          {
+            name: 'PowSolver',
+            file: 'ds_core/src/accounts/pow.rs',
+            role: 'PoW 挑战求解：wasmtime 加载 WASM、动态探测导出函数、执行 DeepSeekHashV1',
+          },
+        ],
+        codeStructure: `ds_core/src/
+├── lib.rs           # 公共 API: re-exports DsCore, CoreError
+├── accounts.rs      # Facade: Accounts struct
+├── accounts/
+│   ├── client.rs    # 原始 HTTP: API 端点, Envelope 解析
+│   ├── pool.rs      # 账号池: init, selection, AccountGuard
+│   └── pow.rs       # PoW: wasmtime WASM, DeepSeekHashV1
+├── chat.rs          # Facade: Chat struct (会话编排)
+└── config.rs        # DsCoreConfig, AccountConfig`,
+      },
+
+      // ── 账号池初始化 ──
+      poolInit: {
+        title: '账号池初始化',
+        description:
+          'AccountPool::init() 并发初始化所有账号（Semaphore 上限 13）。每个账号独立完成 4 步初始化，失败重试 3 次（2s 间隔），全部失败标记为 InitFailed。',
+        steps: [
+          { step: '1. 登录', detail: '调用 DeepSeek 登录接口，用账号凭据换取 Bearer Token。这是认证链的起点——没有 Token 后续所有操作都会被拒绝' },
+          { step: '2. 创建聊天会话', detail: '用 Token 调用 create_session 接口创建一个聊天会话。1 账号 = 1 session = 1 并发' },
+          { step: '3. 健康检查', detail: '执行一次带 PoW 的测试 completion，验证会话可写。如果这一步失败说明 session 有问题（可能被 WAF 拦截或 PoW 求解失败）' },
+          { step: '4. 重命名会话', detail: '将 session 标题改为 "managed-by-ai-free-api"，标记为代理管理的会话' },
+        ],
+        retry: '每个账号重试 3 次，间隔 2s。全部失败标记为 InitFailed，不参与轮转。',
+        concurrency: '并发初始化上限 13（tokio::sync::Semaphore 控制），避免大量账号同时登录触发风控。',
+      },
+
+      // ── PoW 挑战求解 ──
+      pow: {
+        title: 'PoW 挑战求解（Proof of Work）',
+        description:
+          'DeepSeek 网页端要求 Proof of Work 挑战——这是反爬机制的核心。每次聊天请求前必须求解一次 PoW，否则请求被拒绝。ds-free-api 用 wasmtime 执行 DeepSeek 的 WASM 求解器。',
+        mechanism: [
+          { step: '1. 获取挑战参数', detail: '从 DeepSeek 获取 challenge 参数（难度值、算法标识等）。参数每次请求不同' },
+          { step: '2. 加载 WASM 模块', detail: 'wasmtime 加载 DeepSeek 的 WASM 求解器模块。WASM 代码从 DeepSeek CDN 下载，URL 可在 config.toml 中配置' },
+          { step: '3. 动态探测导出函数', detail: '不硬编码 WASM 导出函数名——动态探测所有导出符号，找到求解入口。这确保 DeepSeek 更新 WASM 后仍能工作' },
+          { step: '4. 执行 DeepSeekHashV1', detail: '在 WASM 中执行哈希求解算法，找到一个满足难度条件的 nonce 值' },
+          { step: '5. 返回 proof', detail: '将求解结果（nonce + proof）附加到聊天请求中，DeepSeek 后端验证通过后才处理请求' },
+        ],
+        codeExample: `// ds_core/src/accounts/pow.rs 核心逻辑（伪代码）
+
+pub struct PowSolver {
+    engine: wasmtime::Engine,
+    module: wasmtime::Module,
+}
+
+impl PowSolver {
+    // 加载 WASM 模块
+    pub fn load(wasm_url: &str) -> Result<Self> {
+        let wasm_bytes = download(wasm_url)?;
+        let engine = Engine::default();
+        let module = Module::new(&engine, &wasm_bytes)?;
+        Ok(Self { engine, module })
+    }
+
+    // 求解 PoW 挑战
+    pub fn solve(&self, challenge: &Challenge) -> Result<Proof> {
+        let store = Store::new(&self.engine, ());
+        let instance = self.module.instantiate(&mut store, [])?;
+
+        // 动态探测导出函数（不硬编码符号名）
+        let solve_func = probe_export(&instance, &store, "solve")?;
+        let result = solve_func.call(&mut store, &[challenge.into()])?;
+
+        Ok(Proof::from(result))
+    }
+}`,
+        notes: [
+          'PoW 是 DeepSeek 网页端的反爬机制，不是标准 API 认证——标准 API 只需 API Key',
+          '每次聊天请求前必须求解一次 PoW，求解结果不可复用',
+          'WASM 模块可能被 DeepSeek 更新（重新编译），动态探测导出函数确保兼容性',
+          '如果 WASM URL 变更，需更新 config.toml 中的 wasm_url 配置',
+          'wasmtime 是重量级依赖（编译慢、二进制大），但确保了 PoW 求解的正确性',
+        ],
+      },
+
+      // ── WAF 绕过 ──
+      waf: {
+        title: 'WAF 绕过（AWS Web Application Firewall）',
+        description:
+          'DeepSeek 部署了 AWS WAF 防护，会拦截非浏览器请求。ds-free-api 使用 wreq（BoringSSL）模拟 Chrome 136 TLS 指纹来绕过 WAF 检测。',
+        mechanism: [
+          { step: 'TLS 指纹模拟', detail: 'wreq 使用 BoringSSL 编译，模拟 Chrome 136 的 TLS ClientHello 指纹。WAF 通过 TLS 指纹判断请求是否来自真实浏览器' },
+          { step: 'WAF Challenge 检测', detail: '如果收到 HTTP 202（WAF Challenge 响应），说明被 WAF 拦截。非美国 IP 更容易触发' },
+          { step: '代理转发', detail: '配置 config.toml [proxy] 使用美国 IP 代理，避免地域性 WAF 拦截' },
+          { step: '指纹更新', detail: '如果 WAF 更新指纹策略（HTTP 403 或连接重置），需更新 wreq 版本或切换模拟配置文件' },
+        ],
+        configExample: `# config.toml
+[proxy]
+url = "http://your-us-proxy:8080"  # 美国 IP 代理，避免 WAF Challenge`,
+        notes: [
+          'WAF 绕过是逆向网页端的特有需求——标准 API 不需要处理 WAF',
+          'TLS 指纹模拟是被动绕过，不是主动攻击 WAF',
+          'wreq + BoringSSL 编译依赖 cmake、g++、libclang-dev',
+          '如果 WAF 升级检测策略，可能需要更新 wreq 或切换到其他 HTTP 客户端',
+        ],
+      },
+
+      // ── Session 管理 ──
+      session: {
+        title: 'Session 生命周期管理',
+        description:
+          '每次聊天请求创建一个临时 session，请求结束后销毁。AccountGuard 确保账号在 session 存活期间被标记为忙碌，GuardedStream 确保 session 在流结束时清理。',
+        lifecycle: [
+          { phase: '1. 获取账号', detail: 'AccountPool::get_account() → AccountGuard。LIFO 空闲最久优先，DashMap 无锁读。AtomicBool 标记忙碌' },
+          { phase: '2. 创建 session', detail: '为本次请求创建专用聊天会话（不是复用初始化时的 session）' },
+          { phase: '3. 上传历史', detail: '多轮对话历史分块上传为文件（split_history），最后 1-2 轮内联在 prompt 中' },
+          { phase: '4. PoW + Completion', detail: '求解 PoW → 发送 completion 请求 → 接收 SSE 流响应' },
+          { phase: '5. 流式传输', detail: 'GuardedStream 包装 SSE 流，保持账号忙碌状态直到流结束' },
+          { phase: '6. 销毁 session', detail: 'GuardedStream::drop 时销毁 session 并释放账号。异常断开时调用 stop_stream' },
+        ],
+        accountGuard: `// AccountGuard 核心逻辑（伪代码）
+pub struct AccountGuard {
+    account: Arc<Account>,
+}
+
+impl AccountGuard {
+    fn new(account: Arc<Account>) -> Self {
+        account.busy.store(true, Ordering::Relaxed);  // 标记忙碌
+        Self { account }
+    }
+}
+
+impl Drop for AccountGuard {
+    fn drop(&mut self) {
+        self.account.busy.store(false, Ordering::Relaxed);  // 释放
+    }
+}
+
+// GuardedStream 在流结束时触发 AccountGuard::drop
+// 确保 session 在流传输期间不被其他请求复用`,
+        notes: [
+          '1 账号 = 1 session = 1 并发——水平扩展靠增加账号数量',
+          '每次请求创建新 session（不复用），确保多轮对话隔离',
+          'GuardedStream::drop 保证异常断开时也能清理 session',
+          'active_sessions: Arc<Mutex<HashMap>> 追踪所有活跃 session',
+        ],
+      },
+
+      // ── 客户端认证（管理面板） ──
+      clientAuth: {
+        title: '客户端认证（管理面板 + API Key）',
+        description:
+          'ds-free-api 对客户端提供两层认证：管理面板使用 JWT（bcrypt 密码），API 请求使用 API Key。两者独立于 DeepSeek 后端认证。',
+        layers: [
+          {
+            name: '管理面板认证',
+            steps: [
+              { step: '1. 设置密码', detail: '首次访问 /admin 引导设置管理密码。bcrypt 哈希存储，不明文保存' },
+              { step: '2. 登录签发 JWT', detail: '密码验证通过后签发 JWT（24h 有效）。前端存储在 localStorage' },
+              { step: '3. 登录限流', detail: '5 次登录失败锁定 5 分钟，防止暴力破解' },
+              { step: '4. 密码重置吊销', detail: '密码重置时吊销所有旧 JWT，强制重新登录' },
+            ],
+          },
+          {
+            name: 'API Key 认证',
+            steps: [
+              { step: '1. 创建 API Key', detail: '通过管理面板创建/删除 API Key。存储在 config.toml 的 [[api_keys]] 中' },
+              { step: '2. 请求鉴权', detail: '客户端请求携带 Authorization: Bearer <api_key>。HashSet O(1) 查找' },
+              { step: '3. 空配置无认证', detail: 'config 为空时（无 API Key）不启用认证，任何请求都可访问' },
+            ],
+          },
+        ],
+        securityNotes: [
+          '管理密码使用 bcrypt 哈希，不存储明文',
+          'JWT 密钥在首次设置密码时随机生成，存储在 config.toml',
+          'config.toml 文件权限 0600，原子写入（tmp + rename）',
+          '账号 ID 在响应头中脱敏（x-ds-account）',
+          '请求体不记录日志，敏感信息不外泄',
+          'CORS 默认仅允许 localhost:22217，可配置允许的 Origin 列表',
+        ],
+      },
+
+      // ── 与标准 API 认证的对比 ──
+      comparison: {
+        title: '与标准 API 认证的对比',
+        description: 'DeepSeek 网页端认证远比标准 API 复杂——标准 API 只需一个 Key，网页端需要逆向整套反爬体系。',
+        table: [
+          { aspect: '认证方式', standard: 'API Key（Bearer Token）', deepseek: '账号密码登录 + PoW + WAF 绕过 + Session 管理' },
+          { aspect: '认证步骤', standard: '1 步（携带 Key）', deepseek: '7+ 步（登录→Session→PoW→WAF→请求→清理）' },
+          { aspect: '并发模型', standard: '无限制（按量计费）', deepseek: '1 账号 = 1 并发（Session 级限流）' },
+          { aspect: '反爬措施', standard: '无', deepseek: 'PoW 挑战 + AWS WAF + TLS 指纹检测' },
+          { aspect: 'Session 管理', standard: '无状态（每次请求独立）', deepseek: '有状态（创建→使用→销毁，异常清理）' },
+          { aspect: '成本', standard: '按 Token 计费', deepseek: '免费（但有速率限制和并发限制）' },
+          { aspect: '稳定性', standard: '高（SLA 保障）', deepseek: '低（WASM 可能更新、WAF 可能升级、账号可能被封）' },
+        ],
+      },
+    },
+
+    // ── CodeArts IDE OAuth 认证 ──
+    {
+      id: 'codearts-oauth',
+      name: 'CodeArts IDE OAuth',
+      badge: 'OAuth 2.0',
+      tagline: 'PKCE + DPoP + STS Token + SDK-HMAC-SHA256 签名',
+      description:
+        '@wwkit/llmproxy 的 providers/codearts/ 模块逆向了 CodeArts IDE 插件（snap_AIIDE v5.3.0）的认证流程。使用 OAuth 2.0 PKCE + DPoP 向华为云 STS 换取临时安全凭证（AK/SK/SecurityToken），再用 SDK-HMAC-SHA256 对每个请求签名。与 DeepSeek 网页端认证完全不同——这是标准 OAuth 流程，不需要 PoW 或 WAF 绕过。',
+
+      architecture: {
+        title: '认证架构',
+        description:
+          'llmproxy 的 provider 插件架构：providers/<type>/ 下放 auth.js / sign.js / client.js / config.js / error.js 五个文件，core/factory.js 按路径约定动态 import，新增 provider 只需放文件无需改代码。',
+        layers: [
+          {
+            name: 'CodeartsAuth',
+            file: 'providers/codearts/auth.js',
+            role: 'OAuth 2.0 PKCE + DPoP 认证：浏览器登录 → 换 STS Token → 持久化 → 自动续期',
+          },
+          {
+            name: 'CodeartsSign',
+            file: 'providers/codearts/sign.js',
+            role: 'SDK-HMAC-SHA256 请求签名：构造 Canonical Request → HMAC 签名 → 返回 Authorization 头',
+          },
+          {
+            name: 'CodeartsClient',
+            file: 'providers/codearts/client.js',
+            role: '请求发送：auth 拿凭证 + sign 签名 + undici fetch + SSE 异常检测',
+          },
+          {
+            name: 'CodeartsConfig',
+            file: 'providers/codearts/config.js',
+            role: '固定配置：benefit 模型列表（每日免费额度模型自动附加 maas_type 头）',
+          },
+          {
+            name: 'CodeartsError',
+            file: 'providers/codearts/error.js',
+            role: '错误模式识别：TM.00001041 = 并发会话超限',
+          },
+        ],
+        codeStructure: `providers/codearts/
+├── auth.js       # OAuth PKCE + DPoP → STS Token
+├── sign.js       # SDK-HMAC-SHA256 签名 + SIGN_CONFIG (host/basePath)
+├── client.js     # auth + sign + fetch + SSE guard
+├── config.js     # BENEFIT_MODELS (每日免费额度)
+└── error.js      # sessionLimit 错误模式`,
+      },
+
+      oauthFlow: {
+        title: 'OAuth 2.0 PKCE + DPoP 认证流程',
+        description:
+          '完整的 7 步 OAuth 流程，从生成密钥对到拿到可用凭证。PKCE 防止授权码拦截，DPoP 证明请求来自密钥持有者。',
+        steps: [
+          { step: '1. 生成 PKCE pair', detail: 'code_verifier = randomBytes(64).hex；code_challenge = SHA256(code_verifier) → base64url。PKCE 防止授权码被中间人截获——verifier 只在客户端，不经过浏览器' },
+          { step: '2. 生成 DPoP ES256 密钥对', detail: 'crypto.generateKeyPairSync("ec", { namedCurve: "P-256" }) → publicKeyJwk + privateKeyJwk。DPoP (Demonstrating Proof-of-Possession) 让每个 token 请求都附带密钥持有证明' },
+          { step: '3. 启动本地回调服务器', detail: 'http.createServer 监听 127.0.0.1 随机端口，等待 /oauth/callback?code=xxx 回调' },
+          { step: '4. 构建授权 URL + 打开浏览器', detail: 'https://codearts.huaweicloud.com/portal/authorize?client_id=codearts-agent&code_challenge=<PKCE>&... → 经过 IAM 登录页 → 用户手动登录 → 重定向到回调' },
+          { step: '5. 换 STS Token', detail: 'POST https://sts.cn-north-4.myhuaweicloud.com/v1/oauth2/tokens，Headers: DPoP=<ES256 签名 JWT>，Body: client_id + code + code_verifier + grant_type=authorization_code → 返回 access_key_id + secret_access_key + security_token + refresh_token' },
+          { step: '6. 凭证持久化', detail: '存储到 ~/.config/llmproxy/.creds.json（0600 权限），含 AK/SK/SecurityToken/refreshToken/loginContext（PKCE pair + DPoP 密钥对，用于续期）' },
+          { step: '7. 自动续期', detail: 'getCredentials() 检查 expiresAt，过期前 5 分钟用 refresh_token 续期（grant_type=refresh_token + 同一 DPoP 密钥）。续期失败 → 自动触发浏览器重新登录' },
+        ],
+        codeExample: `// providers/codearts/auth.js 核心逻辑
+
+// PKCE 生成
+const codeVerifier = crypto.randomBytes(64).toString("hex")
+const codeChallenge = crypto.createHash("sha256")
+  .update(codeVerifier).digest("base64")
+  .replace(/\\+/g, "-").replace(/\\//g, "_").replace(/=/g, "")
+
+// DPoP 签名
+_signDPoP(dpopKeyPair, method, url) {
+  const payload = { htm: method, htu: url, iat: Date.now()/1000, jti: random }
+  const header = { alg: "ES256", typ: "dpop+jwt", jwk: dpopKeyPair.publicKeyJwk }
+  const data = base64url(header) + "." + base64url(payload)
+  const sig = crypto.createSign("SHA256").update(data)
+    .sign(dpopKeyPair.privateKey)  // ES256 签名
+  return data + "." + base64url(derToRawRS(sig))
+}
+
+// STS Token 交换
+const res = await fetch("https://sts.cn-north-4.myhuaweicloud.com/v1/oauth2/tokens", {
+  method: "POST",
+  headers: { "Content-Type": "application/x-www-form-urlencoded", "DPoP": dpop },
+  body: "client_id=codearts-agent&code=<auth_code>&code_verifier=<pkce>&grant_type=authorization_code"
+})
+// → { credentials: { access_key_id, secret_access_key, security_token, expiration },
+//     refresh_token, domain_id, user_id, user_name }`,
+        notes: [
+          'PKCE：code_verifier 只在客户端，不经过浏览器，防止授权码拦截攻击',
+          'DPoP：每次换 token 时用 ES256 私钥签名一个 JWT（htm+htu+iat+jti），证明密钥持有者身份',
+          'STS Token 是华为云临时安全凭证（AK/SK/SecurityToken），有过期时间，不是永久 Token',
+          'loginContext（含 DPoP 私钥 JWK）一起持久化，续期时重建 KeyPair 对象',
+          '凭证文件 0600 权限，原子写入（先写 tmp 再 rename）',
+          'chat 请求路径上不允许自动登录（autoLogin: false），避免阻塞请求——凭证缺失直接抛错',
+        ],
+      },
+
+      sdkSign: {
+        title: 'SDK-HMAC-SHA256 请求签名',
+        description:
+          '拿到 STS 凭证后，每个 chat 请求需要用华为云 SDK 签名。这是华为云 API Gateway 的标准认证方式，不是 OAuth token 直接使用。',
+        mechanism: [
+          { step: '1. 构造 Canonical Request', detail: 'HTTP方法 + 规范URI(末尾加/) + 规范查询参数(排序+URL编码) + 规范Headers(小写+排序) + 签名Headers列表(分号分隔) + Body的SHA256哈希' },
+          { step: '2. 构造 String to Sign', detail: '"SDK-HMAC-SHA256" + SDK日期(UTC) + SHA256(Canonical Request)' },
+          { step: '3. HMAC-SHA256 签名', detail: 'signature = HMAC-SHA256(secretAccessKey, String to Sign)' },
+          { step: '4. 返回认证头', detail: 'Authorization: SDK-HMAC-SHA256 Access=<AK>, SignedHeaders=<headers>, Signature=<sig> + X-Sdk-Date: <UTC时间>' },
+        ],
+        codeExample: `// providers/codearts/sign.js 核心逻辑
+
+sign(req) {
+  const bodyHash = sha256(req.bodyStr)
+  const canonicalRequest = [
+    req.method.toUpperCase(),    // POST
+    canonicalUri,                // /api/v2/chat/completions/
+    canonicalQueryString,        // 排序+URL编码的查询参数
+    canonicalHeaders,            // 小写+排序的 headers
+    signedHeadersStr,            // host;x-sdk-date;x-security-token
+    bodyHash,                    // body 的 SHA256
+  ].join("\\n")
+
+  const stringToSign = [
+    "SDK-HMAC-SHA256",
+    sdkDate,
+    sha256(canonicalRequest),
+  ].join("\\n")
+
+  const signature = hmacSha256(secretAccessKey, stringToSign)
+  return {
+    Authorization: "SDK-HMAC-SHA256 Access=" + accessKeyId +
+      ", SignedHeaders=" + signedHeadersStr +
+      ", Signature=" + signature,
+    "X-Sdk-Date": sdkDate,
+  }
+}`,
+        notes: [
+          '签名用 SK（secretAccessKey）作为 HMAC 密钥，AK（accessKeyId）放在 Authorization 头',
+          'SecurityToken 通过 X-Security-Token 头传递，因为 STS 凭证是临时的',
+          '每个请求都重新签名——SDK 日期和 body hash 每次不同',
+          'benefit 模型（glm-5.3-flash 等）自动附加 maas_type: benefit 头，消耗每日免费额度',
+        ],
+      },
+
+      requestFlow: {
+        title: '请求发送流程',
+        description:
+          'CodeartsClient 封装了"auth 拿凭证 + sign 签名 + fetch 发送"的完整链路。客户端只需发标准 OpenAI 请求，代理自动添加认证。',
+        steps: [
+          { step: '1. 获取凭证', detail: 'authProvider.getCredentials({ autoLogin: false }) → AK/SK/SecurityToken。chat 路径不自动登录，凭证缺失直接抛错' },
+          { step: '2. 构建请求头', detail: 'Content-Type + Host + X-Security-Token（如有）+ maas_type: benefit（如 benefit 模型）' },
+          { step: '3. SDK 签名', detail: 'signProvider.sign({ method, url, headers, bodyStr, accessKeyId, secretAccessKey }) → Authorization + X-Sdk-Date' },
+          { step: '4. 发送请求', detail: 'undici fetch（connections: 1, keepAliveTimeout: 100ms，避免上游会话池占用）' },
+          { step: '5. SSE 异常检测', detail: 'wrapSSEAbnormalGuard 检测上游 SSE 流中的非标准错误（InferHub.ModelArts.xxx），改写为标准 OpenAI 错误格式' },
+        ],
+      },
+
+      comparison: {
+        title: '与 DeepSeek 网页端认证的对比',
+        description: '两种认证机制完全不同——CodeArts 是标准 OAuth + SDK 签名，DeepSeek 是逆向 PoW/WAF/Session。',
+        table: [
+          { aspect: '认证方式', deepseek: '账号密码 + PoW + WAF 绕过', codearts: 'OAuth 2.0 PKCE + DPoP' },
+          { aspect: '凭证类型', deepseek: 'Bearer Token（Session 级）', codearts: 'STS 临时凭证（AK/SK/SecurityToken）' },
+          { aspect: '请求签名', deepseek: '无（Token 直接用）', codearts: 'SDK-HMAC-SHA256（每个请求签名）' },
+          { aspect: '反爬措施', deepseek: 'PoW WASM + AWS WAF + TLS 指纹', codearts: '无（标准 OAuth 流程）' },
+          { aspect: 'Session 管理', deepseek: '有状态（创建→使用→销毁）', codearts: '无状态（Token 续期即可）' },
+          { aspect: '并发模型', deepseek: '1 账号 = 1 并发', codearts: '无限制（按 STS 额度）' },
+          { aspect: '凭证续期', deepseek: '重新登录（无 refresh）', codearts: 'refresh_token 自动续期（5 分钟前）' },
+          { aspect: '用户交互', deepseek: '无（全自动逆向）', codearts: '首次需浏览器手动登录' },
+          { aspect: '稳定性', deepseek: '低（WASM/WAF 可能更新）', codearts: '高（标准 OAuth 2.0 协议）' },
+        ],
+      },
+    },
+
+    // ── bluesllm W3 账密认证 ──
+    {
+      id: 'bluesllm-w3',
+      name: 'bluesllm W3 认证',
+      badge: '账密登录',
+      tagline: 'W3 工号密码登录 + Token 缓存 + 模板替换 + 三种认证模式',
+      description:
+        '@wego/bluesllm 的 auth.js 支持三种认证类型（auth.type）：w3（默认，账密登录获取 token）、apikey（静态 Key）、cookie（静态凭据）。核心是 TokenManager——用 W3 工号密码调用华为内部登录接口，获取 cloudDragonTokens.authToken，缓存 24 小时，过期自动刷新。认证与协议转换完全分离：createAuthHooks() 返回 headerHook（注入认证头）和 requestHook（注入 body 参数），与 translator.js 无关。',
+
+      architecture: {
+        title: '认证架构',
+        description:
+          'bluesllm 的认证模块分为 TokenManager（W3 登录+缓存）和 createAuthHooks（Hook 工厂）两部分。配置驱动——所有行为差异由 configs/*.json 的 auth/headers/body 段控制。',
+        layers: [
+          {
+            name: 'TokenManager',
+            file: 'src/auth.js',
+            role: 'W3 账密登录：POST 登录接口 → 提取 cloudDragonTokens.authToken + department → 缓存到 <name>-token.json（24h TTL）→ 过期自动刷新',
+          },
+          {
+            name: 'createAuthHooks',
+            file: 'src/auth.js',
+            role: 'Hook 工厂：根据 auth.type 创建 headerHook（注入认证头）+ requestHook（注入 body 参数 + 强制 stream）',
+          },
+          {
+            name: 'Config',
+            file: 'configs/base.json',
+            role: '认证配置：auth.type / login_url / app_name / token_cache_duration / env_dir / env_file',
+          },
+          {
+            name: 'env.json',
+            file: '~/.bluesllm/env.json',
+            role: '凭证存储：W3_USER_ID + W3_USER_PWD（w3 模式）或 {NAME}_API_KEY（apikey 模式）',
+          },
+        ],
+        codeStructure: `src/auth.js
+├── TokenManager              # W3 登录 + token 缓存
+│   ├── getData(force)        # 获取有效 token（缓存优先）
+│   ├── getCached()           # 从磁盘读缓存
+│   ├── isTokenValid(cached)  # 检查 expiry
+│   ├── refresh()             # 调用登录接口
+│   ├── getCodemateData(data) # 提取 token + department
+│   └── saveData(data)        # 持久化到磁盘
+├── createAuthHooks(config)   # Hook 工厂
+│   ├── headerHook            # 注入认证头（{token}/{api_key} 模板替换）
+│   └── requestHook           # 注入 body 参数 + force_stream
+├── getApiKey(config)         # apikey 模式：读 env.json 或内置默认值
+├── getCookieEnv(config)      # cookie 模式：读 env.json 前缀字段
+└── getEnvConfig(envFile)     # w3 模式：读 W3_USER_ID/W3_USER_PWD`,
+      },
+
+      threeAuthModes: {
+        title: '三种认证模式',
+        description:
+          'bluesllm 通过 auth.type 配置切换三种认证模式，无需改代码。三种模式共享 headerHook/requestHook 接口，但凭证来源不同。',
+        modes: [
+          {
+            name: 'w3（默认）',
+            type: 'auth.type = "w3"',
+            credential: 'W3 工号密码 → 登录接口 → cloudDragonTokens.authToken + department',
+            template: '{token} / {department} 模板替换到 headers.inject',
+            useCase: '华为内部模型服务（cida/codemate 等），需要 W3 账号认证',
+          },
+          {
+            name: 'apikey',
+            type: 'auth.type = "apikey"',
+            credential: 'env.json 中的 {NAME}_API_KEY 或代码内置默认值',
+            template: '{api_key} 模板替换到 headers.inject',
+            useCase: '公开代理服务，用户无需配置 W3 账号，内置 API Key 即可使用',
+          },
+          {
+            name: 'cookie',
+            type: 'auth.type = "cookie"',
+            credential: 'env.json 中 {NAME}_ 前缀的所有字段（如 AUTH_TOKEN、COOKIE）',
+            template: '{auth_token} / {cookie} 等模板替换到 headers.inject',
+            useCase: '使用浏览器 Cookie 认证的服务，从 env.json 读取静态凭据',
+          },
+        ],
+      },
+
+      w3Flow: {
+        title: 'W3 账密登录流程',
+        description:
+          'TokenManager 的完整认证流程：从 env.json 读取账密 → 调用登录接口 → 提取 token + department → 缓存 → 模板替换注入请求头。',
+        steps: [
+          { step: '1. 读取账密', detail: '从 ~/.bluesllm/env.json 读取 W3_USER_ID 和 W3_USER_PWD。缺失则抛错"Missing W3 credentials"' },
+          { step: '2. 检查缓存', detail: '从 <name>-token.json 读取缓存的 token 数据，检查 codemate.expiry 是否在有效期内（24h TTL）' },
+          { step: '3. 调用登录接口', detail: 'POST https://rnd-idea-api.huawei.com/ideaclientservice/login/v4/secureLogin，Body: { user, password, requireUserInfo, appName, oauthApp, requireCodeHubOpenToken }' },
+          { step: '4. 提取 token', detail: '从响应中提取 cloudDragonTokens.authToken（token）和 userInfo 中的 hwDepartName1-6（拼接为 department）' },
+          { step: '5. 持久化', detail: '将完整登录响应 + codemate（token + department + expiry）写入 <name>-token.json。多代理实例各自独立缓存' },
+          { step: '6. 模板替换', detail: 'headerHook 将 headers.inject 中的 {token} 替换为 authToken、{department} 替换为部门路径，注入到请求头' },
+          { step: '7. 自动刷新', detail: 'getData() 检查缓存有效性，过期时自动调用 refresh() 重新登录。重试时（ctx.retry > 0）强制刷新' },
+        ],
+        codeExample: `// src/auth.js — TokenManager 核心逻辑
+
+class TokenManager {
+  // 获取有效 token（缓存优先）
+  async getData(force = false) {
+    if (force) return this.refresh()
+    const cached = this.getCached()
+    if (this.isTokenValid(cached)) return cached
+    return this.refresh()
+  }
+
+  // 调用 W3 登录接口
+  async refresh() {
+    const response = await fetch(this.loginUrl, {
+      method: "POST",
+      headers: {
+        "X-Language": "en",
+        "Content-Type": "application/json",
+        "X-User-Id": this.userId,
+      },
+      body: JSON.stringify({
+        user: this.userId,
+        password: this.userPwd,
+        requireUserInfo: true,
+        appName: this.appName,
+        oauthApp: this.appName,
+        requireCodeHubOpenToken: true,
+      }),
+    })
+    const data = await response.json()
+    data.codemate = this.getCodemateData(data)
+    this.saveData(data)
+    return data
+  }
+
+  // 提取 token + department
+  getCodemateData(data) {
+    const token = data?.cloudDragonTokens?.authToken
+    if (!token) return {}
+    const dept = [hwDepartName1, ..., hwDepartName6]
+      .filter(Boolean).join("/")
+    return { token, department: dept, expiry: now + 86400 }
+  }
+}
+
+// headerHook 模板替换
+headerHook = async (ctx, incomingHeaders) => {
+  const data = await tokenManager.getData(ctx.retry > 0)
+  const token = data.codemate.token
+  const department = data.codemate.department
+  for (const [key, val] of Object.entries(inject)) {
+    result[key] = String(val)
+      .replaceAll("{token}", token)
+      .replaceAll("{department}", department)
+  }
+}`,
+        notes: [
+          'W3 登录是华为内部认证——使用工号密码，不是 OAuth 或 API Key',
+          'cloudDragonTokens.authToken 是登录后获得的 Bearer Token，用于后续 API 请求',
+          'department 是用户部门路径（如 "Cloud/BU1/Team2"），部分上游需要此信息',
+          'token 缓存 24 小时（86400 秒），过期自动刷新，无需用户干预',
+          '重试时强制刷新 token（ctx.retry > 0 → force=true），避免用过期 token 重试',
+          'env.json 权限应为 0600，包含明文密码——不提交到 git',
+          'NODE_TLS_REJECT_UNAUTHORIZED=0：内网 SSL 证书不校验（华为内网常见）',
+        ],
+      },
+
+      hookSystem: {
+        title: 'Hook 系统：认证与请求注入',
+        description:
+          'createAuthHooks() 返回 headerHook 和 requestHook 两个异步函数。headerHook 在请求发送前注入认证头，requestHook 在请求体发送前注入参数。两者与协议转换完全分离。',
+        headerHook: `// headerHook: 注入认证头
+async function headerHook(ctx, incomingHeaders) {
+  // 1. 获取凭证（w3/apikey/cookie 三选一）
+  const { token, department } = await tokenManager.getData()
+  // 2. 展开客户端传入的 headers（可选）
+  if (spread_incoming) Object.assign(result, incomingHeaders)
+  // 3. 注入静态 headers（模板替换）
+  for (const [key, val] of Object.entries(inject)) {
+    result[key] = val
+      .replaceAll("{token}", token)
+      .replaceAll("{department}", department)
+  }
+  // 4. 注入动态 headers（uuid / timestamp_ms 等）
+  for (const [key, funcName] of Object.entries(dynamic)) {
+    result[key] = resolveDynamic(funcName)
+  }
+  return result
+}`,
+        requestHook: `// requestHook: 注入 body 参数
+async function requestHook(ctx, body) {
+  // 1. 强制 stream=true（body.force_stream）
+  if (force_stream) parsed.stream = true
+  // 2. 注入缺失参数（body.inject，仅在 undefined/null 时填充）
+  for (const [key, val] of Object.entries(inject)) {
+    if (parsed[key] === undefined) parsed[key] = val
+  }
+  // 3. 强制覆盖参数（body.override，无条件替换）
+  for (const [key, val] of Object.entries(override)) {
+    parsed[key] = val
+  }
+  return body
+}`,
+        notes: [
+          'headerHook 和 requestHook 是异步函数，接收 (ctx, data) 参数，返回修改后的 data',
+          'ctx.retry 表示当前重试次数，> 0 时强制刷新 token',
+          'ctx.logger 可选链式调用（this.logger?.info?.(...)），logger 不存在时静默跳过',
+          'Throw HookAbortError 可中止请求——认证失败时抛出带 status_code 的错误',
+          'force_stream 让上游强制返回流式响应，代理再决定是否 merge_stream_to_non_stream',
+        ],
+      },
+
+      comparison: {
+        title: '三种认证机制对比',
+        description: 'bluesllm W3 认证、CodeArts OAuth、DeepSeek 逆向认证三种机制的本质差异。',
+        table: [
+          { aspect: '认证方式', bluesllm: 'W3 工号密码登录', codearts: 'OAuth 2.0 PKCE + DPoP', deepseek: '账号密码 + PoW + WAF' },
+          { aspect: '凭证类型', bluesllm: 'cloudDragonTokens.authToken（Bearer）', codearts: 'STS 临时凭证（AK/SK/Token）', deepseek: 'Session Token' },
+          { aspect: '请求签名', bluesllm: '无（Token 模板替换到头）', codearts: 'SDK-HMAC-SHA256', deepseek: '无（Token 直接用）' },
+          { aspect: '凭证缓存', bluesllm: '<name>-token.json（24h）', codearts: '.creds.json（含 refresh_token）', deepseek: '内存（Session 级）' },
+          { aspect: '自动续期', bluesllm: '过期重新登录（无 refresh_token）', codearts: 'refresh_token 续期（5 分钟前）', deepseek: '重新登录' },
+          { aspect: '用户交互', bluesllm: '无（配置文件存账密）', codearts: '首次需浏览器登录', deepseek: '无（全自动逆向）' },
+          { aspect: '多模式', bluesllm: '✅ w3 / apikey / cookie 三选一', codearts: '❌ 仅 OAuth', deepseek: '❌ 仅逆向' },
+          { aspect: '认证与转换', bluesllm: '分离（Hook 系统 vs translator.js）', codearts: '分离（auth.js vs 无转换）', deepseek: '分离（ds_core vs adapter）' },
+        ],
+      },
+    },
+  ],
+}