pj0235-eai_agentplatform/docs/01_System_Overall/SY21_统一角色技能动作架构.md

SY21 — 统一 Expert / Skill / Action 总架构确认稿

状态：总架构确认稿 日期：2026-09-16 关联文档：

• History_And_Retrospectives/系统演进旧稿/SY03_知识中心型智能体平台战略.md
• History_And_Retrospectives/系统演进旧稿/SY15_术语基准本体语义层与对象层.md
• History_And_Retrospectives/系统演进旧稿/SY20_角色卡与轻量本体架构.md
• docs/01_System_Overall/History_And_Retrospectives/系统演进旧稿/SY24_平台架构重思考.md

2026-09-16 术语同步： 本文原先使用 Role / role / role_card 作为主术语。 现已确认 Role 不再作为推荐命名，统一改口为：

• 对外：专家（Expert） / 技能 / 连接器
• 对内：expert / skill / action / connector / policy 文中尚未完全迁移的 role、role_card、角色对象层，后续均应分别理解为 expert、expert_card、专家对象层。

---

1. 这份文档要确认什么

在前面几轮讨论后，当前项目需要一份统一总架构结论，用来回答以下问题：

1. 平台到底按几层架构来收敛
2. 本体、角色卡、对象、技能、Action、连接器分别处于什么位置
3. 对外到底暴露什么，对内到底运行什么
4. 是否还要继续使用 tool 这个词
5. 当前代码和文档后续应该往哪个方向迁移

这份文档用于先定平台的总语言、总结构和总对象模型。

---

2. 最终结论

2.1 平台采用六层总架构

建议正式统一为六层：

1. 外部连接层
2. 本体与语义上下文层
3. 总线与编排层
4. 能力层
5. 专家对象层
6. 工作台与运行治理层

这六层已经足以覆盖：

• 通用数字员工
• 文档类、知识类、分析类能力
• 工业设备监测、安防、巡检、告警、工单等强外部接口场景

2.2 不再把 tool 作为正式命名

命名上正式收敛为：

• 对外：专家 / 技能 / 连接器
• 对内：expert / skill / action / connector / policy

结论：

以后不再新增正式架构概念 tool。

tool 只作为历史迁移词存在，用于兼容旧文档、旧字段、旧目录，不再作为未来架构的主词。

2.3 对外默认暴露 专家 + 技能

外部用户默认看到的是：

• 专家
• 技能
• 欢迎语
• starter prompts
• 可完成的任务

因此，用户入口层默认暴露 skill，不暴露 action。

2.4 对内统一使用 action

内部最小执行单元统一叫：

Action

它用于承接：

• 一次原子能力执行
• 一次外部系统调用
• 一次标准化输入输出动作
• 一次可授权、可审计、可编排的执行操作

也就是说：

• skill 是任务化能力包
• action 是原子执行单元

2.5 要引入本体层，而且是必需的

如果平台后续要扩展到：

• 工业设备运行监测员
• 安防管理员
• 巡检专员
• 告警分析专员
• 工单协调专员

那么本体层是必要项。

原因很简单：

没有本体层，上层对象和工作台体验很快就会被行业对象、事件、状态、规则的差异撕裂。

2.6 专家卡作为专家对象属性存在

角色卡仍然要保留，并作为专家对象的交互属性集存在：

专家卡 = 专家对象的交互属性集

它负责：

• 角色是谁
• 角色如何开场
• 角色如何和用户说话
• 角色建议用户如何开始
• 角色承诺做什么、不做什么

---

3. 六层总架构定义

3.1 第一层：外部连接层

这一层负责连接真实世界和外部系统。

包括：

• PLC
• SCADA
• MES
• ERP
• CRM
• CMMS / 工单系统
• IoT 平台
• 视频平台
• 文档系统
• 数据库
• API / Webhook / MQ

这一层回答的是：

数据从哪里来，动作往哪里去。

在本项目里，这一层的标准对象是：

• connector_definition
• connector_binding

3.2 第二层：本体与语义上下文层

这一层负责定义平台语义。

它承载平台统一语义底座。

当前阶段建议采用轻量本体，先定义：

1. 对象类型

   • device
   • alarm
   • work_order
   • report
   • contract
   • knowledge_item
   • person
   • site

2. 动作类型

   • monitor
   • inspect
   • diagnose
   • review
   • extract
   • translate
   • escalate
   • dispatch

3. 状态类型

   • running
   • warning
   • critical
   • pending
   • approved
   • closed

4. 关系类型

   • belongs_to
   • depends_on
   • triggers
   • resolves
   • cites
   • produces

