跳到主要内容

Bolt 框架

Bolt 框架

Bolt 是编写工作区所用的框架：一套由声明函数构成的编写接口、一个把工作区变成单个可移植制品的编译器，以及一个任何宿主都能运行的引擎。它不了解任何特定宿主——Colony 是一种宿主，你自己服务器上的 bolt start 是另一种。

软件包

  • @norbital-ai/bolt——十七个声明函数（workspace、secrets、team、app、group、kiosk、messages、model、relationship、customField、collection、integration、pipeline、policy、envoy、mcp 与 automation）及其签名所用的类型。它的 /client 入口即 $bolt，/test 是测试工具包，/engine 是宿主嵌入的引擎。
  • @norbital-ai/bolt-server——bolt start，即自托管服务器，实现了所有宿主端口。
  • @norbital-ai/ui——构建页面所用的视图、输入控件与布局。
  • @norbital-ai/std——值类库：十进制数、日期、日历、时区、表格、公式、PDF 文档等。
  • @norbital-ai/doctor——bolt check 运行的静态规则。

原则

  • **声明优先。**凡是声明能表达的都用声明表达，这样宿主就能在每条路径上强制执行它、为 Agent 呈现它、并据此路由实时查询。TypeScript 是逃生通道，它可能出现的每个位置都有类型且受限。
  • **声明即数据。**字段类型、输入、谓词、触发器、审批流程与限流都是带类型的对象字面量，代码体以独立语句附加。只有声明函数才是值。
  • **一切都指向集合。**模型是存储；它的集合是所有界面所指向的公开部分。
  • **唯一的写入路径。**页面、Agent、自动化、API 密钥、导入、集成数据源、审批决定与入站消息都对集合调用 act，并经过它的 transform。
  • **两类租户代码。**事务性代码——transform、查询与操作——没有外部 I/O，集成的纯代码体（数据源的 map、出站规则的 build）也没有。自动化与集成的持久代码体（数据源的 read、出站规则的 run）通过带类型的设施进行 I/O，每个副作用都会记入日志。
  • **没有任何静默行为。**没有默认读取上限，没有默认重试，不会因遗漏而删除，不会静默截断。每项配额都有带类型的错误。
  • **可选的提供方从不是必需的。**AI、地理编码、PDF 渲染与邮件传输都是宿主可能提供的设施；没有时，调用返回 Unavailable，构建也从不要求它存在。

拓扑

Browser                         Host (bolt-server, Colony, or the test kit)
───────                         ──────────────────────────────────────────────
$bolt, ui views   ── /q ──────►  session → actor → authority
  optimistic      ── /act ────►  query compiler: Where → SQL, masks, cursors
  paint, settled  ── /live ───►  write pipeline: allowlist → grant → transform
  by the outcome     (SSE)         → approval route → one statement
                  ── /files ──►  live engine: routes each commit to its views
                  ── /session ►  runs and queue → deadlines port
                                 agent loop, envoys, MCP client, integrations
                                 host ports: database, files, secrets, AI, …
                                        │                        │
                                        ▼                        ▼
                                 Postgres 18 per tenant    guest isolates:
                                 (bolt-server PGlite; Colony local Postgres / hosted Neon) tenant code only,
                                                           2 s CPU, 256 MiB

引擎运行在宿主端：普通读写、策略评估、导入、种子数据与实时增量都不消耗访客 CPU。租户代码——transform、查询、操作、自动化运行与集成代码体（数据源的 read 或 map、出站规则的 build 或 run）——每次调用都在一个全新的隔离环境中运行，最多 2 秒访客 CPU 与 256 MiB 内存，每次 I/O 响应的空闲期限为 20 秒，流式进度会刷新期限。Bolt 和 Colony 在本地及测试中使用 PGlite；托管 Colony 使用 PostgreSQL 控制库，每个租户独享一个 Neon 项目。

一个制品

bolt build 生成一个制品：清单（纯数据）、数据库结构、租户代码的访客包、客户端包、资源与技能，种子数据包放在其旁边。制品带有契约摘要，宿主实现一组契约摘要，因此保留的发布版本在宿主升级后仍可激活。

宿主端口

引擎接收一套端口配置：数据库、文件、deadlines、机密、AI、语音、文档转换、地理编码、网页读取、推送、集成链接、计量、租户与成员。bolt-server 为自托管实现了全部端口，Colony 为托管云实现了它们。Bolt 包中没有任何内容指名某个宿主。

内部原理

架构指南会更深入一层：