@h-ai/cli 0.1.0-alpha.12 → 0.1.0-alpha.15

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

@@ -0,0 +1,272 @@
+---
+name: hai-api-contract
+description: 使用 @h-ai/api-contract 定义或扩展 oRPC HTTP API 契约；当需求涉及定义新领域 contract、组合应用级 contract、使用内置 IAM/Storage/AI/Payment 契约、编写自定义 procedure 输入输出 Schema 或为 @h-ai/api-client/@h-ai/serv 提供接口真相源时使用。
+---
+
+# hai-api-contract
+
+> `@h-ai/api-contract` 是 hai-framework 的公共 HTTP API 契约包，使用 oRPC contract + Zod v4 作为唯一接口真相源。本包只描述接口边界，不包含任何 procedure 实现。
+
+---
+
+## 运行环境
+
+> ✅ **纯定义包，无运行时依赖。** 可在客户端、服务端、测试环境直接引用。
+
+---
+
+## 适用场景
+
+- 定义新领域的 oRPC contract（输入/输出 Schema + HTTP 路由元数据）
+- 组合多个领域 contract 为应用级 contract
+- 向 `@h-ai/serv` 提供 contract（装配为 HTTP API）
+- 向 `@h-ai/api-client` 提供 contract（生成类型安全客户端）
+- 复用内置领域 contract（iam/storage/ai/payment）
+- 复用公共 Schema 工厂（`apiContract.haiResultSchema`、分页 Schema）
+
+---
+
+## 使用步骤
+
+### 1. 组合应用级 contract
+
+```typescript
+import { apiContract } from '@h-ai/api-contract'
+
+// 按需组合，传 false/undefined 的领域不会出现在 contract 或 OpenAPI spec 中
+export const myContract = apiContract.create({
+  iam: apiContract.iam,
+  storage: apiContract.storage,
+  ai: apiContract.ai,
+  payment: false, // 禁用领域
+})
+
+// myContract.iam.auth.login
+// myContract.storage.presignedUrls.createUpload
+// myContract.ai.chats.createCompletion
+```
+
+### 2. 组合自定义 contract
+
+```typescript
+import { apiContract } from '@h-ai/api-contract'
+
+export const myContract = apiContract.create({
+  iam: apiContract.iam,
+  storage: apiContract.storage,
+  payment: false, // 禁用领域（不会出现在 contract 或 OpenAPI spec 中）
+})
+```
+
+### 3. 定义新领域 contract
+
+```typescript
+import { apiContract } from '@h-ai/api-contract'
+import { z } from 'zod'
+
+// 输入 Schema
+const WidgetCreateInputSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+})
+
+// 输出 Schema（统一包装为 HaiResult<T>）
+const WidgetOutputSchema = apiContract.haiResultSchema(z.object({
+  id: z.string(),
+  name: z.string(),
+  createdAt: z.string(),
+}))
+
+// 领域 contract
+export const widgetContract = {
+  widget: {
+    create: apiContract
+      .route({
+        method: 'POST',
+        path: '/widgets',
+        operationId: 'widget.create',
+        summary: 'Create widget',
+        tags: ['widget'],
+      })
+      .input(WidgetCreateInputSchema)
+      .output(WidgetOutputSchema),
+
+    getById: apiContract
+      .route({
+        method: 'GET',
+        path: '/widgets/{id}',
+        operationId: 'widget.getById',
+        summary: 'Get widget by id',
+        tags: ['widget'],
+      })
+      .input(z.object({ id: z.string() }))
+      .output(WidgetOutputSchema),
+  },
+}
+```
+
+### 4. 将新 contract 挂入应用级 contract
+
+```typescript
+import { apiContract } from '@h-ai/api-contract'
+import { widgetContract } from './widget-contract.js'
+
+export const appContract = apiContract.create({
+  iam: apiContract.iam,
+  widget: widgetContract,
+})
+```
+
+### 5. 传给 `@h-ai/serv`（服务端）
+
+```typescript
+import { serv } from '@h-ai/serv'
+import { appContract } from './app-contract.js'
+import { createMyProcedures } from './procedures/widget.js'
+
+const app = serv.createApp({
+  contract: appContract,
+  procedures: {
+    iam: createIamProcedures({ iam }),
+    widget: createMyProcedures(),
+  },
+  http: { apiPrefix: '/api/v1' },
+})
+```
+
+---
+
+## 核心 API
+
+### `apiContract.create(options)` — 组合领域 contract
+
+```typescript
+import { apiContract } from '@h-ai/api-contract'
+
+const contract = apiContract.create({
+  iam: apiContract.iam,      // 启用：纳入 contract
+  storage: false,            // 禁用：不出现在 OpenAPI spec 中
+  custom: myContract,        // 自定义领域
+})
+// 类型自动收窄，被禁用的 key 不出现在 contract 类型中
+```
+
+### 内置领域 contract
+
+| 访问路径 | 领域 | 功能概述 |
+| --- | --- | --- |
+| `apiContract.iam` | IAM | auth（登录/登出/OTP/刷新/注册/改密码）、users、roles、permissions Admin CRUD |
+| `apiContract.storage` | Storage | presignedUrls（上传/下载/批量）、files（元数据查询/删除） |
+| `apiContract.ai` | AI | chats（completion/流式）、knowledge（上传/查询） |
+| `apiContract.payment` | Payment | orders、subscriptions |
+
+### 内置 contract 路径示例
+
+```typescript
+const myContract = apiContract.create({ iam: apiContract.iam, storage: apiContract.storage, ai: apiContract.ai })
+
+// IAM
+myContract.iam.auth.login        // POST /auth/login
+myContract.iam.auth.logout       // POST /auth/logout
+myContract.iam.users.list        // GET  /iam/users
+myContract.iam.roles.create      // POST /iam/roles
+
+// Storage
+myContract.storage.presignedUrls.createUpload   // POST /storage/presigned-urls/upload
+
+// AI
+myContract.ai.chats.createCompletion  // POST /ai/chats/completion
+```
+
+### `apiContract.haiResultSchema(dataSchema)` — 标准输出包装
+
+所有 HTTP 输出必须通过 `apiContract.haiResultSchema` 包装为 `HaiResult<T>`，与 `@h-ai/core` 的 `ok()/err()` 返回结构一致：
+
+```typescript
+import { apiContract } from '@h-ai/api-contract'
+import { z } from 'zod'
+
+const OutputSchema = apiContract.haiResultSchema(z.object({
+  id: z.string(),
+  name: z.string(),
+}))
+
+// 等价于:
+// { success: true, data: { id: string, name: string } }
+// | { success: false, error: HaiError }
+```
+
+### 公共 Schema 工具
+
+| 访问路径 | 说明 |
+| --- | --- |
+| `apiContract.haiResultSchema(dataSchema)` | `HaiResult<T>` 输出包装 |
+| `apiContract.voidResultSchema` | `HaiResult<void>` 空结果包装 |
+| `apiContract.paginatedSchema(itemSchema)` | 分页列表输出 Schema |
+| `HaiErrorSchema` | HaiError 公共字段 Schema |
+| `PaginationInputSchema` | 分页参数 Schema（page/limit） |
+| `PaginationOutputSchema` | 分页元数据 Schema（total/page/limit） |
+
+---
+
+## Contract 定义规范
+
+### 必须遵循
+
+- **输出必须包装为 `apiContract.haiResultSchema`** — 客户端依赖 `success` 判断成功/失败
+- **`operationId` 全局唯一** — 格式为 `domain.resource.action`，如 `iam.auth.login`
+- **`tags` 至少包含领域名** — 供 OpenAPI 文档分组
+- **输入 Schema 用 Zod v4** — 与 `@orpc/zod/zod4` 的 `ZodToJsonSchemaConverter` 配套
+- **Contract 不含业务逻辑** — 只有 Schema + 路由元数据，没有 `async function`
+
+### 禁止
+
+- ❌ Contract 文件中 `import` 任何业务模块（`@h-ai/iam`、`@h-ai/storage` 等）
+- ❌ 在 contract 中使用 `z.any()` 或 `z.unknown()` 作为输出类型
+- ❌ 重复定义已存在的领域 contract
+
+---
+
+## 常见模式
+
+### 带分页的列表接口
+
+```typescript
+import { apiContract, PaginationInputSchema } from '@h-ai/api-contract'
+import { z } from 'zod'
+
+const WidgetSchema = z.object({ id: z.string(), name: z.string() })
+
+const listWidgets = apiContract
+  .route({ method: 'GET', path: '/widgets', operationId: 'widget.list', tags: ['widget'] })
+  .input(PaginationInputSchema.extend({ keyword: z.string().optional() }))
+  .output(apiContract.haiResultSchema(apiContract.paginatedSchema(WidgetSchema)))
+```
+
+### 路径参数
+
+```typescript
+// 路径中的 {id} 对应 input 中的 id 字段
+const getWidget = apiContract
+  .route({ method: 'GET', path: '/widgets/{id}', operationId: 'widget.getById', tags: ['widget'] })
+  .input(z.object({ id: z.string() }))
+  .output(apiContract.haiResultSchema(WidgetSchema))
+```
+
+### 无输入的端点
+
+```typescript
+const healthContract = apiContract
+  .route({ method: 'GET', path: '/health', operationId: 'health.check', tags: ['system'] })
+  .output(apiContract.haiResultSchema(z.object({ status: z.string() })))
+```
+
+---
+
+## 测试
+
+```bash
+pnpm --filter @h-ai/api-contract test
+pnpm --filter @h-ai/api-contract typecheck
+pnpm --filter @h-ai/api-contract lint
+```

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

