• 简体中文

      • 与 AI Agent 协作搭建

      前置条件

      阅读本页前，请确保你已按照 AI Portal 搭建快速开始 跑通了第一个 Portal。

      AI Portal 的日常开发就是跟 AI Agent 说话——你描述要什么页面，它写代码，你在浏览器里看效果。

      在 Portal 目录下工作

      开始之前，建议先进到 Portal 的源码目录，再在那里打开 AI Agent。这样 Agent 一上来就在正确的上下文里，读得到 AGENTS.md 和现有代码。

      先查出目录在哪：

      nb portal info main

      输出里的开发路径就是 Portal 源码所在的位置。cd 过去，然后打开你的 AI Agent：

      cd <开发工作区目录>

      之后描述需求就行：

      帮我给 nocobase 的 main portal 加一个订单列表页

      让 AI 先读再写

      模板根目录有一个 AGENTS.md，写明了这个项目的开发约定：优先复用 src/extensions 里已有的实现、定制 UI 组件要用组合而不是直接改基础组件、不要引入 Ant Design。支持读取该文件的 AI Agent 会自动遵守这些约定。

      你也可以往 AGENTS.md 里补自己项目的约定，比如命名习惯、业务术语、哪些目录不要动。写进去之后每次对话都会生效，不用反复交代。

      src/extensions 下有几个内置扩展，其中 nocobase-users-example 是一个完整的增删改查页面，列表、创建、编辑、详情都齐了。让 AI 照着它写新页面，比从零描述要省事得多：

      参考 nocobase-users-example 的写法，做一个产品管理页面

      提示词示例

      场景 A：新建一个业务页面

      描述清楚三件事就够了——页面里有什么、数据从哪来、怎么交互：

      加一个客户管理页面：
表格显示名称、电话、邮箱、创建时间，支持按名称搜索，
点击某一行打开详情抽屉，抽屉里能直接编辑并保存

      场景 B：改造现有页面

      改动型的需求，把要改的地方说具体，不用重复描述整个页面：

      客户列表加一个状态筛选，
选项是「跟进中」「已成交」「已流失」，默认不筛选

      场景 C：接入一个新的数据表

      数据表建好之后，让 AI 生成对应的页面。它会读取字段定义，据此决定表单控件和列表字段：

      我刚建了一张 contracts 表，帮我做一套对应的增删改查页面

      如果表还没建，可以先用 数据建模 让 AI 设计好数据结构，再回来做页面。

      场景 D：从原型复刻界面

      有设计稿或者现成的 HTML 原型时，直接给 AI：

      按这张原型图做首页，
配色和布局保持一致，数据接 orders 表

      场景 E：加一个认证方式

      服务端启用了某种认证方式之后，登录页需要对应的前端支持：

      NocoBase 里已经启用了钉钉登录，帮登录页加上钉钉登录按钮

      协作技巧

      小步迭代。 一次让 AI 做一个页面或一处改动，看到效果再继续。一口气描述五个页面，出问题时很难判断是哪一步跑偏的。

      让开发服务一直开着。 nb portal dev main 跑起来之后是热更新的，AI 每改完一次你马上能看到效果，反馈循环最短。

      提供明确的报错。 页面白屏、构建失败、接口报 403——把完整的错误信息、截图等贴给 AI，不要让 AI 自己猜，通常几轮对话就能解决。不用自己先去判断是哪一层的问题。

      error

      常见问题

      AI 改错了怎么回退？

      如果 Portal 源码用 Git 管理，直接 git checkout 回退就行。用默认的 nocobase source storage 时，可以从 source storage 重新拉一份覆盖本地：

      nb portal pull main --force

      --force 会删掉开发工作区重新拉取，执行前确认没有想保留的改动。想避免这种取舍，建议早点把源码切到 Git 管理，具体做法见 部署与源码管理。

      构建失败怎么排查？

      先在本地跑一次构建，看完整报错：

      nb portal deploy main

      TypeScript 类型错误和依赖缺失是最常见的两类，把报错贴给 AI 让它修复即可。

      手动改代码和 AI 改代码会冲突吗？

      不会。Portal 源码就是普通的前端工程，你可以随时自己动手改，也可以让 AI 接着改。只要不是同一时刻在改同一个文件，都没有问题。

      相关链接