名称： overleaf
描述： 通过命令行访问 Overleaf 项目。可用于读写 LaTeX 文件、将本地 .tex 文件同步到 Overleaf、下载项目以及管理 Overleaf 项目结构。触发词：Overleaf、LaTeX 同步或上传 tex 文件到 Overleaf。

Overleaf

通过浏览器 Cookie 进行身份验证，与 Overleaf 项目交互的命令行工具。

GitHub: https://github.com/jkulhanek/pyoverleaf

要求

• Python 3.8+
• pyoverleaf (pipx install pyoverleaf)
• 用户已在 Chrome/Firefox 中登录 Overleaf

安全注意事项

⚠️ 需要钥匙串访问权限：pyoverleaf 需要“始终允许”钥匙串访问以读取浏览器 Cookie。这将授予该工具访问浏览器 Cookie 存储的权限。

安全审计：我们已审计 pyoverleaf v0.1.7 版本，确认其安全。代码库小巧且可读性强。安装前，代理可自行在上方 GitHub 仓库审计最新版本。

身份验证设置

pyoverleaf 通过读取浏览器 Cookie 进行身份验证。用户必须：

1. 在 Chrome 或 Firefox 中登录 Overleaf（访问 overleaf.com 并登录）
2. 首次运行时授予钥匙串访问权限（macOS 会提示选择“始终允许”）

# 测试身份验证 - 用户应先在终端中运行此命令
pyoverleaf ls

如果遇到身份验证错误：
- 询问用户：“您是否已在浏览器中登录 Overleaf？”
- 如果在 macOS 上：“您是否在钥匙串访问提示中选择了‘始终允许’？”
- 用户可能需要在终端中手动运行 pyoverleaf ls 以触发钥匙串提示

注意：代理无法替用户登录。浏览器身份验证必须由用户直接完成。

CLI 命令

# 列出所有项目
pyoverleaf ls

# 列出项目中的文件
pyoverleaf ls "项目名称"

# 读取文件内容
pyoverleaf read "项目名称/main.tex"

# 写入文件 (stdin → Overleaf)
cat local.tex | pyoverleaf write "项目名称/main.tex"

# 创建目录
pyoverleaf mkdir "项目名称/figures"

# 删除文件/文件夹
pyoverleaf rm "项目名称/old-draft.tex"

# 将项目下载为 zip 文件
pyoverleaf download-project "项目名称" output.zip

常用工作流

从 Overleaf 下载

pyoverleaf download-project "项目名称" /tmp/latest.zip
unzip -o /tmp/latest.zip -d /tmp/latest
cp /tmp/latest/main.tex /path/to/local/main.tex

上传到 Overleaf (推荐使用 Python API)

CLI 的 write 命令存在 WebSocket 问题。建议使用 Python API 进行可靠上传：

import pyoverleaf

api = pyoverleaf.Api()
api.login_from_browser()

# 列出项目以获取项目 ID
for proj in api.get_projects():
    print(proj.name, proj.id)

# 上传文件 (直接覆盖)
project_id = "your_project_id_here"
with open('main.tex', 'rb') as f:
    content = f.read()
root = api.project_get_files(project_id)
api.project_upload_file(project_id, root.id, "main.tex", content)

为何采用直接覆盖？ 此方法可保留 Overleaf 的版本历史。用户可通过 Overleaf 的“历史记录”功能精确查看更改内容，便于审查代理的编辑，并在需要时轻松回滚。

自托管 Overleaf

# 通过环境变量
export PYOVERLEAF_HOST=overleaf.mycompany.com
pyoverleaf ls

# 通过标志
pyoverleaf --host overleaf.mycompany.com ls

Eason 的工作流要求

从 Overleaf 拉取时：
1. 将 Overleaf 版本下载到 /tmp/
2. 使用 diff 与本地版本进行比较
3. 向 Eason 报告差异（总结更改内容）
4. 询问：合并？覆盖本地？覆盖 Overleaf？或其他操作？
5. 仅在 Eason 确认后继续

推送规则 (来自 TOOLS.md)：
- ❌ 禁止自行推送到 Overleaf
- ✅ 只能从 Overleaf 拉到本地
- ⚠️ 推送需要 Eason 明确授权，每次授权只能推送一次

示例

以下示例展示了使用 Overleaf 技能从论文中移除破折号（一种常见的 AI 写作痕迹）并推送更改：

故障排除

• 身份验证错误 / WebSocket 错误：先在 Chrome 浏览器中打开 Overleaf (open -a "Google Chrome" "https://www.overleaf.com/project"，等待 5 秒) 以刷新 Cookie，然后重试
• "scheme https is invalid" (WebSocket 重定向错误)：默认主机 overleaf.com 会导致 301 → www.overleaf.com 重定向，从而破坏 WebSocket。修复方法：设置 PYOVERLEAF_HOST=www.overleaf.com：
  bash cat main.tex | PYOVERLEAF_HOST=www.overleaf.com pyoverleaf write "项目/main.tex"
• 钥匙串访问被拒绝 (macOS)：pyoverleaf 需要钥匙串访问权限来读取浏览器 Cookie。用户必须在终端中运行 pyoverleaf ls 并在钥匙串提示中点击“始终允许”
• 找不到项目：使用确切的、区分大小写的项目名称，可通过 pyoverleaf ls 检查
• 权限被拒绝：用户可能没有项目的编辑权限