@h-ai/core 1.0.0-beta.2 → 1.0.0-beta.20

package/README.md

@@ -4,649 +4,890 @@
 
 [框架首页](../../README.md)
 
-## 简介
+`@h-ai/core` 是 Hai Framework 的公共基础层，为应用和其他框架模块提供一致的配置、错误、日志和国际化能力。常用工具可直接使用；Node 应用需要加载配置时再调用 `core.init()`。
 
-hai Agent Framework 核心模块 — 提供统一的基础工具、类型定义、配置管理和日志功能。
+## 快速开始
 
-## 核心功能清单
+下面按 `core` 对象上的全部子功能介绍用途、示例与必要限制。需要加载配置时先看初始化；日志、消息和通用工具可直接使用。
 
-- **HaiResult 类型** — 函数式错误处理（`ok` / `err`），所有模块统一返回值
-- **统一日志** — Node.js 基于 pino，浏览器基于 loglevel，API 一致
-- **国际化（i18n）** — 集中式 locale 管理 + 类型安全的消息获取器
-- **Zod 校验错误映射** — 兼容 Zod v3/v4 的 issue 提取与默认英文消息本地化
-- **配置管理** — YAML 加载、约定式环境变量映射、显式环境变量插值、Zod 校验、文件监听（Node.js 专用）
-- **ID 生成** — nanoid 与 UUID v4
-- **错误定义** — 标准化错误码体系，支持跨模块统一的错误定义与实例创建
-- **模块工具** — NotInitializedKit 代理模式，各模块共用的生命周期基础设施
-- **工具函数库** — 类型检查、对象 / 字符串 / 数组 / 异步 / 时间操作
+运行功能通过 `core.xxx()` 或 `core.<子功能>.xxx()` 调用。结果构造器 `ok` / `err`，以及类型、Schema 和错误常量，从包入口单独导入，具体用法见对应小节。
 
-## 使用入门
+```bash
+pnpm add @h-ai/core
+```
 
-### 快速开始
+下方自定义配置和表单校验示例还使用 Zod，运行这些示例前安装 `pnpm add zod`。数据库、缓存示例的额外依赖在相应小节说明。
 
-#### Node.js 环境
+### 初始化：`core.init`
 
-```typescript
-import { core } from '@h-ai/core'
+Node 启动时加载 YAML 并设置日志；浏览器只设置日志。初始化 Core 不会启动数据库等其他模块。
 
-// 初始化：加载配置目录（可选）
-core.init({ configDir: './config', watchConfig: true })
+#### Node.js
 
-// 日志
-core.logger.info('Server started', { port: 3000 })
-core.logger.warn('Slow query', { duration: 2500 })
-core.logger.error('Connection failed', { error })
+准备 `config/_core.yml`：
 
-// 创建模块级 logger（独立名称空间）
-const dbLogger = core.logger.create({ name: 'db' })
-dbLogger.info('Connected to PostgreSQL')
+```yaml
+# 应用元信息，供启动代码和页面读取。
+name: orders
+version: 0.1.0
+env: development
+# 默认消息语言；启动代码读取后调用 setGlobalLocale 应用。
+defaultLocale: zh-CN
+logging:
+  level: info # 输出 info 及以上级别。
+  format: pretty # 本地开发使用便于阅读的日志。
+```
 
-// 创建子 logger（自动携带固定上下文，适合请求级/操作级追踪）
-const reqLogger = core.logger.child({ requestId: 'req-001', userId: 'u-123' })
-reqLogger.info('Request started') // 日志自动包含 requestId + userId
-reqLogger.error('Request failed') // 同上
+```ts
+import { core, CoreConfigSchema } from '@h-ai/core'
 
-// 子 logger 可嵌套
-const opLogger = reqLogger.child({ operation: 'createOrder' })
-opLogger.info('Order created') // 包含 requestId + userId + operation
+// 1. 读取 config 目录中的 YAML，_core.yml 对应名称 core。
+core.init({ configDir: './config' }) // 返回 undefined；配置缓存中可读取 core。
 
-// 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'
+// 2. 检查应用必需的配置；失败时停止启动，保留原始错误供排查。
+const config = core.config.validate('core', CoreConfigSchema)
+if (!config.success)
+  throw new Error(config.error.message, { cause: config.error })
 
-// ID 生成
-const nanoid = core.id.generate()
-const shortId = core.id.short()
-const uuid = core.id.uuid()
-const prefixed = core.id.withPrefix('order_')
+// 成功时 config.success 为 true；config.data.name 为 'orders'，defaultLocale 为 'zh-CN'。
 
-// 工具函数
-core.object.deepMerge(objA, objB)
-core.sanitize.sanitizeSensitiveFields({ password: 'secret', email: 'user@example.com' })
-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)
+// 3. 将配置中的语言应用到默认消息；读取 YAML 本身不会切换语言。
+core.i18n.setGlobalLocale(config.data.defaultLocale) // 返回 undefined；后续默认消息使用中文。
+
+// 4. 记录已验证的应用名称，确认启动完成。
+core.logger.info('Application ready', { name: config.data.name }) // 返回 undefined；info 日志包含 name: 'orders'。
 ```
 
-#### 浏览器环境
+启动边界在必需配置失败时中止启动。`core.init()` 对单项加载失败记日志并继续，所以不能把调用结束视为所有配置校验成功；目录扫描、日志设置等异常仍可能抛出。
+
+#### 浏览器
 
-```typescript
+```ts
 import { core } from '@h-ai/core'
 
-// 初始化日志级别（浏览器不支持配置加载）
-core.init({ logging: { level: 'warn' } })
+// 浏览器不读取 YAML；此处只设置日志，输出 warn 及以上级别。
+core.init({
+  logging: { level: 'warn' }
+}) // 返回 undefined；之后 info 日志被过滤。
 
-core.logger.info('Page ready')
-const id = core.id.generate()
+// 设置当前页面使用的默认消息语言。
+core.i18n.setGlobalLocale('zh-CN') // 返回 undefined；页面默认消息使用中文。
 
-// 其他工具函数与 Node.js 相同
-core.string.capitalize('hello')
-core.array.unique([1, 1, 2])
+// 给一次请求生成编号，后续日志可用同一编号关联排查。
+const requestId = core.id.request() // 返回随机字符串，如 'req-V1StGXR8_Z5jdHi6B-myT'。
+core.logger.warn('Request needs attention', { requestId }) // 返回 undefined；浏览器输出 warn 消息及同一个 requestId。
 ```
 
-浏览器端会保留 `core.config` API 形态以匹配类型定义，但不支持文件配置：
+浏览器配置由宿主通过公开字段下发，不传完整服务端配置或密钥。`core.config.get()` / `has()` / `keys()` 分别返回 `undefined` / `false` / `[]`；`loadEnvFiles()`、`load()`、`validate()`、`reload()` 返回 `SERVICE_UNAVAILABLE`，`getOrThrow()` 抛错。`watch()` 立即回调同一不可用错误并返回空取消函数。
 
-- `core.config.get()` 返回 `undefined`，`has()` 返回 `false`，`keys()` 返回 `[]`
-- `loadEnvFiles()` / `load()` / `validate()` / `reload()` 返回 `HaiCommonError.SERVICE_UNAVAILABLE`
-- `watch()` 会立即用同一错误调用回调，并返回安全的 no-op 取消函数
-- 需要配置时请由服务端读取后通过接口下发，或只在浏览器端用 `core.init({ logging })` 配置日志
+## 功能
 
-### 详细 API
+| 能力             | 解决的问题                                                                                   | 主要入口                                                |
+| ---------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| 配置与启动       | 加载 YAML、合并环境覆盖、校验配置，按依赖顺序编排模块启动与关闭                              | `core.config`、`core.init`、`core.module.createRuntime` |
+| 结果与错误       | 用统一结果表达业务成败，定义错误码，在接口边界生成安全提示                                   | `HaiResult`、`ok` / `err`、`core.error`                 |
+| 日志与诊断       | 结构化日志、请求关联、凭据脱敏及日志观察                                                     | `core.logger`、`core.context`、`core.sanitize`          |
+| 国际化与校验提示 | 管理消息语言，隔离并发请求语言，把 Zod 错误转换为本地化字段提示                              | `core.i18n`、`core.zodValidation`                       |
+| 请求访问控制     | 解析可信客户端地址，按路径、方法、IP 和时段检查请求                                          | `core.access`（Node 专属）                              |
+| 通用工具         | 复用标识生成、类型检查、对象、字符串、数组、异步和时间操作，以及模块未初始化时的统一错误返回 | `core.id`、`core.typeUtils`、`core.object` 等           |
 
-#### 日志（Logger）
+### Node 与浏览器的边界
 
-`core.logger` 既是默认 Logger 实例，也是日志管理的统一入口。
+两端都通过 `import { core } from '@h-ai/core'` 使用，由打包工具选择对应环境的代码。
 
-##### 日志记录
+| 能力                                                      | Node.js                                                        | 浏览器                                                                   |
+| --------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| 日志、结果/错误、消息、通用工具，以及模块的顺序启动与关闭 | 支持                                                           | 支持                                                                     |
+| YAML、dotenv、环境映射与文件监听                          | 可以读取和监听本地配置文件                                     | 不能读取或监听本地文件；调用加载方法会返回失败                           |
+| 请求关联 `core.context.run`                               | 每个请求保留自己的编号等信息，等待异步操作后仍能读取，互不串用 | 只在回调的同步代码中保留信息，`await` 后不再保留                         |
+| 请求语言 `core.i18n.runWithLocale`                        | 请求使用自己的语言，等待异步操作后也不会受其他请求影响         | 调用会抛错；用 `setGlobalLocale()` 设置页面语言，或在取消息时指定 locale |
+| 请求策略 `core.access`                                    | 可以检查请求地址、路径和时段                                   | 不提供此工具                                                             |
 
-6 个级别：`trace` / `debug` / `info` / `warn` / `error` / `fatal`
+`core.init()` 只负责 Core 的配置和日志设置，同步返回 `void`，Core 没有 `close()` 方法。应用如果还需要启动数据库、缓存等模块，可用 `core.module.createRuntime()` 集中管理它们：调用返回对象的 `start()` 依次初始化，调用 `close()` 按相反顺序清理。下方“应用启动与关闭”给出完整示例。
 
