feat: support agent skills
feat:support agent skills
This commit is contained in:
@@ -0,0 +1,482 @@
|
||||
# Agent Skills 文档
|
||||
|
||||
## 概述
|
||||
|
||||
Agent Skills 是一种让 Agent 通过阅读"使用说明书"来学习新能力的扩展机制。与传统的硬编码工具不同,Skills 通过注入到 System Prompt 来扩展 Agent 的能力,遵循 **Progressive Disclosure(渐进式披露)** 的设计理念。
|
||||
|
||||
### 核心特性
|
||||
|
||||
- **非侵入式扩展**:不影响原有 Agent ReAct 流程
|
||||
- **按需加载**:三级渐进式加载,优化 Token 使用
|
||||
- **沙箱执行**:脚本在隔离环境中安全执行
|
||||
- **灵活配置**:支持多目录、白名单过滤
|
||||
|
||||
## 设计理念
|
||||
|
||||
### Progressive Disclosure(渐进式披露)
|
||||
|
||||
Skills 采用三级加载机制,确保只在需要时才向 LLM 提供详细信息:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Level 1: 元数据 (Metadata) │
|
||||
│ • 始终加载到 System Prompt │
|
||||
│ • 约 100 tokens/skill │
|
||||
│ • 包含:技能名称 + 简短描述 │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
↓ 用户请求匹配时
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Level 2: 指令 (Instructions) │
|
||||
│ • 通过 read_skill 工具按需加载 │
|
||||
│ • SKILL.md 的指令内容 │
|
||||
│ • 包含:详细指令、代码示例、使用方法 │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
↓ 需要更多信息时
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Level 3: 附加资源 (Resources) │
|
||||
│ • 通过 read_skill 工具加载特定文件 │
|
||||
│ • 补充文档、配置模板、脚本文件 │
|
||||
│ • 通过 execute_skill_script 执行脚本 │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Skill 目录结构
|
||||
|
||||
每个 Skill 是一个目录,包含 `SKILL.md` 主文件和可选的附加资源:
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md # 必需:主文件(含 YAML frontmatter)
|
||||
├── REFERENCE.md # 可选:补充文档
|
||||
├── templates/ # 可选:模板文件
|
||||
│ └── config.yaml
|
||||
└── scripts/ # 可选:可执行脚本
|
||||
├── analyze.py
|
||||
└── generate.sh
|
||||
```
|
||||
|
||||
## SKILL.md 格式
|
||||
|
||||
### YAML Frontmatter
|
||||
|
||||
每个 `SKILL.md` 必须以 YAML frontmatter 开头,定义元数据:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: pdf-processing
|
||||
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
---
|
||||
|
||||
# PDF Processing
|
||||
|
||||
This skill provides utilities for working with PDF documents.
|
||||
|
||||
## Quick Start
|
||||
|
||||
Use pdfplumber to extract text from PDFs:
|
||||
|
||||
```python
|
||||
import pdfplumber
|
||||
|
||||
with pdfplumber.open("document.pdf") as pdf:
|
||||
text = pdf.pages[0].extract_text()
|
||||
print(text)
|
||||
```
|
||||
|
||||
## Available Operations
|
||||
|
||||
1. **Text Extraction**: Extract text content from PDF pages
|
||||
2. **Table Extraction**: Extract tabular data from PDFs
|
||||
...
|
||||
```
|
||||
|
||||
### 元数据验证规则
|
||||
|
||||
| 字段 | 要求 |
|
||||
|------|------|
|
||||
| `name` | 1-50 字符,仅允许 `a-z`, `0-9`, `-`, `_`,不能是保留词 |
|
||||
| `description` | 1-500 字符,描述技能用途和触发条件 |
|
||||
|
||||
**保留词**:`system`, `default`, `internal`, `core`, `base`, `root`, `admin`
|
||||
|
||||
### 最佳实践
|
||||
|
||||
**name 命名**:
|
||||
- ✅ `pdf-processing`, `code_review`, `api-client`
|
||||
- ❌ `PDF Processing`, `my skill`, `system`
|
||||
|
||||
**description 编写**:
|
||||
- 清晰描述技能的功能
|
||||
- 包含触发条件(如 "when working with PDF files")
|
||||
- 避免过于模糊的描述
|
||||
|
||||
## 配置
|
||||
|
||||
### AgentConfig 配置项
|
||||
|
||||
```go
|
||||
type AgentConfig struct {
|
||||
// ... 其他配置 ...
|
||||
|
||||
// Skills 相关配置
|
||||
SkillsEnabled bool `json:"skills_enabled"` // 是否启用 Skills
|
||||
SkillDirs []string `json:"skill_dirs"` // Skill 目录列表
|
||||
AllowedSkills []string `json:"allowed_skills"` // 白名单(空=全部允许)
|
||||
SandboxMode string `json:"sandbox_mode"` // sandbox 模式
|
||||
SandboxTimeout int `json:"sandbox_timeout"` // 脚本执行超时(秒)
|
||||
}
|
||||
```
|
||||
|
||||
### 配置示例
|
||||
|
||||
```json
|
||||
{
|
||||
"skills_enabled": true,
|
||||
"skill_dirs": [
|
||||
"/path/to/project/skills",
|
||||
"/home/user/.agent-skills"
|
||||
],
|
||||
"allowed_skills": ["pdf-processing", "code-review"],
|
||||
"sandbox_mode": "docker",
|
||||
"sandbox_timeout": 30
|
||||
}
|
||||
```
|
||||
|
||||
### Sandbox 模式
|
||||
|
||||
| 模式 | 说明 |
|
||||
|------|------|
|
||||
| `docker` | 使用 Docker 容器隔离(推荐) |
|
||||
| `local` | 本地进程执行(基础安全限制) |
|
||||
| `disabled` | 禁用脚本执行 |
|
||||
|
||||
## Agent 工具
|
||||
|
||||
Skills 功能通过两个工具与 Agent 交互:
|
||||
|
||||
### read_skill
|
||||
|
||||
读取技能内容或特定文件。
|
||||
|
||||
**参数**:
|
||||
```json
|
||||
{
|
||||
"skill_name": "pdf-processing", // 必需:技能名称
|
||||
"file_path": "FORMS.md" // 可选:相对路径
|
||||
}
|
||||
```
|
||||
|
||||
**使用场景**:
|
||||
1. 加载 Level 2 内容:仅传 `skill_name`
|
||||
2. 加载 Level 3 资源:同时传 `skill_name` 和 `file_path`
|
||||
|
||||
**示例调用**:
|
||||
```json
|
||||
// 加载技能主内容
|
||||
{"skill_name": "pdf-processing"}
|
||||
|
||||
// 加载补充文档
|
||||
{"skill_name": "pdf-processing", "file_path": "FORMS.md"}
|
||||
|
||||
// 查看脚本内容
|
||||
{"skill_name": "pdf-processing", "file_path": "scripts/analyze.py"}
|
||||
```
|
||||
|
||||
### execute_skill_script
|
||||
|
||||
在沙箱中执行技能脚本。
|
||||
|
||||
**参数**:
|
||||
```json
|
||||
{
|
||||
"skill_name": "pdf-processing", // 必需:技能名称
|
||||
"script_path": "scripts/analyze.py", // 必需:脚本相对路径
|
||||
"args": ["input.pdf", "--format", "json"] // 可选:命令行参数
|
||||
}
|
||||
```
|
||||
|
||||
**支持的脚本类型**:
|
||||
- Python (`.py`)
|
||||
- Shell (`.sh`)
|
||||
- JavaScript/Node.js (`.js`)
|
||||
- Ruby (`.rb`)
|
||||
- Go (`.go`)
|
||||
|
||||
## 创建自定义 Skill
|
||||
|
||||
### 第一步:创建目录结构
|
||||
|
||||
```bash
|
||||
mkdir -p my-skills/code-review
|
||||
cd my-skills/code-review
|
||||
```
|
||||
|
||||
### 第二步:编写 SKILL.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: code-review
|
||||
description: Review code for best practices, security issues, and performance. Use when the user asks to review, analyze, or improve code quality.
|
||||
---
|
||||
|
||||
# Code Review Skill
|
||||
|
||||
This skill helps analyze code for quality and security issues.
|
||||
|
||||
## How to Use
|
||||
|
||||
When reviewing code:
|
||||
|
||||
1. Check for common security vulnerabilities
|
||||
2. Identify performance bottlenecks
|
||||
3. Suggest best practice improvements
|
||||
|
||||
## Security Checklist
|
||||
|
||||
- [ ] SQL Injection prevention
|
||||
- [ ] XSS protection
|
||||
- [ ] Input validation
|
||||
- [ ] Authentication checks
|
||||
|
||||
## Performance Tips
|
||||
|
||||
- Avoid N+1 queries
|
||||
- Use appropriate data structures
|
||||
- Consider caching strategies
|
||||
```
|
||||
|
||||
### 第三步:添加辅助脚本(可选)
|
||||
|
||||
创建 `scripts/lint.py`:
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""Simple code linter for demonstration."""
|
||||
import sys
|
||||
import json
|
||||
|
||||
def lint_code(filepath):
|
||||
issues = []
|
||||
with open(filepath) as f:
|
||||
for i, line in enumerate(f, 1):
|
||||
if len(line) > 120:
|
||||
issues.append({
|
||||
"line": i,
|
||||
"issue": "Line too long",
|
||||
"severity": "warning"
|
||||
})
|
||||
if "eval(" in line:
|
||||
issues.append({
|
||||
"line": i,
|
||||
"issue": "Avoid using eval()",
|
||||
"severity": "error"
|
||||
})
|
||||
return issues
|
||||
|
||||
if __name__ == "__main__":
|
||||
if len(sys.argv) < 2:
|
||||
print("Usage: lint.py <filepath>")
|
||||
sys.exit(1)
|
||||
|
||||
result = lint_code(sys.argv[1])
|
||||
print(json.dumps(result, indent=2))
|
||||
```
|
||||
|
||||
### 第四步:配置 Agent
|
||||
|
||||
将 Skill 目录添加到 Agent 配置:
|
||||
|
||||
```json
|
||||
{
|
||||
"skills_enabled": true,
|
||||
"skill_dirs": ["/path/to/my-skills"]
|
||||
}
|
||||
```
|
||||
|
||||
## 沙箱安全机制
|
||||
|
||||
### Docker 沙箱
|
||||
|
||||
Docker 模式提供最强的隔离:
|
||||
|
||||
- **非 root 用户**:容器内以普通用户运行
|
||||
- **Capability 限制**:移除所有 Linux capabilities
|
||||
- **只读文件系统**:根文件系统只读
|
||||
- **资源限制**:内存 256MB,CPU 限制
|
||||
- **网络隔离**:默认无网络访问
|
||||
- **临时挂载**:Skill 目录只读挂载
|
||||
|
||||
```bash
|
||||
# Docker 执行示例
|
||||
docker run --rm \
|
||||
--user 1000:1000 \
|
||||
--cap-drop ALL \
|
||||
--read-only \
|
||||
--memory=256m \
|
||||
--network=none \
|
||||
-v /path/to/skill:/skill:ro \
|
||||
-w /skill \
|
||||
python:3.11-slim \
|
||||
python scripts/analyze.py input.pdf
|
||||
```
|
||||
|
||||
### Local 沙箱
|
||||
|
||||
Local 模式提供基础保护:
|
||||
|
||||
- **命令白名单**:仅允许特定解释器
|
||||
- **工作目录限制**:限定在 Skill 目录
|
||||
- **环境变量过滤**:仅传递安全变量
|
||||
- **超时控制**:默认 30 秒超时
|
||||
- **路径遍历防护**:防止访问 Skill 目录外文件
|
||||
|
||||
**允许的命令**:
|
||||
- `python`, `python3`
|
||||
- `node`, `nodejs`
|
||||
- `bash`, `sh`
|
||||
- `ruby`
|
||||
- `go run`
|
||||
|
||||
## API 参考
|
||||
|
||||
### SkillManager
|
||||
|
||||
```go
|
||||
type Manager interface {
|
||||
// 初始化,发现所有 Skills
|
||||
Initialize(ctx context.Context) error
|
||||
|
||||
// 获取所有 Skill 元数据(Level 1)
|
||||
GetAllMetadata() []*SkillMetadata
|
||||
|
||||
// 加载 Skill 指令(Level 2)
|
||||
LoadSkill(ctx context.Context, skillName string) (*Skill, error)
|
||||
|
||||
// 读取 Skill 文件内容(Level 3)
|
||||
ReadSkillFile(ctx context.Context, skillName, filePath string) (string, error)
|
||||
|
||||
// 列出 Skill 中的所有文件
|
||||
ListSkillFiles(ctx context.Context, skillName string) ([]string, error)
|
||||
|
||||
// 执行 Skill 脚本
|
||||
ExecuteScript(ctx context.Context, skillName, scriptPath string, args []string) (*sandbox.ExecuteResult, error)
|
||||
|
||||
// 检查是否启用
|
||||
IsEnabled() bool
|
||||
}
|
||||
```
|
||||
|
||||
### Skill 结构
|
||||
|
||||
```go
|
||||
type Skill struct {
|
||||
Name string // 技能名称
|
||||
Description string // 技能描述
|
||||
BasePath string // 目录绝对路径
|
||||
FilePath string // SKILL.md 绝对路径
|
||||
Instructions string // SKILL.md 主体指令内容
|
||||
Loaded bool // 是否已加载 Level 2
|
||||
}
|
||||
|
||||
type SkillMetadata struct {
|
||||
Name string // 技能名称
|
||||
Description string // 技能描述
|
||||
BasePath string // 目录路径
|
||||
}
|
||||
```
|
||||
|
||||
### ExecuteResult 结构
|
||||
|
||||
```go
|
||||
type ExecuteResult struct {
|
||||
ExitCode int // 退出码
|
||||
Stdout string // 标准输出
|
||||
Stderr string // 标准错误
|
||||
Duration time.Duration // 执行时长
|
||||
Error error // 执行错误
|
||||
}
|
||||
```
|
||||
|
||||
## 示例:完整工作流
|
||||
|
||||
以下是 Agent 处理用户请求的完整流程:
|
||||
|
||||
```
|
||||
用户: "帮我从 report.pdf 提取表格数据"
|
||||
|
||||
Agent 思考:
|
||||
→ 查看 System Prompt 中的 Skills 列表
|
||||
→ 发现 "pdf-processing" 技能匹配
|
||||
|
||||
Agent 行动 1: 调用 read_skill
|
||||
→ {"skill_name": "pdf-processing"}
|
||||
→ 获取 SKILL.md 指令内容
|
||||
→ 学习如何使用 pdfplumber
|
||||
|
||||
Agent 行动 2: 调用 execute_skill_script
|
||||
→ {"skill_name": "pdf-processing",
|
||||
"script_path": "scripts/extract_text.py",
|
||||
"args": ["report.pdf"]}
|
||||
→ 脚本在沙箱中执行,返回提取的表格数据
|
||||
|
||||
Agent 回复:
|
||||
→ 向用户展示提取的表格数据
|
||||
→ 提供数据使用建议
|
||||
```
|
||||
|
||||
## 故障排查
|
||||
|
||||
### Skill 未被发现
|
||||
|
||||
1. 检查 `skill_dirs` 配置是否正确
|
||||
2. 确认目录中存在 `SKILL.md` 文件
|
||||
3. 验证 YAML frontmatter 格式
|
||||
|
||||
```bash
|
||||
# 运行 demo 验证
|
||||
go run ./cmd/skills-demo/main.go
|
||||
```
|
||||
|
||||
### 脚本执行失败
|
||||
|
||||
1. 检查 `sandbox_mode` 配置
|
||||
2. Docker 模式:确认 Docker 服务运行中
|
||||
3. Local 模式:确认解释器已安装
|
||||
4. 检查脚本权限和语法
|
||||
|
||||
### 元数据验证错误
|
||||
|
||||
常见错误:
|
||||
- `skill name too long`: 名称超过 50 字符
|
||||
- `skill name contains invalid characters`: 包含非法字符
|
||||
- `skill name is reserved`: 使用了保留词
|
||||
- `skill description too long`: 描述超过 500 字符
|
||||
|
||||
## 运行 Demo
|
||||
|
||||
```bash
|
||||
cd /path/to/WeKnora
|
||||
go run ./cmd/skills-demo/main.go
|
||||
```
|
||||
|
||||
输出示例:
|
||||
|
||||
```
|
||||
=======================================================================
|
||||
Agent Skills Demo - Progressive Disclosure in Action
|
||||
=======================================================================
|
||||
|
||||
📁 Skills directory: /path/to/WeKnora/examples/skills
|
||||
|
||||
Step 1: Initialize Sandbox Manager
|
||||
---------------------------------------------------
|
||||
✅ Sandbox initialized (type: local)
|
||||
|
||||
Step 2: Initialize Skills Manager
|
||||
---------------------------------------------------
|
||||
✅ Discovered 1 skills
|
||||
|
||||
...
|
||||
|
||||
🎉 Demo completed successfully!
|
||||
```
|
||||
Reference in New Issue
Block a user