dsh-tap 0.20.0

package/providers/trae/index.js

@@ -0,0 +1,126 @@
+/**
+ * providers/trae/index.js — TraeWork CN（api.trae.cn / trae-api-cn.mchost.guru）
+ * 薄适配器。
+ *
+ * 与 providers/codebuddy/ 同构：本目录收敛全部 Trae 上游事实（OAuth 设备流、
+ * 本地模型目录、云端翻译网关、错误信封），core/ 与组合根通过结构钩子消费。
+ * 规则/证据文档：
+ *   - docs/reverse/traework-cn.md       → OAuth 与云端面逆向档案
+ *   - docs/reverse/trae-cloud-api.md    → 2026-08-23 无凭据探测校准（网关/信封）
+ *   - docs/reverse/trae-model-catalog.md → 目录提取安全契约
+ *
+ * 凭据形态与 codebuddy 的差异：Trae 只有 OAuth 一种模式（订阅额度跟账号走），
+ * 没有多 Key 轮换；设备密钥自持（oauth.js 文件头），刷新可自控。
+ */
+
+import { createTraeOAuth } from './oauth.js'
+import { fetchLocalCatalog } from './catalog.js'
+import { createTraeGateway } from './gateway.js'
+import { createTraeQuota } from './quota.js'
+
+export const TRAE_PROVIDER_ID = 'trae'
+
+/**
+ * @param {{
+ *   readAuth: () => object,
+ *   writeAuth: (v: object) => void,
+ *   settings: () => object,
+ *   withCredentials: (attempt: (cred) => Promise<Response>) => Promise<{cred,res,err}>,
+ *   meter: { record: Function },
+ *   runtime: { running: boolean, port: number|null, lastError: string|null },
+ *   forensics?: { logPath: () => string|undefined },
+ *   getModelPrefs?: () => object,  // { [id]: { effort? } } remote 出站补默认档位（G3）
+ * }} deps
+ */
+export function createTraeProvider(deps) {
+  const oauth = createTraeOAuth({ readAuth: deps.readAuth, writeAuth: deps.writeAuth })
+
+  // 目录实例状态（模块作用域每插件实例一份，踩坑 #20 纪律）。
+  let catalogState = null // { profiles, catalog, fetchedAt, source }
+  let lastSyncError = null // 最近一次同步失败原因（成功即清空；设置卡模型区显示用）
+
+  const provider = {
+    id: TRAE_PROVIDER_ID,
+    oauth,
+
+    /** 从本机 state.vscdb 同步目录（单飞）。返回 {ok, count|error, kept}。 */
+    async syncCatalog({ dbPath } = {}) {
+      try {
+        const result = fetchLocalCatalog({ dbPath })
+        catalogState = result
+        lastSyncError = null
+        return { ok: true, count: result.profiles.length, fetchedAt: result.fetchedAt, source: result.source }
+      } catch (err) {
+        lastSyncError = err?.message ?? String(err)
+        return { ok: false, error: lastSyncError, kept: catalogState != null }
+      }
+    },
+
+    catalogView() {
+      return catalogState
+        ? {
+            at: catalogState.fetchedAt,
+            count: catalogState.profiles.length,
+            candidate: catalogState.source.chosen,
+            profiles: catalogState.profiles,
+            // 逐模型目录声明档位（reasoning_effort_config.options 原文拼写，G3）——
+            // 设置卡 select 选项与 traeModelSetPrefs 校验的真源（上游词汇；宿主
+            // 选择器侧的枚举键映射在 catalogToProfiles 的 reasoningEfforts 里）。
+            // 未声明模型不在场。max 不在目录 options 里但上游实测接受且产生
+            // 比 extra_high 更多的推理（docs/probes/trae-max-effort-*.json），
+            // 给声明了 extra_high 的模型追加为上位档。
+            efforts: Object.fromEntries(
+              (catalogState.catalog?.models ?? [])
+                .filter((m) => m.reasoningEffortConfig?.supportThinking === true
+                  && Array.isArray(m.reasoningEffortConfig.options) && m.reasoningEffortConfig.options.length)
+                .map((m) => {
+                  const opts = m.reasoningEffortConfig.options.slice()
+                  if (opts.includes('extra_high') && !opts.includes('max')) opts.push('max')
+                  return [m.id, opts]
+                })),
+          }
+        : null
+    },
+
+    /** 设置卡模型区的同步状态：成功 → {at,count,candidate}；失败 → 附 error
+     * （有旧清单则连同旧计数一起给 = kept 语义；从未成功过则只有 error）。 */
+    syncView() {
+      if (!catalogState) return lastSyncError ? { error: lastSyncError } : null
+      const view = {
+        at: catalogState.fetchedAt,
+        count: catalogState.profiles.length,
+        candidate: catalogState.source.chosen,
+      }
+      if (lastSyncError) view.error = lastSyncError
+      return view
+    },
+
+    /** 已同步目录 id（/models 端点与镜像同步用）。 */
+    catalogIds() {
+      return catalogState ? catalogState.profiles.map((p) => p.id) : []
+    },
+
+    /** 凭据视图（设置卡）。 */
+    credentialView() {
+      return oauth.oauthStatus()
+    },
+
+    /** 双额度池余额只读快照（60s memoize，永不 throw）。 */
+    quota: createTraeQuota({ settings: deps.settings, readAuth: deps.readAuth, oauth }),
+  }
+
+  const gateway = createTraeGateway({
+    settings: deps.settings,
+    withCredentials: deps.withCredentials,
+    readAuthDevice: () => deps.readAuth().device ?? null,
+    readAuthMeta: () => ({ uid: deps.readAuth().account?.uid ?? null }),
+    meter: deps.meter,
+    runtime: deps.runtime,
+    forensics: deps.forensics,
+    getCatalogIds: () => provider.catalogIds(),
+    getModelPrefs: deps.getModelPrefs ?? (() => ({})),
+  })
+  provider.gateway = gateway
+
+  return provider
+}