-```typescript
-core.logger.info('User created', { userId: '123' })
-core.logger.error('Failed to connect', { error })
-core.logger.debug('Processing item', { id, step: 'validation' })
-```
+### 文件与环境配置：`core.config`
 
-##### 创建模块级 logger
+读取 YAML、应用环境变量覆盖、检查配置类型，并管理配置缓存与文件监听。下列文件与环境操作仅在 Node 中可用。
 
-```typescript
-// 独立名称空间，适合模块内全局使用
-const logger = core.logger.create({ name: 'payment' })
-logger.info('Payment processed')
-```
+#### 加载、校验与读取
 
-##### 子 logger（child）
+`core.init({ configDir, configSchemas?, watchConfig? })` 扫描指定目录直属的 `.yml` / `.yaml` 文件；`_core.yml` 注册为 `core`，`_db.yml` 注册为 `db`，`app.yml` 注册为 `app`。构建/部署设置由 CLI 从项目根 `hai.json` 读取，不属于运行时 YAML。
 
-```typescript
-// 携带固定上下文，每条日志自动附带这些字段
-const reqLogger = core.logger.child({ requestId: 'req-001', userId: 'u-123' })
-reqLogger.info('Request started') // 输出包含 requestId + userId
-reqLogger.warn('Slow response') // 同上
+`_core.yml` 使用 `CoreConfigSchema` 校验，只接受 `name`、`version`、`env`、`defaultLocale` 和 `logging`。默认值依次为 `hai Admin`、`0.1.0`、`development`、`zh-CN`；`logging` 可省略。元数据不会自行修改 `NODE_ENV`、切换消息语言或注册业务翻译。日志应从此处配置；显式传入 `core.init({ logging })` 会覆盖本次初始化对 YAML 日志设置的应用。
 
-// 嵌套 child：子上下文递归合并
-const opLogger = reqLogger.child({ operation: 'login' })
-opLogger.info('Login succeeded') // 输出包含 requestId + userId + operation
-opLogger.error('Login failed', { reason: 'invalid_password' })
+其他配置在扫描时仅借助宿主提供的 `configSchemas` 识别结构和类型，完整业务校验留给模块初始化或显式 `validate()`。直接 `load(name, file, schema)` 会立即校验。
+
+以下文件示例使用这份 `config/app.yml`，并假设没有额外环境变量覆盖：
+
+```yaml
+# config/app.yml
+port: 3000
 ```
 
-> **典型用法**：在请求入口创建 `reqLogger`，传入 service 层，service 层再 `child` 添加操作上下文，最终日志自动串联完整链路。
+`load()` 读取文件并可立即校验；`validate()` 校验已加载的缓存。`get()` 找不到时返回 undefined，`getOrThrow()` 找不到时抛错；泛型只帮助 TypeScript，不会替代实际校验。`has()` / `keys()` 用于检查有哪些配置。
 
-##### 日志管理
+```ts
+import { core } from '@h-ai/core'
+import { z } from 'zod'
 
-```typescript
-// 配置输出格式和级别（Node.js / Browser）
-core.logger.configure({
-  level: 'info',
-  format: 'json', // 'json' | 'pretty'
-  context: { app: 'my-service' }, // 全局默认上下文
-  redact: ['password', 'token'], // 脱敏字段
+// 读取上方 config/app.yml；Schema 同时描述类型和校验规则。
+const AppSchema = z.object({
+  port: z.number().int().min(1).max(65535)
 })
+const loaded = core.config.load('app', './config/app.yml', AppSchema)
+if (!loaded.success)
+  throw new Error(loaded.error.message, { cause: loaded.error })
 
-core.logger.setLevel('debug')
-const level = core.logger.getLevel() // 'debug'
-```
+// loaded：{ success: true, data: { port: 3000 } }。
 
-`core.init()` 加载 `_core.yml.logging` 后，或调用 `configure` / `setLevel` 后，默认、模块和嵌套 child Logger 会在后续输出中使用当前全局配置，即使这些实例在初始化前创建。`create({ level, format, context })` 的显式级别、格式和本地上下文仍优先；未指定的选项动态继承全局配置，调用时上下文覆盖固定上下文。附加 `redact` 对这些实例统一生效，不需要重建模块 Logger。
+// validate 用于重新校验缓存；加载时未传 Schema 的配置也可在这里校验。
+const validated = core.config.validate('app', AppSchema)
+if (!validated.success)
+  throw new Error(validated.error.message, { cause: validated.error })
 
-浏览器仍输出到 DevTools console：`pretty` 使用可读消息与上下文，`json` 输出包含 `level` / `msg` 的 JSON 字符串。默认凭据脱敏与配置的字段路径脱敏同时生效，支持嵌套点/括号路径和 `*`；消息文本本身需调用方脱敏。
+// validated：{ success: true, data: { port: 3000 } }。
 
-日志上下文中的原生 `Error` 会先转为包含 `name`、`message`、`stack`、`cause`、`AggregateError.errors` 与可枚举自有上下文的副本，再执行默认字段/URL 脱敏与配置的 `redact`；两端规则一致，原异常不变。异常子图循环返回 `[Circular]`，32 层上限返回 `[MaxDepth]`；其中的自定义替换值也经同一规范化处理，普通对象的替换语义不变。无 Error 的普通对象循环仍保留原结构，不保证可直接 JSON 序列化。异常文本会清理显式标注的凭据（如 `passwordHash=...`、`secretKey=...`）、认证头和 URL 凭据；无法保证识别任意无标签秘密，调用方仍应清理或用 `error.message` / `error.stack` 等路径整体遮蔽。
+// get 适合可选配置；getOrThrow 适合已确认存在的必需配置。
+if (core.config.has('app')) { // true：上方已成功加载 app。
+  const optional = core.config.get<z.infer<typeof AppSchema>>('app') // { port: 3000 }。
+  const required = core.config.getOrThrow<z.infer<typeof AppSchema>>('app') // { port: 3000 }；缺失则抛错。
+  core.logger.info('App config ready', { port: required.port, available: optional !== undefined })
+}
+core.config.keys() // 仅运行本节 load 示例时为 ['app']。
+```
+
+#### 重载、监听与清理
 
-`core.logger` 默认会对日志上下文执行安全脱敏：`password`、`passwordHash`、`passwd`、`token`、`secret`、`secretKey`、`privateKey`、`apiV3Key` 等凭证类字段会替换为 `[REDACTED]`，`url` / `baseUrl` / `endpoint` 这类字段会掩码 URL 中的用户名、密码和敏感查询参数（含 OAuth 键值 fragment）；非法 URL 返回固定占位符；邮箱、手机号默认不会被遮盖。
+修改配置后可用 `reload()` 主动读盘，也可用 `watch()` 接收新值或错误。监听支持普通保存、文件原子替换以及删除后重建；失败保留最近一次成功的缓存。`unwatch()` 停止监听，`clear()` 同时清缓存；二者省略名称时作用于全部配置。
 
-##### 日志级别规范
+`watchConfig` 默认 false；重载缓存不会自动重新初始化数据库等已启动模块。下面的清理操作应在不再需要这份配置时调用。
 
-| 级别    | 适用场景                           |
-| ------- | ---------------------------------- |
-| `trace` | 循环内详细调试数据                 |
-| `debug` | 函数进入、参数概要、读操作         |
-| `info`  | 业务事件（初始化完成、写操作成功） |
-| `warn`  | 异常但可恢复（校验失败、重试）     |
-| `error` | 操作失败（需人工排查）             |
-| `fatal` | 致命错误（服务无法继续）           |
+```ts
+import { core } from '@h-ai/core'
 
-#### 国际化（i18n）
+// 前提：app 已由 init/load 加载。回调需先处理读取或校验失败。
+const stop = core.config.watch('app', (_settings, error) => {
+  // 文件改成 port: 4000 后，成功回调收到 { port: 4000 }、error 为 undefined；失败时为 null 和错误对象。
+  if (error)
+    core.logger.error('Config reload failed', { error })
+  else
+    core.logger.info('Config reloaded')
+})
+// watch 返回取消函数 stop，不立即返回配置值。
+core.config.isWatching('app') // true。
+const reloaded = core.config.reload('app') // 文件仍为 port: 3000 时返回 { success: true, data: { port: 3000 } }。
+if (!reloaded.success)
+  core.logger.warn('Manual reload failed', { error: reloaded.error })
+
+stop() // 返回 undefined；取消当前回调，没有其他回调时停止底层监听。
+core.config.unwatch('app') // 返回 undefined；isWatching('app') 变为 false。
+core.config.clear('app') // 返回 undefined；get('app') 变为 undefined，has('app') 变为 false。
+```
 
-内置语言为 `zh-CN`、`en-US`、`ja-JP`；`ja` 简写会规范化为 `ja-JP`，所有模块共用此语言设置。
+#### 环境变量如何改变 YAML 配置
 
-```typescript
-// 设置全局语言（所有 getMessage 函数自动响应）
-core.i18n.setGlobalLocale('en-US')
-const current = core.i18n.getGlobalLocale() // 'en-US'
+框架根据配置名和字段位置自动确定用于覆盖配置的环境变量名。例如文件 `app.yml` 的 `port` 对应 `HAI_APP_PORT`，嵌套的 `http.maxRetries` 对应 `HAI_APP_HTTP_MAXRETRIES`。每层转大写并用 `_` 连接，camelCase 不拆词；YAML 不必写 `${...}` 才能被覆盖。
 
-// 为每个模块创建消息获取器
-const getMessage = core.i18n.createMessageGetter({
-  'zh-CN': { welcome: '欢迎 {name}', error: '错误：{code}' },
-  'en-US': { welcome: 'Welcome {name}', error: 'Error: {code}' },
-})
+先看一个固定值的例子：YAML 写 `port: 3000`，没有 `HAI_APP_PORT` 时得到 3000，设置 `HAI_APP_PORT=5000` 后得到 5000。
 
-// 使用：自动读取全局 locale，支持参数插值
-getMessage('welcome', { params: { name: 'Alice' } }) // 'Welcome Alice'
+在 YAML 中写 `${变量名}`，读取时就会用对应环境变量的值替换这段表达式。冒号后面的文字是在变量没有设置时使用的默认值：
 
