AI识别标注服务插件设计文档

一、功能概述

1.1 定位

@youchaoyun.com/plugin-ai-identification-annotation 是一个服务型插件，采用”记录表 + 默认工作流 + 按钮 + 后台设置”架构，在 NocoBase 本端承担以下职责：

示例业务：本文档以工地安全 AI 识别为示例业务场景贯穿说明，所有提示词、结构化输出均围绕”施工现场安全巡检 → YOLO 违规目标标注 + 合规检查文本输出”展开。该业务可替换为任意”图片 → AI 识别 → 结构化标注”的场景。

1. 本端创建默认 AI 员工：插件安装/启用/启动时创建 yolo AI 员工；知识库绑定留空，由用户在 AI 员工管理界面自行配置模型 / 知识库。
2. 本端创建默认工作流”工地安全AI识别”：插件启动时自动创建一条名为”工地安全AI识别”的默认工作流（collection 触发器 + AI 员工节点 + 更新记录节点），AI 员工节点配置按预设提示词与结构化输出直接硬编码（不通过变量绑定从预设表读取），用户开箱即用。
3. 提供 AI 识别标注按钮：可在任意业务表的”表头批量动作”与”行操作”中配置，按钮直接指定要触发的工作流 Key，点击 → 提取用户选中附件字段的图片 URL（一个或多个）→ 自动创建 标注记录 记录并触发指定工作流。
4. 提供 AI 标注后台设置：管理员可在后台设置页直接修改关联工作流中 AI 员工节点的参数（背景提示词、用户输出、结构化输出），无需进入工作流编排界面；并按数据来源做权限控制。
5. 提供提交记录 API：人工标注端调用 submit 创建一条记录 → 触发关联工作流 → 异步处理 → 结果写回记录表（通过监听 executions 表自动同步状态）。

1.2 核心优势

• 默认工作流开箱即用：插件启动时自动创建”工地安全AI识别”默认工作流（含触发器、AI 员工节点、更新节点），AI 员工节点具有默认预设值；后续可在工作流界面自由扩展（条件分支、通知、并行等）。
• 按钮即触发：业务表上配置”AI 识别标注”按钮后，按钮直接指定要调用的工作流，用户选中附件记录点击即提交，无需自建提交界面；支持表头批量与行操作两种位置。
• 统一记录表规避单表限制：所有来源的图像（监控截图 / 附件上传 / 详情页按钮）统一写入 标注记录 表，工作流只需监听这一张表，规避了 NocoBase 工作流 collection 触发器只能绑定单表的限制。
• 工作流可视化编排：AI 处理由 NocoBase 工作流完成，非开发人员可在工作流界面调整流程，无需改代码。
• AI 员工节点直接硬编码 + 后台直改：AI 员工节点的背景 / 用户输出 / 结构化输出由插件创建时直接写入节点 config（不通过变量绑定），后台设置页可绕开工作流编排界面直接修改这三项；并按触发数据表过滤仅展示本插件业务关联的工作流。
• 图片通过 files 字段传入：AI 员工节点原生支持 file_url 类型，自动下载图片并转为 AI 视觉模型可读的附件。
• 解耦知识库：AI 员工仅创建外壳，知识库、模型等由用户在 AI 员工管理界面自由配置。
• 幂等初始化：AI 员工、默认工作流在 install / afterEnable / beforeStart 三处均检查并补建/同步。

---

二、架构设计

2.1 架构模式

flowchart TD
    subgraph Admin[本端管理员]
        A2[AI员工管理界面 配置模型/知识库]
        A3[工作流界面 编排流程]
        A4[AI 标注后台设置 直改 AI 员工节点参数]
        A5[业务表配置 AI 识别标注按钮]
    end

    subgraph Client[人工标注端 / 业务用户]
        B2[submit 提交 imageUrl]
        B3[轮询 get 获取 status 与结果]
        B4[在业务表选中附件记录 → 点击 AI 识别标注按钮]
    end

    subgraph Plugin[plugin-ai-identification-annotation]
        C2[(标注记录 记录表)]
        C4[REST: 标注记录 submit/get/list/triggerByButton]
        C5[按钮 Schema: 表头/行 配置项]
        C6[REST: aiAnnotationSettings 后台设置]
        C7[createDefaultWorkflow 默认工作流]
    end

    subgraph Workflow[NocoBase 工作流]
        W0[默认工作流 工地安全AI识别]
        W1[collection 触发器 监听记录表新增]
        W3[AI员工节点 硬编码配置]
        W4[更新记录节点 写回结果]
    end

    subgraph AI[AI 能力]
        E[NocoBase AI Plugin]
        F[LLM Provider]
    end

    A2 --> E
    A4 --> C6
    C6 -- 过滤触发数据表/key前缀 --> W0
    A5 --> C5

    B2 --> C4
    C4 -- 创建记录 --> C2
    B3 --> C4
    C4 -- 读取记录 --> C2
    B4 --> C5
    C5 -- 直指定 workflowKey + 提取选中附件图片URL --> C4

    C2 -- 新增触发 --> W1
    W1 -- 触发 --> W3
    W3 -- 调用 --> E
    E -- 请求 --> F
    F -- 返回结果 --> E
    E -- 返回结果 --> W3
    W3 -- 输出结果 --> W4
    W4 -- 写回 --> C2

    C7 -- 启动时创建 --> W0

