Initial Daily Campaign Agent release

2026-09-16 21:00:13 +08:00
commit 14fc94b3f0
86 changed files with 10766 additions and 0 deletions
@@ -0,0 +1,139 @@
+# Input and KPI contract
+
+Use this reference when a report is new, its schema is unfamiliar, or KPI maturity
+and targets have not already been confirmed.
+
+## 1. Identify the reporting grain
+
+Determine whether each row represents a date, account, Campaign, Ad Group, Ad,
+creative, country, placement, or a combination. Preserve the full parent-child path.
+Do not aggregate rows across accounts, currencies, timezones, attribution definitions,
+or materially different objectives without explicit normalization.
+
+Prefer stable IDs at every available level over display names. If only names exist,
+disclose collision and rename risk. Detect whether blank Campaign or Ad Group cells
+mean a visually merged/continued parent; forward-fill only inside the current date and
+parent block, then reset at boundaries.
+
+Identify parent totals, subtotals, and leaf rows. Aggregate from one consistent grain,
+normally the finest trustworthy Ad rows. Never sum a Campaign/Ad Group total together
+with its children. Reconcile leaf totals to exported parents when both are available.
+
+## 2. Map fields by meaning, not spelling
+
+Map the available fields to these roles:
+
+- dimensions: date, account, Campaign ID/name, Ad Group ID/name, Ad ID/name, status,
+  objective, country, platform;
+- delivery: budget, daily spend/pacing target, spend, impressions, reach, clicks,
+  installs, conversions, revenue;
+- quality/outcomes: retained users, purchases, qualified leads, downstream events;
+- ratios: CPM, CPC, CPI, CPA, CTR, CVR, retention, ROAS;
+- context: currency, timezone, attribution window, cohort eligibility, data watermark,
+  launch date, intervention timestamps, and an intervention/change log.
+
+Column aliases vary by platform and language. Never decide that a similarly named
+field is equivalent when its denominator, attribution window, or cohort definition is
+unclear. Show the proposed mapping for material fields.
+
+When numerator and denominator are present, compute the aggregate ratio from them and
+use the exported ratio only as a cross-check. If only a precomputed ratio is present,
+state that weighted aggregation may be impossible.
+
+## 3. Confirm the KPI contract
+
+For each decision-relevant KPI, capture:
+
+| Field | Meaning |
+|---|---|
+| Role | Primary KPI, secondary KPI, or hard guardrail |
+| Formula | Numerator, denominator, and eligible population |
+| Direction | Lower-is-better, higher-is-better, or bounded range |
+| Target | Business threshold and optional tolerance |
+| Scope | Global, account, objective, product, geo, or Campaign-specific |
+| Attribution | Click/view window and event definition |
+| Maturity lag | When a cohort is complete enough to judge |
+| Minimum sample | Spend, clicks, installs, conversions, or eligible cohort |
+
+KPI targets may differ across Campaigns, Ad Groups, or Ads. Apply the narrowest
+confirmed target matching the row and display which target was used.
+
+Treat spend/pacing as its own contract:
+
+| Field | Meaning |
+|---|---|
+| Scope | Portfolio/account, platform, Campaign, or Ad Group |
+| Period | Daily, weekly, flight-to-date, or another pacing window |
+| Target type | Minimum delivery, desired level, maximum cap, or range |
+| Target value | Amount and currency |
+| Allocation rule | Whether and where incremental spend may be assigned |
+
+Compute target attainment and gap/overage at the configured scope. A minimum daily
+spend goal does not override efficiency or quality guardrails. Report the numerical
+shortfall, but do not automatically distribute it to weak Ads.
+
+If any field needed for a verdict is missing, ask a concise question. A useful form is:
+
+> 请确认主要 KPI、目标值和方向；日消耗目标的作用范围；每个滞后指标最晚成熟到哪一天；是否有最低样本门槛或分层目标？
+
+Do not infer a business target from industry benchmarks, historical averages, file
+names, source code, or another user's configuration.
+
+## 4. Capture intervention history
+
+When the question involves scaling, sudden deterioration, rollback, a former winner,
+or a restructured Campaign, capture each known manual or automated change:
+
+| Field | Meaning |
+|---|---|
+| Timestamp | Effective time in the reporting timezone |
+| Entity path | Campaign, Ad Group, or Ad and stable ID |
+| Change type | Budget, bid, targeting, word pack, match type, creative, status, structure, tracking, or platform automation |
+| Before / after | Previous and new value or configuration |
+| Reason | Operator hypothesis or system trigger, if known |
+| Expected maturity | First cohort/date on which the change can be judged |
+
+Keep budget, configured caps, and observed spend distinct. A spend plateau or jump can
+suggest a delivery phase, but it does not prove that the budget changed. When the file
+contains spend but no budget history, label any inferred phase boundary as an
+inference and ask for the change log only if it could materially alter the action.
+
+If there is no formal log, accept dated operator statements as declared context and
+mark their provenance. Do not silently turn an approximate recollection into an exact
+timestamp.
+
+## 5. Resolve metric-specific mature dates
+
+Let each KPI have its own latest mature date `D_metric`. Examples:
+
+- spend, impressions, and clicks may mature on the latest complete reporting day;
+- installs or purchases may require an attribution delay;
+- D1 retention for an August 23 cohort cannot be treated as mature until its defined
+  next-day observation is complete, so its latest usable cohort may be August 22;
+- D7 retention and revenue windows may lag further.
+
+Report `D_metric` beside the KPI. Build recent and prior windows relative to that
+metric's mature date. Do not compare an immature value with a mature target.
+
+If maturity cannot be established, present the value as provisional and exclude it
+from strong intervention claims.
+
+## 6. Data-quality checks
+
+Before interpretation, check:
+
+- missing or duplicated entity-date rows;
+- inconsistent date formats, timezones, currencies, or units;
+- blanks confused with zero;
+- zero delivery versus absent ingestion;
+- totals mixed with detail rows;
+- hierarchy blanks incorrectly treated as missing parents or forwarded across blocks;
+- parent totals double-counted with Ad Group/Ad detail;
+- negative or impossible counts and rates;
+- spend with missing outcomes after the expected maturity lag;
+- abrupt schema, tracking, attribution, or target changes;
+- known intervention dates missing from the export or conflicting with delivery;
+- insufficient history for complete 7D/14D comparisons.
+
+Do not silently discard questionable rows. Quantify affected spend and Campaigns when
+possible, and decide whether the issue blocks only one KPI or the whole report.