1688-shop-operate

## 环境准备 统一入口：`python3 {baseDir}/cli.py <command> [options]` 尽量使用绝对路径执行脚本 ### Windows 权限问题（仅 Windows 用户需要） 若 skills 目录缺少执行权限（提示"拒绝访问"），需先将目录拷贝到 workspace 再操作： ```cmd xcopy /E /I /Y "<skills目录路径>" "%USERPROFILE%\workspace\1688-auth-skill-for-wukong" cd /d "%USERPROFILE%\workspace\1688-auth-skill-for-wukong" ``` > `/E` 递归复制所有子目录，`/I` 目标不存在时自动创建，`/Y` 覆盖时不询问确认。 > 拷贝完成后，后续所有命令均在 workspace 路径下执行。 首次使用前，在项目根目录执行： ```bash pip install -r requirements.txt # 若上述命令不可用，尝试： pip3 install -r requirements.txt ``` 依赖列表：仅使用 python3 标准库，无需额外安装第三方包。 ## AK 安全说明 > ⚠️ **AK 是访问 1688 接口的唯一凭证，请妥善保管，避免泄漏。** - AK 在本地以**设备绑定加密**方式存储（PBKDF2 派生密钥 + 流加密 + HMAC 校验），加密文件拷贝到其他机器后**无法解密** - 不要将 AK 明文粘贴到聊天记录、截图、日志或版本控制中 - 不要将 `ak_store.json` 或 `.device_id` 上传到任何云端或共享目录 - 如怀疑 AK 已泄漏，立即执行 `cli.py configure --clear` 清除本地存储，并前往 [clawhub.1688.com](https://clawhub.1688.com/) 重新获取 ## 命令速查 ### AK 管理 | 命令 | 说明 | 示例 | |------|------|------| | `get_ak` | 获取AK | `cli.py get_ak` | | `set_ak` | 手动设置AK（已有 AK 时使用） | `cli.py configure YOUR_AK` | | `reset_ak` | 重置AK | `cli.py configure --reset YOUR_NEW_AK` | | `clear_ak` | 清除AK | `cli.py configure --clear` | | `status_ak` | 检查AK状态 | `cli.py configure --status` | ### 店铺经营健康诊断 | 命令 | 说明 | 示例 | |------|------|------| | `get_core_metrics` | 获取店铺核心指标同行对比及趋势数据 | `cli.py get_core_metrics -d RECENT_7` | | `get_traffic_structure` | 获取店铺流量结构数据 | `cli.py get_traffic_structure -d RECENT_7` | | `get_transaction_ranking` | 获取行业交易排名数据 | `cli.py get_transaction_ranking -d RECENT_7` | | `get_customer_profile` | 获取客户画像数据 | `cli.py get_customer_profile -d RECENT_7` | 所有命令输出 JSON：`{"success": bool, "markdown": str, "data": {...}}` **展示时直接输出 `markdown` 字段，Agent 分析追加在后面，不得混入其中。** ## 使用流程 Agent 根据用户意图**直接执行对应命令**。 各命令在 AK 缺失等情况下会自行返回明确错误，Agent 按下方「异常处理」应对即可。 **店铺健康诊断使用指引**： - 当用户要求店铺诊断、经营分析、同行对比时，需并行调用以下 4 个命令获取数据： - `get_core_metrics` — 核心指标同行对比及趋势 - `get_traffic_structure` — 流量结构分析 - `get_transaction_ranking` — 行业交易排名（⚠️ 仅支持 RECENT_7 / RECENT_30） - `get_customer_profile` — 客户画像 - 公共可选参数： - `--date_type` / `-d`：日期类型，默认 `RECENT_7` - `--device` / `-v`：设备类型，默认 `ALL` - 获取数据后由 LLM 综合分析生成诊断报告，详见下方「店铺健康诊断流程」 ## 数据查询命令详细说明 ### get_core_metrics — 核心指标同行对比及趋势 ```bash python3 {baseDir}/cli.py get_core_metrics [--date_type <DATE_TYPE>] [--device <DEVICE>] ``` **返回字段映射**： | 返回区块 | 含义 | 用途 | |---------|------|------| | `core_metrics` | 7项核心指标的本店值、同行同层平均、评级（优秀/持平/略低/极低） | 快速定位落后指标 | | `trend` | 各指标的环比、同期对比、较同行变化率 | 判断趋势方向 | **core_metrics 中的 metric_code 取值**： | metric_code | 指标名 | |-------------|--------| | `impression` | 展现次数 | | `visitor` | 访客数 | | `page_view` | 浏览量 | | `click_cvr` | 点击转化率 | | `pay_cvr` | 支付转化率 | | `buyer_count` | 支付买家数 | | `pay_amount` | 支付金额 | **rating 评级含义**： | 评级 | 含义 | ratio_to_peer 参考范围 | |------|------|----------------------| | 优秀 | 高于同行同层平均 | >= 1.1 | | 持平 | 接近同行同层平均 | 0.9 - 1.1 | | 略低 | 低于同行同层平均 | 0.5 - 0.9 | | 极低 | 远低于同行同层平均 | < 0.5 | **trend 字段结构**： | 子字段 | 含义 | 计算基准 | |--------|------|---------| | `year_on_year` | 年同比 | RECENT_1: 今天 vs 去年同一天；RECENT_7: 本周 vs 去年同一周；RECENT_30: 本月 vs 去年同一月 | | `week_on_week` | 周期环比 | RECENT_1: 今天 vs 昨天；RECENT_7: 本周 vs 上周；RECENT_30: 本月 vs 上月 | | `vs_peer_avg` | 较同行平均的变化率 | 本店变化率 vs 同行平均变化率 | | `vs_peer_good` | 较同行优秀的变化率 | 本店变化率 vs 同行优秀变化率 | > **⚠️ 注意**：`trend` 数据并非完全覆盖 `core_metrics` 的全部 7 项指标，实际返回的趋势指标为：`impression`（展现次数）、`visitor`（访客数）、`page_view`（浏览量）、`click_cvr`（点击转化率）、`buyer_count`（支付买家数），以及额外的 `ad_impression`（广告展现）。**缺失** `pay_cvr`（支付转化率）和 `pay_amount`（支付金额）的趋势数据。 ### get_traffic_structure — 流量结构数据 ```bash python3 {baseDir}/cli.py get_traffic_structure [--date_type <DATE_TYPE>] [--device <DEVICE>] ``` **返回字段映射**： | 返回区块 | 含义 | 用途 | |---------|------|------| | `traffic` | 流量来源排行、新老访客比、PC/无线占比、跳失率、入店搜索词 | 分析流量结构健康度 | ### get_transaction_ranking — 行业交易排名 ```bash python3 {baseDir}/cli.py get_transaction_ranking [--date_type <DATE_TYPE>] [--device <DEVICE>] ``` **⚠️ 日期类型限制**：仅支持 `RECENT_7` 和 `RECENT_30`，不支持 `RECENT_1`。若用户请求近1天数据，行业定位章节应跳过。 **返回字段映射**： | 返回字段 | 含义 | 用途 | |---------|------|------| | `industry_name` | 所属行业名称 | 行业定位 | | `my_pay_amount` | 本店支付金额 | 行业排名依据 | | `industry_rank` | 行业排名 | 行业地位评估 | | `industry_total` | 行业店铺总数 | 排名百分位计算 | | `rank_percentile` | 排名百分位（如 0.25 表示前25%） | 行业相对位置 | | `benchmark` | TOP标杆数据（top3_avg、top10_avg、top100_avg） | 与标杆差距对比 | **benchmark 字段结构**： | 子字段 | 含义 | |--------|------| | `top3_avg` | 行业TOP3平均支付金额 | | `top10_avg` | 行业TOP10平均支付金额 | | `top100_avg` | 行业TOP100平均支付金额 | ### get_customer_profile — 客户画像数据 ```bash python3 {baseDir}/cli.py get_customer_profile [--date_type <DATE_TYPE>] [--device <DEVICE>] ``` **返回字段映射**： | 返回区块 | 含义 | 用途 | |---------|------|------| | `customer` | 支付买家/L会员/客户数 vs 同行优秀、回头率、新老客 GMV 构成、客单价 | 分析客户结构 | ## 安全声明 | 风险级别 | 命令 | Agent 行为 | |---------|------|-----------| | **只读** | get_core_metrics | 可直接执行，无需确认 | | **只读** | get_traffic_structure | 可直接执行，无需确认 | | **只读** | get_transaction_ranking | 可直接执行，无需确认 | | **只读** | get_customer_profile | 可直接执行，无需确认 | ## 店铺健康诊断流程 ### 规范约束 1. **禁止编造数据**：所有数据必须通过 CLI 命令获取真实数据 2. **数据格式**：金额保留 2 位小数并使用千分位格式（如 ¥125,000.00），百分比保留 1 位小数 3. **错误处理**：命令返回错误或数据为空时，对应章节标注"数据暂不可用"，不要用假数据填充 4. **精简输出**：表格数据完整展示，文字分析聚焦瓶颈识别和改善方向，每个瓶颈的改善建议控制在 1-2 条 ### Step 1 — 确定查询参数 默认使用 `RECENT_7`（近 7 天）数据，设备类型默认 `ALL`。接受用户指定 `date_type` 和 `device`。 ### Step 2 — 并行获取诊断数据 以下四个命令可**并行执行**，它们之间无数据依赖： ```bash python3 {baseDir}/cli.py get_core_metrics --date_type <DATE_TYPE> --device <DEVICE> python3 {baseDir}/cli.py get_traffic_structure --date_type <DATE_TYPE> --device <DEVICE> python3 {baseDir}/cli.py get_transaction_ranking --date_type <DATE_TYPE> --device <DEVICE> python3 {baseDir}/cli.py get_customer_profile --date_type <DATE_TYPE> --device <DEVICE> ``` 错误处理规则： - **`get_transaction_ranking`**：执行失败或数据为空/不含 `industry_name` → 跳过"行业定位"章节 - **其他命令返回错误**：对应报告章节标注"数据暂不可用"，其余章节正常生成 ### Step 3 — LLM 分析推理 此步为 LLM 推理环节，不调用脚本： **指标评估**（数据来源：`get_core_metrics`）： - 遍历 `core_metrics`，重点标注 `rating` 为"略低"和"极低"的指标 - 结合 `trend` 数据判断趋势方向（改善中 / 恶化中 / 稳定） **流量结构分析**（数据来源：`get_traffic_structure`）： - 基于 `traffic` 数据，分析来源集中度（是否过度依赖单一渠道） - 评估新老访客比例是否健康（新客占比过高说明老客留存差） - 跳失率是否偏高、人均浏览量是否合理 **行业定位**（数据来源：`get_transaction_ranking`）： - ⚠️ **数据可用性检查**： - 命令执行失败 → 跳过此模块 - 返回数据中无 `industry_name` 字段 → 跳过此模块 - 数据正常 → 基于返回数据，展示行业名称、排名、百分位、标杆对比 - 数据正常时，分析要点： - 根据 `industry_rank` 和 `industry_total` 计算排名百分位 - 对比 `benchmark.top3_avg/top10_avg/top100_avg`，评估与标杆差距 - 判断行业地位（头部/中上部/中部/下部）及提升空间 **客户健康度**（数据来源：`get_customer_profile`）： - 基于 `customer` 数据，对比同行优秀水平 - 分析复购率、新老客 GMV 结构 **瓶颈诊断结论**（综合四个命令全部数据）： - 综合以上数据，识别 1-3 个核心瓶颈，按严重程度排序 - 每个瓶颈需有数据支撑（引用具体指标和数值） - 针对每个瓶颈给出 1-2 条可落地的改善方向 ### Step 4 — 生成诊断报告 按下方报告模板组织数据，输出完整诊断报告。 **章节生成规则**： - **"一、核心指标 vs 同行同层"**：必选章节 - **"二、流量结构分析"**：必选章节 - **"行业定位章节"**：如果 `get_transaction_ranking` 返回错误或数据为空，**直接跳过此章节**，后续章节顺序自动调整（客户健康度变为"三"、瓶颈诊断变为"四"） - **"客户健康度章节"**：必选章节。若行业定位章节跳过，则编号为"三"；否则编号为"四" - **"瓶颈诊断章节"**：必选章节。若行业定位章节跳过，则编号为"四"；否则编号为"五" ### Phase 2：交互深入分析 输出诊断报告后，在末尾追加交互引导： ``` --- 如需深入了解某个方面（流量优化 / 转化提升 / 客户运营），或希望基于诊断结论生成月度经营规划，请告知。 ``` 用户可以： - 针对某个瓶颈要求更详细的分析和建议 - 要求聚焦某个维度（如流量、客户）做深入分析 - 要求生成月度经营规划（引导至月度规划 skill） 交互跟进时复用已获取的数据，不重新调用脚本。 ## 诊断报告输出格式 采用**模块化输出**，每个模块用 HTML 注释标记边界和结构化元数据，便于 UI 层按模块拆分渲染。HTML 注释在 Markdown 渲染时不可见，不影响阅读体验。 ### 模块标记规范 - `<!-- MODULE: 模块名 -->` 和 `<!-- /MODULE: 模块名 -->` 标记模块边界 - `<!-- KEY: value -->` 标记模块内的结构化决策值 - 模块内部使用标准 Markdown 格式（表格、引用、列表等） - 所有金额单位为元，保留2位小数，千分位格式 - 百分比保留1位小数 ## 报告模板 ```markdown # 店铺经营健康诊断报告（{start_date} 至 {end_date}） <!-- MODULE: diagnosis --> <!-- DATE_RANGE: {start_date} 至 {end_date} --> <!-- DATE_TYPE: {date_type} --> <!-- BOTTLENECKS: ["瓶颈一", "瓶颈二"] --> ## 一、核心指标 vs 同行同层 | 指标 | 本店 | 同行同层均值 | 达标率 | 评级 | |------|------|------------|--------|------| | 展现次数 | {my_value} | {peer_avg} | {ratio_to_peer}% | {rating_emoji} {rating} | | 访客数 | {my_value} | {peer_avg} | {ratio_to_peer}% | {rating_emoji} {rating} | | 浏览量 | {my_value} | {peer_avg} | {ratio_to_peer}% | {rating_emoji} {rating} | | 点击转化率 | {my_value}% | {peer_avg}% | {ratio_to_peer}% | {rating_emoji} {rating} |