rivetkit

Name: rivetkit
Author: rivet-dev

github.com/rivet-dev开发447.7k 次安装1 天前更新

代码仓库

关于 rivetkit

这项技能用于构建和运维 RivetKit Actor，即面向 AI Agent、实时应用和工作流的长时运行有状态进程。内容涵盖项目设置、持久化选择、部署和通过 inspector API 调试。

主要功能

01设置并运行 RivetKit Actor
02选择持久化状态、KV 或 SQLite
03检查 Actor 状态、连接和工作流
04配置部署与版本管理
05处理错误与 TypeScript 类型问题

适用场景

01构建有状态 AI Agent 后端
02实现实时协作应用
03编排持久化后台工作流
04调试 Actor 状态和工作流历史

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/rivet-dev/skills --skill rivetkit

安装后在 Claude Code 中输入/rivetkit确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

index.json

openapi.json

reference/actors/

access-control.md

actions.md

actor-runtime-socket.md

appearance.md

authentication.md

communicating-between-actors.md

connections.md

debugging.md

design-patterns.md

destroy.md

errors.md

events.md

fetch-and-websocket-handler.md

helper-types.md

http-api.md

input.md

inspector-tabs.md

keys.md

kv.md

lifecycle.md

limits.md

metadata.md

queues.md

reference/actors/quickstart/

backend.md

cloudflare.md

effect.md

next-js.md

react.md

详细介绍

Rivet Actors

在 Rivet 的 Actor 运行时上构建高性能、长生命周期的内存进程。当 HTTP 端点、数据库或队列无法满足 AI Agent、实时协作、工作流编排或地理分布式数据的需求时，请使用此技能。

遇到问题时的处理方式

如果某些功能未按预期运行，或者您遇到了难题，请提示用户加入 Rivet Discord，或在 Rivet GitHub 上提交问题，以报告问题并获得帮助。

向用户提供预先生成的报告，内容包括：

症状
- 问题发生在本地开发、已部署环境，还是两者都有
- 您看到的错误
- 与此相关的源代码
您尝试过的解决方法
环境
- RivetKit 版本
- 运行时（Node、Bun 等），包括版本
- 如适用，所用的提供商（例如 Vercel、Railway 等）
- 如适用，所用的 HTTP 路由器（例如 Hono、Express、Elysia）

调试 Actors

使用检查器 HTTP API 检查正在运行的 Actors。可通过网关访问这些端点，路径为 /gateway/{actor_id}/inspector/*。主要端点：

GET /inspector/summary - Actor 的完整快照（状态、连接、RPC、队列）
GET /inspector/state / PATCH /inspector/state - 读取/写入 Actor 状态
GET /inspector/connections - 活跃连接
GET /inspector/rpcs - 可用操作
POST /inspector/action/{name} - 使用 {"args": [...]} 执行操作
POST /inspector/database/execute - 使用 {"sql": "...", "args": [...]} 或 {"sql": "...", "properties": {...}} 执行 SQL，可用于读取或修改数据
GET /inspector/queue?limit=50 - 队列状态
GET /inspector/traces?startMs=0&endMs=...&limit=1000 - 跟踪跨度（OTLP JSON）
GET /inspector/workflow-history - 以 JSON 格式返回工作流历史记录和状态（nameRegistry、entries、entryMetadata）
POST /inspector/workflow/replay - 从指定步骤或开头重放工作流；如果工作流仍在运行，则返回 409 actor/workflow_in_flight
GET /inspector/database/schema - 通过 c.db 暴露的 SQLite 表和视图
GET /inspector/database/rows?table=...&limit=100&offset=0 - 分页读取表或视图中的 SQLite 行

在本地开发环境中，无需身份验证令牌。在生产环境中，请传入 Authorization: Bearer <inspector-token>；检查器令牌是首次启动时自动生成并保存在 Actor 内部 KV 的键 0x03 中的 Actor 专属令牌。Rivet 控制面板会自动获取此令牌；如需直接访问 API，请通过管理 KV 端点获取。详情请参阅调试文档。

引用来源

提供 Rivet 文档中的信息时，请引用规范 URL，以便用户了解更多信息。每个参考文件都会在标头元数据中包含其规范 URL。

引用方式：

为关键概念添加行内链接：“使用Actor 键唯一标识实例。”
对于复杂主题的说明，请在后面添加“了解更多”链接

查找规范 URL：

下方的参考映射链接到参考文件。每个文件的标头都包含：

> Canonical URL: https://rivet.dev/docs/actors/actions

引用时请使用该规范 URL，而不是参考文件路径。

示例：

Actions → https://rivet.dev/docs/actors/actions
React 客户端 → https://rivet.dev/docs/clients/react
在 Kubernetes 上自托管 → https://rivet.dev/docs/self-hosting/kubernetes

版本检查

开始任何工作之前，请检查用户的项目是否使用最新版本的 RivetKit（最新版本：2.3.7）。查看用户 package.json 中的 rivetkit 版本（检查 dependencies 和 devDependencies）。如果安装的版本早于 2.3.7，请告知用户并建议升级：

npm install [email protected]

如果用户还使用 @rivetkit/react、@rivetkit/next-js 或其他 @rivetkit/* 客户端程序包，也建议升级这些程序包。过时版本可能存在已知错误或缺少某些功能，从而导致问题。

起步

安装 RivetKit（最新版本：2.3.7）
```
npm install [email protected]
```
使用 setup({ use: { /* actors */ } }) 定义注册表。
调用 registry.start() 启动服务。要集成自定义 HTTP 服务，请搭配 Hono 之类的路由器使用 registry.handler()。对于无服务部署，请使用 registry.serve()。对于仅运行器模式，请使用 registry.startEnvoy()。
部署前，确认 /api/rivet/metadata 返回 200。
配置 Rivet Cloud 或可自托管引擎
- 生产构建必须配置版本管理。本地开发无需此配置。请参阅版本与升级。
集成客户端（请参阅下方的客户端指南，了解 JavaScript、React 或 Swift）
询问用户是否要部署。如果要部署，请转到“部署 Rivet 后端”。

