00痛点 · 方案 总览（先看这一张）

本次收集到的业务痛点分为三大类共 8 项，下表标出每一项在本 SOP 中的覆盖状态与对应章节，方便业务同学带着问题查阅。

🔥 三类痛点速览

01场景与角色

业务背景：电商三环节质检 — 事前（商品上架）、事中（交易/审核）、事后（差评/申诉）。

使用对象：本 SOP 面向业务同学（无编程基础），操作动作只有「下文件 → 拖文件夹 → 看报告」。所有自动化由 AI / 数据侧承接。

02总体流程（双通道全景图）

数据处理分为离线和在线两大通道，最终汇入统一的「汇总结果」和「报告生成」环节：

📥 离线通道（CSV / Excel 文件）

📡 在线通道（MCP / BI 图卡 API）

📂 一、离线数据处理

离线数据来源于业务系统导出的 CSV / Excel 文件，由 AI 自动完成清洗、对比、汇总全链路。业务同学只需「下文件 → 扔文件 → 看报告」。

1.1文件夹与命名规范

📁 共享文件夹结构（建一次，长期用）

✍️ 文件命名规范

统一格式：环节_细分类_日期_负责人.xlsx。事中/事后必须用细分类区分通道。

1.2数据结构类痛点

🔧 P1-1 多表映射：统一主键 + 关系总图

问题：审核库、回扫库、策略库、商品库各有自己的 ID，业务同学看不懂怎么 join。

解法：约定全链路通用主键，AI 按通用主键自动 join 出宽表，业务同学只看汇总不写 SQL。

1.3人机 diff 三环节判定矩阵 (P1-2)

问题：机审 / 一审 / 二审 三个环节每个都是多标签结果。进入二审的样本，要以二审为真相，分别判定机审、一审「漏放」了哪些标签、「误伤」了哪些标签。手工对比 + 多标签集合差，业务同学算不过来。

📐 业务定义（先对齐口径）

• 真相集合（GT）：以二审标签集合为准，记为 L₂。
• 漏放（Miss）：真相里有，但当前环节没有 → L₂ − Lₓ（这些应该判出却没判出）。
• 误伤（Over）：当前环节有，但真相里没有 → Lₓ − L₂（这些不该判却判了）。
• 命中（Hit）：交集 → L₂ ∩ Lₓ（判得对的部分）。

其中 Lₓ 表示机审标签集合 L₀ 或一审标签集合 L₁。

🤖 AI 自动产出（业务同学只看结论）

把事中_机审_* / 事中_一审_* / 事中_二审_*三类文件扔进对应文件夹，AI 自动按auditId对齐三环节标签，输出三份报告：

1. 明细表：每个 auditId 一行，含三环节标签集合、漏放集合、误伤集合。
2. 标签级汇总：按标签维度汇总，输出"机审漏放 Top 标签"、"一审误伤 Top 标签"。
3. 环节对比看板：机审 漏放率 / 误伤率，一审 漏放率 / 误伤率，环比折线。

📋 输出表样式（02_已清洗/ 下生成）

1.4回扫队列结果列拆分 (P1-3)

问题：回扫导出的"结果"一列把审核环节 / 准入时间 / 结果标签三种信息塞在一起，例如：

机审|2026-05-11 14:23:01|通过
人审|2026-05-11 16:08:42|打回-标签B,标签C
机审|2026-05-11 17:12:09|存疑

🛠️ AI 拆分规则（业务同学不用看懂）

1. 按第一个分隔符（| / / / 空格 / 全角竖线）切前两段：review_type + access_time；
2. 剩余部分作为result_label，多标签按,或;再次切分；
3. 识别失败的行不丢弃，单独输出到「待人工核对」sheet，并标红行号。

📋 拆分前后对照

1.5智能 / 人工质检双通道分流 (P2-1)

问题：智能质检批量大、转换慢，和人工质检走同一管道时拖慢人工部分的及时性。

解法：物理上分两个文件夹 + 两个独立 AI 任务并行跑，互不阻塞。

1.6字段白名单裁剪 (P2-2)

问题：导出台不能选字段，全字段导出 → 大量冗余 → 模型转换慢 + 文件臃肿。

解法：在00_字段翻译表.xlsx新增「必要」列，AI 只对必要字段做清洗与汇总，冗余字段原样保留到归档目录、不进汇总管道。

📋 翻译表新版结构（增加最后两列）

1.7大数据量分片留底 + 稳定转换 (P2-3)

问题：日维度全量塞进单表 → Excel 打不开 / 写入出错 / 设备卡顿；目前用"虾"工具不稳定，经常瘫痪不干活。

🗂️ 分片留底规则

