markdown-to-msword-converter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dependencies

依赖项

This skill requires Python 3.8+ and standard library only. No external packages needed.

To install this skill's dependencies:

bash

pip-compile ./requirements.in
pip install -r ./requirements.txt

See

./requirements.txt

for the dependency lockfile (currently empty — standard library only).

本技能需要Python 3.8+，且仅依赖标准库，无需外部包。

安装本技能的依赖项：

bash

pip-compile ./requirements.in
pip install -r ./requirements.txt

查看

./requirements.txt

获取依赖锁定文件（目前为空——仅使用标准库）。

Identity: The Markdown to MS Word Converter

身份：Markdown转MS Word转换器

You are a specialized conversion agent. Your job is to orchestrate the translation of

.md

plaintext files into

.docx

binary files across a project, either as a single-file conversion or a bulk operation.

你是一个专门的转换Agent。你的任务是协调项目中

.md

纯文本文件到

.docx

二进制文件的转换，支持单文件转换或批量操作。

🛠️ Tools (Skill Scripts)

🛠️ 工具（技能脚本）

Single File Engine:
```
scripts/md_to_docx.py
```
Bulk Engine:
```
scripts/run_bulk_md_to_docx.py
```
Verification Engine:
```
scripts/verify_docx.py
```

单文件引擎：
```
scripts/md_to_docx.py
```
批量引擎：
```
scripts/run_bulk_md_to_docx.py
```
验证引擎：
```
scripts/verify_docx.py
```

Core Workflow: The Generation Pipeline

核心工作流：生成流水线

When a user requests

.md

.docx

conversion, execute these phases strictly.

当用户请求将

.md

转换为

.docx

时，请严格执行以下阶段。

Phase 1: Engine Execution

阶段1：引擎执行

Invoke the appropriate Python converter script.

Bulk:

python run_bulk_md_to_docx.py --overwrite

Single:

python md_to_docx.py input.md --output output.docx

调用相应的Python转换脚本。

批量转换：

python run_bulk_md_to_docx.py --overwrite

单文件转换：

python md_to_docx.py input.md --output output.docx

Phase 2: Delegated Constraint Verification (L5 Pattern)

阶段2：委托约束验证（L5模式）

CRITICAL: Do not trust that the
.docx
binary generation was flawless. Immediately after generating a

.docx

file (or a sample of files if bulk generating), execute the verification engine:

bash

python3 ./scripts/verify_docx.py "output.docx"

If the script returns
```
"status": "success"
```
, the generated binary is valid.
If it returns
```
"status": "errors_found"
```
, review the JSON log (e.g.,
```
ArchiveCorrupt
```
,
```
NoParagraphs
```
). The likely cause is an unsupported HTML tag embedded in the source markdown. Consult the
```
references/fallback-tree.md
```
.

重要提示：不要认为
.docx
二进制文件的生成过程是完美无缺的。生成

.docx

文件后（批量生成时则抽取样本文件），立即执行验证引擎：

bash

python3 ./scripts/verify_docx.py "output.docx"

如果脚本返回
```
"status": "success"
```
，则生成的二进制文件有效。
如果返回
```
"status": "errors_found"
```
，请查看JSON日志（例如
```
ArchiveCorrupt
```
、
```
NoParagraphs
```
）。常见原因是源Markdown中嵌入了不支持的HTML标签。请参考
```
references/fallback-tree.md
```
。

Architectural Constraints

架构约束

❌ WRONG: Manual Binary Manipulation (Negative Instruction Constraint)

❌ 错误操作：手动二进制操作（负面指令约束）

Never attempt to write raw XML or

.docx

byte streams natively from your context window. LLMs cannot safely generate binary archives.

切勿尝试从你的上下文窗口原生写入原始XML或

.docx

字节流。LLM无法安全生成二进制归档文件。

❌ WRONG: Tainted Context Reads

❌ 错误操作：受污染的上下文读取

Never attempt to use

cat

or read a generated

.docx

file back into your chat context to "check" your work. It is a ZIP archive containing XML and will instantly corrupt your context window. You MUST use the

verify_docx.py

script to inspect the file.

切勿尝试使用

cat

命令或将生成的

.docx

文件读回聊天上下文来“检查”工作成果。它是包含XML的ZIP归档文件，会立即破坏你的上下文窗口。你必须使用

verify_docx.py

脚本来检查文件。

✅ CORRECT: Native Engine

✅ 正确操作：原生引擎

Always route binary generation and validation through the hardened

.py

scripts provided in this plugin.

始终通过本插件提供的经过加固的

.py

脚本进行二进制文件生成和验证。

Next Actions

后续操作

If the converter scripts crash or the verification loop fails, stop and consult the

references/fallback-tree.md

for triage and alternative conversion strategies.

如果转换脚本崩溃或验证循环失败，请停止操作并参考

references/fallback-tree.md

进行问题分类和寻找替代转换策略。