@h-ai/cli 1.0.0-beta.6 → 1.0.0-beta.8

package/templates/skills/hai-ai/resources.md

@@ -0,0 +1,69 @@
+# 配置与数据库资源清单
+
+AI 的可维护资源统一使用两份来源：初始化配置（通常来自 config/ai.yml）和 AIStoreProvider 数据库。按 ID 合并，同 ID 配置优先；配置条目只读，不复制到数据库。移除配置后，原来被遮蔽的数据库条目重新可见。数据库变更不会修改配置文件。
+
+| 清单入口 | 配置数组 | 使用方 |
+| --- | --- | --- |
+| `ai.llm.models` | `llm.models` | LLM、embedding、rerank、ACP 原生模型配置 |
+| `ai.audio.models` | `audio.models` | ASR/TTS |
+| `ai.image.models` | `image.models` | 图像生成 |
+| `ai.mcp.servers` | `mcp.servers` | ACP `mcpServerIds`，外部 MCP 连接资料 |
+| `ai.retrieval.sources` | `retrieval.sources` | 检索源及旧 addSource/removeSource/listSources 接口 |
+| `ai.acp.agents` | `acp.agents` | 智能体接入、初始化和会话 |
+| `ai.acp.workspaces` | `acp.workspaces` | 工程准备、会话目录及 Git 操作 |
+
+这些清单支持 `list/get/register/update/remove`。`list/get` 返回 `HaiResult`，条目为 `{ value, source, version? }`；`source` 是 config 或 database，数据库 `get` 带版本。`update` 接受完整定义，不是部分 patch。编辑前 get，再把 version 传给 update/remove，过期写入返回冲突。已有运行中的 ACP 会话保留原模型绑定；新会话读取最新清单，恢复会话会校验模型与智能体定义是否仍兼容。
+
+```ts
+import { ai } from '@h-ai/ai'
+
+// 已按应用生命周期成功初始化 reldb、vecdb 和 ai。
+async function changeModel() {
+  const current = await ai.llm.models.get('coding')
+  if (!current.success) return current
+  if (current.data.source === 'config') return current
+  return ai.llm.models.update({ ...current.data.value, temperature: 0.2 }, current.data.version)
+}
+```
+
+配置示例（模型名、地址与路径由部署提供）：
+
+```yaml
+llm:
+  models:
+    - id: coding
+      model: your-model
+      protocol: responses
+acp:
+  agents:
+    - id: coder
+      name: Codex
+      mode: embedded
+      adapter: codex
+      modelIds: [coding]
+  workspaces:
+    - id: project
+      storage:
+        type: directory
+        path: /srv/projects/project
+      repositories:
+        - id: api
+          url: https://git.example.com/team/api.git
+          mainBranch: trunk
+mcp:
+  servers:
+    - id: docs
+      name: Docs
+      transport: stdio
+      command: docs-mcp
+      environmentRefs:
+        API_TOKEN: DOCS_API_TOKEN
+```
+
+创建会话时传 `mcpServerIds: ['docs']`；配置和数据库 MCP 条目都可选择。环境变量在实际启动时解析，不将引用替换为密钥后保存到 MCP 定义。HTTP/SSE 的 headers 使用 `headerEnv`，stdio 的环境变量使用 `environmentRefs`。这份清单只维护外部服务器；`ai.mcp.registerTool/registerResource/registerPrompt` 仍是宿主进程的函数注册，不将可执行函数存进数据库。
+
+框架的异步模型调用每次读取最新清单；mem0 外部运行时在初始化时读取合并快照，其内置模型配置修改后需要重新初始化 AI。音频 `getCapabilities()` 保留原同步契约，使用本进程最近一次目录读写或异步音频调用刷新的快照；跨节点修改后先 await `ai.audio.models.get/list` 再同步查询能力。清单不是业务会话历史：session、聊天记录、persona 等继续使用各自已有的持久化 API，不从配置导入运行历史。
+
+配置项改写返回 `hai:ai:090`，缺失为 091，版本/重复冲突为 092，无效定义为 093，存储失败为 094。工作区路径重叠、仍被会话引用等使用 ACP 错误。数据库工作区更新/删除前需关闭并移除引用它的会话记录；移除记录不删除磁盘目录、worktree 或 volume。
+
+清单 API 是可信服务端管理接口，模型原始定义可能包含 apiKey。应用必须鉴权并自行选择可返回浏览器的字段，不直接透传整个 value。生产继续沿用 AI 模块已有共享数据库及向量库前置要求。