如需了解更多信息，请阅读与用户项目相关的快速入门指南。

项目设置

.gitignore

每个 RivetKit 项目都应包含 .gitignore。至少应包含：

node_modules/
dist/
.env

.dockerignore

每个包含 Dockerfile 的项目都应有 .dockerignore，以减小镜像体积并避免泄露机密：

node_modules/
dist/
.env
.git/

Dockerfile

将此 Dockerfile 用作部署 RivetKit 项目的基础配置。RIVET_RUNNER_VERSION 构建参数仅在可自托管或使用自定义运行器时需要（Rivet Compute 无需此参数）。它能让 Rivet 跟踪正在运行的 Actor 版本，并在部署时排空旧 Actor。详情请参阅 https://rivet.dev/docs/actors/versions。

FROM node:24-alpine

ARG RIVET_RUNNER_VERSION
ENV RIVET_RUNNER_VERSION=$RIVET_RUNNER_VERSION

WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY . .
RUN npm run build --if-present

CMD ["node", "dist/index.js"]

使用以下命令构建：

docker build --build-arg RIVET_RUNNER_VERSION=$(date +%s) .

根据项目的入口点调整 CMD。如果项目使用不同的输出目录或启动命令，请相应更新。

错误处理策略

默认优先采用快速失败行为。
除非确实需要执行恢复操作、划定清理边界或补充可执行的上下文，否则避免使用 try/catch。
切勿吞掉错误。如果添加 catch，必须明确处理错误，至少要记录错误日志。
无法恢复时，记录上下文并重新抛出错误。

State 与 Vars：持久化规则

c.vars 是临时的。 c.vars 中的数据会在每次重启、崩溃、升级或休眠／唤醒周期中丢失。c.vars 仅用于存储不可序列化的对象（例如物理引擎、WebSocket 引用、事件发射器、缓存），或真正临时的运行时数据（例如断开连接后便无关紧要的当前输入方向）。

持久化存储选项。 任何需要在重启后保留的数据都应存入以下选项之一，而不是 c.vars：

c.state — 用于小型、有界数据集的 CBOR 可序列化数据。适合存储配置、计数器、小型玩家列表、阶段标记等。大小应保持在 128 KB 以下。不要在此存储无界或持续增长的数据（例如聊天记录、事件历史、无限增长的生成实体列表）。每个持久化周期都会将状态作为单个数据块读取／写入。
c.kv — 用于无界数据的键值存储。c.state 底层使用的就是它。支持二进制值。适合存储较大或大小可变的数据，例如用户物品栏、世界区块、文件数据块，或任何可能随时间增长的集合。键的作用域限定为 Actor 实例。
c.db — 用于结构化或复杂数据的 SQLite 数据库。当你需要查询、索引、联接、聚合或关系建模时使用。适合存储排行榜、对局历史、玩家池，或任何适合用 SQL 处理的数据。

