@h-ai/cli 0.1.0-alpha.66 → 0.1.0-alpha.68

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

@@ -2,7 +2,7 @@
 
 从 [SKILL.md](SKILL.md) 选择主题后读取对应小节。代码片段展示 API 用法；省略的业务变量、schema、依赖与 return 上下文需由应用补齐。
 
-> `@h-ai/ui` 是基于 Svelte 5 Runes 的多端 UI 组件库，采用 DaisyUI v5 + Tailwind CSS v4 + Bits UI v2，内置 15 个精选 DaisyUI 主题、内置中英文 i18n、自动导入。内置 Shiki 代码高亮、Mermaid 图表渲染、Design Token 系统和 7 个移动端组件。
+> `@h-ai/ui` 是基于 Svelte 5 Runes 的多端 UI 组件库，采用 DaisyUI v5 + Tailwind CSS v4 + Bits UI v2，内置 15 个精选 DaisyUI 主题、内置中英日文 i18n、自动导入。内置 Shiki 代码高亮、Mermaid 图表渲染、Design Token 系统和 7 个移动端组件。
 
 ## 运行环境
 
@@ -28,7 +28,7 @@
 
 - **优先复用 `@h-ai/ui` 现有组件**，不要在 app 中重复实现同类按钮、表格、表单、弹层或场景页面。
 - **页面级文案与业务逻辑放在应用层**；`@h-ai/ui` 负责展示与交互，不承接业务服务、数据库访问或页面级 i18n 管理。
-- **场景组件自带内置中英文文案**（如 IAM / CRUD / AI / Storage 场景），除非组件显式提供覆盖 prop，否则不要把页面翻译样板再传进去。
+- **场景组件自带内置中英日文文案**（如 IAM / CRUD / AI / Storage 场景），除非组件显式提供覆盖 prop，否则不要把页面翻译样板再传进去。
 - **自动导入不是全能魔法**：`toast`、类型导入和 `Range` 仍需显式 `import`；其它公开 Svelte 组件可交给 `autoImportHaiUi()`。
 - **移动端组件不是样式糖**：使用 `SafeArea` / `BottomNav` / `PullRefresh` / `ActionSheet` 时，务必同步引入 `design-tokens.css` 与 `mobile.css`。
 
@@ -39,7 +39,7 @@
 至少检查以下四项：
 
 - `svelte.config.*`：`autoImportHaiUi()` 在 `vitePreprocess()` 前。
-- `vite.config.*`：`ssr.noExternal` 包含 `@h-ai/*`，`optimizeDeps.exclude` 包含 `bits-ui`。
+- `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}`。
 
@@ -52,7 +52,6 @@
 - **primitives**：单个交互单元，例如 `Button`、`Input`、`Select`、`Badge`。
 - **compounds**：通用业务骨架，例如 `Form`、`Modal`、`Drawer`、`DataTable`、`Pagination`。
 - **scenes**：完整业务流，例如 `LoginForm`、`FileUpload`、`CrudPage`、`AiDocumentEditor`。
-
 经验法则：
 
 - 只是做一个输入控件或按钮行 → 先看 primitives。
@@ -89,7 +88,7 @@
 
 ```bash
 # 核心包
-npm install @h-ai/ui
+npm install @h-ai/ui @h-ai/core
 
 # 必须的对等依赖与构建工具
 npm install -D svelte @sveltejs/kit @sveltejs/vite-plugin-svelte
@@ -99,6 +98,8 @@ 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
@@ -143,7 +144,8 @@ export default defineConfig({
   },
   ssr: {
     // @h-ai 包为 ESM + Svelte 组件，需 Vite 在 SSR 时处理
-    noExternal: [/@h-ai\//],
+    noExternal: ['@h-ai/ui', '@h-ai/kit'],
+    external: ['@h-ai/core', 'sm-crypto'],
   },
 })
 ```
@@ -342,7 +344,7 @@ const p = usePlatform()
 
 ### 场景组件（Scenes）
 
-内置中英文翻译的业务场景组件。
+内置中英日文翻译的业务场景组件。
 
 #### 引导与帮助场景组件
 
@@ -358,7 +360,7 @@ const p = usePlatform()
 | 组件           | Props 要点                                      | 说明     |
 | -------------- | ----------------------------------------------- | -------- |
 | `AuthShell`    | `variant`('card'/'split'), `title`, `brandTitle`, `brandText`, `illustration`, `description`, `highlights` | 认证页布局（包裹登录/注册表单） |
