overleaf

name	overleaf
description	LaTeX 文档与 Overleaf 项目的首选方案。当需要编写或编辑 .tex 文件、编译 LaTeX 项目并获取 PDF、创建或管理 Overleaf 项目、查看或解决 review 评论时触发。

Overleaf Skill

通过 Git 协议操作 Overleaf 项目文件（克隆、拉取、编辑、提交、推送），通过 REST API 创建新项目，通过 Review API 管理评论线程（列出、解决），通过 Compile API 触发远程编译并下载 PDF。

所有文件级操作（浏览目录、读写文件、创建删除、下载项目）统一通过 git clone/git pull + 本地编辑 + git push 完成，不再使用 WebSocket/REST 逐文件操作。

Skill 目录结构

scripts/ 与本 SKILL.md 同级，位于 SKILL.md 所在目录下：

<skill-dir>/          ← 本 SKILL.md 所在目录
├── SKILL.md
└── scripts/
    ├── ol.sh           # 入口：环境准备 + 转发给 ol.py
    ├── ol.py           # CLI 入口：命令解析与调度
    └── edge_cookies.py # 从 Edge 浏览器提取 Cookie

使用前先确定 SKILL_DIR（从 AGENTS.md 中本 skill 的 <location> 标签推导）：

# <location> 示例：/some/path/overleaf/SKILL.md
# → SKILL_DIR=/some/path/overleaf
SKILL_DIR="$(dirname "$(grep -A1 'name: overleaf' ~/.pi/agent/AGENTS.md | grep location | sed 's/.*<location>\(.*\)\/SKILL.md.*/\1/')")"
# 或直接手动赋值为 <location> 去掉末尾 /SKILL.md 后的路径

⚠️ 始终用 $SKILL_DIR/scripts/ol.sh 调用，不要使用 ~/scripts/ 或其他猜测路径。

环境准备

获取 overleaf 认证信息

Cookie 支持自动获取：当 OVERLEAF_COOKIE 环境变量未设置时，ol.sh 会自动从 macOS Edge 浏览器提取对应域名的 Cookie（需要 Edge 已登录 Overleaf）。

因此通常只需设置 OVERLEAF_HOST，Cookie 会自动处理。推荐在 ~/.config/overleaf/config.env 中保留域名选择；ol.sh 会自动加载该文件：

# 官方 Overleaf（当前选择）
OVERLEAF_HOST="www.overleaf.com"

# 自托管实例（需要时与上一行互换注释）
# OVERLEAF_HOST="overleaf.cyl.qzz.io"

变量名	说明	是否必须
OVERLEAF_HOST	Overleaf 实例域名（不含 https://）	是（默认 www.overleaf.com）
OVERLEAF_COOKIE	浏览器 Cookie 头部字符串	否（未设置时自动从 Edge 获取）

自动获取会按浏览器规则读取目标主机及其父域 Cookie（例如 www.overleaf.com 会同时读取 .overleaf.com 的会话 Cookie），并依赖 macOS Keychain 授权（首次会弹窗确认）。若自动获取失败，可手动设置： 获取 Cookie：浏览器打开 Overleaf → F12 → Network → 任意请求 → Request Headers → Cookie。

export OVERLEAF_COOKIE="overleaf_session2=s%3Axxx; gke-route=yyy"

Git 认证信息

Git 认证与网页/API Cookie 是两套独立凭据。Git 使用系统配置的 osxkeychain credential helper；每个域名仍需单独保存 Git token，不能从 Edge 网页 Cookie 推导或复用。官方站点使用 git.overleaf.com，自托管实例通常使用 <OVERLEAF_HOST>/git。

若 git clone 提示认证失败，需要先为对应 Git 域名配置 token。网页 Cookie 自动读取成功不代表 Git token 已配置。

WSL/自托管实例的账号登录

如果 Overleaf 服务部署在 WSL，且实例使用本地邮箱/密码认证（EXTERNAL_AUTH=none），可以直接使用已有 Overleaf 账号自动获取会话 Cookie，不需要读取 Windows Edge Cookie：

export OVERLEAF_HOST="overleaf.example.com"
export OVERLEAF_EMAIL="[e-mail]"
export OVERLEAF_PASSWORD_FILE="$HOME/.config/overleaf/password"

密码文件必须设置为 600。也可以使用 OVERLEAF_PASSWORD_COMMAND 从 pass 等凭据管理器读取密码。ol.sh 会自动登录、缓存短期会话，并在会话过期后重新登录。

调用方式

Review/获取项目对应 git 地址 的操作通过 wrapper 脚本：

bash "$SKILL_DIR/scripts/ol.sh" <命令> [参数]

Cookie 会自动从 Edge 浏览器获取，无需手动 source 或设置环境变量。

获取 git url后，直接使用 git 命令行进行管理。

命令参考

创建新项目

# 创建空白项目
bash "$SKILL_DIR/scripts/ol.sh" create "My New Paper"

# 创建带 Overleaf 示例内容的项目
bash "$SKILL_DIR/scripts/ol.sh" create "My New Paper" --template example

# 紧凑 JSON 输出
bash "$SKILL_DIR/scripts/ol.sh" create "My New Paper" --compact

输出字段：project_id、project_name、template、git_url、git_clone_url、web_url。

获取项目 Git 地址

# 列出所有项目及其 Git 地址（带缩进 JSON）
bash "$SKILL_DIR/scripts/ol.sh" git urls

# 紧凑 JSON（便于管道处理）
bash "$SKILL_DIR/scripts/ol.sh" git urls --compact

# 覆盖默认 Git 地址前缀（官方默认 https://git.overleaf.com）
bash "$SKILL_DIR/scripts/ol.sh" git urls --base-url "https://git.example.com"

