Kronecker/NotesAgentic
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 4 Wiki Activity

feat(export): 多格式文档导出服务（HTML / PDF / DOCX + 函数图像渲染） #41

Closed
yxx wants to merge 0 commits from feat/export-service into main
pull from: feat/export-service
merge into: :main
Conversation 1 Commits - Files Changed -
+4836 -17
yxx commented 2026-09-07 00:05:05 +08:00
Collaborator
Copy Link
Copy Source

概述

Export Service：把笔记或未保存的 Markdown 文本导出为 HTML / PDF / DOCX 的完整链路——创建即返回 queued、后台 asyncio.Task 渲染、产物 24h 过期、轮询 GET /api/exports/{job_id} 下载。

范围（相对 main：28 文件 / +4836 行）

  • Document AST：mistune renderer="ast" → DocumentNode 内部协议 + DocumentExporter Protocol。
  • 三种导出器：
    • HtmlExporter：完整 HTML5 + function-plot 静态 SVG 内嵌。
    • PdfExporter：reportlab，function-plot 内嵌矢量 Drawing（与 SVG 同源共享几何），中文字体 STSong-Light，列表/表格/引用/行内语义。
    • DocxExporter：python-docx，标题/列表/链接/表格，中文经 w:eastAsia=宋体。
  • Function Plot：白名单 AST 表达式解析（parser.py）、共享几何 compute_geometry（render.py）、reportlab 矢量后端（render_reportlab.py）、StaticRenderer 内部契约（renderer.py）。
  • 资源上限：输入 200k 字符、单图 ≤16 表达式、文档 ≤16 图、累计 AST 节点预算 8000、并发渲染 2、产物 20MB。
  • HTTP 契约与路由：app/contracts.py + app/routes.py 的 /api/exports*（创建/查询/下载/取消）。
  • 测试与文档：tests/test_export.py、tests/test_plot.py，docs/development/Export开发说明.md、接口契约 §10。

审阅修复记录（多轮）

  • 引用块正文丢失、嵌套列表顺序与排队取消
  • 列表项行内语义丢失与混合嵌套顺序重排
  • 函数图像数量/复杂度预算上限
  • PDF 函数图像矢量内嵌
  • 显式 range 外曲线裁剪 + PDF 纵轴标签旋转修正
  • 渐近点落在采样点之间时断段（避免贯穿绘图区的伪竖线）

验证结果

  • 后端完整测试：720 passed
  • git diff --check：通过
  • 与当前远程 main：无合并冲突
## 概述 Export Service：把笔记或未保存的 Markdown 文本导出为 HTML / PDF / DOCX 的完整链路——创建即返回 `queued`、后台 asyncio.Task 渲染、产物 24h 过期、轮询 `GET /api/exports/{job_id}` 下载。 ## 范围（相对 main：28 文件 / +4836 行） - **Document AST**：mistune `renderer="ast"` → `DocumentNode` 内部协议 + `DocumentExporter` Protocol。 - **三种导出器**： - `HtmlExporter`：完整 HTML5 + function-plot 静态 SVG 内嵌。 - `PdfExporter`：reportlab，function-plot 内嵌矢量 `Drawing`（与 SVG 同源共享几何），中文字体 STSong-Light，列表/表格/引用/行内语义。 - `DocxExporter`：python-docx，标题/列表/链接/表格，中文经 `w:eastAsia=宋体`。 - **Function Plot**：白名单 AST 表达式解析（`parser.py`）、共享几何 `compute_geometry`（`render.py`）、reportlab 矢量后端（`render_reportlab.py`）、`StaticRenderer` 内部契约（`renderer.py`）。 - **资源上限**：输入 200k 字符、单图 ≤16 表达式、文档 ≤16 图、累计 AST 节点预算 8000、并发渲染 2、产物 20MB。 - **HTTP 契约与路由**：`app/contracts.py` + `app/routes.py` 的 `/api/exports*`（创建/查询/下载/取消）。 - **测试与文档**：`tests/test_export.py`、`tests/test_plot.py`，`docs/development/Export开发说明.md`、接口契约 §10。 ## 审阅修复记录（多轮） - 引用块正文丢失、嵌套列表顺序与排队取消 - 列表项行内语义丢失与混合嵌套顺序重排 - 函数图像数量/复杂度预算上限 - PDF 函数图像矢量内嵌 - 显式 range 外曲线裁剪 + PDF 纵轴标签旋转修正 - 渐近点落在采样点之间时断段（避免贯穿绘图区的伪竖线） ## 验证结果 - 后端完整测试：`720 passed` - `git diff --check`：通过 - 与当前远程 `main`：无合并冲突
yxx added 18 commits 2026-09-07 00:05:06 +08:00
feat(export): 交付 Markdown → HTML 导出服务 5c2441464d 
实现 Export Service 完整生命周期：mistune AST → Document AST → HtmlExporter 渲染完整 HTML5，异步任务注册表 + 取消 + 24h 产物过期。新增 5 个 /api/exports 端点与 15 项测试；pdf/docx 与函数图像静态渲染留待后续 PR。
Merge remote-tracking branch 'origin/main' into feat/export-service 7eae7fba00
fix(export): 修复 PR #17 审阅问题（1 P1 + 5 P2） 64af1f5165 
- P1 链接/图片 URL 协议白名单校验，危险协议降级为纯文本 + warning
- P2 图片 AST 字段映射（src=attrs.url，alt 取 children 文本）
- P2 原始 HTML 块转义保留，正文不丢失 + warning
- P2 过期/淘汰/重启清理导出产物文件
- P2 解析与渲染移入 asyncio.to_thread，运行中取消生效
- P2 function-plot 围栏别名补全
- 回归测试覆盖全部修复