2.2 职责边界

职责（本插件）	非职责（由人工标注端 / 业务端负责）
监听 标注记录 表	人工标注 UI、其他业务表触发方式定义
创建默认 AI 员工 yolo（知识库留空）	配置 AI 员工的模型 / 知识库（AI 员工管理界面进行）
创建默认”工地安全AI识别”工作流（含触发器与节点链）	工作流扩展编排（管理员在工作流界面完成）
submit API：创建记录触发工作流	业务表附件字段定义
提供 AI 识别标注按钮 Schema（表头/行配置项）	业务表本身的数据维护
AI 标注后台设置 API：直改关联工作流 AI 员工节点参数	工作流结构本身的增删节点
监听 executions.afterUpdate 自动同步记录状态

---

三、数据设计

3.1 AI 识别标注按钮配置

按钮配置不单独建表，使用 NocoBase Schema 机制存储于按钮所在业务表的 ui_schemas 中。按钮 Schema 内的关键配置项：

配置项	类型	必填	说明
attachmentField	string	是	业务表中”附件”字段名（解析时取其下的图片 URL 列表）
workflowKey	string	是	按钮直指定要触发的工作流 Key（默认指向插件创建的”工地安全AI识别”工作流）
multiple	boolean	否	是否允许一次提取多张图片（true → 批量创建多条记录；false → 仅取第一张）
confirm	boolean	否	点击是否需二次确认

按钮注册为 NocoBase 的 customize:bulkAction（表头批量动作）与 customize:recordAction（行操作）两类 Schema 项，配置 UI 由插件的 SchemaInitializer + SettingsForm 提供。

3.2 AI 标注后台设置存储

后台设置页不单独建表，直接复用工作流图节点配置（flow_nodes 表）：

• 通过 workflowKey 反查 workflows.key → 取 flow_nodes 中 type='ai-employee' 的节点 → 修改其 config 字段。
• 修改项仅限：config.message.system（背景）、config.message.user（用户输出）、config.structuredOutput.schema（结构化输出）。
• 不修改触发器、更新节点结构、AI 员工 username / files / model / userId 等。

权限策略存储于 NocoBase ACL 角色资源中（见 §6.4）。

---

四、API 设计

4.1 AI 识别标注按钮触发 API

按钮点击后由前端调用，封装了”从选中附件提取图片 URL → 批量创建记录 → 触发指定工作流”的完整流程。

POST /api/标注记录:triggerByButton
Content-Type: application/json

{
  "collection": "inspectionRecords",
  "attachmentField": "photos",
  "recordIds": [101, 102],
  "workflowKey": "ai-annotation-safety-inspection",
  "multiple": true
}

参数	类型	必填	说明
collection	string	是	业务表 collection name
attachmentField	string	是	业务表附件字段名
recordIds	number[]	是	用户选中的业务表记录 ID 列表
workflowKey	string	是	按钮直指定要触发的工作流 Key
multiple	boolean	否	是否每张图片各创建一条记录（默认 true）

行为：

1. 服务端按 collection + attachmentField + recordIds 拉取附件数据，提取每张图片的 URL。
2. 为每张图片在 标注记录 创建一条记录（sourceCollection/sourceId/workflowKey/aiEmployee='yolo' 同步写入，presetId 留空）。
3. 调用 workflowPlugin.execute() 精确触发 workflowKey 对应的当前启用工作流版本。
4. 返回每条记录的 id / status / executionId。

响应