-// 支持 locale 参数覆盖
-getMessage('welcome', { locale: 'zh-CN', params: { name: 'Alice' } }) // '欢迎 Alice'
+| YAML 写法                    | 环境输入                         | 读取结果                                                 |
+| ---------------------------- | -------------------------------- | -------------------------------------------------------- |
+| `port: ${PORT}`              | `PORT=4000`                      | 使用 4000；若 PORT 没设置，返回 `CONFIG_ENV_VAR_MISSING` |
+| `port: ${PORT:3000}`         | 没有 PORT                        | 使用表达式中的默认值 3000                                |
+| `port: ${PORT:3000}`         | `PORT=4000`、`HAI_APP_PORT=5000` | 使用 5000，约定变量优先                                  |
+| `label: server-${PORT:3000}` | `PORT=4000`                      | 拼成字符串 `server-4000`                                 |
 
-// 常量
-core.i18n.DEFAULT_LOCALES // [{ code: 'zh-CN', label: '简体中文' }, { code: 'en-US', label: 'English' }, { code: 'ja-JP', label: '日本語' }]
-core.i18n.DEFAULT_LOCALE // 'zh-CN'
-```
+实际读取顺序是：先检查 `HAI_APP_PORT`；有值就直接覆盖这一项，不再解析该项的 `${PORT...}`。否则读取 YAML：写了表达式才查 PORT，写的是固定值就直接用固定值。因此已有 HAI_APP_PORT 覆盖时，不要求 PORT 也存在。
 
-#### 脱敏工具
+同一份环境来源可以先给父对象 JSON，再覆盖具体字段：`HAI_APP='{"port":3000,"label":"local"}'` 配合 `HAI_APP_PORT=4000`，结果是 port=4000、label=local，与行顺序无关。高优先级来源整体替换对象时，不会继续保留低来源的细项覆盖。数组 JSON 替换整个列表，索引变量只修改已有项，越界报错。
 
-`core.sanitize.sanitizeSensitiveFields()` 可递归脱敏对象/数组中的敏感字段；默认会处理 password/passwordHash、passwd、token、secret/secretKey、privateKey、apiV3Key 等凭证类字段，并自动掩码 `url` / `baseUrl` / `endpoint` 字段中的内嵌凭证、敏感查询参数和 OAuth 键值 fragment。`core.sanitize.sanitizeUrl(url, options)` 可单独处理 URL，非法 URL 返回 `(invalid url)`；自定义 matcher 同样适用于参数名。`sanitizeText` 清理显式凭据标签和 URL，也可传入调用方已知的秘密值；它不识别任意无标签秘密。
+#### 从 .env 文件读取变量
 
-```typescript
-core.sanitize.sanitizeSensitiveFields({
-  email: 'user@example.com',
-  password: 'secret',
-  baseUrl: 'https://user:pass@example.com/api/v1',
-  profile: { token: 'jwt-token' },
-})
-// => { email: 'user@example.com', password: '[REDACTED]', baseUrl: 'https://[REDACTED]:[REDACTED]@example.com/api/v1', profile: { token: '[REDACTED]' } }
+`core.init()` 不自行读取 .env 文件。需要时先调用 `loadEnvFiles()`，确认 success 后把结果放入 process.env，再加载 YAML。`development` / `production` 映射为 `dev` / `prod`；缺失文件跳过，同文件重复键报错。优先级从高到低是：**进程环境 > `.env.<mode>.local` > `.env.local` > `.env.<mode>` > `.env` > YAML**。私有 .local 文件不提交 Git。
 
-core.sanitize.sanitizeSensitiveFields({ email: 'user@example.com' }, {
-  matcher: /email/i,
-  replacement: '***',
-})
-// => { email: '***' }
-```
+```ts
+import { core } from '@h-ai/core'
 
-#### Zod 校验错误 i18n 映射
+// 前提：.env 写 HAI_APP_PORT=4000，没有其他来源覆盖这个变量。
+// 先读取并合并 .env 文件与进程环境，失败时停止启动。
+const result = core.config.loadEnvFiles({ mode: 'dev', envDir: '.' })
+if (!result.success)
+  throw new Error(result.error.message, { cause: result.error })
+// 成功时 result.success 为 true，result.data.HAI_APP_PORT 为 '4000'；其他键来自合并后的环境。
+// 返回值不会自动写入进程；显式应用后再初始化。
+Object.assign(process.env, result.data)
+core.init({ configDir: './config' }) // 返回 undefined；app.yml 中 port: 3000 被覆盖为数字 4000。
+```
 
-`core.zodValidation` 用于把 Zod `SafeParseError` / `ZodError` 转为扁平表单错误，并将 Zod
-默认英文消息映射为调用方自己的 i18n 文案。
+#### 替换后的值是什么类型
 
-严格 schema 的未知字段错误映射为 `validationUnexpectedFields`，不向用户暴露内部字段名。自定义消息获取器需要处理此 key；Kit、Serv 已提供中英日文提示。Schema 显式指定的业务消息仍原样保留。
+环境变量原本都是文本。给 `load()` / `resolve()` 传入 Zod Schema 后，框架会按字段类型转换替换结果：`z.number()` 对应数字，`z.boolean()` 对应布尔值，`z.string()` 保留字符串。
 
-- 两个公开入口：
-  - `createPrefixedZodMessageGetter()`：按模块前缀自动派生 `serv_validation*` / `kit_validation*` 这类 key，省掉手写 `KEY_MAP`
-  - `mapZodErrorToFormErrors()`：一步完成提取 + 本地化 + 扁平化
-- 自定义业务消息不会被覆盖；只有 Zod 默认英文消息才会被替换
+例如 `${PORT:3000}` 占据整个值时，可得到数字 3000；`${ENABLED:false}` 可得到布尔值 false。`server-${PORT:3000}` 带有其他文字，拼接后仍是字符串。字符串字段 `code` 的默认文本 00123 保持为 `'00123'`，不会丢掉前导零。下面不用读文件，直接给出相同的 YAML 内容和环境数据来演示：
 
-```typescript
-import type { ZodMessageGetter } from '@h-ai/core'
+```ts
 import { core } from '@h-ai/core'
 import { z } from 'zod'
 
-const LoginSchema = z.object({
-  email: z.string().email(),
-  password: z.string().min(8),
-  nickname: z.string().min(1, '请填写昵称'),
+// 用显式环境数据演示覆盖顺序、数值/布尔转换与字符串保留。
+const AppSchema = z.object({
+  port: z.number(),
+  enabled: z.boolean(),
+  label: z.string(),
+  code: z.string()
 })
-
-const getMessage: ZodMessageGetter = (key, params) => {
-  switch (key) {
-    case 'validationEmail':
-      return '请输入合法邮箱地址'
-    case 'validationStringMin':
-      return `至少输入 ${params?.min} 个字符`
-    case 'validationRequired':
-      return '此项为必填项'
-    default:
-      return '输入不合法'
-  }
-}
-
-const result = LoginSchema.safeParse({
-  email: 'bad',
-  password: '123',
-  nickname: '',
+const resolved = core.config.resolve({
+  name: 'app',
+
+  value: {
+    // eslint-disable-next-line no-template-curly-in-string -- 保留供配置解析器处理的字面占位符。
+    port: '${PORT:3000}',
+    // eslint-disable-next-line no-template-curly-in-string -- 保留供配置解析器处理的字面占位符。
+    enabled: '${ENABLED:false}',
+    // eslint-disable-next-line no-template-curly-in-string -- 保留供配置解析器处理的字面占位符。
+    label: 'server-${PORT:3000}',
+    // eslint-disable-next-line no-template-curly-in-string -- 保留供配置解析器处理的字面占位符。
+    code: '${APP_CODE:00123}'
+  },
+  environment: { PORT: '4000', HAI_APP_PORT: '5000' },
+  schema: AppSchema,
 })
+if (!resolved.success)
+  throw new Error(resolved.error.message, { cause: resolved.error })
 
-if (!result.success) {
-  const getMessage = core.zodValidation.createPrefixedZodMessageGetter(
-    'kit',
-    (messageKey, params) => {
-      if (messageKey === 'kit_validationEmail')
-        return '请输入合法邮箱地址'
-      if (messageKey === 'kit_validationStringMin')
-        return `至少输入 ${params?.min} 个字符`
-      return '输入不合法'
-    },
-  )
-  const errors = core.zodValidation.mapZodErrorToFormErrors(result.error, getMessage)
-
-  errors[0]?.field // 'email'
-  errors[0]?.message // '请输入合法邮箱地址'
-  errors[2]?.message // '请填写昵称'（schema 自定义消息原样保留）
+// resolved：{ success: true, data: { port: 5000, enabled: false, label: 'server-4000', code: '00123' } }。
 
-  core.logger.info('Validation failed', { errors })
-}
+// resolve 只做替换和类型还原；再用 Schema 确认最终数据符合要求。
+const validated = AppSchema.safeParse(resolved.data)
+if (!validated.success)
+  throw new Error(validated.error.message, { cause: validated.error })
+core.logger.info('Config resolved', { settings: validated.data })
+// settings: { port: 5000, enabled: false, label: 'server-4000', code: '00123' }
 ```
 
-#### 配置管理（Node.js 专用）
+空字符串表示“变量已经设置，只是内容为空”，不会被当成缺失、null、false 或 0。例如 `APP_CODE=''` 会使 code 保持 `''`，不会改用 00123；是否允许空串由 Schema 决定。数字字段收到空串则通常校验失败。
 
-> 浏览器端没有文件系统，`core.config` 仅提供占位 API：文件相关方法返回 `SERVICE_UNAVAILABLE`，不会加载 YAML。
+变量替换只处理 YAML 中的表达式；环境变量或父 JSON 中的 `server-${PORT}` 会按原文保留。例如 `HAI_APP_LABEL='server-${PORT}'` 最终仍为 `server-${PORT}`。需要替换时，把表达式写在 YAML 中。
 
-Node 自动加载和监听配置目录内所有 `.yml` / `.yaml`，没有保留文件名例外。项目根 `hai.json` 中的 `build` / `deploy` 由 CLI 读取，不进入运行时 YAML 配置。单项加载返回失败时记录错误并继续，必需配置由应用调用 `core.config.validate` 并检查 `success`；目录扫描、日志设置等异常仍可能传播。
+没有 Schema 时，框架按现有 YAML/JSON 结构识别路径，并对单个表达式按 YAML 规则解释数字/布尔值；缺少的合法可选路径可由 `configSchemas` 提供。最终业务校验仍应通过 `validate()` 或模块 init 执行。
 
