数模论文同步

数模论文同步是一款面向受支持数学建模队伍的 VS Code 扩展。它把论文创建、加入、导入、编译和同步集中在中文图形界面中，日常使用不需要手动执行 Git 命令。

功能

• 在“论文协作中心”分别查看本机保存情况、协作状态和操作结果。
• 通过浏览器登录 AtomGit；退出登录前会再次确认。
• 选择论文保存位置，并在创建前检查路径是否适合 LaTeX 与协作工具使用。
• 使用最新版模板新建论文；有可选模板版本时，可在创建时选择。
• 加入已有远端论文，或导入已有的本地论文目录。
• 打开受管论文文件夹后自动获取远端更新；本地有修改或未保存编辑、版本分叉时停止，并提示手动处理。
• 点击“同步论文”上传已保存的修改、获取对方更新；有未保存编辑时提示先保存，遇到内容冲突时停止，不强制覆盖文件。
• 保存论文后自动记录本地历史；用时间线查看已保存版本、标记重要节点、比较差异或恢复旧版。
• 内容冲突时逐文件查看双方版本，选择采用本地、采用对方或手动合并；确认应用前保留双方原记录，结果不会自动上传。
• 管理远端论文仓库；删除前需要再次输入仓库名确认，并保留本地论文文件。
• 使用项目固定的 XeLaTeX 配置编译 PDF，并提供“修复 XeLaTeX 编译配置”按钮。

使用要求

• Windows
• VS Code 1.95.0 或更高版本
• LaTeX Workshop
• 能够使用 XeLaTeX 的 TeX Live
• 能够访问 AtomGit 的网络连接
• 已加入本扩展支持的 AtomGit 队伍，并拥有该队伍私有模板和论文仓库的访问权限

安装扩展时，VS Code 会尝试一并安装 LaTeX Workshop。扩展运行时不要求另外安装 Git、Node.js 或 Python。

安装

1. 在 VS Code 中打开“扩展”视图。
2. 搜索 @id:math-paper-sync.math-paper-sync。
3. 点击“安装”。已安装旧版本时，点击“更新”。
4. 安装完成后，从活动栏打开“数模论文同步”。

也可以从扩展视图右上角的“…”菜单选择“从 VSIX 安装…”，然后选择获得的 .vsix 文件。登录和论文协作仍需要网络连接。

基本使用

1. 点击“登录 AtomGit”，在浏览器中完成登录。
2. 选择一个不含中文、空格或特殊字符的论文保存位置。
3. 点击“新建论文”“加入已有论文”或“导入本地论文”。
4. 点击“编译 PDF”生成论文；遇到项目编译配置异常时，可先点击“修复 XeLaTeX 编译配置”。
5. 重新打开论文文件夹后，登录验证完成时会自动检查并获取一次远端更新。开始编辑前，可在“协作”状态卡片查看结果。
6. 写作过程中，按 Ctrl+S 保存文件，需要共享时再点击“同步论文”。本机保存不代表其他人已经收到修改。
7. 点击“版本历史”查看时间线，使用“查看差异”“标记版本”或“恢复这个版本”。

自动更新不会保存编辑器内容、提交或上传本地修改，也不进行定时同步。未登录或工作区未受信任时不会开始；本地有修改、双方版本分叉，或远端变更涉及编辑器/编译配置及项目记录时，会保留现场并提示手动处理。离线时仍可继续本地写作和查看已有历史，恢复网络后使用“同步论文”。“截至上次检查已同步”只代表最后一次成功检查的结果，不表示实时协作。

模板只用于生成新论文的初始文件。创建、加入或导入完成后，论文不会自动跟随模板变化。

论文版本历史

• 本地记录：打开受信任的受管论文、通过 VS Code 保存或创建/删除/重命名论文文件后，扩展会记录磁盘上的论文内容。短时间内连续保存会合并，通常在停止保存约 2 秒后记录；其他论文操作进行中时顺延。未保存的编辑不会进入历史，也不会自动上传。
• 时间线：连续普通保存只显示一个“本地保存”节点，展开后按时间查看每条已采集记录，仍可逐条比较和恢复，不删除或覆盖原记录。手动命名的版本、已共享版本、恢复及恢复前保留记录单独显示，并分隔前后的普通保存。给重要记录命名（例如“初稿完成”）即可将其显示为独立节点。本地历史和版本名称只属于此设备、此论文目录，不会随同步传给其他人。
• 查看差异：选择版本及文件，与当前已保存内容作只读比较；不会替换编辑器内未保存的内容。图片等二进制资源不能显示文本差异。
• 恢复旧版：先保存编辑，再确认恢复。扩展先生成“恢复前自动保留”记录，再将选定版本恢复为新的本地记录；旧历史不删除，不自动上传。想撤回恢复，可再恢复“恢复前自动保留”。检测到继续编辑、项目切换或校验失败时会停止；若已经写入部分文件，请先检查当前文件与保留记录，不要直接同步。

