cli-anything-nslogger 是做什麼的？
一個完整的命令列工具（CLI harness），用於 NSLogger — macOS 上 iOS/macOS 應用程式的日誌檢視器。
安裝
cd nslogger/agent-harness
pip install -e .
# 驗證
cli-anything-nslogger --help
指令參考
generate — 建立用於測試的範例檔案
cli-anything-nslogger generate sample.rawnsloggerdata --count 50
read — 顯示檔案中的訊息
# 所有訊息
cli-anything-nslogger read session.rawnsloggerdata
# 僅錯誤（層級 0）
cli-anything-nslogger read session.rawnsloggerdata --level 0
# 依標籤與文字搜尋過濾
cli-anything-nslogger read session.rawnsloggerdata --tag Network --search "timeout"
# 前 20 則訊息，輸出為 JSON
cli-anything-nslogger read session.rawnsloggerdata --limit 20 --json
filter — 進階過濾
# 僅錯誤與警告
cli-anything-nslogger filter session.rawnsloggerdata --level 1
# 依標籤
cli-anything-nslogger filter session.rawnsloggerdata --tag Auth --tag Network
# 正規表示式搜尋
cli-anything-nslogger filter session.rawnsloggerdata --regex "(timeout|failed|error)"
# 依執行緒
cli-anything-nslogger filter session.rawnsloggerdata --thread "main"
# JSON 輸出
cli-anything-nslogger filter session.rawnsloggerdata --level 0 --json
export — 匯出為文字/JSON/CSV
# JSON 輸出到標準輸出
cli-anything-nslogger export session.rawnsloggerdata --format json
# CSV 輸出到檔案
cli-anything-nslogger export session.rawnsloggerdata --format csv --output logs.csv
# 過濾後文字匯出
cli-anything-nslogger export session.rawnsloggerdata --format text --level 1 --tag Network
stats — 摘要統計
# 人類可讀的摘要
cli-anything-nslogger stats session.rawnsloggerdata
# 供代理使用的 JSON 格式
cli-anything-nslogger stats session.rawnsloggerdata --json
JSON 輸出形狀：
{
"total": 342,
"by_level": {"ERROR": 12, "WARNING": 34, "INFO": 200, "DEBUG": 96},
"by_tag": {"Network": 89, "Auth": 45, "UI": 120},
"by_thread": {"main": 200, "bg-queue": 142},
"by_type": {"text": 340, "client_info": 1, "disconnect": 1},
"clients": ["MyApp"],
"first_timestamp": "2024-01-01T10:00:00+00:00",
"last_timestamp": "2024-01-01T10:05:30+00:00",
"duration_seconds": 330.0
}
listen — 接收即時連線
# 比對 NSLogger.app GUI Bonjour 行為，用於 iOS 自動發現
cli-anything-nslogger listen --bonjour --name bazinga --debug
# 將即時日誌鏡像到文字檔案，同時仍列印到標準輸出
cli-anything-nslogger listen --bonjour --name bazinga --output app.log
# 寫入機器可讀的 JSON Lines
cli-anything-nslogger listen --bonjour --name bazinga --output app.jsonl --output-format jsonl
# 直接 TCP/TLS 模式，用於手動設定的客戶端
cli-anything-nslogger listen --port 50000 --ssl --debug
# 監聽時僅顯示錯誤，輸出為 JSON 串流
cli-anything-nslogger listen --bonjour --name bazinga --level 0 --json
# 持續執行直到按下 Ctrl-C
cli-anything-nslogger listen --bonjour --name bazinga
對於 iOS 應用，請優先使用 Bonjour 模式，因為它與桌面 NSLogger GUI 的行為一致：
CLI 會發布一個原生的 macOS NetService，使用 _nslogger-ssl._tcp 協定，
並接受 TLS NSLogger 幀。只有在應用程式已手動設定 Mac 主機與連接埠時，才使用直接 TCP/TLS 模式。
repl — 互動式指令 REPL
cli-anything-nslogger repl session.rawnsloggerdata
# 或者直接執行 cli-anything-nslogger（不帶子指令）即可啟動。
日誌層級
| 值 | 名稱 | 用途 |
|---|---|---|
| 0 | ERROR | 無法復原的失敗 |
| 1 | WARNING | 可復原的問題 |
| 2 | INFO | 正常運作 |
| 3 | DEBUG | 開發人員細節 |
| 4 | VERBOSE | 追蹤等級的雜訊 |
訊息 JSON 形狀
{
"sequence": 42,
"timestamp": "2024-01-01T10:01:23+00:00",
"timestamp_ms": 456,
"thread_id": "main",
"tag": "Network",
"level": 0,
"level_name": "ERROR",
"type": "text",
"text": "Connection timed out after 30s",
"image_width": 0,
"image_height": 0,
"client_name": "MyApp",
"client_version": "2.1.0",
"os_name": "iOS",
"os_version": "17.0",
"machine": "iPhone15,2"
}
代理工作流程範例
# 1. 檢查捕獲的崩潰工作階段
cli-anything-nslogger stats crash.rawnsloggerdata --json
# 2. 找出崩潰前 5 分鐘內的所有錯誤
cli-anything-nslogger filter crash.rawnsloggerdata --level 0 --json
# 3. 僅取得網路失敗
cli-anything-nslogger filter crash.rawnsloggerdata --tag Network --regex "fail|timeout|error" --json
# 4. 匯出完整日誌供離線分析
cli-anything-nslogger export crash.rawnsloggerdata --format json --output crash_log.json
# 5. 即時監控 iOS 應用並保留本機副本
cli-anything-nslogger listen --bonjour --name bazinga --output app.log --debug