# 技能管理（Skill）需求

> 归属系统：对话交互式 AI 系统  
> 版本：v1.0  
> 日期：2026-03-15  

---

## 1. 概述

技能（Skill）是系统内对"可复用的 AI 行为指令"的统一抽象。一个技能本质上是一段 **Markdown 格式的结构化提示文本**，用于在对话中注入特定领域的专业知识、行为规范或工具使用指引。

**核心定位**：让普通用户也能通过编写 Markdown 文档来"教会" AI 做特定事情，无需开发代码。

### 主流平台对比

| 平台/工具 | 技能概念 | 描述方式 | 组合 / 引用 | 技能生态 |
|-----------|---------|---------|------------|---------|
| **OpenAI GPTs** | "Instructions" + Actions | 自然语言 System Prompt + OpenAPI Schema | 不可引用其他 GPT | GPT Store，社区发布与搜索 |
| **Coze（扣子）** | 插件 + 工作流 + 知识库 | 可视化编排 + Prompt 节点 | 工作流中引用插件 | Bot Store，插件市场 |
| **Dify** | Agent + Tool + Prompt 模板 | YAML 模板 + Prompt 变量 | 支持工具引用和模板嵌套 | Explore 社区模板 |
| **LangChain / LangGraph** | Chain + Tool + Agent | Python/TS 代码定义 | 代码级链式组合 | LangChain Hub，Prompt 模板仓库 |
| **Copilot Studio** | Topics + Actions + Plugins | 可视化画布 + Prompt 节点 | Topic 间跳转，Plugin 调用 | Microsoft 365 生态集成 |
| **Cursor / GitHub Copilot** | .instructions.md / SKILL.md | Markdown 文件 + YAML 元数据 | 内容中提及其他 Skill 名称 | 工作区本地管理 |
| **OpenClaw（龙虾🦞）** | SKILL.md（三层：bundled/managed/workspace） | YAML frontmatter + Markdown 正文 | 无显式引用，按上下文激活 | ClawHub 注册中心（13,700+ 技能），CLI 安装 |
| **ZeroClaw** | TOML manifest + SKILL.md | TOML 配置 + Markdown 正文 | 与 OpenClaw 技能兼容 | Open-Skills 同步（opt-in） |
| **LobeChat** | 助手市场 + Plugin | System Prompt + JSON Plugin | 插件独立定义，Prompt 引用 | 助手市场，社区共享 |
| **AutoGPT / AgentGPT** | Goal + Task 分解 | 自然语言目标描述 | 任务链自动编排 | 无统一技能市场 |
| **通义千问 / 豆包** | 智能体 + 工作流 | System Prompt + 工具配置 | 工作流节点引用 | 智能体广场 |

**设计选择**：采用 Markdown 文本 + 数据库管理方案，门槛最低，与 Cursor/Copilot 的思路一致；借鉴 OpenClaw 的 YAML 元数据、Token 开销意识和技能激活控制等成熟实践。

---

## 2. 技能定义

每个技能包含以下核心属性：

| 属性 | 说明 |
|------|------|
| 编码（Code） | 英文标识，唯一，如 `coder`、`translator` |
| 名称（Name） | 技能展示名称，同时也是 `@引用` 的标识，如"编程助手"、"翻译助手" |
| 图标（Icon） | Material Icon 名称，前端展示用，如 `code`、`translate` |
| 分类（Category） | 技能分类，如"通用"、"开发"、"创作"、"分析" |
| 描述（Description） | 一句话说明该技能做什么 |
| 技能正文（Content） | **大文本 Markdown**，包含完整的行为指令、规则、示例和 MCP 工具指引 |
| 排序权重（Sort） | 数值大的排前面，用于控制系统技能展示顺序 |
| 启用状态 | 是否对用户可见可用 |
| 系统标记 | 是否为系统内置（内置技能不可删除） |

---

## 3. 技能正文格式

技能正文（Content 字段）使用 Markdown 编写，推荐结构：

```markdown
# 编程助手

## 角色定义
你是一个专业的编程助手，精通多种编程语言和框架。

## 行为规则
- 代码优先：回答编程问题时优先给出可运行的代码
- 解释清晰：每段代码附带简明注释
- 最佳实践：遵循语言社区的编码规范

## MCP 工具使用
当用户需要查询 API 文档或运行代码时，可使用以下 MCP 工具：
- 使用 `search_docs` 工具搜索技术文档
- 使用 `run_code` 工具在沙箱中执行代码验证

## 引用技能
需要时可组合使用以下技能：
- @翻译助手：当用户要求用其他语言解释代码时调用
- @深度研究：当涉及复杂架构问题的多角度分析时引入

## 输出格式
- 使用 Markdown 格式回复
- 代码块标注语言
- 复杂逻辑使用分步骤讲解
```

### MCP 工具在技能中的表述

技能通过 **自然语言** 在 Markdown 正文中描述 MCP 工具的使用方式，无需额外的结构化字段：

- 在"MCP 工具使用"章节中，说明何时应该使用哪些工具、使用的场景和注意事项
- 系统在构建 System Prompt 时，将技能正文连同已配置的 MCP 工具定义一起注入模型上下文
- 模型根据技能正文中的指引决定何时调用哪个工具

这种"自然语言指引 + 工具定义自动注入"的方式：
- 无需维护技能与 MCP Server 的 ID 关联关系
- 用户编写技能时不需要知道 MCP Server 的技术细节
- 模型可以根据语义理解灵活决策，而非被硬绑定到特定工具

---

## 4. 技能引用（`@技能名`）

用户可在对话输入或技能正文中通过 `@技能名` 引用其他技能。

### 引用规则

