店客多外卖品牌/门店诊断及数据分析

概述

dkd-brand-data-analysis – 店客多外卖经营分析技能（报表生成 + 门店诊断 + 接口编排）

1️⃣ ⚡ 执行锚点（零搜索 · 首屏强制 · 全文第一入口）

① 位置：技能根目录 = 本 SKILL.md 所在目录（脚本与文档均在该目录平铺存放，无子目录）。

② 调用：以本技能目录为基准拼路径调用，例如 python "<本技能目录>/generate_brand_daily.py" --brand "XX品牌"（<本技能目录> 即本 SKILL.md 所在目录，不要写死绝对路径）。禁止用搜索（Glob/Grep/遍历目录）去找脚本、配置或文档——脚本内部按自身位置定位同目录资源（config.json / .cache / 模板 / 图表库），因此可在任意工作目录下调用。

③ 产物落点（关键 · 决定后续到哪取文件，不要靠搜）：

• HTML 报表 / *_AI分析.md → 当前工作目录（可用环境变量 DKD_OUT_DIR 指定固定目录）；脚本运行结束会打印完整产物路径，直接读该路径交给用户，不要再去搜文件。
• 技能根目录 · 读写同源（两条流各自独立，文件名不同，切勿混用）：
  • 报表流：report_diagnostic_data.json（门店对齐 / 门店单平台报表的取数导出）→ AI 读它写 ai_diagnosis_{门店/品牌}_{类型}.json → 重跑报表脚本自动回填。
  • 诊断流：diagnostic_data_{平台}.json（generate_platform_diagnose.py 取数产物）→ render_diagnosis.py 读取判定；AI 可另写 ai_plan_*.json 优化方案。
  • 品牌报表不导出中间数据文件，AI 诊断直接读生成的 HTML。

④ 运行期只读白名单（其余文档属开发期维护资料，运行期不读，避免无效翻阅拖长链路）：

场景	运行期读取
① 报表生成	仅本文件（命令见「5️⃣」、回填见「6️⃣」）
② 门店诊断	本文件「1️⃣4️⃣」+ 命中平台的一份判定文档（美团门店诊断逻辑.md / 淘宝门店诊断逻辑.md），仅在需核对阈值/子项权重时读
③ 接口编排	仅本文件「8️⃣」（4 类坑正解 + action 清单均已内联）；接口能力与应用场景.md 降为按需检索（调不通 / 需完整示例时按 §号 定点读）
排障	仅 Token/连通性问题才读 TOKEN.md

运行期禁止读：USER_GUIDE.md、报表特性.md、接口编排.md（内容已并入本文件）。

⑤ 路径规范（可移植 · 硬约束）：

• 唯一基准：本技能内所有路径以「本 SKILL.md 所在目录」（= 技能根目录）为基准，文档与代码一律使用不含前缀的相对名（如 generate_brand_daily.py、config.json、.cache/、diagnostic_data_{平台}.json）。禁止拼接固定前缀（skills/…、scripts/…）或书写绝对路径。
• 脚本自定位：全部脚本用 SKILL_DIR = os.path.dirname(os.path.abspath(__file__)) 推导技能根目录——不依赖调用方的工作目录，也不依赖技能装在哪里（本机任意目录 / 市场安装位均可直接运行）。
• 统一锚点命名：SKILL_DIR = 技能根目录（config.json / .cache / 模板 / 诊断 JSON 等读写同源资源都以它为基准）；OUT_DIR = 产物目录（默认当前工作目录，可用环境变量 DKD_OUT_DIR 覆盖）；BASE / SCRIPTS / TEMPLATES 为历史别名，恒等于 SKILL_DIR。
• 禁止出现任何机器相关的绝对路径、宿主目录名或用户名——技能必须能整体复制到任意路径/机器后直接可用。

⑥ ⚡ 会话效率纪律（降低「轮数 × 每轮上下文」· 强制）：技能一旦触发，其必读内容在后续每一轮都会重复计入上下文——所以"少读一次"与"少花一轮"是同一件事的两面。

• 一轮闭环：拆解声明 → 取数 → 渲染 → present_files 交付，在同一轮内完成。除「🧩 Step 6 阻断白名单」两种情况外，禁止把拆解结果、或"要不要继续 / 这样对吗"单独发成一轮。
• 零搜索取件：脚本运行结束会打印完整产物路径——直接读该路径；config.json / .cache/ / 模板 / 诊断 JSON 一律按本文件声明落点直取。禁止 Glob / Grep / 遍历目录去找脚本或产物。
• 只读必需的：运行期按上表 ④ 白名单读取；接口能力与应用场景.md 已降为按需检索（4 类坑正解已内联至「8️⃣」）；USER_GUIDE.md / 报表特性.md / 接口编排.md 运行期禁读。
• 门店定位零轮次：不要为"确认门店/确认 Token"单独发轮（列门店池 / search_shops / check_token）——直接调报表脚本，脚本内部自动解析门店。
• 但「品牌 vs 门店」判定不了时必须问用户：脚本能自愈的只有"典型品牌名"（多店共享 ≥4 字前缀 + 各店后缀互不相同）→ 直接给品牌命令；判定不了时脚本会给出提问话术，照它问用户（问 1 轮 < 猜错白跑 1 轮 + 拿到口径错的数据）。详见「🔑 主体定位」。

🧩 用户需求拆解（首屏 · 第一动作 · 强制执行）

任何需求进 AI 前必须先做"6 步拆解"，再决定是直接生成 / 拆分执行 / 反问确认。

这是接收需求的第一动作——比路由判定、报表选择更靠前。

Step 5（数据获取方式判定）为必做项：拆解必须产出并在回复开头显式写出「走哪条路拿数据」——没写出来即视为拆解未完成。

🚨 时序硬约束（v1.1.19 强化 · 针对"先动手后补拆解"失效模式）：

六步拆解是动手前的内部动作——在发出任何取数动作之前必须已完成。取数动作包括（不止）：

ToolSearch 查 MCP schema · 读写技能内脚本 · 写新取数脚本 · 调 call_mcp · 跑 extend_query.py。

拆解的文字放在同一条回复的开头即可（不必单独一轮），但它不得晚于第一个取数动作：

先摸接口、后补拆解 = 拆解未做（本次实跑已踩：未判 Step 5 就直接 ToolSearch 摸裸 MCP，绕过了封装层）。

📊 强制级别图例（全文规则分级 · AI 识别优先级）：

级别	标识	含义	违反后果
🚨 强刷 / 最高优先级	违规即不合规	必须 100% 遵守	不合规即未完成
⚠️ 强制	必须遵守的硬约束	99% 场景不可破例	破例需明确说明理由
📌 推荐	建议遵守的最佳实践	多数场景下遵守	不遵守可接受但效率/质量下降
💡 可选	参考性的细节处理	按需选用	不影响主流程

Step 1：关键信息提取（5 个核心字段）

主体 3 种情况 → 报表类型映射

💡 关键区分：

• ② 单店（"XX门店"）：只填 --shop，AI 用名称模糊匹配；可能跨品牌（同名店多家）
• ③ 品牌门店（"XX品牌的XX门店"）：同时填 --shop + --brand，品牌作精确过滤，避免误匹配同名店
• ① 品牌整体（"XX品牌"）：填 --brand，报表自动聚合所有门店

展示方式 5 种场景 → 输出类型映射（数据分析默认 widget）

💡 核心原则：

• 数据分析场景 → 默认 widget 渲染（对话内最直观）
• 其他场景按用户明确需求决定；用户没说则按默认 widget
• 多输出支持：同时要多种（如"分析后给我 Excel"）→ widget + 文件同时生成（不冲突，按需求累加）

🔑 主体定位：品牌 vs 门店（最高频动作 · 零决策 · 禁止单独占轮）

⛔ 不要为了"确认门店"单独跑一轮（列门店池 / 跑 search_shops / 先 check_token）。

报表脚本内部已自动解析门店（search_shops），一条命令直达报表——"查门店"不是一个步骤，是脚本内部实现。

判定口径：词指向一个品牌（下含多家店）→ 品牌脚本；指向某一家店 → 门店脚本。拿不准就直接跑门店脚本，让脚本去判——它只有几种结果（见下表），每一种都给了你下一步的原文。

🧬 脚本已内置「门店自愈」（引擎级 · AI 不需要处理）——四种结果都产出可复制的命令或提问话术：

⛔ 不要换关键词盲试、不要加 --brand <品牌名> 硬凑（--shop <品牌名> --brand <品牌名> 命中结果完全相同，纯白跑一轮）。

⚠️ 歧义必须问用户（禁止猜）

为什么：主体判错 = 客户拿到口径错误的数据（想查一家店却给了全品牌；想查品牌却给了一家店）。这比多花 1 轮严重得多——问 1 轮 < 猜错白跑 1 轮 + 口径错数据。

什么算「判定不了」（脚本自动识别，你不需要自己判断）：

• 多店共享前缀 < 4 字（如"华强北"）——2~3 字多为地名 / 门店名前缀
• 共享前缀以门店 / 地名类词结尾（店 / 铺 / 馆 / 城 / 路 / 街 / 号 / 区 / 市 …）
• 关键词不在店名开头（位于中段）
• 共享前缀之后的分店标识过短或重复（如"店" vs "二店"）
• 多家店名无公共前缀（跨品牌同名）

怎么问：脚本已在 [阻断] 里给出可照抄的话术。用你所在环境的提问 / 选项工具（带选项的提问卡片）向用户确认；没有该工具就在回复里列出选项让用户选。

「<关键词>」匹配到 N 家门店，你想看哪一个？
  A. 整个品牌汇总（N 家合计）
  B. <门店1>（M 平台）
  C. <门店2>（M 平台）

问完怎么走（0 额外轮次）：

• 用户选 A（品牌） → 跑脚本给的品牌命令；若脚本提示"先向用户要品牌名"，就把品牌名问出来

（判定不了时脚本不会硬凑品牌名——--brand "华强北" / --brand "" 都会跑空）

• 用户选 B/C（某一家） → 直接抄脚本列出的那家门店命令

🔍 需逐条门店明细（含 alignmentId / shopUniqueKey）时：DKD_VERBOSE=1 python <脚本> …；默认不打印（省上下文）。

Step 2：多平台并列识别（核心 · 易错点）

⚡ 轮次纪律（先看这条，它决定会话成本）：

• 多平台 = 并行不增轮：N 个平台在同一个回合里发出 N 条命令（并行），总轮次仍是 1 轮。

禁止"跑一个平台 → 等结果 → 再跑下一个"（那是 N 轮，每轮都要重放全部上下文）。

• "整体 + 分平台拆解"根本不用拆：generate_brand_* / generate_store_* 1 条命令就含分平台卡片、饼图、门店榜（实测 generate_brand_daily.py --brand 创膳 直接输出 [分平台] {美团:9361, 淘宝:4302, 京东:2873}）。
• 只有"分平台各自的前N/排名"才需要 N 条命令（generate_platform_* 是单平台口径，必须带 --platform）。

