一、项目定位与目标

Twenty 是一款定位为「#1 开源 CRM」的客户关系管理平台，致力于在现代化开源协议下提供可自托管、可扩展的企业级 CRM 能力。仓库根目录的 README.md 将其描述为「The #1 Open-Source CRM」，并强调在版本控制、原语（primitives）、AI 代理与工具链等方面持续投入，以帮助团队以编程方式构建、部署并管理业务实体。资料来源：README.md

项目围绕几个核心理念展开：

• 开放与可扩展：核心代码以开源协议发布，应用层通过 SDK 与 CLI 工具支持二次开发。
• AI 优先：内置 AI 代理（agents）、技能（skills）、聊天能力（见 README.md 中 v2-ai-agents 特性图）。
• 可定制的页面与视图：用户可自定义记录页面布局（layout），并以 user-guide/layout/overview 为文档入口。资料来源：README.md

二、技术栈总览

Twenty 是一套典型的前后端分离、并以 Nx 组织的 monorepo 工程。在根 README.md 的「Stack」一节中，明确列出主要技术：

资料来源：README.md、packages/twenty-docs/README.md

三、Monorepo 仓库结构

Twenty 在 packages/ 目录下以多包形式组织核心与生态代码，核心包包括后端、前端、共享类型、UI 库、文档站、SDK 与若干应用样例。下面用 Mermaid 图展示其主要组成部分及其关系。

graph TD
  Root[Twenty Monorepo Root]
  Root --> SDK[create-twenty-app]
  Root --> Server[twenty-server / NestJS]
  Root --> Front[twenty-front / React]
  Root --> UI[twenty-ui / 组件库]
  Root --> Shared[twenty-shared / 共享类型]
  Root --> Docs[twenty-docs / Mintlify]
  Root --> Codex[twenty-codex-plugin / AI 插件]
  Root --> Apps[twenty-apps / 应用生态]
  Apps --> Community[community/ 如 github-connector]
  Apps --> Internal[internal/ 如 twenty-fireflies]
  Apps --> Examples[examples/ 如 postcard]
  SDK --> Apps
  Codex --> SDK
  Front --> UI
  Front --> Shared
  Server --> Shared

各包职责简述：

• packages/twenty-shared：通过 package.json 的 typesVersions 暴露 ai、application、database-events、logic-function、metadata、workflow、workspace 等子路径类型声明，是后端、前端与 SDK 共同依赖的契约层。资料来源：packages/twenty-shared/package.json
• packages/twenty-ui：新版本组件库，目标是用 SCSS Modules + Base UI 替代旧的 twenty-ui-deprecated，并保持 13 个子路径导出与 ~180 个组件的 API 完全一致（导出标识符集合已校验一致）。资料来源：packages/twenty-ui/README.md
• packages/twenty-docs：使用 Mintlify 构建文档站，涵盖 46 页用户指南、24 页开发者文档与 25 页 UI 组件文档；本地通过 npx nx run twenty-docs:dev 启动。资料来源：packages/twenty-docs/README.md

四、应用开发生态

Twenty 不仅是 CRM 本身，更是一个应用平台。围绕核心 SDK 与 CLI，仓库内自带了脚手架、参考应用与 AI 插件。

4.1 脚手架 CLI：`create-twenty-app`

create-twenty-app 是官方提供的项目脚手架，发布在 npm 上，支持通过 npx create-twenty-app@latest my-twenty-app 一行命令生成完整工程。脚手架会负责 TypeScript、lint、twenty-sdk 等基础配置，开发者随后可执行 yarn twenty dev 进入本地开发模式。资料来源：packages/create-twenty-app/README.md

4.2 参考应用

仓库自带三类应用示例，作为开发者学习 SDK 实体模型的参考：

• examples/postcard：最丰富的样例，演示了 Application、Objects、Fields、Logic Functions、Front Components、Roles、Views、Navigation、Skills、Agents、Page Layouts 等全部 SDK 实体类型。资料来源：packages/twenty-apps/examples/postcard/README.md
• community/github-connector：社区贡献的 GitHub 连接器，包含 13 个 logic functions（覆盖 PR、Issue、Contributor、Project Item 等对象）、7 个 front components（命令与面板等）以及 GitHub Dashboard 布局。资料来源：packages/twenty-apps/community/github-connector/README.md
• internal/twenty-fireflies：内置的 Fireflies 通话记录集成，将会议转写与 AI 摘要落到 CalendarEvent 上，并提供三个工作流工具（同步、按参会人列出、手动触发等）用于补全与恢复。资料来源：packages/twenty-apps/internal/twenty-fireflies/README.md

4.3 Codex AI 插件：`twenty-codex-plugin`

twenty-codex-plugin 是面向 AI 编程代理（Codex）的官方插件，发布在 Codex 市场。package.json 声明其包含 .codex-plugin、skills、references、templates 等产物文件，并由 Node.js ≥ 24.5.0 与 Yarn ≥ 4.0.2 提供运行时支持。资料来源：packages/twenty-codex-plugin/package.json

插件以五个聚焦的 skill 形式组织能力：create-app、develop-app、manage-app、publish-app、use-twenty-mcp，分别对应应用脚手架、实体开发、远程与部署管理、发布准备以及 Twenty 工作区 MCP 查询。资料来源：packages/twenty-codex-plugin/README.md

特别需要注意的是，工作区专属的 MCP URL 属于用户本地配置，不应被打包进插件；插件内仅内置面向公共文档的 twenty-docs MCP 服务器，并提供一个 setup-mcp.sh 脚本帮助用户把工作区 MCP 写入 Codex 的本机配置。资料来源：packages/twenty-codex-plugin/README.md

五、典型工作流（脚手架到部署）

最常见的使用路径由 create-twenty-app 触发，经 SDK 与 dev server 完成本地联调，最终以应用形式发布：

1. 脚手架：执行 npx create-twenty-app@latest 创建项目并安装依赖。资料来源：packages/create-twenty-app/README.md
2. 本地开发：通过 yarn twenty dev 启动开发服务器，server 会在 http://localhost:2021 上运行；CLI 会自动生成类型化客户端。
3. 远程配置：yarn twenty remote:add 将本地 Twenty 服务注册为远端，需提供 API Key（来自 Settings → Developers）。资料来源：packages/twenty-apps/community/github-connector/README.md
4. 构建与部署：通过 manage-app 技能或 yarn twenty 的相关命令完成 build / deploy / sync / logs 等操作。资料来源：packages/twenty-codex-plugin/README.md
5. 发布：使用 publish-app 技能准备 README、市场元数据、Logo、截图等公共资产后发布到 npm / Marketplace。资料来源：packages/twenty-codex-plugin/README.md

