132 lines
4.8 KiB
Markdown
132 lines
4.8 KiB
Markdown
# Skill 功能
|
||
|
||
> 负责范围：技能包管理服务 - 核心实现
|
||
> 最后更新：2026-04-16
|
||
|
||
## 当前状态
|
||
|
||
Skill 系统支持两种来源：官方 skills (`./skills/`) 和用户 skills (`projects/uploads/{bot_id}/skills/`)。支持 Hook 系统和 MCP 服务器配置，通过 SKILL.md 或 plugin.json 定义元数据。
|
||
|
||
目前已新增一批**纯 `SKILL.md` 型业务 skill MVP**，用于研究、摘要、报告和情报编排，底层文件处理与外部检索能力继续复用既有 skill。
|
||
|
||
## 核心文件
|
||
|
||
- `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
|
||
|
||
## 最近重要事项
|
||
|
||
- 2026-04-16: 为 `auto-daily-summary` 和 `competitor-news-intel` 新增 Python CLI 脚本 MVP，统一采用 `argparse + JSON stdout` 模式
|
||
- 2026-04-16: 新增 6 个纯 `SKILL.md` 型业务 skill：`market-academic-insight`、`financial-report-generator`、`contract-document-generator`、`sales-decision-report`、`auto-daily-summary`、`competitor-news-intel`
|
||
- 2025-02-11: 初始化 skill 功能 memory
|
||
|
||
## Gotchas（开发必读）
|
||
|
||
- ⚠️ 纯 `SKILL.md` 型业务 skill 适合先承载 workflow、输入模板、输出模板；需要稳定文件产出或自动化时再补 `scripts/`
|
||
- ⚠️ 新业务 skill 应复用既有基础能力 skill（如 `baidu-search`、`xlsx`、`docx`、`pdf`、`schedule-job`、`imap-smtp-email`），避免重复定义底层工具能力
|
||
- ⚠️ 新增脚本优先采用 `Python + argparse + JSON stdout`，比 `argv[1] JSON` 更适合自动化链路
|
||
- ⚠️ `auto-daily-summary` 需要特别注意中文分句、action 边界截断、risk 窗口裁剪，否则容易把整句/整段吞进去
|
||
- ⚠️ `competitor-news-intel` 的 payload 校验应按命令拆分（collect/analyze/run），不要共用一套最小校验
|
||
- ⚠️ `competitor-news-intel` 的 `collect/run` 依赖 `BAIDU_API_KEY`；无该环境变量时应返回稳定错误 JSON，不要静默降级
|
||
- ⚠️ 执行脚本必须使用绝对路径
|
||
- ⚠️ 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 格式
|
||
|
||
```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
|
||
|
||
## 设计原则
|
||
|
||
- **渐进式加载**：按需加载，避免一次性读取所有
|
||
- **绝对路径优先**：执行脚本必须使用绝对路径
|
||
- **通用化设计**：脚本应参数化，解决一类问题
|
||
- **安全优先**：完整的上传验证链
|
||
|
||
## 配置项
|
||
|
||
```bash
|
||
SKILLS_DIR=./skills # 官方 skills 目录
|
||
BACKEND_HOST=xxx # RAG API 主机
|
||
MASTERKEY=xxx # 认证密钥
|
||
```
|
||
|
||
## 索引
|
||
|
||
- 设计决策：`decisions/`
|
||
- 变更历史：`changelog/`
|
||
- 相关文档：`docs/`
|