md2docx

Appearance

Markdown to DOCX 转换工具 - 轻量级架构设计 ​

1. 设计理念 ​

  • 渐进式开发：从最基础功能开始，逐步添加新特性
  • 最小可用原则：每个功能模块都可以独立运行和测试
  • 简单易用：降低架构复杂度，便于维护和打包发布
  • 可测试性：所有功能都要有对应的测试用例
  • 文档驱动：先文档后开发，保持文档与代码的一致性

2. 项目结构 ​

md2docx/
├── src/
│   └── mddocx/              # PyPI 包名 mddocx
│       ├── __init__.py
│       ├── cli.py           # CLI 入口 (mddocx)
│       ├── converter/       # 转换核心
│       │   ├── base.py      # BaseConverter · _reset_state()
│       │   ├── token_processor.py  # token 遍历
│       │   ├── security.py  # 图片 URL/路径安全校验
│       │   ├── errors.py    # 统一错误码
│       │   └── elements/    # 元素转换器（heading/text/list/...）
│       └── webui/           # Flask Web 界面 (mddocx-webui)
│           ├── app.py       # 路由 · bleach 预览 · CSRF
│           ├── config.py    # 默认 HOST 127.0.0.1
│           ├── rate_limit.py
│           ├── templates/
│           ├── static/
│           └── tests/
├── tests/                   # 单元 + 集成测试
│   ├── unit/
│   ├── integration/
│   └── samples/
├── docs/                    # 01–07 阅读序，见 docs/README.md
├── scripts/
│   └── batch_convert.py
├── .github/workflows/       # CI/CD (ci.yml · publish.yml)
├── pyproject.toml           # 依赖与构建（唯一依赖源）
├── plan.md                  # Sprint 编排（jwplan/jwrun）
└── README.md

3. 功能开发路线 ​

阶段一：基础文本结构（已完成） ​

  1. 标题转换（h1-h6）
    • 基础转换类设计
    • 标题层级和样式支持
    • 完整测试用例
  2. 段落和文本样式
    • 段落格式
    • 粗体、斜体
    • 删除线
  3. 引用块
    • 单层引用
    • 多层嵌套引用

阶段二：列表和代码（已完成） ​

  1. 列表转换
    • 无序列表（* - +）
    • 有序列表（1. 2. 3.）
    • 多级列表缩进
  2. 代码支持
    • 行内代码
    • 代码块
    • 基础语法高亮

阶段三：链接和图片（已完成） ​

  1. 链接处理
    • 内联链接
    • 引用链接
    • URL 自动链接
  2. 图片支持
    • 本地图片
    • 在线图片
    • 图片尺寸调整

阶段四：表格和分隔符（已完成） ​

  1. 表格转换
    • 基础表格
    • 对齐方式
    • 表格样式
  2. 分隔线
  3. 任务列表（TODO）

阶段五：高级功能（已完成 v0.5.x） ​

  1. ✅ 数学公式（LaTeX · CodeCogs PNG）
  2. ✅ Mermaid（graph/flowchart/sequence/gantt/state/class/pie · mermaid.ink）
  3. ✅ HTML 块（html-for-docx 可选依赖）
  4. ✅ 统一错误码（errors.py）

阶段六：界面与架构（已完成 v0.4.x–v0.5.x） ​

  1. ✅ Web 编辑器与文件上传
  2. ✅ 实时预览（bleach 消毒）
  3. ✅ DOCX 导出下载
  4. ✅ CSRF / CSP / SSRF 防护 · per-IP 限流
  5. ✅ TokenProcessor 拆分（base.py 精简）
  6. 🔲 自定义样式配置（远期）

4. 核心设计 ​

转换器设计 ​

python
class BaseConverter:
    """基础转换器，处理文档结构"""
    def convert(self, md_text: str) -> Document:
        pass

class ElementConverter:
    """元素转换器基类"""
    def convert(self, element: Any) -> Any:
        pass