-```typescript
-import { core, HaiConfigError } from '@h-ai/core'
-import { z } from 'zod'
+#### 生成配置文件时使用的工具
 
-// 方式 1：init 时自动加载运行时配置
-core.init({
-  configDir: './config', // 扫描配置目录内所有 .yml / .yaml
-  watchConfig: true, // 监听变更并自动重载
-})
+`resolve()` 也可供构建/部署工具在内存中计算配置。`toEnv()` 把对象转为环境变量，`mergeEnv()` 合并多个来源，`stringifyEnv()` / `parseEnv()` 编解码 .env 文本；这些工具不自动脱敏。
 
-// 方式 2：手动加载单个文件（可选 Schema 校验）
-const AppSchema = z.object({
-  name: z.string(),
-  port: z.number().default(3000),
+```ts
+import { core } from '@h-ai/core'
+
+// 配置生成器把普通对象转成 HAI_APP_PORT 等变量；数组保留为 JSON。
+const values = core.config.toEnv({
+  prefix: 'HAI_APP',
+  value: {
+    port: 3000,
+    tags: ['local']
+  }
 })
-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 })
-}
+// values：{ HAI_APP_PORT: '3000', HAI_APP_TAGS: '["local"]' }。
+const merged = core.config.mergeEnv([
+  values,
+  { HAI_APP_PORT: '4000' }
+])
+// merged：{ HAI_APP_PORT: '4000', HAI_APP_TAGS: '["local"]' }。
+const text = core.config.stringifyEnv(merged) // 编码为可写入 .env 的文本。
+// text 含以下两行，每行以换行符结尾：
+// HAI_APP_PORT='4000'
+// HAI_APP_TAGS='["local"]'
+const restored = core.config.parseEnv(text) // 解析回字面字符串，不执行其中的变量。
+// restored：{ HAI_APP_PORT: '4000', HAI_APP_TAGS: '["local"]' }。
+core.logger.info('Generated config verified', { port: restored.HAI_APP_PORT })
+```
 
-// 校验已加载的配置
-const validResult = core.config.validate('app', AppSchema)
+普通对象默认展开；数组、动态字典和空对象保留 JSON。整体替换对象的生成规则、完整来源优先级与应用接入见[基础配置手册](../../docs/usage/configuration/runtime.md).
 
-// 查询和获取
-if (core.config.has('app')) {
-  const cfg = core.config.get<z.infer<typeof AppSchema>>('app') // undefined 或配置
-  const cfg2 = core.config.getOrThrow<z.infer<typeof AppSchema>>('app') // 未加载时抛异常
-}
-core.config.keys() // ['core', 'app', 'db', ...]
+### 记录日志：`core.logger`
 
-// 重新加载
-const reloadResult = core.config.reload('app')
+`core.logger` 用于记录结构化日志。六个级别从详细到严重依次为 trace、debug、info、warn、error、fatal；fatal 记录日志，是否退出由应用决定。
 
-// 监听文件变更
-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 })
+`core.logger` 支持 `trace` / `debug` / `info` / `warn` / `error` / `fatal`。Node 使用 pino，浏览器使用 loglevel；未配置时为 `info` / `pretty`。若提供经 `LoggingConfigSchema` 解析的 `logging` 对象，其格式默认 `json`。Node 缺少可选 `pino-pretty` 时使用 JSON 输出。
+
+```ts
+import { core } from '@h-ai/core'
+
+// 先设置级别；低于当前级别的日志不会输出。
+core.logger.setLevel('trace') // 返回 undefined；以下六个级别均会输出。
+core.logger.trace('Processing detail', { step: 1 })
+core.logger.debug('Read started')
+core.logger.info('Order created', { orderId: 'order-1' })
+core.logger.warn('Retry scheduled')
+core.logger.error('Operation failed', {
+  error: new Error('Example failure')
 })
-unwatch() // 取消监听
+core.logger.fatal('Service cannot continue')
+// 六次日志调用均返回 undefined；分别输出对应级别、上面的消息及所传字段。
+// 例如 info 日志的消息为 'Order created'，字段 orderId 为 'order-1'。
+```
 
-// 清除缓存（同时停止对应监听）
-core.config.clear('app') // 清除单个
-core.config.clear() // 清除全部
+`create()` 创建有名称的 Logger，`child()` 给后续日志附带固定字段。`configure()` 设置输出与附加脱敏路径，`setLevel()` / `getLevel()` 调整或查看全局级别。
+
+```ts
+import { core } from '@h-ai/core'
+
+// 全局配置可作用于已经创建的 Logger；redact 补充业务隐私字段。
+core.logger.configure({
+  level: 'info',
+  format: 'json',
+  redact: ['customer.email']
+}) // 返回 undefined；后续日志按此配置输出。
+const orders = core.logger.create({ name: 'orders' }) // 返回 Logger 对象，可调用 info/warn 等方法。
+const request = core.logger.child({ requestId: 'request-1' }) // 返回带固定 requestId 的 Logger。
+orders.info('Order created', {
+  customer: { email: 'user@example.com' }
+}) // 返回 undefined；输出中 customer.email 为 '[REDACTED]'。
+request.warn('Request needs attention') // 返回 undefined；输出中 requestId 为 'request-1'。
+core.logger.getLevel() // 'info'。
 ```
 
-##### dotenv 文件与环境切换
+已有默认、模块和嵌套 child Logger 的后续输出会使用当前全局配置，`setLevel()` 也即时生效。`create()` 显式指定的 level/format/context 优先；未指定项动态继承，调用时上下文覆盖固定上下文，当前请求关联字段再由 `core.context` 附加。浏览器 JSON 输出包含 `level` / `msg`，pretty 输出可读消息和上下文。
 
-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。
+`observe()` 用于诊断采集，接收经过当前级别过滤与脱敏的记录，返回解除订阅的函数。回调只做有界内存收集，持久化由应用另行异步完成；它不代表日志已保存。回调异常与同步重入被隔离。
 
 ```ts
-const env = core.config.loadEnvFiles({ mode: 'dev', envDir: '.' })
-if (!env.success)
-  throw new Error(env.error.message)
-Object.assign(process.env, env.data)
-core.init({ configDir: './config' })
+import { core } from '@h-ai/core'
+
+// 观察经过级别过滤和脱敏的记录；内存收集设置上限。
+const recentMessages: string[] = []
+const stop = core.logger.observe((record) => {
+  if (recentMessages.length === 100)
+    recentMessages.shift()
+  recentMessages.push(record.message)
+})
+// observe 返回取消函数 stop；本例 warn 日志触发一次回调，record.message 为 'Observed event'。
+core.logger.warn('Observed event')
+recentMessages // ['Observed event']。
+stop() // 返回 undefined；后续日志不再进入这个回调。
 ```
 
-##### 环境变量映射与插值
+### 关联同一次请求：`core.context`
 
-`core.config.load(name, ...)` 会为每个 YAML 叶子配置项自动映射
-`HAI_<配置名>_<YAML 路径>` 环境变量。配置名和每层 key 转成大写，层级以 `_`
-分隔，camelCase 不拆词；例如 `ai.llm.apiKey` 对应 `HAI_AI_LLM_APIKEY`，
-`ai.llm.maxTokens` 对应 `HAI_AI_LLM_MAXTOKENS`。数组索引也作为一层，例如
-`ai.llm.models[0].temperature` 对应 `HAI_AI_LLM_MODELS_0_TEMPERATURE`。
+`run()` 让一次请求或任务携带 requestId、userId、scopeId、jobId 等关联信息，`get()` 读取当前值。Node 中等待数据库或其他异步操作后，仍能读取这次请求自己的信息，其他请求不会覆盖它。已有 Logger 会自动带上这些字段。
 
-环境变量存在时覆盖 YAML 值，并按 YAML 标量规则还原 number / boolean 等类型；
-环境变量不存在时保留 YAML 值。对象或数组节点也可用同名变量整体替换（JSON），例如 HAI_DB 切换完整连接配置、HAI_REACH_PROVIDERS 替换渠道数组。父节点整体覆盖优先于其子字段环境变量；替换后仍执行 Schema 校验。
+```ts
+import { core } from '@h-ai/core'
 
-```yaml
-# config/_ai.yml（core.init 扫描后配置名为 ai）
-llm:
-  apiKey: ''
-  baseUrl: https://api.xiaomimimo.com/v1
-  model: mimo-v2.5
-  maxTokens: 4096
+// Node 示例：同一请求等待异步处理后，仍能取得自己的编号。
+await core.context.run({ requestId: 'request-1', userId: 'user-1' }, async () => {
+  await core.async.delay(1)
+  const current = core.context.get() // 包含 requestId: 'request-1'、traceId: 'request-1'、userId: 'user-1'；其他字段为 undefined。
+  core.logger.info('Request continued', { requestId: current.requestId })
+  return current.requestId
+}) // run 返回回调的结果；此处 await 后得到 'request-1'。
+core.context.get() // {}，回到外层后不保留上面请求的上下文。
+
+// 采集器自身写日志时，可暂停观察回调，正常日志输出仍然执行。
+core.context.run({ suppressLogObservers: true }, () => core.logger.warn('Collector diagnostic'))
+// 返回 undefined；输出 warn 日志，但不会触发日志观察回调。
 ```
 
