Template upgrade reference: 2025-12 baseline to 2026-08 current / 模板升级参考：2025-12 基线至 2026-08 当前版

Authors

Affiliations

John Doe

Key Laboratory of Environmental Aquatic Chemistry, State Key Laboratory of Regional Environment and Sustainability, Research Center for Eco-Environmental Sciences, Chinese Academy of Sciences.

Corresponding Author One

Key Laboratory of Environmental Aquatic Chemistry, State Key Laboratory of Regional Environment and Sustainability, Research Center for Eco-Environmental Sciences, Chinese Academy of Sciences.

University of Chinese Academy of Sciences.

Corresponding Author Two

Key Laboratory of Environmental Aquatic Chemistry, State Key Laboratory of Regional Environment and Sustainability, Research Center for Eco-Environmental Sciences, Chinese Academy of Sciences.

University of Chinese Academy of Sciences.

Published

August 13, 2026

范围与基线 / 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 . 混入数据和生成文件。

1. 更新共享框架 / Refresh shared framework

对可适配项目，基于本模板更新：

_metadata.yml、_metadata-protected.yml、_metadata-public.yml、_brand.yml、Makefile；
删除 about.qmd、apple-touch-icon.png（若仍存在）；
更新 README、.gitignore、.githooks/pre-commit 和 scripts/；
添加/更新 MS/Brief.qmd、TODO.qmd、RN/、LOG/、RP/、SD/、TC/ 的入口和模板。

可使用：

# 在 su2023temp 中先预览；仅对干净的兼容仓库使用 --apply
scripts/migrate-manuscript-template.sh ~/manuscript/PROJECT
scripts/migrate-manuscript-template.sh --apply ~/manuscript/PROJECT

# 仅刷新共享 YAML / 品牌 / Makefile；保留目标项目的身份信息
scripts/refresh-shared-config.sh --allow-dirty ~/manuscript/PROJECT

运行前先阅读脚本输出；对非 manuscript 项目、特殊期刊项目或包含非标准部署逻辑的项目，不直接批量应用。

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/PROJECT

GA.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 强制阻止。每次升级提交中仍应写明：基线、迁移范围、未处理的项目特异问题及实际编译结果。

验证 / Verification

基线提交、时间窗口和提交历史已由 Git 检查。
文件变更规模和目录差异已由 Git diff 检查。
当前脚本、配置和 README 已复核，并将限制写入本文。
本页创建后由正常项目渲染流程纳入站点。