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

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

@@ -0,0 +1,202 @@
+# hai-scheduler 参考
+
+持久化动态任务每个 `tickInterval`（默认 1000ms）在运行节点刷新；API 操作及获锁后的每次尝试重读定义，读取失败或任务已禁用/删除/改期时中断执行。`tasks` 仅表示最近成功刷新快照，已开始的外部副作用不会回滚。跨节点任务使用 `register()` 与共享数据库、Redis；`init({ tasks })` 是节点本地配置，memory cache 不支持跨进程防重。
+
+`refreshTasks()` 主动刷新而不执行，同一快照的并发读取合并；保存、更新和删除落库成功后才发布内存投影。清空可选策略使用 `retry: null` / `handler: null`。Hook 业务异常为 `failed` 并重试，缺处理器、取消或 `SchedulerTaskSkippedError` 为 `interrupted`；一次性任务只在成功后删除。`event.context.occurrenceId` 在一次发生的重试期间不变，宿主用其绑定持久幂等回执；跨周期长任务使用宿主持久租约。配置被替换时旧发生停止重试，成功清理前再次核对定义。
+
+关闭必须 `await scheduler.close()` 后再关闭数据库和缓存：关闭会拒绝新任务、取消 HTTP/Worker/重试并等待执行链退出。生命周期回调通过事件 `signal` 协作取消，必须自行停止外部副作用，禁止在 Hook 阻塞主线程。旧任务取消后不重试、不删除新实例同 ID 的任务。
+
+JS 任务每次调用独立 Worker，默认 30000 毫秒期限包含线程启动；超时后等待线程终止才返回失败或重试，同步死循环不会占用主事件循环。上下文和结果须支持结构化克隆。Worker/vm 不构成安全沙箱，仍只接受受信任的服务端代码。
+
+初始化为全有或全无：必须检查 `init()` 的 HaiResult。空 ID、重复 ID（包括与数据库记录重复）、无效 cron、持久化读取或解析失败均使初始化失败并清理状态；修正后重试，不会静默跳过任务。
+
+API 任务 `timeout` 默认 30000 毫秒，覆盖请求及完整响应体读取；`maxResponseBytes` 指定实际接收字节上限（正安全整数，默认 1048576 即 1 MiB），例如 `maxResponseBytes: 10 * 1024 * 1024` 允许最大 10 MiB；非法值在请求前失败。超时、超限和非成功 HTTP 状态均失败，重试由任务 retry 策略控制。
+
+
+
+> `@h-ai/scheduler` 使用统一任务模型管理 API / JS / Hook 三类执行路径，支持持久化、手工触发来源记录、分布式锁与全局生命周期回调。
+
+## 运行环境
+
+> ⚠️ **服务端模块（Node.js only）。** 浏览器端通过 API 端点触发 `scheduler.trigger()` 或查询任务日志。
+
+## 依赖
+
+| 模块 | 用途 | 是否必需 | 初始化要求 |
+| --- | --- | --- | --- |
+| `@h-ai/reldb` | 任务定义与执行日志持久化 | `enableDb: true` 时必需 | 需在 `scheduler.init()` 前初始化 |
+| `@h-ai/cache` | 分布式锁 | 可选 | 初始化后自动启用 |
+
+## 使用步骤
+
+### 1. 初始化
+
+```ts
+import { cache } from '@h-ai/cache'
+import { core } from '@h-ai/core'
+import { reldb } from '@h-ai/reldb'
+import { scheduler } from '@h-ai/scheduler'
+
+await reldb.init({ type: 'sqlite', database: './scheduler.db' })
+await cache.init({ type: 'memory' })
+
+await scheduler.init({
+  enableDb: true,
+  maxLogs: 1000,
+  retentionDays: 30,
+  hooks: {
+    onTaskStart(event) {
+      core.logger.info('Task started', { taskId: event.task.id, trigger: event.trigger })
+    },
+    onTaskInterrupted(event) {
+      core.logger.warn('Task interrupted', { taskId: event.task.id, reason: event.reason })
+    },
+    onTaskFinish(event) {
+      core.logger.info('Task finished', { status: event.log.status })
+    },
+  },
+})
+```
+
+### 2. 注册任务
+
+```ts
+await scheduler.register({
+  id: 'health-check',
+  name: '健康检查',
+  description: '每 5 分钟巡检一次接口健康状态',
+  cron: '*/5 * * * *',
+  params: { channel: 'ops' },
+  retry: { maxAttempts: 3, backoffMs: [1000, 5000] },
+  handler: {
+    kind: 'api',
+    url: 'https://api.example.com/health',
+    method: 'GET',
+  },
+})
+
+await scheduler.register({
+  id: 'cleanup',
+  name: '清理过期数据',
+  description: '夜间单次清理任务',
+  cron: '0 2 * * *',
+  deleteAfterRun: true,
+  params: { source: 'nightly' },
+  handler: {
+    kind: 'js',
+    code: '(context) => ({ taskId: context.taskId, params: context.params })',
+  },
+})
+```
+
+> ⚠️ **安全警示**：`kind: 'js'` 仅允许受信任的服务端代码。当前实现在线程内使用 Node.js `vm`，超时可终止 Worker，但不构成安全沙箱；禁止把用户、租户或运营后台自由输入的 JS 字符串直接注册为任务。需要可配置执行逻辑时，优先改用 `kind: 'api'` 或 `hooks.onTaskExecute`。
+
+### 3. 使用全局 execute hook 处理无 handler 任务
+
+```ts
+await scheduler.setHooks({
+  async onTaskExecute(event) {
+    return { via: 'hook', source: event.context.trigger.source }
+  },
+})
+
+await scheduler.register({
+  id: 'hook-task',
+  name: 'Hook 任务',
+  cron: '* * * * *',
+})
+```
+
+### 4. 手工触发与日志查询
+
+```ts
+const result = await scheduler.trigger('cleanup', { source: 'admin-console' })
+
+const logs = await scheduler.getLogs({
+  taskId: 'cleanup',
+  triggerType: 'manual',
+  triggerSource: 'admin-console',
+  startedAfter: Date.now() - 24 * 60 * 60 * 1000,
+  startedBefore: Date.now(),
+  pagination: { page: 1, pageSize: 20 },
+})
+```
+
+## 核心 API
+
+| 方法 / 属性 | 签名 | 说明 |
+| --- | --- | --- |
+| `init` | `(config?) => Promise<HaiResult<void>>` | 初始化调度器 |
+| `register` | `(task) => Promise<HaiResult<void>>` | 注册统一任务模型 |
+| `updateTask` | `(taskId, updates) => Promise<HaiResult<void>>` | 更新 cron / params / handler |
+| `refreshTasks` | `() => Promise<HaiResult<void>>` | 主动刷新共享定义，不执行任务 |
+| `register` 扩展字段 | `description / deleteAfterRun / retry` | 支持任务描述、一次性任务、失败重试策略 |
+| `trigger` | `(taskId, { source? }) => Promise<HaiResult<TaskExecutionLog>>` | 手工触发并记录来源 |
+| `getLogs` | `(options?) => Promise<HaiResult<PaginatedResult<TaskExecutionLog>>>` | 支持按 trigger + startedAfter/startedBefore 过滤日志 |
+| `setHooks` | `(hooks) => HaiResult<void>` | 设置全局生命周期回调 |
+| `clearHooks` | `() => HaiResult<void>` | 清空全局生命周期回调 |
+| `start / stop` | `() => HaiResult<void>` | 启动 / 停止调度 |
+| `close` | `() => Promise<void>` | 关闭调度器 |
+
+## 常见模式
+
+### 持久化 JS 任务
+
+```ts
+await scheduler.init({ enableDb: true })
+
+await scheduler.register({
+  id: 'persisted-js',
+  name: '持久化 JS 任务',
+  cron: '*/10 * * * *',
+  handler: {
+    kind: 'js',
+    code: '(context) => ({ taskId: context.taskId })',
+  },
+})
+```
+
+### 手工触发来源审计
+
+```ts
+await scheduler.trigger('cleanup', { source: 'admin-console' })
+await scheduler.trigger('cleanup', { source: 'cli' })
+
+const adminLogs = await scheduler.getLogs({ triggerSource: 'admin-console' })
+```
+
+### 分布式锁
+
+```ts
+await cache.init({ type: 'redis', host: 'localhost', port: 6379 })
+await reldb.init({ type: 'sqlite', database: './scheduler.db' })
+await scheduler.init({
+  enableDb: true,
+  maxLogs: 500,
+  retentionDays: 14,
+  lockExpireMs: 300000,
+  nodeId: 'node-1',
+})
+```
+
+## 错误码 — `HaiSchedulerError`
+
+| 错误码 | code | 说明 |
+|--------|------|------|
+| `HaiSchedulerError.NOT_INITIALIZED` | `hai:scheduler:010` | 未初始化 |
+| `HaiSchedulerError.INIT_FAILED` | `hai:scheduler:011` | 初始化失败 |
+| `HaiSchedulerError.CONFIG_ERROR` | `hai:scheduler:012` | 配置错误 |
+| `HaiSchedulerError.TASK_NOT_FOUND` | `hai:scheduler:020` | 任务不存在 |
+| `HaiSchedulerError.TASK_ALREADY_EXISTS` | `hai:scheduler:021` | 任务已存在 |
+| `HaiSchedulerError.INVALID_CRON` | `hai:scheduler:022` | Cron 表达式无效 |
+| `HaiSchedulerError.EXECUTION_FAILED` | `hai:scheduler:023` | 执行失败 |
+| `HaiSchedulerError.JS_EXECUTION_FAILED` | `hai:scheduler:024` | JS 执行失败 |
+| `HaiSchedulerError.API_EXECUTION_FAILED` | `hai:scheduler:025` | API 执行失败 |
+| `HaiSchedulerError.DB_SAVE_FAILED` | `hai:scheduler:026` | DB 保存失败 |
+| `HaiSchedulerError.ALREADY_RUNNING` | `hai:scheduler:027` | 已在运行 |
+| `HaiSchedulerError.NOT_RUNNING` | `hai:scheduler:028` | 未在运行 |
+| `HaiSchedulerError.LOCK_ACQUIRE_FAILED` | `hai:scheduler:029` | 锁获取失败 |
+| `HaiSchedulerError.JS_COMPILE_FAILED` | `hai:scheduler:030` | JS 编译失败 |
+| `HaiSchedulerError.HOOK_EXECUTION_FAILED` | `hai:scheduler:031` | Hook 执行失败 |
+
+调度循环按分钟时间点匹配 cron，并用同一分钟生成分布式锁键；启动或 tick 延迟至非零秒仍检查当前分钟，同一轮运行不会每个 tick 重复调度。

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

