Analytics 技能
適用於任何數據集的靈活數據科學分析。自動探索結構、推薦視覺化圖表，並以 create-figure 格式匯出。
快速開始（任何數據集）
cd .pi/skills/analytics
./run.sh describe data.jsonl
./run.sh chart data.jsonl --name distribution_channel -o chart.json
cd .agent/skills/create-figure
./run.sh metrics -i /path/to/chart.json --type bar -o chart.pdf
無縫流程
任何數據 (JSONL/JSON/CSV)
│
▼
┌─────────────────────────────────┐
│ analytics describe │ ← 探索結構，推薦圖表
│ "偵測到 5 個類別、2 個數值、 │
│ 1 個時間欄位" │
│ 推薦圖表： │
│ - distribution_channel (bar) │
│ - trend_by_date (line) │
│ - heatmap_hour_x_day │
└─────────────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ analytics chart/group-by │ ← 以 create-figure 格式生成圖表數據
│ --name distribution_channel │
│ -o chart.json │
└─────────────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ create-figure metrics │ ← 渲染可出版品質的 PDF/PNG
│ -i chart.json --type bar │
│ -o channel_distribution.pdf │
└─────────────────────────────────┘
指令
探索（從這裡開始）
| 指令 | 說明 |
|---|
describe <file> | 探索結構，偵測欄位類型，推薦圖表 |
./run.sh describe sales.jsonl
靈活分析
| 指令 | 說明 |
|---|
group-by <file> | 依任何欄位進行分組並聚合 |
stats <file> | 數值統計與相關性分析 |
chart <file> | 生成供 create-figure 使用的圖表規格 |
./run.sh group-by data.jsonl --by channel --for-figure -o by_channel.json
./run.sh group-by data.jsonl --by category --agg price --func sum
./run.sh stats data.jsonl --columns revenue,cost,profit
./run.sh chart data.jsonl --name distribution_channel -o chart.json
含時間戳記的數據（ingest-* 輸出）
| 指令 | 說明 |
|---|
insights <file> | 完整分析摘要（趨勢、工作階段、模式） |
trends <file> | 含移動平均的觀看趨勢 |
sessions <file> | 工作階段偵測與狂看分析 |
time-patterns <file> | 小時/天數分佈 |
evolution <file> | 偏好隨時間的變化 |
輸出
| 指令 | 說明 |
|---|
export <file> | 批次匯出所有標準圖表 |
report <file> | Horus 風格敘事報告 |
支援的格式
| 格式 | 副檔名 | 自動偵測 |
|---|
| JSONL | .jsonl | 行分隔 JSON |
| JSON | .json | 陣列或 {data: [...]} |
| CSV | .csv | 逗號分隔 |
欄位類型偵測
describe 指令會自動偵測：
| 類型 | 偵測邏輯 | 推薦圖表 |
|---|
| 時間 | datetime64、類似日期的字串 | 折線圖、面積圖、熱力圖（時間軸） |
| 數值 | int64、float64 | 直方圖、散佈圖、統計圖 |
| 類別 | 低基數（≤20 個唯一值） | 長條圖、圓餅圖、熱力圖 |
| 布林值 | bool dtype | 圓餅圖（真/假） |
| 文字 | 高基數字串 | 文字雲、前 N 名 |
圖表推薦
根據欄位類型，analytics 會推薦：
| 數據模式 | 圖表類型 | create-figure 指令 |
|---|
| 1 個類別 | 長條圖、圓餅圖 | metrics --type bar |
| 1 個時間 | 折線圖 | training-curves |
| 2 個類別 | 熱力圖 | heatmap |
| 時間 + 類別 | 熱力圖 | heatmap |
| 2+ 個數值 | 相關矩陣 | heatmap |
| 1 個數值 | 直方圖 | metrics --type bar |
代理工作流程
專案代理可依下列方式分析任何資料集並進行視覺化：
result = run("./run.sh describe data.jsonl --json")
recommendations = result["recommendations"]
chart_name = recommendations[0]["name"]
cmd = recommendations[0]["create_figure_cmd"]
run(f"./run.sh chart data.jsonl --name {chart_name} -o chart.json")
run(f"cd .agent/skills/create-figure && ./run.sh {cmd} -i chart.json -o chart.pdf")
範例
電子商務銷售數據
./run.sh describe orders.jsonl
./run.sh group-by orders.jsonl --by category --agg amount --func sum --for-figure -o revenue_by_category.json
cd .agent/skills/create-figure
./run.sh metrics -i revenue_by_category.json --type bar -o revenue.pdf
YouTube 歷史記錄（ingest-yt-history）
./run.sh insights ~/.pi/ingest-yt-history/history.jsonl
./run.sh export ~/.pi/ingest-yt-history/history.jsonl -o ./charts --for-figure
cd .agent/skills/create-figure
./run.sh heatmap -i charts/heatmap.json -o viewing_heatmap.pdf
API 回應數據
./run.sh describe api_logs.json
./run.sh stats api_logs.json --columns response_time
./run.sh group-by api_logs.json --by endpoint --agg response_time --func mean --for-figure -o latency.json
相依性
dependencies = [
"pandas>=2.0.0",
"typer>=0.9.0",
"rich>=13.0.0",
]
整合 Horus
./run.sh insights ~/.pi/ingest-yt-history/history.jsonl --horus
常見錯誤
./run.sh stats data.jsonl --columns revenue,cost
./run.sh describe data.jsonl
./run.sh group-by data.jsonl --by date --agg views | ./run.sh metrics --type pie