@h-ai/cli 1.0.0-beta.18 → 1.0.0-beta.19

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

@@ -1,5 +1,7 @@
 # hai-core — 详细用法
 
+HTTP/UI 边界只对明确的有效 4xx 状态公开业务提示；错误缺少 `httpStatus` 或状态非法时按 500 返回安全提示。手写业务错误须提供完整错误定义或显式状态，不能依赖缺省状态展示原文。
+
 从 [SKILL.md](SKILL.md) 选择主题后读取对应小节。代码片段展示 API 用法；省略的业务变量、schema、依赖与 return 上下文需由应用补齐。
 
 > `@h-ai/core` 是 hai-framework 的基础模块，提供配置管理、结构化日志、国际化、HaiResult 错误模型、Zod 校验错误本地化与模块生命周期工具。所有其他模块均依赖 core。
@@ -448,6 +450,7 @@ Core 模块定义了两组标准错误码：
 | `HaiCommonError.VALIDATION_ERROR` | `hai:common:200` | 校验失败 |
 | `HaiCommonError.INVALID_REQUEST` | `hai:common:201` | 请求无效 |
 | `HaiCommonError.PARAMETER_MISSING` | `hai:common:202` | 参数缺失 |
+| `HaiCommonError.RATE_LIMIT_EXCEEDED` | `hai:common:203` | 请求频率超限（HTTP 429） |
 | `HaiCommonError.NOT_FOUND` | `hai:common:300` | 资源不存在 |
 | `HaiCommonError.ALREADY_EXISTS` | `hai:common:301` | 资源已存在 |
 | `HaiCommonError.CONFLICT` | `hai:common:302` | 冲突 |

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

@@ -33,6 +33,8 @@
 
 ## 使用步骤
 
