开始使用

应用目前处于 Alpha 测试阶段。该功能可用，但仍在演进中。

应用可通过自定义对象、字段、逻辑函数、AI 技能和 UI 组件来扩展 Twenty——全部以代码进行管理。 你现在可以做什么:

以代码定义自定义对象和字段（受管理的数据模型）
使用自定义触发器（HTTP 路由、cron、数据库事件）构建逻辑函数
为 AI 智能体定义技能
构建在 Twenty 的 UI 中渲染的前端组件
将同一个应用部署到多个工作空间

先决条件

Node.js 24+ 和 Yarn 4
一个 Twenty 工作空间和一个 API 密钥（在 https://app.twenty.com/settings/api-webhooks 创建）

使用官方脚手架创建一个新应用，然后进行身份验证并开始开发：

# Scaffold a new app (includes all examples by default)
npx create-twenty-app@latest my-twenty-app
cd my-twenty-app

# Start dev mode: automatically syncs local changes to your workspace
yarn twenty app:dev

脚手架工具支持两种模式，用于控制包含哪些示例文件：

# Default (exhaustive): all examples (object, field, logic function, front component, view, navigation menu item, skill)
npx create-twenty-app@latest my-app

# Minimal: only core files (application-config.ts and default-role.ts)
npx create-twenty-app@latest my-app --minimal

从这里您可以：

# Add a new entity to your application (guided)
yarn twenty entity:add

# Watch your application's function logs
yarn twenty function:logs

# Execute a function by name
yarn twenty function:execute -n my-function -p '{"name": "test"}'

# Execute the pre-install function
yarn twenty function:execute --preInstall

# Execute the post-install function
yarn twenty function:execute --postInstall

# Uninstall the application from the current workspace
yarn twenty app:uninstall

# Display commands' help
yarn twenty help

另请参阅：create-twenty-app 和 twenty-sdk CLI 的 CLI 参考页面。

项目结构（脚手架生成）

当你运行 npx create-twenty-app@latest my-twenty-app 时，脚手架将：

将一个最小的基础应用复制到 my-twenty-app/ 中
添加本地 twenty-sdk 依赖和 Yarn 4 配置
创建与 twenty CLI 关联的配置文件和脚本
生成核心文件（应用配置、默认函数角色、安装前/安装后函数），并基于脚手架模式生成示例文件

使用默认 --exhaustive 模式新搭建的应用如下所示：

my-twenty-app/
  package.json
  yarn.lock
  .gitignore
  .nvmrc
  .yarnrc.yml
  .yarn/
    install-state.gz
  .oxlintrc.json
  tsconfig.json
  README.md
  public/                           # Public assets folder (images, fonts, etc.)
  src/
  ├── application-config.ts           # Required - main application configuration
  ├── roles/
  │   └── default-role.ts               # Default role for logic functions
  ├── objects/
  │   └── example-object.ts             # Example custom object definition
  ├── fields/
  │   └── example-field.ts              # Example standalone field definition
  ├── logic-functions/
  │   ├── hello-world.ts                # Example logic function
  │   ├── pre-install.ts                # Pre-install logic function
  │   └── post-install.ts               # Post-install logic function
  ├── front-components/
  │   └── hello-world.tsx               # Example front component
  ├── views/
  │   └── example-view.ts                # Example saved view definition
  ├── navigation-menu-items/
  │   └── example-navigation-menu-item.ts # Example sidebar navigation link
  └── skills/
      └── example-skill.ts                # Example AI agent skill definition

使用 --minimal 时，只会创建核心文件（application-config.ts、roles/default-role.ts、logic-functions/pre-install.ts 和 logic-functions/post-install.ts）。总体来说：

package.json：声明应用名称、版本、引擎（Node 24+、Yarn 4），并添加 twenty-sdk 以及一个 twenty 脚本，该脚本会委托给本地的 twenty CLI。运行 yarn twenty help 以列出所有可用命令。
.gitignore：忽略常见产物，如 node_modules、.yarn、generated/（类型化客户端）、dist/、build/、覆盖率文件夹、日志文件以及 .env* 文件。
yarn.lock、.yarnrc.yml、.yarn/：锁定并配置项目使用的 Yarn 4 工具链。
.nvmrc：固定项目期望的 Node.js 版本。
.oxlintrc.json 和 tsconfig.json：为应用的 TypeScript 源码提供 Lint 与 TypeScript 配置。
README.md：应用根目录中的简短 README，包含基本说明。
public/: 一个用于存储公共资源（图像、字体、静态文件）的文件夹，这些资源将随你的应用程序一起提供。放置在此处的文件会在同步期间上传，并可在运行时访问。
src/：你以代码形式定义应用的主要位置

