nocobase-ai-employee

目标

为 NocoBase 业务界面配置合适的 AI 员工，并安全地负责其受支持的生命周期。判断需求应使用内置 UI 操作、JS 操作、工作流还是 AI 员工；然后复用、创建、维护和验证配置，并将最终的 UI 放置工作移交给 nocobase-ui-builder。

范围

• 判断请求是否需要 AI 员工，并选择或创建合适的非开发人员员工。
• 检查、创建、更新、启用、停用、验证并安全删除受支持的 AI 员工记录。
• 配置受支持的资料字段和专用聊天模型限制。
• 准备公开的 AI 员工操作契约，并将 UI 放置工作移交给 nocobase-ui-builder。

非目标

• 不配置 LLM 提供商或已保存的服务；请使用 nocobase-ai-manager。
• 不判断知识库使用权限，也不创建向量数据库、知识库或文档；请使用 nocobase-ai-knowledge-base-manager。
• 不通过编写原始 Flow Model 或数据库行来放置操作；请使用 nocobase-ui-builder。
• 不要在业务界面或 AI Portal 界面上公开开发人员员工。

必需的移交技能

• 使用 nocobase-ui-builder 编写 Modern 页面／区块／操作，并放置 AI 员工操作。
• 如果需求需要在 AI 操作生效前新增集合、字段或关系，请使用 nocobase-data-modeling。
• 如果 AI 员工需要调用或触发工作流工具，或者任务主要是确定性的后端自动化，请使用 nocobase-workflow-manage。
• 创建或更改专用 modelSettings 前，请使用 nocobase-ai-manager。
• 如果请求需要知识库功能、资源或绑定准备，请使用 nocobase-ai-knowledge-base-manager。

输入契约

输入	必填	默认值	验证	澄清问题
action	是	decide	以下之一：decide/inspect/create/update/delete/verify/place	"应执行哪项 AI 员工操作？"
env	否	nb env list 中的当前环境	已配置、可访问且已通过身份验证	"应针对哪个 NocoBase 环境操作？"
username	记录变更时必填；决策／检查时可选	无	精确且稳定的用户名，且唯一匹配	"员工的准确用户名是什么？"
targetSurface	放置时必填	无	精确的页面／区块／操作上下文	"应在哪个 UI 界面公开该员工？"
changes	创建／更新时必填	保留未提及的值	受支持的可写字段或经验证的专家移交	"要更改哪些员工字段？"
confirmation	高风险操作时必填	无	展示影响后，对确切目标进行新的确认	"请确认此次确切的可用状态、模型、身份或删除变更。"

规则：

• 如果缺少必需输入或依赖项尚未就绪，请停止变更并请求澄清。
• 如果用户说“由你决定”，则只检查并推荐可复用的候选项；不要创建或修改记录。
• 不要悄悄将重复创建转换为更新，也不要悄悄丢弃不受支持的字段。

强制澄清门槛

• 最多澄清 2 轮；每轮最多提问 3 个。
• 变更前，确认环境、准确用户名、计划修改的可写字段、启用状态、模型引用及任何专家移交。
• 模型变更必须取得 nocobase-ai-manager 当前的就绪结果。
• 停用、模型变更、身份变更和删除必须遵循安全门槛中的影响评估及二次确认规则。

决策门

在编写任何内容之前，先对用户请求进行分类：

需求	优先选择
固定的 CRUD、导航、可见性、筛选、字段赋值或简单按钮行为	通过 nocobase-ui-builder 配置内置 UI 操作 / 响应
确定性的客户端计算、格式化、验证或数据转换	通过 nocobase-ui-builder 配置 JS 操作 / JS 界面
确定性的多步骤服务端自动化、审批、通知或定时任务	通过 nocobase-workflow-manage 配置工作流
自然语言解读、意图模糊、从杂乱文本中提取信息、摘要、分类、起草、建议、数据洞察叙述、工具选择或模型判断	AI 员工操作

仅当模型判断能显著减少歧义，或能为用户提供自然语言任务界面时，才选择 AI 员工。不要用 AI 员工替代常规的确定性 UI 配置。

工作流

1. 分解请求

   • 确定目标页面／区块／操作槽位、目标集合、当前记录还是整个区块的上下文，以及预期的用户交互。
   • 将确定性的设置与非确定性的模型工作拆分开。
   • 如果无法唯一确定目标 UI 界面，先使用 nocobase-ui-builder 检查路由。

2. 判断是否适合使用 AI 员工

   • 应用决策关卡。
   • 如果不适合使用 AI，则移交给相关技能，并说明更精简的处理路径。
   • 如果适合使用 AI，则编写简洁的任务契约：员工角色、输入上下文、预期输出、是否自动发送、是否使用网页搜索，以及所需的工具／技能。

