初始化设置

首次使用时，请先阅读 setup.md，并在提出 Notebook 修改建议前，明确激活行为与风险边界。

适用场景

当用户需要在 Google Colab 中开展具备可复现性的 Notebook 工作（而非一次性试错）时使用。本 Agent 负责运行时环境搭建、包与依赖管理、数据导入导出流程、故障调试以及实验追踪。

架构设计

记忆状态存储于 ~/google-colab/ 目录下。有关初始化配置与状态字段定义，请参阅 memory-template.md。

~/google-colab/
|-- memory.md                   # 激活偏好、约束条件及当前目标
|-- notebooks.md                # Notebook 注册表（含所有者与各 Notebook 的目标）
|-- runtimes.md                 # 运行时选择、依赖版本锁定及重启历史
|-- datasets.md                 # 数据源映射、挂载路径与验证备注
|-- incidents.md                # 错误时间线、根本原因与修复措施
`-- experiments.md              # 假设、指标与可复现性证据

快速查阅指南

请为当前任务选用最小且最相关的文件。

系统要求

• 用于诊断与轻量级 API 检查：curl、jq
• 用于 Notebook 执行：具备 Colab 访问权限的 Google 账户
• 用于数据集挂载：需显式授予对 Google Drive、GCS 或外部端点的访问权限

切勿要求用户将 API 密钥、OAuth 刷新令牌或私有数据集凭证粘贴至聊天窗口中。

数据存储

本地运维记录统一保存在 ~/google-colab/ 目录中：

• Notebook 清单（含目标、所有者与当前状态）
• 运行时与依赖决策（含版本锁定信息）
• 数据集与 Schema 验证历史
• 实验结果与未解决的风险项

核心规则

1. 以目标、约束与退出条件为起点

编写 Notebook 步骤前，须明确以下三点：

• 目标：原型开发、基准测试、微调、教学演示，或生产就绪准备
• 约束：运行时规格（如 CPU/T4/L4/A100）、预算、执行时长、数据可用性
• 退出条件：指标阈值、产物输出，或关键决策检查点

若无明确退出条件，Notebook 会偏离预期方向，难以评估成效。

2. 将 Notebook 单元格设计为契约

每个单元格应具备清晰契约：

• 所需输入及其来源
• 确定性输出结构与校验方式
• 失败模式及降级行为

将单元格间隐式状态视为技术债务；所有状态依赖均需显式记录。

3. 锁定运行时与依赖状态

任何可执行方案必须明确定义：

• Python 版本与运行时类型（CPU、T4、L4、A100 等，视场景而定）
• 非标准库的精确依赖版本
• 运行时断连或重启后的状态重建步骤

不可假设新启动的运行时与此前依赖状态一致。

4. 在训练或评估前验证数据路径与 Schema

在执行高开销操作前：

• 确认挂载成功且路径存在
• 采样并校验 Schema 及空值分布模式
• 当数据集划分边界或标签列含义模糊时，主动阻断执行

快速 Schema 检查可避免长时间失败运行及无效指标产出。

5. 显式声明成本与时间防护机制

对于中高成本运行任务：

• 预估运行时长与检查点间隔
• 定义早停条件与预算截断规则
• 建议先用小规模干运行（dry-run）数据集进行验证

任何全量运行启动前，必须已设定预算上限与截断规则。

6. 按层级而非猜测进行故障归因

分层调试流程如下：

1. 运行时健康状态与包导入层
2. 数据加载与预处理层
3. 模型逻辑与训练循环层
4. 评估与产物导出层

分层归因可缩短故障响应时间，避免随机修补。

7. 每次重要运行均须记录可复现性证据

针对每次具有实际意义的运行，需采集：

• Notebook ID 或链接、运行时类型、随机种子、依赖快照
• 数据集版本或时间戳、划分方式
• 主指标结果及是否满足退出条件

若缺失可复现性证据，则所有结论均视为临时性结论。

常见陷阱

• 跨单元格随意安装未锁定版本的包 → 运行时重连后结果不一致
• 复用旧会话中的绝对本地路径 → 回放时文件无法定位
• 未完成 Schema 与空值校验即开始训练 → GPU 时间浪费、指标失真
• 在同一 Notebook 中混用探索性与生产级单元格 → 执行顺序脆弱易断
• 将缓存输出误认为最新真实结果 → 评估陈旧、决策错误
• 忽略随机种子与数据划分控制 → 实验结果无法横向对比
• 导出产物时不附带元数据 → 后续无法审计模型文件

外部端点

除非用户显式配置额外系统，否则不应向其他外部端点发送任何数据。

安全与隐私

离开本地设备的数据包括：

• Colab 服务必需的 Notebook 载荷与运行时元数据
• Drive 或 GCS 操作所需的文件与对象元数据
• 依赖安装所需的包查找请求

保留在本地的数据包括：

• 位于 ~/google-colab/ 下的工作流记忆与决策日志
• 故障记录、实验摘要与验证证据

本能力不会：

• 在对话文本中请求或存储原始密钥
• 在无显式防护机制前提下执行高成本运行
• 绕过用户定义的数据边界或合规规则

信任声明

本能力依赖于 Google Colab、Google API 及 Notebook 初始化过程中使用的包仓库。仅当您信任这些系统对您的代码与数据的处理能力时，方可安装并启用本能力。

关联能力

若用户确认，可通过 clawhub install 安装：

• gcp —— 规划 Google 环境下的云工作负载、存储与服务边界
• api —— 设计面向数据与模型集成的弹性 API 契约
• pandas —— 构建健壮的表格数据转换与验证流水线
• numpy —— 优化数值计算模式与向量化操作
• automate —— 将可重复的 Notebook 步骤转化为可靠自动化工作流

反馈

• 若体验良好：clawhub star google-colab
• 保持更新：clawhub sync