过去一个月我重度使用 Claude Code，发现一个反复出现的问题：
描述了一个复杂的多步骤任务 → AI 开始执行 → 中间上下文被压缩 → 之前的进度全丢了 → 不知道跑到哪了
更糟糕的是训练场景——挂着一晚上跑微调，第二天起来发现半夜就 OOM 挂了，整整 6 个小时白等。
AI 任务的进度，完全是个黑盒。
于是我花了两天时间，写了这个 Claude Code Skill——progress-tracker。
它是什么？
一个双层架构的 AI 任务进度跟踪系统：
┌─────────────────────────────────────────┐
│ Skill 层（对话驱动） │
│ AI 识别多步骤任务 → 自动创建清单 → 静默更新 │
├─────────────────────────────────────────┤
│ Runtime 层（代码自主上报） │
│ @track 装饰器 / RuntimeTracker / CLI │
│ 训练脚本无需 AI 介入，自主报告进度 │
└─────────────────────────────────────────┘
核心思路很简单：
- Skill 层负责对话中的任务管理——你描述工作流，AI 自动建清单、跟踪状态
- Runtime 层负责脱离对话的进度上报——你的训练脚本自己报告百分比，不需要 AI 在线
两层共享同一份 progress.json，互不依赖。
怎么用？
安装（一行命令）
git clone https://github.com/wpylove666/progress-tracker.git ~/.claude/skills/progress-tracker
重启 Claude Code，搞定。不需要配置文件，不需要 API Key，不需要数据库。
Skill 层：对话中自动触发
你只需要正常对话：
👤 我要微调 Qwen2.5：准备数据 → 配置 LoRA → 训练 → 评估 → 导出
🤖 检测到 5 步工作流，建议创建进度跟踪：
+ 微调 Qwen2.5
[ ] 准备训练数据
[ ] 配置 LoRA 参数
[ ] 启动训练
[ ] 评估模型
[ ] 导出模型
创建？[Y/n]
执行过程中：
- ✅ 步骤完成 → 静默更新，不打扰你
- ❌ 步骤失败 → 立即告警（"CUDA OOM at step 1500, try reducing batch size"）
- 📊 随时问"进度如何" → 显示完整进度树
Runtime 层：训练脚本自主上报
这是 v0.2.0 新增的能力。有三种使用方式：
方式一：装饰器（最省事）
from runtime import track
@track(task_id="t1.3")
def train_model(epochs=10):
for epoch in range(epochs):
...
函数执行前自动标记 in_progress，成功返回标记 done，抛异常自动写入 alert。一行代码搞定。
方式二：手动控制（训练循环内）
from runtime import RuntimeTracker
tracker = RuntimeTracker(task_id="t1.3")
tracker.start()
for epoch in range(10):
train_epoch()
tracker.report(pct=(epoch + 1) * 10, msg=f"Epoch {epoch+1}/10")
tracker.done()
方式三：CLI（Shell 脚本也能用）
python runtime.py report --id t1.3 --pct 60 --msg "Batch 600/1000"
python runtime.py watch --id t1.3 --interval 5 --timeout 3600
watch 子命令会阻塞等待任务完成，返回不同 exit code——适合 CI/CD pipeline。
终端长什么样？
Progress Tracker - 2026-05-30T14:30:00
+ 微调 Qwen2.5 [==== ] 40%
[x] 准备训练数据
[x] 配置 LoRA 参数
[ ] 启动训练 ← in progress
[ ] 评估模型
Total: 2/4 done (50%)
简洁直观的 ASCII 进度条，一眼看清全局状态。
技术设计
几个我觉得值得一提的设计决策：
1. 零依赖
整个项目 100% Python stdlib。为什么？因为 Claude Code 用户的环境千差万别——有人用 venv，有人用 conda，有人直接在系统 Python 跑。一个 pip install 都没有，意味着到处都能跑。
2. 静默失败
这是 Runtime 层最重要的设计原则：进度上报失败绝不崩溃你的训练任务。
def _safe(fn):
"""所有更新方法都套了这个装饰器"""
@functools.wraps(fn)
def wrapper(*args, **kwargs):
try:
return fn(*args, **kwargs)
except Exception:
pass # 进度上报挂了，训练继续
return wrapper
你跑了一天的训练因为进度上报崩了——这不可接受。
3. 百分比自动计算
progress.json 里的百分比从来不是存储值，而是根据子任务状态实时计算。这避免了"手动改了状态百分比没更新"的陈旧数据问题。
4. 两层解耦
Skill 层和 Runtime 层共享 JSON Schema，但完全独立运作。AI 对话中可以手动更新进度，训练脚本也可以自主上报——互不干扰。
适用场景
- 🏋️ 模型微调/训练（多 epoch，需要实时知道进度和 loss）
- 📊 批量数据处理（多阶段 ETL pipeline）
- 🤖 Claude Code Agent 工作流（多步骤自动化任务编排）
- 🔧 任何需要"知道跑到哪了"的长时 AI 任务
项目状态
- GitHub：wpylove666/progress-tracker
- 当前版本：v0.2.0
- 依赖：0 个
- License：MIT
- UUMit 能力市场：已上架，80 UT
刚发布一天，0 star 起步。如果你也用 Claude Code 做复杂任务，欢迎试试看——clone 下来就能用，不需要任何配置。
后续计划
- 自动生成 Markdown 报告（任务结束后输出总结）
- 多项目并行追踪
- Web Dashboard（给团队看的多任务总览页）
- 更多的 CI/CD 集成（GitHub Actions 原生支持）
如果你有想法或需求，欢迎提 Issue 或 PR 👏
效果图