常见错误： 将有意义的游戏／应用数据存入 c.vars，而不是进行持久化。例如，如果用户可以在物理模拟中生成对象，那么生成定义（位置、大小、类型）必须持久化到 c.state（如果无界，则存入 c.kv），即使物理引擎等不可序列化的运行时对象存放在 c.vars 中也是如此。重启后，run() 应根据持久化的数据重新创建运行时对象。

部署 Rivet 后端

除非另有说明，否则假设用户要部署到 Rivet Cloud。如果用户要自行托管，请阅读下方的自托管指南。

确认 Rivet Actors 在本地开发环境中正常运行
提示用户选择要部署到的提供商（提供商列表请参阅 Connect，例如 Vercel、Railway 等）
按照所选提供商的部署指南操作。需要手动干预时，请指导用户完成相应步骤。

API 参考

RivetKit OpenAPI 规范位于技能目录中的 openapi.json 文件内。此文件记录了用于管理 Actor 的所有 HTTP 端点。

其他说明

Rivet 的域名是 rivet.dev，而不是 rivet.gg

TypeScript 注意事项：Actor 客户端类型推断

在多文件 TypeScript 项目中，如果两个 Actor 都使用 c.client<typeof registry>()，双向 Actor 调用可能会造成循环类型依赖。
常见表现包括：c.state 变为 unknown，Actor 方法变为可能未定义，或首次跨 Actor 调用后出现 TS2322／TS2722 错误。
如果某个操作返回另一个 Actor 调用的结果，最好为该操作显式标注返回类型，而不要依赖通过 c.client<typeof registry>() 进行推断。
如果显式返回类型仍不够，请使用更精简的客户端类型或注册表类型，仅包含该操作所需的 Actor。
作为最后手段，可将 unknown 作为注册表类型传入，并明确说明这会放弃该调用位置的类型安全。

功能

长时间运行的有状态计算：每个计算单元都像一台微型服务器，可以在请求之间记住数据——无需从数据库重新获取数据，也不必担心超时。就像 AWS Lambda，但有内存且不会超时。
极速读写：状态存储在执行计算的同一台机器上，因此读写速度极快。无需往返数据库，也不会出现延迟峰值。状态会持久化到 Rivet，供长期存储，因此即使服务器重启也能保留。
实时：通过 WebSocket 实时更新状态并广播变更。无需外部发布/订阅系统，也无需轮询——只需使用内置的低延迟事件。
无限扩展：自动扩展，可从零扩展到数百万个并发 Actor。按使用量付费，即时扩展且没有冷启动。
容错：内置错误处理和恢复机制。Actor 在发生故障时会自动重启，同时保持状态完整性并继续运行。

何时使用 Rivet Actors

AI Agent 与沙盒：多步骤工具链、对话记忆、沙盒编排。
多人或协作应用：CRDT 文档、共享光标、实时仪表板、聊天。
工作流自动化：后台任务、cron、速率限制器、持久队列、背压控制。
数据密集型后端：地理分布式或按租户划分的数据库、内存缓存、分片 SQL。
网络工作负载：WebSocket 服务、自定义协议、本地优先同步、边缘扇出。

最小项目

后端

index.ts

客户端文档

使用与你的应用匹配的客户端 SDK：

Actor 快速参考

内存状态

重启、崩溃和部署后仍可保留的持久数据。状态会持久化到 Rivet Cloud 或 Rivet 可自托管版本，因此即使当前进程崩溃或退出，重启后也能保留。

静态初始状态

动态初始状态

文档

键

键用于唯一标识 Actor 实例。使用复合键（数组）进行分层寻址：

如果 userId 包含用户数据，不要使用字符串插值（例如 "org:${userId}"）来构建键。请改用数组，以防止键注入攻击。

文档

输入

创建 Actor 时传递初始化数据。输入仅在 createState 和 onCreate 中可用，因此如果之后还需要使用，请将其存储在状态中。

文档

临时变量

重启后不会保留的临时数据。用于不可序列化的对象（事件发射器、连接等）。

静态初始变量

动态初始变量

文档

操作

操作是客户端和其他 Actor 与某个 Actor 通信的主要方式。

操作可以嵌套，以归组相关行为。例如，handle.users.add("Ada") 会调用低级操作名称 users.add。

文档

事件与广播

