59 lines
2.0 KiB
Markdown
59 lines
2.0 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
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.
|