{ "canonical_name": "nocobase/nocobase", "compilation_id": "pack_8b7b1742fc9b4f6eadde8aa4738727fb", "created_at": "2026-05-13T23:32:11.033502+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": "manual corrective reclassification after strong category signal" }, "target_user": "使用 local_cli 等宿主 AI 的用户", "title_en": "nocobase", "title_zh": "nocobase 能力包", "visible_tags": [ { "label_en": "Knowledge Retrieval", "label_zh": "知识检索", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-knowledge-retrieval", "type": "product_domain" }, { "label_en": "Knowledge Base Q&A", "label_zh": "知识库问答", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-knowledge-base-q-a", "type": "user_job" }, { "label_en": "Workflow Automation", "label_zh": "流程自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-workflow-automation", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "type": "workflow_pattern" }, { "label_en": "Evaluation Suite", "label_zh": "评测体系", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-evaluation-suite", "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": [ "知识检索", "知识库问答", "流程自动化", "节点式流程编排", "评测体系" ], "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> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 nocobase 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. nocobase-overview：NocoBase 概述。围绕“NocoBase 概述”模拟一次用户任务，不展示安装或运行结果。\n2. system-architecture：系统架构与设计模式。围绕“系统架构与设计模式”模拟一次用户任务，不展示安装或运行结果。\n3. data-modeling：数据建模与集合管理。围绕“数据建模与集合管理”模拟一次用户任务，不展示安装或运行结果。\n4. acl-permissions：权限系统与 ACL。围绕“权限系统与 ACL”模拟一次用户任务，不展示安装或运行结果。\n5. workflow-engine：工作流引擎。围绕“工作流引擎”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. nocobase-overview\n输入：用户提供的“NocoBase 概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. system-architecture\n输入：用户提供的“系统架构与设计模式”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. data-modeling\n输入：用户提供的“数据建模与集合管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. acl-permissions\n输入：用户提供的“权限系统与 ACL”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. workflow-engine\n输入：用户提供的“工作流引擎”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / nocobase-overview：Step 1 必须围绕“NocoBase 概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / system-architecture：Step 2 必须围绕“系统架构与设计模式”形成一个小中间产物，并等待用户确认。\n- Step 3 / data-modeling：Step 3 必须围绕“数据建模与集合管理”形成一个小中间产物，并等待用户确认。\n- Step 4 / acl-permissions：Step 4 必须围绕“权限系统与 ACL”形成一个小中间产物，并等待用户确认。\n- Step 5 / workflow-engine：Step 5 必须围绕“工作流引擎”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\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- README.zh-CN.md\n- package.json\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 nocobase 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "voices": [ { "body": "来源平台：github。github/github_issue: 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": [ "知识检索", "知识库问答", "流程自动化", "节点式流程编排", "评测体系" ], "thumb": "gray", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/nocobase/nocobase 项目说明书\n\n生成时间：2026-05-13 22:57:37 UTC\n\n## 目录\n\n- [NocoBase 概述](#nocobase-overview)\n- [系统架构与设计模式](#system-architecture)\n- [数据建模与集合管理](#data-modeling)\n- [外部数据源与多数据库支持](#external-data-sources)\n- [权限系统与 ACL](#acl-permissions)\n- [工作流引擎](#workflow-engine)\n- [AI 集成与智能员工](#ai-integration)\n- [界面构建器](#interface-builder)\n- [文件管理与存储](#file-manager)\n- [插件开发指南](#plugin-development)\n\n\n\n## NocoBase 概述\n\n### 相关页面\n\n相关主题：[系统架构与设计模式](#system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/nocobase/nocobase/blob/main/README.md)\n- [README.zh-CN.md](https://github.com/nocobase/nocobase/blob/main/README.zh-CN.md)\n- [package.json](https://github.com/nocobase/nocobase/blob/main/package.json)\n- [packages/core/client/src/user/Help.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/user/Help.tsx)\n- [packages/core/flow-engine/src/flowSettings.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/flowSettings.ts)\n
\n\n# NocoBase 概述\n\n## 什么是 NocoBase\n\nNocoBase 是一个开源的 AI + 无代码平台，用于快速构建业务系统。与从零开始生成所有内容不同，AI 在经过生产验证的基础设施和所见即所得（WYSIWYG）的无代码界面上工作，既能保证开发速度，又能确保系统的稳定性和可靠性。\n\n资料来源：[README.md:1-10]()\n\n### 核心价值主张\n\nNocoBase 的核心价值在于将人工智能与无代码技术相结合，让开发者和业务用户能够：\n\n- **快速构建**：通过可视化配置而非传统编码方式快速搭建业务系统\n- **AI 赋能**：借助 AI Agent 实现自动化和智能化的业务流程\n- **灵活扩展**：支持插件化架构，可根据需求扩展功能\n- **协作共建**：AI 和人类协同工作，共同构建系统\n\n资料来源：[README.md:47-52]()\n\n---\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TB\n subgraph 前端层[\"前端层 (Client)\"]\n PC[PC 端客户端]\n Mobile[移动端插件
@nocobase/plugin-mobile]\n Theme[主题编辑器
@nocobase/plugin-theme-editor]\n end\n \n subgraph 核心层[\"核心模块 (Core)\"]\n Schema[Schema 组件系统]\n PM[插件管理器
PluginManager]\n FlowEngine[流程引擎
FlowEngine]\n Variables[变量系统]\n SchemaSettings[Schema 配置]\n SchemaInitializer[Schema 初始化器]\n end\n \n subgraph 插件层[\"插件生态\"]\n AI[AI 插件
@nocobase/plugin-ai]\n Auth[认证插件]\n Database[数据库插件]\n API[API 插件]\n end\n \n subgraph 服务层[\"服务端 (Server)\"]\n Server[服务端核心]\n DatabaseEngine[(数据库引擎)]\n end\n \n PC --> Schema\n PC --> PM\n Mobile --> Schema\n Theme --> Schema\n \n Schema --> SchemaSettings\n Schema --> SchemaInitializer\n \n PM --> AI\n PM --> Auth\n PM --> Database\n \n AI --> Server\n Server --> DatabaseEngine\n \n PC --> Server\n```\n\n### 目录结构\n\nNocoBase 采用 monorepo 结构，主要目录如下：\n\n| 目录 | 说明 |\n|------|------|\n| `packages/core/` | 核心包，包含客户端和服务端基础模块 |\n| `packages/core/client/` | 前端核心代码 |\n| `packages/core/flow-engine/` | 流程引擎实现 |\n| `packages/plugins/` | 官方插件集合 |\n| `packages/plugins/@nocobase/plugin-mobile/` | 移动端支持插件 |\n| `packages/plugins/@nocobase/plugin-ai/` | AI 能力插件 |\n| `packages/plugins/@nocobase/plugin-theme-editor/` | 主题编辑器插件 |\n\n资料来源：[package.json:1-20]()\n\n---\n\n## 核心模块详解\n\n### 插件管理系统 (PluginManager)\n\nNocoBase 的核心架构基于插件系统，插件管理器（PluginManager）负责插件的加载、启停和管理。\n\n```mermaid\ngraph LR\n subgraph 插件详情[\"插件详情组件\"]\n PInfo[基本信息]\n DCheck[依赖兼容性检查]\n CHLog[更新日志]\n end\n \n PM[PluginManager] --> PInfo\n PM --> DCheck\n PM --> CHLog\n \n DCheck --> |兼容性状态| Alert[警告提示]\n DCheck --> Table[依赖表格]\n```\n\n每个插件包含以下元信息：\n\n| 属性 | 说明 |\n|------|------|\n| `packageName` | 插件包名称 |\n| `version` | 当前版本号 |\n| `description` | 插件描述 |\n| `author` | 作者信息 |\n| `license` | 开源许可证 |\n| `homepage` | 项目主页 |\n| `isCompatible` | 与系统的兼容性状态 |\n\n资料来源：[packages/core/client/src/pm/PluginDetail.tsx:1-50]()\n\n### Schema 组件系统\n\nSchema 是 NocoBase 中用于描述界面配置的核心概念，通过声明式的 Schema 定义，可以配置页面的布局、字段、动作等元素。\n\n#### Schema 组成部分\n\n| 组件 | 功能 |\n|------|------|\n| SchemaSettings | Schema 的配置面板，用于设置组件属性 |\n| SchemaInitializer | Schema 的初始化器，决定可以在何处添加新元素 |\n| GeneralSchemaDesigner | 通用的 Schema 设计器组件 |\n| LinkageFilter | 联动过滤器，用于配置条件联动规则 |\n\n资料来源：[packages/core/client/src/schema-settings/index.md:1-20]()\n资料来源：[packages/core/client/src/schema-component/antd/linkageFilter/index.md:1-15]()\n\n### 变量系统 (Variables)\n\nNocoBase 提供丰富的内置变量系统，支持在配置中引用各种运行时上下文。\n\n```mermaid\ngraph TD\n V[内置变量] --> User[用户变量]\n V --> Role[角色变量]\n V --> DateTime[时间变量]\n V --> URL[URL 参数]\n V --> System[系统变量]\n \n User --> |$nUserId| UserId[当前用户 ID]\n User --> |$nUserRoles| UserRoles[当前用户角色]\n User --> |$nUserEmail| UserEmail[用户邮箱]\n \n DateTime --> |$nDate| CurrentDate[当前日期]\n DateTime --> |$nExactDate| ExactDateTime[精确时间]\n \n System --> |$system| SystemInfo[系统信息]\n```\n\n**内置变量列表：**\n\n| 变量名 | 说明 | 状态 |\n|--------|------|------|\n| `$nUserId` | 当前登录用户 ID | 活跃 |\n| `$nRoleId` | 当前用户角色 ID | 活跃 |\n| `$nDate` | 当前日期时间 | 活跃 |\n| `$nExactDate` | 精确时间戳 | 活跃 |\n| `$date` | 日期（已废弃） | 废弃 |\n| `$system` | 系统变量（已废弃） | 废弃 |\n| `currentTime` | 当前时间（已废弃） | 废弃 |\n| `urlSearchParams` | URL 查询参数 | 活跃 |\n\n资料来源：[packages/core/client/src/variables/hooks/useBuiltinVariables.ts:1-80]()\n\n### 流程引擎 (Flow Engine)\n\n流程引擎是 NocoBase 处理复杂业务流程的核心模块，支持可视化的工作流配置。\n\n#### FlowSettings 配置结构\n\n```typescript\ninterface FlowSettingsConfig {\n footer?: React.ReactNode | ((originNode, { OkBtn, CancelBtn }) => React.ReactNode) | null;\n [key: string]: any;\n}\n```\n\n**Footer 自定义方式：**\n\n| 类型 | 示例 | 说明 |\n|------|------|------|\n| 直接渲染 | `` | 静态内容 |\n| 包裹式 | `footer: (originNode) => (
包裹 {originNode}
)` | 在原有按钮外添加内容 |\n| 函数式 | `footer: (originNode, { OkBtn, CancelBtn }) => ()` | 完全自定义按钮组合 |\n| 隐藏 | `footer: null` | 隐藏底部按钮栏 |\n\n资料来源：[packages/core/flow-engine/src/flowSettings.ts:1-50]()\n\n---\n\n## 主要功能特性\n\n### 1. 协作式构建\n\nNocoBase 强调 AI 和人类协作构建系统的理念：\n\n- AI Agent 可以帮助完成代码生成、API 调用、文档阅读等任务\n- 人类开发者通过可视化的无代码界面进行配置和调整\n- 两者相互配合，提高开发效率\n\n资料来源：[README.md:53-58]()\n\n### 2. 移动端支持\n\n通过 `@nocobase/plugin-mobile` 插件，NocoBase 支持移动端应用的构建：\n\n| 组件 | 说明 |\n|------|------|\n| MobileTabBar | 移动端底部导航栏 |\n| MobileTabBar.Item | 导航项 |\n| MobileTabBar.Link | 链接导航项，支持内部页面和外部页面跳转 |\n| DesktopMode | 桌面端访问移动端页面时的占位组件 |\n\n移动端支持 Schema 配置，可以实现复杂的移动端页面布局。\n\n资料来源：[packages/plugins/@nocobase/plugin-mobile/src/client/pages/index.md:1-25]()\n资料来源：[packages/plugins/@nocobase/plugin-mobile/src/client/mobile-layout/index.md:1-20]()\n\n### 3. 主题定制\n\n`@nocobase/plugin-theme-editor` 插件提供了主题编辑功能，支持通过 Ant Design Token 定制界面样式。\n\n资料来源：[packages/plugins/@nocobase/plugin-theme-editor/src/client/antd-token-previewer/component-demos/typography/typographyFull.tsx:1-30]()\n\n### 4. AI Agent 能力\n\n`@nocobase/plugin-ai` 插件集成了 AI 能力，支持：\n\n- 文档阅读和检索\n- 代码生成和执行\n- 数据库操作的智能辅助\n- 多数据源支持\n\n**AI 插件特性：**\n\n| 功能 | 说明 |\n|------|------|\n| 文档工具 | 读取项目文档和 API 文档 |\n| 代码执行 | 支持 RunJS 等代码执行环境 |\n| 数据库操作 | 辅助生成 SQL 和数据库操作 |\n| 多语言支持 | 支持中英文等不同语言的交互 |\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/tools/docs.ts:1-50]()\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/ai-employees/prompts.ts:1-40]()\n\n---\n\n## 快速链接\n\n### 官方资源\n\n| 资源 | 链接 |\n|------|------|\n| 官方网站 | https://www.nocobase.com/ |\n| 在线演示 | https://demo.nocobase.com/new |\n| 开发文档 | https://docs.nocobase.com/ |\n| 用户论坛 | https://forum.nocobase.com/ |\n| 更新日志 | https://www.nocobase.com/en/blog/timeline |\n\n资料来源：[README.md:20-40]()\n资料来源：[packages/core/client/src/user/Help.tsx:1-50]()\n\n---\n\n## 技术栈概览\n\n### 前端技术\n\n- **框架**：React\n- **UI 库**：Ant Design\n- **状态管理**：Zustand\n- **移动端**：React Native（通过 WebView 混合方案）\n\n### 后端技术\n\n- **运行时**：Node.js\n- **框架**：Koa.js\n- **数据库**：支持多种数据库（MySQL、PostgreSQL、SQLite 等）\n\n### 构建工具\n\n- **包管理**：pnpm\n- **构建**：Turborepo\n- **类型检查**：TypeScript\n\n资料来源：[package.json:1-100]()\n\n---\n\n## 总结\n\nNocoBase 是一个现代化的开源无代码平台，通过以下核心特性为业务系统开发提供强大支持：\n\n1. **插件化架构**：高度可扩展的插件系统，支持按需加载功能\n2. **Schema 驱动的配置**：声明式的界面配置方式\n3. **AI 赋能**：集成 AI Agent，提升开发效率\n4. **多端支持**：同时支持桌面端和移动端\n5. **灵活的主题定制**：通过 Token 系统实现品牌定制\n\n无论是小型业务系统还是大型企业应用，NocoBase 都能提供灵活、高效的解决方案。\n\n---\n\n\n\n## 系统架构与设计模式\n\n### 相关页面\n\n相关主题：[NocoBase 概述](#nocobase-overview), [插件开发指南](#plugin-development)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/client/src/application.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/application.ts)\n- [packages/core/server/src/application.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/server/src/application.ts)\n- [packages/core/server/src/plugin.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/server/src/plugin.ts)\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/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
\n\n# 系统架构与设计模式\n\n## 概述\n\nNocoBase 采用分层模块化架构设计，核心遵循**插件化架构**（Plugin Architecture）和**配置驱动架构**（Configuration-driven Architecture）两大设计理念。系统分为服务端（Server）和客户端（Client）两大主体，通过插件机制实现功能扩展，通过 Schema 配置驱动实现前端界面与业务逻辑的解耦。\n\n## 核心架构分层\n\n### 架构层次总览\n\n```graph TD\n A[客户端 Client] --> B[应用层 Application]\n A --> C[Schema 组件层]\n A --> D[Schema 配置层]\n B --> E[插件管理层 PM]\n C --> F[数据区块 Provider]\n D --> G[Schema 设计器]\n E --> H[插件 Plugin]\n H --> I[服务端插件]\n H --> J[客户端插件]\n```\n\n### 服务端架构\n\n服务端基于 **Plugin 插件基类**构建，所有业务模块均以插件形式注册。插件系统提供了完整的生命周期管理，包括 `load`、`enable`、`disable` 等状态转换。\n\n```graph TD\n A[Application] --> B[Plugin Manager]\n A --> C[数据层 Data]\n A --> D[认证层 Auth]\n B --> E[Plugin 实例]\n E --> F[install]\n E --> G[load]\n E --> H[enable]\n E --> I[disable]\n```\n\n服务端 `Application` 类负责统一管理插件的加载与初始化流程，通过 `pm`（Plugin Manager）实现插件的注册、启用、停用等操作。资料来源：[packages/core/server/src/application.ts]()\n\n### 客户端架构\n\n客户端采用 **React Context** 进行状态管理和依赖注入，主要包括以下几个核心模块：\n\n| 模块 | 职责 | 核心文件 |\n|------|------|----------|\n| Application | 应用初始化与全局状态 | application.ts |\n| SchemaComponent | Schema 驱动的组件渲染 | schema-component/index.md |\n| SchemaSettings | Schema 配置编辑器 | schema-settings/index.md |\n| SchemaInitializer | Schema 初始化器 | schema-initializer/index.md |\n| PM (Plugin Manager) | 插件管理与详情展示 | PluginDetail.tsx |\n\n## 插件系统设计\n\n### 插件架构模式\n\nNocoBase 的插件系统采用**观察者模式**与**依赖注入模式**相结合的架构。每个插件包含服务端和客户端两部分，通过统一的插件管理器进行协调。\n\n```mermaid\ngraph TD\n subgraph 服务端\n A1[Plugin 基类] --> A2[install 方法]\n A1 --> A3[load 方法]\n A1 --> A4[enable 方法]\n end\n \n subgraph 客户端\n B1[React Component] --> B2[Configuration]\n B1 --> B3[Settings]\n B1 --> B4[Initializer]\n end\n \n A1 --> B1\n```\n\n### 插件元数据管理\n\n插件详情组件 `PluginDetail` 展示插件的完整信息，包括版本、依赖兼容性、许可证等。依赖兼容性检查机制确保插件间的版本匹配。\n\n```typescript\n// 插件详情信息结构\ninterface PluginInfo {\n packageName: string; // 包名\n version: string; // 版本号\n description?: string; // 描述\n author?: string; // 作者\n homepage?: string; // 主页\n license?: string; // 许可证\n depsCompatible?: boolean; // 依赖兼容性\n}\n```\n\n资料来源：[packages/core/client/src/pm/PluginDetail.tsx]()\n\n### 依赖兼容性检查\n\n插件系统内置依赖兼容性检查机制，通过 `externalVersion.js` 文件记录插件的外部依赖版本信息。检查结果通过 `isCompatible` 字段标识，兼容性检查失败时会显示错误提示。\n\n## Schema 驱动架构\n\n### Schema 设计理念\n\nNocoBase 的前端界面完全由 **Schema 配置**驱动。Schema 是 JSON 格式的配置对象，定义了界面的结构、行为和样式。这种设计实现了**界面与逻辑的分离**，使非开发人员也能通过配置自定义系统功能。\n\n```mermaid\ngraph LR\n A[Schema JSON] --> B[Schema 解析器]\n B --> C[SchemaComponent]\n B --> D[SchemaSettings]\n B --> E[SchemaInitializer]\n C --> F[用户界面]\n```\n\n### Schema 组件层级\n\n| 组件类型 | 用途 | 配置属性 |\n|----------|------|----------|\n| SchemaComponent | 根据 Schema 渲染 UI | `x-component` |\n| SchemaSettings | 组件的配置面板 | `x-settings` |\n| SchemaInitializer | 组件的初始化器 | `x-initializer` |\n\n### SchemaToolbar 组件\n\n`GeneralSchemaDesigner` 是 Schema 设计器的核心组件，负责渲染 Schema 的工具栏界面，包括标题、拖拽手柄、初始化器和配置下拉菜单。\n\n```typescript\ninterface SchemaToolbarProps {\n title?: string | string[];\n template?: boolean;\n draggable?: boolean;\n showDataSource?: boolean;\n templateName?: string;\n}\n```\n\n资料来源：[packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx]()\n\n## 流程引擎架构\n\n### FlowSettings 配置系统\n\n流程引擎（Flow Engine）采用**配置化设计**，通过 `FlowSettings` 类管理流程节点组件和作用域变量。\n\n```typescript\nclass 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]()\n\n### 流程配置 Footer 自定义\n\n流程设置支持四种 Footer 配置模式：\n\n| 模式 | 类型 | 说明 |\n|------|------|------|\n| 默认 | `React.ReactNode` | 原生 React 节点 |\n| 增强 | 函数式 | `(originNode, { OkBtn, CancelBtn }) => ReactNode` |\n| 完全自定义 | 函数式 | 重新组合按钮布局 |\n| 隐藏 | `null` | 隐藏底部区域 |\n\n## 变量系统\n\n### 内置变量机制\n\n系统提供内置变量支持，通过 `useBuiltInVariables` Hook 获取。内置变量包括用户上下文、日期时间、URL 参数等。\n\n```typescript\n// 内置变量列表\nconst builtinVariables = [\n { name: '$nUser', ctx: currentUserCtx },\n { name: '$nRole', ctx: currentRoleCtx },\n { name: '$nDate', ctx: datetimeCtx },\n { name: '$nExactDate', ctx: exactDateTimeCtx },\n { name: '$nUrlSearchParams', ctx: urlSearchParamsCtx },\n { name: '$env', ctx: envVariableCtx },\n];\n```\n\n已废弃的兼容变量包括 `$date`、`$system`、`currentTime`，建议使用新版变量名替代。\n\n资料来源：[packages/core/client/src/variables/hooks/useBuiltinVariables.ts]()\n\n## 设计模式总结\n\n### 核心设计模式\n\n| 模式名称 | 应用场景 | 实现方式 |\n|----------|----------|----------|\n| 插件模式 | 功能扩展 | Plugin 基类 + PM 管理器 |\n| 配置驱动 | UI 生成 | Schema JSON 配置 |\n| 依赖注入 | 状态共享 | React Context Provider |\n| 观察者模式 | 事件通知 | 插件生命周期事件 |\n| 策略模式 | 流程节点 | FlowSettings components |\n| 工厂模式 | Schema 组件 | x-component 类型映射 |\n\n### 模块间通信\n\n```mermaid\nsequenceDiagram\n participant App as Application\n participant PM as Plugin Manager\n participant Plugin as Plugin\n participant Schema as SchemaComponent\n \n App->>PM: 注册插件\n PM->>Plugin: 实例化\n Plugin->>Plugin: load()\n Plugin->>Schema: 注册组件\n Schema->>Schema: 渲染界面\n```\n\n## 移动端适配\n\n系统通过 `DesktopMode` 组件实现移动端与桌面端的视图切换，当检测到非移动端设备访问移动端页面时，渲染桌面端适配组件。\n\n```tsx\n\n \n\n```\n\n## 系统信息与帮助\n\n`Help` 组件负责展示系统信息，包括版本号（`data?.data?.version`）、文档链接、许可证信息等。根据语言设置（`isSimplifiedChinese`）动态切换中英文文档地址。\n\n资料来源：[packages/core/client/src/user/Help.tsx]()\n\n---\n\n## 总结\n\nNocoBase 的系统架构围绕**插件化**和**配置驱动**两大核心理念构建，实现了高度的模块化和可扩展性。服务端通过 Plugin 基类实现功能模块化管理，客户端通过 Schema 配置实现界面的动态渲染，两者通过统一的插件管理器协调工作，形成一个完整的有机整体。\n\n---\n\n\n\n## 数据建模与集合管理\n\n### 相关页面\n\n相关主题：[外部数据源与多数据库支持](#external-data-sources), [权限系统与 ACL](#acl-permissions)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/database/src/collection.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/database/src/collection.ts)\n- [packages/core/database/src/field.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/database/src/field.ts)\n- [packages/core/database/src/repository.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/database/src/repository.ts)\n- [packages/plugins/@nocobase/plugin-data-source-manager](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-data-source-manager)\n- [packages/core/client/src/collection-manager/Configuration/components/Summary.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/collection-manager/Configuration/components/Summary.tsx)\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\n# 数据建模与集合管理\n\n## 概述\n\nNocoBase 的数据建模与集合管理模块是整个平台的核心基础设施，负责定义数据结构、管理数据关系、提供数据访问接口。该模块采用面向集合（Collection）的数据建模范式，支持多数据源管理，并提供了完整的 CRUD 操作能力。\n\n数据建模系统的主要职责包括：\n\n- **集合定义**：定义数据集合的结构、字段和约束\n- **字段管理**：支持多种字段类型和数据验证规则\n- **数据访问**：通过 Repository 模式提供统一的数据操作接口\n- **多数据源**：支持连接不同类型的数据源（主数据库、远程服务等）\n- **Schema 管理**：将数据模型与前端 Schema 绑定，实现 UI 联动\n\n资料来源：[packages/core/database/src/collection.ts]()\n\n## 核心概念\n\n### 集合（Collection）\n\n集合是 NocoBase 中数据组织的基本单元，类似于传统数据库中的表概念。每个集合包含以下关键属性：\n\n| 属性 | 说明 | 类型 |\n|------|------|------|\n| name | 集合名称，唯一标识 | string |\n| fields | 字段定义数组 | Field[] |\n| title | 显示名称 | string |\n| description | 描述信息 | string |\n| filterTargetKey | 过滤目标键 | string |\n| treeCollection | 是否为树形结构 | boolean |\n\n集合通过 Database 实例进行注册和管理，支持热插拔式的数据模型变更。\n\n### 字段（Field）\n\n字段是集合中的数据列定义，支持多种数据类型：\n\n- **普通字段**：字符串、数字、布尔值、日期等\n- **关系字段**：belongsTo、hasOne、hasMany、belongsToMany\n- **特殊字段**：json、radio、checkbox、sequence 等\n\n资料来源：[packages/core/database/src/field.ts]()\n\n## 架构设计\n\n```mermaid\ngraph TD\n A[数据建模层] --> B[CollectionManager]\n A --> C[数据源管理器]\n B --> D[Collection 集合]\n D --> E[Field 字段]\n D --> F[Repository 数据访问]\n C --> G[主数据源]\n C --> H[远程数据源]\n G --> I[MySQL/PostgreSQL/SQLite]\n H --> J[外部 API]\n```\n\n### 层次结构\n\nNocoBase 数据建模系统分为三个主要层次：\n\n1. **Schema 层**：定义数据结构的元信息\n2. **Collection 层**：将 Schema 实例化为可操作的集合\n3. **Repository 层**：提供数据访问的抽象接口\n\n```mermaid\nclassDiagram\n class Collection {\n +name: string\n +fields: Field[]\n +repository: Repository\n +create(data)\n +update(id, data)\n +delete(id)\n +find(params)\n }\n \n class Field {\n +name: string\n +type: string\n +options: object\n +validate(data)\n }\n \n class Repository {\n +create(data)\n +find(params)\n +update(id, data)\n +destroy(id)\n +count(params)\n }\n \n class Database {\n +registerCollections()\n +getCollection(name)\n }\n \n Collection \"1\" --> \"*\" Field : contains\n Collection --> Repository\n Database --> Collection : manages\n```\n\n资料来源：[packages/core/database/src/collection.ts:1-100]()\n\n## 集合管理\n\n### CollectionManager\n\nCollectionManager 是集合管理的核心类，负责维护所有已注册的集合实例：\n\n```typescript\n// 伪代码示例\nclass CollectionManager {\n collections: Map;\n \n getCollection(name: string): Collection;\n registerCollection(collection: Collection): void;\n removeCollection(name: string): void;\n getCollections(options?: FilterOptions): Collection[];\n}\n```\n\n### 集合注册流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户/开发者\n participant DB as Database\n participant CM as CollectionManager\n participant Col as Collection\n \n User->>DB: registerCollection(config)\n DB->>CM: addCollection(name, config)\n CM->>Col: new Collection(config)\n Col->>Col: parse fields\n Col->>Col: create repository\n CM->>DB: collection registered\n DB-->>User: success\n```\n\n资料来源：[packages/core/database/src/collection.ts]()\n\n### 集合配置组件\n\n在前端，集合配置通过 Summary 组件展示：\n\n```tsx\nconst Summary: React.FC = ({ label, schema }) => {\n // 展示集合配置的摘要信息\n return (\n
\n
\n {label}: {compile(schema.title)}\n
\n {schema.description &&
{compile(schema.description)}
}\n
\n );\n};\n```\n\n该组件负责渲染集合的名称和描述信息，支持国际化配置。\n\n资料来源：[packages/core/client/src/collection-manager/Configuration/components/Summary.tsx]()\n\n## 字段系统\n\n### 字段类型\n\nNocoBase 支持丰富的字段类型，定义在 field.ts 中：\n\n| 类型 | 说明 | 适用场景 |\n|------|------|----------|\n| string | 字符串 | 文本输入 |\n| integer | 整数 | 数量、ID |\n| bigInt | 大整数 | 雪花ID |\n| float/double | 浮点数 | 金额 |\n| boolean | 布尔值 | 开关状态 |\n| date/datetime | 日期/时间 | 时间记录 |\n| json | JSON 对象 | 复杂数据结构 |\n| belongsTo | 一对一关联 | 用户-角色 |\n| hasMany | 一对多关联 | 帖子-评论 |\n| belongsToMany | 多对多关联 | 用户-权限 |\n\n### 字段定义\n\n```typescript\ninterface FieldOptions {\n type: string;\n name: string;\n title?: string;\n description?: string;\n defaultValue?: any;\n uiSchema?: object;\n validation?: ValidationRule[];\n unique?: boolean;\n allowNull?: boolean;\n primaryKey?: boolean;\n}\n```\n\n字段支持级联配置，包括验证规则、默认值、UI 组件绑定等。\n\n资料来源：[packages/core/database/src/field.ts]()\n\n## Repository 数据访问层\n\n### Repository 模式\n\nRepository 提供统一的数据访问接口，封装了底层数据库操作：\n\n```typescript\ninterface IRepository {\n // 创建\n create(data: object, options?: CreateOptions): Promise;\n createMany(data: object[], options?: CreateOptions): Promise;\n \n // 查询\n find(params: FindParams): Promise;\n findOne(params: FindParams): Promise;\n findById(id: any): Promise;\n count(params?: FilterParams): Promise;\n \n // 更新\n update(params: UpdateParams): Promise;\n updateById(id: any, data: object): Promise;\n \n // 删除\n destroy(params: FilterParams): Promise;\n destroyById(id: any): Promise;\n \n // 关联操作\n add(field: string, id: any, relatedIds: any[]): Promise;\n set(field: string, id: any, relatedIds: any[]): Promise;\n remove(field: string, id: any, relatedIds: any[]): Promise;\n}\n```\n\n### 查询构建器\n\nRepository 内置强大的查询构建能力：\n\n```typescript\n// 基础查询\nrepository.find({\n filter: { status: 'active' },\n fields: ['id', 'name'],\n sort: ['createdAt'],\n page: 1,\n pageSize: 20\n});\n\n// 关联查询\nrepository.find({\n filter: { 'profile.nickname.$contains': 'admin' },\n appends: ['profile']\n});\n```\n\n资料来源：[packages/core/database/src/repository.ts]()\n\n## 数据源管理\n\n### 数据源管理器插件\n\nplugin-data-source-manager 负责管理多数据源连接：\n\n```mermaid\ngraph LR\n A[应用层] --> B[数据源管理器]\n B --> C[主数据源
Main Database]\n B --> D[远程数据源
Remote Data Source]\n B --> E[第三方服务]\n \n C --> F[MySQL/PostgreSQL]\n D --> G[REST API]\n D --> H[GraphQL]\n```\n\n### 数据源配置\n\n| 配置项 | 说明 | 示例 |\n|--------|------|------|\n| name | 数据源名称 | 'main' |\n| type | 数据源类型 | 'mysql' |\n| host | 主机地址 | 'localhost' |\n| port | 端口号 | 3306 |\n| database | 数据库名 | 'nocobase' |\n| username | 用户名 | 'root' |\n\n### 数据源隔离\n\nNocoBase 支持逻辑隔离的数据源架构，每个数据源可以：\n\n- 拥有独立的连接池\n- 使用不同的数据库引擎\n- 配置独立的迁移策略\n- 实现独立的缓存策略\n\n## Schema 集成\n\n### Schema 与集合绑定\n\n数据模型通过 Schema 与前端组件绑定：\n\n```typescript\nconst schema = {\n type: 'object',\n 'x-collection': 'users',\n properties: {\n name: {\n type: 'string',\n 'x-field': 'name'\n },\n email: {\n type: 'string',\n 'x-field': 'email'\n }\n }\n};\n```\n\n### Schema 初始化器\n\nSchema 初始化器提供了动态插入 Schema 的能力：\n\n```typescript\n// 插入 Schema 配置\nconst initializerConfig = {\n title: 'Form Item',\n type: 'object',\n 'x-component': 'FormItem',\n properties: {\n field1: {\n type: 'string',\n 'x-component': 'Input'\n }\n }\n};\n```\n\n支持动态显示/隐藏、动态加载子节点等高级功能。\n\n资料来源：[packages/core/client/src/schema-initializer/index.md]()\n\n## 内置变量与上下文\n\n### 变量系统\n\n数据模型支持在运行时使用内置变量：\n\n```typescript\nconst builtinVariables = [\n { name: '$nDate', ctx: datetimeCtx },\n { name: '$nExactDate', ctx: exactDateTimeCtx },\n { name: '$nRole', ctx: currentRoleCtx },\n { name: '$nUser', ctx: currentUserCtx },\n { name: '$nUrlSearchParams', ctx: urlSearchParamsCtx }\n];\n```\n\n### 上下文变量\n\n| 变量名 | 说明 | 返回值 |\n|--------|------|--------|\n| $nDate | 当前日期时间 | ISO 8601 格式 |\n| $nExactDate | 精确时间戳 | 带毫秒 |\n| $nRole | 当前用户角色 | 角色对象 |\n| $nUser | 当前用户信息 | 用户对象 |\n| $nUrlSearchParams | URL 参数 | 参数对象 |\n\n资料来源：[packages/core/client/src/variables/hooks/useBuiltinVariables.ts]()\n\n## 工作流程\n\n### 数据操作完整流程\n\n```mermaid\ngraph TD\n A[前端请求] --> B[Schema 验证]\n B --> C{请求类型}\n C -->|Create| D[数据验证]\n C -->|Read| E[查询构建]\n C -->|Update| F[变更检测]\n C -->|Delete| G[软删除检查]\n \n D --> H[事务开始]\n E --> I[Repository.find]\n F --> H\n G --> H\n \n H --> J[数据库操作]\n J --> K[事务提交]\n K --> L[返回结果]\n \n I --> L\n```\n\n### 集合管理器初始化流程\n\n```mermaid\nsequenceDiagram\n participant App as 应用启动\n participant DB as Database\n participant CM as CollectionManager\n participant Plugin as 插件加载\n \n App->>DB: initialize()\n DB->>CM: 创建实例\n CM->>Plugin: 加载数据源插件\n Plugin->>CM: registerCollection()\n CM->>CM: 创建 Collection 实例\n CM->>CM: 解析字段定义\n CM->>CM: 创建 Repository\n Plugin-->>DB: 注册完成\n DB-->>App: 数据库就绪\n```\n\n## 最佳实践\n\n### 集合命名规范\n\n- 使用小写字母和下划线：`user_profiles`\n- 避免使用保留字：`order`, `user`, `group`\n- 使用单数名词：`user` 而非 `users`\n- 有意义的名称：`order_items` 而非 `oi`\n\n### 字段设计建议\n\n1. **主键设计**：每个集合应定义主键字段\n2. **时间戳**：建议包含 `createdAt` 和 `updatedAt` 字段\n3. **软删除**：使用 `deletedAt` 而非物理删除\n4. **索引**：频繁查询字段添加索引配置\n\n### 关系设计原则\n\n```typescript\n// 一对多关系示例\nconst postCollection = {\n name: 'posts',\n fields: [\n { type: 'string', name: 'title' },\n { \n type: 'hasMany', \n name: 'comments',\n foreignKey: 'postId'\n }\n ]\n};\n\n// 评论表定义\nconst commentCollection = {\n name: 'comments',\n fields: [\n { type: 'string', name: 'content' },\n { type: 'integer', name: 'postId' },\n { \n type: 'belongsTo', \n name: 'post',\n foreignKey: 'postId'\n }\n ]\n};\n```\n\n## 总结\n\nNocoBase 的数据建模与集合管理系统提供了完整的数据建模解决方案：\n\n1. **灵活的集合定义**：支持多种字段类型和复杂的数据结构\n2. **强大的数据访问**：通过 Repository 模式提供统一的 CRUD 接口\n3. **多数据源支持**：可连接多种类型的数据库和外部服务\n4. **Schema 驱动**：与前端组件无缝集成，实现数据与 UI 联动\n5. **变量系统**：运行时支持丰富的上下文变量\n\n该系统设计遵循低耦合、高内聚的原则，便于扩展和维护，是 NocoBase 作为无代码平台的核心支撑模块。\n\n---\n\n\n\n## 外部数据源与多数据库支持\n\n### 相关页面\n\n相关主题：[数据建模与集合管理](#data-modeling), [系统架构与设计模式](#system-architecture)\n\n# 外部数据源与多数据库支持\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/plugins/@nocobase/plugin-data-source-external-mysql](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-data-source-external-mysql)\n- [packages/plugins/@nocobase/plugin-data-source-external-postgres](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-data-source-external-postgres)\n- [packages/plugins/@nocobase/plugin-data-source-external-mariadb](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-data-source-external-mariadb)\n- [packages/plugins/@nocobase/plugin-collection-fdw](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-collection-fdw)\n
\n\n> **说明**：当前检索到的上下文信息中，未包含上述外部数据源插件的详细源码实现内容。以下内容基于 NocoBase 核心代码库中与多数据源相关的公开信息进行整理。\n\n---\n\n## 概述\n\nNocoBase 采用**数据模型驱动**的架构设计，而非传统的表单或表格驱动方式。这种设计模式将数据结构与用户界面完全解耦，使得系统能够同时支持主数据库、外部数据库以及第三方 API 作为数据来源。\n\n资料来源：[README.md](https://github.com/nocobase/nocobase/blob/main/README.md)\n\n## 核心特性\n\n### 数据源类型支持\n\nNocoBase 的多数据库支持涵盖以下数据源类型：\n\n| 数据源类型 | 说明 | 支持状态 |\n|-----------|------|---------|\n| 主数据库 | 系统内置的主数据存储 | 完整支持 |\n| MySQL | 外部 MySQL 数据库连接 | 插件支持 |\n| PostgreSQL | 外部 PostgreSQL 数据库连接 | 插件支持 |\n| MariaDB | 外部 MariaDB 数据库连接 | 插件支持 |\n| 第三方 API | REST API 作为数据来源 | 插件支持 |\n\n### 数据库标识符引用规则\n\n不同数据库引擎对 SQL 标识符（如表名、字段名）的引用规则存在差异。NocoBase 在生成 SQL 语句时会根据数据源类型自动应用正确的引用规则。\n\n```ts\n/**\n * 标识符引用规则根据数据源类型确定\n * - MySQL 使用反引号 (`)\n * - PostgreSQL 使用双引号 (\")\n * - SQLite 使用双引号 (\")\n */\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/ai-employees/prompts.ts](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai/src/server/ai-employees/prompts.ts)\n\n### 环境配置参数\n\nAI 代理在处理数据库操作时会参考以下环境配置：\n\n- **main_database**: 主数据库引擎类型，影响 SQL 语法和标识符引用方式\n- **locale**: 通信语言和地区格式化设置\n- **quotingRules**: 不同数据源的 SQL 标识符引用规则\n\n## 插件体系架构\n\n外部数据源功能通过独立的插件实现，便于按需加载和维护：\n\n```mermaid\ngraph TD\n A[NocoBase 核心] --> B[plugin-data-source-external-mysql]\n A --> C[plugin-data-source-external-postgres]\n A --> D[plugin-data-source-external-mariadb]\n A --> E[plugin-collection-fdw]\n \n B --> F[MySQL 连接器]\n C --> G[PostgreSQL 连接器]\n D --> H[MariaDB 连接器]\n E --> I[联邦集合支持]\n```\n\n### 插件列表\n\n| 插件名称 | 功能描述 | 数据源类型 |\n|---------|---------|-----------|\n| plugin-data-source-external-mysql | MySQL 外部数据源连接 | MySQL |\n| plugin-data-source-external-postgres | PostgreSQL 外部数据源连接 | PostgreSQL |\n| plugin-data-source-external-mariadb | MariaDB 外部数据源连接 | MariaDB |\n| plugin-collection-fdw | 外部数据封装器支持 | 多类型 |\n\n## 数据源管理界面\n\nNocoBase 提供了插件详情管理界面，支持查看和管理已安装数据源插件：\n\n### 插件信息展示\n\n在插件详情页面中，可查看以下关键信息：\n\n| 字段 | 说明 |\n|-----|------|\n| PackageName | 插件包名称 |\n| Version | 当前版本号 |\n| Description | 插件描述 |\n| Author | 作者信息 |\n| License | 开源许可证 |\n| Homepage | 项目主页 |\n| Repository | 代码仓库地址 |\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### 依赖兼容性检查\n\n插件管理界面包含依赖兼容性验证功能：\n\n- 验证 `dist/externalVersion.js` 文件是否存在\n- 检查插件依赖版本是否满足要求\n- 在依赖不兼容时显示警告信息\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\n### 统一数据管理\n\n通过外部数据源功能，用户可以在 NocoBase 平台上：\n\n1. **连接现有数据库** - 无需迁移数据，直接连接已有的 MySQL、PostgreSQL 或 MariaDB 数据库\n2. **跨库查询** - 在单一界面中操作来自不同数据库的数据\n3. **API 集成** - 将第三方 REST API 作为数据来源使用\n\n### 数据结构与界面分离\n\nNocoBase 的核心优势在于：\n\n- UI 和数据结构完全解耦\n- 可以为同一张表或记录创建任意数量和形式的区块和操作\n- 支持在同一系统中混合使用多种数据源\n\n## 相关文档\n\n- [官方文档](https://docs.nocobase.com/)\n- [在线演示](https://demo.nocobase.com/new)\n- [用户案例](https://www.nocobase.com/en/blog/tags/customer-stories)\n\n---\n\n> **注意**：如需获取特定数据源插件的详细技术实现，建议查阅各插件目录下的源代码文件，或参考官方技术文档。\n\n---\n\n\n\n## 权限系统与 ACL\n\n### 相关页面\n\n相关主题：[数据建模与集合管理](#data-modeling)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/client/src/application/hooks/useAclSnippets.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/application/hooks/useAclSnippets.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/core/client/src/pm/PluginDetail.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginDetail.tsx)\n- [packages/plugins/@nocobase/plugin-acl](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-acl)\n- [packages/core/server/src/acl/acl.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/server/src/acl/acl.ts)\n- [packages/core/server/src/acl/role.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/server/src/acl/role.ts)\n
\n\n# 权限系统与 ACL\n\n## 概述\n\nNocoBase 的权限系统基于 **ACL（Access Control List，访问控制列表）** 机制实现。该系统采用角色（Role）和资源（Resource）两层的权限管理模式，支持细粒度的操作级别控制。权限系统贯穿整个应用，从服务端到客户端均有完整的权限校验链路，确保数据安全和操作合规。\n\n## 核心概念\n\n| 概念 | 说明 |\n|------|------|\n| **角色（Role）** | 一组权限的集合，用户通过关联角色获得相应权限 |\n| **资源（Resource）** | 需要被保护的实体，如数据表、字段、插件等 |\n| **操作（Action）** | 对资源的具体操作，如 view、create、update、delete |\n| **Snippet** | 权限片段，用于灵活组合和管理权限规则 |\n\n资料来源：[packages/core/server/src/acl/role.ts:1-20]()\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[用户请求] --> B[ACL 中间件]\n B --> C{权限校验}\n C -->|通过| D[业务逻辑处理]\n C -->|拒绝| E[返回 403 错误]\n D --> F[数据响应]\n \n G[角色管理] --> H[角色权限配置]\n H --> I[Snippet 定义]\n I --> C\n```\n\n### 服务端架构\n\n服务端 ACL 模块位于 `packages/core/server/src/acl/` 目录，包含以下核心组件：\n\n- **ACL 类**：权限系统的核心管理器，负责加载权限规则、执行权限校验\n- **Role 类**：角色实体，封装角色的权限配置信息\n- **中间件**：拦截请求并进行权限验证\n\n```mermaid\ngraph LR\n A[Request] --> B[ACL Middleware]\n B --> C[ACL Manager]\n C --> D[Role Manager]\n D --> E[Snippet Matcher]\n E --> F{Permission Check}\n F -->|Match| G[Allow]\n F -->|No Match| H[Deny]\n```\n\n资料来源：[packages/core/server/src/acl/acl.ts:1-30]()\n\n### 客户端架构\n\n客户端通过 React Context 提供 ACL 上下文，使用 Hook 方式暴露权限判断能力：\n\n```tsx\n// ACL Provider 提供全局上下文\n\n \n\n\n// 子组件中使用权限 Hook\nconst { allow, snippets } = useACLRoleContext();\n```\n\n资料来源：[packages/core/client/src/application/hooks/useAclSnippets.ts:10-20]()\n\n## 角色与权限\n\n### 角色定义\n\n角色是权限管理的基本单位，每个角色包含以下属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| name | string | 角色标识名称 |\n| title | string | 角色显示名称 |\n| snippets | string[] | 权限片段列表 |\n| allowAll | boolean | 是否允许所有操作 |\n\n资料来源：[packages/core/server/src/acl/role.ts:20-40]()\n\n### 预定义内置变量\n\nNocoBase 在权限上下文中注入了多个内置变量，用于权限判断和动态规则：\n\n| 变量名 | 说明 | 用途 |\n|--------|------|------|\n| `$nRole` | 当前角色 | 获取当前用户的角色信息 |\n| `$nUser` | 当前用户 | 获取当前登录用户信息 |\n| `$nDate` | 当前日期 | 日期相关的权限条件 |\n| `$nExactDate` | 精确当前时间 | 时间戳相关的权限条件 |\n| `$nenv` | 环境变量 | 服务器环境变量访问 |\n\n资料来源：[packages/core/client/src/variables/hooks/useBuiltinVariables.ts:20-50]()\n\n### Snippet 匹配机制\n\n系统使用 `ignore` 库实现 Snippet 的模式匹配，支持通配符和否定前缀：\n\n```typescript\nconst ig = ignore().add(snippets);\nconst appAllowed = allowAll || ig.ignores(aclSnippet);\n```\n\n匹配规则：\n- `allowAll` 为 `true` 时，跳过 Snippet 校验，直接放行\n- 使用 `ignore` 库的标准 glob 匹配规则\n- 支持 `!` 前缀表示显式拒绝\n\n资料来源：[packages/core/client/src/application/hooks/useAclSnippets.ts:12-18]()\n\n## 权限配置\n\n### Schema 中的权限声明\n\n在数据 Schema 中通过 `x-acl-action` 字段声明权限要求：\n\n```typescript\nconst schema: ISchema = {\n type: 'void',\n 'x-acl-action': 'collections:view', // 声明需要的权限\n 'x-decorator': 'DetailsBlockProvider',\n 'x-component': 'CardItem',\n};\n```\n\n资料来源：[packages/core/client/src/schema-initializer/utils.ts:15-25]()\n\n### 权限操作类型\n\n| 操作 | 说明 | 适用资源 |\n|------|------|----------|\n| `view` | 查看资源 | 表单、详情、列表 |\n| `create` | 创建新资源 | 表单、列表 |\n| `update` | 修改现有资源 | 表单、详情 |\n| `delete` | 删除资源 | 列表、操作按钮 |\n| `get` | 获取单个资源 | 详情块 |\n\n资料来源：[packages/core/client/src/schema-initializer/utils.ts:22-30]()\n\n## 插件系统集成\n\n### 插件兼容性检查\n\nNocoBase 的插件管理界面集成了 ACL 权限校验，插件详情页提供依赖兼容性检查功能：\n\n```tsx\n{\n key: 'dependencies',\n label: t('Dependencies compatibility check'),\n children: (\n <>\n \n \n ),\n}\n```\n\n资料来源：[packages/core/client/src/pm/PluginDetail.tsx:80-100]()\n\n### 插件权限声明\n\n插件可通过配置文件声明所需的权限：\n\n```json\n{\n \"name\": \"@nocobase/plugin-sample\",\n \"permissions\": [\n \"collections:view\",\n \"collections:create\",\n \"!system:admin\"\n ]\n}\n```\n\n## 工作流程\n\n### 权限校验流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Middleware as ACL 中间件\n participant ACL as ACL 管理器\n participant Role as 角色管理器\n participant Resource as 资源\n\n Client->>Middleware: 请求资源\n Middleware->>ACL: 发起权限校验\n ACL->>Role: 获取用户角色\n Role-->>ACL: 返回角色配置\n ACL->>ACL: 匹配 Snippet\n ACL-->>Middleware: 校验结果\n Middleware->>Resource: 允许/拒绝访问\n```\n\n### 客户端权限 Hook 使用\n\n```typescript\nimport { useAclSnippets } from '@nocobase/client';\n\nfunction MyComponent() {\n const { allow } = useAclSnippets();\n \n // 检查特定权限\n if (!allow('collections:view')) {\n return ;\n }\n \n return ;\n}\n```\n\n资料来源：[packages/core/client/src/application/hooks/useAclSnippets.ts:1-25]()\n\n## 最佳实践\n\n### 1. 合理设计角色\n\n建议采用最小权限原则，按业务职能划分角色：\n\n| 角色 | 权限范围 | 适用场景 |\n|------|----------|---------- |\n| admin | 所有权限 | 系统管理员 |\n| operator | 业务操作权限 | 普通业务人员 |\n| viewer | 仅查看权限 | 数据查看者 |\n\n### 2. 使用 Snippet 组合\n\n将常用权限组合定义为 Snippet，便于复用：\n\n```typescript\n// 定义 Snippet\nsnippets: [\n 'collections:view',\n 'collections:create',\n 'collections:update',\n]\n\n// 使用通配符\nsnippets: [\n 'collections:*', // 所有集合操作\n '!collections:delete' // 排除删除\n]\n```\n\n### 3. Schema 权限声明\n\n在开发插件或自定义页面时，应明确声明所需的权限：\n\n```typescript\nconst schema = {\n type: 'void',\n 'x-acl-action': `${collectionName}:view`,\n 'x-settings': 'settings:acl',\n};\n```\n\n## 相关配置\n\n### 环境变量\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `ACL_ENABLED` | 是否启用 ACL | `true` |\n| `ACL_DEFAULT_ROLE` | 默认角色 | `guest` |\n\n### 插件依赖\n\n权限系统作为核心插件 `@nocobase/plugin-acl` 提供，独立于业务插件存在：\n\n```\n@nocobase/plugin-acl\n├── server/src/acl/ # 服务端实现\n├── client/src/acl/ # 客户端实现\n└── index.ts # 插件入口\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-acl](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-acl)\n\n## 总结\n\nNocoBase 的权限系统采用成熟的 ACL 模型，通过角色、权限片段和资源操作的三层结构实现了灵活且强大的访问控制。系统支持服务端的中间件校验和客户端的上下文感知，两端协同确保权限策略的一致性和安全性。开发者应遵循最小权限原则，合理设计角色和 Snippet，在 Schema 中明确声明权限需求，以构建安全可靠的应用系统。\n\n---\n\n\n\n## 工作流引擎\n\n### 相关页面\n\n相关主题：[AI 集成与智能员工](#ai-integration), [界面构建器](#interface-builder)\n\n
\n相关源码文件\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- [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/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- [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
\n\n# 工作流引擎\n\n## 概述\n\nNocoBase 工作流引擎是一个强大的业务流程自动化模块，允许用户通过可视化画布设计、配置和管理自动化工作流程。工作流引擎支持在数据保存前后触发、执行队列任务、审批流程以及自定义操作事件，为业务系统提供灵活的自动化能力。\n\n工作流引擎的核心职责包括：\n\n- 提供可视化的流程设计画布\n- 管理流程节点的执行逻辑\n- 处理流程执行状态和历史记录\n- 支持条件分支和循环控制\n- 与系统各模块集成实现自动化触发\n\n资料来源：[packages/core/flow-engine/src/flowSettings.ts:1-50]()\n\n## 架构设计\n\n### 核心组件\n\n工作流引擎由多个核心组件构成，各组件协同完成流程设计、执行和监控功能。\n\n```mermaid\ngraph TD\n A[FlowSettings 配置面板] --> B[FlowModel 模型层]\n B --> C[FlowModelRenderer 渲染器]\n C --> D[CanvasContent 画布内容]\n D --> E[ExecutionCanvas 执行画布]\n \n F[FlowContext 上下文] --> B\n G[节点组件] --> D\n H[任务队列] --> E\n```\n\n### 目录结构\n\n工作流引擎主要代码分布在以下位置：\n\n| 层级 | 路径 | 说明 |\n|------|------|------|\n| 核心引擎 | `packages/core/flow-engine/` | 流程引擎核心逻辑和组件 |\n| 工作流插件 | `packages/plugins/@nocobase/plugin-workflow/` | 工作流可视化设计和执行 |\n| 审批插件 | `packages/plugins/@nocobase/plugin-workflow-approval/` | 审批流程支持 |\n| 请求插件 | `packages/plugins/@nocobase/plugin-workflow-request/` | HTTP 请求节点支持 |\n\n资料来源：[packages/core/flow-engine/src/components/FlowModelRenderer.tsx:1-30]()\n\n## FlowSettings 配置系统\n\n`FlowSettings` 是工作流引擎的配置管理核心类，负责注册和管理流程相关的 UI 组件和作用域。\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### 配置属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `components` | `Record` | 注册的流程组件集合 |\n| `scopes` | `Record` | 流程作用域配置 |\n| `antdComponentsLoaded` | `boolean` | Antd 组件加载状态 |\n| `enabled` | `boolean` | 流程启用状态 |\n| `#forceEnabled` | `boolean` | 强制启用覆盖状态 |\n\n### 底部栏配置\n\nFlowSettings 支持通过 `footer` 属性自定义底部操作栏的展示形式：\n\n```typescript\n// 1. 静态自定义 - 直接替换\nfooter:
自定义底部内容
\n\n// 2. 包裹式自定义 - 在原节点基础上添加内容\nfooter: (originNode, { OkBtn, CancelBtn }) => (\n
\n Additional info\n {originNode}\n
\n)\n\n// 3. 函数式自定义 - 完全重新组合按钮\nfooter: (originNode, { OkBtn, CancelBtn }) => (\n \n \n \n \n \n)\n\n// 4. 隐藏底部\nfooter: null\n```\n\n资料来源：[packages/core/flow-engine/src/flowSettings.ts:1-80]()\n\n## 流程渲染器\n\n### FlowModelRenderer\n\n`FlowModelRenderer` 是核心的流程模型渲染组件，负责将流程模型渲染为可视化的流程配置界面。\n\n```typescript\nexport const FlowModelRenderer: React.FC = React.memo((props) => {\n // 构建渲染内容：统一在渲染前触发 beforeRender 事件（带缓存）\n const content = (\n \n );\n\n // 当需要错误回退时，将整体包裹在 ErrorBoundary 和 FlowModelProvider 中\n if (showErrorFallback) {\n return (\n \n {content}\n \n );\n }\n\n return content;\n});\n```\n\n### MemoFlowModelRenderer\n\n对于需要优化渲染性能的场景，引擎提供了 `MemoFlowModelRenderer` 包装版本，仅在父级重渲且 props 浅比较未变时跳过渲染，不影响内部响应式更新。\n\n```typescript\nexport const MemoFlowModelRenderer = React.memo(FlowModelRenderer);\nMemoFlowModelRenderer.displayName = 'MemoFlowModelRenderer';\n```\n\n### Props 配置\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `model` | `Model` | 流程数据模型 |\n| `showFlowSettings` | `boolean` | 是否显示流程设置 |\n| `flowSettingsVariant` | `string` | 设置面板变体 |\n| `hideRemoveInSettings` | `boolean` | 在设置中隐藏删除按钮 |\n| `showTitle` | `boolean` | 是否显示标题 |\n| `inputArgs` | `any[]` | 输入参数列表 |\n| `showErrorFallback` | `boolean` | 是否显示错误回退 |\n| `settingsMenuLevel` | `'first' \\| 'second'` | 设置菜单层级 |\n| `extraToolbarItems` | `ReactNode` | 额外工具栏项 |\n| `fallback` | `ComponentType` | 自定义回退组件 |\n| `useCache` | `boolean` | 是否启用缓存 |\n\n资料来源：[packages/core/flow-engine/src/components/FlowModelRenderer.tsx:1-100]()\n\n## 执行上下文\n\n### FlowContext\n\n`FlowContext` 提供流程执行时的运行时上下文，贯穿整个流程执行生命周期。\n\n```typescript\n\n {children}\n\n```\n\n### 上下文属性\n\n| 属性 | 说明 |\n|------|------|\n| `workflow` | 当前执行的流程对象 |\n| `nodes` | 流程节点配置列表 |\n| `execution` | 执行实例信息 |\n| `viewJob` | 当前查看的任务节点 |\n| `setViewJob` | 设置查看任务的方法 |\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx:1-60]()\n\n## 可视化画布\n\n### CanvasContent\n\n画布内容组件负责渲染流程节点的可视化展示和交互。\n\n```typescript\n
\n \n
\n
\n
{lang('Start')}
\n {renderNodes(entry, nodes)}\n
{lang('End')}
\n
\n
\n \n {copiedNode ? (\n
\n
\n {lang('Copied node')}\n
\n
\n
{copiedTypeTitle}
\n
{copiedNode.title ?? copiedNode.type}
\n
\n
\n ) : null}\n
\n \n
\n
\n```\n\n### 画布功能\n\n| 功能 | 说明 |\n|------|------|\n| 节点渲染 | 渲染流程中的所有节点和连接线 |\n| 剪贴板预览 | 显示复制的节点信息 |\n| 缩放控制 | 支持 10%-100% 的画布缩放 |\n| 错误边界 | 捕获节点渲染中的错误 |\n\n### ExecutionCanvas 执行画布\n\n执行画布展示流程的实际执行状态和结果。\n\n```typescript\n{lang('Workflow')} },\n { title: {workflow.title} },\n { title: },\n ]}\n/>\n{compile(statusOption.label)}\n\n```\n\n### 执行状态展示\n\n| 元素 | 说明 |\n|------|------|\n| 面包屑导航 | 显示从流程列表到具体执行的路径 |\n| 状态标签 | 以颜色区分执行状态 |\n| 时间戳 | 显示最后更新时间 |\n| 取消按钮 | 可取消未完成的执行 |\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/client/CanvasContent.tsx:1-80]()\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx:1-70]()\n\n## 触发机制\n\n工作流支持多种触发方式，满足不同业务场景的自动化需求。\n\n```mermaid\ngraph LR\n A[数据保存] --> B[触发前 Pre-Action]\n A --> C[触发后 Post-Action]\n D[按钮点击] --> E[自定义事件]\n F[定时任务] --> G[队列执行]\n```\n\n### 触发类型\n\n| 触发类型 | 说明 | 支持模式 |\n|----------|------|----------|\n| 保存后触发 | 数据保存成功后自动执行 | 本地模式 |\n| 提交后触发 | 表单提交成功后执行 | 全模式 |\n| 删除前触发 | 数据删除前执行（仅本地模式） | 本地模式 |\n| 按钮点击 | 点击按钮直接触发 | 自定义事件 |\n| 后台队列 | 作为排队任务后台执行 | 全模式 |\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/locale/ko-KR.json:1-50]()\n\n## 国际化支持\n\n工作流引擎内置多语言支持，核心翻译键值如下：\n\n| 键值 | 中文 | 英文 |\n|------|------|------|\n| `Workflow` | 工作流 | 工作流 |\n| `Workflow tasks` | 工作流任务 | 工作流任务 |\n| `Workflow todos` | 工作流待办 | 工作流待办 |\n| `View result` | 查看结果 | 查看结果 |\n| `Workflow executed` | 工作流已执行 | 工作流已执行 |\n| `Execution status` | 执行状态 | 执行状态 |\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/locale/ko-KR.json:50-100]()\n\n## 相关插件\n\n### plugin-workflow\n\n基础工作流插件，提供核心的流程设计、执行和管理功能。\n\n- 可视化流程画布设计\n- 节点配置和管理\n- 执行历史记录\n- 流程复制和粘贴\n\n### plugin-workflow-approval\n\n审批流程插件，扩展工作流引擎支持审批业务场景。\n\n- 审批节点类型\n- 审批人指定\n- 审批意见记录\n\n### plugin-workflow-request\n\nHTTP 请求插件，支持在工作流中发起外部 API 调用。\n\n- HTTP 请求节点\n- 响应数据处理\n- 错误处理机制\n\n## 最佳实践\n\n### 性能优化\n\n1. **使用 MemoFlowModelRenderer**：在父组件频繁重渲但实际数据未变的场景，使用 Memo 版本避免不必要的重渲\n2. **合理设置 useCache**：启用缓存可减少重复计算，但需注意数据一致性问题\n3. **showErrorFallback 策略**：在复杂节点场景启用错误边界，避免单个节点错误导致整个流程崩溃\n\n### 错误处理\n\n1. **ErrorBoundary 包装**：确保节点渲染错误被正确捕获\n2. **FlowErrorFallback 自定义**：根据业务需求提供友好的错误展示\n3. **FlowModelProvider 上下文**：在错误回退中仍可获取模型上下文进行恢复操作\n\n## 总结\n\nNocoBase 工作流引擎采用模块化设计，通过 FlowSettings 配置系统、FlowModelRenderer 渲染器、CanvasContent 画布和 ExecutionCanvas 执行画布等核心组件，为业务系统提供了完整的流程自动化能力。引擎支持多种触发机制、可视化设计和执行监控，结合审批和请求等扩展插件，能够满足复杂业务场景的流程自动化需求。\n\n---\n\n\n\n## AI 集成与智能员工\n\n### 相关页面\n\n相关主题：[工作流引擎](#workflow-engine), [权限系统与 ACL](#acl-permissions)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/plugins/@nocobase/plugin-ai](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai) - 插件源码未在当前上下文提供\n- [packages/plugins/@nocobase/plugin-ai-knowledge-base](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai-knowledge-base) - 插件源码未在当前上下文提供\n- [docs/docs/cn/ai-employees/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/cn/ai-employees/index.md) - 文档源码未在当前上下文提供\n- [docs/docs/cn/ai-employees/knowledge-base/rag.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/cn/ai-employees/knowledge-base/rag.md) - 文档源码未在当前上下文提供\n
\n\n# AI 集成与智能员工\n\n## 概述\n\n根据当前检索到的上下文信息，未能获取到 AI 插件和智能员工相关的具体源码文件。以下信息基于 NocoBase 仓库中可访问的通用架构和功能模块进行说明。\n\n### 当前可访问的上下文信息\n\n从仓库中检索到的相关文件主要包括：\n\n| 文件路径 | 说明 |\n|---------|------|\n| `packages/core/client/src/user/Help.tsx` | 用户帮助菜单，集成外部文档链接 |\n| `packages/core/client/src/pm/PluginDetail.tsx` | 插件详情管理组件 |\n| `packages/core/client/src/variables/hooks/useBuiltinVariables.ts` | 内置变量系统（含日期、用户、URL参数等） |\n| `README.md` | 项目主文档，提及 AI Agent Access 功能 |\n| `packages/core/flow-engine/src/flowSettings.ts` | 流程引擎配置系统 |\n\n## AI 集成架构\n\n根据项目 README 中的描述，NocoBase 是一个开源的 AI + No-Code 平台，用于快速构建业务系统。AI 功能建立在经过生产验证的基础设施和所见即所得的 No-Code 界面上。\n\n> Coding agents get a... (文档内容在此处截断)\n\n## 变量系统与 AI 上下文\n\nNocoBase 的内置变量系统为 AI 集成提供了上下文数据支持：\n\n```typescript\n// 资料来源：packages/core/client/src/variables/hooks/useBuiltinVariables.ts:1-100\n\nconst builtinVariables = [\n {\n name: '$date',\n ctx: datetimeCtx, // 日期时间上下文\n },\n {\n name: '$nExactDate',\n ctx: exactDateTimeCtx, // 精确日期时间\n },\n {\n name: '$system',\n ctx: {\n now: () => dayjs().toISOString(),\n },\n },\n {\n name: 'currentTime',\n ctx: () => dayjs().toISOString(),\n },\n {\n name: urlSearchParamsName,\n ctx: urlSearchParamsCtx,\n defaultValue,\n },\n];\n```\n\n| 变量名称 | 用途 | 状态 |\n|---------|------|------|\n| `$date` | 当前日期时间 | 已弃用 |\n| `$nExactDate` | 精确日期时间 | 活跃 |\n| `$system` | 系统信息（含 now 方法） | 已弃用 |\n| `currentTime` | 当前时间戳 | 已弃用 |\n| URL 参数变量 | 动态 URL 参数 | 活跃 |\n\n## 文档资源链接\n\n根据 Help 组件配置，NocoBase 提供了以下官方文档资源：\n\n| 资源类型 | 简体中文链接 | 英文链接 |\n|---------|-------------|---------|\n| 官网首页 | https://www.nocobase.com/cn/ | https://www.nocobase.com |\n| 用户手册 | https://v2.docs.nocobase.com/cn/guide/ | https://v2.docs.nocobase.com/guide/ |\n\n> 资料来源：packages/core/client/src/user/Help.tsx:1-60\n\n## 流程引擎配置\n\nAI 智能员工的执行逻辑可能通过流程引擎实现。当前可访问的流程配置支持自定义底部按钮：\n\n```typescript\n// 资料来源：packages/core/flow-engine/src/flowSettings.ts:1-50\n\ninterface FlowSettingsConfig {\n footer?:\n | React.ReactNode\n | ((originNode: React.ReactNode, extra: { OkBtn: React.FC; CancelBtn: React.FC }) => React.ReactNode)\n | null;\n [key: string]: any;\n}\n```\n\n## 插件系统\n\nNocoBase 的插件管理器支持查看插件详情，包括依赖兼容性检查：\n\n> 资料来源：packages/core/client/src/pm/PluginDetail.tsx:1-100\n\n| 检查项 | 说明 |\n|-------|------|\n| 包名称 | 插件的唯一标识符 |\n| 版本号 | 当前安装的版本 |\n| 依赖兼容性 | 检查 `dist/externalVersion.js` 是否存在 |\n| 许可证 | 开源许可证类型 |\n\n## 注意事项\n\n**当前页面内容不完整**\n\n由于以下关键源码文件未在当前检索上下文中提供，无法生成详细的 AI 集成与智能员工技术文档：\n\n1. `packages/plugins/@nocobase/plugin-ai` - AI 核心插件\n2. `packages/plugins/@nocobase/plugin-ai-knowledge-base` - AI 知识库插件\n3. `docs/docs/cn/ai-employees/index.md` - AI 员工文档首页\n4. `docs/docs/cn/ai-employees/knowledge-base/rag.md` - RAG 检索增强生成文档\n\n## 后续步骤\n\n如需完整的技术文档，请提供以下任一方式：\n\n1. **重新检索** - 请求检索上述缺失的 AI 相关源码文件\n2. **访问源码** - 直接访问 GitHub 仓库中的 AI 插件目录\n3. **访问文档** - 查看官方文档站点 https://docs.nocobase.com/\n\n---\n\n*本页面基于 NocoBase 仓库 v1.0+ 版本编写，部分内容因源码文件不可用而标记为待补充。*\n\n---\n\n\n\n## 界面构建器\n\n### 相关页面\n\n相关主题：[数据建模与集合管理](#data-modeling), [工作流引擎](#workflow-engine)\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- [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/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- [packages/core/client/src/pm/PluginDetail.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginDetail.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/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/mobile-layout/index.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-mobile/src/client/mobile-layout/index.md)\n
\n\n# 界面构建器\n\n## 概述\n\n界面构建器（Interface Builder）是 NocoBase 平台的核心模块之一，用于通过可视化的方式构建业务系统的用户界面。它基于 Schema 驱动的架构设计，允许用户通过声明式配置定义界面结构、数据源、交互行为等，而无需编写大量代码。\n\n界面构建器的核心理念是通过数据驱动的方式实现 UI 的声明式构建，所有界面配置都以 JSON Schema 格式存储在数据库中，支持运行时动态修改和渲染。\n\n## 核心架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[用户界面] --> B[Schema 配置]\n B --> C[Schema 解析器]\n C --> D[组件映射表]\n D --> E[React 组件]\n E --> A\n \n F[Schema 设置面板] --> B\n G[Schema 初始化器] --> B\n H[Schema 工具栏] --> B\n \n I[数据源配置] --> J[变量系统]\n J --> C\n```\n\n### 主要模块\n\n| 模块 | 功能 | 源码位置 |\n|------|------|----------|\n| Schema Settings | 界面属性的配置面板 | `packages/core/client/src/schema-settings/` |\n| Schema Initializer | 向 Schema 中动态插入新节点 | `packages/core/client/src/schema-initializer/` |\n| Schema Component | Schema 渲染的核心组件库 | `packages/core/client/src/schema-component/` |\n| Schema Toolbar | 工具栏，提供设计态操作入口 | `packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx` |\n| LinkageFilter | 联动规则的条件配置组件 | `packages/core/client/src/schema-component/antd/linkageFilter/` |\n\n## Schema 配置结构\n\n### Schema 基本结构\n\nSchema 是界面构建器的核心配置单元，采用 JSON Schema 格式定义界面的层级结构和属性。\n\n```typescript\n{\n type: 'string',\n 'x-decorator': 'FormItem',\n 'x-component': 'Input',\n 'x-component-props': {\n placeholder: '{{t(\"Please enter\")}}',\n },\n 'x-designable-bahavior': 'editable'\n}\n```\n\n### x-designable-bahavior 行为类型\n\n| 行为类型 | 说明 | 源码引用 |\n|----------|------|----------|\n| `editable` | 可切换 designable 状态 | `schema-component/index.md` |\n| `readonly` | 只读状态，不可切换 | `schema-component/index.md` |\n| `none` | 完全禁用设计态 | `schema-component/index.md` |\n\n资料来源：[schema-component/index.md:8-11]()\n\n## Schema 初始化器\n\nSchema 初始化器负责在设计时动态向 Schema 中插入新的节点或配置，是实现可视化配置的关键组件。\n\n### 功能特性\n\n- **动态可见性**：根据条件动态显示或隐藏配置项\n- **子节点动态加载**：支持按需加载子配置节点\n- **Schema 插入**：支持多种类型的 Schema 插入模式\n\n### 插入模式\n\n| 模式 | 说明 | 示例位置 |\n|------|------|----------|\n| Basic | 基础插入模式 | `demos/insert-schema-basic.tsx` |\n| Action | 动作类插入 | `demos/insert-schema-action.tsx` |\n| FormItem | 表单项插入 | `demos/insert-schema-form-item.tsx` |\n\n资料来源：[schema-initializer/index.md:12-20]()\n\n## Schema 设置面板\n\nSchema 设置面板提供配置界面的入口，允许用户修改 Schema 节点的各种属性。\n\n### GeneralSchemaDesigner 组件\n\n`GeneralSchemaDesigner` 是核心的 Schema 设计器组件，提供了完整的可视化编辑能力。\n\n```typescript\ninterface SchemaToolbarProps {\n title?: string | string[];\n showDataSource?: boolean;\n dataSource?: any;\n template?: boolean;\n draggable?: boolean;\n disableInitializer?: boolean;\n}\n```\n\n资料来源：[GeneralSchemaDesigner.tsx:145-153]()\n\n### 工具栏功能\n\n| 功能 | 说明 | 交互方式 |\n|------|------|----------|\n| 拖拽手柄 | 支持 Schema 节点拖拽排序 | `DragHandler` 组件 |\n| 初始化器 | 插入新的 Schema 节点 | `InitializerComponent` |\n| 设置下拉菜单 | 访问节点属性配置 | `SchemaSettingsDropdown` |\n| 数据源显示 | 显示当前节点所属数据源 | 标题区域 |\n\n资料来源：[GeneralSchemaDesigner.tsx:40-75]()\n\n### 标题渲染逻辑\n\n```typescript\n// 数据源和标题组合显示\n{dataSource ? `${compile(dataSource?.displayName)} > ${compile(title)}` : compile(title)}\n```\n\n## 组件类型系统\n\n### 内置组件类型\n\nNocoBase 提供了多种内置组件类型，可直接在 Schema 中引用：\n\n| 类型 | 用途 | 源码 |\n|------|------|------|\n| FormItem | 表单项装饰器 | 内置 |\n| Input | 文本输入 | antd |\n| Select | 下拉选择 | antd |\n| Markdown | Markdown 编辑器 | 自定义 |\n\n### LinkageFilter 组件\n\n`LinkageFilter` 用于前端联动规则的条件配置，支持变量、操作符的联动变化。\n\n```typescript\ntype FilterActionProps = ActionProps & {\n options?: any[];\n form?: Form;\n onSubmit?: (values: T) => void;\n onReset?: (values: T) => void;\n}\n```\n\n资料来源：[linkageFilter/index.md:7-13]()\n\n## 变量系统\n\n### 内置变量\n\n界面构建器支持丰富的内置变量，用于在配置中引用运行时数据：\n\n| 变量名 | 说明 | 类型 |\n|--------|------|------|\n| `$nDate` | 当前日期时间 | ISO 8601 格式 |\n| `$nExactDate` | 精确时间戳 | ISO 8601 格式 |\n| `$date` | 日期（已废弃） | 兼容性支持 |\n| `$system` | 系统变量（已废弃） | 兼容性支持 |\n| `$urlSearchParams` | URL 查询参数 | 对象 |\n| `currentTime` | 当前时间（已废弃） | 兼容性支持 |\n\n资料来源：[useBuiltinVariables.ts:30-70]()\n\n### 变量上下文结构\n\n```typescript\n{\n name: '$nDate',\n ctx: () => dayjs().toISOString(),\n defaultValue?: any\n}\n```\n\n## 流程设置集成\n\n界面构建器与流程引擎深度集成，支持在配置面板中嵌入流程节点设置。\n\n### FlowSettings 配置结构\n\n```typescript\ninterface FlowSettingsProps {\n footer?: React.ReactNode | \n ((originNode: React.ReactNode, extra: { \n OkBtn: React.FC; \n CancelBtn: React.FC \n }) => React.ReactNode) | null;\n onCancel?: () => void | Promise;\n onSaved?: () => void | Promise;\n}\n```\n\n资料来源：[flowSettings.ts:40-52]()\n\n### 自定义 Footer 示例\n\n```tsx\n// 在底部工具栏添加内容\nfooter: (originNode, { OkBtn, CancelBtn }) => (\n
\n Additional info\n {originNode}\n
\n)\n\n// 隐藏底部\nfooter: null\n```\n\n## 移动端适配\n\n### 桌面模式组件\n\n当在桌面端访问移动端页面时，系统会渲染 `DesktopMode` 组件进行适配。\n\n```tsx\n\n \n\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-mobile/src/client/desktop-mode/index.md]()\n\n### 移动端 TabBar\n\n移动端使用自定义的 `MobileTabBar` 组件，支持链接跳转功能：\n\n| 功能 | 说明 |\n|------|------|\n| Inner Link | 内部页面跳转 |\n| Outer Page | 外部页面跳转 |\n| Selected | 选中状态管理 |\n\n资料来源：[mobile-layout/index.md]()\n\n## 设计态与运行态\n\n### 状态切换机制\n\n```mermaid\nstateDiagram-v2\n [*] --> Designable: 设计态开启\n Designable --> [*]: 保存配置\n Designable --> Readonly: 切换为只读\n Readonly --> Designable: 重新编辑\n Readonly --> [*]: 退出编辑\n```\n\n### Designable 上下文\n\n通过 `useDesignable()` Hook 可以获取当前设计态状态：\n\n```typescript\nconst { designable } = useDesignable();\n```\n\n## 配置示例\n\n### 基本 Schema 配置\n\n```typescript\n{\n type: 'object',\n properties: {\n name: {\n type: 'string',\n 'x-decorator': 'FormItem',\n 'x-component': 'Input',\n 'x-component-props': {\n placeholder: '{{t(\"Name\")}}',\n },\n },\n },\n}\n```\n\n### Markdown 编辑器配置\n\n```typescript\n{\n content: {\n type: 'string',\n 'x-decorator': 'FormItem',\n 'x-component': (props) => {\n return ctx.markdown.edit({\n ...props,\n value: props.value || ctx.model.props.value,\n mode: 'sv',\n height: '82vh',\n });\n },\n },\n}\n```\n\n资料来源：[packages/core/client/src/flow/flows/editMarkdownFlow.tsx]()\n\n## 最佳实践\n\n### 性能优化\n\n1. **减少不必要的渲染**：使用 `React.memo` 包装自定义组件\n2. **延迟加载**：对于复杂配置，使用动态导入\n3. **状态管理**：合理使用 Context 避免过度 prop drilling\n\n### 可维护性\n\n1. **Schema 分离**：将复杂的 Schema 拆分为多个子 Schema\n2. **组件复用**：提取公共配置为可复用组件\n3. **类型定义**：为自定义配置提供完整的 TypeScript 类型支持\n\n## 相关资源\n\n- [Schema Settings 文档](./schema-settings/index.md)\n- [Schema Initializer 文档](./schema-initializer/index.md)\n- [Schema Component 文档](./schema-component/index.md)\n- [流程引擎文档](../flow-engine/index.md)\n\n---\n\n\n\n## 文件管理与存储\n\n### 相关页面\n\n相关主题：[数据建模与集合管理](#data-modeling), [界面构建器](#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/plugins/@nocobase/plugin-ai/src/server/document-loader/cached.ts](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai/src/server/document-loader/cached.ts)\n- [packages/plugins/@nocobase/plugin-file-manager](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-file-manager) - *未在本次检索中获取到详细内容*\n- [packages/plugins/@nocobase/plugin-file-storage-s3-pro](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-file-storage-s3-pro) - *未在本次检索中获取到详细内容*\n- [docs/docs/cn/file-manager/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/cn/file-manager/index.md) - *未在本次检索中获取到详细内容*\n
\n\n# 文件管理与存储\n\n## 概述\n\nNocoBase 的文件管理与存储系统是一个模块化的基础设施，用于处理用户上传的文件、文档解析、以及与各种云存储服务的集成。该系统通过插件化的架构设计，支持灵活扩展存储后端，同时提供统一的客户端上传组件和服务器端处理逻辑。\n\n文件管理在 NocoBase 中扮演着关键角色，因为作为一个无代码平台，用户经常需要上传附件、文档、图片等资源，并对其进行管理和应用。\n\n## 核心组件架构\n\n### 上传组件（Upload）\n\nNocoBase 的前端上传组件基于 ant-design 的 Upload 组件进行封装，提供增强的功能和更好的用户体验。\n\n**组件类型定义：**\n\n```ts\ntype UploadProps = Omit & {\n onChange?: (fileList: UploadFile[]) => void;\n serviceErrorMessage?: string;\n value?: any;\n size?: string;\n};\n\ntype UploadReadPrettyProps = AntdUploadProps;\n```\n\n资料来源：[packages/core/client/src/schema-component/antd/upload/index.md:1-9]()\n\n**主要功能特性：**\n\n| 功能 | 描述 |\n|------|------|\n| 基础上传 | 支持单文件和文件列表上传 |\n| 规则验证 | 支持文件类型、大小等上传规则配置 |\n| 读写分离 | 提供不同的展示和编辑模式 |\n| 错误处理 | 支持自定义服务错误消息 |\n\n### 文档加载器\n\n在 AI 插件中，文件管理系统还负责文档的解析和加载。\n\n```ts\nprivate get aiFilesRepo() {\n return this.plugin.db.getRepository('aiFiles');\n}\n\nprivate get fileManager(): PluginFileManagerServer {\n return this.plugin.app.pm.get('file-manager');\n}\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/document-loader/cached.ts:76-81]()\n\n## 存储插件体系\n\n### 文件管理器插件\n\n文件管理器插件（`plugin-file-manager`）是 NocoBase 核心的文件管理模块，负责：\n\n- 文件元数据管理\n- 文件上传处理\n- 存储后端抽象\n- 访问权限控制\n\n### 存储后端插件\n\nNocoBase 采用插件化的存储后端设计，支持多种存储服务：\n\n| 存储类型 | 插件包 | 说明 |\n|----------|--------|------|\n| S3 兼容存储 | `plugin-file-storage-s3-pro` | 支持 AWS S3、MinIO 等 S3 兼容服务 |\n| 本地存储 | 内置支持 | 开发环境使用 |\n| 其他云存储 | 可扩展 | 通过插件机制支持 |\n\n## 数据流架构\n\n```mermaid\ngraph TD\n A[客户端上传组件] --> B[Upload API 端点]\n B --> C[文件管理器插件]\n C --> D[存储后端选择]\n D --> E[本地磁盘]\n D --> F[S3 兼容存储]\n D --> G[其他云存储]\n E --> H[文件元数据存储]\n F --> H\n G --> H\n H --> I[数据库记录]\n```\n\n## 客户端上传组件使用\n\n### 基础用法\n\n```tsx\nimport { Upload } from '@nocobase/client';\n\n// 基础上传示例\n\n```\n\n### 多文件上传\n\n```tsx\n// 多文件上传模式\n\n```\n\n### 带规则验证\n\n```tsx\n// 配置上传规则\n\n```\n\n### 只读展示\n\n```tsx\n// 用于展示已上传文件\n\n```\n\n## 服务器端处理\n\n### 文件管理器服务端\n\n文件管理器服务端负责处理上传请求、管理存储后端、以及维护文件元数据：\n\n```ts\nprivate get aiFilesRepo() {\n return this.plugin.db.getRepository('aiFiles');\n}\n\nprivate get fileManager(): PluginFileManagerServer {\n return this.plugin.app.pm.get('file-manager');\n}\n```\n\n服务器端提供以下核心能力：\n\n1. **文件存储抽象** - 通过统一的接口支持多种存储后端\n2. **元数据管理** - 使用 `aiFiles` 仓库管理文件元数据\n3. **访问控制** - 集成 NocoBase 的权限系统\n4. **文档解析** - 支持 AI 插件的文档加载需求\n\n### 文档解析元数据\n\n```ts\nprivate getParseMeta(meta?: Record): DocumentParseMeta | null {\n if (!meta || typeof meta !== 'object') {\n return null;\n }\n return meta[DOCUMENT_PARSE_META_KEY] ?? null;\n}\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/document-loader/cached.ts:47-52]()\n\n## 配置与扩展\n\n### 创建自定义存储后端\n\n开发者可以通过实现以下接口来创建自定义存储后端：\n\n```ts\ninterface StorageBackend {\n upload(file: Buffer, metadata: FileMetadata): Promise;\n download(path: string): Promise;\n delete(path: string): Promise;\n getUrl(path: string): string;\n}\n```\n\n### 注册文件处理插件\n\n```ts\n// 在插件的 install 方法中注册\nthis.app.pm.get('file-manager').registerBackend('custom', CustomStorageBackend);\n```\n\n## 与 AI 系统的集成\n\nNocoBase 的文件管理系统与 AI 插件深度集成，支持：\n\n- **文档加载** - 从存储中加载文档进行 AI 处理\n- **文件解析** - 解析各种文档格式提取内容\n- **向量化存储** - 支持将文件内容向量化后存储\n\n```ts\nreturn [\n new Document({\n pageContent: text,\n metadata: {\n source: sourceFile.filename,\n extname,\n },\n }),\n];\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/document-loader/cached.ts:32-40]()\n\n## 最佳实践\n\n### 前端配置建议\n\n1. **合理设置文件大小限制** - 根据业务需求和存储成本设置\n2. **使用适当的文件类型白名单** - 提高系统安全性\n3. **配置错误提示信息** - 提供清晰的用户反馈\n\n### 存储策略建议\n\n1. **生产环境使用云存储** - 如 S3、阿里云 OSS 等\n2. **配置合理的缓存策略** - 减少存储成本\n3. **定期清理过期文件** - 释放存储空间\n\n## 相关资源\n\n- [NocoBase 官方文档](https://docs.nocobase.com/)\n- [文件管理器插件源码](https://github.com/nocobase/nocobase/tree/main/packages/plugins/@nocobase/plugin-file-manager)\n- [S3 存储插件源码](https://github.com/nocobase/nocobase/tree/main/packages/plugins/@nocobase/plugin-file-storage-s3-pro)\n\n---\n\n\n\n## 插件开发指南\n\n### 相关页面\n\n相关主题：[系统架构与设计模式](#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/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-initializer/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-initializer/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/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/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/mobile-layout/index.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-mobile/src/client/mobile-layout/index.md)\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/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- [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-component/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/index.md)\n
\n\n# 插件开发指南\n\n## 概述\n\nNocoBase 采用插件化架构，所有功能均以插件形式实现。插件系统是 NocoBase 的核心组成部分，允许开发者通过编写插件来扩展系统功能，实现模块化的功能管理与部署。\n\nNocoBase 的插件分为两类：\n\n- **客户端插件**：负责用户界面、页面路由、Schema 组件、Schema 初始化器等前端功能\n- **服务器端插件**：负责数据模型、API 接口、业务逻辑、数据库操作等后端功能\n\n一个完整的插件可以同时包含客户端和服务器端代码，通过统一的插件机制进行注册和管理。\n\n## 插件架构\n\n### 核心架构图\n\n```mermaid\ngraph TB\n subgraph 客户端 Client\n UI[用户界面]\n SC[Schema 组件]\n SI[Schema 初始化器]\n SS[Schema 设置]\n PM_UI[插件管理器 UI]\n end\n\n subgraph 服务器端 Server\n API[API 接口]\n DB[数据库操作]\n MODEL[数据模型]\n HOOKS[Hooks 钩子]\n end\n\n subgraph 核心 Core\n PM[插件管理器 PluginManager]\n PM_API[插件 API]\n end\n\n UI --> PM_UI\n SC --> SS\n SI --> SS\n PM_UI --> PM\n PM --> PM_API\n API --> PM_API\n DB --> PM_API\n MODEL --> PM_API\n HOOKS --> PM_API\n\n style PM fill:#e1f5fe\n style PM_API fill:#e1f5fe\n```\n\n### 插件生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> 安装: npm install\n 安装 --> 启用: enable()\n 启用 --> 加载: load()\n 加载 --> 运行: activate()\n 运行 --> 禁用: deactivate()\n 禁用 --> 启用: activate()\n 启用 --> 卸载: disable()\\nuninstall()\n 运行 --> 卸载: disable()\\nuninstall()\n 卸载 --> [*]\n```\n\n## 目录结构\n\n一个典型的插件项目目录结构如下：\n\n```\npackages/plugins/@nocobase/plugin-sample/\n├── src/\n│ ├── client/ # 客户端代码\n│ │ ├── index.ts # 客户端插件入口\n│ │ ├── pages/ # 页面组件\n│ │ ├── components/ # 自定义组件\n│ │ ├── schema-components/ # Schema 组件\n│ │ ├── schema-initializers/ # Schema 初始化器\n│ │ ├── schema-settings/ # Schema 设置\n│ │ ├── demos/ # 文档示例\n│ │ └── index.md # 文档\n│ └── server/ # 服务器端代码\n│ ├── index.ts # 服务器端插件入口\n│ ├── actions/ # 自定义 actions\n│ ├── collections/ # 数据模型定义\n│ └── migrations/ # 数据库迁移\n├── package.json\n└── README.md\n```\n\n## 服务器端插件开发\n\n### 插件类基础\n\n服务器端插件继承自 `Plugin` 基类，通过覆写生命周期方法来实现功能：\n\n```typescript\nimport { Plugin } from '@nocobase/server';\n\nexport class SamplePlugin extends Plugin {\n async load() {\n // 加载阶段：注册数据模型、API 路由等\n this.app.collection({\n name: 'samples',\n fields: [\n { type: 'string', name: 'title' },\n { type: 'text', name: 'description' },\n ],\n });\n\n this.app.acl.allow('samples', 'list');\n }\n\n async activate() {\n // 激活阶段：执行初始化逻辑\n }\n\n async deactivate() {\n // 停用阶段：清理资源\n }\n}\n\nexport default SamplePlugin;\n```\n\n### 数据模型定义\n\n```typescript\nthis.app.collection({\n name: 'articles',\n fields: [\n { type: 'belongsTo', name: 'author' },\n { type: 'hasMany', name: 'comments' },\n { type: 'string', name: 'title' },\n { type: 'richtext', name: 'content' },\n { type: 'date', name: 'publishedAt' },\n { type: 'boolean', name: 'isPublished' },\n ],\n});\n```\n\n### API 路由注册\n\n```typescript\nthis.app.resourcer.define({\n name: 'articles',\n actions: {\n async list(ctx, next) {\n // 自定义列表逻辑\n await next();\n },\n async create(ctx, next) {\n ctx.request.body.author = ctx.state.currentUser.id;\n await next();\n },\n },\n});\n```\n\n### Hooks 机制\n\nNocoBase 提供了丰富的 Hooks 用于扩展功能：\n\n| Hook 名称 | 说明 | 使用场景 |\n|---------|------|---------|\n| `beforeSave` | 保存前执行 | 数据校验、默认值设置 |\n| `afterSave` | 保存后执行 | 关联操作、日志记录 |\n| `beforeFind` | 查询前执行 | 权限过滤、条件追加 |\n| `afterFind` | 查询后执行 | 数据转换、字段处理 |\n| `beforeRemove` | 删除前执行 | 关联删除、权限校验 |\n| `afterRemove` | 删除后执行 | 清理操作、通知发送 |\n\n```typescript\nthis.app.on('afterSave', async (event, model) => {\n if (model.get('type') === 'published') {\n // 发送通知等操作\n }\n});\n```\n\n### 资源上下文 API\n\n插件可以通过 `ctx.resource` 访问当前资源上下文：\n\n```typescript\n// 设置资源当前数据（仅前端）\nctx.resource.setData(value);\n\n// 从后端刷新数据\nawait ctx.resource.refresh();\n\n// 订阅资源事件\nctx.resource.on('refresh', () => {});\n\n// 设置资源名称\nctx.resource.setResourceName('users');\n\n// 设置主键/过滤键\nctx.resource.setFilterByTk(id);\n\n// 执行资源动作\nawait ctx.resource.runAction('create', data);\n```\n\n## 客户端插件开发\n\n### 插件入口\n\n```typescript\nimport { Plugin } from '@nocobase/client';\n\nexport class SamplePlugin extends Plugin {\n async load() {\n // 注册页面路由\n this.app.router.add('sample', {\n path: '/sample',\n Component: SamplePage,\n });\n\n // 注册 Schema 组件\n this.app.schemaInitializerManager.add('SampleInitializer', {\n // ...\n });\n\n // 注册 Schema 设置\n this.app.schemaSettingsManager.add('SampleSetting', {\n // ...\n });\n }\n}\n\nexport default SamplePlugin;\n```\n\n### Schema 组件\n\nSchema 是 NocoBase 前端配置的核心机制，用于描述界面结构和行为：\n\n```mermaid\ngraph LR\n A[Schema 配置] --> B[组件渲染]\n A --> C[数据绑定]\n A --> D[事件处理]\n A --> E[样式配置]\n```\n\n#### Schema 基础结构\n\n```typescript\nconst schema = {\n type: 'void',\n 'x-component': 'SampleCard',\n 'x-component-props': {\n title: '{{ title }}',\n },\n properties: {\n content: {\n type: 'void',\n 'x-component': 'Markdown',\n 'x-content': '{{ content }}',\n },\n },\n};\n```\n\n#### Schema 组件类型\n\n| 类型 | 说明 | 示例 |\n|-----|------|------|\n| `void` | 容器组件 | `Grid`, `Card`, `Form` |\n| `string` | 文本输入 | `Input`, `Textarea` |\n| `number` | 数字输入 | `InputNumber` |\n| `boolean` | 开关选择 | `Switch` |\n| `date` | 日期选择 | `DatePicker` |\n\n### Schema 初始化器\n\nSchema 初始化器用于在设计器中插入 Schema 节点：\n\n```typescript\nthis.app.schemaInitializerManager.add('SampleBlockInitializer', {\n title: '示例区块',\n icon: 'PlusOutlined',\n sections: {\n basic: {\n title: '基础',\n items: [\n {\n title: '表格',\n schema: {\n type: 'void',\n 'x-component': 'Table',\n },\n },\n ],\n },\n },\n});\n```\n\n#### 动态显示和隐藏\n\n```typescript\n{\n 'x-initializer': 'SampleInitializer',\n 'x-initializer-props': {\n filter: (node) => node.schema?.['x-designer'] === 'SampleDesigner',\n },\n}\n```\n\n### Schema 设置\n\nSchema 设置用于配置 Schema 节点的属性：\n\n```typescript\nthis.app.schemaSettingsManager.add('SampleSetting', {\n title: '示例设置',\n items: [\n {\n name: 'title',\n title: '标题',\n component: {\n name: 'Input',\n props: {\n placeholder: '{{ t(\"Title\") }}',\n },\n },\n },\n {\n name: 'description',\n title: '描述',\n component: {\n name: 'TextArea',\n props: {\n rows: 4,\n },\n },\n },\n {\n name: 'divider',\n type: 'divider',\n },\n {\n name: 'delete',\n title: '删除',\n component: {\n name: 'Delete',\n props: {\n danger: true,\n },\n },\n },\n ],\n});\n```\n\n### Schema 设计器\n\nSchema 设计器提供可视化编辑 Schema 的能力：\n\n```typescript\nimport { GeneralSchemaDesigner } from '@nocobase/client';\n\nconst SampleDesigner = () => {\n return (\n \n );\n};\n```\n\n## 插件管理器\n\nNocoBase 提供了内置的插件管理器，支持插件的安装、启用、禁用和卸载。\n\n### 插件信息展示\n\n插件详情页面展示以下信息：\n\n| 字段 | 说明 |\n|-----|------|\n| 名称 (Name) | 插件内部名称 |\n| 显示名称 (DisplayName) | 用户友好的名称 |\n| 包名 (PackageName) | npm 包名 |\n| 版本 (Version) | 当前版本号 |\n| 作者 (Author) | 插件作者 |\n| 仓库 (Repository) | 源码仓库地址 |\n| 主页 (Homepage) | 文档或项目主页 |\n| 许可证 (License) | 开源许可证 |\n| 描述 (Description) | 插件功能描述 |\n\n### 依赖兼容性检查\n\n插件管理器会检查插件依赖的兼容性：\n\n```typescript\n// 检查是否包含 externalVersion.js\nif (data?.data?.depsCompatible === false) {\n return ;\n}\n\n// 检查依赖版本是否兼容\nif (!data?.data?.['isCompatible']) {\n return ;\n}\n```\n\n## 变量系统\n\nNocoBase 提供了内置变量系统，支持在配置中使用动态值：\n\n### 内置变量\n\n| 变量名 | 说明 | 示例 |\n|-------|------|------|\n| `$nRecord` | 当前记录数据 | `$nRecord.title` |\n| `$nUser` | 当前用户信息 | `$nUser.id`, `$nUser.name` |\n| `$nRole` | 当前角色信息 | `$nRole.name` |\n| `$nDate` | 当前日期时间 | `$nDate.format('YYYY-MM-DD')` |\n| `$nExactDate` | 精确时间戳 | `$nExactDate` |\n| `$date` | 日期（已废弃） | - |\n| `$system` | 系统变量（已废弃） | - |\n| `currentTime` | 当前时间（已废弃） | - |\n| `$nVisible` | 可见性控制 | `$nVisible` |\n\n### 变量上下文\n\n```typescript\n{\n name: '$nUser',\n ctx: {\n id: () => currentUser.id,\n name: () => currentUser.name,\n email: () => currentUser.email,\n },\n}\n```\n\n## 流程引擎集成\n\n插件可以与流程引擎集成，实现复杂的业务流程：\n\n### 自定义动作\n\n```typescript\nimport { FlowSettings } from '@nocobase/plugin-workflow';\n\nclass SamplePlugin extends Plugin {\n async load() {\n // 注册流程设置组件\n this.app.setFlowSettings({\n components: {\n SampleNode: SampleNodeComponent,\n },\n scopes: {\n sampleScope: SampleScopeComponent,\n },\n });\n }\n}\n```\n\n### 自定义 Footer\n\n流程设置支持自定义底部按钮区域：\n\n```typescript\n// 方式一：追加内容\nfooter: (originNode, { OkBtn, CancelBtn }) => (\n
\n Additional info\n {originNode}\n
\n)\n\n// 方式二：完全自定义\nfooter: (originNode, { OkBtn, CancelBtn }) => (\n \n \n \n \n)\n\n// 方式三：隐藏底部\nfooter: null\n```\n\n## 移动端插件开发\n\nNocoBase 支持移动端页面的开发，通过 MobileTabBar 提供底部导航：\n\n### MobileTabBar 组件\n\n```typescript\nimport { MobileTabBar } from '@nocobase/plugin-mobile';\n\n// 使用 Link 跳转\n}\n title=\"首页\"\n/>\n\n// 外部链接\n}\n title=\"外部链接\"\n/>\n```\n\n### Schema 定义\n\n```typescript\n{\n type: 'void',\n 'x-component': 'MobileTabBar',\n 'x-component-props': {\n activeKey: '{{ activeKey }}',\n },\n properties: {\n home: {\n type: 'void',\n 'x-component': 'MobileTabBar.Item',\n 'x-component-props': {\n key: 'home',\n icon: 'HomeOutlined',\n link: '/pages/home/index',\n },\n },\n },\n}\n```\n\n### Desktop Mode\n\n当在桌面端访问移动端页面时，可以使用 DesktopMode 组件：\n\n```typescript\nimport { DesktopMode } from '@nocobase/plugin-mobile';\n\n\n \n\n```\n\n## 联动规则\n\nNocoBase 支持在表单中使用联动规则，实现字段间的动态关联：\n\n### LinkageFilter 组件\n\n```typescript\ntype FilterActionProps = ActionProps & {\n options?: any[]; // 可选的操作符\n form?: Form; // 表单实例\n onSubmit?: (values: T) => void; // 提交回调\n onReset?: (values: T) => void; // 重置回调\n};\n```\n\n### 基本用法\n\n左侧支持变量、操作符，右侧变量组件跟随左侧变量联动：\n\n```typescript\n{\n type: 'void',\n 'x-component': 'LinkageFilter',\n 'x-component-props': {\n options: [\n { label: '等于', value: '=' },\n { label: '包含', value: 'contains' },\n ],\n onSubmit: (values) => {\n // 处理筛选\n },\n },\n}\n```\n\n## 最佳实践\n\n### 1. 插件命名规范\n\n```json\n{\n \"name\": \"@nocobase/plugin-{feature-name}\",\n \"version\": \"1.0.0\",\n \"displayName\": \"{{t('Feature Name')}}\",\n \"description\": \"{{t('Plugin description')}}\"\n}\n```\n\n### 2. 国际化支持\n\n```typescript\n// 使用 t() 函数进行翻译\ntitle: t('Sample Plugin'),\ndescription: t('This is a sample plugin for demonstration'),\n\n// 支持中文\ndata?.data?.lang === 'zh-CN' ? '中文链接' : 'English Link'\n```\n\n### 3. Schema 组件开发\n\n```typescript\nimport { SchemaComponent } from '@nocobase/client';\n\nconst SampleComponent = (props) => {\n return (\n \n );\n};\n```\n\n### 4. 错误处理\n\n```typescript\n// 插件加载失败处理\nasync load() {\n try {\n await this.registerCollections();\n await this.registerActions();\n } catch (error) {\n console.error('Plugin load error:', error);\n throw error;\n }\n}\n\n// 依赖检查\nif (data?.data?.depsCompatible === false) {\n throw new Error('插件依赖不兼容，请重新构建');\n}\n```\n\n### 5. 性能优化\n\n```typescript\n// 使用 React.memo 优化组件\nconst SchemaToolbar = React.memo((props) => {\n // ...\n});\n\n// 使用 useCallback 缓存回调\nconst onVisibleChange = useCallback((nextVisible: boolean) => {\n startTransition(() => {\n setVisible(nextVisible);\n });\n}, []);\n```\n\n## 注册插件到系统\n\n### 服务器端注册\n\n```typescript\n// packages/plugins/@nocobase/plugin-sample/src/server/index.ts\nimport { SamplePlugin } from './SamplePlugin';\n\nexport default SamplePlugin;\n```\n\n### 客户端注册\n\n```typescript\n// packages/plugins/@nocobase/plugin-sample/src/client/index.ts\nimport { SampleClientPlugin } from './SampleClientPlugin';\n\nexport default SampleClientPlugin;\n```\n\n### 插件启用\n\n在 `packages/core/server/src/plugins/index.ts` 中添加插件：\n\n```typescript\nimport sample from '@nocobase/plugin-sample';\n\nexport const plugins = [\n // ...其他插件\n sample,\n];\n```\n\n## 总结\n\nNocoBase 的插件系统提供了完整的扩展能力：\n\n- **模块化架构**：前后端分离的插件开发模式\n- **Schema 机制**：灵活的界面配置系统\n- **生命周期管理**：完整的插件安装、启用、停用流程\n- **依赖管理**：自动化的依赖检查和兼容性验证\n- **多端支持**：同时支持桌面端和移动端插件开发\n\n开发者可以通过继承基类、重写生命周期方法、注册组件和配置来实现各种业务需求。\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 项目说明书", "目录", "NocoBase 概述", "什么是 NocoBase", "系统架构", "核心模块详解", "主要功能特性", "快速链接", "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": "f67491bb035cca5c27cb15de94a288dd03bd72c6", "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- 文件总数：18350\n- 重要文件覆盖：40/18350\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- **NocoBase 概述**：importance `high`\n - source_paths: README.md, README.zh-CN.md, package.json\n- **系统架构与设计模式**：importance `high`\n - source_paths: packages/core/client/src/application.ts, packages/core/server/src/application.ts, packages/core/server/src/plugin.ts\n- **数据建模与集合管理**：importance `high`\n - source_paths: packages/plugins/@nocobase/plugin-data-source-manager, packages/core/database/src/collection.ts, packages/core/database/src/field.ts, packages/core/database/src/repository.ts\n- **外部数据源与多数据库支持**：importance `medium`\n - source_paths: packages/plugins/@nocobase/plugin-data-source-external-mysql, packages/plugins/@nocobase/plugin-data-source-external-postgres, packages/plugins/@nocobase/plugin-data-source-external-mariadb, packages/plugins/@nocobase/plugin-collection-fdw\n- **权限系统与 ACL**：importance `high`\n - source_paths: packages/plugins/@nocobase/plugin-acl, packages/core/server/src/acl/acl.ts, packages/core/server/src/acl/role.ts\n- **工作流引擎**：importance `high`\n - source_paths: packages/plugins/@nocobase/plugin-workflow, packages/plugins/@nocobase/plugin-workflow-approval, packages/plugins/@nocobase/plugin-workflow-request, docs/docs/cn/workflow/index.md\n- **AI 集成与智能员工**：importance `high`\n - source_paths: packages/plugins/@nocobase/plugin-ai, packages/plugins/@nocobase/plugin-ai-knowledge-base, docs/docs/cn/ai-employees/index.md, docs/docs/cn/ai-employees/knowledge-base/rag.md\n- **界面构建器**：importance `high`\n - source_paths: packages/plugins/@nocobase/plugin-client, docs/docs/cn/interface-builder/index.md, docs/docs/cn/interface-builder/blocks/index.md, docs/docs/cn/interface-builder/actions/index.md\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `f67491bb035cca5c27cb15de94a288dd03bd72c6`\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-13 22:57:37 UTC\n\n## 目录\n\n- [NocoBase 概述](#nocobase-overview)\n- [系统架构与设计模式](#system-architecture)\n- [数据建模与集合管理](#data-modeling)\n- [外部数据源与多数据库支持](#external-data-sources)\n- [权限系统与 ACL](#acl-permissions)\n- [工作流引擎](#workflow-engine)\n- [AI 集成与智能员工](#ai-integration)\n- [界面构建器](#interface-builder)\n- [文件管理与存储](#file-manager)\n- [插件开发指南](#plugin-development)\n\n\n\n## NocoBase 概述\n\n### 相关页面\n\n相关主题：[系统架构与设计模式](#system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/nocobase/nocobase/blob/main/README.md)\n- [README.zh-CN.md](https://github.com/nocobase/nocobase/blob/main/README.zh-CN.md)\n- [package.json](https://github.com/nocobase/nocobase/blob/main/package.json)\n- [packages/core/client/src/user/Help.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/user/Help.tsx)\n- [packages/core/flow-engine/src/flowSettings.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/flowSettings.ts)\n
\n\n# NocoBase 概述\n\n## 什么是 NocoBase\n\nNocoBase 是一个开源的 AI + 无代码平台，用于快速构建业务系统。与从零开始生成所有内容不同，AI 在经过生产验证的基础设施和所见即所得（WYSIWYG）的无代码界面上工作，既能保证开发速度，又能确保系统的稳定性和可靠性。\n\n资料来源：[README.md:1-10]()\n\n### 核心价值主张\n\nNocoBase 的核心价值在于将人工智能与无代码技术相结合，让开发者和业务用户能够：\n\n- **快速构建**：通过可视化配置而非传统编码方式快速搭建业务系统\n- **AI 赋能**：借助 AI Agent 实现自动化和智能化的业务流程\n- **灵活扩展**：支持插件化架构，可根据需求扩展功能\n- **协作共建**：AI 和人类协同工作，共同构建系统\n\n资料来源：[README.md:47-52]()\n\n---\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TB\n subgraph 前端层[\"前端层 (Client)\"]\n PC[PC 端客户端]\n Mobile[移动端插件
@nocobase/plugin-mobile]\n Theme[主题编辑器
@nocobase/plugin-theme-editor]\n end\n \n subgraph 核心层[\"核心模块 (Core)\"]\n Schema[Schema 组件系统]\n PM[插件管理器
PluginManager]\n FlowEngine[流程引擎
FlowEngine]\n Variables[变量系统]\n SchemaSettings[Schema 配置]\n SchemaInitializer[Schema 初始化器]\n end\n \n subgraph 插件层[\"插件生态\"]\n AI[AI 插件
@nocobase/plugin-ai]\n Auth[认证插件]\n Database[数据库插件]\n API[API 插件]\n end\n \n subgraph 服务层[\"服务端 (Server)\"]\n Server[服务端核心]\n DatabaseEngine[(数据库引擎)]\n end\n \n PC --> Schema\n PC --> PM\n Mobile --> Schema\n Theme --> Schema\n \n Schema --> SchemaSettings\n Schema --> SchemaInitializer\n \n PM --> AI\n PM --> Auth\n PM --> Database\n \n AI --> Server\n Server --> DatabaseEngine\n \n PC --> Server\n```\n\n### 目录结构\n\nNocoBase 采用 monorepo 结构，主要目录如下：\n\n| 目录 | 说明 |\n|------|------|\n| `packages/core/` | 核心包，包含客户端和服务端基础模块 |\n| `packages/core/client/` | 前端核心代码 |\n| `packages/core/flow-engine/` | 流程引擎实现 |\n| `packages/plugins/` | 官方插件集合 |\n| `packages/plugins/@nocobase/plugin-mobile/` | 移动端支持插件 |\n| `packages/plugins/@nocobase/plugin-ai/` | AI 能力插件 |\n| `packages/plugins/@nocobase/plugin-theme-editor/` | 主题编辑器插件 |\n\n资料来源：[package.json:1-20]()\n\n---\n\n## 核心模块详解\n\n### 插件管理系统 (PluginManager)\n\nNocoBase 的核心架构基于插件系统，插件管理器（PluginManager）负责插件的加载、启停和管理。\n\n```mermaid\ngraph LR\n subgraph 插件详情[\"插件详情组件\"]\n PInfo[基本信息]\n DCheck[依赖兼容性检查]\n CHLog[更新日志]\n end\n \n PM[PluginManager] --> PInfo\n PM --> DCheck\n PM --> CHLog\n \n DCheck --> |兼容性状态| Alert[警告提示]\n DCheck --> Table[依赖表格]\n```\n\n每个插件包含以下元信息：\n\n| 属性 | 说明 |\n|------|------|\n| `packageName` | 插件包名称 |\n| `version` | 当前版本号 |\n| `description` | 插件描述 |\n| `author` | 作者信息 |\n| `license` | 开源许可证 |\n| `homepage` | 项目主页 |\n| `isCompatible` | 与系统的兼容性状态 |\n\n资料来源：[packages/core/client/src/pm/PluginDetail.tsx:1-50]()\n\n### Schema 组件系统\n\nSchema 是 NocoBase 中用于描述界面配置的核心概念，通过声明式的 Schema 定义，可以配置页面的布局、字段、动作等元素。\n\n#### Schema 组成部分\n\n| 组件 | 功能 |\n|------|------|\n| SchemaSettings | Schema 的配置面板，用于设置组件属性 |\n| SchemaInitializer | Schema 的初始化器，决定可以在何处添加新元素 |\n| GeneralSchemaDesigner | 通用的 Schema 设计器组件 |\n| LinkageFilter | 联动过滤器，用于配置条件联动规则 |\n\n资料来源：[packages/core/client/src/schema-settings/index.md:1-20]()\n资料来源：[packages/core/client/src/schema-component/antd/linkageFilter/index.md:1-15]()\n\n### 变量系统 (Variables)\n\nNocoBase 提供丰富的内置变量系统，支持在配置中引用各种运行时上下文。\n\n```mermaid\ngraph TD\n V[内置变量] --> User[用户变量]\n V --> Role[角色变量]\n V --> DateTime[时间变量]\n V --> URL[URL 参数]\n V --> System[系统变量]\n \n User --> |$nUserId| UserId[当前用户 ID]\n User --> |$nUserRoles| UserRoles[当前用户角色]\n User --> |$nUserEmail| UserEmail[用户邮箱]\n \n DateTime --> |$nDate| CurrentDate[当前日期]\n DateTime --> |$nExactDate| ExactDateTime[精确时间]\n \n System --> |$system| SystemInfo[系统信息]\n```\n\n**内置变量列表：**\n\n| 变量名 | 说明 | 状态 |\n|--------|------|------|\n| `$nUserId` | 当前登录用户 ID | 活跃 |\n| `$nRoleId` | 当前用户角色 ID | 活跃 |\n| `$nDate` | 当前日期时间 | 活跃 |\n| `$nExactDate` | 精确时间戳 | 活跃 |\n| `$date` | 日期（已废弃） | 废弃 |\n| `$system` | 系统变量（已废弃） | 废弃 |\n| `currentTime` | 当前时间（已废弃） | 废弃 |\n| `urlSearchParams` | URL 查询参数 | 活跃 |\n\n资料来源：[packages/core/client/src/variables/hooks/useBuiltinVariables.ts:1-80]()\n\n### 流程引擎 (Flow Engine)\n\n流程引擎是 NocoBase 处理复杂业务流程的核心模块，支持可视化的工作流配置。\n\n#### FlowSettings 配置结构\n\n```typescript\ninterface FlowSettingsConfig {\n footer?: React.ReactNode | ((originNode, { OkBtn, CancelBtn }) => React.ReactNode) | null;\n [key: string]: any;\n}\n```\n\n**Footer 自定义方式：**\n\n| 类型 | 示例 | 说明 |\n|------|------|------|\n| 直接渲染 | `
内容
` | 静态内容 |\n| 包裹式 | `footer: (originNode) => (
包裹 {originNode}
)` | 在原有按钮外添加内容 |\n| 函数式 | `footer: (originNode, { OkBtn, CancelBtn }) => ()` | 完全自定义按钮组合 |\n| 隐藏 | `footer: null` | 隐藏底部按钮栏 |\n\n资料来源：[packages/core/flow-engine/src/flowSettings.ts:1-50]()\n\n---\n\n## 主要功能特性\n\n### 1. 协作式构建\n\nNocoBase 强调 AI 和人类协作构建系统的理念：\n\n- AI Agent 可以帮助完成代码生成、API 调用、文档阅读等任务\n- 人类开发者通过可视化的无代码界面进行配置和调整\n- 两者相互配合，提高开发效率\n\n资料来源：[README.md:53-58]()\n\n### 2. 移动端支持\n\n通过 `@nocobase/plugin-mobile` 插件，NocoBase 支持移动端应用的构建：\n\n| 组件 | 说明 |\n|------|------|\n| MobileTabBar | 移动端底部导航栏 |\n| MobileTabBar.Item | 导航项 |\n| MobileTabBar.Link | 链接导航项，支持内部页面和外部页面跳转 |\n| DesktopMode | 桌面端访问移动端页面时的占位组件 |\n\n移动端支持 Schema 配置，可以实现复杂的移动端页面布局。\n\n资料来源：[packages/plugins/@nocobase/plugin-mobile/src/client/pages/index.md:1-25]()\n资料来源：[packages/plugins/@nocobase/plugin-mobile/src/client/mobile-layout/index.md:1-20]()\n\n### 3. 主题定制\n\n`@nocobase/plugin-theme-editor` 插件提供了主题编辑功能，支持通过 Ant Design Token 定制界面样式。\n\n资料来源：[packages/plugins/@nocobase/plugin-theme-editor/src/client/antd-token-previewer/component-demos/typography/typographyFull.tsx:1-30]()\n\n### 4. AI Agent 能力\n\n`@nocobase/plugin-ai` 插件集成了 AI 能力，支持：\n\n- 文档阅读和检索\n- 代码生成和执行\n- 数据库操作的智能辅助\n- 多数据源支持\n\n**AI 插件特性：**\n\n| 功能 | 说明 |\n|------|------|\n| 文档工具 | 读取项目文档和 API 文档 |\n| 代码执行 | 支持 RunJS 等代码执行环境 |\n| 数据库操作 | 辅助生成 SQL 和数据库操作 |\n| 多语言支持 | 支持中英文等不同语言的交互 |\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/tools/docs.ts:1-50]()\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/ai-employees/prompts.ts:1-40]()\n\n---\n\n## 快速链接\n\n### 官方资源\n\n| 资源 | 链接 |\n|------|------|\n| 官方网站 | https://www.nocobase.com/ |\n| 在线演示 | https://demo.nocobase.com/new |\n| 开发文档 | https://docs.nocobase.com/ |\n| 用户论坛 | https://forum.nocobase.com/ |\n| 更新日志 | https://www.nocobase.com/en/blog/timeline |\n\n资料来源：[README.md:20-40]()\n资料来源：[packages/core/client/src/user/Help.tsx:1-50]()\n\n---\n\n## 技术栈概览\n\n### 前端技术\n\n- **框架**：React\n- **UI 库**：Ant Design\n- **状态管理**：Zustand\n- **移动端**：React Native（通过 WebView 混合方案）\n\n### 后端技术\n\n- **运行时**：Node.js\n- **框架**：Koa.js\n- **数据库**：支持多种数据库（MySQL、PostgreSQL、SQLite 等）\n\n### 构建工具\n\n- **包管理**：pnpm\n- **构建**：Turborepo\n- **类型检查**：TypeScript\n\n资料来源：[package.json:1-100]()\n\n---\n\n## 总结\n\nNocoBase 是一个现代化的开源无代码平台，通过以下核心特性为业务系统开发提供强大支持：\n\n1. **插件化架构**：高度可扩展的插件系统，支持按需加载功能\n2. **Schema 驱动的配置**：声明式的界面配置方式\n3. **AI 赋能**：集成 AI Agent，提升开发效率\n4. **多端支持**：同时支持桌面端和移动端\n5. **灵活的主题定制**：通过 Token 系统实现品牌定制\n\n无论是小型业务系统还是大型企业应用，NocoBase 都能提供灵活、高效的解决方案。\n\n---\n\n\n\n## 系统架构与设计模式\n\n### 相关页面\n\n相关主题：[NocoBase 概述](#nocobase-overview), [插件开发指南](#plugin-development)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/client/src/application.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/application.ts)\n- [packages/core/server/src/application.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/server/src/application.ts)\n- [packages/core/server/src/plugin.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/server/src/plugin.ts)\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/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
\n\n# 系统架构与设计模式\n\n## 概述\n\nNocoBase 采用分层模块化架构设计，核心遵循**插件化架构**（Plugin Architecture）和**配置驱动架构**（Configuration-driven Architecture）两大设计理念。系统分为服务端（Server）和客户端（Client）两大主体，通过插件机制实现功能扩展，通过 Schema 配置驱动实现前端界面与业务逻辑的解耦。\n\n## 核心架构分层\n\n### 架构层次总览\n\n```graph TD\n A[客户端 Client] --> B[应用层 Application]\n A --> C[Schema 组件层]\n A --> D[Schema 配置层]\n B --> E[插件管理层 PM]\n C --> F[数据区块 Provider]\n D --> G[Schema 设计器]\n E --> H[插件 Plugin]\n H --> I[服务端插件]\n H --> J[客户端插件]\n```\n\n### 服务端架构\n\n服务端基于 **Plugin 插件基类**构建，所有业务模块均以插件形式注册。插件系统提供了完整的生命周期管理，包括 `load`、`enable`、`disable` 等状态转换。\n\n```graph TD\n A[Application] --> B[Plugin Manager]\n A --> C[数据层 Data]\n A --> D[认证层 Auth]\n B --> E[Plugin 实例]\n E --> F[install]\n E --> G[load]\n E --> H[enable]\n E --> I[disable]\n```\n\n服务端 `Application` 类负责统一管理插件的加载与初始化流程，通过 `pm`（Plugin Manager）实现插件的注册、启用、停用等操作。资料来源：[packages/core/server/src/application.ts]()\n\n### 客户端架构\n\n客户端采用 **React Context** 进行状态管理和依赖注入，主要包括以下几个核心模块：\n\n| 模块 | 职责 | 核心文件 |\n|------|------|----------|\n| Application | 应用初始化与全局状态 | application.ts |\n| SchemaComponent | Schema 驱动的组件渲染 | schema-component/index.md |\n| SchemaSettings | Schema 配置编辑器 | schema-settings/index.md |\n| SchemaInitializer | Schema 初始化器 | schema-initializer/index.md |\n| PM (Plugin Manager) | 插件管理与详情展示 | PluginDetail.tsx |\n\n## 插件系统设计\n\n### 插件架构模式\n\nNocoBase 的插件系统采用**观察者模式**与**依赖注入模式**相结合的架构。每个插件包含服务端和客户端两部分，通过统一的插件管理器进行协调。\n\n```mermaid\ngraph TD\n subgraph 服务端\n A1[Plugin 基类] --> A2[install 方法]\n A1 --> A3[load 方法]\n A1 --> A4[enable 方法]\n end\n \n subgraph 客户端\n B1[React Component] --> B2[Configuration]\n B1 --> B3[Settings]\n B1 --> B4[Initializer]\n end\n \n A1 --> B1\n```\n\n### 插件元数据管理\n\n插件详情组件 `PluginDetail` 展示插件的完整信息，包括版本、依赖兼容性、许可证等。依赖兼容性检查机制确保插件间的版本匹配。\n\n```typescript\n// 插件详情信息结构\ninterface PluginInfo {\n packageName: string; // 包名\n version: string; // 版本号\n description?: string; // 描述\n author?: string; // 作者\n homepage?: string; // 主页\n license?: string; // 许可证\n depsCompatible?: boolean; // 依赖兼容性\n}\n```\n\n资料来源：[packages/core/client/src/pm/PluginDetail.tsx]()\n\n### 依赖兼容性检查\n\n插件系统内置依赖兼容性检查机制，通过 `externalVersion.js` 文件记录插件的外部依赖版本信息。检查结果通过 `isCompatible` 字段标识，兼容性检查失败时会显示错误提示。\n\n## Schema 驱动架构\n\n### Schema 设计理念\n\nNocoBase 的前端界面完全由 **Schema 配置**驱动。Schema 是 JSON 格式的配置对象，定义了界面的结构、行为和样式。这种设计实现了**界面与逻辑的分离**，使非开发人员也能通过配置自定义系统功能。\n\n```mermaid\ngraph LR\n A[Schema JSON] --> B[Schema 解析器]\n B --> C[SchemaComponent]\n B --> D[SchemaSettings]\n B --> E[SchemaInitializer]\n C --> F[用户界面]\n```\n\n### Schema 组件层级\n\n| 组件类型 | 用途 | 配置属性 |\n|----------|------|----------|\n| SchemaComponent | 根据 Schema 渲染 UI | `x-component` |\n| SchemaSettings | 组件的配置面板 | `x-settings` |\n| SchemaInitializer | 组件的初始化器 | `x-initializer` |\n\n### SchemaToolbar 组件\n\n`GeneralSchemaDesigner` 是 Schema 设计器的核心组件，负责渲染 Schema 的工具栏界面，包括标题、拖拽手柄、初始化器和配置下拉菜单。\n\n```typescript\ninterface SchemaToolbarProps {\n title?: string | string[];\n template?: boolean;\n draggable?: boolean;\n showDataSource?: boolean;\n templateName?: string;\n}\n```\n\n资料来源：[packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx]()\n\n## 流程引擎架构\n\n### FlowSettings 配置系统\n\n流程引擎（Flow Engine）采用**配置化设计**，通过 `FlowSettings` 类管理流程节点组件和作用域变量。\n\n```typescript\nclass 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]()\n\n### 流程配置 Footer 自定义\n\n流程设置支持四种 Footer 配置模式：\n\n| 模式 | 类型 | 说明 |\n|------|------|------|\n| 默认 | `React.ReactNode` | 原生 React 节点 |\n| 增强 | 函数式 | `(originNode, { OkBtn, CancelBtn }) => ReactNode` |\n| 完全自定义 | 函数式 | 重新组合按钮布局 |\n| 隐藏 | `null` | 隐藏底部区域 |\n\n## 变量系统\n\n### 内置变量机制\n\n系统提供内置变量支持，通过 `useBuiltInVariables` Hook 获取。内置变量包括用户上下文、日期时间、URL 参数等。\n\n```typescript\n// 内置变量列表\nconst builtinVariables = [\n { name: '$nUser', ctx: currentUserCtx },\n { name: '$nRole', ctx: currentRoleCtx },\n { name: '$nDate', ctx: datetimeCtx },\n { name: '$nExactDate', ctx: exactDateTimeCtx },\n { name: '$nUrlSearchParams', ctx: urlSearchParamsCtx },\n { name: '$env', ctx: envVariableCtx },\n];\n```\n\n已废弃的兼容变量包括 `$date`、`$system`、`currentTime`，建议使用新版变量名替代。\n\n资料来源：[packages/core/client/src/variables/hooks/useBuiltinVariables.ts]()\n\n## 设计模式总结\n\n### 核心设计模式\n\n| 模式名称 | 应用场景 | 实现方式 |\n|----------|----------|----------|\n| 插件模式 | 功能扩展 | Plugin 基类 + PM 管理器 |\n| 配置驱动 | UI 生成 | Schema JSON 配置 |\n| 依赖注入 | 状态共享 | React Context Provider |\n| 观察者模式 | 事件通知 | 插件生命周期事件 |\n| 策略模式 | 流程节点 | FlowSettings components |\n| 工厂模式 | Schema 组件 | x-component 类型映射 |\n\n### 模块间通信\n\n```mermaid\nsequenceDiagram\n participant App as Application\n participant PM as Plugin Manager\n participant Plugin as Plugin\n participant Schema as SchemaComponent\n \n App->>PM: 注册插件\n PM->>Plugin: 实例化\n Plugin->>Plugin: load()\n Plugin->>Schema: 注册组件\n Schema->>Schema: 渲染界面\n```\n\n## 移动端适配\n\n系统通过 `DesktopMode` 组件实现移动端与桌面端的视图切换，当检测到非移动端设备访问移动端页面时，渲染桌面端适配组件。\n\n```tsx\n\n \n\n```\n\n## 系统信息与帮助\n\n`Help` 组件负责展示系统信息，包括版本号（`data?.data?.version`）、文档链接、许可证信息等。根据语言设置（`isSimplifiedChinese`）动态切换中英文文档地址。\n\n资料来源：[packages/core/client/src/user/Help.tsx]()\n\n---\n\n## 总结\n\nNocoBase 的系统架构围绕**插件化**和**配置驱动**两大核心理念构建，实现了高度的模块化和可扩展性。服务端通过 Plugin 基类实现功能模块化管理，客户端通过 Schema 配置实现界面的动态渲染，两者通过统一的插件管理器协调工作，形成一个完整的有机整体。\n\n---\n\n\n\n## 数据建模与集合管理\n\n### 相关页面\n\n相关主题：[外部数据源与多数据库支持](#external-data-sources), [权限系统与 ACL](#acl-permissions)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/database/src/collection.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/database/src/collection.ts)\n- [packages/core/database/src/field.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/database/src/field.ts)\n- [packages/core/database/src/repository.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/database/src/repository.ts)\n- [packages/plugins/@nocobase/plugin-data-source-manager](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-data-source-manager)\n- [packages/core/client/src/collection-manager/Configuration/components/Summary.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/collection-manager/Configuration/components/Summary.tsx)\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\n# 数据建模与集合管理\n\n## 概述\n\nNocoBase 的数据建模与集合管理模块是整个平台的核心基础设施，负责定义数据结构、管理数据关系、提供数据访问接口。该模块采用面向集合（Collection）的数据建模范式，支持多数据源管理，并提供了完整的 CRUD 操作能力。\n\n数据建模系统的主要职责包括：\n\n- **集合定义**：定义数据集合的结构、字段和约束\n- **字段管理**：支持多种字段类型和数据验证规则\n- **数据访问**：通过 Repository 模式提供统一的数据操作接口\n- **多数据源**：支持连接不同类型的数据源（主数据库、远程服务等）\n- **Schema 管理**：将数据模型与前端 Schema 绑定，实现 UI 联动\n\n资料来源：[packages/core/database/src/collection.ts]()\n\n## 核心概念\n\n### 集合（Collection）\n\n集合是 NocoBase 中数据组织的基本单元，类似于传统数据库中的表概念。每个集合包含以下关键属性：\n\n| 属性 | 说明 | 类型 |\n|------|------|------|\n| name | 集合名称，唯一标识 | string |\n| fields | 字段定义数组 | Field[] |\n| title | 显示名称 | string |\n| description | 描述信息 | string |\n| filterTargetKey | 过滤目标键 | string |\n| treeCollection | 是否为树形结构 | boolean |\n\n集合通过 Database 实例进行注册和管理，支持热插拔式的数据模型变更。\n\n### 字段（Field）\n\n字段是集合中的数据列定义，支持多种数据类型：\n\n- **普通字段**：字符串、数字、布尔值、日期等\n- **关系字段**：belongsTo、hasOne、hasMany、belongsToMany\n- **特殊字段**：json、radio、checkbox、sequence 等\n\n资料来源：[packages/core/database/src/field.ts]()\n\n## 架构设计\n\n```mermaid\ngraph TD\n A[数据建模层] --> B[CollectionManager]\n A --> C[数据源管理器]\n B --> D[Collection 集合]\n D --> E[Field 字段]\n D --> F[Repository 数据访问]\n C --> G[主数据源]\n C --> H[远程数据源]\n G --> I[MySQL/PostgreSQL/SQLite]\n H --> J[外部 API]\n```\n\n### 层次结构\n\nNocoBase 数据建模系统分为三个主要层次：\n\n1. **Schema 层**：定义数据结构的元信息\n2. **Collection 层**：将 Schema 实例化为可操作的集合\n3. **Repository 层**：提供数据访问的抽象接口\n\n```mermaid\nclassDiagram\n class Collection {\n +name: string\n +fields: Field[]\n +repository: Repository\n +create(data)\n +update(id, data)\n +delete(id)\n +find(params)\n }\n \n class Field {\n +name: string\n +type: string\n +options: object\n +validate(data)\n }\n \n class Repository {\n +create(data)\n +find(params)\n +update(id, data)\n +destroy(id)\n +count(params)\n }\n \n class Database {\n +registerCollections()\n +getCollection(name)\n }\n \n Collection \"1\" --> \"*\" Field : contains\n Collection --> Repository\n Database --> Collection : manages\n```\n\n资料来源：[packages/core/database/src/collection.ts:1-100]()\n\n## 集合管理\n\n### CollectionManager\n\nCollectionManager 是集合管理的核心类，负责维护所有已注册的集合实例：\n\n```typescript\n// 伪代码示例\nclass CollectionManager {\n collections: Map;\n \n getCollection(name: string): Collection;\n registerCollection(collection: Collection): void;\n removeCollection(name: string): void;\n getCollections(options?: FilterOptions): Collection[];\n}\n```\n\n### 集合注册流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户/开发者\n participant DB as Database\n participant CM as CollectionManager\n participant Col as Collection\n \n User->>DB: registerCollection(config)\n DB->>CM: addCollection(name, config)\n CM->>Col: new Collection(config)\n Col->>Col: parse fields\n Col->>Col: create repository\n CM->>DB: collection registered\n DB-->>User: success\n```\n\n资料来源：[packages/core/database/src/collection.ts]()\n\n### 集合配置组件\n\n在前端，集合配置通过 Summary 组件展示：\n\n```tsx\nconst Summary: React.FC = ({ label, schema }) => {\n // 展示集合配置的摘要信息\n return (\n
\n
\n {label}: {compile(schema.title)}\n
\n {schema.description &&
{compile(schema.description)}
}\n
\n );\n};\n```\n\n该组件负责渲染集合的名称和描述信息，支持国际化配置。\n\n资料来源：[packages/core/client/src/collection-manager/Configuration/components/Summary.tsx]()\n\n## 字段系统\n\n### 字段类型\n\nNocoBase 支持丰富的字段类型，定义在 field.ts 中：\n\n| 类型 | 说明 | 适用场景 |\n|------|------|----------|\n| string | 字符串 | 文本输入 |\n| integer | 整数 | 数量、ID |\n| bigInt | 大整数 | 雪花ID |\n| float/double | 浮点数 | 金额 |\n| boolean | 布尔值 | 开关状态 |\n| date/datetime | 日期/时间 | 时间记录 |\n| json | JSON 对象 | 复杂数据结构 |\n| belongsTo | 一对一关联 | 用户-角色 |\n| hasMany | 一对多关联 | 帖子-评论 |\n| belongsToMany | 多对多关联 | 用户-权限 |\n\n### 字段定义\n\n```typescript\ninterface FieldOptions {\n type: string;\n name: string;\n title?: string;\n description?: string;\n defaultValue?: any;\n uiSchema?: object;\n validation?: ValidationRule[];\n unique?: boolean;\n allowNull?: boolean;\n primaryKey?: boolean;\n}\n```\n\n字段支持级联配置，包括验证规则、默认值、UI 组件绑定等。\n\n资料来源：[packages/core/database/src/field.ts]()\n\n## Repository 数据访问层\n\n### Repository 模式\n\nRepository 提供统一的数据访问接口，封装了底层数据库操作：\n\n```typescript\ninterface IRepository {\n // 创建\n create(data: object, options?: CreateOptions): Promise;\n createMany(data: object[], options?: CreateOptions): Promise;\n \n // 查询\n find(params: FindParams): Promise;\n findOne(params: FindParams): Promise;\n findById(id: any): Promise;\n count(params?: FilterParams): Promise;\n \n // 更新\n update(params: UpdateParams): Promise;\n updateById(id: any, data: object): Promise;\n \n // 删除\n destroy(params: FilterParams): Promise;\n destroyById(id: any): Promise;\n \n // 关联操作\n add(field: string, id: any, relatedIds: any[]): Promise;\n set(field: string, id: any, relatedIds: any[]): Promise;\n remove(field: string, id: any, relatedIds: any[]): Promise;\n}\n```\n\n### 查询构建器\n\nRepository 内置强大的查询构建能力：\n\n```typescript\n// 基础查询\nrepository.find({\n filter: { status: 'active' },\n fields: ['id', 'name'],\n sort: ['createdAt'],\n page: 1,\n pageSize: 20\n});\n\n// 关联查询\nrepository.find({\n filter: { 'profile.nickname.$contains': 'admin' },\n appends: ['profile']\n});\n```\n\n资料来源：[packages/core/database/src/repository.ts]()\n\n## 数据源管理\n\n### 数据源管理器插件\n\nplugin-data-source-manager 负责管理多数据源连接：\n\n```mermaid\ngraph LR\n A[应用层] --> B[数据源管理器]\n B --> C[主数据源
Main Database]\n B --> D[远程数据源
Remote Data Source]\n B --> E[第三方服务]\n \n C --> F[MySQL/PostgreSQL]\n D --> G[REST API]\n D --> H[GraphQL]\n```\n\n### 数据源配置\n\n| 配置项 | 说明 | 示例 |\n|--------|------|------|\n| name | 数据源名称 | 'main' |\n| type | 数据源类型 | 'mysql' |\n| host | 主机地址 | 'localhost' |\n| port | 端口号 | 3306 |\n| database | 数据库名 | 'nocobase' |\n| username | 用户名 | 'root' |\n\n### 数据源隔离\n\nNocoBase 支持逻辑隔离的数据源架构，每个数据源可以：\n\n- 拥有独立的连接池\n- 使用不同的数据库引擎\n- 配置独立的迁移策略\n- 实现独立的缓存策略\n\n## Schema 集成\n\n### Schema 与集合绑定\n\n数据模型通过 Schema 与前端组件绑定：\n\n```typescript\nconst schema = {\n type: 'object',\n 'x-collection': 'users',\n properties: {\n name: {\n type: 'string',\n 'x-field': 'name'\n },\n email: {\n type: 'string',\n 'x-field': 'email'\n }\n }\n};\n```\n\n### Schema 初始化器\n\nSchema 初始化器提供了动态插入 Schema 的能力：\n\n```typescript\n// 插入 Schema 配置\nconst initializerConfig = {\n title: 'Form Item',\n type: 'object',\n 'x-component': 'FormItem',\n properties: {\n field1: {\n type: 'string',\n 'x-component': 'Input'\n }\n }\n};\n```\n\n支持动态显示/隐藏、动态加载子节点等高级功能。\n\n资料来源：[packages/core/client/src/schema-initializer/index.md]()\n\n## 内置变量与上下文\n\n### 变量系统\n\n数据模型支持在运行时使用内置变量：\n\n```typescript\nconst builtinVariables = [\n { name: '$nDate', ctx: datetimeCtx },\n { name: '$nExactDate', ctx: exactDateTimeCtx },\n { name: '$nRole', ctx: currentRoleCtx },\n { name: '$nUser', ctx: currentUserCtx },\n { name: '$nUrlSearchParams', ctx: urlSearchParamsCtx }\n];\n```\n\n### 上下文变量\n\n| 变量名 | 说明 | 返回值 |\n|--------|------|--------|\n| $nDate | 当前日期时间 | ISO 8601 格式 |\n| $nExactDate | 精确时间戳 | 带毫秒 |\n| $nRole | 当前用户角色 | 角色对象 |\n| $nUser | 当前用户信息 | 用户对象 |\n| $nUrlSearchParams | URL 参数 | 参数对象 |\n\n资料来源：[packages/core/client/src/variables/hooks/useBuiltinVariables.ts]()\n\n## 工作流程\n\n### 数据操作完整流程\n\n```mermaid\ngraph TD\n A[前端请求] --> B[Schema 验证]\n B --> C{请求类型}\n C -->|Create| D[数据验证]\n C -->|Read| E[查询构建]\n C -->|Update| F[变更检测]\n C -->|Delete| G[软删除检查]\n \n D --> H[事务开始]\n E --> I[Repository.find]\n F --> H\n G --> H\n \n H --> J[数据库操作]\n J --> K[事务提交]\n K --> L[返回结果]\n \n I --> L\n```\n\n### 集合管理器初始化流程\n\n```mermaid\nsequenceDiagram\n participant App as 应用启动\n participant DB as Database\n participant CM as CollectionManager\n participant Plugin as 插件加载\n \n App->>DB: initialize()\n DB->>CM: 创建实例\n CM->>Plugin: 加载数据源插件\n Plugin->>CM: registerCollection()\n CM->>CM: 创建 Collection 实例\n CM->>CM: 解析字段定义\n CM->>CM: 创建 Repository\n Plugin-->>DB: 注册完成\n DB-->>App: 数据库就绪\n```\n\n## 最佳实践\n\n### 集合命名规范\n\n- 使用小写字母和下划线：`user_profiles`\n- 避免使用保留字：`order`, `user`, `group`\n- 使用单数名词：`user` 而非 `users`\n- 有意义的名称：`order_items` 而非 `oi`\n\n### 字段设计建议\n\n1. **主键设计**：每个集合应定义主键字段\n2. **时间戳**：建议包含 `createdAt` 和 `updatedAt` 字段\n3. **软删除**：使用 `deletedAt` 而非物理删除\n4. **索引**：频繁查询字段添加索引配置\n\n### 关系设计原则\n\n```typescript\n// 一对多关系示例\nconst postCollection = {\n name: 'posts',\n fields: [\n { type: 'string', name: 'title' },\n { \n type: 'hasMany', \n name: 'comments',\n foreignKey: 'postId'\n }\n ]\n};\n\n// 评论表定义\nconst commentCollection = {\n name: 'comments',\n fields: [\n { type: 'string', name: 'content' },\n { type: 'integer', name: 'postId' },\n { \n type: 'belongsTo', \n name: 'post',\n foreignKey: 'postId'\n }\n ]\n};\n```\n\n## 总结\n\nNocoBase 的数据建模与集合管理系统提供了完整的数据建模解决方案：\n\n1. **灵活的集合定义**：支持多种字段类型和复杂的数据结构\n2. **强大的数据访问**：通过 Repository 模式提供统一的 CRUD 接口\n3. **多数据源支持**：可连接多种类型的数据库和外部服务\n4. **Schema 驱动**：与前端组件无缝集成，实现数据与 UI 联动\n5. **变量系统**：运行时支持丰富的上下文变量\n\n该系统设计遵循低耦合、高内聚的原则，便于扩展和维护，是 NocoBase 作为无代码平台的核心支撑模块。\n\n---\n\n\n\n## 外部数据源与多数据库支持\n\n### 相关页面\n\n相关主题：[数据建模与集合管理](#data-modeling), [系统架构与设计模式](#system-architecture)\n\n# 外部数据源与多数据库支持\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/plugins/@nocobase/plugin-data-source-external-mysql](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-data-source-external-mysql)\n- [packages/plugins/@nocobase/plugin-data-source-external-postgres](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-data-source-external-postgres)\n- [packages/plugins/@nocobase/plugin-data-source-external-mariadb](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-data-source-external-mariadb)\n- [packages/plugins/@nocobase/plugin-collection-fdw](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-collection-fdw)\n
\n\n> **说明**：当前检索到的上下文信息中，未包含上述外部数据源插件的详细源码实现内容。以下内容基于 NocoBase 核心代码库中与多数据源相关的公开信息进行整理。\n\n---\n\n## 概述\n\nNocoBase 采用**数据模型驱动**的架构设计，而非传统的表单或表格驱动方式。这种设计模式将数据结构与用户界面完全解耦，使得系统能够同时支持主数据库、外部数据库以及第三方 API 作为数据来源。\n\n资料来源：[README.md](https://github.com/nocobase/nocobase/blob/main/README.md)\n\n## 核心特性\n\n### 数据源类型支持\n\nNocoBase 的多数据库支持涵盖以下数据源类型：\n\n| 数据源类型 | 说明 | 支持状态 |\n|-----------|------|---------|\n| 主数据库 | 系统内置的主数据存储 | 完整支持 |\n| MySQL | 外部 MySQL 数据库连接 | 插件支持 |\n| PostgreSQL | 外部 PostgreSQL 数据库连接 | 插件支持 |\n| MariaDB | 外部 MariaDB 数据库连接 | 插件支持 |\n| 第三方 API | REST API 作为数据来源 | 插件支持 |\n\n### 数据库标识符引用规则\n\n不同数据库引擎对 SQL 标识符（如表名、字段名）的引用规则存在差异。NocoBase 在生成 SQL 语句时会根据数据源类型自动应用正确的引用规则。\n\n```ts\n/**\n * 标识符引用规则根据数据源类型确定\n * - MySQL 使用反引号 (`)\n * - PostgreSQL 使用双引号 (\")\n * - SQLite 使用双引号 (\")\n */\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/ai-employees/prompts.ts](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai/src/server/ai-employees/prompts.ts)\n\n### 环境配置参数\n\nAI 代理在处理数据库操作时会参考以下环境配置：\n\n- **main_database**: 主数据库引擎类型，影响 SQL 语法和标识符引用方式\n- **locale**: 通信语言和地区格式化设置\n- **quotingRules**: 不同数据源的 SQL 标识符引用规则\n\n## 插件体系架构\n\n外部数据源功能通过独立的插件实现，便于按需加载和维护：\n\n```mermaid\ngraph TD\n A[NocoBase 核心] --> B[plugin-data-source-external-mysql]\n A --> C[plugin-data-source-external-postgres]\n A --> D[plugin-data-source-external-mariadb]\n A --> E[plugin-collection-fdw]\n \n B --> F[MySQL 连接器]\n C --> G[PostgreSQL 连接器]\n D --> H[MariaDB 连接器]\n E --> I[联邦集合支持]\n```\n\n### 插件列表\n\n| 插件名称 | 功能描述 | 数据源类型 |\n|---------|---------|-----------|\n| plugin-data-source-external-mysql | MySQL 外部数据源连接 | MySQL |\n| plugin-data-source-external-postgres | PostgreSQL 外部数据源连接 | PostgreSQL |\n| plugin-data-source-external-mariadb | MariaDB 外部数据源连接 | MariaDB |\n| plugin-collection-fdw | 外部数据封装器支持 | 多类型 |\n\n## 数据源管理界面\n\nNocoBase 提供了插件详情管理界面，支持查看和管理已安装数据源插件：\n\n### 插件信息展示\n\n在插件详情页面中，可查看以下关键信息：\n\n| 字段 | 说明 |\n|-----|------|\n| PackageName | 插件包名称 |\n| Version | 当前版本号 |\n| Description | 插件描述 |\n| Author | 作者信息 |\n| License | 开源许可证 |\n| Homepage | 项目主页 |\n| Repository | 代码仓库地址 |\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### 依赖兼容性检查\n\n插件管理界面包含依赖兼容性验证功能：\n\n- 验证 `dist/externalVersion.js` 文件是否存在\n- 检查插件依赖版本是否满足要求\n- 在依赖不兼容时显示警告信息\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\n### 统一数据管理\n\n通过外部数据源功能，用户可以在 NocoBase 平台上：\n\n1. **连接现有数据库** - 无需迁移数据，直接连接已有的 MySQL、PostgreSQL 或 MariaDB 数据库\n2. **跨库查询** - 在单一界面中操作来自不同数据库的数据\n3. **API 集成** - 将第三方 REST API 作为数据来源使用\n\n### 数据结构与界面分离\n\nNocoBase 的核心优势在于：\n\n- UI 和数据结构完全解耦\n- 可以为同一张表或记录创建任意数量和形式的区块和操作\n- 支持在同一系统中混合使用多种数据源\n\n## 相关文档\n\n- [官方文档](https://docs.nocobase.com/)\n- [在线演示](https://demo.nocobase.com/new)\n- [用户案例](https://www.nocobase.com/en/blog/tags/customer-stories)\n\n---\n\n> **注意**：如需获取特定数据源插件的详细技术实现，建议查阅各插件目录下的源代码文件，或参考官方技术文档。\n\n---\n\n\n\n## 权限系统与 ACL\n\n### 相关页面\n\n相关主题：[数据建模与集合管理](#data-modeling)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/client/src/application/hooks/useAclSnippets.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/application/hooks/useAclSnippets.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/core/client/src/pm/PluginDetail.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginDetail.tsx)\n- [packages/plugins/@nocobase/plugin-acl](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-acl)\n- [packages/core/server/src/acl/acl.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/server/src/acl/acl.ts)\n- [packages/core/server/src/acl/role.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/server/src/acl/role.ts)\n
\n\n# 权限系统与 ACL\n\n## 概述\n\nNocoBase 的权限系统基于 **ACL（Access Control List，访问控制列表）** 机制实现。该系统采用角色（Role）和资源（Resource）两层的权限管理模式，支持细粒度的操作级别控制。权限系统贯穿整个应用，从服务端到客户端均有完整的权限校验链路，确保数据安全和操作合规。\n\n## 核心概念\n\n| 概念 | 说明 |\n|------|------|\n| **角色（Role）** | 一组权限的集合，用户通过关联角色获得相应权限 |\n| **资源（Resource）** | 需要被保护的实体，如数据表、字段、插件等 |\n| **操作（Action）** | 对资源的具体操作，如 view、create、update、delete |\n| **Snippet** | 权限片段，用于灵活组合和管理权限规则 |\n\n资料来源：[packages/core/server/src/acl/role.ts:1-20]()\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[用户请求] --> B[ACL 中间件]\n B --> C{权限校验}\n C -->|通过| D[业务逻辑处理]\n C -->|拒绝| E[返回 403 错误]\n D --> F[数据响应]\n \n G[角色管理] --> H[角色权限配置]\n H --> I[Snippet 定义]\n I --> C\n```\n\n### 服务端架构\n\n服务端 ACL 模块位于 `packages/core/server/src/acl/` 目录，包含以下核心组件：\n\n- **ACL 类**：权限系统的核心管理器，负责加载权限规则、执行权限校验\n- **Role 类**：角色实体，封装角色的权限配置信息\n- **中间件**：拦截请求并进行权限验证\n\n```mermaid\ngraph LR\n A[Request] --> B[ACL Middleware]\n B --> C[ACL Manager]\n C --> D[Role Manager]\n D --> E[Snippet Matcher]\n E --> F{Permission Check}\n F -->|Match| G[Allow]\n F -->|No Match| H[Deny]\n```\n\n资料来源：[packages/core/server/src/acl/acl.ts:1-30]()\n\n### 客户端架构\n\n客户端通过 React Context 提供 ACL 上下文，使用 Hook 方式暴露权限判断能力：\n\n```tsx\n// ACL Provider 提供全局上下文\n\n \n\n\n// 子组件中使用权限 Hook\nconst { allow, snippets } = useACLRoleContext();\n```\n\n资料来源：[packages/core/client/src/application/hooks/useAclSnippets.ts:10-20]()\n\n## 角色与权限\n\n### 角色定义\n\n角色是权限管理的基本单位，每个角色包含以下属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| name | string | 角色标识名称 |\n| title | string | 角色显示名称 |\n| snippets | string[] | 权限片段列表 |\n| allowAll | boolean | 是否允许所有操作 |\n\n资料来源：[packages/core/server/src/acl/role.ts:20-40]()\n\n### 预定义内置变量\n\nNocoBase 在权限上下文中注入了多个内置变量，用于权限判断和动态规则：\n\n| 变量名 | 说明 | 用途 |\n|--------|------|------|\n| `$nRole` | 当前角色 | 获取当前用户的角色信息 |\n| `$nUser` | 当前用户 | 获取当前登录用户信息 |\n| `$nDate` | 当前日期 | 日期相关的权限条件 |\n| `$nExactDate` | 精确当前时间 | 时间戳相关的权限条件 |\n| `$nenv` | 环境变量 | 服务器环境变量访问 |\n\n资料来源：[packages/core/client/src/variables/hooks/useBuiltinVariables.ts:20-50]()\n\n### Snippet 匹配机制\n\n系统使用 `ignore` 库实现 Snippet 的模式匹配，支持通配符和否定前缀：\n\n```typescript\nconst ig = ignore().add(snippets);\nconst appAllowed = allowAll || ig.ignores(aclSnippet);\n```\n\n匹配规则：\n- `allowAll` 为 `true` 时，跳过 Snippet 校验，直接放行\n- 使用 `ignore` 库的标准 glob 匹配规则\n- 支持 `!` 前缀表示显式拒绝\n\n资料来源：[packages/core/client/src/application/hooks/useAclSnippets.ts:12-18]()\n\n## 权限配置\n\n### Schema 中的权限声明\n\n在数据 Schema 中通过 `x-acl-action` 字段声明权限要求：\n\n```typescript\nconst schema: ISchema = {\n type: 'void',\n 'x-acl-action': 'collections:view', // 声明需要的权限\n 'x-decorator': 'DetailsBlockProvider',\n 'x-component': 'CardItem',\n};\n```\n\n资料来源：[packages/core/client/src/schema-initializer/utils.ts:15-25]()\n\n### 权限操作类型\n\n| 操作 | 说明 | 适用资源 |\n|------|------|----------|\n| `view` | 查看资源 | 表单、详情、列表 |\n| `create` | 创建新资源 | 表单、列表 |\n| `update` | 修改现有资源 | 表单、详情 |\n| `delete` | 删除资源 | 列表、操作按钮 |\n| `get` | 获取单个资源 | 详情块 |\n\n资料来源：[packages/core/client/src/schema-initializer/utils.ts:22-30]()\n\n## 插件系统集成\n\n### 插件兼容性检查\n\nNocoBase 的插件管理界面集成了 ACL 权限校验，插件详情页提供依赖兼容性检查功能：\n\n```tsx\n{\n key: 'dependencies',\n label: t('Dependencies compatibility check'),\n children: (\n <>\n \n \n ),\n}\n```\n\n资料来源：[packages/core/client/src/pm/PluginDetail.tsx:80-100]()\n\n### 插件权限声明\n\n插件可通过配置文件声明所需的权限：\n\n```json\n{\n \"name\": \"@nocobase/plugin-sample\",\n \"permissions\": [\n \"collections:view\",\n \"collections:create\",\n \"!system:admin\"\n ]\n}\n```\n\n## 工作流程\n\n### 权限校验流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Middleware as ACL 中间件\n participant ACL as ACL 管理器\n participant Role as 角色管理器\n participant Resource as 资源\n\n Client->>Middleware: 请求资源\n Middleware->>ACL: 发起权限校验\n ACL->>Role: 获取用户角色\n Role-->>ACL: 返回角色配置\n ACL->>ACL: 匹配 Snippet\n ACL-->>Middleware: 校验结果\n Middleware->>Resource: 允许/拒绝访问\n```\n\n### 客户端权限 Hook 使用\n\n```typescript\nimport { useAclSnippets } from '@nocobase/client';\n\nfunction MyComponent() {\n const { allow } = useAclSnippets();\n \n // 检查特定权限\n if (!allow('collections:view')) {\n return ;\n }\n \n return ;\n}\n```\n\n资料来源：[packages/core/client/src/application/hooks/useAclSnippets.ts:1-25]()\n\n## 最佳实践\n\n### 1. 合理设计角色\n\n建议采用最小权限原则，按业务职能划分角色：\n\n| 角色 | 权限范围 | 适用场景 |\n|------|----------|---------- |\n| admin | 所有权限 | 系统管理员 |\n| operator | 业务操作权限 | 普通业务人员 |\n| viewer | 仅查看权限 | 数据查看者 |\n\n### 2. 使用 Snippet 组合\n\n将常用权限组合定义为 Snippet，便于复用：\n\n```typescript\n// 定义 Snippet\nsnippets: [\n 'collections:view',\n 'collections:create',\n 'collections:update',\n]\n\n// 使用通配符\nsnippets: [\n 'collections:*', // 所有集合操作\n '!collections:delete' // 排除删除\n]\n```\n\n### 3. Schema 权限声明\n\n在开发插件或自定义页面时，应明确声明所需的权限：\n\n```typescript\nconst schema = {\n type: 'void',\n 'x-acl-action': `${collectionName}:view`,\n 'x-settings': 'settings:acl',\n};\n```\n\n## 相关配置\n\n### 环境变量\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `ACL_ENABLED` | 是否启用 ACL | `true` |\n| `ACL_DEFAULT_ROLE` | 默认角色 | `guest` |\n\n### 插件依赖\n\n权限系统作为核心插件 `@nocobase/plugin-acl` 提供，独立于业务插件存在：\n\n```\n@nocobase/plugin-acl\n├── server/src/acl/ # 服务端实现\n├── client/src/acl/ # 客户端实现\n└── index.ts # 插件入口\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-acl](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-acl)\n\n## 总结\n\nNocoBase 的权限系统采用成熟的 ACL 模型，通过角色、权限片段和资源操作的三层结构实现了灵活且强大的访问控制。系统支持服务端的中间件校验和客户端的上下文感知，两端协同确保权限策略的一致性和安全性。开发者应遵循最小权限原则，合理设计角色和 Snippet，在 Schema 中明确声明权限需求，以构建安全可靠的应用系统。\n\n---\n\n\n\n## 工作流引擎\n\n### 相关页面\n\n相关主题：[AI 集成与智能员工](#ai-integration), [界面构建器](#interface-builder)\n\n
\n相关源码文件\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- [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/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- [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
\n\n# 工作流引擎\n\n## 概述\n\nNocoBase 工作流引擎是一个强大的业务流程自动化模块，允许用户通过可视化画布设计、配置和管理自动化工作流程。工作流引擎支持在数据保存前后触发、执行队列任务、审批流程以及自定义操作事件，为业务系统提供灵活的自动化能力。\n\n工作流引擎的核心职责包括：\n\n- 提供可视化的流程设计画布\n- 管理流程节点的执行逻辑\n- 处理流程执行状态和历史记录\n- 支持条件分支和循环控制\n- 与系统各模块集成实现自动化触发\n\n资料来源：[packages/core/flow-engine/src/flowSettings.ts:1-50]()\n\n## 架构设计\n\n### 核心组件\n\n工作流引擎由多个核心组件构成，各组件协同完成流程设计、执行和监控功能。\n\n```mermaid\ngraph TD\n A[FlowSettings 配置面板] --> B[FlowModel 模型层]\n B --> C[FlowModelRenderer 渲染器]\n C --> D[CanvasContent 画布内容]\n D --> E[ExecutionCanvas 执行画布]\n \n F[FlowContext 上下文] --> B\n G[节点组件] --> D\n H[任务队列] --> E\n```\n\n### 目录结构\n\n工作流引擎主要代码分布在以下位置：\n\n| 层级 | 路径 | 说明 |\n|------|------|------|\n| 核心引擎 | `packages/core/flow-engine/` | 流程引擎核心逻辑和组件 |\n| 工作流插件 | `packages/plugins/@nocobase/plugin-workflow/` | 工作流可视化设计和执行 |\n| 审批插件 | `packages/plugins/@nocobase/plugin-workflow-approval/` | 审批流程支持 |\n| 请求插件 | `packages/plugins/@nocobase/plugin-workflow-request/` | HTTP 请求节点支持 |\n\n资料来源：[packages/core/flow-engine/src/components/FlowModelRenderer.tsx:1-30]()\n\n## FlowSettings 配置系统\n\n`FlowSettings` 是工作流引擎的配置管理核心类，负责注册和管理流程相关的 UI 组件和作用域。\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### 配置属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `components` | `Record` | 注册的流程组件集合 |\n| `scopes` | `Record` | 流程作用域配置 |\n| `antdComponentsLoaded` | `boolean` | Antd 组件加载状态 |\n| `enabled` | `boolean` | 流程启用状态 |\n| `#forceEnabled` | `boolean` | 强制启用覆盖状态 |\n\n### 底部栏配置\n\nFlowSettings 支持通过 `footer` 属性自定义底部操作栏的展示形式：\n\n```typescript\n// 1. 静态自定义 - 直接替换\nfooter:
自定义底部内容
\n\n// 2. 包裹式自定义 - 在原节点基础上添加内容\nfooter: (originNode, { OkBtn, CancelBtn }) => (\n
\n Additional info\n {originNode}\n
\n)\n\n// 3. 函数式自定义 - 完全重新组合按钮\nfooter: (originNode, { OkBtn, CancelBtn }) => (\n \n \n \n \n \n)\n\n// 4. 隐藏底部\nfooter: null\n```\n\n资料来源：[packages/core/flow-engine/src/flowSettings.ts:1-80]()\n\n## 流程渲染器\n\n### FlowModelRenderer\n\n`FlowModelRenderer` 是核心的流程模型渲染组件，负责将流程模型渲染为可视化的流程配置界面。\n\n```typescript\nexport const FlowModelRenderer: React.FC = React.memo((props) => {\n // 构建渲染内容：统一在渲染前触发 beforeRender 事件（带缓存）\n const content = (\n \n );\n\n // 当需要错误回退时，将整体包裹在 ErrorBoundary 和 FlowModelProvider 中\n if (showErrorFallback) {\n return (\n \n {content}\n \n );\n }\n\n return content;\n});\n```\n\n### MemoFlowModelRenderer\n\n对于需要优化渲染性能的场景，引擎提供了 `MemoFlowModelRenderer` 包装版本，仅在父级重渲且 props 浅比较未变时跳过渲染，不影响内部响应式更新。\n\n```typescript\nexport const MemoFlowModelRenderer = React.memo(FlowModelRenderer);\nMemoFlowModelRenderer.displayName = 'MemoFlowModelRenderer';\n```\n\n### Props 配置\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `model` | `Model` | 流程数据模型 |\n| `showFlowSettings` | `boolean` | 是否显示流程设置 |\n| `flowSettingsVariant` | `string` | 设置面板变体 |\n| `hideRemoveInSettings` | `boolean` | 在设置中隐藏删除按钮 |\n| `showTitle` | `boolean` | 是否显示标题 |\n| `inputArgs` | `any[]` | 输入参数列表 |\n| `showErrorFallback` | `boolean` | 是否显示错误回退 |\n| `settingsMenuLevel` | `'first' \\| 'second'` | 设置菜单层级 |\n| `extraToolbarItems` | `ReactNode` | 额外工具栏项 |\n| `fallback` | `ComponentType` | 自定义回退组件 |\n| `useCache` | `boolean` | 是否启用缓存 |\n\n资料来源：[packages/core/flow-engine/src/components/FlowModelRenderer.tsx:1-100]()\n\n## 执行上下文\n\n### FlowContext\n\n`FlowContext` 提供流程执行时的运行时上下文，贯穿整个流程执行生命周期。\n\n```typescript\n\n {children}\n\n```\n\n### 上下文属性\n\n| 属性 | 说明 |\n|------|------|\n| `workflow` | 当前执行的流程对象 |\n| `nodes` | 流程节点配置列表 |\n| `execution` | 执行实例信息 |\n| `viewJob` | 当前查看的任务节点 |\n| `setViewJob` | 设置查看任务的方法 |\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx:1-60]()\n\n## 可视化画布\n\n### CanvasContent\n\n画布内容组件负责渲染流程节点的可视化展示和交互。\n\n```typescript\n
\n \n
\n
\n
{lang('Start')}
\n {renderNodes(entry, nodes)}\n
{lang('End')}
\n
\n
\n \n {copiedNode ? (\n
\n
\n {lang('Copied node')}\n
\n
\n
{copiedTypeTitle}
\n
{copiedNode.title ?? copiedNode.type}
\n
\n
\n ) : null}\n
\n \n
\n
\n```\n\n### 画布功能\n\n| 功能 | 说明 |\n|------|------|\n| 节点渲染 | 渲染流程中的所有节点和连接线 |\n| 剪贴板预览 | 显示复制的节点信息 |\n| 缩放控制 | 支持 10%-100% 的画布缩放 |\n| 错误边界 | 捕获节点渲染中的错误 |\n\n### ExecutionCanvas 执行画布\n\n执行画布展示流程的实际执行状态和结果。\n\n```typescript\n{lang('Workflow')} },\n { title: {workflow.title} },\n { title: },\n ]}\n/>\n{compile(statusOption.label)}\n\n```\n\n### 执行状态展示\n\n| 元素 | 说明 |\n|------|------|\n| 面包屑导航 | 显示从流程列表到具体执行的路径 |\n| 状态标签 | 以颜色区分执行状态 |\n| 时间戳 | 显示最后更新时间 |\n| 取消按钮 | 可取消未完成的执行 |\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/client/CanvasContent.tsx:1-80]()\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx:1-70]()\n\n## 触发机制\n\n工作流支持多种触发方式，满足不同业务场景的自动化需求。\n\n```mermaid\ngraph LR\n A[数据保存] --> B[触发前 Pre-Action]\n A --> C[触发后 Post-Action]\n D[按钮点击] --> E[自定义事件]\n F[定时任务] --> G[队列执行]\n```\n\n### 触发类型\n\n| 触发类型 | 说明 | 支持模式 |\n|----------|------|----------|\n| 保存后触发 | 数据保存成功后自动执行 | 本地模式 |\n| 提交后触发 | 表单提交成功后执行 | 全模式 |\n| 删除前触发 | 数据删除前执行（仅本地模式） | 本地模式 |\n| 按钮点击 | 点击按钮直接触发 | 自定义事件 |\n| 后台队列 | 作为排队任务后台执行 | 全模式 |\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/locale/ko-KR.json:1-50]()\n\n## 国际化支持\n\n工作流引擎内置多语言支持，核心翻译键值如下：\n\n| 键值 | 中文 | 英文 |\n|------|------|------|\n| `Workflow` | 工作流 | 工作流 |\n| `Workflow tasks` | 工作流任务 | 工作流任务 |\n| `Workflow todos` | 工作流待办 | 工作流待办 |\n| `View result` | 查看结果 | 查看结果 |\n| `Workflow executed` | 工作流已执行 | 工作流已执行 |\n| `Execution status` | 执行状态 | 执行状态 |\n\n资料来源：[packages/plugins/@nocobase/plugin-workflow/src/locale/ko-KR.json:50-100]()\n\n## 相关插件\n\n### plugin-workflow\n\n基础工作流插件，提供核心的流程设计、执行和管理功能。\n\n- 可视化流程画布设计\n- 节点配置和管理\n- 执行历史记录\n- 流程复制和粘贴\n\n### plugin-workflow-approval\n\n审批流程插件，扩展工作流引擎支持审批业务场景。\n\n- 审批节点类型\n- 审批人指定\n- 审批意见记录\n\n### plugin-workflow-request\n\nHTTP 请求插件，支持在工作流中发起外部 API 调用。\n\n- HTTP 请求节点\n- 响应数据处理\n- 错误处理机制\n\n## 最佳实践\n\n### 性能优化\n\n1. **使用 MemoFlowModelRenderer**：在父组件频繁重渲但实际数据未变的场景，使用 Memo 版本避免不必要的重渲\n2. **合理设置 useCache**：启用缓存可减少重复计算，但需注意数据一致性问题\n3. **showErrorFallback 策略**：在复杂节点场景启用错误边界，避免单个节点错误导致整个流程崩溃\n\n### 错误处理\n\n1. **ErrorBoundary 包装**：确保节点渲染错误被正确捕获\n2. **FlowErrorFallback 自定义**：根据业务需求提供友好的错误展示\n3. **FlowModelProvider 上下文**：在错误回退中仍可获取模型上下文进行恢复操作\n\n## 总结\n\nNocoBase 工作流引擎采用模块化设计，通过 FlowSettings 配置系统、FlowModelRenderer 渲染器、CanvasContent 画布和 ExecutionCanvas 执行画布等核心组件，为业务系统提供了完整的流程自动化能力。引擎支持多种触发机制、可视化设计和执行监控，结合审批和请求等扩展插件，能够满足复杂业务场景的流程自动化需求。\n\n---\n\n\n\n## AI 集成与智能员工\n\n### 相关页面\n\n相关主题：[工作流引擎](#workflow-engine), [权限系统与 ACL](#acl-permissions)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/plugins/@nocobase/plugin-ai](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai) - 插件源码未在当前上下文提供\n- [packages/plugins/@nocobase/plugin-ai-knowledge-base](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai-knowledge-base) - 插件源码未在当前上下文提供\n- [docs/docs/cn/ai-employees/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/cn/ai-employees/index.md) - 文档源码未在当前上下文提供\n- [docs/docs/cn/ai-employees/knowledge-base/rag.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/cn/ai-employees/knowledge-base/rag.md) - 文档源码未在当前上下文提供\n
\n\n# AI 集成与智能员工\n\n## 概述\n\n根据当前检索到的上下文信息，未能获取到 AI 插件和智能员工相关的具体源码文件。以下信息基于 NocoBase 仓库中可访问的通用架构和功能模块进行说明。\n\n### 当前可访问的上下文信息\n\n从仓库中检索到的相关文件主要包括：\n\n| 文件路径 | 说明 |\n|---------|------|\n| `packages/core/client/src/user/Help.tsx` | 用户帮助菜单，集成外部文档链接 |\n| `packages/core/client/src/pm/PluginDetail.tsx` | 插件详情管理组件 |\n| `packages/core/client/src/variables/hooks/useBuiltinVariables.ts` | 内置变量系统（含日期、用户、URL参数等） |\n| `README.md` | 项目主文档，提及 AI Agent Access 功能 |\n| `packages/core/flow-engine/src/flowSettings.ts` | 流程引擎配置系统 |\n\n## AI 集成架构\n\n根据项目 README 中的描述，NocoBase 是一个开源的 AI + No-Code 平台，用于快速构建业务系统。AI 功能建立在经过生产验证的基础设施和所见即所得的 No-Code 界面上。\n\n> Coding agents get a... (文档内容在此处截断)\n\n## 变量系统与 AI 上下文\n\nNocoBase 的内置变量系统为 AI 集成提供了上下文数据支持：\n\n```typescript\n// 资料来源：packages/core/client/src/variables/hooks/useBuiltinVariables.ts:1-100\n\nconst builtinVariables = [\n {\n name: '$date',\n ctx: datetimeCtx, // 日期时间上下文\n },\n {\n name: '$nExactDate',\n ctx: exactDateTimeCtx, // 精确日期时间\n },\n {\n name: '$system',\n ctx: {\n now: () => dayjs().toISOString(),\n },\n },\n {\n name: 'currentTime',\n ctx: () => dayjs().toISOString(),\n },\n {\n name: urlSearchParamsName,\n ctx: urlSearchParamsCtx,\n defaultValue,\n },\n];\n```\n\n| 变量名称 | 用途 | 状态 |\n|---------|------|------|\n| `$date` | 当前日期时间 | 已弃用 |\n| `$nExactDate` | 精确日期时间 | 活跃 |\n| `$system` | 系统信息（含 now 方法） | 已弃用 |\n| `currentTime` | 当前时间戳 | 已弃用 |\n| URL 参数变量 | 动态 URL 参数 | 活跃 |\n\n## 文档资源链接\n\n根据 Help 组件配置，NocoBase 提供了以下官方文档资源：\n\n| 资源类型 | 简体中文链接 | 英文链接 |\n|---------|-------------|---------|\n| 官网首页 | https://www.nocobase.com/cn/ | https://www.nocobase.com |\n| 用户手册 | https://v2.docs.nocobase.com/cn/guide/ | https://v2.docs.nocobase.com/guide/ |\n\n> 资料来源：packages/core/client/src/user/Help.tsx:1-60\n\n## 流程引擎配置\n\nAI 智能员工的执行逻辑可能通过流程引擎实现。当前可访问的流程配置支持自定义底部按钮：\n\n```typescript\n// 资料来源：packages/core/flow-engine/src/flowSettings.ts:1-50\n\ninterface FlowSettingsConfig {\n footer?:\n | React.ReactNode\n | ((originNode: React.ReactNode, extra: { OkBtn: React.FC; CancelBtn: React.FC }) => React.ReactNode)\n | null;\n [key: string]: any;\n}\n```\n\n## 插件系统\n\nNocoBase 的插件管理器支持查看插件详情，包括依赖兼容性检查：\n\n> 资料来源：packages/core/client/src/pm/PluginDetail.tsx:1-100\n\n| 检查项 | 说明 |\n|-------|------|\n| 包名称 | 插件的唯一标识符 |\n| 版本号 | 当前安装的版本 |\n| 依赖兼容性 | 检查 `dist/externalVersion.js` 是否存在 |\n| 许可证 | 开源许可证类型 |\n\n## 注意事项\n\n**当前页面内容不完整**\n\n由于以下关键源码文件未在当前检索上下文中提供，无法生成详细的 AI 集成与智能员工技术文档：\n\n1. `packages/plugins/@nocobase/plugin-ai` - AI 核心插件\n2. `packages/plugins/@nocobase/plugin-ai-knowledge-base` - AI 知识库插件\n3. `docs/docs/cn/ai-employees/index.md` - AI 员工文档首页\n4. `docs/docs/cn/ai-employees/knowledge-base/rag.md` - RAG 检索增强生成文档\n\n## 后续步骤\n\n如需完整的技术文档，请提供以下任一方式：\n\n1. **重新检索** - 请求检索上述缺失的 AI 相关源码文件\n2. **访问源码** - 直接访问 GitHub 仓库中的 AI 插件目录\n3. **访问文档** - 查看官方文档站点 https://docs.nocobase.com/\n\n---\n\n*本页面基于 NocoBase 仓库 v1.0+ 版本编写，部分内容因源码文件不可用而标记为待补充。*\n\n---\n\n\n\n## 界面构建器\n\n### 相关页面\n\n相关主题：[数据建模与集合管理](#data-modeling), [工作流引擎](#workflow-engine)\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- [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/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- [packages/core/client/src/pm/PluginDetail.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginDetail.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/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/mobile-layout/index.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-mobile/src/client/mobile-layout/index.md)\n
\n\n# 界面构建器\n\n## 概述\n\n界面构建器（Interface Builder）是 NocoBase 平台的核心模块之一，用于通过可视化的方式构建业务系统的用户界面。它基于 Schema 驱动的架构设计，允许用户通过声明式配置定义界面结构、数据源、交互行为等，而无需编写大量代码。\n\n界面构建器的核心理念是通过数据驱动的方式实现 UI 的声明式构建，所有界面配置都以 JSON Schema 格式存储在数据库中，支持运行时动态修改和渲染。\n\n## 核心架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[用户界面] --> B[Schema 配置]\n B --> C[Schema 解析器]\n C --> D[组件映射表]\n D --> E[React 组件]\n E --> A\n \n F[Schema 设置面板] --> B\n G[Schema 初始化器] --> B\n H[Schema 工具栏] --> B\n \n I[数据源配置] --> J[变量系统]\n J --> C\n```\n\n### 主要模块\n\n| 模块 | 功能 | 源码位置 |\n|------|------|----------|\n| Schema Settings | 界面属性的配置面板 | `packages/core/client/src/schema-settings/` |\n| Schema Initializer | 向 Schema 中动态插入新节点 | `packages/core/client/src/schema-initializer/` |\n| Schema Component | Schema 渲染的核心组件库 | `packages/core/client/src/schema-component/` |\n| Schema Toolbar | 工具栏，提供设计态操作入口 | `packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx` |\n| LinkageFilter | 联动规则的条件配置组件 | `packages/core/client/src/schema-component/antd/linkageFilter/` |\n\n## Schema 配置结构\n\n### Schema 基本结构\n\nSchema 是界面构建器的核心配置单元，采用 JSON Schema 格式定义界面的层级结构和属性。\n\n```typescript\n{\n type: 'string',\n 'x-decorator': 'FormItem',\n 'x-component': 'Input',\n 'x-component-props': {\n placeholder: '{{t(\"Please enter\")}}',\n },\n 'x-designable-bahavior': 'editable'\n}\n```\n\n### x-designable-bahavior 行为类型\n\n| 行为类型 | 说明 | 源码引用 |\n|----------|------|----------|\n| `editable` | 可切换 designable 状态 | `schema-component/index.md` |\n| `readonly` | 只读状态，不可切换 | `schema-component/index.md` |\n| `none` | 完全禁用设计态 | `schema-component/index.md` |\n\n资料来源：[schema-component/index.md:8-11]()\n\n## Schema 初始化器\n\nSchema 初始化器负责在设计时动态向 Schema 中插入新的节点或配置，是实现可视化配置的关键组件。\n\n### 功能特性\n\n- **动态可见性**：根据条件动态显示或隐藏配置项\n- **子节点动态加载**：支持按需加载子配置节点\n- **Schema 插入**：支持多种类型的 Schema 插入模式\n\n### 插入模式\n\n| 模式 | 说明 | 示例位置 |\n|------|------|----------|\n| Basic | 基础插入模式 | `demos/insert-schema-basic.tsx` |\n| Action | 动作类插入 | `demos/insert-schema-action.tsx` |\n| FormItem | 表单项插入 | `demos/insert-schema-form-item.tsx` |\n\n资料来源：[schema-initializer/index.md:12-20]()\n\n## Schema 设置面板\n\nSchema 设置面板提供配置界面的入口，允许用户修改 Schema 节点的各种属性。\n\n### GeneralSchemaDesigner 组件\n\n`GeneralSchemaDesigner` 是核心的 Schema 设计器组件，提供了完整的可视化编辑能力。\n\n```typescript\ninterface SchemaToolbarProps {\n title?: string | string[];\n showDataSource?: boolean;\n dataSource?: any;\n template?: boolean;\n draggable?: boolean;\n disableInitializer?: boolean;\n}\n```\n\n资料来源：[GeneralSchemaDesigner.tsx:145-153]()\n\n### 工具栏功能\n\n| 功能 | 说明 | 交互方式 |\n|------|------|----------|\n| 拖拽手柄 | 支持 Schema 节点拖拽排序 | `DragHandler` 组件 |\n| 初始化器 | 插入新的 Schema 节点 | `InitializerComponent` |\n| 设置下拉菜单 | 访问节点属性配置 | `SchemaSettingsDropdown` |\n| 数据源显示 | 显示当前节点所属数据源 | 标题区域 |\n\n资料来源：[GeneralSchemaDesigner.tsx:40-75]()\n\n### 标题渲染逻辑\n\n```typescript\n// 数据源和标题组合显示\n{dataSource ? `${compile(dataSource?.displayName)} > ${compile(title)}` : compile(title)}\n```\n\n## 组件类型系统\n\n### 内置组件类型\n\nNocoBase 提供了多种内置组件类型，可直接在 Schema 中引用：\n\n| 类型 | 用途 | 源码 |\n|------|------|------|\n| FormItem | 表单项装饰器 | 内置 |\n| Input | 文本输入 | antd |\n| Select | 下拉选择 | antd |\n| Markdown | Markdown 编辑器 | 自定义 |\n\n### LinkageFilter 组件\n\n`LinkageFilter` 用于前端联动规则的条件配置，支持变量、操作符的联动变化。\n\n```typescript\ntype FilterActionProps = ActionProps & {\n options?: any[];\n form?: Form;\n onSubmit?: (values: T) => void;\n onReset?: (values: T) => void;\n}\n```\n\n资料来源：[linkageFilter/index.md:7-13]()\n\n## 变量系统\n\n### 内置变量\n\n界面构建器支持丰富的内置变量，用于在配置中引用运行时数据：\n\n| 变量名 | 说明 | 类型 |\n|--------|------|------|\n| `$nDate` | 当前日期时间 | ISO 8601 格式 |\n| `$nExactDate` | 精确时间戳 | ISO 8601 格式 |\n| `$date` | 日期（已废弃） | 兼容性支持 |\n| `$system` | 系统变量（已废弃） | 兼容性支持 |\n| `$urlSearchParams` | URL 查询参数 | 对象 |\n| `currentTime` | 当前时间（已废弃） | 兼容性支持 |\n\n资料来源：[useBuiltinVariables.ts:30-70]()\n\n### 变量上下文结构\n\n```typescript\n{\n name: '$nDate',\n ctx: () => dayjs().toISOString(),\n defaultValue?: any\n}\n```\n\n## 流程设置集成\n\n界面构建器与流程引擎深度集成，支持在配置面板中嵌入流程节点设置。\n\n### FlowSettings 配置结构\n\n```typescript\ninterface FlowSettingsProps {\n footer?: React.ReactNode | \n ((originNode: React.ReactNode, extra: { \n OkBtn: React.FC; \n CancelBtn: React.FC \n }) => React.ReactNode) | null;\n onCancel?: () => void | Promise;\n onSaved?: () => void | Promise;\n}\n```\n\n资料来源：[flowSettings.ts:40-52]()\n\n### 自定义 Footer 示例\n\n```tsx\n// 在底部工具栏添加内容\nfooter: (originNode, { OkBtn, CancelBtn }) => (\n
\n Additional info\n {originNode}\n
\n)\n\n// 隐藏底部\nfooter: null\n```\n\n## 移动端适配\n\n### 桌面模式组件\n\n当在桌面端访问移动端页面时，系统会渲染 `DesktopMode` 组件进行适配。\n\n```tsx\n\n \n\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-mobile/src/client/desktop-mode/index.md]()\n\n### 移动端 TabBar\n\n移动端使用自定义的 `MobileTabBar` 组件，支持链接跳转功能：\n\n| 功能 | 说明 |\n|------|------|\n| Inner Link | 内部页面跳转 |\n| Outer Page | 外部页面跳转 |\n| Selected | 选中状态管理 |\n\n资料来源：[mobile-layout/index.md]()\n\n## 设计态与运行态\n\n### 状态切换机制\n\n```mermaid\nstateDiagram-v2\n [*] --> Designable: 设计态开启\n Designable --> [*]: 保存配置\n Designable --> Readonly: 切换为只读\n Readonly --> Designable: 重新编辑\n Readonly --> [*]: 退出编辑\n```\n\n### Designable 上下文\n\n通过 `useDesignable()` Hook 可以获取当前设计态状态：\n\n```typescript\nconst { designable } = useDesignable();\n```\n\n## 配置示例\n\n### 基本 Schema 配置\n\n```typescript\n{\n type: 'object',\n properties: {\n name: {\n type: 'string',\n 'x-decorator': 'FormItem',\n 'x-component': 'Input',\n 'x-component-props': {\n placeholder: '{{t(\"Name\")}}',\n },\n },\n },\n}\n```\n\n### Markdown 编辑器配置\n\n```typescript\n{\n content: {\n type: 'string',\n 'x-decorator': 'FormItem',\n 'x-component': (props) => {\n return ctx.markdown.edit({\n ...props,\n value: props.value || ctx.model.props.value,\n mode: 'sv',\n height: '82vh',\n });\n },\n },\n}\n```\n\n资料来源：[packages/core/client/src/flow/flows/editMarkdownFlow.tsx]()\n\n## 最佳实践\n\n### 性能优化\n\n1. **减少不必要的渲染**：使用 `React.memo` 包装自定义组件\n2. **延迟加载**：对于复杂配置，使用动态导入\n3. **状态管理**：合理使用 Context 避免过度 prop drilling\n\n### 可维护性\n\n1. **Schema 分离**：将复杂的 Schema 拆分为多个子 Schema\n2. **组件复用**：提取公共配置为可复用组件\n3. **类型定义**：为自定义配置提供完整的 TypeScript 类型支持\n\n## 相关资源\n\n- [Schema Settings 文档](./schema-settings/index.md)\n- [Schema Initializer 文档](./schema-initializer/index.md)\n- [Schema Component 文档](./schema-component/index.md)\n- [流程引擎文档](../flow-engine/index.md)\n\n---\n\n\n\n## 文件管理与存储\n\n### 相关页面\n\n相关主题：[数据建模与集合管理](#data-modeling), [界面构建器](#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/plugins/@nocobase/plugin-ai/src/server/document-loader/cached.ts](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai/src/server/document-loader/cached.ts)\n- [packages/plugins/@nocobase/plugin-file-manager](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-file-manager) - *未在本次检索中获取到详细内容*\n- [packages/plugins/@nocobase/plugin-file-storage-s3-pro](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-file-storage-s3-pro) - *未在本次检索中获取到详细内容*\n- [docs/docs/cn/file-manager/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/cn/file-manager/index.md) - *未在本次检索中获取到详细内容*\n
\n\n# 文件管理与存储\n\n## 概述\n\nNocoBase 的文件管理与存储系统是一个模块化的基础设施，用于处理用户上传的文件、文档解析、以及与各种云存储服务的集成。该系统通过插件化的架构设计，支持灵活扩展存储后端，同时提供统一的客户端上传组件和服务器端处理逻辑。\n\n文件管理在 NocoBase 中扮演着关键角色，因为作为一个无代码平台，用户经常需要上传附件、文档、图片等资源，并对其进行管理和应用。\n\n## 核心组件架构\n\n### 上传组件（Upload）\n\nNocoBase 的前端上传组件基于 ant-design 的 Upload 组件进行封装，提供增强的功能和更好的用户体验。\n\n**组件类型定义：**\n\n```ts\ntype UploadProps = Omit & {\n onChange?: (fileList: UploadFile[]) => void;\n serviceErrorMessage?: string;\n value?: any;\n size?: string;\n};\n\ntype UploadReadPrettyProps = AntdUploadProps;\n```\n\n资料来源：[packages/core/client/src/schema-component/antd/upload/index.md:1-9]()\n\n**主要功能特性：**\n\n| 功能 | 描述 |\n|------|------|\n| 基础上传 | 支持单文件和文件列表上传 |\n| 规则验证 | 支持文件类型、大小等上传规则配置 |\n| 读写分离 | 提供不同的展示和编辑模式 |\n| 错误处理 | 支持自定义服务错误消息 |\n\n### 文档加载器\n\n在 AI 插件中，文件管理系统还负责文档的解析和加载。\n\n```ts\nprivate get aiFilesRepo() {\n return this.plugin.db.getRepository('aiFiles');\n}\n\nprivate get fileManager(): PluginFileManagerServer {\n return this.plugin.app.pm.get('file-manager');\n}\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/document-loader/cached.ts:76-81]()\n\n## 存储插件体系\n\n### 文件管理器插件\n\n文件管理器插件（`plugin-file-manager`）是 NocoBase 核心的文件管理模块，负责：\n\n- 文件元数据管理\n- 文件上传处理\n- 存储后端抽象\n- 访问权限控制\n\n### 存储后端插件\n\nNocoBase 采用插件化的存储后端设计，支持多种存储服务：\n\n| 存储类型 | 插件包 | 说明 |\n|----------|--------|------|\n| S3 兼容存储 | `plugin-file-storage-s3-pro` | 支持 AWS S3、MinIO 等 S3 兼容服务 |\n| 本地存储 | 内置支持 | 开发环境使用 |\n| 其他云存储 | 可扩展 | 通过插件机制支持 |\n\n## 数据流架构\n\n```mermaid\ngraph TD\n A[客户端上传组件] --> B[Upload API 端点]\n B --> C[文件管理器插件]\n C --> D[存储后端选择]\n D --> E[本地磁盘]\n D --> F[S3 兼容存储]\n D --> G[其他云存储]\n E --> H[文件元数据存储]\n F --> H\n G --> H\n H --> I[数据库记录]\n```\n\n## 客户端上传组件使用\n\n### 基础用法\n\n```tsx\nimport { Upload } from '@nocobase/client';\n\n// 基础上传示例\n\n```\n\n### 多文件上传\n\n```tsx\n// 多文件上传模式\n\n```\n\n### 带规则验证\n\n```tsx\n// 配置上传规则\n\n```\n\n### 只读展示\n\n```tsx\n// 用于展示已上传文件\n\n```\n\n## 服务器端处理\n\n### 文件管理器服务端\n\n文件管理器服务端负责处理上传请求、管理存储后端、以及维护文件元数据：\n\n```ts\nprivate get aiFilesRepo() {\n return this.plugin.db.getRepository('aiFiles');\n}\n\nprivate get fileManager(): PluginFileManagerServer {\n return this.plugin.app.pm.get('file-manager');\n}\n```\n\n服务器端提供以下核心能力：\n\n1. **文件存储抽象** - 通过统一的接口支持多种存储后端\n2. **元数据管理** - 使用 `aiFiles` 仓库管理文件元数据\n3. **访问控制** - 集成 NocoBase 的权限系统\n4. **文档解析** - 支持 AI 插件的文档加载需求\n\n### 文档解析元数据\n\n```ts\nprivate getParseMeta(meta?: Record): DocumentParseMeta | null {\n if (!meta || typeof meta !== 'object') {\n return null;\n }\n return meta[DOCUMENT_PARSE_META_KEY] ?? null;\n}\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/document-loader/cached.ts:47-52]()\n\n## 配置与扩展\n\n### 创建自定义存储后端\n\n开发者可以通过实现以下接口来创建自定义存储后端：\n\n```ts\ninterface StorageBackend {\n upload(file: Buffer, metadata: FileMetadata): Promise;\n download(path: string): Promise;\n delete(path: string): Promise;\n getUrl(path: string): string;\n}\n```\n\n### 注册文件处理插件\n\n```ts\n// 在插件的 install 方法中注册\nthis.app.pm.get('file-manager').registerBackend('custom', CustomStorageBackend);\n```\n\n## 与 AI 系统的集成\n\nNocoBase 的文件管理系统与 AI 插件深度集成，支持：\n\n- **文档加载** - 从存储中加载文档进行 AI 处理\n- **文件解析** - 解析各种文档格式提取内容\n- **向量化存储** - 支持将文件内容向量化后存储\n\n```ts\nreturn [\n new Document({\n pageContent: text,\n metadata: {\n source: sourceFile.filename,\n extname,\n },\n }),\n];\n```\n\n资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/document-loader/cached.ts:32-40]()\n\n## 最佳实践\n\n### 前端配置建议\n\n1. **合理设置文件大小限制** - 根据业务需求和存储成本设置\n2. **使用适当的文件类型白名单** - 提高系统安全性\n3. **配置错误提示信息** - 提供清晰的用户反馈\n\n### 存储策略建议\n\n1. **生产环境使用云存储** - 如 S3、阿里云 OSS 等\n2. **配置合理的缓存策略** - 减少存储成本\n3. **定期清理过期文件** - 释放存储空间\n\n## 相关资源\n\n- [NocoBase 官方文档](https://docs.nocobase.com/)\n- [文件管理器插件源码](https://github.com/nocobase/nocobase/tree/main/packages/plugins/@nocobase/plugin-file-manager)\n- [S3 存储插件源码](https://github.com/nocobase/nocobase/tree/main/packages/plugins/@nocobase/plugin-file-storage-s3-pro)\n\n---\n\n\n\n## 插件开发指南\n\n### 相关页面\n\n相关主题：[系统架构与设计模式](#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/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-initializer/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-initializer/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/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/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/mobile-layout/index.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-mobile/src/client/mobile-layout/index.md)\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/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- [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-component/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/index.md)\n
\n\n# 插件开发指南\n\n## 概述\n\nNocoBase 采用插件化架构，所有功能均以插件形式实现。插件系统是 NocoBase 的核心组成部分，允许开发者通过编写插件来扩展系统功能，实现模块化的功能管理与部署。\n\nNocoBase 的插件分为两类：\n\n- **客户端插件**：负责用户界面、页面路由、Schema 组件、Schema 初始化器等前端功能\n- **服务器端插件**：负责数据模型、API 接口、业务逻辑、数据库操作等后端功能\n\n一个完整的插件可以同时包含客户端和服务器端代码，通过统一的插件机制进行注册和管理。\n\n## 插件架构\n\n### 核心架构图\n\n```mermaid\ngraph TB\n subgraph 客户端 Client\n UI[用户界面]\n SC[Schema 组件]\n SI[Schema 初始化器]\n SS[Schema 设置]\n PM_UI[插件管理器 UI]\n end\n\n subgraph 服务器端 Server\n API[API 接口]\n DB[数据库操作]\n MODEL[数据模型]\n HOOKS[Hooks 钩子]\n end\n\n subgraph 核心 Core\n PM[插件管理器 PluginManager]\n PM_API[插件 API]\n end\n\n UI --> PM_UI\n SC --> SS\n SI --> SS\n PM_UI --> PM\n PM --> PM_API\n API --> PM_API\n DB --> PM_API\n MODEL --> PM_API\n HOOKS --> PM_API\n\n style PM fill:#e1f5fe\n style PM_API fill:#e1f5fe\n```\n\n### 插件生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> 安装: npm install\n 安装 --> 启用: enable()\n 启用 --> 加载: load()\n 加载 --> 运行: activate()\n 运行 --> 禁用: deactivate()\n 禁用 --> 启用: activate()\n 启用 --> 卸载: disable()\\nuninstall()\n 运行 --> 卸载: disable()\\nuninstall()\n 卸载 --> [*]\n```\n\n## 目录结构\n\n一个典型的插件项目目录结构如下：\n\n```\npackages/plugins/@nocobase/plugin-sample/\n├── src/\n│ ├── client/ # 客户端代码\n│ │ ├── index.ts # 客户端插件入口\n│ │ ├── pages/ # 页面组件\n│ │ ├── components/ # 自定义组件\n│ │ ├── schema-components/ # Schema 组件\n│ │ ├── schema-initializers/ # Schema 初始化器\n│ │ ├── schema-settings/ # Schema 设置\n│ │ ├── demos/ # 文档示例\n│ │ └── index.md # 文档\n│ └── server/ # 服务器端代码\n│ ├── index.ts # 服务器端插件入口\n│ ├── actions/ # 自定义 actions\n│ ├── collections/ # 数据模型定义\n│ └── migrations/ # 数据库迁移\n├── package.json\n└── README.md\n```\n\n## 服务器端插件开发\n\n### 插件类基础\n\n服务器端插件继承自 `Plugin` 基类，通过覆写生命周期方法来实现功能：\n\n```typescript\nimport { Plugin } from '@nocobase/server';\n\nexport class SamplePlugin extends Plugin {\n async load() {\n // 加载阶段：注册数据模型、API 路由等\n this.app.collection({\n name: 'samples',\n fields: [\n { type: 'string', name: 'title' },\n { type: 'text', name: 'description' },\n ],\n });\n\n this.app.acl.allow('samples', 'list');\n }\n\n async activate() {\n // 激活阶段：执行初始化逻辑\n }\n\n async deactivate() {\n // 停用阶段：清理资源\n }\n}\n\nexport default SamplePlugin;\n```\n\n### 数据模型定义\n\n```typescript\nthis.app.collection({\n name: 'articles',\n fields: [\n { type: 'belongsTo', name: 'author' },\n { type: 'hasMany', name: 'comments' },\n { type: 'string', name: 'title' },\n { type: 'richtext', name: 'content' },\n { type: 'date', name: 'publishedAt' },\n { type: 'boolean', name: 'isPublished' },\n ],\n});\n```\n\n### API 路由注册\n\n```typescript\nthis.app.resourcer.define({\n name: 'articles',\n actions: {\n async list(ctx, next) {\n // 自定义列表逻辑\n await next();\n },\n async create(ctx, next) {\n ctx.request.body.author = ctx.state.currentUser.id;\n await next();\n },\n },\n});\n```\n\n### Hooks 机制\n\nNocoBase 提供了丰富的 Hooks 用于扩展功能：\n\n| Hook 名称 | 说明 | 使用场景 |\n|---------|------|---------|\n| `beforeSave` | 保存前执行 | 数据校验、默认值设置 |\n| `afterSave` | 保存后执行 | 关联操作、日志记录 |\n| `beforeFind` | 查询前执行 | 权限过滤、条件追加 |\n| `afterFind` | 查询后执行 | 数据转换、字段处理 |\n| `beforeRemove` | 删除前执行 | 关联删除、权限校验 |\n| `afterRemove` | 删除后执行 | 清理操作、通知发送 |\n\n```typescript\nthis.app.on('afterSave', async (event, model) => {\n if (model.get('type') === 'published') {\n // 发送通知等操作\n }\n});\n```\n\n### 资源上下文 API\n\n插件可以通过 `ctx.resource` 访问当前资源上下文：\n\n```typescript\n// 设置资源当前数据（仅前端）\nctx.resource.setData(value);\n\n// 从后端刷新数据\nawait ctx.resource.refresh();\n\n// 订阅资源事件\nctx.resource.on('refresh', () => {});\n\n// 设置资源名称\nctx.resource.setResourceName('users');\n\n// 设置主键/过滤键\nctx.resource.setFilterByTk(id);\n\n// 执行资源动作\nawait ctx.resource.runAction('create', data);\n```\n\n## 客户端插件开发\n\n### 插件入口\n\n```typescript\nimport { Plugin } from '@nocobase/client';\n\nexport class SamplePlugin extends Plugin {\n async load() {\n // 注册页面路由\n this.app.router.add('sample', {\n path: '/sample',\n Component: SamplePage,\n });\n\n // 注册 Schema 组件\n this.app.schemaInitializerManager.add('SampleInitializer', {\n // ...\n });\n\n // 注册 Schema 设置\n this.app.schemaSettingsManager.add('SampleSetting', {\n // ...\n });\n }\n}\n\nexport default SamplePlugin;\n```\n\n### Schema 组件\n\nSchema 是 NocoBase 前端配置的核心机制，用于描述界面结构和行为：\n\n```mermaid\ngraph LR\n A[Schema 配置] --> B[组件渲染]\n A --> C[数据绑定]\n A --> D[事件处理]\n A --> E[样式配置]\n```\n\n#### Schema 基础结构\n\n```typescript\nconst schema = {\n type: 'void',\n 'x-component': 'SampleCard',\n 'x-component-props': {\n title: '{{ title }}',\n },\n properties: {\n content: {\n type: 'void',\n 'x-component': 'Markdown',\n 'x-content': '{{ content }}',\n },\n },\n};\n```\n\n#### Schema 组件类型\n\n| 类型 | 说明 | 示例 |\n|-----|------|------|\n| `void` | 容器组件 | `Grid`, `Card`, `Form` |\n| `string` | 文本输入 | `Input`, `Textarea` |\n| `number` | 数字输入 | `InputNumber` |\n| `boolean` | 开关选择 | `Switch` |\n| `date` | 日期选择 | `DatePicker` |\n\n### Schema 初始化器\n\nSchema 初始化器用于在设计器中插入 Schema 节点：\n\n```typescript\nthis.app.schemaInitializerManager.add('SampleBlockInitializer', {\n title: '示例区块',\n icon: 'PlusOutlined',\n sections: {\n basic: {\n title: '基础',\n items: [\n {\n title: '表格',\n schema: {\n type: 'void',\n 'x-component': 'Table',\n },\n },\n ],\n },\n },\n});\n```\n\n#### 动态显示和隐藏\n\n```typescript\n{\n 'x-initializer': 'SampleInitializer',\n 'x-initializer-props': {\n filter: (node) => node.schema?.['x-designer'] === 'SampleDesigner',\n },\n}\n```\n\n### Schema 设置\n\nSchema 设置用于配置 Schema 节点的属性：\n\n```typescript\nthis.app.schemaSettingsManager.add('SampleSetting', {\n title: '示例设置',\n items: [\n {\n name: 'title',\n title: '标题',\n component: {\n name: 'Input',\n props: {\n placeholder: '{{ t(\"Title\") }}',\n },\n },\n },\n {\n name: 'description',\n title: '描述',\n component: {\n name: 'TextArea',\n props: {\n rows: 4,\n },\n },\n },\n {\n name: 'divider',\n type: 'divider',\n },\n {\n name: 'delete',\n title: '删除',\n component: {\n name: 'Delete',\n props: {\n danger: true,\n },\n },\n },\n ],\n});\n```\n\n### Schema 设计器\n\nSchema 设计器提供可视化编辑 Schema 的能力：\n\n```typescript\nimport { GeneralSchemaDesigner } from '@nocobase/client';\n\nconst SampleDesigner = () => {\n return (\n \n );\n};\n```\n\n## 插件管理器\n\nNocoBase 提供了内置的插件管理器，支持插件的安装、启用、禁用和卸载。\n\n### 插件信息展示\n\n插件详情页面展示以下信息：\n\n| 字段 | 说明 |\n|-----|------|\n| 名称 (Name) | 插件内部名称 |\n| 显示名称 (DisplayName) | 用户友好的名称 |\n| 包名 (PackageName) | npm 包名 |\n| 版本 (Version) | 当前版本号 |\n| 作者 (Author) | 插件作者 |\n| 仓库 (Repository) | 源码仓库地址 |\n| 主页 (Homepage) | 文档或项目主页 |\n| 许可证 (License) | 开源许可证 |\n| 描述 (Description) | 插件功能描述 |\n\n### 依赖兼容性检查\n\n插件管理器会检查插件依赖的兼容性：\n\n```typescript\n// 检查是否包含 externalVersion.js\nif (data?.data?.depsCompatible === false) {\n return ;\n}\n\n// 检查依赖版本是否兼容\nif (!data?.data?.['isCompatible']) {\n return ;\n}\n```\n\n## 变量系统\n\nNocoBase 提供了内置变量系统，支持在配置中使用动态值：\n\n### 内置变量\n\n| 变量名 | 说明 | 示例 |\n|-------|------|------|\n| `$nRecord` | 当前记录数据 | `$nRecord.title` |\n| `$nUser` | 当前用户信息 | `$nUser.id`, `$nUser.name` |\n| `$nRole` | 当前角色信息 | `$nRole.name` |\n| `$nDate` | 当前日期时间 | `$nDate.format('YYYY-MM-DD')` |\n| `$nExactDate` | 精确时间戳 | `$nExactDate` |\n| `$date` | 日期（已废弃） | - |\n| `$system` | 系统变量（已废弃） | - |\n| `currentTime` | 当前时间（已废弃） | - |\n| `$nVisible` | 可见性控制 | `$nVisible` |\n\n### 变量上下文\n\n```typescript\n{\n name: '$nUser',\n ctx: {\n id: () => currentUser.id,\n name: () => currentUser.name,\n email: () => currentUser.email,\n },\n}\n```\n\n## 流程引擎集成\n\n插件可以与流程引擎集成，实现复杂的业务流程：\n\n### 自定义动作\n\n```typescript\nimport { FlowSettings } from '@nocobase/plugin-workflow';\n\nclass SamplePlugin extends Plugin {\n async load() {\n // 注册流程设置组件\n this.app.setFlowSettings({\n components: {\n SampleNode: SampleNodeComponent,\n },\n scopes: {\n sampleScope: SampleScopeComponent,\n },\n });\n }\n}\n```\n\n### 自定义 Footer\n\n流程设置支持自定义底部按钮区域：\n\n```typescript\n// 方式一：追加内容\nfooter: (originNode, { OkBtn, CancelBtn }) => (\n
\n Additional info\n {originNode}\n
\n)\n\n// 方式二：完全自定义\nfooter: (originNode, { OkBtn, CancelBtn }) => (\n \n \n \n \n)\n\n// 方式三：隐藏底部\nfooter: null\n```\n\n## 移动端插件开发\n\nNocoBase 支持移动端页面的开发，通过 MobileTabBar 提供底部导航：\n\n### MobileTabBar 组件\n\n```typescript\nimport { MobileTabBar } from '@nocobase/plugin-mobile';\n\n// 使用 Link 跳转\n}\n title=\"首页\"\n/>\n\n// 外部链接\n}\n title=\"外部链接\"\n/>\n```\n\n### Schema 定义\n\n```typescript\n{\n type: 'void',\n 'x-component': 'MobileTabBar',\n 'x-component-props': {\n activeKey: '{{ activeKey }}',\n },\n properties: {\n home: {\n type: 'void',\n 'x-component': 'MobileTabBar.Item',\n 'x-component-props': {\n key: 'home',\n icon: 'HomeOutlined',\n link: '/pages/home/index',\n },\n },\n },\n}\n```\n\n### Desktop Mode\n\n当在桌面端访问移动端页面时，可以使用 DesktopMode 组件：\n\n```typescript\nimport { DesktopMode } from '@nocobase/plugin-mobile';\n\n\n \n\n```\n\n## 联动规则\n\nNocoBase 支持在表单中使用联动规则，实现字段间的动态关联：\n\n### LinkageFilter 组件\n\n```typescript\ntype FilterActionProps = ActionProps & {\n options?: any[]; // 可选的操作符\n form?: Form; // 表单实例\n onSubmit?: (values: T) => void; // 提交回调\n onReset?: (values: T) => void; // 重置回调\n};\n```\n\n### 基本用法\n\n左侧支持变量、操作符，右侧变量组件跟随左侧变量联动：\n\n```typescript\n{\n type: 'void',\n 'x-component': 'LinkageFilter',\n 'x-component-props': {\n options: [\n { label: '等于', value: '=' },\n { label: '包含', value: 'contains' },\n ],\n onSubmit: (values) => {\n // 处理筛选\n },\n },\n}\n```\n\n## 最佳实践\n\n### 1. 插件命名规范\n\n```json\n{\n \"name\": \"@nocobase/plugin-{feature-name}\",\n \"version\": \"1.0.0\",\n \"displayName\": \"{{t('Feature Name')}}\",\n \"description\": \"{{t('Plugin description')}}\"\n}\n```\n\n### 2. 国际化支持\n\n```typescript\n// 使用 t() 函数进行翻译\ntitle: t('Sample Plugin'),\ndescription: t('This is a sample plugin for demonstration'),\n\n// 支持中文\ndata?.data?.lang === 'zh-CN' ? '中文链接' : 'English Link'\n```\n\n### 3. Schema 组件开发\n\n```typescript\nimport { SchemaComponent } from '@nocobase/client';\n\nconst SampleComponent = (props) => {\n return (\n \n );\n};\n```\n\n### 4. 错误处理\n\n```typescript\n// 插件加载失败处理\nasync load() {\n try {\n await this.registerCollections();\n await this.registerActions();\n } catch (error) {\n console.error('Plugin load error:', error);\n throw error;\n }\n}\n\n// 依赖检查\nif (data?.data?.depsCompatible === false) {\n throw new Error('插件依赖不兼容，请重新构建');\n}\n```\n\n### 5. 性能优化\n\n```typescript\n// 使用 React.memo 优化组件\nconst SchemaToolbar = React.memo((props) => {\n // ...\n});\n\n// 使用 useCallback 缓存回调\nconst onVisibleChange = useCallback((nextVisible: boolean) => {\n startTransition(() => {\n setVisible(nextVisible);\n });\n}, []);\n```\n\n## 注册插件到系统\n\n### 服务器端注册\n\n```typescript\n// packages/plugins/@nocobase/plugin-sample/src/server/index.ts\nimport { SamplePlugin } from './SamplePlugin';\n\nexport default SamplePlugin;\n```\n\n### 客户端注册\n\n```typescript\n// packages/plugins/@nocobase/plugin-sample/src/client/index.ts\nimport { SampleClientPlugin } from './SampleClientPlugin';\n\nexport default SampleClientPlugin;\n```\n\n### 插件启用\n\n在 `packages/core/server/src/plugins/index.ts` 中添加插件：\n\n```typescript\nimport sample from '@nocobase/plugin-sample';\n\nexport const plugins = [\n // ...其他插件\n sample,\n];\n```\n\n## 总结\n\nNocoBase 的插件系统提供了完整的扩展能力：\n\n- **模块化架构**：前后端分离的插件开发模式\n- **Schema 机制**：灵活的界面配置系统\n- **生命周期管理**：完整的插件安装、启用、停用流程\n- **依赖管理**：自动化的依赖检查和兼容性验证\n- **多端支持**：同时支持桌面端和移动端插件开发\n\n开发者可以通过继承基类、重写生命周期方法、注册组件和配置来实现各种业务需求。\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> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 nocobase 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. nocobase-overview：NocoBase 概述。围绕“NocoBase 概述”模拟一次用户任务，不展示安装或运行结果。\n2. system-architecture：系统架构与设计模式。围绕“系统架构与设计模式”模拟一次用户任务，不展示安装或运行结果。\n3. data-modeling：数据建模与集合管理。围绕“数据建模与集合管理”模拟一次用户任务，不展示安装或运行结果。\n4. acl-permissions：权限系统与 ACL。围绕“权限系统与 ACL”模拟一次用户任务，不展示安装或运行结果。\n5. workflow-engine：工作流引擎。围绕“工作流引擎”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. nocobase-overview\n输入：用户提供的“NocoBase 概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. system-architecture\n输入：用户提供的“系统架构与设计模式”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. data-modeling\n输入：用户提供的“数据建模与集合管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. acl-permissions\n输入：用户提供的“权限系统与 ACL”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. workflow-engine\n输入：用户提供的“工作流引擎”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / nocobase-overview：Step 1 必须围绕“NocoBase 概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / system-architecture：Step 2 必须围绕“系统架构与设计模式”形成一个小中间产物，并等待用户确认。\n- Step 3 / data-modeling：Step 3 必须围绕“数据建模与集合管理”形成一个小中间产物，并等待用户确认。\n- Step 4 / acl-permissions：Step 4 必须围绕“权限系统与 ACL”形成一个小中间产物，并等待用户确认。\n- Step 5 / workflow-engine：Step 5 必须围绕“工作流引擎”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\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- README.zh-CN.md\n- package.json\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 nocobase 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：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" }