Documentation Index
Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
Use this file to discover all available pages before exploring further.
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
文件组织由你决定。 实体检测基于 AST——无论文件位于何处，SDK 都能找到 export default defineEntity(...) 的调用。 上述文件夹结构是一种约定，而非强制要求。
实体类型
| 实体 | 目的 | 文档 |
|---|
| 应用程序 | 应用标识、默认角色、变量 | 应用配置 |
| 角色 | 对象和字段的权限集 | 角色与权限 |
| 对象 | 带字段的自定义记录类型 | 对象 |
| 字段 | 从其他应用向对象添加字段 | 扩展对象 |
| 关系 | 对象之间的双向链接 | 关系 |
| 逻辑函数 | 带触发器的服务端 TypeScript | 逻辑函数 |
| 技能 | 可复用的 AI 代理指令 | 技能与代理 |
| 代理 | 具有自定义提示词的 AI 助手 | 技能与代理 |
| 连接提供方 | 用于第三方 API 的 OAuth 凭证 | 连接 |
| 视图 | 预配置的记录列表视图 | 视图 |
| 导航菜单项 | 自定义侧边栏条目 | 导航菜单项 |
| 页面布局 | 记录详情页上的选项卡和小部件 | 页面布局 |
| 前端组件 | Twenty 内的沙盒化 React UI | 前端组件 |
| 命令菜单项 | 快速操作和 Cmd+K 条目 | 命令菜单项 |
沙盒化
- 逻辑函数 在服务器上的独立 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 打包逻辑函数和前端组件，并生成清单。- 预/后安装钩子 — 在安装过程中运行的可选函数。 详见 安装钩子。
后续步骤
