feat: 新增 DocForge 文档制作工具

[Lance0174]

变更说明

• 新增基于 Rust 与 egui 的 DocForge Windows 桌面工具，提供统一中文图形界面。
• 匹配当前 VitePress 文档目录，支持文档扫描、选择、编辑以及原子保存。
• 提供接近 VS Code 的 Markdown 编辑体验，并将编辑区与文档站预览区并列显示。
• 支持导入视频、自动或手动截取关键画面，并生成或追加 VitePress 教程文档。
• 支持文档图片二次编辑，包括裁剪、矩形框选、箭头、画笔和马赛克。
• 支持多语言翻译、Markdown 预览以及将当前编辑内容和本地图片导出为 PDF。
• 提供 Windows 绿色包构建脚本；构建缓存、临时文件和便携包输出均被忽略，不污染文档仓库。

验证结果

• cargo fmt --check
• cargo clippy --locked --offline --all-targets --all-features -- -D warnings
• cargo test --locked --offline
• 18 项单元测试全部通过

提交范围

• .gitignore
• tools/docforge 下的源码、锁文件、中文使用说明、字体说明与打包脚本

未提交 tools/docforge/target、tmp、out，也未包含当前工作区中 plugin/start/start.md 和 plugin/img/generated 的测试内容。

Summary by Sourcery

引入一个全新的基于 Rust 的 DocForge 桌面工具，用于编写 AUTO-MAS VitePress 文档，支持编辑、翻译、视频教程生成以及 PDF 相关工作流。

New Features:

• 新增 Windows 桌面 GUI 应用程序（DocForge），可以自动发现 AUTO-MAS VitePress 站点结构，并提供类似 VS Code 的 Markdown 编辑器以及实时 VitePress 预览。
• 支持文档健康检查、原子保存以及图片管理，包括打开、标注和更新文档本地的媒体引用。
• 集成视频工具，通过 FFmpeg 捕获帧或关键帧，对其进行标注，并生成或追加结构化的教程 Markdown 以及关联图片。
• 提供翻译工作区，调用兼容 OpenAI 的聊天 API 生成和管理多语言 Markdown 草稿，同时保留 VitePress 特定语法和资源。
• 允许将当前 Markdown（包括本地图片）导出为 PDF，并将 PDF 文本导回 Markdown，支持可选自定义字体和页面预览。
• 提供 CLI，用于在 GUI 应用程序之外进行站点结构扫描、PDF 导入/导出以及视频帧捕获。
• 新增 Windows 打包脚本和本地 Cargo 构建配置，以生成可移植的 DocForge 打包文件，同时避免污染主文档仓库。

Build:

• 为 DocForge 工具新增独立的 Cargo 包，包含其自身依赖和优化后的 release 配置。
• 引入 PowerShell 打包脚本，用于构建 DocForge、打包字体和可选媒体工具，并输出可移植的 ZIP 压缩包。

Documentation:

• 为 DocForge 工具新增中文使用文档和字体说明，解释 AUTO-MAS 文档作者的安装步骤和工作流。

Tests:

• 新增单元测试，用于验证 Markdown 解析与预览、PDF 生成与图片嵌入、标注与裁剪行为、站点发现与路径校验、翻译工具、视频工具以及原子文件操作等核心 DocForge 功能。

Original summary in English

Summary by Sourcery

Introduce a new Rust-based DocForge desktop tool for authoring AUTO-MAS VitePress documentation with editing, translation, video-tutorial generation, and PDF workflows.

New Features:

• Add a Windows desktop GUI application (DocForge) that discovers the AUTO-MAS VitePress site structure and provides a VS Code-like Markdown editor with live VitePress preview.
• Support document health checks, atomic saves, and image management, including opening, annotating, and updating document-local media references.
• Integrate video tooling to capture frames or keyframes via FFmpeg, annotate them, and generate or append structured tutorial Markdown with associated images.
• Provide a translation workspace that calls OpenAI-compatible chat APIs to produce and manage multilingual Markdown drafts while preserving VitePress-specific syntax and assets.
• Enable exporting the current Markdown (including local images) to PDF and importing PDF text back into Markdown, with optional custom fonts and page previews.
• Expose a CLI for scanning site structure, PDF import/export, and video frame capture alongside the GUI application.
• Add a Windows packaging script and local Cargo build setup to produce a portable DocForge bundle without polluting the main docs repository.

Build:

