develop-app

适用场景

当用户想要更改现有 Twenty 应用的功能——数据模型、UI、逻辑或工作流时，选择此技能。典型触发场景：

• “在我的 Twenty 应用中添加一个新对象”
• “创建一个在记录创建时运行的逻辑函数”
• “为 company 对象添加一个自定义字段”
• “为 deal 页面构建一个前端组件”
• “修改现有的实体 / 对象 / 字段”
• “添加一个带手动触发器的工作流”
• “为我的应用添加角色和权限”
• “在我的应用中创建独立页面”

不要使用此技能来搭建全新应用（使用 create-app）、同步 / 部署 / 排查问题（使用 manage-app）、准备市场素材（使用 publish-app），或查询工作区记录（使用 use-twenty-mcp）。

适用范围

如需了解 Twenty 应用的工作方式——SDK 包、远程服务、同步生命周期和渲染模型——请阅读 ../../references/concepts/how-apps-work.md。适用于所有 Twenty 应用任务的跨技能操作规则见 ../../references/concepts/operating-rules.md；这些规则具有权威性，不会在每项技能中重复说明。

不要在此处搭建新应用。如果应用尚不存在，请先使用 create-app。

工作流

首先，在更改实体前确认配置正常。当前目录应是现有 Twenty 应用的根目录：

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

如果缺少其中任一文件，不要贸然编辑。检查附近的文件夹以找到应用根目录；如果应用不存在，则使用 create-app。

如果配置、依赖项、远程服务、身份验证、同步、构建、部署、日志或 CI/CD 出现问题，请先切换到 manage-app，再继续处理实体。

如需了解应用结构和实体文件结构，请阅读 ../../references/develop-app/app-structure.md。

编辑前制定计划

对于涉及多个实体的任何更改，请在编辑前用 3–6 行说明计划：扩展哪些对象、添加哪些字段、声明哪些逻辑函数和安装后钩子，以及应用是否需要 UI。存在实际选择时，请与用户确认。

单实体编辑、重命名和文案修正可跳过此步骤。

代码组织

保持逻辑函数、安装后钩子和前端组件精简。除触发器、输入、写入操作、渲染外壳或外部调用之外的所有内容都应提取出来：

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

文件名使用 kebab-case。src/ 中的每个辅助函数、类型和客户端文件都必须只导出一个内容——绝不要在同一个文件中导出多个函数。此规则按导出内容计数：本地（未导出）类型可以与工具函数放在一起，但类型一旦导出或被复用，就必须拆分到单独的 src/types/<name>.ts 文件中，与 src/utils/<name>.util.ts 文件分开。规范规则和完整后缀约定请参见 app-structure.md。

以下情况需要重构：

• *.logic-function.ts 或 *.post-install.ts 文件超过软性上限（参见 ../../references/develop-app/logic.md）。
• 前端组件中存在重复的命令执行、记录加载、逻辑函数查找、载荷构建、结果解析或 snackbar 格式化逻辑。
• 不同对象类型中出现相同的解析或映射逻辑。
• 多个字段文件只有名称和标识符不同——请在 src/fields/ 下使用工厂函数。

每个新增或修改的工具函数／函数都必须在同级的 __tests__/ 文件夹中创建一个 *.spec.ts 测试文件，每个源文件对应一个测试文件。请参见 ../../references/develop-app/tests.md。

当前端组件为选中的记录触发逻辑函数时，除非用户明确说明该函数仅用于一条记录，否则应始终优先使用支持批量处理的逻辑函数。默认载荷结构为 records: Array<{ id: string; ...fields }>：在 records 内，使用 id 表示 Twenty 记录 ID，因为数组名称已经明确了记录上下文。除非用户明确要求保留现有的单记录 API，否则不要添加扁平的单记录兼容载荷。

添加新实体

使用 CLI 添加新实体。CLI 会生成正确的文件结构、UUID、SDK 导入和样板代码。请先检查是否有可独立运行且无需终端的 CLI：

command -v twenty && twenty app add object --name invoice --name-plural invoices --create-view --create-navigation-menu-item --create-page-layout --no-input

如果缺少独立 CLI，请先安装。对于受支持的类型，使用 twenty app add；对于其他实体，请遵循上方所链接操作规则中的规则 3 以及相应的 SDK 定义。

前端组件默认规范

每个可见的前端组件都应默认使用 twenty-ui 组件和独立图标。编写自定义控件或添加其他 UI 库之前，先复用功能等效的 Twenty UI 组件。对于布局容器以及没有等效 Twenty UI 组件的内容，可以使用纯 HTML。

创建或编辑前端组件 UI 之前，请阅读 ../../references/develop-app/front-components.md，了解导入和渲染器限制；并阅读 ../../references/design/front-component-ui.md，了解组件选择、主题令牌、无障碍性和可见状态。首次实现和之后的视觉润色都必须遵循此要求。请使用链接中的官方组件页面查看最新的属性和组合方式，不要猜测 API，也不要将完整文档复制到应用中。

实体变更后

完成所有变更编辑后，在最后运行一次 lint 和类型检查（不要在每次单独编辑后运行），然后将应用同步到当前激活的远程服务：

twenty app typecheck
yarn lint
twenty app apply

twenty app typecheck 检查生成的应用类型，yarn lint 检查本地 lint 规则，twenty app apply 将实体定义同步到当前激活的远程服务。完成所有编辑后，将这三项各运行一次，不要在每个步骤后反复运行。用户明确要求运行测试时，请遵循 ../../references/develop-app/tests.md。

涉及确切的实体字段、导入项或配置结构时，请查阅 Twenty 官方文档或本地 SDK 源码。

开发参考资料

阅读与请求的实体工作相匹配的最精简参考资料：

• 对象、字段、关系、角色和权限：../../references/develop-app/data-model.md
• 视图、导航、页面布局、页面布局选项卡、前端组件注册和设置菜单项：../../references/develop-app/layout.md
• 全页面自定义 UI 和独立页面模式：../../references/develop-app/standalone-pages.md
• 前端组件源码、Twenty UI 导入项、数据钩子、运行时导入项和浏览器验证：../../references/develop-app/front-components.md
• 逻辑函数、技能、Agent、安装后钩子和连接提供方：../../references/develop-app/logic.md
• 工作流、手动触发器、草稿/激活生命周期和种子程序陷阱：../../references/develop-app/workflows.md
• 测试——需要覆盖的内容及文件放置位置：../../references/develop-app/tests.md
• 应用文件结构和实体验证清单：../../references/develop-app/app-structure.md
• 详细的前端组件 UI 设计：../../references/design/front-component-ui.md

对于前端组件，请在实现前阅读 front-components.md。使用 layout.md 确定放置位置，使用 standalone-pages.md 了解全页面自定义 UI，使用 front-component-ui.md 进行视觉设计并选择 Twenty UI 组件。

交接事项

所有可见的前端组件（包括首次实现）都要使用 ../../references/design/front-component-ui.md。

当任务涉及 README、市场文案、截图、徽标或上架资源时，请使用 publish-app。