mslxdff 0.1.138 → 0.1.141

package/src/providers/codearts/const.js

@@ -0,0 +1,60 @@
+// CodeArts Agent 云端 API 常量（逆向自 HITZY2002/codearts2api，源自 vscode-codebot 26.7.0）。
+// 端点契约见 docs/adr/0027-codearts-provider.md。
+
+// 盘古引擎/聊天网关（product.json snapEngineDomain，商业版 cn-north-4）。
+export const SNAP_BASE = "https://snap-access.cn-north-4.myhuaweicloud.com";
+// STS 令牌端点（refresh_token 与 client_id + DPoP 公钥 + code_verifier 三重绑定）。
+export const STS_HOST = "https://sts.cn-north-4.myhuaweicloud.com";
+// 限时福利（免费套餐）网关（模型发现 + 领取）。
+export const BENEFIT_HOST = "https://opengw.developer.huaweicloud.com";
+// OAuth authorize 入口（注意带 /portal）。
+export const PORTAL_HOST = "https://codearts.huaweicloud.com/portal";
+
+export const EP_CHAT_V2 = "/api/v2/chat/completions";
+export const EP_MODEL_BUILTIN = "/v1/model/builtin";
+export const EP_AGENT_LIST = "/v1/agent-center/agents/useragents";
+export const EP_AGENT_DETAIL = "/v1/agent-center/agents/detail";
+export const EP_BENEFIT_CONFIG = "/api/v1/gateway/config";
+export const EP_BENEFIT_CLAIM = "/api/v1/benefit/claim";
+export const EP_OAUTH_TOKENS = "/v1/oauth2/tokens";
+export const EP_LOGIN_TICKET = "/v1/login/ticket";
+export const SNAP_MANAGER_PATH = "/snap-manager";
+
+// OAuth client：官方 CodeArts Agent 插件的 uri_scheme；refresh_token 与之绑定。
+export const CLIENT_ID = "codearts-agent";
+// ticket 轮询的插件标识（逆向自 huaweicloud.authentication 扩展）。
+export const PLUGIN_NAME = "snap_AIIDE";
+export const PLUGIN_VERSION = "5.2.0";
+
+// 聊天路由头（官方 AgentKernel 形状；均进入 SDK-HMAC-SHA256 签名）。
+export function chatBaseHeaders(securityToken, traceId) {
+  return {
+    "content-type": "application/json",
+    "accept": "text/event-stream",
+    "x-auth-token": securityToken || "",
+    "x-snap-traceid": traceId,
+    "x-language": "zh-cn",
+    "app-id": "CodeAgent3.0",
+    "is_confidential": "false",
+  };
+}
+
+// 福利路由头：必须在 signRequest 之前设置（计入 SignedHeaders），否则 InferHub.002002009.404。
+export const MAAS_TYPE_HEADER = "maas_type";
+export const MAAS_BENEFIT = "benefit";
+
+// 冷启动种子：福利套餐轮换后新模型在首次发现前也按福利路由（宁多带不少带，少带即 404）。
+export const SEED_BENEFIT_MODELS = ["deepseek-v4-flash-0731", "deepseek-v4-pro-0813", "glm-5.3-flash"];
+// 内置模型种子（仅用于大小写归一，不标福利）。
+export const SEED_KNOWN_MODELS = [
+  "GLM-5.2", "GLM-5.2-ArkTS-SPARK", "GLM-5.1", "GLM-4.7",
+  "OpenPangu-2.0-Pro", "OpenPangu-2.0-Flash",
+  "Qwen3-VL-235B", "Qwen3.5-397B-A17B-VL", "Qwen3.6-27B-VL",
+];
+
+// 目录 TTL：超过则建议重新发现（对齐 codearts2api CatalogTTL）。
+export const CATALOG_TTL_MS = 60 * 60 * 1000;
+// listModels 缓存（与全仓 10min 对齐）。
+export const MODELS_CACHE_TTL_MS = 10 * 60 * 1000;
+// STS 凭证提前刷新量（对齐 codearts2api RefreshSkew 30min）。
+export const REFRESH_SKEW_MS_DEFAULT = 30 * 60 * 1000;

package/src/providers/codearts/dpop.js