@@ -33,16 +33,17 @@ description: 应用开发入口技能。提供项目架构总览（SSR/SPA/原
 | 单元测试 | Vitest                         |
 | E2E 测试 | Playwright                     |
 | 原生 App | Capacitor 7                    |
-| 认证     | Bearer Token（统一）           |
+| 公共 API | oRPC contract + Hono + typed client |
+| 认证     | Bearer access token + httpOnly refresh cookie（浏览器推荐） |
 
 ### 多端构建模式
 
 | 模式    | Adapter        | 认证方式              | 部署目标                |
 | ------- | -------------- | --------------------- | ----------------------- |
-| SSR Web | adapter-node   | Bearer Token + Cookie | Node.js 服务器          |
-| SPA     | adapter-static | Bearer Token          | CDN / 静态托管          |
-| Android | adapter-static | Bearer Token          | Capacitor → Android APK |
-| iOS     | adapter-static | Bearer Token          | Capacitor → iOS IPA     |
+| SSR Web | adapter-node   | Bearer access token + Cookie | Node.js 服务器          |
+| SPA     | adapter-static | Bearer access token + httpOnly refresh cookie | CDN / 静态托管          |
+| Android | adapter-static | Bearer access token + Capacitor secure storage | Capacitor → Android APK |
+| iOS     | adapter-static | Bearer access token + Capacitor secure storage | Capacitor → iOS IPA     |
 
 **Adapter 切换**：
 