历史只覆盖符合检查条件的论文源文件和资源，不是整个工程目录的备份。配置、编译产物、缓存、疑似凭据及特殊链接不纳入记录；恢复不会修改这些排除项。过大或无法安全读取的工程会停止记录，并在本机保存状态下提示历史未记录成功。请保留自己的重要文件备份。

本地历史保存在 VS Code 的扩展数据目录中，不在论文目录内；移动论文目录或清理扩展数据可能使原本地记录不可用。已有共享记录来自本机已获取的历史，列表最多读取近期 50 条，不会为打开历史界面额外联网。

处理论文冲突

1. 保存编辑后点击“同步论文”。遇到可处理的内容冲突时会打开“处理论文冲突”页面；也可点击协作状态中的“处理冲突”，或运行同名命令。
2. 按文件对照“本地内容”和“对方内容”，需要时展开共同基础版本。每个文件都必须明确选择，不会默认采用某一方。
3. 选择“采用本地内容”“采用对方内容”，或在“手动合并”中填写合并后的完整文件内容。选择按整个文件生效，不是逐行自动拼接。二进制文件只支持选择一方；选择已删除的一方会删除该文件，并在确认中提示。
4. 全部选好后点击“保留双方版本并应用”，核对确认窗口。扩展先保留双方原论文内容，再应用选择及一方独有的变更；原记录可从“版本历史”查看和恢复。
5. 检查处理结果，确认无误后再点击“同步论文”共享。关闭或取消冲突页面不会替换论文文件；应用不会自动上传。

冲突页面使用本机已获取的对方版本，不会额外联网。继续编辑、切换论文或版本变化会使原选择失效；失败后先检查文件和保留记录，复制需要保留的手动输入，再重新打开冲突页面。手动输入只在当前页面中保留，关闭页面后不保留。

此功能处理普通论文文件的内容冲突。涉及项目配置变化、文件与目录互换、路径别名、链接、疑似凭据或超出安全大小限制时会停止，不强制改写。双方保留记录遵循上述本地历史范围，不是全目录备份。

数据处理与隐私

• 扩展不包含广告，也不发送独立的使用情况遥测。

• 登录时会打开 AtomGit 授权页面，并通过由 Cloudflare Workers 承载的登录中转服务完成授权结果的一次性交接。该服务为限流使用由连接 IP 派生的摘要；登录会话有效期为 10 分钟，访问令牌的加密交接有效期最长为 90 秒，领取后会立即清除，过期数据由清理任务清除。服务处理位置未固定为单一地区，论文内容不会经过该服务。

• 登录成功后，访问令牌保存在 VS Code 的加密凭据存储（SecretStorage）中，不会写入论文文件或 Git 配置；退出登录会删除扩展保存的令牌。

• 登录验证、仓库列表、模板下载、打开论文时的自动获取更新，以及用户发起的创建、加入、同步和删除操作会直接与 AtomGit 交换必要的账号、仓库元数据和论文内容。自动更新只获取远端内容，不上传本地论文修改。AtomGit 和 VS Code 对这些数据的处理同时受各自服务规则约束。

• 论文保存位置记录在 VS Code 扩展状态中；论文文件、项目元数据、模板缓存、编译结果、本地版本历史及版本名称保存在本机。历史记录包含纳入记录的论文内容，不是加密备份；清除登录凭据不会清除本地历史。XeLaTeX 编译在本机执行。

• 导入操作不会删除或修改原始论文目录。

• 同步不会强制推送，也不会静默覆盖发生冲突的内容。

• 上传前会检查常见凭据、私钥和访问令牌，并排除常见 LaTeX 构建产物。

• 删除远端仓库不会删除本地论文；操作前会显示目标并要求二次确认。

• 创建、导入或同步失败时，本地可恢复文件会被保留，并在界面中显示下一步建议。

请勿把访问令牌写入扩展设置、论文文件或 Git 配置。网络中断或冲突导致同步停止时，请先保留本地论文，再根据界面提示重试或处理冲突。