# 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 为统一运行现场的数字员工与工业智能体平台。**