@go-wind/admin-react 0.0.0-stage → 0.1.0

package/dist/storage/storage.types.d.ts

@@ -0,0 +1,199 @@
+/**
+ * 存储类型
+ */
+export type StorageType = "localStorage" | "sessionStorage";
+/**
+ * 缓存驱逐策略
+ * - lru: 最近最少使用 (Least Recently Used)
+ * - lfu: 最不经常使用 (Least Frequently Used)
+ * - hybrid: 混合策略（结合 LRU 和 LFU）
+ */
+export type EvictionStrategy = "lru" | "lfu" | "hybrid";
+/**
+ * 存储元数据
+ * @description 用于跟踪每个存储项的状态信息，支持智能缓存管理
+ */
+export interface StorageMeta {
+    /** 过期时间戳 (null=永久有效) */
+    e: number | null;
+    /** 原始数据大小 (bytes) */
+    s: number;
+    /** 访问次数 (用于 LFU 策略) */
+    a: number;
+    /** 最后访问时间戳 (用于 LRU 策略) */
+    t: number;
+    /** 是否已压缩 */
+    c: boolean;
+}
+/**
+ * 存储性能指标
+ * @description 用于监控存储使用情况和分析性能瓶颈
+ */
+export interface StorageMetrics {
+    /** 命中次数 */
+    hits: number;
+    /** 未命中次数 */
+    misses: number;
+    /** 过期清理次数 */
+    expirations: number;
+    /** 设置操作次数 */
+    sets: number;
+    /** 错误次数 */
+    errors: number;
+    /** 配额使用量 (bytes) */
+    quotaUsageBytes: number;
+    /** 命中率 (0-1) */
+    hitRate: number;
+}
+/**
+ * 多标签页同步消息
+ * @description 用于在不同标签页之间同步存储状态
+ */
+export interface SyncMessage {
+    /** 操作类型 */
+    type: "set" | "remove" | "clear";
+    /** 存储键名 */
+    key: string;
+    /** 标签页 ID */
+    tabId: string;
+    /** 时间戳 */
+    ts: number;
+}
+/**
+ * 存储管理器配置选项
+ * @description 用于初始化 StorageManager 实例时的配置参数
+ */
+export interface StorageManagerOptions {
+    /** 存储键名前缀，用于隔离不同模块的数据 */
+    prefix?: string;
+    /** 存储类型：localStorage 或 sessionStorage */
+    storageType?: StorageType;
+    /** 触发压缩的阈值 (bytes)，默认 1024 */
+    compressionThreshold?: number;
+    /** 缓存驱逐策略，默认 "hybrid" */
+    evictionStrategy?: EvictionStrategy;
+    /** 最大存储项数 (0=不限)，默认 0 */
+    maxItems?: number;
+    /** 最大使用量 (MB)，默认 10 */
+    maxUsageMB?: number;
+    /** 默认过期时间 (ms)，null 表示永不过期 */
+    defaultTTL?: number | null;
+    /** 是否开启多标签页同步，默认 true */
+    enableSync?: boolean;
+    /** 指标变化回调函数 */
+    onMetrics?: (metrics: StorageMetrics) => void;
+    /** 同步事件回调函数 */
+    onSync?: (event: SyncMessage) => void;
+}
+/**
+ * 存储项结构（旧版，保留用于兼容）
+ * @deprecated 请使用 StorageValue 替代
+ */
+export interface StorageItem<T> {
+    /** 过期时间戳 */
+    expiry?: number;
+    /** 存储的值 */
+    value: T;
+}
+/**
+ * 存储值结构
+ * @description 封装数据和过期信息的标准格式
+ */
+export interface StorageValue<T> {
+    /** 存储的实际数据 */
+    data: T;
+    /** 过期时间戳 (null=永不过期) */
+    expiry: number | null;
+}
+/**
+ * 批量设置项的配置
+ * @description 用于在批量设置时为每个项指定独立的 TTL
+ */
+export interface BatchSetItem<T> {
+    /** 要存储的值 */
+    value: T;
+    /** 过期时间 (ms)，覆盖默认 TTL */
+    ttl?: number | null;
+}
+/**
+ * 批量获取的选项
+ * @description 控制批量获取操作的行为
+ */
+export interface BatchGetOptions {
+    /** 是否跳过过期项（默认 true，自动清理过期数据） */
+    skipExpired?: boolean;
+    /** 是否返回原始解析结果（用于调试，默认 false） */
+    includeRaw?: boolean;
+}
+/**
+ * 批量操作结果
+ * @description 包含批量操作的执行结果统计
+ */
+export interface BatchResult<T> {
+    /** 成功设置的项 */
+    success: Record<string, T>;
+    /** 失败的项及对应的错误信息 */
+    failed: Record<string, Error>;
+    /** 因过期被清理的键列表 */
+    expired: string[];
+}
+/**
+ * 批量操作进度回调
+ * @description 用于实时监控批量操作的执行进度
+ */
+export type BatchProgressCallback = (progress: {
+    /** 当前已处理的项目数 */
+    current: number;
+    /** 总项目数 */
+    total: number;
+    /** 当前处理的键名 */
+    key: string;
+    /** 处理状态 */
+    status: "success" | "failed" | "expired";
+}) => void;
+/**
+ * 存储缓存接口
+ * @description 定义存储管理器的基本操作契约
+ */
+export interface IStorageCache {
+    /** 清除所有存储项 */
+    clear(): void;
+    /** 清除所有过期项 */
+    clearExpiredItems(): void;
+    /**
+     * 获取指定索引的键名
+     * @param index - 索引位置
+     * @returns 键名或 null
+     */
+    key(index: number): string | null;
+    /**
+     * 获取存储项数量
+     * @returns 存储项总数
+     */
+    length(): number;
+    /**
+     * 移除指定键的存储项
+     * @param key - 存储键名
+     */
+    removeItem(key: string): void;
+    /**
+     * 设置存储项
+     * @param key - 存储键名
+     * @param value - 要存储的值
+     * @param ttl - 过期时间 (ms)，可选
+     */
+    setItem<T>(key: string, value: T, ttl?: number | null): void;
+    /**
+     * 获取存储项
+     * @param key - 存储键名
+     * @param defaultValue - 默认值，当键不存在时返回
+     * @returns 存储的值或默认值
+     */
+    getItem<T>(key: string, defaultValue?: T | null): T | null;
+    /**
+     * 检查键是否存在且未过期
+     * @param key - 存储键名
+     * @returns 是否存在
+     */
+    hasItem(key: string): boolean;
+}

