docs: 工作台设计稿收入 docs 体系，routes.go 更名 ai_routes.go
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
@@ -0,0 +1,552 @@
|
||||
# 技能文件规范
|
||||
|
||||
> 落盘日期：2026-09-16
|
||||
> 状态：生效中
|
||||
> 作用：定义“每个技能在前端代码中应该以什么文件形式存在”
|
||||
> 关联文档：`AR05_Workbench_Architecture_Contract.md`
|
||||
|
||||
---
|
||||
|
||||
## 1. 结论
|
||||
|
||||
从本规范生效开始：
|
||||
|
||||
**技能不再以独立执行页面的形式存在。**
|
||||
|
||||
每个技能必须被建模为：
|
||||
|
||||
`定义文件 + 执行器文件 + 结果组件 + 可选扩展组件`
|
||||
|
||||
而不是：
|
||||
|
||||
`一个完整的 xxxPage.vue`
|
||||
|
||||
---
|
||||
|
||||
## 2. 标准目录
|
||||
|
||||
所有技能统一存放在：
|
||||
|
||||
`frontend/src/skills/`
|
||||
|
||||
目录结构固定为：
|
||||
|
||||
```text
|
||||
src/skills/
|
||||
registry/
|
||||
eai.ts
|
||||
custom.ts
|
||||
index.ts
|
||||
shared/
|
||||
types.ts
|
||||
schema.ts
|
||||
runtime.ts
|
||||
eai/
|
||||
smart-assistant/
|
||||
index.ts
|
||||
executor.ts
|
||||
ResultCard.vue
|
||||
document-translate/
|
||||
index.ts
|
||||
executor.ts
|
||||
ResultCard.vue
|
||||
copy-proofreading/
|
||||
index.ts
|
||||
executor.ts
|
||||
ResultCard.vue
|
||||
contract-review/
|
||||
index.ts
|
||||
executor.ts
|
||||
ResultCard.vue
|
||||
audio-transcribe/
|
||||
index.ts
|
||||
executor.ts
|
||||
ResultCard.vue
|
||||
batch-extract/
|
||||
index.ts
|
||||
executor.ts
|
||||
ResultCard.vue
|
||||
custom/
|
||||
adapters/
|
||||
normalize.ts
|
||||
executorFactory.ts
|
||||
```
|
||||
|
||||
强约束：
|
||||
|
||||
1. `eai/` 只放 EAI 官方内置技能
|
||||
2. `custom/` 不放每个用户技能的源码页面
|
||||
3. 用户自定义技能的实例数据应存后端，由前端运行时归一化
|
||||
4. 前端 repo 里只允许保留 `custom/adapters/*` 这类运行时适配代码
|
||||
|
||||
---
|
||||
|
||||
## 3. 技能来源必须分开
|
||||
|
||||
从本规范生效开始，技能必须强制区分来源：
|
||||
|
||||
- `source = 'eai'`
|
||||
- `source = 'custom'`
|
||||
|
||||
### 3.1 EAI 技能
|
||||
|
||||
定义：
|
||||
|
||||
- 平台内置
|
||||
- 由 EAI 官方提供
|
||||
- 随代码仓库交付
|
||||
- 放在 `src/skills/eai/`
|
||||
|
||||
### 3.2 用户自定义技能
|
||||
|
||||
定义：
|
||||
|
||||
- 由租户 / 用户 / 管理员创建
|
||||
- 不属于平台内置源码
|
||||
- 应以数据形式存储在后端
|
||||
- 由前端在运行时转换成统一 `SkillDefinition`
|
||||
|
||||
### 3.3 不允许混放
|
||||
|
||||
禁止以下做法：
|
||||
|
||||
1. 把用户技能和 EAI 技能放在同一层目录
|
||||
2. 给用户技能也手工创建一个 `src/skills/eai/*` 目录
|
||||
3. 把用户技能伪装成内置技能编号
|
||||
4. 让前端页面层自己判断“这是官方技能还是用户技能”
|
||||
|
||||
来源判断必须统一由 registry 和 definition 字段承担。
|
||||
|
||||
---
|
||||
|
||||
## 4. 每个工具允许的文件
|
||||
|
||||
每个 EAI 工具目录下只允许这 4 类文件：
|
||||
|
||||
### 4.1 `index.ts`
|
||||
|
||||
这是工具主定义文件，必须存在。
|
||||
|
||||
作用：
|
||||
|
||||
- 定义工具身份
|
||||
- 定义显示名称
|
||||
- 定义设置 schema
|
||||
- 定义开场提示
|
||||
- 绑定执行器
|
||||
- 绑定结果渲染组件
|
||||
|
||||
### 4.2 `executor.ts`
|
||||
|
||||
这是工具执行器，必须存在。
|
||||
|
||||
作用：
|
||||
|
||||
- 组装请求参数
|
||||
- 调用后端接口
|
||||
- 归一化响应结果
|
||||
|
||||
约束：
|
||||
|
||||
- 不允许依赖页面组件
|
||||
- 不允许写 DOM 逻辑
|
||||
- 不允许直接操作路由
|
||||
|
||||
### 4.3 `ResultCard.vue`
|
||||
|
||||
这是工具结果渲染组件，必须存在。
|
||||
|
||||
作用：
|
||||
|
||||
- 渲染该工具的结果卡片
|
||||
- 展示结构化结果
|
||||
- 展示摘要、状态、附加信息
|
||||
|
||||
约束：
|
||||
|
||||
- 这是局部结果组件，不是页面
|
||||
- 不允许包含整个聊天布局
|
||||
- 不允许自己持有输入框
|
||||
|
||||
### 4.4 `SettingsPanel.vue`
|
||||
|
||||
这是可选文件，只在 schema 驱动不够时允许出现。
|
||||
|
||||
作用：
|
||||
|
||||
- 处理复杂设置 UI
|
||||
|
||||
约束：
|
||||
|
||||
- 默认不创建
|
||||
- 只有通用 schema 无法表达时才允许新增
|
||||
|
||||
---
|
||||
|
||||
## 5. 编号与命名规范
|
||||
|
||||
每个工具必须同时拥有以下 4 个身份字段：
|
||||
|
||||
1. `id`
|
||||
2. `code`
|
||||
3. `key`
|
||||
4. `label`
|
||||
|
||||
四者职责不同，禁止混用。
|
||||
|
||||
### 5.1 `id`
|
||||
|
||||
`id` 是机器标识，必须全局唯一，且不可变。
|
||||
|
||||
格式固定为：
|
||||
|
||||
- EAI 技能：`eai.<skill-key>`
|
||||
- 用户技能：`custom.<owner-key>.<skill-key>`
|
||||
|
||||
示例：
|
||||
|
||||
- `eai.document-translate`
|
||||
- `eai.audio-transcribe`
|
||||
- `custom.acme.document-translate-pro`
|
||||
|
||||
规则：
|
||||
|
||||
1. 全小写
|
||||
2. 使用 `.` 做命名空间分隔
|
||||
3. 最后一段必须和 `skill-key` 一致
|
||||
4. 一经创建不得修改
|
||||
|
||||
### 5.2 `code`
|
||||
|
||||
`code` 是展示编号，给人看，用于列表、配置页、运营页、审计页。
|
||||
|
||||
格式固定为：
|
||||
|
||||
- EAI 技能：`EAI-T-001`
|
||||
- 用户技能：`CUS-T-001`
|
||||
|
||||
规则：
|
||||
|
||||
1. `EAI-T-xxx` 只保留给官方内置技能
|
||||
2. `CUS-T-xxx` 只保留给用户自定义技能
|
||||
3. `xxx` 为三位流水号，从 `001` 开始
|
||||
4. 用户技能的 `code` 允许在“当前租户 / 当前工作区”范围内顺序编号
|
||||
5. 全局唯一性由 `id` 保证，不由 `code` 保证
|
||||
|
||||
### 5.3 `key`
|
||||
|
||||
`key` 是前端目录名和查找键，必须使用 kebab-case。
|
||||
|
||||
示例：
|
||||
|
||||
- `document-translate`
|
||||
- `contract-review`
|
||||
- `batch-extract`
|
||||
|
||||
规则：
|
||||
|
||||
1. 只能包含小写字母、数字、中划线
|
||||
2. 不允许空格
|
||||
3. 不允许中文
|
||||
4. 必须与目录名一致
|
||||
|
||||
### 5.4 `label`
|
||||
|
||||
`label` 是用户可见名称，必须是中文产品名。
|
||||
|
||||
示例：
|
||||
|
||||
- `文档翻译`
|
||||
- `合同审查`
|
||||
- `批量提取`
|
||||
|
||||
规则：
|
||||
|
||||
1. 优先使用中文
|
||||
2. 不带技术实现词
|
||||
3. 不在名称里拼接编号
|
||||
4. 不在名称里拼接来源前缀
|
||||
|
||||
错误示例：
|
||||
|
||||
- `EAI-T-001 文档翻译`
|
||||
- `custom_contract_review`
|
||||
- `合同审查工具V2`
|
||||
|
||||
---
|
||||
|
||||
## 6. 每个技能必须导出的定义结构
|
||||
|
||||
每个技能的 `index.ts` 必须默认导出一个标准对象。
|
||||
|
||||
字段固定如下：
|
||||
|
||||
```ts
|
||||
export interface SkillDefinition {
|
||||
id: string
|
||||
code: string
|
||||
source: 'eai' | 'custom'
|
||||
key: string
|
||||
label: string
|
||||
kind: 'skill'
|
||||
icon: string
|
||||
description: string
|
||||
settings: SkillSettingSchema[]
|
||||
starterPrompts: string[]
|
||||
executor: SkillExecutor
|
||||
resultCard: Component
|
||||
}
|
||||
```
|
||||
|
||||
强约束：
|
||||
|
||||
1. `id` 必须全局唯一
|
||||
2. `code` 必须符合来源对应的编号前缀
|
||||
3. `source` 只能是 `eai` 或 `custom`
|
||||
4. `key` 必须与目录名一致
|
||||
5. `kind` 固定为 `'skill'`
|
||||
6. `settings` 必须是 schema 数据，不允许把设置 UI 直接写进定义文件
|
||||
7. `executor` 必须指向当前技能自己的 `executor.ts`
|
||||
8. `resultCard` 必须指向当前技能自己的 `ResultCard.vue`
|
||||
|
||||
---
|
||||
|
||||
## 7. 文件职责边界
|
||||
|
||||
### 7.1 `index.ts` 负责什么
|
||||
|
||||
只负责：
|
||||
|
||||
- 元数据
|
||||
- schema
|
||||
- 组件与执行器装配
|
||||
|
||||
不负责：
|
||||
|
||||
- 发请求
|
||||
- 维护输入状态
|
||||
- 渲染完整聊天界面
|
||||
|
||||
### 7.2 `executor.ts` 负责什么
|
||||
|
||||
只负责：
|
||||
|
||||
- 把任务上下文和设置值转换成请求
|
||||
- 调用后端
|
||||
- 返回标准结果对象
|
||||
|
||||
不负责：
|
||||
|
||||
- 决定页面跳转
|
||||
- 直接操作 store 里的 UI 状态
|
||||
- 渲染文本
|
||||
|
||||
### 7.3 `ResultCard.vue` 负责什么
|
||||
|
||||
只负责：
|
||||
|
||||
- 接收标准结果数据
|
||||
- 渲染结果
|
||||
|
||||
不负责：
|
||||
|
||||
- 调接口
|
||||
- 打开任务
|
||||
- 切换工具
|
||||
|
||||
---
|
||||
|
||||
## 8. 严格禁止的文件形式
|
||||
|
||||
从本规范生效开始，以下文件形式禁止继续新增：
|
||||
|
||||
1. `src/views/tools/*Page.vue` 作为工具执行页
|
||||
2. 每个工具单独复制一份 `ChatLayout`
|
||||
3. 每个工具单独复制一份 `ChatInputBar`
|
||||
4. 每个工具单独维护一份本地 `messages`
|
||||
5. 每个工具单独维护一份本地 `taskItems`
|
||||
6. 每个工具单独维护一份右栏面板
|
||||
7. 每个工具用独立路由页面表达“当前正在使用”
|
||||
|
||||
一句话：
|
||||
|
||||
**技能可以有自己的定义文件和局部组件，但不能再有自己的执行页面。**
|
||||
|
||||
---
|
||||
|
||||
## 9. 统一注册方式
|
||||
|
||||
技能注册必须按来源拆分：
|
||||
|
||||
- `src/skills/registry/eai.ts`
|
||||
- `src/skills/registry/custom.ts`
|
||||
- `src/skills/registry/index.ts`
|
||||
|
||||
注册形式固定为：
|
||||
|
||||
```ts
|
||||
// registry/eai.ts
|
||||
import smartAssistant from '../eai/smart-assistant'
|
||||
import documentTranslate from '../eai/document-translate'
|
||||
|
||||
export const eaiSkillRegistry = [
|
||||
smartAssistant,
|
||||
documentTranslate,
|
||||
]
|
||||
|
||||
// registry/custom.ts
|
||||
export async function loadCustomSkillRegistry() {
|
||||
return fetchCustomSkillsFromBackend()
|
||||
}
|
||||
|
||||
// registry/index.ts
|
||||
export async function loadSkillRegistry() {
|
||||
const customSkills = await loadCustomSkillRegistry()
|
||||
return [...eaiSkillRegistry, ...customSkills]
|
||||
}
|
||||
```
|
||||
|
||||
约束：
|
||||
|
||||
1. EAI 工具只能从 `registry/eai.ts` 注册
|
||||
2. 用户工具只能从 `registry/custom.ts` 装载
|
||||
3. `registry/index.ts` 只做合并，不写业务逻辑
|
||||
4. 页面层不允许自己 import 某个工具目录
|
||||
5. 工作台只能通过统一 registry 查工具
|
||||
6. 页面层不允许自己判断来源并做分支
|
||||
7. 工具排序优先使用 `code` 和显式排序字段，不允许靠文件名碰运气
|
||||
|
||||
---
|
||||
|
||||
## 10. 工作台与工具的关系
|
||||
|
||||
Workbench 是唯一执行面。
|
||||
|
||||
因此：
|
||||
|
||||
- 输入框属于 Workbench
|
||||
- 当前对象 chip 属于 Workbench
|
||||
- 设置条属于 Workbench
|
||||
- 工作流 / 产物右栏属于 Workbench
|
||||
- 任务列表属于 Workbench
|
||||
|
||||
工具只提供：
|
||||
|
||||
- 自己是谁
|
||||
- 自己能做什么
|
||||
- 自己有哪些设置
|
||||
- 自己如何执行
|
||||
- 自己如何渲染结果
|
||||
|
||||
---
|
||||
|
||||
## 11. 文件名规范
|
||||
|
||||
### 11.1 工具目录名
|
||||
|
||||
必须使用 kebab-case：
|
||||
|
||||
- `document-translate`
|
||||
- `audio-transcribe`
|
||||
- `batch-extract`
|
||||
|
||||
### 11.2 文件名
|
||||
|
||||
固定如下：
|
||||
|
||||
- `index.ts`
|
||||
- `executor.ts`
|
||||
- `ResultCard.vue`
|
||||
- `SettingsPanel.vue`
|
||||
|
||||
禁止：
|
||||
|
||||
- `DocumentTranslatePage.vue`
|
||||
- `AudioToolPage.vue`
|
||||
- `TranslateWorkbench.vue`
|
||||
|
||||
### 11.3 组件名
|
||||
|
||||
工具局部组件必须使用 PascalCase：
|
||||
|
||||
- `ResultCard.vue`
|
||||
- `SettingsPanel.vue`
|
||||
- `ArtifactPreview.vue`
|
||||
|
||||
### 11.4 目录与 key 的关系
|
||||
|
||||
工具目录名必须与 `key` 一致：
|
||||
|
||||
- 目录：`document-translate`
|
||||
- key：`document-translate`
|
||||
|
||||
不允许目录名和 key 各写各的。
|
||||
|
||||
---
|
||||
|
||||
## 12. 迁移结果
|
||||
|
||||
`src/views/tools/*.vue` 旧执行页已经完成退出，当前状态如下：
|
||||
|
||||
### 已完成
|
||||
|
||||
- 旧技能执行路由已删除
|
||||
- `src/views/tools/*.vue` 中的执行页源码已删除
|
||||
- 技能配置与执行逻辑已开始收敛到 `src/skills/*`
|
||||
- `/home` 已成为唯一工作台执行入口
|
||||
|
||||
### 仍需继续推进
|
||||
|
||||
虽然旧页面已经删除，但下面几类资产还要继续补齐：
|
||||
|
||||
- 更完整的 `executor` 接线
|
||||
- 更统一的 `ResultCard` / `SettingsPanel` 规范
|
||||
- 用户自定义技能的后端配置接入
|
||||
- 对象实例化后的运行记录与产物呈现
|
||||
|
||||
---
|
||||
|
||||
## 13. 特殊情况处理
|
||||
|
||||
### 13.1 设置特别复杂的技能
|
||||
|
||||
如果某个技能的设置无法由通用 schema 表达，允许新增：
|
||||
|
||||
- `SettingsPanel.vue`
|
||||
|
||||
但仍然禁止：
|
||||
|
||||
- 为此恢复一个完整技能页
|
||||
|
||||
### 13.2 结果展示特别复杂的技能
|
||||
|
||||
如果 `ResultCard.vue` 不够，可以继续拆分局部组件，例如：
|
||||
|
||||
- `ResultSummary.vue`
|
||||
- `ArtifactPreview.vue`
|
||||
|
||||
但这些文件仍然必须放在该技能目录下，且都属于局部组件，不是页面。
|
||||
|
||||
---
|
||||
|
||||
## 14. 最终硬规范
|
||||
|
||||
从现在开始，前端对“技能”的唯一合法表达方式是：
|
||||
|
||||
EAI 技能：
|
||||
|
||||
`src/skills/eai/<skill-key>/index.ts`
|
||||
|
||||
用户技能：
|
||||
|
||||
不以源码页面形式存在，统一由后端配置记录 + `src/skills/custom/adapters/*` 运行时适配。
|
||||
|
||||
这是技能的主入口。
|
||||
|
||||
配套合法文件只有：
|
||||
|
||||
- `executor.ts`
|
||||
- `ResultCard.vue`
|
||||
- `SettingsPanel.vue`（可选）
|
||||
|
||||
除此之外，不再接受任何“每个工具一个执行页”的实现方式，也不接受把用户工具和 EAI 工具混放在同一来源目录里。
|
||||
Reference in New Issue
Block a user