• Add a dedicated Cargo package for the DocForge tool with its own dependencies and optimized release profile.
• Introduce a PowerShell packaging script to build DocForge, bundle fonts and optional media tools, and emit a portable ZIP archive.

Documentation:

• Add Chinese usage documentation and font notes for the DocForge tool, explaining installation and workflow for AUTO-MAS docs authors.

Tests:

• Add unit tests for markdown parsing and preview, PDF generation and image embedding, annotation and cropping behaviour, site discovery and path validation, translation utilities, video tooling, and atomic file operations to validate core DocForge functionality.

[sourcery-ai]

Sorry @Lance0174, your pull request is larger than the review limit of 150000 diff characters

[sourcery-ai]

Reviewer's Guide

介绍用于 AUTO-MAS 文档的 DocForge Windows 桌面工具（Rust + egui），包括用于 Markdown 编辑的完整 GUI 应用、视频帧捕获 → 教程生成、图像标注、通过兼容 OpenAI 的 API 进行翻译、PDF 导入/导出，以及命令行工具和用于构建便携式 Windows 打包的 PowerShell 脚本；更新 .gitignore，并在 tools/docforge 下为该工具添加专用 Cargo workspace。

视频转教程文档生成的序列图

sequenceDiagram
    actor User
    participant DocforgeApp
    participant VideoTool
    participant Tutorial
    participant Atomic
    participant SiteProfile

    User->>DocforgeApp: choose_video()
    DocforgeApp->>VideoTool: discover(None)
    VideoTool-->>DocforgeApp: VideoTool
    User->>DocforgeApp: capture_key_frames(ctx)
    DocforgeApp->>VideoTool: capture_keyframes(video,output_dir,capture_count)
    VideoTool-->>DocforgeApp: Vec_TutorialStep

    User->>DocforgeApp: generate_tutorial_document()
    alt tutorial_target == NewDocument
        DocforgeApp->>SiteProfile: tutorial_document_path(tutorial_language,section,tutorial_file_stem)
        DocforgeApp->>SiteProfile: media_dir_for_section(section)
        loop for each TutorialStep
            DocforgeApp->>Atomic: copy_atomic(step.frame,destination)
        end
        DocforgeApp->>Tutorial: render_document(tutorial_title,tutorial_summary,tutorial_prerequisites,media)
        Tutorial-->>DocforgeApp: markdown_source
        DocforgeApp->>Atomic: atomic_write(target,markdown_source.as_bytes())
        DocforgeApp->>SiteProfile: discover(root)
        SiteProfile-->>DocforgeApp: SiteProfile
    else tutorial_target == CurrentDocument
        DocforgeApp->>SiteProfile: media_dir(document)
        loop for each TutorialStep
            DocforgeApp->>Atomic: copy_atomic(step.frame,destination)
        end
        DocforgeApp->>Tutorial: render_section(tutorial_title,tutorial_summary,media)
        Tutorial-->>DocforgeApp: section_markdown
        DocforgeApp->>DocforgeApp: save_document()
    end

Loading

File-Level Changes

