odt

ODT 文档技能

.odt 文件是一个包含 XML 文件和资源的 ZIP 包。尽可能使用高级库；对于复杂格式、修订或精确控制，则回退到原始 XML。

参考文件

主题	文件
包结构	references/odt-structure.md
修订	references/odt-change-tracking.md
语言/区域设置	references/odt-language.md
XML 模式	references/odf-xml.md
odfdo 库	references/odfdo.md
ODTDocument API	references/odt-document.md
架构验证	references/odf-schemas.md
工具概览	references/tools.md

示例提示词

• “从此 ODT 中提取所有文本，并总结标题和表格。”
• “应用修订来替换这些短语，同时保留修订痕迹。”
• “为所有段落样式设置高棉语语言/区域设置和字体。”
• “验证此 ODT 包并报告缺失的文件。”
• “解包、编辑 content.xml，然后重新打包，且不破坏样式。”

工作流决策树

任务	方法
读取/提取文本	使用 pandoc 或 odfdo-markdown
创建新文档	阅读 references/odfdo.md，使用 odfdo 库
简单编辑	阅读 references/odfdo.md，使用 odfdo 库
修订/注释	阅读 references/odt-document.md，使用 ODTDocument API
复杂 XML 编辑	阅读 references/odf-xml.md，直接编辑 XML

核心操作

文本提取

pandoc document.odt -o document.md      # Convert to Markdown
odfdo-markdown document.odt > out.md    # Alternative

解包/打包工作流

python scripts/unpack_odt.py <file.odt> <dir>   # Unpack
# ... edit XML files ...
python scripts/pack_odt.py <dir> <file.odt>     # Repack

使用 ODTDocument 库

使用 ODTDocument 的脚本需要将 PYTHONPATH 设置为技能根目录。如果从仓库根目录运行，请将其明确指向技能文件夹：

PYTHONPATH=/path/to/repo/skills/odt python your_script.py
# example from repo root
PYTHONPATH=skills/odt python your_script.py

使用 odfdo 创建文档

请先阅读 references/odfdo.md。基本示例：

from odfdo import Document, Paragraph
doc = Document('text')
doc.body.append(Paragraph('Hello'))
doc.save('output.odt')

原始 XML 编辑

请先阅读 references/odf-xml.md。关键文件：

• content.xml — 文档主要内容
• styles.xml — 文档样式
• META-INF/manifest.xml — 包清单（添加文件时需更新）

修订工作流

请阅读 references/odt-change-tracking.md 了解结构详情。关键原则：

• 批量更改：每批将 3–10 项相关更改分组，便于调试
• 尽量少标记：仅标记实际更改的文本

工作流：

1. 转换为 Markdown：pandoc doc.odt -o doc.md
2. 识别更改并将其分批
3. 使用 ODTDocument.suggest_replacement() / suggest_insertion() / suggest_deletion()
4. 验证：python scripts/validate_changes.py content.xml
5. 重新打包并在 LibreOffice 中验证

语言支持（高棉语、泰语、阿拉伯语等）

参见 references/odt-language.md。辅助脚本：

python scripts/set_language.py styles.xml --lang km --country KH --font "Khmer OS System"

将 ODT 转换为 PDF/图像

soffice --headless --convert-to pdf document.odt    # ODT → PDF
pdftoppm -jpeg -r 150 document.pdf page             # PDF → images

依赖项

必需

• odfdo：pip install odfdo（创建/编辑 ODT）
• defusedxml：pip install defusedxml（安全解析 XML）

可选

• pandoc：brew install pandoc（Markdown 转换）
• LibreOffice：brew install --cask libreoffice（ODT → PDF）
• jing：用于 validate_rng.py 的 Relax NG 验证器
• Poppler：brew install poppler（用于 PDF → 图像的 pdftoppm）

验证脚本

python scripts/validate_odt.py <dir> --original <file.odt>     # Package validation
python scripts/validate_changes.py <dir>/content.xml           # Change tracking
python scripts/validate_rng.py <dir>/content.xml               # RNG schema (needs jing)
python scripts/smoke_test.py <file.odt> <work_dir>             # Full roundtrip