一、简介 ​

一键日志解析是 openUBMC Studio 提供的 BMC 现场日志离线分析工具，对应扩展 openubmc.bmcstudio-log-reviewer。它把 BMC 一键日志包（或已解压的 dump 目录）解析为一组可视化页面，覆盖硬件、告警、传感器、性能、调速、线缆与各类运行日志，并可结合 openUBMC RAG 进行 Agent 日志体检与告警链条分析。

本文档面向使用 openUBMC Studio 定位现场问题的开发者与运维支持人员。

使用方式总览 ​

二、使用前准备 ​

前置条件：

• 已安装 openUBMC Studio 最新版（获取方法参见《openUBMC Studio 安装指南》）。
• 已安装一键日志解析插件（随 openUBMC Studio 扩展包分发）。
• 本文功能说明与数据字段基于一键日志解析插件解析的日志包验证。

如果活动栏中没有“一键日志解析”图标，请先安装插件：

1. 在 openUBMC Studio 的插件市场搜索 openUBMC 一键日志解析 并安装，按提示重新加载窗口。
2. 确认活动栏出现标题为 一键日志解析 的图标。

使用 Agent 日志体检还需满足以下条件：

• 已登录 openUBMC 社区（登录步骤见《openUBMC Studio 用户指南》“三、登录到社区”）。
• openubmc-rag 扩展已启用。
• 当前网络可以访问配置的 LightRAG 服务。
• AI Agent 可以访问 openUBMC Studio MCP 工具。

三、导入日志 ​

支持导入以下内容：

• .tar.gz、.tgz、.tar 或 .zip 格式的 BMC 一键日志压缩包。
• 已解压且包含 AppDump 子目录的 dump 目录。

日志包典型结构如下：

dump_info/
├── AppDump/
├── LogDump/
├── RTOSDump/
└── OSDump/

操作步骤如下：

1. 单击活动栏中的“一键日志解析”图标。

2. 根据日志形态，选择 打开 BMC 一键日志压缩包 或 打开 BMC 一键日志。

3. 选中压缩包，或包含 AppDump 的 dump 根目录。

4. 等待解压与解析完成，日志页面在编辑器区域打开。

也可以通过以下入口打开日志：

• 在资源管理器中右键单击日志压缩包或 dump 文件夹，选择对应的一键日志解析命令。
• 单击“最近打开”中的历史记录，重新打开对应日志。

导入失败常见于扩展名不支持或解压异常，日志包缺 AppDump 也会导致导入失败（见下方“目录缺失的影响”）；导入成功但页面数据不全时另见“解析限制”。

解析限制 ​

目录缺失的影响 ​

导入完成后，可用 Agent 日志体检 快速定位问题，或翻阅 可视化页面 人工核查。

四、界面与通用规则 ​

导航结构 ​

本文涉及三个层级：页签指顶部的 14 个一级入口（其中“其他功能”本身不展示内容，只作下级页面容器）；子页面指“其他功能”下的各页面；子页签指个别页面内部的第二层切换（如操作日志、调速信息、性能信息、首页存储详情面板内部）。

• 一级页签原文：首页、FRU信息、告警信息、传感器信息、操作日志、板卡及版本信息、调速信息、性能信息、统计信息、🔍 智能检测、🔌 线缆检测、🔗 同步属性、一键日志原始文件、其他功能（其中 3 个页签标签内带 emoji 图标，首页另带独立首页图标）。
• “其他功能”子页面原文：框架日志、维护日志、app日志、串口日志、驱动日志、journalctl、CSR原始文件、丝印文件、故障诊断。

各节标题与对应页签同指一页。

文中“侧边栏”有两处含义，请勿混淆：IDE 侧边栏的“最近打开”视图用于重新打开、刷新与清空历史；页面左侧栏只在“其他功能”（切换子页面）和支持保存搜索的视图（显示“已保存搜索”面板）中出现。

顶部状态区 ​

检索控件 ​

页面通常有两条检索条：筛选条（如 筛选传感器名称...）隐藏不匹配内容，搜索高亮条（搜索高亮...）只标记不隐藏。匹配计数有三种显示形式：N处匹配 (i/N)、i/N、预览面板中的 N 处匹配。

