Rivet Actors 文档工程规范：docs Bundle 布局、CodeSnippet 类型安全嵌入与术语体系解析

Rivet Actors 文档工程规范docs Bundle 布局、CodeSnippet 类型安全嵌入与术语体系解析【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors本文档从 Rivet Actors 仓库的 docs/CLAUDE.md 出发系统解析这套文档包docs bundle的工程规范页面如何组织、Frontmatter 如何声明、导航如何配置、代码示例如何以类型安全的方式嵌入以及全站术语如何保持一致。无论你是要为本仓库贡献新的文档页面还是想理解 docs 目录与官网站点的发布链路都能从中获得一套可直接照做的完整流程。文档包Docs Bundle的定位与发布机制在深入具体规则之前先要理解一个关键前提本仓库docs/下的页面并不在本仓库内渲染。docs/CLAUDE.md开头即声明这些页面由独立的官网仓库发布官网仓库通过 symlink 把本目录链接进其内容集合。这意味着这里编写的每一页最终都会成为公开文档的一部分因此只有真正的页面real pages才能出现在content/下任何脚本、测试夹具、临时笔记如果被放进content/都会被当作文档页面发布出去页面在本仓库与官网站点之间通过同一套相对路径解析规范由此而来。这种仓库写文档、网站发文档的多仓库协作模式是所有后续规则布局、Frontmatter、路径、术语的出发点。docs 目录既是内容源也是被外部系统消费的产物目录规范必须保证两者对齐。目录布局content 之下只有真实页面docs/CLAUDE.md给出了标准的目录骨架docs/ sidebar.json navigation for the two tabs content/ docs/**.mdx - /{product}/docs/... tutorials/**.mdx - /{product}/tutorials/...对照本仓库的实际结构docs/content布局比骨架示例更丰富docs/content/docs/产品文档主体约 50 个.mdx页面覆盖 Quickstartbackend、react、next-js、rust、effect、cloudflare、supabase、Featuresstate、actions、events、queues、schedule、sqlite与 Conceptscrash-course、keys、input、lifecycle 等docs/content/learn/教程类内容如 a-radically-simpler-architecture.mdx、chat-room.mdxdocs/content/integrations/集成页面durable-streams、flue、vercel-eve、workflow-sdkdocs/content/use-cases/使用场景页docs/sidebar.json导航配置本仓库内唯一位于 docs/sidebar.json。核心原则只有一条content 目录与发布产出一一对应。规范的表述是 The website linksdocs/contentinto its content collection, so only real pages belong undercontent/。所以在贡献新内容时先判断它是不是一个真正面向读者的页面如果是脚本、夹具或内部笔记请放到 docs 之外的目录否则会被无声地发布出去。Frontmatter 规范title 与 description 双必填每一页都必须声明title和description两个 Frontmatter 字段它们承担双重职责两者都用于SEO搜索引擎与页面摘要当 sidebar 条目省略标题时侧边栏回退使用页面的title。docs/CLAUDE.md给出的标准示例--- title: In-Memory State description: Actors store state in memory for instant reads and writes. ---仓库中的真实页面完全遵循此格式。以 docs/content/docs/state.mdx 为例其 Frontmatter 为--- title: In-Memory State description: Actors store state in memory for instant reads and writes. State can be persisted automatically or kept ephemeral. skill: true ---这里还出现了一个可选的skill字段true/false在 crash-course.mdx 中同样出现。这类附加字段表明Frontmatter 不限于 title/description还可以承载站点级元数据但 title/description 是硬性要求。实际编写时请始终以这两个字段起步description 应写成一句完整、可独立检索的句子说明页面要解决什么问题。sidebar.json导航即配置导航完全由 docs/sidebar.json 驱动。docs/CLAUDE.md给出的最小示例{ docs: [ { title: General, pages: [ { title: Introduction, href: /actors/docs, icon: faSquareInfo } ]} ], tutorials: [] }关键规则有三条href必须是完整的站点路径包含产品段product segment。例如/actors/docs/quickstart/backend、/actors/docs/state而不是相对路径或文件名往content/添加页面并不会自动加入导航必须同时在这里登记。只写页面、不同步 sidebar页面就会存在但不可达Self-Host 标签页不在此文件中由网站侧生成因此不需要也不应该在这里维护。仓库中的实际 sidebar.json 比示例大得多结构上包含三个顶层区段docs按 General / Quickstart / Features / Concepts / Clients / Reference 分组、learn、integrations。每个条目支持iconFont Awesomeexport 名称如faSquareInfo、faNodeJs、faRust、collapsible可折叠分组、pages子页面、badge如 Rust、Effect.ts 的 Beta 徽标等字段。这印证了docs/CLAUDE.md中图标以 Font Awesome export names 传输而非对象的说法——导航数据是纯 JSON仓库侧无需依赖网站的图标包。实操要点新增一页文档时遵循页面 导航双提交调整分组或排序时直接编辑 sidebar.json 中对应条目的顺序即可。CodeSnippet 代码嵌入让示例永不腐烂这是整套规范中最具工程价值的机制docs/CLAUDE.md用了一整节Code来约束它。核心思想一句话概括文档中的 TypeScript 示例必须来自真实源码文件并且必须通过编译否则网站构建失败。为什么禁止内联 TypeScript规范原文是 Never inline a fenced TypeScript block。原因是类型检查真实示例放在examples/下通过CodeSnippet嵌入它们会参与tsc --noEmit编译一个无法编译的 snippet 就会让网站构建失败。这从根本上杜绝了文档代码腐烂rot——代码一旦变更构建即报警而不是等到读者踩坑。仓库证据充分文档页中大量使用CodeSnippet例如 crash-course.mdx 单页出现 26 处state.mdx、actions.mdx 也各有十余处。而示例源码集中存放在 examples/docs 下按主题分目录actors-state/、actors-actions/、actors-crash-course/、actors-request-handler/、actors-sqlite/等与文档页面一一对应。示例工程本身是可编译的独立包examples/docs/package.json 名为docs-snippets提供check-types脚本tsc --noEmit依赖rivetkitworkspace:*、rivetkit/react、rivetkit/engine-api-full、effect、hono、pg、drizzle-orm等——它涵盖了文档示例可能用到的全部 SDK 与第三方库从依赖层面保证类型检查真实有效。路径规则相对仓库根CodeSnippet fileexamples/docs/actors-state/durable-basic.ts /Snippet 路径相对本仓库根目录这样同一个路径在本仓库和官网站点通过 symlink 消费解析结果一致。这也是为什么示例统一放在仓库根下的examples/docs/而不是散落在docs/content内部。region嵌入文件的局部片段当文件过长、只想嵌入其中一段时用regionname并在源码中用注释界定CodeSnippet fileexamples/docs/actors-request-handler/http-api-fetch.ts regionfetch /对应源码 examples/docs/actors-request-handler/http-api-fetch.ts 中的界定符// docs:start fetch // Replace with your actor ID and token const actorId your-actor-id; // ... // docs:end fetch export {};另一个实例是 examples/docs/actors-inspector-tabs/inspector-tab-types.ts用// docs:start types/// docs:end types围住一组类型导入再被 inspector-tabs.mdx 以CodeSnippet fileexamples/docs/actors-inspector-tabs/inspector-tab-types.ts regiontypes /引用。注意源码文件在片段之外通常还需要export {}或类型导出保持自身模块完整——snippet 是从可编译文件中截取而不是为文档临时拼一段。nocheck 的适用边界规范允许nocheck但仅限当前分支尚不存在的 API。例如 state.mdx 中的外部数据库示例import { actor } from rivetkit; import { Pool } from pg; // One shared pool for the whole process, created once and reused by every actor const pool new Pool({ connectionString: process.env.DATABASE_URL }); // ...这表示示例引用了真实 API但因环境如未安装pg的 CI 或 API 尚未落地跳过类型校验。反过来说能编译的代码就不该加nocheck加了反而掩盖真实类型错误。CodeGroup 与多文件 workspaceCodeGroup用于并列展示同一主题的多个变体如 state.mdx 中 Durable 类型的三个文件CodeGroup CodeSnippet fileexamples/docs/actors-state/durable-basic.ts titleBasic / CodeSnippet fileexamples/docs/actors-state/durable-dynamic-init.ts titleDynamic init / CodeSnippet fileexamples/docs/actors-state/durable-with-input.ts titleWith input / /CodeGroup跨多个文件的完整示例则用CodeGroup workspace每个文件一个CodeSnippet。仓库中的实际用例见 websocket-handler.mdx两处、sqlite-drizzle.mdx 与 clients/swiftui.mdx。可内联的代码类型禁止内联的规则只针对 TypeScript。Shell 命令、YAML、Dockerfile 和终端输出可以放心使用普通 fenced block。例如 request-handler.mdx 中配合 region 示例展示的 curl 命令curl -X POST https://api.rivet.dev/gateway/{actorId}/request/increment \ -H x-rivet-token: {token}以及Tabs/Tab切换组件见 crash-course.mdx 的 State、Vars、Connections 示例都属于允许内联的展示结构。此外每个 TypeScript snippet必须包含其 imports 并定义所有引用到的符号保证片段脱离文档上下文也能独立编译。内容边界什么不该写进这里docs/CLAUDE.md用 What does not belong here 一节明确划定了三类禁区避免文档包与网站仓库职责混淆营销页面Marketing pages归网站仓库本仓库只承载技术文档部署与自托管指南Deploy and self-hosting guides在网站仓库写一次跨产品模板化复用不写每产品的副本。这与 sidebar.json 中Self-Host 标签由网站生成的机制互相印证网站组件Website components不允许通过相对路径或别名从网站仓库 import页面必须只依赖站点已提供的组件如CodeSnippet、CodeGroup、Tabs、Accordion这类声明式组件。这条边界保证了 docs 目录的纯净它是内容源不是渲染环境。编写页面时只使用网站约定的声明式组件与规范允许的内联代码类型页面才能在官网正确渲染。术语体系一份贯穿全站的词典docs/CLAUDE.md的 Terminology 一节定义了强制性的术语使用规则适用于所有对外发布内容。它们不是建议而是硬约束直接影响检索与 Agent 理解的一致性场景必须使用禁止使用负责路由、调度、持久化的服务control planeengine、server、orchestrator运行用户代码带 Rivet SDK的进程workerenvoy、runner、node、compute、data plane部署级名词不使用 agentagentOS 与 Actors 存在不可恢复的语义冲突agent代理基础设施不出现 envoyEnvoy Proxy 是 CNCF 顶级项目内部代码另有命名envoy托管服务名称Rivet CloudRivet Compute 已退役Rivet Compute产品拼写agentOSAgentOS专有名词Rivet Actor大写通用 actor 小写大小写混用域名rivet.devrivet.gg这套术语的工程价值在于文档、SDK、官网与 Agent 消费方共享同一套命名避免了一个概念多个名字造成的歧义。例如把运行用户代码的进程统一定义为 worker配合examples/docs与docs/content中一致的页面命名actions、events、queues、sqlite 等让文档体系在机器可读层面也保持稳定。写作规范句子、标点与不记录增量写作层面的两条硬规则注释与正文一律使用完整句子绝不使用破折号em dash需要分隔时用句号。这既保证了可读性也避免了部分渲染管线对破折号的解析问题不记录增量变化Do not document deltas。一个从未见过旧版本的读者从这个功能曾经叫 X后来改名为 Y这类表述中得不到任何价值。文档应只描述当前状态的最终形态。这两条与术语不回溯历史如 Rivet Compute 已退役直接写 Rivet Cloud共同构成了面向当前版本的写作观。本地预览与发布链路docs/CLAUDE.md提供了完整的本地预览流程将网站仓库克隆到本仓库旁边网站会自动检测兄弟目录并实时提供本目录的页面git clone 网站仓库地址 cd rivet-website pnpm install pnpm dev需要排查或切换产品文档来源时有两个实用操作pnpm assemble会打印每个产品解析到的 checkout用于确认本仓库的 docs 是否被正确链接指向其他 checkout 时重新指向 symlink 即可。该 symlink 是 gitignored 的assemble会保留已存在的 symlinkln -sfn /path/to/this/repo/docs/content src/content/docs/product整体发布链路可以归纳为本仓库编写docs/content页面 examples/docs示例 sidebar.json导航→ 网站仓库 symlink 消费 → assemble 校验与链接 → 类型检查 → 站点构建发布。任何一环如 snippet 编译失败都会在构建期暴露问题这正是该工程规范追求早失败、可追溯的体现。总结Rivet Actors 的 docs bundle 规范用一套清晰的工程手段解决了文档工程的两个根本问题示例永不腐烂通过examples/docs源码 类型检查 CodeSnippet强制嵌入与内容永不漂移通过术语词典、内容边界、Frontmatter 与 sidebar 双登记机制。对于想要为本仓库贡献文档的开发者最低限度的入门清单是把页面放进docs/content/的正确子目录、写全 title 与 description、用CodeSnippet引用 examples/docs 中的真实示例、同步更新 docs/sidebar.json并严格遵循术语与写作规范。【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考