Vector Text Fixer

修复 PDF/SVG 矢量图形中的乱码文本，使其可在 AI 工具中编辑。

功能特性

• 乱码文本检测：自动识别 PDF/SVG 文件中的乱码文本
• 智能修复：基于上下文推断原始文本内容
• 批量处理：支持对文件夹内多个文件进行批量修复
• 格式保留：修复后的文件维持原始矢量格式与版面布局
• AI 辅助编辑：输出中间格式，可导入至 AI 编辑器中使用

支持场景

1. PDF 乱码文本修复

• 因字体嵌入问题导致的方框/问号显示异常
• 因编码转换错误导致的乱码文本
• 因缺失字体替换而生成的异常字符
• 多语言混合编码问题

2. SVG 乱码文本修复

• 文本实体编码错误
• 特殊字符转义问题
• 因无效字体引用导致的显示异常
• XML 编码声明错误

使用方法

命令行方式

# 修复单个 PDF 文件
python scripts/main.py --input document.pdf --output fixed.pdf

# 修复单个 SVG 文件
python scripts/main.py --input diagram.svg --output fixed.svg

# 批量处理文件夹
python scripts/main.py --batch ./input_folder --output ./output_folder

# 交互式修复（手动指定替换内容）
python scripts/main.py --input doc.pdf --interactive

# 导出为可编辑格式（JSON）
python scripts/main.py --input doc.pdf --export-json editable.json

Python API

from scripts.main import VectorTextFixer

# 创建修复器实例
fixer = VectorTextFixer()

# 修复 PDF
result = fixer.fix_pdf("input.pdf", "output.pdf")

# 修复 SVG
result = fixer.fix_svg("input.svg", "output.svg")

# 批量处理
results = fixer.batch_fix("./input_folder", "./output_folder")

# 获取文本映射（用于 AI 编辑）
text_map = fixer.extract_text_map("input.pdf")

输入参数

*--input 与 --batch 至少需指定其一

输出格式

修复后的 PDF/SVG

• 维持原始矢量格式
• 乱码文本被替换为可读内容
• 字体与版面布局保持不变

JSON 导出格式

{
  "file_type": "pdf",
  "pages": [
    {
      "page_num": 1,
      "text_blocks": [
        {
          "id": "tb_001",
          "bbox": [100, 200, 300, 220],
          "original_text": "",
          "detected_encoding": "UTF-8",
          "confidence": 0.3,
          "suggested_fix": "Sample Text"
        }
      ]
    }
  ],
  "fonts_used": ["Arial", "SimSun"],
  "repair_summary": {
    "total_blocks": 15,
    "fixed_blocks": 12,
    "skipped_blocks": 3
  }
}

乱码文本检测规则

本工具采用以下规则检测乱码文本：

1. 替换字符检测：识别 Unicode U+FFFD（）及各类方框字符
2. 控制字符过滤：排除不可见的非打印控制字符
3. 编码一致性检查：检测由混合编码引发的异常
4. 字体回退检测：识别因缺失字体而生成的替代字符
5. 概率模型评估：基于字符频率统计评估乱码可能性

修复策略

Minimal（最小化修复）

• 仅修复明显错误（如替换字符、空字节等）
• 最大程度保留原始文本完整性
• 适用于轻微乱码问题

Standard（标准修复）

• 修复常见编码问题
• 智能字体替换
• 在修复率与准确性之间取得平衡

Aggressive（激进修复）

• 全面执行文本重新编码
• 结合 OCR 辅助识别
• 适用于严重乱码文档

示例

修复单页 PDF

输入：

python scripts/main.py --input report.pdf --output fixed_report.pdf

输出：

✓ Processing: report.pdf
✓ Detected 5 garbled text blocks
✓ Fixed 4 blocks automatically
⚠ 1 block requires manual review
✓ Output saved: fixed_report.pdf
✓ Report saved: fixed_report_repair_log.json

导出可编辑 JSON

输入：

python scripts/main.py --input diagram.svg --export-json editable.json

输出 JSON 结构：

{
  "file_type": "svg",
  "svg_info": {
    "width": 800,
    "height": 600,
    "viewBox": "0 0 800 600"
  },
  "text_elements": [
    {
      "id": "text_1",
      "x": 100,
      "y": 200,
      "font_family": "Arial",
      "font_size": 14,
      "original": "",
      "user_editable": "",
      "confidence": 0.25
    }
  ]
}

依赖项

pdfplumber>=0.10.0      # PDF 解析
PyMuPDF>=1.23.0         # PDF 处理（fitz）
cairosvg>=2.7.0         # SVG 转换
beautifulsoup4>=4.12.0  # SVG 解析
fonttools>=4.40.0       # 字体处理
chardet>=5.0.0          # 编码检测
Pillow>=10.0.0          # 图像处理

限制条件

• 加密 PDF 需在处理前解锁密码
• 严重损坏的矢量文件可能无法完全修复
• 部分罕见字体可能无法正确映射
• 扫描版 PDF 需先通过 OCR 进行文字识别

版本信息

• 版本：1.0.0
• 最后更新时间：2026-02-06
• 状态：已就绪，可供使用

风险评估

安全检查清单

• 无硬编码凭据或 API 密钥
• 无未授权的文件系统访问（如 ../）
• 输出内容不暴露敏感信息
• 已部署防提示注入保护机制
• 输入文件路径已校验（防止 ../ 目录遍历）
• 输出目录限定于 workspace 范围内
• 脚本在沙箱环境中执行
• 错误消息已脱敏（不暴露堆栈跟踪）
• 所有依赖项均已审计

前置条件

# Python 依赖安装
pip install -r requirements.txt

评估标准

成功指标

• 主要功能可正常执行
• 输出结果符合质量标准
• 可优雅地处理边界情况
• 性能表现可接受

测试用例

1. 基础功能：标准输入 → 预期输出
2. 边界情况：非法输入 → 优雅错误处理
3. 性能测试：大数据集 → 可接受的处理耗时

生命周期状态

• 当前阶段：草案（Draft）
• 下次评审日期：2026-03-06
• 已知问题：无
• 计划改进项：
  • 性能优化
  • 新增功能支持