@@ -0,0 +1,95 @@
+// DPoP（RFC 9449）证明 JWT：ES256 + P-256，供 STS /v1/oauth2/tokens 请求头使用。
+// refresh_token 与首次换取时的 DPoP 公钥绑定：私钥 JWK 必须随凭证持久化（d 字段），
+// 换新私钥刷新会被 STS 拒（400 invalid refresh token: InvalidDPoPHeader）。
+// 算法对齐 HITZY2002/codearts2api internal/upstream/dpop.go。
+import crypto from "node:crypto";
+
+// P-256 阶 n（用于低 S 归一化：s > n/2 → s = n - s，jose 默认低 S 兼容性更好）。
+const P256_N = 0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551n;
+
+const b64url = (data) => Buffer.from(data).toString("base64url");
+
+/** 生成可持久化的 DPoP 私钥 JWK（kty/crv/x/y/d，均 base64url 无 padding）。 */
+export function newDpopPrivateJwk() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync("ec", { namedCurve: "P-256" });
+  const pub = publicKey.export({ format: "jwk" });
+  const priv = privateKey.export({ format: "jwk" });
+  return { kty: "EC", crv: "P-256", x: pub.x, y: pub.y, d: priv.d };
+}
+
+export function dpopPublicJwk(privateJwk) {
+  return { kty: "EC", crv: "P-256", x: privateJwk?.x || "", y: privateJwk?.y || "" };
+}
+
+export function isValidDpopJwk(jwk) {
+  return !!jwk && jwk.kty === "EC" && jwk.crv === "P-256" && typeof jwk.d === "string" && jwk.d.length > 0 && !!jwk.x && !!jwk.y;
+}
+
+/** 从持久化 JWK 恢复私钥对象（非法材料直接抛错，调用方须提示重新登录）。 */
+export function dpopPrivateKey(jwk) {
+  if (!isValidDpopJwk(jwk)) throw new Error("codearts: invalid DPoP private JWK — re-login required");
+  try {
+    return crypto.createPrivateKey({ key: { ...jwk }, format: "jwk" });
+  } catch (err) {
+    throw new Error(`codearts: DPoP private JWK unusable (${err?.message || err}) — re-login required`);
+  }
+}
+
+/** 低 S 归一化：ieee-p1363 64 字节 r||s 原地修正 s（合法：ECDSA (r, n-s) 等价）。 */
+function normalizeLowS(sig) {
+  if (sig.length !== 64) return sig;
+  const s = BigInt("0x" + sig.subarray(32, 64).toString("hex"));
+  const half = P256_N >> 1n;
+  if (s <= half || s === 0n) return sig;
+  const fixed = P256_N - s;
+  Buffer.from(fixed.toString(16).padStart(64, "0"), "hex").copy(sig, 32);
+  return sig;
+}
+
+/**
+ * 生成 DPoP proof JWT。
+ * @param {object} privateJwk 持久化私钥 JWK（含 d）
+ * @param {string} htu 目标端点完整 URL（STS token 端点）
+ * @returns {string} `b64(header).b64(payload).b64(sig)` 三段 JWT
+ */
+export function signDpopProof(privateJwk, htu) {
+  const key = dpopPrivateKey(privateJwk);
+  const header = { alg: "ES256", typ: "dpop+jwt", jwk: dpopPublicJwk(privateJwk) };
+  const payload = {
+    htm: "POST",
+    htu: String(htu || ""),
+    iat: Math.floor(Date.now() / 1000),
+    jti: crypto.randomBytes(32).toString("hex"),
+  };
+  const input = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(payload))}`;
+  // 标准 JWS/ES256：对 ASCII(input) 做 SHA256+ECDSA（crypto.sign("SHA256", input)）。
+  // 注意：千万别用 sign(null, sha256(input))——OpenSSL 的 noneWithECDSA 把 digest 当整数标量，
+  // 签出来自验能过、但任何标准验签方（含 WebCrypto/华为 STS）都拒签（真机 400 STS5.1804 实锤）。
+  const sig = normalizeLowS(crypto.sign("SHA256", Buffer.from(input, "utf8"), { key, dsaEncoding: "ieee-p1363" }));
+  return `${input}.${b64url(sig)}`;
+}
+
+/** 验签辅助（测试/诊断用）：校验 JWT 签名是否与 JWK 公钥匹配。 */
+export function verifyDpopProof(proof) {
+  const parts = String(proof || "").split(".");
+  if (parts.length !== 3) return { ok: false };
+  try {
+    const header = JSON.parse(Buffer.from(parts[0], "base64url").toString("utf8"));
+    const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+    const sig = Buffer.from(parts[2], "base64url");
+    const pub = crypto.createPublicKey({ key: { kty: "EC", crv: "P-256", x: header.jwk.x, y: header.jwk.y }, format: "jwk" });
+    const input = Buffer.from(`${parts[0]}.${parts[1]}`, "utf8");
+    const s = BigInt("0x" + sig.subarray(32, 64).toString("hex"));
+    // 标准 JWS/ES256 验签（与签名端对称；dsaEncoding 必须显式 ieee-p1363，node 默认 DER）。
+    const vopts = { dsaEncoding: "ieee-p1363" };
+    const ok = crypto.verify("SHA256", input, { key: pub, ...vopts }, sig)
+      || (s > P256_N >> 1n && crypto.verify("SHA256", input, { key: pub, ...vopts }, (() => {
+        const alt = Buffer.from(sig);
+        Buffer.from((P256_N - s).toString(16).padStart(64, "0"), "hex").copy(alt, 32);
+        return alt;
+      })()));
+    return { ok, header, payload };
+  } catch {
+    return { ok: false };
+  }
+}

package/src/providers/codearts/index.js

@@ -0,0 +1,160 @@
+// codearts 供应商工厂：注册表入口（registry.js → createCodeartsProvider）。
+// key = 凭证 blob（JSON 字符串，一华为账号一条，见 auth-pool.js）；多账号 keyring 自动轮转。
+import { createKeyRing } from "../keyring.js";
+import { loadProviderKeys, loadProviderBaseUrl, saveProviderConfig } from "../../state.js";
+import { getUndici, createAgent, envInt, collectApiKeysGeneric } from "../base.js";
+import { compatFetch } from "../../compat.js";
+import { logDir } from "../../logs.js";
+import { join } from "node:path";
+import { SNAP_BASE, MODELS_CACHE_TTL_MS } from "./const.js";
+import { createAuthPool } from "./auth-pool.js";
+import { createCatalog, discoverAccountModels } from "./models.js";
+import { createChatService } from "./chat.js";
+
+const { UndiciFetch } = getUndici();
+
+function resolveBaseUrl(baseUrl) {
+  if (baseUrl) return String(baseUrl).trim().replace(/\/+$/, "");
+  const env = loadProviderBaseUrl("codearts");
+  return env || SNAP_BASE;
+}
+
+export function createCodeartsProvider({
+  id = "codearts",
+  baseUrl,
+  apiKeys,
+  apiKey,
+  chatPath,
+  stsHost,
+  benefitHost,
+  snapBase,
+  connectTimeoutMs = envInt("MSLXDFF_CODEARTS_TIMEOUT_MS", 30_000),
+  cooldownMs = envInt("MSLXDFF_CODEARTS_COOLDOWN_MS", 30_000),
+  autoClaim = process.env.MSLXDFF_CODEARTS_AUTO_CLAIM !== "0",
+  fetchImpl,
+  file,
+  clock = Date.now,
+} = {}) {
+  if (id !== "codearts") throw new Error(`codearts provider id mismatch: ${id}`);
+  const resolvedBase = snapBase || resolveBaseUrl(baseUrl);
+  if (!fetchImpl) fetchImpl = UndiciFetch || compatFetch;
+  const chatSvcBase = resolvedBase;
+
+  const rawKeys = collectApiKeysGeneric(id, apiKeys, apiKey, (pid) => loadProviderKeys(pid, file ? { file } : {}));
+  const allKeys = [...new Set(rawKeys.map((k) => String(k).trim()).filter(Boolean))];
+  const ring = createKeyRing(allKeys, { cooldownMs });
+
+  // 刷新轮转写回：原位替换 providerConfigs.codearts.keys 里的旧 blob + ring/pool 重排
+  const saveFn = async ({ oldBlob, newBlob }) => {
+    try {
+      const cur = loadProviderKeys(id, file ? { file } : {});
+      const idx = cur.indexOf(oldBlob);
+      if (idx < 0) return;
+      const next = [...cur];
+      next[idx] = newBlob;
+      saveProviderConfig(id, { baseUrl: loadProviderBaseUrl(id, file ? { file } : {}) || resolvedBase, keys: next }, file ? { file } : {});
+      ring.replace(oldBlob, newBlob);
+      pool.replace(oldBlob, newBlob);
+    } catch {}
+  };
+  const pool = createAuthPool({ keys: allKeys, fetchImpl, stsHost, clock, saveFn });
+  const catalog = createCatalog();
+
+  let agent = null; let dispatcher = null;
+  try {
+    const a = createAgent({
+      keepAliveTimeout: envInt("MSLXDFF_CODEARTS_KEEPALIVE_TIMEOUT", 30_000),
+      keepAliveMaxTimeout: envInt("MSLXDFF_CODEARTS_KEEPALIVE_MAX_TIMEOUT", 60_000),
+      connections: envInt("MSLXDFF_CODEARTS_KEEPALIVE_CONNECTIONS", 20),
+    });
+    agent = a.agent;
+    dispatcher = a.dispatcher;
+  } catch {}
+
+  const chatSvc = createChatService({
+    id, baseUrl: chatSvcBase, chatPath, fetchImpl, dispatcher, authPool: pool, catalog, connectTimeoutMs, clock,
+  });
+
+  async function chat(body, opts = {}) {
+    if (!ring.size) throw new Error("codearts: missing credential — run: mslxdff -provider codearts login");
+    return chatSvc.runChat(body, ring, opts);
+  }
+  async function chatWithKeys(body, keys, opts = {}) {
+    const blobs = (keys || []).filter((k) => typeof k === "string" && k.trim().startsWith("{"));
+    if (!blobs.length) throw new Error("codearts: shared keys are not valid credential blobs");
+    const tmpRing = createKeyRing(blobs, { cooldownMs });
+    const tmpPool = createAuthPool({ keys: blobs, fetchImpl, stsHost, clock }); // 借用凭据不写回本节点
+    const tmpSvc = createChatService({ id, baseUrl: chatSvcBase, chatPath, fetchImpl, dispatcher: null, authPool: tmpPool, catalog, connectTimeoutMs, clock });
+    return tmpSvc.runChat(body, tmpRing, opts);
+  }
+
+  // 三路发现（主账号）；结果写目录（benefit 判定按账号隔离）
+  let discovering = null;
+  async function discover(force = false) {
+    const primary = pool.pickPrimary();
+    if (!primary) throw new Error("codearts: no alive account — run: mslxdff -provider codearts login");
+    if (!force && !catalog.isStale(primary.userId, clock())) return catalog.accountModels(primary.userId);
+    if (discovering) return discovering;
+    discovering = (async () => {
+      try {
+        const account = await pool.getCredential(primary.blob);
+        const { models, builtinOk, benefitOk } = await discoverAccountModels({ account, snapBase: resolvedBase, benefitHost, autoClaim, fetchImpl });
+        catalog.setAccount(account.userId, models, { keepBenefit: builtinOk && !benefitOk, now: clock() });
+        return models;
+      } finally {
+        discovering = null;
+      }
+    })();
+    return discovering;
+  }
+
+  let modelsCache = { at: 0, list: [] };
+  async function listModels() {
+    if (clock() - modelsCache.at < MODELS_CACHE_TTL_MS && modelsCache.list.length) return modelsCache.list;
+    let models;
+    try {
+      models = await discover();
+    } catch {
+      models = catalog.accountModels(pool.pickPrimary()?.userId || "");
+    }
+    if (!models.length) return [];
+    const list = models.map((m) => ({
+      id: `codearts/${m.id}`,
+      object: "model",
+      name: m.name || m.id,
+      ...(m.contextWindow ? { maxInputTokens: m.contextWindow } : {}),
+      ...(m.maxTokens ? { maxOutputTokens: m.maxTokens } : {}),
+      ...(m.benefit ? { tags: ["free:benefit"] } : {}),
+    }));
+    modelsCache = { at: clock(), list };
+    return list;
+  }
+
+  async function preheat() {
+    if (!ring.size) return { ok: false, skipped: true };
+    try {
+      await discover();
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, error: String(err?.message || err).slice(0, 120) };
+    }
+  }
+
+  async function close() { if (agent?.close) try { await agent.close(); } catch {} }
+
+
+  return {
+    id,
+    chat,
+    chatWithKeys,
+    listModels,
+    preheat,
+    close,
+    agent,
+    keyRing: ring,
+    baseUrl: resolvedBase,
+    _pool: pool,
+    _catalog: catalog,
+    _snapshotPath: join(logDir(), "codearts-models.json"),
+  };
+}

package/src/providers/codearts/login.js

@@ -0,0 +1,214 @@
+// codearts 浏览器登录：OAuth2 PKCE + DPoP，双通道取凭证：
+//   1) 本地回调 server（portal 307 → ?secret=... → ?code=...）→ 授权码换 token
+//   2) ticket 轮询（无浏览器机器：任意设备打开链接后，凭 ticket_id+secret 轮询下发）
+// 凭证落盘 providerConfigs.codearts.keys（blob，见 auth-pool.js），并默认放行模型目录。
+import crypto from "node:crypto";
+import http from "node:http";
+import { SNAP_BASE, STS_HOST, PORTAL_HOST, SNAP_MANAGER_PATH, EP_LOGIN_TICKET, CLIENT_ID, PLUGIN_NAME, PLUGIN_VERSION } from "./const.js";
+import { exchangeAuthorizationCode, normalizeTokenResponse } from "./sts.js";
+import { newDpopPrivateJwk } from "./dpop.js";
+import { signRequest } from "./sign.js";
+import { compatFetch } from "../../compat.js";
+
+const hex = (n) => crypto.randomBytes(n).toString("hex");
+const b64url = (b) => Buffer.from(b).toString("base64url");
+
+export function buildLoginState({ clientId = CLIENT_ID } = {}) {
+  const verifier = b64url(crypto.randomBytes(64));
+  const challenge = b64url(crypto.createHash("sha256").update(verifier, "utf8").digest());
+  return { clientId, ticketId: hex(16), secret: hex(16), codeVerifier: verifier, codeChallenge: challenge, dpopJwk: newDpopPrivateJwk() };
+}
+
+export function buildAuthorizeUrl({ state, port }) {
+  const q = new URLSearchParams({
+    theme: "2",
+    locale: "zh-cn",
+    uri_scheme: state.clientId,
+    client_id: state.clientId,
+    port: String(port ?? ""),
+    code_challenge: state.codeChallenge,
+    code_challenge_method: "SHA-256",
+    ticket_id: state.ticketId,
+    "plugin-name": PLUGIN_NAME,
+    "plugin-version": PLUGIN_VERSION,
+  });
+  return `${PORTAL_HOST}/authorize?${q.toString()}`;
+}
+
+function startCallbackServer() {
+  return new Promise((resolve, reject) => {
+    const hits = [];
+    const waiters = new Set();
+    const srv = http.createServer((req, res) => {
+      const u = new URL(req.url, "http://127.0.0.1");
+      const hit = Object.fromEntries(u.searchParams.entries());
+      hits.push(hit);
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end("<html><body><h3>CodeArts 登录回调已收到</h3>可关闭此页面，回到 mslxdff 终端查看结果。</body></html>");
+      for (const w of waiters) w(hit);
+      waiters.clear();
+    });
+    srv.on("error", reject);
+    srv.listen(0, "127.0.0.1", () => resolve({
+      port: srv.address().port,
+      nextHit: (timeoutMs) => new Promise((r) => {
+        if (hits.length) return r(hits.shift());
+        const t = setTimeout(() => { waiters.delete(w); r(null); }, timeoutMs);
+        const w = (hit) => { clearTimeout(t); r(hit); };
+        waiters.add(w);
+      }),
+      close: () => { try { srv.close(); } catch {} },
+    }));
+  });
+}
+
+// 兜底通道：无浏览器机器上，任意设备完成授权后凭 ticket_id+secret 轮询拿凭证。
+export async function pollTicket({ state, snapBase = SNAP_BASE, fetchImpl, timeoutMs = 5 * 60_000, intervalMs = 2000, log = () => {}, signal } = {}) {
+  const doFetch = fetchImpl || compatFetch;
+  const url = `${snapBase}${SNAP_MANAGER_PATH}${EP_LOGIN_TICKET}?ticket_id=${encodeURIComponent(state.ticketId)}&secret=${encodeURIComponent(state.secret)}`;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline && !signal?.aborted) {
+    try {
+      const res = await doFetch(url, { headers: { "plugin-name": PLUGIN_NAME, "plugin-version": PLUGIN_VERSION } });
+      const raw = await res.text().catch(() => "");
+      if (res.ok) {
+        const account = normalizeTokenResponse(JSON.parse(raw));
+        if (account) return account;
+      }
+    } catch { /* 未下发/网络抖动：继续轮询 */ }
+    await new Promise((r) => {
+      const t = setTimeout(r, intervalMs);
+      signal?.addEventListener("abort", () => { clearTimeout(t); r(); }, { once: true });
+    });
+    log(`等待授权下发…（ticket 轮询中，剩余 ${Math.max(0, Math.round((deadline - Date.now()) / 1000))}s）`);
+  }
+  return null;
+}
+
+/**
+ * 身份回填：生产 exchange 响应 user_id 常为空（portal 只回 code），空身份会让
+ * 登录去重把不同账号当同一账号替换。对齐 codearts2api lookupIdentity（先 STS
+ * caller-identity，再 snap current/user，最后 refresh_token JWT sub 兜底）。
+ * @returns {{userId, userName, domainId}|null}
+ */
+export async function lookupIdentity({ account, stsHost = STS_HOST, snapBase = SNAP_BASE, fetchImpl, log = () => {} } = {}) {
+  const doFetch = fetchImpl || compatFetch;
+  const cred = { accessKeyId: account?.accessKeyId, secretAccessKey: account?.secretAccessKey, securityToken: account?.securityToken };
+  async function signedGet(url) {
+    const { headers } = signRequest({ method: "GET", url, headers: { "content-type": "application/json", "x-language": "zh-cn" }, body: "", cred });
+    const res = await doFetch(url, { method: "GET", headers });
+    const raw = await res.text().catch(() => "");
+    if (res.status >= 400) throw new Error(`identity http ${res.status}: ${String(raw).slice(0, 120)}`);
+    return JSON.parse(raw);
+  }
+  // 1) STS caller-identity：{account_id, principal_id, principal_urn}（name 取 urn ":user:" 尾段）
+  try {
+    const j = await signedGet(`${stsHost}/v5/caller-identity`);
+    const urn = String(j.principal_urn || "");
+    const tail = urn.includes(":user:") ? urn.slice(urn.lastIndexOf(":user:") + 6) : "";
+    if (j.principal_id || tail) return { userId: String(j.principal_id || ""), userName: tail, domainId: String(j.account_id || "") };
+  } catch (err) { log(`身份查询（caller-identity）失败，换备用接口：${String(err?.message || err).slice(0, 120)}`); }
+  // 2) snap current/user：{user_id, user_name, domain_id}
+  try {
+    const j = await signedGet(`${snapBase}/v1/current/user`);
+    if (j.user_id || j.user_name) return { userId: String(j.user_id || ""), userName: String(j.user_name || ""), domainId: String(j.domain_id || "") };
+  } catch (err) { log(`身份查询（current/user）失败：${String(err?.message || err).slice(0, 120)}`); }
+  // 3) refresh_token JWT sub 兜底
+  try {
+    const payload = JSON.parse(Buffer.from(String(account?.refreshToken || "").split(".")[1] || "", "base64url").toString("utf8"));
+    if (payload?.sub) return { userId: String(payload.sub), userName: "", domainId: "" };
+  } catch {}
+  return null;
+}
+
+/**
+ * 跑完整登录流程。
+ * @param {object} [opts] { clientId, snapBase, stsHost, fetchImpl, timeoutMs, log, openBrowser }
+ * @returns {{account, redirectUri}} 成功返回账号（含 refreshToken/AK/SK/dpopJwk 等）
+ */
+export async function runCodeartsLogin({
+  clientId = CLIENT_ID,
+  snapBase = SNAP_BASE,
+  stsHost = STS_HOST,
+  fetchImpl,
+  timeoutMs = 5 * 60_000,
+  log = console.log,
+} = {}) {
+  const state = buildLoginState({ clientId });
+  const server = await startCallbackServer();
+  const redirectUri = `http://127.0.0.1:${server.port}/oauth/callback`;
+  const authorizeUrl = buildAuthorizeUrl({ state, port: server.port });
+  log("");
+  log("请用浏览器打开下面的链接并登录华为云（授权 CodeArts Agent）：");
+  log("");
+  log(`  ${authorizeUrl}`);
+  log("");
+  log(`本机回调：${redirectUri}（回调通道优先；ticket 轮询后台兜底，谁先到用谁）`);
+
+  const deadline = Date.now() + timeoutMs;
+  const ticketAbort = new AbortController();
+  let ticketPromise = null;
+  try {
+    while (Date.now() < deadline) {
+      const hit = await server.nextHit(Math.min(3000, deadline - Date.now()));
+      // 通道 1：浏览器回调带 code → 直接换 token（谁先到用谁；portal 带 port 参数走这路，ticket 不会下发）
+      if (hit?.code) {
+        log("已收到授权码，正在换取 STS 凭证…");
+        const account = await exchangeAuthorizationCode({
+          code: hit.code,
+          verifier: state.codeVerifier,
+          redirectUri,
+          clientId: state.clientId,
+          dpopJwk: state.dpopJwk,
+          fetchImpl,
+          stsHost,
+        });
+        // portal 回调只回 code 不带身份（生产 exchange 响应 user_id 常为空）：
+        // 空身份会导致登录去重把不同账号当同一账号替换，必须落盘前补调身份接口
+        if (!account.userId || !account.userName) {
+          log("正在查询账号身份…");
+          const id = await lookupIdentity({ account, fetchImpl, log }).catch(() => null);
+          if (id) {
+            if (id.userId) account.userId = id.userId;
+            if (id.userName) account.userName = id.userName;
+            if (id.domainId) account.domainId = id.domainId;
+          }
+        }
+        ticketAbort.abort(); // 回调已赢，停掉后台 ticket 轮询
+        return { account, state, redirectUri };
+      }
+      // 授权失败（用户拒绝等）：把上游原因说人话抛出
+      if (hit?.error) throw new Error(`codearts authorize failed: ${hit.error}${hit.error_description ? ` — ${hit.error_description}` : ""}`);
+      // 通道 2：首次（portal 307 带 secret 一跳，或 3s 无回调）→ 后台起 ticket 轮询
+      // 关键：绝不 await 阻塞主循环——否则浏览器 code 回调无人消费，永远轮询（真机首登实测死锁）
+      if ((hit?.secret || !hit) && !ticketPromise) {
+        ticketPromise = pollTicket({ state, snapBase, fetchImpl, timeoutMs: deadline - Date.now(), log, signal: ticketAbort.signal }).catch(() => null);
+      }
+      // ticket 后台结果非阻塞查询：未决立即返回 null，主循环继续收回调
+      if (ticketPromise) {
+        const acc = await Promise.race([ticketPromise, Promise.resolve(null)]);
+        if (acc) return { account: acc, state, redirectUri };
+      }
+    }
+  } finally {
+    server.close();
+  }
+  throw new Error("codearts login timed out — 未在时限内拿到授权（可重跑：mslxdff -provider codearts login）");
+}
+
+/** 账号对象 → 可持久化 blob 字符串（与 auth-pool.blobFromAccount 同形状）。 */
+export function accountToBlob(account, { codeVerifier, dpopJwk, clientId = CLIENT_ID }) {
+  return JSON.stringify({
+    userId: account.userId,
+    userName: account.userName,
+    domainId: account.domainId,
+    refreshToken: account.refreshToken,
+    clientId,
+    codeVerifier,
+    dpopJwk,
+    accessKeyId: account.accessKeyId,
+    secretAccessKey: account.secretAccessKey,
+    securityToken: account.securityToken,
+    expiration: account.expiration,
+  });
+}