⚠️ 关键判断信号（两套规则 · 不能混用）：

💡 核心原则：用户没明确说「要 N 个平台各自排行」就默认按对齐汇总——1 条命令。TOP/排名 才是触发「N 条命令」的信号，且触发后必须同轮并行。

Step 3：TOP N 识别

• 「前 10/前 20/前三/前五」→ --top N（默认 10，未指定 TOP 时也用 10）
• 「前 1/最高/榜首」→ --top 1
• 「全部/所有门店」→ 不限 Top（按所有门店）

⏱️ Step 4：时间标准化（4 步速查）

⚠️ 特殊场景补充（不在上表）：

• 实时 / 今天 / 现在 / 目前数据 → ① 实时优先：调 realtime 接口（品牌→query_realtime_summary；单店/门店→query_realtime_list）拿当天实时数据；② 实时无数据（返回空）→ 回退日报（默认昨日）
• 去年同期 / 同比 / 和去年比 → 对应报表内置对比参数（自动含同比口径，无需手动传）
• 前天 / 大前天 → 日报 + --date <YYYYMMDD>（按 Step 4 「昨日 – N」规则推导）
• 近N天数字映射（近3天=3 / 近7天=7 / 近14天=14 / 近30天=30 / 近60天=60）：详见「5.3 ② 近N天口语数字映射」。

Step 5：数据获取方式判定（必做 · 必须显式说明）

核心规则：同一条需求可能有三条路可走，选错就白跑。拆解必须产出一个明确的「数据获取方式」并写进回复开头——这是给用户的第一句交代，也是让用户当场纠偏的钩子。

判定顺序（三问定路 · 不得跳步、不得颠倒）：

Q1: 是不是"诊断/评估某门店"且要七维度判定？      → 是：② 门店诊断（走专属流程）
Q2: 是不是落在 9 类报表范围（门店/品牌 × 日/周/月/近N天/自定义区间）？ → 是：① 报表脚本
Q3: 以上都不命中 → ③ 接口编排（先过「8️⃣」执行闸门速查卡 → 再选 extend_query 或 chain_business）

⚠️ 三条硬约束：

• ① 与 ③ 不得互串：命中 9 类报表就不许改用 extend_query / chain_business 现编替代——报表脚本已内置环比对比期 / 商圈排名 / 门店分档 / 健康体检 / 6 层诊断框架 / 趋势图
• ② 是独立路径：门店诊断不走报表脚本、不做现场编排；诊断只出 widget，不产 HTML 文件
• ③ 必须先过速查卡再动手：走接口编排必须先过「8️⃣」执行闸门速查卡（4 类坑正解已内联）——日期格式（已由封装层自动归一：传 20260916 / 2026-09-16 / 今天 都通，不必判断是哪个接口）/ 单店必传项 / 平台限制 / 门店 vs 品牌维度，跳过必踩坑。速查卡已自足，无需跨文件读文档；仅调不通或需完整示例时，才按 §号 定点读 接口能力与应用场景.md。

💡 为什么必须"说出来"：客户说"看看XX门店最近表现"——可能是①日报、可能是②诊断、也可能是③编排的实时 TOP；三者产出物完全不同。把选择理由显式写出来，客户能当场说"我要的是诊断"，避免跑完一长串才发现方向错了。

Step 6：拆解 → 直接执行（不阻断 · 一轮闭环）

⛔ 禁止把拆解单独发成一轮、然后停下等用户确认。 拆解是内部动作 + 回复开头的声明——声明之后在同一轮内继续执行到交付。

只有命中下方「阻断白名单」才允许停下来问；其余一律用默认值 + 声明假设的方式往前推。

• 拆解结果写在回复开头（与执行结果同一条消息，不是先发一条问"这样拆对吗"）：

  需求拆解：
  ① 时间：昨日（2026-08-19）
  ② 主体：XX品牌（品牌整体）
  ③ 维度：3 平台并列 → 拆 3 个子查询
  ④ 指标 + TOP：商家实收 · 前 10
  ⑤ 展示方式：🎯 Widget 渲染（默认）
  ⑥ 数据获取方式：① 报表脚本 → generate_brand_daily.py --brand "XX品牌" --date 20260819
  子任务：
  - 美团外卖·XX品牌·20260819·收入 TOP10
  - 淘宝闪购·XX品牌·20260819·收入 TOP10
  - 京东外卖·XX品牌·20260819·收入 TOP10

• 同轮并行执行（关键 · 决定轮次成本）：上面 3 条平台命令必须在同一条消息内并行发出，总轮次 = 1；严禁"跑完一个再看下一个"（那是 3 轮，每轮重放全部上下文）
• 输出对齐：每个平台独立一张排行表，表头标注「[平台名] · [品牌] · [日期] · 收入 TOP N」
• ⚡ 若非"分平台各自排行"，而是"整体 + 分平台拆解" → 1 条 generate_brand_daily.py 即可（报告已内置分平台表/饼图/门店榜），不要拆

✅ 阻断提问白名单（仅此 2 类可停下问，其余一律不阻断）：

💡 声明假设 ≠ 提问：把"已按 X 口径输出，若非此意说一声"写在结果开头，用户看到不对可当场叫停——纠错收益与提问相同，但少花一轮。

拆解示例集（覆盖 80% 场景）

0️⃣ 🗺️ 执行索引（全文章节地图 · 编号检索入口）

💡 强制流程：任何需求先做 6 步拆解（§🧩 Step 1-6，其中 Step 5 必须产出「数据获取方式」），再按下方 3 大场景路由执行。

🗺️ 章节地图（编号 = 稳定 ID，按此检索，不要靠搜索）

⚠️ 编号说明（消除检索歧义）：本文章节编号为稳定 ID，不代表阅读顺序（阅读顺序 = 文档物理顺序）。

无 §10——历史编号已废弃，相关内容已并入 §9️⃣（AI 深度分析） 与 §1️⃣1️⃣（数据口径），不要查找 §10。

§1️⃣ 与 §0️⃣ 同属"首屏区"：§1️⃣ 执行锚点为全文第一入口，§0️⃣ 为其后的索引。

三大场景（互斥 · 先判定归属，再执行）

支撑规范（所有场景强制）

2️⃣ 🔀 三大场景路由（强制执行 · 最高优先级 · 先于一切流程）

任何需求，生成前先判定属于哪一类场景（3 类互斥、不得混淆），再按对应路径执行：

📢 数据获取方式必须显式声明（本节的落地动作）：判定场景归属后，必须在回复开头写清走哪条路拿数据（① 报表脚本 / ② 门店诊断 / ③ 接口编排）及其理由——对应「🧩 需求拆解 Step 5」。走 ③ 接口编排的，必须先过「8️⃣」执行闸门速查卡（4 类坑正解已内联，免跨文件读文档）。

场景	数据获取方式（显式写出）	运行期必读
① 报表生成	generate_* 一键脚本	仅本文件
② 门店诊断	generate_platform_diagnose.py → render_diagnosis.py	本文件「1️⃣4️⃣」+ 平台诊断逻辑文档
③ 接口编排	extend_query.py --action / chain_business.py	本文件「8️⃣」速查卡（已内联）；接口能力与应用场景.md 仅按需定点查

🚫 禁止条款（DO NOT）：

• 禁止为 9 类覆盖范围内的需求自写/复制编排脚本——generate_* 已内置环比对比期、商圈排名、门店等级分档、健康体检、6 层诊断框架、趋势图
• 禁止把「门店诊断」当普通报表或现场编排处理——诊断必须走「1️⃣4️⃣」专属流程
• 禁止改写脚本本体（generate_* / render_diagnosis.py / generate_platform_diagnose.py，需要新报表形态 → 走「8️⃣ 接口编排」产出 HTML/文字）
• 禁止命中一键脚本时用 extend_query / chain_business 现编替代
• 禁止把场景①②③混着做（如"诊断XX门店"却跑报表脚本再自己分析）

⚠️ 反面案例 1：生成「XX品牌 2026年7月 品牌月报」时，绕过 generate_brand_report.py，自写脚本 → 缺环比对比期/商圈/分档。9 类场景 = 一键脚本，没有例外。

⚠️ 反面案例 2：用户说"诊断XX门店"，却跑去跑 generate_* 周报脚本再"自己分析" → 缺七维度判定/健康分/分级行动建议。门店诊断 = 专属诊断流程（「1️⃣4️⃣」），没有例外。

3️⃣ 前置配置与安装

🚀 Token 配置（仅首次安装做一次 · 日常无需再跑）

⛔ 日常分析不要执行本节任何命令——脚本会自动读取配置、自动命中门店列表缓存，不需要先跑 check_token.py。

把 check_token.py 当作"每次运行的前置步骤"是常见误区：白烧一轮 + 一轮上下文。

只有两种情况才回到本节：① 首次安装配置 Token；② 取数报 401 / 「今日调用次数已达上限」。

1. 打开链接 → 【店客多 AI 技能中心】：https://ka.diankeduo.net/#/crayfish/index
2. 登录店客多账号 → 系统自动生成 Token（43 位随机字符串，以你账号实际生成的为准）
3. 填入配置 → 编辑 config.json，把 "mcp_token": "<客户Token>" 替换为真实 Token
4. （可选）验证配置 → python check_token.py，看到「状态: ✅ 可用」即通过；首次成功后会自动拉取并缓存门店列表（详见下方「缓存指纹机制」）

💡 完整流程 + 3 种配置方式 + URL 切换 + 错误码速查：详见 TOKEN.md。若报错是「门店范围为 0」（Token 有效但账号未授权门店）→ 属账号侧问题，去技能中心确认账号已绑定门店，换 Token 重试无效。

🗂️ 门店列表缓存机制（重要）

核心机制：门店列表缓存文件名绑定 Token 指纹——换 Token 自动失效重拉，无需 action=clear_cache。

1. 缓存文件命名规范

.cache/
├── shop_list_all_<token_fp>.json      ← 全平台门店列表（含指纹）
├── shop_list_meituan_<token_fp>.json  ← 美团门店（含指纹）
├── shop_list_taobao_<token_fp>.json   ← 淘宝闪购（含指纹）
├── shop_list_jd_<token_fp>.json       ← 京东外卖（含指纹）
└── metric_fields_<token_fp>.json      ← 指标字段（含指纹）

• <token_fp> = 当前 Token 的 SHA256 截前 8 位 hex（例：ad678271）
• 实测样例（当前 Token 指纹 = ad678271）：shop_list_all_ad678271.json

2. 自动失效原理

换 Token → SHA256 变化 → token_fp 变化 → 缓存 key 变化 → 旧缓存自然找不到 → 自动重拉

