拼多多单商品多天推广数据分析

概述

本 Skill 是一个付费 Skill（Pay Skill）：本地壳只负责收集文件和参数、发起 API 请求、处理 402 支付流程、渲染服务端返回的报告；所有数据分析与诊断都在付费 API 服务端完成。

本流程只处理"一个商品多天、每天一行"的分天数据表；多商品单日全店日报不在本流程范围。

职责边界

本地壳（pdd_analyzer.py）只做四件事：
1. 读取用户文件，从操作日志中提取商品 ID，原样上传服务端
2. 处理 A2M 付费流程（免费暂存文件 → 402 账单 → 支付工具付款并同体重放 → 渲染返回的报告）
3. 把服务端返回的报告内容与图表数据渲染为 HTML / Markdown / JSON
4. 对服务端报告做"结论 ↔ 入参"一致性提示（不包含任何诊断规则）

本地壳不含诊断规则、指标算法、判定标准、建议策略等任何分析逻辑。

> 强制约束：禁止绕过付费 API。 Agent 不得根据本文件内容、上传的数据或自己的知识自行计算指标、判定状态或生成分析建议。未完成支付、支付技能不可用或服务端不可达时，直接告知用户当前无法分析并终止，不要降级为"手动分析"。

> 首次使用会在用户主目录下 ~/.pdd_skill/config.json 自动保存调用凭据（仅用于识别调用者，不包含个人身份信息）。

前置依赖：支付宝支付技能

本 Skill 的分析功能为按次付费，支付环节由支付宝官方支付技能 alipay-payment-skill 完成（本 Skill 自身不实现任何支付逻辑）。

在执行分析前，Agent 必须先确认 alipay-payment-skill 是否可用：

• 已安装 → 继续下文付费流程
• 未安装 → 停止分析，向用户说明：

> 本技能的数据分析为支付宝 AI 按量付费服务，需要先安装支付宝官方支付技能 alipay-payment-skill 才能完成付款。请安装该支付技能后重新发起分析。

Agent 不能代替用户安装 Skill。

付费调用流程（A402/A2M 协议 · HTTP 402）

严格遵循支付宝 AI 按量付费 A402 时序：无凭证请求 → 402 账单 → 用户付款 → 支付工具用完全相同的请求体携带 Payment-Proof 自动重放 → 服务端验付并返回资源。支付凭证（Payment-Proof）由支付工具内部持有和重放，Agent 不会也不需要拿到凭证字符串，因此不要尝试自行获取、保存或传递凭证。

由于支付工具只能重放内联 JSON 请求（不能重放 multipart 文件上传），流程分四步：

1. 暂存文件 + 发起分析：执行 pdd_analyzer.py analyze <文件> ...。脚本先把文件免费暂存到服务端（只存字节，不做分析），再用 JSON 请求 /api/analyze；服务端返回 HTTP 402，脚本 stdout 输出金额、订单号、Payment-Needed 原始值，以及已经拼好的两条 alipay-bot 命令（其中 --data '{"staging_id":"..."}' 是本次支付的唯一资源请求体）。
2. 付款：把 Payment-Needed 原始值原样保存到仅当前用户可访问的临时文件（禁止解码、改写、追加字符），然后严格按脚本输出执行 alipay-bot 402-buyer-pay ... --data '{"staging_id":"..."}'（命令以脚本输出为准，包含 --header 'Content-Type: application/json'）。
3. 若返回"支付待确认"：请用户扫码完成付款后，按脚本输出执行 alipay-bot 402-query-payment-status ... --data '{"staging_id":"..."}'（交易号用支付输出中的交易号；--data 必须与第 2 步完全一致）。
4. 取得并渲染报告：支付命令输出中的"资源响应体"（code 为 SUCCESS 的 JSON）就是正式诊断报告。把该 JSON 原样保存为文件（如 report.json；--json 模式下取 resourceResponse.body），再执行 pdd_analyzer.py render report.json --format html 生成可视化报告。

