项目概述

Twenty 是一个开源的客户关系管理系统（CRM），致力于为技术团队提供构建企业级 CRM 的模块化解决方案。该项目采用现代技术栈构建，具有 AI 就绪特性，支持企业快速定制和部署属于自己的 CRM 系统。

Twenty 的核心价值主张在于：构建您的竞争对手无法购买的 CRM。作为一个开源项目，Twenty 赋予企业对系统的完全控制权，同时保持灵活性以适应不断变化的业务需求。

资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:8-12]()

核心特性

开源与可扩展性

Twenty 采用开源模式，允许企业自由部署、自托管和深度定制系统。项目采用模块化架构设计，使技术团队能够根据复杂业务需求构建定制化 CRM，同时在业务发展过程中快速适应变化。

资料来源：[packages/twenty-website-new/src/app/[locale]/why-twenty/page.tsx:5-15]()

AI 集成能力

Twenty 被设计为 AI 就绪（AI-ready）系统。传统的 CRM 系统往往只是数据存储库，而 Twenty 正在演变为运营系统（Operating System）。AI 代理可以开始起草外展内容、评分潜在客户、研究客户账户、撰写跟进内容以及更新交易阶段。这些操作都会从 CRM 读取数据并写入 CRM。

资料来源：[packages/twenty-website-new/src/app/[locale]/why-twenty/page.tsx:30-45]()

无代码定制

系统提供无代码配置能力，允许用户在不依赖工程团队的情况下快速修改工作空间。自定义字段、工作流、视图和业务逻辑都可以通过可视化界面完成配置。

资料来源：[packages/twenty-website-new/src/app/[locale]/product/page.tsx:45-52]()

项目架构

Twenty 项目采用 monorepo 结构，主要包含以下核心包：

架构图

graph TB
    subgraph 前端层
        A[packages/twenty-front<br/>前端应用]
        B[packages/twenty-website-new<br/>官网]
    end
    
    subgraph UI 层
        C[packages/twenty-ui<br/>UI 组件库]
    end
    
    subgraph 工具层
        D[packages/create-twenty-app<br/>CLI 工具]
        E[twenty-sdk]
    end
    
    A --> C
    B --> C
    D --> E
    
    style A fill:#e1f5fe
    style C fill:#fff3e0
    style D fill:#f3e5f5

包结构详解

twenty-front

packages/twenty-front 是 Twenty 的核心前端应用，包含 CRM 的主要功能模块。该包使用 React 18 和 TypeScript 构建，采用组件化架构设计。

核心模块包括：

• AI 模块 (src/modules/ai)：包含 LazyMarkdownRenderer 等组件，用于处理 AI 生成内容的渲染和展示
• UI 组件系统：基于 packages/twenty-ui 构建的完整组件生态
• 状态管理：使用 React Context 和自定义 Hook 进行状态管理

资料来源：packages/twenty-front/src/modules/ai/components/LazyMarkdownRenderer.tsx:1-30

twenty-ui

packages/twenty-ui 是 Twenty 的共享 UI 组件库，提供了构建 CRM 界面所需的基础组件。该库使用 Storybook 进行文档化和测试。

主要组件包括：

• Modal 组件：支持多种配置选项（size、padding、overlay）
• Button 组件：支持多种变体（primary、secondary、outlined）和强调色
• 表单组件：输入框、下拉选择器等
• 布局组件：Container、Section 等

资料来源：packages/twenty-ui/src/layout/modal/components/__stories__/Modal.stories.tsx:1-60

twenty-website-new

packages/twenty-website-new 是 Twenty 的官方网站的代码库，基于 Next.js App Router 构建。该包负责展示产品信息、文档、合作伙伴页面和定价页面等。

网站结构包含多个主要页面：

• 首页 (/)：产品介绍和价值主张
• 产品页 (/product)：功能演示和特性展示
• 定价页 (/pricing)：定价方案和计算器
• 合作伙伴页 (/partners)：合作伙伴计划信息
• 客户案例页 (/customers)：成功案例展示
• 文章页 (/articles)：博客和团队文章
• 隐私政策页 (/privacy-policy)：隐私政策文档

资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:1-25]()

create-twenty-app

create-twenty-app 是 Twenty 的官方 CLI 脚手架工具，用于快速创建基于 Twenty CRM 的应用程序。该工具集成 twenty-sdk，为开发者提供开箱即用的项目模板。

快速开始命令：

npx create-twenty-app@latest my-twenty-app
cd my-twenty-app
yarn twenty dev

脚手架工具会自动创建包含 TypeScript、linting 配置和 twenty-sdk 集成的项目结构。

资料来源：packages/create-twenty-app/README.md:1-25

页面组件架构

Twenty 网站的页面采用组件组合模式，主要包含以下结构化组件：

graph LR
    A[Hero 组件] --> B[TrustedBy 组件]
    A --> C[Problem 组件]
    A --> D[ThreeCards 组件]
    A --> E[Faq 组件]
    A --> F[Signoff 组件]
    
    style A fill:#e3f2fd
    style E fill:#e8f5e9
    style F fill:#fff8e1

核心组件列表

国际化

Twenty 项目采用国际化（i18n）设计，所有用户可见的文本都通过 i18n._() 函数包裹，支持多语言切换。国际化配置位于 src/lib/i18n 目录下。

使用示例：

{i18n._(msg`Get started`)}
{i18n._(msg`Stop fighting custom.`)}
{i18n._(msg`Start building, with Twenty`)}

资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:15-22]()

企业级功能

自托管部署

Twenty 支持企业自托管部署，提供完整的许可证激活流程。企业用户可以在完成购买后，通过激活页面将许可证密钥集成到自托管实例中。

资料来源：[packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx:1-20]()

隐私与合规

Twenty 致力于遵守适用的数据保护法规，包括：

• 通用数据保护条例（GDPR）
• 加州消费者隐私法案（CCPA）

官方隐私政策于 2025 年 10 月 13 日生效。

资料来源：[packages/twenty-website-new/src/app/[locale]/privacy-policy/_components/PrivacyPolicyDocument.tsx:1-20]()

技术栈概览

快速开始

开发者可以通过以下方式快速开始使用 Twenty：

1. 体验云端版本：访问 app.twenty.com/welcome
2. 搭建本地开发环境：使用 create-twenty-app CLI 工具
3. 贡献代码：参考项目中的 CLAUDE.md 了解贡献指南

社区与支持

• Discord 社区：discord.gg/cx5n4Jzs57
• 官方网站：twenty.com
• 开源许可证：采用开源许可证（详见 LICENSE 文件）

资料来源：packages/create-twenty-app/README.md:5-8

总结

Twenty 是一个现代化的开源 CRM 平台，专为技术团队设计。它通过模块化架构、AI 集成能力和无代码定制特性，使企业能够构建真正符合自身需求的客户关系管理系统。作为一个活跃的开源项目，Twenty 持续演进，为开源 CRM 生态提供企业级替代方案。

项目架构概览

Twenty 采用 Monorepo 结构管理，使用 Nx 作为构建系统。整体架构分为前端展示层、后端服务层和数据持久层。

graph TD
    subgraph 前端层
        WEB[twenty-website-new<br/>营销网站]
        FRONT[twenty-front<br/>CRM前端应用]
    end
    
    subgraph 服务层
        SERVER[twenty-server<br/>后端服务]
        SDK[twenty-sdk<br/>SDK工具包]
    end
    
    subgraph 工具层
        CLI[create-twenty-app<br/>脚手架工具]
        DOCS[twenty-docs<br/>文档系统]
    end
    
    subgraph 数据层
        DB[(PostgreSQL)]
        CACHE[(Redis)]
    end
    
    WEB --> SERVER
    FRONT --> SERVER
    FRONT --> SDK
    CLI --> SDK
    SERVER --> DB
    SERVER --> CACHE

包结构说明

项目位于 packages/ 目录下，主要包含以下核心包：

前端技术栈

核心框架

前端采用 React 18 作为 UI 框架，结合 TypeScript 提供类型安全。组件化架构支持高度定制化的 CRM 功能开发。

graph LR
    subgraph React生态
        CORE[React Core]
        ROUTER[React Router]
        QUERY[React Query<br/>数据获取]
        FORM[React Hook Form]
    end
    
    subgraph UI层
        COMP[组件库]
        ICONS[图标系统]
        STYLES[样式方案]
    end
    
    CORE --> ROUTER
    CORE --> QUERY
    CORE --> FORM
    ROUTER --> COMP
    QUERY --> COMP

营销网站技术选型

twenty-website-new 包采用 Next.js App Router 架构实现国际化营销站点：

• Next.js 14+：App Router 路由系统
• 国际化方案：基于 i18n._() 的消息提取模式
• 样式方案：CSS Modules + 设计系统变量
• 动态路由：[locale] 动态段支持多语言

关键特性实现

从代码分析可知，前端实现了多项 CRM 核心功能：

后端技术栈

服务端架构

twenty-server 采用模块化的 Node.js 服务架构：

graph TD
    API[API Gateway]
    subgraph 引擎层
        WM[Workspace Manager]
        OBJ[Object Metadata]
        FIELD[Field Metadata]
    end
    
    subgraph 标准应用
        TWENTY_STD[Twenty Standard<br/>Application]
    end
    
    subgraph 数据层
        ORM[ORM Layer]
        DB[(Database)]
    end
    
    API --> WM
    WM --> OBJ
    WM --> FIELD
    OBJ --> TWENTY_STD
    FIELD --> TWENTY_STD
    TWENTY_STD --> ORM
    ORM --> DB

