@h-ai/core 0.1.0-alpha5

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2026] [idealworld.group]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,422 @@
+# @h-ai/core
+
+> hai Agent Framework 核心模块 — 提供统一的基础工具、类型定义、配置管理和日志功能。
+
+## 支持的能力
+
+- **HaiResult 类型** — 函数式错误处理（`ok` / `err`），所有模块统一返回值
+- **统一日志** — Node.js 基于 pino，浏览器基于 loglevel，API 一致
+- **国际化（i18n）** — 集中式 locale 管理 + 类型安全的消息获取器
+- **配置管理** — YAML 加载、环境变量插值、Zod 校验、文件监听（Node.js 专用）
+- **ID 生成** — nanoid 与 UUID v4
+- **错误定义** — 标准化错误码体系，支持跨模块统一的错误定义与实例创建
+- **模块工具** — NotInitializedKit 代理模式，各模块共用的生命周期基础设施
+- **工具函数库** — 类型检查、对象 / 字符串 / 数组 / 异步 / 时间操作
+
+## 快速开始
+
+### Node.js 环境
+
+```typescript
+import { core } from '@h-ai/core'
+
+// 初始化：加载配置目录（可选）
+core.init({ configDir: './config', watchConfig: true })
+
+// 日志
+core.logger.info('Server started', { port: 3000 })
+core.logger.warn('Slow query', { duration: 2500 })
+core.logger.error('Connection failed', { error })
+
+// 创建模块级 logger（独立名称空间）
+const dbLogger = core.logger.create({ name: 'db' })
+dbLogger.info('Connected to PostgreSQL')
+
+// 创建子 logger（自动携带固定上下文，适合请求级/操作级追踪）
+const reqLogger = core.logger.child({ requestId: 'req-001', userId: 'u-123' })
+reqLogger.info('Request started') // 日志自动包含 requestId + userId
+reqLogger.error('Request failed') // 同上
+
+// 子 logger 可嵌套
+const opLogger = reqLogger.child({ operation: 'createOrder' })
+opLogger.info('Order created') // 包含 requestId + userId + operation
+
+// i18n
+core.i18n.setGlobalLocale('zh-CN')
+const getMessage = core.i18n.createMessageGetter({
+  'zh-CN': { welcome: '欢迎 {name}', error: '发生错误：{msg}' },
+  'en-US': { welcome: 'Welcome {name}', error: 'Error: {msg}' },
+})
+getMessage('welcome', { params: { name: 'Alice' } }) // '欢迎 Alice'
+
+// ID 生成
+const nanoid = core.id.generate()
+const shortId = core.id.short()
+const uuid = core.id.uuid()
+const prefixed = core.id.withPrefix('order_')
+
+// 工具函数
+core.object.deepMerge(objA, objB)
+core.string.capitalize('hello')
+core.array.unique([1, 1, 2, 3])
+core.array.chunk([1, 2, 3, 4, 5], 2) // [[1,2], [3,4], [5]]
+await core.async.delay(1000)
+await core.async.retry(() => fetchData(), { maxRetries: 3, delay: 1000 })
+core.time.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')
+core.typeUtils.isDefined(value)
+```
+
+### 浏览器环境
+
+```typescript
+import { core } from '@h-ai/core'
+
+// 初始化日志级别（浏览器不支持配置加载）
+core.init({ logging: { level: 'warn' } })
+
+core.logger.info('Page ready')
+const id = core.id.generate()
+
+// 其他工具函数与 Node.js 相同
+core.string.capitalize('hello')
+core.array.unique([1, 1, 2])
+```
+
+## 详细 API
+
+### 日志（Logger）
+
+`core.logger` 既是默认 Logger 实例，也是日志管理的统一入口。
+
+#### 日志记录
+
+6 个级别：`trace` / `debug` / `info` / `warn` / `error` / `fatal`
+
+```typescript
+core.logger.info('User created', { userId: '123' })
+core.logger.error('Failed to connect', { error })
+core.logger.debug('Processing item', { id, step: 'validation' })
+```
+
+#### 创建模块级 logger
+
+```typescript
+// 独立名称空间，适合模块内全局使用
+const logger = core.logger.create({ name: 'payment' })
+logger.info('Payment processed')
+```
+
+#### 子 logger（child）
+
+```typescript
+// 携带固定上下文，每条日志自动附带这些字段
+const reqLogger = core.logger.child({ requestId: 'req-001', userId: 'u-123' })
+reqLogger.info('Request started') // 输出包含 requestId + userId
+reqLogger.warn('Slow response') // 同上
+
+// 嵌套 child：子上下文递归合并
+const opLogger = reqLogger.child({ operation: 'login' })
+opLogger.info('Login succeeded') // 输出包含 requestId + userId + operation
+opLogger.error('Login failed', { reason: 'invalid_password' })
+```
+
+> **典型用法**：在请求入口创建 `reqLogger`，传入 service 层，service 层再 `child` 添加操作上下文，最终日志自动串联完整链路。
+
+#### 日志管理
+
+```typescript
+// 配置输出格式和级别（Node.js）
+core.logger.configure({
+  level: 'info',
+  format: 'json', // 'json' | 'pretty'
+  context: { app: 'my-service' }, // 全局默认上下文
+  redact: ['password', 'token'], // 脱敏字段
+})
+
+core.logger.setLevel('debug')
+const level = core.logger.getLevel() // 'debug'
+```
+
+#### 日志级别规范
+
+| 级别    | 适用场景                           |
+| ------- | ---------------------------------- |
+| `trace` | 循环内详细调试数据                 |
+| `debug` | 函数进入、参数概要、读操作         |
+| `info`  | 业务事件（初始化完成、写操作成功） |
+| `warn`  | 异常但可恢复（校验失败、重试）     |
+| `error` | 操作失败（需人工排查）             |
+| `fatal` | 致命错误（服务无法继续）           |
+
+### 国际化（i18n）
+
+```typescript
+// 设置全局语言（所有 getMessage 函数自动响应）
+core.i18n.setGlobalLocale('en-US')
+const current = core.i18n.getGlobalLocale() // 'en-US'
+
+// 为每个模块创建消息获取器
+const getMessage = core.i18n.createMessageGetter({
+  'zh-CN': { welcome: '欢迎 {name}', error: '错误：{code}' },
+  'en-US': { welcome: 'Welcome {name}', error: 'Error: {code}' },
+})
+
+// 使用：自动读取全局 locale，支持参数插值
+getMessage('welcome', { params: { name: 'Alice' } }) // 'Welcome Alice'
+
+// 支持 locale 参数覆盖
+getMessage('welcome', { locale: 'zh-CN', params: { name: 'Alice' } }) // '欢迎 Alice'
+
+// 常量
+core.i18n.DEFAULT_LOCALES // [{ code: 'zh-CN', label: '简体中文' }, { code: 'en-US', label: 'English' }]
+core.i18n.DEFAULT_LOCALE // 'zh-CN'
+```
+
+### 配置管理（Node.js 专用）
+
+```typescript
+import { core, HaiConfigError } from '@h-ai/core'
+import { z } from 'zod'
+
+// 方式 1：init 时自动加载整个配置目录
+core.init({
+  configDir: './config', // 扫描该目录所有 .yml 文件
+  watchConfig: true, // 监听变更并自动重载
+})
+
+// 方式 2：手动加载单个文件（可选 Schema 校验）
+const AppSchema = z.object({
+  name: z.string(),
+  port: z.number().default(3000),
+})
+const result = core.config.load('app', './config/app.yml', AppSchema)
+if (result.success) {
+  core.logger.info('Config loaded', { name: result.data.name })
+}
+else {
+  core.logger.error('Config load failed', { code: result.error.code })
+}
+
+// 校验已加载的配置
+const validResult = core.config.validate('app', AppSchema)
+
+// 查询和获取
+if (core.config.has('app')) {
+  const cfg = core.config.get<typeof AppSchema>('app') // undefined 或配置
+  const cfg2 = core.config.getOrThrow<typeof AppSchema>('app') // 未加载时抛异常
+}
+core.config.keys() // ['core', 'app', 'db', ...]
+
+// 重新加载
+const reloadResult = core.config.reload('app')
+
+// 监听文件变更
+const unwatch = core.config.watch('app', (newConfig, error) => {
+  if (error) {
+    core.logger.error('Config reload failed', { error })
+    return
+  }
+  core.logger.info('Config updated', { config: newConfig })
+})
+unwatch() // 取消监听
+
+// 清除缓存（同时停止对应监听）
+core.config.clear('app') // 清除单个
+core.config.clear() // 清除全部
+```
+
+#### 环境变量插值
+
+`core.config.load()` 加载 YAML 时，自动对字符串值做 `${VAR}` 环境变量替换。
+
+- `${VAR}` — 读取 `process.env.VAR`；若不存在则返回 `CONFIG_ENV_VAR_MISSING` 错误
+- `${VAR:default}` — 读取 `process.env.VAR`；若不存在则使用冒号后的默认值
+
+**类型还原：** 当整个值恰好是单个变量表达式（如 `${PORT:3000}`）时，插值结果按 YAML 规则还原为原生类型（number / boolean 等）。混合文本始终为字符串。
+
+```yaml
+# config/app.yml
+debug: ${DEBUG:false} # → boolean false
+port: ${PORT:3000} # → number 3000
+database: ${DB_CONNECTION} # → 环境变量缺失时报错
+url: http://${HOST}:${PORT} # → string（混合文本）
+```
+
+### ID 生成
+
+```typescript
+const id = core.id.generate() // nanoid 21 字符
+const id8 = core.id.generate(8) // 自定义长度
+const shortId = core.id.short() // 10 字符短 ID
+const prefixed = core.id.withPrefix('user_') // 'user_V1StGXR...'
+const traceId = core.id.trace() // 'trace-V1StGXR...'
+const reqId = core.id.request() // 'req-V1StGXR...'
+const uuid = core.id.uuid() // UUID v4
+
+// 校验
+core.id.isValidUUID('f47ac10b-...') // true/false
+core.id.isValidNanoId('abc123', 6) // true/false
+```
+
+### 工具函数
+
+```typescript
+// 类型检查
+core.typeUtils.isDefined(x) // x !== undefined
+core.typeUtils.isObject(x) // plain object
+core.typeUtils.isFunction(x)
+core.typeUtils.isPromise(x)
+core.typeUtils.isString(x)
+core.typeUtils.isNumber(x)
+core.typeUtils.isBoolean(x)
+core.typeUtils.isArray(x)
+
+// 对象操作
+core.object.deepClone(obj)
+core.object.deepMerge(a, b) // 递归合并（防原型污染）
+core.object.deepMerge(a, b, c) // 支持多个对象
+core.object.pick(obj, ['a', 'b'])
+core.object.omit(obj, ['c', 'd'])
+core.object.keys(obj) // typed Object.keys
+core.object.values(obj)
+core.object.entries(obj)
+core.object.fromEntries(entries)
+
+// 字符串操作
+core.string.capitalize('hello') // 'Hello'
+core.string.kebabCase('helloWorld') // 'hello-world'
+core.string.camelCase('hello-world') // 'helloWorld'
+core.string.snakeCase('helloWorld') // 'hello_world'
+core.string.pascalCase('hello-world') // 'HelloWorld'
+core.string.truncate('long text', 5) // 'long ...'
+core.string.trim(' hello ') // 'hello'
+core.string.isBlank('') // true
+core.string.isNotBlank('x') // true
+core.string.padStart('5', 3, '0') // '005'
+core.string.padEnd('5', 3, '0') // '500'
+core.string.constantTimeEqual(a, b) // 防时序攻击比较
+
+// 数组操作
+core.array.unique([1, 1, 2]) // [1, 2]
+core.array.chunk([1, 2, 3, 4], 2) // [[1,2], [3,4]]
+core.array.groupBy(items, item => item.type) // Record<string, T[]>
+core.array.first([1, 2, 3]) // 1
+core.array.last([1, 2, 3]) // 3
+core.array.flatten([[1], [2, 3]]) // [1, 2, 3]
+core.array.compact([1, null, 2]) // [1, 2]
+core.array.shuffle([1, 2, 3]) // 随机排列
+core.array.intersection([1, 2], [2, 3]) // [2]
+core.array.difference([1, 2], [2, 3]) // [1]
+
+// 异步操作
+await core.async.delay(1000)
+await core.async.withTimeout(fetch('/api'), 5000)
+await core.async.retry(fn, { maxRetries: 3, delay: 1000 })
+await core.async.parallel(items, processFn, 5) // 并发限制
+await core.async.serial(items, processFn)
+const debouncedFn = core.async.debounce(fn, 300)
+const throttledFn = core.async.throttle(fn, 200)
+
+// 时间操作
+core.time.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')
+core.time.timeAgo(new Date(Date.now() - 60000)) // '1 分钟前'
+core.time.now() // Date.now()
+core.time.nowSeconds() // Math.floor(Date.now() / 1000)
+core.time.parseDate('2024-01-01')
+core.time.isValidDate(date)
+core.time.addDays(date, 7)
+core.time.addHours(date, 2)
+core.time.startOfDay(date)
+core.time.endOfDay(date)
+```
+
+### 模块基础工具（module）
+
+提供各模块共用的初始化错误处理：
+
+```typescript
+import { core } from '@h-ai/core'
+
+const notInitialized = core.module.createNotInitializedKit(
+  HaiDbError.NOT_INITIALIZED,
+  () => dbM('db_notInitialized'),
+)
+
+// 创建占位 Proxy（异步接口，默认）
+const currentDdl: DdlOperations = notInitialized.proxy<DdlOperations>()
+// 创建占位 Proxy（同步接口）
+const currentHash: HashOperations = notInitialized.proxy<HashOperations>('sync')
+```
+
+## 错误处理
+
+### HaiResult 类型
+
+所有可能失败的操作返回 `HaiResult<T>`：
+
+```typescript
+import type { HaiResult } from '@h-ai/core'
+import { core, err, HaiCommonError, ok } from '@h-ai/core'
+
+function divide(a: number, b: number): HaiResult<number> {
+  if (b === 0)
+    return err(HaiCommonError.VALIDATION_ERROR, 'Division by zero')
+  return ok(a / b)
+}
+
+const result = divide(10, 2)
+if (result.success) {
+  core.logger.info('Result', { data: result.data })
+}
+else {
+  core.logger.error('Error', { error: result.error })
+}
+```
+
+### 自定义错误码（模块级）
+
+```typescript
+import type { ErrorInfo } from '@h-ai/core'
+import { core } from '@h-ai/core'
+
+// 定义错误码（格式 'code:httpStatus'）
+const DbErrorInfo = {
+  NOT_INITIALIZED: '001:500',
+  CONNECTION_FAILED: '010:500',
+  QUERY_FAILED: '011:500',
+} as const satisfies ErrorInfo
+
+// 生成错误定义对象
+export const DbError = core.error.buildHaiErrorsDef('db', DbErrorInfo)
+// DbError.CONNECTION_FAILED → { code: 'hai:db:010', httpStatus: 500, system: 'hai', module: 'db' }
+
+// 创建错误实例
+const errorInst = core.error.buildHaiErrorInst(
+  DbError.CONNECTION_FAILED,
+  'Unable to connect to PostgreSQL',
+  originalError, // cause（可选）
+  'Check connection string', // suggestion（可选）
+)
+```
+
+### 配置错误码
+
+```typescript
+import { HaiConfigError } from '@h-ai/core'
+
+HaiConfigError.CONFIG_FILE_NOT_FOUND // hai:core:010 - 配置文件不存在
+HaiConfigError.CONFIG_PARSE_ERROR // hai:core:011 - YAML 解析失败
+HaiConfigError.CONFIG_VALIDATION_ERROR // hai:core:012 - Schema 校验失败
+HaiConfigError.CONFIG_ENV_VAR_MISSING // hai:core:013 - 环境变量缺失
+HaiConfigError.CONFIG_NOT_LOADED // hai:core:014 - 配置未加载
+```
+
+## 测试
+
+```bash
+pnpm --filter @h-ai/core test
+```
+
+## License
+
+Apache-2.0

