develop-app

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When To Use

何时使用

Pick this skill when the user wants to change what an existing Twenty app does — its data model, UI, logic, or workflows. Representative triggers:

"add a new object to my Twenty app"
"create a logic function that runs on record create"
"add a custom field to the company object"
"build a front component for the deal page"
"modify an existing entity / object / field"
"add a workflow with a manual trigger"
"add roles and permissions to my app"
"create a standalone page in my app"

Do not use this skill to scaffold a brand-new app (use

create-app

), to sync/deploy/troubleshoot (use

manage-app

), to prepare marketplace assets (use

publish-app

), or to query workspace records (use

use-twenty-mcp

当用户希望更改现有 Twenty app 的行为时选择此 skill——即其数据模型、UI、逻辑或 workflow。典型触发场景：

“为我的 Twenty app 添加一个新 object”
“创建一个在记录创建时运行的 logic function”
“为 company object 添加一个自定义 field”
“为 deal 页面构建一个 front component”
“修改现有 entity / object / field”
“添加一个带手动触发器的 workflow”
“为我的 app 添加 role 和 permission”
“在我的 app 中创建一个 standalone page”

不要使用此 skill 搭建全新 app（请使用

create-app

）、执行同步/部署/故障排查（请使用

manage-app

）、准备 marketplace 资产（请使用

publish-app

），或查询 workspace 记录（请使用

use-twenty-mcp

）。

Boundaries

边界

For background on how Twenty apps work — the SDK packages, remotes, sync lifecycle, and rendering model — read

../../references/concepts/how-apps-work.md

. Cross-skill operating rules that apply to every Twenty app task are in

../../references/concepts/operating-rules.md

; they are authoritative and not restated per skill.

Do not scaffold a new app here. Use

create-app

first when the app does not exist.

如需了解 Twenty app 的运作机制背景——包括 SDK packages、remotes、sync lifecycle 和 rendering model——请阅读

../../references/concepts/how-apps-work.md

。适用于所有 Twenty app 任务的跨 skill 操作规则位于

../../references/concepts/operating-rules.md

；这些规则具有权威性，此处不逐一重复。

不要在此处搭建新 app。当 app 尚不存在时，请先使用

create-app

。

Workflow

工作流

First, confirm the setup is sane before changing entities. The current directory should be the root of an existing Twenty app:

bash

test -f package.json
test -f src/application-config.ts

If either file is missing, do not edit blindly. Inspect nearby folders to find the app root, or use

create-app

when the app does not exist.

If setup, dependencies, remotes, authentication, sync, build, deploy, logs, or CI/CD are failing, switch to

manage-app

before continuing with entity work.

For app shape and entity file structure, read

../../references/develop-app/app-structure.md

在修改实体前，先确认环境配置合理。当前目录应当是现有 Twenty app 的根目录：

bash

test -f package.json
test -f src/application-config.ts

如果缺少其中任一文件，请勿盲目编辑。检查附近的目录以查找 app 根目录；如果 app 不存在，则使用

create-app

。

如果 setup、dependencies、remotes、authentication、sync、build、deploy、logs 或 CI/CD 出现问题，请在继续处理实体工作前切换到

manage-app

。

有关 app 结构和实体文件结构，请阅读

../../references/develop-app/app-structure.md

。

Plan Before Editing

编辑前规划

For any change involving more than one entity, state the plan back in 3–6 lines before editing: objects extended, fields added, logic functions and post-install hooks declared, whether the app needs UI. Confirm with the user when there is a real choice.

Skip for single-entity edits, renames, and copy fixes.

对于涉及多个实体的任何更改，在编辑前用 3–6 行向用户说明计划：扩展哪些 object、添加哪些 field、声明哪些 logic function 和 post-install hook，以及 app 是否需要 UI。存在实质性选择时，请向用户确认。

单实体编辑、重命名和文案修正无需执行此步骤。

Code Organization

代码组织

Keep logic functions, post-install hooks, and front components narrow. Extract everything that is not the trigger, inputs, writes, rendering shell, or external call:

```
src/utils/<name>.util.ts
```
— pure helpers (parsers, mappers, formatters).
```
src/front-components/utils/<name>.util.ts
```
— front-component runtime helpers that are reusable and testable.
```
src/types/<name>.ts
```
— external API and internal DTO types (one PascalCase type per file).
```
src/<service>-client/<name>.ts
```
— wrappers around external SDKs or shared HTTP clients. One folder per service, matching Twenty's
```
*-client
```
convention.

Kebab-case filenames. One export per file is mandatory for every helper, type, and client file in

src/

— never multiple function exports in one file. The rule counts exports: a local (non-exported) type may stay alongside the util, but once a type is exported or reused it splits into a

src/types/<name>.ts

file separate from the

src/utils/<name>.util.ts

file. See

app-structure.md

for the canonical rule and the full suffix convention.

Refactor when:

*.logic-function.ts

*.post-install.ts

file exceeds the soft cap (see

../../references/develop-app/logic.md

A front component contains duplicated command execution, record loading, logic-function lookup, payload building, result parsing, or snackbar formatting.
The same parsing or mapping logic appears across object types.
Multiple field files differ only by name and identifier — use a factory under
```
src/fields/
```
.

Always create a

*.spec.ts

test file in a sibling

__tests__/

folder for every util/function you add or change, one spec file per source file. See

../../references/develop-app/tests.md

When a front component triggers a logic function for selected records, always prefer a bulk-capable logic function unless the user explicitly states that the function is only for one record. The default payload shape is

records: Array<{ id: string; ...fields }>

: inside

records

, use

id

for the Twenty record ID because the array name already establishes the record context. Do not add flat single-record compatibility payloads unless the user explicitly asks to preserve an existing single-record API.

保持 logic function、post-install hook 和 front component 职责单一。将不属于触发器、输入、写入、渲染外壳或外部调用的所有内容提取出来：

```
src/utils/<name>.util.ts
```
——纯辅助函数（解析器、映射器、格式化器）。
```
src/front-components/utils/<name>.util.ts
```
——可复用且可测试的 front component 运行时辅助函数。
```
src/types/<name>.ts
```
——外部 API 和内部 DTO 类型（每个文件一个 PascalCase 类型）。
```
src/<service>-client/<name>.ts
```
——外部 SDK 或共享 HTTP client 的封装。每个服务使用一个文件夹，并遵循 Twenty 的
```
*-client
```
命名约定。

文件名使用 Kebab-case。对于

src/

中的每个辅助函数、类型和 client 文件，必须每个文件仅导出一个项目，绝不能在一个文件中导出多个 function。该规则按导出项计算：本地（未导出的）type 可以与 util 放在同一文件中，但 type 一旦被导出或复用，就必须拆分到独立的

src/types/<name>.ts

文件中，并与其

src/utils/<name>.util.ts

文件分离。有关规范规则和完整的文件后缀约定，请参阅

app-structure.md

。

出现以下情况时进行重构：

*.logic-function.ts

或

*.post-install.ts

文件超过软性上限（参阅

../../references/develop-app/logic.md

）。

front component 中存在重复的命令执行、记录加载、logic function 查找、payload 构建、结果解析或 snackbar 格式化逻辑。
相同的解析或映射逻辑出现在多个 object type 中。
多个 field 文件仅在名称和标识符上存在差异——请改用
```
src/fields/
```
下的 factory。

对于每个新增或修改的 util/function，始终在同级

__tests__/

文件夹中创建一个

*.spec.ts

测试文件，每个源文件对应一个 spec 文件。请参阅

../../references/develop-app/tests.md

。

当 front component 为选中的记录触发 logic function 时，除非用户明确说明该 function 仅适用于单条记录，否则始终优先使用支持批量处理的 logic function。默认 payload 结构为

records: Array<{ id: string; ...fields }>

：在

records

内部使用

id

表示 Twenty record ID，因为数组名称已经确立了记录上下文。除非用户明确要求保留现有的单记录 API，否则不要添加扁平的单记录兼容 payload。

Adding New Entities

添加新实体

Use the app CLI to add new entities. It generates the correct file structure, UUIDs, SDK imports, and boilerplate automatically:

bash

yarn twenty dev:add

This is the default and preferred way to create objects, fields, views, logic functions, front components, and other entities. Do not manually create entity files, explore SDK typings in

node_modules

, or generate UUIDs by hand when the CLI can do it.

Only create entity files manually when modifying existing entities or when the CLI does not support the specific entity type.

使用 app CLI 添加新实体。它会自动生成正确的文件结构、UUID、SDK imports 和 boilerplate：

bash

yarn twenty dev:add

这是创建 object、field、view、logic function、front component 和其他实体的默认且首选方式。当 CLI 可以完成这些工作时，不要手动创建实体文件、探索

node_modules

中的 SDK 类型定义或手工生成 UUID。

仅在修改现有实体，或者 CLI 不支持特定实体类型时，才手动创建实体文件。

After Entity Changes

实体更改完成后

Once all edits for the change are complete, run lint and typecheck once at the end (not after each individual edit), then sync the app to the active remote:

bash

yarn twenty dev:typecheck
yarn lint
yarn twenty apply

yarn twenty dev:typecheck

checks generated app types,

yarn lint

checks local lint rules, and

yarn twenty apply

syncs entity definitions to the active remote. Run all three a single time once every edit is done, not repeatedly after each step. When the user explicitly asks to run tests, follow

../../references/develop-app/tests.md

Use the official Twenty docs or local SDK source when exact entity fields, imports, or configuration shapes matter.

所有更改完成后，在最后运行一次 lint 和 typecheck（不要在每次单独编辑后运行），然后将 app 同步到当前 remote：

bash

yarn twenty dev:typecheck
yarn lint
yarn twenty apply

yarn twenty dev:typecheck

检查生成的 app types，

yarn lint

检查本地 lint 规则，

yarn twenty apply

将实体定义同步到当前 remote。所有编辑完成后，将以上三项统一运行一次，不要在每个步骤后反复运行。当用户明确要求运行测试时，请遵循

../../references/develop-app/tests.md

。

当确切的实体 fields、imports 或配置结构很重要时，请查阅 Twenty 官方文档或本地 SDK 源码。

Develop References

开发参考

Read the smallest reference that matches the requested entity work:

Objects, fields, relations, roles, and permissions:
```
../../references/develop-app/data-model.md
```
Views, navigation, page layouts, page layout tabs, front component registration, and settings menu items:
```
../../references/develop-app/layout.md
```
Full-page custom UI and standalone page patterns:
```
../../references/develop-app/standalone-pages.md
```
Front component source, Twenty UI imports, data hooks, runtime imports, and browser verification:
```
../../references/develop-app/front-components.md
```
Logic functions, skills, agents, post-install hooks, and connection providers:
```
../../references/develop-app/logic.md
```
Workflows, manual triggers, draft/activate lifecycle, and seeder pitfalls:
```
../../references/develop-app/workflows.md
```
Tests — what to cover and where to put the files:
```
../../references/develop-app/tests.md
```
App file structure and entity validation checklist:
```
../../references/develop-app/app-structure.md
```

Detailed front component UI design:

../../references/design/front-component-ui.md

For front components, read

front-components.md

before implementation. Use

layout.md

for placement,

standalone-pages.md

for full-page custom UI, and

front-component-ui.md

for visual design and Twenty UI component selection.

请阅读与所请求实体工作相匹配的最精简参考文档：

Object、field、relation、role 和 permission：
```
../../references/develop-app/data-model.md
```
View、navigation、page layout、page layout tab、front component 注册和 settings menu item：
```
../../references/develop-app/layout.md
```
全页面 custom UI 和 standalone page 模式：
```
../../references/develop-app/standalone-pages.md
```
Front component 源码、Twenty UI imports、data hooks、runtime imports 和浏览器验证：
```
../../references/develop-app/front-components.md
```
Logic function、skill、agent、post-install hook 和 connection provider：
```
../../references/develop-app/logic.md
```
Workflow、手动触发器、draft/activate lifecycle 和 seeder 常见问题：
```
../../references/develop-app/workflows.md
```
测试——需要覆盖的内容以及文件存放位置：
```
../../references/develop-app/tests.md
```

App 文件结构和实体验证清单：

../../references/develop-app/app-structure.md

Front component 的详细 UI 设计：

../../references/design/front-component-ui.md

对于 front component，请在实现前阅读

front-components.md

。使用

layout.md

了解 placement，使用

standalone-pages.md

了解全页面 custom UI，使用

front-component-ui.md

了解 visual design 和 Twenty UI component selection。

Handoffs

交接

Use

../../references/design/front-component-ui.md

when the entity work turns into front component UI design.

Use

publish-app

when the task turns into README, marketplace copy, screenshots, logos, or listing assets.

当实体工作转为 front component UI 设计时，使用

../../references/design/front-component-ui.md

。

当任务转为 README、marketplace 文案、截图、logo 或上架资产时，使用

publish-app

。