保存搜索 ​

• 支持该功能的视图共 11 个：告警信息、传感器信息、操作日志、一键日志原始文件、框架日志、维护日志、app 日志、串口日志、驱动日志、CSR 原始文件、故障诊断。丝印文件、journalctl、同步属性等页面没有该按钮。
• 不需要命名，标签由检索词自动生成（超长截断）；按文件保存的页面标签带文件名前缀，恢复时自动展开对应文件。
• 面板中的记录会带页面简称，与页签名称不完全一致：告警（告警信息）、传感器（传感器信息）、文件树（一键日志原始文件）、串口（串口日志）、驱动（驱动日志）、CSR（CSR 原始文件）等，单击记录会跳到对应页面。
• 最多 20 条，超出后保存不生效且无提示；同页面相同检索词覆盖旧记录。面板标题为 已保存搜索 (N/20)（N 为已保存条数），空列表提示 点击搜索条右侧 📌 按钮保存。
• 记录存于本机浏览器本地存储，与日志包无关，换机器或清除本地数据后不保留。
• CSR 原始文件页保存的检索条件不含匹配片段，其预览区显示 无预览数据，请点击"在页面中查看"，需单击该按钮后才能看到内容。

分页与每页条数 ​

分页条在列表上方，形式为“首页 / 上一页 / 当前页-总页数 / 下一页 / 末页”加页码跳转框；没有每页条数选择器，页码越界自动钳制到首尾页。

表头不支持单击排序，列头也不会弹出筛选面板；行顺序由解析逻辑固定。

截断与数据量上限 ​

空态、错误态与加载态 ​

空态提示由图标与文字两部分组成，本文“提示文案”只给文字本体（⚠ 与 ✅ 开头的属于文案本身）；同一图标在不同页面复用，不能凭图标判断页面。部分页面在目录缺失时不报错而返回空结果（框架日志、维护日志、app 日志、同步属性）。出现具体“缺少 xxx 目录/文件”字样才是读取失败，只有“无数据”类文案说明该日志本身为空。

数据取值约定 ​

单击时间戳联动应用日志 ​

告警信息、操作日志、性能信息、框架日志、维护日志、journalctl 页面的时间可单击，打开“应用日志”抽屉查看该时刻前后日志：锚点取时间差最小的条目并自动滚动定位；初始展示锚点前后各约 300 条，滚动接近边缘时两侧各再扩展约 200 条；锚点与目标相差超过 1 小时时提示 ⚠ 目标时间超出app.log范围，显示最近可用条目。；宽度可拖拽（320～1200 像素，默认 460，本机持久化）；× 或遮罩关闭。

BMC 时钟未同步时日志时间戳为 1970 年，此时向上取最近一条非 1970 时间作为锚点，并在标题保留原始 1970 时间，属预期行为。

机型档案 ​

解析器按机型档案适配细节：读取 FRU 信息判定机型，命中已登记机型使用专用档案，否则使用“通用机型”档案。

加载与缓存 ​

同一日志包、同一查询条件的重复请求命中解析结果缓存（按最近使用保留 32 项），不重新读取文件——改完日志内容必须重新导入才会生效。只有成功的结果会被缓存：返回“缺少文件/目录”这类错误的请求不缓存，按目录导入的日志包补好缺失文件后再次请求即可读到内容。页面只显示日志包内相对路径与文件名，不回显宿主机绝对路径。

五、页面速查 ​

六、各页面功能说明 ​

首页（现场概览） ​

• 设备信息 7 项：产品序列号、主机名（优先完整域名）、iBMC固件版本、MAC地址、全局唯一标识符（优先 GUID 回退 UUID）、BIOS固件版本、BIOS固件发布日期。
• 资源表“在位”列只统计在位条目；“补充信息”列仅内存（N GiB）与存储（RAID卡: N 物理盘: N 逻辑盘: N）有值。
• 六个资源详情（处理器、内存、存储、电源、风扇、网络适配器）在单击资源表行的详情入口后于页面内展开，首次打开才解析。
• 详情页字段翻译不统一：只有电源详情页把字段名映射为中文标签（在位状态、额定功率、输入输出电压、部件编码等，未收录字段回退原始字段名）；风扇与网络适配器详情页直接按解析结果字段名展示（不翻译），空值与 Unknown 不显示，因此不同机型字段清单不同。处理器与内存列表只展示在位条目，其“状态”列恒为“在位”。
• 换算规则：主频 ≥1000MHz 显示 GHz；内存容量 ≥1024MiB 显示 GB；网卡速率 ≥1000Mbps 显示 Gbps，无效值显示 --；磁盘容量按 TB/GB/MiB 自动换算，异常值显示 --。
• 存储详情含 存储信息 与 RAID日志 两个子页签，每次进入默认回到 存储信息。解析结果包含逻辑卷与磁盘阵列数据，页面未提供展示入口。

