black-yt 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