NocoBase 本周更新中，一个值得开发者关注的变化是：JS 区块开始支持注册前端 AI 工具。它让低代码页面不再只是展示 AI 返回的文本，而是可以把页面上下文和受控操作包装成工具，交给 AI 调用。与此同时，NocoBase 仍并行维护 main、next 和 develop 三个分支，采用这项能力前需要先判断稳定性要求。
注册前端工具意味着什么
传统 AI 对话框通常只能访问服务端提供的数据。前端工具注册机制则可以把浏览器中的状态和动作暴露为结构化能力，例如：
- 读取当前表单字段，但不直接提交表单；
- 获取表格中用户选中的记录；
- 根据自然语言设置筛选条件；
- 打开指定记录的详情页；
- 调用已有前端动作，并把执行结果返回给 AI。
这种模式特别适合 JS 区块，因为开发者可以在区块中编写少量 JavaScript，把 NocoBase 页面能力封装成参数明确的工具。AI 不必知道组件树或 DOM 结构，只需理解工具名称、参数定义和返回值。
它也带来了一条重要边界：前端工具运行在用户浏览器中，不能替代服务端鉴权。隐藏按钮、禁用输入框或在工具描述中写“仅管理员使用”，都不构成权限控制。任何读取或修改业务数据的动作，最终仍应由服务端依据当前用户身份校验。
三个分支该怎么选
更新摘要给出了清晰的分支定位：
| 分支 | 定位 | 适用场景 |
|---|---|---|
main |
当前最稳定，官方推荐安装 | 生产环境、关键业务系统 |
next |
包含即将发布并经过初步测试的功能 | 验证前端 AI 工具、提交反馈、预发布测试 |
develop |
持续开发中的版本 | 插件开发、源码调试、跟踪最新改动 |
如果前端 AI 工具尚未进入你所使用的 main 版本，可以在隔离环境中使用 next 验证，不要直接替换生产实例。验证环境至少应该复制权限模型和典型页面配置，但应使用脱敏数据。
切换源码分支前，可以这样检查并创建独立测试分支：
git fetch origin --prune
git branch -r | grep -E 'origin/(main|next|develop)$'
git switch -c test-frontend-ai origin/next
具体构建和启动命令应以仓库当前版本的项目文件为准。不要在包含未提交修改的工作目录中直接切换分支，也不要让 next 环境与生产环境共用数据库。
可以这样封装一个只读 AI 工具
下面是一个可改造的 JS 区块示例。由于摘要没有给出 NocoBase 当前版本的确切注册 API，示例假设运行环境提供 ctx.ai.registerTool()，并通过 ctx.form.getValues() 读取当前表单。使用前需要把这两个接口替换为所安装版本实际暴露的上下文 API。
// Assumption: ctx is provided by the JS block runtime.
const unregister = ctx.ai.registerTool({
name: 'get_current_form_summary',
description: 'Read selected fields from the current form for summarization.',
inputSchema: {
type: 'object',
properties: {
fields: {
type: 'array',
items: { type: 'string' },
description: 'Allowed field names to return'
}
},
required: ['fields'],
additionalProperties: false
},
async execute({ fields }) {
const allowedFields = new Set(['title', 'status', 'owner', 'description']);
const values = await ctx.form.getValues();
return Object.fromEntries(
fields
.filter((field) => allowedFields.has(field))
.map((field) => [field, values[field] ?? null])
);
}
});
// Call unregister() when the block is unmounted if the runtime requires cleanup.
这里没有把整个表单原样交给模型，而是使用字段白名单。这样可以避免密码、令牌、内部备注或个人信息因页面状态变化而意外进入 AI 上下文。
工具描述也应保持具体。与其注册一个范围模糊的 manage_record，不如拆成 read_selected_record、draft_filter 和 request_record_update。工具越小，参数验证、授权和审计越容易落实。
写操作需要增加确认和审计
如果工具要修改记录，可以这样实践：让 AI 只生成变更草案，前端展示差异并要求用户确认，确认后再调用受权限保护的服务端 API。
async function proposeStatusChange({ recordId, nextStatus }) {
const allowedStatuses = new Set(['pending', 'approved', 'rejected']);
if (!allowedStatuses.has(nextStatus)) {
throw new Error('Unsupported status');
}
const confirmed = window.confirm(
`Change record ${recordId} status to ${nextStatus}?`
);
if (!confirmed) {
return { ok: false, reason: 'cancelled_by_user' };
}
const response = await fetch(`/api/records/${encodeURIComponent(recordId)}`, {
method: 'PATCH',
headers: { 'Content-Type': 'application/json' },
credentials: 'same-origin',
body: JSON.stringify({ status: nextStatus })
});
if (!response.ok) {
throw new Error(`Update failed with HTTP ${response.status}`);
}
return { ok: true, record: await response.json() };
}
示例中的 /api/records/:id 是占位接口，需要替换为实际资源 API。服务端必须再次验证用户是否能修改该记录、状态迁移是否合法，并记录操作者、工具名称、参数摘要和执行结果。浏览器确认框可用于最小验证，正式界面更适合使用能展示变更前后内容的确认对话框。
上线前的检查清单
采用前端 AI 工具时，可以按以下顺序推进：
- 在
next的隔离环境中确认 API、生命周期和异常处理方式。 - 优先注册只读工具，再逐步引入带确认步骤的写工具。
- 为参数设置 JSON Schema、枚举、长度和字段白名单。
- 确认服务端权限不依赖前端按钮或工具可见性。
- 检查发送给模型的数据是否包含个人信息、密钥或内部备注。
- 记录工具调用日志，并为失败、超时和重复调用设计处理逻辑。
- 等目标功能进入稳定分支并完成回归测试后，再考虑生产部署。
JS 区块注册前端 AI 工具缩短了“自然语言意图”到“页面动作”之间的距离，但也扩大了前端代码可以触达的业务范围。最稳妥的采用方式，是从受控读取开始，把写操作放在确认、鉴权和审计之后，并根据 main、next、develop 的定位选择合适环境。