# 对象命名标准化清单

> 日期：2026-09-17
> 性质：**阶段性清单 / 历史记录**
> 2026-09-18 补注：本文原本记录的是 09-17 当天的待改项。其后代码与规范已大幅收口，**请勿再把本文当作当前现状说明**。当前规范以 `AR09_Object_Naming_Standard.md`、`TOP_CODING_RULES.md` 与代码现实为准。
> 关联文档：
> - `docs/对象标准化与解耦总则.md`
> - `docs/2026-09-17_六层架构与三对象建设重点阶段性复盘.md`
> - `docs/02_Architecture/AR09_Object_Naming_Standard.md`
> - `更名收尾说明.md`

---

## 一、这份清单现在该怎么读

这不是“还有哪些问题没修”的现状文档，
而是一次命名收口行动的**问题发现记录**。

它现在有两个用途：

1. 解释我们当时为什么要动那些名字
2. 给后来者留一份“哪些误导性命名曾真实存在过”的反例库

如果本文与当前代码冲突：

```text
以当前代码 + AR09 + 更名收尾说明 为准
```

---

## 二、09-18 后的总状态

### 1. 已完成的主收口

以下问题已经在 09-18 这轮重构中完成：

| 项 | 09-17 问题 | 09-18 结果 |
|---|---|---|
| 应用对象主词 | `app` 与对象体系冲突 | 已统一为 `xapp` |
| 任务运行命名 | `worker_*` 混杂“专员形态 / 任务运行”两层语义 | 已统一为 `task_*` |
| 技能对象分类字段 | `RoleKind / role_kind` 带旧 `role` 心智 | 已迁到 `ObjectKind / object_kind` |
| AI 用量字段 | `capability` 停留在存储层 | 已迁到 `usage_kind` |
| 工作台入口协议 | 写读参数不一致 | 已统一为 `xapp_specialist / xapp_skill / xapp_prompt`，并抽成共享常量 |
| 静态旧目录变量 | `businessApps`、`availableSkills` | 前者已删；后者已更名 `staticSkillCatalog` |
| 默认聊天入口旧名 | `assistant.js` / `smart_assistant.go` | 已收口到 `chatMessage.js` / `chat_message.go` |
| XApp 中心旧存储 key | `eai-app-center` 长期兼容 | 已改为一次迁移后清旧 key |

### 2. 仍可继续优化，但不再是主阻塞

这些点还值得继续做，但已经不是“命名体系没立住”的主问题：

| 项 | 当前状态 |
|---|---|
| `projectStore.js` 文件名后缀 | 仍是孤例，可继续收口为 `project.js` |
| 某些历史方案文档 | 仍保留旧路径名，需逐步补“历史映射”说明 |
| 一些研究/阶段性文档中的 `app_*` 或 `capability` | 多属历史语境，不应再回流到代码实现 |

---

## 三、09-17 当时识别出的核心问题

下面这些判断在当时是成立的，之所以保留，是因为它们解释了后续为什么要那样改。

### 3.1 旧术语和新术语混用

当时代码里同时混着：

- `role`
- `assistant`
- `specialist`
- `skill`
- `app`
- `worker`
- `capability`

这个判断是对的，也是后续重构的出发点。

### 3.2 文件名、字段名、变量名在讲旧故事

当时最典型的误导项包括：

- `capability_definition.go`
- `RoleKind`
- `businessApps`
- `availableSkills`
- 页面局部 `const app = specialistCatalog.getByKey(...)`
- `assistant.js`
- `workerRuntime.js`

这些名字的共同问题不是“难看”，而是**让对象边界持续失真**。

### 3.3 入口协议写读不对称

09-17 时，应用目录与工作台的 query 参数协议不统一，这不是风格问题，而是功能 bug。

这一条后来直接推动了共享常量 `XAPP_ENTRY_QUERY_KEYS` 的建立。

---

## 四、旧结论与新现实映射表

为了避免后续阅读时把旧清单直接套到现代码，这里给出一张映射表。

| 本文旧说法 | 当前应理解为 |
|---|---|
| `app` 对象 | `xapp` 对象 |
| `appCatalog.js` | `xappCatalog.js` |
| `assistant.js` | `chatMessage.js` |
| `smart_assistant.go` | `chat_message.go` |
| `workerRuntime.js` | `taskRuntime.js` |
| `api/worker.js` | `api/taskRuntime.js` |
| `worker_task.go` / `worker_run.go` / `worker_artifact.go` | `task_record.go` / `task_run.go` / `task_artifact.go` |
| `app_specialist / app_skill / app_prompt` | `xapp_specialist / xapp_skill / xapp_prompt` |
| `RoleKind` | `ObjectKind` |
| `capability`（AI 用量字段） | `usage_kind` |
| `capability_definition.go` | `skill_action_definition.go` |
| `businessApps` | 已删除，不应复活 |
| `availableSkills` | `staticSkillCatalog` |

---

## 五、保留下来的有效原则

这份旧清单里，有些原则到今天仍然完全成立：

### 5.1 对象名必须准确

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

这条没有过时。

### 5.2 旧词只能留在兼容层

像下面这些旧词：

- `role`
- `worker`
- `capability`
- `assistant`

只有在这三类位置允许保留：

1. 迁移逻辑
2. 迁移测试
3. 历史说明文档

不能再回流到业务模型、API、store、组件和新文档标题。

### 5.3 页面局部变量也会污染认知

`const app = specialistCatalog.getByKey(...)` 这种问题之所以要修，
不是因为会报错，
而是因为它会被后续代码继续照抄。

这一判断现在仍然成立。

### 5.4 入口协议必须抽成共享常量

09-17 的诊断后来被证明完全正确：

```text
能用结构消除的协议分叉，不要靠人工扫描补漏
```

---

## 六、当前建议的阅读顺序

如果现在要继续做命名与对象规范工作，建议按这个顺序看：

1. [AR09_Object_Naming_Standard.md](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/docs/02_Architecture/AR09_Object_Naming_Standard.md)
2. [更名收尾说明.md](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/更名收尾说明.md)
3. 本文

原因很简单：

- `AR09` 讲**当前正式规范**
- `更名收尾说明` 讲**这轮收口后哪些旧名只该留在迁移里**
- 本文只讲**09-17 当时发现过什么问题**

---

## 七、结论

09-17 这份清单的价值不在于“它现在还是不是待办列表”，
而在于它准确记录了当时的混乱来源：

- 对象主词混用
- 路径协议分叉
- 旧变量名继续扩散
- 局部变量失真
- 历史术语假装仍是正式术语

而 09-18 的重构已经把这些主问题大体收口。

所以现在最准确的判断是：

```text
这份文档应被视为历史问题记录，而不是当前待办清单。
```

后续若继续优化，应优先清理仍会误导人的历史文档与剩余孤例，
而不是回头按本文旧路径逐项“照单执行”。