• 旧 Token 的 .cache/shop_list_all_<旧_fp>.json 文件仍保留在磁盘（不影响功能）
• 不需要手动清理，指纹机制已自动处理

3. 缓存更新机制（何时刷新）

默认场景全覆盖：除「新店开张 24h 内」和「数据陈旧」外，所有场景都自动处理。

4. 强制刷新门店列表（2 种方法）

方法 1：调 action=clear_cache（脚本级清理，仅清 .cache/，不动其他文件）

python chain_business.py action=clear_cache
# 输出：已清理 N 个缓存文件

方法 2：换 Token 自动重拉（无需清理旧文件，指纹机制自动处理）

# 编辑 config.json 替换 mcp_token
# 重跑 check_token.py（token_fp 变化，自动拉新缓存）
python check_token.py

💡 完整配置 + Token 三级优先级 + 多工具适配 + 上手引导：详见 TOKEN.md（完整接入流程）。

4️⃣ 目录结构（技能根目录）

📁 路径基准：下方为平铺结构（无子目录）。本技能不写死安装路径——目录名 dkd-brand-data-analysis/ 仅作示意，实际根目录 = 本 SKILL.md 所在目录；技能可整体复制到任意路径/机器，脚本靠 SKILL_DIR（由 __file__ 推导）自定位。

下表「运行期」列标明该文件在运行期是否可读——标注「禁读」的属开发期维护资料，内容已并入本文件，运行期翻阅只会拖长链路。

dkd-brand-data-analysis/                      # 技能根目录 = 本 SKILL.md 所在目录
├── SKILL.md                                  # 本文件（唯一权威规范）
├── TOKEN.md                                  # Token 接入完整流程（仅排障时读）
├── config.json                               # 独立配置（换 Token 改这里）
├── chain_business.py                         # MCP 接口封装（含缓存与异常处理）
├── check_token.py                            # Token 检查 + 门店列表缓存预热
├── generate_store_{daily,weekly,monthly}.py  # 门店对齐报表 ×3
├── generate_platform_{daily,weekly,monthly}.py  # 门店单平台报表 ×3
├── generate_brand_daily.py / generate_brand_weekly.py / generate_brand_report.py  # 品牌报表 ×3
├── generate_platform_diagnose.py             # 门店诊断取数（场景②）
├── render_diagnosis.py                       # 诊断 widget 渲染 + AI 诊断回填（场景②）
├── 美团门店诊断逻辑.md / 淘宝门店诊断逻辑.md   # 七维度判定权威文档（诊断时按平台读一份）
├── ai_diagnosis_*.json                       # AI 诊断回填数据示例（含 XX 占位符，非真实数据）
├── report_diagnostic_data.json               # 报表流取数导出（运行期产物，门店/单平台报表生成）
├── diagnostic_data_{平台}.json                # 诊断流取数产物（运行期产物，按平台一份）
├── ai_plan_{门店}_{平台}_{周期}.json          # ⑥ 优化方案回填（运行期产物：AI 写入，render_diagnosis.py --ai-plan 读取；包内不含示例）
├── extend_query.py                           # 接口编排高频示例
├── chart.umd.min.js / echarts.min.js         # 本地图表库副本（运行期不使用：图表一律走 CDN，见「8️⃣」）
├── diagnostic_template.html / diagnostic_widget_template.html  # widget 模板
├── 接口能力与应用场景.md                      # 【场景③ 按需检索手册】17 接口全清单 + 组合编排完整示例（§5.14~5.23）+ 单/多店速查 + 日期格式 + 平台限制；4 类坑正解已内联至「8️⃣」，**运行期非必读，按 §号 定点查**
├── 输出规范参考.md                            # 按需读（仅核对组件样式细节时）
├── 接口编排.md / 报表特性.md / USER_GUIDE.md  # 开发期维护资料 · 运行期禁读（内容已并入本文件）
└── .cache/                                   # 门店列表缓存（Token 指纹绑定）

输出文件：HTML / AI分析.md 生成在当前工作目录（可用环境变量 DKD_OUT_DIR 覆盖）；诊断/方案 JSON 一律放在本技能根目录。脚本结束时会打印产物完整路径——直接使用该路径，不要搜索文件。

5️⃣ 报表体系（9 种 + 近N天 + 自定义）· 命令唯一来源

本节是全部报表命令的唯一权威来源；「6️⃣ 核心工作流」与「13️⃣ 9报表诊断场景」只引用本节，不重复命令。

5.1 报表一览表（脚本与 SKILL.md 同目录，可从任意工作目录调用）

generate_platform_*（单平台）：--shop/--shop-id + --platform 均必填；该报表是单一平台独立视图（无「总→分」对比/分平台表/分平台主拖累诊断），保留商圈收入排行+核心指标+利润+流量漏斗+推广+评价+复购+取消+AI诊断。

--brand 必填规则：仅品牌报表（generate_brand_*）必填（不传提示指定并退出）；单店报表可选（仅同名精确过滤；--shop 匹配到多家跨品牌门店时脚本会提示补品牌）。品牌名 = 客户提示词中的品牌，禁止用示例名替代。

输出文件（HTML / AI分析.md）生成在当前工作目录，诊断文件在技能根目录。

门店定位：--shop <关键词>（模糊匹配：连续子串 或 按标点分词后全部命中，兼容同名门店跨平台命名差异，如美团「XX·甄选店（A店）」vs 淘宝「XX(A店)」）或 --shop-id <shopUniqueKey|平台门店ID>（精确），二选一必填。若模糊匹配 0 家 → 先用 search_shops 查一次拿到 shopUniqueKey，再改用 --shop-id（避免反复换关键词试错）。

工作流调整（两步取数）：①先 search_shops() 取 shopUniqueKey → ②再用 --shop-id 传 shopUniqueKey 调用脚本（更稳定，避免名称模糊匹配导致错店）

5.2 🚫 零硬编码 · 全部由用户提示词驱动

脚本内不存在任何固定时间、固定门店名、固定品牌名，所有报表均按当次调用参数生成：

AI 执行规则（强制 · 补充说明）：

• 表格已列参数 → 按表填写；未列项（如品牌）按下方判断
• 用户未提品牌时：单店报表直接不传 --brand 正常生成；仅当是品牌报表且未给品牌名时，先确认品牌名再运行
• 禁止用任何示例名替代用户提示词中的名称

5.3 🧭 提示词解析速查（用户问法 → 参数）· 含近N天智能路由

① 平台别名映射（用户提到平台 → --platform 值）：

② 近N天口语数字映射：

③ 门店 + 品牌 / 平台组合路由：

④ 歧义处理（仅意图不明显时确认，意图明确直接生成）：

核心原则：能用最少信息确定唯一报表 → 直接生成，不确认；存在多种合理解读 → 才确认。

✅ 意图明确 → 直接生成（不问）——以下情况参数自足，立即运行：

• 有明确门店名 + 时间（"XX门店昨天怎么样"）→ 单店日报
• 有明确品牌 + 时间（"XX品牌上周数据"）→ 品牌周报
• 有门店 + 平台 + 时间（"XX门店美团近7天"）→ 单平台周报 + --days 7
• 有明确品牌/门店 + "直接出/不用问/随便" → 用最合理默认（品牌整体 / 单店 + 昨日）并注明假设

⚠️ 意图不明显 → 先确认（禁止擅自默认）——存在多种合理解读时，不要自行假设后直接出报表：

• 只说品牌/品类词 + "数据怎么样/怎么样/看看"（如"XX品牌数据怎么样"）——未明确是品牌整体还是某单店、未给日期
• 只说"分析一下XX"而未给任何时间词（"分析一下XX品牌"→ 品牌 or 门店？哪一天？）
• 只说时间词（"这周数据"）但没给门店/品牌维度
• 品牌/门店名模糊匹配多家 → 需要澄清（如"文山店"可能有多平台）

确认清单（一次性问清 2 个参数）：

1. 维度：品牌整体？还是某家具体门店？（品牌 → --brand；单店 → --shop）
2. 日期范围：昨天 / 近7天 / 本周 / 本月 / 自定义区间？

标准确认话术示例：

"XX品牌"匹配到品牌 XX品牌（802 家门店）。请问要分析：

① 品牌整体 还是 某家具体门店（如XX门店）？

② 哪个日期范围：昨日 / 近7天 / 本周 / 本月？

确认后路由：维度（品牌→generate_brand_* / 门店→generate_store_* 或单平台 --platform）× 日期（昨天→日报 / 近N天→周报+--days N / 本周本月→周报月报 / 自定义→--start --end）。其他歧义：品牌报表未给品牌名 → 先确认；--shop 模糊匹配多家 → 补 --brand 或 --shop-id；品牌+门店+平台同时出现 → 平台报表优先（单平台口径信息最全）。

⑥ 近N天智能路由细则：识别 近N天/最近N天/过去N天/N天数据（N=3/7/14/30…）→ 加 --days N，用周报模板（含日趋势/周期汇总/环比对比）；周期=[昨日-(N-1), 昨日]，对比期=再往前推 N 天；近30天/近1个月同样用 --days 30（周报模板，非月报）；"近N天"未给门店/品牌 → 按⑤先确认维度。示例：generate_store_weekly.py --shop "XX门店" --days 7、generate_platform_weekly.py --shop "XX门店" --platform 美团外卖 --days 14。

判断规则：先按 门店 / 品牌 / 平台 定位维度，再按 时间词（昨天→日报、这周→周报、本月→月报、近N天→周报模板+–days N）定报表；只问"怎么样/数据"未给时间时，默认日报并询问周期。

品牌名 = 客户提示中的品牌（"分析XX品牌"的 XX），不是示例默认值。

6️⃣ 核心工作流（一键分析诊断闭环）

① 生成报表数据  → 运行 generate_* 脚本（命令见 5.1）→ HTML（AI 区为规则诊断占位）+ *_AI分析.md（规则版）
② AI 深度诊断   → 读取报表数据/诊断数据 → 写 ai_diagnosis_{门店/品牌}_{类型}.json（技能根目录）
③ 回填重跑      → 再次运行同一脚本 → 自动读取诊断文件 → 覆盖规则诊断
④ 对话内交付    → 五段式文字分析（图表由 HTML 卡片渲染，见「7️⃣」） + present_files 打开 HTML

6.1 一键生成报表

运行命令见 5.1。产出（当前工作目录）：

• {报表名}.html（可视化报表，AI 区为规则诊断占位）
• {报表名}_AI分析.md（五段式文字版，总览/亮点/问题&方案/行动建议/一句话结论；AI 诊断回填后自动生成 AI 深度版）

6.2 AI 深度诊断 + JSON 文件

读取 HTML 关键板块（KPI/分平台/商圈/趋势）+ 门店对齐 / 门店单平台报表导出的 report_diagnostic_data.json（品牌报表不导出中间数据文件，直接读 HTML 即可），按「9️⃣ AI 深度分析」6 层框架拆解，写诊断文件：

