{ "canonical_name": "nocobase/nocobase", "compilation_id": "pack_8c92950e1eb844dfbe1a0d9a59ff7b5e", "created_at": "2026-05-18T03:05:27.294805+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 `npm install -g @nocobase/cli@beta` 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": "npm install -g @nocobase/cli@beta", "sandbox_container_image": "node:22-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_bfe181e6b8ab46e1966b59684a966970" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_b6cd00c55779838784bb89dbfdde4bf1", "canonical_name": "nocobase/nocobase", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/nocobase/nocobase", "slug": "nocobase", "source_packet_id": "phit_593d3163cc094881bd6a3b64c7f75dee", "source_validation_id": "dval_f19ace9415b842238cdebc408dab5a9d" }, "merchandising": { "best_for": "需要客户沟通与团队运营能力，并使用 local_cli的用户", "github_forks": 2596, "github_stars": 22374, "one_liner_en": "NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.", "one_liner_zh": "NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.", "primary_category": { "category_id": "customer-team-operations", "confidence": "high", "name_en": "Customer & Team Operations", "name_zh": "客户沟通与团队运营", "reason": "curated popular coverage category matched project identity" }, "target_user": "使用 local_cli 等宿主 AI 的用户", "title_en": "nocobase", "title_zh": "nocobase 能力包", "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": "Structured Data Extraction", "label_zh": "结构化数据提取", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-structured-data-extraction", "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": "Open Source Tool", "label_zh": "开源工具", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-open-source-tool", "type": "selection_signal" } ] }, "packet_id": "phit_593d3163cc094881bd6a3b64c7f75dee", "page_model": { "artifacts": { "artifact_slug": "nocobase", "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": "npm install -g @nocobase/cli@beta", "label": "Node.js / npm · 官方安装入口", "source": "https://github.com/nocobase/nocobase#readme", "verified": true } ], "display_tags": [ "浏览器 Agent", "网页任务自动化", "结构化数据提取", "节点式流程编排", "开源工具" ], "eyebrow": "客户沟通与团队运营", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要客户沟通与团队运营能力，并使用 local_cli的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability." }, { "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 社区证据显示该项目存在一个安全/权限相关的待验证问题：REST API: Multiple select field not working in edit form", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_36b6b605781f4652849d06443cd76da9 | https://github.com/nocobase/nocobase/issues/8836 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：REST API: Multiple select field not working in edit form", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0-alpha.33", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_71fc97aec74e43618fab9e19d0aa9a9f | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.33 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v2.1.0-alpha.33", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0-beta.30", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_3eea74dae9c548fc8058563df21058d3 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.30 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v2.1.0-beta.30", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.0.51", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_06f3ce01049e42f586931cf6e9a46335 | https://github.com/nocobase/nocobase/releases/tag/v2.0.51 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v2.0.51", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.1.0-alpha.32", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_7055255c88f94ecc84dfc5c09fc6c3a3 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.32 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v2.1.0-alpha.32", "user_impact": "可能影响升级、迁移或版本选择。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.1.0-beta.29", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_c4b7dfdc1a164f5cb82fec5622b80342 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.29 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v2.1.0-beta.29", "user_impact": "可能影响升级、迁移或版本选择。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:306829688 | https://github.com/nocobase/nocobase | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:306829688 | https://github.com/nocobase/nocobase | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | github_repo:306829688 | https://github.com/nocobase/nocobase | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "No sandbox install has been executed yet; downstream must verify before user use.", "category": "安全/权限坑", "evidence": [ "risks.safety_notes | github_repo:306829688 | https://github.com/nocobase/nocobase | No sandbox install has been executed yet; downstream must verify before user use." ], "severity": "medium", "suggested_check": "转成明确权限清单和安全审查提示。", "title": "存在安全注意事项", "user_impact": "用户安装前需要知道权限边界和敏感操作。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | github_repo:306829688 | https://github.com/nocobase/nocobase | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.52", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_1ca2b2aac82447ea8ca5b5536fff978e | https://github.com/nocobase/nocobase/releases/tag/v2.0.52 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v2.0.52", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0-alpha.31", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_7a2bc590f0974b79880f86db553b3a2e | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.31 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v2.1.0-alpha.31", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0-beta.27", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_43d1bbbbee81474cb8e2e4f722fdb398 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.27 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v2.1.0-beta.27", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0-beta.32", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_31e3065c9e884205a29f181cbbc50458 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.32 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v2.1.0-beta.32", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "issue_or_pr_quality=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:306829688 | https://github.com/nocobase/nocobase | issue_or_pr_quality=unknown" ], "severity": "low", "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。", "title": "issue/PR 响应质量未知", "user_impact": "用户无法判断遇到问题后是否有人维护。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 17 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：REST API: Multiple select field not working in edit form。", "title": "踩坑日志" }, "snapshot": { "contributors": 103, "forks": 2596, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 22374 }, "source_url": "https://github.com/nocobase/nocobase", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.", "title": "nocobase 能力包", "trial_prompt": "# nocobase - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for nocobase/nocobase.\n\nProject:\n- Name: nocobase\n- Repository: https://github.com/nocobase/nocobase\n- Summary: NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. overview: Overview. Produce one small intermediate artifact and wait for confirmation.\n2. system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n3. deployment: Deployment. Produce one small intermediate artifact and wait for confirmation.\n4. plugin-system: Plugin System. Produce one small intermediate artifact and wait for confirmation.\n5. data-modeling: Data Modeling. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/nocobase/nocobase\n- https://github.com/nocobase/nocobase#readme\n- docs/docs/de/ai-employees/advanced/skill.md\n- docs/docs/es/ai-employees/advanced/skill.md\n- docs/docs/fr/ai-employees/advanced/skill.md\n- docs/docs/ja/ai-employees/advanced/skill.md\n- docs/docs/ko/ai-employees/advanced/skill.md\n- docs/docs/pt/ai-employees/advanced/skill.md\n- docs/docs/ru/ai-employees/advanced/skill.md\n- README.md\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n", "voices": [ { "body": "来源平台：github。github/github_issue: REST API: Multiple select field not working in edit form（https://github.com/nocobase/nocobase/issues/8836）；github/github_release: v2.0.52（https://github.com/nocobase/nocobase/releases/tag/v2.0.52）；github/github_release: v2.1.0-beta.32（https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.32）；github/github_release: v2.1.0-beta.30（https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.30）；github/github_release: v2.1.0-alpha.33（https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.33）；github/github_release: v2.1.0-alpha.32（https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.32）；github/github_release: v2.1.0-beta.29（https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.29）；github/github_release: v2.0.51（https://github.com/nocobase/nocobase/releases/tag/v2.0.51）；github/github_release: v2.1.0-beta.27（https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.27）；github/github_release: v2.1.0-alpha.31（https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.31）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "REST API: Multiple select field not working in edit form", "url": "https://github.com/nocobase/nocobase/issues/8836" }, { "kind": "github_release", "source": "github", "title": "v2.0.52", "url": "https://github.com/nocobase/nocobase/releases/tag/v2.0.52" }, { "kind": "github_release", "source": "github", "title": "v2.1.0-beta.32", "url": "https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.32" }, { "kind": "github_release", "source": "github", "title": "v2.1.0-beta.30", "url": "https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.30" }, { "kind": "github_release", "source": "github", "title": "v2.1.0-alpha.33", "url": "https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.33" }, { "kind": "github_release", "source": "github", "title": "v2.1.0-alpha.32", "url": "https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.32" }, { "kind": "github_release", "source": "github", "title": "v2.1.0-beta.29", "url": "https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.29" }, { "kind": "github_release", "source": "github", "title": "v2.0.51", "url": "https://github.com/nocobase/nocobase/releases/tag/v2.0.51" }, { "kind": "github_release", "source": "github", "title": "v2.1.0-beta.27", "url": "https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.27" }, { "kind": "github_release", "source": "github", "title": "v2.1.0-alpha.31", "url": "https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.31" } ], "status": "已收录 10 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "客户沟通与团队运营", "desc": "NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.", "effort": "安装已验证", "forks": 2596, "icon": "users", "name": "nocobase 能力包", "risk": "可发布", "slug": "nocobase", "stars": 22374, "tags": [ "浏览器 Agent", "网页任务自动化", "结构化数据提取", "节点式流程编排", "开源工具" ], "thumb": "gray", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/nocobase/nocobase 项目说明书\n\n生成时间：2026-05-18 02:07:18 UTC\n\n## 目录\n\n- [Overview](#overview)\n- [System Architecture](#system-architecture)\n- [Deployment](#deployment)\n- [Plugin System](#plugin-system)\n- [Data Modeling](#data-modeling)\n- [Interface Builder](#interface-builder)\n- [Workflow Engine](#workflow-engine)\n- [Authentication and Permissions](#authentication-permissions)\n- [AI Integration](#ai-integration)\n- [File Storage](#file-storage)\n- [Cluster Mode](#cluster-mode)\n- [Plugin Development](#plugin-development)\n\n\n\n## Overview\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [Plugin System](#plugin-system), [AI Integration](#ai-integration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/nocobase/nocobase/blob/main/README.md)\n- [docs/README.md](https://github.com/nocobase/nocobase/blob/main/docs/README.md)\n- [docs/docs/en/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/index.md)\n- [packages/core/client/src/schema-initializer/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-initializer/index.md)\n- [packages/core/client/src/schema-component/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/index.md)\n- [packages/core/flow-engine/src/flowSettings.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/flowSettings.ts)\n- [packages/core/client/src/variables/hooks/useBuiltinVariables.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/variables/hooks/useBuiltinVariables.ts)\n- [packages/plugins/@nocobase/plugin-mobile/src/client/pages/index.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-mobile/src/client/pages/index.md)\n- [packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/chatbox/stores/chat-messages.ts](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/chatbox/stores/chat-messages.ts)\n
\n\n# Overview\n\nNocoBase is an open-source **NoCode/LowCode platform** that enables users to build scalable business applications through a visual interface without writing code. It provides a comprehensive system for creating data models, designing user interfaces, configuring business workflows, and extending functionality through a plugin-based architecture.\n\n## Architecture Overview\n\nNocoBase follows a modern full-stack architecture with clear separation between client and server components. The platform is built on a plugin-based architecture that allows for flexible extension and customization.\n\n```mermaid\ngraph TD\n Client[\"Client (React)\"]\n Server[\"Server (Node.js)\"]\n Database[\"Database\"]\n Client --> Server\n Server --> Database\n \n subgraph Client\n UI[\"UI Components\"]\n Schema[\"Schema System\"]\n Variables[\"Variable System\"]\n PM[\"Plugin Manager\"]\n end\n \n subgraph Server\n API[\"API Layer\"]\n FlowEngine[\"Flow Engine\"]\n Plugins[\"Plugin System\"]\n end\n \n subgraph Plugins\n Mobile[\"Mobile Plugin\"]\n AI[\"AI Plugin\"]\n ThemeEditor[\"Theme Editor Plugin\"]\n end\n```\n\n### Core Components\n\n| Component | Description | Location |\n|-----------|-------------|----------|\n| Schema System | Declarative UI and data structure definition | `packages/core/client/src/schema-component/` |\n| Flow Engine | Business workflow execution engine | `packages/core/flow-engine/` |\n| Plugin Manager | Dynamic plugin loading and management | `packages/core/client/src/pm/` |\n| Variable System | Runtime variable resolution and context | `packages/core/client/src/variables/` |\n| Schema Initializer | Visual block insertion and configuration | `packages/core/client/src/schema-initializer/` |\n| Schema Settings | Configuration panel for schema blocks | `packages/core/client/src/schema-settings/` |\n\n资料来源：[packages/core/client/src/schema-component/index.md:1]()\n\n## Data Model Architecture\n\nNocoBase uses a schema-based approach for defining data models and user interfaces. Collections represent database tables, and fields define the structure of data entries.\n\n```mermaid\ngraph LR\n Collection[\"Collection
(Data Model)\"]\n Field[\"Field
(Column Definition)\"]\n Association[\"Association
(Relationship)\"]\n Schema[\"Schema
(UI Configuration)\"]\n \n Collection --> Field\n Collection --> Association\n Schema --> Collection\n```\n\nThe system supports multiple data types and associations, enabling complex business data modeling scenarios.\n\n资料来源：[packages/core/client/src/schema-component/antd/association-select/index.md:1]()\n\n## User Interface System\n\n### Schema Component Architecture\n\nThe UI in NocoBase is built using a **Schema-based Component System**. Each UI element is defined through a schema configuration that describes its type, properties, and behavior.\n\n#### Built-in Components\n\nNocoBase provides several built-in components ready for use:\n\n| Component | Purpose | Location |\n|-----------|---------|----------|\n| `GeneralSchemaDesigner` | Main schema designer wrapper | `packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx` |\n| `LinkageFilter` | Frontend linkage rules and condition configuration | `packages/core/client/src/schema-component/antd/linkageFilter/index.md` |\n| `AssociationSelect` | Data selection linked to collections and fields | `packages/core/client/src/schema-component/antd/association-select/index.md` |\n\n#### Schema Designer Features\n\nThe schema designer provides visual editing capabilities for:\n\n- **Drag and Drop**: Rearrange schema blocks within the interface\n- **Designable Toggle**: Switch between view and edit modes\n- **Initializer Integration**: Insert new schema blocks dynamically\n- **Settings Panel**: Configure properties of selected blocks\n\n```mermaid\ngraph TD\n User[\"User\"] --> Designer[\"Schema Designer\"]\n Designer --> Drag[\"Drag & Drop\"]\n Designer --> Initializer[\"Schema Initializer\"]\n Designer --> Settings[\"Schema Settings\"]\n \n Drag --> Block1[\"Block 1\"]\n Drag --> Block2[\"Block 2\"]\n Initializer --> Block3[\"New Block\"]\n Settings --> Config[\"Configuration\"]\n```\n\n资料来源：[packages/core/client/src/schema-component/index.md:1]()\n\n### Schema Initializer\n\nThe Schema Initializer enables dynamic insertion of schema blocks into the design canvas. It supports:\n\n- **Built-in Types**: Pre-configured component templates\n- **Dynamic Visibility**: Show/hide items based on conditions\n- **Dynamic Children**: Load child items on demand\n- **Insert Schema**: Insert complete schema structures including actions and form items\n\n资料来源：[packages/core/client/src/schema-initializer/index.md:1]()\n\n## Variable System\n\nVariables provide dynamic data context for formulas, conditions, and display values throughout the application. NocoBase includes a comprehensive built-in variable system.\n\n### Built-in Variables\n\n| Variable | Description | Type |\n|----------|-------------|------|\n| `$date` | Current date (deprecated, use `$nDate`) | DateTime |\n| `$nDate` | Current date in ISO format | DateTime |\n| `$nExactDate` | Exact current datetime | DateTime |\n| `$system` | System context with `now()` function (deprecated) | Object |\n| `$nRole` | Current user's role information | Object |\n| `$nUser` | Current authenticated user details | Object |\n| `currentTime` | Current timestamp (deprecated) | String |\n| URL Parameters | Query string variables | Various |\n\n### Variable Resolution Flow\n\n```mermaid\ngraph LR\n Request[\"Request Context\"]\n Resolver[\"Variable Resolver\"]\n Context[\"Context Variables\"]\n Output[\"Resolved Values\"]\n \n Request --> Resolver\n Context --> Resolver\n Resolver --> Output\n```\n\nVariables are evaluated at runtime and support context-dependent values from:\n\n- Current user session\n- Current role permissions\n- URL query parameters\n- Environment variables\n- Date/time calculations\n\n资料来源：[packages/core/client/src/variables/hooks/useBuiltinVariables.ts:1]()\n\n## Plugin System\n\nNocoBase adopts a **plugin-first architecture**. All features are implemented as plugins that can be dynamically loaded, enabled, disabled, and configured.\n\n### Plugin Manager\n\nThe Plugin Manager (`pm`) handles plugin lifecycle operations:\n\n| Operation | Description |\n|-----------|-------------|\n| Install | Add new plugin to the system |\n| Uninstall | Remove plugin from the system |\n| Enable | Activate plugin functionality |\n| Disable | Deactivate plugin without removal |\n| Configure | Manage plugin-specific settings |\n\n```mermaid\ngraph TD\n PM[\"Plugin Manager\"]\n Store[\"Plugin Store\"]\n Loader[\"Plugin Loader\"]\n Registry[\"Plugin Registry\"]\n \n PM --> Store\n PM --> Loader\n PM --> Registry\n Loader --> Plugin[\"Plugin Instance\"]\n Registry --> Plugin\n```\n\n### Plugin Detail View\n\nEach plugin displays comprehensive information:\n\n- **Package Name**: Unique plugin identifier\n- **Version**: Semantic version number\n- **Description**: Plugin functionality summary\n- **Homepage**: Documentation or project URL\n- **Author**: Plugin maintainer information\n- **License**: Legal usage terms\n- **Dependencies**: Compatibility check with core system\n\n资料来源：[packages/core/client/src/pm/PluginDetail.tsx:1]()\n\n### Available Plugin Categories\n\n| Category | Examples | Purpose |\n|----------|----------|---------|\n| Mobile | `@nocobase/plugin-mobile` | Mobile-specific UI and navigation |\n| AI | `@nocobase/plugin-ai` | AI-powered features and assistants |\n| Theme | `@nocobase/plugin-theme-editor` | Visual theme customization |\n| Workflow | Flow Engine | Business process automation |\n\n## Mobile Support\n\nThe Mobile plugin provides responsive interfaces and navigation optimized for mobile devices.\n\n### Desktop Mode\n\nWhen accessing mobile pages from a desktop browser, the `DesktopMode` component renders a responsive wrapper:\n\n```tsx\n\n \n\n```\n\n### Page Types\n\n| Page Type | Description |\n|-----------|-------------|\n| Home Page | Default landing page; redirects to first route if not configured |\n| NotFound Page | 404 error page for unmatched routes |\n| Custom Pages | User-defined pages with custom components |\n\n#### Home Page Modes\n\n- **Basic**: Default empty home page\n- **Custom Home**: User-defined home page component\n- **No Routes**: Configuration without any routes\n\n资料来源：[packages/plugins/@nocobase/plugin-mobile/src/client/pages/index.md:1]()\n\n### Mobile Navigation\n\nThe `MobileTabBar` component provides tab-based navigation with `Bar.Item` elements:\n\n```mermaid\ngraph LR\n TabBar[\"MobileTabBar\"]\n BarItem[\"Bar.Item\"]\n Link[\"Link Component\"]\n \n TabBar --> BarItem\n BarItem --> Link\n Link --> Route[\"Route Path\"]\n```\n\n#### Link Types\n\n| Type | Description |\n|------|-------------|\n| Inner Link | Navigate to internal application routes |\n| Outer Page | Link to external URLs |\n| Selected | Display currently active/selected state |\n\n资料来源：[packages/plugins/@nocobase/plugin-mobile/src/client/mobile-layout/index.md:1]()\n\n## Workflow Engine\n\nThe Flow Engine (`flow-engine`) provides a visual workflow execution environment for business process automation.\n\n### Flow Settings\n\nFlows can be configured with custom interfaces and behaviors:\n\n| Setting | Description |\n|---------|-------------|\n| `title` | Display name for the flow |\n| `description` | Human-readable flow description |\n| `footer` | Customizable footer with buttons |\n| `onCancel` | Callback when cancel is triggered |\n| `onSaved` | Callback when configuration is saved |\n\n#### Footer Configuration Options\n\n- **Default**: Use system-provided buttons\n- **Wrap**: Add custom content around origin buttons\n- **Functional**: Completely replace with custom composition\n- **Hidden**: Set to `null` to hide footer entirely\n\n```typescript\n// Wrap existing buttons\nfooter: (originNode, { OkBtn, CancelBtn }) => (\n
\n Additional info\n {originNode}\n
\n)\n\n// Hide footer\nfooter: null\n```\n\n资料来源：[packages/core/flow-engine/src/flowSettings.ts:1]()\n\n## AI Integration\n\nThe AI plugin (`@nocobase/plugin-ai`) extends NocoBase with artificial intelligence capabilities.\n\n### Chat Messages Store\n\nAI features utilize a state management system for chat interactions:\n\n```mermaid\ngraph TD\n ChatStore[\"ChatMessages Store\"]\n Messages[\"messages[]\"]\n Attachments[\"attachments[]\"]\n Context[\"contextItems[]\"]\n System[\"systemMessage\"]\n \n ChatStore --> Messages\n ChatStore --> Attachments\n ChatStore --> Context\n ChatStore --> System\n```\n\n#### Store Actions\n\n| Action | Purpose |\n|--------|---------|\n| `setMessages` | Replace all messages |\n| `addMessage` | Append single message |\n| `addMessages` | Append multiple messages |\n| `updateLastMessage` | Modify most recent message |\n| `removeMessage` | Delete message by key |\n| `setAttachments` | Update file attachments |\n| `addContextItems` | Add context items with deduplication |\n| `setSystemMessage` | Update system prompt |\n\n#### Datasource Management\n\nAI features support multiple data sources with configuration:\n\n- **Collection**: Target collection reference\n- **Limit**: Maximum records to retrieve\n- **Description**: Data source purpose documentation\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/chatbox/stores/chat-messages.ts:1]()\n\n### Documentation Tools\n\nThe AI plugin includes tools for reading and navigating documentation:\n\n```mermaid\ngraph LR\n Input[\"Module Key Input\"]\n Parser[\"Path Parser\"]\n Resolver[\"Path Resolver\"]\n Output[\"File/Directory Content\"]\n \n Input --> Parser\n Parser --> Resolver\n Resolver --> Output\n```\n\nKey functions:\n\n- `normalizeModuleKey`: Validates and normalizes module identifiers\n- `resolveDocPath`: Maps module keys to absolute file paths\n- Documentation entries include both files and subdirectories with hierarchical structure\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/tools/docs.ts:1]()\n\n## Frontend Utilities\n\n### CSS Module Resolution\n\nUtility functions support frontend asset handling:\n\n| Function | Purpose |\n|----------|---------|\n| `isCssFile(url)` | Determines if a URL points to a CSS file |\n\nThe function handles:\n\n- Query string parameters (e.g., `style.css?v=123`)\n- Hash fragments (e.g., `style.css#section`)\n- Extension-based file type detection\n\n```typescript\nisCssFile('style.css') // true\nisCssFile('style.css?v=123') // true\nisCssFile('style.css#section') // true\nisCssFile('script.js') // false\n```\n\n资料来源：[packages/core/flow-engine/src/utils/resolveModuleUrl.ts:1]()\n\n## Technology Stack\n\n| Layer | Technology | Purpose |\n|-------|------------|---------|\n| Frontend Framework | React | UI component rendering |\n| State Management | Zustand | Lightweight state management |\n| UI Library | Ant Design | Pre-built component library |\n| Backend Runtime | Node.js | Server-side execution |\n| Database | Multiple (via ORM) | Data persistence |\n| Package Manager | Monorepo (npm workspaces) | Code organization |\n\n## Key Design Principles\n\n1. **Schema-Driven**: All configurations are declarative schema definitions\n2. **Plugin-First**: Every feature is a plugin with isolated scope\n3. **Visual Configuration**: No-code interfaces for common operations\n4. **Code Extension**: Low-code escape hatch for custom requirements\n5. **Dynamic Loading**: Runtime plugin activation without full reload\n\n## Documentation Structure\n\nThe NocoBase documentation is organized as follows:\n\n```\ndocs/\n├── README.md # Documentation index\n├── docs/\n│ └── en/ # English documentation\n│ └── index.md # Entry point\n├── packages/\n│ └── plugins/ # Plugin-specific docs\n└── README.md # Root documentation\n```\n\n资料来源：[docs/README.md:1]()\n\n## Getting Started\n\nTo begin working with NocoBase:\n\n1. **Understand the Architecture**: Familiarize yourself with the plugin-based structure\n2. **Define Data Models**: Create collections and configure fields in the admin interface\n3. **Design UI Schemas**: Use the schema designer to build application interfaces\n4. **Configure Workflows**: Set up automation using the flow engine\n5. **Extend with Plugins**: Add custom functionality through the plugin system\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Overview](#overview), [Plugin System](#plugin-system), [Deployment](#deployment)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/nocobase/nocobase/blob/main/README.md)\n- [packages/plugins/@nocobase/plugin-data-source-main/README.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-data-source-main/README.md)\n- [packages/plugins/@nocobase/plugin-form-drafts/README.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-form-drafts/README.md)\n- [packages/plugins/@nocobase/plugin-audit-logs/README.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-audit-logs/README.md)\n- [packages/plugins/@nocobase/plugin-mobile/README.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-mobile/README.md)\n
\n\n# System Architecture\n\n## Overview\n\nNocoBase is an open-source AI + no-code platform designed for building business systems rapidly. The platform adopts a **data model-driven architecture** that separates data structure from user interface, enabling unlimited possibilities for application development. 资料来源：[README.md:1]()\n\nThe architecture is built with **plugin-first extensibility** at its core, allowing developers and AI agents to extend functionality without modifying the core codebase. This design philosophy enables organizations to adapt quickly to changing business requirements while maintaining system stability and performance. 资料来源：[packages/plugins/@nocobase/plugin-data-source-main/README.md:1]()\n\n## Core Architectural Principles\n\n### Data Model-Driven Approach\n\nUnlike traditional form or table-driven platforms, NocoBase implements a data model-driven approach that decouples UI and data structure completely. This architectural decision provides several key advantages:\n\n| Characteristic | Traditional Platforms | NocoBase Architecture |\n|----------------|----------------------|----------------------|\n| UI-Data Coupling | Tightly coupled | Fully decoupled |\n| Interface Flexibility | Limited to table/form views | Unlimited block types |\n| Data Source Support | Main database only | Main DB, external DBs, third-party APIs |\n| Multiple Views | One view per entity | Multiple blocks for same table/record |\n\n资料来源：[packages/plugins/@nocobase/plugin-form-drafts/README.md:1-15]()\n\n### Plugin-Based Extensibility\n\nThe entire NocoBase system is constructed as a collection of plugins. This modular architecture allows:\n\n- **Selective Feature Loading**: Only required plugins are loaded, reducing footprint\n- **Independent Updates**: Plugins can be updated without affecting core functionality\n- **Hot Module Replacement**: Plugins can be enabled/disabled at runtime\n- **AI Integration**: AI employees can programmatically interact with any plugin\n\n```graph TD\n A[NocoBase Core] --> B[Plugin System]\n B --> C[Data Source Plugins]\n B --> D[UI Block Plugins]\n B --> E[Workflow Plugins]\n B --> F[AI Agent Plugins]\n C --> G[Main Database]\n C --> H[External Databases]\n C --> I[Third-party APIs]\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-data-source-main/README.md:1-10]()\n\n## System Components\n\n### Plugin Categories\n\nNocoBase organizes its functionality into distinct plugin categories based on responsibility:\n\n| Category | Purpose | Example Plugins |\n|----------|---------|-----------------|\n| Data Management | Handle data operations and storage | `plugin-data-source-main` |\n| User Interface | Provide UI components and blocks | `plugin-mobile`, `plugin-block-workbench` |\n| Workflow Automation | Manage business processes | `plugin-workflow-manual`, `plugin-workflow-notification` |\n| System Utilities | Core system features | `plugin-audit-logs`, `plugin-verification` |\n| AI Integration | Enable AI capabilities | `plugin-ai` |\n\n### Database Layer\n\nThe database layer in NocoBase supports multiple data source types through a unified abstraction:\n\n- **Main Database**: Primary storage engine (configurable type)\n- **External Databases**: Direct connections to external SQL databases\n- **Third-party APIs**: REST/GraphQL API integrations as data sources\n\n资料来源：[packages/plugins/@nocobase/plugin-data-source-main/README.md:1-12]()\n\n```graph TD\n A[Application Layer] --> B[Data Source Abstraction]\n B --> C[Main Database Engine]\n B --> D[External DB Connectors]\n B --> E[API Connectors]\n C --> F[SQL Translation Layer]\n D --> F\n E --> F\n F --> G[Query Optimization]\n```\n\n### User Interface Architecture\n\nNocoBase provides a flexible UI system that supports both desktop and mobile clients:\n\n#### Desktop Client\n\nThe desktop client (`packages/core/client`) implements a schema-driven UI system where:\n\n- Components are defined as schemas\n- UI blocks are composed declaratively\n- Schema settings control component behavior\n\n资料来源：[packages/plugins/@nocobase/plugin-mobile/README.md:1-8]()\n\n#### Mobile Client\n\nThe mobile plugin provides:\n\n- Mobile-optimized page layouts\n- Responsive design support\n- Native-like navigation patterns\n- Mobile-specific UI components\n\n```graph TD\n A[Client Request] --> B{Router}\n B -->|Desktop| C[Desktop UI Renderer]\n B -->|Mobile| D[Mobile UI Renderer]\n C --> E[Schema Component Tree]\n D --> F[Mobile Page Layouts]\n E --> G[Block Designer]\n F --> G\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-mobile/README.md:1-15]()\n\n## Workflow System Architecture\n\n### Plugin-Based Workflows\n\nNocoBase implements workflows as plugins, enabling:\n\n- **Manual Triggers**: User-initiated workflow execution\n- **Automated Triggers**: Event-based workflow activation\n- **Notification System**: Multi-channel alert delivery\n- **Dynamic Calculation**: Runtime computation within workflows\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow-manual/README.md:1-10]()\n\n### Workflow Components\n\n| Component | Function | Plugin |\n|-----------|----------|--------|\n| Trigger | Initiates workflow execution | `plugin-workflow-manual` |\n| Actions | Perform operations | Core system |\n| Conditions | Control flow logic | Core system |\n| Notifications | Send alerts | `plugin-workflow-notification` |\n| Calculations | Compute values | `plugin-workflow-dynamic-calculation` |\n\n```graph TD\n A[Workflow Start] --> B{Trigger Type}\n B -->|Manual| C[User Action]\n B -->|Automated| D[Event Listener]\n C --> E[Condition Evaluation]\n D --> E\n E -->|True| F[Execute Actions]\n E -->|False| G[Skip Workflow]\n F --> H{Notification?}\n H -->|Yes| I[Send Notification]\n H -->|No| J[Continue Actions]\n I --> K[Workflow Complete]\n J --> K\n G --> K\n```\n\n## Audit and Logging Architecture\n\nThe audit logs plugin (`plugin-audit-logs`) captures comprehensive system activity:\n\n- **Data Changes**: All database modifications\n- **User Actions**: User interactions with the system\n- **System Events**: Server-side operations\n- **Access Patterns**: Authentication and authorization events\n\n资料来源：[packages/plugins/@nocobase/plugin-audit-logs/README.md:1-12]()\n\n## AI Integration Architecture\n\nNocoBase integrates AI capabilities through a dedicated AI plugin system:\n\n### AI Employee System\n\nUnlike standalone AI implementations, NocoBase allows embedding AI capabilities seamlessly into:\n\n- **Interfaces**: AI-powered form components and data displays\n- **Workflows**: AI-driven decision making and automation\n- **Business Logic**: Custom AI agents for domain-specific tasks\n- **Data Operations**: Intelligent data processing and analysis\n\n```graph TD\n A[AI Plugin System] --> B[AI Employees]\n A --> C[Prompt Templates]\n A --> D[Model Adapters]\n B --> E[Business Interfaces]\n B --> F[Workflow Integration]\n B --> G[Data Processing]\n C --> H[System Context]\n D --> I[LLM Providers]\n E --> J[User Interface]\n F --> K[Automation Engine]\n G --> L[Data Layer]\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-data-source-main/README.md:1-8]()\n\n## Extensibility Patterns\n\n### Plugin Development\n\nDevelopers can extend NocoBase by creating custom plugins:\n\n1. **Plugin Structure**: Each plugin is a self-contained module\n2. **Dependency Management**: Plugins can depend on other plugins\n3. **Lifecycle Hooks**: Initialization, activation, and deactivation\n4. **Schema Extension**: Custom schema types and components\n\n```graph TD\n A[Custom Plugin] --> B[Plugin Manifest]\n A --> C[Server Code]\n A --> D[Client Code]\n A --> E[Resources]\n B --> F[Plugin Metadata]\n B --> G[Dependencies]\n C --> H[Database Models]\n C --> I[API Routes]\n C --> J[Services]\n D --> K[UI Components]\n D --> L[Schema Definitions]\n D --> M[State Management]\n```\n\n### Schema-Driven UI\n\nThe schema system allows declarative UI definition:\n\n| Schema Type | Purpose | Extensibility |\n|-------------|---------|---------------|\n| `Field` | Data display/input | Custom field types |\n| `Block` | Layout containers | Custom block types |\n| `Action` | User interactions | Custom action handlers |\n| `Selector` | Data filtering | Custom filter types |\n\n## System Requirements and Deployment\n\n### Database Support\n\nNocoBase supports multiple database engines:\n\n| Database | Status | Notes |\n|----------|--------|-------|\n| PostgreSQL | Full Support | Recommended for production |\n| MySQL | Full Support | Wide compatibility |\n| SQLite | Development Only | Limited concurrent access |\n| Others | Via External DB Plugin | API-based connectivity |\n\n### Runtime Requirements\n\n- **Node.js**: v18+ required\n- **Package Manager**: npm or yarn\n- **Memory**: Minimum 2GB RAM for development\n- **Storage**: Varies by database and data volume\n\n## Architectural Benefits\n\n### Scalability\n\n- **Horizontal Scaling**: Stateless server design enables load balancing\n- **Vertical Scaling**: Efficient resource utilization supports larger deployments\n- **Plugin Isolation**: Prevents resource contention between features\n\n### Maintainability\n\n- **Modular Design**: Each plugin can be developed and tested independently\n- **Clear Boundaries**: Well-defined interfaces between components\n- **Version Management**: Plugins maintain their own version history\n\n### Flexibility\n\n- **Multiple Data Sources**: Connect to various databases and APIs\n- **Custom UI**: Schema-driven interface allows infinite combinations\n- **AI Integration**: Built-in support for AI-augmented functionality\n\n## Summary\n\nNocoBase's system architecture is designed around three fundamental principles:\n\n1. **Data Model Centrality**: The data model drives all application behavior, not forms or tables\n2. **Plugin-Based Extensibility**: Every feature is a plugin that can be added, removed, or customized\n3. **AI Integration**: AI capabilities are first-class citizens integrated throughout the system\n\nThis architecture enables organizations to build sophisticated business applications rapidly while maintaining the flexibility to adapt to changing requirements. The separation of concerns between data, logic, and presentation layers ensures that changes in one area do not cascade into others, resulting in a maintainable and scalable system.\n\n---\n\n\n\n## Deployment\n\n### 相关页面\n\n相关主题：[Cluster Mode](#cluster-mode), [System Architecture](#system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [docker-compose.yml](https://github.com/nocobase/nocobase/blob/main/docker-compose.yml)\n- [Dockerfile](https://github.com/nocobase/nocobase/blob/main/Dockerfile)\n- [docker/nocobase/Dockerfile](https://github.com/nocobase/nocobase/blob/main/docker/nocobase/Dockerfile)\n- [docker/app-postgres/docker-compose.yml](https://github.com/nocobase/nocobase/blob/main/docker/app-postgres/docker-compose.yml)\n- [docker/app-mysql/docker-compose.yml](https://github.com/nocobase/nocobase/blob/main/docker/app-mysql/docker-compose.yml)\n- [docker/app-mariadb/docker-compose.yml](https://github.com/nocobase/nocobase/blob/main/docker/app-mariadb/docker-compose.yml)\n- [docker/app-sqlite/docker-compose.yml](https://github.com/nocobase/nocobase/blob/main/docker/app-sqlite/docker-compose.yml)\n- [docs/docs/en/get-started/deployment/production.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/get-started/deployment/production.md)\n- [docs/docs/en/get-started/installation/docker.mdx](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/get-started/installation/docker.mdx)\n
\n\n# Deployment\n\nNocoBase provides flexible deployment options to accommodate various infrastructure requirements and operational preferences. The platform supports containerized deployment via Docker, traditional server deployment, and development-focused installations.\n\n## Overview\n\nNocoBase is designed as a headless CMS with an API-first architecture. The application server exposes REST and GraphQL APIs, while the admin client is a separate SPA (Single Page Application). This separation allows for flexible deployment strategies where the server and client can be scaled independently.\n\n## Deployment Methods\n\n### Docker Deployment (Recommended)\n\nDocker deployment is the recommended approach for production environments. It provides the easiest setup with no-code requirements and simplified maintenance through image updates.\n\n**Minimal Quick Start:**\n```bash\nnpm install -g @nocobase/cli@beta\nmkdir my-nocobase && cd my-nocobase\nnb init --ui\n```\n\n资料来源：[README.md:8-13]()\n\n### Database Support\n\nNocoBase supports multiple database backends. Each database type has a dedicated Docker Compose configuration:\n\n| Database | Configuration File | Use Case |\n|------------|-------------------------------------------|----------------------------------|\n| PostgreSQL | `docker/app-postgres/docker-compose.yml` | Production, enterprise scale |\n| MySQL | `docker/app-mysql/docker-compose.yml` | Production, wide compatibility |\n| MariaDB | `docker/app-mariadb/docker-compose.yml` | Production, MySQL fork |\n| SQLite | `docker/app-sqlite/docker-compose.yml` | Development, small deployments |\n\n资料来源：[docker/app-postgres/docker-compose.yml](https://github.com/nocobase/nocobase/blob/main/docker/app-postgres/docker-compose.yml), [docker/app-mysql/docker-compose.yml](https://github.com/nocobase/nocobase/blob/main/docker/app-mysql/docker-compose.yml)\n\n### Docker Architecture\n\n```mermaid\ngraph TD\n A[Client Browser] -->|HTTPS| B[NocoBase Application]\n B -->|API Requests| C[API Server :13000]\n B -->|Static Assets| D[Admin SPA :13000]\n C --> E[(PostgreSQL
MySQL
MariaDB)]\n C --> F[(SQLite)]\n E --> G[Uploaded Files
/uploads]\n F --> G\n```\n\n## Docker Configuration\n\n### Main Dockerfile\n\nThe primary Dockerfile (`docker/nocobase/Dockerfile`) builds the NocoBase application image. It uses a multi-stage build process to:\n\n1. Install dependencies\n2. Build the application\n3. Create an optimized production image\n\n### Environment Variables\n\nKey environment variables for Docker deployment:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `APP_KEY` | Application encryption key | Generated on first run |\n| `DB_DIALECT` | Database type (postgres, mysql, sqlite) | postgres |\n| `DB_HOST` | Database host | db |\n| `DB_PORT` | Database port | 5432 / 3306 |\n| `DB_DATABASE` | Database name | nocobase |\n| `DB_USER` | Database username | nocobase |\n| `DB_PASSWORD` | Database password | nocobase |\n| `API_PORT` | API server port | 13000 |\n\n### Docker Compose Services\n\nTypical Docker Compose configuration includes:\n\n```yaml\nservices:\n app:\n image: nocobase/app:latest\n ports:\n - \"13000:13000\"\n environment:\n - DB_DIALECT=postgres\n - DB_HOST=db\n - DB_PORT=5432\n volumes:\n - ./uploads:/app/uploads\n depends_on:\n - db\n\n db:\n image: postgres:15\n environment:\n - POSTGRES_DB=nocobase\n - POSTGRES_USER=nocobase\n - POSTGRES_PASSWORD=nocobase\n volumes:\n - db_data:/var/lib/postgresql/data\n\nvolumes:\n db_data:\n```\n\n## Production Deployment\n\n### Prerequisites\n\nFor production deployments, ensure:\n\n1. **Reverse Proxy**: Configure nginx or similar for SSL termination\n2. **Database**: Use PostgreSQL or MySQL for production workloads\n3. **Storage**: Configure persistent storage for uploaded files\n4. **Environment**: Set secure `APP_KEY` in production\n\n### Deployment Checklist\n\n| Item | Priority | Description |\n|------|----------|-------------|\n| SSL Certificate | Required | Enable HTTPS for production |\n| Database Backup | Required | Configure automated backups |\n| APP_KEY Configuration | Required | Use unique, secure key |\n| Environment Variables | Required | Set production values |\n| Upload Storage | Required | Configure persistent storage |\n| Monitoring | Recommended | Set up application monitoring |\n| Log Management | Recommended | Configure centralized logging |\n\n资料来源：[docs/docs/en/get-started/deployment/production.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/get-started/deployment/production.md)\n\n### Production Reverse Proxy Configuration\n\n```nginx\nserver {\n listen 80;\n server_name your-domain.com;\n return 301 https://$server_name$request_uri;\n}\n\nserver {\n listen 443 ssl http2;\n server_name your-domain.com;\n\n ssl_certificate /path/to/cert.pem;\n ssl_certificate_key /path/to/key.pem;\n\n client_max_body_size 100M;\n\n location / {\n proxy_pass http://localhost:13000;\n proxy_http_version 1.1;\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection 'upgrade';\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_cache_bypass $http_upgrade;\n }\n\n location /uploads/ {\n alias /path/to/uploads/;\n expires 7d;\n add_header Cache-Control \"public, immutable\";\n }\n}\n```\n\n## Installation Methods Comparison\n\n| Method | Best For | Code Writing | Upgrade Process | Development |\n|--------|----------|--------------|-----------------|-------------|\n| Docker | Production, no-code | No | Pull image, restart | Limited |\n| create-nocobase-app | Business projects | Yes (low-code) | Rebuild project | Full |\n| Git Clone | Contributing, latest | Yes | Git pull | Full |\n\n资料来源：[README.md:18-33]()\n\n## Upgrading\n\n### Docker Upgrades\n\nFor Docker deployments, upgrading involves:\n\n```bash\n# Pull latest image\ndocker pull nocobase/app:latest\n\n# Restart container\ndocker-compose down\ndocker-compose up -d\n```\n\n### Database Migration\n\nNocoBase automatically runs database migrations on startup. Ensure:\n\n1. Database backup before upgrade\n2. Sufficient downtime window for migration\n3. Rollback plan if migration fails\n\n## File Structure Reference\n\n```\n├── docker-compose.yml # Main compose file\n├── Dockerfile # Legacy Dockerfile\n├── docker/\n│ ├── nocobase/\n│ │ └── Dockerfile # Modern app Dockerfile\n│ ├── app-postgres/\n│ │ └── docker-compose.yml\n│ ├── app-mysql/\n│ │ └── docker-compose.yml\n│ ├── app-mariadb/\n│ │ └── docker-compose.yml\n│ └── app-sqlite/\n│ └── docker-compose.yml\n└── uploads/ # User uploads directory\n```\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| Container won't start | Check environment variables and volume permissions |\n| Database connection failed | Verify DB_HOST, DB_PORT, and credentials |\n| File upload fails | Check uploads directory permissions and size limits |\n| Slow performance | Increase memory limits, enable caching |\n\n### Health Check\n\nNocoBase provides health check endpoint at the root path:\n\n```bash\ncurl http://localhost:13000/\n```\n\nA successful response indicates the application is running correctly.\n\n## Next Steps\n\n- [Installation Guide](https://docs.nocobase.com/welcome/getting-started/installation/docker-compose)\n- [Production Best Practices](https://docs.nocobase.com/welcome/getting-started/deployment/production)\n- [Plugin Development](https://docs.nocobase.com/development/server/plugins)\n\n---\n\n\n\n## Plugin System\n\n### 相关页面\n\n相关主题：[Plugin Development](#plugin-development), [Data Modeling](#data-modeling), [Workflow Engine](#workflow-engine)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/client/src/pm/PluginDetail.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginDetail.tsx)\n- [packages/core/client/src/pm/PluginManagerLink.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginManagerLink.tsx)\n- [packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx)\n- [packages/core/flow-engine/src/flowSettings.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/flowSettings.ts)\n- [packages/plugins/@nocobase/plugin-mobile/src/client/pages/index.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-mobile/src/client/pages/index.md)\n
\n\n# Plugin System\n\n## Overview\n\nNocoBase implements a modular plugin-based architecture that enables developers to extend core functionality without modifying the framework's source code. Plugins in NocoBase are self-contained packages that can add new features, customize existing behavior, and integrate with external services.\n\nThe plugin system provides a unified mechanism for both server-side and client-side extensions, allowing developers to hook into application lifecycle events, register custom components, define database schemas, and expose APIs.\n\n## Architecture\n\n```graph TD\n subgraph Core[\"NocoBase Core\"]\n PM[Plugin Manager]\n ER[Event Router]\n SM[Schema Manager]\n end\n \n subgraph PluginTypes[\"Plugin Types\"]\n SP[Server Plugin]\n CP[Client Plugin]\n FP[Full-Stack Plugin]\n end\n \n subgraph Lifecycle[\"Lifecycle Phases\"]\n LOAD[Load]\n BOOT[Boot]\n MOUNT[Mount]\n ACTIVE[Active]\n end\n \n PM -->|manages| SP\n PM -->|manages| CP\n PM -->|manages| FP\n SP --> LOAD\n CP --> LOAD\n FP --> LOAD\n LOAD --> BOOT\n BOOT --> MOUNT\n MOUNT --> ACTIVE\n```\n\n## Plugin Manager\n\nThe Plugin Manager (`PluginManagerLink.tsx`) handles the registration and lifecycle of all plugins within the application.\n\n### Core Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| `PluginDetail` | `packages/core/client/src/pm/PluginDetail.tsx` | Displays plugin metadata and dependency information |\n| `PluginManagerLink` | `packages/core/client/src/pm/PluginManagerLink.tsx` | Provides UI navigation to plugin settings |\n| `SchemaToolbar` | `packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx` | Enables schema-based plugin configuration |\n\n### Plugin Detail Display\n\nThe `PluginDetail` component renders comprehensive information about installed plugins:\n\n```tsx\n{plugin.packageName}\n • }>\n {plugin.version}\n\n\n```\n\n资料来源：[packages/core/client/src/pm/PluginDetail.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginDetail.tsx)\n\n### Dependencies Compatibility Check\n\nPlugins validate their dependencies through the compatibility checking system:\n\n```tsx\n{data?.data?.depsCompatible === false ? (\n \n {t('`dist/externalVersion.js` not found or failed to `require`. Please rebuild this plugin.')}\n \n) : (\n <>\n {!data?.data?.['isCompatible'] && (\n \n )}\n \n \n)}\n```\n\n资料来源：[packages/core/client/src/pm/PluginDetail.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginDetail.tsx)\n\n## Plugin Settings Management\n\n### Settings Menu Integration\n\nThe `PluginManagerLink` component integrates with the application settings menu:\n\n```tsx\nconst settingItems = useMemo(() => {\n const pinnedSettings = app.pluginSettingsManager\n .getPinnedSettings()\n .filter((setting) => setting.snippet !== false)\n .map((setting) => {\n return {\n key: setting.name,\n icon: setting.icon,\n label: setting.link ? (\n
window.open(setting.link)}>{compile(setting.title)}
\n ) : (\n {compile(setting.title)}\n ),\n };\n });\n // ...\n}, [app, t]);\n```\n\n资料来源：[packages/core/client/src/pm/PluginManagerLink.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginManagerLink.tsx)\n\n### Mobile Layout Handling\n\nSettings are hidden in mobile layouts:\n\n```tsx\nconst { isMobileLayout } = useMobileLayout();\n\nif (isMobileLayout) {\n return null;\n}\n```\n\n资料来源：[packages/core/client/src/pm/PluginManagerLink.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginManagerLink.tsx)\n\n## Schema-Based Plugin Extensions\n\n### Schema Designer Integration\n\nPlugins can extend the schema designer through the `GeneralSchemaDesigner` component:\n\n```tsx\n
\n \n {draggable && (\n \n \n \n )}\n {!disableInitializer &&\n (ctx?.InitializerComponent ? (\n \n ) : (\n ctx?.renderSchemaInitializer?.(initializerProps)\n ))}\n {schemaSettingsExists ? (\n schemaSettingsRender(contextValue)\n ) : (\n \n }\n {...schemaSettingsProps}\n >\n {props.children}\n \n )}\n \n
\n```\n\n资料来源：[packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx)\n\n### Toolbar Components\n\nThe schema toolbar provides a unified interface for plugin-defined tools:\n\n```tsx\n
\n \n {dragElement}\n {initializerElement}\n {settingsElement}\n \n
\n```\n\n资料来源：[packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx)\n\n## Plugin Lifecycle\n\n```graph LR\n A[Install] --> B[Load]\n B --> C[Configure]\n C --> D[Enable]\n D --> E[Boot]\n E --> F[Mount]\n F --> G[Disable]\n G --> H[Uninstall]\n```\n\n### Flow Settings Integration\n\nThe flow engine demonstrates plugin extensibility through settings:\n\n```tsx\nexport class FlowSettings {\n public components: Record = {};\n public scopes: Record = {};\n private antdComponentsLoaded = false;\n public enabled: boolean;\n #forceEnabled = false; // Force enable state\n}\n```\n\n资料来源：[packages/core/flow-engine/src/flowSettings.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/flowSettings.ts)\n\n### Modal Footer Customization\n\nPlugins can customize modal dialogs through the footer API:\n\n```tsx\nfooter?:\n | React.ReactNode\n | ((originNode: React.ReactNode, extra: { OkBtn: React.FC; CancelBtn: React.FC }) => React.ReactNode)\n | null;\n```\n\n资料来源：[packages/core/flow-engine/src/flowSettings.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/flowSettings.ts)\n\n## Client-Side Plugin Components\n\n### Page Components\n\nMobile plugins extend the application through page components:\n\n| Page Type | Description |\n|-----------|-------------|\n| Home Page | Default landing page with routing support |\n| NotFound Page | 404 error handling |\n| Desktop Mode | Desktop layout wrapper for mobile content |\n\n```tsx\n\n \n\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-mobile/src/client/desktop-mode/index.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-mobile/src/client/desktop-mode/index.md)\n\n### Schema Initializer Extensions\n\nPlugins extend schema initialization through:\n\n```tsx\n### Insert schema\n#### Basic\n\n#### Action\n\n#### FormItem\n\n```\n\n资料来源：[packages/core/client/src/schema-initializer/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-initializer/index.md)\n\n## Error Handling\n\n### Error Fallback Component\n\nPlugins integrate with the error handling system through the `ErrorFallback` component:\n\n```tsx\n\n \n {t('Feedback')}\n ,\n ,\n ]}\n />\n\n```\n\n资料来源：[packages/core/client/src/schema-component/antd/error-fallback/ErrorFallback.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/antd/error-fallback/ErrorFallback.tsx)\n\n## Plugin Package Structure\n\n| Directory/File | Purpose |\n|---------------|---------|\n| `src/server/` | Server-side plugin logic |\n| `src/client/` | Client-side React components |\n| `src/locale/` | Internationalization files |\n| `dist/` | Compiled distribution files |\n| `dist/externalVersion.js` | Version compatibility manifest |\n\n## Built-in Variables System\n\nPlugins can access built-in variables for dynamic content:\n\n| Variable | Context | Description |\n|----------|---------|-------------|\n| `$date` | datetimeCtx | Current date (deprecated) |\n| `$nExactDate` | exactDateTimeCtx | Precise timestamp |\n| `$nDate` | datetimeCtx | Current date |\n| `$system` | now | System time (deprecated) |\n| `currentTime` | () => dayjs | Legacy time variable |\n\n资料来源：[packages/core/client/src/variables/hooks/useBuiltinVariables.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/variables/hooks/useBuiltinVariables.ts)\n\n---\n\n\n\n## Data Modeling\n\n### 相关页面\n\n相关主题：[Plugin System](#plugin-system), [Interface Builder](#interface-builder), [Authentication and Permissions](#authentication-permissions)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/database/src/database.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/database/src/database.ts)\n- [packages/core/client/src/schema-templates/SchemaTemplateManagerProvider.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-templates/SchemaTemplateManagerProvider.tsx)\n- [packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx)\n- [packages/core/client/src/schema-component/antd/table/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/antd/table/index.md)\n- [packages/core/client/src/schema-settings/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-settings/index.md)\n
\n\n# Data Modeling\n\n## Overview\n\nData Modeling in NocoBase represents the foundational system for defining, organizing, and managing data structures within the application. It provides a comprehensive framework that enables users to create collections, define fields, establish relationships, and configure data sources through both programmatic APIs and user interfaces.\n\nThe data modeling system serves as the core abstraction layer that bridges the gap between application-level schema definitions and the underlying database infrastructure. It supports multiple database dialects and provides consistent data management capabilities across different storage backends.\n\n## Architecture\n\n### Core Database System\n\nThe `Database` class in NocoBase acts as the central orchestrator for all data modeling operations. It maintains several internal maps and registries that track collections, fields, models, and their relationships.\n\n```mermaid\ngraph TD\n A[Database] --> B[Collections Map]\n A --> C[Repositories Map]\n A --> D[Operators Map]\n A --> E[Model-Collection Maps]\n A --> F[Query Interface]\n A --> G[Dialect Layer]\n B --> H[Collection Metadata]\n E --> I[Model-Collection Binding]\n E --> J[Model Name Mapping]\n E --> K[Table Name Mapping]\n```\n\nThe database system initializes with the following key components:\n\n| Component | Type | Purpose |\n|-----------|------|---------|\n| `collections` | `Map` | Stores all registered collections by name |\n| `collectionsSort` | `Map` | Manages collection ordering/priority |\n| `repositories` | `Map` | Caches repository instances |\n| `modelCollection` | `Map` | Binds model classes to collections |\n| `modelNameCollectionMap` | `Map` | Lookup by model name |\n| `tableNameCollectionMap` | `Map` | Lookup by table name |\n| `pendingFields` | `Map` | Handles deferred field relations |\n| `interfaceManager` | `InterfaceManager` | Manages field type interfaces |\n\n资料来源：[packages/core/database/src/database.ts:26-45]()\n\n### Dialect Support\n\nThe database layer implements a dialect pattern through `BaseDialect` to support multiple database engines. The dialect system is registered statically and enables the framework to generate appropriate SQL syntax for different database backends.\n\n```mermaid\ngraph LR\n A[Database] --> B[Dialect Abstraction]\n B --> C[PostgreSQL]\n B --> D[MySQL]\n B --> E[SQLite]\n B --> F[Other Engines]\n \n G[SQL Identifier Quoting] --> C\n G --> D\n G --> E\n G --> F\n```\n\n资料来源：[packages/core/database/src/database.ts:47-59]()\n\n## Collections\n\nCollections are the primary units of data organization in NocoBase. They represent database tables and serve as containers for fields and their associated metadata.\n\n### Collection Management\n\nThe system provides multiple mechanisms for retrieving collections:\n\n| Method | Description |\n|--------|-------------|\n| `getCollection(name)` | Retrieve collection by exact name |\n| `getRepository(name)` | Get repository instance for collection |\n| `getModel(name)` | Access the ORM model |\n| `tableNameCollectionMap` | Lookup by database table name |\n\nThe collection system supports template-based creation through the `SchemaTemplateManagerProvider`, which enables reusable collection schemas:\n\n```typescript\ngetTemplatesByCollection: useCallback(\n (dataSource: string, collectionName: string) => {\n const parentCollections = getInheritCollections(collectionName, dataSource);\n const totalCollections = parentCollections.concat([collectionName]);\n const items = templates?.filter?.(\n (template) =>\n (template.dataSourceKey || DEFAULT_DATA_SOURCE_KEY) === dataSource &&\n totalCollections.includes(template.collectionName),\n );\n return items || [];\n },\n [getInheritCollections, templates],\n),\n```\n\n资料来源：[packages/core/client/src/schema-templates/SchemaTemplateManagerProvider.tsx:45-60]()\n\n### Collection Inheritance\n\nCollections support inheritance through the `InheritanceMap`, allowing child collections to derive schema from parent collections. This enables hierarchical data modeling where common fields are defined once and inherited by specialized collections.\n\n## Fields\n\nFields define the structure and behavior of data within collections. Each field has a type, validation rules, and UI configurations.\n\n### Field Types\n\nThe system includes built-in field types and supports custom interface extensions:\n\n| Category | Description |\n|----------|-------------|\n| Built-in Types | Standard field types provided by NocoBase |\n| Custom Interfaces | Extensible field type system |\n| Relation Fields | References to other collections |\n| Virtual Fields | Computed or derived fields |\n\nFields can be configured with dynamic visibility and child elements:\n\n```tsx\n// Dynamic visible & children\n// Supports conditional display and dynamic loading of child fields\n```\n\n资料来源：[packages/core/client/src/schema-settings/index.md:15-17]()\n\n### Field Configuration\n\nFields support various configuration options including:\n\n- Display names and descriptions\n- Default values\n- Validation rules\n- UI components and templates\n- Access control permissions\n\n## Schema System\n\nThe schema system provides a declarative way to define UI and data structures. It integrates with collections to render appropriate interface components.\n\n### Schema Designer\n\nThe `GeneralSchemaDesigner` component provides the visual interface for editing schema configurations:\n\n```mermaid\ngraph TD\n A[GeneralSchemaDesigner] --> B[Title Bar]\n A --> C[Drag Handler]\n A --> D[Initializer Component]\n A --> E[Schema Settings Dropdown]\n \n B --> F[Data Source Display]\n B --> G[Template Reference]\n \n D --> H[Dynamic Initializer]\n \n E --> I[Custom Settings Menu]\n```\n\n资料来源：[packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx:1-50]()\n\n### Schema Templates\n\nSchema templates enable reusable component configurations:\n\n| Method | Purpose |\n|--------|---------|\n| `getTemplateBySchemaId` | Find template by schema UID |\n| `getTemplateById` | Find template by key |\n| `getTemplatesByComponentName` | Filter by component type |\n| `getTemplatesByCollection` | Filter by collection with inheritance |\n\n资料来源：[packages/core/client/src/schema-templates/SchemaTemplateManagerProvider.tsx:32-44]()\n\n## Data Sources\n\nThe system supports multiple data sources, allowing connections to different databases within a single application.\n\n### Data Source Manager\n\nData sources are managed through a dedicated configuration system that handles:\n\n- Connection configuration\n- Dialect-specific settings\n- SQL identifier quoting rules\n- Cross-database relationships\n\nThe quoting rules vary by database type and must be respected when generating SQL:\n\n> Quote SQL identifiers according to each data source's database type specified in ``.\n> - Convert camelCase names to snake_case for databases that use underscore naming\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/ai-employees/prompts.ts:15-20]()\n\n## Table Components\n\nThe system provides multiple table rendering modes for different use cases:\n\n| Mode | Use Case |\n|------|----------|\n| `Table.Void` | Read-only display without interaction |\n| `Table.RowSelection` | Selectable rows for batch operations |\n| `Table.Array` | Editable array-based table |\n\n资料来源：[packages/core/client/src/schema-component/antd/table/index.md:1-14]()\n\n### Table Examples\n\nThe table component supports various configurations:\n\n- Basic void table display\n- Row selection with checkboxes\n- Array-based inline editing\n- Integrated action buttons\n\n## Workflow Integration\n\nData modeling integrates with the workflow engine through the `FlowSettings` system, which provides:\n\n- Custom variable definitions\n- Linkage rules configuration\n- Condition evaluation based on field values\n- Action triggers tied to data changes\n\nThe linkage rules system allows conditional logic based on collection fields:\n\n```typescript\n// Condition evaluation structure\n{\n condition: FilterGroup,\n actions: Action[]\n}\n```\n\n资料来源：[packages/core/client/src/flow/actions/linkageRules.tsx:60-80]()\n\n## API Reference\n\n### Database Initialization\n\n```typescript\nconst database = new Database({\n dialect: 'postgres',\n // ... connection options\n});\n```\n\n### Collection Definition\n\n```typescript\ndatabase.collection({\n name: 'users',\n fields: [\n { type: 'string', name: 'name' },\n { type: 'hasMany', name: 'posts' },\n ],\n});\n```\n\n### Query Operations\n\n| Method | Description |\n|--------|-------------|\n| `db.getCollection(name)` | Get collection instance |\n| `collection.repository` | Access CRUD operations |\n| `collection.model` | Access ORM model |\n\n## Summary\n\nThe Data Modeling system in NocoBase provides a comprehensive solution for defining and managing application data structures. It combines:\n\n1. **Collection Management**: Organize data into logical groupings\n2. **Field Definition**: Configure data attributes with types and validation\n3. **Schema Templates**: Enable reusable configurations\n4. **Multi-Datasource Support**: Connect to various database backends\n5. **UI Integration**: Seamless rendering through schema components\n6. **Workflow Connection**: Trigger actions based on data conditions\n\nThe architecture emphasizes extensibility through plugins, custom field interfaces, and dialect-specific optimizations.\n\n---\n\n\n\n## Interface Builder\n\n### 相关页面\n\n相关主题：[Data Modeling](#data-modeling), [Workflow Engine](#workflow-engine), [Plugin Development](#plugin-development)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/client/src/schema-settings/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-settings/index.md)\n- [packages/core/client/src/schema-initializer/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-initializer/index.md)\n- [packages/core/client/src/schema-component/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/index.md)\n- [packages/core/flow-engine/src/flowSettings.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/flowSettings.ts)\n- [packages/core/client/src/schema-component/antd/markdown/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/antd/markdown/index.md)\n- [packages/core/client/src/schema-component/antd/association-select/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/antd/association-select/index.md)\n- [packages/core/client/src/schema-component/antd/linkageFilter/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/antd/linkageFilter/index.md)\n
\n\n# Interface Builder\n\n## Overview\n\nThe Interface Builder is NocoBase's core visual configuration system that enables users to create and customize application interfaces through a schema-driven approach. It provides a declarative way to define UI components, their behaviors, and data relationships without requiring code modifications.\n\n### Core Concepts\n\nThe Interface Builder operates on a schema-based architecture where every UI element is defined through JSON schemas that describe:\n\n- Component type and properties\n- Data binding and field mappings\n- Action handlers and event callbacks\n- Styling and layout configurations\n- Conditional visibility rules\n\n### Architecture Overview\n\n```mermaid\ngraph TD\n A[Interface Builder] --> B[Schema Settings]\n A --> C[Schema Initializers]\n A --> D[Schema Components]\n A --> E[Variables System]\n \n B --> B1[Built-in Types]\n B --> B2[Designer Context]\n \n C --> C1[Block Initializers]\n C --> C2[Field Initializers]\n C --> C3[Action Initializers]\n \n D --> D1[Form Components]\n D --> D2[Display Components]\n D --> D3[Action Components]\n \n E --> E1[System Variables]\n E --> E2[Custom Variables]\n E --> E3[Flow Variables]\n```\n\n## Schema System\n\nThe schema system is the foundation of the Interface Builder. Schemas define the structure, behavior, and appearance of interface elements.\n\n### Schema Properties\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `x-component` | string | The component to render |\n| `x-component-props` | object | Component-specific props |\n| `x-decorator` | string | Wrapper component (e.g., FormItem) |\n| `x-decorator-props` | object | Decorator component props |\n| `x-designable` | boolean | Enable visual editing |\n| `x-hidden` | boolean | Hide the element |\n| `x-visible` | expression | Conditional visibility |\n\n### Basic Schema Example\n\n```tsx\n{\n type: 'string',\n 'x-component': 'Markdown',\n 'x-decorator': 'FormItem',\n 'x-component-props': {\n mode: 'sv',\n height: '82vh'\n }\n}\n```\n\n资料来源：[packages/core/client/src/flow/flows/editMarkdownFlow.tsx](./packages/core/client/src/flow/flows/editMarkdownFlow.tsx)\n\n## Schema Settings\n\nSchema Settings provide configuration panels for customizing schema properties in design mode. They appear when users click the settings icon on schema elements.\n\n### Built-in Schema Settings\n\nThe system includes several built-in schema settings components:\n\n| Component | Purpose |\n|-----------|---------|\n| `GeneralSchemaDesigner` | General schema configuration |\n| `SchemaSettings` | Base settings collection |\n| `SchemaSettingsDropdown` | Dropdown menu for settings |\n| `SchemaToolbar` | Toolbar for schema operations |\n\n### Designer Toolbar\n\nThe schema designer toolbar provides quick access to common operations:\n\n```tsx\n\n```\n\n资料来源：[packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx](./packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx)\n\n### Toolbar Components\n\n| Component | Function |\n|-----------|----------|\n| `DragHandler` | Drag handle for reordering |\n| `InitializerComponent` | Insert new elements |\n| `SchemaSettingsDropdown` | Open settings panel |\n\n### Toolbar Title Display\n\nThe toolbar displays hierarchical information when configured:\n\n```tsx\n\n {dataSource ? `${compile(dataSource?.displayName)} > ${titleArr[0]}` : titleArr[0]}\n\n```\n\n## Schema Initializers\n\nSchema Initializers define where and what elements can be inserted into the interface. They provide the \"Add\" functionality within design mode.\n\n### Initializer Types\n\n#### Block Initializers\n\nBlock initializers add container-level components like tables, forms, and grids.\n\n```tsx\n{\n type: 'array',\n title: '{{t(\"Blocks\")}}',\n name: 'blockInitializers',\n children: [\n // Table block\n {\n title: '{{t(\"Table\")}}',\n name: 'tableSelector',\n Component: TableSelectorInitializer\n },\n // Form block\n {\n title: '{{t(\"Form\")}}',\n name: 'formItemInitializers',\n Component: FormItemInitializers\n }\n ]\n}\n```\n\n#### Field Initializers\n\nField initializers add data fields to forms and tables.\n\n```tsx\n{\n type: 'array',\n title: '{{t(\"Fields\")}}',\n name: 'fieldInitializers',\n children: [\n {\n title: '{{t(\"Text\")}}',\n name: 'text',\n Component: DateFormatInitializer\n }\n ]\n}\n```\n\n### Dynamic Visibility\n\nInitializers can dynamically show or hide items based on context:\n\n```tsx\n{\n 'x-visible': '{{curdModel === \"list\"}}',\n children: [\n // Dynamic children\n ]\n}\n```\n\n## Schema Components\n\nNocoBase provides a rich library of schema components for building interfaces.\n\n### Form Components\n\n#### Markdown\n\nA rich text editor supporting Markdown syntax.\n\n```tsx\ninterface MarkdownProps extends TextAreaProps {\n value?: string;\n onChange?: (value: string) => void;\n mode?: 'sv' | 'wysiwyg';\n}\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `mode` | `'sv' \\| 'wysiwyg'` | `'sv'` | Editor mode |\n| `height` | `string \\| number` | `200` | Editor height |\n| `value` | `string` | - | Markdown content |\n| `onChange` | `function` | - | Change handler |\n\n资料来源：[packages/core/client/src/schema-component/antd/markdown/index.md](./packages/core/client/src/schema-component/antd/markdown/index.md)\n\n#### Markdown.Void\n\nA void component for inline markdown editing.\n\n```tsx\ninterface MarkdownVoidProps extends Omit {\n defaultValue?: string;\n onSubmit?: (value: string) => void;\n onCancel?: (e: React.MouseEvent) => void;\n}\n```\n\n### Association Components\n\n#### AssociationSelect\n\nSelect component for related data from specified tables.\n\n```tsx\ntype AssociationSelectProps

= RemoteSelectProps

& {\n action?: string;\n multiple?: boolean;\n};\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `action` | `string` | `'list'` | Data fetching action |\n| `multiple` | `boolean` | `false` | Enable multi-select |\n| `type` | `'string' \\| 'array'` | `'string'` | Value type |\n| `fieldNames` | `object` | - | Field name mappings |\n\n资料来源：[packages/core/client/src/schema-component/antd/association-select/index.md](./packages/core/client/src/schema-component/antd/association-select/index.md)\n\n### Filter Components\n\n#### LinkageFilter\n\nComponent for frontend linkage rules and condition configuration.\n\n```tsx\ntype FilterActionProps = ActionProps & {\n options?: any[];\n form?: Form;\n onSubmit?: (values: T) => void;\n onReset?: (values: T) => void;\n}\n```\n\n### Built-in Component Types\n\n| Category | Components |\n|----------|------------|\n| Input | Input, TextArea, NumberPicker, Password |\n| Select | Select, Checkbox, Radio, Switch |\n| Display | Markdown, Markdown.Void, LinkageFilter |\n| Association | AssociationSelect, RecordPicker |\n| DateTime | DatePicker, TimePicker, DateRangePicker |\n\n## Variables System\n\nThe Variables system provides dynamic data access within the Interface Builder, enabling context-aware functionality.\n\n### Variable Types\n\n| Type | Label | Description |\n|------|-------|-------------|\n| `system` | System | Built-in system variables |\n| `currentUser` | Current User | Logged-in user information |\n| `currentRole` | Current Role | Current user's role |\n| `dateNow` | Date Now | Current timestamp |\n| `form` | Form | Form values and state |\n| `record` | Record | Current data record |\n| `variable` | Custom Variable | User-defined variables |\n\n### Variable Table Structure\n\nVariables are displayed in a structured table:\n\n| Column | Description |\n|--------|-------------|\n| `title` | Variable display name |\n| `key` | Variable identifier |\n| `type` | Variable data type |\n| `actions` | Edit and delete operations |\n\n### Custom Variables\n\nCustom variables can be created and managed in workflows:\n\n```tsx\n{\n title: t('Custom Variables'),\n key: 'customVariables',\n type: 'object',\n children: [\n {\n title: variable.title,\n key: variable.key,\n type: variable.type\n }\n ]\n}\n```\n\n资料来源：[packages/core/client/src/flow/actions/customVariable.tsx](./packages/core/client/src/flow/actions/customVariable.tsx)\n\n## Actions\n\nActions define user interactions and their corresponding behaviors within the Interface Builder.\n\n### Action Types\n\n| Action | Description |\n|--------|-------------|\n| `submit` | Submit form data |\n| `cancel` | Cancel current operation |\n| `create` | Create new record |\n| `update` | Update existing record |\n| `delete` | Delete record |\n| `custom` | Custom action handler |\n\n### Action Schema Configuration\n\n```tsx\n{\n type: 'object',\n 'x-component': 'Action',\n 'x-component-props': {\n type: 'primary',\n icon: 'CheckOutlined'\n }\n}\n```\n\n## UI Mode Configuration\n\nThe UI Mode system allows customization of dialog and modal appearances.\n\n### Footer Configuration\n\n```tsx\nfooter: (originNode, { OkBtn, CancelBtn }) => (\n

\n Additional info\n {originNode}\n
\n)\n```\n\n### Footer Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `null` | `null` | Hide footer |\n| `ReactNode` | `ReactNode` | Static footer content |\n| `function` | `(originNode, { OkBtn, CancelBtn }) => ReactNode` | Dynamic footer |\n\n资料来源：[packages/core/flow-engine/src/flowSettings.ts](./packages/core/flow-engine/src/flowSettings.ts)\n\n## Designer Context\n\nThe Designer Context provides runtime information and utilities for schema design mode.\n\n### Context Features\n\n- `designable` - Current design mode state\n- `designerProps` - Designer-specific properties\n- `resources` - Available schema resources\n- `schema` - Current schema instance\n- `refresh` - Refresh handler for data updates\n\n### Context Usage\n\n```tsx\nconst { designable, schema, refresh } = useDesigner();\n\nif (designable) {\n return ;\n}\n```\n\n## Integration with Flow Engine\n\nThe Interface Builder integrates with NocoBase's Flow Engine to provide workflow-driven interface behavior.\n\n### Flow Settings Integration\n\nFlow settings can be embedded within schema components:\n\n```tsx\n{\n type: 'object',\n 'x-component': 'FlowSettings',\n properties: {\n content: {\n type: 'string',\n 'x-component': 'Markdown',\n 'x-component-props': {\n mode: 'sv'\n }\n }\n }\n}\n```\n\n### Default Parameters\n\nSchemas can define default parameters for flows:\n\n```tsx\ndefaultParams: (ctx) => {\n return {\n content: ctx.t('{{t(\"Default content\")}}'),\n };\n}\n```\n\n### Liquid Template Rendering\n\nVariables support Liquid template syntax:\n\n```tsx\nconst result = await ctx.liquid.renderWithFullContext(content, ctx);\n```\n\n## Mobile Interface Builder\n\nNocoBase supports mobile-specific interface building through the mobile plugin.\n\n### Mobile Pages\n\n| Page | Description |\n|------|-------------|\n| Home Page | Application homepage |\n| NotFound Page | 404 error page |\n\n### Mobile Layout Components\n\n| Component | Description |\n|-----------|-------------|\n| `MobileTabBar` | Bottom navigation bar |\n| `MobileTabBar.Item` | Tab bar items |\n| `MobileTabBar.Link` | Link navigation items |\n\n### Desktop Mode\n\nMobile pages can be wrapped for desktop viewing:\n\n```tsx\n\n \n\n```\n\n## Plugin Manager Integration\n\nThe Plugin Manager provides configuration UI for plugins built with the Interface Builder system.\n\n### Plugin Details Display\n\n```tsx\n{\n key: 'info',\n label: t('Plugin Info'),\n children: (\n <>\n {plugin.packageName}\n \n \n )\n}\n```\n\n### Dependency Compatibility\n\nPlugin details include dependency compatibility checking:\n\n```tsx\n{\n key: 'dependencies',\n label: t('Dependencies compatibility check'),\n children: (\n \n )\n}\n```\n\n## Best Practices\n\n### Schema Organization\n\n1. Use meaningful `name` properties for schema identification\n2. Group related components under consistent parent schemas\n3. Leverage decorators (`x-decorator`) for common patterns\n\n### Performance Optimization\n\n1. Use `x-hidden` over conditional rendering for hidden elements\n2. Leverage `designable` flag to skip rendering logic in production\n3. Use void components for modal content\n\n### Accessibility\n\n1. Include `aria-label` on interactive elements\n2. Use proper heading hierarchy within schema blocks\n3. Ensure keyboard navigation support\n\n## See Also\n\n- [Schema Settings Reference](./schema-settings/index.md)\n- [Schema Components Reference](./schema-component/index.md)\n- [Variables System](./variables.md)\n- [Mobile Interface](./mobile/index.md)\n\n---\n\n\n\n## Workflow Engine\n\n### 相关页面\n\n相关主题：[Interface Builder](#interface-builder), [Plugin System](#plugin-system), [Authentication and Permissions](#authentication-permissions)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx)\n- [packages/plugins/@nocobase/plugin-workflow/src/locale/ko-KR.json](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-workflow/src/locale/ko-KR.json)\n- [packages/core/flow-engine/src/flowSettings.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/flowSettings.ts)\n- [packages/core/flow-engine/src/components/FlowModelRenderer.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/components/FlowModelRenderer.tsx)\n- [packages/core/client/src/flow/actions/customVariable.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/flow/actions/customVariable.tsx)\n- [packages/plugins/@nocobase/plugin-workflow/src/client/CanvasContent.tsx](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-workflow/src/client/CanvasContent.tsx)\n
\n\n# Workflow Engine\n\n## Overview\n\nThe Workflow Engine is NocoBase's core system for designing, executing, and managing automated business processes. It provides a visual canvas-based interface where users can create workflows by connecting different node types, define triggers that initiate workflow execution, and configure custom variables for data transformation.\n\nThe engine is designed as a plugin (`@nocobase/plugin-workflow`) that integrates with the broader NocoBase platform, leveraging the `flow-engine` core module for rendering and execution logic.\n\n## Architecture\n\nThe Workflow Engine follows a provider-based architecture with clear separation between UI rendering and execution logic.\n\n```graph TD\n A[Workflow Canvas] --> B[FlowContext Provider]\n B --> C[ExecutionCanvas Component]\n C --> D[CanvasContent Component]\n C --> E[JobModal Component]\n D --> F[FlowModelRenderer]\n F --> G[FlowModelProvider]\n G --> H[ErrorBoundary]\n F --> I[MemoFlowModelRenderer]\n```\n\n## Core Components\n\n### FlowContext Provider\n\nThe `FlowContext` provides runtime data to all workflow-related components. It encapsulates the current workflow, nodes, execution context, and view state.\n\n```typescript\n\n```\n\n**Context Values:**\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `workflow` | `Workflow` | The workflow configuration object |\n| `nodes` | `Node[]` | Array of nodes in the workflow |\n| `execution` | `Execution` | Current execution instance |\n| `viewJob` | `Job \\| null` | Job selected for detailed view |\n| `setViewJob` | `Function` | Callback to update viewJob state |\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx:21-28]()\n\n### ExecutionCanvas\n\nThe `ExecutionCanvas` is the main container component for viewing workflow executions. It renders the toolbar, status indicators, and delegates content rendering to child components.\n\n**Key Features:**\n\n- Breadcrumb navigation to workflow details\n- Execution status badge with color coding\n- Cancel execution capability (when execution is not in terminal state)\n- Last updated timestamp display\n\n```typescript\n{lang('Workflow')} },\n {\n title: (\n \n {workflow.title}\n \n ),\n },\n { title: },\n ]}\n/>\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx:31-44]()\n\n### FlowModelRenderer\n\nThe `FlowModelRenderer` is the core rendering component that displays the workflow model with all connected nodes. It supports several configuration options:\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `model` | `Model` | Required | The data model to render |\n| `showFlowSettings` | `boolean` | `true` | Whether to show flow settings panel |\n| `flowSettingsVariant` | `string` | `undefined` | Visual variant for settings |\n| `hideRemoveInSettings` | `boolean` | `false` | Hide remove button in settings |\n| `showTitle` | `boolean` | `true` | Show the model title |\n| `inputArgs` | `any[]` | `[]` | Input arguments for the flow |\n| `showErrorFallback` | `boolean` | `true` | Show error fallback UI |\n| `settingsMenuLevel` | `string` | `undefined` | Settings menu hierarchy level |\n| `extraToolbarItems` | `ReactNode` | `undefined` | Additional toolbar content |\n| `fallback` | `React.FC` | `undefined` | Custom fallback component |\n| `useCache` | `boolean` | `false` | Enable render caching |\n\n资料来源：[packages/core/flow-engine/src/components/FlowModelRenderer.tsx:1-50]()\n\n**Memoization:**\n\n```typescript\nexport const MemoFlowModelRenderer = React.memo(FlowModelRenderer);\nMemoFlowModelRenderer.displayName = 'MemoFlowModelRenderer';\n```\n\nThe component includes a memoized version (`MemoFlowModelRenderer`) that skips re-rendering when parent components re-render but props remain unchanged. This optimization does not affect internal reactive updates.\n\n资料来源：[packages/core/flow-engine/src/components/FlowModelRenderer.tsx:110-112]()\n\n### CanvasContent\n\nThe `CanvasContent` component renders the actual workflow visualization including nodes, edges, and clipboard preview functionality.\n\n**Features:**\n\n- Terminal node display (Start/End markers)\n- Clipboard preview for copied nodes\n- Zoom slider control\n\n```typescript\n
\n \n
\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/client/CanvasContent.tsx:1-100]()\n\n## Flow Settings\n\nThe `FlowSettings` class manages flow configuration dialogs and their component registry.\n\n```typescript\nexport class FlowSettings {\n public components: Record = {};\n public scopes: Record = {};\n private antdComponentsLoaded = false;\n public enabled: boolean;\n #forceEnabled = false;\n}\n```\n\n资料来源：[packages/core/flow-engine/src/flowSettings.ts:1-10]()\n\n### Footer Configuration\n\nFlow settings support customizable footer content through a flexible API:\n\n```typescript\nfooter?:\n | React.ReactNode\n | ((originNode: React.ReactNode, extra: { OkBtn: React.FC; CancelBtn: React.FC }) => React.ReactNode)\n | null;\n```\n\n**Footer Patterns:**\n\n| Pattern | Example |\n|---------|---------|\n| **Default** | Preserves original footer with Ok/Cancel buttons |\n| **Overlay** | Add content above origin footer |\n| **Replace** | Full custom footer composition |\n| **Hidden** | Set `footer: null` to hide |\n\n资料来源：[packages/core/flow-engine/src/flowSettings.ts:1-30]()\n\n## Variables System\n\nThe workflow engine supports variable injection for data transformation between nodes.\n\n### Custom Variables Configuration\n\nThe `customVariable.tsx` file provides the UI for managing custom workflow variables:\n\n**Variable Properties:**\n\n| Property | Data Index | Description |\n|----------|------------|-------------|\n| Title | `title` | Display name for the variable |\n| Identifier | `key` | Unique key for referencing |\n| Type | `type` | Data type classification |\n\n**Available Variable Types:**\n\n| Type | Label | Usage |\n|------|-------|-------|\n| `string` | String | Text data |\n| `number` | Number | Numeric values |\n| `boolean` | Boolean | True/false flags |\n| `array` | Array | List of values |\n| `object` | Object | Complex structured data |\n\n**Actions:**\n\n| Action | Icon | Description |\n|--------|------|-------------|\n| Edit | `EditOutlined` | Modify variable configuration |\n| Delete | `DeleteOutlined` | Remove variable from workflow |\n\n```typescript\nrender: (_: unknown, __: FlowVariable, index: number) => (\n \n }\n onClick={() => handleEdit(index)}\n disabled={disabled}\n title={t('Edit')}\n />\n }\n danger\n onClick={() => handleDelete(index)}\n disabled={disabled}\n title={t('Delete')}\n />\n \n)\n```\n\n资料来源：[packages/core/client/src/flow/actions/customVariable.tsx:1-80]()\n\n## Execution States\n\nThe engine tracks execution status through a state machine:\n\n```graph TD\n A[Created] --> B[Running]\n B --> C[Success]\n B --> D[Failed]\n B --> E[Cancelled]\n D --> F[Retry]\n F --> B\n```\n\n**Status Options:**\n\n| Status | Color | Description |\n|--------|-------|-------------|\n| Running | Processing | Execution in progress |\n| Success | Success | Completed successfully |\n| Failed | Error | Execution encountered an error |\n| Cancelled | Warning | Execution manually stopped |\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/locale/ko-KR.json:1-50]()\n\n## Trigger Points\n\nWorkflows can be triggered at various points in the application lifecycle:\n\n| Trigger | Description |\n|---------|-------------|\n| After Saving | Triggered after data save completes |\n| After Submitting | Triggered after form submission succeeds |\n| Before Deleting | Triggered before deletion (local mode only) |\n| Button Click | Triggered directly on button click without saving |\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/locale/ko-KR.json:50-100]()\n\n## Error Handling\n\nThe system implements multi-level error handling:\n\n1. **ErrorBoundary Wrapper:** Catches rendering errors around the FlowModelRenderer\n2. **FlowModelProvider:** Provides error context to child components\n3. **FlowErrorFallback:** Renders user-friendly error messages with recovery options\n\n```typescript\nif (showErrorFallback) {\n return (\n \n {content}\n \n );\n}\n```\n\n资料来源：[packages/core/flow-engine/src/components/FlowModelRenderer.tsx:85-92]()\n\n## Integration with Plugin System\n\nThe workflow plugin integrates with NocoBase's plugin manager through:\n\n- **Route Registration:** `/workflow` path for navigation\n- **Settings Manager:** `app.pluginSettingsManager.getRoutePath('workflow')`\n- **Localization:** Multi-language support via JSON locale files\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx:35]()\n\n## Summary\n\nThe Workflow Engine provides a comprehensive system for building and executing automated workflows within NocoBase. Key aspects include:\n\n- **Visual Canvas:** Drag-and-drop workflow design interface\n- **Context-Based Architecture:** React Context for global state management\n- **Flexible Configuration:** Customizable settings dialogs and footers\n- **Variable System:** Support for custom variables with type classification\n- **Error Resilience:** Built-in error boundaries and fallback components\n- **Execution Tracking:** Real-time status updates and execution history\n- **Plugin Integration:** Seamless integration with the NocoBase plugin ecosystem\n\n---\n\n\n\n## Authentication and Permissions\n\n### 相关页面\n\n相关主题：[Workflow Engine](#workflow-engine), [Data Modeling](#data-modeling), [Plugin Development](#plugin-development)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [docs/docs/en/auth-verification/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/auth-verification/index.md)\n- [docs/docs/en/users-permissions/acl/permissions.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/users-permissions/acl/permissions.md)\n- [docs/docs/en/users-permissions/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/users-permissions/index.md)\n- [docs/docs/en/plugins/@nocobase/plugin-acl/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/plugins/@nocobase/plugin-acl/index.md)\n- [docs/docs/en/plugins/@nocobase/plugin-auth/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/plugins/@nocobase/plugin-auth/index.md)\n- [docs/docs/en/users-permissions/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/users-permissions/index.md)\n
\n\n# Authentication and Permissions\n\n## Overview\n\nNocoBase implements a comprehensive authentication and permissions system built on a plugin-based architecture. The system is designed to provide secure access control through multiple integrated plugins that handle user authentication, role-based access control (RBAC), and granular resource permissions.\n\n## Authentication System\n\n### Authentication Plugin\n\nThe `@nocobase/plugin-auth` plugin provides the core authentication capabilities for NocoBase. This plugin handles user identity verification, session management, and integrates with various authentication providers.\n\n### Authentication Verification Flow\n\nThe auth-verification system implements a multi-step verification process to ensure secure access to NocoBase resources.\n\n```mermaid\ngraph TD\n A[Client Request] --> B{Authentication Required?}\n B -->|Yes| C[Auth Plugin Verification]\n B -->|No| G[Resource Access]\n C --> D{Credentials Valid?}\n D -->|Yes| E[Generate Session Token]\n D -->|No| F[Authentication Failed - 401]\n E --> G[Resource Access with Token]\n```\n\n### User Management\n\nThe `@nocobase/plugin-users` plugin extends the authentication system by providing comprehensive user management capabilities. User records store essential identity information and serve as the basis for permission assignments.\n\n## Access Control List (ACL) System\n\n### ACL Plugin Architecture\n\nThe `@nocobase/plugin-acl` plugin implements NocoBase's Access Control List system, providing fine-grained permission management across collections, actions, and fields.\n\n```mermaid\ngraph TD\n A[User Request] --> B{ACL Check}\n B --> C{Role Assigned?}\n C -->|No| D[Default Deny]\n C -->|Yes| E[Check Resource Permissions]\n E --> F{Action Allowed?}\n F -->|Yes| G[Execute Action]\n F -->|No| H[Permission Denied - 403]\n```\n\n### Permission Model\n\nNocoBase's permissions system follows a hierarchical structure:\n\n| Permission Level | Scope | Description |\n|-----------------|-------|-------------|\n| Collection | `collections:*` | Global collection access |\n| Specific Collection | `collections:posts` | Single collection access |\n| Action | `collections:posts:*` | All actions on collection |\n| Field | `fields:posts:title` | Specific field access |\n| Resource | `resources:posts` | Resource-level permissions |\n\n资料来源：[docs/docs/en/users-permissions/acl/permissions.md]()\n\n### Built-in Roles\n\n| Role | Description | Default Permissions |\n|------|-------------|---------------------|\n| `admin` | Full system access | All permissions |\n| `member` | Basic user access | Limited to assigned resources |\n| `guest` | Unauthenticated users | Minimal or no access |\n\n资料来源：[docs/docs/en/plugins/@nocobase/plugin-acl/index.md]()\n\n## Permissions Management\n\n### Role-Based Access Control\n\nThe permissions system in NocoBase is built on the principle of assigning permissions to roles, then assigning roles to users. This follows the standard RBAC (Role-Based Access Control) model.\n\n```mermaid\ngraph LR\n A[Users] -->|assigned to| B[Roles]\n B -->|grants| C[Permissions]\n C -->|apply to| D[Resources/Actions]\n \n E[Collections] -->|scope| C\n F[Fields] -->|scope| C\n G[Actions] -->|scope| C\n```\n\n资料来源：[docs/docs/en/users-permissions/index.md]()\n\n### Permission Configuration\n\nPermissions can be configured at multiple levels:\n\n| Level | Syntax | Example |\n|-------|--------|---------|\n| All resources | `*` | `collections:*` |\n| Specific resource | `resourceName` | `collections:posts` |\n| Nested resource | `parent.child` | `collections:posts.comments` |\n| Field-level | `resource:field` | `collections:posts:title` |\n\n### UI Permission Handling\n\nIn the client-side implementation, permission checks are integrated throughout the UI components. Fields that users lack permission to modify are automatically restricted:\n\n```typescript\n// From: packages/core/client/src/flow/models/fields/AssociationFieldModel/SubTableFieldModel/SubTableColumnModel.tsx\nconst messageValue = useMemo(() => {\n return t(\n `The current user only has the UI configuration permission, but don't have \"{{actionName}}\" permission for field \"{{name}}\"`,\n {\n name: nameValue,\n actionName: t(capitalize(actionName)),\n },\n ).replaceAll('>', '>');\n}, [nameValue, t]);\n```\n\nThis code demonstrates how NocoBase handles field-level permissions, displaying lock icons and tooltip messages when users lack action permissions on specific fields.\n\n## Security Implementation\n\n### Safe Globals in Execution Contexts\n\nFor sensitive operations like custom JavaScript execution (e.g., RunJS nodes in workflows), NocoBase implements safe globals to prevent unauthorized access:\n\n```typescript\n// From: packages/core/flow-engine/src/utils/safeGlobals.ts\nconst allowed: Record = {\n clipboard,\n};\n\nObject.defineProperty(allowed, 'onLine', {\n get: () => !!nav?.onLine,\n enumerable: true,\n configurable: false,\n});\n\nreturn new Proxy(\n {},\n {\n get(_t, prop: string) {\n if (prop in allowed) return (allowed as any)[prop];\n throw new Error(`Access to navigator property \"${String(prop)}\" is not allowed.`);\n },\n },\n);\n```\n\nThis security measure ensures that sensitive browser APIs are either read-only or completely blocked in untrusted execution contexts.\n\n### URL Security Validation\n\nWhen workflows or scripts need to open URLs, NocoBase enforces strict URL validation:\n\n```typescript\n// From: packages/core/flow-engine/src/utils/safeGlobals.ts\nconst isSafeUrl = (u: string): boolean => {\n try {\n const parsed = new URL(u, getSafeBaseHref());\n const protocol = parsed.protocol.toLowerCase();\n if (protocol === 'about:') return parsed.href === 'about:blank';\n return protocol === 'http:' || protocol === 'https:';\n } catch {\n return false;\n }\n};\n```\n\nOnly `http://`, `https://`, and `about:blank` URLs are permitted, preventing potential security vulnerabilities from malicious URL schemes.\n\n## Plugin Dependencies\n\nThe authentication and permissions system depends on a plugin hierarchy:\n\n```mermaid\ngraph BT\n A[plugin-auth] --> B[plugin-users]\n C[plugin-acl] --> B\n B --> D[plugin-core]\n```\n\n| Plugin | Purpose |\n|--------|---------|\n| `plugin-auth` | Authentication mechanisms |\n| `plugin-users` | User management |\n| `plugin-acl` | Access Control List implementation |\n\n## Related Documentation\n\n| Document | Path |\n|----------|------|\n| Auth Verification | `docs/docs/en/auth-verification/index.md` |\n| ACL Permissions | `docs/docs/en/users-permissions/acl/permissions.md` |\n| User Permissions Guide | `docs/docs/en/users-permissions/index.md` |\n| ACL Plugin | `docs/docs/en/plugins/@nocobase/plugin-acl/index.md` |\n| Auth Plugin | `docs/docs/en/plugins/@nocobase/plugin-auth/index.md` |\n| Users Plugin | `docs/docs/en/plugins/@nocobase/plugin-users/index.md` |\n\n---\n\n\n\n## AI Integration\n\n### 相关页面\n\n相关主题：[Overview](#overview), [Workflow Engine](#workflow-engine), [Plugin Development](#plugin-development)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/chatbox/Messages.tsx](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/chatbox/Messages.tsx)\n- [packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/admin/Employees.tsx](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/admin/Employees.tsx)\n- [packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/admin/Templates.tsx](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/admin/Templates.tsx)\n- [packages/plugins/@nocobase/plugin-ai/src/server/tools/docs.ts](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai/src/server/tools/docs.ts)\n- [packages/core/flow-engine/src/runjs-context/contexts/base.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/runjs-context/contexts/base.ts)\n- [packages/core/client/src/flow/actions/customVariable.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/flow/actions/customVariable.tsx)\n
\n\n# AI Integration\n\nNocoBase provides a comprehensive AI Integration system through the `@nocobase/plugin-ai` package. This system enables users to create, manage, and deploy AI employees that can collaborate with human users to build and manage business applications. The AI integration leverages modern LLM (Large Language Model) technology to provide intelligent assistance throughout the platform.\n\n## Overview\n\nThe AI Integration feature in NocoBase is designed to:\n\n- Enable AI agents to work alongside human users in a collaborative environment\n- Provide customizable AI employees with different roles and capabilities\n- Support knowledge base integration for context-aware responses\n- Offer tool-calling capabilities for AI to interact with the NocoBase system\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/chatbox/Messages.tsx:1-40]()\n\n## Architecture\n\nThe AI Integration system follows a plugin-based architecture that integrates seamlessly with the NocoBase core system.\n\n### System Components\n\n| Component | Purpose | Location |\n|-----------|---------|----------|\n| AI Employees | Virtual team members that can perform tasks | `packages/plugins/@nocobase/plugin-ai` |\n| Chat Interface | Real-time messaging between users and AI | `src/client/ai-employees/chatbox/` |\n| Admin Panel | Management interface for AI configurations | `src/client/ai-employees/admin/` |\n| Templates | Pre-configured AI employee templates | `src/client/ai-employees/admin/Templates.tsx` |\n| Tool System | Server-side tools for AI operations | `src/server/tools/` |\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/admin/Employees.tsx:1-80]()\n\n## AI Employees\n\nAI Employees are virtual team members that can be assigned tasks, communicate with users, and perform various operations within the NocoBase ecosystem.\n\n### Employee Management\n\nThe `Employees` component provides a comprehensive interface for managing AI employees:\n\n```tsx\n\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/admin/Employees.tsx:35-75]()\n\n### Employee Data Model\n\n| Field | Type | Description |\n|-------|------|-------------|\n| username | string | Unique identifier for the AI employee |\n| category | string | Classification category (e.g., 'business') |\n| enabled | boolean | Whether the employee is active |\n| sort | number | Display order |\n| templates | array | Pre-configured task templates |\n\n### Category Filtering\n\nAI employees can be filtered by category using the `CategoryFilter` component, allowing administrators to organize employees based on their functional areas or roles.\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/admin/Employees.tsx:50-55]()\n\n## Chat Interface\n\nThe chatbox component provides a real-time messaging interface for user interaction with AI employees.\n\n### Message Display\n\nMessages are rendered using the `Messages` component which handles different message states:\n\n```tsx\n
\n {messages.length > 0 ? (\n
\n {messages.map((msg) => {\n return (\n \n );\n })}\n
\n ) : (\n \n {t('Work with your AI crew')}\n
\n )}\n\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/chatbox/Messages.tsx:10-40]()\n\n### Message States\n\n| State | Description | Visual Indicator |\n|-------|-------------|------------------|\n| normal | Standard message display | Default styling |\n| loading | Message being processed | Loading spinner |\n| error | Failed message | Error styling |\n| streaming | Real-time response | Progressive rendering |\n\n## Templates System\n\nTemplates provide pre-configured AI employee configurations that can be quickly deployed to create new AI team members.\n\n### Template Loading\n\nTemplates are loaded dynamically from the server:\n\n```tsx\nconst { data: templates, loading } = useRequest<{ data: AIEmployee[] }>(() =>\n api\n .resource('aiEmployees')\n .getTemplates()\n .then((res) => res?.data?.data),\n);\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/admin/Templates.tsx:1-30]()\n\n### Template Creation Flow\n\nWhen creating a new employee from a template, the system uses a drawer component with form validation:\n\n```tsx\n\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/admin/Templates.tsx:35-85]()\n\n## Server-Side Tools\n\nThe AI integration includes server-side tools that allow AI employees to interact with various NocoBase system components.\n\n### Documentation Reader Tool\n\nThe `readDocEntry` tool enables AI employees to access and read documentation entries:\n\n```tsx\nreadDocEntry: {\n description: 'Read a documentation entry',\n parameters: {\n type: 'object',\n properties: {\n module: {\n type: 'string',\n description: 'The module key (e.g., \"runjs\")',\n },\n },\n required: ['module'],\n },\n async handler(ctx) {\n try {\n const { pluginKey, relativePath, canonicalPath } = parseDocPath(input);\n const meta = docsModules.get(pluginKey);\n if (!meta) {\n throw new Error(`Document module \"${pluginKey}\" not found.`);\n }\n // Read and return documentation content\n } catch (error) {\n ctx.log?.error?.(error, {\n module: 'ai',\n subModule: 'toolCalling',\n toolName: 'readDocEntry',\n });\n return {\n status: 'error',\n content: `Failed to read docs entry: ${error.message}`,\n };\n }\n },\n},\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/tools/docs.ts:1-80]()\n\n### Tool Execution Flow\n\n```mermaid\ngraph TD\n A[User Request] --> B[AI Employee Processing]\n B --> C{Requires Tool?}\n C -->|Yes| D[Tool Selection]\n C -->|No| E[Direct Response]\n D --> F[Execute Server Tool]\n F --> G[Tool Handler]\n G --> H[Error Handling]\n H --> I[Return Result]\n E --> I\n I --> J[Response to User]\n```\n\n### Available Server Tools\n\n| Tool Name | Purpose | Module |\n|-----------|---------|--------|\n| readDocEntry | Read documentation entries | ai |\n| customVariable | Manage flow variables | flow |\n| runjs | Execute JavaScript code | flow-engine |\n\n## AI Context in Workflows\n\nThe AI system integrates with NocoBase's workflow engine through a comprehensive context system that provides AI employees access to system resources.\n\n### Resource Context\n\nAI employees can interact with resources through the context API:\n\n```typescript\ninterface ResourceContext {\n setData: {\n description: '设置资源当前数据（仅前端）';\n detail: '(value: any) => this';\n completion: { insertText: 'ctx.resource.setData(value)' };\n };\n refresh: {\n description: '从后端刷新数据';\n detail: '() => Promise';\n completion: { insertText: 'await ctx.resource.refresh()' };\n };\n on: {\n description: '订阅资源事件';\n detail: '(event: string, callback: (...args) => void) => void';\n completion: { insertText: \"ctx.resource.on('refresh', () => {})\" };\n };\n setResourceName: {\n description: '设置资源名称';\n detail: '(resourceName: string) => this';\n completion: { insertText: \"ctx.resource.setResourceName('users')\" };\n };\n setFilterByTk: {\n description: '设置主键/过滤键';\n detail: '(filterByTk: any) => this';\n completion: { insertText: 'ctx.resource.setFilterByTk(filterByTk)' };\n };\n runAction: {\n description: '执行资源动作';\n };\n}\n```\n\n资料来源：[packages/core/flow-engine/src/runjs-context/contexts/base.ts:1-50]()\n\n## Flow Variables\n\nAI integration supports custom variables that can be used in workflows and shared between human and AI collaborators.\n\n### Variable Management Interface\n\nThe variable management UI provides full CRUD operations:\n\n```tsx\ncolumns={[\n {\n title: t('Name'),\n dataIndex: 'name',\n key: 'name',\n ellipsis: true,\n render: (text: string) => {text},\n },\n {\n title: t('Identifier'),\n dataIndex: 'key',\n key: 'key',\n ellipsis: true,\n },\n {\n title: t('Type'),\n dataIndex: 'type',\n key: 'type',\n render: (type: FlowVariableType) => (\n {t(VARIABLE_TYPE_LABELS[type] || type)}\n ),\n },\n {\n title: t('Actions'),\n key: 'actions',\n render: (_: unknown, __: FlowVariable, index: number) => (\n \n }\n onClick={() => handleEdit(index)}\n />\n }\n danger\n onClick={() => handleDelete(index)}\n />\n \n ),\n },\n]}\n```\n\n资料来源：[packages/core/client/src/flow/actions/customVariable.tsx:1-70]()\n\n### Variable Types\n\n| Type | Label | Description |\n|------|-------|-------------|\n| string | String | Text value |\n| number | Number | Numeric value |\n| boolean | Boolean | True/false value |\n| date | Date | Date and time value |\n| object | Object | Complex data structure |\n| array | Array | Collection of values |\n\n## Error Handling\n\nThe AI integration system includes comprehensive error handling for both client and server components.\n\n### Client-Side Error Fallback\n\n```tsx\n\n {t('Feedback')}\n ,\n ,\n ]}\n>\n \n \n {error.stack}\n \n \n\n```\n\n资料来源：[packages/core/client/src/schema-component/antd/error-fallback/ErrorFallback.tsx:1-30]()\n\n### Server-Side Error Logging\n\nErrors are logged with module context for debugging:\n\n```tsx\nctx.log?.error?.(error, {\n module: 'ai',\n subModule: 'toolCalling',\n toolName: 'readDocEntry',\n});\n```\n\n## Installation and Setup\n\nTo enable AI integration in NocoBase:\n\n1. Install the `@nocobase/plugin-ai` package\n2. Configure the plugin in the NocoBase administration panel\n3. Set up AI provider credentials (API keys for LLM services)\n4. Create AI employees and assign roles\n5. Configure knowledge bases and tools as needed\n\n## Summary\n\nThe AI Integration system in NocoBase provides a powerful framework for creating intelligent AI employees that can collaborate with human users. Key features include:\n\n- **Employee Management**: Create, edit, and organize AI team members with different roles\n- **Real-time Chat**: Direct communication channel between users and AI employees\n- **Template System**: Quick deployment of pre-configured AI employees\n- **Tool Integration**: AI can access NocoBase system capabilities through server-side tools\n- **Workflow Integration**: AI context available in NocoBase workflow engine\n- **Error Handling**: Comprehensive error reporting and recovery mechanisms\n\nThis system enables organizations to build AI-powered business applications that leverage the intelligence of large language models while maintaining the flexibility and extensibility of the NocoBase no-code platform.\n\n---\n\n\n\n## File Storage\n\n### 相关页面\n\n相关主题：[Data Modeling](#data-modeling), [Interface Builder](#interface-builder)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/client/src/schema-component/antd/upload/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/antd/upload/index.md)\n- [packages/core/client/src/schema-component/antd/upload/Upload.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/antd/upload/Upload.tsx)\n- [packages/core/client/src/schema-component/antd/input/ScanInput/QRCodeScanner.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/antd/input/ScanInput/QRCodeScanner.tsx)\n- [packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx)\n- [packages/core/flow-engine/src/utils/resolveModuleUrl.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/utils/resolveModuleUrl.ts)\n
\n\n# File Storage\n\n## Overview\n\nFile Storage in NocoBase is a comprehensive system for managing file uploads, storage, and preview capabilities across the platform. The system is built on top of Ant Design's Upload component and extends it with additional features such as thumbnail preview, file type validation, size restrictions, and integration with the broader schema system.\n\nThe file storage subsystem consists of several key components:\n\n- **Upload Component**: The primary interface for file uploads\n- **Storage Adapters**: Backend mechanisms for persisting files\n- **File Preview**: Preview capabilities for various file types\n- **Schema Integration**: Deep integration with NocoBase's schema system\n\n资料来源：[packages/core/client/src/schema-component/antd/upload/index.md:1-24]()\n\n## Upload Component\n\n### Type Definitions\n\nThe Upload component is defined with the following type signature:\n\n```typescript\ntype UploadProps = Omit & {\n onChange?: (fileList: UploadFile[]) => void;\n serviceErrorMessage?: string;\n value?: any;\n size?: string;\n};\n```\n\n资料来源：[packages/core/client/src/schema-component/antd/upload/index.md:8-13]()\n\nThe component accepts all Ant Design Upload props while extending them with NocoBase-specific functionality. The `value` prop allows for controlled usage within schema forms, and `size` can be used to restrict upload behavior.\n\n### Read Pretty Mode\n\nFor display-only scenarios, a specialized read-pretty variant is available:\n\n```typescript\ntype UploadReadPrettyProps = AntdUploadProps;\n```\n\n资料来源：[packages/core/client/src/schema-component/antd/upload/index.md:17-18]()\n\n## File List Item Rendering\n\nThe file list rendering in `Upload.tsx` demonstrates how individual uploaded files are displayed to users:\n\n```typescript\nconst item = [\n \n \n ,\n showFileName !== false && file.title ? (\n \n {file.status === 'uploading' ? t('Uploading') : file.title}\n \n ) : null,\n];\n```\n\n资料来源：[packages/core/client/src/schema-component/antd/upload/Upload.tsx:1-11]()\n\nThe rendered item can be either a clickable link (if `file.url` exists) or a plain span:\n\n```typescript\nconst wrappedItem = file.url ? (\n \n {item}\n \n) : (\n {item}\n);\n```\n\n资料来源：[packages/core/client/src/schema-component/antd/upload/Upload.tsx:13-20]()\n\n### File Actions\n\nEach file item includes action buttons for managing the upload:\n\n| Action | Condition | Icon | Handler |\n|--------|-----------|------|---------|\n| Download | `!readPretty && file.url` | `DownloadOutlined` | `onDownload` |\n| Delete | `!readPretty && !disabled && file.status !== 'uploading'` | `DeleteOutlined` | `onDelete` |\n\n资料来源：[packages/core/client/src/schema-component/antd/upload/Upload.tsx:23-35]()\n\n## Upload Workflow\n\n```mermaid\ngraph TD\n A[User Selects File] --> B{File Size Check}\n B -->|Greater than 1MB| C[Show Error Alert]\n B -->|Within Limit| D[startScanFile]\n D --> E[Upload to Server]\n E --> F{Upload Status}\n F -->|uploading| G[Show Progress]\n F -->|done| H[Display Thumbnail]\n F -->|error| I[Show Error State]\n```\n\n## File Size Validation\n\nThe system enforces a 1MB limit on uploaded images with user-friendly error messaging:\n\n```typescript\nif (file && file.size < 1024 * 1024) {\n startScanFile(file);\n} else {\n alert(t('The image size is too large. Please compress it to below 1MB before uploading'));\n}\n```\n\n资料来源：[packages/core/client/src/schema-component/antd/input/ScanInput/QRCodeScanner.tsx:1-8]()\n\nThis validation pattern ensures users receive clear guidance when attempting to upload oversized files.\n\n## Thumbnail Preview\n\nThe thumbnail previewer component handles generating previews for uploaded files. The `ThumbnailPreviewer` component is referenced in the upload component's item rendering and provides visual feedback for uploaded content.\n\n## Integration with Schema System\n\n### Schema Designer Integration\n\nFiles can be configured and managed through NocoBase's schema system using the `GeneralSchemaDesigner` component:\n\n```typescript\n\n {showDataSource && dataSource\n ? `${compile(dataSource?.displayName)} > ${compile(title)}`\n : compile(title)}\n\n```\n\n资料来源：[packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx:1-8]()\n\nThis allows file storage configurations to be embedded within the broader schema initialization and settings infrastructure.\n\n## File Type Detection\n\nThe upload system includes utility functions for determining file types, including CSS file detection:\n\n```typescript\nexport function isCssFile(url: string): boolean {\n if (!url || typeof url !== 'string') {\n return false;\n }\n // 去掉 query 和 hash 后判断文件扩展名\n const pathPart = url.split('?')[0].split('#')[0];\n return pathPart.endsWith('.css');\n}\n```\n\n资料来源：[packages/core/flow-engine/src/utils/resolveModuleUrl.ts:1-14]()\n\nThis utility strips query parameters and hash fragments before checking file extensions, supporting URLs like `example.css?v=123` or `example.css#section`.\n\n## Configuration Options\n\n### Upload Component Properties\n\n| Property | Type | Description | Default |\n|----------|------|-------------|---------|\n| `value` | `any` | Controlled value for the file list | - |\n| `onChange` | `(fileList: UploadFile[]) => void` | Callback when file list changes | - |\n| `serviceErrorMessage` | `string` | Custom error message for upload failures | - |\n| `size` | `string` | Size restriction identifier | - |\n| `readPretty` | `boolean` | Display-only mode | `false` |\n\n### File List Item States\n\n| Status | UI Indicator | Available Actions |\n|--------|--------------|-------------------|\n| `uploading` | Progress indicator | None |\n| `done` | Thumbnail + filename | Download, Delete |\n| `error` | Error state | Delete |\n\n## Best Practices\n\n1. **Size Limits**: Always validate file sizes before upload to provide immediate user feedback\n2. **Thumbnail Previews**: Enable thumbnails to improve user experience for image files\n3. **Accessible Links**: Use proper `target=\"_blank\"` and `rel=\"noopener noreferrer\"` for downloaded files\n4. **Status Indicators**: Show upload progress and error states clearly\n5. **URL Handling**: Strip query parameters and hash fragments when determining file types\n\n---\n\n\n\n## Cluster Mode\n\n### 相关页面\n\n相关主题：[Deployment](#deployment), [System Architecture](#system-architecture)\n\n
\nRelated Source Files\n\nThe following source files were referenced for this documentation:\n\n- [docs/docs/en/cluster-mode/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/cluster-mode/index.md)\n- [docs/docs/en/cluster-mode/kubernetes.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/cluster-mode/kubernetes.md)\n- [docs/docs/en/cluster-mode/development.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/cluster-mode/development.md)\n- [docs/docs/en/cluster-mode/operations.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/cluster-mode/operations.md)\n- [docs/docs/en/cluster-mode/preparations.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/cluster-mode/preparations.md)\n- [docs/docs/en/plugins/@nocobase/plugin-lock-adapter-redis/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/plugins/@nocobase/plugin-lock-adapter-redis/index.md)\n- [docs/docs/en/plugins/@nocobase/plugin-pubsub-adapter-redis/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/plugins/@nocobase/plugin-pubsub-adapter-redis/index.md)\n
\n\n# Cluster Mode\n\n## Overview\n\nCluster Mode in NocoBase enables horizontal scaling by running multiple application instances behind a load balancer. This architecture provides high availability, improved performance under concurrent load, and fault tolerance for production deployments.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n Client1[Client] --> LB[Load Balancer]\n Client2[Client] --> LB\n Client3[Client] --> LB\n LB --> App1[NocoBase Instance 1]\n LB --> App2[NocoBase Instance 2]\n LB --> App3[NocoBase Instance N]\n App1 <--> Redis[(Redis)]\n App2 <--> Redis\n App3 <--> Redis\n App1 <--> DB[(Database)]\n App2 <--> DB\n App3 <--> DB\n```\n\n### Core Components\n\n| Component | Purpose | Required |\n|-----------|---------|----------|\n| Load Balancer | Distributes traffic across instances | Yes |\n| NocoBase Instances | Application servers running the same codebase | Yes |\n| Shared Database | MySQL/PostgreSQL for persistent data storage | Yes |\n| Redis | Lock adapter and pub/sub for inter-instance communication | Yes |\n| File Storage | S3/MinIO for file uploads (shared across instances) | Yes |\n\n## Prerequisites\n\n### Infrastructure Requirements\n\nBefore deploying in cluster mode, ensure the following:\n\n1. **Database**: MySQL 8.0+ or PostgreSQL 12+ with proper network access\n2. **Redis**: Redis 6.0+ for distributed locking and pub/sub\n3. **File Storage**: Shared storage solution (S3-compatible, MinIO, or NFS)\n4. **Load Balancer**: Nginx, HAProxy, or cloud provider LB\n\n### Environment Variables\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `APP_ENV` | Application environment | `production` |\n| `DB_DIALECT` | Database type | `mysql` or `postgres` |\n| `DB_HOST` | Database host | `localhost` |\n| `DB_PORT` | Database port | `3306` |\n| `DB_DATABASE` | Database name | `nocobase` |\n| `DB_USER` | Database user | `nocobase` |\n| `DB_PASSWORD` | Database password | `***` |\n| `REDIS_URL` | Redis connection string | `redis://localhost:6379` |\n| `CACHE_STORAGE` | Cache storage type | `redis` |\n\n## Redis Plugins\n\nNocoBase requires two Redis plugins for cluster operation:\n\n### Lock Adapter (Redis)\n\nHandles distributed locking to prevent race conditions across instances.\n\n**Plugin**: `@nocobase/plugin-lock-adapter-redis`\n\n```bash\nnpm install @nocobase/plugin-lock-adapter-redis\n```\n\nConfiguration in `database.yml`:\n\n```yaml\nplugins:\n - name: lock\n options:\n type: redis\n redis:\n port: 6379\n host: localhost\n password: ''\n db: 0\n```\n\n### Pub/Sub Adapter (Redis)\n\nEnables real-time communication between instances for features like:\n\n- Live query updates\n- Real-time collaboration\n- Broadcast notifications\n\n**Plugin**: `@nocobase/plugin-pubsub-adapter-redis`\n\n```bash\nnpm install @nocobase/plugin-pubsub-adapter-redis\n```\n\n## Deployment Options\n\n### Docker Compose (Development/Testing)\n\n```yaml\nversion: '3.8'\nservices:\n app:\n image: nocobase/app:latest\n replicas: 3\n depends_on:\n - redis\n - db\n environment:\n - APP_ENV=production\n - DB_DIALECT=postgres\n - REDIS_URL=redis://redis:6379\n deploy:\n replicas: 3\n\n redis:\n image: redis:7-alpine\n ports:\n - \"6379:6379\"\n\n db:\n image: postgres:15\n environment:\n - POSTGRES_DB=nocobase\n - POSTGRES_USER=nocobase\n - POSTGRES_PASSWORD=nocobase\n```\n\n### Kubernetes Deployment\n\nFor production environments, Kubernetes provides:\n\n- Automatic scaling\n- Rolling updates\n- Self-healing capabilities\n- Service discovery\n\nRefer to the [Kubernetes Deployment Guide](kubernetes.md) for detailed configuration.\n\n## Configuration\n\n### Load Balancer Configuration (Nginx)\n\n```nginx\nupstream nocobase_backend {\n least_conn;\n server app1:13000 weight=5;\n server app2:13000 weight=5;\n server app3:13000 weight=5;\n}\n\nserver {\n listen 80;\n server_name your-domain.com;\n\n location / {\n proxy_pass http://nocobase_backend;\n proxy_http_version 1.1;\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection \"upgrade\";\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n }\n\n location /socket.io/ {\n proxy_pass http://nocobase_backend;\n proxy_http_version 1.1;\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection \"upgrade\";\n }\n}\n```\n\n### Application Configuration\n\nIn `data/source/database.yml`:\n\n```yaml\ndatabase:\n type: mysql\n ...\n pool: 10\n\nredis:\n host: redis-host\n port: 6379\n\nplugins:\n - '@nocobase/plugin-lock-adapter-redis'\n - '@nocobase/plugin-pubsub-adapter-redis'\n```\n\n## Operations\n\n### Health Checks\n\nConfigure health check endpoints on the load balancer:\n\n| Endpoint | Expected Response | Purpose |\n|----------|-------------------|---------|\n| `/api/health` | `200 OK` | Instance health status |\n| `/api/healthy` | `200 OK` | Readiness probe |\n\n### Scaling\n\n```mermaid\ngraph LR\n A[Request] --> B{Higher Load?}\n B -->|Yes| C[Scale Up Instances]\n B -->|No| D[Current Scale]\n C --> E[Update LB Pool]\n E --> A\n```\n\n### Monitoring\n\nKey metrics to monitor:\n\n- Request latency per instance\n- Database connection pool usage\n- Redis connection status\n- Session distribution\n- Error rates per instance\n\n### Rolling Updates\n\n1. Deploy new version to subset of instances\n2. Remove updated instances from LB pool temporarily\n3. Update remaining instances\n4. Restore full instance count\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| 502 Bad Gateway | All instances down | Check instance logs, restart services |\n| Stale data displayed | Cache inconsistency | Clear Redis cache, check pub/sub connectivity |\n| Lock contention | High concurrency | Increase Redis resources, optimize locking strategy |\n| WebSocket disconnection | Proxy timeout | Configure longer timeouts in load balancer |\n\n### Diagnostics\n\n```bash\n# Check instance connectivity\ncurl http://instance-ip:13000/api/health\n\n# Verify Redis connectivity\nredis-cli -h redis-host ping\n\n# Check database connectivity\nnpm run nocobase db:ping\n```\n\n## Best Practices\n\n1. **Stateless Design**: Ensure applications do not store user state locally\n2. **Session Management**: Use Redis-backed sessions for sticky sessions\n3. **Database Connection Pooling**: Configure appropriate pool sizes per instance\n4. **File Storage**: Use shared storage to ensure file consistency\n5. **Graceful Shutdown**: Configure proper shutdown handlers for rolling updates\n6. **Logging**: Centralize logs from all instances for debugging\n\n## Related Documentation\n\n- [Kubernetes Deployment](kubernetes.md)\n- [Development Setup](development.md)\n- [Operations Guide](operations.md)\n- [Preparations](preparations.md)\n- [Redis Lock Adapter Plugin](../plugins/@nocobase/plugin-lock-adapter-redis/index.md)\n- [Redis Pub/Sub Adapter Plugin](../plugins/@nocobase/plugin-pubsub-adapter-redis/index.md)\n\n---\n\n\n\n## Plugin Development\n\n### 相关页面\n\n相关主题：[Plugin System](#plugin-system), [System Architecture](#system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/client/src/pm/PluginDetail.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginDetail.tsx)\n- [packages/core/client/src/pm/PluginManagerLink.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginManagerLink.tsx)\n- [packages/core/client/src/application/utils/remotePlugins.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/application/utils/remotePlugins.ts)\n- [packages/core/client/src/nocobase-buildin-plugin/index.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/nocobase-buildin-plugin/index.tsx)\n
\n\n# Plugin Development\n\n## Overview\n\nNocoBase adopts a **plugin-based architecture** where every feature is implemented as a plugin. This modular design enables:\n\n- **Extensibility**: Add new functionality without modifying the core system\n- **Maintainability**: Features are isolated and independently deployable\n- **Reusability**: Plugins can be shared and reused across different projects\n- **Hot-loading**: Plugins can be loaded/unloaded at runtime\n\n```mermaid\ngraph TD\n A[NocoBase Core] --> B[Plugin System]\n B --> C[Server Plugins]\n B --> D[Client Plugins]\n C --> E[Database Operations]\n C --> F[API Routes]\n C --> G[Event Handlers]\n D --> H[UI Components]\n D --> I[Schema Initializers]\n D --> J[Schema Settings]\n```\n\n## Plugin Structure\n\nA typical NocoBase plugin follows this directory structure:\n\n```bash\nmy-plugin/\n├── src/\n│ ├── client/ # Client-side code\n│ │ ├── index.ts # Client plugin entry\n│ │ └── components/ # UI components\n│ ├── server/ # Server-side code\n│ │ ├── index.ts # Server plugin entry\n│ │ ├── actions/ # Custom actions\n│ │ └── migrations/ # Database migrations\n│ └── index.ts # Main entry (client + server)\n├── package.json\n└── dist/ # Build output\n └── externalVersion.js\n```\n\n## Plugin Types\n\n### Server Plugins\n\nServer plugins handle backend logic including database operations, API routes, and event handling.\n\n**Entry Point** (`src/server/index.ts`):\n\n```typescript\nimport { Plugin } from '@nocobase/server';\n\nexport default class MyPlugin extends Plugin {\n async load() {\n // Register collections\n this.app.collection({\n name: 'posts',\n fields: [\n { type: 'string', name: 'title' },\n { type: 'text', name: 'content' },\n ],\n });\n\n // Register API routes\n this.app.resourcer.define({\n name: 'posts',\n actions: {\n async list(ctx, next) {\n ctx.body = await ctx.db.getRepository('posts').find();\n await next();\n },\n },\n });\n }\n}\n\nPlugin.register(MyPlugin);\n```\n\n资料来源：[packages/core/client/src/pm/PluginDetail.tsx:1-50]()\n\n### Client Plugins\n\nClient plugins manage UI components, schema initializers, and schema settings.\n\n**Entry Point** (`src/client/index.ts`):\n\n```typescript\nimport { Plugin } from '@nocobase/client';\n\nexport default class MyPlugin extends Plugin {\n async load() {\n // Register schema initializer\n this.schemaInitializerManager.addItem(\n 'charts',\n 'my-plugin:item',\n {\n title: 'My Chart',\n component: 'MyChartComponent',\n }\n );\n\n // Register schema settings\n this.schemaSettingsManager.add('my-plugin:settings', {\n title: 'My Settings',\n items: [\n { name: 'title', component: 'Input' },\n { name: 'delete', type: 'danger' },\n ],\n });\n }\n}\n\nPlugin.register(MyPlugin);\n```\n\n资料来源：[packages/core/client/src/pm/PluginManagerLink.tsx:1-30]()\n\n## Remote Plugins\n\nNocoBase supports loading plugins remotely via require.js. Remote plugins are configured through the application settings and loaded on demand.\n\n**Configuration** (`src/application/utils/remotePlugins.ts`):\n\n```typescript\nexport function configRequirejs(requirejs: any, pluginData: PluginData[]) {\n requirejs.requirejs.config({\n waitSeconds: 120,\n paths: pluginData.reduce>((acc, cur) => {\n acc[cur.packageName] = cur.url;\n return acc;\n }, {}),\n });\n}\n\nexport function processRemotePlugins(\n pluginData: PluginData[], \n resolve: (plugins: [string, typeof Plugin][]) => void\n) {\n return (...pluginModules: (typeof Plugin & { default?: typeof Plugin })[]) => {\n const res: [string, typeof Plugin][] = pluginModules\n .map<[string, typeof Plugin]>((item, index) => [\n pluginData[index].name, \n item?.default || item\n ])\n .filter((item) => item[1]);\n resolve(res);\n };\n}\n```\n\nKey characteristics:\n- **Timeout**: 120 seconds wait time for plugin loading\n- **Path Mapping**: Maps package names to remote URLs\n- **Default Export**: Automatically handles both default and named exports\n\n资料来源：[packages/core/client/src/application/utils/remotePlugins.ts:40-70]()\n\n## Plugin Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> Registered\n Registered --> Loading\n Loading --> Loaded\n Loaded --> Enabled\n Enabled --> Disabled\n Disabled --> Enabled\n Enabled --> Unloaded\n Unloaded --> [*]\n```\n\n### Application States\n\nThe plugin system tracks various application states during initialization:\n\n| State Code | Status | Icon | Description |\n|------------|--------|------|-------------|\n| `APP_PREPARING` | info | LoadingOutlined | App preparing |\n| `APP_INITIALIZING` | info | LoadingOutlined | App initializing |\n| `APP_INITIALIZED` | info | - | App initialized |\n| `APP_NOT_INSTALLED_ERROR` | warning | - | App not installed |\n| `APP_STOPPED` | warning | - | App stopped |\n| `APP_COMMANDING` | info | LoadingOutlined | App commanding |\n| `ENOENT`, `APP_ERROR`, `LOAD_ERROR` | error | - | App error |\n\n资料来源：[packages/core/client/src/nocobase-buildin-plugin/index.tsx:1-60]()\n\n## Plugin Manager\n\nThe Plugin Manager provides a UI interface for managing plugins with the following features:\n\n### Plugin Detail Display\n\n```typescript\ninterface PluginDetailProps {\n plugin: {\n packageName: string;\n version: string;\n name: string;\n displayName?: string;\n description?: string;\n version?: string;\n };\n data?: {\n packageJson: {\n license?: string;\n };\n homepage?: string;\n depsCompatible: boolean | null;\n isCompatible: boolean;\n };\n}\n```\n\nThe plugin detail view displays:\n\n- **Package Name**: Unique identifier for the plugin\n- **Version**: Current installed version\n- **Display Name**: Human-readable name\n- **Description**: Plugin functionality description\n- **License**: Package license type\n- **Homepage**: External documentation URL\n- **Dependencies**: Compatibility status\n\n资料来源：[packages/core/client/src/pm/PluginDetail.tsx:1-100]()\n\n### Dependencies Compatibility Check\n\n```typescript\n{\n key: 'dependencies',\n label: t('Dependencies compatibility check'),\n children: (\n <>\n {data?.data?.depsCompatible === false ? (\n \n {t('`dist/externalVersion.js` not found or failed to `require`. Please rebuild this plugin.')}\n \n ) : (\n <>\n {!data?.data?.['isCompatible'] && (\n \n )}\n \n \n )}\n \n ),\n}\n```\n\n| Check Type | Condition | Message |\n|------------|-----------|---------|\n| Build Required | `dist/externalVersion.js` not found | Rebuild plugin required |\n| Compatibility | `isCompatible === false` | Dependency version mismatch |\n| Success | All checks pass | Dependencies compatible |\n\n资料来源：[packages/core/client/src/pm/PluginDetail.tsx:20-45]()\n\n## Plugin Settings\n\nPlugins can register their own settings pages in the administration interface:\n\n```typescript\nconst settingItems = settings\n .filter((setting) => setting.visible !== false)\n .map((setting) => {\n return {\n key: setting.name,\n icon: setting.icon,\n label: setting.link ? (\n
window.open(setting.link)}>\n {compile(setting.title)}\n
\n ) : (\n {compile(setting.title)}\n ),\n };\n });\n```\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `name` | string | Unique setting identifier |\n| `title` | string | Display title |\n| `icon` | ReactNode | Setting icon |\n| `path` | string | Navigation route |\n| `link` | string | External link (optional) |\n| `visible` | boolean | Visibility control |\n\n资料来源：[packages/core/client/src/pm/PluginManagerLink.tsx:1-50]()\n\n## Building Plugins\n\n### Build Output Requirements\n\nAfter building a plugin, ensure the following files exist in the `dist/` directory:\n\n```\ndist/\n├── index.js\n├── client.js\n├── server.js\n└── externalVersion.js # Required for compatibility\n```\n\nThe `externalVersion.js` file exports version information for dependency compatibility checks.\n\n### Remote Plugin Loading\n\n```typescript\ninterface PluginData {\n packageName: string;\n url: string;\n name: string;\n}\n```\n\nPlugins loaded remotely must:\n1. Export a default class extending `Plugin`\n2. Be accessible via the configured URL\n3. Include `externalVersion.js` for dependency validation\n\n资料来源：[packages/core/client/src/application/utils/remotePlugins.ts:1-40]()\n\n## Error Handling\n\n### Plugin Load Errors\n\nWhen plugins fail to load, the system logs detailed error messages:\n\n```typescript\nif (emptyPlugins.length > 0) {\n console.error(\n '[nocobase load plugin error]: These plugins do not have an `export.default` exported content or there is an error in the plugins. error plugins: \\r\\n%s',\n emptyPlugins.join(', \\r\\n'),\n );\n}\n```\n\nCommon error causes:\n- Missing `export default` in the plugin entry\n- Syntax errors in plugin code\n- Circular dependency issues\n- Timeout during remote plugin loading\n\n### App Error States\n\n| Error Code | Severity | Resolution |\n|------------|----------|------------|\n| `ENOENT` | error | Check file paths and build output |\n| `APP_ERROR` | error | Review application logs |\n| `LOAD_ERROR` | error | Verify plugin exports and dependencies |\n| `APP_NOT_INSTALLED` | warning | Run installation command |\n| `APP_STOPPED` | warning | Restart the application |\n\n资料来源：[packages/core/client/src/nocobase-buildin-plugin/index.tsx:40-55]()\n\n## Schema Integration\n\nPlugins can extend the application schema system by registering:\n\n### Schema Initializers\n\nEnable adding new items to schema initialization panels:\n\n```typescript\nthis.schemaInitializerManager.addItem(\n scope: string, // Parent group identifier\n key: string, // Unique item key\n item: SchemaInitializerItem // Item configuration\n);\n```\n\n### Schema Settings\n\nAdd configuration panels for schema components:\n\n```typescript\nthis.schemaSettingsManager.add(\n name: string,\n config: SchemaSettingsConfig\n);\n```\n\n## Best Practices\n\n1. **Always export default**: Plugin classes must use `export default` for proper loading\n2. **Include externalVersion.js**: Required for dependency compatibility checks\n3. **Handle errors gracefully**: Wrap async operations in try-catch blocks\n4. **Use unique namespacing**: Prefix plugin-specific names with plugin name\n5. **Document dependencies**: Clearly specify version requirements in package.json\n\n## Related Documentation\n\n- [Write Your First Plugin](write-your-first-plugin.md)\n- [Server Development](server/index.md)\n- [Client Development](client/index.md)\n- [Dependency Management](dependency-management.md)\n- [Building Plugins](build.md)\n- [Internationalization](languages.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：nocobase/nocobase\n\n摘要：发现 17 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：REST API: Multiple select field not working in edit form。\n\n## 1. 安全/权限坑 · 来源证据：REST API: Multiple select field not working in edit form\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：REST API: Multiple select field not working in edit form\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_36b6b605781f4652849d06443cd76da9 | https://github.com/nocobase/nocobase/issues/8836 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：v2.1.0-alpha.33\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0-alpha.33\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_71fc97aec74e43618fab9e19d0aa9a9f | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.33 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：v2.1.0-beta.30\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0-beta.30\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3eea74dae9c548fc8058563df21058d3 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.30 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 配置坑 · 来源证据：v2.0.51\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.0.51\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_06f3ce01049e42f586931cf6e9a46335 | https://github.com/nocobase/nocobase/releases/tag/v2.0.51 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 配置坑 · 来源证据：v2.1.0-alpha.32\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.1.0-alpha.32\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7055255c88f94ecc84dfc5c09fc6c3a3 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.32 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 配置坑 · 来源证据：v2.1.0-beta.29\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.1.0-beta.29\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c4b7dfdc1a164f5cb82fec5622b80342 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.29 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 能力坑 · 能力判断依赖假设\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:306829688 | https://github.com/nocobase/nocobase | README/documentation is current enough for a first validation pass.\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:306829688 | https://github.com/nocobase/nocobase | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:306829688 | https://github.com/nocobase/nocobase | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:306829688 | https://github.com/nocobase/nocobase | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 11. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:306829688 | https://github.com/nocobase/nocobase | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 来源证据：v2.0.52\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.52\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1ca2b2aac82447ea8ca5b5536fff978e | https://github.com/nocobase/nocobase/releases/tag/v2.0.52 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：v2.1.0-alpha.31\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0-alpha.31\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7a2bc590f0974b79880f86db553b3a2e | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.31 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：v2.1.0-beta.27\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0-beta.27\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_43d1bbbbee81474cb8e2e4f722fdb398 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.27 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：v2.1.0-beta.32\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0-beta.32\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_31e3065c9e884205a29f181cbbc50458 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.32 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · 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:306829688 | https://github.com/nocobase/nocobase | issue_or_pr_quality=unknown\n\n## 17. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:306829688 | https://github.com/nocobase/nocobase | release_recency=unknown\n\n\n", "markdown_key": "nocobase", "pages": "draft", "source_refs": [ { "evidence_id": "github_repo:306829688", "kind": "repo", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/nocobase/nocobase" }, { "evidence_id": "art_caaf91f38ff941e1b9d8887e1efd896c", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/nocobase/nocobase#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "nocobase 说明书", "toc": [ "https://github.com/nocobase/nocobase 项目说明书", "目录", "Overview", "Architecture Overview", "Data Model Architecture", "User Interface System", "Variable System", "Plugin System", "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": "4235a0146f8dc0a3b92261c2bfac9ba2c1060713", "repo_inspection_error": null, "repo_inspection_files": [ "Dockerfile", "package.json", "README.md", "docker-compose.yml", "docs/package.json", "docs/README.md", "docs/locales.ts", "docs/tsconfig.json", "docs/biome.json", "docs/rspress.config.ts", "docs/plugins/pluginOgDescription.ts", "docs/plugins/pluginRemoveGenerator.ts", "docs/theme/utils.ts", "docs/docs/de/index.md", "docs/docs/de/_nav.json", "docs/docs/ja/index.md", "docs/docs/ja/_nav.json", "docs/docs/es/index.md", "docs/docs/es/_nav.json", "docs/docs/fr/index.md", "docs/docs/fr/_nav.json", "docs/docs/ar/index.md", "docs/docs/ar/_nav.json", "docs/docs/pt/index.md", "docs/docs/pt/_nav.json", "docs/docs/en/index.md", "docs/docs/en/_nav.json", "docs/docs/ru/index.md", "docs/docs/ru/_nav.json", "docs/docs/ko/index.md", "docs/docs/ko/_nav.json", "docs/docs/cn/index.md", "docs/docs/cn/_nav.json", "docs/docs/de/solution/_meta.json", "docs/docs/de/flow-engine/flow-engine-and-plugins.md", "docs/docs/de/flow-engine/what-is-flow-engine.md", "docs/docs/de/flow-engine/flow-definition.md", "docs/docs/de/flow-engine/flow-context.md", "docs/docs/de/flow-engine/index.md", "docs/docs/de/flow-engine/create-mock-client.md" ], "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": "# nocobase - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 nocobase 编译的 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- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`docs/docs/de/ai-employees/advanced/skill.md`, `docs/docs/es/ai-employees/advanced/skill.md`, `docs/docs/fr/ai-employees/advanced/skill.md`, `docs/docs/ja/ai-employees/advanced/skill.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `npm install -g @nocobase/cli@beta` 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：仅建议沙盒试装\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：仅建议沙盒试装\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`docs/docs/de/ai-employees/advanced/skill.md`, `docs/docs/es/ai-employees/advanced/skill.md`, `docs/docs/fr/ai-employees/advanced/skill.md`, `docs/docs/ja/ai-employees/advanced/skill.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`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）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`docs/docs/de/ai-employees/advanced/skill.md`, `docs/docs/es/ai-employees/advanced/skill.md`, `docs/docs/fr/ai-employees/advanced/skill.md`, `docs/docs/ja/ai-employees/advanced/skill.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`docs/docs/de/ai-employees/advanced/skill.md`, `docs/docs/es/ai-employees/advanced/skill.md`, `docs/docs/fr/ai-employees/advanced/skill.md`, `docs/docs/ja/ai-employees/advanced/skill.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`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_0005` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0006` 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 体验。 证据：`docs/docs/de/ai-employees/advanced/skill.md`, `docs/docs/es/ai-employees/advanced/skill.md`, `docs/docs/fr/ai-employees/advanced/skill.md`, `docs/docs/ja/ai-employees/advanced/skill.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：18353\n- 重要文件覆盖：40/18353\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请基于 nocobase 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 nocobase 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 nocobase 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 7 个角色 / Skill / 项目文档条目。\n\n- **Erweitert**（skill）：:::tip KI-Übersetzungshinweis Diese Dokumentation wurde automatisch von KI übersetzt. ::: 激活提示：当用户任务与“Erweitert”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`docs/docs/de/ai-employees/advanced/skill.md`\n- **Avanzado**（skill）：:::tip Aviso de traducción por IA Esta documentación ha sido traducida automáticamente por IA. ::: 激活提示：当用户任务与“Avanzado”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`docs/docs/es/ai-employees/advanced/skill.md`\n- **Avancé**（skill）：:::tip Avis de traduction IA Cette documentation a été traduite automatiquement par IA. ::: 激活提示：当用户任务与“Avancé”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`docs/docs/fr/ai-employees/advanced/skill.md`\n- **応用**（skill）：:::tip このドキュメントはAIによって翻訳されました。不正確な情報については、 英語版 /en をご参照ください ::: 激活提示：当用户任务与“応用”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`docs/docs/ja/ai-employees/advanced/skill.md`\n- **고급**（skill）：:::tip 이 문서는 AI로 번역되었습니다. 부정확한 내용이 있을 경우 영어 버전 /en 을 참조하세요 ::: 激活提示：当用户任务与“고급”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`docs/docs/ko/ai-employees/advanced/skill.md`\n- **Avançado**（skill）：:::tip Aviso de tradução por IA Esta documentação foi traduzida automaticamente por IA. ::: 激活提示：当用户任务与“Avançado”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`docs/docs/pt/ai-employees/advanced/skill.md`\n- **Расширенные возможности**（skill）：:::tip Уведомление о переводе ИИ Эта документация была автоматически переведена ИИ. ::: 激活提示：当用户任务与“Расширенные возможности”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`docs/docs/ru/ai-employees/advanced/skill.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **NocoBase Documentation**（documentation）：NocoBase Documentation --lang --check-dead-links 证据：`docs/README.md`\n- **安装插件**（documentation）：详细的安装与升级方式请参考： 商业插件激活指南 https://www.nocobase.com/cn/blog/nocobase-commercial-license-activation-guide 证据：`docs/docs/cn/template-print/install.md`\n- **Erweitert**（skill_instruction）：:::tip KI-Übersetzungshinweis Diese Dokumentation wurde automatisch von KI übersetzt. ::: 证据：`docs/docs/de/ai-employees/advanced/skill.md`\n- **Plugins installieren**（documentation）：:::tip KI-Übersetzungshinweis Diese Dokumentation wurde automatisch von KI übersetzt. ::: 证据：`docs/docs/de/template-print/install.md`\n- **Install Plugins**（documentation）：For detailed installation and upgrade instructions, please refer to: Commercial Plugin Activation Guide https://www.nocobase.com/en/blog/nocobase-commercial-license-activation-guide 证据：`docs/docs/en/template-print/install.md`\n- **Avanzado**（skill_instruction）：:::tip Aviso de traducción por IA Esta documentación ha sido traducida automáticamente por IA. ::: 证据：`docs/docs/es/ai-employees/advanced/skill.md`\n- **Instalar plugins**（documentation）：:::tip Aviso de traducción por IA Esta documentación ha sido traducida automáticamente por IA. ::: 证据：`docs/docs/es/template-print/install.md`\n- **Avancé**（skill_instruction）：:::tip Avis de traduction IA Cette documentation a été traduite automatiquement par IA. ::: 证据：`docs/docs/fr/ai-employees/advanced/skill.md`\n- **Installation des plugins**（documentation）：:::tip Avis de traduction IA Cette documentation a été traduite automatiquement par IA. ::: 证据：`docs/docs/fr/template-print/install.md`\n- **応用**（skill_instruction）：:::tip このドキュメントはAIによって翻訳されました。不正確な情報については、 英語版 /en をご参照ください ::: 证据：`docs/docs/ja/ai-employees/advanced/skill.md`\n- **プラグインのインストール**（documentation）：:::tip このドキュメントはAIによって翻訳されました。不正確な情報については、 英語版 /en をご参照ください ::: 证据：`docs/docs/ja/template-print/install.md`\n- **고급**（skill_instruction）：:::tip 이 문서는 AI로 번역되었습니다. 부정확한 내용이 있을 경우 영어 버전 /en 을 참조하세요 ::: 证据：`docs/docs/ko/ai-employees/advanced/skill.md`\n- **플러그인 설치**（documentation）：:::tip 이 문서는 AI로 번역되었습니다. 부정확한 내용이 있을 경우 영어 버전 /en 을 참조하세요 ::: 证据：`docs/docs/ko/template-print/install.md`\n- **Avançado**（skill_instruction）：:::tip Aviso de tradução por IA Esta documentação foi traduzida automaticamente por IA. ::: 证据：`docs/docs/pt/ai-employees/advanced/skill.md`\n- **Instalar Plugins**（documentation）：:::tip Aviso de tradução por IA Esta documentação foi traduzida automaticamente por IA. ::: 证据：`docs/docs/pt/template-print/install.md`\n- **Расширенные возможности**（skill_instruction）：:::tip Уведомление о переводе ИИ Эта документация была автоматически переведена ИИ. ::: 证据：`docs/docs/ru/ai-employees/advanced/skill.md`\n- **Установка плагинов**（documentation）：:::tip Уведомление о переводе ИИ Эта документация была автоматически переведена ИИ. ::: 证据：`docs/docs/ru/template-print/install.md`\n- **Table of Contents**（documentation）：English 简体中文 ./README.zh-CN.md 日本語 ./README.ja-JP.md Français ./README.fr.md Español ./README.es.md Português ./README.pt.md Bahasa Indonesia ./README.id.md Tiếng Việt ./README.vi.md Deutsch ./README.de.md 证据：`README.md`\n- **koa-database**（documentation）：koa-database koa-sequelize nocobase-server koa-resourcer nocobase-app 证据：`benchmark/README.md`\n- **NocoBase Locales**（documentation）：Language Code Language ------------- -------------- ar-EG العربية az-AZ Azərbaycan dili bg-BG Български bn-BD Bengali by-BY Беларускі ca-ES Сatalà/Espanya cs-CZ Česky da-DK Dansk de-DE ./de-DE.json Deutsch el-GR Ελληνικά en-GB English GB en-US ./en-US.json English es-ES ./es-ES.json Español et-EE Estonian Eesti fa-IR فارسی fi-FI Suomi fr-BE Français BE fr-CA Français CA fr-FR ./fr-FR.json Français ga-IE Gaeilge gl-ES Galego he-IL עברית hi-IN हिन्दी hr-HR Hrvatski jezik hu-HU Magyar hy-AM Հայերեն id-ID ./id-ID.json Bahasa Indonesia is-IS Íslenska it-IT ./it-IT.json Italiano ja-JP ./ja-JP.json 日本語 ka-GE ქართული kk-KZ Қазақ тілі km-KH ភាសាខ្មែរ kn-IN ಕನ್ನಡ ko-KR ./ko-KR.json 한국어 ku-IQ کوردی lt… 证据：`locales/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/acl/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/actions/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/ai/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/app/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/auth/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/build/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/cache/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/cli/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/client-v2/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/client/README.md`\n- **useVariables**（documentation）：ts const { registerVariable, parseVariable } = useVariables ; 证据：`packages/core/client/src/variables/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/create-nocobase-app/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/data-source-manager/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/database/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/devtools/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/evaluators/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/flow-engine/README.md`\n- **Grid 拖拽设计 / Grid Drag Planner**（documentation）：zh-CN 版本在前，English version follows after each section. 证据：`packages/core/flow-engine/src/components/dnd/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/lock-manager/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/logger/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/resourcer/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/sdk/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/server/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/shared/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/snowflake-id/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/telemetry/README.md`\n- **NocoBase**（documentation）：NocoBase is the most extensible AI-powered no-code platform. Total control. Infinite extensibility. AI collaboration. Enable your team to adapt quickly and cut costs dramatically. No years of development. No millions wasted. Deploy NocoBase in minutes — and take control of everything. 证据：`packages/core/utils/README.md`\n- **插件示例**（documentation）：插件名 插件描述 包名 -------------------- ---- ----------------------------------------------- 简易区块 @nocobase-example/plugin-simple-block 数据表区块 @nocobase-example/plugin-collection-block 数据区块 @nocobase-example/plugin-data-block 区块子菜单展示 @nocobase-example/plugin-nested-block 自定义详情区块 @nocobase-example/plugin-custom-details-block 自定义表单区块 @nocobase-example/plugin-custom-form-block 自定义表格区块 @nocobase-example/plugin-custom-table-block 证据：`packages/plugins/@nocobase-example/README.md`\n- **@nocobase-example/plugin-acl-allow**（documentation）：@nocobase-example/plugin-acl-allow 证据：`packages/plugins/@nocobase-example/plugin-acl-allow/README.md`\n- **@nocobase-example/plugin-acl-middleware**（documentation）：@nocobase-example/plugin-acl-middleware 证据：`packages/plugins/@nocobase-example/plugin-acl-middleware/README.md`\n- **@nocobase-example/plugin-action-group**（documentation）：@nocobase-example/plugin-action-group 证据：`packages/plugins/@nocobase-example/plugin-action-group/README.md`\n- **@nocobase-example/plugin-block-custom-resource**（documentation）：@nocobase-example/plugin-block-custom-resource 证据：`packages/plugins/@nocobase-example/plugin-block-custom-resource/README.md`\n- **@nocobase-example/plugin-block-filter-collection**（documentation）：@nocobase-example/plugin-block-filter-collection 证据：`packages/plugins/@nocobase-example/plugin-block-filter-collection/README.md`\n- **@nocobase-example/plugin-block-timeline**（documentation）：@nocobase-example/plugin-block-timeline 证据：`packages/plugins/@nocobase-example/plugin-block-timeline/README.md`\n- **@nocobase-example/plugin-collection-block**（documentation）：@nocobase-example/plugin-collection-block 证据：`packages/plugins/@nocobase-example/plugin-collection-block/README.md`\n- **@nocobase-example/plugin-custom-details-block**（documentation）：@nocobase-example/plugin-custom-details-block 证据：`packages/plugins/@nocobase-example/plugin-custom-details-block/README.md`\n- **@nocobase-example/plugin-custom-form-block**（documentation）：@nocobase-example/plugin-custom-form-block 证据：`packages/plugins/@nocobase-example/plugin-custom-form-block/README.md`\n- **@nocobase-example/plugin-custom-table-block-action-group**（documentation）：@nocobase-example/plugin-custom-table-block-action-group 证据：`packages/plugins/@nocobase-example/plugin-custom-table-block-action-group/README.md`\n- **@nocobase-example/plugin-custom-table-block-field**（documentation）：@nocobase-example/plugin-custom-table-block-field 证据：`packages/plugins/@nocobase-example/plugin-custom-table-block-field/README.md`\n- **@nocobase-example/plugin-custom-table-block-resource**（documentation）：@nocobase-example/plugin-custom-table-block-resource 证据：`packages/plugins/@nocobase-example/plugin-custom-table-block-resource/README.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/README.md`, `docs/docs/cn/template-print/install.md`, `docs/docs/de/ai-employees/advanced/skill.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/README.md`, `docs/docs/cn/template-print/install.md`, `docs/docs/de/ai-employees/advanced/skill.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- **Overview**：importance `high`\n - source_paths: README.md, docs/README.md, docs/docs/en/index.md\n- **System Architecture**：importance `high`\n - source_paths: docs/docs/en/get-started/how-nocobase-works.mdx, docs/docs/en/database/index.md, docs/docs/en/plugin-development/project-structure.md\n- **Deployment**：importance `high`\n - source_paths: docker-compose.yml, Dockerfile, docker/nocobase/Dockerfile, docker/app-postgres/docker-compose.yml, docker/app-mysql/docker-compose.yml\n- **Plugin System**：importance `high`\n - source_paths: docs/docs/en/plugin-development/index.md, docs/docs/en/plugin-development/server/plugin.md, docs/docs/en/plugin-development/client/plugin.md, docs/docs/en/plugin-development/lifecycle.md, docs/docs/en/plugins/index.mdx\n- **Data Modeling**：importance `high`\n - source_paths: docs/docs/en/data-sources/data-modeling/collection.md, docs/docs/en/data-sources/data-modeling/collection-fields/index.md, docs/docs/en/data-sources/data-source-manager/index.md, docs/docs/en/api/database/collection.md, docs/docs/en/api/database/field.md\n- **Interface Builder**：importance `high`\n - source_paths: docs/docs/en/interface-builder/index.md, docs/docs/en/interface-builder/blocks/index.md, docs/docs/en/interface-builder/fields/index.md, docs/docs/en/interface-builder/actions/index.md, docs/docs/en/interface-builder/variables.md\n- **Workflow Engine**：importance `high`\n - source_paths: docs/docs/en/workflow/index.md, docs/docs/en/workflow/nodes/index.md, docs/docs/en/workflow/triggers/index.md, docs/docs/en/flow-engine/index.md, docs/docs/en/plugins/@nocobase/plugin-workflow/index.md\n- **Authentication and Permissions**：importance `high`\n - source_paths: docs/docs/en/auth-verification/index.md, docs/docs/en/users-permissions/acl/permissions.md, docs/docs/en/users-permissions/index.md, docs/docs/en/plugins/@nocobase/plugin-acl/index.md, docs/docs/en/plugins/@nocobase/plugin-auth/index.md\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `4235a0146f8dc0a3b92261c2bfac9ba2c1060713`\n- inspected_files: `Dockerfile`, `package.json`, `README.md`, `docker-compose.yml`, `docs/package.json`, `docs/README.md`, `docs/locales.ts`, `docs/tsconfig.json`, `docs/biome.json`, `docs/rspress.config.ts`, `docs/plugins/pluginOgDescription.ts`, `docs/plugins/pluginRemoveGenerator.ts`, `docs/theme/utils.ts`, `docs/docs/de/index.md`, `docs/docs/de/_nav.json`, `docs/docs/ja/index.md`, `docs/docs/ja/_nav.json`, `docs/docs/es/index.md`, `docs/docs/es/_nav.json`, `docs/docs/fr/index.md`\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: 来源证据：REST API: Multiple select field not working in edit form\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：REST API: Multiple select field not working in edit form\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_36b6b605781f4652849d06443cd76da9 | https://github.com/nocobase/nocobase/issues/8836 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：v2.1.0-alpha.33\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0-alpha.33\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_71fc97aec74e43618fab9e19d0aa9a9f | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.33 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：v2.1.0-beta.30\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0-beta.30\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_3eea74dae9c548fc8058563df21058d3 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.30 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：v2.0.51\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.0.51\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_06f3ce01049e42f586931cf6e9a46335 | https://github.com/nocobase/nocobase/releases/tag/v2.0.51 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：v2.1.0-alpha.32\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.1.0-alpha.32\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_7055255c88f94ecc84dfc5c09fc6c3a3 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.32 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v2.1.0-beta.29\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.1.0-beta.29\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_c4b7dfdc1a164f5cb82fec5622b80342 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.29 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:306829688 | https://github.com/nocobase/nocobase | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:306829688 | https://github.com/nocobase/nocobase | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:306829688 | https://github.com/nocobase/nocobase | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: risks.safety_notes | github_repo:306829688 | https://github.com/nocobase/nocobase | No sandbox install has been executed yet; downstream must verify before user use.\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项目：nocobase/nocobase\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- 来源证据：REST API: Multiple select field not working in edit form（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：v2.1.0-alpha.33（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v2.1.0-beta.30（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v2.0.51（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v2.1.0-alpha.32（medium）：可能影响升级、迁移或版本选择。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\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/nocobase/nocobase 项目说明书\n\n生成时间：2026-05-18 02:07:18 UTC\n\n## 目录\n\n- [Overview](#overview)\n- [System Architecture](#system-architecture)\n- [Deployment](#deployment)\n- [Plugin System](#plugin-system)\n- [Data Modeling](#data-modeling)\n- [Interface Builder](#interface-builder)\n- [Workflow Engine](#workflow-engine)\n- [Authentication and Permissions](#authentication-permissions)\n- [AI Integration](#ai-integration)\n- [File Storage](#file-storage)\n- [Cluster Mode](#cluster-mode)\n- [Plugin Development](#plugin-development)\n\n\n\n## Overview\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [Plugin System](#plugin-system), [AI Integration](#ai-integration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/nocobase/nocobase/blob/main/README.md)\n- [docs/README.md](https://github.com/nocobase/nocobase/blob/main/docs/README.md)\n- [docs/docs/en/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/index.md)\n- [packages/core/client/src/schema-initializer/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-initializer/index.md)\n- [packages/core/client/src/schema-component/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/index.md)\n- [packages/core/flow-engine/src/flowSettings.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/flowSettings.ts)\n- [packages/core/client/src/variables/hooks/useBuiltinVariables.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/variables/hooks/useBuiltinVariables.ts)\n- [packages/plugins/@nocobase/plugin-mobile/src/client/pages/index.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-mobile/src/client/pages/index.md)\n- [packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/chatbox/stores/chat-messages.ts](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/chatbox/stores/chat-messages.ts)\n
\n\n# Overview\n\nNocoBase is an open-source **NoCode/LowCode platform** that enables users to build scalable business applications through a visual interface without writing code. It provides a comprehensive system for creating data models, designing user interfaces, configuring business workflows, and extending functionality through a plugin-based architecture.\n\n## Architecture Overview\n\nNocoBase follows a modern full-stack architecture with clear separation between client and server components. The platform is built on a plugin-based architecture that allows for flexible extension and customization.\n\n```mermaid\ngraph TD\n Client[\"Client (React)\"]\n Server[\"Server (Node.js)\"]\n Database[\"Database\"]\n Client --> Server\n Server --> Database\n \n subgraph Client\n UI[\"UI Components\"]\n Schema[\"Schema System\"]\n Variables[\"Variable System\"]\n PM[\"Plugin Manager\"]\n end\n \n subgraph Server\n API[\"API Layer\"]\n FlowEngine[\"Flow Engine\"]\n Plugins[\"Plugin System\"]\n end\n \n subgraph Plugins\n Mobile[\"Mobile Plugin\"]\n AI[\"AI Plugin\"]\n ThemeEditor[\"Theme Editor Plugin\"]\n end\n```\n\n### Core Components\n\n| Component | Description | Location |\n|-----------|-------------|----------|\n| Schema System | Declarative UI and data structure definition | `packages/core/client/src/schema-component/` |\n| Flow Engine | Business workflow execution engine | `packages/core/flow-engine/` |\n| Plugin Manager | Dynamic plugin loading and management | `packages/core/client/src/pm/` |\n| Variable System | Runtime variable resolution and context | `packages/core/client/src/variables/` |\n| Schema Initializer | Visual block insertion and configuration | `packages/core/client/src/schema-initializer/` |\n| Schema Settings | Configuration panel for schema blocks | `packages/core/client/src/schema-settings/` |\n\n资料来源：[packages/core/client/src/schema-component/index.md:1]()\n\n## Data Model Architecture\n\nNocoBase uses a schema-based approach for defining data models and user interfaces. Collections represent database tables, and fields define the structure of data entries.\n\n```mermaid\ngraph LR\n Collection[\"Collection
(Data Model)\"]\n Field[\"Field
(Column Definition)\"]\n Association[\"Association
(Relationship)\"]\n Schema[\"Schema
(UI Configuration)\"]\n \n Collection --> Field\n Collection --> Association\n Schema --> Collection\n```\n\nThe system supports multiple data types and associations, enabling complex business data modeling scenarios.\n\n资料来源：[packages/core/client/src/schema-component/antd/association-select/index.md:1]()\n\n## User Interface System\n\n### Schema Component Architecture\n\nThe UI in NocoBase is built using a **Schema-based Component System**. Each UI element is defined through a schema configuration that describes its type, properties, and behavior.\n\n#### Built-in Components\n\nNocoBase provides several built-in components ready for use:\n\n| Component | Purpose | Location |\n|-----------|---------|----------|\n| `GeneralSchemaDesigner` | Main schema designer wrapper | `packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx` |\n| `LinkageFilter` | Frontend linkage rules and condition configuration | `packages/core/client/src/schema-component/antd/linkageFilter/index.md` |\n| `AssociationSelect` | Data selection linked to collections and fields | `packages/core/client/src/schema-component/antd/association-select/index.md` |\n\n#### Schema Designer Features\n\nThe schema designer provides visual editing capabilities for:\n\n- **Drag and Drop**: Rearrange schema blocks within the interface\n- **Designable Toggle**: Switch between view and edit modes\n- **Initializer Integration**: Insert new schema blocks dynamically\n- **Settings Panel**: Configure properties of selected blocks\n\n```mermaid\ngraph TD\n User[\"User\"] --> Designer[\"Schema Designer\"]\n Designer --> Drag[\"Drag & Drop\"]\n Designer --> Initializer[\"Schema Initializer\"]\n Designer --> Settings[\"Schema Settings\"]\n \n Drag --> Block1[\"Block 1\"]\n Drag --> Block2[\"Block 2\"]\n Initializer --> Block3[\"New Block\"]\n Settings --> Config[\"Configuration\"]\n```\n\n资料来源：[packages/core/client/src/schema-component/index.md:1]()\n\n### Schema Initializer\n\nThe Schema Initializer enables dynamic insertion of schema blocks into the design canvas. It supports:\n\n- **Built-in Types**: Pre-configured component templates\n- **Dynamic Visibility**: Show/hide items based on conditions\n- **Dynamic Children**: Load child items on demand\n- **Insert Schema**: Insert complete schema structures including actions and form items\n\n资料来源：[packages/core/client/src/schema-initializer/index.md:1]()\n\n## Variable System\n\nVariables provide dynamic data context for formulas, conditions, and display values throughout the application. NocoBase includes a comprehensive built-in variable system.\n\n### Built-in Variables\n\n| Variable | Description | Type |\n|----------|-------------|------|\n| `$date` | Current date (deprecated, use `$nDate`) | DateTime |\n| `$nDate` | Current date in ISO format | DateTime |\n| `$nExactDate` | Exact current datetime | DateTime |\n| `$system` | System context with `now()` function (deprecated) | Object |\n| `$nRole` | Current user's role information | Object |\n| `$nUser` | Current authenticated user details | Object |\n| `currentTime` | Current timestamp (deprecated) | String |\n| URL Parameters | Query string variables | Various |\n\n### Variable Resolution Flow\n\n```mermaid\ngraph LR\n Request[\"Request Context\"]\n Resolver[\"Variable Resolver\"]\n Context[\"Context Variables\"]\n Output[\"Resolved Values\"]\n \n Request --> Resolver\n Context --> Resolver\n Resolver --> Output\n```\n\nVariables are evaluated at runtime and support context-dependent values from:\n\n- Current user session\n- Current role permissions\n- URL query parameters\n- Environment variables\n- Date/time calculations\n\n资料来源：[packages/core/client/src/variables/hooks/useBuiltinVariables.ts:1]()\n\n## Plugin System\n\nNocoBase adopts a **plugin-first architecture**. All features are implemented as plugins that can be dynamically loaded, enabled, disabled, and configured.\n\n### Plugin Manager\n\nThe Plugin Manager (`pm`) handles plugin lifecycle operations:\n\n| Operation | Description |\n|-----------|-------------|\n| Install | Add new plugin to the system |\n| Uninstall | Remove plugin from the system |\n| Enable | Activate plugin functionality |\n| Disable | Deactivate plugin without removal |\n| Configure | Manage plugin-specific settings |\n\n```mermaid\ngraph TD\n PM[\"Plugin Manager\"]\n Store[\"Plugin Store\"]\n Loader[\"Plugin Loader\"]\n Registry[\"Plugin Registry\"]\n \n PM --> Store\n PM --> Loader\n PM --> Registry\n Loader --> Plugin[\"Plugin Instance\"]\n Registry --> Plugin\n```\n\n### Plugin Detail View\n\nEach plugin displays comprehensive information:\n\n- **Package Name**: Unique plugin identifier\n- **Version**: Semantic version number\n- **Description**: Plugin functionality summary\n- **Homepage**: Documentation or project URL\n- **Author**: Plugin maintainer information\n- **License**: Legal usage terms\n- **Dependencies**: Compatibility check with core system\n\n资料来源：[packages/core/client/src/pm/PluginDetail.tsx:1]()\n\n### Available Plugin Categories\n\n| Category | Examples | Purpose |\n|----------|----------|---------|\n| Mobile | `@nocobase/plugin-mobile` | Mobile-specific UI and navigation |\n| AI | `@nocobase/plugin-ai` | AI-powered features and assistants |\n| Theme | `@nocobase/plugin-theme-editor` | Visual theme customization |\n| Workflow | Flow Engine | Business process automation |\n\n## Mobile Support\n\nThe Mobile plugin provides responsive interfaces and navigation optimized for mobile devices.\n\n### Desktop Mode\n\nWhen accessing mobile pages from a desktop browser, the `DesktopMode` component renders a responsive wrapper:\n\n```tsx\n\n \n\n```\n\n### Page Types\n\n| Page Type | Description |\n|-----------|-------------|\n| Home Page | Default landing page; redirects to first route if not configured |\n| NotFound Page | 404 error page for unmatched routes |\n| Custom Pages | User-defined pages with custom components |\n\n#### Home Page Modes\n\n- **Basic**: Default empty home page\n- **Custom Home**: User-defined home page component\n- **No Routes**: Configuration without any routes\n\n资料来源：[packages/plugins/@nocobase/plugin-mobile/src/client/pages/index.md:1]()\n\n### Mobile Navigation\n\nThe `MobileTabBar` component provides tab-based navigation with `Bar.Item` elements:\n\n```mermaid\ngraph LR\n TabBar[\"MobileTabBar\"]\n BarItem[\"Bar.Item\"]\n Link[\"Link Component\"]\n \n TabBar --> BarItem\n BarItem --> Link\n Link --> Route[\"Route Path\"]\n```\n\n#### Link Types\n\n| Type | Description |\n|------|-------------|\n| Inner Link | Navigate to internal application routes |\n| Outer Page | Link to external URLs |\n| Selected | Display currently active/selected state |\n\n资料来源：[packages/plugins/@nocobase/plugin-mobile/src/client/mobile-layout/index.md:1]()\n\n## Workflow Engine\n\nThe Flow Engine (`flow-engine`) provides a visual workflow execution environment for business process automation.\n\n### Flow Settings\n\nFlows can be configured with custom interfaces and behaviors:\n\n| Setting | Description |\n|---------|-------------|\n| `title` | Display name for the flow |\n| `description` | Human-readable flow description |\n| `footer` | Customizable footer with buttons |\n| `onCancel` | Callback when cancel is triggered |\n| `onSaved` | Callback when configuration is saved |\n\n#### Footer Configuration Options\n\n- **Default**: Use system-provided buttons\n- **Wrap**: Add custom content around origin buttons\n- **Functional**: Completely replace with custom composition\n- **Hidden**: Set to `null` to hide footer entirely\n\n```typescript\n// Wrap existing buttons\nfooter: (originNode, { OkBtn, CancelBtn }) => (\n
\n Additional info\n {originNode}\n
\n)\n\n// Hide footer\nfooter: null\n```\n\n资料来源：[packages/core/flow-engine/src/flowSettings.ts:1]()\n\n## AI Integration\n\nThe AI plugin (`@nocobase/plugin-ai`) extends NocoBase with artificial intelligence capabilities.\n\n### Chat Messages Store\n\nAI features utilize a state management system for chat interactions:\n\n```mermaid\ngraph TD\n ChatStore[\"ChatMessages Store\"]\n Messages[\"messages[]\"]\n Attachments[\"attachments[]\"]\n Context[\"contextItems[]\"]\n System[\"systemMessage\"]\n \n ChatStore --> Messages\n ChatStore --> Attachments\n ChatStore --> Context\n ChatStore --> System\n```\n\n#### Store Actions\n\n| Action | Purpose |\n|--------|---------|\n| `setMessages` | Replace all messages |\n| `addMessage` | Append single message |\n| `addMessages` | Append multiple messages |\n| `updateLastMessage` | Modify most recent message |\n| `removeMessage` | Delete message by key |\n| `setAttachments` | Update file attachments |\n| `addContextItems` | Add context items with deduplication |\n| `setSystemMessage` | Update system prompt |\n\n#### Datasource Management\n\nAI features support multiple data sources with configuration:\n\n- **Collection**: Target collection reference\n- **Limit**: Maximum records to retrieve\n- **Description**: Data source purpose documentation\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/chatbox/stores/chat-messages.ts:1]()\n\n### Documentation Tools\n\nThe AI plugin includes tools for reading and navigating documentation:\n\n```mermaid\ngraph LR\n Input[\"Module Key Input\"]\n Parser[\"Path Parser\"]\n Resolver[\"Path Resolver\"]\n Output[\"File/Directory Content\"]\n \n Input --> Parser\n Parser --> Resolver\n Resolver --> Output\n```\n\nKey functions:\n\n- `normalizeModuleKey`: Validates and normalizes module identifiers\n- `resolveDocPath`: Maps module keys to absolute file paths\n- Documentation entries include both files and subdirectories with hierarchical structure\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/tools/docs.ts:1]()\n\n## Frontend Utilities\n\n### CSS Module Resolution\n\nUtility functions support frontend asset handling:\n\n| Function | Purpose |\n|----------|---------|\n| `isCssFile(url)` | Determines if a URL points to a CSS file |\n\nThe function handles:\n\n- Query string parameters (e.g., `style.css?v=123`)\n- Hash fragments (e.g., `style.css#section`)\n- Extension-based file type detection\n\n```typescript\nisCssFile('style.css') // true\nisCssFile('style.css?v=123') // true\nisCssFile('style.css#section') // true\nisCssFile('script.js') // false\n```\n\n资料来源：[packages/core/flow-engine/src/utils/resolveModuleUrl.ts:1]()\n\n## Technology Stack\n\n| Layer | Technology | Purpose |\n|-------|------------|---------|\n| Frontend Framework | React | UI component rendering |\n| State Management | Zustand | Lightweight state management |\n| UI Library | Ant Design | Pre-built component library |\n| Backend Runtime | Node.js | Server-side execution |\n| Database | Multiple (via ORM) | Data persistence |\n| Package Manager | Monorepo (npm workspaces) | Code organization |\n\n## Key Design Principles\n\n1. **Schema-Driven**: All configurations are declarative schema definitions\n2. **Plugin-First**: Every feature is a plugin with isolated scope\n3. **Visual Configuration**: No-code interfaces for common operations\n4. **Code Extension**: Low-code escape hatch for custom requirements\n5. **Dynamic Loading**: Runtime plugin activation without full reload\n\n## Documentation Structure\n\nThe NocoBase documentation is organized as follows:\n\n```\ndocs/\n├── README.md # Documentation index\n├── docs/\n│ └── en/ # English documentation\n│ └── index.md # Entry point\n├── packages/\n│ └── plugins/ # Plugin-specific docs\n└── README.md # Root documentation\n```\n\n资料来源：[docs/README.md:1]()\n\n## Getting Started\n\nTo begin working with NocoBase:\n\n1. **Understand the Architecture**: Familiarize yourself with the plugin-based structure\n2. **Define Data Models**: Create collections and configure fields in the admin interface\n3. **Design UI Schemas**: Use the schema designer to build application interfaces\n4. **Configure Workflows**: Set up automation using the flow engine\n5. **Extend with Plugins**: Add custom functionality through the plugin system\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Overview](#overview), [Plugin System](#plugin-system), [Deployment](#deployment)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/nocobase/nocobase/blob/main/README.md)\n- [packages/plugins/@nocobase/plugin-data-source-main/README.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-data-source-main/README.md)\n- [packages/plugins/@nocobase/plugin-form-drafts/README.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-form-drafts/README.md)\n- [packages/plugins/@nocobase/plugin-audit-logs/README.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-audit-logs/README.md)\n- [packages/plugins/@nocobase/plugin-mobile/README.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-mobile/README.md)\n
\n\n# System Architecture\n\n## Overview\n\nNocoBase is an open-source AI + no-code platform designed for building business systems rapidly. The platform adopts a **data model-driven architecture** that separates data structure from user interface, enabling unlimited possibilities for application development. 资料来源：[README.md:1]()\n\nThe architecture is built with **plugin-first extensibility** at its core, allowing developers and AI agents to extend functionality without modifying the core codebase. This design philosophy enables organizations to adapt quickly to changing business requirements while maintaining system stability and performance. 资料来源：[packages/plugins/@nocobase/plugin-data-source-main/README.md:1]()\n\n## Core Architectural Principles\n\n### Data Model-Driven Approach\n\nUnlike traditional form or table-driven platforms, NocoBase implements a data model-driven approach that decouples UI and data structure completely. This architectural decision provides several key advantages:\n\n| Characteristic | Traditional Platforms | NocoBase Architecture |\n|----------------|----------------------|----------------------|\n| UI-Data Coupling | Tightly coupled | Fully decoupled |\n| Interface Flexibility | Limited to table/form views | Unlimited block types |\n| Data Source Support | Main database only | Main DB, external DBs, third-party APIs |\n| Multiple Views | One view per entity | Multiple blocks for same table/record |\n\n资料来源：[packages/plugins/@nocobase/plugin-form-drafts/README.md:1-15]()\n\n### Plugin-Based Extensibility\n\nThe entire NocoBase system is constructed as a collection of plugins. This modular architecture allows:\n\n- **Selective Feature Loading**: Only required plugins are loaded, reducing footprint\n- **Independent Updates**: Plugins can be updated without affecting core functionality\n- **Hot Module Replacement**: Plugins can be enabled/disabled at runtime\n- **AI Integration**: AI employees can programmatically interact with any plugin\n\n```graph TD\n A[NocoBase Core] --> B[Plugin System]\n B --> C[Data Source Plugins]\n B --> D[UI Block Plugins]\n B --> E[Workflow Plugins]\n B --> F[AI Agent Plugins]\n C --> G[Main Database]\n C --> H[External Databases]\n C --> I[Third-party APIs]\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-data-source-main/README.md:1-10]()\n\n## System Components\n\n### Plugin Categories\n\nNocoBase organizes its functionality into distinct plugin categories based on responsibility:\n\n| Category | Purpose | Example Plugins |\n|----------|---------|-----------------|\n| Data Management | Handle data operations and storage | `plugin-data-source-main` |\n| User Interface | Provide UI components and blocks | `plugin-mobile`, `plugin-block-workbench` |\n| Workflow Automation | Manage business processes | `plugin-workflow-manual`, `plugin-workflow-notification` |\n| System Utilities | Core system features | `plugin-audit-logs`, `plugin-verification` |\n| AI Integration | Enable AI capabilities | `plugin-ai` |\n\n### Database Layer\n\nThe database layer in NocoBase supports multiple data source types through a unified abstraction:\n\n- **Main Database**: Primary storage engine (configurable type)\n- **External Databases**: Direct connections to external SQL databases\n- **Third-party APIs**: REST/GraphQL API integrations as data sources\n\n资料来源：[packages/plugins/@nocobase/plugin-data-source-main/README.md:1-12]()\n\n```graph TD\n A[Application Layer] --> B[Data Source Abstraction]\n B --> C[Main Database Engine]\n B --> D[External DB Connectors]\n B --> E[API Connectors]\n C --> F[SQL Translation Layer]\n D --> F\n E --> F\n F --> G[Query Optimization]\n```\n\n### User Interface Architecture\n\nNocoBase provides a flexible UI system that supports both desktop and mobile clients:\n\n#### Desktop Client\n\nThe desktop client (`packages/core/client`) implements a schema-driven UI system where:\n\n- Components are defined as schemas\n- UI blocks are composed declaratively\n- Schema settings control component behavior\n\n资料来源：[packages/plugins/@nocobase/plugin-mobile/README.md:1-8]()\n\n#### Mobile Client\n\nThe mobile plugin provides:\n\n- Mobile-optimized page layouts\n- Responsive design support\n- Native-like navigation patterns\n- Mobile-specific UI components\n\n```graph TD\n A[Client Request] --> B{Router}\n B -->|Desktop| C[Desktop UI Renderer]\n B -->|Mobile| D[Mobile UI Renderer]\n C --> E[Schema Component Tree]\n D --> F[Mobile Page Layouts]\n E --> G[Block Designer]\n F --> G\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-mobile/README.md:1-15]()\n\n## Workflow System Architecture\n\n### Plugin-Based Workflows\n\nNocoBase implements workflows as plugins, enabling:\n\n- **Manual Triggers**: User-initiated workflow execution\n- **Automated Triggers**: Event-based workflow activation\n- **Notification System**: Multi-channel alert delivery\n- **Dynamic Calculation**: Runtime computation within workflows\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow-manual/README.md:1-10]()\n\n### Workflow Components\n\n| Component | Function | Plugin |\n|-----------|----------|--------|\n| Trigger | Initiates workflow execution | `plugin-workflow-manual` |\n| Actions | Perform operations | Core system |\n| Conditions | Control flow logic | Core system |\n| Notifications | Send alerts | `plugin-workflow-notification` |\n| Calculations | Compute values | `plugin-workflow-dynamic-calculation` |\n\n```graph TD\n A[Workflow Start] --> B{Trigger Type}\n B -->|Manual| C[User Action]\n B -->|Automated| D[Event Listener]\n C --> E[Condition Evaluation]\n D --> E\n E -->|True| F[Execute Actions]\n E -->|False| G[Skip Workflow]\n F --> H{Notification?}\n H -->|Yes| I[Send Notification]\n H -->|No| J[Continue Actions]\n I --> K[Workflow Complete]\n J --> K\n G --> K\n```\n\n## Audit and Logging Architecture\n\nThe audit logs plugin (`plugin-audit-logs`) captures comprehensive system activity:\n\n- **Data Changes**: All database modifications\n- **User Actions**: User interactions with the system\n- **System Events**: Server-side operations\n- **Access Patterns**: Authentication and authorization events\n\n资料来源：[packages/plugins/@nocobase/plugin-audit-logs/README.md:1-12]()\n\n## AI Integration Architecture\n\nNocoBase integrates AI capabilities through a dedicated AI plugin system:\n\n### AI Employee System\n\nUnlike standalone AI implementations, NocoBase allows embedding AI capabilities seamlessly into:\n\n- **Interfaces**: AI-powered form components and data displays\n- **Workflows**: AI-driven decision making and automation\n- **Business Logic**: Custom AI agents for domain-specific tasks\n- **Data Operations**: Intelligent data processing and analysis\n\n```graph TD\n A[AI Plugin System] --> B[AI Employees]\n A --> C[Prompt Templates]\n A --> D[Model Adapters]\n B --> E[Business Interfaces]\n B --> F[Workflow Integration]\n B --> G[Data Processing]\n C --> H[System Context]\n D --> I[LLM Providers]\n E --> J[User Interface]\n F --> K[Automation Engine]\n G --> L[Data Layer]\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-data-source-main/README.md:1-8]()\n\n## Extensibility Patterns\n\n### Plugin Development\n\nDevelopers can extend NocoBase by creating custom plugins:\n\n1. **Plugin Structure**: Each plugin is a self-contained module\n2. **Dependency Management**: Plugins can depend on other plugins\n3. **Lifecycle Hooks**: Initialization, activation, and deactivation\n4. **Schema Extension**: Custom schema types and components\n\n```graph TD\n A[Custom Plugin] --> B[Plugin Manifest]\n A --> C[Server Code]\n A --> D[Client Code]\n A --> E[Resources]\n B --> F[Plugin Metadata]\n B --> G[Dependencies]\n C --> H[Database Models]\n C --> I[API Routes]\n C --> J[Services]\n D --> K[UI Components]\n D --> L[Schema Definitions]\n D --> M[State Management]\n```\n\n### Schema-Driven UI\n\nThe schema system allows declarative UI definition:\n\n| Schema Type | Purpose | Extensibility |\n|-------------|---------|---------------|\n| `Field` | Data display/input | Custom field types |\n| `Block` | Layout containers | Custom block types |\n| `Action` | User interactions | Custom action handlers |\n| `Selector` | Data filtering | Custom filter types |\n\n## System Requirements and Deployment\n\n### Database Support\n\nNocoBase supports multiple database engines:\n\n| Database | Status | Notes |\n|----------|--------|-------|\n| PostgreSQL | Full Support | Recommended for production |\n| MySQL | Full Support | Wide compatibility |\n| SQLite | Development Only | Limited concurrent access |\n| Others | Via External DB Plugin | API-based connectivity |\n\n### Runtime Requirements\n\n- **Node.js**: v18+ required\n- **Package Manager**: npm or yarn\n- **Memory**: Minimum 2GB RAM for development\n- **Storage**: Varies by database and data volume\n\n## Architectural Benefits\n\n### Scalability\n\n- **Horizontal Scaling**: Stateless server design enables load balancing\n- **Vertical Scaling**: Efficient resource utilization supports larger deployments\n- **Plugin Isolation**: Prevents resource contention between features\n\n### Maintainability\n\n- **Modular Design**: Each plugin can be developed and tested independently\n- **Clear Boundaries**: Well-defined interfaces between components\n- **Version Management**: Plugins maintain their own version history\n\n### Flexibility\n\n- **Multiple Data Sources**: Connect to various databases and APIs\n- **Custom UI**: Schema-driven interface allows infinite combinations\n- **AI Integration**: Built-in support for AI-augmented functionality\n\n## Summary\n\nNocoBase's system architecture is designed around three fundamental principles:\n\n1. **Data Model Centrality**: The data model drives all application behavior, not forms or tables\n2. **Plugin-Based Extensibility**: Every feature is a plugin that can be added, removed, or customized\n3. **AI Integration**: AI capabilities are first-class citizens integrated throughout the system\n\nThis architecture enables organizations to build sophisticated business applications rapidly while maintaining the flexibility to adapt to changing requirements. The separation of concerns between data, logic, and presentation layers ensures that changes in one area do not cascade into others, resulting in a maintainable and scalable system.\n\n---\n\n\n\n## Deployment\n\n### 相关页面\n\n相关主题：[Cluster Mode](#cluster-mode), [System Architecture](#system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [docker-compose.yml](https://github.com/nocobase/nocobase/blob/main/docker-compose.yml)\n- [Dockerfile](https://github.com/nocobase/nocobase/blob/main/Dockerfile)\n- [docker/nocobase/Dockerfile](https://github.com/nocobase/nocobase/blob/main/docker/nocobase/Dockerfile)\n- [docker/app-postgres/docker-compose.yml](https://github.com/nocobase/nocobase/blob/main/docker/app-postgres/docker-compose.yml)\n- [docker/app-mysql/docker-compose.yml](https://github.com/nocobase/nocobase/blob/main/docker/app-mysql/docker-compose.yml)\n- [docker/app-mariadb/docker-compose.yml](https://github.com/nocobase/nocobase/blob/main/docker/app-mariadb/docker-compose.yml)\n- [docker/app-sqlite/docker-compose.yml](https://github.com/nocobase/nocobase/blob/main/docker/app-sqlite/docker-compose.yml)\n- [docs/docs/en/get-started/deployment/production.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/get-started/deployment/production.md)\n- [docs/docs/en/get-started/installation/docker.mdx](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/get-started/installation/docker.mdx)\n
\n\n# Deployment\n\nNocoBase provides flexible deployment options to accommodate various infrastructure requirements and operational preferences. The platform supports containerized deployment via Docker, traditional server deployment, and development-focused installations.\n\n## Overview\n\nNocoBase is designed as a headless CMS with an API-first architecture. The application server exposes REST and GraphQL APIs, while the admin client is a separate SPA (Single Page Application). This separation allows for flexible deployment strategies where the server and client can be scaled independently.\n\n## Deployment Methods\n\n### Docker Deployment (Recommended)\n\nDocker deployment is the recommended approach for production environments. It provides the easiest setup with no-code requirements and simplified maintenance through image updates.\n\n**Minimal Quick Start:**\n```bash\nnpm install -g @nocobase/cli@beta\nmkdir my-nocobase && cd my-nocobase\nnb init --ui\n```\n\n资料来源：[README.md:8-13]()\n\n### Database Support\n\nNocoBase supports multiple database backends. Each database type has a dedicated Docker Compose configuration:\n\n| Database | Configuration File | Use Case |\n|------------|-------------------------------------------|----------------------------------|\n| PostgreSQL | `docker/app-postgres/docker-compose.yml` | Production, enterprise scale |\n| MySQL | `docker/app-mysql/docker-compose.yml` | Production, wide compatibility |\n| MariaDB | `docker/app-mariadb/docker-compose.yml` | Production, MySQL fork |\n| SQLite | `docker/app-sqlite/docker-compose.yml` | Development, small deployments |\n\n资料来源：[docker/app-postgres/docker-compose.yml](https://github.com/nocobase/nocobase/blob/main/docker/app-postgres/docker-compose.yml), [docker/app-mysql/docker-compose.yml](https://github.com/nocobase/nocobase/blob/main/docker/app-mysql/docker-compose.yml)\n\n### Docker Architecture\n\n```mermaid\ngraph TD\n A[Client Browser] -->|HTTPS| B[NocoBase Application]\n B -->|API Requests| C[API Server :13000]\n B -->|Static Assets| D[Admin SPA :13000]\n C --> E[(PostgreSQL
MySQL
MariaDB)]\n C --> F[(SQLite)]\n E --> G[Uploaded Files
/uploads]\n F --> G\n```\n\n## Docker Configuration\n\n### Main Dockerfile\n\nThe primary Dockerfile (`docker/nocobase/Dockerfile`) builds the NocoBase application image. It uses a multi-stage build process to:\n\n1. Install dependencies\n2. Build the application\n3. Create an optimized production image\n\n### Environment Variables\n\nKey environment variables for Docker deployment:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `APP_KEY` | Application encryption key | Generated on first run |\n| `DB_DIALECT` | Database type (postgres, mysql, sqlite) | postgres |\n| `DB_HOST` | Database host | db |\n| `DB_PORT` | Database port | 5432 / 3306 |\n| `DB_DATABASE` | Database name | nocobase |\n| `DB_USER` | Database username | nocobase |\n| `DB_PASSWORD` | Database password | nocobase |\n| `API_PORT` | API server port | 13000 |\n\n### Docker Compose Services\n\nTypical Docker Compose configuration includes:\n\n```yaml\nservices:\n app:\n image: nocobase/app:latest\n ports:\n - \"13000:13000\"\n environment:\n - DB_DIALECT=postgres\n - DB_HOST=db\n - DB_PORT=5432\n volumes:\n - ./uploads:/app/uploads\n depends_on:\n - db\n\n db:\n image: postgres:15\n environment:\n - POSTGRES_DB=nocobase\n - POSTGRES_USER=nocobase\n - POSTGRES_PASSWORD=nocobase\n volumes:\n - db_data:/var/lib/postgresql/data\n\nvolumes:\n db_data:\n```\n\n## Production Deployment\n\n### Prerequisites\n\nFor production deployments, ensure:\n\n1. **Reverse Proxy**: Configure nginx or similar for SSL termination\n2. **Database**: Use PostgreSQL or MySQL for production workloads\n3. **Storage**: Configure persistent storage for uploaded files\n4. **Environment**: Set secure `APP_KEY` in production\n\n### Deployment Checklist\n\n| Item | Priority | Description |\n|------|----------|-------------|\n| SSL Certificate | Required | Enable HTTPS for production |\n| Database Backup | Required | Configure automated backups |\n| APP_KEY Configuration | Required | Use unique, secure key |\n| Environment Variables | Required | Set production values |\n| Upload Storage | Required | Configure persistent storage |\n| Monitoring | Recommended | Set up application monitoring |\n| Log Management | Recommended | Configure centralized logging |\n\n资料来源：[docs/docs/en/get-started/deployment/production.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/get-started/deployment/production.md)\n\n### Production Reverse Proxy Configuration\n\n```nginx\nserver {\n listen 80;\n server_name your-domain.com;\n return 301 https://$server_name$request_uri;\n}\n\nserver {\n listen 443 ssl http2;\n server_name your-domain.com;\n\n ssl_certificate /path/to/cert.pem;\n ssl_certificate_key /path/to/key.pem;\n\n client_max_body_size 100M;\n\n location / {\n proxy_pass http://localhost:13000;\n proxy_http_version 1.1;\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection 'upgrade';\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_cache_bypass $http_upgrade;\n }\n\n location /uploads/ {\n alias /path/to/uploads/;\n expires 7d;\n add_header Cache-Control \"public, immutable\";\n }\n}\n```\n\n## Installation Methods Comparison\n\n| Method | Best For | Code Writing | Upgrade Process | Development |\n|--------|----------|--------------|-----------------|-------------|\n| Docker | Production, no-code | No | Pull image, restart | Limited |\n| create-nocobase-app | Business projects | Yes (low-code) | Rebuild project | Full |\n| Git Clone | Contributing, latest | Yes | Git pull | Full |\n\n资料来源：[README.md:18-33]()\n\n## Upgrading\n\n### Docker Upgrades\n\nFor Docker deployments, upgrading involves:\n\n```bash\n# Pull latest image\ndocker pull nocobase/app:latest\n\n# Restart container\ndocker-compose down\ndocker-compose up -d\n```\n\n### Database Migration\n\nNocoBase automatically runs database migrations on startup. Ensure:\n\n1. Database backup before upgrade\n2. Sufficient downtime window for migration\n3. Rollback plan if migration fails\n\n## File Structure Reference\n\n```\n├── docker-compose.yml # Main compose file\n├── Dockerfile # Legacy Dockerfile\n├── docker/\n│ ├── nocobase/\n│ │ └── Dockerfile # Modern app Dockerfile\n│ ├── app-postgres/\n│ │ └── docker-compose.yml\n│ ├── app-mysql/\n│ │ └── docker-compose.yml\n│ ├── app-mariadb/\n│ │ └── docker-compose.yml\n│ └── app-sqlite/\n│ └── docker-compose.yml\n└── uploads/ # User uploads directory\n```\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| Container won't start | Check environment variables and volume permissions |\n| Database connection failed | Verify DB_HOST, DB_PORT, and credentials |\n| File upload fails | Check uploads directory permissions and size limits |\n| Slow performance | Increase memory limits, enable caching |\n\n### Health Check\n\nNocoBase provides health check endpoint at the root path:\n\n```bash\ncurl http://localhost:13000/\n```\n\nA successful response indicates the application is running correctly.\n\n## Next Steps\n\n- [Installation Guide](https://docs.nocobase.com/welcome/getting-started/installation/docker-compose)\n- [Production Best Practices](https://docs.nocobase.com/welcome/getting-started/deployment/production)\n- [Plugin Development](https://docs.nocobase.com/development/server/plugins)\n\n---\n\n\n\n## Plugin System\n\n### 相关页面\n\n相关主题：[Plugin Development](#plugin-development), [Data Modeling](#data-modeling), [Workflow Engine](#workflow-engine)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/client/src/pm/PluginDetail.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginDetail.tsx)\n- [packages/core/client/src/pm/PluginManagerLink.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginManagerLink.tsx)\n- [packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx)\n- [packages/core/flow-engine/src/flowSettings.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/flowSettings.ts)\n- [packages/plugins/@nocobase/plugin-mobile/src/client/pages/index.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-mobile/src/client/pages/index.md)\n
\n\n# Plugin System\n\n## Overview\n\nNocoBase implements a modular plugin-based architecture that enables developers to extend core functionality without modifying the framework's source code. Plugins in NocoBase are self-contained packages that can add new features, customize existing behavior, and integrate with external services.\n\nThe plugin system provides a unified mechanism for both server-side and client-side extensions, allowing developers to hook into application lifecycle events, register custom components, define database schemas, and expose APIs.\n\n## Architecture\n\n```graph TD\n subgraph Core[\"NocoBase Core\"]\n PM[Plugin Manager]\n ER[Event Router]\n SM[Schema Manager]\n end\n \n subgraph PluginTypes[\"Plugin Types\"]\n SP[Server Plugin]\n CP[Client Plugin]\n FP[Full-Stack Plugin]\n end\n \n subgraph Lifecycle[\"Lifecycle Phases\"]\n LOAD[Load]\n BOOT[Boot]\n MOUNT[Mount]\n ACTIVE[Active]\n end\n \n PM -->|manages| SP\n PM -->|manages| CP\n PM -->|manages| FP\n SP --> LOAD\n CP --> LOAD\n FP --> LOAD\n LOAD --> BOOT\n BOOT --> MOUNT\n MOUNT --> ACTIVE\n```\n\n## Plugin Manager\n\nThe Plugin Manager (`PluginManagerLink.tsx`) handles the registration and lifecycle of all plugins within the application.\n\n### Core Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| `PluginDetail` | `packages/core/client/src/pm/PluginDetail.tsx` | Displays plugin metadata and dependency information |\n| `PluginManagerLink` | `packages/core/client/src/pm/PluginManagerLink.tsx` | Provides UI navigation to plugin settings |\n| `SchemaToolbar` | `packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx` | Enables schema-based plugin configuration |\n\n### Plugin Detail Display\n\nThe `PluginDetail` component renders comprehensive information about installed plugins:\n\n```tsx\n{plugin.packageName}\n • }>\n {plugin.version}\n\n\n```\n\n资料来源：[packages/core/client/src/pm/PluginDetail.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginDetail.tsx)\n\n### Dependencies Compatibility Check\n\nPlugins validate their dependencies through the compatibility checking system:\n\n```tsx\n{data?.data?.depsCompatible === false ? (\n \n {t('`dist/externalVersion.js` not found or failed to `require`. Please rebuild this plugin.')}\n \n) : (\n <>\n {!data?.data?.['isCompatible'] && (\n \n )}\n \n \n)}\n```\n\n资料来源：[packages/core/client/src/pm/PluginDetail.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginDetail.tsx)\n\n## Plugin Settings Management\n\n### Settings Menu Integration\n\nThe `PluginManagerLink` component integrates with the application settings menu:\n\n```tsx\nconst settingItems = useMemo(() => {\n const pinnedSettings = app.pluginSettingsManager\n .getPinnedSettings()\n .filter((setting) => setting.snippet !== false)\n .map((setting) => {\n return {\n key: setting.name,\n icon: setting.icon,\n label: setting.link ? (\n
window.open(setting.link)}>{compile(setting.title)}
\n ) : (\n {compile(setting.title)}\n ),\n };\n });\n // ...\n}, [app, t]);\n```\n\n资料来源：[packages/core/client/src/pm/PluginManagerLink.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginManagerLink.tsx)\n\n### Mobile Layout Handling\n\nSettings are hidden in mobile layouts:\n\n```tsx\nconst { isMobileLayout } = useMobileLayout();\n\nif (isMobileLayout) {\n return null;\n}\n```\n\n资料来源：[packages/core/client/src/pm/PluginManagerLink.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginManagerLink.tsx)\n\n## Schema-Based Plugin Extensions\n\n### Schema Designer Integration\n\nPlugins can extend the schema designer through the `GeneralSchemaDesigner` component:\n\n```tsx\n
\n \n {draggable && (\n \n \n \n )}\n {!disableInitializer &&\n (ctx?.InitializerComponent ? (\n \n ) : (\n ctx?.renderSchemaInitializer?.(initializerProps)\n ))}\n {schemaSettingsExists ? (\n schemaSettingsRender(contextValue)\n ) : (\n \n }\n {...schemaSettingsProps}\n >\n {props.children}\n \n )}\n \n
\n```\n\n资料来源：[packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx)\n\n### Toolbar Components\n\nThe schema toolbar provides a unified interface for plugin-defined tools:\n\n```tsx\n
\n \n {dragElement}\n {initializerElement}\n {settingsElement}\n \n
\n```\n\n资料来源：[packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx)\n\n## Plugin Lifecycle\n\n```graph LR\n A[Install] --> B[Load]\n B --> C[Configure]\n C --> D[Enable]\n D --> E[Boot]\n E --> F[Mount]\n F --> G[Disable]\n G --> H[Uninstall]\n```\n\n### Flow Settings Integration\n\nThe flow engine demonstrates plugin extensibility through settings:\n\n```tsx\nexport class FlowSettings {\n public components: Record = {};\n public scopes: Record = {};\n private antdComponentsLoaded = false;\n public enabled: boolean;\n #forceEnabled = false; // Force enable state\n}\n```\n\n资料来源：[packages/core/flow-engine/src/flowSettings.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/flowSettings.ts)\n\n### Modal Footer Customization\n\nPlugins can customize modal dialogs through the footer API:\n\n```tsx\nfooter?:\n | React.ReactNode\n | ((originNode: React.ReactNode, extra: { OkBtn: React.FC; CancelBtn: React.FC }) => React.ReactNode)\n | null;\n```\n\n资料来源：[packages/core/flow-engine/src/flowSettings.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/flowSettings.ts)\n\n## Client-Side Plugin Components\n\n### Page Components\n\nMobile plugins extend the application through page components:\n\n| Page Type | Description |\n|-----------|-------------|\n| Home Page | Default landing page with routing support |\n| NotFound Page | 404 error handling |\n| Desktop Mode | Desktop layout wrapper for mobile content |\n\n```tsx\n\n \n\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-mobile/src/client/desktop-mode/index.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-mobile/src/client/desktop-mode/index.md)\n\n### Schema Initializer Extensions\n\nPlugins extend schema initialization through:\n\n```tsx\n### Insert schema\n#### Basic\n\n#### Action\n\n#### FormItem\n\n```\n\n资料来源：[packages/core/client/src/schema-initializer/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-initializer/index.md)\n\n## Error Handling\n\n### Error Fallback Component\n\nPlugins integrate with the error handling system through the `ErrorFallback` component:\n\n```tsx\n\n \n {t('Feedback')}\n ,\n ,\n ]}\n />\n\n```\n\n资料来源：[packages/core/client/src/schema-component/antd/error-fallback/ErrorFallback.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/antd/error-fallback/ErrorFallback.tsx)\n\n## Plugin Package Structure\n\n| Directory/File | Purpose |\n|---------------|---------|\n| `src/server/` | Server-side plugin logic |\n| `src/client/` | Client-side React components |\n| `src/locale/` | Internationalization files |\n| `dist/` | Compiled distribution files |\n| `dist/externalVersion.js` | Version compatibility manifest |\n\n## Built-in Variables System\n\nPlugins can access built-in variables for dynamic content:\n\n| Variable | Context | Description |\n|----------|---------|-------------|\n| `$date` | datetimeCtx | Current date (deprecated) |\n| `$nExactDate` | exactDateTimeCtx | Precise timestamp |\n| `$nDate` | datetimeCtx | Current date |\n| `$system` | now | System time (deprecated) |\n| `currentTime` | () => dayjs | Legacy time variable |\n\n资料来源：[packages/core/client/src/variables/hooks/useBuiltinVariables.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/variables/hooks/useBuiltinVariables.ts)\n\n---\n\n\n\n## Data Modeling\n\n### 相关页面\n\n相关主题：[Plugin System](#plugin-system), [Interface Builder](#interface-builder), [Authentication and Permissions](#authentication-permissions)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/database/src/database.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/database/src/database.ts)\n- [packages/core/client/src/schema-templates/SchemaTemplateManagerProvider.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-templates/SchemaTemplateManagerProvider.tsx)\n- [packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx)\n- [packages/core/client/src/schema-component/antd/table/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/antd/table/index.md)\n- [packages/core/client/src/schema-settings/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-settings/index.md)\n
\n\n# Data Modeling\n\n## Overview\n\nData Modeling in NocoBase represents the foundational system for defining, organizing, and managing data structures within the application. It provides a comprehensive framework that enables users to create collections, define fields, establish relationships, and configure data sources through both programmatic APIs and user interfaces.\n\nThe data modeling system serves as the core abstraction layer that bridges the gap between application-level schema definitions and the underlying database infrastructure. It supports multiple database dialects and provides consistent data management capabilities across different storage backends.\n\n## Architecture\n\n### Core Database System\n\nThe `Database` class in NocoBase acts as the central orchestrator for all data modeling operations. It maintains several internal maps and registries that track collections, fields, models, and their relationships.\n\n```mermaid\ngraph TD\n A[Database] --> B[Collections Map]\n A --> C[Repositories Map]\n A --> D[Operators Map]\n A --> E[Model-Collection Maps]\n A --> F[Query Interface]\n A --> G[Dialect Layer]\n B --> H[Collection Metadata]\n E --> I[Model-Collection Binding]\n E --> J[Model Name Mapping]\n E --> K[Table Name Mapping]\n```\n\nThe database system initializes with the following key components:\n\n| Component | Type | Purpose |\n|-----------|------|---------|\n| `collections` | `Map` | Stores all registered collections by name |\n| `collectionsSort` | `Map` | Manages collection ordering/priority |\n| `repositories` | `Map` | Caches repository instances |\n| `modelCollection` | `Map` | Binds model classes to collections |\n| `modelNameCollectionMap` | `Map` | Lookup by model name |\n| `tableNameCollectionMap` | `Map` | Lookup by table name |\n| `pendingFields` | `Map` | Handles deferred field relations |\n| `interfaceManager` | `InterfaceManager` | Manages field type interfaces |\n\n资料来源：[packages/core/database/src/database.ts:26-45]()\n\n### Dialect Support\n\nThe database layer implements a dialect pattern through `BaseDialect` to support multiple database engines. The dialect system is registered statically and enables the framework to generate appropriate SQL syntax for different database backends.\n\n```mermaid\ngraph LR\n A[Database] --> B[Dialect Abstraction]\n B --> C[PostgreSQL]\n B --> D[MySQL]\n B --> E[SQLite]\n B --> F[Other Engines]\n \n G[SQL Identifier Quoting] --> C\n G --> D\n G --> E\n G --> F\n```\n\n资料来源：[packages/core/database/src/database.ts:47-59]()\n\n## Collections\n\nCollections are the primary units of data organization in NocoBase. They represent database tables and serve as containers for fields and their associated metadata.\n\n### Collection Management\n\nThe system provides multiple mechanisms for retrieving collections:\n\n| Method | Description |\n|--------|-------------|\n| `getCollection(name)` | Retrieve collection by exact name |\n| `getRepository(name)` | Get repository instance for collection |\n| `getModel(name)` | Access the ORM model |\n| `tableNameCollectionMap` | Lookup by database table name |\n\nThe collection system supports template-based creation through the `SchemaTemplateManagerProvider`, which enables reusable collection schemas:\n\n```typescript\ngetTemplatesByCollection: useCallback(\n (dataSource: string, collectionName: string) => {\n const parentCollections = getInheritCollections(collectionName, dataSource);\n const totalCollections = parentCollections.concat([collectionName]);\n const items = templates?.filter?.(\n (template) =>\n (template.dataSourceKey || DEFAULT_DATA_SOURCE_KEY) === dataSource &&\n totalCollections.includes(template.collectionName),\n );\n return items || [];\n },\n [getInheritCollections, templates],\n),\n```\n\n资料来源：[packages/core/client/src/schema-templates/SchemaTemplateManagerProvider.tsx:45-60]()\n\n### Collection Inheritance\n\nCollections support inheritance through the `InheritanceMap`, allowing child collections to derive schema from parent collections. This enables hierarchical data modeling where common fields are defined once and inherited by specialized collections.\n\n## Fields\n\nFields define the structure and behavior of data within collections. Each field has a type, validation rules, and UI configurations.\n\n### Field Types\n\nThe system includes built-in field types and supports custom interface extensions:\n\n| Category | Description |\n|----------|-------------|\n| Built-in Types | Standard field types provided by NocoBase |\n| Custom Interfaces | Extensible field type system |\n| Relation Fields | References to other collections |\n| Virtual Fields | Computed or derived fields |\n\nFields can be configured with dynamic visibility and child elements:\n\n```tsx\n// Dynamic visible & children\n// Supports conditional display and dynamic loading of child fields\n```\n\n资料来源：[packages/core/client/src/schema-settings/index.md:15-17]()\n\n### Field Configuration\n\nFields support various configuration options including:\n\n- Display names and descriptions\n- Default values\n- Validation rules\n- UI components and templates\n- Access control permissions\n\n## Schema System\n\nThe schema system provides a declarative way to define UI and data structures. It integrates with collections to render appropriate interface components.\n\n### Schema Designer\n\nThe `GeneralSchemaDesigner` component provides the visual interface for editing schema configurations:\n\n```mermaid\ngraph TD\n A[GeneralSchemaDesigner] --> B[Title Bar]\n A --> C[Drag Handler]\n A --> D[Initializer Component]\n A --> E[Schema Settings Dropdown]\n \n B --> F[Data Source Display]\n B --> G[Template Reference]\n \n D --> H[Dynamic Initializer]\n \n E --> I[Custom Settings Menu]\n```\n\n资料来源：[packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx:1-50]()\n\n### Schema Templates\n\nSchema templates enable reusable component configurations:\n\n| Method | Purpose |\n|--------|---------|\n| `getTemplateBySchemaId` | Find template by schema UID |\n| `getTemplateById` | Find template by key |\n| `getTemplatesByComponentName` | Filter by component type |\n| `getTemplatesByCollection` | Filter by collection with inheritance |\n\n资料来源：[packages/core/client/src/schema-templates/SchemaTemplateManagerProvider.tsx:32-44]()\n\n## Data Sources\n\nThe system supports multiple data sources, allowing connections to different databases within a single application.\n\n### Data Source Manager\n\nData sources are managed through a dedicated configuration system that handles:\n\n- Connection configuration\n- Dialect-specific settings\n- SQL identifier quoting rules\n- Cross-database relationships\n\nThe quoting rules vary by database type and must be respected when generating SQL:\n\n> Quote SQL identifiers according to each data source's database type specified in ``.\n> - Convert camelCase names to snake_case for databases that use underscore naming\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/ai-employees/prompts.ts:15-20]()\n\n## Table Components\n\nThe system provides multiple table rendering modes for different use cases:\n\n| Mode | Use Case |\n|------|----------|\n| `Table.Void` | Read-only display without interaction |\n| `Table.RowSelection` | Selectable rows for batch operations |\n| `Table.Array` | Editable array-based table |\n\n资料来源：[packages/core/client/src/schema-component/antd/table/index.md:1-14]()\n\n### Table Examples\n\nThe table component supports various configurations:\n\n- Basic void table display\n- Row selection with checkboxes\n- Array-based inline editing\n- Integrated action buttons\n\n## Workflow Integration\n\nData modeling integrates with the workflow engine through the `FlowSettings` system, which provides:\n\n- Custom variable definitions\n- Linkage rules configuration\n- Condition evaluation based on field values\n- Action triggers tied to data changes\n\nThe linkage rules system allows conditional logic based on collection fields:\n\n```typescript\n// Condition evaluation structure\n{\n condition: FilterGroup,\n actions: Action[]\n}\n```\n\n资料来源：[packages/core/client/src/flow/actions/linkageRules.tsx:60-80]()\n\n## API Reference\n\n### Database Initialization\n\n```typescript\nconst database = new Database({\n dialect: 'postgres',\n // ... connection options\n});\n```\n\n### Collection Definition\n\n```typescript\ndatabase.collection({\n name: 'users',\n fields: [\n { type: 'string', name: 'name' },\n { type: 'hasMany', name: 'posts' },\n ],\n});\n```\n\n### Query Operations\n\n| Method | Description |\n|--------|-------------|\n| `db.getCollection(name)` | Get collection instance |\n| `collection.repository` | Access CRUD operations |\n| `collection.model` | Access ORM model |\n\n## Summary\n\nThe Data Modeling system in NocoBase provides a comprehensive solution for defining and managing application data structures. It combines:\n\n1. **Collection Management**: Organize data into logical groupings\n2. **Field Definition**: Configure data attributes with types and validation\n3. **Schema Templates**: Enable reusable configurations\n4. **Multi-Datasource Support**: Connect to various database backends\n5. **UI Integration**: Seamless rendering through schema components\n6. **Workflow Connection**: Trigger actions based on data conditions\n\nThe architecture emphasizes extensibility through plugins, custom field interfaces, and dialect-specific optimizations.\n\n---\n\n\n\n## Interface Builder\n\n### 相关页面\n\n相关主题：[Data Modeling](#data-modeling), [Workflow Engine](#workflow-engine), [Plugin Development](#plugin-development)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/client/src/schema-settings/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-settings/index.md)\n- [packages/core/client/src/schema-initializer/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-initializer/index.md)\n- [packages/core/client/src/schema-component/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/index.md)\n- [packages/core/flow-engine/src/flowSettings.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/flowSettings.ts)\n- [packages/core/client/src/schema-component/antd/markdown/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/antd/markdown/index.md)\n- [packages/core/client/src/schema-component/antd/association-select/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/antd/association-select/index.md)\n- [packages/core/client/src/schema-component/antd/linkageFilter/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/antd/linkageFilter/index.md)\n
\n\n# Interface Builder\n\n## Overview\n\nThe Interface Builder is NocoBase's core visual configuration system that enables users to create and customize application interfaces through a schema-driven approach. It provides a declarative way to define UI components, their behaviors, and data relationships without requiring code modifications.\n\n### Core Concepts\n\nThe Interface Builder operates on a schema-based architecture where every UI element is defined through JSON schemas that describe:\n\n- Component type and properties\n- Data binding and field mappings\n- Action handlers and event callbacks\n- Styling and layout configurations\n- Conditional visibility rules\n\n### Architecture Overview\n\n```mermaid\ngraph TD\n A[Interface Builder] --> B[Schema Settings]\n A --> C[Schema Initializers]\n A --> D[Schema Components]\n A --> E[Variables System]\n \n B --> B1[Built-in Types]\n B --> B2[Designer Context]\n \n C --> C1[Block Initializers]\n C --> C2[Field Initializers]\n C --> C3[Action Initializers]\n \n D --> D1[Form Components]\n D --> D2[Display Components]\n D --> D3[Action Components]\n \n E --> E1[System Variables]\n E --> E2[Custom Variables]\n E --> E3[Flow Variables]\n```\n\n## Schema System\n\nThe schema system is the foundation of the Interface Builder. Schemas define the structure, behavior, and appearance of interface elements.\n\n### Schema Properties\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `x-component` | string | The component to render |\n| `x-component-props` | object | Component-specific props |\n| `x-decorator` | string | Wrapper component (e.g., FormItem) |\n| `x-decorator-props` | object | Decorator component props |\n| `x-designable` | boolean | Enable visual editing |\n| `x-hidden` | boolean | Hide the element |\n| `x-visible` | expression | Conditional visibility |\n\n### Basic Schema Example\n\n```tsx\n{\n type: 'string',\n 'x-component': 'Markdown',\n 'x-decorator': 'FormItem',\n 'x-component-props': {\n mode: 'sv',\n height: '82vh'\n }\n}\n```\n\n资料来源：[packages/core/client/src/flow/flows/editMarkdownFlow.tsx](./packages/core/client/src/flow/flows/editMarkdownFlow.tsx)\n\n## Schema Settings\n\nSchema Settings provide configuration panels for customizing schema properties in design mode. They appear when users click the settings icon on schema elements.\n\n### Built-in Schema Settings\n\nThe system includes several built-in schema settings components:\n\n| Component | Purpose |\n|-----------|---------|\n| `GeneralSchemaDesigner` | General schema configuration |\n| `SchemaSettings` | Base settings collection |\n| `SchemaSettingsDropdown` | Dropdown menu for settings |\n| `SchemaToolbar` | Toolbar for schema operations |\n\n### Designer Toolbar\n\nThe schema designer toolbar provides quick access to common operations:\n\n```tsx\n\n```\n\n资料来源：[packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx](./packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx)\n\n### Toolbar Components\n\n| Component | Function |\n|-----------|----------|\n| `DragHandler` | Drag handle for reordering |\n| `InitializerComponent` | Insert new elements |\n| `SchemaSettingsDropdown` | Open settings panel |\n\n### Toolbar Title Display\n\nThe toolbar displays hierarchical information when configured:\n\n```tsx\n\n {dataSource ? `${compile(dataSource?.displayName)} > ${titleArr[0]}` : titleArr[0]}\n\n```\n\n## Schema Initializers\n\nSchema Initializers define where and what elements can be inserted into the interface. They provide the \"Add\" functionality within design mode.\n\n### Initializer Types\n\n#### Block Initializers\n\nBlock initializers add container-level components like tables, forms, and grids.\n\n```tsx\n{\n type: 'array',\n title: '{{t(\"Blocks\")}}',\n name: 'blockInitializers',\n children: [\n // Table block\n {\n title: '{{t(\"Table\")}}',\n name: 'tableSelector',\n Component: TableSelectorInitializer\n },\n // Form block\n {\n title: '{{t(\"Form\")}}',\n name: 'formItemInitializers',\n Component: FormItemInitializers\n }\n ]\n}\n```\n\n#### Field Initializers\n\nField initializers add data fields to forms and tables.\n\n```tsx\n{\n type: 'array',\n title: '{{t(\"Fields\")}}',\n name: 'fieldInitializers',\n children: [\n {\n title: '{{t(\"Text\")}}',\n name: 'text',\n Component: DateFormatInitializer\n }\n ]\n}\n```\n\n### Dynamic Visibility\n\nInitializers can dynamically show or hide items based on context:\n\n```tsx\n{\n 'x-visible': '{{curdModel === \"list\"}}',\n children: [\n // Dynamic children\n ]\n}\n```\n\n## Schema Components\n\nNocoBase provides a rich library of schema components for building interfaces.\n\n### Form Components\n\n#### Markdown\n\nA rich text editor supporting Markdown syntax.\n\n```tsx\ninterface MarkdownProps extends TextAreaProps {\n value?: string;\n onChange?: (value: string) => void;\n mode?: 'sv' | 'wysiwyg';\n}\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `mode` | `'sv' \\| 'wysiwyg'` | `'sv'` | Editor mode |\n| `height` | `string \\| number` | `200` | Editor height |\n| `value` | `string` | - | Markdown content |\n| `onChange` | `function` | - | Change handler |\n\n资料来源：[packages/core/client/src/schema-component/antd/markdown/index.md](./packages/core/client/src/schema-component/antd/markdown/index.md)\n\n#### Markdown.Void\n\nA void component for inline markdown editing.\n\n```tsx\ninterface MarkdownVoidProps extends Omit {\n defaultValue?: string;\n onSubmit?: (value: string) => void;\n onCancel?: (e: React.MouseEvent) => void;\n}\n```\n\n### Association Components\n\n#### AssociationSelect\n\nSelect component for related data from specified tables.\n\n```tsx\ntype AssociationSelectProps

= RemoteSelectProps

& {\n action?: string;\n multiple?: boolean;\n};\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `action` | `string` | `'list'` | Data fetching action |\n| `multiple` | `boolean` | `false` | Enable multi-select |\n| `type` | `'string' \\| 'array'` | `'string'` | Value type |\n| `fieldNames` | `object` | - | Field name mappings |\n\n资料来源：[packages/core/client/src/schema-component/antd/association-select/index.md](./packages/core/client/src/schema-component/antd/association-select/index.md)\n\n### Filter Components\n\n#### LinkageFilter\n\nComponent for frontend linkage rules and condition configuration.\n\n```tsx\ntype FilterActionProps = ActionProps & {\n options?: any[];\n form?: Form;\n onSubmit?: (values: T) => void;\n onReset?: (values: T) => void;\n}\n```\n\n### Built-in Component Types\n\n| Category | Components |\n|----------|------------|\n| Input | Input, TextArea, NumberPicker, Password |\n| Select | Select, Checkbox, Radio, Switch |\n| Display | Markdown, Markdown.Void, LinkageFilter |\n| Association | AssociationSelect, RecordPicker |\n| DateTime | DatePicker, TimePicker, DateRangePicker |\n\n## Variables System\n\nThe Variables system provides dynamic data access within the Interface Builder, enabling context-aware functionality.\n\n### Variable Types\n\n| Type | Label | Description |\n|------|-------|-------------|\n| `system` | System | Built-in system variables |\n| `currentUser` | Current User | Logged-in user information |\n| `currentRole` | Current Role | Current user's role |\n| `dateNow` | Date Now | Current timestamp |\n| `form` | Form | Form values and state |\n| `record` | Record | Current data record |\n| `variable` | Custom Variable | User-defined variables |\n\n### Variable Table Structure\n\nVariables are displayed in a structured table:\n\n| Column | Description |\n|--------|-------------|\n| `title` | Variable display name |\n| `key` | Variable identifier |\n| `type` | Variable data type |\n| `actions` | Edit and delete operations |\n\n### Custom Variables\n\nCustom variables can be created and managed in workflows:\n\n```tsx\n{\n title: t('Custom Variables'),\n key: 'customVariables',\n type: 'object',\n children: [\n {\n title: variable.title,\n key: variable.key,\n type: variable.type\n }\n ]\n}\n```\n\n资料来源：[packages/core/client/src/flow/actions/customVariable.tsx](./packages/core/client/src/flow/actions/customVariable.tsx)\n\n## Actions\n\nActions define user interactions and their corresponding behaviors within the Interface Builder.\n\n### Action Types\n\n| Action | Description |\n|--------|-------------|\n| `submit` | Submit form data |\n| `cancel` | Cancel current operation |\n| `create` | Create new record |\n| `update` | Update existing record |\n| `delete` | Delete record |\n| `custom` | Custom action handler |\n\n### Action Schema Configuration\n\n```tsx\n{\n type: 'object',\n 'x-component': 'Action',\n 'x-component-props': {\n type: 'primary',\n icon: 'CheckOutlined'\n }\n}\n```\n\n## UI Mode Configuration\n\nThe UI Mode system allows customization of dialog and modal appearances.\n\n### Footer Configuration\n\n```tsx\nfooter: (originNode, { OkBtn, CancelBtn }) => (\n

\n Additional info\n {originNode}\n
\n)\n```\n\n### Footer Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `null` | `null` | Hide footer |\n| `ReactNode` | `ReactNode` | Static footer content |\n| `function` | `(originNode, { OkBtn, CancelBtn }) => ReactNode` | Dynamic footer |\n\n资料来源：[packages/core/flow-engine/src/flowSettings.ts](./packages/core/flow-engine/src/flowSettings.ts)\n\n## Designer Context\n\nThe Designer Context provides runtime information and utilities for schema design mode.\n\n### Context Features\n\n- `designable` - Current design mode state\n- `designerProps` - Designer-specific properties\n- `resources` - Available schema resources\n- `schema` - Current schema instance\n- `refresh` - Refresh handler for data updates\n\n### Context Usage\n\n```tsx\nconst { designable, schema, refresh } = useDesigner();\n\nif (designable) {\n return ;\n}\n```\n\n## Integration with Flow Engine\n\nThe Interface Builder integrates with NocoBase's Flow Engine to provide workflow-driven interface behavior.\n\n### Flow Settings Integration\n\nFlow settings can be embedded within schema components:\n\n```tsx\n{\n type: 'object',\n 'x-component': 'FlowSettings',\n properties: {\n content: {\n type: 'string',\n 'x-component': 'Markdown',\n 'x-component-props': {\n mode: 'sv'\n }\n }\n }\n}\n```\n\n### Default Parameters\n\nSchemas can define default parameters for flows:\n\n```tsx\ndefaultParams: (ctx) => {\n return {\n content: ctx.t('{{t(\"Default content\")}}'),\n };\n}\n```\n\n### Liquid Template Rendering\n\nVariables support Liquid template syntax:\n\n```tsx\nconst result = await ctx.liquid.renderWithFullContext(content, ctx);\n```\n\n## Mobile Interface Builder\n\nNocoBase supports mobile-specific interface building through the mobile plugin.\n\n### Mobile Pages\n\n| Page | Description |\n|------|-------------|\n| Home Page | Application homepage |\n| NotFound Page | 404 error page |\n\n### Mobile Layout Components\n\n| Component | Description |\n|-----------|-------------|\n| `MobileTabBar` | Bottom navigation bar |\n| `MobileTabBar.Item` | Tab bar items |\n| `MobileTabBar.Link` | Link navigation items |\n\n### Desktop Mode\n\nMobile pages can be wrapped for desktop viewing:\n\n```tsx\n\n \n\n```\n\n## Plugin Manager Integration\n\nThe Plugin Manager provides configuration UI for plugins built with the Interface Builder system.\n\n### Plugin Details Display\n\n```tsx\n{\n key: 'info',\n label: t('Plugin Info'),\n children: (\n <>\n {plugin.packageName}\n \n \n )\n}\n```\n\n### Dependency Compatibility\n\nPlugin details include dependency compatibility checking:\n\n```tsx\n{\n key: 'dependencies',\n label: t('Dependencies compatibility check'),\n children: (\n \n )\n}\n```\n\n## Best Practices\n\n### Schema Organization\n\n1. Use meaningful `name` properties for schema identification\n2. Group related components under consistent parent schemas\n3. Leverage decorators (`x-decorator`) for common patterns\n\n### Performance Optimization\n\n1. Use `x-hidden` over conditional rendering for hidden elements\n2. Leverage `designable` flag to skip rendering logic in production\n3. Use void components for modal content\n\n### Accessibility\n\n1. Include `aria-label` on interactive elements\n2. Use proper heading hierarchy within schema blocks\n3. Ensure keyboard navigation support\n\n## See Also\n\n- [Schema Settings Reference](./schema-settings/index.md)\n- [Schema Components Reference](./schema-component/index.md)\n- [Variables System](./variables.md)\n- [Mobile Interface](./mobile/index.md)\n\n---\n\n\n\n## Workflow Engine\n\n### 相关页面\n\n相关主题：[Interface Builder](#interface-builder), [Plugin System](#plugin-system), [Authentication and Permissions](#authentication-permissions)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx)\n- [packages/plugins/@nocobase/plugin-workflow/src/locale/ko-KR.json](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-workflow/src/locale/ko-KR.json)\n- [packages/core/flow-engine/src/flowSettings.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/flowSettings.ts)\n- [packages/core/flow-engine/src/components/FlowModelRenderer.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/components/FlowModelRenderer.tsx)\n- [packages/core/client/src/flow/actions/customVariable.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/flow/actions/customVariable.tsx)\n- [packages/plugins/@nocobase/plugin-workflow/src/client/CanvasContent.tsx](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-workflow/src/client/CanvasContent.tsx)\n
\n\n# Workflow Engine\n\n## Overview\n\nThe Workflow Engine is NocoBase's core system for designing, executing, and managing automated business processes. It provides a visual canvas-based interface where users can create workflows by connecting different node types, define triggers that initiate workflow execution, and configure custom variables for data transformation.\n\nThe engine is designed as a plugin (`@nocobase/plugin-workflow`) that integrates with the broader NocoBase platform, leveraging the `flow-engine` core module for rendering and execution logic.\n\n## Architecture\n\nThe Workflow Engine follows a provider-based architecture with clear separation between UI rendering and execution logic.\n\n```graph TD\n A[Workflow Canvas] --> B[FlowContext Provider]\n B --> C[ExecutionCanvas Component]\n C --> D[CanvasContent Component]\n C --> E[JobModal Component]\n D --> F[FlowModelRenderer]\n F --> G[FlowModelProvider]\n G --> H[ErrorBoundary]\n F --> I[MemoFlowModelRenderer]\n```\n\n## Core Components\n\n### FlowContext Provider\n\nThe `FlowContext` provides runtime data to all workflow-related components. It encapsulates the current workflow, nodes, execution context, and view state.\n\n```typescript\n\n```\n\n**Context Values:**\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `workflow` | `Workflow` | The workflow configuration object |\n| `nodes` | `Node[]` | Array of nodes in the workflow |\n| `execution` | `Execution` | Current execution instance |\n| `viewJob` | `Job \\| null` | Job selected for detailed view |\n| `setViewJob` | `Function` | Callback to update viewJob state |\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx:21-28]()\n\n### ExecutionCanvas\n\nThe `ExecutionCanvas` is the main container component for viewing workflow executions. It renders the toolbar, status indicators, and delegates content rendering to child components.\n\n**Key Features:**\n\n- Breadcrumb navigation to workflow details\n- Execution status badge with color coding\n- Cancel execution capability (when execution is not in terminal state)\n- Last updated timestamp display\n\n```typescript\n{lang('Workflow')} },\n {\n title: (\n \n {workflow.title}\n \n ),\n },\n { title: },\n ]}\n/>\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx:31-44]()\n\n### FlowModelRenderer\n\nThe `FlowModelRenderer` is the core rendering component that displays the workflow model with all connected nodes. It supports several configuration options:\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `model` | `Model` | Required | The data model to render |\n| `showFlowSettings` | `boolean` | `true` | Whether to show flow settings panel |\n| `flowSettingsVariant` | `string` | `undefined` | Visual variant for settings |\n| `hideRemoveInSettings` | `boolean` | `false` | Hide remove button in settings |\n| `showTitle` | `boolean` | `true` | Show the model title |\n| `inputArgs` | `any[]` | `[]` | Input arguments for the flow |\n| `showErrorFallback` | `boolean` | `true` | Show error fallback UI |\n| `settingsMenuLevel` | `string` | `undefined` | Settings menu hierarchy level |\n| `extraToolbarItems` | `ReactNode` | `undefined` | Additional toolbar content |\n| `fallback` | `React.FC` | `undefined` | Custom fallback component |\n| `useCache` | `boolean` | `false` | Enable render caching |\n\n资料来源：[packages/core/flow-engine/src/components/FlowModelRenderer.tsx:1-50]()\n\n**Memoization:**\n\n```typescript\nexport const MemoFlowModelRenderer = React.memo(FlowModelRenderer);\nMemoFlowModelRenderer.displayName = 'MemoFlowModelRenderer';\n```\n\nThe component includes a memoized version (`MemoFlowModelRenderer`) that skips re-rendering when parent components re-render but props remain unchanged. This optimization does not affect internal reactive updates.\n\n资料来源：[packages/core/flow-engine/src/components/FlowModelRenderer.tsx:110-112]()\n\n### CanvasContent\n\nThe `CanvasContent` component renders the actual workflow visualization including nodes, edges, and clipboard preview functionality.\n\n**Features:**\n\n- Terminal node display (Start/End markers)\n- Clipboard preview for copied nodes\n- Zoom slider control\n\n```typescript\n
\n \n
\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/client/CanvasContent.tsx:1-100]()\n\n## Flow Settings\n\nThe `FlowSettings` class manages flow configuration dialogs and their component registry.\n\n```typescript\nexport class FlowSettings {\n public components: Record = {};\n public scopes: Record = {};\n private antdComponentsLoaded = false;\n public enabled: boolean;\n #forceEnabled = false;\n}\n```\n\n资料来源：[packages/core/flow-engine/src/flowSettings.ts:1-10]()\n\n### Footer Configuration\n\nFlow settings support customizable footer content through a flexible API:\n\n```typescript\nfooter?:\n | React.ReactNode\n | ((originNode: React.ReactNode, extra: { OkBtn: React.FC; CancelBtn: React.FC }) => React.ReactNode)\n | null;\n```\n\n**Footer Patterns:**\n\n| Pattern | Example |\n|---------|---------|\n| **Default** | Preserves original footer with Ok/Cancel buttons |\n| **Overlay** | Add content above origin footer |\n| **Replace** | Full custom footer composition |\n| **Hidden** | Set `footer: null` to hide |\n\n资料来源：[packages/core/flow-engine/src/flowSettings.ts:1-30]()\n\n## Variables System\n\nThe workflow engine supports variable injection for data transformation between nodes.\n\n### Custom Variables Configuration\n\nThe `customVariable.tsx` file provides the UI for managing custom workflow variables:\n\n**Variable Properties:**\n\n| Property | Data Index | Description |\n|----------|------------|-------------|\n| Title | `title` | Display name for the variable |\n| Identifier | `key` | Unique key for referencing |\n| Type | `type` | Data type classification |\n\n**Available Variable Types:**\n\n| Type | Label | Usage |\n|------|-------|-------|\n| `string` | String | Text data |\n| `number` | Number | Numeric values |\n| `boolean` | Boolean | True/false flags |\n| `array` | Array | List of values |\n| `object` | Object | Complex structured data |\n\n**Actions:**\n\n| Action | Icon | Description |\n|--------|------|-------------|\n| Edit | `EditOutlined` | Modify variable configuration |\n| Delete | `DeleteOutlined` | Remove variable from workflow |\n\n```typescript\nrender: (_: unknown, __: FlowVariable, index: number) => (\n \n }\n onClick={() => handleEdit(index)}\n disabled={disabled}\n title={t('Edit')}\n />\n }\n danger\n onClick={() => handleDelete(index)}\n disabled={disabled}\n title={t('Delete')}\n />\n \n)\n```\n\n资料来源：[packages/core/client/src/flow/actions/customVariable.tsx:1-80]()\n\n## Execution States\n\nThe engine tracks execution status through a state machine:\n\n```graph TD\n A[Created] --> B[Running]\n B --> C[Success]\n B --> D[Failed]\n B --> E[Cancelled]\n D --> F[Retry]\n F --> B\n```\n\n**Status Options:**\n\n| Status | Color | Description |\n|--------|-------|-------------|\n| Running | Processing | Execution in progress |\n| Success | Success | Completed successfully |\n| Failed | Error | Execution encountered an error |\n| Cancelled | Warning | Execution manually stopped |\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/locale/ko-KR.json:1-50]()\n\n## Trigger Points\n\nWorkflows can be triggered at various points in the application lifecycle:\n\n| Trigger | Description |\n|---------|-------------|\n| After Saving | Triggered after data save completes |\n| After Submitting | Triggered after form submission succeeds |\n| Before Deleting | Triggered before deletion (local mode only) |\n| Button Click | Triggered directly on button click without saving |\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/locale/ko-KR.json:50-100]()\n\n## Error Handling\n\nThe system implements multi-level error handling:\n\n1. **ErrorBoundary Wrapper:** Catches rendering errors around the FlowModelRenderer\n2. **FlowModelProvider:** Provides error context to child components\n3. **FlowErrorFallback:** Renders user-friendly error messages with recovery options\n\n```typescript\nif (showErrorFallback) {\n return (\n \n {content}\n \n );\n}\n```\n\n资料来源：[packages/core/flow-engine/src/components/FlowModelRenderer.tsx:85-92]()\n\n## Integration with Plugin System\n\nThe workflow plugin integrates with NocoBase's plugin manager through:\n\n- **Route Registration:** `/workflow` path for navigation\n- **Settings Manager:** `app.pluginSettingsManager.getRoutePath('workflow')`\n- **Localization:** Multi-language support via JSON locale files\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx:35]()\n\n## Summary\n\nThe Workflow Engine provides a comprehensive system for building and executing automated workflows within NocoBase. Key aspects include:\n\n- **Visual Canvas:** Drag-and-drop workflow design interface\n- **Context-Based Architecture:** React Context for global state management\n- **Flexible Configuration:** Customizable settings dialogs and footers\n- **Variable System:** Support for custom variables with type classification\n- **Error Resilience:** Built-in error boundaries and fallback components\n- **Execution Tracking:** Real-time status updates and execution history\n- **Plugin Integration:** Seamless integration with the NocoBase plugin ecosystem\n\n---\n\n\n\n## Authentication and Permissions\n\n### 相关页面\n\n相关主题：[Workflow Engine](#workflow-engine), [Data Modeling](#data-modeling), [Plugin Development](#plugin-development)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [docs/docs/en/auth-verification/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/auth-verification/index.md)\n- [docs/docs/en/users-permissions/acl/permissions.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/users-permissions/acl/permissions.md)\n- [docs/docs/en/users-permissions/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/users-permissions/index.md)\n- [docs/docs/en/plugins/@nocobase/plugin-acl/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/plugins/@nocobase/plugin-acl/index.md)\n- [docs/docs/en/plugins/@nocobase/plugin-auth/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/plugins/@nocobase/plugin-auth/index.md)\n- [docs/docs/en/users-permissions/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/users-permissions/index.md)\n
\n\n# Authentication and Permissions\n\n## Overview\n\nNocoBase implements a comprehensive authentication and permissions system built on a plugin-based architecture. The system is designed to provide secure access control through multiple integrated plugins that handle user authentication, role-based access control (RBAC), and granular resource permissions.\n\n## Authentication System\n\n### Authentication Plugin\n\nThe `@nocobase/plugin-auth` plugin provides the core authentication capabilities for NocoBase. This plugin handles user identity verification, session management, and integrates with various authentication providers.\n\n### Authentication Verification Flow\n\nThe auth-verification system implements a multi-step verification process to ensure secure access to NocoBase resources.\n\n```mermaid\ngraph TD\n A[Client Request] --> B{Authentication Required?}\n B -->|Yes| C[Auth Plugin Verification]\n B -->|No| G[Resource Access]\n C --> D{Credentials Valid?}\n D -->|Yes| E[Generate Session Token]\n D -->|No| F[Authentication Failed - 401]\n E --> G[Resource Access with Token]\n```\n\n### User Management\n\nThe `@nocobase/plugin-users` plugin extends the authentication system by providing comprehensive user management capabilities. User records store essential identity information and serve as the basis for permission assignments.\n\n## Access Control List (ACL) System\n\n### ACL Plugin Architecture\n\nThe `@nocobase/plugin-acl` plugin implements NocoBase's Access Control List system, providing fine-grained permission management across collections, actions, and fields.\n\n```mermaid\ngraph TD\n A[User Request] --> B{ACL Check}\n B --> C{Role Assigned?}\n C -->|No| D[Default Deny]\n C -->|Yes| E[Check Resource Permissions]\n E --> F{Action Allowed?}\n F -->|Yes| G[Execute Action]\n F -->|No| H[Permission Denied - 403]\n```\n\n### Permission Model\n\nNocoBase's permissions system follows a hierarchical structure:\n\n| Permission Level | Scope | Description |\n|-----------------|-------|-------------|\n| Collection | `collections:*` | Global collection access |\n| Specific Collection | `collections:posts` | Single collection access |\n| Action | `collections:posts:*` | All actions on collection |\n| Field | `fields:posts:title` | Specific field access |\n| Resource | `resources:posts` | Resource-level permissions |\n\n资料来源：[docs/docs/en/users-permissions/acl/permissions.md]()\n\n### Built-in Roles\n\n| Role | Description | Default Permissions |\n|------|-------------|---------------------|\n| `admin` | Full system access | All permissions |\n| `member` | Basic user access | Limited to assigned resources |\n| `guest` | Unauthenticated users | Minimal or no access |\n\n资料来源：[docs/docs/en/plugins/@nocobase/plugin-acl/index.md]()\n\n## Permissions Management\n\n### Role-Based Access Control\n\nThe permissions system in NocoBase is built on the principle of assigning permissions to roles, then assigning roles to users. This follows the standard RBAC (Role-Based Access Control) model.\n\n```mermaid\ngraph LR\n A[Users] -->|assigned to| B[Roles]\n B -->|grants| C[Permissions]\n C -->|apply to| D[Resources/Actions]\n \n E[Collections] -->|scope| C\n F[Fields] -->|scope| C\n G[Actions] -->|scope| C\n```\n\n资料来源：[docs/docs/en/users-permissions/index.md]()\n\n### Permission Configuration\n\nPermissions can be configured at multiple levels:\n\n| Level | Syntax | Example |\n|-------|--------|---------|\n| All resources | `*` | `collections:*` |\n| Specific resource | `resourceName` | `collections:posts` |\n| Nested resource | `parent.child` | `collections:posts.comments` |\n| Field-level | `resource:field` | `collections:posts:title` |\n\n### UI Permission Handling\n\nIn the client-side implementation, permission checks are integrated throughout the UI components. Fields that users lack permission to modify are automatically restricted:\n\n```typescript\n// From: packages/core/client/src/flow/models/fields/AssociationFieldModel/SubTableFieldModel/SubTableColumnModel.tsx\nconst messageValue = useMemo(() => {\n return t(\n `The current user only has the UI configuration permission, but don't have \"{{actionName}}\" permission for field \"{{name}}\"`,\n {\n name: nameValue,\n actionName: t(capitalize(actionName)),\n },\n ).replaceAll('>', '>');\n}, [nameValue, t]);\n```\n\nThis code demonstrates how NocoBase handles field-level permissions, displaying lock icons and tooltip messages when users lack action permissions on specific fields.\n\n## Security Implementation\n\n### Safe Globals in Execution Contexts\n\nFor sensitive operations like custom JavaScript execution (e.g., RunJS nodes in workflows), NocoBase implements safe globals to prevent unauthorized access:\n\n```typescript\n// From: packages/core/flow-engine/src/utils/safeGlobals.ts\nconst allowed: Record = {\n clipboard,\n};\n\nObject.defineProperty(allowed, 'onLine', {\n get: () => !!nav?.onLine,\n enumerable: true,\n configurable: false,\n});\n\nreturn new Proxy(\n {},\n {\n get(_t, prop: string) {\n if (prop in allowed) return (allowed as any)[prop];\n throw new Error(`Access to navigator property \"${String(prop)}\" is not allowed.`);\n },\n },\n);\n```\n\nThis security measure ensures that sensitive browser APIs are either read-only or completely blocked in untrusted execution contexts.\n\n### URL Security Validation\n\nWhen workflows or scripts need to open URLs, NocoBase enforces strict URL validation:\n\n```typescript\n// From: packages/core/flow-engine/src/utils/safeGlobals.ts\nconst isSafeUrl = (u: string): boolean => {\n try {\n const parsed = new URL(u, getSafeBaseHref());\n const protocol = parsed.protocol.toLowerCase();\n if (protocol === 'about:') return parsed.href === 'about:blank';\n return protocol === 'http:' || protocol === 'https:';\n } catch {\n return false;\n }\n};\n```\n\nOnly `http://`, `https://`, and `about:blank` URLs are permitted, preventing potential security vulnerabilities from malicious URL schemes.\n\n## Plugin Dependencies\n\nThe authentication and permissions system depends on a plugin hierarchy:\n\n```mermaid\ngraph BT\n A[plugin-auth] --> B[plugin-users]\n C[plugin-acl] --> B\n B --> D[plugin-core]\n```\n\n| Plugin | Purpose |\n|--------|---------|\n| `plugin-auth` | Authentication mechanisms |\n| `plugin-users` | User management |\n| `plugin-acl` | Access Control List implementation |\n\n## Related Documentation\n\n| Document | Path |\n|----------|------|\n| Auth Verification | `docs/docs/en/auth-verification/index.md` |\n| ACL Permissions | `docs/docs/en/users-permissions/acl/permissions.md` |\n| User Permissions Guide | `docs/docs/en/users-permissions/index.md` |\n| ACL Plugin | `docs/docs/en/plugins/@nocobase/plugin-acl/index.md` |\n| Auth Plugin | `docs/docs/en/plugins/@nocobase/plugin-auth/index.md` |\n| Users Plugin | `docs/docs/en/plugins/@nocobase/plugin-users/index.md` |\n\n---\n\n\n\n## AI Integration\n\n### 相关页面\n\n相关主题：[Overview](#overview), [Workflow Engine](#workflow-engine), [Plugin Development](#plugin-development)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/chatbox/Messages.tsx](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/chatbox/Messages.tsx)\n- [packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/admin/Employees.tsx](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/admin/Employees.tsx)\n- [packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/admin/Templates.tsx](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/admin/Templates.tsx)\n- [packages/plugins/@nocobase/plugin-ai/src/server/tools/docs.ts](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai/src/server/tools/docs.ts)\n- [packages/core/flow-engine/src/runjs-context/contexts/base.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/runjs-context/contexts/base.ts)\n- [packages/core/client/src/flow/actions/customVariable.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/flow/actions/customVariable.tsx)\n
\n\n# AI Integration\n\nNocoBase provides a comprehensive AI Integration system through the `@nocobase/plugin-ai` package. This system enables users to create, manage, and deploy AI employees that can collaborate with human users to build and manage business applications. The AI integration leverages modern LLM (Large Language Model) technology to provide intelligent assistance throughout the platform.\n\n## Overview\n\nThe AI Integration feature in NocoBase is designed to:\n\n- Enable AI agents to work alongside human users in a collaborative environment\n- Provide customizable AI employees with different roles and capabilities\n- Support knowledge base integration for context-aware responses\n- Offer tool-calling capabilities for AI to interact with the NocoBase system\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/chatbox/Messages.tsx:1-40]()\n\n## Architecture\n\nThe AI Integration system follows a plugin-based architecture that integrates seamlessly with the NocoBase core system.\n\n### System Components\n\n| Component | Purpose | Location |\n|-----------|---------|----------|\n| AI Employees | Virtual team members that can perform tasks | `packages/plugins/@nocobase/plugin-ai` |\n| Chat Interface | Real-time messaging between users and AI | `src/client/ai-employees/chatbox/` |\n| Admin Panel | Management interface for AI configurations | `src/client/ai-employees/admin/` |\n| Templates | Pre-configured AI employee templates | `src/client/ai-employees/admin/Templates.tsx` |\n| Tool System | Server-side tools for AI operations | `src/server/tools/` |\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/admin/Employees.tsx:1-80]()\n\n## AI Employees\n\nAI Employees are virtual team members that can be assigned tasks, communicate with users, and perform various operations within the NocoBase ecosystem.\n\n### Employee Management\n\nThe `Employees` component provides a comprehensive interface for managing AI employees:\n\n```tsx\n\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/admin/Employees.tsx:35-75]()\n\n### Employee Data Model\n\n| Field | Type | Description |\n|-------|------|-------------|\n| username | string | Unique identifier for the AI employee |\n| category | string | Classification category (e.g., 'business') |\n| enabled | boolean | Whether the employee is active |\n| sort | number | Display order |\n| templates | array | Pre-configured task templates |\n\n### Category Filtering\n\nAI employees can be filtered by category using the `CategoryFilter` component, allowing administrators to organize employees based on their functional areas or roles.\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/admin/Employees.tsx:50-55]()\n\n## Chat Interface\n\nThe chatbox component provides a real-time messaging interface for user interaction with AI employees.\n\n### Message Display\n\nMessages are rendered using the `Messages` component which handles different message states:\n\n```tsx\n
\n {messages.length > 0 ? (\n
\n {messages.map((msg) => {\n return (\n \n );\n })}\n
\n ) : (\n \n {t('Work with your AI crew')}\n
\n )}\n\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/chatbox/Messages.tsx:10-40]()\n\n### Message States\n\n| State | Description | Visual Indicator |\n|-------|-------------|------------------|\n| normal | Standard message display | Default styling |\n| loading | Message being processed | Loading spinner |\n| error | Failed message | Error styling |\n| streaming | Real-time response | Progressive rendering |\n\n## Templates System\n\nTemplates provide pre-configured AI employee configurations that can be quickly deployed to create new AI team members.\n\n### Template Loading\n\nTemplates are loaded dynamically from the server:\n\n```tsx\nconst { data: templates, loading } = useRequest<{ data: AIEmployee[] }>(() =>\n api\n .resource('aiEmployees')\n .getTemplates()\n .then((res) => res?.data?.data),\n);\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/admin/Templates.tsx:1-30]()\n\n### Template Creation Flow\n\nWhen creating a new employee from a template, the system uses a drawer component with form validation:\n\n```tsx\n\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/client/ai-employees/admin/Templates.tsx:35-85]()\n\n## Server-Side Tools\n\nThe AI integration includes server-side tools that allow AI employees to interact with various NocoBase system components.\n\n### Documentation Reader Tool\n\nThe `readDocEntry` tool enables AI employees to access and read documentation entries:\n\n```tsx\nreadDocEntry: {\n description: 'Read a documentation entry',\n parameters: {\n type: 'object',\n properties: {\n module: {\n type: 'string',\n description: 'The module key (e.g., \"runjs\")',\n },\n },\n required: ['module'],\n },\n async handler(ctx) {\n try {\n const { pluginKey, relativePath, canonicalPath } = parseDocPath(input);\n const meta = docsModules.get(pluginKey);\n if (!meta) {\n throw new Error(`Document module \"${pluginKey}\" not found.`);\n }\n // Read and return documentation content\n } catch (error) {\n ctx.log?.error?.(error, {\n module: 'ai',\n subModule: 'toolCalling',\n toolName: 'readDocEntry',\n });\n return {\n status: 'error',\n content: `Failed to read docs entry: ${error.message}`,\n };\n }\n },\n},\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/tools/docs.ts:1-80]()\n\n### Tool Execution Flow\n\n```mermaid\ngraph TD\n A[User Request] --> B[AI Employee Processing]\n B --> C{Requires Tool?}\n C -->|Yes| D[Tool Selection]\n C -->|No| E[Direct Response]\n D --> F[Execute Server Tool]\n F --> G[Tool Handler]\n G --> H[Error Handling]\n H --> I[Return Result]\n E --> I\n I --> J[Response to User]\n```\n\n### Available Server Tools\n\n| Tool Name | Purpose | Module |\n|-----------|---------|--------|\n| readDocEntry | Read documentation entries | ai |\n| customVariable | Manage flow variables | flow |\n| runjs | Execute JavaScript code | flow-engine |\n\n## AI Context in Workflows\n\nThe AI system integrates with NocoBase's workflow engine through a comprehensive context system that provides AI employees access to system resources.\n\n### Resource Context\n\nAI employees can interact with resources through the context API:\n\n```typescript\ninterface ResourceContext {\n setData: {\n description: '设置资源当前数据（仅前端）';\n detail: '(value: any) => this';\n completion: { insertText: 'ctx.resource.setData(value)' };\n };\n refresh: {\n description: '从后端刷新数据';\n detail: '() => Promise';\n completion: { insertText: 'await ctx.resource.refresh()' };\n };\n on: {\n description: '订阅资源事件';\n detail: '(event: string, callback: (...args) => void) => void';\n completion: { insertText: \"ctx.resource.on('refresh', () => {})\" };\n };\n setResourceName: {\n description: '设置资源名称';\n detail: '(resourceName: string) => this';\n completion: { insertText: \"ctx.resource.setResourceName('users')\" };\n };\n setFilterByTk: {\n description: '设置主键/过滤键';\n detail: '(filterByTk: any) => this';\n completion: { insertText: 'ctx.resource.setFilterByTk(filterByTk)' };\n };\n runAction: {\n description: '执行资源动作';\n };\n}\n```\n\n资料来源：[packages/core/flow-engine/src/runjs-context/contexts/base.ts:1-50]()\n\n## Flow Variables\n\nAI integration supports custom variables that can be used in workflows and shared between human and AI collaborators.\n\n### Variable Management Interface\n\nThe variable management UI provides full CRUD operations:\n\n```tsx\ncolumns={[\n {\n title: t('Name'),\n dataIndex: 'name',\n key: 'name',\n ellipsis: true,\n render: (text: string) => {text},\n },\n {\n title: t('Identifier'),\n dataIndex: 'key',\n key: 'key',\n ellipsis: true,\n },\n {\n title: t('Type'),\n dataIndex: 'type',\n key: 'type',\n render: (type: FlowVariableType) => (\n {t(VARIABLE_TYPE_LABELS[type] || type)}\n ),\n },\n {\n title: t('Actions'),\n key: 'actions',\n render: (_: unknown, __: FlowVariable, index: number) => (\n \n }\n onClick={() => handleEdit(index)}\n />\n }\n danger\n onClick={() => handleDelete(index)}\n />\n \n ),\n },\n]}\n```\n\n资料来源：[packages/core/client/src/flow/actions/customVariable.tsx:1-70]()\n\n### Variable Types\n\n| Type | Label | Description |\n|------|-------|-------------|\n| string | String | Text value |\n| number | Number | Numeric value |\n| boolean | Boolean | True/false value |\n| date | Date | Date and time value |\n| object | Object | Complex data structure |\n| array | Array | Collection of values |\n\n## Error Handling\n\nThe AI integration system includes comprehensive error handling for both client and server components.\n\n### Client-Side Error Fallback\n\n```tsx\n\n {t('Feedback')}\n ,\n ,\n ]}\n>\n \n \n {error.stack}\n \n \n\n```\n\n资料来源：[packages/core/client/src/schema-component/antd/error-fallback/ErrorFallback.tsx:1-30]()\n\n### Server-Side Error Logging\n\nErrors are logged with module context for debugging:\n\n```tsx\nctx.log?.error?.(error, {\n module: 'ai',\n subModule: 'toolCalling',\n toolName: 'readDocEntry',\n});\n```\n\n## Installation and Setup\n\nTo enable AI integration in NocoBase:\n\n1. Install the `@nocobase/plugin-ai` package\n2. Configure the plugin in the NocoBase administration panel\n3. Set up AI provider credentials (API keys for LLM services)\n4. Create AI employees and assign roles\n5. Configure knowledge bases and tools as needed\n\n## Summary\n\nThe AI Integration system in NocoBase provides a powerful framework for creating intelligent AI employees that can collaborate with human users. Key features include:\n\n- **Employee Management**: Create, edit, and organize AI team members with different roles\n- **Real-time Chat**: Direct communication channel between users and AI employees\n- **Template System**: Quick deployment of pre-configured AI employees\n- **Tool Integration**: AI can access NocoBase system capabilities through server-side tools\n- **Workflow Integration**: AI context available in NocoBase workflow engine\n- **Error Handling**: Comprehensive error reporting and recovery mechanisms\n\nThis system enables organizations to build AI-powered business applications that leverage the intelligence of large language models while maintaining the flexibility and extensibility of the NocoBase no-code platform.\n\n---\n\n\n\n## File Storage\n\n### 相关页面\n\n相关主题：[Data Modeling](#data-modeling), [Interface Builder](#interface-builder)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/client/src/schema-component/antd/upload/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/antd/upload/index.md)\n- [packages/core/client/src/schema-component/antd/upload/Upload.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/antd/upload/Upload.tsx)\n- [packages/core/client/src/schema-component/antd/input/ScanInput/QRCodeScanner.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/antd/input/ScanInput/QRCodeScanner.tsx)\n- [packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx)\n- [packages/core/flow-engine/src/utils/resolveModuleUrl.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/utils/resolveModuleUrl.ts)\n
\n\n# File Storage\n\n## Overview\n\nFile Storage in NocoBase is a comprehensive system for managing file uploads, storage, and preview capabilities across the platform. The system is built on top of Ant Design's Upload component and extends it with additional features such as thumbnail preview, file type validation, size restrictions, and integration with the broader schema system.\n\nThe file storage subsystem consists of several key components:\n\n- **Upload Component**: The primary interface for file uploads\n- **Storage Adapters**: Backend mechanisms for persisting files\n- **File Preview**: Preview capabilities for various file types\n- **Schema Integration**: Deep integration with NocoBase's schema system\n\n资料来源：[packages/core/client/src/schema-component/antd/upload/index.md:1-24]()\n\n## Upload Component\n\n### Type Definitions\n\nThe Upload component is defined with the following type signature:\n\n```typescript\ntype UploadProps = Omit & {\n onChange?: (fileList: UploadFile[]) => void;\n serviceErrorMessage?: string;\n value?: any;\n size?: string;\n};\n```\n\n资料来源：[packages/core/client/src/schema-component/antd/upload/index.md:8-13]()\n\nThe component accepts all Ant Design Upload props while extending them with NocoBase-specific functionality. The `value` prop allows for controlled usage within schema forms, and `size` can be used to restrict upload behavior.\n\n### Read Pretty Mode\n\nFor display-only scenarios, a specialized read-pretty variant is available:\n\n```typescript\ntype UploadReadPrettyProps = AntdUploadProps;\n```\n\n资料来源：[packages/core/client/src/schema-component/antd/upload/index.md:17-18]()\n\n## File List Item Rendering\n\nThe file list rendering in `Upload.tsx` demonstrates how individual uploaded files are displayed to users:\n\n```typescript\nconst item = [\n \n \n ,\n showFileName !== false && file.title ? (\n \n {file.status === 'uploading' ? t('Uploading') : file.title}\n \n ) : null,\n];\n```\n\n资料来源：[packages/core/client/src/schema-component/antd/upload/Upload.tsx:1-11]()\n\nThe rendered item can be either a clickable link (if `file.url` exists) or a plain span:\n\n```typescript\nconst wrappedItem = file.url ? (\n \n {item}\n \n) : (\n {item}\n);\n```\n\n资料来源：[packages/core/client/src/schema-component/antd/upload/Upload.tsx:13-20]()\n\n### File Actions\n\nEach file item includes action buttons for managing the upload:\n\n| Action | Condition | Icon | Handler |\n|--------|-----------|------|---------|\n| Download | `!readPretty && file.url` | `DownloadOutlined` | `onDownload` |\n| Delete | `!readPretty && !disabled && file.status !== 'uploading'` | `DeleteOutlined` | `onDelete` |\n\n资料来源：[packages/core/client/src/schema-component/antd/upload/Upload.tsx:23-35]()\n\n## Upload Workflow\n\n```mermaid\ngraph TD\n A[User Selects File] --> B{File Size Check}\n B -->|Greater than 1MB| C[Show Error Alert]\n B -->|Within Limit| D[startScanFile]\n D --> E[Upload to Server]\n E --> F{Upload Status}\n F -->|uploading| G[Show Progress]\n F -->|done| H[Display Thumbnail]\n F -->|error| I[Show Error State]\n```\n\n## File Size Validation\n\nThe system enforces a 1MB limit on uploaded images with user-friendly error messaging:\n\n```typescript\nif (file && file.size < 1024 * 1024) {\n startScanFile(file);\n} else {\n alert(t('The image size is too large. Please compress it to below 1MB before uploading'));\n}\n```\n\n资料来源：[packages/core/client/src/schema-component/antd/input/ScanInput/QRCodeScanner.tsx:1-8]()\n\nThis validation pattern ensures users receive clear guidance when attempting to upload oversized files.\n\n## Thumbnail Preview\n\nThe thumbnail previewer component handles generating previews for uploaded files. The `ThumbnailPreviewer` component is referenced in the upload component's item rendering and provides visual feedback for uploaded content.\n\n## Integration with Schema System\n\n### Schema Designer Integration\n\nFiles can be configured and managed through NocoBase's schema system using the `GeneralSchemaDesigner` component:\n\n```typescript\n\n {showDataSource && dataSource\n ? `${compile(dataSource?.displayName)} > ${compile(title)}`\n : compile(title)}\n\n```\n\n资料来源：[packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx:1-8]()\n\nThis allows file storage configurations to be embedded within the broader schema initialization and settings infrastructure.\n\n## File Type Detection\n\nThe upload system includes utility functions for determining file types, including CSS file detection:\n\n```typescript\nexport function isCssFile(url: string): boolean {\n if (!url || typeof url !== 'string') {\n return false;\n }\n // 去掉 query 和 hash 后判断文件扩展名\n const pathPart = url.split('?')[0].split('#')[0];\n return pathPart.endsWith('.css');\n}\n```\n\n资料来源：[packages/core/flow-engine/src/utils/resolveModuleUrl.ts:1-14]()\n\nThis utility strips query parameters and hash fragments before checking file extensions, supporting URLs like `example.css?v=123` or `example.css#section`.\n\n## Configuration Options\n\n### Upload Component Properties\n\n| Property | Type | Description | Default |\n|----------|------|-------------|---------|\n| `value` | `any` | Controlled value for the file list | - |\n| `onChange` | `(fileList: UploadFile[]) => void` | Callback when file list changes | - |\n| `serviceErrorMessage` | `string` | Custom error message for upload failures | - |\n| `size` | `string` | Size restriction identifier | - |\n| `readPretty` | `boolean` | Display-only mode | `false` |\n\n### File List Item States\n\n| Status | UI Indicator | Available Actions |\n|--------|--------------|-------------------|\n| `uploading` | Progress indicator | None |\n| `done` | Thumbnail + filename | Download, Delete |\n| `error` | Error state | Delete |\n\n## Best Practices\n\n1. **Size Limits**: Always validate file sizes before upload to provide immediate user feedback\n2. **Thumbnail Previews**: Enable thumbnails to improve user experience for image files\n3. **Accessible Links**: Use proper `target=\"_blank\"` and `rel=\"noopener noreferrer\"` for downloaded files\n4. **Status Indicators**: Show upload progress and error states clearly\n5. **URL Handling**: Strip query parameters and hash fragments when determining file types\n\n---\n\n\n\n## Cluster Mode\n\n### 相关页面\n\n相关主题：[Deployment](#deployment), [System Architecture](#system-architecture)\n\n
\nRelated Source Files\n\nThe following source files were referenced for this documentation:\n\n- [docs/docs/en/cluster-mode/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/cluster-mode/index.md)\n- [docs/docs/en/cluster-mode/kubernetes.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/cluster-mode/kubernetes.md)\n- [docs/docs/en/cluster-mode/development.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/cluster-mode/development.md)\n- [docs/docs/en/cluster-mode/operations.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/cluster-mode/operations.md)\n- [docs/docs/en/cluster-mode/preparations.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/cluster-mode/preparations.md)\n- [docs/docs/en/plugins/@nocobase/plugin-lock-adapter-redis/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/plugins/@nocobase/plugin-lock-adapter-redis/index.md)\n- [docs/docs/en/plugins/@nocobase/plugin-pubsub-adapter-redis/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/en/plugins/@nocobase/plugin-pubsub-adapter-redis/index.md)\n
\n\n# Cluster Mode\n\n## Overview\n\nCluster Mode in NocoBase enables horizontal scaling by running multiple application instances behind a load balancer. This architecture provides high availability, improved performance under concurrent load, and fault tolerance for production deployments.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n Client1[Client] --> LB[Load Balancer]\n Client2[Client] --> LB\n Client3[Client] --> LB\n LB --> App1[NocoBase Instance 1]\n LB --> App2[NocoBase Instance 2]\n LB --> App3[NocoBase Instance N]\n App1 <--> Redis[(Redis)]\n App2 <--> Redis\n App3 <--> Redis\n App1 <--> DB[(Database)]\n App2 <--> DB\n App3 <--> DB\n```\n\n### Core Components\n\n| Component | Purpose | Required |\n|-----------|---------|----------|\n| Load Balancer | Distributes traffic across instances | Yes |\n| NocoBase Instances | Application servers running the same codebase | Yes |\n| Shared Database | MySQL/PostgreSQL for persistent data storage | Yes |\n| Redis | Lock adapter and pub/sub for inter-instance communication | Yes |\n| File Storage | S3/MinIO for file uploads (shared across instances) | Yes |\n\n## Prerequisites\n\n### Infrastructure Requirements\n\nBefore deploying in cluster mode, ensure the following:\n\n1. **Database**: MySQL 8.0+ or PostgreSQL 12+ with proper network access\n2. **Redis**: Redis 6.0+ for distributed locking and pub/sub\n3. **File Storage**: Shared storage solution (S3-compatible, MinIO, or NFS)\n4. **Load Balancer**: Nginx, HAProxy, or cloud provider LB\n\n### Environment Variables\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `APP_ENV` | Application environment | `production` |\n| `DB_DIALECT` | Database type | `mysql` or `postgres` |\n| `DB_HOST` | Database host | `localhost` |\n| `DB_PORT` | Database port | `3306` |\n| `DB_DATABASE` | Database name | `nocobase` |\n| `DB_USER` | Database user | `nocobase` |\n| `DB_PASSWORD` | Database password | `***` |\n| `REDIS_URL` | Redis connection string | `redis://localhost:6379` |\n| `CACHE_STORAGE` | Cache storage type | `redis` |\n\n## Redis Plugins\n\nNocoBase requires two Redis plugins for cluster operation:\n\n### Lock Adapter (Redis)\n\nHandles distributed locking to prevent race conditions across instances.\n\n**Plugin**: `@nocobase/plugin-lock-adapter-redis`\n\n```bash\nnpm install @nocobase/plugin-lock-adapter-redis\n```\n\nConfiguration in `database.yml`:\n\n```yaml\nplugins:\n - name: lock\n options:\n type: redis\n redis:\n port: 6379\n host: localhost\n password: ''\n db: 0\n```\n\n### Pub/Sub Adapter (Redis)\n\nEnables real-time communication between instances for features like:\n\n- Live query updates\n- Real-time collaboration\n- Broadcast notifications\n\n**Plugin**: `@nocobase/plugin-pubsub-adapter-redis`\n\n```bash\nnpm install @nocobase/plugin-pubsub-adapter-redis\n```\n\n## Deployment Options\n\n### Docker Compose (Development/Testing)\n\n```yaml\nversion: '3.8'\nservices:\n app:\n image: nocobase/app:latest\n replicas: 3\n depends_on:\n - redis\n - db\n environment:\n - APP_ENV=production\n - DB_DIALECT=postgres\n - REDIS_URL=redis://redis:6379\n deploy:\n replicas: 3\n\n redis:\n image: redis:7-alpine\n ports:\n - \"6379:6379\"\n\n db:\n image: postgres:15\n environment:\n - POSTGRES_DB=nocobase\n - POSTGRES_USER=nocobase\n - POSTGRES_PASSWORD=nocobase\n```\n\n### Kubernetes Deployment\n\nFor production environments, Kubernetes provides:\n\n- Automatic scaling\n- Rolling updates\n- Self-healing capabilities\n- Service discovery\n\nRefer to the [Kubernetes Deployment Guide](kubernetes.md) for detailed configuration.\n\n## Configuration\n\n### Load Balancer Configuration (Nginx)\n\n```nginx\nupstream nocobase_backend {\n least_conn;\n server app1:13000 weight=5;\n server app2:13000 weight=5;\n server app3:13000 weight=5;\n}\n\nserver {\n listen 80;\n server_name your-domain.com;\n\n location / {\n proxy_pass http://nocobase_backend;\n proxy_http_version 1.1;\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection \"upgrade\";\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n }\n\n location /socket.io/ {\n proxy_pass http://nocobase_backend;\n proxy_http_version 1.1;\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection \"upgrade\";\n }\n}\n```\n\n### Application Configuration\n\nIn `data/source/database.yml`:\n\n```yaml\ndatabase:\n type: mysql\n ...\n pool: 10\n\nredis:\n host: redis-host\n port: 6379\n\nplugins:\n - '@nocobase/plugin-lock-adapter-redis'\n - '@nocobase/plugin-pubsub-adapter-redis'\n```\n\n## Operations\n\n### Health Checks\n\nConfigure health check endpoints on the load balancer:\n\n| Endpoint | Expected Response | Purpose |\n|----------|-------------------|---------|\n| `/api/health` | `200 OK` | Instance health status |\n| `/api/healthy` | `200 OK` | Readiness probe |\n\n### Scaling\n\n```mermaid\ngraph LR\n A[Request] --> B{Higher Load?}\n B -->|Yes| C[Scale Up Instances]\n B -->|No| D[Current Scale]\n C --> E[Update LB Pool]\n E --> A\n```\n\n### Monitoring\n\nKey metrics to monitor:\n\n- Request latency per instance\n- Database connection pool usage\n- Redis connection status\n- Session distribution\n- Error rates per instance\n\n### Rolling Updates\n\n1. Deploy new version to subset of instances\n2. Remove updated instances from LB pool temporarily\n3. Update remaining instances\n4. Restore full instance count\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| 502 Bad Gateway | All instances down | Check instance logs, restart services |\n| Stale data displayed | Cache inconsistency | Clear Redis cache, check pub/sub connectivity |\n| Lock contention | High concurrency | Increase Redis resources, optimize locking strategy |\n| WebSocket disconnection | Proxy timeout | Configure longer timeouts in load balancer |\n\n### Diagnostics\n\n```bash\n# Check instance connectivity\ncurl http://instance-ip:13000/api/health\n\n# Verify Redis connectivity\nredis-cli -h redis-host ping\n\n# Check database connectivity\nnpm run nocobase db:ping\n```\n\n## Best Practices\n\n1. **Stateless Design**: Ensure applications do not store user state locally\n2. **Session Management**: Use Redis-backed sessions for sticky sessions\n3. **Database Connection Pooling**: Configure appropriate pool sizes per instance\n4. **File Storage**: Use shared storage to ensure file consistency\n5. **Graceful Shutdown**: Configure proper shutdown handlers for rolling updates\n6. **Logging**: Centralize logs from all instances for debugging\n\n## Related Documentation\n\n- [Kubernetes Deployment](kubernetes.md)\n- [Development Setup](development.md)\n- [Operations Guide](operations.md)\n- [Preparations](preparations.md)\n- [Redis Lock Adapter Plugin](../plugins/@nocobase/plugin-lock-adapter-redis/index.md)\n- [Redis Pub/Sub Adapter Plugin](../plugins/@nocobase/plugin-pubsub-adapter-redis/index.md)\n\n---\n\n\n\n## Plugin Development\n\n### 相关页面\n\n相关主题：[Plugin System](#plugin-system), [System Architecture](#system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/client/src/pm/PluginDetail.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginDetail.tsx)\n- [packages/core/client/src/pm/PluginManagerLink.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginManagerLink.tsx)\n- [packages/core/client/src/application/utils/remotePlugins.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/application/utils/remotePlugins.ts)\n- [packages/core/client/src/nocobase-buildin-plugin/index.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/nocobase-buildin-plugin/index.tsx)\n
\n\n# Plugin Development\n\n## Overview\n\nNocoBase adopts a **plugin-based architecture** where every feature is implemented as a plugin. This modular design enables:\n\n- **Extensibility**: Add new functionality without modifying the core system\n- **Maintainability**: Features are isolated and independently deployable\n- **Reusability**: Plugins can be shared and reused across different projects\n- **Hot-loading**: Plugins can be loaded/unloaded at runtime\n\n```mermaid\ngraph TD\n A[NocoBase Core] --> B[Plugin System]\n B --> C[Server Plugins]\n B --> D[Client Plugins]\n C --> E[Database Operations]\n C --> F[API Routes]\n C --> G[Event Handlers]\n D --> H[UI Components]\n D --> I[Schema Initializers]\n D --> J[Schema Settings]\n```\n\n## Plugin Structure\n\nA typical NocoBase plugin follows this directory structure:\n\n```bash\nmy-plugin/\n├── src/\n│ ├── client/ # Client-side code\n│ │ ├── index.ts # Client plugin entry\n│ │ └── components/ # UI components\n│ ├── server/ # Server-side code\n│ │ ├── index.ts # Server plugin entry\n│ │ ├── actions/ # Custom actions\n│ │ └── migrations/ # Database migrations\n│ └── index.ts # Main entry (client + server)\n├── package.json\n└── dist/ # Build output\n └── externalVersion.js\n```\n\n## Plugin Types\n\n### Server Plugins\n\nServer plugins handle backend logic including database operations, API routes, and event handling.\n\n**Entry Point** (`src/server/index.ts`):\n\n```typescript\nimport { Plugin } from '@nocobase/server';\n\nexport default class MyPlugin extends Plugin {\n async load() {\n // Register collections\n this.app.collection({\n name: 'posts',\n fields: [\n { type: 'string', name: 'title' },\n { type: 'text', name: 'content' },\n ],\n });\n\n // Register API routes\n this.app.resourcer.define({\n name: 'posts',\n actions: {\n async list(ctx, next) {\n ctx.body = await ctx.db.getRepository('posts').find();\n await next();\n },\n },\n });\n }\n}\n\nPlugin.register(MyPlugin);\n```\n\n资料来源：[packages/core/client/src/pm/PluginDetail.tsx:1-50]()\n\n### Client Plugins\n\nClient plugins manage UI components, schema initializers, and schema settings.\n\n**Entry Point** (`src/client/index.ts`):\n\n```typescript\nimport { Plugin } from '@nocobase/client';\n\nexport default class MyPlugin extends Plugin {\n async load() {\n // Register schema initializer\n this.schemaInitializerManager.addItem(\n 'charts',\n 'my-plugin:item',\n {\n title: 'My Chart',\n component: 'MyChartComponent',\n }\n );\n\n // Register schema settings\n this.schemaSettingsManager.add('my-plugin:settings', {\n title: 'My Settings',\n items: [\n { name: 'title', component: 'Input' },\n { name: 'delete', type: 'danger' },\n ],\n });\n }\n}\n\nPlugin.register(MyPlugin);\n```\n\n资料来源：[packages/core/client/src/pm/PluginManagerLink.tsx:1-30]()\n\n## Remote Plugins\n\nNocoBase supports loading plugins remotely via require.js. Remote plugins are configured through the application settings and loaded on demand.\n\n**Configuration** (`src/application/utils/remotePlugins.ts`):\n\n```typescript\nexport function configRequirejs(requirejs: any, pluginData: PluginData[]) {\n requirejs.requirejs.config({\n waitSeconds: 120,\n paths: pluginData.reduce>((acc, cur) => {\n acc[cur.packageName] = cur.url;\n return acc;\n }, {}),\n });\n}\n\nexport function processRemotePlugins(\n pluginData: PluginData[], \n resolve: (plugins: [string, typeof Plugin][]) => void\n) {\n return (...pluginModules: (typeof Plugin & { default?: typeof Plugin })[]) => {\n const res: [string, typeof Plugin][] = pluginModules\n .map<[string, typeof Plugin]>((item, index) => [\n pluginData[index].name, \n item?.default || item\n ])\n .filter((item) => item[1]);\n resolve(res);\n };\n}\n```\n\nKey characteristics:\n- **Timeout**: 120 seconds wait time for plugin loading\n- **Path Mapping**: Maps package names to remote URLs\n- **Default Export**: Automatically handles both default and named exports\n\n资料来源：[packages/core/client/src/application/utils/remotePlugins.ts:40-70]()\n\n## Plugin Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> Registered\n Registered --> Loading\n Loading --> Loaded\n Loaded --> Enabled\n Enabled --> Disabled\n Disabled --> Enabled\n Enabled --> Unloaded\n Unloaded --> [*]\n```\n\n### Application States\n\nThe plugin system tracks various application states during initialization:\n\n| State Code | Status | Icon | Description |\n|------------|--------|------|-------------|\n| `APP_PREPARING` | info | LoadingOutlined | App preparing |\n| `APP_INITIALIZING` | info | LoadingOutlined | App initializing |\n| `APP_INITIALIZED` | info | - | App initialized |\n| `APP_NOT_INSTALLED_ERROR` | warning | - | App not installed |\n| `APP_STOPPED` | warning | - | App stopped |\n| `APP_COMMANDING` | info | LoadingOutlined | App commanding |\n| `ENOENT`, `APP_ERROR`, `LOAD_ERROR` | error | - | App error |\n\n资料来源：[packages/core/client/src/nocobase-buildin-plugin/index.tsx:1-60]()\n\n## Plugin Manager\n\nThe Plugin Manager provides a UI interface for managing plugins with the following features:\n\n### Plugin Detail Display\n\n```typescript\ninterface PluginDetailProps {\n plugin: {\n packageName: string;\n version: string;\n name: string;\n displayName?: string;\n description?: string;\n version?: string;\n };\n data?: {\n packageJson: {\n license?: string;\n };\n homepage?: string;\n depsCompatible: boolean | null;\n isCompatible: boolean;\n };\n}\n```\n\nThe plugin detail view displays:\n\n- **Package Name**: Unique identifier for the plugin\n- **Version**: Current installed version\n- **Display Name**: Human-readable name\n- **Description**: Plugin functionality description\n- **License**: Package license type\n- **Homepage**: External documentation URL\n- **Dependencies**: Compatibility status\n\n资料来源：[packages/core/client/src/pm/PluginDetail.tsx:1-100]()\n\n### Dependencies Compatibility Check\n\n```typescript\n{\n key: 'dependencies',\n label: t('Dependencies compatibility check'),\n children: (\n <>\n {data?.data?.depsCompatible === false ? (\n \n {t('`dist/externalVersion.js` not found or failed to `require`. Please rebuild this plugin.')}\n \n ) : (\n <>\n {!data?.data?.['isCompatible'] && (\n \n )}\n \n \n )}\n \n ),\n}\n```\n\n| Check Type | Condition | Message |\n|------------|-----------|---------|\n| Build Required | `dist/externalVersion.js` not found | Rebuild plugin required |\n| Compatibility | `isCompatible === false` | Dependency version mismatch |\n| Success | All checks pass | Dependencies compatible |\n\n资料来源：[packages/core/client/src/pm/PluginDetail.tsx:20-45]()\n\n## Plugin Settings\n\nPlugins can register their own settings pages in the administration interface:\n\n```typescript\nconst settingItems = settings\n .filter((setting) => setting.visible !== false)\n .map((setting) => {\n return {\n key: setting.name,\n icon: setting.icon,\n label: setting.link ? (\n
window.open(setting.link)}>\n {compile(setting.title)}\n
\n ) : (\n {compile(setting.title)}\n ),\n };\n });\n```\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `name` | string | Unique setting identifier |\n| `title` | string | Display title |\n| `icon` | ReactNode | Setting icon |\n| `path` | string | Navigation route |\n| `link` | string | External link (optional) |\n| `visible` | boolean | Visibility control |\n\n资料来源：[packages/core/client/src/pm/PluginManagerLink.tsx:1-50]()\n\n## Building Plugins\n\n### Build Output Requirements\n\nAfter building a plugin, ensure the following files exist in the `dist/` directory:\n\n```\ndist/\n├── index.js\n├── client.js\n├── server.js\n└── externalVersion.js # Required for compatibility\n```\n\nThe `externalVersion.js` file exports version information for dependency compatibility checks.\n\n### Remote Plugin Loading\n\n```typescript\ninterface PluginData {\n packageName: string;\n url: string;\n name: string;\n}\n```\n\nPlugins loaded remotely must:\n1. Export a default class extending `Plugin`\n2. Be accessible via the configured URL\n3. Include `externalVersion.js` for dependency validation\n\n资料来源：[packages/core/client/src/application/utils/remotePlugins.ts:1-40]()\n\n## Error Handling\n\n### Plugin Load Errors\n\nWhen plugins fail to load, the system logs detailed error messages:\n\n```typescript\nif (emptyPlugins.length > 0) {\n console.error(\n '[nocobase load plugin error]: These plugins do not have an `export.default` exported content or there is an error in the plugins. error plugins: \\r\\n%s',\n emptyPlugins.join(', \\r\\n'),\n );\n}\n```\n\nCommon error causes:\n- Missing `export default` in the plugin entry\n- Syntax errors in plugin code\n- Circular dependency issues\n- Timeout during remote plugin loading\n\n### App Error States\n\n| Error Code | Severity | Resolution |\n|------------|----------|------------|\n| `ENOENT` | error | Check file paths and build output |\n| `APP_ERROR` | error | Review application logs |\n| `LOAD_ERROR` | error | Verify plugin exports and dependencies |\n| `APP_NOT_INSTALLED` | warning | Run installation command |\n| `APP_STOPPED` | warning | Restart the application |\n\n资料来源：[packages/core/client/src/nocobase-buildin-plugin/index.tsx:40-55]()\n\n## Schema Integration\n\nPlugins can extend the application schema system by registering:\n\n### Schema Initializers\n\nEnable adding new items to schema initialization panels:\n\n```typescript\nthis.schemaInitializerManager.addItem(\n scope: string, // Parent group identifier\n key: string, // Unique item key\n item: SchemaInitializerItem // Item configuration\n);\n```\n\n### Schema Settings\n\nAdd configuration panels for schema components:\n\n```typescript\nthis.schemaSettingsManager.add(\n name: string,\n config: SchemaSettingsConfig\n);\n```\n\n## Best Practices\n\n1. **Always export default**: Plugin classes must use `export default` for proper loading\n2. **Include externalVersion.js**: Required for dependency compatibility checks\n3. **Handle errors gracefully**: Wrap async operations in try-catch blocks\n4. **Use unique namespacing**: Prefix plugin-specific names with plugin name\n5. **Document dependencies**: Clearly specify version requirements in package.json\n\n## Related Documentation\n\n- [Write Your First Plugin](write-your-first-plugin.md)\n- [Server Development](server/index.md)\n- [Client Development](client/index.md)\n- [Dependency Management](dependency-management.md)\n- [Building Plugins](build.md)\n- [Internationalization](languages.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：nocobase/nocobase\n\n摘要：发现 17 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：REST API: Multiple select field not working in edit form。\n\n## 1. 安全/权限坑 · 来源证据：REST API: Multiple select field not working in edit form\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：REST API: Multiple select field not working in edit form\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_36b6b605781f4652849d06443cd76da9 | https://github.com/nocobase/nocobase/issues/8836 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：v2.1.0-alpha.33\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0-alpha.33\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_71fc97aec74e43618fab9e19d0aa9a9f | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.33 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：v2.1.0-beta.30\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0-beta.30\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3eea74dae9c548fc8058563df21058d3 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.30 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 配置坑 · 来源证据：v2.0.51\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.0.51\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_06f3ce01049e42f586931cf6e9a46335 | https://github.com/nocobase/nocobase/releases/tag/v2.0.51 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 配置坑 · 来源证据：v2.1.0-alpha.32\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.1.0-alpha.32\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7055255c88f94ecc84dfc5c09fc6c3a3 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.32 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 配置坑 · 来源证据：v2.1.0-beta.29\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.1.0-beta.29\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c4b7dfdc1a164f5cb82fec5622b80342 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.29 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 能力坑 · 能力判断依赖假设\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:306829688 | https://github.com/nocobase/nocobase | README/documentation is current enough for a first validation pass.\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:306829688 | https://github.com/nocobase/nocobase | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:306829688 | https://github.com/nocobase/nocobase | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:306829688 | https://github.com/nocobase/nocobase | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 11. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:306829688 | https://github.com/nocobase/nocobase | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 来源证据：v2.0.52\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.52\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1ca2b2aac82447ea8ca5b5536fff978e | https://github.com/nocobase/nocobase/releases/tag/v2.0.52 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：v2.1.0-alpha.31\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0-alpha.31\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7a2bc590f0974b79880f86db553b3a2e | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.31 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：v2.1.0-beta.27\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0-beta.27\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_43d1bbbbee81474cb8e2e4f722fdb398 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.27 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：v2.1.0-beta.32\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0-beta.32\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_31e3065c9e884205a29f181cbbc50458 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.32 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · 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:306829688 | https://github.com/nocobase/nocobase | issue_or_pr_quality=unknown\n\n## 17. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:306829688 | https://github.com/nocobase/nocobase | 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项目：nocobase/nocobase\n\n摘要：发现 17 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：REST API: Multiple select field not working in edit form。\n\n## 1. 安全/权限坑 · 来源证据：REST API: Multiple select field not working in edit form\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：REST API: Multiple select field not working in edit form\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_36b6b605781f4652849d06443cd76da9 | https://github.com/nocobase/nocobase/issues/8836 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：v2.1.0-alpha.33\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0-alpha.33\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_71fc97aec74e43618fab9e19d0aa9a9f | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.33 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：v2.1.0-beta.30\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0-beta.30\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3eea74dae9c548fc8058563df21058d3 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.30 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 配置坑 · 来源证据：v2.0.51\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.0.51\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_06f3ce01049e42f586931cf6e9a46335 | https://github.com/nocobase/nocobase/releases/tag/v2.0.51 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 配置坑 · 来源证据：v2.1.0-alpha.32\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.1.0-alpha.32\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7055255c88f94ecc84dfc5c09fc6c3a3 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.32 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 配置坑 · 来源证据：v2.1.0-beta.29\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.1.0-beta.29\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c4b7dfdc1a164f5cb82fec5622b80342 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.29 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 能力坑 · 能力判断依赖假设\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:306829688 | https://github.com/nocobase/nocobase | README/documentation is current enough for a first validation pass.\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:306829688 | https://github.com/nocobase/nocobase | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:306829688 | https://github.com/nocobase/nocobase | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:306829688 | https://github.com/nocobase/nocobase | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 11. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:306829688 | https://github.com/nocobase/nocobase | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 来源证据：v2.0.52\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.52\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1ca2b2aac82447ea8ca5b5536fff978e | https://github.com/nocobase/nocobase/releases/tag/v2.0.52 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：v2.1.0-alpha.31\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0-alpha.31\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7a2bc590f0974b79880f86db553b3a2e | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.31 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：v2.1.0-beta.27\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0-beta.27\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_43d1bbbbee81474cb8e2e4f722fdb398 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.27 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：v2.1.0-beta.32\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0-beta.32\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_31e3065c9e884205a29f181cbbc50458 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.32 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · 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:306829688 | https://github.com/nocobase/nocobase | issue_or_pr_quality=unknown\n\n## 17. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:306829688 | https://github.com/nocobase/nocobase | release_recency=unknown\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# nocobase - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for nocobase/nocobase.\n\nProject:\n- Name: nocobase\n- Repository: https://github.com/nocobase/nocobase\n- Summary: NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. overview: Overview. Produce one small intermediate artifact and wait for confirmation.\n2. system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n3. deployment: Deployment. Produce one small intermediate artifact and wait for confirmation.\n4. plugin-system: Plugin System. Produce one small intermediate artifact and wait for confirmation.\n5. data-modeling: Data Modeling. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/nocobase/nocobase\n- https://github.com/nocobase/nocobase#readme\n- docs/docs/de/ai-employees/advanced/skill.md\n- docs/docs/es/ai-employees/advanced/skill.md\n- docs/docs/fr/ai-employees/advanced/skill.md\n- docs/docs/ja/ai-employees/advanced/skill.md\n- docs/docs/ko/ai-employees/advanced/skill.md\n- docs/docs/pt/ai-employees/advanced/skill.md\n- docs/docs/ru/ai-employees/advanced/skill.md\n- README.md\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：nocobase/nocobase\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install -g @nocobase/cli@beta\n```\n\n来源：https://github.com/nocobase/nocobase#readme\n\n## 来源\n\n- repo: https://github.com/nocobase/nocobase\n- docs: https://github.com/nocobase/nocobase#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_f19ace9415b842238cdebc408dab5a9d" }