SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skills1688-item-selection

1688-item-selection

Office & productivity

View repository

Updated 10-16 06:50

About this skill

1688-item-selection — Merchant Key Product Selection

Skill Overview

Intelligently identifies products that merchants should focus on for operations, performs comprehensive scoring and tiering based on five major dimensions, and outputs a product list; products can also be searched by keyword.

Output Principles：

  • Only output the product list (product name, ID, tags, reason for selection)
  • Do not display comprehensive scores, do not output optimization actions, do not output action recommendations
  • Product optimization actions are handled by the independent "Product Diagnosis skill"
  • By default, recommend 3 products; users can specify the recommendation quantity (1-10 products)
  • When no key products are selected, merchants can be advised to enter keywords to search for products

Scoring Dimensions

  1. Sales Contribution(30%) - The product's contribution to store GMV and number of buyers
  2. Traffic Efficiency(25%) - Traffic conversion rate, impression conversion, add-to-cart rate
  3. Growth Potential(20%) - Platform tags (excellent product/potential product), growth tiering
  4. Marketing ROI(15%) - Advertising input-output ratio
  5. Product Health(10%) - Service capability, inventory, refund rate

Tiering Standards

  • S-level (≥80 points): Key promotion product - increase investment to seize traffic
  • A-level (60-80 points): Potential cultivation product - targeted optimization of weaknesses
  • B-level (40-60 points): Maintenance operations product - maintain status quo as auxiliary
  • C-level (<40 points): Optimization and adjustment product - diagnose problems and consider delisting

CLI Commands

configure — Configure AK

# 查看 AK 状态
python {baseDir}/cli.py configure
# 设置 AK
python {baseDir}/cli.py configure YOUR_AK

Configure the AK required for gateway authentication. All operation commands depend on the AK, and it must be configured before first use.

get_item_overview — Get product overview statistics

python {baseDir}/cli.py get_item_overview

Returns: total number of products, number of products with sales, total sales amount, total number of buyers, total UV, and the number of products segmented by sales amount.

get_shop_data — Get store-dimension data

python {baseDir}/cli.py get_shop_data

Returns: store payment amount, number of paying buyers, number of online products. Used as the comparison benchmark for product scoring.

score_and_select — Product scoring and selection

python {baseDir}/cli.py score_and_select \
  --shop_total '{"pay_ord_amt_1d_001": 100000, "pay_ord_byr_cnt_1d_001": 50}' \
  --strategy comprehensive \
  --limit 100 \
  --top_n 3

Parameter description:

Parameter Required Description
--shop_total Yes Store-dimension data JSON (obtained by get_shop_data)
--strategy No Query strategy: comprehensive (default) / sales / all
--limit No Maximum number of products to obtain, default 100
--top_n No Output the top N products, default 10

⚠️ Interactive rendering (must be executed): When the data.data.products returned by this command contains ≥2 products,prohibitedOutput product data directly in a Markdown table; it must be rendered through an interactive component:

  1. First read the {baseDir}/references/interaction-specs.md in select_products_from_scoring section to obtain the complete data structure definition of the interactive component
  2. Then trigger the metadata.interactions declared in select_products_from_scoring interaction, and construct the parameters strictly according to the field mapping in specs

search_offer_by_keyword — Search store products by keyword

python {baseDir}/cli.py search_offer_by_keyword --keyword "测试" --page 1 --page_size 10

Parameter description:

Parameter Required Description
--keyword No Search keyword (optional). If there are no results after passing in the keyword,have the large model try several short similar words to search, with a maximum of 3 attempts
--page No Page number, default 1
--page_size No Number per page, default 10

⚠️ Interactive rendering (must be executed): When the data.data.items returned by this command contains ≥2 products,it is prohibitedto output product data directly in a Markdown table; it must be rendered through an interactive component:

  1. First read the {baseDir}/references/interaction-specs.md in select_products_from_search section to obtain the complete data structure definition of the interactive component
  2. Then trigger the metadata.interactions declared in select_products_from_search interaction, and construct the parameters strictly according to the field mapping in specs

Generation process

Step 1: Collect information

Obtain the following information from the user:

  1. Recommendation quantity(optional): the number of products to recommend, default 3
  2. Filter conditions(optional): category scope, product quantity limits, etc.

Step 2: Query overview data (can be executed in parallel)

python {baseDir}/cli.py get_item_overview
python {baseDir}/cli.py get_shop_data

Determine the next query strategy based on the total number of products in the overview results:

  • ≤200 products: Use --strategy all to query all directly
  • 201-500 products: Use --strategy comprehensive default filtering
  • >500 products: Use --strategy comprehensive --limit 200 to limit the quantity

Step 3: Scoring and selection

Pass the store data obtained in Step 2 through --shop_total into the scoring command:

python {baseDir}/cli.py score_and_select \
  --shop_total '{第2步返回的店铺数据 JSON}' \
  --strategy <策略> \
  --limit <N> \
  --top_n <推荐数量>

Step 4: Generate report and interactive selection

