@h-ai/cli 1.0.0-beta.21 → 1.0.0-beta.22

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "1.0.0-beta.21",
+  "version": "1.0.0-beta.22",
   "description": "Hai Framework CLI for project scaffolding and code generation.",
   "license": "Apache-2.0",
   "keywords": [
@@ -30,7 +30,7 @@
     "node": "^22.23.4 || ^24.22.1 || ^26.12.1"
   },
   "dependencies": {
-    "@h-ai/core": "1.0.0-beta.21",
+    "@h-ai/core": "1.0.0-beta.22",
     "cac": "^7.1.0",
     "chalk": "^6.0.1",
     "fast-wrap-ansi": "^0.2.2",
@@ -41,18 +41,18 @@
     "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@h-ai/api-client": "1.0.0-beta.21",
-    "@h-ai/cache": "1.0.0-beta.21",
-    "@h-ai/crypto": "1.0.0-beta.21",
-    "@h-ai/deploy": "1.0.0-beta.21",
-    "@h-ai/feedback": "1.0.0-beta.21",
-    "@h-ai/iam": "1.0.0-beta.21",
-    "@h-ai/kit": "1.0.0-beta.21",
-    "@h-ai/payment": "1.0.0-beta.21",
-    "@h-ai/reach": "1.0.0-beta.21",
-    "@h-ai/reldb": "1.0.0-beta.21",
-    "@h-ai/storage": "1.0.0-beta.21",
-    "@h-ai/vecdb": "1.0.0-beta.21",
+    "@h-ai/api-client": "1.0.0-beta.22",
+    "@h-ai/cache": "1.0.0-beta.22",
+    "@h-ai/crypto": "1.0.0-beta.22",
+    "@h-ai/deploy": "1.0.0-beta.22",
+    "@h-ai/feedback": "1.0.0-beta.22",
+    "@h-ai/iam": "1.0.0-beta.22",
+    "@h-ai/kit": "1.0.0-beta.22",
+    "@h-ai/payment": "1.0.0-beta.22",
+    "@h-ai/reach": "1.0.0-beta.22",
+    "@h-ai/reldb": "1.0.0-beta.22",
+    "@h-ai/storage": "1.0.0-beta.22",
+    "@h-ai/vecdb": "1.0.0-beta.22",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^26.6.6",
     "@types/prompts": "^2.4.9",

package/templates/apps/fullstack/images/web/nginx.conf.hbs

@@ -1,12 +1,14 @@
 {{! @skipIfEmpty }}
 {{#if fullstack.frontends.web}}
+{{{nginxDownloadErrors "http"}}}
 server {
   listen 8080;
   server_name _;
   root /usr/share/nginx/html;
 
+{{{nginxDownloadErrors "server"}}}
   location / {
-    try_files $uri $uri/ /index.html;
+    try_files $uri $uri/ @hai_spa_fallback;
   }
 
   location = /runtime-config.js {

package/templates/base/images/web/nginx.conf.hbs

@@ -1,12 +1,14 @@
 {{! @skipIfEmpty }}
 {{#if isSvelteOnlyApp}}
+{{{nginxDownloadErrors "http"}}}
 server {
   listen 8080;
   server_name _;
   root /usr/share/nginx/html;
 
+{{{nginxDownloadErrors "server"}}}
   location / {
-    try_files $uri $uri/ /index.html;
+    try_files $uri $uri/ @hai_spa_fallback;
   }
 
   location = /runtime-config.js {

package/templates/base/package.json.hbs

@@ -1,7 +1,7 @@
 {
   "engines": { "node": "^22.23.4 || ^24.22.1 || ^26.12.1" },
   "name": "{{projectName}}",
-  "version": "1.0.0-beta.21",
+  "version": "1.0.0-beta.22",
   "private": true,
   "packageManager": "pnpm@12.11.2",
   "description": "{{#if_eq appType 'admin'}}Enterprise management system built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'website'}}Enterprise website built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'h5'}}Mobile H5 app built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'api'}}REST API service built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'mobile-app'}}Mobile app built with hai Agent Framework{{/if_eq}}",

package/templates/shared/download-error/http.conf

@@ -0,0 +1,19 @@
+map "$request_method:$args" $hai_signed_download {
+  default 0;
+  "~*^(GET|HEAD):(?:[^&]*&)*X-Amz-Signature=[^&]+(?:&|$)" 1;
+}
+map $http_accept_language $hai_download_language {
+  default zh-CN;
+  ~*^en en-US;
+  ~*^ja ja-JP;
+}
+map $hai_download_language $hai_download_title {
+  default "下载链接无法访问";
+  en-US "Download link unavailable";
+  ja-JP "ダウンロードリンクにアクセスできません";
+}
+map $hai_download_language $hai_download_instruction {
+  default "请返回下载页面重新获取链接。若仍无法下载，请联系管理员。";
+  en-US "Return to the download page to get a new link. If the download still fails, contact your administrator.";
+  ja-JP "ダウンロードページに戻り、新しいリンクを取得してください。解決しない場合は管理者にお問い合わせください。";
+}

package/templates/shared/download-error/server.conf

@@ -0,0 +1,52 @@
+  location @hai_download_unavailable {
+    access_log off;
+    error_log /dev/null;
+    types { }
+    default_type text/html;
+    charset utf-8;
+    add_header Cache-Control "private, no-store" always;
+    add_header Referrer-Policy no-referrer always;
+    add_header X-Content-Type-Options nosniff always;
+    add_header Content-Security-Policy "default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'" always;
+    return 404 '<!doctype html>
+<html lang="$hai_download_language">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="robots" content="noindex">
+  <meta name="referrer" content="no-referrer">
+  <link rel="icon" href="data:,">
+  <title>$hai_download_title</title>
+  <style>
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      min-height: 100vh;
+      display: grid;
+      place-items: center;
+      padding: 24px;
+      background: #f1f5f9;
+      color: #172033;
+      font-family: Inter, system-ui, "Microsoft YaHei", sans-serif;
+      line-height: 1.7;
+    }
+    main {
+      width: min(100%, 640px);
+      padding: clamp(24px, 6vw, 48px);
+      border: 1px solid #dbe3ee;
+      border-top: 4px solid #2563eb;
+      border-radius: 12px;
+      background: #fff;
+    }
+    h1 { margin: 0 0 16px; font-size: clamp(24px, 5vw, 32px); line-height: 1.4; }
+    p { margin: 0; color: #475569; font-size: 16px; }
+  </style>
+</head>
+<body><main><h1>$hai_download_title</h1><p>$hai_download_instruction</p></main></body>
+</html>';
+  }
+  location @hai_spa_fallback {
+    error_page 418 = @hai_download_unavailable;
+    if ($hai_signed_download) { return 418; }
+    try_files /index.html =404;
+  }

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

@@ -23,7 +23,7 @@ description: "接入或排查 @h-ai/api-client typed API、登录 Token、自动
 4. 同步服务端与客户端的刷新、加密和错误处理；切换配置前 close，任务结束释放客户端。
 5. 验证登录、刷新重试、失败、退出与会话恢复。
 
-错误提示与诊断分离：HTTP/UI 边界用 core.error.toPublic，仅公开 i18n 安全消息及 error.traceId；重新翻译后用 core.error.formatMessage 保留关联。ToastContainer 默认只显示可读说明，自动将编号移入排查信息图标，展开后可查看、复制并提供给客户支持或开发人员。前后端日志传完整 Error 和操作上下文，使用同一 requestId/traceId 并脱敏；禁止只写通用错误标题，也不能把 cause/ext/SQL/绑定值直接返回用户。数据库日志保留安全的驱动错误码、消息和堆栈。
+保留服务端错误的 `traceId`，UI 使用公开安全消息，重新翻译后用 `core.error.formatMessage` 保留编号。4xx 和可关联的服务端错误使用 `debug`。客户端自己的网络、协议或未关联的 5xx 失败使用 `error`，记录可用的传输诊断字段。具体见 [日志与错误诊断](../hai-app-create/logging.md)。
 
 非 2xx HTTP 响应中的合法失败 HaiResult 保留服务端业务码、消息与 traceId，以真实 HTTP 状态执行脱敏。验证 409 冲突、422 输入错误、429 限流和 5xx，不只测试 HTTP 200 业务失败；UI 包装 Error 时通过 cause 保留 HaiError。
 

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

@@ -19,6 +19,8 @@ description: "在 hai 应用中新增、修改或修复功能，按需求复用
 
 沟通、问题状态与文档/配置/截图/测试/模板/调用方同步遵循[沟通与同步维护](collaboration.md)。
 
+生成或修改错误处理和日志时，应用 [日志与错误诊断](logging.md) 中的级别、根因与脱敏规则。
+
 范围、验收、复用依据和证据按 [工作交接契约](../hai-spec-implement/handoff.md) 贯穿实现、测试和审查；小改动使用简短记录，文档驱动任务沿既有任务记录续跑。
 
 业务以用户当前明确要求及其指定文档为准；模板规则、生成代码与测试只描述初始方案。需求改变角色、流程、限额或架构时，在已有授权范围内同步调整冲突实现及过期 AGENTS/skills/README，不要求把需求改回模板。具体判定见 [development.md](development.md#需求与模板的关系)。

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

@@ -0,0 +1,32 @@
+# 日志与错误诊断
+
+框架模块、服务端业务代码和浏览器代码统一使用 `core.logger`。用 `core.logger.child({ module, scope })` 标记稳定的来源，英文日志消息说明发生的操作。应用与常规 CLI 操作沿用 Core 日志配置，应用可通过 `_core.yml` 的 `logging.level` 或 `HAI_CORE_LOGGING_LEVEL` 设置阈值。提供 JSON 输出的命令按其机器可读输出契约处理诊断。
+
+## 日志级别
+
+| 级别 | 使用场景 |
+| --- | --- |
+| `trace` | 请求和响应摘要、循环细节等按需诊断。请求查询只记录参数数量。 |
+| `debug` | 常规读写的安全摘要、预期的 HTTP 4xx、客户端对已带服务端追踪编号的错误进行关联。 |
+| `info` | 初始化完成、服务就绪和有意义的低频状态变化。 |
+| `warn` | 模块所拥有的业务操作失败、可恢复的外部故障或清理失败。 |
+| `error` | 初始化或连接失败、影响资源状态的关闭失败、未预期异常和服务端 5xx。 |
+| `fatal` | 进程无法继续运行的故障。 |
+
+由能看到根因的层记录失败。上层复用错误码和追踪编号，按需要补充诊断摘要。接口和 UI 使用现有的公开错误映射与本地化提示。客户端自己的网络、协议或未处理异常需要独立诊断。操作日志的读写开关控制正常摘要，错误日志由对应级别和 Core 阈值控制。持久化审计遵循审计契约。
+
+## 保留根因与关联信息
+
+- 对 `HaiResult` 先判断 `success`。业务调用方应得到有区分度的错误码和消息，以及可获得的原始 `error.cause`。把后续失败单独保存在 `error.ext.cleanupError` 等既有诊断字段，保留取消原因和业务分支所需的错误码。HTTP 对外使用安全消息和追踪编号。
+- 日志使用结构化上下文。沿用模块已有的操作名和错误码字段，并按需记录失败阶段、状态和可用的 `traceId` 或 `requestId`。上游请求编号独立记录为 `providerRequestId`。需要堆栈时保留可排查的脱敏异常链。
+- 用明确的字段白名单构造日志。省略密码、token、密钥、连接凭据、完整配置、请求正文和查询值、联系方式、消息主题和正文、签名 URL、对象或文件内容、SQL 绑定值、文档、向量和过滤值。连接地址复用 `core.sanitize.sanitizeUrl`。字段脱敏不能识别自由文本里的全部私密值，外部错误正文应提取有界的错误码、状态和请求编号。
+
+## Storage
+
+`storage` 默认开启写操作摘要，读操作按需开启。常规操作使用 `debug`，上传、下载、删除等失败返回业务错误并记录 `warn`，初始化、连接或关闭失败记录 `error`。日志省略对象键、签名地址和内容。使用 `HAI_CORE_LOGGING_LEVEL`，旧的 `HAI_STORAGE_OPERATIONLOG_LEVEL` 与 `operationLog.level` 已移除。
+
+流式上传保留源读取错误、取消原因和 S3 原始写入错误。分片清理也失败时单独保留清理错误，并记录可用的 S3 操作名和请求编号。条件写入冲突按 `ALREADY_EXISTS` 处理。使用 Storage 时查阅项目中 `hai-storage` 的配置与错误说明。
+
+## 验证
+
+修改日志或错误处理时，从实际公共入口验证受影响的成功和失败分支。按场景核对日志级别、原始原因、关联编号和脱敏字段。涉及上传、取消或回滚的双重失败，用受控故障验证业务结果和日志均保留首次错误与清理诊断。可使用 `core.logger.observe` 捕获结构化记录。

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

@@ -15,6 +15,7 @@
 - 服务端校验输入、身份、权限及资源/租户归属；SQL 值参数化、标识符白名单、文件路径防逃逸。不把隐藏按钮当授权，不执行不可信 HTML/AI 内容。
 - 密钥不进入 PUBLIC_/VITE_、浏览器或日志，敏感 token 不写 localStorage；沿现有 Cookie/内存或原生安全存储流程。用户提示准确且脱敏，日志保留英文操作上下文及可关联错误，未知提交不自动重放。
 - 禁止 any、无说明的 as unknown as、console.log、硬编码密钥。注释中文，结构化日志英文且脱敏，用户文本沿现有 i18n 同步全部 locale。
+- 实现或审查错误处理和日志时，核对 [日志与错误诊断](logging.md) 的业务返回、日志级别、字段白名单与追踪编号。
 
 ## 代码注释与示例
 

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

@@ -228,9 +228,7 @@ export async function listArticles(params: ListParams): Promise<HaiResult<Pagina
 ### 服务层规则
 
 - 应用领域操作沿现有契约返回 `HaiResult<T>`；纯 getter、工具、工厂与流按实际签名，不统一改造
-- 写操作需 `debug`（进入）+ `info`（成功）日志
-- 读操作仅 `debug` 日志
-- 禁止 `console.log`，使用 `core.logger`
+- 需要记录服务层操作时，使用 `core.logger` 和 [日志与错误诊断](logging.md) 约定的安全摘要。传播框架模块的 `HaiResult` 错误时保留原因和关联信息。
 - 服务层不处理 HTTP 响应格式，只返回 HaiResult
 
 ## 创建数据模型
@@ -357,7 +355,7 @@ core.init() → crypto.init() → reldb.init() → cache.init() → iam.init()
 - [ ] 页面使用 Svelte 5 Runes 语法
 - [ ] API 端点有权限守卫与输入校验
 - [ ] 服务层和调用方遵循实际返回/抛错/流契约，不能以 HTTP 成功替代业务状态成功
-- [ ] 日志级别正确（读 debug / 写 debug+info / 失败 warn|error）
+- [ ] 已验证 [日志与错误诊断](logging.md) 的日志级别、失败原因、关联编号和脱敏字段
 - [ ] 禁止 `console.log`、`any`、硬编码密钥
 - [ ] 用户可见文本走 i18n
 - [ ] 涉及容器交付时，镜像启动及配置/环境变量/数据目录行为已验证

package/templates/skills/hai-app-review/SKILL.md

@@ -60,7 +60,7 @@ typecheck/lint 不能证明越权、租户隔离、事务、错误状态或资
 
 - 禁止 `any`、无说明的 `as unknown as T`、`console.log`、硬编码密钥；外部 `unknown` 先校验/缩窄。必要第三方断言有真实依据。
 - 遵循当前 ESLint、TypeScript、目录与命名规则，函数返回类型按真实契约标注；不把所有返回类型都强制成 HaiResult。
-- 注释中文，结构化日志英文并脱敏。读操作用 debug，写操作成功用 info，失败按业务/系统性质用 warn/error；避免记录整份请求、凭据或未经脱敏的 error/context。
+- 注释中文，结构化日志英文。按 [日志与错误诊断](../hai-app-create/logging.md) 核对级别、字段白名单、原始原因和重复记录。
 - 用户可见文案沿现有 i18n 入口，同步中英日文；包括错误、空态、降级、校验和状态文案。禁止手改 Paraglide 生成文件；框架组件内置翻译沿公开 Props 使用。
 - 业务逻辑不塞入 UI/hook；优先 early return、按职责拆分复杂函数。遵守实际 lint 的复杂度/长度限制，不为了数字拆出无意义转发链。
 - 循环串行/并发按依赖、事务、限流与资源限制选择；列表分页/流式处理，避免热路径同步 I/O、重复连接和无界并发。

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

@@ -192,7 +192,7 @@ logger.info('Module initialized')
 
 // 创建携带固定上下文的子 logger（自动合并到每条日志）
 const reqLogger = core.logger.child({ requestId: 'req-001' })
-reqLogger.info('Request started') // 日志中自动包含 requestId
+reqLogger.debug('Request started') // 日志中自动包含 requestId
 
 // 配置输出格式和级别
 core.logger.configure({
@@ -204,16 +204,7 @@ core.logger.setLevel('debug')
 const level = core.logger.getLevel() // 'debug'
 ```
 
-**日志级别规范**：
-
-| 级别    | 适用场景                           |
-| ------- | ---------------------------------- |
-| `trace` | 循环内详细调试数据                 |
-| `debug` | 函数进入、参数概要、读操作         |
-| `info`  | 业务事件（初始化完成、写操作成功） |
-| `warn`  | 异常但可恢复（校验失败、重试）     |
-| `error` | 操作失败（需人工排查）             |
-| `fatal` | 致命错误（服务无法继续）           |
+日志级别、业务错误处理和字段选择见 [日志与错误诊断](../hai-app-create/logging.md)。
 
 ### 国际化 — `core.i18n`
 

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

@@ -206,8 +206,8 @@ const sharedServer = crypto.transport.createServer({
 
 使用流程：
 1. 先 `await crypto.init()`。
-2. 服务端显式传入受管 serverKeyRing 和共享 keyStore，协商返回 `serverKeyId + serverPublicKey + clientId`。
-3. 客户端 `createClient({ keyExchangeUrl })` 后，首次 `init()` / `encryptedFetch()` 会自动做密钥协商。
+2. 服务端显式传入受管 `serverKeyRing` 和共享 `keyStore`。协商响应包含 `serverKeyId`、`serverPublicKey`、`clientId`、`maxPlaintextBytes` 和可选的 `clientKeyTtlSeconds`。自定义适配器读取 `manager.clientKeyTtlSeconds` 填充登记有效期。
+3. 客户端 `createClient({ keyExchangeUrl })` 后，首次使用或登记临近到期时自动协商。并发请求共享握手，协商完成后再发送业务请求。
 4. 所有请求均发送 v2 认证封装；包括 GET/HEAD 和无 input POST，不能只附带 clientId。
 5. 自定义适配器先 await authenticateTransportRequest(manager, request)，再用 manager.encryptResponse(verified.data.context, data, status) 关联响应。
 6. 客户端收到 `X-Encrypted: true` 的响应后自动解密；`destroy()` 可清空当前会话。

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

@@ -98,6 +98,8 @@ Serv/SvelteKit 后端的策略快照、只读挂载、环境覆盖、代理信
 
 ## 自建对象存储直连
 
+签名下载误入静态网站回退或在 SSR/API 网关收到应用 404 时，Nginx 返回独立的 404 提示页。重复失败时，检查生效的 `HAI_STORAGE_PUBLICENDPOINT` 和实际代理路由，再签发新链接验证。升级已有代理规则使用完整交付包，独立静态 Web 镜像从更新后的模板重建。
+
 S3 的内部 endpoint 与预签名 publicEndpoint 分开；后者无默认，填用户可访问的 HTTP(S) origin，不含桶名或网站目录。全栈 Web Nginx 及 SSR/API gateway 将实际桶路径原样代理至 storage，不经过 Serv，保留签名 Host/URI/query，关闭对象缓冲和签名日志。桶与网站/API 路径不能重叠；外层反向代理也须转发桶路径，不能把网站 base 加到签名 URL。跨源 CORS 在 S3 配置，私有桶保持签名授权；外部 S3 不生成本地路由，Local 不开放目录。
 
 自建保留 bucket/region/prefix/publicEndpoint/publicUrl/operationLog。增加 gateway 或改变这些访问配置需全量基线，增量摘要不一致在更新前拒绝；选中范围不改变完整拓扑规划。应用/Storage 增量刷新保留代理 DNS，恢复使用旧发布拓扑。验证真实 S3+Nginx 大文件、Range、PUT、匿名/篡改/过期拒绝，并核对外层日志和回滚；不能用只检查生成字符串代替网络验证。

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

@@ -28,7 +28,7 @@ transport 仅支持 v2：SM2 发送方签名、独立密钥的 Encrypt-then-HMAC
 3. 区分返回 HaiResult 的业务操作与抛 Response/redirect/error 的框架控制流，不吞掉控制流。
 4. 对齐 Cookie/CSRF/transport 与服务端配置，验证匿名、登录、权限拒绝和表单失败。
 
-默认请求日志支持 prerender：查询应从独立 `new URL(event.request.url)` 读取，路径保留 `event.url.pathname`，不为观测读取跟踪 URL 的 search/searchParams 而建立页面依赖或触发静态构建错误。保持默认日志开启、JSON 正文日志默认关闭；查询/可选正文先脱敏再写 trace，正文读取副本，不能消耗业务请求。页面业务确实依赖查询时仍按 SvelteKit 的动态路由条件处理，不用日志绕过来声明业务可静态生成。
+默认请求日志支持 prerender。查询从独立 `new URL(event.request.url)` 统计参数数量，路径保留 `event.url.pathname`。JSON 正文日志默认关闭，显式启用时从请求副本读取并脱敏。页面业务确实依赖查询时按 SvelteKit 的动态路由条件处理。
 
 Kit 自动请求审计与 Serv 一样，仅在请求时发现 audit.isInitialized 才写入；未选 Audit 的站点不因默认 handle 产生未初始化错误。选择 Audit 时检查 init 结果并失败停止启动；显式业务审计仍遵守初始化和事务合同，已就绪模块写入失败必须保留诊断，不能当作可选模块静默跳过。handle 创建早于模块初始化时不能在装配阶段把审计永久禁用。
 
@@ -38,7 +38,7 @@ Kit 自动请求审计与 Serv 一样，仅在请求时发现 audit.isInitialize
 
 业务容量统一配置 transport.maxPlaintextBytes：UTF-8 JSON 明文字节，默认 1 MiB，有效整数范围 1 KiB～64 MiB，请求和响应共用。客户端从握手获取服务端预算，可选本地上限取较小值；resolveTransportBodyLimits 自动推导密文预算为两倍明文加 32 KiB。握手 JSON 16 KiB、公钥 4 KiB、认证头 16 KiB、路径 8 KiB、认证及防重放保持独立。原流超限/取消立即停止、取消并释放 reader；请求 413、响应返回加密的 500 容量错误，客户端识别 TransportBodyTooLargeError / hai:crypto:070。 通过 _kit.yml 的 transport.maxPlaintextBytes 或对应 HAI_*_TRANSPORT_MAXPLAINTEXTBYTES 配置并转发到服务端 transport；重建正文保留 signal 并删除旧长度/编码头。
 
-错误提示与诊断分离：HTTP/UI 边界用 core.error.toPublic，仅公开 i18n 安全消息及 error.traceId；重新翻译后用 core.error.formatMessage 保留关联。ToastContainer 默认只显示可读说明，自动将编号移入排查信息图标，展开后可查看、复制并提供给客户支持或开发人员。前后端日志传完整 Error 和操作上下文，使用同一 requestId/traceId 并脱敏；禁止只写通用错误标题，也不能把 cause/ext/SQL/绑定值直接返回用户。数据库日志保留安全的驱动错误码、消息和堆栈。
+HTTP/UI 边界用 `core.error.toPublic` 公开本地化安全消息和 `error.traceId`，重新翻译后用 `core.error.formatMessage` 保留编号。ToastContainer 可展开查看和复制。HTTP 4xx 记录 `debug`，5xx 记录 `error` 并保留安全的服务端诊断。日志字段和跨层关联按 [日志与错误诊断](../hai-app-create/logging.md)。
 
 ## 按需参考
 

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

@@ -42,7 +42,7 @@ export const handle: Handle = haiHandle
 
 ### 2. SvelteKit API endpoint
 
-业务失败用 `kit.response.fromResult/fromError`，保留安全字段错误、显式 `publicExt` 和 HTTP 状态，内部异常仅进入关联日志；不要在业务 endpoint 手工拼接原始异常。
+业务失败用 `kit.response.fromResult/fromError`，保留安全字段错误、显式 `publicExt` 和 HTTP 状态。4xx 使用 `debug` 记录错误码、状态和追踪编号，5xx 使用 `error` 记录服务端异常诊断。请求日志仅记录查询参数数量。
 
 ```ts
 import { kit } from '@h-ai/kit'

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

@@ -5,7 +5,7 @@
 > `@h-ai/reldb` 提供统一的数据库操作接口，支持 SQLite、PostgreSQL、MySQL，包含 DDL、SQL、CRUD 抽象、事务与分页。
 
 
-派生 `BaseReldbCrudRepository` 的自定义 SQL 方法先检查 `await this.ensureReady()`；构造函数启动自动建表不等于仓库就绪，服务 init 必须等待候选仓库的就绪入口再发布。PostgreSQL 自动提交的单条 `CREATE TABLE/INDEX IF NOT EXISTS` 仅对 `23505/pg_class_relname_nsp_index`（建表还包括 `pg_type_typname_nsp_index`）目录竞争，或建表时 `42710` 且服务端 routine 为 `heap_create_with_catalog` / `TypeCreate` 的行类型竞争重执行一次；重试仍失败则保留错误，DDL 与 SQL 入口一致；事务、业务唯一约束及其他错误不自动重试。初始化连接探测仅对临时 DNS 错误 `EAI_AGAIN` 最多尝试三次，间隔 250/500 ms；不重放业务 SQL。
+派生 `BaseReldbCrudRepository` 的自定义 SQL 方法先检查 `await this.ensureReady()`；构造函数启动自动建表不等于仓库就绪，服务 init 必须等待候选仓库的就绪入口再发布。PostgreSQL 自动提交的单条 `CREATE TABLE/INDEX IF NOT EXISTS` 仅对 `23505/pg_class_relname_nsp_index`（建表还包括 `pg_type_typname_nsp_index`）目录竞争，以及建表时 `42710/heap_create_with_catalog`、`42710/TypeCreate` 或 `42P07/heap_create_with_catalog` 的目录竞争重执行一次。DDL 和 SQL 入口均保留重试后的错误。事务、业务唯一约束及其他错误不自动重试。初始化连接探测仅对临时 DNS 错误 `EAI_AGAIN` 最多尝试三次，间隔 250/500 ms；不重放业务 SQL。
 
 ## 运行环境
 

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

@@ -35,7 +35,7 @@ transport 仅支持 v2：SM2 发送方签名、独立密钥的 Encrypt-then-HMAC
 
 业务容量统一配置 transport.maxPlaintextBytes：UTF-8 JSON 明文字节，默认 1 MiB，有效整数范围 1 KiB～64 MiB，请求和响应共用。客户端从握手获取服务端预算，可选本地上限取较小值；resolveTransportBodyLimits 自动推导密文预算为两倍明文加 32 KiB。握手 JSON 16 KiB、公钥 4 KiB、认证头 16 KiB、路径 8 KiB、认证及防重放保持独立。原流超限/取消立即停止、取消并释放 reader；请求 413、响应返回加密的 500 容量错误，客户端识别 TransportBodyTooLargeError / hai:crypto:070。 通过 _serv.yml 的 transport.maxPlaintextBytes 或对应 HAI_*_TRANSPORT_MAXPLAINTEXTBYTES 配置并转发到服务端 transport；重建正文保留 signal 并删除旧长度/编码头。
 
-错误提示与诊断分离：HTTP/UI 边界用 core.error.toPublic，仅公开 i18n 安全消息及 error.traceId；重新翻译后用 core.error.formatMessage 保留关联。ToastContainer 默认只显示可读说明，自动将编号移入排查信息图标，展开后可查看、复制并提供给客户支持或开发人员。前后端日志传完整 Error 和操作上下文，使用同一 requestId/traceId 并脱敏；禁止只写通用错误标题，也不能把 cause/ext/SQL/绑定值直接返回用户。数据库日志保留安全的驱动错误码、消息和堆栈。
+Procedure 业务失败按公开错误中的归一化 HTTP 状态分类。4xx 以 `debug` 记录错误码和追踪编号，5xx 或未捕获异常由服务端以 `error` 保留脱敏诊断。对外提示由 `core.error.toPublic` 生成。日志字段与跨层关联按 [日志与错误诊断](../hai-app-create/logging.md)。
 
 ## 按需参考
 

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

@@ -25,6 +25,7 @@ description: "实现本地/S3 文件与目录操作、流式读写、checksum
 5. 批量删除核对逐项进度，S3 每批最多 1000 项；HTTP 200 不能代替成功判断。unknown 结果先核对业务状态，避免重删并发新对象；dir.delete 不保证隔离并发写入或清除 S3 历史版本。
 6. 自建 Compose 的桶路径由 Web Nginx 或 SSR/API gateway 直达 storage，下载/Range 不经过 Serv，存储端口和控制台不公开。publicEndpoint 可含入口前缀，Nginx 用原始 request_uri 去前缀且保留编码、Host、签名查询，外层代理不能再剥离；入口可在网站目录内，拒绝 API/资源/健康冲突。新增网关、变更桶/公开地址需全量基线，增量及回滚保持原配置。外部 S3 不生成本地路由，Local 不开放目录。验证大文件、Range、过期/篡改/匿名拒绝、根/前缀路径和增量代理 DNS 刷新；签名 URL 不进入日志或截图。
 7. 同源对象可能包含不可信 HTML；默认代理返回 CSP sandbox/default-src none、nosniff、no-referrer、private/no-store，不用于执行网站脚本。外部 S3/CDN 须配置等价策略。自建 bucket/region 为空时由部署补 hai/us-east-1，不能误写成 Storage Schema 默认值。
+8. 写操作默认以 `debug` 记录，业务操作失败返回原错误并记录 `warn`，初始化、连接及关闭失败记录 `error`。正常日志由 Core 级别过滤。调用方按 [日志与错误诊断](../hai-app-create/logging.md) 保留原因和关联编号。
 
 ## 按需参考
 

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

@@ -35,12 +35,14 @@ root: ./data/storage
 # createBucket: ${HAI_STORAGE_CREATEBUCKET:false}
 # forcePathStyle: false
 # prefix: "${HAI_STORAGE_PREFIX:}"
+# multipart:
+#   partSizeBytes: ${HAI_STORAGE_MULTIPART_PARTSIZEBYTES:5242880}
+#   queueSize: ${HAI_STORAGE_MULTIPART_QUEUESIZE:2}
 # publicUrl: ''
 operationLog:
   read: false # file.get/head/exists, dir.list, presign.getUrl/publicUrl
-  write: false # file.put/delete/deleteMany/copy, dir.delete, presign.putUrl
+  write: true # file.put/delete/deleteMany/copy, dir.delete, presign.putUrl
   maxLength: 1000
-  level: debug # info | debug | trace
 ```
 
 约定环境变量优先于 YAML，例如 `HAI_STORAGE_ROOT`、
@@ -52,7 +54,15 @@ MinIO、RustFS 使用同一个 S3 Provider：配置 `type: s3`、S3 API `endpoin
 
 使用 hai-deploy 的默认自建 S3 配置时，可通过 `hai.json` 的 `deploy.container.s3Engine`（`HAI_DEPLOY_CONTAINER_S3ENGINE`，`rustfs | minio`）选择实现，默认 RustFS。运行环境启用 `HAI_STORAGE_CREATEBUCKET=true` 后由应用初始化 storage 时建桶；部署不再生成独立初始化服务或脚本。自定义外部 S3 默认不建桶，可按凭据权限显式启用。
 
-`operationLog` 在 Local/S3 Provider 的真实 file/dir/presign 操作处输出日志，不要在 `storage-main.ts` 或调用方重复包装。文件内容不会写入日志，上传数据只记录字节长度；`maxLength` 用于截断序列化后的参数，`level` 默认 `debug`。
+`operationLog` 默认记录写操作，读操作需显式开启。操作记录固定为 `debug`，由 Core 日志级别过滤。业务失败返回原错误并记录一次 `warn`，初始化、连接和关闭失败为 `error`。`maxLength` 限制安全摘要的字符数，0 省略摘要。签名直传助手在浏览器记录失败，日志不包含对象键、签名 URL 或文件内容。升级时移除 `operationLog.level` 与 `HAI_STORAGE_OPERATIONLOG_LEVEL`，通过 `HAI_CORE_LOGGING_LEVEL` 设置全局阈值。
+
+S3 服务端流式上传使用 `multipart.partSizeBytes` 和 `multipart.queueSize`，默认 5 MiB 和 2 片。大小为 5 MiB 至 5 GiB 的整数，队列大小为正整数。上述两个环境变量在初始化时覆盖相应字段。每个活跃上传的主要缓冲预算约为片大小乘以并发数。
+
+S3 流式上传用 `error.cause` 获取首次失败，`error.ext?.s3Operation` 查看失败的 S3 操作。若分片清理也失败，从 `error.ext?.cleanupError` 获取清理错误。告警包含可取得的服务端请求编号。
+
+若 `UploadPart` 返回成功但缺少 `ETag`，用 `MissingETag`、分片编号及请求编号定位存储端和网关的响应。
+
+处理 `storage.file.put()` 失败时用 `error.code` 分支，底层原因可用时从 `error.cause` 读取。`ifNoneMatch: '*'` 的目标冲突为 `ALREADY_EXISTS`，文件或输入流读取失败为 `UPLOAD_FAILED`，取消保留 `AbortSignal.reason`。告警记录原因摘要、底层错误码及可用的 HTTP 状态。
 
 ### 2. 初始化与关闭
 

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

@@ -58,7 +58,7 @@ operationLog:
 约定环境变量优先于 YAML，例如 `HAI_VECDB_URL`、
 `HAI_VECDB_APIKEY`、`HAI_VECDB_OPERATIONLOG_LEVEL`。
 
-`operationLog` 在集合/向量操作进入真实 Provider 前输出日志，不要在 `vecdb-main.ts` 或调用方重复包装。`maxLength` 用于截断序列化后的向量、文档和过滤条件，`level` 默认 `debug`。
+`operationLog` 在集合/向量操作进入真实 Provider 前输出日志。日志包含操作类型以及条数、维度、topK、是否有过滤条件等摘要。`maxLength` 限制摘要字符数，0 省略摘要。`level` 默认 `debug`。
 
 ### 2. 初始化与关闭