@h-ai/core 0.1.0-alpha.66 → 0.1.0-alpha.67

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.en.md CHANGED
@@ -4,9 +4,11 @@
4
4
 
5
5
  [Framework home](../../README.en.md)
6
6
 
7
- > The core of hai Agent Framework: shared utilities, types, configuration management, and logging.
7
+ ## Introduction
8
8
 
9
- ## Capabilities
9
+ The core of hai Agent Framework: shared utilities, types, configuration management, and logging.
10
+
11
+ ## Core features
10
12
 
11
13
  - **HaiResult types**: functional error handling (`ok` / `err`) with a shared result format across modules.
12
14
  - **Unified logging**: pino on Node.js and loglevel in browsers, with the same API.
@@ -18,9 +20,11 @@
18
20
  - **Module utilities**: NotInitializedKit proxies and shared lifecycle infrastructure.
19
21
  - **Utility library**: type checks and object / string / array / async / time operations.
20
22
 
21
- ## Quick start
23
+ ## Getting started
24
+
25
+ ### Quick start
22
26
 
23
- ### Node.js environment
27
+ #### Node.js environment
24
28
 
25
29
  ```typescript
26
30
  import { core } from '@h-ai/core'
@@ -72,7 +76,7 @@ core.time.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')
72
76
  core.typeUtils.isDefined(value)
73
77
  ```
74
78
 
75
- ### Browser environment
79
+ #### Browser environment
76
80
 
77
81
  ```typescript
78
82
  import { core } from '@h-ai/core'
@@ -95,13 +99,13 @@ The browser retains the `core.config` API shape for type compatibility, but does
95
99
  - `watch()` immediately calls its callback with the same error and returns a safe no-op unsubscribe function.
96
100
  - Read configuration on the server and deliver it through an API, or use `core.init({ logging })` only to configure browser logging.
97
101
 
98
- ## Detailed API
102
+ ### Detailed API
99
103
 
100
- ### Logging (Logger)
104
+ #### Logging (Logger)
101
105
 
102
106
  `core.logger` is both the default Logger instance and the shared entry point for logger management.
103
107
 
104
- #### Write logs
108
+ ##### Write logs
105
109
 
106
110
  Six levels: `trace` / `debug` / `info` / `warn` / `error` / `fatal`.
107
111
 
@@ -111,7 +115,7 @@ core.logger.error('Failed to connect', { error })
111
115
  core.logger.debug('Processing item', { id, step: 'validation' })
112
116
  ```
113
117
 
114
- #### Create a module logger
118
+ ##### Create a module logger
115
119
 
116
120
  ```typescript
117
121
  // 独立名称空间,适合模块内全局使用
@@ -119,7 +123,7 @@ const logger = core.logger.create({ name: 'payment' })
119
123
  logger.info('Payment processed')
120
124
  ```
121
125
 
122
- #### Child loggers
126
+ ##### Child loggers
123
127
 
124
128
  ```typescript
125
129
  // 携带固定上下文,每条日志自动附带这些字段
@@ -135,7 +139,7 @@ opLogger.error('Login failed', { reason: 'invalid_password' })
135
139
 
136
140
  > **Typical usage**: create `reqLogger` at the request entry, pass it to the service layer, and add operation context with `child`. Logs then include the complete request context.
137
141
 
138
- #### Logger management
142
+ ##### Logger management
139
143
 
140
144
  ```typescript
141
145
  // 配置输出格式和级别(Node.js / Browser)
@@ -156,7 +160,7 @@ Browser logs still use the DevTools console: `pretty` prints readable messages w
156
160
 
157
161
  `core.logger` redacts log context by default: credentials such as `password`, `token`, `secret`, `privateKey`, and `apiV3Key` become `[REDACTED]`. Fields such as `url` / `baseUrl` / `endpoint` mask only embedded usernames/passwords. Email addresses and phone numbers are not masked by default.
