Daily-Campaign-Agent/.agents/skills/daily-campaign-triage/references/script-usage.md

Script usage

The scripts are deterministic helpers. They prepare evidence and render the final artifact; the Skill instructions still own KPI confirmation, interpretation, and action judgment.

1. Normalize a report

python3 scripts/analyze_report.py report.xlsx \
  --analysis-date 2026-08-25 \
  --retention-lag-days 1 \
  --output /tmp/report.analysis.json

Supported inputs are .xlsx, .csv, and .tsv. The analyzer uses the first sheet by default. Use --sheet SHEET_NAME to select another sheet. It recognizes common English and Chinese names for date, Campaign, Ad Group, Ad, spend, installs, and D1 retained users. If the export differs, pass a JSON mapping:

{
  "date": "统计日期",
  "campaign": "系列",
  "ad_group": "广告组",
  "ad": "广告",
  "spend": "花费 USD",
  "installs": "安装",
  "retained": "D1 用户"
}

The evidence JSON deliberately contains no KPI verdict or action. Ratios are always recomputed from summed components. Retention windows end on the explicit mature date; acquisition windows end on the analysis date.

2. Apply the decision framework

Read the evidence JSON, confirm the user's KPI card and pacing card, then fill a brief JSON matching examples/brief.example.json. Do not mechanically classify Ads from a single ratio. Use sample, persistence, trend, maturity, learning stage, recent changes, and budget impact as required by the Skill.

3. Build the Word brief

python3 scripts/build_brief.py /tmp/brief.json \
  --output ./output/2026-08-25-campaign-triage.docx

The renderer enforces the stable tier names and rejects forbidden daily-brief sections such as Campaign ranking, 核心判断, and stale named-Ad drilldowns. It uses only three visual colors and lets tables flow naturally without forced section page breaks.

Output safety

Write temporary analysis JSON and generated briefs outside the repository. Never add the user's source workbook or a real advertiser name to examples, fixtures, or assets.