package/dist/stores/auth.d.ts

@@ -0,0 +1,56 @@
+import { type StoreApi } from 'zustand';
+import { type AdminLoginParams } from '../auth-gateway';
+import type { AdminUserInfo } from '../types';
+/**
+ * 令牌载荷
+ */
+export interface TokenPayload {
+    /**
+     * 令牌值
+     */
+    value: string;
+    /**
+     * 令牌过期时间
+     */
+    expiresAt?: number;
+}
+export interface AuthState {
+    accessToken: string | null;
+    accessTokenExpireAt: number | null;
+    userInfo: AdminUserInfo | null;
+    mfaOperationId: string | null;
+    loginLoading: boolean;
+    error: string | null;
+    login: (params: AdminLoginParams, onSuccess?: () => void, captcha?: {
+        id: string;
+        value: string;
+    }) => Promise<void>;
+    /**
+     * 完成 MFA 挑战：用 operation_id + TOTP 码调后端验证，通过则后端返回真 token，
+     * 复用登录成功流程（存 token / 拉用户信息 / 跳首页）。失败抛错。
+     */
+    completeMfaChallenge: (totpCode: string, onSuccess?: () => void) => Promise<void>;
+    /** 完成 OIDC SSO 登录：code+state 换令牌，复用登录成功流程；失败抛错 */
+    completeSsoLogin: (code: string, state: string, onSuccess?: () => void) => Promise<void>;
+    logout: (redirect?: boolean) => Promise<void>;
+    refreshToken: () => Promise<string>;
+    reauthenticate: () => void;
+    /** 强制登出：纯前端清除认证状态 + 跳转登录页，不调后端接口（用于 token 已失效场景） */
+    forceLogout: () => void;
+    setUserInfo: (info: AdminUserInfo) => void;
+    clearError: () => void;
+    $reset: () => void;
+}
+export declare const useAuthStore: import("zustand").UseBoundStore<Omit<StoreApi<AuthState>, "setState" | "persist"> & {
+    setState(partial: AuthState | Partial<AuthState> | ((state: AuthState) => AuthState | Partial<AuthState>), replace?: false | undefined): unknown;
+    setState(state: AuthState | ((state: AuthState) => AuthState), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<import("zustand/middleware").PersistOptions<AuthState, {}, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void>;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: AuthState) => void) => () => void;
+        onFinishHydration: (fn: (state: AuthState) => void) => () => void;
+        getOptions: () => Partial<import("zustand/middleware").PersistOptions<AuthState, {}, unknown>>;
+    };
+}>;

