AndonQ

腾讯云 AndonQ 工单与智能客服助手 — 不切窗口、不排队，即刻获得腾讯云全产品线专业解答。支持工单查询（列表/详情/流水）、集团工单与需求单管理，以及腾讯云全产品线智能问答。当用户查询工单、查看工单详情、咨询腾讯云产品问题（如 CVM、轻量应用服务器、COS 等）、查询集团工单/需求单，或要求找人工客服时使用。

☁️ AndonQ — 腾讯云工单与智能客服助手

核心能力：工单查询（列表查询、详情查询，TC3-HMAC-SHA256 签名鉴权）+ 智能客服多轮问答（SSE 流式响应，免鉴权）。工单模块与智能客服完全独立，统一输出格式。

---

一、鉴权方式

1.1 工单查询（GetMCTicketList / GetMCTicketById）

使用腾讯云 API AK/SK 签名认证（TC3-HMAC-SHA256），通过环境变量配置密钥：

• TENCENTCLOUD_SECRET_ID — 腾讯云 SecretId（必填）
• TENCENTCLOUD_SECRET_KEY — 腾讯云 SecretKey（必填）

密钥获取地址：https://console.cloud.tencent.com/cam/capi

凭据权限要求：请使用最小权限、可随时吊销的子账号密钥，不要使用主账号密钥。 本 Skill 只需要工单相关的读取权限。

推荐方式 — 会话级注入（不落盘）

优先从密钥管理器读取，仅注入当前会话，命令结束即失效：

bash

# macOS 钥匙串示例
export TENCENTCLOUD_SECRET_ID="$(security find-generic-password -s tencentcloud-secret-id -w)"
export TENCENTCLOUD_SECRET_KEY="$(security find-generic-password -s tencentcloud-secret-key -w)"

其他可用方案：pass、1Password CLI（op read）、HashiCorp Vault、企业密钥管理服务。

备选方式 — 写入 shell 配置文件（有风险，请知悉后再用）

若确实需要跨会话持久化，可写入 ~/.zshrc / ~/.bashrc：

bash

echo 'export TENCENTCLOUD_SECRET_ID="your-secret-id"' >> ~/.zshrc
echo 'export TENCENTCLOUD_SECRET_KEY="your-secret-key"' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell（写入用户级环境变量）：

powershell

[Environment]::SetEnvironmentVariable("TENCENTCLOUD_SECRET_ID", "your-secret-id", "User")
[Environment]::SetEnvironmentVariable("TENCENTCLOUD_SECRET_KEY", "your-secret-key", "User")

⚠️ 持久化的代价：这样做会把长期有效的明文密钥留在磁盘上。该文件会被备份、 被同步工具上传、被其他本地进程读取，且泄露后不会有任何提示。 选择此方式时请确保密钥为最小权限子账号密钥，并定期轮换。

Agent 不应主动替用户执行写入操作，应说明两种方式的差异，由用户自行选择。

1.2 智能问答（SmartQA）

无需 AK/SK，uin 和 skey 默认为空。直接调用即可。

⚠️ 数据出境提示：SmartQA 会把你输入的问题以及多轮对话的上下文发送到 腾讯云在线客服服务（cloud.tencent.com / andon.cloud.tencent.com）进行处理。 这些内容离开本地环境，且可能被服务端留存用于客服记录。

请不要在提问中包含密钥、内部主机名、客户数据或其他敏感信息。 首次为用户调用 SmartQA 时，应主动告知这一点。

---

二、前置检查

运行需要 AK/SK 的接口前，必须先确保环境变量已生效。如果是新会话或环境变量刚写入配置文件，先执行：

bash

source ~/.zshrc   # macOS / zsh 用户
# 或
source ~/.bashrc  # Linux / bash 用户

然后运行环境检测：

bash

python3 {baseDir}/check_env.py

支持参数：

• --quiet — 静默模式，仅输出错误信息
• --skip-update — 跳过版本更新检查

