fix(export): 修复引用块正文丢失、嵌套列表顺序与排队取消（复审） #37

2026-09-06T17:52:26+08:00

yxx commented

2026-09-06 17:52:26 +08:00

复审修复（响应 PR #33 审阅结论）

修复 3 个 P2 与 1 个 P3，补充结构内容回归测试，并同步最新 main（e29cc42）。

P2 修复

引用块正文丢失：PDF/DOCX 的 _block_blockquote 此前把块级子节点（paragraph/list）交给行内渲染器，导致 quoted **content** 的正文被当作「无法表示的行内节点」丢弃。现改为逐个渲染块级子节点，并继承引用缩进/颜色。
PDF 嵌套列表顺序颠倒：_block_list_item 此前在循环里遇到嵌套列表就立即递归输出，父级正文后置。现改为先输出父级正文、再输出子列表。
排队任务无法及时取消：_execute 此前在获得渲染槽位前就置为 running，取消标志要等拿到槽位后才检查。现改为等待槽位期间保持 queued 并同时监听取消，取消即时生效。

P3 修复

接口契约：同步 html/pdf/docx 三格式均已实现，移除 EXPORT_FORMAT_UNSUPPORTED。

附带修复

DOCX 列表项此前未处理直接 text 子节点，正文被块级渲染器丢弃（结构内容测试暴露），已一并修复。

测试

新增结构内容回归测试：引用块正文（PDF 提取文本 / DOCX 解包 XML）、嵌套列表父级在前、排队任务取消。
全量 708 用例通过。

## 复审修复（响应 PR #33 审阅结论）修复 3 个 P2 与 1 个 P3，补充结构内容回归测试，并同步最新 main（`e29cc42`）。 ### P2 修复 - **引用块正文丢失**：PDF/DOCX 的 `_block_blockquote` 此前把块级子节点（paragraph/list）交给行内渲染器，导致 `quoted **content**` 的正文被当作「无法表示的行内节点」丢弃。现改为逐个渲染块级子节点，并继承引用缩进/颜色。 - **PDF 嵌套列表顺序颠倒**：`_block_list_item` 此前在循环里遇到嵌套列表就立即递归输出，父级正文后置。现改为先输出父级正文、再输出子列表。 - **排队任务无法及时取消**：`_execute` 此前在获得渲染槽位前就置为 `running`，取消标志要等拿到槽位后才检查。现改为等待槽位期间保持 `queued` 并同时监听取消，取消即时生效。 ### P3 修复 - **接口契约**：同步 `html`/`pdf`/`docx` 三格式均已实现，移除 `EXPORT_FORMAT_UNSUPPORTED`。 ### 附带修复 - DOCX 列表项此前未处理直接 `text` 子节点，正文被块级渲染器丢弃（结构内容测试暴露），已一并修复。 ### 测试 - 新增结构内容回归测试：引用块正文（PDF 提取文本 / DOCX 解包 XML）、嵌套列表父级在前、排队任务取消。 - 全量 708 用例通过。

Kronecker commented

2026-09-06 19:00:53 +08:00

审阅结论：请求修改，暂不建议合并

审阅提交：6c14047

上一轮提出的问题已经完成基础修复：

PDF/DOCX 引用块正文可以正常保留；
简单父子嵌套列表顺序正确；
等待渲染槽位的任务保持 queued，可以即时取消；
PDF/DOCX 接口状态已经同步。

本轮进一步审阅发现 2 个 P2、1 个 P3。

[P2] PDF 仍会重排混合列表项内容

位置：backend/app/export/exporters/pdf.py:223–238

当前实现会先收集列表项中的全部正文，随后统一输出所有嵌套列表。这只能保证简单的“父项在前、子列表在后”，无法保持混合列表项的原始 AST 顺序。

例如：

- parent

  - child

  after

原始顺序是：

parent
child
after

实际 PDF 流程顺序为：

parent
after
child

建议按照 AST 顺序分段输出：

遇到普通内容时暂存当前正文；
遇到嵌套列表前先输出已暂存正文；
在当前位置递归输出嵌套列表；
然后继续处理后续正文。

请增加“父段落—子列表—后续段落”的顺序回归测试。

[P2] DOCX/PDF 列表项会丢失链接和强调语义

位置：

backend/app/export/exporters/docx.py:169–184
backend/app/export/exporters/pdf.py:227–235

