docs: 对象命名规范 AR09 与标准化讨论文档入库
- 新增 docs/02_Architecture/AR09_Object_Naming_Standard.md（规范性文件，非设计稿）： 十节结构 —— 原理 / 判据 / 对象术语表 / 五层命名规范 / 命名模式库 / 如何检查（人工五问 + 6 个机器守卫）/ 如何修复（迁移顺序 + 改名六步法）/ 现状问题登记（逐条带 file:line）/ 反例库 / 修订记录。 核心判断：名称即契约，改名前先查已靠名字建立的协议表 - 02_Architecture/README.md 登记 AR09，并说明其规范性定位（约束新增代码， 与 TOP_CODING_RULES.md 的 G03 配套），与 AR01–AR08 设计稿区别 - 收入本轮讨论与调研文档：对象命名标准化清单、对象标准化与解耦总则、 六层架构与三对象建设重点阶段性复盘、目录结构化迁移说明、 AionUi 对照分析两篇 Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
eaiadmin
@@ -0,0 +1,345 @@
|
||||
# 对象标准化与解耦总则
|
||||
|
||||
## 一、目标
|
||||
|
||||
这个项目后续不再围绕“某个页面怎么写”来扩能力，
|
||||
而是围绕三类核心对象做长期演进：
|
||||
|
||||
- **专员**
|
||||
- **技能**
|
||||
- **应用**
|
||||
|
||||
目标不是把功能堆起来，而是把这三类对象做成：
|
||||
|
||||
```text
|
||||
定义稳定
|
||||
+ 关系清晰
|
||||
+ 数据源唯一
|
||||
+ 前后端解耦
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、统一结构
|
||||
|
||||
三类对象以后都按同一种思路建模：
|
||||
|
||||
```text
|
||||
对象定义 + 绑定关系 + 运行态数据
|
||||
```
|
||||
|
||||
### 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. 专员
|
||||
|
||||
专员只负责：
|
||||
|
||||
- 理解任务
|
||||
- 拆解步骤
|
||||
- 决定何时调用技能
|
||||
- 决定输出的协作方式
|
||||
|
||||
专员不是技能，也不是应用入口。
|
||||
|
||||
专员的本质是：
|
||||
|
||||
```text
|
||||
规则层 / 编排层 / 协作层
|
||||
```
|
||||
|
||||
### 2. 技能
|
||||
|
||||
技能只负责：
|
||||
|
||||
- 执行动作
|
||||
- 接收输入
|
||||
- 产生结果
|
||||
- 输出产物
|
||||
|
||||
技能不负责“扮演谁”，也不负责“对外怎么卖”。
|
||||
|
||||
技能的本质是：
|
||||
|
||||
```text
|
||||
执行层 / 工具层
|
||||
```
|
||||
|
||||
### 3. 应用
|
||||
|
||||
应用只负责：
|
||||
|
||||
- 面向用户提供一键入口
|
||||
- 预装默认专员
|
||||
- 预装默认技能
|
||||
- 预装默认提示词
|
||||
|
||||
应用不应该承载规则本体，也不应该直接替代技能。
|
||||
|
||||
应用的本质是：
|
||||
|
||||
```text
|
||||
产品化入口层
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、解耦原则
|
||||
|
||||
### 原则 1：后端是唯一目录源
|
||||
|
||||
以后目录对象必须以后端表为准。
|
||||
|
||||
前端只能做：
|
||||
|
||||
- 请求
|
||||
- 归一化
|
||||
- 渲染
|
||||
|
||||
前端不能再承担：
|
||||
|
||||
- 正式编号生成规则
|
||||
- 正式目录维护
|
||||
- 对象真数据拼装
|
||||
|
||||
### 原则 2：页面不能成为数据源
|
||||
|
||||
目录页、详情页、加号菜单、聊天胶囊都只能消费 store，
|
||||
不能各自再维护一份对象数组。
|
||||
|
||||
### 原则 3：配置文件不能充当生产目录
|
||||
|
||||
配置文件最多只允许承担：
|
||||
|
||||
- fallback
|
||||
- 样式增强
|
||||
- 本地 demo
|
||||
|
||||
不能承担：
|
||||
|
||||
- 生产目录
|
||||
- 正式编号
|
||||
- 主入口映射
|
||||
|
||||
### 原则 4：对象定义和用户态分离
|
||||
|
||||
全局对象属于系统目录。
|
||||
|
||||
用户收藏、最近使用、自定义应用，属于用户态。
|
||||
|
||||
这两层必须分开：
|
||||
|
||||
```text
|
||||
系统目录 != 用户偏好 != 运行态挂载
|
||||
```
|
||||
|
||||
### 原则 5：编号必须系统化
|
||||
|
||||
编号不是前端算出来的临时 UI 字符串，
|
||||
而是正式对象属性。
|
||||
|
||||
统一规则：
|
||||
|
||||
- 专员：`专 / EAI-S-`
|
||||
- 技能：`能 / EAI-K-`
|
||||
- 应用：`应 / EAI-A-`
|
||||
- 连接器：`连 / EAI-C-`
|
||||
|
||||
---
|
||||
|
||||
## 五、标准对象视图
|
||||
|
||||
前端消费对象时，应尽量收敛到统一视图，而不是每类对象各起一套随意字段。
|
||||
|
||||
建议统一成：
|
||||
|
||||
```text
|
||||
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`
|
||||
|
||||
最终应该形成：
|
||||
|
||||
```text
|
||||
对象定义表
|
||||
+ 对象关系表
|
||||
+ 运行态任务表
|
||||
```
|
||||
|
||||
而不是：
|
||||
|
||||
```text
|
||||
对象定义表
|
||||
+ seed 里一段字符串
|
||||
+ 前端里一段数组
|
||||
+ prompt 里再提一次
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、后续开发规则
|
||||
|
||||
以后新增一个专员、技能、应用，顺序必须是：
|
||||
|
||||
1. 先定义它属于哪一层
|
||||
2. 再写后端对象定义
|
||||
3. 再补绑定关系
|
||||
4. 最后前端消费目录
|
||||
|
||||
禁止反过来：
|
||||
|
||||
1. 先在前端做个入口
|
||||
2. 再在页面里写死配置
|
||||
3. 最后再考虑后端有没有这对象
|
||||
|
||||
---
|
||||
|
||||
## 八、当前项目的正确方向
|
||||
|
||||
这个项目后续最重要的不是再多做几个按钮，
|
||||
而是把平台真正推进到：
|
||||
|
||||
```text
|
||||
专员层
|
||||
+ 技能层
|
||||
+ 应用层
|
||||
+ 连接器层
|
||||
```
|
||||
|
||||
四层稳定分离、统一建模、统一编号、统一目录源。
|
||||
|
||||
这样后面不管是对标 AionUi、MyGPT，还是继续扩办公生产力能力，
|
||||
都不会再陷入“每扩一个能力，就前后端各写一遍”的结构性债务。
|
||||
|
||||
---
|
||||
|
||||
## 九、当前阶段判断
|
||||
|
||||
虽然长期结构上仍然需要关系层，
|
||||
但**当前阶段不要把“复杂绑定关系”当成第一优先级**。
|
||||
|
||||
原因不是这个逻辑不成立，
|
||||
而是当前对象成熟度还没有到那一步：
|
||||
|
||||
- 专员还没有形成稳定、强编排能力
|
||||
- 技能还没有强壮到值得被专员大量调用
|
||||
- 应用当前更像产品化入口，而不是复杂能力编排器
|
||||
|
||||
所以当前更符合实际的推进顺序是：
|
||||
|
||||
### 1. 先把对象本身做强
|
||||
|
||||
- 专员先做成稳定对象：有身份、有规则、有入口、能承接任务
|
||||
- 技能先做成强能力：单独使用就有价值，输入输出稳定，结果可靠
|
||||
- 应用先做成强入口：打开就能用，能直接产出，不强求复杂编排
|
||||
|
||||
### 2. 暂时不为了“结构漂亮”提前过度设计关系层
|
||||
|
||||
现阶段不要把大量精力投到：
|
||||
|
||||
- 专员大量调用技能
|
||||
- 应用绑定复杂技能树
|
||||
- 为了理论完整性提前拆很多关系表
|
||||
|
||||
如果对象本身不强，关系层只会变成空架子。
|
||||
|
||||
### 3. 关系层仍然重要，但属于下一阶段
|
||||
|
||||
当下面几件事开始稳定出现时，再提高关系层优先级：
|
||||
|
||||
- 一个专员开始稳定复用多种技能
|
||||
- 一个技能被多个专员反复复用
|
||||
- 一个应用需要切默认专员或默认能力组合
|
||||
- 后台出现真实的配置、运营和灰度需求
|
||||
|
||||
所以当前项目的阶段性原则是：
|
||||
|
||||
```text
|
||||
先强对象，再补关系
|
||||
先做成立，再做复杂协作
|
||||
```
|
||||
|
||||
这条判断优先级高于“结构看起来够不够完整”。
|
||||
Reference in New Issue
Block a user