讓 Agent 處理長任務：檢查點、分段與進度回報

階段化設計

STAGES = [
  {'name': 'scan',    'desc': '掃描並列出待處理項目', 'max_steps': 5},
  {'name': 'process', 'desc': '逐項處理',             'max_steps': 3, 'per_item': True},
  {'name': 'verify',  'desc': '檢查結果一致性',       'max_steps': 4},
  {'name': 'report',  'desc': '產出總結報告',         'max_steps': 2},
]

每個階段是一次獨立的 Agent 執行，有自己的上下文與步數上限。階段之間只傳遞結構化結果，不傳遞完整對話歷史——這是控制上下文膨脹的關鍵。

逐項處理的檢查點

def process_stage(items, run_id):
    done = store.completed_items(run_id)        # 續跑時跳過已完成的
    for it in items:
        if it['id'] in done:
            continue
        try:
            result = run_agent(f"處理項目：{it}", max_steps=3)
            store.save_item(run_id, it['id'], result, status='ok')
        except Exception as e:
            store.save_item(run_id, it['id'], None, status='failed', error=str(e))
        emit_progress(run_id, done=len(done) + 1, total=len(items))

注意失敗的項目也要記錄並繼續，不要讓一個壞掉的項目中斷整批。最後在報告階段列出失敗清單。

進度回報的三個層次

• 階段層級：目前在第幾階段、共幾階段。
• 項目層級：已完成 47 / 320 項。
• 當前動作：「正在分析 invoice_0048.pdf」。

第三層特別重要。使用者看到具體的檔名在跳動，就知道系統還活著；只有進度條時，卡住三分鐘就會被當成當機。

上下文預算

def stage_context(prev_results, budget_tokens=6000):
    # 只傳遞摘要與關鍵欄位，不傳完整內容
    summary = summarize_results(prev_results, max_tokens=budget_tokens // 2)
    stats = {'total': len(prev_results),
             'ok': sum(r['status'] == 'ok' for r in prev_results),
             'failed_ids': [r['id'] for r in prev_results if r['status'] != 'ok'][:20]}
    return {'summary': summary, 'stats': stats}

可中斷與可恢復

1. 使用者可以隨時暫停，已完成的部分保留。
2. 恢復時從最後一個檢查點續跑，不重做已完成的項目。
3. 取消時要清楚說明「已完成的部分是否保留」。