nocobase-ai-builder

目标

将用户的业务需求转化为结构完整、符合生产环境要求的 AI 门户应用。负责产品设计和源代码实现：如果用户没有提供详细的信息架构、页面构成、文案或视觉方向，不要只做机械的 CRUD 示例。

入口约定

• 对于已解析出 portalType === "ai" 的 Portal，所有开发请求都使用此技能。
• 如果 nocobase-portal-manage 提供了已解析 Portal 的名称、环境和本地源代码路径，请使用这些信息。不要在此技能中重新解析其他 Portal。
• 没有真实的本地源代码目录时，不要开始修改源代码。如果 nb portal list -j 或 nb portal info <portal> -j 中选定的 AI Portal 的 developmentPath / localPath / 本地源代码路径为空，请先通过 Portal 工作流运行 nb portal pull <portal>，然后再次读取 Portal 信息或列表，并进入拉取后的开发目录，再应用此技能。
• 不要将源代码存储配置用作工作目录。sourceStorage、git_repo、git_branch、git_path、--git-path、仓库子目录以及部署／存储路径用于指定 Portal 源代码的拉取、推送或部署位置；除非 nb portal pull 的回读结果明确将同一路径作为 developmentPath / localPath 返回，否则这些路径都不是用于修改源代码的本地开发目录。
• 如果用户当前已在一个可识别的 AI Portal 源代码项目中工作，除非请求指定了其他 Portal，否则请直接使用该项目。
• 将 @nocobase/portal-template-default 视为规范的基础模板包。除非用户明确缩小了请求范围，否则升级 Portal 意味着安全地将最新的基础模板源代码变更应用到用户项目，并同时应用所需的 @nocobase/portal-sdk 和已安装的 Registry 迁移；这绝不意味着只修改软件包或兼容性版本。
• 原始构建请求即表示已授权修改和验证该 Portal 的源代码。不要再次询问是否确认修改代码。
• 修改文件前，请阅读项目的 AGENTS.md 和适用的本地说明。
• 保留与当前任务无关的工作区变更。除非用户提出要求，否则不要推送或部署。

必需工作流

1. 检查当前应用

在设计或编写代码之前，先通过问题驱动的渐进式探索了解项目。不要把完整盘点仓库作为常规前置步骤。

将探索范围限定为当前任务或里程碑。只有在能够回答具体问题或支持当前变更时，才检查应用源码；无关层面等到确有需要时再看。

1. 直接阅读项目说明、package 脚本，以及与请求直接相关的路由或功能入口。
2. 打开文件前，先按文件名、符号、路由、导出项或导入项搜索。检查最接近的匹配实现，以及理解其公开契约所需的直接依赖。
3. 根据这些文件确认相关的品牌、导航、主题、身份验证、ACL、i18n、API 和资源约定。只有在某个具体的未解问题阻碍安全实现时，才扩大搜索范围。
4. 通过真实的 NocoBase 元数据、Swagger 文档、响应或现有代码，确认集合、字段、关联和操作。如果任务涉及 API 集成，请使用 nb api swagger list/get 阅读范围最小的相关文档命名空间。切勿臆造后端契约。
5. 对于全新系统或经过大幅重新设计的系统，确认必须替换的模板演示界面；不要审查无关的 Registry 项或应用功能。

确认目标位置、最适用的实现契约、任务所需的任何 API 契约，以及合适的验证方式后，就停止探索。不要仅为了增强整体信心而递归阅读 src、registry 或 src/extensions。仅在明确要求审计、升级、迁移或跨领域重构时，才进行全仓库检查。

如果请求的服务端功能没有可靠的现有示例，必须先阅读 Swagger，再声称可以实现。找到并获取相关的集合或插件命名空间，然后确认端点、方法、参数、请求体、响应和文档中说明的权限要求。如果现有文档中没有所需功能，不要猜测 API，也不要声称该功能受支持；应指出缺少的契约，并确定是否需要修改后端或插件。

如果当前里程碑要修改应用结构或 UI 基础，请阅读 项目约定。如果要实现数据、身份验证、i18n、运行时配置或资源，请阅读 NocoBase 运行时。

2. 编码前设计系统

在系统设计开始时，明确询问用户是否需要国际化。如果需要，确认主要语言区域和所需的其他语言区域；如果请求中已说明，则不要再次询问。

根据用户的请求整理一份精简的内部产品简介：