清洗结果按ds + stage分片，每片不超过 5 万行，文件夹结构如下：

🛠️ 替代"虾"工具的稳定方案

1.8多源看板一键登记 (P3-1 / P3-2)

问题：数据源 = 队列 + 看板 + 报表 等多个入口，目前由负责人手抄到一份大表，效率低、易错。

解法：一份「看板登记表」固化所有数据源；AI 按表自动抓取或读取导出文件；自动生成统一汇总。

📋 看板登记表结构（00_看板登记表.xlsx）

🤖 AI 一键汇总（每天 17:00 自动 / 手动触发）

1. 读取看板登记表 → 知道今天应到的所有文件清单；
2. 检查 01_待处理 下每条记录对应的目录是否到齐；
3. 缺文件 → 自动 @ 对应负责人催单（IM 群提醒）；
4. 到齐则自动跑清洗 → 分片 → 汇总；
5. 汇总落盘到 03_汇总结果 / 当日 / 下，并群内推送当日汇总链接 + 关键指标。

🧪 自动抽样校验（替代人工复核 P3-2）

汇总完成后 AI 自动做一次抽样校验：

• 每个数据源随机抽 min(50, 总行数*1%) 条；
• 对比汇总表 vs 源表的主键 + 关键字段是否一致；
• 不一致行输出到「差异核对」sheet，标红 + 给出可能原因；
• 没有差异时给"✅ 抽样 50 条全部一致，无需人工复核"。

1.9AI 人话报告样式

✅ 收到 7 份文件 / 应到 7 份（看板登记表对账完成）

📊 当日基本情况：
   - 事前_商品：1.2 万行
   - 事中_机审：38 万行（智能通道，已分 8 片）
   - 事中_一审：1.4 万行
   - 事中_二审：3,200 行
   - 事中_回扫：26 万行（混杂列已自动拆为 3 列）
   - 事后_智能质检：54 万行（白名单裁剪后体积 -72%）
   - 事后_人工质检：4,800 行

🔁 人机 diff（以二审为真相）：
   - 机审 漏放率 12.3% (Top: 标签C、标签D)
   - 机审 误伤率  4.1% (Top: 标签A)
   - 一审 漏放率  3.8% (Top: 标签C)
   - 一审 误伤率  6.7% (Top: 标签D)

⚠️ 待业务确认：
   - 第 88 行：日期写成"5.11"，已自动改成 2026-05-11
   - 回扫文件第 456 行：结果列拆分失败，请人工核对

🧪 抽样校验：50 条 / 源表 = 50 条 / 汇总表，全部一致 ✅

📂 已保存：
   - 02_已清洗/ds=2026-05-11/
   - 03_汇总结果/2026-05-11/
   - 03_汇总结果/2026-05-11/人机diff报告.xlsx

1.10团队公约：6 件事

1.11离线数据 FAQ

🔌 二、在线数据处理

在线数据通过 MCP 协议调用 BI 平台 API，实时获取图卡数据、执行 SQL 查询。Agent 全自动调度，业务同学只需自然语言提问即可获得结构化数据。

2.1在线数据源总览

除了离线 CSV/Excel 文件外，系统还通过 MCP（Model Context Protocol）协议对接在线数据源。Agent 可实时调用 BI 平台 API，获取图卡数据、执行 SQL 查询、拉取聚合指标。

📡 在线数据源类型

2.2BI 图卡数据输出（核心能力）

BI 图卡是在线数据的核心来源。Agent 通过 MCP 工具调用 BI 平台 API，按 cardId 获取图卡数据，支持指标卡、多列表格、折线图等多种图卡类型。

🧩 图卡调用基本结构

// MCP 工具调用格式
{
  "tool": "query_bi_card_data",
  "parameters": {
    "bizId": "biz_space_001",          // BI 空间 ID
    "cardQuery": {
      "cardId": "card_metric_001",     // 图卡唯一标识
      "pageId": 100001,                // 仪表盘 ID
      "paramsId": "param_hash_abc",    // 可选：仪表盘筛选态快照
      "limit": 50,                     // 返回行数上限
      "variables": [                   // 可选：自定义筛选条件
        {"key": "time_range.start", "value": "20260501", "valueType": "num_YYYYMMDD"},
        {"key": "time_range.end", "value": "20260514", "valueType": "num_YYYYMMDD"},
        {"key": "category_filter", "value": "类目A", "valueType": "string"}
      ]
    }
  }
}

📋 图卡类型与返回格式

📊 图卡数据字段规范（示例）

以一个典型的「核心指标卡」为例：

以一个「多列表格」为例（类目级数据）：

2.3图卡查询三种模式

