@h-ai/cli 0.1.0-alpha.66 → 0.1.0-alpha.68

package/templates/features/payment/routes/api/v1/payment/create/+server.ts

@@ -1,38 +1,31 @@
-/**
- * 创建支付订单 API
- */
+/** 创建支付参数 API；渠道、场景与 openid 必须通过显式校验，禁止回落到其它支付模式。 */
 import type { RequestHandler } from './$types'
 import { kit } from '@h-ai/kit'
 import { payment } from '@h-ai/payment'
+import { z } from 'zod'
 
-export const POST: RequestHandler = async ({ request, locals }) => {
-  const body = await request.json()
-  const { provider, tradeType, outTradeNo, totalAmount, subject, notifyUrl, userId, metadata } = body
-
-  if (!provider || !outTradeNo || !totalAmount || !subject) {
-    return kit.response.badRequest('Missing required fields: provider, outTradeNo, totalAmount, subject')
-  }
-
-  const normalizedTradeType = tradeType === 'h5'
-    || tradeType === 'app'
-    || tradeType === 'native'
-    || tradeType === 'mini_program'
-    ? tradeType
-    : 'jsapi'
+/** 本模板的业务字段；服务端仍需从可信订单重新核对金额、描述、订单号和所属用户。 */
+const CreatePaymentSchema = z.object({
+  provider: z.enum(['wechat', 'alipay', 'stripe']),
+  tradeType: z.enum(['jsapi', 'h5']),
+  outTradeNo: z.string().min(1),
+  totalAmount: z.number().int().positive(),
+  subject: z.string().min(1),
+  userId: z.string().trim().min(1).max(128).optional(),
+  metadata: z.record(z.string(), z.string()).optional(),
+  notifyUrl: z.url({ protocol: /^https?$/ }).optional(),
+}).strict().refine(input => input.tradeType === (input.provider === 'wechat' ? 'jsapi' : 'h5'), { path: ['tradeType'] }).refine(input => input.provider !== 'wechat' || input.userId !== undefined, { path: ['userId'] })
 
+export const POST: RequestHandler = async ({ request, locals }) => {
+  const { provider, tradeType, outTradeNo, totalAmount, subject, notifyUrl, userId, metadata } = await kit.validate.body(request, CreatePaymentSchema)
   const result = await payment.createOrder(provider, {
     orderNo: outTradeNo,
-    amount: Number(totalAmount),
+    amount: totalAmount,
     description: subject,
-    tradeType: normalizedTradeType,
+    tradeType,
     userId,
     metadata,
     notifyUrl: notifyUrl ?? `${new URL(request.url).origin}/api/v1/payment/notify/${provider}`,
   })
-
-  if (!result.success) {
-    return kit.response.internalError(result.error.message)
-  }
-
-  return kit.response.ok(result.data, locals.requestId)
+  return kit.response.fromResult(result, locals.requestId)
 }

package/templates/features/payment/routes/api/v1/payment/notify/[provider]/+server.ts

@@ -30,6 +30,10 @@ export const POST: RequestHandler = async ({ request, params }) => {
     return new Response('FAIL', { status: 500 })
   }
 
+  // 此模板仅确认已验签解析；success 不代表已付款，Stripe 延迟付款会返回 pending。
+  // 业务接入时须在响应成功前，用共享数据库核对订单/金额/币种，按 eventId 去重并防止状态倒退；
+  // 仅 status=paid 可触发履约，不在进程内 Set/Map 中维护通知去重。
+
   // 微信支付要求返回 JSON，支付宝要求返回 "success"
   if (provider === 'wechat') {
     return new Response(JSON.stringify({ code: 'SUCCESS', message: '' }), {

package/templates/i18n/project.inlang/settings.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://inlang.com/schema/project-settings",
   "baseLocale": "zh-CN",
-  "locales": ["zh-CN", "en-US"],
+  "locales": ["zh-CN", "en-US", "ja-JP"],
   "modules": [
     "./node_modules/@inlang/plugin-message-format/dist/index.js"
   ],

package/templates/shared/.gitattributes

@@ -3,3 +3,9 @@
 *.sh.hbs text eol=lf
 *.envsh text eol=lf
 *.envsh.hbs text eol=lf
+
+# Linux 容器引擎读取忽略规则和构建文件时统一使用 LF。
+.dockerignore text eol=lf
+*.dockerignore text eol=lf
+Dockerfile text eol=lf
+*.Dockerfile text eol=lf

package/templates/shared/e2e-env.ts

@@ -0,0 +1,98 @@
+import { createECDH } from 'node:crypto'
+import { isAbsolute } from 'node:path'
+import process from 'node:process'
+
+/**
+ * 仅给 Playwright 的服务子进程装配环境；不修改测试进程和 pnpm/Turbo 的环境。
+ * @param profile - 本轮测试明确选择的模块配置和可信控制值。
+ * @returns Playwright webServer.env；undefined 项由 Node spawn 从子进程环境中移除。
+ * @throws 缺少绝对数据目录，或 API 指向非本轮 loopback HTTP 夹具时抛错。
+ * @example
+ * ```ts
+ * // 测试内部上下文；数据目录由 run-e2e 为本轮分配。
+ * const env = createE2eServerEnv({
+ *   HAI_E2E_DATA_ROOT: process.cwd(),
+ *   HAI_CACHE: JSON.stringify({ type: 'memory' }),
+ * })
+ * if (env.HAI_E2E !== '1') throw new Error('E2E profile was not applied')
+ * ```
+ */
+export function createE2eServerEnv(profile: Record<string, string>): Record<string, string> {
+  const dataRoot = profile.HAI_E2E_DATA_ROOT || process.env.HAI_E2E_DATA_ROOT
+  if (!dataRoot || !isAbsolute(dataRoot))
+    throw new Error('Run E2E through the managed entrypoint with its own absolute HAI_E2E_DATA_ROOT')
+  if (profile.PUBLIC_API_BASE) {
+    const api = new URL(profile.PUBLIC_API_BASE)
+    if (api.protocol !== 'http:' || !['127.0.0.1', 'localhost', '[::1]'].includes(api.hostname) || api.username || api.password)
+      throw new Error('E2E API must use an unauthenticated loopback HTTP fixture')
+  }
+  const environment: Record<string, string | undefined> = Object.fromEntries(
+    Object.keys(process.env).filter(key => /^(?:HAI_|PUBLIC_|VITE_)/i.test(key)).map(key => [key, undefined]),
+  )
+  for (const name of ['HAI_E2E_DATA_ROOT', 'HAI_AUTH_EVIDENCE_DIR', 'HAI_CORE_NAME', 'HAI_CORE_VERSION']) {
+    if (process.env[name] !== undefined)
+      environment[name] = process.env[name]
+  }
+  Object.assign(environment, { HAI_E2E: '1', NODE_ENV: 'test', HAI_E2E_DATA_ROOT: dataRoot }, profile)
+  // Playwright 声明仅接受 string，但其 WebServer 合并 env 后直接交 Node spawn；
+  // 已用安装版真实 WebServer 验证 undefined 会删除继承项，因此仅在第三方类型边界使用窄断言。
+  return environment as Record<string, string>
+}
+
+/**
+ * 每轮生成独立可信 SM2 ring；私钥只传服务子进程，不进入公开配置或报告。
+ * @returns 符合 transport serverKeyRing 配置的 JSON 字符串。
+ * @throws 当前 Node/OpenSSL 不支持 SM2 时抛错，不降级为不可信握手。
+ * @example
+ * ```ts
+ * // 测试内部上下文；仅交给本轮服务子进程。
+ * const env = createE2eServerEnv({
+ *   HAI_E2E_DATA_ROOT: process.cwd(),
+ *   HAI_CRYPTO_TRANSPORT_SERVERKEYRING: createE2eTransportRing(),
+ * })
+ * if (!env.HAI_CRYPTO_TRANSPORT_SERVERKEYRING) throw new Error('Trusted ring is required')
+ * ```
+ */
+export function createE2eTransportRing(): string {
+  const key = createECDH('SM2')
+  key.generateKeys()
+  return JSON.stringify({ activeKeyId: 'e2e-v1', keys: { 'e2e-v1': {
+    publicKey: key.getPublicKey('hex'),
+    privateKey: key.getPrivateKey('hex').padStart(64, '0'),
+  } } })
+}
+
+/**
+ * 只把既有的本轮 loopback 通知夹具控制地址转成明确 Reach 配置。
+ * @returns 未启用通知夹具时为空对象；启用时包含 OTP、模板及协议配置。
+ * @throws IAM_NOTIFICATION_URL 不是无凭据的 loopback HTTP 地址时抛错。
+ * @example
+ * ```ts
+ * // 测试内部上下文；IAM_NOTIFICATION_URL 由样板门禁启动的通知夹具提供。
+ * const env = createE2eServerEnv({
+ *   ...createE2eNotificationEnv(),
+ *   HAI_E2E_DATA_ROOT: process.cwd(),
+ * })
+ * if (env.HAI_E2E !== '1') throw new Error('Notification profile was not isolated')
+ * ```
+ */
+export function createE2eNotificationEnv(): Record<string, string> {
+  const address = process.env.IAM_NOTIFICATION_URL
+  if (!address)
+    return {}
+  const url = new URL(address)
+  if (url.protocol !== 'http:' || !['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname) || url.username || url.password)
+    throw new Error('E2E notification fixture must use an unauthenticated loopback HTTP address')
+  return {
+    HAI_IAM_LOGIN_OTP: 'true',
+    HAI_IAM_PASSWORDRESET_ENABLED: 'true',
+    HAI_REACH_PROVIDERS: JSON.stringify(['email', 'sms'].map(name => ({ name, type: 'api', url: new URL('/send', url).href }))),
+    HAI_REACH_TEMPLATES: JSON.stringify([
+      { name: 'otp_email', provider: 'email', body: 'Code: {code}' },
+      { name: 'otp_sms', provider: 'sms', body: 'Code: {code}' },
+      { name: 'password_reset', provider: 'email', body: 'Reset: {token}' },
+      { name: 'password_reset_sms', provider: 'sms', body: 'Reset: {token}' },
+    ]),
+    HAI_IAM_AGREEMENTS: JSON.stringify({ showOnRegister: true, showOnLogin: true, userAgreementMarkdown: '# Configured registration agreement\n\n**Registration terms**\n\n- Keep your account credentials secure.', userAgreementUrl: new URL('/terms', url).href, privacyPolicyUrl: new URL('/privacy', url).href }),
+  }
+}

package/templates/shared/run-e2e.mjs

@@ -1,4 +1,4 @@
-/** 运行浏览器验收，并在报告写完后清理本次输出；失败和中断同样清理。 */
+/** 运行浏览器验收，保留本轮证据；退出后仅回收本轮服务数据，失败和中断同样处理。 */
 import { spawn } from 'node:child_process'
 import { mkdirSync, mkdtempSync, rmSync } from 'node:fs'
 import { createRequire } from 'node:module'
@@ -21,14 +21,29 @@ for (const argument of process.argv.slice(2)) {
 }
 let child
 let interrupted = false
+let stopping
+/**
+ * 结束本轮 Playwright；Windows 同时结束其进程树，finally 等待该命令退出后才清理数据。
+ * @returns {void} 终止请求由 child 退出事件和 stopping Promise 确认。
+ * @example 模块内部信号处理
+ * ```js
+ * process.once('SIGTERM', stop)
+ * ```
+ */
 function stop() {
   if (interrupted)
     return
   interrupted = true
   if (process.platform === 'win32' && child?.pid && child.exitCode === null) {
     // Windows 的 kill 不传递 SIGTERM；同时结束本次 Playwright 创建的浏览器与服务进程。
-    spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' })
-      .once('error', () => child?.kill())
+    stopping = new Promise((resolve) => {
+      const killer = spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' })
+      killer.once('error', () => {
+        child?.kill()
+        resolve()
+      })
+      killer.once('exit', resolve)
+    })
   }
   else {
     child?.kill()
@@ -37,19 +52,37 @@ function stop() {
 process.once('SIGINT', stop)
 process.once('SIGTERM', stop)
 try {
-  for (const args of groups) {
+  // 证据与临时业务数据分开；每组使用独立输出，后续 Playwright 不会清空前组证据。
+  const evidenceParent = resolve(process.env.HAI_AUTH_EVIDENCE_DIR || join(cwd, 'test-results'))
+  mkdirSync(evidenceParent, { recursive: true })
+  const runRoot = mkdtempSync(join(evidenceParent, 'run-'))
+  for (const [index, args] of groups.entries()) {
+    const groupRoot = join(runRoot, `group-${index + 1}`)
+    const groupDataRoot = join(dataRoot, `group-${index + 1}`)
+    mkdirSync(groupDataRoot)
+    const hasOutput = args.some(argument => argument === '--output' || argument.startsWith('--output='))
+    const outputArgs = hasOutput ? [] : ['--output', join(groupRoot, 'results')]
+    const html = process.env.PLAYWRIGHT_HTML_OUTPUT_DIR || process.env.PLAYWRIGHT_HTML_REPORT
     const code = await new Promise((resolve, reject) => {
-      child = spawn(process.execPath, [cli, 'test', ...args], {
+      child = spawn(process.execPath, [cli, 'test', ...args, ...outputArgs], {
         cwd,
         windowsHide: true,
         stdio: 'inherit',
-        env: { ...process.env, HAI_AUTH_EVIDENCE_DIR: join(cwd, 'test-results/evidence'), HAI_E2E_DATA_ROOT: dataRoot },
+        env: {
+          ...process.env,
+          ...(!html ? { PLAYWRIGHT_HTML_OUTPUT_DIR: join(groupRoot, 'html') } : {}),
+          HAI_AUTH_EVIDENCE_DIR: process.env.HAI_AUTH_EVIDENCE_DIR || join(groupRoot, 'evidence'),
+          HAI_E2E_DATA_ROOT: groupDataRoot,
+        },
       })
       child.once('error', reject)
       child.once('exit', resolve)
     })
-    if (code !== 0 || interrupted) {
-      process.exitCode = typeof code === 'number' && code !== 0 ? code : 1
+    // 配置组互相独立，普通失败继续收集；保留首个失败码，中断才停止后续组。
+    if (code !== 0)
+      process.exitCode ||= typeof code === 'number' && code !== 0 ? code : 1
+    if (interrupted) {
+      process.exitCode ||= 1
       break
     }
   }
@@ -57,9 +90,15 @@ try {
 finally {
   process.removeListener('SIGINT', stop)
   process.removeListener('SIGTERM', stop)
-  // 固定为当前测试工程中的标准输出目录，禁止删除调用方任意指定的路径。
-  for (const name of ['test-results', 'playwright-report'])
-    rmSync(join(cwd, name), { recursive: true, force: true, maxRetries: 3, retryDelay: 100 })
+  await stopping
   // Playwright 退出后服务进程已关闭，此时删除 SQLite / storage，避免 Windows 文件锁。
-  rmSync(dataRoot, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 })
+  try {
+    rmSync(dataRoot, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 })
+  }
+  catch (error) {
+    process.stderr.write(`E2E data cleanup failed: ${error instanceof Error ? error.message : String(error)}\n`)
+    // 清理错误不能把原始失败（如 exit 7）覆盖成另一状态，也不能让成功变为假成功。
+    if (!process.exitCode)
+      process.exitCode = 1
+  }
 }

package/templates/skills/AGENTS.md

@@ -41,7 +41,7 @@
 1. 先搜索现有实现、引用点、测试和 README。
 2. 小步修改，优先保持目录结构、公开 API 和脚本稳定。
 3. 改动公共类型、配置、模板或共享逻辑时，同步更新所有调用方与文档。
-4. 每次改动后按影响范围运行质量门禁并记录结果。
+4. 一轮修改完成后按影响范围收集全部可执行门禁结果，汇总问题再集中修复、复测；普通失败不立即从头重跑。
 
 ## 代码注释与示例
 
@@ -52,7 +52,7 @@
 
 ## 质量门禁
 
-先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。
+先核对 package.json，按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集适用检查与日志，再归并修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。文档检查引用，UI/路由变更加 E2E，未运行项说明原因。
 
 ```bash
 pnpm typecheck
@@ -64,7 +64,7 @@ pnpm test:e2e
 
 ## 完成条件
 
-- typecheck / lint / build / test / test:e2e 状态明确；失败必须先修复或明确说明原因。
+- typecheck / lint / build / test / test:e2e 状态明确；整轮收集后集中修复，最终必需门禁对最终代码有效通过，未执行或阻塞明确原因，不能宣称完成。
 - README、i18n、测试、代码注释与实现保持一致。
 - 最终回复说明执行过的门禁、已同步的文档 / 依赖方，以及未完成项。
 
@@ -75,3 +75,7 @@ pnpm test:e2e
 - `.agents/skills/hai-app-review/SKILL.md`：应用代码审查。
 - `.agents/skills/hai-app-tests/SKILL.md`：Vitest / Playwright 测试策略。
 - 具体模块按需读取对应 `hai-*` Skill。
+
+前端项目已交付对应技能时，先按 hai-ui-design 确定任务、布局、状态与组件映射，使用 hai-ui 实现，再由 hai-ui-review 检查真实页面。窄范围修改复用已有设计；按实际语言/主题/尺寸验证。
+
+工作流技能按 hai-领域-动作 命名，能力使用类沿用领域名。需求、验收、发现与当前版本证据按 [工作交接契约](.agents/skills/hai-spec-implement/handoff.md) 传递，沿既有清单恢复任务。

package/templates/skills/bridges/admin/AGENTS.md

@@ -38,7 +38,7 @@
 
 - 页面组件、layout、load 只负责渲染、权限态拼装和请求编排；业务逻辑放在 `src/lib/server/services` 或模块 API。
 - 认证授权使用 `@h-ai/iam` / `@h-ai/kit`；Web token 优先 httpOnly cookie。
-- 所有用户可见文本走 `$lib/paraglide/messages.js`，同步 `messages/zh-CN.json` 与 `messages/en-US.json`。
+- 所有用户可见文本走 `$lib/paraglide/messages.js`，同步 `messages/zh-CN.json`、`messages/en-US.json`、`messages/ja-JP.json`。
 - API 边界必须做 Zod 校验，HaiResult 错误用 kit response 转换。
 - `+server.ts` 只能导出 handler 和 SvelteKit 允许的配置项；helper 放到 `src/lib/server/**`。
 - 本样板默认不使用 `@h-ai/serv`、`@h-ai/api-contract`、`@h-ai/api-client`、`@h-ai/capacitor` 作为主架构。
@@ -60,7 +60,7 @@
 
 ## 质量门禁
 
-先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。
+先核对 package.json，按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集适用检查与日志，再归并修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。文档检查引用，UI/路由变更加 E2E，未运行项说明原因。
 
 ```bash
 pnpm typecheck
@@ -81,3 +81,7 @@ pnpm test:e2e
 - `hai-build`、`hai-app-create`、`hai-app-review`、`hai-app-tests`
 - `hai-kit`、`hai-ui`、`hai-iam`、`hai-reldb`、`hai-cache`、`hai-crypto`
 - 其它 `hai-*` 模块按需读取
+
+前端页面先按 [hai-ui-design](.agents/skills/hai-ui-design/SKILL.md) 确定任务、布局、状态与组件映射，使用 [hai-ui](.agents/skills/hai-ui/SKILL.md) 实现，再由 [hai-ui-review](.agents/skills/hai-ui-review/SKILL.md) 检查真实页面。窄范围修改复用已有设计；按实际语言/主题/尺寸验证。
+
+工作流技能按 hai-领域-动作 命名，能力使用类沿用领域名。需求、验收、发现与当前版本证据按 [工作交接契约](.agents/skills/hai-spec-implement/handoff.md) 传递，沿既有清单恢复任务。

package/templates/skills/bridges/api/AGENTS.md

@@ -57,7 +57,7 @@
 
 ## 质量门禁
 
-先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。
+先核对 package.json，按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集适用检查与日志，再归并修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。文档检查引用，UI/路由变更加 E2E，未运行项说明原因。
 
 ```bash
 pnpm typecheck
@@ -77,3 +77,5 @@ pnpm test:e2e
 - `hai-build`、`hai-app-create`、`hai-app-review`、`hai-app-tests`
 - `hai-serv`、`hai-api-contract`、`hai-api-client`
 - `hai-core`、`hai-reldb`、`hai-cache`、`hai-iam`、`hai-crypto`
+
+工作流技能按 hai-领域-动作 命名，能力使用类沿用领域名。需求、验收、发现与当前版本证据按 [工作交接契约](.agents/skills/hai-spec-implement/handoff.md) 传递，沿既有清单恢复任务。

package/templates/skills/bridges/fullstack/AGENTS.md.hbs

@@ -74,7 +74,7 @@ Fullstack 多包工程入口。先读 README、根 workspace 脚本与相关 pac
 
 ## 质量门禁
 
-按影响范围执行，跨包契约从根工作区验证：
+按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集一轮适用门禁及日志，汇总后集中修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。跨包契约从根工作区验证：
 
 ```bash
 pnpm typecheck
@@ -94,3 +94,7 @@ pnpm test:e2e
 ## 优先 Skills
 
 构建与验收：`hai-build`、`hai-app-review`、`hai-app-tests`。管理业务按需读取 `hai-iam`、`hai-reldb`、`hai-cache`、`hai-audit`、`hai-storage`、`hai-crypto`；配置与跨端读取 `hai-core`、`hai-ui`、`hai-serv`、`hai-api-contract`、`hai-api-client`、`hai-capacitor`。
+
+前端页面先按 [hai-ui-design](.agents/skills/hai-ui-design/SKILL.md) 确定任务、布局、状态与组件映射，使用 [hai-ui](.agents/skills/hai-ui/SKILL.md) 实现，再由 [hai-ui-review](.agents/skills/hai-ui-review/SKILL.md) 检查真实页面。窄范围修改复用已有设计；按实际语言/主题/尺寸验证。
+
+工作流技能按 hai-领域-动作 命名，能力使用类沿用领域名。需求、验收、发现与当前版本证据按 [工作交接契约](.agents/skills/hai-spec-implement/handoff.md) 传递，沿既有清单恢复任务。

package/templates/skills/bridges/h5/AGENTS.md

@@ -37,7 +37,7 @@
 ## 架构边界
 
 - 使用移动端友好的布局和 `@h-ai/ui` 移动组件。
-- 页面文本走 i18n，同步中英文 messages。
+- 页面文本走 i18n，同步中英日文 messages。
 - API 输入必须校验，业务错误按 HaiResult 传递。
 - `+server.ts` 只能导出 handler 和 SvelteKit 允许的配置项；helper 放到 `src/lib/**`。
 - 敏感 token 不要写入不安全存储；优先复用模板已有的鉴权与请求模式。
@@ -60,7 +60,7 @@
 
 ## 质量门禁
 
-先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。
+先核对 package.json，按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集适用检查与日志，再归并修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。文档检查引用，UI/路由变更加 E2E，未运行项说明原因。
 
 ```bash
 pnpm typecheck
@@ -80,3 +80,7 @@ pnpm test:e2e
 - `hai-build`、`hai-app-create`、`hai-app-review`、`hai-app-tests`
 - `hai-kit`、`hai-ui`、`hai-reldb`、`hai-cache`
 - 其它 `hai-*` 模块按需读取
+
+前端页面先按 [hai-ui-design](.agents/skills/hai-ui-design/SKILL.md) 确定任务、布局、状态与组件映射，使用 [hai-ui](.agents/skills/hai-ui/SKILL.md) 实现，再由 [hai-ui-review](.agents/skills/hai-ui-review/SKILL.md) 检查真实页面。窄范围修改复用已有设计；按实际语言/主题/尺寸验证。
+
+工作流技能按 hai-领域-动作 命名，能力使用类沿用领域名。需求、验收、发现与当前版本证据按 [工作交接契约](.agents/skills/hai-spec-implement/handoff.md) 传递，沿既有清单恢复任务。

package/templates/skills/bridges/mobile-app/AGENTS.md

@@ -42,7 +42,7 @@
 - 需求迁移到 SvelteKit 时同步运行环境、路由、初始化、构建与原生壳集成；不能仅添加 `+page.svelte` 等文件就视为完成迁移。
 - 原生能力通过 `@h-ai/capacitor` 使用；token 原生端使用 Capacitor 安全存储，Web 预览仅使用内存存储。
 - API 调用使用 `@h-ai/api-client`，业务错误按 HaiResult 处理。
-- 页面文本走 i18n，同步中英文 messages。
+- 页面文本走 i18n，同步中英日文 messages。
 - 原生桥接与设备调用放在 `src/lib/capacitor.ts` 或 service，避免散落在页面模板中。
 - 本样板默认不使用 `@h-ai/core`、`@h-ai/kit`、`@h-ai/serv`、`@h-ai/api-contract` 作为主架构。
 
@@ -71,7 +71,7 @@ pnpm cap:build:android:release
 
 ## 质量门禁
 
-先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。
+先核对 package.json，按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集适用检查与日志，再归并修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。文档检查引用，UI/路由变更加 E2E，未运行项说明原因。
 
 ```bash
 pnpm typecheck
@@ -92,3 +92,7 @@ pnpm test:e2e
 - `hai-build`、`hai-app-review`、`hai-app-tests`
 - `hai-ui`、`hai-api-client`、`hai-capacitor`
 - 其它 `hai-*` 模块按需读取
+
+前端页面先按 [hai-ui-design](.agents/skills/hai-ui-design/SKILL.md) 确定任务、布局、状态与组件映射，使用 [hai-ui](.agents/skills/hai-ui/SKILL.md) 实现，再由 [hai-ui-review](.agents/skills/hai-ui-review/SKILL.md) 检查真实页面。窄范围修改复用已有设计；按实际语言/主题/尺寸验证。
+
+工作流技能按 hai-领域-动作 命名，能力使用类沿用领域名。需求、验收、发现与当前版本证据按 [工作交接契约](.agents/skills/hai-spec-implement/handoff.md) 传递，沿既有清单恢复任务。

package/templates/skills/bridges/website/AGENTS.md

@@ -36,7 +36,7 @@
 
 ## 架构边界
 
-- 页面内容与导航文案全部走 i18n，同步中英文 messages。
+- 页面内容与导航文案全部走 i18n，同步中英日文 messages。
 - 表单和 API 输入必须 Zod 校验。
 - UI 组件优先使用 `@h-ai/ui`，不要重复实现已有组件。
 - `+server.ts` 只能导出 handler 和 SvelteKit 允许的配置项；helper 放到 `src/lib/**`。
@@ -60,7 +60,7 @@
 
 ## 质量门禁
 
-先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。
+先核对 package.json，按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集适用检查与日志，再归并修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。文档检查引用，UI/路由变更加 E2E，未运行项说明原因。
 
 ```bash
 pnpm typecheck
@@ -80,3 +80,7 @@ pnpm test:e2e
 - `hai-build`、`hai-app-create`、`hai-app-review`、`hai-app-tests`
 - `hai-kit`、`hai-ui`、`hai-reldb`、`hai-cache`
 - 其它 `hai-*` 模块按需读取
+
+前端页面先按 [hai-ui-design](.agents/skills/hai-ui-design/SKILL.md) 确定任务、布局、状态与组件映射，使用 [hai-ui](.agents/skills/hai-ui/SKILL.md) 实现，再由 [hai-ui-review](.agents/skills/hai-ui-review/SKILL.md) 检查真实页面。窄范围修改复用已有设计；按实际语言/主题/尺寸验证。
+
+工作流技能按 hai-领域-动作 命名，能力使用类沿用领域名。需求、验收、发现与当前版本证据按 [工作交接契约](.agents/skills/hai-spec-implement/handoff.md) 传递，沿既有清单恢复任务。

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

@@ -13,12 +13,14 @@ description: "接入 @h-ai/ai 的 LLM、工具/MCP、RAG、会话记忆、图像
 | 适用场景 | AI 应用服务端集成或浏览器代理接入 |
 | 输入 | AIConfigInput、消息/音频/图片、scope、AbortSignal |
 | 输出 | 领域操作为 HaiResult；流为 AsyncIterable，迭代可抛错 |
-| 限制 | tools/stream 无需 init；其他领域先初始化。持久化需先初始化 reldb + vecdb 或传 storeProvider；临时 Store 关闭后丢失。工具调用仍需业务授权。 |
+| 限制 | tools/stream 无需 init；其他领域先初始化。生产须先初始化共享 PostgreSQL/MySQL + 网络 vecdb 或传 stateScope=shared 的 Provider；临时 Store 仅开发/测试，关闭后丢失。工具调用仍需业务授权。 |
 
 ## 使用路径
 
 - 先选择完整结果还是流式 API；不要对 AsyncIterable 取 `.success`。流取消/错误须结束播放器和连接。
-- Memory/Context 用 objectId/sessionId 隔离主体；手动 turnCommit 只提交实际播放/发生的文本。
+- Memory/Context 用 objectId/sessionId 隔离主体；Context scope 必填，跨节点读先 reload/restore，manual pending 可跨节点按 turnId 幂等提交实际文本。共享 Store 必须实现版本 CAS/存储端期限；过期生成不自动重放外部副作用。
+- Mem0 生产须实际映射持久 Qdrant；内存回退开关不能绕过。列表/条件清理最多 1000 条主体原始候选，超限检查 `MEMORY_LIST_INCOMPLETE`；禁止把截断结果当完整 total。
+- HTTP AI 使用 `@h-ai/api-client` 的 typed 领域方法；A2A 由应用定义并绑定自己的 contract；`@h-ai/ai/client` 只提供独立 `createAudioClient`，不再封装字符串路径 HTTP 或重复 SSE helper。
 - 语音客户端用一次性 ticket，不能把 IAM access token 放 URL；按 segment_started 的真实格式解码。
 - 压缩超过硬预算须停止模型请求；不能失败后发送原始超长消息。
 
@@ -42,3 +44,7 @@ description: "接入 @h-ai/ai 的 LLM、工具/MCP、RAG、会话记忆、图像
 - 质量与安全检查
 
 补充类型/错误码与范本见 [reference.md](reference.md)，仅在上述用法不足时读取。
+
+公开 API 示例以安装包的实际入口为准；框架源码中的内部工厂例子仅供模块维护。HaiResult 调用先检查 success，流与浏览器 AudioClient 按显式抛错契约处理；Context flush 失败和 A2A 未知外部效果不得盲目重放。
+
+Node 自定义 SSE 使用 ai.stream 的统一编解码，不用 split/trim 手拆上游事件；encoder 的非法元数据会显式抛错。Anthropic/MiMo 的真实 HTTP 流在退出和取消时释放正文，EOF 不伪造未完成事件，不自动重连或重放业务。