Shopkeeping

---
name: "秒绘管家"
display_name: "秒绘管家"
display_name_en: "Shopkeeping"
description: "当用户需要查询秒绘管家的门店经营、会员、预约、回访、订单或库存时使用；先完成 OAuth 授权，仅调用实时目录中当前员工可用的只读工具。"
description_zh: "通过自然语言查询当前员工有权访问的店务数据，提供只读经营分析。"
description_en: "Use authorized read-only Shopkeeping tools to query shop operations and business data."
version: "1.0.1"
author: "秒绘管家"
---

# 秒绘管家

当用户提到秒绘管家或需要查询门店经营、会员、预约、回访、订单、员工业绩、库存时使用。
只提供查询和分析；可用能力取决于本次连接实时返回的工具目录，不假定所有工具已上线或已授权。

## 连接与授权

首次使用时由 WorkBuddy 按标准 MCP OAuth 流程打开秒绘管家登录与授权页。
未登录时先登录，选择正确员工/商户，再确认授权。管理员须事先为该员工分配 MCP 席位及所需 AI 工具权限。
不向用户索要密码、API Key 或令牌，不在对话、参数或示例中填写凭证。
令牌过期由 WorkBuddy 自动刷新；刷新失败或授权撤销时，引导用户重新连接。

可调用工具由当前员工的 AI 工具权限决定，后台菜单权限不代替 AI 工具权限。
如果某个工具未出现在实时目录中，不应尝试绕过权限调用。

## 调用步骤

1. 先读取 MCP 实时工具目录，依据工具描述及 `inputSchema` 选择工具。只有目录中出现的工具才可调用。
2. 未明确门店 ID 时，若目录有 `shop.list`，先用空对象查询可访问门店。门店名称不唯一或有多家门店时询问用户选择，不猜 ID。
3. 根据实时 schema 填写参数，检查类型、必填字段、枚举、默认值、日期范围与分页上限。不添加 schema 未声明的字段，不构造员工、商户或权限身份。
4. 将“今天”“明天”等日期转换为业务时区 Asia/Shanghai 的明确日期；不把示例中的日期或 ID 当成真实查询参数。
5. 只执行满足用户请求的最少查询。跨门店经营汇总优先用目录中可用的批量工具，避免逐店并发查询。
6. 根据实际结构化结果回答，说明门店、时间范围、币种/单位及无数据情况；保留金额精度。不要把查询失败或缺失值解释为零，也不要把部分分页结果当成全量统计。

## 核心工具选择

下列名称用于选工具；每次以实时目录为准。工具不存在时说明当前不可用，不改名探测或绕过权限。

| 工具 | 用途 |
| --- | --- |
| `shop.list` | 当前员工可访问的门店名称和 ID |
| `report.business_overview` | 单门店、明确日期区间的经营金额概览 |
| `report.business_overview_batch` | 多门店经营汇总、比较及趋势 |
| `staff.list` | 单门店在职员工目录 |
| `member.search` | 按用户提供的文字在指定门店定位会员 |
| `member.summary` | 已定位会员的概要与最近订单 |
| `appointment.list` | 指定门店和日期范围的预约日程 |
| `revisit.task_list` | 指定门店和日期范围的待回访任务 |
| `revisit.statistics` | 回访执行统计 |
| `report.staff_performance` | 指定门店的员工业绩汇总 |
| `report.member_analysis` | 会员生命周期人数与变化 |
| `report.revenue_summary` | 营收汇总，保持营收业务口径 |
| `report.collection_summary` | 实收汇总，与营收分开解读 |
| `order.search` | 通过会员 ID 或订单号查询基础订单 |
| `inventory.stock_list` | 仅当实时目录已提供时查询门店库存 |
| `inventory.movement_list` | 仅当实时目录已提供时查询库存项入出库流水 |
| `report.asset_summary` | 仅当实时目录已提供时查询资产日快照，不称为实时资产 |
| `report.customer_visit_trend` | 仅当实时目录已提供时查询到店人数与日趋势 |

## 参数和返回格式

MCP 工具目录内的 `inputSchema` 是字段类型、必填和默认值的依据，工具描述补充日期/分页范围。
不同工具使用的日期字段可能是 `startDate/endDate` 或 `dateFrom/dateTo`，不可混用。
门店 ID 从 `shop.list` 或用户明确提供的系统 ID 获取；会员 ID、库存项 ID 从对应查询结果获取，不能用手机号或产品 ID 替代。
可选分页参数没有显式要求时采用实时 schema/描述中的默认值；需要更多记录时按工具支持的分页方式继续。
默认值、支持字段或输出版本变更时，以实时声明为准，不沿用本文示例覆盖它。

调用示例（以下 ID 和日期仅用于解释格式，执行时使用已确认的真实门店和日期）：

```json
{"name":"shop.list","arguments":{}}
```

```json
{"name":"report.business_overview","arguments":{"shopId":123,"startDate":"2026-10-08","endDate":"2026-10-08"}}
```

`shop.list` 返回门店集合及 `shopId/shopName`；单店经营概览的结构化数据包含门店、日期、
`amountUnit` 和经营金额指标。业务结果通常在 MCP `structuredContent` 中，`content` 提供可读内容。
只使用实际返回的字段；金额按 `amountUnit` 解释，精确十进制字符串不得随意四舍五入。
`isError=true` 或协议错误表示失败，不能把其错误正文当作业务数据。

## 异常恢复与只读边界

- 未连接、401 或授权过期：让 WorkBuddy 处理 OAuth 刷新；无法恢复时提示重新连接。
- 工具缺失、权限不足或不可见对象：说明当前账号不可用，建议管理员核对 AI 工具权限、席位及门店范围；不尝试其他身份或随机 ID。
- 参数错误：根据实时 schema 和用户已确认的信息修正，缺少必要信息时询问用户。
- 限流：遵循返回的重试间隔；余额/调用额度不足时提示管理员处理，不循环调用。
- 超时或服务不可用：说明暂时无法获取结果，停止当前查询，不重复并发请求或伪造数据。
- 不执行付款、退款、开单、库存变更、修改会员资产、权限或其他写操作。用户要求写操作时引导到秒绘管家业务页面；用户确认也不会使本连接器获得写能力。
- 只展示完成请求所需的数据，不反推脱敏手机号，不输出完整凭证或内部地址。