Co-Authored-By: Claude Code <noreply@anthropic.com>
feat(export): 函数图像静态渲染（function-plot → SVG） f49d1245a1 
- 新增 app/plot 包：白名单表达式解析（ast 无 eval）+ FunctionPlot 模型 + 静态 SVG 渲染
- HtmlExporter 的 function_plot 节点解析并内嵌 SVG，解析失败回退占位并转诊断
- 新增 test_plot.py（13 个测试）覆盖表达式安全、指令解析、SVG 输出与导出链路集成

Co-Authored-By: Claude Code <noreply@anthropic.com>
fix(plot): 修复函数图像审阅问题（1 P1 + 2 P2） 04f36524b1 
- P1 浮点刻度死循环：_ticks 改为有上限的整数索引推进并校验步长推进
- P2 求值异常：白名单函数校验参数数量；负数底非整数指数按断点处理；采样容错复数
- P2 无效纵轴范围：退化/非有限 range 丢弃并自动采样重算；渲染异常回退占位不阻断导出
- 补 6 个回归测试

Co-Authored-By: Claude Code <noreply@anthropic.com>
Merge origin/main into feat/export-service 50d7fb4c7d 
同步 main（054f704），解决 contracts.py / main.py / README.md / 技术栈说明 的合并冲突。
- contracts.py：保留 pydantic 多行导入并新增 RequestOverride
- main.py：合并 lifespan（导出孤儿清理 + 转写/本地模型生命周期）
- README.md / 技术栈说明：文档取 main 最新版本

Co-Authored-By: Claude Code <noreply@anthropic.com>
fix(plot): 修复复审问题（2 P2 + 1 P3） b87f94551b 
- P2 复杂表达式绕过异常回退：解析与渲染共同纳入局部异常回退；
  AST 深度/节点数上限拦截 RecursionError
- P2 极端有限范围生成 nan SVG：校验坐标跨度有限且 >0，回退安全范围；
  _polyline 拒绝非有限像素坐标
- P3 更新接口契约文档：function-plot 静态 SVG 已实现

Co-Authored-By: Claude Code <noreply@anthropic.com>
fix(export): 为函数图像与导出产物增加资源上限 124024a547 
针对 PR 审阅「函数数量没有限制，可能生成数百 MB 的 SVG」：

- parser: 单块 function-plot 表达式上限 _MAX_EXPRESSIONS=16，超限整块回退
- html: 单篇文档函数图像上限 _MAX_FUNCTION_PLOTS=16，超出回退源码占位
- service: 输入源 MAX_MARKDOWN_CHARS、产物 MAX_EXPORT_BYTES，超限分别
  拒绝创建或标记 failed（EXPORT_OUTPUT_TOO_LARGE）
- 补充 4 条回归测试与文档说明

Co-Authored-By: Claude Code <noreply@anthropic.com>
fix(export): 增加文档级组合复杂度预算与并发渲染限制 c9c5f81d49 
针对 PR 审阅 P1「组合复杂度仍可长时间占满导出线程」与 P3「EXPORT_OUTPUT_TOO_LARGE 误标 HTTP 413」：

