店铺经营健康诊断

1688 店铺经营健康诊断

职责边界

本技能采用「MCP 工具取数 + Python 脚本后处理」模式：

• 账号鉴权、Token 刷新、OAuth 授权全部由 MCP 连接器 ali1688-seller 管理。
• Agent 不处理 AK，不读取/保存 AK，不调用 configure、get_ak、change_ak、authorize 等授权命令。
• 经营数据必须通过 MCP 工具获取，禁止再通过 Python 脚本直接调用 HTTP API。
• MCP 返回后的结构校验、日期规则、行业模块跳过、字段格式化、章节重排、瓶颈诊断等后处理逻辑交给本技能 Python 脚本执行。

MCP 连接器

• 连接器名称：ali1688-seller
• 协议：Streamable HTTP
• 本技能使用工具：get_core_metrics、get_traffic_structure、get_transaction_ranking、get_customer_profile

本地后处理脚本

• 脚本入口：python3 {baseDir}/cli.py post_process_report --input-file <mcp_result.json>
• 输入：包含 MCP 四路工具返回结果的 JSON 文件
• 输出：标准 JSON：{"success": bool, "markdown": str, "data": {...}}
• 用户可见内容：直接使用输出中的 markdown
• Agent 只能把 MCP 原始返回传给脚本，不得自行重写复杂报告逻辑

输入 JSON 结构：

{
  "date_type": "RECENT_7",
  "get_core_metrics": {},
  "get_traffic_structure": {},
  "get_customer_profile": {},
  "get_transaction_ranking": {}
}

说明：

• 每个工具结果可以是 MCP 原始对象，也可以是 {"success": true, "data": {"data": {...}}} 这类包装结构。
• RECENT_1 不调用 get_transaction_ranking，输入中可省略 get_transaction_ranking。
• 脚本会按旧逻辑处理模块失败：单模块不可用时标注“数据暂不可用”，行业模块不可用时跳过行业章节并重排编号。

严格禁止 (NEVER DO)

• 不得编造任何经营数据，包括指标值、排名、百分位、趋势、行业标杆、客户数据。
• 不得在 MCP 或脚本失败时用估算值、历史记忆、模型推测补齐结果。
• 不得调用旧 Python 查询命令通过 HTTP 拉取经营数据，如 get_core_metrics、get_traffic_structure、get_transaction_ranking、get_customer_profile。
• 不得触发本技能内的 AK/OAuth 管理逻辑；鉴权异常只提示用户检查 ali1688-seller 连接器授权状态。
• 不得把 MCP 原始结构化数据直接全量倾倒给用户，必须通过 post_process_report 生成报告。
• 不得忽略日期类型限制：get_transaction_ranking 不支持 RECENT_1。

意图判断

触发本技能（满足任一）

• 用户提及：店铺诊断、经营诊断、健康诊断、经营分析、同行对比、店铺健康。
• 用户要求：分析最近经营表现、找经营瓶颈、输出提升建议。
• 用户希望按时间维度看经营情况：近1天、近7天、近30天。

不触发本技能

• 商品选品、找货、同款搜索、比价，应触发 1688-product-find。
• 商品发布、标题优化、主图优化、上下架，应触发 1688-product-manage。
• 下单、付款、履约、物流、售后、库存管理。

参数约束

公共规则：

• device 固定传 ALL
• 默认 date_type = RECENT_7

日期映射：

各 MCP 工具的 date_type 白名单：

参数不合法时直接提示用户使用近1天、近7天或近30天，不做隐式修正。

核心工作流

Step 1：确定查询参数

1. 从用户请求中识别时间范围。
2. 未指定时使用 RECENT_7。
3. device 始终使用 ALL。
4. 若用户指定近1天（RECENT_1），后续跳过 get_transaction_ranking。

Step 2：通过 MCP 并行获取数据

并行调用无数据依赖的 MCP 工具：

1. get_core_metrics(date_type, device="ALL")
2. get_traffic_structure(date_type, device="ALL")
3. get_customer_profile(date_type, device="ALL")
4. get_transaction_ranking(date_type, device="ALL")，仅当 date_type != RECENT_1

MCP 调用规则：

