Jumper Kpi Analysis

---
display_name: "天使医生经营分析"
display_name_en: "Angel Doctor KPI Analytics"
description_zh: "通过自然语言查询当前天使医生账号有权限的医院经营指标、渠道分布、同比环比及人员 KPI 完成情况。"
description_en: "Query hospital operations and staff KPI performance within your Angel Doctor account permissions."
version: "1.0.0"
author: "Jumper"
name: jumper-kpi-analysis
description: "使用 Jumper MCP 只读查询和分析医院经营与门店人员的 KPI 数据。门店维度：有效金额、退款、成交、线索/客资/商机漏斗、企微客户数（CRM客户数）、渠道来源、趋势、同比环比、医院与渠道排名，也用于识别收入/利润/成本/净额等当前不支持的口径。支持通过人名、地区/城市匹配医院简称。人员维度：个人 KPI 目标、完成金额、完成率、缺口、达标情况、职级与 KPI 档级、按医院汇总的人员达标率，以及逐日进度（截至某日的月累计、当日新增业绩、每天的走势）。用于回答「某家门店上月业绩多少」「各门店渠道来源对比」「某院这个月新增多少企微客户」「本月环比上月」「某个顾问某月完成得怎么样」「某人某天做了多少」「某门店谁业绩最差」这类问题。不用于数据写入，也不用于非医院经营的问题。"
---

# Jumper 医院经营与人员 KPI 分析

## 两个维度，先选对再读细则

| 维度 | 工具 | 回答什么 |
|---|---|---|
| **门店经营** | `search_hospitals`、`query_hospital_kpi`、`query_hospital_channel_kpi`、`compare_hospital_kpi`、`rank_kpi` | 整店的金额、退款、成交、漏斗、企微客户数、渠道、趋势、同比环比、排名 |
| **门店人员** | `search_staff`、`query_staff_kpi`、`query_staff_daily_kpi`、`query_hospital_staff_summary` | 具体某个人/顾问的 KPI 目标、完成率、达标、逐日业绩，以及各院的人员达标率 |

**硬规则：调用任一维度的工具之前，必须先读对应的细则文件。**

- 门店维度 → 读 `references/hospital-kpi.md`
- 人员维度 → 读 `references/staff-kpi.md`
- 问题同时涉及两边（如「这家店 8 月怎么样，谁做得最差」）→ 两份都读，分别取数，**不要把两边的数字放进同一个计算里**（见下方对照表）。

本文件只有路由与共用规则；参数合同、口径陷阱、输出格式都在细则里。不要凭本文件的摘要回答具体口径问题。

## 两个维度的量纲与时点对照（最容易出错的地方）

|  | 门店经营 | 门店人员 |
|---|---|---|
| 底表 | `ads_hospital_daily_kpi` | `ads_hospital_staff_daily_kpi` |
| 一行代表 | 一家店的**一天** | 一个人的**一个 KPI 月份**的一张快照 |
| 金额单位 | **元** | **万元** |
| 时点语义 | 按日增量：当天发生额 | 每日快照：**截至该日的当月累计** |
| 跨行求和 | 跨日相加 = 区间合计 ✅ | 跨快照日相加 ❌（同一笔业绩重复几十次） |
| 日粒度怎么来 | `granularity="day"` 直接给 | 相邻两天的累计值**相减**（`dailyAmount`） |
| 数据完整性信号 | `containsPartialDay` + `containsIncompleteSource` | `monthInProgress` + `monthEnded` |
| 覆盖范围 | 全店经营额 | 只统计配置了 KPI 的人 |

**两边金额相差 1 万倍，且口径不同：禁止相互印证、比较、相减或算占比**（如「人员完成额占门店业绩多少」）。也禁止用门店数据推断个人业绩（按人数摊人头、由店推人）。

## 共用硬规则

1. 只查询和分析，不执行写入、修改、删除。
2. 工具名、参数名按细则精确填写；工具名或参数结构若与文档不同，以调用时实际暴露的 Schema 为准。
3. **ID 一律是不透明别名**：医院 `H_`、渠道 `C_`、人员 `U_` + 10 位大写十六进制（如 `H_3F7A2B9C41`）。必须原样使用 `search_hospitals` / `search_staff` 的返回值；服务端只认别名，**传真实数字 ID 会被直接拒绝**。禁止自行拼造、禁止传 JSON 数字、禁止传数组；多个 ID 用英文逗号连成一个字符串。
4. 可选参数不需要时直接省略，不传 `null`、空字符串或自造默认值。
5. 业务日期按 `Asia/Shanghai` 换算。
6. 已取得唯一 ID 后只传 ID，不要再同时传 keyword。
7. OAuth 登录、授权、令牌刷新由 MCP 客户端管理（WorkBuddy 中由连接器管理）；只通过客户端打开的授权页面登录，不在对话中索取或输出密码、访问令牌、刷新令牌、API Key，也不改用 API Key 绕过 OAuth。
8. 本 Skill 中「全部医院」「全国」「整体」均限于当前账号授权可见的范围；结果不足以证明全平台覆盖时，输出写「当前账号可见范围」，不得声称全国全量。空结果也可能由可见范围限制产生。

