EaiLab/pj0235-eai_agentplatform
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ddd2d2cbd824489ab68d40a1f8c7c541e0261657
pj0235-eai_agentplatform/docs/2026-09-17_对象命名标准化清单.md
T
eaiadminandClaude Code ddd2d2cbd8 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>
2026-09-17 23:38:42 +08:00

550 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 对象命名标准化清单
> 日期：2026-09-17
> 性质：代码目录、文件名、变量名、函数名的对象命名标准化清单
> 关联文档：
> - `docs/对象标准化与解耦总则.md`
> - `docs/2026-09-17_六层架构与三对象建设重点阶段性复盘.md`
---
## 一、结论
当前代码目录整体上已经开始围绕对象收口，
但命名层面仍然处于**新旧术语混用**的过渡态。
最准确的判断是：
- **目录结构基本清楚**
- **对象落点已经清楚**
- **命名标准还不统一**
- **旧词残留仍在持续污染对象边界**
当前最主要的问题不是“找不到代码在哪”，
而是：
**看名字时，仍然经常不知道它到底指的是专员、技能、应用、默认助手，还是历史遗留概念。**
---
## 二、当前对象落点是否清楚
### 1. 后端主模型落点是清楚的
- 专员：`backend-go/internal/model/specialist.go`
- 技能：`backend-go/internal/model/skill_definition.go`
- 应用：`backend-go/internal/model/app_definition.go`
- 连接器：`backend-go/internal/connector/*`
其中三大对象模型命名基本准确：
- [specialist.go](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/backend-go/internal/model/specialist.go)
- [skill_definition.go](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/backend-go/internal/model/skill_definition.go#L5-L32)
- [app_definition.go](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/backend-go/internal/model/app_definition.go#L5-L38)
### 2. 前端 catalog store 方向也是清楚的
- `specialistCatalog`
- `skillCatalog`
- `appCatalog`
对应文件：
- [specialistCatalog.js](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/store/specialistCatalog.js#L17-L88)
- [skillCatalog.js](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/store/skillCatalog.js)
- [appCatalog.js](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/store/appCatalog.js#L22-L155)
这一层说明：**对象目录化方向是正确的。**
---
## 三、当前命名不清晰的主要问题
## 3.1 旧术语和新术语混用
当前代码中同时混着：
- `role`
- `assistant`
- `specialist`
- `skill`
- `app`
- `worker`
- `capability`
这会导致以下问题：
1. 同一个对象被多个词指代
2. 同一个词被多个对象复用
3. 页面层很容易把对象边界重新写乱
### 典型例子
技能模型已经叫 `SkillDefinition`，
但字段仍叫 `RoleKind`：
[skill_definition.go:L5-L25](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/backend-go/internal/model/skill_definition.go#L5-L25)
这说明：
- 模型名是新的
- 字段语义还是旧的
这类命名会误导人以为 `role` 仍然是正式一级对象。
## 3.2 文件名与真实职责不完全一致
最典型的是：
- [capability_definition.go](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/backend-go/internal/api/capability_definition.go#L1-L120)
这个文件名叫 `capability_definition`，
但里面做的是：
- `skillDefinitionReq`
- `actionDefinitionReq`
- `ListSkillDefinitions`
问题不只是不好看，
而是它在语义上制造了一个模糊的一级概念：`capability`。
当前系统正式对象语言应是：
- `specialist`
- `skill`
- `app`
- `connector`
- `action`（底层）
不应再让 `capability` 作为主要文件名继续扩散。
## 3.3 历史静态目录变量名不准
最典型的旧变量在：
[workbench.js:L99-L105](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/config/workbench.js#L99-L105)
[workbench.js:L1434-L1443](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/config/workbench.js#L1434-L1443)
包括：
- `availableSkills`
- `businessApps`
- `connectors`
其中问题最大的是：
- `businessApps` 实际装的是专员目录，不是应用目录
- `availableSkills` 现在更像静态 fallback，不是正式生产技能目录
所以这些名字会把开发者带偏。
## 3.4 页面局部变量有失真
例如：
[SmartAssistantPage.vue:L311-L334](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/views/workbench/SmartAssistantPage.vue#L311-L334)
这里：
```js
const app = specialistCatalog.getByKey(key)
```
拿到的是专员对象，却命名成 `app`。
这类局部变量不会影响编译，
但会持续破坏对象认知。
## 3.5 路由参数协议不统一
应用目录里拼路由时使用：
[appCatalog.js:L135-L145](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/store/appCatalog.js#L135-L145)
- `specialist`
- `skill`
- `prompt`
但工作台页面读取的是：
[SmartAssistantPage.vue:L602-L626](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/views/workbench/SmartAssistantPage.vue#L602-L626)
- `app_specialist`
- `app_skill`
- `app_prompt`
这已经不是风格差异，
而是**入口协议不统一**。
## 3.6 默认助手概念没有完全收口
当前存在：
- API 文件名：`assistant.js`
- 默认技能 key：`smart-assistant`
- 默认专员 key：`general-assistant`
见：
- [assistant.js:L1-L3](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/api/assistant.js#L1-L3)
- [workerRuntime.js:L17-L21](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/store/workerRuntime.js#L17-L21)
这说明“assistant”当前同时在承担：
- 默认聊天接口名
- 默认技能语义
- 默认专员语义
需要明确边界，不然以后越做越乱。
---
## 四、标准命名原则
## 4.1 正式对象术语
对外和对内统一如下：
- 专员：`specialist`
- 技能：`skill`
- 应用：`app`
- 连接器：`connector`
- 动作：`action`
## 4.2 非正式或历史兼容词的处理原则
以下词允许保留在历史兼容层，
但**不再继续扩散为新的正式命名**：
- `role`
- `businessApps`
- `availableSkills`
- `capability`（除非明确表示“泛能力总称”，不能再充当对象级文件名）
- `assistant`（除非明确指聊天接口或默认助手）
## 4.3 命名优先级
命名时遵守：
```text
对象准确性 > 历史兼容性 > 书写简短
```
意思是：
- 宁可名字长一点
- 也不要再用会误导对象边界的旧词
---
## 五、标准化建议
## 5.1 P0：立即统一入口协议和最容易误导人的命名
### A. 统一应用入口 query 参数
当前应统一为一套，
不要一边写 `specialist/skill/prompt`，
一边读 `app_specialist/app_skill/app_prompt`。
建议二选一，但必须全链路统一。
推荐统一成：
- `app_specialist`
- `app_skill`
- `app_prompt`
原因：
- 一眼能看出这是“应用带入工作台”的预置参数
- 不会和普通页面 query 混淆
### B. 修正页面里的失真变量名
例如：
- `const app = specialistCatalog.getByKey(...)`
应改成：
- `const specialist = ...`
这类改动优先级很高，
因为它们会直接影响后续开发者理解对象边界。
### C. 停止新增 `businessApps` / `availableSkills` 这类旧变量名
现有代码可暂时保留兼容，
但后续新增代码禁止继续使用这些命名。
---
## 5.2 P1：统一文件名与对象职责
### A. `capability_definition.go`
当前建议拆或改名：
方案 1：
- `skill_definition.go`
- `action_definition.go`
方案 2：
- 保留文件不拆，但改名为 `skill_and_action_definition.go`
不建议继续用：
- `capability_definition.go`
因为它已经不能准确表达该文件实际职责。
### B. `assistant.js`
当前如果它只是默认聊天接口，
建议更明确地表达为：
- `smartAssistant.js`
或
- `assistantChat.js`
而不是继续模糊地叫 `assistant.js`。
---
## 5.3 P1：统一 store 与 fallback 的命名语义
### A. `availableSkills`
如果继续保留作为静态补丁源，
建议改名为：
- `staticSkillCatalog`
或
- `legacySkillCatalog`
不要再叫：
- `availableSkills`
因为现在真正“可用技能目录”已经是后端 + `skillCatalog`。
### B. `businessApps`
如果继续保留作为专员静态兼容源，
建议改名为：
- `staticSpecialistCatalog`
或
- `legacySpecialistCatalog`
不要再叫：
- `businessApps`
因为它和 `app` 已经明确冲突。
---
## 5.4 P2：统一字段语义
### A. `RoleKind`
当前字段：
[skill_definition.go:L13](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/backend-go/internal/model/skill_definition.go#L13)
建议后续迁移为更准确的名字，例如：
- `object_kind`
或
- `owner_kind`
如果业务语义是“这个技能归属于哪类对象”。
如果短期不迁字段，
至少要在文档中明确：
- `RoleKind` 是历史兼容字段
- 不再代表正式 `role` 概念
### B. `assistant` 的语义边界
需要明确规定：
- `assistant` 只用于默认通用助手的聊天接口语义
- `specialist` 才是正式对象名
否则会继续出现：
- 默认助手既像 skill 又像 specialist
- 页面里又再抽象成 role
---
## 六、按文件的具体清单
## 6.1 后端
### `backend-go/internal/model/skill_definition.go`
问题：
- `RoleKind` 仍带旧语义
建议：
- 文档先标记为历史兼容字段
- 后续统一迁移为更准确字段名
### `backend-go/internal/api/capability_definition.go`
问题：
- 文件名与实际职责不匹配
- `capability` 不是当前正式对象主词
建议：
- 重命名或拆分
### `backend-go/internal/api/router.go`
优点：
- `/api/specialists`
- `/api/skills`
- `/api/apps`
- `/api/connectors`
这层命名已经较清楚：
[router.go:L39-L49](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/backend-go/internal/api/router.go#L39-L49)
建议：
- 保持这层对象 API 命名不再回退
## 6.2 前端
### `frontend/src/config/workbench.js`
问题：
- 是历史静态大杂烩
- `businessApps` 命名错误
- `availableSkills` 命名已过时
建议：
- 不再作为生产目录源
- 继续降级为静态 fallback
- 变量名按对象真实语义重命名
### `frontend/src/views/workbench/SmartAssistantPage.vue`
问题：
- 局部变量名存在失真
- `currentRolePresentation` 仍有旧 `role` 心智残留
建议：
- 局部变量全部改成对象准确名
- 将 `role presentation` 逐步收敛为 `currentObjectPresentation`
或明确区分：
- `currentSpecialistPresentation`
- `currentSkillPresentation`
- `defaultAssistantPresentation`
### `frontend/src/api/assistant.js`
问题：
- 文件名语义太宽
建议：
- 仅在确认其职责是“默认助手聊天接口”后保留
- 否则改名为更准确的接口文件名
### `frontend/src/store/appCatalog.js`
优点：
- `normalizeRemoteApp`
- `normalizeCustomApp`
- `resolveOpenRoute`
这套命名整体清楚：
[appCatalog.js:L22-L145](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/store/appCatalog.js#L22-L145)
问题：
- 路由 query 命名与工作台读取不一致
建议：
- 先统一 query 协议
### `frontend/src/store/specialistCatalog.js`
优点：
- 命名整体比较准确
- `normalizeSpecialist / getByKey / getByPath` 清楚
见：
[specialistCatalog.js:L17-L87](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/store/specialistCatalog.js#L17-L87)
建议：
- 继续作为专员目录的标准写法模板
---
## 七、执行顺序
建议按下面顺序做命名清理：
1. **统一入口协议**
- app query 参数统一
2. **清理页面级失真变量**
- 特别是 `SmartAssistantPage.vue`
- `CurrentObjectChip.vue`
- `PlusMenu.vue`
3. **清理历史静态变量名**
- `businessApps`
- `availableSkills`
4. **清理文件名级旧词**
- `capability_definition.go`
- `assistant.js`
5. **最后处理字段迁移**
- 如 `RoleKind`
这样做的原因是：
- 先收敛入口协议，避免继续产生新分叉
- 再清局部变量，马上提升可读性
- 最后再碰数据库字段，避免一次性改太重
---
## 八、最终判断
当前代码不是“命名完全混乱”，
而是：
**目录已经开始清楚，但命名标准还没有真正收口。**
最核心的问题不是技术能力，
而是术语迁移还没做完。
后续只要坚持：
```text
对象名必须准确
旧词只做兼容
页面变量不得歪曲对象语义
路由 / API / store 使用同一套对象协议
```
这套代码的可读性会明显上一个台阶。
Reference in New Issue View Git Blame Copy Permalink