Add skill system design document
This commit is contained in:
288
docs/superpowers/specs/2026-03-21-skill-system-design.md
Normal file
288
docs/superpowers/specs/2026-03-21-skill-system-design.md
Normal file
@@ -0,0 +1,288 @@
|
|||||||
|
# Skill 系统设计方案
|
||||||
|
|
||||||
|
## 1. 概述
|
||||||
|
|
||||||
|
### 1.1 背景
|
||||||
|
|
||||||
|
当前 Jarvis 系统采用基于 LangGraph 的多 Agent 架构（Master/Planner/Executor/Librarian/Analyst），通过关键词规则路由到子 Agent。系统缺乏可扩展的 Skill 机制，无法让 Agent 按需调用自定义能力。
|
||||||
|
|
||||||
|
### 1.2 目标
|
||||||
|
|
||||||
|
构建一个 **Skill 系统**，让每个 Agent 能够：
|
||||||
|
- 挂载可配置的 Skill 能力插件
|
||||||
|
- 由 LLM 自主判断何时使用哪个 Skill
|
||||||
|
- 支持私有/团队共享/市场三种可见性
|
||||||
|
- Skill 作为 Agent 的指令模板 + 工具组合
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 核心理念
|
||||||
|
|
||||||
|
**Skill 是 Agent 的"能力插件"，由 LLM 自主决策调用时机。**
|
||||||
|
|
||||||
|
```
|
||||||
|
用户: "帮我规划今天的工作"
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
Master Agent 理解意图
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
路由到 Planner Agent
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
Planner 分析任务 → 自主判断需要什么 Skill
|
||||||
|
│
|
||||||
|
├──→ 需要数据 → 调用 "数据获取" Skill
|
||||||
|
├──→ 需要优先级 → 调用 "任务排序" Skill
|
||||||
|
└──→ 需要时间安排 → 调用 "日程规划" Skill
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 数据模型
|
||||||
|
|
||||||
|
### 3.1 Skill 实体
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|-----|------|-----|
|
||||||
|
| id | UUID | 主键 |
|
||||||
|
| name | str | Skill 名称，如 "任务排序" |
|
||||||
|
| description | str | 供 LLM 理解该 Skill 的用途 |
|
||||||
|
| instructions | str | Agent 执行时的系统指令模板 |
|
||||||
|
| agent_type | AgentRole | 适用于哪个 Agent (master/planner/executor/librarian/analyst) |
|
||||||
|
| tools | List[str] | 引用的工具名称列表 |
|
||||||
|
| required_context | List[str] | 需要的前置数据 |
|
||||||
|
| output_format | str | 输出格式要求（可选） |
|
||||||
|
| visibility | enum | private/team/market |
|
||||||
|
| team_id | UUID | 团队 ID（visibility=team 时使用） |
|
||||||
|
| is_active | bool | 是否启用 |
|
||||||
|
| owner_id | UUID | 创建者 ID |
|
||||||
|
| created_at | datetime | 创建时间 |
|
||||||
|
| updated_at | datetime | 更新时间 |
|
||||||
|
|
||||||
|
### 3.2 Agent-Skill 关联
|
||||||
|
|
||||||
|
每个 Agent 运行时从数据库加载其 `agent_type` 对应的所有 `is_active=True` 的 Skills，作为可选能力供 LLM 调用。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 系统架构
|
||||||
|
|
||||||
|
### 4.1 组件关系
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────┐
|
||||||
|
│ Agent Brain │
|
||||||
|
│ ┌─────────────────────────────────────────────┐ │
|
||||||
|
│ │ Master Agent (理解意图，路由到子 Agent) │ │
|
||||||
|
│ └─────────────────────────────────────────────┘ │
|
||||||
|
│ │ │
|
||||||
|
│ ▼ │
|
||||||
|
│ ┌─────────────────────────────────────────────┐ │
|
||||||
|
│ │ [Planner] [Executor] [Librarian] ... │ │
|
||||||
|
│ │ │ │ │ │ │
|
||||||
|
│ │ └───────────┼────────────┘ │ │
|
||||||
|
│ │ ▼ │ │
|
||||||
|
│ │ ┌──────────────────┐ │ │
|
||||||
|
│ │ │ Skill Registry │ │ │
|
||||||
|
│ │ │ (可用的 Skills) │ │ │
|
||||||
|
│ │ └────────┬─────────┘ │ │
|
||||||
|
│ │ │ │ │
|
||||||
|
│ │ LLM 自主判断使用哪个 Skill │ │
|
||||||
|
│ └─────────────────────────────────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2 组件说明
|
||||||
|
|
||||||
|
| 组件 | 职责 |
|
||||||
|
|-----|------|
|
||||||
|
| Skill Registry | 存储 Skill 定义，提供加载接口，权限校验 |
|
||||||
|
| Skill Loader | 运行时加载 Agent 对应的 Skills |
|
||||||
|
| Skill Executor | 执行 Skill 指令，调用工具链 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Skill 定义示例
|
||||||
|
|
||||||
|
### 5.1 任务排序 Skill
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "任务排序",
|
||||||
|
"description": "根据优先级、截止日期、依赖关系对任务列表进行智能排序",
|
||||||
|
"instructions": "你是一个任务排序专家。接收任务列表后，按以下规则排序：\n1. 紧急且重要优先\n2. 有截止日期的优先\n3. 依赖其他任务的优先\n输出排序后的任务列表及理由。",
|
||||||
|
"agent_type": "planner",
|
||||||
|
"tools": ["get_tasks"],
|
||||||
|
"required_context": ["原始任务列表"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.2 知识检索 Skill
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "知识检索",
|
||||||
|
"description": "从用户知识库中检索相关内容，支持向量检索和关键词检索",
|
||||||
|
"instructions": "你是一个知识管理员。从知识库中检索与用户问题相关的内容，返回相关文档片段和来源。",
|
||||||
|
"agent_type": "librarian",
|
||||||
|
"tools": ["search_knowledge", "hybrid_search"],
|
||||||
|
"required_context": ["用户查询"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.3 数据分析 Skill
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "效率分析",
|
||||||
|
"description": "分析任务完成情况，计算工作效率指标",
|
||||||
|
"instructions": "你是一个数据分析师。接收任务列表后，分析：\n1. 完成率\n2. 平均完成时间\n3. 阻塞原因\n4. 改进建议",
|
||||||
|
"agent_type": "analyst",
|
||||||
|
"tools": ["get_tasks", "get_stats"],
|
||||||
|
"required_context": ["任务数据"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. API 设计
|
||||||
|
|
||||||
|
### 6.1 Skill 管理
|
||||||
|
|
||||||
|
| 方法 | 路径 | 说明 |
|
||||||
|
|-----|------|-----|
|
||||||
|
| POST | /api/skills | 创建 Skill |
|
||||||
|
| GET | /api/skills | 列表（支持过滤 agent_type, visibility） |
|
||||||
|
| GET | /api/skills/{id} | 详情 |
|
||||||
|
| PUT | /api/skills/{id} | 更新 |
|
||||||
|
| DELETE | /api/skills/{id} | 删除 |
|
||||||
|
|
||||||
|
### 6.2 Skill 执行
|
||||||
|
|
||||||
|
| 方法 | 路径 | 说明 |
|
||||||
|
|-----|------|-----|
|
||||||
|
| POST | /api/skills/{id}/execute | 手动执行 Skill |
|
||||||
|
| GET | /api/skills/execute/{execution_id} | 查询执行结果 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 数据库表设计
|
||||||
|
|
||||||
|
### 7.1 skill 表
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE skill (
|
||||||
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
name VARCHAR(100) NOT NULL,
|
||||||
|
description TEXT,
|
||||||
|
instructions TEXT NOT NULL,
|
||||||
|
agent_type VARCHAR(50) NOT NULL,
|
||||||
|
tools JSONB DEFAULT '[]',
|
||||||
|
required_context JSONB DEFAULT '[]',
|
||||||
|
output_format TEXT,
|
||||||
|
visibility VARCHAR(20) DEFAULT 'private',
|
||||||
|
team_id UUID,
|
||||||
|
is_active BOOLEAN DEFAULT true,
|
||||||
|
owner_id UUID NOT NULL,
|
||||||
|
created_at TIMESTAMP DEFAULT NOW(),
|
||||||
|
updated_at TIMESTAMP DEFAULT NOW()
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE INDEX idx_skill_agent_type ON skill(agent_type);
|
||||||
|
CREATE INDEX idx_skill_visibility ON skill(visibility);
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. 前端界面
|
||||||
|
|
||||||
|
### 8.1 Skill 管理入口
|
||||||
|
|
||||||
|
入口位置：智能链路 → Skill 市场
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────┐
|
||||||
|
│ 智能链路 → Skill 市场 │
|
||||||
|
├─────────────────────────────────────────────┤
|
||||||
|
│ [我的 Skills] [团队共享] [市场] │
|
||||||
|
├─────────────────────────────────────────────┤
|
||||||
|
│ ┌───────────────────────────────────────┐ │
|
||||||
|
│ │ 任务排序 │ │
|
||||||
|
│ │ 适用: Planner Agent │ │
|
||||||
|
│ │ 工具: get_tasks │ │
|
||||||
|
│ │ 描述: 根据优先级排序任务列表 │ │
|
||||||
|
│ │ 可见: 私有 │ │
|
||||||
|
│ │ [编辑] [禁用] [复制] │ │
|
||||||
|
│ └───────────────────────────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8.2 Skill 编辑界面
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────┐
|
||||||
|
│ 创建/编辑 Skill │
|
||||||
|
├─────────────────────────────────────────────┤
|
||||||
|
│ 名称: [________________] │
|
||||||
|
│ 描述: [________________] │
|
||||||
|
│ │
|
||||||
|
│ 适用 Agent: │
|
||||||
|
│ ( ) Master (●) Planner ( ) Executor │
|
||||||
|
│ ( ) Librarian ( ) Analyst │
|
||||||
|
│ │
|
||||||
|
│ 引用工具: │
|
||||||
|
│ ☑ get_tasks ☑ create_task │
|
||||||
|
│ ☐ search_knowledge ☐ hybrid_search │
|
||||||
|
│ │
|
||||||
|
│ 指令模板: │
|
||||||
|
│ ┌─────────────────────────────────────┐ │
|
||||||
|
│ │ 你是一个任务排序专家... │ │
|
||||||
|
│ └─────────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
│ 可见性: │
|
||||||
|
│ (●) 私有 ( ) 团队共享 ( ) 公开市场 │
|
||||||
|
│ │
|
||||||
|
│ [取消] [保存] │
|
||||||
|
└─────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. 与现有系统集成
|
||||||
|
|
||||||
|
| 现有组件 | 集成方式 |
|
||||||
|
|---------|---------|
|
||||||
|
| Agent Role | Skill.agent_type 引用现有 AgentRole 枚举 |
|
||||||
|
| Tools | Skill.tools 引用现有 ALL_TOOLS 中的工具名 |
|
||||||
|
| Prompts | Skill.instructions 作为 Agent 系统提示的补充 |
|
||||||
|
| User/Team | 复用现有权限体系，visibility 字段控制 |
|
||||||
|
| Router | Master Agent 路由逻辑不变，Skill 由子 Agent 按需调用 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. 实现计划
|
||||||
|
|
||||||
|
### Phase 1: 基础框架
|
||||||
|
- [ ] Skill 数据模型与 CRUD API
|
||||||
|
- [ ] Skill Registry 服务
|
||||||
|
- [ ] Skill 加载机制（Agent 初始化时注入）
|
||||||
|
- [ ] 前端 Skill 管理界面
|
||||||
|
|
||||||
|
### Phase 2: 执行机制
|
||||||
|
- [ ] Skill Executor
|
||||||
|
- [ ] 工具调用桥接
|
||||||
|
- [ ] 执行结果返回
|
||||||
|
|
||||||
|
### Phase 3: 高级特性
|
||||||
|
- [ ] 团队共享机制
|
||||||
|
- [ ] Skill 市场
|
||||||
|
- [ ] Skill 编排（多个 Skill 串联）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. 风险与约束
|
||||||
|
|
||||||
|
1. **LLM 自主性**：依赖 LLM 准确理解 Skill 描述，需优化 prompt
|
||||||
|
2. **工具兼容性**：Skill 引用的工具需在 ALL_TOOLS 中存在
|
||||||
|
3. **权限控制**：团队共享需防止越权访问
|
||||||
Reference in New Issue
Block a user