package/dist/stores/index.d.ts

@@ -0,0 +1,2 @@
+export * from './auth';
+export * from './user';

package/dist/stores/user.d.ts

@@ -0,0 +1,32 @@
+import type { AdminUserBasic } from '../types';
+export interface UserState {
+    userInfo: AdminUserBasic | null;
+    userRoles: string[];
+    accessCodes: string[];
+    hiddenFields: string[];
+    tenantId: string | null;
+    isLoggedIn: boolean;
+    setUserInfo: (info: AdminUserBasic | null) => void;
+    setUserRoles: (roles: string[]) => void;
+    setAccessCodes: (codes: string[]) => void;
+    setHiddenFields: (fields: string[]) => void;
+    isTenantUser: () => boolean;
+    $reset: () => void;
+}
+export declare const useUserStore: import("zustand").UseBoundStore<Omit<import("zustand").StoreApi<UserState>, "setState" | "persist"> & {
+    setState(partial: UserState | Partial<UserState> | ((state: UserState) => UserState | Partial<UserState>), replace?: false | undefined): unknown;
+    setState(state: UserState | ((state: UserState) => UserState), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<import("zustand/middleware").PersistOptions<UserState, {
+            userInfo: AdminUserBasic | null;
+        }, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void>;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: UserState) => void) => () => void;
+        onFinishHydration: (fn: (state: UserState) => void) => () => void;
+        getOptions: () => Partial<import("zustand/middleware").PersistOptions<UserState, {
+            userInfo: AdminUserBasic | null;
+        }, unknown>>;
+    };
+}>;

package/dist/transport/rest/captcha-headers.d.ts

@@ -0,0 +1,2 @@
+export declare function setCaptchaHeaders(id: string, value: string): void;
+export declare function consumeCaptchaHeaders(): Record<string, string> | null;

package/dist/transport/rest/index.d.ts

@@ -0,0 +1,8 @@
+export * from './captcha-headers';
+export * from './preset-interceptors';
+export * from './request-client';
+export * from './types';
+export * from './request-api';
+export * from './utils';
+export * from './pagination';
+export * from 'axios';

package/dist/transport/rest/modules/downloader.d.ts

@@ -0,0 +1,9 @@
+import type { AxiosRequestConfig } from 'axios';
+import type { RequestClient } from '../request-client';
+import type { RequestResponse } from '../types';
+declare class FileDownloader {
+    private client;
+    constructor(client: RequestClient);
+    download(url: string, config?: AxiosRequestConfig): Promise<RequestResponse<Blob>>;
+}
+export { FileDownloader };

package/dist/transport/rest/modules/interceptor.d.ts

@@ -0,0 +1,9 @@
+import type { AxiosInstance } from 'axios';
+import type { RequestInterceptorConfig, ResponseInterceptorConfig } from '../types';
+declare class InterceptorManager {
+    private axiosInstance;
+    constructor(instance: AxiosInstance);
+    addRequestInterceptor({ fulfilled, rejected, }?: RequestInterceptorConfig): void;
+    addResponseInterceptor<T = any>({ fulfilled, rejected, }?: ResponseInterceptorConfig<T>): void;
+}
+export { InterceptorManager };

package/dist/transport/rest/modules/uploader.d.ts

@@ -0,0 +1,10 @@
+import type { AxiosRequestConfig, AxiosResponse } from 'axios';
+import type { RequestClient } from '../request-client';
+declare class FileUploader {
+    private client;
+    constructor(client: RequestClient);
+    upload(url: string, data: {
+        file: Blob | File;
+    } & Record<string, any>, config?: AxiosRequestConfig): Promise<AxiosResponse>;
+}
+export { FileUploader };

package/dist/transport/rest/pagination.d.ts

