Skip to content

Fix PDF and LaTeX export layout for Chinese notes #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Cat-blizzard merged 1 commit into from
May 20, 2026
Merged

Fix PDF and LaTeX export layout for Chinese notes #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 17 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,14 +63,25 @@ Open `outputs\lecture\notes.md`. Images are bundled under `outputs\lecture\notes

## Optional GUI

SlideNote Studio is a Streamlit wrapper around the same CLI pipeline. It lets you upload PPT/PDF files, configure providers, watch progress, and view notes, coverage, usage, and cost reports.
SlideNote Studio is a Streamlit wrapper around the same CLI pipeline. It lets users upload PPT/PDF files, configure API keys in the page, run presets, monitor progress/ETA, inspect token and cost reports, review page-level source traces, and download the generated results.

```powershell
python -m pip install -e ".[dev,llm,gui]"
streamlit run gui/app.py
```

The GUI passes API keys through subprocess environment variables, not command-line arguments. See [gui/README_GUI.md](gui/README_GUI.md) for details.
GUI highlights:

- **API setup without command-line env edits:** API keys entered in the page are passed to the build subprocess through environment variables and are not written to source code or command-line arguments.
- **Speed and cost controls:** exposes `--speed-mode`, global `--concurrency`, `--llm-concurrency`, `--vision-concurrency`, `--ocr-concurrency`, `--figure-concurrency`, shared global cache, OCR/Vision target caps, and page-level `--refresh-pages`.
- **Runtime visibility:** shows readable API states (`Off`, `Missing key`, `Ready`), progress, ETA estimate, stage output, `run_summary.json`, usage files, and token/cost dashboards.
- **Doctor panel:** runs the same environment checks as `slidenote doctor` and shows missing dependencies/API setup hints in the GUI.
- **Review workspace:** provides page explorer views that link original page screenshots, parsed elements, generated notes, page modality, coverage quality, and a manual modality correction manifest.
- **Save and export UX:** supports the default `gui_runs/outputs` workspace or a custom output folder. The sidebar can request `notes.toc.md`, Word `notes.docx`, PDF `notes.pdf`, and LaTeX `notes.tex`, and the results area offers one-click downloads for generated exports and the full result ZIP. Word/LaTeX require Pandoc; PDF is generated from the Word document through LibreOffice for more reliable Chinese/CJK layout. The GUI warns before the run when Pandoc or LibreOffice is missing.

See [gui/README_GUI.md](gui/README_GUI.md) for details.

> GUI export note: Markdown TOC export does not need extra tools. Word and LaTeX use Pandoc, while PDF is produced by converting `notes.docx` with LibreOffice; `export_report.json` records success/failure details. PDF export prefers DOCX → LibreOffice PDF instead of Markdown → LaTeX PDF, because this is much more stable for Chinese/CJK notes. LaTeX remains available as a technical source export.

## Features

Expand All @@ -85,7 +96,7 @@ The GUI passes API keys through subprocess environment variables, not command-li
- Produces `content.json` as the source inventory.
- Produces `notes.md` with hidden source markers by default, plus optional visible page references.
- Produces `coverage.json` / `coverage.md` to flag elements that may be missing from the notes.
- Optional exports can generate `notes.toc.md`, `notes.docx`, `notes.pdf`, and `notes.tex`; Word/PDF/LaTeX require Pandoc.
- Optional exports can generate `notes.toc.md`, `notes.docx`, `notes.pdf`, and `notes.tex`; Word/LaTeX require Pandoc. PDF requires Pandoc plus LibreOffice because it is converted from notes.docx for better CJK layout.
- Optional vision extraction writes OCR text and visual summaries back into the structured content.
- Optional LLM generation supports OpenAI/ChatGPT, DeepSeek, Qwen, Doubao/Volcengine Ark, GLM, Gemini, and Claude.
- Optional `lecture-weave` note strategy first generates detailed per-page explanations, then weaves them into coherent sections.
Expand Down Expand Up @@ -192,7 +203,8 @@ PowerShell `$env:...="..."` values only apply to the current terminal session. F
| Understand diagrams, screenshots, charts, and visual layouts | Configure a vision model API and run with `--vision auto` |
| Preserve PPTX full-slide screenshots | Install LibreOffice, or install PowerPoint + `pywin32` on Windows |
| Process old `.ppt` files | Recommended: install LibreOffice; fallback: manually export to PDF |
| Export Word, PDF, or LaTeX notes | Install Pandoc and run with `--export docx,pdf,latex` |
| Export Word or LaTeX notes | Install Pandoc and run with `--export docx,latex` |
| Export PDF notes | Install Pandoc + LibreOffice and run with `--export pdf`; PDF is converted from `notes.docx` for better CJK layout |

