@h-ai/cli 1.0.0-beta.2 → 1.0.0-beta.20

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

@@ -1,8 +1,10 @@
 # hai-ui — 详细用法
 
+HTTP/UI 边界只对明确的有效 4xx 状态公开业务提示；错误缺少 `httpStatus` 或状态非法时按 500 返回安全提示。手写业务错误须提供完整错误定义或显式状态，不能依赖缺省状态展示原文。
+
 从 [SKILL.md](SKILL.md) 选择主题后读取对应小节。代码片段展示 API 用法；省略的业务变量、schema、依赖与 return 上下文需由应用补齐。
 
-> `@h-ai/ui` 是基于 Svelte 5 Runes 的多端 UI 组件库，采用 DaisyUI v5 + Tailwind CSS v4 + Bits UI v2，内置 15 个精选 DaisyUI 主题及 high-contrast 高对比、formal 直角商务主题、内置中英日文 i18n、自动导入。内置 Shiki 代码高亮、Mermaid 图表渲染、Design Token 系统和 7 个移动端组件。
+> `@h-ai/ui` 是基于 Svelte 5 Runes 的多端 UI 组件库，采用 DaisyUI v5 + Tailwind CSS v4 + Bits UI v2，内置 15 个精选 DaisyUI 主题及 high-contrast 高对比、formal 直角商务、eye-care 暖绿护眼主题、内置中英日文 i18n、自动导入。内置 Shiki 代码高亮、Mermaid 图表渲染、Design Token 系统和 7 个移动端组件。
 
 ## 运行环境
 
@@ -39,7 +41,8 @@
 
 至少检查以下四项：
 
-- `svelte.config.*`：`autoImportHaiUi()` 在 `vitePreprocess()` 前。
+- SvelteKit 3 在 `vite.config.*` 的 `sveltekit({...})` 中设置预处理；纯 Svelte/Vite 使用 `svelte.config.*`。两者都先执行 `vitePreprocess()` 或其他样式/模板语言转换，再执行 `autoImportHaiUi()`；后者按整份 Svelte AST 定位实例脚本，不直接接受转换前的 SCSS/Pug，直接 markup 调用保持同步。
+- 自动导入只补模板中实际使用且未被脚本或模板局部作用域绑定的组件；注释、textarea 与脚本字符串里的组件示例不触发导入。
 - `vite.config.*`：`ssr.noExternal` 包含 `@h-ai/ui` 和 `@h-ai/kit`，`optimizeDeps.exclude` 包含 `bits-ui`。
 - `app.css`：已导入 `global.css` / `theme.css`；移动端还要导入 `design-tokens.css` / `mobile.css`。
 - Tailwind：已配置 `@source` 扫描 `@h-ai/ui/dist/**/*.{svelte,js,ts}`。
@@ -99,55 +102,39 @@ npm install -D tailwindcss @tailwindcss/vite daisyui
 npm install -D @iconify/tailwind4 @iconify-json/tabler
 ```
 
-Node adapter 使用 Crypto、Kit 或 IAM 时，还需将 `sm-crypto@0.5.7` 作为直接生产依赖安装，保留 Node 原生模块解析。
-
-### 2. svelte.config.js
+Node adapter 使用 Crypto、Kit 或 IAM 时，还需将 `sm-crypto@0.5.8` 作为直接生产依赖安装，保留 Node 原生模块解析。
 
-```js
-import { autoImportHaiUi } from '@h-ai/ui/auto-import'
-import adapter from '@sveltejs/adapter-node'
-import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
-
-/** @type {import('@sveltejs/kit').Config} */
-const config = {
-  // autoImportHaiUi 必须在 vitePreprocess 之前
-  preprocess: [autoImportHaiUi(), vitePreprocess()],
-  compilerOptions: {
-    runes: true, // 强制 Svelte 5 Runes 模式
-  },
-  kit: {
-    adapter: adapter(),
-    alias: {
-      $components: './src/lib/components',
-      $stores: './src/lib/stores',
-    },
-  },
-}
+### 2. package.json 的应用导入
 
-export default config
+```json
+{ "imports": { "#lib/*": "./src/lib/*" } }
 ```
 
 ### 3. vite.config.ts
 
+SvelteKit 3 的预处理、编译器和适配器统一配置在 Vite 插件；纯 Svelte/Vite 工程保留自己的 svelte.config.js。
+
 ```ts
+import { autoImportHaiUi } from '@h-ai/ui/auto-import'
+import { haiOptimizeExclude, haiPrebundledDeps } from '@h-ai/ui/vite'
+import adapter from '@sveltejs/adapter-node'
 import { sveltekit } from '@sveltejs/kit/vite'
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
 import tailwindcss from '@tailwindcss/vite'
 import { defineConfig } from 'vite'
 
 export default defineConfig({
   plugins: [
-    sveltekit(),
+    sveltekit({
+      preprocess: [vitePreprocess(), autoImportHaiUi()],
+      compilerOptions: { runes: true },
+      adapter: adapter(),
+      paths: { relative: false },
+    }),
     tailwindcss(),
   ],
-  optimizeDeps: {
-    // bits-ui 使用 Svelte 虚拟模块，需排除预构建
-    exclude: ['bits-ui'],
-  },
-  ssr: {
-    // @h-ai 包为 ESM + Svelte 组件，需 Vite 在 SSR 时处理
-    noExternal: ['@h-ai/ui', '@h-ai/kit'],
-    external: ['@h-ai/core', 'sm-crypto'],
-  },
+  optimizeDeps: { exclude: [...haiOptimizeExclude], include: [...haiPrebundledDeps] },
+  ssr: { noExternal: ['@h-ai/ui', '@h-ai/kit'], external: ['@h-ai/core', 'sm-crypto'] },
 })
 ```
 
