colab-operator

技能：Colab 会话操作员

通过 colab CLI 操作 Google Colab 环境：配置 GPU/TPU 会话、在 VM 上运行 Python/ shell、同步文件，并将工作保存为笔记本。

安装

如果用户尚未安装 colab 工具，可以运行 uv tool install google-colab-cli 或 pip install google-colab-cli 进行安装。

何时启用

• 创建或管理 TPU/GPU 会话。
• 在远程 Colab VM 上运行 Python 或 shell。
• 在本地和远程之间同步文件。
• 自动配置环境（软件包、身份验证、Drive）。
• 将会话历史导出为 Jupyter 笔记本。

心智模型（请先阅读）

• 一个会话 == 租用 VM 上运行的 Jupyter 内核。 colab new 会分配一台计费 VM；colab stop 会释放它。只要内核处于活动状态，会话就会保持运行，Colab 后端会自动维持其活动状态。
• 在同一会话中，内核状态会在多次 colab exec / colab repl 调用之间持续保留。 每次调用都会重新连接到同一个内核（内核 ID 会缓存在本地状态中），并且只会在退出时关闭 websocket —— 不会关闭内核。因此，导入项、变量和已定义的函数会在不同的 colab exec 命令之间保留。逐步构建状态；不要每次调用都重新导入所有内容。（真正重置内核的是 colab stop 和 colab restart-kernel。）
• 默认工作目录是 /content。 每次运行 exec/repl/run 时都会先切换到此目录；处理文件时优先使用绝对路径（/content/...）。对于 colab ls/rm/upload/download，可以使用绝对 /content/... 路径，默认 ls 路径是 content（VM 根目录）。
• colab 执行后即退出，不会持续运行。 每条命令都会进行身份验证、执行一项操作，然后退出。

身份验证（最常见的 Agent 阻塞问题）

• 全局标志是 --auth={adc,oauth2}，默认值为 adc（应用默认凭据）。它必须放在子命令之前：colab --auth=adc new -s x。
• ADC 设置（最适合无头/Agent 使用）。Colab 后端需要一组特定的作用域，因此请使用以下全部四个作用域重新生成 ADC：

  gcloud auth application-default login \
    --scopes=openid,\
  https://www.googleapis.com/auth/cloud-platform,\
  https://www.googleapis.com/auth/userinfo.email,\
  https://www.googleapis.com/auth/colaboratory
  

  为什么需要全部四个：userinfo.email（会话后端 colab.research.google.com，否则返回 401）、colaboratory（Colab 功能/API）、openid+cloud-platform（gcloud 强制要求；如果作用域列表缺少 cloud-platform，它会拒绝请求）。
• oauth2 设置：首次使用时，colab --auth=oauth2 <anything> 会触发浏览器授权流程（令牌缓存在 ~/.config/colab-cli/token.json）。需要在 ~/.colab-cli-oauth-config.json 中提供客户端配置（或使用 -c PATH）。浏览器步骤通常需要人工操作；对 Agent 来说，优先使用 ADC。
• 一次性验证身份验证：运行 colab sessions（只读，列出服务器分配情况）或 colab whoami（隐藏的调试命令：显示当前邮箱、作用域、受众和到期时间）。任何调用返回 401 或 403 时，原因几乎总是缺少凭据或作用域 —— colab whoami 会立即显示问题。
• 不要将 colab auth 与 CLI 身份验证混淆。 colab auth 会将 VM 端 的 GCP 凭据注入正在运行的内核（让笔记本代码能够调用 BigQuery/GCS）；它与 CLI 本身的身份验证方式无关。切勿建议运行 colab auth 来修复 CLI 的 401/403 —— 这是作用域/身份问题，应通过上述 gcloud 命令修复。

工作流

配置

• colab new -s <name>（CPU）。添加 --gpu A100 或 --tpu v6e1 来使用加速器。始终传入 -s <name>——省略名称时会自动生成一个随机的 6 位十六进制字符串，导致后续命令无法明确指定目标。
• 支持的 --gpu：T4、L4、G4、H100、A100。支持的 --tpu：v5e1、v6e1。
• 注意：无法识别的 --gpu 值会静默回退到 A100（这通常会导致下一步失败）。使用加速器时，colab new 返回 400 表示此账号没有相应的配额或使用权限——请改用 --gpu T4，或省略该标志以使用 CPU。
• 加速器的可用性取决于账号等级；大多数账号只能使用 CPU。不要假设一定能分配到 GPU/TPU。

执行

