sls-query
SKILL.md
SLS 日志查询 Skill
常用场景快速索引
根据查询目的快速定位 logstore：
- 用户登录/活跃 →
login_log - 聊天消息 →
msgsave - 金币变动 →
coin_change_log - 游戏币变动 →
chip_change_log - 游戏对局 →
sls_game_log - API 请求 →
http-extranet_api_info - HTTP 网关 →
http-ex-access - TCP 网关 →
connector_access - 内容审核/违规 →
dirtyfilter-info - 风控事件 →
risk-engine - 活动相关日志 →
activity_server - 定时任务相关 →
wespy-http-go-cron - 用户成长值日志 →
sls_growth_log
重要规则
脚本路径（按优先级）：
~/.claude/skills/act-sls-query/scripts/sls_cli.py（默认路径，Claude Code）~/.cursor/rules/act-sls-query/scripts/sls_cli.py（Cursor）~/.claude/skills/act-sls-query/scripts/sls_cli.py（Codex）
重要：
- Agent 调用时必须使用完整路径，不要使用相对路径
- 默认使用 Claude Code 路径（
~/.claude/skills/act-sls-query/scripts/sls_cli.py）
核心原则：
- 先问再查，禁止盲查：信息不足时必须先向用户确认，不要猜测后盲目查询多个 logstore
- 优先 CLI，避免写代码：使用 CLI 命令完成所有查询操作
- 批量拉取用 query-all：需要拉取超过 500 条记录时，使用
query-all命令自动分页，无需编写分页脚本 - JSON 输出到 stdout：日志数据输出到 stdout（JSON 格式），状态信息和错误输出到 stderr
- 注意查询时间范围：默认查询最近 1 小时，排查问题时注意根据实际情况调整时间范围
- 区服判断：用户提到具体区服时使用
--region，未指定时使用配置文件中的default_region，如用户未明确区服则询问
排查流程（必须严格遵守）
每次查询必须经过：信息收集 → 确认汇总 → 执行查询 → 超时兜底，四个阶段缺一不可。
第一步：信息收集（必填项检查）
收到排查请求后，必须对照以下清单逐项检查，4 项全部确认后才能进入下一步：
| 必填项 | 说明 | 缺失时处理 |
|---|---|---|
| logstore | 要查哪个日志库 | 根据「logstore 决策树」推断，无法确定则必须反问 |
| 区服 | 查哪个区服的数据 | 必须反问，禁止猜测或使用默认值 |
| 时间范围 | 问题发生的具体时间 | 必须反问，禁止使用默认 1h（容易查不到白跑） |
| 查询条件 | uid / act_id / device_id 等 | 至少一个过滤条件，否则必须反问 |
反问规则：
- 缺少任意必填项 → 一次性列出所有缺失项，避免多轮追问
- 4 项全部具备 → 进入第二步确认
反问模板：
查询日志前需要确认以下信息：
1. 📦 日志库：查哪个库？（如：活动日志 activity_server / 金币变动 coin_change_log / ...）
2. 🌐 区服：哪个区服？（如：华语服 C / 日服 J / ...）
3. ⏰ 时间范围：大概什么时间发生的？（如：今天 14:00 左右 / 最近 2 小时 / 2026-04-01 14:00~16:00）
4. 🔍 查询条件：uid / act_id / 其他关键信息？
第二步：确认汇总（执行前必须确认）
无论信息是用户一次性提供还是多轮补充的，执行查询前必须输出确认汇总，等待用户确认后再查询：
📋 查询确认：
- 日志库：activity_server
- 区服：华语服 (C)
- 时间范围：2026-04-01 14:00:00 ~ 2026-04-01 16:00:00
- 查询条件：uid: 12345
确认后开始查询，请回复"确认"或修改以上信息。
用户回复"确认"/"可以"/"查"等肯定词后，立即执行查询。 用户提出修改 → 更新对应项后重新输出确认汇总。
第三步：执行查询（带超时保护）
超时兜底规则：
每次执行 CLI 查询命令时，必须设置 5 分钟（300 秒）超时：
timeout 300 ~/.claude/skills/act-sls-query/scripts/sls_cli.py --region C query \
--logstore activity_server --query "* and uid: 12345" \
--from "2026-04-01 14:00:00" --to "2026-04-01 16:00:00"
查询超时或无结果时的处理：
⏱️ 查询超时/无结果，可能原因：
1. 时间范围过大，数据量超出处理能力 → 建议缩小时间范围（如从 2h 缩到 30m）
2. 查询条件过于宽泛 → 建议增加过滤条件（如加上 act_id）
3. logstore 选择不对 → 该问题的日志可能记录在其他库中
4. 该时间段确实无匹配数据
请提供以下信息帮助进一步排查：
- 能否缩小时间范围？（精确到分钟最佳）
- 是否有其他过滤条件可以补充？
- 是否需要换一个日志库查询？
优化查询性能的原则：
- 时间范围尽量精确：能用 30m 不用 1h，能用 1h 不用 24h
- 必须带过滤条件：禁止
--query "*"全量查询 - 优先用
count预估数据量：数据量大时先 count，再决定是否 query-all query-all大数据量场景：建议--format jsonl+ 重定向到文件，避免内存溢出
logstore 决策树
当用户未明确 logstore 但描述了问题场景时，按以下规则快速定位：
| 用户描述关键词 | 对应 logstore | 直接查询 |
|---|---|---|
| "登录"、"在线"、"活跃"、"版本" | login_log |
✅ |
| "金币"、"充值"、"钻石" | coin_change_log |
✅ |
| "游戏币"、"筹码"、"下注" | chip_change_log |
✅ |
| "对局"、"胜负"、"游戏记录" | sls_game_log |
✅ |
| "活动"、"act_id"、"活动参与"、"活动报错"、"活动异常" | activity_server + http-extranet_api_info |
✅ 两个库都查 |
| "定时任务"、"cron"、"定时" | wespy-http-go-cron |
✅ |
| "成长值"、"等级"、"经验" | sls_growth_log |
✅ |
| "聊天"、"消息"、"发言" | msgsave |
✅ |
| "违规"、"封禁"、"审核" | dirtyfilter-info |
✅ |
| "风控"、"异常检测" | risk-engine |
✅ |
| "接口报错"、"API"、"500" | http-extranet_api_info |
✅ |
| "网关"、"超时"、"请求慢" | http-ex-access |
✅ |
| 无法从描述判断 | — | ❌ 必须反问 |
活动相关查询特殊规则
当判断为活动相关问题（提到"活动"、"act_id"、活动名称等）且用户未指定具体 logstore 时：
- 默认同时查询两个库：
activity_server（活动业务日志）+http-extranet_api_info（API 请求日志） - 先查
activity_server定位活动业务逻辑问题，再查http-extranet_api_info看接口层是否有报错 - 如果两个库都没有明显线索，再反问用户补充信息
完整示例
❌ 错误做法（盲查 + 无确认 + 无超时）：
用户：帮我查一下 uid 12345 的活动问题
Agent：（不确认，直接查 activity_server → 超时 → 查 http-extranet_api_info → 又超时 → 10 分钟过去了...）
✅ 正确做法：
用户：帮我查一下 uid 12345 的活动问题
Agent：查询前确认以下信息：
1. 🌐 区服：哪个区服？
2. ⏰ 时间范围：大概什么时间发生的？
用户：华语服，今天下午 2 点左右
Agent：
📋 查询确认：
- 日志库：activity_server + http-extranet_api_info
- 区服：华语服 (C)
- 时间范围：2026-04-07 14:00:00 ~ 2026-04-07 15:00:00
- 查询条件：uid: 12345
确认后开始查询，请回复"确认"或修改以上信息。
用户：确认
Agent：（执行 timeout 300 查询...）
配置说明
配置文件 ~/.sls_config.json：
{
"default_region": "C",
"access_key_id": "<your-access-key-id>",
"access_key_secret": "<your-access-key-secret>"
}
default_region：默认区服（不指定--region时使用）- 也可通过环境变量配置 AK/SK：
SLS_ACCESS_KEY_ID、SLS_ACCESS_KEY_SECRET - 优先级：
--region>--endpoint/--project> 环境变量 > 配置文件default_region> 配置文件endpoint/project
快速参考
| 操作 | 命令 | 示例 |
|---|---|---|
| 查询日志 | query |
sls_cli.py --region C query --logstore login_log --query "* and uid: 123" --from 24h |
| 拉取全部 | query-all |
sls_cli.py --region A query-all --logstore coin_change_log --query "* and type: 2607" --from "2026-02-09 00:00:00" --to "2026-02-09 14:30:00" |
| 统计数量 | count |
sls_cli.py --region 土语服 count --logstore login_log --query "* and uid: 123" --from 7d |
| 列出 logstore | list-logstores |
sls_cli.py list-logstores |
| 列出区服 | list-regions |
sls_cli.py list-regions |
CLI 命令详细用法
全局参数
--region：区服代码或名称（如C/华语服/J/日服），自动映射到对应的 endpoint 和 project。优先级最高。--dev：查询测试服环境，自动在 project 名后追加-dev（如weplay-sgp→weplay-sgp-dev）--endpoint：手动指定 SLS endpoint（--region优先）--project：手动指定 SLS project（--region优先）
query — 查询日志记录
~/.claude/skills/act-sls-query/scripts/sls_cli.py [--region <区服>] query \
--logstore <logstore名称> \
--query "<SLS查询语句>" \
[--from <起始时间>] \
[--to <结束时间>] \
[--limit <最大返回条数>] \
[--offset <分页偏移量>] \
[--reverse]
参数说明：
--logstore(required)：LogStore 名称，见下方 logstore 列表--query(required)：SLS 查询语句，如"* and uid: 123"--from：起始时间（默认1h）- 相对时间：
15m、1h、24h、7d、30d - 日期字符串：
2024-01-01或2024-01-01 00:00:00 - Unix 时间戳：
1704067200
- 相对时间：
--to：结束时间（默认now），格式同--from--limit：最大返回条数（默认 500）--offset：分页偏移量（默认 0）--reverse：倒序排列（最新的在前）
query-all — 自动分页拉取全部记录
~/.claude/skills/act-sls-query/scripts/sls_cli.py [--region <区服>] query-all \
--logstore <logstore名称> \
--query "<SLS查询语句>" \
[--from <起始时间>] \
[--to <结束时间>] \
[--page-size <每页记录数>] \
[--format json|jsonl] \
[--reverse]
参数说明：
--logstore(required)：LogStore 名称--query(required)：SLS 查询语句--from：起始时间（默认1h），格式同 query 命令--to：结束时间（默认now）--page-size：每页记录数（默认 500），内部自动循环分页直到拉完--format：输出格式，json（默认，JSON 数组）或jsonl（每行一个 JSON 对象，适合大数据量管道处理）--reverse：倒序排列
适用场景：需要拉取超过 500 条记录的批量分析，无需手动编写分页循环。内置自动重试（incomplete 时最多重试 3 次）。
示例：
# 拉取某天全部金币入场记录（JSON 数组）
sls_cli.py --region A query-all --logstore coin_change_log \
--query "* and type: 2607 and subtype: 2005" \
--from "2026-02-09 00:00:00" --to "2026-02-09 14:30:00"
# 拉取并以 JSONL 格式输出（适合 jq 管道处理）
sls_cli.py --region A query-all --logstore chip_change_log \
--query "* and type: 2607" \
--from "2026-02-09 00:00:00" --to "2026-02-09 14:30:00" \
--format jsonl
# 保存到文件
sls_cli.py --region A query-all --logstore sls_game_log \
--query "* and game_type: 2005" \
--from "2026-02-09 00:00:00" --to "2026-02-09 17:00:00" \
--format jsonl > /tmp/game_logs.jsonl
count — 统计日志数量
~/.claude/skills/act-sls-query/scripts/sls_cli.py [--region <区服>] count \
--logstore <logstore名称> \
--query "<SLS查询语句>" \
[--from <起始时间>] \
[--to <结束时间>]
内部自动在 query 后追加 | select count(*) as total，返回 {"total": N}。
list-logstores — 列出已知 logstore
~/.claude/skills/act-sls-query/scripts/sls_cli.py list-logstores
列出内置的 logstore 列表，包含名称、说明和常用字段。
list-regions — 列出可用区服
~/.claude/skills/act-sls-query/scripts/sls_cli.py list-regions
列出所有可用区服及其代码、项目名和别名。
区服代码
支持标准代码和中文别名，使用 --region 参数指定：
| 代码 | 名称 | Project | 别名 |
|---|---|---|---|
C |
华语服 | weplay-sgp | 华语、中国、新加坡 |
T |
泰服 | weplay-bkk | 泰国、泰语服 |
M |
马尼服 | weplay-mas | 马来西亚、马来服 |
P |
菲律宾服 | weplay-phl | 菲律宾 |
V |
越南服 | weplay-vnm | 越南 |
J |
日服 | weplay-tky | 日本、日语服 |
K |
韩服 | weplay-sel | 韩国 |
U |
美服 | weplay-sv | 美国 |
R |
俄语服 | weplay-rus | 俄罗斯、俄服 |
B |
葡语服 | weplay-br | 葡萄牙、葡萄牙服 |
S |
西语服 | weplay-va | 西班牙 |
F |
法语服 | weplay-par | 法国 |
G |
德语服 | weplay-de | 德国 |
Y |
意语服 | weplay-it | 意大利 |
A |
阿语服 | weplay-fra | 阿拉伯、阿语 |
Q |
土耳其服 | weplay-tur | 土语服、土耳其 |
I |
印度服 | weplay-in | 印度 |
O |
JK服 | jackaroo-ar | jk、jackaroo |
N |
巴基斯坦服 | weplay-pk | 巴基斯坦、乌语服 |
使用示例：--region C、--region 华语服、--region 土语服 均可。
已知 LogStore 列表
| LogStore | 说明 | 常用字段 |
|---|---|---|
login_log |
登录/活跃记录 | uid, device_id, ip, platform, log_time, app_version, country, province |
msgsave |
聊天消息 | uid, content, target_id, msg_type |
coin_change_log |
金币变动 | uid, coin, type, subtype, remain_coin, log_time, device_id |
chip_change_log |
游戏币变动 | uid, chip, type, subtype, remain_chip, log_time, device_id |
sls_game_log |
游戏记录 | uid, rid, game_type, is_win, bet_level, start_time, end_time |
activity_data |
活动事件 | act_id, uid, key |
risk-engine |
风控日志 | uid, device_id, risk_source |
dirtyfilter-info |
内容过滤 | uid, content, channel, risk_level, label, sub_label, scene, rid |
external_info |
短信日志 (prod) | — |
http-extranet_api_info |
API 服务日志 | method, path, status, response_time, uid |
http-ex-access |
HTTP 网关日志 | bytes_sent, client_ip, http_code, method, uri, response_ms, uid, ua, referer, protocol, forward_ip |
connector_access |
TCP 网关日志 | uid, command, type, response_time, bytes_sent, c_body_size, rid, version |
tmproom |
临时房间信息 | — |
clientupload |
客户端上报 | — |
client_ping |
客户端心跳 | uid, device_name |
sls_user_title_log |
用户称号 | uid |
record |
杂项记录 | category, uid, content, shumei_device_id, scene_type, labels |
activity_server |
活动相关日志 | act_id, uid |
wespy-http-go-cron |
定时任务相关 | uid |
sls_growth_log |
用户成长值日志 | uid, old_value, new_value |
SLS 查询语法参考
基础语法
# 全量查询
*
# AND 条件
* and uid: 123
# 多条件 AND
* and uid: 123 and platform: android
# OR 条件
* and (type: 1 or type: 2)
# NOT 条件
* and uid: 123 not platform: ios
# 字符串精确匹配（带引号）
* and content: "hello world"
# 数值比较（需要 SQL 子句）
* | select * where coin > 100
SQL 分析子句
SLS 支持在查询后追加 | select ... 进行 SQL 分析：
# 统计总数
* and uid: 123 | select count(*) as total
# 求和
* and uid: 123 | select sum(coin) as total_coin
# 分组统计
* and uid: 123 | select type, count(*) as cnt group by type
# 条件过滤 + 统计
* and uid: 123 | select sum(coin) as total where coin < 0
# 去重计数
* and uid: 123 | select count(distinct device_id) as device_count
# 排序 + 分页
* and uid: 123 | select * order by __time__ desc limit 0, 100
# 时间聚合
* and uid: 123 | select date_format(__time__, '%Y-%m-%d') as day, count(*) as cnt group by day order by day
常用内置字段
__time__：日志时间（Unix 时间戳）__source__：日志来源__topic__：日志 topic
常用查询模板
登录日志 (login_log)
# 查询用户最近登录记录
sls_cli.py query --logstore login_log --query "* and uid: 123" --from 7d --reverse
# 查询某设备的登录记录
sls_cli.py query --logstore login_log --query "* and device_id: abc123" --from 24h
# 统计用户某段时间登录次数
sls_cli.py count --logstore login_log --query "* and uid: 123" --from 30d
# 查询某国家的登录分布
sls_cli.py query --logstore login_log --query "* and uid: 123 | select country, count(*) as cnt group by country" --from 30d
金币变动 (coin_change_log)
# 查询用户金币变动
sls_cli.py query --logstore coin_change_log --query "* and uid: 123" --from 24h --reverse
# 查询特定类型的金币变动
sls_cli.py query --logstore coin_change_log --query "* and uid: 123 and type: 1" --from 7d
# 统计用户金币总收入
sls_cli.py query --logstore coin_change_log --query "* and uid: 123 | select sum(coin) as total where coin > 0" --from 30d
# 统计用户金币变动次数（按类型分组）
sls_cli.py query --logstore coin_change_log --query "* and uid: 123 | select type, subtype, count(*) as cnt, sum(coin) as total group by type, subtype" --from 7d
游戏币变动 (chip_change_log)
# 查询用户游戏币变动
sls_cli.py query --logstore chip_change_log --query "* and uid: 123" --from 24h --reverse
# 拉取某天全部游戏币入场记录
sls_cli.py query-all --logstore chip_change_log --query "* and type: 2607" --from "2026-02-09 00:00:00" --to "2026-02-09 14:30:00"
# 统计用户游戏币变动（按类型分组）
sls_cli.py query --logstore chip_change_log --query "* and uid: 123 | select type, count(*) as cnt, sum(chip) as total group by type" --from 7d
聊天消息 (msgsave)
# 查询用户聊天记录
sls_cli.py query --logstore msgsave --query "* and uid: 123" --from 24h --reverse
# 查询两个用户之间的聊天
sls_cli.py query --logstore msgsave --query "* and uid: 123 and target_id: 456" --from 7d
游戏记录 (sls_game_log)
# 查询用户游戏记录
sls_cli.py query --logstore sls_game_log --query "* and uid: 123" --from 7d --reverse
# 查询某房间的游戏记录
sls_cli.py query --logstore sls_game_log --query "* and rid: 456" --from 24h
# 统计用户胜率
sls_cli.py query --logstore sls_game_log --query "* and uid: 123 | select is_win, count(*) as cnt group by is_win" --from 30d
活动数据 (activity_data)
# 查询用户的活动参与记录
sls_cli.py query --logstore activity_data --query "* and uid: 123 and act_id: 100" --from 7d
# 统计活动参与人数
sls_cli.py query --logstore activity_data --query "* and act_id: 100 | select count(distinct uid) as user_count" --from 7d
内容过滤 (dirtyfilter-info)
# 查询用户的违规记录
sls_cli.py query --logstore dirtyfilter-info --query '* and uid: 123 and (risk_level: REVIEW or risk_level: REJECT)' --from 7d
# 查询高风险内容
sls_cli.py query --logstore dirtyfilter-info --query '* and risk_level: REJECT and "check result record"' --from 24h --reverse
# 按标签统计违规类型
sls_cli.py query --logstore dirtyfilter-info --query '* and uid: 123 and risk_level: REJECT | select label, count(*) as cnt group by label' --from 30d
风控日志 (risk-engine)
# 查询用户风控事件
sls_cli.py query --logstore risk-engine --query "* and uid: 123" --from 7d
# 查询设备的风控事件
sls_cli.py query --logstore risk-engine --query "* and device_id: abc123" --from 7d
杂项记录 (record)
# 查询特定分类的记录
sls_cli.py query --logstore record --query "* and category: bottle and uid: 123" --from 7d
# 查询数美风控事件
sls_cli.py query --logstore record --query "* and category: shumei_risk and uid: 123" --from 7d
注意事项
- 时间范围：默认查询最近 1 小时，排查历史问题时记得调整
--from参数 - 返回条数：
query默认最多返回 500 条，可通过--limit调整；需要拉取全部数据时使用query-all命令自动分页 - 查询完整性：
query和query-all均内置 incomplete 自动重试（最多 3 次），无需手动处理 - 批量数据分析：优先使用
query-all命令直接拉取全部数据，避免手动编写分页脚本。大数据量场景建议使用--format jsonl输出，便于管道处理 - 金币 vs 游戏币：金币变动在
coin_change_log，游戏币变动在chip_change_log，两者是不同的 logstore，字段也不同（coin vs chip） - logstore 名称：注意 dev 和 prod 环境的 logstore 可能不同（如短信日志在 dev 用
http-extranet_api_info，prod 用external_info） - SQL 子句：使用
| select ...时，统计结果可能需要更长时间，建议缩小时间范围