这一层回答的是：

系统里到底有什么对象，它们如何关联，允许哪些动作。

3.3 第三层：总线与编排层

这一层负责流转，不负责人格，不负责 UI。

它至少应包含三类总线：

1. 上下文总线
2. 事件总线
3. 能力编排总线

职责包括：

• 角色之间的协作
• skill 对 action 的编排
• action 对 connector 的调用
• 事件进入任务上下文
• 审批和安全边界控制

这一层回答的是：

对象怎么流动，能力怎么协作，任务怎么推进。

3.4 第四层：能力层

这一层正式拆成三类对象：

1. skill
2. action
3. policy

3.4.1 skill

skill 是面向任务的能力包。

它通常由以下部分组成：

• intent
• prompt template
• action chain
• input schema
• output schema
• artifact schema
• guardrails

可以理解为：

skill = 用户任务入口 + 规则 + 执行编排模板

3.4.2 action

action 是内部原子执行单元。

例如：

• read_device_status
• query_alarm_history
• create_work_order
• extract_contract_terms
• translate_document
• generate_shift_report

它必须具备：

• 标准输入
• 标准输出
• 权限边界
• 风险级别
• 审计记录

3.4.3 policy

policy 负责定义约束和治理条件，例如：

• 某 action 是否允许自动执行
• 是否需要人工确认
• 哪些角色可以调用哪些 skill
• 哪些 connector 只能读不能写

这一层回答的是：

系统能做哪些事，这些事如何以任务化和原子化两种粒度存在。

3.5 第五层：专家对象层

这是用户真正感知到的执行主体层。

专家对象统一采用一个根模型，例如：

• object_definition

专家对象不再分裂成多套根结构。

建议至少包含两类专家：

1. assistant
2. specialist

如果后续需要更强的“执行人格化对象”，可补充：

3. executor

其中：

• assistant：默认兜底编排专家
• specialist：面向领域任务的主专家
• executor：必要时暴露给用户的窄能力执行专家

这里最关键的变化是：

专家对象不直接等于 action。

专家对象负责承接用户、暴露 skill、组织交互体验； 真正执行时，仍然落到 skill -> action -> connector。

3.5.1 专家卡属于这一层

expert_card 是专家对象属性，不再单列成架构层。

建议最少包含：

• name
• tagline
• greeting
• tone
• opening_prompt
• starter_prompts
• boundaries
• relationship_to_user

3.5.2 专家对象与能力层的关系

专家对象不直接暴露所有 action。

更合适的关系是：

• 专家对象暴露 skill
• skill 编排多个 action
• action 调用 connector

所以：

专家承接用户，skill 组织任务，action 执行动作。

3.6 第六层：工作台与运行治理层

这一层是最终运行现场。

包括：

• /home Workbench
• task
• task_message
• task_object_instance
• object_run
• artifact
• workflow panel
• audit / observe / approval

这一层回答的是：

一条具体任务如何挂载角色、发送消息、运行 skill、触发 action、沉淀产物。

---

4. 最终对象关系

建议以后统一采用下面这条主链路：

user -> expert -> skill -> action -> connector

再叠加本体层：

ontology -> expert / skill / action / connector

也就是说：

1. 用户不是直接找 action
2. 用户是进入某个专家
3. 专家向用户暴露 skill
4. skill 编排 action
5. action 调用 connector
6. 全程受 ontology 和 policy 约束

---

5. 对外暴露模型

5.1 对终端用户

默认暴露：

• 专员
• 技能
• 欢迎语
• 任务入口
• 产物结果

默认不暴露：

• action
• connector 技术细节
• 编排细节
• 底层风险策略

5.2 对管理员 / 搭建者

可以暴露：

• skill 绑定了哪些 action
• action 绑定了哪些 connector
• 权限和审批条件
• 输出 schema
• 审计与日志

5.3 对运行时

直接处理：

• action call
• connector call
• context binding
• event routing
• approval gate
• audit log

---

6. 为什么不再使用 tool

6.1 对外不合适

tool 太像功能按钮集合，不像任务语言，也不像角色语言。

尤其在数字员工和工业智能体场景里，它会把产品体验拉回“工具页”心智。

6.2 对内也不够精确

内部真正需要区分的是：

• 任务级能力包：skill
• 原子执行动作：action
• 外部系统入口：connector

tool 夹在中间，语义反而模糊。

6.3 正式命名替换

后续正式命名建议统一为：

