235 lines
9.4 KiB
Plaintext
235 lines
9.4 KiB
Plaintext
---
|
|
title: 开始使用
|
|
description: 几分钟内创建你的第一个 Twenty 应用。
|
|
---
|
|
|
|
<Warning>
|
|
应用目前处于 Alpha 测试阶段。 该功能可用，但仍在演进中。
|
|
</Warning>
|
|
|
|
应用可通过自定义对象、字段、逻辑函数、AI 技能和 UI 组件来扩展 Twenty——全部以代码进行管理。
|
|
|
|
**你可以构建的内容:**
|
|
|
|
* 自定义对象、字段、视图和导航项，以塑造你的数据模型
|
|
* 由 HTTP 路由、cron 调度或数据库事件触发的逻辑函数
|
|
* 在 Twenty 的 UI 中直接渲染的前端组件
|
|
* 用于扩展 Twenty 的 AI 代理的技能
|
|
* 将同一个应用部署到多个工作空间
|
|
|
|
## 先决条件
|
|
|
|
* Node.js 24+
|
|
* Yarn 4
|
|
* Docker (或正在运行的本地 Twenty 实例)
|
|
|
|
## 开始使用
|
|
|
|
使用官方脚手架创建一个新应用，然后进行身份验证并开始开发：
|
|
|
|
```bash filename="Terminal"
|
|
# Scaffold a new app (includes all examples by default)
|
|
npx create-twenty-app@latest my-twenty-app
|
|
```
|
|
|
|
> 使用 `--minimal` 选项生成最简安装脚手架
|
|
|
|
从这里您可以：
|
|
|
|
```bash filename="Terminal"
|
|
# Add a new entity to your application (guided)
|
|
yarn twenty 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 uninstall
|
|
|
|
# Display commands' help
|
|
yarn twenty help
|
|
```
|
|
|
|
另请参阅：[create-twenty-app](https://www.npmjs.com/package/create-twenty-app) 和 [twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk) 的 CLI 参考页面。
|
|
|
|
## 项目结构（脚手架生成）
|
|
|
|
当你运行 `npx create-twenty-app@latest my-twenty-app` 时，脚手架将：
|
|
|
|
* 将一个最小的基础应用复制到 `my-twenty-app/` 中
|
|
* 添加本地 `twenty-sdk` 依赖和 Yarn 4 配置
|
|
* 创建与 `twenty` CLI 关联的配置文件和脚本
|
|
* 生成核心文件（应用配置、默认函数角色、安装前/安装后函数），并基于脚手架模式生成示例文件
|
|
|
|
使用默认 `--exhaustive` 模式新搭建的应用如下所示：
|
|
|
|
```text filename="my-twenty-app/"
|
|
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`、`.twenty/`、`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 代理技能定义 |
|
|
|
|
<Note>
|
|
**文件命名是灵活的。** 实体检测基于 AST — SDK 会扫描你的源文件以查找 `export default define<Entity>({...})` 模式。 你可以按照自己的喜好组织文件和文件夹。 按实体类型分组（例如 `logic-functions/`、`roles/`）只是代码组织的一种约定，并非必需。
|
|
</Note>
|
|
|
|
已检测实体的示例：
|
|
|
|
```typescript
|
|
// 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 dev` 会自动生成类型化的 `CoreApiClient`（通过 `/graphql` 获取工作区数据），并写入 `node_modules/twenty-client-sdk/`。 `MetadataApiClient`（通过 `/metadata` 处理工作区配置和文件上传）为预构建版本，可立即使用。 分别从 `twenty-client-sdk/core` 和 `twenty-client-sdk/metadata` 导入它们。
|
|
* `yarn twenty add` 会在 `src/` 下为你的自定义对象、函数、前端组件、角色、技能等添加实体定义文件。
|
|
|
|
## 身份验证
|
|
|
|
首次运行 `yarn twenty auth:login` 时，你将被提示输入：
|
|
|
|
* API URL（默认为 http://localhost:3000 或你当前的工作空间配置）
|
|
* API 密钥
|
|
|
|
你的凭据按用户存储在 `~/.twenty/config.json` 中。 你可以维护多个配置文件并在它们之间切换。
|
|
|
|
### 管理工作空间
|
|
|
|
```bash filename="Terminal"
|
|
# 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 中配置一个脚本：
|
|
|
|
```bash filename="Terminal"
|
|
yarn add -D twenty-sdk
|
|
```
|
|
|
|
然后添加一个 `twenty` 脚本：
|
|
|
|
```json filename="package.json"
|
|
{
|
|
"scripts": {
|
|
"twenty": "twenty"
|
|
}
|
|
}
|
|
```
|
|
|
|
现在你可以通过 `yarn twenty <command>` 运行所有命令，例如 `yarn twenty dev`、`yarn twenty help` 等。
|
|
|
|
## 如何使用本地 Twenty 实例
|
|
|
|
如果你已经在本地运行一个 Twenty 实例（例如通过 `npx nx start twenty-server`），你可以连接到它，而不是使用 Docker:
|
|
|
|
```bash filename="Terminal"
|
|
# During scaffolding — skip Docker, connect to your running instance
|
|
npx create-twenty-app@latest my-app --port 3000
|
|
|
|
# Or after scaffolding — add a remote pointing to your instance
|
|
yarn twenty remote add --local --port 3000
|
|
```
|
|
|
|
## 故障排除
|
|
|
|
* 身份验证错误：运行 `yarn twenty auth:login`，并确保你的 API 密钥具有所需权限。
|
|
* 无法连接到服务器：请验证 API URL，并确保 Twenty 服务器可达。
|
|
* 类型或客户端缺失/过期：重启 `yarn twenty dev` — 它会自动生成类型化客户端。
|
|
* 开发模式未同步：确保 `yarn twenty dev` 正在运行，并且你的环境不会忽略变更。
|
|
|
|
Discord 帮助频道：https://discord.com/channels/1130383047699738754/1130386664812982322
|