根据不同场景，图卡查询有三种使用方式：

📋 模式对比

⚠️ 关键约束（踩坑总结）

🔧 按类目取数的正确姿势（关键）

当图卡 SQL 固定形如 WHERE category_1 in (?) AND category_leaf in (?) 时：

1. 先获取候选值列表：调用 get_card_variables 工具获取筛选项的候选 options（如所有叶子类目列表）；
2. 按目标一级类目过滤：从 options 中筛选出属于目标一级类目的所有叶子类目；
3. 构造 variables：一级类目传单值，叶子类目传逗号分隔的完整列表；
4. 不传 paramsId：避免被仪表盘预置的类目筛选干扰。

// 示例：按「类目A」获取 TOP case
{
  "cardQuery": {
    "cardId": "card_table_002",
    "pageId": 100001,
    "limit": 10,
    "variables": [
      {"key": "time_range.start", "value": "20260408", "valueType": "num_YYYYMMDD"},
      {"key": "time_range.end", "value": "20260421", "valueType": "num_YYYYMMDD"},
      {"key": "category_1_filter", "value": "类目A", "valueType": "string"},
      {"key": "category_leaf_filter", "value": "子类A1,子类A2,子类A3,子类A4,...", "valueType": "string"}
    ]
  }
}

2.4API 调用节流与容错

⏱ 节流控制（强约束）

📋 推荐调取顺序（分批执行）

🚨 异常处理

• 某图卡返回为空：跳过该图卡，在报告中标记「部分数据缺失」
• API 调用失败：自动重试 3 次；仍失败则降级到离线数据 + 告警
• 鉴权过期：401/403 → 自动刷新 Token 后重试 1 次 → 仍失败则告警@数据侧
• 禁止行为：❌ 一次性请求全部图卡 / ❌ 并发请求 / ❌ 忽略间隔限制

2.5在线 + 离线数据融合规则

大部分报告需要在线实时数据与离线清洗数据的融合：

2.6在线数据 FAQ

00为什么要封装 Skill（链路位置）

🎯 封装 Skill 解决什么问题

01Skill 6 件套结构（每个 Skill 都长这样）

每个 Skill 都是一个独立目录，固定包含 6 个文件，缺一不可：

📋 SKILL.md 标准模板（最重要）

---
name: biz-analysis-biweekly-report
version: 1.2.0
description: 基于MCP数据自动生成差评分析报告
triggers:
  - 业务分析双周报
  - 风险 case 分析
  - 商品风险治理报告
inputs:
  start_ds:    { type: date, required: true,  desc: 起始日期 }
  end_ds:      { type: date, required: true,  desc: 结束日期 }
  threshold:   { type: float, default: 0.03,  desc: 差评率阈值 }
  recipients:  { type: list, default: ["leader@..."] }
outputs:
  - path: 03_汇总结果/双周报/{yyyy-Wxx}/双周报.html
  - channel: email + IM
quality_check:
  - 抽样 50 条 vs 源表反推一致
  - 差评率波动 ≤ 200%
on_failure:
  - retry: 3 次（间隔 2/5/10 分钟）
  - alert: P2 告警 @负责人
---

## 工作流（Agent 严格按此 5 步执行）
1. 调 MCP 取数（数据表A + 数据表B）
2. 计算 6 个核心指标
3. 渲染 HTML 报告（templates/biweek.html）
4. 跑 quality_check
5. 落盘 + 邮件 + IM 推送

02封装 5 步生命周期

把数据处理流程的某一步沉淀为 Skill，固定走这 5 步：

📋 每一步必须产出什么

03🛠️ 模板 1 · 数据清洗 Skill

对应数据处理流程 Tab 中的 03–09 节（文件夹规范 / 字段翻译 / JSON 修复 / 列拆分 / 白名单裁剪 / 分片）。

04🛠️ 模板 2 · 人机 diff Skill

对应数据处理流程 Tab 中的 05 节（机审/一审/二审三环节集合差判定）。

05🛠️ 模板 3 · 看板汇总 Skill

对应数据处理流程 Tab 中的 10 节（多源看板一键登记 + 抽样校验）。

06🛠️ 模板 4 · 报告渲染 Skill

对应报告生成流程 Tab 中的 03–06 节（4 类报告模板）。每类报告是一个独立 Skill，模板共用底层结构。

07Agent 周期调度配置

Agent = 把多个 Skill 串起来按时跑的"调度员"。每个业务场景对应一个 Agent，统一调用 Skill。

📋 Agent 标准配置（YAML）

name: biz-daily-agent
description: 电商质检每日数据处理 + 报告生成
schedule:
  cron: "0 17 * * *"        # 每天 17:00
  timezone: Asia/Shanghai
  holiday_skip: false        # 节假日是否跳过

