tencent-qidian-cs-skill

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 返回的错误码处理：

• 完全无权限（未勾选任何 AI 连接器权限位）：返回对应错误码时，回复——

  查询到权限不足，请联系管理员到企点客服账户中心（https://admin.qidian.qq.com/）中【企业管理】-【权限角色】-【AI连接器】模块中添加权限。（仅在线客服专业版、企业版套餐的企业可使用）

• 部分权限（已开通某些权限位，但用户的需求落在未开通的位上）：回复——

  检测到缺少 {缺失权限位名称} 权限，无法执行最终操作。请联系管理员到企点客服账户中心（https://admin.qidian.qq.com/）中【企业管理】-【权限角色】-【AI连接器】模块中添加权限。（仅在线客服专业版、企业版套餐的企业可使用）

  {缺失权限位名称} 替换为下方映射表中对应的名称。

• 其他错误：见《常见错误码速查表》。不要编造结果或绕过——伪造数据会让用户基于错误信息做决策。

⚠️ 数据范围（务必知悉）

当前所有接口覆盖企业全体员工数据，与登录账号无关：可以拉到所有员工的工单、所有坐席的会话。因此：

• 默认查询返回全公司数据；用户想看"我的 / 某人的"，要用 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（姓名） 格式输出。

强制流程：

1. 批量收集：扫描即将展示给用户的数据，收集所有 openId 值（去重），统一传入 get_staff_info 的 openids 数组一次性查询，避免 N+1 调用。
2. 构建映射表：从返回值中得到 {openid → name} 的映射缓存（同一轮对话内可复用，下次再遇到相同 openId 直接查映射表，不重复调）。
3. 格式化展示：在所有用户可见的输出中，把 openId 字段渲染为 ouxxxxxx（张三） 的形式。
   • 表格中：单独一列展示，或合并为"处理人"列内显示 张三（ouxxxxxx） 也可。
   • 自然语言：『工单 W-001 当前的处理人是 张三（openId: ouxxxxxx）』。
4. 解析失败兜底：get_staff_info 返回为空（员工已离职/不存在）时，按 ouxxxxxx（未找到员工） 显示，不要让 openId 裸奔。
5. 本人识别：如果 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：当下时间 = 系统当下，不能凭记忆/训练数据

• 任何涉及"今天 / 现在 / 最近 X 天 / 本周 / 本月"的计算，第一步必须用 Bash 取真实当前时间：

  date "+%Y-%m-%d %H:%M:%S %Z"        # 人类可读
  date +%s                              # 秒级时间戳
  date +%s%6N                           # 微秒级时间戳（用于 ref_time 等）
  

• 禁止根据训练截止日期、对话上下文推断"今天是 X 月 X 日"。模型的内部时间认知通常滞后真实时间数月到数年，这是已知的事故源头。

规则 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

• 写入参数前必须用 Bash 重新算一次对应单位的时间戳，不要直接 ×1000 / ÷1000 拍脑袋。例如：

  date -j -f "%Y-%m-%d %H:%M:%S" "2026-04-28 00:00:00" +%s    # macOS BSD date
  # 输出 1777593600（秒）→ 毫秒需要 ×1000 = 1777593600000
  

规则 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：拉完所有页的标准流程

1. 第一页拉取：调接口拿到第一页数据 + 总数（total / count / maxLimitTotal）。
2. 判断是否还有下一页：
   • 若 已拉条数 < total → 继续拉下一页（自增 index 或 page）
   • 若 data.next_page_token / next_custid 非空 → 用游标拉下一页
   • 若用户明确说"够了 / 别拉太多"→ 停止并告知已拉条数 / 总数比例
3. 告知翻页规模：若 total 较大（≥ 3 页或 ≥ 200 条），先停下来告诉用户：『总共 N 页 / N 条，预计要拉完才能给你完整答案，确认继续吗？』取得同意再翻。
4. 数据合并：所有页数据合并到一个数组，用 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 张"的输出必须满足以下任一条件：

1. 优先取接口返回的 total / count / maxLimitTotal 字段——这是服务端给出的权威计数，比模型自己数准。
2. 若返回结构没有 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']))"
   

3. 数组很短（≤ 5 条）且需要逐条展示时，先编号列出每一项，再以列表的最后一个编号作为总数（如 "12 项 → 编号 1 至 12 → 总数 12"）。

规则 B：列表数 ≠ 概括数 时，立即停止并重算

输出格式如果同时包含两个数字（例如开头说"共 N 条"，下面又详细列了 M 条），N 必须等于 M。出现差值时：

1. 立即停止当前回复，不要硬着头皮往下写。
2. 用规则 A 的方式重新核对总数。
3. 修正后再发给用户。

规则 C：用户反馈"数错了"时，先承认再程序化重算

如果用户指出"你说 N 个但列了 M 个"：

1. 直接承认："你说得对，确实数错了。"——不要找借口。
2. 走规则 A 重新数（优先 total，其次 Bash 计算），不要再用眼睛数第二次。
3. 给出经程序化验证的最终数字。

规则 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）