158
162
 
159
- #### Log level conventions
163
+ ##### Log level conventions
160
164
 
161
165
  | Level | Use case |
162
166
  | ------- | --------------------------------------------------- |
@@ -167,7 +171,7 @@ Browser logs still use the DevTools console: `pretty` prints readable messages w
167
171
  | `error` | Operation failures requiring investigation |
168
172
  | `fatal` | Fatal errors preventing continued service |
169
173
 
170
- ### Internationalization (i18n)
174
+ #### Internationalization (i18n)
171
175
 
172
176
  ```typescript
173
177
  // 设置全局语言(所有 getMessage 函数自动响应)
@@ -191,7 +195,7 @@ core.i18n.DEFAULT_LOCALES // [{ code: 'zh-CN', label: '简体中文' }, { code:
191
195
  core.i18n.DEFAULT_LOCALE // 'zh-CN'
192
196
  ```
193
197
 
194
- ### Redaction utilities
198
+ #### Redaction utilities
195
199
 
196
200
  `core.sanitize.sanitizeSensitiveFields()` recursively redacts objects and arrays. By default it handles password, token, secret, privateKey, apiV3Key, and similar credentials, and masks embedded credentials in `url` / `baseUrl` / `endpoint`. Modules can supply custom matchers.
197
201
 
