@h-ai/cli 0.1.0-alpha9 → 1.0.0-beta.2

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

@@ -0,0 +1,280 @@
+# hai-api-contract 参考
+
+> `@h-ai/api-contract` 是 hai-framework 的公共 HTTP API 契约包，使用 oRPC contract + Zod v4 作为唯一接口真相源。本包只描述接口边界，不包含任何 procedure 实现。
+
+## 运行环境
+
+独立 contract 包发布前验证实际声明构建。`ContractProcedureBuilderWithInputOutput`、`ContractProcedureBuilderWithOutput`、`Schema` 直接复用上游公共类型，由 `@h-ai/api-contract` 类型转出，供推导声明与显式 `import type` 使用；不手写仿造类型或导入 node_modules 内部路径。
+
+> ✅ **契约定义包，无服务端业务依赖；Zod/oRPC schema 构造仍有运行时代码。** 可在客户端、服务端、测试环境直接引用。
+
+## 适用场景
+
+- 定义新领域的 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(),
+})
+
+// 同一 contract 内两个接口复用，因此保留为文件私有常量，不从 schemas 导出。
+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（非流式补全/消息/历史）、memories（召回/列表）、sessions（列表） |
+| `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/completions，非流式 JSON
+```
+
+### `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 getWidget = apiContract
+  .route({ method: 'GET', path: '/widgets/{id}' })
+  .output(apiContract.haiResultSchema(z.object({
+    id: z.string(),
+    name: z.string(),
+  })))
+
+// 等价于:
+// { success: true, data: { id: string, name: string } }
+// | { success: false, error: HaiError }
+```
+
+### `apiContract.pathOf(procedure)` — 读取业务路径
+
+```typescript
+const refreshPath = apiContract.pathOf(apiContract.iam.auth.refresh)
+// '/auth/refresh'
+```
+
+middleware、client 与 E2E 需要业务路径时从 contract 元数据读取，不维护第二份 route 常量。服务端挂载时再与 `_serv.yml` 的 `http.apiPrefix` 拼接。
+
+### 公共 Schema 工具
+
+| 访问路径 | 说明 |
+| --- | --- |
+| `apiContract.haiResultSchema(dataSchema)` | `HaiResult<T>` 输出包装 |
+| `apiContract.voidResultSchema` | `HaiResult<void>` 空结果包装 |
+| `apiContract.paginatedSchema(itemSchema)` | 分页列表输出 Schema |
+| `HaiErrorSchema` | HaiError 公共字段 Schema |
+| `PaginationQuerySchema` | 分页参数 Schema（可选 page/pageSize，pageSize 上限 100；默认值由服务端处理） |
+
+## Contract 定义规范
+
+### 必须遵循
+
+- **输出必须包装为 `apiContract.haiResultSchema`** — 客户端依赖 `success` 判断成功/失败
+- **业务 path 直接写在对应 `*-contract.ts`** — 禁止新增 `*-routes.ts` 或业务路径常量
+- **一次性 `*OutputSchema` 直接内联** — 不在 schemas 文件声明或导出
+- **同一 contract 内重复使用的输出可设私有常量** — 不得为复用扩大公共导出
+- **公共 HTTP 传输配置以配置文件为准** — API 前缀、健康检查、OpenAPI/docs、密钥协商路径与跨端 Header 放在 service 的 `_serv.yml`，不放 contract 包
+- **schemas 只保留真实复用结构** — 至少被多个接口或 contract/procedure 等不同层共同消费
+- **`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
+- ❌ 导出只被单个 contract 接口使用的 `*OutputSchema`
+- ❌ 用独立 `*-routes.ts` 维护业务接口路径
+
+### 文件职责
+
+| 文件 | 只负责 |
+| --- | --- |
+| `*-contract.ts` | 业务接口 path、method、输入与输出边界 |
+| `*-schemas.ts` | 跨接口或跨层复用的输入、实体、数据结构 |
+| service `config/_serv.yml` | API 前缀、基础设施端点、跨端 Header 与加密 transport 配置 |
+
+## 常见模式
+
+### 带分页的列表接口
+
+```typescript
+import { apiContract, PaginationQuerySchema } 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(PaginationQuerySchema.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 versionContract = apiContract
+  .route({ method: 'GET', path: '/system/version', operationId: 'system.version', tags: ['system'] })
+  .output(apiContract.haiResultSchema(z.object({ version: 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-app-create/SKILL.md

@@ -1,371 +1,58 @@
 ---
 name: hai-app-create
-description: 以 TDD 方式在应用中创建新功能：先编写测试定义行为，再编码实现直至测试通过；当需求涉及新增页面/路由、API、服务、数据模型、组件时使用。
+description: "在 hai 应用中新增、修改或修复功能，按需求复用框架能力并验证安全、质量与风格。"
 ---
 
-# hai-app-create — TDD 驱动的应用功能创建规范
+# hai-app-create
 
-> 面向 AI 助手的应用功能创建指南。**必须遵循 TDD**：先写测试（Red）→ 再实现（Green）→ 再重构（Refactor）。
+## 能力契约
 
----
-
-## 适用场景
-
-- 新增页面（路由）
-- 新增 API 端点
-- 新增服务层模块（`$lib/server/services/`）
-- 新增数据库表 / 数据模型
-- 新增业务组件
-
----
-
-## TDD 开发流程（强制）
-
-创建任何新功能时，必须按以下顺序执行：
-
-### Step 1：需求分析与测试设计
-
-1. 明确功能的输入、输出、边界条件、错误场景
-2. 确定需要创建的文件（服务、路由、Schema、组件等）
-3. 设计测试用例清单（参照 `hai-app-tests` 技能的覆盖范围要求）
-
-### Step 2：编写测试（Red 阶段）
-
-1. **创建单元测试**：在 `tests/` 下为服务层、Schema 编写 Vitest 测试
-2. **创建 E2E 测试**：在 `e2e/` 下为 API 端点、页面交互编写 Playwright 测试
-3. **创建空的实现文件**：仅包含函数签名和类型定义，不写实际逻辑（确保 import 不报错）
-4. **运行测试确认全部失败**：
-   ```bash
-   pnpm --filter <app-name> test        # 应全部 FAIL
-   ```
-
-### Step 3：编写实现（Green 阶段）
-
-按照下文的「创建指南」编写实际功能代码，每完成一个功能点立即运行测试确认通过。
-
-### Step 4：重构与验证（Refactor 阶段）
-
-1. 参照 `hai-app-review` 审查代码规范
-2. 运行质量门禁：`pnpm typecheck && pnpm lint && pnpm test`
-3. 运行 E2E：`pnpm --filter <app-name> test:e2e`
-
----
-
-## 目录结构约定
-
-```
-src/
-  hooks.server.ts                # Handle Hook 入口
-  app.css                        # 全局样式（TailwindCSS 4）
-  lib/
-    server/
-      init.ts                    # 应用初始化（模块 init 顺序）
-      services/                  # 业务服务层（Server-only）
-        index.ts                 # 服务聚合导出
-        user.ts                  # 示例：用户服务
-      schemas/                   # 请求校验 Schema（Zod）
-    components/                  # 业务组件（非 @h-ai/ui 通用组件）
-    stores/                      # 客户端 Store（Svelte 5 Runes）
-    paraglide/                   # i18n 生成文件（禁止手动修改）
-  routes/
-    +layout.svelte               # 根布局
-    +page.svelte                 # 首页
-    (auth)/                      # 认证分组路由
-      login/+page.svelte
-    admin/                       # 管理区域
-      users/
-        +page.svelte             # 列表页
-        +page.server.ts          # 列表数据加载
-        [id]/
-          +page.svelte           # 详情页
-          +page.server.ts
-    api/                         # API 端点
-      auth/+server.ts
-      health/+server.ts
-      iam/
-        users/+server.ts
-  messages/                      # i18n 消息文件
-    en-US.json
-    zh-CN.json
-  config/                        # 模块配置文件
-    _core.yml
-    _db.yml
-    _cache.yml
-    _iam.yml
-```
-
----
-
-## 创建页面
-
-### 页面路由规则
-
-使用 SvelteKit 文件路由，参考 `src/routes/` 约定：
-
-| 类型     | 路径示例                           | 说明                 |
-| -------- | ---------------------------------- | -------------------- |
-| 静态页面 | `routes/about/+page.svelte`        | 常规页面             |
-| 动态路由 | `routes/users/[id]/+page.svelte`   | URL 参数             |
-| 分组路由 | `routes/(auth)/login/+page.svelte` | 共享布局，不影响 URL |
-| API 端点 | `routes/api/users/+server.ts`      | RESTful API          |
-
-### 页面文件模板
-
-```svelte
-<!-- +page.svelte -->
-<script lang="ts">
-  // Svelte 5 Runes 语法
-  let { data } = $props()
-  let loading = $state(false)
-
-  async function handleAction() {
-    loading = true
-    try {
-      // 业务逻辑
-    } finally {
-      loading = false
-    }
-  }
-</script>
-
-<div class="container mx-auto p-4">
-  <!-- 使用 @h-ai/ui 组件 -->
-</div>
-```
-
-### 数据加载（+page.server.ts）
-
-```typescript
-import type { PageServerLoad } from './$types'
-import { kit } from '@h-ai/kit'
-
-export const load: PageServerLoad = async (event) => {
-  // 权限守卫
-  const guard = kit.guard.requireAuth(event)
-  if (!guard.success)
-    return kit.response.redirect('/login')
-
-  // 加载数据
-  const result = await someService.list()
-  if (!result.success)
-    return kit.response.error(500, result.error.message)
-
-  return { items: result.data }
-}
-```
-
----
-
-## 创建 API 端点
-
-### RESTful 端点模板
-
-```typescript
-// src/routes/api/[resource]/+server.ts
-import type { RequestHandler } from './$types'
-import { kit } from '@h-ai/kit'
-import { z } from 'zod'
+| 项目 | 契约 |
+| --- | --- |
+| 能力 | 在 hai 应用中新增、修改或修复页面、API、服务、模型与组件 |
+| 适用场景 | 日常应用功能开发与已授权修复 |
+| 输入 | 功能需求、现有路由/contract、数据模型和验收场景 |
+| 输出 | 能力选择依据、最小实现、行为验证、i18n 与受影响文档 |
+| 限制 | 优先复用；TDD 验证本次目标行为，仍适用的回归保持通过。保留 API workspace 架构时不混入 SvelteKit 路由。 |
 
