zcw-shared 2.26.0 → 2.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zcw-shared",
-  "version": "2.26.0",
+  "version": "2.27.0",
   "files": [
     "references",
     "dist",
@@ -33,9 +33,13 @@
     "typescript": "^5.8.3",
     "vitepress": "^1.6.4",
     "vue": "^3.5.22",
-    "zcw-vue-ui": "^1.30.0"
+    "zcw-vue-ui": "^1.31.0"
   },
   "exports": {
+    "./constants/agentAvatar3d": "./dist/constants/agentAvatar3d.js",
+    "./constants/agentAvatar3dModular": "./dist/constants/agentAvatar3dModular.js",
+    "./constants/agentPresence3dLabels": "./dist/constants/agentPresence3dLabels.js",
+    "./constants/aiApiRoutes": "./dist/constants/aiApiRoutes.js",
     "./constants/aiChatSuggestions": "./dist/constants/aiChatSuggestions.js",
     "./constants/api": "./dist/constants/api.js",
     "./constants/apiErrorCodes": "./dist/constants/apiErrorCodes.js",
@@ -51,26 +55,39 @@
     "./constants/namedColors": "./dist/constants/namedColors.js",
     "./constants/softwareConfigs": "./dist/constants/softwareConfigs.js",
     "./functions/ag-grid/generateLicense": "./dist/functions/ag-grid/generateLicense.js",
+    "./functions/ai/agentAvatar3dArkitMorph": "./dist/functions/ai/agentAvatar3dArkitMorph.js",
+    "./functions/ai/agentAvatar3dCapabilities": "./dist/functions/ai/agentAvatar3dCapabilities.js",
+    "./functions/ai/agentAvatar3dFacePresets": "./dist/functions/ai/agentAvatar3dFacePresets.js",
+    "./functions/ai/agentAvatar3dMaterialTint": "./dist/functions/ai/agentAvatar3dMaterialTint.js",
+    "./functions/ai/agentAvatar3dMorphCatalog": "./dist/functions/ai/agentAvatar3dMorphCatalog.js",
     "./functions/ai/aiAgentToolTimeline": "./dist/functions/ai/aiAgentToolTimeline.js",
     "./functions/ai/aiChatSessionListDom": "./dist/functions/ai/aiChatSessionListDom.js",
     "./functions/ai/aiChatSessionOps": "./dist/functions/ai/aiChatSessionOps.js",
     "./functions/ai/aiChatSessionPins": "./dist/functions/ai/aiChatSessionPins.js",
     "./functions/ai/aiLlmModelCapabilities": "./dist/functions/ai/aiLlmModelCapabilities.js",
     "./functions/ai/aiReplyStreamDisplay": "./dist/functions/ai/aiReplyStreamDisplay.js",
+    "./functions/ai/applyAiAgentAvatar3dFace": "./dist/functions/ai/applyAiAgentAvatar3dFace.js",
     "./functions/ai/applyLlmExtraBody": "./dist/functions/ai/applyLlmExtraBody.js",
     "./functions/ai/buildOpenAiChatCompletionsRequestBody": "./dist/functions/ai/buildOpenAiChatCompletionsRequestBody.js",
     "./functions/ai/buildResolvedLlmToolsList": "./dist/functions/ai/buildResolvedLlmToolsList.js",
     "./functions/ai/catalogLinkMode": "./dist/functions/ai/catalogLinkMode.js",
     "./functions/ai/createSyntheticAgentEmail": "./dist/functions/ai/createSyntheticAgentEmail.js",
     "./functions/ai/fetchAiChatSuggestions": "./dist/functions/ai/fetchAiChatSuggestions.js",
+    "./functions/ai/getEffectiveAvatar3dMorphWeights": "./dist/functions/ai/getEffectiveAvatar3dMorphWeights.js",
     "./functions/ai/isValidMcpToolWirePayload": "./dist/functions/ai/isValidMcpToolWirePayload.js",
     "./functions/ai/mapAiChatMessagesToImChat": "./dist/functions/ai/mapAiChatMessagesToImChat.js",
     "./functions/ai/mcpUpstreamAuthHeaders": "./dist/functions/ai/mcpUpstreamAuthHeaders.js",
+    "./functions/ai/normalizeAiAgentAvatar3d": "./dist/functions/ai/normalizeAiAgentAvatar3d.js",
+    "./functions/ai/normalizeAiAgentAvatar3dFace": "./dist/functions/ai/normalizeAiAgentAvatar3dFace.js",
+    "./functions/ai/normalizeAiAgentAvatar3dModular": "./dist/functions/ai/normalizeAiAgentAvatar3dModular.js",
     "./functions/ai/normalizeAiAgentReplyFormat": "./dist/functions/ai/normalizeAiAgentReplyFormat.js",
     "./functions/ai/normalizeAiAttachmentPayloadFormat": "./dist/functions/ai/normalizeAiAttachmentPayloadFormat.js",
     "./functions/ai/normalizeMcpToolsWireFormat": "./dist/functions/ai/normalizeMcpToolsWireFormat.js",
     "./functions/ai/normalizeToolProcessEnv": "./dist/functions/ai/normalizeToolProcessEnv.js",
     "./functions/ai/pickToolChoiceFromAgentToolsConfig": "./dist/functions/ai/pickToolChoiceFromAgentToolsConfig.js",
+    "./functions/ai/proceduralHumanoidMorph": "./dist/functions/ai/proceduralHumanoidMorph.js",
+    "./functions/ai/randomizeModularAvatar3dAppearance": "./dist/functions/ai/randomizeModularAvatar3dAppearance.js",
+    "./functions/ai/resolveAvatar3dModular": "./dist/functions/ai/resolveAvatar3dModular.js",
     "./functions/ai/toolCatalogInlineEnv": "./dist/functions/ai/toolCatalogInlineEnv.js",
     "./functions/algorithm/binarySearch": "./dist/functions/algorithm/binarySearch.js",
     "./functions/algorithm/canJump": "./dist/functions/algorithm/canJump.js",
@@ -297,7 +314,6 @@
     "./functions/dom/readBrowserDomDeps": "./dist/functions/dom/readBrowserDomDeps.js",
     "./functions/dom/resolveChatMessageImageFromContextMenu": "./dist/functions/dom/resolveChatMessageImageFromContextMenu.js",
     "./functions/dom/resolveOverlayTeleportParent": "./dist/functions/dom/resolveOverlayTeleportParent.js",
-    "./functions/dom/safeBrowserDom": "./dist/functions/dom/safeBrowserDom.js",
     "./functions/dom/writeImageBlobToClipboard": "./dist/functions/dom/writeImageBlobToClipboard.js",
     "./functions/download/adaptDownloadDispatcherForUrlFeedback": "./dist/functions/download/adaptDownloadDispatcherForUrlFeedback.js",
     "./functions/download/buildCapacitorDownloadRelativePath": "./dist/functions/download/buildCapacitorDownloadRelativePath.js",
@@ -649,6 +665,7 @@
     "./functions/project/buildProjectMachineHeaders": "./dist/functions/project/buildProjectMachineHeaders.js",
     "./functions/promise/sleep": "./dist/functions/promise/sleep.js",
     "./functions/promise/timeout": "./dist/functions/promise/timeout.js",
+    "./functions/qiankun/bootstrapQiankunDomPatch": "./dist/functions/qiankun/bootstrapQiankunDomPatch.js",
     "./functions/qiankun/createQiankunVueApp": "./dist/functions/qiankun/createQiankunVueApp.js",
     "./functions/release/buildCapacitorApkCacheRelPath": "./dist/functions/release/buildCapacitorApkCacheRelPath.js",
     "./functions/release/buildCapacitorApkUpdatePrompt": "./dist/functions/release/buildCapacitorApkUpdatePrompt.js",
@@ -799,6 +816,8 @@
     "./functions/vue/isVNode": "./dist/functions/vue/isVNode.js",
     "./functions/vue/isVueComponent": "./dist/functions/vue/isVueComponent.js",
     "./functions/vue/parseVueFile": "./dist/functions/vue/parseVueFile.js",
+    "./functions/vue-router/normalizeWebHistoryBase": "./dist/functions/vue-router/normalizeWebHistoryBase.js",
+    "./functions/vue-router/pushInAppRoute": "./dist/functions/vue-router/pushInAppRoute.js",
     "./functions/wallet/createBrowserWalletPayPasswordSessionAccess": "./dist/functions/wallet/createBrowserWalletPayPasswordSessionAccess.js",
     "./functions/wallet/trc20PayQr": "./dist/functions/wallet/trc20PayQr.js",
     "./functions/wallet/walletLedgerUi": "./dist/functions/wallet/walletLedgerUi.js",
@@ -873,6 +892,7 @@
     "./vue-hooks/worker/useWorkerPool": "./dist/vue-hooks/worker/useWorkerPool.js",
     "./types/address": "./types/address.d.ts",
     "./types/agent-input-content": "./types/agent-input-content.d.ts",
+    "./types/ai-admin": "./types/ai-admin.d.ts",
     "./types/ai-agent": "./types/ai-agent.d.ts",
     "./types/ai-chat": "./types/ai-chat.d.ts",
     "./types/ai-llm-model-capabilities": "./types/ai-llm-model-capabilities.d.ts",
@@ -882,6 +902,8 @@
     "./types/altool": "./types/altool.d.ts",
     "./types/android-build": "./types/android-build.d.ts",
     "./types/api-client": "./types/api-client.d.ts",
+    "./types/api-contract-helpers": "./types/api-contract-helpers.d.ts",
+    "./types/api-contract": "./types/api-contract.d.ts",
     "./types/app-safe-area": "./types/app-safe-area.d.ts",
     "./types/assets": "./types/assets.d.ts",
     "./types/auth": "./types/auth.d.ts",
@@ -894,6 +916,7 @@
     "./types/cloud-disk-config": "./types/cloud-disk-config.d.ts",
     "./types/cloud-disk": "./types/cloud-disk.d.ts",
     "./types/color": "./types/color.d.ts",
+    "./types/community": "./types/community.d.ts",
     "./types/component-material": "./types/component-material.d.ts",
     "./types/design-system": "./types/design-system.d.ts",
     "./types/download": "./types/download.d.ts",
@@ -921,7 +944,9 @@
     "./types/named-sse": "./types/named-sse.d.ts",
     "./types/notification": "./types/notification.d.ts",
     "./types/observability": "./types/observability.d.ts",
+    "./types/openapi": "./types/openapi.d.ts",
     "./types/order": "./types/order.d.ts",
+    "./types/org": "./types/org.d.ts",
     "./types/oss-signed-upload": "./types/oss-signed-upload.d.ts",
     "./types/oss": "./types/oss.d.ts",
     "./types/page-config": "./types/page-config.d.ts",
@@ -934,6 +959,7 @@
     "./types/product": "./types/product.d.ts",
     "./types/rbac": "./types/rbac.d.ts",
     "./types/reactive": "./types/reactive.d.ts",
+    "./types/recharge": "./types/recharge.d.ts",
     "./types/report": "./types/report.d.ts",
     "./types/review": "./types/review.d.ts",
     "./types/semver": "./types/semver.d.ts",

package/types/address.d.ts

@@ -1,38 +1,7 @@
-export interface Address {
-  id: number
-  user_id?: string
-  name?: string
-  phone?: string
-  province?: string
-  city?: string
-  district?: string
-  detail?: string
-  is_default?: boolean
-  created_at?: string
-  updated_at?: string
-}
+import type { ApiSchema } from './api-contract'
 
-export interface AddressListResponse {
-  data: Address[]
-  count: number
-}
+export type Address = ApiSchema['Address']
 
-export interface CreateAddressPayload {
-  name: string
-  phone: string
-  province: string
-  city: string
-  district?: string
-  detail: string
-  is_default?: boolean
-}
+export type CreateAddressPayload = ApiSchema['CreateAddressRequest']
 
-export interface UpdateAddressPayload {
-  name?: string
-  phone?: string
-  province?: string
-  city?: string
-  district?: string
-  detail?: string
-  is_default?: boolean
-}
+export type UpdateAddressPayload = ApiSchema['UpdateAddressRequest']

package/types/ai-admin.d.ts

@@ -0,0 +1,33 @@
+import type { ApiSchema } from './api-contract'
+
+export type AiAgentPublic = ApiSchema['AiAgentPublic']
+
+export type AiAgentTask = ApiSchema['AiAgentTask']
+
+export type AiAgentTaskRun = ApiSchema['AiAgentTaskRun']
+
+export type AiAgentRuntimeSnapshot = ApiSchema['AiAgentRuntimeSnapshot']
+
+export type AiAgentAutomationConfig = ApiSchema['AiAgentAutomationConfig']
+
+export type AiAgentTaskExecution = ApiSchema['AiAgentTaskExecution']
+
+export type AiAgentOrchestration = ApiSchema['AiAgentOrchestration']
+
+export type AiAgentOrchestrationStep = ApiSchema['AiAgentOrchestrationStep']
+
+export type AiAgentOrchestrationDetail = ApiSchema['AiAgentOrchestrationDetail']
+
+export type AiToolCatalog = ApiSchema['AiToolCatalog']
+
+export type AiMcpCatalog = ApiSchema['AiMcpCatalog']
+
+export type LlmGatewayInfo = ApiSchema['LlmGatewayInfo']
+
+export type DynamicToolsHintBlock = ApiSchema['DynamicToolsHintBlock']
+
+export type AiSettingsHintBlocks = ApiSchema['AiSettingsHintBlocks']
+
+export type AgentActiveHours = ApiSchema['AgentActiveHours']
+
+export type AiGatewayTickResult = ApiSchema['AiGatewayTickResult']

package/types/ai-agent.d.ts

@@ -3,3 +3,46 @@ export type AiAgentReplyFormat = 'markdown' | 'text' | 'json'
 
 /** 智能体多模态载荷编码（`ai_agents.attachment_payload_format`） */
 export type AiAttachmentPayloadFormat = 'ag_ui' | 'openai'
+
+/** `ai_agents.avatar_3d.face` */
+export interface AiAgentAvatar3dFace {
+  skinColor?: string
+  hairColor?: string
+  eyeColor?: string
+  faceWidth?: number
+  faceRound?: number
+  eyeSize?: number
+  noseSize?: number
+  mouthSize?: number
+  morphWeights?: Record<string, number>
+}
+
+/** `avatar_3d.modular.slots` */
+export interface AiAgentAvatar3dModularSlots {
+  hair?: string
+  top?: string
+  bottom?: string
+  shoes?: string
+  gloves?: string
+  headwear?: string
+  faceAccessory?: string
+}
+
+/** `avatar_3d.modular` */
+export interface AiAgentAvatar3dModular {
+  version: 'v1'
+  basePartId: string
+  skeletonProfile: 'rpm_mixamo'
+  slots: AiAgentAvatar3dModularSlots
+}
+
+/** `ai_agents.avatar_3d` JSONB */
+export interface AiAgentAvatar3d {
+  modular?: AiAgentAvatar3dModular
+  builtin?: 'humanoid_v1'
+  modelUrl?: string
+  format?: 'glb' | 'gltf' | 'fbx'
+  scale?: number
+  rotationY?: number
+  face?: AiAgentAvatar3dFace
+}

package/types/ai-chat.d.ts

@@ -1,23 +1,39 @@
-export type AiChatMessageRole = 'user' | 'assistant' | 'system'
-
-export interface AiChatMessage {
-  id: string
-  session_id: string
-  role: AiChatMessageRole
-  content: string
-  created_at: string
-}
-
-export type AiChatSuggestionCategory = 'news' | 'creative' | 'qa' | 'general'
-
-export interface AiChatSuggestion {
-  id: string
-  text: string
-  category?: AiChatSuggestionCategory
-}
-
-/** GET /ai-chat/suggestions 响应体 */
-export interface AiChatSuggestionsPayload {
-  title: string
-  items: AiChatSuggestion[]
-}
+import type { ApiOpRequestBody, ApiSchema } from './api-contract'
+
+export type AiChatMessageRole = ApiSchema['AiChatMessage']['role']
+
+export type AiChatMessage = ApiSchema['AiChatMessage']
+
+export type AiChatAvailableModel = ApiSchema['AiChatModelOption']
+
+export type AiChatSession = ApiSchema['AiChatSession']
+
+export type AiChatMessageFeedbackVote = NonNullable<ApiSchema['AiChatMessage']['feedback_vote']>
+
+export type AiChatMessageFeedback = ApiSchema['AiChatMessageFeedback']
+
+export type AiChatMessageSpeechPayload = ApiSchema['AiChatMessageSpeech']
+
+export type AiChatMessageSharePayload = ApiSchema['AiChatMessageShare']
+
+export type AiChatMessageListPayload = ApiSchema['AiChatMessageList']
+
+export type AiChatSuggestionCategory = NonNullable<
+  ApiSchema['AiChatSuggestionItem']['category']
+>
+
+export type AiChatSuggestion = ApiSchema['AiChatSuggestionItem']
+
+/** GET /chat/ai/suggestions 响应体 */
+export type AiChatSuggestionsPayload = ApiSchema['AiChatSuggestionsPayload']
+
+/** GET /chat/ai/shares/:token 公开分享内容 */
+export type AiChatPublicSharePayload = ApiSchema['AiChatPublicShare']
+
+export type AiChatStreamMessageBody = ApiOpRequestBody<'ChatAi_sendMessage'>
+
+export type AiChatStreamFirstMessageBody = ApiOpRequestBody<'ChatAi_createSessionWithFirstMessage'>
+
+export type CreateAiChatSessionBody = ApiOpRequestBody<'ChatAi_createSession'>
+
+export type UpdateAiChatSessionBody = ApiOpRequestBody<'ChatAi_updateSession'>

package/types/api-contract-helpers.d.ts

@@ -0,0 +1,24 @@
+import type { operations } from "./openapi";
+
+type JsonBody<R> = R extends { content: { "application/json": infer B } } ? B : never;
+
+type Response200Body<Op extends keyof operations> = operations[Op] extends {
+  responses: { 200: infer R };
+}
+  ? JsonBody<R>
+  : never;
+
+/** 从 operation 提取 200 响应的 `data`（ApiEnvelope）；无 data 字段时取整个 body */
+export type ApiOpData<Op extends keyof operations> =
+  Response200Body<Op> extends { data: infer D } ? D : Response200Body<Op>;
+
+/** 从 operation 提取 JSON requestBody */
+export type ApiOpRequestBody<Op extends keyof operations> =
+  operations[Op] extends { requestBody: { content: { "application/json": infer B } } }
+    ? B
+    : never;
+
+/** 从 operation 提取 query 参数 */
+export type ApiOpQuery<Op extends keyof operations> = NonNullable<
+  operations[Op]["parameters"]["query"]
+>;

package/types/api-contract.d.ts

@@ -0,0 +1,6 @@
+/** TypeSpec 契约类型 re-export（由 api pnpm spec:sync-shared 生成） */
+export type { components, operations, paths } from "./openapi";
+
+export type ApiSchema = import("./openapi").components["schemas"];
+
+export type { ApiOpData, ApiOpQuery, ApiOpRequestBody } from "./api-contract-helpers";

package/types/auth.d.ts

@@ -1,18 +1,31 @@
 /**
- * 认证相关 API 类型定义
+ * 认证相关 API 类型定义（与 OpenAPI 契约对齐）
  */
 
+/** 内部 JWT 签发结果（仅服务端 token.service 使用） */
 export interface TokenResult {
   token: string
   expiresIn: number
   expiresAt: number
 }
 
-export interface TokenPair {
+/** 内部 JWT 令牌对（仅服务端签发流程使用） */
+export interface IssuedTokenPair {
   accessToken: TokenResult
   refreshToken: TokenResult
 }
 
+/** OpenAPI TokenPair — 扁平 JWT 登录令牌对 */
+export interface TokenPair {
+  accessToken: string
+  refreshToken: string
+  expiresIn: number
+}
+
+export interface OkResult {
+  ok: true
+}
+
 export interface UserInfo {
   id: string
   phone?: string
@@ -22,31 +35,6 @@ export interface UserInfo {
   avatarUrl?: string
 }
 
-export interface LoginResponse {
-  code: number
-  data: {
-    userInfo: UserInfo
-    tokenPair: TokenPair
-  }
-  message: string
-}
-
-export interface RefreshTokenResponse {
-  code: number
-  data: TokenPair
-  message: string
-}
-
-/** 发送验证码响应：data 不含验证码（安全），仅返回发送结果 */
-export interface SendSmsCodeResponse {
-  code: number
-  data: {
-    success: boolean
-    message: string
-  }
-  message: string
-}
-
 export interface PhoneLoginPayload {
   phone: string
   code: string

package/types/cloud-disk.d.ts

@@ -1,56 +1,59 @@
-export type CloudDiskNodeKind = 'folder' | 'file'
+import type { ApiSchema } from './api-contract'
 
-/** 列表视图语义（部分 tab 由客户端筛选实现） */
-export type CloudDiskListTab = 'all' | 'recent' | 'shared' | 'trash'
+/** API 契约：GET /cloud-disk/files 单条 */
+export type CloudDiskFile = ApiSchema['CloudDiskFile']
 
-export type CloudDiskNode = {
+export type CloudDiskNodeKind = 'file' | 'folder'
+
+export type CloudDiskFileCategory = 'image' | 'doc' | 'video' | 'audio' | 'other'
+
+export type CloudDiskMediaAttachmentKind = 'image' | 'video' | 'file'
+
+/** 客户端列表/网格视图节点（由 {@link CloudDiskFile} 映射） */
+export interface CloudDiskNode {
   id: string
   name: string
   kind: CloudDiskNodeKind
   parent_id: string | null
-  owner_id: string
-  size?: number | null
-  mime_type?: string | null
-  updated_at: string
+  owner_id?: string
+  size?: number
+  mime_type?: string
+  updated_at?: string
   created_at?: string
   path_breadcrumb?: string | null
   is_starred?: boolean
   is_shared?: boolean
   is_private?: boolean
   deleted_at?: string | null
-  url?: string | null
-  thumbnail_url?: string | null
+  url?: string
+  thumbnail_url?: string
 }
 
-export type CloudDiskListResult = { items: CloudDiskNode[]; total: number }
+export type CloudDiskListTab = 'recent' | 'shared' | 'trash'
 
-/** 后端 cloud_disk_files 行（GET /cloud-disk/files 解包后） */
-export type CloudDiskFileDto = {
+export interface CloudDiskListResult {
+  items: CloudDiskNode[]
+  total: number
+}
+
+export interface CloudDiskPrivateFolderEntry {
+  id: string
+  path: string
+}
+
+export interface CloudDiskPrivateFolderGuard {
+  privateEntries: readonly CloudDiskPrivateFolderEntry[]
+  parentMap: ReadonlyMap<string, string | null | undefined>
+  unlockedFolderIds: ReadonlySet<string>
+}
+
+export interface CloudDiskNodeDragPayload {
   id: string
-  user_id: string
   name: string
-  type: 'file' | 'folder'
+  kind?: CloudDiskNodeKind
   parent_id?: string | null
-  path?: string
-  mime_type?: string | null
-  size?: number | null
-  is_starred?: boolean
-  is_shared?: boolean
-  is_private?: boolean
-  created_at?: string
-  updated_at: string
-  deleted_at?: string | null
-  url?: string | null
-  thumbnail_url?: string | null
 }
 
-export type CloudDiskFileCategory =
-  | 'image'
-  | 'doc'
-  | 'video'
-  | 'audio'
-  | 'other'
-
 export type CloudDiskUploadPhase =
   | 'preparing'
   | 'uploading'
@@ -58,25 +61,10 @@ export type CloudDiskUploadPhase =
   | 'done'
   | 'failed'
 
-export type CloudDiskUploadTask = {
+export interface CloudDiskUploadTask {
   id: string
   name: string
-  progress: number
   phase: CloudDiskUploadPhase
+  progress: number
   error?: string
 }
-
-export type CloudDiskPrivateFolderEntry = { id: string; path: string }
-
-export type CloudDiskMediaAttachmentKind = 'image' | 'video' | 'file'
-
-export type CloudDiskPrivateFolderGuard = {
-  privateEntries: readonly CloudDiskPrivateFolderEntry[]
-  parentMap: ReadonlyMap<string, string | null | undefined>
-  unlockedFolderIds: ReadonlySet<string>
-}
-
-export type CloudDiskNodeDragPayload = {
-  id: string
-  name: string
-}

package/types/community.d.ts

@@ -0,0 +1,7 @@
+import type { ApiSchema } from './api-contract'
+
+export type CommunityPost = ApiSchema['CommunityPost']
+
+export type CreateCommunityPostPayload = ApiSchema['CreateCommunityPostRequest']
+
+export type UpdateCommunityPostPayload = ApiSchema['UpdateCommunityPostRequest']

package/types/im-ai-agent.d.ts

@@ -1,6 +1,6 @@
 import type { ImAccountKind } from './im-account-kind'
 
-/** `/ai/agents` 列表行（映射 Agent 选项所需字段） */
+/** `admin/ai/agents` 列表行（映射 Agent 选项所需字段） */
 export type ImAiAgentCatalogRow = {
   id?: string | null
   user_id?: string | null

package/types/im-api.d.ts

@@ -3,14 +3,13 @@
  *
  * - **终端 UI 展示**见 `zcw-shared/types/im-chat`（`ChatMessage` / `ChatConversation`，camelCase、含 sender 对象等），
  *   与本文件的 `ImApiMessage` 在设计上不同：前者是列表/气泡视图模型，后者是接口契约。
+ * - 核心 HTTP 形状以 `ApiSchema['ImApiMessage']` / `ImApiConversation` 为契约来源，此处放宽 `id` 与 `extra_data` 以兼容多存储驱动。
  */
 
+import type { ApiSchema } from './api-contract'
+
 /** 出站投递状态（与送达已读 status 分离）；库内成功落库行一般为 success */
-export type ImOutboundStatus =
-  | 'queued'
-  | 'sending'
-  | 'failed'
-  | 'success'
+export type ImOutboundStatus = NonNullable<ApiSchema['ImApiMessage']['outbound_status']>
 
 /** ImProxy 落库：用户停止或模型/流异常时的助手消息标记 */
 export interface ImApiAiReplyExtra {
@@ -63,13 +62,16 @@ export interface ImApiMessage {
    * 智能体中断回复：`extra_data.ai_reply` 见 {@link ImApiAiReplyExtra}。
    * 智能体回复用量：`extra_data.llm_context` 见 `types/im-llm-context.d.ts` 的 {@link ImLlmContextExtra}。
    */
-  extra_data?: Record<string, any>
+  extra_data?: any
   created_at?: string
   updated_at?: string
   /** 软删除时刻（ISO）；存在时列表接口不应返回该条（服务端过滤） */
   deleted_at?: string | null
 }
 
+/** TypeSpec 契约形状（`id` 为 string；`extra_data` 为 unknown） */
+export type ImApiMessageContract = ApiSchema['ImApiMessage']
+
 /** 会话对象（接口返回；成员 id 列表 + 可选最后一条消息） */
 export interface ImApiConversation {
   id: string
@@ -88,6 +90,8 @@ export interface ImApiConversation {
   updated_at?: string
 }
 
+export type ImApiConversationContract = ApiSchema['ImApiConversation']
+
 /** `registerMediaOutbound` 响应：附件 id、已落库消息、OSS 直传目标 */
 export interface ImRegisterMediaOutboundResult {
   attachmentId: string
@@ -113,7 +117,7 @@ export interface ImDbMessageRow {
   client_message_id?: string | null
   send_retry_count?: number | null
   outbound_status?: string | null
-  extra_data?: Record<string, any>
+  extra_data?: any
   created_at?: string
   updated_at?: string
   deleted_at?: string | null
@@ -157,7 +161,7 @@ export type ImMessage = ImApiMessage
 /** 与 `ImApiConversation` 相同 */
 export type ImConversation = ImApiConversation
 
-/** 与 `ImApiConversation` 相同（历史泛名，建议新代码用 ImApiConversation） */
+/** @deprecated 请使用 {@link ImConversation} */
 export type Conversation = ImApiConversation
 
 export type RegisterMediaOutboundResult = ImRegisterMediaOutboundResult

package/types/im-call.d.ts

@@ -1,3 +1,5 @@
+import type { ApiOpData } from './api-contract'
+
 /** IM 实时通话媒体类型（WebRTC，非文件消息） */
 export type ImCallMedia = 'audio' | 'video'
 
@@ -39,6 +41,5 @@ export interface ImCallSignalEventPayload extends ImCallSignalPayload {
   fromUserId: string
 }
 
-export interface ImCallIceServersResponse {
-  iceServers: RTCIceServer[]
-}
+/** GET /im/call/ice-servers → `ApiEnvelope.data` */
+export type ImCallIceServersData = ApiOpData<'ImCore_callIceServers'>