- plot: FunctionPlot 记录整块 AST 节点数（node_count），parser 累计
- html: 单篇文档累计节点预算 _MAX_TOTAL_PLOT_NODES=8000，超限回退占位
- service: 并发渲染信号量 MAX_CONCURRENT_RENDERS=2，超限额任务排队等待
- docs: 错误码区分同步 HTTP 错误与异步任务错误，EXPORT_OUTPUT_TOO_LARGE 由
  error_code 返回而非 HTTP 413
- 补充节点预算与并发限制两条回归测试（全量 627 通过）

Co-Authored-By: Claude Code <noreply@anthropic.com>
Merge remote-tracking branch 'origin/main' into feat/export-service 966a94cad8 
# Conflicts:
#	backend/app/routes.py
feat(export): 新增 PDF/DOCX 导出与 StaticRenderer 内部契约 406dd42571 
- 新增 PdfExporter（reportlab）与 DocxExporter（python-docx），实现与
  HtmlExporter 一致的同步 render + 异步 export，v1 文本优先（标题/段落/
  行内强调与链接/列表/引用/表格/代码块/数学文本），function_plot 与 mermaid
  保留源码占位并记 warning。
- service 层加 _EXPORTERS 注册表按格式分发，删除 format!=html 硬限制，
  扩展名/MIME/产物清理泛化到 html/pdf/docx 三种格式。
- 新增 app/plot/renderer.py：StaticRenderRequest + StaticRenderer Protocol +
  FunctionPlotStaticRenderer + MermaidStaticRenderer；HtmlExporter 改经
  FunctionPlotStaticRenderer 消费，去除对 render_svg 的直接依赖。
- 补齐 PDF/DOCX 魔法字节、CJK 字体、占位 warning 与 StaticRenderer 契约测试。
- 更新 Export开发说明.md。

Co-Authored-By: Claude Code <noreply@anthropic.com>
Merge remote-tracking branch 'origin/main' into feat/export-service dffafce8b9 
# Conflicts:
#	.gitignore
#	backend/app/main.py
fix(export): 修复引用块正文丢失、嵌套列表顺序与排队取消 780e24a399 
- 引用块直接子节点为块级节点，PDF/DOCX 改为逐个渲染并继承缩进/颜色，
  不再交给行内渲染器导致正文丢失
- PDF 嵌套列表先输出父级正文再输出子列表，修复顺序颠倒
- 等待渲染槽位期间保持 queued 并监听取消，取消即时生效
- DOCX 列表项补处理直接 text 子节点，避免正文被块级渲染器丢弃
- 补充引用块/嵌套列表/排队取消的结构内容回归测试
- 接口契约同步 html/pdf/docx 三格式均已实现，移除 EXPORT_FORMAT_UNSUPPORTED

Co-Authored-By: Claude Code <noreply@anthropic.com>
Merge remote-tracking branch 'origin/main' into feat/export-service 6c14047899
fix(export): 修复列表项行内语义丢失与混合嵌套顺序重排 4fc26a11e1 
- pdf.py `_block_list_item` 改为按 AST 顺序逐段输出：正文暂存为行内标记文本，
  遇嵌套列表先 flush 再递归，之后继续后续正文，保持「父段—子列表—后续段」原始顺序
- pdf.py/docx.py 列表项直接行内节点改走 `_render_inline_node`，保留加粗/链接语义，
  不再只渲染 children 而丢掉格式（PDF 链接以 /URI 注解保留，DOCX 写入 w:hyperlink）
- docx.py `_render_inline_node` 增加 bold/italic 默认值，便于列表项直接调用
- 契约文档 StaticRenderer 状态「计划新增」→「已实现」
- 新增回归测试：混合嵌套顺序、PDF/DOCX 列表项行内语义

Co-Authored-By: Claude Code <noreply@anthropic.com>
feat(export): PDF 内嵌函数图像矢量图 f1ac414866 
- 抽取 render.py 共享几何：新增 PlotGeometry + compute_geometry，render_svg
  改为薄序列化层，SVG 输出与重构前逐字节一致（8 组用例回归验证）
