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

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}`。
@@ -72,6 +75,7 @@
 | 登录/注册页布局 | `AuthShell` + `LoginForm` / `RegisterForm` | `variant='card'` 或 `'split'`；split 可通过 `illustration`/`description`/`highlights` 放大图与重点说明 |
 | 登录/注册/资料页 | `LoginForm` / `RegisterForm` / `UserProfile` | 页面只负责路由和提交逻辑 |
 | 文件/图片上传 | `FileUpload` / `ImageUpload` / `AvatarUpload` | 上传 URL、限制和业务状态由应用层提供 |
+| 在线代码浏览与检查 | `CodeWorkspace` | 两个读取回调接入文件树与多标签，按需添加工作区搜索、检查面板和选区操作 |
 | 移动端页面骨架 | `SafeArea` + `AppBar` + `BottomNav` | 原生壳页面优先这一套 |
 | AI 文档/Markdown 展示 | `MarkdownRenderer` / `AiDocumentEditor` | Mermaid、代码高亮、复制/下载已内置 |
 
@@ -99,55 +103,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
-
-```js
-import { autoImportHaiUi } from '@h-ai/ui/auto-import'
-import adapter from '@sveltejs/adapter-node'
-import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
+Node adapter 使用 Crypto、Kit 或 IAM 时，还需将 `sm-crypto@0.5.8` 作为直接生产依赖安装，保留 Node 原生模块解析。
 
-/** @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 +261,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`   | 无限滚动加载     |
@@ -347,6 +337,33 @@ const p = usePlatform()
 
 内置中英日文翻译的业务场景组件。
 
+#### 代码工作区
+
+`CodeWorkspace` 提供异步文件树、只读 Monaco 代码区和可选的检查面板。从 `@h-ai/ui/components/scenes/code/index` 导入组件和类型。
+
+```svelte
+<script lang="ts">
+  import type { CodeWorkspaceSource } from '@h-ai/ui/components/scenes/code/index'
+  import { CodeWorkspace } from '@h-ai/ui/components/scenes/code/index'
+
+  const source: CodeWorkspaceSource = {
+    listChildren: () => [{ kind: 'file', id: 'readme', name: 'README.md' }],
+    readFile: () => ({ text: '# Hello', language: 'markdown' }),
+  }
+</script>
+
+<CodeWorkspace {source} />
+```
+
+- `listChildren(null, signal)` 读取根节点。目录展开时组件传入目录节点并复用已加载的结果。文件 ID 与版本用于复用标签和恢复视图。`initialFile` 与 `initialAncestors` 可预先打开文件并展开其父目录。保持 `source` 对象引用稳定，切换仓库或分支时替换对象。
+- 可选的 `search({ mode, query, cursor }, signal)` 接入宿主索引。`mode` 是 `files` 或 `content`。命中包含 `node`，可附带 `ancestors`、`range` 和 `preview`。返回 `nextCursor` 启用续页。把收到的 `signal` 传给实际请求，后端负责授权与索引范围。回调失败时可抛错或拒绝 Promise，组件会提供重试入口。
+- 节点的 `markers` 使用 `label` 提供可访问名称，按需附加 `text` 和 `tone`。`readFile` 返回的 `annotations` 使用 `range`、`label` 和可选的 `tone`、`display`，可在行前和对应范围内显示。搜索命中与标注应使用同一文件版本，行列从 1 开始，列按 UTF-16 计数，结束位置不含。
+- `inspector` snippet 收到 `{ file, selection, reveal }`，其中 `selection` 可以为 `null`。`selectionActions` 收到非空选区、同一 `file`、`reveal` 和 `openInspector`。`reveal(range)` 仅在对应文档仍激活时跳转，`openInspector()` 可打开已有右栏。解释、标记保存等宿主操作从这两个入口接入。
+- 工作区内 `Ctrl/⌘+P` 找文件，`Ctrl/⌘+Shift+F` 搜工作区内容；代码区 `Ctrl/⌘+F` 查找，`Ctrl/⌘+G` 跳行；`Alt+Shift+Enter` 聚焦可用的选区操作。通过 `options` 设置行号、缩略图、面包屑和换行的初始值，用户可在工具栏切换。
+- `theme` 默认 `inherit`，另有 `vs-light`、`vs-dark`、`hc-light`、`hc-dark` 和 `github-dark`。自定义主题传入 `{ base, colors, tokens }`，其中 `base` 是 VS 或高对比预设，`colors` 和 `tokens` 可省略。同页 Monaco 实例共享编辑器主题。工作区外壳可 SSR，Monaco 及默认同源 worker 由 Vite 在浏览器按需加载。移动端和编辑器加载失败时使用纯文本视图。
+
+行前图标和浮层可通过 `annotationIcon`、`annotationHover` Snippet 自定义，两者收到 `{ file, annotation }`。仅需提示文字时，在标注上传入 `hoverText`，它优先于浮层 Snippet。图标锚定标注起始行，支持悬停、键盘和点击。
+
 #### 引导与帮助场景组件
 
 | 组件 | Props 要点 | 说明 |
@@ -365,6 +382,8 @@ const p = usePlatform()
 | `RegisterForm` | `fields`, `minPasswordLength`, `errors`         | 注册表单 |
 | `UserProfile`  | `user`, `editable`, `fields`, `avatarAccept`, `avatarHint` | 用户资料，选择器和提示对齐业务校验；最终验证和上传仍由回调负责 |
 
+`UserProfile.onsubmit` 必须返回 `true` / `false` 表示保存成功 / 失败；仅成功退出编辑，失败保留编辑器与草稿。宿主在失败时更新错误提示并返回 `false`，不要把失败转换成正常关闭。
+
 #### 错误页 / 设置场景组件
 
 | 组件             | Props 要点                                  | 说明     |
@@ -546,7 +565,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'
@@ -660,6 +679,7 @@ AuthPanel 在 SSR 阶段禁用原生表单控件，客户端挂载并绑定事
 | `@h-ai/ui/auto-import`     | Svelte 预处理器：组件自动导入          |
 | `@h-ai/ui/components/primitives/index` 等明确 barrel | 仅 package.exports 列出的组件目录；组件默认导出经 barrel 转发 |
 | `@h-ai/ui/components/primitives/index` | 公开原子组件目录入口，如 Button/Input |
+| `@h-ai/ui/components/scenes/code/index` | `CodeWorkspace` 与代码工作区接入类型 |
 | `@h-ai/ui/styles/global.css`       | 全局基础样式（重置/滚动条/焦点）       |
 | `@h-ai/ui/styles/theme.css`        | Tailwind v4 `@theme` Token            |
 | `@h-ai/ui/styles/design-tokens.css`| CSS 自定义属性（间距/圆角/z-index）    |

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**：