| name | log-analysis |
| description | 服务端日志智能分析与日志检索最佳实践 - 解读应用日志、JSON/structured logs、HTTP/access log、数据库慢查询、消息队列、定时任务、网关/代理和系统组件日志；适配本地文件、grep/rg/zgrep/jq 输出及主流日志平台线索。按 traceId/correlationId/requestId/spanId/线程/业务 ID 拆分链路，还原请求、任务、消息或批处理时间线，诊断报错、超时、慢调用、字段为空、数据不一致、重试降级、敏感信息泄露、日志质量、索引/标签/高基数和查询范围问题。用户粘贴日志、提供日志文件路径、贴查询结果、询问“分析日志”“查日志最佳实践”“帮我看下这段 log”“接口为什么慢”“为什么失败/超时/为空”“字段在哪一跳丢了”“日志里有没有报错”“怎么搜 trace”“慢查询/消息消费/access log/任务日志排查”时使用。 |
log-analysis：通用服务端日志智能分析
IRON LAW: 先回答用户真正问的问题；不要把日志分析写成逐行翻译或全景流水账。
将应用日志、网关/access log、数据库慢查询、消息消费、任务调度、系统组件日志等混杂文本拆成可读链路，恢复时间线，定位异常、性能瓶颈、字段丢失和跨服务不一致，并在证据不足时给出最小深挖命令。
执行清单
复制并逐项完成：
输入处理
支持直接粘贴日志、本地日志文件路径、命令输出片段、压缩日志的 grep/zgrep 结果。若路径在远程机器上，不要假设当前环境可读；请用户粘贴片段、上传文件，或先在远端执行过滤命令。
日志极大时先让用户缩小范围：优先按 trace/correlation id、业务 id、时间窗口、错误关键词或线程名过滤。不要默认读取或要求分析超大完整日志。
分析模式
聚焦模式
触发：用户问了具体问题，例如某接口为什么慢、某任务为什么失败、某请求为什么返回空、某时间段为什么报错。
行为：先给一段直接结论，再给证据链。仍需拆分全局链路以避免漏掉根因，但只展开与问题相关的链路；其他链路只在总览中一行带过。加载 references/report-templates.md 的聚焦模板。
字段溯源模式
触发：用户关注字段为空、丢失、错值、跨系统不一致、入参和出参不一致、数据库和接口结果不一致。
行为：加载 references/field-tracing.md。沿入口、网关/中间层、服务调用、数据库/缓存、消息/事件、响应组装逐跳标注字段状态。必须区分有值、空值、未打印、名称变化、来源不同、查错数据源。
快速概览模式
触发：用户没有具体问题，且日志少于约 100 行或独立链路不超过 2 条。
行为：加载 references/report-templates.md 的快速模板。输出概览、链路总览、问题（如有）和一句话结论。正常日志不要硬凑深挖命令。
深度诊断模式
触发：用户没有具体问题，且日志较多、链路较多，或用户传入 --deep。
行为：加载 references/analysis-playbook.md 和 references/report-templates.md。覆盖链路拓扑、异常分布、性能瓶颈、数据访问、外部依赖、重试/降级、日志质量和安全风险。
日志检索/查询优化模式
触发：用户问“怎么查日志”“怎么搜 trace”“日志查询最佳实践”“为什么搜不到”“查询太慢/结果太多/漏日志”，或当前日志不足以闭环需要设计下一步查询。
行为：加载 references/log-search-best-practices.md。先明确问题、时间窗、服务范围和可用字段，再给最小查询集合。优先使用结构化字段和关联 ID；对 Loki 标签、Elasticsearch 索引字段、Cloud Logging JSON 路径等平台能力给出平台相关建议；同时提醒高基数字段应作为结构化属性/元数据或查询字段，不应盲目提升为标签。
预期行为对齐
触发：用户问“有没有 bug”“逻辑是否正确”“是否符合需求”“为什么结果不对”等需要按预期判定的问题。
行为：从用户描述中提取可验证的判断标准；若预期不完整，先列出“暂定判断标准”并标注需要确认的点。分析日志时只判断日志事实是否违反这些标准，不把 200、SUCCESS 或无 ERROR 直接等同于逻辑正确。用户补充或修正预期后，必须按新标准重新判定。
分支路径分析
触发：日志中出现多分支逻辑、配置开关、版本判断、命中/未命中、fallback、降级、重试或短路返回。
行为：提取分支入口条件，例如配置、版本、状态、开关、命中结果或错误码；标注每个关键判断的结果：命中、未命中、跳过、fallback、短路、重试或降级；记录分支后的副作用：写库、发消息、调用下游、更新缓存或返回结果；用“条件 -> 分支 -> 副作用 -> 最终结果”输出。
手动参数
--quick：强制快速概览，除非日志不足以判断基本事实。--deep：强制深度诊断。--trace <id>：围绕指定 trace/correlation id 分析。--field <name>：进入字段溯源模式。--time-window <range>：只分析指定时间范围。--query-plan：只输出下一步日志检索方案和查询命令，不做完整诊断。
链路拆分优先级
- trace id / correlation id / request id / span id：最可靠。
- 线程名、协程名、任务名、消费者分区：适合同一执行上下文。
- 业务 id、实体 id、消息 id、批次 id：适合跨线程或跨服务关联。
- 时间窗口 + 语义连续性：兜底，需要标注不确定性。
同一线程可能复用处理多个请求；异步任务可能缺少 trace id；多服务日志可能格式不同。遇到这些情况时，说明归组依据和置信度。
诊断维度
按场景选择，不要机械展开所有维度：
- 失败诊断：错误级别、异常堆栈、失败计数、错误码、降级路径、最终状态。
- 性能诊断：端到端耗时、单步耗时、慢依赖、重复调用、排队/锁等待、批处理效率。
- 数据诊断：字段流转、空值来源、数据源差异、缓存与数据库不一致、写入与读取时间差。
- 依赖诊断：HTTP/RPC/消息/数据库/缓存/第三方调用的频次、耗时、状态和重试。
- 日志质量：关键字段缺失、上下文断裂、trace 丢失、敏感信息泄露、日志噪音。
- 检索质量：查询范围过宽、字段未结构化、标签/索引高基数、时间窗缺失、采样/轮转导致漏日志。
需要更细规则时加载 references/analysis-playbook.md。
深挖命令
只有在当前日志无法闭环时才输出。需要补齐具体证据命令时加载 references/grep-recipes.md；需要设计平台查询策略或解释查询质量问题时加载 references/log-search-best-practices.md。命令应优先限制 trace id、业务 id、时间窗口和文件范围；跨服务或大目录扫描必须加入 timeout、nice 或等价保护。
每条命令都必须说明“为什么查这个”。不要输出与用户问题无关的命令。
输出原则
- 结论先行：用户带问题时，报告开头直接回答。
- 证据驱动：每个判断都要能回指日志时间、字段、线程、trace 或关键片段。
- 量化表达：写“重复 17 次，总耗时约 680ms”，不要写“很多次”。
- 区分事实和推断：日志能证明的写事实，日志不足的写不确定性和下一步验证。
- 字段优先：结构化日志按字段查询和对比；文本日志才退回关键词、正则和时间邻近。
- 标准先行：用户问是否符合预期时，先列判断标准，再写事实对照和结论。
- 分支可见：链路包含分支、fallback、短路或配置开关时，写清实际走到哪个分支以及依据。
- 聚焦当前问题：其他疑点只列为次要风险，不抢主线。
- 引用敏感信息时保持最小必要；发现 token、密钥、手机号、证件号等，标注日志脱敏风险。
反模式
- 不要逐行翻译日志。
- 不要按日志级别堆列表而忽略请求/任务链路。
- 不要把“日志没打印字段”断言成“服务没收到字段”。
- 不要把下游空值处理当成最早根因。
- 不要在聚焦模式里展开所有无关链路。
- 不要给出无时间窗、无关键词、无保护的大范围 grep。
- 不要为了显得完整而输出与当前问题无关的 SQL、服务调用或安全分析。
- 不要在证据不足时写“根因就是”；改写为“当前日志支持的最可能原因是”并给验证命令。
- 不要把 HTTP 200、SUCCESS 或无 ERROR 直接判定为“逻辑没问题”。
- 用户补充或修正预期后，不要沿用旧结论；必须按新预期重新判定。
交付前检查
输出前逐项确认：