- 新增 app/plot/render_reportlab.py：消费共享几何产出 reportlab 矢量 Drawing
  （网格/坐标轴 Line、曲线 PolyLine、刻度/标签 String、ylabel Group 旋转），
  复用 STSong-Light 渲染中文，按页面内容宽 renderScale 缩放
- pdf.py _block_function_plot 改为内嵌矢量图（解析/渲染失败或超预算回退占位，
  单图失败不阻断整篇）；mermaid 仍占位
- 抽取 FunctionPlotBudget + format_plot_diagnostic 到 _common.py，html/pdf 共用
- 文档同步：PDF 已内嵌函数图像，DOCX 仍占位（栅格化范围外）

Co-Authored-By: Claude Code <noreply@anthropic.com>
fix(export): 裁剪超出范围的曲线并修正 PDF 纵轴标签 edc41fdade 
- 共享几何将曲线裁剪到绘图矩形，避免超出显式 range 的曲线覆盖 PDF 其他内容
- PDF 纵轴标签改为组内局部坐标 + 先平移后旋转，标签边界落回 Drawing 范围内
- 更新 pdf.py 模块说明：function_plot 已内嵌矢量图
- 新增曲线裁剪与纵轴标签边界回归测试

Co-Authored-By: Claude Code <noreply@anthropic.com>
fix(plot): 渐近点落在采样点之间时断段，避免伪竖线 4276cb73c2 
相邻有限采样点分居可见范围上下两侧时说明中间夹着竖直渐近线，
此前只对非有限值断段，会被 Liang-Barsky 裁剪成贯穿绘图区的伪竖线；
现在在共享几何层断段，并新增回归测试断言不存在跨越上下边界的伪连接线段。

Co-Authored-By: Claude Code <noreply@anthropic.com>
Kronecker commented 2026-09-07 00:25:30 +08:00
Owner
Copy Link
Copy Source

审阅结论

暂不建议合并，当前仍有 1 个 P2 问题。

P2：渐近线判断会误删正常的陡峭连续曲线

当前实现将“相邻采样值分别低于 ymin 和高于 ymax”直接判断为中间存在渐近线并断开曲线。

但正常的连续函数也可能在两个采样点之间快速穿过可见范围。例如：

domain: -1, 1
range: -1, 1
y = 1000*(x-0.0025)

实测该函数最终生成 0 个曲线段，整条本应穿过绘图区的直线完全消失。

建议：

  • 对疑似不连续的采样区间进行中点求值或自适应细分。
  • 如果细分过程中找到位于可见范围内的有限点，则说明曲线连续，应保留并使用细分点绘制。
  • 达到细分深度或精度上限后仍无法找到范围内的有限点，再将该区间断开。
  • 增加陡峭连续函数的回归测试，确保修复渐近线问题时不会误删正常曲线。

已确认内容

  • 上一轮的渐近线伪竖线问题已消除。
  • PR 标题和描述已经准确覆盖整个 Export Service。
  • 后端完整测试：720 passed
  • git diff --check：通过
  • 与当前远程 main：无合并冲突
## 审阅结论 暂不建议合并，当前仍有 1 个 P2 问题。 ### P2：渐近线判断会误删正常的陡峭连续曲线 当前实现将“相邻采样值分别低于 `ymin` 和高于 `ymax`”直接判断为中间存在渐近线并断开曲线。 但正常的连续函数也可能在两个采样点之间快速穿过可见范围。例如： ```text domain: -1, 1 range: -1, 1 y = 1000*(x-0.0025) ``` 实测该函数最终生成 0 个曲线段，整条本应穿过绘图区的直线完全消失。 建议： - 对疑似不连续的采样区间进行中点求值或自适应细分。 - 如果细分过程中找到位于可见范围内的有限点，则说明曲线连续，应保留并使用细分点绘制。 - 达到细分深度或精度上限后仍无法找到范围内的有限点，再将该区间断开。 - 增加陡峭连续函数的回归测试，确保修复渐近线问题时不会误删正常曲线。 ## 已确认内容 - 上一轮的渐近线伪竖线问题已消除。 - PR 标题和描述已经准确覆盖整个 Export Service。 - 后端完整测试：`720 passed` - `git diff --check`：通过 - 与当前远程 `main`：无合并冲突
Kronecker closed this pull request 2026-09-07 00:25:30 +08:00

Pull request closed

Please reopen this pull request to perform a merge.
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
saint yxx Kronecker (Kronecker)
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Kronecker/NotesAgentic#41