package/templates/skills/hai-api-client/reference.md

@@ -9,6 +9,8 @@
 
 ## 使用步骤
 
+`client.close()` 使旧刷新失效并等待已开始的凭据写入，但不清除宿主 TokenStorage。关闭完成后可复用同一存储重新 init；迟到刷新不能覆盖新身份。请求 timeout 覆盖响应头与完整 JSON 正文；自定义流按需读取，以调用方 signal 取消正文。内置 Cookie 适配器的登录和刷新包含跨域凭据，服务端须配置明确 Origin；内存/原生存储保留原请求凭据策略。
+
 ### 1. 初始化
 
 浏览器默认使用 httpOnly cookie 存储（推荐）：

package/templates/skills/hai-app-create/development.md

@@ -22,7 +22,7 @@ README 编辑先读章节，把功能说明与示例合并到对应章节；新
 
 ### 页面与布局
 
-新建工程统一采用适用的完整模块和示例，服务端包含 AI、向量库、反馈等依赖；客户端仍按类型隔离服务端模块。安装体积相应增加，示例需按实际业务替换。`--template`、`--features`、`--examples/--no-examples` 已删除，`create --yes/-y` 改为 `--defaults`，旧参数明确报错；`deploy --yes` 保持原义。已有工程的模块选择不受影响。
+每个模板只安装实际使用的模块：admin/h5 包含认证、验证码及找回密码通知，以及数据库、缓存、加密依赖；website 只包含 Core/Kit/UI；API 包含认证、通知、上传和反馈；fullstack 保留管理后台的认证、审计、存储、通知、调度和反馈；mobile-app 只使用客户端能力。AI、payment、vecdb、datapipe 不默认安装。所有项目保留完整模块 YAML 和 `.env.example`，未启用项以注释提供，只有已启用项进入公共环境默认值。后续添加对应依赖、取消所需配置注释，再接入初始化、关闭及业务路由；添加依赖不会自动启用功能。`--template`、`--features`、`--examples/--no-examples` 已删除，`create --yes/-y` 改为 `--defaults`，旧参数明确报错；`deploy --yes` 保持原义。已有工程不会自动裁剪依赖。
 
 website默认SSR；静态发布须先移除服务端业务依赖、初始化及API/actions。静态构建与实际路径验证按[hai-build](../hai-build/SKILL.md)。
 

package/templates/skills/hai-app-create/reference.md