{
  "code": 200,
  "msg": "success",
  "isSuccess": true,
  "data": {
    "records": [
      { "id": 11, "status": "pending", "executionId": 9001, "imageUrl": "https://.../a.jpg" },
      { "id": 12, "status": "pending", "executionId": 9002, "imageUrl": "https://.../b.jpg" }
    ]
  }
}

4.3 AI 标注后台设置 API

• 资源名：aiAnnotationSettings
• 动作：listWorkflows / getWorkflowConfig / updateAINodeConfig / getDefaultWorkflow
• 权限：loggedIn（细粒度权限见 §6.4）

列出可管理的工作流（仅本插件业务关联的）

GET /api/aiAnnotationSettings:listWorkflows

返回仅包含触发数据表为 标注记录 的工作流（，或 workflowKey 以插件前缀 ai-annotation- 开头的工作）。两种过滤策略见 §6.2。

获取某工作流 AI 员工节点当前配置

GET /api/aiAnnotationSettings:getWorkflowConfig?filterByTk=<workflowId>

返回：

{
  "data": {
    "workflowId": 1,
    "workflowKey": "ai-annotation-safety-inspection",
    "title": "工地安全AI识别",
    "aiNode": {
      "nodeId": "abc123",
      "aiEmployee": "yolo",
      "systemPrompt": "...",
      "userMessage": "...",
      "structuredOutput": { ... }
    }
  }
}

修改 AI 员工节点参数

POST /api/aiAnnotationSettings:updateAINodeConfig
Content-Type: application/json

{
  "workflowId": 1,
  "nodeId": "abc123",
  "systemPrompt": "（新）背景提示词...",
  "userMessage": "（新）用户输出...",
  "structuredOutput": { ... }
}

行为：直接更新 flow_nodes 表中 id=nodeId 的 config 字段对应子项；其余配置项保持不变。

获取默认工作流

GET /api/aiAnnotationSettings:getDefaultWorkflow

返回插件创建的默认工作流 Key 与基本信息，供按钮默认配置使用。

---

五、AI 识别标注按钮设计

5.1 按钮配置位置

按钮支持两种配置位置：

位置	Schema 类型	触发对象	典型场景
表头	customize:bulkAction	用户勾选的多条记录	批量为多条记录的附件触发识别
行操作	customize:recordAction	单条记录	为某条记录的附件触发识别

按钮通过 SchemaInitializer 注册到业务表的”配置按钮”菜单中，命名”AI 识别标注”。

5.2 按钮配置项（SettingsForm）

按钮 Schema 内嵌 x-settings，点击”配置”按钮弹出 SettingsForm：

• 附件字段（attachmentField）：下拉选择当前业务表的附件类型字段。
• 关联工作流（workflowKey）：下拉选择启用的、且（ Key 以插件前缀 ai-annotation- 开头）的工作流；默认选中插件创建的”工地安全AI识别”工作流。
• 多张提取（multiple）：开关，默认开启；关闭时仅取首张图片。
• 二次确认（confirm）：开关，默认开启。

5.3 点击行为

1. 收集选中记录：
   • 表头批量动作：取 useTableSelectedRecords() 的勾选记录 ID 列表。
   • 行操作：取当前行记录 ID 单元素列表。
2. 校验：未勾选记录时提示”请至少选择一条记录”；附件字段为空时提示。
3. 调用 triggerByButton API（§4.1）：服务端拉附件 → 解析图片 URL → 批量建记录 → 触发按钮指定的工作流。
4. 结果展示：
   • 同步返回每条记录的 id 与 executionId 后，前端可弹出”已提交 N 条，正在处理”的轻提示。
   • 可选：弹窗内轮询各 record.id 的 status，全部完成后展示汇总结果（违规目标数量 / 风险等级等）。

5.4 权限控制

• 按钮触发 API 标注记录:triggerByButton 受 loggedIn + 资源 ACL 控制；
• 业务表读取附件数据时复用当前用户在该业务表上的读权限（无权读取的记录会被自动过滤，避免越权触发）；
• （触发的工作流 Key 必须以插件前缀 ai-annotation- 开头（即由本插件创建或纳入管理范围），避免按钮被配置为触发任意工作流。）

---

六、AI 标注后台设置

6.1 设置入口

插件在 NocoBase 设置中心注册”AI 标注后台设置”菜单项，进入后展示仅与本插件业务关联的工作流列表，每个工作流行可进入”AI 员工节点参数”编辑页。

