| name | overleaf-project-sync |
| description | 当需要从 Overleaf 网页端项目下载 ZIP、用浏览器开发者工具获取 Overleaf Cookie 和 download/zip 链接、检查本地 LaTeX/论文目录是否与远端 Overleaf 一致、或把远端 Overleaf 文件覆盖同步到本地目录时使用。 |
Overleaf Project Sync
核心原则
- 只从浏览器当前登录会话中临时复制 Overleaf Cookie；不要把 Cookie、项目 ID、下载链接或个人账号信息写入仓库。
- 用
scripts/overleaf_sync.py 执行检查和同步，不要把一次性脚本复制到论文项目根目录。
- 默认不写入本地目录；不传子命令时等价于
check。
- 只有显式执行
update --overwrite 时才把 Overleaf ZIP 中的文件复制到本地；update 不带 --overwrite 也只做 dry-run。
- 脚本会在系统临时目录下载和解压 ZIP，并在结束后自动清理；不要在项目根目录留下
overleaf_tmp.zip、overleaf_tmp/ 等临时文件。
- 同步前先
check，确认差异符合预期后再 update。
- 同步后检查
git status --short 和 git diff --check；不要直接提交未审阅的远端覆盖结果。
从 Overleaf 网页获取参数
- 在浏览器打开 Overleaf 首页并保持登录。
- 按
Ctrl + Shift + C，或用浏览器菜单打开开发者工具。
- 切到
Network 面板。
- 建议勾选
Preserve log，避免从首页跳转到项目页时请求记录被清掉。
- 从 Overleaf 首页点击进入目标项目页，让浏览器产生项目相关请求。
- 在 Network 请求列表中选择一个 Overleaf 请求。优先找这些请求：
- 下载项目 ZIP 的请求；
- URL 中包含
/project/[PROJECT_ID] 的项目页请求；
- URL 中包含
download/zip 的请求；
- 其他发往
www.overleaf.com 且状态码正常的请求。
- 点开请求的
Headers。
- 在
Request Headers 中找到 Cookie，复制 Cookie: 后面的值。
- 通常只需要其中的
overleaf_session2=... 这一段；如果下载返回 401、403 或登录态异常，再复制完整 Cookie 串重试。
- 在项目页找到下载项目 ZIP 的请求或链接，形如：
https://www.overleaf.com/project/[PROJECT_ID]/download/zip
也可以根据项目 URL 手动拼出 ZIP 下载链接：
项目页: https://www.overleaf.com/project/[PROJECT_ID]
ZIP 链接: https://www.overleaf.com/project/[PROJECT_ID]/download/zip
- 把 Cookie 和 ZIP URL 作为环境变量或命令行参数传给脚本。
推荐使用环境变量，避免命令历史里直接出现长 Cookie：
export OVERLEAF_ZIP_URL='https://www.overleaf.com/project/[PROJECT_ID]/download/zip'
export OVERLEAF_COOKIE='overleaf_session2=[SESSION_VALUE]'
如果 Cookie 很长，也可以写到一个本地临时文件，但不要提交：
printf '%s' 'overleaf_session2=[SESSION_VALUE]' > .overleaf-cookie.local
检查本地与远端是否一致
在本地论文目录或 LaTeX 项目目录中运行：
python /path/to/overleaf-project-sync/scripts/overleaf_sync.py --target .
也可以显式传参：
python /path/to/overleaf-project-sync/scripts/overleaf_sync.py check \
--url 'https://www.overleaf.com/project/[PROJECT_ID]/download/zip' \
--cookie-file .overleaf-cookie.local \
--target .
输出含义：
Changed files：两边都有，但内容不同。Missing locally, present in Overleaf：Overleaf 有，本地没有。Extra locally, absent from Overleaf：本地有，Overleaf 没有。- 完全一致时返回
0；发现差异时返回 2，方便脚本化检查。
从 Overleaf 更新本地目录
先 dry-run：
python /path/to/overleaf-project-sync/scripts/overleaf_sync.py update \
--target . \
--dry-run
确认将复制的文件无误后再执行：
python /path/to/overleaf-project-sync/scripts/overleaf_sync.py update \
--overwrite \
--target .
更新行为：
- 只有带
--overwrite 时，远端 ZIP 中未被忽略的文件才会复制到本地同名路径。
- 已存在的本地文件会被覆盖。
- 本地额外文件不会被删除。
- 不会修改
.git/、.codex/、.claude/ 等默认忽略路径。
更新后必须检查：
git status --short
git diff --check
git diff --stat
默认忽略规则
默认忽略适合“本地 repo 中有维护脚本和 agent 文档，Overleaf 只保存论文源文件”的场景：
- 目录：
.git/、.codex/、.claude/、__pycache__/、node_modules/、latex_cache/、backups/、raw/、context/ 等。
- 文件：
*.py、*.pyc、*.md、.gitignore、.gitmodules、AGENTS.md、CLAUDE.md、常见 LaTeX 编译产物。
如果项目确实需要同步某些默认忽略内容，用：
python /path/to/overleaf-project-sync/scripts/overleaf_sync.py check \
--target . \
--no-default-ignores
如果只需要额外忽略某些文件：
python /path/to/overleaf-project-sync/scripts/overleaf_sync.py check \
--target . \
--ignore 'figures/generated/**' \
--ignore '*.bak'
常见问题
HTTP 401 / HTTP 403：Cookie 过期、复制不完整、项目权限不足，重新从浏览器 Network 面板复制 Cookie。HTTP 403 且只复制了 overleaf_session2：检查 session 值是否少字符；如果仍失败，复制完整 Cookie 请求头重试。Missing URL：没有传 --url，也没有设置 OVERLEAF_ZIP_URL。Missing Cookie：没有传 --cookie / --cookie-file，也没有设置 OVERLEAF_COOKIE。- 无法连接 Overleaf、DNS 失败、连接超时或代理端口不可达：检查当前 shell 的代理变量；如果代理污染或代理不可用，临时关闭代理后重试，不要修改长期 shell 配置。
- 差异里出现大量本地脚本或缓存：增加
--ignore，或确认默认忽略规则没有被 --no-default-ignores 关闭。
- 本地文件被覆盖后不符合预期：不要继续提交，先用 Git 查看 diff，并从版本控制恢复或重新运行
check 分析差异。
临时关闭代理示例：
env -u http_proxy -u https_proxy -u HTTP_PROXY -u HTTPS_PROXY -u all_proxy -u ALL_PROXY \
python /path/to/overleaf-project-sync/scripts/overleaf_sync.py --target .
验证脚本本身
修改脚本后至少运行：
python -m py_compile overleaf-project-sync/scripts/overleaf_sync.py
python overleaf-project-sync/scripts/overleaf_sync.py --help