六、常见问题与定位指南

• Server 无法启动：通常是 Docker 未运行；可执行 yarn twenty docker:logs 排查。资料来源：packages/create-twenty-app/README.md
• 鉴权失败：重新执行 yarn twenty remote:add 刷新远端凭据。资料来源：packages/create-twenty-app/README.md
• 类型未生成：确保 yarn twenty dev 正在运行，类型化客户端由其自动生成。资料来源：packages/create-twenty-app/README.md
• MCP 连接错乱：检查是否误把工作区 URL 写进了插件包；正确做法是使用 setup-mcp.sh 写入用户本机的 Codex 配置。资料来源：packages/twenty-codex-plugin/README.md

See Also

• 用户指南：布局与视图
• 开发者文档：应用构建
• 开发者文档：应用发布
• 应用操作总览

概述

Twenty 是一个基于 Nx 构建的单仓库（Monorepo）开源 CRM 平台，仓库根目录的 README.md 明确列出了核心技术栈，包括 TypeScript、Nx、NestJS（含 BullMQ）、PostgreSQL、Redis 与 React 资料来源：README.md。该 Monorepo 通过统一的包管理与构建系统，将后端服务、前端应用、UI 组件库、共享类型、客户端 SDK、文档站、AI 插件以及大量领域示例应用集中管理，使不同角色的贡献者（后端、前端、文档、集成开发者）能在同一棵源码树中协同迭代。

仓库统一采用 Yarn 作为包管理器，所有包在 package.json 中通过 workspace:* 协议互相引用，并在 engines 字段统一锁定 Node ^24.5.0 与 Yarn ^4.0.2 资料来源：packages/twenty-shared/package.json、packages/twenty-docs/package.json。这套约束既保证可复现的构建环境，也让 Nx 的增量缓存与任务图能够可靠地跨包复用。

顶层包结构

packages/ 目录下按职责划分为多个独立发布的包。下表汇总了核心包及其定位：

应用包与领域生态

packages/twenty-apps 是 Monorepo 内应用层的入口，按治理级别与发布渠道进一步细分：

• community/：由社区贡献并由官方托管的应用，例如 github-connector。该应用提供 Pull Request、Issue、Contributor、Project Item 等对象及同步逻辑函数，并通过 yarn twenty dev 与本地服务器实时联动 资料来源：packages/twenty-apps/community/github-connector/README.md。
• internal/：官方维护的闭源或受限应用，例如 twenty-fireflies，负责把 Fireflies 通话记录同步到 Twenty 的 CalendarEvent，并暴露工作流工具与 AI 摘要字段 资料来源：packages/twenty-apps/internal/twenty-fireflies/README.md。
• examples/：用于教学与模板的最小示例，如 postcard，展示对象、字段、Logic Function、布局与 AI 代理的组合方式 资料来源：packages/twenty-apps/examples/postcard/README.md。

这种 community / internal / examples 三段式布局，使 Twenty 团队既能控制核心 IP，又能借助社区生态扩展集成，并通过示例持续降低新贡献者的接入门槛。

构建系统、共享与发布

整个 Monorepo 依赖 Nx 作为任务编排与缓存层，配合 Yarn Workspaces 完成依赖解析。twenty-shared 通过 typesVersions 显式声明每个子路径的 .d.ts 入口，使下游包可以以 twenty-shared/metadata、twenty-shared/workflow 等形式按需导入，避免一次性引入全部模块 资料来源：packages/twenty-shared/package.json。twenty-client-sdk 同样采用子路径拆分（core、metadata、rest、generate），便于 SDK 使用者按场景引入 资料来源：packages/twenty-client-sdk/package.json。

对外发布方面，仓库内部维护了明确的“版本升级 → 灰度替换 → codemod → 移除旧包”流程：twenty-ui 在保持子路径导出与组件签名一致的前提下替换 twenty-ui-deprecated，并要求 Storybook、a11y 与体积检查三套验证随版本推进 资料来源：packages/twenty-ui/README.md。twenty-docs 则通过 navigation/base-structure.json 与 Crowdin 翻译模板解耦，使贡献者改动结构无需跨语言同步 资料来源：packages/twenty-docs/README.md。

AI 工具链层面，twenty-codex-plugin 把 Twenty 平台知识以“技能 + MCP”的方式注入 Codex：技能覆盖从 create-app、develop-app 到发布与版本控制的全生命周期，并通过 templates/marketplace.example.json 提供本地市场配置模板 资料来源：packages/twenty-codex-plugin/README.md。

flowchart LR
  A["twenty-shared<br/>types/ai/workflow/metadata"] --> B["twenty-front<br/>(NestJS + React)"]
  A --> C["twenty-client-sdk<br/>core/rest/generate"]
  A --> D["twenty-ui"]
  A --> E["twenty-apps/*<br/>community/internal/examples"]
  F["twenty-docs<br/>(Mintlify)"] --> A
  G["twenty-codex-plugin<br/>skills + MCP"] --> E
  H["PostgreSQL + Redis + BullMQ"] --> B

常见失败模式

由于所有包共享同一组 Node/Yarn 引擎约束，本地若使用旧版 Node 或非 Yarn 包管理器，会立即在 engines 校验或 workspace 协议解析阶段失败——例如 twenty-codex-plugin 与 twenty-docs 都强制 node ^24.5.0 与 yarn ^4.0.2 资料来源：packages/twenty-codex-plugin/package.json、packages/twenty-docs/package.json。文档侧的另一个常见坑是：翻译文件 packages/twenty-docs/l/<language>/navigation.json 只允许改动标签，不能改 slug，否则会与 base-structure.json 脱钩导致导航错乱 资料来源：packages/twenty-docs/README.md。

See Also

• 二十号文档站：docs.twenty.com
• 应用开发指南：developers/extend/apps/getting-started
• 应用发布流程：developers/extend/apps/publishing
• Codex 插件技能清单：packages/twenty-codex-plugin/skills

概述

Twenty 的「应用脚手架与 SDK」是一组用于在 Twenty CRM 平台上创建、扩展和发布自定义应用的工具链。它由三个相互协作的层次组成：底层的 twenty-client-sdk 与 twenty-shared 公共包提供类型与运行时原语；中层的 create-twenty-app 与 twenty-codex-plugin 提供脚手架与 AI 辅助开发能力；上层的示例应用（如 postcard、github-connector、twenty-fireflies）则展示 SDK 能构建出的完整形态（自定义对象、逻辑函数、HTTP 路由、前端组件、工作流等）。整个项目使用 Nx monorepo 组织，并通过 NestJS、PostgreSQL、Redis、BullMQ 等基础设施支撑后端，通过 React 支撑前端（资料来源：README.md）。