@@ -315,7 +315,7 @@ interface CreateArticleInput {
 
 ## 初始化顺序
 
-CLI 项目统一忽略 `**/data/`，含根目录、workspace 子目录及 `.gitkeep`；数据库/上传文件不入 Git。Fullstack 的服务端 config 始终保留 core、serv、db、cache、iam、storage、audit、reach、ai、vecdb、payment、scheduler、feedback 共 13 份 YAML；构建部署配置统一位于项目根 hai.json，未启用模块整份注释，可选字段及替代 Provider 按块注释，`.env.example` 也保留未启用模块的注释凭据。
+CLI 项目统一忽略 `**/data/`，含根目录、workspace 子目录及 `.gitkeep`；数据库/上传文件不入 Git。每个模板只安装实际使用的模块，同时在应用 config 保留 core、serv、kit、db、cache、iam、storage、audit、reach、ai、vecdb、payment、scheduler、feedback 共 14 份 YAML；纯客户端的服务端配置仅作参考。构建部署配置统一位于项目根 hai.json，未启用模块整份注释，可选字段及替代 Provider 按块注释，`.env.example` 保留全部模块变量，未启用项不进入公共环境默认值。新增功能时添加对应依赖、启用所需配置，并接入初始化、反序关闭和业务路由；添加依赖不会自动接入模块。LDAP 只有在 login.ldap 为 true 时才参与部署扫描。
 
 H5 所有页面继承根布局的 header/footer；认证页隐藏底部导航，业务页面使用 `@h-ai/ui` 的 `BottomNav` 与移动端壳样式，导航启用 centered/maxWidth/safeArea，与页面同宽。
 

package/templates/skills/hai-build/SKILL.md

@@ -27,7 +27,7 @@ description: "构建或排查 hai 应用的源码、静态网站、容器镜像
 
 ## 构建与部署
 
-- 新建website包含完整模块与示例，默认Node SSR；静态发布须先移除服务端业务依赖、初始化及API/actions，保留Core/Kit/UI。compile静态预渲染使用`HAI_BUILD_STATIC=1 PUBLIC_BASE_PATH=/docs-site`，docs-site替换为实际仓库名，各路径段仅ASCII字母、数字、_、.、-，无末尾/；省略/0保持SSR，根站路径留空。HAI_BUILD_STATIC仅用于compile，PUBLIC_BASE_PATH也支持image网站构建。静态拒绝服务端业务模块、自定义API/actions与未预渲染页面，不放宽生产守卫、不用SPA fallback；默认健康端点不发布。构建不读根.env，static为公开目录，拒绝.env/.env.*与符号链接。上传build使用include-hidden-files:true保留.nojekyll，验首页/深链/刷新/资产与敏感哨兵。
+- 新建website只安装Core/Kit/UI，默认Node SSR，可直接切换静态发布；注释配置与环境变量参考不启用模块。后续增加的服务端业务依赖、初始化及API/actions须先移除。compile静态预渲染使用`HAI_BUILD_STATIC=1 PUBLIC_BASE_PATH=/docs-site`，docs-site替换为实际仓库名，各路径段仅ASCII字母、数字、_、.、-，无末尾/；省略/0保持SSR，根站路径留空。HAI_BUILD_STATIC仅用于compile，PUBLIC_BASE_PATH也支持image网站构建。静态拒绝服务端业务模块、自定义API/actions与未预渲染页面，不放宽生产守卫、不用SPA fallback；默认健康端点不发布。构建不读根.env，static为公开目录，拒绝.env/.env.*与符号链接。上传build使用include-hidden-files:true保留.nojekyll，验首页/深链/刷新/资产与敏感哨兵。
 
 - 创建默认包含开发期部署工具，可用 --no-deploy 关闭。每个镜像使用 images/ 中独立 Dockerfile，Web 配置位于 images/web/，不使用镜像阶段 target 配置。
 - 构建器生成 images/dependencies/ 安装输入；fetch、安装和生产依赖整理共用 pnpm store，安装与生产依赖整理共用 SQLite 驱动缓存，并复用依赖层；依赖安装在源码COPY前，前后端仅复制各自需要的源码。运行镜像去掉应用自身声明、source map和README。file: 归档、补丁、workspace 元数据必须进入下载上下文；原生依赖缓存按系统/架构/ABI 区分。基础镜像、中间件及工具指定版本，禁止 latest。

package/templates/skills/hai-build/reference.md

@@ -60,7 +60,7 @@ Dockerfile 在 FROM 前声明 HAI_NODE_IMAGE / 适用的 HAI_NGINX_IMAGE，构
 
 ### SvelteKit Adapter 模式
 
-CLI website模板默认Node SSR。新建工程包含完整模块和示例，静态发布须先移除服务端业务依赖、初始化和API/actions；在compile时使用`HAI_BUILD_STATIC=1`与可选`PUBLIC_BASE_PATH`切换完整静态预渲染，边界见本skill的静态网站说明；该模板没有使用下方VITE_ADAPTER工厂。静态产物用preview本机检查，上传build到Pages/CDN；生成的start/Docker配置属于普通SSR模式，不能用于运行静态HTML。切回SSR只需清除静态开关并重建，PUBLIC_BASE_PATH仍可按实际网站目录用于SSR或Docker；SvelteKit/Vite差异、制品格式和健康检查见[网站挂载目录](paths.md)。
+CLI website模板默认Node SSR，只安装Core/Kit/UI；注释配置和环境变量参考不启用模块。后续增加的服务端业务依赖、初始化和API/actions须在静态发布前移除；在compile时使用`HAI_BUILD_STATIC=1`与可选`PUBLIC_BASE_PATH`切换完整静态预渲染，边界见本skill的静态网站说明；该模板没有使用下方VITE_ADAPTER工厂。静态产物用preview本机检查，上传build到Pages/CDN；生成的start/Docker配置属于普通SSR模式，不能用于运行静态HTML。切回SSR只需清除静态开关并重建，PUBLIC_BASE_PATH仍可按实际网站目录用于SSR或Docker；SvelteKit/Vite差异、制品格式和健康检查见[网站挂载目录](paths.md)。
 
 仅在项目实际使用 SvelteKit 和 `@h-ai/kit/adapter` 时使用；Vite SPA 不配置 SvelteKit adapter，fullstack 各前端按自身 scripts 构建。
 

package/templates/skills/hai-cache/reference.md

@@ -38,9 +38,13 @@ type: memory # memory | redis
 ### 2. 初始化与关闭
 
 ```typescript
-import { cache } from '@h-ai/cache'
+import { core } from '@h-ai/core'
+import { cache, CacheConfigSchema } from '@h-ai/cache'
 
-await cache.init(core.config.get('cache'))
+const config = core.config.validate('cache', CacheConfigSchema)
+if (!config.success) throw new Error(config.error.message)
+const initialized = await cache.init(config.data)
+if (!initialized.success) throw new Error(initialized.error.message)
 // 使用后关闭
 const closed = await cache.close()
 if (!closed.success) throw new Error(closed.error.message)

package/templates/skills/hai-ci/SKILL.md

@@ -61,6 +61,8 @@ lint/typecheck 只能执行已配置的规则。新增开发规范时区分可
 - 若 E2E 稳定且耗时可控，可作为 required check。
 - 若 E2E 依赖浏览器、服务、密钥或容易 flaky，先放到 `workflow_dispatch` / `schedule` / 独立 job。
 - 应用级 E2E 使用：`pnpm --filter <app> test:e2e`。
+- 依赖镜像或环境开关的关键 E2E，在 CI 中必须明确准备前置并启用；准备失败应阻断，不能让缺少配置导致的 skip 冒充验收。使用 Turbo 严格环境时，将影响测试执行范围的变量放入 `env`，同时传递变量并参与缓存身份，避免命中跳过用例时的缓存。
+- 真实付费服务验收限用户已授权的可信分支和事件。可复用 workflow 的 secret 仅在调用方按事件显式传入，并只向定向验收步骤注入；安装、构建和普通根测试剥离该凭据。PR 继续使用夹具。成功和失败均可保留脱敏 JSON/HTML/截图证据，不能将密钥或认证头写入制品。
 
 ### hai-framework 依赖策略
 

package/templates/skills/hai-core/SKILL.md

@@ -21,7 +21,7 @@ description: "配置 hai 应用启动、YAML/环境变量、日志、i18n 与 Ha
 - 自动加载和监听配置目录内所有 YAML；项目根 `hai.json` 的 `build` / `deploy` 由 CLI 读取，不进入运行时配置。单项 load 返回失败时记日志并继续，必需配置须 validate 并检查 success；目录扫描、日志设置等异常仍可能传播。
 - 应用名称、版本、环境、默认语言和日志设置统一从 `_core.yml` 经 core.config 获取，日志使用 core.logger；UI 不另维护硬编码副本。SvelteKit layout / fullstack app.info 仅下发公开字段白名单；独立 Vite mobile-app 在 Node 构建时解析并注入公开默认值，修改这些编译默认值需要重新构建。静态 Web 的公开 API 地址等通过 `runtime-config.js` 覆盖时无需重建镜像，原生包在复制静态资源前准备配置入口。浏览器不加载 YAML，不接收完整模块配置、密钥或日志脱敏上下文。
 - `HAI_<配置名>_<路径>` 支持父 JSON 基础与细项覆盖，同源先父后子，高来源整段替换清除低来源细项。camelCase 不拆词，约定变量优先于显式插值；宿主显式提供 `configSchemas` 识别 YAML 缺少的可选路径，模块执行业务校验。
-- 环境文件采用六类：`.env.example` 完整列出字段用途、默认值、枚举和范围；`.env` 为公共基础；`.env.dev`、`.env.test`、`.env.prod` 为公共环境覆盖，这五类均提交 Git。`.env.local` 为本机私有配置，不提交 Git。优先级为进程环境 > `.env.local` > 环境文件 > `.env`；Vite 在 Node 配置阶段调用 `core.config.loadEnvFiles({ mode, envDir })` 并检查 success 后注入进程，Node 脚本按相同顺序传入 `--env-file`。`core.init` 不自行读取 dotenv。
+- 环境文件约定：`.env.example` 完整列出字段用途、默认值、枚举和范围；`.env` 为公共基础；`.env.dev`、`.env.test`、`.env.prod` 为公共环境覆盖，公共文件提交 Git。`.env.local` 为共享私有配置，`.env.<mode>.local` 为模式私有配置，均不提交 Git。优先级为进程环境 > `.env.<mode>.local` > `.env.local` > `.env.<mode>` > `.env` > YAML；Vite 在 Node 配置阶段调用 `core.config.loadEnvFiles({ mode, envDir })` 并检查 success 后注入进程，Node 入口复用 `run-node.mjs` 的结构合并，避免原生多 `--env-file` 遗留低来源细项。`core.init` 不自行读取 dotenv。
 - 配置 getter 与 ID/logger 方法不是 HaiResult；validate/load 等须检查 success。
 - 日志可用 `{ error }` 记录原生 Error；两端先规范化诊断再字段/URL 脱敏，配置 redact 路径仍生效。默认包含 passwordHash、passwd、secretKey 等实际凭据字段；异常文本清理显式凭据标签和 URL，不保证识别无标签秘密。原异常不变，错误子图循环/深度用固定标记；业务隐私仍由调用方清理或遮蔽整条路径。
 - 初始化前创建的默认、模块与嵌套 child Logger 在后续输出中应用当前全局 logging；configure/setLevel 也作用于已有实例。create 的显式 level/format/context 优先，未指定项动态继承。浏览器 json/pretty 与附加 redact 路径实际生效，消息文本仍由调用方脱敏。

package/templates/skills/hai-crypto/reference.md

@@ -9,6 +9,8 @@
 
 ## 运行环境
 
+传输客户端 `destroy()` 会取消并废弃在途握手；旧握手成功或失败都不能恢复状态或影响下一代握手。单请求取消仍只停止该请求的等待。
+
 **Node.js + 浏览器双端可用。** 浏览器端通过 `crypto.init()` 初始化（无需配置参数）。
 
 | 能力 | Node.js | 浏览器 | 说明 |

package/templates/skills/hai-payment/reference.md

@@ -244,30 +244,52 @@ import { apiContract } from '@h-ai/api-contract'
 
 ### 服务端路由（SvelteKit）
 
+应用实现 `readOrder`：从共享数据库读取订单，返回持久化的金额、币种、所有者与支付状态。通知地址取服务端配置；在宿主权限配置中登记并授予 `payment:create`。以下工厂在路由模块中注入这两个可信依赖，`kit.handler` 仅提供错误边界，认证和资源授权仍在示例中显式执行。
+
 ```typescript
+import type { HaiResult } from '@h-ai/core'
 import { kit } from '@h-ai/kit'
-// src/routes/api/v1/payment/create/+server.ts
 import { payment } from '@h-ai/payment'
+import { z } from 'zod'
+
+interface PayableOrder {
+  orderNo: string
+  ownerId: string
+  amount: number
+  currency: string
+  description: string
+  status: 'pending' | 'paid' | 'closed'
+}
 
-export const POST = kit.handler(async ({ request, locals }) => {
-  const body = await request.json()
-  const result = await payment.createOrder(body.provider, {
-    orderNo: body.orderNo,
-    amount: body.amount,
-    description: body.description,
-    tradeType: body.tradeType,
-    userId: body.userId,
-    notifyUrl: body.notifyUrl,
+export function createPaymentHandler(
+  readOrder: (id: string) => Promise<HaiResult<PayableOrder | null>>,
+  notifyUrl: string,
+) {
+  return kit.handler(async ({ request, locals }) => {
+    const session = locals.session
+    if (!session) return kit.response.unauthorized()
+    kit.guard.require(session, 'payment:create')
+    const input = await kit.validate.body(request, z.object({ orderId: z.string().min(1) }).strict())
+    const order = await readOrder(input.orderId)
+    if (!order.success) return kit.response.fromError(order.error)
+    if (!order.data || order.data.ownerId !== session.userId || order.data.status !== 'pending')
+      return kit.response.forbidden()
+    const result = await payment.createOrder('stripe', {
+      orderNo: order.data.orderNo,
+      amount: order.data.amount,
+      currency: order.data.currency,
+      description: order.data.description,
+      tradeType: 'h5',
+      notifyUrl,
+    })
+    if (!result.success) return kit.response.fromError(result.error, locals.requestId)
+    return kit.response.ok(result.data, locals.requestId)
   })
-
-  if (!result.success) {
-    return kit.response.internalError(result.error.message)
-  }
-
-  return kit.response.ok(result.data, locals.requestId)
-})
+}
 ```
 
+在 `+server.ts` 中将可信业务读取函数和通知地址传给工厂，再导出返回值为 `POST`。
+
 ### 完整支付流程
 
 ```

package/templates/skills/hai-reach/reference.md

@@ -6,6 +6,8 @@
 
 ## 运行环境
 
+Provider 名称必须唯一，重名在连接前返回 CONFIG_ERROR。close 等待在途初始化并释放其 Provider，返回后不再迟到发布模块或定时器。
+
 > ⚠️ **服务端模块（Node.js only）。** 浏览器端不直接发送邮件/短信，而是通过 API 端点触发服务端 `reach.send()`。
 
 ## 依赖
@@ -76,21 +78,27 @@ API Provider 只接受 HTTP(S) URL。回调地址若来自不可信输入，业
 ### 2. 初始化与关闭
 
 ```typescript
-import { cache } from '@h-ai/cache'
+import { cache, CacheConfigSchema } from '@h-ai/cache'
 import { core } from '@h-ai/core'
-import { reach } from '@h-ai/reach'
-import { reldb } from '@h-ai/reldb'
+import { reach, ReachConfigSchema } from '@h-ai/reach'
+import { reldb, ReldbConfigSchema } from '@h-ai/reldb'
 
 // 当前配置启用了 delay：数据库和队列表为必需依赖。
-const database = await reldb.init(core.config.get('db'))
+const databaseConfig = core.config.validate('db', ReldbConfigSchema)
+if (!databaseConfig.success) throw new Error(databaseConfig.error.message)
+const database = await reldb.init(databaseConfig.data)
 if (!database.success)
   throw new Error(database.error.message)
-const cached = await cache.init(core.config.get('cache')) // 可选，启用 flush 分布式锁
+const cacheConfig = core.config.validate('cache', CacheConfigSchema)
+if (!cacheConfig.success) throw new Error(cacheConfig.error.message)
+const cached = await cache.init(cacheConfig.data) // 可选，启用 flush 分布式锁
 if (!cached.success)
   throw new Error(cached.error.message)
 
 // 再初始化触达模块（自动检测已初始化的 reldb/cache 单例）
-const initialized = await reach.init(core.config.get('reach'))
+const reachConfig = core.config.validate('reach', ReachConfigSchema)
+if (!reachConfig.success) throw new Error(reachConfig.error.message)
+const initialized = await reach.init(reachConfig.data)
 if (!initialized.success)
   throw new Error(initialized.error.message)
 // ... 使用触达服务
@@ -234,7 +242,7 @@ interface ReachConfigInput {
 
 验证码和密码重置等有时效的通知应明确选择 DND 策略；可靠入队成功不代表用户已收到验证码。
 
-队列 `created_at` / `updated_at` / `locked_until` / `next_attempt_at` 均为 Unix 毫秒 `BIGINT`（SQLite 为 64 位 INTEGER）；仓库把 driver 的字符串/数字归一化为安全整数 number，并拒绝负数、小数和不安全整数。模板仓库的 TIMESTAMP 时间返回 Date。已有表须在部署时同步列结构，包含次数、退避策略和失败分类，模块不自动迁移旧表；跨库验收必须运行 PostgreSQL/MySQL 用例，SQLite 无法证明 32 位溢出已经消除。
+队列 `created_at` / `updated_at` / `locked_until` / `next_attempt_at` 均为 Unix 毫秒 `BIGINT`（SQLite 为 64 位 INTEGER）；仓库把 driver 的字符串/数字归一化为安全整数 number，并拒绝负数、小数和不安全整数。模板仓库的 TIMESTAMP 时间返回 Date。初始化自动执行版本化迁移，包含次数、退避策略和失败分类；升级前先 dry-run、备份并停止旧写入。旧通知载荷退役会清空正文/变量并将旧待发项标记 discarded，回退镜像不能恢复这些数据；跨库验收必须运行 PostgreSQL/MySQL 用例，SQLite 无法证明 32 位溢出已经消除。
 
 ### 租约、接收端幂等与未知结果
 

package/templates/skills/hai-reldb/reference.md

@@ -62,9 +62,12 @@ PostgreSQL 空闲连接错误已监听，由池移除并在下一次查询替换
 
 ```typescript
 import { core } from '@h-ai/core'
-import { reldb } from '@h-ai/reldb'
+import { reldb, ReldbConfigSchema } from '@h-ai/reldb'
 
-await reldb.init(core.config.get('db'))
+const config = core.config.validate('db', ReldbConfigSchema)
+if (!config.success) throw new Error(config.error.message)
+const initialized = await reldb.init(config.data)
+if (!initialized.success) throw new Error(initialized.error.message)
 // ... 使用数据库
 const closed = await reldb.close()
 if (!closed.success) throw new Error(closed.error.message)

package/templates/skills/hai-scheduler/reference.md

@@ -175,7 +175,7 @@ await scheduler.init({
 
 可信服务端用 `execution.listLogFailures({ limit, offset })` 监控 pending（范围与 listUnknown 相同），用 `execution.repairLog(occurrenceId)` 从共享 journal 幂等补写；可跨节点、重启及并发调用。写入已提交但回执丢失时通过固定主键和完整内容核对去重。补写返回 `LOG_PERSIST_FAILED`（032）时继续保留 pending，并输出安全告警；全部数据库不可用且终态未提交时仍按 unknown 核对外部效果，不能假定存在可恢复结果。补写与日志保留均不调用业务 Hook。保留策略失败仅告警，不撤销已保存日志。`onTaskFinish` 是本地业务完成通知，其 unconfirmed 状态不是持久化确认；以 trigger 返回值及 execution.get 的 logPersistence 为准。
 
-领取前竞争/跳过的 interrupted 仅为观测日志，没有可补写的终态；其写入未确认时返回 unconfirmed。JSON 大载荷保存完整结果和全部重试记录，避免 MySQL 的 255 字符截断；新 schema 不自动迁移旧日志/执行表。关闭会等待在途补写，先关闭 scheduler 再关闭数据库。
+领取前竞争/跳过的 interrupted 仅为观测日志，没有可补写的终态；其写入未确认时返回 unconfirmed。JSON 大载荷保存完整结果和全部重试记录，避免 MySQL 的 255 字符截断；初始化会自动执行版本化迁移，归档并复制旧日志；升级前先 dry-run、备份并停止旧写入，按模块 README 核对迁移影响。关闭会等待在途补写，先关闭 scheduler 再关闭数据库。
 
 ```ts
 const result = await scheduler.trigger('cleanup', { idempotencyKey: 'cleanup-2026-10-23' })

package/templates/skills/hai-storage/reference.md

@@ -4,6 +4,8 @@
 
 ## 运行环境
 
+Local 的 key 路径拒绝文件符号链接和目录 junction，`.meta.json` / `.upload.tmp` 保留后缀不区分大小写。覆盖 put 清除旧元数据，copy 默认继承源元数据。浏览器根入口仅导出 Schema、类型和客户端辅助能力。
+
 > ⚠️ **服务端模块**。`storage.file` / `storage.dir` / `storage.presign` 均在 Node.js 端使用。浏览器端通过预签名 URL 或 API 端点间接访问存储（见下方「浏览器端文件上传」）。
 
 ## 适用场景
@@ -53,9 +55,13 @@ MinIO、RustFS 使用同一个 S3 Provider：配置 `type: s3`、S3 API `endpoin
 ### 2. 初始化与关闭
 
 ```typescript
-import { storage } from '@h-ai/storage'
+import { core } from '@h-ai/core'
+import { storage, StorageConfigSchema } from '@h-ai/storage'
 
-await storage.init(core.config.get('storage'))
+const config = core.config.validate('storage', StorageConfigSchema)
+if (!config.success) throw new Error(config.error.message)
+const initialized = await storage.init(config.data)
+if (!initialized.success) throw new Error(initialized.error.message)
 // 使用后关闭
 const closeResult = await storage.close()
 if (!closeResult.success) {

package/templates/skills/hai-vecdb/reference.md

@@ -6,6 +6,8 @@
 
 ## 运行环境
 
+pgvector 将集合 metric 持久保存在 vector 列注释，索引、info、search 使用同一值；重连后修改默认 metric 不改变已有集合。旧集合从实际索引恢复；缺少索引与有效注释时先恢复定义，不按当前默认值猜测。
+
 > ⚠️ **服务端模块（Node.js only）。** 浏览器端不直接操作向量数据库，通过 `@h-ai/ai` 的 API 端点间接使用（如 RAG 检索、知识库查询）。
 
 ## 适用场景
@@ -62,9 +64,12 @@ operationLog:
 
 ```typescript
 import { core } from '@h-ai/core'
-import { vecdb } from '@h-ai/vecdb'
+import { vecdb, VecdbConfigSchema } from '@h-ai/vecdb'
 
-await vecdb.init(core.config.get('vecdb'))
+const config = core.config.validate('vecdb', VecdbConfigSchema)
+if (!config.success) throw new Error(config.error.message)
+const initialized = await vecdb.init(config.data)
+if (!initialized.success) throw new Error(initialized.error.message)
 // ... 使用向量数据库
 const closeResult = await vecdb.close()
 if (!closeResult.success) {