Twenty Apps 开发指南hello-world 示例中 LLM 协作开发的三条核心规则UUID v4、视图导航关联、组件响应式【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty本文以 Twenty 官方 hello-world 应用示例中的 LLM 指令文档 LLMS.md 为主体逐条拆解其中定义的UUID 必须为 v4硬性要求与两条常见陷阱并对照该示例应用的全部源码实体对象、视图、导航菜单项、前端组件、逻辑函数说明每条规则背后的工程约束。读完后你应当掌握用 LLM 辅助生成 Twenty App 代码时的三条自检规则以及如何在仓库中找到对应的参照实现与更完整的 rich-app 样例。一、LLMS.md 的定位写给 LLM 的应用开发守则hello-world 是 Twenty 仓库内置的最小可用应用示例其 README 中明确写道Main docs and pitfalls are available in LLMS.md file.见 README.md。也就是说LLMS.md 是该应用面向大语言模型LLM的官方提示文档用于在 LLM 生成或修改应用代码时约束其行为边界。该文档由三个部分组成Base documentation基础文档入口指向 Twenty 官方应用开发 Getting Started 文档并指向一个内容更丰富的完整应用样例——在本仓库中对应 rich-app 示例当 hello-world 不足以覆盖某种模式时rich-app 是首选参照UUID requirementUUID 要求All generated UUIDs must be valid UUID v4.所有生成的 UUID 必须是合法的 UUID v4Common Pitfalls常见陷阱两条具体陷阱——Creating a view without a navigationMenuItem associated.创建视图时未关联对应的 navigationMenuItemCreating a front-end component that has a scroll instead of being responsive to its fixed widget height and width, unless it is specifically meant to be used in a canvas tab.前端组件内置了滚动而不是响应式地适应其固定的 widget 高度与宽度除非该组件专门用于 canvas tab。这三条规则看似简短却分别对应 Twenty 应用开发中三个最容易由 LLM想当然写错的层面稳定标识符、界面导航注册、组件尺寸约束。下文逐条展开。二、规则一所有生成的 UUID 必须是合法的 UUID v42.1 为什么 universalIdentifier 是应用的核心从 hello-world 示例的源码结构看应用中的每一类实体都通过universalIdentifier字段建立唯一身份且该值是硬编码在源码中的字符串常量而不是运行时生成实体类型定义文件universalIdentifier 示例应用application-config.tsbb1decf6-dee5-43ef-b881-9799f97b02a8对象Objectexample-object.ts47fd9bd9-392b-4d9f-9091-9a91b1edf519字段Fieldexample-object.ts2d9ff841-cf8e-44ec-ad8e-468455f7eebd视图Viewexample-view.ts965e3776-b966-4be8-83f7-6cd3bce5e1bd导航菜单项example-navigation-menu-item.ts9327db91-afa1-41b6-bd9d-2b51a26efb4c前端组件hello-world.tsx7a758f23-5e7d-497d-98c9-7ca8d6c085b0逻辑函数hello-world.tsb05e4b30-72d4-4d7f-8091-32e037b601da安装前钩子pre-install.tsf8ad4b09-6a12-4b12-a52a-3472d3a78dc7安装后钩子post-install.ts8c726dcc-1709-4eac-aa8b-f99960a9ec1b这些标识符的作用可以从源码中相互引用的方式得到印证example-object.ts 将对象标识符导出为EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER、将 name 字段导出为NAME_FIELD_UNIVERSAL_IDENTIFIER随后 example-view.ts 通过objectUniversalIdentifier属性引用前者、通过fieldMetadataUniversalIdentifier引用后者example-navigation-menu-item.ts 再引用视图的标识符。可见 universalIdentifier 是跨实体装配应用的稳定主键安装、同步、升级都依赖它识别这是同一个实体。因此 LLM 新增任何实体时必须生成一个全新的、合法的标识符并硬编码导出而不能省略或随意填写。2.2 如何验证一个 UUID 是合法的 v4UUID v4 的格式为 8-4-4-4-12 共 32 位十六进制数其中有两个指纹位第三组首位必须是版本位4第四组首位必须是变体位取值范围为8、9、a、b。以本示例中的应用标识符bb1decf6-dee5-43ef-b881-9799f97b02a8为例第三组43ef以4开头版本位正确第四组9799以9开头变体位合法因此是一个标准的 UUID v4。示例中列出的其余标识符如47fd9bd9-392b-4d9f-9091-9a91b1edf519、965e3776-b966-4be8-83f7-6cd3bce5e1bd同样满足这两条指纹规则。这对 LLM 生成代码有直接的实操含义生成的每个universalIdentifier都应先通过上述两条指纹位校验标识符必须在整个应用内唯一新增实体时不能复制已有实体的值标识符一经写入源码即成为稳定契约后续迭代不应重新生成。三、规则二视图必须关联 navigationMenuItem否则不会按预期出现在左侧边栏LLMS.md 的第一条 Common Pitfall 指出Creating a view without a navigationMenuItem associated. 即只创建视图而不创建关联的导航菜单项是 LLM 生成应用代码时最常见的错误之一。hello-world 示例给出了正确的完整配对方式。3.1 视图侧只负责声明看什么example-view.ts 通过defineView声明了一个针对自定义对象 exampleItems 的列表视图export const EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER 965e3776-b966-4be8-83f7-6cd3bce5e1bd; export default defineView({ universalIdentifier: EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER, name: All example items, objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER, icon: IconList, position: 0, fields: [ { universalIdentifier: f926bdb7-6af7-4683-9a09-adbca56c29f0, fieldMetadataUniversalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER, position: 0, isVisible: true, size: 200, }, ], });注意视图中每一列同样拥有自己的universalIdentifier这里是 name 字段列并引用对象字段定义中的NAME_FIELD_UNIVERSAL_IDENTIFIER——每列一个 v4 UUID的规则在视图中再次得到贯彻。3.2 菜单项侧负责把视图挂到左侧导航example-navigation-menu-item.ts 通过defineNavigationMenuItem声明导航入口并以type: NavigationMenuItemType.VIEW类型来自twenty-shared/types加viewUniversalIdentifier指向该视图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, });从源码结构看两者之间不互相导入组件实现而是通过视图导出的标识符常量完成装配菜单项决定左侧边栏出现什么、排第几、什么颜色图标视图决定点开之后展示哪些字段。因此 LLM 在生成代码时的检查项很明确每生成一个defineView必须同时生成一个defineNavigationMenuItem菜单项的viewUniversalIdentifier必须引用视图导出的标识符常量而不是手敲一份副本菜单项自身同样需要独立的 UUID v4 标识符。四、规则三前端组件必须响应式适应 widget 尺寸默认不内置滚动第二条 Common Pitfall 要求前端组件不应自带滚动条scroll而应响应式地适应其所在的 widget 的固定高度与宽度——唯一的例外是该组件明确用于 canvas tab 场景。4.1 组件运行环境决定了这条规则应用的前端组件最终由 Twenty 的前端组件渲染器加载执行相关运行时实现位于 twenty-front-component-renderer 包中从源码结构看它包含host/宿主侧与remote/远端沙箱侧两部分及polyfills/目录负责把应用包中的 React 组件挂载到 Twenty 界面里的具体插槽中。组件在记录页、看板等位置呈现时通常被放进尺寸固定的 widget 容器——如果组件内部再声明一套自己的滚动区域就会出现滚动套滚动、内容被双重裁剪的观感问题。LLMS.md 因此把响应容器而非自滚定为默认规范仅当组件是专为 canvas tab大画布场景用户预期内容可滚动扩展设计时才允许内部滚动。4.2 hello-world 组件的示范写法hello-world.tsx 展示了符合该规则的典型形态const client new CoreApiClient(); // ... return ( div style{{ padding: 20px, fontFamily: sans-serif }} h1Hello, World!/h1 pThis is your first front component./p {data ? ( div pCompany name: {data.name}/p pCompany id: {data.id}/p /div ) : ( pCompany not found/p )} /div ); export default defineFrontComponent({ universalIdentifier: HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER, name: hello-world-front-component, description: A sample front component, component: HelloWorld, });要点有三组件根节点是普通流式div不设固定高度、不设overflow滚动内容自然撑开或由父容器约束组件通过CoreApiClient来自twenty-client-sdk/core发起类型化的 GraphQL 查询示例中按position: 1过滤取一条 company 记录展示应用组件与宿主数据模型的交互方式组件通过defineFrontComponent注册并遵循规则一使用 UUID v4 的universalIdentifier。对 LLM 的落地约束可以归纳为生成组件时避免height: 100vh、固定像素高容器、overflow: auto/scroll这类写法除非需求明确说明组件用于 canvas tab否则一律按内容自适应、滚动交给宿主来写。五、配套工作流与落地检查清单规则生效的场景正是 README 中描述的 LLM 参与开发的工作流见 README.md# 认证到目标 workspace yarn twenty remote:add --api-url http://localhost:2020 --as local # 启动开发模式watch build sync 自动生成类型化 client yarn twenty dev # 用脚手架生成新实体object / field / function / front-component / role / view / navigation-menu-item yarn twenty dev:addyarn twenty dev:add支持脚手架化的实体类型中同时包含view与navigation-menu-item这正对应本文规则二强调的成对生成。综合 LLMS.md 与示例源码LLM 生成或修改 Twenty App 代码后建议按下述清单自检标识符所有新增/修改的universalIdentifier应用、对象、字段、视图、视图列、菜单项、组件、逻辑函数均为合法 UUID v4且全应用唯一视图-导航配对每个新视图都有对应的defineNavigationMenuItem且通过导出的标识符常量引用该视图组件响应式前端组件不内置滚动适应 widget 固定尺寸仅 canvas tab 专用组件例外引用方式实体间引用一律使用导出的标识符常量不复制粘贴字符串模式不足时hello-world 覆盖不到的更复杂模式角色权限、技能、字段类型等参考本仓库中更完整的 rich-app 样例 与 LLMS.md 所指向的官方 Getting Started 文档。以上五条规则在 hello-world 示例的每一个源码文件中都有对应实例可循是 LLM 与开发者协作开发 Twenty 应用时最基础、也最值得固化的行为约束。【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