@@ -0,0 +1,73 @@
+export declare class PaginationQuery {
+    paging?: {
+        page?: number;
+        pageSize?: number;
+    };
+    formValues?: Record<string, unknown> | null;
+    fieldMask?: string | string[] | null;
+    orderBy?: string[] | null;
+    isTenantUser: boolean;
+    constructor(data?: Partial<PaginationQuery>);
+    /**
+     * 移除对象中的 null 和 undefined 值
+     * @param obj - 需要清理的对象
+     * @returns 清理后的对象
+     */
+    private static removeNullUndefined;
+    /**
+     * key 末段是否已是 go-crud 支持的查询操作符（created_at__gte、type__not 等）。
+     * 这类 key 不能再叠加 __contains：go-crud 会把 `a__gte__contains`
+     * 解析成 `a CONTAINS value`，对时间/布尔列直接 SQL 报错（500），
+     * "排除"等语义也可能被静默反转。
+     *
+     * 下表与 go-crud `filter/operator_converter.go` 的 operatorMap 别名集
+     * 逐字对齐（含 i_* 前缀变体、数值比较长拼写/连字符拼写、is_not_null
+     * 拼写族、json_contains/array_contains/exists/search/exact/iexact）。
+     * 后端映射表变更时须同步此表；匹配前做小写归一（后端同）。此表缺项
+     * 会让对应后缀键被追加 __contains 而语义反转或 500（2026-09-13 修复的缺口）。
+     */
+    private static hasOperatorSuffix;
+    /**
+     * 创建列表查询 JSON 过滤字符串
+     *
+     * 后端 go-crud 的裸 `{"field": value}` 走 EQ 精确匹配；搜索框输入部分关键词
+     * 必须使用 `field__contains` 才是模糊匹配。这里约定：字符串值统一转
+     * `__contains`（contains 是完整值精确匹配的超集，对下拉枚举等完整值查询
+     * 结果一致），非字符串（数字/布尔）保持 EQ 精确语义。
+     * @param formValues - 查询表单值
+     * @param needCleanTenant - 是否需要清理租户字段
+     * @returns JSON 字符串或 undefined
+     */
+    private static makeQueryString;
+    /**
+     * 创建排序字符串
+     * @param orderBy - 排序字段数组
+     * @returns JSON 字符串或 undefined
+     */
+    private static makeOrderBy;
+    get noPaging(): boolean;
+    get orderByString(): string | undefined;
+    get queryString(): string | undefined;
+    private get formattedFieldMask();
+    toRawParams(): {
+        page: number | undefined;
+        pageSize: number | undefined;
+        noPaging: boolean;
+        fieldMask: string | undefined;
+        orderBy: string | undefined;
+        query: string | undefined;
+        sorting: undefined;
+        offset: undefined;
+        limit: undefined;
+        token: undefined;
+        filter: undefined;
+        filterExpr: undefined;
+    };
+}
+/**
+ * 分页查询结果类型
+ */
+export type PaginationResult<T> = {
+    items: T[];
+    total: number;
+};

package/dist/transport/rest/preset-interceptors.d.ts

@@ -0,0 +1,25 @@
+import type { RequestClient } from './request-client';
+import type { MakeErrorMessageFn, ResponseInterceptorConfig } from './types';
+/**
+ * 认证响应拦截器：处理 401 错误，支持自动刷新 token 和重新认证
+ * @param client 请求客户端实例
+ * @param doReAuthenticate 重新认证函数，返回 Promise<void>
+ * @param doRefreshToken 刷新 token 函数，返回 Promise<string>，成功时返回新的 token
+ * @param enableRefreshToken 是否启用刷新 token 功能
+ * @param formatToken 格式化 token 的函数，接受原始 token 字符串，返回格式化后的 token 字符串（如添加 "Bearer " 前缀），如果返回 null 则不设置 Authorization 头
+ * @returns 响应拦截器配置对象
+ */
+export declare const authenticateResponseInterceptor: ({ client, doReAuthenticate, doRefreshToken, enableRefreshToken, formatToken, }: {
+    client: RequestClient;
+    doReAuthenticate: () => Promise<void>;
+    doRefreshToken: () => Promise<string>;
+    enableRefreshToken: boolean;
+    formatToken: (token: string) => null | string;
+}) => ResponseInterceptorConfig;
+/**
+ * 错误消息拦截器：提取错误文本并回调
+ * @param makeErrorMessage 错误消息回调函数
+ * @param getErrorMsg 获取错误消息函数，默认为 getDefaultErrorMsg
+ * @returns 响应拦截器配置对象
+ */
+export declare const errorMessageResponseInterceptor: (makeErrorMessage?: MakeErrorMessageFn, getErrorMsg?: (error: unknown) => string) => ResponseInterceptorConfig;

package/dist/transport/rest/request-api.d.ts

