upstream-twenty/packages/twenty-docs/l/zh/developers/extend/apps/getting-started/concepts.mdx

---
title: 概念
description: Twenty 应用的工作方式 — 实体模型、沙盒机制和安装生命周期。
icon: sitemap
---

Twenty 应用是 TypeScript 包，可通过自定义对象、逻辑、UI 组件和 AI 能力扩展你的工作区。 它们在 Twenty 平台上运行，具备完备的沙盒与权限控制。

## 应用如何运作

应用是由 `twenty-sdk` 包中的 `defineEntity()` 函数声明的**实体**集合。 SDK 在构建时通过 AST 分析检测到这些声明，并生成一份**清单**——完整描述你的应用为工作区新增的内容。 这些函数会在构建时校验你的配置，并提供 IDE 自动补全和类型安全。

```
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/config/application)                                                    |
| **角色**    | 对象和字段的权限集                         | [角色与权限](/l/zh/developers/extend/apps/config/roles)                                                         |
| **对象**    | 带字段的自定义记录类型                       | [对象](/l/zh/developers/extend/apps/data/objects)                                                            |
| **字段**    | 从其他应用向对象添加字段                      | [扩展对象](/l/zh/developers/extend/apps/data/extending-objects)                                                |
| **关系**    | 对象之间的双向链接                         | [关系](/l/zh/developers/extend/apps/data/relations)                                                          |
| **逻辑函数**  | 带触发器的服务端 TypeScript               | [逻辑函数](/l/zh/developers/extend/apps/logic/logic-functions)                                                 |
| **技能**    | 可复用的 AI 代理指令                      | [技能与代理](/l/zh/developers/extend/apps/logic/skills-and-agents)                                              |
| **代理**    | 具有自定义提示词的 AI 助手                   | [技能与代理](/l/zh/developers/extend/apps/logic/skills-and-agents)                                              |
| **连接提供方** | 用于第三方 API 的 OAuth 凭证              | [连接](/l/zh/developers/extend/apps/logic/connections)                                                       |
| **视图**    | 预配置的记录列表视图                        | [视图](/l/zh/developers/extend/apps/layout/views)                                                            |
| **导航菜单项** | 自定义侧边栏条目                          | [导航菜单项](/l/zh/developers/extend/apps/layout/navigation-menu-items)                                         |
| **页面布局**  | 记录详情页上的选项卡和小部件                    | [页面布局](/l/zh/developers/extend/apps/layout/page-layouts)                                                   |
| **前端组件**  | Twenty 内的沙盒化 React UI             | [前端组件](/l/zh/developers/extend/apps/layout/front-components)                                               |
| **共享依赖项** | 由应用的前端组件共享的依赖项，在 package.json 中声明 | [共享依赖项](/l/zh/developers/extend/apps/layout/front-components#sharing-dependencies-across-front-components) |
| **命令菜单项** | 快速操作和 Cmd+K 条目                    | [命令菜单项](/l/zh/developers/extend/apps/layout/command-menu-items)                                            |

## 沙盒化

* **逻辑函数** 在服务器上的独立 Node.js 进程中运行。 它们仅通过类型化 API 客户端访问数据，该客户端会以触发运行的人员或应用本身的身份执行操作。 请参阅[调用使用谁的访问权限](/l/zh/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses)。
* **前端组件** 在使用 Remote DOM 的 Web Worker 中运行——与主页面沙盒隔离，但渲染原生 DOM 元素（非 iframe）。 它们通过消息传递的宿主 API 与 Twenty 通信。
* **权限** 在 API 层面强制执行。 系统会注入两个运行时令牌，二者均派生自通过 `defineApplicationRole()` 声明的角色；只要运行由人员触发，默认令牌的权限范围就会进一步缩小为该触发人员可执行的操作。

## 应用生命周期

```
┌─────────────────────────────────────────────────────────┐
│ Development                                             │
│   npx create-twenty-app → yarn twenty dev (live sync)   │
├─────────────────────────────────────────────────────────┤
│ Build & Deploy                                          │
│   yarn twenty dev:build → yarn twenty app:publish        │
├─────────────────────────────────────────────────────────┤
│ Install flow                                            │
│   upload → [pre-install] → metadata migration →         │
│   generate SDK → [post-install] → … → [uninstall]       │
├─────────────────────────────────────────────────────────┤
│ Publish                                                 │
│   npm publish → appears in Twenty marketplace           │
└─────────────────────────────────────────────────────────┘
```

* **`yarn twenty dev`** — 监视你的源文件，并将更改实时同步到已连接的 Twenty 服务器。 当模式发生变化时，会自动重新生成类型化的 API 客户端。
* **`yarn twenty dev:build`** — 编译 TypeScript，使用 esbuild 打包逻辑函数和前端组件，并生成清单。
* **预/后安装和卸载钩子** — 在安装过程中或在卸载前立即运行的可选函数。 详见 [安装钩子](/l/zh/developers/extend/apps/config/install-hooks)。

## 后续步骤

<CardGroup cols={2}>
  <Card title="配置" icon="screwdriver-wrench" href="/l/zh/developers/extend/apps/config/overview">
    应用标识、默认角色，以及安装和卸载钩子。
  </Card>
  <Card title="数据" icon="database" href="/l/zh/developers/extend/apps/data/overview">
    对象、字段和双向关系。
  </Card>
  <Card title="逻辑" icon="bolt" href="/l/zh/developers/extend/apps/logic/overview">
    逻辑函数、技能、代理和 OAuth 连接。
  </Card>
  <Card title="布局" icon="table-columns" href="/l/zh/developers/extend/apps/layout/overview">
    视图、导航、页面布局、前端组件。
  </Card>
  <Card title="操作" icon="rocket" href="/l/zh/developers/extend/apps/operations/overview">
    CLI、测试、远程、CI，以及发布你的应用。
  </Card>
</CardGroup>