1688 Product Analysis

1688 商品全方位分析诊断工具，整合多个数据源对指定商品进行深度分析。当用户需要分析某个指定商品表现、诊断流量问题、优化商品策略时使用。适用于指定商品的：商品数据分析、销售表现诊断、搜索排名问题分析、广告效果评估、市场竞争分析、商品优化建议。触发关键词包括"分析这个商品"、"商品诊断"、"商品表现分析"、"为什么商品没流量"、"商品优化建议"、"商品数据分析"等。

1688 商品诊断

⚠️ 强制约束

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

数据查询命令

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

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

命令	用法	说明
get_abnormal_offers	python3 {baseDir}/cli.py get_abnormal_offers [--date_type <日期类型>] [--device <设备>]	查询商家需重点关注的异常商品列表（支付下跌、访客下跌等，多个异常榜单取交集）
get_offer_data	python3 {baseDir}/cli.py get_offer_data --offer_id <商品ID> [--modules <模块列表>]	获取商品综合数据（基础资料、表现、货盘、搜推问题、购买因素、异常检测、广告分析、热搜词、热品）

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 读取：

文档	路径
分析维度	references/analysis-dimensions.md
报告模板	references/report-template-simple.md
交互规范	references/interaction-specs.md

安全声明

风险级别	命令	Agent 行为
只读	get_abnormal_offers	可直接执行，无需确认
只读	get_offer_data	可直接执行，无需确认

诊断执行步骤

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. 再根据关键词追加引导：

markdown 关键词	Agent 额外动作
"AK 未配置"	提示用户在 OpenClaw 配置 ALI_1688_AK，或检查 ~/.openclaw/openclaw.json
"offer_id 不能为空" / "modules 取值非法"	提示用户使用合法的参数值
"dateType 取值非法" / "device 取值非法"	提示用户使用合法的参数值
"异常商品数据为空" / "商品数据为空"	提示用户确认账号是否已沉淀有效数据
"网络异常，已重试" / "限流" / "429"	建议用户等待 1-2 分钟后重试
其他	仅输出 markdown 即可

环境变量（.env）

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

变量	默认值	说明
SKILL_NAME	1688-product-analysis	skill 名称
SKILL_VERSION	1.0.0	skill 版本号
SKILL_CHANNEL	clawhub	发布渠道
ALI_1688_AK	由平台 OpenClaw 注入	1688 开放平台 AK，CLI 自动解析卖家身份并注入 __userId__
OPENCLAW_CONFIG_DIR	~/.openclaw	OpenClaw 配置文件目录（AK 兜底读取来源）

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

注意事项

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