package/providers/trae/oauth.js

@@ -0,0 +1,443 @@
+/**
+ * providers/trae/oauth.js — TraeWork CN OAuth 设备流（自持设备密钥）。
+ *
+ * 流程（docs/reverse/traework-cn.md §OAuth，2026-08-23 无凭据实测校准）：
+ *   1. 本地回环服务 127.0.0.1:<随机端口>，唯一端点 GET /authorize；
+ *   2. 授权页 URL = <loginHost>/authorization?…&code_challenge=S256…（PKCE）；
+ *   3. 浏览器完成登录后 302 回 /authorize?userInfo=…&authCodeInfo=…（JSON 字符串
+ *      内嵌 AuthCode）；
+ *   4. POST <authBase>/trae/api/v3/oauth/ExchangeToken（AuthCode 模式）：
+ *      {ClientID, AuthCode, CodeVerifier, DeviceInfo{…DevicePublicKey}, IDEVersion}
+ *      → Result.{Token, RefreshToken, TokenExpireAt, TokenExpireDuration, RefreshExpireAt}；
+ *   5. 刷新 = 同端点 RefreshToken 模式 + DeviceProof{Signature,Timestamp,Nonce}：
+ *      签名串逐行拼接 "POST\n/trae/api/v3/oauth/ExchangeToken\n<ClientID>\n
+ *      <RefreshToken>\n<Timestamp>\n<Nonce>"，ECDSA P-256/SHA-256。
+ *
+ * 关键设计：设备密钥对由**本插件生成并持有**（首次登录时创建 P-256 PKCS#8，
+ * 存 ~/.dsh/trae-plugin-auth.json），DeviceInfo.DevicePublicKey 上报公钥——因此
+ * refresh 的 DeviceProof 签名完全可自控，不依赖官方 IDE 的安全存储（traework-cn.md
+ * 关键判断 #5 只针对"偷 IDE 的 refresh token"路线，本路线不受其限制）。
+ *
+ * 实测锚点（2026-08-23，无凭据探测）：
+ *   - ExchangeToken 双路径均存活；假 ClientID → 400 code 10101 "Invalid client."；
+ *     真实 ClientID + 假 AuthCode → 400 code 10101 "无效参数：{__Message.field}."；
+ *   - GetUserInfo 无 token → 401 code 20310 "The user is not logged in,"；
+ *   - 错误信封均为火山系 ResponseMetadata.Error{Code,Message,StandardCode}。
+ *
+ * 实例状态（refresh 单飞锁、pending 回环服务句柄）在本工厂闭包内（踩坑 #20 纪律）。
+ */
+
+import { createServer } from 'node:http'
+import { createHash, generateKeyPairSync, randomBytes, randomInt, randomUUID, sign, createPrivateKey } from 'node:crypto'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const CLIENT_ID_SOLO_LITE = 'en1oxy7wnw8j9n' // SOLO Lite 分支默认（traework-cn.md §3）
+const CLIENT_ID_TRAE = 'ono9krqynydwx5' // 普通 TRAE 分支默认
+const PLATFORM_CODE = 'SOLO_PC'
+const IDE_VERSION = '0.1.52'
+const PLUGIN_VERSION = '2.3.73734'
+const LOGIN_TIMEOUT_MS = 10 * 60 * 1000
+
+/** 秒级时间戳与毫秒级并存于线上响应（doc 示例是秒），统一归一到毫秒。 */
+function normalizeExpiry(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return null
+  return value > 1e12 ? value : value * 1000
+}
+
+function b64url(buf) {
+  return Buffer.from(buf).toString('base64url')
+}
+
+/** HTML 转义（审计 [10]/[15]/[21]/[24]）：登录回调页以 text/html 应答，所有
+ *  来自 URL query / 上游响应的插值必须先转义，杜绝回环页上的脚本注入。 */
+function esc(value) {
+  return String(value)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;')
+}
+
+/** 从设备身份生成出站 DeviceInfo（公钥用 SPKI base64，私钥永不出存储）。 */
+function deviceInfoFrom(device) {
+  return {
+    DeviceID: device.deviceId,
+    MachineID: device.machineId,
+    PlatformCode: PLATFORM_CODE,
+    DeviceType: 'PC',
+    DeviceName: device.deviceName,
+    DeviceModel: device.deviceModel,
+    ClientVersion: IDE_VERSION,
+    DevicePublicKey: device.devicePublicKey,
+    DeviceBrand: device.deviceBrand,
+    DeviceCPU: device.deviceCpu,
+    OSInfo: device.osInfo,
+    OSVersion: device.osVersion,
+  }
+}
+
+/** 解析 ExchangeToken 响应（成功 Result / 失败 ResponseMetadata.Error）。 */
+function parseExchangeResult(body) {
+  if (!body || typeof body !== 'object') return { error: '响应不是 JSON 对象' }
+  if (body.Result?.Token) {
+    const r = body.Result
+    return {
+      token: r.Token,
+      refreshToken: r.RefreshToken ?? null,
+      expiresAt: normalizeExpiry(r.TokenExpireAt),
+      refreshExpiresAt: normalizeExpiry(r.RefreshExpireAt),
+    }
+  }
+  const err = body.ResponseMetadata?.Error
+  if (err) return { error: `ExchangeToken ${err.Code}：${err.Message}` }
+  return { error: `ExchangeToken 响应缺少 Result.Token` }
+}
+
+/**
+ * @param {{
+ *   readAuth: () => object, writeAuth: (v: object) => void,
+ * }} deps 令牌存储 IO（组合根绑定 ~/.dsh/trae-plugin-auth.json；令牌与设备
+ *   私钥永不回传浏览器——oauthStatus() 只出视图字段）。
+ */
+export function createTraeOAuth({ readAuth, writeAuth }) {
+  let refreshInFlight = null
+  // 令牌存储代际号：logout 令其失效。refresh 落盘是读-改-写（writeAuth
+  // ({...readAuth(), auth: next})）——与 logout 的整体覆写竞态时，在飞刷新
+  // 会把已登出的令牌写回（登出失效）。落盘前比对代际，过期即丢弃结果。
+  let storeGeneration = 0
+  const pending = { active: false, authUrl: '', error: '' , closeServer: null }
+
+  /** 首次使用时生成并持久化设备身份 + P-256 密钥对（幂等）。 */
+  function ensureDevice(store) {
+    if (store.device?.privateKeyPem && store.device?.clientId) return store.device
+    const { publicKey, privateKey } = generateKeyPairSync('ec', { namedCurve: 'P-256' })
+    const device = {
+      clientId: CLIENT_ID_SOLO_LITE,
+      // 设备标识形态对齐官方日志：十进制设备 id + 64 hex 机器 id。16 位、
+      // 首位非零——node:crypto 随机（审计 [16]：Math.random 可预测，凭据栈禁用）。
+      deviceId: Array.from({ length: 16 }, (_, i) => randomInt(i === 0 ? 1 : 0, 10)).join(''),
+      machineId: randomBytes(32).toString('hex'),
+      deviceName: 'DESKTOP-' + randomBytes(4).toString('hex').toUpperCase(),
+      deviceModel: 'PC',
+      deviceBrand: 'volcengine',
+      deviceCpu: 'AMD64',
+      osInfo: 'Windows',
+      osVersion: '10.0.26100',
+      devicePublicKey: publicKey.export({ type: 'spki', format: 'der' }).toString('base64'),
+      privateKeyPem: privateKey.export({ type: 'pkcs8', format: 'pem' }).toString(),
+      // DeviceProof 签名编码：DER（node:crypto 原生）；若线上校验要求 IEEE-P1363
+      // 裸签名，改为 'raw'（DER→r||s 转换在 signDeviceProof 内）。
+      signatureFormat: 'der',
+    }
+    const next = { ...store, device }
+    writeAuth(next)
+    return device
+  }
+
+  function derToRaw(der) {
+    // SEQUENCE(r INTEGER, s INTEGER) → 32+32 大端拼接
+    let offset = 2
+    if (der[1] & 0x80) offset += der[1] & 0x7f
+    const readInt = () => {
+      const len = der[offset + 1]
+      offset += 2
+      const bytes = der.subarray(offset, offset + len)
+      offset += len
+      // 去掉前导 0x00，左填充到 32 字节
+      const stripped = bytes[0] === 0 ? bytes.subarray(1) : bytes
+      return Buffer.concat([Buffer.alloc(32 - stripped.length), stripped])
+    }
+    return Buffer.concat([readInt(), readInt()])
+  }
+
+  function signDeviceProof(device, refreshToken, timestamp, nonce) {
+    const stringToSign = ['POST', '/trae/api/v3/oauth/ExchangeToken', device.clientId, refreshToken, String(timestamp), nonce].join('\n')
+    const key = createPrivateKey(device.privateKeyPem)
+    const der = sign('sha256', Buffer.from(stringToSign, 'utf8'), key)
+    const sig = device.signatureFormat === 'raw' ? derToRaw(der) : der
+    return sig.toString('base64')
+  }
+
+  /** RefreshToken 模式换新 token（单飞；失败返回 undefined 不抛）。 */
+  async function refreshOAuth(s, auth) {
+    if (refreshInFlight) return refreshInFlight
+    const generation = storeGeneration
+    refreshInFlight = (async () => {
+      try {
+        const store = readAuth()
+        const device = ensureDevice(store)
+        const timestamp = Math.floor(Date.now() / 1000)
+        const nonce = randomBytes(16).toString('hex')
+        const body = {
+          ClientID: device.clientId,
+          ClientSecret: '',
+          RefreshToken: auth.refreshToken,
+          DeviceInfo: deviceInfoFrom(device),
+          DeviceProof: {
+            Signature: signDeviceProof(device, auth.refreshToken, timestamp, nonce),
+            Timestamp: timestamp,
+            Nonce: nonce,
+          },
+          IDEVersion: IDE_VERSION,
+        }
+        const res = await fetch(`${s.traeAuthBaseURL}/trae/api/v3/oauth/ExchangeToken`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+          body: JSON.stringify(body),
+        })
+        const parsed = parseExchangeResult(await res.json().catch(() => null))
+        if (parsed.error) return undefined
+        // logout 竞态守卫：代际在飞期间已变（用户点了退出）→ 丢弃刷新结果
+        if (generation !== storeGeneration) return undefined
+        const next = {
+          accessToken: parsed.token,
+          expiresAt: parsed.expiresAt ?? (Date.now() + 3600_000),
+          refreshToken: parsed.refreshToken ?? auth.refreshToken,
+          refreshExpiresAt: parsed.refreshExpiresAt ?? auth.refreshExpiresAt ?? null,
+        }
+        writeAuth({ ...readAuth(), auth: next })
+        return next
+      } catch {
+        return undefined
+      } finally {
+        refreshInFlight = null
+      }
+    })()
+    return refreshInFlight
+  }
+
+  /** 每次出站共用的凭据分支：临期自动刷新，双头形态（Cloud-IDE-JWT + x-cloudide-token）。
+   *  expiresAt 缺失视为临期而非永不过期——拿着未知新鲜度的凭据出门，上游 401
+   *  远不如本地一次清晰刷新（有 refreshToken 时）。 */
+  async function resolveTraeCredential(s) {
+    const store = readAuth()
+    const auth = store.auth
+    if (!auth?.accessToken) return null
+    let current = auth
+    const stale = !auth.expiresAt || auth.expiresAt - Date.now() < 60_000
+    if (auth.refreshToken && stale) {
+      const refreshed = await refreshOAuth(s, auth)
+      if (!refreshed) return null
+      current = refreshed
+    }
+    return {
+      authorization: `Cloud-IDE-JWT ${current.accessToken}`,
+      headers: { 'x-cloudide-token': current.accessToken, 'X-User-Region': 'CN' },
+    }
+  }
+
+  /**
+   * 启动登录：开回环回调服务 → 返回授权页 URL。浏览器 302 回 /authorize 后，
+   * 回调内完成 AuthCode→Token 交换与账号信息拉取，然后关闭服务。
+   */
+  async function startOAuth(s) {
+    if (pending.active) return { started: true, authUrl: pending.authUrl }
+
+    // 基址前置校验（开回环服务之前）：traeLoginHost 保存侧已过 validateBaseURL
+    // （组合根），但手改设置文件仍可能塞进 javascript: 之类非法值——在此响亮
+    // 失败，而不是拼出可执行授权页 URL 直送浏览器导航。与 codebuddy 的
+    // assertSafeAuthUrl 不同：本 URL 的 host 来自本地用户设置而非上游响应，
+    // 故只做基址校验、不做站点族校验。校验置于 listen 之前：失败时不遗留
+    // 回环监听句柄。
+    let loginBase
+    try {
+      loginBase = new URL(s.traeLoginHost)
+    } catch {
+      throw new Error('traeLoginHost 不是合法 URL')
+    }
+    if (loginBase.protocol !== 'http:' && loginBase.protocol !== 'https:') {
+      throw new Error('traeLoginHost 必须使用 http 或 https')
+    }
+
+    const store = readAuth()
+    const device = ensureDevice(store)
+    const codeVerifier = b64url(randomBytes(48))
+    const codeChallenge = b64url(createHash('sha256').update(codeVerifier).digest())
+    const traceId = randomUUID()
+
+    const server = createServer((req, res) => { handleCallback(req, res) })
+    await new Promise((resolve, reject) => {
+      server.once('error', reject)
+      server.listen(0, '127.0.0.1', () => resolve())
+    })
+    const port = server.address().port
+    const callbackUrl = `http://127.0.0.1:${port}/authorize`
+
+    const params = new URLSearchParams({
+      login_version: '1',
+      auth_from: 'solo',
+      login_channel: 'native_ide',
+      plugin_version: PLUGIN_VERSION,
+      auth_type: 'local',
+      client_id: device.clientId,
+      redirect: '0',
+      login_trace_id: traceId,
+      auth_callback_url: callbackUrl,
+      machine_id: device.machineId,
+      device_id: device.deviceId,
+      x_device_id: device.deviceId,
+      x_machine_id: device.machineId,
+      x_device_brand: device.deviceBrand,
+      x_device_type: device.osInfo,
+      x_os_version: device.osVersion,
+      x_app_version: IDE_VERSION,
+      x_app_type: 'stable',
+      code_challenge: codeChallenge,
+      code_challenge_method: 'S256',
+      hide_saas_login: 'true',
+    })
+    // URL 解析构造：合法 http(s) 基址 + 路径绝对引用恒可解析；基址带尾路径或
+    // 尾斜杠时以 /authorization 为准（旧字符串拼接会产出 `//authorization`
+    // 双斜杠或把基址路径串进授权页路径）。
+    const authUrl = new URL(`/authorization?${params.toString()}`, loginBase).toString()
+
+    pending.active = true
+    pending.authUrl = authUrl
+    pending.error = ''
+    pending.closeServer = () => {
+      try { server.closeAllConnections?.(); server.close() } catch { /* best-effort */ }
+      pending.closeServer = null
+    }
+    const timer = setTimeout(() => {
+      if (pending.active) pending.error = '登录超时（10 分钟未完成回调）'
+      pending.active = false
+      pending.closeServer?.()
+    }, LOGIN_TIMEOUT_MS)
+    timer.unref?.()
+
+    /** 回调处理：解析 query → 交换 token → 拉账号 → 落盘 → 应答成功页。 */
+    async function handleCallback(req, res) {
+      const finish = (html, logErr) => {
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+        res.end(html)
+        clearTimeout(timer)
+        pending.active = false
+        pending.closeServer?.()
+        if (logErr) pending.error = logErr
+      }
+      try {
+        const url = new URL(req.url, callbackUrl)
+        if (url.pathname !== '/authorize') {
+          finish('<h3>404</h3>')
+          return
+        }
+        const q = url.searchParams
+        const errCode = q.get('error_code')
+        if (errCode) {
+          const errMsg = q.get('error_msg') ?? ''
+          // query 是外部输入：进 text/html 前一律转义（审计 [10]/[15]/[21]/[24]）。
+          // pending.error 是 JSON 状态视图字段（设置卡按 React 文本节点渲染），
+          // 保持原文不双转义。
+          finish(`<h3>登录失败</h3><p>${esc(errCode)} ${esc(errMsg)}</p>`,
+            `登录失败：${errCode} ${errMsg}`)
+          return
+        }
+        let authCode = null
+        try {
+          const info = JSON.parse(q.get('authCodeInfo') ?? 'null')
+          authCode = info?.AuthCode ?? info?.authCode ?? null
+        } catch { /* not JSON */ }
+        if (!authCode) {
+          finish('<h3>回调缺少 AuthCode</h3>', '回调缺少 AuthCode')
+          return
+        }
+        const body = {
+          ClientID: device.clientId,
+          AuthCode: authCode,
+          CodeVerifier: codeVerifier,
+          DeviceInfo: deviceInfoFrom(device),
+          IDEVersion: IDE_VERSION,
+        }
+        const res2 = await fetch(`${s.traeAuthBaseURL}/trae/api/v3/oauth/ExchangeToken`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+          body: JSON.stringify(body),
+        })
+        const parsed = parseExchangeResult(await res2.json().catch(() => null))
+        if (parsed.error) {
+          finish(`<h3>Token 交换失败</h3><p>${esc(parsed.error)}</p>`, parsed.error)
+          return
+        }
+        const auth = {
+          accessToken: parsed.token,
+          expiresAt: parsed.expiresAt ?? (Date.now() + 3600_000),
+          refreshToken: parsed.refreshToken,
+          refreshExpiresAt: parsed.refreshExpiresAt ?? null,
+        }
+        // 账号信息尽力而为（GetUserInfo，双头形态）。
+        let account = {}
+        try {
+          const acc = await fetch(`${s.traeAuthBaseURL}/cloudide/api/v3/trae/GetUserInfo`, {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              Authorization: `Cloud-IDE-JWT ${auth.accessToken}`,
+              'x-cloudide-token': auth.accessToken,
+              'X-User-Region': 'CN',
+            },
+          })
+          const accBody = await acc.json().catch(() => null)
+          const r = accBody?.Result
+          if (r && typeof r === 'object') {
+            account = {
+              // 2026-08-24 实测：GetUserInfo 的昵称字段是 ScreenName。
+              nickname: r.ScreenName ?? r.Name ?? r.Nickname ?? r.UserName ?? r.DisplayName ?? null,
+              uid: r.UserId ?? r.UserID ?? r.Uid ?? null,
+              email: r.Email ?? null,
+            }
+          }
+        } catch { /* best-effort */ }
+        writeAuth({ ...readAuth(), auth, account })
+        finish('<h3>登录成功</h3><p>可以回到 dsh 设置卡继续。</p>')
+      } catch (err) {
+        const errMsg = String(err?.message ?? err)
+        finish(`<h3>登录处理异常</h3><p>${esc(errMsg)}</p>`, errMsg)
+      }
+    }
+
+    return { started: true, authUrl }
+  }
+
+  /** 视图（令牌/私钥永不出宿主）。 */
+  function oauthStatus() {
+    const store = readAuth()
+    const auth = store.auth
+    const acct = store.account ?? {}
+    return {
+      pending: pending.active,
+      authUrl: pending.active ? pending.authUrl : '',
+      error: pending.error,
+      signedIn: Boolean(auth?.accessToken),
+      account: acct.nickname || acct.uid ? { nickname: acct.nickname, uid: acct.uid } : null,
+      accessTokenExpiresAt: auth?.expiresAt ?? null,
+      refreshExpiresAt: auth?.refreshExpiresAt ?? null,
+      signatureFormat: store.device?.signatureFormat ?? null,
+    }
+  }
+
+  function logout() {
+    if (pending.closeServer) { pending.closeServer(); }
+    pending.active = false
+    pending.error = ''
+    storeGeneration++ // 终止在飞 refresh：其落盘前的代际校验必然失败
+    // 设备身份保留（clientId/密钥对与该账号的设备注册绑定，重登录可复用；
+    // 只清令牌与账号）。
+    const store = readAuth()
+    writeAuth({ device: store.device })
+  }
+
+  /** 供联调探测切换签名编码（der/raw）。 */
+  function setSignatureFormat(format) {
+    if (format !== 'der' && format !== 'raw') throw new Error('signatureFormat 只支持 der|raw')
+    const store = readAuth()
+    if (store.device) {
+      store.device.signatureFormat = format
+      writeAuth(store)
+    }
+    return format
+  }
+
+  return { resolveTraeCredential, startOAuth, oauthStatus, logout, setSignatureFormat }
+}

