@h-ai/core 0.1.0-alpha5

package/dist/core-util-module-B-wH5_ZT.d.ts

@@ -0,0 +1,1626 @@
+import { z } from 'zod';
+
+/**
+ * @h-ai/core — 核心配置 Schema
+ *
+ * 核心模块的配置 Schema 定义（使用 Zod 校验）
+ * @module core-config
+ */
+
+/**
+ * 环境类型 Schema。
+ *
+ * @example
+ * ```ts
+ * EnvSchema.parse('development')
+ * ```
+ */
+declare const EnvSchema: z.ZodEnum<{
+    development: "development";
+    production: "production";
+    test: "test";
+    staging: "staging";
+}>;
+type Env = z.infer<typeof EnvSchema>;
+/**
+ * 日志级别 Schema。
+ *
+ * @example
+ * ```ts
+ * LogLevelSchema.parse('info')
+ * ```
+ */
+declare const LogLevelSchema: z.ZodEnum<{
+    trace: "trace";
+    debug: "debug";
+    info: "info";
+    warn: "warn";
+    error: "error";
+    fatal: "fatal";
+}>;
+type LogLevel = z.infer<typeof LogLevelSchema>;
+/**
+ * 日志格式 Schema。
+ *
+ * @example
+ * ```ts
+ * LogFormatSchema.parse('json')
+ * ```
+ */
+declare const LogFormatSchema: z.ZodEnum<{
+    json: "json";
+    pretty: "pretty";
+}>;
+type LogFormat = z.infer<typeof LogFormatSchema>;
+/**
+ * 日志配置 Schema。
+ *
+ * @example 最小配置（全部使用默认值）
+ * ```ts
+ * LoggingConfigSchema.parse({})
+ * // => { level: 'info', format: 'json', redact: [] }
+ * ```
+ *
+ * @example 开发环境（pretty 格式 + debug 级别）
+ * ```ts
+ * LoggingConfigSchema.parse({ level: 'debug', format: 'pretty' })
+ * // => { level: 'debug', format: 'pretty', redact: [] }
+ * ```
+ *
+ * @example 带上下文与脱敏
+ * ```ts
+ * LoggingConfigSchema.parse({
+ *   level: 'warn',
+ *   format: 'json',
+ *   context: { service: 'api-gateway', region: 'us-east-1' },
+ *   redact: ['password', 'token', 'headers.authorization'],
+ * })
+ * // => { level: 'warn', format: 'json', context: { service: 'api-gateway', region: 'us-east-1' }, redact: ['password', 'token', 'headers.authorization'] }
+ * ```
+ *
+ * @example 在 _core.yml 中配置
+ * ```yaml
+ * logging:
+ *   level: info
+ *   format: json
+ *   context:
+ *     service: my-app
+ *   redact:
+ *     - password
+ *     - token
+ * ```
+ */
+declare const LoggingConfigSchema: z.ZodObject<{
+    level: z.ZodDefault<z.ZodEnum<{
+        trace: "trace";
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+        error: "error";
+        fatal: "fatal";
+    }>>;
+    format: z.ZodDefault<z.ZodEnum<{
+        json: "json";
+        pretty: "pretty";
+    }>>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    redact: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type LoggingConfig = z.infer<typeof LoggingConfigSchema>;
+/**
+ * ID 生成器配置 Schema。
+ *
+ * @example
+ * ```ts
+ * IdConfigSchema.parse({ length: 12 })
+ * // => { length: 12 }
+ *
+ * IdConfigSchema.parse({ prefix: 'usr_', length: 16 })
+ * // => { prefix: 'usr_', length: 16 }
+ * ```
+ */
+declare const IdConfigSchema: z.ZodObject<{
+    prefix: z.ZodOptional<z.ZodString>;
+    length: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type IdConfig = z.infer<typeof IdConfigSchema>;
+/**
+ * Core 配置 Schema。
+ *
+ * 描述应用的基础配置，通常通过 `_core.yml` 加载。
+ *
+ * @example
+ * ```ts
+ * CoreConfigSchema.parse({ name: 'demo', env: 'production' })
+ * // => { name: 'demo', version: '0.1.0', env: 'production', debug: false, defaultLocale: 'zh-CN' }
+ * ```
+ */
+declare const CoreConfigSchema: z.ZodObject<{
+    name: z.ZodDefault<z.ZodString>;
+    version: z.ZodDefault<z.ZodString>;
+    env: z.ZodDefault<z.ZodEnum<{
+        development: "development";
+        production: "production";
+        test: "test";
+        staging: "staging";
+    }>>;
+    debug: z.ZodDefault<z.ZodBoolean>;
+    logging: z.ZodOptional<z.ZodObject<{
+        level: z.ZodDefault<z.ZodEnum<{
+            trace: "trace";
+            debug: "debug";
+            info: "info";
+            warn: "warn";
+            error: "error";
+            fatal: "fatal";
+        }>>;
+        format: z.ZodDefault<z.ZodEnum<{
+            json: "json";
+            pretty: "pretty";
+        }>>;
+        context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        redact: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    id: z.ZodOptional<z.ZodObject<{
+        prefix: z.ZodOptional<z.ZodString>;
+        length: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    defaultLocale: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+type CoreConfig = z.infer<typeof CoreConfigSchema>;
+
+/**
+ * @h-ai/core — 错误注册与处理
+ *
+ * 提供统一的错误定义生成与实例化能力。
+ *
+ * @module core-function-error
+ */
+
+/**
+ * 根据模块错误映射生成标准错误定义对象。
+ *
+ * 将错误信息映射（如 `{ CONFIG_NOT_FOUND: '010:500' }`）转换为结构化的 HaiErrorDef，
+ * 自动组装完整的错误码（格式：`system:module:code`）以及对应的 HTTP 状态码。
+ *
+ * @template T - 错误信息映射的类型
+ *
+ * @param module - 模块名称（如 'core'、'db'、'api'），会作为错误码的第二段
+ * @param errorInfo - 错误信息映射对象，值格式为 `'错误码数字:HTTP状态码'`（如 `'010:500'`）
+ * @param system - 系统标识，默认 'hai'，会作为错误码的第一段
+ *
+ * @returns 返回同类型的错误定义对象，每个 key 对应一个 HaiErrorDef 对象
+ *
+ * @example
+ * ```ts
+ * const ConfigErrorInfo = {
+ *   FILE_NOT_FOUND: '010:500',
+ *   PARSE_ERROR: '011:500',
+ *   VALIDATION_ERROR: '012:500',
+ * } as const
+ *
+ * const ConfigError = buildHaiErrorsDef('core', ConfigErrorInfo)
+ * // =>
+ * // ConfigError.FILE_NOT_FOUND = {
+ * //   code: 'hai:core:010',
+ * //   httpStatus: 500,
+ * //   system: 'hai',
+ * //   module: 'core',
+ * // }
+ * ```
+ */
+declare function buildHaiErrorsDef<T extends Record<string, string>>(module: string, errorInfo: T, system?: string): {
+    [K in keyof T]: HaiErrorDef;
+};
+/**
+ * 根据错误定义创建错误实例。
+ *
+ * 将 HaiErrorDef（错误定义）扩展为 HaiError（运行时错误实例），
+ * 添加具体的错误消息、原因和建议等运行时信息。
+ *
+ * @param def - 错误定义对象（通常由 buildHaiErrorsDef 生成）
+ * @param message - 错误消息（描述此次具体发生了什么）
+ * @param cause - 原始错误原因（可选，用于链式错误追踪）
+ * @param suggestion - 用户可采取的建议（可选，如 "'请检查配置文件格式'）
+ *
+ * @returns 返回完整的 HaiError 实例，包含错误码、HTTP 状态、消息、原因和建议
+ *
+ * @example
+ * ```ts
+ * const err = buildHaiErrorInst(
+ *   HaiConfigError.FILE_NOT_FOUND,
+ *   'config.yml 文件不存在',
+ *   new Error('ENOENT: no such file'),
+ *   '请确保 _core.yml 在项目根目录'
+ * )
+ * // => {
+ * //   code: 'hai:core:010',
+ * //   httpStatus: 500,
+ * //   system: 'hai',
+ * //   module: 'core',
+ * //   message: 'config.yml 文件不存在',
+ * //   cause: Error('ENOENT: no such file'),
+ * //   suggestion: '请确保 _core.yml 在项目根目录'
+ * // }
+ * ```
+ */
+declare function buildHaiErrorInst(def: HaiErrorDef, message: string, cause?: unknown, suggestion?: string): HaiError;
+declare const error: {
+    buildHaiErrorsDef: typeof buildHaiErrorsDef;
+    buildHaiErrorInst: typeof buildHaiErrorInst;
+};
+/** error 子工具类型 */
+type ErrorFn = typeof error;
+
+/**
+ * @h-ai/core — ID 生成器
+ *
+ * 基于 nanoid 的 ID 生成工具。
+ * @module core-function-id
+ */
+/**
+ * ID 生成工具对象。
+ *
+ * @example
+ * ```ts
+ * const id1 = id.generate()
+ * const id2 = id.short()
+ * ```
+ */
+declare const id: {
+    /**
+     * 生成标准 nanoid（默认 21 字符）。
+     *
+     * @param length - ID 长度
+     * @returns nanoid 字符串
+     *
+     * @example
+     * ```ts
+     * const id = core.id.generate(16)
+     * ```
+     */
+    generate(length?: number): string;
+    /**
+     * 生成短 ID（10 字符）。
+     *
+     * @example
+     * ```ts
+     * const shortId = core.id.short()
+     * ```
+     */
+    short(): string;
+    /**
+     * 生成带前缀的 ID。
+     *
+     * @param prefix - 前缀
+     * @param length - ID 长度
+     *
+     * @example
+     * ```ts
+     * const userId = core.id.withPrefix('user_')
+     * ```
+     */
+    withPrefix(prefix: string, length?: number): string;
+    /**
+     * 生成 Trace ID。
+     *
+     * @example
+     * ```ts
+     * const traceId = core.id.trace()
+     * ```
+     */
+    trace(): string;
+    /**
+     * 生成 Request ID。
+     *
+     * @example
+     * ```ts
+     * const requestId = core.id.request()
+     * ```
+     */
+    request(): string;
+    /**
+     * 生成 UUID v4。
+     *
+     * @example
+     * ```ts
+     * const uuid = core.id.uuid()
+     * ```
+     */
+    uuid(): string;
+    /**
+     * 验证是否为有效的 UUID v4。
+     *
+     * @example
+     * ```ts
+     * core.id.isValidUUID('f47ac10b-58cc-4372-a567-0e02b2c3d479')
+     * ```
+     */
+    isValidUUID(uuid: string): boolean;
+    /**
+     * 验证是否为有效的 nanoid。
+     *
+     * @param str - 待验证字符串
+     * @param length - 期望长度
+     *
+     * @example
+     * ```ts
+     * core.id.isValidNanoId('abc', 3)
+     * ```
+     */
+    isValidNanoId(str: string, length?: number): boolean;
+};
+/** id 子工具类型 */
+type IdFn = typeof id;
+
+/**
+ * @h-ai/core — i18n 国际化工具
+ *
+ * 国际化核心实现，为 JSON 消息字典提供通用类型支持。
+ * @module core-i18n-utils
+ */
+
+declare function getGlobalLocale(): Locale;
+declare function setGlobalLocale(locale: Locale): void;
+/**
+ * 创建消息获取函数。
+ *
+ * 各模块通过此函数创建自己的消息获取器，自动读取全局 locale。
+ * 若指定的 locale 不支持，回退到默认语言；key 不存在时返回 key 本身。
+ *
+ * @param messages - 多语言消息对象
+ * @returns 消息获取函数
+ *
+ * @example
+ * ```ts
+ * const getMessage = createMessageGetter({
+ *   'zh-CN': { hello: '你好' },
+ *   'en-US': { hello: 'Hello' },
+ * })
+ * getMessage('hello')                              // '你好'
+ * getMessage('hello', { locale: 'en-US' })          // 'Hello'
+ * getMessage('msg', { params: { name: 'World' } }) // 插值
+ * ```
+ */
+declare function createMessageGetter<K extends string>(messages: LocaleMessages<K>): (key: K, options?: MessageOptions) => string;
+declare const i18n: {
+    DEFAULT_LOCALES: LocaleInfo[];
+    DEFAULT_LOCALE: string;
+    setGlobalLocale: typeof setGlobalLocale;
+    getGlobalLocale: typeof getGlobalLocale;
+    createMessageGetter: typeof createMessageGetter;
+    coreM: (key: "$schema" | "core_errorUnknown" | "core_errorNetwork" | "core_errorTimeout" | "core_errorNotFound" | "core_errorUnauthorized" | "core_errorForbidden" | "core_errorValidation" | "core_errorInternal" | "core_actionConfirm" | "core_actionCancel" | "core_actionSave" | "core_actionDelete" | "core_actionEdit" | "core_actionCreate" | "core_actionUpdate" | "core_actionSearch" | "core_actionReset" | "core_actionSubmit" | "core_actionLoading" | "core_actionRetry" | "core_statusSuccess" | "core_statusFailed" | "core_statusPending" | "core_statusProcessing" | "core_statusCompleted" | "core_statusCancelled" | "core_validationRequired" | "core_validationMinLength" | "core_validationMaxLength" | "core_validationEmail" | "core_validationUrl" | "core_validationNumber" | "core_validationInteger" | "core_validationPositive" | "core_validationPattern" | "core_timeJustNow" | "core_timeSecondsAgo" | "core_timeMinutesAgo" | "core_timeHoursAgo" | "core_timeDaysAgo" | "core_timeWeeksAgo" | "core_timeMonthsAgo" | "core_timeYearsAgo" | "core_browserFeatureUnsupported" | "core_configEnvVarMissing" | "core_configFileNotExist" | "core_configParseFailed" | "core_configValidationFailed" | "core_configNotLoaded", options?: MessageOptions) => string;
+};
+/** i18n 子工具类型 */
+type I18nFn = typeof i18n;
+
+/**
+ * @h-ai/core — 数组操作工具
+ * @module core-util-array
+ */
+/**
+ * 数组去重。
+ * @param arr - 输入数组
+ * @returns 去重后的新数组
+ * @remarks 保留首次出现的顺序；空数组返回空数组。
+ *
+ * @example
+ * ```ts
+ * array.unique([1, 1, 2]) // [1, 2]
+ * ```
+ */
+declare function unique<T>(arr: T[]): T[];
+/**
+ * 按条件分组。
+ * @param arr - 输入数组
+ * @param fn - 分组键生成函数
+ * @returns 分组结果对象
+ * @remarks 当数组为空时返回空对象。
+ *
+ * @example
+ * ```ts
+ * array.groupBy([{ r: 'a' }, { r: 'b' }], item => item.r)
+ * ```
+ */
+declare function groupBy<T, K extends string | number>(arr: T[], fn: (item: T) => K): Record<K, T[]>;
+/**
+ * 分割为指定大小的块。
+ * @param arr - 输入数组
+ * @param size - 每块大小（应为正整数）
+ * @returns 分块后的二维数组
+ * @remarks size <= 0 时结果为空数组。
+ *
+ * @example
+ * ```ts
+ * array.chunk([1, 2, 3], 2) // [[1,2],[3]]
+ * ```
+ */
+declare function chunk<T>(arr: T[], size: number): T[][];
+/**
+ * 获取第一个元素。
+ * @param arr - 输入数组
+ * @returns 第一个元素或 undefined
+ * @remarks 空数组返回 undefined。
+ *
+ * @example
+ * ```ts
+ * array.first([1, 2, 3]) // 1
+ * ```
+ */
+declare function first<T>(arr: T[]): T | undefined;
+/**
+ * 获取最后一个元素。
+ * @param arr - 输入数组
+ * @returns 最后一个元素或 undefined
+ * @remarks 空数组返回 undefined。
+ *
+ * @example
+ * ```ts
+ * array.last([1, 2, 3]) // 3
+ * ```
+ */
+declare function last<T>(arr: T[]): T | undefined;
+/**
+ * 数组扁平化。
+ * @param arr - 二维数组
+ * @returns 扁平化后的数组
+ * @remarks 仅扁平一层。
+ *
+ * @example
+ * ```ts
+ * array.flatten([[1], [2, 3]]) // [1, 2, 3]
+ * ```
+ */
+declare function flatten<T>(arr: T[][]): T[];
+/**
+ * 过滤掉 null 和 undefined。
+ * @param arr - 输入数组
+ * @returns 过滤后的数组
+ * @remarks 会保留 0、false、'' 等假值。
+ *
+ * @example
+ * ```ts
+ * array.compact([0, null, 1]) // [0, 1]
+ * ```
+ */
+declare function compact<T>(arr: (T | null | undefined)[]): T[];
+/**
+ * 随机打乱数组。
+ * @param arr - 输入数组
+ * @returns 打乱后的新数组
+ * @remarks 不修改原数组。
+ *
+ * @example
+ * ```ts
+ * const shuffled = array.shuffle([1, 2, 3])
+ * ```
+ */
+declare function shuffle<T>(arr: T[]): T[];
+/**
+ * 取数组交集。
+ * @param arr1 - 数组 1
+ * @param arr2 - 数组 2
+ * @returns 交集数组
+ * @remarks 保持 arr1 中的顺序。
+ *
+ * @example
+ * ```ts
+ * array.intersection([1, 2], [2, 3]) // [2]
+ * ```
+ */
+declare function intersection<T>(arr1: T[], arr2: T[]): T[];
+/**
+ * 取数组差集。
+ * @param arr1 - 数组 1
+ * @param arr2 - 数组 2
+ * @returns 差集数组（arr1 中存在且 arr2 不存在）
+ * @remarks 保持 arr1 中的顺序。
+ *
+ * @example
+ * ```ts
+ * array.difference([1, 2, 3], [2]) // [1, 3]
+ * ```
+ */
+declare function difference<T>(arr1: T[], arr2: T[]): T[];
+/**
+ * 数组操作工具对象。
+ *
+ * @example
+ * ```ts
+ * array.unique([1, 1, 2])
+ * ```
+ */
+declare const array: {
+    unique: typeof unique;
+    groupBy: typeof groupBy;
+    chunk: typeof chunk;
+    first: typeof first;
+    last: typeof last;
+    flatten: typeof flatten;
+    compact: typeof compact;
+    shuffle: typeof shuffle;
+    intersection: typeof intersection;
+    difference: typeof difference;
+};
+/** array 子工具类型 */
+type ArrayFn = typeof array;
+
+/**
+ * @h-ai/core — 异步操作工具
+ * @module core-util-async
+ */
+/**
+ * 延迟执行。
+ *
+ * @param ms - 延迟毫秒数
+ * @returns 延迟完成后的 Promise
+ *
+ * @example
+ * ```ts
+ * await async.delay(1000)
+ * ```
+ */
+declare function delay(ms: number): Promise<void>;
+/**
+ * 添加超时限制。
+ *
+ * @param promise - 目标 Promise
+ * @param ms - 超时时间（毫秒）
+ * @returns 原 Promise 的结果
+ * @throws 超时将抛出错误
+ *
+ * @example
+ * ```ts
+ * await async.withTimeout(fetch('/api'), 5000)
+ * ```
+ */
+declare function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T>;
+/**
+ * 重试操作。
+ *
+ * @param fn - 待重试函数
+ * @param options - 重试配置
+ * @param options.maxRetries - 最大重试次数
+ * @param options.delay - 重试间隔（毫秒）
+ * @returns 成功的结果
+ * @throws 重试耗尽后抛出最后一次错误
+ *
+ * @example
+ * ```ts
+ * await async.retry(() => fetch('/api'), { maxRetries: 3, delay: 500 })
+ * ```
+ */
+declare function retry<T>(fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    delay?: number;
+}): Promise<T>;
+/**
+ * 并行执行，限制并发数。
+ *
+ * @param items - 输入列表
+ * @param fn - 处理函数
+ * @param concurrency - 最大并发数
+ * @returns 处理结果列表
+ * @remarks 结果顺序与输入顺序一致。
+ *
+ * @example
+ * ```ts
+ * await async.parallel([1, 2, 3], async n => n * 2, 2)
+ * ```
+ */
+declare function parallel<T, R>(items: T[], fn: (item: T, index: number) => Promise<R>, concurrency?: number): Promise<R[]>;
+/**
+ * 串行执行。
+ *
+ * @param items - 输入列表
+ * @param fn - 处理函数
+ * @returns 处理结果列表
+ *
+ * @example
+ * ```ts
+ * await async.serial([1, 2], async n => n * 2)
+ * ```
+ */
+declare function serial<T, R>(items: T[], fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+/**
+ * 防抖。
+ *
+ * @param fn - 目标函数
+ * @param ms - 延迟毫秒数
+ * @returns 防抖后的函数
+ * @remarks 只会在最后一次调用后执行。
+ *
+ * @example
+ * ```ts
+ * const onInput = async.debounce(() => {}, 300)
+ * ```
+ */
+declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, ms: number): (...args: Parameters<T>) => void;
+/**
+ * 节流。
+ *
+ * @param fn - 目标函数
+ * @param ms - 间隔毫秒数
+ * @returns 节流后的函数
+ * @remarks 在时间窗口内最多触发一次。
+ *
+ * @example
+ * ```ts
+ * const onScroll = async.throttle(() => {}, 200)
+ * ```
+ */
+declare function throttle<T extends (...args: unknown[]) => unknown>(fn: T, ms: number): (...args: Parameters<T>) => void;
+/**
+ * 异步操作工具对象。
+ *
+ * @example
+ * ```ts
+ * await async.delay(100)
+ * ```
+ */
+declare const async: {
+    delay: typeof delay;
+    withTimeout: typeof withTimeout;
+    retry: typeof retry;
+    parallel: typeof parallel;
+    serial: typeof serial;
+    debounce: typeof debounce;
+    throttle: typeof throttle;
+};
+/** async 子工具类型 */
+type AsyncFn = typeof async;
+
+/**
+ * @h-ai/core — 对象操作工具
+ * @module core-util-object
+ */
+/**
+ * 深度克隆对象。
+ * 使用 structuredClone（Node 17+ / 现代浏览器），支持 Date、Map、Set、RegExp、
+ * ArrayBuffer、循环引用等 JSON 方案无法处理的类型。
+ *
+ * @param obj - 目标对象
+ * @returns 深度克隆结果
+ *
+ * @example
+ * ```ts
+ * const cloned = object.deepClone({ a: 1, d: new Date() })
+ * ```
+ */
+declare function deepClone<T>(obj: T): T;
+/**
+ * 深度合并多个对象。
+ * @param objects - 需要合并的对象列表
+ * @returns 合并后的新对象
+ * @remarks 仅合并纯对象字段，数组会被直接覆盖。
+ *
+ * @example
+ * ```ts
+ * const merged = object.deepMerge({ a: 1 }, { b: 2 })
+ * ```
+ */
+declare function deepMerge<T extends Record<string, unknown>>(...objects: Partial<T>[]): T;
+/**
+ * 从对象中选取指定的键。
+ * @param obj - 目标对象
+ * @param keys - 要选取的键列表
+ * @returns 仅包含指定键的新对象
+ *
+ * @example
+ * ```ts
+ * object.pick({ a: 1, b: 2 }, ['a'])
+ * ```
+ */
+declare function pick<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
+/**
+ * 从对象中排除指定的键。
+ * @param obj - 目标对象
+ * @param keys - 要排除的键列表
+ * @returns 排除指定键后的新对象
+ *
+ * @example
+ * ```ts
+ * object.omit({ a: 1, b: 2 }, ['b'])
+ * ```
+ */
+declare function omit<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
+/**
+ * 获取对象的所有键。
+ * @param obj - 目标对象
+ * @returns 键列表
+ *
+ * @example
+ * ```ts
+ * object.keys({ a: 1, b: 2 })
+ * ```
+ */
+declare function keys<T extends Record<string, unknown>>(obj: T): (keyof T)[];
+/**
+ * 获取对象的所有值。
+ * @param obj - 目标对象
+ * @returns 值列表
+ *
+ * @example
+ * ```ts
+ * object.values({ a: 1, b: 2 })
+ * ```
+ */
+declare function values<T extends Record<string, unknown>>(obj: T): T[keyof T][];
+/**
+ * 获取对象的键值对数组。
+ * @param obj - 目标对象
+ * @returns 键值对数组
+ *
+ * @example
+ * ```ts
+ * object.entries({ a: 1 })
+ * ```
+ */
+declare function entries<T extends Record<string, unknown>>(obj: T): [keyof T, T[keyof T]][];
+/**
+ * 从键值对数组创建对象。
+ * @param entries - 键值对数组
+ * @returns 生成的对象
+ *
+ * @example
+ * ```ts
+ * object.fromEntries([['a', 1]])
+ * ```
+ */
+declare function fromEntries<K extends string, V>(entries: [K, V][]): Record<K, V>;
+/**
+ * 对象操作工具对象。
+ *
+ * @example
+ * ```ts
+ * object.deepMerge({ a: 1 }, { b: 2 })
+ * ```
+ */
+declare const object: {
+    deepClone: typeof deepClone;
+    deepMerge: typeof deepMerge;
+    pick: typeof pick;
+    omit: typeof omit;
+    keys: typeof keys;
+    values: typeof values;
+    entries: typeof entries;
+    fromEntries: typeof fromEntries;
+};
+/** object 子工具类型 */
+type ObjectFn = typeof object;
+
+/**
+ * @h-ai/core — 字符串操作工具
+ * @module core-util-string
+ */
+/**
+ * 首字母大写。
+ * @param str - 输入字符串
+ * @returns 首字母大写后的字符串
+ * @remarks 空字符串返回空字符串。
+ *
+ * @example
+ * ```ts
+ * string.capitalize('hello') // 'Hello'
+ * ```
+ */
+declare function capitalize(str: string): string;
+/**
+ * 转换为 kebab-case。
+ * @param str - 输入字符串
+ * @returns kebab-case 字符串
+ * @remarks 支持连续大写字母拆分（如 `getHTTPSUrl` → `get-https-url`）。
+ *
+ * @example
+ * ```ts
+ * string.kebabCase('helloWorld') // 'hello-world'
+ * string.kebabCase('getHTTPSUrl') // 'get-https-url'
+ * ```
+ */
+declare function kebabCase(str: string): string;
+/**
+ * 转换为 camelCase。
+ * @param str - 输入字符串
+ * @returns camelCase 字符串
+ * @remarks 仅处理包含 '-' 的字符串。
+ *
+ * @example
+ * ```ts
+ * string.camelCase('hello-world') // 'helloWorld'
+ * ```
+ */
+declare function camelCase(str: string): string;
+/**
+ * 截断字符串。
+ * @param str - 输入字符串
+ * @param length - 最大长度（小于等于 0 时返回原字符串）
+ * @param suffix - 超出长度时的后缀
+ * @returns 截断后的字符串
+ *
+ * @example
+ * ```ts
+ * string.truncate('hello world', 5) // 'hello...'
+ * ```
+ */
+declare function truncate(str: string, length: number, suffix?: string): string;
+/**
+ * 转换为 snake_case。
+ * @param str - 输入字符串
+ * @returns snake_case 字符串
+ * @remarks 支持连续大写字母拆分（如 `getHTTPSUrl` → `get_https_url`）。
+ *
+ * @example
+ * ```ts
+ * string.snakeCase('helloWorld') // 'hello_world'
+ * string.snakeCase('getHTTPSUrl') // 'get_https_url'
+ * ```
+ */
+declare function snakeCase(str: string): string;
+/**
+ * 转换为 PascalCase。
+ * @param str - 输入字符串
+ * @returns PascalCase 字符串
+ * @remarks 支持 '-' 与 '_' 分隔。
+ *
+ * @example
+ * ```ts
+ * string.pascalCase('hello-world') // 'HelloWorld'
+ * ```
+ */
+declare function pascalCase(str: string): string;
+/**
+ * 移除字符串两端的空白。
+ * @param str - 输入字符串
+ * @returns 去除两端空白后的字符串
+ *
+ * @example
+ * ```ts
+ * string.trim('  hi  ') // 'hi'
+ * ```
+ */
+declare function trim(str: string): string;
+/**
+ * 检查字符串是否为空或只包含空白。
+ * @param str - 输入字符串
+ * @returns 是否为空或全空白
+ *
+ * @example
+ * ```ts
+ * string.isBlank('   ') // true
+ * ```
+ */
+declare function isBlank(str: string): boolean;
+/**
+ * 检查字符串是否不为空。
+ * @param str - 输入字符串
+ * @returns 是否非空
+ *
+ * @example
+ * ```ts
+ * string.isNotBlank('ok') // true
+ * ```
+ */
+declare function isNotBlank(str: string): boolean;
+/**
+ * 填充字符串到指定长度（左侧）。
+ * @param str - 输入字符串
+ * @param length - 目标长度
+ * @param char - 填充字符
+ * @returns 填充后的字符串
+ *
+ * @example
+ * ```ts
+ * string.padStart('1', 3, '0') // '001'
+ * ```
+ */
+declare function padStart(str: string, length: number, char?: string): string;
+/**
+ * 填充字符串到指定长度（右侧）。
+ * @param str - 输入字符串
+ * @param length - 目标长度
+ * @param char - 填充字符
+ * @returns 填充后的字符串
+ *
+ * @example
+ * ```ts
+ * string.padEnd('1', 3, '0') // '100'
+ * ```
+ */
+declare function padEnd(str: string, length: number, char?: string): string;
+/**
+ * 常量时间字符串比较。
+ *
+ * 防止时序侧信道攻击：无论输入差异位置如何，执行时间恒定。
+ * 兼容 Node.js 与浏览器环境（纯 JS 实现，无平台依赖）。
+ *
+ * @param a - 字符串 a
+ * @param b - 字符串 b
+ * @returns 是否相等
+ *
+ * @example
+ * ```ts
+ * string.constantTimeEqual('abc', 'abc') // true
+ * string.constantTimeEqual('abc', 'abd') // false
+ * ```
+ */
+declare function constantTimeEqual(a: string, b: string): boolean;
+/**
+ * 字符串操作工具对象。
+ *
+ * @example
+ * ```ts
+ * string.capitalize('hello')
+ * ```
+ */
+declare const string: {
+    capitalize: typeof capitalize;
+    kebabCase: typeof kebabCase;
+    camelCase: typeof camelCase;
+    truncate: typeof truncate;
+    snakeCase: typeof snakeCase;
+    pascalCase: typeof pascalCase;
+    trim: typeof trim;
+    isBlank: typeof isBlank;
+    isNotBlank: typeof isNotBlank;
+    padStart: typeof padStart;
+    padEnd: typeof padEnd;
+    constantTimeEqual: typeof constantTimeEqual;
+};
+/** string 子工具类型 */
+type StringFn = typeof string;
+
+/**
+ * @h-ai/core — 时间操作工具
+ * @module core-util-time
+ */
+/**
+ * 格式化日期。
+ * @param date - 日期对象
+ * @param format - 格式模板（默认 YYYY-MM-DD）
+ * @returns 格式化后的字符串
+ *
+ * @example
+ * ```ts
+ * time.formatDate(new Date(), 'YYYY-MM-DD')
+ * ```
+ */
+declare function formatDate(date: Date, format?: string): string;
+/**
+ * 相对时间描述。
+ * @param date - 目标日期
+ * @returns 相对时间文案
+ * @remarks 使用 i18n 消息返回结果。
+ *
+ * @example
+ * ```ts
+ * time.timeAgo(new Date(Date.now() - 60000))
+ * ```
+ */
+declare function timeAgo(date: Date): string;
+/**
+ * 获取当前时间戳（毫秒）。
+ * @returns 当前时间戳（毫秒）
+ *
+ * @example
+ * ```ts
+ * const ts = time.now()
+ * ```
+ */
+declare function now(): number;
+/**
+ * 获取当前时间戳（秒）。
+ * @returns 当前时间戳（秒）
+ *
+ * @example
+ * ```ts
+ * const ts = time.nowSeconds()
+ * ```
+ */
+declare function nowSeconds(): number;
+/**
+ * 解析日期字符串。
+ * @param dateStr - 日期字符串
+ * @returns Date 对象
+ * @remarks 无效字符串将生成 Invalid Date。
+ *
+ * @example
+ * ```ts
+ * const date = time.parseDate('2024-01-01')
+ * ```
+ */
+declare function parseDate(dateStr: string): Date;
+/**
+ * 判断是否为有效日期。
+ * @param date - Date 对象
+ * @returns 是否为有效日期
+ *
+ * @example
+ * ```ts
+ * time.isValidDate(new Date('invalid')) // false
+ * ```
+ */
+declare function isValidDate(date: Date): boolean;
+/**
+ * 添加天数。
+ * @param date - 原始日期
+ * @param days - 增加天数（可为负数）
+ * @returns 新的日期对象
+ *
+ * @example
+ * ```ts
+ * time.addDays(new Date(), 7)
+ * ```
+ */
+declare function addDays(date: Date, days: number): Date;
+/**
+ * 添加小时。
+ * @param date - 原始日期
+ * @param hours - 增加小时（可为负数）
+ * @returns 新的日期对象
+ *
+ * @example
+ * ```ts
+ * time.addHours(new Date(), 1)
+ * ```
+ */
+declare function addHours(date: Date, hours: number): Date;
+/**
+ * 获取日期的开始时间（00:00:00）。
+ * @param date - 目标日期
+ * @returns 当天开始时间
+ *
+ * @example
+ * ```ts
+ * time.startOfDay(new Date())
+ * ```
+ */
+declare function startOfDay(date: Date): Date;
+/**
+ * 获取日期的结束时间（23:59:59）。
+ * @param date - 目标日期
+ * @returns 当天结束时间
+ *
+ * @example
+ * ```ts
+ * time.endOfDay(new Date())
+ * ```
+ */
+declare function endOfDay(date: Date): Date;
+/**
+ * 时间操作工具对象。
+ *
+ * @example
+ * ```ts
+ * time.formatDate(new Date())
+ * ```
+ */
+declare const time: {
+    formatDate: typeof formatDate;
+    timeAgo: typeof timeAgo;
+    now: typeof now;
+    nowSeconds: typeof nowSeconds;
+    parseDate: typeof parseDate;
+    isValidDate: typeof isValidDate;
+    addDays: typeof addDays;
+    addHours: typeof addHours;
+    startOfDay: typeof startOfDay;
+    endOfDay: typeof endOfDay;
+};
+/** time 子工具类型 */
+type TimeFn = typeof time;
+
+/**
+ * @h-ai/core — 类型检查工具
+ * @module core-util-type
+ */
+/**
+ * 检查值是否已定义（非 null 和 undefined）。
+ * @param value - 待检查值
+ * @returns 是否已定义
+ *
+ * @example
+ * ```ts
+ * typeUtils.isDefined(0) // true
+ * ```
+ */
+declare function isDefined<T>(value: T | undefined | null): value is T;
+/**
+ * 检查值是否为纯对象（排除数组）。
+ * @param value - 待检查值
+ * @returns 是否为纯对象
+ *
+ * @example
+ * ```ts
+ * typeUtils.isObject({}) // true
+ * ```
+ */
+declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * 检查值是否为函数。
+ * @param value - 待检查值
+ * @returns 是否为函数
+ *
+ * @example
+ * ```ts
+ * typeUtils.isFunction(() => {}) // true
+ * ```
+ */
+declare function isFunction(value: unknown): value is (...args: unknown[]) => unknown;
+/**
+ * 检查值是否为 Promise。
+ * @param value - 待检查值
+ * @returns 是否为 Promise
+ *
+ * @example
+ * ```ts
+ * typeUtils.isPromise(Promise.resolve()) // true
+ * ```
+ */
+declare function isPromise<T>(value: unknown): value is Promise<T>;
+/**
+ * 检查值是否为字符串。
+ * @param value - 待检查值
+ * @returns 是否为字符串
+ *
+ * @example
+ * ```ts
+ * typeUtils.isString('a') // true
+ * ```
+ */
+declare function isString(value: unknown): value is string;
+/**
+ * 检查值是否为数字。
+ * @param value - 待检查值
+ * @returns 是否为数字（排除 NaN）
+ *
+ * @example
+ * ```ts
+ * typeUtils.isNumber(1) // true
+ * ```
+ */
+declare function isNumber(value: unknown): value is number;
+/**
+ * 检查值是否为布尔值。
+ * @param value - 待检查值
+ * @returns 是否为布尔值
+ *
+ * @example
+ * ```ts
+ * typeUtils.isBoolean(false) // true
+ * ```
+ */
+declare function isBoolean(value: unknown): value is boolean;
+/**
+ * 检查值是否为数组。
+ * @param value - 待检查值
+ * @returns 是否为数组
+ *
+ * @example
+ * ```ts
+ * typeUtils.isArray([1, 2]) // true
+ * ```
+ */
+declare function isArray<T = unknown>(value: unknown): value is T[];
+/**
+ * 类型检查工具对象。
+ *
+ * @example
+ * ```ts
+ * typeUtils.isDefined('x')
+ * ```
+ */
+declare const typeUtils: {
+    isDefined: typeof isDefined;
+    isObject: typeof isObject;
+    isFunction: typeof isFunction;
+    isPromise: typeof isPromise;
+    isString: typeof isString;
+    isNumber: typeof isNumber;
+    isBoolean: typeof isBoolean;
+    isArray: typeof isArray;
+};
+/** typeUtils 子工具类型 */
+type TypeUtilFn = typeof typeUtils;
+
+/**
+ * @h-ai/core — 类型定义
+ *
+ * 核心模块的公共类型（前后端通用）
+ * @module core-types
+ */
+
+type HaiResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: HaiError;
+};
+declare function ok<T>(data: T): HaiResult<T>;
+declare function err(errorOrDef: HaiErrorDef | HaiError | Error, message?: string, cause?: unknown, suggestion?: string): HaiResult<never>;
+/**
+ * HaiResult 模式匹配处理器。
+ *
+ * 提供对 HaiResult 的模式匹配能力，分别处理成功和失败两种情况。
+ *
+ * @template T - 成功数据类型
+ * @template R1 - ok 分支返回类型
+ * @template R2 - err 分支返回类型
+ *
+ * @example
+ * ```ts
+ * const handlers: MatchHandlers<number, number, number> = {
+ *   ok: n => n + 1,
+ *   err: () => 0,
+ * }
+ * ```
+ */
+interface MatchHandlers<T, R1, R2> {
+    /** 成功分支处理器 */
+    ok: (data: T) => R1;
+    /** 失败分支处理器 */
+    err: (error: HaiError) => R2;
+}
+/** 错误信息值格式：`错误码数字段:HTTP状态码`，例如 `001:500`。 */
+type ErrorInfoValue = `${string}:${string}`;
+/** 模块错误信息映射。 */
+type ErrorInfo = Record<string, ErrorInfoValue>;
+interface HaiErrorDef {
+    code: string | number;
+    httpStatus: number;
+    system: string;
+    module: string;
+}
+interface HaiError {
+    code: string | number;
+    message: string;
+    httpStatus?: number;
+    system?: string;
+    module?: string;
+    cause?: unknown;
+    suggestion?: string;
+    ext?: Record<string, unknown>;
+}
+declare const HaiCommonError: {
+    readonly NOT_INITIALIZED: HaiErrorDef;
+    readonly INIT_FAILED: HaiErrorDef;
+    readonly INIT_IN_PROGRESS: HaiErrorDef;
+    readonly UNAUTHORIZED: HaiErrorDef;
+    readonly FORBIDDEN: HaiErrorDef;
+    readonly TOKEN_EXPIRED: HaiErrorDef;
+    readonly TOKEN_INVALID: HaiErrorDef;
+    readonly VALIDATION_ERROR: HaiErrorDef;
+    readonly INVALID_REQUEST: HaiErrorDef;
+    readonly PARAMETER_MISSING: HaiErrorDef;
+    readonly NOT_FOUND: HaiErrorDef;
+    readonly ALREADY_EXISTS: HaiErrorDef;
+    readonly CONFLICT: HaiErrorDef;
+    readonly API_ERROR: HaiErrorDef;
+    readonly NETWORK_ERROR: HaiErrorDef;
+    readonly TIMEOUT: HaiErrorDef;
+    readonly SERVICE_UNAVAILABLE: HaiErrorDef;
+    readonly INTERNAL_ERROR: HaiErrorDef;
+    readonly DATABASE_ERROR: HaiErrorDef;
+    readonly UNKNOWN_ERROR: HaiErrorDef;
+};
+declare const HaiConfigError: {
+    readonly CONFIG_FILE_NOT_FOUND: HaiErrorDef;
+    readonly CONFIG_PARSE_ERROR: HaiErrorDef;
+    readonly CONFIG_VALIDATION_ERROR: HaiErrorDef;
+    readonly CONFIG_ENV_VAR_MISSING: HaiErrorDef;
+    readonly CONFIG_NOT_LOADED: HaiErrorDef;
+};
+/**
+ * 分页参数输入（可选字段，未提供时使用默认值）。
+ *
+ * @example
+ * ```ts
+ * const input: PaginationOptionsInput = { page: 2, pageSize: 20 }
+ * ```
+ */
+interface PaginationOptionsInput {
+    /** 页码（从 1 开始，默认 1） */
+    page?: number;
+    /** 每页数量（默认由业务层决定） */
+    pageSize?: number;
+}
+/**
+ * 分页参数（必填，已确定具体值）。
+ *
+ * @example
+ * ```ts
+ * const options: PaginationOptions = { page: 1, pageSize: 20 }
+ * ```
+ */
+interface PaginationOptions {
+    /** 页码（从 1 开始） */
+    page: number;
+    /** 每页数量 */
+    pageSize: number;
+}
+/**
+ * 分页结果。
+ *
+ * @template T - 数据项类型
+ *
+ * @example
+ * ```ts
+ * const result: PaginatedResult<User> = {
+ *   items: [{ id: 1, name: 'Alice' }],
+ *   total: 100,
+ *   page: 1,
+ *   pageSize: 20,
+ * }
+ * ```
+ */
+interface PaginatedResult<T> {
+    /** 当前页数据 */
+    items: T[];
+    /** 总数量 */
+    total: number;
+    /** 页码（从 1 开始） */
+    page: number;
+    /** 每页数量 */
+    pageSize: number;
+}
+/**
+ * 日志上下文。
+ *
+ * @example
+ * ```ts
+ * const context: LogContext = { requestId: 'req-1' }
+ * ```
+ */
+interface LogContext {
+    timestamp?: Date;
+    level?: LogLevel;
+    message?: string;
+    [key: string]: unknown;
+}
+/**
+ * 日志选项。
+ *
+ * @example
+ * ```ts
+ * const options: LoggerOptions = { name: 'api', level: 'debug' }
+ * ```
+ */
+interface LoggerOptions {
+    name?: string;
+    level?: LogLevel;
+    format?: LogFormat;
+    context?: Record<string, unknown>;
+}
+/**
+ * Logger 接口。
+ * 统一的日志记录接口，具体实现由 Provider 提供。
+ *
+ * @example
+ * ```ts
+ * core.logger.info('ready', { requestId: 'req-1' })
+ * ```
+ */
+interface Logger {
+    trace: (message: string, context?: LogContext) => void;
+    debug: (message: string, context?: LogContext) => void;
+    info: (message: string, context?: LogContext) => void;
+    warn: (message: string, context?: LogContext) => void;
+    error: (message: string, context?: LogContext) => void;
+    fatal: (message: string, context?: LogContext) => void;
+    child: (context: Record<string, unknown>) => Logger;
+}
+/**
+ * Core 公共 Logger — Logger 实例 + 管理方法。
+ *
+ * @example
+ * ```ts
+ * core.logger.info('ready')
+ * core.logger.configure({ level: 'debug' })
+ * core.logger.setLevel('warn')
+ * const level = core.logger.getLevel()
+ * const db = core.logger.create({ name: 'db' })
+ * ```
+ */
+interface CoreLogger extends Logger {
+    /** 创建新的 Logger 实例 */
+    create: (options?: LoggerOptions) => Logger;
+    /** 配置全局 Logger 选项（级别、格式、上下文等） */
+    configure: (config: Partial<LoggingConfig>) => void;
+    /** 设置全局日志级别 */
+    setLevel: (level: LogLevel) => void;
+    /** 获取当前全局日志级别 */
+    getLevel: () => LogLevel;
+}
+/**
+ * Logger 函数组合（平台实现依赖）。
+ *
+ * 由各平台（Node.js / Browser）提供具体实现，通过 `createCore()` 注入。
+ *
+ * @example
+ * ```ts
+ * const fns: LoggerFunctions = {
+ *   createLogger,
+ *   getLogger,
+ *   configureLogger,
+ *   setLogLevel,
+ *   getLogLevel,
+ * }
+ * ```
+ */
+interface LoggerFunctions {
+    /** 创建新的 Logger 实例 */
+    createLogger: (options?: LoggerOptions) => Logger;
+    /** 获取默认或命名 Logger 实例（单例） */
+    getLogger: (name?: string) => Logger;
+    /** 配置全局 Logger 选项（级别、格式、上下文等） */
+    configureLogger: (config: Partial<LoggingConfig>) => void;
+    /** 设置全局日志级别 */
+    setLogLevel: (level: LogLevel) => void;
+    /** 获取当前全局日志级别 */
+    getLogLevel: () => LogLevel;
+}
+/**
+ * Core 配置选项。
+ *
+ * @example
+ * ```ts
+ * const options: CoreOptions = { configDir: './config', watchConfig: true }
+ * ```
+ */
+interface CoreOptions {
+    /** 日志配置 */
+    logging?: Partial<LoggingConfig>;
+    /**
+     * 配置目录（约定优于配置模式）
+     *
+     * 指定后会自动扫描目录中的 yml/yaml 文件：
+     * - `_core.yml` → 自动使用 CoreConfigSchema 校验
+     * - `_xx.yml` → 加载为 'xx'（各模块自行调用 `config.validate` 校验）
+     * - `app.yml` → 加载为 'app'（需使用方自行校验）
+     *
+     * @example
+     * ```ts
+     * core.init({ configDir: './config' })
+     * ```
+     */
+    configDir?: string;
+    /** 是否启用配置文件监听（默认 false） */
+    watchConfig?: boolean;
+}
+/**
+ * 语言代码（ISO 639-1 + 地区代码）。
+ *
+ * @example 'zh-CN', 'en-US', 'ja-JP'
+ */
+type Locale = string;
+/**
+ * 语言信息。
+ *
+ * @example
+ * ```ts
+ * const locale: LocaleInfo = { code: 'zh-CN', label: '简体中文' }
+ * ```
+ */
+interface LocaleInfo {
+    /** 语言代码（如 'zh-CN'、'en-US'） */
+    code: Locale;
+    /** 显示名称（如 '简体中文'、'English'） */
+    label: string;
+    /** 是否为从右到左书写的语言（如阿拉伯语），默认 false */
+    rtl?: boolean;
+}
+/**
+ * 插值参数类型。
+ *
+ * 用于 i18n 消息模板中的 `{key}` 占位符替换。
+ *
+ * @example
+ * ```ts
+ * const params: InterpolationParams = { name: 'Alice', count: 3 }
+ * // 模板 'Hello, {name}! You have {count} items.'
+ * ```
+ */
+type InterpolationParams = Record<string, string | number | boolean>;
+/**
+ * 消息字典类型（单语言的 key-value 映射）。
+ *
+ * @example
+ * ```ts
+ * const dict: MessageDictionary = { hello: '你好', bye: '再见' }
+ * ```
+ */
+type MessageDictionary = Record<string, string>;
+/**
+ * 多语言消息集合。
+ *
+ * 以 locale 为键，每个 locale 下包含该语言的所有消息 key-value。
+ *
+ * @template K - 消息 key 的联合类型
+ *
+ * @example
+ * ```ts
+ * const messages: LocaleMessages<'hello' | 'bye'> = {
+ *   'zh-CN': { hello: '你好', bye: '再见' },
+ *   'en-US': { hello: 'Hello', bye: 'Bye' },
+ * }
+ * ```
+ */
+type LocaleMessages<K extends string = string> = Record<Locale, Record<K, string>>;
+/**
+ * 消息获取选项。
+ *
+ * @example
+ * ```ts
+ * getMessage('hello', { locale: 'en-US', params: { name: 'World' } })
+ * ```
+ */
+interface MessageOptions {
+    /** 指定 locale（不传则使用全局 locale） */
+    locale?: Locale;
+    /** 插值参数 */
+    params?: InterpolationParams;
+}
+/** Core 服务聚合接口（createCore 返回类型） */
+interface CoreFunctions {
+    /** 默认 Logger（懒加载单例），同时提供日志管理方法 */
+    readonly logger: CoreLogger;
+    /** 国际化工具 */
+    readonly i18n: I18nFn;
+    /** ID 生成工具 */
+    readonly id: IdFn;
+    /** 类型检查工具 */
+    readonly typeUtils: TypeUtilFn;
+    /** 对象操作工具 */
+    readonly object: ObjectFn;
+    /** 字符串操作工具 */
+    readonly string: StringFn;
+    /** 数组操作工具 */
+    readonly array: ArrayFn;
+    /** 异步操作工具 */
+    readonly async: AsyncFn;
+    /** 时间操作工具 */
+    readonly time: TimeFn;
+    /** 错误工具 */
+    readonly error: ErrorFn;
+    /** 模块基础工具 */
+    readonly module: ModuleFn;
+}
+
+/**
+ * @h-ai/core — 模块初始化工具
+ *
+ * 封装各模块共同的「未初始化」错误处理模式，消除跨模块冗余。
+ * @module core-util-module
+ */
+
+/**
+ * 未初始化工具集返回类型。
+ *
+ * 提供错误创建、HaiResult 包装和 Proxy 代理等能力，
+ * 用于模块未初始化时的安全回退。
+ *
+ * @template E - 模块错误类型（必须继承 HaiError）
+ */
+interface NotInitializedKit<E extends HaiError> {
+    /** 创建未初始化错误对象 */
+    error: () => E;
+    /** 创建包含未初始化错误的失败 HaiResult */
+    result: <T>() => HaiResult<T>;
+    /**
+     * 创建 Proxy 代理，拦截所有方法调用并返回未初始化错误。
+     *
+     * @param mode - 'async'（默认）所有方法返回 `Promise<HaiResult>`；'sync' 所有方法返回 `HaiResult`
+     */
+    proxy: <T>(mode?: 'async' | 'sync') => T;
+}
+/** module 子工具类型 */
+/** overloaded function type for createNotInitializedKit */
+interface CreateNotInitializedKitFn {
+    (codeOrDef: HaiErrorDef, messageFn: () => string): NotInitializedKit<HaiError>;
+    <E extends HaiError>(codeOrDef: E['code'], messageFn: () => string): NotInitializedKit<E>;
+}
+interface ModuleFn {
+    createNotInitializedKit: CreateNotInitializedKitFn;
+}
+
+export { type ArrayFn as A, type LoggerFunctions as B, type CoreOptions as C, type LoggerOptions as D, type ErrorFn as E, type LoggingConfig as F, LoggingConfigSchema as G, type HaiError as H, type I18nFn as I, type MatchHandlers as J, type MessageDictionary as K, type Locale as L, type ModuleFn as M, type MessageOptions as N, type ObjectFn as O, type PaginatedResult as P, type PaginationOptions as Q, type PaginationOptionsInput as R, type StringFn as S, type TypeUtilFn as T, err as U, ok as V, type HaiResult as a, type CoreLogger as b, type IdFn as c, type AsyncFn as d, type TimeFn as e, type CoreConfig as f, CoreConfigSchema as g, type CoreFunctions as h, type Env as i, EnvSchema as j, type ErrorInfo as k, type ErrorInfoValue as l, HaiCommonError as m, HaiConfigError as n, type HaiErrorDef as o, type IdConfig as p, IdConfigSchema as q, type InterpolationParams as r, type LocaleInfo as s, type LocaleMessages as t, type LogContext as u, type LogFormat as v, LogFormatSchema as w, type LogLevel as x, LogLevelSchema as y, type Logger as z };