列表项的直接子节点可能是 strong、emphasis 或 link。当前遇到带 children 的节点时，会直接渲染其子节点，从而绕过该节点自身的格式处理。

实测：

- **bold** [link](https://example.com)

DOCX 结果中：

bold 被写成 w:b=0，没有加粗；
不存在 w:hyperlink；
不存在指向 https://example.com 的外部关系。

PDF 中的链接也会被降级为普通文字，并且不会产生 warning。

建议：

对直接行内节点调用 _render_inline_node；
仅对 paragraph 等块级容器展开 children；
分别增加列表项内加粗、斜体和链接的产物结构测试。

[P3] `StaticRenderer` 仍被标记为计划新增

位置：docs/contracts/第二阶段接口契约-开发版.md:77

本 PR 已新增并接入 StaticRenderer 内部契约，但接口总表仍将 Renderer 标记为“计划新增”。

请更新为“已实现”，并明确：

Function Plot 已支持后端静态 SVG 渲染；
Mermaid 当前返回占位结果；
PDF/DOCX 中两者目前保留源码占位。

验证结果

后端全量测试：708 passed
git diff --check：通过
与最新 main：无冲突
远程状态：可合并

Git 层面已经可以合并，但仍建议修复以上问题并补充测试后再提交复审。

## 审阅结论：请求修改，暂不建议合并审阅提交：`6c14047` 上一轮提出的问题已经完成基础修复： - PDF/DOCX 引用块正文可以正常保留； - 简单父子嵌套列表顺序正确； - 等待渲染槽位的任务保持 `queued`，可以即时取消； - PDF/DOCX 接口状态已经同步。本轮进一步审阅发现 **2 个 P2、1 个 P3**。 ### [P2] PDF 仍会重排混合列表项内容位置：`backend/app/export/exporters/pdf.py:223–238` 当前实现会先收集列表项中的全部正文，随后统一输出所有嵌套列表。这只能保证简单的“父项在前、子列表在后”，无法保持混合列表项的原始 AST 顺序。例如： ```markdown - parent - child after ``` 原始顺序是： ```text parent child after ``` 实际 PDF 流程顺序为： ```text parent after child ``` 建议按照 AST 顺序分段输出： 1. 遇到普通内容时暂存当前正文； 2. 遇到嵌套列表前先输出已暂存正文； 3. 在当前位置递归输出嵌套列表； 4. 然后继续处理后续正文。请增加“父段落—子列表—后续段落”的顺序回归测试。 ### [P2] DOCX/PDF 列表项会丢失链接和强调语义位置： - `backend/app/export/exporters/docx.py:169–184` - `backend/app/export/exporters/pdf.py:227–235` 列表项的直接子节点可能是 `strong`、`emphasis` 或 `link`。当前遇到带 `children` 的节点时，会直接渲染其子节点，从而绕过该节点自身的格式处理。实测： ```markdown - **bold** [link](https://example.com) ``` DOCX 结果中： - `bold` 被写成 `w:b=0`，没有加粗； - 不存在 `w:hyperlink`； - 不存在指向 `https://example.com` 的外部关系。 PDF 中的链接也会被降级为普通文字，并且不会产生 warning。建议： - 对直接行内节点调用 `_render_inline_node`； - 仅对 `paragraph` 等块级容器展开 `children`； - 分别增加列表项内加粗、斜体和链接的产物结构测试。 ### [P3] `StaticRenderer` 仍被标记为计划新增位置：`docs/contracts/第二阶段接口契约-开发版.md:77` 本 PR 已新增并接入 `StaticRenderer` 内部契约，但接口总表仍将 Renderer 标记为“计划新增”。请更新为“已实现”，并明确： - Function Plot 已支持后端静态 SVG 渲染； - Mermaid 当前返回占位结果； - PDF/DOCX 中两者目前保留源码占位。 ### 验证结果 - 后端全量测试：**708 passed** - `git diff --check`：通过 - 与最新 `main`：无冲突 - 远程状态：可合并 Git 层面已经可以合并，但仍建议修复以上问题并补充测试后再提交复审。

Kronecker closed this pull request

2026-09-06 19:00:53 +08:00

Kronecker reopened this pull request

2026-09-06 19:37:19 +08:00

Kronecker closed this pull request

2026-09-06 19:37:33 +08:00

Pull request closed

This pull request cannot be reopened because the branch was deleted.

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Kronecker/NotesAgentic#37