批次報告技能
為已完成的批次處理作業生成全面的分析報告。
特點
- 清單分析 - 統計成功、失敗、部分完成數量
- 時間分佈 - 各步驟延遲分析，找出瓶頸
- 失敗模式 - 分類與摘要失敗原因
- 品質指標 - 抽樣輸出以進行品質評估
- Markdown 報告 - 人類可讀的摘要
- Agent-inbox 整合 - 自動傳送至專案收件匣
快速開始
cd .pi/skills/batch-report
# 為擷取器批次生成報告（自動偵測格式）
uv run python report.py analyze /path/to/batch/output
# 生成報告並傳送至 agent-inbox
uv run python report.py analyze /path/to/batch/output --send-to extractor
# 僅顯示摘要統計
uv run python report.py summary /path/to/batch/output
# 分析獨立狀態檔案
uv run python report.py state /path/to/.batch_state.json
# JSON 輸出以便管線傳遞
uv run python report.py summary /path/to/output --json | jq .success_rate
命令
analyze - 完整分析報告
uv run python report.py analyze /path/to/output \
--output report.md \
--send-to extractor \
--priority high
選項：
| 選項 | 簡寫 | 說明 |
|---|---|---|
--output | -o | 輸出檔案路徑（預設為 stdout） |
--send-to | -s | 將報告傳送至 agent-inbox 專案 |
--priority | -p | agent-inbox 的優先級（low/normal/high/critical） |
--sample | -n | 包含的樣本數（預設：5） |
--format | -f | 批次格式：extractor、youtube、generic、auto（預設：auto） |
--json | -j | 輸出為 JSON，供其他工具串接 |
summary - 快速統計
uv run python report.py summary /path/to/output
uv run python report.py summary /path/to/output --json
輸出：
批次：run-2025-12-18_144426-2eb428c
總計：230 | 成功：180 | 失敗：35 | 部分完成：15
成功率：78.3%
平均時間：4.2 分鐘 | 最慢：09_section_summarizer（45%）
JSON 輸出：
{
"batch": "run-2025-12-18_144426-2eb428c",
"format": "extractor",
"total": 230,
"successful": 180,
"partial": 15,
"failed": 35,
"success_rate": 78.3,
"avg_time_min": 4.2
}
state - 分析獨立狀態檔案
uv run python report.py state /path/to/.batch_state.json
uv run python report.py state /path/to/.batch_state.json --json
可與任何批次作業的 .batch_state.json 檔案搭配使用。
failures - 列出失敗項目及其原因
uv run python report.py failures /path/to/output
uv run python report.py failures /path/to/output --json
報告格式
# 批次報告：run-2025-12-18_144426-2eb428c
## 摘要
- **總項目數：** 230
- **成功：** 180（78.3%）
- **失敗：** 35（15.2%）
- **部分完成：** 15（6.5%）
## 時間分析
| 步驟 | 平均值（秒） | 最大值（秒） | 佔總計百分比 |
|------|---------|---------|------------|
| 09_section_summarizer | 120.5 | 341.0 | 45.2% |
| 05_table_extractor | 65.3 | 105.0 | 24.5% |
...
## 失敗模式
| 模式 | 數量 | 範例 |
|---------|-------|---------|
| 空的 text_content | 12 | 047ca6ef... |
| CUDA OOM | 5 | 9497a4e5... |
...
## 建議
1. 考慮對知識萃取使用 --text-only 模式
2. 在 VLM 前新增表格信心閾值
...
視覺化
生成報告後（特別是搭配 --json），可提議透過 /create-figure 進行視覺化：
# 按管線步驟顯示時間瀑布圖
create-figure metrics --input batch.json --output timing.png --type hbar --title "步驟時間"
# 成功/失敗分佈
create-figure metrics --input batch.json --output results.png --type pie --title "批次結果"
# 失敗模式細項
create-figure metrics --input batch.json --output failures.png --type bar --title "失敗模式"
何時提出： 在呈現批次分析後，詢問：「要我將時間分佈視覺化嗎？」
支援的批次格式
--format 旗標接受：extractor、youtube、generic 或 auto（預設）。
自動偵測邏輯：
- 如果
*/manifest.json和*/timings_summary.json存在 →extractor - 如果
.batch_state.json的 description 中包含「transcript」→youtube - 如果
.batch_state.json存在 →generic
Extractor 批次
預期包含：
*/manifest.json- 每個項目的清單*/timings_summary.json- 時間資料*/14_report_generator/json_output/final_report.json- 品質指標failed_urls.txt- 失敗項目清單
YouTube 逐字稿批次
預期包含：
.batch_state.json- 含有 transcript 相關 description 的狀態檔案
Generic 批次
預期包含：
.batch_state.json- 含有完成/失敗計數的狀態檔案*.log檔案（選擇性）用於失敗分析
與 agent-inbox 整合
# 將報告以 bug 形式傳送
uv run python report.py analyze /path/to/output \
--send-to extractor \
--priority high
# 已傳送訊息：extractor_abc123
相依性
dependencies = [
"typer",
"rich",
]