3. 查找现有 AI 员工

   • 优先使用 aiEmployees:listByUser 查找用户可见的员工。
   • 对于业务和 AI Portal 界面，筛选 enabled=true、deprecated=false、角色可见且 category!="developer" 的记录。即使类别元数据缺失或过时，也要排除已知开发者用户名 nathan、dara、lina 和 orin。
   • 根据角色、职位、简介、现有工具和 modelSettings 进行匹配。
   • 仅在需要具体资源名称、字段或载荷结构时，才读取 references/ai-employee-api.md。

4. 复用或创建

   • 如果现有员工的角色匹配度高，且其工具和模型限制兼容，则复用该员工。
   • 仅当没有现有员工的匹配度达到约 70%，或用户明确要求专属员工时，才创建新员工。
   • 对于新员工，bio 面向用户，操作行为放在 about 中。
   • 对于新员工，在调用 aiEmployees:create 之前，验证创建载荷中的 avatar 已设置为受支持的头像种子。
   • 如果 avatar 缺失、为空、为 null 或不受支持，则将其设为默认的受支持种子 nocobase-015-male。
   • 业务或 AI Portal 交互中，绝不创建开发者类别的员工。
   • 如果操作使用 nb api ai employees，请遵循 员工记录管理；该更严格的安全字段契约约束记录写入。

5. 将员工绑定到区块

   • 绑定之前，读取所选员工的信息；如果员工的 category="developer" 或用户名是已知开发者用户名，则拒绝操作。开发者员工仅用于专属的 NocoBase 构建器／编辑器界面；不要在面向用户的 Portal 交互中添加、公开或选择他们。
   • 使用 nocobase-ui-builder 及其 AI 员工操作参考。
   • 仅使用公开的操作结构：type: "aiEmployee"，并设置 settings.username、settings.auto、settings.workContext、settings.tasks、settings.style。
   • 不要写入原始 props、stepParams、flowModels 或数据库行。
   • 对于区块／表单／记录上下文，默认使用 workContext: [{ "type": "flow-model", "target": "self" }]。

6. 验证

   • 如果发生了写入操作，则通过 nocobase-ui-builder 读取目标界面或进行检查。
   • 验证 AI 操作指向预期的非开发者用户名，且任务消息符合预期。
   • 如果创建了新员工，验证其针对预期角色显示在 aiEmployees:listByUser 中，并确认其 avatar 非空且仍是受支持的头像种子之一。如果该员工不可见，请说明需要进行的角色／ACL 后续处理。

员工匹配规则

适用时优先使用业务内置员工：

• atlas：将宽泛的请求分派给其他员工，或协调子 Agent。
• dex：从杂乱文本中提取、清理和整理信息，或填写表单。
• viz：分析数据并生成洞察或报告。
• ellis：理解、总结邮件并起草回复。
• lexi：为业务用户提供翻译和本地化服务。

切勿在业务或 AI Portal 界面中使用开发者员工。这包括任何 category="developer" 的员工，以及已知用户名 nathan、dara、lina 和 orin。当任务需要特定领域行为、受限的模型集、专用自定义工作流工具，或需要向业务用户公开的角色／人设时，请创建专用业务员工。

头像载荷规则

• avatar 是预设种子字符串，不是上传的文件对象或外部图片 URL。
• 默认种子：nocobase-015-male。
• 每个新的 aiEmployees:create 载荷都必须包含 avatar。
• 创建前，根据以下支持的种子验证 avatar。如果值缺失、为空、为 null 或不受支持，则替换为 nocobase-015-male。
• 创建后，通过 aiEmployees:list 或 aiEmployees:listByUser 读取员工记录，并确认存在 avatar。

支持的头像种子：

nocobase-001-male
nocobase-002-male
nocobase-003-female
nocobase-004-male
nocobase-005-female
nocobase-006-male
nocobase-007-male
nocobase-008-female
nocobase-009-female
nocobase-010-male
nocobase-011-male
nocobase-012-male
nocobase-013-female
nocobase-014-female
nocobase-015-male
nocobase-016-female
nocobase-017-female
nocobase-018-female
nocobase-019-female
nocobase-020-female
nocobase-021-male
nocobase-022-male
nocobase-023-female
nocobase-024-male
nocobase-025-male
nocobase-026-male
nocobase-027-female
nocobase-028-male
nocobase-029-male
nocobase-030-male
nocobase-031-female
nocobase-032-male
nocobase-033-male
nocobase-034-female
nocobase-035-male
nocobase-036-female
nocobase-037-male
nocobase-038-female
nocobase-039-female
nocobase-040-female
nocobase-041-male
nocobase-042-male
nocobase-043-male
nocobase-044-male
nocobase-045-female
nocobase-046-female
nocobase-047-male
nocobase-048-female
nocobase-049-male
nocobase-050-female
nocobase-051-female
nocobase-052-female
nocobase-053-male
nocobase-054-female
nocobase-055-male
nocobase-056-female
nocobase-057-female
nocobase-058-female
nocobase-059-male
nocobase-060-female