## Installation

Expand Down Expand Up @@ -293,7 +305,7 @@ By default, `notes.md` references bundled image copies under `notes.assets/`. If

`content_guard.json` is generated by default when `--content-guard auto` is enabled. Without `--use-llm`, it records a local heuristic review. With `--use-llm`, SlideNote first preselects candidate tables, formulas, definitions, conditions, OCR text, visual summaries, and non-decorative figures, then asks the text model to classify page roles and element learning roles. Only high-confidence `must_explain` items count toward `required_visible_coverage` and can trigger one natural repair pass; low-confidence items remain audit information.

Extra exports are opt-in. `--export markdown-toc` writes `notes.toc.md` without Pandoc. `--export docx,pdf,latex` uses Pandoc to write `notes.docx`, `notes.pdf`, and `notes.tex`; conversion status and any Pandoc errors are written to `export_report.json`.
Extra exports are opt-in. `--export markdown-toc` writes `notes.toc.md` without Pandoc. `--export docx,latex` uses Pandoc to write `notes.docx` and `notes.tex`; `--export pdf` first builds `notes.docx` with Pandoc and then converts it to `notes.pdf` with LibreOffice; conversion status and any Pandoc errors are written to `export_report.json`.

## Environment Check

Expand Down
19 changes: 15 additions & 4 deletions README.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,14 +63,25 @@ python -m slidenote build path\to\lecture.pdf --out outputs\lecture --use-llm --

## 可选 GUI

SlideNote Studio 是套在同一条 CLI pipeline 外面的 Streamlit 图形界面。它支持上传 PPT/PDF、配置 provider、查看进度，并预览 notes、coverage、usage 和成本报告。
SlideNote Studio 是套在同一条 CLI pipeline 外面的 Streamlit 图形界面。它支持上传 PPT/PDF、在页面内配置 API key、选择运行预设、查看进度/ETA、查看 token 与成本报告、做逐页溯源检查，并下载生成结果。

```powershell
python -m pip install -e ".[dev,llm,gui]"
streamlit run gui/app.py
```

GUI 会通过子进程环境变量传递 API key，不把 key 放进命令行参数。更多说明见 [gui/README_GUI.zh-CN.md](gui/README_GUI.zh-CN.md)。
GUI 亮点：

- **不用命令行配置 API：** 页面中输入的 API key 会通过子进程环境变量传给本次 build，不写入源码，也不放进命令行参数。
- **速度与成本控制：** 暴露 `--speed-mode`、总并发 `--concurrency`、`--llm-concurrency`、`--vision-concurrency`、`--ocr-concurrency`、`--figure-concurrency`、共享全局缓存、OCR/Vision 目标上限和按页 `--refresh-pages`。
- **运行可观测：** 用更直观的 `Off` / `Missing key` / `Ready` 显示 API 状态，并展示进度、ETA、阶段日志、`run_summary.json`、usage 文件和 token/cost dashboard。
- **Doctor 面板：** 在 GUI 内运行与 `slidenote doctor` 同源的环境检查，并展示缺失依赖和 API 配置建议。
- **审阅工作台：** Page explorer 可以联动查看原页截图、解析元素、生成笔记、页面类型、coverage 质量，并保存页面类型人工修正清单。
- **保存与导出体验：** 支持默认 `gui_runs/outputs` 工作区，也支持自定义输出目录；可在侧边栏直接勾选导出 `notes.toc.md`、Word `notes.docx`、PDF `notes.pdf` 和 LaTeX `notes.tex`，生成后可一键下载单个文件或完整结果 ZIP。Word/LaTeX 需要 Pandoc；PDF 会优先通过 LibreOffice 将 notes.docx 转成 notes.pdf，以保证中文/CJK 排版更稳定。GUI 会提前提示缺失依赖。

更多说明见 [gui/README_GUI.zh-CN.md](gui/README_GUI.zh-CN.md)。

> GUI 导出说明：Markdown 目录版不需要额外依赖；Word 和 LaTeX 使用 Pandoc；PDF 会先生成 `notes.docx`，再通过 LibreOffice 转成 `notes.pdf`；`export_report.json` 会记录成功/失败原因。PDF 导出不再默认走 Markdown → LaTeX → PDF，而是优先走 DOCX → LibreOffice PDF，这样中文和图片排版更稳定；LaTeX 仍保留为技术型源码导出。