• 系统用途和工作标题；
• 主要用户角色及其常见任务；
• 信息架构和菜单层级；
• 页面清单及各页面职责；
• 核心页面的内容、操作和状态；
• 路由、对话框、抽屉和子页面模型；
• 前端访问控制模型；
• 视觉方向、信息密度、主题和响应式行为。

持续滚动规划实现工作，并将计划拆分为适当规模的里程碑。对于完整系统，简要列出后续里程碑，并详细规划当前可逆的里程碑。完成并验证当前里程碑后，再优化下一个里程碑，并在相关工作开始时加载专用技能。

遇到细节缺失时，做出合理的产品决策。仅当缺失的选择会实质性地改变业务行为、数据、安全性或不可逆操作时才提问。

不要以用户或 CRUD 示例为基础推导整个产品。根据业务调整页面构成：工作区应突出工作事项，概览页应突出可执行的信号，详情页应整理相关上下文，表单应遵循实际工作流。

将初始侧边栏视为预设参考，而不是固定的应用外壳。作为产品设计优化，应考虑最适合系统的导航结构，例如顶部导航、侧边栏导航、二级菜单、上下文选项卡，或适度组合这些方式。这只是指导，不要求替换侧边栏。无论选择哪种模式，都应确保导航易于理解，并保证路由、直接访问、响应式布局和交互在受支持的设备尺寸下均可正常使用。

3. 设计和配置角色与权限

对于完整系统，在 Todo 列表或实现计划中加入专门的角色与权限任务。不要将其归入项目检查、路由或页面实现之中。

• 定义实际的用户角色、成员关系及各角色的职责。如果系统确实只有一个无差别的角色，应明确记录这一决定，而不是默默省略权限设计。
• 决定并配置哪些角色可以进入 Portal。
• 为已确定的 Portal 创建角色时，将该 Portal 的 uid 或准确身份传递给 nocobase-acl-manage，并将明确授予该角色进入 Portal 的权限作为角色创建的一部分。继续之前，验证角色与 Portal 的关联。
• 在依赖前端可见性之前，为每个角色配置并验证服务端资源、操作、范围和字段策略。
• 针对获准和未获准的用户，设计前端菜单、路由、页面、区域、字段、操作和记录行为。
• 在最小且正确的范围内使用已安装的 ACL 边界：整页使用 AclPage，独立的受保护面板使用 AclRegion，字段或字段组使用 AclField，控件和记录操作使用 CanAccess 或支持 ACL 的内置操作组件。不要用本地布尔值或硬编码的角色比较来重复检查。
• 隐藏控件并不足以保障安全；NocoBase 服务端 ACL 始终具有最终决定权。

使用 nocobase-acl-manage 进行角色、成员关系、Portal 访问权限和服务端 ACL 变更。实现前端权限之前，请完整阅读 路由与访问控制，并至少验证一种允许状态和一种拒绝状态（角色或权限）。

4. 规划导航和 URL

在实现页面内部之前，先设计导航和 URL 界面：

• 每个可见的末级菜单都必须指向真实且可访问的路由。
• 每个计划显示在侧边栏中的页面都必须声明其路由和 Refine resource；仅有路由元素不会创建菜单项。
• 不要创建占位菜单项或空分组。
• 对话框、抽屉、详情、编辑器和有意义的子页面都必须拥有独立 URL，支持直接打开、刷新、分享和浏览器历史记录。
• 在实现路由之前，先确定每个创建、编辑和查看操作应使用抽屉、对话框还是完整页面。将 resourceAction 视为 Refine 路径元数据，而非展示方式选择。
• 每个资源的创建、编辑或查看操作只注册一个规范的 resourceAction 路径。当同一界面从其他列表、详情或工作流宿主打开时，通过该宿主拥有的普通相对型子路由复用其业务内容；不要导航到规范绝对 URL 并替换当前工作流。
• 打开上下文子界面时，保留完整的来源 URL，包括搜索参数和哈希值。关闭时，如果来源 URL 已知，则返回该 URL；否则使用解析后的父路由作为直接进入时的回退路径。

每当任务新增或更改导航、路由、对话框、抽屉、子页面、角色或权限时，都要完整阅读 路由与访问控制。

5. 实现应用自有代码