任务约定模板

确定归属前，使用此内部模板：

{
  "intent": "what the user wants",
  "targetSurface": "page/block/action slot",
  "decision": "builtin|js|workflow|ai-employee",
  "employee": {
    "mode": "reuse|create",
    "username": "candidate-or-new-username",
    "role": "short business role",
    "reason": "why this employee fits"
  },
  "aiAction": {
    "auto": false,
    "autoSend": false,
    "context": "self|named block|record",
    "taskTitle": "short button/task title",
    "systemMessage": "stable operational constraints",
    "userMessage": "what the employee should do with the block context",
    "webSearch": false
  }
}

员工记录管理

重要

原有的 nocobase-ai-employee-manager 技能已移除并弃用。现在，所有受支持的员工记录操作均使用 nocobase-ai-employee。

本章是对上述决策、员工匹配、头像、操作约定和 UI 放置工作流的补充，而非替代。请将操作细节保留在随附的参考文档中，不要在此主文件中展开。

记录管理规则

• 使用 nb api ai employees 前，请先阅读 employee-command-map.md、employee-record-fields.md 和 employee-record-workflows.md。
• 确定一个准确且稳定的 username；创建前确认其不存在，创建后绝不更改身份信息。
• 仅写入所选 API 接口支持的字段，保留未提及的字段，并拒绝受保护字段，不得静默丢弃。
• 仅在创建或更改专用 modelSettings 时运行 nocobase-ai-manager。
• 对于任何知识库相关需求，使用 nocobase-ai-knowledge-base-manager 准备能力、资源和绑定；本技能仅执行已验证的员工字段交接，不重复知识库规则。
• 每次创建或更新后都要读取记录。绝不删除内置员工；删除自定义员工前，必须获得针对该目标的最新明确确认。
• 按照 employee-record-workflows.md 执行操作顺序、幂等性、确认、回滚和故障处理。

参考资料加载索引

参考资料	适用场景	备注
AI 员工 API	需要选择员工，或在 CLI 记录操作范围之外使用已确认的资源操作时。	核心字段、提示词语义和创建指南。
区块操作载荷	准备现代 UI AI 员工操作时。	公开的操作结构和放置交接。
示例	区分 AI 行为和确定性行为，或起草任务文本时。	可复用的决策和载荷。
员工命令索引	通过 nb api ai employees 检查或修改记录时。	支持的 CRUD、前置条件和排除项。
员工记录字段	构建员工记录载荷时。	可写字段、默认值和受保护字段。
员工记录工作流	创建、更新、停用、删除、验证或回滚时。	幂等性和安全操作顺序。

安全关卡

高影响操作包括更改身份、停用业务员工、更改专用模型设置，以及删除自定义员工。切勿写入受保护的内部字段或删除内置员工。

二次确认模板：

• “确认执行：在 <env> 环境中对 AI 员工 <username> 执行 <action>。预期影响：<availability/model/identity impact>。输入 confirm 以继续。”

回滚指南见 employee-record-workflows.md。验证失败后，切勿自动删除新员工；写入超时或返回 5xx 时，在读取回查前应将状态视为未知。

验证清单

• 已验证目标环境和员工命令／资源操作范围。
• 创建时用户名尚不存在；其他操作时已唯一确定目标用户。
• 用于业务或 AI Portal 部署的员工已确认不是开发人员。
• 创建载荷包含受支持的头像。
• 载荷仅包含所选操作范围允许写入的字段。
• 每次创建／更新后，都已独立读取回查安全字段。
• 绝不删除内置员工或修改其身份。
• 必须分别报告所需确认、允许的情况、拒绝的情况、错误和部分成功。

最简测试场景

1. 正常流程：检查并复用现有员工，避免不必要的前置操作。
2. 正常流程：创建或更新自定义员工，并通过读取回查进行验证。
3. 缺少必需输入或存在无效的受保护字段时，阻止修改。
4. 身份验证或权限失败时，停止执行并提供恢复指南。
5. 拒绝的情况：拒绝删除内置员工；删除自定义员工需要重新确认并验证其已不存在。

输出约定

最终回复必须说明环境、操作、确切用户名、已执行的安全命令、应用的默认值、使用的前置条件或专家交接、读取回查证据、确认、回滚限制、部分成功以及剩余的 UI 操作。

参考资料

• NocoBase AI 员工文档：用于检查当前产品行为。[已验证：2026-08-04]
• AI 员工 API：用于了解员工字段、提示词语义和已确认的资源操作。
• 区块操作载荷：用于了解公开的 UI 操作约定。
• 示例：用于参考分类和任务示例。
• 员工命令索引：用于了解受支持的 nb api ai employees 命令和排除项。
• 员工记录字段：用于了解安全字段架构、模型限制、默认值和受保护字段。
• 员工记录工作流：用于了解 CRUD、验证、回滚和删除安全流程。