---
document_id: agent.dataset.jd.task.category_product_ranking
schema_version: 1
---

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

# Category product ranking / 品类商品排名

Rank exact product IDs within a resolved category and time range.

在已对齐的品类和时间范围内对精确商品 ID 排名。

## Required inputs / 必要输入

- `category` — `search_values`; required (`category_l3`): Exact category value
  精确品类值
- `time` — `user_required`; required: Analysis time range
  分析时间范围
- `ranking_metric` — `user_required`; optional; default `gmv`; allowed: `gmv, units`: Metric used to rank products
  商品排名所用指标
- `top_n` — `user_required`; optional; default `20`: Number of products to return
  返回商品数量

## Steps / 步骤

1. `resolve_category` · `search_values` — Resolve the category value.
   对齐品类值。
   - search `category_l3` with `${category}`
2. `query_products` · `query_metrics` — Query and order products by the requested metric.
   查询商品并按用户要求的指标排序。
   - metrics: `gmv`, `units`
   - group_by: `product_id`, `title`, `product_url`
   - result entity: `product`
   - filters: `category_l3 eq ${category}`
   - time: `${time}`
   - order_by: `${ranking_metric}` desc
   - limit: `${top_n}`

## Agent computation / Agent 计算

- `rank_products` · `rank` from `query_products` — Preserve the server ordering and requested limit.
  保留服务端排序和用户要求的数量限制。

## Output requirements / 输出要求

- Return product IDs, titles, canonical URLs, and the values used for ranking.
  返回商品 ID、标题、标准链接和用于排名的指标值。

## Limitations / 限制

- Product titles are not available for fuzzy resolution.
  不支持通过商品标题进行模糊解析。

## Stop conditions / 停止条件

- Stop if the category cannot be resolved exactly.
  无法精确对齐品类时停止。