@scorehub/creator-outreach 1.9.0 → 1.10.1

package/.codebuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tiktok-creator-outreach",
-  "version": "1.9.0",
+  "version": "1.10.1",
   "description": "ScoreHub AI's TikTok creator marketing expert for building clear creator profiles and validating focused collaboration shortlists across 13 markets in Southeast Asia, the United States, and Europe.",
   "author": {
     "name": "Ben",
@@ -13,7 +13,8 @@
     "./skills/tiktok-creator-search",
     "./skills/tiktok-creator-analysis",
     "./skills/tiktok-batch-outreach",
-    "./skills/tiktok-similar-creators"
+    "./skills/tiktok-similar-creators",
+    "./skills/tiktok-affiliate-analytics"
   ],
   "expertType": "agent",
   "agentName": "tiktok-creator-outreach",
@@ -26,8 +27,8 @@
     "zh": "TikTok 达人营销专家"
   },
   "displayDescription": {
-    "en": "Tiky is ScoreHub AI's TikTok creator marketing expert. She builds creator profiles and validates focused outreach shortlists.",
-    "zh": "Tiky 是 ScoreHub AI TikTok 达人营销专家，建立达人画像并小范围建联验证。"
+    "en": "Tiky is ScoreHub AI's TikTok creator marketing expert for creator profiles, shop analytics, and focused outreach.",
+    "zh": "Tiky 是 ScoreHub AI TikTok 达人营销专家，达人画像、小范围建联验证及经营分析"
   },
   "avatar": "avatars/scorehub-ai-white.png",
   "categoryId": "07-SalesCommerce",
@@ -60,8 +61,8 @@
       "zh": "帮我找一批适合我店铺品类的 TikTok 达人"
     },
     {
-      "en": "Evaluate the collaboration value of these creators",
-      "zh": "帮我评估这几个达人的合作价值"
+      "en": "Analyze my shop's affiliate performance and product results for the previous calendar month",
+      "zh": "分析我店铺上个月的联盟经营和商品表现"
     }
   ]
 }

package/README.en.md

@@ -4,6 +4,10 @@ Chinese version: [README.md](./README.md)
 
 **ScoreHub AI TikTok Creator Marketing Expert · Tiky** is ScoreHub AI's creator marketing expert for TikTok Shop sellers. Tiky discovers suitable creators by category, GMV, units sold, follower count and age/gender profile, content performance, and collaboration traits, then combines recent commerce, content, category, and audience data into clear, comparable creator profiles. Sellers can use those profiles to select a focused shortlist and quickly validate collaboration hypotheses through targeted outreach. Tiky is not a mass-messaging tool for contacting thousands of creators. TikTok operations run through ScoreHub MCP, and ScoreHub manages the TikTok API credentials so users do not need to configure them.
 
+## Shop Analytics
+
+Tiky's fifth Skill provides read-only analysis of authorized shops, including shop overview, affiliate contribution, product performance, product affiliate orders, and top creators by product. It checks authorization and data readiness before querying a single day or month.
+
 ## Supported Markets
 
 Tiky currently covers 13 country markets: Indonesia (ID), Thailand (TH), Malaysia (MY), Vietnam (VN), the Philippines (PH), Singapore (SG), the United States (US), the United Kingdom (GB), Germany (DE), Italy (IT), France (FR), Spain (ES), and Ireland (IE). The Agent specification is authoritative for this market boundary.
@@ -81,6 +85,7 @@ Ask Tiky:
 - Find 20 beauty creators with 10K-100K followers, at least 60% female followers aged 18-34, GMV of $1K+, 5K+ average shoppable-video views, independent status, and fast growth.
 - Analyze the sales performance of these 10 creators and rank them.
 - From the top five, select the three best-matched creators, choose one benefit-first offer, preview its first 15 notification characters, and start a focused outreach validation.
+- Analyze my shop's affiliate performance and product results for the previous calendar month.
 
 ## Troubleshooting
 

package/README.md

@@ -4,6 +4,10 @@ English version: [README.en.md](./README.en.md)
 
 **ScoreHub AI TikTok达人营销专家 · Tiky** 是 ScoreHub AI 面向 TikTok Shop 卖家打造的达人营销专家。Tiky 可按类目、GMV、销量、粉丝量级与年龄/性别、内容表现和合作特征发现合适的达人，结合近 30 天带货、内容、品类和受众数据建立清晰可比较的达人画像，并通过精选后的小范围建联快速验证合作假设。Tiky 不是面向成千上万达人的海量群发工具。TikTok 操作通过 ScoreHub MCP 完成，TikTok API 凭证由 ScoreHub 托管，使用者无需配置。
 
+## 数据分析
+
+Tiky 的第五个 Skill 支持只读复盘已授权店铺的经营总览、联盟贡献、商品表现、商品联盟订单和商品 TOPN 出单达人。分析会先检查店铺授权和数据是否就绪，再按单日或单月范围查询。
+
 ## 支持市场
 
 Tiky 当前覆盖 13 个国家市场：印度尼西亚（ID）、泰国（TH）、马来西亚（MY）、越南（VN）、菲律宾（PH）、新加坡（SG）、美国（US）、英国（GB）、德国（DE）、意大利（IT）、法国（FR）、西班牙（ES）和爱尔兰（IE）。市场边界以 Agent 规范为准。
@@ -82,6 +86,8 @@ node packages/creator-outreach/install.js bootstrap --dev --install --json
 - 分析这 10 个达人的带货表现，帮我打分排名
 - 从排名前 5 位中选出最匹配的 3 位，选择一种利益前置 Offer，预览通知栏前 15 字后发起建联验证
 
+- 分析我店铺上个月的联盟经营和商品表现
+
 ## 故障排查
 
 ### 找不到受支持的客户端

package/agents/tiktok-creator-outreach.md

@@ -13,6 +13,7 @@ skills:
   - tiktok-creator-analysis
   - tiktok-batch-outreach
   - tiktok-similar-creators
+  - tiktok-affiliate-analytics
 ---
 
 # ScoreHub AI TikTok达人营销专家 · Tiky
@@ -58,7 +59,7 @@ bootstrap 返回 `ready` 后，再识别以下明确意图：
 
 > 你好，我是 Tiky，ScoreHub AI 的 TikTok 达人营销专家。我先帮你建立清晰准确的达人画像，评估合作价值，再对精选候选人进行小范围建联验证。我不是面向成千上万达人的海量群发工具。以下是我能帮你做的事情：
 >
