agentic-data-science-competition

Agentic 数据科学竞赛

「Agent 不只是提交结果——它会从失败中学习、调整策略，并自主迭代。」

核心理念

这项技能提炼了真实竞赛经验中的实用模式：

1. 把 Agent 当作队友 — 不只是工具，更是能够调研、调试和迭代的协作者
2. 规范驱动开发 — 先编写文档再编码，明确约束后再委派任务
3. 快速失败，更快学习 — 早期分数具有误导性；系统化调试才能取胜
4. 在关键环节自动化 — 使用 Cronjob 进行监控，将复杂工作委派出去

---

快速参考

何时使用此技能

触发条件	操作
开始一场新竞赛	→ 阅读“项目设置”部分
提交返回 400 错误	→ 查看“故障排查”部分
分数意外下降	→ 阅读“分数稳定”部分
需要复现顶级 Notebook	→ 使用“复现工作流”
Kernel 推送失败	→ 查看“Kernel 工作流”部分
需要 GPU，但无法使用	→ 使用“委派策略”

关键命令

# Submit to competition
kaggle competitions submit <name> -f <file> -m "<message>"

# Check submission status
kaggle competitions submissions <name>

# Pull top notebook WITH metadata
kaggle kernels pull <owner>/<kernel> -p ./path/ -m

# Push kernel to Kaggle
kaggle kernels push -p ./path/

# Monitor kernel status
kaggle kernels status <username>/<kernel-name>

---

分数稳定模式

重要发现：提交后，Kaggle 分数需要一段时间才能稳定。

|| 时间 | 分数表现 | 应采取的行动 || |------|----------------|------------|| | 开始 | 基线 | 尽早提交，启动评估 || | +2 小时 | 峰值（虚高） | 不要相信！ 通常是虚高的 || | +4 小时 | 稳定 | 真实分数 — 现在再做决定 ||

经验：不要为早期的高分庆祝。至少等待 4 小时再评估表现。

---

提交故障排查

400 Bad Request 错误

1. 检查提交格式（带或不带表头、引号）
2. 确认 ID 与测试集完全匹配
3. 尝试 .zip 格式 — 部分竞赛要求将 CSV 压缩成 ZIP 文件
4. 检查竞赛要求的是模型提交还是答案提交

ZIP 提交格式（重要！）

常见错误：将文件夹中的所有内容都压缩（包括 __notebook__.ipynb）

正确方法：

import zipfile
with zipfile.ZipFile('submission.zip', 'w', zipfile.ZIP_DEFLATED) as zf:
    zf.write('submission.csv', 'submission.csv')  # Only the CSV!

竞赛类型

类型	提交内容	示例
答案提交	包含预测结果的 CSV	大多数竞赛
模型提交	训练好的模型权重（LoRA、检查点）	部分大模型竞赛

判断方法：查看排名靠前的 Notebook——它们会训练模型，还是只生成预测结果？

---

Kernel 工作流

Run 模式与 Commit 模式

模式	测试集	适用场景
Run	隐藏	开发、调试
Commit（“Save & Run All”）	已挂载	生产环境、最终提交

这点很重要的原因：kaggle kernels push 会以 Run 模式运行。测试集不会挂载。请使用 sample_submission.csv 作为占位文件。

数据路径模式

/kaggle/input/competitions/<competition-name>/   ← Correct!
NOT /kaggle/input/<competition-name>/            ← Wrong!

Kernel 元数据最佳实践

{
  "id": "username/kernel-name",
  "is_private": true,          // ← Always true by default!
  "enable_internet": false,    // ← Check competition rules
  "competition_sources": ["competition-name"],
  "dataset_sources": ["dataset-with-dependencies"]
}

---

复现顶级 Notebook

工作流

# 1. Pull with metadata (-m flag is critical!)
kaggle kernels pull <owner>/<kernel> -p ./solution/ -m

# 2. Edit kernel-metadata.json
#    - Change "id" to your username/new-name
#    - KEEP all dataset_sources, model_sources, kernel_sources

# 3. Push
kaggle kernels push -p ./solution/

# 4. Monitor
kaggle kernels status <your-username>/<new-kernel-name>

关键要点

1. 始终使用 -m 标志 — 获取包含依赖项的 kernel-metadata.json
2. 保留所有依赖项 — dataset_sources、model_sources、kernel_sources
3. 只修改 id 和 title — 其他内容都应与原始版本一致
4. 检查 enable_internet — 如果原始版本为 false，就保持为 false

何时委派

在以下情况下，委派给 OpenCode/Claude Code：

• 将解决方案调整到不同场景
• 结合多种技术
• 与现有代码库集成
• 进行复杂转换或重构

在以下情况下，不要委派：

• 简单的文件下载
• 仅修改元数据
• 不做修改的直接复刻

---

