diff --git a/docs/superpowers/specs/2026-03-21-skill-system-design.md b/docs/superpowers/specs/2026-03-21-skill-system-design.md new file mode 100644 index 0000000..67d7885 --- /dev/null +++ b/docs/superpowers/specs/2026-03-21-skill-system-design.md @@ -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. **权限控制**：团队共享需防止越权访问