Change	Details	Files
为基于 VitePress 的文档工作区实现 DocforgeApp 的 egui GUI，用于管理文档列表、编辑器、预览、基于视频的教程构建、翻译、PDF 导出/导入，并具备原子文件操作和 UI 状态管理。	定义 DocforgeApp 状态（选中的站点、文档、工作区标签页、Markdown 缓冲区、翻译配置、视频/教程上下文、标注状态、PDF 预览）。 实现站点打开和文档选择时的安全检查（未保存编辑检查、初始文档启发式），使用 SiteProfile 的发现功能。 提供 Markdown 编辑面板，带行号、光标位置跟踪，以及实时的、对 VitePress 友好的预览，包括图像缩略图和校验检查。 添加教程工作区以导入视频、捕获帧（关键帧、均匀帧、手动）、标注图像、将帧插入当前文档或生成新的教程文档，包括媒体复制和 Markdown 渲染。 支持翻译工作区，异步调用兼容 OpenAI 的 /chat/completions API，然后将翻译内容保存到当前缓冲区或对应语言文件中，并以原子方式写入。 支持导出工作区，将当前 Markdown 写入 PDF，可选择自定义字体，并预览渲染出的首页和提取的文本；同时允许从 PDF 导入文本到 Markdown。 实现顶层 egui 布局：顶部栏、带标签的活动栏、文档浏览侧边栏、状态栏，以及路由到相应工作区的中央面板。	tools/docforge/src/app.rs
为 VitePress 文档添加 Markdown 辅助工具：结构检查、内联预览渲染、图像分辨与替换、媒体追加，以及块级预览分段。	实现 check_document，用于验证 H1 标题是否存在、代码围栏是否闭合、VitePress 容器是否闭合、本地图像是否存在，并返回 CheckItem 条目。 提供 image_references 和 resolve_image_path，用于提取图像的 alt/src 对，并解析路径（绝对/站点根路径 vs 相对/文档目录）。 实现 inline_preview_text，以去除常见 Markdown 语法，只显示链接标签。 提供 append_media 辅助函数，用于为教程/媒体章节追加一个标题和图像列表。 实现 preview_blocks，将 Markdown 转换为 PreviewBlock 枚举（标题、段落、代码块、图像、提示块、水平分割线），具备基础容器解析和代码围栏处理。 添加标题提取逻辑，忽略 YAML frontmatter，返回第一个 H1，并为所有工具添加测试。	tools/docforge/src/markdown.rs
引入 PDF 工具，用于将包含嵌入图像的 Markdown 导出为 PDF、检查 PDF、提取文本以用于预览/导入，并使用 Poppler（pdftoppm）将首页渲染为图像。	定义 PdfInfo、PdfPreview 和 PdfExportOptions，以承载元数据、预览数据以及导出配置（字体、文档路径、站点根路径）。 实现 export_markdown_to_pdf，对文本分页，将 Markdown 结构映射到字体样式/缩进，嵌入本地图像，并通过临时文件和 copy_atomic 以原子方式写入。 实现 pdf_to_markdown，使用 pdf-extract 提取文本，并将块转换为简单段落，同时添加一个提示 callout 提醒手动清理。 添加 preview_pdf 和 preview_text，用于检查页数和提取文本，以及 render_first_page，用于查找 pdftoppm 并生成可供 GUI 渲染的 PNG。 实现字体加载：优先选择自定义字体或 Windows CJK 字体；对仅含 ASCII 的内容回退到 Helvetica，并发出警告，同时提供基于 unicode-width 按显示宽度换行的辅助函数。 提供针对换行和验证本地 Markdown 图像在 PDF 中确实生成图像 XObject 的测试。	tools/docforge/src/pdf.rs
实现 DocForge 使用的图像标注与裁剪管线，用于编辑截图或文档图像，支持矩形、箭头、画笔、马赛克和裁剪操作，并以原子方式保存。	定义用于 GUI 工具的 AnnotationKind 和 Annotation 结构体（矩形、箭头、画笔、马赛克、裁剪），并为 UI 提供标签。 实现 AnnotationSession，用于加载图像、累积 Mark 操作，将所有标记渲染到 RgbaImage 上，可选裁剪，并以 PNG 格式原子保存。 提供绘制辅助函数：draw_stroke、draw_box、draw_arrow（带粗线和箭头）、pixelate_area（马赛克效果）以及 normalized_rect，用于将选区限制在图像范围内。 添加 save_annotated，将 egui 归一化坐标转换为像素空间的 Marks，并通过 AnnotationSession 应用它们。 包含测试，以验证 normalized_rect 行为，以及组合矩形/箭头/画笔/马赛克/裁剪操作生成的裁剪输出尺寸符合预期。	tools/docforge/src/annotation.rs
添加针对 AUTO-MAS VitePress 文档树的站点发现和抽象层，包括语言/章节扫描、文档元数据、媒体目录解析，以及教程/翻译目标路径逻辑。	定义 Language 枚举（Zh, En），带标签/前缀，并定义 DocumentRef/SiteProfile 结构，用于记录文档语言、相对/公共路径、标题、章节以及对应文档映射。 实现 SiteProfile::discover，用于验证根目录（.vitepress/config.mts、index.md）、扫描 zh/en 树及章节（使用 walkdir）、构建 DocumentRef 列表、排序，并基于 pair_key 建立语言对应关系。 提供 document_path 和 translation_target_path，带 ensure_inside 检查和父目录自动创建；翻译目标在 zh/en 路径之间对称切换。 实现 media_dir 和 media_dir_for_section，以定位或创建 docs/ /img/generated，并校验 section 是否属于 SECTIONS。 实现 tutorial_document_path，以在指定章节和语言下推导教程 .md 路径，校验 file_stem 是否含非法字符，并安全创建父目录。 添加 frontmatter 感知的标题提取器 first_markdown_heading，以及针对标题解析和非法教程路径拒绝的测试。	tools/docforge/src/site.rs
添加基于 FFmpeg 的视频工具，用于捕获均匀分布帧或关键帧、计算视频时长，并通过原子文件操作与 DocForge 的教程生成工作流集成。	定义 VideoTool 结构体，封装 ffmpeg/ffprobe 路径及 discover 逻辑（优先使用可执行文件旁/ bin 下的路径；否则回退到 PATH），使用 command_works 进行探测。 实现 capture_evenly，根据视频时长计算时间戳并调用 capture_many；实现 capture_at/capture_one 用于单一时间戳抓帧并缩放；实现 capture_keyframes，使用 FFmpeg 场景检测滤镜作为首选，若失败则回退到均匀抓帧。 实现 duration 和 duration_seconds，通过解析 ffprobe 输出获取结果，并带有错误信息；实现 ensure_video 验证文件存在。 提供辅助函数 move_frames 和 unique_path，用于将临时帧移动到 output_dir 中稳定且无冲突的文件名，使用 atomic::copy_atomic。 添加 WindowsCommandExt trait，以设置 creation_flags 隐藏控制台窗口，以及跨平台运行包装器，提供详细错误报告。 在可行处包含针对帧命名/数量的测试。	tools/docforge/src/video.rs
实现兼容 OpenAI 的 Markdown 文档翻译客户端，并提供配置结构和工具，用于规范化端点、从响应中剥离外层代码围栏块，并截断错误消息。	定义 TranslationConfig，包含 endpoint、model、api_key、source_language、target_language，并提供针对 OpenAI /v1 和 gpt-4.1-mini 调优的 Default。 实现 translate_markdown，用于验证配置和源内容，构造带系统 + 用户消息的 ChatRequest 负载（包含保留 Markdown 的指令），调用阻塞式 reqwest 客户端，并解析 ChatResponse；处理非成功 HTTP 状态和格式错误的 JSON，并附加上下文。 添加 normalize_endpoint，确保路径以 /chat/completions 结尾；添加 strip_outer_fence，用于移除返回结果中的 markdown / md 外层包裹；添加 shorten 用于截断过长的错误主体。 提供针对端点规范化和围栏剥离的测试。	tools/docforge/src/translation.rs
添加用于文档仓库内安全写入/复制的原子文件 I/O 工具，具备平台特定的替换语义和目录同步，在 DocForge 中用于保存 Markdown、图像、PDF。	实现 atomic_write，在同一目录中写入唯一命名的临时文件，执行 fsync，然后使用 replace_file 重命名/替换最终目标；sync_directory 确保持久性（Unix 上对目录执行 fsync）。 实现 copy_atomic，读取源字节并委托给 atomic_write。 实现 ensure_inside，对根目录和候选父目录进行规范化，强制最终路径保持在根目录内，并返回安全路径；被 SiteProfile 以及 pdf/Video 工具使用。 实现 Windows 特定的 replace_file，使用 MoveFileExW 和 MOVEFILE_REPLACE_EXISTING	MOVEFILE_WRITE_THROUGH；非 Windows 则使用 fs::rename。 添加测试，验证重复调用 atomic_write 会替换内容，并且目录中不会留下临时文件。
添加统一的 CLI 入口和 GUI 启动器，用于 DocForge，并连接站点扫描、PDF 导入/导出、视频帧捕获等子命令，同时配置 egui/eframe 应用。	定义基于 Clap 的 Cli 结构，带可选 --site 参数和子命令：Scan、ExportPdf、ImportPdf、Capture。 实现 main，根据命令进行分发：Scan → SiteProfile::discover + JSON 输出；ExportPdf → 读取 Markdown，调用 pdf::export_markdown_to_pdf，输出状态/警告；ImportPdf → pdf_to_markdown + atomic_write；Capture → 发现 VideoTool 并调用 capture_keyframes 或 capture_evenly，输出帧路径。 配置 eframe::NativeOptions，并在无子命令时通过 run_native 启动 DocforgeApp，设置视口标题/尺寸约束，并传入可选的 initial_site。 在非调试模式下启用 windows_subsystem = "windows"，以避免 GUI 二进制出现控制台窗口。 连接模块树：annotation、app、atomic、markdown、pdf、site、translation、tutorial、video。	tools/docforge/src/main.rs
添加教程 Markdown 生成助手，将捕获的 TutorialMedia 转换为完整教程文档或章节，带标准化标题、描述和时间戳。	定义 TutorialStep，具有默认标题/描述和可选时间戳，以及 TutorialMedia，携带标题/描述/public_path/时间戳。 实现 render_document，生成完整教程页面（标题、摘要、前置条件、带时间戳和图像的步骤，以及完成提示 callout）。 实现 render_section，在现有文档中生成子章节，带标题/摘要和步骤。 提供 non_empty 和 format_timestamp 辅助函数，用于默认值和人类可读的 MM:SS 时间戳。 添加测试，以验证输出结构（标题、时间戳格式、图像路径、完成 callout）。	tools/docforge/src/tutorial.rs
提供 PowerShell 打包脚本，用于构建并组装 DocForge 的 Windows 便携式包，可选包含 FFmpeg 工具和字体，并生成 ZIP 压缩包。	在运行 cargo build --release --locked 之前，通过环境变量及可选 HTTP(S) 代理配置，为各工具设置独立的 Cargo home/target 目录。 验证构建出的 release 二进制，并在 tools/docforge/out 下清理/重建 outputRoot，防止意外删除预期路径之外的内容。 将 docforge.exe、README、可选的字体目录以及可选的 MediaToolsDirectory（例如 FFmpeg 二进制）复制到便携目录的 bin/ 下。 从便携目录创建 ZIP 压缩包 docforge-portable-windows-x64.zip，并输出路径概要。	tools/docforge/package.ps1
添加 Cargo 清单和辅助文件（锁文件、gitignore、字体 README），用于定义 docforge crate，并将构建产物、临时目录和便携式输出排除在版本控制之外。	为 docforge 创建 Cargo.toml，包含元数据、依赖（eframe/egui、image/imageproc、printpdf/lopdf/pdf-extract、pulldown-cmark、reqwest+rfd、tempfile/walkdir/windows-sys 等），以及调优的 release 配置（LTO、strip、单 codegen 单元）。 添加 tools/docforge/.gitignore，用于忽略构建产物、tmp、target、out 以及其他不应提交的本地/生成内容。 包含 Cargo.lock，以锁定依赖版本并实现可重现构建。 添加 README.zh-CN.txt 和 fonts/README.txt 作为中文使用说明和字体指南的占位/文档。	tools/docforge/Cargo.toml tools/docforge/.gitignore tools/docforge/Cargo.lock tools/docforge/README.zh-CN.txt tools/docforge/fonts/README.txt

