
> 《ops-agent 建造笔记》第 15 篇（续篇分篇）
> 代码基线：[v0.1.0-rc.4](https://github.com/mengbin92/ops-agent/tree/v0.1.0-rc.4)，提交 `8dfa085`（2026-11-09 候选版）；前 13 篇仍固定 [v0.1.0-rc.1](https://github.com/mengbin92/ops-agent/tree/v0.1.0-rc.1)
> 对照实现：`agent/logscan.py`、`agent/tools.py` 的 `logscan` 工具定义与 `SCHEDULED_TOOLS`

---

## 0. 第 2 篇的规矩，延伸到日志

第 2 篇讲巡检不交给模型判：固定探针、五种状态、采不到就留缺口，模型可以解释采样结果，但不能替规则下「正常」的结论。那条链路覆盖的是连通性、资源和服务。日志一直是个例外——排查时模型要自己翻 `grep` / `tail` 的输出，逐行读语义。

`v0.1.0-rc.2` 把这条思路补到了日志上，新增只读工具 `logscan`。`agent/logscan.py` 开头那句定位写得很直白：「模型读语义之前的规则第一道」。海量日志先按规则收口，模型只看聚类报告和少量样本，不逐行扫原始日志；输出即证据，每条结论附来源命令。

这不是为了让模型少干活。逐行把原始日志塞进上下文，成本高、脱敏难、还不可复核：一句「看起来没什么问题」没有留下可回看的依据。把第一道交给确定性规则，至少能说清「按什么规则收口、扫了多少行、哪些没扫到」。

---

## 1. 规则第一道具体做什么

三步，都在 `agent/logscan.py` 里，不依赖 API Key：

1. **收口**。按错误级别（`error` 优先 `warn`，一行多命中取高级别）和关键词筛行。关键词覆盖 exception、traceback、failed、timeout、refused、denied、out of memory、reset by peer、非 0 退出码，以及 nginx access 里的 5xx 状态码。
2. **聚类去重**。把行首时间戳、IPv4、UUID、十六进制和数字归一化成 `<ip>` / `<id>` / `<hex>` / `<n>` 一类占位符，同一故障的重复报错聚成一团，而不是一万条独立异常。
3. **时间分布**。能解析出行首时间戳（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 篇](17-notify-and-acceptance.md)。

### 对照源码与证据

- [logscan：级别/关键词、聚类归一化、时间桶与部分扫描标注](https://github.com/mengbin92/ops-agent/blob/v0.1.0-rc.4/agent/logscan.py)
- [logscan 工具 schema、敏感路径拒绝与 SCHEDULED_TOOLS](https://github.com/mengbin92/ops-agent/blob/v0.1.0-rc.4/agent/tools.py)
- [rc.2 发布说明（新增 logscan）](https://github.com/mengbin92/ops-agent/blob/v0.1.0-rc.4/docs/releases/release-v0.1.0-rc.2.md) · [rc.4 发布说明（R09 与远程日志失败语义）](https://github.com/mengbin92/ops-agent/blob/v0.1.0-rc.4/docs/releases/release-v0.1.0-rc.4.md)
- [完整变更日志](https://github.com/mengbin92/ops-agent/blob/v0.1.0-rc.4/CHANGELOG.md)

《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

模型读日志之前，先过一道规则

《ops-agent 建造笔记》第 15 篇（续篇分篇） 代码基线：v0.1.0-rc.4

后端

人工智能

logscan工具作为规则第一道防线，通过收口、聚类去重和时间分布三步处理海量日志，确保模型仅读取聚类报告与样本。参数默认值、部分扫描标注及敏感路径拒绝均体现采集证据完整性。rc.4版本修复采集失败语义，合并输出并拒绝非零退出，确保日志真采性，强化确定性检查边界。

日志文件

容器

Docker

Nginx

Agent

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

模型读日志之前，先过一道规则-腾讯云开发者社区-腾讯云

模型读日志之前，先过一道规则

模型读日志之前，先过一道规则

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