文件内容
SKILL.md
---
name: 1688-item-selection
description: |
1688 商家重点品圈选 —— 基于多维度商品评分智能识别值得重点运营的商品或搜索商品。
工具能力：五维度评分（销售贡献、流量效率、成长潜力、营销ROI、商品健康度），商品分层（S/A/B/C级），搜索商品。
触发词：重点品查看、圈选重点品、圈选运营商品、今日运营重点、选品、推荐商品、商品分层、商品优先级、搜索商品。
metadata:
openclaw:
emoji: "🎯"
requires:
bins:
- python
interactions:
- name: select_products_from_scoring
type: table
selectionType: product
description: "从评分圈选结果中选择要重点运营的商品"
required_data:
title: "表格标题，固定为'重点品圈选结果'"
columns: "列定义数组，包含商品ID、标题、等级、分层、综合得分、支付金额、买家数、访客数"
rows: "数据行数组，每行包含 id, title, level, levelName, totalScore, payAmount, buyerCount, uv"
totalCount: "数据总条数"
- name: select_products_from_search
type: table
selectionType: product
description: "从关键词搜索结果中选择商品"
required_data:
title: "表格标题，如'搜索结果: {keyword}'"
columns: "列定义数组，包含图片、商品ID、标题、最低价、最高价、状态"
rows: "数据行数组，每行包含 id, title, imageUrl, minPrice, maxPrice, status"
totalCount: "数据总条数"
---
# 1688-item-selection — 商家重点品圈选
## 技能概述
智能识别商家应该重点运营的商品，基于五大维度进行综合评分和分层，输出商品清单；也可以通过关键词搜索商品。
**输出原则**：
- 仅输出商品清单（商品名称、ID、标签、选择原因）
- 不展示综合得分、不输出优化动作、不输出行动建议
- 商品优化动作由独立的"商品诊断skill"负责
- 默认推荐 3 款商品，用户可指定推荐数量（1-10 款）
- 当没有圈出重点商品时可以建议商家输入关键词搜索商品
## 评分维度
1. **销售贡献度**（30%）- 商品对店铺GMV和买家数的贡献
2. **流量效率**（25%）- 流量转化率、曝光转化、加购率
3. **成长潜力**（20%）- 平台标签（优品/潜力品）、成长分层
4. **营销ROI**（15%）- 广告投入产出比
5. **商品健康度**（10%）- 服务能力、库存、退款率
## 分层标准
- **S级（≥80分）**：重点推广品 - 加大投入抢占流量
- **A级（60-80分）**：潜力培育品 - 针对性优化短板
- **B级（40-60分）**：维持运营品 - 保持现状作为辅助
- **C级（<40分）**：优化调整品 - 诊断问题考虑下架
## CLI 命令
### configure — 配置 AK
```bash
# 查看 AK 状态
python {baseDir}/cli.py configure
# 设置 AK
python {baseDir}/cli.py configure YOUR_AK
```
配置网关鉴权所需的 AK。所有操作命令都依赖 AK，首次使用前需先配置。
### get_item_overview — 获取商品概览统计
```bash
python {baseDir}/cli.py get_item_overview
```
返回：商品总数、有销售商品数、总销售额、总买家数、总UV，以及按销售额分段的商品数量。
### get_shop_data — 获取店铺维度数据
```bash
python {baseDir}/cli.py get_shop_data
```
返回：店铺支付金额、支付买家数、在线商品数。用作商品评分的对比基准。
### score_and_select — 商品评分与圈选
```bash
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
```
参数说明：
| 参数 | 必填 | 说明 |
|------|------|------|
| `--shop_total` | 是 | 店铺维度数据 JSON（由 get_shop_data 获取） |
| `--strategy` | 否 | 查询策略: comprehensive(默认) / sales / all |
| `--limit` | 否 | 获取商品数量上限，默认100 |
| `--top_n` | 否 | 输出排名前N的商品，默认10 |
**⚠️ 交互渲染（必须执行）**：当此命令返回的 `data.data.products` 包含 **≥2 个商品**时，**禁止**直接用 Markdown 表格输出商品数据，必须通过交互组件渲染：
1. **先读取** `{baseDir}/references/interaction-specs.md` 中的 `select_products_from_scoring` 章节，获取交互组件的完整数据结构定义
2. **再触发** `metadata.interactions` 中声明的 `select_products_from_scoring` 交互，严格按 specs 中的字段映射构造参数
### search_offer_by_keyword — 通过关键词搜索店铺商品
```bash
python {baseDir}/cli.py search_offer_by_keyword --keyword "测试" --page 1 --page_size 10
```
参数说明：
| 参数 | 必填 | 说明 |
|------|------|------|
| `--keyword` | 否 | 搜索关键词（可选）。如果传入关键词后搜索无结果，**让大模型尝试换几个简短的相似词来搜索，最多尝试 3 次** |
| `--page` | 否 | 页码，默认 1 |
| `--page_size` | 否 | 每页数量，默认 10 |
**⚠️ 交互渲染（必须执行）**：当此命令返回的 `data.data.items` 包含 **≥2 个商品**时，**禁止**直接用 Markdown 表格输出商品数据，必须通过交互组件渲染：
1. **先读取** `{baseDir}/references/interaction-specs.md` 中的 `select_products_from_search` 章节，获取交互组件的完整数据结构定义
2. **再触发** `metadata.interactions` 中声明的 `select_products_from_search` 交互，严格按 specs 中的字段映射构造参数
## 生成流程
### 第1步：收集信息
从用户获取以下信息：
1. **推荐数量**（可选）：需要推荐的商品数量，默认为 3 款
2. **筛选条件**（可选）：类目范围、商品数量限制等
### 第2步：查询概览数据（可并行执行）
```bash
python {baseDir}/cli.py get_item_overview
python {baseDir}/cli.py get_shop_data
```
根据概览结果中的商品总数决定下一步查询策略：
- **≤200个商品**：使用 `--strategy all` 直接查询全部
- **201-500个商品**：使用 `--strategy comprehensive` 默认筛选
- **>500个商品**：使用 `--strategy comprehensive --limit 200` 限制数量
### 第3步：评分与圈选
将第2步获取的店铺数据通过 `--shop_total` 传入评分命令：
```bash
python {baseDir}/cli.py score_and_select \
--shop_total '{第2步返回的店铺数据 JSON}' \
--strategy <策略> \
--limit <N> \
--top_n <推荐数量>
```
### 第4步：生成报告与交互选择
基于评分结果，按综合得分从高到低排序，选取前 N 款商品（默认 3 款），输出结构化的 Markdown 报告。
**交互触发**：当圈选结果包含多个商品（≥2 款）时，在输出 Markdown 报告的同时，调用 `show_interaction` 并设置 `name='select_products_from_scoring'`，将 `score_and_select` 返回的 `products` 数组映射到交互数据槽位，让用户通过表格勾选要重点运营的商品。具体的字段映射规则与组件渲染数据结构请查阅 [`references/interaction-specs.md`](./references/interaction-specs.md) 中对应交互的章节。
## 报告模板
```markdown
# 重点品圈选结果
基于{策略总结}，推荐以下 {N} 款商品：
1. **{商品标题}** (ID: {item_id}) —— 【{商品标签}】
- {选择原因，1-2句话说明核心数据和优势}
2. **{商品标题}** (ID: {item_id}) —— 【{商品标签}】
- {选择原因}
3. ...
```
**格式要求**：
- **商品标签**：根据商品特征标注角色，如引流款、利润款、潜力款、爆款、动销款等
- **选择原因**：1-2句话说明核心数据和优势
- **禁止内容**：不展示综合得分、不输出优化动作、不输出行动建议
## 交互能力
本 Skill 支持通过 Newton Agent 的客户端交互组件，在输出多个商品时提供可视化的表格选择体验。
### 触发规则
| 交互名称 | 触发时机 | 数据来源 |
|----------|---------|---------|
| `select_products_from_scoring` | `score_and_select` 返回 ≥2 个商品时 | `score_and_select` 返回的 `products` 数组 |
| `select_products_from_search` | `search_offer_by_keyword` 返回 ≥2 个商品时 | `search_offer_by_keyword` 返回的 `items` 数组 |
### 数据填充
- **`select_products_from_scoring`**：设置 `title` 为表格标题，`columns` 为列定义数组，将 `score_and_select` 返回的 `data.data.products` 数组逐项转换后赋值给 `rows` 槽位。每行需包含 `id`、`title`、`level`、`levelName`、`totalScore`、`payAmount`、`buyerCount`、`uv`。
- **`select_products_from_search`**：设置 `title` 为表格标题，`columns` 为列定义数组，将 `search_offer_by_keyword` 返回的 `data.data.items` 数组逐项转换后赋值给 `rows` 槽位。每行需包含 `id`（源字段 `itemId`）、`title`、`imageUrl`（源字段 `mainImage`）、`minPrice`、`maxPrice`、`status`。
**具体的字段映射规则与组件渲染数据结构请查阅 [`references/interaction-specs.md`](./references/interaction-specs.md) 中对应交互的章节。**
### 注意事项
- 调用 `table` 类型交互前，务必确保 `rows` 有真实数据，否则前端会报错
- 当结果仅有 1 个商品时，无需触发交互，直接输出 Markdown 报告即可
- 交互组件与 Markdown 报告可同时输出，互不冲突
## 安全声明
| 风险级别 | 命令 | Agent 行为 |
|---------|------|----------|
| 只读 | configure | 可直接执行，无需确认 |
| 只读 | get_item_overview | 可直接执行，无需确认 |
| 只读 | get_shop_data | 可直接执行，无需确认 |
| 只读 | score_and_select | 可直接执行，无需确认 |
| 只读 | search_offer_by_keyword | 可直接执行，无需确认 |
## 异常处理
任何命令输出 `success: false` 时：
1. **先输出 `markdown` 字段**（已包含用户可读的错误描述）
2. **再根据关键词追加引导**：
| markdown 关键词 | Agent 额外动作 |
|----------------|--------------|
| "AK 未配置" 或 "签名无效" 或 "401" | 提示用户补充有效 AK 或检查鉴权配置后重试 |
| "限流" 或 "429" | 建议用户等待 1-2 分钟后重试 |
| 其他 | 仅输出 markdown 即可 |
## 环境变量（.env）
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SKILL_NAME` | `1688-item-selection` | skill 名称 |
| `SKILL_VERSION` | `1.0.0` | skill 版本号 |
| `SKILL_CHANNEL` | `clawhub` | 发布渠道 |
## 埋点上报
每次 CLI 命令执行时，自动向 skill 网关上报一次调用记录，用于统计 skill 调用次数。
## 输出格式
采用标准 JSON 输出：
```json
{
"success": true,
"markdown": "商品评分与圈选成功",
"data": {
"data": {
"total_scored": 50,
"returned_count": 3,
"products": [...],
"summary": {"S级": 2, "A级": 5, "B级": 20, "C级": 23}
}
}
}
```
## 评分规则
详细的评分规则和权重说明见 [scoring_rules.md](references/scoring_rules.md)。
## 数据表Schema
数据表字段定义见 [table_schema.md](references/table_schema.md)。
## 使用原则
1. **必须查询真实数据**：通过 CLI 命令获取真实数据，不要编造
2. 概览和店铺数据脚本可以并行执行以提高效率
3. 根据概览结果的商品数量决定明细查询策略
4. 此技能为只读操作，不会修改任何数据
## 免责声明：
1、您理解并同意，技能运行结果和输出内容可能因适用的AI agent、大模型不同而产生差异或幻觉，请您对重要的信息进行甄别核实。
2、您应妥善保管您的Access Key（AK），这是您运行1688技能的身份凭证，请勿提供给第三人，避免身份凭证泄露造成损失。
3、您下载安装1688技能运行时应始终保持其完整性，不得擅自篡改技能的代码、相关文件或其他内容，否则1688不对技能运行结果和输出内容承担任何法律责任。
4、受限于当前技术发展，我们无法保证技能所有运行结果、输出内容的准确性、真实性、时效性，亦不代表我们的态度、观点和推荐，请您谨慎核实技能运行结果和输出内容，除法律规定由我们承担赔偿责任的场景外，我们不承担其他赔偿责任。