# 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. **权限控制**：团队共享需防止越权访问
