houseassassin/twenty
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

i18n - docs translations (#20366)

Browse Source 
Created by Github action

Co-authored-by: github-actions <github-actions@twenty.com>
This commit is contained in:
github-actions[bot]
2026-05-07 18:53:27 +02:00
committed by GitHub
parent 24e64350ee
commit 95bc8aea28
175 changed files with 5164 additions and 5007 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/twenty-docs/l/zh/developers/extend/apps/getting-started/concepts.mdx
+42 -42
View File
@@ -1,14 +1,14 @@
---
title: Concepts
description: How Twenty apps work — entity model, sandboxing, and the install lifecycle.
title: 概念
description: Twenty 应用的工作方式 — 实体模型、沙盒机制和安装生命周期。
icon: sitemap
---
Twenty apps are TypeScript packages that extend your workspace with custom objects, logic, UI components, and AI capabilities. They run on the Twenty platform with full sandboxing and permission controls.
Twenty 应用是 TypeScript 包，可通过自定义对象、逻辑、UI 组件和 AI 能力扩展你的工作区。 它们在 Twenty 平台上运行，具备完备的沙盒与权限控制。
## How apps work
## 应用如何运作
An app is a collection of **entities** declared using `defineEntity()` functions from the `twenty-sdk` package. The SDK detects these declarations via AST analysis at build time and produces a **manifest** — a complete description of what your app adds to a workspace. These functions validate your configuration at build time and provide IDE autocompletion and type safety.
应用是由 `twenty-sdk` 包中的 `defineEntity()` 函数声明的**实体**集合。 SDK 在构建时通过 AST 分析检测到这些声明，并生成一份**清单**——完整描述你的应用为工作区新增的内容。 这些函数会在构建时校验你的配置，并提供 IDE 自动补全和类型安全。
```
your-app/
@@ -29,35 +29,35 @@ your-app/
```
<Note>
**File organization is up to you.** Entity detection is AST-based — the SDK finds `export default defineEntity(...)` calls regardless of where the file lives. The folder structure above is a convention, not a requirement.
**文件组织由你决定。** 实体检测基于 AST——无论文件位于何处，SDK 都能找到 `export default defineEntity(...)` 的调用。 上述文件夹结构是一种约定，而非强制要求。
</Note>
## Entity types
## 实体类型
| Entity | Purpose | Docs |
| ------------------------ | ------------------------------------------ | ----------------------------------------------------------------------------- |
| **Application** | App identity, default role, variables | [Application Config](/l/zh/developers/extend/apps/config/application) |
| **Role** | Permission sets on objects and fields | [Roles & Permissions](/l/zh/developers/extend/apps/config/roles) |
| **Object** | Custom record types with fields | [Objects](/l/zh/developers/extend/apps/data/objects) |
| **Field** | Add fields to objects from other apps | [Extending Objects](/l/zh/developers/extend/apps/data/extending-objects) |
| **Relation** | Bidirectional links between objects | [Relations](/l/zh/developers/extend/apps/data/relations) |
| **Logic Function** | Server-side TypeScript with triggers | [Logic Functions](/l/zh/developers/extend/apps/logic/logic-functions) |
| **Skill** | Reusable AI agent instructions | [Skills & Agents](/l/zh/developers/extend/apps/logic/skills-and-agents) |
| **Agent** | AI assistants with custom prompts | [Skills & Agents](/l/zh/developers/extend/apps/logic/skills-and-agents) |
| **Connection Provider** | OAuth credentials for third-party APIs | [Connections](/l/zh/developers/extend/apps/logic/connections) |
| **View** | Pre-configured record list views | [Views](/l/zh/developers/extend/apps/layout/views) |
| **Navigation Menu Item** | Custom sidebar entries | [Navigation Menu Items](/l/zh/developers/extend/apps/layout/navigation-menu-items) |
| **Page Layout** | Tabs and widgets on a record's detail page | [Page Layouts](/l/zh/developers/extend/apps/layout/page-layouts) |
| **Front Component** | Sandboxed React UI inside Twenty | [Front Components](/l/zh/developers/extend/apps/layout/front-components) |
| **Command Menu Item** | Quick actions and Cmd+K entries | [Command Menu Items](/l/zh/developers/extend/apps/layout/command-menu-items) |
| 实体 | 目的 | 文档 |
| --------- | --------------------- | ---------------------------------------------------------------- |
| **应用程序** | 应用标识、默认角色、变量 | [Application Config](/l/zh/developers/extend/apps/config/application) |
| **角色** | 对象和字段的权限集 | [角色和权限](/l/zh/developers/extend/apps/config/roles) |
| **对象** | 带字段的自定义记录类型 | [对象](/l/zh/developers/extend/apps/data/objects) |
| **字段** | 从其他应用向对象添加字段 | [扩展对象](/l/zh/developers/extend/apps/data/extending-objects) |
| **关系** | 对象之间的双向链接 | [关系](/l/zh/developers/extend/apps/data/relations) |
| **逻辑函数** | 带触发器的服务端 TypeScript | [逻辑函数](/l/zh/developers/extend/apps/logic/logic-functions) |
| **技能** | 可复用的 AI 代理指令 | [技能与代理](/l/zh/developers/extend/apps/logic/skills-and-agents) |
| **代理** | 具有自定义提示词的 AI 助手 | [技能与代理](/l/zh/developers/extend/apps/logic/skills-and-agents) |
| **连接提供方** | 用于第三方 API 的 OAuth 凭证 | [连接](/l/zh/developers/extend/apps/logic/connections) |
| **视图** | 预配置的记录列表视图 | [视图](/l/zh/developers/extend/apps/layout/views) |
| **导航菜单项** | 自定义侧边栏条目 | [导航菜单项](/l/zh/developers/extend/apps/layout/navigation-menu-items) |
| **页面布局** | 记录详情页上的选项卡和小部件 | [页面布局](/l/zh/developers/extend/apps/layout/page-layouts) |
| **前端组件** | Twenty 内的沙盒化 React UI | [前端组件](/l/zh/developers/extend/apps/layout/front-components) |
| **命令菜单项** | 快速操作和 Cmd+K 项 | [命令菜单项](/l/zh/developers/extend/apps/layout/command-menu-items) |
## Sandboxing
## 沙盒化
* **Logic functions** run in isolated Node.js processes on the server. They only access data through the typed API client, scoped to the app's role permissions.
* **Front components** run in Web Workers using Remote DOM — sandboxed from the main page but rendering native DOM elements (not iframes). They communicate with Twenty via a message-passing host API.
* **Permissions** are enforced at the API level. The runtime token (`TWENTY_APP_ACCESS_TOKEN`) is derived from the role defined in `defineApplication()`.
* **逻辑函数** 在服务器上的独立 Node.js 进程中运行。 它们只能通过类型化的 API 客户端访问数据，且范围受应用角色权限限制。
* **前端组件** 在使用 Remote DOM 的 Web Worker 中运行——与主页面沙盒隔离，但渲染原生 DOM 元素（非 iframe）。 它们通过消息传递的宿主 API 与 Twenty 通信。
* **权限** 在 API 层面强制执行。 运行时令牌（`TWENTY_APP_ACCESS_TOKEN`）源自 `defineApplication()` 中定义的角色。
## App lifecycle
## 应用生命周期
```
┌─────────────────────────────────────────────────────────┐
@@ -76,26 +76,26 @@ your-app/
└─────────────────────────────────────────────────────────┘
```
* **`yarn twenty dev`** — watches your source files and live-syncs changes to a connected Twenty server. The typed API client is regenerated automatically when the schema changes.
* **`yarn twenty build`** — compiles TypeScript, bundles logic functions and front components with esbuild, and produces a manifest.
* **Pre/post-install hooks** — optional functions that run during installation. See [Install Hooks](/l/zh/developers/extend/apps/config/install-hooks) for details.
* **`yarn twenty dev`** — 监视你的源文件，并将更改实时同步到已连接的 Twenty 服务器。 当模式发生变化时，会自动重新生成类型化的 API 客户端。
* **`yarn twenty build`** — 编译 TypeScript，使用 esbuild 打包逻辑函数和前端组件，并生成清单。
* **预/后安装钩子** — 在安装过程中运行的可选函数。 详见 [安装钩子](/l/zh/developers/extend/apps/config/install-hooks)。
## Next steps
## 后续步骤
<CardGroup cols={2}>
<Card title="Config" icon="screwdriver-wrench" href="/l/zh/developers/extend/apps/config/overview">
Application identity, default role, and install hooks.
<Card title="配置" icon="screwdriver-wrench" href="/l/zh/developers/extend/apps/config/overview">
应用标识、默认角色和安装钩子。
</Card>
<Card title="Data" icon="database" href="/l/zh/developers/extend/apps/data/overview">
Objects, fields, and bidirectional relations.
<Card title="数据" icon="database" href="/l/zh/developers/extend/apps/data/overview">
对象、字段和双向关系。
</Card>
<Card title="Logic" icon="bolt" href="/l/zh/developers/extend/apps/logic/overview">
Logic functions, skills, agents, and OAuth connections.
<Card title="逻辑" icon="bolt" href="/l/zh/developers/extend/apps/logic/overview">
逻辑函数、技能、代理和 OAuth 连接。
</Card>
<Card title="Layout" icon="table-columns" href="/l/zh/developers/extend/apps/layout/overview">
Views, navigation, page layouts, front components.
<Card title="布局" icon="table-columns" href="/l/zh/developers/extend/apps/layout/overview">
视图、导航、页面布局、前端组件。
</Card>
<Card title="Operations" icon="rocket" href="/l/zh/developers/extend/apps/operations/overview">
CLI, testing, remotes, CI, and publishing your app.
<Card title="操作" icon="rocket" href="/l/zh/developers/extend/apps/operations/overview">
CLI、测试、远程、CI，以及发布你的应用。
</Card>
</CardGroup>
packages/twenty-docs/l/zh/developers/extend/apps/getting-started/local-server.mdx
+34 -34
View File
@@ -1,61 +1,61 @@
---
title: Local Server
description: Manage the local Twenty Docker server — start, stop, upgrade, parallel test instance, and manual SDK setup.
title: 本地服务器
description: 管理本地 Twenty Docker 服务器 — 启动、停止、升级、并行测试实例，以及手动设置 SDK。
icon: server
---
## Managing the local server
## 管理本地服务器
Use `yarn twenty server` to control the local Twenty container:
使用 `yarn twenty server` 控制本地的 Twenty 容器：
| Command | What it does |
| -------------------------------------- | -------------------------------------------- |
| `yarn twenty server start` | Start the server (pulls the image if needed) |
| `yarn twenty server start --port 3030` | Start on a custom port |
| `yarn twenty server stop` | Stop the server (preserves data) |
| `yarn twenty server status` | Show URL, version, and login credentials |
| `yarn twenty server logs` | Stream server logs |
| `yarn twenty server reset` | Wipe data and start fresh |
| `yarn twenty server upgrade` | Pull the latest `twenty-app-dev` image |
| `yarn twenty server upgrade 2.2.0` | Upgrade to a specific version |
| 命令 | 作用 |
| -------------------------------------- | ------------------------- |
| `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 reset` | 清空数据并全新开始 |
| `yarn twenty server upgrade` | 拉取最新的 `twenty-app-dev` 镜像 |
| `yarn twenty server upgrade 2.2.0` | 升级到指定版本 |
Data persists across restarts in two Docker volumes (`twenty-app-dev-data` for PostgreSQL, `twenty-app-dev-storage` for files). Use `reset` to wipe everything.
数据在重启后会保留，存储于两个 Docker 卷中（`twenty-app-dev-data` 用于 PostgreSQL，`twenty-app-dev-storage` 用于文件）。 使用 `reset` 清空所有内容。
## Upgrading the server image
## 升级服务器镜像
`yarn twenty server upgrade` pulls the latest image, compares digests, and only recreates the container if anything actually changed. Volumes are preserved — only the container is replaced. If a new image was pulled and the container was running, the upgrade automatically starts a new container; run `yarn twenty server start` afterward to wait for it to become healthy.
`yarn twenty server upgrade` 将拉取最新镜像、比较摘要，并且仅在确有变更时才重新创建容器。 数据卷将被保留——只会替换容器。 如果已拉取新镜像且容器正在运行，升级会自动启动一个新容器；之后运行 `yarn twenty server start` 以等待其变为健康状态。
```bash filename="Terminal"
yarn twenty server upgrade # Latest
yarn twenty server upgrade 2.2.0 # Specific version
```
Verify the running version with `yarn twenty server status` (it shows the `APP_VERSION` baked into the container).
使用 `yarn twenty server status` 验证正在运行的版本（它会显示写入容器的 `APP_VERSION`）。
## Running a parallel test instance
## 运行并行测试实例
Pass `--test` to any `server` command to manage a second, fully isolated instance — useful for integration tests or experiments without touching your main dev data:
向任意 `server` 命令传递 `--test` 以管理第二个、完全隔离的实例——这有助于在不影响主开发数据的情况下进行集成测试或试验：
| Command | What it does |
| ----------------------------------- | ----------------------------------------------- |
| `yarn twenty server start --test` | Start the test instance (defaults to port 2021) |
| `yarn twenty server stop --test` | Stop it |
| `yarn twenty server status --test` | Show its status |
| `yarn twenty server logs --test` | Stream its logs |
| `yarn twenty server reset --test` | Wipe its data |
| `yarn twenty server upgrade --test` | Upgrade its image |
| 命令 | 作用 |
| ----------------------------------- | ------------------- |
| `yarn twenty server start --test` | 启动测试实例 (默认端口为 2021) |
| `yarn twenty server stop --test` | 停止它 |
| `yarn twenty server status --test` | 显示其状态 |
| `yarn twenty server logs --test` | 流式输出其日志 |
| `yarn twenty server reset --test` | 清空其数据 |
| `yarn twenty server upgrade --test` | 升级其镜像 |
The test instance has its own container (`twenty-app-dev-test`), volumes (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`), and config — it runs alongside your main instance without conflicts. Combine `--test` with `--port` to override 2021.
测试实例有其自己的容器（`twenty-app-dev-test`）、卷（`twenty-app-dev-test-data`、`twenty-app-dev-test-storage`）和配置——它可与你的主实例并行运行且不会发生冲突。 将 `--test` 与 `--port` 组合使用以覆盖 2021 端口。
## Manual setup (without the scaffolder)
## 手动设置（不使用脚手架）
Skip the scaffolder if you're adding the SDK to an existing project:
如果你要将 SDK 添加到现有项目中，可跳过脚手架：
```bash filename="Terminal"
yarn add twenty-sdk twenty-client-sdk
```
Add the script to `package.json`:
在 `package.json` 中添加该脚本：
```json filename="package.json"
{
@@ -65,8 +65,8 @@ Add the script to `package.json`:
}
```
You can now run `yarn twenty dev`, `yarn twenty server start`, and the rest.
现在你可以运行 `yarn twenty dev`、`yarn twenty server start`，以及其他命令。
<Note>
Don't install `twenty-sdk` globally — pin it per project so each app uses its own version.
不要全局安装 `twenty-sdk` —— 在每个项目中固定其版本，使每个应用都使用各自的版本。
</Note>
packages/twenty-docs/l/zh/developers/extend/apps/getting-started/project-structure.mdx
+12 -12
View File
@@ -1,10 +1,10 @@
---
title: Project Structure
description: What's inside a scaffolded Twenty app — files, folders, and what each one does.
title: 项目结构
description: 脚手架生成的 Twenty 应用中包含哪些内容——文件、文件夹以及它们各自的作用。
icon: folder-tree
---
A new app generated by `npx create-twenty-app` looks like this:
由 `npx create-twenty-app` 生成的新应用看起来是这样的：
```text filename="my-twenty-app/"
my-twenty-app/
@@ -25,16 +25,16 @@ my-twenty-app/
README.md, LLMS.md
```
## Key files
## 关键文件
| File / Folder | Purpose |
| ---------------------------------------- | -------------------------------------------------------------- |
| `src/application-config.ts` | **Required.** The main configuration file for your app. |
| `src/default-role.ts` | Default role controlling what your logic functions can access. |
| `src/constants/universal-identifiers.ts` | Auto-generated UUIDs and metadata (display name, description). |
| `src/__tests__/` | Integration tests (setup + example test). |
| `public/` | Static assets (images, fonts) served with your app. |
| 文件 / 文件夹 | 目的 |
| ---------------------------------------- | ------------------------- |
| `src/application-config.ts` | **必需。** 应用的主配置文件。 |
| `src/default-role.ts` | 默认角色，用于控制你的逻辑函数可访问的内容。 |
| `src/constants/universal-identifiers.ts` | 自动生成的 UUID 和元数据（显示名称、描述）。 |
| `src/__tests__/` | 集成测试（设置 + 示例测试）。 |
| `public/` | 随应用一起提供的静态资源（图像、字体）。 |
<Note>
**File organization is up to you.** The folders above are conventions — the SDK detects entities via AST analysis on `export default defineEntity(...)` calls regardless of where the file lives.
**文件组织由你决定。** 上述文件夹只是约定——SDK 通过对 `export default defineEntity(...)` 调用进行 AST 分析来检测实体，而不受文件所在位置影响。
</Note>
packages/twenty-docs/l/zh/developers/extend/apps/getting-started/quick-start.mdx
+78 -78
View File
@@ -1,184 +1,184 @@
---
title: Quick Start
title: 快速开始
icon: rocket
description: Create your first Twenty app in minutes.
description: 几分钟内创建你的第一个 Twenty 应用。
---
## Prerequisites
## 先决条件
* **Node.js 24+** — [Download](https://nodejs.org/)
* **Yarn 4** — bundled with Node via Corepack. Enable it: `corepack enable`
* **Docker** — [Download](https://www.docker.com/products/docker-desktop/). Needed to run a local Twenty server. Skip if you already have Twenty running elsewhere.
* **Node.js 24+** — [在此下载](https://nodejs.org/)
* **Yarn 4** — 通过 Corepack 随 Node.js 提供。 启用它：`corepack enable`
* **Docker** — [在此下载](https://www.docker.com/products/docker-desktop/)。 运行本地 Twenty 服务器所需。 如果你已经在其他地方运行了 Twenty，请跳过。
Building a Twenty app has three phases. The scaffolder collapses them into one happy-path command, but each phase is a separate concept — when something fails, knowing which phase you're in tells you what to fix.
构建一个 Twenty 应用包含三个阶段。 脚手架工具将它们合并为一个理想路径的命令，但每个阶段都是独立的概念——当出现问题时，知道自己处于哪个阶段可以指明需要修复什么。
| Phase | What you do | Tool | Result |
| ------------------- | ---------------------------------- | ----------------------------- | ----------------------------- |
| **1. Scaffold** | Generate the app's source code | `npx create-twenty-app` | A TypeScript project on disk |
| **2. Run a server** | Start a Twenty server to sync into | Docker + `yarn twenty server` | A running Twenty instance |
| **3. Sync** | Live-sync your code to the server | `yarn twenty dev` | Your changes appear in the UI |
| 阶段 | 你要做什么 | 工具 | 结果 |
| ------------ | -------------------- | ----------------------------- | -------------------- |
| **1. 脚手架** | 生成应用的源代码 | `npx create-twenty-app` | 磁盘上的一个 TypeScript 项目 |
| **2. 运行服务器** | 启动一个 Twenty 服务器以进行同步 | Docker + `yarn twenty server` | 一个正在运行的 Twenty 实例 |
| **3. 同步** | 将你的代码实时同步到服务器 | `yarn twenty dev` | 你的更改会出现在 UI 中 |
---
## Phase 1 — Scaffold your project
## 阶段 1 — 搭建项目脚手架
Create a new app from the template:
从模板创建一个新应用：
```bash filename="Terminal"
npx create-twenty-app@latest my-twenty-app
```
You'll be prompted for a name and description — press **Enter** for the defaults. This generates a TypeScript project in `my-twenty-app/` with a starter `application-config.ts`, a default role, a CI workflow, and an integration test.
系统会提示你输入名称和描述——按下 **Enter** 采用默认值。 这将在 `my-twenty-app/` 中生成一个 TypeScript 项目，包含一个入门版的 `application-config.ts`、一个默认角色、一个 CI 工作流，以及一个集成测试。
**After this phase:** you have an app's source code on your machine. It isn't running yet — that's Phase 2.
**完成此阶段后：** 你的机器上已有该应用的源代码。 它还未运行——那是第 2 阶段的内容。
---
## Phase 2 — Run a local Twenty server
## 阶段 2 — 运行本地 Twenty 服务器
Your app needs a Twenty server to sync into. The server is a full Twenty instance — UI, GraphQL API, PostgreSQL — running locally in Docker. Your local code uploads its definitions to that server, which makes them appear in the UI.
你的应用需要一个 Twenty 服务器来进行同步。 该服务器是一个完整的 Twenty 实例——包含 UI、GraphQL API、PostgreSQL——在本地的 Docker 中运行。 你的本地代码会将其定义上传到该服务器，从而使其显示在 UI 中。
The scaffolder offers to start one for you:
脚手架工具会为你提供启动它的选项：
> **Would you like to set up a local Twenty instance?**
> **是否要设置本地 Twenty 实例？**
* **Yes (recommended)** — pulls the `twentycrm/twenty-app-dev` Docker image and starts it on port `2020`. Make sure Docker is running first.
* **No** — choose this if you already have a Twenty server you want to connect to. You can wire it up later with `yarn twenty remote add`.
* **是（推荐）** — 将拉取 `twentycrm/twenty-app-dev` Docker 镜像，并在端口 `2020` 上启动它。 请先确保 Docker 正在运行。
* **否** — 如果你已经有一个想要连接的 Twenty 服务器，请选择此项。 你可以稍后通过 `yarn twenty remote add` 将其连接起来。
<div style={{textAlign: 'center'}}>
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="Should start local instance?" />
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="是否启动本地实例？" />
</div>
Once the server is up, a browser opens for sign-in. Use the pre-seeded demo account:
服务器启动后，浏览器会打开登录页面。 使用预置的演示账户：
* **Email:** `tim@apple.dev`
* **Password:** `tim@apple.dev`
* **邮箱：** `tim@apple.dev`
* **密码：** `tim@apple.dev`
<div style={{textAlign: 'center'}}>
<img src="/images/docs/developers/extends/apps/login.png" alt="Twenty login screen" />
<img src="/images/docs/developers/extends/apps/login.png" alt="Twenty 登录界面" />
</div>
Click **Authorize** on the next screen — this gives the CLI access to your workspace.
在下一屏点击 **Authorize** —— 这将授予 CLI 访问你工作区的权限。
<div style={{textAlign: 'center'}}>
<img src="/images/docs/developers/extends/apps/authorize.png" alt="Twenty CLI authorization screen" />
<img src="/images/docs/developers/extends/apps/authorize.png" alt="Twenty CLI 授权界面" />
</div>
Your terminal will confirm everything is set up.
你的终端会确认一切已就绪。
<div style={{textAlign: 'center'}}>
<img src="/images/docs/developers/extends/apps/scaffolded.png" alt="App scaffolded successfully" />
<img src="/images/docs/developers/extends/apps/scaffolded.png" alt="应用脚手架创建成功" />
</div>
**After this phase:** you have a running Twenty server at [http://localhost:2020](http://localhost:2020) with your CLI authorized to sync to it.
**完成此阶段后：** 你在 [http://localhost:2020](http://localhost:2020) 上拥有一个正在运行的 Twenty 服务器，且你的 CLI 已获授权可与其同步。
<Note>
If Docker isn't installed or running, the scaffolder will tell you the right start command for your OS. Once Docker is up, you can resume with `yarn twenty server start` — no need to re-scaffold.
如果未安装或未运行 Docker，脚手架工具会告诉你在所用操作系统上正确的启动命令。 Docker 启动后，你可以通过 `yarn twenty server start` 继续——无需重新生成脚手架。
</Note>
---
## Phase 3 — Sync your changes
## 阶段 3 — 同步你的更改
This is the inner loop you'll spend most of your time in.
这是你大部分时间所处的内循环。
```bash filename="Terminal"
cd my-twenty-app
yarn twenty dev
```
This watches `src/`, rebuilds on every change, and syncs the result to the server. Edit a file, save, and within a second the server reflects the change. You'll see a live status panel in your terminal.
它会监视 `src/`，在每次更改时重新构建，并将结果同步到服务器。 编辑文件、保存，服务器会在一秒内反映出更改。 你会在终端中看到一个实时状态面板。
For more detailed output (build logs, sync requests, error traces), add `--verbose`.
如需更详细的输出（构建日志、同步请求、错误跟踪），请添加 `--verbose`。
<div style={{textAlign: 'center'}}>
<img src="/images/docs/developers/extends/apps/dev.png" alt="Dev mode terminal output" />
<img src="/images/docs/developers/extends/apps/dev.png" alt="开发模式终端输出" />
</div>
Open [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). You should see your app under **Your Apps**.
打开 [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer)。 你应当在 **你的应用** 下看到你的应用。
<div style={{textAlign: 'center'}}>
<img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Your Apps list showing My twenty app" />
<img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="“你的应用”列表显示 My twenty app" />
</div>
Click **My twenty app** to see its **application registration** — a server-level record describing your app (name, identifier, OAuth credentials, source). One registration can be installed across multiple workspaces on the same server.
点击 **My twenty app** 查看其**应用注册**——一条用于描述你的应用（名称、标识符、OAuth 凭据、来源）的服务器级记录。 同一服务器上的多个工作区可以安装同一个注册项。
<div style={{textAlign: 'center'}}>
<img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Application registration details" />
<img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="应用注册详情" />
</div>
Click **View installed app** to see the workspace install. The **About** tab shows version and management options.
点击 **查看已安装的应用** 以查看工作区安装项。 **关于** 选项卡显示版本和管理选项。
<div style={{textAlign: 'center'}}>
<img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Installed app" />
<img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="已安装的应用" />
</div>
**After this phase:** you have a live development loop. Edit any file in `src/` and it appears in the UI.
**完成此阶段后：** 你拥有一个实时的开发循环。 编辑 `src/` 中的任意文件，更改会显示在 UI 中。
### One-shot sync for CI and scripts
### 用于 CI 和脚本的一次性同步
Pass `--once` to run a single build + sync and exit — same pipeline, no watcher:
传入 `--once` 以执行一次构建与同步后退出——相同的流水线，无文件监视器：
```bash filename="Terminal"
yarn twenty dev --once
```
| Command | Behavior | When to use |
| ------------------------ | ------------------------------------------------------------- | ---------------------------------------------------- |
| `yarn twenty dev` | Watches and re-syncs on every change. Runs until you stop it. | Interactive local development. |
| `yarn twenty dev --once` | Single build + sync, exits `0` on success, `1` on failure. | CI, pre-commit hooks, AI agents, scripted workflows. |
| 命令 | 行为 | 适用场景 |
| ------------------------ | -------------------------------- | ------------------------------ |
| `yarn twenty dev` | 监视并在每次更改时重新同步。 持续运行，直到你将其停止。 | 交互式本地开发。 |
| `yarn twenty dev --once` | 单次构建与同步，成功时以 `0` 退出，失败时以 `1` 退出。 | CI、pre-commit 钩子、AI 代理、脚本化工作流。 |
Both modes need a server in development mode and an authenticated remote.
两种模式都需要处于开发模式的服务器和已认证的远程。
<Warning>
Dev mode is only available on Twenty instances running in development (`NODE_ENV=development`). Production instances reject dev sync requests — use `yarn twenty deploy` to deploy to production servers. See [Publishing](/l/zh/developers/extend/apps/operations/publishing).
开发模式仅适用于以开发模式运行的 Twenty 实例（`NODE_ENV=development`）。 生产实例会拒绝开发同步请求——请使用 `yarn twenty deploy` 部署到生产服务器。 参见[发布](/l/zh/developers/extend/apps/operations/publishing)。
</Warning>
---
## Starting from an example
## 从示例开始
Use `--example` to start with a more complete project (custom objects, fields, logic functions, front components):
使用 `--example` 从一个更完整的项目开始（自定义对象、字段、逻辑函数、前端组件）：
```bash filename="Terminal"
npx create-twenty-app@latest my-twenty-app --example postcard
```
Examples live in [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples). You can also scaffold individual entities into an existing project with `yarn twenty add` — see [Scaffolding](/l/zh/developers/extend/apps/getting-started/scaffolding).
示例位于 [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples)。 你也可以使用 `yarn twenty add` 为现有项目生成单个实体的脚手架——参见[脚手架](/l/zh/developers/extend/apps/getting-started/scaffolding)。
---
## What you can build
## 你可以构建的内容
Apps are composed of **entities** — each defined as a TypeScript file with a single `export default`:
应用由**实体**组成——每个实体定义为一个包含单一 `export default` 的 TypeScript 文件：
| Entity | What it does |
| ---------------------- | ----------------------------------------------------------------------------------- |
| **Objects & Fields** | Custom data models (Post Card, Invoice, etc.) with typed fields |
| **Logic functions** | Server-side TypeScript triggered by HTTP routes, cron schedules, or database events |
| **Front components** | React components that render inside Twenty's UI (side panel, widgets, command menu) |
| **Skills & Agents** | AI capabilities — reusable instructions and autonomous assistants |
| **Views & Navigation** | Pre-configured list views and sidebar menu items |
| **Page layouts** | Custom record detail pages with tabs and widgets |
| 实体 | 作用 |
| ---------- | ------------------------------------------ |
| **对象与字段** | 自定义数据模型（明信片、发票等） 带有类型化字段 |
| **逻辑函数** | 由 HTTP 路由、cron 调度或数据库事件触发的服务端 TypeScript |
| **前端组件** | 在 Twenty 的 UI 内渲染的 React 组件（侧边面板、小部件、命令菜单） |
| **技能与智能体** | AI 能力——可复用的指令和自主助手 |
| **视图与导航** | 预配置的列表视图和侧边栏菜单项 |
| **页面布局** | 带有选项卡和小部件的自定义记录详情页 |
Full reference: [Concepts](/l/zh/developers/extend/apps/getting-started/concepts).
完整参考：[概念](/l/zh/developers/extend/apps/getting-started/concepts)。
## Next steps
## 后续步骤
<CardGroup cols={2}>
<Card title="Config" icon="screwdriver-wrench" href="/l/zh/developers/extend/apps/config/overview">
Application identity, default role, install hooks, public assets.
<Card title="配置" icon="screwdriver-wrench" href="/l/zh/developers/extend/apps/config/overview">
应用身份、默认角色、安装钩子、公共资源。
</Card>
<Card title="Data" icon="database" href="/l/zh/developers/extend/apps/data/overview">
Objects, fields, and bidirectional relations.
<Card title="数据" icon="database" href="/l/zh/developers/extend/apps/data/overview">
对象、字段和双向关系。
</Card>
<Card title="Logic" icon="bolt" href="/l/zh/developers/extend/apps/logic/overview">
Logic functions, skills, agents, and OAuth connections.
<Card title="逻辑" icon="bolt" href="/l/zh/developers/extend/apps/logic/overview">
逻辑函数、技能、代理和 OAuth 连接。
</Card>
<Card title="Layout" icon="table-columns" href="/l/zh/developers/extend/apps/layout/overview">
Views, navigation, page layouts, front components.
<Card title="布局" icon="table-columns" href="/l/zh/developers/extend/apps/layout/overview">
视图、导航、页面布局、前端组件。
</Card>
<Card title="Operations" icon="rocket" href="/l/zh/developers/extend/apps/operations/overview">
CLI, testing, remotes, CI, and publishing your app.
<Card title="操作" icon="rocket" href="/l/zh/developers/extend/apps/operations/overview">
CLI、测试、远程、CI，以及发布你的应用。
</Card>
</CardGroup>
packages/twenty-docs/l/zh/developers/extend/apps/getting-started/scaffolding.mdx
+29 -29
View File
@@ -1,18 +1,18 @@
---
title: Scaffolding
description: Generate entity files interactively with yarn twenty add — objects, fields, views, logic functions, and more.
title: 脚手架
description: 通过 yarn twenty add 以交互方式生成实体文件——对象、字段、视图、逻辑函数等。
icon: wand-magic-sparkles
---
Instead of creating entity files by hand, use the interactive scaffolder:
无需手动创建实体文件，使用交互式脚手架：
```bash filename="Terminal"
yarn twenty add
```
It prompts you to pick an entity type and walks you through the required fields, then writes a ready-to-use file with a stable `universalIdentifier` and the correct `defineEntity()` call.
它会提示你选择一个实体类型，引导你填写所需字段，然后生成一个可直接使用的文件，其中包含稳定的 `universalIdentifier` 和正确的 `defineEntity()` 调用。
You can also pass the entity type directly to skip the first prompt:
你也可以直接传入实体类型以跳过第一个提示：
```bash filename="Terminal"
yarn twenty add object
@@ -20,38 +20,38 @@ yarn twenty add logicFunction
yarn twenty add frontComponent
```
## Available entity types
## 可用的实体类型
| Entity type | Command | Generated file |
| -------------------- | ------------------------------------ | ------------------------------------------------------- |
| Object | `yarn twenty add object` | `src/objects/\<name>.ts` |
| Field | `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` |
| Role | `yarn twenty add role` | `src/roles/\<name>.ts` |
| Skill | `yarn twenty add skill` | `src/skills/\<name>.ts` |
| Agent | `yarn twenty add agent` | `src/agents/\<name>.ts` |
| View | `yarn twenty add view` | `src/views/\<name>.ts` |
| Navigation menu item | `yarn twenty add navigationMenuItem` | `src/navigation-menu-items/\<name>.ts` |
| Page layout | `yarn twenty add pageLayout` | `src/page-layouts/\<name>.ts` |
| 实体类型 | 命令 | 生成的文件 |
| ----- | ------------------------------------ | ------------------------------------------------------- |
| 对象 | `yarn twenty add object` | `src/objects/\<name>.ts` |
| 字段 | `yarn twenty add field` | `src/fields/\<name>.ts` |
| 逻辑函数 | `yarn twenty add logicFunction` | `src/logic-functions/\<name>.ts` |
| 前端组件 | `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` |
## What the scaffolder generates
## 脚手架生成的内容
Each entity type has its own template. For example, `yarn twenty add object` asks for:
每种实体类型都有其自己的模板。 例如，`yarn twenty add object` 会询问：
1. **Name (singular)** — e.g., `invoice`
2. **Name (plural)** — e.g., `invoices`
3. **Label (singular)** — auto-populated from the name (e.g., `Invoice`)
4. **Label (plural)** — auto-populated (e.g., `Invoices`)
5. **Create a view and navigation item?** — if you answer yes, the scaffolder also generates a matching view and sidebar link for the new object.
1. **名称（单数）**——例如，`invoice`
2. **名称（复数）**——例如，`invoices`
3. **标签（单数）**——根据名称自动填充（例如，`Invoice`）
4. **标签（复数）**——自动填充（例如，`Invoices`）
5. **创建视图和导航项？**——如果你选择是，脚手架还会为新对象生成相应的视图和侧边栏链接。
Other entity types have simpler prompts — most only ask for a name.
其他实体类型的提示更简单——大多只会询问名称。
The `field` entity type is more detailed: it asks for the field name, label, type (from a list of all available field types like `TEXT`, `NUMBER`, `SELECT`, `RELATION`, etc.), and the target object's `universalIdentifier`.
`field` 实体类型更为详细：它会询问字段名称、标签、类型（从所有可用字段类型列表中选择，如 `TEXT`、`NUMBER`、`SELECT`、`RELATION` 等），以及目标对象的 `universalIdentifier`。
## Custom output path
## 自定义输出路径
Use the `--path` flag to place the generated file in a custom location:
使用 `--path` 标志将生成的文件放置在自定义位置：
```bash filename="Terminal"
yarn twenty add logicFunction --path src/custom-folder