Agent Skills 最佳实践

---
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.
---

---
name: PDF Processing
description: Handles PDF files.
---

# Skill Name

## 快速开始

### 基本用法
步骤 1：准备工作
步骤 2：执行任务

### 高级用法
步骤 1：配置选项
步骤 2：优化性能

## 最佳实践

### 性能优化
- 建议 1
- 建议 2

### 错误处理
- 常见错误及解决方案

## 示例：提取 PDF 文本

```python
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    for page in pdf.pages:
        text = page.extract_text()
        print(text)
```

**输出**：
```
Page 1 content here...
```

## 示例
使用相关库读取 PDF 文件并提取内容。

# PDF Processing

## 快速开始

提取 PDF 文本：
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## 高级功能

需要表单填写？查看 [FORMS.md](FORMS.md)
需要 PDF 合并？查看 [MERGE.md](MERGE.md)

## 数据验证

使用验证脚本确保数据格式正确：

```bash
python scripts/validate.py data.json
```

脚本会检查：
- JSON 格式有效性
- 必需字段存在
- 数据类型正确

## 限制

本 Skill 有以下限制：
- 不支持网络请求
- 仅支持预安装的 Python 包
- 最大文件大小：10MB
- 支持的格式：PDF, DOCX, TXT

## 常见问题

### 问题：文件过大导致处理失败

**症状**：Error: File size exceeds limit

**解决方案**：
```python
# 分批处理大文件
def process_large_file(filepath, chunk_size=1000):
    with open(filepath, 'r') as f:
        while True:
            chunk = f.read(chunk_size)
            if not chunk:
                break
            process_chunk(chunk)
```

# Skill Name

## 最简单的用例
一行代码完成基本任务：
```python
result = simple_function(input)
```

## 常见场景
添加错误处理和选项：
```python
try:
    result = function(input, option=True)
except Exception as e:
    handle_error(e)
```

## 高级用法
详见 [ADVANCED.md](ADVANCED.md)

## 常用模式

### 模式 1：批量处理
```python
def batch_process(items):
    results = []
    for item in items:
        result = process_item(item)
        results.append(result)
    return results
```

### 模式 2：错误重试
```python
def retry_operation(func, max_attempts=3):
    for attempt in range(max_attempts):
        try:
            return func()
        except Exception as e:
            if attempt == max_attempts - 1:
                raise e
            time.sleep(2 ** attempt)
```

## 使用场景

### 场景 1：客户支持
自动分类和路由客户邮件

```python
email_category = classify_email(email_content)
if email_category == "billing":
    route_to_billing_team(email)
elif email_category == "technical":
    route_to_tech_support(email)
```

### 场景 2：内容审核
检测和标记不适当内容

```python
moderation_result = moderate_content(user_post)
if moderation_result["flagged"]:
    notify_moderators(user_post, moderation_result["reasons"])
```

## 完整示例：PDF 报告生成

```python
from reportlab.lib.pagesizes import letter
from reportlab.pdfgen import canvas

def generate_report(data, output_path):
    """生成 PDF 报告
    
    Args:
        data: 报告数据字典
        output_path: 输出文件路径
    
    Returns:
        str: 生成的文件路径
    """
    c = canvas.Canvas(output_path, pagesize=letter)
    
    # 添加标题
    c.setFont("Helvetica-Bold", 16)
    c.drawString(100, 750, data["title"])
    
    # 添加内容
    c.setFont("Helvetica", 12)
    y_position = 700
    for item in data["items"]:
        c.drawString(100, y_position, item)
        y_position -= 20
    
    c.save()
    return output_path

# 使用示例
report_data = {
    "title": "Monthly Sales Report",
    "items": [
        "Total Sales: $50,000",
        "New Customers: 120",
        "Growth Rate: 15%"
    ]
}

output_file = generate_report(report_data, "report.pdf")
print(f"报告已生成：{output_file}")
```

## 验证结果

完成操作后，验证结果：

```python
# 1. 检查文件是否创建
assert os.path.exists(output_file), "输出文件未创建"

# 2. 验证文件大小
file_size = os.path.getsize(output_file)
assert file_size > 0, "输出文件为空"

# 3. 验证内容
with open(output_file, 'r') as f:
    content = f.read()
    assert "expected_content" in content, "内容验证失败"

print("✅ 所有验证通过")
```

## 性能优化

### 大文件处理
处理大文件时使用流式处理：

```python
# ❌ 不推荐：一次性加载
with open('large_file.txt', 'r') as f:
    content = f.read()  # 可能耗尽内存
    process(content)

# ✅ 推荐：流式处理
with open('large_file.txt', 'r') as f:
    for line in f:  # 逐行处理
        process(line)

# ❌ 不推荐：逐个处理
for item in items:
    database.insert(item)  # 多次数据库连接

# ✅ 推荐：批量插入
database.bulk_insert(items)  # 一次连接