记一次 PySide6 智能助手闪退排查：QWebEngineView 与输入法事件过滤器冲突，导致 getWrapperForQObject 段错误

关键词：PySide6、QtWebEngine、matplotlib、PyInstaller、银河麒麟、段错误、coredump、智能助手、图表渲染

摘要：政务信息化项目档案管理系统的智能助手在输入「统计项目状态分布」时整个应用闪退（段错误，无 Python 异常堆栈）。本文完整记录从 coredump 定位到根因、再到重构图表渲染链路、修复打包后图表不显示的全过程，并顺带解决意图识别不稳定、气泡高度跳动、滚动不丝滑等问题。核心结论：在国产化 Linux 桌面（银河麒麟 V10 / 内核 5.4）上，PySide6 的 QWebEngineView 与全局 XIM 输入法事件过滤器存在原生层冲突，应彻底避免在聊天界面内嵌 Chromium 渲染图表。

一、问题背景

系统是一套「政务信息化项目全流程管理系统」，桌面端用 PySide6 6.6.3 开发，运行环境是 银河麒麟 V10（内核 5.4.18）。系统内置一个「智能助手」聊天组件，支持自然语言查询/统计/生成图表，架构上遵循：

意图上云：用户自然语言意图发给大模型（DeepSeek）解析，返回 JSON 指令；
数据留本地：业务数据由本地 Skill 获取、本地模板渲染，永不回传云端。

智能助手的图表此前用 plotly + QWebEngineView 渲染：plotly 生成 HTML，QWebEngineView 内嵌 Chromium 加载本地 plotly.min.js 展示交互式图表。

问题发生在：用户在智能助手输入 「统计项目状态分布」 并发送后，整个应用直接闪退（Segmentation fault，核心已转储），且没有任何 Python traceback。

二、问题一：智能助手「统计项目状态分布」闪退

2.1 现象

源码运行和打包运行都复现；
日志里最后一行是输入法桥接的几何日志 for QTextBrowser，之后戛然而止；
进程收到 SIGSEGV，coredumpctl 显示「核心已转储」；
无 Python 异常堆栈，说明是原生层崩溃 ，不是 try/except 能捕获的异常。

2.2 用 coredump 定位崩溃点

这是本次排查最关键的一步。先确认 core 已生成：

bash 复制代码

coredumpctl list | tail

拿到崩溃进程 PID 后，导出 core 并用 gdb 取主线程回溯：

bash 复制代码

coredumpctl dump <PID> -o /tmp/core.dump
gdb -q /usr/local/python310/bin/python3.10 /tmp/core.dump -batch -ex "thread 1" -ex "bt"

主线程回溯的关键帧如下：

复制代码

#0  ??() @ libpyside6.abi3.so
#1  PySide::getWrapperForQObject(QObject*, _typeobject*)
#3  QCoreApplicationPrivate::sendThroughApplicationEventFilters(QObject*, QEvent*)
#6  QObject::doSetProperty(char const*, QVariant const*, QVariant*)
#7  PySide::getWrapperForQObject(QObject*, _typeobject*)
#9  QCoreApplicationPrivate::sendThroughApplicationEventFilters(QObject*, QEvent*)
#12 QCoreApplicationPrivate::sendPostedEvents(QObject*, int, QThreadData*)
#19 QCoreApplication::exec()

关键信息：

崩溃发生在主线程事件循环里；
卡在 sendThroughApplicationEventFilters ------ 即 Qt 在把事件派发给应用级事件过滤器；
最终死在 PySide::getWrapperForQObject，这是 PySide 给 QObject 生成 Python 包装对象的 C++ 代码。

全项目只有一个全局事件过滤器------XIM 输入法桥接器 （fcitx_im.py 里 app.installEventFilter(self)）。而触发点正是创建 QWebEngineView：Chromium 渲染进程会高频创建/销毁原生子对象，事件经全局过滤器分发时，PySide 要给一个已析构的悬垂 QObject 包装 Python 对象，于是段错误。

2.3 根因

QWebEngineView（Chromium 内核）与全局 XIM 输入法事件过滤器在原生层冲突 ，导致 getWrapperForQObject 访问悬垂 QObject 触发段错误。这类崩溃发生在 C++/原生层，try/except 无法捕获，--no-sandbox 也无效（我最初误判为 Chromium 沙箱问题，实测无效）。

2.4 解决方案：彻底移除 QWebEngineView，改用 matplotlib 渲染 PNG

既然 QWebEngineView 在这个国产化环境上不可靠，最稳妥的方案是完全不使用它 ，改用 matplotlib（Agg 无显示后端）把图表渲染成 PNG 图片 ，再用普通 QLabel + QPixmap 展示。这样：

