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

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,31 @@
+# 页面模式与设计决策
+
+本文件用于选择布局和交互，组件签名仍从当前版本公开类型确认。先看业务应用已有页面与组件展厅，再选择下面的模式；示例中的业务数据、文案和回调由应用提供。
+
+| 场景 | 优先组件 | 设计决策与验收 |
+| --- | --- | --- |
+| 列表、搜索、详情和编辑 | CrudPage；需要自定义编排时 DataTable、TableToolbar、Pagination | 标题/统计与搜索/操作分组；明确筛选后的空态和请求失败；窄屏允许表格内部滚动；排序状态、分页、返回位置可感知 |
+| 数据录入、设置、资料 | Form 或原生 form + FormLayout、FormField、现有输入组件 | 关联字段分组，明确必填和单位；输入后失焦/提交显示错误，修正更新；自动/显式跨列；失败保留输入，重复提交策略按真实业务 |
+| 详情、确认、短流程 | Drawer、Modal、Confirm、Steps | 根据内容长度与前后文选择；标题、正文、操作区清楚；正文独立滚动，确认操作可见；焦点进入与关闭返回；保留输入与危险操作规则明确 |
+| 多区域导航、移动端 | PageHeader、Breadcrumb、Tabs、AppBar、BottomNav、SafeArea | 导航名称对应真实任务；页签与路由导航分清；方向键和禁用项处理；移动端安全区域、触摸、返回与深链符合当前宿主 |
+| 加载、无结果、失败和完成 | Skeleton、Empty、Result、ToastContainer，Alert仅用于info/success | 区分“没有数据”“筛选无匹配”“请求失败”“无权限”；警告和错误经Toast提示，页面保留恢复动作与状态占位，不另放行内错误段落或Alert |
+| 上传与长任务 | 现有 storage 场景组件、进度与状态组件 | 大小/类型限制与服务端一致；区分上传、处理、完成和失败；取消/重试按幂等契约；真实外部效果未知时不能显示完成 |
+| AI 对话、Markdown、代码和图表 | 已导出的 AI/图表场景组件 | 控制正文阅读宽度，代码/表格内部滚动；明确流式/加载/失败；渲染不可信内容走安全边界；图表图例、单位、色彩外的信息和文本摘要可读 |
+| 官网与帮助 | 现有布局、内容与 guide 能力 | 官网按内容与行动组织层级，帮助按问题和步骤组织；使用真实文案/素材，语言展开和阅读宽度适合目标端 |
+
+## 后台页面默认约束
+
+- 后台与工作台优先使用 WorkspaceLayout 统一紧凑顶栏、内容内边距和可选页脚，不叠加大段上下 padding。导航已显示页面标题时，内容区不再重复；PageHeader 与 SettingsLayout 保留说明/操作，CrudPage 将操作放入工具栏。独立页面或真实子区域保留必要标题。
+- 多条件筛选使用 FilterBar 或 CrudFilterBar，默认收起扩展条件，搜索/查询/重置保持可用；提供 activeCount 和实际 onreset，收起不能丢值或隐式清空查询。复用组件状态及三语文案，不在页面复制折叠状态机。TableToolbar 已有弹层筛选可继续复用。
+
+## 视觉约定如何落到实现
+
+- 语义色用 `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,32 @@
+---
+name: hai-ui-review
+description: "审查实际 Hai 界面的布局、信息层级、交互、响应式、可访问性和异常恢复；只读评审与已有授权的修复复测均适用。"
+---
+
+# hai-ui-review
+
+## 能力契约
+
+| 项目 | 契约 |
+| --- | --- |
+| 能力 | 根据用户任务与真实渲染检查界面体验和技术质量 |
+| 适用场景 | 界面走查、前端改动自查、布局/交互评审与已授权修复验收 |
+| 输入 | 目标页面/组件、需求或设计约定、运行环境、实际界面与相关实现 |
+| 输出 | 带位置、操作、后果和截图/运行证据的问题清单及复测结果 |
+| 限制 | 只读请求不自动修改；审美偏好单列，不能推翻明确设计。浏览器证据不等于原生平台或真实外部服务验收。 |
+
+## 审查路径
+
+发现和同步决策遵循[沟通与同步维护](../hai-app-create/collaboration.md)；涉及使用指南的截图须来自当前实际操作并脱敏，不能仅凭源码说明视觉效果已通过。
+
+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,29 @@
+# 实际界面走查
+
+按本次真实任务选择检查项，说明不适用原因。无需为后台、官网、API 项目强加同样的页面制度。
+
+| 维度 | 如何检查 | 问题的可观察依据 |
+| --- | --- | --- |
+| 用户任务 | 从入口完成一次真实操作，再尝试失败和恢复 | 操作找不到、错误状态、数据未保存却提示成功、返回后丢失工作 |
+| 信息结构 | 看标题、主操作、筛选、内容和反馈是否能快速定位 | 关键动作埋没、状态不清楚、同级内容层级不一致 |
+| 布局与密度 | 目标手机、桌面、窄抽屉及产品需要的大屏 | 整页横向溢出、遮挡、操作离屏、无效空白、容器嵌套限制宽度 |
+| 内容与语言 | 长中文、长英文、无空格标识符、多行错误、空值 | 截断关键信息、按钮重叠、标签挤压、切语言后出现旧错误文案 |
+| 主题与焦点 | 已编译的明暗主题、Tab 键移动 | 控件边界和焦点不可见、状态仅由颜色区分、主题变量失效 |
+| 键盘与辅助信息 | Tab/Shift+Tab、Enter/Space、方向键、Home/End、Escape | 禁用项被激活、焦点消失、弹层关闭不返回、tab/panel/sort 状态不对应 |
+| 输入与触摸 | 点击区域、IME、失焦/提交、连续操作 | 触摸难点、输入法误提交、隐藏字段旧错误、重复提交或失败后丢输入 |
+| 状态与恢复 | 加载、空态、无匹配、失败、无权限、长任务 | 只有 spinner、无法重试、toast 代替持久错误、未知外部效果被标完成 |
+| 动效与性能 | 减少动态效果、内容加载、表格/图表与流式内容 | 装饰动画仍执行、布局反复跳动、监听器未释放、交互明显卡顿 |
+| 安全与平台 | 不可信 HTML/URL、会话与实际 Web/App/Desktop 宿主 | 未消毒内容执行、前端隐藏代替鉴权、浏览器结果被冒充原生能力 |
+| 部署目录 | [网站挂载目录](../hai-build/paths.md)、资源、当前导航与深链刷新 | 跳到域名根、运行配置未加载、API地址错位、带前缀后守卫漏匹配 |
+
+## 紧凑工作区必查
+
+- 导航已显示当前标题时，内容区没有重复标题；隐藏标题后新建、自定义操作和说明仍可用。顶栏、正文和页脚没有叠加的大段上下空白。
+- 多条件筛选可通过键盘展开/收起，收起保留值且提示已启用条件；搜索和重置可触达，重置清空全部条件并真正更新列表。
+- 手机、1440/1920/2560/3840px 下无整页横向溢出；表格自己滚动，分页不遮挡数据。用实际尺寸、截图和操作验证，不能只匹配 class。
+
+## 验收怎么写
+
+可用例子：“390px、英文、暗色模式下，打开筛选后首个控件获焦，Escape 关闭并回到筛选按钮，整页无横向溢出。”
+
+不够具体的例子：“响应式已适配”“体验已优化”“截图正常”。截图应能对应页面与条件；键盘、数据保存、重试等必须实际操作，并保留必要断言。视觉审美建议注明与哪个既定设计目标相关，不能把个人字体/配色偏好写成缺陷。

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

@@ -1,279 +1,37 @@
 ---
 name: hai-vecdb
-description: 使用 @h-ai/vecdb 进行向量数据库操作（LanceDB/pgvector/Qdrant）的集合管理与向量增删改查；当需求涉及向量存储、相似度搜索、嵌入检索或语义搜索时使用。
+description: "使用 LanceDB/pgvector/Qdrant/Chroma 管理向量集合、写入和检索；排查维度、连接与过滤问题。"
 ---
 
 # hai-vecdb
 
-> `@h-ai/vecdb` 提供统一的向量数据库操作接口，支持 LanceDB、pgvector、Qdrant，包含集合管理和向量 CRUD/搜索。
+## 能力契约
 
----
-
-## 运行环境
-
-> ⚠️ **服务端模块（Node.js only）。** 浏览器端不直接操作向量数据库，通过 `@h-ai/ai` 的 API 端点间接使用（如 RAG 检索、知识库查询）。
-
----
-
-## 适用场景
-
-- 新增或修改向量数据库访问逻辑（集合管理/向量插入/搜索）
-- 接入不同向量数据库后端（LanceDB / pgvector / Qdrant）
-- 基于 `HaiVecdbError` 做错误分支处理
-- 构建 RAG、语义搜索、知识库等 AI 场景
-
----
-
-## 使用步骤
-
-### 1. 配置
-
-```yaml
-# config/_vecdb.yml
-
-# LanceDB（默认，嵌入式本地存储）
-type: lancedb
-path: ./data/vecdb
-
-# pgvector
-# type: pgvector
-# url: ${HAI_VECDB_PG_URL:postgres://user:pass@localhost:5432/mydb}
-# indexType: hnsw
-# tablePrefix: vec_
-
-# Qdrant
-# type: qdrant
-# url: ${HAI_VECDB_QDRANT_URL:http://localhost:6333}
-# apiKey: ${HAI_VECDB_QDRANT_API_KEY:}
-```
-
-### 2. 初始化与关闭
-
-```typescript
-import { core } from '@h-ai/core'
-import { vecdb } from '@h-ai/vecdb'
-
-await vecdb.init(core.config.get('vecdb'))
-// ... 使用向量数据库
-await vecdb.close()
-```
-
-### 3. 选择操作接口
-
-| 接口       | 用途                       | 入口              |
-| ---------- | -------------------------- | ----------------- |
-| collection | 集合创建/删除/查询/判断存在 | `vecdb.collection` |
-| vector     | 向量插入/更新/删除/搜索/计数 | `vecdb.vector`     |
-
----
-
-## 核心 API
-
-### 集合操作 — `vecdb.collection`
-
-| 方法     | 签名                                       | 说明           |
-| -------- | ------------------------------------------ | -------------- |
-| `create` | `(name, options) => HaiResult<void>`          | 创建集合       |
-| `drop`   | `(name) => HaiResult<void>`                   | 删除集合       |
-| `exists` | `(name) => HaiResult<boolean>`                | 判断集合是否存在 |
-| `info`   | `(name) => HaiResult<CollectionInfo>`         | 获取集合信息   |
-| `list`   | `() => HaiResult<string[]>`                   | 列出所有集合   |
-
-> 所有方法均返回 `Promise<HaiResult<T>>`，上表省略异步与错误类型。
-
-```typescript
-// 创建集合（指定维度和度量）
-await vecdb.collection.create('docs', { dimension: 1536, metric: 'cosine' })
-
-// 查询集合信息
-const info = await vecdb.collection.info('docs')
-if (info.success) {
-  // info.data => { name, dimension, metric, count }
-}
-
-// 列出所有集合
-const list = await vecdb.collection.list()
-```
-
-**CollectionCreateOptions**：
-
-```typescript
-interface CollectionCreateOptions {
-  dimension: number            // 向量维度（必填）
-  metric?: 'cosine' | 'euclidean' | 'dot'  // 距离度量（默认 cosine）
-}
-```
+| 项目     | 契约                                                                                                     |
+| -------- | -------------------------------------------------------------------------------------------------------- |
+| 能力     | 使用 @h-ai/vecdb 管理 LanceDB/pgvector/Qdrant/Chroma 集合与向量检索                                      |
+| 适用场景 | 向量持久化、集合管理或相似度搜索                                                                         |
+| 输入     | VecdbConfigInput、集合、固定维度向量、查询过滤条件                                                       |
+| 输出     | 集合/向量操作的 HaiResult                                                                                |
+| 限制     | 仅服务端；向量维度须匹配集合。Chroma 是 HTTP 服务，本地 path 模式需可用服务命令；init 失败不得当成空库。 |
 
-### 向量操作 — `vecdb.vector`
+## 使用路径
 
-| 方法     | 签名                                                | 说明           |
-| -------- | --------------------------------------------------- | -------------- |
-| `insert` | `(collection, documents) => HaiResult<void>`           | 批量插入       |
-| `upsert` | `(collection, documents) => HaiResult<void>`           | 批量更新/插入  |
-| `delete` | `(collection, ids) => HaiResult<void>`                 | 按 ID 删除     |
-| `search` | `(collection, vector, options?) => HaiResult<SearchResult[]>` | 向量搜索 |
-| `count`  | `(collection) => HaiResult<number>`                    | 文档计数       |
+- `_vecdb.yml` 选择实际后端；init 后检查连接结果，再创建集合并写入相同维度向量。
+- 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 校验，非法输入返回操作错误，不执行无过滤回退。
 
-> 所有方法均返回 `Promise<HaiResult<T>>`，上表省略异步与错误类型。
-
-```typescript
-// 插入向量文档
-await vecdb.vector.insert('docs', [
-  { id: 'doc-1', vector: embedding, content: '文档内容', metadata: { source: 'wiki' } },
-  { id: 'doc-2', vector: embedding2, content: '另一段内容' },
-])
-
-// 向量搜索（返回相似度排序结果）
-const result = await vecdb.vector.search('docs', queryVector, {
-  topK: 10,
-  minScore: 0.7,
-  filter: { source: 'wiki' },
-})
-if (result.success) {
-  for (const item of result.data) {
-    // item => { id, score, content, metadata }
-  }
-}
-
-// 更新已有文档（按 id 匹配）
-await vecdb.vector.upsert('docs', [
-  { id: 'doc-1', vector: newEmbedding, content: '更新后的内容' },
-])
-
-// 删除
-await vecdb.vector.delete('docs', ['doc-1', 'doc-2'])
-```
-
-**VectorDocument**：
-
-```typescript
-interface VectorDocument {
-  id: string                            // 文档唯一标识
-  vector: number[]                      // 向量数据
-  content?: string                      // 文本内容（可选）
-  metadata?: Record<string, unknown>    // 元数据（可选）
-}
-```
-
-**VectorSearchOptions**：
-
-```typescript
-interface VectorSearchOptions {
-  topK?: number                         // 返回数量（默认 10）
-  filter?: Record<string, unknown>      // 元数据过滤（键值精确匹配）
-  minScore?: number                     // 最低相似度阈值（0-1）
-}
-```
-
----
-
-## 错误码 — `HaiVecdbError`
-
-| 错误码                                    | code              | 说明               |
-| ----------------------------------------- | ----------------- | ------------------ |
-| `HaiVecdbError.CONNECTION_FAILED`         | `hai:vecdb:001`   | 连接失败           |
-| `HaiVecdbError.QUERY_FAILED`             | `hai:vecdb:002`   | 查询失败           |
-| `HaiVecdbError.COLLECTION_NOT_FOUND`     | `hai:vecdb:003`   | 集合不存在         |
-| `HaiVecdbError.COLLECTION_ALREADY_EXISTS`| `hai:vecdb:004`   | 集合已存在         |
-| `HaiVecdbError.DIMENSION_MISMATCH`       | `hai:vecdb:005`   | 向量维度不匹配     |
-| `HaiVecdbError.INSERT_FAILED`            | `hai:vecdb:006`   | 插入失败           |
-| `HaiVecdbError.DELETE_FAILED`            | `hai:vecdb:007`   | 删除失败           |
-| `HaiVecdbError.UPDATE_FAILED`            | `hai:vecdb:008`   | 更新失败           |
-| `HaiVecdbError.INDEX_BUILD_FAILED`       | `hai:vecdb:009`   | 索引构建失败       |
-| `HaiVecdbError.NOT_INITIALIZED`          | `hai:vecdb:010`   | 未初始化           |
-| `HaiVecdbError.CONFIG_ERROR`             | `hai:vecdb:011`   | 配置错误           |
-| `HaiVecdbError.UNSUPPORTED_TYPE`         | `hai:vecdb:012`   | 不支持的数据库类型 |
-| `HaiVecdbError.DRIVER_NOT_FOUND`         | `hai:vecdb:013`   | 驱动未安装         |
-| `HaiVecdbError.SERIALIZATION_FAILED`     | `hai:vecdb:014`   | 序列化失败         |
-
----
-
-## 常见模式
-
-### RAG 检索
-
-```typescript
-import { ai } from '@h-ai/ai'
-import { vecdb } from '@h-ai/vecdb'
-
-// 将查询文本转为向量
-const embedResult = await ai.embedding.embedText(query)
-if (!embedResult.success) return embedResult
-
-// 检索最相似的文档
-const searchResult = await vecdb.vector.search('knowledge', embedResult.data, {
-  topK: 5,
-  minScore: 0.7,
-})
-if (!searchResult.success) return searchResult
-
-// 拼接上下文，送入 LLM
-const context = searchResult.data.map(r => r.content).join('\n\n')
-const chatResult = await ai.llm.chat({
-  messages: [
-    { role: 'system', content: `参考以下资料回答用户问题：\n${context}` },
-    { role: 'user', content: query },
-  ],
-})
-```
-
-### 文档入库
-
-```typescript
-import { datapipe } from '@h-ai/datapipe'
-import { ai } from '@h-ai/ai'
-import { vecdb } from '@h-ai/vecdb'
-
-// 清洗 + 分块
-const pipeline = await datapipe.pipeline()
-  .clean({ removeHtml: true })
-  .chunk({ mode: 'markdown', maxSize: 1000, overlap: 100 })
-  .run(rawText)
-
-if (!pipeline.success) return pipeline
-
-// 批量生成嵌入
-const embeddings = await ai.embedding.embedBatch(
-  pipeline.data.chunks.map(c => c.content),
-)
-if (!embeddings.success) return embeddings
-
-// 批量入库
-const docs = pipeline.data.chunks.map((chunk, i) => ({
-  id: `doc-${i}`,
-  vector: embeddings.data[i],
-  content: chunk.content,
-  metadata: chunk.metadata,
-}))
-await vecdb.vector.insert('knowledge', docs)
-```
-
-### 错误分支处理
-
-```typescript
-import { vecdb, HaiVecdbError } from '@h-ai/vecdb'
-
-const result = await vecdb.collection.create('docs', { dimension: 1536 })
-if (!result.success) {
-  switch (result.error.code) {
-    case HaiVecdbError.COLLECTION_ALREADY_EXISTS.code:
-      // 集合已存在，可跳过
-      break
-    case HaiVecdbError.NOT_INITIALIZED.code:
-      // 未初始化，需先 vecdb.init()
-      break
-    default:
-      // 意外错误
-      break
-  }
-}
-```
-
----
+## 按需参考
 
-## 相关 Skills
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
-- `hai-ai`：LLM 与 Embedding 能力
-- `hai-datapipe`：文本清洗与分块
-- `hai-reldb`：关系型数据库（知识库需要同时使用 reldb 存储结构化数据）
-- `hai-core`：配置管理、HaiResult 模型
+- 运行环境
+- 适用场景
+- 使用步骤
+- 核心 API
+- 错误码 — `HaiVecdbError`
+- 常见模式
+- 相关 Skills