+并发调用 `close()` 会使尚未完成的 `init()` 失效，迟到初始化不会重新打开模块；等待该次初始化返回后可再次初始化。
+
 ### 1. 初始化与关闭
 
 ```typescript

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

@@ -47,12 +47,18 @@ description: "构建并发布或交付已有镜像：完整离线包、按服务
 
 所有容器模板共用deploy.provider.expose.https，省略时HTTP。files指定domain、certificateFile、privateKeyFile（相对工程根），校验域名/期限/密钥并复制到私有包。letsencrypt指定domain、email、acceptTerms:true，HTTP hostPort必须80，公网DNS、80入站及CA出站须可达。固定版本官方Certbot申请并每12小时检查续期，Nginx自动重载。仅单域名HTTP-01，无DNS/通配符。HTTPS默认443、redirectHttp默认true；--yes复用配置。启停或改模式/域名/端口/本地证书需全量。状态在服务器https/acme及按域名隔离的https/certificates目录，需备份；续期失败保留旧证书并须及时处理，隔离目标用已有证书。打包/plan不申请证书。
 
+files 只接收末级无软链接或硬链接的普通 PEM 文件，每份最多 1 MiB，父目录仍须可信。Certbot `live/` 软链需安全复制为受控目录中的普通文件，或使用框架 `letsencrypt` 模式。
+
 默认.tar.gz，显式--output release.tar为未压缩，README仅外层。镜像从解包目录导入，release只留配置/恢复状态；成功后清理本次incoming，失败保留诊断。中间件归档按镜像内容ID缓存且复用前验摘要。
 
-Serv 生产登录的刷新 Cookie 默认带 `Secure`。受控内网或 VPN 的 HTTP 部署可在所选 `.env.prod.local` 配置 `HAI_SERV_REFRESH_COOKIE_SECURE=false` 和实际 `HAI_SERV_CORS_ORIGIN`，再重新部署后端。详见 [Serv Cookie 配置](../hai-serv/reference.md#cookie-规格)。
+Serv 生产登录的刷新 Cookie 默认带 `Secure`。受控内网或 VPN 的 HTTP 部署可在所选 `.env.prod.local` 配置 `HAI_SERV_REFRESH_COOKIE_SECURE=false` 和实际 `HAI_SERV_CORS_ORIGIN`，再重新部署后端。仅在工程使用 Serv 且已交付 `hai-serv` 时读取该技能 `reference.md` 的“Cookie 规格”；Kit 应用按自己的 `hai-kit` 认证契约处理，不加载未交付的 Serv 技能。
 
 ## 后端运行配置重载
 
+SvelteKit SSR 的 HTTP/HTTPS 部署均通过独立 `gateway`，SSR 容器不映射公开端口。网关覆盖 Host 与标准转发头；Compose 固定 adapter-node 的协议/主机/客户端地址信任，业务 `.env.runtime` 不能覆盖。adapter-node 6 不再读取运行期 `ORIGIN`，旧直接公开 SSR 的部署必须重新生成全量交付包；源应用默认不固定 `paths.origin`，保持镜像跨环境复用。
+
+外层 TLS 终止时，独立 gateway 只接受 `trustedEdgeProxies` 白名单真实对端的单值 `http` / `https` 协议；外层必须覆盖 Host/XFF/协议头。未授权来源或组合值使用 gateway 自身协议，不直接透传外部 Forwarded、主机/端口转发值。
+
 交付 README 仅列初始账号变量名及所选环境文件或 `process.env` 来源，不打印密码。Fullstack 初始密码在创建工程时生成，部署带入已有值；已有账号不因环境变量变更重置密码或恢复旧职责，自定义应用以实际引导逻辑为准。
 
 独立读取的核心环境、职责账号初始密码和传输密钥环保留进程语义，不能仅按前缀判定已失效；Node 启动参数及私有代理标记由部署装配提供，不在运行文件重复保留无效项。

package/templates/skills/hai-deploy/middleware.md

@@ -94,6 +94,8 @@ AI 使用 MySQL 的首次建表需 CREATE 与 INDEX 权限，节点可并发初
 
 以下是自定义向导的连接字段；完整可用项、枚举与范围仍以项目 `.env.example` 和公开 Schema 为准。变量前缀为 `HAI_DB`、`HAI_CACHE`、`HAI_STORAGE`、`HAI_VECDB`、`HAI_IAM_LDAP`；Reach 使用实际索引 `HAI_REACH_PROVIDERS_<index>`。camelCase 不拆词，例如 `bindPassword` → `BINDPASSWORD`。
 
+HTTP API 的全部自定义请求头整体写入私有环境文件，不能按头名猜测秘密。迁移已有 dotenv 项会处理行首空格/Tab、export 与多行引号，并移除同模式公共文件中的旧值；操作后仍核对私有文件与忽略规则，不在日志中输出值。
+
 | 后端               | 连接字段                                                                                                                             |
 | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
 | SQLite             | database（文件路径或 `:memory:`）                                                                                                    |
@@ -128,7 +130,7 @@ manifest.json 的 partial 与 selectedServices、apply 脚本共同记录部署
 
 生成 web.conf 时从目标环境解析后的 _serv.yml 读取 transport.maxPlaintextBytes，调用 crypto.resolveTransportBodyLimits 推导 client_max_body_size；默认 2129920 字节，8 MiB 明文对应 16809984 字节。请求/响应 buffering 关闭，认证头缓冲固定。SvelteKit 从 _kit.yml 自动推导 adapter-node BODY_SIZE_LIMIT。app 增量包携带代理配置；容量变化时复用现有 Web 镜像重建代理并纳入失败恢复，容量不变保留 Web 容器。容量变化须选择 app；路由/端口/其他代理策略改变仍要求全量部署。应用继续独立限制业务文件、解压和行数。自管代理调用 resolveTransportBodyLimits 获取同一预算。
 
-完全离线构建另需基础镜像、Linux 依赖缓存、pnpm 和匹配驱动/Node ABI/架构/libc 的原生预编译包。联网准备可选 --image-source / --npm-source 的 official、cn、custom；npm 参数随 --build 使用。代理通过 --proxy-mode 及 --proxy-url / --proxy-bypass 配置，--no-http-proxy 等价 none；镜像拉取端还需配置引擎代理。具体契约见 [下载源与代理](../hai-build/reference.md#下载源与代理)。原生包保留 --sqlite-prebuild-mirror，不让 deploy 下载编译环境。生产 HTTPS、CORS、证书、DNS 另行准备。实际断网验收登录、刷新、重启和数据持久化。
+完全离线构建另需基础镜像、Linux 依赖缓存、pnpm 和匹配驱动/Node ABI/架构/libc 的原生预编译包。联网准备可选 --image-source / --npm-source 的 official、cn、custom；npm 参数随 --build 使用。代理通过 --proxy-mode 及 --proxy-url / --proxy-bypass 配置，--no-http-proxy 等价 none；镜像拉取端还需配置引擎代理。具体契约见 [下载源与代理](../hai-build/reference.md#下载源与代理)。SQLite 13 的原生二进制随 npm 包交付，不再需要独立镜像参数；deploy 不下载编译环境。生产 HTTPS、CORS、证书、DNS 另行准备。实际断网验收登录、刷新、重启和数据持久化。
 
 ## 命令输出
 

package/templates/skills/hai-framework-sync/sync.md

@@ -18,6 +18,8 @@ hai-framework 是通用能力和 skill 模板的源头；应用仓库消费这
 
 ## 同步完整技能与入口
 
+依赖补丁必须与引用它的 pnpm 配置一起复制并验证安装。当前 DaisyUI 5.7.50 的 join 补丁是 CSS 构建兼容修复，**不是安全漏洞补丁**：它以零特异性的 `:where(:scope)` 避免优化器丢弃聚焦/悬停层级，依据 [官方问题](https://github.com/tailwindlabs/tailwindcss/issues/20668) 与[上游修复 PR](https://github.com/tailwindlabs/tailwindcss/pull/20671)。升级后验证实际 compile/optimize 与界面再决定移除；不要靠关闭优化或隐藏警告处理。纯 API 没有 UI/Svelte 构建依赖，不注册未使用的 DaisyUI/deepmerge 补丁；不能用安装豁免掩盖模板依赖差异。
+
 通过 CLI 补齐缺失文件时，先按 [CLI 安装与命令](../hai-app-create/development.md#cli-安装与命令) 安装所需精确版本的 `@h-ai/cli` 并检查 `hai --version` / `hai --help`，再从应用根运行 `hai init`。临时使用 CLI 可隔离安装到临时目录；不为读取模板要求全局安装或改变系统级工具。
 
 `hai init` 只补缺失内容，即使 `--force` 也不覆盖已有 AI 规则和 skills，不能用它代替旧版本规则合并。未发布模板修正从明确本地来源同步，不能假定已发布 CLI 已包含。

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

@@ -1,7 +1,11 @@
 # hai-kit 参考
 
+HTTP/UI 边界只对明确的有效 4xx 状态公开业务提示；错误缺少 `httpStatus` 或状态非法时按 500 返回安全提示。手写业务错误须提供完整错误定义或显式状态，不能依赖缺省状态展示原文。
+
 > `@h-ai/kit` 只负责 SvelteKit 集成：`handle` hook、guard、response、validate、client、auth、crud、A2A。公共跨端 HTTP API 契约统一使用 `@h-ai/api-contract` + `@h-ai/serv`，不要在 kit 中定义业务 API contract。
 
+命名空间公开类型为 `KitFunctions`（服务端）与 `BrowserKitFunctions`（浏览器）。浏览器条件入口仅暴露 client、crud、页面 Token 与默认语言操作，不含服务端认证、Hook 或限流。服务端认证 Cookie 的最小写入依赖为根入口的 `AuthCookieWriter`。运行时仍使用 `kit.xx`，导出方法或命名空间的声明不需要内部 helper 或私有构建路径。
+
 认证协议仅支持 v2：独立随机 SM4-CBC 密钥和 HMAC-SM3 密钥由 SM2 封装，先验签、再验证 MAC，最后解密 CBC。请求由客户端私钥签名，响应由所选服务端版本签名。认证字段包括 version、direction、serverKeyId、clientId、128 位随机 requestId（兼 nonce）、issuedAt、HTTP method、pathname + 原始 search 的 SM3 pathHash，以及响应 status。请求默认有效期为 5 分钟，客户端时间最多可领先服务器 30 秒。服务端可用 `maxRequestAgeSeconds`（1～600）和 `maxFutureSkewSeconds`（0～300）调整，单位为整数秒。共享 registry 原子消费 (clientId, requestId)，nonce 保留到 issuedAt + 11 分钟，覆盖最长可配窗口及节点时钟差，存储故障拒绝请求。Redis 必须保留有效 nonce，使用 noeviction/可靠持久化策略；各节点时钟须同步。此能力防止同一传输消息重放，业务重试仍需自己的幂等键。
 
 在 `_kit.yml` 的 `transport` 块配置时间窗口，将字段传给服务端 transport 装配。完成旧节点升级后等待 12 分钟，再把有效期调到 300 秒以上。校时提示与 `TransportTimeError.serverTime` 见 [Crypto 参考](../hai-crypto/reference.md)。`kit.client.createAuthActions()` 将已认证校时错误转为 `HaiResult`，供 AuthPanel 展示。
@@ -10,10 +14,14 @@
 
 ## 使用步骤
 
+错误响应与 Serv 共用 `HaiCommonError`：未认证用 `UNAUTHORIZED.code`、无权限用 `FORBIDDEN.code`、限流用 `RATE_LIMIT_EXCEEDED.code`（429）；不要匹配旧的无命名空间字符串。`fromError/fromResult` 保留安全字段校验、`httpStatus` 和追踪编号，内部异常只记录日志。前端使用已本地化的安全消息，排查按 `traceId` 关联服务端原因。
+
+`kit.response.validationError(errors)` 同样经 `fromError` 过滤，响应 `error.cause` 只含本地化 `field/message`；不回显 rejectedValue、SQL 或其他字段，不再读取 `details.errors`。
+
 ### 1. 请求管道
 
 ```ts
