scaffold-colab

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Colab-Centric Project Scaffold

以 Colab 为中心的项目脚手架

Build only after inspecting what the notebooks deliver, who reads and runs them, which runtime they need (CPU, GPU, TPU), and every working tool or structure already present. Present the intended concrete project shape to the user before creating anything.

只有在检查 notebooks 要交付什么、谁会阅读和运行它们、需要哪种 runtime（CPU、GPU、TPU），以及所有已经存在且可正常使用的工具或结构后，才能开始构建。在创建任何内容之前，先向用户展示拟采用的具体项目形态。

Choose the project shape

选择项目形态

Notebook project (default): the deliverable is Colab notebooks. The repository root holds
```
.ipynb
```
files as local mirrors of the remote Colab notebooks, and the full workflow below applies.
Ephemeral runtime: Colab is only a disposable compute backend — local scripts run on temporary VMs through
```
google-colab-cli
```
, and there may be no notebook at all. Choose this only when the user's goal is explicitly to borrow Colab hardware for scripts. The CLI then becomes required rather than asked-about, colab-mcp becomes optional, and the mirror rule, notebook doctrine, and cell-syntax references do not apply; steps 2, 6, and 7 below reduce to scripts plus the CLI run loop described in references/colab-connection.md.

Do not blend the shapes. When in doubt, ask the user; default to the notebook project.

Notebook 项目（默认）：交付物是 Colab notebooks。仓库根目录保存
```
.ipynb
```
文件，作为远程 Colab notebooks 的本地镜像，并适用下面的完整工作流。
临时 runtime：Colab 仅作为一次性算力后端——本地脚本通过
```
google-colab-cli
```
在临时 VMs 上运行，而且可能完全没有 notebook。仅当用户明确希望为脚本借用 Colab 硬件时，才选择此形态。此时 CLI 是必选项，无需再询问是否安装，colab-mcp 则是可选项；镜像规则、notebook 规范和 cell 语法参考均不适用；下面的步骤 2、6 和 7 将简化为脚本加上 references/colab-connection.md 所述的 CLI 运行循环。

不要混用两种形态。如有疑问，先询问用户；默认采用 notebook 项目。

Workflow

工作流

Confirm the project shape, then what the notebooks teach or demonstrate, the audience, the runtime type (CPU, GPU, TPU), whether cell outputs are committed, and the current repository state.
Lay out the repository. Notebooks are the product and live in the repository root: a single-notebook project keeps one
```
notebook.ipynb
```
; a multi-notebook project keeps several descriptively named root
```
.ipynb
```
files — no
```
notebooks/
```
subdirectory. Each file is the local mirror of a remote Colab notebook and the two must stay identical. Around them goes a thin shell:
```
.editorconfig
```
, pre-commit config, assets/justfile, and assets/agents-md.md copied to
```
AGENTS.md
```
. Rework every line of every copied asset; an unresolved placeholder is an unmade project decision. Do not create
```
src/
```
machinery — reuse and abstraction belong in Python libraries, not in a notebook project.
Treat the Colab preinstalled environment as the dependency baseline. Read references/environment-debugging.md before adding, pinning, or upgrading any package, and whenever local behavior differs from real Colab.
Set up the devcontainer on the official Colab runtime image: read references/local-runtime.md first. Suggest a registry region (
```
us
```
,
```
europe
```
,
```
asia
```
serve identical images) but let the user decide it. Copy and rework the matching devcontainer asset. Make generic devcontainer decisions with the
```
devcontainer-setup
```
skill; if it is not installed, load the
```
ryan-minato-skills-installing
```
skill and install
```
devcontainer-setup
```
as it directs — never run an install command yourself. If the user declines, proceed with the reference alone.
Wire the real-Colab connection: read references/colab-connection.md. Register colab-mcp in the client's project-scoped MCP configuration, then ask the user whether to also install
```
google-colab-cli
```
as an auxiliary tool — never install it unprompted.
Author the notebooks: read references/notebook-doctrine.md before writing or reviewing any notebook cell. Read references/colab-forms.md when adding parameters, cell titles, or hidden-code forms, and references/colab-markdown.md when writing markdown cells.
Validate and synchronize. Edit the local mirror, execute it headlessly in the local runtime container as a first pass, then run it in a real Colab session through colab-mcp for final confirmation. After a change on either side, synchronize the other immediately — colab-mcp is the primary channel,
```
colab upload
```
/
```
colab download
```
the auxiliary one when the CLI is installed. The mirror and the remote notebook must never drift.
Work tracking, planning, and agent-autonomy rules are designed with the
```
meta-workflow-design
```
and
```
meta-agent-authority
```
skills, not improvised here — do not invent an issue, review, or autonomy flow in the scaffold. If they are not installed, load the
```
ryan-minato-skills-installing
```
skill and install the whole
```
meta
```
catalog at project scope as it directs (its builders stack and are disposed together); never run an install command yourself. If the user declines, leave management design out and record the gap in the handoff.
Deposit the durable rules — mirror consistency, dependency baseline, notebook doctrine digest, validation loop — into the target
```
AGENTS.md
```
. Never copy this skill's disposable marker into any generated file.
Run the target repository's checks and inspect the result with the user.
Hand the rest of the harness — entrypoint depth, knowledge, project skills, synchronization — and the closing of the build to the
```
meta-harness- building
```
skill; the same
```
meta
```
catalog install from step 8 covers it when it is not installed. If the user declines that handoff, close here: once the deposit is verified and before the work goes to review, ask the user whether to delete the disposable builders now — the build request is not deletion consent — and on that decision load
```
meta-disposal
```
, which lists, confirms, and removes them. If they keep the builders, leave them in place and out of every commit, and record it in the handoff.

