@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/core/http.js

@@ -0,0 +1,903 @@
+// 唯一的出网层。
+//
+// 所有请求都从这里出去，所以"每个请求该带什么"只有一处实现：
+//
+// - **固定 User-Agent `xinhe-oa-cli/1`**（不含版本号）。服务端把 refresh 绑在
+//   `HMAC(UA + X-Device-Id)` 上，UA 里出现版本号会让用户一升级 CLI 就
+//   `auth.device_mismatch`、被迫重新短信登录。版本号走 `X-CLI-Version`。
+// - **每个请求带 `X-Device-Id`**（契约 §4）。
+// - **每个请求带 `X-Request-Id`**：服务端会原样回显（`app/api/deps.py` 只接受
+//   `[A-Za-z0-9_.:-]` 且 ≤64 字符），于是 CLI 的 `meta.request_id` 与服务端审计里的
+//   那一行是同一个值。
+// - 写操作带 `Idempotency-Key`（可被 `--idempotency-key` 覆盖）。
+// - 429 / 5xx / 连接失败**退避重试**。
+//
+// ## 为什么用 `node:http` / `node:https` 而不是 fetch / undici
+//
+// 1. **代理**：`fetch` 直接把环境变量里的 `*_PROXY` 当空气（undici 要显式给
+//    `ProxyAgent`），而客户机器上 `ALL_PROXY=socks5h://127.0.0.1:7890` 是常态。
+//    `node:http` 允许我们自己指定 `createConnection`，于是 HTTP 代理（CONNECT /
+//    绝对 URI）与 SOCKS5 都能实现，而且**零依赖** —— 一个要装进客户机器的
+//    CLI，少一个依赖就少一份供应链风险。
+// 2. **逐跳控制**：重定向、超时、重试要自己说了算（fetch 的 redirect/超时语义
+//    与这里要的"重试的是同一个 request_id"对不上）。
+//
+// ## 代理（客户机器上最容易踩的坑）
+//
+// 环境里常见 `ALL_PROXY=socks5h://127.0.0.1:7890`（公司出口代理）。三件事：
+//
+// 1. **SOCKS5 要自己实现**（见 `openSocks5`）：没有依赖可用；
+// 2. **本机与私网地址永远直连**（回环、`.local`、RFC1918、link-local）：
+//    隔着代理去连 `127.0.0.1:8102` 必然连不上，而这是本地验收最常见的场景；
+// 3. `config --set proxy=none`（或 `XINHE_OA_PROXY=none`）让客户在**内网直连**时
+//    彻底关掉代理 —— 有些内网代理配置会静默把请求送进黑洞。
+
+import http from 'node:http';
+import https from 'node:https';
+import net from 'node:net';
+import tls from 'node:tls';
+
+import { classify, CliError, Kind, loginHint } from './error.js';
+import { ProxyMode } from './config.js';
+import { newRequestId } from './util.js';
+// 重试与告警都往 stderr 走（`output.js` 的 `warn`）：**stdout 只放结果**。
+import { warn } from './output.js';
+import { VERSION } from '../version.js';
+
+/** 固定 UA：**不含版本号**（见模块说明）。 */
+export const USER_AGENT = 'xinhe-oa-cli/1';
+/** 服务端把 refresh 的指纹绑在这个头 + UA 上。 */
+export const DEVICE_HEADER = 'X-Device-Id';
+/** 客户端自带的请求 id（服务端校验字符集后原样沿用）。 */
+export const REQUEST_ID_HEADER = 'X-Request-Id';
+/** 版本头（UA 里刻意不带版本号）。 */
+export const VERSION_HEADER = 'X-CLI-Version';
+
+/** 默认超时：连接 10s、整次请求 60s（`--timeout` 可覆盖整次请求那个）。 */
+export const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
+export const DEFAULT_TIMEOUT_MS = 60_000;
+/** 最多重试几次（不含首次）。 */
+const MAX_RETRIES = 3;
+/** 重定向跟随上限（reqwest 侧是 `Policy::limited(5)`）。 */
+const MAX_REDIRECTS = 5;
+
+/** 代理策略判定结果（纯函数，便于单测）。 */
+export const ProxyPlan = Object.freeze({
+  /** 本机/私网地址：直连，不经过任何代理。 */
+  DirectLoopback: 'direct_loopback',
+  /** 尊重环境代理。 */
+  System: 'system',
+  /** 用户显式关掉代理。 */
+  DirectByChoice: 'direct_by_choice',
+});
+
+/** `host` 是不是**不该走代理**的地址（回环 / 私网 / link-local / `.local`）。 */
+export function isNonProxyHost(host) {
+  const trimmed = String(host ?? '').trim().replace(/^\[/, '').replace(/\]$/, '');
+  if (trimmed.length === 0) return false;
+  const lowered = trimmed.toLowerCase();
+  if (lowered === 'localhost' || lowered.endsWith('.localhost') || lowered.endsWith('.local')) {
+    return true;
+  }
+  // 主机名里没有点又只有数字/字母 → 内网短名（如 `api`、`oa-server`），按直连处理。
+  if (
+    !lowered.includes('.') &&
+    !lowered.includes(':') &&
+    net.isIP(lowered) === 0
+  ) {
+    return true;
+  }
+  const family = net.isIP(lowered);
+  if (family === 4) {
+    const parts = lowered.split('.').map((part) => Number(part));
+    const [a, b] = parts;
+    if (a === 127 || a === 10 || a === 0) return true;
+    if (a === 172 && b >= 16 && b <= 31) return true;
+    if (a === 192 && b === 168) return true;
+    if (a === 169 && b === 254) return true;
+    return false;
+  }
+  if (family === 6) {
+    const normalized = normalizeIpv6(lowered);
+    if (normalized === '::1' || normalized === '::') return true;
+    // fc00::/7（唯一本地地址）
+    const firstGroup = normalized.split(':')[0] ?? '';
+    if (firstGroup.length > 0) {
+      const value = Number.parseInt(firstGroup.padStart(4, '0'), 16);
+      if (Number.isFinite(value) && (value & 0xfe00) === 0xfc00) return true;
+    }
+    return false;
+  }
+  return false;
+}
+
+function normalizeIpv6(address) {
+  // 只做够用的规范化：处理 `0:0:0:0:0:0:0:1` 与 `::1` 这两种写法。
+  if (address === '0:0:0:0:0:0:0:1') return '::1';
+  if (address === '0:0:0:0:0:0:0:0') return '::';
+  return address;
+}
+
+/** 给定 base_url 与代理策略，决定这一次怎么出网。 */
+export function proxyPlan(baseUrl, mode) {
+  const host = hostOf(baseUrl) ?? '';
+  if (isNonProxyHost(host)) return ProxyPlan.DirectLoopback;
+  return mode === ProxyMode.None ? ProxyPlan.DirectByChoice : ProxyPlan.System;
+}
+
+/** 从 URL 里取主机名（只取 host 这一段，不做完整 URL 解析）。 */
+export function hostOf(raw) {
+  const text = String(raw ?? '');
+  const withoutScheme = text.includes('://') ? text.slice(text.indexOf('://') + 3) : text;
+  let authority = withoutScheme.split(/[/?#]/)[0] ?? '';
+  const at = authority.lastIndexOf('@');
+  if (at >= 0) authority = authority.slice(at + 1);
+  if (authority.startsWith('[')) {
+    const end = authority.indexOf(']');
+    return end > 0 ? authority.slice(1, end) : null;
+  }
+  const host = authority.split(':')[0] ?? '';
+  return host.length === 0 ? null : host;
+}
+
+/** 把 base_url 规范化：补协议、去尾斜杠。 */
+export function normalizeBaseUrl(raw) {
+  const trimmed = String(raw ?? '').trim().replace(/\/+$/, '');
+  return trimmed.includes('://') ? trimmed : `http://${trimmed}`;
+}
+
+// ---------------------------------------------------------------------------
+// 环境代理解析（Node 不像 reqwest 那样自动读 *_PROXY，得自己来）
+// ---------------------------------------------------------------------------
+function envValue(...names) {
+  for (const name of names) {
+    const value = process.env[name];
+    if (value && value.trim().length > 0) return value.trim();
+  }
+  return null;
+}
+
+/** NO_PROXY / no_proxy 匹配（支持 `*`、后缀匹配、host:port、CIDR 的常见写法）。 */
+export function noProxyMatch(host, noProxyRaw) {
+  const raw = noProxyRaw ?? envValue('NO_PROXY', 'no_proxy');
+  if (!raw) return false;
+  const target = String(host ?? '').toLowerCase();
+  if (target.length === 0) return false;
+  for (const entryRaw of raw.split(',')) {
+    const entry = entryRaw.trim().toLowerCase();
+    if (entry.length === 0) continue;
+    if (entry === '*') return true;
+    const withoutPort = entry.includes(':') && net.isIP(entry) === 0 ? entry.split(':')[0] : entry;
+    const candidate = withoutPort.replace(/^\./, '');
+    const bare = target.includes(':') ? target.split(':')[0] : target;
+    if (bare === candidate || bare.endsWith(`.${candidate}`)) return true;
+  }
+  return false;
+}
+
+/**
+ * 解析要用的代理 URL。
+ *
+ * 优先级（与 curl 的习惯一致）：目标 https → `HTTPS_PROXY`；否则 `HTTP_PROXY`；
+ * 都没有再退 `ALL_PROXY`。命中的代理若被 `NO_PROXY` 排除则直连。
+ */
+export function resolveProxyUrl(targetUrl, mode) {
+  if (mode === ProxyMode.None) return null;
+  const parsed = new URL(targetUrl);
+  const isHttps = parsed.protocol === 'https:';
+  const candidate = isHttps
+    ? envValue('HTTPS_PROXY', 'https_proxy', 'ALL_PROXY', 'all_proxy')
+    : envValue('HTTP_PROXY', 'http_proxy', 'ALL_PROXY', 'all_proxy');
+  if (!candidate) return null;
+  if (noProxyMatch(parsed.hostname)) return null;
+  if (candidate.includes('://')) return candidate;
+  return `http://${candidate}`;
+}
+
+/** 一次请求的可选修饰。 */
+export function requestSpec(init = {}) {
+  return {
+    idempotencyKey: init.idempotencyKey ?? null,
+    body: init.body ?? null,
+    multipart: init.multipart ?? null,
+    query: init.query ?? [],
+    timeout: init.timeout ?? null,
+  };
+}
+
+/** multipart 表单（只支持文本字段 + 一个文件，够 `POST /attachments` 用）。 */
+export function multipartBody(fields = [], file = null) {
+  return { fields, file };
+}
+
+/** 一次请求要带的认证方式。 */
+export const Auth = Object.freeze({
+  none: () => ({ kind: 'none', token: null }),
+  bearer: (token) => ({ kind: 'bearer', token }),
+});
+
+// ---------------------------------------------------------------------------
+// 客户端
+// ---------------------------------------------------------------------------
+export class Http {
+  /**
+   * @param {string} baseUrl
+   * @param {string} mode ProxyMode.System | ProxyMode.None
+   * @param {string} deviceId
+   * @param {number|null} timeoutMs 整次请求超时（毫秒）
+   */
+  constructor(baseUrl, mode, deviceId, timeoutMs = null) {
+    this.baseUrl = normalizeBaseUrl(baseUrl);
+    this.deviceId = deviceId ?? '';
+    this.mode = mode;
+    this.plan = proxyPlan(this.baseUrl, mode);
+    this.timeoutMs = timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+
+  /** 这次出网走的是哪条路（`doctor` / `config --show` 用它解释代理行为）。 */
+  proxyPlan() {
+    return this.plan;
+  }
+
+  timeout() {
+    return this.timeoutMs;
+  }
+
+  /**
+   * 发一次请求。`command` 只用于错误提示（不进 URL）。
+   *
+   * 重试的前提：**每次尝试共用同一个 request_id** —— 重试的是"同一个请求"，
+   * 服务端审计里因此只有一行（而不是三次失败的样子）。
+   */
+  async send(method, path, auth, spec, command) {
+    const url = `${this.baseUrl}${path}`;
+    const requestId = newRequestId();
+    let attempt = 0;
+    for (;;) {
+      let parsed;
+      try {
+        parsed = await this.attemptWithRedirects({
+          method,
+          url,
+          auth,
+          spec,
+          requestId,
+          redirects: 0,
+        });
+      } catch (err) {
+        if (err instanceof CliError) {
+          // 非 JSON 响应（网关/代理页）——退避后重试一次是合理的。
+          if (attempt < MAX_RETRIES) {
+            const wait = backoff(attempt, null);
+            warn(
+              `${command} 收到非 JSON 响应（${err.message}），${(wait / 1000).toFixed(1)}s 后重试`,
+            );
+            await sleep(wait);
+            attempt += 1;
+            continue;
+          }
+          throw err;
+        }
+        const retryable = err.retryable === true;
+        if (retryable && attempt < MAX_RETRIES) {
+          const wait = backoff(attempt, null);
+          warn(
+            `${command} 网络故障（${shortReason(err)}），${(wait / 1000).toFixed(1)}s 后重试（第 ${attempt + 1}/${MAX_RETRIES} 次）`,
+          );
+          await sleep(wait);
+          attempt += 1;
+          continue;
+        }
+        throw networkError(url, err, requestId);
+      }
+
+      if (shouldRetryStatus(parsed.status) && attempt < MAX_RETRIES) {
+        const wait = backoff(attempt, retryAfter(parsed));
+        warn(
+          `服务端返回 ${parsed.status}，${(wait / 1000).toFixed(1)}s 后重试（第 ${attempt + 1}/${MAX_RETRIES} 次）`,
+        );
+        await sleep(wait);
+        attempt += 1;
+        continue;
+      }
+      if (parsed.status >= 200 && parsed.status < 300) return parsed;
+      throw this.serverError(parsed);
+    }
+  }
+
+  /** 单次尝试（含最多 5 跳重定向）。 */
+  async attemptWithRedirects({ method, url, auth, spec, requestId, redirects }) {
+    const response = await this.attempt({ method, url, auth, spec, requestId });
+    const location = headerValue(response.headers, 'location');
+    if (isRedirect(response.status) && location && redirects < MAX_REDIRECTS) {
+      // 5xx/429 之外的重定向：按 RFC 语义跟随（301/302/303 对非 GET 降级为 GET）。
+      const next = new URL(location, url).toString();
+      const downgrade = response.status === 303 || response.status === 301 || response.status === 302;
+      const nextMethod = downgrade && method !== 'GET' && method !== 'HEAD' ? 'GET' : method;
+      const nextSpec = nextMethod === method ? spec : requestSpec({ ...spec, body: null });
+      return this.attemptWithRedirects({
+        method: nextMethod,
+        url: next,
+        auth,
+        spec: nextSpec,
+        requestId,
+        redirects: redirects + 1,
+      });
+    }
+    return this.ingest(response, requestId);
+  }
+
+  /** 真正的一次 HTTP 往返（拿回原始响应）。 */
+  attempt({ method, url, auth, spec, requestId }) {
+    const target = new URL(url);
+    const isHttps = target.protocol === 'https:';
+    const headers = {
+      'user-agent': USER_AGENT,
+      accept: 'application/json',
+      [REQUEST_ID_HEADER.toLowerCase()]: requestId,
+      [VERSION_HEADER.toLowerCase()]: VERSION,
+    };
+    if (this.deviceId.length > 0) headers[DEVICE_HEADER.toLowerCase()] = this.deviceId;
+    if (auth?.kind === 'bearer' && auth.token) {
+      headers.authorization = `Bearer ${auth.token}`;
+    }
+    if (spec.idempotencyKey) headers['idempotency-key'] = spec.idempotencyKey;
+
+    const search = new URLSearchParams();
+    for (const [key, value] of spec.query) search.append(key, value);
+    if (search.toString().length > 0) target.search = search.toString();
+
+    let payload = null;
+    if (spec.multipart) {
+      const built = buildMultipart(spec.multipart);
+      payload = built.payload;
+      headers['content-type'] = built.contentType;
+    } else if (spec.body !== null && spec.body !== undefined) {
+      payload = Buffer.from(JSON.stringify(spec.body), 'utf8');
+      headers['content-type'] = 'application/json';
+    }
+    if (payload) headers['content-length'] = String(payload.length);
+
+    const timeoutMs = spec.timeout ?? this.timeoutMs;
+    const plan = this.plan;
+    const proxyUrl =
+      plan === ProxyPlan.System ? resolveProxyUrl(target.toString(), this.mode) : null;
+
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let timeoutHandle = null;
+      let connectTimeoutHandle = null;
+
+      const fail = (err) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeoutHandle);
+        clearTimeout(connectTimeoutHandle);
+        reject(err);
+      };
+
+      const onResponse = (response) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeoutHandle);
+        clearTimeout(connectTimeoutHandle);
+        const chunks = [];
+        response.on('data', (chunk) => chunks.push(chunk));
+        response.on('end', () => {
+          resolve({
+            status: response.statusCode ?? 0,
+            headers: response.headers,
+            body: Buffer.concat(chunks),
+          });
+        });
+        response.on('error', (err) => fail(markNetwork(err)));
+      };
+
+      // 超时：整次请求（含建连、发送、收完响应体）。
+      timeoutHandle = setTimeout(() => {
+        const err = new Error('请求超时');
+        err.code = 'ETIMEDOUT';
+        err.retryable = true;
+        err.timedOut = true;
+        fail(err);
+      }, timeoutMs);
+      if (typeof timeoutHandle.unref === 'function') timeoutHandle.unref();
+
+      const requestOptions = {
+        method,
+        headers,
+        // 私网/回环与 `proxy=none` 都走这条：**完全不读**环境里的 *_PROXY。
+        agent: false,
+      };
+
+      const handleRequest = (req) => {
+        req.on('error', (err) => fail(markNetwork(err)));
+        if (payload) req.write(payload);
+        req.end();
+      };
+
+      if (proxyUrl) {
+        const proxy = new URL(proxyUrl);
+        if (proxy.protocol === 'socks5:' || proxy.protocol === 'socks5h:' || proxy.protocol === 'socks4:') {
+          const proxyPort = Number(proxy.port || 1080);
+          openSocks5({
+            proxyHost: proxy.hostname,
+            proxyPort,
+            targetHost: target.hostname,
+            targetPort: Number(target.port || (isHttps ? 443 : 80)),
+            timeoutMs: DEFAULT_CONNECT_TIMEOUT_MS,
+          })
+            .then((socket) => {
+              if (settled) {
+                socket.destroy();
+                return;
+              }
+              if (isHttps) {
+                const secure = tls.connect({
+                  socket,
+                  servername: target.hostname,
+                  rejectUnauthorized: true,
+                });
+                secure.on('error', (err) => fail(markNetwork(err)));
+                secure.on('secureConnect', () => {
+                  const req = https.request(
+                    { ...requestOptions, createConnection: () => secure, servername: target.hostname },
+                    onResponse,
+                  );
+                  handleRequest(req);
+                });
+              } else {
+                const req = http.request(
+                  { ...requestOptions, createConnection: () => socket },
+                  onResponse,
+                );
+                handleRequest(req);
+              }
+            })
+            .catch((err) => fail(markNetwork(err)));
+          return;
+        }
+        // HTTP 代理：https 目标走 CONNECT 隧道，http 目标发绝对 URI。
+        if (!isHttps) {
+          const proxyPort = Number(proxy.port || 80);
+          const req = http.request(
+            {
+              ...requestOptions,
+              host: proxy.hostname,
+              port: proxyPort,
+              path: target.toString(),
+              setHost: false,
+              headers: { ...headers, host: target.host },
+            },
+            onResponse,
+          );
+          handleRequest(req);
+          return;
+        }
+        const proxyPort = Number(proxy.port || 80);
+        const connectReq = http.request({
+          host: proxy.hostname,
+          port: proxyPort,
+          method: 'CONNECT',
+          path: `${target.hostname}:${Number(target.port || 443)}`,
+          headers: {
+            host: `${target.hostname}:${Number(target.port || 443)}`,
+            ...(proxy.username
+              ? {
+                  'proxy-authorization': `Basic ${Buffer.from(
+                    `${decodeURIComponent(proxy.username)}:${decodeURIComponent(proxy.password)}`,
+                  ).toString('base64')}`,
+                }
+              : {}),
+          },
+          agent: false,
+        });
+        connectTimeoutHandle = setTimeout(() => {
+          const err = new Error('连接代理超时');
+          err.code = 'ETIMEDOUT';
+          err.retryable = true;
+          err.timedOut = true;
+          connectReq.destroy(err);
+        }, DEFAULT_CONNECT_TIMEOUT_MS);
+        if (typeof connectTimeoutHandle.unref === 'function') connectTimeoutHandle.unref();
+        connectReq.on('connect', (res, socket) => {
+          clearTimeout(connectTimeoutHandle);
+          if (res.statusCode !== 200) {
+            socket.destroy();
+            fail(
+              Object.assign(new Error(`代理 CONNECT 失败（HTTP ${res.statusCode}）`), {
+                retryable: false,
+              }),
+            );
+            return;
+          }
+          const secure = tls.connect({
+            socket,
+            servername: target.hostname,
+            rejectUnauthorized: true,
+          });
+          secure.on('error', (err) => fail(markNetwork(err)));
+          secure.on('secureConnect', () => {
+            const req = https.request(
+              { ...requestOptions, createConnection: () => secure, servername: target.hostname },
+              onResponse,
+            );
+            handleRequest(req);
+          });
+        });
+        connectReq.on('error', (err) => {
+          clearTimeout(connectTimeoutHandle);
+          fail(markNetwork(err));
+        });
+        connectReq.end();
+        return;
+      }
+
+      // 直连。
+      const options = {
+        ...requestOptions,
+        host: target.hostname,
+        port: target.port ? Number(target.port) : isHttps ? 443 : 80,
+        path: `${target.pathname}${target.search}`,
+        ...(isHttps ? { servername: target.hostname } : {}),
+      };
+      const req = isHttps ? https.request(options, onResponse) : http.request(options, onResponse);
+      handleRequest(req);
+    });
+  }
+
+  /** 响应 → `ApiResponse`（非 JSON 走 raw 字节，附件下载靠它）。 */
+  async ingest(response, fallbackRequestId) {
+    const responseRequestId = headerValue(response.headers, REQUEST_ID_HEADER) ?? fallbackRequestId;
+    const serverVersion = headerValue(response.headers, 'x-server-version');
+    const contentType = (headerValue(response.headers, 'content-type') ?? '').toLowerCase();
+    const isJson = contentType.includes('json');
+    if (!isJson) {
+      return {
+        status: response.status,
+        body: { __raw_bytes: response.body.length },
+        request_id: responseRequestId,
+        server_version: serverVersion,
+        raw: response.body,
+      };
+    }
+    const text = response.body.toString('utf8');
+    if (text.trim().length === 0) {
+      return {
+        status: response.status,
+        body: {},
+        request_id: responseRequestId,
+        server_version: serverVersion,
+        raw: null,
+      };
+    }
+    let body;
+    try {
+      body = JSON.parse(text);
+    } catch (err) {
+      throw new CliError(
+        Kind.Server,
+        'cli.bad_response',
+        `服务端返回的不是 JSON（HTTP ${response.status}）：${err.message}`,
+      )
+        .withDetails({ body_preview: preview(text) })
+        .withRequestId(responseRequestId);
+    }
+    return {
+      status: response.status,
+      body,
+      request_id: responseRequestId,
+      server_version: serverVersion,
+      raw: null,
+    };
+  }
+
+  /** 服务端错误 → CLI 错误（`error.code` → 退出码，契约 §3.2）。 */
+  serverError(response) {
+    const error = isPlainObject(response.body?.error) ? response.body.error : {};
+    const code = typeof error.code === 'string' ? error.code : 'internal.error';
+    const message =
+      typeof error.message === 'string' ? error.message : `服务端返回 HTTP ${response.status}`;
+    const details = error.details === undefined || error.details === null ? {} : error.details;
+    const hint = typeof error.hint === 'string' ? error.hint : null;
+
+    let kind;
+    if (
+      code === 'request.invalid' &&
+      (details?.reason === 'move_into_own_subtree' || details?.max_depth !== undefined)
+    ) {
+      // ORG-001 §5 场景 3：`org --move` 的两类状态拒绝（移进自己子树 / 超 32 层）
+      // 语义是"当前树形状下的状态冲突"，归 5 —— 只有带这两个 details 的才归 5。
+      kind = Kind.Conflict;
+    } else if (code === 'request.invalid' && details?.reason === 'transfer_target_required') {
+      // ORG-004：缺 `--transfer-to` 且服务端解析不出默认目标。契约把这一条钉成
+      // **用法错误（退出码 2）**：客户端判不了"该企业有没有 tenant_owner"（那是服务端事实）。
+      kind = Kind.Usage;
+    } else {
+      kind = classify(code, response.status);
+    }
+
+    const err = new CliError(kind, code, message).withDetails(details);
+    err.requestId = response.request_id ?? null;
+    err.httpStatus = response.status;
+
+    // hint：服务端的 hint 优先（它最懂自己缺什么）；凭据类错误一律补上登录命令。
+    if (code.startsWith('auth.')) {
+      err.hint = hint
+        ? `${hint}；或者直接重新登录：xinhe-oa-cli login --phone <你的手机号>`
+        : loginHint(null);
+    } else {
+      err.hint = hint;
+    }
+    if (response.status === 404 && !err.hint) {
+      err.hint = '用 `xinhe-oa-cli schema` 看当前命令面支持的路径';
+    }
+    return err;
+  }
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function headerValue(headers, name) {
+  const value = headers?.[name.toLowerCase()];
+  if (Array.isArray(value)) return value[0] ?? null;
+  return typeof value === 'string' ? value : null;
+}
+
+function isRedirect(status) {
+  return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+
+function shouldRetryStatus(status) {
+  return status === 429 || status >= 500;
+}
+
+function retryAfter(response) {
+  const seconds = response.body?.error?.details?.retry_after_seconds;
+  return typeof seconds === 'number' ? String(seconds) : null;
+}
+
+/** 指数退避 + 抖动：0.4s / 0.8s / 1.6s（尊重 Retry-After，上限 30s）。 */
+export function backoff(attempt, retryAfterRaw) {
+  if (retryAfterRaw !== null && retryAfterRaw !== undefined && String(retryAfterRaw).trim() !== '') {
+    const seconds = Number(String(retryAfterRaw).trim());
+    if (Number.isFinite(seconds)) return Math.min(Math.max(seconds, 0), 30) * 1000;
+  }
+  const base = 400 * 2 ** Math.min(attempt, 4);
+  const jitter = Math.floor(Math.random() * 200);
+  return Math.min(base + jitter, 30_000);
+}
+
+/**
+ * 退避等待。
+ *
+ * **这里绝对不能 `unref()`**：重试路径上此刻已经没有别的 handle（socket 刚关掉），
+ * 把定时器 unref 掉事件循环就直接空转 → Node 打印
+ * `Warning: Detected unsettled top-level await` 并以**退出码 13** 结束，
+ * 于是"退避重试"变成"静默死掉"，而契约要求网络故障是 7、5xx 是 6。
+ * 请求超时/连接超时那两个定时器可以 unref（socket 本身撑着事件循环），这个不行。
+ */
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+/** 网络错误打标：只有超时 / 连接类错误值得重试。 */
+function markNetwork(err) {
+  const code = err?.code ?? '';
+  const retryable =
+    err?.timedOut === true ||
+    code === 'ETIMEDOUT' ||
+    code === 'ECONNREFUSED' ||
+    code === 'ECONNRESET' ||
+    code === 'ENOTFOUND' ||
+    code === 'EAI_AGAIN' ||
+    code === 'EPIPE' ||
+    code === 'EHOSTUNREACH' ||
+    code === 'ENETUNREACH' ||
+    code === 'ERR_SOCKET_CONNECTION_TIMEOUT';
+  err.retryable = retryable;
+  return err;
+}
+
+function shortReason(err) {
+  if (err?.timedOut === true || err?.code === 'ETIMEDOUT') return '请求超时';
+  if (err?.code === 'ECONNREFUSED') return '连接被拒绝或不可达';
+  if (err?.code === 'ENOTFOUND' || err?.code === 'EAI_AGAIN') return '域名解析失败';
+  if (err?.code === 'ECONNRESET') return '连接被重置';
+  const text = String(err?.message ?? '未知网络错误');
+  return text.split('\n')[0];
+}
+
+function networkError(url, err, requestId) {
+  const target = hostOf(url) ?? url;
+  const cliError = CliError.local(`连不上服务端 ${target}：${shortReason(err)}`).withRequestId(
+    requestId,
+  );
+  cliError.hint =
+    '检查：① `xinhe-oa-cli config --show` 里的 base_url ② 服务端是否在跑 ' +
+    '③ 若在本地/内网直连，关掉代理：`xinhe-oa-cli config --set proxy=none` ' +
+    '（或临时 `XINHE_OA_PROXY=none xinhe-oa-cli doctor`）';
+  cliError.details = { target_host: target };
+  return cliError;
+}
+
+function preview(text) {
+  const chars = Array.from(String(text));
+  return chars.length > 200 ? `${chars.slice(0, 200).join('')}…` : chars.join('');
+}
+
+// ---------------------------------------------------------------------------
+// multipart（手写：Content-Length 必须给准，否则有些网关会挂住）
+// ---------------------------------------------------------------------------
+function buildMultipart(form) {
+  const boundary = `----xinheoa${Math.random().toString(16).slice(2)}${Date.now().toString(16)}`;
+  const parts = [];
+  for (const [key, value] of form.fields) {
+    parts.push(
+      Buffer.from(
+        `--${boundary}\r\nContent-Disposition: form-data; name="${escapeHeader(key)}"\r\n\r\n${value}\r\n`,
+        'utf8',
+      ),
+    );
+  }
+  if (form.file) {
+    const [field, filename, bytes] = form.file;
+    parts.push(
+      Buffer.from(
+        `--${boundary}\r\nContent-Disposition: form-data; name="${escapeHeader(field)}"; filename="${escapeHeader(filename)}"\r\nContent-Type: application/octet-stream\r\n\r\n`,
+        'utf8',
+      ),
+    );
+    parts.push(Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes));
+    parts.push(Buffer.from('\r\n', 'utf8'));
+  }
+  parts.push(Buffer.from(`--${boundary}--\r\n`, 'utf8'));
+  return {
+    payload: Buffer.concat(parts),
+    contentType: `multipart/form-data; boundary=${boundary}`,
+  };
+}
+
+function escapeHeader(value) {
+  return String(value).replace(/[\r\n"]/g, '_');
+}
+
+// ---------------------------------------------------------------------------
+// SOCKS5（无依赖实现：客户机器上 `ALL_PROXY=socks5h://…` 是常态）
+// ---------------------------------------------------------------------------
+/**
+ * 建一条经 SOCKS5 代理到目标的 TCP 连接。
+ *
+ * 支持无认证与用户名/口令认证（RFC 1928/1929）。`socks5h` 与 `socks5` 都按
+ * **远端解析**处理：把域名交给代理去解析 —— 这正是 `socks5h` 那个 `h` 的含义，
+ * 而用 `socks5` 的人几乎都是想让代理去解析（本地解析在内网里常常失败）。
+ */
+export function openSocks5({ proxyHost, proxyPort, targetHost, targetPort, timeoutMs }) {
+  return new Promise((resolve, reject) => {
+    const socket = net.connect({ host: proxyHost, port: proxyPort });
+    let settled = false;
+    const handle = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      const err = new Error('连接 SOCKS5 代理超时');
+      err.code = 'ETIMEDOUT';
+      err.retryable = true;
+      reject(err);
+    }, timeoutMs);
+    if (typeof handle.unref === 'function') handle.unref();
+
+    const finish = (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(handle);
+      socket.removeAllListeners('data');
+      socket.removeAllListeners('error');
+      if (err) {
+        socket.destroy();
+        reject(err);
+      } else {
+        resolve(socket);
+      }
+    };
+
+    socket.on('error', (err) => finish(err));
+    socket.on('connect', () => {
+      // 第一步：问候（无认证 + 用户名/口令都报上，让代理挑）。
+      const proxyUser = process.env.XINHE_OA_PROXY_USER;
+      const proxyPass = process.env.XINHE_OA_PROXY_PASSWORD;
+      const withAuth = Boolean(proxyUser);
+      socket.write(Buffer.from(withAuth ? [0x05, 0x02, 0x00, 0x02] : [0x05, 0x01, 0x00]));
+    });
+
+    let stage = 'greeting';
+    let buffer = Buffer.alloc(0);
+
+    socket.on('data', (chunk) => {
+      buffer = Buffer.concat([buffer, chunk]);
+      for (;;) {
+        if (stage === 'greeting') {
+          if (buffer.length < 2) return;
+          const version = buffer[0];
+          const method = buffer[1];
+          buffer = buffer.subarray(2);
+          if (version !== 0x05) {
+            finish(Object.assign(new Error('SOCKS5 代理版本不匹配'), { retryable: false }));
+            return;
+          }
+          if (method === 0x02) {
+            const user = process.env.XINHE_OA_PROXY_USER ?? '';
+            const pass = process.env.XINHE_OA_PROXY_PASSWORD ?? '';
+            const userBuf = Buffer.from(user, 'utf8');
+            const passBuf = Buffer.from(pass, 'utf8');
+            socket.write(
+              Buffer.concat([
+                Buffer.from([0x01, userBuf.length]),
+                userBuf,
+                Buffer.from([passBuf.length]),
+                passBuf,
+              ]),
+            );
+            stage = 'auth';
+            continue;
+          }
+          if (method !== 0x00) {
+            finish(
+              Object.assign(new Error('SOCKS5 代理要求不支持的认证方式'), { retryable: false }),
+            );
+            return;
+          }
+          sendConnect();
+          continue;
+        }
+        if (stage === 'auth') {
+          if (buffer.length < 2) return;
+          const ok = buffer[1] === 0x00;
+          buffer = buffer.subarray(2);
+          if (!ok) {
+            finish(Object.assign(new Error('SOCKS5 认证失败'), { retryable: false }));
+            return;
+          }
+          sendConnect();
+          continue;
+        }
+        // stage === 'connect'
+        if (buffer.length < 4) return;
+        const reply = buffer[1];
+        const addressType = buffer[3];
+        let need = 4;
+        if (addressType === 0x01) need += 4 + 2;
+        else if (addressType === 0x04) need += 16 + 2;
+        else if (addressType === 0x03) need += 1 + (buffer[4] ?? 0) + 2;
+        else {
+          finish(Object.assign(new Error('SOCKS5 响应地址类型不认'), { retryable: false }));
+          return;
+        }
+        if (buffer.length < need) return;
+        buffer = buffer.subarray(need);
+        if (reply !== 0x00) {
+          finish(
+            Object.assign(new Error(`SOCKS5 连接被拒（reply=${reply}）`), { retryable: false }),
+          );
+          return;
+        }
+        finish(null);
+        return;
+      }
+    });
+
+    function sendConnect() {
+      const hostBuf = Buffer.from(targetHost, 'utf8');
+      const portBuf = Buffer.alloc(2);
+      portBuf.writeUInt16BE(targetPort, 0);
+      socket.write(
+        Buffer.concat([Buffer.from([0x05, 0x01, 0x00, 0x03, hostBuf.length]), hostBuf, portBuf]),
+      );
+      stage = 'connect';
+    }
+  });
+}