## 功能

Expand All @@ -86,7 +97,7 @@ GUI 会通过子进程环境变量传递 API key，不把 key 放进命令行参
- 生成 `content.json` 作为原始内容清单。
- 生成 `notes.md`，默认隐藏来源标记，也可选择显示简洁页码或详细元素 ID。
- 生成 `coverage.json` / `coverage.md`，检查哪些元素没有出现在笔记中。
- 可选导出 `notes.toc.md`、`notes.docx`、`notes.pdf` 和 `notes.tex`；Word/PDF/LaTeX 需要安装 Pandoc。
- 可选导出 `notes.toc.md`、`notes.docx`、`notes.pdf` 和 `notes.tex`；Word/LaTeX 需要安装 Pandoc；PDF 需要 Pandoc 和 LibreOffice。
- 支持多家 LLM：ChatGPT/OpenAI、DeepSeek、通义千问、豆包、GLM、Gemini、Claude。
- 支持 `lecture-weave` 高质量笔记策略：先逐页深讲，再按章节编织成连贯笔记。
- 支持控制笔记输出语言和术语策略：英文课件可以生成中文或英文笔记，中文笔记可保留英文专业术语。
Expand Down Expand Up @@ -294,7 +305,7 @@ outputs/lecture/

`content_guard.json` 默认由 `--content-guard auto` 生成。不开 `--use-llm` 时，它只记录本地启发式审查；开启 `--use-llm` 后，SlideNote 会先本地预筛表格、公式、定义、条件、OCR 关键文本、视觉摘要和非装饰图片，再让文本模型判断页面角色和元素级学习角色。只有高置信 `must_explain` 元素会进入 `required_visible_coverage` 并触发最多一次自然修复；低置信元素只保留在审查报告里。

额外导出默认关闭。`--export markdown-toc` 不需要 Pandoc，会写出带目录的 `notes.toc.md`。`--export docx,pdf,latex` 会调用 Pandoc 生成 `notes.docx`、`notes.pdf` 和 `notes.tex`；转换结果和错误摘要会写入 `export_report.json`。
额外导出默认关闭。`--export markdown-toc` 不需要 Pandoc，会写出带目录的 `notes.toc.md`。`--export docx,pdf,latex` 会调用 Pandoc 生成 `notes.docx` 和 `notes.tex`，并用 LibreOffice 将 `notes.docx` 转为 `notes.pdf`；转换结果和错误摘要会写入 `export_report.json`。

## 环境检测

Expand Down
29 changes: 19 additions & 10 deletions ROADMAP.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ SlideNote 当前的核心定位仍然是：
- 支持 Deck Brief 课程全景图：`--deck-brief auto` 可用 LLM 生成课程主题、核心问题、概念依赖关系和页面角色划分，作为后续笔记生成的全局导航。
- 支持 Figure Grounding 图文锚定：`--figure-grounding local|vision` 将图片锚定到页面内最近的文本或表格元素，让笔记中的图片出现在相关概念附近而非堆积在页尾。输出 `figure_grounding.json`。
- 支持 Content Guard：`--content-guard auto` 识别高置信关键学习内容，并对 required visible coverage 做一次自然修复。
- 支持额外导出：带目录 Markdown、Word、PDF、LaTeX；Word/PDF/LaTeX 通过可选 Pandoc。
- 支持额外导出：带目录 Markdown、Word、PDF、LaTeX；Word/LaTeX 通过 Pandoc，PDF 通过 DOCX → LibreOffice 转换以改善中文/CJK 排版。
- 支持基础 SlideNote Studio GUI 和成本报告：上传文件、配置 provider、查看进度、预览输出和 token/cost dashboard。

## 1. 上下文策略增强
Expand Down Expand Up @@ -373,6 +373,9 @@ lecture-weave 第二阶段按 section 编织

基础版已经合入 SlideNote Studio：一个 Streamlit GUI，包装现有 `python -m slidenote build` pipeline，不改核心解析和生成逻辑。它已经支持上传 PPT/PDF、选择预设、填写 provider/API key、配置 OCR/Vision/LLM、设置缓存和并发、查看 `progress.json`、预览 notes/coverage/run summary，并生成 token/cost 报告。

**2026-05 GUI 导出补齐：** Studio 现在可以在侧边栏直接选择 Markdown TOC、Word、PDF 和 LaTeX 导出，并在结果区提供 Exports 标签页、单文件下载和完整 ZIP 下载。Pandoc 或 LibreOffice 缺失时 GUI 会提前提示，不影响基础 notes.md 生成；转换状态写入 `export_report.json`。