-```dotenv
-HAI_AI_LLM_APIKEY=your-api-key
-HAI_AI_LLM_MAXTOKENS=8192
+浏览器只能在 run 回调的同步代码中保留信息，await 后不再保留。关联编号不是身份授权，用户和租户范围必须由可信服务端代码提供。
+
+### 清理诊断数据：`core.sanitize`
+
+用于日志、诊断包或公开错误输出前清理凭据。可以判断字段名是否敏感、清理单个值、递归处理对象、遮蔽 URL 凭据，或清理文本中带标签的凭据和调用方已知的秘密值。
+
+```ts
+import { core } from '@h-ai/core'
+
+core.sanitize.isSensitiveKey('apiKey') // true。
+core.sanitize.sanitizeSensitiveValue('example-only', 'password') // '[REDACTED]'。
+const safe = core.sanitize.sanitizeSensitiveFields({ password: 'example-only', email: 'user@example.com' })
+// safe：{ password: '[REDACTED]', email: 'user@example.com' }，原对象不变。
+// 默认仅遮蔽凭据；额外业务隐私可在已处理凭据的副本上继续清理。
+core.sanitize.sanitizeSensitiveFields(safe, {
+  matcher: ['email'],
+  replacement: '***'
+})
+// => { password: '[REDACTED]', email: '***' }
+core.sanitize.sanitizeUrl('https://user:example-only@example.com/?token=example-only')
+// => 'https://[REDACTED]:[REDACTED]@example.com/?token=[REDACTED]'
+core.sanitize.sanitizeText('Bearer example-only') // '[REDACTED]'。
+core.sanitize.sanitizeText('Request failed with a known private value', ['private value'])
+// => 'Request failed with a known [REDACTED]'
 ```
 
-确实需要特殊变量名时，继续使用显式 `${VAR}` 语法。优先级固定为：
-约定环境变量 > 显式环境变量 > YAML 默认值。
+`defaultSensitiveKeyRegex` / `defaultSensitiveReplacement` 提供默认匹配规则和 `[REDACTED]` 替换值。传入自定义 matcher 会替换默认匹配规则，所以额外清理业务隐私时应先保留默认凭据清理结果。
 
-- `${VAR}` — 读取 `process.env.VAR`；若不存在则返回 `CONFIG_ENV_VAR_MISSING` 错误
-- `${VAR:default}` — 读取 `process.env.VAR`；若不存在则使用冒号后的默认值
+日志默认遮蔽 password/passwordHash、token、secretKey、privateKey 等凭据字段，以及 URL 的用户名、密码、敏感查询参数和 OAuth 键值 fragment；非法 URL 返回 `(invalid url)`。`redact` 叠加业务隐私路径，支持点/括号和单层 `*`，区分大小写；邮箱、手机号默认保留。
 
-**类型还原：** 当整个值恰好是单个变量表达式（如 `${PORT:3000}`）时，插值结果按 YAML 规则还原为原生类型（number / boolean 等）。混合文本始终为字符串。
+原生 `Error` 先转为含 name/message/stack/cause、聚合错误和枚举上下文的副本再脱敏，不修改原异常；异常子图循环和 32 层深度分别使用 `[Circular]` / `[MaxDepth]`。普通对象循环保留，不保证可直接 JSON 序列化。消息与异常文本会清理显式凭据标签和 URL，无法识别任意无标签秘密，调用方仍需清理或整体遮蔽相应路径。
 
-`${VAR:}` 或值为空字符串的 `${VAR}` 会保留为 `''`，不会被 YAML 转成 `null`。需要表达“未配置”的模块应在自身 Schema 中把空字符串规范化为 `undefined`。
+脱敏结果只保留数据：普通对象和类实例复制自有、可枚举的数据属性，不保留类原型，不执行访问器或自定义 `toJSON()`。日期转为 ISO 字符串，URL 转为已脱敏的字符串；原对象保持不变。记录 SDK/业务对象时仍应只选取排查所需字段，未标注的秘密和业务隐私需由应用明确清理。
 
-```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
-```
-
-UUID 只使用密码学安全的 randomUUID/getRandomValues；均不可用时明确抛错，不生成 Math.random 标识。
-
-#### 工具函数
-
-```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) // Node 使用原生等长比较；浏览器不保证恒时
-
-// 数组操作
-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)
-```
-
-Node 入口的 core.string.constantTimeEqual 将原始 UTF-16 单元编码后使用 node:crypto.timingSafeEqual 比较等长字节，长度不相同时直接 false，长度本身不受保护。浏览器实现仅避免按内容提前返回，不提供 JavaScript 引擎级恒时保证，不用于服务端凭证校验。外围分支、编码和请求处理不因此自动成为恒时。
-
-#### 模块基础工具（module）
-
-提供各模块共用的初始化错误处理：
-
-```typescript
-import { core } from '@h-ai/core'
+### 结果与错误：`core.error`
 
-const notInitialized = core.module.createNotInitializedKit(
-  HaiDbError.NOT_INITIALIZED,
-  () => dbM('db_notInitialized'),
-)
+用 `core.error` 定义模块错误、创建本次失败的实例，并在 HTTP/UI 边界生成安全提示。错误码稳定，消息可以按当前语言产生；接口响应状态和响应头由 Serv/Kit 等 HTTP 框架处理。
 
-// 创建占位 Proxy（异步接口，默认）
-const currentDdl: DdlOperations = notInitialized.proxy<DdlOperations>()
-// 创建占位 Proxy（同步接口）
-const currentHash: HashOperations = notInitialized.proxy<HashOperations>('sync')
-```
+```ts
+import { core } from '@h-ai/core'
 
-### 错误处理
+// 定义稳定错误码，消息在创建实例时根据当前语言获取。
+const OrderError = core.error.buildHaiErrorsDef('orders', { NOT_FOUND: '300:404' })
+// OrderError.NOT_FOUND：{ code: 'hai:orders:300', httpStatus: 404, system: 'hai', module: 'orders' }。
+const failure = core.error.buildHaiErrorInst(OrderError.NOT_FOUND, core.i18n.coreM('core_errorNotFound', { locale: 'zh-CN' }))
+// failure：上面的错误定义加上 message: '资源不存在'。
+const publicError = core.error.toPublic(failure, 'request-1')
+// publicError：保留 code/httpStatus/system/module，增加 traceId: 'request-1'；
+// message 为 '资源不存在 (traceId: request-1)'。
+const message = core.error.formatMessage(publicError) // '资源不存在 (traceId: request-1)'，编号不会重复追加。
+core.logger.warn('Order unavailable', { error: failure, publicMessage: message })
+```
 
-#### HaiResult 类型
+#### 共用结果类型与独立构造器
 
-所有可能失败的操作返回 `HaiResult<T>`：
+`HaiResult<T>` 用 success 区分 data 和 error。单独导入 `ok` / `err` 可构造成功或失败的结果。调用业务 API 后先检查 success；getter、工具与工厂按各自签名返回直接值或抛错。
 
-```typescript
+```ts
 import type { HaiResult } from '@h-ai/core'
 import { core, err, HaiCommonError, ok } from '@h-ai/core'
 
+// 业务失败返回 err，成功返回 ok；共用构造器保持独立导入。
 function divide(a: number, b: number): HaiResult<number> {
   if (b === 0)
-    return err(HaiCommonError.VALIDATION_ERROR, 'Division by zero')
-  return ok(a / b)
+    return err(HaiCommonError.VALIDATION_ERROR, core.i18n.coreM('core_errorValidation', { locale: 'zh-CN' }))
+  return ok(a / b) // 如 ok(5) 返回 { success: true, data: 5 }。
 }
 
-const result = divide(10, 2)
-if (result.success) {
-  core.logger.info('Result', { data: result.data })
-}
-else {
-  core.logger.error('Error', { error: result.error })
-}
+// 先检查 success，再读取 data 或 error。
+const result = divide(10, 2) // { success: true, data: 5 }。
+if (!result.success)
+  core.logger.warn('Calculation failed', { error: result.error })
+else
+  core.logger.info('Calculation completed', { value: result.data })
+
+const failed = divide(10, 0)
+// failed：{ success: false, error: { code: 'hai:common:200', httpStatus: 400,
+// system: 'hai', module: 'common', message: '验证失败' } }，无 data。
+if (!failed.success)
+  core.logger.warn('Calculation rejected', { code: failed.error.code })
 ```
 
-#### 自定义错误码（模块级）
+在 HTTP/UI 边界使用 `core.error.toPublic(error, traceId?, locale?)`：5xx 改为本地化通用提示，清理其他消息中的已知凭据，仅保留安全字段。追踪编号依次取显式参数、上下文 traceId/requestId、已有 error.traceId，否则生成；`formatMessage()` 在消息中附加合法编号，重复调用不会重复追加同一编号。
+
+内部 `cause` / `ext` 默认不公开；400/422 的字段校验可保留 `field` / `message`，明确批准且经业务 Schema 校验的 `publicExt` 会脱敏后转为公开 `ext`。Core 不自动验证 `publicExt` 的业务安全性。HTTP 状态、响应头和提示组件由 Serv/Kit/UI 宿主装配。
 
-```typescript
-import type { ErrorInfo } from '@h-ai/core'
+| 配置错误                  | 错误码         | 场景                       |
+| ------------------------- | -------------- | -------------------------- |
+| `CONFIG_FILE_NOT_FOUND`   | `hai:core:010` | 文件不存在                 |
+| `CONFIG_PARSE_ERROR`      | `hai:core:011` | YAML/dotenv 读取或解析失败 |
+| `CONFIG_VALIDATION_ERROR` | `hai:core:012` | Schema 或环境覆盖无效      |
+| `CONFIG_ENV_VAR_MISSING`  | `hai:core:013` | 必需插值变量缺失           |
+| `CONFIG_NOT_LOADED`       | `hai:core:014` | 配置未加载                 |
+
+以上常量来自 `HaiConfigError`；跨模块通用错误使用 `HaiCommonError`。
+
+通用错误 `HaiCommonError.RATE_LIMIT_EXCEEDED` 对应 `hai:common:203` / HTTP 429；Kit 的快捷响应和守卫同样使用通用错误码。
+
+HTTP/UI 边界只对明确的有效 4xx 状态公开业务提示；错误缺少 `httpStatus` 或状态非法时按 500 返回安全提示。手写业务错误须提供完整错误定义或显式状态，不能依赖缺省状态展示原文。
+
+### 消息与语言：`core.i18n`
+
+为业务字典创建带参数替换的消息获取器，也可取得 Core 内置消息和当前语言。常量列出框架内置语言，不会自动为应用注册翻译。
+
+```ts
 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
