Agent 控制平面工作台

本页是一篇完整方案指南:以开源 agent-control-plane 插件(com.auraboot.agent-control-plane,命名空间 acp)为例,讲清楚如何在 AuraBoot 上搭一套有治理的多 Agent 工作台。它是 config 型插件——16 个 model、53 条命令、33 个页面全部是 DSL JSON 声明,依赖另一个轻量插件 core-aurabot(只提供 AI 中心的导航菜单与权限)。下面每个 model、命令、权限、角色、状态值你都能在插件里 grep 到。

源码:agent-control-plane on GitHub ↗

适用场景:周期性运行的 Agent(竞品情报周报、巡检、对账、数据富化等)需要任务编排 + 审批门控 + 运行追踪 + 产出物留痕。agent-control-plane 不是为某一个垂直场景定制的,它是承载所有这类工作流的通用底座。

1. 用户场景

一支团队要把一批重复性强的工作交给 AI Agent 周期性执行。以「竞品情报周报」为例:

• 每周一定时触发,采集 Agent 从公开来源抓取信号 → 富化 Agent 规范化 → 撰写 Agent 起草周报;
• 涉及外部网页访问、超预算调用、对外发送邮件等高风险动作时,要暂停等人工审批;
• 每次运行要记录用了哪个模型、花了多少 token、多少钱、耗时多久;
• 最终周报作为产出物持久化,带质量评分和来源链接,事后可追溯;
• Agent 要能记住「上周用户偏好哪些竞品、要什么输出格式」,下次运行自动带上。

不同角色看到的工作台不同:运营负责人管使命与任务,审批人只处理审批队列,管理员配 Agent 定义与审批策略。

2. 需求痛点

• 聊天界面不可治理:扁平的对话框没有可重复执行路径、没有审批门控、没有成本记录,也产不出下游可用的制品。
• 高风险动作无门控:Agent 直接访问外部 API、发邮件、改数据,没有「先停下来等人确认」的机制,出事只能事后补救。
• 运行不可追溯:哪次运行调了什么工具、花了多少钱、产出了什么,散落在日志里,查不到也对不上账。
• Agent 无记忆:每次运行都要重新喂偏好,无法沉淀「这个租户/用户惯用的配置」。

这些都不是「再写一个聊天机器人」能解决的,而是把 Agent 动作纳入受控状态变更的问题。

3. 产品方案

在 AuraBoot 里,Agent 的每一个生命周期动作都是一条命令,走统一的 命令管道:

• 「完成任务」按钮调用 acp:complete_task,而不是裸写任务表;命令在管道里统一鉴权 → 校验 → 执行 → 审计,任务状态从 in_progress 推进到 done。
• 高风险动作落 agent_approval(审批)模型,由 approval_policy(审批策略)决定哪些动作需要人工确认(tool_call / data_change / external_api / cost_threshold / sensitive_action)。审批人用 acp:approve_request / acp:reject_request 处理队列。
• 每次执行写一条 agent_run,记录 run_model、input_tokens、output_tokens、total_cost、duration_ms;产物写 agent_artifact,带 run_id 回指运行。
• Agent 的长期偏好写 agent_memory,按 memory_type 分类、带 importance 和有效期,下次运行自动检索携带。

同一条命令既是 UI 按钮的目标,也能被调度计划(agent_schedule)、审批流和 Agent 运行时调用,所以「周一 08:00 自动跑一轮」和「人工点一下补跑」走的是同一套受控路径。

4. 功能设计

4.1 数据模型(16 个)

4.2 命令与状态机

命令命名 acp:<动词>_<名词>,共 53 条(各 model 的 create / update / delete,加上状态流转与审批自定义命令)。代表性命令:

每条命令都是一段声明。例如 acp:complete_task(config/commands.json)的真实定义:

{
  "code": "acp:complete_task",
  "displayName:zh-CN": "完成任务",
  "displayName:en": "Complete Task",
  "type": "state_transition",
  "modelCode": "agent_task",
  "stateField": "task_status",
  "fromStates": ["in_progress"],
  "toState": "done",
  "extension": {
    "confirmMessage:zh-CN": "确认完成此任务？",
    "confirmMessage:en": "Complete this task?"
  }
}

读出来的设计信息:这是一条 state_transition,只允许从 in_progress 推进到 done(agent_task.task_status)——其它状态点这个按钮会被管道拦下。extension.confirmMessage 让 UI 在执行前弹出二次确认。任务的完整状态机由 4 条命令构成:acp:start_task(todo → in_progress)、acp:complete_task(in_progress → done)、acp:block_task(in_progress → blocked)、acp:cancel_task(backlog/todo/in_progress/blocked → cancelled)。

审批类命令用 type: custom(如 acp:approve_request 绑 agent_approval),因为审批通过/拒绝要写多个字段并触发后续逻辑,不是单纯的单字段状态翻转。

4.3 权限与角色

13 个权限码(注意:这里的权限码是 acp_<资源> 下划线风格,与命令的冒号风格不同):

acp_agent_definition    acp_mission             acp_agent_task
acp_agent_run           acp_agent_artifact      acp_agent_schedule
acp_approval_policy      acp.agent.approval      acp_agent_memory
acp_agent_observation   acp_agent_tool          acp_agent_skill
acp_mission_control     AGENT_MANAGE

