Bolt 框架

本页是后续内容的心智模型——Bolt 是什么、它拥有什么，以及 Colony 从哪里开始。 @norbital-ai/bolt 是租户工作区的文件系统编译器、编写 SDK、运行时、客户端与 Vite 插件。你无需手工拼接——只需在每个已识别的角色目录下放置一个声明，即 src/ ，其余一切都由 Bolt 派生。Colony 是宿主，而非 Bolt 的依赖。

编写 → 构建 → 运行

┌────────── Author ───────────┐   ┌────────── Build ───────────┐   ┌─────────── Run ────────────┐
│ src/                         │   │ bolt sync                  │   │ Colony hosts the           │
│ collections/  apps/          │──►│ validates every role       │──►│ immutable artifact         │
│ automations/ functions/      │──►│ generates $types           │──►│ provisions the tenant      │
│ access/ capabilities/        │   │ builds the client          │   │ database                   │
│ envoys/ datatypes/           │   │ emits .norbital/           │   │ apps load and run          │
│ +agents.md  +seed.ts         │   │ (one artifact)             │   └────────────────────────────┘
│ (one declaration per role)   │   └────────────────────────────┘
└──────────────────────────────┘

编写 —— 每个已识别的 src/** 文件系统角色一个声明。没有注册文件，没有手工装配。
构建 —— bolt sync 运行 Bolt 插件：先同步文件系统（生成类型、注册表与编译后的客户端），再把可移植产物与迁移输出到 .norbital/ .
运行 —— Colony 托管不可变产物并配置租户数据库。Bolt’s 同步引擎让每个浏览器客户端对数据库保持实时。

钩子、自动化、流水线、远程函数与 Agent 工具都是 Effect 原生 的：处理器是 Effect.gen(function* () { … }) 函数，每个 api.db.* / api.infer / api.readFileAsset 调用都是你 yield* 的 Effect。运行时确实会执行它们——before/after 钩子包裹 create、update、delete；自动化按计划或集合变更触发，并接收触发行作为 scope.incoming_record ；导入/导出流水线与远程函数处理请求。校验留在 ~standard ，因此编写中没有 zod。

handler: ({ input, api }) =>
	Effect.gen(function* () {
		const site = yield* api.db.query.sites.findFirst({
			where: { id: { eq: input.site_id } }
		});
		if (site == null) refuse('Referenced site does not exist.');
		return input;
	})

使用 Effect Schema 的自定义类型

自定义类型的 schema 是 Effect Schema（ Schema.Struct 、 Schema.Union 、 Schema.Literals 、 Schema.NullOr ），由 effect 组合而成，并通过 ~standard 经 Schema.toStandardSchemaV1 校验。编写中没有 zod。

bolt CLI

bolt 二进制在任意 checkout 中驱动工作区的生命周期：

bolt sync —— 重新生成工作区类型、构建客户端并输出可移植产物
bolt migrate —— 对照迁移谱系比较已编写模型并写下下一条迁移
bolt audit —— 对工作区运行静态代码质量审计

Bolt 拥有什么

文件系统编译器 —— 角色发现、校验、生成模块与本地类型
Vite 插件 —— Svelte、Tailwind、服务端/客户端构建、迁移与 DDL
集合运行时 —— SQL 编译、策略评估、审批、钩子与远程函数
同步引擎 —— 实时查询、乐观写入，以及按策略过滤的本地副本
应用外壳 —— 生成的应用加载器与带类型的客户端访问
设施端口 —— 数据库、文件、AI、消息、任务与宿主工具

子系统一览

工作区能做的一切都经由一小套子系统，每个子系统都有独立文档页：

客户端 —— 应用用来读、写与调用的带类型表面
同步引擎 —— 实时查询、乐观写入与本地副本
持久自动化 —— 宿主接纳的定时、集合事件与 Agent 循环函数——而非基础设施队列设施
UI 库 —— 应用组合所用的布局原语与集合表面
设施 —— 宿主如何提供数据库、存储、模型与队列

一个生成根目录

Bolt 把诊断、构建输出、生成模块、角色类型、迁移历史与一个生成的 TypeScript 配置写入 .norbital/ 。只有 .norbital/migrations/ 会提交。构建输出位于 .norbital/dist/ ：编译后的浏览器客户端。可移植的服务端产物——编译后的运行时、租户应用、资源与迁移——位于 .norbital/artifact/bundle.mjs，是像 Colony 这样的宿主加载的文件。

系统集合

运行时拥有的集合（user、session、account、verification、auth_config、team、approval_request、requestor）在构建时被合并进清单；你永远不必重新定义它们。身份是 user、session、account、verification 与 auth_config 行，每个主体属于恰好一个 team 行。策略同样不是数据行——它是工作区源码中的一个 src/access/policies/+<name>.ts 模块，与它所授权的集合一起被编译进清单。租户作者在其上追加领域集合。参见系统集合。

数据同步

Bolt 内置原生同步引擎：租户应用通过针对按策略过滤的本地副本的实时查询读取，并通过 client.db.<collection>.mutate(values) 乐观写入——应用代码从不调用 invalidate 、 refetch 或 revalidate 。作者使用的读写 API 记录在实时数据。

策略

访问基于策略：可复用的授权由团队、envoy 与自动化持有，在 bolt 运行时的每次读取与变更上评估。审批门采用先写后锁。参见策略。

设施

工作区代码只能通过宿主提供的绑定访问 Postgres、存储、AI 与密钥——绝无直接凭据。Bolt 暴露 ai 设施端口；宿主在运行时绑定具体提供者。

宿主拥有什么

宿主提供具体设施与运维隔离：

租户数据库连接池、对象存储、模型 API 与凭据存储
不可变产物存储与 bundle 服务
DDL 校验、迁移应用、登录验证码投递与计费

工作区源码只声明需求，绝不包含密钥值。客户端代码无法访问私有运行时设施。

仅 Colony：工作区工作室

工作区工作室 （浏览器编辑与发布产物发布）仅由 Colony 提供。 Agent 循环、/agent 界面与对话记录随 @norbital-ai/bolt 提供；Colony 托管推理、持久编排与计量。参见 Colony 。

编写契约

Bolt 为运维 UI 圈定了一小套公开编写表面。这些指南描述租户作者依赖的契约：

UI 组件 —— schema 派生的表单、自定义类型与 +representation.svelte 覆盖
导航状态 —— ?stack= 中的记录详情栈与侧边抽屉外壳
布局 —— 布局原语与应用主体契约
实时数据 —— 实时查询、乐观写入，无需手动缓存失效

工作区边界

没有 SvelteKit 依赖、路由、 +page 文件或 svelte.config.*
没有编写式装配注册表或生成声明
没有直接凭据、宿主内部或自定义打包脚本
不重复引入基础 CSS 或 Tailwind 集成