@tbox-dev-js/sdk 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,1415 @@
+/**
+ * 百宝箱插件服务 SDK - 类型定义
+ */
+/**
+ * SDK 统一响应包装
+ */
+export interface SdkResponse<T = unknown> {
+    /** 是否成功 */
+    success: boolean;
+    /** 响应数据 */
+    data?: T;
+    /** 错误码 */
+    errorCode?: string;
+    /** 错误信息 */
+    errorMsg?: string;
+}
+/**
+ * 文字转语音请求
+ */
+export interface TtsRequest {
+    /** 用户输入文案（必填） */
+    tts_text: string;
+}
+/**
+ * 文字转语音响应
+ */
+export interface TtsResponse {
+    /** Base64 编码的音频数据 */
+    base64Audio?: string;
+}
+/**
+ * 语音转文字请求（Base64 输入）
+ */
+export interface AsrRequest {
+    /** Base64 编码后的音频数据（必填） */
+    base64_audio: string;
+    /** 音频格式，pcm、wav、mp3、mp4，默认 pcm */
+    audio_format?: string;
+}
+/**
+ * 语音转文字响应
+ */
+export interface AsrResponse {
+    /** 识别出的文本 */
+    text?: string;
+}
+/**
+ * 插件工具执行请求
+ */
+export interface PluginToolExecRequest {
+    /** 工具输入参数（key-value 形式，服务端字段名：params） */
+    params?: Record<string, unknown>;
+    /** 扩展参数 */
+    [key: string]: unknown;
+}
+/**
+ * 插件工具执行结果（run 方法返回的 data 字段）
+ *
+ * 对应服务端 Java 类：
+ * ```java
+ * private Boolean success;
+ * private Object result;   // 工具实际输出，结构因工具而异
+ * private long cost;
+ * private String traceId;
+ * ```
+ */
+export interface PluginExecResult {
+    /** 工具执行是否成功 */
+    success?: boolean;
+    /** 工具实际输出数据（结构因工具而异） */
+    result?: unknown;
+    /** 执行耗时（毫秒） */
+    cost?: number;
+    /** 链路追踪 ID */
+    traceId?: string;
+}
+/**
+ * 插件工具信息
+ */
+export interface PluginToolInfo {
+    /** 工具 ID */
+    pluginToolId?: string;
+    /** 工具名称 */
+    name?: string;
+    /** 工具描述 */
+    description?: string;
+    /** 工具请求参数定义 */
+    toolInputParams?: Array<Record<string, unknown>>;
+    /** 工具响应参数定义 */
+    toolOutputParams?: Array<Record<string, unknown>>;
+}
+/**
+ * 插件信息（含工具集）
+ */
+export interface PluginInfo {
+    /** 插件名称 */
+    name?: string;
+    /** 插件描述 */
+    description?: string;
+    /** 插件下的工具列表 */
+    pluginToolList?: PluginToolInfo[];
+}
+/**
+ * 分页查询结果
+ * 服务端实际返回字段：currentPage / data / pageSize / totalCount
+ */
+export interface PaginationResult<T> {
+    /** 数据列表（服务端字段名：data） */
+    data?: T[];
+    /** 总条数（服务端字段名：totalCount） */
+    totalCount?: number;
+    /** 当前页码（服务端字段名：currentPage） */
+    currentPage?: number;
+    /** 每页条数 */
+    pageSize?: number;
+}
+/**
+ * 创建会话请求
+ */
+export interface ConversationCreateRequest {
+    /** 百宝箱应用 ID（agentId） */
+    agentId: string;
+    /** 用户 ID */
+    userId: string;
+}
+/**
+ * 查询会话列表请求
+ */
+export interface ConversationQueryRequest {
+    /** 百宝箱应用 ID */
+    agentId?: string;
+    /** 用户 ID */
+    userId?: string;
+    /** 来源渠道（可选，默认 openapi） */
+    fromSource?: string;
+    /** 页码，从 1 开始（可选） */
+    pageNum?: number;
+    /** 每页条数（可选） */
+    pageSize?: number;
+    /** 扩展参数 */
+    [key: string]: unknown;
+}
+/**
+ * 会话信息
+ * 服务端实际返回字段：id / appId / fromEndUserId / fromSource / gmtCreate
+ */
+export interface ConversationInfo {
+    /** 会话 ID（服务端字段名：id） */
+    id?: string;
+    /** 应用 ID */
+    appId?: string;
+    /** 用户 ID（服务端字段名：fromEndUserId） */
+    fromEndUserId?: string;
+    /** 来源渠道 */
+    fromSource?: string;
+    /** 创建时间（字符串格式，如 "2026-04-09 23:26:18"，服务端字段名：gmtCreate） */
+    gmtCreate?: string;
+    /** 扩展字段 */
+    [key: string]: unknown;
+}
+/**
+ * 查询消息列表请求
+ */
+export interface MessageQueryRequest {
+    /** 会话 ID */
+    conversationId?: string;
+    /** 百宝箱应用 ID（必填，服务端校验非空） */
+    agentId: string;
+    /** 用户 ID */
+    userId?: string;
+    /** 来源渠道（可选，默认 openapi） */
+    fromSource?: string;
+    /** 游标，上页最后一条消息 ID，第一页不填（可选） */
+    beforeId?: string;
+    /** 页码，从 1 开始（可选，服务端字段名：pageNo） */
+    pageNo?: number;
+    /** 每页条数（可选） */
+    pageSize?: number;
+}
+/**
+ * 消息信息
+ */
+export interface MessageInfo {
+    /** 消息 ID */
+    messageId?: string;
+    /** 会话 ID */
+    conversationId?: string;
+    /** 用户提问内容 */
+    query?: string;
+    /** AI 回答内容 */
+    answer?: string;
+    /** 媒体类型 */
+    mediaType?: string;
+    /** 生成状态 */
+    generateState?: string;
+    /** 外部业务 ID */
+    outerBusinessId?: string;
+    /** 创建时间（时间戳） */
+    createTime?: number;
+    /** 扩展字段 */
+    [key: string]: unknown;
+}
+/**
+ * 保存会话消息请求
+ */
+export interface MessageSaveRequest {
+    /** 百宝箱应用 ID（必填，服务端鉴权需要） */
+    agentId: string;
+    /** 会话 ID */
+    conversationId: string;
+    /** 用户提问内容 */
+    query?: string;
+    /** AI 回答内容 */
+    answer?: string;
+    /** 媒体类型（可选） */
+    mediaType?: string;
+    /** 生成状态（可选） */
+    generateState?: string;
+    /** 外部业务 ID（可选） */
+    outerBusinessId?: string;
+    /** 输入参数（可选） */
+    inputs?: Record<string, unknown>;
+    /** 多模态输入（可选） */
+    multiModalInputs?: Record<string, unknown>;
+    /** 额外参数（可选，字符串格式） */
+    extraParams?: string;
+}
+/**
+ * 用户信息条目（key-value 形式）
+ */
+export interface UserInfo {
+    /**
+     * 信息类型，枚举值如：name、phone、email 等
+     * 对应服务端 InfoTypeEnum
+     */
+    infoType: string;
+    /** 信息值 */
+    infoValue: string;
+}
+/**
+ * 设备信息
+ */
+export interface DeviceInfo {
+    /**
+     * 产品类型，如 APP、MINI_PROGRAM 等
+     * 对应服务端 ProductTypeEnum
+     */
+    productType?: string;
+    /** 应用名称 */
+    appName?: string;
+    /** 应用版本号 */
+    appVersion?: string;
+    /**
+     * 系统平台，如 IOS、Android、HarmonyOS 等
+     * 对应服务端 DevicePlatformEnum
+     */
+    platform?: string;
+    /** 系统平台版本号，如 iOS 版本号 */
+    system?: string;
+    /** 设备 ID */
+    deviceId?: string;
+    /** 设备名称 */
+    deviceName?: string;
+    /** 设备型号 */
+    model?: string;
+    /** 设备品牌 */
+    brand?: string;
+}
+/**
+ * 生成 Session 请求
+ */
+export interface AppGenerateSessionRequest {
+    /** 百宝箱应用 ID */
+    appId: string;
+    /** 用户 ID */
+    userId: string;
+    /** 请求来源（可选） */
+    source?: string;
+    /** 发布渠道（可选） */
+    fromSource?: string;
+    /** 请求的链接类型（可选） */
+    type?: string;
+    /** 用户信息列表（可选，用于传递用户扩展属性） */
+    userInfo?: UserInfo[];
+    /** 设备信息（可选） */
+    deviceInfo?: DeviceInfo;
+}
+/**
+ * 生成 Session 响应
+ */
+export interface AppSessionResult {
+    /** 会话 ID，用于免登录访问百宝箱应用 */
+    sessionId?: string;
+    /** 登录渠道，固定值 third_platform_sdk_login */
+    channel?: string;
+}
+/**
+ * 网络搜索请求
+ */
+export interface WebSearchRequest {
+    /** 搜索关键词（必填） */
+    q: string;
+}
+/**
+ * 搜索结果条目的扩展信息
+ */
+export interface WebSearchItemExtra {
+    /** 条目的备用 URL */
+    extraUrl?: string;
+    /** 来源域名，如 quark */
+    domain?: string;
+    /** 排序序号 */
+    sort?: number;
+    /** 备用标题 */
+    extraTitle?: string;
+}
+/**
+ * 单条搜索结果
+ */
+export interface WebSearchItem {
+    /** 文章 ID */
+    articleId?: string;
+    /** 标题 */
+    title?: string;
+    /** 摘要描述 */
+    desc?: string;
+    /** 原始 URL */
+    url?: string;
+    /** 发布时间（Unix 时间戳字符串） */
+    publishTime?: string;
+    /** 来源渠道，如 quark */
+    channel?: string;
+    /** 扩展信息 */
+    extra?: WebSearchItemExtra;
+}
+/**
+ * 网络搜索响应
+ */
+export interface WebSearchResponse {
+    /** 搜索结果列表 */
+    items?: WebSearchItem[];
+}
+/**
+ * TboxPluginClient 初始化配置
+ */
+export interface TboxPluginClientConfig {
+    /**
+     * API Key（Bearer Token），通过 Authorization 头传递。
+     * 格式：直接传 key 字符串，SDK 内部会自动拼接 "Bearer " 前缀。
+     */
+    apiKey: string;
+    /**
+     * 自定义 base URL（可选）。
+     * 默认为 https://o.tbox.cn
+     */
+    baseUrl?: string;
+    /**
+     * 请求超时时间（毫秒，可选）。
+     * 默认不设置超时。
+     */
+    timeout?: number;
+}
+/**
+ * AmapClient 初始化配置
+ */
+export interface AmapClientConfig {
+    /**
+     * API Key（Bearer Token），通过 Authorization 头传递。
+     * 格式：直接传 key 字符串，SDK 内部会自动拼接 "Bearer " 前缀。
+     */
+    apiKey: string;
+    /**
+     * 自定义 base URL（可选）。
+     * 默认为 https://o.tbox.cn
+     */
+    baseUrl?: string;
+    /**
+     * 请求超时时间（毫秒，可选）。
+     * 默认不设置超时。
+     */
+    timeout?: number;
+}
+/**
+ * 高德天气查询请求
+ */
+export interface AmapWeatherRequest {
+    /**
+     * 查询指定城市或地点的天气（必填）。
+     * 可输入：省份名（如：浙江省）、市名（如：杭州市）、区/县/镇（如：西湖区）、
+     * 乡/村（如：西湖区古荡新村）、地点（如：四川省成都市锦江区春熙路街道）
+     */
+    city: string;
+    /**
+     * 查询气象类型（可选）。
+     * base：查询实况天气（默认）；all：查询预报天气
+     */
+    extensions?: string;
+}
+/**
+ * 实况天气数据
+ */
+export interface AmapWeatherLive {
+    /** 省份名 */
+    province?: string;
+    /** 城市名 */
+    city?: string;
+    /** 区域编码 */
+    adcode?: string;
+    /** 实时气温，单位：摄氏度 */
+    temperature?: string;
+    /** 实时气温（浮点数），单位：摄氏度 */
+    temperature_float?: string;
+    /** 空气湿度 */
+    humidity?: string;
+    /** 空气湿度（浮点数） */
+    humidity_float?: string;
+    /** 风力级别，单位：级 */
+    windpower?: string;
+    /** 风向描述 */
+    winddirection?: string;
+    /** 天气现象（汉字描述） */
+    weather?: string;
+    /** 数据发布的时间 */
+    reporttime?: string;
+}
+/**
+ * 单日天气预报
+ */
+export interface AmapWeatherForecastCast {
+    /** 日期 */
+    date?: string;
+    /** 星期几 */
+    week?: string;
+    /** 白天天气现象 */
+    dayweather?: string;
+    /** 白天温度 */
+    daytemp?: string;
+    /** 白天气温（浮点数） */
+    daytemp_float?: string;
+    /** 白天风向 */
+    daywind?: string;
+    /** 白天风力 */
+    daypower?: string;
+    /** 晚上天气现象 */
+    nightweather?: string;
+    /** 晚上温度 */
+    nighttemp?: string;
+    /** 晚上气温（浮点数） */
+    nighttemp_float?: string;
+    /** 晚上风向 */
+    nightwind?: string;
+    /** 晚上风力 */
+    nightpower?: string;
+}
+/**
+ * 预报城市天气信息
+ */
+export interface AmapWeatherForecast {
+    /** 省份名 */
+    province?: string;
+    /** 城市名 */
+    city?: string;
+    /** 区域编码 */
+    adcode?: string;
+    /** 数据发布的时间 */
+    reporttime?: string;
+    /** 逐日预报列表 */
+    casts?: AmapWeatherForecastCast[];
+}
+/**
+ * 高德天气查询响应
+ */
+export interface AmapWeatherResponse {
+    /** 返回状态，1：成功；0：失败 */
+    status?: string;
+    /** 返回的状态信息 */
+    info?: string;
+    /** 返回状态说明，10000 代表正确 */
+    infocode?: string;
+    /** 返回结果总数目 */
+    count?: string;
+    /** 响应状态码 */
+    code?: number;
+    /** 实况天气数据信息（extensions=base 时返回） */
+    lives?: AmapWeatherLive[];
+    /** 预报天气信息数据（extensions=all 时返回） */
+    forecasts?: AmapWeatherForecast[];
+}
+/**
+ * 高德地址转经纬度请求
+ */
+export interface AmapGeocodeRequest {
+    /**
+     * 详细地址信息（必填）。
+     * 可输入：国家、省份、城市、区县、城镇、乡村、街道、门牌号
+     */
+    address: string;
+    /**
+     * 查询的城市（可选）。
+     * 指定查询的城市，可提高查询精度
+     */
+    city?: string;
+}
+/**
+ * 地理编码信息
+ */
+export interface AmapGeocode {
+    /** 格式化地址 */
+    formatted_address?: string;
+    /** 省份 */
+    province?: string;
+    /** 城市 */
+    city?: string;
+    /** 区县 */
+    district?: string;
+    /** 经纬度坐标 */
+    location?: string;
+    /** 区域编码 */
+    adcode?: string;
+    /** 匹配级别 */
+    level?: string;
+}
+/**
+ * 高德地址转经纬度响应
+ */
+export interface AmapGeocodeResponse {
+    /** 响应状态码 */
+    code?: number;
+    /** 返回状态，1：成功；0：失败 */
+    status?: string;
+    /** 错误码 */
+    infocode?: string;
+    /** 返回结果数目 */
+    count?: string;
+    /** 地理编码信息列表 */
+    geocodes?: AmapGeocode[];
+}
+/**
+ * 骑行路线规划请求
+ */
+export interface AmapCyclingRouteRequest {
+    /** 起点位置名称（必填） */
+    origin: string;
+    /** 终点位置名称（必填） */
+    destination: string;
+}
+/**
+ * 骑行路线方案
+ */
+export interface AmapCyclingPath {
+    /** 路线距离（米） */
+    distance?: string;
+    /** 预计时间（秒） */
+    duration?: string;
+    /** 道路名列表 */
+    roads?: Array<{
+        /** 道路名称 */
+        name?: string;
+        /** 道路距离 */
+        distance?: string;
+    }>;
+}
+/**
+ * 骑行路线信息
+ */
+export interface AmapCyclingRoute {
+    /** 起点经纬度 */
+    origin?: string;
+    /** 终点经纬度 */
+    destination?: string;
+    /** 算路方案详情列表 */
+    paths?: AmapCyclingPath[];
+}
+/**
+ * 骑行路线规划响应
+ */
+export interface AmapCyclingRouteResponse {
+    /** 响应状态码 */
+    code?: number;
+    /** 返回状态 */
+    status?: string;
+    /** 错误码 */
+    infocode?: string;
+    /** 路径规划方案总数 */
+    count?: string;
+    /** 规划方案详情 */
+    route?: AmapCyclingRoute;
+}
+/**
+ * IP 定位请求
+ */
+export interface AmapIpLocationRequest {
+    /** 需要搜索的 IP 地址（必填，暂不支持 IPv6） */
+    ip: string;
+}
+/**
+ * IP 定位响应
+ */
+export interface AmapIpLocationResponse {
+    /** 响应状态码 */
+    code?: number;
+    /** 错误码 */
+    infocode?: string;
+    /** 省份名称 */
+    province?: string;
+    /** 城市名称 */
+    city?: string;
+    /** 城市的 adcode 编码 */
+    adcode?: string;
+}
+/**
+ * 周边搜索请求
+ */
+export interface AmapPeripheralSearchRequest {
+    /** 中心点地址信息（必填） */
+    address: string;
+    /** 检索关键词（必填，景点、美食、游玩区域等，不超过 80 字符） */
+    keyword: string;
+    /** 返回条数（可选，默认 5） */
+    count?: number;
+    /** 搜索半径（米，可选，范围 0-50000） */
+    radius?: number;
+}
+/**
+ * POI 信息
+ */
+export interface AmapPoi {
+    /** POI 的 ID */
+    id?: string;
+    /** 名称 */
+    name?: string;
+    /** 类型 */
+    type?: string;
+    /** 类型编码 */
+    typecode?: string;
+    /** 地址 */
+    address?: string;
+    /** 经纬度坐标 */
+    location?: string;
+    /** 距离中心点的距离（米） */
+    distance?: string;
+    /** 电话 */
+    tel?: string;
+    /** 扩展信息 */
+    [key: string]: unknown;
+}
+/**
+ * 周边搜索响应
+ */
+export interface AmapPeripheralSearchResponse {
+    /** 响应状态码 */
+    code?: number;
+    /** 结果状态值，0 或 1 */
+    status?: string;
+    /** 错误码 */
+    infocode?: string;
+    /** 返回结果总数 */
+    count?: string;
+    /** POI 信息列表 */
+    pois?: AmapPoi[];
+}
+/**
+ * 步行路线规划请求
+ */
+export interface AmapWalkingRouteRequest {
+    /** 起点地址（必填） */
+    origin: string;
+    /** 终点地址（必填） */
+    destination: string;
+}
+/**
+ * 步行路线方案
+ */
+export interface AmapWalkingPath {
+    /** 路线距离（米） */
+    distance?: string;
+    /** 预计时间（秒） */
+    duration?: string;
+    /** 步行引导信息 */
+    steps?: Array<{
+        /** 指令 */
+        instruction?: string;
+        /** 道路名称 */
+        road?: string;
+        /** 距离 */
+        distance?: string;
+    }>;
+}
+/**
+ * 步行路线信息
+ */
+export interface AmapWalkingRoute {
+    /** 起点坐标 */
+    origin?: string;
+    /** 终点坐标 */
+    destination?: string;
+    /** 算路方案详情列表 */
+    paths?: AmapWalkingPath[];
+}
+/**
+ * 步行路线规划响应
+ */
+export interface AmapWalkingRouteResponse {
+    /** 响应状态码 */
+    code?: number;
+    /** 返回状态，1 成功，0 失败 */
+    status?: string;
+    /** 错误码 */
+    infocode?: string;
+    /** 路径规划方案总数 */
+    count?: string;
+    /** 规划方案详情 */
+    route?: AmapWalkingRoute;
+}
+/**
+ * 驾车路线规划请求
+ */
+export interface AmapDrivingRouteRequest {
+    /** 起点地址或经纬度（必填） */
+    origin: string;
+    /** 终点地址或经纬度（必填） */
+    destination: string;
+}
+/**
+ * 驾车路线方案
+ */
+export interface AmapDrivingPath {
+    /** 路线距离（米） */
+    distance?: string;
+    /** 预计时间（秒） */
+    duration?: string;
+    /** 预估策略 */
+    strategy?: string;
+    /** 高速费用（元） */
+    tolls?: string;
+    /** 高速距离（米） */
+    tollDistance?: string;
+    /** 步骤信息 */
+    steps?: unknown[];
+}
+/**
+ * 驾车路线信息
+ */
+export interface AmapDrivingRoute {
+    /** 起点经纬度 */
+    origin?: string;
+    /** 终点经纬度 */
+    destination?: string;
+    /** 预计出租车费用（元） */
+    taxi_cost?: string;
+    /** 算路方案详情列表 */
+    paths?: AmapDrivingPath[];
+}
+/**
+ * 驾车路线规划响应
+ */
+export interface AmapDrivingRouteResponse {
+    /** 响应状态码 */
+    code?: number;
+    /** 返回状态，1 成功，0 失败 */
+    status?: string;
+    /** 错误码 */
+    infocode?: string;
+    /** 路径规划方案总数 */
+    count?: string;
+    /** 规划方案详情 */
+    route?: AmapDrivingRoute;
+}
+/**
+ * 电动车路线规划请求
+ */
+export interface AmapEbikeRouteRequest {
+    /** 起点地址或经纬度（必填） */
+    origin: string;
+    /** 终点地址或经纬度（必填） */
+    destination: string;
+}
+/**
+ * 电动车路线方案
+ */
+export interface AmapEbikePath {
+    /** 路线距离（米） */
+    distance?: string;
+    /** 预计时间（秒） */
+    duration?: string;
+    /** 道路信息 */
+    roads?: unknown[];
+}
+/**
+ * 电动车路线信息
+ */
+export interface AmapEbikeRoute {
+    /** 起点坐标 */
+    origin?: string;
+    /** 终点坐标 */
+    destination?: string;
+    /** 算路方案列表 */
+    paths?: AmapEbikePath[];
+}
+/**
+ * 电动车路线规划响应
+ */
+export interface AmapEbikeRouteResponse {
+    /** 响应状态码 */
+    code?: number;
+    /** 返回状态，1 成功，0 失败 */
+    status?: string;
+    /** 错误码 */
+    infocode?: string;
+    /** 返回结果总数目 */
+    count?: string;
+    /** 路线信息 */
+    route?: AmapEbikeRoute;
+}
+/**
+ * 公交路线规划请求
+ */
+export interface AmapTransitRouteRequest {
+    /** 起点地址或经纬度（必填） */
+    origin: string;
+    /** 终点地址或经纬度（必填） */
+    destination: string;
+}
+/**
+ * 公交换乘方案成本
+ */
+export interface AmapTransitCost {
+    /** 票价（元） */
+    transitCost?: string;
+}
+/**
+ * 公交换乘方案
+ */
+export interface AmapTransitItem {
+    /** 方案花费（元） */
+    cost?: string;
+    /** 方案预计时间（秒） */
+    duration?: string;
+    /** 步行距离（米） */
+    walkingDistance?: string;
+    /** 换乘详情 */
+    segments?: unknown[];
+}
+/**
+ * 公交路线信息
+ */
+export interface AmapTransitRoute {
+    /** 起点坐标 */
+    origin?: string;
+    /** 终点坐标 */
+    destination?: string;
+    /** 起点和终点的步行距离 */
+    distance?: string;
+    /** 换乘方案价格 */
+    cost?: AmapTransitCost;
+    /** 公交换乘方案列表 */
+    transits?: AmapTransitItem[];
+}
+/**
+ * 公交路线规划响应
+ */
+export interface AmapTransitRouteResponse {
+    /** 结果状态值，0 或 1 */
+    status?: string;
+    /** 错误码 */
+    infocode?: string;
+    /** 返回状态说明 */
+    info?: string;
+    /** 公交换乘方案数目 */
+    count?: string;
+    /** 路线信息 */
+    route?: AmapTransitRoute;
+}
+/**
+ * 行政区域查询请求
+ */
+export interface AmapDistrictRequest {
+    /** 查询关键字（必填，行政区名称、citycode、adcode） */
+    keywords: string;
+}
+/**
+ * 行政区信息
+ */
+export interface AmapDistrict {
+    /** 行政区编码 */
+    adcode?: string;
+    /** 城市编码 */
+    citycode?: string;
+    /** 行政区名称 */
+    name?: string;
+    /** 中心点坐标 */
+    center?: string;
+    /** 行政区级别 */
+    level?: string;
+    /** 下级行政区列表 */
+    districts?: AmapDistrict[];
+}
+/**
+ * 行政区建议信息
+ */
+export interface AmapDistrictSuggestion {
+    /** 建议关键字列表 */
+    keywords?: string[];
+    /** 建议城市列表 */
+    cities?: string[];
+}
+/**
+ * 行政区域查询响应
+ */
+export interface AmapDistrictResponse {
+    /** 响应状态码 */
+    code?: number;
+    /** 错误码 */
+    infocode?: string;
+    /** 一级行政区总数 */
+    count?: string;
+    /** 行政区列表 */
+    districts?: AmapDistrict[];
+    /** 建议结果列表 */
+    suggestion?: AmapDistrictSuggestion;
+}
+/**
+ * 经纬度转地址请求
+ */
+export interface AmapRegeocodeRequest {
+    /** 经纬度坐标（必填，经度在前，纬度在后，英文逗号分隔） */
+    location: string;
+    /** 返回数据类型（可选）：base（基本地址）/ all（详细信息） */
+    extensions?: string;
+}
+/**
+ * 地址组成元素
+ */
+export interface AmapAddressComponent {
+    /** 省份 */
+    province?: string;
+    /** 城市 */
+    city?: string;
+    /** 城市编码 */
+    citycode?: string;
+    /** 区县 */
+    district?: string;
+    /** 区域编码 */
+    adcode?: string;
+    /** 街道 */
+    township?: string;
+    /** 门牌号 */
+    streetNumber?: string;
+    /** 扩展信息 */
+    [key: string]: unknown;
+}
+/**
+ * 逆地理编码结果
+ */
+export interface AmapRegeocode {
+    /** 格式化后的地址信息 */
+    formatted_address?: string;
+    /** 地址元素列表 */
+    addressComponent?: AmapAddressComponent;
+}
+/**
+ * 经纬度转地址响应
+ */
+export interface AmapRegeocodeResponse {
+    /** 响应状态码 */
+    code?: number;
+    /** 返回结果状态值 */
+    status?: string;
+    /** 返回状态说明 */
+    info?: string;
+    /** 逆地理编码结果 */
+    regeocode?: AmapRegeocode;
+}
+/**
+ * 坐标转换请求
+ */
+export interface AmapConvertRequest {
+    /** 坐标点（必填，经纬度用逗号分隔，多个坐标用 "|" 分隔，最多 40 个） */
+    locations: string;
+    /** 原坐标系（必填）：gps / mapbar / baidu / autonavi */
+    coordsys: string;
+}
+/**
+ * 坐标转换响应
+ */
+export interface AmapConvertResponse {
+    /** 响应状态码 */
+    code?: number;
+    /** 返回状态，1 成功，0 失败 */
+    status?: string;
+    /** 返回的状态信息 */
+    info?: string;
+    /** 高德错误码 */
+    infocode?: string;
+    /** 转换后的坐标（多个用 ";" 分隔） */
+    locations?: string;
+}
+/**
+ * POI 关键字搜索请求
+ */
+export interface AmapPoiSearchRequest {
+    /** 查询关键字（可选） */
+    keywords?: string;
+    /** 指定地点类型（可选） */
+    types?: string;
+    /** 搜索区划（可选，默认全国） */
+    region?: string;
+    /** 是否限制在 region 内（可选）：true / false */
+    city_limit?: string;
+    /** 每页数据条数（可选，1-25） */
+    page_size?: string;
+    /** 分页页码（可选，1-100） */
+    page_num?: string;
+}
+/**
+ * POI 关键字搜索响应
+ */
+export interface AmapPoiSearchResponse {
+    /** 响应状态码 */
+    code?: number;
+    /** 返回状态，1 成功，0 失败 */
+    status?: string;
+    /** 错误码 */
+    infocode?: string;
+    /** 单次请求返回的 POI 点个数 */
+    count?: string;
+    /** POI 完整集合 */
+    pois?: AmapPoi[];
+}
+/**
+ * KnowledgeClient 初始化配置
+ */
+export interface KnowledgeClientConfig {
+    /**
+     * API Key（Bearer Token），通过 Authorization 头传递。
+     * 格式：直接传 key 字符串，SDK 内部会自动拼接 "Bearer " 前缀。
+     */
+    apiKey: string;
+    /**
+     * 自定义 base URL（可选）。
+     * 默认为 https://o.tbox.cn
+     */
+    baseUrl?: string;
+    /**
+     * 请求超时时间（毫秒，可选）。
+     * 默认不设置超时。
+     */
+    timeout?: number;
+}
+/**
+ * 表格列定义
+ */
+export interface TableSchemaColumn {
+    /** 数据类型：STRING, NUMBER, BOOLEAN 等 */
+    dataType?: string;
+    /** 字段描述 */
+    description?: string;
+    /** 是否字段索引 */
+    fieldIndexed?: boolean;
+    /** 是否索引 */
+    indexed?: boolean;
+    /** 字段名称 */
+    name: string;
+    /** 字段顺序 */
+    order?: number;
+    /** 是否主键 */
+    primaryKey?: boolean;
+    /** 是否必填 */
+    required?: boolean;
+    /** 前端组件类型 */
+    'x-component'?: string;
+    /** 默认值 */
+    default_value?: string;
+}
+/**
+ * 表格 Schema 定义
+ */
+export interface TableSchema {
+    /** 列定义列表 */
+    columns?: TableSchemaColumn[];
+    /** 字段映射关系 */
+    fieldMap?: Record<string, unknown>;
+    /** Formily 表单 Schema */
+    formilySchema?: Record<string, unknown>;
+    /** 表格名称 */
+    name?: string;
+    /** 表格描述 */
+    description?: string;
+}
+/**
+ * 创建知识库请求
+ */
+export interface KnowledgeCreateRequest {
+    /**
+     * 上传的文件（必填）。
+     * 支持格式：.xlsx、.pdf 等
+     */
+    file: File | Blob;
+    /**
+     * 数据类型（必填）。
+     * STRUCTURED：结构化数据；其他类型：非结构化数据
+     */
+    type: string;
+    /**
+     * 表格 Schema 定义（条件必填）。
+     * 当 type = STRUCTURED 时必填
+     */
+    tableSchema?: TableSchema;
+    /**
+     * 索引列名列表（条件必填）。
+     * 当 type = STRUCTURED 时必填
+     */
+    indexColumns?: string[];
+}
+/**
+ * 创建知识库响应
+ */
+export interface KnowledgeCreateResponse {
+    /** 处理请求的主机名 */
+    hostName?: string;
+    /** 结果信息 */
+    result?: {
+        /** 错误类型 */
+        errorType?: string;
+        /** 响应详情 */
+        response?: {
+            /** 创建后的文档 ID（用于后续更新操作） */
+            documentId?: string;
+        };
+        /** 业务处理是否成功 */
+        success?: boolean;
+    };
+    /** 请求是否成功 */
+    success?: boolean;
+    /** 链路追踪 ID */
+    traceId?: string;
+}
+/**
+ * 更新知识库请求
+ */
+export interface KnowledgeUpdateRequest {
+    /**
+     * 上传的文件（必填）。
+     * 支持格式：.xlsx、.pdf 等
+     */
+    file: File | Blob;
+    /**
+     * 数据类型（必填）。
+     * STRUCTURED：结构化数据；其他类型：非结构化数据
+     */
+    type: string;
+    /**
+     * 要更新的文档 ID（必填）。
+     * 从创建响应中获取
+     */
+    documentId: string;
+    /**
+     * 表格 Schema 定义（可选）。
+     * 结构化数据需要
+     */
+    tableSchema?: TableSchema;
+    /**
+     * 更新模式（可选）。
+     * OVERWRITE：覆盖更新；UPSERT：增量更新（默认）
+     */
+    updateMode?: 'OVERWRITE' | 'UPSERT';
+}
+/**
+ * 更新知识库响应
+ */
+export interface KnowledgeUpdateResponse {
+    /** 处理请求的主机名 */
+    hostName?: string;
+    /** 结果信息 */
+    result?: {
+        /** 错误类型 */
+        errorType?: string;
+        /** 响应详情 */
+        response?: {
+            /** 更新后的文档 ID */
+            documentId?: string;
+        };
+        /** 业务处理是否成功 */
+        success?: boolean;
+    };
+    /** 请求是否成功 */
+    success?: boolean;
+    /** 链路追踪 ID */
+    traceId?: string;
+}
+/**
+ * 查询知识库列表请求
+ */
+export interface KnowledgeQueryListRequest {
+    /**
+     * 知识库名称（支持模糊查询）。
+     */
+    name?: string;
+    /**
+     * 页码，从 1 开始（可选，默认 1）
+     */
+    pageNo?: number;
+    /**
+     * 每页条数（可选，默认 10）
+     */
+    pageSize?: number;
+}
+/**
+ * 知识库信息
+ */
+export interface KnowledgeDatasetInfo {
+    /** 知识库 ID */
+    datasetId?: string;
+    /** 知识库名称 */
+    name?: string;
+    /** 存储大小 */
+    storeSize?: number;
+    /** 数据类型：STRUCTURED / UNSTRUCTURED */
+    type?: string;
+}
+/**
+ * 查询知识库列表响应
+ */
+export interface KnowledgeQueryListResponse {
+    /** 当前页码 */
+    currentPage?: number;
+    /** 知识库列表 */
+    datasets?: KnowledgeDatasetInfo[];
+    /** 每页条数 */
+    pageSize?: number;
+    /** 总条数 */
+    total?: number;
+}
+/**
+ * 检索知识库请求
+ */
+export interface KnowledgeRetrieveRequest {
+    /**
+     * 知识库名称（优先使用）。
+     * 如果提供 name，SDK 会自动查询获取 datasetId。
+     * name 和 datasetId 至少提供一个
+     */
+    name?: string;
+    /**
+     * 知识库 ID（可选）。
+     * 如果同时提供 name 和 datasetId，优先使用 datasetId。
+     * 如果只提供 name，SDK 会自动查询获取 datasetId
+     */
+    datasetId?: string;
+    /**
+     * 查询内容（必填）。
+     * 自然语言描述
+     */
+    query: string;
+}
+/**
+ * 检索结果条目
+ */
+export interface KnowledgeRetrieveItem {
+    /** 检索到的内容片段 */
+    content?: string;
+    /** 原始文件名 */
+    originFileName?: string;
+    /** 相关度分数（0-1，越高越相关） */
+    score?: number;
+}
+/**
+ * 检索知识库响应
+ */
+export interface KnowledgeRetrieveResponse {
+    /** 检索结果数组（直接作为 data 字段返回） */
+    data?: KnowledgeRetrieveItem[];
+    /** 错误码（"0"表示成功） */
+    errorCode?: string;
+    /** 错误信息 */
+    errorMsg?: string;
+    /** 请求是否成功 */
+    success?: boolean;
+    /** 链路追踪 ID */
+    traceId?: string;
+}
+/**
+ * LlmClient 初始化配置
+ */
+export interface LlmClientConfig {
+    /**
+     * API Key（Bearer Token），通过 Authorization 头传递。
+     * 格式：直接传 key 字符串，SDK 内部会自动拼接 "Bearer " 前缀。
+     */
+    apiKey: string;
+    /**
+     * 自定义 base URL（可选）。
+     * 默认为 https://o.tbox.cn
+     */
+    baseUrl?: string;
+    /**
+     * 请求超时时间（毫秒，可选）。
+     * 默认不设置超时。
+     */
+    timeout?: number;
+}
+/**
+ * 对话消息
+ */
+export interface ChatMessage {
+    /** 角色：system / user / assistant */
+    role: 'system' | 'user' | 'assistant';
+    /** 消息内容 */
+    content: string;
+}
+/**
+ * 流式选项
+ */
+export interface StreamOptions {
+    /** 是否在末尾 chunk 返回 token 用量 */
+    include_usage?: boolean;
+}
+/**
+ * Chat Completions 请求
+ */
+export interface ChatCompletionRequest {
+    /** 模型名称（必填） */
+    model: string;
+    /** 对话消息列表（必填） */
+    messages: ChatMessage[];
+    /** 是否流式输出，默认 false */
+    stream?: boolean;
+    /** 流式选项 */
+    stream_options?: StreamOptions;
+    /** 温度参数，范围 0~2 */
+    temperature?: number;
+    /** 核采样参数，范围 0~1，推荐 0.95 */
+    top_p?: number;
+    /** 最大输出 token 数，推荐 8000 */
+    max_tokens?: number;
+}
+/**
+ * Chat Completions 响应（非流式）
+ */
+export interface ChatCompletionResponse {
+    /** 响应 ID */
+    id?: string;
+    /** 选择列表 */
+    choices?: ChatCompletionChoice[];
+    /** 创建时间戳 */
+    created?: number;
+    /** 模型名称 */
+    model?: string;
+    /** 对象类型 */
+    object?: string;
+    /** Token 用量 */
+    usage?: {
+        /** 输入 token 数 */
+        prompt_tokens?: number;
+        /** 输出 token 数 */
+        completion_tokens?: number;
+        /** 总 token 数 */
+        total_tokens?: number;
+    };
+}
+/**
+ * 非流式响应的选择项
+ */
+export interface ChatCompletionChoice {
+    /** 索引 */
+    index?: number;
+    /** 消息内容 */
+    message?: ChatMessage;
+    /** 结束原因：stop / length / content_filter 等 */
+    finish_reason?: string | null;
+}
+/**
+ * Chat Completions 流式响应块
+ */
+export interface ChatCompletionChunk {
+    /** 响应 ID */
+    id?: string;
+    /** 选择列表 */
+    choices?: ChatCompletionChunkChoice[];
+    /** 创建时间戳 */
+    created?: number;
+    /** 模型名称 */
+    model?: string;
+    /** 对象类型 */
+    object?: string;
+    /** 系统指纹 */
+    system_fingerprint?: string;
+    /** Token 用量（仅在 stream_options.include_usage=true 时，最后一个 chunk 携带） */
+    usage?: {
+        /** 输入 token 数 */
+        prompt_tokens?: number;
+        /** 输出 token 数 */
+        completion_tokens?: number;
+        /** 总 token 数 */
+        total_tokens?: number;
+    };
+}
+/**
+ * 流式响应的选择项
+ */
+export interface ChatCompletionChunkChoice {
+    /** 索引 */
+    index?: number;
+    /** 增量内容 */
+    delta?: {
+        /** 角色（仅首个 chunk 包含） */
+        role?: 'system' | 'user' | 'assistant';
+        /** 文本片段 */
+        content?: string;
+        /** 推理内容片段（推理模型如 glm-5v-turbo 返回） */
+        reasoning_content?: string;
+    };
+    /** 结束原因：stop / length / content_filter 等，正常结束为 stop */
+    finish_reason?: string | null;
+}