@@ -211,7 +215,7 @@ core.sanitize.sanitizeSensitiveFields({ email: 'user@example.com' }, {
211
215
  // => { email: '***' }
212
216
  ```
213
217
 
214
- ### Zod validation error localization
218
+ #### Zod validation error localization
215
219
 
216
220
  `core.zodValidation` converts Zod `SafeParseError` / `ZodError` into flat form errors and maps Zod's
217
221
  default English messages to the caller's own localized messages.
@@ -272,7 +276,7 @@ if (!result.success) {
272
276
  }
273
277
  ```
274
278
 
275
- ### Configuration management (Node.js only)
279
+ #### Configuration management (Node.js only)
276
280
 
277
281
  > Browsers have no filesystem access. `core.config` offers placeholder APIs only: file-related methods return `SERVICE_UNAVAILABLE` and do not load YAML.
278
282
 
@@ -327,7 +331,7 @@ core.config.clear('app') // 清除单个
327
331
  core.config.clear() // 清除全部
328
332
  ```
329
333
 
330
- #### Dotenv files and environment modes
334
+ ##### Dotenv files and environment modes
331
335
 
332
336
  Node-only `core.config.loadEnvFiles({ mode, envDir })` returns HaiResult and merges `.env` → `.env.<mode>` → `.env.local`, with existing process variables taking priority. development/production map to dev/prod; missing files are skipped. It does not mutate the process: check success before assigning. Track public environment files and `.env.example`; ignore private `.env.local`. core.init does not load dotenv. Browser calls return SERVICE_UNAVAILABLE.
333
337
 
@@ -339,7 +343,7 @@ Object.assign(process.env, env.data)
339
343
  core.init({ configDir: './config' })
340
344
  ```
341
345
 
342
- #### Environment variable mapping and interpolation
346
+ ##### Environment variable mapping and interpolation
343
347
 
344
348
  `core.config.load(name, ...)` automatically maps each YAML leaf to an
345
349
  environment variable named `HAI_<CONFIG_NAME>_<YAML_PATH>`. Configuration names and keys are uppercased, levels are separated by `_`,
@@ -382,7 +386,7 @@ database: ${DB_CONNECTION} # → 环境变量缺失时报错
382
386
  url: http://${HOST}:${PORT} # → string(混合文本)
383
387
  ```
384
388
 
385
- ### ID generation
389
+ #### ID generation
386
390
 
387
391
  ```typescript
388
392
  const id = core.id.generate() // nanoid 21 字符
@@ -398,7 +402,7 @@ core.id.isValidUUID('f47ac10b-...') // true/false
398
402
  core.id.isValidNanoId('abc123', 6) // true/false
399
403
  ```
400
404
 
401
- ### Utilities
405
+ #### Utilities
402
406
 
403
407
  ```typescript
404
408
  // 类型检查
@@ -470,7 +474,7 @@ core.time.startOfDay(date)
470
474
  core.time.endOfDay(date)
471
475
  ```
472
476
 
473
- ### Module utilities (module)
477
+ #### Module utilities (module)
474
478
 
475
479
  Shared initialization error handling for modules:
476
480
 
@@ -488,9 +492,9 @@ const currentDdl: DdlOperations = notInitialized.proxy<DdlOperations>()
488
492
  const currentHash: HashOperations = notInitialized.proxy<HashOperations>('sync')
489
493
  ```
490
494
 
491
- ## Error handling
495
+ ### Error handling
492
496
 
493
- ### HaiResult types
497
+ #### HaiResult types
494
498
 
495
499
  All operations that may fail return `HaiResult<T>`:
496
500
 
@@ -513,7 +517,7 @@ else {
513
517
  }
514
518
  ```
515
519
 
516
- ### Custom error codes (per module)
520
+ #### Custom error codes (per module)
517
521
 
518
522
  ```typescript
519
523
  import type { ErrorInfo } from '@h-ai/core'
@@ -539,7 +543,7 @@ const errorInst = core.error.buildHaiErrorInst(
539
543
  )
540
544
  ```
541
545
 
542
- ### Configuration error codes
546
+ #### Configuration error codes
543
547
 
544
548
  ```typescript
545
549
  import { HaiConfigError } from '@h-ai/core'
@@ -551,7 +555,7 @@ HaiConfigError.CONFIG_ENV_VAR_MISSING // hai:core:013 - 环境变量缺失
551
555
  HaiConfigError.CONFIG_NOT_LOADED // hai:core:014 - 配置未加载
552
556
  ```
553
557
 
554
- ## Tests
558
+ ## Development and testing
555
559
 
556
560
  ```bash
557
561
  pnpm --filter @h-ai/core test
package/README.ja.md CHANGED
@@ -4,7 +4,9 @@
4
4
 
5
5
  [フレームワークのホーム](../../README.ja.md)
6
6
 
7
- > hai Agent Framework の中核モジュール。共通ツール、型定義、設定管理、ログ機能を提供します。
7
+ ## 概要
8
+
9
+ hai Agent Framework の中核モジュール。共通ツール、型定義、設定管理、ログ機能を提供します。
8
10
 
9
11
  ## 主な機能
10
12
 
@@ -18,9 +20,11 @@
18
20
  - **モジュールツール**:NotInitializedKit のプロキシと共通のライフサイクル基盤。
19
21
  - **ツール関数**:型確認、オブジェクト・文字列・配列・非同期・時刻の操作。
20
22
 
21
- ## クイックスタート
23
+ ## 使い始める
24
+
25
+ ### クイックスタート
22
26
 
23
- ### Node.js 環境
27
+ #### Node.js 環境
24
28
 
25
29
  ```typescript
26
30
  import { core } from '@h-ai/core'
@@ -72,7 +76,7 @@ core.time.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')
72
76
  core.typeUtils.isDefined(value)
73
77
  ```
74
78
 
75
- ### ブラウザー環境
79
+ #### ブラウザー環境
76
80
 
77
81
  ```typescript
78
82
  import { core } from '@h-ai/core'
@@ -95,13 +99,13 @@ core.array.unique([1, 1, 2])
95
99
  - `watch()` は同じエラーで直ちにコールバックを呼び、安全な no-op の監視解除関数を返します。
96
100
  - 設定が必要な場合はサーバーで読み込み API で渡すか、ブラウザーでは `core.init({ logging })` でログのみ設定してください。
97
101
 
98
- ## API の詳細
102
+ ### API の詳細
99
103
 
100
- ### ログ(Logger)
104
+ #### ログ(Logger)
101
105
 
102
106
  `core.logger` は既定の Logger インスタンスであり、ログ管理の共通入口でもあります。
103
107
 
104
- #### ログの記録
108
+ ##### ログの記録
105
109
 
106
110
  6 つのレベル:`trace` / `debug` / `info` / `warn` / `error` / `fatal`。
107
111
 
@@ -111,7 +115,7 @@ core.logger.error('Failed to connect', { error })
111
115
  core.logger.debug('Processing item', { id, step: 'validation' })
112
116
  ```
113
117
 
114
- #### モジュール用 logger の作成
118
+ ##### モジュール用 logger の作成
115
119
 
116
120
  ```typescript
117
121
  // 独立名称空间,适合模块内全局使用
@@ -119,7 +123,7 @@ const logger = core.logger.create({ name: 'payment' })
119
123
  logger.info('Payment processed')
120
124
  ```
121
125
 
122
- #### 子 logger(child)
126
+ ##### 子 logger(child)
123
127
 
124
128
  ```typescript
125
129
  // 携带固定上下文,每条日志自动附带这些字段
@@ -135,7 +139,7 @@ opLogger.error('Login failed', { reason: 'invalid_password' })
135
139
 
136
140
  > **典型的な使い方**:リクエスト入口で `reqLogger` を作成してサービス層に渡し、サービス層で `child` に操作コンテキストを追加します。ログに処理全体のコンテキストが自動的に含まれます。
137
141
 
138
- #### ログの管理
142
+ ##### ログの管理
139
143
 
140
144
  ```typescript
141
145
  // 配置输出格式和级别(Node.js / Browser)
@@ -156,7 +160,7 @@ const level = core.logger.getLevel() // 'debug'
156
160
 
157
161
  `core.logger` は既定でログの機密情報をマスクします。`password`、`token`、`secret`、`privateKey`、`apiV3Key` などは `[REDACTED]` に置換されます。`url` / `baseUrl` / `endpoint` は URL 内のユーザー名・パスワードのみをマスクします。メールアドレス・電話番号は既定では隠しません。
158
162
 
159
- #### ログレベルの規約
163
+ ##### ログレベルの規約
160
164
 
161
165
  | レベル | 用途 |
162
166
  | ------- | ---------------------------------------- |
@@ -167,7 +171,7 @@ const level = core.logger.getLevel() // 'debug'
167
171
  | `error` | 調査が必要な操作の失敗 |
168
172
  | `fatal` | サービス継続不能の致命的エラー |
169
173
 
170
- ### 国際化(i18n)
174
+ #### 国際化(i18n)
171
175
 
172
176
  ```typescript
173
177
  // 设置全局语言(所有 getMessage 函数自动响应)
@@ -191,7 +195,7 @@ core.i18n.DEFAULT_LOCALES // [{ code: 'zh-CN', label: '简体中文' }, { code:
191
195
  core.i18n.DEFAULT_LOCALE // 'zh-CN'
192
196
  ```
193
197
 
194
- ### 機密情報のマスク
198
+ #### 機密情報のマスク
195
199
 
196
200
  `core.sanitize.sanitizeSensitiveFields()` はオブジェクト・配列内の機密情報を再帰的にマスクします。既定では password、token、secret、privateKey、apiV3Key などを処理し、`url` / `baseUrl` / `endpoint` の認証情報もマスクします。独自の matcher も指定できます。
197
201
 
@@ -211,7 +215,7 @@ core.sanitize.sanitizeSensitiveFields({ email: 'user@example.com' }, {
211
215
  // => { email: '***' }
212
216
  ```
213
217
 
214
- ### Zod 検証エラーの i18n 変換
218
+ #### Zod 検証エラーの i18n 変換
215
219
 
216
220
  `core.zodValidation` は Zod の `SafeParseError` / `ZodError` をフラットなフォームエラーに変換し、
217
221
  Zod の既定の英語メッセージを呼び出し元の i18n 文言に変換します。
@@ -272,7 +276,7 @@ if (!result.success) {
272
276
  }
273
277
  ```
274
278
 
275
- ### 設定管理(Node.js 専用)
279
+ #### 設定管理(Node.js 専用)
276
280
 
277
281
  > ブラウザーにはファイルシステムがないため、`core.config` は代替 API の形状のみを提供します。ファイル関連メソッドは `SERVICE_UNAVAILABLE` を返し、YAML を読み込みません。
278
282
 
@@ -327,7 +331,7 @@ core.config.clear('app') // 清除单个
327
331
  core.config.clear() // 清除全部
328
332
  ```
329
333
 
330
- #### dotenv ファイルと環境切り替え
334
+ ##### dotenv ファイルと環境切り替え
331
335
 
332
336
  Node 専用の `core.config.loadEnvFiles({ mode, envDir })` は HaiResult を返し、`.env` → `.env.<mode>` → `.env.local` の順で読み込みます。既存のプロセス変数が最優先です。development/production は dev/prod に対応し、存在しないファイルは省略します。プロセスは変更しないため、success を確認してから代入します。公開設定と `.env.example` は Git 登録し、私有の `.env.local` は除外します。core.init は dotenv を読み込まず、ブラウザーでは SERVICE_UNAVAILABLE を返します。
333
337
 
@@ -339,7 +343,7 @@ Object.assign(process.env, env.data)
339
343
  core.init({ configDir: './config' })
340
344
  ```
341
345
 
342
- #### 環境変数のマッピングと展開
346
+ ##### 環境変数のマッピングと展開
343
347
 
344
348
  `core.config.load(name, ...)` は YAML の各末端設定を
345
349
  `HAI_<CONFIG_NAME>_<YAML_PATH>` の環境変数に自動対応付けします。設定名・各 key は大文字化し、階層は `_` で区切り、
@@ -382,7 +386,7 @@ database: ${DB_CONNECTION} # → 环境变量缺失时报错
382
386
  url: http://${HOST}:${PORT} # → string(混合文本)
383
387
  ```
384
388
 
385
- ### ID 生成
389
+ #### ID 生成
386
390
 
387
391
  ```typescript
388
392
  const id = core.id.generate() // nanoid 21 字符
@@ -398,7 +402,7 @@ core.id.isValidUUID('f47ac10b-...') // true/false
398
402
  core.id.isValidNanoId('abc123', 6) // true/false
399
403
  ```
400
404
 
401
- ### ツール関数
405
+ #### ツール関数
402
406
 
403
407
  ```typescript
404
408
  // 类型检查
@@ -470,7 +474,7 @@ core.time.startOfDay(date)
470
474
  core.time.endOfDay(date)
471
475
  ```
472
476
 
473
- ### モジュール共通ツール(module)
477
+ #### モジュール共通ツール(module)
474
478
 
475
479
  モジュール共通の初期化エラー処理:
476
480
 
@@ -488,9 +492,9 @@ const currentDdl: DdlOperations = notInitialized.proxy<DdlOperations>()
488
492
  const currentHash: HashOperations = notInitialized.proxy<HashOperations>('sync')
489
493
  ```
490
494
 
491
- ## エラー処理
495
+ ### エラー処理
492
496
 
493
- ### HaiResult 型
497
+ #### HaiResult 型
494
498
 
495
499
  失敗する可能性がある操作は `HaiResult<T>` を返します:
496
500
 
@@ -513,7 +517,7 @@ else {
513
517
  }
514
518
  ```
515
519
 
516
- ### 独自のエラーコード(モジュール単位)
520
+ #### 独自のエラーコード(モジュール単位)
517
521
 
518
522
  ```typescript
519
523
  import type { ErrorInfo } from '@h-ai/core'
@@ -539,7 +543,7 @@ const errorInst = core.error.buildHaiErrorInst(
539
543
  )
540
544
  ```
541
545
 
542
- ### 設定エラーコード
546
+ #### 設定エラーコード
543
547
 
544
548
  ```typescript
545
549
  import { HaiConfigError } from '@h-ai/core'
@@ -551,12 +555,12 @@ HaiConfigError.CONFIG_ENV_VAR_MISSING // hai:core:013 - 环境变量缺失
551
555
  HaiConfigError.CONFIG_NOT_LOADED // hai:core:014 - 配置未加载
552
556
  ```
553
557
 
554
- ## テスト
558
+ ## 開発とテスト
555
559
 
556
560
  ```bash
557
561
  pnpm --filter @h-ai/core test
558
562
  ```
559
563
 
560
- ## License
564
+ ## ライセンス
561
565
 
562
566
  Apache-2.0
package/README.md CHANGED
@@ -4,9 +4,11 @@
4
4
 
5
5
  [框架首页](../../README.md)
6
6
 
7
- > hai Agent Framework 核心模块 — 提供统一的基础工具、类型定义、配置管理和日志功能。
7
+ ## 简介
8
8
 
9
- ## 支持的能力
9
+ hai Agent Framework 核心模块 — 提供统一的基础工具、类型定义、配置管理和日志功能。
10
+
11
+ ## 核心功能清单
10
12
 
11
13
  - **HaiResult 类型** — 函数式错误处理(`ok` / `err`),所有模块统一返回值
12
14
  - **统一日志** — Node.js 基于 pino,浏览器基于 loglevel,API 一致
@@ -18,9 +20,11 @@
18
20
  - **模块工具** — NotInitializedKit 代理模式,各模块共用的生命周期基础设施
19
21
  - **工具函数库** — 类型检查、对象 / 字符串 / 数组 / 异步 / 时间操作
20
22
 
21
- ## 快速开始
23
+ ## 使用入门
24
+
25
+ ### 快速开始
22
26
 
23
- ### Node.js 环境
27
+ #### Node.js 环境
24
28
 
25
29
  ```typescript
26
30
  import { core } from '@h-ai/core'
@@ -72,7 +76,7 @@ core.time.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')
72
76
  core.typeUtils.isDefined(value)
73
77
  ```
74
78
 
75
- ### 浏览器环境
79
+ #### 浏览器环境
76
80
 
77
81
  ```typescript
78
82
  import { core } from '@h-ai/core'
@@ -95,13 +99,13 @@ core.array.unique([1, 1, 2])
95
99
  - `watch()` 会立即用同一错误调用回调,并返回安全的 no-op 取消函数
96
100
  - 需要配置时请由服务端读取后通过接口下发,或只在浏览器端用 `core.init({ logging })` 配置日志
97
101
 
98
- ## 详细 API
102
+ ### 详细 API
99
103
 
100
- ### 日志(Logger)
104
+ #### 日志(Logger)
101
105
 
102
106
  `core.logger` 既是默认 Logger 实例,也是日志管理的统一入口。
103
107
 
104
- #### 日志记录
108
+ ##### 日志记录
105
109
 
106
110
  6 个级别:`trace` / `debug` / `info` / `warn` / `error` / `fatal`
107
111
 
@@ -111,7 +115,7 @@ core.logger.error('Failed to connect', { error })
111
115
  core.logger.debug('Processing item', { id, step: 'validation' })
112
116
  ```
113
117
 
114
- #### 创建模块级 logger
118
+ ##### 创建模块级 logger
115
119
 
116
120
  ```typescript
117
121
  // 独立名称空间,适合模块内全局使用
@@ -119,7 +123,7 @@ const logger = core.logger.create({ name: 'payment' })
119
123
  logger.info('Payment processed')
120
124
  ```
121
125
 
122
- #### 子 logger(child)
126
+ ##### 子 logger(child)
123
127
 
124
128
  ```typescript
125
129
  // 携带固定上下文,每条日志自动附带这些字段
@@ -135,7 +139,7 @@ opLogger.error('Login failed', { reason: 'invalid_password' })
135
139
 
136
140
  > **典型用法**:在请求入口创建 `reqLogger`,传入 service 层,service 层再 `child` 添加操作上下文,最终日志自动串联完整链路。
137
141
 
138
- #### 日志管理
142
+ ##### 日志管理
139
143
 
140
144
  ```typescript
141
145
  // 配置输出格式和级别(Node.js / Browser)
@@ -156,7 +160,7 @@ const level = core.logger.getLevel() // 'debug'
156
160
 
157
161
  `core.logger` 默认会对日志上下文执行安全脱敏:`password`、`token`、`secret`、`privateKey`、`apiV3Key` 等凭证类字段会替换为 `[REDACTED]`,`url` / `baseUrl` / `endpoint` 这类字段只会掩码 URL 中内嵌的用户名和密码;邮箱、手机号默认不会被遮盖。
158
162
 
159
- #### 日志级别规范
163
+ ##### 日志级别规范
160
164
 
161
165
  | 级别 | 适用场景 |
162
166
  | ------- | ---------------------------------- |
@@ -167,7 +171,7 @@ const level = core.logger.getLevel() // 'debug'
167
171
  | `error` | 操作失败(需人工排查) |
168
172
  | `fatal` | 致命错误(服务无法继续) |
169
173
 
170
- ### 国际化(i18n)
174
+ #### 国际化(i18n)
171
175
 
172
176
  ```typescript
173
177
  // 设置全局语言(所有 getMessage 函数自动响应)
@@ -191,7 +195,7 @@ core.i18n.DEFAULT_LOCALES // [{ code: 'zh-CN', label: '简体中文' }, { code:
191
195
  core.i18n.DEFAULT_LOCALE // 'zh-CN'
192
196
  ```
193
197
 
194
- ### 脱敏工具
198
+ #### 脱敏工具
195
199
 
196
200
  `core.sanitize.sanitizeSensitiveFields()` 可递归脱敏对象/数组中的敏感字段;默认会处理密码、token、secret、privateKey、apiV3Key 等凭证类字段,并自动掩码 `url` / `baseUrl` / `endpoint` 字段中的内嵌凭证。模块也可自定义 matcher。
197
201
 
@@ -211,7 +215,7 @@ core.sanitize.sanitizeSensitiveFields({ email: 'user@example.com' }, {
211
215
  // => { email: '***' }
212
216
  ```
213
217
 
214
- ### Zod 校验错误 i18n 映射
218
+ #### Zod 校验错误 i18n 映射
215
219
 
216
220
  `core.zodValidation` 用于把 Zod `SafeParseError` / `ZodError` 转为扁平表单错误,并将 Zod
217
221
  默认英文消息映射为调用方自己的 i18n 文案。
@@ -272,7 +276,7 @@ if (!result.success) {
272
276
  }
273
277
  ```
274
278
 
275
- ### 配置管理(Node.js 专用)
279
+ #### 配置管理(Node.js 专用)
276
280
 
277
281
  > 浏览器端没有文件系统,`core.config` 仅提供占位 API:文件相关方法返回 `SERVICE_UNAVAILABLE`,不会加载 YAML。
278
282
 
@@ -327,7 +331,7 @@ core.config.clear('app') // 清除单个
327
331
  core.config.clear() // 清除全部
328
332
  ```
329
333
 
330
- #### dotenv 文件与环境切换
334
+ ##### dotenv 文件与环境切换
331
335
 
332
336
  Node 专用的 `core.config.loadEnvFiles({ mode, envDir })` 返回 HaiResult,读取 `.env` → `.env.<mode>` → `.env.local`,已有进程环境最高;development/production 映射为 dev/prod,文件不存在时跳过。该函数不修改进程,调用方检查 success 后注入。除 `.env.local` 外的公共环境文件及完整说明 `.env.example` 提交 Git。`core.init` 不自动读取 dotenv,浏览器调用返回 SERVICE_UNAVAILABLE。
333
337
 
@@ -339,7 +343,7 @@ Object.assign(process.env, env.data)
339
343
  core.init({ configDir: './config' })
340
344
  ```
341
345
 
342
- #### 环境变量映射与插值
346
+ ##### 环境变量映射与插值
343
347
 
344
348
  `core.config.load(name, ...)` 会为每个 YAML 叶子配置项自动映射
345
349
  `HAI_<配置名>_<YAML 路径>` 环境变量。配置名和每层 key 转成大写,层级以 `_`
@@ -382,7 +386,7 @@ database: ${DB_CONNECTION} # → 环境变量缺失时报错
382
386
  url: http://${HOST}:${PORT} # → string(混合文本)
383
387
  ```
384
388
 
385
- ### ID 生成
389
+ #### ID 生成
386
390
 
387
391
  ```typescript
388
392
  const id = core.id.generate() // nanoid 21 字符
@@ -398,7 +402,7 @@ core.id.isValidUUID('f47ac10b-...') // true/false
398
402
  core.id.isValidNanoId('abc123', 6) // true/false
399
403
  ```
400
404
 
401
- ### 工具函数
405
+ #### 工具函数
402
406
 
403
407
  ```typescript
404
408
  // 类型检查
@@ -470,7 +474,7 @@ core.time.startOfDay(date)
470
474
  core.time.endOfDay(date)
471
475
  ```
472
476
 
473
- ### 模块基础工具(module)
477
+ #### 模块基础工具(module)
474
478
 
475
479
  提供各模块共用的初始化错误处理:
476
480
 
@@ -488,9 +492,9 @@ const currentDdl: DdlOperations = notInitialized.proxy<DdlOperations>()
488
492
  const currentHash: HashOperations = notInitialized.proxy<HashOperations>('sync')
489
493
  ```
490
494
 
491
- ## 错误处理
495
+ ### 错误处理
492
496
 
493
- ### HaiResult 类型
497
+ #### HaiResult 类型
494
498
 
495
499
  所有可能失败的操作返回 `HaiResult<T>`:
496
500
 
@@ -513,7 +517,7 @@ else {
513
517
  }
514
518
  ```
515
519
 
516
- ### 自定义错误码(模块级)
520
+ #### 自定义错误码(模块级)
517
521
 
518
522
  ```typescript
519
523
  import type { ErrorInfo } from '@h-ai/core'
@@ -539,7 +543,7 @@ const errorInst = core.error.buildHaiErrorInst(
539
543
  )
540
544
  ```
541
545
 
542
- ### 配置错误码
546
+ #### 配置错误码
543
547
 
544
548
  ```typescript
545
549
  import { HaiConfigError } from '@h-ai/core'
@@ -551,12 +555,12 @@ HaiConfigError.CONFIG_ENV_VAR_MISSING // hai:core:013 - 环境变量缺失
551
555
  HaiConfigError.CONFIG_NOT_LOADED // hai:core:014 - 配置未加载
552
556
  ```
553
557
 
554
- ## 测试
558
+ ## 开发测试
555
559
 
556
560
  ```bash
557
561
  pnpm --filter @h-ai/core test
558
562
  ```
559
563
 
560
- ## License
564
+ ## 许可证
561
565
 
562
566
  Apache-2.0
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@h-ai/core",
3
3
  "type": "module",
4
- "version": "0.1.0-alpha.66",
4
+ "version": "0.1.0-alpha.67",
5
5
  "description": "Hai Framework core module with shared utilities, types, configuration, and logging.",
6
6
  "license": "Apache-2.0",
7
7
  "exports": {