数据来源：AppDump/product_mgmt、bmc_network、firmware_mgmt、compute、storage、power_mgmt、thermal_mgmt、network_adapter、event；电源数量与产品名称、序列号、制造商另取 AppDump/frudata/fruinfo.txt。

提示文案：暂无资源信息、无处理器数据、无内存数据、未找到存储信息、无RAID日志、无电源数据、无风扇数据、未找到网卡信息；网卡数据解析异常时显示 解析网卡信息失败。

FRU 信息 ​

• FRU 字段按原始英文字段名展示（不翻译），空值字段不显示；扩展信息优先拆出描述、问题编号、CLEI 码、BOM、型号，无法识别时整串作为 Raw 显示。
• 设备卡片默认全部收起；设备 ID 为 0 的 BMC 记录排在列表最后。
• 架构图由 FRU 数据动态生成，按名称与描述关键词归类为 硬盘背板、风扇板、CPU板、扩展板、Riser、电源、网卡、BMC、PCIe卡，未识别类型不进入架构图；日志加载完成后会自动弹出一次，可用 × 或点遮罩关闭，获取失败时不显示入口且不影响其余 FRU 内容。

数据来源：AppDump/frudata/fruinfo.txt，架构图另用 AppDump/pcie_device/mdb_info.log。

提示文案：未找到 FRU 信息；缺少文件时 fruinfo.txt not found。

告警信息 ​

• 一次查询同时返回当前告警与历史 SEL 首页数据；当前告警不分页，历史 SEL 每页 50 条。
• 级别归类规则：级别文本含 critical 归紧急、含 major 归严重、含 minor 或 warning 归轻微、含 normal 归正常，无法归类不着色。
• 描述恰为 System in health state. 的当前告警行被当作健康占位过滤，不显示。
• 行筛选命中任一单元格即保留该行；搜索高亮只标记不隐藏。

数据来源：AppDump/event 下的当前告警文件与 SEL 记录文件（含 .gz）。

提示文案：系统运行正常，无当前告警、无匹配的告警、无系统事件记录、无匹配的事件、缺少event目录。

传感器信息 ​

• 表格列按日志表头动态生成，不同日志包的列集合可能不同；未收录的表头直接按英文原样显示。固定列映射为 sensor id→ID、sensor name→名称、value→值、unit→单位、status→状态、category→类别。
• 门限与迟滞量列有缩写与全称两套表头写法，映射到同一中文列名：

“紧急”档只由缩写 lnr/unr 产生：全称 critical 与 major 都映射到“严重”，因此看到“严重上门限”并不等于日志里没有 non-recoverable 门限。

• “类别”列由单位判定（degrees C→温度、Volts→电压、Amps→电流、Watts→功率、RPM→风扇转速、discrete→离散），无法判定归入其他；类别筛选按此顺序展示。
• 类别内出现既非 ok 也非 na 的状态记录时，该类别统计卡左侧标红边。
• 名称筛选占位符写作“筛选传感器名称...”，实际按全部单元格内容匹配。
• 不分页，全部记录在固定高度区域内滚动。

数据来源：AppDump/sensor/sensor_info.txt。

提示文案：未找到传感器信息、无匹配的传感器、缺少sensor/sensor_info.txt文件。

操作日志 ​

