---
document_id: agent.dataset.tmall.task.product_contribution
schema_version: 1
---

<!-- Generated by scripts.build_agent_guide; do not edit. -->

# Product contribution to change / 商品变化贡献

Attribute cross-period GMV change from two product-level atomic queries.

通过两次商品级原子查询归因跨期销售额变化。

## Required inputs / 必要输入

- `scope` — `search_values`; required (`category_l3`): Exact category scope
  精确品类范围
- `periods` — `user_required`; required: Two comparable periods
  两个可比较期间

## Steps / 步骤

1. `resolve_scope` · `search_values` — Resolve the category value.
   对齐品类值。
   - search `category_l3` with `${scope}`
2. `query_first_period` · `query_metrics` — Query product GMV in the first period.
   查询第一个期间的商品销售额。
   - bundle: `contribution_periods` (one `query_metrics` call)
   - metrics: `gmv`
   - group_by: `product_id`, `title`, `product_url`
   - result entity: `product`
   - filters: `category_l3 eq ${scope}`
   - time: `${periods.first}`
   - limit: `1000`
3. `query_second_period` · `query_metrics` — Query product GMV in the second period.
   查询第二个期间的商品销售额。
   - bundle: `contribution_periods` (one `query_metrics` call)
   - metrics: `gmv`
   - group_by: `product_id`, `title`, `product_url`
   - result entity: `product`
   - filters: `category_l3 eq ${scope}`
   - time: `${periods.second}`
   - limit: `1000`

## Agent computation / Agent 计算

- `compute_contribution` · `contribution` from `query_first_period`, `query_second_period` — Join by product ID, subtract periods, and rank contributions.
  按商品 ID 连接、计算期间差值并排序贡献。
  - Before computing, require `meta.truncated=false` from every source query; stop if any source is truncated.
  - 计算前必须确认每个来源查询均为 `meta.truncated=false`；任一来源被截断时立即停止。

## Output requirements / 输出要求

- Show product IDs, titles, canonical URLs, deltas, and contribution to total change.
  展示商品 ID、标题、标准链接、变化量及其对总变化的贡献。

## Limitations / 限制

- Contribution is arithmetic attribution, not causal inference.
  贡献度是算术归因，不是因果推断。
- Attribution requires complete source queries; use each response's meta.truncated flag as the source of truth.
  归因要求来源查询完整；以每个响应的 meta.truncated 标记为唯一判断依据。

## Stop conditions / 停止条件

- Stop when periods or filters differ.
  两个期间或筛选条件不一致时停止。
- Stop and report truncation when either period response has meta.truncated=true.
  任一期间响应的 meta.truncated=true 时停止并说明结果被截断。