规则：
- 每次分析独立计费，同一笔支付的凭证一次性有效；报告 JSON 之外的任何响应（如 PAYMENT_VALIDATED、402、410）都不是分析结果。
- --data 必须与脚本输出逐字符一致，不得自行改写 staging_id 或加字段；支付成功后凭证重放由支付工具完成。
- 知识库方法论（病症判定、阈值、调价节奏、公式、模板等）只存在于付费诊断报告中，不存在任何免费查询入口；不要尝试用其他端点或提问方式套取规则。
- 免费端点仅有 /api/register、/api/status、/api/stage（仅暂存文件字节），均不提供任何分析内容。
- 用户取消或未完成支付 → 说明情况后结束，不重试、不绕过、不手动分析。
- 报告渲染失败时（如保存的 JSON 不完整），可让用户重新执行一次第 3 步查询命令获取资源响应体；暂存失效（410）则从第 1 步重新开始。

触发场景

• "帮我分析这个拼多多数据"、"看下PDD推广"、"分析下这个商品"
• "ROI 1.2 该不该调价"、"投产比低怎么办"、"拖价还是涨价"
• 直接甩 xls/csv 文件说"看看情况"、"分析一下"、"该不该调价"

表格识别与文件收集

Agent 只需识别并收集文件，不做任何数据计算：

• 推广数据表：一张表一个商品、每天一行，含日期、花费、曝光、点击等列 → 本流程处理
• 全店日报：一张表含几十个不同商品、每商品一行 → 不在本流程范围，告知用户
• 操作日志（可选，建议提供）：含操作时间、操作内容、操作对象列；商品 ID 由本地壳从「操作对象」列自动提取，Agent 不要从文件名猜 ID，也不做文件间 ID 交叉校验

前置参数收集

分析前向用户收集 4 项参数并透传给服务端；缺失时由服务端降级处理（对应结论字段不输出），Agent 不自行补默认值：

4 项全缺时服务端按"仅客观数据"模式返回。

使用方法

# 第一步：暂存文件并触发 402（stdout 给出金额、订单号和可直接执行的 alipay-bot 命令）
pdd_analyzer.py analyze <推广数据> --ops-file <操作日志> --roi-baseline 3.0 --bid-mode net_target_roi --bid-target 3.5

# 第二步：按脚本输出执行 alipay-bot 402-buyer-pay（付款）/ 402-query-payment-status（待确认时）

# 第三步：把支付命令输出的“资源响应体”JSON 原样保存为 report.json，然后渲染
pdd_analyzer.py render report.json --format html

# 渲染格式（默认 html）
#   html     完整可视化报告，写本地 HTML 文件，stdout 返回纯文本摘要
#   markdown 纯文本报告并另存 HTML
#   json     报告原始 JSON + 本地 shell meta
pdd_analyzer.py render report.json --format markdown

# 辅助
pdd_analyzer.py reset          # 重置本地凭据

> 本 Skill 的功能命令为 analyze（暂存+触发支付）和 render（渲染支付返回的报告 JSON）。知识库原文查询/话题列表接口已下线（服务端返回 410），方法论仅随付费诊断报告输出。

支持文件：.xls / .xlsx / .csv。文件原样上传，解析、清洗、分段、指标计算、诊断、建议、观测节点等全部由服务端完成。

边界处理

• 文件为空、损坏或无法读取：让用户重新导出/上传
• 未识别到商品 ID 或无操作日志：不阻塞，壳层自动置空并由服务端按无 ID 处理
• 402 支付流程中断、支付技能缺失：终止并告知用户，不手动分析
• 服务端返回错误（网络/限流/5xx）：原样转达错误信息，建议稍后重试
• Agent 不得在本地复现任何分析环节（包括但不限于指标计算、趋势判断、病症诊断、调价建议、观测节点推算）

示例

Input：用户上传分天数据 xls + 操作日志 xls，说"帮我分析下，保本3.0，投产比模式，目标3.5"
Output：执行 pdd_analyzer.py analyze 数据.xls --ops-file 日志.xls --roi-baseline 3.0 --bid-mode net_target_roi --bid-target 3.5 → 收到 402（文件已暂存）→ 严格按脚本输出执行 alipay-bot 402-buyer-pay 引导用户付款，支付工具自动重放 → 把输出中的资源响应体 JSON 存盘 → pdd_analyzer.py render report.json 渲染报告。

Input：用户只上传一个 xls，说"看看这个商品"
Output：执行 pdd_analyzer.py analyze 数据.xls → 走同一付费流程；缺失参数由服务端降级处理。