API 约定

公共能力从根入口按需导入 createStorage、createDb、createHttp、createBridge、createClipboard、createLogger、createEnvironment。也可从对应显式 subpath 导入。普通辅助操作按动作命名，例如 unwrapBusinessEnvelope。

创建与配置

import 不读取宿主或注册监听。factory 创建能力对象并校验必要配置；业务请求、数据库连接和事件订阅通过实例方法显式发生。createEnvironment 会在调用时探测环境并生成不可变快照，不申请权限或执行存储写入。

创建后修改原配置对象不会重新配置实例。Bridge 省略 adapter 时使用延迟访问宿主的 App 适配；显式提供 adapter 时捕获其方法并保留 receiver；adapter 自己的内部状态仍可变化。Logger 的 getRoute/getTraceId 是明确的动态入口，每条日志求值。需要不同配置时创建新实例。

实例类型按领域职责命名：Bridge、StorageArea、Environment、Logger、HttpClient、Db、ClipboardClient，不要求统一类型后缀。Db 表示数据库能力入口，DbDatabase 表示打开的具体数据库；ClipboardClient 避免与 DOM 全局 Clipboard 类型混淆，HttpClient 表达 HTTP 请求客户端。保留清楚、简短的名称，仅在能澄清职责、行为或单位时改名。

失败处理

API	失败处理
HTTP endpoint、DB open / deleteDatabase / CRUD、Bridge call / 基础方法、Clipboard writeText	Promise reject 模块 Error
DB store / index 获取句柄	同步抛 DbError
Bridge on / subscription.dispose	同步抛错
Logger 方法	resolve failed 状态；不会因日志失败中断业务
Storage 方法	容错读取或 boolean 结果；可配置 onError 获取诊断；业务 updater 异常原样传播

DB 的 db.store(name) 和 store.index(name) 是同步方法。把句柄获取和 await 数据操作放在同一个 try/catch 中，才能同时捕获两类失败；只在链式表达式末尾调用 .catch() 无法捕获前面的同步异常。

例如 Bridge 调用直接返回数据，使用 try/catch 处理失败：

try {
  const data = await bridge.call('read', { id: '1' });
  useData(data);
} catch (error) {
  handleError(error);
}

模块错误类均可 instanceof，使用 kind 分类、code 识别运行时错误、cause 获取原始失败。HTTP 的 businessCode / transportCode、Bridge 的 hostCode 与运行时 code 分开。不要根据错误消息字符串编写业务分支。

Storage 的缺失、过期和版本不匹配属于正常读取结果。parser 异常或平台读写失败可由 createStorage(type, { onError }) 观察。需要事务及结构化查询时使用 DB。

能力检查与生命周期

Environment.supports 查询创建时的 API 存在性或宿主声明；Clipboard.isAvailable 检查当前复制策略是否存在，Db.isAvailable 检查当前 IndexedDB factory 是否存在，Storage.getInfo 使用临时写入探测当前存储可读写性。它们都不保证后续操作成功。

数据库连接通过 close 释放；事件 subscription 通过 dispose 释放。Bridge 调用超时只结束等待，无法撤销已执行的宿主动作。Environment 不自动刷新，需要时重新创建快照。

类型与宿主预设

Storage schema、Bridge 方法/事件表、HTTP endpoint 契约用于集中声明类型。泛型只提供静态检查，外部数据仍需验证。HTTP 可使用 Standard Schema，Bridge 的自定义契约由 adapter 与业务验证，getConfig/closePage 等基础方法验证其已声明回包字段。

Bridge 面向 App 内嵌 WebView：createBridge 默认接入约定的 App 协议，基础方法直接放在实例上，自定义调用与通知分别使用 call/on。自定义 adapter 返回已解码数据，不再自动解包。Native 日志协议使用 createBridgeLogTransport；HTTP 业务响应协议通过 decodeResponse: unwrapBusinessEnvelope 显式启用。