@@ -76,10 +77,11 @@ const config = {
     app.d.ts                      # 全局类型声明
     hooks.server.ts               # 服务端 Hook（模块初始化 + 请求管道）
     lib/
-      api.ts                      # API Client 初始化（SPA / 原生 App 使用）
+      api.ts                      # @h-ai/api-client 初始化（SPA / 原生 App 使用）
       capacitor.ts                # Capacitor 初始化（原生 App）
       server/
         init.ts                   # 模块初始化入口（单例，SSR）
+        procedures/               # 应用私有 oRPC procedures（仅 API Service 场景）
       paraglide/                  # i18n 生成文件（禁止手动修改）
       components/                 # 应用组件
     routes/
@@ -105,8 +107,10 @@ core（基础能力：配置、日志、i18n、HaiResult）
   ├── ai（AI：LLM/MCP/Agent）
   ├── iam（身份管理）← 依赖 crypto + db + cache
   ├── payment（支付）← 依赖 db + crypto
-  ├── kit（SvelteKit 集成）← 依赖 iam + cache + storage + crypto
-  ├── api-client（HTTP 客户端）← 纯浏览器端，依赖 iam/api（类型）
+  ├── api-contract（公共 HTTP API 契约）← 纯定义，依赖 core + zod + oRPC contract
+  ├── serv（Hono + oRPC API Service）← 依赖 api-contract；features 按需依赖 iam/storage/ai
+  ├── kit（SvelteKit 集成）← Hook / guard / validate / response，不定义公共 contract
+  ├── api-client（typed API 客户端）← 依赖 api-contract + oRPC client
   ├── capacitor（原生能力）← 纯浏览器端
   └── ui（UI 组件库）← 依赖 core
 ```
@@ -144,6 +148,8 @@ export async function initModules() {
 
   // 4. 集成层
   // kit 无需 init，通过 createHandle 配置
+  // api-contract 无需 init，只在服务端/客户端共享 contract
+  // serv 在 API Service 中通过 serv.createApp({ contract, procedures }) 装配
 
   initialized = true
 }
@@ -152,16 +158,17 @@ export async function initModules() {
 #### SPA / 原生 App 模式（src/lib/api.ts）
 
 ```typescript
-import { api } from '@h-ai/api-client'
+import { apiClient } from '@h-ai/api-client'
 
 export async function initApi() {
-  return api.init({
+  return apiClient.init({
     baseUrl: import.meta.env.VITE_API_BASE_URL,
+    auth: {}, // 浏览器默认 httpOnly cookie；原生 App 传入 Capacitor TokenStorage
     timeout: 15_000,
   })
 }
 
-export { api }
+export { apiClient }
 ```
 
 #### 原生 App 追加初始化（src/lib/capacitor.ts）
@@ -204,9 +211,11 @@ log:
 | 加密/签名/哈希        | `hai-crypto`     | crypto.init, SM2, SM3, SM4, 加密, 签名            |
 | 身份认证/授权         | `hai-iam`        | iam.init, 登录, 注册, RBAC, Token, Bearer         |
 | AI/LLM/MCP            | `hai-ai`         | ai.init, LLM, MCP, Agent, 工具调用                |
-| SvelteKit 集成        | `hai-kit`        | kit.createHandle, guard, fromContract, middleware |
+| 公共 API 契约         | `hai-api-contract` | apiContract.create, contract, schema, oRPC, HaiResult |
+| API Service 运行时    | `hai-serv`       | serv.createApp, Hono, procedures, OpenAPI, docs, requireAuth |
+| SvelteKit 集成        | `hai-kit`        | kit.createHandle, guard, middleware, validate, response |
 | UI 组件               | `hai-ui`         | 表单, 按钮, 表格, Modal, Toast, 移动端组件        |
-| HTTP 客户端           | `hai-api-client` | api.call, api.get, api.post, Bearer, 拦截器       |
+| typed API 客户端      | `hai-api-client` | apiClient.init, typed client, Bearer, 401 refresh, custom fetch |
 | 原生 App 能力         | `hai-capacitor`  | capacitor, 相机, 推送, 状态栏, 设备信息           |
 | 支付                  | `hai-payment`    | payment, 微信支付, 支付宝, Stripe, 订单           |
 
@@ -217,6 +226,9 @@ log:
 | 创建页面/组件/API/模型 | `hai-app-create` | 新建页面, 添加组件, API 端点, 数据模型 |
 | 代码审查与规范化       | `hai-app-review` | 审查, review, 规范, 优化               |
 | 编写/补充测试          | `hai-app-tests`  | 测试, test, 单测, 覆盖率, TDD, E2E     |
+| CI/CD 与质量门禁       | `hai-ci`         | CI, CD, GitHub Actions, workflow, secret scan |
+| PR / Issue 交付审查    | `hai-pr-review`  | PR, pull request, issue, CODEOWNERS, 自动 Review, AI Review |
+| hai-framework 同步     | `hai-framework-sync` | hai-framework, skills 同步, framework:use:local, framework:watch |
 
 ---
 

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

@@ -52,14 +52,14 @@ await capacitor.close()
 ### 2. Token 安全存储（与 api-client 配合）
 
 ```typescript
-import { api } from '@h-ai/api-client'
+import { apiClient } from '@h-ai/api-client'
 import { createCapacitorTokenStorage } from '@h-ai/capacitor'
 
-await api.init({
+await apiClient.init({
   baseUrl: import.meta.env.PUBLIC_API_BASE,
   auth: {
     storage: createCapacitorTokenStorage(),
-    refreshUrl: '/api/v1/auth/refresh',
+    refreshPath: '/api/v1/auth/refresh',
   },
 })
 ```
@@ -278,20 +278,20 @@ const config = {
 
 ```typescript
 // src/lib/api.ts
-import { api } from '@h-ai/api-client'
+import { apiClient } from '@h-ai/api-client'
 import { createCapacitorTokenStorage } from '@h-ai/capacitor'
 
 export async function initApi() {
-  return api.init({
+  return apiClient.init({
     baseUrl: `${import.meta.env.PUBLIC_API_BASE}/api/v1`,
     auth: {
       storage: createCapacitorTokenStorage(),
-      refreshUrl: '/auth/refresh',
+      refreshPath: '/auth/refresh',
     },
   })
 }
 
-export { api }
+export { apiClient }
 ```
 
 ### 推送通知完整流程

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

@@ -0,0 +1,112 @@
+---
+name: hai-ci
+description: 设计和维护 hai-framework 应用仓库的 CI/CD、GitHub Actions、质量门禁、secret scan 与 workflow 安全；当需求涉及 CI、GitHub Actions、required checks、泄漏扫描或 release workflow 编排时使用。
+---
+
+# hai-ci — CI/CD 与质量门禁规范
+
+> 面向 AI 助手和团队成员的仓库自动化指南。目标是让每个 PR 都能被机器稳定验证，同时避免把 secrets 暴露给不可信 PR 或第三方 Action。
+
+---
+
+## 适用场景
+
+- 新增或修改 `.github/workflows/**`
+- 配置 `pnpm typecheck`、`pnpm lint`、`pnpm test`、`pnpm build`、E2E
+- 调整 secret scan、依赖扫描、安全扫描、release workflow 编排
+- 设计 required checks 的 CI 状态、workflow 权限、触发条件与 concurrency
+- 排查 CI flaky、缓存、矩阵构建或执行顺序问题
+
+不负责：PR 人工审查流程（用 `hai-pr-review`）、测试用例设计（用 `hai-app-tests`）、代码质量审查（用 `hai-app-review`）、云资源开通与应用部署 API（用 `hai-deploy`）。
+
+---
+
+## 核心原则
+
+1. **确定性检查优先**：CI 只负责可重复的机器检查；测试内容设计交给 `hai-app-tests`，代码规范判断交给 `hai-app-review`。
+2. **最小权限**：默认 `permissions: contents: read`，只有 release、comment、pages 等明确场景才提升权限。
+3. **PR 不使用 secrets**：来自 fork 或不可信分支的 PR 不得运行读取 secrets 的 workflow。
+4. **禁用高风险组合**：禁止 `pull_request_target` + checkout PR 代码 + secrets/写权限。
+5. **先轻后重**：核心 CI 必须稳定；E2E、发布、安全深扫可以拆成 manual/nightly 或独立 workflow。
+6. **可追溯**：workflow 改动必须说明触发条件、权限、缓存、失败路径和验证命令。
+
+---
+
+## 标准 CI 工作流
+
+### PR / main 基础质量门禁
+
+建议顺序：
+
+```bash
+pnpm install --frozen-lockfile
+pnpm typecheck
+pnpm lint
+pnpm test
+pnpm build
+```
+
+测试覆盖范围与 TDD 断言由 `hai-app-tests` 定义；本技能只决定这些命令如何在 workflow 中稳定执行。
+
+### E2E 策略
+
+- 若 E2E 稳定且耗时可控，可作为 required check。
+- 若 E2E 依赖浏览器、服务、密钥或容易 flaky，先放到 `workflow_dispatch` / `schedule` / 独立 job。
+- 应用级 E2E 使用：`pnpm --filter <app> test:e2e`。
+
+### hai-framework 依赖策略
+
+- CI 默认使用 `pnpm-lock.yaml` 中的 npm/published 依赖，确保与真实安装环境一致。
+- 本地联调使用 `framework:use:local` / `framework:watch`，但不要让默认 PR CI 隐式依赖本机路径。
+- 需要验证本地 framework 改动时，创建显式的 sync/drift check 或双仓联动 PR。
+
+---
+
+## GitHub Actions 安全清单
+
+- [ ] workflow 顶层声明 `permissions`
+- [ ] PR workflow 使用 `pull_request`，不用 `pull_request_target`
+- [ ] 不在 PR workflow 中读取 secrets
+- [ ] 第三方 action 固定版本；高风险 action 优先改为本地脚本或官方 action
+- [ ] 使用 `concurrency` 取消同分支旧任务
+- [ ] 不在 CI 日志打印 token、cookie、连接串、`.env` 内容
+- [ ] release workflow 独立提权，只在 main/tag/manual 触发
+- [ ] 失败日志可定位，不吞错、不 `|| true` 掩盖核心质量门禁
+
+---
+
+## Secret scan 策略
+
+### 推荐
+
+- 用无 secrets 的高置信正则扫描常见密钥形态。
+- 排除示例 skill、锁文件、图片等容易误报的路径。
+- 需要私有关键词表时，仅在受信任分支的独立 workflow 中运行，不对 fork PR 暴露。
+
+### 禁止
+
+- ❌ `pull_request_target` 中 checkout 不可信 PR 代码后读取 `secrets.*`
+- ❌ 把完整密钥关键词列表传给未知第三方 action
+- ❌ 为了通过扫描而删除失败证据或扩大忽略范围
+
+---
+
+## Workflow 变更交付清单
+
+修改 CI/CD 时，PR 描述必须包含：
+
+- 触发条件：`pull_request` / `push` / `workflow_dispatch` / `schedule`
+- 权限：顶层和 job 级 `permissions`
+- 执行命令：每个 job 的核心命令
+- 安全影响：是否读取 secrets、是否写仓库、是否评论 PR
+- 验证方式：本地命令或 GitHub Actions dry run 结果
+
+---
+
+## 相关 Skills
+
+- `hai-build` — 项目结构与质量门禁总览
+- `hai-app-tests` — Vitest / Playwright 测试规范
+- `hai-pr-review` — PR 审查与 AI Review 策略
+- `hai-deploy` — 应用部署与云服务开通
+- `hai-framework-sync` — hai-framework 与应用仓库同步策略

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

@@ -1,11 +1,11 @@
 ---
 name: hai-core
-description: 使用 @h-ai/core 进行配置加载、日志记录、i18n 国际化、HaiResult 错误处理与模块生命周期管理；当需求涉及 core.init、core.logger、core.config、core.i18n、ok/err 或模块初始化模式时使用。
+description: 使用 @h-ai/core 进行配置加载、日志记录、i18n 国际化、HaiResult 错误处理、Zod 校验错误本地化与模块生命周期管理；当需求涉及 core.init、core.logger、core.config、core.i18n、core.zodValidation、ok/err 或模块初始化模式时使用。
 ---
 
 # hai-core
 
-> `@h-ai/core` 是 hai-framework 的基础模块，提供配置管理、结构化日志、国际化、HaiResult 错误模型与模块生命周期工具。所有其他模块均依赖 core。
+> `@h-ai/core` 是 hai-framework 的基础模块，提供配置管理、结构化日志、国际化、HaiResult 错误模型、Zod 校验错误本地化与模块生命周期工具。所有其他模块均依赖 core。
 
 ---
 
@@ -18,6 +18,7 @@ description: 使用 @h-ai/core 进行配置加载、日志记录、i18n 国际
 | `core.logger` | ✅ pino（结构化 JSON / pretty） | ✅ loglevel（DevTools console） |
 | `core.config` | ✅ 完整（YAML 加载、watch、validate） | ⚠️ 仅支持 `core.init({ ... })` 传入配置 |
 | `core.i18n` | ✅ | ✅ |
+| `core.zodValidation` | ✅ | ✅ |
 | `core.id` | ✅ | ✅ |
 | 工具函数 | ✅ | ✅ |
 
@@ -29,6 +30,7 @@ description: 使用 @h-ai/core 进行配置加载、日志记录、i18n 国际
 - 使用 `core.logger` 记录日志
 - 使用 `core.config` 读取/校验模块配置
 - 使用 `core.i18n` 管理多语言
+- 使用 `core.zodValidation` 将 Zod 默认英文错误映射为模块自己的 i18n 文案
 - 使用 `ok()` / `err()` 构建 HaiResult 类型返回值
 - 创建模块级 logger 或 i18n 消息获取器
 
@@ -56,6 +58,9 @@ core.logger.info('Server started', { port: 3000 })
 
 // 配置
 const dbConfig = core.config.get('db')
+
+// Zod 校验错误本地化
+const formErrors = core.zodValidation.mapZodErrorToFormErrors(zodError, getMessage)
 ```
 
 ---
@@ -210,6 +215,64 @@ m('user_created') // "用户已创建"
 m('welcome', { params: { name: '张三' } }) // "欢迎，张三"
 ```
 
+### Zod 校验错误映射 — `core.zodValidation`
+
+适用于 `@h-ai/kit`、`@h-ai/serv`、`@h-ai/api-client` 等需要把 Zod 默认英文错误
+转换为模块自身 i18n 文案的场景。优先复用 `core.zodValidation`，不要在各模块重复维护
+默认消息正则 / issue 本地化逻辑。
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `createPrefixedZodMessageGetter` | `(prefix, getMessage) => ZodMessageGetter` | 按模块前缀自动派生 `serv_validation*` / `kit_validation*` 这类消息 key |
+| `mapZodErrorToFormErrors` | `(error, getMessage) => ValidationFormError[]` | 一步完成提取 + 本地化 + 扁平化 |
+
+```typescript
+import type { ZodMessageGetter } from '@h-ai/core'
+import { core } from '@h-ai/core'
+import { z } from 'zod'
+
+const LoginSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+  nickname: z.string().min(1, '请填写昵称'),
+})
+
+const getMessage: ZodMessageGetter = (key, params) => {
+  switch (key) {
+    case 'validationEmail':
+      return '请输入合法邮箱地址'
+    case 'validationStringMin':
+      return `至少输入 ${params?.min} 个字符`
+    default:
+      return '输入不合法'
+  }
+}
+
+const result = LoginSchema.safeParse({
+  email: 'bad',
+  password: '123',
+  nickname: '',
+})
+
+if (!result.success) {
+  const getMessage = core.zodValidation.createPrefixedZodMessageGetter(
+    'serv',
+    (messageKey, params) => {
+      if (messageKey === 'serv_validationEmail')
+        return '请输入合法邮箱地址'
+      if (messageKey === 'serv_validationStringMin')
+        return `至少输入 ${params?.min} 个字符`
+      return '输入不合法'
+    },
+  )
+  const errors = core.zodValidation.mapZodErrorToFormErrors(result.error, getMessage)
+
+  errors[0]?.field // 'email'
+  errors[0]?.message // '请输入合法邮箱地址'
+  errors[2]?.message // '请填写昵称'（schema 自定义消息原样保留）
+}
+```
+
 ### ID 生成 — `core.id`
 
 | 方法           | 签名                                    | 说明                          |