☁️ 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网络超时或连接失败检查网络，重试SessionCreateFailedSmartQA 会话创建失败可能是暂时性问题，重试EmptyResponseSSE 流中无回答内容问题格式不支持HttpErrorHTTP 状态码非 200检查 API 状态ParseError响应不是有效 JSON检查网络环境

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

错误码含义解决方案AuthFailureAK/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等级-1L10L21L32L4

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 SecretIdTENCENTCLOUD_SECRET_KEY工单操作必填腾讯云 API SecretKey

SmartQA 的 uin 和 skey 默认为空。

7.2 网络访问范围#

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

域名用途tandon.tencentcloudapi.com工单 API（列表、详情）cloud.tencent.comSmartQA 会话创建andon.cloud.tencent.comSmartQA 聊天（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 — 需求单详情字段、评论格式说明