@@ -1,6 +1,6 @@
 ---
 name: hai-serv
-description: "使用 @h-ai/serv 装配 contract/procedures、认证守卫、OpenAPI、HTTP 与语音 WebSocket。"
+description: "为独立 API 服务装配 contract/procedures、认证守卫、Node/Fetch、OpenAPI 与语音 WebSocket。"
 ---
 
 # hai-serv
@@ -25,7 +25,7 @@ description: "使用 @h-ai/serv 装配 contract/procedures、认证守卫、Open
 
 ## 按需参考
 
-详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 运行环境
 - 适用场景

package/templates/skills/hai-spec-implement/SKILL.md

@@ -25,7 +25,7 @@ description: "从需求或设计文档规划、执行、返修 hai 应用，或
 2. 按下方原则决定一个任务还是多个任务，使用 [任务文档范本](templates.md) 写入清单、文档基线和任务记录。一个任务也保留清单及记录，已有清单优先更新，不重复规划已交付内容。
 3. 执行、继续或返修时读取 [执行与 Git 流程](workflow.md)，核验依赖、工作区、主分支和实际状态；每个任务使用记录中的独立分支。
 4. 按 [hai-app-create](../hai-app-create/SKILL.md) 与当前版本公开契约实现，按 [hai-app-tests](../hai-app-tests/SKILL.md) 做 Red → Green → Refactor，按 [hai-app-review](../hai-app-review/SKILL.md) 审查改动。只读取当前任务需要的模块资源。