• 将所有应用自有的业务功能（包括路由、页面、组件、钩子、工具和翻译）放在应用自有的 src 目录中，并遵循项目当前的组织方式。不要为此创建 src/extensions/<business-feature>。
• src/extensions 仅用于已安装的 Registry 扩展源代码；将 src/components/ui 视为 shadcn 基础层。默认情况下，不要修改这两处内容。
• 复用扩展或基础组件时，从应用自有代码中导入、重新导出、封装或组合。只有当任务明确要求更改该扩展或基础层，且组合无法满足要求时，才修改其源代码；并将差异控制在最小范围内。
• 使用项目中已有的 React、TypeScript、Refine、React Router、Tailwind 和 shadcn Base UI 模式。
• 不要引入 Ant Design 或基于 Ant Design 的 NocoBase 客户端组件。
• 遵循 Base UI 的渲染约定。当受控 Select 存储枚举键或记录 ID 时，应在 SelectValue 中解析并渲染面向用户的标签，而不是暴露原始值。
• 复用 Portal 的 API 客户端、数据提供程序、身份验证会话、ACL 运行时、i18n 运行时、系统设置、basename 和资源 URL 辅助工具。
• 对图表、KPI 和分组聚合使用 NocoBase 的 query 操作；不要获取所有列表记录，再在浏览器中推导服务器规模的分析结果。
• 根据实际情况覆盖加载、空状态、错误、未授权、成功、破坏性操作确认和响应式状态。
• 使用语义化令牌和共享组合。避免一次性颜色、随意指定尺寸、过多的 className，以及不必要地重写 shadcn 默认样式。
• 保留模板的根级和页面级错误边界。对于图表、AI 输出或第三方组件等可独立恢复的渲染器，在 region 作用域使用已安装的 NocoBaseErrorBoundary；不要在业务代码中重新实现错误边界基础设施。

构建真实系统时，应从应用界面中移除模板展示内容：在应用层隐藏或注销演示导航和路由，替换入门模板的品牌标识和文案，并确保用户首次可访问的页面对目标用户有用。不要仅为隐藏演示入口而删除已安装的扩展源代码。

6. 填充有代表性的演示数据

对于新建或大幅重建的系统，在数据模型和核心工作流正常运行后，填充完整一致的演示记录。这是交付内容的一部分，而非可选的后续工作。

• 通过真实的 NocoBase API 或 CLI 命令创建记录；不要在前端组件中硬编码模拟业务记录。
• 覆盖主要集合、关联、选项值、所有者、状态和日期，使着陆页、列表、详情、筛选器、仪表板和 AI 上下文都具有实际意义。
• 使用易于识别的演示标识符，并先检查现有记录，避免重复运行时造成无法控制的重复数据。绝不要为了给演示腾出空间而覆盖或删除现有用户数据。
• 在数据中完成至少一个真实的端到端工作流，而不是用互不相关的占位内容填满每个字段。
• 如果目标包含真实业务数据、未获准创建记录，或 API 拒绝了操作，不要默默跳过此步骤。请说明原因和确切的剩余数据设置工作。

7. 选择并应用主题

如果用户未指定主题，请选择一种克制且协调、适合该系统的设计方向，并继续推进，不要因此阻塞工作。通过应用级语义令牌和共享布局规则定义主题行为。

如果用户希望选择主题，请引导他们访问 https://www.shadcn.io/theme，并接受所选主题名称、Registry URL 或生成的安装命令。检查工作树和安装程序的差异，将主题与应用品牌整合，并避免盲目覆盖经过自定义的 src/components/ui 文件。主题提供视觉基础，但不能取代特定于业务的信息架构、内容、状态或交互。

8. 实现有意义的 AI 交互

在系统的核心工作流无需 AI 也能正常运行后，检查已完成的页面，并找出 AI 能显著减少工作量或改善决策的交互。合适的候选场景包括自然语言检索、摘要、信息提取、分类、起草、解释、引导式分析，以及基于当前页面或记录上下文的多步协助。

要完整构建 AI Portal 系统，至少实现一个可信且与上下文相关的 AI 交互。仅进行评估或罗列可能的方案，无法满足此要求。如果不会实质性改变业务行为或安全性，请直接选择最有依据的交互，无需再次确认。

