文件系统

租户工作区是一个普通的 Vite 项目。编写者在 src/ 下每个被识别的文件系统角色中放置一份声明；Bolt 从中推导出全部装配与生成类型。本页是地图——编写章节的其余部分详述每个角色。

规范布局

src/
├── +agents.md                     # required — the workspace prompt
├── +env.ts                        # optional — declare env vars; private keys are server-only
├── access/
│   ├── +teams.ts                  # which policies each named team holds
│   ├── +anonymous_limits.ts       # pre-sign-in address limits only
│   └── policies/+<name>.ts        # grants, approvals, capabilities, and limits
├── capabilities/
│   ├── tools/+<name>.ts           # optional workspace tool
│   ├── mcp/+<name>.ts             # optional remote MCP server
│   └── skills/<name>/+skill.md    # optional workspace Agent Skill
├── collections/
│   ├── +relationship.ts
│   └── <lower_snake_case>/
│       ├── +model.ts
│       ├── +hooks.ts              # optional
│       ├── +pipelines.ts          # optional
│       ├── +integrations.ts       # optional
│       └── +representation.svelte # optional create/display/edit override
├── datatypes/<name>/
│   ├── +definition.ts
│   └── +renderer.svelte           # required
├── apps/
│   ├── +<app>.svelte
│   └── <group>/
│       ├── +group.ts
│       └── +<app>.svelte
├── automations/+<name>.ts
├── envoys/+<name>.ts
├── functions/+<name>.ts
├── i18n/
│   ├── messages.en.json           # required — English copy
│   └── messages.zh.json           # required — Chinese copy, exact same keys
└── lib/**                         # optional, free-form helper code — no role, no + prefix

必需角色是 src/collections/+relationship.ts 、至少一个集合 +model.ts ，以及至少一个应用 src/apps/**/+<lower_snake_case>.svelte 。应用、自动化、函数与 Envoy 的 ID 来自其文件名。放错位置、重复、嵌套与未知的角色文件都会导致结构化编译失败。src/+agents.md 中的工作区提示与 src/i18n/ 中的双语目录都是必需的。

生成状态

.norbital/
├── diagnosis/     # ignored
├── dist/          # ignored
├── generated/     # ignored
├── migrations/    # committed
├── types/         # ignored
└── tsconfig.json  # ignored

编写的根 tsconfig.json 继承 .norbital/tsconfig.json 。Bolt 拥有这份唯一的生成配置与所有编译器路径；它不使用 baseUrl 。只有 .norbital/migrations/ 会被提交。

命令

bolt sync
bolt migrate

bolt sync 运行文件系统编译器：校验角色、生成注册表模块、本地 $types 与生成的 TypeScript 配置。
bolt migrate 会对比已编写模型与迁移历史，并把下一条迁移写入 .norbital/migrations/ .

编写边界

应用从 $bolt/client .
服务器角色使用其相邻的生成 ./$types.js .
不要手工编写注册表、装配模块、生成声明或打包脚本。
不要添加 SvelteKit 路由、 svelte.config.* 、 $app/* 或 #lib .

一览所有角色

每个角色都是在唯一位置的一个文件，默认导出一份声明，并以文件名作为其身份。未知、重复、放错位置或遗留的角色文件是编译错误——不是被静默忽略的文件。

角色	位置	导出	文档
集合模型	`collections/<name>/+model.ts`	`defineModel`	集合
关联注册表	`collections/+relationship.ts`	关联构建器	集合
钩子	`collections/<name>/+hooks.ts`	钩子声明	钩子
流水线	`collections/<name>/+pipelines.ts`	流水线声明	流水线
集成	`collections/<name>/+integrations.ts`	集成声明	集成
表单覆盖	`collections/<name>/+representation.svelte`	创建/展示/编辑组件	UI 组件
自定义类型	`datatypes/<name>/+definition.ts`	`defineCustomType`	UI 组件
自定义类型渲染器	`datatypes/<name>/+renderer.svelte`	展示/编辑组件	UI 组件
应用	`apps/**/+<name>.svelte`	应用组件	应用
应用组	`apps/<group>/+group.ts`	`group`	应用
自动化	`automations/+<name>.ts`	`defineAutomation`	自动化
Agent 工具	`capabilities/tools/+<name>.ts` 位于 `src/`	`defineAgentTool`	自定义工具
Envoy	`envoys/+<name>.ts`	Envoy 声明	Envoy
Agent 指令	`+agents.md`	workspace prompt	Agents
Agent 技能	`capabilities/skills/<name>/+skill.md`	skill 文档	Agents
策略	`access/policies/+<name>.ts`	policy 声明	策略
远程函数	`functions/+<name>.ts`	`defineQueryHandler` / `defineCommandHandler`	函数
环境	`+env.ts`	`defineEnvironment`	工作区工作室
种子数据	`+seed.ts`	租户夹具行为	—

保留名称与标识符

以下名称归平台所有。使用它们是编译错误，而不是覆盖：

系统集合 —— user 、 team 、 approval_request 、 session 及平台基线中的其余集合可以被查询，但绝不能重新定义（系统集合 )
平台列 —— id 、 created_at 、 updated_at 、 row_version 、 sys_period 及 approval_id 会自动添加到每一行
内置 Agent 工具 —— describe_workspace 、 read_collection 、 write_collection 、 list_skills 、 read_skill 、 spawn_subagent 不能被重新定义为工作区 Agent 工具
随附技能 —— norbital-platform 与 authoring-tenant-workspace 拥有其名称；遮蔽这些名称的工作区技能会被拒绝
布局原语 —— Stack 、 Inline 、 Cluster 、 Split 、 Grid 、 Columns 、 Column 、 Cover 、 Center 、 Frame 、 Bound 、 Scroll 拥有其几何属性——参见布局
编译器私有模块 —— virtual:bolt/* 是编译器私有的；租户源码必须使用 $bolt/client

租户源码中任何位置都禁止使用：

schema.ts 、 workspace.ts 、集合桶文件、 *.schema.ts 、应用 App.svelte 、SvelteKit 路由、自定义打包器、 defineTable 、 defineSchema 、 QueryRow 、 NorbitalAuthoring 、 $tenant 、 #lib
编译器直接拒绝的遗留 API——先前的 Page/Pane/Region、布局元数据、split-client、遗留枚举、record-rep、 +create.svelte 与调用点创建 API。没有兼容路径。