+// 页面语言或服务进程的启动默认值；请求中使用 runWithLocale 单独选择语言。
+core.i18n.setGlobalLocale('zh-CN') // 返回 undefined；后续默认消息使用中文。
+core.i18n.getGlobalLocale() // 'zh-CN'。
+core.i18n.coreM('core_errorNotFound') // '资源不存在'。
+core.i18n.DEFAULT_LOCALE // zh-CN。
+core.i18n.DEFAULT_LOCALES // [{ code: 'zh-CN', label: '简体中文' }, { code: 'en-US', label: 'English' }, { code: 'ja-JP', label: '日本語' }]。
+```
+
+消息语言支持 `zh-CN`、`en-US`、`ja-JP`，简写 `zh` / `en` / `ja` 会规范化。消息优先使用显式 locale，其次为 Node 请求语言，最后为应用默认语言；不支持的语言回退 `zh-CN`，缺失键返回键本身。
 
-// 生成错误定义对象
-export const DbError = core.error.buildHaiErrorsDef('db', DbErrorInfo)
-// DbError.CONNECTION_FAILED → { code: 'hai:db:010', httpStatus: 500, system: 'hai', module: 'db' }
+```ts
+import { core } from '@h-ai/core'
 
-// 创建错误实例
-const errorInst = core.error.buildHaiErrorInst(
-  DbError.CONNECTION_FAILED,
-  'Unable to connect to PostgreSQL',
-  originalError, // cause（可选）
-  'Check connection string', // suggestion（可选）
-)
+// 业务字典按语言组织；占位参数在取消息时传入。
+const message = core.i18n.createMessageGetter({
+  'zh-CN': { welcome: '欢迎 {name}' },
+  'en-US': { welcome: 'Welcome {name}' },
+  'ja-JP': { welcome: 'ようこそ {name}' },
+})
+// createMessageGetter 返回消息函数；如 message('welcome', { locale: 'zh-CN', params: { name: 'Alice' } }) 得到 '欢迎 Alice'。
+const greeting = await core.i18n.runWithLocale('en-US', async () => {
+  await Promise.resolve()
+  return message('welcome', {
+    params: { name: 'Alice' }
+  })
+})
+// greeting：'Welcome Alice'；runWithLocale 返回回调的结果，此处等待 Promise 得到字符串。
+core.logger.info('Greeting prepared', { greeting })
 ```
 
-#### 配置错误码
+Node 请求/SSR 用 `runWithLocale()` 包裹实际异步处理；Serv 自动建立请求语言上下文，Kit 提供同名入口。在请求上下文内 `setGlobalLocale()` 只修改当前请求；上下文外仅用于启动默认值。浏览器使用应用级 `setGlobalLocale()` 或显式 locale；SSR 的 UI store 不应修改进程默认语言。
+
+### 字段校验提示：`core.zodValidation`
+
+把 Zod 校验错误转换为可显示在表单字段旁的 `{ field, message }[]`。`createPrefixedZodMessageGetter()` 按前缀选择翻译键，`mapZodErrorToFormErrors()` 完成提取、翻译和字段路径转换。
 
-```typescript
-import { HaiConfigError } from '@h-ai/core'
+```ts
+import { core } from '@h-ai/core'
+import { z } from 'zod'
 
-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 - 配置未加载
+// 此例复用 Core 已有翻译；业务表单可注入自己的消息获取器。
+const message = core.zodValidation.createPrefixedZodMessageGetter('core', key =>
+  key === 'core_validationEmail'
+    ? core.i18n.coreM('core_validationEmail', { locale: 'zh-CN' })
+    : core.i18n.coreM('core_errorValidation', { locale: 'zh-CN' }))
+// 返回消息函数；message('validationEmail') 得到 '请输入有效的邮箱地址'。
+const parsed = z.object({
+  email: z.email()
+}).safeParse({ email: 'invalid' })
+if (!parsed.success) {
+  const errors = core.zodValidation.mapZodErrorToFormErrors(parsed.error, message)
+  // errors：[{ field: 'email', message: '请输入有效的邮箱地址' }]。
+  core.logger.info('Validation failed', { errors })
+}
 ```
 
-### 请求语言隔离
+支持 Zod v3/v4 的 issues/errors 结构；默认英文消息会翻译，Schema 显式提供的业务消息保留。字段路径用点号，全局错误用 `_`。严格 Schema 的未知字段使用 validationUnexpectedFields，不公开内部字段名。
+
+### 模块启动与辅助工具：`core.module`
 
-Node 请求与 SSR 使用 `core.i18n.runWithLocale(locale, () => handleRequest())`；SvelteKit 可使用 `kit.i18n.runWithLocale(locale, () => resolve(event))`，serv 自动按请求头建立上下文。异步子任务继承请求语言，优先级为显式 `MessageOptions.locale`、请求语言、进程启动默认语言。`setGlobalLocale` 在请求上下文中只更新当前请求；上下文外仅用于启动默认值，不能在请求 hook 中调用它修改默认值。
+这些工具供应用启动代码和框架模块实现复用，既能管理多个模块，也能在模块尚未初始化时返回一致错误。它们不会替应用决定使用哪些模块。
 
-浏览器继续使用应用级 `setGlobalLocale` / `createLocaleStore`。SSR 的 UI store 初始化和 setter 只修改自身状态，不写全局语言；UI 消息从请求上下文读取。`runWithLocale` 仅支持 Node 入口，浏览器通过显式 locale 或应用状态翻译。
+#### 应用启动与关闭
 
-## 可信地址与请求访问策略（Node）
+应用使用多个模块时，通常需要先完成数据库等资源的初始化，处理业务后再释放资源。`core.module.createRuntime()` 接收这些模块的启动与关闭函数，返回一个供应用调用的对象；创建这个对象时还不会启动模块。
 
-`core.access` 为 HTTP 宿主提供共享的 IP、时间与路径检查，不自动安装 HTTP 拦截器。Serv 使用 `http.access`，SvelteKit 使用 `kit.createHandle({ access })`；IAM 的 `loginAccess` 只检查登录，不能替代每次请求检查。
+下面是本地开发示例，需额外安装 `@h-ai/reldb` 和 `@h-ai/cache`。数据库和缓存都使用内存配置，仅用于演示，生产环境应按模块要求配置共享后端。
 
 ```ts
+import { cache } from '@h-ai/cache'
 import { core } from '@h-ai/core'
+import { reldb } from '@h-ai/reldb'
+
+// 按需要的启动顺序，列出各模块的初始化和关闭函数。
+const runtime = core.module.createRuntime([
+  {
+    name: 'database',
+    start: () => reldb.init({ type: 'sqlite', database: ':memory:' }),
+    close: () => reldb.close(),
+  },
+  {
+    name: 'cache',
+    start: () => cache.init({ type: 'memory' }),
+    close: () => cache.close(),
+  },
+])
+
+// createRuntime 返回带 start()/close() 的对象；到这里数据库和缓存尚未启动。
+
+// 依次启动数据库、缓存；失败时自动清理已尝试启动的模块。
+const started = await runtime.start() // 成功为 { success: true, data: undefined }；两个模块均已初始化。
+if (!started.success)
+  throw new Error(started.error.message, { cause: started.error })
+
+try {
+  // 启动成功后再执行应用业务；这里演示记录启动结果。
+  core.logger.info('Application modules ready')
+}
+finally {
+  // 演示结束后先关闭缓存，再关闭数据库，并检查清理结果。
+  const closed = await runtime.close() // 成功为 { success: true, data: undefined }；两个模块均已关闭。
+  if (!closed.success)
+    core.logger.error('Application cleanup failed', { error: closed.error })
+}
+```
 
