Skip to content

Feature/md to docx#102

Merged
AfishInLake merged 12 commits into
masterfrom
feature/md-to-docx
Jul 13, 2026
Merged

Feature/md to docx#102
AfishInLake merged 12 commits into
masterfrom
feature/md-to-docx

Conversation

@AfishInLake

@AfishInLake AfishInLake commented Jul 12, 2026

Copy link
Copy Markdown
Owner

📌 关联 Issue

  • Closes #xxx
  • Related to #yyy

🎯 变更概述

  • 兼容现有功能（默认选项）
  • 包含破坏性更新（如勾选，请完整填写以下内容）

⚠️ 破坏性更新说明（仅当上方勾选时填写）

  • 受影响的用户场景

    （例如：使用 v0.2 格式配置文件的用户升级后将遇到解析错误）

  • 具体变更点

    （例如：YAML 配置中 style.font_size 字段已移除，改为嵌套结构 style.font.size）

  • 迁移建议

    （例如：请将 font_size: 12 更新为 font: { size: 12 }）

  • 是否提供自动迁移工具？

    • 是（路径：scripts/migrate_v02_to_v03.py）
    • 否

✅ 提交前自查清单

🔹 测试保障

  • 已通过 make test（或等效命令）
  • 新增/修改的功能有对应单元测试（位于 tests/ 目录）
  • 所有测试均使用 io.BytesIO，未保存任何临时 .docx 文件到磁盘
  • 测试覆盖了正常路径、边界情况和错误输入

🔹 配置与兼容性

  • YAML 配置变更向后兼容（旧配置仍能运行，或提供迁移说明）
  • 新增配置项已在 example/ 中提供示例
  • 不依赖未声明的第三方库（requirements.txt 或 pyproject.toml 已更新）

🔹 文档与示例

  • README.md 已更新（如新增功能说明、命令参数）
  • 示例文档（example/）能正常运行且反映最新能力
  • 复杂逻辑已添加必要注释（尤其是涉及 python-docx 底层操作的部分）

🔹 安全与资源

  • 无敏感信息泄露（如 API Key、本地路径）
  • 无内存泄漏风险（如大文档处理时及时释放对象）
  • 未使用不安全的反序列化（如 pickle、yaml.load 未指定 Loader）

🔹 其他

  • 分支基于最新 master 切出，无无关提交
  • Commit 信息清晰（建议遵循 Conventional Commits，如 feat: add table caption check）

💡 温馨提示：勾选 [x] 表示你已确认该项。未勾选项可能成为 Review 阻塞点。