{
  "score": 88,
  "grade": "优秀",
  "verdict": "综合结论（数据+对比+定性判断）",
  "opportunities": ["亮点1（含数据）", "亮点2"],
  "risks": [["问题1（含数据）", "方案1"], ["问题2", "方案2"]],
  "report_date": "20260809"
}

report_date 强制匹配：日报=CUR_DATE、周报/月报=CUR_END_S、近N天=CUR_END_S——必须与报表周期末一致，否则回填时被跳过。

⚠️ risks 必须是「二元数组的数组」（每条 = [问题, 方案]）。若误写成字符串列表（["问题1","问题2"]），脚本会容错解析（整条字符串作为问题、方案取默认值）并在 stdout 提示，但方案列会全部退化为默认文案——请严格按上述格式输出。

⚠️ 回填失败不会静默：JSON 结构错误 / 日期不匹配 / 文件不可读时，脚本会打印 [AI诊断] 回填失败… 或 跳过… 并说明原因，此时报告为规则版诊断。看到该提示请修正 JSON 后重跑，不要当成已回填。

⚠️ 回填文件名（写代码时必看）：中间数据文件名里的门店/品牌名必须经 _safe_fname() 净化，且净化函数必须写在 f-string 的 {} 表达式内：

PYTHON复制

# ✅ 正确
f"ai_diagnosis_{_safe_fname(SHOP_NAME)}_{REPORT_TYPE}.json"
# ❌ 错误：函数名退化成字面文本，回填路径整体失效（脚本找不到文件，静默回退规则版）
f"ai_diagnosis__safe_fname(SHOP_NAME)_{REPORT_TYPE}.json"

门店名含 / : * ? " < > | 时，未净化的路径会直接写失败；写成上面第 2 种形式，即使门店名完全合法也匹配不到文件。改完建议本地跑一次回填链路验证。

6.3 回填 AI 诊断

再次运行同一脚本 → 自动读取 JSON → 校验 report_date → 匹配则覆盖规则诊断（HTML AI 区 + _AI分析.md），不匹配则跳过。

流程记忆点：

• 首次运行（规则占位）→ AI 读数据写 JSON → 重跑（自动回填 AI 版）
• 已有诊断且日期匹配 → 只需跑一次即出最终版
• 诊断日期不匹配 → 自动跳过，回退规则诊断（防跨日期/跨周期误回填）

6.4 🆕 AI 自动生成优化方案 JSON（⑥ 优化方案 · 二要素精简版）

新流程：AI 读取 diagnostic_data_{平台}.json → 按 schema 生成 ai_plan_*.json → render_diagnosis.py --ai-plan 渲染到⑥ 优化方案卡（完全替换默认规则 issues）

核心设计（二要素精简版）：⑥ 优化方案只展示 问题+方案 二要素，去掉所有数据/根因/预期标注，聚焦商家最关心的"问题是什么、怎么解决"。关键数据已隐含在 title 里（如"下单转化严重落后：17.23% vs 22.45%"），无需重复展示。

JSON Schema（ai_optimize_plan/二要素极简版）

{
  "schema": "ai_optimize_plan/二要素极简版",
  "shop": "XX品牌(XX门店)",
  "platform": "淘宝闪购",
  "period": "8月17日 ~ 8月23日（近7天）",
  "generated_at": "2026-08-24 14:00",
  "health_score": 55,
  "summary": "健康分 55（待优化）· 实收 ¥1,951 · 评分 4.9...",
  "items": [
    {
      "prio": "P0",
      "title": "下单转化严重落后：17.23% vs 均值 22.45%（-5.22pp）",
      "sol": "① 套餐重设 3-4 个引流套餐；② 福利区上架天天神券；③ 减配改可选加价；④ 餐盒费≤1元",
      "source": "ai"
    }
  ]
}

字段约束（推荐 · widget 30KB 上限自动裁剪兜底）

精简说明：相比早期版本进一步去掉 data 字段。商家阅读 ⑥ 卡片时最关注两件套：① 这是什么问题 ② 怎么解决。关键数据已隐含在 title 文本里（"下单转化严重落后：17.23% vs 22.45%"），不需单独展示。

命令（AI 一键渲染）

# 1) AI 写 ai_plan_{门店}_{平台}_{周期}.json（技能根目录；文件名自定，包内无示例文件）
# 2) 一键渲染：取数 + 判定 + 渲染 widget（套固定模板 + ai-plan 数据）
python render_diagnosis.py 
    --shop "XX门店" 
    --platform "淘宝闪购" 
    --days 7 
    --ai-plan ai_plan_XX门店_淘宝闪购_7d.json 
    --fetch --widget

与默认规则版对比

AI 何时使用 --ai-plan 模式

• 客户明确要求"深度分析/AI 写方案/精细方案"
• 需输出含具体数据的方案（非通用 SOLUTION_MAP 占位）
• 多门店对比需 AI 各自给出针对性方案时

示例文件

⚠️ 包内不含 ai_plan_*.json 示例文件——请按上方「JSON Schema」自行生成 ai_plan_{门店}_{平台}_{周期}.json（写入技能根目录）。

不要为找示例文件做任何搜索（首屏铁律：禁止搜索）；Schema 即唯一格式依据。

7️⃣ 输出规范（所有分析强制 · 最高优先级）

7.1 📐 文字版分析输出规范（五段式 · 一切交付的格式基准）

适用范围：9 类标准报表、近N天/自定义区间、接口编排、AI 诊断、任何自定义查询结果。格式基准：所有文字输出必须采用五段式结构（下方模板）。数据用 markdown 表格落表；图表一律由可视化组件（HTML 卡片）渲染，禁用 Unicode 文本图表。取数与呈现分离：脚本只输出 markdown 数据表，不生成任何分析文案；五段式由 AI 依据本规范在对话中组织。

① 五段式模板（与 *_AI分析.md 完全一致）：

# {主体}文字版分析 · {品牌/门店}（{场景类型}）
周期：{日期} ｜ {关键评分/合计口径}

## 一、经营总览
- KPI 行：实收 ¥xx ｜ 订单 xx ｜ 单均 ¥xx
- 核心结论句（+ 对比/占比）

| 维度 | 本期 | 对比 | 判断 |
|---|---|---|---|
| 实收 | ¥xx | ▲x.x% | ✅/⚠️ |
| 订单 | xx | ▼x.x% | ✅/⚠️ |

## 二、亮点
- **xxx** 实收 ¥xx，占 xx%，为收入贡献第一（含数据）

## 三、问题与解决方案
- **xxx 下滑 ¥xx（-x.x%）** → 💡 方案：按归因链拆解

## 四、行动建议（优先级）
P0｜止血……  P1｜放大/修复……  P2｜监控……

## 五、一句话结论
……

> 由店客多AI外卖运营提供数据服务

② 场景类型命名：标准报表用原类型名（品牌日报/门店周报…）；自定义用「{场景}扩展分析」——如 品牌扩展分析 · XX品牌（收入TOP10）、门店扩展分析 · XX门店（美团vs淘宝双平台对比）。

③ 数据呈现：markdown 表格 + ▲▼（涨/跌/持平）；排名变化 ↑2位/↓1位；KPI 行用 实收 ¥xx ▲8% · 订单 xx ▲5%。红涨绿跌（中国习惯）、金额 ¥ 千分位。

④ 深度完整性（强制 · 与简洁不冲突）：

• 分平台块标准结构：每平台 5 要素 = ① 实收/订单/占比 ② 环比 ③ 评分 ④ 商圈收入排行（第X/共Y·前X%判断）⑤ 一句话判断；所有平台都展示，不得省略；信息不存在标"无数据"
• 平台专属指标只能分平台展示（强制）：评分/商圈收入排行/店铺分 = 各平台自有体系，禁止合并/求均值/只展示主平台；平台无该指标时标"无数据"
• 判断先行：每条信息必须"数据 + 判断"（主因/亮点/风险/下一步），避免数字堆砌
• 评价场景分平台评分：每平台同时展示「平台展示评分（lastScore）」与「近30日评价均分」双口径，并附菜品/包装/配送分维度评分；缺失维度标"无数据"

⑤ 评分 / 商圈收入排行 / 店铺分 分平台展示逻辑（强化 · 强制）——三项均为平台专属指标，任何涉及多平台/对齐门店/品牌的分析，必须按下方规则逐平台展示，禁止合并、禁止求均值、禁止只展示主平台、禁止跨平台替代：

分平台展示规则（三平台并列时逐平台独立呈现，不得合并）：

1. 评分：美团 4.77 / 淘宝 4.21 / 京东 4.50 —— 各自展示、各自对比（pp 对比按各平台上周自身值），禁止输出"平均分 4.49"这类合并值
2. 商圈收入排行：美团 第 1/161 / 淘宝 第 12/80 / 京东 无数据 —— 每平台「第 X/共 Y + 前 X% 判断」（前10%优秀/前30%合格/其余需优化）；京东一律"无数据"，不得用美团/淘宝排名替代
3. 店铺分：美团 99.0 / 淘宝 85.0 —— 各自展示 + 等级判定；两平台构成不同，判定标准一致（≥90 优秀），但归因时按各自构成拆解（美团的短板是商家评分、淘宝的短板是活动丰富度等，不得套用另一平台构成）

📚 完整 widget 渲染规范（30KB 上限 / 五段式骨架 / 自检清单）：详见 §7.2.0

⚠️ 7.2.0 🚨 【强刷规范·强制 2026-08-24】五段式输出 = widget 渲染（无例外）

核心规则：任何 5 段式分析（总览 / 亮点 / 问题&方案 / 行动建议 / 结论）一律以 widget（show_widget）渲染。

❌ 禁止用 markdown 表格 / 纯文本要点 / Unicode 文本图表 代替 widget。

✅ 30KB 限制内做减法，不做替代——保留五段式结构骨架，超长按「4 段不裁 + 中段折叠」裁剪 widget 内中段。

📐「4 段不裁 + 中段折叠」规则定义（超 30KB 时的唯一裁剪法 · 强制）：

五段式中第 ③ 段（问题与方案）是中段，也是唯一允许压缩的段；其余 4 段一律不裁：

🚫 禁止的"减法"：① 丢掉任一整段；② 改用 markdown 表格/纯文本代替 widget；③ 把 ①②④⑤ 任一段塞进折叠。

✅ 超限自检：裁完若仍 >30KB，继续加深 ③ 段折叠层级，而不是裁其他段、也不是改成 markdown。

❌ 反例清单（5 类禁止 · 触发即不合规）

✅ 必须 widget 渲染的场景（9 类强制 · 触发词清单）