action	说明	文档地址
list_templates	获取工单模板列表	https://api.qidian.qq.com/wiki/doc/open/eynb5ft8gnsrqv17u05h
list_tickets	工单列表查询（条件筛选）	https://api.qidian.qq.com/wiki/doc/open/esa3sklsvw0csvdlo2em
get_ticket	工单详情查看	https://api.qidian.qq.com/wiki/doc/open/ecse8s4sk4n28q0f1mhk
list_statuses	获取工单状态列表	https://api.qidian.qq.com/wiki/doc/open/eqod2tep8hlipt5pk14v

[791] AI新建工单（ticket-create）

action	说明	文档地址
create_ticket	创建工单	https://api.qidian.qq.com/wiki/doc/open/etczss4dko6p9xfs5g43

[792] AI更新全部工单（ticket-update）

action	说明	文档地址
update_ticket	工单信息更新（改处理人 ownerId 用这个）	https://api.qidian.qq.com/wiki/doc/open/e1ssbs7ou39981cmud5f
assign_ticket	工单状态变更（名字虽是 assign，实为改状态）	https://api.qidian.qq.com/wiki/doc/open/e5bms5rryls1e37frhk1

坐席管理

[793] AI查询全部坐席（agent-read）

action	说明	文档地址
list_all_staff	批量拉取员工列表（仅返回 openId，要姓名需配合 get_staff_info）	https://api.qidian.qq.com/wiki/doc/open/enq3asm58qd30e5thznk
get_staff_info	根据 openId 获取员工信息（含姓名）	https://api.qidian.qq.com/wiki/doc/open/emc2lsrxlpeyogp46h43
get_staff_openid	根据 account（组织架构里的英文工号）批量获取 openId	https://api.qidian.qq.com/wiki/doc/open/e1lvod8ftkgs44hupuu3
get_staff_monitor	客服实时监控数据（坐席级）	https://api.qidian.qq.com/wiki/doc/open/em7p5kar7co0f5htpr45

客户管理

[794] AI查询全部客户（customer-read）

action	说明	文档地址
get_user	客户资料查询（按 cust_id）	https://api.qidian.qq.com/wiki/doc/open/ebmlne6s3lpzplguht26
search_user	根据社交账号反查 cust_id	https://api.qidian.qq.com/wiki/doc/open/eal6s336lsl1czg5h569
list_customers	拉取客户列表（游标分页；客户多时慎用）	https://api.qidian.qq.com/wiki/doc/open/evblxstplyo4dpgm4ri6

会话记录

[795] AI查询全部人工会话记录（session-read）

action	说明	文档地址
get_monitored_sessions	人工接待会话记录拉取	https://api.qidian.qq.com/wiki/doc/open/etlka4esonlgrv374h05
get_staff_messages	人工接待消息记录拉取（逐条聊天）	https://api.qidian.qq.com/wiki/doc/open/ed5e6foshrq8ol7k2ws4

[796] AI查询全部客服会话监控（monitor-read）

action	说明	文档地址
get_message_alerts	会话监控实时大盘（排队数、在线会话数、满意度等全局指标）	https://api.qidian.qq.com/wiki/doc/open/eamp842brgr7ni45n5s8

大模型机器人

[797] AI查询机器人全部会话记录（AI-robot-session-read）

action	说明	文档地址
list_robot_sessions	大模型机器人会话记录拉取	https://api.qidian.qq.com/wiki/doc/open/flrka0xclflks9g9kiu8
get_robot_messages	大模型机器人消息记录拉取（问答对）	https://api.qidian.qq.com/wiki/doc/open/esarx13br5fnv2o0h103
list_robots	大模型机器人列表查询（先调它拿 robotId，再 list_robot_sessions 拉会话）	https://api.qidian.qq.com/wiki/doc/open/flk9laym9sbro1qdqfxi

数据报表（已整体迁到 employeeSession 族）

[798] AI查询全部客服报表（report-read）

action	说明	文档地址
get_quality_report	会话客服分析-满意度分析	https://api.qidian.qq.com/wiki/doc/open/e7btspmcwpxr9rd6ez5t
get_service_report	会话客服分析-总览（客服维度）	https://api.qidian.qq.com/wiki/doc/open/evtnbs5pnd007fylwg60
get_staff_duration	会话客服分析-时长分析	https://api.qidian.qq.com/wiki/doc/open/ezdlretsppwfplqix9m9
get_staff_funnel	会话客服分析-响应度分析（名字保留，含义已不是漏斗/转化）	https://api.qidian.qq.com/wiki/doc/open/eutbsc7lp6lf04k2h2ym

权限位速查表

后台权限位中文名已统一为「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 等参数。

必须遵守的流程：

1. 完整展示即将提交的参数——按"字段名：值（含可读名称）"逐项列出，例如：
   • 模板：templateId="614404267440304175"（VIP 客户工单专用模板）
   • 标题：xxx
   • 处理人：ownerId="ouxxxxxx"（张三）
   • 优先级：30（中）
