pj0235-eai_agentplatform/docs/对象标准化与解耦总则.md

对象标准化与解耦总则

一、目标

这个项目后续不再围绕“某个页面怎么写”来扩能力， 而是围绕三类核心对象做长期演进：

• 专员
• 技能
• 应用

目标不是把功能堆起来，而是把这三类对象做成：

定义稳定
+ 关系清晰
+ 数据源唯一
+ 前后端解耦

---

二、统一结构

三类对象以后都按同一种思路建模：

对象定义 + 绑定关系 + 运行态数据

1. 对象定义

定义“这个对象是什么”。

必须由后端保存，前端只能消费，不能再本地拼真数据。

对象定义至少要包含这几类字段：

• key
• label
• display_code
• eailogic_code
• tier
• worker_type
• source
• summary
• state
• sort_order

如果是面向用户展示的对象，还要有：

• badge / market_tag
• color
• icon_text
• cover_tone

2. 绑定关系

定义“它和谁有关系”。

以后不要再把绑定关系散在 prompt、seed 文本和前端配置里。

关系必须可显式表达，比如：

• 专员绑定哪些技能
• 应用默认挂哪个专员
• 应用默认挂哪些技能
• 对象能打开到哪个入口

3. 运行态数据

定义“这次执行过程中发生了什么”。

这层和目录定义分开，不能混。

例如：

• 当前任务挂了哪个专员
• 当前会话挂了哪个技能
• 当前用户收藏了哪个应用
• 最近使用了哪些应用
• 任务执行过程产出了什么文件

---

三、三层职责

1. 专员

专员只负责：

• 理解任务
• 拆解步骤
• 决定何时调用技能
• 决定输出的协作方式

专员不是技能，也不是应用入口。

专员的本质是：

规则层 / 编排层 / 协作层

2. 技能

技能只负责：

• 执行动作
• 接收输入
• 产生结果
• 输出产物

技能不负责“扮演谁”，也不负责“对外怎么卖”。

技能的本质是：

执行层 / 工具层

3. 应用

应用只负责：

• 面向用户提供一键入口
• 预装默认专员
• 预装默认技能
• 预装默认提示词

应用不应该承载规则本体，也不应该直接替代技能。

应用的本质是：

产品化入口层

---

四、解耦原则

原则 1：后端是唯一目录源

以后目录对象必须以后端表为准。

前端只能做：

• 请求
• 归一化
• 渲染

前端不能再承担：

• 正式编号生成规则
• 正式目录维护
• 对象真数据拼装

原则 2：页面不能成为数据源

目录页、详情页、加号菜单、聊天胶囊都只能消费 store， 不能各自再维护一份对象数组。

原则 3：配置文件不能充当生产目录

配置文件最多只允许承担：

• fallback
• 样式增强
• 本地 demo

不能承担：

• 生产目录
• 正式编号
• 主入口映射

原则 4：对象定义和用户态分离

全局对象属于系统目录。

用户收藏、最近使用、自定义应用，属于用户态。

这两层必须分开：

系统目录 != 用户偏好 != 运行态挂载

原则 5：编号必须系统化

编号不是前端算出来的临时 UI 字符串， 而是正式对象属性。

统一规则：

• 专员：专 / EAI-S-
• 技能：能 / EAI-K-
• 应用：应 / EAI-A-
• 连接器：连 / EAI-C-

---

五、标准对象视图

前端消费对象时，应尽量收敛到统一视图，而不是每类对象各起一套随意字段。

建议统一成：

CatalogObjectView
- key
- type
- label
- displayCode
- logicCode
- badge
- tier
- workerType
- summary
- color
- iconText
- coverTone
- openRoute
- state
- sortOrder

扩展字段可以挂在各自域内，但公共展示层尽量对齐。

---

六、绑定关系标准

后面不再继续把绑定关系藏在自由文本里。

应该逐步补成显式关系：

• specialist_skill_binding
• app_specialist_binding
• app_skill_binding
• specialist_connector_binding

最终应该形成：

对象定义表
+ 对象关系表
+ 运行态任务表

而不是：

对象定义表
+ seed 里一段字符串
+ 前端里一段数组
+ prompt 里再提一次

---

七、后续开发规则

以后新增一个专员、技能、应用，顺序必须是：

1. 先定义它属于哪一层
2. 再写后端对象定义
3. 再补绑定关系
4. 最后前端消费目录

禁止反过来：

1. 先在前端做个入口
2. 再在页面里写死配置
3. 最后再考虑后端有没有这对象

---

八、当前项目的正确方向

这个项目后续最重要的不是再多做几个按钮， 而是把平台真正推进到：

专员层
+ 技能层
+ 应用层
+ 连接器层

四层稳定分离、统一建模、统一编号、统一目录源。

这样后面不管是对标 AionUi、MyGPT，还是继续扩办公生产力能力， 都不会再陷入“每扩一个能力，就前后端各写一遍”的结构性债务。

---

九、当前阶段判断

虽然长期结构上仍然需要关系层， 但当前阶段不要把“复杂绑定关系”当成第一优先级。

原因不是这个逻辑不成立， 而是当前对象成熟度还没有到那一步：

• 专员还没有形成稳定、强编排能力
• 技能还没有强壮到值得被专员大量调用
• 应用当前更像产品化入口，而不是复杂能力编排器

所以当前更符合实际的推进顺序是：

1. 先把对象本身做强

• 专员先做成稳定对象：有身份、有规则、有入口、能承接任务
• 技能先做成强能力：单独使用就有价值，输入输出稳定，结果可靠
• 应用先做成强入口：打开就能用，能直接产出，不强求复杂编排

2. 暂时不为了“结构漂亮”提前过度设计关系层

现阶段不要把大量精力投到：

• 专员大量调用技能
• 应用绑定复杂技能树
• 为了理论完整性提前拆很多关系表

如果对象本身不强，关系层只会变成空架子。

3. 关系层仍然重要，但属于下一阶段

当下面几件事开始稳定出现时，再提高关系层优先级：

• 一个专员开始稳定复用多种技能
• 一个技能被多个专员反复复用
• 一个应用需要切默认专员或默认能力组合
• 后台出现真实的配置、运营和灰度需求

所以当前项目的阶段性原则是：

先强对象，再补关系
先做成立，再做复杂协作

这条判断优先级高于“结构看起来够不够完整”。