触发词识别：用户输入含 分析 / 诊断 / 查看 / 对比 / 走势 / 排行 / 评价 / 扫描 / 汇总 任一关键词 + 数据对象（门店 / 品牌 / 平台 / 品类）→ 必须 widget 渲染五段式，不允许 markdown 替代。

🚫 不需要 widget 渲染的场景（客户需求直接类 · 强制排除）

核心原则：widget 是「数据分析类」输出的展示形态；当客户需求是「直接交付文件/数据/网页」时，不走 widget。

判定口诀：

• 客户要"分析/诊断/查看/对比/走势/排行/评价/扫描/汇总" → widget 强制
• 客户要"下载/导出/生成网页/批量取数/整理申诉材料/打包" → 直接交付文件，无 widget
• 强刷规则仅约束"数据分析输出"的展示形态，不约束"文件交付"任务——5段式 widget ≠ 文件交付。

真实案例

• ✅ 分析XX门店美团近 7 天经营情况 → render_diagnosis.py --shop-id <uk> --platform 美团外卖 --days 7 --fetch --widget → 渲染五段式 widget（顶部 + KPI + 七维度 + 转化 + 分子项 + 评分 + 方案 + 结论）
• ❌ 下载XX门店美团近 7 天评价明细 → extend_query.py 或 chain_business.py 拉评价明细 → 写 CSV → present_files 交付（无 widget）
• ❌ 生成XX门店美团 8 月月报 → generate_platform_monthly.py --shop ... → 输出 HTML → present_files 交付（无 widget）

✅ 交付前自检 5 条（缺一不可）

• [ ] ① 五段式结构齐全？（总览 / 亮点 / 问题&方案 / 行动 / 结论，少一段即不合规）
• [ ] ② widget 渲染？（show_widget 调用已发出，对应 widget_code 已提取，非 markdown 表格）
• [ ] ③ widget ≤ 30KB？（超限按「4 段不裁 + 中段折叠」裁剪，禁止改 markdown）
• [ ] ④ 五段组件形态齐全？（① KPI 卡 / ② 绿边亮点卡 / ③ 红橙边问题卡 + 💡 / ④ P0/P1/P2 标签卡 / ⑤ 深色结论条）
• [ ] ⑤ 样式合规？（纯 inline style + table 布局；禁用 <style> 块 + class 选择器 + grid 布局）

⚠️ 违规后果：未通过自检 5 条中任何一条 → 视为未完成交付，需重新生成 widget。

7.2 📊 对话内输出规范（强制 · 标准交付方式）

一键生成/回填完成后，默认三件套同时交付：文字结论 + 可视化图表 + 打开 HTML 报表页面（present_files）。用户没说也要提——只要生成了 {报表名}.html，本回合就必须 present_files 打开。

严格五段式（对话内所有数据分析强制 · 无例外）：① 经营总览（KPI + 数据落表/可视化）→ ② 亮点 → ③ 问题与解决方案 → ④ 行动建议（P0/P1/P2）→ ⑤ 一句话结论。禁止"数据表格 + 要点"扁平交付；无结构 = 未完成。

五段式 widget 输出（强制 · 对话内 widget 一律按五段式骨架渲染）：任何 widget（HTML 片段 / show_widget）必须自上而下遵循五段式骨架，每段对应固定组件形态，禁止只渲染"数据表格 + 要点"扁平版：

① 五段组件形态表（强制映射）：

② 统一样式规格（所有 widget 段强制 · 与诊断配色规范一致）：

