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

name, description, triggers, tools

name	description	triggers	tools
report-distribution-agent	报告分发 Agent - 自动化报告生成、格式转换和多渠道分发	报告分发 自动发送 邮件报告 定时报告 报告模板 通知分发	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: 数据收集

# 从数据源提取数据
extract_data --source $DATA_SOURCE --query $QUERY --output data.json

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

Step 2: 模板渲染

# 渲染报告模板
render_template \
  --template report-template.md \
  --data data.json \
  --output report.md

Step 3: 格式转换

# 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: 分发

# 发送邮件
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

报告模板系统

模板定义

# 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 模板示例

# 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 调度

# 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

事件触发

# 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 集成

# 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

错误处理

发送失败重试

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)  # 指数退避

数据源故障

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)
• 发送时间符合调度
• 审计日志记录