Done when: a fresh checkout opens in the devcontainer, colab-mcp is registered and reachable, every root notebook matches its remote Colab counterpart, the first notebook follows the doctrine and runs clean both in the local container and on real Colab, and the durable rules are recorded in the target AGENTS.md.

Disposable builders never enter a commit: before the first commit, add every skill directory whose description opens with
```
Disposable builder skill (delete after the harness is built):
```
to
```
$(git rev-parse --git-path info/exclude)
```
, stage explicit paths, and read
```
git status
```
before each commit.

确认项目形态，然后确认 notebooks 教授或演示的内容、受众、runtime 类型（CPU、GPU、TPU）、是否将 cell 输出提交到仓库，以及当前仓库状态。
规划仓库结构。Notebooks 就是产品，并位于仓库根目录：单 notebook 项目保留一个
```
notebook.ipynb
```
；多 notebook 项目在根目录保留多个具有描述性名称的
```
.ipynb
```
文件——不设
```
notebooks/
```
子目录。每个文件都是远程 Colab notebook 的本地镜像，两者必须保持一致。在这些文件周围配置一层轻量外壳：
```
.editorconfig
```
、pre-commit 配置、assets/justfile，以及复制为
```
AGENTS.md
```
的 assets/agents-md.md。逐行调整每个复制而来的 asset；任何未处理的占位符都意味着某项项目决策尚未作出。不要创建
```
src/
```
工程结构——复用与抽象应放在 Python 库中，而不是 notebook 项目中。
将 Colab 预装环境视为依赖基线。在添加、固定版本或升级任何依赖包之前，以及每当本地行为与真实 Colab 不一致时，都先阅读 references/environment-debugging.md。
在官方 Colab runtime 镜像上设置 devcontainer：先阅读 references/local-runtime.md。可以建议选择一个 registry 区域（
```
us
```
、
```
europe
```
、
```
asia
```
提供相同的镜像），但最终应由用户决定。复制并调整匹配的 devcontainer asset。通用 devcontainer 决策应使用
```
devcontainer-setup
```
skill；如果尚未安装，则加载
```
ryan-minato-skills-installing
```
skill，并按其指示安装
```
devcontainer-setup
```
——绝不要自行运行安装命令。如果用户拒绝，则仅依据参考文档继续。
建立真实 Colab 连接：先阅读 references/colab-connection.md。在客户端的项目作用域 MCP 配置中注册 colab-mcp，然后询问用户是否还要将
```
google-colab-cli
```
安装为辅助工具——绝不在未经提示的情况下安装。
编写 notebooks：在编写或审查任何 notebook cell 之前，先阅读 references/notebook-doctrine.md。添加参数、cell 标题或隐藏代码表单时，阅读 references/colab-forms.md；编写 markdown cell 时，阅读 references/colab-markdown.md。
验证并同步。编辑本地镜像后，先在本地 runtime 容器中以 headless 模式执行，作为第一轮验证，然后通过 colab-mcp 在真实 Colab 会话中运行，以完成最终确认。任一侧发生变更后，立即同步另一侧——colab-mcp 是主通道；安装 CLI 后，
```
colab upload
```
/
```
colab download
```
是辅助通道。本地镜像与远程 notebook 绝不能出现偏差。
工作跟踪、规划和 Agent 自主性规则应使用
```
meta-workflow-design
```
和
```
meta-agent-authority
```
skills 设计，而不是在此临时发挥——不要在脚手架中自行创建 issue、review 或 autonomy 流程。如果它们尚未安装，则加载
```
ryan-minato-skills-installing
```
skill，并按其指示在项目范围内安装整个
```
meta
```
catalog（这些 builders 会叠加使用并被一并处置）；绝不要自行运行安装命令。如果用户拒绝，则不添加管理设计，并在 handoff 中记录该缺口。
将持久规则——镜像一致性、依赖基线、notebook 规范摘要、验证循环——写入目标
```
AGENTS.md
```
。绝不要将此 skill 的一次性构建器标记复制到任何生成文件中。
运行目标仓库的检查，并与用户一起查看结果。
将 harness 的其余部分——entrypoint 深度、知识、项目 skills、同步——以及构建收尾工作移交给
```
meta-harness-building
```
skill；如果它尚未安装，步骤 8 中对同一
```
meta
```
catalog 的安装也会涵盖它。如果用户拒绝该 handoff，就在此处收尾：一旦规则写入得到验证且在进入 review 之前，询问用户现在是否删除一次性 builders——构建请求并不等于同意删除——并根据该决定加载
```
meta-disposal
```
，由它列出、确认并移除这些 builders。如果用户保留 builders，则让它们留在原处并排除在每次 commit 之外，同时在 handoff 中记录此事。