# 串行依次执行（前一个失败，后续不跑）
pipeline:
  - skill: biz-data-clean
    params: { ds: "{{ yesterday }}" }

  - skill: biz-human-machine-diff
    params: { ds: "{{ yesterday }}" }
    depends_on: [biz-data-clean]

  - skill: biz-dashboard-rollup
    params: { ds: "{{ yesterday }}" }
    depends_on: [biz-data-clean]

  - skill: biz-portrait-weekly
    params: { start_ds: "{{ last_monday }}", end_ds: "{{ last_sunday }}" }
    when: "weekday == 1"     # 仅周一执行

# 全局错误处理
on_failure:
  retry:    { count: 3, backoff: [2m, 5m, 10m] }
  alert:    { channel: IM, mention: ["@负责人"] }
  fallback: send_last_success_report

🕐 调度三种模式

08稳定性保障（结果稳定输出的 4 道防线）

🚨 告警分级（与策略小时报一致）

09版本与变更管理

Skill 是"团队的能力资产"，必须像代码一样管版本。

📋 版本号约定（语义化）

📝 CHANGELOG.md 标准格式

## v1.2.0 (2026-05-13)
- ✨ 新增 threshold 参数，支持自定义差评率阈值
- 🐛 修复跨月统计窗口边界 off-by-one
- ⚠️  入参 start_ds 默认值由"本月 1 日"改为"过去 14 天"

## v1.1.0 (2026-04-20)
- ✨ 新增 IM 推送渠道
- 📝 完善 SKILL.md 注释

🔄 变更评审流程

1. 提变更 → 在 CHANGELOG.md 草稿区写变更说明；
2. 跑 tests/ 全部通过 + 手动跑 1 次完整流程；
3. 数据侧 1 人评审 + 业务侧 1 人确认口径；
4. 发布到 ~/.workbuddy/skills/，CHANGELOG 升版本号；
5. Agent 自动加载新版本，同时保留上一版本 7 天可一键回滚。

10Skill 封装 FAQ

00报告矩阵总览（先看这一张）

团队当前需要对外输出 4 类报告，其周期、面向对象、触发方式、对应 Skill 各不同。本页约定统一生成链路与模板，避免每次都"从零开发"。

01报告生成三层架构

所有报告共用一套底层架构，自下而上分三层：

025 步生成流程（每个报告都走这 5 步）

03📋 模板 1 · 业务分析双周报

📐 报告结构（固化，不可变）

⚙️ 配置参数（变量化，每期可调）

04⏰ 模板 2 · 策略 100123 推审量 / 积压小时报

📐 报告结构

• ① 当前小时推审量：与昨日同小时、过去 7 天均值对比；
• ② 命中率波动：当前小时命中率 vs 7d 滑动均值，偏离 ±20% 触发告警；
• ③ 审核积压：未审核 case 数、最长等待时间、按队列拆分；
• ④ Top 命中规则：当小时命中最多的 5 条子规则；
• ⑤ 处置建议：超阈值时给出"扩容人力 / 调整阈值 / 临时关闭"建议。

🔔 告警规则（一旦触发立刻发 IM）

05📦 模板 3 · 商品画像周报

📐 商品画像字段（每个商品一行）

📊 周报内容

1. 新进观察期商品：本周新加入观察期的商品清单 + 触发原因；
2. 本周出池商品：按出池标签分组，各 Top 10；
3. 水位线异动：价格水位线变化超 20% 的商品（涨价 / 降价）；
4. 差评率 Top 飙升：本周差评率环比涨幅 Top 10；
5. 建议处置：每条都标注「关注 / 强制审核 / 出池」建议。

06🔍 模板 4 · 单点 Case 智能查询

场景：业务同学想看某个具体商品 / auditId / 订单的全链路情况，无需自己写 SQL，直接自然语言提问，秒级返回结果。

💬 提问示例（直接复制改参数）

🛠️ 工作机制

1. 业务同学在 IM / Web 端发自然语言问题；
2. Agent 解析意图 → 选择对应 MCP 工具（数据表A / 商品画像 / 审核库）；
3. Agent 自动拼 SQL → 调 MCP 取数 → 按"问题模板"渲染；
4. 秒级返回结构化答复 + 可点的明细链接。

07报告触发方式（4 种）

08报告质量校验（每份报告生成后自动跑）

报告产出 ≠ 报告可信。每份报告产出后必须先过 4 项自动校验，全部通过才推送：

09报告分发与归档

📨 分发规则

🗂️ 归档目录（30 天热数据 + 全量留底）

10报告生成 FAQ