# @happyvertical/smrt-web 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/smrt-web/

版本：0\.62\.1
npm 元数据更新时间：2026-11-17T07:54:42.668Z
中文译文更新时间：2026-11-17T09:43:45.082Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/smrt-web
原文对照：https://npmcn.com/package/%40happyvertical/smrt-web/?lang=original
项目主页：https://github.com/happyvertical/smrt#readme
源码仓库：https://github.com/happyvertical/smrt

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.1 MB，73 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-07-03T18:04:12.739Z
- 最新版本发布：2026-11-17T07:54:42.475Z
- 近 30 天下载量：20193（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：323（近 12 个月 323 个）

## 中文简介

SMRT 浏览器客户端数据运行时间: 键入收集厂将客户端-数据引擎包入生成的 REST 客户端

## 安装

```sh
npm install @happyvertical/smrt-web
```

也可以使用：`pnpm add @happyvertical/smrt-web`、`yarn add @happyvertical/smrt-web`、`bun add @happyvertical/smrt-web`

## README

# @happy垂直/smrt-web

生成的 s-m-r-t REST 集合的框架不可知浏览器数据运行时间 。 这个 将显式生成的收集定义变成缓存的、被动的、, 乐观的客户端收藏,同时将基础数据引擎放在后面 s -m -r.

