EaiLab/pj0235-eai_agentplatform
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 工作台设计稿收入 docs 体系，routes.go 更名 ai_routes.go

Browse Source 
7 份散落在 frontend/src/views/workbench/ 的设计稿按现有编号体系收入 docs/，
源码目录现在只剩 12 个 .vue 页面：

  PlatformArchitectureRethink       -> docs/01_System_Overall/SY24
  WorkbenchArchitectureContract     -> docs/02_Architecture/AR05
  SkillPackagingSpecification       -> docs/02_Architecture/AR06
  ArchitectureAlignmentAudit        -> docs/02_Architecture/AR07
  RoleInteractionDesign             -> docs/02_Architecture/AR08
  YunQuParityRoadmap_OfficePlatform -> docs/06_Product_Lines/PL04
  WorkBuddySkillRpaLearning         -> docs/09_Research/RS01

14 处交叉引用同步更新（含 SY20/SY21 里指向旧源码路径的两处）；三份 README 索引
补齐 SY20-SY24 与 AR05-AR08、PL04；README 顶部「本目录全是历史快照」的说法改精确
（AR05-AR08、PL04 不属于 V1.1 / V1 快照）。

AR08 文首补注「采纳与废弃」，避免它被当成现行设计照做：
- 已采纳：对象不跳页 / 不做独立工具页 / + 菜单挂载 / 切换对象=更新任务上下文
- 已废弃：「数字技术员」第三类对象（SY21 §2.2 已废除 tool 命名）、
  「通用助手 = 默认专员」、§14「与本稿冲突以本稿为准」的自我授权

backend-go: internal/api/routes.go -> ai_routes.go。该文件管的是 AI 模型路由
（LLM provider 列表），与 router.go 的 URL 路由注册同包同名易混，加文件头注释钉死。