---

Tips and commands

Interacting with Sourcery

• 触发新审查： 在拉取请求中评论 @sourcery-ai review。
• 继续讨论： 直接回复 Sourcery 的审查评论。
• 从审查评论生成 GitHub issue： 通过回复某条审查评论让 Sourcery 从该评论创建 issue。你也可以回复审查评论 @sourcery-ai issue 来从评论创建 issue。
• 生成拉取请求标题： 在拉取请求标题的任意位置写上 @sourcery-ai，即可随时生成标题。你也可以在拉取请求中评论 @sourcery-ai title 来（重新）生成标题。
• 生成拉取请求摘要： 在拉取请求正文的任意位置写上 @sourcery-ai summary，即可在该位置随时生成 PR 摘要。你也可以在拉取请求中评论 @sourcery-ai summary 来（重新）生成摘要。
• 生成审查者指南： 在拉取请求中评论 @sourcery-ai guide，即可随时（重新）生成审查者指南。
• 解决所有 Sourcery 评论： 在拉取请求中评论 @sourcery-ai resolve，即可解决所有 Sourcery 评论。如果你已经处理了所有评论且不想再看到它们，这会非常有用。
• 关闭所有 Sourcery 审查： 在拉取请求中评论 @sourcery-ai dismiss，即可关闭所有现有 Sourcery 审查。尤其适用于你希望从一次全新的审查开始——别忘了评论 @sourcery-ai review 来触发新的审查！

