腾讯云 CLS 日志查询
只读查询腾讯云 CLS 日志，并据此还原时间线、判断故障根因。本技能不绑定任何业务、账号或日志主题；每位使用者自行配置凭证和 Topic。
何时使用
- 用户粘贴 CLS 控制台检索页 URL
- 用户给出请求 ID、Trace ID、错误码、关键字，要求查线上或生产日志
- 用户要求根据日志判断根因、还原调用链或核对某次请求是否命中
不要用本技能写入、删除日志，或修改索引与 CLS 配置。
安装
把本目录放到 Agent 可加载的 skills 路径，例如：
- Cursor 个人技能：
~/.cursor/skills/tencent-cls-query/ - 项目技能：
.cursor/skills/tencent-cls-query/ - Claude Code：
~/.claude/skills/tencent-cls-query/
首次使用前配置只读 API 密钥，并指定要查询的日志主题。
安全约束
- 只调用
SearchLog，不得执行写入、删除、索引或配置变更。 - 凭证只从环境变量或本机钥匙串读取，禁止写入命令、代码、配置文件、仓库或回复。
- 不向用户索要控制台账号密码。使用仅有目标日志主题
cls:SearchLog权限的子账号密钥。 - 输出日志前遮蔽 token、密码、密钥、身份证号、手机号、邮箱等敏感字段。
- 不要把真实密钥或他人未授权的 Topic ID、检索链接提交到公开仓库。
- 查询命令可以使用完整检索词；写进对话的内容必须先脱敏，见「对话脱敏」。
默认行为
本技能不内置任何业务 Topic ID 或密钥。未覆盖时：
- 地域：
ap-beijing，可用环境变量TENCENTCLOUD_CLS_REGION或--region修改 - 日志主题：必须通过
--topic-id、控制台 URL，或环境变量TENCENTCLOUD_CLS_TOPIC_ID提供 - 时间范围：最近 1 小时
- 返回条数：100，单次最多 1000
用户给出的 URL、--region、--topic-id 优先于默认值。
查询流程
- 从用户描述提取请求 ID、Trace ID、错误码、用户标识等检索词。
- 若提供 CLS 控制台 URL，原样传给
--url；脚本会解析地域、Topic、时间和启用的筛选词。 - 若没有 URL，将检索词用
AND组合；不确定字段名时先做全文检索，不猜字段名。 - 范围先窄后宽：默认最近 1 小时；无结果再扩到 6 小时、24 小时。
- 在技能根目录执行：
scripts/run.sh \
--query '"request-id" AND "error"' \
--since 1h \
--topic-id '<日志主题 ID>'
或：
scripts/run.sh --url '<CLS 控制台检索页完整 URL>'
- 按时间顺序关联同一请求、Trace 或业务 ID 的上下文，区分根因日志与连带报错。
- 按「对话脱敏」汇报，不要把原始检索词或原始日志整段写进对话。
常用参数
--query STRING CLS CQL 检索语句
--url URL 腾讯云 CLS 控制台检索 URL
--since 30m|6h|2d 相对当前时间范围
--from TIME 起始时间，ISO 8601 或 Unix 毫秒
--to TIME 结束时间，ISO 8601 或 Unix 毫秒
--region REGION 覆盖地域（如 ap-beijing、ap-shanghai）
--topic-id ID 覆盖日志主题 ID
--limit N 返回条数，1-1000
--sort asc|desc 时间排序
--output json|jsonl 输出格式
首次配置
本技能不附带腾讯云密钥。请自行创建仅有目标日志主题 cls:SearchLog 只读权限的子账号，再在本机配置凭证。
方式一：macOS 钥匙串
密钥不会写入仓库：
scripts/setup-keychain.sh
脚本会分别提示输入 SecretId 和 SecretKey，输入内容不会回显。不要在对话、代码或配置文件中提供真实密钥。
方式二：环境变量
export TENCENTCLOUD_SECRET_ID='<SecretId>'
export TENCENTCLOUD_SECRET_KEY='<SecretKey>'
# 可选：默认地域，不填则使用 ap-beijing
export TENCENTCLOUD_CLS_REGION='ap-beijing'
# 可选：默认日志主题；不填则每次查询必须传 --topic-id 或控制台 URL
export TENCENTCLOUD_CLS_TOPIC_ID='<日志主题 ID>'
若使用 CAM 角色或 STS 临时密钥，再设置：
export TENCENTCLOUD_TOKEN='<临时密钥 Token>'
凭证读取优先级：环境变量 → macOS 钥匙串。
对话脱敏
查询脚本可以使用用户给出的完整检索词。回复用户时必须先脱敏，不得原样复述个人标识。
回复只包含：
- 时间范围
- 脱敏后的查询语句
- 命中数
- 关键时间线（个人标识已掩码）
- 根因判断、证据不足项、下一步
掩码规则：
- 手机号：
138****1234 - 身份证：保留前 6 位和后 4 位，中间用
* - 邮箱：保留前 1～2 位和域名，中间用
* - token、密码、密钥、cookie：写
***REDACTED***，不得出现原文 - 请求 ID / Trace ID：只保留本次排障直接相关的少量，不要罗列无关 ID
不要整段粘贴原始日志或脚本 stdout。只引用已脱敏的关键字段。用户已经提供过的手机号、身份证、邮箱，回复里也要掩码，不要再抄一遍。
无结果时
- 核对 Topic 和 Region 是否属于当前账号、当前日志主题。
- 查看脚本输出的实际检索语句，必要时去掉部分
AND条件。 - 依次扩大到
--since 6h、--since 24h。 - 若 API 返回无权限，停止重试，提示补充目标 Topic 的
cls:SearchLog权限。 - 若字段未建键值索引，改用全文检索，不修改线上索引。