用于浏览器侧收藏状态, 共享请求分解, 离线 写入、 坚持读取缓存和活化无效 。 丝绒绑住 [`@happyvertical/smrt-svelte/web`](https://npmcn.com/package/%40happyvertical/smrt-svelte/README.md)。 。 。 .

查询后表面可以使用 `createSmrtWebQuery(collection, transport)` 改为 获取一个划线的页面 。 可见运行更新状态; `background`, (中文(简体) ), `prefetch`,以及 `silent` 运行远离可见状态。 控制器保留 刷新时 stale 行可用, 取消替换可见行, 并且可以 附加一个查询范围实况订阅.

数据表面行动使用情况 `executeSmrtWebDataSurfaceAction(transport, request)`。 。 。 . 其请求载有服务器发布的修订版,并附有适用性 键; 浏览器规范化器拒绝格式错误、大小过大或不匹配 在到达UI状态前预览/应用结果. 认证的服务器仍然 获得权威并验证确认符.

## 安装

```bash
pnpm add @happyvertical/smrt-web
```

## 快开始

s-m-r-t的 Vite 插件通过 `@happyvertical/smrt-virt-web` 虚拟模块 :

```ts
import {
  createSmrtCollection,
  createSmrtWebClient,
} from '@happyvertical/smrt-web';
import { getCollectionDefinition } from '@happyvertical/smrt-virt-web';

const client = createSmrtWebClient();
const products = createSmrtCollection(
  getCollectionDefinition('products'),
  { basePath: '/api/v1', client },
);

await products.preload();
console.log(products.toArray);

const transaction = products.insert({
  id: crypto.randomUUID(),
  name: 'New product',
});
await transaction.isPersisted.promise;
```

传出同样的 `client` 用于共享缓存身份的相关收藏, 飞行中请求中断, 和关系产生的无效.

## 数据行为

-   读取的读取是陈旧的,同时重新验证; `staleTimeMs` 默认为30秒.
-   同时期的同义读取连接到一个网络请求中 .
-   插入是乐观的,如果持久性失败则会退后.
-   `initialData` 种子 SSR-水分行,不重复第一手取取取.
-   公共行为平面 DTO; 数据引擎类型和虚拟字段不交叉 软件包边界.

## 可选能力

能力是每次收集选入的,并经过稳定的生命周期接合. 没有它们的收藏保留了基本的运行时间行为.

### 持久离线写入

```ts
import { offlineOutbox } from '@happyvertical/smrt-web';

const products = createSmrtCollection(definition, {
  capabilities: [
    offlineOutbox({
      object: definition,
      namespace: {
        apiBase: '/api',
        tenantId,
        identityId: userId,
        manifestHash,
      },
      syncApplyBasePath: '/api',
    }),
  ],
});
```

IndexedDB出道盒通过生成的同步应用合同重放FIFO. 客户端 UUID 和 idepotent 严格插入对齐乐观行 创建第二个服务器身份。 Web 锁定会选出一个重播指挥 选项卡.

### 通过您自己的服务器操作进行离线写入

当一个模型生成的写动词因权限而关闭时 服务拥有其写规则,通过该操作重放而不是 `sync/apply`。通过 `transport` 改为 `offlineOutbox()` 用于收集或使用 `offlineCommandQueue()` 没有收藏的写法 :

```ts
import {
  dataSurfaceActionCommandTransport,
  offlineCommandQueue,
} from '@happyvertical/smrt-web';

const punches = offlineCommandQueue({
  name: 'clock_in',
  namespace, // the same DurableStoreKey as the app's other outboxes
  transport: dataSurfaceActionCommandTransport({
    transport: actionTransport, // the surface's online action transport
    request: (command) => ({
      identity: descriptor.identity,
      actionId: 'clock-in',
      expectedRevision: currentRevision(), // read at first replay, then pinned
      selection: { scope: 'current-page' },
      payload: command.payload,
    }),
  }),
});

const itemId = await punches.enqueue({ payload: { note } });
if (!itemId) {
  // Not captured durably (no IndexedDB): perform the action online instead.
}
```

每个回放都带有耐用性 `idempotencyKey`,该服务器 操作必须打开。 每条路由在自己的跨塔布下重放 FIFO 领导,有相同的后退和 `pending → uploading → synced | failed` 状态 机器。 机器。 。 重新装入的写入等待队列带有它的名字附加; 它是 从未改道 `sync/apply`。 。 。 .

### 清理共享设备的陈旧数据

`listDurableNamespaces()` 返回此浏览器的持久存储命名空间 持有(只有名称,没有内容) . `pruneDurableNamespace(namespace, { olderThan })` 删除此命名空间的队列已下线, 并排入前 `olderThan` 联合国 `Date` 不挂起队列: 无重放, 无传送 仅限 `{ removed, skipped }` 计数回来。 线路a上的项目 正在重放的活的队列( 在任意标签中) 被跳过 。 用它来变老 个人在共享硬件上排队的工作; 持续读取快照没有年龄 并留给 `wipeDurableStore`。 。 。 .

```ts
const cutoff = Date.now() - 7 * 24 * 60 * 60 * 1000;
for (const namespace of await listDurableNamespaces()) {
  await pruneDurableNamespace(namespace, { olderThan: cutoff });
}
```

### 已读缓存

`persistCollection()` 从索引化的 DB 快照启动温暖,然后重新验证 在背景中。 其命名空间包括API、租户、身份和清单 hash,因此用户开关和合同更改不能将另一个瞄准镜的行水合. 敏感收藏应省略这一能力.

`persistDataSurface({ namespace, identity })` 对挂载数据所做的同样 表面,其行来自主范围查询,而不是生成 `list` 路径 : `load()` 在第一次接货之前, `save(rows)` 每次刷新之后. 它共享命名空间, 所以同样的擦擦干净它.

### 实时无效

创建一个全应用程序 `createSmrtWebEventSubscriber()` 和登记 `liveInvalidation({ subscriber, tableName })` 每个收藏。 它会消耗 名称 `_events` SSE 框架和永久降级为 `_changes` 投票时间 SSE不可用或致命关闭。 授权和租赁 生成服务器读取路径; 信号不含行有效载荷 .

### 更新认识

`createUpdateState()` 将捆绑式的更新信号和合同显示信号结合起来. 斯维尔特适配器 `useUpdateAvailable` 连接到 SvelteKit 的更新商店 .

## 引擎边界

当前执行在内部使用 TanStack DB,但没有 `@tanstack/*` 类型可能在公共API中出现或生成声明。 应用程序必须 取决于 `SmrtWebCollection` 财务报告和审定财务报表 `SmrtWebClient`,保留引擎 可替换并阻止 Svelte 唯一的出口进入框架中性 核心键.

## 公共API团体

| 组 | 主要出口 |
| --- | --- |
| 收款 | `createSmrtCollection`, (中文(简体) ), `createSmrtWebClient`, (中文(简体) ), `newLocalId` |
| 远程查询 | `createSmrtWebQuery`, (中文(简体) ), `SmrtWebQueryTransport` |
| 数据表面行动 | `executeSmrtWebDataSurfaceAction`, (中文(简体) ), `SmrtWebDataSurfaceActionTransport`, (中文(简体) ), `dataSurfaceActionCommandTransport` |
| HTTP 密码 | `createDefinitionFetchers`, (中文(简体) ), `unwrapListResult`, (中文(简体) ), `unwrapItemResult` |
| 离线 | `offlineOutbox`, (中文(简体) ), `offlineCommandQueue`, (中文(简体) ), `getOutboxHandle`, (中文(简体) ), `listDurableNamespaces`, (中文(简体) ), `pruneDurableNamespace` |
| 持久性 | `persistCollection`, (中文(简体) ), `persistDataSurface`, (中文(简体) ), `wipeDurableStore` |
| 实时更新 | `createSmrtWebEventSubscriber`, (中文(简体) ), `liveInvalidation` |
| 版本意识 | `createUpdateState` |
| 网络MCP | `registerWebMcpTools`, (中文(简体) ), `registerWebMcpBespokeTool`, (中文(简体) ), `registerViewIntent`, (中文(简体) ), `reserveWebMcpToolNames` |

## WebMCP能力曝光

`registerWebMcpTools()` 默认安全: 省略曝光政策 仅登记 `read` 工具。 CRUD效应是固定的(`list`编号 :`get` 为: `read`, (中文(简体) ), `create`编号 :`update` 为: `write`,以及 `delete` 实值 `destructive`) (中文(简体) ). 自定义动作 未申报的元数据被视为具有破坏性、非理想性和开放性 这个世界 仅在路由元数据中宣布更安全的自定义动作语义 这些都是事实:

```ts
@smrt({
  api: {
    routes: {
      preview: {
        method: 'GET',
        effect: 'read',
        idempotent: true,
        openWorld: false,
      },
    },
  },
})
class Report extends SmrtObject {}
```

明确选择更广泛的能力. `namespace` 防止地表交叉 名称相撞, 明确 `maxTools` 链接所选集,并复制 名称或稳定的收集/行动身份 第一个浏览器注册。 不对全局适用隐含预算 改为注册 :

```ts
registerWebMcpTools(definitions, {
  effects: ['read', 'write', 'destructive'],
  namespace: 'admin',
  maxTools: 32,
  filter: (collection, tool) => collection.fields.tenantId !== undefined,
  filterTool: (tool) => tool.collection === 'reports',
});
```

返回的处置者还暴露了 `ready` 答应。 当宿主来临的时候 必须报告浏览器侧注册拒绝; 任何被拒绝的工具都会全部中止 之前那通电话的兄弟姐妹登记 `ready` 拒绝.

`filter` 接收遗留的收集元数据; `filterTool` 接收犬类 每工具定义。 在登记定义时只配置一个过滤器 对于其它过滤器类型, 关闭失败; 条形工具不携带完整 收集字段元数据,遗留的描述符不能满足词 过滤合同。 政策回调和获取器解析器获得孤立值 快照; 通过收藏/行动或工具等稳定值绘制关键主机侧图 名称,而不是定义对象身份.

不要将完整的遗产 和条理定义套装为相同的 藏书. 其重复的工具名称或收集/行动身份被拒绝 解剖注册。 优先选择完整生成的光圈集 涵盖范围,或只组成了脱节的后遗症和犬科子集.

### 宣布取消执行

铃声工具 `execute(args, options)` 接收主机的可选 `WebMcpToolExecutionOptions` 不变,包括 `options.signal`传出 向同步操作发出信号,并在发布结果前检查. 它代表了在登记之外取消这种援引 表示未注册工具。 现有的单参数调用和主机 删除选项仍然支持。 取消是合作的,不滚动 返回一个已经生效的操作.

使用相同的回调类型 `smrt-svelte`是因为 `useWebMcpTool`此转发 合同不为生成的REST或收集业务添加注销.

### 每个文档都锁定工具名称

生成的模型工具, 六个固定 `smrt_ui_*` 工具 UI 层登记册 在它自己的前缀下,宣布视图意图,以及手写铃声工具 独立生成名称, 全部结束于一个 `document.modelContext`。无 在宣布时间看到其他人,因为 `namespace` 一个UI `prefix` 为: 运行时间值 .

每个路径在浏览器之前通过一个文档全局锁定保留它的名称 看到它们,所以交叉路径的碰撞 被拒绝同步与一个 `WebMcpToolNameCollisionError` 指定工具名称和持有工具的所有人 (单位:千美元)`generated`, (中文(简体) ), `ui`, (中文(简体) ), `intent`,或 `bespoke`) (中文(简体) ). 浏览器用来拒绝 后来的登记和工具完全没有.

