框架开发
技术规范
项目技术栈
公共
Node.js
TypeScript
JavaScript
pnpm
服务端
NestJS
PostgreSQL
TypeORM
...
前置准备
本地运行 BuildingAI 之前，你首先需要安装一些开发环境依赖项：
Docker
NodeJS
pnpm
环境准备
Docker
MacOS
Download for Mac – Apple Silicon
如果是Intel芯片的Mac则点击下面的链接下...
本地部署与开发
本地部署
上一篇 前置准备我们已经完成了环境的准备，接下来我们来本地部署和启动 BuildingAI。
拉取代码
首先从代码仓库拉取最新代码：
# Github
git clone https://github.com/BidingCC/BuildingAI.git
# or Gitee
git c...
目录结构
截止于 v26.0.0 版本，项目目录结构如下所示：
/
├── assets/ 静态资源（项目级图片、图标等）
├── docker/ Docker 相关配置与镜像构建文件
├── extensions/ 扩展应用（可插拔扩展/示例扩展）
├── packages/ 包
│ ├── @bui...
项目配置
截止于 v25.0.5 版本，项目.env文件配置如下：
# Base
# 项目名称
APP_NAME=BuildingAI
# if you deploy to production, please set this to real url
# 项目域名
APP_DOMAIN=
# Server...
主程 序启动链路
1. packages/api/src/main.ts
API 入口启动流程：
加载环境变量
调 AppModule.register()
创建 Nest app
注册 XML body parser 与 cookie parser
配置 CORS
配置静态资源目录
注册全局 Validation...
请求处理链路
1. 全局守卫顺序
当前主程序通过 APP_GUARD 注册了：
DemoGuard
AuthGuard
AgentGuard
ExtensionGuard
PermissionsGuard
SuperAdminGuard
MemberOnlyGuard
日常二开最常碰到的是：
AuthGua...
后端开发约定
1. 标准模块结构
主系统模块一般按下面组织：
packages/api/src/modules/{module-name}/
├── {module-name}.module.ts
├── controllers/
│ ├── console/
│ └── web/
├── service...
BaseController 与 BaseService
1. BaseController
主要用来统一分页返回：
return this.paginationResult(items, total, queryDto);
返回：
{
"items": [],
"total": 100,
"...
DTO、工具与通用服务
1. PaginationDto
分页 DTO 基类：
export class PaginationDto {
page?: number = 1;
pageSize?: number = 15;
}
2. buildWhere()
用于忽略 undefined 条件，简化列表查...
前端开发
1. 入口
主前端入口在：
packages/client/src/main.tsx
packages/client/src/router/index.tsx
默认挂载：
I18nProvider
QueryClientProvider
ThemeProvider
TooltipProvide...
主程序计费接入
主程序里的计费，不建议自己直接改 user.power，而应该统一走 AppBillingService 或 BaseBillingService。
1. 计费模块结构
主程序计费能力在：
packages/core/src/modules/billing/
├── billing.module.t...
数据库与实体建议
主系统表一般放在 public schema。
适合放主程序表的场景：
平台全局用户体系
全局菜单、 角色、权限
平台 AI 模型、Provider、MCP、数据集
支付、充值、会员、消息通知
简单查询优先用 buildWhere()，复杂查询再上 QueryBuilder。
AI SDK 开发文档
@buildingai/ai-sdk
基于 Vercel AI SDK 6.x 的统一 AI SDK，提供项目内统一的 Provider 注册、能力分发和常用工具封装。
特性
统一文本、Embedding、图像、语音、转写、重排序、内容审核能力
基于 getProvider() / getProv...
BuildingAI 升级开发文档
本文是教作为开发者如果进行升级脚本书写：
什么时候需要写 migration
什么时候需要写 Upgrade
Upgrade 应该怎么写
有没有命令可以生成升级文件
写完以后系统是怎么识别并执行的
本文适用于主程序范围内的二开：
packages/api
packages/client
pac...
前端组件与工具开发文档
本文档整理 BuildingAI 前端中已经自研或二次封装过的组件与工具。它不是第三方库说明书，而是告诉开发者：项目里已有的封装在哪里、适合解决什么问题、怎么接入、什么时候不要重复造。
范围与导入规则
类型
位置
导入方式
说明
跨项目 UI 组件
packages/@buildinga...
后端工具与封装开发文档
本文档整理 BuildingAI 后端中已经封装好的基础类、装饰器、模块和工具函数。目标是让开发者新增业务模块、扩展 API、数据库操作、上传/队列/缓存逻辑时，优先复用现有封装。
范围与导入规则
类型
位置
导入方式
用途
基础 Controller/Service
packages/...