@h-ai/cli 0.1.0-alpha.65 → 0.1.0-alpha.67

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

@@ -0,0 +1,243 @@
+# hai-storage 参考
+
+> `@h-ai/storage` 提供统一文件存储接口，支持本地文件系统（LocalProvider）和 S3 兼容存储（S3Provider），通过 `storage.file`、`storage.dir`、`storage.presign` 访问存储，`storage.checksum` 提供 Node 端无需初始化的字节完整性工具。
+
+## 运行环境
+
+> ⚠️ **服务端模块**。`storage.file` / `storage.dir` / `storage.presign` 均在 Node.js 端使用。浏览器端通过预签名 URL 或 API 端点间接访问存储（见下方「浏览器端文件上传」）。
+
+## 适用场景
+
+- 文件上传与下载
+- 预签名 URL 生成（客户端直传）
+- S3 兼容存储对接（AWS S3、MinIO、RustFS、阿里云 OSS 等）
+- 本地开发文件存储
+- 目录前缀清理与批量文件删除
+
+## 使用步骤
+
+### 1. 配置
+
+```yaml
+# config/_storage.yml
+type: local # local | s3
+# 本地存储
+root: ./data/storage
+# S3 存储（type=s3 时生效）
+# endpoint: ''
+# region: us-east-1
+# accessKeyId: ''
+# secretAccessKey: ''
+# bucket: my-bucket
+# forcePathStyle: false
+# prefix: ''
+# publicUrl: ''
+operationLog:
+  read: false # file.get/head/exists, dir.list, presign.getUrl/publicUrl
+  write: false # file.put/delete/deleteMany/copy, dir.delete, presign.putUrl
+  maxLength: 1000
+  level: debug # info | debug | trace
+```
+
+约定环境变量优先于 YAML，例如 `HAI_STORAGE_ROOT`、
+`HAI_STORAGE_ACCESSKEYID`、`HAI_STORAGE_SECRETACCESSKEY`。
+
+MinIO、RustFS 使用同一个 S3 Provider：配置 `type: s3`、S3 API `endpoint`（通常为 9000 端口）和 `forcePathStyle: true`，并预先创建 `bucket`；不要新增 `type: minio` 或 `type: rustfs`。
+
+使用 hai-deploy 的默认自建 S3 配置时，可通过 `container.s3Engine`（`HAI_DEPLOY_CONTAINER_S3ENGINE`，`rustfs | minio`）选择实现，默认 RustFS。部署流程复用应用镜像中的 S3 SDK 幂等初始化 bucket，不依赖单独的 mc 镜像；自定义外部 S3 服务仍需确认 bucket 已存在且凭据有相应权限。
+
+`operationLog` 在 Local/S3 Provider 的真实 file/dir/presign 操作处输出日志，不要在 `storage-main.ts` 或调用方重复包装。文件内容不会写入日志，上传数据只记录字节长度；`maxLength` 用于截断序列化后的参数，`level` 默认 `debug`。
+
+### 2. 初始化与关闭
+
+```typescript
+import { storage } from '@h-ai/storage'
+
+await storage.init(core.config.get('storage'))
+// 使用后关闭
+const closeResult = await storage.close()
+if (!closeResult.success) {
+  throw new Error(closeResult.error.message)
+}
+```
+
+> `storage.config` 返回的是**脱敏配置快照**；S3 的 `accessKeyId` / `secretAccessKey` 等敏感字段会被替换为 `[REDACTED]`。
+
+## 核心 API
+
+### 文件操作
+
+`storage.file` 提供以下方法：
+
+- `put(key, data, options?)`
+- `get(key, options?)`
+- `getStream(key, options?)`（字节流，迭代错误可抛出）
+- `head(key)`
+- `exists(key)`
+- `delete(key)`
+- `deleteMany(keys)`
+- `copy(sourceKey, destKey, options?)`
+
+```typescript
+// 上传文件
+const result = await storage.file.put('avatars/user-123.png', fileBuffer, {
+  contentType: 'image/png',
+  metadata: { userId: '123' },
+})
+
+// 下载文件
+const file = await storage.file.get('avatars/user-123.png')
+
+// 列出文件
+const files = await storage.dir.list({ prefix: 'avatars/', maxKeys: 100 })
+```
+
+### 预签名 URL
+
+`storage.presign` 提供以下方法：
+
+- `getUrl(key, options?)`
+- `putUrl(key, options?)`
+- `publicUrl(key)`
+
+```typescript
+// 客户端直传模式
+const uploadUrl = await storage.presign.putUrl('uploads/doc.pdf', {
+  expiresIn: 3600, // 1 小时有效
+  contentType: 'application/pdf',
+})
+
+// 临时下载链接
+const downloadUrl = await storage.presign.getUrl('uploads/doc.pdf', {
+  expiresIn: 300, // 5 分钟有效
+})
+```
+
+> `storage.presign.putUrl()` 当前不支持 `maxSize` 约束参数；如需大小限制，请在应用层上传前校验，或在服务端落库/回调处二次校验。
+
+## 错误码 — `HaiStorageError`
+
+| 错误码 | code | 说明 |
+|--------|------|------|
+| `HaiStorageError.CONNECTION_FAILED` | `hai:storage:001` | 连接失败 |
+| `HaiStorageError.OPERATION_FAILED` | `hai:storage:002` | 操作失败 |
+| `HaiStorageError.NOT_FOUND` | `hai:storage:003` | 文件不存在 |
+| `HaiStorageError.ALREADY_EXISTS` | `hai:storage:004` | 文件已存在 |
+| `HaiStorageError.CHECKSUM_FAILED` | `hai:storage:016` | checksum 读取/计算失败 |
+| `HaiStorageError.INVALID_CHECKSUM` | `hai:storage:017` | checksum 格式/算法非法 |
+| `HaiStorageError.PERMISSION_DENIED` | `hai:storage:005` | 权限不足 |
+| `HaiStorageError.QUOTA_EXCEEDED` | `hai:storage:006` | 配额超限 |
+| `HaiStorageError.INVALID_PATH` | `hai:storage:007` | 路径无效 |
+| `HaiStorageError.IO_ERROR` | `hai:storage:008` | IO 错误 |
+| `HaiStorageError.NETWORK_ERROR` | `hai:storage:009` | 网络错误 |
+| `HaiStorageError.NOT_INITIALIZED` | `hai:storage:010` | 未初始化 |
+| `HaiStorageError.UNSUPPORTED_TYPE` | `hai:storage:011` | 不支持的存储类型 |
+| `HaiStorageError.CONFIG_ERROR` | `hai:storage:012` | 配置错误 |
+| `HaiStorageError.PRESIGN_FAILED` | `hai:storage:013` | 预签名 URL 生成失败 |
+| `HaiStorageError.UPLOAD_FAILED` | `hai:storage:014` | 上传失败 |
+| `HaiStorageError.DOWNLOAD_FAILED` | `hai:storage:015` | 下载失败 |
+
+## HTTP API 契约
+
+公共 HTTP API 统一由 `@h-ai/api-contract` 提供，并由 `@h-ai/serv/features/storage` 绑定到本模块。
+
+```typescript
+import { apiClient } from '@h-ai/api-client'
+
+const result = await apiClient.storage.presignedUrls.createUpload({ key: 'avatar.png' })
+```
+
+## 常见模式
+
+大文件上传用 `file.put(key, readableOrAsyncByteStream, { signal, ifNoneMatch: '*' })`，内部使用有界 S3 multipart；下载用 `file.getStream(key, { signal, rangeStart, rangeEnd })`，及时消费或关闭，迭代期间 I/O/取消可能抛错。本地读取目录直接返回 `INVALID_PATH`。checksum 的 signal 取消会停止等待下一块数据并请求关闭输入迭代器。`get()` 返回完整 Buffer，只用于容量可控的数据。仅创建写入采用 S3 标准条件或本地原子发布，冲突返回 `ALREADY_EXISTS`；后端不支持时失败，不退回覆盖。
+
+`checksum.generate(data, options?)` / `checksum.verify(data, expected, options?)` 默认 SHA-256、小写 hex，可选 sha384/sha512/sha1/md5、base64 编码与 signal；流仅消费一次，读取失败返回 HaiResult 错误，不匹配返回 false。MD5/SHA-1 不作安全认证，ETag 和 multipart 复合 checksum 不当作完整文件摘要。浏览器不导入 Node checksum；离线增量摘要需使用适用的浏览器实现，不把 SubtleCrypto.digest 当流式 API。
+
+### 与 kit 集成（文件上传 API）
+
+```typescript
+import { storage } from '$lib/server/init'
+// src/routes/api/files/upload/+server.ts
+import { kit } from '@h-ai/kit'
+import { z } from 'zod'
+
+const UploadSchema = z.object({
+  key: z.string().min(1),
+})
+
+export const POST = kit.handler(async ({ request, locals }) => {
+  kit.guard.require(locals.session, 'storage:write')
+  const formData = await request.formData()
+  const file = formData.get('file') as File
+  if (!file)
+    return kit.response.badRequest('Missing file')
+
+  const key = `uploads/${locals.session.userId}/${file.name}`
+  const buffer = new Uint8Array(await file.arrayBuffer())
+  const result = await storage.file.put(key, buffer, { contentType: file.type })
+  if (!result.success)
+    return kit.response.internalError()
+  return kit.response.created({ key })
+})
+```
+
+> 说明：`@h-ai/storage` 只提供存储能力，不强制要求 `/api/storage` 路由命名。应用可按业务语义自定义 API 路径。
+
+> Local Provider 的 `storage.dir.list()` 会递归扫描匹配前缀下的文件，仅支持 `maxKeys` 截断，不支持 `continuationToken` 真分页；大目录建议缩小 `prefix` 或改用 S3 Provider。
+
+### 头像上传
+
+```typescript
+const key = `avatars/${userId}/${Date.now()}.png`
+const result = await storage.file.put(key, avatarBuffer, {
+  contentType: 'image/png',
+})
+if (result.success) {
+  const publicUrl = storage.presign.publicUrl(key)
+  await iam.user.updateUser(userId, { avatarUrl: publicUrl ?? '' })
+}
+```
+
+## 浏览器端文件上传（预签名 URL 模式）
+
+浏览器端无法直接使用 `storage` 模块，应通过 API 获取预签名 URL 后直传：
+
+```typescript
+import { apiFetch } from '$lib/utils/api'
+
+// 1. 向服务端请求预签名上传 URL
+const res = await apiFetch('/api/storage/presign/upload', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ key: `uploads/${file.name}`, contentType: file.type }),
+})
+const { url } = await res.json()
+
+// 2. 浏览器直传到存储（不经过服务端，大文件友好）
+await fetch(url, {
+  method: 'PUT',
+  body: file,
+  headers: { 'Content-Type': file.type },
+})
+```
+
+也可使用 typed client（需配合 `@h-ai/api-client`）：
+
+```typescript
+import { apiClient } from '@h-ai/api-client'
+
+const result = await apiClient.storage.presignedUrls.createUpload({
+  key: `avatars/${userId}.png`,
+  contentType: 'image/png',
+})
+if (result.success) {
+  await fetch(result.data.url, { method: 'PUT', body: file })
+}
+```
+
+## 相关 Skills
+
+- `hai-build`：模块初始化顺序
+- `hai-core`：配置与 HaiResult 模型
+- `hai-kit`：SvelteKit API 端点集成（`kit.handler` + `kit.guard`）
+- `hai-ui`：Storage 场景组件（FileUpload/ImageUpload/AvatarUpload）

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