• 由 MCP 自动注入鉴权上下文。
• 工具返回错误时保留原始错误对象，不要自行兜底造数据。
• 除 RECENT_1 主动跳过行业排名外，其他工具都应尝试调用。

Step 3：把 MCP 返回交给 Python 后处理

将 Step 2 的所有工具返回写入一个 JSON 文件，例如：

{
  "date_type": "RECENT_7",
  "get_core_metrics": "<MCP get_core_metrics 原始返回>",
  "get_traffic_structure": "<MCP get_traffic_structure 原始返回>",
  "get_customer_profile": "<MCP get_customer_profile 原始返回>",
  "get_transaction_ranking": "<MCP get_transaction_ranking 原始返回>"
}

然后执行：

python3 {baseDir}/cli.py post_process_report --input-file <mcp_result.json>

必须使用脚本输出的 markdown 作为最终诊断报告。Agent 可以在报告后追加一句很短的交互引导，但不得修改报告里的指标、章节、判断、排名或改善方向。

Step 4：脚本保留的后处理口径

post_process_report 必须保留以下旧逻辑：

1. 返回结构校验

   • 每个工具结果必须能解析为对象。
   • 非对象按“格式异常，请稍后重试”处理。

2. 日期规则

   • get_transaction_ranking 只支持 RECENT_7、RECENT_30。
   • RECENT_1 默认跳过行业定位章节。

3. 行业定位可用性判定

   • 行业工具调用失败、返回为空、缺失 industry_name 时，跳过行业章节。
   • 跳过后，客户健康度与瓶颈诊断章节编号自动前移。

4. 趋势字段不完整兼容

   • get_core_metrics.trend 可能缺失 pay_cvr、pay_amount。
   • 缺失项统一标注“数据暂不可用”，不得补造。

5. 统一输出格式

   • 金额统一“元”，保留2位小数并带千分位，如 ¥125,000.00。
   • 百分比保留1位小数。
   • 数据缺失统一标注“数据暂不可用”。
   • 报告章节顺序稳定，行业章节可跳过。

6. 瓶颈诊断

   • 基于核心指标评级、流量结构、行业排名、客户复购等字段识别 1-3 个瓶颈。
   • 每个瓶颈必须包含数据依据和改善方向。
   • 数据不足时输出“数据完整性不足”类瓶颈，不得伪造业务结论。

MCP 数据字段

get_core_metrics

• core_metrics：7项核心指标。
• trend：同比、环比、较同行变化。

核心指标：

评级口径：

get_traffic_structure

重点字段：来源排行、新老访客比、终端占比、跳失率、入店搜索词。

get_transaction_ranking

重点字段：industry_name、my_pay_amount、industry_rank、industry_total、rank_percentile、benchmark。

get_customer_profile

重点字段：买家数、L会员数、客户数、回头率、新老客 GMV、客单价。

报告输出要求

最终报告由脚本生成，结构如下：

# 店铺经营健康诊断报告（{date_range 或 date_type}）

## 一、核心指标 vs 同行同层
...

## 二、流量结构分析
...

## 三、行业定位（当可用）
...

## 四、客户健康度（若行业定位不可用则编号前移）
...

## 五、瓶颈诊断与改善方向（若行业定位不可用则编号前移）
...

报告要求：

• 核心指标、流量结构、客户健康度为固定章节。
• 行业定位仅在 get_transaction_ranking 数据可用时出现。
• 单模块失败时该模块标注“数据暂不可用”，其他模块继续。
• 全部失败时脚本返回明确失败或“数据完整性不足”，不得生成伪报告。

错误处理

MCP 工具调用/网关错误

业务错误码命中以下之一时，也按连接器授权错误处理：

• 1688_token_expired
• 1688_invalid_token
• 1688_token_revoked
• 1688_token_unauthorized
• 1688_no_scope_specified
• 1688_invalid_scope

Python 后处理错误

参数补齐引导话术

默认按近7天做店铺健康诊断。你也可以指定时间范围：近1天、近7天、近30天。

免责声明

1. 技能运行结果可能因模型能力与上下文差异产生偏差，请对关键结论自行核验。
2. 请妥善保管账号与授权信息，避免泄露导致损失。
3. 不得篡改技能内容用于非授权用途。
4. 平台不保证输出绝对准确、真实、时效，请谨慎使用。