# 对象命名标准化清单

> 日期：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 使用同一套对象协议
```

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