• 两个子页签数据源相互独立：操作日志解析自文本行，命令行历史读取各用户的 shell 历史文件，二者无字段级关联。
• 方式列配色：CLI 紫、WEB 蓝、Redfish 橙，其他（如 SSH）默认色；方式与模块为空时归入 other。
• 行筛选只作用于“操作详情”列，搜索高亮作用于全列并在跨页命中时自动翻页定位。
• 轮转文件按名称倒序读取（旧文件在前）；命令行历史子页签未点开时显示 无命令行历史记录，点开后才读取。

数据来源：LogDump/operation.log*（.gz 自动解压）；RTOSDump/other_info/command_records/<用户>/ash_history。

提示文案：无操作日志记录、无命令行历史记录、缺少command_records目录。

板卡及版本信息 ​

• 分区标题按固定映射翻译（iBMC 信息、产品信息、Riser 卡信息、硬盘背板信息、CPU 板信息、扩展板信息、风扇板信息、PCIe 卡信息、电源信息、VRD信息），未收录的分区名按原始英文显示（例如网卡信息分区）。
• 分区内可识别为板卡的条目成卡展示（板卡名称、板卡ID、唯一标识、PCB/CSR/MCU/FPGA/CPLD/BIOS/固件版本、双 CPLD 与双 FPGA 版本、类型、制造商、产品名称、PCIe带宽、VRD版本），其余属性按原始英文键名平铺。
• 默认只展开第一个分区；app组件版本信息默认收起，其数据文件缺失时整段隐藏且不报错。组件版本串包含版本号、分支、提交标识与时间戳。

数据来源：RTOSDump/versioninfo/app_revision.txt、RTOSDump/versioninfo/package_info。

提示文案：无版本数据；缺少数据文件时提示 缺少RTOSDump/versioninfo/package_info文件。

调速信息 ​

三个子页签的数据源各不相同，按子页签分述如下。

风扇调速 ​

• 风扇 PWM 原始量程与换算、着色规则见数据取值约定。
• 打点明细有数量上限，统计卡“数据条数”按全量统计——需要完整打点时到“一键日志原始文件”页看原始文件（上限见截断与数据量上限）。
• 仅当日志文件多于 1 个时才出现 日志文件 (N个) 选择区。

数据来源：LogDump/cooling_control*。

提示文案：无调速数据、（当前筛选无数据）、缺少LogDump目录、缺少cooling_control日志文件、无法读取日志文件。

PID 配置下发记录 ​

• 记录按每页 15 条分页展示下发动作。
• 记录中的环温调速曲线为静态图，不支持悬浮与缩放；曲线点全部无效时提示 ⚠ 此温区无有效调速曲线（全部点为哨兵值，可能为禁用/复位信号）。

数据来源：LogDump/app.log* 中的配置下发记录。

提示文案：无PID配置下发记录。

CoolingPolicy 生效情况 ​

• 策略类型按取值显示为 1 (InletCustom)、2 (DiskCustom)、4294967295 (InvalidType)，未收录取值按原始数字显示；生效状态为“生效”或“不生效”。
• 条件与区间列过长会省略，可悬浮查看，空值显示 -；区间数组超过 6 个时显示前 3 个 + 省略号 + 后 3 个。

数据来源：AppDump/cooling/mdb_info.log 与 AppDump/thermal_mgmt/mdb_info.log。

提示文案：无CoolingPolicy数据。

性能信息 ​

四个子页签的数据源各不相同，按子页签分述如下。

CPU 使用率 ​

• 打点记录每页 500 条，超限事件与打点同源。
• 单 bit ECC 提示由总内存与 1700MiB 比较得出：总内存低于 1700MiB 时显示 该环境已开启单bit ECC (总内存 N MiB < 1700)，否则显示 该环境未开启单bit ECC (总内存 N MiB ≥ 1700)。该比较阈值无明确业务依据，判断 ECC 配置请以机型内存规格为准。
• 占用率着色规则见数据取值约定。

数据来源：LogDump/bmc_health*（文件名需含 bmc_health 且带 .log 或 .gz）。

提示文案：无性能数据、⚠ <原因> 请调整时间范围后重新筛选、缺少bmc_health日志文件、bmc_health日志无有效数据、筛选范围内无数据、无法读取日志文件。

内存监控 ​

首次点开该子页签才解析。

数据来源：LogDump/mem_info_<服务名>.csv，服务名取自文件名。

提示文案：无内存监控数据。

Top 信息 ​