@@ -0,0 +1,6 @@
+export declare function requestApi({ path, method, body, headers, }: {
+    path: string;
+    method: string;
+    body: null | string;
+    headers?: Record<string, string>;
+}): Promise<unknown>;

package/dist/transport/rest/request-client.d.ts

@@ -0,0 +1,87 @@
+import type { AxiosRequestConfig } from 'axios';
+import { FileDownloader } from './modules/downloader';
+import { InterceptorManager } from './modules/interceptor';
+import { FileUploader } from './modules/uploader';
+import type { RequestClientCallbacks, RequestClientOptions } from './types';
+declare class RequestClient {
+    private readonly instance;
+    /**
+     * 错误消息提取函数（由应用层注入，接入 i18n；未注入时回退到 getDefaultErrorMsg）。
+     * 仅基于 reason 翻译，不返回后端 message。
+     */
+    private readonly getErrorMsg;
+    addRequestInterceptor: InterceptorManager['addRequestInterceptor'];
+    addResponseInterceptor: InterceptorManager['addResponseInterceptor'];
+    download: FileDownloader['download'];
+    isRefreshing: boolean;
+    refreshTokenQueue: ((token: string) => void)[];
+    upload: FileUploader['upload'];
+    private static _instance;
+    /**
+     * 初始化全局单例（在 bootstrap 时调用一次）
+     */
+    static init(baseURL: string, callbacks: RequestClientCallbacks): void;
+    /**
+     * 获取全局单例
+     */
+    static getInstance(): RequestClient;
+    /**
+     * 构造函数，创建 Axios 实例并注册拦截器
+     * @param options - Axios 请求配置
+     * @param callbacks - 业务回调接口（token、认证、错误处理），由应用层注入
+     */
+    constructor(options?: RequestClientOptions, callbacks?: RequestClientCallbacks);
+    /**
+     * 格式化令牌
+     */
+    private formatToken;
+    /**
+     * 注册所有内置拦截器
+     */
+    private setupInterceptors;
+    /**
+     * 请求拦截器：注入 Authorization Token
+     */
+    private useTokenInterceptor;
+    /**
+     * 请求拦截器：注入 X-Request-ID 和 XMLHttpRequest 标识
+     */
+    private useRequestIdInterceptor;
+    /**
+     * 请求拦截器：注入 Accept-Language
+     */
+    private useLocaleInterceptor;
+    /**
+     * 响应拦截器：解构响应数据（只返回 data 部分）
+     */
+    private useResponseDataInterceptor;
+    /**
+     * 401 认证拦截器：自动刷新 Token 或跳转登录页
+     */
+    private useAuthInterceptor;
+    /**
+     * 统一错误消息拦截器：提取错误文本并回调
+     */
+    private useErrorMessageInterceptor;
+    /**
+     * DELETE请求方法
+     */
+    delete<T = never>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * GET请求方法
+     */
+    get<T = never>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * POST请求方法
+     */
+    post<T = never>(url: string, data?: never, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * PUT请求方法
+     */
+    put<T = never>(url: string, data?: never, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * 通用的请求方法
+     */
+    request<T>(url: string, config: AxiosRequestConfig): Promise<T>;
+}
+export { RequestClient };

package/dist/transport/rest/types.d.ts

@@ -0,0 +1,38 @@
+import type { AxiosResponse, CreateAxiosDefaults, InternalAxiosRequestConfig } from 'axios';
+type RequestResponse<T = any> = AxiosResponse<T>;
+type RequestContentType = 'application/json;charset=utf-8' | 'application/octet-stream;charset=utf-8' | 'application/x-www-form-urlencoded;charset=utf-8' | 'multipart/form-data;charset=utf-8';
+type RequestClientOptions = CreateAxiosDefaults;
+interface RequestInterceptorConfig {
+    fulfilled?: (config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig<any> | Promise<InternalAxiosRequestConfig<any>>;
+    rejected?: (error: any) => any;
+}
+interface ResponseInterceptorConfig<T = any> {
+    fulfilled?: (response: AxiosResponse<T>) => AxiosResponse | Promise<AxiosResponse>;
+    rejected?: (error: any) => any;
+}
+type MakeErrorMessageFn = (message: string, error: any) => void;
+interface HttpResponse {
+    code: number;
+    reason: string;
+    message: string;
+    metadata: object;
+}
+/**
+ * 请求客户端回调接口
+ * 由应用层（bootstrap）注入具体实现，基础设施层不感知业务逻辑
+ */
+interface RequestClientCallbacks {
+    /** 获取当前 access token */
+    getToken: () => string | null;
+    /** 获取当前语言标识（如 zh-CN、en-US） */
+    getLocale?: () => string;
+    /** 刷新 token，返回新的 access token */
+    refreshToken: () => Promise<string>;
+    /** Token 彻底失效时的处理（登出 + 跳转登录页） */
+    onReAuthenticate: (redirect?: boolean) => Promise<void>;
+    /** 错误消息处理（弹窗、toast 等） */
+    onError?: (message: string) => void;
+    /** 从错误对象中提取用户友好的错误消息（可接入 i18n） */
+    getErrorMsg?: (error: unknown) => string;
+}
+export type { RequestClientCallbacks, HttpResponse, MakeErrorMessageFn, RequestClientOptions, RequestContentType, RequestInterceptorConfig, RequestResponse, ResponseInterceptorConfig, };

package/dist/transport/rest/utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 创建更新掩码字符串
+ * @param keys - 字段键名数组
+ * @returns 逗号分隔的字符串
+ */
+export declare function makeUpdateMask(keys: string[]): string;
+/**
+ * 默认的请求 ID 生成器
+ */
+export declare function defaultIdGenerator(): string;
+/**
+ * 默认的错误消息提取（不依赖 i18n，纯逻辑 fallback）
+ * 仅基于 reason；不再回退到后端 message 字段（该字段后续将被移除）。
+ * 如需 i18n 翻译，通过 RequestClientCallbacks.getErrorMsg 注入。
+ */
+export declare function getDefaultErrorMsg(error: unknown): string;

package/dist/transport/sse/event.d.ts

@@ -0,0 +1,44 @@
+/**
+ * SSE 事件名注册表（react 端副本）。
+ *
+ * 真相源是后端 `backend/pkg/sseevent/sseevent.go`：它把常量写进帧的 `event:` 行，
+ * 这里按同名注册回调，中间没有编译期检查（`SSEEventName` 带 `| string`，等于不约束）。
+ * 新增事件要两边同时改；已发布事件的取值不可改——改名等于对线上前端静默断流。
+ */
+export declare const SSE_EVENT: {
+    /**
+     * 站内信收件行推送。
+     *
+     * data 为 `InternalMessageRecipient` 的 protojson：camelCase 键（`messageId` /
+     * `recipientUserId` / `createdAt`），`status` 是枚举名字符串（`RECEIVED` / `READ`），
+     * 与 REST 收件箱接口返回的形状一致。
+     */
+    readonly Notification: "notification";
+    /**
+     * AI 对话流式片段推送。
+     *
+     * data 为 `ChatChunkEvent` 的 protojson：camelCase 键（`conversationId` /
+     * `seq` / `delta`）。一次对话产生多个 chunk 帧，按 conversationId 归组、
+     * seq 顺序累积渲染；POST /admin/v1/ai/chat/completions 的同步响应携带
+     * 完整回复，以响应为准校正累积文本。
+     */
+    readonly AIChatChunk: "ai_chat_chunk";
+    /**
+     * AI 对话的工具调用可见化推送。
+     *
+     * data 为 `ChatToolEvent` 的 protojson：camelCase 键（`conversationId` /
+     * `name` / `arguments` / `result`）。模型每发起一次本地工具调用并执行完成
+     * 后推一帧；工具轮不进消息落库（落库的 assistant 消息只有最终答案），
+     * 本事件是前端展示"模型正在调工具"的唯一信息源（尽力而为，丢帧可容忍）。
+     */
+    readonly AIChatTool: "ai_chat_tool";
+    /**
+     * AI Agent 试运行实时推送。
+     *
+     * data 为 `AgentRunEvent` 的 protojson：camelCase 键（`runId` / `appId` /
+     * `seq` / `phase`（node_start|node_end|error|done） / `nodeId` / `summary` /
+     * `status`）。一次试运行产生多帧；Run 同步响应携带完整 trace 与终态，
+     * 以响应为准校正（尽力而为，丢帧可容忍）。streamId 与对话同为发起用户流。
+     */
+    readonly AgentRun: "ai_agent_run";
+};

package/dist/transport/sse/index.d.ts

@@ -0,0 +1,5 @@
+import { SSEClient } from './sse_client';
+export * from './sse_client';
+export * from './types';
+export * from './event';
+export declare const globalSSEClient: SSEClient;