docs: 重构仓库文档目录并迁移训练素材
按当前架构重组 docs 目录，统一中文命名与目录分层，并将训练原材料迁移到独立目录以保持架构文档边界清晰。
This commit is contained in:
eaiadmin
@@ -0,0 +1,531 @@
|
||||
# 数字员工 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 = 持续工作空间对象
|
||||
```
|
||||
Reference in New Issue
Block a user