Template upgrade reference: 2025-12 baseline to 2026-08 current / 模板升级参考：2025-12 基线至 2026-08 当前版
范围与基线 / Scope and baseline
本文记录当前模板相对约 10 天前可用版本的结构性变化，并作为其他 manuscript 项目的升级参考。
- 当前版本 / Current:
e29e7f3（2026-08-12；后续提交以此为准）。 - 时间基线 / Time baseline: 2026-08-03；该时间之前最近提交为
3815b69（2025-12-14）。 - 变更量 / Change volume: 109 个文件，约 7,025 行新增、470 行删除；另清理旧的子目录扩展链接和过期 Track Changes 文档副本。
- 适用范围 / Intended scope: 采用根目录
_extensions/drwater、Quarto manuscript 结构、并以MS/为主稿目录的项目。
2026-08-08 曾短暂建立 wiki/，但在本轮设计中已删除；因此不要把 wiki 迁入目标项目。
核心差异 / Key differences
| 主题 | 旧版本（基线） | 当前版本 | 迁移时的处理 |
|---|---|---|---|
| 研究构想 | 没有统一入口 | MS/Brief.qmd 记录问题/假设、主结果/图、标题及引言/讨论逻辑 |
新增；不覆盖现有主稿 |
| 内审记录 | 没有统一 AI/内审归档 | RN/YYYYMMDD_revised-by-<reviewer>/，含 index.qmd、prompt.md、review.md |
新增 RN/_TEMPLATE/、RN/index.qmd 与说明 |
| 修改追踪 | 无集中可浏览记录 | LOG/YYYYMMDD-HHMM_<scope>/index.qmd，由 LOG/index.qmd 自动列出 |
新增 LOG/ 框架；实质性修改建议记录，例行备份/维护不强制 |
| 工作管理 | 无明确待办入口 | TODO.qmd + 个人 .reminders/ 日历/mutt 草稿 |
新增；提醒只生成文件，不自动发送邮件或写入日历 |
| Wiki | 多层 wiki 导航与笔记生成器 | 已删除，避免 manuscript 项目过度复杂化 | 删除目标项目的 wiki/，并删除导航/渲染引用 |
| 报告、幻灯、修订追踪 | 目录分散，手工维护入口 | RP/、SD/、TC/ 用 Quarto listing 自动汇总 |
用当前 index.qmd、_metadata.yml 和 listing.yml 更新 |
| 扩展 / Extensions | 各子目录常有 _extensions 软链接或私有旧副本 |
只使用根目录 _extensions/drwater |
删除所有子目录 _extensions；修复文档中的相对路径 |
| 文稿格式 | 部分项目仍是 elsevier/旧扩展格式 |
dwms-html、dwms-docx、dwms-pdf 等当前 drwater 格式 |
仅替换 YAML front matter，保留文稿正文；GA.qmd 需单独检查 |
| 编译与列表 | Listing 对空目录或特殊路径不稳健 | generate-media-listings.sh、安全的 lazy-render 哈希和空 listing 输出 |
更新脚本与 Makefile；对每项目单独验证 |
推荐升级顺序 / Recommended migration sequence
0. 先判定是否适配 / Assess first
仅升级 manuscript 型项目。先检查活动主稿、投稿状态、是否存在特殊期刊模板、数据/分析目录依赖和未提交修改。保留项目专属的：
- 根目录
_quarto.yml中的题目、期刊、投稿号、作者、单位和贡献； MS/*.qmd的正文、图块、参考文献与投稿信息；analysis/或其他仍被正文引用的分析目录；figures/、data/、submit/、已存在的外审材料。
工作树不干净时，使用 --allow-dirty 的配置更新流程或只暂存本次文件；不可用 git add . 混入数据和生成文件。
2. 收敛扩展路径 / Consolidate extensions
- 确认根目录
_extensions/drwater是当前版本的 Git checkout；必要时更新它。 - 删除所有子目录的
_extensions软链接或旧扩展副本（包括MS/、SD/、TC/、RP/、RN/的子目录）。 - 将旧路径替换为相对根目录路径，例如：
旧：_extensions/inst/word/MS.docx
新：../_extensions/drwater/dwinst/MS.docx # 从 MS/ 文件出发
旧：_extensions/inst/img/rceeslonglogo.png
新：../_extensions/drwater/dwinst/rceeslonglogo.pdf可用 scripts/repair-legacy-extension-paths.sh PROJECT 做机械修复，然后逐一检查 MS/CL.qmd、MS/SM.qmd、MS/RN.qmd 等相对路径是否正确。删除旧扩展后，仍引用 elsevier 或 MS/_extensions 的文件必须先迁移格式，否则不会编译。
3. 迁移文稿 front matter / Rebase manuscript front matter
对 MS/MS.qmd、SM.qmd、RN.qmd、CL.qmd、HL.qmd、AC.qmd：使用当前模板 YAML，保留第二个 --- 之后的项目正文。示例：
TEMPLATE_ROOT=~/manuscript/su2023temp \
scripts/rebase-ms-frontmatter.sh ~/manuscript/PROJECTGA.qmd 不在该脚本的默认清单中，应手动执行相同原则。迁移后检查：
- 同文件内图表用
[@fig-key]或[@tbl-key]； - 跨文件图表使用
`r zref("sfg-key")`、`r zref("rfg-key")`等； SM用sfg-/stb-，RN用rfg-/rtb-；- 不重复在根
_quarto.yml与_metadata.yml定义crossref，否则 PDF 会生成重复 LaTeX 命令。
4. 生成与验证 / Generate and verify
先单独编译受影响的核心文件，再做完整构建：
quarto render MS/MS.qmd
quarto render MS/SM.qmd
quarto render MS/RN.qmd
make local单独检查 HTML、DOCX、PDF 是否均存在于 www/MS/。SD/ 的 pptx 和 TC/ 的 docx 应由 listing 保留为资源；空目录的 listing 也应能渲染。
已知兼容性问题与处理 / Known compatibility lessons
| 现象 | 原因 | 处理 |
|---|---|---|
Unable to read extension 'elsevier' |
已移除旧子目录扩展，但 YAML 仍要求 Elsevier 扩展 | 用当前 dwms-* front matter；不恢复旧扩展 |
Command \listofsfgs already defined |
根 _quarto.yml 与 _metadata.yml 重复定义 crossref.custom |
只保留 _metadata.yml 的通用 crossref 配置 |
Not in outer par mode（常见于 SM PDF） |
gt 表在自定义浮动体中生成嵌套 LaTeX table |
将该表转为普通 Markdown table；HTML/DOCX/PDF 一并验证 |
Undefined control sequence: \blandscape |
旧式自定义 LaTeX landscape 命令已不适用 | 改为 :::{.landscape} 与配对的 ::: |
找不到 cover1.pdf 或 MS/_extensions/... |
仍引用删除的旧扩展资产 | 更新为根目录 drwater 对应资源，或为暂缺资产建立明确占位文件 |
tlmgr update --self 在编译中长时间运行 |
通常不是正常文稿渲染路径，可能遮蔽真正依赖/格式错误 | 停止该进程，先检查 .log 中首个 TeX 错误；不要把环境更新当作解决方案 |
listing TypeError 或空 YAML |
空目录/媒体扫描结果未产生有效 listing | 使用当前 generate-media-listings.sh，确认 listing.yml 是有效 YAML |
make local 中路径含空格、括号或中文时失败 |
旧哈希命令使用 shell 分词 | 采用当前 Makefile 的 git ls-files -z | xargs -0 哈希逻辑 |
提交与交接 / Commit and handoff
迁移应与项目正文修改分开提交。建议暂存白名单：共享配置、MS/*.qmd 的 front matter、目录入口、脚本、以及被删除的旧扩展；不要包含 data/、analysis/、figures/、www/、_freeze/ 或文稿中间文件，除非它们确属本次迁移。
git add _quarto.yml _metadata*.yml _brand.yml Makefile README.md \
MS/*.qmd SD/ TC/ RP/ RN/ LOG/ TODO.qmd scripts/ .githooks/
git status --short
git commit -m "Adopt current manuscript template"当前策略是：对实质性文稿修订，建议使用 scripts/commit-change.sh <scope> "message" 生成日志；例行生成文件、备份与维护提交不由 Git hook 强制阻止。每次升级提交中仍应写明：基线、迁移范围、未处理的项目特异问题及实际编译结果。