@@ -31,7 +31,7 @@ description: "使用 @h-ai/ui 构建 Svelte 5 表单、表格、弹窗、新手
 
 新手引导、首次 Cookie 提示、操作导览和帮助中心见 [guide.md](guide.md)。fullstack 默认在共享管理界面接入，新增业务只补内容与 data-guide 锚点。
 
-详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 运行环境
 - 适用场景

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

@@ -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}`。
 
@@ -89,7 +89,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 +99,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 +145,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'],
   },
 })
 ```
@@ -606,6 +609,8 @@ AuthPanel 直接接收 IAM 白名单配置和 actions，内置登录（密码/LD
 
 AuthPanel 在 SSR 阶段禁用原生表单控件，客户端挂载并绑定事件后自动开放输入，避免接管时丢失早到的输入。应用无需额外的就绪适配；E2E 等待控件可编辑，并覆盖客户端脚本延迟加载的场景。
 
+认证链接指向当前完整 URL 时，AuthPanel 只切换场景并阻止重复导航，返回登录后可立即输入。路径、查询串或 hash 不同时交给应用路由处理；Ctrl/Cmd 等修改键点击保留浏览器行为。不要为切换场景额外调用 goto 或 location.reload。
+
 
 协议在 Modal 内显示并保留表单输入；使用 URL 时，协议页面须允许 iframe 嵌入，组件禁用其脚本，另提供新窗口查看入口。登录/注册表单使用 `header/extraFields/footer` snippet，AuthPanel 透传 `loginHeader/loginFields/loginFooter` 和 `registerHeader/registerFields/registerFooter`，底部保留内置导航。自定义字段由应用绑定状态和提交，不会隐式写入 IAM 用户模型。
 
@@ -632,8 +637,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 重复封装组件
 
 ## 导出路径
 

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

@@ -1,6 +1,6 @@
 ---
 name: hai-vecdb
-description: "使用 @h-ai/vecdb 管理 LanceDB/pgvector/Qdrant/Chroma 集合与向量检索。"
+description: "使用 LanceDB/pgvector/Qdrant/Chroma 管理向量集合、写入和检索；排查维度、连接与过滤问题。"
 ---
 
 # hai-vecdb
@@ -22,7 +22,7 @@ description: "使用 @h-ai/vecdb 管理 LanceDB/pgvector/Qdrant/Chroma 集合与
 
 ## 按需参考
 
-详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 运行环境
 - 适用场景