@h-ai/cli 1.0.0-beta.13 → 1.0.0-beta.15

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "1.0.0-beta.13",
+  "version": "1.0.0-beta.15",
   "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.13",
+    "@h-ai/core": "1.0.0-beta.15",
     "cac": "^7.0.1",
     "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.13",
-    "@h-ai/cache": "1.0.0-beta.13",
-    "@h-ai/crypto": "1.0.0-beta.13",
-    "@h-ai/deploy": "1.0.0-beta.13",
-    "@h-ai/feedback": "1.0.0-beta.13",
-    "@h-ai/iam": "1.0.0-beta.13",
-    "@h-ai/kit": "1.0.0-beta.13",
-    "@h-ai/payment": "1.0.0-beta.13",
-    "@h-ai/reach": "1.0.0-beta.13",
-    "@h-ai/reldb": "1.0.0-beta.13",
-    "@h-ai/storage": "1.0.0-beta.13",
-    "@h-ai/vecdb": "1.0.0-beta.13",
+    "@h-ai/api-client": "1.0.0-beta.15",
+    "@h-ai/cache": "1.0.0-beta.15",
+    "@h-ai/crypto": "1.0.0-beta.15",
+    "@h-ai/deploy": "1.0.0-beta.15",
+    "@h-ai/feedback": "1.0.0-beta.15",
+    "@h-ai/iam": "1.0.0-beta.15",
+    "@h-ai/kit": "1.0.0-beta.15",
+    "@h-ai/payment": "1.0.0-beta.15",
+    "@h-ai/reach": "1.0.0-beta.15",
+    "@h-ai/reldb": "1.0.0-beta.15",
+    "@h-ai/storage": "1.0.0-beta.15",
+    "@h-ai/vecdb": "1.0.0-beta.15",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^26.6.5",
     "@types/prompts": "^2.4.9",

package/templates/apps/api/apps/{{projectName}}-serv/config/_serv.yml.hbs

@@ -57,6 +57,9 @@ cors:
 {{else}}
   maxPlaintextBytes: ${HAI_SERV_TRANSPORT_MAXPLAINTEXTBYTES:1048576}
 {{/if}}
+  # 传输时钟窗口，单位秒；允许领先 0～300 秒，请求有效期 1～600 秒。
+  maxFutureSkewSeconds: ${HAI_SERV_TRANSPORT_MAXFUTURESKEWSECONDS:30}
+  maxRequestAgeSeconds: ${HAI_SERV_TRANSPORT_MAXREQUESTAGESECONDS:300}
   # HAI_SERV_TRANSPORT_ROUTEPLAINTEXTBYTES 可填 JSON 路径映射。
   routePlaintextBytes: {}
   # 单条路径需要更大请求体时填写字节数，* 只匹配一段路径。

package/templates/apps/api/apps/{{projectName}}-serv/src/app.ts.hbs