完成标准：全新 checkout 能在 devcontainer 中打开，colab-mcp 已注册且可访问，根目录中的每个 notebook 都与其远程 Colab 对应项一致，第一个 notebook 符合规范，并且能在本地容器和真实 Colab 中无错误运行，持久规则也已记录到目标

AGENTS.md

中。

一次性 builders 绝不进入 commit：第一次 commit 之前，将所有 description 以
```
Disposable builder skill (delete after the harness is built):
```
开头的 skill 目录添加到
```
$(git rev-parse --git-path info/exclude)
```
，显式暂存指定路径，并在每次 commit 前读取
```
git status
```
。

Gotchas

常见陷阱

The local runtime image approximates Colab; it does not equal it. Drive mounting, Google auth flows, and form-control rendering exist only in real Colab — a local pass is preliminary, only a real Colab run confirms.
pip upgrades inside the preinstalled environment cascade through its tightly coupled dependency set. Add missing packages; upgrade only when unavoidable.
The regional registries are byte-identical mirrors. The choice is download locality, never a technical difference — and it is the user's to make.
Prefer
```
# @param
```
form comments over ipywidgets: they render natively in Colab and degrade to harmless comments everywhere else.

本地 runtime 镜像只是 Colab 的近似环境，并不等同于 Colab。Google Drive 挂载、Google 身份验证流程和表单控件渲染只存在于真实 Colab 中——本地运行通过只是初步结果，只有在真实 Colab 中运行才能最终确认。
在预装环境中进行 pip 升级，会连锁波及其紧密耦合的依赖集合。添加缺失的依赖包；仅在不可避免时升级现有包。
各区域 registry 是字节完全相同的镜像。选择只影响下载距离，不存在技术差异——并且应由用户决定。
优先采用
```
# @param
```
表单注释，而不是 ipywidgets：它们能在 Colab 中原生渲染，并在其他环境中安全降级为普通注释。