acp.agent.approval 专门控制审批队列处理权(可以审批别人提交的请求);acp_mission_control 控制能否进任务控制台首页;AGENT_MANAGE 控制能否创建/编辑自定义 AI 员工(agent_definition 中 is_employee=true 的)。

插件内置 1 个角色 acp_admin(ACP 管理员),聚合除 acp_agent_skill / AGENT_MANAGE 外的全部管理权限。落地真实组织时你会再拆出「运营」「审批人」「只读观察」等角色,各自挑选权限码——这正是把跨 UI / Controller / 导出的手工分支逻辑收敛成一份声明式角色配置的价值。

4.4 页面

33 个页面:17 个 list、15 个 form、1 个 detail。菜单按「Agent / 执行 / 语义配置 / 治理」分组:

• Agent:Mission Control(任务控制台 /p/acp_mission_control)、使命、任务、Agent 定义、工具、记忆、技能市场、MCP 服务器;
• 执行:运行记录、调度、产出物;
• 语义配置:对象别名、语义术语;
• 治理:业务动作、审批、审批策略、观测。

5. 具体开发与实施

先掌握基础。本插件没有任何后端 Java,全靠平台的几个核心契约。动手前请先读:Model 与 Field · Command · 命令管道 · Permission · 插件清单 · 纯配置 Plugin · Page Designer。

落地一个像 agent-control-plane 这样的 config 插件,步骤是:

1. 定义 model 与字段 —— config/models.json + config/fields.json,字段类型用平台 dataType(string / text / enum / integer / decimal / datetime / boolean / reference…),长度等约束写在 constraints(如 {"required": true, "maxLength": 64}),不要内联进类型名。详见 Model 与 Field。
2. 声明命令 —— config/commands.json,状态流转用 type: state_transition + stateField/fromStates/toState;复合写动作用 type: custom。详见 Command。
3. 配 model-field binding —— config/bindings.json 以 {modelCode, fieldCode, sequence, required, visible, editable} 把字段挂到 model 上,并在 resourceDirs.modelFieldBindings 注册(见「典型错误」)。
4. 设计页面 —— config/pages.json,列表/表单/详情用 Page Designer 出 DSL。
5. 权限、角色、字典、菜单 —— config/permissions.json / roles.json / dicts.json / menus.json。本插件还声明了 named-queries.json(命名查询)和 default-bootstrap.json(初始化数据)。
6. 打包导入 —— 用 aura CLI 的 import-directory-sync(参数是目录 path)或平台导入接口;校验返回 success:true 才算导入成功。注意 agent-control-plane 依赖 core-aurabot,要先导入依赖。详见 插件清单。

6. 常见配置

• 审批门控:在 approval_policy 上配 trigger_rules(按 approval_type 触发,如 external_api / cost_threshold)和 approver_rules;命中时生成 agent_approval 请求,挂起运行,审批人用 acp:approve_request 放行。设 auto_approve=true 可对低风险类型自动通过,timeout_hours + timeout_action 处理超时。
• 调度运行:agent_schedule 定义周期触发,用 acp:pause_schedule / acp:activate_schedule 控制开关;acp_schedule_status 为 expired 表示计划已到期。
• 成本与追踪:每次运行写 agent_run,平台记录 input_tokens / output_tokens / total_cost / duration_ms;产物写 agent_artifact 并以 run_id 回指,做到「报告 → 运行 → 成本」可追溯。
• Agent 记忆:agent_memory 按 memory_type + category 分类,importance 控制优先级,valid_from/valid_until 控制有效期,source_run_id 标明来源——让 Agent 跨运行记住偏好,而不是每次重配。
• 语义层:object_alias 和 semantic_term 让 Agent 用业务词汇(而非裸 modelCode)定位对象,降低自然语言到命令的歧义。

7. 典型错误

• 命令码用点号:写成 acp.task.complete 跑不通——命令是冒号 + 动词_名词:acp:complete_task。同一个插件里命令用冒号(acp:complete_task)、权限码用下划线(acp_agent_task),两套命名别混。
• 绕过命令直接改任务/运行表:直接 UPDATE agent_task 会跳过状态机校验(acp:complete_task 只允许 in_progress → done)、审计和事件投递。一切状态变更都走命令。
• bindingRules 写进 commands.json 内联:不会被导入;必须独立 binding 文件(本插件是 config/bindings.json)并在 resourceDirs 注册,否则报 [S-EXT-HANDLER] references unregistered handler。详见 纯配置 Plugin。
• 命令执行 payload 结构:字段放在 { "payload": { ... }, "operationType": ... },目标记录用 targetRecordId(不是 recordId)——放错位会出现「执行成功却字段为空」的迷惑性报错。
• 漏导依赖插件:agent-control-plane 的 plugin.json 声明 dependencies: ["com.auraboot.core-aurabot"];不先导入 core-aurabot,AI 中心的导航菜单和部分权限会缺失,工作台入口打不开。

下一步

• 系统总览 —— 插件、命令与运行时如何拼到一起
• 命令管道 —— 上面每条命令都走的执行契约
• 权限 —— 上面角色背后的五层模型
• Agent 就绪度 —— 如何设计 agentHint 和风险字段以保障安全执行
• Agent 系统 —— Agent 定义、运行、记忆与工具的平台契约