105 lines
6.8 KiB
Plaintext
105 lines
6.8 KiB
Plaintext
---
|
|
title: 架构
|
|
description: Twenty 应用如何运作——沙盒化、生命周期与构建模块。
|
|
icon: sitemap
|
|
---
|
|
|
|
Twenty 应用是 TypeScript 包，可通过自定义对象、逻辑、UI 组件和 AI 能力扩展你的工作区。 它们在 Twenty 平台上运行，具备完备的沙盒与权限控制。
|
|
|
|
## 应用如何运作
|
|
|
|
应用是由 `twenty-sdk` 包中的 `defineEntity()` 函数声明的**实体**集合。 SDK 在构建时通过 AST 分析检测到这些声明，并生成一份**清单**——完整描述你的应用为工作区新增的内容。
|
|
|
|
```
|
|
your-app/
|
|
├── src/
|
|
│ ├── application-config.ts ← defineApplication (required, one per app)
|
|
│ ├── roles/ ← defineRole
|
|
│ ├── objects/ ← defineObject
|
|
│ ├── fields/ ← defineField
|
|
│ ├── logic-functions/ ← defineLogicFunction
|
|
│ ├── front-components/ ← defineFrontComponent
|
|
│ ├── skills/ ← defineSkill
|
|
│ ├── agents/ ← defineAgent
|
|
│ ├── views/ ← defineView
|
|
│ ├── navigation-menu-items/ ← defineNavigationMenuItem
|
|
│ └── page-layouts/ ← definePageLayout
|
|
├── public/ ← Static assets (images, icons)
|
|
└── package.json
|
|
```
|
|
|
|
<Note>
|
|
**文件组织由你决定。** 实体检测基于 AST——无论文件位于何处，SDK 都能找到 `export default defineEntity(...)` 的调用。 上述文件夹结构是一种约定，而非强制要求。
|
|
</Note>
|
|
|
|
## 实体类型
|
|
|
|
| 实体 | 目的 | 文档 |
|
|
| --------- | ------------------------- | -------------------------------------------------- |
|
|
| **应用程序** | 应用标识、权限、变量 | [数据模型](/l/zh/developers/extend/apps/data-model) |
|
|
| **角色** | 对象和字段的权限集 | [数据模型](/l/zh/developers/extend/apps/data-model) |
|
|
| **对象** | 带字段的自定义数据表 | [数据模型](/l/zh/developers/extend/apps/data-model) |
|
|
| **字段** | 扩展现有对象，定义关系 | [数据模型](/l/zh/developers/extend/apps/data-model) |
|
|
| **逻辑函数** | 带触发器的服务端 TypeScript | [逻辑函数](/l/zh/developers/extend/apps/logic-functions) |
|
|
| **前端组件** | 在 Twenty 页面中的沙盒化 React UI | [前端组件](/l/zh/developers/extend/apps/front-components) |
|
|
| **技能** | 可复用的 AI 代理指令 | [技能与代理](/l/zh/developers/extend/apps/skills-and-agents) |
|
|
| **代理** | 具有自定义提示词的 AI 助手 | [技能与代理](/l/zh/developers/extend/apps/skills-and-agents) |
|
|
| **视图** | 预配置的记录列表视图 | [布局](/l/zh/developers/extend/apps/layout) |
|
|
| **导航菜单项** | 自定义侧边栏条目 | [布局](/l/zh/developers/extend/apps/layout) |
|
|
| **页面布局** | 自定义记录页面的选项卡和小部件 | [布局](/l/zh/developers/extend/apps/layout) |
|
|
|
|
## 沙盒化
|
|
|
|
* **逻辑函数** 在服务器上的独立 Node.js 进程中运行。 它们只能通过类型化的 API 客户端访问数据，且范围受应用角色权限限制。
|
|
* **前端组件** 在使用 Remote DOM 的 Web Worker 中运行——与主页面沙盒隔离，但渲染原生 DOM 元素（非 iframe）。 它们通过消息传递的宿主 API 与 Twenty 通信。
|
|
* **权限** 在 API 层面强制执行。 运行时令牌（`TWENTY_APP_ACCESS_TOKEN`）源自 `defineApplication()` 中定义的角色。
|
|
|
|
## 应用生命周期
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Development │
|
|
│ npx create-twenty-app → yarn twenty dev (live sync) │
|
|
├─────────────────────────────────────────────────────────┤
|
|
│ Build & Deploy │
|
|
│ yarn twenty build → yarn twenty deploy │
|
|
├─────────────────────────────────────────────────────────┤
|
|
│ Install flow │
|
|
│ upload → [pre-install] → metadata migration → │
|
|
│ generate SDK → [post-install] │
|
|
├─────────────────────────────────────────────────────────┤
|
|
│ Publish │
|
|
│ npm publish → appears in Twenty marketplace │
|
|
└─────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
* **`yarn twenty dev`** — 监视你的源文件，并将更改实时同步到已连接的 Twenty 服务器。 当模式发生变化时，会自动重新生成类型化的 API 客户端。
|
|
* **`yarn twenty build`** — 编译 TypeScript，使用 esbuild 打包逻辑函数和前端组件，并生成清单。
|
|
* **预/后安装钩子** — 在安装过程中运行的可选逻辑函数。 详情请参见[逻辑函数](/l/zh/developers/extend/apps/logic-functions)。
|
|
|
|
## 后续步骤
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="数据模型" icon="database" href="/l/zh/developers/extend/apps/data-model">
|
|
定义对象、字段、角色和关系。
|
|
</Card>
|
|
<Card title="逻辑函数" icon="bolt" href="/l/zh/developers/extend/apps/logic-functions">
|
|
具有 HTTP、cron 和事件触发器的服务端函数。
|
|
</Card>
|
|
<Card title="前端组件" icon="window-maximize" href="/l/zh/developers/extend/apps/front-components">
|
|
Twenty 的 UI 中的沙盒化 React 组件。
|
|
</Card>
|
|
<Card title="布局" icon="table-columns" href="/l/zh/developers/extend/apps/layout">
|
|
视图、导航菜单项和记录页面布局。
|
|
</Card>
|
|
<Card title="技能与智能体" icon="robot" href="/l/zh/developers/extend/apps/skills-and-agents">
|
|
具有自定义提示词的 AI 技能与代理。
|
|
</Card>
|
|
<Card title="CLI 与测试" icon="terminal" href="/l/zh/developers/extend/apps/cli-and-testing">
|
|
CLI 命令、测试、资源、远程和 CI。
|
|
</Card>
|
|
<Card title="发布" icon="rocket" href="/l/zh/developers/extend/apps/publishing">
|
|
部署到服务器或发布到应用市场。
|
|
</Card>
|
|
</CardGroup>
|