# 技能文件规范

> 落盘日期：2026-09-16
> 状态：生效中
> 作用：定义“每个技能在前端代码中应该以什么文件形式存在”
> 关联文档：`AR05_工作台架构约定.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 工具混放在同一来源目录里。