不依赖 Chromium 沙箱、GPU、渲染进程；
不产生 QWebEngineView 的原生子对象，避开与事件过滤器的冲突；
matplotlib Agg 是纯离屏渲染，头等稳定。

核心改动是新建 render_chart_image，并把聊天界面的图表展示从 QWebEngineView 换成 QLabel：

python 复制代码

# src/utils/chart_generator.py（节选）
import matplotlib
matplotlib.use('Agg')  # 无显示后端
import matplotlib.pyplot as plt

def render_chart_image(chart_type: str, chart_data: dict) -> bytes:
    """把结构化图表数据渲染为 PNG 字节"""
    if chart_type == 'pie':
        return _render_pie(chart_data)
    if chart_type == 'timeline':
        return _render_timeline(chart_data)
    return _render_bar(chart_data)

python 复制代码

# src/ui/chat_widget.py（节选）
def _add_chart_image(self, png_bytes: bytes):
    pixmap = QPixmap()
    if not png_bytes or not pixmap.loadFromData(png_bytes):
        self._add_message("assistant", "图表加载失败")
        return
    image_label = QLabel()
    image_label.setPixmap(pixmap)
    image_label.setAlignment(Qt.AlignCenter)
    ...

同时，把渲染从主线程挪到后台线程，信号从传 dict（跨线程序列化有坑）改为传 PNG 字节：

python 复制代码

# 后台线程直接渲染，再通过信号传字节
class AssistantWorker(QThread):
    chart_image_received = Signal(object)  # PNG bytes

    def run(self):
        ...
        if result.get("chart_type") and result.get("chart_data"):
            from src.utils.chart_generator import render_chart_image
            png = render_chart_image(result["chart_type"], result["chart_data"])
            if png:
                self.chart_image_received.emit(png)

这样既绕开了 dict 跨线程的序列化不可靠问题，也避免了在主线程构建 matplotlib 字体缓存时阻塞 UI。

三、问题二：打包后图表不显示（ModuleNotFoundError: unittest）

3.1 现象

源码运行图表正常，但 ./build_kylin.sh 打包后，图表不显示（但也不闪退了）。

3.2 排查：给渲染路径加上日志

之前的代码是 except Exception: pass 静默吞错，导致无法定位。第一步是给渲染路径加日志：

python 复制代码

@Slot(object)
def _on_chart_image_received(self, png_bytes):
    logger.info(f"图表图片: bytes={len(png_bytes) if png_bytes else 0}")
    ...

重新打包运行后，日志立刻暴露了真正的错误：

复制代码

后台渲染图表失败: No module named 'unittest'
Traceback (most recent call last):
  File "src/utils/chart_generator.py", line 22, in <module>
  File "matplotlib/__init__.py", line 161, in <module>
  File "matplotlib/rcsetup.py", line 29, in <module>
  File "matplotlib/_fontconfig_pattern.py", line 15, in <module>
  File "pyparsing/__init__.py", line 156, in <module>
  File "pyparsing/testing.py", line 6, in <module>
ModuleNotFoundError: No module named 'unittest'

3.3 根因

PyInstaller 打包配置（.spec）的 excludes 里为了减小体积排除了 unittest：

python 复制代码

excludes = [
    'tkinter',
    'unittest',   # ← 罪魁祸首
    ...
]

但 matplotlib 的依赖链是：

复制代码

matplotlib._fontconfig_pattern → pyparsing → pyparsing.testing → import unittest

于是打包后 import matplotlib 直接 ModuleNotFoundError，图表渲染失败。

3.4 解决方案

把 unittest 从 excludes 移除，让 PyInstaller 自动把它作为依赖打进去：

python 复制代码

excludes = [
    'tkinter',
    # 注意：不要排除 unittest！
    # matplotlib 依赖链需要 import unittest（经 pyparsing.testing），
    # 排除后打包程序导入 matplotlib 会报 ModuleNotFoundError。
    'test',
    'pytest',
    ...
]

顺带排查了 excludes 里其它项，确认都安全（tkinter 只在 TkAgg 后端用、pydoc 是 numpy 函数内懒加载、setuptools 是版本检测懒加载等），唯独 unittest 在模块顶层导入链里被真实依赖。

四、顺带优化（让智能助手「更稳定更聪明」）

4.1 意图识别不稳定 → 本地关键词兜底

现象：「画一个项目预算成本柱状图」三次可能返回三种结果（unknown、JSON 解析失败、正确）。根因是大模型输出的 JSON 意图偶尔不稳定。在不改动「意图上云」主流程的前提下，加一层本地安全网：

python 复制代码

