ril-log-parser

C++17 command-line tool that parses Android RIL logcat into structured JSON reports,
designed to bridge MODEM domain knowledge with AI-assisted analysis via MCP Server.

Tech Stack：C++17 CMake std::regex JSON MCP pipeline

---

這個專案解決什麼問題？

MODEM 工程師每天面對大量的 RIL logcat，手動從 log 裡找出錯誤、AT Command 狀態、SIM 初始化流程、網路註冊結果，非常耗時。

這個工具把原始 log 自動解析成結構化 JSON，讓工程師一秒掌握關鍵狀態，並可直接銜接 MCP Server，讓 Claude Desktop 以自然語言回答「這台手機的網路有正常連上嗎？」這類問題。

---

Demo 輸出

./ril_parser samples/sample.log

{
  "summary": {
    "total_lines": 14,
    "error_count": 1,
    "sim_ready": true,
    "registration_success": true
  },
  "errors": [
    {
      "tag": "RILJ",
      "message": "RIL_REQUEST_GET_CURRENT_CALLS error 1"
    }
  ],
  "at_commands": [
    {
      "command": "AT+CSQ",
      "response": "+CSQ: 23,0",
      "status": "OK",
      "interpreted": "Signal: -67 dBm"
    },
    {
      "command": "AT+COPS?",
      "response": "+COPS: 0,0,\"Chunghwa\",7",
      "status": "OK",
      "interpreted": "Operator: Chunghwa, RAT: LTE"
    },
    {
      "command": "AT+CIMI",
      "response": "466920123456789",
      "status": "OK",
      "interpreted": "IMSI: 466920123456789"
    }
  ],
  "registration_flow": [
    { "state": "SEARCHING",          "rat": "Unknown" },
    { "state": "REGISTERED_ROAMING", "rat": "LTE" }
  ],
  "sim_flow": [
    { "state": "UNKNOWN" },
    { "state": "READY" }
  ]
}

---

功能

功能	CLI 參數	說明
整合報告	（不帶參數）	輸出完整 JSON，供 MCP Server 讀入
錯誤偵測	--errors	擷取 priority E/W 或含 error / fail / timeout 的行
AT Command	--at-commands	配對 command + response + status，並解譯為人讀格式
網路註冊	--registration	還原 regState 流程，判斷是否成功連網
SIM 狀態	--sim	追蹤 SIM_STATE_CHANGED 流程，判斷是否就緒
寫出檔案	-o <file>	輸出寫入 JSON 檔，供下游工具讀取

---

Build

需求：g++ / clang++（C++17）、CMake 3.10+

git clone https://github.com/linyuhang617/ril-log-parser.git
cd ril-log-parser
mkdir build && cd build
cmake ..
make

---

測試

cd build
./test_line_parser    # 單行解析
./test_errors         # 錯誤事件偵測
./test_at             # AT Command 配對與解譯
./test_registration   # 網路註冊流程
./test_sim            # SIM 狀態追蹤

全部輸出 All tests passed!

---

專案架構

include/parser/
  LogEntry.h        ← 共用資料結構（LogEntry / AtCommand / RegEvent / SimEvent）
  LineParser.h      ← logcat 單行解析
  EventClassifier.h ← 錯誤偵測、AT Command 配對、註冊與 SIM 流程擷取
  AtInterpreter.h   ← AT Command response 解譯（CSQ / COPS / CIMI）
  JsonExporter.h    ← JSON 輸出（各 section 及整合報告）
src/                ← 對應實作
tests/              ← 各模組單元測試
samples/            ← 測試用 RIL log

---

設計決策

為什麼 regState 轉成文字？
3GPP 數值（0–5）對人不直覺。轉成 SEARCHING、REGISTERED 等文字後，MCP Server 傳給 Claude 時不需要額外對照表，Claude 可直接用自然語言回答。

為什麼零第三方依賴？
JSON 手刻字串拼接、測試用 assert()，專案只需要 STL，任何 C++17 環境都能直接 build。

---

銜接 MCP Server

# 產生報告
./ril_parser samples/sample.log -o report.json

# ril-mcp-server 讀入此檔案，讓 Claude Desktop 可以查詢 MODEM 狀態
# 詳見 ril-mcp-server（開發中）