进程快照，按日志采集时刻原样展示，首次点开该子页签才解析。

数据来源：RTOSDump/sysinfo/top_info。

提示文案：缺少top_info文件。

启动耗时 ​

• 甘特图按秒刻度绘制，组件行可展开查看资源位置与对象组上树时间。
• 启动周期下拉项由“启动时间 + (第N次)”拼接而成，最后一项追加 ← 最近。时钟未同步时启动时间本身已变成 (未同步) 第N次，拼接后该选项里会出现两次次数（如 (未同步) 第3次 (第3次)），时间列则显示 (未同步到时间)。
• 首次点开该子页签才解析。

数据来源：LogDump/framework.log* 与 LogDump/app.log* 中的启动与上树记录。

提示文案：无启动耗时数据。

统计信息 ​

• 页面为两张入口卡片，单击后才加载对应区块。本页卡片名写作 入风口温度，而首页占位标签写作 进风口温度，两处指同一数据。
• 统计卡数值由页面按当前时间筛选范围重新计算；修改起止时间后同步变化。
• 时间筛选按整分钟区间比较，起止分钟均包含在内；首次加载按数据首末时间预填，重置 清空。
• 图例可点选隐藏某一功率系列，图表不支持缩放；横轴不显示年份。
• 本页不提供关键字筛选、搜索高亮与保存搜索。

数据来源：功率统计取 AppDump/power_strategy/power_statistics.csv，入风口温度取 AppDump/cooling/env_web_view.dat。

提示文案：所选时间范围内无功率数据、所选时间范围内无温度数据、缺少power_statistics.csv、缺少env_web_view.dat。

智能检测 ​

• 本页数据来自 Agent 日志体检的分析结果，不是从日志包直接解析；分析操作与结果字段含义见 Agent 日志体检。
• 结构化诊断按前后 5 分钟的时间窗口回溯关联错误日志，超出窗口或模块不匹配时给出结论性提示，而不是留空。
• 状态与按钮可用性：

• RAG 来源可信度显示为三档：非常高（故障案例库）、较高（含故障案例库）、一般（其他知识来源）。
• “复制 Prompt 模板”先弹出“补充分析信息”对话框：问题描述与相关代码仓均为选填（描述最长 4000 字符、仓库地址每行一个最多 5 个），描述框提示语为 请描述异常现象、发生条件、期望结果与实际差异，可补充分支或固件版本。，可“跳过并复制”。
• 窗口宽度不足时先隐藏置信度条，再隐藏得分条，不影响问题内容。
• 复制与重新分析的取消反馈：复制状态异常时提示 Prompt 未复制，请重试；取消保存对话框后分别提示 已取消导出、已取消重新分析。

数据来源：分析会话数据（来自 Agent 日志体检），问题证据关联 AppDump/event 与 AppDump/fault_diagnosis。

提示文案：等待 Agent 分析结果、本次分析未生成问题报告；失败状态下建议语为 解决失败原因后点击“重新分析”，再复制新的 Prompt 模板。。结构化诊断找不到关联日志时提示 未在前后5分钟内找到关联错误日志 (模块=N)、无法确定采集时间、检测时间范围无效、该操作可能未产生app日志，或app日志已被轮转 或 该操作可能因非模块错误导致(如超时、网络断开)，检查操作日志详情。

线缆检测 ​

• 五个统计卡：总线缆端口、匹配成功、插错、缺失、不在位。插错与不在位大于 0 变红、缺失大于 0 变橙。
• 状态取值与释义：

• 建议面板按状态生成：端口插错给出期望槽位；端口缺失建议把对应端口线缆插入该槽位；槽位期望连接但无任何线缆时给出槽位级告警；必需组件不在位时区分两种建议——线缆已连但卡位错（形如 <组件>→线缆已连接(<端口>)，但卡不在<槽位>槽位，请检查卡是否安装）与未检测到线缆。
• 接线图为按机型预置的固定节点与连线，节点可拖动；非该机型时此图含义不适用，请以 📡 BCU端口实际连接 与 📋 槽位白名单配置 两张表为准。
• 机型档案会豁免特定组件的缺位告警，见机型档案。
• 本页不提供关键字筛选、搜索高亮与保存搜索。