事件支持 Actor 与已连接客户端之间的实时通信。

文档

连接

通过 c.conn 访问当前连接，或通过 c.conns 访问所有已连接客户端。使用 c.conn.id 或 c.conn.state 安全地识别调用操作的客户端。c.conn 仅在通过已连接客户端调用操作时可用；无状态的 Actor 句柄调用不会携带连接，因此需要对此进行防护。连接状态通过 connState 或 createConnState 初始化，后者会接收客户端连接时传递的参数。

静态连接初始状态

动态连接初始状态

文档

队列

使用队列在 run 循环中按顺序处理持久消息。

文档

工作流

当你的 run 逻辑需要持久化、可重放的多步执行时，请使用工作流。

文档

Actor 间通信

Actor 可以使用 c.client() 调用其他 Actor。

文档

定时任务与 Cron

在延迟一段时间后或指定时间运行一次性操作。使用命名的 cron 任务安排日历计划和固定间隔任务。这两种任务都会在休眠、重启、升级和崩溃后持久保留。

文档

销毁 Actor

使用 c.destroy() 永久删除 Actor 及其状态。

文档

生命周期钩子

Actor 支持用于初始化、后台处理、连接、网络和状态变更的钩子。使用 run 执行长期运行的后台循环，并使用 c.aborted 或 c.abortSignal 实现平稳关闭。

文档

上下文类型

在 Actor 定义之外编写辅助函数时，使用 *ContextOf<typeof myActor> 提取正确的上下文类型。ActionContextOf、CreateContextOf、ConnContextOf 和 ConnInitContextOf 等辅助类型由 "rivetkit" 导出。不要手动定义自己的上下文接口，始终从 Actor 定义派生。

文档

错误

使用 UserError 抛出可安全返回给客户端的错误。传入 metadata 可包含结构化数据。其他错误会出于安全考虑转换为通用的“内部错误”。

Actor

客户端

文档

底层 HTTP 与 WebSocket 处理器

对于自定义协议或需要直接访问 HTTP Request/Response 或 WebSocket 连接的库集成，请使用 onRequest 和 onWebSocket。

HTTP 处理器文档 · WebSocket 处理器文档

图标与名称

通过显示名称和图标自定义 Actor 在 UI 中的显示方式。建议始终为 Actor 提供名称和图标，以便在控制面板中更容易区分。

import { actor } from "rivetkit";

const chatRoom = actor({
	options: {
		name: "Chat Room",
		icon: "💬", // or FontAwesome: "comments", "chart-line", etc.
	},
	// ...
});

文档

客户端文档

在此查阅完整的客户端指南：

常见模式

Actor 通过隔离状态和消息传递实现自然扩展。请使用以下模式构建应用：

文档

每个实体对应一个 Actor

为每个用户、文档或房间创建一个 Actor。使用复合键限定实体范围：

协调器与数据 Actor

数据 Actor 负责核心逻辑（聊天室、游戏会话、用户数据）。协调器 Actor 跟踪并管理数据 Actor 集合，可将其视为索引。

运行循环

使用 run 循环在 Actor 内执行持续的后台工作。按顺序处理队列消息，定期运行逻辑，流式传输 AI 响应，或协调长期运行的任务。

工作流循环

对于需要初始化资源、循环处理命令并最终清理的长期持久化工作流，请使用此模式。

文档

操作与队列

操作不具备持久性。将其用于实时读取、临时数据，以及玩家输入等低延迟通信。
队列具备持久性。使用队列通过运行循环串行处理变更，避免与 SQLite 及其他本地状态发生竞态条件。调用方仍可等待队列任务的响应。

身份验证、安全性与 CORS

在 onBeforeConnect 或 createConnState 中验证凭据，并抛出错误以拒绝未授权的连接。
在操作中使用 c.conn.state 安全地识别用户，而不是信任操作参数。
对于跨域访问，请在 onBeforeConnect 中验证请求来源。

身份验证文档 · CORS 文档

版本与升级

部署新代码时，请设置版本号，以便 Rivet 将新 Actor 路由到最新的运行器，并可选择排空旧运行器。版本号可以使用构建时间戳、git 提交数或 CI 构建编号。在部署到生产环境之前，配置版本控制非常重要。如果没有版本控制，Actor 可能会因运行在较旧的运行器版本上而回退，并且现有 Actor 永远不会被强制迁移到新的运行器。它们会继续在旧运行器上无限期运行，直到退出。

文档