AfishInLake added 12 commits July 12, 2026 17:55
@AfishInLake
新增 Markdown → Docx 转换功能 + 优化 apply 模式批注逻辑
c31ac33 
- 新增 `wordf md` 命令，支持将 Markdown 文件转换为格式化 .docx
- 基于 mistune 解析 Markdown AST，复用现有 FormatNode 树 + YAML 配置驱动的格式管线
- apply 模式采用"先写后 diff"策略：只对修正失败的残留差异写批注，已成功修正的不再产生噪音
- 修复标点检测批注误用红色的问题（标点 → 提醒 → 蓝色）
- 修复 NodeConfigRoot.__getattr__ 对缺失 key 返回 None 导致的 .enabled 崩溃
- 新增 17 个 Markdown 解析器单元测试
@AfishInLake
修复 NODE_TYPE 路径不匹配 + 清理死配置 + 移除 wordformat-skill 自定义脚本
169a1ee 
- FigureImage.NODE_TYPE: "figure_image" → "figures.image"，与 YAML figures.image 对齐
- TableObject.NODE_TYPE: "table_object" → "tables.object"，与 YAML tables.object 对齐
- 移除 tables.content 配置块（无对应 FormatNode 消费者）
- 移除 numbering.captions 配置块（与 figures/tables.rules.caption_numbering 重复）
- 移除 wordformat-skill/scripts/ 目录（自定义验证脚本）
@AfishInLake
统一 NODE_TYPE 命名规范：<类别>.<类型>
2e046cf 
- abstract.chinese.{chinese_title→title, chinese_content→body}
- abstract.english.{english_title→title, english_content→body}
- abstract.{keywords.chinese→chinese.keywords, keywords.english→english.keywords}
- {body_text→body.text}
- {figures→figures.caption, figures.image}
- {tables→tables.caption, tables.object}
- {references.content→references.entry}
- {acknowledgements.content→acknowledgements.body}
- DEFAULTS 内部 key 同步改名（chinese_title→title, etc.）
- 同步更新 YAML 配置和测试夹具
@AfishInLake
框架抽象：DotDict 自动 fallback paragraph/font 子字典 + DEFAULTS/YAML 分组
7461c00 
- DotDict.__getattr__: key 缺失时自动到 paragraph/font 子字典查找
- BASE_FORMAT 改为 {paragraph: {...}, font: {...}} 分组结构
- 所有 FormatNode DEFAULTS 改用 deep_merge(BASE_FORMAT, {...}) 覆盖
- YAML global_format 锚点改用 paragraph/font 分组
- 各节点平铺覆盖字段保持不变，框架透明处理查找
@AfishInLake
完善 md→docx 转换：图片/表格/题注/编号/换行符/内联代码
e167117 
- 图片：FigureImage._try_insert_image 从 value 路径插入实际图片，图在题注上
- 表格：TableObject._try_insert_table 创建 Word 表格，通过 addnext 定位到段落后
- 题注：![alt](path) 自动拆为 figure_image + caption_figure 节点
- 代码块：按行拆为独立 body_text 段落，每行一个节点
- 换行符：parser 层统一 \r\n→\n，apply 时自动清除 <w:br/>
- codespan：_extract_text 补充处理内联代码 `` `xxx` ``
- NodeConfigRoot 加 paragraph/font fallback，编号颜色/字体跟随标题样式
@AfishInLake
完善 md→docx 转换：图片/表格/题注/编号/换行符/内联代码
dce7863 
- 图片：FigureImage._try_insert_image 从 value 路径插入实际图片，图在题注上
- 表格：TableObject._try_insert_table 创建 Word 表格，通过 addnext 定位到段落后
- 题注：![alt](path) 自动拆为 figure_image + caption_figure 节点
- 代码块：按行拆为独立 body_text 段落，每行一个节点
- 换行符：parser 层统一 \r\n→\n，apply 时自动清除 <w:br/>
- codespan：_extract_text 补充处理内联代码 `` `xxx` ``
- NodeConfigRoot 加 paragraph/font fallback，编号颜色/字体跟随标题样式
@AfishInLake
优化 wordformat-skill 文档 + 精简 README AI Skill 段
05f6486 
- SKILL.md: 去掉已删除脚本引用，新增 wordf md 命令，精简为三个流程
- config_spec.md: 更新到新配置路径和 paragraph/font 分组，移除死字段
- category_reference.md: 从 155 行精简到 60 行
- README: 移除 AI Skill 集成段（体验差，浪费 token），保留预设配置说明
@AfishInLake
WordFormatUI 配置路径同步后端 NODE_TYPE 重命名
dcde435 
- 所有配置路径匹配新命名: title/body/keywords/caption/entry/object
- global_format 改用 paragraph/font 分组结构
- style_checks_warning: font_name→font_name_cn+font_name_en, line_spacingrule→line_spacing_rule
- 删除死字段: tables.content, numbering.captions
- FormatConfig.vue 覆盖全部 16 个 paragraph+font 字段，无需改动
@AfishInLake
新增测试：parser 边缘情况 + stages_md + object.py，覆盖率回到 87%
cca59fb 
- parser: 表格/引用/图片+题注/删除线/链接/crlf/内联代码/换行 等 12 个测试
- stages_md: LoadMarkdownStage/MarkdownParseStage/DocumentCreationStage 4 个测试
- object: FigureImage._base/_try_insert_image, TableObject 表格创建/位置 6 个测试
@AfishInLake
修复 stages_md 测试在 Windows 下的 UnicodeEncodeError
7051842 
- 测试内容改用 ASCII，mock logger 避免中文日志触发 charmap 编码错误
@AfishInLake
新增 math 模块：Markdown 数学公式（$...$ / $$...$$）转 OMML
7c110e6 
LaTeX → latex2mathml → MathML → mathml2omml → OMML，基于 python-docx 的
OxmlElement 构建 OMML 元素，集成到 md→docx 管线中：
- 解析器使用 mistune math 插件识别 $ 和 $$ 分隔符
- DocumentCreationStage 渲染 m:oMath / m:oMathPara
@AfishInLake
修复 math_block 丢失 + 清理不存在的 [api] extra 引用
6fe4049 
- 新增 MathBlock FormatNode (@register("math_block"))，避免 node_factory 跳过
- tree_builder 将 math_block 排除在 heading 之外，防止嵌套吸收后续段落
- 移除 README/CLAUDE.md/docs 中所有 wordformat[api] 引用（extra 不存在）
@AfishInLake
AfishInLake merged commit df3e4bf into master Jul 13, 2026
12 checks passed
@AfishInLake
AfishInLake deleted the feature/md-to-docx branch July 13, 2026 06:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@AfishInLake