验证：go build ./... 通过；go vet ./internal/api/ 无告警；npm run build 通过。

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
eaiadmin
2026-09-17 19:26:26 +08:00
co-authored by Claude Code
parent 24cac4de6e
commit fa6c26ea41
16 changed files with 5735 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/01_System_Overall/README.md
+14 -1
View File
@@ -2,6 +2,9 @@
> **命名规则：** `SY{NN}_{描述}.md`
> **用途：** 系统概述、架构愿景、设计原则
>
> **当前统一口径：** 术语与一级导航请以 `SY21`、`SY22` 为准。
> 当前产品一级导航目标态为：`新建任务 / 项目 / 专员·技能·APP·连接器 / 长程APP / 知识库 / 后台管理 / 我的`
## 文件清单
@@ -24,9 +27,14 @@
| `SY14_Industry_Derived_Connector_And_Application_Requirement_Matrix.md` | 从六个行业反推连接器与应用方向矩阵 |
| `SY15_Terminology_Benchmark_Ontology_Semantic_Layer_Object_Layer.md` | 本体层 / 语义层 / 对象层命名基准研究（含星邺汇捷 / Palantir / Microsoft / Salesforce 对照） |
| `SY16_Ontology_Generalizes_Data_Actions_And_Workflows.md` | 本体如何让数据、动作、工作流一般化 |
| `SY17_Workbench_UI_Wireframes.md` | 数字员工平台 UI 线框图（知识库固定 + 专员动态生长） |
| `SY17_Workbench_UI_Wireframes.md` | 数字员工平台 UI 线框图（早期线框推演，当前命名与导航以 SY22 为准） |
| `SY18_DWP_DW_ADW_Formal_Design_Contract.md` | DWP / DW / ADW 正式设计合同（供人和 AI 共用的对象基准） |
| `SY19_Universal_Digital_Worker_Product_Planning.md` | 通用数字员工平台 V1.0 产品规划（先通用、后定制的产品打法收口） |
| `SY20_Role_Card_And_Lightweight_Ontology_Architecture.md` | 角色卡与轻量本体对象架构（专家对象交互属性的历史收敛稿） |
| `SY21_Unified_Role_Skill_Action_Architecture.md` | 统一 Expert / Skill / Action 总架构确认稿（六层架构与命名收口） |
| `SY22_Role_Skill_App_Unified_Task_Architecture.md` | Expert / Skill / App 统一任务架构（把 App 升级为一级对象、补齐完整一级导航、并将知识库确认为默认内建 App，产品名收口为“长程APP”） |
| `SY23_Specialist_Rule_File_And_Skill_Binding_Plan.md` | 专员「岗位说明书 + 技能绑定」改造方案（诊断运行时同质化根因 + 三步打通链路 + AionUi 规则文件改写清单） |
| `SY24_Platform_Architecture_Rethink.md` | 数字员工平台整体架构重思考（Workbench 收敛与对象化迁移**历史稿**，其结论已并入 SY21 / SY22） |
## 当前主线关系
@@ -44,3 +52,8 @@
12. `SY17`：把六层架构落成数字员工平台工作台线框，明确平台不再是单一导航后台
13. `SY18`：正式定义 DWP / DW / ADW 的结构合同、字段规范和 AI 生成规则
14. `SY19`：把当前阶段产品路线正式收口为「先通用数字员工、后行业包与企业定制」
15. `SY20`：把角色卡从 UI 文案提升为角色对象内建属性，并确认轻量本体的落地边界
16. `SY21`：正式收口六层架构与 `expert / skill / action / connector / policy` 总命名
17. `SY22`：在 `SY21` 基础上补齐第三类一级对象 `app`，补全完整一级导航视图，并将知识库确认为默认内建 App，把平台升级为 Expert / Skill / App 三对象统一任务系统，产品名收口为“长程APP”
18. `SY23`：定位到「专员与技能之间缺绑定边、专员说明未进 prompt」是专员的运行时空洞根因，给出三步打通方案与 AionUi 规则文件改写清单
19. `SY24`：Workbench 收敛与对象化迁移的历史重思考稿，结论已并入 `SY21` / `SY22`；本文只作背景追溯，命名一律以 `SY21` 为准
docs/01_System_Overall/SY20_Role_Card_And_Lightweight_Ontology_Architecture.md
+484
View File
@@ -0,0 +1,484 @@
# SY20 — 角色卡与轻量本体对象架构
> 状态：架构建议稿
> 日期：2026-09-16
> 关联文档：
> - `SY03_Knowledge_Centric_Agent_Platform_Strategy.md`
> - `docs/01_System_Overall/SY24_Platform_Architecture_Rethink.md`
> 2026-09-16 术语同步：
> 本文档继续成立，但请以 `SY21_Unified_Role_Skill_Action_Architecture.md`、`SY22_Role_Skill_App_Unified_Task_Architecture.md` 为总架构收口版本。
> 其中最关键的口径更新是：
> - 角色卡属于专家对象属性，不再单列为独立架构层
> - 对外当前统一采用 `专家 / 技能 / 长程APP / 知识库`
> - 对内正式收敛为 `expert / skill / app / action / connector / policy`
> - 当前一级导航目标态为 `新建任务 / 项目 / 专员·技能·APP·连接器 / 长程APP / 知识库 / 后台管理 / 我的`
> - 本文中原先出现的“角色 / Role / 工具”概念，应理解为历史过渡词，未来命名统一转向 `专家 / 技能 / action`
---
## 1. 这份文档要回答什么
在当前工作台架构下，我们已经确认：
- 专员和技能都不应该再是独立页面
- 它们都应该作为可挂载对象进入 `/home`
- 当前最大问题已经不是“怎么跳转”，而是“对象本身怎么定义”
这份文档要回答 3 个关键问题：
1. 专员和技能型角色是否应该统一为同一种对象
2. 是否应该引入类似 character.ai 的“角色卡”
3. 是否应该在当前阶段引入“本体 / ontology”
---
## 2. 核心结论
### 2.1 专员和工具应统一为同一种对象
建议统一收敛为：
**角色对象（Role Object）**
两者底层结构基本一致，差异只在能力边界：
- 工具：单能力、单任务域、通常不再继续调用别的工具
- 专员：多步骤、可编排、允许调用工具完成子任务
也就是说：
**工具不是“低一层的页面”，而是“能力范围更窄的角色”。**
### 2.2 应该加入角色卡，而且要作为对象内建属性
建议明确加入：
**Role Card = 角色对象的可定义交互外壳**
它不只是欢迎语，而是对象如何被用户感知、如何开场、如何引导用户进入任务的第一层契约。
欢迎语应从硬编码 UI 文案，升级为：
**对象属性驱动的开场定义**
### 2.3 应该加入本体，但当前只做轻量本体
建议加入：
**轻量运营本体（Lightweight Operational Ontology）**
但不建议现在就上完整 RDF / OWL / SHACL 那套重语义工程。
当前阶段更合适的是：
- 先定义平台自己的对象类型、动作类型、产物类型、关系类型
- 先服务工作台挂载、执行链、权限、结果展示
- 先把“平台语义层”立起来
而不是一开始就追求语义网级别的正式本体工程。
---
## 3. 为什么要引入角色卡
### 3.1 当前问题
现在工作台的问题不是“没有欢迎语”这么简单，而是：
- 选了专员后，页面不知道该如何以这个对象的身份开场
- 选了工具后，只是多了一个 chip，但没有人格化 / 职责化表达
- 当前欢迎态仍然是“通用助手门厅”，不是“当前对象门厅”
这说明我们缺的不是一句文案，而是：
**对象自我介绍能力**
### 3.2 角色卡的价值
角色卡负责定义：
1. 这个对象是谁
2. 它擅长什么
3. 它怎么和用户说话
4. 它建议用户怎么开始
5. 它不做什么
所以角色卡不是装饰，而是对象定义的一部分。
### 3.3 角色卡应该覆盖的内容
建议 `role_card` 最少包含：
```json
{
"name": "合同审查专员",
"tagline": "把合同风险、红线和交付意见整理清楚",
"greeting": "我是合同审查专员，已经准备好帮你定位条款风险、整理红线建议，并输出可交付的审查结果。",
"relationship_to_user": "你的法务协作搭档",
"tone": "专业、直接、可追溯",
"opening_prompt": "把合同发给我，或者直接告诉我这次要重点盯哪些条款。",
"starter_prompts": [
"审查这份采购合同的风险点",
"帮我整理一版 redline 建议",
"重点看赔偿责任和终止条款"
],
"boundaries": [
"我会指出风险，但不替代人工法律意见",
"高风险条款会明确标出待人工确认"
]
}
```
---
## 4. 为什么要引入轻量本体
### 4.1 我们真正需要的不是“知识图谱名词”，而是平台统一语义
如果没有本体层，平台会继续出现这些问题：
- 专员和工具只是 UI 名字，没有统一语义身份
- 任务挂的是 `specialist_key`，但系统不知道对象之间是什么关系
- 工作流、产物、动作、知识对象各自分散，难以统一编排
- 后面做多对象协作时，平台不知道谁能调用谁、产出什么、依赖什么
### 4.2 当前阶段不适合直接上重本体
完整本体工程的问题不在“对不对”，而在“此刻成本太高”：
- 建模成本高
- 治理成本高
- 版本演进成本高
- 需要更成熟的数据治理和知识工程流程
对我们当前阶段来说，最重要的是先统一平台对象语义，而不是先做语义网工程。
### 4.3 当前阶段建议的本体范围
建议只定义 5 类核心语义：
1. **角色类型**
- specialist
- tool
2. **对象类型**
- contract
- customer
- report
- resume
- knowledge_item
3. **动作类型**
- analyze
- extract
- review
- draft
- translate
- escalate
4. **产物类型**
- summary
- report
- redline
- checklist
- spreadsheet
5. **关系类型**
- can_use_tool
- produces_artifact
- acts_on_object
- depends_on
- cites_knowledge
这就足以支撑我们当前的工作台对象化。
---
## 5. 建议采用的统一对象架构
### 5.1 根对象：`object_definition`
不建议再把“专员定义”和“工具定义”拆成两套根结构。
建议统一使用已有方向里的：
**`object_definition`**
然后在里面用 `role_kind` 区分：
- `specialist`
- `tool`
### 5.2 建议结构
```json
{
"id": "obj.contract-review",
"code": "EAI-R-001",
"key": "contract-review",
"label": "合同审查专员",
"object_class": "role",
"role_kind": "specialist",
"source": "eai",
"status": "active",
"role_card": {
"tagline": "把合同风险、红线和交付意见整理清楚",
"greeting": "我是合同审查专员，已经准备好帮你定位条款风险并输出审查建议。",
"relationship_to_user": "你的法务协作搭档",
"tone": "专业、直接、可追溯",
"opening_prompt": "把合同发给我，或者告诉我这次重点审哪些条款。",
"starter_prompts": [
"审查这份采购合同的风险点",
"帮我整理一版 redline 建议"
],
"boundaries": [
"我会标出高风险项",
"最终法律意见仍需人工确认"
]
},
"capability_profile": {
"summary": "条款识别、风险分析、红线建议、交付摘要",
"input_types": ["document", "text"],
"artifact_types": ["summary", "redline", "checklist"],
"can_chat": true,
"can_execute": true
},
"collaboration_profile": {
"callable_tool_keys": ["document-translate", "batch-extract"],
"can_be_called_by": [],
"orchestration_mode": "supervisor"
},
"ontology_binding": {
"acts_on_object_types": ["contract"],
"action_types": ["review", "analyze", "draft"],
"produces_artifact_types": ["summary", "redline", "checklist"],
"knowledge_domains": ["legal", "compliance"]
},
"execution_profile": {
"settings_schema": [],
"executor_key": "contract-review",
"result_card_key": "contract-review"
}
}
```
### 5.3 工具对象也用同一结构
工具只是把 `role_kind` 改为 `tool`：
```json
{
"key": "document-translate",
"label": "文档翻译",
"object_class": "role",
"role_kind": "tool",
"role_card": {
"tagline": "把内容准确翻译成目标语言并输出指定格式",
"greeting": "我是文档翻译工具，可以把文本、文档整理成目标语言输出。",
"relationship_to_user": "你的翻译执行角色"
},
"collaboration_profile": {
"callable_tool_keys": [],
"orchestration_mode": "none"
}
}
```
也就是说：
**工具和专员不是两套模型，而是一套模型上的两个角色种类。**
---
## 6. 专员与工具的真正差异
建议只保留这一个核心差异：
### 6.1 工具
- 聚焦单能力
- 输入输出边界更明确
- 通常不再调别的工具
- 更像“执行角色”
### 6.2 专员
- 聚焦任务闭环
- 可以调用多个工具
- 会管理步骤、产物、待确认点
- 更像“编排角色”
所以：
**专员 = 能调用工具的角色对象**
而不是：
**专员 = 页面，工具 = 页面里的功能按钮**
---
## 7. 对工作台交互的直接影响
### 7.1 欢迎态改成对象驱动
当前 `/home` 的欢迎态不应再写死成通用助手。
应该改为：
1. 如果当前挂的是对象，就优先显示该对象的 `role_card.greeting`
2. `starter_prompts` 作为欢迎态快捷入口
3. `tagline / opening_prompt / boundaries` 作为辅助说明
4. 如果没有挂对象，再退回通用助手默认欢迎态
### 7.2 输入框左侧对象 chip 不再只是标签
它应表达：
- 当前对象是谁
- 当前对象属于 `specialist` 还是 `tool`
- 当前对象的 `tagline`
### 7.3 右栏不应再叫“专员面板”
因为工具也是角色对象。
建议后续改成更中性的：
- `ObjectPanel`
- `RolePanel`
只是当对象是 `specialist` 时，展示更完整的工作流与产物；
当对象是 `tool` 时，展示它的输入边界、执行结果、相关产物。
---
## 8. 对数据层的建议
### 8.1 先别引入新根对象名，先复用 `object_definition`
当前项目已经在往：
- `object_definition`
- `task_object_instance`
- `object_run`
- `task_message`
这条路上走。
因此不建议再新起一套：
- `specialist_definition`
- `tool_definition`
- `role_definition`
而是：
**在 `object_definition` 里加角色属性分组。**
### 8.2 建议新增的对象属性分组
建议统一加这几组：
- `role_kind`
- `role_card_json`
- `capability_profile_json`
- `collaboration_profile_json`
- `ontology_binding_json`
### 8.3 后端可以分阶段兼容
第一阶段不必立刻改完后端表。
可以先在前端 registry 和 specialist adapter 里形成统一结构：
- 内置工具走前端静态定义
- 专员走后端字段 + 前端适配
- 统一映射成 `object_definition` 视图模型
等结构稳定后，再把后端持久化模型补齐。
---
## 9. 当前阶段的实施建议
### Phase 1：先把角色卡引入前端对象视图层
先做：
- `role_card` 统一适配层
- `/home` 欢迎态改为对象驱动
- 专员 / 工具都能显示自己的 greeting 与 starter prompts
这一步不要求后端表结构大改。
### Phase 2：把 Studio / Market 的专员编辑升级为对象编辑
新增：
- 欢迎语
- tagline
- opening prompt
- starter prompts
- boundaries
让专员卡真正可定义。
工具也开始逐步以同样结构注册。
### Phase 3：补轻量本体层
建立平台统一字典：
- object types
- action types
- artifact types
- relation types
先服务工作台、运行链和知识引用，不追求重语义工程。
---
## 10. 最终建议
这次不建议二选一，而是建议同时引入两层：
### 必须现在就做
1. **角色卡**
- 必须加
- 而且要作为对象属性
- 欢迎语、引导语、starter prompts 都应从这里来
2. **统一对象模型**
- 专员和工具统一为 `object_definition`
- 用 `role_kind` 区分
- 专员只是“可调用工具的角色”
### 应该现在开始，但先做轻量版
3. **轻量本体**
- 必须做
- 但只做平台运营本体
- 不要一开始就上重 RDF / OWL 工程
### 暂时不要做的事
4. 不要再继续把“欢迎语”写成页面模板文案
5. 不要再继续把“工具”当页面，而不是角色
6. 不要现在就把本体做成知识工程大项目
---
## 11. 一句话收口
建议把平台对象统一定义为：
**“带角色卡的角色对象”**
其中：
- 工具 = 单能力角色
- 专员 = 可调用工具的编排角色
- 本体 = 这些角色、动作、对象、产物之间的轻量语义骨架
docs/01_System_Overall/SY21_Unified_Role_Skill_Action_Architecture.md
+691
View File
@@ -0,0 +1,691 @@
# SY21 — 统一 Expert / Skill / Action 总架构确认稿
> 状态：总架构确认稿
> 日期：2026-09-16
> 关联文档：
> - `SY03_Knowledge_Centric_Agent_Platform_Strategy.md`
> - `SY15_Terminology_Benchmark_Ontology_Semantic_Layer_Object_Layer.md`
> - `SY20_Role_Card_And_Lightweight_Ontology_Architecture.md`
> - `docs/01_System_Overall/SY24_Platform_Architecture_Rethink.md`
> 2026-09-16 术语同步：
> 本文原先使用 `Role / role / role_card` 作为主术语。
> 现已确认 `Role` 不再作为推荐命名，统一改口为：
> - 对外：`专家（Expert） / 技能 / 连接器`
> - 对内：`expert / skill / action / connector / policy`
> 文中尚未完全迁移的 `role`、`role_card`、`角色对象层`，后续均应分别理解为 `expert`、`expert_card`、`专家对象层`。
---
## 1. 这份文档要确认什么
在前面几轮讨论后，当前项目已经不再缺“局部页面方案”，真正缺的是一份统一总架构结论，用来回答以下问题：
1. 平台到底按几层架构来收敛
2. 本体、角色卡、对象、技能、Action、连接器分别处于什么位置
3. 对外到底暴露什么，对内到底运行什么
4. 是否还要继续使用 `tool` 这个词
5. 当前代码和文档后续应该往哪个方向迁移
这份文档的目标不是给出某个局部功能设计，而是把平台的总语言、总结构、总对象模型先定下来。
---
## 2. 最终结论
## 2.1 平台采用六层总架构
建议正式统一为六层：
1. 外部连接层
2. 本体与语义上下文层
3. 总线与编排层
4. 能力层
5. 专家对象层
6. 工作台与运行治理层
这六层已经足以覆盖：
- 通用数字员工
- 文档类、知识类、分析类能力
- 工业设备监测、安防、巡检、告警、工单等强外部接口场景
## 2.2 不再把 `tool` 作为正式命名
命名上正式收敛为：
- 对外：`专家 / 技能 / 连接器`
- 对内：`expert / skill / action / connector / policy`
结论：
**以后不再新增正式架构概念 `tool`。**
`tool` 只作为历史迁移词存在，用于兼容旧文档、旧字段、旧目录，不再作为未来架构的主词。
## 2.3 对外默认暴露 `专家 + 技能`
外部用户看到的应该是：
- 专家
- 技能
- 欢迎语
- starter prompts
- 可完成的任务
而不是：
- tool 列表
- 底层调用动作
- 技术执行接口
所以：
**用户入口层默认暴露 skill，不暴露 action。**
## 2.4 对内统一使用 `action`
内部最小执行单元统一叫：
**Action**
它用于承接：
- 一次原子能力执行
- 一次外部系统调用
- 一次标准化输入输出动作
- 一次可授权、可审计、可编排的执行操作
也就是说：
- `skill` 是任务化能力包
- `action` 是原子执行单元
## 2.5 要引入本体层，而且是必需的
如果平台后续要扩展到：
- 工业设备运行监测员
- 安防管理员
- 巡检专员
- 告警分析专员
- 工单协调专员
那么本体层不是可选项，而是必要项。
原因很简单：
没有本体层，上层对象和工作台体验很快就会被行业对象、事件、状态、规则的差异撕裂。
## 2.6 专家卡不是独立层，而是专家对象属性
角色卡仍然要保留，但它不是一层单独架构层。
更准确的定义是：
**专家卡 = 专家对象的交互属性集**
它负责：
- 角色是谁
- 角色如何开场
- 角色如何和用户说话
- 角色建议用户如何开始
- 角色承诺做什么、不做什么
---
## 3. 六层总架构定义
## 3.1 第一层：外部连接层
这一层负责连接真实世界和外部系统。
包括：
- PLC
- SCADA
- MES
- ERP
- CRM
- CMMS / 工单系统
- IoT 平台
- 视频平台
- 文档系统
- 数据库
- API / Webhook / MQ
这一层回答的是：
**数据从哪里来，动作往哪里去。**
在本项目里，这一层的标准对象是：
- `connector_definition`
- `connector_binding`
## 3.2 第二层：本体与语义上下文层
这一层负责定义平台语义。
它不是简单的表结构，而是平台统一语义底座。
当前阶段建议采用轻量本体，先定义：
1. 对象类型
- device
- alarm
- work_order
- report
- contract
- knowledge_item
- person
- site
2. 动作类型
- monitor
- inspect
- diagnose
- review
- extract
- translate
- escalate
- dispatch
3. 状态类型
- running
- warning
- critical
- pending
- approved
- closed
4. 关系类型
- belongs_to
- depends_on
- triggers
- resolves
- cites
- produces
这一层回答的是：
**系统里到底有什么对象，它们如何关联，允许哪些动作。**
## 3.3 第三层：总线与编排层
这一层负责流转，不负责人格，不负责 UI。
它至少应包含三类总线：
1. 上下文总线
2. 事件总线
3. 能力编排总线
职责包括：
- 角色之间的协作
- skill 对 action 的编排
- action 对 connector 的调用
- 事件进入任务上下文
- 审批和安全边界控制
这一层回答的是：
**对象怎么流动，能力怎么协作，任务怎么推进。**
## 3.4 第四层：能力层
这一层正式拆成三类对象：
1. `skill`
2. `action`
3. `policy`
### 3.4.1 skill
`skill` 是面向任务的能力包。
它通常由以下部分组成：
- intent
- prompt template
- action chain
- input schema
- output schema
- artifact schema
- guardrails
可以理解为：
**skill = 用户任务入口 + 规则 + 执行编排模板**
### 3.4.2 action
`action` 是内部原子执行单元。
例如：
- `read_device_status`
- `query_alarm_history`
- `create_work_order`
- `extract_contract_terms`
- `translate_document`
- `generate_shift_report`
它必须具备：
- 标准输入
- 标准输出
- 权限边界
- 风险级别
- 审计记录
### 3.4.3 policy
`policy` 负责定义约束和治理条件，例如：
- 某 action 是否允许自动执行
- 是否需要人工确认
- 哪些角色可以调用哪些 skill
- 哪些 connector 只能读不能写
这一层回答的是：
**系统能做哪些事，这些事如何以任务化和原子化两种粒度存在。**
## 3.5 第五层：专家对象层
这是用户真正感知到的执行主体层。
专家对象统一采用一个根模型，例如：
- `object_definition`
专家对象不再分裂成多套根结构。
建议至少包含两类专家：
1. `assistant`
2. `specialist`
如果后续需要更强的“执行人格化对象”，可补充：
3. `executor`
其中：
- `assistant`：默认兜底编排专家
- `specialist`：面向领域任务的主专家
- `executor`：必要时暴露给用户的窄能力执行专家
这里最关键的变化是：
**专家对象不直接等于 action。**
专家对象负责承接用户、暴露 skill、组织交互体验；
真正执行时，仍然落到 `skill -> action -> connector`。
### 3.5.1 专家卡属于这一层
`expert_card` 是专家对象属性，不再单列成架构层。
建议最少包含：
- name
- tagline
- greeting
- tone
- opening_prompt
- starter_prompts
- boundaries
- relationship_to_user
### 3.5.2 专家对象与能力层的关系
专家对象不直接暴露所有 action。
更合适的关系是：
- 专家对象暴露 `skill`
- `skill` 编排多个 `action`
- `action` 调用 `connector`
所以：
**专家承接用户，skill 组织任务，action 执行动作。**
## 3.6 第六层：工作台与运行治理层
这一层是最终运行现场。
包括：
- `/home` Workbench
- task
- task_message
- task_object_instance
- object_run
- artifact
- workflow panel
- audit / observe / approval
这一层回答的是：
**一条具体任务如何挂载角色、发送消息、运行 skill、触发 action、沉淀产物。**
---
## 4. 最终对象关系
建议以后统一采用下面这条主链路：
`user -> expert -> skill -> action -> connector`
再叠加本体层：
`ontology -> expert / skill / action / connector`
也就是说：
1. 用户不是直接找 action
2. 用户是进入某个专家
3. 专家向用户暴露 skill
4. skill 编排 action
5. action 调用 connector
6. 全程受 ontology 和 policy 约束
---
## 5. 对外暴露模型
## 5.1 对终端用户
默认暴露：
- 专员
- 技能
- 欢迎语
- 任务入口
- 产物结果
默认不暴露：
- action
- connector 技术细节
- 编排细节
- 底层风险策略
## 5.2 对管理员 / 搭建者
可以暴露：
- skill 绑定了哪些 action
- action 绑定了哪些 connector
- 权限和审批条件
- 输出 schema
- 审计与日志
## 5.3 对运行时
直接处理：
- action call
- connector call
- context binding
- event routing
- approval gate
- audit log
---
## 6. 为什么不再使用 `tool`
## 6.1 对外不合适
`tool` 太像功能按钮集合，不像任务语言，也不像角色语言。
尤其在数字员工和工业智能体场景里，它会把产品体验拉回“工具页”心智。
## 6.2 对内也不够精确
内部真正需要区分的是：
- 任务级能力包：`skill`
- 原子执行动作：`action`
- 外部系统入口：`connector`
`tool` 夹在中间，语义反而模糊。
## 6.3 正式命名替换
后续正式命名建议统一为：
- 用户可见的 `tool` -> `skill`
- 内部原子执行的 `tool` -> `action`
- `chatTools` -> `availableSkills`
- `currentToolKey` -> `currentSkillKey`
- `tool_keys` -> `skill_keys`
- 顶部设置条组件 -> `SkillStrip` 或 `ActionStrip`
- 前端技能定义目录 -> `src/skills/*`
- 后端原子动作定义 -> `action_definition / action_refs / action_records`
说明：
当前仓库已有大量 `tool` 历史字段，不建议在总架构确认稿阶段立刻全量重命名；
但从现在开始，**不再新增新的正式 `tool` 命名。**
---
## 7. 角色、技能、Action 的清晰边界
## 7.1 角色
回答的是：
**谁来承接这次任务。**
角色包含：
- 身份
- 角色卡
- 协作边界
- 可暴露 skills
- 权限范围
## 7.2 技能
回答的是：
**用户想完成什么任务。**
技能包含：
- 任务意图
- 开始条件
- 输入输出约束
- 产物定义
- 对 action 的编排模板
## 7.3 Action
回答的是：
**系统这一步到底执行了什么动作。**
Action 包含：
- 原子能力定义
- 风险级别
- 调用协议
- connector 绑定
- 审计信息
---
## 8. 角色卡和本体是否重叠
不重叠。
它们都可能写到“能力”相关内容，但目标完全不同。
## 8.1 本体
服务机器一致性，定义：
- 对象
- 动作
- 状态
- 关系
- 规则
## 8.2 角色卡
服务人机交互一致性，定义：
- 开场方式
- 角色语气
- 任务入口提示
- 用户对该角色的体验预期
一句话：
**本体定义世界，角色卡定义人格。**
---
## 9. 对当前 Workbench 的直接要求
## 9.1 欢迎语必须对象属性驱动
当用户挂载某个角色后，Workbench 不应继续显示通用助手欢迎语。
应改为：
1. 优先显示当前专家的 `expert_card.greeting`
2. 下方展示 `starter_prompts`
3. 辅助展示 `tagline / opening_prompt / boundaries`
4. 无挂载角色时，再退回默认助手欢迎态
## 9.2 输入区顶部应体现当前对象
输入区顶部不应只显示一个孤立 chip。
应明确表达：
- 当前对象是谁
- 当前这次输入会触发什么任务语义
- 当前对象是否存在可调设置
并冻结以下交互规则：
1. `+` 右边一次只显示一个当前对象
2. 当前对象要么是专员，要么是技能，要么是默认助手
3. 专员内部调用技能时，下游技能只进入执行链与右侧面板，不在输入区显性双挂
## 9.3 右侧面板应是对象面板，不再是旧“工具面板”
建议中性命名：
- `ObjectPanel`
- `ExpertPanel`
其内容由当前角色和当前运行态决定，而不是由旧页面类型决定。
---
## 10. 目标数据结构建议
## 10.1 角色定义 `object_definition`
建议继续作为统一根对象，至少补充：
- `object_kind`
- `expert_card_json`
- `capability_profile_json`
- `collaboration_profile_json`
- `ontology_binding_json`
## 10.2 技能定义 `skill_definition`
建议新增独立定义层，至少包含：
- `id`
- `key`
- `label`
- `description`
- `exposed_to_user`
- `input_schema`
- `output_schema`
- `artifact_schema`
- `action_refs`
- `policy_refs`
- `ontology_binding`
## 10.3 Action 定义 `action_definition`
建议新增，至少包含：
- `id`
- `key`
- `label`
- `action_type`
- `connector_ref`
- `input_schema`
- `output_schema`
- `risk_level`
- `approval_mode`
- `audit_level`
## 10.4 运行态
建议继续沿用并收敛为：
- `task`
- `task_object_instance`
- `task_message`
- `object_run`
- `artifact`
其中：
- `task_object_instance` 负责挂载当前角色
- `task_message` 负责持久化会话
- `object_run` 负责记录 skill 和 action 的执行链
---
## 11. 对当前项目的迁移原则
## 11.1 总原则
先定语言，再改代码。
当前阶段最重要的是把架构口径统一为：
- 六层总架构
- 对外 `角色 + 技能`
- 对内 `skill + action + connector`
- `tool` 正式退出未来命名
## 11.2 当前阶段不要做的事
1. 不要继续新增 `tool` 概念
2. 不要再把 action 做成独立页面
3. 不要再让路由承担能力身份
4. 不要让欢迎语继续写死在页面里
## 11.3 下一阶段最值得做的事
1. 先把当前架构文档同步到这一套口径
2. 再把前端欢迎态改为 `expert_card.greeting` 驱动
3. 再把 `tool` 相关变量和目录逐步迁移到 `skill / action`
4. 后续再进入数据库与运行时的对象化升级
---
## 12. 一句话总收口
平台以后应统一理解为：
**一个以本体为语义底座、以角色为用户承接体、以技能为任务入口、以 Action 为原子执行单元、以 Workbench 为统一运行现场的数字员工与工业智能体平台。**
docs/01_System_Overall/SY22_Role_Skill_App_Unified_Task_Architecture.md
+755
View File
@@ -0,0 +1,755 @@
# SY22 — Expert / Skill / App 统一任务架构
> 状态：总架构扩展确认稿
> 日期：2026-09-16
> 关联文档：
> - `SY17_Workbench_UI_Wireframes.md`
> - `SY20_Role_Card_And_Lightweight_Ontology_Architecture.md`
> - `SY21_Unified_Role_Skill_Action_Architecture.md`
---
## 1. 这份文档要解决什么问题
在 `SY21` 中，平台已经正式收敛为六层架构，并明确了：
- 对外暴露 `专家 / 技能 / 连接器`
- 对内运行 `expert / skill / action / connector / policy`
- 不再继续扩张 `tool` 概念
但随着工作台进一步向 WorkBuddy 类产品演进，出现了一个新问题：
**系统里需要一种既不是专家、也不是技能的新一级对象。**
它具备以下特征：
- 不是以对话为主交互
- 有自己长期存在的主界面
- 有结构化状态、表单、题卡、看板、画布等交互
- 启动后应成为一个长程任务实例
- 可挂载右栏 AI、可调用技能、可沉淀业务产物
这类对象不适合继续塞进 `expert`，也不适合伪装成“大 skill”。
因此，这份文档正式确认：
> **平台需要第三类一级对象：App。**
---
## 2. 最终结论
## 2.1 六层总架构继续成立，但第五层升级
`SY21` 的六层架构继续有效：
1. 外部连接层
2. 本体与语义上下文层
3. 总线与编排层
4. 能力层
5. 对象层
6. 工作台与运行治理层
本次变化不是推翻六层，而是把第五层从偏“专家对象层”正式升级为：
> **对象层（Expert / Skill / App）**
## 2.2 App 是一级对象，不是页面，也不是大技能
App 的准确定义是：
> **面向某类长程任务的状态化运行壳。**
它与 Skill 的区别在于：
- `skill` 解决“做什么”
- `app` 解决“这类工作如何持续运行、展示、交互、留痕”
它与 Expert 的区别在于：
- `expert` 解决“谁在与你协作”
- `app` 解决“这项工作在什么界面和状态机里被推进”
## 2.3 任务不再等于对话
平台后续的统一定义应为：
> **任务 = 一个工作实例容器**
这个容器里可以挂载：
- 一个主 `app`
- 一个右栏 `expert`
- 多个后台 `skill`
- 若干 `connector`
因此：
- 对话是任务中的一种交互轨迹
- 不是所有任务都必须以消息流作为主界面
## 2.4 长程APP是一级导航，但一级导航必须完整描述
`app` 升格后，不能只补一句“新增长程APP”，否则会把整个一级导航重新说乱。
一级导航不再是同质栏目，而应明确分成四类：
1. 工作入口
2. 对象目录
3. 组织知识入口
4. 治理与个人入口
推荐的一级导航全景应为：
1. `新建任务`
- 对话驱动任务的默认入口
- 负责创建以 `expert` 为主对象的任务
2. `项目`
- 任务容器与聚合视图
- 用于组织多个长程任务与对话任务
3. `专家 · 技能 · 连接器`
- 对象目录与配置浏览入口
- 这里看的是定义，不是运行时
4. `长程APP`
- `app` 定义卡片入口
- 这里展示的是可启动的长程 App，不是历史任务
5. `知识库`
- 组织级默认内建 App 的直达入口
- 承载组织专有知识、素材、题库、结果记录等核心资产
- 是 Expert 与 App 共同消费的知识底座
6. `后台管理`
- 工坊、系统配置、对象治理、权限治理
- 是平台治理入口，不是业务运行入口
7. `我的`
- 个人总览、我的资料、个人偏好与个人工作视角
这里最重要的边界是：
- `专家 · 技能 · 连接器` 看的是对象定义与配置
- `长程APP` 看的是可运行的 `app`
- `项目` 看的是任务集合
- `知识库` 看的是组织级知识底座与其内建 App 运行面
这里需要明确一个特例：
> **知识库本身也是 `app`，但它不是普通可选 App，而是组织级默认必须存在的内建 App。**
原因是：
- 平台服务的是单一组织而不是开放公域
- 没有组织专有知识，很多 Expert 与 App 无法稳定运行
- 知识库不仅提供资料查看，还承担沉淀、审批、引用、题库与知识资产治理
因此在产品层，知识库同时具有两种身份：
1. 在对象模型里，它属于 `app.knowledge_hub`
2. 在一级导航里，它拥有保留的直达入口，不必埋进“长程APP”卡片列表
点击 `长程APP` 里的卡片后，标准动作应为：
1. 创建任务实例
2. 挂载主 `app`
3. 进入该 `app` 的运行界面
4. 同时进入统一任务列表
当前像 `AI考试` 这种已经长出独立业务界面的主导航，在架构上应理解为**过渡态专题入口**。
后续应逐步收敛为：
- `长程APP -> app.training_exam`
而不是继续长期作为与 `专家 / 技能 / 项目 / 知识库` 并列的专题型一级主栏目。
---
## 3. 三类一级对象的边界
## 3.1 Expert
`expert` 是面向用户协作的交互外壳。
核心职责：
- 理解意图
- 引导开场
- 陪伴推进
- 解释状态
- 调度技能
典型交互：
- 对话主导
- 欢迎语
- starter prompts
- 右栏 AI 助手
## 3.2 Skill
`skill` 是面向任务复用的能力包。
核心职责：
- 封装某类能力
- 编排 `action`
- 规范输入输出
- 生成产物
典型交互：
- 被角色调用
- 被 App 调用
- 被工作流调用
## 3.3 App
`app` 是面向场景化长程任务或组织级运行面的运行壳。
核心职责：
- 承载主界面
- 驱动状态机
- 管理结构化数据
- 组织多步骤交互
- 沉淀长程产物
典型交互：
- 菜单
- 表单
- 按钮
- 题卡
- 看板
- 画布
其中应区分两类 App：
1. **任务型 App**
- 进入后通常创建 `app_task`
- 例如培训考试、审批、数据分析、流程编排
2. **底座型 App**
- 组织级长期存在，默认安装
- 例如知识库
- 它既提供独立运行面，也为其他任务提供知识支撑
AI 在 App 中通常位于：
- 右栏副驾驶位
- 辅助填表
- 规则解释
- 状态总结
- 自然语言触发复杂动作
---
## 4. 六层架构回溯后的新定义
## 4.1 第一层：外部连接层
这一层继续负责连接真实世界与外部系统。
包括：
- 本地文件系统
- 企业业务系统
- 工业系统
- 培训 / 考试 / OA / ERP / MES / CRM / LMS
- 模型服务
- API / Webhook / MQ
这一层回答的是：
**数据从哪里来，动作往哪里去。**
## 4.2 第二层：本体与语义上下文层
这一层需要从行业对象语义继续扩展到工作对象语义。
除了原有：
- device
- alarm
- work_order
- report
还应补充：
- task
- stage
- expert
- skill
- app
- artifact
- form
- workflow
- record
对于 `app`，这一层必须支持：
- App 处理的业务对象类型
- App 允许的阶段类型
- App 产物类型
- App 与 Expert / Skill 的可挂载关系
这一层回答的是：
**平台到底在处理哪些业务对象、工作对象和它们之间的关系。**
## 4.3 第三层：总线与编排层
这一层继续承担流转职责，但要正式接纳 `app` 作为任务主对象。
至少应包含：
1. 任务总线
2. 事件总线
3. 对象挂载总线
4. 能力编排总线
新职责包括：
- 任务创建后挂载主 `app`
- 根据 `app` 状态切换工作台界面
- 允许右栏 `expert` 感知当前 `app` 上下文
- 允许 `app` 调度 `skill`
- 允许人工接管与审批节点插入
这一层回答的是：
**任务如何创建，对象如何挂载，状态如何推进，能力如何协作。**
## 4.4 第四层：能力层
这一层继续保持：
- `skill`
- `action`
- `policy`
但要明确一个边界：
> **App 不进入能力层。**
原因是：
- `skill` 是能力包
- `action` 是原子动作
- `app` 是运行壳
App 可以调用 Skill，但不替代 Skill。
## 4.5 第五层：对象层
这一层正式收敛为：
- `expert`
- `skill`
- `app`
并且三者都应该具备：
- 对象定义
- 版本信息
- 生命周期状态
- 权限边界
- 可挂载关系
这一层回答的是：
**平台有哪些可被用户使用、可被任务挂载、可被版本化治理的一等对象。**
## 4.6 第六层：工作台与运行治理层
这一层不再只有单一对话工作台，而应明确分成两类运行现场：
### A. 对话工作台
- 以专家为主
- 适合模糊任务、探索任务、咨询任务
- 中央区域以消息流为主
### B. 长程APP
- 以 App 为主
- 适合强状态、强结构、长周期任务
- 中央区域以业务界面为主
- AI 位于右栏
两者统一纳入：
- 同一任务列表
- 同一运行治理体系
- 同一审计和产物体系
---
## 5. 统一任务模型
## 5.1 任务是工作实例容器
新的任务定义应为：
> **task = 一次完整工作实例**
它负责统一承载：
- 当前主对象
- 当前阶段
- 当前参与对象
- 当前运行状态
- 当前产物集合
## 5.2 一个任务可挂多个对象实例
建议使用如下运行模型：
- 主挂载：`app` 或 `expert`
- 右栏挂载：`expert`
- 后台挂载：`skill`
例如一个培训考试任务可以是：
- 主对象：`app.training_exam`
- 右栏对象：`expert.learning_coach`
- 后台能力：`skill.auto_grading`
- 后台能力：`skill.study_plan_generation`
## 5.3 会话只是任务的一部分
以后应避免继续把任务状态写死在消息流里。
更准确的关系是：
- `task`：工作容器
- `task_message`：对话轨迹
- `app_state`：App 主状态
- `artifact`：产物
- `event`：运行轨迹
---
## 6. 存储架构建议
## 6.1 对象定义层
建议继续使用统一根定义：
- `object_definition`
- `object_version`
关键字段建议：
- `object_id`
- `object_type`：`expert | skill | app`
- `code`
- `key`
- `label`
- `status`
- `manifest`
- `schema_version`
其中 `app.manifest` 至少应包含：
- `object_entry_route`
- `layout_type`
- `supported_views`
- `default_sidebar_expert`
- `allowed_skills`
- `state_schema`
- `artifact_schema`
- `permission_model`
为避免与 AI 路由和普通页面导航混同，当前项目统一采用三类命名：
- `ai_route_*`：AI 模型路由
- `object_entry_route`：专家 / 技能 / APP 这类业务对象的进入入口
- `page_route`：普通页面导航路径
## 6.2 任务与挂载层
建议新增或统一为：
- `task`
- `task_object_instance`
`task` 核心字段建议：
- `task_id`
- `task_type`：`conversation_task | app_task`
- `title`
- `status`
- `source_object_type`
- `source_object_id`
- `current_stage`
- `started_at`
- `completed_at`
`task_object_instance` 核心字段建议：
- `task_object_instance_id`
- `task_id`
- `object_id`
- `object_version_id`
- `object_type`
- `mount_slot`：`main | right_sidebar | background`
- `instance_role`：`primary | assistant | worker`
## 6.3 运行轨迹层
建议使用：
- `object_run`
- `task_message`
其中：
- `object_run` 记录对象执行、阶段推进、技能调用、人工确认
- `task_message` 仅记录对话内容和消息元数据
需要明确：
> **`task_message` 不再承担 App 主状态存储责任。**
## 6.4 App 状态层
建议为 `app` 单独引入运行时状态存储：
- `app_instance_state`
- `app_event`
- `app_artifact`
`app_instance_state` 建议存：
- `task_id`
- `task_object_instance_id`
- `workflow_state`
- `ui_state`
- `form_state`
- `selected_record_id`
- `snapshot_version`
`app_event` 建议存：
- `event_type`
- `payload`
- `operator`
- `created_at`
`app_artifact` 建议存：
- `artifact_type`
- `artifact_uri`
- `artifact_meta`
- `produced_by`
- `created_at`
## 6.5 领域数据层
对于复杂 App，不应把所有业务数据都塞进 `app_instance_state.payload_json`。
必须允许按领域建模。
例如培训考试 App 可拥有独立领域表：
- `training_plan`
- `course_module`
- `exam_paper`
- `exam_question`
- `exam_attempt`
- `exam_answer`
- `exam_score`
因此存储应分为：
- 通用运行表：承载平台运行
- 领域业务表：承载业务事实
---
## 7. 前端与交互层含义
## 7.1 一级导航升级
前端一级导航不能只补“长程APP”这一项，而应整体升级为完整的信息架构。
建议目标态如下：
1. `新建任务`
- 默认进入对话工作台
- 主对象通常为 `expert`
2. `项目`
- 承载项目列表与项目详情
- 用于聚合任务、产物与阶段
3. `专家 · 技能 · 连接器`
- 展示 `expert / skill / connector` 的定义目录
- 负责浏览、筛选、配置、安装态查看
4. `长程APP`
- 展示 `app` 定义卡片
- 负责启动 `app_task`
5. `知识库`
- 作为默认必须存在的内建 App 直接出现在一级导航
- 承载组织知识、素材、题库、记录与知识治理
- 是任务运行的公共知识面
6. `后台管理`
- 承载工坊、系统配置、组织与治理能力
7. `我的`
- 承载个人总览、个人资料与个人入口
因此，一级导航里实际并存四种不同语义：
- 工作启动入口：`新建任务`
- 工作组织入口：`项目`
- 对象目录入口：`专家 · 技能 · 连接器`、`长程APP`
- 组织知识与治理入口：`知识库`、`后台管理`、`我的`
### 7.1.1 为什么必须这样写全
如果只写：
- 专家
- 技能
- 长程APP
会遗漏三件事：
1. `项目` 其实是统一任务系统的重要容器，不是普通页面
2. `知识库` 是组织级默认内建 App，也是 Expert 和 App 的共用知识底座，不是边角内容
3. `后台管理 / 我的` 分别承担治理与个人视角，不应被误解为附属页
### 7.1.2 当前专题主导航的收敛原则
凡是已经长成“非对话式、强结构、强状态”的专题栏目，例如：
- 培训考试
- 审批中心
- 数据分析台
- 流程编排台
在目标架构中都应优先判断为 `app`，最终收敛进：
- `长程APP`
而不是继续无限增长新的专题型一级导航。
唯一应保留一级直达入口的 App，是像 `知识库` 这种**组织级默认必装底座 App**。
## 7.2 进入 App 的动作不是“打开页面”，而是“创建任务”
点击 App 卡片后的标准动作应为：
1. 创建 `task`
2. 创建主 `task_object_instance(app)`
3. 自动挂载右栏 `expert`
4. 进入 `app runtime`
## 7.3 App 运行界面不再强制对话居中
App 主界面应由业务形态决定，例如：
- 培训考试：课程目录、题卡、成绩面板
- 审批：表单、节点、操作栏
- 数据分析：图表、筛选器、表格
- 流程编排：画布、节点、日志
AI 对话框在 App 中退居右栏能力区。
---
## 8. 样板场景：培训考试 App
## 8.1 对象组合
- 主对象：`app.training_exam`
- 右栏对象：`expert.learning_coach`
- 调用技能：`skill.generate_study_plan`
- 调用技能：`skill.auto_grade_exam`
## 8.2 任务阶段
建议阶段至少包括：
1. 待建档
2. 培训中
3. 练习中
4. 待模拟考
5. 模拟考完成
6. 待正式考试
7. 正式考试中
8. 待复盘
9. 待补训
10. 已结业
## 8.3 交互形态
- 培训中：课程目录 + 内容区 + 右栏 AI 教练
- 练习中：题目区 + 即时讲解
- 正式考试中：题卡 + 倒计时 + 受控作答区
- 复盘中：错题分析 + 补训计划 + 证书面板
这个样板说明：
> **同一个任务实例中，对话、结构化界面、技能执行、产物沉淀可以长期共存。**
---
## 9. 迁移指导
## 9.1 术语迁移
对外：
- 专家
- 技能
- 长程APP
一级导航目标态：
- 新建任务
- 项目
- 专家 · 技能 · 连接器
- 长程APP
- 知识库
- 后台管理
- 我的
对内：
- `expert`
- `skill`
- `app`
- `action`
- `connector`
- `policy`
## 9.2 后端迁移重点
1. 从“任务 = 对话”迁移到“任务 = 工作实例”
2. 新增 `app` 对象定义与版本机制
3. 新增 `task_object_instance`
4. 新增 `app_state / app_event / app_artifact`
5. 把消息表从主状态中心降级为对话轨迹层
## 9.3 前端迁移重点
1. 把一级导航整理为“新建任务 / 项目 / 专家 · 技能 · 连接器 / 长程APP / 知识库 / 后台管理 / 我的”
2. 新增“长程APP”并以对象定义驱动 App 卡片列表与详情页
3. 将现有专题型一级导航逐步收敛为 `app`，避免继续平铺新的业务主栏目；`知识库` 作为默认必装底座 App 保留一级直达入口
4. 统一任务列表兼容 `conversation_task` 和 `app_task`
5. App Runtime 布局支持“主业务区 + 右栏 AI”
---
## 10. 最终定义
这次架构升级后的平台可以正式定义为：
> **一个以统一任务系统为核心、同时承载 Expert / Skill / App 三类一级对象的工业智能体操作平台。**
其中：
- `Expert` 负责协作
- `Skill` 负责能力
- `App` 负责长程任务运行壳
- `Task` 负责统一承载工作实例
这意味着平台已经不再是单一对话驱动系统，而是：
> **对话工作台与长程APP并存，但统一运行、统一治理、统一沉淀。**
docs/01_System_Overall/SY23_Specialist_Rule_File_And_Skill_Binding_Plan.md
+381
View File
@@ -0,0 +1,381 @@
# SY23 — 专员「岗位说明书 + 技能绑定」改造方案
> 状态：实施建议稿
> 日期：2026-09-17
> 关联文档：`SY18_Specialist_Minimal_Definition_Model.md`、`SY20_Role_Card_And_Lightweight_Ontology_Architecture.md`、`SY21_Unified_Role_Skill_Action_Architecture.md`、`SY22_Role_Skill_App_Unified_Task_Architecture.md`
> 外部参照：AionUi / AionCore 内置助手与技能（已下载至 `codebase/AionCore-assets/`）
---
## 0. 一句话诊断
**我们现在的 10 个专员，在运行时是同一个助手换了 10 个名字。**
工作台主对话走 `POST /api/assistant/chat`（前端 `api/assistant.js` → `chatWithAssistant`），而这个接口：
| 环节 | 现状 | 位置 |
|------|------|------|
| 前端发送的字段 | 只有 `message` / `mode` / `ai_route_id` | `views/workbench/SmartAssistantPage.vue:471` |
| 后端请求体 | **已有** `task_id` / `context` 字段，但前端一个都没发 | `internal/api/smart_assistant.go:17-25` |
| 后端 System Prompt | **两条写死的字符串**，与专员无关 | `internal/api/smart_assistant.go:136-140` |
| 后端是否查过 specialist 表 | **从未** | `callAssistantAI` 全文 26 行 |
| 「专家模式」任务拆解 | **三条写死的假步骤**（准备/执行/完成阶段） | `internal/api/smart_assistant.go:161-174` |
| 知识检索 | 这条链路完全不检索知识库 | 对比 `worker_task.go:707` |
也就是说：**不管用户选了「合同审查专员」还是「物流履约专员」，后端收到的请求完全一样，产出的 System Prompt 完全一样。** 专员是在前端画出来的差异，不是后端跑出来的差异。
这与 SY21 §3.5.2 已经拍板的关系式直接冲突：
> 专家承接用户，skill 组织任务，action 执行动作。
我们目前**只做了「专家承接用户」（前端 UI），缺了「专家暴露 skill」和「skill 编排 action」两条边**。
---
## 1. AionUi 做对了什么（三件事）
AionCore 的 `builtin-assistants/assistants.json` 里，每个助手就三个关键字段：
```json
{
"id": "word-creator",
"rule_file": "word-creator.{locale}.md",
"enabled_skills": ["officecli-docx"]
}
```
拆开看：
**① 每个助手有一份「岗位说明书」（rule file）**
- 就是这个助手的 System Prompt 主体，会话创建时注入
- 简体中文版共 21 份，长度分布很说明问题：
- 办公类 9 份在 **433–650 字**（如 `word-creator.zh-CN.md` 517 字）
- 编排类 9 份在 **2470–9007 字**（如 `cowork.zh-CN.md` 6705 字）
- **短的那批不是偷懒，是分工**：它们把「怎么做」全部委托给技能，说明书本身只负责「我是谁 / 什么时候说什么 / 什么时候用哪个技能」
`word-creator.zh-CN.md` 全文的结构（517 字）：
```markdown
# Word 文档助手
你是 **Word Creator** —— 一个专门使用 officecli 创建、编辑和分析专业 Word 文档的 AI 助手。
## 当用户打招呼或询问你能做什么时
简短介绍自己：[一段自我介绍的原文]
然后等待用户请求。
## 当用户想要创建或编辑文档时
严格按照 `officecli-docx` 技能执行。……不要偏离或简化技能中的指令。
在开始工作前，主动提醒用户一次：[一段提醒原文]
在生成完成后，明确告诉用户：[一段收尾原文]
```
**② 每个助手声明它能用哪些技能（`enabled_skills`）**
- 技能以目录形式链接进工作区，底层 CLI 通过 `native_skills_dirs` 发现
- 21 个助手里 13 个只绑 1 个技能，`cowork` 绑 5 个，`game-3d` / `ui-ux-pro-max` / `planning-with-files` / `human-3-coach` 绑 0 个
- **绑 0 个技能但有 4000+ 字说明书的，恰恰是最像「专员」的那几个**（纯靠说明书驱动行为，不靠工具）
**③ 说明书负责「调度」，技能负责「执行」**
- 长说明书（`cowork` 6705 字）的核心内容就是「什么场景下按哪个技能走」——这正是 SY20 说的「专员 = 可调用工具的角色」
- `cowork` 是 21 个助手里唯一的多技能编排样板，**也是我们最该先抄的一份**
### 结论
SY18 + SY20 + AionUi 三边指向同一件缺失的事：
```
SY18 说：专员有「动作」 ─┐
SY20 说：专员 = 可调用工具的角色 ─┼─→ 专员和技能之间没有绑定边
SY21 说：专家对象暴露 skill ─┤ 专员没有一份进 prompt 的说明书
AionUi 说：rule_file + enabled_skills ─┘
```
**我们已经有的（没用的）**：`specialist.role_card_json` 字段建了、值也写了，但从未进过任何 prompt。
**我们缺的**：不是字段，是**把字段送进 prompt 的那条线**，和**专员↔技能的绑定边**。
---
## 2. 改造方案
三步，从「运行时能看出差异」倒推，不铺新架构。
### 步骤 1：给专员两样东西（数据层，改动最小）
在 `internal/model/specialist.go` 加两个字段：
```go
// RuleFileMarkdown 岗位说明书正文（Markdown 全文）。
// 会话创建时注入 System Prompt，决定这个专员怎么说话、怎么推进、什么时候调用哪个技能。
RuleFileMarkdown string `gorm:"type:text" json:"rule_file_markdown"`
// AllowedSkills 绑定技能 key 列表，JSON 数组，顺序即优先级（首个为主技能）。
// 元素取值对齐前端 availableSkills[].key，见 §2.4 校验清单。
AllowedSkills string `gorm:"type:text" json:"allowed_skills"`
```
**为什么是两个字段而不是两张表**
| 选择 | 理由 |
|------|------|
| 说明书用单字段 | AionUi 也是「一个助手一份 rule file」，不引入版本表 |
| 技能绑定用 JSON 数组 | SY22 §6.1 已把 `allowed_skills` 定为对象 `manifest` 的字段。现在用同名字段落地，**将来迁到 `object_definition` 时只是把列搬进 manifest，没有语义返工** |
| 不新建 `specialist_skill` 表 | 10 个专员 × 3–5 个技能 ≈ 40 行。表能提供的索引和 FK，在这里都不成立——15 个前端技能在后端根本没有行，FK 建不起来。数组顺序天然表达优先级，无需 `sort_order` 列 |
> 升级路径（不在本轮）：若将来技能绑定要挂**属性**（按技能配参数默认值、按技能配权限档位），再拆成关联表；那时 `allowed_skills` 里的元素从字符串升级为对象，字段名不变。
**迁移**：GORM `AutoMigrate` 会自动 `ADD COLUMN`，**不需要**手写迁移函数。
（`internal/store/db.go:83` 的 `migrateObjectEntryRouteColumns` 是为 `DROP COLUMN` 写的——SQLite 的 AutoMigrate 删不掉列，加列不在此列。）
**播种**：在 `internal/store/seed.go` 的 `seedSpecialists()` 之后加 `seedSpecialistRules()`，遵守现有「存在则只补空字段」约定——**说明书非空就不覆盖**，保护人工编辑。
### 步骤 2：让对话带上专员（打通链路）
这是**当前最大的断点**，也是投入产出比最高的一处。改动共 4 个文件、约 30 行。
**前端（3 处）**
| 文件 | 改动 |
|------|------|
| `frontend/src/api/assistant.js` | `chatWithAssistant(data)` 已透传整个 data，无需改 |
| `frontend/src/store/workerRuntime.js` | 已有 `currentSpecialistKey` computed（185-192 行），直接用 |
| `frontend/src/views/workbench/SmartAssistantPage.vue:471` | 请求体补上 `task_id` 与 `specialist_key` |
```js
const res = await chatWithAssistant({
message: text,
mode: mode.value,
ai_route_id: selectedAiChatRouteId.value,
task_id: currentTaskId.value || 0,
specialist_key: workerRuntime.currentSpecialistKey || '',
})
```
> 两个都发是刻意的：**有任务时以 `task_id` 为准**（服务端从 `worker_task.specialist_key` 反查，不信任客户端）；**任务尚未创建时**（刚进 `/home` 还没发第一句话）前端手上只有 `pendingSpecialistKey`，此时用 `specialist_key` 兜底。
**后端（1 处）**
`internal/api/smart_assistant.go` 的 `callAssistantAI` 增加专员解析：
```go
// 解析当前专员：优先按 task_id 反查（服务端权威），其次用请求里的 specialist_key
func resolveSpecialist(userID uint, req SmartAssistantRequest) *model.Specialist {
if req.TaskID > 0 {
var task model.WorkerTask
if err := store.DB.Where("id = ? AND user_id = ?", req.TaskID, userID).
First(&task).Error; err == nil && task.SpecialistKey != "" {
var s model.Specialist
if err := store.DB.Where("key = ?", task.SpecialistKey).First(&s).Error; err == nil {
return &s
}
}
}
if req.SpecialistKey != "" {
var s model.Specialist
if err := store.DB.Where("key = ?", req.SpecialistKey).First(&s).Error; err == nil {
return &s
}
}
return nil
}
```
> 现成的反查先例：`internal/api/worker_task.go:364` 就是同一套 `store.DB.Where("key = ?", task.SpecialistKey).First(&specialist)`。
`SmartAssistantRequest` 需补一个字段（`TaskID` 已存在，只差 `SpecialistKey`）：
```go
SpecialistKey string `json:"specialist_key"`
```
### 步骤 3：让说明书进 prompt（注入）
改造 `callAssistantAI` 的 System Prompt 拼装，从「二选一写死」变成「通用底座 + 专员说明书」：
```go
func buildAssistantSystemPrompt(userID uint, req SmartAssistantRequest, enableThinking bool) string {
base := "你是一位专业的AI通用助手，回答简洁直接，不展开思考过程，快速响应用户问题。"
if enableThinking {
base = "你是一位专家级AI数字员工，使用 thinking 模式。……"
}
s := resolveSpecialist(userID, req)
if s == nil {
return base // 未挂专员 → 通用助手兜底，行为与今天一致
}
var b strings.Builder
b.WriteString(base)
b.WriteString("\n\n【当前专员】")
b.WriteString(s.Label)
if skills := parseAllowedSkills(s.AllowedSkills); len(skills) > 0 {
b.WriteString("\n【可用技能】")
b.WriteString(strings.Join(skills, "、"))
}
// 说明书是主体，放最后，避免被前面的短句稀释
if strings.TrimSpace(s.RuleFileMarkdown) != "" {
b.WriteString("\n\n")
b.WriteString(s.RuleFileMarkdown)
}
return b.String()
}
```
**同时接上第二条链路**：`internal/api/worker_task.go:708` 已经在拼 System Prompt 且**手上就有 specialist 对象**，把说明书一起拼进去即可——这条链路是免费的，因为它本来就认识专员。
```go
systemPrompt := buildSystemPrompt(contextJSON, knowledge) +
specialistPromptSection(specialist) + // ← 新增
"\n\n当前任务：" + buildWorkerAITaskPrompt(task, specialist, req)
```
> `specialistPromptSection(s)` 抽成一个共用小函数，`smart_assistant.go` 和 `worker_task.go` 都调它，避免两处 prompt 拼法各写一遍。
### §2.4 技能 key 校验清单
绑定的是裸字符串，所以需要一个校验来源。**新增单个 Go 常量文件**即可（22 条，从 `frontend/src/config/workbench.js` 的 `availableSkills` 一次性抄出）：
```go
// internal/model/skill_keys.go
// 前端 availableSkills 的 key 全集。绑定校验以此为准。
// 注意：这里只列 key，不含技能实现——技能实现仍在前端。
var ValidSkillKeys = map[string]bool{
"smart-assistant": true, "document-translate": true, "copy-proofreading": true,
"audio-transcribe": true, "batch-extract": true, "contract-review": true,
"report-generation": true, "ppt-generation": true, "mind-map": true,
"longform-writing": true, "text-toolkit": true, "ocr-understanding": true,
"meeting-minutes": true, "project-planning": true, "email-drafting": true,
"table-cleanup": true, "proposal-summary": true, "progress-report": true,
"contract-brief": true, "interview-summary": true, "policy-rewrite": true,
"survey-summary": true,
}
```
写入时校验，非法 key 直接 400 —— 这样至少在录入侧挡住拼写错误。
> **命名冲突提醒**：`contract-review` 和 `report-generation` **既是专员 key 又是技能 key**。
> 这是对的、也是刻意的（合同审查专员绑定合同审查技能），但读日志和调代码时极易混淆。建议**日志与报错文案一律写成 `专员:contract-review` / `技能:contract-review`** 带类型前缀。
---
## 3. 21 份规则文件，先改写哪几份
全部 21 份已下载在 `codebase/AionCore-assets/crates/aionui-app/assets/builtin-assistants/rules/`。
### 第一梯队：直接改写就能用（建议本轮做）
| # | AionUi 来源 | 字数 | 对应我们的专员 | 为什么先做 |
|---|-------------|------|----------------|------------|
| 1 | `cowork` + 5 技能 | 6705 | `general-assistant`、`process-coordination` | **21 份里唯一的多技能编排样板**。它的说明书通篇在写「什么场景按哪个技能走」——这正是 SY20「专员 = 可调用工具的角色」要的东西。我们的「通用助手 / 流程协调」现在完全是空壳 |
| 2 | `word-creator` + `officecli-docx` | 517 | `report-generation`、`solution-proposal` | 说明书只有 517 字，是**最简模板**，改造成本最低；`officecli-docx` 是文档产出的通用底座，一份技能喂两个专员 |
| 3 | `morph-ppt` + `officecli-pptx` | 554 | `training-delivery` | 培训交付要出课件，morph-ppt 专做「文档转 PPT」，另有 3D 变体。我们「培训交付」目前零后端实现，接上就是真能力 |
### 第二梯队：要改业务语义（本轮之后）
| # | AionUi 来源 | 字数 | 对应我们的专员 | 改造要点 |
|---|-------------|------|----------------|----------|
| 4 | `social-job-publisher` | 2470 | `hr-email-sorter`、`resume-processor` | 招聘发布场景接近，但从「发帖到社媒」改成「读邮箱 → 写简历表」，需按 SY18 的信源/结果模型重写 |
| 5 | `planning-with-files` | 5500 | `process-coordination` | 纯说明书（绑 0 技能），讲「用文件做长期规划」，接近流程协调 |
| 6 | `beautiful-mermaid` | 433 | `report-generation` | 图表产出，可作报告生成的第二个技能 |
| 7 | `excel-creator` + `officecli-xlsx` | 562 | `report-generation` | 表格产出 |
| 8 | `dashboard-creator`、`financial-model-creator`、`pitch-deck-creator`、`academic-paper` | 567–614 | `solution-proposal` | 方案建议的几种形态，按客户行业挑 |
### 不要碰
| 来源 | 原因 |
|------|------|
| **`builtin-skills/pdf/`** | **© 2025 Anthropic, PBC，附加条款明文禁止创建衍生作品、禁止在服务外保留副本、禁止再分发。必须删除，不得移植进产品。** |
| `openclaw-setup`、`aionui-assistant`、`aionui-*` 技能 | AionUi 自身的安装运维助手，与业务无关 |
| `moltbook` | 面向其自有平台的发布助手 |
| `game-3d`、`story-roleplay`、`human-3-coach`、`ui-ux-pro-max` | 游戏 / 角色扮演 / 个人成长 / 设计工具，与企业办公无关 |
| `weixin-file-send` | 是「把文件发到微信」的客户端脚本，依赖其本地 Electron 环境，不可移植（公众号专员要的是发文，不是发文件） |
### 前置依赖：OfficeCLI 未下载
7 个 `officecli-*` 技能全部依赖 **OfficeCLI**（AionUi 用它免装 Office 操作 docx/xlsx/pptx）。**我们目前没有这份资产**，第一梯队第 2、3 项开工前必须先搞定它，否则说明书改完也没东西可调。
---
## 4. 前端要动的地方（最小集）
**前提原则（沿用已拍板方向）：专员是任务的字段，不是页面。** 本方案不新增任何专员页面。
### 必改
| 文件 | 改动 |
|------|------|
| `views/workbench/SmartAssistantPage.vue:471` | 请求体补 `task_id` / `specialist_key`（步骤 2） |
| `views/workbench/CapabilityCatalogDetailPage.vue:257` | 专员详情页 `extraSections: []` 是空的，**正好是挂「绑定技能」「岗位说明书」两个 section 的位置**（技能详情页 160-183 行有现成写法可抄） |
| `store/workerRuntime.js:425-441` | `attachSpecialistToCurrentTask` 目前**强制**把技能清成 `DEFAULT_SKILL_KEY`（438 行）。这正是「选了专员反而更空」的根因——应改为写入该专员的**主技能**（`allowed_skills[0]`） |
### 建议改
| 文件 | 改动 |
|------|------|
| `views/workbench/StudioPage.vue:1505-1545`、`MarketPage.vue:660-740` | 管理员/市场的专员表单，是录入说明书与绑定技能的两个编辑入口（`api/specialist.go` 与表单 payload 需同步透传新字段） |
| `components/chat/SpecialistChip.vue:41-54` | 胶囊提示补「已绑定 N 个技能」 |
| `views/workbench/CapabilityCatalogPage.vue:385-404` | 专员卡片增加技能徽章 |
### 明确不改
- `config/workbench.js` 的 `availableSkills`（22 条）—— 技能仍归前端，本方案不把技能搬到后端
- `config/skillSettings.js` 的既有 7 条技能定义
- `skills/registry/*` 技能实现本体
> **双份真相问题记录在案**：前端 22 个技能 vs 后端 `skill_definition` 7 行，今天无同步机制。本方案用 §2.4 的 `ValidSkillKeys` 常量做**单向校验**兜底，不解决同步问题。彻底解决要等 SY22 的 `object_definition` 落地，**不在本轮**。
---
## 5. 顺带发现的线上缺陷（独立于本方案，建议立即修）
`internal/api/batch_extract.go:62` 与 `internal/api/contract_review.go:359` 调用：
```go
ai.GenerateWithFallback(nil, messages)
```
而 `internal/ai/llm.go:302` 的实现第一行就是：
```go
fallbacks, err := config.GetFallbackRoutes(primary.RouteID) // primary == nil → 空指针
```
**验证结论**：
- `internal/api/router.go:146` / `:152` 确认两条路由都是活路径（`POST /api/contract/review`、`POST /api/batch/extract`，均挂 `middleware.Auth`）
- `cmd/server/main.go:47` 用的是 `gin.Default()`，自带 Recovery —— 所以表现为 **HTTP 500**，不会打挂进程，但**这两个功能 100% 不可用**
- 前端 `api/contract.js:3`、`api/batch.js:3` 确实在调这两个接口
**修复**：两处改为传入真实路由（`config.GetRoute(...)`，可参照 `smart_assistant.go:146`），或在 `GenerateWithFallback` 入口对 `primary == nil` 显式返回错误而非 panic。**建议两者都做**——前者修功能，后者防复发。
---
## 6. 不建议现在做的事
| 事项 | 原因 |
|------|------|
| 迁到统一的 `object_definition` 根表 | SY22 §6.1 是终态，但当前前端专员/技能展示**大量读本地硬编码**（`businessApps` 10 个、`availableSkills` 22 个）。先迁表等于先付迁移成本、后拿收益。本方案的字段命名已与 SY22 对齐，将来搬迁无返工 |
| 把 22 个前端技能搬到后端 | 无运行时收益，且会立刻暴露「技能没有真实实现」的更大缺口 |
| 给专员做独立页面 | 违背已拍板方向（专员是任务的字段）。AionUi 同样把助手配置放在设置里，不放主界面 |
| 移植 `builtin-skills/pdf/` | 许可证禁止（见 §3） |
| 补 `specialist_skill` 关联表 | 见 §2 步骤 1 的取舍说明 |
---
## 7. 工作量与推进顺序
| 阶段 | 内容 | 估时 |
|------|------|------|
| **P0** | 修 §5 的空指针缺陷 | 0.5 天 |
| **P1** | 步骤 1 数据层（2 字段 + 播种 + `ValidSkillKeys` 校验） | 0.5 天 |
| **P2** | 步骤 2 打通链路（前端 2 处 + 后端 `resolveSpecialist`） | 0.5 天 |
| **P3** | 步骤 3 注入 prompt（`buildAssistantSystemPrompt` + `worker_task.go:708` 同步） | 0.5 天 |
| **P4** | 前端最小集（详情页两个 section + `attachSpecialistToCurrentTask` 改主技能） | 1 天 |
| **P5** | 第一梯队 3 份说明书改写（需先拿到 OfficeCLI） | 每份 0.5–1 天 |
**P1–P3 合计约 1.5 天，做完即可看到「同一个助手在不同专员下说话方式不同」**——这是整个方案能否立住的最小验证点。**建议 P1–P3 做完先停下来验证一次，再决定要不要投 P5。**
### 验收标准（沿用 SY18 §8）
> 如果一个专员无法用三行（信源 / 动作 / 结果）说清、且权限说不出「能读什么 / 能写什么 / 谁能用」，说明设计过重了。
再加一条本方案的：
> **选中两个不同的专员、问同一句话，后端发出的 System Prompt 必须不同。** 只要这一条不成立，专员就还只是装饰。
docs/01_System_Overall/SY24_Platform_Architecture_Rethink.md
+941
View File
@@ -0,0 +1,941 @@
# 数字员工平台整体架构重思考
> 落盘日期：2026-09-16
> 状态：架构重思考稿，作为后续产品与数据结构重构的总纲
> 关联文档：
> - `../02_Architecture/AR05_Workbench_Architecture_Contract.md`
> - `../02_Architecture/AR06_Skill_Packaging_Specification.md`
> - `../02_Architecture/AR08_Role_Interaction_Design.md`
> 2026-09-16 架构同步说明：
> 本文档保留 Workbench 收敛和对象化迁移结论，但总命名以
> `docs/01_System_Overall/SY21_Unified_Role_Skill_Action_Architecture.md` 为准。
> 当前统一口径为：
> - 对外：`角色 / 技能 / 连接器`
> - 对内：`role / skill / action / connector / policy`
> - `tool` 在本稿中主要代表历史命名和过渡字段，不再作为未来正式概念
> - 欢迎语、starter prompts、对象开场方式，应由角色对象属性驱动，而不是页面硬编码
---
## 1. 最终判断
现在这个系统最核心的问题，不是页面太多，也不是导航太乱，而是：
**产品架构、前端架构、后端数据结构三层没有使用同一个对象模型。**
当前系统里同时混着以下几种模型：
1. `任务挂专员`
2. `工具等于页面`
3. `项目保存一组 skill_keys / specialist_keys`
4. `运行记录只知道 specialist_key，不知道真正执行的是谁`
这四套模型不能长期并存。
所以新的总架构必须统一成一句话：
`一个 Workbench + 一个任务会话 + 多个可挂载对象 + 一条可追踪执行链`
---
## 2. 产品架构重定义
平台以后不是“很多能力页面”，而是一个真正的数字员工平台，分成两大面：
### 2.1 执行面
执行面只保留一个：
- `Workbench`
它承载：
- 当前任务
- 当前对象
- 消息流
- 工作流
- 产物
- 附件
- 启动对象 / 切换对象 / 关闭对象
### 2.2 管理面
管理面负责：
- 目录浏览
- 配置
- 安装
- 权限
- 连接器
- 运营
- 观测
它不承担任务执行。
一句话：
- `Workbench` 负责使用
- `Catalog / Studio / Console` 负责管理
---
## 3. 统一对象模型
未来系统里所有“可被用户启动、配置、关闭、调用”的东西，都统一叫：
`对象`
对象分三类：
### 3.1 默认助手
定义：
- 默认兜底对象
- 没选专员、没选技术员时的默认入口
本质：
- 一种特殊的编排对象
### 3.2 数字专员
定义：
- 负责任务拆解、编排、协调、汇总的对象
本质：
- 编排型对象
### 3.3 数字技术员
定义：
- 负责某一个能力动作的对象
本质：
- 执行型对象
### 3.4 关键结论
工具不再是页面，也不再是一个特殊技术概念。
工具只是：
`数字技术员的产品展示名称`
所以未来建模必须统一为：
- 对象定义
- 对象安装
- 对象实例
- 对象运行
而不是：
- 专员一套表
- 工具一套路由
- 页面里再塞一套局部状态
---
## 4. 新的领域分层
系统应该拆成 4 层：
### 4.1 定义层
定义“这个对象是谁”。
例如：
- 文档翻译技术员
- 合同审查专员
- 通用助手
这一层存：
- 身份
- 来源
- 版本
- 设置 schema
- 能力 schema
- 展示配置
### 4.2 安装层
定义“这个对象在当前租户 / 工作区里是否可用”。
这一层存：
- 是否启用
- 是否安装
- 版本锁定
- 权限范围
- 默认配置
### 4.3 实例层
定义“这条任务当前挂了谁”。
这一层存：
- 当前任务里挂载了哪些对象
- 当前焦点是谁
- 各对象的本次任务配置快照
- 对象是否打开 / 关闭
### 4.4 运行层
定义“这次实际跑了什么”。
这一层存：
- 消息
- 调用链
- 步骤
- 产物
- 日志
- 状态变化
---
## 5. 最重要的结构纠偏
### 5.1 Task 不能只挂一个 specialist_key
当前 `worker_task` 的核心绑定是：
- `specialist_key`
这不够。
因为未来一条任务里可能同时存在：
- 一个主专员
- 多个技术员
- 动态切换的当前焦点对象
但对用户可见的输入区交互，必须坚持一条规则：
- `+` 右边一次只显示一个当前对象
- 当前对象要么是专员，要么是技能，要么是默认助手
- 专员内部调用技能，只进入执行链和右侧面板，不在输入区显性双挂
所以真正的任务结构不应是：
`task -> specialist_key`
而应是：
`task -> mounted objects`
### 5.2 Run 不能只知道 specialist_key
当前 `worker_run` 也只知道：
- `specialist_key`
- `action_key`
这会导致系统分不清：
- 是哪个对象发起的
- 是哪个对象实际执行的
- 是专员步骤，还是技术员步骤
- 是人工确认，还是自动调用
所以运行记录必须升级为：
- 谁发起
- 谁执行
- 父子运行关系
- 对应对象实例
### 5.3 Project 不能只存 skill_keys 与 object_entry_route 语义
当前项目里保存：
- `specialist_keys`
- `skill_keys`
- `connector_keys`
方向是对的，但语义还不够硬。
以后项目应该保存的是：
- 默认对象绑定
- 默认配置快照
- 默认连接器绑定
- 默认知识域
而不是仅仅一串“key 列表”。
### 5.4 消息必须成为一等数据
当前系统最大缺口之一，是消息没有成为正式持久化对象。
没有消息层，Workbench 永远只是半成品，因为：
- 任务无法真正恢复
- 对象切换没有上下文历史
- 运行记录无法和用户意图精确对齐
- 后续审计、回放、总结都不完整
所以必须新增：
- `task_message`
---
## 6. 推荐的核心数据结构
以下是建议采用的目标数据模型。
## 6.1 对象定义表 `object_definition`
作用：
- 统一描述默认助手 / 专员 / 技术员
建议字段：
```ts
type ObjectDefinition = {
id: string
code: string
source: 'eai' | 'custom'
kind: 'assistant' | 'specialist' | 'tool'
key: string
label: string
description: string
version: string
state: 'active' | 'inactive'
icon: string
color: string
capabilitySchema: object
settingsSchema: object[]
workflowSchema: object[]
artifactSchema: object[]
uiSchema: object
createdAt: string
updatedAt: string
}
```
关键说明：
1. `specialist` 和 `tool` 都是对象定义，不再属于两套异构模型
2. EAI 与 custom 由 `source` 区分
3. 旧的 `specialist` 表最终应演进成这一层
## 6.2 对象安装表 `object_installation`
作用：
- 记录某个对象在某个租户 / 工作区 / 组织里是否可用
建议字段：
```ts
type ObjectInstallation = {
id: string
objectDefinitionId: string
tenantId: string
workspaceId: string
state: 'installed' | 'disabled' | 'trial'
pinned: boolean
permissionScope: object
connectorBindings: object[]
knowledgeBindings: object[]
defaultSettings: object
createdAt: string
updatedAt: string
}
```
关键说明：
1. 这层解决“平台有，但当前租户能不能用”
2. 这层负责安装态，而不是任务态
## 6.3 项目表 `project`
作用：
- 作为任务的长期上下文容器
建议字段：
```ts
type Project = {
id: string
code: string
name: string
ownerId: string
instruction: string
templateKey: string
defaultObjectBindings: object[]
defaultConnectorBindings: object[]
defaultKnowledgeBindings: object[]
state: 'active' | 'archived'
pinned: boolean
createdAt: string
updatedAt: string
}
```
关键说明：
1. 项目不是对象目录
2. 项目是任务上下文模板
3. 项目里应该保存默认挂载关系，而不是只保存裸 key 列表
## 6.4 任务会话表 `task_session`
作用：
- 表示用户正在处理的一条真实任务
建议字段：
```ts
type TaskSession = {
id: string
title: string
summary: string
ownerId: string
projectId?: string
state: 'draft' | 'running' | 'waiting' | 'done' | 'archived'
priority: 'P1' | 'P2' | 'P3'
currentObjectInstanceId?: string
defaultSpecialistInstanceId?: string
latestRunId?: string
latestArtifactId?: string
pinned: boolean
dueAt?: string
createdAt: string
updatedAt: string
}
```
关键说明：
1. 任务只记录“当前主会话”
2. 任务不直接存 `tool object_entry_route`
3. 任务不直接把工具建模成页面
## 6.5 任务挂载对象表 `task_object_instance`
作用：
- 这是整个系统最关键的新表
- 记录某条任务当前挂载了哪些对象
建议字段：
```ts
type TaskObjectInstance = {
id: string
taskId: string
objectDefinitionId: string
objectKind: 'assistant' | 'specialist' | 'skill'
role: 'default' | 'primary' | 'secondary'
state: 'mounted' | 'focused' | 'closed'
settingsSnapshot: object
source: 'manual' | 'auto'
mountedAt: string
closedAt?: string
updatedAt: string
}
```
关键说明：
1. 当前专员、当前技能都应该从这里来
2. `currentSkillKey` 只是这张表的前端运行态字段
3. 关闭对象时，不是跳页面，而是把实例 state 改成 `closed`
## 6.6 消息表 `task_message`
作用：
- 持久化消息流
建议字段：
```ts
type TaskMessage = {
id: string
taskId: string
objectInstanceId?: string
role: 'user' | 'assistant' | 'system'
messageType: 'text' | 'tool_call' | 'status' | 'summary'
contentText: string
contentJSON?: object
replyToMessageId?: string
createdAt: string
}
```
关键说明：
1. 每条消息可以挂到某个对象实例上
2. 这样才能知道“这句话是对谁说的”
3. 回放、总结、继续追问都依赖这层
## 6.7 执行表 `object_run`
作用：
- 记录对象实际执行的过程
建议字段：
```ts
type ObjectRun = {
id: string
taskId: string
objectInstanceId: string
initiatedByRunId?: string
initiatedByObjectInstanceId?: string
parentRunId?: string
runType: 'chat' | 'workflow' | 'skill' | 'approval'
actionKey: string
actionTitle: string
state: 'queued' | 'running' | 'waiting' | 'done' | 'failed' | 'cancelled'
inputJSON: object
outputJSON?: object
logsJSON?: object[]
startedAt?: string
finishedAt?: string
createdAt: string
updatedAt: string
}
```
关键说明：
1. 必须显式有 `running / waiting / failed`
2. 当前 `worker_run.status` 默认 `done` 的模型是不够的
3. `parentRunId` 解决专员调用技术员的问题
## 6.8 产物表 `artifact`
作用：
- 统一管理任务产出
建议字段：
```ts
type Artifact = {
id: string
taskId: string
objectInstanceId?: string
createdByRunId?: string
artifactType: string
title: string
state: 'draft' | 'review' | 'approved' | 'published'
contentText?: string
contentJSON?: object
sourceRefsJSON?: object[]
createdAt: string
updatedAt: string
}
```
关键说明：
1. 产物不属于页面
2. 产物属于任务和执行链
3. 右栏展示只是视图，不是数据来源
---
## 7. 前端运行时结构重定义
前端 store 应该从“按页面凑状态”改成“按任务会话管理状态”。
推荐结构：
```ts
type WorkbenchRuntime = {
activeTaskId: string
draftSelection: {
specialistKey?: string
toolKey?: string
mode?: string
}
tasksById: Record<string, TaskSession>
mountedObjectsByTaskId: Record<string, TaskObjectInstance[]>
messagesByTaskId: Record<string, TaskMessage[]>
runsByTaskId: Record<string, ObjectRun[]>
artifactsByTaskId: Record<string, Artifact[]>
focusedObjectInstanceIdByTaskId: Record<string, string>
panelStateByTaskId: Record<string, { activeTab: 'workflow' | 'artifacts' }>
}
```
关键说明：
1. 当前对象应该由 `focusedObjectInstanceId` 决定
2. `currentSkillKey` 和 `currentSpecialistKey` 最终都只是计算值
3. 页面不应该自己猜当前对象是谁
---
## 8. 前端目录结构重定义
建议未来前端结构分成 5 块：
```text
src/
workbench/
pages/
components/
stores/
runtime/
tools/
eai/
custom/
registry/
shared/
specialists/
eai/
custom/
registry/
shared/
connectors/
catalog/
```
关键说明：
1. `workbench/` 只承载执行工作面
2. `tools/` 只放技术员定义与局部组件
3. `specialists/` 只放专员定义与局部组件
4. 不再允许 `views/tools/*.vue` 承担执行职责
---
## 9. 路由模型重定义
未来路由应该只分三类：
### 9.1 执行路由
- `/home`
### 9.2 目录路由
- `/catalog/specialists`
- `/catalog/skills`
- `/catalog/connectors`
### 9.3 配置 / 管理路由
- `/studio`
- `/console`
- `/projects`
强结论：
- `apps/*` 退出执行入口
- `tools/*` 退出执行入口
---
## 10. 对当前表结构的明确评价
### 10.1 当前 `specialist` 表
优点：
- 已经积累了足够多的对象定义字段
问题：
- 同时承载了目录字段、展示字段、流程字段、配置字段
- 仍然以“专员”命名，无法统一承载默认助手和技术员
判断：
- 可以作为 `object_definition` 的迁移来源
- 不建议长期继续维持原表语义
### 10.2 当前 `worker_task` 表
优点：
- 已经有任务的基础壳
问题：
- 核心绑定仍然是 `specialist_key`
- 还没有对象实例层
- 还没有消息层
判断：
- 适合作为 `task_session` 的迁移来源
- 不适合作为最终任务模型
### 10.3 当前 `worker_run` 表
优点：
- 已经有动作记录
问题：
- 缺少对象实例 id
- 缺少父子调用链
- 缺少真实运行状态
判断：
- 适合作为 `object_run` 的迁移来源
- 必须升级
### 10.4 当前 `worker_artifact` 表
优点：
- 基本方向正确
问题：
- 仍然绑定 `specialist_key`
- 没有明确对象实例来源
判断：
- 可以直接演进成新 `artifact` 模型
---
## 11. 最关键的产品决策
下面这些必须作为平台级决策固定下来：
### 11.1 任务中心化
所有运行时行为都围绕任务展开。
### 11.2 对象实例化
对象不是页面，不是 tab，不是配置项。
对象在任务里必须有实例。
### 11.3 消息持久化
没有消息层，就没有真正的 Workbench。
### 11.4 运行链可追踪
专员调技术员，必须可追踪为父子执行链。
### 11.5 管理与使用分离
Catalog / Studio / Console 不参与执行面。
---
## 12. 推荐迁移顺序
### Phase 1：冻结对象模型
确定：
- assistant / specialist / tool 三类对象
- source / code / key / label 规范
### Phase 2：补对象实例层
新增：
- `task_object_instance`
前端先用 runtime 影子模型兼容。
### Phase 3：补消息层
新增：
- `task_message`
让任务真正可恢复。
### Phase 4：升级运行链
把 `worker_run` 升级为带父子关系的 `object_run`。
### Phase 5：收口前端执行页
删除：
- `apps/*` 执行页
- `tools/*` 执行页
### Phase 6：收口定义层
把：
- `specialist`
- `tool config`
逐步统一到对象定义体系。
---
## 13. WorkBuddy 实测确认点
本轮已实际登录并查看 WorkBuddy，以下观察可以作为架构校准依据。
### 13.1 单一执行工作面成立
登录后默认进入的是单一工作台，而不是“先选一个工具页再开始工作”。
可见特征：
- 左侧是一级工作区标签
- 中间是统一输入工作面
- 右侧是固定侧栏
这说明：
- 我们保留唯一 Workbench 的方向是对的
### 13.2 `项目` 是独立管理面，不是执行页
WorkBuddy 的 `项目` 入口跳到单独的项目列表与模板空间。
这个页面的职责是：
- 项目管理
- 项目模板
- 多人协同入口
而不是聊天执行。
这说明：
- 我们把 `项目` 归入管理面是对的
- 项目不是对象目录，也不是工具页
### 13.3 `专家·技能·连接器` 是统一目录中心
WorkBuddy 中这一组入口是统一的目录中心，内部再切：
- 专家
- 技能
- 连接器
它的形态明显是：
- 搜索
- 分类
- 推荐
- 安装 / 连接
而不是执行工作面。
这说明：
- 我们把 `Catalog` 与 `Workbench` 分开是对的
- `专员·工具·连接器` 不应该承担直接执行语义
### 13.4 具体技能点击后是详情 / 安装，不是进入另一套聊天页
在 `技能` 列表中点击某个具体技能后，出现的是技能详情与安装动作，而不是跳进单独的技能聊天页面。
这说明：
- “一个工具一个执行页”的老结构方向不对
- 工具更接近“目录项 + 详情 + 安装 + 后续被调用”
### 13.5 右侧面板是壳层能力，不是某个页面私有能力
无论在新建任务、项目、技能、连接器等区域，右侧面板结构都持续存在。
即使内容为空，壳也还在。
这说明：
- 右栏应该属于 shell / workbench 壳层
- 不应该每个工具页自己维护一份右栏
### 13.6 WorkBuddy 仍然保留了较强的“市场 / 目录 / 工作台”边界
它不是把所有东西都糊成一个平面，而是：
- 工作台负责执行
- 项目负责协同容器
- 专家 / 技能 / 连接器负责目录与安装
这和我们当前重构方向高度一致。
### 13.7 对我们的直接启发
WorkBuddy 实测后，可以进一步确认以下决策不需要再摇摆：
1. 保留唯一执行工作面
2. `项目` 作为管理 / 协同面保留
3. `专家·技能·连接器` 作为目录中心保留
4. 工具不再做独立执行页
5. 右栏属于壳层，而不是页面层
### 13.8 我们不需要照搬的地方
WorkBuddy 当前实现里，仍然保留了较强的目录跳转结构。
我们项目和它的差异是：
- 我们更强调“任务上下文中的对象挂载”
- 我们更强调“启动、配置、关闭对象”
- 我们希望对象实例层更加明确
所以我们不需要简单复刻它的页面结构，而应该吸收它已经验证过的边界：
- 工作台是工作台
- 目录是目录
- 安装是安装
- 执行不是目录页行为
---
## 14. 关于 WorkBuddy 与本项目的关系
基于当前仓库、既有合同以及本轮 WorkBuddy 实测，已经可以确认：
- 第一性原理判断没有走偏
- WorkBuddy 更适合用来校准边界，而不是替代建模
也就是说：
- 我们参考 WorkBuddy
- 但我们的最终模型应该比它更明确地引入“对象实例层”
---
## 15. 最终一句话
这个平台最终不应该再被理解为：
`专员页 + 工具页 + 若干配置页`
而应该被理解为：
`一个数字员工工作台 + 一套对象目录 + 一层对象实例模型 + 一条执行与产物链`
如果后续任何实现仍然要求用户去理解：
- 我现在在哪个工具页
- 我是不是切到了另一个专员页
- 这个页面和那条任务是什么关系
那就说明架构还没有真正完成重构。