package/providers/trae/quota.js

@@ -0,0 +1,75 @@
+/**
+ * providers/trae/quota.js — TraeWork CN 双额度池余额只读快照（设置卡用）。
+ *
+ * 端点：POST {traeAuthBaseURL}/trae/api/v2/pay/ide_user_ent_usage。
+ * 实测口径（docs/probes/trae-credits-2026-08-24T07-16-51.json）：
+ *   - req_source=0 一次调用即返回全部资源包（req_source=1 只回 endpoint=0 子集），
+ *     故只发一发；按 entitlement_base_info.available_endpoint 分池
+ *     （0=IDE 池/raw 面消耗、1=work 池/remote 面消耗，docs/reverse/trae-cloud-api.md）。
+ *   - 头组 = traeOutboundHeaders（设备指纹与登录上报一致）+ 凭证三头
+ *     （Authorization: Cloud-IDE-JWT / X-Cloudide-Token / x-ide-token）。
+ * 成本纪律：60s memoize（与 codebuddy quotaSnapshot 同口径）；永不 throw——
+ * 失败回 { error }，调用方（设置卡）据此显示「—」，绝不编造数值。
+ */
+
+import { traeOutboundHeaders } from './gateway.js'
+
+export function createTraeQuota({ settings, readAuth, oauth }) {
+  let cache = { at: 0, value: null }
+  // 单飞：并发 snapshot 共享同一在飞请求，不重复打上游。
+  let inFlight = null
+
+  async function fetchSnapshot() {
+    const s = settings()
+    const cred = await oauth.resolveTraeCredential(s)
+    if (!cred) return { error: '未登录', fetchedAt: Date.now() }
+    const token = String(cred.authorization).replace(/^Cloud-IDE-JWT\s+/, '')
+    const store = readAuth()
+    const uid = store?.account?.uid
+    const headers = {
+      ...traeOutboundHeaders(store?.device ?? null, uid, crypto.randomUUID()),
+      Authorization: `Cloud-IDE-JWT ${token}`,
+      'X-Cloudide-Token': token,
+      'x-ide-token': token,
+    }
+    const res = await fetch(`${s.traeAuthBaseURL}/trae/api/v2/pay/ide_user_ent_usage`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ require_usage: true, req_source: 0 }),
+      signal: AbortSignal.timeout(15_000),
+    })
+    const body = await res.json().catch(() => null)
+    const packs = body?.user_entitlement_pack_list
+    if (!res.ok || !Array.isArray(packs)) {
+      return { error: `code ${body?.code ?? `http ${res.status}`}`, fetchedAt: Date.now() }
+    }
+    const sum = { ide: { limit: 0, used: 0 }, work: { limit: 0, used: 0 } }
+    for (const p of packs) {
+      const ep = p?.entitlement_base_info?.available_endpoint
+      const pool = ep === 1 ? sum.work : ep === 0 ? sum.ide : null
+      if (!pool) continue
+      const limit = p?.entitlement_base_info?.quota?.credits_limit
+      const used = p?.usage?.credits_amount
+      if (typeof limit === 'number') pool.limit += limit
+      if (typeof used === 'number') pool.used += used
+    }
+    const round = (n) => Math.round(n * 100) / 100
+    const pack = (pool) => ({ limit: round(pool.limit), used: round(pool.used), remain: round(pool.limit - pool.used) })
+    return { pools: { ide: pack(sum.ide), work: pack(sum.work) }, fetchedAt: Date.now() }
+  }
+
+  function snapshot() {
+    if (cache.value && Date.now() - cache.at < 60_000) return Promise.resolve(cache.value)
+    if (inFlight) return inFlight
+    inFlight = fetchSnapshot()
+      .catch((err) => ({ error: err?.message ?? String(err), fetchedAt: Date.now() }))
+      .then((value) => {
+        cache = { at: Date.now(), value }
+        return value
+      })
+      .finally(() => { inFlight = null })
+    return inFlight
+  }
+
+  return { snapshot }
+}