# 数字员工 Workbench 架构合同

> 落盘日期：2026-09-16
> 状态：架构合同
> 作用：作为后续前端重构的强约束，先定模型，再做代码迁移
> 关联文档：`AR08_角色交互设计.md`

---

## 1. 目标

系统后续只保留一个大的工作台。

这个工作台必须同时满足 4 件事：

1. 用户始终在同一个主工作面里完成任务
2. 专员和工具都作为挂载在当前任务里的对象运行
3. 对象可以被启动、配置、切换焦点、关闭
4. 所有执行上下文都以任务为中心组织

一句话定义：

`一个 Workbench + 一条任务上下文 + 多个可挂载对象`

---

## 2. 强结论

### 2.1 保留一个唯一执行工作面

前端只允许一个执行型主工作面：

- 建议沿用 `/home` 作为 canonical page_route
- `/` 直接进入 `/home`

这个页面承载：

- 消息流
- 当前对象 chip
- 设置条
- 工作流 / 产物右栏
- 附件入口
- `+` 菜单

### 2.2 `apps/*` 不再作为使用入口

`/apps/*` 收敛为以下两种形态：

1. 被删除
2. 退化成兼容跳转，统一跳回 `/home`

它承担的角色收敛为：

- 打开专员工作台
- 在专员页里执行任务
- 与主工作面并行存在

### 2.3 `tools/*` 不再作为使用入口

`/tools/*` 收敛为兼容跳转入口。

工具统一建模为：

- 当前任务里被启动的技术员对象
- 由统一工作面承载执行

`/tools/*` 在迁移期只允许做兼容跳转，不允许继续扩散业务逻辑。

---

## 3. 对象模型

### 3.1 三类对象

| 对象 | 本质 | 角色 |
|------|------|------|
| 通用助手 | 默认专员 | 没有显式指定对象时的兜底编排者 |
| 数字专员 | 编排型对象 | 负责拆任务、排步骤、调用工具、汇总结果 |
| 数字技术员 | 执行型对象 | 负责单点能力执行，例如翻译、提取、转写 |

### 3.2 工具的真正定义

“工具”只是数字技术员的展示别名，不再是页面类型。

所以未来语义应该是：

- 文档翻译工具 -> 文档翻译技术员
- 文案校对工具 -> 文案校对技术员
- 批量提取工具 -> 批量提取技术员

如果某个对象既有“专员态”又有“工具态”，必须拆成两个不同 key，禁止复用同一个 key。

例如这类冲突必须消除：

- `contract-review` 不能同时代表专员和工具
- `report-generation` 不能同时代表专员和工具

---

## 4. 状态模型

## 4.1 核心原则

所有运行时状态必须挂在“当前任务”下面。

禁止再出现：

- 专员状态靠任务 store
- 工具状态靠路由
- 右栏状态靠页面推断

这三套并行模型。

### 4.2 迁移期必须新增的状态

第一阶段必须补上：

```ts
type TaskRuntimeContextV1 = {
  currentTaskId: string
  currentSpecialistKey: string
  currentSkillKey: string
}
```

其中：

- `currentSpecialistKey` 表示当前任务挂载的主编排对象
- `currentSkillKey` 表示当前输入区和设置条默认服务的技能对象

`currentSkillKey` 用于把技能正式纳入任务上下文，并承接输入区和设置条的默认服务对象。

### 4.3 最终推荐状态模型

在迁移完成后，建议升级为：

```ts
type TaskRuntimeContext = {
  currentTaskId: string
  currentSpecialistKey: string
  openedSkillKeys: string[]
  focusedObjectKind: 'assistant' | 'specialist' | 'skill'
  focusedObjectKey: string
  mode: 'quick' | 'expert'
}
```

解释：

- `currentTaskId`：当前任务
- `currentSpecialistKey`：这条任务当前的主编排者
- `openedSkillKeys`：这条任务里已启动但未关闭的技能
- `focusedObjectKind` / `focusedObjectKey`：当前输入框、设置条、右栏正在服务哪个对象
- `mode`：当前工作模式

### 4.4 状态约束

必须满足以下约束：

1. 没有任务时，允许预选对象，但只能作为 pending 状态
2. 一旦第一条消息发出，pending 状态必须落入任务上下文
3. `focusedObjectKey` 必须属于：
   - `currentSpecialistKey`
   - `openedSkillKeys`
   - 或默认助手
4. 关闭对象后，焦点必须自动切回：
   - 同任务下的其他已打开对象
   - 没有则回到当前专员
   - 再没有则回到通用助手

---

## 5. 路由收敛原则

### 5.1 执行路由

执行型路由只保留：

- `/home`

### 5.2 目录与配置路由

允许保留的非执行路由只有两类：