核心依赖

后端服务主要依赖以下技术：

标准对象系统

系统内置标准对象通过 create-standard-flat-object-metadata 工具创建：

• messageThread：消息会话对象
• message：消息记录对象
• noteTarget：笔记关联对象

每个标准对象包含以下元数据属性：

开发者工具链

CLI 脚手架

create-twenty-app 提供快速启动能力：

npx create-twenty-app@latest my-twenty-app
cd my-twenty-app
yarn twenty dev

脚手架自动配置：

• TypeScript 项目结构
• ESLint + Prettier 代码规范
• twenty-sdk 集成
• 开发服务器配置

SDK 工具包

twenty-sdk 是连接应用与 Twenty CRM 的官方开发工具包，封装了：

• GraphQL 客户端
• 认证模块
• 数据操作 API
• 类型定义导出

文档系统

开发者文档架构

twenty-docs 采用 MDX 格式编写文档，支持 Mintlify 文档站点生成：

graph LR
    MDX[MDX 源文件] --> NAV[导航结构]
    NAV --> CROWDIN[国际化 Crowdin]
    CROWDIN --> BUILD[docs.json]
    BUILD --> MINTLIFY[Mintlify 站点]

文档配置要点

构建与部署

Monorepo 构建配置

项目使用 Nx 管理多包构建：

• 依赖关系自动分析
• 增量构建支持
• 任务编排优化
• affected 命令支持

云端部署

Twenty 支持多种部署方式：

企业版激活

企业版通过许可证密钥激活，激活流程：

1. 完成企业版购买
2. 在自托管实例中输入许可证密钥
3. 系统验证并激活高级功能

总结

Twenty 的技术栈设计体现了现代化 CRM 的最佳实践：

• 前后端分离：清晰的职责边界
• TypeScript 全面覆盖：类型安全
• Monorepo 管理：代码复用与统一版本控制
• 模块化架构：易于扩展和维护
• 国际化支持：全球化部署

这套技术架构既保证了系统的稳定性和可扩展性，又为开发者提供了良好的二次开发体验。

概述

Twenty项目采用Nx驱动的Monorepo架构，将前端、后端、文档等多个应用和包组织在单一代码仓库中。这种架构模式便于统一管理依赖、共享代码库、简化CI/CD流程，并确保整个项目的一致性。

核心包结构

Twenty项目的主要包位于packages/目录下，每个包都有独立的职责：

Nx工作区配置

项目根目录的nx.json定义了Monorepo的工作区配置：

{
  "extends": "@nx/next/preset",
  "namedInputs": {
    "default": ["{projectRoot}/**/*"],
    "production": ["!{projectRoot}/**/*.spec.ts"]
  }
}

Nx提供了以下核心能力：

• 增量构建：只重新构建变更影响的包
• 任务编排：管理包之间的构建顺序和依赖关系
• 代码生成：通过生成器创建模块、组件、服务
• 依赖图可视化：展示包之间的依赖关系

前端包结构

twenty-front

主CRM前端应用，包含以下核心目录：

packages/twenty-front/
├── src/
│   └── modules/           # 功能模块
│       ├── ai/            # AI相关组件
│       ├── activities/   # 活动管理
│       ├── companies/     # 公司管理
│       ├── contacts/      # 联系人
│       └── ...           # 其他业务模块

从ThinkingStepsDisplay.tsx可以看到前端组件遵循的约定：

• 使用React functional component
• 样式通过Styled*前缀的组件封装
• 支持TypeScript泛型和严格类型检查

twenty-website-new

新版官方网站采用App Router结构：

packages/twenty-website-new/
├── src/
│   ├── app/
│   │   └── [locale]/      # 国际化路由
│   │       ├── (home)/    # 首页路由组
│   │       ├── articles/  # 文章页面
│   │       ├── releases/  # 发布日志
│   │       ├── customers/ # 客户案例
│   │       ├── partners/  # 合作伙伴
│   │       ├── product/   # 产品页面
│   │       ├── enterprise/# 企业版页面
│   │       ├── why-twenty/# 为什么选择Twenty
│   │       └── privacy-policy/ # 隐私政策
│   ├── sections/          # 可复用页面区块
│   │   ├── Hero/          # 英雄区组件
│   │   ├── Footer/        # 页脚
│   │   ├── CaseStudy/     # 案例研究组件
│   │   ├── AppPreview/    # 应用预览
│   │   └── ...
│   └── content/           # 内容配置
│       └── releases/      # 发布说明MDX

后端包结构

twenty-server

后端服务位于packages/twenty-server/，采用模块化架构：

packages/twenty-server/
└── src/
    └── engine/
        ├── workspace-manager/           # 工作区管理
        │   └── twenty-standard-application/
        │       └── utils/
        │           ├── object-metadata/ # 对象元数据工具
        │           └── field-metadata/   # 字段元数据工具
        └── api/                         # API层

核心模块包括：

• workspace-manager：管理工作区生命周期和标准对象
• twenty-standard-application：标准应用定义，包含如messageThread、message等系统对象
• metadata层：处理元数据的创建和关系映射

文档系统

twenty-docs

文档包使用Mintlify框架，支持国际化：

packages/twenty-docs/
├── navigation/
│   ├── base-structure.json      # 导航基准结构
│   └── navigation.template.json # 翻译模板
├── l/                           # 本地化文件
│   └── <language>/
│       └── navigation.json      # 语言特定导航
├── docs.json                    # 生成的Mintlify配置
└── docs/                        # MDX文档内容

文档导航配置流程：

1. 编辑navigation/base-structure.json定义结构和slug
2. 运行yarn docs:generate-navigation-template生成翻译模板
3. 上传到Crowdin进行翻译
4. 拉取翻译文件到l/<language>/navigation.json
5. 运行yarn docs:generate生成最终配置

依赖关系图