数据来源：AppDump/pcie_device/cable_info 与 AppDump/pcie_device/mdb_info.log。

提示文案：未找到线缆检测数据、cable_info not found；全部正常时 ✅ 所有UBC线缆连接正确。

同步属性 ​

• 每行是一个同步属性记录，展开后可见各源参数的来源服务、对象路径、接口.属性、历史值序列、更新时间序列与逐次更新方式。
• 更新方式取值与含义：主动（按需或周期读取源属性）、信号（源属性变化上报）、上树（源对象上树时触发）。页面说明框给出的组合判读：仅主动为“⚠ 被动”、主动+信号为“● 健康”、主动+上树+信号为“● 完整”。
• 值振荡判定：某源参数历史值不少于 3 个且相邻取值不同不少于 2 处，异常行整行淡红底并在展开区提示 ⚠ 值振荡（历史值交替变化）。
• 表达式超过 40 字符省略，悬浮查看完整内容；多条表达式逗号分隔。
• 每页 500 条；任一筛选条件变化会重置页码并收起展开行。
• 日志包缺少对应目录时返回空结果（不报错），页面显示无数据。

数据来源：AppDump/<组件目录>/sync_property_trace.log。

提示文案：未找到同步属性 Trace。

一键日志原始文件 ​

• 目录树徽标：目录为直接子项个数，文件为格式化大小；树筛选按名称子串匹配（忽略大小写），命中时自动展开全部父级。
• 文件标题栏显示大小与行数；行数按已加载内容统计，大文件会因读取上限偏少于真实值（见截断与数据量上限）。
• 每个文件保留各自的搜索条件，切换文件时自动恢复。
• 本页不提供复制与下载入口，需要导出原文请用系统工具打开文件。

数据来源：日志包根目录下全部文件。

提示文案：未找到日志目录、选择左侧文件查看内容、Invalid path、Cannot read file、Not found。

其他功能 ​

“其他功能”页签含 9 个子页面，其中 7 个（框架日志、维护日志、app 日志、串口日志、驱动日志、CSR 原始文件、故障诊断）使用同一类日志浏览器（本文对这类共用同一套文件卡片与检索条的页面的统称）。该浏览器由四部分组成：折叠的文件选择卡片（勾选后“确认加载”）、筛选条（隐藏不匹配内容）、搜索高亮条（只标记不隐藏）、保存搜索（支持范围见保存搜索）。各子页面的差异如下：

CSR 原始文件为合并视图 ​

同名主文件（<名称>.sr）与软件叠加文件（<名称>_soft.sr）合并，主文件的对象定义覆盖叠加文件，并在文件名后标注 (已合并_soft.sr)；存在同名 .sr 时不再展示其二进制导出文件 .bin；只有 .bin 时尝试解压还原出 JSON 并标注 (解压)。因此页面上看不到单独的叠加文件条目。文件卡片标注对象数与行数，展开后可文件内搜索与复制全文。

七、AI 辅助分析 ​

Agent 日志体检 ​

日志体检将本地日志证据与 openUBMC RAG 检索结果关联，按严重程度、紧急度和置信度排列问题。故障案例库是可信度最高的知识来源，但不是唯一可用来源。

日志体检的整体流程：智能检测页“复制 Prompt 模板”→ 交给能访问 openUBMC Studio MCP 的 AI Agent → Agent 调用 openUBMC RAG 检索故障案例并实时回写问题到“Agent 日志问题”区域 → 完成后按 TopN 截取、稳定排序，再“导出 PDF 报告”生成可复核结论。

复制分析 Prompt ​

1. 打开日志页面顶部的“智能检测”（页面构成见智能检测）。
2. 单击“复制 Prompt 模板”，可在弹出的“补充分析信息”对话框中补充线索（见智能检测），或直接“跳过并复制”。
3. 将 Prompt 粘贴到能够访问 openUBMC Studio MCP 工具的 AI Agent 中并发送。
4. 等待 AI Agent 完成 RAG 状态检查并开始分析。复制成功后页面提示 Prompt 模板已复制，请粘贴给 Agent 开始分析；新建任务时提示 已创建新的分析任务，请复制 Prompt 模板后交给 Agent。