当前基础版已经实现：

- 降低 API key 配置门槛。
Expand Down Expand Up @@ -1471,18 +1474,24 @@ CLI 对新手不够友好，尤其是多个服务商都要 key。

### P0：近期最值得做

已完成基础版，后续增强：
已完成或已具备基础可用能力：

- `slidenote doctor` 环境检测：已实现完整命令行诊断；后续补 GUI 一键诊断和更友好的 API key 配置引导。
- 运行进度系统：CLI 实时进度、`progress.json`、`run_summary.json` 已完成；后续补 ETA、失败恢复和更细阶段统计。
- 加速与成本调度：`--speed-mode`、总并发、LLM/Vision/OCR/Figure 细分并发、`--global-cache-dir`、`--refresh-pages` 和临时错误重试已完成；后续补自动限速、只重跑指定小节。
- SlideNote Studio GUI：基础 Streamlit GUI、上传文件、运行预设、进度预览、成本报告已完成；后续补原页/元素/笔记联动视图、doctor 面板和局部 refresh。
- 分层生成策略：Lecture-Weave（`--note-strategy lecture-weave`）已是默认策略；后续补质量评分、自动补回遗漏细节。
- 页面类型检测与处理路由：`page_modalities.json` 已实现；后续补更准的版面分析和 GUI 手动修正。
- 视觉目标选择：装饰图过滤、figure crop 优先级、图片学习价值排序已实现；后续补内容图分类和更强版面分析。
- `slidenote doctor` 环境检测：已实现完整命令行诊断；SlideNote Studio 已补 GUI Doctor 面板，可在页面内查看 Python、核心依赖、可选导出工具、LLM/OCR/Vision API key readiness，并给出基础修复建议。
- 运行进度系统：CLI 实时进度、`progress.json`、`run_summary.json` 已完成；SlideNote Studio 已补 live run 状态、elapsed、ETA 估算、运行日志和结果预览。
- 加速与成本调度：`--speed-mode`、总并发、LLM/Vision/OCR/Figure 细分并发、`--global-cache-dir`、`--refresh-pages` 和临时错误重试已完成；SlideNote Studio 已暴露 speed mode、总并发、细分并发、cache、refresh pages、OCR/Vision target 限制和 token/cost dashboard。
- SlideNote Studio GUI：已支持 Streamlit GUI、上传文件、运行预设、页面内 API key 配置、进度预览、成本报告、自定义保存目录、完整结果 ZIP 下载、Doctor 面板、Quality 面板、Page explorer 原页/元素/笔记联动视图，以及 page modality 手动修正 manifest。
- 分层生成策略：Lecture-Weave（`--note-strategy lecture-weave`）已是默认策略；GUI 已暴露 note strategy、note depth、note context、section detection、deck brief、content guard 等控制项，并在 Quality 面板中展示 coverage score、missing elements 和 repair queue。
- 页面类型检测与处理路由：`page_modalities.json` 已实现；GUI 已支持查看每页 modality，并可保存 `page_modalities.overrides.json` 作为人工修正清单。
- 视觉目标选择：装饰图过滤、figure crop 优先级、图片学习价值排序已实现；GUI 已暴露 Vision/OCR/Figure 相关 target、detail、edge、crop 设置，并可结合 Page explorer 查看页面截图与解析元素。

仍待实现：
仍待实现或进一步增强：

- 自动限速：根据 provider rate limit、错误类型和重试历史自动调整并发。
- 真正的小节级局部重跑：目前 GUI 可传 `--refresh-pages` 做页级 refresh；后续补 section/chapter-level refresh 与依赖结果复用。
- 失败恢复增强：目前支持日志、失败提示和复用输出目录局部重跑；后续补断点续跑、失败阶段回滚和任务恢复。
- 更细阶段统计：后续在 GUI 中展示 parsing / OCR / Vision / LLM / coverage / export 的耗时占比和失败统计。
- 质量评分自动闭环：目前 GUI 展示 coverage 与 repair queue；后续补自动补回遗漏细节、二次生成和质量评分阈值。
- 更强版面分析与内容图分类：后续补更准的图表/流程图/表格/装饰图分类，以及 GUI 中人工选择 OCR/Vision 页和目标图。
- 课程工作区基础模型：Course / Source / Chapter。
- 多 PPT / 多 PDF 课程级整合。
- PPT 章节切分与分批输出：`split` 子命令、`--split-by section`、`section_index.json` 等。
Expand Down
Loading
Loading