企业官网建设流程全解析

本周工作概览

Agent已经能在人工确认下执行低风险操作，这周需要让整个“监控—分析—决策—执行”流程结束后，自动产出一份可供存档和复盘的结构化文档。另外，我也花了不少时间优化知识库的检索质量，并和前端同学一起完成了分析过程的时间线展示。

具体工作内容

事故复盘报告的数据模型设计

复盘报告不能只是一堆日志的堆砌，需要有清晰的章节结构和可读性。我先设计了一个IncidentReport的数据类，包含以下字段：incident_id（自动生成的时间戳加告警名）、alert_summary（原始告警的摘要）、time_line（关键时间点列表）、impact_scope（影响的服务和用户范围）、root_cause_analysis（根因分析结论和证据链）、actions_taken（人工确认执行的每一步操作）、recovery_result（恢复后的指标对比）、improvement_suggestions（改进建议）。这个结构覆盖了项目目标中提到的“监控指标变化、影响范围、处置过程、恢复结果和改进建议”。

为了能让Agent自动填充这些字段，我在系统提示词里增加了一个“报告生成模式”。当用户输入“生成复盘报告”或者故障处理流程自然结束时，Agent会切换到这个模式，不再调用外部工具，而是回顾整个会话的messages和collected_data，按模板逐段输出。输出格式要求是Markdown，方便直接复制到文档系统里。

时间线的自动提取与排序

复盘报告中最有价值的部分是时间线。一个完整的故障处理过程可能有多个时间点：告警触发时间、Agent开始分析时间、每个工具调用完成时间、用户确认操作时间、命令执行时间、指标恢复正常时间。这些时间点散落在不同的数据结构里——告警里有startsAt，工具调用日志里有timestamp，人工确认记录里有confirmed_at。

我写了一个TimelineExtractor工具函数，遍历AgentState中的每一条trace记录，从中提取带时间戳的事件，然后按时间排序。为了减少噪音，只保留“告警到达”、“分析节点开始/结束”、“工具调用完成”、“用户确认”、“命令执行”、“指标恢复”这几类事件。每个事件用一句话描述，例如“14:30:12 - 告警到达：CPU使用率98%”或者“14:31:05 - Agent调用PromQL查询，返回过去30分钟趋势”。最终生成的时间线是一个编号列表，放在报告的第二章节。

根因分析结论的格式化输出

之前Agent给出的根因分析是自然语言段落，不够结构化。这周我要求Agent在分析阶段就按照一个固定格式输出：候选根因（列出1到3个可能原因）、判断依据（每个原因对应的证据，如“PromQL查询显示连接池活跃连接数在14:28达到上限”、“日志检索发现120条connection timeout”）、验证步骤（如何进一步确认）。这个结构化输出不仅帮助用户理解，也方便后续直接填入复盘报告的根因分析章节。

一个具体的例子是之前的数据库连接池耗尽故障。Agent输出的根因分析包含：候选根因第一位是“数据库连接池配置过小或被突发流量打满”，判断依据中有“连接池活跃连接曲线在故障时刻触及maxActive阈值”和“日志中出现acquire timeout异常”，验证步骤是“查看连接池监控面板和当前活跃连接数”。这种格式比纯文本更有说服力。

知识库的故障案例沉淀

前几周知识库里只有提前录入的几个通用排查指南，这周我开始把每一次真实故障的处理过程作为新案例加入知识库。设计的流程是：每次复盘报告生成后，Agent会询问用户“是否将此案例保存到知识库？”如果用户同意，系统将报告中的alert_summary、root_cause_analysis、actions_taken和improvement_suggestions组合成一个新的文档，经过切片和向量化后存入Qdrant。同时我还加了一个简单的版本控制，每个案例有唯一的case_id和创建时间，避免重复保存。

为了提升检索时相关案例的召回率，我调整了文档的元数据结构。每个案例文档包含故障类型（如CPU、内存、磁盘、网络、数据库）、服务类型（核心服务或普通服务）、严重程度等标签。检索时不仅用向量相似度，还允许用户或Agent通过标签过滤。例如当收到数据库相关的告警时，Agent可以先过滤出故障类型=数据库的案例再计算相似度，结果更精准。

前端可视化展示的对接

这周前端同学完成了Web控制台的告警面板和分析过程展示页面，我需要把Agent输出的各种数据通过API传递给前端。我设计了一个/api/analysis/session/{session_id}接口，返回整个会话的完整状态，包括每一步的trace、工具调用记录、中间结论、最终报告等。前端用这个数据渲染出一个可折叠的时间线组件，用户点击每个步骤可以看到Agent当时的思考内容、调用的工具以及返回的结果摘要。

另一个展示重点是指标趋势图。前端的图表库需要原始时序数据，我在PromQL查询工具之外又封装了一个/api/metrics/query_range接口，前端可以直接传PromQL表达式和时间范围，拿到JSON格式的数据点数组。这个接口和Agent调用的底层是同一个PrometheusClient，但跳过了Agent的思考过程，专用于图表展示。这样用户在告警面板上可以手动查看任意指标的历史曲线，不依赖Agent触发。

报告生成的端到端测试

周五我们用上周那个磁盘清理的案例完整跑了一遍报告生成流程。故障结束后，用户在界面上点击“生成复盘报告”，Agent收到指令后回顾了整个会话：原始告警是/dev/sda1磁盘使用率87%，Agent调用了PromQL查询磁盘使用趋势和df -h工具确认，从知识库检索到清理旧日志的建议，用户确认执行find命令删除了超过7天的日志，再次查询后使用率降到62%。Agent把这些信息填进模板，生成了大约1500字的Markdown报告。

报告的时间线部分自动提取了7个事件点，从告警到达到最后指标恢复总共23分钟。根因分析写的是“/var/log/nginx目录下access.log滚动策略缺失，导致日志文件长期堆积”。改进建议包括“配置logrotate每周轮转”和“设置磁盘使用率低于75%的监控预警”。我把这份报告和之前人工写的复盘文档对比，发现Agent生成的版本在完整性和数据准确度上不输人工，而且省去了整理时间线和汇总操作记录的繁琐工作。

本周遇到的问题与解决

最大的问题是报告生成时的上下文长度。一个复杂的故障会话可能包含几十轮工具调用和思考记录，全部塞给模型会导致超过上下文窗口。我的解决方案是只把关键信息喂给模型，时间线只保留每个阶段的第一条和最后一条，工具调用只保留成功和失败的结果而不保留中间参数细节。另外改进建议这部分不依赖模型凭空生成，而是从知识库中检索相似案例的改进措施，再让模型改写适配当前场景。

另一个问题是时间戳的时区不一致。告警的startsAt是UTC+0，而前端展示和日志里用的是本地时间（UTC+8），导致时间线事件顺序看起来错乱。统一把所有时间戳在存入AgentState之前都转换成带时区信息的datetime对象，显示时再格式化为本地时间字符串。