保留是一无所有, 处理注册 发布它的名字, 因此一个名称下的挂载/卸载/重挂循环继续工作. 用户界面 通过无依赖性登记其固定工具储备 `@happyvertical/smrt-web/webmcp-tool-names` 条目,通过相同的 `document` 写着 `modelContext` 从. 汇编已宣布视图意图的绑定 并登记在 `registerWebMcpBespokeTool` - 而不是通过 `registerViewIntent` ——通过 `owner: 'intent'` 因此,诊断名称 意图。 店主只是标签而已,却一文不值.

WebMCP 政策控制 网页广告的能力;它不是 授权边界。 执行仍然使用页面认证的 REST 运输,其认证、租赁、可写字的场地和敏感场地警卫必须 继续启用。 所有应用程序生成的工具结果都附加说明为不可信 内容,包括突变响应.

政策只缩小了生成的API元数据已经曝光的动作. 在收藏品外的遗物描述 `actions` 设定拒绝整个 注册,以及内在的 CRUD 效果不能被调用者数据重新标记.

移徙说明:以前依赖每个描述的登记 曝光现在必须通过 `effects: ['read', 'write', 'destructive']`优先选择 每个浏览器表面的更窄的允许列表 。 以前按键的集成 过滤器或解析器状态,根据定义,对象身份必须迁移到稳定 名称或收集/动作密钥。 如果既有遗产, 也有犬类定义阵列 可用, 在合并前选择一个完整的源或删除重叠 他们。 设定 `maxTools` (a) 明确显示需要硬性能力预算的表面; 溢出者拒绝完全登记,而不是截断登记.