Prompt 已自带以下约束，无需手动填写日志路径：只允许读取当前分析任务绑定的日志包；必须先检查 RAG 连接与社区登录状态；必须保留 RAG 引用的真实来源；每个问题必须同时给出 RAG 匹配内容与本地日志证据；完成后按用户配置的 TopN 返回结果。

MCP 工具调用失败时以短语返回原因（打开失败、取数失败、查询失败、回调失败: N、分析任务不存在或已关闭），AI Agent 会据此提示下一步。

查看实时问题 ​

分析期间每个已确认的问题会实时显示在“Agent 日志问题”区域，问题卡片包含：

同一根因产生的重复现象会合并为一个问题；分析完成后按严重程度、紧急度、置信度排序，展示最紧急的 TopN 问题。

Agent 回写的每条问题都要通过字段校验（严重程度、紧急度、置信度、事件标识与证据字段均需合规）。校验不通过时该条写入被拒绝，页面不会出现这个问题。

配置 TopN ​

默认 10，可设 1～50，设置方法见命令与设置项。TopN 只限制分析完成后页面与 PDF 报告中展示的问题数量，Agent 可在分析过程中回写更多候选问题，插件在完成时统一排序与截取。已创建的分析会话沿用创建时的取值。

导出 PDF 报告 ​

仅在状态为“已完成”时可用（页面显示 分析状态：已完成）。选择保存路径后提示 PDF 报告已导出: <路径>（取消时的提示见智能检测）。导出后核对摘要、问题排序、RAG 内容、日志证据与处理建议。报告在扩展宿主运行期间可持续导出；完全关闭或重启 Studio 后内存中的分析会话不保留，需重新发起分析。

会话异常处理 ​

定向诊断 ​

在 AI Agent 对话中提供日志路径与分析目标即可，例如：

请打开并诊断 /path/to/bmc-log.tar.gz，先给出设备健康概览、关键异常和对应证据位置。

Studio 会打开同一份日志的可视化面板，并把结构化数据交给 Agent。若 Agent 跳过打开步骤直接调用读取类工具，会得到要求先调用 log_reviewer_open 打开日志包的提示，让它先打开日志包即可。可继续要求聚焦某个领域，再回到对应页面复核：

继续分析当前日志中的散热异常，关联传感器、调速策略、功率和相关运行日志。

告警链条分析 ​

分析单条告警时，建议提供以下任一组定位信息：

• 事件码与发生时间。事件码格式为 0x 后接 8 位十六进制数字，时间格式为 YYYY-MM-DD HH:mm:ss。
• sel.txt 中的事件记录 ID，可据此解析事件码与发生时间。
• 需要区分多个告警实例时，再补充组件或实例名称。

示例：

基于当前打开的一键日志，分析事件码 0x12345678、时间 2026-08-28 14:23:16 的完整告警触发链。
请说明当前告警状态、已观察到和缺失的阶段、恢复与复发情况，并在每个节点标注证据文件及行号或数据库记录位置。

Agent 会根据日志中的实际证据给出：唯一告警锚点（即在日志中锁定到的那条告警记录）及匹配方式；当前状态（active、inactive、conflicted、unknown）及状态依据；已观察到的触发流程（采样、数值转换、门限或事件规则求值、事件存储、北向上报），未采集到的阶段标记为缺失；运行期事件与 dump 内 .sr 文件中 CSR Event/PowerEvent 定义的关联结果；恢复配对、复发次数下界、历史覆盖范围与可能的时钟跳变；每个关键事实的相对路径、行号、列号、JSON Pointer 或数据库定位。

八、命令与设置项 ​

设置项 ​

设置入口为 IDE 侧边栏“最近打开”视图标题栏的齿轮按钮，单击后在编辑器中打开设置页并定位到 bmcstudio.logReviewer 相关配置项。

命令与入口 ​

“命令面板可见”按插件的 commandPalette 规则判定：刷新最近打开、打开最近的 dump、从最近打开中移除 被显式隐藏，只能从界面按钮或菜单触发。扩展未注册独立快捷键。

九、数据范围与安全边界 ​