-5. 验证、提交、合并后更新清单与任务记录；全部目标范围验收通过才推进文档基线，规则见 [基线收尾](changes.md#验收与基线推进)。报告完成任务、旧/新文档 SHA、实现/合并提交、门禁和剩余阻塞；验证通过但尚未合并不能标为已完成。
+5. 按 [分轮验证与集中修复](../hai-app-tests/validation.md) 先收集适用门禁、集中修复再复测；验证、提交、合并后更新清单与任务记录。全部目标范围验收通过才推进文档基线，规则见 [基线收尾](changes.md#验收与基线推进)。报告完成任务、旧/新文档 SHA、实现/合并提交、门禁和剩余阻塞；验证通过但尚未合并不能标为已完成。
 
 ## 拆分原则
 

package/templates/skills/hai-spec-implement/workflow.md

@@ -36,14 +36,14 @@
 
 ## 验证、提交与合并
 
-1. 按项目已有脚本和影响范围依次运行 typecheck → lint → build（构建/模板/跨包变更）→ test；UI、路由、跨层流程再跑适用 E2E，涉及界面时保留可核验截图。工作区包优先用 filter，不能拿缓存/旧截图代替当前行为。未运行、失败、mock 与真实环境分别记录。
+1. 按项目已有脚本和影响范围执行 [分轮验证与集中修复](../hai-app-tests/validation.md)：先收集本轮全部可执行的 typecheck/lint/build/test 及适用 E2E，普通失败不边测边改；汇总后集中修复、再验证。涉及界面保留可核验截图，工作区包优先用 filter；不能拿旧产物/旧截图代替当前行为，未运行、失败、mock 与真实环境分别记录。
 2. 把主分支的新提交合入任务分支，解决冲突后重跑受影响门禁；若主分支再次推进，重新同步及验证。冲突按当前需求和双方真实改动解决，不能整体选择 ours/theirs 覆盖其他任务。
 3. 通过后将本轮状态更新为“已验证”，只提交本任务的代码、配置、测试、说明和任务信息；检查 staged diff，不能混入用户或其他任务改动。可保留有意义的小步提交，不要求每个任务只有一个 commit。
 4. 回到主分支（或它对应的干净 worktree），将任务分支合并；项目没有相反规则时使用 `git merge --no-ff <任务分支>` 保留任务边界。明确授权执行本工作流时可完成本地合并；用户明确只要分支/待审结果时保持“已验证”。遵守项目受保护分支/PR 规则，不绕过；远端推送、PR、发布依用户实际授权处理。
-5. 核对实际集成提交及主分支已包含本轮改动；项目采用 squash/rebase 时记录对应提交，不能假定 SHA 保持不变。运行集成后受影响验证。所有任务完成后再执行项目要求的全量门禁和整体需求验收；最终任务保持“已验证”，直到这些检查通过。失败先修复，不把 Git 合并成功当成业务验证通过。
+5. 核对实际集成提交及主分支已包含本轮改动；项目采用 squash/rebase 时记录对应提交，不能假定 SHA 保持不变。运行集成后受影响验证。所有任务完成后再按分轮流程收集项目要求的全量门禁和整体需求验收，汇总后集中修复、再验证；最终任务保持“已验证”，直到这些检查通过。不把 Git 合并成功当成业务验证通过。
 6. 在主分支将清单和任务记录更新为“已完成”，写入本轮任务分支 tip SHA、实际 merge SHA、集成验证结果和下一步，做独立的文档记账提交。merge SHA 在合并后才能知道，不能预填、也不能 amend 已合并提交去补记录。保留任务分支，以便返修。整个计划/变更轮次的已验收文档与实现基线只按 [基线收尾](changes.md#验收与基线推进) 推进，单个任务完成不代表整体完成。
 
-有中断时保存实际阶段及下一步。已经合并却验证失败时，记录实际 merge SHA 和失败，清单保持“进行中”或“阻塞”，回原任务分支修复；后续任务暂不越过失败依赖。收尾报告区分“代码已合并”与“任务已完成”。
+有中断时保存实际阶段及下一步。已经合并却验证失败时，记录实际 merge SHA 和失败，先收集本轮其余可执行检查，清单保持“进行中”或“阻塞”，汇总后回原任务分支集中修复；后续任务暂不越过失败依赖。收尾报告区分“代码已合并”与“任务已完成”。
 
 ## 原任务返修
 

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

@@ -1,6 +1,6 @@
 ---
 name: hai-storage
-description: "使用 @h-ai/storage 访问本地/S3 文件、目录和预签名上传下载。"
+description: "实现本地/S3 文件与目录操作、流式读写、checksum 和预签名上传下载；处理冲突、校验与取消。"
 ---
 
 # hai-storage
@@ -15,244 +15,23 @@ description: "使用 @h-ai/storage 访问本地/S3 文件、目录和预签名
 | 输出 | file/dir/presign 操作的 HaiResult；checksum 生成字符串或校验结果 |
 | 限制 | 仅服务端；浏览器经 API/预签名 URL。Local list 非真分页；putUrl 不提供 maxSize 强制约束，上传大小须服务端验证。 |
 
-> `@h-ai/storage` 提供统一文件存储接口，支持本地文件系统（LocalProvider）和 S3 兼容存储（S3Provider），通过 `storage.file`、`storage.dir`、`storage.presign` 访问存储，`storage.checksum` 提供 Node 端无需初始化的字节完整性工具。
+## 使用路径
 
-## 运行环境
+1. Node 端配置 Local/S3，校验并检查 init；MinIO/RustFS 使用 s3 类型，确认桶和权限。
+2. 从 file/dir/presign 选择操作，检查 HaiResult。流与 checksum 按真实签名处理，checksum 在 Node 无需 init。
+3. 客户端经受保护 API 或预签名 URL，服务端校验路径、内容、大小及资源权限；putUrl 不强制 maxSize。
+4. 不覆盖上传使用 ifNoneMatch；冲突/checksum 失败不能伪装成功。验证取消、流错误和文件清理，最后 close。
 
-> ⚠️ **服务端模块**。`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）
+- [运行环境](reference.md#运行环境)
+- [适用场景](reference.md#适用场景)
+- [使用步骤](reference.md#使用步骤)
+- [核心 API](reference.md#核心-api)
+- [错误码 — `HaiStorageError`](reference.md#错误码--haistorageerror)
+- [HTTP API 契约](reference.md#http-api-契约)
+- [常见模式](reference.md#常见模式)
+- [浏览器端文件上传（预签名 URL 模式）](reference.md#浏览器端文件上传预签名-url-模式)
+- [相关 Skills](reference.md#相关-skills)