1688 商品诊断

⚠️ 强制约束

1. 禁止编造数据：所有数据必须来自 CLI 真实返回结果
2. 先执行 CLI 再分析：必须先通过 python3 cli.py 调用获取数据，不得跳过
3. 如实标注失败或空数据：返回 success=false 或空数据时标注"数据暂不可用"，不必反复重试

数据查询命令

统一入口：python3 {baseDir}/cli.py [options]

__userId__ 由 cli.py 通过解析 ALI_1688_AK 自动注入，命令本身无需感知卖家身份。

get_abnormal_offers 参数说明

• --date_type：日期类型（可选，默认 RECENT_7）
  • 可选值：RECENT_7（近 7 天）、RECENT_30（近 30 天）
• --device：设备筛选（可选，默认 ALL）
  • 可选值：ALL（全部）、PC、APP

返回值示例：

{
  "success": true,
  "data": {
    "count": 20,
    "items": [
      {"itemId": "668758083302", "offerTitle": "...", "reason": "支付下跌", "valueMap": {...}},
      {"itemId": "779218424674", "offerTitle": "...", "reason": "访客下跌", "valueMap": {...}}
    ]
  }
}

get_offer_data 参数说明

• --offer_id：商品 ID，字符串（必填）
• --modules：要获取的数据模块，逗号分隔（可选，默认 all）
  • 可选值：profile（基础资料）、performance（表现）、huopan（货盘）、search_issues（搜推问题）、purchase_factors（购买因素）、sycm_anomaly（异常检测）、ad_analysis（广告分析）、hotwords（热搜词）、hot_items（热品）、all

输出 JSON：{"success": bool, "markdown": str, "data": {...}}

示例：

# 获取全量数据
python3 {baseDir}/cli.py get_offer_data --offer_id 1048050628164

# 仅获取表现 + 广告 + 搜推问题
python3 {baseDir}/cli.py get_offer_data --offer_id 1048050628164 --modules performance,ad_analysis,search_issues

参考文档

通过 read_file 读取：

安全声明

诊断执行步骤

Step 1: 查询异常商品列表 + 交互选择（前置步骤）

执行异常商品查询，获取商家需要重点关注的商品：

python3 {baseDir}/cli.py get_abnormal_offers

根据返回结果分两种情况处理：

情况 A：异常商品列表不为空

调用 show_interaction 以 Table 组件展示异常商品供用户选择：

• 设置 name='select_abnormal_offer'
• 将 get_abnormal_offers 返回的 data.items 数组按照 references/interaction-specs.md 中定义的字段映射规则，转换后赋值给 rows 槽位
• 具体的列定义、字段映射和数据结构请查阅 references/interaction-specs.md 中 select_abnormal_offer 章节

用户选择商品后，从交互结果中提取 id（即 itemId）作为后续诊断的 offer_id。

情况 B：异常商品列表为空

调用 show_interaction 以 Input 组件引导用户手动输入商品 ID：

• 设置 name='input_offer_id'
• 具体的数据结构请查阅 references/interaction-specs.md 中 input_offer_id 章节

用户输入商品 ID 后，将其作为后续诊断的 offer_id。

如果用户已明确提供了商品 ID，可跳过此步骤直接进入 Step 2。

Step 2: 读取分析标准 + 收集商品数据（并发执行）

用户选择商品（或输入 offer_id）后，同时执行：

• read_file("references/analysis-dimensions.md")
• bash("python3 {baseDir}/cli.py get_offer_data --offer_id <商品ID>")

Step 3: 输出精简报告

按照 references/report-template-simple.md 模板输出诊断报告。

输出格式：

1. [商品名称] (ID: [商品ID]) —— 【货盘定位】
   ● 选择原因：[为什么优化，用数据说话]
   ● 优化：
      - [优化项1]
      - [优化项2]
      - [优化项3]

要求：

1. 货盘定位 - 标注【引流款】【利润款】【爆款】【定制款】【新品】
2. 选择原因 - 1-2 句话说明核心问题，必须引用具体数据
3. 优化项 - 每个商品 1-4 条，要具体可执行（不要泛泛而谈）
4. 优先级 - 违规问题 > 流量问题 > 转化问题 > 优化建议

Step 4: 行动选择（必须执行，禁止省略）

诊断报告输出完成后，Agent 必须立即调用 show_interaction 触发 select_action 交互：

1. 先读取 references/interaction-specs.md 中 select_action 章节，获取完整的数据槽位、构造规则、关键词映射表、完整 JSON 示例
2. 再触发 metadata.interactions 中声明的 select_action，严格按 specs 中的字段映射构造 questions 数据
3. 数据来源：options 数组的内容必须从本次诊断报告"优化项"原文提取，禁止硬编码或编造
4. 用户选中后：根据 specs 中"用户选择后的处理"表，直接调用对应下游技能（1688-item-image-optimizer / 1688-item-title-optimizer），并把当前诊断的 offer_id 与对应优化项原文作为上下文传入，无需用户再次输入

⚠️ 即使报告输出完整、用户没有进一步发言，也必须触发此交互，否则视为流程未完成。

异常处理

任何命令输出 success: false 时：

1. 先输出 markdown 字段（已包含用户可读的错误描述）
2. 再根据关键词追加引导：

环境变量（.env）

项目根目录的 .env 文件存储 skill 基础信息，供埋点上报等模块读取。发布到不同环境时可直接替换该文件中的变量值。

已存在的系统环境变量优先级高于 .env，CI/CD 注入的变量不会被覆盖。

注意事项

• 商品 ID 为字符串格式，通过 --offer_id 参数传入
• 报告中每一项数据都必须能追溯到 CLI 的真实输出
• 建议要具体可执行，结合 1688 平台特点和商家实际需求