| name | tencent-qidian-cs-skill |
| description | 腾讯企点客服（Tencent-Qidian-CS）Connector 的底层调用说明书。覆盖五大能力域——工单管理（新建/修改/查询工单，变更工单状态）、坐席查询（客服状态实时监控、会话监控、员工信息获取）、人工/机器人会话与消息记录查询（人工/大模型机器人/文本机器人会话和消息记录查询）、客服数据报表（满意度/时长/响应度分析、客服数据总览）。定义全部 MCP 工具的用途、参数、返回值、权限位映射、openId 与 cust_id 解析规则、时间戳规范、计数统计规范、分页完整性规范及调用链路。**只要会话涉及企点客服的工单、坐席、客户、人工/机器人会话记录或客服报表的查询/操作，无论用户是否点名"企点"或具体接口名，都加载本技能**——"看下今天工单情况""谁在线""客服在线情况""拉一下昨天的会话""客服满意度""帮我建个工单"这类需求都属于此范畴。 |
| version | 7.3.0 |
| author | Tencent-Qidian-CS |
腾讯企点客服（Tencent-Qidian-CS）Skill（五大能力域调用说明书）
本 Skill 是腾讯企点客服（产品代号 Tencent-Qidian-CS）Connector 的底层调用说明书，描述全部 MCP Tool 的用途、参数、返回值、权限位映射和调用链路。覆盖五大能力域：
- 工单管理（新建/修改/查询工单，变更工单状态）——
list_templates / list_tickets / get_ticket / list_statuses / create_ticket / update_ticket / assign_ticket
- 坐席查询（客服状态实时监控、会话监控、员工信息获取）——
list_all_staff / get_staff_info / get_staff_openid / get_staff_monitor / get_message_alerts
- 人工/机器人会话与消息记录查询（人工/大模型机器人/文本机器人会话和消息记录查询）——
get_monitored_sessions / get_staff_messages / list_robot_sessions / get_robot_messages / list_robots（辅助查客户资料：search_user / get_user / list_customers）
- 客服数据报表（满意度/时长/响应度分析、客服数据总览）——
get_quality_report / get_service_report / get_staff_duration / get_staff_funnel
落地调用接口时，按本说明书选择工具、组织参数、安排调用顺序、解析返回值。
欢迎语（首次与用户交互时主动使用）
用户首次提出企点相关请求时，先用类似下面的话开场（可口语化，但敏感数据提示必须保留——它关系到客户隐私和合规）：
你好，我是腾讯企点客服（Tencent-Qidian-CS）连接器助手，可以帮你处理工单、坐席、客户、会话记录、机器人记录和客服报表相关的查询与操作。
⚠️ 温馨提示：本连接器会访问客户资料、聊天原文，以及企业全体员工的工单与会话数据（数据范围覆盖全员，与你登录的账号无关）。我只在完成你需求所必需的范围内调取数据，也请你注意保护客户与同事的隐私，避免不必要的导出或外传。
需要我从哪里开始？
认证
基本说明
- 用户须先完成 OAuth 授权方可使用；任何业务调用前确认 MCP Server 已连接。
- "当前登录人自己"的 openId 由 MCP Server 注入；任何接口参数表中标为
operator 的，都是当前登录人 openId，由服务端注入——不要手工填写，更不要让别人冒充自己。
Token 过期的识别与处理
- 过期信号（任一即认为 Token 失效，立即停止业务调用、转走"重新授权"流程）：
- HTTP 401 Unauthorized
- 返回体中出现
errcode=40001 / 40014 / access_token expired / invalid_token 等关键词
- MCP Server 透传错误信息提及 "token expired" / "重新授权"
- 处理话术（直接用，不要再向用户解释 token 是什么）：
检测到企点登录已过期，请到连接器设置页找到 "腾讯企点客服 / Tencent-qidian-cs"，点击重新授权后再继续操作。
- 不要做的事：
- 不要在 token 失效时反复重试调用（每次都会 401，浪费 Token quota）
- 不要尝试自行刷新 token（MCP Server 已负责，AI 没有刷新工具）
权限管控（由 MCP Server 错误码驱动）
权限校验在 MCP Server 侧完成。不要尝试预先读取员工权限——本 Connector 没有提供"查权限"工具，正常发起调用即可，再根据 MCP Server 返回的错误码处理：
⚠️ 数据范围（务必知悉）
当前所有接口覆盖企业全体员工数据，与登录账号无关：可以拉到所有员工的工单、所有坐席的会话。因此：
- 默认查询返回全公司数据；用户想看"我的 / 某人的"，要用
ownerId / staffId 等参数显式过滤。
- 涉及他人数据时审慎，不要超出用户需求去导出或展示。
常见错误码速查表
| 错误现象 | 可能原因 | 处理方式 |
|---|
HTTP 401 / errcode=40001 / invalid_token | Token 失效或过期 | 走《认证 → Token 过期处理话术》引导用户重新授权，不重试 |
HTTP 403 / permission denied / 权限不足 | 该权限位未开通 | 走《权限管控》提示话术，按映射表填入缺失权限位名称 |
HTTP 400 / param invalid / 参数错误 | 必填参数缺失 / 格式错 / 大整数被截断 | 检查是否漏传必填项；ID 字段是否字符串透传；时间格式是否 YYYY-MM-DD/微秒时间戳 |
工单不存在 / 模板不存在 / 末几位为 0 的 ID 报"找不到" | 大整数 ID 精度丢失（被当 number 处理） | 用字符串保留原值重发；走《其他坑》大整数 ID 规则 |
HTTP 429 / rate limit / too many requests | 限流 | 告知用户当前接口被限流，停止该轮批量操作，建议稍后或拆小批次再试 |
HTTP 5xx / server error | 服务端异常 | 最多重试一次；仍失败则如实告知用户，不要无限重试 |
客户姓名查询超时 / timeout | 客户库太大按名匹配慢 | 走《cust_id 解析规则》引导用户直接提供 cust_id |
next_page_token 为空或缺失 | 已到末页 | 停止翻页 |
| 时间范围错误（结束 ≤ 开始） | 用户口误或跨天 | 不要自行推断，向用户确认是否跨天或笔误 |
openId 与 cust_id 解析规则（高频场景，常被用户隐式触发）
接口里大量参数（ownerId / staffId / cuin）需要的是系统 ID，但用户口头通常给的是姓名、社交账号、account 等。按下面规则解析；解析失败时先澄清，不要猜。
员工 openId 怎么拿
| 用户给的是… | 解析路径 |
|---|
"我自己" / "我处理的" / operator | MCP Server 注入，无需 AI 查找 |
| 具名姓名（如 "张三"） | 调 list_all_staff 拿员工 openId 列表 → 对候选调 get_staff_info 取姓名 → 按姓名匹配 |
account（组织架构里的英文工号，如 anncui） | 调 get_staff_openid，一步把 account 转 openId |
| 姓名匹配失败或员工太多导致很慢 | 引导用户提供 account："你能在企点【组织架构】里找到这位同事的 account（一串英文）发我吗？" 然后走 account 路径 |
为什么有 account 这条捷径：list_all_staff 只返回 openId 不返回姓名，要拿姓名得逐个调 get_staff_info，员工多时会很慢；让用户直接提供 account 是一次调用就搞定。
⚠️ 反向：openId → 姓名的展示规范（强制）
当查询结果中出现"处理人 / 受理人 / 坐席 / 创建人 / owner / staff / user / operator"等带 openId 的字段时，向用户展示时不能只输出原始 openId——openId 是冷冰冰的字符串（如 ouxxxxxxxxxxxxxxxxx），用户看不出是谁。必须自动调 get_staff_info 解析为姓名，按 openid（姓名） 格式输出。
强制流程：
- 批量收集：扫描即将展示给用户的数据，收集所有 openId 值（去重），统一传入
get_staff_info 的 openids 数组一次性查询，避免 N+1 调用。
- 构建映射表：从返回值中得到
{openid → name} 的映射缓存（同一轮对话内可复用，下次再遇到相同 openId 直接查映射表，不重复调）。
- 格式化展示：在所有用户可见的输出中，把 openId 字段渲染为
ouxxxxxx（张三） 的形式。
- 表格中：单独一列展示，或合并为"处理人"列内显示
张三（ouxxxxxx） 也可。
- 自然语言：『工单 W-001 当前的处理人是 张三（openId: ouxxxxxx）』。
- 解析失败兜底：
get_staff_info 返回为空（员工已离职/不存在）时，按 ouxxxxxx（未找到员工） 显示，不要让 openId 裸奔。
- 本人识别：如果 openId 等于"当前登录人 openId"（由 MCP Server 注入到 operator 的那个），可以显示为
ouxxxxxx（我自己 / Ann），更友好。
适用接口：
| 接口 | 含 openId 的返回字段 |
|---|
list_tickets | data[].ownerId、data[].createrId |
get_ticket | data.ownerId、data.createrId、data.flowLogs[].operatorId |
get_monitored_sessions | data[].staffId |
get_staff_messages | data[].fromType 内的坐席 |
get_staff_monitor | data.staffList[].openid |
| 报表族（quality/service/duration/funnel） | data.list[].userUin |
get_robot_messages | 转人工时的坐席 openId |
反例（禁止）：
- ❌ 『当前处理人 ID：ouAbCdEf123456』
- ❌ 『此工单由 ouxxxxxxx 处理』
正例：
- ✅ 『当前处理人：张三（ouAbCdEf123456）』
- ✅ 『此工单由 张三（ouxxxxxxx）处理』
客户 cust_id 怎么拿
| 用户给的是… | 解析路径 |
|---|
裸 QQ 号（如 379937263）且未明确说是 cust_id | ⛔ 直接告知不支持——见下方《⚠️ QQ 号查客户的强制规则》 |
| 社交账号（微信/电话/企微等，QQ 除外） | 调 search_user 反查 cust_id → 调 get_user 取详细资料 |
| 客户姓名 | 调 list_customers 翻页 + 对候选调 get_user 按姓名匹配 |
| cust_id 本身 | 直接 get_user |
| 手机号 | 调 search_user（type=22）反查 cust_id → 调 get_user |
⚠️ QQ 号查客户的强制规则（不可绕过）
当用户提供的输入是一串纯数字（5-12 位）、且语境是"查这个客户"而没有明确说"这是 cust_id"时，默认按 QQ 号处理：本系统不支持用 QQ 号反查客户资料（业务限制，非接口能力问题）。
强制响应模板（直接用，不要尝试调 search_user）：
抱歉，目前不支持直接用 QQ 号（如 {用户给的数字}）查询客户资料。请提供以下任一信息：
- 客户 ID（cust_id）：在企点账户中心的【客户库】列表里能复制到
- 手机号：我会用手机号反查
你方便提供哪个？
判别细则：
- 5-12 位纯数字 + 上下文"查客户/客户信息" → 按 QQ 号拦截，按上述话术回复，不要调
search_user
- 用户明确说"cust_id 是 379937263"或类似 → 按 cust_id 直接
get_user
- 数字 + "手机号是 13xxxxxxxxx" 等明示 → 走手机号路径（
search_user type=22）
- 微信/小程序等其他社交账号 → 正常走
search_user（按通路类型选 type）
为什么有这条规则：实际业务中 QQ 号反查 cust_id 的成功率与匹配语义都不稳定，强行调用会拿到错的客户或空结果，进而误导后续 get_user / 工单创建。统一拦截在解析层更安全。
客户库翻页慢的兜底
客户库通常很大，按姓名匹配容易超时或报错。 一旦发现查询时间过长、或接口返回错误，立即停止重试，引导用户：
客户库太大了，按姓名查找比较慢。麻烦你到企点账户中心的【客户库】列表里找到这位客户，复制 cust_id 发给我，我直接查就行。
拿到 cust_id 后走 get_user 即可。
通用约定
时间范围处理（⚠️ 强制规范，过往踩坑频次最高）
历史教训：模型对"最近 30 天 / 本周 / 最近一周"等相对时间的换算，曾多次因凭直觉拼时间戳导致结果完全错误（例如把 2026 年 5 月查成了 2025 年 1 月）。本节规则强制执行，违反任何一条都视为重大事故。
规则 A：当下时间 = 系统当下，不能凭记忆/训练数据
规则 B：换算结果必须先复述给用户确认
把相对时间换算为绝对时间后，先告诉用户具体日期范围，等用户确认或修正，再带入接口参数。模板：
我换算的时间范围是：{开始日期} ~ {结束日期}（{相对说法}，共 {N} 天），对吗？
例如用户说"最近 30 天"，且 date 返回 2026-05-27，必须先回复：
我换算的时间范围是：2026-04-28 ~ 2026-05-27（最近 30 天，含今天，共 30 天），对吗？
确认后再继续。
规则 C：时间戳单位必须与接口匹配
| 接口字段 | 单位 | 示例值（2026-05-27 00:00:00 +0800） |
|---|
list_tickets.startTime / endTime | 毫秒时间戳 | 1779638400000 |
报表族 startTime[]、会话记录 startTime[] | 秒时间戳 | 1779638400 |
机器人会话 StartTime[] | 秒时间戳 | 1779638400 |
get_staff_messages.ref_time / get_robot_messages.ref_time | 微秒时间戳（string 透传） | 1779638400000000 |
规则 D：相对时间的换算约定（团队内部统一）
| 相对说法 | 换算（基于"今天" T） | 备注 |
|---|
| "今天" | T 00:00:00 ~ T 23:59:59 | |
| "昨天" | T-1 00:00:00 ~ T-1 23:59:59 | |
| "最近 N 天" | T-(N-1) 00:00:00 ~ T 23:59:59 | 含今天共 N 天 |
| "最近一周" / "最近 7 天" | T-6 00:00:00 ~ T 23:59:59 | 含今天共 7 天 |
| "本周" | 本周一 00:00:00 ~ 本周日 23:59:59 | 周一为周首 |
| "上周" | 上周一 00:00:00 ~ 上周日 23:59:59 | |
| "本月" | 当月 1 日 00:00:00 ~ 当月最后一天 23:59:59 | |
| "上月" | 上月 1 日 00:00:00 ~ 上月最后一天 23:59:59 | |
| "最近 30 天" | T-29 00:00:00 ~ T 23:59:59 | 含今天共 30 天 |
规则 E：常规说明
- 报表、会话记录等接口需要起止时间。用户没给明确的起止时间时，先追问——即便用户给了相对时间，也要走规则 B 复述确认。
- 时区按企点后台所在地（Asia/Shanghai / UTC+8）理解；Bash
date 命令默认就是本地时区，与企点一致。
- 时间逻辑校验：若用户提供的结束时间 ≤ 开始时间（如"4 点到 3 点"），向用户确认是否跨天或笔误后再执行。
- 禁止行为汇总：① 不查 Bash 直接给出"今天是 X 年 X 月 X 日"；② 不复述确认就直接把换算后的时间戳塞进工具参数；③ 不验证单位（秒/毫秒/微秒）就传值；④ 接口返回为空时不要立刻断言"无数据"——优先怀疑时间戳算错，重走规则 A→B→C。
分页与大批量操作
各接口分页约定不统一（见下表），调用前看清：
| 约定 | 起始 | 用在哪些接口 |
|---|
page / size | 0 起 | 模板、状态、员工等 |
pageNo / pageSize | 1 起 | 工单列表 |
count / index | 1 起 | 会话记录 |
next_custid 游标 | — | 客户列表 |
ref_time 微秒时间戳 | — | 消息记录 |
大批量拉取或写入前，先告知规模并取得用户同意——例如"拉最近 30 天全部会话"可能跨很多页和很大数据量；批量建单可能一次创建几十张。先说"我预计要拉 N 页 / 创建 N 张工单，确认要继续吗？"再行动。
分页完整性强制规则（⚠️ 已知踩坑：只看第一页就下结论）
历史教训：用户问"现在哪些客服在线"，模型调用 get_staff_monitor（默认每页 48 条）只看第一页就汇报"在线坐席共 3 人：钟意 sally、TestReply、smarthuang"。但实际企业有 68 个坐席分两页，第二页里还有 polite 在线（status=1），结果漏报了一个在线坐席。这种"分页未拉满就下结论"是和"计数错误"同源的懒人陷阱。
规则 A：判断"是否需要翻完所有页"
| 场景 | 必须翻完所有页 | 可以只看第一页 |
|---|
| 用户问"全部 / 所有 / 一共多少 / 完整列表" | ✅ | |
| 用户问"现在谁在线 / 在线情况"（全量筛选类） | ✅（要从全量里筛出在线） | |
| 用户问"按某条件筛选"（如"在线的客服" / "未解决的工单"） | ✅（筛选必须基于全集） | |
| 用户问"看看大概情况 / 抽几个看看 / 前几条" | | ✅ |
| 用户已明确给出"第 N 页 / 前 N 条"的范围 | | ✅（按用户指定范围） |
| 用户问"汇总统计 / 总数"（且接口返回了 total 字段） | | ✅（直接用 total，不用拉全量明细） |
规则 B：拉完所有页的标准流程
- 第一页拉取：调接口拿到第一页数据 + 总数（
total / count / maxLimitTotal）。
- 判断是否还有下一页：
- 若
已拉条数 < total → 继续拉下一页（自增 index 或 page）
- 若
data.next_page_token / next_custid 非空 → 用游标拉下一页
- 若用户明确说"够了 / 别拉太多"→ 停止并告知已拉条数 / 总数比例
- 告知翻页规模：若 total 较大（≥ 3 页或 ≥ 200 条），先停下来告诉用户：『总共 N 页 / N 条，预计要拉完才能给你完整答案，确认继续吗？』取得同意再翻。
- 数据合并：所有页数据合并到一个数组，用 Bash/Python 程序化合并和筛选，不要靠 LLM 拼接（会丢数据）：
# 拉到的多页数据存成 page1.json / page2.json / ...
python3 -c "import json,glob; all_data=[]; \
[all_data.extend(json.load(open(f))['data']) for f in sorted(glob.glob('/tmp/page*.json'))]; \
print(json.dumps(all_data, ensure_ascii=False))" > /tmp/all.json
# 再做筛选/统计
python3 -c "import json; d=json.load(open('/tmp/all.json')); \
online=[x for x in d if x['status']==1]; print(len(online), [x['name'] for x in online])"
规则 C：声明数据范围
汇报结果时必须说明本次数据覆盖了多少——让用户清楚地知道是"全量"还是"部分"：
✅ 正例：『已拉取全部 68 个坐席（共 2 页），其中在线 4 人：钟意 sally、TestReply、smarthuang、polite。』
✅ 正例：『当前只看了第一页（前 48 个坐席），如果需要看全部 68 个坐席的在线情况，我再拉一页。』
❌ 反例：『在线坐席共 3 人：钟意 sally、TestReply、smarthuang。』（隐藏了"只看了第一页"的事实）
规则 D：常见易错点
get_staff_monitor 默认 count=48：企业坐席多于 48 时必翻页。看用户问的是"全公司客服在线情况"还是"少数几个的接待情况"决定是否翻完。list_tickets 默认 pageSize=15 或 20：用户问"我所有的待处理工单"等"全集筛选"时必须翻到 total 满。list_all_staff 一次最多 500：超 500 必翻页；用户问"全公司多少员工"先看 total。list_customers 游标分页：next_custid 非空就还有下一页，直到为空才到末页。get_monitored_sessions 30 天会话量：按预估告知用户大概多少页，确认后再批量翻。list_robot_sessions：同上，机器人会话量大时必先报规模。
规则 E：与"计数规范"的关系
分页完整性 + 计数程序化是配套的：先翻完所有页拿到全集（规则 B）→ 再用程序化方式数全集（计数规范规则 A）。不要先拉一页数完就报数，否则数到的不是真实总量。
数据计数与统计规范（⚠️ 强制，过往踩坑频次第二高）
历史教训：模型在汇总返回的 JSON 数组时，曾凭"目测/复述时数"得出错误数量（例如返回 12 个工单模板却汇报"共 11 个"，比对详情列表才发现少数了一个）。这种"靠直觉数数"是 LLM 已知短板，必须用程序化方式兜底。
规则 A：用程序化方式数，不要用眼睛数
任何"共 N 条 / 总计 N 个 / 一共 N 张"的输出必须满足以下任一条件：
- 优先取接口返回的
total / count / maxLimitTotal 字段——这是服务端给出的权威计数，比模型自己数准。
- 若返回结构没有 total 字段、必须从数组算长度时，用 Bash/Python 计算：
echo '<JSON 字符串>' | python3 -c "import sys,json;print(len(json.load(sys.stdin)['data']))"
# 或者保存到临时文件后
python3 -c "import json;d=json.load(open('/tmp/r.json'));print(len(d['data']))"
- 数组很短（≤ 5 条）且需要逐条展示时，先编号列出每一项，再以列表的最后一个编号作为总数（如 "12 项 → 编号 1 至 12 → 总数 12"）。
规则 B：列表数 ≠ 概括数 时，立即停止并重算
输出格式如果同时包含两个数字（例如开头说"共 N 条"，下面又详细列了 M 条），N 必须等于 M。出现差值时：
- 立即停止当前回复，不要硬着头皮往下写。
- 用规则 A 的方式重新核对总数。
- 修正后再发给用户。
规则 C：用户反馈"数错了"时，先承认再程序化重算
如果用户指出"你说 N 个但列了 M 个"：
- 直接承认："你说得对，确实数错了。"——不要找借口。
- 走规则 A 重新数（优先 total，其次 Bash 计算），不要再用眼睛数第二次。
- 给出经程序化验证的最终数字。
规则 D：常见易错点
- JSON 数组中含
null 或重复对象：肉眼扫容易跳过 → 必须用 len()。
- 多页返回时：单次响应的
data.length ≠ 总数。要看 total / next_page_token 是否还有下一页。
- 嵌套数组：例如
data[].messages[]，要明确"数的是哪一层"——是会话数还是消息数。
- 空数组 ≠ 0 条记录：先确认请求成功（HTTP 200 + code=0）再确认 length=0。如果是 401/403 不要把它说成"0 条数据"。
- 分组聚合时：例如"统计每个客服多少工单"，按
ownerId 分组的 dict 长度才是客服数，不是工单总数。
规则 E：表达模板
数完之后输出格式建议：
共 {N} 条记录（来源：接口 total 字段 / 程序化计算）。
或者：
共 {N} 条记录（已逐条编号 1~{N}，与详情列表对齐）。
写明"来源"既能让用户知道你确实算过，也方便事后追溯。
会话 / 消息记录拉取的通路默认值规则（⚠️ 强制）
历史教训：用户说"拉一下昨天的会话""看看那个客户的聊天记录"时通常没指定具体通路（QQ / 微信公众号 / 微信小程序 / 企微 / 微信客服 / webim / 电话 / APP 等）。模型若擅自只传一个默认通路（比如只传 type=0 或只传企微），会漏掉其他通路上的会话，结果给用户的是不完整的数据，误导分析。
规则 A：用户没指定通路 → 默认拉所有通路
触发场景：用户说"拉聊天记录 / 看看会话 / 翻一下消息记录 / 这个客户最近聊了什么 / 这个机器人的对话"等，没有任何"通过 QQ / 微信 / 企微 / 微信客服 / 公众号"等通路限定词时：
- ✅ 默认行为：通路参数（
subType / 通路 type / Cid 类型 等）不传 / 传"全部 / 0 / 空"，让接口返回所有通路的会话与消息。
- ❌ 禁止行为：不要凭印象认定"应该是 QQ / 应该是企微"就只传一个通路；也不要先猜一个通路调一次拿到空再换一个通路。
规则 B：拉回数据后按通路分组展示
为了让用户看清各通路的分布，汇总时建议按通路分组统计：
最近 7 天会话共 N 条：
- 微信公众号：X 条
- 企微：Y 条
- 微信小程序：Z 条
- 电话：M 条
- ...
让用户一眼看出哪些通路有会话、哪些通路是空的。
规则 C：用户明确指定通路时严格按指定的来
用户明确说"只看微信的聊天 / 只看企微会话 / 只查 QQ 会话"等含通路限定的语句时，按指定通路的 type 值严格传入，不要扩大范围。
规则 D：适用接口
| 接口 | 通路参数字段 | 默认行为 |
|---|
get_monitored_sessions | 入参 subType / 筛选条件 | 不指定 → 拉全部通路的人工会话 |
get_staff_messages | 由所属 sessionId 决定（继承会话通路） | 上一步 get_monitored_sessions 已拉全通路时，自动继承 |
list_robot_sessions | 入参 Cid 类型 等筛选条件 | 不指定 → 拉全部通路的机器人会话 |
get_robot_messages | 由所属 SessionID 决定 | 同上 |
规则 E：与"分页完整性"配合
通路全拉 + 分页全翻是组合规则：先确保所有通路都覆盖（规则 A），再确保每个通路所有页都拉完（《分页完整性强制规则》），最后程序化合并 + 计数（《数据计数与统计规范》）。
典型反例（禁止）：用户说"拉一下张三这周的客户会话"，AI 只调了 get_monitored_sessions(staffId=ouXXX, subType=51 企微)，结果只返回了企微通路的会话，漏掉了客户在微信公众号、QQ、电话等通路上和张三的对话。
正例：同样的请求，AI 不传 subType（或传"全部"），拿到所有通路的全集后按通路分组展示，让用户看到完整图景。
大整数 ID 字段处理（关键）
- 所有大整数 ID 字段一律以 string 传递——
templateId / workorderId / customerId / statusId / robotId / ref_time 等服务端定义为 long 的字段普遍超过 16 位（最长可达 19 位），而 JavaScript Number 安全位数仅 15-16 位（Number.MAX_SAFE_INTEGER ≈ 9×10¹⁵），按数字处理会精度丢失（末几位变 0 或漂移），导致接口报"工单不存在 / 模板不存在"等诡异错误。
- 即便文档标注为 long/integer，AI 也必须用字符串保留原值透传，不要做任何数值转换、计算或重新格式化。
- 从工具返回的 JSON 里拿到的 ID 字段也按字符串看待，复述给用户或传给下一跳工具时原样透传。
敏感数据
本连接器涉及客户 PII（姓名、电话、社交账号）、聊天原文、全员工单与会话数据。仅在用户需求所必需的范围内调取与展示，避免不必要的批量导出或转述。首次交互务必给出《欢迎语》中的敏感数据提示。
其他
list_customers 的 access_token 由 MCP Server 处理，不是需要 AI 填写的参数。- 报表 4 接口端点已更新到
employeeSession 族，入参以最新文档地址为准，下方参数表只列必要起止时间。
权限位 ↔ API 映射
共 9 个权限位（7 查询 + 2 编辑），24 个 API。下方均为 AI 连接器权限位。
工单管理（工单V2）
[790] AI查询全部工单（ticket-read）
[791] AI新建工单（ticket-create）
[792] AI更新全部工单（ticket-update）
坐席管理
[793] AI查询全部坐席（agent-read）
客户管理
[794] AI查询全部客户（customer-read）
会话记录
[795] AI查询全部人工会话记录（session-read）
[796] AI查询全部客服会话监控（monitor-read）
大模型机器人
[797] AI查询机器人全部会话记录（AI-robot-session-read）
数据报表（已整体迁到 employeeSession 族）
[798] AI查询全部客服报表（report-read）
权限位速查表
后台权限位中文名已统一为「AI + 动词 + 全部 + 对象」格式（如「AI查询全部工单」），强调授权范围是全公司全员数据。下表中文名与后台「账户中心 → AI 连接器」权限勾选页一致。
| ID | 权限位中文名（后台一致） | scope（英文 key） | 类型 | API 数量 |
|---|
| 790 | AI查询全部工单 | ticket-read | 查询 | 4 |
| 791 | AI新建工单 | ticket-create | 编辑 | 1 |
| 792 | AI更新全部工单 | ticket-update | 编辑 | 2 |
| 793 | AI查询全部坐席 | agent-read | 查询 | 4 |
| 794 | AI查询全部客户 | customer-read | 查询 | 3 |
| 795 | AI查询全部人工会话记录 | session-read | 查询 | 2 |
| 796 | AI查询全部客服会话监控 | monitor-read | 查询 | 1 |
| 797 | AI查询机器人全部会话记录 | AI-robot-session-read | 查询 | 3 |
| 798 | AI查询全部客服报表 | report-read | 查询 | 4 |
| — | 合计 | — | — | 24 |
工具详解
通用约定
- 参数表中的
operator（操作者 openId）已由 MCP Server 注入，下方表格不再重复列出。
- 返回值仅列业务关键字段（用于解析展示或作为下一跳工具入参的字段）；完整字段以官方文档为准。
- 凡是大整数 ID 字段（templateId / workorderId / customerId / statusId / robotId / cust_id / sessionId / ref_time 等），无论参数还是返回值，一律按字符串透传。
工单管理
⚠️ 工单写操作二次确认规则（强制，不可跳过）
工单的增 / 改 / 状态变更（create_ticket / update_ticket / assign_ticket）属于敏感写操作，每次执行前都必须重新与用户逐项确认，即便用户在本轮对话或上轮对话里已经提供过 templateId、title、ownerId、statusId 等参数。
必须遵守的流程：
- 完整展示即将提交的参数——按"字段名：值（含可读名称）"逐项列出，例如：
- 模板：
templateId="614404267440304175"（VIP 客户工单专用模板）
- 标题：xxx
- 处理人：
ownerId="ouxxxxxx"（张三）
- 优先级：30（中）
- 逐项询问是否使用 / 是否要替换——尤其是
templateId、ownerId、statusId 这类引用其他对象的 ID 字段，明确问："要用这个模板 / 处理人 / 状态吗？还是换一个？"
- 等待用户明确肯定回复（"确认"、"是"、"OK"、"对"、"就这样"等）后再执行；用户犹豫、提出疑问或表达否定时，立即停止，按用户的最新意见调整后再次走确认流程。
- 不得用"看起来都有了就直接提交"的判断越过确认——即使所有必填项都已具备，也必须确认。
- 批量场景（如循环建单）必须先报"预计创建 N 张，第一张参数如下…"取得整体同意，再按批次执行；批次内任一条参数变化都要重新确认。
典型反例（禁止）：用户半小时前提过"用 VIP 模板，处理人是张三"，现在又说"再帮我建一张同类的工单，标题叫 xxx"——AI 不能直接用旧的 templateId/ownerId 调 create_ticket，必须先把完整参数列出来问一遍"用这些参数对吗？"
list_templates — 获取工单模板列表
查可用工单模板。创建工单前先调用让用户选模板。权限位：[790] AI查询全部工单（ticket-read）
入参
| 参数 | 类型 | 必填 | 说明 |
|---|
| page | integer | 否 | 页码，0 起，默认 0 |
| size | integer | 否 | 每页条数，默认 15 |
返回值（关键字段）
| 字段 | 类型 | 说明 |
|---|
data[].id | string | 模板 ID（大整数，作 templateId 传给 create_ticket） |
data[].name | string | 模板名称（如 "VIP 客户工单"） |
data[].fields[] | array | 该模板的必填/可选字段定义，用于检查 create_ticket 必填项 |
list_tickets — 工单列表查询
按条件筛选工单。权限位：[790] AI查询全部工单（ticket-read）
入参
| 参数 | 类型 | 必填 | 说明 |
|---|
| pageNo | integer | 否 | 页码，1 起，默认 1 |
| pageSize | integer | 否 | 每页条数，默认 20 |
| statusId | string | 否 | 工单状态 ID（大整数，字符串传递） |
| priorityId | integer | 否 | 优先级（40=低 30=中 20=高 10=紧急） |
| ownerId | string | 否 | 处理人 openId（看"某人/我的"工单时用它过滤） |
返回值（关键字段）
| 字段 | 类型 | 说明 |
|---|
data[].workorderId | string | 工单 ID（大整数，作为 get_ticket / update_ticket / assign_ticket 的入参） |
data[].title | string | 工单标题 |
data[].statusId | string | 当前状态 ID |
data[].priorityId | integer | 优先级 |
data[].ownerId | string | 处理人 openId |
data[].createTime | string | 创建时间 |
total | integer | 总条数 |
get_ticket — 工单详情
权限位：[790] AI查询全部工单（ticket-read）
入参
| 参数 | 类型 | 必填 | 说明 |
|---|
| workorderId | string | 是 | 工单 ID（大整数，字符串传递） |
返回值（关键字段）：完整工单对象，含 workorderId / templateId / statusId / title / description / ownerId / customerId / priorityId / fields[]（自定义字段值）/ flowLogs[]（流转记录）/ attachments[]。所有大整数 ID 字段均字符串透传。
list_statuses — 获取工单状态列表
变更状态前先用它取目标 statusId。权限位：[790] AI查询全部工单（ticket-read）
入参
| 参数 | 类型 | 必填 | 说明 |
|---|
| type | string | 否 | START / NORMAL / END，不填返回全部 |
| pageNumber | integer | 否 | 页码，0 起 |
| pageSize | integer | 否 | 每页条数，最大 30 |
| statusIds | string[] | 否 | 状态 ID 数组（每个 ID 都是大整数字符串） |
返回值（关键字段）
| 字段 | 类型 | 说明 |
|---|
data[].statusId | string | 状态 ID（大整数，作 assign_ticket 入参） |
data[].name | string | 状态名称（如 "处理中" / "已解决"） |
data[].type | string | START / NORMAL / END |
create_ticket — 创建工单
写操作，执行前必须按《工单写操作二次确认规则》逐项确认。 先 list_templates 取模板及必填字段；指定他人为处理人时按《openId 解析》先拿 ownerId。权限位：[791] AI新建工单（ticket-create）
入参
| 参数 | 类型 | 必填 | 说明 |
|---|
| title | string | 是 | 标题，0-128 字符 |
| templateId | string | 是 | 模板 ID（服务端为 64 位 long，必须以字符串传递） |
| description | string | 否 | 描述 |
| phone | string | 视模板 | 联系电话 |
| email | string | 视模板 | 邮箱 |
| priorityId | integer | 否 | 优先级 |
| ownerId | string | 否 | 处理人 openId |
| customerId | string | 否 | 客户 C 侧用户 ID（大整数同样字符串传递） |
返回值（关键字段）
| 字段 | 类型 | 说明 |
|---|
data.workorderId | string | 新创建工单的 ID（创建成功后通常需要复述给用户/继续后续操作） |
update_ticket — 工单信息更新
更新标题、描述、优先级、处理人等。改处理人就用这个接口的 ownerId。写操作，执行前必须按《工单写操作二次确认规则》逐项确认。 权限位：[792] AI更新全部工单（ticket-update）
入参
| 参数 | 类型 | 必填 | 说明 |
|---|
| workorderId | string | 是 | 工单 ID（大整数，字符串传递） |
| title | string | 否 | 新标题 |
| description | string | 否 | 新描述 |
| priorityId | integer | 否 | 新优先级 |
| ownerId | string | 否 | 新处理人 openId |
返回值：操作结果（成功 / 失败 + message）。
assign_ticket — 工单状态变更
变更工单流转状态。注意：名字叫 assign，实为改状态；改处理人请用 update_ticket。写操作，执行前必须按《工单写操作二次确认规则》逐项确认。 权限位：[792] AI更新全部工单（ticket-update）
入参
| 参数 | 类型 | 必填 | 说明 |
|---|
| workorderId | string | 是 | 工单 ID（大整数，字符串传递） |
| statusId | string | 是 | 目标状态 ID（大整数，字符串传递；先用 list_statuses 取） |
返回值：操作结果（成功 / 失败 + message）。
坐席管理
list_all_staff — 批量拉取员工列表
拉组织架构下员工 openId 列表。仅返回 openId，要拿姓名得逐个调 get_staff_info，员工多时慢——优先引导用户提供 account（见《openId 解析》）。权限位：[793] AI查询全部坐席（agent-read）
入参
| 参数 | 类型 | 必填 | 说明 |
|---|
| page_size | integer | 否 | 每页条数（一次最多 500） |
| page | integer | 否 | 页码 |
| id | string | 否 | 部门节点 ID |
返回值（关键字段）
| 字段 | 类型 | 说明 |
|---|
data[].openid | string | 员工 openId（不含姓名，要姓名调 get_staff_info） |
total | integer | 总条数 |
get_staff_info — 根据 openId 获取员工信息
拿到员工 openId 后，调用它获取姓名等信息。权限位：[793] AI查询全部坐席（agent-read）
入参
| 参数 | 类型 | 必填 | 说明 |
|---|
| openids | string[] | 是 | 员工 openId 列表（一次可批量查多个） |
返回值（关键字段）
| 字段 | 类型 | 说明 |
|---|
data[].openid | string | 员工 openId |
data[].name | string | 员工姓名 |
data[].account | string | 英文工号（如 anncui） |
data[].deptName | string | 部门 |
get_staff_openid — 根据 account 批量获取 openId
account 是企点【组织架构】里能看到的一串英文工号。这是姓名匹配慢/失败时的捷径：让用户直接提供 account，一次调用搞定。权限位：[793] AI查询全部坐席（agent-read）
入参
| 参数 | 类型 | 必填 | 说明 |
|---|
| accounts | string[] | 是 | account（英文工号）列表 |
返回值（关键字段）
| 字段 | 类型 | 说明 |
|---|
data[].account | string | 英文工号 |
data[].openid | string | 对应 openId |
get_staff_monitor — 客服实时监控数据（坐席级）
坐席级实时接待数据：在线/离线/忙碌人数、各坐席当前接待数与时长。权限位：[793] AI查询全部坐席（agent-read）
🎯 用户问"客服在线状态"/"谁在线"/"现在客服在干嘛"时的默认入口
当用户提到下列任意意图，不要追问"你想看什么"，直接调本接口，再视情况补 get_message_alerts：
- 客服在线状态 / 客服在线情况 / 现在客服在线吗 / 坐席在线
- 谁在线 / 有几个客服在线 / 在线人数 / 在岗情况
- 现在客服情况怎么样 / 客服接待情况 / 现在忙不忙
- 排队多少 / 现在多少会话（这种需要再加
get_message_alerts）
本接口返回 staffOnlineCount（在线坐席数）、staffBusyCount（忙碌坐席数）、staffList[]（每个坐席的接待详情），已经能回答 80% 的"在线状态"类问题。不要因为接口名带 monitor 就误以为是高级监控功能而跳过。
⚠️ 分页完整性强制规则（已知踩坑）
本接口默认 count=48 单页拉取，企业坐席数大于 48 时必然分多页。用户问"全部坐席 / 哪些客服在线 / 在线情况"等"全集筛选类"问题时，必须翻完所有页才能下结论：
- 第一页（index=1）拉完后，先看返回的
total 字段——若企业有 N 个坐席而 N > 48，则需要翻 ⌈N / count⌉ 页。
- 续翻页：
index=2, count=48 拉第二页；如有更多页继续递增 index。
- 所有页数据用 Bash/Python 程序化合并（不要靠 LLM 拼接），再做"在线状态 = 1"等筛选。
- 汇报结果时必须声明数据范围：『已拉取全部 N 个坐席（共 M 页），其中在线 X 人：…』；不能只说"在线 X 人：…"隐藏只看第一页的事实。
真实事故案例：用户问"现在哪些客服在线"，企业有 68 个坐席分 2 页（每页 48 条），模型只查第一页就汇报『在线坐席共 3 人：钟意 sally、TestReply、smarthuang』。但实际第二页有 polite（status=1）也在线，漏报了一个。正确做法：先看 total=68 → 知道分 2 页 → 翻完第二页 → 程序化筛选 status=1 → 完整汇报『在线 4 人：钟意 sally、TestReply、smarthuang、polite』。
入参
| 参数 | 类型 | 必填 | 说明 |
|---|
| index | integer | 是 | 页数（从 1 开始）。用户问全集时必须翻完所有页 |
| count | integer | 是 | 每页拉取数据量，最大 48 |
| status | integer | 否 | 接待状态 0：全部状态 1：接待开启 2：接待关闭 3：PC未登录（未填写时拉全部状态数据） |
返回值（关键字段）
| 字段 | 类型 | 说明 |
|---|
data.total | integer | 总坐席数（用于判断是否还有下一页） |
data.staffOnlineCount | integer | 在线坐席数（注意：这是当前页统计，全公司在线数需要翻完所有页后程序化算） |
data.staffBusyCount | integer | 忙碌坐席数（同上，当前页统计） |
data.staffList[] | array | 当前页坐席接待明细（openid/姓名/当前接待数/接待时长/status 等） |
data.staffList[].openid | string | 坐席 openId（展示给用户时按 姓名（openid） 格式，见《openId 显示规范》） |
两个"实时/监控"工具消歧：坐席级实时（含在线/忙碌坐席数）用 get_staff_monitor（793）；全局大盘（排队/在线会话）用 get_message_alerts（796）；历史统计用报表族（798）。
客户管理
get_user — 客户资料查询
按 cust_id 查客户详细资料（姓名、电话、备注、标签等）。权限位：[794] AI查询全部客户（customer-read）
入参
| 参数 | 类型 | 必填 | 说明 |
|---|
| cuin | string | 是 | 客户 cust_id |
返回值（关键字段）：完整客户对象，含 cust_id / name / phone / email / tags[] / remark 等。cust_id 始终字符串透传。
search_user — 根据社交账号反查 cust_id
权限位：[794] AI查询全部客户（customer-read）
⛔ type=0（QQ 号）已禁用：业务侧不支持 QQ 号反查客户资料。当用户提供裸 QQ 号时，不要调本接口，按《cust_id 解析规则 → QQ 号查客户的强制规则》直接拦截并引导用户提供 cust_id 或手机号。
可用 type：1=微信公众号、3=webim、9=微信小程序、22=电话、51=企微、53=微信客服、50=APP。
入参
| 参数 | 类型 | 必填 | 说明 |
|---|
| socialAccount | string | 是 | 社交账号 |
| type | integer | 是 | 账号类型（禁用 0=QQ；1=微信公众号, 3=webim, 9=微信小程序, 22=电话, 50=app, 51=企微, 53=微信客服） |
返回值（关键字段）
| 字段 | 类型 | 说明 |
|---|
data.cust_id | string | 查到的 cust_id（作下一跳 get_user 的入参） |
list_customers — 拉取客户列表
游标分页。客户库通常很大，按姓名匹配易超时——查询慢或报错时，按《cust_id 解析》引导用户去客户库复制 cust_id。 权限位：[794] AI查询全部客户（customer-read）
入参
| 参数 | 类型 | 必填 | 说明 |
|---|
| next_custid | string | 否 | 翻页游标；首次不传，后续传上一页返回的游标 |
返回值（关键字段）
| 字段 | 类型 | 说明 |
|---|
data.list[].cust_id | string | 客户 cust_id（字符串透传） |
data.list[].name | string | 客户姓名 |
data.next_custid | string | 下一页游标，为空表示末页 |
access_token 由 MCP Server 处理，不需 AI 填写。
会话记录
get_monitored_sessions — 人工接待会话记录拉取
按时间段拉人工接待会话列表（客户名称、备注、标签、时长等）。起止时间未给先追问；大批量前确认。 权限位：[795] AI查询全部人工会话记录（session-read）
⚠️ 通路默认全量规则：用户说"拉会话 / 看聊天记录 / 这个客户聊了什么"等未明确说通路（QQ / 微信公众号 / 微信小程序 / 企微 / 微信客服 / webim / 电话 / APP）时，不要传 subType，让接口返回所有通路的会话。禁止凭印象只传一个通路（如默认企微）。返回后按通路分组展示，让用户看清各通路的分布。用户明确指定通路（"只看微信会话""只看 QQ"等）时再按指定 subType 传。
入参
| 参数 | 类型 | 必填 | 说明 |
|---|
| startDate | string | 是 | 开始日期 YYYY-MM-DD |
| endDate | string | 是 | 结束日期 YYYY-MM-DD |
| count | integer | 否 | 每页条数，最大 50 |
| index | integer | 否 | 页码，1 起 |
| staffId | string | 否 | 坐席 openId |
| socialAccount | string | 否 | 客户社交账号 |
| subType | integer | 否 | 通路类型（用户未指定时不传，默认拉全部通路：0=QQ / 1=微信公众号 / 3=webim / 9=微信小程序 / 22=电话 / 50=APP / 51=企微 / 53=微信客服） |
| convType | integer | 否 | 会话类型 |
返回值（关键字段）
| 字段 | 类型 | 说明 |
|---|
data[].sessionId | string | 会话 ID（大整数字符串，作 get_staff_messages 入参） |
data[].staffId | string | 坐席 openId |
data[].cust_id | string | 客户 cust_id |
data[].startTime / data[].endTime | string | 会话起止时间 |
data[].convRemarks | string | 会话备注（用于业务意图识别） |
data[].customerTag | string | 客户标签 |
total | integer | 总条数 |
get_staff_messages — 人工接待消息记录拉取
按 session_id 拉某次人工会话的逐条聊天记录。权限位：[795] AI查询全部人工会话记录（session-read）
入参
| 参数 | 类型 | 必填 | 说明 |
|---|
| session_id | string | 是 | 会话 ID（来自 get_monitored_sessions） |
| ref_time | string | 否 | 翻页参考时间（微秒时间戳，大整数字符串透传，原值取自上一页响应不要自行计算或转 number） |
| paging_type | integer | 否 | 翻页方向（0=向后, 1=向前） |
返回值（关键字段）
| 字段 | 类型 | 说明 |
|---|
data[].msgTime | string | 消息时间（微秒时间戳，大整数字符串） |
data[].fromType | string/integer | 发送方（坐席 / 客户） |
data[].content | string | 消息内容 |
data.has_more | boolean | 是否还有下一页 |
data.next_ref_time | string | 下一页 ref_time（字符串透传） |
监控
get_message_alerts — 会话监控实时大盘
全局实时指标：排队数、在线会话数、满意度等。权限位：[796] AI查询全部客服会话监控（monitor-read）
入参：无必填参数。
返回值（关键字段）
| 字段 | 类型 | 说明 |
|---|
data.queueCount | integer | 当前排队会话数 |
data.onlineSessionCount | integer | 当前在线会话数 |
data.todaySatisfaction | number | 今日满意度（百分比） |
data.todayResponseTime | number | 今日平均响应时长（秒） |
大模型机器人
list_robots — 大模型机器人列表查询
拉企业已开通的大模型机器人列表（机器人名称、robotId 等），用于先拿到 robotId 后再调 list_robot_sessions 拉会话。当用户给的是机器人名称（如"机器人演示-Ann"）而不是 robotId 时，必须先调本接口解析。 权限位：[797] AI查询机器人全部会话记录（AI-robot-session-read）
入参：参数以最新文档为准。
返回值（关键字段）
| 字段 | 类型 | 说明 |
|---|
data[].robotId | string | 机器人 ID（大整数字符串，作 list_robot_sessions 入参） |
data[].name | string | 机器人名称（用于按名匹配） |
list_robot_sessions — 大模型机器人会话记录拉取
起止时间未给先追问。 权限位：[797] AI查询机器人全部会话记录（AI-robot-session-read）
⚠️ 通路默认全量规则：用户说"拉机器人会话 / 看机器人聊了什么 / 这个客户问机器人什么"等未明确说通路时，不要传 Cid 类型 等通路过滤参数，让接口返回所有通路的机器人会话。返回后按通路分组展示。用户明确指定通路时再严格按指定的 type 传入。
入参
| 参数 | 类型 | 必填 | 说明 |
|---|
| robotId | string | 是 | 机器人 ID（大整数，字符串传递） |
| startTime | string | 否 | 开始时间 |
| endTime | string | 否 | 结束时间 |
| page | integer | 否 | 页码 |
| pageSize | integer | 否 | 每页条数 |
| Cid 类型 | integer | 否 | 通路类型（用户未指定时不传，默认拉全部通路） |
返回值（关键字段）
| 字段 | 类型 | 说明 |
|---|
data[].SessionID | string | 会话 ID（大整数字符串，作 get_robot_messages 入参） |
data[].RobotID | string | 机器人 ID |
data[].startTime / data[].endTime | string | 起止时间 |
total | integer | 总条数 |
get_robot_messages — 大模型机器人消息记录拉取
按会话 ID 取机器人会话的问答对。权限位：[797] AI查询机器人全部会话记录（AI-robot-session-read）
入参
| 参数 | 类型 | 必填 | 说明 |
|---|
| robotId | string | 是 | 机器人 ID（大整数，字符串传递） |
| sessionIds | string[] | 是 | 会话 ID 列表（来自 list_robot_sessions；每个 ID 均为大整数字符串） |
返回值（关键字段）
| 字段 | 类型 | 说明 |
|---|
data[].sessionId | string | 会话 ID |
data[].messages[].question | string | 用户提问 |
data[].messages[].answer | string | 机器人回答 |
data[].messages[].timestamp | string | 时间戳 |
数据报表（端点已更新，参数以最新文档为准）
下列 4 个接口均为"会话客服分析"系列，起止时间为通用必填项；其余字段按各自文档地址核对。起止时间未给先追问。 返回值通常含 data.metrics（核心指标对象）+ data.list[]（按坐席/天/会话维度的明细），AI 解析时按用户问的维度展示即可。
get_quality_report — 满意度分析
权限位：[798] AI查询全部客服报表（report-read）
入参
| 参数 | 类型 | 必填 | 说明 |
|---|
| startDate | string | 是 | YYYY-MM-DD |
| endDate | string | 是 | YYYY-MM-DD |
get_service_report — 总览（客服维度）
权限位：[798] AI查询全部客服报表（report-read）（参数同上）
get_staff_duration — 时长分析
权限位：[798] AI查询全部客服报表（report-read）（参数同上）
get_staff_funnel — 响应度分析
权限位：[798] AI查询全部客服报表（report-read）（参数同上）。名字保留为 get_staff_funnel，当前对应响应度分析，已不是"客户转化漏斗"。
常见调用链路（每个域至少一条示例）
【工单管理】创建工单
用户："帮我建个工单，VIP 模版，处理人是张三"
- 解析处理人 openId：先
list_all_staff + get_staff_info 按姓名匹配；匹配慢/不准 → 引导用户给 account → get_staff_openid 一步到位。
list_templates 搜 "VIP" 取 templateId（保持字符串原值不动）及必填字段。- 按《工单写操作二次确认规则》逐项展示参数，请用户明确确认或调整——即便用户上文已说过模板/处理人，也必须再问一次"用这些参数对吗？"。
- 用户确认后调
create_ticket（所有大整数 ID 字段保持字符串透传）。
【工单管理】改状态 / 改处理人
- "把这个工单改为处理中" →
list_statuses 取目标 statusId → 按二次确认规则确认 workorderId + statusId 后调 assign_ticket。
- "把这个工单分给张三" → 解析张三 openId → 按二次确认规则确认 workorderId + 新 ownerId 后调
update_ticket。
【坐席查询】客服在线状态 / 谁在线 / 现在客服情况怎么样
用户任意一种表达：「客服在线情况」「现在谁在线」「有几个客服在岗」「客服在忙吗」
- 直接调
get_staff_monitor（坐席级实时监控），无需追问"你想看什么"——本接口已含在线/忙碌/接待数据。
- 如果用户的问题里还涉及"排队 / 在线会话总数 / 客户等待"，再补调
get_message_alerts 取全局大盘。
- 汇总返回，重点字段：
staffOnlineCount（在线坐席数）/staffBusyCount（忙碌）/staffList[]（各坐席详情）。
⚠️ 反例（禁止）：看到"客服在线状态"就追问"你是想查在线员工列表，还是接待情况？" —— 用户语义就是要看接待端的实时状态，直接 get_staff_monitor 比追问更专业。
【客户查询】用户给社交账号或客户 ID
- 用户给 cust_id（明确说"客户 ID 是 xxx"）→ 直接
get_user。
- 用户给 微信/手机号/企微 ID 等社交账号 →
search_user（按通路选 type）→ get_user。
- 用户给 纯数字串（5-12 位）查客户 → 拦截，按《QQ 号查客户的强制规则》话术引导用户提供 cust_id 或手机号，不要调
search_user type=0。
- 用户给客户姓名 →
list_customers 翻页匹配；客户库大时超时立即停止，引导用户去客户库复制 cust_id。
【人工会话与消息记录】分析某段时间会话
用户："帮我看下昨天某个客户的聊天记录"
- 起止时间不明先追问（"昨天"换算成具体日期再确认）。
- 解析客户：给社交账号 →
search_user；给姓名 → 按《cust_id 解析》，必要时引导提供 cust_id。
- 通路默认全量：用户没说"通过 QQ / 微信 / 企微"等具体通路时，调
get_monitored_sessions 时不传 subType，让接口返回所有通路的会话。
get_monitored_sessions（带 startDate/endDate + socialAccount 或 staffId 过滤）拉会话列表。大批量前先报规模并确认。- 对感兴趣的
sessionId 调 get_staff_messages 拉逐条聊天，AI 分析。
- 汇总时按通路分组展示，让用户看清各通路的会话分布。
【大模型机器人记录】看机器人最近对话
用户："看看那个机器人这周聊了什么"
- 起止时间不明先追问（"这周"换算成具体起止日期再确认）。
- 解析 robotId：用户直接给 robotId 则用；用户给的是机器人名称（如"机器人演示-Ann"）→ 调
list_robots 按名称匹配拿 robotId（保持字符串原值）。
- 通路默认全量：用户没说"通过 QQ / 微信公众号 / 企微"等具体通路时，调
list_robot_sessions 时**不传 Cid 类型**等通路过滤参数，让接口返回所有通路的机器人会话。
list_robot_sessions（robotId + startTime + endTime）拉会话列表，分页全翻。- 对感兴趣的 sessionIds 调
get_robot_messages 拉问答对，AI 分析。
- 汇总时按通路分组展示。
【客服数据报表】生成运营日报
用户："出一份今天的运营日报"
- 确认"今天"的具体起止时间。
get_message_alerts 取实时大盘。get_quality_report 满意度、get_service_report 客服总览、get_staff_duration 时长、get_staff_funnel 响应度。get_staff_monitor 取坐席在线与实时接待数据。- AI 汇总成报告。
【会话分析 + 批量建单】综合示例
用户："拉最近 30 天会话，有购买意向的客户每个建一个工单"
- 起止时间未给先确认；解析处理人 openId。
get_monitored_sessions 分页拉取（每页最多 50；先报"预计 N 页"取得用户同意）。- AI 分析 convRemarks + customerTag 识别购买意图。
list_templates 取模板。- 按《工单写操作二次确认规则》先告知"预计创建 N 张工单"并展示第一张完整参数（templateId/ownerId/title 等），取得整体同意，再循环
create_ticket；批次内任一条参数与样本不一致都要重新确认。
注意事项速查
这一节是上面所有规则的精简提取，便于 AI 在执行中快速核对。详细规则见各对应章节。
- 认证：Token 过期信号（401 /
errcode=40001）→ 不重试，按《认证》话术引导重新授权。
- 权限：权限错误（403）→ 按映射表填写缺失权限位名称，按话术回复。其他错误见《常见错误码速查表》。
- 员工 openId：我自己 → MCP Server；具名姓名 →
list_all_staff + get_staff_info 匹配；匹配慢/失败 → 引导提供 account → get_staff_openid。
- ⚠️ openId → 姓名展示规范：所有展示给用户的处理人/坐席/操作者字段，禁止裸输出 openId——必须批量调
get_staff_info 解析为姓名，按 openid（姓名） 或 姓名（openid） 格式展示；同一轮对话内的映射可缓存复用；员工不存在时显示 openid（未找到员工）。
- 客户 cust_id：手机/微信等社交账号 →
search_user（type≠0）；姓名 → list_customers + get_user；超时或报错时引导用户去客户库复制 cust_id。
- ⛔ 裸 QQ 号查客户禁用：5-12 位纯数字 + 上下文是"查客户"时，直接拦截，按《QQ 号查客户的强制规则》话术引导用户提供 cust_id 或手机号，不要调 search_user type=0。
- operator：所有接口的
operator 由 MCP Server 注入，不必手工填。
- 大整数 ID 全 string：
templateId / workorderId / customerId / statusId / robotId / sessionId / ref_time 等，参数与返回值一律字符串透传，不做任何数值转换。
- 写操作二次确认：工单 create/update/assign 前即便参数齐全也必须逐项让用户确认或更换，不得直接执行；批量场景按批次确认。
- assign_ticket 是改状态；改处理人请用
update_ticket 的 ownerId。
- 客服在线状态 =
get_staff_monitor：用户问"谁在线 / 客服在线情况 / 现在客服情况怎么样"等，直接调本接口，无需追问；含排队/在线会话再补 get_message_alerts。
- 两类"监控"消歧：
get_message_alerts 全局大盘 / get_staff_monitor 坐席级实时（含在线/忙碌坐席数）/ 报表族（798）历史统计。
get_staff_funnel 现为响应度分析，已不是漏斗/转化。- ⚠️ 计数必须程序化：任何"共 N 条 / 一共 N 个"的输出，优先取接口返回的 total 字段；没有 total 时用 Bash/Python
len() 算，禁止靠肉眼数。"开头说 N 条 + 下面列 M 条"两数对不上时立刻停止重算。用户反馈数错时先承认再程序化重算。
- ⚠️ 分页完整性必检：用户问"全部 / 所有 / 在线情况 / 筛选某条件"时，必须翻完所有页才能下结论——已知事故：
get_staff_monitor 默认 count=48，企业 68 个坐席分两页时只看第一页会漏掉第二页的 polite 等在线坐席。第一页拉完后立刻看 ，若 必须续翻，并先告知用户预计页数取得同意；汇报结果时必须声明数据范围（"已拉取全部 N 个坐席，共 M 页" vs "当前只看了第一页"）。