2. 逐项询问是否使用 / 是否要替换——尤其是 templateId、ownerId、statusId 这类引用其他对象的 ID 字段，明确问："要用这个模板 / 处理人 / 状态吗？还是换一个？"
3. 等待用户明确肯定回复（"确认"、"是"、"OK"、"对"、"就这样"等）后再执行；用户犹豫、提出疑问或表达否定时，立即停止，按用户的最新意见调整后再次走确认流程。
4. 不得用"看起来都有了就直接提交"的判断越过确认——即使所有必填项都已具备，也必须确认。
5. 批量场景（如循环建单）必须先报"预计创建 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 时必然分多页。用户问"全部坐席 / 哪些客服在线 / 在线情况"等"全集筛选类"问题时，必须翻完所有页才能下结论：

1. 第一页（index=1）拉完后，先看返回的 total 字段——若企业有 N 个坐席而 N > 48，则需要翻 ⌈N / count⌉ 页。
2. 续翻页：index=2, count=48 拉第二页；如有更多页继续递增 index。
3. 所有页数据用 Bash/Python 程序化合并（不要靠 LLM 拼接），再做"在线状态 = 1"等筛选。
4. 汇报结果时必须声明数据范围：『已拉取全部 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 模版，处理人是张三"

1. 解析处理人 openId：先 list_all_staff + get_staff_info 按姓名匹配；匹配慢/不准 → 引导用户给 account → get_staff_openid 一步到位。
2. list_templates 搜 "VIP" 取 templateId（保持字符串原值不动）及必填字段。
3. 按《工单写操作二次确认规则》逐项展示参数，请用户明确确认或调整——即便用户上文已说过模板/处理人，也必须再问一次"用这些参数对吗？"。
4. 用户确认后调 create_ticket（所有大整数 ID 字段保持字符串透传）。

【工单管理】改状态 / 改处理人

• "把这个工单改为处理中" → list_statuses 取目标 statusId → 按二次确认规则确认 workorderId + statusId 后调 assign_ticket。
• "把这个工单分给张三" → 解析张三 openId → 按二次确认规则确认 workorderId + 新 ownerId 后调 update_ticket。

【坐席查询】客服在线状态 / 谁在线 / 现在客服情况怎么样

用户任意一种表达：「客服在线情况」「现在谁在线」「有几个客服在岗」「客服在忙吗」

1. 直接调 get_staff_monitor（坐席级实时监控），无需追问"你想看什么"——本接口已含在线/忙碌/接待数据。
2. 如果用户的问题里还涉及"排队 / 在线会话总数 / 客户等待"，再补调 get_message_alerts 取全局大盘。
3. 汇总返回，重点字段：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。

【人工会话与消息记录】分析某段时间会话

用户："帮我看下昨天某个客户的聊天记录"

1. 起止时间不明先追问（"昨天"换算成具体日期再确认）。
2. 解析客户：给社交账号 → search_user；给姓名 → 按《cust_id 解析》，必要时引导提供 cust_id。
3. 通路默认全量：用户没说"通过 QQ / 微信 / 企微"等具体通路时，调 get_monitored_sessions 时不传 subType，让接口返回所有通路的会话。
4. get_monitored_sessions（带 startDate/endDate + socialAccount 或 staffId 过滤）拉会话列表。大批量前先报规模并确认。
5. 对感兴趣的 sessionId 调 get_staff_messages 拉逐条聊天，AI 分析。
6. 汇总时按通路分组展示，让用户看清各通路的会话分布。

【大模型机器人记录】看机器人最近对话

用户："看看那个机器人这周聊了什么"

1. 起止时间不明先追问（"这周"换算成具体起止日期再确认）。
2. 解析 robotId：用户直接给 robotId 则用；用户给的是机器人名称（如"机器人演示-Ann"）→ 调 list_robots 按名称匹配拿 robotId（保持字符串原值）。
3. 通路默认全量：用户没说"通过 QQ / 微信公众号 / 企微"等具体通路时，调 list_robot_sessions 时**不传 Cid 类型**等通路过滤参数，让接口返回所有通路的机器人会话。
4. list_robot_sessions（robotId + startTime + endTime）拉会话列表，分页全翻。
5. 对感兴趣的 sessionIds 调 get_robot_messages 拉问答对，AI 分析。
6. 汇总时按通路分组展示。

【客服数据报表】生成运营日报

用户："出一份今天的运营日报"

1. 确认"今天"的具体起止时间。
2. get_message_alerts 取实时大盘。
3. get_quality_report 满意度、get_service_report 客服总览、get_staff_duration 时长、get_staff_funnel 响应度。
4. get_staff_monitor 取坐席在线与实时接待数据。
5. AI 汇总成报告。

【会话分析 + 批量建单】综合示例

用户："拉最近 30 天会话，有购买意向的客户每个建一个工单"

1. 起止时间未给先确认；解析处理人 openId。
2. get_monitored_sessions 分页拉取（每页最多 50；先报"预计 N 页"取得用户同意）。
3. AI 分析 convRemarks + customerTag 识别购买意图。
4. list_templates 取模板。
5. 按《工单写操作二次确认规则》先告知"预计创建 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 "当前只看了第一页"）。