-| `LoginForm`    | `showRememberMe`, `showRegisterLink`, `errors`  | 登录表单 |
+| `LoginForm`    | `showForgotPassword`, `showRegisterLink`, `errors`  | 登录表单 |
 | `RegisterForm` | `fields`, `minPasswordLength`, `errors`         | 注册表单 |
 | `UserProfile`  | `user`, `editable`, `fields`, `avatarAccept`, `avatarHint` | 用户资料，选择器和提示对齐业务校验；最终验证和上传仍由回调负责 |
 
@@ -579,6 +581,8 @@ typescript, javascript, python, java, go, rust, c, cpp, csharp, ruby, php, swift
 
 ## 配置驱动认证页面
 
+密码登录只接收 identifier/password；AuthPanel 将 LoginForm 的 username 映射为 identifier。会话期限来自服务端 session.maxAge/refreshTokenMaxAge，不增加未实现的登录偏好字段或持久会话选择框。
+
 协议支持 `agreements.userAgreementMarkdown` 与 `privacyPolicyMarkdown` 直接从配置加载；YAML 的 `|` 保留 Markdown 段落和换行。弹窗复用安全 MarkdownRenderer，关闭原始 HTML、脚本和代码复制工具。同主题同时提供正文与 URL 时优先正文，URL 可作为额外查看入口；只有 URL 时使用隔离 iframe。
 
 ```yaml
@@ -634,8 +638,9 @@ AuthPanel 在 SSR 阶段禁用原生表单控件，客户端挂载并绑定事
 4. **Combobox 统一单选/多选**：`MultiSelect` 已删除
 5. **移动端样式**：务必引入 `design-tokens.css` + `mobile.css`，使用 SafeArea 包裹原生 App 页面
 6. **`@source` 必须配置**：未配置则 TailwindCSS 无法扫描 `@h-ai/ui` 组件中的 class，样式会丢失
-7. **`ssr.noExternal`**：Vite SSR 需要将 `@h-ai/*` 包纳入处理，否则 SSR 时 Svelte 组件无法正确编译
-8. **data-* 属性透传**：公开 Svelte 组件会把调用方传入的 `data-*` 属性透传到根节点或主交互节点；测试和自动化优先直接使用 `data-testid`、`data-analytics-id`，不要为测试 ID 重复封装组件
+7. **响应式布局**：后台工作区和数据列表使用可用宽度，避免外壳固定 max-width 造成宽屏两侧留白。flex/grid 子项设 min-width: 0，表格在自身容器滚动；正文和登录框保留阅读宽度。至少验证 390、1440、1920、2560、3840px 的内容占宽、导航与全页溢出。
+8. **`ssr.noExternal`**：Svelte 组件及 `@h-ai/kit/client` 的 `$app/*` 路由别名需要 Vite 编译，UI 和 Kit 保持 noExternal，core 及其他纯服务端包保留原生加载；本地链接的框架包也要显式 external，避免日志、数据库等原生依赖被重复打包。sm-crypto 使用动态 CommonJS require，应放入 `ssr.external`，并以明确版本列入应用 dependencies；adapter-node 只根据直接生产依赖排除二次打包，不能仅依赖它作为框架的传递依赖。
+9. **data-* 属性透传**：公开 Svelte 组件会把调用方传入的 `data-*` 属性透传到根节点或主交互节点；测试和自动化优先直接使用 `data-testid`、`data-analytics-id`，不要为测试 ID 重复封装组件
 
 ## 导出路径
 
@@ -647,7 +652,7 @@ AuthPanel 在 SSR 阶段禁用原生表单控件，客户端挂载并绑定事
 | `@h-ai/ui/theme`           | 轻量主题元数据与工具，不经过组件根入口 |
 | `@h-ai/ui/i18n`            | 轻量语言工具，供状态层使用，不加载组件或引导 CSS |
 | `@h-ai/ui/auto-import`     | Svelte 预处理器：组件自动导入          |
-| `@h-ai/ui/components/*`    | 公开组件目录的 JS 入口，按实际 exports/产物选择 |
+| `@h-ai/ui/components/primitives/index` 等明确 barrel | 仅 package.exports 列出的组件目录；组件默认导出经 barrel 转发 |
 | `@h-ai/ui/components/primitives/index` | 公开原子组件目录入口，如 Button/Input |
 | `@h-ai/ui/styles/global.css`       | 全局基础样式（重置/滚动条/焦点）       |
 | `@h-ai/ui/styles/theme.css`        | Tailwind v4 `@theme` Token            |
@@ -682,3 +687,13 @@ IAM 表单、AuthPanel、UserProfile、FeedbackModal 直接接收同组参数；
   <Button type="submit">{m.save()}</Button>
 </Form>
 ```
+
+Node 请求/SSR 必须用 `core.i18n.runWithLocale(locale, callback)`（kit 同名方法）包裹实际异步 resolve；serv 自动建立请求语言上下文。浏览器 setGlobalLocale/createLocaleStore 继续管理应用语言，SSR 的 UI setter/store 不写全局值。显式 MessageOptions.locale 优先；进程默认语言仅在启动时设置。
+
+`@h-ai/ui/i18n` 的 `createLocaleStore` 按“可解析的持久化值 → 完整 navigator.languages（再检查 navigator.language）→ defaultLocale → 支持列表首项”选择语言；首个不支持的候选不触发默认回退。匹配大小写、语言简写及逐级区域/脚本回退，返回 supportedLocales 中的配置代码；同语言多个变体按列表顺序选择。detectBrowserLocale 无实际命中返回 null，不插入框架默认值；空支持列表最终保留调用方默认值。SSR 不读取浏览器候选或修改全局语言。应用若使用 Paraglide，仍需用该项目的 setLocale 同步应用翻译；内置 UI 字典的覆盖范围不因自定义 store 列表而自动增加。
+
+## 设计、实现与审查交接
+
+新页面/较大改版由 [hai-ui-design](../hai-ui-design/SKILL.md) 记录任务、信息结构、状态与组件映射；本参考负责公开用法；[hai-ui-review](../hai-ui-review/SKILL.md) 查看真实页面。theme.css 已引入 design-tokens.css；--hai-focus-color 缺省跟随主题 primary。
+
+Tabs 提供单一 Tab 入口、方向键/Home/End、跳过禁用项和 children 内容关联。DataTable 提供 aria-sort、aria-busy、加载文字及行键盘激活。Pagination 导航与输入名称走 UI i18n，外部 page 同步跳页草稿，触摸设备扩大按钮。TableToolbar 进入弹层后聚焦，Escape 返回触发点，视图按钮带 aria-pressed；业务回调仍须实际更新对应数据和视图。Empty/Alert 可容纳长内容与恢复操作；全局样式响应减少动态效果。

package/templates/skills/hai-ui-design/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: hai-ui-design
+description: "为 Hai 前端的新页面、业务流程或较大改版制定信息结构、交互状态、视觉约定和组件方案；实现用 hai-ui，现有界面审查用 hai-ui-review。"
+---
+
+# hai-ui-design
+
+## 能力契约
+
+| 项目 | 契约 |
+| --- | --- |
+| 能力 | 把用户目标转为适配当前 Hai 组件、主题与平台的页面设计 |
+| 适用场景 | 新页面、新业务流程、信息结构/布局调整或建立应用视觉约定 |
+| 输入 | 用户任务、需求/验收、目标端、当前页面、组件公开类型和已有品牌/设计规则 |
+| 输出 | 页面结构、状态与交互、组件映射、必要的全局/页面设计约定和可观察验收 |
+| 限制 | 方案请求停在设计；已有实现授权时继续交给 hai-app-create / hai-ui。设计不能补定权限等未决业务规则，组件 API 以实际版本为准。 |
+
+## 设计路径
+
+1. 读取项目入口、需求、实际页面和已有设计，确认目标是新建、局部优化还是整体改版。复用已确认材料；仅澄清会影响用户任务的实质缺口，普通实施细节沿已有授权继续。
+2. 确认本页面的主要任务：后台/编辑器重视扫描、操作和状态；官网重视内容表达与行动；文档/帮助重视阅读；作品展示由内容主导。同一个应用的不同页面可有不同任务，不能把营销式大留白强加给高密度操作界面。
+3. 按 [页面模式与决策](patterns.md) 选择信息结构：主操作、导航、筛选、内容、详情和反馈。列出初始、加载、空态、错误、成功、无权限及实际需要的长任务/取消/重试状态。
+4. 检查安装版本 exports/types 和已有应用实现，按场景 → 组合 → 原子选择 [hai-ui](../hai-ui/SKILL.md) 组件。明确业务负责的数据、鉴权和回调；真实缺口才增加应用组件或提出公共组件改进，不编造 Props。
+5. 把设计落到现有 DaisyUI 语义色、Hai tokens、字体层级、间距、密度和布局。保留本次范围适用的品牌、字体和颜色选择；允许业务主题覆盖，组件内不散落新的色值体系。窄抽屉按容器宽度调整，表格滚动由自身承接。
+6. 用“角色/操作 → 可观察结果”写验收，包含目标尺寸、语言/主题、长内容、键盘/触摸、减少动态效果和适用失败恢复。实现后交给 [hai-ui-review](../hai-ui-review/SKILL.md) 查看真实渲染与行为，必要时修订设计记录。
+
+## 设计记录
+
+沿用项目已有设计文件。小任务在任务记录或方案中说明即可；跨页面共用规则确实需要持久维护时使用一份 `.agents/instructions/ui-design.md`（或项目既定位置）。记录用户/任务、目标端、主题/token 对应、布局/密度、组件、交互和验收；页面仅记录差异，避免复制需求或整份组件 API。
+
+前端工作与 SDD 通过 [交接契约](../hai-spec-implement/handoff.md) 传递范围和验收。设计来源可参考 [UI/UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) 的场景匹配与全局/页面分层，以及 [Impeccable](https://github.com/pbakaus/impeccable) 的任务模式；所有建议须经现有产品、平台和真实组件核验。

package/templates/skills/hai-ui-design/patterns.md

@@ -0,0 +1,26 @@
+# 页面模式与设计决策
+
+本文件用于选择布局和交互，组件签名仍从当前版本公开类型确认。先看业务应用已有页面与组件展厅，再选择下面的模式；示例中的业务数据、文案和回调由应用提供。
+
+| 场景 | 优先组件 | 设计决策与验收 |
+| --- | --- | --- |
+| 列表、搜索、详情和编辑 | CrudPage；需要自定义编排时 DataTable、TableToolbar、Pagination | 标题/统计与搜索/操作分组；明确筛选后的空态和请求失败；窄屏允许表格内部滚动；排序状态、分页、返回位置可感知 |
+| 数据录入、设置、资料 | Form 或原生 form + FormLayout、FormField、现有输入组件 | 关联字段分组，明确必填和单位；首次失焦/提交显示错误，修正更新；自动/显式跨列；失败保留输入，重复提交策略按真实业务 |
+| 详情、确认、短流程 | Drawer、Modal、Confirm、Steps | 根据内容长度与前后文选择；标题、正文、操作区清楚；正文独立滚动，确认操作可见；焦点进入与关闭返回；保留输入与危险操作规则明确 |
+| 多区域导航、移动端 | PageHeader、Breadcrumb、Tabs、AppBar、BottomNav、SafeArea | 导航名称对应真实任务；页签与路由导航分清；方向键和禁用项处理；移动端安全区域、触摸、返回与深链符合当前宿主 |
+| 加载、无结果、失败和完成 | Skeleton、Empty、Alert、Result、现有消息容器 | 区分“没有数据”“筛选无匹配”“请求失败”“无权限”；说明原因和下一动作；重复实时播报、旋转图标和 toast 不能代替可恢复状态 |
+| 上传与长任务 | 现有 storage 场景组件、进度与状态组件 | 大小/类型限制与服务端一致；区分上传、处理、完成和失败；取消/重试按幂等契约；真实外部效果未知时不能显示完成 |
+| AI 对话、Markdown、代码和图表 | 已导出的 AI/图表场景组件 | 控制正文阅读宽度，代码/表格内部滚动；明确流式/加载/失败；渲染不可信内容走安全边界；图表图例、单位、色彩外的信息和文本摘要可读 |
+| 官网与帮助 | 现有布局、内容与 guide 能力 | 官网按内容与行动组织层级，帮助按问题和步骤组织；使用真实文案/素材，语言展开和阅读宽度适合目标端 |
+
+## 视觉约定如何落到实现
+
+- 语义色用 `base-*`、`primary`、`success`、`warning`、`error` 等当前主题变量，焦点沿 `--hai-focus-color`；使用已编译主题白名单与公开 theme 工具。
+- 共享间距、圆角、动效、触摸区域沿 theme/design tokens；表格使用现有 `density`。调整密度以任务和目标设备为依据，不为每个组件新增同名配置。
+- 标题、说明、字段标签、数值、状态有明确层级；后台外壳使用可用宽度，正文保留阅读宽度。flex/grid 子项考虑 `min-width: 0`；长链接/标识符可换行，代码可内部滚动。
+- 操作优先级按业务决定；按钮文案说明动作，图标按钮有可访问名称。关键操作不只依赖颜色或 hover。
+- 动效说明变化或空间关系，尊重 `prefers-reduced-motion`。新动效的加载、取消和最终状态都要可验证。
+
+## 页面方案最小示例
+
+“成员列表”沿现有 CrudPage 实现：用户任务是查找成员、查看详情和修改获授权字段。顶部放名称/数量及主要操作，筛选与排序放工具栏，表格使用现有 density；窄屏内部滚动。记录初次加载、请求失败重试、无成员、筛选无结果、提交失败保留输入和缺权限状态。验收覆盖操作后的真实数据、键盘排序/页签、390px 手机、1440px 桌面、英文长名称和明暗主题。具体字段/权限来自业务需求，不从组件示例推断。

package/templates/skills/hai-ui-review/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: hai-ui-review
+description: "审查实际 Hai 界面的布局、信息层级、交互、响应式、可访问性和异常恢复；只读评审与已有授权的修复复测均适用。"
+---
+
+# hai-ui-review
+
+## 能力契约
+
+| 项目 | 契约 |
+| --- | --- |
+| 能力 | 根据用户任务与真实渲染检查界面体验和技术质量 |
+| 适用场景 | 界面走查、前端改动自查、布局/交互评审与已授权修复验收 |
+| 输入 | 目标页面/组件、需求或设计约定、运行环境、实际界面与相关实现 |
+| 输出 | 带位置、操作、后果和截图/运行证据的问题清单及复测结果 |
+| 限制 | 只读请求不自动修改；审美偏好单列，不能推翻明确设计。浏览器证据不等于原生平台或真实外部服务验收。 |
+
+## 审查路径
+
+1. 明确本次页面、角色、主要任务、设计约定与授权范围；理解本次是局部改善还是重新设计。沿 [hai-ui-design](../hai-ui-design/SKILL.md) 的页面任务判断层级、密度和表达。
+2. 使用项目已有运行/浏览器测试入口装配隔离环境。先看真实页面再定位源码；不能启动时做源码/已有截图审查，标明截图来源与新旧关系，记录实际浏览器未验证。
+3. 按 [走查清单](checklist.md) 完成用户路径。先处理任务无法完成、状态错误、键盘不可达和内容溢出，再评估布局一致性、层级和细节。每个问题记录具体页面、尺寸、语言/主题、操作和实际后果。
+4. 复核发现是否来自公共组件、业务组合、设计规则或环境。公共问题优先修正 [hai-ui](../hai-ui/SKILL.md) 对应组件，再同步应用、CLI、文档；业务专属问题留在业务层，实际权限仍由服务端验收。
+5. 已授权修复时集中处理本轮发现，再批量复测受影响路径和尺寸；需要行为回归时按 [hai-app-tests](../hai-app-tests/SKILL.md) 选合适测试层。纯视觉调整使用真实渲染验证，避免只匹配 class 字符串的测试。
+
+## 问题与证据
+
+沿 [交接契约](../hai-spec-implement/handoff.md) 记录稳定编号、优先级、位置、触发操作、后果、依据、建议和验收。截图证明布局，浏览器操作证明交互，服务/存储证据证明业务效果；三者按实际范围分别说明。
+
+先报告已确认问题，再列实际覆盖和未验证边界。已修复项附本轮源码标识、操作与结果，日志/截图放 Git 忽略目录。没有浏览器或宿主环境时继续能做的检查，保留环境限制，不将静态清单视为实际通过。

package/templates/skills/hai-ui-review/checklist.md

@@ -0,0 +1,22 @@
+# 实际界面走查
+
+按本次真实任务选择检查项，说明不适用原因。无需为后台、官网、API 项目强加同样的页面制度。
+
+| 维度 | 如何检查 | 问题的可观察依据 |
+| --- | --- | --- |
+| 用户任务 | 从入口完成一次真实操作，再尝试失败和恢复 | 操作找不到、错误状态、数据未保存却提示成功、返回后丢失工作 |
+| 信息结构 | 看标题、主操作、筛选、内容和反馈是否能快速定位 | 关键动作埋没、状态不清楚、同级内容层级不一致 |
+| 布局与密度 | 目标手机、桌面、窄抽屉及产品需要的大屏 | 整页横向溢出、遮挡、操作离屏、无效空白、容器嵌套限制宽度 |
+| 内容与语言 | 长中文、长英文、无空格标识符、多行错误、空值 | 截断关键信息、按钮重叠、标签挤压、切语言后出现旧错误文案 |
+| 主题与焦点 | 已编译的明暗主题、Tab 键移动 | 控件边界和焦点不可见、状态仅由颜色区分、主题变量失效 |
+| 键盘与辅助信息 | Tab/Shift+Tab、Enter/Space、方向键、Home/End、Escape | 禁用项被激活、焦点消失、弹层关闭不返回、tab/panel/sort 状态不对应 |
+| 输入与触摸 | 点击区域、IME、失焦/提交、连续操作 | 触摸难点、输入法误提交、隐藏字段旧错误、重复提交或失败后丢输入 |
+| 状态与恢复 | 加载、空态、无匹配、失败、无权限、长任务 | 只有 spinner、无法重试、toast 代替持久错误、未知外部效果被标完成 |
+| 动效与性能 | 减少动态效果、内容加载、表格/图表与流式内容 | 装饰动画仍执行、布局反复跳动、监听器未释放、交互明显卡顿 |
+| 安全与平台 | 不可信 HTML/URL、会话与实际 Web/App/Desktop 宿主 | 未消毒内容执行、前端隐藏代替鉴权、浏览器结果被冒充原生能力 |
+
+## 验收怎么写
+
+可用例子：“390px、英文、暗色模式下，打开筛选后首个控件获焦，Escape 关闭并回到筛选按钮，整页无横向溢出。”
+
+不够具体的例子：“响应式已适配”“体验已优化”“截图正常”。截图应能对应页面与条件；键盘、数据保存、重试等必须实际操作，并保留必要断言。视觉审美建议注明与哪个既定设计目标相关，不能把个人字体/配色偏好写成缺陷。

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

@@ -1,28 +1,32 @@
 ---
 name: hai-vecdb
-description: "使用 @h-ai/vecdb 管理 LanceDB/pgvector/Qdrant/Chroma 集合与向量检索。"
+description: "使用 LanceDB/pgvector/Qdrant/Chroma 管理向量集合、写入和检索；排查维度、连接与过滤问题。"
 ---
 
 # hai-vecdb
 
 ## 能力契约
 
-| 项目 | 契约 |
-| --- | --- |
-| 能力 | 使用 @h-ai/vecdb 管理 LanceDB/pgvector/Qdrant/Chroma 集合与向量检索 |
-| 适用场景 | 向量持久化、集合管理或相似度搜索 |
-| 输入 | VecdbConfigInput、集合、固定维度向量、查询过滤条件 |
-| 输出 | 集合/向量操作的 HaiResult |
-| 限制 | 仅服务端；向量维度须匹配集合。Chroma 是 HTTP 服务，本地 path 模式需可用服务命令；init 失败不得当成空库。 |
+| 项目     | 契约                                                                                                     |
+| -------- | -------------------------------------------------------------------------------------------------------- |
+| 能力     | 使用 @h-ai/vecdb 管理 LanceDB/pgvector/Qdrant/Chroma 集合与向量检索                                      |
+| 适用场景 | 向量持久化、集合管理或相似度搜索                                                                         |
+| 输入     | VecdbConfigInput、集合、固定维度向量、查询过滤条件                                                       |
+| 输出     | 集合/向量操作的 HaiResult                                                                                |
+| 限制     | 仅服务端；向量维度须匹配集合。Chroma 是 HTTP 服务，本地 path 模式需可用服务命令；init 失败不得当成空库。 |
 
 ## 使用路径
 
 - `_vecdb.yml` 选择实际后端；init 后检查连接结果，再创建集合并写入相同维度向量。
-- Chroma 本地服务不可用返回连接错误；Qdrant 只有 404 代表集合不存在。
+- LanceDB 集合维度/metric 随 Arrow schema 持久化，连接 metric 仅是新集合默认值；本地路径不自动跨节点共享。分布式应用优先服务端后端，重启复用持久目录与匹配的 embedding 维度。
+- LanceDB insert/upsert 均需持久非空 id 主键与原子 merge；insert 保留已有 ID，upsert 整行替换。同批重复 ID 或能力缺失返回 CONFIG_ERROR，无 delete/add 回退。原子性只覆盖每次 merge；检查错误后再继续业务写入。
+- LanceDB 使用原生 JSON metadata；filter 仅支持顶层字面量键的 string/有限 number/boolean/null AND 匹配，null 不匹配缺失字段。对象/数组/undefined 与旧 Utf8 metadata 表返回 CONFIG_ERROR；过滤在 topK 前执行，错误不得当作空结果。其它后端的 null/复杂过滤能力须单独核对。
+- Chroma 仅支持 HTTP(S) 根 url（优先于 host/port），不接受路径前缀/URL 凭据/query/fragment；apiKey 按自托管网关协议发送 Authorization: Bearer，不表示 Chroma Cloud 支持。初始化同时验证数据端点权限，认证失败不得当成空库。Qdrant 只有 404 代表集合不存在。
+- Qdrant 仅支持未命名向量字段的三种公开 metric，外部 named-vector/Manhattan 集合返回 CONFIG_ERROR；Chroma 的 metadata/filter 由真实 SDK 校验，非法输入返回操作错误，不执行无过滤回退。
 
 ## 按需参考
 
-详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 运行环境
 - 适用场景

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

@@ -44,7 +44,7 @@ path: ./data/vecdb
 # type: chroma
 # url: http://localhost:8000
 # apiKey: ''
-# serverCommand: chroma      # 嵌入式模式拉起服务的可执行命令（默认 chroma，来自 chromadb 包）
+# serverCommand: chroma      # 嵌入式服务端命令，默认 chroma；需独立安装服务端 CLI
 # startupTimeout: 30000      # 嵌入式服务就绪等待超时（毫秒）
 operationLog:
   read: false # collection.exists/info/list, vector.search/count
@@ -118,6 +118,20 @@ interface CollectionCreateOptions {
 }
 ```
 
+LanceDB 将向量维度存于 Arrow 固定长度 vector 字段，将集合 metric 存于同一 schema 的 metadata；空表也可正确恢复。`collection.create` 中的 metric 优先于连接配置，连接 metric 仅是新集合的默认值。重启或更换默认值不会改变已有集合。每次操作读取持久 schema，并检查其它连接的提交；缺少有效集合定义时返回 `CONFIG_ERROR`，不探测假向量或猜测 metric。旧表/外部表如缺少该定义，需要重建集合，不提供兼容推断。
+
+LanceDB 是嵌入式本地文件后端。只有访问相同持久目录、且底层文件系统支持 LanceDB 并发提交的进程才能共享数据；不同节点各自的同名本地路径互不共享。分布式服务优先选择 pgvector、Qdrant 或 Chroma 服务端。AI Knowledge 的 reldb 与 vecdb 都须持久化并指向同一业务数据集，替换 embedding 维度时须重建匹配的集合。
+
+搜索始终使用集合 metric，`euclidean` 映射 LanceDB 的 `l2`。`score` 延续公开 API 的 0–1、越大越相似约定：cosine 为 `clamp(1 - distance / 2, 0, 1)`；euclidean 为 `1 / (1 + squaredL2)`；dot 为 `sigmoid(dotProduct)`，用于保持内积排序而非概率。`minScore` 在该转换后过滤；不同 metric/后端的阈值不应视为通用校准值。
+
+LanceDB 原子写入的验证基线为 `@lancedb/lancedb 0.40.0 / Lance 13`。新集合在初始 Arrow schema 声明 id 为不可空主键；insert/upsert 均使用原生 merge，以 id 参与严格键冲突检测。依据：[Lance 13 table format](https://github.com/lance-format/lance/blob/v13.0.0/docs/src/format/table/index.md#unenforced-primary-key)、[Lance 13 transaction](https://github.com/lance-format/lance/blob/v13.0.0/protos/transaction.proto)、[Node binding 0.40.0](https://github.com/lancedb/lancedb/blob/v0.40.0/nodejs/lancedb/table.ts)。
+
+LanceDB 的 `insert` 仅插入新 ID，已有 ID 保留不覆盖；`upsert` 新增或整体替换。同批重复 ID、缺失 merge 能力/持久主键均返回 `CONFIG_ERROR`，不执行写入。旧表需重建，不自动迁移或清空。每个 merge 独立原子提交；并发胜者由提交顺序决定，不提供多个 merge 或 reldb/vecdb 间的共同事务。框架不会回退到 delete/add；写入结果不明时按 ID 核对。直接使用原生 add 的外部写入会绕过该保护，不属于本接口保证。
+
+LanceDB metadata 使用原生 JSON 字段，仍可保存嵌套 JSON 对象，搜索结果还原为对象；insert/upsert 明确使用 Arrow JSON schema 完成 JSONB 编码。旧 Utf8 metadata 表写入或过滤返回 CONFIG_ERROR，需要重建，不自动迁移。依据：[Lance 13 JSON UDF](https://github.com/lance-format/lance/blob/v13.0.0/rust/lance-datafusion/src/udf/json.rs)、[Node 0.40.0 JSON field](https://github.com/lancedb/lancedb/blob/v0.40.0/nodejs/lancedb/arrow.ts)。
+
+LanceDB filter 只支持顶层字面量键的 AND 精确匹配，值为 string/有限 number/boolean/null；例如 `{ tenant: 'acme', page: 1, active: true, removedAt: null }`。数字/布尔不匹配同形字符串；null 只匹配显式 JSON null，不匹配缺失键。引号、反斜线、百分号、下划线均为字面量，点/括号不解释为嵌套路径。空对象不筛选；对象、数组、undefined、非有限数值返回 CONFIG_ERROR，不能忽略条件重试。过滤在向量 topK 前执行，随后应用 minScore；其它 Provider 沿用原生约束，不保证同样的 null、复杂值和路径语义。
+
 ### 向量操作 — `vecdb.vector`
 
 | 方法     | 签名                                                          | 说明          |
@@ -160,7 +174,15 @@ await vecdb.vector.delete('docs', ['doc-1', 'doc-2'])
 
 > 空批量 `insert/upsert/delete` 会被视为 no-op；写入与搜索会校验向量维度，不匹配时返回 `HaiVecdbError.DIMENSION_MISMATCH`。Qdrant `collection.exists()` 仅在 404 时返回 `false`，网络异常会返回查询错误而不是误判不存在。
 
-> Chroma 在 Node 端只有 HTTP 客户端（无进程内嵌入式）。嵌入式模式（提供 `path` 且无 `url`）下 `vecdb.init` 通过 `serverCommand`（默认 `chroma`，来自可选依赖 `chromadb`）拉起本地服务，`vecdb.close` 时关闭进程；服务命令不可用或就绪超时时 `init` 返回 `HaiVecdbError.CONNECTION_FAILED`。直连模式提供 `url` 即可，不拉起进程。
+Qdrant `insert/upsert/delete` 等待服务端应用完成（wait:true）才返回成功，`vector.count` 请求精确计数。多次操作之间没有事务；Knowledge 在此基础上使用共享版本清单发布与补偿。
+
+> Chroma 在 Node 端只有 HTTP 客户端（无进程内嵌入式）。嵌入式模式（提供 `path` 且无 `url`）下 `vecdb.init` 通过 `serverCommand`（默认 `chroma`）拉起本地服务，`vecdb.close` 时关闭进程；npm `chromadb` 提供客户端，服务端 CLI 需另行安装。服务命令不可用或就绪超时时 `init` 返回 `HaiVecdbError.CONNECTION_FAILED`。
+
+Chroma 直连 `url` 仅支持 HTTP(S) 根端点，优先于 `host/port`；URL 不得带凭据、路径前缀、query 或 fragment。无 `url` 时 `host/port` 使用 HTTP。可选 `apiKey` 以 `Authorization: Bearer <apiKey>` 发送给采用此协议的自托管服务/网关；远程传输应使用 HTTPS。空串表示未配置，其余值只允许无空白的可打印 ASCII。本接口使用默认 tenant/database，不提供 Chroma Cloud 契约。初始化在心跳后验证数据端点权限，认证/权限失败返回 `CONNECTION_FAILED`，必须先检查 `success` 再执行业务。SDK 参数依据：[chromadb 3.5.0 官方客户端](https://docs.trychroma.com/reference/typescript/client)。
+
+直连初始化总截止为 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 和复杂元数据语义不承诺统一。
 
 **VectorDocument**：
 
@@ -178,7 +200,7 @@ interface VectorDocument {
 ```typescript
 interface VectorSearchOptions {
   topK?: number // 返回数量（默认 10）
-  filter?: Record<string, unknown> // 元数据过滤（键值精确匹配）
+  filter?: Record<string, unknown> // Provider 原生约束；LanceDB 仅支持上述顶层标量 AND 匹配
   minScore?: number // 最低相似度阈值（0-1）
 }
 ```
@@ -293,3 +315,11 @@ if (!result.success) {
 - `hai-datapipe`：文本清洗与分块
 - `hai-reldb`：关系型数据库（知识库需要同时使用 reldb 存储结构化数据）
 - `hai-core`：配置管理、HaiResult 模型
+
+## 生产共享状态
+
+生产使用 Qdrant、pgvector 或远端 Chroma；LanceDB 和嵌入式 Chroma 只用于开发/明确测试。 NODE_ENV 或 HAI_CORE_ENV 为 production 时在初始化成功前检查，只有 HAI_E2E=1/HAI_E2E_MOCK=1 明确测试豁免。不要将租约当作最终写入条件，外部未知效果须按稳定业务键核对。
+
+## 关闭与失败恢复
+
+vecdb.close() 失败后不要把资源视为已释放；error.ext.cleanupPending 表示同一模块仍保有待清理资源。旧操作引用也会返回 NOT_INITIALIZED；重试 close 或 init 的前置清理，不创建并行替代连接。内嵌 Chroma 只有直接子进程 exit 确认后关闭成功，终止信号回执不是退出证明。