Customizing Your Experience

访问你的 dashboard 来：

• 启用或禁用审查特性，例如 Sourcery 生成的拉取请求摘要、审查者指南等。
• 更改审查语言。
• 添加、移除或编辑自定义审查说明。
• 调整其他审查设置。

Getting Help

• 如需提问或反馈，请联系支持团队。
• 访问我们的文档以获取详细指南和信息。
• 通过关注 X/Twitter、LinkedIn 或 GitHub 与 Sourcery 团队保持联系。

Original review guide in English

Reviewer's Guide

Introduce the DocForge Windows desktop tool (Rust + egui) for AUTO-MAS docs, including a full GUI app for Markdown editing, video frame capture → tutorial generation, image annotation, translation via OpenAI-compatible APIs, PDF import/export, plus command-line utilities and a PowerShell script to build a portable Windows bundle; update .gitignore and add a dedicated Cargo workspace for the tool under tools/docforge.

Sequence diagram for video-to-tutorial document generation

sequenceDiagram
    actor User
    participant DocforgeApp
    participant VideoTool
    participant Tutorial
    participant Atomic
    participant SiteProfile

    User->>DocforgeApp: choose_video()
    DocforgeApp->>VideoTool: discover(None)
    VideoTool-->>DocforgeApp: VideoTool
    User->>DocforgeApp: capture_key_frames(ctx)
    DocforgeApp->>VideoTool: capture_keyframes(video,output_dir,capture_count)
    VideoTool-->>DocforgeApp: Vec_TutorialStep

    User->>DocforgeApp: generate_tutorial_document()
    alt tutorial_target == NewDocument
        DocforgeApp->>SiteProfile: tutorial_document_path(tutorial_language,section,tutorial_file_stem)
        DocforgeApp->>SiteProfile: media_dir_for_section(section)
        loop for each TutorialStep
            DocforgeApp->>Atomic: copy_atomic(step.frame,destination)
        end
        DocforgeApp->>Tutorial: render_document(tutorial_title,tutorial_summary,tutorial_prerequisites,media)
        Tutorial-->>DocforgeApp: markdown_source
        DocforgeApp->>Atomic: atomic_write(target,markdown_source.as_bytes())
        DocforgeApp->>SiteProfile: discover(root)
        SiteProfile-->>DocforgeApp: SiteProfile
    else tutorial_target == CurrentDocument
        DocforgeApp->>SiteProfile: media_dir(document)
        loop for each TutorialStep
            DocforgeApp->>Atomic: copy_atomic(step.frame,destination)
        end
        DocforgeApp->>Tutorial: render_section(tutorial_title,tutorial_summary,media)
        Tutorial-->>DocforgeApp: section_markdown
        DocforgeApp->>DocforgeApp: save_document()
    end