返回码含义：

• 0 = 环境就绪（密钥配置正常）
• 1 = Python 版本不满足要求（需 3.7+）
• 2 = AK/SK 未配置或无效
• 4 = Skill 版本过旧，需要更新

智能问答（SmartQA）无需前置检查，可直接使用。

---

三、可用接口（共 9 个）

3.0 GetCurrentTime — 获取当前时间

返回当前时间和常用时间范围预设（最近 7/30/90/365 天），用于构造查询参数。无需鉴权，本地执行。

• 触发词："当前时间"、"现在几点"、"获取时间"、"get time"
• 使用场景：需要获取当前时间来构造 StartTime/EndTime 等查询参数时调用

bash

python3 {baseDir}/scripts/andon-api.py -a GetCurrentTime -d '{}'

返回示例：

json

{
  "success": true,
  "action": "GetCurrentTime",
  "data": {
    "now": "2026-03-24 18:30:00",
    "today": "2026-03-24",
    "timestamp": 1742816600,
    "presets": {
      "last_7d": {"startTime": "2026-03-17 18:30:00", "endTime": "2026-03-24 18:30:00"},
      "last_30d": {"startTime": "2026-02-22 18:30:00", "endTime": "2026-03-24 18:30:00"},
      "last_90d": {"startTime": "2025-12-24 18:30:00", "endTime": "2026-03-24 18:30:00"},
      "last_180d": {"startTime": "2025-09-26 18:30:00", "endTime": "2026-03-24 18:30:00"},
      "last_365d": {"startTime": "2025-03-24 18:30:00", "endTime": "2026-03-24 18:30:00"}
    }
  },
  "requestId": ""
}

3.1 GetMCTicketList — 查询工单列表

查询当前账户下的工单列表，默认按创建时间倒序返回。

• 触发词：“查询工单”、“工单列表”、“我的工单”、“看看工单”、“有哪些工单”、“list tickets”、“my tickets”
• 详细文档：使用前加载 {baseDir}/references/GetMCTicketList.md

数据范围：默认只返回当前账号自己的工单。 加上 --include-organization 才会同时查询 DescribeOrganizationTickets 并按 TicketId 去重合并，此时返回结果会扩大到集团范围的工单， 可能包含其他成员的工单标题、UIN 与问题描述。

Agent 不应默认加这个参数。只有当用户明确要求查看集团/成员工单时才使用， 并在返回前说明数据范围已扩大。合并模式下任一来源失败会被静默忽略， 因此结果可能不完整。

bash

# 默认查询（最新 20 条，仅本账号工单）
python3 {baseDir}/scripts/andon-api.py -a GetMCTicketList -d '{}'

# 按状态过滤（待处理 + 处理中）
python3 {baseDir}/scripts/andon-api.py -a GetMCTicketList -d '{"StatusIdList":[0,1]}'

# 关键词搜索
python3 {baseDir}/scripts/andon-api.py -a GetMCTicketList -d '{"Search":"CVM","PageSize":10}'

# 显式扩大到集团范围（需用户明确要求）
python3 {baseDir}/scripts/andon-api.py -a GetMCTicketList -d '{}' --include-organization

返回示例：

json

{
  "success": true,
  "action": "GetMCTicketList",
  "data": {
    "tickets": [{"TicketId": "202603244502", "Question": "CVM 无法登录", "StatusId": 1}],
    "total": 15
  },
  "requestId": "xxx"
}

3.2 GetMCTicketById — 查询工单详情

根据工单 ID 查询详情，包含沟通记录（Comments）。必填参数：TicketId。

• 触发词：“工单详情”、“查看工单”、“工单进展”、“工单状态”、“这个工单怎么样了”、“ticket detail”、“check ticket”
• 详细文档：使用前加载 {baseDir}/references/GetMCTicketById.md

bash

python3 {baseDir}/scripts/andon-api.py -a GetMCTicketById -d '{"TicketId":"202603244502"}'

