i18n - docs translations (#19925)
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
This commit is contained in:
github-actions[bot]
committed by
GitHub
GitHub
parent
15938c1fca
commit
cd73088be6
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,434 @@
|
||||
---
|
||||
title: CLI & Testing
|
||||
description: CLI commands, testing setup, public assets, npm packages, remotes, and CI configuration.
|
||||
icon: terminal
|
||||
---
|
||||
|
||||
## Public assets (`public/` folder)
|
||||
|
||||
The `public/` folder at the root of your app holds static files — images, icons, fonts, or any other assets your app needs at runtime. These files are automatically included in builds, synced during dev mode, and uploaded to the server.
|
||||
|
||||
Files placed in `public/` are:
|
||||
|
||||
* **Publicly accessible** — once synced to the server, assets are served at a public URL. No authentication is needed to access them.
|
||||
* **Available in front components** — use asset URLs to display images, icons, or any media inside your React components.
|
||||
* **Available in logic functions** — reference asset URLs in emails, API responses, or any server-side logic.
|
||||
* **Used for marketplace metadata** — the `logoUrl` and `screenshots` fields in `defineApplication()` reference files from this folder (e.g., `public/logo.png`). These are displayed in the marketplace when your app is published.
|
||||
* **Auto-synced in dev mode** — when you add, update, or delete a file in `public/`, it is synced to the server automatically. No restart needed.
|
||||
* **Included in builds** — `yarn twenty build` bundles all public assets into the distribution output.
|
||||
|
||||
### Accessing public assets with `getPublicAssetUrl`
|
||||
|
||||
Use the `getPublicAssetUrl` helper from `twenty-sdk` to get the full URL of a file in your `public/` directory. It works in both **logic functions** and **front components**.
|
||||
|
||||
**In a logic function:**
|
||||
|
||||
```ts src/logic-functions/send-invoice.ts
|
||||
import { defineLogicFunction, getPublicAssetUrl } from 'twenty-sdk/define';
|
||||
|
||||
const handler = async (): Promise<any> => {
|
||||
const logoUrl = getPublicAssetUrl('logo.png');
|
||||
const invoiceUrl = getPublicAssetUrl('templates/invoice.png');
|
||||
|
||||
// Fetch the file content (no auth required — public endpoint)
|
||||
const response = await fetch(invoiceUrl);
|
||||
const buffer = await response.arrayBuffer();
|
||||
|
||||
return { logoUrl, size: buffer.byteLength };
|
||||
};
|
||||
|
||||
export default defineLogicFunction({
|
||||
universalIdentifier: 'a1b2c3d4-...',
|
||||
name: 'send-invoice',
|
||||
description: 'Sends an invoice with the app logo',
|
||||
timeoutSeconds: 10,
|
||||
handler,
|
||||
});
|
||||
```
|
||||
|
||||
**In a front component:**
|
||||
|
||||
```tsx src/front-components/company-card.tsx
|
||||
import { defineFrontComponent, getPublicAssetUrl } from 'twenty-sdk/define';
|
||||
|
||||
export default defineFrontComponent(() => {
|
||||
const logoUrl = getPublicAssetUrl('logo.png');
|
||||
|
||||
return <img src={logoUrl} alt="App logo" />;
|
||||
});
|
||||
```
|
||||
|
||||
The `path` argument is relative to your app's `public/` folder. Both `getPublicAssetUrl('logo.png')` and `getPublicAssetUrl('public/logo.png')` resolve to the same URL — the `public/` prefix is stripped automatically if present.
|
||||
|
||||
## Using npm packages
|
||||
|
||||
You can install and use any npm package in your app. Both logic functions and front components are bundled with [esbuild](https://esbuild.github.io/), which inlines all dependencies into the output — no `node_modules` are needed at runtime.
|
||||
|
||||
### Installing a package
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn add axios
|
||||
```
|
||||
|
||||
Then import it in your code:
|
||||
|
||||
```ts src/logic-functions/fetch-data.ts
|
||||
import { defineLogicFunction } from 'twenty-sdk/define';
|
||||
import axios from 'axios';
|
||||
|
||||
const handler = async (): Promise<any> => {
|
||||
const { data } = await axios.get('https://api.example.com/data');
|
||||
|
||||
return { data };
|
||||
};
|
||||
|
||||
export default defineLogicFunction({
|
||||
universalIdentifier: '...',
|
||||
name: 'fetch-data',
|
||||
description: 'Fetches data from an external API',
|
||||
timeoutSeconds: 10,
|
||||
handler,
|
||||
});
|
||||
```
|
||||
|
||||
The same works for front components:
|
||||
|
||||
```tsx src/front-components/chart.tsx
|
||||
import { defineFrontComponent } from 'twenty-sdk/define';
|
||||
import { format } from 'date-fns';
|
||||
|
||||
const DateWidget = () => {
|
||||
return <p>Today is {format(new Date(), 'MMMM do, yyyy')}</p>;
|
||||
};
|
||||
|
||||
export default defineFrontComponent({
|
||||
universalIdentifier: '...',
|
||||
name: 'date-widget',
|
||||
component: DateWidget,
|
||||
});
|
||||
```
|
||||
|
||||
### How bundling works
|
||||
|
||||
构建步骤使用 esbuild 为每个逻辑函数和每个前端组件生成一个自包含文件。 All imported packages are inlined into the bundle.
|
||||
|
||||
**Logic functions** run in a Node.js environment. Node built-in modules (`fs`, `path`, `crypto`, `http`, etc.) are available and do not need to be installed.
|
||||
|
||||
**Front components** run in a Web Worker. Node built-in modules are **not** available — only browser APIs and npm packages that work in a browser environment.
|
||||
|
||||
Both environments have `twenty-client-sdk/core` and `twenty-client-sdk/metadata` available as pre-provided modules — these are not bundled but resolved at runtime by the server.
|
||||
|
||||
## 测试你的应用
|
||||
|
||||
该 SDK 提供可编程的 API，使你可以在测试代码中构建、部署、安装和卸载你的应用。 结合 [Vitest](https://vitest.dev/) 和类型化 API 客户端，你可以编写集成测试，在真实的 Twenty 服务器上验证你的应用端到端运行是否正常。
|
||||
|
||||
### 设置
|
||||
|
||||
脚手架生成的应用已包含 Vitest。 如果你手动进行设置，请安装这些依赖：
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn add -D vitest vite-tsconfig-paths
|
||||
```
|
||||
|
||||
在应用根目录下创建一个 `vitest.config.ts`：
|
||||
|
||||
```ts vitest.config.ts
|
||||
import tsconfigPaths from 'vite-tsconfig-paths';
|
||||
import { defineConfig } from 'vitest/config';
|
||||
|
||||
export default defineConfig({
|
||||
plugins: [
|
||||
tsconfigPaths({
|
||||
projects: ['tsconfig.spec.json'],
|
||||
ignoreConfigErrors: true,
|
||||
}),
|
||||
],
|
||||
test: {
|
||||
testTimeout: 120_000,
|
||||
hookTimeout: 120_000,
|
||||
include: ['src/**/*.integration-test.ts'],
|
||||
setupFiles: ['src/__tests__/setup-test.ts'],
|
||||
env: {
|
||||
TWENTY_API_URL: 'http://localhost:2020',
|
||||
TWENTY_API_KEY: 'your-api-key',
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
创建一个设置文件，在测试运行前验证服务器可达：
|
||||
|
||||
```ts src/__tests__/setup-test.ts
|
||||
import * as fs from 'fs';
|
||||
import * as os from 'os';
|
||||
import * as path from 'path';
|
||||
import { beforeAll } from 'vitest';
|
||||
|
||||
const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020';
|
||||
const TEST_CONFIG_DIR = path.join(os.tmpdir(), '.twenty-sdk-test');
|
||||
|
||||
beforeAll(async () => {
|
||||
// Verify the server is running
|
||||
const response = await fetch(`${TWENTY_API_URL}/healthz`);
|
||||
|
||||
if (!response.ok) {
|
||||
throw new Error(
|
||||
`Twenty server is not reachable at ${TWENTY_API_URL}. ` +
|
||||
'Start the server before running integration tests.',
|
||||
);
|
||||
}
|
||||
|
||||
// Write a temporary config for the SDK
|
||||
fs.mkdirSync(TEST_CONFIG_DIR, { recursive: true });
|
||||
|
||||
fs.writeFileSync(
|
||||
path.join(TEST_CONFIG_DIR, 'config.json'),
|
||||
JSON.stringify({
|
||||
remotes: {
|
||||
local: {
|
||||
apiUrl: process.env.TWENTY_API_URL,
|
||||
apiKey: process.env.TWENTY_API_KEY,
|
||||
},
|
||||
},
|
||||
defaultRemote: 'local',
|
||||
}, null, 2),
|
||||
);
|
||||
});
|
||||
```
|
||||
|
||||
### 可编程的 SDK API
|
||||
|
||||
子路径 `twenty-sdk/cli` 导出了可直接在测试代码中调用的函数：
|
||||
|
||||
| 函数 | 描述 |
|
||||
| -------------- | ------------------ |
|
||||
| `appBuild` | 构建应用，并可选地打包为 tar 包 |
|
||||
| `appDeploy` | 将 tar 包上传到服务器 |
|
||||
| `appInstall` | 在活动工作区安装该应用 |
|
||||
| `appUninstall` | 从活动工作区卸载该应用 |
|
||||
|
||||
每个函数都会返回一个结果对象，包含 `success: boolean`，以及 `data` 或 `error` 之一。
|
||||
|
||||
### 编写集成测试
|
||||
|
||||
下面是一个完整示例：构建、部署并安装该应用，然后验证它出现在工作区中：
|
||||
|
||||
```ts src/__tests__/app-install.integration-test.ts
|
||||
import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config';
|
||||
import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli';
|
||||
import { MetadataApiClient } from 'twenty-client-sdk/metadata';
|
||||
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
|
||||
|
||||
const APP_PATH = process.cwd();
|
||||
|
||||
describe('App installation', () => {
|
||||
beforeAll(async () => {
|
||||
const buildResult = await appBuild({
|
||||
appPath: APP_PATH,
|
||||
tarball: true,
|
||||
onProgress: (message: string) => console.log(`[build] ${message}`),
|
||||
});
|
||||
|
||||
if (!buildResult.success) {
|
||||
throw new Error(`Build failed: ${buildResult.error?.message}`);
|
||||
}
|
||||
|
||||
const deployResult = await appDeploy({
|
||||
tarballPath: buildResult.data.tarballPath!,
|
||||
onProgress: (message: string) => console.log(`[deploy] ${message}`),
|
||||
});
|
||||
|
||||
if (!deployResult.success) {
|
||||
throw new Error(`Deploy failed: ${deployResult.error?.message}`);
|
||||
}
|
||||
|
||||
const installResult = await appInstall({ appPath: APP_PATH });
|
||||
|
||||
if (!installResult.success) {
|
||||
throw new Error(`Install failed: ${installResult.error?.message}`);
|
||||
}
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
await appUninstall({ appPath: APP_PATH });
|
||||
});
|
||||
|
||||
it('should find the installed app in the workspace', async () => {
|
||||
const metadataClient = new MetadataApiClient();
|
||||
|
||||
const result = await metadataClient.query({
|
||||
findManyApplications: {
|
||||
id: true,
|
||||
name: true,
|
||||
universalIdentifier: true,
|
||||
},
|
||||
});
|
||||
|
||||
const installedApp = result.findManyApplications.find(
|
||||
(app: { universalIdentifier: string }) =>
|
||||
app.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER,
|
||||
);
|
||||
|
||||
expect(installedApp).toBeDefined();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### 运行测试
|
||||
|
||||
确保你的本地 Twenty 服务器正在运行，然后：
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn test
|
||||
```
|
||||
|
||||
或者在开发期间使用监听模式：
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn test:watch
|
||||
```
|
||||
|
||||
### 类型检查
|
||||
|
||||
你也可以在不运行测试的情况下对应用进行类型检查：
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty typecheck
|
||||
```
|
||||
|
||||
这会运行 `tsc --noEmit` 并报告所有类型错误。
|
||||
|
||||
## CLI 参考
|
||||
|
||||
除了 `dev`、`build`、`add` 和 `typecheck` 外，CLI 还提供了用于执行函数、查看日志和管理应用安装的命令。
|
||||
|
||||
### 执行函数（`yarn twenty exec`）
|
||||
|
||||
手动运行逻辑函数，而无需通过 HTTP、定时任务或数据库事件来触发：
|
||||
|
||||
```bash filename="Terminal"
|
||||
# Execute by function name
|
||||
yarn twenty exec -n create-new-post-card
|
||||
|
||||
# Execute by universalIdentifier
|
||||
yarn twenty exec -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf
|
||||
|
||||
# Pass a JSON payload
|
||||
yarn twenty exec -n create-new-post-card -p '{"name": "Hello"}'
|
||||
|
||||
# Execute the post-install function
|
||||
yarn twenty exec --postInstall
|
||||
```
|
||||
|
||||
### 查看函数日志（`yarn twenty logs`）
|
||||
|
||||
实时流式查看你的应用逻辑函数的执行日志：
|
||||
|
||||
```bash filename="Terminal"
|
||||
# Stream all function logs
|
||||
yarn twenty logs
|
||||
|
||||
# Filter by function name
|
||||
yarn twenty logs -n create-new-post-card
|
||||
|
||||
# Filter by universalIdentifier
|
||||
yarn twenty logs -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf
|
||||
```
|
||||
|
||||
<Note>
|
||||
这与 `yarn twenty server logs` 不同，后者显示的是 Docker 容器日志。 `yarn twenty logs` 会显示来自 Twenty 服务器的应用函数执行日志。
|
||||
</Note>
|
||||
|
||||
### 卸载应用（`yarn twenty uninstall`）
|
||||
|
||||
将你的应用从活动工作区中移除：
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty uninstall
|
||||
|
||||
# Skip the confirmation prompt
|
||||
yarn twenty uninstall --yes
|
||||
```
|
||||
|
||||
## 管理远程
|
||||
|
||||
“远程”是指你的应用连接到的 Twenty 服务器。 在设置期间，脚手架工具会为你自动创建一个。 你可以随时添加更多远程或在它们之间切换。
|
||||
|
||||
```bash filename="Terminal"
|
||||
# Add a new remote (opens a browser for OAuth login)
|
||||
yarn twenty remote add
|
||||
|
||||
# Connect to a local Twenty server (auto-detects port 2020 or 3000)
|
||||
yarn twenty remote add --local
|
||||
|
||||
# Add a remote non-interactively (useful for CI)
|
||||
yarn twenty remote add --api-url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as my-remote
|
||||
|
||||
# List all configured remotes
|
||||
yarn twenty remote list
|
||||
|
||||
# Switch the active remote
|
||||
yarn twenty remote switch <name>
|
||||
```
|
||||
|
||||
你的凭据存储在 `~/.twenty/config.json` 中。
|
||||
|
||||
## 使用 GitHub Actions 进行 CI
|
||||
|
||||
脚手架工具会在 `.github/workflows/ci.yml` 生成一个开箱即用的 GitHub Actions 工作流。 它会在每次向 `main` 推送以及拉取请求上自动运行你的集成测试。
|
||||
|
||||
工作流：
|
||||
|
||||
1. 检出你的代码
|
||||
2. 使用 `twentyhq/twenty/.github/actions/spawn-twenty-docker-image` 动作启动一个临时的 Twenty 服务器
|
||||
3. 使用 `yarn install --immutable` 安装依赖
|
||||
4. 运行 `yarn test`，并从该动作的输出中注入 `TWENTY_API_URL` 和 `TWENTY_API_KEY`
|
||||
|
||||
```yaml .github/workflows/ci.yml
|
||||
name: CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
pull_request: {}
|
||||
|
||||
env:
|
||||
TWENTY_VERSION: latest
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Spawn Twenty instance
|
||||
id: twenty
|
||||
uses: twentyhq/twenty/.github/actions/spawn-twenty-docker-image@main
|
||||
with:
|
||||
twenty-version: ${{ env.TWENTY_VERSION }}
|
||||
github-token: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
- name: Enable Corepack
|
||||
run: corepack enable
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version-file: '.nvmrc'
|
||||
cache: 'yarn'
|
||||
|
||||
- name: Install dependencies
|
||||
run: yarn install --immutable
|
||||
|
||||
- name: Run integration tests
|
||||
run: yarn test
|
||||
env:
|
||||
TWENTY_API_URL: ${{ steps.twenty.outputs.server-url }}
|
||||
TWENTY_API_KEY: ${{ steps.twenty.outputs.access-token }}
|
||||
```
|
||||
|
||||
你无需配置任何机密——`spawn-twenty-docker-image` 动作会在运行器中直接启动一个临时的 Twenty 服务器，并输出连接详情。 GitHub 会自动提供 `GITHUB_TOKEN` 机密。
|
||||
|
||||
若要固定为特定的 Twenty 版本而不是 `latest`，请在工作流顶部修改 `TWENTY_VERSION` 环境变量。
|
||||
@@ -0,0 +1,494 @@
|
||||
---
|
||||
title: 数据模型
|
||||
description: Define objects, fields, roles, and application metadata with the Twenty SDK.
|
||||
icon: database
|
||||
---
|
||||
|
||||
The `twenty-sdk` package provides `defineEntity` functions to declare your app's data model. 你必须使用 `export default defineEntity({...})`，这样 SDK 才能检测到你的实体。 这些函数会在构建时校验你的配置，并提供 IDE 自动补全和类型安全。
|
||||
|
||||
<Note>
|
||||
**文件组织由你决定。**
|
||||
实体检测基于 AST——无论文件位于何处，SDK 都能找到 `export default defineEntity(...)` 的调用。 按类型对文件分组（例如 `logic-functions/`、`roles/`）只是代码组织的一种约定，并非必需。
|
||||
</Note>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="defineRole" description="配置角色权限和对象访问">
|
||||
|
||||
角色封装了对你的工作空间对象与操作的权限。
|
||||
|
||||
```ts restricted-company-role.ts
|
||||
import {
|
||||
defineRole,
|
||||
PermissionFlag,
|
||||
STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
|
||||
} from 'twenty-sdk/define';
|
||||
|
||||
export default defineRole({
|
||||
universalIdentifier: '2c80f640-2083-4803-bb49-003e38279de6',
|
||||
label: 'My new role',
|
||||
description: 'A role that can be used in your workspace',
|
||||
canReadAllObjectRecords: false,
|
||||
canUpdateAllObjectRecords: false,
|
||||
canSoftDeleteAllObjectRecords: false,
|
||||
canDestroyAllObjectRecords: false,
|
||||
canUpdateAllSettings: false,
|
||||
canBeAssignedToAgents: false,
|
||||
canBeAssignedToUsers: false,
|
||||
canBeAssignedToApiKeys: false,
|
||||
objectPermissions: [
|
||||
{
|
||||
objectUniversalIdentifier:
|
||||
STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
|
||||
canReadObjectRecords: true,
|
||||
canUpdateObjectRecords: true,
|
||||
canSoftDeleteObjectRecords: false,
|
||||
canDestroyObjectRecords: false,
|
||||
},
|
||||
],
|
||||
fieldPermissions: [
|
||||
{
|
||||
objectUniversalIdentifier:
|
||||
STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
|
||||
fieldUniversalIdentifier:
|
||||
STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.name.universalIdentifier,
|
||||
canReadFieldValue: false,
|
||||
canUpdateFieldValue: false,
|
||||
},
|
||||
],
|
||||
permissionFlags: [PermissionFlag.APPLICATIONS],
|
||||
});
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="defineApplication" description="配置应用元数据（必需，每个应用一个）">
|
||||
|
||||
每个应用必须且只能有一个 `defineApplication` 调用，用于描述：
|
||||
|
||||
* **应用的身份**：标识符、显示名称和描述。
|
||||
* **权限**：其函数和前端组件所使用的角色。
|
||||
* **（可选）变量**：以环境变量形式提供给函数的键值对。
|
||||
* **（可选）安装前/安装后函数**：在安装之前或之后运行的逻辑函数。
|
||||
|
||||
```ts src/application-config.ts
|
||||
import { defineApplication } from 'twenty-sdk/define';
|
||||
import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role';
|
||||
|
||||
export default defineApplication({
|
||||
universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
|
||||
displayName: 'My Twenty App',
|
||||
description: 'My first Twenty app',
|
||||
icon: 'IconWorld',
|
||||
applicationVariables: {
|
||||
DEFAULT_RECIPIENT_NAME: {
|
||||
universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
|
||||
description: 'Default recipient name for postcards',
|
||||
value: 'Jane Doe',
|
||||
isSecret: false,
|
||||
},
|
||||
},
|
||||
defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
|
||||
});
|
||||
```
|
||||
|
||||
备注:
|
||||
* `universalIdentifier` 字段是你拥有的确定性 ID。 只需生成一次，并在多次同步过程中保持稳定不变。
|
||||
* `applicationVariables` 会变成你的函数和前端组件可用的环境变量（例如，`DEFAULT_RECIPIENT_NAME` 可作为 `process.env.DEFAULT_RECIPIENT_NAME` 使用）。
|
||||
* `defaultRoleUniversalIdentifier` 必须引用使用 `defineRole()` 定义的角色（见上文）。
|
||||
* 在构建清单时会自动检测安装前/安装后函数——无需在 `defineApplication()` 中引用它们。
|
||||
|
||||
#### 应用市场元数据
|
||||
|
||||
如果你计划[发布你的应用](/l/zh/developers/extend/apps/publishing)，这些可选字段将控制你的应用在应用市场中的展示：
|
||||
|
||||
| 字段 | 描述 |
|
||||
| ------------------ | -------------------------------------------------------------- |
|
||||
| `作者` | 作者或公司名称 |
|
||||
| `类别` | 用于应用市场筛选的应用类别 |
|
||||
| `logoUrl` | 应用徽标的路径（例如 `public/logo.png`） |
|
||||
| `screenshots` | 截图路径数组（例如 `public/screenshot-1.png`） |
|
||||
| `aboutDescription` | 用于“关于”选项卡的更长的 Markdown 描述。 如果省略，市场将使用该软件包在 npm 上的 `README.md`。 |
|
||||
| `websiteUrl` | 你的网站链接 |
|
||||
| `termsUrl` | 服务条款链接 |
|
||||
| `emailSupport` | 支持电子邮件地址 |
|
||||
| `issueReportUrl` | 问题跟踪器链接 |
|
||||
|
||||
#### 角色和权限
|
||||
|
||||
`application-config.ts` 中的 `defaultRoleUniversalIdentifier` 字段指定你的应用的逻辑函数和前端组件所使用的默认角色。 详见上文的 `defineRole`。
|
||||
|
||||
* 作为 `TWENTY_APP_ACCESS_TOKEN` 注入的运行时令牌来源于该角色。
|
||||
* 类型化客户端将受限于该角色授予的权限。
|
||||
* 遵循最小权限原则：创建一个仅包含你的函数所需权限的专用角色。
|
||||
|
||||
##### 默认函数角色
|
||||
|
||||
当你使用脚手架创建新应用时，CLI 会创建一个默认角色文件：
|
||||
|
||||
```ts src/roles/default-role.ts
|
||||
import { defineRole, PermissionFlag } from 'twenty-sdk/define';
|
||||
|
||||
export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
|
||||
'b648f87b-1d26-4961-b974-0908fd991061';
|
||||
|
||||
export default defineRole({
|
||||
universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
|
||||
label: 'Default function role',
|
||||
description: 'Default role for function Twenty client',
|
||||
canReadAllObjectRecords: true,
|
||||
canUpdateAllObjectRecords: false,
|
||||
canSoftDeleteAllObjectRecords: false,
|
||||
canDestroyAllObjectRecords: false,
|
||||
canUpdateAllSettings: false,
|
||||
canBeAssignedToAgents: false,
|
||||
canBeAssignedToUsers: false,
|
||||
canBeAssignedToApiKeys: false,
|
||||
objectPermissions: [],
|
||||
fieldPermissions: [],
|
||||
permissionFlags: [],
|
||||
});
|
||||
```
|
||||
|
||||
该角色的 `universalIdentifier` 会在 `application-config.ts` 中被引用为 `defaultRoleUniversalIdentifier`：
|
||||
|
||||
* **\*.role.ts** 定义该角色可以执行的操作。
|
||||
* **application-config.ts** 指向该角色，使你的函数继承其权限。
|
||||
|
||||
备注:
|
||||
* 从脚手架生成的角色开始，然后按照最小权限原则逐步收紧权限。
|
||||
* 将 `objectPermissions` 和 `fieldPermissions` 替换为你的函数所需的对象/字段。
|
||||
* `permissionFlags` 控制对平台级能力的访问。 尽量保持最小化。
|
||||
* 查看一个可运行示例：[`hello-world/src/roles/function-role.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/hello-world/src/roles/function-role.ts)。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="defineObject" description="定义带字段的自定义对象">
|
||||
|
||||
自定义对象同时描述工作空间中记录的架构与行为。 使用 `defineObject()` 以内置校验定义对象：
|
||||
|
||||
```ts postCard.object.ts
|
||||
import { defineObject, FieldType } from 'twenty-sdk/define';
|
||||
|
||||
enum PostCardStatus {
|
||||
DRAFT = 'DRAFT',
|
||||
SENT = 'SENT',
|
||||
DELIVERED = 'DELIVERED',
|
||||
RETURNED = 'RETURNED',
|
||||
}
|
||||
|
||||
export default defineObject({
|
||||
universalIdentifier: '54b589ca-eeed-4950-a176-358418b85c05',
|
||||
nameSingular: 'postCard',
|
||||
namePlural: 'postCards',
|
||||
labelSingular: 'Post Card',
|
||||
labelPlural: 'Post Cards',
|
||||
description: 'A post card object',
|
||||
icon: 'IconMail',
|
||||
fields: [
|
||||
{
|
||||
universalIdentifier: '58a0a314-d7ea-4865-9850-7fb84e72f30b',
|
||||
name: 'content',
|
||||
type: FieldType.TEXT,
|
||||
label: 'Content',
|
||||
description: "Postcard's content",
|
||||
icon: 'IconAbc',
|
||||
},
|
||||
{
|
||||
universalIdentifier: 'c6aa31f3-da76-4ac6-889f-475e226009ac',
|
||||
name: 'recipientName',
|
||||
type: FieldType.FULL_NAME,
|
||||
label: 'Recipient name',
|
||||
icon: 'IconUser',
|
||||
},
|
||||
{
|
||||
universalIdentifier: '95045777-a0ad-49ec-98f9-22f9fc0c8266',
|
||||
name: 'recipientAddress',
|
||||
type: FieldType.ADDRESS,
|
||||
label: 'Recipient address',
|
||||
icon: 'IconHome',
|
||||
},
|
||||
{
|
||||
universalIdentifier: '87b675b8-dd8c-4448-b4ca-20e5a2234a1e',
|
||||
name: 'status',
|
||||
type: FieldType.SELECT,
|
||||
label: 'Status',
|
||||
icon: 'IconSend',
|
||||
defaultValue: `'${PostCardStatus.DRAFT}'`,
|
||||
options: [
|
||||
{ value: PostCardStatus.DRAFT, label: 'Draft', position: 0, color: 'gray' },
|
||||
{ value: PostCardStatus.SENT, label: 'Sent', position: 1, color: 'orange' },
|
||||
{ value: PostCardStatus.DELIVERED, label: 'Delivered', position: 2, color: 'green' },
|
||||
{ value: PostCardStatus.RETURNED, label: 'Returned', position: 3, color: 'orange' },
|
||||
],
|
||||
},
|
||||
{
|
||||
universalIdentifier: 'e06abe72-5b44-4e7f-93be-afc185a3c433',
|
||||
name: 'deliveredAt',
|
||||
type: FieldType.DATE_TIME,
|
||||
label: 'Delivered at',
|
||||
icon: 'IconCheck',
|
||||
isNullable: true,
|
||||
defaultValue: null,
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
关键点：
|
||||
|
||||
* 使用 `defineObject()` 以获得内置校验和更好的 IDE 支持。
|
||||
* `universalIdentifier` 必须在各次部署间保持唯一且稳定。
|
||||
* 每个字段都需要 `name`、`type`、`label` 以及其自身稳定的 `universalIdentifier`。
|
||||
* `fields` 数组是可选的——你可以定义没有自定义字段的对象。
|
||||
* 你可以使用 `yarn twenty add` 脚手架创建新对象，它会引导你完成命名、字段和关系。
|
||||
|
||||
<Note>
|
||||
**基础字段会自动创建。** 当你定义自定义对象时，Twenty 会自动添加标准字段
|
||||
例如 `id`、`name`、`createdAt`、`updatedAt`、`createdBy`、`updatedBy` 和 `deletedAt`。
|
||||
你无需在 `fields` 数组中定义这些字段——只需添加你的自定义字段。
|
||||
你可以通过在你的 `fields` 数组中定义一个同名字段来覆盖默认字段，
|
||||
但不建议这样做。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="defineField — 标准字段" description="为现有对象扩展额外字段">
|
||||
|
||||
使用 `defineField()` 向你不拥有的对象添加字段——例如标准的 Twenty 对象（Person、Company 等）。 或来自其他应用的对象。 与在 `defineObject()` 中的内联字段不同，独立字段需要一个 `objectUniversalIdentifier` 来指定它们要扩展的对象：
|
||||
|
||||
```ts src/fields/company-loyalty-tier.field.ts
|
||||
import { defineField, FieldType } from 'twenty-sdk/define';
|
||||
|
||||
export default defineField({
|
||||
universalIdentifier: 'f2a1b3c4-d5e6-7890-abcd-ef1234567890',
|
||||
objectUniversalIdentifier: '701aecb9-eb1c-4d84-9d94-b954b231b64b', // Company object
|
||||
name: 'loyaltyTier',
|
||||
type: FieldType.SELECT,
|
||||
label: 'Loyalty Tier',
|
||||
icon: 'IconStar',
|
||||
options: [
|
||||
{ value: 'BRONZE', label: 'Bronze', position: 0, color: 'orange' },
|
||||
{ value: 'SILVER', label: 'Silver', position: 1, color: 'gray' },
|
||||
{ value: 'GOLD', label: 'Gold', position: 2, color: 'yellow' },
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
关键点：
|
||||
* `objectUniversalIdentifier` 用于标识目标对象。 对于标准对象，请使用从 `twenty-sdk` 导出的 `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS`。
|
||||
* 在 `defineObject()` 中以内联方式定义字段时，你不需要 `objectUniversalIdentifier`——它会从父对象继承。
|
||||
* `defineField()` 是为非通过 `defineObject()` 创建的对象添加字段的唯一方式。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="defineField — 关联字段" description="使用双向关系将对象连接在一起">
|
||||
|
||||
关系用于将对象彼此连接。 在 Twenty 中，关系始终是双向的——你需要定义两侧，每一侧都引用另一侧。
|
||||
|
||||
关系有两种类型：
|
||||
|
||||
| 关系类型 | 描述 | 是否有外键？ |
|
||||
| ------------- | ------------------- | ------------------- |
|
||||
| `MANY_TO_ONE` | 该对象的多条记录指向目标对象的一条记录 | 是（`joinColumnName`） |
|
||||
| `ONE_TO_MANY` | 该对象的一条记录拥有目标对象的多条记录 | 否（反向侧） |
|
||||
|
||||
#### 关系如何工作
|
||||
|
||||
每个关系都需要两个相互引用的字段：
|
||||
|
||||
1. **MANY_TO_ONE** 侧——位于持有外键的对象上
|
||||
2. **ONE_TO_MANY** 侧——位于拥有集合的对象上
|
||||
|
||||
两个字段都使用 `FieldType.RELATION`，并通过 `relationTargetFieldMetadataUniversalIdentifier` 相互交叉引用。
|
||||
|
||||
#### 示例：Post Card 拥有多个收件人
|
||||
|
||||
假设一个 `PostCard` 可以发送到多个 `PostCardRecipient` 记录。 每个收件人只隶属于一张 Post Card。
|
||||
|
||||
**步骤 1：在 PostCard 上定义 ONE_TO_MANY 侧**（“一”侧）：
|
||||
|
||||
```ts src/fields/post-card-recipients-on-post-card.field.ts
|
||||
import { defineField, FieldType, RelationType } from 'twenty-sdk/define';
|
||||
import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
|
||||
import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
|
||||
|
||||
// Export so the other side can reference it
|
||||
export const POST_CARD_RECIPIENTS_FIELD_ID = 'a1111111-1111-1111-1111-111111111111';
|
||||
// Import from the other side
|
||||
import { POST_CARD_FIELD_ID } from './post-card-on-post-card-recipient.field';
|
||||
|
||||
export default defineField({
|
||||
universalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
|
||||
objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
|
||||
type: FieldType.RELATION,
|
||||
name: 'postCardRecipients',
|
||||
label: 'Post Card Recipients',
|
||||
icon: 'IconUsers',
|
||||
relationTargetObjectMetadataUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
|
||||
relationTargetFieldMetadataUniversalIdentifier: POST_CARD_FIELD_ID,
|
||||
universalSettings: {
|
||||
relationType: RelationType.ONE_TO_MANY,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
**步骤 2：在 PostCardRecipient 上定义 MANY_TO_ONE 侧**（“多”侧——持有外键）：
|
||||
|
||||
```ts src/fields/post-card-on-post-card-recipient.field.ts
|
||||
import { defineField, FieldType, RelationType, OnDeleteAction } from 'twenty-sdk/define';
|
||||
import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
|
||||
import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
|
||||
|
||||
// Export so the other side can reference it
|
||||
export const POST_CARD_FIELD_ID = 'b2222222-2222-2222-2222-222222222222';
|
||||
// Import from the other side
|
||||
import { POST_CARD_RECIPIENTS_FIELD_ID } from './post-card-recipients-on-post-card.field';
|
||||
|
||||
export default defineField({
|
||||
universalIdentifier: POST_CARD_FIELD_ID,
|
||||
objectUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
|
||||
type: FieldType.RELATION,
|
||||
name: 'postCard',
|
||||
label: 'Post Card',
|
||||
icon: 'IconMail',
|
||||
relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
|
||||
relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
|
||||
universalSettings: {
|
||||
relationType: RelationType.MANY_TO_ONE,
|
||||
onDelete: OnDeleteAction.CASCADE,
|
||||
joinColumnName: 'postCardId',
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
<Note>
|
||||
\*\*循环导入：\*\*两个关系字段相互引用彼此的 `universalIdentifier`。 为避免循环导入问题，请在各自文件中将字段 ID 作为具名常量导出，并在另一个文件中导入它们。 构建系统会在编译时解析这些引用。
|
||||
</Note>
|
||||
|
||||
#### 与标准对象建立关系
|
||||
|
||||
要与内置的 Twenty 对象（Person、Company 等）建立关系，请使用 `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS`：
|
||||
|
||||
```ts src/fields/person-on-self-hosting-user.field.ts
|
||||
import {
|
||||
defineField,
|
||||
FieldType,
|
||||
RelationType,
|
||||
OnDeleteAction,
|
||||
STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
|
||||
} from 'twenty-sdk/define';
|
||||
import { SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER } from '../objects/self-hosting-user.object';
|
||||
|
||||
export const PERSON_FIELD_ID = 'c3333333-3333-3333-3333-333333333333';
|
||||
export const SELF_HOSTING_USER_REVERSE_FIELD_ID = 'd4444444-4444-4444-4444-444444444444';
|
||||
|
||||
export default defineField({
|
||||
universalIdentifier: PERSON_FIELD_ID,
|
||||
objectUniversalIdentifier: SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER,
|
||||
type: FieldType.RELATION,
|
||||
name: 'person',
|
||||
label: 'Person',
|
||||
description: 'Person matching with the self hosting user',
|
||||
isNullable: true,
|
||||
relationTargetObjectMetadataUniversalIdentifier:
|
||||
STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier,
|
||||
relationTargetFieldMetadataUniversalIdentifier: SELF_HOSTING_USER_REVERSE_FIELD_ID,
|
||||
universalSettings: {
|
||||
relationType: RelationType.MANY_TO_ONE,
|
||||
onDelete: OnDeleteAction.SET_NULL,
|
||||
joinColumnName: 'personId',
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
#### 关系字段属性
|
||||
|
||||
| 属性 | 必填 | 描述 |
|
||||
| ------------------------------------------------- | ---------------- | -------------------------------------------------------------- |
|
||||
| `类型` | 是 | 必须为 `FieldType.RELATION` |
|
||||
| `relationTargetObjectMetadataUniversalIdentifier` | 是 | 目标对象的 `universalIdentifier` |
|
||||
| `relationTargetFieldMetadataUniversalIdentifier` | 是 | 目标对象上匹配字段的 `universalIdentifier` |
|
||||
| `universalSettings.relationType` | 是 | `RelationType.MANY_TO_ONE` 或 `RelationType.ONE_TO_MANY` |
|
||||
| `universalSettings.onDelete` | 仅适用于 MANY_TO_ONE | 当被引用的记录被删除时的处理方式：`CASCADE`、`SET_NULL`、`RESTRICT` 或 `NO_ACTION` |
|
||||
| `universalSettings.joinColumnName` | 仅适用于 MANY_TO_ONE | 外键的数据库列名（例如，`postCardId`） |
|
||||
|
||||
#### 在 defineObject 中内联关系字段
|
||||
|
||||
你也可以直接在 `defineObject()` 内定义关系字段。 在这种情况下，省略 `objectUniversalIdentifier`——它会从父对象继承：
|
||||
|
||||
```ts
|
||||
export default defineObject({
|
||||
universalIdentifier: '...',
|
||||
nameSingular: 'postCardRecipient',
|
||||
// ...
|
||||
fields: [
|
||||
{
|
||||
universalIdentifier: POST_CARD_FIELD_ID,
|
||||
type: FieldType.RELATION,
|
||||
name: 'postCard',
|
||||
label: 'Post Card',
|
||||
relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
|
||||
relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
|
||||
universalSettings: {
|
||||
relationType: RelationType.MANY_TO_ONE,
|
||||
onDelete: OnDeleteAction.CASCADE,
|
||||
joinColumnName: 'postCardId',
|
||||
},
|
||||
},
|
||||
// ... other fields
|
||||
],
|
||||
});
|
||||
```
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Scaffolding entities with `yarn twenty add`
|
||||
|
||||
Instead of creating entity files by hand, you can use the interactive scaffolder:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty add
|
||||
```
|
||||
|
||||
This prompts you to pick an entity type and walks you through the required fields. It generates a ready-to-use file with a stable `universalIdentifier` and the correct `defineEntity()` call.
|
||||
|
||||
You can also pass the entity type directly to skip the first prompt:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty add object
|
||||
yarn twenty add logicFunction
|
||||
yarn twenty add frontComponent
|
||||
```
|
||||
|
||||
### 可用的实体类型
|
||||
|
||||
| 实体类型 | 命令 | Generated file |
|
||||
| --------------- | ------------------------------------ | ------------------------------------------------------- |
|
||||
| 对象 | `yarn twenty add object` | `src/objects/\<name>.ts` |
|
||||
| 字段 | `yarn twenty add field` | `src/fields/\<name>.ts` |
|
||||
| Logic function | `yarn twenty add logicFunction` | `src/logic-functions/\<name>.ts` |
|
||||
| Front component | `yarn twenty add frontComponent` | `src/front-components/\<name>.tsx` |
|
||||
| 角色 | `yarn twenty add role` | `src/roles/\<name>.ts` |
|
||||
| 技能 | `yarn twenty add skill` | `src/skills/\<name>.ts` |
|
||||
| 代理 | `yarn twenty add agent` | `src/agents/\<name>.ts` |
|
||||
| 视图 | `yarn twenty add view` | `src/views/\<name>.ts` |
|
||||
| 导航菜单项 | `yarn twenty add navigationMenuItem` | `src/navigation-menu-items/\<name>.ts` |
|
||||
| 页面布局 | `yarn twenty add pageLayout` | `src/page-layouts/\<name>.ts` |
|
||||
|
||||
### 脚手架生成的内容
|
||||
|
||||
每种实体类型都有其自己的模板。 例如，`yarn twenty add object` 会询问：
|
||||
|
||||
1. **名称（单数）**——例如，`invoice`
|
||||
2. **名称（复数）**——例如，`invoices`
|
||||
3. **标签（单数）**——根据名称自动填充（例如，`Invoice`）
|
||||
4. **标签（复数）**——自动填充（例如，`Invoices`）
|
||||
5. **创建视图和导航项？**——如果你选择是，脚手架还会为新对象生成相应的视图和侧边栏链接。
|
||||
|
||||
其他实体类型的提示更简单——大多只会询问名称。
|
||||
|
||||
`field` 实体类型更为详细：它会询问字段名称、标签、类型（从所有可用字段类型列表中选择，如 `TEXT`、`NUMBER`、`SELECT`、`RELATION` 等），以及目标对象的 `universalIdentifier`。
|
||||
|
||||
### 自定义输出路径
|
||||
|
||||
使用 `--path` 标志将生成的文件放置在自定义位置：
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty add logicFunction --path src/custom-folder
|
||||
```
|
||||
@@ -0,0 +1,419 @@
|
||||
---
|
||||
title: 前端组件
|
||||
description: Build React components that render inside Twenty's UI with sandboxed isolation.
|
||||
icon: window-maximize
|
||||
---
|
||||
|
||||
前端组件是直接在 Twenty 的 UI 内渲染的 React 组件。 它们在使用 Remote DOM 的**隔离 Web Worker**中运行——你的代码在沙盒中执行，但会原生渲染到页面中，而非在 iframe 里。
|
||||
|
||||
## 前端组件可用位置
|
||||
|
||||
在 Twenty 中，前端组件可在两个位置进行渲染：
|
||||
|
||||
* **侧边栏** — 非无头的前端组件会在右侧侧边栏中打开。 当前端组件从命令菜单触发时，这是默认行为。
|
||||
* **小部件（仪表盘和记录页面）** — 前端组件可以作为小部件嵌入页面布局中。 在配置仪表盘或记录页面布局时，用户可以添加前端组件小部件。
|
||||
|
||||
## 基础示例
|
||||
|
||||
最快体验前端组件运行方式的方法是将其注册为一个**命令**。 添加一个 `command` 字段并设置 `isPinned: true`，即可让它以快速操作按钮的形式出现在页面右上角——无需页面布局：
|
||||
|
||||
```tsx src/front-components/hello-world.tsx
|
||||
import { defineFrontComponent } from 'twenty-sdk/define';
|
||||
|
||||
const HelloWorld = () => {
|
||||
return (
|
||||
<div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
|
||||
<h1>Hello from my app!</h1>
|
||||
<p>This component renders inside Twenty.</p>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
export default defineFrontComponent({
|
||||
universalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
|
||||
name: 'hello-world',
|
||||
description: 'A simple front component',
|
||||
component: HelloWorld,
|
||||
command: {
|
||||
universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
|
||||
shortLabel: 'Hello',
|
||||
label: 'Hello World',
|
||||
icon: 'IconBolt',
|
||||
isPinned: true,
|
||||
availabilityType: 'GLOBAL',
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
使用 `yarn twenty dev` 同步后（或单次运行 `yarn twenty dev --once`），快速操作会出现在页面右上角：
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/quick-action.png" alt="右上角的快速操作按钮" />
|
||||
</div>
|
||||
|
||||
点击它以内联方式渲染该组件。
|
||||
|
||||
## 配置字段
|
||||
|
||||
| 字段 | 必填 | 描述 |
|
||||
| --------------------- | -- | ----------------------------------------------------------------------------------- |
|
||||
| `universalIdentifier` | 是 | 该组件的稳定唯一 ID |
|
||||
| `component` | 是 | 一个 React 组件函数 |
|
||||
| `name` | 否 | 显示名称 |
|
||||
| `描述` | 否 | 组件的功能描述 |
|
||||
| `isHeadless` | 否 | Set to `true` if the component has no visible UI (see below) |
|
||||
| `命令` | 否 | Register the component as a command (see [command options](#command-options) below) |
|
||||
|
||||
## Placing a front component on a page
|
||||
|
||||
Beyond commands, you can embed a front component directly into a record page by adding it as a widget in a **page layout**. See the [definePageLayout](/l/zh/developers/extend/apps/skills-and-agents#definepagelayout) section for details.
|
||||
|
||||
## 无头与非无头
|
||||
|
||||
前端组件有两种由 `isHeadless` 选项控制的渲染模式：
|
||||
|
||||
**非无头（默认）** — 该组件会渲染可见的 UI。 从命令菜单触发时，它会在侧边栏中打开。 当 `isHeadless` 为 `false` 或被省略时，这是默认行为。
|
||||
|
||||
**无头 (`isHeadless: true`)** — 该组件会在后台以不可见的方式挂载。 它不会打开侧边栏。 无头组件旨在用于执行逻辑后自行卸载的操作——例如运行异步任务、导航到某个页面或显示确认模态框。 它们与下文介绍的 SDK Command 组件天然契合。
|
||||
|
||||
```tsx src/front-components/sync-tracker.tsx
|
||||
import { defineFrontComponent } from 'twenty-sdk/define';
|
||||
import { useRecordId, enqueueSnackbar } from 'twenty-sdk/front-component';
|
||||
import { useEffect } from 'react';
|
||||
|
||||
const SyncTracker = () => {
|
||||
const recordId = useRecordId();
|
||||
|
||||
useEffect(() => {
|
||||
enqueueSnackbar({ message: `Tracking record ${recordId}`, variant: 'info' });
|
||||
}, [recordId]);
|
||||
|
||||
return null;
|
||||
};
|
||||
|
||||
export default defineFrontComponent({
|
||||
universalIdentifier: '...',
|
||||
name: 'sync-tracker',
|
||||
description: 'Tracks record views silently',
|
||||
isHeadless: true,
|
||||
component: SyncTracker,
|
||||
});
|
||||
```
|
||||
|
||||
Because the component returns `null`, Twenty skips rendering a container for it — no empty space appears in the layout. The component still has access to all hooks and the host communication API.
|
||||
|
||||
## SDK Command 组件
|
||||
|
||||
`twenty-sdk` 包提供了四个为无头前端组件设计的 Command 辅助组件。 每个组件都会在挂载时执行一个操作，通过显示 snackbar 通知来处理错误，并在完成后自动卸载该前端组件。
|
||||
|
||||
从 `twenty-sdk/command` 导入它们：
|
||||
|
||||
* **`Command`** — 通过 `execute` 属性运行异步回调。
|
||||
* **`CommandLink`** — 导航到某个应用路径。 属性：`to`、`params`、`queryParams`、`options`。
|
||||
* **`CommandModal`** — 打开一个确认模态框。 如果用户确认，则执行 `execute` 回调。 属性：`title`、`subtitle`、`execute`、`confirmButtonText`、`confirmButtonAccent`。
|
||||
* **`CommandOpenSidePanelPage`** — 打开特定的侧边栏页面。 属性：`page`、`pageTitle`、`pageIcon`。
|
||||
|
||||
下面是一个完整示例：无头前端组件使用 `Command` 从命令菜单运行一个操作：
|
||||
|
||||
```tsx src/front-components/run-action.tsx
|
||||
import { defineFrontComponent } from 'twenty-sdk/define';
|
||||
import { Command } from 'twenty-sdk/command';
|
||||
import { CoreApiClient } from 'twenty-sdk/clients';
|
||||
|
||||
const RunAction = () => {
|
||||
const execute = async () => {
|
||||
const client = new CoreApiClient();
|
||||
|
||||
await client.mutation({
|
||||
createTask: {
|
||||
__args: { data: { title: 'Created by my app' } },
|
||||
id: true,
|
||||
},
|
||||
});
|
||||
};
|
||||
|
||||
return <Command execute={execute} />;
|
||||
};
|
||||
|
||||
export default defineFrontComponent({
|
||||
universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
|
||||
name: 'run-action',
|
||||
description: 'Creates a task from the command menu',
|
||||
component: RunAction,
|
||||
isHeadless: true,
|
||||
command: {
|
||||
universalIdentifier: 'f6a7b8c9-d0e1-2345-fabc-456789012345',
|
||||
label: 'Run my action',
|
||||
icon: 'IconPlayerPlay',
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
另一个示例：使用 `CommandModal` 在执行前请求确认：
|
||||
|
||||
```tsx src/front-components/delete-draft.tsx
|
||||
import { defineFrontComponent } from 'twenty-sdk/define';
|
||||
import { CommandModal } from 'twenty-sdk/command';
|
||||
|
||||
const DeleteDraft = () => {
|
||||
const execute = async () => {
|
||||
// perform the deletion
|
||||
};
|
||||
|
||||
return (
|
||||
<CommandModal
|
||||
title="Delete draft?"
|
||||
subtitle="This action cannot be undone."
|
||||
execute={execute}
|
||||
confirmButtonText="Delete"
|
||||
confirmButtonAccent="danger"
|
||||
/>
|
||||
);
|
||||
};
|
||||
|
||||
export default defineFrontComponent({
|
||||
universalIdentifier: 'a7b8c9d0-e1f2-3456-abcd-567890123456',
|
||||
name: 'delete-draft',
|
||||
description: 'Deletes a draft with confirmation',
|
||||
component: DeleteDraft,
|
||||
isHeadless: true,
|
||||
command: {
|
||||
universalIdentifier: 'b8c9d0e1-f2a3-4567-bcde-678901234567',
|
||||
label: 'Delete draft',
|
||||
icon: 'IconTrash',
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## Accessing runtime context
|
||||
|
||||
Inside your component, use SDK hooks to access the current user, record, and component instance:
|
||||
|
||||
```tsx src/front-components/record-info.tsx
|
||||
import { defineFrontComponent } from 'twenty-sdk/define';
|
||||
import {
|
||||
useUserId,
|
||||
useRecordId,
|
||||
useFrontComponentId,
|
||||
} from 'twenty-sdk/front-component';
|
||||
|
||||
const RecordInfo = () => {
|
||||
const userId = useUserId();
|
||||
const recordId = useRecordId();
|
||||
const componentId = useFrontComponentId();
|
||||
|
||||
return (
|
||||
<div>
|
||||
<p>User: {userId}</p>
|
||||
<p>Record: {recordId ?? 'No record context'}</p>
|
||||
<p>Component: {componentId}</p>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
export default defineFrontComponent({
|
||||
universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
|
||||
name: 'record-info',
|
||||
component: RecordInfo,
|
||||
});
|
||||
```
|
||||
|
||||
Available hooks:
|
||||
|
||||
| 钩子 | Returns | 描述 |
|
||||
| --------------------------------------------- | ------------------ | ---------------------------------------------------------- |
|
||||
| `useUserId()` | `string` or `null` | The current user's ID |
|
||||
| `useRecordId()` | `string` or `null` | The current record's ID (when placed on a record page) |
|
||||
| `useFrontComponentId()` | `string` | This component instance's ID |
|
||||
| `useFrontComponentExecutionContext(selector)` | 因情况而异 | Access the full execution context with a selector function |
|
||||
|
||||
## Host communication API
|
||||
|
||||
Front components can trigger navigation, modals, and notifications using functions from `twenty-sdk`:
|
||||
|
||||
| 函数 | 描述 |
|
||||
| ----------------------------------------------- | ----------------------------- |
|
||||
| `navigate(to, params?, queryParams?, options?)` | Navigate to a page in the app |
|
||||
| `openSidePanelPage(params)` | Open a side panel |
|
||||
| `closeSidePanel()` | 关闭侧边栏 |
|
||||
| `openCommandConfirmationModal(params)` | Show a confirmation dialog |
|
||||
| `enqueueSnackbar(params)` | Show a toast notification |
|
||||
| `unmountFrontComponent()` | Unmount the component |
|
||||
| `updateProgress(progress)` | Update a progress indicator |
|
||||
|
||||
下面是一个示例，使用宿主 API 在操作完成后显示一条 snackbar 并关闭侧边栏：
|
||||
|
||||
```tsx src/front-components/archive-record.tsx
|
||||
import { defineFrontComponent } from 'twenty-sdk/define';
|
||||
import { useRecordId } from 'twenty-sdk/front-component';
|
||||
import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
|
||||
import { CoreApiClient } from 'twenty-sdk/clients';
|
||||
|
||||
const ArchiveRecord = () => {
|
||||
const recordId = useRecordId();
|
||||
|
||||
const handleArchive = async () => {
|
||||
const client = new CoreApiClient();
|
||||
|
||||
await client.mutation({
|
||||
updateTask: {
|
||||
__args: { id: recordId, data: { status: 'ARCHIVED' } },
|
||||
id: true,
|
||||
},
|
||||
});
|
||||
|
||||
await enqueueSnackbar({
|
||||
message: 'Record archived',
|
||||
variant: 'success',
|
||||
});
|
||||
|
||||
await closeSidePanel();
|
||||
};
|
||||
|
||||
return (
|
||||
<div style={{ padding: '20px' }}>
|
||||
<p>Archive this record?</p>
|
||||
<button onClick={handleArchive}>Archive</button>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
export default defineFrontComponent({
|
||||
universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
|
||||
name: 'archive-record',
|
||||
description: 'Archives the current record',
|
||||
component: ArchiveRecord,
|
||||
});
|
||||
```
|
||||
|
||||
## Command options
|
||||
|
||||
Adding a `command` field to `defineFrontComponent` registers the component in the command menu (Cmd+K). If `isPinned` is `true`, it also appears as a quick-action button in the top-right corner of the page.
|
||||
|
||||
| 字段 | 必填 | 描述 |
|
||||
| --------------------------------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `universalIdentifier` | 是 | Stable unique ID for the command |
|
||||
| `标签` | 是 | Full label shown in the command menu (Cmd+K) |
|
||||
| `shortLabel` | 否 | Shorter label displayed on the pinned quick-action button |
|
||||
| `图标` | 否 | Icon name displayed next to the label (e.g. `'IconBolt'`, `'IconSend'`) |
|
||||
| `isPinned` | 否 | When `true`, shows the command as a quick-action button in the top-right corner of the page |
|
||||
| `availabilityType` | 否 | Controls where the command appears: `'GLOBAL'` (always available), `'RECORD_SELECTION'` (only when records are selected), or `'FALLBACK'` (shown when no other commands match) |
|
||||
| `availabilityObjectUniversalIdentifier` | 否 | Restrict the command to pages of a specific object type (e.g. only on Company records) |
|
||||
| `conditionalAvailabilityExpression` | 否 | A boolean expression to dynamically control whether the command is visible (see below) |
|
||||
|
||||
## Conditional availability expressions
|
||||
|
||||
The `conditionalAvailabilityExpression` field lets you control when a command is visible based on the current page context. Import typed variables and operators from `twenty-sdk` to build expressions:
|
||||
|
||||
```tsx
|
||||
import { defineFrontComponent } from 'twenty-sdk/define';
|
||||
import {
|
||||
pageType,
|
||||
numberOfSelectedRecords,
|
||||
objectPermissions,
|
||||
everyEquals,
|
||||
isDefined,
|
||||
} from 'twenty-sdk/front-component';
|
||||
|
||||
export default defineFrontComponent({
|
||||
universalIdentifier: '...',
|
||||
name: 'bulk-action',
|
||||
component: BulkAction,
|
||||
command: {
|
||||
universalIdentifier: '...',
|
||||
label: 'Bulk Update',
|
||||
availabilityType: 'RECORD_SELECTION',
|
||||
conditionalAvailabilityExpression: everyEquals(
|
||||
objectPermissions,
|
||||
'canUpdateObjectRecords',
|
||||
true,
|
||||
),
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
**Context variables** — these represent the current state of the page:
|
||||
|
||||
| 变量 | 类型 | 描述 |
|
||||
| ------------------------------ | --------- | ---------------------------------------------------------------- |
|
||||
| `pageType` | `string` | Current page type (e.g. `'RecordIndexPage'`, `'RecordShowPage'`) |
|
||||
| `isInSidePanel` | `boolean` | Whether the component is rendered in a side panel |
|
||||
| `numberOfSelectedRecords` | `数字` | Number of currently selected records |
|
||||
| `isSelectAll` | `boolean` | Whether "select all" is active |
|
||||
| `selectedRecords` | `array` | The selected record objects |
|
||||
| `favoriteRecordIds` | `array` | IDs of favorited records |
|
||||
| `objectPermissions` | `对象` | Permissions for the current object type |
|
||||
| `targetObjectReadPermissions` | `对象` | Read permissions for the target object |
|
||||
| `targetObjectWritePermissions` | `对象` | Write permissions for the target object |
|
||||
| `featureFlags` | `对象` | Active feature flags |
|
||||
| `objectMetadataItem` | `对象` | Metadata of the current object type |
|
||||
| `hasAnySoftDeleteFilterOnView` | `boolean` | Whether the current view has a soft-delete filter |
|
||||
|
||||
**Operators** — combine variables into boolean expressions:
|
||||
|
||||
| Operator | 描述 |
|
||||
| ----------------------------------- | ----------------------------------------------------------------- |
|
||||
| `isDefined(value)` | `true` if the value is not null/undefined |
|
||||
| `isNonEmptyString(value)` | `true` if the value is a non-empty string |
|
||||
| `includes(array, value)` | `true` if the array contains the value |
|
||||
| `includesEvery(array, prop, value)` | `true` if every item's property includes the value |
|
||||
| `every(array, prop)` | `true` if the property is truthy on every item |
|
||||
| `everyDefined(array, prop)` | `true` if the property is defined on every item |
|
||||
| `everyEquals(array, prop, value)` | `true` if the property equals the value on every item |
|
||||
| `some(array, prop)` | `true` if the property is truthy on at least one item |
|
||||
| `someDefined(array, prop)` | `true` if the property is defined on at least one item |
|
||||
| `someEquals(array, prop, value)` | `true` if the property equals the value on at least one item |
|
||||
| `someNonEmptyString(array, prop)` | `true` if the property is a non-empty string on at least one item |
|
||||
| `none(array, prop)` | `true` if the property is falsy on every item |
|
||||
| `noneDefined(array, prop)` | `true` if the property is undefined on every item |
|
||||
| `noneEquals(array, prop, value)` | `true` if the property does not equal the value on any item |
|
||||
|
||||
## Public assets
|
||||
|
||||
Front components can access files from the app's `public/` directory using `getPublicAssetUrl`:
|
||||
|
||||
```tsx
|
||||
import { defineFrontComponent, getPublicAssetUrl } from 'twenty-sdk/define';
|
||||
|
||||
const Logo = () => <img src={getPublicAssetUrl('logo.png')} alt="Logo" />;
|
||||
|
||||
export default defineFrontComponent({
|
||||
universalIdentifier: '...',
|
||||
name: 'logo',
|
||||
component: Logo,
|
||||
});
|
||||
```
|
||||
|
||||
See the [public assets section](/l/zh/developers/extend/apps/cli-and-testing#public-assets-public-folder) for details.
|
||||
|
||||
## 样式
|
||||
|
||||
Front components support multiple styling approaches. You can use:
|
||||
|
||||
* **Inline styles** — `style={{ color: 'red' }}`
|
||||
* **Twenty UI components** — import from `twenty-sdk/ui` (Button, Tag, Status, Chip, Avatar, and more)
|
||||
* **Emotion** — CSS-in-JS with `@emotion/react`
|
||||
* **Styled-components** — `styled.div` patterns
|
||||
* **Tailwind CSS** — utility classes
|
||||
* **Any CSS-in-JS library** compatible with React
|
||||
|
||||
```tsx
|
||||
import { defineFrontComponent } from 'twenty-sdk/define';
|
||||
import { Button, Tag, Status } from 'twenty-sdk/ui';
|
||||
|
||||
const StyledWidget = () => {
|
||||
return (
|
||||
<div style={{ padding: '16px', display: 'flex', gap: '8px' }}>
|
||||
<Button title="Click me" onClick={() => alert('Clicked!')} />
|
||||
<Tag text="Active" color="green" />
|
||||
<Status color="green" text="Online" />
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
export default defineFrontComponent({
|
||||
universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-567890123456',
|
||||
name: 'styled-widget',
|
||||
component: StyledWidget,
|
||||
});
|
||||
```
|
||||
@@ -1,13 +1,12 @@
|
||||
---
|
||||
title: 开始使用
|
||||
icon: rocket
|
||||
description: 几分钟内创建你的第一个 Twenty 应用。
|
||||
---
|
||||
|
||||
<Warning>
|
||||
应用目前处于 Alpha 阶段。 该功能可用，但仍在演进中。
|
||||
</Warning>
|
||||
## 什么是应用？
|
||||
|
||||
应用可通过自定义对象、字段、逻辑函数、AI 技能和 UI 组件来扩展 Twenty——全部以代码进行管理。
|
||||
应用可通过自定义对象、字段、逻辑函数、前端组件、AI 技能等来扩展 Twenty——全部以代码进行管理。 无需通过 UI 配置所有内容，你可以用 TypeScript 定义数据模型和逻辑，并将其部署到一个或多个工作空间。
|
||||
|
||||
## 先决条件
|
||||
|
||||
@@ -17,7 +16,9 @@ description: 几分钟内创建你的第一个 Twenty 应用。
|
||||
* **Yarn 4** — 通过 Corepack 随 Node.js 提供。 通过运行 `corepack enable` 启用它
|
||||
* **Docker** — [在此下载](https://www.docker.com/products/docker-desktop/)。 运行本地 Twenty 实例所必需。 如果你已经有一个正在运行的 Twenty 服务器，则不需要。
|
||||
|
||||
## 步骤 1：为你的应用创建脚手架
|
||||
## 创建你的第一个应用
|
||||
|
||||
### 为你的应用创建脚手架
|
||||
|
||||
打开终端并运行：
|
||||
|
||||
@@ -29,18 +30,7 @@ npx create-twenty-app@latest my-twenty-app
|
||||
|
||||
这会创建一个名为 `my-twenty-app` 的新文件夹，其中包含你所需的一切。
|
||||
|
||||
<Note>
|
||||
脚手架工具支持以下标志：
|
||||
|
||||
* `--minimal` — 仅创建必要文件，不包含示例（默认）
|
||||
* `--exhaustive` — 创建所有示例实体
|
||||
* `--name <name>` — 设置应用名称（跳过提示）
|
||||
* `--display-name <displayName>` — 设置显示名称（跳过提示）
|
||||
* `--description <description>` — 设置描述（跳过提示）
|
||||
* `--skip-local-instance` — 跳过本地服务器设置提示
|
||||
</Note>
|
||||
|
||||
## 步骤 2：设置本地 Twenty 实例
|
||||
### 设置本地 Twenty 实例
|
||||
|
||||
脚手架工具会询问：
|
||||
|
||||
@@ -53,7 +43,7 @@ npx create-twenty-app@latest my-twenty-app
|
||||
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="是否启动本地实例？" />
|
||||
</div>
|
||||
|
||||
## 步骤 3：登录你的工作区
|
||||
### 登录你的工作区
|
||||
|
||||
接下来，将打开一个浏览器窗口，显示 Twenty 登录页面。 使用预置的演示账户登录：
|
||||
|
||||
@@ -64,7 +54,7 @@ npx create-twenty-app@latest my-twenty-app
|
||||
<img src="/images/docs/developers/extends/apps/login.png" alt="Twenty 登录界面" />
|
||||
</div>
|
||||
|
||||
## 步骤 4：授权该应用
|
||||
### 授权该应用
|
||||
|
||||
登录后，你会看到一个授权界面。 这使你的应用可以与工作区交互。
|
||||
|
||||
@@ -80,7 +70,7 @@ npx create-twenty-app@latest my-twenty-app
|
||||
<img src="/images/docs/developers/extends/apps/scaffolded.png" alt="应用脚手架创建成功" />
|
||||
</div>
|
||||
|
||||
## 步骤 5：开始开发
|
||||
### 开始开发
|
||||
|
||||
进入你的新应用文件夹并启动开发服务器：
|
||||
|
||||
@@ -105,7 +95,22 @@ yarn twenty dev --verbose
|
||||
<img src="/images/docs/developers/extends/apps/dev.jpg" alt="开发模式终端输出" />
|
||||
</div>
|
||||
|
||||
## 步骤 6：在 Twenty 中查看你的应用
|
||||
#### 使用 `yarn twenty dev --once` 进行一次性同步
|
||||
|
||||
如果不希望有监视器在后台运行（例如在 CI 流水线、git 钩子或脚本化工作流中），请传入 `--once` 标志。 它运行与 `yarn twenty dev` 相同的流水线 — 构建清单、打包文件、上传、同步、重新生成类型化 API 客户端 — 但会在**同步完成后立即退出**：
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty dev --once
|
||||
```
|
||||
|
||||
| 命令 | 行为 | 适用场景 |
|
||||
| ------------------------ | ----------------------------------------- | -------------------------------------- |
|
||||
| `yarn twenty dev` | 监视你的源文件，并在每次更改时重新同步。 会持续运行，直到你停止它。 | 交互式本地开发 — 你需要实时状态面板和即时反馈循环。 |
|
||||
| `yarn twenty dev --once` | 执行一次构建与同步，然后在成功时以代码 `0` 退出，失败时以代码 `1` 退出。 | 脚本、CI、pre-commit 钩子、AI 代理，以及任何非交互式工作流。 |
|
||||
|
||||
两种模式都需要一个以开发模式运行的 Twenty 服务器和一个已认证的远程端 — 相同的先决条件同样适用。
|
||||
|
||||
### 在 Twenty 中查看你的应用
|
||||
|
||||
在浏览器中打开 [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer)。 前往 **设置 > 应用**，并选择 **开发者** 选项卡。 你应当在 **你的应用** 下看到你的应用：
|
||||
|
||||
@@ -133,13 +138,28 @@ yarn twenty dev --verbose
|
||||
|
||||
一切就绪！ 编辑 `src/` 中的任意文件，更改会被自动检测到。
|
||||
|
||||
前往[构建应用](/l/zh/developers/extend/apps/building)，查看关于创建对象、逻辑函数、前端组件、技能等的详细指南。
|
||||
---
|
||||
|
||||
## 你可以构建的内容
|
||||
|
||||
应用由**实体**组成——每个实体定义为一个包含单一 `export default` 的 TypeScript 文件：
|
||||
|
||||
| 实体 | 作用 |
|
||||
| ---------- | ------------------------------------------- |
|
||||
| **对象与字段** | 使用类型化字段定义自定义数据模型（如 Post Card、Invoice） |
|
||||
| **逻辑函数** | 由 HTTP 路由、cron 调度或数据库事件触发的服务端 TypeScript 函数 |
|
||||
| **前端组件** | 在 Twenty 的 UI 内渲染的 React 组件（侧边面板、小部件、命令菜单） |
|
||||
| **技能与智能体** | AI 能力——可复用的指令和自主助手 |
|
||||
| **视图与导航** | 为你的对象预配置的列表视图和侧边栏菜单项 |
|
||||
| **页面布局** | 带有选项卡和小部件的自定义记录详情页 |
|
||||
|
||||
前往[构建应用](/l/zh/developers/extend/apps/building)，查看每种实体类型的详细指南。
|
||||
|
||||
---
|
||||
|
||||
## 项目结构
|
||||
|
||||
脚手架工具会生成以下文件结构（以 `--exhaustive` 模式展示，其中包含每种实体类型的示例）：
|
||||
脚手架工具会生成以下文件结构：
|
||||
|
||||
```text filename="my-twenty-app/"
|
||||
my-twenty-app/
|
||||
@@ -148,231 +168,82 @@ my-twenty-app/
|
||||
.gitignore
|
||||
.nvmrc
|
||||
.yarnrc.yml
|
||||
.yarn/
|
||||
install-state.gz
|
||||
.oxlintrc.json
|
||||
tsconfig.json
|
||||
tsconfig.spec.json # TypeScript config for tests
|
||||
vitest.config.ts # Vitest test runner configuration
|
||||
tsconfig.spec.json # TypeScript config for tests
|
||||
vitest.config.ts # Vitest test runner configuration
|
||||
LLMS.md
|
||||
README.md
|
||||
.github/
|
||||
└── workflows/
|
||||
└── ci.yml # GitHub Actions CI workflow
|
||||
public/ # Public assets (images, fonts, etc.)
|
||||
└── ci.yml # GitHub Actions CI workflow
|
||||
public/ # Public assets (images, fonts, etc.)
|
||||
src/
|
||||
├── application-config.ts # Required — main application configuration
|
||||
├── __tests__/
|
||||
│ ├── setup-test.ts # Test setup (server health check, config)
|
||||
│ └── app-install.integration-test.ts # Example integration test
|
||||
├── 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
|
||||
│ ├── create-hello-world-company.ts # Example logic function using CoreApiClient
|
||||
│ ├── pre-install.ts # Runs before installation
|
||||
│ └── post-install.ts # Runs after installation
|
||||
├── front-components/
|
||||
│ └── hello-world.tsx # Example front component
|
||||
├── page-layouts/
|
||||
│ └── example-record-page-layout.ts # Example page layout with 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
|
||||
└── agents/
|
||||
└── example-agent.ts # Example AI agent definition
|
||||
├── application-config.ts # Required — main application configuration
|
||||
├── default-role.ts # Default role for logic functions
|
||||
├── constants/
|
||||
│ └── universal-identifiers.ts # Auto-generated UUIDs and app metadata
|
||||
└── __tests__/
|
||||
├── setup-test.ts # Test setup (server health check, config)
|
||||
└── app-install.integration-test.ts # Integration test
|
||||
```
|
||||
|
||||
默认情况下（`--minimal`），仅创建核心文件：`application-config.ts`、`roles/default-role.ts`、`logic-functions/pre-install.ts` 和 `logic-functions/post-install.ts`。 使用 `--exhaustive` 可包含上面展示的所有示例文件。
|
||||
### 从示例开始
|
||||
|
||||
若要从一个更完整的示例开始（包含自定义对象、字段、逻辑函数、前端组件等），请使用 `--example` 标志：
|
||||
|
||||
```bash filename="Terminal"
|
||||
npx create-twenty-app@latest my-twenty-app --example postcard
|
||||
```
|
||||
|
||||
示例来自 GitHub 上的 [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples) 目录。 你也可以使用 `yarn twenty add` 为现有项目生成单个实体的脚手架（参见[构建应用](/l/zh/developers/extend/apps/building#scaffolding-entities-with-yarn-twenty-add)）。
|
||||
|
||||
### 关键文件
|
||||
|
||||
| 文件 / 文件夹 | 目的 |
|
||||
| ---------------------------- | ------------------------------------------------------------------ |
|
||||
| `package.json` | 声明应用的名称、版本和依赖。 包含一个 `twenty` 脚本，因此你可以运行 `yarn twenty help` 查看所有命令。 |
|
||||
| `src/application-config.ts` | **必需。** 应用的主配置文件。 |
|
||||
| `src/roles/` | 定义角色，用于控制逻辑函数的访问权限。 |
|
||||
| `src/logic-functions/` | 由路由、cron 调度或数据库事件触发的服务端函数。 |
|
||||
| `src/front-components/` | 在 Twenty 的 UI 中渲染的 React 组件。 |
|
||||
| `src/objects/` | 用于扩展数据模型的自定义对象定义。 |
|
||||
| `src/fields/` | 添加到现有对象的自定义字段。 |
|
||||
| `src/views/` | 已保存的视图配置。 |
|
||||
| `src/navigation-menu-items/` | 侧边栏导航中的自定义链接。 |
|
||||
| `src/skills/` | 用于扩展 Twenty 的 AI 代理的技能. |
|
||||
| `src/agents/` | 具有自定义提示词的 AI 智能体。 |
|
||||
| `src/page-layouts/` | 记录视图的自定义页面布局。 |
|
||||
| `src/__tests__/` | 集成测试（设置 + 示例测试）。 |
|
||||
| `public/` | 随应用一起提供的静态资源（图像、字体）。 |
|
||||
| 文件 / 文件夹 | 目的 |
|
||||
| ---------------------------------------- | ------------------------------------------------------------------ |
|
||||
| `package.json` | 声明应用的名称、版本和依赖。 包含一个 `twenty` 脚本，因此你可以运行 `yarn twenty help` 查看所有命令。 |
|
||||
| `src/application-config.ts` | **必需。** 应用的主配置文件。 |
|
||||
| `src/default-role.ts` | 默认角色，用于控制你的逻辑函数可访问的内容。 |
|
||||
| `src/constants/universal-identifiers.ts` | 自动生成的 UUID 和应用元数据（显示名称、描述）。 |
|
||||
| `src/__tests__/` | 集成测试（设置 + 示例测试）。 |
|
||||
| `public/` | 随应用一起提供的静态资源（图像、字体）。 |
|
||||
|
||||
## 管理远程
|
||||
## 本地开发服务器
|
||||
|
||||
“远程”是指你的应用连接到的 Twenty 服务器。 在设置期间，脚手架工具会为你自动创建一个。 你可以随时添加更多远程或在它们之间切换。
|
||||
脚手架工具已经为你启动了一个本地 Twenty 服务器。 稍后要进行管理，请使用 `yarn twenty server`：
|
||||
|
||||
```bash filename="Terminal"
|
||||
# Add a new remote (opens a browser for OAuth login)
|
||||
yarn twenty remote add
|
||||
| 命令 | 描述 |
|
||||
| -------------------------------------- | -------------------- |
|
||||
| `yarn twenty server start` | 启动本地服务器（按需拉取镜像） |
|
||||
| `yarn twenty server start --port 3030` | 在自定义端口启动 |
|
||||
| `yarn twenty server start --test` | 在 2021 端口启动一个独立的测试实例 |
|
||||
| `yarn twenty server stop` | 停止服务器（保留数据） |
|
||||
| `yarn twenty server status` | 显示服务器状态、URL 和凭据 |
|
||||
| `yarn twenty server logs` | 流式输出服务器日志 |
|
||||
| `yarn twenty server logs --lines 100` | 显示最近 100 行日志 |
|
||||
| `yarn twenty server reset` | 删除所有数据并全新开始 |
|
||||
|
||||
# Connect to a local Twenty server (auto-detects port 2020 or 3000)
|
||||
yarn twenty remote add --local
|
||||
数据在重启后会保留，存储于两个 Docker 卷中（`twenty-app-dev-data` 用于 PostgreSQL，`twenty-app-dev-storage` 用于文件）。 使用 `reset` 清空所有内容并重新开始。
|
||||
|
||||
# Add a remote non-interactively (useful for CI)
|
||||
yarn twenty remote add --api-url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as my-remote
|
||||
### 运行测试实例
|
||||
|
||||
# List all configured remotes
|
||||
yarn twenty remote list
|
||||
向任何 `server` 命令传递 `--test` 以管理第二个、完全隔离的实例——这对于运行集成测试或在不影响主开发数据的情况下进行试验非常有用。
|
||||
|
||||
# Switch the active remote
|
||||
yarn twenty remote switch <name>
|
||||
```
|
||||
| 命令 | 描述 |
|
||||
| ---------------------------------- | ------------------- |
|
||||
| `yarn twenty server start --test` | 启动测试实例 (默认端口为 2021) |
|
||||
| `yarn twenty server stop --test` | 停止测试实例 |
|
||||
| `yarn twenty server status --test` | 显示测试实例状态、URL 和凭据 |
|
||||
| `yarn twenty server logs --test` | 流式输出测试实例日志 |
|
||||
| `yarn twenty server reset --test` | 清除测试数据并全新开始 |
|
||||
|
||||
你的凭据存储在 `~/.twenty/config.json` 中。
|
||||
|
||||
## 本地开发服务器（`yarn twenty server`）
|
||||
|
||||
CLI 可以管理在 Docker 中运行的本地 Twenty 服务器。 这与使用 `create-twenty-app` 搭建应用时自动启动的服务器相同，但你也可以手动管理它。
|
||||
|
||||
### 启动服务器
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty server start
|
||||
```
|
||||
|
||||
这将拉取 `twentycrm/twenty-app-dev:latest` Docker 镜像（如果尚未存在），创建名为 `twenty-app-dev` 的容器，并在端口 **2020** 上启动它。 CLI 会等待服务器通过健康检查后再返回。
|
||||
|
||||
会创建两个 Docker 卷，以在重启之间持久化数据：
|
||||
|
||||
* `twenty-app-dev-data` — PostgreSQL 数据库
|
||||
* `twenty-app-dev-storage` — 文件存储
|
||||
|
||||
如果端口 2020 已被占用，你可以在其他端口上启动：
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty server start --port 3030
|
||||
```
|
||||
|
||||
CLI 会自动配置容器内部的 `NODE_PORT` 和 `SERVER_URL` 以匹配所选端口，从而使逻辑函数、OAuth 以及所有其他内部网络正常工作。
|
||||
|
||||
启动后，该服务器会在你的 CLI 配置中自动注册为 `local` 远程。
|
||||
|
||||
### 检查服务器状态
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty server status
|
||||
```
|
||||
|
||||
显示服务器是否在运行、其 URL，以及默认登录凭据（`tim@apple.dev` / `tim@apple.dev`）。
|
||||
|
||||
### 查看服务器日志
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty server logs
|
||||
```
|
||||
|
||||
持续输出容器日志。 使用 `--lines` 控制显示的最近日志行数：
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty server logs --lines 100
|
||||
```
|
||||
|
||||
### 停止服务器
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty server stop
|
||||
```
|
||||
|
||||
停止容器。 你的数据会保存在 Docker 卷中——下次 `start` 会从上次中断处继续。
|
||||
|
||||
### 重置服务器
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty server reset
|
||||
```
|
||||
|
||||
移除容器并删除这两个 Docker 卷，清除所有数据。 下一次 `start` 会创建一个全新实例。
|
||||
测试实例在其独立的 Docker 容器 (`twenty-app-dev-test`) 中运行，配有专用的卷 (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`) 和配置，因此可以与主实例并行运行且不会发生冲突。 将 `--test` 与 `--port` 一起使用以覆盖默认的 2021 端口。
|
||||
|
||||
<Note>
|
||||
服务器需要 Docker 处于运行状态。 如果看到 "Docker not running" 错误，请确保 Docker Desktop（或 Docker 守护进程）已启动。
|
||||
</Note>
|
||||
|
||||
### 命令参考
|
||||
|
||||
| 命令 | 描述 |
|
||||
| -------------------------------------- | --------------- |
|
||||
| `yarn twenty server start` | 启动本地服务器（按需拉取镜像） |
|
||||
| `yarn twenty server start --port 3030` | 在自定义端口启动 |
|
||||
| `yarn twenty server stop` | 停止服务器（保留数据） |
|
||||
| `yarn twenty server status` | 显示服务器状态、URL 和凭据 |
|
||||
| `yarn twenty server logs` | 流式输出服务器日志 |
|
||||
| `yarn twenty server logs --lines 100` | 显示最近 100 行日志 |
|
||||
| `yarn twenty server reset` | 删除所有数据并全新开始 |
|
||||
|
||||
## 使用 GitHub Actions 进行 CI
|
||||
|
||||
脚手架工具会在 `.github/workflows/ci.yml` 生成一个开箱即用的 GitHub Actions 工作流。 它会在每次向 `main` 推送以及拉取请求上自动运行你的集成测试。
|
||||
|
||||
工作流：
|
||||
|
||||
1. 检出你的代码
|
||||
2. 使用 `twentyhq/twenty/.github/actions/spawn-twenty-docker-image` 动作启动一个临时的 Twenty 服务器
|
||||
3. 使用 `yarn install --immutable` 安装依赖
|
||||
4. 运行 `yarn test`，并从该动作的输出中注入 `TWENTY_API_URL` 和 `TWENTY_API_KEY`
|
||||
|
||||
```yaml .github/workflows/ci.yml
|
||||
name: CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
pull_request: {}
|
||||
|
||||
env:
|
||||
TWENTY_VERSION: latest
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Spawn Twenty instance
|
||||
id: twenty
|
||||
uses: twentyhq/twenty/.github/actions/spawn-twenty-docker-image@main
|
||||
with:
|
||||
twenty-version: ${{ env.TWENTY_VERSION }}
|
||||
github-token: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
- name: Enable Corepack
|
||||
run: corepack enable
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version-file: '.nvmrc'
|
||||
cache: 'yarn'
|
||||
|
||||
- name: Install dependencies
|
||||
run: yarn install --immutable
|
||||
|
||||
- name: Run integration tests
|
||||
run: yarn test
|
||||
env:
|
||||
TWENTY_API_URL: ${{ steps.twenty.outputs.server-url }}
|
||||
TWENTY_API_KEY: ${{ steps.twenty.outputs.access-token }}
|
||||
```
|
||||
|
||||
你无需配置任何机密——`spawn-twenty-docker-image` 动作会在运行器中直接启动一个临时的 Twenty 服务器，并输出连接详情。 GitHub 会自动提供 `GITHUB_TOKEN` 机密。
|
||||
|
||||
若要固定为特定的 Twenty 版本而不是 `latest`，请在工作流顶部修改 `TWENTY_VERSION` 环境变量。
|
||||
|
||||
## 手动设置（不使用脚手架）
|
||||
|
||||
如果你不想使用 `create-twenty-app`，而是自行完成设置，可以分两步进行。
|
||||
|
||||
@@ -0,0 +1,131 @@
|
||||
---
|
||||
title: 布局
|
||||
description: Define views, navigation menu items, and page layouts to shape how your app appears in Twenty.
|
||||
icon: table-columns
|
||||
---
|
||||
|
||||
Layout entities control how your app surfaces inside Twenty's UI — what lives in the sidebar, which saved views ship with the app, and how a record detail page is arranged.
|
||||
|
||||
## Layout concepts
|
||||
|
||||
| Concept | What it controls | 实体 |
|
||||
| ------------------------ | --------------------------------------------------------------------------------- | -------------------------- |
|
||||
| **View** | A saved list configuration for an object — visible fields, order, filters, groups | `defineView` |
|
||||
| **Navigation Menu Item** | An entry in the left sidebar that links to a view or an external URL | `defineNavigationMenuItem` |
|
||||
| **Page Layout** | The tabs and widgets that make up a record's detail page | `definePageLayout` |
|
||||
|
||||
Views, navigation items, and page layouts reference each other by `universalIdentifier`:
|
||||
|
||||
* A **navigation menu item** of type `VIEW` points at a `defineView` identifier, so the sidebar link opens that saved view.
|
||||
* A **page layout** of type `RECORD_PAGE` targets an object and can embed [front components](/l/zh/developers/extend/apps/front-components) inside its tabs as widgets.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="defineView" description="为对象定义已保存的视图">
|
||||
|
||||
Views are saved configurations for how records of an object are displayed — including which fields are visible, their order, and any filters or groups applied. Use `defineView()` to ship pre-configured views with your app:
|
||||
|
||||
```ts src/views/example-view.ts
|
||||
import { defineView, ViewKey } from 'twenty-sdk/define';
|
||||
import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
|
||||
import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
|
||||
|
||||
export default defineView({
|
||||
universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
|
||||
name: 'All example items',
|
||||
objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
|
||||
icon: 'IconList',
|
||||
key: ViewKey.INDEX,
|
||||
position: 0,
|
||||
fields: [
|
||||
{
|
||||
universalIdentifier: 'f926bdb7-6af7-4683-9a09-adbca56c29f0',
|
||||
fieldMetadataUniversalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER,
|
||||
position: 0,
|
||||
isVisible: true,
|
||||
size: 200,
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
关键点：
|
||||
* `objectUniversalIdentifier` specifies which object this view applies to.
|
||||
* `key` determines the view type (e.g., `ViewKey.INDEX` for the main list view).
|
||||
* `fields` controls which columns appear and their order. Each field references a `fieldMetadataUniversalIdentifier`.
|
||||
* You can also define `filters`, `filterGroups`, `groups`, and `fieldGroups` for more advanced configurations.
|
||||
* `position` controls the ordering when multiple views exist for the same object.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="defineNavigationMenuItem" description="定义侧边栏导航链接">
|
||||
|
||||
Navigation menu items add custom entries to the workspace sidebar. Use `defineNavigationMenuItem()` to link to views, external URLs, or objects:
|
||||
|
||||
```ts src/navigation-menu-items/example-navigation-menu-item.ts
|
||||
import { defineNavigationMenuItem, NavigationMenuItemType } from 'twenty-sdk/define';
|
||||
import { EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER } from '../views/example-view';
|
||||
|
||||
export default defineNavigationMenuItem({
|
||||
universalIdentifier: '9327db91-afa1-41b6-bd9d-2b51a26efb4c',
|
||||
name: 'example-navigation-menu-item',
|
||||
icon: 'IconList',
|
||||
color: 'blue',
|
||||
position: 0,
|
||||
type: NavigationMenuItemType.VIEW,
|
||||
viewUniversalIdentifier: EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER,
|
||||
});
|
||||
```
|
||||
|
||||
关键点：
|
||||
* `type` determines what the menu item links to: `NavigationMenuItemType.VIEW` for a saved view, or `NavigationMenuItemType.LINK` for an external URL.
|
||||
* For view links, set `viewUniversalIdentifier`. For external links, set `link`.
|
||||
* `position` controls the ordering in the sidebar.
|
||||
* `icon` and `color` (optional) customize the appearance.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="definePageLayout" description="Define custom page layouts for record views">
|
||||
|
||||
Page layouts let you customize how a record detail page looks — which tabs appear, what widgets are inside each tab, and how they are arranged. Use `definePageLayout()` to ship custom layouts with your app:
|
||||
|
||||
```ts src/page-layouts/example-record-page-layout.ts
|
||||
import { definePageLayout, PageLayoutTabLayoutMode } from 'twenty-sdk/define';
|
||||
import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
|
||||
import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';
|
||||
|
||||
export default definePageLayout({
|
||||
universalIdentifier: '203aeb94-6701-46d6-9af1-be2bbcc9e134',
|
||||
name: 'Example Record Page',
|
||||
type: 'RECORD_PAGE',
|
||||
objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
|
||||
tabs: [
|
||||
{
|
||||
universalIdentifier: '6ed26b60-a51d-4ad7-86dd-1c04c7f3cac5',
|
||||
title: 'Hello World',
|
||||
position: 50,
|
||||
icon: 'IconWorld',
|
||||
layoutMode: PageLayoutTabLayoutMode.CANVAS,
|
||||
widgets: [
|
||||
{
|
||||
universalIdentifier: 'aa4234e0-2e5f-4c02-a96a-573449e2351d',
|
||||
title: 'Hello World',
|
||||
type: 'FRONT_COMPONENT',
|
||||
configuration: {
|
||||
configurationType: 'FRONT_COMPONENT',
|
||||
frontComponentUniversalIdentifier:
|
||||
HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
关键点：
|
||||
* `type` is typically `'RECORD_PAGE'` to customize the detail view of a specific object.
|
||||
* `objectUniversalIdentifier` specifies which object this layout applies to.
|
||||
* Each `tab` defines a section of the page with a `title`, `position`, and `layoutMode` (`CANVAS` for free-form layout).
|
||||
* Each `widget` inside a tab can render a front component, a relation list, or other built-in widget types.
|
||||
* `position` on tabs controls their order. Use higher values (e.g., 50) to place custom tabs after built-in ones.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@@ -0,0 +1,560 @@
|
||||
---
|
||||
title: 逻辑函数
|
||||
description: Define server-side TypeScript functions with HTTP, cron, and database event triggers.
|
||||
icon: bolt
|
||||
---
|
||||
|
||||
Logic functions are server-side TypeScript functions that run on the Twenty platform. They can be triggered by HTTP requests, cron schedules, or database events — and can also be exposed as tools for AI agents.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="defineLogicFunction" description="定义逻辑函数及其触发器">
|
||||
|
||||
每个函数文件都使用 `defineLogicFunction()` 导出包含处理程序和可选触发器的配置。
|
||||
|
||||
```ts src/logic-functions/createPostCard.logic-function.ts
|
||||
import { defineLogicFunction } from 'twenty-sdk/define';
|
||||
import type { DatabaseEventPayload, ObjectRecordCreateEvent, CronPayload, RoutePayload } from 'twenty-sdk/define';
|
||||
import { CoreApiClient, type Person } from 'twenty-client-sdk/core';
|
||||
|
||||
const handler = async (params: RoutePayload) => {
|
||||
const client = new CoreApiClient();
|
||||
const name = 'name' in params.queryStringParameters
|
||||
? params.queryStringParameters.name ?? process.env.DEFAULT_RECIPIENT_NAME ?? 'Hello world'
|
||||
: 'Hello world';
|
||||
|
||||
const result = await client.mutation({
|
||||
createPostCard: {
|
||||
__args: { data: { name } },
|
||||
id: true,
|
||||
name: true,
|
||||
},
|
||||
});
|
||||
return result;
|
||||
};
|
||||
|
||||
export default defineLogicFunction({
|
||||
universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
|
||||
name: 'create-new-post-card',
|
||||
timeoutSeconds: 2,
|
||||
handler,
|
||||
httpRouteTriggerSettings: {
|
||||
path: '/post-card/create',
|
||||
httpMethod: 'GET',
|
||||
isAuthRequired: true,
|
||||
},
|
||||
/*databaseEventTriggerSettings: {
|
||||
eventName: 'people.created',
|
||||
},*/
|
||||
/*cronTriggerSettings: {
|
||||
pattern: '0 0 1 1 *',
|
||||
},*/
|
||||
});
|
||||
```
|
||||
|
||||
可用的触发器类型：
|
||||
* **httpRoute**：在 **`/s/` 端点**下通过 HTTP 路径和方法公开你的函数：
|
||||
> 例如 `path: '/post-card/create'` 可在 `https://your-twenty-server.com/s/post-card/create` 调用
|
||||
* **cron**：使用 CRON 表达式按计划运行你的函数。
|
||||
* **databaseEvent**：在工作空间对象生命周期事件上运行。 当事件操作为 `updated` 时，可以在 `updatedFields` 数组中指定要监听的特定字段。 如果未定义或为空，任何更新都会触发该函数。
|
||||
> 例如 `person.updated`、`*.created`、`company.*`
|
||||
|
||||
<Note>
|
||||
你也可以使用 CLI 手动执行函数：
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty exec -n create-new-post-card -p '{"key": "value"}'
|
||||
```
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty exec -y e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf
|
||||
```
|
||||
|
||||
你可以通过以下方式查看日志：
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty logs
|
||||
```
|
||||
</Note>
|
||||
|
||||
#### 路由触发器负载
|
||||
|
||||
当路由触发器调用你的逻辑函数时，它会接收一个遵循
|
||||
[AWS HTTP API v2 格式](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html)的 `RoutePayload` 对象。
|
||||
从 `twenty-sdk` 导入 `RoutePayload` 类型：
|
||||
|
||||
```ts
|
||||
import { defineLogicFunction, type RoutePayload } from 'twenty-sdk/define';
|
||||
|
||||
const handler = async (event: RoutePayload) => {
|
||||
const { headers, queryStringParameters, pathParameters, body } = event;
|
||||
const { method, path } = event.requestContext.http;
|
||||
|
||||
return { message: 'Success' };
|
||||
};
|
||||
```
|
||||
|
||||
`RoutePayload` 类型具有以下结构：
|
||||
|
||||
| 属性 | 类型 | 描述 | 示例 |
|
||||
| ---------------------------- | ------------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------- |
|
||||
| `headers` | `Record\<string, string \| undefined>` | HTTP 请求头（仅限 `forwardedRequestHeaders` 中列出的那些） | 见下文 |
|
||||
| `queryStringParameters` | `Record\<string, string \| undefined>` | 查询字符串参数（多个值以逗号连接） | `/users?ids=1&ids=2&ids=3&name=Alice` -> `{ ids: '1,2,3', name: 'Alice' }` |
|
||||
| `pathParameters` | `Record\<string, string \| undefined>` | 从路由模式中提取的路径参数 | `/users/:id`，`/users/123` -> `{ id: '123' }` |
|
||||
| `body` | `object \| null` | 已解析的请求体（JSON） | `{ id: 1 }` -> `{ id: 1 }` |
|
||||
| `isBase64Encoded` | `boolean` | 请求体是否为 base64 编码 | |
|
||||
| `requestContext.http.method` | `string` | HTTP 方法（GET、POST、PUT、PATCH、DELETE） | |
|
||||
| `requestContext.http.path` | `string` | 原始请求路径 | |
|
||||
|
||||
|
||||
#### forwardedRequestHeaders
|
||||
|
||||
出于安全原因，默认**不会**将传入请求的 HTTP 请求头传递给你的逻辑函数。
|
||||
如需访问特定请求头，请在 `forwardedRequestHeaders` 数组中显式列出：
|
||||
|
||||
```ts
|
||||
export default defineLogicFunction({
|
||||
universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
|
||||
name: 'webhook-handler',
|
||||
handler,
|
||||
httpRouteTriggerSettings: {
|
||||
path: '/webhook',
|
||||
httpMethod: 'POST',
|
||||
isAuthRequired: false,
|
||||
forwardedRequestHeaders: ['x-webhook-signature', 'content-type'],
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
在你的处理程序中，可以这样访问被转发的请求头：
|
||||
|
||||
```ts
|
||||
const handler = async (event: RoutePayload) => {
|
||||
const signature = event.headers['x-webhook-signature'];
|
||||
const contentType = event.headers['content-type'];
|
||||
|
||||
// Validate webhook signature...
|
||||
return { received: true };
|
||||
};
|
||||
```
|
||||
|
||||
<Note>
|
||||
请求头名称会被规范化为小写。 请使用小写键访问它们（例如，`event.headers['content-type']`）。
|
||||
</Note>
|
||||
|
||||
#### 将函数作为工具公开
|
||||
|
||||
逻辑函数可以作为供 AI 智能体和工作流使用的**工具**对外提供。 当函数被标记为工具时，Twenty 的 AI 功能即可发现它，并可在工作流自动化中使用。
|
||||
|
||||
要将逻辑函数标记为工具，请设置 `isTool: true`：
|
||||
|
||||
```ts src/logic-functions/enrich-company.logic-function.ts
|
||||
import { defineLogicFunction } from 'twenty-sdk/define';
|
||||
import { CoreApiClient } from 'twenty-client-sdk/core';
|
||||
|
||||
const handler = async (params: { companyName: string; domain?: string }) => {
|
||||
const client = new CoreApiClient();
|
||||
|
||||
const result = await client.mutation({
|
||||
createTask: {
|
||||
__args: {
|
||||
data: {
|
||||
title: `Enrich data for ${params.companyName}`,
|
||||
body: `Domain: ${params.domain ?? 'unknown'}`,
|
||||
},
|
||||
},
|
||||
id: true,
|
||||
},
|
||||
});
|
||||
|
||||
return { taskId: result.createTask.id };
|
||||
};
|
||||
|
||||
export default defineLogicFunction({
|
||||
universalIdentifier: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
|
||||
name: 'enrich-company',
|
||||
description: 'Enrich a company record with external data',
|
||||
timeoutSeconds: 10,
|
||||
handler,
|
||||
isTool: true,
|
||||
});
|
||||
```
|
||||
|
||||
关键点：
|
||||
|
||||
* 你可以将 `isTool` 与触发器结合使用——一个函数既可以作为工具（由 AI 智能体调用），也可以同时由事件触发。
|
||||
* **`toolInputSchema`**（可选）：描述函数可接受参数的 JSON Schema 对象。 该模式会通过对源代码的静态分析自动推导，但你也可以显式设置：
|
||||
|
||||
```ts
|
||||
export default defineLogicFunction({
|
||||
...,
|
||||
toolInputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
companyName: {
|
||||
type: 'string',
|
||||
description: 'The name of the company to enrich',
|
||||
},
|
||||
domain: {
|
||||
type: 'string',
|
||||
description: 'The company website domain (optional)',
|
||||
},
|
||||
},
|
||||
required: ['companyName'],
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
<Note>
|
||||
**写一个好的 `description`。** AI 智能体会依赖该函数的 `description` 字段来决定何时使用该工具。 明确说明该工具的作用以及应在何时调用。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="definePostInstallLogicFunction" description="定义一个安装后逻辑函数（每个应用一个）">
|
||||
|
||||
安装后函数是在你的应用安装到工作区后自动运行的逻辑函数。 服务器会在应用的元数据已同步并已生成 SDK 客户端**之后**执行它，因此工作区已完全可用，且新架构已就绪。 常见用例包括预置默认数据、创建初始记录、配置工作区设置，或在第三方服务上预配资源。
|
||||
|
||||
```ts src/logic-functions/post-install.ts
|
||||
import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
|
||||
|
||||
const handler = async (payload: InstallPayload): Promise<void> => {
|
||||
console.log('Post install logic function executed successfully!', payload.previousVersion);
|
||||
};
|
||||
|
||||
export default definePostInstallLogicFunction({
|
||||
universalIdentifier: 'f7a2b9c1-3d4e-5678-abcd-ef9876543210',
|
||||
name: 'post-install',
|
||||
description: 'Runs after installation to set up the application.',
|
||||
timeoutSeconds: 300,
|
||||
shouldRunOnVersionUpgrade: false,
|
||||
shouldRunSynchronously: false,
|
||||
handler,
|
||||
});
|
||||
```
|
||||
|
||||
你也可以随时使用 CLI 手动执行安装后函数：
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty exec --postInstall
|
||||
```
|
||||
|
||||
关键点：
|
||||
* 安装后函数使用 `definePostInstallLogicFunction()` —— 这是一个省略触发器设置（`cronTriggerSettings`、`databaseEventTriggerSettings`、`httpRouteTriggerSettings`、`isTool`）的专用变体。
|
||||
* 处理程序会接收一个 `InstallPayload`，其为 `{ previousVersion?: string; newVersion: string }` —— `newVersion` 是正在安装的版本，而 `previousVersion` 是先前已安装的版本（在全新安装时为 `undefined`）。 使用这些值来区分全新安装与升级，并运行特定版本的迁移逻辑。
|
||||
* **钩子何时运行**：默认情况下，仅在全新安装时运行。 如果还希望在应用从旧版本升级时运行，请传入 `shouldRunOnVersionUpgrade: true`。 若省略，该标志默认为 `false`，升级将跳过该钩子。
|
||||
* **执行模型 — 默认异步，可选择同步**：`shouldRunSynchronously` 标志控制安装后*如何*执行。
|
||||
* `shouldRunSynchronously: false` *(默认)* — 该钩子会**加入消息队列**，设置 `retryLimit: 3`，并在工作线程中异步运行。 作业一入列，安装响应即返回，因此缓慢或失败的处理程序不会阻塞调用方。 工作线程最多会重试三次。 **将其用于长时间运行的作业**——预填充大型数据集、调用缓慢的第三方 API、预配外部资源，以及任何可能超出合理 HTTP 响应窗口的任务。
|
||||
* `shouldRunSynchronously: true` — 该钩子会在安装流程中**内联执行**（与安装前使用相同的执行器）。 安装请求将阻塞直至处理程序完成；若抛出异常，安装调用方将收到 `POST_INSTALL_ERROR`。 不进行自动重试。 **用于需要在响应前完成的快速工作**——例如向用户返回验证错误，或进行安装调用返回后客户端将立即依赖的快速设置。 请注意，运行安装后时，元数据迁移已应用完成，因此同步模式下的失败**不会**回滚架构更改——它只会暴露错误。
|
||||
* 确保你的处理程序是幂等的。 在异步模式下，队列最多可重试三次；在任一模式下，当 `shouldRunOnVersionUpgrade: true` 时，该钩子在升级时可能再次运行。
|
||||
* 在处理程序内可使用环境变量 `APPLICATION_ID`、`APP_ACCESS_TOKEN` 和 `API_URL`（与其他逻辑函数相同），因此你可以使用作用域限定到你应用的应用访问令牌调用 Twenty API。
|
||||
* 每个应用仅允许一个安装后函数。 如果检测到多个，清单构建将报错。
|
||||
* 构建期间，函数的 `universalIdentifier`、`shouldRunOnVersionUpgrade` 和 `shouldRunSynchronously` 会自动附加到应用清单的 `postInstallLogicFunction` 字段下——你无需在 `defineApplication()` 中引用它们。
|
||||
* 默认超时时间设置为 300 秒（5 分钟），以便支持更长的设置任务，如数据填充。
|
||||
* **开发模式下不执行**：当应用在本地注册（通过 `yarn twenty dev`）时，服务器会完全跳过安装流程，并通过 CLI 监视器直接同步文件——因此无论 `shouldRunSynchronously` 如何，安装后在开发模式下都不会运行。 使用 `yarn twenty exec --postInstall` 在运行中的工作区上手动触发它。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="definePreInstallLogicFunction" description="定义一个安装前逻辑函数（每个应用一个）">
|
||||
|
||||
安装前函数是在安装期间自动运行的逻辑函数，**在应用工作区元数据迁移之前**。 它与安装后共享相同的负载结构（`InstallPayload`），但在安装流程中位置更早，因此可以准备即将到来的迁移所依赖的状态——典型用例如备份数据、验证与新架构的兼容性，或归档即将被重构或删除的记录。
|
||||
|
||||
```ts src/logic-functions/pre-install.ts
|
||||
import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
|
||||
|
||||
const handler = async (payload: InstallPayload): Promise<void> => {
|
||||
console.log('Pre install logic function executed successfully!', payload.previousVersion);
|
||||
};
|
||||
|
||||
export default definePreInstallLogicFunction({
|
||||
universalIdentifier: 'a1b2c3d4-5678-90ab-cdef-1234567890ab',
|
||||
name: 'pre-install',
|
||||
description: 'Runs before installation to prepare the application.',
|
||||
timeoutSeconds: 300,
|
||||
shouldRunOnVersionUpgrade: true,
|
||||
handler,
|
||||
});
|
||||
```
|
||||
|
||||
你也可以随时使用 CLI 手动执行安装前函数：
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty exec --preInstall
|
||||
```
|
||||
|
||||
关键点：
|
||||
* 安装前函数使用 `definePreInstallLogicFunction()`——与安装后相同的专用配置，只是附加到不同的生命周期阶段。
|
||||
* 安装前和安装后处理程序接收相同的 `InstallPayload` 类型：`{ previousVersion?: string; newVersion: string }`。 导入一次，可在两个钩子中复用。
|
||||
* **钩子何时运行**：位于工作区元数据迁移（`synchronizeFromManifest`）之前。 在执行之前，服务器会运行一次纯增量的“精简同步”，将**新**版本的安装前函数注册到工作区元数据中——不会触及其他任何内容——然后再执行它。 由于此次同步仅为增量操作，当你的处理程序运行时，上一版本的对象、字段和数据仍完好无损：你可以安全地读取并备份迁移前的状态。
|
||||
* **执行模型**：安装前以**同步**方式执行，并且**会阻塞安装**。 如果处理程序抛出异常，安装会在任何架构更改应用之前被中止——工作区将保持在上一版本且处于一致状态。 这是有意为之：安装前是你拒绝高风险升级的最后机会。
|
||||
* 与安装后相同，每个应用仅允许一个安装前函数。 在构建期间，它会自动附加到应用清单的 `preInstallLogicFunction` 下。
|
||||
* **开发模式下不执行**：与安装后相同——对于本地注册的应用将完全跳过安装流程，因此在 `yarn twenty dev` 下不会运行安装前。 使用 `yarn twenty exec --preInstall` 手动触发它。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="安装前 vs 安装后：何时使用哪一个" description="选择合适的安装钩子">
|
||||
|
||||
两个钩子都属于同一安装流程，并接收相同的 `InstallPayload`。 区别在于它们相对于工作区元数据迁移**何时**运行，这会影响它们可以安全访问的数据范围。
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ install flow │
|
||||
│ │
|
||||
│ upload package → [pre-install] → metadata migration → │
|
||||
│ generate SDK → [post-install] │
|
||||
│ │
|
||||
│ old schema visible new schema visible │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
安装前始终为**同步**（会阻塞安装并可中止它）。 安装后**默认异步**——在工作线程中入列并自动重试——但可通过 `shouldRunSynchronously: true` 选择同步执行。 关于各模式的使用场景，请参见上方的 `definePostInstallLogicFunction` 折叠面板。
|
||||
|
||||
**对于需要新架构已存在的任何事项，请使用 `post-install`。** 这是最常见的情况：
|
||||
|
||||
* 针对新添加的对象和字段预填充默认数据（创建初始记录、默认视图、演示内容）。
|
||||
* 在应用已有凭据的前提下，向第三方服务注册 Webhook。
|
||||
* 调用你自己的 API 完成依赖已同步元数据的设置。
|
||||
* 用于在每次升级时对状态进行对账的幂等“确保其存在”逻辑——结合 `shouldRunOnVersionUpgrade: true` 使用。
|
||||
|
||||
示例——在安装后预填充一个默认的 `PostCard` 记录：
|
||||
|
||||
```ts src/logic-functions/post-install.ts
|
||||
import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
|
||||
import { createClient } from './generated/client';
|
||||
|
||||
const handler = async ({ previousVersion }: InstallPayload): Promise<void> => {
|
||||
if (previousVersion) return; // fresh installs only
|
||||
|
||||
const client = createClient();
|
||||
await client.postCard.create({
|
||||
data: { title: 'Welcome to Postcard', content: 'Your first card!' },
|
||||
});
|
||||
};
|
||||
|
||||
export default definePostInstallLogicFunction({
|
||||
universalIdentifier: 'f7a2b9c1-3d4e-5678-abcd-ef9876543210',
|
||||
name: 'post-install',
|
||||
description: 'Seeds a welcome post card after install.',
|
||||
timeoutSeconds: 300,
|
||||
shouldRunOnVersionUpgrade: false,
|
||||
handler,
|
||||
});
|
||||
```
|
||||
|
||||
**当迁移可能破坏或损坏现有数据时，请使用 `pre-install`。** 由于安装前在*先前*架构上运行，且其失败会回滚升级，因此凡是有风险的操作都应放在这里：
|
||||
|
||||
* **备份即将被删除或重构的数据**——例如，你在 v2 中移除某个字段，需要在迁移运行前将其值复制到另一个字段或导出到存储中。
|
||||
* **归档会被新约束判为无效的记录**——例如某个字段将变为 `NOT NULL`，你需要先删除或修正具有空值的行。
|
||||
* **验证兼容性；若当前数据无法干净迁移则拒绝升级**——从处理程序中抛出异常，安装将中止且不会应用任何更改。 这比在迁移中途才发现不兼容要更安全。
|
||||
* **在会导致关联丢失的架构更改之前**对数据进行重命名或重新设置键。
|
||||
|
||||
示例——在破坏性迁移之前归档记录：
|
||||
|
||||
```ts src/logic-functions/pre-install.ts
|
||||
import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
|
||||
import { createClient } from './generated/client';
|
||||
|
||||
const handler = async ({ previousVersion, newVersion }: InstallPayload): Promise<void> => {
|
||||
// Only the 1.x → 2.x upgrade drops the legacy `notes` field.
|
||||
if (!previousVersion?.startsWith('1.') || !newVersion.startsWith('2.')) {
|
||||
return;
|
||||
}
|
||||
|
||||
const client = createClient();
|
||||
const legacyRecords = await client.postCard.findMany({
|
||||
where: { notes: { isNotNull: true } },
|
||||
});
|
||||
|
||||
if (legacyRecords.length === 0) return;
|
||||
|
||||
// Copy legacy `notes` into the new `description` field before the migration
|
||||
// drops the `notes` column. If this fails, the upgrade is aborted and the
|
||||
// workspace stays on v1 with all data intact.
|
||||
await Promise.all(
|
||||
legacyRecords.map((record) =>
|
||||
client.postCard.update({
|
||||
where: { id: record.id },
|
||||
data: { description: record.notes },
|
||||
}),
|
||||
),
|
||||
);
|
||||
};
|
||||
|
||||
export default definePreInstallLogicFunction({
|
||||
universalIdentifier: 'a1b2c3d4-5678-90ab-cdef-1234567890ab',
|
||||
name: 'pre-install',
|
||||
description: 'Backs up legacy notes into description before the v2 migration.',
|
||||
timeoutSeconds: 300,
|
||||
shouldRunOnVersionUpgrade: true,
|
||||
handler,
|
||||
});
|
||||
```
|
||||
|
||||
**经验法则：**
|
||||
|
||||
| You want to... | 使用 |
|
||||
| ----------------------- | ------------------------------------------------------------- |
|
||||
| 预填充默认数据、配置工作区、注册外部资源 | `post-install` |
|
||||
| 运行不应阻塞安装响应的长时间预填充或第三方调用 | `post-install` (默认 — `shouldRunSynchronously: false`，由工作线程重试) |
|
||||
| 运行安装调用返回后调用方将立即依赖的快速设置 | `post-install`，配合 `shouldRunSynchronously: true` |
|
||||
| 读取或备份即将被迁移丢失的数据 | `pre-install` |
|
||||
| 拒绝会损坏现有数据的升级 | `pre-install`（从处理程序中抛出异常） |
|
||||
| 在每次升级时执行对账 | `post-install` 配合 `shouldRunOnVersionUpgrade: true` |
|
||||
| 仅在首次安装时执行一次性设置 | `post-install` 配合 `shouldRunOnVersionUpgrade: false`（默认） |
|
||||
|
||||
<Note>
|
||||
如有不确定，默认选择**安装后（post-install）**。 仅当迁移本身具有破坏性，且你需要在其丢失之前拦截先前状态时，才使用安装前。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 类型化 API 客户端（`twenty-client-sdk`）
|
||||
|
||||
`twenty-client-sdk` 包提供了两个类型化的 GraphQL 客户端，供你的逻辑函数和前端组件与 Twenty API 交互。
|
||||
|
||||
| 客户端 | 导入 | 端点 | 是否生成？ |
|
||||
| ------------------- | ---------------------------- | ------------------------ | --------- |
|
||||
| `CoreApiClient` | `twenty-client-sdk/core` | `/graphql`——工作区数据（记录、对象） | 是，在开发/构建时 |
|
||||
| `MetadataApiClient` | `twenty-client-sdk/metadata` | `/metadata`——工作区配置、文件上传 | 否，已预构建提供 |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="CoreApiClient" description="查询和变更工作区数据（记录、对象）">
|
||||
|
||||
`CoreApiClient` 是用于查询和变更工作区数据的主要客户端。 它会在执行 `yarn twenty dev` 或 `yarn twenty build` 时**根据你的工作区架构生成**，因此完全类型化以匹配你的对象和字段。
|
||||
|
||||
```ts
|
||||
import { CoreApiClient } from 'twenty-client-sdk/core';
|
||||
|
||||
const client = new CoreApiClient();
|
||||
|
||||
// Query records
|
||||
const { companies } = await client.query({
|
||||
companies: {
|
||||
edges: {
|
||||
node: {
|
||||
id: true,
|
||||
name: true,
|
||||
domainName: {
|
||||
primaryLinkLabel: true,
|
||||
primaryLinkUrl: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
// Create a record
|
||||
const { createCompany } = await client.mutation({
|
||||
createCompany: {
|
||||
__args: {
|
||||
data: {
|
||||
name: 'Acme Corp',
|
||||
},
|
||||
},
|
||||
id: true,
|
||||
name: true,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
该客户端使用选择集语法：传入 `true` 以包含某字段，使用 `__args` 传递参数，并通过嵌套对象表示关系。 你将基于工作区架构获得完整的自动补全和类型检查。
|
||||
|
||||
<Note>
|
||||
**CoreApiClient 在开发/构建时生成。** 如果在未先运行 `yarn twenty dev` 或 `yarn twenty build` 的情况下尝试使用它，将会抛出错误。 该生成过程是自动完成的——CLI 会自省你的工作区 GraphQL 架构，并使用 `@genql/cli` 生成类型化客户端。
|
||||
</Note>
|
||||
|
||||
#### 使用 CoreSchema 进行类型标注
|
||||
|
||||
`CoreSchema` 提供与工作区对象相匹配的 TypeScript 类型，可用于为组件状态或函数参数进行类型标注：
|
||||
|
||||
```ts
|
||||
import { CoreApiClient, CoreSchema } from 'twenty-client-sdk/core';
|
||||
import { useState } from 'react';
|
||||
|
||||
const [company, setCompany] = useState<
|
||||
Pick<CoreSchema.Company, 'id' | 'name'> | undefined
|
||||
>(undefined);
|
||||
|
||||
const client = new CoreApiClient();
|
||||
const result = await client.query({
|
||||
company: {
|
||||
__args: { filter: { position: { eq: 1 } } },
|
||||
id: true,
|
||||
name: true,
|
||||
},
|
||||
});
|
||||
setCompany(result.company);
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="MetadataApiClient" description="工作区配置、应用和文件上传">
|
||||
|
||||
`MetadataApiClient` 随 SDK 一并提供，已预构建（无需生成）。 它会查询 `/metadata` 端点以获取工作区配置、应用和文件上传。
|
||||
|
||||
```ts
|
||||
import { MetadataApiClient } from 'twenty-client-sdk/metadata';
|
||||
|
||||
const metadataClient = new MetadataApiClient();
|
||||
|
||||
// List first 10 objects in the workspace
|
||||
const { objects } = await metadataClient.query({
|
||||
objects: {
|
||||
edges: {
|
||||
node: {
|
||||
id: true,
|
||||
nameSingular: true,
|
||||
namePlural: true,
|
||||
labelSingular: true,
|
||||
isCustom: true,
|
||||
},
|
||||
},
|
||||
__args: {
|
||||
filter: {},
|
||||
paging: { first: 10 },
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
#### 上传文件
|
||||
|
||||
`MetadataApiClient` 包含一个 `uploadFile` 方法，用于将文件附加到文件类型字段：
|
||||
|
||||
```ts
|
||||
import { MetadataApiClient } from 'twenty-client-sdk/metadata';
|
||||
import * as fs from 'fs';
|
||||
|
||||
const metadataClient = new MetadataApiClient();
|
||||
|
||||
const fileBuffer = fs.readFileSync('./invoice.pdf');
|
||||
|
||||
const uploadedFile = await metadataClient.uploadFile(
|
||||
fileBuffer, // file contents as a Buffer
|
||||
'invoice.pdf', // filename
|
||||
'application/pdf', // MIME type
|
||||
'58a0a314-d7ea-4865-9850-7fb84e72f30b', // field universalIdentifier
|
||||
);
|
||||
|
||||
console.log(uploadedFile);
|
||||
// { id: '...', path: '...', size: 12345, createdAt: '...', url: 'https://...' }
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 描述 |
|
||||
| ---------------------------------- | -------- | -------------------------------------------- |
|
||||
| `fileBuffer` | `Buffer` | 原始文件内容 |
|
||||
| `filename` | `string` | 文件名称（用于存储和显示） |
|
||||
| `contentType` | `string` | MIME 类型（如果省略，默认为 `application/octet-stream`） |
|
||||
| `fieldMetadataUniversalIdentifier` | `string` | 你的对象上文件类型字段的 `universalIdentifier` |
|
||||
|
||||
关键点：
|
||||
* 使用字段的 `universalIdentifier`（而不是其工作区特定的 ID），因此你的上传代码可在安装了你的应用的任何工作区中运行。
|
||||
* 返回的 `url` 是一个签名 URL，你可以用它来访问已上传的文件。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
<Note>
|
||||
当你的代码在 Twenty 上运行（逻辑函数或前端组件）时，平台会以环境变量的形式注入凭据：
|
||||
|
||||
* `TWENTY_API_URL`——Twenty API 的基础 URL
|
||||
* `TWENTY_APP_ACCESS_TOKEN`——作用域限定为你的应用默认函数角色的短期密钥
|
||||
|
||||
你无需将这些值传递给客户端——它们会自动从 `process.env` 读取。 API 密钥的权限由你的 `application-config.ts` 中 `defaultRoleUniversalIdentifier` 引用的角色决定。
|
||||
</Note>
|
||||
@@ -1,12 +1,9 @@
|
||||
---
|
||||
title: 发布
|
||||
icon: 上传
|
||||
description: 将你的 Twenty 应用分发到应用市场，或进行内部部署。
|
||||
---
|
||||
|
||||
<Warning>
|
||||
应用目前处于 Alpha 阶段。 该功能可用，但仍在演进中。
|
||||
</Warning>
|
||||
|
||||
## 概览
|
||||
|
||||
一旦你的应用已[在本地构建并完成测试](/l/zh/developers/extend/apps/building)，你可以通过两种方式进行分发：
|
||||
@@ -52,7 +49,11 @@ yarn twenty deploy
|
||||
|
||||
### 共享已部署的应用
|
||||
|
||||
通过 tar 包分发的应用不会出现在公共市场中，因此同一服务器上的其他工作区无法通过浏览发现它们。 要共享已部署的应用：
|
||||
<Warning>
|
||||
在多个工作区之间共享私有（tarball）应用是一项 **Enterprise** 功能。 在您的工作区拥有有效的 Enterprise 密钥之前，**Distribution** 选项卡将显示升级提示，而不是共享控件。 请前往 [设置 > 管理面板 > Enterprise](/settings/admin-panel#enterprise) 以启用。
|
||||
</Warning>
|
||||
|
||||
通过 tar 包分发的应用不会出现在公共市场中，因此同一服务器上的其他工作区无法通过浏览发现它们。 一旦您的工作区升级到企业版计划，您就可以像这样分享已部署的应用：
|
||||
|
||||
1. 前往 **Settings > Applications > Registrations** 并打开你的应用
|
||||
2. 在 **Distribution** 选项卡中，点击 **Copy share link**
|
||||
@@ -60,20 +61,73 @@ yarn twenty deploy
|
||||
|
||||
该分享链接使用服务器的基础 URL（不包含任何工作区子域），因此适用于该服务器上的任意工作区。
|
||||
|
||||
<Warning>
|
||||
Sharing private apps is an Enterprise feature. Go to [Settings > Admin Panel > Enterprise](/settings/admin-panel#enterprise) to enable it.
|
||||
</Warning>
|
||||
|
||||
### 版本管理
|
||||
|
||||
在更新已部署的 tarball 应用时，服务器要求 `package.json` 中的 `version` 必须**严格高于**（按[语义化版本](https://semver.org)排序）当前已部署的版本。 在 tar 包存储之前，重新部署相同版本或推送更低版本都会被拒绝 — 你会在 CLI 中看到 `VERSION_ALREADY_EXISTS` 错误。
|
||||
|
||||
要发布更新：
|
||||
|
||||
1. 更新 `package.json` 中的 `version` 字段
|
||||
1. 将 `package.json` 中的 `version` 字段递增（例如：`1.2.3` → `1.2.4`、`1.3.0` 或 `2.0.0`）
|
||||
2. Run `yarn twenty deploy` (or `yarn twenty deploy --remote production`)
|
||||
3. 已安装该应用的工作区会在其设置中看到可用的升级
|
||||
|
||||
<Note>
|
||||
预发布标签按预期工作：将 `1.0.0-rc.1` 递增为 `1.0.0-rc.2` 是允许的，并且像 `1.0.0` 这样的正式发布会被正确识别为高于 `1.0.0-rc.5`。 `package.json` 中的版本本身必须是有效的 SemVer 字符串。
|
||||
</Note>
|
||||
|
||||
{/* TODO: add screenshot of the Upgrade button */}
|
||||
|
||||
## 自动化 CI/CD（脚手架生成的工作流）
|
||||
|
||||
使用 `create-twenty-app` 生成的应用开箱即带有两个 GitHub Actions 工作流，位于 `.github/workflows/`。 当你将仓库推送到 GitHub 后即可运行——CI 无需额外设置，CD 只需要一个机密。
|
||||
|
||||
### CI — `ci.yml`
|
||||
|
||||
它会在每次向 `main` 推送以及拉取请求上自动运行你的集成测试。
|
||||
|
||||
**作用:**
|
||||
|
||||
1. 检出你的应用源代码。
|
||||
2. 使用 `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main` 组合 action 启动一个隔离的 Twenty 测试实例（相当于 CI 中的 `yarn twenty server start --test`）。
|
||||
3. 启用 Corepack，从你的 `.nvmrc` 设置 Node.js，并使用 `yarn install --immutable` 安装依赖。
|
||||
4. 运行 `yarn test`，并从启动的实例传入 `TWENTY_API_URL` 和 `TWENTY_API_KEY`，以便你的测试可以与真实服务器通信。
|
||||
|
||||
**配置选项:**
|
||||
|
||||
* `TWENTY_VERSION`（环境变量，默认 `latest`）— 通过在 `ci.yml` 中编辑它来固定 CI 使用的 Twenty 服务器版本。
|
||||
* 并发按 `github.ref` 分组，并会在有新的推送时取消进行中的运行。
|
||||
|
||||
不需要任何机密——测试实例是临时的，只在作业持续期间存在。
|
||||
|
||||
### CD — `cd.yml`
|
||||
|
||||
在每次向 `main` 推送时将你的应用部署到已配置的 Twenty 服务器；当为拉取请求添加 `deploy` 标签时，也可从该拉取请求进行部署。
|
||||
|
||||
**作用:**
|
||||
|
||||
1. 检出 PR 的 head（针对已加标签的 PR），或被推送的提交。
|
||||
2. 运行 `twentyhq/twenty/.github/actions/deploy-twenty-app@main`——相当于 CI 中的 `yarn twenty deploy`。
|
||||
3. 运行 `twentyhq/twenty/.github/actions/install-twenty-app@main`，将新部署的版本安装到目标工作区。
|
||||
|
||||
**必需的配置:**
|
||||
|
||||
| 设置 | 位置 | 目的 |
|
||||
| ----------------------- | -------------------------------------------------------- | ---------------------------------------- |
|
||||
| `TWENTY_DEPLOY_URL` | `cd.yml` 中的 `env`（默认值为 `http://localhost:3000`） | 要部署到的 Twenty 服务器。 首次使用前将其更改为你真实的服务器 URL。 |
|
||||
| `TWENTY_DEPLOY_API_KEY` | GitHub 仓库 **Settings → Secrets and variables → Actions** | 在目标服务器上具有部署权限的 API 密钥。 |
|
||||
|
||||
<Note>
|
||||
默认的 `TWENTY_DEPLOY_URL` 值 `http://localhost:3000` 只是占位符——从 GitHub 托管的 runner 无法访问任何资源。 在启用 CD 之前，将其更新为你服务器的公网 URL（或使用具有网络访问权限的自托管 runner）。
|
||||
</Note>
|
||||
|
||||
**从 PR 触发预览部署:**
|
||||
|
||||
为拉取请求添加 `deploy` 标签。 在 `cd.yml` 中的 `if:` 守卫会使用该 PR 的 head 提交为其运行作业，使你能在合并前在目标服务器上验证更改。
|
||||
|
||||
### 固定可复用的 actions
|
||||
|
||||
两个工作流都引用了位于 `@main` 的可复用 actions，因此会自动获取 `twentyhq/twenty` 仓库中的 action 更新。 如果你希望构建具有确定性，请在每个 `uses:` 行中将 `@main` 替换为某个提交的 SHA 或发行标签。
|
||||
|
||||
## 发布到 npm
|
||||
|
||||
发布到 npm 可让你的应用在 Twenty 应用市场中被发现。 任何 Twenty 工作区都可以直接通过 UI 浏览、安装和升级应用市场中的应用。
|
||||
@@ -81,7 +135,7 @@ Sharing private apps is an Enterprise feature. Go to [Settings > Admin Panel > E
|
||||
### 要求
|
||||
|
||||
* 一个 [npm](https://www.npmjs.com) 账户
|
||||
* The `twenty-app` keyword in your `package.json` `keywords` array (already included when you scaffold with `create-twenty-app`)
|
||||
* 你在 `package.json` 的 `keywords` 数组中的 `twenty-app` 关键字（需要手动添加 — 在 `create-twenty-app` 模板中默认不包含）
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
@@ -189,3 +243,12 @@ You can also install apps from the command line:
|
||||
```bash filename="Terminal"
|
||||
yarn twenty install
|
||||
```
|
||||
|
||||
<Note>
|
||||
服务器在安装时强制执行 SemVer 版本控制，与部署时的规则一致：
|
||||
|
||||
* 尝试安装与工作区中已安装版本相同的版本将被拒绝，并返回 `APP_ALREADY_INSTALLED` 错误。
|
||||
* 尝试安装低于当前已安装版本的版本将被拒绝，并返回 `CANNOT_DOWNGRADE_APPLICATION` 错误。
|
||||
|
||||
若要安装较新的版本，请先部署或发布它，然后重新运行 `yarn twenty install`。
|
||||
</Note>
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: 技能与智能体
|
||||
description: Define AI skills and agents for your app.
|
||||
icon: robot
|
||||
---
|
||||
|
||||
<Warning>
|
||||
Skills and agents are currently in alpha. 该功能可用，但仍在演进中。
|
||||
</Warning>
|
||||
|
||||
Apps can define AI capabilities that live inside the workspace — reusable skill instructions and agents with custom system prompts.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="defineSkill" description="定义 AI 智能体技能">
|
||||
|
||||
技能定义了可复用的指令和能力，AI 智能体可在你的工作区中使用。 使用 `defineSkill()` 定义带内置校验的技能：
|
||||
|
||||
```ts src/skills/example-skill.ts
|
||||
import { defineSkill } from 'twenty-sdk/define';
|
||||
|
||||
export default defineSkill({
|
||||
universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
|
||||
name: 'sales-outreach',
|
||||
label: 'Sales Outreach',
|
||||
description: 'Guides the AI agent through a structured sales outreach process',
|
||||
icon: 'IconBrain',
|
||||
content: `You are a sales outreach assistant. When reaching out to a prospect:
|
||||
1. Research the company and recent news
|
||||
2. Identify the prospect's role and likely pain points
|
||||
3. Draft a personalized message referencing specific details
|
||||
4. Keep the tone professional but conversational`,
|
||||
});
|
||||
```
|
||||
|
||||
关键点：
|
||||
* `name` 是该技能的唯一标识字符串（推荐使用 kebab-case）。
|
||||
* `label` 是在 UI 中显示的人类可读名称。
|
||||
* `content` 包含技能指令——这是 AI 智能体使用的文本。
|
||||
* `icon`（可选）设置在 UI 中显示的图标。
|
||||
* `description`（可选）提供有关技能用途的更多上下文。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="defineAgent" description="Define AI agents with custom prompts">
|
||||
|
||||
Agents are AI assistants that live inside your workspace. Use `defineAgent()` to create agents with a custom system prompt:
|
||||
|
||||
```ts src/agents/example-agent.ts
|
||||
import { defineAgent } from 'twenty-sdk/define';
|
||||
|
||||
export default defineAgent({
|
||||
universalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
|
||||
name: 'sales-assistant',
|
||||
label: 'Sales Assistant',
|
||||
description: 'Helps the sales team draft outreach emails and research prospects',
|
||||
icon: 'IconRobot',
|
||||
prompt: 'You are a helpful sales assistant. Help users with their questions and tasks.',
|
||||
});
|
||||
```
|
||||
|
||||
关键点：
|
||||
* `name` is the unique identifier string for the agent (kebab-case recommended).
|
||||
* `label` is the display name shown in the UI.
|
||||
* `prompt` is the system prompt that defines the agent's behavior.
|
||||
* `description` (optional) provides context about what the agent does.
|
||||
* `icon`（可选）设置在 UI 中显示的图标。
|
||||
* `modelId` (optional) overrides the default AI model used by the agent.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
Reference in New Issue
Block a user