---
document_id: agent.dataset.tmall.task.product_contribution
schema_version: 2
parent_document_id: agent.dataset.tmall
section: capabilities
---

<!-- 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`

## Call example / 调用示例

Replace the example values with exact user inputs or values returned by `search_values`. / 将示例值替换为用户的精确输入或 `search_values` 返回的平台原始值。

`search_values`

```json
{
  "task_query": "使用 tmall 数据执行商品变化贡献；scope=示例品类，periods={\"first\":{\"start\":\"2025-01-01\",\"end\":\"2025-03-31\"},\"second\":{\"start\":\"2025-04-01\",\"end\":\"2025-06-30\"}}",
  "dataset": "tmall",
  "field": "category_l3",
  "kw": "示例品类",
  "limit": 10
}
```

`query_metrics`

```json
{
  "metrics": [
    "gmv"
  ],
  "time": {
    "start": "2025-01-01",
    "end": "2025-03-31"
  },
  "group_by": [
    "product_id",
    "title",
    "product_url"
  ],
  "filters": [
    {
      "field": "category_l3",
      "op": "eq",
      "value": "示例品类"
    }
  ],
  "limit": 1000,
  "task_query": "使用 tmall 数据执行商品变化贡献；scope=示例品类，periods={\"first\":{\"start\":\"2025-01-01\",\"end\":\"2025-03-31\"},\"second\":{\"start\":\"2025-04-01\",\"end\":\"2025-06-30\"}}",
  "dataset": "tmall",
  "main_query_name": "query_first_period",
  "additional_queries": [
    {
      "name": "query_second_period",
      "metrics": [
        "gmv"
      ],
      "time": {
        "start": "2025-04-01",
        "end": "2025-06-30"
      },
      "group_by": [
        "product_id",
        "title",
        "product_url"
      ],
      "filters": [
        {
          "field": "category_l3",
          "op": "eq",
          "value": "示例品类"
        }
      ],
      "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 时停止并说明结果被截断。