Files
zyt/artifacts/stream_markdown_review_20261026.md
T
2026-10-27 14:03:35 +08:00

12 KiB
Raw Blame History

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 始终与原始输入完全一致。证实渲染时间点与旁路是直接原因。

最小修复建议

  1. 保持 _stream_text、_raw_payload、批准边界、字素队列与最后一帧回调;只调整逐帧的展示入口。最小接线变更是在 3402 将已到展示偏移的 delta 交给现有 body.append_stream_text(...),从而恢复“稳定段落保留、只重解析未完成尾段”的 Markdown 渲染。不要在每帧调用 set_payload(full_text):那会重新解析完整历史并可能显示尚未轮到的正文。
  2. 必须同步替换 R40 的“播放期间等于原始 Markdown 前缀”断言。纯文本仍可保持逐字前缀断言;Markdown 应断言已展示的语义内容和 Qt 文档格式。_raw_payload == answer 继续单独验证,不能用视图纯文本代表原始来源是否完整。
  3. 该接线变更只能修复“已完整的语法长期不渲染”。若验收要求是“任何一帧都看不到 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 验证长积压,另保留短文本物理计时器测试。

建议新增或更新的测试

  1. 真实 SSE 展示入口回归:用 dialog._stream_event(delta) → _flush_stream_chunks(),断言调用的是逐字渲染链路。在尚未 done、播放到完整 ### 标题 / **重点** / - 列表项 后,检查标题级别、粗体与 textList();不能只检查文本包含正文。
  2. 完整批准突发与切分到达:同一合成正文分别整段批准、每字符批准、7 字符批准,控制 Qt timeout;记录每帧与可见视图,验证无正文提前出现、无重复/丢失。若采用零标记口径,检查所有歧义前缀帧,而不是只看闭合后的快照。
  3. 长尾与段落边界:覆盖 2048 前后、2200/11000 字符、长无空行段落、闭合前后代码围栏;检查批准尾部在继续输入/终态后完整,已显示的格式不会退化为源文。
  4. 语法与文字区分:标题、加粗、无序/有序/嵌套列表、链接、表格;代码/转义里的 ### ** -、JSON 值里的相同字符、比较符号与负数应按原语义保留。
  5. 来源与终态一致性:_raw_payload 始终逐字等于批准输入;最后以 set_payload(answer) 为 oracle 比较 toPlainText() 与文档结构/HTML。error/EOF/取消路径也检查格式、失败提示和不创建成功报告。
  6. 时序/生命周期回归:保留 done 及时释放发送按钮、后续请求可启动、旧气泡独立播放、关闭/切患者停止 timer、迟到事件不污染新患者和图表 owner 检查。保留 Unicode/CRLF 和稳定选区回归。
  7. 有限性能检查:长文本用受控 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 体验。本次未运行全部应用测试。