| 规则 | 说明 |
|------|------|
| 引用语法 | `@技能名`，如 `@翻译助手`、`@编程助手` |
| 对话中引用 | 用户发消息时输入 `@编程助手`，系统自动将该技能内容注入本次会话的 System Prompt |
| 技能间引用 | 技能 A 的 Content 中写 `@技能B`，构建 Prompt 时自动展开技能 B 的内容 |
| 解析时机 | 构建 System Prompt 时，自动扫描 `@xxx` 引用并展开 |
| 循环引用保护 | A→B→A 自动检测并中断，记录警告 |
| 引用深度 | 最多 3 层嵌套（A→B→C），超过不再展开 |
| 引用不存在的技能 | 保留原文不报错，日志记录 |

### 输入框自动补全

- 用户在输入框中键入 `@` 后，弹出技能候选列表
- 列表按用户最近使用排序，显示技能图标 + 名称 + 简短描述
- 选中后插入 `@技能名 `（末尾空格），系统自动解析并在本次对话注入该技能

---

## 5. 技能激活与展示

### 激活方式

| 方式 | 说明 |
|------|------|
| **输入框 `@` 引用** | 发消息时输入 `@技能名`，本次对话注入该技能（推荐方式） |
| **SkillBar 点击** | 输入框下方的技能栏，点击技能按钮激活/取消 |
| **默认技能** | `UserSetting.DefaultSkill` 存储的编码，新会话自动应用 |
| **系统默认技能** | `IsSystem=true` 且 `Enable=true` 的技能，所有对话自动注入 |

### SkillBar 展示规则

输入框下方的技能栏（SkillBar）展示用户可快速访问的技能列表，展示顺序：

1. **用户最近使用的技能**（最近 7 天内使用过的，按使用时间从近到远排列）
2. **系统技能**（`IsSystem=true` 且 `Sort` 较高的，排在用户技能之后）
3. 超过 7 天未使用的用户技能不展示在 SkillBar 中
4. SkillBar 最多展示 **6 个**技能按钮 + 1 个"更多"按钮
5. "更多"按钮弹出完整技能列表（SkillPopover），分类分组显示

### 用户技能使用记录

系统自动记录用户使用技能的行为：

- 用户通过 `@技能名` 或 SkillBar 激活技能时，自动记录使用时间
- 同一技能重复使用时更新最后使用时间
- SkillBar 根据使用记录动态排列，让最常用的技能最容易触达

---

## 6. System Prompt 构建顺序

当技能被激活时，最终注入到模型的 System Prompt 按如下顺序拼接：

```
1. 系统级默认技能内容（IsSystem=true 且 Enable=true）
2. 用户的全局 System Prompt（UserSetting.SystemPrompt）
3. 当前会话激活的技能内容（含 @引用 展开后的完整文本）
```

---

## 7. 内置技能（系统预置）

系统初始化时自动创建以下技能（`IsSystem=true`），不可删除：

| 编码 | 名称 | 图标 | 分类 | 说明 |
|------|------|------|------|------|
| general | 通用助手 | smart_toy | 通用 | 默认的通用对话技能，无特殊指令 |
| coder | 编程助手 | code | 开发 | 精通多种编程语言，擅长代码编写、调试、Code Review |
| writer | 写作助手 | edit_note | 创作 | 擅长各类文体写作、内容编辑、文案优化 |
| translator | 翻译助手 | translate | 通用 | 多语言互译，保留原文风格和术语准确性 |
| analyst | 数据分析 | analytics | 分析 | 数据解读、报表生成、趋势分析 |
| researcher | 深度研究 | travel_explore | 分析 | 复杂问题的深度调研与多角度分析 |

---

## 8. 前端交互

### SkillBar 改造

当前 SkillBar 的技能项是硬编码的，改为从后端动态获取：

| 改造点 | 说明 |
|--------|------|
| 数据源 | 从后端获取"最近使用 + 系统技能"列表 |
| 图标和名称 | 使用技能的 `Icon` 和 `Name` 字段 |
| 点击行为 | 点击技能按钮激活，注入到当前会话的 System Prompt |
| 活跃态 | 当前会话选中的技能高亮显示 |
| "更多"按钮 | 弹出完整技能列表（SkillPopover），分类分组，含搜索 |

### 输入框 `@` 补全

| 功能 | 说明 |
|------|------|
| 触发 | 输入 `@` 字符时弹出候选列表 |
| 列表内容 | 最近使用的技能优先，然后是全部启用的技能 |
| 每项展示 | 图标 + 名称 + 描述 |
| 选中行为 | 插入 `@技能名 `，本次对话自动注入该技能 |
| 键盘操作 | ↑↓ 选择、Enter 确认、Esc 关闭 |

### 技能管理页（设置 Tab）

在设置页新增"技能"Tab：

| 功能 | 说明 |
|------|------|
| 技能列表 | 展示所有可用技能，分类分组显示 |
| 技能详情 | 点击展开查看完整 Markdown 内容 |
| 编辑技能 | 管理员可编辑技能内容（Markdown 编辑器） |
| 创建技能 | 管理员可创建新自定义技能 |
| 删除技能 | 管理员可删除非系统技能 |

---

## 9. 与现有体系的关系

| 集成点 | 说明 |
|--------|------|
| MCP 工具 | 技能正文中以自然语言描述 MCP 工具的使用场景，模型根据语义自行决策调用 |
| 函数调用 | 技能正文中可声明工具使用规范（如"优先使用 xxx 工具查询"），指导模型何时调用 |
| System Prompt | 技能内容最终拼接为 System Prompt 的一部分，与用户自定义 Prompt 共存 |
| 用户设置 | `UserSetting.DefaultSkill` 字段存储默认技能编码，新建会话时自动应用 |
| 会话 | `Conversation` 表增加 `SkillId` 字段，记录当前会话使用的技能 |