package/dist/browser.d.ts

@@ -0,0 +1,43 @@
+import { C as CoreOptions, b as CoreLogger, I as I18nFn, c as IdFn, T as TypeUtilFn, O as ObjectFn, S as StringFn, A as ArrayFn, d as AsyncFn, e as TimeFn, E as ErrorFn, M as ModuleFn } from './core-util-module-B-wH5_ZT.js';
+export { f as CoreConfig, g as CoreConfigSchema, h as CoreFunctions, i as Env, j as EnvSchema, k as ErrorInfo, l as ErrorInfoValue, m as HaiCommonError, n as HaiConfigError, H as HaiError, o as HaiErrorDef, a as HaiResult, p as IdConfig, q as IdConfigSchema, r as InterpolationParams, L as Locale, s as LocaleInfo, t as LocaleMessages, u as LogContext, v as LogFormat, w as LogFormatSchema, x as LogLevel, y as LogLevelSchema, z as Logger, B as LoggerFunctions, D as LoggerOptions, F as LoggingConfig, G as LoggingConfigSchema, J as MatchHandlers, K as MessageDictionary, N as MessageOptions, P as PaginatedResult, Q as PaginationOptions, R as PaginationOptionsInput, U as err, V as ok } from './core-util-module-B-wH5_ZT.js';
+import 'zod';
+
+/**
+ * Core 服务对象 - 聚合常用功能（浏览器）。
+ *
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * core.logger.info('browser ready')
+ * ```
+ */
+declare const core: {
+    /** 初始化 Core */
+    init: typeof initCore;
+    logger: CoreLogger;
+    i18n: I18nFn;
+    id: IdFn;
+    typeUtils: TypeUtilFn;
+    object: ObjectFn;
+    string: StringFn;
+    array: ArrayFn;
+    async: AsyncFn;
+    time: TimeFn;
+    error: ErrorFn;
+    module: ModuleFn;
+};
+/**
+ * 初始化 Core（内部实现，通过 core.init() 调用）。
+ * 注意：浏览器环境不支持 config 和 watchConfig 选项。
+ *
+ * @param options - 初始化选项
+ *
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * core.init({ logging: { level: 'debug' } })
+ * ```
+ */
+declare function initCore(options?: CoreOptions): void;
+
+export { CoreLogger, CoreOptions, core };