1. 目录路由  
   例如：
   - `/catalog/specialists`
   - `/catalog/skills`
   - `/catalog/connectors`

2. 配置 / 管理路由  
   例如：
   - `/studio`
   - `/console`
   - 后台管理页

### 5.3 兼容跳转规则

在迁移阶段：

- `/apps/*` -> 跳回 `/home`
- `/tools/*` -> 跳回 `/home`

跳转时要把对象意图带回工作台，例如：

- 原 `/tools/document-translate`
  -> `/home` 并恢复 `currentSkillKey=document-translate`
- 原 `/apps/contract-review`
  -> `/home` 并恢复 `currentSpecialistKey=contract-review-specialist`

兼容跳转只做迁移兜底，不允许再承载新逻辑。

---

## 6. 工作台交互合同

### 6.1 输入区

输入区固定结构：

`[+] [当前对象 chip] [附件] [输入框] [发送]`

规则：

1. `+` 是唯一启动入口
2. `当前对象 chip` 是唯一上下文可视入口
3. 输入区永远不因为对象类型不同而变成另一套布局

### 6.2 `+` 菜单

`+` 菜单只负责 4 类动作：

1. 切模式
2. 启动 / 切换专员
3. 启动工具
4. 打开连接器相关能力

`+` 菜单不负责跳执行页。

### 6.3 当前对象 chip

规则：

1. 固定显示在 `+` 右边
2. 始终展示当前焦点对象
3. 专员、工具结构统一，只是样式和文案不同
4. 点击 chip 只提供：
   - 展开详情
   - 切焦点
   - 打开配置抽屉

点击行为始终留在当前执行工作面内。

### 6.4 设置条

设置条服务当前焦点对象，并由当前焦点对象驱动。

规则：

1. 只服务 `focusedObjectKey`
2. 改动从下一条消息开始生效
3. 不允许继续根据 `/tools/*` 路由推断工具身份

### 6.5 右栏

右栏固定两个 tab：

- 工作流
- 产物

规则：

1. 右栏服务当前焦点对象
2. 专员焦点时，展示专员级工作流与产物
3. 工具焦点时，展示工具级执行流与产物
4. 右栏不允许只支持专员、不支持工具

---

## 7. 对象生命周期

每个专员 / 工具都必须服从统一生命周期：

### 7.1 启动

启动来源：

- `+` 菜单
- 目录页中的“启动”动作
- 兼容跳转恢复

启动结果：

- 对象进入当前任务上下文
- 成为可聚焦对象
- 在输入区显示为当前对象或可切换对象

### 7.2 配置

配置行为包括：

- 修改模式
- 修改对象设置
- 打开对象详情
- 调整对象参数

配置结果必须记录在任务上下文，而不是记录在页面局部状态。

### 7.3 关闭

关闭对象后：

- 从当前任务的已打开对象列表中移除
- 关闭该对象设置条
- 焦点自动切回其他对象

关闭表示从当前任务上下文卸载对象。

### 7.4 重新打开

如果任务里已经存在一个对象，再次点击它时：

- 默认切焦点
- 不再重复创建

---

## 8. 页面职责收敛

### 8.1 `BusinessAppPage` 的状态

`BusinessAppPage` 已从前端仓库移除。

这说明以下约束已经落地：

- 不再承担聊天执行
- 不再承担任务推进主入口
- 不再与 `/home` 形成并行的第二工作台

### 8.2 各 `ToolPage` 的状态

`DocumentTranslatePage`、`CopyProofreadingPage`、`AudioTranscribePage` 等旧工具执行页已从前端仓库移除。

它们留下来的有效资产只剩两类：

1. 已抽离出的 schema / runtime / 组件
2. 历史设计文档中的迁移记录

它们已经不再作为产品形态存在。

---

## 9. 数据层约束

### 9.1 任务是唯一事实来源

以下运行时状态必须最终可从任务恢复：

- 当前专员
- 当前工具
- 已打开工具列表
- 当前焦点对象
- 对象设置快照
- 关键工作流状态
- 产物列表

### 9.2 禁止继续混用演示数据与真实数据

以下情况必须逐步清理：

- 页面本地写死 `messages`
- 页面本地写死 `taskItems`
- 工作台 snapshot 与 live data 混合渲染但界面上不区分

迁移后应满足：

1. 真数据就渲真数据
2. 演示态必须明确标注为模板 / 示例 / 空态
3. 不允许让示例数据冒充真实任务结果

---

## 10. 迁移顺序

### Phase 0：合同冻结

先冻结这份合同，后续改造按它执行。

### Phase 1：补全任务上下文

目标：

- 增加 `currentSkillKey`
- 让技能脱离路由身份，先进入任务 store

结果：

