1688-item-selection

# 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、受限于当前技术发展，我们无法保证技能所有运行结果、输出内容的准确性、真实性、时效性，亦不代表我们的态度、观点和推荐，请您谨慎核实技能运行结果和输出内容，除法律规定由我们承担赔偿责任的场景外，我们不承担其他赔偿责任。