def _local_keyword_match(self, user_message: str) -> Optional[str]:
    """仅在大模型意图识别失败时启用，只匹配无必填参数的技能"""
    query = user_message.strip().lower()
    best_name, best_score = None, 0.0
    for skill in registry.get_all_skills().values():
        d = skill.definition
        if any(p.required for p in d.params):
            continue  # 有必填参数的技能不做本地兜底，避免参数提取错误
        score = 0.0
        for kw in d.keywords:
            if kw and kw.lower() in query:
                score += len(kw) * 2  # 精确包含权重最高
        ...
    return best_name if best_score >= 4 else None

4.2 「查看项目N的完整档案」被误路由

现象：输入「查看项目1的完整档案」却返回所有项目列表，或编排成错误工作流报 NoneType。根因是 get_all_projects 的关键词 "查看项目" 太宽泛，且大模型会把「带编号的档案」误拆成多步工作流。

修复：① 收紧关键词（去掉 "查看项目"，补 "完整档案"）；② 提示词加「意图消歧规则」；③ 加本地意图纠偏，识别「项目N + 档案/详情」模式直接改判为单技能：

python 复制代码

def _local_project_archive_correction(self, user_message, intent):
    m = re.search(r'项目\s*(\d+)\s*(?:的)?\s*(完整档案|完整详情|档案|详情|完整信息)', user_message)
    if not m:
        return None
    project_id = int(m.group(1))
    # 已正确路由则不干预
    if intent.get("action") == "call_skill" and intent.get("skill_name") == "get_project_with_details":
        if str((intent.get("params") or {}).get("project_id")) == str(project_id):
            return None
    return {"action": "call_skill", "skill_name": "get_project_with_details",
            "params": {"project_id": project_id}, "reply_hint": ""}

4.3 气泡「先高后调」的视觉跳动

根因：气泡用 QTextBrowser.setHtml() 渲染，尺寸靠 documentSizeChanged 信号 + QTimer(50ms) 异步计算，于是先以默认高度显示、再回调到正确高度。修复：插入气泡后同步调用一次尺寸计算：

python 复制代码

bubble = MessageBubble(role, content, timestamp)
self.messages_layout.insertWidget(self.messages_layout.count() - 1, bubble)
bubble._adjust_bubble_size()   # 同步确定尺寸，消除跳动

QTextDocument.idealWidth()/size() 会强制同步完成布局，因此能立即拿到正确尺寸。

4.4 滚动不丝滑 → 贴底自动滚动

根因：气泡高度异步重排，_scroll_to_bottom 只在插入后滚动一次，追不上内容高度变化。修复：监听滚动条 rangeChanged/valueChanged，实现微信式「贴底跟随」：

python 复制代码

self._auto_scroll = True
_vbar = scroll_area.verticalScrollBar()
_vbar.rangeChanged.connect(self._on_scroll_range_changed)  # 内容变高时贴底
_vbar.valueChanged.connect(self._on_scroll_value_changed)  # 手动上滑暂停跟随

4.5 图表美观与数据可读性

用 matplotlib 重写渲染：类 Tableau 扁平配色、饼图改环形图（中心显示总数、图例标注实际数值）、柱状图每个柱顶标注数值（含千分位）、淡网格、去除冗余边框、dpi 提升到 130。

五、经验总结

原生层闪退用 coredump + gdb 定位，不要靠猜 。这次先误判为 Chromium 沙箱（--no-sandbox 无效），coredump 回溯才一锤定音------崩溃在 sendThroughApplicationEventFilters，是事件过滤器与 QWebEngineView 的冲突。
国产化 Linux（麒麟/内核 5.4）上谨慎使用 QWebEngineView，尤其是应用里同时挂了全局事件过滤器（如输入法桥接）时。图表展示用 matplotlib Agg 出 PNG + QLabel 更稳妥。
别让异常静默吞掉 。except Exception: pass 让打包后图表不显示完全无迹可寻，改成打日志后一次就定位到 unittest 缺失。
PyInstaller 的 excludes 别随意排除 stdlib 模块 。unittest 看着没用，却是 matplotlib→pyparsing 依赖链的一环。
大模型意图识别要有本地兜底。在「意图上云」架构不变的前提下，加关键词兜底 + 模式纠偏，能显著提升稳定性。

六、关键文件改动一览

文件	改动
`src/utils/chart_generator.py`	plotly→matplotlib Agg 出 PNG，美化图表
`src/ui/chat_widget.py`	QWebEngineView→QLabel，渲染移到后台线程，气泡同步定高，贴底滚动
`src/ai/dialog_manager.py`	本地关键词兜底 + 项目档案意图纠偏 + 提示词消歧
`src/ai/skills/tool_skills.py`	图表 Skill 返回结构化 `chart_data`
`src/ai/skills/service_skills.py`	修正关键词歧义
`IAS_kylin.spec` / `IAS.spec`	移除 plotly、修复 `unittest` 排除
`requirements.txt`	移除 plotly/pandas

本文由实际生产环境排障过程整理而成，如有帮助欢迎点赞、收藏、评论交流。