• AI Agent 日志工具只能访问分析任务绑定的日志包，不会自动选择其他历史日志。
• 日志证据使用日志包内相对路径，不回显宿主机绝对路径；解压产生的临时目录位于系统临时目录（前缀 bmc-log-），由插件管理。
• 日志体检唯一允许访问的外部知识是 openUBMC RAG 状态与知识检索结果。
• tar 系列导入会拒绝路径逃逸、绝对路径与解压炸弹，并忽略符号链接、硬链接与设备文件。
• PDF 报告只包含当前分析会话中的摘要、TopN 问题、RAG 依据与日志证据。
• 保存搜索与抽屉宽度等偏好存于本机浏览器本地存储，与日志包无关。

十、常见问题 ​

Q1：导入失败并提示文件可能不是 openUBMC 一键日志包 ​

日志包内未找到 AppDump 目录。按提示的“顶层内容”或“路径”核对目录层级——压缩包内需含 AppDump，或直接选中包含该目录的 dump 根目录后重新导入。详见导入日志。

Q2：页面显示“缺少 xxx 目录/文件”与“无数据”有什么区别 ​

“缺少 xxx 目录/文件”表示该目录确实不在日志包内（读取失败）；“无数据”表示数据源存在但无匹配内容（多为日志为空或筛选过窄）。先清筛选与搜索条件，仍空则对照各页面功能说明中该页的数据来源核对依赖的目录。

Q3：文件内容只显示一部分，行数与真实文件不符 ​

“一键日志原始文件”与串口日志均有读取/展示上限，故正文与行数会偏少于真实文件。用筛选缩小范围，或用系统工具直接打开原文。详见截断与数据量上限。

Q4：调速信息里某个风扇的明细少于统计卡数值 ​

属预期：调速每设备打点明细有数量上限，统计卡“数据条数”按全量统计，故明细可少于统计值。需完整数据时到“一键日志原始文件”页查看对应 cooling_control 文件。详见截断与数据量上限。

Q5：修改 TopN 后结果数量未变化，或重启 Studio 后分析结果丢失 ​

TopN 仅对新分析会话生效——需从“最近打开”删除该日志重新导入并发起分析；分析结果存于扩展宿主内存，Studio 完全重启后不保留，需重新发起或提前导出 PDF 报告。详见命令与设置项与 Agent 日志体检。

Q6：保存搜索没有生效 ​

保存搜索有数量上限且超出静默失败、无提示；同一页面相同检索词会覆盖旧记录，看起来像“没新增”。在“已保存搜索”面板清部分记录后重存。详见保存搜索。

Q7：顶部显示电源状态为上电且无告警，但现场明明有告警 ​

一键日志包不保存上电状态与指示灯历史值，顶部按固定值展示、不反映采集时刻；顶部告警数取自 AppDump/event。以告警信息页的当前告警与历史 SEL 为准，两页皆空则检查日志包是否缺 AppDump/event。

Q8：改过日志包内容或换了日志包，页面却没有变化 ​

同一日志包、同一查询命中解析结果缓存，不重新读文件。从“最近打开”删除该日志后重新导入，或直接导入新日志包。详见加载与缓存。

Q9：顶部页签、保存搜索按钮找不到，或接线图与现场接线对不上 ​

保存搜索并非所有视图支持；接线图为按机型预置的固定节点，非该机型时不适用。接线图以 📡 BCU端口实际连接、📋 槽位白名单配置 两表为准，并先核对机型档案。详见保存搜索。

Q10：AI Agent 报找不到分析任务或回调失败，页面一直没有问题 ​

Agent 可能报“分析任务不存在”或回调失败。原因：任务标识与回调地址仅在日志页面打开且回调可达扩展宿主时有效，页面关闭、Studio 重启或用旧 Prompt 都会让回调失败，回环地址被代理改写时回调返回非 JSON。处理：保持页面打开、重新复制 Prompt；将 localhost、127.0.0.0/8、::1 加入代理直连或 NO_PROXY 后重启 Studio 与 Agent；仍无结果则核对社区登录、openubmc-rag 扩展与 LightRAG 可达性。详见 Agent 日志体检。

十一、附录 ​

术语 ​

相关文档 ​

• 《openUBMC Studio 用户指南》
• 《openUBMC Studio 安装指南》
• 《BMC 收集日志》