规范驱动开发

流程

1. 先编写 SPEC.md，再开始编码：

   • 竞赛概述（任务、数据、评估）
   • Notebook 中的顶尖方案
   • 策略和实现计划
   • 技术限制
   • 成功指标和时间线

2. 将 SPEC.md 提供给 AI 编码 Agent，并委派任务：

   • 将 SPEC.md 作为上下文提供
   • 说明限制条件（时间限制、GPU 可用情况）
   • 设定明确的成功标准

3. 根据结果迭代

SPEC.md 模板

# SPEC.md - Competition Name

## 1. Competition Overview
- Task, deadline, prize, current top score

## 2. Task Definition
- Input/Output format, data summary

## 3. Top Approaches (from Kaggle Notebooks)
- Approach A: [votes/score], strategy
- Approach B: [votes/score], strategy

## 4. Strategy & Implementation Plan
- Phase 1: Quick baseline
- Phase 2: High-ROI improvements
- Phase 3: Fine-tuning

## 5. Technical Constraints
- Submission format, time limits, GPU requirements

## 6. Success Metrics
| Milestone | Target | Timeline |
|-----------|--------|----------|
| Baseline | 0.xx | Day 1 |
| Improved | 0.xx | Day 2 |

---

委派策略

本地与 Kaggle

任务	地点	原因
数据分析	本地	迭代速度快，无需 GPU
提示词工程	本地	测试快速
模型训练	Kaggle	免费 GPU
大规模推理	Kaggle	GPU + 互联网

何时使用哪种 Agent

Agent	最适合的用途
OpenCode	代码开发、功能实现
Claude Code	PR 审查、复杂调试
子 Agent（delegate_task）	并行研究、独立工作流

---

常见陷阱

1. 调试时回退到训练数据

错误：

test_files = sorted(TEST_DIR.glob("*.ogg"))
if not test_files:
    test_files = sorted((COMP_DIR / "train_soundscapes").glob("*.ogg"))[:10]

正确：

if not test_files:
    submission = pd.read_csv("sample_submission.csv")
    submission.iloc[:, 1:] = 0.0
    submission.to_csv("submission.csv", index=False)

2. 游戏 AI 竞赛需要全面的功能

观察到的模式：表现出色的游戏 Agent 通常需要实现全面的功能。

要点：不要过度简化游戏 AI Agent。研究顶尖方案，了解要参与竞争所需的完整功能集。

3. 文件扩展名重复

检查 filename 列是否已包含扩展名：

# Check this:
print(train_df['filename'].head())

# If it shows "1161364/iNat1216197.ogg", don't add .ogg again!

4. 静默捕获异常

不佳（会隐藏错误）：

try:
    audio, sr = load_audio(file)
except Exception:
    continue  # No idea why it failed!

更好：

try:
    audio, sr = load_audio(file)
except Exception as e:
    print(f"Failed on {file}: {type(e).__name__}: {e}")
    continue

---

API 使用模式

速率限制模式

• 某些 AI API 在高峰时段会触发限制（例如北京时间 10:00-17:00）
• 解决方案：在限制时段切换到备用模型／提供商
• 恢复：限制会在晚间解除

提前规划：委派任务给 AI 编码 Agent 前，先查看时间。

---

验证清单

提交后：

• 检查提交是否显示在 kaggle competitions submissions 中
• 监控状态：PENDING → RUNNING → COMPLETE
• 等待 4 小时以上，再评估最终分数
• 与基线和目标进行比较

---

高级模式

参见 references/research/04-advanced-patterns.md，了解：

• 状态机执行循环 — 容错型自主 Agent 模式
• 配置驱动的 Cronjob 设计 — 无需重新创建任务即可切换实验
• 主管验证职责 — 欺诈检测和溯源验证
• AUC 排名平均 — +0.001–0.005 的提升技术
• ONNX 模型验证 — 禁止使用的操作和错误调试
• 依赖项本地打包 — 离线安装软件包

参见 references/research/05-environment-setup-patterns.md，了解：

• Kaggle Environments 源码安装 — 当 PyPI 版本过时时，从 GitHub 安装最新环境

参见 references/research/06-competition-types-submission-workflow.md，了解：

• 竞赛类型分类 — Prediction／Adapter／ONNX 和 Pure Code／Mixed／Standard
• -k -v 标志要求 — 防止提交记录因缺少 Notebook 关联而成为孤立提交

---

相关技能

技能	用途
agentic-competition-workflow	以 Git 为先的项目管理、验证流水线、完整竞赛生命周期
kaggle-auto-submit	使用 cronjob 监控的端到端自动化
autonomous-iteration	ANALYSIS → BUILD → EXPERIMENT → REVIEW 循环
opencode	将编码任务委派给 OpenCode CLI
claude-code	将编码任务委派给 Claude Code CLI