snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/zh/developers/extend/apps/getting-started/concepts.mdx

@@ -0,0 +1,102 @@
+---
+title: 概念
+description: Twenty 应用的工作方式 — 实体模型、沙盒机制和安装生命周期。
+icon: sitemap
+---
+
+Twenty 应用是 TypeScript 包，可通过自定义对象、逻辑、UI 组件和 AI 能力扩展你的工作区。 它们在 Twenty 平台上运行，具备完备的沙盒与权限控制。
+
+## 应用如何运作
+
+应用是由 `twenty-sdk` 包中的 `defineEntity()` 函数声明的**实体**集合。 SDK 在构建时通过 AST 分析检测到这些声明，并生成一份**清单**——完整描述你的应用为工作区新增的内容。 这些函数会在构建时校验你的配置，并提供 IDE 自动补全和类型安全。
+
+```
+your-app/
+├── src/
+│   ├── application-config.ts    ← defineApplication (required, one per app)
+│   ├── roles/                   ← defineRole
+│   ├── objects/                 ← defineObject
+│   ├── fields/                  ← defineField
+│   ├── logic-functions/         ← defineLogicFunction
+│   ├── front-components/        ← defineFrontComponent
+│   ├── skills/                  ← defineSkill
+│   ├── agents/                  ← defineAgent
+│   ├── views/                   ← defineView
+│   ├── navigation-menu-items/   ← defineNavigationMenuItem
+│   └── page-layouts/            ← definePageLayout
+├── public/                      ← Static assets (images, icons)
+└── package.json
+```
+
+<Note>
+  **文件组织由你决定。** 实体检测基于 AST——无论文件位于何处，SDK 都能找到 `export default defineEntity(...)` 的调用。 上述文件夹结构是一种约定，而非强制要求。
+</Note>
+
+## 实体类型
+
+| 实体        | 目的                                | 文档                                                                                                    |
+| --------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| **应用程序**  | 应用标识、默认角色、变量                      | [应用配置](/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)                                               |
+| **共享依赖项** | 由应用的前端组件共享的依赖项，在 package.json 中声明 | [共享依赖项](/l/zh/developers/extend/apps/layout/front-components#sharing-dependencies-across-front-components) |
+| **命令菜单项** | 快速操作和 Cmd+K 条目                    | [命令菜单项](/l/zh/developers/extend/apps/layout/command-menu-items)                                            |
+
+## 沙盒化
+
+* **逻辑函数** 在服务器上的独立 Node.js 进程中运行。 它们仅通过类型化 API 客户端访问数据，该客户端会以触发运行的人员或应用本身的身份执行操作。 请参阅[调用使用谁的访问权限](/l/zh/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses)。
+* **前端组件** 在使用 Remote DOM 的 Web Worker 中运行——与主页面沙盒隔离，但渲染原生 DOM 元素（非 iframe）。 它们通过消息传递的宿主 API 与 Twenty 通信。
+* **权限** 在 API 层面强制执行。 系统会注入两个运行时令牌，二者均派生自通过 `defineApplicationRole()` 声明的角色；只要运行由人员触发，默认令牌的权限范围就会进一步缩小为该触发人员可执行的操作。
+
+## 应用生命周期
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Development                                             │
+│   npx create-twenty-app → yarn twenty dev (live sync)   │
+├─────────────────────────────────────────────────────────┤
+│ Build & Deploy                                          │
+│   yarn twenty dev:build → yarn twenty app:publish        │
+├─────────────────────────────────────────────────────────┤
+│ Install flow                                            │
+│   upload → [pre-install] → metadata migration →         │
+│   generate SDK → [post-install] → … → [uninstall]       │
+├─────────────────────────────────────────────────────────┤
+│ Publish                                                 │
+│   npm publish → appears in Twenty marketplace           │
+└─────────────────────────────────────────────────────────┘
+```
+
+* **`yarn twenty dev`** — 监视你的源文件，并将更改实时同步到已连接的 Twenty 服务器。 当模式发生变化时，会自动重新生成类型化的 API 客户端。
+* **`yarn twenty dev:build`** — 编译 TypeScript，使用 esbuild 打包逻辑函数和前端组件，并生成清单。
+* **预/后安装和卸载钩子** — 在安装过程中或在卸载前立即运行的可选函数。 详见 [安装钩子](/l/zh/developers/extend/apps/config/install-hooks)。
+
+## 后续步骤
+
+<CardGroup cols={2}>
+  <Card title="配置" icon="screwdriver-wrench" href="/l/zh/developers/extend/apps/config/overview">
+    应用标识、默认角色，以及安装和卸载钩子。
+  </Card>
+  <Card title="数据" icon="database" href="/l/zh/developers/extend/apps/data/overview">
+    对象、字段和双向关系。
+  </Card>
+  <Card title="逻辑" icon="bolt" href="/l/zh/developers/extend/apps/logic/overview">
+    逻辑函数、技能、代理和 OAuth 连接。
+  </Card>
+  <Card title="布局" icon="table-columns" href="/l/zh/developers/extend/apps/layout/overview">
+    视图、导航、页面布局、前端组件。
+  </Card>
+  <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

@@ -0,0 +1,87 @@
+---
+title: 本地服务器
+description: 管理本地 Twenty Docker 服务器 — 启动、停止、升级、并行测试实例，以及手动设置 SDK。
+icon: server
+---
+
+## 管理本地服务器
+
+使用 `yarn twenty docker:*` 控制本地的 Twenty 容器：
+
+| 命令                                     | 作用                        |
+| -------------------------------------- | ------------------------- |
+| `yarn twenty docker:start`             | 启动服务器（按需拉取镜像）             |
+| `yarn twenty docker:start 2.2.0`       | 启动指定的服务器版本                |
+| `yarn twenty docker:start --port 3030` | 在自定义端口启动                  |
+| `yarn twenty docker:stop`              | 停止服务器（保留数据）               |
+| `yarn twenty docker:status`            | 显示 URL、版本和登录凭据            |
+| `yarn twenty docker:logs`              | 流式输出服务器日志                 |
+| `yarn twenty docker:reset`             | 清空数据并全新开始                 |
+| `yarn twenty docker:upgrade`           | 拉取最新的 `twenty-app-dev` 镜像 |
+| `yarn twenty docker:upgrade 2.2.0`     | 升级到指定版本                   |
+
+数据在重启后会保留，存储于两个 Docker 卷中（`twenty-app-dev-data` 用于 PostgreSQL，`twenty-app-dev-storage` 用于文件）。 使用 `reset` 清空所有内容。
+
+## 固定服务器版本
+
+当未传入版本时，`docker:start` 会根据你的应用在 `package.json` 中的 `engines.twenty` 范围解析版本 —— 这与在安装你的应用时服务器用于校验的范围相同。 它会启动满足该范围的最新已发布 `twenty-app-dev` 镜像，当该字段缺失或没有已发布版本匹配时，则回退到 `latest`：
+
+```json filename="package.json"
+{
+  "engines": {
+    "twenty": ">=2.2.0"
+  }
+}
+```
+
+显式传入一个版本以在单次运行中覆盖该范围：`yarn twenty docker:start 2.3.0`。 如果已有容器使用的是不同版本，`docker:start` 会就地升级它（在保留你的数据卷的同时重新创建容器）。
+
+## 升级服务器镜像
+
+`yarn twenty docker:upgrade` 将拉取最新镜像、比较摘要，并且仅在确有变更时才重新创建容器。 数据卷将被保留——只会替换容器。 如果已拉取新镜像且容器正在运行，升级会自动启动一个新容器；之后运行 `yarn twenty docker:start` 以等待其变为健康状态。
+
+```bash filename="Terminal"
+yarn twenty docker:upgrade            # Latest
+yarn twenty docker:upgrade 2.2.0      # Specific version
+```
+
+使用 `yarn twenty docker:status` 验证正在运行的版本（它会显示写入容器的 `APP_VERSION`）。
+
+## 运行并行测试实例
+
+向任意 `docker:*` 命令传递 `--test` 以管理第二个、完全隔离的实例——这有助于在不影响主开发数据的情况下进行集成测试或试验：
+
+| 命令                                  | 作用                  |
+| ----------------------------------- | ------------------- |
+| `yarn twenty docker:start --test`   | 启动测试实例 (默认端口为 2021) |
+| `yarn twenty docker:stop --test`    | 停止它                 |
+| `yarn twenty docker:status --test`  | 显示其状态               |
+| `yarn twenty docker:logs --test`    | 流式输出其日志             |
+| `yarn twenty docker:reset --test`   | 清空其数据               |
+| `yarn twenty docker:upgrade --test` | 升级其镜像               |
+
+测试实例有其自己的容器（`twenty-app-dev-test`）、卷（`twenty-app-dev-test-data`、`twenty-app-dev-test-storage`）和配置——它可与你的主实例并行运行且不会发生冲突。 将 `--test` 与 `--port` 组合使用以覆盖 2021 端口。
+
+## 手动设置（不使用脚手架）
+
+如果你要将 SDK 添加到现有项目中，可跳过脚手架：
+
+```bash filename="Terminal"
+yarn add twenty-sdk twenty-client-sdk
+```
+
+在 `package.json` 中添加该脚本：
+
+```json filename="package.json"
+{
+  "scripts": {
+    "twenty": "twenty"
+  }
+}
+```
+
+现在你可以运行 `yarn twenty dev`、`yarn twenty docker:start`，以及其他命令。
+
+<Note>
+不要全局安装 `twenty-sdk` —— 在每个项目中固定其版本，使每个应用都使用各自的版本。
+</Note>

packages/twenty-docs/l/zh/developers/extend/apps/getting-started/project-structure.mdx

@@ -0,0 +1,79 @@
+---
+title: 项目结构
+description: 脚手架生成的 Twenty 应用中包含哪些内容——文件、文件夹以及它们各自的作用。
+icon: folder-tree
+---
+
+由 `npx create-twenty-app` 生成的新应用看起来是这样的：
+
+```text filename="my-twenty-app/"
+my-twenty-app/
+  package.json
+  src/
+    application-config.ts                   # Required — your app's entry point
+    default-role.ts                         # Permissions for logic functions
+    constants/
+      universal-identifiers.ts              # Auto-generated UUIDs and metadata
+    front-components/
+      main-page.tsx                         # Welcome page component
+    navigation-menu-items/
+      main-page.navigation-menu-item.ts     # Sidebar entry for the welcome page
+    page-layouts/
+      main-page.page-layout.ts              # Standalone page hosting the component
+    __tests__/
+      application-config.test.ts            # Unit test
+      global-setup.ts                       # Integration test setup (sync + uninstall)
+      schema.integration-test.ts            # Integration test against a live server
+  .github/workflows/
+    ci.yml                                  # Lint, typecheck, unit + integration tests
+    cd.yml                                  # Deploy + install on push to main
+    publish.yml                             # Publish to npm on version tags (with provenance)
+  public/
+    logo.svg                                # Static assets
+  vitest.config.ts                          # Integration test runner config
+  vitest.unit.config.ts                     # Unit test runner config
+  tsconfig.json, tsconfig.spec.json
+  .nvmrc, .yarnrc.yml, .oxlintrc.json
+  README.md, AGENTS.md, CLAUDE.md, CHANGELOG.md, SETUP.md
+```
+
+## 关键文件
+
+| 文件 / 文件夹                                                                   | 目的                                      |
+| -------------------------------------------------------------------------- | --------------------------------------- |
+| `src/application-config.ts`                                                | **必需。** 应用的主配置文件。                       |
+| `src/default-role.ts`                                                      | 默认角色，用于控制你的逻辑函数可访问的内容。                  |
+| `src/constants/universal-identifiers.ts`                                   | 自动生成的 UUID 和元数据（显示名称、描述）。               |
+| `src/front-components/`, `src/navigation-menu-items/`, `src/page-layouts/` | 一个入门欢迎页面：由独立页面布局渲染的前端组件，可从侧边栏访问。        |
+| `src/__tests__/`                                                           | 一个单元测试加一个集成测试（带有其全局设置），用于将应用与真实服务器进行同步。 |
+| `public/`                                                                  | 随应用一起提供的静态资源（图像、字体）。                    |
+| `AGENTS.md` / `CLAUDE.md`                                                  | 为在该应用上工作的 AI 编码代理提供指导。                  |
+| `CHANGELOG.md` / `SETUP.md`                                                | 显著更改的更新日志以及用于本地开发的设置说明。                 |
+
+<Note>
+**文件组织由你决定。** 上述文件夹只是约定——SDK 通过对 `export default defineEntity(...)` 调用进行 AST 分析来检测实体，而不受文件所在位置影响。
+</Note>
+
+## 依赖项
+
+这两个 Twenty SDK 软件包都应放在 `devDependencies` 下，而不是 `dependencies`：
+
+```json filename="package.json"
+{
+  "dependencies": {},
+  "devDependencies": {
+    "twenty-client-sdk": "2.20.0",
+    "twenty-sdk": "2.20.0",
+    "twenty-ui": "1.0.0-alpha.1"
+  }
+}
+```
+
+脚手架工具将 `twenty-sdk` 和 `twenty-client-sdk` 固定为与自身相同的版本——升级时请保持这两者同步。
+
+* **`twenty-sdk`** 提供 `twenty` CLI 以及构建/脚手架工具。 它只在开发和构建阶段运行，且永远不会在已发布应用的运行时环境中被导入。
+* **`twenty-client-sdk`** 会被你的应用代码（`CoreApiClient`、`MetadataApiClient`、`RestApiClient`）导入，但 Twenty 会在运行时提供它——逻辑函数从生成的 SDK 层获取它，前端组件则从服务器提供的模块中解析它。 你安装的副本仅用于类型检查和部署时的构建，因此不需要被打包进已部署的 bundle 中。
+
+把任意一个软件包放在 `dependencies` 下，都会把它拉入已安装应用的运行时 bundle 中，在那里只是累赘。 当任一软件包仍然列在 `dependencies` 下时，`twenty dev:build` 会发出警告。
+
+像往常一样，把你的应用自身的运行时依赖项（逻辑函数在运行时实际导入的库）添加到 `dependencies` 下。 保持依赖树精简：`dependencies` 会被安装到一个解压后上限为 250MB 的运行时层中，如果超过该依赖大小限制，同步或安装就会失败并报依赖大小错误——UI 库和开发工具应放在 `devDependencies` 中。

packages/twenty-docs/l/zh/developers/extend/apps/getting-started/quick-start.mdx

@@ -0,0 +1,166 @@
+---
+title: 快速开始
+icon: rocket
+description: 几分钟内创建你的第一个 Twenty 应用。
+---
+
+## 先决条件
+
+* **Node.js 24.5+** — [在此下载](https://nodejs.org/)
+* **Yarn 4** — 通过 Corepack 随 Node.js 提供。 启用它：`corepack enable`
+* **Docker** — [在此下载](https://www.docker.com/products/docker-desktop/)。 运行本地 Twenty 服务器所需。 如果你已经在其他地方运行了 Twenty，请跳过。
+
+构建一个 Twenty 应用包含三个阶段。 脚手架工具将它们合并为一个理想路径的命令，但每个阶段都是独立的概念——当出现问题时，知道自己处于哪个阶段可以指明需要修复什么。
+
+| 阶段           | 你要做什么                | 工具                                  | 结果                   |
+| ------------ | -------------------- | ----------------------------------- | -------------------- |
+| **1. 脚手架**   | 生成应用的源代码             | `npx create-twenty-app`             | 磁盘上的一个 TypeScript 项目 |
+| **2. 运行服务器** | 启动一个 Twenty 服务器以进行同步 | Docker + `yarn twenty docker:start` | 一个正在运行的 Twenty 实例    |
+| **3. 同步**    | 将你的代码实时同步到服务器        | `yarn twenty dev`                   | 你的更改会出现在 UI 中        |
+
+---
+
+## 阶段 1 — 搭建项目脚手架
+
+从模板创建一个新应用：
+
+```bash filename="Terminal"
+npx create-twenty-app@latest my-twenty-app
+```
+
+脚手架是非交互式的：目录名称会成为应用名称。 传递 `--display-name` 和 `--description` 来自定义生成的元数据（你也可以稍后在 `src/constants/universal-identifiers.ts` 中进行编辑）。 这将在 `my-twenty-app/` 中生成一个 TypeScript 项目，包含一个入门版的 `application-config.ts`、一个默认角色、CI/CD 工作流，以及一个集成测试。
+
+**完成此阶段后：** 你的机器上已有该应用的源代码。 它还未运行——那是第 2 阶段的内容。
+
+---
+
+## 阶段 2 — 运行本地 Twenty 服务器
+
+你的应用需要一个 Twenty 服务器来进行同步。 该服务器是一个完整的 Twenty 实例——包含 UI、GraphQL API、PostgreSQL——在本地的 Docker 中运行。 你的本地代码会将其定义上传到该服务器，从而使其显示在 UI 中。
+
+脚手架会为你启动一个：在 Docker 正在运行的情况下，它会拉取 `twentycrm/twenty-app-dev` 镜像，在端口 `2020` 上启动，并将 CLI 认证到预置的演示工作区（`tim@apple.dev`）——无需登录。
+
+若要改为连接到现有的 Twenty 服务器，请传入 `--url \<your-server-url>`。 远程服务器通过 OAuth 进行身份验证：会打开一个浏览器窗口，你可以登录并点击 **Authorize**，从而授予 CLI 访问你工作区的权限。 （你也可以在本地选择使用 OAuth，方式是添加 `--authentication-method oauth` —— 使用 `tim@apple.dev` / `tim@apple.dev` 登录。）
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/login.png" alt="Twenty 登录界面" />
+</div>
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/authorize.png" alt="Twenty CLI 授权界面" />
+</div>
+
+你的终端会确认一切已就绪。
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/scaffolded.png" alt="应用脚手架创建成功" />
+</div>
+
+**完成此阶段后：** 你在 [http://localhost:2020](http://localhost:2020) 上拥有一个正在运行的 Twenty 服务器，且你的 CLI 已获授权可与其同步。
+
+<Note>
+如果未安装或未运行 Docker，脚手架工具会告诉你在所用操作系统上正确的启动命令。 Docker 启动后，你可以通过 `yarn twenty docker:start` 继续——无需重新生成脚手架。
+</Note>
+
+---
+
+## 阶段 3 — 同步你的更改
+
+这是你大部分时间所处的内循环。
+
+```bash filename="Terminal"
+cd my-twenty-app
+yarn twenty dev
+```
+
+它会监视 `src/`，在每次更改时重新构建，并将结果同步到服务器。 编辑文件、保存，服务器会在几秒内反映出更改。 你会在终端中看到一个实时状态面板。
+
+如需更详细的输出（构建日志、同步请求、错误跟踪），请添加 `--verbose`。
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/dev.png" alt="开发模式终端输出" />
+</div>
+
+打开 [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="“你的应用”列表显示 My twenty app" />
+</div>
+
+点击 **My twenty app** 查看其**应用注册**——一条用于描述你的应用（名称、标识符、OAuth 凭据、来源）的服务器级记录。 同一服务器上的多个工作区可以安装同一个注册项。
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="应用注册详情" />
+</div>
+
+点击 **查看已安装的应用** 以查看工作区安装项。 **关于** 选项卡显示版本和管理选项。
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="已安装的应用" />
+</div>
+
+**完成此阶段后：** 你拥有一个实时的开发循环。 编辑 `src/` 中的任意文件，更改会显示在 UI 中。
+
+### 用于 CI 和脚本的一次性同步
+
+使用 `plan` 和 `apply` 在无监视器的情况下各运行一次相同的流水线：
+
+```bash filename="Terminal"
+yarn twenty plan   # preview the metadata changes without applying them
+yarn twenty apply  # show the plan, then apply it
+```
+
+| 命令                  | 行为                                                                 | 适用场景                            |
+| ------------------- | ------------------------------------------------------------------ | ------------------------------- |
+| `yarn twenty dev`   | 监视并在每次更改时重新同步。 持续运行，直到你将其停止。                                       | 交互式本地开发。                        |
+| `yarn twenty apply` | 单次构建与同步，成功时以 `0` 退出，失败时以 `1` 退出。 在执行破坏性变更前会要求确认（传入 `--force` 可跳过）。 | CI、pre-commit 钩子、AI 智能体、脚本化工作流。 |
+| `yarn twenty plan`  | 构建并打印元数据更改，**但不会应用这些更改**。                                          | 在提交同步之前检查它会更改哪些内容。              |
+
+所有模式都需要经过身份验证的远程服务器。 有关 `plan` 的更多信息，请参见 [同步与恢复](/l/zh/developers/extend/apps/operations/sync-and-recovery#previewing-changes-plan)。
+
+<Note>
+`yarn twenty dev --once` 和 `yarn twenty dev --once --dry-run` 是 `yarn twenty apply` 和 `yarn twenty plan` 的已弃用别名。
+</Note>
+
+### 开发模式选项
+
+| 标志                                    | 描述                             |
+| ------------------------------------- | ------------------------------ |
+| `--force`                             | 在不经确认的情况下应用破坏性变更（删除）。          |
+| `--debounceMs \<ms>` | 以毫秒为单位设置文件更改的防抖延迟（默认值：`1000`）。 |
+| `--verbose` / `--debug`               | 显示详细的构建日志、同步请求和错误跟踪。           |
+
+## 你可以构建的内容
+
+应用由**实体**组成——每个实体定义为一个包含单一 `export default` 的 TypeScript 文件：
+
+| 实体         | 作用                                         |
+| ---------- | ------------------------------------------ |
+| **对象与字段**  | 自定义数据模型（明信片、发票等） 带有类型化字段                   |
+| **逻辑函数**   | 由 HTTP 路由、cron 调度或数据库事件触发的服务端 TypeScript   |
+| **前端组件**   | 在 Twenty 的 UI 内渲染的 React 组件（侧边面板、小部件、命令菜单） |
+| **技能与智能体** | AI 能力——可复用的指令和自主助手                         |
+| **视图与导航**  | 预配置的列表视图和侧边栏菜单项                            |
+| **页面布局**   | 带有选项卡和小部件的自定义记录详情页                         |
+
+完整参考：[概念](/l/zh/developers/extend/apps/getting-started/concepts)。
+
+## 后续步骤
+
+<CardGroup cols={2}>
+  <Card title="配置" icon="screwdriver-wrench" href="/l/zh/developers/extend/apps/config/overview">
+    应用标识、默认角色、安装和卸载钩子、公共资源。
+  </Card>
+  <Card title="数据" icon="database" href="/l/zh/developers/extend/apps/data/overview">
+    对象、字段和双向关系。
+  </Card>
+  <Card title="逻辑" icon="bolt" href="/l/zh/developers/extend/apps/logic/overview">
+    逻辑函数、技能、智能体和 OAuth 连接。
+  </Card>
+  <Card title="布局" icon="table-columns" href="/l/zh/developers/extend/apps/layout/overview">
+    视图、导航、页面布局、前端组件。
+  </Card>
+  <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

@@ -0,0 +1,63 @@
+---
+title: 脚手架
+description: 通过 yarn twenty dev:add 以交互方式生成实体文件——对象、字段、视图、逻辑函数等。
+icon: wand-magic-sparkles
+---
+
+无需手动创建实体文件，使用交互式脚手架：
+
+```bash filename="Terminal"
+yarn twenty dev:add
+```
+
+它会提示你选择一个实体类型，引导你填写所需字段，然后生成一个可直接使用的文件，其中包含稳定的 `universalIdentifier` 和正确的 `defineEntity()` 调用。
+
+你也可以直接传入实体类型以跳过第一个提示：
+
+```bash filename="Terminal"
+yarn twenty dev:add object
+yarn twenty dev:add logicFunction
+yarn twenty dev:add frontComponent
+```
+
+## 可用的实体类型
+
+| 实体类型    | 命令                                         | 生成的文件                                                     |
+| ------- | ------------------------------------------ | --------------------------------------------------------- |
+| 对象      | `yarn twenty dev:add object`               | `src/objects/\<name>.ts`                 |
+| 字段      | `yarn twenty dev:add field`                | `src/fields/\<name>.ts`                  |
+| 逻辑函数    | `yarn twenty dev:add logicFunction`        | `src/logic-functions/\<name>.ts`         |
+| 前端组件    | `yarn twenty dev:add frontComponent`       | `src/front-components/\<name>.tsx`       |
+| 角色      | `yarn twenty dev:add role`                 | `src/roles/\<name>.ts`                   |
+| 技能      | `yarn twenty dev:add skill`                | `src/skills/\<name>.ts`                  |
+| 代理      | `yarn twenty dev:add agent`                | `src/agents/\<name>.ts`                  |
+| 视图      | `yarn twenty dev:add view`                 | `src/views/\<name>.ts`                   |
+| 导航菜单项   | `yarn twenty dev:add navigationMenuItem`   | `src/navigation-menu-items/\<name>.ts`   |
+| 页面布局    | `yarn twenty dev:add pageLayout`           | `src/page-layouts/\<name>.ts`            |
+| 页面布局选项卡 | `yarn twenty dev:add pageLayoutTab`        | `src/page-layout-tabs/\<name>.ts`        |
+| 命令菜单项   | `yarn twenty dev:add commandMenuItem`      | `src/command-menu-items/\<name>.ts`      |
+| 视图字段    | `yarn twenty dev:add viewField`            | `src/view-fields/\<name>.ts`             |
+| 连接提供方   | `yarn twenty dev:add connectionProvider`   | `src/connection-providers/\<name>.ts`    |
+| 时间线活动类型 | `yarn twenty dev:add timelineActivityType` | `src/timeline-activity-types/\<name>.ts` |
+
+## 脚手架生成的内容
+
+每种实体类型都有其自己的模板。 例如，`yarn twenty dev:add object` 会询问：
+
+1. **名称（单数）**——例如，`invoice`
+2. **名称（复数）**——例如，`invoices`
+3. **标签（单数）**——根据名称自动填充（例如，`Invoice`）
+4. **标签（复数）**——自动填充（例如，`Invoices`）
+5. **创建视图和导航项？**——如果你选择是，脚手架还会为新对象生成相应的视图和侧边栏链接。
+
+其他实体类型的提示更简单——大多只会询问名称。
+
+`field` 实体类型更为详细：它会询问字段名称、标签、类型（从所有可用字段类型列表中选择，如 `TEXT`、`NUMBER`、`SELECT`、`RELATION` 等），以及目标对象的 `universalIdentifier`。
+
+## 自定义输出路径
+
+使用 `--path` 标志将生成的文件放置在自定义位置：
+
+```bash filename="Terminal"
+yarn twenty dev:add logicFunction --path src/custom-folder
+```

packages/twenty-docs/l/zh/developers/extend/apps/getting-started/troubleshooting.mdx

@@ -0,0 +1,14 @@
+---
+title: 故障排除
+description: 常见的首次运行问题 — Docker、Node 版本、Yarn、依赖项。
+icon: wrench
+---
+
+* **Docker 错误** — 在运行 `yarn twenty docker:start` 之前，请确保 Docker Desktop（或守护进程）已在运行。 错误消息会显示适用于你的操作系统的正确启动命令。
+* **错误的 Node 版本** — 需要 24.5+（`engines.node: ^24.5.0`）。 使用 `node -v` 检查。
+* **缺少 Yarn 4** — 运行 `corepack enable`。
+* **依赖损坏** — `rm -rf node_modules && yarn install`。
+* **`twenty-sdk` 升级到 v2.8.0 后出现错误** — 在 v2.8.0 中，它从 `dependencies` 移动到了 `devDependencies`。 请参阅[项目结构 → 依赖项](/l/zh/developers/extend/apps/getting-started/project-structure#dependencies)。
+* **`twenty dev:build` 会对 `dependencies` 下的 `twenty-client-sdk` 发出警告** — 它由 Twenty 在运行时提供，因此应与 `twenty-sdk` 一起移动到 `devDependencies` 中。 请参阅[项目结构 → 依赖项](/l/zh/developers/extend/apps/getting-started/project-structure#dependencies)。
+
+卡住了吗？ 在 [Twenty 的 Discord](https://discord.com/channels/1130383047699738754/1130386664812982322) 上提问。