Word DOCX (OOXML) – docx-md
Overview
Three entry points: Read – output compact Markdown (default, token-efficient) or full JSON; Modify – apply AI-returned edits to the docx; Finalize – accept all revisions and remove all comments. Implemented via OOXML (ZIP + XML). No commercial Word libraries required.
Workflow
| Goal | Action |
|---|
| Get document for AI | Read: run read script → Markdown (default) or JSON. Markdown includes <!-- b:N --> blockIndex markers for edit targeting. |
| Apply AI edits to docx |
Modify: run apply script with docx + edits JSON → new docx with track changes and comments. |
|
Deliver final version |
Finalize: run finalize script → new docx with no revisions/comments. |
LLM-oriented pipeline
- 1. Read – Parse docx; output Markdown (default) or JSON. Markdown uses
<!-- b:N --> prefix per block; revisions: {+inserted+} {-deleted-}; comments: [comment: text]. - Send the output + task prompt to the model; require the model to output only the edit JSON:
blockIndex, originalContent, content, basis . - Modify – Script infers op from
blockIndex, originalContent, content, basis; converts to OOXML (w:ins / w:del / comment anchors), then write back to Word. - Finalize – When the user confirms, run finalize to accept all revisions and remove all comments.
See references/llm-pipeline.md for the Markdown format, JSON schema, and edit format.
1. Read
- - Parse
word/document.xml (w:body only) and word/comments.xml. - Output Markdown (default) or JSON. Markdown is compact and token-efficient.
Script: INLINECODE18
CODEBLOCK0
Options:
- -
-o, --output – Output path (default: stdout) - INLINECODE21 ,
--format – md (default) or INLINECODE24
2. Modify
- - Input: docx path + edit JSON
{ modifications: [{ blockIndex, originalContent, content, basis }] } (same blockIndex as read output). - Flow: Convert JSON to OOXML (
w:ins / w:del / comments), then write back to Word.
Script: scripts/apply_edits_docx.py. Use - as edits file to read JSON from stdin.
CODEBLOCK1
Options: --author (default: "Review")
3. Finalize
- - Accept all revisions (flatten to final text), remove all comments. Save as new docx.
- Uses
docx-revisions to accept revisions (preserves encoding), then removes comment markup via regex on raw bytes.
Script: INLINECODE33
Requires: pip install docx-revisions (see requirements.txt)
CODEBLOCK2
Resources
scripts/
- - readdocx.py – Read: INLINECODE36
- applyeditsdocx.py – Modify: INLINECODE37
- finalizedocx.py – Finalize: INLINECODE38
references/
- - ooxml.md – OOXML layout (document.xml, comments.xml, revisions, comments)
- llm-pipeline.md – Pipeline: read → Markdown/JSON → model edits → modify; defines Markdown format, JSON shape (blockIndex, originalContent, content, basis)
Word DOCX (OOXML) – docx-md
概述
三个入口点：读取 – 输出紧凑型Markdown（默认，节省Token）或完整JSON；修改 – 将AI返回的编辑内容应用到docx；定稿 – 接受所有修订并删除所有批注。通过OOXML（ZIP + XML）实现。无需商业Word库。
工作流程
| 目标 | 操作 |
|---|
| 获取文档供AI处理 | 读取：运行读取脚本 → Markdown（默认）或JSON。Markdown包含用于编辑定位的<!-- b:N -->块索引标记。 |
| 将AI编辑内容应用到docx |
修改：使用docx + 编辑JSON运行应用脚本 → 带有修订标记和批注的新docx。 |
|
交付最终版本 |
定稿：运行定稿脚本 → 无修订/批注的新docx。 |
面向LLM的流水线
- 1. 读取 – 解析docx；输出Markdown（默认）或JSON。Markdown每块使用前缀；修订：{+插入内容+} {-删除内容-}；批注：[comment: 文本]。
- 将输出结果+任务提示发送给模型；要求模型仅输出编辑JSON：blockIndex、originalContent、content、basis。
- 修改 – 脚本从blockIndex、originalContent、content、basis推断操作；转换为OOXML（w:ins / w:del / 批注锚点），然后写回Word。
- 定稿 – 当用户确认后，运行定稿以接受所有修订并删除所有批注。
有关Markdown格式、JSON模式和编辑格式，请参阅references/llm-pipeline.md。
1. 读取
- - 解析word/document.xml（仅w:body）和word/comments.xml。
- 输出Markdown（默认）或JSON。Markdown紧凑且节省Token。
脚本：scripts/read_docx.py
bash
默认：Markdown输出（节省Token）
python3 skills/docx-md/scripts/read_docx.py document.docx
python3 skills/docx-md/scripts/read_docx.py document.docx -o result.md
JSON输出（完整结构）
python3 skills/docx-md/scripts/read_docx.py document.docx -f json -o result.json
选项：
- - -o、--output – 输出路径（默认：标准输出）
- -f、--format – md（默认）或json
2. 修改
- - 输入：docx路径 + 编辑JSON { modifications: [{ blockIndex, originalContent, content, basis }] }（与读取输出的blockIndex相同）。
- 流程：将JSON转换为OOXML（w:ins / w:del / 批注），然后写回Word。
脚本：scripts/applyeditsdocx.py。使用-作为编辑文件从标准输入读取JSON。
bash
python3 skills/docx-md/scripts/applyeditsdocx.py document.docx edits.json -o output.docx
python3 skills/docx-md/scripts/applyeditsdocx.py document.docx - -o output.docx # 标准输入
选项：--author（默认：Review）
3. 定稿
- - 接受所有修订（展平为最终文本），删除所有批注。保存为新docx。
- 使用docx-revisions接受修订（保留编码），然后通过原始字节的正则表达式删除批注标记。
脚本：scripts/finalize_docx.py
要求：pip install docx-revisions（参见requirements.txt）
bash
python3 skills/docx-md/scripts/finalize_docx.py input.docx -o output.docx
资源
scripts/
- - readdocx.py – 读取：python3 scripts/readdocx.py document.docx [-o out.md] [-f md|json]
- applyeditsdocx.py – 修改：python3 scripts/applyeditsdocx.py document.docx edits.json -o output.docx
- finalizedocx.py – 定稿：python3 scripts/finalizedocx.py input.docx -o output.docx
references/
- - ooxml.md – OOXML布局（document.xml、comments.xml、修订、批注）
- llm-pipeline.md – 流水线：读取 → Markdown/JSON → 模型编辑 → 修改；定义Markdown格式、JSON结构（blockIndex、originalContent、content、basis）
