---
document_id: agent.dataset.pdd.task.cross_period_products
schema_version: 2
parent_document_id: agent.dataset.pdd
section: capabilities
---

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

# Cross-period product sets / 跨期商品集合

Compare product-ID sets returned by one bundled period call. / 比较一次组合调用返回的两个期间商品 ID 集合。

## 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 products in the first period.
   查询第一个期间的商品。
   - bundle: `period_comparison` (one `query_metrics` call)
   - metrics: `units`
   - 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 products in the second period.
   查询第二个期间的商品。
   - bundle: `period_comparison` (one `query_metrics` call)
   - metrics: `units`
   - 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": "使用 pdd 数据执行跨期商品集合；scope=示例品类，periods={\"first\":{\"start\":\"2025-01-01\",\"end\":\"2025-03-31\"},\"second\":{\"start\":\"2025-04-01\",\"end\":\"2025-06-30\"}}",
  "dataset": "pdd",
  "field": "category_l3",
  "kw": "示例品类",
  "limit": 10
}
```

`query_metrics`

```json
{
  "metrics": [
    "units"
  ],
  "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": "使用 pdd 数据执行跨期商品集合；scope=示例品类，periods={\"first\":{\"start\":\"2025-01-01\",\"end\":\"2025-03-31\"},\"second\":{\"start\":\"2025-04-01\",\"end\":\"2025-06-30\"}}",
  "dataset": "pdd",
  "main_query_name": "query_first_period",
  "additional_queries": [
    {
      "name": "query_second_period",
      "metrics": [
        "units"
      ],
      "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 计算

- `compare_sets` · `set_difference` from `query_first_period`, `query_second_period` — Compute new, missing, and retained product IDs.
  计算新增、消失和持续存在的商品 ID。
  - Before computing, require `meta.truncated=false` from every source query; stop if any source is truncated.
  - 计算前必须确认每个来源查询均为 `meta.truncated=false`；任一来源被截断时立即停止。

## Output requirements / 输出要求

- State period direction and list exact product IDs, titles, and canonical URLs.
  说明期间方向并列出精确商品 ID、标题和标准链接。

## Limitations / 限制

- Absence means no returned units in the queried data, not a launch claim.
  未出现仅表示查询数据中无销量，不代表新品上市结论。
- The comparison requires complete source queries; use each response's meta.truncated flag as the source of truth.
  集合比较要求来源查询完整；以每个响应的 meta.truncated 标记为唯一判断依据。

## Stop conditions / 停止条件

- Stop when the periods or scope are not comparable.
  期间或范围不可比时停止。
- Stop and report truncation when either period response has meta.truncated=true.
  任一期间响应的 meta.truncated=true 时停止并说明结果被截断。