omni-re-formatter 0.3.0

Omni-Re-Formatter: 将本地化后的 MD/XLIFF 还原为目标复杂格式

Omni-Re-Formatter (ORF)

ORF 是 Omni 文档本地化生态的最后一环，负责将标准化中间件还原为目标复杂格式。

核心功能

• 读取 OL 翻译后的 MD/XLIFF 及 manifest.json/skeleton.zip
• 调用 Pandoc/md2pptx/translate-toolkit 等成熟轮子
• 配合自研胶水代码（manifest 解析、skeleton 回填、资源路径还原）
• 重组生成本地化的复杂格式文档
• AI Agent 原生集成：通过 MCP Server 对外暴露为 AI Agent Tool，支持 Foreman/Specialist 智能编排

支持格式

MD 回写

• DOCX, ODT, EPUB, HTML, RTF, PDF, PPTX
• ICML (InDesign), SRT (字幕)

XLIFF 回写

• DOCX, PPTX, EPUB, HTML, ODF

云存储

• AWS S3, Azure Blob Storage

AI 辅助

• 布局溢出检测与修正

数据格式

• XLSX, CSV, JSON

结构化标记

• XML

Jupyter 笔记本

• IPYNB

邮件格式

• EML, MSG

安装

# 核心功能
pip install omni-re-formatter

# 开发依赖
pip install -e ".[dev]"

# 可选依赖
pip install -e ".[weasyprint]"   # PDF 生成
pip install -e ".[cloud]"       # S3/Azure 支持
pip install -e ".[ai]"          # AI 布局修正
pip install -e ".[office]"      # XLSX 支持
pip install -e ".[notebook]"    # IPYNB 支持
pip install -e ".[email-output]" # MSG 支持
pip install -e ".[mcp]"         # MCP Server (AI Agent 集成)

快速开始

CLI 使用

# MD 转 DOCX
orf apply-md translated.md --target-format docx --output result.docx

# MD 转 EPUB — JSON 输出
orf apply-md translated.md --target-format epub --output result.epub --json

# XLIFF 回填（需要 skeleton.zip）
orf apply-xliff original.docx --xliff translated.xlf --output result.docx

# XLIFF 回填 + 图片注入（OPP 输出 images.json）
orf apply-xliff original.docx --xliff translated.xlf --output result.docx --images-json images.json

# 批量转换 — JSON 输出
orf convert-batch ./translated --target-format docx --pattern "*.md" --json

MCP Server（AI Agent 集成）

# 启动 MCP Server
orf-mcp-server

# AI Agent 可通过 MCP 协议调用以下工具：
# - apply_md       将 MD 转换为目标格式
# - apply_xliff    应用 XLIFF 翻译到原始文档（含可选图片注入）
# - batch_convert  批量转换 MD 文件
# - detect_format  自动检测文档格式
# - info           获取文档信息

所有 MCP 工具均使用 Pydantic 类型模型 进行输入输出验证，防止因 schema 不匹配导致的调用失败（实测可将此类错误从 38% 降至 0%）。

CLI 命令

命令	说明	JSON 输出
apply-md	将 MD 文件转换为目标格式	--json 支持
apply-xliff	应用 XLIFF 翻译到原始文档	--json 支持
convert-batch	批量转换 MD 文件	--json 支持
info	显示文档信息	--json 支持

AI Agent 原生架构

ORF v0.3.0 重构为 Agent-Oriented 架构，专为 AI Agent 集成设计，而非传统 CLI 工具。

MCP Server — 为 AI Agent 而生

ORF 的 MCP Server 基于 FastMCP 构建，对外提供 5 个工具，AI Agent（Claude、Cursor、OpenCode 等）可通过标准 MCP 协议直接调用 ORF 的文档转换能力。

AI Agent (Claude/Cursor) 
    │
    ▼ MCP 协议
┌──────────────────┐
│  ORF MCP Server   │
│  ┌──────────────┐ │
│  │ apply_md     │ │  ← Pydantic 类型验证
│  │ apply_xliff  │ │  ← 路径安全校验
│  │ batch_convert│ │  ← 子进程隔离
│  │ detect_format│ │
│  │ info         │ │
│  └──────────────┘ │
└──────────────────┘

MCP 安全设计：

• PathValidator 防止目录遍历攻击
• 所有路径输入通过 resolve() + 白名单策略校验
• CLI 调用于子进程隔离执行

Foreman + Specialist Agent 编排系统

ORF 内置完整的 Agent 编排系统，可按文档格式自动路由到专业处理单元：

         ┌─────────────────┐
         │  ForemanAgent    │  ← 作业编排编排器
         │  评估复杂度       │
         │  分解子任务       │
         │  调度 Specialist  │
         └──────┬──────────┘
                │
     ┌──────────┼──────────┐
     ▼          ▼          ▼
┌────────┐ ┌────────┐ ┌────────┐
│Format   │ │Data    │ │Markup  │
│Specialist│ │Specialist│ │Specialist│
│docx/odt │ │xlsx/csv│ │xml/html│
│epub/pptx│ │/json   │ │        │
└────────┘ └────────┘ └────────┘
                    ┌────────┐
                    │Email   │
                    │Specialist│
                    │eml/msg │
                    └────────┘