-const CreateSchema = z.object({
-  name: z.string().min(1).max(100),
-  description: z.string().optional(),
-})
+## 使用路径
 
-// GET - 列表
-export const GET = kit.handler(async ({ locals }) => {
-  kit.guard.requirePermission(locals.session, 'resource:read')
+沟通、问题状态与文档/配置/截图/测试/模板/调用方同步遵循[沟通与同步维护](collaboration.md)。
 
-  const result = await service.list()
-  if (!result.success)
-    return kit.response.error(500, result.error.message)
-  return kit.response.ok(result.data)
-})
+范围、验收、复用依据和证据按 [工作交接契约](../hai-spec-implement/handoff.md) 贯穿实现、测试和审查；小改动使用简短记录，文档驱动任务沿既有任务记录续跑。
 
-// POST - 创建
-export const POST = kit.handler(async ({ request, locals }) => {
-  kit.guard.requirePermission(locals.session, 'resource:create')
+业务以用户当前明确要求及其指定文档为准；模板规则、生成代码与测试只描述初始方案。需求改变角色、流程、限额或架构时，在已有授权范围内同步调整冲突实现及过期 AGENTS/skills/README，不要求把需求改回模板。具体判定见 [development.md](development.md#需求与模板的关系)。
 
-  const data = await kit.validate.formOrFail(request, CreateSchema)
+从需求/设计文档开始生成项目或功能前，使用 [hai-spec-review](../hai-spec-review/SKILL.md) 检查文档是否足以确定实现；修正影响行为的缺项、歧义和技术错误后再进入生成。普通小改动按本次范围确认规则，不要求重审无关文档。
 
-  const result = await service.create(data)
-  if (!result.success)
-    return kit.response.error(500, result.error.message)
-  return kit.response.created(result.data)
-})
-```
+需要按文档规划/执行、返修或根据已提交文档差异同步实现时，使用 [hai-spec-implement](../hai-spec-implement/SKILL.md) 管理 docs 清单、任务记录、文档基线、TDD 和任务分支；本 skill 负责其中的具体应用实现，复用固定目标版本、范围与验收。
 
-### 要点
+需要新建项目、添加模块、补齐配置或生成代码时，先按 [CLI 安装与命令](development.md#cli-安装与命令) 全局安装 `@h-ai/cli`，再执行 `hai` 命令。
 
-- 所有端点**必须**用 `kit.handler(async ({ locals, request, ... }) => { ... })` 包裹，由 handler 统一处理 throw 的 Response
-- 权限守卫使用 `kit.guard.requirePermission(locals.session, 'xxx:yyy')`，它本身就是 throw 模式（未通过时 throw 403 Response），**无需**检查返回值
-- 输入校验使用 `await kit.validate.formOrFail(request, Schema)`，校验失败时 throw 400 Response，**无需**手动判断 valid
-- 返回统一使用 `kit.response.*`
-- HaiResult 错误直接透传，不重新包装
-- 框架模块 API 不抛异常，不要用 `try/catch` 处理模块返回的错误，直接检查 `result.success`
+1. 读取 [development.md](development.md)：先按真实需求匹配框架能力、已安装版本与应用架构，再确定改动。适用能力包括同一模块已有 feature、配置和扩展点，不以导入包作为复用完成的证据。
+2. 读取所选模块的 skill 与实际公开类型，复用现有服务和组件。新增依赖或直接使用第三方 SDK 前说明已有能力的具体缺口；无需安装无关模块。
+3. 新增或改变行为时用有意义的目标用例验证，仍适用的回归保持通过；被明确新需求替代的模板断言同步更新并记录依据。按下方参考实现，使用 [hai-app-review](../hai-app-review/SKILL.md) 检查改动涉及的安全与质量边界。
+4. 按 [分轮验证与集中修复](../hai-app-tests/validation.md) 运行已有门禁：一轮先收集所有可执行结果，再归并修复、复测失败及受影响项；报告行为证据、能力选择及未验证项。纯文案、格式和文档变化按影响验证，不强制新增测试。
 
----
-
-## 创建服务层
-
-服务层位于 `$lib/server/services/`，处理业务逻辑。
-
-```typescript
-import type { HaiResult } from '@h-ai/core'
-// src/lib/server/services/article.ts
-import { core } from '@h-ai/core'
-import { reldb } from '@h-ai/reldb'
-
-const logger = core.logger
-
-/** 创建文章 */
-export async function createArticle(input: CreateArticleInput): Promise<HaiResult<Article>> {
-  logger.debug('Creating article', { title: input.title })
-
-  const result = await reldb.crud.create('articles', {
-    id: crypto.randomUUID(),
-    ...input,
-    created_at: new Date().toISOString(),
-  })
-  if (!result.success)
-    return result
-
-  logger.info('Article created', { id: result.data.id })
-  return result
-}
-
-/** 获取文章列表 */
-export async function listArticles(params: ListParams): Promise<HaiResult<PaginatedResult<Article>>> {
-  logger.debug('Listing articles', { page: params.page })
-  return reldb.crud.paginate('articles', params)
-}
-```
-
-### 服务层规则
+## 按需参考
 
-- 统一返回 `HaiResult<T>`
-- 写操作需 `debug`（进入）+ `info`（成功）日志
-- 读操作仅 `debug` 日志
-- 禁止 `console.log`，使用 `core.logger`
-- 服务层不处理 HTTP 响应格式，只返回 HaiResult
+界面新建或明显改变信息结构时先用已交付的 hai-ui-design 确定页面模式、状态和组件映射；使用 hai-ui 的当前版本契约实现，以 hai-ui-review 的真实页面检查收尾。窄范围修复直接复用既有设计。界面方案与最终实现的差异需回写适用设计记录。
 
----
-
-## 创建数据模型
-
-### Schema 定义（SQL DDL）
-
-数据库表 Schema 定义在 `$lib/server/init.ts` 中：
-
-```typescript
-const BUSINESS_SCHEMA = `
-CREATE TABLE IF NOT EXISTS articles (
-  id TEXT PRIMARY KEY,
-  title TEXT NOT NULL,
-  content TEXT,
-  author_id TEXT NOT NULL,
-  status TEXT DEFAULT 'draft',
-  created_at TEXT DEFAULT (datetime('now')),
-  updated_at TEXT DEFAULT (datetime('now'))
-);
+带前端的工程新增引导或帮助时，读取本工程 `hai-ui` Skill 中的 `guide.md`，复用 fullstack 的共享 guide-store、locale 与稳定 data-guide 锚点；纯 API 工程不需要 UI 指引。
 
-CREATE INDEX IF NOT EXISTS idx_articles_author_id ON articles(author_id);
-CREATE INDEX IF NOT EXISTS idx_articles_status ON articles(status);
-`
-```
-
-### 类型定义
-
-```typescript
-// 在服务文件或独立类型文件中定义
-interface Article {
-  id: string
-  title: string
-  content: string | null
-  authorId: string
-  status: 'draft' | 'published' | 'archived'
-  createdAt: string
-  updatedAt: string
-}
-
-interface CreateArticleInput {
-  title: string
-  content?: string
-  authorId: string
-}
-```
-
----
-
-## 创建业务组件
-
-业务组件放在 `$lib/components/`，通用 UI 使用 `@h-ai/ui`。
-
-```svelte
-<!-- src/lib/components/ArticleCard.svelte -->
-<script lang="ts">
-  import type { Article } from '$lib/server/services/article'
-
-  let { article, onEdit }: { article: Article, onEdit?: () => void } = $props()
-</script>
-
-<div class="card bg-base-100 shadow">
-  <div class="card-body">
-    <h2 class="card-title">{article.title}</h2>
-    <p>{article.content ?? ''}</p>
-    {#if onEdit}
-      <div class="card-actions justify-end">
-        <button class="btn btn-primary" onclick={onEdit}>编辑</button>
-      </div>
-    {/if}
-  </div>
-</div>
-```
-
-### 组件规则
-
-- 使用 Svelte 5 Runes 语法（`$props()`、`$state()`、`$derived()`、`$effect()`）
-- 事件回调通过 props 传入（非 `createEventDispatcher`）
-- 样式使用 TailwindCSS 4 + DaisyUI 5 class
-- 通用 UI 组件优先使用 `@h-ai/ui`，不重复实现
-- i18n 文本使用 `$lib/paraglide/messages.js` 中的 key
-
----
-
-## 初始化顺序
-
-在 `$lib/server/init.ts` 中管理模块初始化顺序：
-
-```
-core.init() → reldb.init() → cache.init() → iam.init() → createBusinessTables()
-```
-
-新增模块时需在此文件中按依赖顺序添加初始化调用。
-
----
-
-## 检查清单
-
-- [ ] **TDD 流程已执行**：先写测试 → 确认失败 → 再实现 → 确认通过
-- [ ] 单元测试已编写（服务层、Schema）
-- [ ] E2E 测试已编写（API 端点、页面交互）
-- [ ] 页面使用 Svelte 5 Runes 语法
-- [ ] API 端点有权限守卫与输入校验
-- [ ] 服务层统一返回 `HaiResult<T>`
-- [ ] 日志级别正确（读 debug / 写 debug+info / 失败 warn|error）
-- [ ] 禁止 `console.log`、`any`、硬编码密钥
-- [ ] 用户可见文本走 i18n
-- [ ] 新增表有索引定义
-- [ ] 组件优先使用 `@h-ai/ui`
-- [ ] `pnpm typecheck && pnpm lint && pnpm test` 通过
-
----
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
-## 相关 Skills
+- 适用场景
+- 行为开发与验证
+- 目录结构约定
+- 创建页面
+- 创建 API 端点
+- 创建服务层
+- 创建数据模型
+- 创建业务组件
+- 初始化顺序
+- 容器交付
+- 检查清单
+- 相关 Skills
 
-- `hai-build`：项目架构与模块初始化顺序
-- `hai-app-tests`：TDD 测试规范（Red 阶段详细指引）
-- `hai-app-review`：代码审查规范（Refactor 阶段参照）
-- `hai-kit`：SvelteKit 集成的完整 API
-- `hai-ui`：UI 组件库使用
-- `hai-reldb`：数据库操作详细 API
-- `hai-iam`：认证与权限管理
+宿主生命周期优先 core.module.createRuntime([{name,enabled?,start,close}])：声明真实顺序与业务钩子，失败回滚，关闭失败保留依赖和义务待重试。不要在应用复制并发/回滚/关闭状态机；纯函数与 core 配置不臆造 init/close。错误只报告模块、阶段、错误码和配置路径，不传播私密值。