pj0235-eai_agentplatform/docs/2026-09-17_对象命名标准化清单.md

对象命名标准化清单

日期：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
• skill_definition.go
• app_definition.go

2. 前端 catalog store 方向也是清楚的

• specialistCatalog
• skillCatalog
• appCatalog

对应文件：

• specialistCatalog.js
• skillCatalog.js
• appCatalog.js

这一层说明：对象目录化方向是正确的。

---

三、当前命名不清晰的主要问题

3.1 旧术语和新术语混用

当前代码中同时混着：

• role
• assistant
• specialist
• skill
• app
• worker
• capability

这会导致以下问题：

1. 同一个对象被多个词指代
2. 同一个词被多个对象复用
3. 页面层很容易把对象边界重新写乱

典型例子

技能模型已经叫 SkillDefinition， 但字段仍叫 RoleKind： skill_definition.go:L5-L25

这说明：

• 模型名是新的
• 字段语义还是旧的

这类命名会误导人以为 role 仍然是正式一级对象。

3.2 文件名与真实职责不完全一致

最典型的是：

• capability_definition.go

这个文件名叫 capability_definition， 但里面做的是：

• skillDefinitionReq
• actionDefinitionReq
• ListSkillDefinitions

问题不只是不好看， 而是它在语义上制造了一个模糊的一级概念：capability。

当前系统正式对象语言应是：

• specialist
• skill
• app
• connector
• action（底层）

不应再让 capability 作为主要文件名继续扩散。

3.3 历史静态目录变量名不准

最典型的旧变量在： workbench.js:L99-L105 workbench.js:L1434-L1443

包括：

• availableSkills
• businessApps
• connectors

其中问题最大的是：

• businessApps 实际装的是专员目录，不是应用目录
• availableSkills 现在更像静态 fallback，不是正式生产技能目录

所以这些名字会把开发者带偏。

3.4 页面局部变量有失真

例如： SmartAssistantPage.vue:L311-L334

这里：

const app = specialistCatalog.getByKey(key)

拿到的是专员对象，却命名成 app。

这类局部变量不会影响编译， 但会持续破坏对象认知。

3.5 路由参数协议不统一

应用目录里拼路由时使用： appCatalog.js:L135-L145

• specialist
• skill
• prompt

但工作台页面读取的是： 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
• workerRuntime.js:L17-L21

这说明“assistant”当前同时在承担：

• 默认聊天接口名
• 默认技能语义
• 默认专员语义

需要明确边界，不然以后越做越乱。

---

四、标准命名原则

4.1 正式对象术语

对外和对内统一如下：

• 专员：specialist
• 技能：skill
• 应用：app
• 连接器：connector
• 动作：action

4.2 非正式或历史兼容词的处理原则

以下词允许保留在历史兼容层， 但不再继续扩散为新的正式命名：

• role
• businessApps
• availableSkills
• capability（除非明确表示“泛能力总称”，不能再充当对象级文件名）
• assistant（除非明确指聊天接口或默认助手）

4.3 命名优先级

命名时遵守：

对象准确性 > 历史兼容性 > 书写简短

意思是：

• 宁可名字长一点
• 也不要再用会误导对象边界的旧词

---

五、标准化建议

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

建议后续迁移为更准确的名字，例如：

• 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

建议：

• 保持这层对象 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

问题：

• 路由 query 命名与工作台读取不一致

建议：

• 先统一 query 协议

frontend/src/store/specialistCatalog.js

优点：

• 命名整体比较准确
• normalizeSpecialist / getByKey / getByPath 清楚

见： 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

这样做的原因是：

• 先收敛入口协议，避免继续产生新分叉
• 再清局部变量，马上提升可读性
• 最后再碰数据库字段，避免一次性改太重

---

八、最终判断

当前代码不是“命名完全混乱”， 而是：

目录已经开始清楚，但命名标准还没有真正收口。

最核心的问题不是技术能力， 而是术语迁移还没做完。

后续只要坚持：

对象名必须准确
旧词只做兼容
页面变量不得歪曲对象语义
路由 / API / store 使用同一套对象协议

这套代码的可读性会明显上一个台阶。