• ForemanAgent：接收作业请求 → 评估复杂度（SIMPLE / MODERATE / COMPLEX）→ 分解子任务 → 路由到 Specialist → 聚合结果
• FormatSpecialist：docx、odt、epub、pptx
• DataSpecialist：xlsx、csv、json
• MarkupSpecialist：xml、html
• EmailSpecialist：eml、msg
• Error Recovery：基于错误码的自动恢复策略（ABORT / SKIP / RETRY / MANUAL_INTERVENTION / FALLBACK）

Human-in-the-Loop (HITL) 审批

对高风险操作提供人工审批流程：

场景	风险等级	需要审批
文件 > 100MB	HIGH	✅
云存储上传（S3/Azure）	HIGH	✅
需人工干预的恢复策略	LIMITED	✅
文件 > 500MB	UNACCEPTABLE	✅
标准操作	LOW	❌

审计追踪

所有操作记录到 logs/audit_{date}.log，每条日志包含：

• correlation_id：跨系统追踪 ID
• agent_id：调用方 Agent 标识
• 时间戳、操作类型、结果状态

架构

src/orf/
├── channels/          # 格式转换通道 (MD→X, XLIFF→X)
├── converters/        # 转换器基类与流式处理
│   └── base.py        # ConversionResult, ErrorDetail, WarningDetail
├── parsers/          # manifest.json, frontmatter 解析
├── detection/         # 格式自动探测
├── resources/        # 图片资源管理
├── skeleton/          # skeleton.zip 加载与回填
├── cloud/            # S3, Azure Blob 客户端
├── ai/               # 布局分析与溢出修正
├── mcp/              # MCP Server (Agent 集成层)
│   ├── server.py     # FastMCP 服务，5 个工具
│   ├── schemas.py    # Pydantic 类型模型
│   ├── security.py   # PathValidator 路径安全
│   └── config.py     # MCP 配置
├── agents/           # Agent 编排系统
│   ├── foreman.py    # ForemanAgent 作业编排器
│   └── specialists/  # 格式专用专业 Agent
│       ├── format_specialist.py    # docx/odt/epub/pptx
│       ├── data_specialist.py      # xlsx/csv/json
│       ├── markup_specialist.py    # xml/html
│       └── email_specialist.py     # eml/msg
├── workflow/         # 工作流引擎
│   └── hitl_approval.py  # 人工审批流程
├── logging/          # 日志系统（含审计追踪）
└── error_handlers/   # 错误处理与恢复策略

项目状态 (v0.3.0)

• Agent-Oriented 架构：MCP Server + Foreman/Specialist + HITL 审批
• 图片精确定位注入：支持 DOCX/PPTX/HTML/EPUB 图片按位置回填
• MCP 工具：5 个类型安全的 Agent 工具（Pydantic 模型验证）
• 路径安全：PathValidator 防止目录遍历
• 审计日志：correlation_id + agent_id 全链路追踪
• 400+ 个测试用例（含 MCP 集成测试 + 端到端管线测试）
• MD 回写: 9 种格式 (DOCX, ODT, EPUB, HTML, RTF, PDF, PPTX, ICML, SRT)
• XLIFF 回写: 5 种格式 (DOCX, PPTX, EPUB, HTML, ODF)
• 云存储: S3 + Azure Blob 集成
• AI: 布局溢出检测与修正
• 数据格式: XLSX, CSV, JSON
• 结构化标记: XML
• Jupyter 笔记本: IPYNB
• 邮件格式: EML, MSG
• 完整的错误处理和日志系统

开发

# 安装开发依赖
pip install -e ".[dev,mcp]"

# 运行测试
pytest tests/

# 仅测试 MCP
pytest tests/test_orf_mcp_server.py -v

# 仅测试端到端管线
pytest tests/test_e2e_omni_pipeline.py -v

# 代码检查
ruff check src/orf
mypy src/orf --ignore-missing-imports

# 构建包
python -m build

Pipeline — Omni Localization Suite

ORF is Step 3 (final step) of the Omni Localization Suite pipeline:

┌────────────────────────────────────────────────────────────────────────┐
│                     OMNI LOCALIZATION SUITE                             │
│                                                                        │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐               │
│  │     OPP     │───▶│     OL      │───▶│     ORF      │               │
│  │  (提取)     │    │   (翻译)    │    │   (回写)    │               │
│  └─────────────┘    └─────────────┘    └─────────────┘               │
│                                                                        │
│  Step 1: OPP        Step 2: OL            Step 3: ORF                  │
│  Extract →          Translate →           Backfill →                  │
│  MD + XLIFF +       MD + XLIFF            DOCX/PPTX                   │
│  skeleton.zip                                                    │
└────────────────────────────────────────────────────────────────────────┘

Complete Workflow

# Step 1: OPP - Extract document to MD/XLIFF + skeleton.zip
opp --target-format=both --source-lang=en --target-lang=zh document.docx

# Step 2: OL - Translate to target language
ol translate-md document.md -s en -t zh -o translated/

# Step 3: ORF - Backfill translated content to target format ← YOU ARE HERE
orf apply-xliff document.docx --xliff translated/document.xlf --output result.docx

Related Projects

• OPP (Omni-Pre-Processor) - PREREQUISITE. Produces skeleton.zip and manifest.json that ORF uses.
• OL (Omni-Localizer) - PREREQUISITE. Produces translated MD/XLIFF that ORF backfills.

许可证

MIT