qwen_agent/.features/skill/MEMORY.md

Skill 功能

负责范围：技能包管理服务 - 核心实现 最后更新：2025-02-11

当前状态

Skill 系统支持两种来源：官方 skills (./skills/) 和用户 skills (projects/uploads/{bot_id}/skills/)。支持 Hook 系统和 MCP 服务器配置，通过 SKILL.md 或 plugin.json 定义元数据。

核心文件

• routes/skill_manager.py - Skill 上传/删除/列表 API
• agent/plugin_hook_loader.py - Hook 系统实现
• agent/deep_assistant.py - CustomSkillsMiddleware
• agent/prompt_loader.py - PrePrompt hooks + MCP 配置合并
• skills/ - 官方 skills 目录
• skills_developing/ - 开发中 skills

最近重要事项

• 2025-02-11: 初始化 skill 功能 memory

Gotchas（开发必读）

• ⚠️ 执行脚本必须使用绝对路径
• ⚠️ MCP 配置优先级：Skill MCP > 默认 MCP > 用户参数
• ⚠️ 上传大小限制：50MB（ZIP），解压后最大 500MB
• ⚠️ 压缩比例检查：最大 100:1（防止 zip 炸弹）
• ⚠️ 符号链接检查：禁止解压包含符号链接的文件

Skill 目录结构

skill-name/
├── SKILL.md                    # 核心指令文档（必需）
├── skill.yaml                  # 元数据配置（可选）
├── .claude-plugin/
│   └── plugin.json            # Hook 和 MCP 配置（可选）
└── scripts/                    # 可执行脚本（可选）
    └── script.py

Hook 系统

Hook 类型	执行时机	用途
PrePrompt	system_prompt 加载时	动态注入用户上下文
PostAgent	agent 执行后	处理响应结果
PreSave	保存消息前	内容过滤/修改

API 接口

端点	方法	功能
GET /api/v1/skill/list	-	返回官方 + 用户 skills
POST /api/v1/skill/upload	-	ZIP 上传，解压到用户目录
DELETE /api/v1/skill/remove	-	删除用户 skill

内置 Skills

Skill 名称	功能描述
excel-analysis	Excel 数据分析、透视表、图表
managing-scripts	管理可复用脚本库
rag-retrieve	RAG 知识库检索
jina-ai	Jina AI Reader/Search
user-context-loader	Hook 机制示例

plugin.json 格式

{
  "name": "skill-name",
  "description": "描述",
  "hooks": {
    "PrePrompt": [{"type": "command", "command": "python hooks/pre_prompt.py"}],
    "PostAgent": [...],
    "PreSave": [...]
  },
  "mcpServers": {
    "server-name": {
      "command": "...",
      "args": [...]
    }
  }
}

Skill 加载优先级

1. Skill MCP 配置（最高）
2. 默认 MCP 配置 (mcp/mcp_settings.json)
3. 用户传入参数（覆盖所有）

安全措施

• ZipSlip 防护：检查解压路径
• 路径遍历防护：验证 bot_id 和 skill_name 格式
• 大小限制：上传 50MB，解压后 500MB
• 压缩比限制：最大 100:1

设计原则

• 渐进式加载：按需加载，避免一次性读取所有
• 绝对路径优先：执行脚本必须使用绝对路径
• 通用化设计：脚本应参数化，解决一类问题
• 安全优先：完整的上传验证链

配置项

SKILLS_DIR=./skills           # 官方 skills 目录
BACKEND_HOST=xxx             # RAG API 主机
MASTERKEY=xxx                # 认证密钥

索引

• 设计决策：decisions/
• 变更历史：changelog/
• 相关文档：docs/