{
"canonical_name": "twentyhq/twenty",
"compilation_id": "pack_caa2c80779ec47b3acbe6a028f12d5ca",
"created_at": "2026-05-19T06:59:39.672994+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npx create-twenty-app` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npx create-twenty-app",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_c3f73b7e18c24328a4010c55aff90415"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_910e0e5e624ce1088381edf648dfff6a",
"canonical_name": "twentyhq/twenty",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/twentyhq/twenty",
"slug": "twenty",
"source_packet_id": "phit_b988552efc27463abb49ea3c6540001b",
"source_validation_id": "dval_dc0a3e18e3004d02b563af37ede7f8e8"
},
"merchandising": {
"best_for": "需要客户沟通与团队运营能力，并使用 local_cli的用户",
"github_forks": 6438,
"github_stars": 45884,
"one_liner_en": "The open alternative to Salesforce, designed for AI.",
"one_liner_zh": "The open alternative to Salesforce, designed for AI.",
"primary_category": {
"category_id": "customer-team-operations",
"confidence": "high",
"name_en": "Customer & Team Operations",
"name_zh": "客户沟通与团队运营",
"reason": "strong category phrase match from project identity and outcome"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "twenty",
"title_zh": "twenty 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_b988552efc27463abb49ea3c6540001b",
"page_model": {
"artifacts": {
"artifact_slug": "twenty",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npx create-twenty-app",
"label": "Node.js / npx · 官方安装入口",
"source": "https://github.com/twentyhq/twenty#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"流程自动化",
"节点式流程编排",
"本地优先"
],
"eyebrow": "客户沟通与团队运营",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要客户沟通与团队运营能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "The open alternative to Salesforce, designed for AI."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_8f7dbe9bbbcb4664b1513a32d303b9eb | https://github.com/twentyhq/twenty/issues/20625 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Restart loop after first workspace creation on a fresh self-host install 2.4.0",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_45aa2211a5b64bdc84ba3b47e72701ce | https://github.com/twentyhq/twenty/issues/20666 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Restart loop after first workspace creation on a fresh self-host install 2.4.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "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",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_e572dc6d35d74c9ca8d15889a5cdcb12 | https://github.com/twentyhq/twenty/issues/15800 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Cannot use the Add New Button from the list to create Tasks and Notes - Error: Should never occur, encountered unknown…",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：On record table, relation fields, we only display 3 items even when the cell is larger",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_2446ebd3b44b4378b8725f00f1d22023 | https://github.com/twentyhq/twenty/issues/12039 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：On record table, relation fields, we only display 3 items even when the cell is larger",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Notes not editable in People section",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_594e914f1db84296ad7d08410941f4ff | https://github.com/twentyhq/twenty/issues/20288 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Notes not editable in People section",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Object Type translations are not applied to details panel",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_d961ff61e7ff4bfbb2740d5b00781250 | https://github.com/twentyhq/twenty/issues/19790 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Object Type translations are not applied to details panel",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Pagination broken when sorting by multiple fields when first field has duplicates (both REST and Graphql APIs)",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_b5b75503f7ff4e4493c3503f86acf36b | https://github.com/twentyhq/twenty/issues/20520 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Pagination broken when sorting by multiple fields when first field has duplicates (both REST and Graphql APIs)",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "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",
"category": "安装坑",
"evidence": [
"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"
],
"severity": "medium",
"suggested_check": "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",
"title": "失败模式：installation: Restart loop after first workspace creation on a fresh self-host install 2.4.0",
"user_impact": "Developers may fail before the first successful local run: Restart loop after first workspace creation on a fresh self-host install 2.4.0"
},
{
"body": "Developers should check this installation risk before relying on the project: v1.22.0",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_7102b6d7804c49862dcef507bd3213a5 | https://github.com/twentyhq/twenty/releases/tag/v1.22.4 | v1.22.0"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: v1.22.0. Context: Observed during installation or first-run setup.",
"title": "失败模式：installation: v1.22.0",
"user_impact": "Upgrade or migration may change expected behavior: v1.22.0"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_1807294d92bc4e919fe1baf88520bb3c | https://github.com/twentyhq/twenty/issues/20671 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "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",
"category": "配置坑",
"evidence": [
"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"
],
"severity": "medium",
"suggested_check": "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.",
"title": "失败模式：configuration: Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync",
"user_impact": "Developers may misconfigure credentials, environment, or host setup: Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync"
},
{
"body": "Developers should check this configuration risk before relying on the project: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses",
"category": "配置坑",
"evidence": [
"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"
],
"severity": "medium",
"suggested_check": "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",
"title": "失败模式：configuration: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses",
"user_impact": "Developers may misconfigure credentials, environment, or host setup: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses"
},
{
"body": "Developers should check this configuration risk before relying on the project: v1.19.0",
"category": "配置坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_15301e2ca30bc826383cea157ed32bcb | https://github.com/twentyhq/twenty/releases/tag/v1.19.0 | v1.19.0"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: v1.19.0. Context: Observed during version upgrade or migration.",
"title": "失败模式：configuration: v1.19.0",
"user_impact": "Upgrade or migration may change expected behavior: v1.19.0"
},
{
"body": "Developers should check this configuration risk before relying on the project: v2.0.0",
"category": "配置坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_ab9b1aea9055fca76d3a881c8ee8f317 | https://github.com/twentyhq/twenty/releases/tag/v2.0.0 | v2.0.0"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: v2.0.0. Context: Observed when using docker",
"title": "失败模式：configuration: v2.0.0",
"user_impact": "Upgrade or migration may change expected behavior: v2.0.0"
},
{
"body": "Developers should check this configuration risk before relying on the project: v2.3.0",
"category": "配置坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_05b61500a200d1852774253b2b09cb5f | https://github.com/twentyhq/twenty/releases/tag/v2.3.0 | v2.3.0"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: v2.3.0. Context: Observed when using docker",
"title": "失败模式：configuration: v2.3.0",
"user_impact": "Upgrade or migration may change expected behavior: v2.3.0"
},
{
"body": "Developers should check this configuration risk before relying on the project: v2.4.0",
"category": "配置坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_c37fffb0f1bdf017e6070e311b099597 | https://github.com/twentyhq/twenty/releases/tag/v2.4.0 | v2.4.0"
],
"severity": "medium",
"suggested_check": "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.",
"title": "失败模式：configuration: v2.4.0",
"user_impact": "Upgrade or migration may change expected behavior: v2.4.0"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 31 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 627,
"forks": 6438,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 45884
},
"source_url": "https://github.com/twentyhq/twenty",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "The open alternative to Salesforce, designed for AI.",
"title": "twenty 能力包",
"trial_prompt": "# twenty - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 twenty 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的客户沟通与团队运营任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-tech-stack：技术栈概览。围绕“技术栈概览”模拟一次用户任务，不展示安装或运行结果。\n3. page-monorepo-structure：Monorepo结构。围绕“Monorepo结构”模拟一次用户任务，不展示安装或运行结果。\n4. page-frontend-architecture：前端架构。围绕“前端架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-server-architecture：后端架构。围绕“后端架构”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-tech-stack\n输入：用户提供的“技术栈概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-monorepo-structure\n输入：用户提供的“Monorepo结构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-frontend-architecture\n输入：用户提供的“前端架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-server-architecture\n输入：用户提供的“后端架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-tech-stack：Step 2 必须围绕“技术栈概览”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-monorepo-structure：Step 3 必须围绕“Monorepo结构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-frontend-architecture：Step 4 必须围绕“前端架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-server-architecture：Step 5 必须围绕“后端架构”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/twentyhq/twenty\n- https://github.com/twentyhq/twenty#readme\n- .cursor/skills/syncable-entity-builder-and-validation/SKILL.md\n- .cursor/skills/syncable-entity-cache-and-transform/SKILL.md\n- .cursor/skills/syncable-entity-integration/SKILL.md\n- .cursor/skills/syncable-entity-runner-and-actions/SKILL.md\n- .cursor/skills/syncable-entity-testing/SKILL.md\n- .cursor/skills/syncable-entity-types-and-constants/SKILL.md\n- packages/twenty-claude-skills/skills/twenty-record-presentation/SKILL.md\n- README.md\n- package.json\n- CLAUDE.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 twenty 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Pagination broken when sorting by multiple fields when first field has d（https://github.com/twentyhq/twenty/issues/20520）；github/github_issue: Cannot use the Add New Button from the list to create Tasks and Notes - （https://github.com/twentyhq/twenty/issues/15800）；github/github_issue: Notes not editable in People section（https://github.com/twentyhq/twenty/issues/20288）；github/github_issue: On record table, relation fields, we only display 3 items even when the （https://github.com/twentyhq/twenty/issues/12039）；github/github_issue: Object Type translations are not applied to details panel（https://github.com/twentyhq/twenty/issues/19790）；github/github_issue: Bug(UI): BlockNote Editor slash command shows nothing when no matches ar（https://github.com/twentyhq/twenty/issues/20625）；github/github_issue: Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR d（https://github.com/twentyhq/twenty/issues/20671）；github/github_issue: TypeError in RestApiService swallows internal network errors, resulting （https://github.com/twentyhq/twenty/issues/20136）；github/github_issue: Bug(UI): BlockNote Editor slash command shows nothing when no matches ar（https://github.com/twentyhq/twenty/issues/20625）；github/github_issue: Restart loop after first workspace creation on a fresh self-host install（https://github.com/twentyhq/twenty/issues/20666）；github/github_issue: Bug(UI): Currency icon not aligned properly（https://github.com/twentyhq/twenty/issues/20640）；github/github_release: v2.4.0（https://github.com/twentyhq/twenty/releases/tag/v2.4.0）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Pagination broken when sorting by multiple fields when first field has d",
"url": "https://github.com/twentyhq/twenty/issues/20520"
},
{
"kind": "github_issue",
"source": "github",
"title": "Cannot use the Add New Button from the list to create Tasks and Notes - ",
"url": "https://github.com/twentyhq/twenty/issues/15800"
},
{
"kind": "github_issue",
"source": "github",
"title": "Notes not editable in People section",
"url": "https://github.com/twentyhq/twenty/issues/20288"
},
{
"kind": "github_issue",
"source": "github",
"title": "On record table, relation fields, we only display 3 items even when the ",
"url": "https://github.com/twentyhq/twenty/issues/12039"
},
{
"kind": "github_issue",
"source": "github",
"title": "Object Type translations are not applied to details panel",
"url": "https://github.com/twentyhq/twenty/issues/19790"
},
{
"kind": "github_issue",
"source": "github",
"title": "Bug(UI): BlockNote Editor slash command shows nothing when no matches ar",
"url": "https://github.com/twentyhq/twenty/issues/20625"
},
{
"kind": "github_issue",
"source": "github",
"title": "Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR d",
"url": "https://github.com/twentyhq/twenty/issues/20671"
},
{
"kind": "github_issue",
"source": "github",
"title": "TypeError in RestApiService swallows internal network errors, resulting ",
"url": "https://github.com/twentyhq/twenty/issues/20136"
},
{
"kind": "github_issue",
"source": "github",
"title": "Bug(UI): BlockNote Editor slash command shows nothing when no matches ar",
"url": "https://github.com/twentyhq/twenty/issues/20625"
},
{
"kind": "github_issue",
"source": "github",
"title": "Restart loop after first workspace creation on a fresh self-host install",
"url": "https://github.com/twentyhq/twenty/issues/20666"
},
{
"kind": "github_issue",
"source": "github",
"title": "Bug(UI): Currency icon not aligned properly",
"url": "https://github.com/twentyhq/twenty/issues/20640"
},
{
"kind": "github_release",
"source": "github",
"title": "v2.4.0",
"url": "https://github.com/twentyhq/twenty/releases/tag/v2.4.0"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "客户沟通与团队运营",
"desc": "The open alternative to Salesforce, designed for AI.",
"effort": "安装已验证",
"forks": 6438,
"icon": "users",
"name": "twenty 能力包",
"risk": "可发布",
"slug": "twenty",
"stars": 45884,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"流程自动化",
"节点式流程编排",
"本地优先"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/twentyhq/twenty 项目说明书\n\n生成时间：2026-05-18 21:19:12 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [技术栈概览](#page-tech-stack)\n- [Monorepo结构](#page-monorepo-structure)\n- [前端架构](#page-frontend-architecture)\n- [UI组件库](#page-ui-components)\n- [后端架构](#page-server-architecture)\n- [数据模型](#page-database-models)\n- [Activities活动模块](#page-activities-module)\n- [Views与Pipelines](#page-views-pipelines)\n- [Apps扩展系统](#page-apps-system)\n- [GitHub Connector示例](#page-github-connector)\n- [Docker部署](#page-docker-deployment)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[技术栈概览](#page-tech-stack), [Monorepo结构](#page-monorepo-structure)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/twentyhq/twenty/blob/main/README.md)\n- [packages/twenty-website-new/src/app/[locale]/(home)/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/(home)/page.tsx)\n- [packages/create-twenty-app/README.md](https://github.com/twentyhq/twenty/blob/main/packages/create-twenty-app/README.md)\n- [packages/twenty-front/src/modules/ai/components/LazyMarkdownRenderer.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/ai/components/LazyMarkdownRenderer.tsx)\n- [packages/twenty-ui/src/layout/modal/components/__stories__/Modal.stories.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-ui/src/layout/modal/components/__stories__/Modal.stories.tsx)\n \n\n# 项目介绍\n\n## 项目概述\n\nTwenty 是一个开源的客户关系管理系统（CRM），致力于为技术团队提供构建企业级 CRM 的模块化解决方案。该项目采用现代技术栈构建，具有 AI 就绪特性，支持企业快速定制和部署属于自己的 CRM 系统。\n\nTwenty 的核心价值主张在于：**构建您的竞争对手无法购买的 CRM**。作为一个开源项目，Twenty 赋予企业对系统的完全控制权，同时保持灵活性以适应不断变化的业务需求。\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:8-12]()\n\n## 核心特性\n\n### 开源与可扩展性\n\nTwenty 采用开源模式，允许企业自由部署、自托管和深度定制系统。项目采用模块化架构设计，使技术团队能够根据复杂业务需求构建定制化 CRM，同时在业务发展过程中快速适应变化。\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/why-twenty/page.tsx:5-15]()\n\n### AI 集成能力\n\nTwenty 被设计为 AI 就绪（AI-ready）系统。传统的 CRM 系统往往只是数据存储库，而 Twenty 正在演变为运营系统（Operating System）。AI 代理可以开始起草外展内容、评分潜在客户、研究客户账户、撰写跟进内容以及更新交易阶段。这些操作都会从 CRM 读取数据并写入 CRM。\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/why-twenty/page.tsx:30-45]()\n\n### 无代码定制\n\n系统提供无代码配置能力，允许用户在不依赖工程团队的情况下快速修改工作空间。自定义字段、工作流、视图和业务逻辑都可以通过可视化界面完成配置。\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/product/page.tsx:45-52]()\n\n## 项目架构\n\nTwenty 项目采用 monorepo 结构，主要包含以下核心包：\n\n| 包名 | 说明 | 技术栈 |\n|------|------|--------|\n| `packages/twenty-front` | 前端应用 | React, TypeScript |\n| `packages/twenty-ui` | UI 组件库 | React, Storybook |\n| `packages/twenty-website-new` | 官网与文档 | Next.js |\n| `packages/create-twenty-app` | CLI 脚手架工具 | Node.js |\n\n### 架构图\n\n```mermaid\ngraph TB\n subgraph 前端层\n A[packages/twenty-front
前端应用]\n B[packages/twenty-website-new
官网]\n end\n \n subgraph UI 层\n C[packages/twenty-ui
UI 组件库]\n end\n \n subgraph 工具层\n D[packages/create-twenty-app
CLI 工具]\n E[twenty-sdk]\n end\n \n A --> C\n B --> C\n D --> E\n \n style A fill:#e1f5fe\n style C fill:#fff3e0\n style D fill:#f3e5f5\n```\n\n## 包结构详解\n\n### twenty-front\n\n`packages/twenty-front` 是 Twenty 的核心前端应用，包含 CRM 的主要功能模块。该包使用 React 18 和 TypeScript 构建，采用组件化架构设计。\n\n核心模块包括：\n\n- **AI 模块** (`src/modules/ai`)：包含 `LazyMarkdownRenderer` 等组件，用于处理 AI 生成内容的渲染和展示\n- **UI 组件系统**：基于 `packages/twenty-ui` 构建的完整组件生态\n- **状态管理**：使用 React Context 和自定义 Hook 进行状态管理\n\n资料来源：[packages/twenty-front/src/modules/ai/components/LazyMarkdownRenderer.tsx:1-30]()\n\n### twenty-ui\n\n`packages/twenty-ui` 是 Twenty 的共享 UI 组件库，提供了构建 CRM 界面所需的基础组件。该库使用 Storybook 进行文档化和测试。\n\n主要组件包括：\n\n- **Modal 组件**：支持多种配置选项（`size`、`padding`、`overlay`）\n- **Button 组件**：支持多种变体（`primary`、`secondary`、`outlined`）和强调色\n- **表单组件**：输入框、下拉选择器等\n- **布局组件**：Container、Section 等\n\n资料来源：[packages/twenty-ui/src/layout/modal/components/__stories__/Modal.stories.tsx:1-60]()\n\n### twenty-website-new\n\n`packages/twenty-website-new` 是 Twenty 的官方网站的代码库，基于 Next.js App Router 构建。该包负责展示产品信息、文档、合作伙伴页面和定价页面等。\n\n网站结构包含多个主要页面：\n\n- 首页 (`/`)：产品介绍和价值主张\n- 产品页 (`/product`)：功能演示和特性展示\n- 定价页 (`/pricing`)：定价方案和计算器\n- 合作伙伴页 (`/partners`)：合作伙伴计划信息\n- 客户案例页 (`/customers`)：成功案例展示\n- 文章页 (`/articles`)：博客和团队文章\n- 隐私政策页 (`/privacy-policy`)：隐私政策文档\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:1-25]()\n\n### create-twenty-app\n\n`create-twenty-app` 是 Twenty 的官方 CLI 脚手架工具，用于快速创建基于 Twenty CRM 的应用程序。该工具集成 `twenty-sdk`，为开发者提供开箱即用的项目模板。\n\n快速开始命令：\n\n```bash\nnpx create-twenty-app@latest my-twenty-app\ncd my-twenty-app\nyarn twenty dev\n```\n\n脚手架工具会自动创建包含 TypeScript、linting 配置和 twenty-sdk 集成的项目结构。\n\n资料来源：[packages/create-twenty-app/README.md:1-25]()\n\n## 页面组件架构\n\nTwenty 网站的页面采用组件组合模式，主要包含以下结构化组件：\n\n```mermaid\ngraph LR\n A[Hero 组件] --> B[TrustedBy 组件]\n A --> C[Problem 组件]\n A --> D[ThreeCards 组件]\n A --> E[Faq 组件]\n A --> F[Signoff 组件]\n \n style A fill:#e3f2fd\n style E fill:#e8f5e9\n style F fill:#fff8e1\n```\n\n### 核心组件列表\n\n| 组件名称 | 用途 | 常见页面 |\n|----------|------|----------|\n| `Hero` | 首屏大图和主标题 | 所有页面 |\n| `TrustedBy` | 客户信任展示 | 首页、定价、合作伙伴 |\n| `Problem` | 问题陈述 | 首页 |\n| `ThreeCards` | 三栏特性卡片 | 首页、合作伙伴、产品 |\n| `Editorial` | 编辑风格内容区块 | Why Twenty 页面 |\n| `Faq` | 常见问题解答 | 所有营销页面 |\n| `Signoff` | 行动召唤区块 | 所有页面 |\n| `Testimonials` | 用户推荐轮播 | 首页、合作伙伴 |\n| `Demo` | 产品演示区块 | 产品页 |\n\n## 国际化\n\nTwenty 项目采用国际化（i18n）设计，所有用户可见的文本都通过 `i18n._()` 函数包裹，支持多语言切换。国际化配置位于 `src/lib/i18n` 目录下。\n\n使用示例：\n\n```tsx\n{i18n._(msg`Get started`)}\n{i18n._(msg`Stop fighting custom.`)}\n{i18n._(msg`Start building, with Twenty`)}\n```\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:15-22]()\n\n## 企业级功能\n\n### 自托管部署\n\nTwenty 支持企业自托管部署，提供完整的许可证激活流程。企业用户可以在完成购买后，通过激活页面将许可证密钥集成到自托管实例中。\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx:1-20]()\n\n### 隐私与合规\n\nTwenty 致力于遵守适用的数据保护法规，包括：\n\n- 通用数据保护条例（GDPR）\n- 加州消费者隐私法案（CCPA）\n\n官方隐私政策于 2025 年 10 月 13 日生效。\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/privacy-policy/_components/PrivacyPolicyDocument.tsx:1-20]()\n\n## 技术栈概览\n\n| 领域 | 技术选择 |\n|------|----------|\n| 前端框架 | React 18, Next.js |\n| 语言 | TypeScript |\n| UI 组件 | twenty-ui (内部库) |\n| 状态管理 | React Context, Hooks |\n| 样式方案 | CSS-in-JS, Theme System |\n| 国际化 | 自定义 i18n 方案 |\n| 测试 | Storybook, Testing Library |\n| 包管理 | Yarn, npm |\n\n## 快速开始\n\n开发者可以通过以下方式快速开始使用 Twenty：\n\n1. **体验云端版本**：访问 [app.twenty.com/welcome](https://app.twenty.com/welcome)\n2. **搭建本地开发环境**：使用 `create-twenty-app` CLI 工具\n3. **贡献代码**：参考项目中的 `CLAUDE.md` 了解贡献指南\n\n## 社区与支持\n\n- **Discord 社区**：[discord.gg/cx5n4Jzs57](https://discord.gg/cx5n4Jzs57)\n- **官方网站**：[twenty.com](https://twenty.com)\n- **开源许可证**：采用开源许可证（详见 LICENSE 文件）\n\n资料来源：[packages/create-twenty-app/README.md:5-8]()\n\n## 总结\n\nTwenty 是一个现代化的开源 CRM 平台，专为技术团队设计。它通过模块化架构、AI 集成能力和无代码定制特性，使企业能够构建真正符合自身需求的客户关系管理系统。作为一个活跃的开源项目，Twenty 持续演进，为开源 CRM 生态提供企业级替代方案。\n\n---\n\n\n\n## 技术栈概览\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [前端架构](#page-frontend-architecture), [后端架构](#page-server-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/twentyhq/twenty/blob/main/package.json)\n- [nx.json](https://github.com/twentyhq/twenty/blob/main/nx.json)\n- [packages/twenty-front/package.json](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/package.json)\n- [packages/twenty-server/package.json](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/package.json)\n- [packages/twenty-website-new/package.json](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/package.json)\n- [packages/twenty-docs/package.json](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/package.json)\n- [packages/create-twenty-app/README.md](https://github.com/twentyhq/twenty/blob/main/packages/create-twenty-app/README.md)\n \n\n# 技术栈概览\n\nTwenty 是一个开源的企业级 CRM 系统，采用现代化的全栈技术架构。本页面详细介绍整个项目的技术选型、核心依赖和架构设计。\n\n## 项目架构概览\n\nTwenty 采用 **Monorepo** 结构管理，使用 Nx 作为构建系统。整体架构分为前端展示层、后端服务层和数据持久层。\n\n```mermaid\ngraph TD\n subgraph 前端层\n WEB[twenty-website-new
营销网站]\n FRONT[twenty-front
CRM前端应用]\n end\n \n subgraph 服务层\n SERVER[twenty-server
后端服务]\n SDK[twenty-sdk
SDK工具包]\n end\n \n subgraph 工具层\n CLI[create-twenty-app
脚手架工具]\n DOCS[twenty-docs
文档系统]\n end\n \n subgraph 数据层\n DB[(PostgreSQL)]\n CACHE[(Redis)]\n end\n \n WEB --> SERVER\n FRONT --> SERVER\n FRONT --> SDK\n CLI --> SDK\n SERVER --> DB\n SERVER --> CACHE\n```\n\n## 包结构说明\n\n项目位于 `packages/` 目录下，主要包含以下核心包：\n\n| 包名 | 说明 | 技术框架 |\n|------|------|----------|\n| `twenty-front` | CRM 前端应用 | React, TypeScript, GraphQL |\n| `twenty-server` | 后端 API 服务 | Node.js, TypeScript |\n| `twenty-website-new` | 营销网站 | Next.js, React, TypeScript |\n| `twenty-docs` | 开发者文档 | MDX, Mintlify |\n| `twenty-sdk` | SDK 开发工具包 | TypeScript |\n| `create-twenty-app` | 项目脚手架 | Node.js CLI |\n\n## 前端技术栈\n\n### 核心框架\n\n前端采用 **React 18** 作为 UI 框架，结合 **TypeScript** 提供类型安全。组件化架构支持高度定制化的 CRM 功能开发。\n\n```mermaid\ngraph LR\n subgraph React生态\n CORE[React Core]\n ROUTER[React Router]\n QUERY[React Query
数据获取]\n FORM[React Hook Form]\n end\n \n subgraph UI层\n COMP[组件库]\n ICONS[图标系统]\n STYLES[样式方案]\n end\n \n CORE --> ROUTER\n CORE --> QUERY\n CORE --> FORM\n ROUTER --> COMP\n QUERY --> COMP\n```\n\n### 营销网站技术选型\n\n`twenty-website-new` 包采用 Next.js App Router 架构实现国际化营销站点：\n\n- **Next.js 14+**：App Router 路由系统\n- **国际化方案**：基于 `i18n._()` 的消息提取模式\n- **样式方案**：CSS Modules + 设计系统变量\n- **动态路由**：`[locale]` 动态段支持多语言\n\n### 关键特性实现\n\n从代码分析可知，前端实现了多项 CRM 核心功能：\n\n| 功能模块 | 实现方式 | 文件位置 |\n|----------|----------|----------|\n| 对象元数据管理 | 标准化对象定义系统 | `packages/twenty-server/src/engine/workspace-manager/` |\n| 字段元数据 | 字段类型系统 (UUID, DateTime 等) | `packages/twenty-server/.../field-metadata/` |\n| 工作区管理 | Workspace Manager 统一管理 | `packages/twenty-server/.../workspace-manager/` |\n\n## 后端技术栈\n\n### 服务端架构\n\n`twenty-server` 采用模块化的 Node.js 服务架构：\n\n```mermaid\ngraph TD\n API[API Gateway]\n subgraph 引擎层\n WM[Workspace Manager]\n OBJ[Object Metadata]\n FIELD[Field Metadata]\n end\n \n subgraph 标准应用\n TWENTY_STD[Twenty Standard
Application]\n end\n \n subgraph 数据层\n ORM[ORM Layer]\n DB[(Database)]\n end\n \n API --> WM\n WM --> OBJ\n WM --> FIELD\n OBJ --> TWENTY_STD\n FIELD --> TWENTY_STD\n TWENTY_STD --> ORM\n ORM --> DB\n```\n\n### 核心依赖\n\n后端服务主要依赖以下技术：\n\n| 技术类别 | 选型 | 用途 |\n|----------|------|------|\n| 运行时 | Node.js | 服务端运行环境 |\n| 语言 | TypeScript | 类型安全开发 |\n| 框架 | 自研引擎 | CRM 核心业务逻辑 |\n| 数据库 | PostgreSQL | 主数据存储 |\n| 缓存 | Redis | 会话和缓存管理 |\n| API | GraphQL | 前后端数据交互 |\n\n### 标准对象系统\n\n系统内置标准对象通过 `create-standard-flat-object-metadata` 工具创建：\n\n- **messageThread**：消息会话对象\n- **message**：消息记录对象\n- **noteTarget**：笔记关联对象\n\n每个标准对象包含以下元数据属性：\n\n| 属性 | 说明 |\n|------|------|\n| `universalIdentifier` | 全局唯一标识符 |\n| `nameSingular/namePlural` | 单复数名称 |\n| `labelSingular/labelPlural` | 显示标签 |\n| `icon` | 图标标识 |\n| `isSystem` | 系统对象标识 |\n| `labelIdentifierFieldMetadataName` | 主标识字段 |\n\n## 开发者工具链\n\n### CLI 脚手架\n\n`create-twenty-app` 提供快速启动能力：\n\n```bash\nnpx create-twenty-app@latest my-twenty-app\ncd my-twenty-app\nyarn twenty dev\n```\n\n脚手架自动配置：\n- TypeScript 项目结构\n- ESLint + Prettier 代码规范\n- twenty-sdk 集成\n- 开发服务器配置\n\n### SDK 工具包\n\n`twenty-sdk` 是连接应用与 Twenty CRM 的官方开发工具包，封装了：\n- GraphQL 客户端\n- 认证模块\n- 数据操作 API\n- 类型定义导出\n\n## 文档系统\n\n### 开发者文档架构\n\n`twenty-docs` 采用 MDX 格式编写文档，支持 Mintlify 文档站点生成：\n\n```mermaid\ngraph LR\n MDX[MDX 源文件] --> NAV[导航结构]\n NAV --> CROWDIN[国际化 Crowdin]\n CROWDIN --> BUILD[docs.json]\n BUILD --> MINTLIFY[Mintlify 站点]\n```\n\n### 文档配置要点\n\n| 文件 | 作用 |\n|------|------|\n| `navigation/base-structure.json` | 导航结构定义（英文源） |\n| `navigation/navigation.template.json` | 翻译模板 |\n| `l//navigation.json` | 各语言本地化 |\n| `docs.json` | Mintlify 配置输出 |\n\n## 构建与部署\n\n### Monorepo 构建配置\n\n项目使用 Nx 管理多包构建：\n\n- 依赖关系自动分析\n- 增量构建支持\n- 任务编排优化\n- affected 命令支持\n\n### 云端部署\n\nTwenty 支持多种部署方式：\n\n| 部署方式 | 说明 | 适用场景 |\n|----------|------|----------|\n| Cloud SaaS | twenty.com 托管服务 | 开箱即用 |\n| 自托管 | Docker/Kubernetes | 企业私有部署 |\n| 开发预览 | 本地开发环境 | 开发调试 |\n\n### 企业版激活\n\n企业版通过许可证密钥激活，激活流程：\n1. 完成企业版购买\n2. 在自托管实例中输入许可证密钥\n3. 系统验证并激活高级功能\n\n## 总结\n\nTwenty 的技术栈设计体现了现代化 CRM 的最佳实践：\n\n- **前后端分离**：清晰的职责边界\n- **TypeScript 全面覆盖**：类型安全\n- **Monorepo 管理**：代码复用与统一版本控制\n- **模块化架构**：易于扩展和维护\n- **国际化支持**：全球化部署\n\n这套技术架构既保证了系统的稳定性和可扩展性，又为开发者提供了良好的二次开发体验。\n\n---\n\n\n\n## Monorepo结构\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [前端架构](#page-frontend-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/twentyhq/twenty/blob/main/package.json)\n- [nx.json](https://github.com/twentyhq/twenty/blob/main/nx.json)\n- [packages/twenty-docs/README.md](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/README.md)\n- [packages/twenty-website-new/src/app/[locale]/(home)/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/(home)/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/articles/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/articles/page.tsx)\n- [packages/twenty-docs/navigation/base-structure.json](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/navigation/base-structure.json)\n- [packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/object-metadata/create-standard-flat-object-metadata.util.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/object-metadata/create-standard-flat-object-metadata.util.ts)\n \n\n# Monorepo结构\n\n## 概述\n\nTwenty项目采用**Nx驱动的Monorepo架构**，将前端、后端、文档等多个应用和包组织在单一代码仓库中。这种架构模式便于统一管理依赖、共享代码库、简化CI/CD流程，并确保整个项目的一致性。\n\n## 核心包结构\n\nTwenty项目的主要包位于`packages/`目录下，每个包都有独立的职责：\n\n| 包名 | 类型 | 描述 |\n|------|------|------|\n| `twenty-front` | Next.js应用 | CRM主前端界面 |\n| `twenty-server` | Node.js服务 | 后端API和引擎 |\n| `twenty-website-new` | Next.js应用 | 官方网站和营销页面 |\n| `twenty-docs` | 文档 | Mintlify文档站点 |\n\n## Nx工作区配置\n\n项目根目录的`nx.json`定义了Monorepo的工作区配置：\n\n```json\n{\n \"extends\": \"@nx/next/preset\",\n \"namedInputs\": {\n \"default\": [\"{projectRoot}/**/*\"],\n \"production\": [\"!{projectRoot}/**/*.spec.ts\"]\n }\n}\n```\n\nNx提供了以下核心能力：\n\n- **增量构建**：只重新构建变更影响的包\n- **任务编排**：管理包之间的构建顺序和依赖关系\n- **代码生成**：通过生成器创建模块、组件、服务\n- **依赖图可视化**：展示包之间的依赖关系\n\n## 前端包结构\n\n### twenty-front\n\n主CRM前端应用，包含以下核心目录：\n\n```\npackages/twenty-front/\n├── src/\n│ └── modules/ # 功能模块\n│ ├── ai/ # AI相关组件\n│ ├── activities/ # 活动管理\n│ ├── companies/ # 公司管理\n│ ├── contacts/ # 联系人\n│ └── ... # 其他业务模块\n```\n\n从`ThinkingStepsDisplay.tsx`可以看到前端组件遵循的约定：\n\n- 使用React functional component\n- 样式通过`Styled*`前缀的组件封装\n- 支持TypeScript泛型和严格类型检查\n\n### twenty-website-new\n\n新版官方网站采用App Router结构：\n\n```\npackages/twenty-website-new/\n├── src/\n│ ├── app/\n│ │ └── [locale]/ # 国际化路由\n│ │ ├── (home)/ # 首页路由组\n│ │ ├── articles/ # 文章页面\n│ │ ├── releases/ # 发布日志\n│ │ ├── customers/ # 客户案例\n│ │ ├── partners/ # 合作伙伴\n│ │ ├── product/ # 产品页面\n│ │ ├── enterprise/# 企业版页面\n│ │ ├── why-twenty/# 为什么选择Twenty\n│ │ └── privacy-policy/ # 隐私政策\n│ ├── sections/ # 可复用页面区块\n│ │ ├── Hero/ # 英雄区组件\n│ │ ├── Footer/ # 页脚\n│ │ ├── CaseStudy/ # 案例研究组件\n│ │ ├── AppPreview/ # 应用预览\n│ │ └── ...\n│ └── content/ # 内容配置\n│ └── releases/ # 发布说明MDX\n```\n\n## 后端包结构\n\n### twenty-server\n\n后端服务位于`packages/twenty-server/`，采用模块化架构：\n\n```\npackages/twenty-server/\n└── src/\n └── engine/\n ├── workspace-manager/ # 工作区管理\n │ └── twenty-standard-application/\n │ └── utils/\n │ ├── object-metadata/ # 对象元数据工具\n │ └── field-metadata/ # 字段元数据工具\n └── api/ # API层\n```\n\n核心模块包括：\n\n- **workspace-manager**：管理工作区生命周期和标准对象\n- **twenty-standard-application**：标准应用定义，包含如`messageThread`、`message`等系统对象\n- **metadata层**：处理元数据的创建和关系映射\n\n## 文档系统\n\n### twenty-docs\n\n文档包使用Mintlify框架，支持国际化：\n\n```\npackages/twenty-docs/\n├── navigation/\n│ ├── base-structure.json # 导航基准结构\n│ └── navigation.template.json # 翻译模板\n├── l/ # 本地化文件\n│ └── /\n│ └── navigation.json # 语言特定导航\n├── docs.json # 生成的Mintlify配置\n└── docs/ # MDX文档内容\n```\n\n文档导航配置流程：\n\n1. 编辑`navigation/base-structure.json`定义结构和slug\n2. 运行`yarn docs:generate-navigation-template`生成翻译模板\n3. 上传到Crowdin进行翻译\n4. 拉取翻译文件到`l//navigation.json`\n5. 运行`yarn docs:generate`生成最终配置\n\n## 依赖关系图\n\n```mermaid\ngraph TD\n A[nx.json - 工作区配置] --> B[twenty-front]\n A --> C[twenty-server]\n A --> D[twenty-website-new]\n A --> E[twenty-docs]\n \n B --> F[@twenty-ui/* 共享UI组件]\n B --> C[API调用]\n \n C --> G[workspace-manager]\n C --> H[standard-application]\n \n D --> B[复用组件]\n D --> I[content - 发布日志]\n \n E --> J[base-structure.json]\n J --> K[Crowdin翻译]\n K --> L[本地化导航]\n L --> M[docs.json]\n```\n\n## 常用命令\n\n项目根目录的`package.json`定义了关键脚本：\n\n| 命令 | 描述 |\n|------|------|\n| `yarn docs:generate` | 生成文档配置 |\n| `yarn docs:dev` | 本地开发文档 |\n| `yarn docs:validate` | 验证文档构建 |\n| `npx nx run twenty-docs:dev` | 运行文档开发服务器 |\n\n## 页面组件层次结构\n\nTwenty网站的页面采用组件组合模式：\n\n```mermaid\ngraph TD\n A[Page Component] --> B[Menu.Root]\n A --> C[Hero.Root]\n A --> D[TrustedBy.Root]\n A --> E[Feature Sections]\n A --> F[Testimonials.Root]\n A --> G[Faq.Root]\n A --> H[Signoff.Root]\n A --> I[Footer]\n \n C --> C1[Hero.Heading]\n C --> C2[Hero.Body]\n C --> C3[Hero.Cta]\n C --> C4[Hero.AppPreview]\n```\n\n## 路由和国际化\n\n网站使用Next.js App Router的`[locale]`动态路由实现国际化：\n\n```\nsrc/app/[locale]/\n├── (home)/page.tsx # 首页\n├── articles/page.tsx # 文章列表\n├── releases/page.tsx # 发布日志\n├── customers/ # 客户案例\n│ └── w3villa/page.tsx\n├── product/page.tsx # 产品页\n└── enterprise/\n └── activate/page.tsx\n```\n\n## 标准对象元数据\n\n后端定义了一系列标准对象（Standard Objects），每个对象都有标准的字段元数据：\n\n| 对象名 | 标签 | 图标 | 用途 |\n|--------|------|------|------|\n| `messageThread` | Message Thread | IconMessage | 消息线程 |\n| `message` | Message | IconMessage | 单条消息 |\n| `noteTarget` | Note Target | - | 笔记关联 |\n\n这些标准对象通过`createStandardFlatObjectMetadata`工具函数创建，具有：\n\n- 系统字段（`id`, `createdAt`, `updatedAt`）\n- 国际化标签支持（通过`i18nLabel`）\n- 标准图标定义\n- 审计日志配置\n\n## 总结\n\nTwenty的Monorepo结构设计遵循以下原则：\n\n1. **职责分离**：每个包有明确的边界和职责\n2. **共享代码**：通过包内部引用实现代码复用\n3. **增量构建**：Nx确保只构建受影响的包\n4. **国际化**：统一的locale路由和翻译管理\n5. **模块化组件**：网站区块高度可复用\n\n---\n\n\n\n## 前端架构\n\n### 相关页面\n\n相关主题：[UI组件库](#page-ui-components), [后端架构](#page-server-architecture), [Monorepo结构](#page-monorepo-structure)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/twenty-website-new/src/app/[locale]/articles/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/articles/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/(home)/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/(home)/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/partners/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/partners/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/pricing/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/pricing/page.tsx)\n- [packages/twenty-front/src/modules/ai/components/ThinkingStepsDisplay.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/ai/components/ThinkingStepsDisplay.tsx)\n- [packages/twenty-front/src/pages/not-found/NotFound.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/pages/not-found/NotFound.tsx)\n- [packages/twenty-website-new/src/sections/Footer/data.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/sections/Footer/data.ts)\n- [packages/twenty-website-new/src/app/[locale]/product/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/product/page.tsx)\n \n\n# 前端架构\n\n## 概述\n\nTwenty 项目采用**多包架构**（monorepo 结构），前端代码分散在多个独立的功能包中，主要包括：\n\n| 包名 | 用途 |\n|------|------|\n| `packages/twenty-front` | 主应用程序前端核心，包含 CRM 业务逻辑和 UI 组件 |\n| `packages/twenty-website-new` | 营销网站和新版文档站点 |\n| `packages/twenty-docs` | 开发者文档（基于 Mintlify） |\n| `packages/create-twenty-app` | 项目脚手架 CLI 工具 |\n\n本页面重点介绍 `twenty-front` 和 `twenty-website-new` 的前端架构设计。\n\n---\n\n## 整体架构分层\n\nTwenty 前端采用**模块化分层架构**，各层职责清晰分离：\n\n```mermaid\ngraph TD\n A[UI Layer
React Components] --> B[Module Layer
Feature Modules]\n B --> C[Hook Layer
Custom Hooks]\n C --> D[State Layer
Recoil/Zustand]\n D --> E[Service Layer
API Clients]\n E --> F[API Layer
GraphQL/REST]\n \n G[Pages] --> A\n H[Layouts] --> A\n I[Shared Components] --> A\n```\n\n### 层级职责说明\n\n| 层级 | 说明 | 代码位置 |\n|------|------|----------|\n| UI Layer | 原子化组件和复合组件 | `packages/twenty-front/src/modules/*/components` |\n| Module Layer | 业务功能模块封装 | `packages/twenty-front/src/modules/*` |\n| Hook Layer | 可复用的业务逻辑钩子 | `packages/twenty-front/src/hooks` |\n| State Layer | 全局状态管理 | `packages/twenty-front/src/modules/*/states` |\n| Service Layer | API 调用封装 | `packages/twenty-front/src/modules/*/services` |\n\n---\n\n## 页面路由结构\n\n### 营销网站路由 (`twenty-website-new`)\n\n营销网站基于 **Next.js App Router**，采用国际化路由 `[locale]` 动态段：\n\n```\nsrc/app/[locale]/\n├── page.tsx # 首页\n├── articles/\n│ └── page.tsx # 文章列表页\n├── partners/\n│ └── page.tsx # 合作伙伴页面\n├── pricing/\n│ └── page.tsx # 定价页面\n├── product/\n│ └── page.tsx # 产品功能页面\n├── enterprise/\n│ └── activate/\n│ └── page.tsx # 企业激活页面\n├── customers/\n│ ├── page.tsx # 客户案例列表\n│ └── w3villa/\n│ └── page.tsx # 特定案例页面\n├── why-twenty/\n│ └── page.tsx # 为什么选择 Twenty\n└── releases/\n └── page.tsx # 发布日志\n```\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:1-10]()\n\n### CRM 应用路由 (`twenty-front`)\n\n主应用使用自定义路由系统，通过 `AppPath` 常量定义路由路径：\n\n```typescript\n// 路由类型定义示例\nexport enum AppPath {\n Index = '/',\n NotFound = '/not-found',\n // ... 更多路由\n}\n```\n\n资料来源：[packages/twenty-front/src/pages/not-found/NotFound.tsx:40-50]()\n\n---\n\n## 组件架构\n\n### 组件组织模式\n\nTwenty 前端采用**区域组件**（Section Components）和**功能组件**分离的组织模式：\n\n```mermaid\ngraph LR\n A[Section Components] -->|Hero| B[HeadingGroup]\n A -->|Hero| C[Body]\n A -->|Hero| D[Cta]\n A -->|Hero| E[Visual]\n F[Feature Components] -->|TrustedBy| G[Logos]\n F -->|TrustedBy| H[Separator]\n F -->|Faq| I[Items]\n F -->|Testimonials| J[Carousel]\n```\n\n### 核心页面组件\n\n| 组件 | 功能 | 源码位置 |\n|------|------|----------|\n| `Hero.Root` | 英雄区域根容器 | `twenty-website-new/src/sections/Hero` |\n| `Hero.Heading` | 主标题渲染 | 同上 |\n| `Hero.Body` | 正文内容 | 同上 |\n| `Hero.Cta` | 行动按钮组 | 同上 |\n| `TrustedBy.Root` | 信任背书区域 | `twenty-website-new/src/sections/TrustedBy` |\n| `Faq.Root` | 常见问题区域 | `twenty-website-new/src/sections/Faq` |\n| `Signoff.Root` | 结尾号召区域 | `twenty-website-new/src/sections/Signoff` |\n| `Testimonials.Carousel` | 用户推荐轮播 | `twenty-website-new/src/sections/Testimonials` |\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:1-20]()\n\n### 组件 Props 接口模式\n\n组件使用强类型 Props 接口，继承基础配置：\n\n```typescript\n// Hero 组件 Props 示例\ninterface HeroProps {\n page: Pages; // 页面标识\n scheme?: 'light' | 'dark';\n children: React.ReactNode;\n}\n\n// Heading 组件\ninterface HeadingPartProps {\n fontFamily: 'serif' | 'sans';\n children: React.ReactNode;\n}\n```\n\n---\n\n## 样式系统\n\n### Styled Components 方案\n\nTwenty 前端使用 `styled-components` 作为主要的样式解决方案：\n\n```typescript\nconst StyledContainer = styled.div`\n display: flex;\n flex-direction: column;\n position: relative;\n`;\n\nconst StyledBackDrop = styled.div`\n position: fixed;\n top: 0;\n width: 100%;\n z-index: ${RootStackingContextZIndices.NotFound};\n`;\n```\n\n资料来源：[packages/twenty-front/src/pages/not-found/NotFound.tsx:1-30]()\n\n### 主题配置\n\n| 配置项 | 说明 |\n|--------|------|\n| `theme.colors.primary` | 主色调变体 |\n| `theme.colors.secondary` | 次要色调变体 |\n| `theme.fonts.serif` | 衬线字体（用于标题） |\n| `theme.fonts.sans` | 无衬线字体（用于正文） |\n\n---\n\n## 国际化实现\n\n### i18n 配置\n\n项目使用 `@lingui` 进行国际化处理：\n\n```typescript\nimport { msg } from '@lingui/macro';\n\n// 使用 msg 宏定义翻译文本\nconst heading = i18n._(msg`Build your Enterprise CRM`);\nconst buttonLabel = i18n._(msg`Get started`);\n```\n\n### 国际化组件\n\n| 组件 | 用途 |\n|------|------|\n| `` | 文本片段字体样式控制 |\n| `` | 眉毛标题（小标签文字） |\n| `` | React 翻译组件 |\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:5-15]()\n\n---\n\n## 状态管理\n\n### 思考步骤状态示例\n\nAI 思考步骤的显示逻辑展示了状态管理模式：\n\n```typescript\nconst ThinkingStepsDisplay = ({ parts, reasoningContent }) => {\n const shouldDisplayReasoningContent = !!reasoningContent;\n \n return (\n \n \n {parts.map((part, index) => (\n \n ))}\n \n \n );\n};\n```\n\n资料来源：[packages/twenty-front/src/modules/ai/components/ThinkingStepsDisplay.tsx:1-30]()\n\n### 状态管理模式\n\n| 模式 | 适用场景 | 库 |\n|------|----------|-----|\n| 组件本地状态 | UI 交互状态 | `useState` |\n| 全局状态 | 跨模块共享数据 | `Recoil` / `Zustand` |\n| 服务端状态 | API 数据缓存 | `React Query` / `SWR` |\n\n---\n\n## 路由与导航\n\n### 主应用路由\n\n```typescript\n// AppPath 枚举定义\nexport enum AppPath {\n Index = '/',\n NotFound = '/not-found',\n // CRM 相关路由...\n}\n\n// 404 页面实现\nexport const NotFound = () => {\n const { t } = useLingui();\n \n return (\n <>\n \n \n \n \n {/* 错误提示内容 */}\n \n \n \n \n \n \n );\n};\n```\n\n资料来源：[packages/twenty-front/src/pages/not-found/NotFound.tsx:40-75]()\n\n### 营销网站路由\n\n营销网站采用 Next.js 的文件系统路由：\n\n```typescript\n// 动态路由段 [locale]\n// 文件结构自动映射到 URL\n// /articles -> 文章列表\n// /pricing -> 定价页面\n// /partners -> 合作伙伴\n```\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/articles/page.tsx:1-10]()\n\n---\n\n## 页面布局模式\n\n### 典型页面结构\n\n```mermaid\ngraph TD\n A[Menu Header] --> B[Hero Section]\n B --> C[TrustedBy Section]\n C --> D[Feature Tabs/Sections]\n D --> E[Testimonials]\n E --> F[Faq Section]\n F --> G[Signoff Section]\n G --> H[Footer]\n```\n\n### 页面区域组件\n\n| 区域组件 | 说明 |\n|----------|------|\n| `Menu.Root` | 顶部导航菜单 |\n| `Hero.Root` | 首屏英雄区域 |\n| `TrustedBy.Root` | 客户信任背书 |\n| `Tabs.Root` | 功能特性标签页 |\n| `ThreeCards.Root` | 三卡片布局 |\n| `PromoSpacing` | 间距调整组件 |\n| `Faq.Root` | 常见问题解答 |\n| `Signoff.Root` | 页面结尾号召 |\n| `Footer` | 页脚信息 |\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/partners/page.tsx:1-40]()\n\n---\n\n## 模块化设计\n\n### 前端模块结构\n\n```\npackages/twenty-front/src/modules/\n├── activities/ # 活动/任务模块\n├── ai/ # AI 功能模块\n├── billing/ # 账单模块\n├── calendar/ # 日历模块\n├── companies/ # 公司管理模块\n├── contacts/ # 联系人模块\n├── people/ # 人员模块\n├── tasks/ # 任务模块\n└── ui-tweak/ # UI 定制模块\n```\n\n每个模块遵循统一的结构：\n\n| 子目录 | 用途 |\n|--------|------|\n| `components/` | 模块专属组件 |\n| `hooks/` | 模块专属钩子 |\n| `states/` | 模块状态定义 |\n| `services/` | 模块 API 服务 |\n| `graphql/` | GraphQL 查询和变更 |\n\n资料来源：[packages/twenty-front/src/modules/ai/components/ThinkingStepsDisplay.tsx:1-5]()\n\n---\n\n## 数据获取\n\n### API 服务层\n\n模块通过服务层封装 API 调用：\n\n```typescript\n// 服务接口定义示例\ninterface ApiService {\n getAll(): Promise;\n getById(id: string): Promise;\n create(data: Partial): Promise;\n update(id: string, data: Partial): Promise;\n delete(id: string): Promise;\n}\n```\n\n### 页面数据获取模式\n\n```typescript\n// Next.js Server Component 模式\nasync function Page() {\n // 服务端获取数据\n const posts = await getPosts();\n \n return ;\n}\n```\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/articles/page.tsx:10-20]()\n\n---\n\n## 错误处理\n\n### 404 错误页面\n\n```typescript\nconst NotFound = () => {\n return (\n \n \n \n \n Off the beaten path\n \n \n The page you're seeking is either gone or never was.\n \n \n \n \n \n \n \n \n );\n};\n```\n\n资料来源：[packages/twenty-front/src/pages/not-found/NotFound.tsx:50-70]()\n\n---\n\n## 构建与部署\n\n### 包管理器\n\n项目使用 **Yarn** 作为包管理器：\n\n```bash\n# 安装依赖\nyarn install\n\n# 开发模式\nyarn dev\n\n# 构建生产版本\nyarn build\n```\n\n### 环境配置\n\n| 环境变量 | 说明 |\n|----------|------|\n| `NEXT_PUBLIC_API_URL` | API 服务地址 |\n| `DATABASE_URL` | 数据库连接字符串 |\n| `STORAGE_SECRET` | 存储服务密钥 |\n\n---\n\n## 技术栈总结\n\n| 类别 | 技术选型 |\n|------|----------|\n| 框架 | Next.js (App Router) / React 18 |\n| 语言 | TypeScript |\n| 样式 | styled-components |\n| 状态管理 | Recoil / Zustand |\n| 国际化 | @lingui |\n| 包管理 | Yarn |\n| 组件库 | 自定义组件系统 |\n| 测试 | Jest / React Testing Library |\n\n---\n\n## 相关文档\n\n- [Twenty 官方文档](https://docs.twenty.com)\n- [Twenty GitHub 仓库](https://github.com/twentyhq/twenty)\n- [Create Twenty App CLI](https://www.npmjs.com/package/create-twenty-app)\n\n---\n\n\n\n## UI组件库\n\n### 相关页面\n\n相关主题：[前端架构](#page-frontend-architecture), [Activities活动模块](#page-activities-module)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/twenty-website-new/src/app/[locale]/(home)/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/(home)/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/product/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/product/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/pricing/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/pricing/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/partners/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/partners/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/customers/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/customers/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/why-twenty/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/why-twenty/page.tsx)\n- [packages/twenty-website-new/src/sections/Footer/data.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/sections/Footer/data.ts)\n- [packages/twenty-website-new/src/sections/Salesforce/components/PricingWindow.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/sections/Salesforce/components/PricingWindow.tsx)\n \n\n# UI组件库\n\nTwenty CRM 的 UI 组件库是一个模块化、可复用的前端组件集合，主要位于 `packages/twenty-front` 和 `packages/twenty-website-new` 包中。该组件库为整个 Twenty 产品提供一致的视觉语言和交互体验。\n\n## 组件库架构\n\n### 包结构\n\n```\ntwenty/\n├── packages/\n│ ├── twenty-front/ # 主应用前端组件\n│ │ └── src/modules/ui-library/ # UI组件库核心\n│ ├── twenty-website-new/ # 营销网站\n│ │ └── src/sections/ # 页面区块组件\n│ └── twenty-front-component-renderer/ # 组件渲染器\n```\n\n### 组件分类\n\nTwenty UI 组件库按功能可分为以下几大类：\n\n| 类别 | 功能描述 | 典型组件 |\n|------|----------|----------|\n| 布局组件 | 页面结构和容器 | Container, Panel |\n| 导航组件 | 用户导航和路由 | LinkButton, UndecoratedLink |\n| 内容组件 | 展示文本和媒体 | Heading, HeadingPart, Eyebrow |\n| 表单组件 | 用户输入和交互 | MainButton, FakeButton |\n| 数据展示 | 列表和表格 | Tiles, Cards |\n| 交互反馈 | 动画和状态 | AnimatedPlaceholder, Tooltip |\n\n## 核心组件详解\n\n### Heading 标题组件\n\n标题组件支持多种字体家族和尺寸配置，用于页面层级的视觉层次表达。\n\n```tsx\n\n \n {i18n._(msg`A modern CRM with`)}\n {' '}\n \n {i18n._(msg`an intuitive interface`)}\n \n\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 可选值 | 默认值 | 说明 |\n|------|------|--------|--------|------|\n| size | string | `sm`, `md`, `lg` | `md` | 标题尺寸 |\n| weight | string | `light`, `regular`, `bold` | `regular` | 字体粗细 |\n| fontFamily | string | `serif`, `sans` | `sans` | 字体系列 |\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/product/page.tsx]()\n\n### LinkButton 链接按钮\n\n用于页面间导航的按钮组件，支持多种变体和颜色配置。\n\n```tsx\n\n```\n\n**变体类型：**\n\n| variant | 说明 |\n|---------|------|\n| `contained` | 实心填充样式 |\n| `outlined` | 描边样式 |\n| `text` | 纯文本样式 |\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/pricing/page.tsx]()\n\n### Hero 英雄区域组件\n\n页面顶部的核心展示区域，包含主标题、描述和行动号召按钮。\n\n```tsx\n\n \n \n {i18n._(msg`Build your Enterprise CRM`)}\n {' '}\n \n {i18n._(msg`at AI Speed`)}\n \n \n \n {i18n._(\n msg`Twenty gives technical teams the building blocks...`,\n )}\n \n \n \n \n \n \n\n```\n\n**Hero 子组件结构：**\n\n```mermaid\ngraph TD\n A[Hero.Root] --> B[Hero.Heading]\n A --> C[Hero.Body]\n A --> D[Hero.Cta]\n A --> E[Hero.AppPreview 或 Hero.PartnerVisual 等]\n```\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx]()\n\n### ThreeCards 三卡片布局\n\n用于特性展示的三列卡片布局组件。\n\n```tsx\n\n \n ...\n ...\n \n \n \n\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| scheme | `light`, `muted`, `dark` | 配色方案 |\n| align | `left`, `center` | 内容对齐方式 |\n| variant | `simple`, `feature` | 卡片变体 |\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/partners/page.tsx]()\n\n### Faq 常见问题组件\n\n可折叠的问答展示组件。\n\n```tsx\n\n \n ...\n ...\n ...\n \n \n\n```\n\n**数据结构：**\n\n```typescript\ninterface FaqQuestion {\n question: string;\n answer: string;\n category?: string;\n}\n```\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/product/page.tsx]()\n\n### TrustedBy 信任背书组件\n\n展示合作品牌和客户数量的组件。\n\n```tsx\n\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| separator | ReactNode | 分隔文本 |\n| logos | Logo[] | 品牌 Logo 数组 |\n| clientCount | string | 客户数量文本 |\n| compactBottom | boolean | 紧凑底部样式 |\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/partners/page.tsx]()\n\n## 样式系统\n\n### Styled Components\n\nTwenty 使用 `styled-components` 进行样式管理，实现 CSS-in-JS 方案。\n\n```tsx\nconst StyledBackDrop = styled.div`\n position: fixed;\n top: 0;\n width: 100%;\n z-index: ${RootStackingContextZIndices.NotFound};\n`;\n\nconst StyledButtonContainer = styled.div`\n width: 200px;\n`;\n```\n\n资料来源：[packages/twenty-front/src/pages/not-found/NotFound.tsx]()\n\n### 主题配置\n\n组件通过 ThemeProvider 获取主题配置，包括颜色、字体、间距等。\n\n```typescript\n\n```\n\n### 配色方案\n\n| 方案名称 | 使用场景 |\n|----------|----------|\n| `light` | 明亮背景区块 |\n| `muted` | 柔和背景区块 |\n| `dark` | 深色背景区块 |\n| `secondary` | 次要强调色 |\n\n## 国际化支持\n\n### @lingui 集成\n\n组件使用 `@lingui` 进行国际化处理，所有用户可见文本都通过 `i18n._()` 或 `msg` 宏定义。\n\n```tsx\nimport { msg } from '@lingui/macro';\n\n// 静态文本\nconst label = msg`Get started`;\n\n// 动态文本\n{i18n._(\n msg`Twenty gives technical teams the building blocks for a custom CRM...`,\n)}\n```\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx]()\n\n## 页面构建模式\n\n### 区块组合模式\n\nTwenty 网站采用区块化设计，通过组合不同 Section 组件构建完整页面。\n\n```tsx\nexport default function HomePage() {\n return (\n <>\n ...\n ...\n ...\n ...\n ...\n ...\n ...\n \n );\n}\n```\n\n**页面结构流程：**\n\n```mermaid\ngraph LR\n A[Hero 英雄区] --> B[TrustedBy 信任背书]\n B --> C[Problem 问题陈述]\n C --> D[ThreeCards 特性卡片]\n D --> E[Feature 功能展示]\n E --> F[Testimonials 客户证言]\n F --> G[Faq 常见问题]\n```\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/customers/page.tsx]()\n\n### 页面类型枚举\n\n```typescript\nenum Pages {\n Home = 'home',\n Product = 'product',\n Pricing = 'pricing',\n Partners = 'partners',\n Articles = 'articles',\n WhyTwenty = 'whyTwenty',\n}\n```\n\n## 组件渲染器\n\n### ComponentRenderer 模块\n\n`twenty-front-component-renderer` 包提供了动态渲染 UI 组件的能力，支持在运行时根据配置渲染不同组件。\n\n```\npackages/twenty-front-component-renderer/src/\n```\n\n该模块允许：\n- 根据数据动态渲染组件\n- 支持组件配置化\n- 实现运行时主题切换\n\n资料来源：[packages/twenty-front-component-renderer/src](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front-component-renderer/src)\n\n## Footer 导航数据\n\nFooter 组件使用配置化数据源定义链接和 CTAs。\n\n```typescript\n{\n id: 'footer-product',\n title: msg`Product`,\n ctas: [\n {\n color: 'secondary',\n href: 'https://app.twenty.com/welcome',\n kind: 'link',\n label: msg`Get started`,\n variant: 'outlined',\n },\n ],\n links: [\n {\n label: msg`API & SDKs`,\n href: 'https://docs.twenty.com/api-rest/overview',\n external: true,\n },\n ],\n}\n```\n\n**Footer 数据结构：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | string | 唯一标识符 |\n| title | Message | 区块标题 |\n| ctas | CTA[] | 行动号召按钮 |\n| links | Link[] | 链接列表 |\n\n资料来源：[packages/twenty-website-new/src/sections/Footer/data.ts]()\n\n## 最佳实践\n\n### 组件组合\n\n使用复合组件模式，通过子组件构建复杂 UI：\n\n```tsx\n\n ...\n ...\n\n```\n\n### 国际化处理\n\n始终使用 `i18n._()` 或 `msg` 包装用户可见文本：\n\n```tsx\n// ✅ 正确\n{i18n._(msg`Welcome`)}\n\n// ❌ 错误\nWelcome\n```\n\n### 样式隔离\n\n使用 styled-components 的样式隔离，避免全局污染：\n\n```tsx\nconst StyledContainer = styled.div`\n // 样式定义\n`;\n```\n\n### 可访问性\n\n确保交互组件包含适当的 ARIA 属性：\n\n```tsx\n\n```\n\n资料来源：[packages/twenty-website-new/src/sections/Salesforce/components/PricingWindow.tsx]()\n\n## 总结\n\nTwenty 的 UI 组件库采用模块化设计，通过复合组件模式、配置化数据和国际化支持，构建了一套高效、可维护的前端组件体系。开发者可以通过组合这些基础组件快速构建页面，同时保持视觉一致性和交互体验的统一。\n\n---\n\n\n\n## 后端架构\n\n### 相关页面\n\n相关主题：[数据模型](#page-database-models), [前端架构](#page-frontend-architecture), [Docker部署](#page-docker-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/twenty-server/src](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src)\n- [packages/twenty-server/src/modules](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/modules)\n- [packages/twenty-docs/developers/contribute/capabilities/backend-development](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/developers/contribute/capabilities/backend-development)\n- [packages/create-twenty-app/README.md](https://github.com/twentyhq/twenty/blob/main/packages/create-twenty-app/README.md)\n- [packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx)\n \n\n# 后端架构\n\n## 概述\n\nTwenty 的后端架构是整个 CRM 系统的核心，负责处理业务逻辑、数据持久化、API 接口服务以及与 AI 能力的集成。Twenty 后端采用模块化架构设计，支持自托管部署和云端服务两种模式，为企业用户提供灵活的 CRM 解决方案。\n\n后端服务位于 `packages/twenty-server/src` 目录下，采用 TypeScript 开发，具备良好的类型安全性和代码可维护性。系统核心功能围绕 **Companies（公司）**、**People（联系人）**、**Opportunities（商机）**、**Activities（活动）** 等 CRM 实体展开，通过统一的 GraphQL API 向前端和其他客户端提供服务。\n\n## 技术栈概览\n\nTwenty 后端采用现代化的技术栈构建，确保系统具备高性能、可扩展性和易维护性：\n\n| 技术类别 | 技术选型 | 说明 |\n|---------|---------|------|\n| 运行时 | Node.js / Deno | 支持服务器端执行 |\n| 语言 | TypeScript | 类型安全的开发体验 |\n| 框架 | NestJS | 模块化的企业级框架 |\n| API | GraphQL | 灵活的数据查询接口 |\n| 数据库 | PostgreSQL | 关系型数据存储 |\n| ORM | TypeORM | 数据库对象关系映射 |\n| 认证 | JWT | 无状态身份验证 |\n| 缓存 | Redis | 会话和数据缓存 |\n\n## 模块化架构\n\nTwenty 后端采用 **模块化架构（Module-based Architecture）**，每个功能领域都封装在独立的模块中。这种设计模式确保了代码的**高内聚、低耦合**，便于团队协作开发和功能扩展。\n\n### 核心模块结构\n\n```mermaid\ngraph TD\n A[twenty-server] --> B[modules]\n A --> C[core]\n A --> D[database]\n A --> E[graphql]\n \n B --> B1[companies]\n B --> B2[people]\n B --> B3[opportunities]\n B --> B4[activities]\n B --> B5[calendar]\n B --> B6[ai]\n B --> B7[messaging]\n \n C --> C1[auth]\n C --> C2[config]\n C --> C3[utils]\n \n D --> D1[migrations]\n D --> D2[seeds]\n```\n\n核心模块位于 `packages/twenty-server/src/modules` 目录下，每个子模块通常包含以下结构：\n\n```\nmodules/[module-name]/\n├── resolvers/ # GraphQL 解析器\n├── services/ # 业务逻辑服务\n├── repositories/ # 数据访问层\n├── entities/ # 数据库实体定义\n├── dto/ # 数据传输对象\n└── tests/ # 单元测试\n```\n\n## GraphQL API 层\n\nTwenty 通过 GraphQL 提供统一的数据接口，前端和其他客户端可以通过灵活的查询语法获取所需数据。GraphQL 层负责处理客户端请求的解析、权限验证和响应格式化。\n\n### API 端点结构\n\n```mermaid\ngraph LR\n A[Client] -->|GraphQL Query/Mutation| B[GraphQL Server]\n B --> C[Resolver Layer]\n C --> D[Service Layer]\n D --> E[Repository Layer]\n E --> F[(PostgreSQL)]\n \n G[Auth Service] -->|JWT Validation| B\n H[Cache Layer] -->|Redis Cache| D\n```\n\n### 查询示例\n\n```graphql\nquery GetCompaniesWithOpportunities {\n findManyCompany(\n where: { deletedAt: { equals: null } }\n orderBy: { createdAt: Desc }\n take: 10\n ) {\n id\n name\n domain\n opportunities {\n id\n amount\n stage\n }\n }\n}\n```\n\nGraphQL API 支持以下主要操作：\n\n| 操作类型 | 说明 | 示例 |\n|---------|------|------|\n| Query | 数据查询 | 获取公司列表、联系人详情 |\n| Mutation | 数据变更 | 创建商机、更新联系人 |\n| Subscription | 实时推送 | 任务状态变更通知 |\n\n## 数据模型\n\nTwenty 后端定义了丰富的 CRM 数据模型，涵盖企业运营的各个方面。核心实体通过 TypeORM 注解与数据库表映射。\n\n### 主要实体关系\n\n```mermaid\nerDiagram\n COMPANY ||--o{ PERSON : has\n COMPANY ||--o{ OPPORTUNITY : manages\n PERSON ||--o{ ACTIVITY : performs\n OPPORTUNITY ||--o{ ACTIVITY : generates\n USER ||--o{ ACTIVITY : owns\n USER ||--o{ COMPANY : assigns\n```\n\n### 核心实体说明\n\n| 实体名称 | 说明 | 主要字段 |\n|---------|------|---------|\n| Company | 公司/组织 | name, domain, employees, revenue |\n| Person | 联系人 | name, email, phone, companyId |\n| Opportunity | 商机 | name, amount, stage, probability |\n| Activity | 活动记录 | type, title, body, dueAt |\n| User | 系统用户 | email, name, role, workspace |\n| Workspace | 工作空间 | name, logo, settings |\n\n## 认证与授权\n\nTwenty 后端采用 **JWT（JSON Web Token）** 实现无状态身份验证，用户登录后获取 token，后续请求通过 token 验证用户身份。\n\n### 认证流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n participant Database\n \n Client->>Server: POST /auth/login (email, password)\n Server->>Database: 验证用户凭据\n Database-->>Server: 用户数据\n Server->>Server: 生成 JWT Token\n Server-->>Client: { accessToken, refreshToken }\n \n Client->>Server: GET /graphql (Authorization: Bearer )\n Server->>Server: 验证 Token\n Server-->>Client: 请求的数据\n```\n\n### 权限控制\n\n系统支持基于角色的访问控制（RBAC），不同角色拥有不同的数据操作权限：\n\n| 角色 | 数据访问 | 操作权限 |\n|-----|---------|---------|\n| Admin | 全部数据 | 完全控制 |\n| Member | 分配的数据 | 创建、更新、查看 |\n| Viewer | 分配的数据 | 仅查看 |\n\n## 移动端支持与 SDK\n\nTwenty 提供 `twenty-sdk` 作为构建第三方应用的基础，支持开发者基于 Twenty CRM 构建自定义应用。通过官方提供的 `create-twenty-app` CLI 工具，开发者可以快速初始化项目。\n\n```bash\nnpx create-twenty-app@latest my-twenty-app\ncd my-twenty-app\nyarn twenty dev\n```\n\nSDK 负责处理以下功能：\n\n- GraphQL API 通信封装\n- 身份验证流程管理\n- 数据缓存与同步\n- 离线模式支持\n\n## 企业部署与激活\n\n对于企业客户，Twenty 提供自托管部署方案。企业版用户可以通过许可证密钥激活系统，实现完全的数据控制和定制化需求。\n\n### 激活流程\n\n```mermaid\ngraph TD\n A[购买企业许可证] --> B[获取许可证密钥]\n B --> C[部署 Twenty 实例]\n C --> D[激活页面配置密钥]\n D --> E{验证密钥}\n E -->|成功| F[启用企业功能]\n E -->|失败| G[检查密钥有效性]\n G --> D\n```\n\n激活相关的前端页面位于 `packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx`，使用 `Suspense` 和错误边界组件确保用户体验。\n\n## 数据库设计\n\nTwenty 使用 PostgreSQL 作为主数据库，通过 TypeORM 实现对象关系映射，支持数据库迁移和种子数据管理。\n\n### 数据库目录结构\n\n```\npackages/twenty-server/src/database/\n├── migrations/ # 数据库迁移脚本\n├── seeds/ # 初始化种子数据\n└── typeorm/ # 数据库配置\n```\n\n### 迁移管理\n\n系统支持数据库版本控制，通过迁移脚本确保数据库结构与代码版本同步：\n\n```bash\n# 运行迁移\nyarn database:migrate\n\n# 回滚迁移\nyarn database:rollback\n\n# 生成新迁移\nyarn database:generate --name=add_new_field\n```\n\n## 配置管理\n\nTwenty 后端支持灵活的环境配置，通过环境变量和配置文件管理不同部署环境的参数。\n\n### 配置项说明\n\n| 配置类别 | 环境变量 | 说明 |\n|---------|---------|------|\n| 数据库 | DATABASE_URL | PostgreSQL 连接字符串 |\n| 缓存 | REDIS_URL | Redis 连接地址 |\n| 认证 | JWT_SECRET | Token 签名密钥 |\n| AI | OPENAI_API_KEY | AI 服务 API 密钥 |\n| 邮件 | SMTP_HOST | 邮件服务器地址 |\n\n## 开发贡献指南\n\n开发者可以通过以下方式参与 Twenty 后端开发：\n\n1. **本地开发环境**：参考 `packages/twenty-docs/developers/contribute/capabilities/backend-development` 文档\n2. **代码规范**：遵循项目定义的 ESLint 和 Prettier 配置\n3. **测试覆盖**：新增功能需包含对应的单元测试和集成测试\n4. **提交规范**：使用 Conventional Commits 格式描述变更\n\n## 扩展能力\n\nTwenty 后端设计支持多种扩展方式：\n\n- **自定义对象**：创建符合业务需求的 CRM 实体\n- **工作流自动化**：定义触发器和自动化动作\n- **API 扩展**：通过 Apollo Federation 集成外部服务\n- **Webhook**：与外部系统的事件集成\n\n## 总结\n\nTwenty 的后端架构采用现代化的模块化设计，通过 GraphQL API 提供灵活的数据接口，支持企业级 CRM 功能的实现。系统具备良好的可扩展性，支持自托管和云端两种部署模式，为不同规模的企业提供可靠的 CRM 解决方案。\n\n---\n\n\n\n## 数据模型\n\n### 相关页面\n\n相关主题：[后端架构](#page-server-architecture), [Activities活动模块](#page-activities-module)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/field-metadata/compute-note-target-standard-flat-field-metadata.util.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/field-metadata/compute-note-target-standard-flat-field-metadata.util.ts)\n- [packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/field-metadata/compute-blocklist-standard-flat-field-metadata.util.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/field-metadata/compute-blocklist-standard-flat-field-metadata.util.ts)\n- [packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/object-metadata/create-standard-flat-object-metadata.util.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/object-metadata/create-standard-flat-object-metadata.util.ts)\n- [packages/twenty-front/src/pages/onboarding/CreateWorkspace.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/pages/onboarding/CreateWorkspace.tsx)\n \n\n# 数据模型\n\n## 概述\n\nTwenty 的数据模型是一个基于元数据驱动（Metadata-Driven）的动态数据架构，它允许用户在不修改代码的情况下自定义数据对象、字段和关系。系统采用 Prisma ORM 作为底层数据库抽象，并通过标准应用层（Twenty Standard Application）定义一组开箱即用的标准对象。\n\n数据模型的核心设计理念：\n\n- **对象（Object）**：代表业务实体，如 Company、Person、Opportunity 等\n- **字段（Field）**：描述对象的属性，包含类型、默认值、验证规则等元信息\n- **关系（Relation）**：定义对象之间的关联，支持一对一、一对多、多对多\n- **工作区隔离**：每个工作区拥有独立的数据模型实例，实现多租户隔离\n\n## 核心组件\n\n### 标准对象（Standard Objects）\n\n标准对象是 Twenty 内置的业务实体，涵盖 CRM 核心场景：\n\n| 对象名称 | 标识符 | 描述 | 标签标识字段 |\n|---------|--------|------|-------------|\n| Company | company | 公司/组织 | name |\n| Person | person | 个人联系人 | name |\n| Opportunity | opportunity | 销售机会 | name |\n| Note | note | 笔记 | title |\n| NoteTarget | noteTarget | 笔记关联目标 | - |\n| Message | message | 消息 | subject |\n| MessageThread | messageThread | 消息线程 | subject |\n| Blocklist | blocklist | 黑名单 | - |\n\n### 标准字段（Standard Fields）\n\n每个对象都包含一组标准字段，继承自 `BaseWorkspaceEntity` 基类：\n\n| 字段名 | 类型 | 说明 | 系统字段 |\n|--------|------|------|----------|\n| id | UUID | 全局唯一标识 | 是 |\n| createdAt | DATE_TIME | 创建时间 | 是 |\n| updatedAt | DATE_TIME | 最后更新时间 | 是 |\n| deletedAt | DATE_TIME | 软删除时间 | 是 |\n\n资料来源：[compute-note-target-standard-flat-field-metadata.util.ts:11-49]()\n\n### 字段类型（FieldMetadataType）\n\n系统支持多种字段类型：\n\n| 类型标识 | 说明 | 是否支持默认值 |\n|---------|------|---------------|\n| UUID | 通用唯一标识符 | 支持（`uuid`） |\n| DATE_TIME | 日期时间 | 支持（`now`） |\n| TEXT | 文本 | 支持 |\n| NUMBER | 数字 | 支持 |\n| BOOLEAN | 布尔值 | 支持 |\n| CURRENCY | 货币 | 支持 |\n| RELATION | 关系 | 不支持 |\n\n## 元数据计算机制\n\n### 对象元数据创建\n\n标准对象元数据通过 `createStandardObjectFlatMetadata` 工具函数创建：\n\n```typescript\ncreateStandardObjectFlatMetadata({\n objectName: 'messageThread',\n dependencyFlatEntityMaps,\n context: {\n universalIdentifier: STANDARD_OBJECTS.messageThread.universalIdentifier,\n nameSingular: 'messageThread',\n namePlural: 'messageThreads',\n labelSingular: i18nLabel(msg`Message Thread`),\n labelPlural: i18nLabel(msg`Message Threads`),\n icon: 'IconMessage',\n isSystem: true,\n isAuditLogged: false,\n labelIdentifierFieldMetadataName: 'subject',\n },\n workspaceId,\n standardObjectMetadataRelatedEntityIds,\n twentyStandardApplicationId,\n now,\n})\n```\n\n资料来源：[create-standard-flat-object-metadata.util.ts:120-145]()\n\n### 字段元数据计算\n\n字段元数据通过专用的计算工具生成。以 `noteTarget` 对象为例：\n\n```typescript\ncreateStandardFieldFlatMetadata({\n objectName,\n workspaceId,\n context: {\n fieldName: 'createdAt',\n type: FieldMetadataType.DATE_TIME,\n label: i18nLabel(msg`Creation date`),\n description: i18nLabel(msg`Creation date`),\n icon: 'IconCalendar',\n isSystem: true,\n isNullable: false,\n isUIReadOnly: true,\n defaultValue: 'now',\n settings: {\n displayFormat: DateDisplayFormat.RELATIVE,\n },\n },\n standardObjectMetadataRelatedEntityIds,\n dependencyFlatEntityMaps,\n twentyStandardApplicationId,\n now,\n})\n```\n\n资料来源：[compute-note-target-standard-flat-field-metadata.util.ts:25-55]()\n\n## 工作区数据模型初始化\n\n当用户创建新工作区时，系统执行三步初始化流程：\n\n```mermaid\ngraph TD\n A[用户提交创建工作区] --> B[Step 1: 设置数据库]\n B --> C[Step 2: 创建数据模型]\n C --> D[Step 3: 预填充工作区数据]\n D --> E[工作区就绪]\n```\n\n资料来源：[CreateWorkspace.tsx:1-50]()\n\n### 初始化步骤说明\n\n| 步骤 | 标识符 | 用户提示文案 |\n|------|--------|-------------|\n| 1 | Step1 | Setting up your database... |\n| 2 | Step2 | Creating your data model... |\n| 3 | Step3 | Prefilling your workspace data... |\n\n```tsx\n{pendingCreationLoaderStep === PendingCreationLoaderStep.Step1 && (\n \n Setting up your database...\n \n)}\n{pendingCreationLoaderStep === PendingCreationLoaderStep.Step2 && (\n \n Creating your data model...\n \n)}\n{pendingCreationLoaderStep === PendingCreationLoaderStep.Step3 && (\n \n Prefilling your workspace data...\n \n)}\n```\n\n资料来源：[CreateWorkspace.tsx:35-48]()\n\n## 数据模型架构图\n\n```mermaid\ngraph TB\n subgraph 工作区层\n WM[Workspace Manager]\n SM[Standard Metadata]\n end\n \n subgraph 对象层\n CO[Company]\n PE[Person]\n OP[Opportunity]\n NO[Note]\n NOB[NoteTarget]\n end\n \n subgraph 字段层\n ID[BaseFields
id, createdAt, updatedAt]\n CF[Custom Fields]\n RF[Relation Fields]\n end\n \n subgraph 存储层\n PR[Prisma ORM]\n DB[(PostgreSQL)]\n end\n \n WM --> SM\n SM --> CO\n SM --> PE\n SM --> OP\n SM --> NO\n NO --> NOB\n \n CO --> ID\n PE --> ID\n CO --> CF\n PE --> CF\n CO --> RF\n PE --> RF\n \n PR --> DB\n```\n\n## 字段属性配置\n\n### 系统字段标记\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| isSystem | boolean | 是否为系统字段（不可删除） |\n| isNullable | boolean | 是否允许为空 |\n| isUIReadOnly | boolean | UI 是否只读 |\n| isAuditLogged | boolean | 是否记录审计日志 |\n\n### 日期字段显示格式\n\n```typescript\nsettings: {\n displayFormat: DateDisplayFormat.RELATIVE,\n}\n```\n\n支持的显示格式：\n\n| 格式 | 说明 |\n|------|------|\n| DateDisplayFormat.RELATIVE | 相对时间（1小时前） |\n| DateDisplayFormat.DATE_ONLY | 仅日期 |\n| DateDisplayFormat.DATE_TIME | 日期时间 |\n\n资料来源：[compute-blocklist-standard-flat-field-metadata.util.ts:25-60]()\n\n## 依赖管理\n\n数据模型采用依赖驱动（Dependency-Driven）的初始化机制。对象之间的依赖关系通过 `dependencyFlatEntityMaps` 传递：\n\n```typescript\ntype FlatFieldMetadata = {\n id: string;\n objectName: string;\n fieldName: string;\n type: FieldMetadataType;\n workspaceId: string;\n isSystem: boolean;\n isNullable: boolean;\n defaultValue: string | null;\n};\n```\n\n依赖计算确保父对象先于子对象创建，保证数据完整性。\n\n## 总结\n\nTwenty 的数据模型采用元数据驱动的设计，通过以下核心机制实现灵活性：\n\n1. **标准对象层**：提供开箱即用的 CRM 实体\n2. **字段元数据层**：支持多种类型和丰富配置\n3. **工作区隔离**：确保多租户数据安全\n4. **依赖解析**：保证对象创建顺序正确\n\n该架构允许开发者在不修改核心代码的前提下扩展业务实体，同时通过 Prisma 抽象保证数据库层面的类型安全和迁移管理。\n\n---\n\n\n\n## Activities活动模块\n\n### 相关页面\n\n相关主题：[前端架构](#page-frontend-architecture), [Views与Pipelines](#page-views-pipelines), [数据模型](#page-database-models)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/twenty-front/src/modules/activities](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/activities)\n- [packages/twenty-front/src/modules/activities/emails](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/activities/emails)\n- [packages/twenty-front/src/modules/activities/tasks](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/activities/tasks)\n- [packages/twenty-front/src/modules/activities/calendar](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/activities/calendar)\n- [packages/twenty-front/src/modules/activities/types/ActivityForEditor.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/activities/types/ActivityForEditor.ts)\n- [packages/twenty-website-new/src/sections/Feature/visuals/EmailsVisual.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/sections/Feature/visuals/EmailsVisual.tsx)\n- [packages/twenty-website-new/src/sections/Feature/visuals/TasksVisual.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/sections/Feature/visuals/TasksVisual.tsx)\n\n \n\n# Activities活动模块\n\n## 概述\n\nActivities活动模块是Twenty CRM系统中用于管理用户日常业务活动的核心功能模块。该模块涵盖了任务的创建与管理、便笺的记录以及电子邮件线程的查看等关键功能。Activities模块作为Twenty前端架构的重要组成部分，为用户提供了统一的交互界面来处理与客户关系相关的各类活动数据。\n\nActivities模块的设计理念是将分散的业务活动统一到一个集中的管理平台，使用户能够在单一界面内完成从任务分配、进度跟踪到沟通记录的全流程操作。该模块与其他业务对象（如联系人、公司、交易等）紧密集成，确保了数据的关联性和可追溯性。\n\n## 模块架构\n\n### 目录结构\n\nActivities模块位于`packages/twenty-front/src/modules/activities`目录下，采用功能分组的组织方式：\n\n```\nactivities/\n├── types/ # 类型定义\n│ └── ActivityForEditor.ts # 编辑器活动类型\n├── emails/ # 邮件相关组件\n├── tasks/ # 任务相关组件\n└── calendar/ # 日历相关组件\n```\n\n### 核心类型定义\n\nActivities模块的核心类型定义位于`ActivityForEditor.ts`文件中，定义了用于编辑器场景的活动数据结构：\n\n```typescript\nimport { type Note } from '@/activities/types/Note';\nimport { type Task } from '@/activities/types/Task';\n\nexport type ActivityForEditor = Partial &\n Partial> &\n Partial>;\n```\n\n这个联合类型的设计允许编辑器同时处理Task和Note两种活动类型，并通过`Partial`和`Pick`工具类型精确选择所需的字段，确保了类型系统的灵活性和安全性。\n\n## 功能模块详解\n\n### 任务模块 (Tasks)\n\n任务模块负责管理和展示用户创建的业务任务。从视觉组件`TasksVisual.tsx`的实现可以看出，任务系统包含以下核心要素：\n\n| 组件属性 | 说明 |\n|---------|------|\n| `task` | 任务描述文本 |\n| `completed` | 任务完成状态 |\n| `dueAt` | 任务截止日期 |\n| `assignee` | 任务负责人 |\n| `taskTargets` | 任务关联目标 |\n| `status` | 任务状态 |\n\n任务在界面上以列表形式展示，每个任务项包含完成状态指示器、任务名称和关联的时间戳。用户可以通过点击完成状态指示器来切换任务的完成状态，界面会通过删除线样式（`data-strikethrough`）来直观展示已完成的任务。\n\n### 邮件模块 (Emails)\n\n邮件模块提供了邮件线程的查看和管理功能。从`EmailsVisual.tsx`组件的实现来看，邮件系统包含以下结构：\n\n```typescript\ntype EmailsVisualProps = {\n active: boolean;\n};\n\nexport function EmailsVisual({ active: _active }: EmailsVisualProps) {\n const [openEmail, setOpenEmail] = useState(null);\n // ...\n}\n```\n\n邮件界面采用标签页式导航设计，包含多个邮件夹选项。每个邮件项展示发件人头像、发件人姓名、邮件主题和时间戳。点击邮件后可以展开查看完整的邮件内容，包括邮件线程中的所有消息记录。\n\n邮件组件的核心数据结构包括：\n\n- **DetailHeader**：邮件头部区域，显示主题和返回按钮\n- **DetailSenderRow**：发件人信息行，包含头像、名称和时间\n- **DetailContent**：邮件正文内容\n- **ThreadMessage**：线程消息组件\n\n### 日历模块 (Calendar)\n\n日历模块用于展示和安排与活动相关的时间信息。该模块与任务模块深度集成，支持基于截止日期的时间视图展示。\n\n## 数据流与状态管理\n\nActivities模块采用了现代化的状态管理模式，组件内部使用React Hooks管理本地状态。以下是典型的状态管理模式：\n\n```mermaid\ngraph TD\n A[用户操作] --> B[组件状态更新]\n B --> C{状态类型判断}\n C -->|完成状态| D[UI渲染更新]\n C -->|邮件操作| E[邮件列表更新]\n C -->|任务操作| F[任务列表更新]\n D --> G[持久化存储]\n E --> G\n F --> G\n```\n\n### 状态管理要点\n\nActivities模块中的状态管理包含以下几个关键方面：\n\n1. **本地状态管理**：使用`useState`管理组件级别的状态，如邮件展开状态\n2. **条件渲染**：根据状态值决定UI展示内容，如根据`openEmail === null`判断显示邮件列表还是详情\n3. **时间控制**：支持时间戳的展示和格式化\n\n## 视觉展示组件\n\nTwenty网站营销页面中的Features模块提供了丰富的可视化演示，展示了Activities功能在实际应用场景中的表现。\n\n### 任务可视化\n\n`TasksVisual.tsx`组件展示了任务列表的交互效果：\n\n- 使用`ActivityRow`作为单个任务行的容器\n- 使用`TaskCircleEl`展示完成状态指示器\n- 使用`ActivityBody`包裹任务主体内容\n- 使用`Timestamp`组件显示任务关联时间\n\n### 邮件可视化\n\n`EmailsVisual.tsx`组件模拟了完整的邮件客户端界面：\n\n- 使用`TabBar`展示邮件分类标签\n- 使用`InboxHeader`展示收件箱头部\n- 使用`DetailHeader`和`DetailBody`构建邮件详情视图\n- 支持邮件线程的展开和折叠\n\n## 组件关联图\n\n```mermaid\ngraph LR\n A[Activities模块] --> B[Task任务]\n A --> C[Note便笺]\n A --> D[Email邮件]\n A --> E[Calendar日历]\n B --> F[status]\n B --> G[dueAt]\n B --> H[assignee]\n B --> I[taskTargets]\n C --> J[noteTargets]\n D --> K[subject]\n D --> L[thread]\n```\n\n## 类型安全设计\n\nActivities模块在TypeScript类型安全方面做了精心设计。`ActivityForEditor`类型采用了以下设计模式：\n\n1. **联合类型**：使用`Task | Note`表示活动可以是任务或便笺\n2. **交叉类型**：通过`&`操作符合并多个类型约束\n3. **部分选择**：使用`Partial>`精确选择需要的字段子集\n\n这种设计模式的优势在于：\n- 提供了编译时类型检查\n- 支持灵活的数据组合\n- 便于扩展新的活动类型\n\n## 与后端标准对象的关联\n\nActivities模块与后端的数据模型紧密对应。根据服务端代码结构，系统定义了一系列标准对象来支撑活动功能的实现：\n\n| 后端对象 | 前端类型 | 说明 |\n|---------|---------|------|\n| messageThread | Email Thread | 邮件会话线程 |\n| message | Email Message | 单条邮件消息 |\n| task | Task | 业务任务 |\n| note | Note | 便笺记录 |\n\n这些标准对象定义了系统级别的活动元数据，包括对象名称、标签、图标等配置信息。\n\n## 总结\n\nActivities活动模块是Twenty CRM系统中连接用户日常业务操作与系统数据管理的核心桥梁。通过任务、便笺、邮件和日历四个子模块的协同工作，该模块为用户提供了完整的活动管理能力。\n\n模块的设计遵循了现代前端开发的最佳实践，包括：\n- 清晰的类型定义和类型安全保证\n- 模块化的组件结构\n- 灵活的状态管理方案\n- 与后端标准对象模型的完整对应\n\n这些设计使得Activities模块能够有效支撑企业的客户关系管理需求，同时保持了代码的可维护性和可扩展性。\n\n---\n\n\n\n## Views与Pipelines\n\n### 相关页面\n\n相关主题：[Activities活动模块](#page-activities-module), [前端架构](#page-frontend-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/twenty-front/src/modules/views](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views)\n- [packages/twenty-front/src/modules/pipelines](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines)\n- [packages/twenty-docs/user-guide/views-pipelines](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/user-guide/views-pipelines)\n- [packages/twenty-front/src/modules/views/states](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views/states)\n- [packages/twenty-front/src/modules/pipelines/states](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines/states)\n- [packages/twenty-front/src/modules/views/hooks](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views/hooks)\n- [packages/twenty-front/src/modules/pipelines/hooks](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines/hooks)\n- [packages/twenty-front/src/modules/views/components](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views/components)\n- [packages/twenty-front/src/modules/pipelines/components](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines/components)\n \n\n# Views与Pipelines\n\n## 概述\n\nViews（视图）和 Pipelines（管道）是 Twenty CRM 中两个核心的数据展示与业务流程管理模块。它们共同构成了系统处理和组织工作流数据的基础架构，使企业能够灵活地自定义数据展示方式和管理销售/业务管道流程。\n\n**Views** 负责定义数据列表的展示方式，包括字段配置、排序规则、筛选条件和显示布局等。**Pipelines** 则专注于管理业务流程管道，如销售管道中的阶段流转、机会追踪和自动化工作流。\n\n资料来源：[packages/twenty-front/src/modules/views](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views)\n资料来源：[packages/twenty-front/src/modules/pipelines](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines)\n\n## 架构设计\n\n### 模块层级结构\n\nTwenty 采用模块化架构设计，Views 和 Pipelines 作为独立的功能模块存在。以下是整体架构关系：\n\n```mermaid\ngraph TD\n A[Twenty Frontend] --> B[Views 模块]\n A --> C[Pipelines 模块]\n B --> D[States 状态管理]\n B --> E[Hooks 自定义钩子]\n B --> F[Components 组件]\n C --> G[States 状态管理]\n C --> H[Hooks 自定义钩子]\n C --> I[Components 组件]\n D --> J[recoil 状态Atom]\n G --> J\n```\n\n### Views 与 Pipelines 的关系\n\nViews 和 Pipelines 存在紧密的关联关系。Pipeline 视图本质上是一种特殊的 Views 实现，专门用于展示管道阶段和卡片式布局。\n\n```mermaid\ngraph TD\n A[View] -->|继承| B[BaseView]\n A -->|扩展| C[PipelineView]\n C -->|包含| D[PipelineStages]\n C -->|包含| E[PipelineSteps]\n C -->|包含| F[Opportunities]\n D -->|关联| E\n```\n\n资料来源：[packages/twenty-docs/user-guide/views-pipelines](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/user-guide/views-pipelines)\n\n## Views 模块详解\n\n### 模块结构\n\nViews 模块位于 `packages/twenty-front/src/modules/views/`，包含以下核心子目录：\n\n| 子目录 | 功能说明 |\n|--------|----------|\n| `states/` | Recoil 状态定义，包含视图配置的 Atom |\n| `hooks/` | 自定义 React Hooks，提供视图操作接口 |\n| `components/` | 视图相关 UI 组件 |\n| `types/` | TypeScript 类型定义 |\n| `utils/` | 视图工具函数 |\n\n资料来源：[packages/twenty-front/src/modules/views](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views)\n\n### 状态管理\n\nViews 模块使用 Recoil 进行状态管理，主要的状态 Atom 包括：\n\n```typescript\n// 视图配置状态\nviewIdState // 当前视图ID\nviewSortsState // 排序规则\nviewFiltersState // 筛选条件\nviewFieldsState // 字段配置\nviewkanbanHideState // 看板隐藏状态\n```\n\n这些状态通过 Selector 进行派生计算，实现视图配置的响应式更新。\n\n资料来源：[packages/twenty-front/src/modules/views/states](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views/states)\n\n### 核心 Hooks\n\nViews 模块提供了多个自定义 Hooks 用于视图操作：\n\n| Hook 名称 | 功能 |\n|-----------|------|\n| `useViews` | 获取视图列表和当前视图 |\n| `useView` | 单个视图的 CRUD 操作 |\n| `useViewSorts` | 排序规则管理 |\n| `useViewFilters` | 筛选条件管理 |\n| `useViewFields` | 字段配置管理 |\n| `useUpdateViewSorts` | 更新排序规则 |\n| `useUpdateViewFilters` | 更新筛选条件 |\n\n资料来源：[packages/twenty-front/src/modules/views/hooks](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views/hooks)\n\n### 视图类型\n\n系统支持多种视图类型，每种类型有不同的展示方式和配置选项：\n\n| 视图类型 | 标识符 | 描述 |\n|----------|--------|------|\n| 列表视图 | `Table` | 表格形式展示数据，支持列配置 |\n| 看板视图 | `Kanban` | 卡片分组展示，按阶段/字段分组 |\n| 画廊视图 | `Gallery` | 卡片网格展示，适合媒体内容 |\n| 时间线视图 | `Timeline` | 时间轴形式展示 |\n\n## Pipelines 模块详解\n\n### 模块结构\n\nPipelines 模块位于 `packages/twenty-front/src/modules/pipelines/`，是 Views 模块在业务管道场景下的扩展实现：\n\n| 子目录 | 功能说明 |\n|--------|----------|\n| `states/` | 管道相关状态定义 |\n| `hooks/` | 管道操作的自定义钩子 |\n| `components/` | 管道展示组件（看板、卡片等） |\n| `types/` | 管道相关类型定义 |\n| `utils/` | 管道工具函数 |\n\n资料来源：[packages/twenty-front/src/modules/pipelines](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines)\n\n### 管道数据模型\n\n```mermaid\nclassDiagram\n class Pipeline {\n +id: string\n +name: string\n +icon: string\n +stages: PipelineStage[]\n }\n class PipelineStage {\n +id: string\n +name: string\n +color: string\n +position: number\n +opportunities: Opportunity[]\n }\n class Opportunity {\n +id: string\n +title: string\n +companyId: string\n +pipelineStageId: string\n +amount: number\n +probability: number\n }\n \n Pipeline \"1\" *-- \"n\" PipelineStage\n PipelineStage \"1\" *-- \"n\" Opportunity\n```\n\n### 状态管理\n\nPipelines 模块的状态管理基于 Recoil，主要包括：\n\n```typescript\n// 管道状态\npipelinesState // 所有管道列表\ncurrentPipelineState // 当前选中管道\npipelineStagesState // 管道阶段\n\n// 机会状态\nopportunitiesState // 所有机会\nopportunitiesByPipelineStageState // 按阶段分组的机会\n```\n\n资料来源：[packages/twenty-front/src/modules/pipelines/states](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines/states)\n\n### 核心 Hooks\n\n| Hook 名称 | 功能 |\n|-----------|------|\n| `usePipelines` | 获取管道列表 |\n| `usePipeline` | 单个管道操作 |\n| `usePipelineStages` | 管道阶段管理 |\n| `useOpportunities` | 机会管理 |\n| `useOpportunity` | 单个机会 CRUD |\n| `useUpdatePipelineStage` | 更新阶段信息 |\n| `useUpdateOpportunity` | 更新机会信息 |\n\n资料来源：[packages/twenty-front/src/modules/pipelines/hooks](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines/hooks)\n\n## 数据流与工作流程\n\n### 视图数据加载流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant C as Component\n participant H as Hook\n participant S as State\n participant A as API\n \n U->>C: 选择视图\n C->>H: useView(viewId)\n H->>S: 读取 viewIdState\n S-->>H: 返回视图配置\n H->>A: 请求视图数据\n A-->>H: 返回记录列表\n H->>S: 更新 viewDataState\n S-->>C: 触发重新渲染\n C-->>U: 展示视图数据\n```\n\n### 管道阶段流转\n\n```mermaid\ngraph LR\n A[新建机会] --> B[资格筛选]\n B --> C[需求分析]\n C --> D[提案报价]\n D --> E[谈判审核]\n E --> F[成交]\n E --> G[输单]\n \n style A fill:#e1f5fe\n style F fill:#c8e6c9\n style G fill:#ffcdd2\n```\n\n## 组件系统\n\n### Views 组件\n\nViews 模块的组件位于 `packages/twenty-front/src/modules/views/components/`，主要组件包括：\n\n| 组件 | 用途 |\n|------|------|\n| `ViewBar` | 视图顶部导航栏 |\n| `ViewHeader` | 视图标题和操作按钮 |\n| `ViewFieldsVisibilityDropdown` | 字段显示/隐藏控制 |\n| `ViewSortDropdown` | 排序规则配置 |\n| `ViewFiltersDropdown` | 筛选条件配置 |\n| `Table` | 表格视图组件 |\n| `Board` | 看板视图组件 |\n\n资料来源：[packages/twenty-front/src/modules/views/components](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views/components)\n\n### Pipelines 组件\n\nPipelines 模块的组件位于 `packages/twenty-front/src/modules/pipelines/components/`：\n\n| 组件 | 用途 |\n|------|------|\n| `PipelineView` | 管道主视图容器 |\n| `PipelineBoard` | 看板式管道展示 |\n| `PipelineStageColumn` | 管道阶段列 |\n| `PipelineCard` | 机会卡片展示 |\n| `PipelineAddButton` | 添加阶段/机会按钮 |\n| `PipelineProgressBar` | 管道进度条 |\n\n资料来源：[packages/twenty-front/src/modules/pipelines/components](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines/components)\n\n## 配置与定制\n\n### 视图配置项\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `fields` | Field[] | 显示的字段列表及顺序 |\n| `sorts` | Sort[] | 排序规则 |\n| `filters` | Filter[] | 筛选条件 |\n| `kanbanHide` | string[] | 看板隐藏的阶段ID |\n| `kanbanGroupBy` | string | 看板分组字段 |\n\n### 管道配置项\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `name` | string | 管道名称 |\n| `icon` | string | 管道图标 |\n| `stages` | Stage[] | 阶段列表 |\n| `stageColors` | Record | 阶段颜色映射 |\n\n## 与其他模块的集成\n\nViews 和 Pipelines 模块与以下模块存在集成关系：\n\n```mermaid\ngraph TD\n V[Views/Pipelines] --> |使用| O[Objects 模块]\n V --> |使用| F[Fields 模块]\n V --> |使用| R[Relations 模块]\n V --> |渲染| UI[UI Components]\n O --> |提供数据模型| D[Data GraphQL]\n F --> |提供字段定义| D\n```\n\n### Objects 模块集成\n\nViews 基于 Objects（对象）模块定义的数据模型进行数据展示。每个视图绑定到特定的对象类型，如 \"Opportunity\"、\"Company\" 或 \"Person\"。\n\n### Fields 模块集成\n\n视图的字段配置依赖于 Fields 模块的字段定义系统，支持标准字段和自定义字段的动态配置。\n\n## 用户使用指南\n\n### 创建新视图\n\n1. 在对象列表页面，点击视图选择器\n2. 选择\"创建新视图\"\n3. 配置视图名称、图标和基础设置\n4. 配置显示字段、排序规则和筛选条件\n5. 保存视图\n\n### 配置销售管道\n\n1. 进入 Pipelines 设置页面\n2. 创建新管道或编辑现有管道\n3. 添加/编辑管道阶段\n4. 为每个阶段配置颜色和图标\n5. 设置阶段流转规则（如有）\n\n资料来源：[packages/twenty-docs/user-guide/views-pipelines](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/user-guide/views-pipelines)\n\n## 最佳实践\n\n### 视图优化建议\n\n| 实践 | 说明 |\n|------|------|\n| 限制字段数量 | 只显示必要字段，减少渲染开销 |\n| 使用索引筛选 | 在大数据集上优先使用索引字段进行筛选 |\n| 合理分组 | 看板视图避免过多分组导致的性能问题 |\n\n### 管道设计建议\n\n| 实践 | 说明 |\n|------|------|\n| 阶段数量控制 | 建议 4-7 个阶段，避免过于复杂 |\n| 明确流转规则 | 为每个阶段的流转定义清晰的触发条件 |\n| 机会状态同步 | 确保机会状态与管道阶段保持一致 |\n\n## 技术限制与注意事项\n\n- 视图配置存储在服务端，切换视图需要网络请求\n- 管道阶段不支持嵌套层级结构\n- 大型数据集（>10000 条记录）建议使用服务端分页\n- 自定义字段在视图中需要额外配置才能显示\n\n---\n\n\n\n## Apps扩展系统\n\n### 相关页面\n\n相关主题：[GitHub Connector示例](#page-github-connector), [Docker部署](#page-docker-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/twenty-apps/examples/hello-world](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/examples/hello-world)\n- [packages/create-twenty-app/src](https://github.com/twentyhq/twenty/blob/main/packages/create-twenty-app/src)\n- [packages/twenty-client-sdk/src](https://github.com/twentyhq/twenty/blob/main/packages/twenty-client-sdk/src)\n- [packages/twenty-docs/developers/extend/apps](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/developers/extend/apps)\n \n\n# Apps扩展系统\n\n## 概述\n\nTwenty的Apps扩展系统是一个模块化的应用扩展框架，允许开发者在Twenty CRM平台上构建和部署自定义业务应用程序。该系统采用现代化的插件架构，开发者可以创建独立的应用包，并在Twenty工作区内注册和使用这些应用。\n\nApps扩展系统的主要目标是：\n\n- 提供标准化的应用开发框架\n- 支持前端和后端代码的打包与分发\n- 与Twenty核心功能无缝集成\n- 支持应用的发现、安装和卸载流程\n\n## 核心组件\n\nApps扩展系统由以下几个核心包组成：\n\n| 包名 | 功能描述 | 位置 |\n|------|----------|------|\n| twenty-apps | 核心应用框架和运行时 | packages/twenty-apps |\n| twenty-client-sdk | 客户端SDK，提供React hooks和UI组件 | packages/twenty-client-sdk |\n| create-twenty-app | 应用脚手架工具，用于快速创建新应用 | packages/create-twenty-app |\n| twenty-docs | 开发者文档和API参考 | packages/twenty-docs/developers/extend/apps |\n\n## 应用架构\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[开发者] -->|create-twenty-app| B[新建App项目]\n B --> C[实现App功能]\n C --> D[打包应用]\n D --> E[twenty-apps运行时]\n E --> F[Twenty CRM]\n G[twenty-client-sdk] --> C\n```\n\n### 应用生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> 创建: create-twenty-app\n 创建 --> 开发: 编写代码\n 开发 --> 调试: 本地测试\n 调试 --> 打包: 构建生产版本\n 打包 --> 发布: 分发应用\n 发布 --> 安装: 用户安装\n 安装 --> 激活: 启用功能\n 激活 --> 使用: 运行中\n 使用 --> 卸载: 用户卸载\n 卸载 --> [*]\n```\n\n## twenty-client-sdk\n\n客户端SDK是Apps扩展系统的前端核心，提供了构建应用UI所需的React组件和Hooks。\n\n### 主要导出模块\n\nSDK包位于 `packages/twenty-client-sdk/src`，包含以下主要导出：\n\n- **React hooks**：用于数据获取、状态管理和与Twenty后端通信\n- **UI组件**：可复用的Twenty风格组件\n- **类型定义**：TypeScript类型和接口\n- **工具函数**：常用业务逻辑封装\n\n### 使用示例\n\n```typescript\nimport { useTwentyClient } from '@twenty/client-sdk';\n\n// 在App中使用Twenty客户端\nconst MyApp = () => {\n const client = useTwentyClient();\n // 通过client与Twenty后端交互\n};\n```\n\n## create-twenty-app\n\n`create-twenty-app` 是Twenty提供的命令行工具，用于快速生成新的App项目脚手架。\n\n### 命令行接口\n\n```bash\nnpx create-twenty-app@latest my-app\n```\n\n### 项目结构\n\n新建的应用项目包含以下标准结构：\n\n```\nmy-app/\n├── src/\n│ ├── index.tsx # 应用入口\n│ ├── App.tsx # 主应用组件\n│ └── components/ # 组件目录\n├── package.json\n├── twenty-app.config.ts # 应用配置\n└── tsconfig.json\n```\n\n### 应用配置\n\n应用配置文件 `twenty-app.config.ts` 定义应用的基本信息：\n\n| 配置项 | 类型 | 描述 |\n|--------|------|------|\n| name | string | 应用名称 |\n| version | string | 应用版本 |\n| description | string | 应用描述 |\n| icon | string | 应用图标标识 |\n\n## hello-world示例\n\n`packages/twenty-apps/examples/hello-world` 提供了一个完整的Hello World示例，展示了Apps扩展系统的基本用法。\n\n### 示例结构\n\n```\nhello-world/\n├── src/\n│ ├── index.tsx\n│ └── App.tsx\n├── package.json\n└── twenty-app.config.ts\n```\n\n### 核心实现\n\n示例应用演示了以下关键功能：\n\n1. **入口点定义**：通过 `index.tsx` 导出应用主组件\n2. **配置声明**：在 `package.json` 中声明应用元数据\n3. **基础UI渲染**：使用SDK组件构建简单界面\n\n## 开发流程\n\n### 环境准备\n\n1. 安装Node.js (v18+)\n2. 安装pnpm包管理器\n3. 克隆Twenty仓库\n\n### 创建新应用\n\n```bash\n# 使用create-twenty-app创建项目\npnpm create twenty-app my-first-app\n\n# 进入项目目录\ncd my-first-app\n\n# 安装依赖\npnpm install\n\n# 启动开发服务器\npnpm dev\n```\n\n### 开发规范\n\n- 使用TypeScript进行开发\n- 遵循Twenty的设计系统\n- 使用SDK提供的类型定义\n- 通过配置文件声明应用元数据\n\n### 打包发布\n\n```bash\n# 构建生产版本\npnpm build\n\n# 产出物位于 dist/ 目录\n```\n\n## 与Twenty核心的集成\n\nApps扩展系统与Twenty CRM核心深度集成，提供以下能力：\n\n### 数据访问\n\n通过 `twenty-client-sdk` 访问Twenty的数据模型：\n\n- 读取标准对象（如Company、Person、Opportunity）\n- 调用GraphQL API\n- 订阅实时数据更新\n\n### UI集成\n\n应用UI可以：\n\n- 使用Twenty的设计组件\n- 遵循Twenty的主题风格\n- 在Twenty的工作区界面中渲染\n\n### 功能扩展\n\n开发者可以通过App扩展以下功能：\n\n- 自定义数据展示\n- 业务工作流自动化\n- 第三方服务集成\n- 自定义报表和仪表盘\n\n## 最佳实践\n\n### 性能优化\n\n1. 使用SDK提供的缓存机制\n2. 实现合理的加载状态处理\n3. 避免不必要的重新渲染\n\n### 错误处理\n\n1. 使用try-catch包装API调用\n2. 向用户展示友好的错误提示\n3. 记录错误日志便于调试\n\n### 安全性\n\n1. 不在客户端存储敏感凭证\n2. 使用Twenty后端进行敏感操作\n3. 遵循最小权限原则\n\n## 相关资源\n\n| 资源类型 | 链接 |\n|----------|------|\n| 官方文档 | [Apps扩展文档](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/developers/extend/apps) |\n| 客户端SDK | [twenty-client-sdk](https://github.com/twentyhq/twenty/blob/main/packages/twenty-client-sdk/src) |\n| CLI工具 | [create-twenty-app](https://github.com/twentyhq/twenty/blob/main/packages/create-twenty-app/src) |\n| 示例代码 | [hello-world示例](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/examples/hello-world) |\n\n---\n\n\n\n## GitHub Connector示例\n\n### 相关页面\n\n相关主题：[Apps扩展系统](#page-apps-system), [后端架构](#page-server-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/twenty-apps/community/github-connector/README.md](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/community/github-connector/README.md)\n- [packages/twenty-apps/community/github-connector/src](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/community/github-connector/src)\n- [packages/twenty-apps/community/github-connector/src/modules/github](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/community/github-connector/src/modules/github)\n \n\n# GitHub Connector示例\n\n## 概述\n\nGitHub Connector 是 Twenty CRM 的一个社区应用集成模块，旨在将 GitHub 平台的数据与 Twenty CRM 系统进行深度整合。该连接器通过 GitHub App 认证机制获取授权，实现对 GitHub 仓库、Issue、Pull Request 以及 Projects (v2) 等数据的同步和展示。\n\n## 核心功能范围\n\nGitHub Connector 提供了以下核心能力：\n\n| 功能模块 | 描述 |\n|---------|------|\n| 仓库同步 | 自动同步指定的 GitHub 仓库数据 |\n| Issue 管理 | 读取和展示仓库中的 Issue 信息 |\n| Pull Request 追踪 | 监控和管理 Pull Request 状态 |\n| Projects v2 集成 | 支持 GitHub Projects (v2) 数据的读取 |\n\n## 认证机制\n\n### GitHub App 认证流程\n\nGitHub Connector 使用 GitHub App 认证方式进行授权，这种方式相比传统的 OAuth 更适合服务器端应用。\n\n```mermaid\nsequenceDiagram\n participant Connector as GitHub Connector\n participant GitHubAPI as GitHub API\n \n Note over Connector: 初始化配置\n Connector->>GitHubAPI: 使用 App Credentials 发起请求\n GitHubAPI-->>Connector: 返回 Installation Token\n Note over Connector: Token 缓存于内存\n Connector->>GitHubAPI: 使用 Installation Token 访问资源\n GitHubAPI-->>Connector: 返回请求的数据\n```\n\n### 必需的环境变量\n\n| 变量名 | 必需 | 说明 |\n|--------|------|------|\n| `GITHUB_APP_ID` | 是 | GitHub App 设置页面中的数字 App ID |\n| `GITHUB_APP_PRIVATE_KEY` | 是 | PEM 格式的私钥（支持换行） |\n| `GITHUB_APP_INSTALLATION_ID` | 是 | App 在组织/用户上的安装 ID |\n| `GITHUB_REPOS` | 是 | 逗号分隔的仓库列表，格式为 `owner/repo` |\n| `GITHUB_PROJECTS` | 否 | 逗号分隔的 GitHub Projects (v2) 列表 |\n\n## 创建 GitHub App\n\n要创建 GitHub App 并配置连接器，请按以下步骤操作：\n\n1. 访问 `https://github.com/settings/apps/new` 或组织页面 `https://github.com/organizations//settings/apps/new`\n2. 配置以下 **仓库权限**：\n\n| 权限类型 | 权限级别 |\n|---------|---------|\n| Contents | Read |\n| Issues | Read |\n| Pull Requests | Read |\n| Metadata | Read |\n| Organization → Projects (可选) | Read |\n\n3. 生成私钥（会下载 `.pem` 文件）\n4. 在组织/用户上安装 App，安装完成后的 URL 中包含安装 ID，格式为 `.../installations/12345678`\n5. 将 App ID、PEM 私钥内容和安装 ID 填入对应的环境变量\n\n## Token 管理\n\nGitHub Connector 实现了智能的 Token 缓存机制：\n\n- 连接器使用 App 凭证换取短期有效的安装 Token\n- Token 被缓存在内存中\n- 在 Token 即将过期前自动刷新\n- 所有 GitHub API 调用都通过该安装 Token 进行认证\n\n## 架构设计\n\n### 模块结构\n\n```\ngithub-connector/\n├── src/\n│ ├── modules/\n│ │ └── github/\n│ │ ├── services/ # GitHub API 服务层\n│ │ ├── types/ # TypeScript 类型定义\n│ │ └── utils/ # 工具函数\n│ └── index.ts # 模块入口\n└── README.md\n```\n\n### 数据流向\n\n```mermaid\ngraph LR\n A[GitHub API] -->|Installation Token| B[GitHub Connector]\n B -->|同步数据| C[Twenty CRM]\n C -->|存储| D[数据库]\n \n E[用户配置] -->|环境变量| B\n```\n\n## 集成示例场景\n\n### 场景一：团队协作数据同步\n\n将开发团队的 GitHub 活动（Issue 分配、PR 审查状态）同步到 CRM 中的相关公司或联系人记录，便于销售团队了解技术支持情况。\n\n### 场景二：项目管理视图\n\n通过 GitHub Projects (v2) 集成，在 Twenty CRM 中创建与 GitHub 项目进度对齐的任务视图。\n\n### 场景三：客户案例追踪\n\n对于使用 Twenty CRM 的技术咨询公司，可将客户项目的 GitHub 仓库活动作为交付进度的参考指标。\n\n## 配置示例\n\n### 环境变量配置\n\n```bash\n# 必需配置\nGITHUB_APP_ID=123456\nGITHUB_APP_PRIVATE_KEY=\"-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQD...\n-----END PRIVATE KEY-----\"\nGITHUB_APP_INSTALLATION_ID=12345678\nGITHUB_REPOS=octocat/hello-world,octo-org/octo-repo\n\n# 可选配置\nGITHUB_PROJECTS=octo-org:1,octo-org:2\n```\n\n### 仓库列表格式\n\n`GITHUB_REPOS` 环境变量支持以下格式：\n\n- 单个仓库：`owner/repo`\n- 多个仓库：`owner/repo1,owner/repo2,another-owner/another-repo`\n\n## 限制与注意事项\n\n| 注意事项 | 说明 |\n|---------|------|\n| 权限要求 | GitHub App 必须具有相应仓库的读取权限 |\n| 速率限制 | 受 GitHub API 速率限制约束 |\n| Token 有效期 | Installation Token 有时效性，Connector 自动处理刷新 |\n| 私钥格式 | 支持带换行的 PEM 格式 |\n\n## 相关资源\n\n- GitHub App 开发文档：https://docs.github.com/en/apps\n- Twenty 官方文档：https://docs.twenty.com\n- GitHub Connector 源码：https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/community/github-connector\n\n## 资料来源\n\n- [packages/twenty-apps/community/github-connector/README.md](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/community/github-connector/README.md)\n\n---\n\n\n\n## Docker部署\n\n### 相关页面\n\n相关主题：[后端架构](#page-server-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/twenty-docker/k8s/README.md](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docker/k8s/README.md)\n- [packages/twenty-docker/scripts/1-click.sh](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docker/scripts/1-click.sh)\n- [packages/twenty-docker/docker-compose.yml](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docker/docker-compose.yml)\n- [packages/twenty-docker/helm/twenty](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docker/helm/twenty)\n- [packages/twenty-docs/developers/self-host](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/developers/self-host)\n \n\n# Docker部署\n\nTwenty CRM 提供多种 Docker 部署方案，支持从简单的单机部署到复杂的 Kubernetes 集群部署。本文详细介绍如何使用 Docker 技术栈在自有基础设施上部署 Twenty CRM。\n\n## 部署方案概览\n\nTwenty 提供以下几种部署方式：\n\n| 部署方式 | 适用场景 | 复杂度 | 自动化程度 |\n|---------|---------|-------|-----------|\n| Docker Compose | 单机部署、开发环境 | 低 | 一键部署 |\n| Kubernetes | 生产集群 | 高 | 支持 Terraform |\n| Helm Chart | Kubernetes 命名空间 | 中高 | 可配置 |\n\n## 环境要求\n\n### 硬件要求\n\n- **CPU**: 最少 2 核，推荐 4 核以上\n- **内存**: 最少 4GB，推荐 8GB 以上\n- **磁盘**: 最少 20GB 可用空间\n\n### 软件要求\n\n- Docker Engine 20.10+\n- Docker Compose 2.0+\n- Kubernetes 1.24+（如需 K8s 部署）\n- Terraform 1.0+（可选）\n\n## Docker Compose 部署\n\nDocker Compose 是最简单快速的部署方式，适合单机运行或初步体验。\n\n### 快速开始\n\n```bash\n# 克隆仓库\ngit clone https://github.com/twentyhq/twenty.git\ncd twenty/packages/twenty-docker\n\n# 启动所有服务\ndocker-compose up -d\n```\n\n### 服务架构\n\n```mermaid\ngraph TD\n A[用户] --> B[NGINX反向代理]\n B --> C[Twenty Frontend]\n B --> D[Twenty Server]\n C --> E[PostgreSQL]\n D --> E\n D --> F[Redis]\n D --> G[MinIO对象存储]\n```\n\n### 环境变量配置\n\n创建 `.env` 文件配置必要的环境变量：\n\n```bash\n# 基础配置\nAPP_ENV=production\nRELEASE_VERSION=latest\n\n# 数据库配置\nPOSTGRES_DB=twenty\nPOSTGRES_USER=twenty\nPOSTGRES_PASSWORD=your_secure_password\n\n# 存储配置\nSTORAGE_S3_REGION=us-east-1\nSTORAGE_S3_BUCKET=twenty-storage\nSTORAGE_S3_ACCESS_KEY_ID=your_access_key\nSTORAGE_S3_SECRET_ACCESS_KEY=your_secret_key\n\n# 认证配置\nACCESS_TOKEN_SECRET=your_access_token_secret\nLOGIN_TOKEN_SECRET=your_login_token_secret\n```\n\n## 一键部署脚本\n\nTwenty 提供 `1-click.sh` 脚本实现自动化部署。\n\n### 脚本功能\n\n该脚本自动完成以下步骤：\n\n1. 环境检测与依赖验证\n2. 配置文件生成\n3. Docker 服务启动\n4. 数据库初始化\n5. 健康检查验证\n\n### 使用方法\n\n```bash\n# 下载并执行一键部署脚本\ncurl -fsSL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/1-click.sh | bash\n```\n\n### 脚本执行流程\n\n```mermaid\ngraph TD\n A[执行1-click.sh] --> B{检测Docker环境}\n B -->|缺失| C[提示安装Docker]\n B -->|存在| D[检查docker-compose]\n D --> E[生成配置文件]\n E --> F[拉取镜像]\n F --> G[启动服务]\n G --> H[健康检查]\n H -->|失败| I[回滚并报错]\n H -->|成功| J[部署完成]\n```\n\n## Kubernetes 部署\n\n对于生产环境，推荐使用 Kubernetes 进行部署以获得更好的可扩展性和高可用性。\n\n### 部署步骤\n\n#### 第一步：克隆仓库\n\n```bash\ngit clone https://github.com/twentyhq/twenty.git\ncd twenty/packages/twenty-docker/k8s\n```\n\n#### 第二步：自定义配置文件\n\n**重要提示**：Kubernetes 清单文件和 Terraform 配置文件需要根据实际环境进行自定义。更新占位符和配置以符合您的环境要求。\n\n#### 第三步：使用 Terraform 部署\n\n1. 进入 Terraform 目录：\n ```bash\n cd terraform\n ```\n\n2. 初始化 Terraform：\n ```bash\n terraform init\n ```\n\n3. 规划部署：\n ```bash\n terraform plan\n ```\n\n4. 执行部署：\n ```bash\n terraform apply\n ```\n\n#### 第三步（替代方案）：使用 Kubernetes 清单\n\n1. 创建命名空间：\n ```bash\n kubectl create namespace twentycrm\n ```\n\n2. 创建密钥：\n ```bash\n kubectl create secret generic -n twentycrm tokens \\\n --from-literal=accessToken=changeme \\\n --from-literal=loginToken=\"changeme\" \\\n --from-literal=refreshToken=\"changeme\" \\\n --from-literal=fileToken=\"changeme\"\n ```\n\n3. 应用清单文件：\n ```bash\n kubectl apply -f deployment.yaml\n kubectl apply -f service.yaml\n kubectl apply -f ingress.yaml\n ```\n\n### Kubernetes 组件说明\n\n| 组件类型 | 资源名称 | 说明 |\n|---------|---------|-----|\n| Deployment | twenty-server | 后端服务部署 |\n| Deployment | twenty-front | 前端服务部署 |\n| Service | twenty-server | 服务内部访问 |\n| Service | twenty-front | 前端负载均衡 |\n| Ingress | twenty-ingress | 外部流量入口 |\n| Secret | tokens | 认证令牌存储 |\n\n### Ingress 配置示例\n\n```yaml\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n name: twenty-ingress\n namespace: twentycrm\nspec:\n rules:\n - host: your-domain.com\n http:\n paths:\n - path: /\n pathType: Prefix\n backend:\n service:\n name: twenty-front\n port:\n number: 3000\n```\n\n配置 TLS 证书：\n\n```bash\nkubectl create secret tls -n twentycrm tls-secret \\\n --cert=path/to/cert.pem \\\n --key=path/to/key.pem\n\n# 使用 helm 设置 ingress TLS\nhelm upgrade twenty ./helm/twenty \\\n --set server.ingress.tls[0].hosts[0]=$DOMAIN \\\n --set server.ingress.tls[0].secretName=tls-secret\n```\n\n## Helm Chart 部署\n\nTwenty 提供 Helm Chart 用于 Kubernetes 部署。\n\n### 安装 Helm Chart\n\n```bash\n# 添加 Helm 仓库\nhelm repo add twenty https://charts.twenty.com\nhelm repo update\n\n# 安装 Twenty\nhelm install twenty twenty/twenty \\\n --namespace twentycrm \\\n --create-namespace \\\n --values values.yaml\n```\n\n### 配置参数\n\n| 参数路径 | 说明 | 默认值 |\n|---------|-----|-------|\n| `server.replicaCount` | 服务端副本数 | 1 |\n| `server.image.repository` | 镜像仓库 | twentyhq/twenty-server |\n| `server.image.tag` | 镜像标签 | latest |\n| `server.service.type` | 服务类型 | ClusterIP |\n| `server.ingress.enabled` | 启用 Ingress | false |\n| `server.ingress.host` | 域名 | - |\n| `database.enabled` | 启用内嵌数据库 | true |\n| `database.externalHost` | 外部数据库地址 | - |\n| `storage.type` | 存储类型 | minio |\n| `storage.s3.endpoint` | S3 兼容端点 | - |\n\n## 存储配置\n\n### MinIO 对象存储\n\nTwenty 使用 MinIO 作为默认对象存储解决方案。\n\n```yaml\nstorage:\n type: minio\n minio:\n endpoint: minio:9000\n bucket: twenty-storage\n accessKey: minioadmin\n secretKey: minioadmin\n```\n\n### 外部 S3 兼容存储\n\n如需使用 AWS S3 或其他 S3 兼容存储：\n\n```yaml\nstorage:\n type: s3\n s3:\n endpoint: https://s3.amazonaws.com\n region: us-east-1\n bucket: your-bucket\n accessKeyId: your-key\n secretAccessKey: your-secret\n```\n\n## 数据库配置\n\n### PostgreSQL 配置\n\n```yaml\ndatabase:\n enabled: true\n postgres:\n host: postgres\n port: 5432\n database: twenty\n username: twenty\n password: your-password\n```\n\n### 使用外部数据库\n\n```yaml\ndatabase:\n enabled: false\n externalHost: your-db-host.com\n externalPort: 5432\n externalDatabase: twenty\n externalUsername: twenty\n externalPassword: your-password\n```\n\n## 运维管理\n\n### 日志查看\n\n```bash\n# 查看所有服务日志\ndocker-compose logs -f\n\n# 查看特定服务日志\ndocker-compose logs -f server\n\n# Kubernetes 日志\nkubectl logs -n twentycrm deployment/twenty-server -f\n```\n\n### 服务重启\n\n```bash\n# Docker Compose\ndocker-compose restart\n\n# Kubernetes\nkubectl rollout restart deployment/twenty-server -n twentycrm\n```\n\n### 数据备份\n\n建议使用 PostgreSQL 的 `pg_dump` 工具进行数据库备份：\n\n```bash\n# 数据库备份\ndocker-compose exec postgres pg_dump -U twenty twenty > backup.sql\n\n# 恢复数据\ndocker-compose exec -T postgres psql -U twenty twenty < backup.sql\n```\n\n## 故障排查\n\n### 常见问题\n\n| 问题现象 | 可能原因 | 解决方案 |\n|---------|---------|---------|\n| 服务启动失败 | 端口冲突 | 检查 3000、5432、9000 端口占用 |\n| 数据库连接失败 | 凭据错误 | 检查环境变量中的数据库配置 |\n| 镜像拉取失败 | 网络问题 | 配置 Docker 镜像加速器 |\n| Ingress 无法访问 | DNS 未配置 | 确认域名解析正确 |\n\n### 健康检查\n\n```bash\n# Docker Compose 健康检查\ndocker-compose ps\n\n# Kubernetes 健康检查\nkubectl get pods -n twentycrm\nkubectl describe pod -n twentycrm \n```\n\n### 资源清理\n\n```bash\n# 停止并删除容器\ndocker-compose down -v\n\n# 删除所有镜像\ndocker-compose down --rmi all\n\n# Kubernetes 清理\nkubectl delete namespace twentycrm\n```\n\n## 安全建议\n\n1. **更换默认密码**：部署前务必修改所有默认密码和密钥\n2. **启用 HTTPS**：生产环境必须使用 TLS 证书\n3. **网络隔离**：使用 Kubernetes NetworkPolicy 限制服务间通信\n4. **定期更新**：关注 Twenty 最新版本，及时更新补丁\n5. **日志审计**：配置日志收集和分析系统\n\n## 相关文档\n\n- [本地开发环境搭建](https://docs.twenty.com/developers/contribute/capabilities/local-setup)\n- [应用开发指南](https://docs.twenty.com/developers/extend/apps/getting-started)\n- [Kubernetes 快速入门](../helm/twenty/QUICKSTART.md)\n- [Helm Chart 详细文档](../helm/twenty/README.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：twentyhq/twenty\n\n摘要：发现 31 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found。\n\n## 1. 安装坑 · 来源证据：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8f7dbe9bbbcb4664b1513a32d303b9eb | https://github.com/twentyhq/twenty/issues/20625 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Restart loop after first workspace creation on a fresh self-host install 2.4.0\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Restart loop after first workspace creation on a fresh self-host install 2.4.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_45aa2211a5b64bdc84ba3b47e72701ce | https://github.com/twentyhq/twenty/issues/20666 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 运行坑 · 来源证据：Cannot use the Add New Button from the list to create Tasks and Notes - Error: Should never occur, encountered unknown…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：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\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e572dc6d35d74c9ca8d15889a5cdcb12 | https://github.com/twentyhq/twenty/issues/15800 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 运行坑 · 来源证据：On record table, relation fields, we only display 3 items even when the cell is larger\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：On record table, relation fields, we only display 3 items even when the cell is larger\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2446ebd3b44b4378b8725f00f1d22023 | https://github.com/twentyhq/twenty/issues/12039 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 维护坑 · 来源证据：Notes not editable in People section\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Notes not editable in People section\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_594e914f1db84296ad7d08410941f4ff | https://github.com/twentyhq/twenty/issues/20288 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 维护坑 · 来源证据：Object Type translations are not applied to details panel\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Object Type translations are not applied to details panel\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d961ff61e7ff4bfbb2740d5b00781250 | https://github.com/twentyhq/twenty/issues/19790 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 安全/权限坑 · 来源证据：Pagination broken when sorting by multiple fields when first field has duplicates (both REST and Graphql APIs)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Pagination broken when sorting by multiple fields when first field has duplicates (both REST and Graphql APIs)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b5b75503f7ff4e4493c3503f86acf36b | https://github.com/twentyhq/twenty/issues/20520 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 失败模式：installation: Restart loop after first workspace creation on a fresh self-host install 2.4.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：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\n- 对用户的影响：Developers may fail before the first successful local run: Restart loop after first workspace creation on a fresh self-host install 2.4.0\n- 建议检查：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\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 9. 安装坑 · 失败模式：installation: v1.22.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.22.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.22.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.22.0. Context: Observed during installation or first-run setup.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_7102b6d7804c49862dcef507bd3213a5 | https://github.com/twentyhq/twenty/releases/tag/v1.22.4 | v1.22.0\n\n## 10. 安装坑 · 来源证据：Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1807294d92bc4e919fe1baf88520bb3c | https://github.com/twentyhq/twenty/issues/20671 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 11. 配置坑 · 失败模式：configuration: Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：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\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync\n- 建议检查：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.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 12. 配置坑 · 失败模式：configuration: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses\n- 建议检查：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\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 13. 配置坑 · 失败模式：configuration: v1.19.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: v1.19.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.19.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.19.0. Context: Observed during version upgrade or migration.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_15301e2ca30bc826383cea157ed32bcb | https://github.com/twentyhq/twenty/releases/tag/v1.19.0 | v1.19.0\n\n## 14. 配置坑 · 失败模式：configuration: v2.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: v2.0.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v2.0.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.0.0. Context: Observed when using docker\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_ab9b1aea9055fca76d3a881c8ee8f317 | https://github.com/twentyhq/twenty/releases/tag/v2.0.0 | v2.0.0\n\n## 15. 配置坑 · 失败模式：configuration: v2.3.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: v2.3.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v2.3.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.3.0. Context: Observed when using docker\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_05b61500a200d1852774253b2b09cb5f | https://github.com/twentyhq/twenty/releases/tag/v2.3.0 | v2.3.0\n\n## 16. 配置坑 · 失败模式：configuration: v2.4.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: v2.4.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v2.4.0\n- 建议检查：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.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_c37fffb0f1bdf017e6070e311b099597 | https://github.com/twentyhq/twenty/releases/tag/v2.4.0 | v2.4.0\n\n## 17. 配置坑 · 来源证据：TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4abd78a034024d29b94e860fbcb298e6 | https://github.com/twentyhq/twenty/issues/20136 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 18. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:572984571 | https://github.com/twentyhq/twenty | README/documentation is current enough for a first validation pass.\n\n## 19. 运行坑 · 来源证据：Bug(UI): Currency icon not aligned properly\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Bug(UI): Currency icon not aligned properly\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c2c473e13c324a60a1b0ba450f77fb32 | https://github.com/twentyhq/twenty/issues/20640 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · 失败模式：migration: v1.20.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: v1.20.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.20.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.20.0. Context: Observed during version upgrade or migration.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_b9ae97dbbd9c277df82d69cda517b768 | https://github.com/twentyhq/twenty/releases/tag/v1.20.0 | v1.20.0\n\n## 21. 维护坑 · 失败模式：migration: v1.21.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: v1.21.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.21.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.21.0. Context: Observed during version upgrade or migration.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_ea380ef68973d4bb1f069cd337fd42af | https://github.com/twentyhq/twenty/releases/tag/v1.21.0 | v1.21.0\n\n## 22. 维护坑 · 失败模式：migration: v1.23.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: v1.23.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.23.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.23.0. Context: Observed during version upgrade or migration.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_d757a9aab11c1a39bfa726eebcb7ab5e | https://github.com/twentyhq/twenty/releases/tag/v1.23.0 | v1.23.0\n\n## 23. 维护坑 · 失败模式：migration: v2.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: v2.1.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v2.1.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.1.0. Context: Observed during version upgrade or migration.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_0bb1a26151a8ea54475ab5fc8c9566c7 | https://github.com/twentyhq/twenty/releases/tag/v2.1.0 | v2.1.0\n\n## 24. 维护坑 · 失败模式：migration: v2.2.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: v2.2.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v2.2.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.2.0. Context: Observed during version upgrade or migration.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_9cfa053b1c1093a4e4bdfc861bc786ab | https://github.com/twentyhq/twenty/releases/tag/v2.2.0 | v2.2.0\n\n## 25. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:572984571 | https://github.com/twentyhq/twenty | last_activity_observed missing\n\n## 26. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:572984571 | https://github.com/twentyhq/twenty | no_demo; severity=medium\n\n## 27. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:572984571 | https://github.com/twentyhq/twenty | no_demo; severity=medium\n\n## 28. 能力坑 · 失败模式：capability: Bug(UI): BlockNote Editor slash command shows nothing when no matches are found\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: Bug(UI): BlockNote Editor slash command shows nothing when no matches are found\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Bug(UI): BlockNote Editor slash command shows nothing when no matches are found\n- 建议检查：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.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 29. 能力坑 · 失败模式：capability: Bug(UI): Currency icon not aligned properly\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: Bug(UI): Currency icon not aligned properly\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Bug(UI): Currency icon not aligned properly\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Bug(UI): Currency icon not aligned properly. Context: Observed when using docker\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_5b942675e057e849cb68cf3923b56dce | https://github.com/twentyhq/twenty/issues/20640 | Bug(UI): Currency icon not aligned properly\n\n## 30. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:572984571 | https://github.com/twentyhq/twenty | issue_or_pr_quality=unknown\n\n## 31. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:572984571 | https://github.com/twentyhq/twenty | release_recency=unknown\n\n\n",
"markdown_key": "twenty",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:572984571",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/twentyhq/twenty"
},
{
"evidence_id": "art_8c5a5febec374073b9646fc99e1f20dc",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/twentyhq/twenty#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "twenty 说明书",
"toc": [
"https://github.com/twentyhq/twenty 项目说明书",
"目录",
"项目介绍",
"项目概述",
"核心特性",
"项目架构",
"包结构详解",
"页面组件架构",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "05f31c183799bf9a06f8cd35d4961396d2535290",
"repo_inspection_error": null,
"repo_inspection_files": [
"package.json",
"README.md",
"packages/twenty-shared/vite.config.individual.ts",
"packages/twenty-shared/vite.config.ts",
"packages/twenty-shared/.oxlintrc.json",
"packages/twenty-shared/package.json",
"packages/twenty-shared/project.json",
"packages/twenty-shared/tsconfig.json",
"packages/twenty-shared/tsconfig.lib.json",
"packages/twenty-e2e-testing/package.json",
"packages/twenty-e2e-testing/project.json",
"packages/twenty-e2e-testing/README.md",
"packages/twenty-e2e-testing/playwright.config.ts",
"packages/twenty-utils/translation-qa-report.ts",
"packages/twenty-utils/package.json",
"packages/twenty-utils/fix-crowdin-translations.ts",
"packages/twenty-utils/fix-docs-tags.ts",
"packages/twenty-utils/congratulate-dangerfile.ts",
"packages/twenty-utils/fix-qa-issues.ts",
"packages/twenty-utils/dangerfile.ts",
"packages/twenty-claude-skills/package.json",
"packages/twenty-claude-skills/README.md",
"packages/twenty-cli/package.json",
"packages/twenty-cli/README.md",
"packages/twenty-cli/deprecate.js",
"packages/twenty-docker/docker-compose.dev.yml",
"packages/twenty-docker/docker-compose.yml",
"packages/twenty-website-new/lingui.config.ts",
"packages/twenty-website-new/tsconfig.spec.json",
"packages/twenty-website-new/.oxlintrc.json",
"packages/twenty-website-new/package.json",
"packages/twenty-website-new/project.json",
"packages/twenty-website-new/README.md",
"packages/twenty-website-new/tsconfig.json",
"packages/twenty-website-new/next.config.ts",
"packages/twenty-client-sdk/vitest.config.ts",
"packages/twenty-client-sdk/vite.config.ts",
"packages/twenty-client-sdk/.oxlintrc.json",
"packages/twenty-client-sdk/package.json",
"packages/twenty-client-sdk/project.json"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# twenty - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 twenty 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.cursor/skills/syncable-entity-builder-and-validation/SKILL.md`, `.cursor/skills/syncable-entity-cache-and-transform/SKILL.md`, `.cursor/skills/syncable-entity-integration/SKILL.md`, `.cursor/skills/syncable-entity-runner-and-actions/SKILL.md` 等 Claim：`clm_0003` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.cursor/skills/syncable-entity-builder-and-validation/SKILL.md`, `.cursor/skills/syncable-entity-cache-and-transform/SKILL.md`, `.cursor/skills/syncable-entity-integration/SKILL.md`, `.cursor/skills/syncable-entity-runner-and-actions/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`CLAUDE.md`, `README.md`, `packages/create-twenty-app/README.md`, `packages/twenty-apps/examples/postcard/README.md` 等 Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `npx create-twenty-app my-app` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `npx twenty deploy` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `npx create-twenty-app@latest my-twenty-app` 证据：`packages/create-twenty-app/README.md` Claim：`clm_0006` supported 0.86, `clm_0007` supported 0.86\n- `npx create-twenty-app@latest my-twenty-app --example hello-world` 证据：`packages/create-twenty-app/README.md` Claim：`clm_0007` supported 0.86\n- `npx create-twenty-app@latest my-app --example postcard` 证据：`packages/twenty-apps/examples/postcard/README.md` Claim：`clm_0008` supported 0.86\n- `npm install -g resend-cli` 证据：`packages/twenty-apps/internal/twenty-for-twenty/README.md` Claim：`clm_0009` supported 0.86\n- `npm install -g twenty-sdk` 证据：`packages/twenty-cli/README.md` Claim：`clm_0010` supported 0.86\n- `git clone https://github.com/twentyhq/twenty.git` 证据：`packages/twenty-docker/k8s/README.md` Claim：`clm_0011` supported 0.86\n- `npx nx run twenty-docs:dev` 证据：`packages/twenty-docs/README.md` Claim：`clm_0012` supported 0.86\n- `npx nx run twenty-docs:validate` 证据：`packages/twenty-docs/README.md` Claim：`clm_0013` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.cursor/skills/syncable-entity-builder-and-validation/SKILL.md`, `.cursor/skills/syncable-entity-cache-and-transform/SKILL.md`, `.cursor/skills/syncable-entity-integration/SKILL.md`, `.cursor/skills/syncable-entity-runner-and-actions/SKILL.md` 等 Claim：`clm_0003` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.cursor/skills/syncable-entity-builder-and-validation/SKILL.md`, `.cursor/skills/syncable-entity-cache-and-transform/SKILL.md`, `.cursor/skills/syncable-entity-integration/SKILL.md`, `.cursor/skills/syncable-entity-runner-and-actions/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`CLAUDE.md`, `README.md`, `packages/create-twenty-app/README.md`, `packages/twenty-apps/examples/postcard/README.md` 等 Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.cursor/skills/syncable-entity-builder-and-validation/SKILL.md`, `.cursor/skills/syncable-entity-cache-and-transform/SKILL.md`, `.cursor/skills/syncable-entity-integration/SKILL.md`, `.cursor/skills/syncable-entity-runner-and-actions/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`CLAUDE.md`, `README.md`, `packages/create-twenty-app/README.md`, `packages/twenty-apps/examples/postcard/README.md` 等\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.cursor/skills/syncable-entity-builder-and-validation/SKILL.md`, `.cursor/skills/syncable-entity-cache-and-transform/SKILL.md`, `.cursor/skills/syncable-entity-integration/SKILL.md`, `.cursor/skills/syncable-entity-runner-and-actions/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`CLAUDE.md`, `README.md`, `packages/create-twenty-app/README.md`, `packages/twenty-apps/examples/postcard/README.md` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0028` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`CLAUDE.md`, `README.md`, `packages/create-twenty-app/README.md`, `packages/twenty-apps/examples/postcard/README.md` 等 Claim：`clm_0029` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.cursor/skills/syncable-entity-builder-and-validation/SKILL.md`, `.cursor/skills/syncable-entity-cache-and-transform/SKILL.md`, `.cursor/skills/syncable-entity-integration/SKILL.md`, `.cursor/skills/syncable-entity-runner-and-actions/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`CLAUDE.md`, `README.md`, `packages/create-twenty-app/README.md`, `packages/twenty-apps/examples/postcard/README.md` 等 Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：20914\n- 重要文件覆盖：40/20914\n- 证据索引条目：80\n- 角色 / Skill 条目：7\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 twenty 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 twenty 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 twenty 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 7 个角色 / Skill / 项目文档条目。\n\n- **syncable-entity-builder-and-validation**（skill）：Create validation logic and migration action builders for syncable entities in Twenty. Use when implementing business rule validation, uniqueness checks, foreign key validation, or building workspace migration actions for syncable entities. Validators never throw and never mutate. 激活提示：当用户任务与“syncable-entity-builder-and-validation”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.cursor/skills/syncable-entity-builder-and-validation/SKILL.md`\n- **syncable-entity-cache-and-transform**（skill）：Create cache services and transformation utilities for syncable entities in Twenty. Use when implementing entity-to-flat conversions, input DTO transpilation to universal flat entities, or cache recomputation for syncable entities. 激活提示：当用户任务与“syncable-entity-cache-and-transform”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.cursor/skills/syncable-entity-cache-and-transform/SKILL.md`\n- **syncable-entity-integration**（skill）：Wire syncable entity services into NestJS modules, create service layer and resolvers for Twenty entities. Use when registering builders, validators, and action handlers in modules, creating business services, or exposing entities via GraphQL API with proper exception handling. 激活提示：当用户任务与“syncable-entity-integration”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.cursor/skills/syncable-entity-integration/SKILL.md`\n- **syncable-entity-runner-and-actions**（skill）：Implement action handlers for executing workspace migrations in Twenty. Use when creating database operations for syncable entities, implementing universal-to-flat entity transpilation, or handling create/update/delete actions in the runner layer. 激活提示：当用户任务与“syncable-entity-runner-and-actions”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.cursor/skills/syncable-entity-runner-and-actions/SKILL.md`\n- **syncable-entity-testing**（skill）：Create comprehensive integration tests for syncable entities in Twenty. Use when writing integration tests for metadata entities, covering validator exceptions, input transpilation errors, and CRUD operations. Tests are MANDATORY for all syncable entities. 激活提示：当用户任务与“syncable-entity-testing”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.cursor/skills/syncable-entity-testing/SKILL.md`\n- **syncable-entity-types-and-constants**（skill）：Define types, entities, and central constant registrations for syncable entities in Twenty's workspace migration system. Use when creating new syncable entities, defining TypeORM entities, flat entity types, or registering in central constants ALL ENTITY PROPERTIES CONFIGURATION BY METADATA NAME, ALL ONE TO MANY METADATA RELATIONS, ALL MANY TO ONE METADATA FOREIGN KEY, ALL MANY TO ONE METADATA RELATIONS . 激活提示：当用户任务与“syncable-entity-types-and-constants”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.cursor/skills/syncable-entity-types-and-constants/SKILL.md`\n- **twenty-record-presentation**（skill）：Retrieve and present Twenty CRM records as readable summaries or tables, using the connected Twenty MCP server to discover fields, fetch relevant data, format dates and values, build record links, and avoid raw API output. 激活提示：当用户任务与“twenty-record-presentation”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/twenty-claude-skills/skills/twenty-record-presentation/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **CLAUDE.md**（documentation）：This file provides guidance to Claude Code claude.ai/code when working with code in this repository. 证据：`CLAUDE.md`\n- **Why Twenty**（documentation）：Website · Documentation · Roadmap · Discord · Figma 证据：`README.md`\n- **Readme**（documentation）：Based on write-good https://github.com/btford/write-good . 证据：`.github/vale-styles/write-good/README.md`\n- **Quick start**（documentation）：The official scaffolding CLI for building apps on top of Twenty CRM https://twenty.com . Sets up a ready-to-run project with twenty-sdk https://www.npmjs.com/package/twenty-sdk . 证据：`packages/create-twenty-app/README.md`\n- **Base documentation**（documentation）：- Getting started: - https://docs.twenty.com/developers/extend/apps/getting-started/quick-start.md - https://docs.twenty.com/developers/extend/apps/getting-started/concepts.md - https://docs.twenty.com/developers/extend/apps/getting-started/project-structure.md - https://docs.twenty.com/developers/extend/apps/getting-started/local-server.md - https://docs.twenty.com/developers/extend/apps/getting-started/scaffolding.md - https://docs.twenty.com/developers/extend/apps/getting-started/troubleshooting.md - Config: - https://docs.twenty.com/developers/extend/apps/config/overview.md - https://docs.twenty.com/developers/extend/apps/config/application.md - https://docs.twenty.com/developers/extend… 证据：`packages/create-twenty-app/src/constants/template/AGENTS.md`\n- **Getting Started**（documentation）：This is a Twenty https://twenty.com application bootstrapped with create-twenty-app https://www.npmjs.com/package/create-twenty-app . 证据：`packages/create-twenty-app/src/constants/template/README.md`\n- **GitHub Connector**（documentation）：Sync pull requests, issues, contributors and project items from GitHub into Twenty, and react to GitHub webhook events in real time. 证据：`packages/twenty-apps/community/github-connector/README.md`\n- **Getting Started**（documentation）：This is a Twenty https://twenty.com application project bootstrapped with create-twenty-app https://www.npmjs.com/package/create-twenty-app . 证据：`packages/twenty-apps/examples/hello-world/README.md`\n- **Base documentation**（documentation）：- Documentation: https://docs.twenty.com/developers/extend/apps/getting-started - Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/fixtures/rich-app 证据：`packages/twenty-apps/examples/postcard/CLAUDE.md`\n- **Postcard App — Twenty App Example**（documentation）：A rich example app showcasing all Twenty app entity types. Use this as a reference when building your own apps. 证据：`packages/twenty-apps/examples/postcard/README.md`\n- **Getting Started**（documentation）：This is a Twenty https://twenty.com application project bootstrapped with create-twenty-app https://www.npmjs.com/package/create-twenty-app . 证据：`packages/twenty-apps/internal/call-recording/README.md`\n- **twenty-exa**（documentation）：Exposes Exa https://exa.ai structured web search to Twenty AI agents chat + workflow agents + MCP as the app exa web search tool. 证据：`packages/twenty-apps/internal/exa/README.md`\n- **Base documentation**（documentation）：- Documentation: https://docs.twenty.com/developers/extend/apps/getting-started - Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples/postcard 证据：`packages/twenty-apps/internal/self-hosting/CLAUDE.md`\n- **Getting Started**（documentation）：This is a Twenty https://twenty.com application bootstrapped with create-twenty-app https://www.npmjs.com/package/create-twenty-app . 证据：`packages/twenty-apps/internal/self-hosting/README.md`\n- **Discord for Twenty**（documentation）：Connect Discord to your Twenty workflows. Post messages, edit them, react, delete, and browse channels — all from the workflow builder or the AI chat. 证据：`packages/twenty-apps/internal/twenty-discord/README.md`\n- **Base documentation**（documentation）：- Documentation: https://docs.twenty.com/developers/extend/apps/getting-started - Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples/postcard 证据：`packages/twenty-apps/internal/twenty-for-twenty/CLAUDE.md`\n- **Overview**（documentation）：This is a Twenty https://twenty.com application bootstrapped with create-twenty-app https://www.npmjs.com/package/create-twenty-app . 证据：`packages/twenty-apps/internal/twenty-for-twenty/README.md`\n- **Base documentation**（documentation）：- Documentation: https://docs.twenty.com/developers/extend/apps/getting-started - Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples/postcard 证据：`packages/twenty-apps/internal/twenty-linear/CLAUDE.md`\n- **Linear for Twenty**（documentation）：Connect your Linear account to Twenty to create issues and look up teams straight from your workflows or the AI chat. 证据：`packages/twenty-apps/internal/twenty-linear/README.md`\n- **twenty-claude-skills**（documentation）：Claude skills for working with Twenty. 证据：`packages/twenty-claude-skills/README.md`\n- **Deprecated: twenty-cli**（documentation）：This package is deprecated. Please install and use twenty-sdk https://www.npmjs.com/package/twenty-sdk instead: 证据：`packages/twenty-cli/README.md`\n- **Twenty Desktop**（documentation）：WARNING: This application is a Proof of Concept POC and must NOT be used in production. It is intended for demonstration and experimentation purposes only. Security, stability, and performance have not been validated for production use. 证据：`packages/twenty-companion/README.md`\n- **Twenty Helm Chart**（documentation）：Deploy Twenty CRM on Kubernetes with server, worker, PostgreSQL, and Redis components. 证据：`packages/twenty-docker/helm/twenty/README.md`\n- **Kubernetes for Twenty CRM Helm**（documentation）：Kubernetes for Twenty CRM Helm DISCLAIMER: The k8s and podman deployments are not maintained by the core team. These files are provided and maintained by the community. Twenty core team maintains support for docker deployment. 证据：`packages/twenty-docker/k8s/README.md`\n- **TwentyCRM Terraform Docs**（documentation）：This file was generated by terraform-docs https://terraform-docs.io/ , for more information on how to install, configure, and use visit their website. 证据：`packages/twenty-docker/k8s/terraform/README.md`\n- **How to deploy twenty on podman**（documentation）：DISCLAIMER: The k8s and podman deployments are not maintained by the core team. These files are provided and maintained by the community. Twenty core team maintains support for docker deployment. 证据：`packages/twenty-docker/podman/README.md`\n- **Twenty Documentation**（documentation）：Official documentation for Twenty CRM, powered by Mintlify https://mintlify.com . 证据：`packages/twenty-docs/README.md`\n- **Twenty end-to-end E2E Testing**（documentation）：Example location of the test must be specified from the root of twenty-e2e-testing package : 证据：`packages/twenty-e2e-testing/README.md`\n- **Twenty Emails**（documentation）：This package contains the email templates used by Twenty. 证据：`packages/twenty-emails/README.md`\n- **Readme**（documentation）：Run yarn dev while server running on port 3000 证据：`packages/twenty-front/README.md`\n- **Quick start**（documentation）：A CLI and SDK to develop, build, and publish applications that extend Twenty CRM https://twenty.com . 证据：`packages/twenty-sdk/README.md`\n- **How to patch a dependency**（documentation）：yarn patch-commit -s does not work in our monorepo. Use the workflow below instead. 证据：`packages/twenty-server/patches/README.md`\n- **Local SSL Certificate Generation Script**（documentation）：Local SSL Certificate Generation Script 证据：`packages/twenty-server/scripts/ssl-generation/README.md`\n- **Analytics Module**（documentation）：This module provides analytics tracking functionality for the Twenty application. 证据：`packages/twenty-server/src/engine/core-modules/audit/README.md`\n- **Twenty UI**（documentation）：This library was generated with Nx https://nx.dev . 证据：`packages/twenty-ui/README.md`\n- **twenty-website-new**（documentation）：twenty-website-new 证据：`packages/twenty-website-new/README.md`\n- **Package**（package_manifest）：{ \"private\": true, \"devDependencies\": { \"@nx/jest\": \"22.5.4\", \"@nx/js\": \"22.5.4\", \"@nx/react\": \"22.5.4\", \"@nx/storybook\": \"22.5.4\", \"@nx/vite\": \"22.5.4\", \"@nx/web\": \"22.5.4\", \"@types/react\": \"^18.2.39\", \"@types/react-dom\": \"^18.2.15\", \"@yarnpkg/types\": \"^4.0.0\", \"concurrently\": \"^8.2.2\", \"http-server\": \"^14.1.1\", \"nx\": \"22.5.4\", \"tsx\": \"^4.17.0\", \"verdaccio\": \"^6.3.1\" }, \"engines\": { \"node\": \"^24.5.0\", \"npm\": \"please-use-yarn\", \"yarn\": \" =4.0.2\" }, \"license\": \"AGPL-3.0\", \"name\": \"twenty\", \"packageManager\": \"yarn@4.13.0\", \"resolutions\": { \"graphql\": \"16.8.1\", \"type-fest\": \"4.10.1\", \"typescript\": \"5.9.2\", \"nodemailer\": \"8.0.4\", \"graphql-redis-subscriptions/ioredis\": \"^5.6.0\", \"@lingui/core\":… 证据：`package.json`\n- **Contributing to Twenty**（documentation）：Thanks for considering contributing to Twenty! 证据：`.github/CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"create-twenty-app\", \"version\": \"2.5.0\", \"description\": \"Command-line interface to create Twenty application\", \"main\": \"dist/cli.cjs\", \"bin\": \"dist/cli.cjs\", \"files\": \"dist\", \"README.md\", \"package.json\" , \"scripts\": { \"build\": \"npx rimraf dist && npx vite build\" }, \"keywords\": \"twenty\", \"cli\", \"crm\", \"application\", \"development\" , \"exports\": { \".\": { \"types\": \"./dist/cli.d.ts\", \"import\": \"./dist/cli.mjs\", \"require\": \"./dist/cli.cjs\" } }, \"license\": \"AGPL-3.0\", \"dependencies\": { \"@genql/cli\": \"^3.0.3\", \"chalk\": \"^5.3.0\", \"commander\": \"^12.0.0\", \"fs-extra\": \"^11.2.0\", \"lodash.camelcase\": \"^4.3.0\", \"lodash.kebabcase\": \"^4.1.1\", \"lodash.startcase\": \"^4.4.0\", \"twenty-sdk\": \"workspace:… 证据：`packages/create-twenty-app/package.json`\n- **Package**（package_manifest）：{ \"name\": \"TO-BE-GENERATED\", \"version\": \"0.1.0\", \"license\": \"MIT\", \"engines\": { \"node\": \"^24.5.0\", \"npm\": \"please-use-yarn\", \"yarn\": \" =4.0.2\" }, \"keywords\": , \"packageManager\": \"yarn@4.9.2\", \"scripts\": { \"twenty\": \"twenty\", \"lint\": \"oxlint -c .oxlintrc.json .\", \"lint:fix\": \"oxlint --fix -c .oxlintrc.json .\", \"test\": \"vitest run\", \"test:watch\": \"vitest\" }, \"dependencies\": { \"twenty-client-sdk\": \"TO-BE-GENERATED\", \"twenty-sdk\": \"TO-BE-GENERATED\" }, \"devDependencies\": { \"@types/node\": \"^24.7.2\", \"@types/react\": \"^19.0.0\", \"oxlint\": \"^0.16.0\", \"react\": \"^19.0.0\", \"react-dom\": \"^19.0.0\", \"typescript\": \"^5.9.3\", \"vite-tsconfig-paths\": \"^4.2.1\", \"vitest\": \"^3.1.1\" } } 证据：`packages/create-twenty-app/src/constants/template/package.json`\n- **Package**（package_manifest）：{ \"name\": \"github-connector\", \"version\": \"0.2.0\", \"license\": \"MIT\", \"engines\": { \"node\": \"^24.5.0\", \"npm\": \"please-use-yarn\", \"yarn\": \" =4.0.2\" }, \"keywords\": \"twenty-app\" , \"packageManager\": \"yarn@4.9.2\", \"scripts\": { \"twenty\": \"twenty\", \"lint\": \"oxlint -c .oxlintrc.json .\", \"lint:fix\": \"oxlint --fix -c .oxlintrc.json .\", \"test\": \"vitest run\", \"test:watch\": \"vitest\" }, \"dependencies\": { \"twenty-client-sdk\": \"2.0.0\", \"twenty-sdk\": \"2.0.0\" }, \"devDependencies\": { \"@types/node\": \"^24.7.2\", \"@types/react\": \"^19.0.0\", \"oxlint\": \"^0.16.0\", \"react\": \"^19.0.0\", \"react-dom\": \"^19.0.0\", \"typescript\": \"^5.9.3\", \"vite-tsconfig-paths\": \"^4.2.1\", \"vitest\": \"^3.1.1\" } } 证据：`packages/twenty-apps/community/github-connector/package.json`\n- **Package**（package_manifest）：{ \"name\": \"hello-world\", \"version\": \"0.1.0\", \"license\": \"MIT\", \"engines\": { \"node\": \"^24.5.0\", \"npm\": \"please-use-yarn\", \"yarn\": \" =4.0.2\" }, \"packageManager\": \"yarn@4.9.2\", \"scripts\": { \"twenty\": \"twenty\", \"lint\": \"oxlint -c .oxlintrc.json .\", \"lint:fix\": \"oxlint --fix -c .oxlintrc.json .\", \"test\": \"vitest run\", \"test:watch\": \"vitest\" }, \"dependencies\": { \"twenty-client-sdk\": \"0.9.0\", \"twenty-sdk\": \"0.9.0\" }, \"devDependencies\": { \"@types/node\": \"^24.7.2\", \"@types/react\": \"^18.2.0\", \"oxlint\": \"^0.16.0\", \"react\": \"^18.2.0\", \"typescript\": \"^5.9.3\", \"vite-tsconfig-paths\": \"^4.2.1\", \"vitest\": \"^3.1.1\" } } 证据：`packages/twenty-apps/examples/hello-world/package.json`\n- **Package**（package_manifest）：{ \"name\": \"postcard\", \"version\": \"0.1.0\", \"license\": \"MIT\", \"engines\": { \"node\": \"^24.5.0\", \"npm\": \"please-use-yarn\", \"yarn\": \" =4.0.2\" }, \"keywords\": \"twenty-app\" , \"packageManager\": \"yarn@4.9.2\", \"scripts\": { \"twenty\": \"twenty\", \"lint\": \"oxlint -c .oxlintrc.json .\", \"lint:fix\": \"oxlint --fix -c .oxlintrc.json .\", \"test\": \"vitest run\", \"test:watch\": \"vitest\" }, \"dependencies\": { \"twenty-client-sdk\": \"2.2.0\", \"twenty-sdk\": \"2.2.0\" }, \"devDependencies\": { \"@types/node\": \"^24.7.2\", \"@types/react\": \"^19.0.0\", \"oxlint\": \"^0.16.0\", \"react\": \"^19.0.0\", \"react-dom\": \"^19.0.0\", \"typescript\": \"^5.9.3\", \"vite-tsconfig-paths\": \"^4.2.1\", \"vitest\": \"^3.1.1\" } } 证据：`packages/twenty-apps/examples/postcard/package.json`\n- **Package**（package_manifest）：{ \"name\": \"function-execute-app\", \"version\": \"0.1.0\", \"license\": \"MIT\", \"engines\": { \"node\": \"^24.5.0\", \"npm\": \"please-use-yarn\", \"yarn\": \" =4.0.2\" }, \"packageManager\": \"yarn@4.9.2\", \"scripts\": { \"dev\": \"twenty dev\", \"exec\": \"twenty exec\", \"uninstall\": \"twenty uninstall\", \"lint\": \"oxlint -c .oxlintrc.json .\", \"lint:fix\": \"oxlint --fix -c .oxlintrc.json .\" }, \"dependencies\": { \"twenty-sdk\": \"latest\", \"twenty-client-sdk\": \"latest\" }, \"devDependencies\": { \"typescript\": \"^5.9.3\", \"@types/node\": \"^24.7.2\", \"@types/react\": \"^19.0.2\", \"react\": \"^19.0.2\", \"oxlint\": \"^0.16.0\" } } 证据：`packages/twenty-apps/fixtures/function-execute-app/package.json`\n- **Package**（package_manifest）：{ \"name\": \"invalid-app\", \"version\": \"0.1.0\", \"license\": \"MIT\", \"engines\": { \"node\": \"^24.5.0\", \"npm\": \"please-use-yarn\", \"yarn\": \" =4.0.2\" }, \"packageManager\": \"yarn@4.9.2\", \"scripts\": { \"twenty\": \"twenty\", \"lint\": \"oxlint -c .oxlintrc.json .\", \"lint:fix\": \"oxlint --fix -c .oxlintrc.json .\" }, \"dependencies\": { \"twenty-sdk\": \"latest\", \"twenty-client-sdk\": \"latest\" }, \"devDependencies\": { \"typescript\": \"^5.9.3\", \"@types/node\": \"^24.7.2\", \"@types/react\": \"^19.0.2\", \"react\": \"^19.0.2\", \"oxlint\": \"^0.16.0\" } } 证据：`packages/twenty-apps/fixtures/invalid-app/package.json`\n- **Package**（package_manifest）：{ \"name\": \"minimal-app\", \"version\": \"0.1.0\", \"license\": \"MIT\", \"engines\": { \"node\": \"^24.5.0\", \"npm\": \"please-use-yarn\", \"yarn\": \" =4.0.2\" }, \"packageManager\": \"yarn@4.9.2\", \"scripts\": { \"twenty\": \"twenty\", \"lint\": \"oxlint -c .oxlintrc.json .\", \"lint:fix\": \"oxlint --fix -c .oxlintrc.json .\" }, \"dependencies\": { \"twenty-sdk\": \"latest\", \"twenty-client-sdk\": \"latest\" }, \"devDependencies\": { \"typescript\": \"^5.9.3\", \"@types/node\": \"^24.7.2\", \"@types/react\": \"^19.0.2\", \"react\": \"^19.0.2\", \"oxlint\": \"^0.16.0\" } } 证据：`packages/twenty-apps/fixtures/minimal-app/package.json`\n- **Package**（package_manifest）：{ \"name\": \"rich-app\", \"version\": \"0.1.0\", \"license\": \"MIT\", \"engines\": { \"node\": \"^24.5.0\", \"npm\": \"please-use-yarn\", \"yarn\": \" =4.0.2\" }, \"packageManager\": \"yarn@4.9.2\", \"scripts\": { \"twenty\": \"twenty\", \"lint\": \"oxlint -c .oxlintrc.json .\", \"lint:fix\": \"oxlint --fix -c .oxlintrc.json .\" }, \"dependencies\": { \"twenty-sdk\": \"latest\", \"twenty-client-sdk\": \"latest\" }, \"devDependencies\": { \"typescript\": \"^5.9.3\", \"@types/node\": \"^24.7.2\", \"@types/react\": \"^19.0.2\", \"react\": \"^19.0.2\", \"oxlint\": \"^0.16.0\" } } 证据：`packages/twenty-apps/fixtures/rich-app/package.json`\n- **Package**（package_manifest）：{ \"name\": \"call-recording\", \"version\": \"0.1.0\", \"license\": \"MIT\", \"engines\": { \"node\": \"^24.5.0\", \"npm\": \"please-use-yarn\", \"yarn\": \" =4.0.2\" }, \"packageManager\": \"yarn@4.9.2\", \"scripts\": { \"twenty\": \"twenty\", \"lint\": \"oxlint -c .oxlintrc.json .\", \"lint:fix\": \"oxlint --fix -c .oxlintrc.json .\" }, \"dependencies\": { \"@emotion/react\": \"^11.11.1\", \"@emotion/styled\": \"^11.11.0\", \"react-loading-skeleton\": \"^3.5.0\", \"react-markdown\": \"^10.1.0\", \"twenty-sdk\": \"0.6.3-alpha\" }, \"devDependencies\": { \"@types/node\": \"^24.7.2\", \"@types/react\": \"^18.2.0\", \"oxlint\": \"^0.16.0\", \"react\": \"^18.2.0\", \"typescript\": \"^5.9.3\" } } 证据：`packages/twenty-apps/internal/call-recording/package.json`\n- **Package**（package_manifest）：{ \"name\": \"twenty-exa\", \"version\": \"0.1.0\", \"description\": \"Structured web search powered by Exa, exposed to Twenty AI agents as a tool.\", \"license\": \"MIT\", \"engines\": { \"node\": \"^24.5.0\", \"npm\": \"please-use-yarn\", \"yarn\": \" =4.0.2\" }, \"keywords\": \"twenty-app\" , \"packageManager\": \"yarn@4.9.2\", \"scripts\": { \"twenty\": \"twenty\", \"lint\": \"oxlint -c .oxlintrc.json .\", \"lint:fix\": \"oxlint --fix -c .oxlintrc.json .\", \"test\": \"vitest run\", \"test:watch\": \"vitest\" }, \"dependencies\": { \"exa-js\": \"^2.12.1\", \"twenty-client-sdk\": \"2.0.0\", \"twenty-sdk\": \"2.1.0\" }, \"devDependencies\": { \"@types/node\": \"^24.7.2\", \"oxlint\": \"^0.16.0\", \"typescript\": \"^5.9.3\", \"vitest\": \"^3.1.1\" } } 证据：`packages/twenty-apps/internal/exa/package.json`\n- **Package**（package_manifest）：{ \"name\": \"self-hosting\", \"version\": \"1.0.0\", \"license\": \"MIT\", \"engines\": { \"node\": \"^24.5.0\", \"npm\": \"please-use-yarn\", \"yarn\": \" =4.0.2\" }, \"packageManager\": \"yarn@4.9.2\", \"scripts\": { \"twenty\": \"twenty\", \"lint\": \"oxlint -c .oxlintrc.json .\", \"lint:fix\": \"oxlint --fix -c .oxlintrc.json .\", \"test\": \"vitest run\", \"test:watch\": \"vitest\" }, \"dependencies\": { \"twenty-client-sdk\": \"1.22.0-canary.6\", \"twenty-sdk\": \"1.22.0-canary.6\" }, \"devDependencies\": { \"@types/node\": \"^24.7.2\", \"@types/react\": \"^19.0.0\", \"oxlint\": \"^0.16.0\", \"react\": \"^19.0.0\", \"react-dom\": \"^19.0.0\", \"typescript\": \"^5.9.3\", \"vite-tsconfig-paths\": \"^4.2.1\", \"vitest\": \"^3.1.1\" } } 证据：`packages/twenty-apps/internal/self-hosting/package.json`\n- **Package**（package_manifest）：{ \"name\": \"twenty-discord\", \"version\": \"0.1.0\", \"description\": \"Discord workflow connector for Twenty\", \"license\": \"MIT\", \"engines\": { \"node\": \"^24.5.0\", \"npm\": \"please-use-yarn\", \"yarn\": \" =4.0.2\" }, \"keywords\": \"twenty-app\" , \"packageManager\": \"yarn@4.9.2\", \"scripts\": { \"twenty\": \"twenty\", \"lint\": \"oxlint -c .oxlintrc.json .\", \"lint:fix\": \"oxlint --fix -c .oxlintrc.json .\", \"test\": \"vitest run\", \"test:watch\": \"vitest\" }, \"dependencies\": { \"twenty-sdk\": \"2.4.0\" }, \"devDependencies\": { \"@types/node\": \"^24.7.2\", \"oxlint\": \"^0.16.0\", \"typescript\": \"^5.9.3\", \"vitest\": \"^3.1.1\" } } 证据：`packages/twenty-apps/internal/twenty-discord/package.json`\n- **Package**（package_manifest）：{ \"name\": \"twenty-for-twenty\", \"version\": \"0.1.0\", \"license\": \"MIT\", \"engines\": { \"node\": \"^24.5.0\", \"npm\": \"please-use-yarn\", \"yarn\": \" =4.0.2\" }, \"keywords\": , \"packageManager\": \"yarn@4.9.2\", \"scripts\": { \"twenty\": \"twenty\", \"lint\": \"oxlint -c .oxlintrc.json .\", \"lint:fix\": \"oxlint --fix -c .oxlintrc.json .\", \"test\": \"vitest run\", \"test:watch\": \"vitest\", \"test:unit\": \"vitest run --config vitest.unit.config.ts\", \"test:unit:watch\": \"vitest --config vitest.unit.config.ts\" }, \"dependencies\": { \"resend\": \"^6.12.0\", \"twenty-client-sdk\": \"npm:twenty-client-sdk@1.23.0-canary.1\", \"twenty-sdk\": \"npm:twenty-sdk@2.0.0\" }, \"devDependencies\": { \"@types/node\": \"^24.7.2\", \"@types/react\": \"^18.2.0\", \"oxli… 证据：`packages/twenty-apps/internal/twenty-for-twenty/package.json`\n- **Package**（package_manifest）：{ \"name\": \"twenty-linear\", \"version\": \"0.1.6\", \"description\": \"Linear integration for Twenty. Connect a user's Linear account and create issues from logic functions.\", \"license\": \"MIT\", \"engines\": { \"node\": \"^24.5.0\", \"npm\": \"please-use-yarn\", \"yarn\": \" =4.0.2\" }, \"keywords\": \"twenty-app\" , \"packageManager\": \"yarn@4.9.2\", \"scripts\": { \"twenty\": \"twenty\", \"lint\": \"oxlint -c .oxlintrc.json .\", \"lint:fix\": \"oxlint --fix -c .oxlintrc.json .\", \"test\": \"vitest run --config vitest.unit.config.ts\", \"test:watch\": \"vitest --config vitest.unit.config.ts\" }, \"dependencies\": { \"twenty-sdk\": \"2.3.1\" }, \"devDependencies\": { \"@types/node\": \"^24.7.2\", \"oxlint\": \"^0.16.0\", \"typescript\": \"^5.9.3\", \"vite-tscon… 证据：`packages/twenty-apps/internal/twenty-linear/package.json`\n- **Package**（package_manifest）：{ \"name\": \"twenty-claude-skills\", \"private\": true, \"version\": \"0.1.0\", \"description\": \"Claude skills for working with Twenty.\", \"license\": \"AGPL-3.0\", \"files\": \"skills\" } 证据：`packages/twenty-claude-skills/package.json`\n- **Package**（package_manifest）：{ \"name\": \"twenty-cli\", \"version\": \"0.3.1\", \"description\": \" DEPRECATED Use twenty-sdk instead: https://www.npmjs.com/package/twenty-sdk\", \"scripts\": { \"build\": \"echo 'use npx nx build'\", \"start\": \"echo 'deprecated'\" }, \"license\": \"AGPL-3.0\" } 证据：`packages/twenty-cli/package.json`\n- **Package**（package_manifest）：{ \"name\": \"twenty-client-sdk\", \"version\": \"2.5.0\", \"sideEffects\": false, \"license\": \"AGPL-3.0\", \"scripts\": { \"build\": \"npx rimraf dist && npx vite build && tsgo -p tsconfig.lib.json --declaration --emitDeclarationOnly --noEmit false --outDir dist --rootDir src && npx tsc-alias -p tsconfig.lib.json --outDir dist\" }, \"exports\": { \"./core\": { \"types\": \"./dist/core/index.d.ts\", \"import\": \"./dist/core.mjs\", \"require\": \"./dist/core.cjs\" }, \"./metadata\": { \"types\": \"./dist/metadata/index.d.ts\", \"import\": \"./dist/metadata.mjs\", \"require\": \"./dist/metadata.cjs\" }, \"./generate\": { \"types\": \"./dist/generate/index.d.ts\", \"import\": \"./dist/generate.mjs\", \"require\": \"./dist/generate.cjs\" } }, \"typesVersi… 证据：`packages/twenty-client-sdk/package.json`\n- **Package**（package_manifest）：{ \"name\": \"twenty-desktop\", \"productName\": \"Twenty\", \"version\": \"1.0.0\", \"description\": \"Twenty meeting recorder\", \"main\": \".webpack/main\", \"scripts\": { \"start\": \"concurrently \\\"yarn start:server\\\" \\\"yarn start:electron\\\"\", \"start:electron\": \"electron-forge start\", \"package\": \"electron-forge package\", \"make\": \"electron-forge make\", \"publish\": \"electron-forge publish\", \"lint\": \"echo \\\"No linting configured\\\"\", \"start:server\": \"node ./src/server.js\" }, \"keywords\": , \"author\": { \"name\": \"Nick Faro\", \"email\": \"yux50000@hotmail.com\" }, \"license\": \"MIT\", \"devDependencies\": { \"@babel/plugin-proposal-class-properties\": \"^7.18.6\", \"@electron-forge/cli\": \"^7.8.0\", \"@electron-forge/maker-deb\": \"^7.8.0… 证据：`packages/twenty-companion/package.json`\n- **Package**（package_manifest）：{ \"name\": \"twenty-docs\", \"description\": \"Twenty documentation site powered by Mintlify\", \"author\": \"\", \"private\": true, \"license\": \"AGPL-3.0\", \"scripts\": { \"dev\": \"mintlify dev\", \"validate\": \"mintlify validate\", \"fix-links\": \"bash scripts/fix-translated-links.sh\", \"lint\": \"npx oxlint -c .oxlintrc.json .\" }, \"dependencies\": { \"mintlify\": \"latest\" }, \"devDependencies\": { \"twenty-shared\": \"workspace: \" }, \"engines\": { \"node\": \"^24.5.0\", \"npm\": \"please-use-yarn\", \"yarn\": \"^4.0.2\" } } 证据：`packages/twenty-docs/package.json`\n- **Package**（package_manifest）：{ \"name\": \"twenty-e2e-testing\", \"description\": \"\", \"author\": \"\", \"private\": true, \"license\": \"AGPL-3.0\", \"devDependencies\": { \"@playwright/test\": \"^1.56.1\", \"playwright\": \"^1.56.1\" } } 证据：`packages/twenty-e2e-testing/package.json`\n- **Package**（package_manifest）：{ \"name\": \"twenty-emails\", \"description\": \"\", \"author\": \"\", \"private\": true, \"license\": \"AGPL-3.0\", \"main\": \"./dist/index.js\", \"scripts\": { \"build\": \"npx vite build\" }, \"dependencies\": { \"@lingui/core\": \"^5.1.2\", \"@lingui/react\": \"^5.1.2\", \"@react-email/components\": \"^0.5.3\", \"twenty-shared\": \"workspace: \" }, \"peerDependencies\": { \"react\": \"^18.2.0 ^19.0.0\", \"react-dom\": \"^18.2.0 ^19.0.0\" }, \"devDependencies\": { \"@lingui/cli\": \"^5.1.2\", \"@lingui/swc-plugin\": \"^5.11.0\", \"@lingui/vite-plugin\": \"^5.1.2\", \"@react-email/preview-server\": \"5.1.0\", \"@tiptap/core\": \"^3.4.2\", \"@types/react\": \"^19\", \"@types/react-dom\": \"^19\", \"@typescript/native-preview\": \"^7.0.0-dev.20260116.1\", \"@vitejs/plugin-react… 证据：`packages/twenty-emails/package.json`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`CLAUDE.md`, `README.md`, `.github/vale-styles/write-good/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`CLAUDE.md`, `README.md`, `.github/vale-styles/write-good/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍**：importance `high`\n - source_paths: README.md, package.json, CLAUDE.md\n- **技术栈概览**：importance `high`\n - source_paths: package.json, nx.json, packages/twenty-front/package.json, packages/twenty-server/package.json\n- **Monorepo结构**：importance `high`\n - source_paths: nx.json, package.json, packages/twenty-front/folderStructure.json, packages/twenty-docs/navigation/base-structure.json\n- **前端架构**：importance `high`\n - source_paths: packages/twenty-front/src/index.tsx, packages/twenty-front/folderStructure.json, packages/twenty-front/src/modules/activities, packages/twenty-front/src/hooks\n- **UI组件库**：importance `medium`\n - source_paths: packages/twenty-docs/twenty-ui, packages/twenty-front/src/modules/ui-library, packages/twenty-front-component-renderer/src\n- **后端架构**：importance `high`\n - source_paths: packages/twenty-server/src, packages/twenty-server/src/modules, packages/twenty-docs/developers/contribute/capabilities/backend-development\n- **数据模型**：importance `high`\n - source_paths: packages/twenty-server/src/database/data-model, packages/twenty-server/prisma/schema.prisma, packages/twenty-docs/user-guide/data-model\n- **Activities活动模块**：importance `high`\n - source_paths: packages/twenty-front/src/modules/activities, packages/twenty-front/src/modules/activities/emails, packages/twenty-front/src/modules/activities/tasks, packages/twenty-front/src/modules/activities/calendar\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `05f31c183799bf9a06f8cd35d4961396d2535290`\n- inspected_files: `package.json`, `README.md`, `packages/twenty-shared/vite.config.individual.ts`, `packages/twenty-shared/vite.config.ts`, `packages/twenty-shared/.oxlintrc.json`, `packages/twenty-shared/package.json`, `packages/twenty-shared/project.json`, `packages/twenty-shared/tsconfig.json`, `packages/twenty-shared/tsconfig.lib.json`, `packages/twenty-e2e-testing/package.json`, `packages/twenty-e2e-testing/project.json`, `packages/twenty-e2e-testing/README.md`, `packages/twenty-e2e-testing/playwright.config.ts`, `packages/twenty-utils/translation-qa-report.ts`, `packages/twenty-utils/package.json`, `packages/twenty-utils/fix-crowdin-translations.ts`, `packages/twenty-utils/fix-docs-tags.ts`, `packages/twenty-utils/congratulate-dangerfile.ts`, `packages/twenty-utils/fix-qa-issues.ts`, `packages/twenty-utils/dangerfile.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_8f7dbe9bbbcb4664b1513a32d303b9eb | https://github.com/twentyhq/twenty/issues/20625 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Restart loop after first workspace creation on a fresh self-host install 2.4.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Restart loop after first workspace creation on a fresh self-host install 2.4.0\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_45aa2211a5b64bdc84ba3b47e72701ce | https://github.com/twentyhq/twenty/issues/20666 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Cannot use the Add New Button from the list to create Tasks and Notes - Error: Should never occur, encountered unknown…\n\n- Trigger: 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\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_e572dc6d35d74c9ca8d15889a5cdcb12 | https://github.com/twentyhq/twenty/issues/15800 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：On record table, relation fields, we only display 3 items even when the cell is larger\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：On record table, relation fields, we only display 3 items even when the cell is larger\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_2446ebd3b44b4378b8725f00f1d22023 | https://github.com/twentyhq/twenty/issues/12039 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：Notes not editable in People section\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Notes not editable in People section\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_594e914f1db84296ad7d08410941f4ff | https://github.com/twentyhq/twenty/issues/20288 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：Object Type translations are not applied to details panel\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Object Type translations are not applied to details panel\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_d961ff61e7ff4bfbb2740d5b00781250 | https://github.com/twentyhq/twenty/issues/19790 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：Pagination broken when sorting by multiple fields when first field has duplicates (both REST and Graphql APIs)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Pagination broken when sorting by multiple fields when first field has duplicates (both REST and Graphql APIs)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_b5b75503f7ff4e4493c3503f86acf36b | https://github.com/twentyhq/twenty/issues/20520 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 失败模式：installation: Restart loop after first workspace creation on a fresh self-host install 2.4.0\n\n- Trigger: 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\n- Host AI rule: 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\n- Why it matters: Developers may fail before the first successful local run: Restart loop after first workspace creation on a fresh self-host install 2.4.0\n- Evidence: 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\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 失败模式：installation: v1.22.0\n\n- Trigger: Developers should check this installation risk before relying on the project: v1.22.0\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v1.22.0. Context: Observed during installation or first-run setup.\n- Why it matters: Upgrade or migration may change expected behavior: v1.22.0\n- Evidence: failure_mode_cluster:github_release | fmev_7102b6d7804c49862dcef507bd3213a5 | https://github.com/twentyhq/twenty/releases/tag/v1.22.4 | v1.22.0\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_1807294d92bc4e919fe1baf88520bb3c | https://github.com/twentyhq/twenty/issues/20671 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：twentyhq/twenty\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Restart loop after first workspace creation on a fresh self-host install 2.4.0（high）：可能影响升级、迁移或版本选择。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Cannot use the Add New Button from the list to create Tasks and Notes - Error: Should never occur, encountered unknown…（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：On record table, relation fields, we only display 3 items even when the cell is larger（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Notes not editable in People section（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/twentyhq/twenty 项目说明书\n\n生成时间：2026-05-18 21:19:12 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [技术栈概览](#page-tech-stack)\n- [Monorepo结构](#page-monorepo-structure)\n- [前端架构](#page-frontend-architecture)\n- [UI组件库](#page-ui-components)\n- [后端架构](#page-server-architecture)\n- [数据模型](#page-database-models)\n- [Activities活动模块](#page-activities-module)\n- [Views与Pipelines](#page-views-pipelines)\n- [Apps扩展系统](#page-apps-system)\n- [GitHub Connector示例](#page-github-connector)\n- [Docker部署](#page-docker-deployment)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[技术栈概览](#page-tech-stack), [Monorepo结构](#page-monorepo-structure)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/twentyhq/twenty/blob/main/README.md)\n- [packages/twenty-website-new/src/app/[locale]/(home)/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/(home)/page.tsx)\n- [packages/create-twenty-app/README.md](https://github.com/twentyhq/twenty/blob/main/packages/create-twenty-app/README.md)\n- [packages/twenty-front/src/modules/ai/components/LazyMarkdownRenderer.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/ai/components/LazyMarkdownRenderer.tsx)\n- [packages/twenty-ui/src/layout/modal/components/__stories__/Modal.stories.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-ui/src/layout/modal/components/__stories__/Modal.stories.tsx)\n \n\n# 项目介绍\n\n## 项目概述\n\nTwenty 是一个开源的客户关系管理系统（CRM），致力于为技术团队提供构建企业级 CRM 的模块化解决方案。该项目采用现代技术栈构建，具有 AI 就绪特性，支持企业快速定制和部署属于自己的 CRM 系统。\n\nTwenty 的核心价值主张在于：**构建您的竞争对手无法购买的 CRM**。作为一个开源项目，Twenty 赋予企业对系统的完全控制权，同时保持灵活性以适应不断变化的业务需求。\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:8-12]()\n\n## 核心特性\n\n### 开源与可扩展性\n\nTwenty 采用开源模式，允许企业自由部署、自托管和深度定制系统。项目采用模块化架构设计，使技术团队能够根据复杂业务需求构建定制化 CRM，同时在业务发展过程中快速适应变化。\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/why-twenty/page.tsx:5-15]()\n\n### AI 集成能力\n\nTwenty 被设计为 AI 就绪（AI-ready）系统。传统的 CRM 系统往往只是数据存储库，而 Twenty 正在演变为运营系统（Operating System）。AI 代理可以开始起草外展内容、评分潜在客户、研究客户账户、撰写跟进内容以及更新交易阶段。这些操作都会从 CRM 读取数据并写入 CRM。\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/why-twenty/page.tsx:30-45]()\n\n### 无代码定制\n\n系统提供无代码配置能力，允许用户在不依赖工程团队的情况下快速修改工作空间。自定义字段、工作流、视图和业务逻辑都可以通过可视化界面完成配置。\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/product/page.tsx:45-52]()\n\n## 项目架构\n\nTwenty 项目采用 monorepo 结构，主要包含以下核心包：\n\n| 包名 | 说明 | 技术栈 |\n|------|------|--------|\n| `packages/twenty-front` | 前端应用 | React, TypeScript |\n| `packages/twenty-ui` | UI 组件库 | React, Storybook |\n| `packages/twenty-website-new` | 官网与文档 | Next.js |\n| `packages/create-twenty-app` | CLI 脚手架工具 | Node.js |\n\n### 架构图\n\n```mermaid\ngraph TB\n subgraph 前端层\n A[packages/twenty-front
前端应用]\n B[packages/twenty-website-new
官网]\n end\n \n subgraph UI 层\n C[packages/twenty-ui
UI 组件库]\n end\n \n subgraph 工具层\n D[packages/create-twenty-app
CLI 工具]\n E[twenty-sdk]\n end\n \n A --> C\n B --> C\n D --> E\n \n style A fill:#e1f5fe\n style C fill:#fff3e0\n style D fill:#f3e5f5\n```\n\n## 包结构详解\n\n### twenty-front\n\n`packages/twenty-front` 是 Twenty 的核心前端应用，包含 CRM 的主要功能模块。该包使用 React 18 和 TypeScript 构建，采用组件化架构设计。\n\n核心模块包括：\n\n- **AI 模块** (`src/modules/ai`)：包含 `LazyMarkdownRenderer` 等组件，用于处理 AI 生成内容的渲染和展示\n- **UI 组件系统**：基于 `packages/twenty-ui` 构建的完整组件生态\n- **状态管理**：使用 React Context 和自定义 Hook 进行状态管理\n\n资料来源：[packages/twenty-front/src/modules/ai/components/LazyMarkdownRenderer.tsx:1-30]()\n\n### twenty-ui\n\n`packages/twenty-ui` 是 Twenty 的共享 UI 组件库，提供了构建 CRM 界面所需的基础组件。该库使用 Storybook 进行文档化和测试。\n\n主要组件包括：\n\n- **Modal 组件**：支持多种配置选项（`size`、`padding`、`overlay`）\n- **Button 组件**：支持多种变体（`primary`、`secondary`、`outlined`）和强调色\n- **表单组件**：输入框、下拉选择器等\n- **布局组件**：Container、Section 等\n\n资料来源：[packages/twenty-ui/src/layout/modal/components/__stories__/Modal.stories.tsx:1-60]()\n\n### twenty-website-new\n\n`packages/twenty-website-new` 是 Twenty 的官方网站的代码库，基于 Next.js App Router 构建。该包负责展示产品信息、文档、合作伙伴页面和定价页面等。\n\n网站结构包含多个主要页面：\n\n- 首页 (`/`)：产品介绍和价值主张\n- 产品页 (`/product`)：功能演示和特性展示\n- 定价页 (`/pricing`)：定价方案和计算器\n- 合作伙伴页 (`/partners`)：合作伙伴计划信息\n- 客户案例页 (`/customers`)：成功案例展示\n- 文章页 (`/articles`)：博客和团队文章\n- 隐私政策页 (`/privacy-policy`)：隐私政策文档\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:1-25]()\n\n### create-twenty-app\n\n`create-twenty-app` 是 Twenty 的官方 CLI 脚手架工具，用于快速创建基于 Twenty CRM 的应用程序。该工具集成 `twenty-sdk`，为开发者提供开箱即用的项目模板。\n\n快速开始命令：\n\n```bash\nnpx create-twenty-app@latest my-twenty-app\ncd my-twenty-app\nyarn twenty dev\n```\n\n脚手架工具会自动创建包含 TypeScript、linting 配置和 twenty-sdk 集成的项目结构。\n\n资料来源：[packages/create-twenty-app/README.md:1-25]()\n\n## 页面组件架构\n\nTwenty 网站的页面采用组件组合模式，主要包含以下结构化组件：\n\n```mermaid\ngraph LR\n A[Hero 组件] --> B[TrustedBy 组件]\n A --> C[Problem 组件]\n A --> D[ThreeCards 组件]\n A --> E[Faq 组件]\n A --> F[Signoff 组件]\n \n style A fill:#e3f2fd\n style E fill:#e8f5e9\n style F fill:#fff8e1\n```\n\n### 核心组件列表\n\n| 组件名称 | 用途 | 常见页面 |\n|----------|------|----------|\n| `Hero` | 首屏大图和主标题 | 所有页面 |\n| `TrustedBy` | 客户信任展示 | 首页、定价、合作伙伴 |\n| `Problem` | 问题陈述 | 首页 |\n| `ThreeCards` | 三栏特性卡片 | 首页、合作伙伴、产品 |\n| `Editorial` | 编辑风格内容区块 | Why Twenty 页面 |\n| `Faq` | 常见问题解答 | 所有营销页面 |\n| `Signoff` | 行动召唤区块 | 所有页面 |\n| `Testimonials` | 用户推荐轮播 | 首页、合作伙伴 |\n| `Demo` | 产品演示区块 | 产品页 |\n\n## 国际化\n\nTwenty 项目采用国际化（i18n）设计，所有用户可见的文本都通过 `i18n._()` 函数包裹，支持多语言切换。国际化配置位于 `src/lib/i18n` 目录下。\n\n使用示例：\n\n```tsx\n{i18n._(msg`Get started`)}\n{i18n._(msg`Stop fighting custom.`)}\n{i18n._(msg`Start building, with Twenty`)}\n```\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:15-22]()\n\n## 企业级功能\n\n### 自托管部署\n\nTwenty 支持企业自托管部署，提供完整的许可证激活流程。企业用户可以在完成购买后，通过激活页面将许可证密钥集成到自托管实例中。\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx:1-20]()\n\n### 隐私与合规\n\nTwenty 致力于遵守适用的数据保护法规，包括：\n\n- 通用数据保护条例（GDPR）\n- 加州消费者隐私法案（CCPA）\n\n官方隐私政策于 2025 年 10 月 13 日生效。\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/privacy-policy/_components/PrivacyPolicyDocument.tsx:1-20]()\n\n## 技术栈概览\n\n| 领域 | 技术选择 |\n|------|----------|\n| 前端框架 | React 18, Next.js |\n| 语言 | TypeScript |\n| UI 组件 | twenty-ui (内部库) |\n| 状态管理 | React Context, Hooks |\n| 样式方案 | CSS-in-JS, Theme System |\n| 国际化 | 自定义 i18n 方案 |\n| 测试 | Storybook, Testing Library |\n| 包管理 | Yarn, npm |\n\n## 快速开始\n\n开发者可以通过以下方式快速开始使用 Twenty：\n\n1. **体验云端版本**：访问 [app.twenty.com/welcome](https://app.twenty.com/welcome)\n2. **搭建本地开发环境**：使用 `create-twenty-app` CLI 工具\n3. **贡献代码**：参考项目中的 `CLAUDE.md` 了解贡献指南\n\n## 社区与支持\n\n- **Discord 社区**：[discord.gg/cx5n4Jzs57](https://discord.gg/cx5n4Jzs57)\n- **官方网站**：[twenty.com](https://twenty.com)\n- **开源许可证**：采用开源许可证（详见 LICENSE 文件）\n\n资料来源：[packages/create-twenty-app/README.md:5-8]()\n\n## 总结\n\nTwenty 是一个现代化的开源 CRM 平台，专为技术团队设计。它通过模块化架构、AI 集成能力和无代码定制特性，使企业能够构建真正符合自身需求的客户关系管理系统。作为一个活跃的开源项目，Twenty 持续演进，为开源 CRM 生态提供企业级替代方案。\n\n---\n\n\n\n## 技术栈概览\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [前端架构](#page-frontend-architecture), [后端架构](#page-server-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/twentyhq/twenty/blob/main/package.json)\n- [nx.json](https://github.com/twentyhq/twenty/blob/main/nx.json)\n- [packages/twenty-front/package.json](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/package.json)\n- [packages/twenty-server/package.json](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/package.json)\n- [packages/twenty-website-new/package.json](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/package.json)\n- [packages/twenty-docs/package.json](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/package.json)\n- [packages/create-twenty-app/README.md](https://github.com/twentyhq/twenty/blob/main/packages/create-twenty-app/README.md)\n \n\n# 技术栈概览\n\nTwenty 是一个开源的企业级 CRM 系统，采用现代化的全栈技术架构。本页面详细介绍整个项目的技术选型、核心依赖和架构设计。\n\n## 项目架构概览\n\nTwenty 采用 **Monorepo** 结构管理，使用 Nx 作为构建系统。整体架构分为前端展示层、后端服务层和数据持久层。\n\n```mermaid\ngraph TD\n subgraph 前端层\n WEB[twenty-website-new
营销网站]\n FRONT[twenty-front
CRM前端应用]\n end\n \n subgraph 服务层\n SERVER[twenty-server
后端服务]\n SDK[twenty-sdk
SDK工具包]\n end\n \n subgraph 工具层\n CLI[create-twenty-app
脚手架工具]\n DOCS[twenty-docs
文档系统]\n end\n \n subgraph 数据层\n DB[(PostgreSQL)]\n CACHE[(Redis)]\n end\n \n WEB --> SERVER\n FRONT --> SERVER\n FRONT --> SDK\n CLI --> SDK\n SERVER --> DB\n SERVER --> CACHE\n```\n\n## 包结构说明\n\n项目位于 `packages/` 目录下，主要包含以下核心包：\n\n| 包名 | 说明 | 技术框架 |\n|------|------|----------|\n| `twenty-front` | CRM 前端应用 | React, TypeScript, GraphQL |\n| `twenty-server` | 后端 API 服务 | Node.js, TypeScript |\n| `twenty-website-new` | 营销网站 | Next.js, React, TypeScript |\n| `twenty-docs` | 开发者文档 | MDX, Mintlify |\n| `twenty-sdk` | SDK 开发工具包 | TypeScript |\n| `create-twenty-app` | 项目脚手架 | Node.js CLI |\n\n## 前端技术栈\n\n### 核心框架\n\n前端采用 **React 18** 作为 UI 框架，结合 **TypeScript** 提供类型安全。组件化架构支持高度定制化的 CRM 功能开发。\n\n```mermaid\ngraph LR\n subgraph React生态\n CORE[React Core]\n ROUTER[React Router]\n QUERY[React Query
数据获取]\n FORM[React Hook Form]\n end\n \n subgraph UI层\n COMP[组件库]\n ICONS[图标系统]\n STYLES[样式方案]\n end\n \n CORE --> ROUTER\n CORE --> QUERY\n CORE --> FORM\n ROUTER --> COMP\n QUERY --> COMP\n```\n\n### 营销网站技术选型\n\n`twenty-website-new` 包采用 Next.js App Router 架构实现国际化营销站点：\n\n- **Next.js 14+**：App Router 路由系统\n- **国际化方案**：基于 `i18n._()` 的消息提取模式\n- **样式方案**：CSS Modules + 设计系统变量\n- **动态路由**：`[locale]` 动态段支持多语言\n\n### 关键特性实现\n\n从代码分析可知，前端实现了多项 CRM 核心功能：\n\n| 功能模块 | 实现方式 | 文件位置 |\n|----------|----------|----------|\n| 对象元数据管理 | 标准化对象定义系统 | `packages/twenty-server/src/engine/workspace-manager/` |\n| 字段元数据 | 字段类型系统 (UUID, DateTime 等) | `packages/twenty-server/.../field-metadata/` |\n| 工作区管理 | Workspace Manager 统一管理 | `packages/twenty-server/.../workspace-manager/` |\n\n## 后端技术栈\n\n### 服务端架构\n\n`twenty-server` 采用模块化的 Node.js 服务架构：\n\n```mermaid\ngraph TD\n API[API Gateway]\n subgraph 引擎层\n WM[Workspace Manager]\n OBJ[Object Metadata]\n FIELD[Field Metadata]\n end\n \n subgraph 标准应用\n TWENTY_STD[Twenty Standard
Application]\n end\n \n subgraph 数据层\n ORM[ORM Layer]\n DB[(Database)]\n end\n \n API --> WM\n WM --> OBJ\n WM --> FIELD\n OBJ --> TWENTY_STD\n FIELD --> TWENTY_STD\n TWENTY_STD --> ORM\n ORM --> DB\n```\n\n### 核心依赖\n\n后端服务主要依赖以下技术：\n\n| 技术类别 | 选型 | 用途 |\n|----------|------|------|\n| 运行时 | Node.js | 服务端运行环境 |\n| 语言 | TypeScript | 类型安全开发 |\n| 框架 | 自研引擎 | CRM 核心业务逻辑 |\n| 数据库 | PostgreSQL | 主数据存储 |\n| 缓存 | Redis | 会话和缓存管理 |\n| API | GraphQL | 前后端数据交互 |\n\n### 标准对象系统\n\n系统内置标准对象通过 `create-standard-flat-object-metadata` 工具创建：\n\n- **messageThread**：消息会话对象\n- **message**：消息记录对象\n- **noteTarget**：笔记关联对象\n\n每个标准对象包含以下元数据属性：\n\n| 属性 | 说明 |\n|------|------|\n| `universalIdentifier` | 全局唯一标识符 |\n| `nameSingular/namePlural` | 单复数名称 |\n| `labelSingular/labelPlural` | 显示标签 |\n| `icon` | 图标标识 |\n| `isSystem` | 系统对象标识 |\n| `labelIdentifierFieldMetadataName` | 主标识字段 |\n\n## 开发者工具链\n\n### CLI 脚手架\n\n`create-twenty-app` 提供快速启动能力：\n\n```bash\nnpx create-twenty-app@latest my-twenty-app\ncd my-twenty-app\nyarn twenty dev\n```\n\n脚手架自动配置：\n- TypeScript 项目结构\n- ESLint + Prettier 代码规范\n- twenty-sdk 集成\n- 开发服务器配置\n\n### SDK 工具包\n\n`twenty-sdk` 是连接应用与 Twenty CRM 的官方开发工具包，封装了：\n- GraphQL 客户端\n- 认证模块\n- 数据操作 API\n- 类型定义导出\n\n## 文档系统\n\n### 开发者文档架构\n\n`twenty-docs` 采用 MDX 格式编写文档，支持 Mintlify 文档站点生成：\n\n```mermaid\ngraph LR\n MDX[MDX 源文件] --> NAV[导航结构]\n NAV --> CROWDIN[国际化 Crowdin]\n CROWDIN --> BUILD[docs.json]\n BUILD --> MINTLIFY[Mintlify 站点]\n```\n\n### 文档配置要点\n\n| 文件 | 作用 |\n|------|------|\n| `navigation/base-structure.json` | 导航结构定义（英文源） |\n| `navigation/navigation.template.json` | 翻译模板 |\n| `l//navigation.json` | 各语言本地化 |\n| `docs.json` | Mintlify 配置输出 |\n\n## 构建与部署\n\n### Monorepo 构建配置\n\n项目使用 Nx 管理多包构建：\n\n- 依赖关系自动分析\n- 增量构建支持\n- 任务编排优化\n- affected 命令支持\n\n### 云端部署\n\nTwenty 支持多种部署方式：\n\n| 部署方式 | 说明 | 适用场景 |\n|----------|------|----------|\n| Cloud SaaS | twenty.com 托管服务 | 开箱即用 |\n| 自托管 | Docker/Kubernetes | 企业私有部署 |\n| 开发预览 | 本地开发环境 | 开发调试 |\n\n### 企业版激活\n\n企业版通过许可证密钥激活，激活流程：\n1. 完成企业版购买\n2. 在自托管实例中输入许可证密钥\n3. 系统验证并激活高级功能\n\n## 总结\n\nTwenty 的技术栈设计体现了现代化 CRM 的最佳实践：\n\n- **前后端分离**：清晰的职责边界\n- **TypeScript 全面覆盖**：类型安全\n- **Monorepo 管理**：代码复用与统一版本控制\n- **模块化架构**：易于扩展和维护\n- **国际化支持**：全球化部署\n\n这套技术架构既保证了系统的稳定性和可扩展性，又为开发者提供了良好的二次开发体验。\n\n---\n\n\n\n## Monorepo结构\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [前端架构](#page-frontend-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/twentyhq/twenty/blob/main/package.json)\n- [nx.json](https://github.com/twentyhq/twenty/blob/main/nx.json)\n- [packages/twenty-docs/README.md](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/README.md)\n- [packages/twenty-website-new/src/app/[locale]/(home)/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/(home)/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/articles/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/articles/page.tsx)\n- [packages/twenty-docs/navigation/base-structure.json](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/navigation/base-structure.json)\n- [packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/object-metadata/create-standard-flat-object-metadata.util.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/object-metadata/create-standard-flat-object-metadata.util.ts)\n \n\n# Monorepo结构\n\n## 概述\n\nTwenty项目采用**Nx驱动的Monorepo架构**，将前端、后端、文档等多个应用和包组织在单一代码仓库中。这种架构模式便于统一管理依赖、共享代码库、简化CI/CD流程，并确保整个项目的一致性。\n\n## 核心包结构\n\nTwenty项目的主要包位于`packages/`目录下，每个包都有独立的职责：\n\n| 包名 | 类型 | 描述 |\n|------|------|------|\n| `twenty-front` | Next.js应用 | CRM主前端界面 |\n| `twenty-server` | Node.js服务 | 后端API和引擎 |\n| `twenty-website-new` | Next.js应用 | 官方网站和营销页面 |\n| `twenty-docs` | 文档 | Mintlify文档站点 |\n\n## Nx工作区配置\n\n项目根目录的`nx.json`定义了Monorepo的工作区配置：\n\n```json\n{\n \"extends\": \"@nx/next/preset\",\n \"namedInputs\": {\n \"default\": [\"{projectRoot}/**/*\"],\n \"production\": [\"!{projectRoot}/**/*.spec.ts\"]\n }\n}\n```\n\nNx提供了以下核心能力：\n\n- **增量构建**：只重新构建变更影响的包\n- **任务编排**：管理包之间的构建顺序和依赖关系\n- **代码生成**：通过生成器创建模块、组件、服务\n- **依赖图可视化**：展示包之间的依赖关系\n\n## 前端包结构\n\n### twenty-front\n\n主CRM前端应用，包含以下核心目录：\n\n```\npackages/twenty-front/\n├── src/\n│ └── modules/ # 功能模块\n│ ├── ai/ # AI相关组件\n│ ├── activities/ # 活动管理\n│ ├── companies/ # 公司管理\n│ ├── contacts/ # 联系人\n│ └── ... # 其他业务模块\n```\n\n从`ThinkingStepsDisplay.tsx`可以看到前端组件遵循的约定：\n\n- 使用React functional component\n- 样式通过`Styled*`前缀的组件封装\n- 支持TypeScript泛型和严格类型检查\n\n### twenty-website-new\n\n新版官方网站采用App Router结构：\n\n```\npackages/twenty-website-new/\n├── src/\n│ ├── app/\n│ │ └── [locale]/ # 国际化路由\n│ │ ├── (home)/ # 首页路由组\n│ │ ├── articles/ # 文章页面\n│ │ ├── releases/ # 发布日志\n│ │ ├── customers/ # 客户案例\n│ │ ├── partners/ # 合作伙伴\n│ │ ├── product/ # 产品页面\n│ │ ├── enterprise/# 企业版页面\n│ │ ├── why-twenty/# 为什么选择Twenty\n│ │ └── privacy-policy/ # 隐私政策\n│ ├── sections/ # 可复用页面区块\n│ │ ├── Hero/ # 英雄区组件\n│ │ ├── Footer/ # 页脚\n│ │ ├── CaseStudy/ # 案例研究组件\n│ │ ├── AppPreview/ # 应用预览\n│ │ └── ...\n│ └── content/ # 内容配置\n│ └── releases/ # 发布说明MDX\n```\n\n## 后端包结构\n\n### twenty-server\n\n后端服务位于`packages/twenty-server/`，采用模块化架构：\n\n```\npackages/twenty-server/\n└── src/\n └── engine/\n ├── workspace-manager/ # 工作区管理\n │ └── twenty-standard-application/\n │ └── utils/\n │ ├── object-metadata/ # 对象元数据工具\n │ └── field-metadata/ # 字段元数据工具\n └── api/ # API层\n```\n\n核心模块包括：\n\n- **workspace-manager**：管理工作区生命周期和标准对象\n- **twenty-standard-application**：标准应用定义，包含如`messageThread`、`message`等系统对象\n- **metadata层**：处理元数据的创建和关系映射\n\n## 文档系统\n\n### twenty-docs\n\n文档包使用Mintlify框架，支持国际化：\n\n```\npackages/twenty-docs/\n├── navigation/\n│ ├── base-structure.json # 导航基准结构\n│ └── navigation.template.json # 翻译模板\n├── l/ # 本地化文件\n│ └── /\n│ └── navigation.json # 语言特定导航\n├── docs.json # 生成的Mintlify配置\n└── docs/ # MDX文档内容\n```\n\n文档导航配置流程：\n\n1. 编辑`navigation/base-structure.json`定义结构和slug\n2. 运行`yarn docs:generate-navigation-template`生成翻译模板\n3. 上传到Crowdin进行翻译\n4. 拉取翻译文件到`l//navigation.json`\n5. 运行`yarn docs:generate`生成最终配置\n\n## 依赖关系图\n\n```mermaid\ngraph TD\n A[nx.json - 工作区配置] --> B[twenty-front]\n A --> C[twenty-server]\n A --> D[twenty-website-new]\n A --> E[twenty-docs]\n \n B --> F[@twenty-ui/* 共享UI组件]\n B --> C[API调用]\n \n C --> G[workspace-manager]\n C --> H[standard-application]\n \n D --> B[复用组件]\n D --> I[content - 发布日志]\n \n E --> J[base-structure.json]\n J --> K[Crowdin翻译]\n K --> L[本地化导航]\n L --> M[docs.json]\n```\n\n## 常用命令\n\n项目根目录的`package.json`定义了关键脚本：\n\n| 命令 | 描述 |\n|------|------|\n| `yarn docs:generate` | 生成文档配置 |\n| `yarn docs:dev` | 本地开发文档 |\n| `yarn docs:validate` | 验证文档构建 |\n| `npx nx run twenty-docs:dev` | 运行文档开发服务器 |\n\n## 页面组件层次结构\n\nTwenty网站的页面采用组件组合模式：\n\n```mermaid\ngraph TD\n A[Page Component] --> B[Menu.Root]\n A --> C[Hero.Root]\n A --> D[TrustedBy.Root]\n A --> E[Feature Sections]\n A --> F[Testimonials.Root]\n A --> G[Faq.Root]\n A --> H[Signoff.Root]\n A --> I[Footer]\n \n C --> C1[Hero.Heading]\n C --> C2[Hero.Body]\n C --> C3[Hero.Cta]\n C --> C4[Hero.AppPreview]\n```\n\n## 路由和国际化\n\n网站使用Next.js App Router的`[locale]`动态路由实现国际化：\n\n```\nsrc/app/[locale]/\n├── (home)/page.tsx # 首页\n├── articles/page.tsx # 文章列表\n├── releases/page.tsx # 发布日志\n├── customers/ # 客户案例\n│ └── w3villa/page.tsx\n├── product/page.tsx # 产品页\n└── enterprise/\n └── activate/page.tsx\n```\n\n## 标准对象元数据\n\n后端定义了一系列标准对象（Standard Objects），每个对象都有标准的字段元数据：\n\n| 对象名 | 标签 | 图标 | 用途 |\n|--------|------|------|------|\n| `messageThread` | Message Thread | IconMessage | 消息线程 |\n| `message` | Message | IconMessage | 单条消息 |\n| `noteTarget` | Note Target | - | 笔记关联 |\n\n这些标准对象通过`createStandardFlatObjectMetadata`工具函数创建，具有：\n\n- 系统字段（`id`, `createdAt`, `updatedAt`）\n- 国际化标签支持（通过`i18nLabel`）\n- 标准图标定义\n- 审计日志配置\n\n## 总结\n\nTwenty的Monorepo结构设计遵循以下原则：\n\n1. **职责分离**：每个包有明确的边界和职责\n2. **共享代码**：通过包内部引用实现代码复用\n3. **增量构建**：Nx确保只构建受影响的包\n4. **国际化**：统一的locale路由和翻译管理\n5. **模块化组件**：网站区块高度可复用\n\n---\n\n\n\n## 前端架构\n\n### 相关页面\n\n相关主题：[UI组件库](#page-ui-components), [后端架构](#page-server-architecture), [Monorepo结构](#page-monorepo-structure)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/twenty-website-new/src/app/[locale]/articles/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/articles/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/(home)/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/(home)/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/partners/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/partners/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/pricing/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/pricing/page.tsx)\n- [packages/twenty-front/src/modules/ai/components/ThinkingStepsDisplay.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/ai/components/ThinkingStepsDisplay.tsx)\n- [packages/twenty-front/src/pages/not-found/NotFound.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/pages/not-found/NotFound.tsx)\n- [packages/twenty-website-new/src/sections/Footer/data.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/sections/Footer/data.ts)\n- [packages/twenty-website-new/src/app/[locale]/product/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/product/page.tsx)\n \n\n# 前端架构\n\n## 概述\n\nTwenty 项目采用**多包架构**（monorepo 结构），前端代码分散在多个独立的功能包中，主要包括：\n\n| 包名 | 用途 |\n|------|------|\n| `packages/twenty-front` | 主应用程序前端核心，包含 CRM 业务逻辑和 UI 组件 |\n| `packages/twenty-website-new` | 营销网站和新版文档站点 |\n| `packages/twenty-docs` | 开发者文档（基于 Mintlify） |\n| `packages/create-twenty-app` | 项目脚手架 CLI 工具 |\n\n本页面重点介绍 `twenty-front` 和 `twenty-website-new` 的前端架构设计。\n\n---\n\n## 整体架构分层\n\nTwenty 前端采用**模块化分层架构**，各层职责清晰分离：\n\n```mermaid\ngraph TD\n A[UI Layer
React Components] --> B[Module Layer
Feature Modules]\n B --> C[Hook Layer
Custom Hooks]\n C --> D[State Layer
Recoil/Zustand]\n D --> E[Service Layer
API Clients]\n E --> F[API Layer
GraphQL/REST]\n \n G[Pages] --> A\n H[Layouts] --> A\n I[Shared Components] --> A\n```\n\n### 层级职责说明\n\n| 层级 | 说明 | 代码位置 |\n|------|------|----------|\n| UI Layer | 原子化组件和复合组件 | `packages/twenty-front/src/modules/*/components` |\n| Module Layer | 业务功能模块封装 | `packages/twenty-front/src/modules/*` |\n| Hook Layer | 可复用的业务逻辑钩子 | `packages/twenty-front/src/hooks` |\n| State Layer | 全局状态管理 | `packages/twenty-front/src/modules/*/states` |\n| Service Layer | API 调用封装 | `packages/twenty-front/src/modules/*/services` |\n\n---\n\n## 页面路由结构\n\n### 营销网站路由 (`twenty-website-new`)\n\n营销网站基于 **Next.js App Router**，采用国际化路由 `[locale]` 动态段：\n\n```\nsrc/app/[locale]/\n├── page.tsx # 首页\n├── articles/\n│ └── page.tsx # 文章列表页\n├── partners/\n│ └── page.tsx # 合作伙伴页面\n├── pricing/\n│ └── page.tsx # 定价页面\n├── product/\n│ └── page.tsx # 产品功能页面\n├── enterprise/\n│ └── activate/\n│ └── page.tsx # 企业激活页面\n├── customers/\n│ ├── page.tsx # 客户案例列表\n│ └── w3villa/\n│ └── page.tsx # 特定案例页面\n├── why-twenty/\n│ └── page.tsx # 为什么选择 Twenty\n└── releases/\n └── page.tsx # 发布日志\n```\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:1-10]()\n\n### CRM 应用路由 (`twenty-front`)\n\n主应用使用自定义路由系统，通过 `AppPath` 常量定义路由路径：\n\n```typescript\n// 路由类型定义示例\nexport enum AppPath {\n Index = '/',\n NotFound = '/not-found',\n // ... 更多路由\n}\n```\n\n资料来源：[packages/twenty-front/src/pages/not-found/NotFound.tsx:40-50]()\n\n---\n\n## 组件架构\n\n### 组件组织模式\n\nTwenty 前端采用**区域组件**（Section Components）和**功能组件**分离的组织模式：\n\n```mermaid\ngraph LR\n A[Section Components] -->|Hero| B[HeadingGroup]\n A -->|Hero| C[Body]\n A -->|Hero| D[Cta]\n A -->|Hero| E[Visual]\n F[Feature Components] -->|TrustedBy| G[Logos]\n F -->|TrustedBy| H[Separator]\n F -->|Faq| I[Items]\n F -->|Testimonials| J[Carousel]\n```\n\n### 核心页面组件\n\n| 组件 | 功能 | 源码位置 |\n|------|------|----------|\n| `Hero.Root` | 英雄区域根容器 | `twenty-website-new/src/sections/Hero` |\n| `Hero.Heading` | 主标题渲染 | 同上 |\n| `Hero.Body` | 正文内容 | 同上 |\n| `Hero.Cta` | 行动按钮组 | 同上 |\n| `TrustedBy.Root` | 信任背书区域 | `twenty-website-new/src/sections/TrustedBy` |\n| `Faq.Root` | 常见问题区域 | `twenty-website-new/src/sections/Faq` |\n| `Signoff.Root` | 结尾号召区域 | `twenty-website-new/src/sections/Signoff` |\n| `Testimonials.Carousel` | 用户推荐轮播 | `twenty-website-new/src/sections/Testimonials` |\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:1-20]()\n\n### 组件 Props 接口模式\n\n组件使用强类型 Props 接口，继承基础配置：\n\n```typescript\n// Hero 组件 Props 示例\ninterface HeroProps {\n page: Pages; // 页面标识\n scheme?: 'light' | 'dark';\n children: React.ReactNode;\n}\n\n// Heading 组件\ninterface HeadingPartProps {\n fontFamily: 'serif' | 'sans';\n children: React.ReactNode;\n}\n```\n\n---\n\n## 样式系统\n\n### Styled Components 方案\n\nTwenty 前端使用 `styled-components` 作为主要的样式解决方案：\n\n```typescript\nconst StyledContainer = styled.div`\n display: flex;\n flex-direction: column;\n position: relative;\n`;\n\nconst StyledBackDrop = styled.div`\n position: fixed;\n top: 0;\n width: 100%;\n z-index: ${RootStackingContextZIndices.NotFound};\n`;\n```\n\n资料来源：[packages/twenty-front/src/pages/not-found/NotFound.tsx:1-30]()\n\n### 主题配置\n\n| 配置项 | 说明 |\n|--------|------|\n| `theme.colors.primary` | 主色调变体 |\n| `theme.colors.secondary` | 次要色调变体 |\n| `theme.fonts.serif` | 衬线字体（用于标题） |\n| `theme.fonts.sans` | 无衬线字体（用于正文） |\n\n---\n\n## 国际化实现\n\n### i18n 配置\n\n项目使用 `@lingui` 进行国际化处理：\n\n```typescript\nimport { msg } from '@lingui/macro';\n\n// 使用 msg 宏定义翻译文本\nconst heading = i18n._(msg`Build your Enterprise CRM`);\nconst buttonLabel = i18n._(msg`Get started`);\n```\n\n### 国际化组件\n\n| 组件 | 用途 |\n|------|------|\n| `` | 文本片段字体样式控制 |\n| `` | 眉毛标题（小标签文字） |\n| `` | React 翻译组件 |\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:5-15]()\n\n---\n\n## 状态管理\n\n### 思考步骤状态示例\n\nAI 思考步骤的显示逻辑展示了状态管理模式：\n\n```typescript\nconst ThinkingStepsDisplay = ({ parts, reasoningContent }) => {\n const shouldDisplayReasoningContent = !!reasoningContent;\n \n return (\n \n \n {parts.map((part, index) => (\n \n ))}\n \n \n );\n};\n```\n\n资料来源：[packages/twenty-front/src/modules/ai/components/ThinkingStepsDisplay.tsx:1-30]()\n\n### 状态管理模式\n\n| 模式 | 适用场景 | 库 |\n|------|----------|-----|\n| 组件本地状态 | UI 交互状态 | `useState` |\n| 全局状态 | 跨模块共享数据 | `Recoil` / `Zustand` |\n| 服务端状态 | API 数据缓存 | `React Query` / `SWR` |\n\n---\n\n## 路由与导航\n\n### 主应用路由\n\n```typescript\n// AppPath 枚举定义\nexport enum AppPath {\n Index = '/',\n NotFound = '/not-found',\n // CRM 相关路由...\n}\n\n// 404 页面实现\nexport const NotFound = () => {\n const { t } = useLingui();\n \n return (\n <>\n \n \n \n \n {/* 错误提示内容 */}\n \n \n \n \n \n \n );\n};\n```\n\n资料来源：[packages/twenty-front/src/pages/not-found/NotFound.tsx:40-75]()\n\n### 营销网站路由\n\n营销网站采用 Next.js 的文件系统路由：\n\n```typescript\n// 动态路由段 [locale]\n// 文件结构自动映射到 URL\n// /articles -> 文章列表\n// /pricing -> 定价页面\n// /partners -> 合作伙伴\n```\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/articles/page.tsx:1-10]()\n\n---\n\n## 页面布局模式\n\n### 典型页面结构\n\n```mermaid\ngraph TD\n A[Menu Header] --> B[Hero Section]\n B --> C[TrustedBy Section]\n C --> D[Feature Tabs/Sections]\n D --> E[Testimonials]\n E --> F[Faq Section]\n F --> G[Signoff Section]\n G --> H[Footer]\n```\n\n### 页面区域组件\n\n| 区域组件 | 说明 |\n|----------|------|\n| `Menu.Root` | 顶部导航菜单 |\n| `Hero.Root` | 首屏英雄区域 |\n| `TrustedBy.Root` | 客户信任背书 |\n| `Tabs.Root` | 功能特性标签页 |\n| `ThreeCards.Root` | 三卡片布局 |\n| `PromoSpacing` | 间距调整组件 |\n| `Faq.Root` | 常见问题解答 |\n| `Signoff.Root` | 页面结尾号召 |\n| `Footer` | 页脚信息 |\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/partners/page.tsx:1-40]()\n\n---\n\n## 模块化设计\n\n### 前端模块结构\n\n```\npackages/twenty-front/src/modules/\n├── activities/ # 活动/任务模块\n├── ai/ # AI 功能模块\n├── billing/ # 账单模块\n├── calendar/ # 日历模块\n├── companies/ # 公司管理模块\n├── contacts/ # 联系人模块\n├── people/ # 人员模块\n├── tasks/ # 任务模块\n└── ui-tweak/ # UI 定制模块\n```\n\n每个模块遵循统一的结构：\n\n| 子目录 | 用途 |\n|--------|------|\n| `components/` | 模块专属组件 |\n| `hooks/` | 模块专属钩子 |\n| `states/` | 模块状态定义 |\n| `services/` | 模块 API 服务 |\n| `graphql/` | GraphQL 查询和变更 |\n\n资料来源：[packages/twenty-front/src/modules/ai/components/ThinkingStepsDisplay.tsx:1-5]()\n\n---\n\n## 数据获取\n\n### API 服务层\n\n模块通过服务层封装 API 调用：\n\n```typescript\n// 服务接口定义示例\ninterface ApiService {\n getAll(): Promise;\n getById(id: string): Promise;\n create(data: Partial): Promise;\n update(id: string, data: Partial): Promise;\n delete(id: string): Promise;\n}\n```\n\n### 页面数据获取模式\n\n```typescript\n// Next.js Server Component 模式\nasync function Page() {\n // 服务端获取数据\n const posts = await getPosts();\n \n return ;\n}\n```\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/articles/page.tsx:10-20]()\n\n---\n\n## 错误处理\n\n### 404 错误页面\n\n```typescript\nconst NotFound = () => {\n return (\n \n \n \n \n Off the beaten path\n \n \n The page you're seeking is either gone or never was.\n \n \n \n \n \n \n \n \n );\n};\n```\n\n资料来源：[packages/twenty-front/src/pages/not-found/NotFound.tsx:50-70]()\n\n---\n\n## 构建与部署\n\n### 包管理器\n\n项目使用 **Yarn** 作为包管理器：\n\n```bash\n# 安装依赖\nyarn install\n\n# 开发模式\nyarn dev\n\n# 构建生产版本\nyarn build\n```\n\n### 环境配置\n\n| 环境变量 | 说明 |\n|----------|------|\n| `NEXT_PUBLIC_API_URL` | API 服务地址 |\n| `DATABASE_URL` | 数据库连接字符串 |\n| `STORAGE_SECRET` | 存储服务密钥 |\n\n---\n\n## 技术栈总结\n\n| 类别 | 技术选型 |\n|------|----------|\n| 框架 | Next.js (App Router) / React 18 |\n| 语言 | TypeScript |\n| 样式 | styled-components |\n| 状态管理 | Recoil / Zustand |\n| 国际化 | @lingui |\n| 包管理 | Yarn |\n| 组件库 | 自定义组件系统 |\n| 测试 | Jest / React Testing Library |\n\n---\n\n## 相关文档\n\n- [Twenty 官方文档](https://docs.twenty.com)\n- [Twenty GitHub 仓库](https://github.com/twentyhq/twenty)\n- [Create Twenty App CLI](https://www.npmjs.com/package/create-twenty-app)\n\n---\n\n\n\n## UI组件库\n\n### 相关页面\n\n相关主题：[前端架构](#page-frontend-architecture), [Activities活动模块](#page-activities-module)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/twenty-website-new/src/app/[locale]/(home)/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/(home)/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/product/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/product/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/pricing/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/pricing/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/partners/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/partners/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/customers/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/customers/page.tsx)\n- [packages/twenty-website-new/src/app/[locale]/why-twenty/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/why-twenty/page.tsx)\n- [packages/twenty-website-new/src/sections/Footer/data.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/sections/Footer/data.ts)\n- [packages/twenty-website-new/src/sections/Salesforce/components/PricingWindow.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/sections/Salesforce/components/PricingWindow.tsx)\n \n\n# UI组件库\n\nTwenty CRM 的 UI 组件库是一个模块化、可复用的前端组件集合，主要位于 `packages/twenty-front` 和 `packages/twenty-website-new` 包中。该组件库为整个 Twenty 产品提供一致的视觉语言和交互体验。\n\n## 组件库架构\n\n### 包结构\n\n```\ntwenty/\n├── packages/\n│ ├── twenty-front/ # 主应用前端组件\n│ │ └── src/modules/ui-library/ # UI组件库核心\n│ ├── twenty-website-new/ # 营销网站\n│ │ └── src/sections/ # 页面区块组件\n│ └── twenty-front-component-renderer/ # 组件渲染器\n```\n\n### 组件分类\n\nTwenty UI 组件库按功能可分为以下几大类：\n\n| 类别 | 功能描述 | 典型组件 |\n|------|----------|----------|\n| 布局组件 | 页面结构和容器 | Container, Panel |\n| 导航组件 | 用户导航和路由 | LinkButton, UndecoratedLink |\n| 内容组件 | 展示文本和媒体 | Heading, HeadingPart, Eyebrow |\n| 表单组件 | 用户输入和交互 | MainButton, FakeButton |\n| 数据展示 | 列表和表格 | Tiles, Cards |\n| 交互反馈 | 动画和状态 | AnimatedPlaceholder, Tooltip |\n\n## 核心组件详解\n\n### Heading 标题组件\n\n标题组件支持多种字体家族和尺寸配置，用于页面层级的视觉层次表达。\n\n```tsx\n\n \n {i18n._(msg`A modern CRM with`)}\n {' '}\n \n {i18n._(msg`an intuitive interface`)}\n \n\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 可选值 | 默认值 | 说明 |\n|------|------|--------|--------|------|\n| size | string | `sm`, `md`, `lg` | `md` | 标题尺寸 |\n| weight | string | `light`, `regular`, `bold` | `regular` | 字体粗细 |\n| fontFamily | string | `serif`, `sans` | `sans` | 字体系列 |\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/product/page.tsx]()\n\n### LinkButton 链接按钮\n\n用于页面间导航的按钮组件，支持多种变体和颜色配置。\n\n```tsx\n\n```\n\n**变体类型：**\n\n| variant | 说明 |\n|---------|------|\n| `contained` | 实心填充样式 |\n| `outlined` | 描边样式 |\n| `text` | 纯文本样式 |\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/pricing/page.tsx]()\n\n### Hero 英雄区域组件\n\n页面顶部的核心展示区域，包含主标题、描述和行动号召按钮。\n\n```tsx\n\n \n \n {i18n._(msg`Build your Enterprise CRM`)}\n {' '}\n \n {i18n._(msg`at AI Speed`)}\n \n \n \n {i18n._(\n msg`Twenty gives technical teams the building blocks...`,\n )}\n \n \n \n \n \n \n\n```\n\n**Hero 子组件结构：**\n\n```mermaid\ngraph TD\n A[Hero.Root] --> B[Hero.Heading]\n A --> C[Hero.Body]\n A --> D[Hero.Cta]\n A --> E[Hero.AppPreview 或 Hero.PartnerVisual 等]\n```\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx]()\n\n### ThreeCards 三卡片布局\n\n用于特性展示的三列卡片布局组件。\n\n```tsx\n\n \n ...\n ...\n \n \n \n\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| scheme | `light`, `muted`, `dark` | 配色方案 |\n| align | `left`, `center` | 内容对齐方式 |\n| variant | `simple`, `feature` | 卡片变体 |\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/partners/page.tsx]()\n\n### Faq 常见问题组件\n\n可折叠的问答展示组件。\n\n```tsx\n\n \n ...\n ...\n ...\n \n \n\n```\n\n**数据结构：**\n\n```typescript\ninterface FaqQuestion {\n question: string;\n answer: string;\n category?: string;\n}\n```\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/product/page.tsx]()\n\n### TrustedBy 信任背书组件\n\n展示合作品牌和客户数量的组件。\n\n```tsx\n\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| separator | ReactNode | 分隔文本 |\n| logos | Logo[] | 品牌 Logo 数组 |\n| clientCount | string | 客户数量文本 |\n| compactBottom | boolean | 紧凑底部样式 |\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/partners/page.tsx]()\n\n## 样式系统\n\n### Styled Components\n\nTwenty 使用 `styled-components` 进行样式管理，实现 CSS-in-JS 方案。\n\n```tsx\nconst StyledBackDrop = styled.div`\n position: fixed;\n top: 0;\n width: 100%;\n z-index: ${RootStackingContextZIndices.NotFound};\n`;\n\nconst StyledButtonContainer = styled.div`\n width: 200px;\n`;\n```\n\n资料来源：[packages/twenty-front/src/pages/not-found/NotFound.tsx]()\n\n### 主题配置\n\n组件通过 ThemeProvider 获取主题配置，包括颜色、字体、间距等。\n\n```typescript\n\n```\n\n### 配色方案\n\n| 方案名称 | 使用场景 |\n|----------|----------|\n| `light` | 明亮背景区块 |\n| `muted` | 柔和背景区块 |\n| `dark` | 深色背景区块 |\n| `secondary` | 次要强调色 |\n\n## 国际化支持\n\n### @lingui 集成\n\n组件使用 `@lingui` 进行国际化处理，所有用户可见文本都通过 `i18n._()` 或 `msg` 宏定义。\n\n```tsx\nimport { msg } from '@lingui/macro';\n\n// 静态文本\nconst label = msg`Get started`;\n\n// 动态文本\n{i18n._(\n msg`Twenty gives technical teams the building blocks for a custom CRM...`,\n)}\n```\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx]()\n\n## 页面构建模式\n\n### 区块组合模式\n\nTwenty 网站采用区块化设计，通过组合不同 Section 组件构建完整页面。\n\n```tsx\nexport default function HomePage() {\n return (\n <>\n ...\n ...\n ...\n ...\n ...\n ...\n ...\n \n );\n}\n```\n\n**页面结构流程：**\n\n```mermaid\ngraph LR\n A[Hero 英雄区] --> B[TrustedBy 信任背书]\n B --> C[Problem 问题陈述]\n C --> D[ThreeCards 特性卡片]\n D --> E[Feature 功能展示]\n E --> F[Testimonials 客户证言]\n F --> G[Faq 常见问题]\n```\n\n资料来源：[packages/twenty-website-new/src/app/[locale]/customers/page.tsx]()\n\n### 页面类型枚举\n\n```typescript\nenum Pages {\n Home = 'home',\n Product = 'product',\n Pricing = 'pricing',\n Partners = 'partners',\n Articles = 'articles',\n WhyTwenty = 'whyTwenty',\n}\n```\n\n## 组件渲染器\n\n### ComponentRenderer 模块\n\n`twenty-front-component-renderer` 包提供了动态渲染 UI 组件的能力，支持在运行时根据配置渲染不同组件。\n\n```\npackages/twenty-front-component-renderer/src/\n```\n\n该模块允许：\n- 根据数据动态渲染组件\n- 支持组件配置化\n- 实现运行时主题切换\n\n资料来源：[packages/twenty-front-component-renderer/src](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front-component-renderer/src)\n\n## Footer 导航数据\n\nFooter 组件使用配置化数据源定义链接和 CTAs。\n\n```typescript\n{\n id: 'footer-product',\n title: msg`Product`,\n ctas: [\n {\n color: 'secondary',\n href: 'https://app.twenty.com/welcome',\n kind: 'link',\n label: msg`Get started`,\n variant: 'outlined',\n },\n ],\n links: [\n {\n label: msg`API & SDKs`,\n href: 'https://docs.twenty.com/api-rest/overview',\n external: true,\n },\n ],\n}\n```\n\n**Footer 数据结构：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | string | 唯一标识符 |\n| title | Message | 区块标题 |\n| ctas | CTA[] | 行动号召按钮 |\n| links | Link[] | 链接列表 |\n\n资料来源：[packages/twenty-website-new/src/sections/Footer/data.ts]()\n\n## 最佳实践\n\n### 组件组合\n\n使用复合组件模式，通过子组件构建复杂 UI：\n\n```tsx\n\n ...\n ...\n\n```\n\n### 国际化处理\n\n始终使用 `i18n._()` 或 `msg` 包装用户可见文本：\n\n```tsx\n// ✅ 正确\n{i18n._(msg`Welcome`)}\n\n// ❌ 错误\nWelcome\n```\n\n### 样式隔离\n\n使用 styled-components 的样式隔离，避免全局污染：\n\n```tsx\nconst StyledContainer = styled.div`\n // 样式定义\n`;\n```\n\n### 可访问性\n\n确保交互组件包含适当的 ARIA 属性：\n\n```tsx\n\n```\n\n资料来源：[packages/twenty-website-new/src/sections/Salesforce/components/PricingWindow.tsx]()\n\n## 总结\n\nTwenty 的 UI 组件库采用模块化设计，通过复合组件模式、配置化数据和国际化支持，构建了一套高效、可维护的前端组件体系。开发者可以通过组合这些基础组件快速构建页面，同时保持视觉一致性和交互体验的统一。\n\n---\n\n\n\n## 后端架构\n\n### 相关页面\n\n相关主题：[数据模型](#page-database-models), [前端架构](#page-frontend-architecture), [Docker部署](#page-docker-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/twenty-server/src](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src)\n- [packages/twenty-server/src/modules](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/modules)\n- [packages/twenty-docs/developers/contribute/capabilities/backend-development](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/developers/contribute/capabilities/backend-development)\n- [packages/create-twenty-app/README.md](https://github.com/twentyhq/twenty/blob/main/packages/create-twenty-app/README.md)\n- [packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx)\n \n\n# 后端架构\n\n## 概述\n\nTwenty 的后端架构是整个 CRM 系统的核心，负责处理业务逻辑、数据持久化、API 接口服务以及与 AI 能力的集成。Twenty 后端采用模块化架构设计，支持自托管部署和云端服务两种模式，为企业用户提供灵活的 CRM 解决方案。\n\n后端服务位于 `packages/twenty-server/src` 目录下，采用 TypeScript 开发，具备良好的类型安全性和代码可维护性。系统核心功能围绕 **Companies（公司）**、**People（联系人）**、**Opportunities（商机）**、**Activities（活动）** 等 CRM 实体展开，通过统一的 GraphQL API 向前端和其他客户端提供服务。\n\n## 技术栈概览\n\nTwenty 后端采用现代化的技术栈构建，确保系统具备高性能、可扩展性和易维护性：\n\n| 技术类别 | 技术选型 | 说明 |\n|---------|---------|------|\n| 运行时 | Node.js / Deno | 支持服务器端执行 |\n| 语言 | TypeScript | 类型安全的开发体验 |\n| 框架 | NestJS | 模块化的企业级框架 |\n| API | GraphQL | 灵活的数据查询接口 |\n| 数据库 | PostgreSQL | 关系型数据存储 |\n| ORM | TypeORM | 数据库对象关系映射 |\n| 认证 | JWT | 无状态身份验证 |\n| 缓存 | Redis | 会话和数据缓存 |\n\n## 模块化架构\n\nTwenty 后端采用 **模块化架构（Module-based Architecture）**，每个功能领域都封装在独立的模块中。这种设计模式确保了代码的**高内聚、低耦合**，便于团队协作开发和功能扩展。\n\n### 核心模块结构\n\n```mermaid\ngraph TD\n A[twenty-server] --> B[modules]\n A --> C[core]\n A --> D[database]\n A --> E[graphql]\n \n B --> B1[companies]\n B --> B2[people]\n B --> B3[opportunities]\n B --> B4[activities]\n B --> B5[calendar]\n B --> B6[ai]\n B --> B7[messaging]\n \n C --> C1[auth]\n C --> C2[config]\n C --> C3[utils]\n \n D --> D1[migrations]\n D --> D2[seeds]\n```\n\n核心模块位于 `packages/twenty-server/src/modules` 目录下，每个子模块通常包含以下结构：\n\n```\nmodules/[module-name]/\n├── resolvers/ # GraphQL 解析器\n├── services/ # 业务逻辑服务\n├── repositories/ # 数据访问层\n├── entities/ # 数据库实体定义\n├── dto/ # 数据传输对象\n└── tests/ # 单元测试\n```\n\n## GraphQL API 层\n\nTwenty 通过 GraphQL 提供统一的数据接口，前端和其他客户端可以通过灵活的查询语法获取所需数据。GraphQL 层负责处理客户端请求的解析、权限验证和响应格式化。\n\n### API 端点结构\n\n```mermaid\ngraph LR\n A[Client] -->|GraphQL Query/Mutation| B[GraphQL Server]\n B --> C[Resolver Layer]\n C --> D[Service Layer]\n D --> E[Repository Layer]\n E --> F[(PostgreSQL)]\n \n G[Auth Service] -->|JWT Validation| B\n H[Cache Layer] -->|Redis Cache| D\n```\n\n### 查询示例\n\n```graphql\nquery GetCompaniesWithOpportunities {\n findManyCompany(\n where: { deletedAt: { equals: null } }\n orderBy: { createdAt: Desc }\n take: 10\n ) {\n id\n name\n domain\n opportunities {\n id\n amount\n stage\n }\n }\n}\n```\n\nGraphQL API 支持以下主要操作：\n\n| 操作类型 | 说明 | 示例 |\n|---------|------|------|\n| Query | 数据查询 | 获取公司列表、联系人详情 |\n| Mutation | 数据变更 | 创建商机、更新联系人 |\n| Subscription | 实时推送 | 任务状态变更通知 |\n\n## 数据模型\n\nTwenty 后端定义了丰富的 CRM 数据模型，涵盖企业运营的各个方面。核心实体通过 TypeORM 注解与数据库表映射。\n\n### 主要实体关系\n\n```mermaid\nerDiagram\n COMPANY ||--o{ PERSON : has\n COMPANY ||--o{ OPPORTUNITY : manages\n PERSON ||--o{ ACTIVITY : performs\n OPPORTUNITY ||--o{ ACTIVITY : generates\n USER ||--o{ ACTIVITY : owns\n USER ||--o{ COMPANY : assigns\n```\n\n### 核心实体说明\n\n| 实体名称 | 说明 | 主要字段 |\n|---------|------|---------|\n| Company | 公司/组织 | name, domain, employees, revenue |\n| Person | 联系人 | name, email, phone, companyId |\n| Opportunity | 商机 | name, amount, stage, probability |\n| Activity | 活动记录 | type, title, body, dueAt |\n| User | 系统用户 | email, name, role, workspace |\n| Workspace | 工作空间 | name, logo, settings |\n\n## 认证与授权\n\nTwenty 后端采用 **JWT（JSON Web Token）** 实现无状态身份验证，用户登录后获取 token，后续请求通过 token 验证用户身份。\n\n### 认证流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n participant Database\n \n Client->>Server: POST /auth/login (email, password)\n Server->>Database: 验证用户凭据\n Database-->>Server: 用户数据\n Server->>Server: 生成 JWT Token\n Server-->>Client: { accessToken, refreshToken }\n \n Client->>Server: GET /graphql (Authorization: Bearer )\n Server->>Server: 验证 Token\n Server-->>Client: 请求的数据\n```\n\n### 权限控制\n\n系统支持基于角色的访问控制（RBAC），不同角色拥有不同的数据操作权限：\n\n| 角色 | 数据访问 | 操作权限 |\n|-----|---------|---------|\n| Admin | 全部数据 | 完全控制 |\n| Member | 分配的数据 | 创建、更新、查看 |\n| Viewer | 分配的数据 | 仅查看 |\n\n## 移动端支持与 SDK\n\nTwenty 提供 `twenty-sdk` 作为构建第三方应用的基础，支持开发者基于 Twenty CRM 构建自定义应用。通过官方提供的 `create-twenty-app` CLI 工具，开发者可以快速初始化项目。\n\n```bash\nnpx create-twenty-app@latest my-twenty-app\ncd my-twenty-app\nyarn twenty dev\n```\n\nSDK 负责处理以下功能：\n\n- GraphQL API 通信封装\n- 身份验证流程管理\n- 数据缓存与同步\n- 离线模式支持\n\n## 企业部署与激活\n\n对于企业客户，Twenty 提供自托管部署方案。企业版用户可以通过许可证密钥激活系统，实现完全的数据控制和定制化需求。\n\n### 激活流程\n\n```mermaid\ngraph TD\n A[购买企业许可证] --> B[获取许可证密钥]\n B --> C[部署 Twenty 实例]\n C --> D[激活页面配置密钥]\n D --> E{验证密钥}\n E -->|成功| F[启用企业功能]\n E -->|失败| G[检查密钥有效性]\n G --> D\n```\n\n激活相关的前端页面位于 `packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx`，使用 `Suspense` 和错误边界组件确保用户体验。\n\n## 数据库设计\n\nTwenty 使用 PostgreSQL 作为主数据库，通过 TypeORM 实现对象关系映射，支持数据库迁移和种子数据管理。\n\n### 数据库目录结构\n\n```\npackages/twenty-server/src/database/\n├── migrations/ # 数据库迁移脚本\n├── seeds/ # 初始化种子数据\n└── typeorm/ # 数据库配置\n```\n\n### 迁移管理\n\n系统支持数据库版本控制，通过迁移脚本确保数据库结构与代码版本同步：\n\n```bash\n# 运行迁移\nyarn database:migrate\n\n# 回滚迁移\nyarn database:rollback\n\n# 生成新迁移\nyarn database:generate --name=add_new_field\n```\n\n## 配置管理\n\nTwenty 后端支持灵活的环境配置，通过环境变量和配置文件管理不同部署环境的参数。\n\n### 配置项说明\n\n| 配置类别 | 环境变量 | 说明 |\n|---------|---------|------|\n| 数据库 | DATABASE_URL | PostgreSQL 连接字符串 |\n| 缓存 | REDIS_URL | Redis 连接地址 |\n| 认证 | JWT_SECRET | Token 签名密钥 |\n| AI | OPENAI_API_KEY | AI 服务 API 密钥 |\n| 邮件 | SMTP_HOST | 邮件服务器地址 |\n\n## 开发贡献指南\n\n开发者可以通过以下方式参与 Twenty 后端开发：\n\n1. **本地开发环境**：参考 `packages/twenty-docs/developers/contribute/capabilities/backend-development` 文档\n2. **代码规范**：遵循项目定义的 ESLint 和 Prettier 配置\n3. **测试覆盖**：新增功能需包含对应的单元测试和集成测试\n4. **提交规范**：使用 Conventional Commits 格式描述变更\n\n## 扩展能力\n\nTwenty 后端设计支持多种扩展方式：\n\n- **自定义对象**：创建符合业务需求的 CRM 实体\n- **工作流自动化**：定义触发器和自动化动作\n- **API 扩展**：通过 Apollo Federation 集成外部服务\n- **Webhook**：与外部系统的事件集成\n\n## 总结\n\nTwenty 的后端架构采用现代化的模块化设计，通过 GraphQL API 提供灵活的数据接口，支持企业级 CRM 功能的实现。系统具备良好的可扩展性，支持自托管和云端两种部署模式，为不同规模的企业提供可靠的 CRM 解决方案。\n\n---\n\n\n\n## 数据模型\n\n### 相关页面\n\n相关主题：[后端架构](#page-server-architecture), [Activities活动模块](#page-activities-module)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/field-metadata/compute-note-target-standard-flat-field-metadata.util.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/field-metadata/compute-note-target-standard-flat-field-metadata.util.ts)\n- [packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/field-metadata/compute-blocklist-standard-flat-field-metadata.util.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/field-metadata/compute-blocklist-standard-flat-field-metadata.util.ts)\n- [packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/object-metadata/create-standard-flat-object-metadata.util.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/object-metadata/create-standard-flat-object-metadata.util.ts)\n- [packages/twenty-front/src/pages/onboarding/CreateWorkspace.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/pages/onboarding/CreateWorkspace.tsx)\n \n\n# 数据模型\n\n## 概述\n\nTwenty 的数据模型是一个基于元数据驱动（Metadata-Driven）的动态数据架构，它允许用户在不修改代码的情况下自定义数据对象、字段和关系。系统采用 Prisma ORM 作为底层数据库抽象，并通过标准应用层（Twenty Standard Application）定义一组开箱即用的标准对象。\n\n数据模型的核心设计理念：\n\n- **对象（Object）**：代表业务实体，如 Company、Person、Opportunity 等\n- **字段（Field）**：描述对象的属性，包含类型、默认值、验证规则等元信息\n- **关系（Relation）**：定义对象之间的关联，支持一对一、一对多、多对多\n- **工作区隔离**：每个工作区拥有独立的数据模型实例，实现多租户隔离\n\n## 核心组件\n\n### 标准对象（Standard Objects）\n\n标准对象是 Twenty 内置的业务实体，涵盖 CRM 核心场景：\n\n| 对象名称 | 标识符 | 描述 | 标签标识字段 |\n|---------|--------|------|-------------|\n| Company | company | 公司/组织 | name |\n| Person | person | 个人联系人 | name |\n| Opportunity | opportunity | 销售机会 | name |\n| Note | note | 笔记 | title |\n| NoteTarget | noteTarget | 笔记关联目标 | - |\n| Message | message | 消息 | subject |\n| MessageThread | messageThread | 消息线程 | subject |\n| Blocklist | blocklist | 黑名单 | - |\n\n### 标准字段（Standard Fields）\n\n每个对象都包含一组标准字段，继承自 `BaseWorkspaceEntity` 基类：\n\n| 字段名 | 类型 | 说明 | 系统字段 |\n|--------|------|------|----------|\n| id | UUID | 全局唯一标识 | 是 |\n| createdAt | DATE_TIME | 创建时间 | 是 |\n| updatedAt | DATE_TIME | 最后更新时间 | 是 |\n| deletedAt | DATE_TIME | 软删除时间 | 是 |\n\n资料来源：[compute-note-target-standard-flat-field-metadata.util.ts:11-49]()\n\n### 字段类型（FieldMetadataType）\n\n系统支持多种字段类型：\n\n| 类型标识 | 说明 | 是否支持默认值 |\n|---------|------|---------------|\n| UUID | 通用唯一标识符 | 支持（`uuid`） |\n| DATE_TIME | 日期时间 | 支持（`now`） |\n| TEXT | 文本 | 支持 |\n| NUMBER | 数字 | 支持 |\n| BOOLEAN | 布尔值 | 支持 |\n| CURRENCY | 货币 | 支持 |\n| RELATION | 关系 | 不支持 |\n\n## 元数据计算机制\n\n### 对象元数据创建\n\n标准对象元数据通过 `createStandardObjectFlatMetadata` 工具函数创建：\n\n```typescript\ncreateStandardObjectFlatMetadata({\n objectName: 'messageThread',\n dependencyFlatEntityMaps,\n context: {\n universalIdentifier: STANDARD_OBJECTS.messageThread.universalIdentifier,\n nameSingular: 'messageThread',\n namePlural: 'messageThreads',\n labelSingular: i18nLabel(msg`Message Thread`),\n labelPlural: i18nLabel(msg`Message Threads`),\n icon: 'IconMessage',\n isSystem: true,\n isAuditLogged: false,\n labelIdentifierFieldMetadataName: 'subject',\n },\n workspaceId,\n standardObjectMetadataRelatedEntityIds,\n twentyStandardApplicationId,\n now,\n})\n```\n\n资料来源：[create-standard-flat-object-metadata.util.ts:120-145]()\n\n### 字段元数据计算\n\n字段元数据通过专用的计算工具生成。以 `noteTarget` 对象为例：\n\n```typescript\ncreateStandardFieldFlatMetadata({\n objectName,\n workspaceId,\n context: {\n fieldName: 'createdAt',\n type: FieldMetadataType.DATE_TIME,\n label: i18nLabel(msg`Creation date`),\n description: i18nLabel(msg`Creation date`),\n icon: 'IconCalendar',\n isSystem: true,\n isNullable: false,\n isUIReadOnly: true,\n defaultValue: 'now',\n settings: {\n displayFormat: DateDisplayFormat.RELATIVE,\n },\n },\n standardObjectMetadataRelatedEntityIds,\n dependencyFlatEntityMaps,\n twentyStandardApplicationId,\n now,\n})\n```\n\n资料来源：[compute-note-target-standard-flat-field-metadata.util.ts:25-55]()\n\n## 工作区数据模型初始化\n\n当用户创建新工作区时，系统执行三步初始化流程：\n\n```mermaid\ngraph TD\n A[用户提交创建工作区] --> B[Step 1: 设置数据库]\n B --> C[Step 2: 创建数据模型]\n C --> D[Step 3: 预填充工作区数据]\n D --> E[工作区就绪]\n```\n\n资料来源：[CreateWorkspace.tsx:1-50]()\n\n### 初始化步骤说明\n\n| 步骤 | 标识符 | 用户提示文案 |\n|------|--------|-------------|\n| 1 | Step1 | Setting up your database... |\n| 2 | Step2 | Creating your data model... |\n| 3 | Step3 | Prefilling your workspace data... |\n\n```tsx\n{pendingCreationLoaderStep === PendingCreationLoaderStep.Step1 && (\n \n Setting up your database...\n \n)}\n{pendingCreationLoaderStep === PendingCreationLoaderStep.Step2 && (\n \n Creating your data model...\n \n)}\n{pendingCreationLoaderStep === PendingCreationLoaderStep.Step3 && (\n \n Prefilling your workspace data...\n \n)}\n```\n\n资料来源：[CreateWorkspace.tsx:35-48]()\n\n## 数据模型架构图\n\n```mermaid\ngraph TB\n subgraph 工作区层\n WM[Workspace Manager]\n SM[Standard Metadata]\n end\n \n subgraph 对象层\n CO[Company]\n PE[Person]\n OP[Opportunity]\n NO[Note]\n NOB[NoteTarget]\n end\n \n subgraph 字段层\n ID[BaseFields
id, createdAt, updatedAt]\n CF[Custom Fields]\n RF[Relation Fields]\n end\n \n subgraph 存储层\n PR[Prisma ORM]\n DB[(PostgreSQL)]\n end\n \n WM --> SM\n SM --> CO\n SM --> PE\n SM --> OP\n SM --> NO\n NO --> NOB\n \n CO --> ID\n PE --> ID\n CO --> CF\n PE --> CF\n CO --> RF\n PE --> RF\n \n PR --> DB\n```\n\n## 字段属性配置\n\n### 系统字段标记\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| isSystem | boolean | 是否为系统字段（不可删除） |\n| isNullable | boolean | 是否允许为空 |\n| isUIReadOnly | boolean | UI 是否只读 |\n| isAuditLogged | boolean | 是否记录审计日志 |\n\n### 日期字段显示格式\n\n```typescript\nsettings: {\n displayFormat: DateDisplayFormat.RELATIVE,\n}\n```\n\n支持的显示格式：\n\n| 格式 | 说明 |\n|------|------|\n| DateDisplayFormat.RELATIVE | 相对时间（1小时前） |\n| DateDisplayFormat.DATE_ONLY | 仅日期 |\n| DateDisplayFormat.DATE_TIME | 日期时间 |\n\n资料来源：[compute-blocklist-standard-flat-field-metadata.util.ts:25-60]()\n\n## 依赖管理\n\n数据模型采用依赖驱动（Dependency-Driven）的初始化机制。对象之间的依赖关系通过 `dependencyFlatEntityMaps` 传递：\n\n```typescript\ntype FlatFieldMetadata = {\n id: string;\n objectName: string;\n fieldName: string;\n type: FieldMetadataType;\n workspaceId: string;\n isSystem: boolean;\n isNullable: boolean;\n defaultValue: string | null;\n};\n```\n\n依赖计算确保父对象先于子对象创建，保证数据完整性。\n\n## 总结\n\nTwenty 的数据模型采用元数据驱动的设计，通过以下核心机制实现灵活性：\n\n1. **标准对象层**：提供开箱即用的 CRM 实体\n2. **字段元数据层**：支持多种类型和丰富配置\n3. **工作区隔离**：确保多租户数据安全\n4. **依赖解析**：保证对象创建顺序正确\n\n该架构允许开发者在不修改核心代码的前提下扩展业务实体，同时通过 Prisma 抽象保证数据库层面的类型安全和迁移管理。\n\n---\n\n\n\n## Activities活动模块\n\n### 相关页面\n\n相关主题：[前端架构](#page-frontend-architecture), [Views与Pipelines](#page-views-pipelines), [数据模型](#page-database-models)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/twenty-front/src/modules/activities](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/activities)\n- [packages/twenty-front/src/modules/activities/emails](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/activities/emails)\n- [packages/twenty-front/src/modules/activities/tasks](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/activities/tasks)\n- [packages/twenty-front/src/modules/activities/calendar](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/activities/calendar)\n- [packages/twenty-front/src/modules/activities/types/ActivityForEditor.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/activities/types/ActivityForEditor.ts)\n- [packages/twenty-website-new/src/sections/Feature/visuals/EmailsVisual.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/sections/Feature/visuals/EmailsVisual.tsx)\n- [packages/twenty-website-new/src/sections/Feature/visuals/TasksVisual.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/sections/Feature/visuals/TasksVisual.tsx)\n\n \n\n# Activities活动模块\n\n## 概述\n\nActivities活动模块是Twenty CRM系统中用于管理用户日常业务活动的核心功能模块。该模块涵盖了任务的创建与管理、便笺的记录以及电子邮件线程的查看等关键功能。Activities模块作为Twenty前端架构的重要组成部分，为用户提供了统一的交互界面来处理与客户关系相关的各类活动数据。\n\nActivities模块的设计理念是将分散的业务活动统一到一个集中的管理平台，使用户能够在单一界面内完成从任务分配、进度跟踪到沟通记录的全流程操作。该模块与其他业务对象（如联系人、公司、交易等）紧密集成，确保了数据的关联性和可追溯性。\n\n## 模块架构\n\n### 目录结构\n\nActivities模块位于`packages/twenty-front/src/modules/activities`目录下，采用功能分组的组织方式：\n\n```\nactivities/\n├── types/ # 类型定义\n│ └── ActivityForEditor.ts # 编辑器活动类型\n├── emails/ # 邮件相关组件\n├── tasks/ # 任务相关组件\n└── calendar/ # 日历相关组件\n```\n\n### 核心类型定义\n\nActivities模块的核心类型定义位于`ActivityForEditor.ts`文件中，定义了用于编辑器场景的活动数据结构：\n\n```typescript\nimport { type Note } from '@/activities/types/Note';\nimport { type Task } from '@/activities/types/Task';\n\nexport type ActivityForEditor = Partial &\n Partial> &\n Partial>;\n```\n\n这个联合类型的设计允许编辑器同时处理Task和Note两种活动类型，并通过`Partial`和`Pick`工具类型精确选择所需的字段，确保了类型系统的灵活性和安全性。\n\n## 功能模块详解\n\n### 任务模块 (Tasks)\n\n任务模块负责管理和展示用户创建的业务任务。从视觉组件`TasksVisual.tsx`的实现可以看出，任务系统包含以下核心要素：\n\n| 组件属性 | 说明 |\n|---------|------|\n| `task` | 任务描述文本 |\n| `completed` | 任务完成状态 |\n| `dueAt` | 任务截止日期 |\n| `assignee` | 任务负责人 |\n| `taskTargets` | 任务关联目标 |\n| `status` | 任务状态 |\n\n任务在界面上以列表形式展示，每个任务项包含完成状态指示器、任务名称和关联的时间戳。用户可以通过点击完成状态指示器来切换任务的完成状态，界面会通过删除线样式（`data-strikethrough`）来直观展示已完成的任务。\n\n### 邮件模块 (Emails)\n\n邮件模块提供了邮件线程的查看和管理功能。从`EmailsVisual.tsx`组件的实现来看，邮件系统包含以下结构：\n\n```typescript\ntype EmailsVisualProps = {\n active: boolean;\n};\n\nexport function EmailsVisual({ active: _active }: EmailsVisualProps) {\n const [openEmail, setOpenEmail] = useState(null);\n // ...\n}\n```\n\n邮件界面采用标签页式导航设计，包含多个邮件夹选项。每个邮件项展示发件人头像、发件人姓名、邮件主题和时间戳。点击邮件后可以展开查看完整的邮件内容，包括邮件线程中的所有消息记录。\n\n邮件组件的核心数据结构包括：\n\n- **DetailHeader**：邮件头部区域，显示主题和返回按钮\n- **DetailSenderRow**：发件人信息行，包含头像、名称和时间\n- **DetailContent**：邮件正文内容\n- **ThreadMessage**：线程消息组件\n\n### 日历模块 (Calendar)\n\n日历模块用于展示和安排与活动相关的时间信息。该模块与任务模块深度集成，支持基于截止日期的时间视图展示。\n\n## 数据流与状态管理\n\nActivities模块采用了现代化的状态管理模式，组件内部使用React Hooks管理本地状态。以下是典型的状态管理模式：\n\n```mermaid\ngraph TD\n A[用户操作] --> B[组件状态更新]\n B --> C{状态类型判断}\n C -->|完成状态| D[UI渲染更新]\n C -->|邮件操作| E[邮件列表更新]\n C -->|任务操作| F[任务列表更新]\n D --> G[持久化存储]\n E --> G\n F --> G\n```\n\n### 状态管理要点\n\nActivities模块中的状态管理包含以下几个关键方面：\n\n1. **本地状态管理**：使用`useState`管理组件级别的状态，如邮件展开状态\n2. **条件渲染**：根据状态值决定UI展示内容，如根据`openEmail === null`判断显示邮件列表还是详情\n3. **时间控制**：支持时间戳的展示和格式化\n\n## 视觉展示组件\n\nTwenty网站营销页面中的Features模块提供了丰富的可视化演示，展示了Activities功能在实际应用场景中的表现。\n\n### 任务可视化\n\n`TasksVisual.tsx`组件展示了任务列表的交互效果：\n\n- 使用`ActivityRow`作为单个任务行的容器\n- 使用`TaskCircleEl`展示完成状态指示器\n- 使用`ActivityBody`包裹任务主体内容\n- 使用`Timestamp`组件显示任务关联时间\n\n### 邮件可视化\n\n`EmailsVisual.tsx`组件模拟了完整的邮件客户端界面：\n\n- 使用`TabBar`展示邮件分类标签\n- 使用`InboxHeader`展示收件箱头部\n- 使用`DetailHeader`和`DetailBody`构建邮件详情视图\n- 支持邮件线程的展开和折叠\n\n## 组件关联图\n\n```mermaid\ngraph LR\n A[Activities模块] --> B[Task任务]\n A --> C[Note便笺]\n A --> D[Email邮件]\n A --> E[Calendar日历]\n B --> F[status]\n B --> G[dueAt]\n B --> H[assignee]\n B --> I[taskTargets]\n C --> J[noteTargets]\n D --> K[subject]\n D --> L[thread]\n```\n\n## 类型安全设计\n\nActivities模块在TypeScript类型安全方面做了精心设计。`ActivityForEditor`类型采用了以下设计模式：\n\n1. **联合类型**：使用`Task | Note`表示活动可以是任务或便笺\n2. **交叉类型**：通过`&`操作符合并多个类型约束\n3. **部分选择**：使用`Partial>`精确选择需要的字段子集\n\n这种设计模式的优势在于：\n- 提供了编译时类型检查\n- 支持灵活的数据组合\n- 便于扩展新的活动类型\n\n## 与后端标准对象的关联\n\nActivities模块与后端的数据模型紧密对应。根据服务端代码结构，系统定义了一系列标准对象来支撑活动功能的实现：\n\n| 后端对象 | 前端类型 | 说明 |\n|---------|---------|------|\n| messageThread | Email Thread | 邮件会话线程 |\n| message | Email Message | 单条邮件消息 |\n| task | Task | 业务任务 |\n| note | Note | 便笺记录 |\n\n这些标准对象定义了系统级别的活动元数据，包括对象名称、标签、图标等配置信息。\n\n## 总结\n\nActivities活动模块是Twenty CRM系统中连接用户日常业务操作与系统数据管理的核心桥梁。通过任务、便笺、邮件和日历四个子模块的协同工作，该模块为用户提供了完整的活动管理能力。\n\n模块的设计遵循了现代前端开发的最佳实践，包括：\n- 清晰的类型定义和类型安全保证\n- 模块化的组件结构\n- 灵活的状态管理方案\n- 与后端标准对象模型的完整对应\n\n这些设计使得Activities模块能够有效支撑企业的客户关系管理需求，同时保持了代码的可维护性和可扩展性。\n\n---\n\n\n\n## Views与Pipelines\n\n### 相关页面\n\n相关主题：[Activities活动模块](#page-activities-module), [前端架构](#page-frontend-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/twenty-front/src/modules/views](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views)\n- [packages/twenty-front/src/modules/pipelines](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines)\n- [packages/twenty-docs/user-guide/views-pipelines](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/user-guide/views-pipelines)\n- [packages/twenty-front/src/modules/views/states](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views/states)\n- [packages/twenty-front/src/modules/pipelines/states](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines/states)\n- [packages/twenty-front/src/modules/views/hooks](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views/hooks)\n- [packages/twenty-front/src/modules/pipelines/hooks](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines/hooks)\n- [packages/twenty-front/src/modules/views/components](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views/components)\n- [packages/twenty-front/src/modules/pipelines/components](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines/components)\n \n\n# Views与Pipelines\n\n## 概述\n\nViews（视图）和 Pipelines（管道）是 Twenty CRM 中两个核心的数据展示与业务流程管理模块。它们共同构成了系统处理和组织工作流数据的基础架构，使企业能够灵活地自定义数据展示方式和管理销售/业务管道流程。\n\n**Views** 负责定义数据列表的展示方式，包括字段配置、排序规则、筛选条件和显示布局等。**Pipelines** 则专注于管理业务流程管道，如销售管道中的阶段流转、机会追踪和自动化工作流。\n\n资料来源：[packages/twenty-front/src/modules/views](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views)\n资料来源：[packages/twenty-front/src/modules/pipelines](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines)\n\n## 架构设计\n\n### 模块层级结构\n\nTwenty 采用模块化架构设计，Views 和 Pipelines 作为独立的功能模块存在。以下是整体架构关系：\n\n```mermaid\ngraph TD\n A[Twenty Frontend] --> B[Views 模块]\n A --> C[Pipelines 模块]\n B --> D[States 状态管理]\n B --> E[Hooks 自定义钩子]\n B --> F[Components 组件]\n C --> G[States 状态管理]\n C --> H[Hooks 自定义钩子]\n C --> I[Components 组件]\n D --> J[recoil 状态Atom]\n G --> J\n```\n\n### Views 与 Pipelines 的关系\n\nViews 和 Pipelines 存在紧密的关联关系。Pipeline 视图本质上是一种特殊的 Views 实现，专门用于展示管道阶段和卡片式布局。\n\n```mermaid\ngraph TD\n A[View] -->|继承| B[BaseView]\n A -->|扩展| C[PipelineView]\n C -->|包含| D[PipelineStages]\n C -->|包含| E[PipelineSteps]\n C -->|包含| F[Opportunities]\n D -->|关联| E\n```\n\n资料来源：[packages/twenty-docs/user-guide/views-pipelines](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/user-guide/views-pipelines)\n\n## Views 模块详解\n\n### 模块结构\n\nViews 模块位于 `packages/twenty-front/src/modules/views/`，包含以下核心子目录：\n\n| 子目录 | 功能说明 |\n|--------|----------|\n| `states/` | Recoil 状态定义，包含视图配置的 Atom |\n| `hooks/` | 自定义 React Hooks，提供视图操作接口 |\n| `components/` | 视图相关 UI 组件 |\n| `types/` | TypeScript 类型定义 |\n| `utils/` | 视图工具函数 |\n\n资料来源：[packages/twenty-front/src/modules/views](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views)\n\n### 状态管理\n\nViews 模块使用 Recoil 进行状态管理，主要的状态 Atom 包括：\n\n```typescript\n// 视图配置状态\nviewIdState // 当前视图ID\nviewSortsState // 排序规则\nviewFiltersState // 筛选条件\nviewFieldsState // 字段配置\nviewkanbanHideState // 看板隐藏状态\n```\n\n这些状态通过 Selector 进行派生计算，实现视图配置的响应式更新。\n\n资料来源：[packages/twenty-front/src/modules/views/states](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views/states)\n\n### 核心 Hooks\n\nViews 模块提供了多个自定义 Hooks 用于视图操作：\n\n| Hook 名称 | 功能 |\n|-----------|------|\n| `useViews` | 获取视图列表和当前视图 |\n| `useView` | 单个视图的 CRUD 操作 |\n| `useViewSorts` | 排序规则管理 |\n| `useViewFilters` | 筛选条件管理 |\n| `useViewFields` | 字段配置管理 |\n| `useUpdateViewSorts` | 更新排序规则 |\n| `useUpdateViewFilters` | 更新筛选条件 |\n\n资料来源：[packages/twenty-front/src/modules/views/hooks](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views/hooks)\n\n### 视图类型\n\n系统支持多种视图类型，每种类型有不同的展示方式和配置选项：\n\n| 视图类型 | 标识符 | 描述 |\n|----------|--------|------|\n| 列表视图 | `Table` | 表格形式展示数据，支持列配置 |\n| 看板视图 | `Kanban` | 卡片分组展示，按阶段/字段分组 |\n| 画廊视图 | `Gallery` | 卡片网格展示，适合媒体内容 |\n| 时间线视图 | `Timeline` | 时间轴形式展示 |\n\n## Pipelines 模块详解\n\n### 模块结构\n\nPipelines 模块位于 `packages/twenty-front/src/modules/pipelines/`，是 Views 模块在业务管道场景下的扩展实现：\n\n| 子目录 | 功能说明 |\n|--------|----------|\n| `states/` | 管道相关状态定义 |\n| `hooks/` | 管道操作的自定义钩子 |\n| `components/` | 管道展示组件（看板、卡片等） |\n| `types/` | 管道相关类型定义 |\n| `utils/` | 管道工具函数 |\n\n资料来源：[packages/twenty-front/src/modules/pipelines](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines)\n\n### 管道数据模型\n\n```mermaid\nclassDiagram\n class Pipeline {\n +id: string\n +name: string\n +icon: string\n +stages: PipelineStage[]\n }\n class PipelineStage {\n +id: string\n +name: string\n +color: string\n +position: number\n +opportunities: Opportunity[]\n }\n class Opportunity {\n +id: string\n +title: string\n +companyId: string\n +pipelineStageId: string\n +amount: number\n +probability: number\n }\n \n Pipeline \"1\" *-- \"n\" PipelineStage\n PipelineStage \"1\" *-- \"n\" Opportunity\n```\n\n### 状态管理\n\nPipelines 模块的状态管理基于 Recoil，主要包括：\n\n```typescript\n// 管道状态\npipelinesState // 所有管道列表\ncurrentPipelineState // 当前选中管道\npipelineStagesState // 管道阶段\n\n// 机会状态\nopportunitiesState // 所有机会\nopportunitiesByPipelineStageState // 按阶段分组的机会\n```\n\n资料来源：[packages/twenty-front/src/modules/pipelines/states](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines/states)\n\n### 核心 Hooks\n\n| Hook 名称 | 功能 |\n|-----------|------|\n| `usePipelines` | 获取管道列表 |\n| `usePipeline` | 单个管道操作 |\n| `usePipelineStages` | 管道阶段管理 |\n| `useOpportunities` | 机会管理 |\n| `useOpportunity` | 单个机会 CRUD |\n| `useUpdatePipelineStage` | 更新阶段信息 |\n| `useUpdateOpportunity` | 更新机会信息 |\n\n资料来源：[packages/twenty-front/src/modules/pipelines/hooks](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines/hooks)\n\n## 数据流与工作流程\n\n### 视图数据加载流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant C as Component\n participant H as Hook\n participant S as State\n participant A as API\n \n U->>C: 选择视图\n C->>H: useView(viewId)\n H->>S: 读取 viewIdState\n S-->>H: 返回视图配置\n H->>A: 请求视图数据\n A-->>H: 返回记录列表\n H->>S: 更新 viewDataState\n S-->>C: 触发重新渲染\n C-->>U: 展示视图数据\n```\n\n### 管道阶段流转\n\n```mermaid\ngraph LR\n A[新建机会] --> B[资格筛选]\n B --> C[需求分析]\n C --> D[提案报价]\n D --> E[谈判审核]\n E --> F[成交]\n E --> G[输单]\n \n style A fill:#e1f5fe\n style F fill:#c8e6c9\n style G fill:#ffcdd2\n```\n\n## 组件系统\n\n### Views 组件\n\nViews 模块的组件位于 `packages/twenty-front/src/modules/views/components/`，主要组件包括：\n\n| 组件 | 用途 |\n|------|------|\n| `ViewBar` | 视图顶部导航栏 |\n| `ViewHeader` | 视图标题和操作按钮 |\n| `ViewFieldsVisibilityDropdown` | 字段显示/隐藏控制 |\n| `ViewSortDropdown` | 排序规则配置 |\n| `ViewFiltersDropdown` | 筛选条件配置 |\n| `Table` | 表格视图组件 |\n| `Board` | 看板视图组件 |\n\n资料来源：[packages/twenty-front/src/modules/views/components](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views/components)\n\n### Pipelines 组件\n\nPipelines 模块的组件位于 `packages/twenty-front/src/modules/pipelines/components/`：\n\n| 组件 | 用途 |\n|------|------|\n| `PipelineView` | 管道主视图容器 |\n| `PipelineBoard` | 看板式管道展示 |\n| `PipelineStageColumn` | 管道阶段列 |\n| `PipelineCard` | 机会卡片展示 |\n| `PipelineAddButton` | 添加阶段/机会按钮 |\n| `PipelineProgressBar` | 管道进度条 |\n\n资料来源：[packages/twenty-front/src/modules/pipelines/components](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines/components)\n\n## 配置与定制\n\n### 视图配置项\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `fields` | Field[] | 显示的字段列表及顺序 |\n| `sorts` | Sort[] | 排序规则 |\n| `filters` | Filter[] | 筛选条件 |\n| `kanbanHide` | string[] | 看板隐藏的阶段ID |\n| `kanbanGroupBy` | string | 看板分组字段 |\n\n### 管道配置项\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `name` | string | 管道名称 |\n| `icon` | string | 管道图标 |\n| `stages` | Stage[] | 阶段列表 |\n| `stageColors` | Record | 阶段颜色映射 |\n\n## 与其他模块的集成\n\nViews 和 Pipelines 模块与以下模块存在集成关系：\n\n```mermaid\ngraph TD\n V[Views/Pipelines] --> |使用| O[Objects 模块]\n V --> |使用| F[Fields 模块]\n V --> |使用| R[Relations 模块]\n V --> |渲染| UI[UI Components]\n O --> |提供数据模型| D[Data GraphQL]\n F --> |提供字段定义| D\n```\n\n### Objects 模块集成\n\nViews 基于 Objects（对象）模块定义的数据模型进行数据展示。每个视图绑定到特定的对象类型，如 \"Opportunity\"、\"Company\" 或 \"Person\"。\n\n### Fields 模块集成\n\n视图的字段配置依赖于 Fields 模块的字段定义系统，支持标准字段和自定义字段的动态配置。\n\n## 用户使用指南\n\n### 创建新视图\n\n1. 在对象列表页面，点击视图选择器\n2. 选择\"创建新视图\"\n3. 配置视图名称、图标和基础设置\n4. 配置显示字段、排序规则和筛选条件\n5. 保存视图\n\n### 配置销售管道\n\n1. 进入 Pipelines 设置页面\n2. 创建新管道或编辑现有管道\n3. 添加/编辑管道阶段\n4. 为每个阶段配置颜色和图标\n5. 设置阶段流转规则（如有）\n\n资料来源：[packages/twenty-docs/user-guide/views-pipelines](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/user-guide/views-pipelines)\n\n## 最佳实践\n\n### 视图优化建议\n\n| 实践 | 说明 |\n|------|------|\n| 限制字段数量 | 只显示必要字段，减少渲染开销 |\n| 使用索引筛选 | 在大数据集上优先使用索引字段进行筛选 |\n| 合理分组 | 看板视图避免过多分组导致的性能问题 |\n\n### 管道设计建议\n\n| 实践 | 说明 |\n|------|------|\n| 阶段数量控制 | 建议 4-7 个阶段，避免过于复杂 |\n| 明确流转规则 | 为每个阶段的流转定义清晰的触发条件 |\n| 机会状态同步 | 确保机会状态与管道阶段保持一致 |\n\n## 技术限制与注意事项\n\n- 视图配置存储在服务端，切换视图需要网络请求\n- 管道阶段不支持嵌套层级结构\n- 大型数据集（>10000 条记录）建议使用服务端分页\n- 自定义字段在视图中需要额外配置才能显示\n\n---\n\n\n\n## Apps扩展系统\n\n### 相关页面\n\n相关主题：[GitHub Connector示例](#page-github-connector), [Docker部署](#page-docker-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/twenty-apps/examples/hello-world](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/examples/hello-world)\n- [packages/create-twenty-app/src](https://github.com/twentyhq/twenty/blob/main/packages/create-twenty-app/src)\n- [packages/twenty-client-sdk/src](https://github.com/twentyhq/twenty/blob/main/packages/twenty-client-sdk/src)\n- [packages/twenty-docs/developers/extend/apps](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/developers/extend/apps)\n \n\n# Apps扩展系统\n\n## 概述\n\nTwenty的Apps扩展系统是一个模块化的应用扩展框架，允许开发者在Twenty CRM平台上构建和部署自定义业务应用程序。该系统采用现代化的插件架构，开发者可以创建独立的应用包，并在Twenty工作区内注册和使用这些应用。\n\nApps扩展系统的主要目标是：\n\n- 提供标准化的应用开发框架\n- 支持前端和后端代码的打包与分发\n- 与Twenty核心功能无缝集成\n- 支持应用的发现、安装和卸载流程\n\n## 核心组件\n\nApps扩展系统由以下几个核心包组成：\n\n| 包名 | 功能描述 | 位置 |\n|------|----------|------|\n| twenty-apps | 核心应用框架和运行时 | packages/twenty-apps |\n| twenty-client-sdk | 客户端SDK，提供React hooks和UI组件 | packages/twenty-client-sdk |\n| create-twenty-app | 应用脚手架工具，用于快速创建新应用 | packages/create-twenty-app |\n| twenty-docs | 开发者文档和API参考 | packages/twenty-docs/developers/extend/apps |\n\n## 应用架构\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[开发者] -->|create-twenty-app| B[新建App项目]\n B --> C[实现App功能]\n C --> D[打包应用]\n D --> E[twenty-apps运行时]\n E --> F[Twenty CRM]\n G[twenty-client-sdk] --> C\n```\n\n### 应用生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> 创建: create-twenty-app\n 创建 --> 开发: 编写代码\n 开发 --> 调试: 本地测试\n 调试 --> 打包: 构建生产版本\n 打包 --> 发布: 分发应用\n 发布 --> 安装: 用户安装\n 安装 --> 激活: 启用功能\n 激活 --> 使用: 运行中\n 使用 --> 卸载: 用户卸载\n 卸载 --> [*]\n```\n\n## twenty-client-sdk\n\n客户端SDK是Apps扩展系统的前端核心，提供了构建应用UI所需的React组件和Hooks。\n\n### 主要导出模块\n\nSDK包位于 `packages/twenty-client-sdk/src`，包含以下主要导出：\n\n- **React hooks**：用于数据获取、状态管理和与Twenty后端通信\n- **UI组件**：可复用的Twenty风格组件\n- **类型定义**：TypeScript类型和接口\n- **工具函数**：常用业务逻辑封装\n\n### 使用示例\n\n```typescript\nimport { useTwentyClient } from '@twenty/client-sdk';\n\n// 在App中使用Twenty客户端\nconst MyApp = () => {\n const client = useTwentyClient();\n // 通过client与Twenty后端交互\n};\n```\n\n## create-twenty-app\n\n`create-twenty-app` 是Twenty提供的命令行工具，用于快速生成新的App项目脚手架。\n\n### 命令行接口\n\n```bash\nnpx create-twenty-app@latest my-app\n```\n\n### 项目结构\n\n新建的应用项目包含以下标准结构：\n\n```\nmy-app/\n├── src/\n│ ├── index.tsx # 应用入口\n│ ├── App.tsx # 主应用组件\n│ └── components/ # 组件目录\n├── package.json\n├── twenty-app.config.ts # 应用配置\n└── tsconfig.json\n```\n\n### 应用配置\n\n应用配置文件 `twenty-app.config.ts` 定义应用的基本信息：\n\n| 配置项 | 类型 | 描述 |\n|--------|------|------|\n| name | string | 应用名称 |\n| version | string | 应用版本 |\n| description | string | 应用描述 |\n| icon | string | 应用图标标识 |\n\n## hello-world示例\n\n`packages/twenty-apps/examples/hello-world` 提供了一个完整的Hello World示例，展示了Apps扩展系统的基本用法。\n\n### 示例结构\n\n```\nhello-world/\n├── src/\n│ ├── index.tsx\n│ └── App.tsx\n├── package.json\n└── twenty-app.config.ts\n```\n\n### 核心实现\n\n示例应用演示了以下关键功能：\n\n1. **入口点定义**：通过 `index.tsx` 导出应用主组件\n2. **配置声明**：在 `package.json` 中声明应用元数据\n3. **基础UI渲染**：使用SDK组件构建简单界面\n\n## 开发流程\n\n### 环境准备\n\n1. 安装Node.js (v18+)\n2. 安装pnpm包管理器\n3. 克隆Twenty仓库\n\n### 创建新应用\n\n```bash\n# 使用create-twenty-app创建项目\npnpm create twenty-app my-first-app\n\n# 进入项目目录\ncd my-first-app\n\n# 安装依赖\npnpm install\n\n# 启动开发服务器\npnpm dev\n```\n\n### 开发规范\n\n- 使用TypeScript进行开发\n- 遵循Twenty的设计系统\n- 使用SDK提供的类型定义\n- 通过配置文件声明应用元数据\n\n### 打包发布\n\n```bash\n# 构建生产版本\npnpm build\n\n# 产出物位于 dist/ 目录\n```\n\n## 与Twenty核心的集成\n\nApps扩展系统与Twenty CRM核心深度集成，提供以下能力：\n\n### 数据访问\n\n通过 `twenty-client-sdk` 访问Twenty的数据模型：\n\n- 读取标准对象（如Company、Person、Opportunity）\n- 调用GraphQL API\n- 订阅实时数据更新\n\n### UI集成\n\n应用UI可以：\n\n- 使用Twenty的设计组件\n- 遵循Twenty的主题风格\n- 在Twenty的工作区界面中渲染\n\n### 功能扩展\n\n开发者可以通过App扩展以下功能：\n\n- 自定义数据展示\n- 业务工作流自动化\n- 第三方服务集成\n- 自定义报表和仪表盘\n\n## 最佳实践\n\n### 性能优化\n\n1. 使用SDK提供的缓存机制\n2. 实现合理的加载状态处理\n3. 避免不必要的重新渲染\n\n### 错误处理\n\n1. 使用try-catch包装API调用\n2. 向用户展示友好的错误提示\n3. 记录错误日志便于调试\n\n### 安全性\n\n1. 不在客户端存储敏感凭证\n2. 使用Twenty后端进行敏感操作\n3. 遵循最小权限原则\n\n## 相关资源\n\n| 资源类型 | 链接 |\n|----------|------|\n| 官方文档 | [Apps扩展文档](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/developers/extend/apps) |\n| 客户端SDK | [twenty-client-sdk](https://github.com/twentyhq/twenty/blob/main/packages/twenty-client-sdk/src) |\n| CLI工具 | [create-twenty-app](https://github.com/twentyhq/twenty/blob/main/packages/create-twenty-app/src) |\n| 示例代码 | [hello-world示例](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/examples/hello-world) |\n\n---\n\n\n\n## GitHub Connector示例\n\n### 相关页面\n\n相关主题：[Apps扩展系统](#page-apps-system), [后端架构](#page-server-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/twenty-apps/community/github-connector/README.md](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/community/github-connector/README.md)\n- [packages/twenty-apps/community/github-connector/src](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/community/github-connector/src)\n- [packages/twenty-apps/community/github-connector/src/modules/github](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/community/github-connector/src/modules/github)\n \n\n# GitHub Connector示例\n\n## 概述\n\nGitHub Connector 是 Twenty CRM 的一个社区应用集成模块，旨在将 GitHub 平台的数据与 Twenty CRM 系统进行深度整合。该连接器通过 GitHub App 认证机制获取授权，实现对 GitHub 仓库、Issue、Pull Request 以及 Projects (v2) 等数据的同步和展示。\n\n## 核心功能范围\n\nGitHub Connector 提供了以下核心能力：\n\n| 功能模块 | 描述 |\n|---------|------|\n| 仓库同步 | 自动同步指定的 GitHub 仓库数据 |\n| Issue 管理 | 读取和展示仓库中的 Issue 信息 |\n| Pull Request 追踪 | 监控和管理 Pull Request 状态 |\n| Projects v2 集成 | 支持 GitHub Projects (v2) 数据的读取 |\n\n## 认证机制\n\n### GitHub App 认证流程\n\nGitHub Connector 使用 GitHub App 认证方式进行授权，这种方式相比传统的 OAuth 更适合服务器端应用。\n\n```mermaid\nsequenceDiagram\n participant Connector as GitHub Connector\n participant GitHubAPI as GitHub API\n \n Note over Connector: 初始化配置\n Connector->>GitHubAPI: 使用 App Credentials 发起请求\n GitHubAPI-->>Connector: 返回 Installation Token\n Note over Connector: Token 缓存于内存\n Connector->>GitHubAPI: 使用 Installation Token 访问资源\n GitHubAPI-->>Connector: 返回请求的数据\n```\n\n### 必需的环境变量\n\n| 变量名 | 必需 | 说明 |\n|--------|------|------|\n| `GITHUB_APP_ID` | 是 | GitHub App 设置页面中的数字 App ID |\n| `GITHUB_APP_PRIVATE_KEY` | 是 | PEM 格式的私钥（支持换行） |\n| `GITHUB_APP_INSTALLATION_ID` | 是 | App 在组织/用户上的安装 ID |\n| `GITHUB_REPOS` | 是 | 逗号分隔的仓库列表，格式为 `owner/repo` |\n| `GITHUB_PROJECTS` | 否 | 逗号分隔的 GitHub Projects (v2) 列表 |\n\n## 创建 GitHub App\n\n要创建 GitHub App 并配置连接器，请按以下步骤操作：\n\n1. 访问 `https://github.com/settings/apps/new` 或组织页面 `https://github.com/organizations//settings/apps/new`\n2. 配置以下 **仓库权限**：\n\n| 权限类型 | 权限级别 |\n|---------|---------|\n| Contents | Read |\n| Issues | Read |\n| Pull Requests | Read |\n| Metadata | Read |\n| Organization → Projects (可选) | Read |\n\n3. 生成私钥（会下载 `.pem` 文件）\n4. 在组织/用户上安装 App，安装完成后的 URL 中包含安装 ID，格式为 `.../installations/12345678`\n5. 将 App ID、PEM 私钥内容和安装 ID 填入对应的环境变量\n\n## Token 管理\n\nGitHub Connector 实现了智能的 Token 缓存机制：\n\n- 连接器使用 App 凭证换取短期有效的安装 Token\n- Token 被缓存在内存中\n- 在 Token 即将过期前自动刷新\n- 所有 GitHub API 调用都通过该安装 Token 进行认证\n\n## 架构设计\n\n### 模块结构\n\n```\ngithub-connector/\n├── src/\n│ ├── modules/\n│ │ └── github/\n│ │ ├── services/ # GitHub API 服务层\n│ │ ├── types/ # TypeScript 类型定义\n│ │ └── utils/ # 工具函数\n│ └── index.ts # 模块入口\n└── README.md\n```\n\n### 数据流向\n\n```mermaid\ngraph LR\n A[GitHub API] -->|Installation Token| B[GitHub Connector]\n B -->|同步数据| C[Twenty CRM]\n C -->|存储| D[数据库]\n \n E[用户配置] -->|环境变量| B\n```\n\n## 集成示例场景\n\n### 场景一：团队协作数据同步\n\n将开发团队的 GitHub 活动（Issue 分配、PR 审查状态）同步到 CRM 中的相关公司或联系人记录，便于销售团队了解技术支持情况。\n\n### 场景二：项目管理视图\n\n通过 GitHub Projects (v2) 集成，在 Twenty CRM 中创建与 GitHub 项目进度对齐的任务视图。\n\n### 场景三：客户案例追踪\n\n对于使用 Twenty CRM 的技术咨询公司，可将客户项目的 GitHub 仓库活动作为交付进度的参考指标。\n\n## 配置示例\n\n### 环境变量配置\n\n```bash\n# 必需配置\nGITHUB_APP_ID=123456\nGITHUB_APP_PRIVATE_KEY=\"-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQD...\n-----END PRIVATE KEY-----\"\nGITHUB_APP_INSTALLATION_ID=12345678\nGITHUB_REPOS=octocat/hello-world,octo-org/octo-repo\n\n# 可选配置\nGITHUB_PROJECTS=octo-org:1,octo-org:2\n```\n\n### 仓库列表格式\n\n`GITHUB_REPOS` 环境变量支持以下格式：\n\n- 单个仓库：`owner/repo`\n- 多个仓库：`owner/repo1,owner/repo2,another-owner/another-repo`\n\n## 限制与注意事项\n\n| 注意事项 | 说明 |\n|---------|------|\n| 权限要求 | GitHub App 必须具有相应仓库的读取权限 |\n| 速率限制 | 受 GitHub API 速率限制约束 |\n| Token 有效期 | Installation Token 有时效性，Connector 自动处理刷新 |\n| 私钥格式 | 支持带换行的 PEM 格式 |\n\n## 相关资源\n\n- GitHub App 开发文档：https://docs.github.com/en/apps\n- Twenty 官方文档：https://docs.twenty.com\n- GitHub Connector 源码：https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/community/github-connector\n\n## 资料来源\n\n- [packages/twenty-apps/community/github-connector/README.md](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/community/github-connector/README.md)\n\n---\n\n\n\n## Docker部署\n\n### 相关页面\n\n相关主题：[后端架构](#page-server-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/twenty-docker/k8s/README.md](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docker/k8s/README.md)\n- [packages/twenty-docker/scripts/1-click.sh](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docker/scripts/1-click.sh)\n- [packages/twenty-docker/docker-compose.yml](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docker/docker-compose.yml)\n- [packages/twenty-docker/helm/twenty](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docker/helm/twenty)\n- [packages/twenty-docs/developers/self-host](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/developers/self-host)\n \n\n# Docker部署\n\nTwenty CRM 提供多种 Docker 部署方案，支持从简单的单机部署到复杂的 Kubernetes 集群部署。本文详细介绍如何使用 Docker 技术栈在自有基础设施上部署 Twenty CRM。\n\n## 部署方案概览\n\nTwenty 提供以下几种部署方式：\n\n| 部署方式 | 适用场景 | 复杂度 | 自动化程度 |\n|---------|---------|-------|-----------|\n| Docker Compose | 单机部署、开发环境 | 低 | 一键部署 |\n| Kubernetes | 生产集群 | 高 | 支持 Terraform |\n| Helm Chart | Kubernetes 命名空间 | 中高 | 可配置 |\n\n## 环境要求\n\n### 硬件要求\n\n- **CPU**: 最少 2 核，推荐 4 核以上\n- **内存**: 最少 4GB，推荐 8GB 以上\n- **磁盘**: 最少 20GB 可用空间\n\n### 软件要求\n\n- Docker Engine 20.10+\n- Docker Compose 2.0+\n- Kubernetes 1.24+（如需 K8s 部署）\n- Terraform 1.0+（可选）\n\n## Docker Compose 部署\n\nDocker Compose 是最简单快速的部署方式，适合单机运行或初步体验。\n\n### 快速开始\n\n```bash\n# 克隆仓库\ngit clone https://github.com/twentyhq/twenty.git\ncd twenty/packages/twenty-docker\n\n# 启动所有服务\ndocker-compose up -d\n```\n\n### 服务架构\n\n```mermaid\ngraph TD\n A[用户] --> B[NGINX反向代理]\n B --> C[Twenty Frontend]\n B --> D[Twenty Server]\n C --> E[PostgreSQL]\n D --> E\n D --> F[Redis]\n D --> G[MinIO对象存储]\n```\n\n### 环境变量配置\n\n创建 `.env` 文件配置必要的环境变量：\n\n```bash\n# 基础配置\nAPP_ENV=production\nRELEASE_VERSION=latest\n\n# 数据库配置\nPOSTGRES_DB=twenty\nPOSTGRES_USER=twenty\nPOSTGRES_PASSWORD=your_secure_password\n\n# 存储配置\nSTORAGE_S3_REGION=us-east-1\nSTORAGE_S3_BUCKET=twenty-storage\nSTORAGE_S3_ACCESS_KEY_ID=your_access_key\nSTORAGE_S3_SECRET_ACCESS_KEY=your_secret_key\n\n# 认证配置\nACCESS_TOKEN_SECRET=your_access_token_secret\nLOGIN_TOKEN_SECRET=your_login_token_secret\n```\n\n## 一键部署脚本\n\nTwenty 提供 `1-click.sh` 脚本实现自动化部署。\n\n### 脚本功能\n\n该脚本自动完成以下步骤：\n\n1. 环境检测与依赖验证\n2. 配置文件生成\n3. Docker 服务启动\n4. 数据库初始化\n5. 健康检查验证\n\n### 使用方法\n\n```bash\n# 下载并执行一键部署脚本\ncurl -fsSL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/1-click.sh | bash\n```\n\n### 脚本执行流程\n\n```mermaid\ngraph TD\n A[执行1-click.sh] --> B{检测Docker环境}\n B -->|缺失| C[提示安装Docker]\n B -->|存在| D[检查docker-compose]\n D --> E[生成配置文件]\n E --> F[拉取镜像]\n F --> G[启动服务]\n G --> H[健康检查]\n H -->|失败| I[回滚并报错]\n H -->|成功| J[部署完成]\n```\n\n## Kubernetes 部署\n\n对于生产环境，推荐使用 Kubernetes 进行部署以获得更好的可扩展性和高可用性。\n\n### 部署步骤\n\n#### 第一步：克隆仓库\n\n```bash\ngit clone https://github.com/twentyhq/twenty.git\ncd twenty/packages/twenty-docker/k8s\n```\n\n#### 第二步：自定义配置文件\n\n**重要提示**：Kubernetes 清单文件和 Terraform 配置文件需要根据实际环境进行自定义。更新占位符和配置以符合您的环境要求。\n\n#### 第三步：使用 Terraform 部署\n\n1. 进入 Terraform 目录：\n ```bash\n cd terraform\n ```\n\n2. 初始化 Terraform：\n ```bash\n terraform init\n ```\n\n3. 规划部署：\n ```bash\n terraform plan\n ```\n\n4. 执行部署：\n ```bash\n terraform apply\n ```\n\n#### 第三步（替代方案）：使用 Kubernetes 清单\n\n1. 创建命名空间：\n ```bash\n kubectl create namespace twentycrm\n ```\n\n2. 创建密钥：\n ```bash\n kubectl create secret generic -n twentycrm tokens \\\n --from-literal=accessToken=changeme \\\n --from-literal=loginToken=\"changeme\" \\\n --from-literal=refreshToken=\"changeme\" \\\n --from-literal=fileToken=\"changeme\"\n ```\n\n3. 应用清单文件：\n ```bash\n kubectl apply -f deployment.yaml\n kubectl apply -f service.yaml\n kubectl apply -f ingress.yaml\n ```\n\n### Kubernetes 组件说明\n\n| 组件类型 | 资源名称 | 说明 |\n|---------|---------|-----|\n| Deployment | twenty-server | 后端服务部署 |\n| Deployment | twenty-front | 前端服务部署 |\n| Service | twenty-server | 服务内部访问 |\n| Service | twenty-front | 前端负载均衡 |\n| Ingress | twenty-ingress | 外部流量入口 |\n| Secret | tokens | 认证令牌存储 |\n\n### Ingress 配置示例\n\n```yaml\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n name: twenty-ingress\n namespace: twentycrm\nspec:\n rules:\n - host: your-domain.com\n http:\n paths:\n - path: /\n pathType: Prefix\n backend:\n service:\n name: twenty-front\n port:\n number: 3000\n```\n\n配置 TLS 证书：\n\n```bash\nkubectl create secret tls -n twentycrm tls-secret \\\n --cert=path/to/cert.pem \\\n --key=path/to/key.pem\n\n# 使用 helm 设置 ingress TLS\nhelm upgrade twenty ./helm/twenty \\\n --set server.ingress.tls[0].hosts[0]=$DOMAIN \\\n --set server.ingress.tls[0].secretName=tls-secret\n```\n\n## Helm Chart 部署\n\nTwenty 提供 Helm Chart 用于 Kubernetes 部署。\n\n### 安装 Helm Chart\n\n```bash\n# 添加 Helm 仓库\nhelm repo add twenty https://charts.twenty.com\nhelm repo update\n\n# 安装 Twenty\nhelm install twenty twenty/twenty \\\n --namespace twentycrm \\\n --create-namespace \\\n --values values.yaml\n```\n\n### 配置参数\n\n| 参数路径 | 说明 | 默认值 |\n|---------|-----|-------|\n| `server.replicaCount` | 服务端副本数 | 1 |\n| `server.image.repository` | 镜像仓库 | twentyhq/twenty-server |\n| `server.image.tag` | 镜像标签 | latest |\n| `server.service.type` | 服务类型 | ClusterIP |\n| `server.ingress.enabled` | 启用 Ingress | false |\n| `server.ingress.host` | 域名 | - |\n| `database.enabled` | 启用内嵌数据库 | true |\n| `database.externalHost` | 外部数据库地址 | - |\n| `storage.type` | 存储类型 | minio |\n| `storage.s3.endpoint` | S3 兼容端点 | - |\n\n## 存储配置\n\n### MinIO 对象存储\n\nTwenty 使用 MinIO 作为默认对象存储解决方案。\n\n```yaml\nstorage:\n type: minio\n minio:\n endpoint: minio:9000\n bucket: twenty-storage\n accessKey: minioadmin\n secretKey: minioadmin\n```\n\n### 外部 S3 兼容存储\n\n如需使用 AWS S3 或其他 S3 兼容存储：\n\n```yaml\nstorage:\n type: s3\n s3:\n endpoint: https://s3.amazonaws.com\n region: us-east-1\n bucket: your-bucket\n accessKeyId: your-key\n secretAccessKey: your-secret\n```\n\n## 数据库配置\n\n### PostgreSQL 配置\n\n```yaml\ndatabase:\n enabled: true\n postgres:\n host: postgres\n port: 5432\n database: twenty\n username: twenty\n password: your-password\n```\n\n### 使用外部数据库\n\n```yaml\ndatabase:\n enabled: false\n externalHost: your-db-host.com\n externalPort: 5432\n externalDatabase: twenty\n externalUsername: twenty\n externalPassword: your-password\n```\n\n## 运维管理\n\n### 日志查看\n\n```bash\n# 查看所有服务日志\ndocker-compose logs -f\n\n# 查看特定服务日志\ndocker-compose logs -f server\n\n# Kubernetes 日志\nkubectl logs -n twentycrm deployment/twenty-server -f\n```\n\n### 服务重启\n\n```bash\n# Docker Compose\ndocker-compose restart\n\n# Kubernetes\nkubectl rollout restart deployment/twenty-server -n twentycrm\n```\n\n### 数据备份\n\n建议使用 PostgreSQL 的 `pg_dump` 工具进行数据库备份：\n\n```bash\n# 数据库备份\ndocker-compose exec postgres pg_dump -U twenty twenty > backup.sql\n\n# 恢复数据\ndocker-compose exec -T postgres psql -U twenty twenty < backup.sql\n```\n\n## 故障排查\n\n### 常见问题\n\n| 问题现象 | 可能原因 | 解决方案 |\n|---------|---------|---------|\n| 服务启动失败 | 端口冲突 | 检查 3000、5432、9000 端口占用 |\n| 数据库连接失败 | 凭据错误 | 检查环境变量中的数据库配置 |\n| 镜像拉取失败 | 网络问题 | 配置 Docker 镜像加速器 |\n| Ingress 无法访问 | DNS 未配置 | 确认域名解析正确 |\n\n### 健康检查\n\n```bash\n# Docker Compose 健康检查\ndocker-compose ps\n\n# Kubernetes 健康检查\nkubectl get pods -n twentycrm\nkubectl describe pod -n twentycrm \n```\n\n### 资源清理\n\n```bash\n# 停止并删除容器\ndocker-compose down -v\n\n# 删除所有镜像\ndocker-compose down --rmi all\n\n# Kubernetes 清理\nkubectl delete namespace twentycrm\n```\n\n## 安全建议\n\n1. **更换默认密码**：部署前务必修改所有默认密码和密钥\n2. **启用 HTTPS**：生产环境必须使用 TLS 证书\n3. **网络隔离**：使用 Kubernetes NetworkPolicy 限制服务间通信\n4. **定期更新**：关注 Twenty 最新版本，及时更新补丁\n5. **日志审计**：配置日志收集和分析系统\n\n## 相关文档\n\n- [本地开发环境搭建](https://docs.twenty.com/developers/contribute/capabilities/local-setup)\n- [应用开发指南](https://docs.twenty.com/developers/extend/apps/getting-started)\n- [Kubernetes 快速入门](../helm/twenty/QUICKSTART.md)\n- [Helm Chart 详细文档](../helm/twenty/README.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：twentyhq/twenty\n\n摘要：发现 31 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found。\n\n## 1. 安装坑 · 来源证据：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8f7dbe9bbbcb4664b1513a32d303b9eb | https://github.com/twentyhq/twenty/issues/20625 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Restart loop after first workspace creation on a fresh self-host install 2.4.0\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Restart loop after first workspace creation on a fresh self-host install 2.4.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_45aa2211a5b64bdc84ba3b47e72701ce | https://github.com/twentyhq/twenty/issues/20666 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 运行坑 · 来源证据：Cannot use the Add New Button from the list to create Tasks and Notes - Error: Should never occur, encountered unknown…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：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\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e572dc6d35d74c9ca8d15889a5cdcb12 | https://github.com/twentyhq/twenty/issues/15800 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 运行坑 · 来源证据：On record table, relation fields, we only display 3 items even when the cell is larger\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：On record table, relation fields, we only display 3 items even when the cell is larger\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2446ebd3b44b4378b8725f00f1d22023 | https://github.com/twentyhq/twenty/issues/12039 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 维护坑 · 来源证据：Notes not editable in People section\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Notes not editable in People section\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_594e914f1db84296ad7d08410941f4ff | https://github.com/twentyhq/twenty/issues/20288 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 维护坑 · 来源证据：Object Type translations are not applied to details panel\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Object Type translations are not applied to details panel\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d961ff61e7ff4bfbb2740d5b00781250 | https://github.com/twentyhq/twenty/issues/19790 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 安全/权限坑 · 来源证据：Pagination broken when sorting by multiple fields when first field has duplicates (both REST and Graphql APIs)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Pagination broken when sorting by multiple fields when first field has duplicates (both REST and Graphql APIs)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b5b75503f7ff4e4493c3503f86acf36b | https://github.com/twentyhq/twenty/issues/20520 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 失败模式：installation: Restart loop after first workspace creation on a fresh self-host install 2.4.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：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\n- 对用户的影响：Developers may fail before the first successful local run: Restart loop after first workspace creation on a fresh self-host install 2.4.0\n- 建议检查：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\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 9. 安装坑 · 失败模式：installation: v1.22.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.22.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.22.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.22.0. Context: Observed during installation or first-run setup.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_7102b6d7804c49862dcef507bd3213a5 | https://github.com/twentyhq/twenty/releases/tag/v1.22.4 | v1.22.0\n\n## 10. 安装坑 · 来源证据：Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1807294d92bc4e919fe1baf88520bb3c | https://github.com/twentyhq/twenty/issues/20671 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 11. 配置坑 · 失败模式：configuration: Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：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\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync\n- 建议检查：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.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 12. 配置坑 · 失败模式：configuration: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses\n- 建议检查：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\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 13. 配置坑 · 失败模式：configuration: v1.19.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: v1.19.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.19.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.19.0. Context: Observed during version upgrade or migration.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_15301e2ca30bc826383cea157ed32bcb | https://github.com/twentyhq/twenty/releases/tag/v1.19.0 | v1.19.0\n\n## 14. 配置坑 · 失败模式：configuration: v2.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: v2.0.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v2.0.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.0.0. Context: Observed when using docker\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_ab9b1aea9055fca76d3a881c8ee8f317 | https://github.com/twentyhq/twenty/releases/tag/v2.0.0 | v2.0.0\n\n## 15. 配置坑 · 失败模式：configuration: v2.3.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: v2.3.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v2.3.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.3.0. Context: Observed when using docker\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_05b61500a200d1852774253b2b09cb5f | https://github.com/twentyhq/twenty/releases/tag/v2.3.0 | v2.3.0\n\n## 16. 配置坑 · 失败模式：configuration: v2.4.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: v2.4.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v2.4.0\n- 建议检查：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.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_c37fffb0f1bdf017e6070e311b099597 | https://github.com/twentyhq/twenty/releases/tag/v2.4.0 | v2.4.0\n\n## 17. 配置坑 · 来源证据：TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4abd78a034024d29b94e860fbcb298e6 | https://github.com/twentyhq/twenty/issues/20136 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 18. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:572984571 | https://github.com/twentyhq/twenty | README/documentation is current enough for a first validation pass.\n\n## 19. 运行坑 · 来源证据：Bug(UI): Currency icon not aligned properly\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Bug(UI): Currency icon not aligned properly\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c2c473e13c324a60a1b0ba450f77fb32 | https://github.com/twentyhq/twenty/issues/20640 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · 失败模式：migration: v1.20.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: v1.20.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.20.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.20.0. Context: Observed during version upgrade or migration.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_b9ae97dbbd9c277df82d69cda517b768 | https://github.com/twentyhq/twenty/releases/tag/v1.20.0 | v1.20.0\n\n## 21. 维护坑 · 失败模式：migration: v1.21.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: v1.21.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.21.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.21.0. Context: Observed during version upgrade or migration.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_ea380ef68973d4bb1f069cd337fd42af | https://github.com/twentyhq/twenty/releases/tag/v1.21.0 | v1.21.0\n\n## 22. 维护坑 · 失败模式：migration: v1.23.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: v1.23.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.23.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.23.0. Context: Observed during version upgrade or migration.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_d757a9aab11c1a39bfa726eebcb7ab5e | https://github.com/twentyhq/twenty/releases/tag/v1.23.0 | v1.23.0\n\n## 23. 维护坑 · 失败模式：migration: v2.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: v2.1.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v2.1.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.1.0. Context: Observed during version upgrade or migration.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_0bb1a26151a8ea54475ab5fc8c9566c7 | https://github.com/twentyhq/twenty/releases/tag/v2.1.0 | v2.1.0\n\n## 24. 维护坑 · 失败模式：migration: v2.2.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: v2.2.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v2.2.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.2.0. Context: Observed during version upgrade or migration.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_9cfa053b1c1093a4e4bdfc861bc786ab | https://github.com/twentyhq/twenty/releases/tag/v2.2.0 | v2.2.0\n\n## 25. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:572984571 | https://github.com/twentyhq/twenty | last_activity_observed missing\n\n## 26. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:572984571 | https://github.com/twentyhq/twenty | no_demo; severity=medium\n\n## 27. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:572984571 | https://github.com/twentyhq/twenty | no_demo; severity=medium\n\n## 28. 能力坑 · 失败模式：capability: Bug(UI): BlockNote Editor slash command shows nothing when no matches are found\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: Bug(UI): BlockNote Editor slash command shows nothing when no matches are found\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Bug(UI): BlockNote Editor slash command shows nothing when no matches are found\n- 建议检查：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.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 29. 能力坑 · 失败模式：capability: Bug(UI): Currency icon not aligned properly\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: Bug(UI): Currency icon not aligned properly\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Bug(UI): Currency icon not aligned properly\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Bug(UI): Currency icon not aligned properly. Context: Observed when using docker\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_5b942675e057e849cb68cf3923b56dce | https://github.com/twentyhq/twenty/issues/20640 | Bug(UI): Currency icon not aligned properly\n\n## 30. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:572984571 | https://github.com/twentyhq/twenty | issue_or_pr_quality=unknown\n\n## 31. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:572984571 | https://github.com/twentyhq/twenty | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：twentyhq/twenty\n\n摘要：发现 31 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found。\n\n## 1. 安装坑 · 来源证据：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8f7dbe9bbbcb4664b1513a32d303b9eb | https://github.com/twentyhq/twenty/issues/20625 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Restart loop after first workspace creation on a fresh self-host install 2.4.0\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Restart loop after first workspace creation on a fresh self-host install 2.4.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_45aa2211a5b64bdc84ba3b47e72701ce | https://github.com/twentyhq/twenty/issues/20666 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 运行坑 · 来源证据：Cannot use the Add New Button from the list to create Tasks and Notes - Error: Should never occur, encountered unknown…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：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\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e572dc6d35d74c9ca8d15889a5cdcb12 | https://github.com/twentyhq/twenty/issues/15800 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 运行坑 · 来源证据：On record table, relation fields, we only display 3 items even when the cell is larger\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：On record table, relation fields, we only display 3 items even when the cell is larger\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2446ebd3b44b4378b8725f00f1d22023 | https://github.com/twentyhq/twenty/issues/12039 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 维护坑 · 来源证据：Notes not editable in People section\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Notes not editable in People section\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_594e914f1db84296ad7d08410941f4ff | https://github.com/twentyhq/twenty/issues/20288 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 维护坑 · 来源证据：Object Type translations are not applied to details panel\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Object Type translations are not applied to details panel\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d961ff61e7ff4bfbb2740d5b00781250 | https://github.com/twentyhq/twenty/issues/19790 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 安全/权限坑 · 来源证据：Pagination broken when sorting by multiple fields when first field has duplicates (both REST and Graphql APIs)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Pagination broken when sorting by multiple fields when first field has duplicates (both REST and Graphql APIs)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b5b75503f7ff4e4493c3503f86acf36b | https://github.com/twentyhq/twenty/issues/20520 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 失败模式：installation: Restart loop after first workspace creation on a fresh self-host install 2.4.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：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\n- 对用户的影响：Developers may fail before the first successful local run: Restart loop after first workspace creation on a fresh self-host install 2.4.0\n- 建议检查：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\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 9. 安装坑 · 失败模式：installation: v1.22.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.22.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.22.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.22.0. Context: Observed during installation or first-run setup.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_7102b6d7804c49862dcef507bd3213a5 | https://github.com/twentyhq/twenty/releases/tag/v1.22.4 | v1.22.0\n\n## 10. 安装坑 · 来源证据：Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1807294d92bc4e919fe1baf88520bb3c | https://github.com/twentyhq/twenty/issues/20671 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 11. 配置坑 · 失败模式：configuration: Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：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\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync\n- 建议检查：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.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 12. 配置坑 · 失败模式：configuration: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses\n- 建议检查：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\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 13. 配置坑 · 失败模式：configuration: v1.19.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: v1.19.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.19.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.19.0. Context: Observed during version upgrade or migration.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_15301e2ca30bc826383cea157ed32bcb | https://github.com/twentyhq/twenty/releases/tag/v1.19.0 | v1.19.0\n\n## 14. 配置坑 · 失败模式：configuration: v2.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: v2.0.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v2.0.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.0.0. Context: Observed when using docker\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_ab9b1aea9055fca76d3a881c8ee8f317 | https://github.com/twentyhq/twenty/releases/tag/v2.0.0 | v2.0.0\n\n## 15. 配置坑 · 失败模式：configuration: v2.3.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: v2.3.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v2.3.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.3.0. Context: Observed when using docker\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_05b61500a200d1852774253b2b09cb5f | https://github.com/twentyhq/twenty/releases/tag/v2.3.0 | v2.3.0\n\n## 16. 配置坑 · 失败模式：configuration: v2.4.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: v2.4.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v2.4.0\n- 建议检查：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.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_c37fffb0f1bdf017e6070e311b099597 | https://github.com/twentyhq/twenty/releases/tag/v2.4.0 | v2.4.0\n\n## 17. 配置坑 · 来源证据：TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4abd78a034024d29b94e860fbcb298e6 | https://github.com/twentyhq/twenty/issues/20136 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 18. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:572984571 | https://github.com/twentyhq/twenty | README/documentation is current enough for a first validation pass.\n\n## 19. 运行坑 · 来源证据：Bug(UI): Currency icon not aligned properly\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Bug(UI): Currency icon not aligned properly\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c2c473e13c324a60a1b0ba450f77fb32 | https://github.com/twentyhq/twenty/issues/20640 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · 失败模式：migration: v1.20.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: v1.20.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.20.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.20.0. Context: Observed during version upgrade or migration.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_b9ae97dbbd9c277df82d69cda517b768 | https://github.com/twentyhq/twenty/releases/tag/v1.20.0 | v1.20.0\n\n## 21. 维护坑 · 失败模式：migration: v1.21.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: v1.21.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.21.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.21.0. Context: Observed during version upgrade or migration.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_ea380ef68973d4bb1f069cd337fd42af | https://github.com/twentyhq/twenty/releases/tag/v1.21.0 | v1.21.0\n\n## 22. 维护坑 · 失败模式：migration: v1.23.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: v1.23.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.23.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.23.0. Context: Observed during version upgrade or migration.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_d757a9aab11c1a39bfa726eebcb7ab5e | https://github.com/twentyhq/twenty/releases/tag/v1.23.0 | v1.23.0\n\n## 23. 维护坑 · 失败模式：migration: v2.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: v2.1.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v2.1.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.1.0. Context: Observed during version upgrade or migration.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_0bb1a26151a8ea54475ab5fc8c9566c7 | https://github.com/twentyhq/twenty/releases/tag/v2.1.0 | v2.1.0\n\n## 24. 维护坑 · 失败模式：migration: v2.2.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: v2.2.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v2.2.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.2.0. Context: Observed during version upgrade or migration.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_9cfa053b1c1093a4e4bdfc861bc786ab | https://github.com/twentyhq/twenty/releases/tag/v2.2.0 | v2.2.0\n\n## 25. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:572984571 | https://github.com/twentyhq/twenty | last_activity_observed missing\n\n## 26. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:572984571 | https://github.com/twentyhq/twenty | no_demo; severity=medium\n\n## 27. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:572984571 | https://github.com/twentyhq/twenty | no_demo; severity=medium\n\n## 28. 能力坑 · 失败模式：capability: Bug(UI): BlockNote Editor slash command shows nothing when no matches are found\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: Bug(UI): BlockNote Editor slash command shows nothing when no matches are found\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Bug(UI): BlockNote Editor slash command shows nothing when no matches are found\n- 建议检查：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.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 29. 能力坑 · 失败模式：capability: Bug(UI): Currency icon not aligned properly\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: Bug(UI): Currency icon not aligned properly\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Bug(UI): Currency icon not aligned properly\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Bug(UI): Currency icon not aligned properly. Context: Observed when using docker\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_5b942675e057e849cb68cf3923b56dce | https://github.com/twentyhq/twenty/issues/20640 | Bug(UI): Currency icon not aligned properly\n\n## 30. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:572984571 | https://github.com/twentyhq/twenty | issue_or_pr_quality=unknown\n\n## 31. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:572984571 | https://github.com/twentyhq/twenty | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# twenty - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 twenty 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的客户沟通与团队运营任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-tech-stack：技术栈概览。围绕“技术栈概览”模拟一次用户任务，不展示安装或运行结果。\n3. page-monorepo-structure：Monorepo结构。围绕“Monorepo结构”模拟一次用户任务，不展示安装或运行结果。\n4. page-frontend-architecture：前端架构。围绕“前端架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-server-architecture：后端架构。围绕“后端架构”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-tech-stack\n输入：用户提供的“技术栈概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-monorepo-structure\n输入：用户提供的“Monorepo结构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-frontend-architecture\n输入：用户提供的“前端架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-server-architecture\n输入：用户提供的“后端架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-tech-stack：Step 2 必须围绕“技术栈概览”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-monorepo-structure：Step 3 必须围绕“Monorepo结构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-frontend-architecture：Step 4 必须围绕“前端架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-server-architecture：Step 5 必须围绕“后端架构”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/twentyhq/twenty\n- https://github.com/twentyhq/twenty#readme\n- .cursor/skills/syncable-entity-builder-and-validation/SKILL.md\n- .cursor/skills/syncable-entity-cache-and-transform/SKILL.md\n- .cursor/skills/syncable-entity-integration/SKILL.md\n- .cursor/skills/syncable-entity-runner-and-actions/SKILL.md\n- .cursor/skills/syncable-entity-testing/SKILL.md\n- .cursor/skills/syncable-entity-types-and-constants/SKILL.md\n- packages/twenty-claude-skills/skills/twenty-record-presentation/SKILL.md\n- README.md\n- package.json\n- CLAUDE.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 twenty 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：twentyhq/twenty\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx create-twenty-app\n```\n\n来源：https://github.com/twentyhq/twenty#readme\n\n## 来源\n\n- repo: https://github.com/twentyhq/twenty\n- docs: https://github.com/twentyhq/twenty#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_dc0a3e18e3004d02b563af37ede7f8e8"
}