graph TD
    A[nx.json - 工作区配置] --> B[twenty-front]
    A --> C[twenty-server]
    A --> D[twenty-website-new]
    A --> E[twenty-docs]
    
    B --> F[@twenty-ui/* 共享UI组件]
    B --> C[API调用]
    
    C --> G[workspace-manager]
    C --> H[standard-application]
    
    D --> B[复用组件]
    D --> I[content - 发布日志]
    
    E --> J[base-structure.json]
    J --> K[Crowdin翻译]
    K --> L[本地化导航]
    L --> M[docs.json]

常用命令

项目根目录的package.json定义了关键脚本：

页面组件层次结构

Twenty网站的页面采用组件组合模式：

graph TD
    A[Page Component] --> B[Menu.Root]
    A --> C[Hero.Root]
    A --> D[TrustedBy.Root]
    A --> E[Feature Sections]
    A --> F[Testimonials.Root]
    A --> G[Faq.Root]
    A --> H[Signoff.Root]
    A --> I[Footer]
    
    C --> C1[Hero.Heading]
    C --> C2[Hero.Body]
    C --> C3[Hero.Cta]
    C --> C4[Hero.AppPreview]

路由和国际化

网站使用Next.js App Router的[locale]动态路由实现国际化：

src/app/[locale]/
├── (home)/page.tsx      # 首页
├── articles/page.tsx    # 文章列表
├── releases/page.tsx    # 发布日志
├── customers/           # 客户案例
│   └── w3villa/page.tsx
├── product/page.tsx     # 产品页
└── enterprise/
    └── activate/page.tsx

标准对象元数据

后端定义了一系列标准对象（Standard Objects），每个对象都有标准的字段元数据：

这些标准对象通过createStandardFlatObjectMetadata工具函数创建，具有：

• 系统字段（id, createdAt, updatedAt）
• 国际化标签支持（通过i18nLabel）
• 标准图标定义
• 审计日志配置

总结

Twenty的Monorepo结构设计遵循以下原则：

1. 职责分离：每个包有明确的边界和职责
2. 共享代码：通过包内部引用实现代码复用
3. 增量构建：Nx确保只构建受影响的包
4. 国际化：统一的locale路由和翻译管理
5. 模块化组件：网站区块高度可复用

概述

Twenty 项目采用多包架构（monorepo 结构），前端代码分散在多个独立的功能包中，主要包括：

本页面重点介绍 twenty-front 和 twenty-website-new 的前端架构设计。

组件库架构

包结构

twenty/
├── packages/
│   ├── twenty-front/                    # 主应用前端组件
│   │   └── src/modules/ui-library/      # UI组件库核心
│   ├── twenty-website-new/              # 营销网站
│   │   └── src/sections/                # 页面区块组件
│   └── twenty-front-component-renderer/ # 组件渲染器

组件分类

Twenty UI 组件库按功能可分为以下几大类：

核心组件详解

Heading 标题组件

标题组件支持多种字体家族和尺寸配置，用于页面层级的视觉层次表达。

<Heading size="lg" weight="light">
  <HeadingPart fontFamily="serif">
    {i18n._(msg`A modern CRM with`)}
  </HeadingPart>{' '}
  <HeadingPart fontFamily="sans">
    {i18n._(msg`an intuitive interface`)}
  </HeadingPart>
</Heading>

参数说明：

资料来源：[packages/twenty-website-new/src/app/[locale]/product/page.tsx]()

LinkButton 链接按钮

用于页面间导航的按钮组件，支持多种变体和颜色配置。

<LinkButton
  color="primary"
  href="https://app.twenty.com/welcome"
  label={i18n._(msg`Get started`)}
  variant="contained"
/>

变体类型：

资料来源：[packages/twenty-website-new/src/app/[locale]/pricing/page.tsx]()

Hero 英雄区域组件

页面顶部的核心展示区域，包含主标题、描述和行动号召按钮。

<Hero.Root>
  <Hero.Heading page={Pages.Home}>
    <HeadingPart fontFamily="serif">
      {i18n._(msg`Build your Enterprise CRM`)}
    </HeadingPart>{' '}
    <HeadingPart fontFamily="sans">
      {i18n._(msg`at AI Speed`)}
    </HeadingPart>
  </Hero.Heading>
  <Hero.Body page={Pages.Home} size="sm">
    {i18n._(
      msg`Twenty gives technical teams the building blocks...`,
    )}
  </Hero.Body>
  <Hero.Cta>
    <LinkButton ... />
    <TalkToUsButton ... />
  </Hero.Cta>
  <Hero.AppPreview visual={APP_PREVIEW_DATA.visual} />
</Hero.Root>

Hero 子组件结构：

graph TD
    A[Hero.Root] --> B[Hero.Heading]
    A --> C[Hero.Body]
    A --> D[Hero.Cta]
    A --> E[Hero.AppPreview 或 Hero.PartnerVisual 等]

资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx]()

ThreeCards 三卡片布局

用于特性展示的三列卡片布局组件。

<ThreeCards.Root scheme="light">
  <ThreeCards.Intro page={Pages.Home} align="center">
    <Eyebrow>...</Eyebrow>
    <Heading>...</Heading>
  </ThreeCards.Intro>
  <ThreeCards.FeatureCards featureCards={FEATURE_CARDS} />
  <ThreeCards.IllustrationCards 
    illustrationCards={ILLUSTRATION_CARDS} 
    variant="simple" 
  />
</ThreeCards.Root>

参数说明：

资料来源：[packages/twenty-website-new/src/app/[locale]/partners/page.tsx]()

Faq 常见问题组件

可折叠的问答展示组件。

<Faq.Root>
  <Faq.Intro>
    <Eyebrow colorScheme="secondary">...</Eyebrow>
    <Faq.Heading>...</Faq.Heading>
    <Faq.Cta>...</Faq.Cta>
  </Faq.Intro>
  <Faq.Items questions={FAQ_QUESTIONS} />
</Faq.Root>

数据结构：

interface FaqQuestion {
  question: string;
  answer: string;
  category?: string;
}

资料来源：[packages/twenty-website-new/src/app/[locale]/product/page.tsx]()

TrustedBy 信任背书组件

展示合作品牌和客户数量的组件。

<TrustedBy.Root
  separator={i18n._(msg`trusted by`)}
  logos={TRUSTED_BY_LOGOS}
  clientCount={i18n._(msg`+10k others`)}
  cardBackgroundColor={ARTICLES_TOP_BACKGROUND_COLOR}
  compactBottom
/>

参数说明：

资料来源：[packages/twenty-website-new/src/app/[locale]/partners/page.tsx]()

样式系统

Styled Components

Twenty 使用 styled-components 进行样式管理，实现 CSS-in-JS 方案。

const StyledBackDrop = styled.div`
  position: fixed;
  top: 0;
  width: 100%;
  z-index: ${RootStackingContextZIndices.NotFound};
`;

const StyledButtonContainer = styled.div`
  width: 200px;
`;

资料来源：packages/twenty-front/src/pages/not-found/NotFound.tsx

主题配置

组件通过 ThemeProvider 获取主题配置，包括颜色、字体、间距等。

<TrustedBy.Root
  backgroundColor={theme.colors.primary.background[100]}
  ...
/>

配色方案

国际化支持

@lingui 集成

组件使用 @lingui 进行国际化处理，所有用户可见文本都通过 i18n._() 或 msg 宏定义。

import { msg } from '@lingui/macro';

// 静态文本
const label = msg`Get started`;

// 动态文本
{i18n._(
  msg`Twenty gives technical teams the building blocks for a custom CRM...`,
)}

资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx]()

页面构建模式

区块组合模式

Twenty 网站采用区块化设计，通过组合不同 Section 组件构建完整页面。

export default function HomePage() {
  return (
    <>
      <Hero.Root>...</Hero.Root>
      <TrustedBy.Root>...</TrustedBy.Root>
      <Problem.Root>...</Problem.Root>
      <ThreeCards.Root>...</ThreeCards.Root>
      <Feature.Root>...</Feature.Root>
      <Testimonials.Root>...</Testimonials.Root>
      <Faq.Root>...</Faq.Root>
    </>
  );
}

页面结构流程：

graph LR
    A[Hero 英雄区] --> B[TrustedBy 信任背书]
    B --> C[Problem 问题陈述]
    C --> D[ThreeCards 特性卡片]
    D --> E[Feature 功能展示]
    E --> F[Testimonials 客户证言]
    F --> G[Faq 常见问题]

资料来源：[packages/twenty-website-new/src/app/[locale]/customers/page.tsx]()

页面类型枚举

enum Pages {
  Home = 'home',
  Product = 'product',
  Pricing = 'pricing',
  Partners = 'partners',
  Articles = 'articles',
  WhyTwenty = 'whyTwenty',
}

组件渲染器

ComponentRenderer 模块

twenty-front-component-renderer 包提供了动态渲染 UI 组件的能力，支持在运行时根据配置渲染不同组件。

packages/twenty-front-component-renderer/src/

该模块允许：

• 根据数据动态渲染组件
• 支持组件配置化
• 实现运行时主题切换

资料来源：packages/twenty-front-component-renderer/src

Footer 导航数据

Footer 组件使用配置化数据源定义链接和 CTAs。

{
  id: 'footer-product',
  title: msg`Product`,
  ctas: [
    {
      color: 'secondary',
      href: 'https://app.twenty.com/welcome',
      kind: 'link',
      label: msg`Get started`,
      variant: 'outlined',
    },
  ],
  links: [
    {
      label: msg`API & SDKs`,
      href: 'https://docs.twenty.com/api-rest/overview',
      external: true,
    },
  ],
}

Footer 数据结构：

资料来源：packages/twenty-website-new/src/sections/Footer/data.ts

最佳实践

组件组合

使用复合组件模式，通过子组件构建复杂 UI：

<Faq.Root>
  <Faq.Intro>...</Faq.Intro>
  <Faq.Items>...</Faq.Items>
</Faq.Root>

国际化处理

始终使用 i18n._() 或 msg 包装用户可见文本：

// ✅ 正确
<Heading>{i18n._(msg`Welcome`)}</Heading>

// ❌ 错误
<Heading>Welcome</Heading>

样式隔离

使用 styled-components 的样式隔离，避免全局污染：

const StyledContainer = styled.div`
  // 样式定义
`;

可访问性

确保交互组件包含适当的 ARIA 属性：

<Separator aria-hidden="true" />

资料来源：packages/twenty-website-new/src/sections/Salesforce/components/PricingWindow.tsx

总结

Twenty 的 UI 组件库采用模块化设计，通过复合组件模式、配置化数据和国际化支持，构建了一套高效、可维护的前端组件体系。开发者可以通过组合这些基础组件快速构建页面，同时保持视觉一致性和交互体验的统一。

概述

Twenty 的后端架构是整个 CRM 系统的核心，负责处理业务逻辑、数据持久化、API 接口服务以及与 AI 能力的集成。Twenty 后端采用模块化架构设计，支持自托管部署和云端服务两种模式，为企业用户提供灵活的 CRM 解决方案。

后端服务位于 packages/twenty-server/src 目录下，采用 TypeScript 开发，具备良好的类型安全性和代码可维护性。系统核心功能围绕 Companies（公司）、People（联系人）、Opportunities（商机）、Activities（活动） 等 CRM 实体展开，通过统一的 GraphQL API 向前端和其他客户端提供服务。

技术栈概览

Twenty 后端采用现代化的技术栈构建，确保系统具备高性能、可扩展性和易维护性：

模块化架构

Twenty 后端采用 模块化架构（Module-based Architecture），每个功能领域都封装在独立的模块中。这种设计模式确保了代码的高内聚、低耦合，便于团队协作开发和功能扩展。

核心模块结构

graph TD
    A[twenty-server] --> B[modules]
    A --> C[core]
    A --> D[database]
    A --> E[graphql]
    
    B --> B1[companies]
    B --> B2[people]
    B --> B3[opportunities]
    B --> B4[activities]
    B --> B5[calendar]
    B --> B6[ai]
    B --> B7[messaging]
    
    C --> C1[auth]
    C --> C2[config]
    C --> C3[utils]
    
    D --> D1[migrations]
    D --> D2[seeds]

核心模块位于 packages/twenty-server/src/modules 目录下，每个子模块通常包含以下结构：

modules/[module-name]/
├── resolvers/       # GraphQL 解析器
├── services/        # 业务逻辑服务
├── repositories/    # 数据访问层
├── entities/        # 数据库实体定义
├── dto/            # 数据传输对象
└── tests/          # 单元测试

GraphQL API 层

Twenty 通过 GraphQL 提供统一的数据接口，前端和其他客户端可以通过灵活的查询语法获取所需数据。GraphQL 层负责处理客户端请求的解析、权限验证和响应格式化。

API 端点结构

graph LR
    A[Client] -->|GraphQL Query/Mutation| B[GraphQL Server]
    B --> C[Resolver Layer]
    C --> D[Service Layer]
    D --> E[Repository Layer]
    E --> F[(PostgreSQL)]
    
    G[Auth Service] -->|JWT Validation| B
    H[Cache Layer] -->|Redis Cache| D

查询示例

query GetCompaniesWithOpportunities {
  findManyCompany(
    where: { deletedAt: { equals: null } }
    orderBy: { createdAt: Desc }
    take: 10
  ) {
    id
    name
    domain
    opportunities {
      id
      amount
      stage
    }
  }
}

GraphQL API 支持以下主要操作：

数据模型

Twenty 后端定义了丰富的 CRM 数据模型，涵盖企业运营的各个方面。核心实体通过 TypeORM 注解与数据库表映射。

主要实体关系

erDiagram
    COMPANY ||--o{ PERSON : has
    COMPANY ||--o{ OPPORTUNITY : manages
    PERSON ||--o{ ACTIVITY : performs
    OPPORTUNITY ||--o{ ACTIVITY : generates
    USER ||--o{ ACTIVITY : owns
    USER ||--o{ COMPANY : assigns

核心实体说明

认证与授权

Twenty 后端采用 JWT（JSON Web Token） 实现无状态身份验证，用户登录后获取 token，后续请求通过 token 验证用户身份。

认证流程

sequenceDiagram
    participant Client
    participant Server
    participant Database
    
    Client->>Server: POST /auth/login (email, password)
    Server->>Database: 验证用户凭据
    Database-->>Server: 用户数据
    Server->>Server: 生成 JWT Token
    Server-->>Client: { accessToken, refreshToken }
    
    Client->>Server: GET /graphql (Authorization: Bearer <token>)
    Server->>Server: 验证 Token
    Server-->>Client: 请求的数据

权限控制

系统支持基于角色的访问控制（RBAC），不同角色拥有不同的数据操作权限：

移动端支持与 SDK

Twenty 提供 twenty-sdk 作为构建第三方应用的基础，支持开发者基于 Twenty CRM 构建自定义应用。通过官方提供的 create-twenty-app CLI 工具，开发者可以快速初始化项目。

npx create-twenty-app@latest my-twenty-app
cd my-twenty-app
yarn twenty dev

SDK 负责处理以下功能：

• GraphQL API 通信封装
• 身份验证流程管理
• 数据缓存与同步
• 离线模式支持

企业部署与激活

对于企业客户，Twenty 提供自托管部署方案。企业版用户可以通过许可证密钥激活系统，实现完全的数据控制和定制化需求。

激活流程

graph TD
    A[购买企业许可证] --> B[获取许可证密钥]
    B --> C[部署 Twenty 实例]
    C --> D[激活页面配置密钥]
    D --> E{验证密钥}
    E -->|成功| F[启用企业功能]
    E -->|失败| G[检查密钥有效性]
    G --> D

激活相关的前端页面位于 packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx，使用 Suspense 和错误边界组件确保用户体验。

数据库设计

Twenty 使用 PostgreSQL 作为主数据库，通过 TypeORM 实现对象关系映射，支持数据库迁移和种子数据管理。

数据库目录结构

packages/twenty-server/src/database/
├── migrations/          # 数据库迁移脚本
├── seeds/              # 初始化种子数据
└── typeorm/            # 数据库配置

迁移管理

系统支持数据库版本控制，通过迁移脚本确保数据库结构与代码版本同步：

# 运行迁移
yarn database:migrate

# 回滚迁移
yarn database:rollback

# 生成新迁移
yarn database:generate --name=add_new_field

配置管理

Twenty 后端支持灵活的环境配置，通过环境变量和配置文件管理不同部署环境的参数。

配置项说明

开发贡献指南

开发者可以通过以下方式参与 Twenty 后端开发：

1. 本地开发环境：参考 packages/twenty-docs/developers/contribute/capabilities/backend-development 文档
2. 代码规范：遵循项目定义的 ESLint 和 Prettier 配置
3. 测试覆盖：新增功能需包含对应的单元测试和集成测试
4. 提交规范：使用 Conventional Commits 格式描述变更

扩展能力

Twenty 后端设计支持多种扩展方式：

• 自定义对象：创建符合业务需求的 CRM 实体
• 工作流自动化：定义触发器和自动化动作
• API 扩展：通过 Apollo Federation 集成外部服务
• Webhook：与外部系统的事件集成

总结

Twenty 的后端架构采用现代化的模块化设计，通过 GraphQL API 提供灵活的数据接口，支持企业级 CRM 功能的实现。系统具备良好的可扩展性，支持自托管和云端两种部署模式，为不同规模的企业提供可靠的 CRM 解决方案。

概述

Twenty 的数据模型是一个基于元数据驱动（Metadata-Driven）的动态数据架构，它允许用户在不修改代码的情况下自定义数据对象、字段和关系。系统采用 Prisma ORM 作为底层数据库抽象，并通过标准应用层（Twenty Standard Application）定义一组开箱即用的标准对象。

数据模型的核心设计理念：

• 对象（Object）：代表业务实体，如 Company、Person、Opportunity 等
• 字段（Field）：描述对象的属性，包含类型、默认值、验证规则等元信息
• 关系（Relation）：定义对象之间的关联，支持一对一、一对多、多对多
• 工作区隔离：每个工作区拥有独立的数据模型实例，实现多租户隔离

核心组件

标准对象（Standard Objects）

标准对象是 Twenty 内置的业务实体，涵盖 CRM 核心场景：

标准字段（Standard Fields）

每个对象都包含一组标准字段，继承自 BaseWorkspaceEntity 基类：

资料来源：compute-note-target-standard-flat-field-metadata.util.ts:11-49

字段类型（FieldMetadataType）

系统支持多种字段类型：

元数据计算机制

对象元数据创建

标准对象元数据通过 createStandardObjectFlatMetadata 工具函数创建：

createStandardObjectFlatMetadata({
  objectName: 'messageThread',
  dependencyFlatEntityMaps,
  context: {
    universalIdentifier: STANDARD_OBJECTS.messageThread.universalIdentifier,
    nameSingular: 'messageThread',
    namePlural: 'messageThreads',
    labelSingular: i18nLabel(msg`Message Thread`),
    labelPlural: i18nLabel(msg`Message Threads`),
    icon: 'IconMessage',
    isSystem: true,
    isAuditLogged: false,
    labelIdentifierFieldMetadataName: 'subject',
  },
  workspaceId,
  standardObjectMetadataRelatedEntityIds,
  twentyStandardApplicationId,
  now,
})

资料来源：create-standard-flat-object-metadata.util.ts:120-145

字段元数据计算

字段元数据通过专用的计算工具生成。以 noteTarget 对象为例：

createStandardFieldFlatMetadata({
  objectName,
  workspaceId,
  context: {
    fieldName: 'createdAt',
    type: FieldMetadataType.DATE_TIME,
    label: i18nLabel(msg`Creation date`),
    description: i18nLabel(msg`Creation date`),
    icon: 'IconCalendar',
    isSystem: true,
    isNullable: false,
    isUIReadOnly: true,
    defaultValue: 'now',
    settings: {
      displayFormat: DateDisplayFormat.RELATIVE,
    },
  },
  standardObjectMetadataRelatedEntityIds,
  dependencyFlatEntityMaps,
  twentyStandardApplicationId,
  now,
})

资料来源：compute-note-target-standard-flat-field-metadata.util.ts:25-55

工作区数据模型初始化

当用户创建新工作区时，系统执行三步初始化流程：

graph TD
    A[用户提交创建工作区] --> B[Step 1: 设置数据库]
    B --> C[Step 2: 创建数据模型]
    C --> D[Step 3: 预填充工作区数据]
    D --> E[工作区就绪]

资料来源：CreateWorkspace.tsx:1-50

初始化步骤说明

{pendingCreationLoaderStep === PendingCreationLoaderStep.Step1 && (
  <SubTitle>
    <Trans>Setting up your database...</Trans>
  </SubTitle>
)}
{pendingCreationLoaderStep === PendingCreationLoaderStep.Step2 && (
  <SubTitle>
    <Trans>Creating your data model...</Trans>
  </SubTitle>
)}
{pendingCreationLoaderStep === PendingCreationLoaderStep.Step3 && (
  <SubTitle>
    <Trans>Prefilling your workspace data...</Trans>
  </SubTitle>
)}

资料来源：CreateWorkspace.tsx:35-48

数据模型架构图

graph TB
    subgraph 工作区层
        WM[Workspace Manager]
        SM[Standard Metadata]
    end
    
    subgraph 对象层
        CO[Company]
        PE[Person]
        OP[Opportunity]
        NO[Note]
        NOB[NoteTarget]
    end
    
    subgraph 字段层
        ID[BaseFields<br/>id, createdAt, updatedAt]
        CF[Custom Fields]
        RF[Relation Fields]
    end
    
    subgraph 存储层
        PR[Prisma ORM]
        DB[(PostgreSQL)]
    end
    
    WM --> SM
    SM --> CO
    SM --> PE
    SM --> OP
    SM --> NO
    NO --> NOB
    
    CO --> ID
    PE --> ID
    CO --> CF
    PE --> CF
    CO --> RF
    PE --> RF
    
    PR --> DB

字段属性配置

系统字段标记

日期字段显示格式

settings: {
  displayFormat: DateDisplayFormat.RELATIVE,
}

支持的显示格式：

资料来源：compute-blocklist-standard-flat-field-metadata.util.ts:25-60

依赖管理

数据模型采用依赖驱动（Dependency-Driven）的初始化机制。对象之间的依赖关系通过 dependencyFlatEntityMaps 传递：

type FlatFieldMetadata = {
  id: string;
  objectName: string;
  fieldName: string;
  type: FieldMetadataType;
  workspaceId: string;
  isSystem: boolean;
  isNullable: boolean;
  defaultValue: string | null;
};

依赖计算确保父对象先于子对象创建，保证数据完整性。

总结

Twenty 的数据模型采用元数据驱动的设计，通过以下核心机制实现灵活性：

1. 标准对象层：提供开箱即用的 CRM 实体
2. 字段元数据层：支持多种类型和丰富配置
3. 工作区隔离：确保多租户数据安全
4. 依赖解析：保证对象创建顺序正确

该架构允许开发者在不修改核心代码的前提下扩展业务实体，同时通过 Prisma 抽象保证数据库层面的类型安全和迁移管理。

概述

Activities活动模块是Twenty CRM系统中用于管理用户日常业务活动的核心功能模块。该模块涵盖了任务的创建与管理、便笺的记录以及电子邮件线程的查看等关键功能。Activities模块作为Twenty前端架构的重要组成部分，为用户提供了统一的交互界面来处理与客户关系相关的各类活动数据。

Activities模块的设计理念是将分散的业务活动统一到一个集中的管理平台，使用户能够在单一界面内完成从任务分配、进度跟踪到沟通记录的全流程操作。该模块与其他业务对象（如联系人、公司、交易等）紧密集成，确保了数据的关联性和可追溯性。

模块架构

目录结构

Activities模块位于packages/twenty-front/src/modules/activities目录下，采用功能分组的组织方式：

activities/
├── types/                    # 类型定义
│   └── ActivityForEditor.ts  # 编辑器活动类型
├── emails/                   # 邮件相关组件
├── tasks/                    # 任务相关组件
└── calendar/                 # 日历相关组件

核心类型定义

Activities模块的核心类型定义位于ActivityForEditor.ts文件中，定义了用于编辑器场景的活动数据结构：

import { type Note } from '@/activities/types/Note';
import { type Task } from '@/activities/types/Task';

export type ActivityForEditor = Partial<Task | Note> &
  Partial<Pick<Task, 'status' | 'dueAt' | 'assignee' | 'taskTargets'>> &
  Partial<Pick<Note, 'noteTargets'>>;

这个联合类型的设计允许编辑器同时处理Task和Note两种活动类型，并通过Partial和Pick工具类型精确选择所需的字段，确保了类型系统的灵活性和安全性。

功能模块详解

任务模块 (Tasks)

任务模块负责管理和展示用户创建的业务任务。从视觉组件TasksVisual.tsx的实现可以看出，任务系统包含以下核心要素：

任务在界面上以列表形式展示，每个任务项包含完成状态指示器、任务名称和关联的时间戳。用户可以通过点击完成状态指示器来切换任务的完成状态，界面会通过删除线样式（data-strikethrough）来直观展示已完成的任务。

邮件模块 (Emails)

邮件模块提供了邮件线程的查看和管理功能。从EmailsVisual.tsx组件的实现来看，邮件系统包含以下结构：

type EmailsVisualProps = {
  active: boolean;
};

export function EmailsVisual({ active: _active }: EmailsVisualProps) {
  const [openEmail, setOpenEmail] = useState<number | null>(null);
  // ...
}

邮件界面采用标签页式导航设计，包含多个邮件夹选项。每个邮件项展示发件人头像、发件人姓名、邮件主题和时间戳。点击邮件后可以展开查看完整的邮件内容，包括邮件线程中的所有消息记录。

邮件组件的核心数据结构包括：

• DetailHeader：邮件头部区域，显示主题和返回按钮
• DetailSenderRow：发件人信息行，包含头像、名称和时间
• DetailContent：邮件正文内容
• ThreadMessage：线程消息组件

日历模块 (Calendar)

日历模块用于展示和安排与活动相关的时间信息。该模块与任务模块深度集成，支持基于截止日期的时间视图展示。

数据流与状态管理

Activities模块采用了现代化的状态管理模式，组件内部使用React Hooks管理本地状态。以下是典型的状态管理模式：

graph TD
    A[用户操作] --> B[组件状态更新]
    B --> C{状态类型判断}
    C -->|完成状态| D[UI渲染更新]
    C -->|邮件操作| E[邮件列表更新]
    C -->|任务操作| F[任务列表更新]
    D --> G[持久化存储]
    E --> G
    F --> G

状态管理要点

Activities模块中的状态管理包含以下几个关键方面：

1. 本地状态管理：使用useState管理组件级别的状态，如邮件展开状态
2. 条件渲染：根据状态值决定UI展示内容，如根据openEmail === null判断显示邮件列表还是详情
3. 时间控制：支持时间戳的展示和格式化

视觉展示组件

Twenty网站营销页面中的Features模块提供了丰富的可视化演示，展示了Activities功能在实际应用场景中的表现。

任务可视化

TasksVisual.tsx组件展示了任务列表的交互效果：

• 使用ActivityRow作为单个任务行的容器
• 使用TaskCircleEl展示完成状态指示器
• 使用ActivityBody包裹任务主体内容
• 使用Timestamp组件显示任务关联时间

邮件可视化

EmailsVisual.tsx组件模拟了完整的邮件客户端界面：

• 使用TabBar展示邮件分类标签
• 使用InboxHeader展示收件箱头部
• 使用DetailHeader和DetailBody构建邮件详情视图
• 支持邮件线程的展开和折叠

组件关联图

graph LR
    A[Activities模块] --> B[Task任务]
    A --> C[Note便笺]
    A --> D[Email邮件]
    A --> E[Calendar日历]
    B --> F[status]
    B --> G[dueAt]
    B --> H[assignee]
    B --> I[taskTargets]
    C --> J[noteTargets]
    D --> K[subject]
    D --> L[thread]

类型安全设计

Activities模块在TypeScript类型安全方面做了精心设计。ActivityForEditor类型采用了以下设计模式：

1. 联合类型：使用Task | Note表示活动可以是任务或便笺
2. 交叉类型：通过&操作符合并多个类型约束
3. 部分选择：使用Partial<Pick<...>>精确选择需要的字段子集

这种设计模式的优势在于：

• 提供了编译时类型检查
• 支持灵活的数据组合
• 便于扩展新的活动类型

与后端标准对象的关联

Activities模块与后端的数据模型紧密对应。根据服务端代码结构，系统定义了一系列标准对象来支撑活动功能的实现：

这些标准对象定义了系统级别的活动元数据，包括对象名称、标签、图标等配置信息。

总结

Activities活动模块是Twenty CRM系统中连接用户日常业务操作与系统数据管理的核心桥梁。通过任务、便笺、邮件和日历四个子模块的协同工作，该模块为用户提供了完整的活动管理能力。

模块的设计遵循了现代前端开发的最佳实践，包括：

• 清晰的类型定义和类型安全保证
• 模块化的组件结构
• 灵活的状态管理方案
• 与后端标准对象模型的完整对应

这些设计使得Activities模块能够有效支撑企业的客户关系管理需求，同时保持了代码的可维护性和可扩展性。

概述

Views（视图）和 Pipelines（管道）是 Twenty CRM 中两个核心的数据展示与业务流程管理模块。它们共同构成了系统处理和组织工作流数据的基础架构，使企业能够灵活地自定义数据展示方式和管理销售/业务管道流程。

Views 负责定义数据列表的展示方式，包括字段配置、排序规则、筛选条件和显示布局等。Pipelines 则专注于管理业务流程管道，如销售管道中的阶段流转、机会追踪和自动化工作流。

资料来源：packages/twenty-front/src/modules/views 资料来源：packages/twenty-front/src/modules/pipelines

架构设计

模块层级结构

Twenty 采用模块化架构设计，Views 和 Pipelines 作为独立的功能模块存在。以下是整体架构关系：

graph TD
    A[Twenty Frontend] --> B[Views 模块]
    A --> C[Pipelines 模块]
    B --> D[States 状态管理]
    B --> E[Hooks 自定义钩子]
    B --> F[Components 组件]
    C --> G[States 状态管理]
    C --> H[Hooks 自定义钩子]
    C --> I[Components 组件]
    D --> J[recoil 状态Atom]
    G --> J

Views 与 Pipelines 的关系

Views 和 Pipelines 存在紧密的关联关系。Pipeline 视图本质上是一种特殊的 Views 实现，专门用于展示管道阶段和卡片式布局。

graph TD
    A[View] -->|继承| B[BaseView]
    A -->|扩展| C[PipelineView]
    C -->|包含| D[PipelineStages]
    C -->|包含| E[PipelineSteps]
    C -->|包含| F[Opportunities]
    D -->|关联| E

资料来源：packages/twenty-docs/user-guide/views-pipelines

Views 模块详解

模块结构

Views 模块位于 packages/twenty-front/src/modules/views/，包含以下核心子目录：

资料来源：packages/twenty-front/src/modules/views

状态管理

Views 模块使用 Recoil 进行状态管理，主要的状态 Atom 包括：

// 视图配置状态
viewIdState        // 当前视图ID
viewSortsState     // 排序规则
viewFiltersState   // 筛选条件
viewFieldsState    // 字段配置
viewkanbanHideState // 看板隐藏状态

这些状态通过 Selector 进行派生计算，实现视图配置的响应式更新。

资料来源：packages/twenty-front/src/modules/views/states

核心 Hooks

Views 模块提供了多个自定义 Hooks 用于视图操作：

资料来源：packages/twenty-front/src/modules/views/hooks

视图类型

系统支持多种视图类型，每种类型有不同的展示方式和配置选项：

Pipelines 模块详解

模块结构

Pipelines 模块位于 packages/twenty-front/src/modules/pipelines/，是 Views 模块在业务管道场景下的扩展实现：

资料来源：packages/twenty-front/src/modules/pipelines

管道数据模型

classDiagram
    class Pipeline {
        +id: string
        +name: string
        +icon: string
        +stages: PipelineStage[]
    }
    class PipelineStage {
        +id: string
        +name: string
        +color: string
        +position: number
        +opportunities: Opportunity[]
    }
    class Opportunity {
        +id: string
        +title: string
        +companyId: string
        +pipelineStageId: string
        +amount: number
        +probability: number
    }
    
    Pipeline "1" *-- "n" PipelineStage
    PipelineStage "1" *-- "n" Opportunity

状态管理

Pipelines 模块的状态管理基于 Recoil，主要包括：

// 管道状态
pipelinesState           // 所有管道列表
currentPipelineState     // 当前选中管道
pipelineStagesState      // 管道阶段

// 机会状态
opportunitiesState       // 所有机会
opportunitiesByPipelineStageState  // 按阶段分组的机会

资料来源：packages/twenty-front/src/modules/pipelines/states

核心 Hooks

资料来源：packages/twenty-front/src/modules/pipelines/hooks

数据流与工作流程

视图数据加载流程

sequenceDiagram
    participant U as 用户
    participant C as Component
    participant H as Hook
    participant S as State
    participant A as API
    
    U->>C: 选择视图
    C->>H: useView(viewId)
    H->>S: 读取 viewIdState
    S-->>H: 返回视图配置
    H->>A: 请求视图数据
    A-->>H: 返回记录列表
    H->>S: 更新 viewDataState
    S-->>C: 触发重新渲染
    C-->>U: 展示视图数据

管道阶段流转

graph LR
    A[新建机会] --> B[资格筛选]
    B --> C[需求分析]
    C --> D[提案报价]
    D --> E[谈判审核]
    E --> F[成交]
    E --> G[输单]
    
    style A fill:#e1f5fe
    style F fill:#c8e6c9
    style G fill:#ffcdd2

组件系统

Views 组件

Views 模块的组件位于 packages/twenty-front/src/modules/views/components/，主要组件包括：

资料来源：packages/twenty-front/src/modules/views/components

Pipelines 组件

Pipelines 模块的组件位于 packages/twenty-front/src/modules/pipelines/components/：

资料来源：packages/twenty-front/src/modules/pipelines/components

配置与定制

视图配置项

管道配置项

与其他模块的集成

Views 和 Pipelines 模块与以下模块存在集成关系：

graph TD
    V[Views/Pipelines] --> |使用| O[Objects 模块]
    V --> |使用| F[Fields 模块]
    V --> |使用| R[Relations 模块]
    V --> |渲染| UI[UI Components]
    O --> |提供数据模型| D[Data GraphQL]
    F --> |提供字段定义| D

Objects 模块集成

Views 基于 Objects（对象）模块定义的数据模型进行数据展示。每个视图绑定到特定的对象类型，如 "Opportunity"、"Company" 或 "Person"。

Fields 模块集成

视图的字段配置依赖于 Fields 模块的字段定义系统，支持标准字段和自定义字段的动态配置。

用户使用指南

创建新视图

1. 在对象列表页面，点击视图选择器
2. 选择"创建新视图"
3. 配置视图名称、图标和基础设置
4. 配置显示字段、排序规则和筛选条件
5. 保存视图

配置销售管道

1. 进入 Pipelines 设置页面
2. 创建新管道或编辑现有管道
3. 添加/编辑管道阶段
4. 为每个阶段配置颜色和图标
5. 设置阶段流转规则（如有）

资料来源：packages/twenty-docs/user-guide/views-pipelines

最佳实践

视图优化建议

管道设计建议

技术限制与注意事项

• 视图配置存储在服务端，切换视图需要网络请求
• 管道阶段不支持嵌套层级结构
• 大型数据集（>10000 条记录）建议使用服务端分页
• 自定义字段在视图中需要额外配置才能显示

概述

Twenty的Apps扩展系统是一个模块化的应用扩展框架，允许开发者在Twenty CRM平台上构建和部署自定义业务应用程序。该系统采用现代化的插件架构，开发者可以创建独立的应用包，并在Twenty工作区内注册和使用这些应用。

Apps扩展系统的主要目标是：

• 提供标准化的应用开发框架
• 支持前端和后端代码的打包与分发
• 与Twenty核心功能无缝集成
• 支持应用的发现、安装和卸载流程

核心组件

Apps扩展系统由以下几个核心包组成：

应用架构

整体架构

graph TD
    A[开发者] -->|create-twenty-app| B[新建App项目]
    B --> C[实现App功能]
    C --> D[打包应用]
    D --> E[twenty-apps运行时]
    E --> F[Twenty CRM]
    G[twenty-client-sdk] --> C

应用生命周期

stateDiagram-v2
    [*] --> 创建: create-twenty-app
    创建 --> 开发: 编写代码
    开发 --> 调试: 本地测试
    调试 --> 打包: 构建生产版本
    打包 --> 发布: 分发应用
    发布 --> 安装: 用户安装
    安装 --> 激活: 启用功能
    激活 --> 使用: 运行中
    使用 --> 卸载: 用户卸载
    卸载 --> [*]

twenty-client-sdk

客户端SDK是Apps扩展系统的前端核心，提供了构建应用UI所需的React组件和Hooks。

主要导出模块

SDK包位于 packages/twenty-client-sdk/src，包含以下主要导出：

• React hooks：用于数据获取、状态管理和与Twenty后端通信
• UI组件：可复用的Twenty风格组件
• 类型定义：TypeScript类型和接口
• 工具函数：常用业务逻辑封装

使用示例

import { useTwentyClient } from '@twenty/client-sdk';

// 在App中使用Twenty客户端
const MyApp = () => {
  const client = useTwentyClient();
  // 通过client与Twenty后端交互
};

create-twenty-app

create-twenty-app 是Twenty提供的命令行工具，用于快速生成新的App项目脚手架。

命令行接口

npx create-twenty-app@latest my-app

项目结构

新建的应用项目包含以下标准结构：

my-app/
├── src/
│   ├── index.tsx          # 应用入口
│   ├── App.tsx            # 主应用组件
│   └── components/       # 组件目录
├── package.json
├── twenty-app.config.ts  # 应用配置
└── tsconfig.json

应用配置

应用配置文件 twenty-app.config.ts 定义应用的基本信息：

hello-world示例

packages/twenty-apps/examples/hello-world 提供了一个完整的Hello World示例，展示了Apps扩展系统的基本用法。

示例结构

hello-world/
├── src/
│   ├── index.tsx
│   └── App.tsx
├── package.json
└── twenty-app.config.ts

核心实现

示例应用演示了以下关键功能：

1. 入口点定义：通过 index.tsx 导出应用主组件
2. 配置声明：在 package.json 中声明应用元数据
3. 基础UI渲染：使用SDK组件构建简单界面

开发流程

环境准备

1. 安装Node.js (v18+)
2. 安装pnpm包管理器
3. 克隆Twenty仓库

创建新应用

# 使用create-twenty-app创建项目
pnpm create twenty-app my-first-app

# 进入项目目录
cd my-first-app

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

开发规范

• 使用TypeScript进行开发
• 遵循Twenty的设计系统
• 使用SDK提供的类型定义
• 通过配置文件声明应用元数据

打包发布

# 构建生产版本
pnpm build

# 产出物位于 dist/ 目录

与Twenty核心的集成

Apps扩展系统与Twenty CRM核心深度集成，提供以下能力：

数据访问

通过 twenty-client-sdk 访问Twenty的数据模型：

• 读取标准对象（如Company、Person、Opportunity）
• 调用GraphQL API
• 订阅实时数据更新

UI集成

应用UI可以：

• 使用Twenty的设计组件
• 遵循Twenty的主题风格
• 在Twenty的工作区界面中渲染

功能扩展

开发者可以通过App扩展以下功能：

• 自定义数据展示
• 业务工作流自动化
• 第三方服务集成
• 自定义报表和仪表盘

最佳实践

性能优化

1. 使用SDK提供的缓存机制
2. 实现合理的加载状态处理
3. 避免不必要的重新渲染

错误处理

1. 使用try-catch包装API调用
2. 向用户展示友好的错误提示
3. 记录错误日志便于调试

安全性

1. 不在客户端存储敏感凭证
2. 使用Twenty后端进行敏感操作
3. 遵循最小权限原则

相关资源

概述

GitHub Connector 是 Twenty CRM 的一个社区应用集成模块，旨在将 GitHub 平台的数据与 Twenty CRM 系统进行深度整合。该连接器通过 GitHub App 认证机制获取授权，实现对 GitHub 仓库、Issue、Pull Request 以及 Projects (v2) 等数据的同步和展示。

核心功能范围

GitHub Connector 提供了以下核心能力：

认证机制

GitHub App 认证流程

GitHub Connector 使用 GitHub App 认证方式进行授权，这种方式相比传统的 OAuth 更适合服务器端应用。

sequenceDiagram
    participant Connector as GitHub Connector
    participant GitHubAPI as GitHub API
    
    Note over Connector: 初始化配置
    Connector->>GitHubAPI: 使用 App Credentials 发起请求
    GitHubAPI-->>Connector: 返回 Installation Token
    Note over Connector: Token 缓存于内存
    Connector->>GitHubAPI: 使用 Installation Token 访问资源
    GitHubAPI-->>Connector: 返回请求的数据

必需的环境变量

创建 GitHub App

要创建 GitHub App 并配置连接器，请按以下步骤操作：

1. 访问 https://github.com/settings/apps/new 或组织页面 https://github.com/organizations/<org>/settings/apps/new
2. 配置以下 仓库权限：

1. 生成私钥（会下载 .pem 文件）
2. 在组织/用户上安装 App，安装完成后的 URL 中包含安装 ID，格式为 .../installations/12345678
3. 将 App ID、PEM 私钥内容和安装 ID 填入对应的环境变量

Token 管理

GitHub Connector 实现了智能的 Token 缓存机制：

• 连接器使用 App 凭证换取短期有效的安装 Token
• Token 被缓存在内存中
• 在 Token 即将过期前自动刷新
• 所有 GitHub API 调用都通过该安装 Token 进行认证

架构设计

模块结构

github-connector/
├── src/
│   ├── modules/
│   │   └── github/
│   │       ├── services/        # GitHub API 服务层
│   │       ├── types/           # TypeScript 类型定义
│   │       └── utils/           # 工具函数
│   └── index.ts                 # 模块入口
└── README.md

数据流向

graph LR
    A[GitHub API] -->|Installation Token| B[GitHub Connector]
    B -->|同步数据| C[Twenty CRM]
    C -->|存储| D[数据库]
    
    E[用户配置] -->|环境变量| B

集成示例场景

场景一：团队协作数据同步

将开发团队的 GitHub 活动（Issue 分配、PR 审查状态）同步到 CRM 中的相关公司或联系人记录，便于销售团队了解技术支持情况。

场景二：项目管理视图

通过 GitHub Projects (v2) 集成，在 Twenty CRM 中创建与 GitHub 项目进度对齐的任务视图。

场景三：客户案例追踪

对于使用 Twenty CRM 的技术咨询公司，可将客户项目的 GitHub 仓库活动作为交付进度的参考指标。

配置示例

环境变量配置

# 必需配置
GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQD...
-----END PRIVATE KEY-----"
GITHUB_APP_INSTALLATION_ID=12345678
GITHUB_REPOS=octocat/hello-world,octo-org/octo-repo

# 可选配置
GITHUB_PROJECTS=octo-org:1,octo-org:2

仓库列表格式

GITHUB_REPOS 环境变量支持以下格式：

• 单个仓库：owner/repo
• 多个仓库：owner/repo1,owner/repo2,another-owner/another-repo

限制与注意事项

相关资源

• GitHub App 开发文档：https://docs.github.com/en/apps
• Twenty 官方文档：https://docs.twenty.com
• GitHub Connector 源码：https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/community/github-connector

资料来源

• packages/twenty-apps/community/github-connector/README.md

部署方案概览

Twenty 提供以下几种部署方式：

环境要求

硬件要求

• CPU: 最少 2 核，推荐 4 核以上
• 内存: 最少 4GB，推荐 8GB 以上
• 磁盘: 最少 20GB 可用空间

软件要求

• Docker Engine 20.10+
• Docker Compose 2.0+
• Kubernetes 1.24+（如需 K8s 部署）
• Terraform 1.0+（可选）

Docker Compose 部署

Docker Compose 是最简单快速的部署方式，适合单机运行或初步体验。

快速开始

# 克隆仓库
git clone https://github.com/twentyhq/twenty.git
cd twenty/packages/twenty-docker

# 启动所有服务
docker-compose up -d

服务架构

graph TD
    A[用户] --> B[NGINX反向代理]
    B --> C[Twenty Frontend]
    B --> D[Twenty Server]
    C --> E[PostgreSQL]
    D --> E
    D --> F[Redis]
    D --> G[MinIO对象存储]

环境变量配置

创建 .env 文件配置必要的环境变量：

# 基础配置
APP_ENV=production
RELEASE_VERSION=latest

# 数据库配置
POSTGRES_DB=twenty
POSTGRES_USER=twenty
POSTGRES_PASSWORD=your_secure_password

# 存储配置
STORAGE_S3_REGION=us-east-1
STORAGE_S3_BUCKET=twenty-storage
STORAGE_S3_ACCESS_KEY_ID=your_access_key
STORAGE_S3_SECRET_ACCESS_KEY=your_secret_key

# 认证配置
ACCESS_TOKEN_SECRET=your_access_token_secret
LOGIN_TOKEN_SECRET=your_login_token_secret

一键部署脚本

Twenty 提供 1-click.sh 脚本实现自动化部署。

脚本功能

该脚本自动完成以下步骤：

1. 环境检测与依赖验证
2. 配置文件生成
3. Docker 服务启动
4. 数据库初始化
5. 健康检查验证

使用方法

# 下载并执行一键部署脚本
curl -fsSL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/1-click.sh | bash

脚本执行流程

graph TD
    A[执行1-click.sh] --> B{检测Docker环境}
    B -->|缺失| C[提示安装Docker]
    B -->|存在| D[检查docker-compose]
    D --> E[生成配置文件]
    E --> F[拉取镜像]
    F --> G[启动服务]
    G --> H[健康检查]
    H -->|失败| I[回滚并报错]
    H -->|成功| J[部署完成]

Kubernetes 部署

对于生产环境，推荐使用 Kubernetes 进行部署以获得更好的可扩展性和高可用性。

部署步骤

#### 第一步：克隆仓库

git clone https://github.com/twentyhq/twenty.git
cd twenty/packages/twenty-docker/k8s

#### 第二步：自定义配置文件

重要提示：Kubernetes 清单文件和 Terraform 配置文件需要根据实际环境进行自定义。更新占位符和配置以符合您的环境要求。

#### 第三步：使用 Terraform 部署

``bash cd terraform ``

1. 进入 Terraform 目录：

``bash terraform init ``

1. 初始化 Terraform：

``bash terraform plan ``

1. 规划部署：

``bash terraform apply ``

1. 执行部署：

#### 第三步（替代方案）：使用 Kubernetes 清单

``bash kubectl create namespace twentycrm ``

1. 创建命名空间：

``bash kubectl create secret generic -n twentycrm tokens \ --from-literal=accessToken=changeme \ --from-literal=loginToken="changeme" \ --from-literal=refreshToken="changeme" \ --from-literal=fileToken="changeme" ``

1. 创建密钥：

``bash kubectl apply -f deployment.yaml kubectl apply -f service.yaml kubectl apply -f ingress.yaml ``

1. 应用清单文件：

Kubernetes 组件说明

Ingress 配置示例

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: twenty-ingress
  namespace: twentycrm
spec:
  rules:
  - host: your-domain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: twenty-front
            port:
              number: 3000

配置 TLS 证书：

kubectl create secret tls -n twentycrm tls-secret \
  --cert=path/to/cert.pem \
  --key=path/to/key.pem

# 使用 helm 设置 ingress TLS
helm upgrade twenty ./helm/twenty \
  --set server.ingress.tls[0].hosts[0]=$DOMAIN \
  --set server.ingress.tls[0].secretName=tls-secret

Helm Chart 部署

Twenty 提供 Helm Chart 用于 Kubernetes 部署。

安装 Helm Chart

# 添加 Helm 仓库
helm repo add twenty https://charts.twenty.com
helm repo update

# 安装 Twenty
helm install twenty twenty/twenty \
  --namespace twentycrm \
  --create-namespace \
  --values values.yaml

配置参数

存储配置

MinIO 对象存储

Twenty 使用 MinIO 作为默认对象存储解决方案。

storage:
  type: minio
  minio:
    endpoint: minio:9000
    bucket: twenty-storage
    accessKey: minioadmin
    secretKey: minioadmin

外部 S3 兼容存储

如需使用 AWS S3 或其他 S3 兼容存储：

storage:
  type: s3
  s3:
    endpoint: https://s3.amazonaws.com
    region: us-east-1
    bucket: your-bucket
    accessKeyId: your-key
    secretAccessKey: your-secret

数据库配置

PostgreSQL 配置

database:
  enabled: true
  postgres:
    host: postgres
    port: 5432
    database: twenty
    username: twenty
    password: your-password

使用外部数据库

database:
  enabled: false
  externalHost: your-db-host.com
  externalPort: 5432
  externalDatabase: twenty
  externalUsername: twenty
  externalPassword: your-password

运维管理

日志查看

# 查看所有服务日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f server

# Kubernetes 日志
kubectl logs -n twentycrm deployment/twenty-server -f

服务重启

# Docker Compose
docker-compose restart

# Kubernetes
kubectl rollout restart deployment/twenty-server -n twentycrm

数据备份

建议使用 PostgreSQL 的 pg_dump 工具进行数据库备份：

# 数据库备份
docker-compose exec postgres pg_dump -U twenty twenty > backup.sql

# 恢复数据
docker-compose exec -T postgres psql -U twenty twenty < backup.sql

故障排查

常见问题

健康检查

# Docker Compose 健康检查
docker-compose ps

# Kubernetes 健康检查
kubectl get pods -n twentycrm
kubectl describe pod -n twentycrm <pod-name>

资源清理

# 停止并删除容器
docker-compose down -v

# 删除所有镜像
docker-compose down --rmi all

# Kubernetes 清理
kubectl delete namespace twentycrm

安全建议

1. 更换默认密码：部署前务必修改所有默认密码和密钥
2. 启用 HTTPS：生产环境必须使用 TLS 证书
3. 网络隔离：使用 Kubernetes NetworkPolicy 限制服务间通信
4. 定期更新：关注 Twenty 最新版本，及时更新补丁
5. 日志审计：配置日志收集和分析系统

相关文档

• 本地开发环境搭建
• 应用开发指南
• Kubernetes 快速入门
• Helm Chart 详细文档

Pitfall Log / 踩坑日志

项目：twentyhq/twenty

摘要：发现 31 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found。

1. 安装坑 · 来源证据：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8f7dbe9bbbcb4664b1513a32d303b9eb | https://github.com/twentyhq/twenty/issues/20625 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安装坑 · 来源证据：Restart loop after first workspace creation on a fresh self-host install 2.4.0

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Restart loop after first workspace creation on a fresh self-host install 2.4.0
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_45aa2211a5b64bdc84ba3b47e72701ce | https://github.com/twentyhq/twenty/issues/20666 | 来源类型 github_issue 暴露的待验证使用条件。

3. 运行坑 · 来源证据：Cannot use the Add New Button from the list to create Tasks and Notes - Error: Should never occur, encountered unknown…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Cannot use the Add New Button from the list to create Tasks and Notes - Error: Should never occur, encountered unknown fields name in objectMetadataItem task
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_e572dc6d35d74c9ca8d15889a5cdcb12 | https://github.com/twentyhq/twenty/issues/15800 | 来源类型 github_issue 暴露的待验证使用条件。

4. 运行坑 · 来源证据：On record table, relation fields, we only display 3 items even when the cell is larger

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：On record table, relation fields, we only display 3 items even when the cell is larger
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2446ebd3b44b4378b8725f00f1d22023 | https://github.com/twentyhq/twenty/issues/12039 | 来源类型 github_issue 暴露的待验证使用条件。

5. 维护坑 · 来源证据：Notes not editable in People section

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Notes not editable in People section
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_594e914f1db84296ad7d08410941f4ff | https://github.com/twentyhq/twenty/issues/20288 | 来源类型 github_issue 暴露的待验证使用条件。

6. 维护坑 · 来源证据：Object Type translations are not applied to details panel

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Object Type translations are not applied to details panel
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_d961ff61e7ff4bfbb2740d5b00781250 | https://github.com/twentyhq/twenty/issues/19790 | 来源类型 github_issue 暴露的待验证使用条件。

7. 安全/权限坑 · 来源证据：Pagination broken when sorting by multiple fields when first field has duplicates (both REST and Graphql APIs)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Pagination broken when sorting by multiple fields when first field has duplicates (both REST and Graphql APIs)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b5b75503f7ff4e4493c3503f86acf36b | https://github.com/twentyhq/twenty/issues/20520 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

8. 安装坑 · 失败模式：installation: Restart loop after first workspace creation on a fresh self-host install 2.4.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Restart loop after first workspace creation on a fresh self-host install 2.4.0
• 对用户的影响：Developers may fail before the first successful local run: Restart loop after first workspace creation on a fresh self-host install 2.4.0
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Restart loop after first workspace creation on a fresh self-host install 2.4.0. Context: Observed when using docker
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_bbe448d3f1b2e30e0f7697a610dcf4b1 | https://github.com/twentyhq/twenty/issues/20666 | Restart loop after first workspace creation on a fresh self-host install 2.4.0

9. 安装坑 · 失败模式：installation: v1.22.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.22.0
• 对用户的影响：Upgrade or migration may change expected behavior: v1.22.0
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.22.0. Context: Observed during installation or first-run setup.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_7102b6d7804c49862dcef507bd3213a5 | https://github.com/twentyhq/twenty/releases/tag/v1.22.4 | v1.22.0

10. 安装坑 · 来源证据：Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_1807294d92bc4e919fe1baf88520bb3c | https://github.com/twentyhq/twenty/issues/20671 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

11. 配置坑 · 失败模式：configuration: Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync. Context: Observed during version upgrade or migration.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_7fe809524bbc2f0017b2770b4cc3ece0 | https://github.com/twentyhq/twenty/issues/20671 | Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync

12. 配置坑 · 失败模式：configuration: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses. Context: Observed when using docker
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_0bfb9bb57a943450e911d804ce107cbf | https://github.com/twentyhq/twenty/issues/20136 | TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses

13. 配置坑 · 失败模式：configuration: v1.19.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.19.0
• 对用户的影响：Upgrade or migration may change expected behavior: v1.19.0
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.19.0. Context: Observed during version upgrade or migration.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_15301e2ca30bc826383cea157ed32bcb | https://github.com/twentyhq/twenty/releases/tag/v1.19.0 | v1.19.0

14. 配置坑 · 失败模式：configuration: v2.0.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v2.0.0
• 对用户的影响：Upgrade or migration may change expected behavior: v2.0.0
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.0.0. Context: Observed when using docker
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_ab9b1aea9055fca76d3a881c8ee8f317 | https://github.com/twentyhq/twenty/releases/tag/v2.0.0 | v2.0.0

15. 配置坑 · 失败模式：configuration: v2.3.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v2.3.0
• 对用户的影响：Upgrade or migration may change expected behavior: v2.3.0
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.3.0. Context: Observed when using docker
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_05b61500a200d1852774253b2b09cb5f | https://github.com/twentyhq/twenty/releases/tag/v2.3.0 | v2.3.0

16. 配置坑 · 失败模式：configuration: v2.4.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v2.4.0
• 对用户的影响：Upgrade or migration may change expected behavior: v2.4.0
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.4.0. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_c37fffb0f1bdf017e6070e311b099597 | https://github.com/twentyhq/twenty/releases/tag/v2.4.0 | v2.4.0

17. 配置坑 · 来源证据：TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_4abd78a034024d29b94e860fbcb298e6 | https://github.com/twentyhq/twenty/issues/20136 | 来源类型 github_issue 暴露的待验证使用条件。

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

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:572984571 | https://github.com/twentyhq/twenty | README/documentation is current enough for a first validation pass.

19. 运行坑 · 来源证据：Bug(UI): Currency icon not aligned properly

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Bug(UI): Currency icon not aligned properly
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c2c473e13c324a60a1b0ba450f77fb32 | https://github.com/twentyhq/twenty/issues/20640 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

20. 维护坑 · 失败模式：migration: v1.20.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v1.20.0
• 对用户的影响：Upgrade or migration may change expected behavior: v1.20.0
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.20.0. Context: Observed during version upgrade or migration.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_b9ae97dbbd9c277df82d69cda517b768 | https://github.com/twentyhq/twenty/releases/tag/v1.20.0 | v1.20.0

21. 维护坑 · 失败模式：migration: v1.21.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v1.21.0
• 对用户的影响：Upgrade or migration may change expected behavior: v1.21.0
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.21.0. Context: Observed during version upgrade or migration.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_ea380ef68973d4bb1f069cd337fd42af | https://github.com/twentyhq/twenty/releases/tag/v1.21.0 | v1.21.0

22. 维护坑 · 失败模式：migration: v1.23.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v1.23.0
• 对用户的影响：Upgrade or migration may change expected behavior: v1.23.0
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.23.0. Context: Observed during version upgrade or migration.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_d757a9aab11c1a39bfa726eebcb7ab5e | https://github.com/twentyhq/twenty/releases/tag/v1.23.0 | v1.23.0

23. 维护坑 · 失败模式：migration: v2.1.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v2.1.0
• 对用户的影响：Upgrade or migration may change expected behavior: v2.1.0
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.1.0. Context: Observed during version upgrade or migration.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_0bb1a26151a8ea54475ab5fc8c9566c7 | https://github.com/twentyhq/twenty/releases/tag/v2.1.0 | v2.1.0

24. 维护坑 · 失败模式：migration: v2.2.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v2.2.0
• 对用户的影响：Upgrade or migration may change expected behavior: v2.2.0
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.2.0. Context: Observed during version upgrade or migration.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_9cfa053b1c1093a4e4bdfc861bc786ab | https://github.com/twentyhq/twenty/releases/tag/v2.2.0 | v2.2.0

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

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:572984571 | https://github.com/twentyhq/twenty | last_activity_observed missing

26. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:572984571 | https://github.com/twentyhq/twenty | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:572984571 | https://github.com/twentyhq/twenty | no_demo; severity=medium

28. 能力坑 · 失败模式：capability: Bug(UI): BlockNote Editor slash command shows nothing when no matches are found

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Bug(UI): BlockNote Editor slash command shows nothing when no matches are found
• 对用户的影响：Developers may hit a documented source-backed failure mode: Bug(UI): BlockNote Editor slash command shows nothing when no matches are found
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Bug(UI): BlockNote Editor slash command shows nothing when no matches are found. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_494ea45b2d55fcdc06b5b89a25d3dfe0 | https://github.com/twentyhq/twenty/issues/20625 | Bug(UI): BlockNote Editor slash command shows nothing when no matches are found

29. 能力坑 · 失败模式：capability: Bug(UI): Currency icon not aligned properly

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Bug(UI): Currency icon not aligned properly
• 对用户的影响：Developers may hit a documented source-backed failure mode: Bug(UI): Currency icon not aligned properly
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Bug(UI): Currency icon not aligned properly. Context: Observed when using docker
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_5b942675e057e849cb68cf3923b56dce | https://github.com/twentyhq/twenty/issues/20640 | Bug(UI): Currency icon not aligned properly

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:572984571 | https://github.com/twentyhq/twenty | issue_or_pr_quality=unknown

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

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:572984571 | https://github.com/twentyhq/twenty | release_recency=unknown