pj0235-eai_agentplatform/docs/02_Architecture/AR05_工作台架构约定.md

数字员工 Workbench 架构合同

落盘日期：2026-09-16 状态：架构合同 作用：作为后续前端重构的强约束，先定模型，再做代码迁移 关联文档：AR08_角色交互设计.md、AR12_对话驱动与结构化交互架构.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 迁移期必须新增的状态

第一阶段必须补上：

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

其中：

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

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

4.3 最终推荐状态模型

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

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. 右栏不允许只支持专员、不支持工具

6.6 关键分叉节点交互

Workbench 采用混合交互架构：

• 对话负责发起任务与局部修订
• 结构化 UI 负责关键分叉节点接管
• 右栏负责持续展示阶段、结果与回退点

因此，以下节点不允许只靠消息流向下滚动：

1. 选题
2. 标题
3. 路由
4. Provider
5. 发布
6. 删除
7. 覆盖已有结果
8. 切换当前主责对象

这些节点一律视为关键分叉节点，必须满足：

1. 显式列出候选项
2. 提供一键确认入口
3. 允许用户手工改写，而不是只能选现有项
4. 标明当前结果是“用户确认”还是“系统默认”
5. 未确认前，不得静默继续执行下游步骤

---

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：持续工作空间对象，负责承载任务过程、结果面板与状态区域。

核心原则：

小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 一句话口径

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