返回示例：

json

{
  "success": true,
  "action": "GetMCTicketById",
  "data": {
    "TicketId": "202603244502",
    "Question": "CVM 无法登录",
    "StatusId": 1,
    "Comments": [{"Content": "您好，请检查安全组配置", "Role": "support"}]
  },
  "requestId": "xxx"
}

3.3 SmartQA — 智能客服问答

调用腾讯云 Andon 智能客服进行产品咨询，支持多轮对话。无需鉴权。

• 触发词："腾讯云工单"、"腾讯云客服"、"腾讯云智能客服"、"问下客服"、"咨询腾讯云"、"腾讯云怎么..."、"腾讯云如何..."、"CVM怎么..."、"轻量应用服务器..."、"对象存储..."
• 详细文档：使用前加载 {baseDir}/references/SmartQA.md

单轮问答：

bash

python3 {baseDir}/scripts/smartqa-api.py -q "轻量应用服务器如何登录"

多轮对话（复用 sessionId 和 agentSessionId）：

bash

# 第一轮
python3 {baseDir}/scripts/smartqa-api.py -q "对象存储COS如何设置跨域访问"
# 返回 sessionId 和 agentSessionId 后，追问
python3 {baseDir}/scripts/smartqa-api.py -q "如果我用的是Python SDK呢" \
  --session-id QT1HHP284PW9 --agent-session-id 1002079011

返回示例：

json

{
  "success": true,
  "action": "SmartQA",
  "data": {
    "answer": "腾讯云服务器（CVM）支持通过控制台和API两种方式重启实例...",
    "intention": "profession",
    "recommendQuestions": ["云服务器如何重启", "轻量应用服务器如何重启实例"],
    "sessionId": "JL7JX8C51GAS",
    "agentSessionId": "1002078124"
  }
}

3.4 DescribeOrganizationTickets — 集团成员工单列表

查询集团成员的工单列表，支持按时间范围、分页等过滤。

• 触发词："集团工单"、"成员工单"、"organization tickets"
• 详细文档：使用前加载 {baseDir}/references/DescribeOrganizationTickets.md

bash

python3 {baseDir}/scripts/andon-api.py -a DescribeOrganizationTickets -d '{"StartTime":"<last_180d.startTime>","EndTime":"<last_180d.endTime>","Offset":0,"Limit":10}'

3.5 DescribeTicket — 查看工单详情（集团）

根据工单 ID 查询集团工单详情。自动注入 Region=ap-guangzhou。

• 触发词："查看集团工单"、"工单详情"、"describe ticket"
• 详细文档：使用前加载 {baseDir}/references/DescribeTicket.md

bash

python3 {baseDir}/scripts/andon-api.py -a DescribeTicket -d '{"TicketId":"11046458"}'

3.6 DescribeTicketOperation — 查询工单流水

查询工单的操作流水记录。注意 TicketId 是 Integer 类型；自动注入 Region=ap-guangzhou。

• 触发词："工单流水"、"操作记录"、"ticket operation"
• 详细文档：使用前加载 {baseDir}/references/DescribeTicketOperation.md

bash

python3 {baseDir}/scripts/andon-api.py -a DescribeTicketOperation -d '{"TicketId":7334156,"Offset":0,"Limit":10}'

3.7 DescribeOrganizationStories — 集团成员需求单列表

查询集团成员的需求单列表，支持按时间范围、分页等过滤。

• 触发词："需求单列表"、"集团需求单"、"organization stories"
• 详细文档：使用前加载 {baseDir}/references/DescribeOrganizationStories.md

bash

python3 {baseDir}/scripts/andon-api.py -a DescribeOrganizationStories -d '{"StartTime":"<last_180d.startTime>","EndTime":"<last_180d.endTime>","Offset":0,"Limit":10}'

3.8 DescribeOrganizationStory — 需求单详情

根据需求单 ID 查询详情，包含评论列表。

