issue-troubleshooter
SKILL.md
客服工单问题排查助手
概述
统一排查入口，根据用户提供的工单/问题信息，自动编排多个下游 skill 完成标准化排查流程。
排查流程（四阶段，两次确认）：
阶段一：信息收集 → 确认汇总 🛑（第一次确认）
↓
阶段二：问题分类 → 生成排查计划 🛑（第二次确认）
↓
阶段三：按计划逐步执行排查
↓
阶段四：汇总结论与建议
下游 Skill 依赖
| Skill | 用途 | 默认脚本路径 |
|---|---|---|
sls-query |
查询生产日志 | ~/.claude/skills/act-sls-query/scripts/sls_cli.py |
fetch-game-config-clean |
查询活动配置 | ~/.claude/skills/act-fetch-game-config-clean/scripts/fetch_config.py |
weplay-config-query |
查询平台配置（礼物、道具等） | ~/.claude/skills/act-weplay-config-query/scripts/query_weplay_config.py |
feishu-project-tool |
查询飞书工单详情 | ~/.claude/skills/act-feishu-project-tool/scripts/query_issue.py |
redis-query |
只读查询线上 Redis 数据 | ~/.claude/skills/act-redis-query/scripts/redis_query.py |
gitepic |
查看代码和提交记录 | gitepic CLI |
脚本路径预检（阶段三执行前必须完成）
在阶段三开始执行排查前，必须先验证所有排查计划中涉及的脚本是否存在。 对排查计划中用到的每个 skill，执行路径检查：
# 检查脚本是否存在（按排查计划中实际用到的 skill 检查，不必全部检查）
ls -la ~/.claude/skills/act-sls-query/scripts/sls_cli.py 2>/dev/null && echo "✅ sls-query" || echo "❌ sls-query"
ls -la ~/.claude/skills/act-fetch-game-config-clean/scripts/fetch_config.py 2>/dev/null && echo "✅ fetch-game-config-clean" || echo "❌ fetch-game-config-clean"
ls -la ~/.claude/skills/act-weplay-config-query/scripts/query_weplay_config.py 2>/dev/null && echo "✅ weplay-config-query" || echo "❌ weplay-config-query"
ls -la ~/.claude/skills/act-feishu-project-tool/scripts/query_issue.py 2>/dev/null && echo "✅ feishu-project-tool" || echo "❌ feishu-project-tool"
ls -la ~/.claude/skills/act-redis-query/scripts/redis_query.py 2>/dev/null && echo "✅ redis-query" || echo "❌ redis-query"
预检结果处理：
| 结果 | 处理 |
|---|---|
| 全部 ✅ | 正常进入阶段三执行 |
| 部分 ❌ | 输出缺失提示，跳过该 skill 对应步骤，排查计划中标注"skill 不可用" |
| 全部 ❌ | 提示用户安装 skill：weactai install-all |
缺失时的提示模板：
⚠️ 脚本预检发现以下 skill 未安装：
- ❌ fetch-game-config-clean（排查计划步骤 2 将跳过）
排查将继续执行可用步骤，跳过的步骤需手动排查。
如需安装缺失 skill，请执行：weactai install fetch-game-config-clean
备选路径探测（当默认路径不存在时）：
部分 skill 可能安装在非标准路径，按以下优先级探测：
~/.claude/skills/act-<name>/scripts/（Claude Code，默认）~/.cursor/rules/act-<name>/scripts/（Cursor）~/.codex/skills/<name>/scripts/（Codex）
# 备选路径探测示例（以 sls-query 为例）
for dir in ~/.claude/skills/act-sls-query ~/.cursor/rules/act-sls-query ~/.codex/skills/sls-query; do
if [ -f "$dir/scripts/sls_cli.py" ]; then
echo "found: $dir/scripts/sls_cli.py"
break
fi
done
阶段一：信息收集与确认 🛑
必填信息（缺一不可）
| 必填项 | 说明 | 缺失时处理 |
|---|---|---|
| 问题描述 | 飞书工单链接 或 文字描述 | 必须反问 |
| 区服 | 哪个区服（如 C/华语服/J/日服） | 必须反问，禁止猜测 |
| 时间范围 | 问题发生的具体时间 | 必须反问，禁止用默认值 |
| 用户标识 | uid 或 device_id | 必须反问 |
可选信息（有则更精准）
| 可选项 | 说明 |
|---|---|
| 活动 ID | act_id，有则直接查活动配置和日志 |
| 具体报错 | 错误码、接口名、截图描述 |
| 环境 | 测试服/正式服（默认正式服） |
| 活动配置 key | 有则直接查配置，无需推断 |
反问规则
缺少任意必填项时，一次性列出所有缺失项：
排查问题前需要确认以下信息：
1. 问题描述：具体是什么问题？（或提供飞书工单链接）
2. 区服：哪个区服？（如：华语服 C / 日服 J / ...）
3. 时间范围：大概什么时间发生的？（如：今天 14:00 左右 / 2026-04-07 14:00~16:00）
4. 用户标识：uid 或 device_id？
飞书工单自动提取
当用户提供飞书工单链接（project.feishu.cn）时：
- 调用
feishu-project-tool获取工单详情 - 从工单中自动提取：问题描述、关联用户、发生时间
- 仍需用户补充缺失的必填项（如区服）
确认汇总（第一次确认）
所有必填项齐全后，必须输出确认汇总，等待用户确认：
📋 排查信息确认：
- 问题描述：用户反馈活动领不到奖励
- 区服：华语服 (C)
- 时间范围：2026-04-07 14:00:00 ~ 2026-04-07 16:00:00
- 用户：uid: 12345
- 活动 ID：100（可选）
- 环境：正式服
信息确认后将生成排查计划，请回复"确认"或修改以上信息。
用户确认后进入阶段二。
阶段二：问题分类与排查计划 🛑
问题分类决策树
根据问题描述中的关键词自动分类：
| 问题类型 | 触发关键词 | 排查步骤（按顺序执行） |
|---|---|---|
| 活动奖励问题 | 领不到、发奖失败、奖励异常、没收到奖励、奖励错误 | ① sls-query activity_server 日志 → ② fetch-game-config-clean 活动配置 → ③ sls-query coin/chip_change_log → ④ redis-query 验证 Redis 存储状态（按需） |
| 活动配置问题 | 配置错误、时间不对、条件不对、活动没开、活动提前结束 | ① fetch-game-config-clean 活动配置 → ② sls-query activity_server 日志 |
| 活动入口/显示问题 | 看不到活动、入口消失、UI异常、活动不显示、白屏 | ① fetch-game-config-clean 活动配置(时间/条件) → ② sls-query http-extranet_api_info |
| 接口报错 | 500、报错、请求失败、超时、接口异常 | ① sls-query http-extranet_api_info → ② sls-query http-ex-access → ③ 代码排查 |
| 用户数据异常 | 金币不对、游戏币丢失、数据异常、余额错误、数据没重置、数据不一致 | ① sls-query coin/chip_change_log → ② sls-query activity_server → ③ redis-query 查 Redis 存储状态 → ④ weplay-config-query 平台配置 |
| 礼物/道具问题 | 礼物、道具、装扮、背包、购买失败 | ① weplay-config-query 礼物/道具配置 → ② sls-query coin_change_log → ③ sls-query http-extranet_api_info |
| 定时任务问题 | cron没执行、定时任务失败、没有自动执行 | ① sls-query wespy-http-go-cron → ② fetch-game-config-clean 相关配置 |
| 用户登录问题 | 登不上、闪退、登录失败、版本不对 | ① sls-query login_log → ② sls-query client_ping |
| 成长值/等级问题 | 成长值、等级、经验、升级 | ① sls-query sls_growth_log → ② sls-query activity_server |
| 无法分类 | — | 反问用户补充更多信息 |
排查计划输出（第二次确认）
分类完成后，输出排查计划并等待用户确认：
📋 排查计划：
问题类型：活动奖励问题
排查步骤：
1. [sls-query] 查 activity_server 日志
→ 区服: C | 时间: 14:00~16:00 | 条件: uid=12345, act_id=100
2. [fetch-game-config-clean] 查活动配置
→ namespace: activity | region: C | key: <从步骤1结果推断或用户提供>
3. [sls-query] 查 coin_change_log 奖励发放记录
→ 区服: C | 时间: 14:00~16:00 | 条件: uid=12345
确认后开始排查，请回复"确认"或修改以上计划。
用户确认后进入阶段三。
阶段三：按计划逐步执行
执行规则
- 按计划步骤顺序执行，每步调用对应 skill
- 每步必须设置超时：所有命令前加
timeout 300（5 分钟） - 逐步输出结果：每步执行完立即输出关键发现，不要等全部跑完
逐步输出格式
每步执行完输出：
✅ 步骤 1/3 完成 [sls-query → activity_server]
发现：用户 12345 在 14:23 参与活动 100，状态为 success，但未触发发奖逻辑
→ 继续步骤 2...
动态调整
- 某步发现关键线索 → 可调整后续步骤优先级
- 例：日志发现 "config not found" → 优先查配置，跳过后续日志步骤
- 某步结果指向新方向 → 可追加排查步骤
- 例：活动配置正常，但日志显示平台礼物 ID 异常 → 追加 weplay-config-query 查礼物配置
- 日志/配置无法解释数据不一致 → 追加 redis-query 查 Redis 实际存储值
- 例：日志显示发奖成功但用户反馈没收到 → 用 redis-query 查
act:{actId}:*:{uid}验证 Redis 中是否有奖励记录
- 例：日志显示发奖成功但用户反馈没收到 → 用 redis-query 查
超时与异常处理
⏱️ 步骤 2/3 超时 [fetch-game-config-clean]
可能原因：配置数据量过大或网络问题
处理：跳过此步，继续步骤 3，最终结论中标注此步未完成
异常处理原则：
- 超时 → 记录原因，继续下一步，不阻塞整体流程
- 无结果 → 记录"该维度未发现异常"，继续下一步
- skill 不可用 → 记录并跳过，建议用户手动检查
下游 Skill 调用规范
sls-query 调用
timeout 300 ~/.claude/skills/act-sls-query/scripts/sls_cli.py \
--region <区服> query \
--logstore <logstore> \
--query "* and uid: <uid>" \
--from "<开始时间>" --to "<结束时间>" \
--limit 100 --reverse
fetch-game-config-clean 调用
timeout 300 ~/.claude/skills/act-fetch-game-config-clean/scripts/fetch_config.py \
--namespace <namespace> \
--region <区服> \
--key <config_key> \
--env <prod|dev> \
--pretty
常用 namespace：
activity：活动配置activity_config：活动全局配置blindbox_config：盲盒配置gift_box：礼盒配置gift_pkg：礼包配置
weplay-config-query 调用
timeout 300 ~/.claude/skills/act-weplay-config-query/scripts/query_weplay_config.py \
--namespace <namespace> \
--key <key> \
--regions <区服> \
--scene online \
--json-output
注意：
- 排查线上问题时
--scene必须传online（该脚本默认test） - 若脚本输出
terminal=true或retryable=false，必须立即停止，不得重试或换参数重查 - 单轮对话内配置查询脚本最多执行一次
feishu-project-tool 调用
timeout 300 ~/.claude/skills/act-feishu-project-tool/scripts/query_issue.py \
"<飞书工单URL或ID>" [--key <namespace_key> --type <issue|story|task>]
支持的输入格式：完整 URL、project_key:type:id、ID + --key + --type、纯 ID（自动遍历）。
redis-query 调用
timeout 300 ~/.claude/skills/act-redis-query/scripts/redis_query.py \
--region <区服> \
--env online \
--agent-user-id <feishu_sender_id> \
--ins <实例名> \
--cmd <命令> [参数...]
排查未知 key 的标准流程：先 TYPE + TTL 探测类型和过期时间，再按类型选择对应读命令（GET/HGETALL/ZREVRANGE 等）。
活动 Redis 键命名规范：act:{actId}:{module}:{entity}:{uid}:{suffix}
常用排查命令：
# 探测 key 类型和过期
--cmd TYPE act:1001:reward:state:12345
--cmd TTL act:1001:reward:state:12345
# 读取 hash 全部字段
--cmd HGETALL act:1001:sign:state:12345
# 查排行榜 Top 10
--cmd ZREVRANGE act:1001:rank:score 0 9 WITHSCORES
# 检查 key 是否存在
--cmd EXISTS act:1001:reward:state:12345
注意：
- 排查线上问题时
--env必须传online（该脚本默认test） --agent-user-id必须使用当前对话中的飞书发送者 ID，禁止臆造- 只读查询，仅允许
GET/HGET/ZRANGE/EXISTS/TYPE/TTL等读命令 GET/HGET超过 4096 字节会被拒绝，需改用GETRANGE分段读取- 有敏感 key 黑名单（coin/充值/支付相关），触发时跳过该步骤
- 请求失败时最多重试一次，禁止循环重试
阶段四：汇总结论与建议
结论输出模板
## 排查结论
**问题类型**：<问题分类>
**根因**：<一句话根因描述>
**证据链**：
1. [activity_server] 用户 14:23 参与活动，状态 success，未触发发奖
2. [活动配置] reward_time = "2026-04-08 00:00:00"，用户参与时未到发奖时间
3. [coin_change_log] 该时间段无该用户的奖励发放记录
**结论**：活动配置中发奖时间设置为 2026-04-08，用户在 04-07 参与时尚未到发奖时间，属于配置预期行为。
**建议**：
- 方案 A：如需立即发奖，修改活动配置 reward_time 为 2026-04-07 00:00:00
- 方案 B：如设计如此，向用户解释发奖将在 04-08 统一发放
**关联信息**：
- 活动配置：namespace=activity, key=xxx
- 关键日志时间：2026-04-07 14:23:15
- 涉及 logstore：activity_server, coin_change_log
无法定位根因时
## 排查结论
**问题类型**：<问题分类>
**当前发现**：
1. [activity_server] 日志显示 xxx
2. [活动配置] 配置值为 xxx
**未能定位根因**，建议：
1. 补充信息：<需要用户提供什么>
2. 扩大排查范围：<建议查哪个库/什么时间段>
3. 代码排查：<建议看哪个模块的代码>
完整示例
示例 1：用户提供飞书工单
用户：帮我排查一下这个工单 https://project.feishu.cn/weplay/issue/detail/6686747751
Agent：
📋 排查信息确认：
- 问题描述：[从工单提取] 用户反馈参与春节活动后未收到金币奖励
- 区服：需要确认，请问是哪个区服？
- 时间范围：[从工单提取] 2026-04-06 提交
- 用户：[从工单提取] uid: 88888
- 工单链接：https://project.feishu.cn/weplay/issue/detail/6686747751
请补充区服信息。
用户：华语服
Agent：
📋 排查信息确认（更新）：
- 问题描述：用户参与春节活动后未收到金币奖励
- 区服：华语服 (C)
- 时间范围：2026-04-06 00:00:00 ~ 2026-04-06 23:59:59
- 用户：uid: 88888
- 环境：正式服
信息确认后将生成排查计划，请回复"确认"。
用户：确认
Agent：
📋 排查计划：
问题类型：活动奖励问题
排查步骤：
1. [sls-query] 查 activity_server 日志 → uid=88888, 华语服, 04-06 全天
2. [fetch-game-config-clean] 查活动配置 → namespace=activity, 华语服
3. [sls-query] 查 coin_change_log → uid=88888, 华语服, 04-06 全天
确认后开始排查。
用户：确认
Agent：（执行排查...逐步输出结果...最终输出结论）
示例 2：用户直接描述问题
用户：华语服 uid 12345 今天下午活动领不到奖
Agent：
📋 排查信息确认：
- 问题描述：活动领不到奖励
- 区服：华语服 (C)
- 时间范围：2026-04-07 12:00:00 ~ 2026-04-07 18:00:00（今天下午）
- 用户：uid: 12345
- 环境：正式服
信息确认后将生成排查计划，请回复"确认"或修改以上信息。
全局超时兜底（10 分钟硬限制）
从阶段三开始计时，如果整体排查超过 10 分钟仍未完成，必须立即中断并输出当前进度报告：
⏱️ 排查已超过 10 分钟，暂停并汇报当前进度：
## 当前进度
| 步骤 | 状态 | 发现 |
|------|------|------|
| 1. activity_server 日志 | ✅ 完成 | 用户 14:23 参与活动，状态 success |
| 2. 活动配置 | ⏱️ 超时 | 未能获取配置数据 |
| 3. coin_change_log | ⏳ 未执行 | — |
## 当前卡点
- 步骤 2 查询活动配置超时，可能原因：配置数据量过大 / 网络问题
- 步骤 3 尚未执行
## 已有线索
- activity_server 显示用户参与成功但未触发发奖
## 加速排查建议
请补充以下信息，可大幅缩短排查时间：
1. **活动配置 key**：如果知道具体的配置 key，可跳过推断直接查询
2. **缩小时间范围**：当前查询 04-06 全天，如能精确到小时（如 14:00~15:00）会更快
3. **具体报错信息**：如有错误码或接口名，可精准定位日志
4. **是否需要继续**：回复"继续"将从卡点恢复执行剩余步骤
→ 补充信息后回复，或回复"继续"从断点恢复。
超时兜底规则：
- 进入阶段三时记录开始时间
- 每步执行完检查累计耗时，超过 10 分钟立即中断
- 中断时必须输出：已完成步骤及发现、卡点原因、已有线索、加速建议
- 用户补充信息后，从断点恢复执行（不重复已完成步骤）
- 用户回复"继续"→ 跳过卡点步骤，执行剩余步骤
注意事项
- 两次确认不可省略：信息确认 + 排查计划确认，确保不做无用功
- 禁止盲查：不在信息不全时尝试多个 logstore
- 双重超时保护：单步
timeout 300（5 分钟） + 全局 10 分钟硬限制 - 逐步输出：每步完成立即输出发现，用户可实时了解进展
- 结论有据：结论必须基于证据链，禁止猜测
- 无法定位时坦诚：给出已有发现和进一步排查建议，不强行下结论
- 断点恢复：超时中断后支持从断点继续，不重复已完成步骤