-import type { Handle } from '@sveltejs/kit'
+import type { Handle } from '@sveltejs/kit/hooks'
 import { cache } from '@h-ai/cache'
 import { kit } from '@h-ai/kit'
 
@@ -34,6 +42,8 @@ export const handle: Handle = haiHandle
 
 ### 2. SvelteKit API endpoint
 
+业务失败用 `kit.response.fromResult/fromError`，保留安全字段错误、显式 `publicExt` 和 HTTP 状态，内部异常仅进入关联日志；不要在业务 endpoint 手工拼接原始异常。
+
 ```ts
 import { kit } from '@h-ai/kit'
 import { z } from 'zod'
@@ -91,12 +101,14 @@ export const handle = kit.createHandle({
 })
 ```
 
-需要保护会话 Cookie 时配置 `crypto.encryptedCookies`，并通过 `crypto.cookieEncryptionKey` 或 `HAI_KIT_COOKIE_KEY` 提供密钥。缺少密钥会在 `createHandle()` 时失败；加解密错误不会回退到明文 Cookie。
+需要保护会话 Cookie 时配置 `crypto.encryptedCookies`，并通过 `crypto.cookieEncryptionKey` 或 `HAI_KIT_COOKIE_KEY` 提供密钥。密钥必须为 32 位十六进制。Cookie 采用分离子密钥的 SM4-CBC/HMAC-SHA256，先验证版本、名称、IV 与密文，再解密；旧版无认证 Cookie 升级后失效，需重新登录。缺少或非法密钥会在 `createHandle()` 时失败；加解密错误不会回退到明文 Cookie。
+
+不再使用无运行入口的旧 Crypto Helpers 或其 `CryptoServiceLike`、`EncryptedCookieConfig`、`CryptoCsrfConfig`、`WebhookVerifyConfig` 类型；这些已删除。Cookie 通过上述 `kit.createHandle` 配置保护，其他加密能力使用 `@h-ai/crypto` 真实公开 API。
 
 ```svelte
 <!-- src/routes/+layout.svelte -->
 <script lang='ts'>
-  import { browser } from '$app/environment'
+  import { browser } from '$app/env'
   import type { LayoutData } from './$types'
   import { crypto } from '@h-ai/crypto'
   import { kit } from '@h-ai/kit'
@@ -164,7 +176,7 @@ export function load() {
 `resolveKitConfig()` 同时解析 `server`（host/port）与 `transport`；host/port 优先级为 `HOST` / `PORT` 环境变量 > `_kit.yml` 的 `server` > 默认 `127.0.0.1:3000`（与 `@h-ai/serv` 同构）。
 `_kit.yml` 在服务端读取，可包含 access 和 trustedProxies；layout data 只投影公开 transport，不通过 ?raw 导入完整文件到浏览器，也不放密钥。如自定义 `keyExchangePath`，浏览器端必须同步映射为 `keyExchangeUrl`。请求策略按[共享约定](../hai-core/request-access.md)装配与验证。
 
-子目录部署从 `$app/paths` 取 `base`，服务端 `crypto.transport.basePath` 与客户端 `installBrowserTransport(config, { crypto, basePath: base })` 同步；独立 client 的 `transport.basePath` 也用该值。默认空字符串为根目录，不能仅调整资源地址后把登录成功当作加密验证。交换/排除/容量路径保持完整请求路径，验证原始请求带加密标记、缺协议被拒绝、排除接口正常且不影响相邻目录。
+子目录部署在 Vite 的 sveltekit 配置设置 `paths.relative: false`，从 `$app/paths` 用 `resolve('/').replace(/\/$/, '')` 取构建挂载目录 `base`，服务端 `crypto.transport.basePath` 与客户端 `installBrowserTransport(config, { crypto, basePath: base })` 同步；独立 client 的 `transport.basePath` 也用该值。默认空字符串为根目录，不能仅调整资源地址后把登录成功当作加密验证。交换/排除/容量路径保持完整请求路径，验证原始请求带加密标记、缺协议被拒绝、排除接口正常且不影响相邻目录。
 
 ## 核心 API
 

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

@@ -26,6 +26,8 @@
 
 ## 使用步骤
 
+并发调用 `close()` 会使尚未完成的 `init()` 失效，迟到初始化不会重新打开模块；等待该次初始化返回后可再次初始化。
+
 ### 1. 配置
 
 ```yaml

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