# 示例：标题转换器
class HeadingConverter(ElementConverter):
    """处理 h1-h6 标题"""
    def convert(self, heading: Any) -> Any:
        pass

5. 开发原则 ​

  1. 独立性

    • 每个转换器独立工作
    • 新功能不影响已有功能
    • 测试覆盖单一功能点

  2. 简单依赖

    • markdown-it-py：Markdown 解析
    • python-docx：DOCX 生成
    • Flask / bleach / flask-wtf：WebUI 与安全
    • requests：在线图片下载

  3. 测试驱动

    • 每个功能都有对应测试
    • 样例文档验证
    • 边界情况处理

6. 打包发布 ​

  1. 依赖管理

    • 最小化依赖
    • 版本锁定
    • 虚拟环境隔离

  2. 打包配置

    • 使用 PyInstaller
    • 单文件模式
    • 资源文件打包

  3. 发布检查

    • 功能完整性验证
    • 依赖完整性检查
    • 启动性能优化

7. 当前阶段任务 ​

  1. ✅ 实现基础转换器
  2. ✅ 完成标题转换功能
  3. ✅ 编写对应测试用例
  4. ✅ 验证导出功能
  5. ✅ 集成AI协作规则系统
  6. ✅ 实现完整Markdown转换功能
  7. ✅ Web 图形界面（Flask WebUI）
  8. ✅ 数学公式、Mermaid、html-for-docx（v0.5.0–v0.5.26）
  9. 🔲 其他 Mermaid 类型（journey/ER 等，见 README）；公式编号已支持（v0.5.35）

8. 开发规范 ​

  1. 代码风格

    • 使用 Black 进行代码格式化
    • 类型注解必须完整
    • 函数必须有文档字符串

  2. 提交规范

    • feat: 新功能
    • fix: 修复问题
    • docs: 文档更新
    • test: 测试相关
    • refactor: 代码重构

  3. 分支管理

    • master: 主分支，稳定版本
    • dev: 开发分支，日常开发
    • feature/*: 功能分支 (从dev分支创建)
    • release/*: 发布分支 (从dev分支创建)

9. 错误处理 ​

  1. 异常体系

    python
    class MD2DocxError(Exception):
    """基础异常类"""
    pass

class ParseError(MD2DocxError):
    """解析错误"""
    pass

class ConvertError(MD2DocxError):
    """转换错误"""
    pass

  2. 错误处理原则

    • 提供清晰的错误信息
    • 保持文档状态一致性
    • 支持错误恢复

10. 版本规划 ​

  1. v0.1.0：基础文本结构（已完成）

    • 标题、段落、文本样式
    • 命令行接口

  2. v0.1.1：AI协作系统集成（已完成）

    • 集成Cursor AI规则系统v3.0.0
    • 智能项目感知和自动进化
    • 多语言协作环境支持

  3. v0.2.0：完整Markdown转换（已完成）

    • 所有类型列表（有序、无序、多级）
    • 代码块支持和基础语法高亮
    • 链接处理（内联、引用、自动链接）
    • 图片支持（本地、在线图片）
    • 表格转换（基础表格、对齐方式）
    • 分隔线和任务列表
    • HTML标签基础支持

  4. v0.4.0：高级功能扩展（已发布）

    • 完整的Web界面功能
    • 自定义样式配置
    • 批量处理界面
    • 主题切换功能

  5. v0.5.0–v0.5.26：产品化增强（已发布）

    • LaTeX 数学公式、Mermaid 流程图
    • html-for-docx 复杂 HTML
    • 架构建议：错误码、TokenProcessor、限流、Dockerfile、mypy 渐进
    • 测试 199 passed

  6. v1.0.0：企业级功能（远期规划）

    • 多格式输出
    • 云端协作
    • 企业级安全和合规

MIT Licensed

Copyright © md2docx contributors