• 整体容器：background:#f5f7fa;padding:24px;color:#1a1a1a;max-width:1080px;margin:0 auto
• 内容卡：白底 #fff + 1px #e7ebf0 边框 + 圆角 12px + padding 18px 20px + 卡间距 12px
• 段标题：黄渐变序号块（22×22px，linear-gradient(135deg,#ffc107,#ff9800) 圆角 6px 白字）+ 标题文字 15px/700
• 判定徽章：绿 #16a34a 优秀 / 蓝 #3b82f6 合格 / 橙 #f59e0b 需优化 / 红 #dc2626 P0 / 灰 #9ca3af 后台确认（白字圆角 10px）
• KPI 数值：23px/700 黑；涨跌 pill 圆角 6px（红底红字涨 #fef2f2/#dc2626、绿底绿字跌 #f0fdf4/#16a34a——中国习惯红涨绿跌）
• 亮点/问题卡：左边框 4px（亮点绿 #16a34a / 问题红 #dc2626 或橙 #f59e0b）+ 浅底（#f0fdf4 / #fef2f2 / #fffbeb）
• P0/P1/P2：左边框 4px（P0 红 #e02e2e / P1 橙 #f59e0b / P2 灰）+ 标签块（24×22px 实色白字）
• 结论条：深灰底 #1f2937 + 白字 + 高亮黄 #fbbf24 + 圆角 12px + padding 18px 22px

③ 渲染规则（show_widget 兼容性 · 强制）：

• 纯 inline style + table 布局，禁用 <style> 块 + class 选择器 + grid（widget 渲染器兼容性差）
• 表格用 <table>（border-collapse:separate + border-spacing 控制间距）；行式信息用 td 内 display:flex
• 每段都渲染：②~④ 无内容时该段省略，但 ① 必含核心 KPI、⑤ 必有一句话结论；禁止把 widget 做成"纯 KPI 卡 + 数据表"的无结构版

④ 分场景五段式 widget 映射（各段放什么）：

⑤ 内容判定优先级（AI 智能筛选）：必提 P0 风险/异常（⚠️ 归零、突降、无效单激增）、显著涨跌（>±10%）、转化/复购短板、头部集中度、评分与商圈排名变化、平台结构突变；可省无变化/非关键数字（折叠进数据表备查）。

• widget 总大小 ≤ 30KB（含 SVG）——仅约束 widget（对话内 HTML 片段）；HTML 报表页面（.html 文件）不受此限，可包含完整图表库与大表格；超长按 §7.2.0「4 段不裁 + 中段折叠」规则定义裁剪
• 参考实现：render_diagnosis.py --widget（build_widget_fixed() 套固定模板 diagnostic_widget_template.html，已修复闭环）已按五段式骨架渲染（顶部渐变条+健康评分大卡→KPI 4 卡→七维度行式→转化 SVG 双图→店铺分子项→评分分析→P0/P1 左边框卡→深色结论）；其余 widget（TOP 排行/对比/趋势）按本表五段式骨架自主组织

AI 智能筛选（强制 · 非全量罗列）：

• 必提：P0 风险/异常（⚠️ 归零、突降、无效单激增）、显著涨跌（>±10%）、转化/复购短板、头部集中度、评分与商圈排名变化、平台结构突变
• 可省：无变化/非关键维度的数字（折叠进数据表备查）

下滑时中段插入归因链：实收% ≈ 订单% + 单均% → 订单端拆 曝光% + 转化% → 定性主因 → 分平台逐平台拆解。

平台主题色映射（强制 · 分平台可视化按平台色，不按"主平台红/其余蓝"）：

常用图表清单：

• KPI 概览卡组（6 卡） / 归因拆解+转化漏斗 / 分平台对比（占比条形） / 品牌分档 / 趋势图（日/周）

完整组件清单与场景映射见 输出规范参考.md（仅在需核对具体样式细节时读，勿为常规输出翻阅）。

8️⃣ 🔧 接口编排（场景③ · 内容已整合至 §6 + chain_business.py）

场景归属：本场景是「2️⃣ 三大场景路由」的场景③（接口编排 · 个性化需求）——9 大报表与门店诊断之外的任意需求（实时 TOP / 增长排行 / 评价归因 / 分平台对比 / 自定义编排…）。本章为指向型章节：流程性内容见 §6 核心工作流；底层 MCP 接口编排见 extend_query.py 与 chain_business.py。

🚨 执行闸门 · 速查卡（场景③ · 动手前必过 · 4 类坑「唯一正解」已内联）

本卡自足：照此执行即不会踩坑，无需再跨文件读文档。 6 类坑各有唯一正解，跳过必返工。

⛔ 红线 · 推广「写接口」永久禁用（最高优先级 · 无例外 · 不得规避）

下列接口会真实修改商家线上推广配置（预算 / 出价 / 投放时段 / 定向 / 开关），参数一旦有误即直接影响商家投放与资金，风险不可接受。

本技能内永久禁止调用 —— 已在 chain_business.py 的 call_mcp / _call_mcp_once / call_mcp_raw 三处收口硬阻断，命中即抛 [禁止调用]，无开关、无逃生参数。

🚫 禁止调用	风险	要看现状时改用（只读）
cpc_promotion_strategy_update（CPC 推广策略设置）	改动线上日预算/出价/投放时段，并可关闭整店推广	--action cpc-strategy
cpc_direction_update（CPC 定向更新）	整批覆盖语义 —— 某维度传漏就把原定向清零	--action cpc-direction
refresh_promotion_realtime（推广实时刷新）	✅ 不在此列：它是幂等只读刷新，允许调用	—

🔴 禁止以任何形式规避：不得用 ToolSearch 直连 MCP、不得改名传参、不得用 call_mcp_raw 直发 tools/call（同样被拦）。

若客户要求改推广配置 → 明确告知「需在平台后台人工操作」，AI 一律不得代改。

坑 0 · 动手前先查封装（不查就裸调 MCP → 白跑接口 + 绕开封装层自动归一）

走场景③的第一个动作是查封装，不是查接口。三层顺序，命中即停：

顺序	查什么	命中则
①	extend_query.py --action 的 17 个 action（见下方「高频 action 清单」）	直接用 action，不要自己写脚本
②	chain_business.py 的 query_* 封装（20 个，见 接口能力与应用场景.md §一）	from chain_business import query_xxx 直接调
③	前两者都没有	才用 call_mcp("<tool>", {...}) 现场编排（§一 未覆盖的接口）

⚠️ 不要用 ToolSearch / 查 MCP schema 作为第一步：MCP 工具是未封装层，直接对接会丢掉封装层的日期归一、门店键转换（shops_to_keys）、空池拦截、分类报错——这些坑一个都不会有人替你挡。

裸调 MCP 只允许出现在 ③，且必须是一次性的——若发现某接口会被反复用到（如本次「分时流量」），说明它该被封装：补 query_* 函数 + --action，而不是每次现场拼。

坑 0.5 · 门店定位一律用门店键（v1.1.22 起）

门店定位首选 --shop-key（shopUniqueKey，形如 1_17859827581；也可传 alignmentId / shopId，逗号分隔可多键）。

定位方式	行为
--shop-key 1_17859827581	✅ 精确命中；命中结果打印「N 家门店 / M 条平台记录」回显；任一键查不到 → 报错退出（码 2），绝不降级为全量
--brand X --shop Y	⚠️ 关键词交集匹配；命中多家门店 → 硬报错并列出候选门店键（含门店名/平台/alignmentId），引导改用 --shop-key
只给 --shop Y	⚠️ 同上报错（跨品牌同名店是重灾区）
只给 --brand X	品牌级查询（报表用），行为不变

实测踩中：--shop 龙华 跨品牌命中 3 家门店 / 8 条平台记录（BossLi·高压锅盖码饭 / MaxBoBo汕头沙茶牛肉饭 / 耿大叔·擂椒盖饭）——

旧逻辑会静默把三家店的数据合成一份结果。方案类任务（只服务一家店）必须用门店键。

确需批量多店时显式传 --allow-multi，不要靠猜。

坑 1 · 单店 / 多店传参（传错 → 直接失败，或静默只取第一家）

只接受单店 ⚠️（要多店就逐店循环调用，禁止塞多店列表）	接受多店
query_shop_score_head（店铺分）· query_menu（菜单）· query_food_analysis（商品分析）· query_event_list（活动）· query_hour_flow（分时流量） · query_cpc_strategy（推广策略） · query_cpc_direction（推广定向） · query_cpc_hour_analysis（推广分时）	search_shops · query_realtime_list · query_realtime_hourly · query_cpc_promotion · query_history_daily · query_evaluate_detail · query_order_period · query_order_profit · query_order_price_distribution · query_operation_log
—	⚠️ 特例：query_realtime_summary / query_history_summary 必须多店合并取总；query_history_list 必须 ≥2 家才有排名价值

坑 2 · 日期格式 —— ✅ 已由封装层自动归一：不必再记规则，也不需要判断是哪个接口

chain_business.py 在接口调用总入口（call_mcp）统一处理日期：传 20260916 / 2026-09-16 / 2026/09/16 / 2026年9月16日 / 今天 / 昨天 任何一种都可以，代码会按服务端要求自动转换（13 个带日期参数的工具全覆盖，含 beginDate 同名反义的 evaluate_detail 与 cpc_promotion_hour_analysis —— 该坑已在代码里封死，不必背）。

脚本层 --date 同样任意格式通用；认不出时统一报 ❌ 日期格式错误: X（--date 支持 YYYYMMDD / YYYY-MM-DD / YYYY/MM/DD，或 今天/昨天） 并退出码 2 —— 这是唯一的日期类报错，见到只需换成 20260916 重跑。

只需记住 4 条业务边界（代码无法替你判断）：

① 离线接口 end ≤ 昨天（T+1；要"今天" → 用 realtime_*）

② 跨度 ≤ 31 天：history_shop_list_data · history_shop_summary_data · order_profit_list

③ realtime_* 的日期只作对比基准日（previousDate，默认昨天），查当日数据本身不传日期

④ 无日期参数（传了报错）：shop_score_head · menu_query · event_list · cpc_* · shop_list_query · shop_search_query

💡 若看到 [date] 工具名.字段: 2026-09-16 → 20260916（已自动归一为 compact），说明该次调用绕过了脚本层（AI 现场编排裸调 MCP）—— 属正常兜底，不必处理。

坑 3 · 平台限制（京东属"功能缺省平台"，缺数据项要标"无数据"，不得静默省略）

接口	限制
query_shop_score_head	仅美团 / 淘宝闪购，京东拒绝
query_menu	京东无分类（categories 空）
query_order_profit	京东无活动数据（商家活动成本 0、优惠明细空）
query_evaluate_detail	不传 platform——靠 shopUniqueKey 前缀识别，传了报"不支持的平台"
query_food_analysis(shop_id_type="2")	alignmentId 只接受单个数字

坑 4 · 门店维度 vs 品牌维度（用错 → "品牌汇总"做成"单店"，客户以为看到了全部）

• 门店维度：search_shops 拿到门店池后，按 shopUniqueKey 逐店取 → 客户说"XX门店 / 这家店"
• 品牌维度：按品牌 / 全部门店聚合取 → 客户说"XX品牌 / 整体 / 全部门店"
• 两者不得混做：不得用品牌均值掩盖单店问题，也不得拿单店结论当品牌结论

坑 5 · 封装层禁缩减（MCP 出新能力时必须同步补封装，且入参必须全量透传）

服务端 MCP 会持续演进（新增工具、给已有工具新增入参）。封装层不得只承接一部分 ——

一旦某个入参只能靠裸调 call_mcp 才能用，调用方就丢掉了门店键转换 / 日期归一 / 空池拦截 / 分类报错四项保护，

而且不会报任何错（静默缩减 —— 这是最难发现的一类退化）。

触发	必须做的动作
服务端出现新工具	补 query_xxx() 封装 +（高频时）--action → 再更新 MCP_COVERAGE 声明表
服务端给已有工具新增入参	在封装函数上加对应参数并真实透传（禁止只加形参不传）→ 再更新 MCP_COVERAGE
专家副本同步（整函数替换后）	必须跑 check_defs.py <副本/chain_business.py>：副本是裁剪旧版，被替换函数引用的 helper 可能不存在（实测踩中 shop_count / _PAGE_LIMIT / _name_match / _degrade_list / _is_permission_denied），运行期直接 NameError（该脚本与 check_mcp_parity.py 同属开发维护工具，不随发行包提供）
日期区间（易被封装吃掉）	接口的 beginDate/endDate 是任意区间，禁止在封装层写死成"近 N 天 / end=昨天"；CLI 必须同时支持 --begin/--end（显式）与 --days N（相对）

🔍 自检入口：python extend_query.py --action mcp-parity

—— 拉服务端 tools/list 权威 schema 与封装层逐参比对，任一入参未承接即 FAIL（也校验写接口黑名单一致性、日期归一表覆盖度）。退出码 1 = 有缺口。

改动封装后必跑，全绿才算同步完成。（该动作依赖 check_mcp_parity.py —— 它属开发维护工具，不随发行包提供；发行包内跑此动作会明确报「找不到」而非崩溃）

📖 仅以下两种情况才需按 §号 定点读 接口能力与应用场景.md（它已降为"按需检索手册"，不再是必读）：

① 调不通（报 Expecting value / 平台不支持 / 参数错）→ 查该接口的逐条参数与返回结构；

② 需要完整示例代码——组合编排实战（§5.14~5.15）· 最少调用优化（§5.17）· 新能力用法（§5.19~5.23）。

按 §号 定点取用，不要通读（通读 15.0k，定点取用 ≈1~2k）。

工具选择：

extend_query.py 高频 action 清单（只列已封装好的）：

⚠️ 以下即 extend_query.py 的 ACTIONS 实际清单（17 个 · 以脚本为准），命名用连字符；evaluation_analysis / cross_platform_compare 等旧名未实现，勿引用。

⛔ 推广（cpc_* 族）平台范围：目前只支持 美团外卖 与 淘宝闪购 —— 京东外卖无推广策略 /

分时投放数据。门店键前缀即平台码（1 美团外卖 / 2 淘宝闪购 / 4 京东外卖）。

需要推广方案时只走美团外卖 / 淘宝闪购的键；承接推广方案生成的 dkd-promotion-strategy

技能已在「取数」与「出方案」两处做平台码硬校验，非 1/2 前缀的门店键直接拒绝出方案。

该技能的预算默认口径 = 按现行策略推广花费（v1.1.31 起；现行未设置时回退日均营业额 8% 档），

方案里的「现行推广方案对比」为按时间排序的逐时段变更清单（出价变化 / 预算变化并列）。

📅 日期区间的两种给法（v1.1.21 起） —— 接口的 beginDate/endDate 是任意区间，CLI 不再只支持"近 N 天"：

① 显式：--begin 2026-09-01 --end 2026-09-15（只给一端也行，另一端取默认：end 缺省=昨天、begin 缺省=end-(–days-1)）

② 相对：--days N（end=昨天、begin 往前推 N-1 天）

适用 hour-flow / cpc-hour / order-profit / price-distribution / operation-log；--end 落在今天会打 T+1 提醒但不阻止。

🚨 cpc-promotion 取数铁律（v1.1.17 起强制 · 不要为了省 15 秒跳过）：

推广实时数据是快照，cpc_promotion_realtime 直接读可能拿到几分钟前的旧值（日消耗/出价/曝光提升滞后）。

因此必须先触发 refresh_promotion_realtime（异步刷新）→ 等待 ≥15 秒 → 再取数，脚本已内置该流程：

• 默认行为：cpc-promotion 自动完成「刷新 + 等 15s + 取数」，单次约多耗 15 秒，不要传 --no-refresh
• 服务端限频：5 分钟才可触发一次刷新；窗口内自动跳过重复触发（打印「距上次刷新 Xs，跳过重复触发」），直接读取已有数据，不是报错
• 逃生开关：--no-refresh（跳过刷新，直接读快照，快约 15s，数据可能滞后）· --promo-wait N（改等待秒数，默认 15，上限 120）· 环境变量 DKD_PROMO_REFRESH=0（全局关闭自动刷新）
• Python 编排同理：query_cpc_promotion(shops) 默认已含该流程；手动调用可用 refresh_promotion_realtime() / wait_for_promotion_refresh(wait_seconds=15)

🌊 分时流量有两条路，别选错（v1.1.19 起已全部封装，不要再现场裸调）：

• 当日分时曲线 → --action realtime-hourly（realtime_hourly_summary_data，仅当天、无商圈基准）
• 近N天分时流量 → --action hour-flow（shop_hour_flow_analysis，支持区间 + 自带商圈均值 / 前10%）

hour-flow 默认只取合并 24 小时；--workday-split 追加工作日/周末分行（48 行/店）· --byday 追加按天展开（天数×24 行/店）；

返回每店 {merge, merge_wd, byday} 三口径原始 dict，取数配方与字段口径见 接口能力与应用场景.md §17。

📥 CSV / Excel 导出落点（明确 · 消除"承诺了却无命令可跑"）——用户说"导出 CSV / 下载表格 / 给我 Excel"时，按下表直接调用，不要现场自写脚本：

要导什么	命令
经营指标（日报/区间）	python chain_business.py action=history_daily beginDate=YYYYMMDD endDate=YYYYMMDD [brand=X] [quotaCodes=all] out=文件名.csv
门店列表（按平台/品牌）	python chain_business.py action=history_list beginDate=... endDate=... [brand=X] [platform=P] out=文件名.csv
区间汇总	python chain_business.py action=history_summary beginDate=... endDate=... [brand=X] out=文件名.csv
订单毛利明细	extend_query.py --action order-profit --shop X --days N
价格区间分布	extend_query.py --action price-distribution --shop X --days N

chain_business.py 的 action= 命令原生支持 out=*.csv（见脚本内 action=help）。generate_* 9 个报表脚本不产出 CSV（只产 HTML + _AI分析.md），勿向其传导出参数。

chain_business.py 现场编排场景：

• 自定义指标组合 / 自定义时段 / 跨接口数据拼接
• 调用 MCP 接口 → 自行渲染（HTML widget / Markdown 报告）

🚨 HTML 图表库规范（防「图表出不来」· 强制 2026-09-15 修订）：

• 图表库一律用稳定 CDN 源链引用，禁止内联 200KB 级单行库脚本——实测（2026-09-15）预览面板对超大单行内联脚本渲染异常（图表空白），小段内联脚本不受影响：
  • Chart.js 4.4.0：<script src="https://fastly.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js"></script>
  • ECharts 5.5.0：<script src="https://fastly.jsdelivr.net/npm/echarts@5.5.0/dist/echarts.min.js"></script>
• 备用源链（主源失败时 window.Chart || document.write("<script src='备用源'></script>") 同步回退，保持时序）：cdn.jsdelivr.net → cdnjs.cloudflare.com → cdn.bootcdn.net
• 禁止随手引未验证源：unpkg / bytecdntp 实测 404；只允许引用本规范列出的 4 个域名
• 标准 generate_* 脚本已内置源链（无需处理）；现场编排手写页面必须按上述源链引用
• 自检：页面外链只允许出现本规范列出的域名；generate_* 产出的页面在预览面板和系统浏览器都能出图

禁止改写 generate_* 脚本：

• 9 类需求已内置全功能（环比对比期 / 商圈排名 / 6 层诊断 / 趋势图）
• 需要新报表形态 → 走 §8 本章节流程（封装到 extend_query.py 或 chain_business.py），不复制标准脚本

9️⃣ 🧠 AI 深度分析（6 层框架 + 运营专家视角 + 诊断规范）

9.1 6 层框架（逐层下钻，不能只看总量）

分析诊断必须按此框架逐层下钻，不能只看总量——每层都要拆到"可行动的主因"：

① 总量层   实收 = 订单 × 单均          → 整体三因子拆解（下滑时必拆）
② 分平台层 每个平台独立拆解：
           实收% ≈ 订单% + 单均%
           订单% ≈ 曝光% + 转化Δ
           叠加评分/商圈排名/推广投放 → 定位"下滑平台 + 平台内下滑因子"
③ 商圈层   自身 vs 商圈均值 vs 前10%    → 倍数（曝光/进店/下单）、转化率 pp、排名
④ 时间层   环比（前日/上周/上月）+ 同比（上周同期/去年）→ 区分短期波动 vs 趋势性下滑
⑤ 结构层   平台占比变化、新老客结构、复购、毛利 → 健康度
⑥ 行动层   按 P0（止血）/ P1（优化）/ P2（放大）给可执行方案

核心方法——下滑归因链（必须逐层定位主因）：

实收下滑 -X% 
  → 拆：订单 -A% + 单均 -B%（谁贡献大谁是主因）
  → 订单下滑再拆：曝光 -C% + 转化 Δpp（流量端 or 承接端）
  → 定位到平台：哪个平台拖累最大？该平台内部又是哪个因子？
  → 结论 + 专属方案（如：京东实收-26.9% = 订单-30%+单均+3%，主因订单→查活动/排名）

规则版扫描器已内置（关键数据问题自动拆解）：

• 总量三因子 + 同比 + 单均/订单下滑
• 分平台逐平台拆解（任一平台环比<-5% 即输出：实收%≈订单%+单均%，主因判定，订单≈曝光%+转化Δ）
• 商圈对比（转化率低于商圈/前10%）、毛利、复购、取消、推广 ROI 阈值扫描

9.2 🎯 外卖运营专家诊断视角

AI 诊断必须站在专业外卖运营角度——不是罗列数据，而是用运营杠杆拆解问题、给可落地的运营动作。核心 6 大杠杆：

① 流量杠杆   曝光量/曝光结构（自然流量 vs 付费 vs 活动位）
             商圈排名（第X/共Y、前10%）、时段覆盖 → 流量是否充足、地位是否稳固
② 转化杠杆   漏斗效率（曝光→进店→下单）
             进店转化率（门头/首图/评分/活动标识）、下单转化率（菜单/价格带/满减/起送价）
③ 客单杠杆   单均实收、凑单设计（加购/套餐/第二份半价）、满减梯度合理性
④ 复购杠杆   复购率、老客占比、会员/储值、评价引导
⑤ 口碑杠杆   评分/好评率、差评标签集中度、评价回复率
⑥ 推广活动杠杆 ROI、占收比、活动档期节奏、预算分配（高转化平台加投）

诊断输出规范（verdict/问题&方案必须体现运营视角）：

诊断句式要求：每个问题 = 数据现象 → 运营归因 → 可执行方案（含具体动作/门槛/活动形式），避免"建议优化"类空话。

9.3 诊断深度要求（参考门店月报标准）

• 📝 verdict：数据 + 环比/同比 + 定性结论（如"回落属短期波动而非结构恶化"）
• 🟢 亮点 4-6 条（诊断深度建议，非 widget UI 限制；widget 场景可折叠）：盈利结构 / 平台均衡 / 转化率优势 / 商圈地位 / 履约 / 口碑
• 🔴 问题&方案 4-6 组配对（诊断深度建议，非 widget UI 限制）：每条问题带具体方案（归因拆解：实收%≈订单%+单均%，订单%≈曝光%+转化%）
• 诊断文件 JSON 结构：见「6.2 步骤②」；文件命名 ai_diagnosis_{门店/品牌}_{daily/weekly/monthly}.json，report_date 必须匹配报表日期（日报=CUR_DATE、周报/月报=CUR_END_S；近N天=CUR_END_S），不匹配自动跳过回退规则诊断，防跨日期/跨周期误回填

1️⃣1️⃣ 数据口径（关键 · 口径识别三问为唯一权威；§9️⃣ 诊断流程只引用不重复）

口径识别三问（任何分析取数前必过 · 强制）：

• 第一问 · 视角（主体）：客户要的是哪个视角？判定信号与默认值——

规则：提店名未提平台→对齐门店（默认）；提了平台→单门店；提了品牌→品牌。视角不明确时（店 vs 品牌、哪个平台都不确定）→ 优先按默认值执行 + 在回复开头声明假设（"已按 X 口径输出，若非此意请说一声"），不要为不确定性阻断提问；仅当两种口径的产出物实质不同、默认值无法覆盖时，才并列给出 2 个候选 + 差异请用户一句话选定（阻断白名单见「🧩 Step 6」）。深度分析结论必须归属正确：对齐=全平台整体、单门店=该平台该店、品牌=整体；不得混用（不得用全平台合并掩盖单平台问题、不得用品牌均值掩盖单店问题、不得把单店结论上升为品牌结论）。

• 第二问 · 字段粒度：① 字段是门店级 / 平台级 / 品牌级？② 客户要的是哪个？③ 有无多粒度近似字段？不得静默选一种——粒度由下方规律推导，并在输出中标注所用粒度；若两种粒度客户都可能需要 → 同轮一并呈现（不要为选粒度阻断提问）。常见粒度对照：

粒度规律（不靠记、靠推导）：字段名含 BusinessCircle → 门店级（该店所在商圈，逐店不同）；含 shopRanking/peerShopNum → 门店级；consumption/promotionExpenses/cubeCost → 门店级推广分项；summary 接口返回 → 品牌级；粒度由"字段语义+接口归属"决定，不由名称里的 Avg/合计 决定。

• 第三问 · 商圈/对比基准：
  • 商圈对比 = 每店各自商圈（强制）：涉及"门店 vs 商圈"（下单率/进店转化/曝光对比）时，必须用该门店自己所在商圈的均值（list 接口 orderConversionBusinessCircleAvg 等字段随记录返回，各店不同），禁止用"平台平均商圈值"当所有门店的基准——那是错误口径（曾把美团平台平均 24.04% 当全部门店商圈基准，导致误判 86 家）。批量门店分析时商圈字段搭进 query_history_list 一次带全（2 次调用），不要逐店/逐平台另查 daily。
  • "vs 平台/大盘" → 平台级汇总；"vs 品牌" → 品牌均值。仅客户明确要对比时才引入均值口径。
• 财务口径：财务估算毛利 = 估算财务净毛利 + 门店推广花费；财务估算净毛利 = 估算财务净毛利；毛利率/净毛利率 = 对应毛利 ÷ 财务收入（未扣自动充）。页面不出现英文字段名（billProfitCpc/billRevenueNotAuto 等仅公式注释，公式只在利润板块用纯中文展示）
• 评分构成：从评价明细统计（过滤 invalidType 无效后：好评4-5星/中评3星/差评1-2星），与负面标签同源；评价总数行标注「有效 X 条 · 无效 Y 条」
• 评分双口径（评价分析必须区分）：① 平台展示评分 = 明细的 lastScore（平台计算、带历史权重、滞后于近期口碑）；② 近30日评价均分 = 有效评价 commentScore 的算术平均（反映近期真实口碑）。两口径差异大时是危险信号（如展示分 4.7 但近30日均分 3.82），必须同时呈现并解释背离；分维度评分 = 菜品 orderCommentScore / 包装 packingScore / 配送 deliveryCommentScore（0 值视为未评，跳过不计）
• 负面标签（容错双轨，强制）：评价明细的负面标签字段为 labels（EVALUATE_HEADERS 已映射「评价标签」）。接口可能返回、也可能不返回该字段（实测 evaluate_detail 当前不携带，全平台全记录均无），处理规则：
  • ① 若明细含 labels → 直接用平台真实标签归因（比人工归类准确），按标签统计条数，输出标注"来源：平台评价标签"
  • ② 若明细无 labels → 回退为差评内容（commentScore≤2）人工归类（如肉质/酱汁/份量/配送/售后主题），输出必须注明"平台未返回标签，按差评内容归类"，不得假装是平台标签
  • ③ 聚合脚本需做字段存在性检查（'labels' in record），禁止假定一定有或一定没有；仅统计有效评价（排除删除/不计入评分）
• 导出列 JSON 已源头解析（强制）：评价明细 CSV 中「点赞菜品/点踩菜品/评价图片/订单详情」等 JSON 字段由脚本 _json_to_text 在导出时自动解析为可读文本（字符串列表"、"分隔；订单详情"名称×数量"），导出文件不出现原始 JSON；AI 聚合评价时直接读 CSV 文本字段，无需二次解析
• 申诉成功评价列表：评价板块含「⚖️ 申诉成功评价」（appealSuccess==2），展示评分/平台/内容
• 商圈排名：list 接口（shopIdType=1）单店形式获取，已并入 QUERY_CODES 一次查询（summary 0 调用）
• 商圈流量对比：daily 接口 + shopIdType=1；周报/月报取周期汇总（量字段求和、比率字段日均）
• 评分：周期内最新（lastOfShopScore），分平台对比行含评分 pp
• 营业天数：日实收>0 天数（月报分母按自然月天数）
• 单平台查询优化：门店单平台报表只查 shopIdType=1 分平台数据（当期/环比/同比 3 次），跳过被覆盖的全平台汇总查询

1️⃣2️⃣ 接口异常处理（chain_business.py 内置）

先看这张「报错原文 → 唯一行动」表定位，再动手。报错不等于 Token / 门店有问题——多数报错与它们无关，先按原文对号入座，禁止一见到报错就去查 Token 或换门店关键词。

HTTP 状态处理（内置）：

1️⃣3️⃣ 📋 9 报表分析·诊断场景（只讲"分析什么 / 诊断看什么"，命令见 5️⃣）

门店对齐报表

门店单平台报表（单平台口径）

品牌报表（全品牌汇总）

💡 场景选择速查：用户问法 → 报表的映射见上方 3 张表「用户问法（触发示例）」列；近N天/自定义区间在表格中已包含时间触发词。

1️⃣4️⃣ 🔬 门店诊断（美团 / 淘宝闪购 · 按平台路由）

场景归属：本场景是「2️⃣ 三大场景路由」的场景②（门店诊断）——诊断有专属取数（generate_platform_diagnose.py 独立脚本）与判定流程（平台诊断文档七维度），不属 9 类报表、不现场编排；任何"诊断门店"类需求必须走本节流程。

触发：客户说"诊断XX门店 / 帮我诊断店铺" → 按平台路由：提到美团 → 美团诊断逻辑；提到淘宝/闪购/饿了么（饿了么并入淘宝闪购）→ 淘宝诊断逻辑；未指定平台 → 美团优先（诊断体系最全）。

数据获取（先取数，拿不到才引导）：

① 一键取数（独立诊断脚本 · 与周报完全分离）

python generate_platform_diagnose.py --shop X --platform <美团外卖/淘宝闪购> --days 7

• 仅 5 次接口：当期+上期分平台列表 ×2 + 评价明细 + 店铺分子项 shop_score_head + 商圈基准 daily
• 不查同比/日趋势、不生成 HTML——诊断只需环比与七维度数据
• 实测耗时 ≈2s；输出 diagnostic_data_{平台}.json
• 输出含：biz_cmp（商圈均值/前10%）、score_analysis（评分分析）
• 用户指定周期（近30天/本月等）按指定

② 一键 widget 渲染（对话内首选）

python render_diagnosis.py --shop X --platform <美团外卖/淘宝闪购> --days 7 --fetch --widget

• 一条命令闭环：自动取数 → 读 diagnostic_data_{平台}.json 七维度判定 → 套固定模板 diagnostic_widget_template.html 渲染五段式 widget
• 通过 ===WIDGET_BEGIN=== / ===WIDGET_END=== sentinel 输出到 stdout
• AI 直接提取片段 → show_widget 渲染到对话内（无需写 HTML 文件）

分两步时：

1. generate_platform_diagnose.py --shop X --platform P --days 7 取数导出
2. render_diagnosis.py --widget 渲染（--shop 缺省自动从 diagnostic_data_{平台}.json 读门店）

诊断与周报完全分离：诊断流程只输出 widget（不生成 HTML 文件），周报流程只生成 HTML+md——按需选用，不混合。

③ 判定 = 脚本已产出（禁止整读 diagnostic_data_{平台}.json）

判定结果由 render_diagnosis.py 直接输出在 stdout 的 ===DIAG_BRIEF_BEGIN=== … ===DIAG_BRIEF_END=== 块内——含七维度分级（优秀/合格/需优化）、问题优先级（P1~P6）、一句话结论，实测约 0.5k token。AI 引用该块即可组织五段式回话与 widget，无需再读 HTML 或现场检索。

⛔ 禁止整读 diagnostic_data_{平台}.json：该文件保留 30+ 条评价明细，实测 27,648 字符 ≈ 10k token，

整读 = 多烧一轮 + 约一万 token，而判定结论已在上面的 BRIEF 块里。仅排障时（如某维度疑似漏判 / 需回溯原始评价）才定点查该 JSON 的对应块。

<details> <summary>数据块 → 内容对照表（<b>仅供排障时定点查询，正常运行不需读</b>）</summary>

</details>

排障时字段先读后取（强制）：定点读 JSON 时先打印 list(d.keys()) 与 list(d['summary'].keys())，只按实际存在的键取值，禁止凭记忆写字段名。

真实事故：曾用 repeatRate 取值而实际字段为 sevenRepeatReta，导致复购误判"无数据"。

"无数据"判定依据（强制）：依据 summary_missing 字段（脚本已记录接口未返回的字段清单），或确认键存在且值确实为 0。禁止仅因取值打印为空而判"无数据"。

口径唯一（强制）：③ 下单转化率一律用 summary.orderConversionRate（进店→下单）对比 biz_cmp.<平台>.orderConversionRateAvg / top_ocr，禁止用 comprehensiveConversionRate（综合转化率是派生指标，勿混）。

④ 一键渲染（效率优先 · 判定+报告自动产出）

python render_diagnosis.py --shop X --platform P --days N [--out 目录] [--fetch] [--widget] [--no-ai]

• --fetch 一条命令闭环：自动取数 + 判定 + 渲染，无需先跑取数
• --widget 输出对话内五段式 widget 片段（套固定模板，配 --fetch 一步闭环）
• 七维度阈值已代码化（与两平台诊断逻辑文档对齐）：

• 读 diagnostic_data_{平台}.json + ai_diagnosis_* 后自动判定 + 套 diagnostic_template.html 渲染
• 输出：① 完整版 HTML ② 对话版 fragment（适配对话内渲染规范）③ 控制台一行式结论（供五段式组织）
• --shop 可省（自动从诊断数据读取，规避全/半角括号差异）
• AI 只需审核判定 + 微调 ai_diagnosis JSON，不再手写 HTML

诊断三步闭环：取数（①）→ 一键渲染（④）→ present_files / 对话内渲染；--fetch 可合并为两步。

模板全页样式统一（卡片/徽章/KPI/表格/间距 6 套规范 + 评价板块紧凑诊断结论形态）见 输出规范参考.md「🎨 诊断渲染规范」。

⑤ 结论兜底

当 AI 未写 ai_diagnosis_*.json（verdict 字段为空）时，render_diagnosis.py 自动按 dims 评分生成 rule-based 一句话结论（数据 + 主因 + 预期），不再显示"AI 结论待补充"占位；有 AI verdict 时优先用 AI 版。

⑥ 可判定维度（用接口数据）

门店开业信息 = 独立展示项（非判定维度）：数据源从 list 接口 shopInfo.beginTime（格式 YYYY-MM-DD HH:MM:SS）提取 earliestOpenDate/firstOpenTime/openDays（基于诊断周期末计算），渲染端按 openDays≤30 标「新店 🆕」徽章（仅标识不判优劣，见各平台诊断文档「门店开业信息」）。

诊断判定字段映射表（七维度 × 字段 × 对比基准 · 强制）：下方为通用版总纲；两平台各自的字段明细（含平台专属字段与口径）以 美团门店诊断逻辑.md / 淘宝门店诊断逻辑.md 顶部「0️⃣ 诊断判定字段映射表」为准，判定时按对应平台文档查表取数。

新老客拆分判定（强制）：③④ 必须看新老客拆分——新客转化显著低于老客时（如某店：新客下单约 10% vs 老客约 39%），问题定性为「新客承接弱」，方案聚焦新客活动（新客立减/首单券/新客专享套餐），不能只看总体转化率；总体低于商圈均值但新老客均接近基准时，才归因于菜单/价格带。

⑤ 复购判定一律用近 7 日复购（sevenRepeatReta）；30 日复购（thirtyRepeatReta）仅作参考展示，不得用作判定字段。

1. 需引导排查维度（接口无数据 → 引导用户到商家后台查看后回填）：
   • 店铺分（100 分制 ≥95 优秀 / ≥90 合格；总分子项接口有则判，无则引导商家后台「门店管理/店铺分」；店铺分构成两平台不同，见各平台文档）
   • 自然/付费流量占比 → 引导「经营数据/推广后台 → 流量来源」
   • 商家配置项（菜品 SKU/分组/福利区/明厨亮灶/海报/店招/橱窗/公告/餐盒费/减配金额等）→ 引导「门店装修/菜品管理」逐一排查

两平台诊断区别对照（重要，判定时按平台选用）：

诊断输出：按 7 大维度逐项给「优秀 / 合格 / 需要优化」判定 + 数据支撑 + 建议（配置类给"建议有/建议X"）；接口判不了的维度明确标注"需商家后台确认"并列出排查项，不得凭空判定；结尾附「推荐平台官方功能」名称清单（只给功能名，按平台清单）。

⚠️ 偏低必挂方案（强制）：凡判定为「需要优化」或「合格偏低」的维度，必须自动挂接对应解决方案——严格按各平台文档「十、诊断结果→解决方案映射」执行（含可调用的分析能力如 评价分析/推广诊断/差评申诉/自动回复，及平台功能名），不得只给判定不给方案、禁止 AI 自创或空泛建议（如"按运营杠杆整改"类占位）。代码已固化：render_diagnosis.py 内置 SOLUTION_MAP（与两平台文档「十」映射表逐条对齐），规则版问题卡自动挂接；AI 深度版 risks 的「→ 方案：」内容原样呈现。判定「优秀」的维度可跳过。

诊断卡片形态（强制 · 对话内渲染）：信息量不减的完整五段式，六段齐全、禁止极简砍信息（如只给七维度网格）：① 标题+周期行 → ② 维度判定网格（7格：收入排名/曝光/下单转化/入店转化（含店铺名称子项）/复购/综合评分/店铺分，优秀绿/需优化红/需关注琥珀）→ ③ 优秀维度（数据判定）→ ④ 需优化维度挂方案 → ⑤ 行动建议 P0/P1/P2 → ⑥ 一句话结论+数据来源。开业信息放周期行尾（· 开业 {日期}（约{时长}），openDays≤30 标「新店」）。表现方式（强制）：诊断默认以「对话内 HTML 展示页/widget」渲染——配色/版式/页面结构/分平台展示/widget 固定模板详见 输出规范参考.md「🎨 诊断渲染规范（完整版）」（含 6 套设计系统 + 14 块页面结构 + diagnostic_widget_template.html 55 占位符 + 分平台展示规则 + 全半角括号坑）；诊断页不要用 var(--color-background-*) 系统变量版式。不设 无障碍标题（用户要求：直接显示诊断报告正文即可，省略无障碍标题）。③ 下单转化格必须显示 orderConversionRate 正确值（如 27.2% 优秀）；综合转化率 comprehensiveConversionRate（如 0.81%）只作④入店转化维度的成因解释，禁止填入③、禁止出现在"需优化"区。

完整判定标准：见同目录 美团门店诊断逻辑.md / 淘宝门店诊断逻辑.md（七维度全部阈值 + 检测项 + 综合评分/店铺分公式与子项权重 + 官方功能表）。