@xgspz/base-sdk 0.0.0-stage → 1.0.5

package/src/index.ts

@@ -0,0 +1,529 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { currentRequestId, REQUEST_ID_HEADER } from "@xgspz/service-kit";
+import type {
+  ApiResponse,
+  HuiJiDetailResult,
+  InternalCollaborationRequest,
+  InternalCollaborationDetail,
+  InternalEmployee,
+  InternalCredential,
+  InternalCredentialRequest,
+  InternalCollaborationResult,
+  InternalJobRequest,
+  InternalConversationRequest,
+  InternalConversationResult,
+  InternalConversationMessageRequest,
+  InternalConversationTurn,
+  InternalJobResult,
+  InternalOrigin,
+  InternalTodoRequest,
+  InternalTodoResult,
+  InternalUploadResult,
+  InternalUploadTextRequest,
+  InternalAttachmentTextRequest,
+  InternalAttachmentResult,
+  InternalUserLookup,
+  InternalJobLineToken,
+  InternalDepartment,
+} from "@xgspz/contracts";
+import type {
+  MediaImageRequest,
+  MediaImageResult,
+  MediaQuota,
+  MediaVisionRequest,
+  MediaVisionResult,
+  StorageFetchResult,
+  StorageStat,
+  StorageUploadTicket,
+} from "@xgspz/contracts";
+import type {
+  InternalVoiceCall,
+  InternalVoiceCallBatchRequest,
+  InternalVoiceCallBatchResult,
+  InternalVoiceCallRequest,
+  InternalVoiceInboundRoute,
+  InternalVoiceInboundRouteRequest,
+  VoiceConfigView,
+  VoiceQueueStatus,
+} from "@xgspz/contracts";
+
+/**
+ * 基础服务客户端。业务服务只依赖这个包，不直接认识平台接口。
+ *
+ * 设计要点：
+ *   - 每次调用都要显式声明 `actingPersonId`（代表谁操作）。不提供"系统身份"
+ *     的默认值，因为平台侧的发起人必须是真实的人，审计也要能追到责任人。
+ *   - 写操作强制 `idempotencyKey`：网络重试、业务重投都不会造成重复送达。
+ *   - 只对**读**和网络层错误重试；写操作交给基础服务的幂等键兜底。
+ */
+
+export class BaseServiceError extends Error {
+  constructor(
+    message: string,
+    readonly code: string,
+    readonly status: number,
+  ) {
+    super(message);
+    this.name = "BaseServiceError";
+  }
+}
+
+export interface BaseClientOptions {
+  /** 基础服务地址，如 http://xg-base:4000。 */
+  baseUrl: string;
+  /** 本服务名，必须与基础服务 SERVICE_TOKENS 里登记的一致。 */
+  serviceName: string;
+  /** 本服务的服务令牌。 */
+  serviceToken: string;
+  timeoutMs?: number;
+  /** 只作用于读操作。 */
+  retries?: number;
+}
+
+export interface ActingUser {
+  /** 平台 personId。该用户必须在基础服务中存在（至少登录过一次）。 */
+  personId: string;
+  /** 当前登录用户调用第三方平台时使用的 access-token。 */
+  accessToken?: string;
+}
+
+const RETRYABLE = new Set([408, 425, 429, 500, 502, 503, 504]);
+
+/**
+ * 校验基础服务发来的语音请求（turnUrl 的每一轮、notifyUrl 的通话结果）确实出自基础服务、说的确实是这一通电话。
+ * 基础服务用**本服务的服务令牌**对「时间戳.通话 id」做 HMAC-SHA256，放在 X-Base-Timestamp / X-Base-Signature 两个头里。
+ * callId 取请求体里的：每一轮是 `body.callId`，通话结果是 `body.call.id`。时间戳超过容差（默认 5 分钟）的一律不认，防重放。
+ */
+export function verifyVoiceSignature(input: {
+  headers: Record<string, string | string[] | undefined>;
+  callId: string;
+  serviceToken: string;
+  toleranceMs?: number;
+  now?: number;
+}) {
+  const header = (name: string) => {
+    const value = input.headers[name] ?? input.headers[name.toLowerCase()];
+    return String(Array.isArray(value) ? value[0] ?? "" : value ?? "").trim();
+  };
+  const timestamp = header("X-Base-Timestamp");
+  const signature = header("X-Base-Signature");
+  if (!input.serviceToken || !input.callId || !/^\d{10,16}$/.test(timestamp) || !/^[0-9a-f]{64}$/i.test(signature)) return false;
+  if (Math.abs((input.now ?? Date.now()) - Number(timestamp)) > (input.toleranceMs ?? 5 * 60_000)) return false;
+  const expected = createHmac("sha256", input.serviceToken).update(`${timestamp}.${input.callId}`).digest();
+  return timingSafeEqual(expected, Buffer.from(signature, "hex"));
+}
+
+export class BaseClient {
+  private readonly baseUrl: string;
+  private readonly timeoutMs: number;
+  private readonly retries: number;
+
+  constructor(private readonly options: BaseClientOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.timeoutMs = options.timeoutMs ?? 20000;
+    this.retries = options.retries ?? 2;
+  }
+
+  get configured() {
+    return Boolean(this.baseUrl && this.options.serviceToken);
+  }
+
+  /** 音频生成不自动重试；TTS 调用可能计费。调用方应设置足够的 timeoutMs。 */
+  generateAudio(input: { text: string; provider?: "doubao" | "minimax"; voiceId?: string; speed?: number }, acting: ActingUser) {
+    return this.call<{ provider: string; voiceId: string; audioUrl: string }>("/internal/audio/generate", { method: "POST", body: input, acting });
+  }
+
+  /**
+   * 生图：基础服务先扣额度，主模型失败换备用（审核拦截不换），结果立即转存对象存储。
+   * 可能要几分钟；不自动重试（每次调用都计次数），重试请带同一个 idempotencyKey。
+   */
+  generateImage(input: MediaImageRequest, acting: ActingUser, opts: { timeoutMs?: number } = {}) {
+    return this.call<MediaImageResult>("/internal/media/images", { method: "POST", body: input, acting, timeoutMs: opts.timeoutMs ?? 400_000 });
+  }
+
+  /** 看图：多张图 + 提示词，可要求按 JSON 回答。不自动重试（计次数）。 */
+  analyzeImages(input: MediaVisionRequest, acting: ActingUser, opts: { timeoutMs?: number } = {}) {
+    return this.call<MediaVisionResult>("/internal/media/vision", { method: "POST", body: input, acting, timeoutMs: opts.timeoutMs ?? 420_000 });
+  }
+
+  /** 当天的生图 / 看图额度。 */
+  mediaQuota(acting: ActingUser) {
+    return this.call<MediaQuota>("/internal/media/quota", { acting, retryable: true });
+  }
+
+  /** 对象存储上传令牌：只对 svc/<本服务>/<keySuffix> 这一个 key 有效、只能新建。配合 uploadToStorage 直传。 */
+  storageUploadToken(input: { keySuffix: string; maxBytes?: number }, acting: ActingUser) {
+    return this.call<StorageUploadTicket>("/internal/storage/upload-token", { method: "POST", body: input, acting, retryable: true });
+  }
+
+  /** 让基础服务代为下载一个地址并存进对象存储（例如会失效的外部链接）。 */
+  fetchIntoStorage(input: { url: string; keySuffix?: string }, acting: ActingUser) {
+    return this.call<StorageFetchResult>("/internal/storage/fetch", { method: "POST", body: input, acting, timeoutMs: 120_000 });
+  }
+
+  /** 本服务对象的短期签名下载链接（不要入库）。 */
+  signStorageUrls(input: { keys: string[]; expiresSec?: number; downloadName?: string }, acting: ActingUser) {
+    return this.call<{ urls: Record<string, string> }>("/internal/storage/sign", { method: "POST", body: input, acting, retryable: true });
+  }
+
+  statStorage(key: string, acting: ActingUser) {
+    return this.call<StorageStat>("/internal/storage/stat", { method: "POST", body: { key }, acting, retryable: true });
+  }
+
+  /**
+   * 在自己的 turnUrl / notifyUrl 处理函数里调：确认请求出自基础服务。
+   * 每一轮传 `body.callId`，通话结果传 `body.call.id`。返回 false 就回 401，不要处理。
+   */
+  verifyVoiceRequest(headers: Record<string, string | string[] | undefined>, callId: string) {
+    return verifyVoiceSignature({ headers, callId, serviceToken: this.options.serviceToken });
+  }
+
+  /** 语音外呼是否已配置好（不含任何密钥和回调地址）。 */
+  voiceConfig(acting: ActingUser) {
+    return this.call<VoiceConfigView>("/internal/voice/config", { acting, retryable: true });
+  }
+
+  /**
+   * 提交一通外呼。**只是排队**：基础服务按并发上限和拨号间隔一通一通拨出，所以返回的状态通常是 QUEUED，
+   * 结果通过 notifyUrl 送回（或用 getVoiceCall 查）。接通后先说 greeting，之后对方每说一句，
+   * 基础服务把文字 POST 到 turnUrl，由业务回下一句；不传 turnUrl 用内置示例对话。
+   * 重试请带同一个 idempotencyKey：已经排上或拨出的不会多打一通。
+   */
+  startVoiceCall(input: InternalVoiceCallRequest, acting: ActingUser) {
+    return this.call<InternalVoiceCall>("/internal/voice/calls", { method: "POST", body: input, acting });
+  }
+
+  /**
+   * 批量提交（一次最多 500 通，再多就分几次调）。每一通各自校验、各自幂等，结果逐条返回；
+   * 一通号码写错不影响其它的。上千人的调研也是这样全部交进来排队，拨出的节奏由基础服务控制。
+   */
+  startVoiceCalls(input: InternalVoiceCallBatchRequest, acting: ActingUser) {
+    return this.call<InternalVoiceCallBatchResult>("/internal/voice/calls/batch", { method: "POST", body: input, acting, timeoutMs: 120_000 });
+  }
+
+  /** 取消某个业务对象名下所有还在排队的外呼（比如调研被叫停）；不传 entityId 就是这一类全部。已拨出的不受影响。 */
+  cancelQueuedVoiceCalls(input: { entityType: string; entityId?: string }, acting: ActingUser) {
+    return this.call<{ cancelled: number }>("/internal/voice/calls/cancel", { method: "POST", body: input, acting });
+  }
+
+  /** 外呼队列现状：排队多少、正在打多少、并发上限、是否在外呼时段、是否被暂停。 */
+  voiceQueue(acting: ActingUser) {
+    return this.call<VoiceQueueStatus>("/internal/voice/queue", { acting, retryable: true });
+  }
+
+  /** 通话状态和全程文字记录。只能查本服务发起（或归本服务接听）的通话。 */
+  getVoiceCall(callId: string, acting: ActingUser) {
+    return this.call<InternalVoiceCall>(`/internal/voice/calls/${encodeURIComponent(callId)}`, { acting, retryable: true });
+  }
+
+  /** 不想打了：还在排队的直接取消；已拨出的在对方下一次说话或沉默时挂断（平台没有即时挂断接口）。 */
+  hangupVoiceCall(callId: string, acting: ActingUser) {
+    return this.call<InternalVoiceCall>(`/internal/voice/calls/${encodeURIComponent(callId)}/hangup`, { method: "POST", body: {}, acting });
+  }
+
+  /** 本服务登记的呼入路由（哪些号码的来电归本服务接）。 */
+  listVoiceInboundRoutes(acting: ActingUser) {
+    return this.call<InternalVoiceInboundRoute[]>("/internal/voice/inbound-routes", { acting, retryable: true });
+  }
+
+  /** 登记或更新一条呼入路由。号码已登记给别的服务时返回 409。 */
+  saveVoiceInboundRoute(input: InternalVoiceInboundRouteRequest, acting: ActingUser) {
+    return this.call<InternalVoiceInboundRoute>("/internal/voice/inbound-routes", { method: "PUT", body: input, acting });
+  }
+
+  deleteVoiceInboundRoute(number: string, acting: ActingUser) {
+    return this.call<{ deleted: boolean }>(`/internal/voice/inbound-routes/${encodeURIComponent(number)}`, { method: "DELETE", body: {}, acting });
+  }
+
+  private headers(acting: ActingUser) {
+    if (!this.options.serviceToken) throw new BaseServiceError("未配置 BASE_SERVICE_TOKEN", "CONFIG_REQUIRED", 503);
+    if (!acting?.personId) throw new BaseServiceError("缺少 actingPersonId：必须声明代表谁操作", "BAD_REQUEST", 400);
+    const requestId = currentRequestId();
+    return {
+      "Content-Type": "application/json",
+      "X-Service-Token": this.options.serviceToken,
+      "X-Service-Name": this.options.serviceName,
+      "X-Acting-PersonId": acting.personId,
+      ...(acting.accessToken ? { "X-Acting-Access-Token": acting.accessToken } : {}),
+      // 把当前请求的追踪 ID 带给基础服务。没有它，一次用户操作在
+      // 业务服务和基础服务的日志里就是两条对不上的记录。
+      ...(requestId ? { [REQUEST_ID_HEADER]: requestId } : {}),
+    };
+  }
+
+  private async call<T>(
+    path: string,
+    init: { method?: string; body?: unknown; acting: ActingUser; retryable?: boolean; timeoutMs?: number },
+  ): Promise<T> {
+    const retries = init.retryable ? this.retries : 0;
+    let lastError: BaseServiceError | undefined;
+    for (let attempt = 0; attempt <= retries; attempt += 1) {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), init.timeoutMs ?? this.timeoutMs);
+      try {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+          method: init.method || "GET",
+          headers: this.headers(init.acting),
+          body: init.body === undefined ? undefined : JSON.stringify(init.body),
+          signal: controller.signal,
+        });
+        const payload = (await response.json().catch(() => null)) as ApiResponse<T> | null;
+        if (response.ok && payload?.success === true) return payload.data;
+        const message = payload && "message" in payload ? payload.message : `基础服务返回 HTTP ${response.status}`;
+        const code = payload && "code" in payload && payload.code ? payload.code : `HTTP_${response.status}`;
+        const error = new BaseServiceError(message, code, response.status);
+        if (!RETRYABLE.has(response.status) || attempt === retries) throw error;
+        lastError = error;
+      } catch (error) {
+        if (error instanceof BaseServiceError) {
+          if (attempt === retries) throw error;
+          lastError = error;
+        } else {
+          const aborted = error instanceof Error && error.name === "AbortError";
+          const normalized = new BaseServiceError(
+            aborted ? "基础服务请求超时" : `基础服务不可达：${error instanceof Error ? error.message : String(error)}`,
+            aborted ? "TIMEOUT" : "UNREACHABLE",
+            503,
+          );
+          if (attempt === retries) throw normalized;
+          lastError = normalized;
+        }
+      } finally {
+        clearTimeout(timeout);
+      }
+      await new Promise((resolve) => setTimeout(resolve, 300 * 2 ** attempt));
+    }
+    throw lastError || new BaseServiceError("基础服务请求失败", "UNKNOWN", 500);
+  }
+
+  /** 探活。业务服务的 /api/health 用它报告依赖状态。 */
+  async ping(): Promise<{ ok: boolean; message?: string }> {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/health`, { signal: AbortSignal.timeout(5000) });
+      return { ok: response.ok };
+    } catch (error) {
+      return { ok: false, message: error instanceof Error ? error.message : String(error) };
+    }
+  }
+
+  /**
+   * 校验终端用户会话。业务服务的鉴权中间件用它。
+   * 结果建议缓存几十秒——不缓存的话每个业务请求都多一次内网往返。
+   */
+  verifySession(token: string, personId: string, acting: ActingUser) {
+    return this.call<InternalUserLookup>("/internal/sessions/verify", {
+      method: "POST",
+      body: { token, personId },
+      acting,
+      retryable: true,
+    });
+  }
+
+  /** 查人。发工作协同前用它补齐 empId。 */
+  lookupUser(personId: string, acting: ActingUser) {
+    return this.call<InternalUserLookup>(`/internal/users/${encodeURIComponent(personId)}`, { acting, retryable: true });
+  }
+
+  /** 按姓名查工作协同员工（姓名完全一致；重名全部返回）。 */
+  searchEmployees(name: string, acting: ActingUser) {
+    return this.call<InternalEmployee[]>(`/internal/employees?name=${encodeURIComponent(name)}`, { acting, retryable: true });
+  }
+
+  /** 平台上出现过的部门（来自登录过的人的 deptList），用于按部门授权。 */
+  listDepartments(acting: ActingUser) {
+    return this.call<InternalDepartment[]>("/internal/departments", { acting, retryable: true });
+  }
+
+  sendCollaboration(input: Omit<InternalCollaborationRequest, "origin"> & { origin: InternalOrigin }, acting: ActingUser) {
+    return this.call<InternalCollaborationResult>("/internal/collaborations", { method: "POST", body: input, acting });
+  }
+
+  sendTodo(input: InternalTodoRequest, acting: ActingUser) {
+    return this.call<InternalTodoResult>("/internal/todos", { method: "POST", body: input, acting });
+  }
+
+  revokeTodo(todoId: string, acting: ActingUser) {
+    return this.call<InternalTodoResult>(`/internal/todos/${encodeURIComponent(todoId)}/revoke`, { method: "POST", body: {}, acting });
+  }
+
+  /**
+   * 把自己发的待办标为已办。已办过再调返回当前状态，不算错误。
+   * force=true：本地已记为已办的也再回写一次（代收件人回写时平台可能静默不生效，需要补办）。
+   */
+  completeTodo(todoId: string, acting: ActingUser, options: { force?: boolean } = {}) {
+    return this.call<InternalTodoResult>(`/internal/todos/${encodeURIComponent(todoId)}/complete`, { method: "POST", body: options.force ? { force: true } : {}, acting });
+  }
+
+  /**
+   * 登记一把平台凭据（AppKey）。同 scope+label 再登记一次就是换 key。
+   * 明文只进不出：返回里没有 appKey，只有末四位。
+   */
+  saveCredential(input: InternalCredentialRequest, acting: ActingUser) {
+    return this.call<InternalCredential>("/internal/credentials", { method: "POST", body: input, acting });
+  }
+
+  listCredentials(scope: string, acting: ActingUser) {
+    return this.call<InternalCredential[]>(`/internal/credentials?scope=${encodeURIComponent(scope)}`, { acting, retryable: true });
+  }
+
+  updateCredential(id: string, input: { label?: string; role?: string; usage?: string; enabled?: boolean }, acting: ActingUser) {
+    return this.call<InternalCredential>(`/internal/credentials/${encodeURIComponent(id)}`, { method: "PATCH", body: input, acting });
+  }
+
+  deleteCredential(id: string, acting: ActingUser) {
+    return this.call<{ deleted: boolean }>(`/internal/credentials/${encodeURIComponent(id)}`, { method: "DELETE", body: {}, acting });
+  }
+
+  /** 本服务的产品线 Token 状态。明文永远不回传，只有末四位。 */
+  jobLineToken(acting: ActingUser) {
+    return this.call<InternalJobLineToken>("/internal/job-line-token", { acting, retryable: true });
+  }
+
+  /** 配置本服务的产品线 Token。每个业务一把，互不共用。 */
+  saveJobLineToken(input: { token: string; label?: string }, acting: ActingUser) {
+    return this.call<InternalJobLineToken>("/internal/job-line-token", { method: "PUT", body: input, acting });
+  }
+
+  deleteJobLineToken(acting: ActingUser) {
+    return this.call<InternalJobLineToken>("/internal/job-line-token", { method: "DELETE", body: {}, acting });
+  }
+
+  /** 按工作协同汇报记录 ID 拉回详情（正文、回复、各节点处理意见）。只能拉本服务自己发出的。 */
+  getCollaborationDetail(recordId: string, acting: ActingUser, options: { includeAssociated?: boolean } = {}) {
+    return this.call<InternalCollaborationDetail>(`/internal/collaborations/remote/${encodeURIComponent(recordId)}${options.includeAssociated ? "?includeAssociated=true" : ""}`, { acting, retryable: true });
+  }
+
+  createJob(input: InternalJobRequest, acting: ActingUser) {
+    return this.call<InternalJobResult>("/internal/agent-jobs", { method: "POST", body: input, acting });
+  }
+
+  /** 取消自己发的 Job。重复取消不算错误，会直接返回当前状态。 */
+  cancelJob(jobId: string, acting: ActingUser) {
+    return this.call<InternalJobResult>(`/internal/agent-jobs/${encodeURIComponent(jobId)}/cancel`, { method: "POST", body: {}, acting });
+  }
+
+  /** 重试自己发出的 Job 失败子任务。 */
+  retryJob(jobId: string, acting: ActingUser, taskKeys?: string[]) {
+    return this.call<InternalJobResult>(`/internal/agent-jobs/${encodeURIComponent(jobId)}/retry`, { method: "POST", body: taskKeys ? { taskKeys } : {}, acting });
+  }
+
+  getJob(jobId: string, acting: ActingUser) {
+    return this.call<InternalJobResult & { tasks: Array<{ taskKey: string; status: string; errorMessage: string | null }> }>(
+      `/internal/agent-jobs/${encodeURIComponent(jobId)}`,
+      { acting, retryable: true },
+    );
+  }
+
+  /** 建对话任务（任务中心 mode=conversation）：firstMessage 是第 1 轮，之后每条消息一轮，每轮结果转发到 notifyUrl。 */
+  createConversation(input: InternalConversationRequest, acting: ActingUser) {
+    return this.call<InternalConversationResult>("/internal/agent-conversations", { method: "POST", body: input, acting });
+  }
+
+  /** 发一条消息 = 一轮。带 businessId 时重复提交只算一轮。 */
+  sendConversationMessage(conversationId: string, input: InternalConversationMessageRequest, acting: ActingUser) {
+    return this.call<InternalConversationResult>(`/internal/agent-conversations/${encodeURIComponent(conversationId)}/messages`, { method: "POST", body: input, acting });
+  }
+
+  getConversation(conversationId: string, acting: ActingUser) {
+    return this.call<InternalConversationResult>(`/internal/agent-conversations/${encodeURIComponent(conversationId)}`, { acting, retryable: true });
+  }
+
+  /** 回调之外的兜底：直接问任务中心各轮状态。 */
+  getConversationTurns(conversationId: string, acting: ActingUser, afterSeq?: number) {
+    return this.call<{ externalJobId?: string; turns: InternalConversationTurn[] }>(
+      `/internal/agent-conversations/${encodeURIComponent(conversationId)}/turns${afterSeq ? `?afterSeq=${afterSeq}` : ""}`,
+      { acting, retryable: true },
+    );
+  }
+
+  /** 结束对话。重复结束不算错误。 */
+  closeConversation(conversationId: string, acting: ActingUser) {
+    return this.call<InternalConversationResult>(`/internal/agent-conversations/${encodeURIComponent(conversationId)}/close`, { method: "POST", body: {}, acting });
+  }
+
+  /** 把文本变成工作协同附件（只生成物理资源，不进知识库，不需要知识库配置）。附件最大 50MB，上传对象存储要时间，默认等 3 分钟。 */
+  uploadAttachmentText(input: InternalAttachmentTextRequest, acting: ActingUser, opts: { timeoutMs?: number } = {}) {
+    return this.call<InternalAttachmentResult>("/internal/attachments/text", { method: "POST", body: input, acting, timeoutMs: opts.timeoutMs ?? 180_000 });
+  }
+
+  /**
+   * 以当前用户本人身份读取慧记会议的完整正文（逐段发言 + 整理纪要）。只读，不生成附件。
+   * 必须带 acting.accessToken：慧记是「我的数据」。一次最多 10 场。
+   */
+  fetchHuiJiDetails(items: Array<string | { id: string; title?: string }>, acting: ActingUser) {
+    const body = { items: items.map((item) => (typeof item === "string" ? { id: item } : item)) };
+    return this.call<HuiJiDetailResult>("/internal/sources/huiji/details", { method: "POST", body, acting, retryable: true });
+  }
+
+  uploadText(input: InternalUploadTextRequest, acting: ActingUser) {
+    return this.call<InternalUploadResult>("/internal/knowledge/text", { method: "POST", body: input, acting });
+  }
+}
+
+/** 从环境变量装配客户端，避免每个业务服务重复写一遍。 */
+export function createBaseClient(env: NodeJS.ProcessEnv, serviceName: string) {
+  return new BaseClient({
+    baseUrl: (env.BASE_SERVICE_URL || "http://127.0.0.1:4000").trim(),
+    serviceName,
+    serviceToken: (env.BASE_SERVICE_TOKEN || "").trim(),
+    timeoutMs: Number(env.BASE_SERVICE_TIMEOUT_MS) || 20000,
+  });
+}
+
+export type { InternalJobNotification, InternalOrigin, InternalConversationNotification, InternalConversationResult, InternalConversationTurn } from "@xgspz/contracts";
+export type {
+  InternalVoiceCall,
+  InternalVoiceCallBatchRequest,
+  InternalVoiceCallBatchResult,
+  InternalVoiceCallNotification,
+  InternalVoiceCallRequest,
+  VoiceCallOutcome,
+  VoiceQueueStatus,
+  InternalVoiceInboundRoute,
+  InternalVoiceInboundRouteRequest,
+  InternalVoiceTurnReply,
+  InternalVoiceTurnRequest,
+} from "@xgspz/contracts";
+
+
+/**
+ * 业务服务的用户鉴权中间件工厂。
+ *
+ * 前端把 access-token + personId 传给业务服务，业务服务**不能**直接相信它们，
+ * 必须回基础服务验一次。这里带一个短 TTL 的内存缓存，避免每个请求都往返。
+ */
+export function createSessionVerifier(client: BaseClient, options: { ttlMs?: number } = {}) {
+  const ttl = options.ttlMs ?? 30_000;
+  const cache = new Map<string, { user: InternalUserLookup; expiresAt: number }>();
+
+  return async function verify(token: string, personId: string): Promise<InternalUserLookup> {
+    if (!token || !personId) {
+      throw new BaseServiceError("缺少 access-token 或 personId", "UNAUTHORIZED", 401);
+    }
+    const key = `${personId}:${token}`;
+    const hit = cache.get(key);
+    if (hit && hit.expiresAt > Date.now()) return hit.user;
+    // 校验时代表的就是这个人自己。
+    const user = await client.verifySession(token, personId, { personId }).catch((error: unknown) => {
+      // 把"验不过"和"验不了"分开：
+      //   基础服务明确拒绝（401/403/404）→ 会话无效，前端该重新登录；
+      //   基础服务不可达或 5xx      → 依赖故障，不能误导用户去重新登录。
+      if (error instanceof BaseServiceError && [401, 403, 404].includes(error.status)) {
+        throw new BaseServiceError("登录已失效，请重新登录", "UNAUTHORIZED", 401);
+      }
+      throw error;
+    });
+    cache.set(key, { user, expiresAt: Date.now() + ttl });
+    // 顺手清理过期项，避免长时间运行后缓存无限增长。
+    if (cache.size > 1000) {
+      const now = Date.now();
+      for (const [cacheKey, value] of cache) if (value.expiresAt <= now) cache.delete(cacheKey);
+    }
+    return user;
+  };
+}
+
+
+export { requireUser, actor, type AuthenticatedUser, type AuthRequest } from "./express.js";
+
+export { uploadToStorage, StorageUploadError } from "./storage-upload.js";

package/src/storage-upload.test.ts

@@ -0,0 +1,82 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { BaseClient, uploadToStorage } from "./index.js";
+
+const policy = (scope: string) => Buffer.from(JSON.stringify({ scope, deadline: 1, insertOnly: 1 })).toString("base64").replace(/\+/g, "-").replace(/\//g, "_");
+const ticket = { key: "svc/notex/exports/a.mp4", token: `AK:SIGN:${policy("bkt:svc/notex/exports/a.mp4")}`, uploadUrl: "https://up.test" };
+
+function stub(handler: (url: string, init: RequestInit) => Response) {
+  const calls: Array<{ url: string; init: RequestInit }> = [];
+  const original = globalThis.fetch;
+  globalThis.fetch = (async (input: string | URL | Request, init: RequestInit = {}) => {
+    calls.push({ url: String(input), init });
+    return handler(String(input), init);
+  }) as typeof fetch;
+  return { calls, restore: () => { globalThis.fetch = original; } };
+}
+
+test("小文件表单上传；key 已存在（614）视为成功", async () => {
+  const s = stub(() => new Response(JSON.stringify({ key: ticket.key }), { status: 200 }));
+  try {
+    const r = await uploadToStorage(ticket, { bytes: Buffer.from("hello") }, { contentType: "text/plain" });
+    assert.deepEqual(r, { key: ticket.key, existed: false, size: 5 });
+    const form = s.calls[0]!.init.body as FormData;
+    assert.equal(s.calls[0]!.url, "https://up.test");
+    assert.equal(form.get("key"), ticket.key);
+    assert.equal(form.get("token"), ticket.token);
+  } finally { s.restore(); }
+  // 七牛用非标准的 614 表示「已存在」：真实网络响应可以带这个码，构造的 Response 不行，这里用一个等价的对象。
+  const exists = { status: 614, ok: false, json: async () => ({ error: "file exists" }), text: async () => "{\"error\":\"file exists\"}" } as unknown as Response;
+  const again = stub(() => exists);
+  try {
+    assert.equal((await uploadToStorage(ticket, { bytes: Buffer.from("hello") }, { contentType: "text/plain" })).existed, true);
+  } finally { again.restore(); }
+});
+
+test("大文件分片上传 v2：initiate → 逐片 PUT（失败重试）→ complete，分片顺序和 etag 正确", async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "sdk-upload-"));
+  const file = path.join(dir, "big.bin");
+  fs.writeFileSync(file, Buffer.alloc(17 * 1024 * 1024 + 5, 7));
+  let flaky = true;
+  const s = stub((url, init) => {
+    if (url.endsWith("/uploads") && init.method === "POST") return new Response(JSON.stringify({ uploadId: "U1" }));
+    if (init.method === "PUT") {
+      if (url.endsWith("/2") && flaky) { flaky = false; return new Response("busy", { status: 503 }); }
+      return new Response(JSON.stringify({ etag: `e${url.split("/").pop()}` }));
+    }
+    return new Response(JSON.stringify({ key: ticket.key, hash: "h" }));
+  });
+  try {
+    const r = await uploadToStorage(ticket, { file }, { contentType: "video/mp4", partSize: 8 * 1024 * 1024 });
+    assert.equal(r.size, 17 * 1024 * 1024 + 5);
+    const base = `https://up.test/buckets/bkt/objects/${Buffer.from(ticket.key).toString("base64").replace(/\+/g, "-").replace(/\//g, "_")}/uploads`;
+    assert.equal(s.calls[0]!.url, base);
+    assert.equal((s.calls[0]!.init.headers as Record<string, string>).Authorization, `UpToken ${ticket.token}`);
+    const puts = s.calls.filter((c) => c.init.method === "PUT").map((c) => c.url.split("/").pop());
+    assert.deepEqual(puts, ["1", "2", "2", "3"], "第 2 片失败后重试");
+    const done = JSON.parse(String(s.calls[s.calls.length - 1]!.init.body));
+    assert.deepEqual(done.parts, [{ partNumber: 1, etag: "e1" }, { partNumber: 2, etag: "e2" }, { partNumber: 3, etag: "e3" }]);
+    assert.equal(done.mimeType, "video/mp4");
+  } finally { s.restore(); fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("生图 / 看图用单次调用的长超时，不自动重试；存储签名可重试", async () => {
+  const client = new BaseClient({ baseUrl: "http://base.test", serviceName: "notex", serviceToken: "tok", timeoutMs: 1 });
+  let calls = 0;
+  const s = stub(() => { calls += 1; return new Response(JSON.stringify({ success: true, data: { callId: "c", model: "10006" } }), { status: 200 }); });
+  try {
+    // 客户端默认超时只有 1ms；生图接口用自己的长超时，所以不会被中止。
+    const r = await client.generateImage({ prompt: "画" }, { personId: "p1" });
+    assert.equal(r.callId, "c");
+    assert.equal(s.calls[0]!.url, "http://base.test/internal/media/images");
+  } finally { s.restore(); }
+  const fail = stub(() => { calls += 1; return new Response(JSON.stringify({ success: false, code: "MEDIA_UPSTREAM", message: "忙" }), { status: 502 }); });
+  try {
+    calls = 0;
+    await assert.rejects(client.analyzeImages({ prompt: "看", images: ["https://x/y.png"] }, { personId: "p1" }, { timeoutMs: 5000 }), /忙/);
+    assert.equal(calls, 1, "看图不自动重试（计次数）");
+  } finally { fail.restore(); }
+});