md-build

md-build — 把 manuscript.md 编译成 Word（第三代·出稿）

当前真源是 manuscript.md；构建新输出，不修改原稿。先按格式档案选择路由。 完整工作流与限制见 ../md-技能套件·用户完全手册.md。

第 0 步 · 工具链（全局安装·只装一次）

格式保留项目优先入口

先检查 <项目>/manifest/format_profile.json。存在时执行本小节；后面的“项目马甲、标题档位、对账、旧过滤器”等仅适用于没有该文件的旧项目。

• 用 build.ps1 -WorkDir <项目> -Mode rebuild 出稿，未指定模式时也默认 rebuild。脚本自动读取格式档案；不重新检测文章语言，不自动套 reference.docx，不按标题页/摘要页等内容用途分类。
• rebuild 保留捕获的 Zotero 活域；live 在需要新引用组时读取原 Word 的 Zotero 文档样式，按真实 key 查询本地 Better BibTeX，新域需在 Word 中 Zotero Refresh；已有引用不必改名为新 key。static 去除 Zotero 域控制代码，保留其显示文字和捕获的格式属性，供校对；解除域仍可能使 Word 重新排版。现有静态验收有两处未解决差异（一处字位置微移、一处脚注文献年份换行），不能承诺与原稿逐像素一致。保格式出稿默认使用 rebuild，不得为通过验收暗中切换模式。
• 标记名称由 formatting/names.json 统一定义；每篇文章的 format_names.md 展示实际中英文对照。语言在摄取时固定，题注标签大小写/中英文另由格式档案控制。
• 普通改稿必须经 md-swarm/apply_formatted_changeset.py 验证后调用原单写者；所有 Div/Span 格式范围和对象 ID 都是必要标记。不能为了通过构建而删除标记、关闭引用默认不删保护或改用旧转换器。
• 阅读 format_capture_report.md 和构建报告。歧义、失去格式范围、缺失引用目标会明确报错。当前未支持：显式 -Reference/-Bib 的保格式导入、叙述式新引用、成组交叉引用等尚未完成，不能静默降级。

出稿与验收

powershell -ExecutionPolicy Bypass -File "<本 skill>\build.ps1" -WorkDir "<项目目录>" -Mode rebuild

产物默认是 <项目>/build/out_rebuild.docx；live/static 对应 out_live.docx/out_static.docx。用 -Out 改输出路径。原 Word 快照只读，已修改内容按当前 Markdown 重建；精确匹配的原生片段只是格式缓存，不是段落修改历史。

构建代码在开始渲染和提交输出前校验路径：输出必须为 .docx，不能位于 manifest/，不能覆盖记录的原 Word、原稿快照或与原稿字节完全一致的文件。新摄取项目记录原稿绝对路径；旧格式项目缺少路径记录时使用原稿SHA识别未改变的原稿及其副本。正常的既有构建输出可以重新生成；遇到拒写应选择新的输出路径，不能删除原稿或格式档案绕过检查。

工具需要 Python 3、lxml 和全局 Pandoc；Pandoc 缺失时运行本目录 setup_md_tools.ps1。格式档案损坏或缺失时必须恢复该项目的档案，不能改走 legacy 来绕过错误。

替换已有图片时读 图片展示与替换。图片文件位于项目 media/，保留对象 ID 并经原改稿入口修改路径；程序保留原尺寸、裁剪和定位。位图替换另需 Pillow，Python 依赖见 format_requirements.txt。SmartArt/组合图等仍按报告保留原生对象，不能称为已支持自由编辑。

修改表格文字时读 表格展示与修改。普通表格以紧凑 Markdown 表展示，复杂表格使用明确的单元格范围；必须保留对象、单元格及格式标记。Markdown 的表头分隔线只是编辑写法，Word 表头、列宽、合并关系仍来自原表。当前不支持增删或移动行列及改变合并关系。

  等标准 Markdown 实体表示原 Word 的不换行空格/连接字符，构建程序会恢复它们。旧格式项目的当前稿需要空格编码迁移时，用 ../md-swarm/apply_formatted_changeset.py --encode-whitespace --manuscript <路径>，先 dry-run；不要重新摄取而丢失已修改内容。