实体检测

该 SDK 通过在你的 TypeScript 文件中解析 export default define<Entity>({...}) 调用来检测实体。每种实体类型都有一个从 twenty-sdk 导出的对应辅助函数：

辅助函数	实体类型
`defineObject`	自定义对象定义
`defineLogicFunction`	逻辑函数定义
`definePreInstallLogicFunction`	安装前逻辑函数（在安装之前运行）
`definePostInstallLogicFunction`	安装后逻辑函数（在安装之后运行）
`defineFrontComponent`	前端组件定义
`defineRole`	角色定义
`defineField`	现有对象的字段扩展
`defineView`	已保存的视图定义
`defineNavigationMenuItem`	导航菜单项定义
`defineSkill`	AI 代理技能定义

文件命名是灵活的。 实体检测基于 AST — SDK 会扫描你的源文件以查找 export default define<Entity>({...}) 模式。你可以按照自己的喜好组织文件和文件夹。按实体类型分组（例如 logic-functions/、roles/）只是代码组织的一种约定，并非必需。

已检测实体的示例：

// This file can be named anything and placed anywhere in src/
import { defineObject, FieldType } from 'twenty-sdk';

export default defineObject({
  universalIdentifier: '...',
  nameSingular: 'postCard',
  // ... rest of config
});

后续命令将添加更多文件和文件夹：

yarn twenty app:dev 会在 node_modules/twenty-sdk/generated 中自动生成两个类型化 API 客户端：CoreApiClient（通过 /graphql 获取工作区数据）和 MetadataApiClient（通过 /metadata 处理工作区配置和文件上传）。
yarn twenty entity:add 会在 src/ 下为你的自定义对象、函数、前端组件、角色、技能等添加实体定义文件。

身份验证

首次运行 yarn twenty auth:login 时，你将被提示输入：

API URL（默认为 http://localhost:3000 或你当前的工作空间配置）
API 密钥

你的凭据按用户存储在 ~/.twenty/config.json 中。你可以维护多个配置文件并在它们之间切换。

管理工作空间

# Login interactively (recommended)
yarn twenty auth:login

# Login to a specific workspace profile
yarn twenty auth:login --workspace my-custom-workspace

# List all configured workspaces
yarn twenty auth:list

# Switch the default workspace (interactive)
yarn twenty auth:switch

# Switch to a specific workspace
yarn twenty auth:switch production

# Check current authentication status
yarn twenty auth:status

使用 yarn twenty auth:switch 切换工作空间后，后续所有命令将默认使用该工作空间。你仍可通过 --workspace <name> 临时覆盖。

手动设置（不使用脚手架）

虽然我们建议使用 create-twenty-app 以获得最佳的上手体验，但你也可以手动设置项目。不要全局安装 CLI。相反，请将 twenty-sdk 添加为本地依赖，并在你的 package.json 中配置一个脚本：

yarn add -D twenty-sdk

然后添加一个 twenty 脚本：

{
  "scripts": {
    "twenty": "twenty"
  }
}

现在你可以通过 yarn twenty <command> 运行所有命令，例如 yarn twenty app:dev、yarn twenty help 等。

故障排除

身份验证错误：运行 yarn twenty auth:login，并确保你的 API 密钥具有所需权限。
无法连接到服务器：请验证 API URL，并确保 Twenty 服务器可达。
类型或客户端缺失/过期：重启 yarn twenty app:dev — 它会自动生成类型化客户端。
开发模式未同步：确保 yarn twenty app:dev 正在运行，并且你的环境不会忽略变更。

Discord 帮助频道：https://discord.com/channels/1130383047699738754/1130386664812982322

开发者

扩展

自托管

贡献

开始使用

先决条件

开始使用

项目结构（脚手架生成）

实体检测

身份验证

管理工作空间

手动设置（不使用脚手架）

故障排除

开发者

扩展

自托管

贡献

​先决条件

​开始使用

​项目结构（脚手架生成）

​实体检测

​身份验证

​管理工作空间

​手动设置（不使用脚手架）

​故障排除

先决条件

开始使用

项目结构（脚手架生成）

实体检测

身份验证

管理工作空间

手动设置（不使用脚手架）

故障排除