eaiadminandClaude Code
593323a934
一次性提交当天全部改动（110 个文件）。 **未按 TOP_CODING_RULES.md G14.5「一次提交只装一件事」拆分** —— 用户明确要求 单一提交，此处如实记录，不静默忽略该冲突。 提交前验证：后端 go build / go vet / go test ./... 全绿，前端 npm run build exit 0，/api/health 与管理员 login 均返回 200。 - 专员目录收敛为 6 个：下线 knowledge-operations / process-coordination / presentation-briefing / report-generation 四个专员（前后端 manifest 与 seed 同步删除），新增 general-assistant。专员的归属关系（拥有哪些技能定义、 哪些目录项、提示词与绑定从哪来）改由 specialists/core 的 ownership.go、 prompt_provider.go、binding_provider.go 统一提供，seed 与 admin_handlers 随之内置化，卸载路径统一走 uninstall.go。 - 技能：补齐 text-to-speech 的前端 manifest（后端包在 HEAD 已存在）， skillcore/ownership.go 提供与专员对称的归属查询。 - AI 路由：ai_config.json 由 OpenRouter/Ollama 切到 LMUAI / SiliconFlow / llama.cpp 本地路由，ai_secrets.example.json 与部署 env 样例同步新增 SILICONFLOW_API_KEY。 - 系统管理页重整：新增 AiAdminPage、OrganizationManagementPage，删除 AdminOverviewPage、CompanyConfigPage，SystemConfigPage 精简，nav / router / config/workbench.js 同步调整。依 G05.5，开发阶段直接收口到新结构，不留旧路由。 - 新增 internal/objectrefs：统一统计对象（专员 / 技能 / xapp）的运行时引用 （被多少 xapp、项目、任务引用），供管理页做删除前的影响面判断。 - 公众号创作专员：新增 OfficialAccountSpecialistPanel，workflow 与投递链路调整。 - XApp：考试 / 培训 Shell 扩展，XAppDirectoryPage 与 xappDefinition 同步。 - 文档：新增 GW01–GW05 工作台演进系列与 AR12 对话驱动与结构化交互架构； 同步 AR05 / SY17 / SY23 / SY25 / PL04；TOP_CODING_RULES.md 增补 G05.5。 Co-Authored-By: Claude Code <noreply@anthropic.com>
559 lines
14 KiB
Markdown
559 lines
14 KiB
Markdown
# 数字员工 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 迁移期必须新增的状态
|
||
|
||
第一阶段必须补上：
|
||
|
||
```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. 右栏不允许只支持专员、不支持工具
|
||
|
||
### 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**：持续工作空间对象，负责承载任务过程、结果面板与状态区域。
|
||
|
||
核心原则：
|
||
|
||
```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 = 持续工作空间对象
|
||
```
|