Latex2docx

Procedure（Plan → Act → Review）

PLAN（诊断 + 风险点确认）

1. 运行环境自检（只打印建议，不会自动安装）：

pwsh .\\scripts\\doctor.ps1

2. 确认风险点：

• 是否缺 pandoc / python
• 输出路径是否有权限
• 是否需要 reference.docx（强烈推荐，用于版式一致性）

ACT（按缺失项兜底，需用户确认后再执行安装）

缺 Pandoc（Windows）

# 任选其一（执行前需用户同意）
choco install pandoc -y
# 或
winget install --id JohnMacFarlane.Pandoc -e --source winget

pandoc --version

缺 Python（Windows）

# 执行前需用户同意
winget install --id Python.Python.3.11 -e --source winget
python --version

建议使用 venv（可选但推荐）

python -m venv .venv
.\\.venv\\Scripts\\Activate.ps1
python -m pip install -r requirements.txt

ACT（执行转换）

python .\\scripts\\cli.py <INPUT_DIR> <OUTPUT_DOCX> -v `
  --reference-doc <REFERENCE_DOCX> `
  --csl <CSL_FILE>

说明：

• 不需要 --reference-doc/--csl 就移除对应参数
• 默认保留分页符；仅在用户明确要求时才使用 --no-preserve-pagebreaks

REVIEW（验收标准）

• 产物：docx 存在、非 0、可打开
• 引用：能看到参考文献段（若项目含 .bib）
• 图片：关键图片未丢失（若丢失，优先排查相对路径与 \\IfFileExists{...}{...}{...} 分支）
• 分页：\\newpage/\\clearpage 对应位置出现 Word 分页符

Troubleshooting（常见失败与处理）

• Pandoc not found：先确保 pandoc --version 在当前 shell 可用
• pip 安装失败：优先 venv；如有代理/镜像需求，让用户提供可用的 pip 源
• 图片缺失：确认文件存在、路径可从 INPUT_DIR 解析；必要时让用户给出图片目录结构
• 引用未渲染：确认 .bib 被扫描到；需要特定样式时提供 --csl

Included resources（随包提供的资源）

• scripts\\doctor.ps1：环境自检
• templates\\copilot-setup-steps.windows.yml：Copilot Cloud Agent 的 Windows runner 预装模板（复制到容器仓库 .github\\workflows\\copilot-setup-steps.yml）