## 消歧通则

1. 用户点名医院 → 先 `search_hospitals`；点名某个人 → 先 `search_staff`。医院 ID 在两个维度的工具之间通用。
2. 出现多个同样合理的匹配（同名院区、跨院同名人员）→ 列出可区分的信息让用户选择，未确认前不下结论，**不要默认取第一个**。
3. 搜索无匹配 → 说明当前账号可见范围内未找到该医院/人员，**不等于「业绩为 0」或「没有业绩」**。
4. 用户提到**人名**（如李兵、刘乐）或**地区/城市**（如重庆、北京）时，这类词往往是医院正式名称或简称的一部分（如「李兵妇产医院」「重庆安琪儿」），不要当成「没点名医院」而按全部医院查。先用该词作 `keyword` 调 `search_hospitals` 定位医院；拿到 `hospitalId` 后，其余医院类工具照常按 ID 使用，命中多家按第 2 条消歧。问的若是这个人自己的 KPI（目标、完成率、达标、逐日业绩），仍按第 1 条先 `search_staff`；两种都讲得通时先搜医院，搜不到再按人员处理。

## 分页通则

查询类工具返回统一包装：`total`、`page`、`pageSize`、`truncated`、`hint`、`items`。

1. `truncated=true` 只表示**本次没有返回全部**，不代表「还有下一页」——最后一页的 `truncated` 仍然是 `true`。是否还有下一页以 `page * pageSize < total` 为准，禁止只看 `truncated` 无限翻页。
2. 需要全量时首次传 `pageSize=500` 减少调用次数；只要前 N 名时传 `pageSize=N`，不必取全。
3. `total>0` 但当前页 `items=[]`，通常是页码越界，不代表没有数据。
4. 合并每页 `items`，不要重复计算已取过的页；未取全结果前，不做整体趋势、排名或汇总类结论。
5. 部分工具不分页（`search_hospitals`、`search_staff`、`rank_kpi`），各维度细则里有说明。

## 结果判定通则

- `total=0` 且 `items=[]`：**先读 `hint`（若有）**。区分「数据尚未更新到该时间」「当前账号可见范围内未找到对象」「该时间段没有返回数据」，**任何一种都不等于「没有业绩」**；没有截止信息时不得编造。
- 字段为 `null`：说明未配置或无法计算，如实说明，不擅自改成 0。
- 完成率、达标率、占比等比率字段都是小数，展示时乘以 100 加 `%`（`0.3031` → `30.31%`）。
- `401` / `invalid_token`：让用户在 MCP 客户端完成登录或重新授权，恢复后再查；不要修改业务参数反复重试。
- `403` / 权限不足：说明当前授权无法访问，请用户核对账号或联系管理员；不扩大查询范围、不换凭据绕过。
- 明确的参数校验错误：按提示改参数后重试一次；网络超时或服务暂不可用：保持原查询条件最多重试一次，仍失败则说明查询未完成。**任何报错都不能转述成「查无数据」**。
- 只描述数据支持的事实，不推断原因（不说「因为不努力」「因为客户少」）。

## 输出通则

先给结论，再给证据，最后集中说明数据限制（周期是否走完、数据截止到哪天、是否分页取全、未配置 KPI 的人数等）。

金额一律写明单位：门店金额是**元**，人员金额是**万元**，同一段话里同时出现时必须分别标注，不能只报数字。

## 共用禁止事项

- 禁止把门店金额（元）与人员金额（万元）相互印证、比较、相减或算占比。
- 禁止用门店维度的数据推断某个人的业绩，或用某个人的数据推断整店经营额。
- 禁止跳过细则文件，凭本文件的摘要回答具体的参数或口径问题。
- 禁止把 ID 当数字或数组传递，或使用未经 `search_*` 返回的自造别名。
- 禁止在医院/人员未消歧时用模糊关键字混查后只取第一个。
- 禁止把空结果或报错说成「这家店/这个人没有业绩」。
- 禁止虚构工具未返回的指标（收入、利润、成本、净额、真实转化率、个人的门店经营额等）。