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