核心 SDK 与共享层

twenty-client-sdk 是面向应用开发者的客户端 SDK，它使用 Vite + vite-plugin-dts 同时输出 ESM/CJS 与 .d.ts，并通过 typesVersions 暴露 core、metadata、rest、generate 四个子路径，运行时依赖 @genql/runtime、graphql 与 lodash（资料来源：packages/twenty-client-sdk/package.json）。twenty-shared 包进一步把 AI、应用元数据、数据库事件、i18n、Logic Function、工作流、测试、翻译、工具、Vite 配置、工作区等子模块以独立入口发布，使前后端及 SDK 都能复用同一份类型与工具（资料来源：packages/twenty-shared/package.json）。

应用脚手架与开发工具

应用脚手架的核心入口是 create-twenty-app，由 twenty-codex-plugin 中的 create-app 技能负责调用，可在数秒内生成一个完整的应用目录结构（资料来源：packages/twenty-codex-plugin/README.md）。develop-app 技能进一步指导如何向已有应用添加对象、字段、Logic Function、布局、前端组件和工作流等实体（资料来源：packages/twenty-codex-plugin/README.md）。manage-app 技能覆盖远程仓库、同步、构建、部署、日志与 CI/CD；publish-app 技能则准备 README、市场元数据、Logo 与截图，以便发布到 npm 与市场（资料来源：packages/twenty-codex-plugin/README.md）。

该插件还捆绑了一个 twenty-docs MCP 服务器，可在 Codex 内即时检索公开文档；同时提供 setup-mcp.sh 脚本用于把用户私有工作区 MCP 端点写入本机 Codex 配置，命名规则为 twenty-<workspace-host>（资料来源：packages/twenty-codex-plugin/README.md）。插件包以 twenty-codex-plugin 名发布，强制使用 Yarn 4 与 Node 24（资料来源：packages/twenty-codex-plugin/package.json）。

flowchart LR
  A[create-twenty-app] --> B[应用目录]
  C[codex plugin<br/>create-app/develop-app] --> B
  B --> D[twenty-client-sdk]
  B --> E[twenty-shared 子模块]
  D --> F[二十工作区<br/>构建/部署/同步]
  E --> F

示例应用与能力展示

postcard 是一个端到端示例，演示 SDK 支持的全部实体类型：application.config.ts（应用元数据与变量）、objects/（自定义对象）、fields/（独立字段与关系）、logic-functions/（HTTP 路由、数据库事件、cron、工具函数、安装钩子）、components/（前端组件）、roles/、views/、navigation-menu-items/、skills/、agents/、page-layouts/（资料来源：packages/twenty-apps/examples/postcard/README.md）。开发者可在该目录内执行 yarn install && yarn twenty dev 启动本地开发服务器。

github-connector 展示了一个真实可用的第三方连接器：六个自定义对象（pullRequest、pullRequestReview、issue 等）、13 个 Logic Function（含签名校验的 Webhook）、GitHub GraphQL/REST 调用，以及 7 个前端组件，所有内容通过 GitHub 侧边栏聚合展示（资料来源：packages/twenty-apps/community/github-connector/README.md）。twenty-fireflies 则演示了 AI 集成模式：Webhook 自动把 Fireflies 转写写入 CalendarEvent 的 Transcript 与 Summary 字段，并暴露三个工作流工具（按需同步、按参与者列出通话等）以覆盖 Webhook 漏接的历史数据（资料来源：packages/twenty-apps/internal/twenty-fireflies/README.md）。

前端组件渲染与 UI 体系

twenty-front-component-renderer 负责把应用内的 React 组件安全地加载到 Twenty 主界面中，其 Storybook 套件按 HTML 标签与 host-api 调用拆分为独立 bundle，并通过 shared/test-utils/ 复用 fixture 与超时工具；每个 bundle 仅凭 URL 即可决定渲染场景，不依赖共享 dispatcher（资料来源：packages/twenty-front-component-renderer/src/__stories__/shared/test-utils/README.md）。twenty-ui 组件库通过 SCSS Modules + Base UI 重写 twenty-ui-deprecated，并保持相同子路径与组件签名，使 twenty-front 约 1730 个文件可通过 codemod 一次性迁移（资料来源：packages/twenty-ui/README.md）。应用脚手架与开发文档则集中在 twenty-docs 包中，由 Mintlify 渲染为 docs.twenty.com（资料来源：packages/twenty-docs/README.md）。

See Also

• 应用市场与发布：见 README.md 中 "Build apps / version control" 章节
• 文档与导航：见 packages/twenty-docs/README.md
• UI 组件迁移：见 packages/twenty-ui/README.md
• 示例应用：packages/twenty-apps/examples/postcard/README.md、packages/twenty-apps/community/github-connector/README.md

概述与目标

Twenty CRM 的前端界面由独立 UI 库 twenty-ui 支撑,该库被定位为可在主应用 twenty-front 之外发布、维护与版本化的 npm 包。其核心目标包括四点:作为可独立发布的版本化 npm 包发布;在替换 twenty-ui 时保证零视觉变化(同设计、同 token);迁移原 twenty-ui-deprecated 导出的全部组件;并将散落在 twenty-front/src/modules/ui 中的通用 UI(下拉菜单、模态框、标签列表、侧边面板、字段输入/展示等)抽离出来,使其与业务逻辑解耦 资料来源:packages/twenty-ui/README.md:1-50。

为保证最终切换不是重写,新库刻意保持与旧库相同的子路径导出、组件名称与 prop 签名,使得约 1,730 个使用点的替换可走 codemod + 依赖重命名路径 资料来源:packages/twenty-ui/README.md:60-80。

包结构与公共 API