@@ -19,7 +19,8 @@ API 空 2xx 表示受理成功；非空 JSON 回执上限 64 KiB。redirect 默
 
 ## 使用路径
 
-- 先配置并注册 Provider，再保存绑定 Provider 的模板；模板发送只传 template/to/vars 即可，显式 provider 可覆盖；直接发送须提供 provider。启用 DND delay 必须先初始化 reldb 并确保队列表可用；成功时 `deferred: true` 与 `queueId` 表示可靠入队，尚未投递；缺库、断连或插入失败须按 HaiResult 失败处理。即时投递与排队状态须区分。
+- 使用模板先初始化 reldb，再初始化 Reach；非空配置模板的仓库/保存失败会使 init 返回 CONFIG_ERROR 并关闭候选 Provider。单次发送从同一模板快照渲染内容和选择默认 Provider，显式 provider 仍可覆盖；直接发送须提供 provider。启用 DND delay 也必须先初始化 reldb 并确保队列表可用；成功时 `deferred: true` 与 `queueId` 表示可靠入队，尚未投递；缺库、断连或插入失败须按 HaiResult 失败处理。即时投递与排队状态须区分。
+- API 自定义请求头整体视为私密数据，部署时写私有环境文件；`reach.config` 隐藏全部头值，不能只依靠 Authorization/token 等名称识别秘密。
 - 验证模板替换和错误分支时使用隔离测试收件人；真实通知须在用户授权范围内。
 - 阿里云短信的 `gateway` 通过 POST 转发已签名查询，可配置请求头和正文；服务端 `reach.init` 可按 Provider 名注入 `gatewayHooks`。受信内网 HTTP 须显式启用，转发日志应脱敏查询串。
 - 缓存锁只减少扫描，按实际执行逐条领取并在途续租。API 只有接收端真正具备原子持久去重时才能声明 idempotent=true，全部请求固定用 queueId 作为 Idempotency-Key；旧节点迟到请求也必须去重。SMTP/短信/默认 API 的在途失败或过期转 unknown，禁止自动重发；可信服务端用 queue.get/resolveUnknown 在人工隔离旧 worker、核对外部记录后裁定 sent/discarded。

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

@@ -14,7 +14,7 @@ Provider 名称必须唯一，重名在连接前返回 CONFIG_ERROR。close 等
 
 | 模块 | 用途 | 是否必需 | 初始化要求 |
 | --- | --- | --- | --- |
-| `@h-ai/reldb` | 数据库（发送日志与模板持久化） | DND delay 必需；其他场景可选 | 启用 delay 前先初始化，队列表不可用则 reach.init 返回 CONFIG_ERROR |
+| `@h-ai/reldb` | 数据库（发送日志与模板持久化） | 模板与 DND delay 必需；其他即时发送可选 | 先初始化；非空配置模板保存或必需表准备失败则 reach.init 返回 CONFIG_ERROR 并关闭候选 Provider |
 | `@h-ai/cache` | 缓存（DND delay 策略分布式锁） | 可选 | 已初始化时自动启用分布式锁 |
 
 ## 适用场景

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

@@ -41,4 +41,4 @@ description: "使用 @h-ai/reldb 访问 SQLite/PostgreSQL/MySQL，编写 SQL、C
 
 JSON 对象合并使用 RFC 7396 补丁，必须将返回的 SQL/params 放在同一次 UPDATE 内；禁止先读对象再覆盖整个列来模拟跨节点原子合并。路径函数的后端差异和完整可类型检查示例见 [reference.md](reference.md)。
 
