12 KiB
AI 问诊逐字流 Markdown 渲染审查
日期:2026-10-26。范围:app/src/doctor_workstation/ui/dialogs/ai_consult.py 与相关 app/tests。本次只读审查已有代码,唯一新增文件为本报告。根 AGENTS.md 已读取;当前工作区不存在 .trellis/,无法继续读取其 workflow/spec。代码原有未提交变更未作修改。
结论
当前问题来自桌面展示链路:服务器已批准的正文进入逐字队列后,每个字素通过 QTextCursor.insertText() 作为普通文本插入。###、** 和列表前缀因此是可见正文,直到最后一帧才统一 Markdown 渲染。不是最终 Markdown 解析器失效,也不需要通过改变模型输出解决。
另有测试契约冲突:R40 测试明确要求 Markdown 在播放期间保持原始文本。修复代码时必须同步更新这一展示断言,同时保留原始来源、字素完整性、请求生命周期及患者归属等检查。
根因与代码证据
以下行号基于本次读取的工作树版本。
| 位置 | 行为与影响 |
|---|---|
ai_consult.py:7300–7314 |
delta 将正文放入 _pending_chunks,首个正文立即 flush,后续由 timer flush。 |
ai_consult.py:7388–7395 |
_flush_stream_chunks() 拼接完整批准源文 _stream_text,调用 bubble.queue_approved_stream_text()。 |
ai_consult.py:3364–3382 |
保存未经改写的 _raw_payload / _presentation_text;缓存源文的字素结束偏移,首帧立即执行。 |
ai_consult.py:3397–3404 |
_advance_stream_presentation() 取下一个源文字素,调用 body.append_plain_stream_text(...)。这是实际展示路径的关键分支。 |
ai_consult.py:2298–2317 |
append_plain_stream_text() 只执行 cursor.insertText(),仅归一化 CRLF,完全不解析 Markdown。 |
ai_consult.py:7337–7341, 5785–5797 |
done 安排最后一帧之后执行的回调;finish_stream_text() 在回调里调用。收到 done 本身不会马上格式化仍在播放的正文。 |
ai_consult.py:3360–3362, 2218–2233, 1134 |
最后一帧之后才执行 set_payload() → render_chat_payload() → setMarkdown(),此时标记消失、标题/粗体/列表生效。 |
ai_consult.py:2235–2296, 3355–3358 |
已有的 append_stream_text() 支持增量 Markdown 与稳定段落,但 SSE 的逐字队列绕过了这条入口。 |
24 ms 单次计时器不会追赶积压(3281–3285, 3405–3408)。这意味着原始标记可能持续整个播放时长,而不只是网络 chunk 到达之间的一瞬间。即使模型已经完成返回,队列尚未播完时仍是纯文本。
离线 Qt 复现
使用当前 app/.venv/Scripts/python.exe -B 与 offscreen Qt,直接构造 _ChatBubble,输入合成正文:
### 标题
**重点**
- 第一项
- 第二项
末尾
调用 queue_approved_stream_text() 后,通过真实 Qt timeout signal 每次推进一帧,未调用 terminal 回调前观察到:
| 源偏移 | 可见内容 | 首块 headingLevel |
|---|---|---|
| 1 | # |
0 |
| 4 | ### |
0 |
| 6 | ### 标题 |
0 |
| 14 | 标题原文、空行、**重点** |
0 |
| 21 | 上述内容与 - 第一项 |
0 |
| 31(全部源文已播出) | 全部 Markdown 源文 | 0 |
随后调用 complete_stream_presentation(bubble.finish_stream_text):可见文本变为“标题 / 重点 / 第一项 / 第二项 / 末尾”,首块 headingLevel == 3,_raw_payload 始终与原始输入完全一致。证实渲染时间点与旁路是直接原因。
最小修复建议
- 保持
_stream_text、_raw_payload、批准边界、字素队列与最后一帧回调;只调整逐帧的展示入口。最小接线变更是在3402将已到展示偏移的 delta 交给现有body.append_stream_text(...),从而恢复“稳定段落保留、只重解析未完成尾段”的 Markdown 渲染。不要在每帧调用set_payload(full_text):那会重新解析完整历史并可能显示尚未轮到的正文。 - 必须同步替换 R40 的“播放期间等于原始 Markdown 前缀”断言。纯文本仍可保持逐字前缀断言;Markdown 应断言已展示的语义内容和 Qt 文档格式。
_raw_payload == answer继续单独验证,不能用视图纯文本代表原始来源是否完整。 - 该接线变更只能修复“已完整的语法长期不渲染”。若验收要求是“任何一帧都看不到 Markdown 控制标记”,还需在同一展示层处理不完整语法:暂存行首标题/列表控制段与尚未闭合的行内标记,或建立基于批准源文的富文本投影,再按可见字素展示。显示内容不得超过已经批准的源文,也不得提前出现尚未轮到的正文。先明确并测试这个验收口径,不能把一行接线改动宣称为逐帧零标记修复。
不建议对原始回答全局删除 #、*、-:代码、转义字符、JSON 字符串、负数及正常原文可能合法包含这些字符。也不建议绕过批准队列或在 done 时直接倾倒剩余正文。
必须考虑的边界
- 半截语法仍会漏标记。 已实际验证旧
append_stream_text()对**重点**逐字输入的可见序列为"","**","**重","**重点","*重点","重点"。因此直接切换入口不足以保证全部帧无标记;分 chunk 的###、有序列表前缀、链接与代码围栏也需覆盖。 - 2048 字符回退。 现有 Markdown 增量入口在未完成尾段长度超过 2048 时改用
insertText()(2278–2280),后续没有稳定段落边界时继续纯文本追加(2261–2262)。只做接线修复后,长段落或未闭合围栏仍可能恢复显示标记。应改为保持已识别结构、对昂贵解析限频或使用投影;不要无条件删除性能保护。 - 稳定边界只是空行启发式。
_stable_markdown_prefix()(2159–2174)知道围栏内空行不能提交,但跨段的引用式链接、紧凑/宽松列表、嵌套块等可能依赖后文。终态整文渲染仍需保留;重要结构应增加一致性回归。 - 代码和来源必须保真。 代码围栏内的
###、**、-是正常文本。JSON/结构化来源的键和值也不能通过展示清洗改写;完整 JSON/HTML 的现有终态识别行为(1120–1134)需单独保留。 - Unicode 与坐标。
_presentation_offset是 Python 源文偏移,QTextCursor位置是 Qt UTF-16 文档坐标。隐藏语法后可见字符数不再等于源偏移,不能直接混用。emoji、组合音标、ZWJ、旗帜与跨 chunk CRLF 的已有逻辑(3220–3248)必须继续适用。 - 异常/取消/跨患者。 error/未确认 EOF 会等批准部分播放完再调用
finish_stream_text()(7433,7457);取消会stop_stream_presentation(reveal_approved=True)并一次格式化批准源文(3419–3427)。这些路径应与成功路径呈现一致,且不能触发成功报告转换或改变患者归属隔离。 - 性能和选区。 逐字调用完整
setMarkdown()会引入随内容增长的重复解析、重排、滚动及选区抖动。应复用稳定段落策略并验证长输入/多气泡;段落对象和用户选区保持是现有测试的明确约束。
现有测试为何未防住
| 测试 | 当前覆盖与缺口 |
|---|---|
test_ai_consult_active_stream_ui.py:26–49 |
直接调用旧 bubble.append_stream_text(),覆盖增量/终态一致性,未经过实际 queue_approved_stream_text() 链路。 |
同文件 51–71, 114–125 |
覆盖旧入口的稳定段落、选区、标题和列表格式;无法证明 R40 逐字入口生效。 |
test_ai_character_presentation_r40.py:330–350 |
明确断言每帧 toPlainText() == answer[:index],最后才调用 set_payload()。这会要求当前问题继续存在,应随体验需求更新。 |
同文件 122–176, 179–326, 354–370 |
有价值的单帧节奏、Unicode、CRLF、缓存分词约束,应继续保留,Markdown 用可见内容断言。 |
test_ai_consult_ui.py:842–857 |
验证完整 payload 的 Markdown/HTML/JSON,未覆盖播放中间态。 |
同文件 1181–1222 |
名称提到“stays_markdown”,中间态实际上只检查 body 显示和 panel 未出现,没有检查 Markdown 格式。其对 done 后仅 processEvents 就出现 panel 的预期也早于 R40 的长队列播放契约。 |
test_ai_repeated_presentation_r38.py:28–62 |
11000 字符按当前 24 ms/字至少需约 264 秒,测试只等 5 秒;修复时不要以此旧时限证明当前逐字方案失效或偷偷加速。使用受控 Qt tick 验证长积压,另保留短文本物理计时器测试。 |
建议新增或更新的测试
- 真实 SSE 展示入口回归:用
dialog._stream_event(delta)→_flush_stream_chunks(),断言调用的是逐字渲染链路。在尚未 done、播放到完整### 标题/**重点**/- 列表项后,检查标题级别、粗体与textList();不能只检查文本包含正文。 - 完整批准突发与切分到达:同一合成正文分别整段批准、每字符批准、7 字符批准,控制 Qt timeout;记录每帧与可见视图,验证无正文提前出现、无重复/丢失。若采用零标记口径,检查所有歧义前缀帧,而不是只看闭合后的快照。
- 长尾与段落边界:覆盖 2048 前后、2200/11000 字符、长无空行段落、闭合前后代码围栏;检查批准尾部在继续输入/终态后完整,已显示的格式不会退化为源文。
- 语法与文字区分:标题、加粗、无序/有序/嵌套列表、链接、表格;代码/转义里的
### ** -、JSON 值里的相同字符、比较符号与负数应按原语义保留。 - 来源与终态一致性:
_raw_payload始终逐字等于批准输入;最后以set_payload(answer)为 oracle 比较toPlainText()与文档结构/HTML。error/EOF/取消路径也检查格式、失败提示和不创建成功报告。 - 时序/生命周期回归:保留 done 及时释放发送按钮、后续请求可启动、旧气泡独立播放、关闭/切患者停止 timer、迟到事件不污染新患者和图表 owner 检查。保留 Unicode/CRLF 和稳定选区回归。
- 有限性能检查:长文本用受控 tick 避免几分钟等待;验证不会每帧重分词全部源文或重渲染全部稳定段落。短文本继续使用真实单次 24 ms timer 验证一帧一字、不追赶积压和实际 viewport paint。
本次验证记录
未访问模型/网络,未修改应用代码或测试。运行 Python 使用 -B,pytest 使用 -p no:cacheprovider,避免生成字节码和 pytest 缓存。离线 Qt 合成复现如上。
以下定向现有测试共 16 passed in 0.60s:
cd D:\web\zyt\app
.\.venv\Scripts\python.exe -B -m pytest -p no:cacheprovider `
tests/test_ai_character_presentation_r40.py::test_markdown_html_and_json_do_not_reinterpret_during_character_playback `
tests/test_ai_character_presentation_r40.py::test_whole_unicode_graphemes_are_visible_exact_prefixes `
tests/test_ai_character_presentation_r40.py::test_split_crlf_holds_trailing_cr_and_reveals_one_normalized_newline `
tests/test_ai_character_presentation_r40.py::test_segmentation_is_cached_on_approved_input_not_rebuilt_each_frame `
tests/test_ai_consult_active_stream_ui.py::test_incremental_markdown_preserves_content_and_terminal_format `
tests/test_ai_consult_active_stream_ui.py::test_heading_size_and_list_spacing_are_stable_during_generation
这些通过结果同时证明:旧增量 Markdown 能正常工作、R40 当前纯文本展示也符合现有测试;它们并不证明逐字中间态具有所需 Markdown 体验。本次未运行全部应用测试。