输出字段：project_id、project_name、git_url、git_clone_url。

获取 review 评论线程

# 带缩进 JSON
bash "$SKILL_DIR/scripts/ol.sh" review list "MyProject"

# 紧凑 JSON
bash "$SKILL_DIR/scripts/ol.sh" review list "MyProject" --compact

解决 review 线程

# 使用线程首条消息用户作为 resolve 用户
bash "$SKILL_DIR/scripts/ol.sh" review resolve "MyProject" "69c2745dc0f84b044e000001"

# 显式指定 user_id
bash "$SKILL_DIR/scripts/ol.sh" review resolve "MyProject" "69c2745dc0f84b044e000001" --user-id "69a65a7a8f69a4e6b57d0ddd"

编译项目

# 触发编译，输出带缩进 JSON（含状态、PDF 地址、所有输出文件）
bash "$SKILL_DIR/scripts/ol.sh" compile "MyProject"

# 紧凑 JSON（便于管道处理）
bash "$SKILL_DIR/scripts/ol.sh" compile "MyProject" --compact

# 指定编译引擎（xelatex / pdflatex / lualatex）
bash "$SKILL_DIR/scripts/ol.sh" compile "MyProject" --compiler xelatex

输出字段：status（success / failure / error）、pdf_url、output_files（含 .pdf、.log、.bbl 等）。

编译并下载 PDF

# 编译并下载 PDF，文件名默认为 <项目名>.pdf
bash "$SKILL_DIR/scripts/ol.sh" pdf "MyProject"

# 指定输出路径
bash "$SKILL_DIR/scripts/ol.sh" pdf "MyProject" --output /tmp/paper.pdf

# 指定编译引擎
bash "$SKILL_DIR/scripts/ol.sh" pdf "MyProject" --compiler xelatex

典型工作流

创建项目并开始编辑

# 1. 创建新项目
bash "$SKILL_DIR/scripts/ol.sh" create "My New Paper"

# 2. 从输出中获取 git_clone_url，克隆到本地
git clone https://[e-mail]/git/<project_id> /tmp/my-new-paper

# 3. 编辑文件
# ...编辑 /tmp/my-new-paper/main.tex

# 4. 提交并推送
cd /tmp/my-new-paper
git add -A
git commit -m "initial content"
git push

克隆并编辑项目

# 1. 获取项目 Git 地址
bash "$SKILL_DIR/scripts/ol.sh" git urls

# 2. 克隆项目到本地
git clone https://[e-mail]/git/<project_id> /tmp/my-project

# 3. 本地编辑文件
# ...编辑 /tmp/my-project/main.tex 等

# 4. 提交并推送
cd /tmp/my-project
git add -A
git commit -m "update content"
git push

在已克隆的项目中同步他人更改

当项目已经克隆到本地，提交前需要先拉取协作者的最新更改：

cd /tmp/my-project

# 拉取远端最新更改（rebase 避免产生多余的 merge commit）
git pull --rebase

# 若有冲突，解决后继续
git add -A
git rebase --continue

# 推送本地修改
git push

处理 review 评论

# 1. 查看所有 review
bash "$SKILL_DIR/scripts/ol.sh" review list "MyProject"

# 2. 克隆项目到本地
git clone https://[e-mail]/git/<project_id> /tmp/my-project

# 3. 根据 review 位置信息，在本地编辑对应文件

# 4. 推送修改
cd /tmp/my-project
git add -A
git commit -m "address review comments"
git push

# 5. 解决已处理的 review
bash "$SKILL_DIR/scripts/ol.sh" review resolve "MyProject" "<thread_id>"

编译并获取 PDF

# 1. 推送最新修改
cd /tmp/my-project
git add -A && git commit -m "final edits" && git push

# 2. 编译并下载 PDF
bash "$SKILL_DIR/scripts/ol.sh" pdf "MyProject"

# 3. 或先确认编译状态，再手动下载
bash "$SKILL_DIR/scripts/ol.sh" compile "MyProject"
# 得到 pdf_url 后：
curl -L -b "$OVERLEAF_COOKIE" "<pdf_url>" -o paper.pdf

已知限制

• Cookie 认证依赖浏览器登录状态，过期后需重新获取
• review list/resolve 依赖 Overleaf 内部评论线程与 joinDoc 接口（非官方公开 API），不同私有部署可能有差异
• compile / pdf 依赖 POST /project/{id}/compile 接口（非官方公开 API），不同私有部署可能有差异
• git urls 依赖 GET /user/projects 接口；若实例关闭或 Cookie 无权限会返回 401/403
• Git 推送后 Overleaf 编辑器需刷新页面才能看到更新

依赖

• pyoverleaf：通过 uv tool install pyoverleaf 安装（仅 review 功能需要）
• Python 解释器路径：~/.local/share/uv/tools/pyoverleaf/bin/python
• git：系统 Git 客户端，凭据已配置在 osxkeychain

代码风格偏好

扩展或修改本 skill 的脚本时，优先拆分为多个子模块，而非将所有逻辑堆入单一文件：

scripts/
  ol.sh              # 入口：环境准备 + 转发给 ol.py
  ol.py              # CLI 入口：只做命令解析与调度，不含业务逻辑
  edge_cookies.py    # 子模块：从 Edge 浏览器提取 Cookie
  api.py             # 子模块：Overleaf REST/WebSocket API 封装
  git_utils.py       # 子模块：Git URL 构造与项目列表
  review.py          # 子模块：review 线程获取与解析
  compile.py         # 子模块：编译与 PDF 下载
  ...

每个子模块职责单一，ol.py 只做 import 和 CLI 注册。新增功能时，新建子模块文件，不要直接往 ol.py 追加几百行。