twenty-ui 内部按职责划分为 13 个子路径入口:display、input、layout、navigation、feedback、components、theme、theme-constants、utilities、accessibility、assets、json-visualizer、testing,共导出约 180 个组件并附 3 个 CSS 文件 资料来源:packages/twenty-ui/README.md:80-95。目录遵循 src/{styles,theme,theme-constants,display,input,layout,navigation,feedback,components,accessibility,utilities,json-visualizer,assets,testing} 的组织方式,内部路径别名 @ui/* 与旧包保持一致 资料来源:packages/twenty-ui/README.md:50-75。

下表总结了迁移的四阶段进展与剩余工作。

资料来源:packages/twenty-ui/README.md:30-55, 100-110。

Twenty 的共享类型与运行时能力由独立 twenty-shared 包提供,涵盖 ai、application、constants、database-events、i18n、logic-function、metadata、testing、translations、types、utils、vite、workflow、workspace 等子路径,所有入口类型由 typesVersions 在 package.json 中显式声明 资料来源:packages/twenty-shared/package.json:1-60。

主题、样式与行为实现

主题层由 theme-constants 子包提供,需对外暴露 ThemeProvider、ThemeContext、useTheme、themeCssVariables 形态、ThemeType、颜色辅助函数,以及 theme-light.css / theme-dark.css 两个 CSS 入口;token 值复用旧包以保证设计一致 资料来源:packages/twenty-ui/README.md:90-115。

在实现层,样式方案由 Linaria(@linaria/react + @wyw-in-js/vite)切换为 SCSS Modules;交互行为由手写实现改为基于 Base UI;在可用处优先使用 Base UI / CSS transition 而非 framer-motion;图标系统继续保留(由 @tabler/icons-react 再导出 + 自定义图标 + Jotai 状态支持构成) 资料来源:packages/twenty-ui/README.md:80-90, 100-110。构建采用 Vite library mode,提供 ESM/CJS 双产物、vite-plugin-dts 生成的类型声明及自动 barrel,导出标识集已与旧包逐一对照一致 资料来源:packages/twenty-ui/README.md:60-80。

质量保障、测试与迁移策略

twenty-ui 的质量门槛通过 Storybook 驱动的多维度测试体系强制落地:每个组件必须配齐变体、尺寸、状态(storybook-addon-pseudo-states)与明暗主题 stories;交互测试由 @storybook/addon-vitest 在真实浏览器中执行,Jest 覆盖 hooks/工具,覆盖率由 @storybook/addon-coverage 收口;无障碍使用 Storybook a11y addon(axe-core)与 parameters.a11y.test = 'error' 作为门禁;视觉回归使用自托管 Argos,以同名 stories 与旧包做像素级 diff 资料来源:packages/twenty-ui/README.md:120-160。

性能与体积方面,每个入口点都有 size-limit 预算、tree-shaking 夹具、React Profiler 渲染基准、Playwright 加载时间测试,并设有"10,000 按钮"压力 story 用于新旧库对比 资料来源:packages/twenty-ui/README.md:130-150。

迁移发布采用分阶段策略:① 用少量非关键 twenty-front 屏 dogfood;② 用 codemod 在 twenty-front、twenty-front-component-renderer、twenty-sdk 三个目标中将 twenty-ui-deprecated 批量替换为 twenty-ui(子路径保留),处理命名差异;③ 替换依赖、跑完整测试 + 视觉 diff 后发布;④ 静默期后移除旧包 资料来源:packages/twenty-ui/README.md:20-40。

在应用与生态中的位置

UI 系统在 Twenty 整体中处于"被消费"位置:被 twenty-front 消费以渲染主应用;被 twenty-front-component-renderer 消费以承载用户在前端组件(front component)中注册的 React 组件。典型应用结构在 postcard 示例中可见——应用通过 src/components/ 声明前端组件,由 Twenty 渲染到工作区 UI 之中 资料来源:packages/twenty-apps/examples/postcard/README.md:1-30。github-connector 等社区应用则演示了命令、面板与仪表盘小部件等多种挂载点 资料来源:packages/twenty-apps/community/github-connector/README.md:1-30。

Codex 插件为开发者提供 create-app、develop-app、manage-app、publish-app、use-twenty-mcp 等技能,涵盖脚手架、组件开发、部署管理与发布流程,与 UI 系统协同支撑扩展生态 资料来源:packages/twenty-codex-plugin/README.md:1-40。用户文档与组件库文档由 Mintlify 驱动的 twenty-docs 站点(docs.twenty.com)发布,提供 95+ 篇页面覆盖用户指南、开发者与 UI 组件库 资料来源:packages/twenty-docs/README.md:1-25。

See Also

• Twenty 应用平台概览
• 主题与设计系统
• 前端组件 SDK

概览

Twenty 是一个以 TypeScript 编写、基于 Nx 构建的 monorepo 项目,后端核心是 NestJS 框架,辅以 BullMQ(基于 Redis 的任务队列)和 PostgreSQL 主数据库。主仓库的 README.md 在"Stack"一节中明确列出了这一技术栈:TypeScript、Nx、NestJS(搭配 BullMQ、PostgreSQL、Redis),共同支撑 CRM 业务能力。Twenty 的后端不仅是单一服务,它既承载核心 CRM 业务对象(联系人、公司、机会等),也作为 Twenty Apps 的执行环境——第三方应用通过 create-twenty-app 脚手架创建后,可以以 logic function(逻辑函数)的形式向 Twenty 服务器注册 HTTP 路由、数据库事件触发器、定时任务等可执行单元,从而把后端能力延伸到应用层。

后端服务架构(NestJS)

后端服务基于 NestJS 模块化设计。在 monorepo 中,核心能力由多个领域模块(domain modules)组合,例如 workspace(工作区)、metadata(元数据)、workflow(工作流)、logic-function(逻辑函数)、database-events(数据库事件)等。这些子路径在共享包 packages/twenty-shared/package.json 的 typesVersions 中都有明确的类型入口声明,例如 dist/workspace/index.d.ts、dist/metadata/index.d.ts、dist/logic-function/index.d.ts 等,反映后端服务的领域划分。

应用层通过"应用包"(application package)进行组织,packages/twenty-shared/package.json 的关键字列表(application、workspace、workflow、logic-function、metadata 等)与上述子路径一一对应,表明后端是围绕工作区与元数据驱动的。

队列与异步任务(BullMQ + Redis)

BullMQ 与 Redis 提供异步任务调度能力,用于处理耗时的后台操作:例如工作流执行、定时任务(cron)、外部系统同步、Webhook 异步处理等。BullMQ 的生产者(Producer)由后端 HTTP 入口或领域事件触发,消费者(Worker)以独立进程或同一 NestJS 应用内的处理器形式运行。

数据库(PostgreSQL)与 Logic Function 扩展

PostgreSQL 是 Twenty 的主数据库,存放工作区数据、对象元数据、字段定义、记录、视图、角色等核心实体。在应用层,create-twenty-app 脚手架为应用暴露了一组可注册的逻辑函数——它们以 HTTP 路由、定时任务或数据库事件触发器等形式运行于 Twenty 后端之上。例如,GitHub 连接器应用注册了 handle-github-webhook(HTTP POST /github/webhook,无认证但带签名校验)以及多个查询接口(count-prs、fetch-prs、count-issues 等);Fireflies 应用则借助 Webhook 把外部会议转写数据写入 Twenty 的 CalendarEvent、Transcript 等自定义对象。这些 logic function 直接读写 PostgreSQL,沿用后端的对象模型与权限系统。

部署、MCP 与扩展点

后端通过 yarn twenty dev 启动开发模式,支持本地热同步应用代码到 Twenty 服务器。Codex 插件 packages/twenty-codex-plugin 进一步把后端操作封装成可被 AI 助手调用的 MCP 服务器,工作区数据访问端点由用户在本地 Codex MCP 配置中自行添加(setup-mcp.sh 辅助脚本会按工作区 host 命名服务器)。这样既保持了后端服务边界的清晰(用户凭据不出本机),又让 AI 工具能够安全地查询与修改工作区记录。

下表汇总了后端核心技术栈及其在仓库中的角色:

flowchart LR
    Client[前端 / 外部客户端] -->|HTTP| NestJS[NestJS 后端]
    NestJS --> PG[(PostgreSQL)]
    NestJS --> Redis[(Redis + BullMQ)]
    App[Twenty App Logic Functions] -->|HTTP/事件| NestJS
    Codex[Codex + MCP] -->|MCP 协议| NestJS
    NestJS --> App

常见失败模式与排障指引

• Docker 未运行导致后端无法启动:create-twenty-app 的 README 在"Troubleshooting"一节中明确指出,服务器无法启动时应先检查 docker info,并通过 yarn twenty docker:logs 查看容器日志。
• 认证失败:yarn twenty remote:add 用于重新配置指向本地 Twenty 服务器的 API Key,适用于远程地址或凭据变更后的场景。
• 类型未生成:yarn twenty dev 会在开发模式下自动生成类型化客户端,若类型缺失,需确认 dev 进程仍在运行。
• Webhook 漏发或缺失:twenty-fireflies 应用指出,在 CalendarEvent 尚未同步时到达的 Fireflies Webhook 可能错过匹配,需要通过"Sync Fireflies Call"工作流工具进行回填或重放。

参见

• 二十应用开发与生命周期
• Logic Function 与工作流引擎
• 部署、CI/CD 与发布到市场

总体架构与技术栈

Twenty CRM 是一个采用 Nx + Yarn Workspaces 组织的 monorepo 项目，以 TypeScript 全栈构建。其基础设施由三层组成：服务端使用 NestJS 框架，叠加 BullMQ 处理异步任务；数据层使用 PostgreSQL 作为主库，Redis 同时承担缓存与队列后端；客户端使用 React 构建 资料来源：README.md:55-66。项目根目录划分多个职责单一的 package：twenty-shared 通过 13 个子路径导出（ai、application、logic-function、workflow、metadata 等）提供跨包共享的类型与工具 资料来源：packages/twenty-shared/package.json:1-50；twenty-client-sdk 暴露 GraphQL/类型生成能力，依赖 @genql/runtime、graphql、esbuild 资料来源：packages/twenty-client-sdk/package.json:36-44；create-twenty-app 是应用脚手架 CLI，强制 Node ≥ 24.5.0、Yarn ≥ 4.0.2 资料来源：packages/create-twenty-app/README.md:1-20；twenty-ui 作为独立的组件库由 Storybook 驱动 资料来源：packages/twenty-ui/README.md:1-30；twenty-docs 由 Mintlify 渲染并发布到 docs.twenty.com 资料来源：packages/twenty-docs/README.md:1-12；twenty-codex-plugin 则是面向 Codex 市场的插件发行载体 资料来源：packages/twenty-codex-plugin/README.md:1-30。

应用生命周期与部署工作流

应用（App）是 Twenty 的核心扩展单元，部署流程由 yarn twenty CLI 统一驱动 资料来源：packages/create-twenty-app/README.md:30-50。开发者通过四步将本地代码推送到目标工作区。

flowchart LR
    A[create-twenty-app<br/>脚手架] --> B[yarn twenty remote:add<br/>注册远程]
    B --> C[yarn twenty dev<br/>热同步开发]
    C --> D[build / deploy / logs<br/>一键发布]
    D --> E[Twenty Workspace<br/>目标实例]

• Step 1 — 脚手架：create-twenty-app 生成符合 src/ 约定的项目结构，所有实体类型（objects、fields、logic functions、front components、workflows、roles、views、agents、page layouts）均有独立子目录 资料来源：packages/twenty-apps/examples/postcard/README.md:15-30。
• Step 2 — 注册远程工作区：yarn twenty remote:add 交互式提示填写本地 Twenty 服务端 URL（默认 http://localhost:2021）与 API Key（来自 Settings -> Developers）资料来源：packages/twenty-apps/community/github-connector/README.md:60-75。
• Step 3 — 开发循环：yarn twenty dev 进入热同步模式，所有代码变更自动重同步到本地 Twenty 服务端 资料来源：packages/twenty-apps/community/github-connector/README.md:65-80。
• Step 4 — 构建与发布：CLI 提供 build、deploy、logs 等子命令；Codex 插件通过 publish-app skill 辅助准备 README、marketplace metadata、logos、screenshots 等发布物料 资料来源：packages/twenty-codex-plugin/README.md:18-28。

基础设施与集成层

MCP 集成采用两层结构：twenty-docs MCP 服务器随插件打包，开箱即用地检索公开文档；用户私有工作区 MCP 端点需通过 bash packages/twenty-codex-plugin/scripts/setup-mcp.sh <host> 写入本地 Codex MCP 配置（按 host 命名，例如 twenty-myworkspace）资料来源：packages/twenty-codex-plugin/README.md:35-55。仓库显式禁止把工作区 URL 提交到插件包内。

Webhook 与外部集成：应用可通过 Logic Function 注册 HTTP 端点接收外部事件，例如 GitHub connector 的 POST /github/webhook（无鉴权、HMAC 签名校验）资料来源：packages/twenty-apps/community/github-connector/README.md:115-130。HMAC 校验要求原始请求体字节，但 Twenty SDK 当前会在路由前解析 JSON，因此官方建议：要么不设置 GITHUB_WEBHOOK_SECRET、依赖难以猜测的 URL + IP 白名单，要么在反代层终止签名校验 资料来源：packages/twenty-apps/community/github-connector/README.md:130-145。

AI/工作流原语：twenty-shared 暴露的 logic-function、workflow、ai、metadata 子路径被服务端、客户端与 SDK 共同消费，确保自定义应用与平台核心 API 类型一致 资料来源：packages/twenty-shared/package.json:8-22。

持续集成、文档与运维

• 视觉回归：twenty-ui 以 Storybook 作为活文档，使用自托管的 Argos 进行像素级对比，并在跨包项目中 diff twenty-ui 与 twenty-ui-deprecated 的同名 story 资料来源：packages/twenty-ui/README.md:25-40。
• 组件库治理：twenty-ui 通过 size-limit 控制每个入口点的 bundle 体积；通过 codemod 在约 1730 个文件中批量替换 twenty-ui-deprecated → twenty-ui，并保留 SCSS Modules + Base UI 的内部实现 资料来源：packages/twenty-ui/README.md:55-75。
• 文档站：packages/twenty-docs 由 Mintlify 驱动，发布到 docs.twenty.com；本地通过 npx nx run twenty-docs:dev 启动（默认 http://localhost:3000）资料来源：packages/twenty-docs/README.md:20-30。
• 客户端 SDK 依赖：@genql/runtime、graphql、lodash、prettier 是运行时依赖，esbuild 负责构建，vitest 负责测试 资料来源：packages/twenty-client-sdk/package.json:36-58。

常见故障模式

• Docker 未运行：服务端启动失败时先 docker info，再 yarn twenty docker:logs 资料来源：packages/create-twenty-app/README.md:55-65。
• 鉴权失败：API Key 过期或工作区切换后需重新执行 yarn twenty remote:add 资料来源：packages/create-twenty-app/README.md:60-70。
• 类型未生成：依赖 yarn twenty dev 后台自动生成 typed client；若 dev 模式未运行则需手动重启 资料来源：packages/create-twenty-app/README.md:65-75。
• Webhook 签名失败：参见上文 HMAC 注意事项，必要时把签名校验下沉到反向代理 资料来源：packages/twenty-apps/community/github-connector/README.md:130-145。

See Also

• create-twenty-app 脚手架与 CLI 详解
• Twenty 应用实体模型与生命周期
• UI 组件库迁移与发布策略
• 官方文档站贡献指南
• Codex 插件与 MCP 集成

一、整体定位与扩展机制概览

Twenty 提供了一套完整的"App 扩展机制"，允许开发者在 CRM 平台之上构建、部署并发布自定义应用。一个 Twenty App 是通过 create-twenty-app 脚手架生成的标准工程，根仓库的 README.md 强调：Apps 是平台的"可编程扩展层"，涵盖对象（Objects）、字段（Fields）、逻辑函数（Logic Functions）、前端组件（Front Components）、视图（Views）、角色（Roles）、导航、工作流、Agents 与 Skills 等多种实体类型。packages/twenty-apps/examples/postcard/README.md 将这些类型整理为一份"实体清单"，是理解扩展边界最权威的索引。

flowchart LR
  A[Twenty SDK / create-twenty-app] --> B[App 工程]
  B --> C1[Objects / Fields]
  B --> C2[Logic Functions]
  B --> C3[Front Components]
  B --> C4[Views / Roles / Navigation]
  B --> C5[Agents / Skills]
  C2 --> D[HTTP 路由<br/>数据库事件<br/>Cron 计划<br/>工具函数<br/>安装钩子]
  C5 --> E[AI 能力<br/>为 Agent 提供上下文]
  C3 --> F[Twenty UI<br/>React 组件渲染]
  B --> G[Remote + Sync + Deploy]
  G --> H[Workspace]

应用的运行与分发依赖 twenty-sdk（见 packages/twenty-sdk/package.json 的 typesVersions），SDK 暴露 application、define、logic-function、front-component、cli、ui 等子路径，CLI 提供 remote:add、dev、build、deploy 等命令。packages/twenty-codex-plugin/README.md 进一步把开发流封装为 Codex 可调用的"技能"，使 AI 编程助手能直接理解与生成 Twenty App。

二、Logic Functions：服务端可编程入口

Logic Functions 是 Twenty 扩展机制中唯一运行在服务端的实体，覆盖绝大多数后端场景。packages/twenty-apps/examples/postcard/README.md 在 src/logic-functions/ 目录下列出了五种触发器：

• HTTP 路由（如 POST /endpoint）—— 处理外部 Webhook 与 API 调用。
• 数据库事件触发器（onRecordCreate / onRecordUpdate / onRecordDelete）—— 在对象记录变更时执行业务逻辑。
• Cron 计划触发器 —— 按计划批量执行。
• 工具函数（tool functions）—— 暴露给工作流构建器与 AI Chat，作为可调用步骤。
• 安装钩子（install hooks）—— 在 App 安装/升级时执行一次性的初始化或迁移。

packages/twenty-apps/internal/twenty-fireflies/README.md 给出了一个完整示例：通过 Sync Fireflies Call 工具函数在 workflow 中按需触发，传入 transcriptId，内部复用 Webhook 同步流水线（拉取转写 + AI 总结、定位匹配的 CalendarEvent、写入 Transcript 与 Summary 字段），并在输出中携带 calendarEventId、updatedFields 与逐字段结果，便于排查部分失败。

packages/twenty-apps/community/github-connector/README.md 进一步展示了 HTTP 触发器的常见模式：所有 Logic Function 形如 count-prs、fetch-prs、handle-github-webhook 等，对应 POST /github/count-prs、POST /github/webhook（无鉴权、签名校验）等路径；Webhooks 的鉴权、签名、重算（recompute-pull-request-reviews）都在 Logic Function 内统一处理。packages/twenty-shared/package.json 同时声明了 logic-function 子路径与 dist/logic-function/index.d.ts，说明 SDK 与 Shared 包都为 Logic Function 提供了类型与工具函数，便于在 App 与 Platform 之间共享契约。

三、Agents：可调度的 AI 单元

Agent 是 Twenty App 中的"AI 执行体"。packages/twenty-apps/examples/postcard/README.md 指出 Agent 文件位于 src/agents/，其最小定义是一个带有系统提示词的 AI 实体，可被工作流、AI Chat 或其它 Logic Function 调用。Agent 与 Logic Function 的关键区别在于：

• Logic Function 是确定性的代码逻辑（TypeScript / JavaScript 运行时）。
• Agent 是概率性的 LLM 推理，其行为由系统提示、可用 Skills、可用工具决定。

Agent 通常复用 Logic Function 暴露的工具（HTTP / database-event / cron），并通过 Skills 获得检索增强上下文。packages/twenty-claude-skills/README.md 展示了另一端的等价能力——twenty-record-presentation Skill 让 Claude 能"以可读形式"呈现 Twenty 记录，证明 Skills 是 Twenty 与外部 AI 编程工具之间的可移植桥。

四、Skills：跨边界的 AI 上下文

Skill 在 Twenty 体系内有两种存在形态：

1. App 内 Skill（src/skills/）：为同一个 App 中的 Agent 提供检索增强上下文，作用域是工作区内的数据。
2. 外部 AI 工具的 Skill 包（如 packages/twenty-claude-skills/、packages/twenty-codex-plugin/skills/）：为 Claude / Codex 等 AI 编程助手提供 Twenty 领域知识与操作手册，作用域是开发者的本地环境。

packages/twenty-codex-plugin/README.md 列举了五类开发型 Skill：create-app、develop-app、manage-app、publish-app、use-twenty-mcp，并通过 AGENTS.md 与 references/ 维护跨 Skill 的操作规则。use-twenty-mcp 借助 setup-mcp.sh 把工作区 MCP 端点写入用户本机配置，遵守"工作区级 MCP 不进入仓库"的设计原则。packages/twenty-claude-skills/README.md 则是这套机制在 Claude 上的镜像：每个 Skill 是一个 SKILL.md，遵守相同的目录约定。

五、典型使用流程与失败模式

最常见的扩展闭环是：

1. 用 create-twenty-app 初始化工程，yarn twenty dev 开启热同步（packages/twenty-apps/community/github-connector/README.md）。
2. 在 src/objects/、src/fields/ 定义数据模型；在 src/logic-functions/ 编写服务端逻辑；在 src/agents/ + src/skills/ 编排 AI 能力。
3. 通过 yarn twenty remote:add 注册工作区，迭代构建、部署、查看日志。
4. 按 packages/twenty-codex-plugin/skills/publish-app/SKILL.md 准备 README、市场元数据、Logo 与截图，发布到 npm / Marketplace。

常见失败模式：把工作区 MCP URL 写进仓库（违反 packages/twenty-codex-plugin/README.md 的"用户本地"原则）；Logic Function 中将 Webhook 路径误设为需鉴权导致回调 401；Agent 未挂载 Skill 导致幻觉（应通过 src/skills/ 注入上下文）；Logic Function 与 Front Component 的类型不一致时应回查 packages/twenty-sdk/package.json 的 typesVersions 校验 dist/logic-function 与 dist/front-component 的导出。

文档体系

Twenty 的官方文档站位于 packages/twenty-docs，由 Mintlify 渲染，线上地址为 docs.twenty.com。源码组织遵循三大目录：

导航结构由 packages/twenty-docs/navigation/base-structure.json 定义，它控制 Tab/分组层级且不上传至 Crowdin。翻译流程是：本地修改后运行 yarn docs:generate-navigation-template 生成 Crowdin 上传的模板 navigation/navigation.template.json，各语种仅提供 packages/twenty-docs/l/<language>/navigation.json 中的 label，slug 始终取自基础结构。本地预览文档的命令为 npx nx run twenty-docs:dev，默认监听 http://localhost:3000（资料来源：packages/twenty-docs/README.md）。

仓库根级 README.md 给出整体技术栈：TypeScript + Nx + NestJS + BullMQ + PostgreSQL + Redis + React。它将读者引向两份关键文档：CRM 功能的 user-guide/introduction 与 Apps 扩展的 developers/extend/apps/getting-started，并在底部提供 Discord、GitHub Discussions、Twitter、LinkedIn 等社区入口（资料来源：README.md）。

运维与开发工具链

Codex 插件

packages/twenty-codex-plugin 是发布到 Codex 市场的官方插件，封装了五个 skill（create-app、develop-app、manage-app、publish-app、use-twenty-mcp），加上公共文档 MCP 服务器 twenty-docs 与一键工作区 MCP 配置脚本 scripts/setup-mcp.sh。其 package.json 声明 setup:mcp、validate、test 三个维护脚本，运行需要 Node ^24.5.0 与 Yarn >=4.0.2，并明确禁止使用 npm（"npm": "please-use-yarn"）。

AGENTS.md 集中存放跨 skill 的操作约定，references/ 子目录提供补充参考文档，开发者不得把工作区特定的 MCP URL 写进插件包，必须放在用户本机的 Codex MCP 配置里（资料来源：packages/twenty-codex-plugin/README.md）。

应用脚手架与运行时

packages/create-twenty-app 提供 create-twenty-app 脚手架与 yarn twenty … CLI 子命令族。典型工作流为：yarn twenty remote:add 注册本地 Twenty 服务（默认 http://localhost:2021），然后 yarn twenty dev 进入实时同步开发模式。

发布产物方面，Postcard 示例应用 packages/twenty-apps/examples/postcard 演示了全部 SDK 实体类型；GitHub Connector packages/twenty-apps/community/github-connector 则给出可独立 dev/install 的复杂集成范例。

共享类型包

跨包共享的类型与工具通过 packages/twenty-shared 暴露，包括 ai、application、database-events、logic-function、workflow、workspace 等子路径，每个子路径在 typesVersions 中声明了对应的 .d.ts 入口，可被其他包以子路径导入做类型消费。

故障排查

服务端基础问题

create-twenty-app 文档给出三类高频问题与修复路径（资料来源：packages/create-twenty-app/README.md）：

1. 服务未启动：先确认 Docker 在运行（docker info），再通过 yarn twenty docker:logs 查看容器日志。
2. 鉴权失败：执行 yarn twenty remote:add 重新绑定 API Key（Key 来自 Twenty UI 的 Settings → Developers）。
3. 类型未生成：确保 yarn twenty dev 正在运行，typed client 由它在后台自动产出。

Codex 插件问题

setup-mcp.sh 按工作区主机名生成 server 标识（如 twenty-myworkspace、twenty-acme），命名冲突时需先清理用户本地 Codex MCP 配置；插件包自身的校验走 node ./scripts/validate.js，单元测试走 node --test ./scripts/__tests__/*.spec.js（资料来源：packages/twenty-codex-plugin/package.json）。

应用集成故障

Fireflies 集成 packages/twenty-apps/internal/twenty-fireflies 针对 Webhook 漏推场景提供 Sync Fireflies Call 工具，可在工作流中按 transcriptId 触发完整管线，实现历史数据回填与失败重放；List Fireflies Calls By Participant 则用于按邮箱检索最近 50 条通话记录。GitHub Connector packages/twenty-apps/community/github-connector 同时给出 yarn twenty dev（实时同步）与一次性 yarn twenty install 两条部署路径，便于在紧密迭代与正式部署之间切换。

UI 包迁移期

twenty-ui 仍在与旧版 twenty-ui-deprecated 并行，其 Argos 视觉对比与 a11y 修复（119 条 a11y: 'todo'）是当前剩余债务。回滚与定位问题时，可参考 packages/twenty-ui/README.md 中的 Phase 0–4 路线图与 codemod 步骤。

操作命令速查

flowchart LR
  A[开发者] --> B[yarn twenty remote:add]
  B --> C{开发模式?}
  C -->|是| D[yarn twenty dev]
  C -->|否| E[yarn twenty install]
  D --> F[二十服务自动同步]
  E --> G[一次性部署到工作区]
  H[维护者] --> I[npx nx run twenty-docs:dev]
  I --> J[本地文档预览]
  K[Codex 用户] --> L[bash packages/twenty-codex-plugin/scripts/setup-mcp.sh host]
  L --> M[写入用户本地 MCP 配置]

参见

• 仓库主文档：README.md
• Mintlify 文档源码：packages/twenty-docs/README.md
• Codex 插件说明：packages/twenty-codex-plugin/README.md
• App 脚手架与 CLI：packages/create-twenty-app/README.md
• 共享类型入口：packages/twenty-shared/package.json

Pitfall Log / 踩坑日志

项目：twentyhq/twenty

摘要：发现 23 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：[self-hosted v2.14.4] TypeError: e.split is not a function on 'New record' in custom view。

1. 安装坑 · 来源证据：[self-hosted v2.14.4] TypeError: e.split is not a function on 'New record' in custom view

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[self-hosted v2.14.4] TypeError: e.split is not a function on 'New record' in custom view
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/twentyhq/twenty/issues/21969 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

2. 安全/权限坑 · 失败模式：security_permissions: Hard Delete Option in Command Menu

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Hard Delete Option in Command Menu
• 对用户的影响：Developers may expose sensitive permissions or credentials: Hard Delete Option in Command Menu
• 证据：failure_mode_cluster:github_issue | https://github.com/twentyhq/twenty/issues/21273 | Hard Delete Option in Command Menu

3. 安全/权限坑 · 来源证据：Hard Delete Option in Command Menu

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Hard Delete Option in Command Menu
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/twentyhq/twenty/issues/21273 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安装坑 · 失败模式：installation: twenty/v2.12.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: twenty/v2.12.0
• 对用户的影响：Upgrade or migration may change expected behavior: twenty/v2.12.0
• 证据：failure_mode_cluster:github_release | https://github.com/twentyhq/twenty/releases/tag/twenty/v2.12.0 | twenty/v2.12.0

5. 安装坑 · 失败模式：installation: v2.7.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v2.7.0
• 对用户的影响：Upgrade or migration may change expected behavior: v2.7.0
• 证据：failure_mode_cluster:github_release | https://github.com/twentyhq/twenty/releases/tag/v2.7.0 | v2.7.0

6. 安装坑 · 失败模式：installation: v2.8.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v2.8.0
• 对用户的影响：Upgrade or migration may change expected behavior: v2.8.0
• 证据：failure_mode_cluster:github_release | https://github.com/twentyhq/twenty/releases/tag/v2.8.0 | v2.8.0

7. 安装坑 · 失败模式：installation: v2.9.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v2.9.0
• 对用户的影响：Upgrade or migration may change expected behavior: v2.9.0
• 证据：failure_mode_cluster:github_release | https://github.com/twentyhq/twenty/releases/tag/v2.9.0 | v2.9.0

8. 安装坑 · 来源证据：Email & Calendar tabs error on custom objects with join-table relations to Person

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Email & Calendar tabs error on custom objects with join-table relations to Person
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/twentyhq/twenty/issues/19676 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

9. 配置坑 · 失败模式：configuration: QuotaExceededError blocks login after upgrading to 2.12.x / 2.13.2

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: QuotaExceededError blocks login after upgrading to 2.12.x / 2.13.2
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: QuotaExceededError blocks login after upgrading to 2.12.x / 2.13.2
• 证据：failure_mode_cluster:github_issue | https://github.com/twentyhq/twenty/issues/21581 | QuotaExceededError blocks login after upgrading to 2.12.x / 2.13.2

10. 配置坑 · 失败模式：configuration: twenty/v2.10

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: twenty/v2.10
• 对用户的影响：Upgrade or migration may change expected behavior: twenty/v2.10
• 证据：failure_mode_cluster:github_release | https://github.com/twentyhq/twenty/releases/tag/twenty/v2.10.0 | twenty/v2.10

11. 配置坑 · 失败模式：configuration: twenty/v2.13.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: twenty/v2.13.0
• 对用户的影响：Upgrade or migration may change expected behavior: twenty/v2.13.0
• 证据：failure_mode_cluster:github_release | https://github.com/twentyhq/twenty/releases/tag/twenty/v2.13.0 | twenty/v2.13.0

12. 配置坑 · 失败模式：configuration: twenty/v2.14.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: twenty/v2.14.0
• 对用户的影响：Upgrade or migration may change expected behavior: twenty/v2.14.0
• 证据：failure_mode_cluster:github_release | https://github.com/twentyhq/twenty/releases/tag/twenty/v2.14.0 | twenty/v2.14.0

13. 配置坑 · 来源证据：Partner marketplace profile links all return 404

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Partner marketplace profile links all return 404
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/twentyhq/twenty/issues/21962 | 来源类型 github_issue 暴露的待验证使用条件。

14. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/twentyhq/twenty | README/documentation is current enough for a first validation pass.

15. 运行坑 · 失败模式：runtime: Email & Calendar tabs error on custom objects with join-table relations to Person

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: Email & Calendar tabs error on custom objects with join-table relations to Person
• 对用户的影响：Developers may hit a documented source-backed failure mode: Email & Calendar tabs error on custom objects with join-table relations to Person
• 证据：failure_mode_cluster:github_issue | https://github.com/twentyhq/twenty/issues/19676 | Email & Calendar tabs error on custom objects with join-table relations to Person

16. 维护坑 · 失败模式：migration: twenty/v2.11.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: twenty/v2.11.0
• 对用户的影响：Upgrade or migration may change expected behavior: twenty/v2.11.0
• 证据：failure_mode_cluster:github_release | https://github.com/twentyhq/twenty/releases/tag/twenty/v2.11.0 | twenty/v2.11.0

17. 维护坑 · 失败模式：migration: v2.6.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v2.6.0
• 对用户的影响：Upgrade or migration may change expected behavior: v2.6.0
• 证据：failure_mode_cluster:github_release | https://github.com/twentyhq/twenty/releases/tag/v2.6.0 | v2.6.0

18. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/twentyhq/twenty | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/twentyhq/twenty | no_demo; severity=medium

20. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/twentyhq/twenty | no_demo; severity=medium

21. 安全/权限坑 · 来源证据：QuotaExceededError blocks login after upgrading to 2.12.x / 2.13.2

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：QuotaExceededError blocks login after upgrading to 2.12.x / 2.13.2
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/twentyhq/twenty/issues/21581 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

22. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/twentyhq/twenty | issue_or_pr_quality=unknown

23. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/twentyhq/twenty | release_recency=unknown