Metadata-Version: 2.4
Name: colabllm
Version: 1.0.0
Summary: Run model services on Google Colab with managed tunnels and authentication
License-Expression: MIT
Project-URL: Homepage, https://github.com/deluxebear/colabllm
Project-URL: Repository, https://github.com/deluxebear/colabllm
Project-URL: Issues, https://github.com/deluxebear/colabllm/issues
Project-URL: Changelog, https://github.com/deluxebear/colabllm/blob/master/CHANGELOG.md
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Google Colab 大模型服务

在 Google Colab GPU 上运行大模型服务，通过 Cloudflare Tunnel（默认）或 FRP + Caddy 提供公网访问。
遵循 **“一个服务 = 一个 notebook (`src/colabllm/services/<name>.ipynb`) + 一个执行脚本 (`src/colabllm/services/<name>.py`)”** 的约定。

## 功能实操视频

[![ColabLLM 全景实操与 Copilot Studio 有声演示视频](https://github.com/deluxebear/colabllm/blob/master/docs/assets/colabllm-walkthrough-poster.png?raw=true)](https://github.com/deluxebear/colabllm/blob/master/docs/assets/colabllm-walkthrough.mp4)

> **有声全景导览（02:22 · IndexTTS-2.5 配音）**：点击上方预览图打开 [GitHub 在线视频播放器](https://github.com/deluxebear/colabllm/blob/master/docs/assets/colabllm-walkthrough.mp4)，查看统一 CLI、Web 舰队管控与 **AI 演练场（Copilot Studio · 同源安全代理 · 多模态与专有 API 控制台）** 完整实操演示（[直接下载 MP4](https://github.com/deluxebear/colabllm/raw/master/docs/assets/colabllm-walkthrough.mp4)）。

## 统一命令入口

用户通过分发包安装，无需克隆源码。从 [GitHub Releases](https://github.com/deluxebear/colabllm/releases) 下载 wheel 后安装（私有仓库需要相应访问权限）：

```bash
uv tool install ./colabllm-1.0.0-py3-none-any.whl
# 如果命令目录尚未加入 PATH
uv tool update-shell
```

版本发布到 PyPI 后，也可以直接安装和升级：

```bash
uv tool install colabllm
uv tool upgrade colabllm
```

之后可以在任意目录使用 `colabllm <运行时名称> <命令> [参数...]`：

```bash
colabllm services                       # 列出全部运行时
colabllm minimax-h3-image up            # 默认 G4（SGLang Diffusion 原生 4K 生图 / 1-16 图编辑）
colabllm minimax-h3-image generate "Rain-soaked Tokyo alley at dusk" --tier 2k -o alley.webp
colabllm unlimited-ocr up                # 默认 A100
colabllm unlimited-ocr ocr ./documents -O ./results
colabllm unlimited-ocr resume JOB_ID --wait
colabllm qwen3-tts up -i 2
colabllm comfyui up
colabllm ollama up --dry-run
colabllm unlimited-ocr --help

# 项目级配置与本地 Web 控制台也使用同一入口
colabllm web
colabllm web -d                         # 后台运行，并支持 --status / --stop
colabllm web --port 8765 --read-only
colabllm tunnel-config
colabllm frp-config --help
colabllm frp-status
```

所有运行脚本和 notebook 都包含在安装包中。本地相对输入/输出路径按调用时所在目录解析。
本项目的配置和运行状态统一写入 `~/.colabllm/`，不读取仓库旧 `.state/`，不提供旧配置迁移。
可设置 `COLABLLM_HOME=/absolute/path` 使用独立目录。

```text
~/.colabllm/
├── tunnel-config.json           # 全局主域名与 FRP 设置
├── services/<name>/state.json   # 实例凭据、会话、隧道与 runner PID
├── services/<name>/run.log      # 日志；执行用 notebook 也在实例目录
└── frp/<server-id>.json         # FRP 私密凭据
```

`colab`、`cf` 和 `ssh` 的授权/配置仍由各自工具管理；Google Drive 数据仍保存在远端。
卸载使用 `uv tool uninstall colabllm`，用户配置目录保留。
升级前先停止运行中的服务，升级后重新启动，避免后台 runner 依赖的安装文件被替换。

### 更换电脑（沿用相同域名与 API Key）

域名归属和凭据只保存在本机 `~/.colabllm/`。在另一台电脑上直接执行 `up --domain` 会遇到：

- **FRP 后端无法启动**：新电脑执行 `frp-config` 会生成新的 `project_id`，已有 DNS 记录和 FRP 服务器路由属于旧 `project_id`，`up` 会以 `DNS conflict` 拒绝接管（防止误抢域名）。
- **API Key 改变**：新电脑没有 `state.json`，会生成新的 Token，客户端中配置的旧 Key 全部返回 401。
- **Cloudflare 后端双连接**：隧道与 DNS 按服务名复用、不区分电脑；若两台电脑同时运行同一服务，请求会在两台 VM 间轮流分发（Key 不同时随机 401）。
- **重复计费**：旧电脑的 runner 未停止时，旧 Colab VM 会继续运行，新电脑会再创建一台。

同一服务、同一实例同一时间只应由一台电脑运行。迁移步骤：

```bash
# 1. 旧电脑：停止服务；不要加 --delete-tunnel，以保留域名路由与 DNS 归属
colabllm <name> down

# 2. 复制整个状态目录到新电脑（含私密凭据，保持仅本人可读）
rsync -a --chmod=go-rwx ~/.colabllm/ <新电脑>:~/.colabllm/

# 3. 新电脑：安装 colabllm，并完成外部工具授权
#    colab 登录 + `colab drive consent`；同一 Cloudflare 账号的 `cf` 登录；FRP 后端还需能 SSH 到服务器
colabllm tunnel-config            # 确认主域名与 FRP 配置已带过来
colabllm doctor

# 4. 新电脑：启动，域名、API Key 与 FRP 路由保持不变
colabllm <name> up --domain
```

`~/.colabllm/` 中与迁移相关的文件：`tunnel-config.json`（主域名、FRP `project_id`）、`frp/*.json`（FRP 客户端凭据）、
`services/<name>/state.json`（API Key / 登录密码、隧道与 DNS 记录）。若确实需要两台电脑同时运行同一服务，
请使用不同实例（如 `-i 2`），它们使用独立的子域名、状态和 Key。

## 运行时使用指南

每个运行时的具体命令、API/UI 工作流、输入输出及恢复语义见下方“各运行时使用文档”表。
共享规则集中在 [运行时通用操作](https://github.com/deluxebear/colabllm/blob/master/docs/runtime-common.md)，可先阅读以理解认证、Drive 路径、超时和多实例。
`docs/<运行时>.md` 是用法说明的维护来源，用户技能内的对应参考由同步工具生成：

```bash
python tools/sync_runtime_docs.py
python tools/sync_runtime_docs.py --check
```

修改用法或新增运行时后需同步；本地测试及 CI 会检查指南完整性、示例参数和技能内容一致。

## 安装 Agent Skill

根目录 [skills/colabllm](https://github.com/deluxebear/colabllm/blob/master/skills/colabllm/SKILL.md) 提供面向使用者的独立技能，覆盖本项目所有运行时。
它包含按任务加载的 OCR、语音、推理、媒体和排错参考，不依赖源码仓库或个人部署配置。

wheel 和源码包均包含完整技能，安装 CLI 后即可导出：

```bash
# 查看主技能说明
colabllm skill

# Codex：将完整 colabllm/ 技能目录导出到个人技能目录
colabllm skill --output "${CODEX_HOME:-$HOME/.codex}/skills"

# 支持 ~/.agents/skills 的 Agent
colabllm skill --output ~/.agents/skills

# 其他 Agent：指定其实际技能目录
colabllm skill --output /path/to/agent/skills
```

`--output` 是技能父目录，实际生成 `<目录>/colabllm/SKILL.md` 和 `references/`。
目标已存在时返回错误，不覆盖用户修改。更新时先导出到新目录，比较后替换；CLI 升级不会自动覆盖已安装的技能。
也可以直接从源码复制整个 `skills/colabllm/` 目录。安装后按 Agent 的方式重新加载技能或开启新会话，
再请求“使用 colabllm 将本地 PDF 转为 Markdown”等任务。

仓库内 `.agents/skills/colab-llm-service/` 是维护者技能；分发给使用者的是 `skills/colabllm/`。

## 开发、构建与发布

```bash
# 开发安装：修改源码立即生效，源码目录需要保留
uv tool install --editable .

# 普通本地安装 / 更新
uv tool install --force .

# 构建 wheel 和源码分发包（dist/）
uv build --no-sources

# 验证 wheel 在隔离环境中的安装与运行
python tools/check_distribution.py dist/colabllm-1.0.0-py3-none-any.whl
```

版本号以 `pyproject.toml` 为唯一来源，CLI 从已安装包元数据读取版本。
采用 `MAJOR.MINOR.PATCH`：修复递增 PATCH、新功能递增 MINOR、不兼容变更递增 MAJOR；
在 `0.x` 开发阶段，不兼容变更递增 MINOR，并在 [CHANGELOG.md](https://github.com/deluxebear/colabllm/blob/master/CHANGELOG.md) 中说明。
当前版本为 `1.0.0`，对应 Git 标签 `v1.0.0`；后续发布示例：

```bash
uv version --bump patch
# 将 CHANGELOG.md 的 Unreleased 内容整理到本次版本的日期条目
python tools/check_release.py --tag v1.0.1
git add pyproject.toml CHANGELOG.md README.md
git commit -m "chore: release 1.0.1"
git tag -a v1.0.1 -m "Release 1.0.1"
git push origin master
git push origin v1.0.1
```

推送 `v*` 标签触发 [release.yml](https://github.com/deluxebear/colabllm/blob/master/.github/workflows/release.yml)：

1. 验证标签、包版本和变更记录一致，复用 Linux/macOS × Python 3.12–3.14 CI。
2. 构建 wheel 和 sdist，验证隔离安装，生成 SHA256SUMS 并保存 Actions artifact。
3. 发布 GitHub Release，附带安装包及校验文件，发布说明取自当前版本的 CHANGELOG 条目。
4. 将同一组已验证的包通过 Trusted Publishing 上传 PyPI。

首次启用 PyPI 需要项目所有者在 [PyPI Publishing](https://pypi.org/manage/account/publishing/)
添加 Pending Publisher：项目 `colabllm`、Owner `deluxebear`、Repository `colabllm`、
Workflow `release.yml`、Environment `pypi`。已有 PyPI 项目则在项目 Publishing 设置添加同样的发布者。
Actions 使用 `pypi` environment 和 OIDC，无需配置长期 PyPI API Token。
参考 [PyPI Trusted Publisher 说明](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)。

PyPI 上传失败时，GitHub Release 仍可下载；修复身份配置后在 Actions 选择 **Re-run failed jobs**。
也可以针对已有标签手动运行 release workflow；已发布的 GitHub Release 会拒绝被覆盖，应优先只重跑失败任务。
已发布版本不移动标签或替换安装包，修复后发布新版本。
通过本地 wheel 安装的用户可安装新 wheel 更新；通过 PyPI 安装的用户使用 `uv tool upgrade colabllm`。

## CLI 行为约定

- `colabllm <服务> --help` 列出生命周期和服务专用命令；`colabllm help <服务> <命令>` 查看详细帮助。
- `-i/--instance` 可放在服务参数的任意位置，`--` 之后按字面解析；实例 ID 必须为 1–64 位字母、数字、下划线或连字符，且不能以连字符开头。
- `--account`（或环境 `COLABLLM_ACCOUNT` / `COLAB_ACCOUNT`）可指定本次使用的 Colab 账户（档案名或邮箱，`up` 与 `doctor` 同时支持 `-a/--account`）；`up --drive-account` 可额外指定共享网盘凭据账户。`up` 启动后会把解析到的账户与网盘绑定写入该实例 `state.json`，后续 `--auto-restart` 自动重拉、`status` 与 `down` 都会锁定原账户，不受之后终端 `colab account use` 切换活动账户影响。
- 普通结果写入 stdout，进度和告警写入 stderr；`--json` 的 stdout 只包含 JSON。
- `info`、`ps`、`list`、`status` 支持 `--json`，默认隐藏凭据；需要时显式加 `--show-secrets`。
- `--quiet` 抑制诊断进度，错误仍然显示；`--no-color` 或 `NO_COLOR` 关闭诊断颜色。非终端输出自动关闭诊断颜色。
- 常见网络、文件和配置错误默认给出简洁提示；`--debug` 显示异常堆栈。
- 成功退出码为 0；操作失败为非零，参数用法错误为 2；外部 Colab 命令失败时保留其正退出码；Ctrl+C 为 130。
- 就绪标记只接受完整的 `CT_READY` 协议行；日志中的普通文字提及不会被视为就绪。
- `up` 默认等待 `CT_READY`；等待超时返回失败，但后台 runner 保留。`up --detach` 仅启动后台 runner，立即返回；`up --foreground` 在当前终端保持连接。
- `up --auto-restart`（可选 `--idle-check SECONDS`、`--restart-delay SECONDS`、`--max-restarts N`）开启所有运行时通用的掉线自动拉起守护：监听 `colab exec` 退出（默认 `3s` 后核实）及每 `10s` 公网边缘探针 + `--idle-check`（默认 5 分钟）兜底的 `colab status` 远端核实，网络闪断时直接重连原 VM 并在服务可用时立即恢复 `ready` 状态，VM 被 Colab 回收时立即清理残留会话并按原 GPU 规格重新建卡、挂载 Drive 与恢复服务（固定域名与 `api_token` 不变）；执行 `down` 时正常停止。
- 同一实例的启动和停止互斥；状态事务使用文件锁和原子替换。前台/后台 runner 都记录进程启动身份，停止前校验身份并等待退出。
- `down` 先确认远端停止成功，再停止本地连接并清理运行状态；远端停止失败时保留连接和追踪信息，便于重试。
- 携带认证信息的 HTTP 请求拒绝跨来源重定向。`--url` 或服务 URL 环境变量切换来源时，需要显式提供 Token，不能自动借用原服务的凭据。来源按协议、主机和有效端口比较。

## 超时与环境诊断

```bash
# 外部命令上限：可放在服务名前后，也可设置 COLABLLM_COMMAND_TIMEOUT
colabllm --command-timeout 60 ollama status

# 默认模式超时只停止等待，后台 runner 保留；前台模式超时会断开本地连接
colabllm ollama up --ready-timeout 600
colabllm ollama up --foreground --ready-timeout 600

# 轮询等待上限：0 保留不限时行为；每次请求也会受剩余时间约束
colabllm unlimited-ocr job JOB_ID --wait --timeout 300
colabllm minimax-h3-image job JOB_ID --wait --timeout 300
colabllm comfyui pull-workflow TEMPLATE --timeout 300 --poll 2
colabllm longcat-avatar job JOB_ID --wait --timeout 300

# 默认只检查本机依赖、Drive 扩展、当前或指定账户授权文件与用户配置
colabllm doctor
colabllm doctor -a gpu2 --online --timeout 10
colabllm doctor --json --transport quick --no-drive

# 额外验证 Colab、Cloudflare、SSH 授权，按选中的后端执行限时只读检查
colabllm doctor --online --timeout 10
```

超时退出码为 `124`。长驻的 `colab exec` 保活连接不受通用外部命令上限影响。
未指定 `--command-timeout` 时，共享外部命令默认 300 秒，个别下载或 SSH 操作保留专属默认上限。
`doctor` 不创建 GPU 会话、不挂载 Drive、不修改隧道，也不显示凭据或外部命令的原始输出。
离线检查不会证明授权仍有效；需要时使用 `--online`，该模式禁用浏览器交互并限制每项检查时间。

## Shell 补全

命令、选项和枚举值来自实际解析器；实例 ID 从 `~/.colabllm/services/` 的目录名读取，补全过程不读取凭据、不联网。

```bash
# Bash：在当前 Shell 加载
source <(colabllm completion bash)

# Zsh：先启用补全系统，再加载
# autoload -Uz compinit && compinit
source <(colabllm completion zsh)
```

Fish 中执行 `colabllm completion fish | source`。需要持久启用时，将相应加载命令加入自己的 Shell 初始化文件，
或将脚本保存在 `~/.colabllm/completions/` 后从初始化文件加载。

## 测试

本地 CLI 与控制逻辑使用 Python 标准库，默认测试无需 Torch、NumPy 或 GPU：

```bash
python -m unittest discover -s tests
```

`tests_colab/` 单独保存 Colab 端模型代码的回归测试（如 LongCat attention 和音频分段）。
它们会导入模型运行代码，仅在对应的 Colab 服务环境中运行；attention 测试还需要 CUDA 和上游 LongCat 源码。
在该环境中，将项目源码放入 VM 后执行：

```bash
# LongCat-Video VM 使用 /content/longcat-video/repo；Avatar VM 使用 /content/longcat-avatar/repo
PYTHONPATH=/content/longcat-video/repo python -m unittest discover -s tests_colab
```

GitHub Actions 在 Linux/macOS、Python 3.12/3.13/3.14 上运行本地测试、三种 Shell 补全测试、构建和隔离 wheel 安装验证。工作流不执行模型测试、不启动 Colab、不自动发布包。

本地缺少 Zsh/Fish 时跳过对应 Shell 集成测试；CI 会安装这些 Shell。
本地测试中的真实 FRP 集成测试需额外指定 `COLABSVC_FRP_TEST_BIN`，默认跳过。

## 架构与职责

| 阶段 / 职责 | 执行位置 | 说明 |
| --- | --- | --- |
| 创建/复用 Colab 会话 (`colab new`) | 本地脚本 `src/colabllm/services/<name>.py` | 会话名与服务名一致，按选定账户注入 `COLAB_ACCOUNT` 隔离会话 |
| 免浏览器挂载网盘 (`colab drive mount` / `dfs mount`) | 本地脚本 `src/colabllm/services/<name>.py` | 按账户或共享 `--drive-account` 挂载到 `/content/drive`；自动跳过 notebook 里的 `drive.mount()` |
| Cloudflare 固定域名 | 本地脚本 (`cf` CLI) | 创建/复用 named tunnel、配置 ingress 和 DNS CNAME；未配置主域名时使用动态 URL |
| FRP 固定域名 | 本地脚本 (`ssh` + `cf` CLI) | SSH 安装或复用服务端 frps/Caddy，通过 Cloudflare DNS 将域名指向服务器 IP |
| 密钥生成与注入 | 本地脚本 -> `--env` | 自动生成账号密码与 Bearer Token，保存在 `~/.colabllm/services/<name>/state.json` (0600) |
| 安装与启动服务 | 远端 `src/colabllm/services/<name>.ipynb` | 幂等安装，服务仅监听 `127.0.0.1` |
| 安全认证层 (Caddy) | 远端 `src/colabllm/services/<name>.ipynb` | 对无自带认证的服务（如 Ollama）前置 Caddy：浏览器走 Basic Auth，API 走 `Authorization: Bearer <token>` |
| 启动 `cloudflared` / `frpc` 与保活 | 远端 `src/colabllm/services/<name>.ipynb` | 最后一个 cell 持续阻塞并监控子进程；本地后台进程保持 `colab exec` 连接以防 Colab 回收会话 |

## 各运行时使用文档

| 服务名称 | 默认 GPU | 认证方式 | 固定域名示例（主域名配置为 `example.com`） | 详细使用说明 |
| --- | --- | --- | --- | --- |
| **NVIDIA-Nemotron-3.5-Transcribe-30B-A4B** | `G4` | `vLLM` Bearer API Key (`builtin`) | `https://transcribe.example.com` | [docs/nemotron-transcribe.md](https://github.com/deluxebear/colabllm/blob/master/docs/nemotron-transcribe.md) |
| **Qwen3-TTS** | `L4` | Bearer API Key (`builtin`) | `https://qwen3-tts.example.com` | [docs/qwen3-tts.md](https://github.com/deluxebear/colabllm/blob/master/docs/qwen3-tts.md) |
| **IndexTTS-2.5** | `L4` | Bearer API Key (`builtin`) | `https://indextts.example.com` | [docs/indextts.md](https://github.com/deluxebear/colabllm/blob/master/docs/indextts.md) |
| **Fish Audio Drama 3 (SGLang-Omni TTS & 小说朗读)** | `G4` | `SGLang-Omni` Bearer API Key (`builtin`) | `https://drama3.example.com` | [docs/drama3.md](https://github.com/deluxebear/colabllm/blob/master/docs/drama3.md) |
| **TangoFlux (44.1 kHz 立体声音效与文本生音频)** | `T4` | Bearer API Key (`builtin`) | `https://tangoflux.example.com` | [docs/tangoflux.md](https://github.com/deluxebear/colabllm/blob/master/docs/tangoflux.md) |
| **Unlimited-OCR 2** | `A100` | Caddy (Basic Auth + Bearer) | `https://unlimited-ocr.example.com` | [docs/unlimited-ocr.md](https://github.com/deluxebear/colabllm/blob/master/docs/unlimited-ocr.md) |
| **LongCat-Video-Avatar 1.5** | `G4` | Caddy (Basic Auth + Bearer) | `https://longcat-avatar.example.com` | [docs/longcat-avatar.md](https://github.com/deluxebear/colabllm/blob/master/docs/longcat-avatar.md) |
| **LongCat-Video** | `G4` | Caddy (Basic Auth + Bearer) | `https://longcat-video.example.com` | [docs/longcat-video.md](https://github.com/deluxebear/colabllm/blob/master/docs/longcat-video.md) |
| **Openjutsu (MiniMax H3 Video Studio)** | `G4` | Caddy (Basic Auth + Bearer) | `https://openjutsu.example.com` | [docs/openjutsu.md](https://github.com/deluxebear/colabllm/blob/master/docs/openjutsu.md) |
| **FLUX 3 Image Klein (T2I + Multi-Ref I2I + PUP)** | `G4` | `vLLM-Omni` Bearer API Key (`builtin`) | `https://flux-klein.example.com` | [docs/flux-klein.md](https://github.com/deluxebear/colabllm/blob/master/docs/flux-klein.md) |
| **Qwen-Image-2.1 (T2I + 1-4 Ref RGBA I2I)** | `G4` | `vLLM-Omni` Bearer API Key (`builtin`) | `https://qwen-image.example.com` | [docs/qwen-image.md](https://github.com/deluxebear/colabllm/blob/master/docs/qwen-image.md) |
| **MiniMax-H3-Image (6-Step PDD Native 4K T2I + 1-16 Ref I2I)** | `G4` | `SGLang Diffusion` Bearer API Key (`builtin`) | `https://minimax-h3-image.example.com` | [docs/minimax-h3-image.md](https://github.com/deluxebear/colabllm/blob/master/docs/minimax-h3-image.md) |
| **ComfyUI + ComfyUI-Manager** | `L4` | Caddy (Basic Auth + Bearer) | `https://comfyui.example.com` | [docs/comfyui.md](https://github.com/deluxebear/colabllm/blob/master/docs/comfyui.md) |
| **Qwen3.8-Flash-Next (UD-Q4_K_XL-V2 · 1M + Vision)** | `G4` | `llama-server` Bearer API Key | `https://qwen.example.com` | [docs/qwen-flash.md](https://github.com/deluxebear/colabllm/blob/master/docs/qwen-flash.md) |
| **DeepSeek-V4.1-Flash Coder (Auto Max 1M + Vision)** | `G4` | `llama-server` Bearer API Key | `https://deepseek.example.com` | [docs/deepseek-coder.md](https://github.com/deluxebear/colabllm/blob/master/docs/deepseek-coder.md) |
| **DeepSeek-V4-Pro-Qwen3.5-9B (i1-Q4_K_M + MTP · 256K + Vision)** | `L4` | `llama-server` Bearer API Key | `https://deepseek-9b.example.com` | [docs/deepseek-qwen-9b.md](https://github.com/deluxebear/colabllm/blob/master/docs/deepseek-qwen-9b.md) |
| **Ollama（含 Qwen3.8-27B BF16 预设）** | `T4` / `G4` | Caddy (Basic Auth + Bearer + `x-api-key`) | `https://ollama.example.com` | [docs/ollama.md](https://github.com/deluxebear/colabllm/blob/master/docs/ollama.md) |
| **Unsloth Studio** | `L4` | 内置 Web 登录 (`builtin`) | `https://unsloth-studio.example.com` | [docs/unsloth-studio.md](https://github.com/deluxebear/colabllm/blob/master/docs/unsloth-studio.md) |
| **Cloudflare R2 → Google Drive 迁移 (`r2-migrate`)** | `CPU` (`--high-mem`) | Caddy + Web UI (`caddy`) | `https://r2-migrate.example.com` | [docs/r2-migrate.md](https://github.com/deluxebear/colabllm/blob/master/docs/r2-migrate.md) |

### 文本与编程大模型选型说明（Colab G4 硬件边界）

针对 Colab G4 的实测硬件边界（本地 NVMe 可用空间约 **`253 GB`**、显存 **`95.6 GiB`**、主机 DDR5 内存 **`~176 GiB`**），项目内三套主力文本/多模态推理方案按如下分工与选型构建：

- **`deepseek-coder`（编程、Coding Agent 与复杂逻辑推理首选）**：默认部署 `Abiray/DeepSeek-V4.1-Flash-1017-Uncensored-GSQ-RCO-Coder-GGUF`（基于 `ISTA-DASLab` 50% 能力剪枝、保留核心 `192` 编程/推理专家的 `GSQ-RCO IQ2_XXS` 主干 `72.1 GB` + `110.6 GB` `IQ4_NL` Engram + `BF16` 视觉，总计 **`183.7 GB`**）。
  - **为何不换用未剪枝 `huihui-ai/Huihui-DeepSeek-V4.1-Flash-1017-abliterated-GGUF`**：该仓库可直接加载的成品仅有 **`1-bit`** 的 `UD-IQ1_S`（`234 GB`，贴近本地盘红线，且主干 `114 GiB` 超出 G4 显存、须卸载约 `30 GiB` 专家至内存而大幅降速）与 `UD-IQ1_M`（`251 GB`，超出本地盘安全容量），其余 `Q2` / `Coder` 均为需本地二次重写的 `patch` 差分包；而当前 `Abiray` 成品版不仅稳留约 `65 GB` 本地盘空间、**主干 100% 全驻 G4 显存（`n_cpu_moe=0`）+ `103 GiB` Engram 全驻 DDR5 内存跑满 `1,048,576`（1M）上下文**，且 `192` 个 `IQ2_XXS` 编程专家保持字节级无损（与原版 Top-1 一致率 `99.80%`、安全拒答率 `0.0%`）。
- **`qwen-flash`（日常通用对话、超长文档理解与文学创作首选）**：默认部署 `huihui-ai/Huihui-Qwen3.8-Flash-Next-abliterated-v2-GGUF` 成品目录 **`unsloth-UD-Q4_K_XL-V2`**（`imatrix_micro3` 校准 **4-bit** 量化，`103.7 GiB` + `BF16` 视觉；该目录已是去审查重校准成品，无需也不应重复叠加仓库内的 `patch-unsloth` 差分包）。通过 `26.82 GiB` PLE 表常驻 DDR5 内存、`q8_0` 压缩 KV/QSA 索引缓存（`16.05 GiB`）及自动卸载仅 `3/48` 层路由专家（`4.39 GiB`），在 G4 上跑满 **`1,048,576`（1M）** 上下文，实测生成吞吐达 **`67 ~ 88 tok/s`**（`84K` 无缓存输入 Prefill 达 `818 tok/s`）。
- **`ollama --preset huihui-27b`（无损 BF16 稠密模型与多协议兼容首选）**：在 G4 上一键部署 `huihui_ai/Qwen3.8-abliterated:27b-bf16`（约 `56 GB` 满血 BF16 权重 + 原生 `262,144` 上下文 + `f16` KV），原生同时开放 Ollama `/api/*`、OpenAI `/v1/*` 与 Anthropic `/v1/messages` 三套接口。
- **`deepseek-qwen-9b`（L4 / T4 省配额高吞吐强推理与多模态首选）**：默认在 **L4（24 GB）** 上部署 `xtools-at/DeepSeek-V4-Pro-Qwen3.5-9B-UNCENSORED-heretic` 的 imatrix 校准 **`i1-Q4_K_M`（`5.24 GiB`）** + **原生 Multi-Token Prediction（`MTP`）草稿侧车（`--spec-type draft-mtp`）** + `mmproj-f16` 视觉（亦可 `--quant Q8_0` 切换 8-bit）；依托 24 层 Gated DeltaNet + 主干/MTP 共 9 层全注意力的混合结构，**256K（`262,144`）满窗口 `q8_0` KV 仅占 `4.83 GiB`**，在 L4（余量 `~9.3 GiB`）上全层 GPU 常驻跑满原生 256K 上下文 + 深度思考 + 视觉理解（`--gpu T4` 同样自动启用 `i1-Q4_K_M` + MTP）。

### 图像生成与多图编辑选型说明（Colab G4 硬件边界）

- **`minimax-h3-image`（旗舰原生 4K 商业质感生图与 1–16 张多参考图编辑首选）**：基于 **SGLang Diffusion + FlashAttention-4** 部署 `MiniMaxAI/MiniMax-H3-Image`（33.1B DiT + 33.4B Qwen3-VL 编码器 + MiniMaxH3ImageVAE，6 步融合 PDD 蒸馏调度 + 在线 AdaLN 预计算释放 `24.6 GiB` 显存）。默认 `fp8-all` 全组件常驻（峰值显存仅 **`~50.4 GiB`**，G4 实测 GPU 推理 **2K 约 `2.6s`、原生 4K `5472×3072` 约 `15.7s`**，留出 `~45 GiB` 余量应对多参考图编辑），亦可 `--quantization bf16` 切换单卡无损常驻（`~92.2 GiB`）；CLI 默认走网络友好的内部 `/api/ct/*` 协议（本地参考图裸二进制上传 + SHA-256 零字节去重、异步后台任务轮询、`HTTP Range` 断点续传与服务端 WebP/JPEG 实时转码、Google Drive 零流量直读直写），同时兼容标准 OpenAI `/v1/images/*`。
- **`qwen-image`（中英双语精准文字排版与原生 RGBA 透明底素材首选）**：基于 `vLLM-Omni` 部署 `Qwen/Qwen-Image-2.1`（7.1B DiT + Qwen3-VL-8B + 4 通道 RGBA VAE），支持 `--rgba` 原生透明通道直出、1–4 张 `<image1>..<image4>` 序号绑定编辑与 LoRA 适配器。
- **`flux-klein`（轻量多卡阶梯兼容、LoRA 生态与提示词扩写首选）**：基于 `vLLM-Omni` 部署 `black-forest-labs/flux-3-image-klein`（5.6B DiT，支持 G4 / H100 / L4），支持 1–10 张参考图编辑、LoRA 适配器以及可选 `flux-3-image-klein-pup`（Qwen3.5-9B）提示词自动扩写。

## 目录结构

```text
LICENSE                        # MIT 开源许可证
pyproject.toml                 # 包元数据、版本、colabllm 命令入口
src/colabllm/
├── cli.py                     # 统一命令分发
├── control.py                 # 全局域名与 FRP 管理
├── utility.py                 # 通用工具子命令
├── lib/                       # 本地共享 runner、状态、HTTP/音频工具与 FRP 实现
└── services/                  # <name>.py + <name>.ipynb；随包安装
templates/                     # notebook 生成器 build_notebooks.py 与嵌入 notebook 的独立模块
docs/                          # 各运行时与 FRP/通用操作文档
skills/colabllm/               # 随包分发的用户 Agent Skill（references 由 docs 同步生成）
tools/                         # 文档同步、分发包校验、基准测试等开发工具
tests/                         # 本地测试（Python 标准库）
tests_colab/                   # 仅在 Colab 模型环境运行的回归测试
```

## 本地环境与前置准备

本机负责创建 Colab 会话、配置隧道、挂载网盘和维持后台连接；模型在远端运行，**本机无需 GPU、CUDA、PyTorch 或模型权重**。

### 必需与可选依赖

| 本机环境 / 工具 | 何时需要 | 说明 |
| --- | --- | --- |
| Linux 或 macOS | 必需 | Colab CLI 当前支持的平台；本项目后台进程管理也使用 Unix 进程组 |
| Python 3.12+ | 必需 | 执行 `src/colabllm/services/*.py`、`src/colabllm/control.py`，满足 `google-colab-cli` 的 Python 要求 |
| `uv` | 包安装与升级 | 隔离安装 colabllm 和 Colab CLI；Git 仅开发时需要 |
| `colab` CLI | 必需 | PyPI 包 `google-colab-cli`，用于会话、文件操作及执行 Notebook |
| `colab-ext` 扩展 | 默认网盘及多账户必需 | [colab-ext](https://github.com/deluxebear/colab-ext)，提供 `drive`（兼容别名 `dfs`）、多账户 `account` 与 `-a`、`ext doctor`；需单独安装 |
| Node.js、npm、Cloudflare `cf` CLI | 固定域名或 FRP 模式 | 本机调用 Cloudflare API 管理 DNS；Cloudflare named tunnel 也由它配置。Quick Tunnel 不需要它 |
| OpenSSH 客户端 `ssh` | FRP 模式；或 Colab SSH 排错 | 用于连接 FRP 服务器，复用 `~/.ssh/config` 的密钥、端口和跳板配置 |

准备可使用所需 GPU 运行时的 Google/Colab 账号，以及有可用空间的 Google Drive。GPU 配额、计算单元余额和机型可用性以账号当前状态为准。首次 Google、Drive 和 Cloudflare 授权需要浏览器完成。

### 1. 安装 Colab CLI

先按 [uv 官方说明](https://docs.astral.sh/uv/getting-started/installation/) 安装 `uv`，并准备 Python 3.12+。使用独立工具环境安装：

```bash
uv tool install google-colab-cli
uv tool update-shell
# 重新打开终端，或按 update-shell 的提示加载 PATH
colab version
colab --help
```

安装来源：[google-colab-cli](https://github.com/googlecolab/google-colab-cli)。首次运行 `colab sessions` 时，按 CLI 的提示完成 Google 认证；需要自行提供 OAuth 客户端配置的环境，应按上游说明放在默认的 `~/.colab-cli-oauth-config.json`。本项目后台调用 `colab`，因此应先在同一用户环境中完成授权。

```bash
colab sessions       # 确认可访问 Colab；不创建新 VM
colab usage          # 查看账号计算单元用量/余额
```

### 2. 安装并授权 `colab-ext` 扩展（免浏览器 Drive 挂载 + 原生多账户）

本项目启动时默认通过免浏览器 DriveFS 挂载网盘（底层调用 `colab dfs mount`，`colab-ext` 中 `dfs` 与 `drive` 等价），不依赖 Notebook 内交互式的 `drive.mount()`；同时也全面兼容 `colab-ext` 的原生多账户会话隔离与共享网盘绑定。扩展来自 [deluxebear/colab-ext](https://github.com/deluxebear/colab-ext)，需在安装 Colab CLI 后单独安装：

```bash
curl -fsSL https://raw.githubusercontent.com/deluxebear/colab-ext/main/install.sh | sh
```

也可以克隆扩展仓库后运行 `python3 install.py`。安装器将源码保存到 `~/.colab-ext/`（旧 `~/.colab-dfs-ext/` 会自动迁移），并自动接入提供 `colab` 命令的 Python 环境；详细选项见[扩展中文说明](https://github.com/deluxebear/colab-ext/blob/main/README.zh-CN.md)。安装后检查并进行一次性 Drive 授权：

```bash
colab ext doctor
colab ext version
colab drive --help       # 旧命令 colab dfs 仍完全兼容
colab drive consent      # 浏览器完成一次授权，后续挂载无需再次交互
colab drive show         # 查看当前/共享 Drive 授权摘要，不打印 refresh token
```

Drive 授权与 Colab 会话认证分别进行。安装多账户扩展后，凭据与会话按账户隔离保存在 `~/.config/colab-cli/accounts/<账户名>/`（主注册表为 `~/.config/colab-cli/accounts.json`；未升级扩展前的单账户凭据位于 `~/.config/colab-cli/dfs_credentials.json`）。正常使用时，服务脚本自动按账户和共享 Drive 绑定挂载远端 `/content/drive`，无需手工调用 `mount`；已有空闲会话可用 `colab -a <账户> drive mount -s <会话名>` 验证。

升级 Colab CLI 后，可执行 `colab ext doctor` 检查扩展是否仍在；命令可用时可运行 `colab ext install` 重新接入。若出现 `No such command: drive` 或 `dfs`，且扩展仍在 `~/.colab-ext/`，可重新运行安装器修复：

```bash
python3 "$HOME/.colab-ext/install.py"
colab ext doctor
```

若扩展目录缺失，重新运行上面的安装命令。`up --no-drive` 可跳过自动挂载，但需要网盘音色、任务持久化和输出保存的功能仍依赖 Drive，不适合作为这些功能的替代配置。

#### 多账户与共享 Google Drive 用法（多张 GPU / 配额轮换）

一个拥有计算单元或 Pro 配额的 Google 账号可能与专门存放大模型缓存的 Google Drive 主账号分离，或需要同时使用多个 Google 账号并发运行多个 Colab GPU 实例并共享同一份网盘数据/模型权重。先在 `colab` CLI 中完成账户登记与共享网盘绑定：

```bash
# 1. 在主网盘账号完成登录与一次 Drive 授权
colab account list
colab -a main drive consent

# 2. 添加用于跑 GPU 的副号并登录，然后将其默认 Drive 绑定到 main（只需一次）
colab account add gpu2
colab account set-drive gpu2 main
# 或设置全账户兜底共享网盘：colab account set-drive --default main

# 3. 检查全部账户会话与配额，或用 doctor 定向检查某个账户
colab sessions --all
colab usage --all
colabllm doctor -a gpu2 --online
```

完成上述绑定后即可直接通过 `-a` / `--account` 与 `--drive-account` 在多个账户间无感切换或并发运行：

```bash
# 切换活动账户：之后不传 --account 的新 up 默认使用 gpu2，运行中的旧实例保持锁定原账户
colab account use gpu2
colabllm qwen-flash up --domain

# 或单次显式指定算力账户与共享网盘账户（两者互不影响）
colabllm qwen-flash up -a gpu2 --drive-account main --auto-restart --domain

# 多账户多卡并发，同时共享同一份 MyDrive/colab-llm 模型缓存
colabllm ollama up -i 1 -a main --domain                     # -> https://ollama-1.example.com（使用 main 算力与网盘）
colabllm ollama up -i 2 -a gpu2 --drive-account main --domain  # -> https://ollama-2.example.com（使用 gpu2 算力 + main 网盘）
colabllm ollama ps
```

> 说明：在 `minimax-h3-image` 的 `generate` / `edit` 等生图子命令中短参数 `-a` 已用于 `--aspect`（宽高比）；若需在业务子命令前置指定账户，请统一使用长参数 `--account <账户>`（例如 `colabllm nemotron-transcribe --account gpu2 ls-drive`），而在 `up` 与 `doctor` 子命令中 `-a` 与 `--account` 均可直接使用。

### 3. 安装 Cloudflare `cf` CLI

使用固定域名时，无论选择 Cloudflare Tunnel 还是 FRP，都需要在**本机**安装并授权 `cf`。这里的 `cf` 是 Cloudflare CLI，不是 Cloud Foundry CLI，也不是远端运行的 `cloudflared`。

准备符合所安装 `cf` 版本要求的 Node.js/npm，然后安装：

```bash
node --version
npm --version
npm install --global cf
cf --version
cf auth login
cf auth whoami
```

安装和认证说明见 [Cloudflare 官方文档](https://developers.cloudflare.com/cf/get-started/)。账号需有目标域名的 Zone/DNS 管理权限；使用 named tunnel 时还需有隧道管理权限。`cf zones list` 可检查域名是否在当前账号中。只使用 Cloudflare 动态 URL 时，可跳过本节。

本机已验证的组合为 `google-colab-cli 0.7.5`、`colab-ext 0.3.0`、`cf 1.0.0-beta.26` 和 Node.js `26.13.0`。其中该 `cf` 版本的 Node.js 要求为 `^22.23.0 || ^24.22.0 || ^26.12.0`；升级版本时以 npm 包的 `engines` 声明为准，避免仅按大版本判断兼容性。

### 4. FRP 模式额外要求

本机需要 OpenSSH，以及能够非交互连接服务器的密钥配置：

```bash
ssh -V
ssh -o BatchMode=yes root@frpip 'id -u'
```

`root@frpip` 是示例，替换为实际 SSH 目标；首次连接应先核实服务器主机指纹。服务器需要 Linux、systemd、Python 3，以及 root 或免密 sudo；读取既有 FRP TOML 配置需要服务器 Python 3.11+。服务端需允许公网 TCP 7000、80 和 443。配置命令会安装或复用服务器上的 frps/Caddy，本机不需要预先安装它们，详见 [FRP 操作说明](https://github.com/deluxebear/colabllm/blob/master/docs/frp.md)。

### 启动前自检

在项目根目录、实际用于运行服务的终端中执行：

```bash
python3 --version
command -v colab
colab version
colab ext doctor
colab drive show
colab account list
colabllm tunnel-config
# 固定域名 / FRP 模式还需检查
command -v cf
cf --version
cf auth whoami
# FRP 模式还需检查
ssh -V
colabllm frp-status
```

认证文件保存在本机用户目录，运行时状态保存在用户目录 `~/.colabllm/services/`。执行脚本的本机需要持续在线且避免休眠：后台 runner 维持 `colab exec` 连接，断开可能导致 Colab 会话被回收。远端所需模型依赖、`cloudflared`/`frpc` 和认证 Caddy 由 Notebook 安装，不需要在本机重复安装。

## Cloudflare Tunnel 配置

通过 `colabllm tunnel-config` 统一配置；所有现有及新增运行时、所有实例均读取同一份主域名配置，保存在本机 `~/.colabllm/tunnel-config.json`。未启用 FRP 且配置为空时，`up`（包括不带 HOST 的 `up --domain`）使用 Cloudflare Quick Tunnel 的随机 `https://*.trycloudflare.com` URL，无需 `cf` 登录；每次启动 URL 可能变化。代码中的历史 `example.com` 后缀不再自动启用。

```bash
# 查看 / 设置 / 清除全局主域名（项目根目录统一入口）
colabllm tunnel-config
colabllm tunnel-config --base-domain example.com
colabllm tunnel-config --clear

# 只为本次启动指定主域名，不写入配置
colabllm longcat-avatar up --base-domain example.com
# -> https://longcat-avatar.example.com
colabllm qwen-flash up -i 2 --base-domain example.com
# -> https://qwen-2.example.com（保留服务别名与实例后缀）

# 已配置主域名后：up 自动使用固定域名；也可以强制动态 URL
colabllm longcat-avatar up
colabllm longcat-avatar up --quick-tunnel

# 完整域名覆盖自动生成的服务域名
colabllm longcat-avatar up --domain avatar.example.com
```

可设置环境变量 `COLABSVC_BASE_DOMAIN=example.com`。选择顺序：`--quick-tunnel` 强制动态；完整 `--domain HOST` > `--base-domain` > 环境变量 > 全局配置 > 动态 URL。三个启动选项互斥。域名只填 DNS 名称，不包含 `https://`、端口或路径。

Cloudflare 固定域名要求 `cf auth login` 且账户有该域名的 DNS Zone 权限，启动时自动创建/复用 named tunnel、设置 ingress 和 DNS CNAME。配置修改仅影响之后的启动，不会重启运行中的服务；已有服务需自行择机重启。切换动态模式不会删除旧隧道和 DNS，可使用 `down --delete-tunnel` 显式清理。

## FRP 后端（项目全局）

默认使用 Cloudflare Tunnel；全局配置 FRP 后，所有运行时的新启动自动使用 FRP + 服务端 Caddy HTTPS。

```bash
# 配置并通过 SSH 自动安装服务端（替换示例 IP、SSH 目标和域名）
colabllm frp-config --server-ip 203.0.113.10 --ssh root@frpip --base-domain example.com
colabllm frp-status
colabllm indextts up

# 本次覆盖 / 关闭全局 FRP
colabllm indextts up --transport cloudflare
colabllm indextts up --quick-tunnel
colabllm frp-config --disable
```

FRP 服务端默认 TCP 7000，Caddy 使用 80/443；DNS 经本机 `cf` 自动配置为 DNS only。配置、自动安装、认证及清理说明见 [FRP 操作说明](https://github.com/deluxebear/colabllm/blob/master/docs/frp.md)。现有运行时不会自动切换。

## 常用命令

以 `unsloth-studio` 和 `ollama` 为例：

```bash
# 1. 启动服务（未配置主域名时使用随机 *.trycloudflare.com 临时链接）
colabllm unsloth-studio up

# 2. 配置所有服务共享的主域名，再启动固定域名服务
colabllm tunnel-config --base-domain example.com
colabllm ollama up --domain
colabllm qwen-flash up --domain     # 绑定 https://qwen.example.com（G4 GPU，1M 上下文 + 视觉）

# 3. 查看访问 URL、登录密码与 API Token
colabllm ollama info --show-secrets

# 4. 查看实时日志 / 检查状态与公网连通性
colabllm ollama logs -f
colabllm ollama status

# 5. 停止服务并释放 Colab VM（加 --delete-tunnel 同时删除 Cloudflare 隧道和 DNS 记录）
colabllm ollama down
colabllm ollama down --delete-tunnel
```

## 多实例（多会话）并发支持（所有运行时通用）

所有运行时脚本（`nemotron-transcribe.py`、`comfyui.py`、`qwen-flash.py`、`ollama.py`、`unsloth-studio.py` 以及 `templates/service.py`）均原生支持通过 **`-i <ID>` / `--instance <ID>`**（或环境变量 `CT_INSTANCE=<ID>`）创建和管理多个独立的 Colab GPU 会话与隧道：

| 实例参数 | Colab 会话名 (`-s`) | 状态目录 (`~/.colabllm/services/`) | 隧道名 (`--domain`) | 默认域名 (`--domain`) | 网盘共享目录 (`CT_DATA_DIR`) |
| --- | --- | --- | --- | --- | --- |
| 默认（不传 `-i`） | `<name>` | `~/.colabllm/services/<name>/` | `colab-<name>` | `<host>.example.com` | `/content/drive/MyDrive/colab-llm/<name>` |
| `-i 1` | `<name>-1` | `~/.colabllm/services/<name>-1/` | `colab-<name>-1` | `<host>-1.example.com` | `/content/drive/MyDrive/colab-llm/<name>`（共享缓存与数据；可用 `-a`/`--drive-account` 跨号共享同一网盘） |
| `-i 2` | `<name>-2` | `~/.colabllm/services/<name>-2/` | `colab-<name>-2` | `<host>-2.example.com` | `/content/drive/MyDrive/colab-llm/<name>`（共享缓存与数据；可用 `-a`/`--drive-account` 跨号共享同一网盘） |

```bash
# 启动任意运行时的多个并发实例（各自拥有独立的 Colab GPU VM、Cloudflare 隧道与域名；可绑定不同账户）
colabllm comfyui up -i 1 --domain               # -> https://comfyui-1.example.com
colabllm comfyui up -i 2 -a gpu2 --domain       # -> https://comfyui-2.example.com（使用 gpu2 账户算力 + 其绑定或指定的 Drive）
colabllm qwen-flash up -i 2 --domain            # -> https://qwen-2.example.com
colabllm ollama up -i 2 --domain                # -> https://ollama-2.example.com
colabllm unsloth-studio up -i 2 --domain        # -> https://unsloth-studio-2.example.com
colabllm nemotron-transcribe up -i 2 --domain   # -> https://transcribe-2.example.com

# 列出某个服务的所有实例状态、URL 与 API Token
colabllm <name> ps

# 查看指定实例的详情 / 日志 / 状态
colabllm <name> info --show-secrets -i 2
colabllm <name> logs -i 2 -f
colabllm <name> status -i 2

# 停止指定实例，或使用 --all 一键停止该服务的所有实例
colabllm <name> down -i 2
colabllm <name> down --all
```

## 新增一个大模型服务

1. 复制模板：
   ```bash
   cp templates/service.py src/colabllm/services/<name>.py
   cp templates/service.ipynb src/colabllm/services/<name>.ipynb
   chmod +x src/colabllm/services/<name>.py
   ```
2. 修改 `src/colabllm/services/<name>.py` 中的 `Service(...)` 配置（端口、`auth="caddy"` 或 `"builtin"`、GPU 类型）。
3. 修改 `src/colabllm/services/<name>.ipynb` 的 **Cell 1（安装）** 和 **Cell 2（启动服务，绑定 `127.0.0.1`）**。
4. 先运行 `colabllm <name> up --dry-run` 检查执行计划，再正式运行 `up`。
5. 同一变更中更新 `docs/<name>.md`，运行 `python tools/sync_runtime_docs.py` 生成对应的技能参考文档，并更新 `skills/colabllm/SKILL.md` 的运行时索引，覆盖启动、调用、输入输出、认证和任务恢复。新增、删除运行时或修改命令行为都需要同步维护用户技能。
6. 核对技能示例与实际 CLI 参数一致，构建分发包，并用 `tools/check_distribution.py` 验证安装、运行时发现和完整技能导出；新增文件类型时同步调整打包规则。运行时及其用户技能均可从安装包使用后，才算完成新增流程。

详细规范与排错指南见 [`.agents/skills/colab-llm-service/SKILL.md`](https://github.com/deluxebear/colabllm/blob/master/.agents/skills/colab-llm-service/SKILL.md)。

## 修改 notebook

`src/colabllm/services/*.ipynb` 与 `templates/service.ipynb` 由 `templates/build_notebooks.py` 生成，请勿直接手改。
中间件、缓存、隧道等逻辑以独立模块保存在 `templates/`（如 `colab_asgi_common.py`、`colab_cache.py`、`tunnel_client.py`），
可在本地单元测试；修改后运行 `python3 templates/build_notebooks.py` 重新生成，测试会校验生成结果与提交内容一致。

## License

本项目基于 [MIT License](https://github.com/deluxebear/colabllm/blob/master/LICENSE) 开源。
各运行时下载的第三方模型、镜像与软件遵循其各自的许可证与使用条款，请在使用前自行确认。