- 选技能不再只是跳页
- 工作台第一次具备“任务 + 专员 + 技能”的统一上下文

### Phase 2：统一当前对象

目标：

- `CurrentObjectChip` 改为真正读任务上下文
- 设置条改为读 `focusedObjectKey`
- 右栏从“专员面板”演进为“对象面板”

结果：

- 输入区、设置条、右栏三者对齐

### Phase 3：路由收敛

目标：

- `/apps/*` 全部改兼容跳转
- `/tools/*` 全部改兼容跳转

结果：

- `/home` 成为唯一执行工作面

### Phase 4：删除重复执行页

目标：

- 删除各类工具执行页中的消息流、输入框、任务逻辑
- 删除各类专员执行页中的聊天职责

结果：

- 页面树明显收缩
- 状态源头回归统一

### Phase 5：命名与对象清洗

目标：

- 拆分专员 key 与工具 key 冲突
- 清理旧命名
- 清理遗留兼容逻辑

结果：

- 模型稳定
- 后续功能可持续扩展

---

## 11. 禁止事项

从这份合同生效开始，以下做法视为逆行：

1. 再新增任何 `/tools/*` 执行页
2. 再新增任何 `/apps/*` 执行页
3. 在页面局部状态里偷偷维护“当前工具”
4. 继续复用同一个 key 同时代表专员和工具
5. 让当前对象由页面 `prefer` 或路由猜测，而不是由任务上下文决定
6. 让右栏只支持专员，不支持工具

---

## 12. 最终产品语义

最终用户感知必须收敛为：

- 我在一个工作台里
- 我当前正在处理一条任务
- 这条任务挂了某个专员
- 这条任务打开了若干工具
- 我现在聚焦在某个对象上
- 我可以启动、配置、关闭这些对象
- 我不需要理解页面切换，只需要理解任务上下文

如果界面上任何一个交互让用户重新产生：

`我是不是又跳进了另一个工具页 / 专员页`

那就说明这次改造没有做完。

---

## 13. 小E 主对话对象前后台合同

> 2026-09-19 补注：本节覆盖本文中早期的「通用助手 = 默认专员」「数字技术员」等旧口径。当前正式对象语义以 `小E / 专员 / 技能 / xapp` 为准。

### 13.1 顶层定位

- **小E**：平台最高级对话对象，负责统一入口、持续陪同、任务识别、对象编排。
- **专员**：领域主责对象，负责某一类专业问题的持续处理。
- **技能**：具体动作对象，负责单项执行与交付。
- **xapp**：持续工作空间对象，负责承载任务过程、结果面板与状态区域。

核心原则：

```text
小E 不隐身，但要退后。
小E 负责陪同与编排，专员负责当前主责。
人格可以保留，但不能越过工作的边界跟用户说话。
```

### 13.2 前后台规则

| 场景 | 前台对象 | 后台对象 | 说明 |
|---|---|---|---|
| 用户刚进入平台、尚未指定对象 | 小E | 无 | 小E 作为默认入口接住需求，判断是直接回答、挂技能、切专员，还是进入 xapp。 |
| 小E 判断问题可直接回答 | 小E | 可感知全部对象，但不切换 | 问答结束即可，不强行挂对象。 |
| 小E 调用某个专员 | 专员 | 小E 退到编排层 | 小E 先做一次明确交接，然后让专员成为当前前台主责对象。 |
| 专员处理中 | 专员 | 小E 持续观察全局 | 小E 不抢主语，不覆盖专员的专业表达；仅保留在状态条、标题层或会话控制层。 |
| 专员需要具体动作能力 | 专员 | 技能 | 技能作为执行能力被调用，不升到对话主位。 |
| 小E 或专员判断进入持续工作态 | 小E + xapp 右栏 | 专员 / 技能按需挂载 | 主对话仍由小E连续陪同，xapp 进入右栏承载工作区、结果区、状态区。 |
| 需要跨专员切换或跨对象协调 | 小E | 原专员退后，新专员待命 | 小E 重新回到前台做编排与交接，避免两个专员直接抢主语。 |
| 任务收口与总结 | 小E | 专员 / 技能 / xapp 结果可被引用 | 最终由小E 做统一收口，把结果、下一步和对象关系讲清楚。 |

### 13.3 明确禁止

- 不允许小E长期伪装成某个领域专员。
- 不允许专员越权冒充平台总入口。
- 不允许技能直接占据持续对话主位。
- 不允许 xapp 替代主对话对象发散式聊天。
- 不允许人格表达遮蔽当前实际负责的对象、执行动作和产物状态。

### 13.4 一句话口径

```text
小E = 平台主对话对象
专员 = 领域主责对象
技能 = 具体动作对象
xapp = 持续工作空间对象
```