• 用户可见的 tool -> skill
• 内部原子执行的 tool -> action
• chatTools -> availableSkills
• currentToolKey -> currentSkillKey
• tool_keys -> skill_keys
• 顶部设置条组件 -> SkillStrip 或 ActionStrip
• 前端技能定义目录 -> src/skills/*
• 后端原子动作定义 -> action_definition / action_refs / action_records

说明：

当前仓库已有大量 tool 历史字段，不建议在总架构确认稿阶段立刻全量重命名；
但从现在开始，不再新增新的正式 tool 命名。

---

7. 角色、技能、Action 的清晰边界

7.1 角色

回答的是：

谁来承接这次任务。

角色包含：

• 身份
• 角色卡
• 协作边界
• 可暴露 skills
• 权限范围

7.2 技能

回答的是：

用户想完成什么任务。

技能包含：

• 任务意图
• 开始条件
• 输入输出约束
• 产物定义
• 对 action 的编排模板

7.3 Action

回答的是：

系统这一步到底执行了什么动作。

Action 包含：

• 原子能力定义
• 风险级别
• 调用协议
• connector 绑定
• 审计信息

---

8. 角色卡和本体是否重叠

不重叠。

它们都可能写到“能力”相关内容，但目标完全不同。

8.1 本体

服务机器一致性，定义：

• 对象
• 动作
• 状态
• 关系
• 规则

8.2 角色卡

服务人机交互一致性，定义：

• 开场方式
• 角色语气
• 任务入口提示
• 用户对该角色的体验预期

一句话：

本体定义世界，角色卡定义人格。

---

9. 对当前 Workbench 的直接要求

9.1 欢迎语必须对象属性驱动

当用户挂载某个角色后，Workbench 不应继续显示通用助手欢迎语。

应改为：

1. 优先显示当前专家的 expert_card.greeting
2. 下方展示 starter_prompts
3. 辅助展示 tagline / opening_prompt / boundaries
4. 无挂载角色时，再退回默认助手欢迎态

9.2 输入区顶部应体现当前对象

输入区顶部不应只显示一个孤立 chip。

应明确表达：

• 当前对象是谁
• 当前这次输入会触发什么任务语义
• 当前对象是否存在可调设置

并冻结以下交互规则：

1. + 右边一次只显示一个当前对象
2. 当前对象要么是专员，要么是技能，要么是默认助手
3. 专员内部调用技能时，下游技能只进入执行链与右侧面板，不在输入区显性双挂

9.3 右侧面板应是对象面板，不再是旧“工具面板”

建议中性命名：

• ObjectPanel
• ExpertPanel

其内容由当前角色和当前运行态决定，而不是由旧页面类型决定。

---

10. 目标数据结构建议

10.1 角色定义 object_definition

建议继续作为统一根对象，至少补充：

• object_kind
• expert_card_json
• capability_profile_json
• collaboration_profile_json
• ontology_binding_json

10.2 技能定义 skill_definition

建议新增独立定义层，至少包含：

• id
• key
• label
• description
• exposed_to_user
• input_schema
• output_schema
• artifact_schema
• action_refs
• policy_refs
• ontology_binding

10.3 Action 定义 action_definition

建议新增，至少包含：

• id
• key
• label
• action_type
• connector_ref
• input_schema
• output_schema
• risk_level
• approval_mode
• audit_level

10.4 运行态

建议继续沿用并收敛为：

• task
• task_object_instance
• task_message
• object_run
• artifact

其中：

• task_object_instance 负责挂载当前角色
• task_message 负责持久化会话
• object_run 负责记录 skill 和 action 的执行链

---

11. 对当前项目的迁移原则

11.1 总原则

先定语言，再改代码。

当前阶段最重要的是把架构口径统一为：

• 六层总架构
• 对外 角色 + 技能
• 对内 skill + action + connector
• tool 正式退出未来命名

11.2 当前阶段不要做的事

1. 不要继续新增 tool 概念
2. 不要再把 action 做成独立页面
3. 不要再让路由承担能力身份
4. 不要让欢迎语继续写死在页面里

11.3 下一阶段最值得做的事

1. 先把当前架构文档同步到这一套口径
2. 再把前端欢迎态改为 expert_card.greeting 驱动
3. 再把 tool 相关变量和目录逐步迁移到 skill / action
4. 后续再进入数据库与运行时的对象化升级

---

12. 一句话总收口

平台以后应统一理解为：

一个以本体为语义底座、以角色为用户承接体、以技能为任务入口、以 Action 为原子执行单元、以 Workbench 为统一运行现场的数字员工与工业智能体平台。