-> ## 四大核心能力
+> ## 五大核心能力
 >
 > **1. 搜索达人** — 从 TikTok Creator Marketplace 多维度筛选
 > - 按品类、用户名或昵称
@@ -80,6 +81,18 @@ bootstrap 返回 `ready` 后，再识别以下明确意图：
 > - 用于验证精选名单，不以海量发送为目标
 > - 智能控制发送频率，降低触发频率限制的风险
 >
+> **4. 相似达人推荐** — 以目标达人为模板，寻找带货表现特征相似的其他达人
+> - 从搜索结果中选择一位目标达人，拓展新的合作候选
+> - 支持按需调整推荐数量，实际返回以可用候选为准
+> - 按相似度排序，并展示相似度、数据置信度和差异化亮点
+> - 推荐结果可继续用于达人画像分析和精选建联验证
+>
+> **5. 数据分析** — 按单日或单月复盘已授权店铺的联盟经营和商品结果
+> - 查看店铺整体经营、趋势变化和联盟渠道贡献
+> - 分析商品表现、商品联盟订单以及重点商品的出单达人
+> - 结合有效历史关联，整理达人贡献、订单结果和可识别的风险与机会
+> - 只读取已授权且完成同步的数据，不会自动同步、修改业务数据或发起建联
+>
 > ## 支持的市场
 >
 > 当前覆盖 13 个国家市场：东南亚的印度尼西亚（ID）、泰国（TH）、马来西亚（MY）、越南（VN）、菲律宾（PH）、新加坡（SG），美国（US），以及欧洲的英国（GB）、德国（DE）、意大利（IT）、法国（FR）、西班牙（ES）、爱尔兰（IE）。
@@ -130,6 +143,11 @@ bootstrap 返回 `ready` 后，再识别以下明确意图：
 - 默认返回 20 位相似达人，可按需调整为 1–50。
 - 外部评分、候选筛选、召回策略和结果展示完整遵循 `tiktok-similar-creators` Skill，不在 Agent 中重复定义。
 
+### 5. 店铺联盟经营数据分析
+复盘已授权店铺在单日或单月范围内的店铺经营、联盟贡献、商品表现、商品联盟订单和商品 TOPN 出单达人。
+- 分析准入、日期规则、五个分析场景和只读工具编排完整遵循 `tiktok-affiliate-analytics` Skill，不在 Agent 中复制指标或 SQL。
+- 分析结果中的本店历史事实与官方达人当前画像分开表达；分析不会自动同步数据、建联、发消息或修改业务数据。
+
 ## 标准工作流程
 
 当你找到我时，通常走这三步：
@@ -194,6 +212,9 @@ Step 3: 小范围建联验证
 - `create_conversation` — 创建达人会话（建联前置，用 `creator_open_id`）
 - `send_message` — 发送建联消息
 - `find_similar_creators` — 以目标达人为模板寻找相似达人
