核心用法
pyoverleaf 是一款基于浏览器 Cookie 认证的命令行工具，允许用户直接在终端与 Overleaf 云端 LaTeX 项目交互。其工作流程分为三步：用户在 Chrome/Firefox 登录 Overleaf → 首次运行时授权钥匙串访问 → 通过 CLI 或 Python API 执行文件操作。主要功能包括：
- 项目浏览：
pyoverleaf ls列出所有可访问项目 - 文件读写：
read/write直接操作 .tex 文件，download-project批量打包下载 - 目录管理：
mkdir/rm维护项目结构 - 邀请处理：Python API 可程序化接受项目协作邀请，无需手动点击邮件链接
- 私有化部署：通过
PYOVERLEAF_HOST环境变量支持自托管 Overleaf 实例
显著优点
1. 无缝集成本地工作流：直接将本地编辑的 LaTeX 文件推送至云端，保留 Overleaf 的版本历史，便于追溯和回滚
2. 免密码认证：复用浏览器登录状态，无需配置 API token 或管理额外凭证
3. 程序化协作：自动处理项目邀请，适合团队批量管理多个协作项目
4. 代码可审计：v0.1.7 版本经安全审计，代码库精简透明，用户可自行审查
潜在局限与风险
- 平台依赖：仅支持 Chrome/Firefox 的 Cookie 存储，Safari 或 headless 环境需额外配置
- 钥匙串权限争议：macOS 需授予"始终允许"钥匙串访问，涉及浏览器 Cookie 的敏感读取权限
- CLI 写入稳定性：
write命令存在 WebSocket 重定向 bug，生产环境建议使用 Python API 直接覆盖 - 权限边界模糊：工具获得的是用户完整的浏览器 Cookie 上下文，理论上可访问同浏览器会话中的其他服务
- 版本锁定风险：审计仅覆盖 v0.1.7，后续版本需用户自行验证
适合人群
- 学术研究者：需要在本地 IDE 与 Overleaf 间频繁同步 LaTeX 手稿
- 技术文档团队：管理多个协作项目，批量处理成员邀请
- DevOps 工程师：将 Overleaf 集成至 CI/CD 流程，自动化文档构建与发布
常规风险
| 风险类型 | 说明 | 缓释措施 |
|---------|------|---------|
| 凭证泄露 | Cookie 被盗用可导致 Overleaf 账户完全失控 | 仅在受信任设备使用，避免共享浏览器配置文件 |
| 数据丢失 | `write` 直接覆盖云端文件，无本地确认环节 | 优先使用 API 上传以保留历史版本，操作前执行 `download-project` 备份 |
| 供应链攻击 | pipx 安装的包可能被篡改 | 校验 GitHub 源码哈希，审计后锁定版本 |
| 隐私泄露 | 钥匙串访问可能暴露其他站点 Cookie | 使用专用浏览器配置文件隔离 Overleaf 会话 |