@@ -48,6 +48,8 @@ export function {{api.serviceAppFactoryName}}(_options: CreateApiServiceAppOptio
 {{/if}}
       keyExchangePath: servConfig.transport.keyExchangePath,
       maxPlaintextBytes: servConfig.transport.maxPlaintextBytes,
+      maxFutureSkewSeconds: servConfig.transport.maxFutureSkewSeconds,
+      maxRequestAgeSeconds: servConfig.transport.maxRequestAgeSeconds,
 {{#if features.feedback}}      routePlaintextBytes: {
         [`${servConfig.http.apiPrefix}/feedback/reports`]: feedbackBudget.maxTransportBytes,
         [`${servConfig.http.apiPrefix}/feedback/reports/*/evidence`]: feedbackBudget.maxTransportBytes,

package/templates/apps/fullstack/apps/{{projectName}}-web/README.md.hbs

@@ -24,6 +24,8 @@
 
 ### 编译、打包与部署
 
+入口 HTML 在主应用前执行 `public/_hai/browser-check/startup.js`。Chrome/Edge 低于 111、Firefox 低于 114、Safari 或 iOS/iPadOS 低于 16.4 时，独立升级页会显示当前版本、最低要求和厂商更新入口。发布时连同该目录的 HTML 和样式一起部署。
+
 ```bash
 # 开发预览，默认端口 {{fullstack.ports.web}}
 pnpm --filter {{projectName}}-web dev

package/templates/apps/fullstack/apps/{{projectName}}-web/index.html.hbs

@@ -5,6 +5,7 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <script id="hai-browser-startup" src="./_hai/browser-check/startup.js"></script>
     <title>{{html fullstack.appName}}</title>
     <link
       rel="icon"

package/templates/apps/fullstack/docs/security-configuration.md.hbs

@@ -7,6 +7,7 @@
 | 文件                                                         | 用途                                               |
 | ------------------------------------------------------------ | -------------------------------------------------- |
 | `packages/{{projectName}}-serv/config/_iam.yml`              | 账号、密码、验证码、锁定、敏感操作、登录限制、会话 |
+| `packages/{{projectName}}-serv/config/_serv.yml`             | API 传输加密及请求时间窗口                          |
 | `packages/{{projectName}}-serv/config/_audit.yml`            | 审计采集、脱敏、保留、备份、告警                   |
 | `packages/{{projectName}}-serv/config/_reach.yml`            | 邮件、短信或通知 API 及通知模板                    |
 | `packages/{{projectName}}-serv/config/_scheduler.yml`        | 已有 Scheduler 的持久化及调度参数                  |
@@ -30,6 +31,8 @@ HAI_AUDIT_BACKUP_ENABLED=true
 
 这里列的是 fullstack 模板默认值，不是所有项目或底层 Schema 的普适限制。
 
+加密请求默认有效 300 秒，允许客户端时间领先服务器最多 30 秒。可在 `_serv.yml` 的 `transport` 下设置 `maxRequestAgeSeconds`（1～600）和 `maxFutureSkewSeconds`（0～300），单位为整数秒。超限时，前端显示校验时的服务器 UTC 时间，提示用户开启设备自动校时或手工修改时间，然后刷新。升级旧版本后，从最后一个旧节点停止处理请求起等待 12 分钟，再把请求有效期调到 300 秒以上。
+
 | 条目                         | fullstack 默认及启用入口                                        | 使用影响                                                 |
 | ---------------------------- | --------------------------------------------------------------- | -------------------------------------------------------- |
 | B03 长期/临时账号            | 用户管理中的账号类型、到期时间                                  | 临时账号必须有未来到期时间；到期后旧会话也不能继续使用   |

package/templates/apps/fullstack/e2e/fullstack.spec.ts.hbs

@@ -78,6 +78,8 @@ for (const scenario of [{ offset: -600_000, width: 1440 }, { offset: 600_000, wi
     await page.goto('./')
     const advice = page.getByRole('alert').filter({ hasText: /同步|synchron|時刻/i })
     await expect(advice).toBeVisible()
+    await expect(advice).toContainText(/\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} UTC/)
+    await expect(advice).toContainText(/请开启设备的自动校时或手工修改时间|set your device time manually|手動で時刻を設定/i)
     await expect(advice).toContainText(/刷新|refresh|再読み込み/i)
     await capture(page, `clock-skew-${scenario.width}.png`, testInfo.outputPath(`clock-skew-${scenario.width}.png`))
     // 校时后由用户明确刷新；不能自动重放之前失败的业务请求。

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_reach.yml.hbs

@@ -23,6 +23,9 @@ providers:
   #   accessKeySecret: ${HAI_REACH_PROVIDERS_1_ACCESSKEYSECRET}
   #   signName: MyApp
   #   endpoint: dysmsapi.aliyuncs.com
+  #   gateway: # 可选；配置后向完整 URL 发送 POST
+  #     url: https://sms-gateway.example.com/dx
+  #     body: {}
   # 自有发送服务：按需将 template.provider 改为 custom。
   # - name: custom
   #   type: api

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_serv.yml.hbs

@@ -62,6 +62,9 @@ transport:
 {{else}}
   maxPlaintextBytes: ${HAI_SERV_TRANSPORT_MAXPLAINTEXTBYTES:1048576}
 {{/if}}
+  # 传输时钟窗口，单位秒；允许领先 0～300 秒，请求有效期 1～600 秒。
+  maxFutureSkewSeconds: ${HAI_SERV_TRANSPORT_MAXFUTURESKEWSECONDS:30}
+  maxRequestAgeSeconds: ${HAI_SERV_TRANSPORT_MAXREQUESTAGESECONDS:300}
   # HAI_SERV_TRANSPORT_ROUTEPLAINTEXTBYTES 可填 JSON，例如 {"/api/v1/uploads/*":8388608}。
   routePlaintextBytes: {}
   keyExchangePath: /_hai/key-exchange

package/templates/base/e2e/app.spec.ts.hbs

@@ -17,7 +17,8 @@ async function whileClientBootPaused(page: Page, inspect: () => Promise<void>) {
     resumeClient = resolve
   })
   await page.route('**/*.js', async (route) => {
-    await clientBoot
+    if (!new URL(route.request().url()).pathname.endsWith('/_hai/browser-check/startup.js'))
+      await clientBoot
     await route.continue()
   })
   try {

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.13",
+  "version": "1.0.0-beta.15",
   "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/base/src/app.html.hbs

@@ -13,6 +13,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <script id="hai-browser-startup" src="%sveltekit.assets%/_hai/browser-check/startup.js"></script>
     <link rel="icon" href="%sveltekit.assets%/favicon.png" />
     <script>
       ;(function () {

package/templates/shared/browser-check/startup.js

@@ -0,0 +1,89 @@
+/* eslint-disable no-var, object-shorthand, prefer-template, prefer-arrow-callback -- 此脚本须在低版本浏览器中直接执行，使用 ES5 语法。 */
+;(function () {
+  var agent = navigator.userAgent
+  var root = document.documentElement
+  var location = window.location
+  var edgeHelp = 'https://support.microsoft.com/edge/microsoft-edge-update-settings'
+  var chromeHelp = 'https://support.google.com/chrome/answer/95414'
+  var firefoxHelp = 'https://support.mozilla.org/kb/update-firefox-latest-release'
+  var safariHelp = 'https://support.apple.com/102665'
+  var iosHelp = 'https://support.apple.com/118575'
+  var browser = getOutdatedBrowser()
+
+  // 匹配 Vite 8 的默认构建基线。Edge 的 UA 同时包含 Chrome，iOS 先按系统版本判断。
+  function getOutdatedBrowser() {
+    var version = /\b(?:CPU (?:iPhone )?OS|iPhone OS) (\d+_\d+(?:_\d+)?)/.exec(agent)
+    if (version && /\b(?:iPhone|iPad|iPod)\b/.test(agent)) {
+      return outdated('iOS / iPadOS', version, 16, 4, iosHelp)
+    }
+    version = /\b(?:EdgA?|Edge)\/(\d+(?:\.\d+)*)/.exec(agent)
+    if (version) {
+      return outdated('Microsoft Edge', version, 111, 0, edgeHelp)
+    }
+    version = /\bFirefox\/(\d+(?:\.\d+)*)/.exec(agent)
+    if (version) {
+      return outdated('Firefox', version, 114, 0, firefoxHelp)
+    }
+    version = /\bChrome\/(\d+(?:\.\d+)*)/.exec(agent)
+    if (version) {
+      if (/\b(?:wv|OPR\/|SamsungBrowser\/|Vivaldi\/|YaBrowser\/|HeadlessChrome\/)/.test(agent))
+        return null
+      return outdated('Google Chrome', version, 111, 0, chromeHelp)
+    }
+    version = /\bVersion\/(\d+(?:\.\d+)*)/.exec(agent)
+    if (version && /\bSafari\//.test(agent)) {
+      return outdated('Safari', version, 16, 4, safariHelp)
+    }
+    return null
+  }
+
+  function outdated(name, match, major, minor, help) {
+    var version = match[1].replace(/_/g, '.')
+    var parts = version.split('.')
+    var currentMajor = Number(parts[0])
+    var currentMinor = Number(parts[1] || 0)
+    if (currentMajor > major || (currentMajor === major && currentMinor >= minor))
+      return null
+    return { name: name, version: version, minimum: minor ? major + '.' + minor : String(major), help: help }
+  }
+
+  function getLanguage(value) {
+    var language = (value || '').toLowerCase().split(/[-_]/)[0]
+    return language === 'zh' || language === 'ja' || language === 'en' ? language : ''
+  }
+
+  function openUpdatePage() {
+    // 以静态脚本地址为基准，保留发布目录。仅传语言，不把原页面地址写到升级页。
+    var script = document.getElementById('hai-browser-startup')
+    var language = getLanguage(root.lang) || getLanguage(navigator.language) || 'en'
+    location.replace(script.src.replace(/\/startup\.js$/, '/update.html') + '#' + language)
+  }
+
+  function showUpdateInstructions() {
+    var locale = getLanguage(location.hash.slice(1)) || getLanguage(navigator.language) || 'en'
+    var messages = {
+      zh: ['浏览器版本过低', '当前使用 {name} {version}。此站点至少需要 {name} {minimum}。', '请更新到最新版本，然后重新打开此站点。', '查看官方更新说明'],
+      en: ['Update your browser', 'You are using {name} {version}. This site requires {name} {minimum} or later.', 'Install the latest update, then reopen this site.', 'Official update instructions'],
+      ja: ['ブラウザーを更新してください', '現在のバージョンは {name} {version} です。このサイトには {name} {minimum} 以降が必要です。', '最新版に更新してから、このサイトを開き直してください。', '公式の更新手順を見る'],
+    }
+    var message = messages[locale]
+    var help = document.getElementById('browser-update-help')
+    root.lang = locale === 'zh' ? 'zh-CN' : locale
+    document.title = message[0]
+    document.getElementById('browser-update-title').textContent = message[0]
+    document.getElementById('browser-update-version').textContent = message[1].replace(/\{(name|version|minimum)\}/g, function (_match, key) {
+      return browser[key]
+    })
+    document.getElementById('browser-update-instruction').textContent = message[2]
+    help.textContent = message[3]
+    help.href = browser.help
+    help.hidden = false
+  }
+
+  if (!browser)
+    return
+  if (root.hasAttribute('data-hai-browser-update'))
+    showUpdateInstructions()
+  else
+    openUpdatePage()
+})()

package/templates/shared/browser-check/update.css

@@ -0,0 +1,37 @@
+body {
+  margin: 0;
+  padding: 12vh 20px 32px;
+  background: #f4f6fa;
+  color: #1b263b;
+  font-family: system-ui, sans-serif;
+  font-size: 1rem;
+  line-height: 1.6;
+}
+
+main {
+  max-width: 33rem;
+  margin: 0 auto;
+  padding: 1.5rem;
+  border: 1px solid #dce2ec;
+  border-radius: 0.75rem;
+  background: #fff;
+}
+
+h1 {
+  margin: 0 0 1rem;
+  font-size: 1.5rem;
+  line-height: 1.25;
+}
+
+p {
+  margin: 0 0 0.75rem;
+}
+
+a {
+  color: #1642a3;
+}
+
+a:focus {
+  outline: 2px solid currentColor;
+  outline-offset: 4px;
+}

package/templates/shared/browser-check/update.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en" data-hai-browser-update>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="robots" content="noindex" />
+    <title>Browser requirements</title>
+    <link rel="stylesheet" href="./update.css" />
+  </head>
+  <body>
+    <main>
+      <h1 id="browser-update-title">Browser requirements</h1>
+      <p id="browser-update-version">This site requires a current browser.</p>
+      <p id="browser-update-instruction">Install the latest update, then reopen this site.</p>
+      <a id="browser-update-help" rel="noreferrer" hidden></a>
+    </main>
+    <script src="./startup.js"></script>
+  </body>
+</html>

package/templates/shared/browser-startup.spec.ts

@@ -0,0 +1,21 @@
+import { expect, test } from '@playwright/test'
+
+test('old browser sees upgrade instructions without the application bundles', async ({ page }) => {
+  // 只改变浏览器脚本看到的版本，确保检测在客户端执行。
+  await page.addInitScript(() => {
+    Object.defineProperty(navigator, 'userAgent', { get: () => 'Mozilla/5.0 Gecko/20100101 Firefox/113.0' })
+  })
+  await page.route('**/*', async (route) => {
+    const { pathname } = new URL(route.request().url())
+    if (/\.(?:js|css)$/.test(pathname) && !pathname.includes('/_hai/browser-check/'))
+      await route.abort()
+    else
+      await route.continue()
+  })
+  await page.goto('./', { waitUntil: 'commit' })
+  await expect(page).toHaveURL(/\/_hai\/browser-check\/update\.html#(?:zh|en|ja)$/)
+  await expect(page.getByRole('heading', { level: 1 })).toBeVisible()
+  await expect(page.getByRole('main')).toContainText('Firefox 113.0')
+  await expect(page.getByRole('main')).toContainText('Firefox 114')
+  await expect(page.getByRole('link')).toHaveAttribute('href', 'https://support.mozilla.org/kb/update-firefox-latest-release')
+})

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

@@ -29,7 +29,7 @@ description: "接入或排查 @h-ai/api-client typed API、登录 Token、自动
 
 ## 按需参考
 
-serv/kit 对通过请求绑定、签名和 MAC 校验但超出时间窗口的报文返回加密的 HTTP 400 时间错误；客户端抛 `TransportTimeError`（`hai:crypto:071`），提示同步设备和服务器时间后刷新重试。`api-client` 映射为 `VALIDATION_FAILED`，在 `cause.transportCode` 保留该原因。不会自动重放请求或放宽防重放窗口；篡改或未认证报文仍返回通用认证失败。
+Serv/Kit 对通过请求绑定、签名和 MAC 校验但超出时间窗口的请求返回加密的 HTTP 400 错误。客户端抛出 `TransportTimeError`（`hai:crypto:071`），显示校验时的服务器 UTC 时间，提示开启设备的自动校时或手工修改时间后刷新。`serverTime` 为 Unix 毫秒，旧服务端未提供该值时仍显示校时提示。`api-client` 映射为 `VALIDATION_FAILED`，在 `cause.transportCode` 和 `cause.serverTime` 保留诊断信息。
 
 按本次操作读取对应小节；以已安装版本的公开类型核验签名，示例中的业务变量由应用提供。
 

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

@@ -3,7 +3,7 @@
 > `@h-ai/api-client` 是跨端 typed API client。公共 HTTP API 由 `@h-ai/api-contract` 定义，服务端由 `@h-ai/serv` 挂载，客户端直接调用 `apiClient.<domain>.<group>.<operation>()`。
 
 
-认证协议仅支持 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 秒；共享 registry 原子消费 (clientId, requestId)，nonce 至少保留到 issuedAt + 6 分钟以覆盖节点偏差，存储故障拒绝请求。Redis 必须保留有效 nonce，使用 noeviction/可靠持久化策略；各节点时钟须同步。此能力防止同一传输消息重放，业务重试仍需自己的幂等键。
+认证协议仅支持 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/可靠持久化策略；各节点时钟须同步。此能力防止同一传输消息重放，业务重试仍需自己的幂等键。
 
 空 POST 也发送空明文的认证封装；GET/HEAD 将封装放在 X-Hai-Transport 头，204/304/HEAD 等无正文响应也使用同名头承载认证封装。其它请求/响应在 JSON 正文承载封装并带 X-Encrypted: true。客户端必须关联原请求上下文和 HTTP status，缺标记、旧格式或认证失败一律 reject；明文接口由 Serv/Kit 路径规则 `encryption: disabled` 或宿主 `excludePaths` 显式允许；调用方同步选择普通请求，API Client/Kit 包装器使用自己的 `excludePaths`。CORS 须允许并暴露 X-Hai-Transport。握手公钥的真实性依赖 TLS，不替代 IAM 业务授权。
 

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

@@ -26,6 +26,8 @@ README 编辑先读章节，把功能说明与示例合并到对应章节；新
 
 website默认SSR；静态发布须先移除服务端业务依赖、初始化及API/actions。静态构建与实际路径验证按[hai-build](../hai-build/SKILL.md)。
 
+admin、website、h5 和 Fullstack Web 在入口 HTML 加载 `_hai/browser-check/startup.js` 后才进入应用。检测到 Chrome/Edge 低于 111、Firefox 低于 114、Safari 或 iOS/iPadOS 低于 16.4 时，浏览器跳转到同目录的静态升级页。保留经典脚本标签和静态资源，验证根目录和发布子目录都能在应用包加载失败时显示升级提示。
+
 网站挂载到`/yyy/`等目录时，按[网站挂载目录](../hai-build/paths.md)同步资源、链接、认证端点和服务端守卫。SvelteKit在编译时固定base，Vite默认相对资源加hash导航；API基址单独配置。SDK子目录制品使用格式5，健康与增量检查随制品处理，不手工修改旧格式清单来代替重新构建。
 
 页面共用根布局的 header/footer。独立移动应用的页面放在 `src/lib/pages/**/*.svelte`，Fullstack 放在 `packages/<name>-shared/src/lib/pages/**/*.svelte`，由 `HashRouter` 和 `import.meta.glob` 自动发现；新增页面无需修改路由表，菜单按业务配置入口。SvelteKit 保留 `src/routes/**/+page.svelte` 自动文件路由、服务端鉴权和刷新定位。

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

@@ -5,7 +5,7 @@ description: "实现 SM2/SM3/SM4 加解密、验签、密码哈希，或通过 s
 
 # hai-crypto
 
-transport 仅支持 v2：SM2 发送方签名、独立密钥的 Encrypt-then-HMAC、HTTP 上下文/响应状态绑定及共享原子防重放。GET/HEAD、空 POST 与空响应也认证；无降级开关。TLS 信任边界、5 分钟窗口、nonce 持久化与实现示例见 [参考](reference.md)。
+transport 仅支持 v2：SM2 发送方签名、独立密钥的 Encrypt-then-HMAC、HTTP 上下文/响应状态绑定及共享原子防重放。GET/HEAD、空 POST 与空响应也认证；无降级开关。TLS 信任边界、可配时间窗口、nonce 持久化与实现示例见 [参考](reference.md)。
 
 ## 能力契约
 
@@ -32,7 +32,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。 自定义适配器使用 manager.bodyLimits 和 readTransportBody 消费原流，不 clone/tee；握手返回 maxPlaintextBytes。
 
-serv/kit 对通过请求绑定、签名和 MAC 校验但超出时间窗口的报文返回加密的 HTTP 400 时间错误；客户端抛 `TransportTimeError`（`hai:crypto:071`），提示同步设备和服务器时间后刷新重试。`api-client` 映射为 `VALIDATION_FAILED`，在 `cause.transportCode` 保留该原因。不会自动重放请求或放宽防重放窗口；篡改或未认证报文仍返回通用认证失败。
+Serv/Kit 对通过请求绑定、签名和 MAC 校验但超出时间窗口的请求返回加密的 HTTP 400 错误。客户端抛出 `TransportTimeError`（`hai:crypto:071`），显示校验时的服务器 UTC 时间，提示开启设备的自动校时或手工修改时间后刷新。`serverTime` 为 Unix 毫秒，旧服务端未提供该值时仍显示校时提示。`api-client` 映射为 `VALIDATION_FAILED`，在 `cause.transportCode` 和 `cause.serverTime` 保留诊断信息。
 
 ## 按需参考
 

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

@@ -3,7 +3,7 @@
 > `@h-ai/crypto` 提供非对称加密、哈希、对称加密与密码哈希能力，支持 Node.js 与浏览器双端。
 
 
-认证协议仅支持 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 秒；共享 registry 原子消费 (clientId, requestId)，nonce 至少保留到 issuedAt + 6 分钟以覆盖节点偏差，存储故障拒绝请求。Redis 必须保留有效 nonce，使用 noeviction/可靠持久化策略；各节点时钟须同步。此能力防止同一传输消息重放，业务重试仍需自己的幂等键。
+认证协议仅支持 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/可靠持久化策略；各节点时钟须同步。此能力防止同一传输消息重放，业务重试仍需自己的幂等键。
 
 空 POST 也发送空明文的认证封装；GET/HEAD 将封装放在 X-Hai-Transport 头，204/304/HEAD 等无正文响应也使用同名头承载认证封装。其它请求/响应在 JSON 正文承载封装并带 X-Encrypted: true。客户端必须关联原请求上下文和 HTTP status，缺标记、旧格式或认证失败一律 reject；明文接口由 Serv/Kit 路径规则 `encryption: disabled` 或宿主 `excludePaths` 显式允许；调用方同步选择普通请求，API Client/Kit 包装器使用自己的 `excludePaths`。CORS 须允许并暴露 X-Hai-Transport。握手公钥的真实性依赖 TLS，不替代 IAM 业务授权。
 
@@ -233,7 +233,7 @@ const manager = crypto.transport.createServer({ serverKeyRing: ring.data, keySto
 
 业务容量统一配置 transport.maxPlaintextBytes：UTF-8 JSON 明文字节，默认 1 MiB，有效整数范围 1 KiB～64 MiB，请求和响应共用。客户端从握手获取服务端预算，可选本地上限取较小值；resolveTransportBodyLimits(limit, { requiredPlaintextBytes }) 合并模块需求：保留显式上限，不足时报配置冲突；省略时按需要推导，无模块需要仍为 1 MiB。Serv/Kit 的 auto 规范化为 undefined。密文预算为两倍明文加 32 KiB。握手 JSON 16 KiB、公钥 4 KiB、认证头 16 KiB、路径 8 KiB、认证及防重放保持独立。原流超限/取消立即停止、取消并释放 reader；请求 413、响应返回加密的 500 容量错误，客户端识别 TransportBodyTooLargeError / hai:crypto:070。 自定义适配器使用 manager.bodyLimits 和 readTransportBody 消费原流，不 clone/tee；握手返回 maxPlaintextBytes。
 
-serv/kit 对通过请求绑定、签名和 MAC 校验但超出时间窗口的报文返回加密的 HTTP 400 时间错误；客户端抛 `TransportTimeError`（`hai:crypto:071`），提示同步设备和服务器时间后刷新重试。`api-client` 映射为 `VALIDATION_FAILED`，在 `cause.transportCode` 保留该原因。不会自动重放请求或放宽防重放窗口；篡改或未认证报文仍返回通用认证失败。
+Serv/Kit 对通过请求绑定、签名和 MAC 校验但超出时间窗口的请求返回加密的 HTTP 400 错误。客户端抛出 `TransportTimeError`（`hai:crypto:071`），显示校验时的服务器 UTC 时间，提示开启设备的自动校时或手工修改时间后刷新。`serverTime` 为 Unix 毫秒，旧服务端未提供该值时仍显示校时提示。`api-client` 映射为 `VALIDATION_FAILED`，在 `cause.transportCode` 和 `cause.serverTime` 保留诊断信息。
 
 自定义 HTTP 适配器检查失败原因 `error instanceof TransportTimeError && error.context` 后，使用 `createTransportErrorResponse(error, { manager, context: error.context })` 加密拒绝响应；不能根据未认证报文的时间戳给出可信时间诊断。
 

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

@@ -7,7 +7,7 @@ description: "在 SvelteKit 中接入 hooks、认证守卫、输入校验、响
 
 限流采用首次成功提交为起点的固定窗口，后续请求不延长 TTL。必须显式传 store；应用先检查共享 Redis 初始化结果，所有节点使用相同 namespace/windowMs/maxRequests。缓存读取/条件提交失败或冲突耗尽返回503，超限429；不会回退 get+set 或本地计数。createMemoryRateLimitStore 仅开发或显式 HAI_E2E/HAI_E2E_MOCK 测试使用，无常驻定时器，丢弃引用即可回收；每次请求最多惰性扫描 64 项，最多保存 10000 个窗口，容量满时对新 key 返回503且不驱逐有效计数，外部 store 生命周期由创建者管理；生产不得设置测试开关。响应重置时间为节点时钟估算，实际窗口由 Redis TTL 决定，须同步时钟。默认键只读取可信 adapter 的 getClientAddress、规范化等价IPv6和IPv4映射地址，不采信原始转发头；代理信任通过部署adapter配置。
 
-transport 仅支持 v2：SM2 发送方签名、独立密钥的 Encrypt-then-HMAC、HTTP 上下文/响应状态绑定及共享原子防重放。GET/HEAD、空 POST 与空响应也认证；无降级开关。TLS 信任边界、5 分钟窗口、nonce 持久化与实现示例见 [参考](reference.md)。
+transport 仅支持 v2：SM2 发送方签名、独立密钥的 Encrypt-then-HMAC、HTTP 上下文/响应状态绑定及共享原子防重放。GET/HEAD、空 POST 与空响应也认证；无降级开关。TLS 信任边界、可配时间窗口、nonce 持久化与实现示例见 [参考](reference.md)。
 
 ## 能力契约
 

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

@@ -2,7 +2,9 @@
 
 > `@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。
 
-认证协议仅支持 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 秒；共享 registry 原子消费 (clientId, requestId)，nonce 至少保留到 issuedAt + 6 分钟以覆盖节点偏差，存储故障拒绝请求。Redis 必须保留有效 nonce，使用 noeviction/可靠持久化策略；各节点时钟须同步。此能力防止同一传输消息重放，业务重试仍需自己的幂等键。
+认证协议仅支持 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 展示。
 
 空 POST 也发送空明文的认证封装；GET/HEAD 将封装放在 X-Hai-Transport 头，204/304/HEAD 等无正文响应也使用同名头承载认证封装。其它请求/响应在 JSON 正文承载封装并带 X-Encrypted: true。客户端必须关联原请求上下文和 HTTP status，缺标记、旧格式或认证失败一律 reject；明文接口由 Serv/Kit 路径规则 `encryption: disabled` 或宿主 `excludePaths` 显式允许；调用方同步选择普通请求，API Client/Kit 包装器使用自己的 `excludePaths`。CORS 须允许并暴露 X-Hai-Transport。握手公钥的真实性依赖 TLS，不替代 IAM 业务授权。
 

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

@@ -21,6 +21,7 @@ API 空 2xx 表示受理成功；非空 JSON 回执上限 64 KiB。redirect 默
 
 - 先配置并注册 Provider，再保存绑定 Provider 的模板；模板发送只传 template/to/vars 即可，显式 provider 可覆盖；直接发送须提供 provider。启用 DND delay 必须先初始化 reldb 并确保队列表可用；成功时 `deferred: true` 与 `queueId` 表示可靠入队，尚未投递；缺库、断连或插入失败须按 HaiResult 失败处理。即时投递与排队状态须区分。
 - 验证模板替换和错误分支时使用隔离测试收件人；真实通知须在用户授权范围内。
+- 阿里云短信的 `gateway` 通过 POST 转发已签名查询，可配置请求头和正文；服务端 `reach.init` 可按 Provider 名注入 `gatewayHooks`。受信内网 HTTP 须显式启用，转发日志应脱敏查询串。
 - 缓存锁只减少扫描，按实际执行逐条领取并在途续租。API 只有接收端真正具备原子持久去重时才能声明 idempotent=true，全部请求固定用 queueId 作为 Idempotency-Key；旧节点迟到请求也必须去重。SMTP/短信/默认 API 的在途失败或过期转 unknown，禁止自动重发；可信服务端用 queue.get/resolveUnknown 在人工隔离旧 worker、核对外部记录后裁定 sent/discarded。
 - queue 重试策略随消息持久保存，默认最多领取 5 次，指数退避 60 秒至 1 小时；永久失败/超限进 dead，满批失败不会原地自旋。可信服务端用 queue.list 查询 dead/unknown；修复根因后以最新 updatedAt 调用 requeueDead，只能恢复 dead，保留同一 queueId 和接收端幂等要求。unknown 不能重排。
 

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

@@ -47,6 +47,10 @@ providers:
     accessKeyId: ${HAI_REACH_PROVIDERS_0_ACCESSKEYID:}
     accessKeySecret: ${HAI_REACH_PROVIDERS_0_ACCESSKEYSECRET:}
     signName: ${HAI_REACH_PROVIDERS_0_SIGNNAME:}
+    # 按需启用隔离网关
+    # gateway:
+    #   url: https://sms-gateway.example.com/dx
+    #   body: {}
   - name: webhook
     type: api
     url: ${HAI_REACH_WEBHOOK_URL:}
@@ -165,13 +169,21 @@ await reach.send({
 })
 ```
 
+### 隔离网关与动态字段
+
+在 `aliyun-sms` 下配置 `gateway.url`，使用包含路径的完整 HTTPS 地址。受信内网确需明文时设置 `gateway.allowInsecureHttp: true`。请求使用 POST，阿里云签名仍基于 RPC 路径 `/` 和查询参数，网关路径、头和正文仅供网关使用。`gateway.headers` 取字符串键值，`gateway.body` 可设 JSON 对象、数组或原始文本，`body: {}` 表示空 JSON 对象。
+
+从服务端 `reach.init(config, { gatewayHooks: { sms: hook } })` 注入同步或异步函数。`sms` 对应已配置网关的 Provider 名称，`hook` 接收 `{ method, url, body, signal }`，其中 `body` 已序列化，`url` 含签名和敏感查询。返回 `{ headers, body }` 时，头按名称忽略大小写覆盖，正文整段替换，省略字段时沿用静态配置。`Host` 和 `Content-Length` 等由 HTTP 客户端管理。函数和请求共用 10 秒期限，拒绝重定向。`reach.config` 仅展示网关的地址和 HTTP 开关。
+
+验证网关转发时确认上游路径、方法和查询参数，HTTP 2xx 且阿里云 `Code: OK` 表示已受理，送达状态通过 `BizId` 查询。明文连接的访问日志应脱敏查询串，配置及测试均使用占位数据或受控的私有注入。
+
 ## 核心 API
 
 ### reach 对象
 
 | 方法 / 属性           | 签名                                                     | 说明                               |
 | --------------------- | -------------------------------------------------------- | ---------------------------------- |
-| `reach.init`          | `(config: ReachConfigInput) => Promise<HaiResult<void>>`    | 初始化（注册多个 Provider）        |
+| `reach.init`          | `(config: ReachConfigInput, options?: ReachInitOptions) => Promise<HaiResult<void>>` | 初始化 Provider，可注入网关函数 |
 | `reach.send`          | `(message: ReachMessage) => Promise<HaiResult<SendResult>>` | 发送消息（通过 provider 字段路由） |
 | `reach.queue.get` | `(queueId: string) => Promise<HaiResult<ReachQueueEntry \| null>>` | 不含正文/收件人的队列状态 |
 | `reach.queue.list` | `(options: ReachQueueListOptions) => Promise<HaiResult<ReachQueueEntry[]>>` | 可信服务端分页查询 dead/unknown，每页至多 100 条 |

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

@@ -5,7 +5,7 @@ description: "为独立 API 服务装配 contract/procedures、认证守卫、No
 
 # hai-serv
 
-transport 仅支持 v2：SM2 发送方签名、独立密钥的 Encrypt-then-HMAC、HTTP 上下文/响应状态绑定及共享原子防重放。GET/HEAD、空 POST 与空响应也认证；无降级开关。TLS 信任边界、5 分钟窗口、nonce 持久化与实现示例见 [参考](reference.md)。
+transport 仅支持 v2：SM2 发送方签名、独立密钥的 Encrypt-then-HMAC、HTTP 上下文/响应状态绑定及共享原子防重放。GET/HEAD、空 POST 与空响应也认证；无降级开关。TLS 信任边界、可配时间窗口、nonce 持久化与实现示例见 [参考](reference.md)。
 
 ## 能力契约
 

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

@@ -287,7 +287,9 @@ transport:
     - /_hai/scalar.js
 ```
 
-认证协议仅支持 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 秒；共享 registry 原子消费 (clientId, requestId)，nonce 至少保留到 issuedAt + 6 分钟以覆盖节点偏差，存储故障拒绝请求。Redis 必须保留有效 nonce，使用 noeviction/可靠持久化策略；各节点时钟须同步。此能力防止同一传输消息重放，业务重试仍需自己的幂等键。
+认证协议仅支持 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/可靠持久化策略；各节点时钟须同步。此能力防止同一传输消息重放，业务重试仍需自己的幂等键。
+
+在 `_serv.yml` 的 `transport` 块配置时间窗口，将字段传给服务端 transport 装配。完成旧节点升级后等待 12 分钟，再把有效期调到 300 秒以上。校时提示与 `TransportTimeError.serverTime` 见 [Crypto 参考](../hai-crypto/reference.md)。
 
 空 POST 也发送空明文的认证封装；GET/HEAD 将封装放在 X-Hai-Transport 头，204/304/HEAD 等无正文响应也使用同名头承载认证封装。其它请求/响应在 JSON 正文承载封装并带 X-Encrypted: true。客户端必须关联原请求上下文和 HTTP status，缺标记、旧格式或认证失败一律 reject；明文接口由 Serv/Kit 路径规则 `encryption: disabled` 或宿主 `excludePaths` 显式允许；调用方同步选择普通请求，API Client/Kit 包装器使用自己的 `excludePaths`。CORS 须允许并暴露 X-Hai-Transport。握手公钥的真实性依赖 TLS，不替代 IAM 业务授权。
 

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

@@ -33,7 +33,7 @@ Toast 支持 F8 聚焦/返回、Escape 关闭可关闭提示并恢复焦点；Mo
 
 状态层可从轻量 `@h-ai/ui/i18n` 导入同一个 `authErrorMessage`，避免加载场景组件；管理台、移动/桌面示例与模板保持一致。
 
-认证错误复用公开 `authErrorMessage(error)`（从 `@h-ai/ui/components/scenes/iam/index` 导入）：凭据错误统一，不显示未知原文，保留有效 traceId 供排查图标展开；首次/到期改密、密码复用 034 和会话上限有明确指引。AuthPanel 与敏感操作确认已内置；自定义改密复用此映射。确认密码按原始字符串比较，不裁剪或 Unicode 归一化；字段错误、操作成功和认证错误均使用统一 Toast，字段保留定位与无障碍关联。
+认证错误复用公开 `authErrorMessage(error)`（从 `@h-ai/ui/components/scenes/iam/index` 导入）：凭据错误统一，不显示未知原文，保留有效 traceId 供排查图标展开；首次/到期改密、密码复用 034 和会话上限有明确指引。AuthPanel 与敏感操作确认已内置；自定义改密复用此映射。确认密码按原始字符串比较，不裁剪或 Unicode 归一化；字段错误、操作成功和认证错误均使用统一 Toast，字段保留定位与无障碍关联。Kit 和 API Client 的已认证传输时间诊断会在认证提示中显示服务器 UTC 时间及校时建议。
 
 新页面或较大改版先使用 [hai-ui-design](../hai-ui-design/SKILL.md) 确定任务、布局、状态和组件映射；本 skill 负责正确实现。完成后按 [hai-ui-review](../hai-ui-review/SKILL.md) 查看真实页面，小范围修复沿用已有设计。