11 KiB
11 KiB
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
{
"name": "任务排序",
"description": "根据优先级、截止日期、依赖关系对任务列表进行智能排序",
"instructions": "你是一个任务排序专家。接收任务列表后，按以下规则排序：\n1. 紧急且重要优先\n2. 有截止日期的优先\n3. 依赖其他任务的优先\n输出排序后的任务列表及理由。",
"agent_type": "planner",
"tools": ["get_tasks"],
"required_context": ["原始任务列表"]
}
5.2 知识检索 Skill
{
"name": "知识检索",
"description": "从用户知识库中检索相关内容，支持向量检索和关键词检索",
"instructions": "你是一个知识管理员。从知识库中检索与用户问题相关的内容，返回相关文档片段和来源。",
"agent_type": "librarian",
"tools": ["search_knowledge", "hybrid_search"],
"required_context": ["用户查询"]
}
5.3 数据分析 Skill
{
"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 表
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. 风险与约束
- LLM 自主性：依赖 LLM 准确理解 Skill 描述，需优化 prompt
- 工具兼容性：Skill 引用的工具需在 ALL_TOOLS 中存在
- 权限控制：团队共享需防止越权访问