ChatOL

ChatOL: Python client and CLI for Overleaf workflows

快速开始

pip install -e ".[dev]"
oleaf --help
oleaf --version
oleaf --tree
oleaf --tree-brief
python -m pytest -q
python -m build

Overleaf CLI 示例

CLI 只做薄封装；对应能力也可以从 chatol.workflows 和 chatol.client.OverleafClient 直接 import 调用。

配置可以来自当前进程环境变量，也可以来自 ChatEnv active overleaf profile。配置键优先复用 Overleaf 官方已有名称，例如 OVERLEAF_SITE_URL 和 OVERLEAF_ADMIN_EMAIL；官方没有的密码、session、HTTP timeout 等补充字段也统一放在 OVERLEAF_* 命名空间里，不再维护 CHATOL_* 兼容入口。命令行示例使用占位符；真实密码建议用 chatenv paste --stdin、私有 profile、环境变量或 --password-stdin，不要写进 shell history。

export OVERLEAF_SITE_URL="https://overleaf.example.com"
export OVERLEAF_ADMIN_EMAIL="<email>"
export OVERLEAF_ADMIN_PASSWORD="<password>"

oleaf doctor --json
oleaf projects list --json
oleaf projects info "<project-name>" --json
oleaf files pull "<project-name>" ./source --json
oleaf templates init article-basic ./template --json
oleaf templates upload "<project-name>" ./template --json
oleaf compile run "<project-name>" --json
oleaf compile pdf "<project-name>" -o output.pdf --json
oleaf compile output "<project-name>" log -o output.log --json
oleaf compile bundle "<project-name>" -o artifacts --json
oleaf admin doctor --json

密码和 session cookie 也可以通过 --password-stdin / --session-stdin 传入，避免出现在 shell history 或进程参数里。

CLI 规范

ChatOL 依赖 chatstyle>=0.2.0,<0.3.0 和 chatenv>=0.2.10,<0.3.0。CLI 合约包括：

• 根命令显式命名为 oleaf，并提供 --version、--tree 和 --tree-brief。
• --tree / --tree-brief 由 ChatStyle 从真实 Click 注册表渲染，不维护包内副本。
• CommandSchema / CommandField 描述输入。
• add_interactive_option() 提供统一 -i/-I。
• resolve_command_inputs() 统一缺参补问、默认值、TTY 与校验。
• OverleafConfig 通过 chatenv.configs 注册，凭据从 ChatEnv 的 typed profile/storage 路径读取。

目录结构

• src/：包源码
• tests/code-tests/：代码测试和历史测试迁移
• tests/cli-tests/：真实 CLI 测试，doc-first
• tests/mock-cli-tests/：mock/fake CLI 测试，doc-first
• docs/：长期维护文档，由 mkdocs 构建

开发说明

扩展脚手架前，先阅读 DEVELOP.md 和 AGENTS.md。