## 发展

```bash
pnpm --filter @happyvertical/smrt-web test
pnpm --filter @happyvertical/smrt-web typecheck
pnpm --filter @happyvertical/smrt-web build
```

该建筑包括一个生成的 声明扫描 拒绝泄露的引擎 类型。 见 [`AGENTS.md`](https://npmcn.com/package/%40happyvertical/smrt-web/AGENTS.md) 用于缓存、发件箱、SSE、持久性和 发动机的边际变化.

## 常见问题

### @happyvertical/smrt-web 是什么？

SMRT 浏览器客户端数据运行时间: 键入收集厂将客户端-数据引擎包入生成的 REST 客户端

### 如何安装 @happyvertical/smrt-web？

在项目目录运行 npm install @happyvertical/smrt-web，或使用 pnpm add / yarn add / bun add。

### @happyvertical/smrt-web 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @happyvertical/smrt-web 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @happyvertical/smrt-web 可以商用吗？

@happyvertical/smrt-web 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @happyvertical/smrt-web 的下载量有多少？

根据 npm 官方下载统计，@happyvertical/smrt-web 在 2026/10/17 – 2026/11/15 这 30 天内被下载 20,193 次，日均约 673 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @happyvertical/smrt-web 还在维护吗？

最新版本 0\.62\.1 发布于 2026/11/17（今天）；至今共发布 323 个版本，其中过去 12 个月发布了 323 个；首次发布于 2026/07/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