Loading

File-Level Changes

Change	Details	Files
Implement the DocforgeApp egui GUI for managing a VitePress-based documentation workspace (document list, editor, preview, video-based tutorial builder, translation, PDF export/import) with atomic file operations and UI state management.	Define DocforgeApp state (selected site, document, workspace tab, markdown buffers, translation config, video/tutorial context, annotation state, PDF preview). Implement site opening and document selection with safety checks for unsaved edits and initial document heuristics, using SiteProfile discovery. Provide Markdown editing panel with line numbers, cursor position tracking, and real-time VitePress-aware preview including image thumbnails and validation checks. Add tutorial workspace to import video, capture frames (key, even, manual), annotate images, insert frames into current doc or generate new tutorial docs, including media copying and markdown rendering. Support translation workspace calling an OpenAI-compatible /chat/completions API asynchronously, then saving translated content either to the current buffer or to the counterpart language file atomically. Support export workspace to write current markdown to PDF, choose custom fonts, and preview the rendered first page + extracted text; also allow importing text from PDF into markdown. Implement top-level egui layout: top bar, activity bar with tabs, document explorer sidebar, status bar, and central panel routing to the appropriate workspace.	tools/docforge/src/app.rs
Add Markdown helper utilities for VitePress docs: structural checks, inline preview rendering, image resolution and replacement, media appending, and block-level preview segmentation.	Implement check_document to validate presence of H1 title, closed code fences, closed VitePress containers, and existence of local images, returning CheckItem entries. Provide image_references and resolve_image_path to extract image alt/src pairs and resolve paths (absolute/site-root vs relative/document directory). Implement inline_preview_text to strip common markdown syntax and show link labels only. Provide append_media helper to append a heading and a list of images for tutorial/media sections. Implement preview_blocks to convert markdown into PreviewBlock enums (headings, paragraphs, code blocks, images, callouts, horizontal rules) with basic container parsing and code fence handling. Add title extraction that ignores YAML frontmatter and returns first H1, plus tests for all utilities.	tools/docforge/src/markdown.rs
Introduce PDF utilities to export markdown (with embedded images) to PDF, inspect PDFs, extract text for preview/import, and render first page to an image using Poppler (pdftoppm).	Define PdfInfo, PdfPreview, and PdfExportOptions to carry metadata, preview data, and export configuration (font, document path, site root). Implement export_markdown_to_pdf which paginates text, maps markdown constructs to font styles/indentation, embeds local images, and writes atomically via temporary file and copy_atomic. Implement pdf_to_markdown that extracts text using pdf-extract and converts blocks into simple paragraphs plus a hint callout about manual cleanup. Add preview_pdf and preview_text for inspecting page count and extracting text, and render_first_page that finds pdftoppm and produces a PNG for GUI rendering. Implement font loading: choose a custom font or Windows CJK font; fallback to Helvetica for ASCII-only content, with warnings, plus helper to wrap text by display width using unicode-width. Provide tests for wrapping and verifying that local markdown image results in a PDF that actually contains an image XObject.	tools/docforge/src/pdf.rs
Implement image annotation and cropping pipeline used by DocForge to edit screenshots or document images, supporting rectangle, arrow, brush, mosaic, and crop operations with atomic saving.	Define AnnotationKind and Annotation structs for GUI tools (rectangle, arrow, brush, mosaic, crop), with labels for UI. Implement AnnotationSession that loads an image, accumulates Mark operations, renders all marks into an RgbaImage, optionally cropping, and saves atomically as PNG. Provide drawing helpers: draw_stroke, draw_box, draw_arrow (with thick lines and arrowheads), pixelate_area (mosaic effect), and normalized_rect for clamping selection to image bounds. Add save_annotated that converts egui-normalized coordinates into pixel-space Marks and applies them via AnnotationSession. Include tests to verify normalized_rect behavior and that combined rectangle/arrow/brush/mosaic/crop operations yield the expected cropped output size.	tools/docforge/src/annotation.rs
Add site discovery and abstraction over the AUTO-MAS VitePress docs tree, including language/section scanning, document metadata, media directory resolution, and tutorial/translation target path logic.	Define Language enum (Zh, En) with labels/prefixes and DocumentRef/SiteProfile structs capturing document language, relative/public paths, title, section, and counterpart mapping. Implement SiteProfile::discover to validate root (.vitepress/config.mts, index.md), scan zh/en trees and sections via walkdir, build DocumentRef list, sort, and establish language counterparts based on pair_key. Provide document_path and translation_target_path with ensure_inside checks and auto-creation of parent directories; translation target swaps between zh/en paths symmetrically. Implement media_dir and media_dir_for_section to locate or create docs/ /img/generated, with validation that section is in SECTIONS. Implement tutorial_document_path to derive tutorial .md path under section and language, validating file_stem for illegal characters and creating parent directories safely. Add frontmatter-aware heading extractor first_markdown_heading and tests for title parsing and invalid tutorial path rejection.	tools/docforge/src/site.rs
Add FFmpeg-based video tooling to capture evenly spaced frames or keyframes, compute video duration, and integrate with DocForge’s tutorial generation workflow using atomic file operations.	Define VideoTool struct that wraps ffmpeg/ffprobe paths and discover logic (prefer alongside executable/bin; fallback to PATH) using command_works probes. Implement capture_evenly to compute timestamps based on video duration and call capture_many; capture_at/capture_one for single timestamp capture with scaling; and capture_keyframes using FFmpeg scene detection filter as primary, falling back to even capture. Implement duration and duration_seconds via ffprobe output parsing, with error messaging, and ensure_video to validate file existence. Provide helper functions move_frames and unique_path to move temporary frames to stable names in output_dir without collisions, using atomic::copy_atomic. Add WindowsCommandExt trait to set creation_flags to hide console window and cross-platform run wrapper with detailed error reporting. Include tests for frame naming / count where feasible.	tools/docforge/src/video.rs
Implement OpenAI-compatible translation client for Markdown documents, with configuration struct and utilities to normalize endpoints, strip surrounding fenced blocks from responses, and truncate error messages.	Define TranslationConfig with endpoint, model, api_key, source_language, target_language and Default tuned for OpenAI /v1 with gpt-4.1-mini. Implement translate_markdown to validate config and source, construct ChatRequest payload (system + user messages) with markdown-preserving instruction, call blocking reqwest client, and parse ChatResponse; handle non-success HTTP status and malformed JSON with context. Add normalize_endpoint to ensure the path ends with /chat/completions, strip_outer_fence to remove markdown/md wrapper if returned, and shorten to truncate long error bodies. Provide tests for endpoint normalization and fence stripping.	tools/docforge/src/translation.rs
Add atomic file I/O utilities for safe writes/copies inside the docs repo, with platform-specific replace semantics and directory sync, used across DocForge (saving markdown, images, PDFs).	Implement atomic_write that writes to a uniquely named temp file in the same directory, fsyncs, and then renames/replaces the final target using replace_file; sync_directory ensures durability (dir fsync on Unix). Implement copy_atomic to read source bytes and delegate to atomic_write. Implement ensure_inside to canonicalize root and candidate parent, enforce that final path remains inside root, and return the safe path; used by SiteProfile and pdf/Video tools. Implement Windows-specific replace_file using MoveFileExW with MOVEFILE_REPLACE_EXISTING	MOVEFILE_WRITE_THROUGH; non-Windows uses fs::rename. Add tests verifying that repeated atomic_write replaces content and leaves no stray temp files in the directory.
Add a unified CLI entrypoint and GUI launcher for DocForge, wired to subcommands for site scanning, PDF import/export, and video frame capture, plus configuration of the egui/eframe app.	Define Clap-based Cli struct with optional --site argument and subcommands: Scan, ExportPdf, ImportPdf, Capture. Implement main to match on command: Scan → SiteProfile::discover + JSON print; ExportPdf → read markdown, call pdf::export_markdown_to_pdf, print status/warnings; ImportPdf → pdf_to_markdown + atomic_write; Capture → discover VideoTool and call capture_keyframes or capture_evenly and print frame paths. Configure eframe::NativeOptions and run_native to start DocforgeApp when no subcommand is given, setting viewport title/size constraints and passing optional initial_site. Enable windows_subsystem = "windows" in non-debug to avoid console window for GUI binaries. Wire module tree: annotation, app, atomic, markdown, pdf, site, translation, tutorial, video.	tools/docforge/src/main.rs
Add tutorial markdown generation helpers to turn captured TutorialMedia into full tutorial documents or sections with standardized headings, descriptions, and timestamps.	Define TutorialStep with default title/description and optional timestamp, and TutorialMedia carrying title/description/public_path/timestamp. Implement render_document to generate a full tutorial page (title, summary, prerequisites, steps with timestamps and images, plus a completion tip callout). Implement render_section to generate a subsection inside an existing doc with heading/summary and steps. Provide non_empty and format_timestamp helpers for defaults and human-readable MM:SS timestamps. Add tests to verify output structure (title, timestamp formatting, image path, completion callout).	tools/docforge/src/tutorial.rs
Provide a PowerShell packaging script to build and assemble a Windows portable bundle for DocForge, including optional FFmpeg tools and fonts, and produce a ZIP archive.	Set up per-tool Cargo home/target directories via environment variables and optional HTTP(S) proxy configuration before running cargo build --release --locked. Validate the built release binary and clean/recreate the outputRoot under tools/docforge/out, guarding against unintended deletion outside the expected path. Copy docforge.exe, README, optional fonts directory, and optional MediaToolsDirectory (e.g., FFmpeg binaries) into the portable directory under bin/. Create a ZIP archive docforge-portable-windows-x64.zip from the portable directory and print summary paths.	tools/docforge/package.ps1
Add Cargo manifest and ancillary files (lockfile, gitignore, font README) to define the docforge crate and keep build artifacts, temp dirs, and portable outputs out of version control.	Create Cargo.toml for docforge with metadata, dependencies (eframe/egui, image/imageproc, printpdf/lopdf/pdf-extract, pulldown-cmark, reqwest+rfd, tempfile/walkdir/windows-sys, etc.), and tuned release profile (LTO, strip, single codegen unit). Add tools/docforge/.gitignore to ignore build artifacts, tmp, target, out and other local/generated content that should not be committed. Include Cargo.lock to lock dependency versions for reproducible builds. Add README.zh-CN.txt and fonts/README.txt placeholders/documentation for Chinese usage and font guidance.	tools/docforge/Cargo.toml tools/docforge/.gitignore tools/docforge/Cargo.lock tools/docforge/README.zh-CN.txt tools/docforge/fonts/README.txt

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.