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
parent d0d7b3588c
commit ddd2d2cbd8
8 changed files with 2655 additions and 0 deletions
@@ -0,0 +1,549 @@
+# 对象命名标准化清单
+
+> 日期：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 使用同一套对象协议
+```
+
+这套代码的可读性会明显上一个台阶。