-const check = core.access.createRequestCheck({
-  rules: [{ id: 'external-api', paths: ['/api/v1/external/**'], allowIps: ['192.0.2.0/24'], encryption: 'disabled' }],
+本例的启动顺序是数据库 → 缓存，关闭顺序是缓存 → 数据库。示例在演示结束后立即清理；长期运行的服务应在退出时执行同样的 `runtime.close()`。
+
+某一步启动失败，会清理已经尝试启动的模块；某一步关闭失败，会先停在该处，保留它仍需使用的依赖，再次调用 `close()` 或 `start()` 时重试清理。多处同时调用 `start()` 不会重复初始化。可选的 `enabled()` 返回 false 时跳过该项。
+
+`start()` / `close()` 都返回 `HaiResult`，应用必须检查 `success`。错误包含模块名、失败阶段、错误码和必要的配置字段提示，避免把配置秘密和 SDK 原始异常作为启动错误公开。
+
+#### 模块尚未初始化时返回错误
+
+`createNotInitializedKit()` 返回 error/result/proxy 三种用法；proxy 为尚未准备好的同步或异步操作返回统一失败结果，模块就绪后应切换为真实操作。消息函数在调用时读取语言。
+
+```ts
+import type { HaiResult } from '@h-ai/core'
+import { core, HaiCommonError } from '@h-ai/core'
+
+const message = core.i18n.createMessageGetter({
+  'zh-CN': { notReady: '请先初始化模块' },
+  'en-US': { notReady: 'Initialize the module first' },
+  'ja-JP': { notReady: '先にモジュールを初期化してください' },
 })
-const decision = check('/api/v1/external/sync', 'POST', '192.0.2.10')
-const mode = check.encryption('/api/v1/external/sync', 'POST') // disabled
+// 本例固定使用中文消息，便于观察返回值。
+core.i18n.setGlobalLocale('zh-CN') // 返回 undefined。
+const waiting = core.module.createNotInitializedKit(HaiCommonError.NOT_INITIALIZED, () => message('notReady'))
+// waiting 是带 error/result/proxy 的对象。
+waiting.error() // { code: 'hai:common:001', httpStatus: 500, system: 'hai', module: 'common', message: '请先初始化模块' }。
+waiting.result<string>() // { success: false, error: 上方错误对象 }，无 data。
+
+// 模块实现可把尚未就绪的操作暂时指向这些代理。
+const asyncOperations = waiting.proxy<{ read: () => Promise<HaiResult<string>> }>()
+const syncOperations = waiting.proxy<{ read: () => HaiResult<string> }>('sync')
+// 两次 proxy 调用分别返回异步和同步操作对象。
+const result = await asyncOperations.read() // { success: false, error: 上方错误对象 }。
+if (!result.success)
+  core.logger.warn('Read before initialization', { error: result.error })
+syncOperations.read() // 直接返回 { success: false, error: 上方错误对象 }，不返回 Promise。
 ```
 
-`createRequestCheck` 在创建时验证并编译规则；`loadPolicy({ file: './config/security/request-access.yml' })` 只在启动时读取独立 YAML，最大 1 MiB，错误配置抛出异常并阻止宿主启动。全局条件与所有命中规则取交集，拒绝地址优先；默认空地址、时间列表不限制对应维度，时区为 UTC。路径是实际 URL pathname，包含部署前缀；支持精确路径和末尾 `/**`，GET 不隐含 HEAD。
+#### 判断是否需要共享状态
 
-可信地址通过 `core.access.createClientIpResolver()` 解析。默认 `auto` 在普通宿主忽略转发头，仅受管 Compose 的私有代理拓扑采用容器网段；`[]` 显式关闭代理信任，自管入口填入真实代理 IP/CIDR。不得把任意请求头当作可信 socket 地址。检查器不在请求中读文件、解析 CIDR 或扫描全部路径规则；同一时区的分钟结果复用，跨分钟仍重新判定。`core.access` 仅在 Node 入口存在，浏览器不提供伪实现。公开配置 Schema 由 `core-config` 入口转出，类型集中于 `core-types`，函数通过 `core-main` 注册的 `core.access` 调用。
+`requiresSharedState()` 判断生产进程是否应拒绝只在本机有效的业务状态后端。它只返回判断，不连接或切换数据库；实际环境由服务端传入。
 
-路径规则的 `encryption` 可选 `required` 或 `disabled`，省略时沿用宿主。选择器复用路径索引，不计算 IP/时间。重叠路径与方法若声明相反模式，创建检查器时失败，与声明顺序无关；同模式或不同方法可以组合。`check.requiresEncryption` 告知宿主是否必须装配传输加密，Core 本身不持有密钥或执行加解密。关闭应用层加密仍需 HTTPS、身份鉴别和访问检查。
+```ts
+import { core } from '@h-ai/core'
 
-完整默认值、代理条件、独立文件、部署和验证步骤见[请求访问控制手册](../../docs/usage/configuration/request-access.md)。
+// 此例用显式数据演示；服务端实际使用时传入 process.env。
+core.module.requiresSharedState({ NODE_ENV: 'production' }) // true：应使用跨主机共享后端。
+core.module.requiresSharedState({ NODE_ENV: 'production', HAI_E2E: '1' }) // false：显式 E2E 例外。
+```
 
-## 配置的实际消费边界
+### 请求访问检查：`core.access`（Node）
 
-`_core.yml` 仅接受 name/version/env/defaultLocale 元数据与 logging；未知字段加载失败。Core 不提供全局 debug、ID 长度/前缀、业务 features 或语言注册列表；日志级别用 logging.level，ID 选项在每次 core.id 调用传入，业务配置放 app.yml 并由应用 Schema 校验。defaultLocale 是可读取的元数据，不会替应用注册翻译或切换 Paraglide。导入 Logger 不改写 LANG、LC_ALL、PYTHONIOENCODING，包括 Windows TTY。全部模块的配置与环境消费链见[配置对应表](../../.agents/skills/hai-module-create/configuration.md)。
+HTTP 请求入口可用这些工具解析可信客户端 IP，再检查地址、路径、方法和允许时段。Core 只提供检查结果；Serv 的 http.access 或 Kit 的 createHandle({ access }) 负责把检查接到请求流程。
 
-## 请求关联与日志观察
+#### 解析与检查客户端地址
 
-采集器内部的持久化/上传路径可使用 `core.context.run({ suppressLogObservers: true }, operation)` 暂停观察回调，避免异步采集自身日志；stdout 等常规日志输出保持生效，退出作用域后恢复。
+```ts
+import { AccessConditionSchema, core } from '@h-ai/core'
 
-`core.logger.observe` 观察当前级别允许且已执行默认/自定义字段脱敏的记录，返回取消函数。订阅者应只做有界内存收集，再异步持久化；日志观察本身不代表已经保存。回调异常和同步重入不影响业务。自由文本与图像仍需采集侧的专门隐私策略。
+core.access.normalizeClientIp('::ffff:198.51.100.23') // 198.51.100.23。
+const resolve = core.access.createClientIpResolver(['192.0.2.10']) // 返回 IP 解析函数，只信任这个代理。
+const request = new Request('https://example.test/api/orders', {
+  headers: { 'x-forwarded-for': '198.51.100.23' }
+})
+// 第二参数必须来自真实 socket/可信平台；这里用测试地址模拟代理对端。
+const clientIp = resolve(request, '192.0.2.10') // '198.51.100.23'，读取受信代理的转发头。
+const check = core.access.createConditionCheck(AccessConditionSchema.parse({
+  allowIps: ['198.51.100.0/24']
+}))
+// createConditionCheck 返回检查函数；check(clientIp) 得到 { allowed: true }。
+core.logger.info('Address checked', { allowed: check(clientIp).allowed })
+```
 
-`core.context.run` 在 Node 中用 AsyncLocalStorage 隔离并发请求和子任务，现有模块 logger 自动附带当前 requestId/userId/scopeId/jobId。身份范围只来自可信服务端代码；关联 ID 不是授权。浏览器保持同一 API，但 run 只建立同步作用域，不能用于跨 await 的身份隔离。
+#### 读取策略并检查请求
 
 ```ts
-import type { LogRecord } from '@h-ai/core'
 import { core } from '@h-ai/core'
 
-const records: LogRecord[] = []
-const unsubscribe = core.logger.observe((record) => {
-  if (records.length === 100)
-    records.shift()
-  records.push(record)
-})
-await core.context.run({ requestId: 'request-1', scopeId: 'tenant-1', userId: 'user-1' }, async () => {
-  await Promise.resolve()
-  core.logger.warn('Business operation failed')
+// 可改为 loadPolicy({ file: './config/security/request-access.yml' }) 在启动时读独立文件。
+const policy = core.access.loadPolicy({
+  rules: [
+    {
+      id: 'external-api',
+      paths: ['/api/external/**'],
+      methods: ['POST'],
+      allowIps: ['192.0.2.0/24'],
+      encryption: 'disabled'
+    }
+  ],
 })
-unsubscribe()
+// policy.rules[0] 保留上方规则，并补 denyIps: []、windows: []、timezone: 'UTC'。
+const check = core.access.createRequestCheck(policy) // 返回请求检查函数，另带 encryption 方法和 requiresEncryption 属性。
+const decision = check('/api/external/sync', 'POST', '192.0.2.10') // { allowed: true }。
+check.encryption('/api/external/sync', 'POST') // disabled，供 HTTP 框架选择传输模式。
+check.requiresEncryption // false；本例没有 required 规则。
+core.logger.info('Request access checked', { allowed: decision.allowed })
 ```
 
-## 应用生命周期编排
+- 创建检查器时验证并编译规则；`loadPolicy({ file })` 启动时读取独立 YAML，最大 1 MiB，配置错误抛出并阻止宿主启动。内联规则与文件不能混用。
+- 全局条件与所有命中规则取交集，拒绝地址优先；空 IP/时间列表不限制对应维度，时区默认 UTC。路径包含部署前缀，支持精确路径和末尾 `/**`，GET 不隐含 HEAD。
+- `createClientIpResolver()` 默认 `auto` 在普通宿主忽略转发头，仅受管私有 Compose 采用容器网段。`[]` 关闭代理信任，自管入口明确填写代理 IP/CIDR；对端地址必须来自 socket 或可信平台。
+- 路径 `encryption` 可为 `required` / `disabled`，省略沿用宿主；重叠路径和方法的相反声明在创建时失败。`check.encryption()` / `requiresEncryption` 供宿主装配传输模式，Core 不持有密钥或执行加解密，仍需 HTTPS 和身份鉴别。
+
+完整默认值、独立文件、代理拓扑及部署步骤见[请求访问控制手册](../../docs/usage/configuration/request-access.md).
+
+### 生成与校验标识：`core.id`
 
-`core.module.createRuntime([{ name, enabled?, start, close }])` 按声明启动、反序关闭，合并并发调用。启动前登记部分资源的清理义务；失败回滚。关闭失败停在该模块并保留依赖，下次 close/start 重试，避免先关闭仍被使用的数据库。错误仅保留模块、阶段、错误码和配置字段路径；不转发配置值或 SDK 原始异常。base/API/fullstack 和管理台均使用此入口。
+生成业务标识与日志关联编号，或检查输入是否符合 UUID v4 / nanoid 格式。
 
-启动错误包含配置原因和处理建议：提供 `ext.fields` 时，`HaiConfigError.CONFIG_ENV_VAR_MISSING` 提示环境变量未设置，`CONFIG_VALIDATION_ERROR` 或 Schema 校验异常提示校验未通过；只有字段路径时提示“配置项缺失或无效”，不猜测具体原因。即使启动边界只打印 `error.message`，也能看到字段、处理建议和底层错误码。自定义初始化钩子可在缺少必需环境变量时抛出带 `code: HaiConfigError.CONFIG_ENV_VAR_MISSING.code` 和 `ext: { fields: ['变量名'] }` 的异常；fullstack 模板的初始管理员密码检查采用此方式。
+```ts
+import { core } from '@h-ai/core'
 
-## 错误提示与关联日志
+// 以下随机值仅展示格式，每次执行都不同。
+core.id.generate() // 如 'V1StGXR8_Z5jdHi6B-myT'，默认 21 字符；generate(8) 返回 8 字符。
+const shortId = core.id.short() // 如 'V1StGXR8_Z'，10 字符。
+core.id.withPrefix('order_') // 如 'order_V1StGXR8_Z5jdHi6B-myT'，前缀后接 21 字符。
+core.id.trace() // 如 'trace-V1StGXR8_Z5jdHi6B-myT'。
+core.id.request() // 如 'req-V1StGXR8_Z5jdHi6B-myT'。
+const uuid = core.id.uuid() // 如 '550e8400-e29b-41d4-a716-446655440000'，UUID v4。
+core.id.isValidUUID(uuid) // true。
+core.id.isValidNanoId(shortId, 10) // true。
+```
 
-HTTP 错误返回本地化安全文案及追踪编号；ToastContainer 默认隐藏编号，由排查信息图标展开和复制。响应同时包含 `error.traceId` 和 `X-Trace-Id`。框架复用本次 requestId 作为 traceId，前后端日志自动关联。底层异常、堆栈和操作上下文经凭据脱敏后写入日志，不通过 cause/ext 向用户公开。字段校验只返回本地化的字段名和错误。
+ID 不能作为密钥。UUID 只使用密码学安全随机源，不可用时抛错；_core.yml 没有全局 ID 长度或前缀配置，按每次调用传参。
 
-`core.error.toPublic(error, traceId?)` 用于接口/UI 边界；`core.error.formatMessage(error)` 用于重新翻译后的提示，重复调用不会重复追加标识。日志传入完整 Error 对象，不能只记录通用标题或提前 String(error) 丢失上下文。数据库失败记录驱动错误码、消息、堆栈及表/列；SQL 原文、绑定值和连接凭据不进入日志。
+### 判断值的类型：`core.typeUtils`
 
-### 公开业务进度
+对边界数据做类型判断，并帮助 TypeScript 在分支中缩小类型；这些判断不替代业务 Schema 校验。
 
-内部 ext 默认不公开。只有明确批准且经过 Schema 校验的业务进度才使用 publicExt，由边界转换为 ext；不能放入内部异常。
+```ts
+import { core } from '@h-ai/core'
+
+core.typeUtils.isDefined(null) // false，同时排除 null 和 undefined。
+core.typeUtils.isObject({ name: 'orders' }) // true；排除 null/数组，但也接受 Date 和类实例。
+core.typeUtils.isFunction(() => {}) // true。
+core.typeUtils.isPromise(Promise.resolve('ready')) // true。
+core.typeUtils.isString('orders') // true。
+core.typeUtils.isNumber(3000) // true；传 NaN 返回 false。
+core.typeUtils.isBoolean(false) // true。
+core.typeUtils.isArray([1, 2]) // true。
+```
+
+### 处理对象：`core.object`
+
+复制、合并或选取对象字段，也提供带键类型的 keys/values/entries 与 fromEntries。
+
+```ts
+import { core } from '@h-ai/core'
+
+const defaults = { name: 'orders', port: 3000 }
+const copy = core.object.deepClone(defaults) // { name: 'orders', port: 3000 }，新副本。
+// 合并局部覆盖时，显式保留包含 name/port 的完整配置类型。
+const settings = core.object.deepMerge<typeof defaults>(copy, { port: 4000 }) // { name: 'orders', port: 4000 }。
+core.object.pick(settings, ['name']) // { name: 'orders' }。
+core.object.omit(settings, ['port']) // { name: 'orders' }。
+core.object.keys(settings) // ['name', 'port']，元素类型为 'name' | 'port'。
+core.object.values(settings) // ['orders', 4000]。
+core.object.entries(settings) // [['name', 'orders'], ['port', 4000]]。
+core.object.fromEntries([
+  ['mode', 'local']
+]) // { mode: 'local' }。
+```
+
+deepClone 使用 structuredClone，支持 Date/Map/Set/循环等可克隆值；不可克隆的函数等会抛错。deepMerge 只递归普通对象，数组、Date、集合和类实例由后值覆盖，不修改输入；不把它当作实例克隆。
+
+### 处理字符串：`core.string`
+
+统一命名格式、处理显示文字、判断空白以及比较字符串。
+
+```ts
+import { core } from '@h-ai/core'
+
+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('abcdef', 3) // 'abc...'。
+core.string.trim(' hello ') // 'hello'。
+core.string.isBlank(' ') // true。
+core.string.isNotBlank('hello') // true。
+core.string.padStart('5', 3, '0') // '005'。
+core.string.padEnd('5', 3, '0') // '500'。
+core.string.constantTimeEqual('same', 'same') // true；安全边界见下方说明。
+```
+
+Node 的 constantTimeEqual 对等长 UTF-16 字节使用原生 timingSafeEqual，不同长度直接返回 false；浏览器不能提供引擎级恒时保证，不用于服务端凭据校验。
+
+### 处理数组：`core.array`
+
+按任务需要对数组去重、分块、分组、筛除空值或计算交集/差集；返回结果，保留输入数组。
+
+```ts
+import { core } from '@h-ai/core'
+
+core.array.unique([1, 1, 2]) // [1, 2]。
+core.array.chunk([1, 2, 3], 2) // [[1, 2], [3]]。
+core.array.groupBy([
+  { role: 'admin' },
+  { role: 'user' }
+], item => item.role)
+// => { admin: [{ role: 'admin' }], user: [{ role: 'user' }] }
+core.array.first([1, 2, 3]) // 1；空数组为 undefined。
+core.array.last([1, 2, 3]) // 3；空数组为 undefined。
+core.array.flatten([
+  [1],
+  [2, 3]
+]) // [1, 2, 3]，只展开一层。
+core.array.compact([0, null, 1, undefined]) // [0, 1]，保留 0/false/空字符串。
+core.array.shuffle([1, 2, 3]) // 如 [2, 3, 1]，次序随机；新数组不修改输入。
+core.array.intersection([1, 2], [2, 3]) // [2]。
+core.array.difference([1, 2], [2, 3]) // [1]。
+```
+
+groupBy 支持 `constructor`、`__proto__` 等原型同名键；chunk 的块大小应为正整数，size<=0 返回空数组。
+
+### 组织异步操作：`core.async`
+
+安排延迟、超时、失败重试、限并发与串行处理，或为输入/滚动等事件添加防抖与节流。
+
+```ts
+import { core } from '@h-ai/core'
+
+await core.async.delay(1) // 等待约 1ms 后得到 undefined；计时以运行环境为准。
+await core.async.withTimeout(Promise.resolve('ready'), 1000) // 'ready'；超时则 reject 为 Error。
+await core.async.retry(async () => 'ready', { maxRetries: 3, delay: 10 }) // 'ready'，本例首次即成功。
+await core.async.parallel([1, 2, 3], async value => value * 2, 2) // [2, 4, 6]，最多同时执行两项。
+await core.async.serial([1, 2, 3], async value => value * 2) // [2, 4, 6]，按输入顺序逐项执行。
+
+// 两种包装保留回调参数类型；调用 search/scroll 时传入同样类型的参数。
+const search = core.async.debounce((term: string) => core.logger.debug('Search requested', { term }), 100)
+const scroll = core.async.throttle((position: number) => core.logger.debug('Scroll position', { position }), 100)
+// debounce/throttle 均返回包装函数，调用时返回 undefined。
+core.logger.setLevel('debug') // 返回 undefined；确保下面的 debug 日志可见。
+search('orders') // 约 100ms 后回调收到 'orders'；100ms 内连续调用只处理最后一次。
+scroll(100) // 本例第一次调用立即回调，position 为 100；100ms 内最多执行一次。
+```
+
+withTimeout 只限制等待时间，不取消底层任务。retry 仅处理抛错/reject，失败 HaiResult 不会自动重试；当前 maxRetries 包含第一次尝试，例如 3 表示最多执行三次。parallel 的并发数须为大于 0 的安全整数，非法值使 Promise 以 RangeError 失败且不执行任务；结果顺序与输入一致。
+
+### 处理日期与时间：`core.time`
+
+在毫秒/秒时间戳、Date 和显示文本之间转换，并计算当地日期边界与相对时间。
+
+```ts
+import { core } from '@h-ai/core'
+
+// date 与以下日期运算使用本机时区；parseDate 中的 Z 表示 UTC。
+const date = new Date(2026, 0, 1, 12, 0, 0)
+core.time.formatDate(date, 'YYYY-MM-DD HH:mm:ss') // '2026-01-01 12:00:00'。
+core.i18n.setGlobalLocale('zh-CN') // 返回 undefined；相对时间使用中文。
+core.time.timeAgo(new Date(Date.now() - 60_000)) // '1 分钟前'（立即执行时）。
+core.time.now() // 当前毫秒时间戳，如 1767268800000；每次执行随时间变化。
+core.time.nowSeconds() // 当前秒时间戳，如 1767268800；相当于当前毫秒时间戳除以 1000 后向下取整。
+const parsed = core.time.parseDate('2026-01-01T00:00:00Z') // Date 对象，toISOString() 为 '2026-01-01T00:00:00.000Z'。
+core.time.isValidDate(parsed) // true；Invalid Date 返回 false。
+core.time.addDays(date, 7) // 新 Date，本机时间 2026-01-08 12:00:00。
+core.time.addHours(date, 2) // 新 Date，本机时间 2026-01-01 14:00:00。
+core.time.startOfDay(date) // 新 Date，本机时间 2026-01-01 00:00:00.000。
+core.time.endOfDay(date) // 新 Date，本机时间 2026-01-01 23:59:59.999。
+```
+
+formatDate 支持 YYYY/MM/DD/HH/mm/ss 占位符，默认 YYYY-MM-DD；日期运算返回新 Date。parseDate 不会因无效文本自动抛错，应使用 isValidDate 检查。
+
+更完整的参数与少见选项见[Core 使用参考](../cli/templates/skills/hai-core/reference.md)；公开契约以当前包声明为准。
+
+## 配置
+
+core.init 接收配置目录、配置 Schema 和日志选项，同步返回 void，没有 close。文件加载、环境来源合并和配置字段的具体示例见快速开始与 core.config；不能把 init 返回视为所有业务配置校验成功。
+
+[逐项配置说明、适用场景和示例](../../docs/usage/configuration/runtime.md).
+
+## 错误处理
+
+领域操作先判断 `result.success`，失败按本模块错误定义与安全提示处理，服务端保留错误码、关联编号和脱敏原因。同步工具、工厂、流迭代及生命周期按各自签名处理，不把 Promise 完成视为业务成功。具体失败与恢复边界见对应功能。
 
 ## 开发测试
 
+在仓库根目录执行（PowerShell 使用 `pnpm.cmd`）：
+
 ```bash
+pnpm --filter @h-ai/core typecheck
+pnpm --filter @h-ai/core lint
+pnpm --filter @h-ai/core build
 pnpm --filter @h-ai/core test
 ```
 
-公开声明和内部结构的注释及可编译示例见[模块 JSDoc 约定](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证)。Node core.init 同步返回 void；单项 config.load 返回失败时记录错误并继续，必需配置须 validate 并检查 success。目录扫描等异常仍可能抛出；模块业务 HaiResult 则先检查 success。
+公开声明与示例检查见[模块 JSDoc 约定](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证).
 
 ## 许可证