• 使用有针对性的搜索，找到与所选交互最接近的已安装 AI 示例。检查该示例、其公开契约，以及复用它所需的直接依赖；不要罗列所有已安装的 AI 扩展、钩子、演示或工具渲染器。
• 绝不要为 Portal AI 交互添加、绑定、公开或选择开发者类别的员工。即使发现 API 返回了已知开发者用户名，例如 nathan、dara、lina 和 orin，也要将其排除；请使用合适的业务员工，或创建专用员工。
• 实现页面级 AI 交互之前，先找到与需求最接近的已安装 Page Context 场景。优先复用现有模式——手动选择页面元素、Shortcut 任务上下文、对话预设上下文、继承的 AIPageContextScope、Form filler，或具有权限感知能力的自定义前端工具——并复用其上下文和任务契约。
• 优先在相关页面、记录、选区或操作附近设置上下文入口。向用户清楚说明共享的上下文以及将生成的结果。
• 保留完整的非 AI 工作流。AI 输出不得绕过校验、ACL、确认步骤或服务端业务规则。
• 复用现有的 AI 运行时以及员工／工具契约。需要配置员工、模型、工具或提示词时，使用 nocobase-ai-employee。
• 不要用装饰性的聊天按钮或不受支持的能力来满足此要求。如果没有员工、模型、工具契约或运行时能够支持可信的交互，请诊断缺少的前置条件，并将 AI 部分报告为未完成，而不是悄然跳过。

9. 通过测试验证结果

在实现的同时设计验证方案。添加或更新最小且有价值的一组自动化测试，用于保护变更后的行为和系统的主要工作流；不要为了提高覆盖率或测试数量而创建测试。

使用前端测试验证无需后端数据、身份验证、ACL 或数据提供方模拟即可运行的纯逻辑和本地组件交互。使用针对真实 NocoBase 环境的 E2E 测试验证身份验证、数据、角色与权限、路由集成、文件、AI 和完整用户旅程。覆盖主要成功工作流，以及具有代表性的高风险拒绝、错误或恢复路径。

运行类型检查、相关前端测试、相关 E2E 测试以及生产构建。仅在自动化断言无法合理表达时，才通过有针对性的浏览器检查进行探索性的视觉或响应式检查；这不能替代可重复的验收测试。

完成重要页面或系统构建之前，请阅读 验证。

10. 安全升级现有 Portal

应将 Portal 升级视为源代码迁移，而非仅更新软件包。应用自身的版本应与 nocobase.defaultTemplateVersion 中继承的具体基础版本保持独立。

在更改现有 Portal 的模板、Portal SDK 主版本或已安装的 Registry 源之前，请完整阅读 Portal Project Upgrades。将用户代码视为不可替代：先建立并验证恢复点；如果项目不是 Git 仓库，还应创建单独的备份。列出目标版本、源代码影响、冲突处理策略、验证方式和回滚计划，并在编辑前获得用户明确确认。随后合并所需的基础模板源代码，同时避免覆盖应用自有代码；单独更新已安装的 Registry 项；只有在实际纳入并验证了匹配的源代码后，才更改兼容性元数据。

协作边界

• 如果用户请求的 UI 需要创建或更改后端集合或字段，请使用 nocobase-data-modeling，然后返回此处实现源代码。
• 如果需要更改角色、用户角色成员关系、Portal 入口访问权限或服务端资源策略，请使用 nocobase-acl-manage；前端访问控制实现仍由此技能负责。
• AI 员工的发现、生命周期、模型、工具或提示词配置，请使用 nocobase-ai-employee。
• Portal 的创建、源代码同步、开发生命周期、推送、部署或销毁操作，请使用 nocobase-portal-manage。
• 如果运行时缺少某项功能，请诊断并报告，而不是用并行的本地实现替代 NocoBase 基础设施。

参考资料加载表

此表仅用于按需指导，并非预先阅读清单。只加载当前阶段所需的参考资料；不要阅读后续阶段的参考资料。

参考资料	何时阅读
Project Conventions	更改结构、品牌、主题、共享 UI、扩展使用方式或起始内容时
NocoBase Runtime	使用数据、API 操作、身份验证、国际化、系统设置、basename 或资源时
Routing and Access	添加导航、URL 入口、角色、ACL 或受保护的控件时
Verification	验证页面、功能、主题或完整系统时
Portal Project Upgrades	升级现有 Portal 模板、Portal SDK 主版本或已安装的 Registry 源时

完成情况报告

报告以下内容：

• 设计的系统或功能；
• 重要的产品与技术决策；
• 更改的文件和集成点；
• 根据真实证据确认的数据、路由和访问控制假设；
• 创建的代表性演示数据，或无法创建的明确原因；
• 已交付的上下文 AI 交互，或阻碍其实现的具体运行时前提条件；
• 已运行的自动化检查和验收场景；
• 尚未完成或需要服务器配置的事项；
• 可选的后续步骤，但不要自动推送或部署。