6.2 工作流过滤策略

后台设置页只列”本插件业务关联”的工作流，过滤策略二选一（默认两者并集）：

策略 A：按触发数据表过滤

• 读取工作流的 config.trigger 节点配置，取其 collection 字段。
• 仅当 collection === '标注记录' 时纳入列表。
• 优点：严格按数据流，确保后台设置改的就是本表关联的工作流。
• 缺点：依赖触发器配置正确。

策略 B：按 workflowKey 前缀过滤？

• 仅纳入 workflowKey 以插件前缀 ai-annotation- 开头的工作流（即由本插件 createDefaultWorkflow 创建或后续纳入插件管理范围的工作流）。
• 优点：不依赖触发器配置，能覆盖未来插件扩展创建的同类工作流。
• 缺点：要求新工作流遵循 Key 前缀约定。

默认实现：取 A ∪ B 并集，确保既覆盖 collection 触发器路径，也覆盖插件管理的工作流。

6.3 AI 员工节点参数修改

进入某工作流的设置页后，可修改以下三项（直接写入工作流节点 config，非通过变量绑定）：

修改项	节点 config 路径	说明
背景提示词	config.message.system	AI 员工的 system message
用户输出	config.message.user	AI 员工的 user message（纯文本指令）
结构化输出	config.structuredOutput.schema	结构化输出 JSON Schema

修改范围限制：

• 仅修改 type='ai-employee' 类型的节点；其他节点不可改。
• 不修改 username（AI 员工选择）、files（图片传入）、model、userId 等。
• 修改后调用工作流插件的”保存节点”逻辑，使新版本即时生效（无需重新启用工作流）。

设计说明：插件创建默认工作流时，AI 员工节点 config 的 message.system / message.user / structuredOutput 三项已按先前预设的提示词与结构化输出直接硬编码写入；后台设置页是这三项参数的唯一修改入口——避免引入额外的预设表做参数中转，简化数据流。

6.4 数据来源权限控制

不同业务数据来源对 AI 标注后台设置的可见性 / 可改性不同：

数据来源	可见工作流范围	可改 AI 节点参数	说明
工地安全（默认业务）	默认工作流	是	管理员可在后台设置自由修改
业务表自定义工作流	该业务表按钮配置的工作流（需触发数据表为 标注记录）	是（仅 AI 节点三项）	业务负责人可改本业务线的工作流
其他工作流	不可见	不可改	不在过滤策略 A ∪ B 范围内的工作流

实现方式：

• 通过 NocoBase ACL 角色资源控制：后台设置 API aiAnnotationSettings:* 配置细粒度策略，按 workflowKey 维度分配；
• 业务负责人角色绑定 workflowKey 白名单，仅可访问本业务线工作流；
• 系统管理员角色可访问全部过滤策略命中的工作流。

---

七、工作流编排

7.1 默认工作流”工地安全AI识别”（插件自动创建）

插件启动时调用 createDefaultWorkflow() 创建一条名为”工地安全AI识别”的工作流，开箱即用：

项	值
title	工地安全AI识别
key	ai-annotation-safety-inspection（稳定常量，跨版本不变）
enabled	true
current	true
trigger.type	collection
trigger.config.collection	标注记录
trigger.config.mode	1（新增后触发）

节点链（自动创建，AI 员工节点直接硬编码）

触发器（标注记录 新增）
   ↓
节点1：AI 员工节点（直接硬编码配置，非变量绑定）
       username:           'yolo'                                  (硬编码)
       message.system:     （预设 DEFAULT_PRESET.systemPrompt 全文，硬编码）
       message.user:       （预设 DEFAULT_PRESET.userMessage 全文，硬编码）
       files[0].type:      file_url
       files[0].value:    {{$context.imageUrl}}                    (图片 URL 仍需变量，每条记录不同)
       structuredOutput:   （预设 DEFAULT_PRESET.structuredOutput 对象，硬编码）
   ↓
节点2：更新记录节点
       更新 标注记录
       filterByTk: {{$context.id}}
       values:
         annotationData: {{$jobsById.节点1.result}}
   ↓
（状态由插件监听 executions.afterUpdate 自动同步，无需更新 status 节点）

关键设计点：