+- `get_analytics_readiness` — 查询分析店铺、数值 ID 映射和同步准入
+- `analyze_shop_overview` / `analyze_affiliate_contribution` / `analyze_product_performance` — 店铺、联盟和商品经营分析
+- `analyze_product_affiliate_orders` / `analyze_product_top_creators` — 商品联盟订单和出单达人分析
 - `authorize` — OAuth 授权；切换店铺时传 `{ "switch_shop": true }`，切换账号时传 `{ "force": true }`
 - `status` — 连接状态
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scorehub/creator-outreach",
-  "version": "1.9.0",
+  "version": "1.10.1",
   "description": "ScoreHub AI TikTok达人营销专家 Tiky — Agent 定义 + Skills 配置",
   "engines": {
     "node": ">=18"

package/skills/tiktok-affiliate-analytics/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: tiktok-affiliate-analytics
+description: 分析已授权且已完成数据同步的 TikTok Shop 店铺联盟经营数据，覆盖店铺、联盟、商品、有效联盟订单和商品 TOPN 出单达人画像。用于店铺经营分析、商品联盟结果、商品出单达人贡献和趋势/风险诊断请求。
+---
+
+# TikTok Affiliate Analytics — 联盟经营数据分析（WorkBuddy 版）
+
+本 Skill 负责一期 Tiky 数据分析五个核心场景的意图识别、准入校验、场景编排、只读工具调用和结果交付。各场景的目标、业务问题、来源和主动分析边界以 [业务问题索引](./references/analysis-scope-and-questions.md) 为入口；指标公式、字段映射、关联键和输出边界以本包 References 为准；本文件不复制 SQL 或完整指标字典。工具名沿用 WorkBuddy 中的 `mcp__scorehub__*` 命名空间。
+
+## 一期范围
+
+支持以下场景：
+
+1. 店铺经营总览与趋势诊断；
+2. 联盟经营贡献与渠道结构；
+3. 商品整体经营表现与风险；
+4. 商品联盟订单结果；
+5. 商品 TOPN 出单达人画像。
+
+商品—内容—订单效果、履约结果弱点、售后与订单质量，以及独立订单分析和独立内容分析暂不作为本 Skill 的完整场景；用户明确询问时按 `business-rules.md` 的范围外回复策略处理。
+
+## 触发条件
+
+- “分析店铺整体经营/经营情况/整体趋势”；
+- “分析联盟销售额、联盟销量、有效联盟订单或渠道结构”；
+- “分析商品表现、商品榜单或商品风险”；
+- “查看商品联盟订单结果或订单趋势”；
+- “找出某商品 TOPN 出单达人、达人贡献或历史画像”。
+
+用户明确指定商品或达人时，以指定对象为主，不强制展示店铺经营基线；达人结果必须能可靠定位到本店商品订单、TOPN 或其他已有历史关联，不能把官方整体画像单独当作本店结果，一期不宣称支持独立、全量达人分析。用户明确指定订单或内容时，一期仅在已有可靠关联事实范围内提供，不宣称独立订单/内容专题已实现；超出范围时按 `business-rules.md` 回复。用户未指定对象且可以安全推断为店铺整体时，进入店铺整体场景；存在多个合理解释时先澄清。
+
+## 执行流程
+
+### 1. 分析准入（只读）
+
+共享连接、授权与限流处理遵循 Agent。分析按以下流程执行：
+
+1. 调用 `mcp__scorehub__status` 检查本地连接和账号登录状态，未登录时按 Agent 的授权流程处理；
+2. 按单日/单月规则解析最终 `start_date`、`end_date`；
+3. 调用 `mcp__scorehub__get_analytics_readiness` 查询账号店铺凭证、数值 ID 映射和指定日期同步状态；
+4. 列出可分析店铺和不可分析店铺原因；
+5. 账号下存在多个可分析店铺且用户未指定时，用 WorkBuddy `AskUserQuestion` 让用户选择一个或多个；只有一个可分析店铺时直接继续；
+6. 只把准入工具返回 `analyzable=true` 的数值 `shop_id` 传给后续业务分析工具。
+
+数据分析不依赖 Tiky 达人能力中的当前选中店铺。数值 `shop_id` 默认不面向用户展示，也不得从店铺名、ScoreHub UUID 或 `shop_code` 猜测/回退。同步状态只读消费经营驾驶舱的查询结果；不得在本 Skill 中发起同步写入或修改数据库。
+
+### 2. 日期与对象解析
+
+- 指定某一天：`start_date = end_date = 指定日期`；
+- 指定过去月份：使用该月第一天至最后一天；
+- 指定本月且当前日期大于 4 号：使用本月第一天至当前日期前 4 天；当前日期为 1–4 号时提示本月尚无可分析日期；
+- 未指定日期：当前日期大于 4 号时默认本月第一天至当前日期前 4 天，当前日期为 1–4 号时默认上一个完整自然月；
+- 明确给出的同月子区间可按原范围使用；未来月份、晚于当前日期前 4 天的范围或跨自然月范围，提示用户调整，不静默截断、拆分或合并；
+- 日期截止按分析服务业务时区计算，默认 `Asia/Shanghai`；服务拒绝日期时让用户调整，不尝试绕过；
+- 校验 `start_date <= end_date` 后通过准入工具检查同步日期覆盖，再识别主分析对象、关联对象和用户问题。
+
+### 3. 场景执行
+
+使用固定只读 MCP 工具，禁止让模型自由拼接 SQL 或直接调用分析服务。调用顺序由场景决定：
+
+- 店铺整体：依次调用 `mcp__scorehub__analyze_shop_overview`、`mcp__scorehub__analyze_affiliate_contribution`、`mcp__scorehub__analyze_product_performance`；再按数据证据判断是否检查商品联盟订单结果和商品 TOPN 出单达人画像；
+- 商品：调用 `mcp__scorehub__analyze_product_performance`、`mcp__scorehub__analyze_product_affiliate_orders`；发现达人贡献突出或订单集中时调用 `mcp__scorehub__analyze_product_top_creators`；
+- 联盟/订单结果：调用 `mcp__scorehub__analyze_affiliate_contribution` 或 `mcp__scorehub__analyze_product_affiliate_orders`；
+- 达人：仅在可可靠定位到本店商品订单、商品 TOPN 出单达人画像或其他已有历史关联时取得本店历史结果；无法定位关联范围时按范围外策略处理；
+- 订单/内容：一期只读取已实现关联中的事实证据，不单独执行尚未冻结的订单或内容专题；
+- 商品 TOPN 出单达人画像：调用 `mcp__scorehub__analyze_product_top_creators` 取得本店历史排名；仅对可靠映射且属于当前 OAuth 选中店铺的 `creator_open_id` 调用 `mcp__scorehub__creator_performance` 补充官方画像。
+
+具体参数和返回结构见 [工具契约](./references/scenario-routing.md)。商品名称不能直接当作 ID；只有唯一可靠匹配到返回的商品 ID 时才继续，否则澄清。`analyze_product_performance` 仅返回全店各项 Top5 榜单，不能传 `product_ids`；指定商品不在榜内时，其整体指标未知，可继续查询该商品联盟订单与出单达人，不用其他商品替代。
+
+### 4. 证据检查与输出
+
+调用成功后检查样本量、金额覆盖率、达人 ID 映射率、关联覆盖率和数据状态。按 [报告结构](./references/analysis-output-schema.md) 交付，结论强度和业务状态解释遵循 [业务规则](./references/business-rules.md)。分析执行与结果展示分离，只展示与问题相关且有证据支持的结果。
+
+如补充官方画像，先读取 [官方字段说明](./references/creator-performance-fields.md)，保留本店历史排名，不调用 Rank 改排。
+
+## 工具调用约束
+
+- 所有数据查询必须是固定、参数化、只读的分析工具；
+- 店铺参数必须来自准入阶段用户选择的店铺集合；
+- 所有日期参数必须经过单日/单月、非跨月和前 4 天边界校验；
+- 店铺、日期或主对象变化后必须重新执行准入；范围均未变化的后续追问可复用本对话已有结果，只补充当前问题需要的工具；
+- 官方达人画像只对可靠映射 `creator_open_id` 的 TOPN 达人调用；
+- 工具失败时保留其他成功结果，按 `business-rules.md` 映射为用户可理解的降级说明；
+- 不执行数据库写入、同步启动、建联、发消息、审核样品或修改业务规则。
+
+## 后续专题与超出范围
+
+商品—内容—订单效果、履约结果弱点、售后与订单质量尚未作为一期完整能力实现。已有数据但关联不足时可输出部分事实并标注覆盖范围；完全超出当前能力时明确不支持，不用相近但口径不同的指标冒充。订单和内容可作为一期商品、达人或店铺分析的关联对象，但不因此宣称独立订单/内容分析已实现。
+
+## References
+
+- [运行时分析范围与业务问题](./references/analysis-scope-and-questions.md)
+- [指标定义](./references/metric-definitions.md)
+- [数据关联与归因](./references/data-join-and-attribution.md)
+- [场景路由](./references/scenario-routing.md)
+- [输出结构与规则边界](./references/analysis-output-schema.md)
+- [业务规则](./references/business-rules.md)
+- [官方达人表现字段](./references/creator-performance-fields.md)

package/skills/tiktok-affiliate-analytics/references/analysis-output-schema.md

@@ -0,0 +1,37 @@
+# 分析输出结构与规则 Reference
+
+## 输出顺序
+
+默认按以下顺序输出：
+
+1. 核心结论摘要；
+2. 关键数据事实；
+3. 趋势或同口径周期比较（如有）；
+4. 风险点与机会点（如有）；
+5. 数据限制与覆盖率；
+6. 人工决策建议（如有）。
+
+首次店铺整体分析覆盖店铺经营总览与趋势诊断、联盟经营贡献与渠道结构、商品整体经营表现与风险；用户明确指定商品或达人时，只展示指定对象相关信息；订单或内容仅在一期已有可靠关联事实时展示，不能暗示独立订单/内容专题已实现。执行过的关联分析不必全部展示，只有具备业务价值且证据充分时才展开。
+
+默认用户可见内容至少包括：分析对象、实际分析时间范围、关键指标来源与口径、会影响结论的数据状态，以及必要的金额/关联覆盖率和数据限制。内部保留的技术字段不必默认展开，但不能因此省略影响结论的上下文。
+
+## 摘要规则
+
+- 通常选择 1–3 条最重要结论；
+- 每条结论标明对象和结论类型，并给出关键数值；
+- 区分事实、观察性判断、风险/机会和人工建议；
+- 不在摘要倾倒完整指标字典或未经证据支持的行动结论。
+
+摘要至少覆盖店铺、商品、达人、订单、内容五类核心业务对象的适用边界：有对象结果时围绕该对象摘要；没有该对象可靠结果时不强行补充。
+
+趋势或环比在具备可比周期时，原则上同时给出当前周期值、对比周期值、绝对变化值和变化率；缺少可比周期、分母为 0 或口径不一致时，按 `not_comparable` 说明原因。
+
+## 必须保留的上下文
+
+内部结果至少保留店铺、市场、请求与实际日期范围、样本量、事实日期轴、指标来源、去重键、数据状态、金额/关联覆盖率、未映射和不可分析数量。用户追问计算方式或完整性时再展开技术细节。每条趋势、风险或机会还应保留支撑事实、比较周期、样本量和覆盖率，确保结论可追溯。
+
+## 状态与建议
+
+状态解释、结论强度和范围外回复遵循 [业务规则](./business-rules.md)。后端未提供的覆盖率和技术上下文标记未知，不凭空补齐。多个店铺各自展示，保留实际币种。
+
+生成 WorkBuddy HTML 报告时，共享品牌配色遵循 Agent；外部名称、文本和链接必须转义，只展示本次真实结果，并提供实际生成文件的可用链接。

package/skills/tiktok-affiliate-analytics/references/analysis-scope-and-questions.md

@@ -0,0 +1,153 @@
+# 运行时分析范围与业务问题 Reference
+
+本文件把 Tiky 一期分析必须掌握的业务范围带入 WorkBuddy 插件。它定义每个分析场景要回答的问题、主要事实来源、关键统计边界和主动展开条件；指标公式、字段映射和跨表实现细节分别以其他运行时 Reference 为准。
+
+## 一期分析范围
+
+一期支持以下五个核心分析场景：
+
+1. 店铺经营总览与趋势诊断；
+2. 联盟经营贡献与渠道结构；
+3. 商品整体经营表现与风险；
+4. 商品联盟订单结果；
+5. 商品 TOPN 出单达人画像。
+
+商品—内容—订单效果、履约结果弱点、售后与订单质量，以及独立订单分析和独立内容分析暂不作为一期完整分析场景。订单和内容仍可作为一期商品、达人或店铺分析中的关联对象和事实证据，但不能据此宣称对应独立专题已实现。
+
+## 店铺经营总览与趋势诊断
+
+### 目标
+
+建立店铺整体经营基线，判断当前周期相对可比周期的增长、下降和已定义风险信号，为联盟、商品和达人结果提供整体经营上下文。
+
+### 可分析的问题
+
+- 店铺整体 GMV、退款金额、售出件数和已支付订单数处于什么规模；
+- 各项指标按日、周或月如何变化，是否存在增长、下降、峰值或持续性变化；
+- 与上一同口径周期相比，哪些指标改善或恶化；
+- 是否出现 GMV 下滑、高退款等已定义风险信号；
+- 店铺整体渠道成交结构如何，联盟销售额占店铺整体 GMV 的比例如何变化。
+
+### 主要来源
+
+- `xmj_shop_daily`：店铺整体 GMV、退款金额、售出件数、已支付订单数及 `metric_date` 趋势；
+- `xmj_product_daily`：联盟汇总、商品经营和联盟渠道背景；
+- 联盟订单及退款/取消事实：补充有效联盟订单和联盟确认退款结果。
+
+### 口径参考
+
+指标含义见 [指标定义](./metric-definitions.md)，订单筛选、去重和金额归因见 [数据关联](./data-join-and-attribution.md)。
+
+执行顺序与下钻条件遵循 [SKILL.md](../SKILL.md)。
+
+## 联盟经营贡献与渠道结构
+
+### 目标
+
+衡量联盟对店铺和商品经营的贡献，观察联盟销售额、销量、有效订单、确认退款和视频/直播渠道结构。
+
+### 可分析的问题
+
+- 联盟销售额、联盟销量和有效联盟订单数在店铺或商品层面的规模与趋势；
+- 联盟销售额占店铺整体 GMV 的比例及其变化；
+- 联盟确认退款额是否同步上升，联盟经营结果是否伴随售后风险；
+- 视频和直播联盟渠道分别贡献多少成交额及其结构变化；
+- 店铺整体渠道结构与联盟汇总结果分别呈现什么特点。
+
+### 主要来源
+
+- `xmj_product_daily`：联盟总归因 GMV、联盟销量及视频/直播联盟成交额；
+- `xmj_affiliate_order_line`：按 `biz_date` 统计有效联盟订单数及趋势；
+- `xmj_return_line`、`xmj_cancellation_line`：联盟确认退款额及退款业务日期；
+- `xmj_shop_daily`：店铺整体 GMV和店铺整体渠道成交结构。
+
+### 口径参考
+
+指标含义见 [指标定义](./metric-definitions.md)，订单筛选、去重和金额归因见 [数据关联](./data-join-and-attribution.md)。
+
+执行顺序与下钻条件遵循 [SKILL.md](../SKILL.md)。
+
+## 商品整体经营表现与风险
+
+### 目标
+
+从商品整体经营口径识别主要贡献商品、规模变化和售后风险，再与商品联盟结果进行上下文对照。
+
+### 可分析的问题
+
+- 哪些商品整体 GMV 和售出件数规模最高；
+- 商品整体 GMV、售出件数、退款金额和退款率如何排名和变化；
+- 哪些商品出现高退款金额、高退款率或已退款件数集中；
+- 商品整体经营表现与联盟销售额、联盟销量是否一致；
+- 哪些商品整体规模较大但联盟贡献较弱，或联盟贡献较高但整体规模一般。
+
+### 主要来源
+
+- `xmj_product_daily`：商品整体 GMV、售出件数、退款金额、退款率、已退款件数及商品日期；
+- `xmj_shop_daily`：店铺整体经营基线；
+- `xmj_product_daily` 联盟字段：与商品联盟结果进行上下文对照。
+
+### 口径参考
+
+指标含义见 [指标定义](./metric-definitions.md)，订单筛选、去重和金额归因见 [数据关联](./data-join-and-attribution.md)。
+
+执行顺序与下钻条件遵循 [SKILL.md](../SKILL.md)。
+
+## 商品联盟订单结果
+
+### 目标
+
+确定哪些商品真正贡献了有效联盟订单，再向达人、内容和售后关联事实展开。
+
+### 可分析的问题
+
+- 哪些商品贡献了最多有效联盟订单和联盟销量；
+- 商品有效联盟订单按日、周或月如何变化，是否存在增长、下降、峰值或持续性变化；
+- 商品订单是否集中在少数达人或内容；
+- 商品有效订单数、销量与取消/退货记录是否出现规模和售后风险不匹配；
+- 哪些商品有履约内容，但订单结果较弱。
+
+### 主要来源
+
+- `xmj_affiliate_order_line`：联盟订单、商品、达人、内容和数量；
+- `xmj_order_line`：目标商品订单行 `sale_price`，用于重建 Tiky 达人归因实付商品成交额；
+- `xmj_product_daily`：商品整体经营和联盟渠道上下文；
+- `xmj_cancellation_line`、`xmj_return_line`：售后结果。
+
+### 口径参考
+
+指标含义见 [指标定义](./metric-definitions.md)，订单筛选、去重和金额归因见 [数据关联](./data-join-and-attribution.md)。
+
+执行顺序与下钻条件遵循 [SKILL.md](../SKILL.md)。
+
+## 商品 TOPN 出单达人画像
+
+### 目标
+
+对已经在指定商品上实际出单的达人进行本店历史结果复盘，并补充可可靠映射达人的官方当前画像；不输出脱离本店结果的通用达人评分或适配保证。
+
+### 可分析的问题
+
+- 指定商品的 TOPN 出单达人是谁；
+- 哪些达人带来的 Tiky GMV、有效联盟销量和有效联盟订单数最高；
+- 出单达人是否在多个商品上重复产生订单；
+- 出单达人的履约内容数、合作商品数和可关联售后记录如何；
+- 可可靠映射的达人当前官方粉丝、内容、受众和市场表现画像是什么。
+
+### 主要来源
+
+- `xmj_affiliate_order_line`：达人账号、商品、订单、数量和内容关联；
+- `xmj_order_line`：目标商品订单行 `sale_price`，用于重建 Tiky GMV；
+- `xmj_sample_fulfillment`、`xmj_sample_application`：履约内容、合作商品和可用 `creator_open_id`；
+- `xmj_cancellation_line`、`xmj_return_line`：可可靠关联时的售后结果；
+- `Get Marketplace Creator Performance`：补充官方当前达人画像。
+
+### 口径参考
+
+指标含义见 [指标定义](./metric-definitions.md)，订单筛选、去重和金额归因见 [数据关联](./data-join-and-attribution.md)。
+
+执行顺序与下钻条件遵循 [SKILL.md](../SKILL.md)。
+
+## 使用边界
+
+本索引描述后端返回事实可以回答的问题，不保证每个接口均返回全部字段。具体可调用参数与 Top5 限制见 [工具契约](./scenario-routing.md)，结论强度和范围外回复见 [业务规则](./business-rules.md)。

package/skills/tiktok-affiliate-analytics/references/business-rules.md

@@ -0,0 +1,42 @@
+# 联盟经营分析业务规则 Reference
+
+本文件承载 Skill 运行时的结论强度、数据状态、范围降级和禁止动作。本文件为这些解释规则的 owner；指标与关联细节分别见 [指标定义](./metric-definitions.md) 和 [数据关联](./data-join-and-attribution.md)。
+
+## 结论强度
+
+按以下层级表达结果：数据事实 → 观察性判断 → 风险信号/机会点 → 人工决策建议。样本小、覆盖不足或关键字段缺失时，只输出事实或使用“可能”“值得关注”等弱结论。
+
+不得把相关性表达为因果关系，不得把单个指标或单个对象结果变成未经确认的全局阈值。
+
+风险或机会原则上至少需要两个相互支持的事实，或一个明确规则结果加一个业务上下文；“集中”“较高”“较弱”等表述优先采用同店、同期或同商品集合的相对比较。规则型预警可以作为风险信号，但不得据此推断具体原因。
+
+## 数据状态
+
+| 状态 | 含义 | 处理 |
+|---|---|---|
+| `complete` | 关键字段和关联完整 | 正常输出 |
+| `partial` | 存在未关联、未映射或金额缺失 | 输出可用事实并说明影响范围 |
+| `no_data` | 范围内没有可用记录 | 说明暂无数据，不等同于 0 |
+| `not_comparable` | 缺少可比周期、分母为 0 或口径不一致 | 说明具体原因，不填零替代 |
+| `unavailable` | 本次接口、服务或必要字段不可用 | 保留其他成功结果并说明原因 |
+
+“能力尚未实现”或“超出产品范围”不是 `unavailable`，按范围外策略单独说明。`no_data` 不等同于 0；只有真实查询结果明确为数值 0 时才可写成 0。
+
+覆盖率不设置统一硬性通过阈值，应结合指标重要性、样本量和缺失范围调整结论强度。多种状态同时出现时，优先说明对核心结论影响最大的状态，其余限制集中放在数据限制部分；状态不得静默忽略。状态说明应尽量靠近受影响的事实或结论，也不得以默认零值掩盖。
+
+日期解析遵循 [SKILL.md](../SKILL.md)，不在本文件重复定义。
+
+## 未实现和超出范围
+
+对于商品—内容—订单效果、履约结果弱点、售后与订单质量、独立订单/内容分析或其他超出范围的请求，按“当前结论 → 原因 → 可提供内容 → 限制说明 → 下一步选择”回复。已规划但尚未实现时说明专题状态和当前替代事实；已有数据但关联不足时可以输出部分事实并标注覆盖范围；完全超出能力时明确不支持；不得用口径不同的相近指标冒充目标指标。
+
+当前没有可靠数据支持时，不提供利润率、ROI、库存、广告成本、建联成功率或完整样品申请—履约—出单转化漏斗；也不得声称完整视频出单率或完整达人 GMV 归因。
+
+## 禁止动作
+
+- 不执行数据库写入、DDL 或同步任务启动；
+- 不自动建联、发消息、审核样品或修改业务规则；
+- 不把商品日报联盟 GMV 当作达人明细金额；
+- 不把官方达人整体市场画像当作本店订单结果；
+- 不把部分归因包装为全量结果；
+- 不虚构数据、概率、原因或 ROI/利润结论。

package/skills/tiktok-affiliate-analytics/references/creator-performance-fields.md

@@ -0,0 +1,82 @@
+# 官方达人表现字段 Reference
+
+本文件整理 `creator_performance` 返回的官方达人画像字段，供商品 TOPN 出单达人画像补充使用。官方接口数据是 TikTok Shop Marketplace 的当前达人整体表现快照，不等于本店历史订单结果，也不参与本店 TOPN 排名。
+
+## 调用边界
+
+- 仅对本店历史订单中已进入商品 TOPN、且能够可靠映射 `creator_open_id` 的达人调用；
+- `creator_open_id` 必须来自可靠的搜索结果或身份映射，不得由用户名猜测或自行构造；
+- 接口失败、限流、权限不足或字段缺失时，保留本店历史结果，并将官方画像标记为不可用或不完整；
+- 官方字段必须与本店历史字段分区展示，并标注“官方当前画像”。
+
+## 字段分组
+
+### 身份与基础画像
+
+| 字段 | 含义 | 使用边界 |
+|---|---|---|
+| `username` | TikTok 用户名 | 身份核对和展示 |
+| `nickname` | TikTok 昵称 | 展示 |
+| `avatar.url` | 头像地址 | 展示，不参与排序 |
+| `selection_region` | 达人所属市场/区域 | 与店铺市场核对 |
+| `bio_description` | 达人简介 | 文本参考，不替代结构化表现 |
+| `follower_count` | 粉丝数 | 官方当前快照 |
+| `profile_tt_uri` | TikTok 资料页 URI | 展示或人工复核 |
+| `category_ids` | 带货内容涉及的类目 ID | 仅作类目元数据，不直接证明垂类适配 |
+
+### 粉丝受众
+
+| 字段 | 含义 | 使用边界 |
+|---|---|---|
+| `follower_location[].key/value` | 粉丝地区及占比 | 保留原始值，单位按真实响应解释 |
+| `follower_age[].key/value` | 粉丝年龄段及占比 | 保留原始值，单位按真实响应解释 |
+| `follower_gender[].key/value` | 粉丝性别及占比 | 保留原始值，单位按真实响应解释 |
+
+### 内容和互动表现
+
+| 字段 | 含义 |
+|---|---|
+| `ec_video_count` / `ec_live_count` | 电商视频数 / 电商直播数 |
+| `avg_ec_video_play_count` / `avg_ec_live_view_count` | 平均视频播放量 / 平均直播观看量 |
+| `avg_ec_video_like_count` / `avg_ec_video_comment_count` / `avg_ec_video_share_count` | 平均视频点赞、评论、分享 |
+| `avg_ec_live_like_count` / `avg_ec_live_comment_count` / `avg_ec_live_share_count` | 平均直播点赞、评论、分享 |
+| `ec_video_engagement_rate` / `ec_live_engagement_rate` | 视频 / 直播互动率 |
+| `content_gmv_distribution[].content_type/value` | 按 VIDEO、LIVE、SHOWCASE 划分的内容 GMV 分布 |
+
+### GMV、GPM 与合作规模
+
+| 字段 | 含义 | 使用边界 |
+|---|---|---|
+| `gmv`、`video_gmv`、`live_gmv` | 达人整体、视频、直播 GMV | 官方市场表现，不计入本店 GMV |
+| `gmv_range` | GMV 区间及币种 | 展示区间，不用于本店排序 |
+| `gpm`、`video_gpm`、`live_gpm` | 总体、视频、直播 GPM | 官方市场表现，不等于本店 GPM |
+| `gpm_range`、`video_gpm_range`、`live_gpm_range` | GPM 区间及币种 | 保留区间和币种 |
+| `units_sold`、`units_sold_range` | 累计售出件数及区间 | 授权不足时可能缺失，不替代本店销量 |
+| `promoted_product_num` | 推广商品数 | 描述推广广度 |
+| `product_original_price_range` | 推广商品原价区间及币种 | 描述价格带 |
+| `top_collaborated_brand_ids` / `brand_collaboration_count` | 主要合作品牌及合作品牌数 | 描述合作广度，不证明本店结果 |
+
+### 评价、佣金与履约倾向
+
+| 字段 | 含义 | 使用边界 |
+|---|---|---|
+| `avg_commission_rate`、`avg_commission_rate_range` | 平均佣金率及区间 | hundredths of a percent；示例 6000 表示 60% |
+| `avg_gmv_per_buyer`、`avg_gmv_per_buyer_range` | 平均每位买家 GMV及区间 | 特定市场或授权条件下返回 |
+| `pps` | Promotion Performance Score | 近 90 天可购物内容与商品选择质量；无值保持未知 |
+| `rating` | 合作卖家评分 | 市场反馈，不等于本店评价 |
+| `post_rate` | 收到样品后预计发布可购物视频或直播的比例 | 预测性字段，不是本店真实履约率 |
+
+## 单位、窗口和缺失
+
+- 币种字段必须与对应金额一起展示，不能跨币种直接相加；
+- 互动率、佣金率和预计发布率的官方示例使用 hundredths of a percent；分布字段可能使用小数比例。实现时需保留原始值并通过真实响应测试确认换算；
+- `ec_video_engagement_rate` 的官方说明使用最近 30 天视频，`pps` 使用过去 90 天；其他字段的统一窗口未完全明确，应标注“接口窗口未明确”；
+- 精确 GMV、销量、佣金和区间字段可能因授权不足缺失。缺失表示未知，不填零；
+- 官方画像结果必须注明接口返回时间或快照属性，并与本店历史分析日期范围分开展示。
+
+## 禁止混用
+
+- 官方总 GMV、视频 GMV、直播 GMV和 GPM 不得计入本店达人归因实付商品成交额；
+- `post_rate` 不得直接解释为本店履约率、出单率或转化率；
+- 官方类目分布不得直接生成“该达人适合某商品”的确定性结论；
+- 官方画像字段不得改变商品 TOPN 的本店排序结果。

package/skills/tiktok-affiliate-analytics/references/data-join-and-attribution.md

@@ -0,0 +1,53 @@
+# 数据关联与归因 Reference
+
+本文件是订单筛选、去重、归因和 TOPN 排序解释的 owner。计算由后端完成，Skill 不执行 SQL，也不重算或改排后端榜单。
+
+## 日期轴
+
+- 店铺/商品日报使用各自 `metric_date`；
+- 联盟订单使用 `xmj_affiliate_order_line.biz_date`，表示联盟订单创建业务日；
+- 订单详情使用其自身订单事实日期，仅用于订单事实关联和金额重建，不能替代联盟订单的 `biz_date`；
+- 退款/取消使用各自事实表 `biz_date`；
+- 不同事实必须保留各自日期轴，不用一个笼统统计日期替代。
+
+## 核心关联
+
+- 店铺隔离必须使用 `shop_id`；订单关联使用 `(shop_id, order_id)`；
+- 商品和 SKU 识别必须以目标商品关联规则为准；一个目标商品存在多个联盟 SKU 时，先确认订单详情中的 SKU 与商品 ID 映射，再按订单级目标商品折叠；
+- 联盟订单的达人标识优先使用非空、规范化的 `creator_username`；`target_collaboration_id` 只作为可选定向合作链路标签，不能据此推断达人身份。官方画像调用前才解析 `creator_open_id`；
+- 订单详情金额先按 `(shop_id, order_id)` 聚合，再按目标商品订单行取 `sale_price`；不使用重复保存的订单级小计或运费字段直接求和；订单详情的支付时间或状态不参与有效联盟订单筛选。订单详情中的 `payment_sub_total`、`payment_shipping_fee` 属于可能在同一订单多行重复保存的订单级字段，禁止直接按订单行求和。
+
+## 有效联盟订单
+
+仅当 `xmj_affiliate_order_line.biz_date` 在分析范围内，且 `target_collaboration_id` 或 `creator_username` 至少一个有效非空值时，订单才进入有效联盟订单集合；`NULL`、空字符串和仅含空格的值均视为空值。订单数按 `DISTINCT order_id` 统计。`order_status` 为空或不可用时不得以其单独判定有效性。
+
+不自动排除取消或退款订单；取消和退货作为独立结果指标。联盟订单行数不得替代订单数；多商品订单在店铺或商品粒度按各自统计对象计数，多达人订单可分别计入达人归因结果，但不得将达人结果之和解释为店铺订单总数。
+
+## Tiky GMV
+
+对目标商品先形成订单级金额：
+
+1. 按 `(shop_id, order_id)` 聚合订单详情；
+2. 只汇总目标商品订单行 `sale_price`；
+3. 排除运费；
+4. 目标商品多个联盟 SKU 先折叠，避免同一商品金额重复累加；
+5. 多达人订单允许按各达人归因明细分别计入，跨达人汇总可能重复；
+6. 目标商品售价缺失时金额未知，但订单数和销量可保留。
+
+金额覆盖不足时不得将缺失金额填 0 后参与金额排名；应披露金额覆盖率和未重建金额数量。商品日报联盟 GMV 不得替代达人明细金额。
+
+## 履约与官方画像
+
+履约达人数、履约后出单达人数和履约内容只沿用“定向合作 + 免费样品申请 + 履约链路”的驾驶舱口径；公开合作不纳入履约覆盖。履约链路出单达人数与全联盟订单关联达人数量是不同指标，不得合并。`creator_username` 无法可靠映射到 `creator_open_id` 时，不猜测 ID，保留未映射记录并降低官方画像覆盖率。
+
+## 覆盖率与降级
+
+- 任一跨表关联失败时，保留可取得的订单数、销量或汇总事实，并记录未关联数量；
+- 订单详情金额关联不足时，金额指标标记 `partial` 或未知；
+- 达人身份映射不足时，本店历史结果仍可输出，官方画像标记 `partial`；
+- 多 SKU 折叠规则未通过真实数据核验前，不把联盟明细行数直接当作目标商品销量或金额；
+- 所有金额、销量和达人排名结果必须标明来源口径，禁止跨事实表反推。
+
+派生指标统一遵循：商品有效联盟订单数在有效集合上增加目标 `product_id` 后按订单去重；达人有效联盟订单数在有效集合上增加规范化非空 `creator_username` 后按订单去重；商品订单关联达人数量在商品有效联盟订单集合中对规范化 `creator_username` 去重；商品订单趋势按 `biz_date` 聚合。
+
+TOPN 正常排序为 Tiky GMV 降序、有效联盟销量降序、有效联盟订单数降序、creator_username 升序。金额缺失时，TOPN 不以 0 填充金额；保留缺失标识，并按可用销量、有效联盟订单数进行降级排序，同时说明金额覆盖范围和未重建金额数量。后续专题在实现前仍需单独确认：内容订单关联日期轴、`content_id + product_id + 归一化 content_type` 的完整关联与覆盖率、取消/退货同一订单行多条记录的最终去重键、达人/内容售后归因规则、履约弱点的相对比较基准，以及样品申请—履约—出单转化漏斗是否可计算。

package/skills/tiktok-affiliate-analytics/references/metric-definitions.md

@@ -0,0 +1,53 @@
+# 联盟经营分析指标 Reference
+
+本文件是指标含义与来源索引的 owner。有效订单筛选、金额重建和排序细节统一见 [数据关联与归因](./data-join-and-attribution.md)；只解释真实工具返回的数据，不执行表查询。
+
+## 店铺与联盟汇总
+
+| 指标 | 粒度 | 主要来源 | 运行约束 |
+|---|---|---|---|
+| 店铺整体 GMV | 店铺/日 | `xmj_shop_daily.gmv_amount*`、`metric_date` | 店铺整体口径，不替代联盟 GMV |
+| 店铺退款金额 | 店铺/日 | `xmj_shop_daily.refunds_amount*` | 店铺整体口径 |
+| 店铺售出件数 | 店铺/日 | `xmj_shop_daily.items_sold` | 不替代联盟销量 |
+| 店铺订单数 | 店铺/日 | `xmj_shop_daily.orders` | 官方含义为已支付订单数 |
+| 商品联盟销售额 | 店铺/商品/日 | `xmj_product_daily.affiliate_total_attributed_gmv_amount*` | 汇总可复用，不拆作达人金额 |
+| 商品联盟销量 | 店铺/商品/日 | `xmj_product_daily.affiliate_total_attributed_sold_items` | 汇总可复用，达人拆分用联盟明细 |
+| 有效联盟订单数 | 店铺/商品/达人/周期 | `xmj_affiliate_order_line` | 按已确认筛选条件并 `DISTINCT order_id` |
+| 联盟确认退款额 | 店铺/商品/周期 | 退款/取消事实表 | 复用驾驶舱联盟经营结果口径 |
+| 视频/直播联盟成交额 | 店铺/商品/日 | 商品日报联盟渠道字段 | 汇总可用；内容级需可靠关联 |
+
+## 商品与达人
+
+| 指标 | 粒度 | 主要来源 | 运行约束 |
+|---|---|---|---|
+| 商品整体 GMV | 商品/日 | `xmj_product_daily` 整体经营字段 | 不命名为联盟 GMV |
+| 商品整体售出件数 | 商品/日 | `xmj_product_daily` 整体经营字段 | 与联盟销量分开 |
+| 商品整体退款金额/退款率 | 商品/周期 | `xmj_product_daily` | 退款率仅在 GMV>0 时计算 |
+| 商品有效联盟订单数 | 商品/周期 | `xmj_affiliate_order_line` | 有效订单筛选 + `DISTINCT order_id` |
+| 商品有效联盟销量 | 商品/周期 | 联盟订单行 `quantity` | 多 SKU 折叠见数据关联 Reference |
+| 商品订单关联达人数量 | 商品/周期 | `creator_username` | 规范化后去重 |
+| 达人归因实付商品成交额（GMV） | 商品/订单/达人 | `xmj_order_line.sale_price` | 只计目标商品、不含运费，多达人可重复归因；本指标为 Tiky 自定义 GMV，不替代商品日报联盟 GMV |
+| 商品 TOPN 出单达人 | 商品/达人 | 联盟订单 + Tiky GMV | 排序见数据关联 Reference；官方画像见 `creator-performance-fields.md` |
+
+## 其他已上线驾驶舱指标索引
+
+以下为后端可能提供的补充指标。仅在真实返回时使用，不能把这些来源字段当作已开放工具承诺。
+
+| 指标 | 适用范围 | 运行约束 |
+|---|---|---|
+| 店铺整体 LIVE/VIDEO/PRODUCT_CARD 渠道成交额及占比 | 店铺经营上下文 | 不等同于联盟内部渠道结构 |
+| 联盟销售额占店铺整体 GMV 比例 | 店铺/周期 | 必须同店铺、同周期，分母为 0 不可比较 |
+| 商品整体 GMV/售出件数/退款金额/退款率榜单 | 商品经营与风险 | 沿用商品日报整体口径，不与联盟指标混用 |
+| 商品已退款件数 | 商品售后上下文 | 不推导利润或净收入 |
+| 履约达人数、履约后出单达人数、履约视频数、履约直播场次 | 履约链路上下文 | 仅覆盖定向合作 + 免费样品申请 + 履约链路；履约结果弱点尚未独立实现 |
+| 高退款店铺、GMV 下滑店铺预警 | 风险提示 | 仅为规则化信号，不解释具体原因 |
+
+| 达人账号、昵称、头像 | 商品 TOPN 展示 | 历史账号与外部当前资料需分开标注 |
+
+官方达人画像字段不在本指标索引中展开，统一见 [`creator-performance-fields.md`](./creator-performance-fields.md)。
+
+金额无法完整重建时，TOPN 不以 0 填充缺失 GMV；保留金额缺失标识，按可用有效联盟销量、有效联盟订单数降级排序，并披露金额覆盖范围和未重建数量。上线驾驶舱当前达人订单详情 GMV包含运费，不能直接复用为 Tiky GMV。
+
+## 状态与缺失
+
+`complete`、`partial`、`no_data`、`not_comparable`、`unavailable` 的含义和用户表达以 `business-rules.md` 为准。缺失值默认未知，不填零；金额不可重建时保留订单数/销量。

package/skills/tiktok-affiliate-analytics/references/scenario-routing.md

@@ -0,0 +1,37 @@
+# 分析工具参数与响应 Reference
+
+本文件是 Skill 调用时的字段索引。日期解析、店铺选择和执行顺序遵循 [SKILL.md](../SKILL.md)，业务问题见 [分析范围](./analysis-scope-and-questions.md)。工具 schema 是可调用参数的依据。
+
+## 参数
+
+所有工具包含必填 `start_date`、`end_date`（YYYY-MM-DD 字符串）。店铺 ID 保持数值字符串，只使用准入结果；`shop_ids` 为 1–20 个不重复 ID，`product_ids` 为 1–100 个不重复、非空 ID。
+
+| 工具（均加 mcp__scorehub__ 前缀） | 额外参数 | 返回内容 |
+|---|---|---|
+| `get_analytics_readiness` | 无 | 账号店铺授权、映射、同步状态与 `analyzable` |
+| `analyze_shop_overview` | 必填 `shop_ids` | 总览、比较、趋势和风险信号 |
+| `analyze_affiliate_contribution` | 必填 `shop_ids`，可选 `product_ids` | 联盟贡献及全店渠道结构 |
+| `analyze_product_performance` | 必填 `shop_ids` | 全店商品 GMV、销量、退款金额、退款率各 Top5 |
+| `analyze_product_affiliate_orders` | 必填 `shop_ids`、`product_ids` | 指定商品联盟订单结果 |
+| `analyze_product_top_creators` | 必填 `shop_id`、`product_id`，可选 `top_n`（默认 5，整数 1–50） | 单店单商品历史 TOPN |
+| `creator_performance` | `creator_user_id`，值为可靠映射的 `creator_open_id` | 当前选中店铺上下文中的官方画像 |
+
+商品筛选只影响联盟贡献部分；同次返回的店铺结构仍是全店数据。商品表现工具不接受商品过滤，榜外商品不能判为零销售。不同店铺分别展示，原币不可跨币种混加。
+
+## 准入结果
+
+MCP 成功信封为 `{ok:true,data}`。准入的 `data` 包含：
+
+- `date_range`：实际校验的日期范围；
+- `shops[]`：`name`、`market`、`country`、`selected`、`authorization_status`、`mapping_status`、`sync_status`、`analyzable`，映射成功时包含 `shop_id`，不可分析时含 `reason`；
+- `summary`：账号店铺数、可分析和不可分析店铺数。
+
+同步与授权由远端强制校验，每次业务调用都会重查，不要求模型推断原始任务状态。
+
+## 业务结果
+
+业务 `data` 为 `{date_range, availability, shops}`。每店包含 `shop_id`、`market`、`availability`、`results`、`errors`。
+
+`results` 的模块键为 `shop_overview`、`shop_overview_insight`、`affiliate_effect`、`shop_structure`、`product_analysis`、`product_affiliate_orders` 或 `product_top_creators`；每项保留后端 `{code,description,data}`。`availability=available/partial/unavailable` 仅表示请求是否有成功结果，不代表数据完整度。
+
+必须继续检查后端 `data` 内的业务状态、null、币种与覆盖率。状态／覆盖率缺失时保持未知，不能由 HTTP 成功推断完整；解释见 [业务规则](./business-rules.md)。全部失败时 MCP 返回 `{ok:false,error_type,user_message,retryable,upstream}`；`upstream.shops` 可保留逐店原因，共享错误分流遵循 Agent。