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

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

## 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 时停止并说明结果被截断。