• 首选：colab exec -s <name> -f <script.py> 可在远程 VM 上运行本地脚本（在本地读取并发送到内核——无需手动上传）。
• 通过管道传入代码：echo "print(1)" | colab exec -s <name> 或 cat script.py | colab exec -s <name>。
• Notebook：colab exec -s <name> -f nb.ipynb 会运行每个代码单元，并在输入文件旁写入 <basename>_output.ipynb。首行中的 # @title Foo 会作为单元格标签显示在进度输出中。
• 绘图/图像：会拦截 PNG/JPEG 输出。使用 exec/repl 上的 --output-image <path> 将其保存到指定位置（否则会打印临时路径）。当 stdout 不是 TTY 时，会自动屏蔽内联终端图像转义序列，因此通过管道传输或捕获的输出仍保持干净。
• Shell：使用 echo "cmd" | colab console -s <name> 批量运行 Shell 命令。Console 会在 tmux 中运行 bash，因此即使输出通过管道传输，也会包含终端控制字节——使用 grep -a 过滤出特定行。如果不需要真正的 Shell，exec 速度更快。
• 切勿从 Agent 交互式运行 colab repl、colab console、colab auth 或 colab drivemount——这些命令需要 TTY，会导致挂起。repl/console 接受通过管道传入的 stdin，并在遇到 EOF 时退出；而 auth/drivemount 确实需要用户在终端中操作。

临时单次任务（colab run）

• colab run [--gpu T4] [--tpu v6e1] [--keep] [-s NAME] script.py [args...] = 用一条命令完成 new + exec + stop。它会配置一个全新的 VM，像原生运行 python script.py args 一样设置 sys.argv 和 __name__ == "__main__" 后运行脚本，然后关闭 VM（除非指定 --keep）。
• 退出码会传递：如果脚本中发生未捕获的异常或调用 sys.exit(N)，colab run 会以非零状态退出（遵循 CPython 语义：sys.exit()/sys.exit(0) → 0，sys.exit(N) → N，sys.exit("msg") → 1）。
• 流分离：colab run 会将自身的 [colab] ... 信息写入 stderr，将脚本输出写入 stdout——因此 colab run job.py > out.txt 只会捕获脚本的 stdout。（colab exec 会将脚本的 stdout/stderr 实时流式传输到你的 stdout/stderr。）
• 可用作 shebang：#!/usr/bin/env -S colab run --gpu T4 可将经 chmod +x 处理的 .py 文件变成一个独立的“租用 GPU、运行、清理”脚本。修改 CLI 行为后，请先重新安装再测试 shebang——它们会通过 $PATH 查找 colab，而不是使用可编辑安装。
• 如果脚本路径不存在，命令会在分配 VM 之前以非零状态退出（不会浪费计算资源）。

自动化

• colab auth -s <name>——VM 端的 GCP 凭据；在 VM 中调用 GCS/BigQuery 前需要执行（交互式；无法由 Agent 运行）。
• colab drivemount -s <name> [PATH]——默认将 Drive 挂载到 /content/drive（交互式；无法由 Agent 运行）。
• colab install -s <name> pkg1 pkg2——通过 uv pip install --system 安装，失败时回退到 pip。也可使用 colab install -s <name> -r requirements.txt。

检查与报告

• colab help（或 colab help <cmd>）会列出并说明命令；命令按字母顺序排列。
• colab sessions 会列出服务端分配情况，并自动清理过时的本地条目。没有本地记录的孤立会话会显示为 [?]。
• colab status [-s <name>] 会显示硬件、IDLE/BUSY 状态和上次执行时间。
• colab log -s <name> [-n 20] [-t TYPE] 会显示最近的结构化事件；任务失败时尤其有用。
• colab log -s <name> -o summary.ipynb 会将会话导出为笔记本（也可根据后缀导出为 .md、.txt、.jsonl）。
• colab url -s <name> 会输出一个浏览器 URL，将 Colab 网页界面连接到现有 CLI 会话，而不是分配新的 VM（添加 --open 可打开该界面）。
• colab skill / colab readme 会输出此 skill 和 README（便于自行了解）。

安全

• 完成后务必运行 colab stop -s <name>——空闲 VM 会消耗计算单位。即使脚本出错，colab run（不带 --keep）也会自动清理。
• 本地状态存放在 ~/.config/colab-cli/sessions.json 中（设置存放在 settings.json 中，历史记录存放在 history/*.jsonl 中）。不要手动编辑。
• 隔离并行运行或 Agent 运行：使用全局 --config <path> 标志，将会话状态指向临时文件（例如 colab --config /tmp/agent.json new -s job）。

恢复

• 执行时出现 “Session not found” / 404 / 401：后端已清理该 VM。colab exec/repl 会检测此情况并自动清理本地状态——运行 colab sessions，然后使用 colab new 重新创建。
• 执行超时或内核卡死：运行 colab restart-kernel -s <name>（保留 VM，重置内核），或运行 colab stop 后再运行 colab new。