• 触发词："需求单详情"、"查看需求单"、"story detail"
• 详细文档：使用前加载 {baseDir}/references/DescribeOrganizationStory.md

bash

python3 {baseDir}/scripts/andon-api.py -a DescribeOrganizationStory -d '{"StoryId":1010239}'

---

四、统一输出格式

所有接口输出为统一 JSON 格式，通过 success 字段区分成功与失败。

成功响应

json

{
  "success": true,
  "action": "GetMCTicketList / GetMCTicketById / SmartQA",
  "data": { ... },
  "requestId": "xxx"
}

失败响应

json

{
  "success": false,
  "action": "...",
  "error": {
    "code": "错误码",
    "message": "错误描述"
  }
}

脚本层面错误码

错误码	含义	解决方案
InvalidParameterValue	参数校验失败	检查输入格式
MissingCredentials	未配置 AK/SK 环境变量	配置密钥
NetworkError	网络超时或连接失败	检查网络，重试
SessionCreateFailed	SmartQA 会话创建失败	可能是暂时性问题，重试
EmptyResponse	SSE 流中无回答内容	问题格式不支持
HttpError	HTTP 状态码非 200	检查 API 状态
ParseError	响应不是有效 JSON	检查网络环境

常见 API 错误码（工单操作）

错误码	含义	解决方案
AuthFailure	AK/SK 不正确或已过期	检查密钥配置
ResourceNotFound	工单 ID 不存在	检查 TicketId 是否正确
InternalError	腾讯云内部错误	重试或联系支持
RequestLimitExceeded	请求频率超限	降低调用频率

---

五、展示规则

5.1 智能问答成功

• answer 字段可能包含 Markdown（标题、列表、代码块、图片链接），原样传递展示
• 若 recommendQuestions 非空，展示为编号列表供用户追问
• 若 smartTool 字段存在，表示返回的是产品操作组件引用（如 SDK 面板），非自然语言回答
• 若 partial: true，提示："回答可能不完整（流被中断）"
• intention 字段说明意图类型：profession = 产品知识问答，hanxuan = 寒暄/闲聊

5.2 工单列表

以表格形式展示，包含工单 ID、问题描述、状态、创建时间。状态显示中文名：

StatusId	状态
0	待处理
1	处理中
2	待确认
3	已完成
4	已关闭
5	已取消
6	重新打开
7	待补充

• toBeAddCount > 0 时提示用户有工单需要补充信息
• toConfirmCount > 0 时提示用户有工单待确认
• 底部显示总数和当前页码

5.3 工单详情

分段展示：基本信息（状态、产品、时间）+ 问题描述 + 沟通记录。

• Comments 按时间顺序展示，标注角色（客服/用户）
• 若 StatusId == 7（待补充），提醒用户需要补充信息
• 若有附件（ReturnCosUrl=true），展示为可点击链接

5.4 多轮对话

必须保留返回的 sessionId 和 agentSessionId，追问时传入，实现上下文连续对话。

5.5 集团工单列表

以表格形式展示，包含工单 ID、标题、状态、创建时间、UIN、渠道。

5.6 工单详情（集团）

分段展示：基本信息（状态、渠道、优先级）+ 问题描述。

优先级映射：

Priority	等级
-1	L1
0	L2
1	L3
2	L4

5.7 工单流水

按时间顺序展示操作列表，标注操作类型（认领/转单/派单/回复）和操作人。

5.8 集团需求单列表

以表格形式展示，包含需求单 ID、标题、状态、创建时间、UIN。

5.9 需求单详情

分段展示：基本信息 + 评论列表。

• 评论中 [br] 转换为换行
• 评论中 [img] 提取为图片链接

5.10 人工客服引导

当用户明确表示要找人工客服、转人工、联系客服、在线客服时，直接给出链接：

您可以通过以下链接联系腾讯云人工客服： https://cloud.tencent.com/online-service?from=claw&redirectType=0