• AI 员工节点 config 直接硬编码：背景提示词 / 用户输出 / 结构化输出按默认值直接写入节点 config 字段。
• 唯一仍用变量的字段是 files[0].value：图片 URL 因每条记录不同，必须通过 {{$context.imageUrl}} 从触发记录上下文读取；其余参数全部硬编码。
• 后续修改这三项参数请通过 §六”AI 标注后台设置”页直接改 flow_nodes.config，避免在工作流编排界面手改节点 config。

7.2 触发器

• 类型：collection 触发器
• 监听表：标注记录
• 事件：新增记录后触发

默认工作流由 submit / triggerByButton API 通过 workflowPlugin.execute(workflow, { data: record }, { manually: true }) 手动触发（创建记录时 skipWorkflow=true）。

7.3 图片处理

AI 员工节点原生支持 file_url 类型（files.ts:84-128）：

• 自动 axios.get 下载图片 URL
• 写入 aiFiles 集合
• 转为带 source 标记的附件对象
• 作为 attachmentPart 附加到 userMessages

---

八、插件初始化机制

AI 员工创建、默认工作流创建在三个生命周期钩子中幂等执行：

时机	执行内容	说明
install()	createPresetAIEmployee() + createDefaultWorkflow()	插件首次安装
afterEnable()	db2cm 同步记录表 + createDefaultWorkflow()	插件启用后同步
beforeStart	createPresetAIEmployee() + createDefaultWorkflow()	每次应用启动均检查

8.1 createPresetAIEmployee()

• 按 username: 'yolo' 检查是否已存在；
• 不存在则创建：enableKnowledgeBase=false，知识库留空；
• 已存在则跳过（不改动模型 / 知识库等可编辑字段）。

8.2 createDefaultWorkflow()

• 按 key: 'ai-annotation-safety-inspection' 查 workflows 表；
• 不存在则创建：默认工作流”工地安全AI识别”（含触发器 + 2 个节点，见 §7.1），enabled=true、current=true；AI 员工节点 config 的 systemPrompt / userMessage / structuredOutput 值直接硬编码写入；
• 已存在则比对节点链关键配置（触发器 collection、AI 员工节点的三项硬编码参数、更新节点的 annotationData 绑定），有变化则同步更新为新版本（保留用户扩展节点不动，仅同步插件管的 2 个核心节点）；
• 重要：若管理员已通过后台设置页（§6.3）修改过 AI 员工节点参数，则启动时不再覆盖这三项（与”已修改则跳过”的幂等策略一致），仅同步触发器与更新节点结构。

---

九、设计约束与注意事项

1. 依赖项：

   • @nocobase/plugin-ai：定义 aiEmployees 表（本插件创建 yolo 员工写入此表）、AI 员工节点类型（默认工作流与后台设置均操作该节点类型）。
   • @nocobase/plugin-workflow：工作流引擎、workflows / flow_nodes / executions / jobs 表。

2. 前置条件（由管理员完成）：

   • 在 AI 员工管理界面为 yolo 员工配置好可用的模型（Model）；
   • 如需知识库，在 AI 员工管理界面为 yolo 绑定对应知识库；
   • 默认工作流由插件自动创建，无需手工编排；如需扩展流程，可在工作流界面新增节点（不要删除插件管的 2 个核心节点）。

3. 异步处理：

   • submit 与 triggerByButton API 创建记录并触发工作流后立即返回，不等待 AI 结果；？
   • 状态由插件监听 executions.afterUpdate 自动同步（pending → processing → completed/failed），无需在工作流中加更新状态节点；
   • 建议轮询间隔 2-5 秒，超时阈值 60-120 秒。

4. 安全性：

   • update 动作开放给工作流”更新记录”节点写回结果；
   • triggerByButton 受按钮所在业务表的读权限二次约束；
   • aiAnnotationSettings:* 按角色 workflowKey 白名单做细粒度权限。

5. 数据同步：

   • yolo AI 员工一旦创建后，插件不会覆盖其可编辑字段；
   • 默认工作流的 2 个核心节点配置在启动时会被同步更新（AI 员工节点参数若已被后台设置页改过则跳过），用户扩展节点不动。

6. 业务示例替换：

   • 默认工作流”工地安全AI识别”的提示词与结构化输出围绕”施工现场安全巡检 → YOLO 违规目标标注 + 合规检查文本”展开；
   • 若需替换为其他业务（如设备缺陷识别、农产品病害识别），可在后台设置页直接改 AI 员工节点三项参数，或在工作流界面新建 Key 以 ai-annotation- 前缀开头的工作流，不影响默认”工地安全AI识别”工作流。