@@ -273,13 +260,15 @@ const p = usePlatform()
 | `Skeleton`   | `variant`, `count`, `animation`                                    | 骨架屏        |
 | `Empty`      | `title`, `description`, `icon`                                     | 空状态        |
 
+滚动或裁剪容器中的 `Dropdown` 使用默认 `click` 或 `hover` 触发，菜单挂载到 `body`。由调用方控制开关时，使用 `trigger='manual'`，通过 `class` 切换 `dropdown-open` 显示内联菜单。`Popover` 默认挂载到 `body`，`click` 模式下键盘打开后焦点进入面板，Escape 关闭并返回触发控件。
+
 #### 移动端组合组件（7 个）
 
 | 组件             | Props 要点                                                                    | 说明             |
 | ---------------- | ----------------------------------------------------------------------------- | ---------------- |
 | `SafeArea`       | `top`, `bottom`, `left`, `right`                                              | 安全区域容器     |
 | `AppBar`         | `title`, `backHref`, `onback`, `fixed`, `transparent`, snippet `left`/`right` | 顶部导航栏       |
-| `BottomNav`      | `items: BottomNavItem[]`, `active`                                            | 底部导航栏       |
+| `BottomNav`      | `items: BottomNavItem[]`, `active`                                            | 底部导航栏，客户端挂载后启用按钮 |
 | `ActionSheet`    | `open`, `title`, `items: ActionSheetItem[]`, `cancelText`, `onselect`         | 底部弹出操作面板 |
 | `PullRefresh`    | `refreshing`, `onrefresh`, `threshold`, `pullText`, `releaseText`             | 下拉刷新         |
 | `InfiniteScroll` | `loading`, `finished`, `threshold`, `onload`, `loadingText`, `finishedText`   | 无限滚动加载     |
@@ -365,6 +354,8 @@ const p = usePlatform()
 | `RegisterForm` | `fields`, `minPasswordLength`, `errors`         | 注册表单 |
 | `UserProfile`  | `user`, `editable`, `fields`, `avatarAccept`, `avatarHint` | 用户资料，选择器和提示对齐业务校验；最终验证和上传仍由回调负责 |
 
+`UserProfile.onsubmit` 必须返回 `true` / `false` 表示保存成功 / 失败；仅成功退出编辑，失败保留编辑器与草稿。宿主在失败时更新错误提示并返回 `false`，不要把失败转换成正常关闭。
+
 #### 错误页 / 设置场景组件
 
 | 组件             | Props 要点                                  | 说明     |
@@ -546,7 +537,7 @@ form={{ variant: 'drawer', drawerWidth: '40rem' }}
 
 ## 主题系统
 
-支持 15 个精选 DaisyUI 主题及 high-contrast 高对比、formal 直角商务主题。
+支持 15 个精选 DaisyUI 主题及 high-contrast 高对比、formal 直角商务、eye-care 暖绿护眼主题。
 
 ```typescript
 import { applyTheme, getCurrentTheme, getSavedTheme, isDarkTheme, THEMES, THEME_GROUPS } from '@h-ai/ui/theme'

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

@@ -6,6 +6,8 @@
 
 ## 运行环境
 
+pgvector 将集合 metric 持久保存在 vector 列注释，索引、info、search 使用同一值；重连后修改默认 metric 不改变已有集合。旧集合从实际索引恢复；缺少索引与有效注释时先恢复定义，不按当前默认值猜测。
+
 > ⚠️ **服务端模块（Node.js only）。** 浏览器端不直接操作向量数据库，通过 `@h-ai/ai` 的 API 端点间接使用（如 RAG 检索、知识库查询）。
 
 ## 适用场景
@@ -62,9 +64,12 @@ operationLog:
 
 ```typescript
 import { core } from '@h-ai/core'
-import { vecdb } from '@h-ai/vecdb'
+import { vecdb, VecdbConfigSchema } from '@h-ai/vecdb'
 
-await vecdb.init(core.config.get('vecdb'))
+const config = core.config.validate('vecdb', VecdbConfigSchema)
+if (!config.success) throw new Error(config.error.message)
+const initialized = await vecdb.init(config.data)
+if (!initialized.success) throw new Error(initialized.error.message)
 // ... 使用向量数据库
 const closeResult = await vecdb.close()
 if (!closeResult.success) {
@@ -182,7 +187,7 @@ Chroma 直连 `url` 仅支持 HTTP(S) 根端点，优先于 `host/port`；URL
 
 直连初始化总截止为 5 秒，本地服务拉起使用 `startupTimeout`；超时中止候选 HTTP 请求。成功清除初始化 timer，不限制后续业务请求。
 
-Qdrant 使用 `@qdrant/js-client-rest 1.18.0`，仅支持未命名向量字段的 cosine/euclidean/dot；外部 named-vector/Manhattan 集合的 info/写入/搜索返回 CONFIG_ERROR，不猜测维度或 metric。Chroma 使用 `chromadb 3.5.0` 的真实类型及 metadata/filter 校验，非法输入返回操作错误，不丢弃过滤；content 可省略。各后端的 null 和复杂元数据语义不承诺统一。
+Qdrant 使用原生 HTTP 固定 REST 端点，无额外 SDK 依赖；超时 30 秒覆盖完整响应体，响应超过 16 MiB 明确失败。仅支持未命名向量字段的 cosine/euclidean/dot；外部 named-vector/Manhattan 集合的 info/写入/搜索返回 CONFIG_ERROR，不猜测维度或 metric。Chroma 使用 `chromadb 3.5.0` 的真实类型及 metadata/filter 校验，非法输入返回操作错误，不丢弃过滤；content 可省略。各后端的 null 和复杂元数据语义不承诺统一。
 
 **VectorDocument**：