@h-ai/core 1.0.0-beta.19 → 1.0.0-beta.20
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 +37 -29
- package/README.ja.md +36 -28
- package/README.md +39 -31
- package/package.json +1 -1
package/README.en.md
CHANGED
|
@@ -4,36 +4,9 @@
|
|
|
4
4
|
|
|
5
5
|
[Framework home](../../README.en.md)
|
|
6
6
|
|
|
7
|
-
## Introduction
|
|
8
|
-
|
|
9
7
|
`@h-ai/core` is the shared foundation of Hai Framework. It gives applications and framework modules consistent configuration, errors, logging, and internationalization. Utilities work directly; call `core.init()` when a Node application needs file configuration.
|
|
10
8
|
|
|
11
|
-
##
|
|
12
|
-
|
|
13
|
-
| Capability | Purpose | Main entry points |
|
|
14
|
-
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
|
|
15
|
-
| Configuration and startup | Load YAML, merge environment overrides, validate settings, and orchestrate module startup and shutdown | `core.config`, `core.init`, `core.module.createRuntime` |
|
|
16
|
-
| Results and errors | Express business success/failure, define error codes, and produce safe messages at API boundaries | `HaiResult`, `ok` / `err`, `core.error` |
|
|
17
|
-
| Logging and diagnostics | Structured logs, request correlation, credential masking, and log observation | `core.logger`, `core.context`, `core.sanitize` |
|
|
18
|
-
| Internationalization and validation messages | Manage message languages, isolate concurrent request locales, and localize Zod field errors | `core.i18n`, `core.zodValidation` |
|
|
19
|
-
| Request access control | Resolve trusted client addresses and check paths, methods, IPs, and time windows | `core.access` (Node only) |
|
|
20
|
-
| General utilities | Generate identifiers and reuse type, object, string, array, async, and time operations, plus consistent errors before module initialization | `core.id`, `core.typeUtils`, `core.object`, and others |
|
|
21
|
-
|
|
22
|
-
### Node and browser boundaries
|
|
23
|
-
|
|
24
|
-
Both environments use `import { core } from '@h-ai/core'`; the bundler selects the code for the target environment.
|
|
25
|
-
|
|
26
|
-
| Capability | Node.js | Browser |
|
|
27
|
-
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
28
|
-
| Logging, results/errors, messages, utilities, and ordered module startup/shutdown | Supported | Supported |
|
|
29
|
-
| YAML, dotenv, environment mapping, file watching | Reads and watches local configuration files | Cannot read or watch local files; loading methods return failure |
|
|
30
|
-
| Request correlation with `core.context.run` | Each request retains its own IDs after asynchronous work, without mixing them with other requests | Values exist only during synchronous callback code and are no longer available after `await` |
|
|
31
|
-
| Request locale with `core.i18n.runWithLocale` | Each request keeps its chosen language after asynchronous work; other requests do not change it | Throws; set the page language with `setGlobalLocale()` or pass a locale when getting a message |
|
|
32
|
-
| Request policies with `core.access` | Checks request addresses, paths, and time windows | This tool is unavailable |
|
|
33
|
-
|
|
34
|
-
`core.init()` configures Core settings and logging synchronously, returns `void`, and Core provides no `close()` method. Applications starting databases, caches, or other modules can manage them with `core.module.createRuntime()`: its returned object's `start()` initializes them in order, and `close()` cleans them up in reverse. A complete example follows under “Application startup and shutdown”.
|
|
35
|
-
|
|
36
|
-
## Getting started
|
|
9
|
+
## Quick Start
|
|
37
10
|
|
|
38
11
|
Each Core feature below has a purpose, examples, and relevant limits. Start with initialization when loading configuration; logging, messages, and general utilities work directly.
|
|
39
12
|
|
|
@@ -107,6 +80,31 @@ core.logger.warn('Request needs attention', { requestId }) // 返回 undefined
|
|
|
107
80
|
|
|
108
81
|
The host supplies public configuration fields; never send complete server settings or secrets. Browser `core.config.get()` / `has()` / `keys()` return `undefined` / `false` / `[]`. `loadEnvFiles()`, `load()`, `validate()`, and `reload()` return `SERVICE_UNAVAILABLE`; `getOrThrow()` throws. `watch()` immediately calls back with the same unavailable error and returns a no-op unsubscribe function.
|
|
109
82
|
|
|
83
|
+
## Features
|
|
84
|
+
|
|
85
|
+
| Capability | Purpose | Main entry points |
|
|
86
|
+
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
|
|
87
|
+
| Configuration and startup | Load YAML, merge environment overrides, validate settings, and orchestrate module startup and shutdown | `core.config`, `core.init`, `core.module.createRuntime` |
|
|
88
|
+
| Results and errors | Express business success/failure, define error codes, and produce safe messages at API boundaries | `HaiResult`, `ok` / `err`, `core.error` |
|
|
89
|
+
| Logging and diagnostics | Structured logs, request correlation, credential masking, and log observation | `core.logger`, `core.context`, `core.sanitize` |
|
|
90
|
+
| Internationalization and validation messages | Manage message languages, isolate concurrent request locales, and localize Zod field errors | `core.i18n`, `core.zodValidation` |
|
|
91
|
+
| Request access control | Resolve trusted client addresses and check paths, methods, IPs, and time windows | `core.access` (Node only) |
|
|
92
|
+
| General utilities | Generate identifiers and reuse type, object, string, array, async, and time operations, plus consistent errors before module initialization | `core.id`, `core.typeUtils`, `core.object`, and others |
|
|
93
|
+
|
|
94
|
+
### Node and browser boundaries
|
|
95
|
+
|
|
96
|
+
Both environments use `import { core } from '@h-ai/core'`; the bundler selects the code for the target environment.
|
|
97
|
+
|
|
98
|
+
| Capability | Node.js | Browser |
|
|
99
|
+
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
100
|
+
| Logging, results/errors, messages, utilities, and ordered module startup/shutdown | Supported | Supported |
|
|
101
|
+
| YAML, dotenv, environment mapping, file watching | Reads and watches local configuration files | Cannot read or watch local files; loading methods return failure |
|
|
102
|
+
| Request correlation with `core.context.run` | Each request retains its own IDs after asynchronous work, without mixing them with other requests | Values exist only during synchronous callback code and are no longer available after `await` |
|
|
103
|
+
| Request locale with `core.i18n.runWithLocale` | Each request keeps its chosen language after asynchronous work; other requests do not change it | Throws; set the page language with `setGlobalLocale()` or pass a locale when getting a message |
|
|
104
|
+
| Request policies with `core.access` | Checks request addresses, paths, and time windows | This tool is unavailable |
|
|
105
|
+
|
|
106
|
+
`core.init()` configures Core settings and logging synchronously, returns `void`, and Core provides no `close()` method. Applications starting databases, caches, or other modules can manage them with `core.module.createRuntime()`: its returned object's `start()` initializes them in order, and `close()` cleans them up in reverse. A complete example follows under “Application startup and shutdown”.
|
|
107
|
+
|
|
110
108
|
### Files and environment settings: `core.config`
|
|
111
109
|
|
|
112
110
|
Read YAML, apply environment overrides, validate configuration types, and manage cached settings and file watchers. The file and environment operations below require Node.
|
|
@@ -868,7 +866,17 @@ formatDate supports YYYY/MM/DD/HH/mm/ss tokens and defaults to YYYY-MM-DD. Date
|
|
|
868
866
|
|
|
869
867
|
See the [Core reference](../cli/templates/skills/hai-core/reference.md) for complete parameters and less common options. Current published declarations define the contract.
|
|
870
868
|
|
|
871
|
-
##
|
|
869
|
+
## Configuration
|
|
870
|
+
|
|
871
|
+
core.init takes configuration directory, schemas and logging options, returns void synchronously and has no close. See Quick Start and core.config for file loading, environment precedence and field examples; init completing does not prove all business configuration is valid.
|
|
872
|
+
|
|
873
|
+
[Per-option purpose, use cases and examples](../../docs/usage/configuration/runtime.md).
|
|
874
|
+
|
|
875
|
+
## Error Handling
|
|
876
|
+
|
|
877
|
+
Check result.success for domain operations. Handle failures with the module error definitions and safe messages; retain codes, correlation IDs and sanitized causes in server logs. Synchronous tools, factories, stream iteration and lifecycle calls follow their own signatures. A completed Promise alone is not business success. See each feature for recovery limits.
|
|
878
|
+
|
|
879
|
+
## Development
|
|
872
880
|
|
|
873
881
|
Run from the repository root (use `pnpm.cmd` in PowerShell):
|
|
874
882
|
|
package/README.ja.md
CHANGED
|
@@ -4,36 +4,9 @@
|
|
|
4
4
|
|
|
5
5
|
[フレームワークのホーム](../../README.ja.md)
|
|
6
6
|
|
|
7
|
-
## 概要
|
|
8
|
-
|
|
9
7
|
`@h-ai/core` は Hai Framework の共通基盤です。アプリケーションと他のモジュールに、設定、エラー、ログ、国際化の共通機能を提供します。ツールはそのまま利用でき、Node アプリでファイル設定が必要な場合に `core.init()` を呼びます。
|
|
10
8
|
|
|
11
|
-
##
|
|
12
|
-
|
|
13
|
-
| 機能 | 用途 | 主な入口 |
|
|
14
|
-
| ---------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------- |
|
|
15
|
-
| 設定と起動 | YAML の読み込み、環境変数の上書き、設定検証、依存順に沿ったモジュールの起動と終了 | `core.config`、`core.init`、`core.module.createRuntime` |
|
|
16
|
-
| 結果とエラー | 業務処理の成否、エラーコード、API 境界で公開する安全なメッセージ | `HaiResult`、`ok` / `err`、`core.error` |
|
|
17
|
-
| ログと診断 | 構造化ログ、リクエスト関連付け、認証情報のマスキング、ログ監視 | `core.logger`、`core.context`、`core.sanitize` |
|
|
18
|
-
| 国際化と検証メッセージ | メッセージ言語、並行リクエストの言語分離、Zod フィールドエラーの翻訳 | `core.i18n`、`core.zodValidation` |
|
|
19
|
-
| リクエストアクセス制御 | 信頼できるクライアント IP の解決と、パス・メソッド・IP・時間帯の検査 | `core.access`（Node 専用） |
|
|
20
|
-
| 共通ツール | ID、型確認、オブジェクト、文字列、配列、非同期処理、日時操作、未初期化時の共通エラー応答 | `core.id`、`core.typeUtils`、`core.object` など |
|
|
21
|
-
|
|
22
|
-
### Node とブラウザーの境界
|
|
23
|
-
|
|
24
|
-
両環境とも `import { core } from '@h-ai/core'` を使い、ビルドツールが対象環境のコードを選びます。
|
|
25
|
-
|
|
26
|
-
| 機能 | Node.js | ブラウザー |
|
|
27
|
-
| --------------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
|
28
|
-
| ログ、結果/エラー、メッセージ、共通ツール、モジュールの順次起動と終了 | 対応 | 対応 |
|
|
29
|
-
| YAML、dotenv、環境変数マッピング、ファイル監視 | ローカル設定ファイルを読み込み、監視できる | ローカルファイルを読み込み・監視できず、読み込みメソッドは失敗を返す |
|
|
30
|
-
| `core.context.run` による関連付け | 非同期処理の待機後も各リクエストの ID を保持し、他のリクエストと混在しない | コールバックの同期処理中だけ保持し、`await` 後には保持しない |
|
|
31
|
-
| `core.i18n.runWithLocale` によるリクエスト言語 | 非同期処理の待機後も選んだ言語を保持し、他のリクエストに変更されない | 例外となる。ページ言語は `setGlobalLocale()`、またはメッセージ取得時の locale で指定する |
|
|
32
|
-
| `core.access` によるアクセス制御 | リクエストのアドレス、パス、時間帯を検査できる | このツールは利用不可 |
|
|
33
|
-
|
|
34
|
-
`core.init()` は Core の設定とログを同期的に準備し、`void` を返します。Core に `close()` メソッドはありません。データベースやキャッシュなども使うアプリは `core.module.createRuntime()` でまとめて管理できます。返されたオブジェクトの `start()` で順に初期化し、`close()` で逆順に解放します。下の「アプリケーションの起動と終了」に例を示します。
|
|
35
|
-
|
|
36
|
-
## 使い始める
|
|
9
|
+
## クイックスタート
|
|
37
10
|
|
|
38
11
|
以下では Core の全機能について用途、例、制約を説明します。設定を読み込む場合は初期化から確認してください。ログ、メッセージ、汎用ツールは直接利用できます。
|
|
39
12
|
|
|
@@ -107,6 +80,31 @@ core.logger.warn('Request needs attention', { requestId }) // 返回 undefined
|
|
|
107
80
|
|
|
108
81
|
ホストは公開可能な設定項目だけを渡し、サーバー設定全体や秘密情報は送りません。ブラウザーの `core.config.get()` / `has()` / `keys()` は `undefined` / `false` / `[]` を返します。`loadEnvFiles()`、`load()`、`validate()`、`reload()` は `SERVICE_UNAVAILABLE` を返し、`getOrThrow()` は例外を送出します。`watch()` は同じ利用不可エラーを即座に通知し、何もしない解除関数を返します。
|
|
109
82
|
|
|
83
|
+
## 機能
|
|
84
|
+
|
|
85
|
+
| 機能 | 用途 | 主な入口 |
|
|
86
|
+
| ---------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------- |
|
|
87
|
+
| 設定と起動 | YAML の読み込み、環境変数の上書き、設定検証、依存順に沿ったモジュールの起動と終了 | `core.config`、`core.init`、`core.module.createRuntime` |
|
|
88
|
+
| 結果とエラー | 業務処理の成否、エラーコード、API 境界で公開する安全なメッセージ | `HaiResult`、`ok` / `err`、`core.error` |
|
|
89
|
+
| ログと診断 | 構造化ログ、リクエスト関連付け、認証情報のマスキング、ログ監視 | `core.logger`、`core.context`、`core.sanitize` |
|
|
90
|
+
| 国際化と検証メッセージ | メッセージ言語、並行リクエストの言語分離、Zod フィールドエラーの翻訳 | `core.i18n`、`core.zodValidation` |
|
|
91
|
+
| リクエストアクセス制御 | 信頼できるクライアント IP の解決と、パス・メソッド・IP・時間帯の検査 | `core.access`（Node 専用） |
|
|
92
|
+
| 共通ツール | ID、型確認、オブジェクト、文字列、配列、非同期処理、日時操作、未初期化時の共通エラー応答 | `core.id`、`core.typeUtils`、`core.object` など |
|
|
93
|
+
|
|
94
|
+
### Node とブラウザーの境界
|
|
95
|
+
|
|
96
|
+
両環境とも `import { core } from '@h-ai/core'` を使い、ビルドツールが対象環境のコードを選びます。
|
|
97
|
+
|
|
98
|
+
| 機能 | Node.js | ブラウザー |
|
|
99
|
+
| --------------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
|
100
|
+
| ログ、結果/エラー、メッセージ、共通ツール、モジュールの順次起動と終了 | 対応 | 対応 |
|
|
101
|
+
| YAML、dotenv、環境変数マッピング、ファイル監視 | ローカル設定ファイルを読み込み、監視できる | ローカルファイルを読み込み・監視できず、読み込みメソッドは失敗を返す |
|
|
102
|
+
| `core.context.run` による関連付け | 非同期処理の待機後も各リクエストの ID を保持し、他のリクエストと混在しない | コールバックの同期処理中だけ保持し、`await` 後には保持しない |
|
|
103
|
+
| `core.i18n.runWithLocale` によるリクエスト言語 | 非同期処理の待機後も選んだ言語を保持し、他のリクエストに変更されない | 例外となる。ページ言語は `setGlobalLocale()`、またはメッセージ取得時の locale で指定する |
|
|
104
|
+
| `core.access` によるアクセス制御 | リクエストのアドレス、パス、時間帯を検査できる | このツールは利用不可 |
|
|
105
|
+
|
|
106
|
+
`core.init()` は Core の設定とログを同期的に準備し、`void` を返します。Core に `close()` メソッドはありません。データベースやキャッシュなども使うアプリは `core.module.createRuntime()` でまとめて管理できます。返されたオブジェクトの `start()` で順に初期化し、`close()` で逆順に解放します。下の「アプリケーションの起動と終了」に例を示します。
|
|
107
|
+
|
|
110
108
|
### ファイルと環境設定：`core.config`
|
|
111
109
|
|
|
112
110
|
YAML の読み込み、環境変数による上書き、型の検証、設定キャッシュとファイル監視を管理します。以下のファイル・環境操作は Node 専用です。
|
|
@@ -868,6 +866,16 @@ formatDate は YYYY/MM/DD/HH/mm/ss に対応し、既定は YYYY-MM-DD です。
|
|
|
868
866
|
|
|
869
867
|
詳しい引数と低頻度の選択肢は [Core 利用リファレンス](../cli/templates/skills/hai-core/reference.md)を参照し、公開契約は現在の宣言に従ってください。
|
|
870
868
|
|
|
869
|
+
## 設定
|
|
870
|
+
|
|
871
|
+
core.init は設定ディレクトリー・Schema・ログ指定を受け同期 void を返し、close はありません。読込・環境優先順位・フィールド例はクイックスタートと core.config を参照し、init 完了だけで業務設定全体の妥当性を判断しないでください。
|
|
872
|
+
|
|
873
|
+
[項目別の用途・適用場面・例](../../docs/usage/configuration/runtime.md).
|
|
874
|
+
|
|
875
|
+
## エラー処理
|
|
876
|
+
|
|
877
|
+
領域操作は result.success を確認し、失敗時はモジュールのエラー定義と安全な説明を使います。コード・関連 ID・秘匿した原因をサーバーログに残します。同期ツール・ファクトリー・ストリーム反復・ライフサイクルは各署名に従い、Promise 完了だけで成功と判断しません。回復条件は各機能を参照してください。
|
|
878
|
+
|
|
871
879
|
## 開発とテスト
|
|
872
880
|
|
|
873
881
|
リポジトリールートで実行します（PowerShell は `pnpm.cmd`）。
|
package/README.md
CHANGED
|
@@ -4,36 +4,9 @@
|
|
|
4
4
|
|
|
5
5
|
[框架首页](../../README.md)
|
|
6
6
|
|
|
7
|
-
## 简介
|
|
8
|
-
|
|
9
7
|
`@h-ai/core` 是 Hai Framework 的公共基础层，为应用和其他框架模块提供一致的配置、错误、日志和国际化能力。常用工具可直接使用；Node 应用需要加载配置时再调用 `core.init()`。
|
|
10
8
|
|
|
11
|
-
##
|
|
12
|
-
|
|
13
|
-
| 能力 | 解决的问题 | 主要入口 |
|
|
14
|
-
| ---------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
|
|
15
|
-
| 配置与启动 | 加载 YAML、合并环境覆盖、校验配置，按依赖顺序编排模块启动与关闭 | `core.config`、`core.init`、`core.module.createRuntime` |
|
|
16
|
-
| 结果与错误 | 用统一结果表达业务成败，定义错误码，在接口边界生成安全提示 | `HaiResult`、`ok` / `err`、`core.error` |
|
|
17
|
-
| 日志与诊断 | 结构化日志、请求关联、凭据脱敏及日志观察 | `core.logger`、`core.context`、`core.sanitize` |
|
|
18
|
-
| 国际化与校验提示 | 管理消息语言，隔离并发请求语言，把 Zod 错误转换为本地化字段提示 | `core.i18n`、`core.zodValidation` |
|
|
19
|
-
| 请求访问控制 | 解析可信客户端地址，按路径、方法、IP 和时段检查请求 | `core.access`（Node 专属） |
|
|
20
|
-
| 通用工具 | 复用标识生成、类型检查、对象、字符串、数组、异步和时间操作，以及模块未初始化时的统一错误返回 | `core.id`、`core.typeUtils`、`core.object` 等 |
|
|
21
|
-
|
|
22
|
-
### Node 与浏览器的边界
|
|
23
|
-
|
|
24
|
-
两端都通过 `import { core } from '@h-ai/core'` 使用，由打包工具选择对应环境的代码。
|
|
25
|
-
|
|
26
|
-
| 能力 | Node.js | 浏览器 |
|
|
27
|
-
| --------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------ |
|
|
28
|
-
| 日志、结果/错误、消息、通用工具，以及模块的顺序启动与关闭 | 支持 | 支持 |
|
|
29
|
-
| YAML、dotenv、环境映射与文件监听 | 可以读取和监听本地配置文件 | 不能读取或监听本地文件；调用加载方法会返回失败 |
|
|
30
|
-
| 请求关联 `core.context.run` | 每个请求保留自己的编号等信息，等待异步操作后仍能读取，互不串用 | 只在回调的同步代码中保留信息，`await` 后不再保留 |
|
|
31
|
-
| 请求语言 `core.i18n.runWithLocale` | 请求使用自己的语言，等待异步操作后也不会受其他请求影响 | 调用会抛错；用 `setGlobalLocale()` 设置页面语言，或在取消息时指定 locale |
|
|
32
|
-
| 请求策略 `core.access` | 可以检查请求地址、路径和时段 | 不提供此工具 |
|
|
33
|
-
|
|
34
|
-
`core.init()` 只负责 Core 的配置和日志设置，同步返回 `void`，Core 没有 `close()` 方法。应用如果还需要启动数据库、缓存等模块，可用 `core.module.createRuntime()` 集中管理它们：调用返回对象的 `start()` 依次初始化，调用 `close()` 按相反顺序清理。下方“应用启动与关闭”给出完整示例。
|
|
35
|
-
|
|
36
|
-
## 使用入门
|
|
9
|
+
## 快速开始
|
|
37
10
|
|
|
38
11
|
下面按 `core` 对象上的全部子功能介绍用途、示例与必要限制。需要加载配置时先看初始化；日志、消息和通用工具可直接使用。
|
|
39
12
|
|
|
@@ -107,6 +80,31 @@ core.logger.warn('Request needs attention', { requestId }) // 返回 undefined
|
|
|
107
80
|
|
|
108
81
|
浏览器配置由宿主通过公开字段下发，不传完整服务端配置或密钥。`core.config.get()` / `has()` / `keys()` 分别返回 `undefined` / `false` / `[]`；`loadEnvFiles()`、`load()`、`validate()`、`reload()` 返回 `SERVICE_UNAVAILABLE`，`getOrThrow()` 抛错。`watch()` 立即回调同一不可用错误并返回空取消函数。
|
|
109
82
|
|
|
83
|
+
## 功能
|
|
84
|
+
|
|
85
|
+
| 能力 | 解决的问题 | 主要入口 |
|
|
86
|
+
| ---------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
|
|
87
|
+
| 配置与启动 | 加载 YAML、合并环境覆盖、校验配置，按依赖顺序编排模块启动与关闭 | `core.config`、`core.init`、`core.module.createRuntime` |
|
|
88
|
+
| 结果与错误 | 用统一结果表达业务成败，定义错误码，在接口边界生成安全提示 | `HaiResult`、`ok` / `err`、`core.error` |
|
|
89
|
+
| 日志与诊断 | 结构化日志、请求关联、凭据脱敏及日志观察 | `core.logger`、`core.context`、`core.sanitize` |
|
|
90
|
+
| 国际化与校验提示 | 管理消息语言，隔离并发请求语言，把 Zod 错误转换为本地化字段提示 | `core.i18n`、`core.zodValidation` |
|
|
91
|
+
| 请求访问控制 | 解析可信客户端地址，按路径、方法、IP 和时段检查请求 | `core.access`（Node 专属） |
|
|
92
|
+
| 通用工具 | 复用标识生成、类型检查、对象、字符串、数组、异步和时间操作，以及模块未初始化时的统一错误返回 | `core.id`、`core.typeUtils`、`core.object` 等 |
|
|
93
|
+
|
|
94
|
+
### Node 与浏览器的边界
|
|
95
|
+
|
|
96
|
+
两端都通过 `import { core } from '@h-ai/core'` 使用，由打包工具选择对应环境的代码。
|
|
97
|
+
|
|
98
|
+
| 能力 | Node.js | 浏览器 |
|
|
99
|
+
| --------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------ |
|
|
100
|
+
| 日志、结果/错误、消息、通用工具，以及模块的顺序启动与关闭 | 支持 | 支持 |
|
|
101
|
+
| YAML、dotenv、环境映射与文件监听 | 可以读取和监听本地配置文件 | 不能读取或监听本地文件；调用加载方法会返回失败 |
|
|
102
|
+
| 请求关联 `core.context.run` | 每个请求保留自己的编号等信息，等待异步操作后仍能读取，互不串用 | 只在回调的同步代码中保留信息，`await` 后不再保留 |
|
|
103
|
+
| 请求语言 `core.i18n.runWithLocale` | 请求使用自己的语言，等待异步操作后也不会受其他请求影响 | 调用会抛错；用 `setGlobalLocale()` 设置页面语言，或在取消息时指定 locale |
|
|
104
|
+
| 请求策略 `core.access` | 可以检查请求地址、路径和时段 | 不提供此工具 |
|
|
105
|
+
|
|
106
|
+
`core.init()` 只负责 Core 的配置和日志设置，同步返回 `void`，Core 没有 `close()` 方法。应用如果还需要启动数据库、缓存等模块，可用 `core.module.createRuntime()` 集中管理它们：调用返回对象的 `start()` 依次初始化，调用 `close()` 按相反顺序清理。下方“应用启动与关闭”给出完整示例。
|
|
107
|
+
|
|
110
108
|
### 文件与环境配置：`core.config`
|
|
111
109
|
|
|
112
110
|
读取 YAML、应用环境变量覆盖、检查配置类型，并管理配置缓存与文件监听。下列文件与环境操作仅在 Node 中可用。
|
|
@@ -305,7 +303,7 @@ const restored = core.config.parseEnv(text) // 解析回字面字符串，不执
|
|
|
305
303
|
core.logger.info('Generated config verified', { port: restored.HAI_APP_PORT })
|
|
306
304
|
```
|
|
307
305
|
|
|
308
|
-
普通对象默认展开；数组、动态字典和空对象保留 JSON。整体替换对象的生成规则、完整来源优先级与应用接入见[基础配置手册](../../docs/usage/configuration/runtime.md)
|
|
306
|
+
普通对象默认展开；数组、动态字典和空对象保留 JSON。整体替换对象的生成规则、完整来源优先级与应用接入见[基础配置手册](../../docs/usage/configuration/runtime.md).
|
|
309
307
|
|
|
310
308
|
### 记录日志：`core.logger`
|
|
311
309
|
|
|
@@ -705,7 +703,7 @@ core.logger.info('Request access checked', { allowed: decision.allowed })
|
|
|
705
703
|
- `createClientIpResolver()` 默认 `auto` 在普通宿主忽略转发头，仅受管私有 Compose 采用容器网段。`[]` 关闭代理信任，自管入口明确填写代理 IP/CIDR；对端地址必须来自 socket 或可信平台。
|
|
706
704
|
- 路径 `encryption` 可为 `required` / `disabled`，省略沿用宿主；重叠路径和方法的相反声明在创建时失败。`check.encryption()` / `requiresEncryption` 供宿主装配传输模式，Core 不持有密钥或执行加解密，仍需 HTTPS 和身份鉴别。
|
|
707
705
|
|
|
708
|
-
完整默认值、独立文件、代理拓扑及部署步骤见[请求访问控制手册](../../docs/usage/configuration/request-access.md)
|
|
706
|
+
完整默认值、独立文件、代理拓扑及部署步骤见[请求访问控制手册](../../docs/usage/configuration/request-access.md).
|
|
709
707
|
|
|
710
708
|
### 生成与校验标识：`core.id`
|
|
711
709
|
|
|
@@ -868,6 +866,16 @@ formatDate 支持 YYYY/MM/DD/HH/mm/ss 占位符，默认 YYYY-MM-DD；日期运
|
|
|
868
866
|
|
|
869
867
|
更完整的参数与少见选项见[Core 使用参考](../cli/templates/skills/hai-core/reference.md)；公开契约以当前包声明为准。
|
|
870
868
|
|
|
869
|
+
## 配置
|
|
870
|
+
|
|
871
|
+
core.init 接收配置目录、配置 Schema 和日志选项，同步返回 void，没有 close。文件加载、环境来源合并和配置字段的具体示例见快速开始与 core.config；不能把 init 返回视为所有业务配置校验成功。
|
|
872
|
+
|
|
873
|
+
[逐项配置说明、适用场景和示例](../../docs/usage/configuration/runtime.md).
|
|
874
|
+
|
|
875
|
+
## 错误处理
|
|
876
|
+
|
|
877
|
+
领域操作先判断 `result.success`，失败按本模块错误定义与安全提示处理，服务端保留错误码、关联编号和脱敏原因。同步工具、工厂、流迭代及生命周期按各自签名处理，不把 Promise 完成视为业务成功。具体失败与恢复边界见对应功能。
|
|
878
|
+
|
|
871
879
|
## 开发测试
|
|
872
880
|
|
|
873
881
|
在仓库根目录执行（PowerShell 使用 `pnpm.cmd`）：
|
|
@@ -879,7 +887,7 @@ pnpm --filter @h-ai/core build
|
|
|
879
887
|
pnpm --filter @h-ai/core test
|
|
880
888
|
```
|
|
881
889
|
|
|
882
|
-
公开声明与示例检查见[模块 JSDoc 约定](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证)
|
|
890
|
+
公开声明与示例检查见[模块 JSDoc 约定](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证).
|
|
883
891
|
|
|
884
892
|
## 许可证
|
|
885
893
|
|
package/package.json
CHANGED