@h-ai/cli 0.1.0-alpha.56 → 0.1.0-alpha.58

package/templates/base/src/lib/server/init.ts.hbs

@@ -30,6 +30,10 @@
 {{#if features.ai}}
 import type { AIConfigInput } from '@h-ai/ai'
 {{/if}}
+{{#if features.audit}}
+import type { AuditInitConfigInput } from '@h-ai/audit'
+{{/if}}
+import type { CoreConfig } from '@h-ai/core'
 {{#if features.iam}}
 import type { IamConfigSettingsInput } from '@h-ai/iam'
 {{/if}}
@@ -43,12 +47,15 @@ import type { StorageConfigInput } from '@h-ai/storage'
 import { ai } from '@h-ai/ai'
 {{/if}}
 {{#if features.audit}}
-import { audit } from '@h-ai/audit'
+import { audit, AuditInitConfigSchema } from '@h-ai/audit'
 {{/if}}
 {{#if features.cache}}
 import { cache, CacheConfigSchema } from '@h-ai/cache'
 {{/if}}
 import { core } from '@h-ai/core'
+{{#if features.crypto}}
+import { crypto } from '@h-ai/crypto'
+{{/if}}
 {{#if features.iam}}
 import { iam } from '@h-ai/iam'
 {{/if}}
@@ -81,9 +88,15 @@ export async function initApp(): Promise<void> {
   // 1. 加载配置
   core.init({
     configDir: './config',
-    logging: { level: 'info' },
   })
 
+{{#if features.crypto}}
+  // 加密模块初始化完成后才继续启动依赖它的 IAM / transport。
+  const cryptoResult = await crypto.init()
+  if (!cryptoResult.success)
+    throw new Error(`Crypto initialization failed: ${cryptoResult.error.message}`)
+{{/if}}
+
 {{#if features.db}}
   // ─── 配置校验 ───
   const dbValidation = core.config.validate('db', ReldbConfigSchema)
@@ -97,6 +110,11 @@ export async function initApp(): Promise<void> {
     throw new Error(`Cache config invalid: ${cacheValidation.error.message}`)
   }
 {{/if}}
+{{#if features.audit}}
+  const auditValidation = core.config.validate('audit', AuditInitConfigSchema)
+  if (!auditValidation.success)
+    throw new Error(`Audit config invalid: ${auditValidation.error.message}`)
+{{/if}}
 
 {{#if features.db}}
   // ─── 获取配置 ───
@@ -108,6 +126,9 @@ export async function initApp(): Promise<void> {
 {{#if features.iam}}
   const iamConfig = core.config.getOrThrow<IamConfigSettingsInput>('iam')
 {{/if}}
+{{#if features.audit}}
+  const auditConfig = core.config.getOrThrow<AuditInitConfigInput>('audit')
+{{/if}}
 {{#if features.storage}}
   const storageConfig = core.config.get<StorageConfigInput>('storage')
 {{/if}}
@@ -177,9 +198,9 @@ export async function initApp(): Promise<void> {
 
 {{#if features.audit}}
   // ─── 初始化审计 ───
-  const auditResult = await audit.init()
+  const auditResult = await audit.init(auditConfig)
   if (!auditResult.success) {
-    core.logger.warn('Audit initialization failed', { error: auditResult.error.message })
+    throw new Error(`Audit initialization failed: ${auditResult.error.message}`)
   }
 {{/if}}
 
@@ -194,5 +215,5 @@ export async function initApp(): Promise<void> {
 {{/if}}
 
   initialized = true
-  core.logger.info('{{projectName}} initialized.')
+  core.logger.info('Application initialized', { app: core.config.getOrThrow<CoreConfig>('core').name })
 }

package/templates/base/src/routes/+layout.server.ts.hbs

@@ -0,0 +1,18 @@
+{{! @skipIfEmpty }}
+{{#unless isSvelteOnlyApp}}
+import type { CoreConfig } from '@h-ai/core'
+import { core } from '@h-ai/core'
+
+/** 只向浏览器提供公开配置，避免暴露日志上下文、凭证或其它模块配置。 */
+export function load() {
+  const config = core.config.getOrThrow<CoreConfig>('core')
+  return {
+    appConfig: {
+      name: config.name,
+      version: config.version,
+      env: config.env,
+      defaultLocale: config.defaultLocale,
+    },
+  }
+}
+{{/unless}}

package/templates/base/tests/scaffold.test.ts.hbs

@@ -1,7 +1,16 @@
+{{#unless isSvelteOnlyApp}}
+import type { CoreConfig } from '@h-ai/core'
+{{/unless}}
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+{{#unless isSvelteOnlyApp}}
+import { core } from '@h-ai/core'
+{{/unless}}
 import { describe, expect, it } from 'vitest'
+{{#unless isSvelteOnlyApp}}
+import { load } from '../src/routes/+layout.server'
+{{/unless}}
 
 const rootDir = fileURLToPath(new URL('..', import.meta.url))
 
@@ -39,4 +48,15 @@ describe('generated scaffold', () => {
     expect(coreConfig).toContain('defaultLocale: {{defaultLocale}}')
   })
 {{/unless}}
-})
+{{#unless isSvelteOnlyApp}}
+
+  it('publishes only public metadata from parsed core configuration', () => {
+    core.init({ configDir: './config' })
+    const config = core.config.getOrThrow<CoreConfig>('core')
+    expect(core.logger.getLevel()).toBe(config.logging?.level ?? 'info')
+    expect(load()).toEqual({
+      appConfig: { name: config.name, version: config.version, env: config.env, defaultLocale: config.defaultLocale },
+    })
+  })
+{{/unless}}
+})

package/templates/base/vite.config.ts.hbs

@@ -1,8 +1,14 @@
 /**
  * {{projectName}} - Vite 配置
  */
+{{#if isSvelteOnlyApp}}
+import type { CoreConfig } from '@h-ai/core'
+{{/if}}
 import path from 'node:path'
 import process from 'node:process'
+{{#if isSvelteOnlyApp}}
+import { core } from '@h-ai/core'
+{{/if}}
 {{#if hasUi}}
 import { haiOptimizeExclude, haiPrebundledDeps } from '@h-ai/ui/vite'
 {{/if}}
@@ -22,8 +28,23 @@ import { defineConfig, loadEnv } from 'vite'
 export default defineConfig(({ mode }) => {
   const env = loadEnv(mode, process.cwd(), '')
   Object.assign(process.env, env)
+{{#if isSvelteOnlyApp}}
+  // 浏览器无法读取 YAML；构建时通过 core 解析，仅注入明确可公开的字段。
+  core.init({ configDir: './config' })
+  const config = core.config.getOrThrow<CoreConfig>('core')
+  const appConfig = {
+    name: config.name,
+    version: config.version,
+    env: config.env,
+    defaultLocale: config.defaultLocale,
+    logging: config.logging ? { level: config.logging.level, format: config.logging.format } : undefined,
+  }
+{{/if}}
 
   return {
+{{#if isSvelteOnlyApp}}
+    define: { __APP_CORE_CONFIG__: JSON.stringify(appConfig) },
+{{/if}}
     plugins: [
   {{#if isSvelteOnlyApp}}
       svelte(),

package/templates/features/ai/routes/api/chat/+server.ts

@@ -4,23 +4,22 @@
 import type { RequestHandler } from './$types'
 import { ai } from '@h-ai/ai'
 import { kit } from '@h-ai/kit'
+import { z } from 'zod'
 
-export const POST: RequestHandler = async ({ request, locals }) => {
-  const { message } = await request.json()
+const ChatInputSchema = z.object({ message: z.string().trim().min(1).max(4000) }).strict()
 
-  if (!message) {
-    return kit.response.badRequest('message is required')
-  }
+export const POST: RequestHandler = kit.handler(async ({ request, locals }) => {
+  const { message } = await kit.validate.body(request, ChatInputSchema)
 
   const result = await ai.llm.ask(message, {
     systemPrompt: 'You are a helpful assistant.',
   })
 
   if (!result.success) {
-    return kit.response.internalError(result.error.message)
+    return kit.response.fromError(result.error, locals.requestId)
   }
 
   return kit.response.ok({
     reply: result.data,
   }, locals.requestId)
-}
+})

package/templates/features/iam/routes-admin/(auth)/auth/login/+page.svelte.hbs

@@ -22,7 +22,7 @@
       const res = await fetch('/api/auth/login', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ username, password }),
+        body: JSON.stringify({ identifier: username, password }),
       })
       const data = await res.json()
       if (data.success) {

package/templates/features/iam/routes-h5/auth/login/+page.svelte.hbs

@@ -22,7 +22,7 @@
       const res = await fetch('/api/auth/login', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ username, password }),
+        body: JSON.stringify({ identifier: username, password }),
       })
       const data = await res.json()
       if (data.success) {

package/templates/features/iam/routes-shared/api/auth/login/+server.ts

@@ -1,32 +1,36 @@
+import type { CoreConfig } from '@h-ai/core'
 /**
  * 登录 API
  */
 import type { RequestHandler } from './$types'
+import { core } from '@h-ai/core'
 import { iam } from '@h-ai/iam'
 import { kit } from '@h-ai/kit'
+import { z } from 'zod'
 
-export const POST: RequestHandler = async ({ request, cookies, locals }) => {
-  const body = await request.json()
-  const { identifier, password } = body
+const LoginInputSchema = z.object({
+  identifier: z.string().trim().min(1).max(254),
+  password: z.string().min(1).max(128),
+}).strict()
 
-  if (!identifier || !password) {
-    return kit.response.badRequest('identifier and password are required')
-  }
+export const POST: RequestHandler = kit.handler(async ({ request, cookies, locals }) => {
+  const { identifier, password } = await kit.validate.body(request, LoginInputSchema)
 
   const result = await iam.auth.login({ identifier, password })
   if (!result.success) {
-    return kit.response.unauthorized(result.error.message)
+    return kit.response.fromError(result.error, locals.requestId)
   }
 
   const { tokens } = result.data
+  const config = core.config.getOrThrow<CoreConfig>('core')
 
   cookies.set('session_token', tokens.accessToken, {
     path: '/',
     httpOnly: true,
     sameSite: 'lax',
-    secure: false,
+    secure: config.env === 'production' || config.env === 'staging',
     maxAge: tokens.expiresIn,
   })
 
-  return kit.response.ok({ message: 'Login successful' }, locals.requestId)
-}
+  return kit.response.ok({ authenticated: true }, locals.requestId)
+})

package/templates/features/iam/routes-shared/api/auth/logout/+server.ts

@@ -5,11 +5,13 @@ import type { RequestHandler } from './$types'
 import { iam } from '@h-ai/iam'
 import { kit } from '@h-ai/kit'
 
-export const POST: RequestHandler = async ({ cookies, locals }) => {
+export const POST: RequestHandler = kit.handler(async ({ cookies, locals }) => {
   const token = cookies.get('session_token')
   if (token) {
-    await iam.auth.logout(token)
+    const result = await iam.auth.logout(token)
+    if (!result.success)
+      return kit.response.fromError(result.error, locals.requestId)
   }
   cookies.delete('session_token', { path: '/' })
-  return kit.response.ok({ message: 'Logout successful' }, locals.requestId)
-}
+  return kit.response.ok({ authenticated: false }, locals.requestId)
+})

package/templates/features/storage/routes/api/upload/+server.ts

@@ -2,28 +2,30 @@
  * 文件上传 API — storage 功能示例
  */
 import type { RequestHandler } from './$types'
+import { core } from '@h-ai/core'
 import { kit } from '@h-ai/kit'
 import { storage } from '@h-ai/storage'
 
-export const POST: RequestHandler = async ({ request, locals }) => {
+export const POST: RequestHandler = kit.handler(async ({ request, locals }) => {
   const formData = await request.formData()
-  const file = formData.get('file') as File | null
+  const file = formData.get('file')
 
-  if (!file) {
-    return kit.response.badRequest('No file provided')
+  if (!(file instanceof File) || file.size === 0 || file.size > 10 * 1024 * 1024) {
+    return kit.response.badRequest(core.i18n.coreM('core_errorValidation'), locals.requestId)
   }
 
   const { Buffer } = await import('node:buffer')
   const buffer = Buffer.from(await file.arrayBuffer())
-  const key = `uploads/${Date.now()}-${file.name}`
+  // 路径由服务端生成，用户文件名仅作为元数据保存。
+  const key = `uploads/${core.id.uuid()}`
 
-  const result = await storage.put(key, buffer, {
+  const result = await storage.file.put(key, buffer, {
     contentType: file.type,
     metadata: { originalName: file.name },
   })
 
   if (!result.success) {
-    return kit.response.internalError(result.error.message)
+    return kit.response.fromError(result.error, locals.requestId)
   }
 
   return kit.response.ok({
@@ -32,4 +34,4 @@ export const POST: RequestHandler = async ({ request, locals }) => {
     size: file.size,
     type: file.type,
   }, locals.requestId)
-}
+})

package/templates/skills/AGENTS.md

@@ -4,6 +4,14 @@
 
 ## 行为契约
 
+普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
+
+- 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。
+- 按已安装版本的公开类型确认模块契约：生命周期模块按 init → use → close；core/serv/kit、纯函数/工厂与流按实际签名处理。返回 HaiResult 的操作先检查 success，不以 try/catch 代替判断；事务失败明确触发回滚。
+- 边界输入做 schema 校验，服务端验证身份、租户与资源权限；SQL 动态值参数化，文件路径防逃逸。密钥不进入 PUBLIC_/VITE_ 变量、客户端代码和日志；敏感 token 不写 localStorage。
+- 禁止 any、无说明的 as unknown as、console.log 和硬编码密钥；从包公开入口导入。注释中文、结构化日志英文并脱敏，用户文本走现有 i18n 并同步所有 locale。
+- 完成时说明实际复用的框架能力、未采用的相关能力及原因、门禁结果；跨边界同步类型、配置、调用方、文档和测试。
+
 先读 README、package.json、相关实现/测试和所需 .agents/skills；不要加载整个 skill 树。新增抽象前确认复用路径与真实需求；保留用户改动。跨文件任务简述影响和验证计划，无须固定规模标签或重复问卷。
 
 - 直接影响：修改 / 新建 / 删除哪些文件；哪些脚本、类型、配置或路由会变。
@@ -13,14 +21,7 @@
 
 本项目由 hai-framework CLI 生成。单应用工程通常在 `src/` 下开发；多包工程会同时包含 `packages/*` 与 `apps/*`。实际结构以当前项目目录为准。
 
-## 通用硬约束
-
-- 先用全局检索确认是否已有实现、测试和文档；优先复用，避免为“未来可能”新增抽象。
-- 生命周期模块按 init → use → close；core/serv/kit/纯函数和流式 API 按实际签名使用。返回 HaiResult 的业务操作先检查 success，不以 try/catch 代替判断。
-- 禁止 `any`、无说明的危险类型断言、`console.log`、硬编码密钥。
-- 用户可见文本必须走 i18n；如果项目启用了 `messages/zh-CN.json` 与 `messages/en-US.json`，修改文案时必须同步更新。
-- 代码注释中文，日志消息英文。
-- 如项目使用 SvelteKit，`+server.ts` 只能导出 HTTP handler 与 SvelteKit 允许的配置项；辅助函数放到 `src/lib/**`。
+如项目使用 SvelteKit，`+server.ts` 只能导出 HTTP handler 与 SvelteKit 允许的配置项；辅助函数放到 `src/lib/**`。
 
 ## 工作流程
 

package/templates/skills/CLAUDE.md

@@ -1,11 +1 @@
-# CLAUDE.md
-
 @AGENTS.md
-
-> Claude Code 项目指引。共享规范通过 `@AGENTS.md` 复用；本文件用于 generic fallback 场景，模块和工作流参考资料位于 `.agents/skills/`。
-
-共享规则见项目根 [AGENTS.md](AGENTS.md)；若未自动加载，先读取该文件。模块/流程按需读取项目根 .agents/skills/<name>/SKILL.md 及其相邻参考文件。
-
-## 质量门禁
-
-按 AGENTS.md 和实际 package.json 选择 typecheck、lint、build、test、test:e2e；最终说明已执行结果、未运行原因及同步文档/依赖方。

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

@@ -4,6 +4,14 @@
 
 ## 行为契约
 
+普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
+
+- 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。
+- 按已安装版本的公开类型确认模块契约：生命周期模块按 init → use → close；core/serv/kit、纯函数/工厂与流按实际签名处理。返回 HaiResult 的操作先检查 success，不以 try/catch 代替判断；事务失败明确触发回滚。
+- 边界输入做 schema 校验，服务端验证身份、租户与资源权限；SQL 动态值参数化，文件路径防逃逸。密钥不进入 PUBLIC_/VITE_ 变量、客户端代码和日志；敏感 token 不写 localStorage。
+- 禁止 any、无说明的 as unknown as、console.log 和硬编码密钥；从包公开入口导入。注释中文、结构化日志英文并脱敏，用户文本走现有 i18n 并同步所有 locale。
+- 完成时说明实际复用的框架能力、未采用的相关能力及原因、门禁结果；跨边界同步类型、配置、调用方、文档和测试。
+
 先读 README、package.json、相关实现/测试和所需 .agents/skills；不要加载整个 skill 树。新增抽象前确认复用路径与真实需求；保留用户改动。跨文件任务简述影响和验证计划，无须固定规模标签或重复问卷。
 
 - 直接影响：哪些 `+page.svelte`、`+layout.svelte`、`+page.server.ts`、`+server.ts`、service、messages、README、测试会变。

package/templates/skills/bridges/admin/copilot-instructions.md

@@ -7,3 +7,5 @@
 ## 质量门禁
 
 按 AGENTS.md 和实际 package.json 选择 typecheck、lint、build、test、test:e2e；最终说明已执行结果、未运行原因及同步文档/依赖方。
+
+普通新增、修改、修复任务先读 [应用开发 Skill](../.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](../.agents/skills/hai-app-create/development.md)，依照 AGENTS.md 的默认规则复用框架并完成安全与质量验证。

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

@@ -4,6 +4,14 @@
 
 ## 行为契约
 
+普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
+
+- 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。
+- 按已安装版本的公开类型确认模块契约：生命周期模块按 init → use → close；core/serv/kit、纯函数/工厂与流按实际签名处理。返回 HaiResult 的操作先检查 success，不以 try/catch 代替判断；事务失败明确触发回滚。
+- 边界输入做 schema 校验，服务端验证身份、租户与资源权限；SQL 动态值参数化，文件路径防逃逸。密钥不进入 PUBLIC_/VITE_ 变量、客户端代码和日志；敏感 token 不写 localStorage。
+- 禁止 any、无说明的 as unknown as、console.log 和硬编码密钥；从包公开入口导入。注释中文、结构化日志英文并脱敏，用户文本走现有 i18n 并同步所有 locale。
+- 完成时说明实际复用的框架能力、未采用的相关能力及原因、门禁结果；跨边界同步类型、配置、调用方、文档和测试。
+
 先读 README、package.json、相关实现/测试和所需 .agents/skills；不要加载整个 skill 树。新增抽象前确认复用路径与真实需求；保留用户改动。跨文件任务简述影响和验证计划，无须固定规模标签或重复问卷。
 
 - 直接影响：哪些 `apps/*-contract`、`apps/*-service`、config、README、测试会变。
@@ -18,7 +26,6 @@
 - API 输入输出必须由 `apps/*-contract/src/**` 中的 Zod schema 与 contract 定义统一约束。
 - Service 通过 `@h-ai/serv` + `@h-ai/api-contract` 装配 HTTP App；不要退回到 SvelteKit API routes 架构。
 - Typed client / contract / service 三者保持同一份路径与类型定义，不要复制粘贴接口。
-- 返回 `HaiResult<T>` 的业务 API 先判断 `success`；纯函数、工厂与流按实际签名处理。
 - 不生成用户页面；不要引入 UI 专属依赖或页面文案。
 - 配置和密钥来自 `apps/*-service/config/` 与环境变量，禁止硬编码。
 

package/templates/skills/bridges/api/copilot-instructions.md

@@ -9,3 +9,5 @@
 ## 质量门禁
 
 按 AGENTS.md 和实际 package.json 选择 typecheck、lint、build、test、test:e2e；最终说明已执行结果、未运行原因及同步文档/依赖方。
+
+普通新增、修改、修复任务先读 [应用开发 Skill](../.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](../.agents/skills/hai-app-create/development.md)，依照 AGENTS.md 的默认规则复用框架并完成安全与质量验证。

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

@@ -4,9 +4,16 @@ Fullstack 多包工程入口。先读 README、根 workspace 脚本与相关 pac
 
 ## 行为契约
 
+普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
+
+- 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。
+- 按已安装版本的公开类型确认模块契约：生命周期模块按 init → use → close；core/serv/kit、纯函数/工厂与流按实际签名处理。返回 HaiResult 的操作先检查 success，不以 try/catch 代替判断；事务失败明确触发回滚。
+- 边界输入做 schema 校验，服务端验证身份、租户与资源权限；SQL 动态值参数化，文件路径防逃逸。密钥不进入 PUBLIC_/VITE_ 变量、客户端代码和日志；敏感 token 不写 localStorage。
+- 禁止 any、无说明的 as unknown as、console.log 和硬编码密钥；从包公开入口导入。注释中文、结构化日志英文并脱敏，用户文本走现有 i18n 并同步所有 locale。
+- 完成时说明实际复用的框架能力、未采用的相关能力及原因、门禁结果；跨边界同步类型、配置、调用方、文档和测试。
+
 - 修改前检索实现、调用方、测试和文档，优先复用现有 contract、procedure、共享组件与脚本。
 - 跨包变更先明确受影响的 contract、serv、shared、前端及交付流程，再同步调用方；不必输出固定问卷。
-- 禁止 `any`、`console.log`、硬编码密钥。代码注释中文，日志英文；用户文本走 i18n。
 
 ## 架构边界
 
@@ -21,9 +28,19 @@ Fullstack 多包工程入口。先读 README、根 workspace 脚本与相关 pac
 | `apps/{{projectName}}-miniapp` | 选择 miniapp 时生成的预留说明与文案，当前不是可运行应用 |
 
 - 前端负责 UI 与请求编排；后端业务放 serv，共享能力放 shared。本样板默认不用 `@h-ai/kit`，不要混入 SvelteKit load / route 结构。
-- 返回 `HaiResult<T>` 的业务 API 先判断 `success`，业务错误直接透传；纯函数、工厂和流按实际签名使用，不能假定都返回 HaiResult。
 - 用户文本按 shared 跨端文案与各 app 专属文案分工，同步现有 locale。
-- 认证接入前检查现有实现；样板不意味着已配好 Cookie 或安全 token 存储。新增认证时 Web 明确 Cookie/内存方案，App 原生端配置安全 TokenStorage，Desktop 按 Tauri 安全边界实现。
+- 本样板默认启用 IAM、reldb、cache、audit、storage 和 crypto，复用现有初始化与关闭顺序；新增模块前先检查依赖、配置与公开契约。
+- 应用名称、版本、环境、日志与 locale 配置通过 core 统一获取；浏览器显示来自服务端 `app.info`，不另写硬编码副本或将私有配置注入客户端。
+
+## 管理与安全边界
+
+- `admin` / `user` 是固定角色代码。管理员进入用户、角色和审计管理；普通用户只进入个人设置。服务端为每个管理操作验证角色，个人资料、密码和头像按当前会话绑定用户，不能只靠导航隐藏保护权限。
+- 角色管理更新说明并显示人数，用户管理负责角色分配；保留当前管理员的自删除、自禁用、自降级及最后管理员保护，并验证并发管理请求。
+- JSON 业务请求与响应统一经 typed api-client 和 serv 的 crypto transport 加解密，包含登录与刷新；健康/就绪检查和公开头像二进制资源遵循已有例外，不能为新增业务 API 绕过传输加密。
+- Web 使用内存 access token 和 HttpOnly refresh Cookie；App 原生端装配 `createCapacitorTokenStorage`，浏览器预览沿用 Cookie；Desktop 原生端使用内存 TokenStorage，重启后重新登录。原生 body 刷新通道同时验证 `X-HAI-Token-Transport: body`、端对应的 `x-request-client` 与受信完整 Origin，刷新请求沿用这些头。敏感 token 不写 localStorage，不擅自将其持久化到普通配置文件。
+- 头像接受 PNG/JPEG/WebP，最大 512 KiB；contract、客户端与服务端校验保持一致。服务端验证实际图片数据并生成 storage key；普通用户仅更新自己的头像，管理员可替用户更新。
+- 用户与审计查询按 contract 分页，`page >= 1`、`pageSize` 为 1–100；页面默认每页 20 条。新增筛选同步 schema、procedure、store 和测试，SQL 值参数化。
+- 语言与主题偏好保存到当前用户 metadata，客户端只应用已支持的值。审计仅记录操作字段和资源标识，不记录密码、token、头像内容或联系信息。
 
 ## 质量门禁
 
@@ -46,4 +63,4 @@ pnpm test:e2e
 
 ## 优先 Skills
 
-构建与验收：`hai-build`、`hai-app-review`、`hai-app-tests`。模块使用：`hai-core`、`hai-ui`、`hai-serv`、`hai-api-contract`、`hai-api-client`、`hai-capacitor`；其余按需选择。
+构建与验收：`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`。

package/templates/skills/bridges/fullstack/copilot-instructions.md.hbs

@@ -4,6 +4,9 @@
 
 - `packages/{{projectName}}-contract` 定义 API；Fullstack 服务端 `packages/{{projectName}}-serv` 实现业务；`packages/{{projectName}}-shared` 共享 UI、i18n 和 typed client。
 - 前端按选择生成；App 使用 Capacitor，Desktop 使用 Tauri v2。miniapp 当前仅预留说明，不是可运行应用。
+- 默认 mini 管理后台复用 IAM/reldb/cache/audit/storage/crypto。管理员管理用户、固定 admin/user 角色及审计；普通用户仅操作个人设置，服务端按角色和当前会话验证权限。
+- typed api-client 与 serv 的 crypto transport 统一加解密 JSON 请求与响应，包含认证与刷新。Web 使用内存 access token + HttpOnly refresh Cookie，App 原生端使用 Capacitor 安全 TokenStorage，Desktop 使用内存 TokenStorage；具体边界与例外见根 AGENTS。
+- 应用名称、版本、环境、日志与 locale 配置通过 core 获取；前端消费 `app.info`。头像、分页、偏好与管理员保护以 contract、服务端实现和根 AGENTS 为准，改动时同步各端。
 
 ## 质量门禁
 
@@ -12,3 +15,5 @@
 ## 完成条件
 
 同步受影响的 contract、serv、shared、各端调用方及文档与测试，报告门禁结果和未执行原因。
+
+普通新增、修改、修复任务先读 [应用开发 Skill](../.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](../.agents/skills/hai-app-create/development.md)，依照 AGENTS.md 的默认规则复用框架并完成安全与质量验证。

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

@@ -4,6 +4,14 @@
 
 ## 行为契约
 
+普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
+
+- 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。
+- 按已安装版本的公开类型确认模块契约：生命周期模块按 init → use → close；core/serv/kit、纯函数/工厂与流按实际签名处理。返回 HaiResult 的操作先检查 success，不以 try/catch 代替判断；事务失败明确触发回滚。
+- 边界输入做 schema 校验，服务端验证身份、租户与资源权限；SQL 动态值参数化，文件路径防逃逸。密钥不进入 PUBLIC_/VITE_ 变量、客户端代码和日志；敏感 token 不写 localStorage。
+- 禁止 any、无说明的 as unknown as、console.log 和硬编码密钥；从包公开入口导入。注释中文、结构化日志英文并脱敏，用户文本走现有 i18n 并同步所有 locale。
+- 完成时说明实际复用的框架能力、未采用的相关能力及原因、门禁结果；跨边界同步类型、配置、调用方、文档和测试。
+
 先读 README、package.json、相关实现/测试和所需 .agents/skills；不要加载整个 skill 树。新增抽象前确认复用路径与真实需求；保留用户改动。跨文件任务简述影响和验证计划，无须固定规模标签或重复问卷。
 
 - 直接影响：哪些页面、layout、导航、API、messages、README、测试会变。

package/templates/skills/bridges/h5/copilot-instructions.md

@@ -7,3 +7,5 @@
 ## 质量门禁
 
 按 AGENTS.md 和实际 package.json 选择 typecheck、lint、build、test、test:e2e；最终说明已执行结果、未运行原因及同步文档/依赖方。
+
+普通新增、修改、修复任务先读 [应用开发 Skill](../.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](../.agents/skills/hai-app-create/development.md)，依照 AGENTS.md 的默认规则复用框架并完成安全与质量验证。

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

@@ -4,6 +4,14 @@
 
 ## 行为契约
 
+普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
+
+- 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。
+- 按已安装版本的公开类型确认模块契约：生命周期模块按 init → use → close；core/serv/kit、纯函数/工厂与流按实际签名处理。返回 HaiResult 的操作先检查 success，不以 try/catch 代替判断；事务失败明确触发回滚。
+- 边界输入做 schema 校验，服务端验证身份、租户与资源权限；SQL 动态值参数化，文件路径防逃逸。密钥不进入 PUBLIC_/VITE_ 变量、客户端代码和日志；敏感 token 不写 localStorage。
+- 禁止 any、无说明的 as unknown as、console.log 和硬编码密钥；从包公开入口导入。注释中文、结构化日志英文并脱敏，用户文本走现有 i18n 并同步所有 locale。
+- 完成时说明实际复用的框架能力、未采用的相关能力及原因、门禁结果；跨边界同步类型、配置、调用方、文档和测试。
+
 先读 README、package.json、相关实现/测试和所需 .agents/skills；不要加载整个 skill 树。新增抽象前确认复用路径与真实需求；保留用户改动。跨文件任务简述影响和验证计划，无须固定规模标签或重复问卷。
 
 - 直接影响：哪些页面、store、原生桥接、messages、README、测试和打包脚本会变。

package/templates/skills/bridges/mobile-app/copilot-instructions.md

@@ -7,3 +7,5 @@
 ## 质量门禁
 
 按 AGENTS.md 和实际 package.json 选择 typecheck、lint、build、test、test:e2e；最终说明已执行结果、未运行原因及同步文档/依赖方。
+
+普通新增、修改、修复任务先读 [应用开发 Skill](../.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](../.agents/skills/hai-app-create/development.md)，依照 AGENTS.md 的默认规则复用框架并完成安全与质量验证。

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

@@ -4,6 +4,14 @@
 
 ## 行为契约
 
+普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
+
+- 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。
+- 按已安装版本的公开类型确认模块契约：生命周期模块按 init → use → close；core/serv/kit、纯函数/工厂与流按实际签名处理。返回 HaiResult 的操作先检查 success，不以 try/catch 代替判断；事务失败明确触发回滚。
+- 边界输入做 schema 校验，服务端验证身份、租户与资源权限；SQL 动态值参数化，文件路径防逃逸。密钥不进入 PUBLIC_/VITE_ 变量、客户端代码和日志；敏感 token 不写 localStorage。
+- 禁止 any、无说明的 as unknown as、console.log 和硬编码密钥；从包公开入口导入。注释中文、结构化日志英文并脱敏，用户文本走现有 i18n 并同步所有 locale。
+- 完成时说明实际复用的框架能力、未采用的相关能力及原因、门禁结果；跨边界同步类型、配置、调用方、文档和测试。
+
 先读 README、package.json、相关实现/测试和所需 .agents/skills；不要加载整个 skill 树。新增抽象前确认复用路径与真实需求；保留用户改动。跨文件任务简述影响和验证计划，无须固定规模标签或重复问卷。
 
 - 直接影响：哪些页面、layout、表单/API、messages、README、测试会变。

package/templates/skills/bridges/website/copilot-instructions.md

@@ -7,3 +7,5 @@
 ## 质量门禁
 
 按 AGENTS.md 和实际 package.json 选择 typecheck、lint、build、test、test:e2e；最终说明已执行结果、未运行原因及同步文档/依赖方。
+
+普通新增、修改、修复任务先读 [应用开发 Skill](../.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](../.agents/skills/hai-app-create/development.md)，依照 AGENTS.md 的默认规则复用框架并完成安全与质量验证。

package/templates/skills/copilot-instructions.md

@@ -7,3 +7,5 @@
 ## 质量门禁
 
 按 AGENTS.md 和实际 package.json 选择 typecheck、lint、build、test、test:e2e；最终说明已执行结果、未运行原因及同步文档/依赖方。
+
+普通新增、修改、修复任务先读 [应用开发 Skill](../.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](../.agents/skills/hai-app-create/development.md)，依照 AGENTS.md 的默认规则复用框架并完成安全与质量验证。

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

@@ -126,6 +126,8 @@ Access token 存在内存中，refresh token 由服务端通过 `HttpOnly` cooki
 
 启用 `transport` 时，登录、业务请求以及 401 后的自动刷新都会复用同一个加密 fetch 链路；不要在业务代码中手写明文 `/auth/refresh` 请求。
 
+自动刷新识别真实 HTTP 401（`Response.status`），以及 HTTP 200 的有效失败 HaiResult（`success=false`、字符串 `error.code/message`、`error.httpStatus=401`），成功后只重试一次原请求。内置登录、注册与配置的 `auth.refreshPath` 排除自动刷新，403/500 等其它失败也不刷新。serv 普通 procedure 的 HTTP 状态仍为 200；调用方须检查最终 `success/error.code` 并处理刷新失败后的登录失效。
+
 ```ts
 import { apiClient } from '@h-ai/api-client'