模型读日志之前,先过一道规则
《ops-agent 建造笔记》第 15 篇(续篇分篇) 代码基线:v0.1.0-rc.4,提交
8dfa085(2026-11-09 候选版);前 13 篇仍固定 v0.1.0-rc.1 对照实现:agent/logscan.py、agent/tools.py的logscan工具定义与SCHEDULED_TOOLS续篇入口:文章锁在 rc.1,代码已经走到 rc.4
0. 第 2 篇的规矩,延伸到日志
第 2 篇讲巡检不交给模型判:固定探针、五种状态、采不到就留缺口,模型可以解释采样结果,但不能替规则下「正常」的结论。那条链路覆盖的是连通性、资源和服务。日志一直是个例外——排查时模型要自己翻 grep / tail 的输出,逐行读语义。
v0.1.0-rc.2 把这条思路补到了日志上,新增只读工具 logscan。agent/logscan.py 开头那句定位写得很直白:「模型读语义之前的规则第一道」。海量日志先按规则收口,模型只看聚类报告和少量样本,不逐行扫原始日志;输出即证据,每条结论附来源命令。
这不是为了让模型少干活。逐行把原始日志塞进上下文,成本高、脱敏难、还不可复核:一句「看起来没什么问题」没有留下可回看的依据。把第一道交给确定性规则,至少能说清「按什么规则收口、扫了多少行、哪些没扫到」。
1. 规则第一道具体做什么
三步,都在 agent/logscan.py 里,不依赖 API Key:
- 收口。按错误级别(
error优先warn,一行多命中取高级别)和关键词筛行。关键词覆盖 exception、traceback、failed、timeout、refused、denied、out of memory、reset by peer、非 0 退出码,以及 nginx access 里的 5xx 状态码。 - 聚类去重。把行首时间戳、IPv4、UUID、十六进制和数字归一化成
<ip>/<id>/<hex>/<n>一类占位符,同一故障的重复报错聚成一团,而不是一万条独立异常。 - 时间分布。能解析出行首时间戳(ISO/journalctl/docker、nginx、syslog 三种格式)就按 10 分钟分桶,解析不了退化为行号区间,让「什么时候开始变多」有据可查。
最后交给模型的,是 top N 个可疑聚类的少量样本(每行截断 200 字符)和行号/时间指针;想深挖某一团,再按指针去针对性复核。来源三选一:本机日志文件路径、journalctl 单元名、docker 容器名;since / until 限定时间窗,pattern 可再聚焦一层正则。远程目标只允许后两者——本机没法替远端核实一个文件路径。
工具 schema 里那句描述把边界写死了:「日志量大时先跑它,不要直接用 grep/tail 逐轮硬翻原始日志」。
2. 参数也是证据的一部分
一组默认值决定了这份报告能覆盖多少,所以它们必须露出来:
| 参数 | 默认 / 上限 | 为什么重要 |
|---|---|---|
lines |
200,000(1–2,000,000) | 默认只扫最近 N 行;故障定位通常有时间窗 |
top |
10(1–50) | 报告里给模型看的聚类数 |
| 扫描时间预算 | 30 秒 | 超时按部分扫描如实标注 |
| 聚类组上限 | 5000 | 全唯一行输入也不能无界占内存,超限如实标注截断 |
| 样本长度 | 200 字符/行 | 只给指针和片段,不给整本日志 |
「部分扫描」「截断」这些标注不是装饰。工具 schema 里还直接写着「无命中 ≠ 没问题」——粗筛规则之外的语义异常仍需针对性复核。这句和第 2 篇里「未配置 services 只能算不完整,不算正常」是同一条规矩:没采到、没扫完、规则没覆盖,都不能被一句「没有异常」盖过去。
路径命中敏感文件/目录规则时,和 read / bash 一样直接拒绝,连审计里也只留 logscan-deny;样本统一经脱敏出口。它被放进 tools.SCHEDULED_TOOLS,和 inspect 一起属于确定性检查,所以子代理和无人值守的定时上下文都能用——第 8 篇讲只读子代理的边界,第 6 篇讲无人值守只有只读工具集,这里没有为它们开新的写通道。
3. rc.4 补的是「采集失败」
规则再细,也得先保证喂给它的日志是真采到的。rc.4 的 R09 与发布前机器评审补了两处:
- 本机:日志采集原先只保留 stdout,
docker logs等写到 stderr 的错误日志会被静默丢掉;现在合并两路输出,非零退出统一按采集失败报错。 - 远程:复审发现共享远程采集函数还把「非零退出且带有错误输出」当成日志内容,一并改为拒绝;诊断摘要先脱敏,本机与远程入口保持一致。
对应的定向回归 5/5 通过,远程 Docker / journal 的非零输出回归先红后绿,正常输出保留。命令错误、输出不完整、采集中途失败,都不能被聚类成「日志里没有问题」——否则第一道规则越精细,越会给一个错误的结论提供可信的外表。
这一篇讲的是能力边界,不是验收结论。logscan 的回归与本机演练不能替代真实主机上的验收;本组续篇按 rc.4 口径,真实 SSH 恢复、断线 unknown 防重放、服务后验与修复版本七天观察仍未完成,证据表在第 17 篇。
对照源码与证据
- logscan:级别/关键词、聚类归一化、时间桶与部分扫描标注
- logscan 工具 schema、敏感路径拒绝与 SCHEDULED_TOOLS
- rc.2 发布说明(新增 logscan) · rc.4 发布说明(R09 与远程日志失败语义)
- 完整变更日志
系列总览 · 目录 · 续篇入口 · 上一篇:第五个壳,没有终端确认框 · 下一篇:批准一张变更单,不再是批准一条命令