Based on the scoring results, sort by overall score from highest to lowest, select the top N products (default 3), and output a structured Markdown report.

Interaction trigger: When the selection result contains multiple products (≥2), while outputting the Markdown report, call show_interaction and set name='select_products_from_scoring', and map the score_and_select array returned by products to the interaction data slots, allowing the user to check the products to focus on operating through the table. For the specific field mapping rules and component rendering data structure, refer to the references/interaction-specs.md section corresponding to the interaction.

Report template

# 重点品圈选结果

基于{策略总结}，推荐以下 {N} 款商品：

1. **{商品标题}** (ID: {item_id}) —— 【{商品标签}】
    - {选择原因，1-2句话说明核心数据和优势}

2. **{商品标题}** (ID: {item_id}) —— 【{商品标签}】
    - {选择原因}

3. ...

Format requirements：

  • Product tags: Label roles based on product characteristics, such as traffic-driving item, profit item, potential item, bestseller, actively selling item, etc.
  • Reason for selection: 1-2 sentences explaining the core data and advantages
  • Prohibited content: Do not display the overall score, do not output optimization actions, and do not output action recommendations

Interaction Capabilities

This Skill supports providing a visualized table selection experience through the Newton Agent's client interaction component when outputting multiple products.

Trigger Rules

Interaction Name Trigger Timing Data Source
select_products_from_scoring score_and_select When ≥2 products are returned score_and_select The returned products array
select_products_from_search search_offer_by_keyword When ≥2 products are returned search_offer_by_keyword The returned items array

Data Filling

  • select_products_from_scoring: Set title as the table title,columns as the column definition array, and convert each item of the score_and_select returned data.data.products array and assign it to the rows slot. Each row must contain id、title、level、levelName、totalScore、payAmount、buyerCount、uv。
  • select_products_from_search: Set title as the table title,columns as the column definition array, and convert each item of the search_offer_by_keyword returned data.data.items array and assign it to the rows slot. Each row must contain id(source field itemId）、title、imageUrl(source field mainImage）、minPrice、maxPrice、status。

For the specific field mapping rules and component rendering data structure, please refer to references/interaction-specs.md the chapter corresponding to the interaction in

Notes

  • Before calling a table type interaction, be sure to ensure that rows has real data, otherwise the frontend will report an error
  • When the result contains only 1 product, there is no need to trigger the interaction; simply output the Markdown report
  • The interaction component and the Markdown report can be output at the same time without conflict

Security Statement

Risk Level Command Agent Behavior
Read-only configure Can be executed directly, no confirmation required
Read-only get_item_overview Can be executed directly, no confirmation required
Read-only get_shop_data Can be executed directly, no confirmation required
Read-only score_and_select Can be executed directly, no confirmation required
Read-only search_offer_by_keyword Can be executed directly, no confirmation required

Exception Handling

When any command outputs success: false :

  1. First output the markdown field(already contains a user-readable error description)
  2. Then append guidance based on keywords：
markdown keyword Additional Agent Action
"AK not configured" or "invalid signature" or "401" Prompt the user to provide a valid AK or check the authentication configuration and retry
"rate limited" or "429" Suggest the user wait 1-2 minutes and retry
Other Just output markdown

Environment Variables (.env)

Variable Default Value Description
SKILL_NAME 1688-item-selection skill name
SKILL_VERSION 1.0.0 skill version number
SKILL_CHANNEL clawhub release channel

Tracking Reporting

Each time a CLI command is executed, a call record is automatically reported to the skill gateway, used to count the number of skill calls.

Output Format

Uses standard JSON output:

{
  "success": true,
  "markdown": "商品评分与圈选成功",
  "data": {
    "data": {
      "total_scored": 50,
      "returned_count": 3,
      "products": [...],
      "summary": {"S级": 2, "A级": 5, "B级": 20, "C级": 23}
    }
  }
}

Scoring Rules

For detailed scoring rules and weight descriptions, see scoring_rules.md。

Data Table Schema

For data table field definitions, see table_schema.md。

Usage Principles

  1. Must query real data: Obtain real data through CLI commands; do not fabricate
  2. The overview and shop data scripts can be executed in parallel to improve efficiency
  3. Determine the detail query strategy based on the number of products in the overview results
  4. This skill is a read-only operation and will not modify any data

Disclaimer:

1. You understand and agree that the skill's execution results and output content may vary or contain hallucinations depending on the applicable AI agent and large model. Please verify important information. 2. You should properly safeguard your Access Key (AK), which is your identity credential for running the 1688 skill. Do not provide it to third parties to avoid losses caused by leakage of identity credentials. 3. When you download and install the 1688 skill to run it, you should always keep it intact and must not alter the skill's code, related files, or other content without authorization; otherwise, 1688 will not bear any legal liability for the skill's execution results and output content. 4. Due to limitations in current technological development, we cannot guarantee the accuracy, authenticity, or timeliness of all the skill's execution results and output content, nor do they represent our stance, views, or recommendations. Please carefully verify the skill's execution results and output content. Except in scenarios where we are legally required to bear compensation liability, we do not bear other compensation liabilities.