文件系统

租户工作区是一个普通的 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
│       ├── +collection.ts         # optional — the write contract; absent means read-only
│       ├── +pipelines.ts          # optional
│       ├── +integrations.ts       # optional
│       └── +representation.svelte # required — create, display, and edit form
├── datatypes/<name>/
│   ├── +definition.ts
│   └── +renderer.svelte           # optional — falls back to the built-in JSON renderer
├── 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/
├── artifact/      # ignored — release bundle, code chunks, manifest, assets
├── config/        # committed — doctor configuration
├── diagnosis/     # ignored
├── dist/          # ignored — browser client
├── generated/     # ignored
├── migrations/    # committed — SQL lineage
├── types/         # ignored
└── tsconfig.json  # ignored

编写的根 tsconfig.json 继承 .norbital/tsconfig.json 。Bolt 拥有这份唯一的生成配置与所有编译器路径；它不使用 baseUrl 。只有 .norbital/migrations/ 与编写的 doctor 配置 .norbital/config/ 会被提交——`.norbital/` 下的其余内容都是可再生成的输出，包括发布产物。

命令

bolt sync
bolt migrate
bolt audit

bolt sync 运行文件系统编译器：校验角色、生成注册表模块、本地 $types 与生成的 TypeScript 配置。
bolt migrate 会对比已编写模型与迁移历史，并把下一条迁移写入 .norbital/migrations/ .
bolt audit 在可选 peer @norbital-ai/doctor 已安装时运行静态代码质量审计，并把报告写入 .norbital/diagnosis/ .

编写边界

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

一览所有角色

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

角色	位置	导出	文档
集合模型	`collections/<name>/+model.ts`	`defineModel`	集合
关联注册表	`collections/+relationship.ts`	关联构建器	集合
写入契约	`collections/<name>/+collection.ts`	defineCollection 声明	写入契约
流水线	`collections/<name>/+pipelines.ts`	流水线声明	流水线
集成	`collections/<name>/+integrations.ts`	集成声明	集成
表单覆盖	`collections/<name>/+representation.svelte`	创建/展示/编辑组件——用户需要创建或打开记录的集合必须有它	UI 组件
自定义类型	`datatypes/<name>/+definition.ts`	`defineCustomType`	UI 组件
自定义类型渲染器	`datatypes/<name>/+renderer.svelte`	展示/编辑组件——可选；缺少时回退到 JSON 渲染器	UI 组件
应用	`apps/**/+<name>.svelte`	应用组件	应用
应用组	`apps/<group>/+group.ts`	`group`	应用
自动化	`automations/+<name>.ts`	`defineAutomation`	自动化
Agent 工具	`capabilities/tools/+<name>.ts`	`defineAgentTool`	自定义工具
Envoy	`envoys/+<name>.ts`	Envoy 声明	Envoy
Agent 指令	`+agents.md`	workspace prompt	Norbius
Agent 技能	`capabilities/skills/<name>/SKILL.md`	skill 文档	Norbius
策略	`access/policies/+<name>.ts`	policy 声明	策略
函数	`functions/+<name>.ts`	`defineQueryHandler` / `defineCommandHandler`	函数
环境	`+env.ts`	`defineEnvironment`	工作区工作室

保留名称与标识符

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

系统集合 —— 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 、 subagent 、 wait / todo / compact / search_task_history / read_messages / use_image / update_plan 不能被重新定义为工作区 Agent 工具——分发优先匹配平台名称
随附技能 —— 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。没有兼容路径。