-框架模块维护自己的版本迁移，应用不直接 ALTER 框架表。schemaColumns 只读真实列；migrateSchema(...,{dryRun:true}) 不创建账本。生产先停旧写入并备份 DB/共享会话缓存；SQLite/PostgreSQL 事务，MySQL DDL 隐式提交须可重入，失败不推进版本且重试检查真实结构。回退恢复兼容 DB 与代码，不只换二进制。模块 migrateIam/migrateReach/migrateScheduler 分别预检，初始化执行受支持步骤。
+框架模块维护自己的版本迁移，应用不直接 ALTER 框架表。`reldb.schemaColumns(table, sql?)` 只读真实列；`reldb.migrateSchema(module, steps, { dryRun: true })` 不创建账本。生产先停旧写入并备份 DB/共享会话缓存；SQLite/PostgreSQL 事务，MySQL DDL 隐式提交须可重入，失败不推进版本且重试检查真实结构。回退恢复兼容 DB 与代码，不只换二进制。模块 migrateIam/migrateReach/migrateScheduler 分别预检，初始化执行受支持步骤。

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

@@ -341,6 +341,8 @@ class UserRepository extends BaseReldbCrudRepository<User> {
 
 ### 事务 — `reldb.tx`
 
+一个事务只允许一个结束操作。`commit()` 或 `rollback()` 开始后，新查询、重复提交和并发回滚立即返回 TRANSACTION_FAILED；连接只归还一次。调用方仍须等待首次结束结果，不能把并发结束当作故障恢复。
+
 ```typescript
 // 方式1：wrap（自动 commit/rollback）
 const result = await reldb.tx.wrap(async (tx) => {
@@ -498,6 +500,8 @@ const result = await reldb.tx.wrap(async (tx) => {
 
 ## 生产共享状态
 
+应用自己的表迁移使用 `reldb.schemaColumns(table, sql?)` 读取真实列，使用 `reldb.migrateSchema(module, steps, options?)` 执行版本步骤；两者属于已初始化实例，不另传 reldb 句柄。`dryRun: true` 不写账本，失败不推进版本；MySQL DDL 必须可重入。框架表由各模块迁移入口维护，应用不要直接修改。
+
 生产仅使用 PostgreSQL/MySQL；SQLite（含磁盘文件）只用于开发/明确测试，不能作为跨主机共享状态。 NODE_ENV 或 HAI_CORE_ENV 为 production 时在初始化成功前检查，只有 HAI_E2E=1/HAI_E2E_MOCK=1 明确测试豁免。不要将租约当作最终写入条件，外部未知效果须按稳定业务键核对。
 
 MySQL 空 url（含空环境变量占位）按未配置处理，使用分字段；非空仍严格校验。

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

@@ -4,12 +4,16 @@
 
 > `@h-ai/serv` 是 hai-framework 的 API Service 运行时，对外暴露最小 HTTP App 抽象，将 `@h-ai/api-contract` 的领域 contract 挂载成跨端可访问的 HTTP API；Hono 是内部实现细节，应用代码不要直接 import 或暴露 Hono。
 
+命名空间的公开类型是根入口的 `ServFunctions`。上下文、工厂与泛型 contract 实现器均通过 `serv.xx` 使用；应用可导出方法或整个命名空间并生成声明，不要为类型推导改用私有构建路径或导入内部函数。
+
 ## 运行环境
 
 > ⚠️ **服务端模块（Node.js 或满足同等 Node API 依赖的宿主）。** 浏览器端通过 `@h-ai/api-client` 调用由本模块暴露的 HTTP API。
 
 > 生命周期说明：`@h-ai/serv` 是无状态 HTTP App 装配器，不提供 `init()` / `close()`；依赖模块（iam/storage/ai/crypto 等）由应用先初始化，并在 `serv.listen(..., { onClose })` 中反向释放。`serv.createApp()` 的启动期配置错误会 fail-fast 抛出。
 
+返回的监听句柄允许立即 `close()` 取消未完成绑定，重复关闭复用结果；真实监听错误仍会拒绝。调用 `handle.close()` 不代替宿主的业务模块清理。
+
 ## 适用场景
 
 - 将 `@h-ai/api-contract` contract 装配成最小 HTTP App 抽象
@@ -25,6 +29,8 @@
 - 公开只读文件通过 `serv.storageAssets(...)` 统一处理安全 key、MIME 白名单、GET/HEAD、ETag 与缓存头
 - 为 Audio WebSocket 配置一次性 ticket 校验、IAM/模型/配额授权与并发释放钩子
 
+权限遵循 IAM/Kit 的精确值、全局 `*` 与冒号前缀 `users:*` 规则；声明多个权限时全部满足。返回的 listener `close()` 幂等并移除信号监听器，先关闭 Audio WebSocket，1 秒后终止未配合的音频连接；业务模块由宿主反序释放。
+
 ## 使用步骤
 
 ### 1. 安装依赖
@@ -63,6 +69,7 @@ const procedures = {
 const app = serv.createApp({
   contract,
   procedures,
+  iam,
   http: {
     apiPrefix: '/api/v1',
     openapi: { path: '/openapi.json' },
@@ -98,6 +105,7 @@ const app = serv.createApp({
     openapi: security.exposeApiDocs ? servConfig.http.openapi : false,
     docs: security.exposeApiDocs ? servConfig.http.docs : false,
   },
+  iam,
   refreshCookie: { secure: security.secureRefreshCookie },
   middlewares: [{
     middleware: serv.cors({
@@ -552,7 +560,7 @@ HTTP 审计、限流、CORS、租户头校验等跨 route 能力继续放在
 
 HTTP middleware、自定义 Response、refresh-cookie、OpenAPI 入口权限和 transport 协议错误分别按自身响应契约处理，可返回真实 HTTP 4xx/5xx。`@h-ai/api-client` 在真实 HTTP 401 或 HTTP 200 的有效失败 HaiResult（`success=false`、字符串 `error.code/message`、`error.httpStatus=401`）后自动刷新，成功后只重试一次；内置登录、注册和配置的刷新路径除外，403/500 不刷新。启用 transport 时刷新和重试复用加密链路，不能手写明文刷新请求。
 
-SvelteKit 的 `kit.response.fromError` 根据 `error.httpStatus` 生成 HTTP Response；`kit.response.fromResult` 使用显式错误码映射，未命中默认 400。这些响应转换规则不能套用到 serv 普通 procedure。
+SvelteKit 的 `kit.response.fromError` 根据归一化后的 `error.httpStatus` 生成 HTTP Response；`kit.response.fromResult` 优先使用显式错误码映射，再使用错误自身的 `httpStatus`，缺失或非法状态统一为 500。这些响应转换规则不能套用到 serv 普通 procedure。
 
 按三层处理：
 
@@ -581,7 +589,7 @@ const procedures = serv
   .build()
 ```
 
-> 如果错误来自下游模块（如 `iam` / `storage`）并且该模块已经返回 `HaiResult`，serv 默认**透传**它的 `error.message`。由于 `HaiError` 目前不携带 `messageKey/params`，serv 边界不能对任意下游错误再做通用重翻译；要做请求级 i18n，必须在创建该错误的模块/feature 里就拿到 locale。
+> 下游 4xx 消息经脱敏后公开，5xx 和缺失或非法状态使用安全内部错误与 traceId，完整原因只记录服务端日志。`HaiError` 不携带 `messageKey/params`，领域消息的请求级 i18n 仍在创建消息的模块/feature 中接收 locale 后完成。自动审计使用同一归一化状态，失败不能按非法原始状态记为成功。
 
 ### `serv.parseRequestContext` — 默认 Context 解析器
 
@@ -737,6 +745,8 @@ route 实现器内置以下错误：
 原生客户端匹配 `nativeTokenTransport.isRequest` 后，登录/注册/刷新响应保留轮换后的
 `refreshToken`，刷新请求从 `{ refreshToken }` body 读取，且不读写浏览器 Cookie。
 
+刷新失败经过同一公开错误投影，并记录英文关联日志；仅 401 认证失效会清除浏览器刷新 Cookie，限流、5xx 和缺失或非法状态保留凭据供稍后重试。未捕获的刷新异常返回安全的 HTTP 500 JSON，不公开内部 cause/ext。
+
 若同时启用 `transport: { crypto, serverKeyRing, keyStore }`，`/auth/refresh` 也必须走加密链路；cookie-only 刷新请求允许空 body，服务端不要把 `Request.body === null` 误判为需要解密的请求体。
 
 ### 配置

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

@@ -4,7 +4,7 @@
 
 ## 运行环境
 
-Local 的 key 路径拒绝文件符号链接和目录 junction，`.meta.json` / `.upload.tmp` 保留后缀不区分大小写。覆盖 put 清除旧元数据，copy 默认继承源元数据。浏览器根入口仅导出 Schema、类型和客户端辅助能力。
+Local 的 key 路径拒绝文件符号链接和目录 junction；每个路径段都保留 `.meta.json` / `.upload.tmp` 后缀及 `.hai-storage-meta` 目录，不区分大小写。先在该内部目录准备文件身份对应的代际元数据（含显式空默认值），再原子发布内容；准备失败不改内容，发布后的历史记录清理失败只记录诊断，不回滚其他写入。代际记录是唯一格式，不读取旧 `<key>.meta.json`；缺少当前记录时明确失败，旧数据须离线迁移或重新 `file.put()`。备份与迁移包含内容和内部记录，不混用旧程序写入。copy 默认继承源元数据；S3 copy 接收原始 key，内部逐段编码 Unicode、空格和 URL 分隔字符。浏览器根入口仅导出 Schema、类型和客户端辅助能力。
 
 > ⚠️ **服务端模块**。`storage.file` / `storage.dir` / `storage.presign` 均在 Node.js 端使用。浏览器端通过预签名 URL 或 API 端点间接访问存储（见下方「浏览器端文件上传」）。
 
@@ -198,10 +198,19 @@ if (!result.success) return result
 
 `checksum.generate(data, options?)` / `checksum.verify(data, expected, options?)` 默认 SHA-256、小写 hex，可选 sha384/sha512/sha1/md5、base64 编码与 signal；流仅消费一次，读取失败返回 HaiResult 错误，不匹配返回 false。MD5/SHA-1 不作安全认证，ETag 和 multipart 复合 checksum 不当作完整文件摘要。浏览器不导入 Node checksum；离线增量摘要需使用适用的浏览器实现，不把 SubtleCrypto.digest 当流式 API。
 
-### 与 kit 集成（文件上传 API）
+### Serv / Fullstack 私有附件
+
+Fullstack/API 项目先读取本工程已交付的 hai-serv/reference.md 中“扩展应用自有 contract + procedures”和“Feature Procedures”，结合 hai-api-contract、hai-api-client 扩展；保留其 contract/serv/shared 分层，不复制下方 SvelteKit 路由。
+
+- 在 `packages/<name>-contract`（API 为 `apps/<name>-contract`）声明应用自己的附件 contract，在 serv 的 procedures 聚合入口挂载。当前生成的 Fullstack 客户端是共享 `managementApi`，需先将新领域纳入工程 contract；不能把文档中的默认 `apiClient.storage` 当作工程已经开放的接口。
+- 自有 procedure 使用 `serv.implement(contract).context<ServContext>().route(...).auth().handle(...)`；owner 来自可信 `context.session.userId`，按 ID 操作还须查验业务记录归属、状态与租户。key 由服务端生成，列表也在服务端限定本人范围。
+- 可复用 `createStorageProcedures({ storage, authorize })` 的已有签名/列表/元数据/删除操作，authorize 必须按可信 session 核对 operation 与全部 keys，拒绝空 prefix 与跨用户请求。只挂载实际需要的子路由，不能绕过应用附件记录、限额或审计；框架没有默认的 `attachments.*` 业务 API。
+- FileUpload 注入应用 uploadHandler；S3 签名 URL 是短期访问凭据，不能当作持续会话授权。上传完成后仍验证大小、实际内容与对象状态；仍有效的 PUT URL 可以重写其目标，严格发布时使用 staging/final 对象隔离。需要 Local 或严格逐次鉴权的二进制流程时，通过 Serv 自有 middleware 接入 `storage.file.put/getStream`，显式认证并精确配置传输策略，不能把公开 `serv.storageAssets` 用于本人私有附件。
+
+### 与 kit 集成（SvelteKit 文件上传 API）
 
 ```typescript
-import { storage } from '$lib/server/init'
+import { storage } from '#lib/server/init.js'
 // src/routes/api/files/upload/+server.ts
 import { kit } from '@h-ai/kit'
 import { z } from 'zod'

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

@@ -42,9 +42,10 @@ Toast 支持 F8 聚焦/返回、Escape 关闭可关闭提示并恢复焦点；Mo
 - 先检查组件导入、Tailwind @source 和主题 CSS，再选场景 → 组合 → 原子组件，缺能力才自定义。
 - 管理列表和工作台随可用宽度展开；flex/grid 子项设 min-width: 0，表格在自身容器滚动。阅读页与登录表单按内容约束宽度。实际检查 390、1440、1920、2560、3840px，避免宽屏仍挤在中央窄列，手机出现整页横向滚动。
 - 按安装版本的 exports 选择明确列出的 components barrel 入口（不开放任意内部文件）；主题工具使用 `@h-ai/ui/theme`，避免仅为主题加载根入口的 AI/图表组件。禁止导入内部 src/dist；例如原子组件使用 `@h-ai/ui/components/primitives/index`。
-- 自动导入识别无分号、跨行及别名的运行时 import；已绑定的本地组件名称不会重复注入。
+- 先执行 `vitePreprocess()` 或其他样式/模板语言转换，再执行 `autoImportHaiUi()`；自动导入读取整份 Svelte AST，不接受未转换的 SCSS/Pug，直接 markup API 保持同步。
+- 自动导入按语法树识别真实 import，保留字符串/注释、别名与已有运行时绑定；根入口 `@h-ai/ui` 的 type-only 组件按需提升。外部同名类型冲突会构建报错并列出文件/组件名，应为类型设置别名或以其他本地名显式导入组件，不重写业务类型引用。
 - 应用只提供页面级文案；组件内部中英日文由 @h-ai/ui 维护。
-- `UserProfile` 用 `avatarAccept` / `avatarHint` 对齐业务的头像格式与大小限制；文件最终校验和上传由业务回调完成。
+- `UserProfile` 用 `avatarAccept` / `avatarHint` 对齐业务的头像格式与大小限制；文件最终校验和上传由业务回调完成。`onsubmit` 必须返回 boolean，只有 `true` 退出编辑，`false` 或异常保留草稿与重试入口。
 - `BareInput type="file"` 通过 `onchange` 的 `currentTarget.files` 读取文件，不绑定文件路径 `value`；其他输入类型可 `bind:value`。
 - AI 文本视为不可信；Markdown/Mermaid 预览与允许执行 HTML/JS 的预览有不同边界。
 

package/templates/skills/hai-ui/guide.md

@@ -10,7 +10,7 @@
 <script lang='ts'>
   import { createGuide, GuideHost } from '@h-ai/ui/guide'
   import { createSvelteKitNavAdapter } from '@h-ai/kit/client'
-  import * as m from '$lib/paraglide/messages.js'
+  import * as m from '#lib/paraglide/messages.js'
 
   const guide = createGuide({
     nav: createSvelteKitNavAdapter(),

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

@@ -1,5 +1,7 @@
 # hai-ui — 详细用法
 
+HTTP/UI 边界只对明确的有效 4xx 状态公开业务提示；错误缺少 `httpStatus` 或状态非法时按 500 返回安全提示。手写业务错误须提供完整错误定义或显式状态，不能依赖缺省状态展示原文。
+
 从 [SKILL.md](SKILL.md) 选择主题后读取对应小节。代码片段展示 API 用法；省略的业务变量、schema、依赖与 return 上下文需由应用补齐。
 
 > `@h-ai/ui` 是基于 Svelte 5 Runes 的多端 UI 组件库，采用 DaisyUI v5 + Tailwind CSS v4 + Bits UI v2，内置 15 个精选 DaisyUI 主题及 high-contrast 高对比、formal 直角商务、eye-care 暖绿护眼主题、内置中英日文 i18n、自动导入。内置 Shiki 代码高亮、Mermaid 图表渲染、Design Token 系统和 7 个移动端组件。
@@ -39,7 +41,7 @@
 
 至少检查以下四项：
 
-- `svelte.config.*`：`autoImportHaiUi()` 在 `vitePreprocess()` 前。
+- SvelteKit 3 在 `vite.config.*` 的 `sveltekit({...})` 中设置预处理；纯 Svelte/Vite 使用 `svelte.config.*`。两者都先执行 `vitePreprocess()` 或其他样式/模板语言转换，再执行 `autoImportHaiUi()`；后者按整份 Svelte AST 定位实例脚本，不直接接受转换前的 SCSS/Pug，直接 markup 调用保持同步。
 - `vite.config.*`：`ssr.noExternal` 包含 `@h-ai/ui` 和 `@h-ai/kit`，`optimizeDeps.exclude` 包含 `bits-ui`。
 - `app.css`：已导入 `global.css` / `theme.css`；移动端还要导入 `design-tokens.css` / `mobile.css`。
 - Tailwind：已配置 `@source` 扫描 `@h-ai/ui/dist/**/*.{svelte,js,ts}`。
@@ -99,55 +101,39 @@ npm install -D tailwindcss @tailwindcss/vite daisyui
 npm install -D @iconify/tailwind4 @iconify-json/tabler
 ```
 
-Node adapter 使用 Crypto、Kit 或 IAM 时，还需将 `sm-crypto@0.5.7` 作为直接生产依赖安装，保留 Node 原生模块解析。
-
-### 2. svelte.config.js
-
-```js
-import { autoImportHaiUi } from '@h-ai/ui/auto-import'
-import adapter from '@sveltejs/adapter-node'
-import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
+Node adapter 使用 Crypto、Kit 或 IAM 时，还需将 `sm-crypto@0.5.8` 作为直接生产依赖安装，保留 Node 原生模块解析。
 
-/** @type {import('@sveltejs/kit').Config} */
-const config = {
-  // autoImportHaiUi 必须在 vitePreprocess 之前
-  preprocess: [autoImportHaiUi(), vitePreprocess()],
-  compilerOptions: {
-    runes: true, // 强制 Svelte 5 Runes 模式
-  },
-  kit: {
-    adapter: adapter(),
-    alias: {
-      $components: './src/lib/components',
-      $stores: './src/lib/stores',
-    },
-  },
-}
+### 2. package.json 的应用导入
 
-export default config
+```json
+{ "imports": { "#lib/*": "./src/lib/*" } }
 ```
 
 ### 3. vite.config.ts
 
+SvelteKit 3 的预处理、编译器和适配器统一配置在 Vite 插件；纯 Svelte/Vite 工程保留自己的 svelte.config.js。
+
 ```ts
+import { autoImportHaiUi } from '@h-ai/ui/auto-import'
+import { haiOptimizeExclude, haiPrebundledDeps } from '@h-ai/ui/vite'
+import adapter from '@sveltejs/adapter-node'
 import { sveltekit } from '@sveltejs/kit/vite'
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
 import tailwindcss from '@tailwindcss/vite'
 import { defineConfig } from 'vite'
 
 export default defineConfig({
   plugins: [
-    sveltekit(),
+    sveltekit({
+      preprocess: [vitePreprocess(), autoImportHaiUi()],
+      compilerOptions: { runes: true },
+      adapter: adapter(),
+      paths: { relative: false },
+    }),
     tailwindcss(),
   ],
-  optimizeDeps: {
-    // bits-ui 使用 Svelte 虚拟模块，需排除预构建
-    exclude: ['bits-ui'],
-  },
-  ssr: {
-    // @h-ai 包为 ESM + Svelte 组件，需 Vite 在 SSR 时处理
-    noExternal: ['@h-ai/ui', '@h-ai/kit'],
-    external: ['@h-ai/core', 'sm-crypto'],
-  },
+  optimizeDeps: { exclude: [...haiOptimizeExclude], include: [...haiPrebundledDeps] },
+  ssr: { noExternal: ['@h-ai/ui', '@h-ai/kit'], external: ['@h-ai/core', 'sm-crypto'] },
 })
 ```
 
@@ -367,6 +353,8 @@ const p = usePlatform()
 | `RegisterForm` | `fields`, `minPasswordLength`, `errors`         | 注册表单 |
 | `UserProfile`  | `user`, `editable`, `fields`, `avatarAccept`, `avatarHint` | 用户资料，选择器和提示对齐业务校验；最终验证和上传仍由回调负责 |
 
+`UserProfile.onsubmit` 必须返回 `true` / `false` 表示保存成功 / 失败；仅成功退出编辑，失败保留编辑器与草稿。宿主在失败时更新错误提示并返回 `false`，不要把失败转换成正常关闭。
+
 #### 错误页 / 设置场景组件
 
 | 组件             | Props 要点                                  | 说明     |

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

@@ -187,7 +187,7 @@ Chroma 直连 `url` 仅支持 HTTP(S) 根端点，优先于 `host/port`；URL
 
 直连初始化总截止为 5 秒，本地服务拉起使用 `startupTimeout`；超时中止候选 HTTP 请求。成功清除初始化 timer，不限制后续业务请求。
 
-Qdrant 使用 `@qdrant/js-client-rest 1.18.0`，仅支持未命名向量字段的 cosine/euclidean/dot；外部 named-vector/Manhattan 集合的 info/写入/搜索返回 CONFIG_ERROR，不猜测维度或 metric。Chroma 使用 `chromadb 3.5.0` 的真实类型及 metadata/filter 校验，非法输入返回操作错误，不丢弃过滤；content 可省略。各后端的 null 和复杂元数据语义不承诺统一。
+Qdrant 使用原生 HTTP 固定 REST 端点，无额外 SDK 依赖；超时 30 秒覆盖完整响应体，响应超过 16 MiB 明确失败。仅支持未命名向量字段的 cosine/euclidean/dot；外部 named-vector/Manhattan 集合的 info/写入/搜索返回 CONFIG_ERROR，不猜测维度或 metric。Chroma 使用 `chromadb 3.5.0` 的真实类型及 metadata/filter 校验，非法输入返回操作错误，不丢弃过滤；content 可省略。各后端的 null 和复杂元数据语义不承诺统一。
 
 **VectorDocument**：