用途：从实时 OpenTelemetry 遥测（traces、logs、metrics）调查并定位生产问题。Kopai 的分析能力（错误率、吞吐、延迟、group-by、时间序列分桶）位于 SDK 查询 API，CLI 未暴露，因此调查以编写简短 TypeScript 脚本为主，CLI 仅作快速查询备用。
前提：服务已向 Kopai 发送 OTel 数据；项目已安装 @kopai/sdk（npm i @kopai/sdk），它提供查询 API 与 .kopairc 读取器。
用法：用 clientFromConfig() 读取 .kopairc（先 ./.kopairc 再 ~/.kopairc，默认 http://localhost:8000），可用 npx tsx rca.mts 运行（.mts 始终为 ES 模块，支持顶层 await；无 tsx 时用 node --experimental-strip-types rca.mts）。用 kq 构建查询，client.query(q) 执行，返回类型化行；聚合查询返回 { data }，原始查询返回 { data, nextCursor }。结果以 console.log(JSON.stringify(data, null, 2)) 输出，并用 try/catch 捕获 KopaiQueryBuildError。
工作流：先按服务聚合错误率与吞吐找出问题服务，再取单个 trace 上下文（getTrace），关联日志（按 TraceId 查询），用时间序列分桶量化影响与起始时间，最后给出根因、证据、影响范围与修复建议。
限制与注意：每个查询都需时间窗口；StatusCode 为 "Unset"|"Ok"|"Error"（首字母大写），建议用 errorRate 度量；列名用 service.name（点号），ServiceName 不可查询；空结果常因列名或值大小写错误；百分位仅 ClickHouse 支持，SQLite 上会报错；Duration 过滤用带单位字符串，结果行仍为纳秒；指标查询需先选类型（Gauge/Sum/Histogram/ExponentialHistogram/Summary）；search* 为异步可迭代，limit 上限 10000，search* 过滤上限 1000。