zclaw_openfang/skills/report-distribution-agent/SKILL.md

---
name: report-distribution-agent
description: "报告分发 Agent - 自动化报告生成、格式转换和多渠道分发"
triggers:
  - "报告分发"
  - "自动发送"
  - "邮件报告"
  - "定时报告"
  - "报告模板"
  - "通知分发"
tools:
  - bash
  - read
  - write
  - grep
  - glob
---

# Report Distribution Agent - 报告分发 Agent

自动化报告生成、格式转换和多渠道分发的智能 Agent，确保报告按时、准确地送达目标受众。

## 能力

- **报告生成**: 从数据源自动生成结构化报告
- **格式转换**: PDF、HTML、Markdown、Excel 等格式互转
- **多渠道分发**: 邮件、Slack、Webhook、文件系统等
- **定时调度**: Cron 表达式驱动的定时报告任务
- **模板管理**: 报告模板创建、版本控制、动态渲染

## 工具依赖

- bash: 执行生成命令、调度任务
- read: 读取数据源、模板文件
- write: 输出报告、配置文件
- grep: 搜索报告内容、模板变量
- glob: 查找报告文件、模板

## 分发渠道矩阵

| 渠道 | 协议 | 适用场景 |
|------|------|----------|
| Email | SMTP | 正式报告、外部分发 |
| Slack | Webhook | 团队通知、快速更新 |
| Teams | Webhook | 企业内部通知 |
| S3/MinIO | S3 API | 大文件归档 |
| Webhook | HTTP POST | 自定义集成 |
| FileSystem | Local | 本地存储 |

## 报告生成流程

### Step 1: 数据收集
```bash
# 从数据源提取数据
extract_data --source $DATA_SOURCE --query $QUERY --output data.json

# 验证数据完整性
validate_data --input data.json --schema report-schema.json
```

### Step 2: 模板渲染
```bash
# 渲染报告模板
render_template \
  --template report-template.md \
  --data data.json \
  --output report.md
```

### Step 3: 格式转换
```bash
# Markdown -> PDF
pandoc report.md -o report.pdf --pdf-engine=wkhtmltopdf

# Markdown -> HTML
pandoc report.md -o report.html --standalone

# Data -> Excel
generate_excel --data data.json --template excel-template.xlsx --output report.xlsx
```

### Step 4: 分发
```bash
# 发送邮件
send_email \
  --to recipients.txt \
  --subject "Daily Report $(date +%Y-%m-%d)" \
  --body report.html \
  --attachments report.pdf,report.xlsx

# 发送 Slack 通知
send_slack \
  --webhook $SLACK_WEBHOOK \
  --message "Daily report ready" \
  --file report.pdf
```

## 报告模板系统

### 模板定义
```yaml
# report-template.yaml
name: "Daily Sales Report"
version: "1.0.0"
schedule: "0 9 * * *"  # 每天 9:00

data_sources:
  - name: sales_data
    type: sql
    connection: $DB_CONNECTION
    query: |
      SELECT date, product, quantity, revenue
      FROM sales
      WHERE date = CURRENT_DATE - 1

  - name: metrics
    type: api
    url: $METRICS_API/daily
    method: GET

template:
  engine: handlebars
  file: templates/daily-sales.md.hbs

output:
  formats:
    - pdf
    - excel
  filename: "sales-report-{{date}}"

distribution:
  email:
    to: ["sales-team@company.com"]
    subject: "Daily Sales Report - {{date}}"
  slack:
    channel: "#sales-reports"
    message: "Daily sales report for {{date}} is ready"
```

### Handlebars 模板示例
```handlebars
# Daily Sales Report - {{formatDate date "YYYY-MM-DD"}}

## Summary
- Total Revenue: {{formatCurrency summary.totalRevenue}}
- Orders: {{summary.orderCount}}
- Avg Order Value: {{formatCurrency summary.avgOrderValue}}

## Top Products
| Product | Quantity | Revenue |
|---------|----------|---------|
{{#each topProducts}}
| {{name}} | {{quantity}} | {{formatCurrency revenue}} |
{{/each}}

## Trends
{{#if trends.growth}}
Revenue is up {{trends.growth}}% compared to yesterday.
{{else}}
Revenue is down {{trends.decline}}% compared to yesterday.
{{/if}}

---
Generated by Report Distribution Agent at {{formatDate now "YYYY-MM-DD HH:mm:ss"}}
```

## 调度配置

### Cron 调度
```toml
# scheduler.toml
[[jobs]]
name = "daily-sales-report"
cron = "0 9 * * *"
timezone = "Asia/Shanghai"
enabled = true

[[jobs]]
name = "weekly-summary"
cron = "0 9 * * 1"  # 每周一 9:00
timezone = "Asia/Shanghai"
enabled = true

[[jobs]]
name = "monthly-analytics"
cron = "0 9 1 * *"  # 每月 1 日 9:00
timezone = "Asia/Shanghai"
enabled = true
```

### 事件触发
```yaml
# event-triggers.yaml
triggers:
  - name: "on-deal-closed"
    event: "deal.closed"
    condition: "deal.value > 100000"
    report: "deal-summary"

  - name: "on-alert-threshold"
    event: "metric.threshold"
    condition: "metric.name == 'revenue' and metric.breach == 'down'"
    report: "revenue-alert"
```

## ZCLAW 集成

```toml
# hands/report-distributor.toml
[hand]
name = "report-distributor"
version = "1.0.0"
trigger = "scheduled"
auto_approve = false

[hand.config]
templates_dir = "~/.zclaw/report-templates"
output_dir = "~/.zclaw/reports"
max_concurrent = 5

[hand.distribution]
default_channel = "email"
fallback_channel = "slack"

[hand.logging]
audit_enabled = true
retention_days = 90
```

## 错误处理

### 发送失败重试
```python
async def distribute_report(report: Report, channels: List[Channel]):
    for channel in channels:
        for attempt in range(3):
            try:
                await send_to_channel(report, channel)
                log_success(report.id, channel.name)
                break
            except ChannelError as e:
                if attempt == 2:
                    log_failure(report.id, channel.name, e)
                    notify_admin(f"Report {report.id} failed to {channel.name}")
                else:
                    await asyncio.sleep(2 ** attempt)  # 指数退避
```

### 数据源故障
```python
def handle_data_source_failure(source: DataSource):
    # 使用缓存数据
    cached = load_cached_data(source.name)
    if cached:
        return cached

    # 生成降级报告
    return generate_degraded_report(source.name)
```

## 协作触发

当以下情况时调用其他 Agent:
- **Data Consolidation Agent**: 需要整合多数据源
- **Sales Data Extraction Agent**: 需要提取销售数据
- **Analytics Reporter**: 需要分析报告数据
- **Support Responder**: 分发失败需要通知

## 成功指标

- 报告按时发送率 > 99.9%
- 分发成功率 > 99.5%
- 格式转换准确率 100%
- 平均分发延迟 < 5s
- 错误自动恢复率 > 90%

## 关键规则

1. 报告必须按计划准时发送
2. 发送失败必须自动重试 3 次
3. 敏感数据必须加密传输
4. 大文件必须压缩后发送
5. 所有分发操作必须记录审计日志
6. 收件人列表必须可配置

## 分发清单

- [ ] 数据源连接验证
- [ ] 模板变量填充完整
- [ ] 格式转换正确
- [ ] 收件人列表有效
- [ ] 附件大小合理 (< 25MB)
- [ ] 发送时间符合调度
- [ ] 审计日志记录