• 触发词："找人工"、"转人工"、"人工客服"、"联系客服"、"在线客服"、"我要找人"、"talk to human"、"human support"
• 无需调用任何接口，直接输出上述链接即可

---

六、调试

启用详细输出查看原始请求/响应：

bash

python3 {baseDir}/scripts/andon-api.py -a GetMCTicketList -d '{}' -v
python3 {baseDir}/scripts/smartqa-api.py -q "..." -v

Dry-run 模式仅展示 payload，不发送请求：

bash

python3 {baseDir}/scripts/andon-api.py -a GetMCTicketList -d '{}' -n
python3 {baseDir}/scripts/smartqa-api.py -q "..." -n

---

七、安全与权限声明

7.1 所需凭证

环境变量	必填	用途
TENCENTCLOUD_SECRET_ID	工单操作必填	腾讯云 API SecretId
TENCENTCLOUD_SECRET_KEY	工单操作必填	腾讯云 API SecretKey

SmartQA 的 uin 和 skey 默认为空。

7.2 网络访问范围

本 Skill 仅连接以下腾讯云官方域名：

域名	用途
tandon.tencentcloudapi.com	工单 API（列表、详情）
cloud.tencent.com	SmartQA 会话创建
andon.cloud.tencent.com	SmartQA 聊天（SSE 流）

7.3 数据安全

• 密钥读取：脚本本身只从环境变量读取 AK/SK，不写入文件、日志，也不会把密钥 发送到签名头以外的任何地方
• 凭据持久化由用户决定：本 Skill 的脚本不会创建配置文件、不缓存数据。 但若用户按 §1.1 的备选方式把 AK/SK 写入 ~/.zshrc / ~/.bashrc 或 Windows 用户级环境变量，则密钥会以明文长期留存在磁盘上 —— 这是用户环境的持久化， 不是脚本的行为，但风险真实存在。推荐使用 §1.1 的会话级注入方式避免落盘。
• SSL 验证：所有 HTTPS 请求启用完整 SSL 证书验证（证书链 + 主机名）
• 纯 Python 实现：无需 curl、openssl、jq 等外部依赖

7.4 数据范围与外发

• SmartQA 会把问题和多轮上下文发送到腾讯云（见 §1.2），内容离开本地环境。
• 工单接口返回敏感数据：工单标题、问题描述、沟通记录、UIN、企业名称、 处理人、操作流水、附件链接等。展示给用户时按需呈现，不要在无关上下文中转述， 也不要写入日志或粘贴到第三方服务。
• 默认只查个人工单：GetMCTicketList 默认仅返回当前账号的工单。 如需同时查询集团范围工单，必须显式传入 --include-organization （见 §3.1）—— 该参数会显著扩大返回数据的范围，应先向用户确认。
• -v / -n 输出包含敏感内容：verbose 会打印原始请求/响应，dry-run 会打印 payload 与签名头元数据。不要在共享终端、录屏或日志中使用这两个模式。

---

八、参考文档

使用某个接口前，建议先加载对应的接口文档获取完整参数说明和展示规则：

• 工单列表：{baseDir}/references/GetMCTicketList.md — 状态码映射、过滤参数、分页说明
• 工单详情：{baseDir}/references/GetMCTicketById.md — 评论分页、附件 URL、响应字段
• 智能问答：{baseDir}/references/SmartQA.md — 多轮对话指南、响应类型、产品问题示例
• 集团工单列表：{baseDir}/references/DescribeOrganizationTickets.md — 集团成员工单查询参数、分页说明
• 工单详情（集团）：{baseDir}/references/DescribeTicket.md — 集团工单详情字段、优先级映射
• 工单流水：{baseDir}/references/DescribeTicketOperation.md — 操作记录类型、分页说明
• 集团需求单列表：{baseDir}/references/DescribeOrganizationStories.md — 集团需求单查询参数、分页说明
• 需求单详情：{baseDir}/references/DescribeOrganizationStory.md — 需求单详情字段、评论格式说明