前言¶
DeepSeek Harness (DSH) 智能體在開發調試時，常需要回答“昨天下午發生了什麼”這類問題。通用的日誌工具通常需要手動編寫 grep 管道和複雜的日期計算邏輯。
dsh-logtimeline 插件解決了這個問題。它利用本地運行的 Python 腳本，解析中文自然語言時間表達式（如“3小時前”、“上週三”），並將日誌匹配結果以結構化 JSON 返回，方便智能體直接進行推理。
插件簡介¶
dsh-logtimeline 是 LogTimeline 項目在 DeepSeek Harness 生態中的適配插件。插件通過調用內置的 Python CLI，實現完全本地化的日誌過濾與統計。
核心功能¶
-
中文時間解析
支持絕對日期（2026-07-03）、相對時間（3小時前）、模糊窗口（下午）以及時間段（14:00-15:00），並返回解析置信度。 -
多格式日誌支持
自動檢測時間戳格式，支持 UTF-8 和 GBK 編碼回退，採用流式過濾機制，避免全量文件加載。 -
默認離線運行
插件不依賴第三方 Python 庫，日誌內容僅在本地解析，不會上傳或外泄。 -
結構化輸出
返回標準 JSON 格式，包含time_range（時間範圍）、filter（過濾統計）和lines（匹配日誌行），符合 DSH 的 50KB 行內預算。
安裝與啓用¶
前置條件：
* 已安裝 DeepSeek Harness，並配置好 web 或 headless profile。
* 系統環境已安裝 Python 3.9+（Windows 上若未配置 python 命令，會自動使用 py 啓動器）。
* 依賴的 DSH 工具版本爲 @deepseek-ai/dsh-tools@0.1.0-rc.6。
安裝命令：
dsh plugin --profile web add file:/path/to/dsh-logtimeline
典型用法¶
在 DSH 會話中，直接告知智能體使用 log_query 工具即可。無需特殊語法。
示例指令：
用 log_query 查一下 demo.log 裏 2026-07-03 的 ERROR 情況。
返回結果示例：
{
"time_range": {
"start": "2026-07-03 00:00:00",
"end": "2026-07-04 00:00:00",
"confidence": 1.0
},
"filter": {
"total_matched": 25,
"stats": {
"errors": 13,
"warns": 5,
"infos": 7,
"debugs": 0
},
"lines": [
/* up to max_lines rows: {lineno, timestamp, raw} */
]
}
}
參數說明：
* time_text (string, required): 中文自然語言時間，如“昨天下午”。
* files (string[]): 日誌文件路徑（絕對路徑或工作區相對路徑）。
* dir (string): 遞歸掃描的目錄。
* pattern (string): 當 dir 參數設置時使用的 Glob 模式（默認 *.log）。
* max_lines (number): 返回的最大行數（默認 500，上限 5000，設爲 0 僅返回統計）。
* since (string): 當 time_text 解析失敗時的 RFC3339 絕對時間回退。
* timezone (string): IANA 時區名稱，如 Asia/Shanghai。
適用場景與注意事項¶
適用場景：
* 本地開發環境下的日誌快速排查。
* 需要結構化數據以供智能體進一步處理的場景。
注意事項：
1. 生產環境慎用：插件聲明未經過生產級加固，不適用於關鍵業務環境。
2. 安全特性：
* 插件不處理 API Key，無外部網絡請求。
* 僅讀取智能體指定的 files 或 dir 路徑，只讀操作，不修改文件。
* 自動清理日誌行中的控制字符和 ANSI 轉義序列。
3. 許可證：採用 GPL-3.0 許可證。
總結¶
dsh-logtimeline 爲 DSH 提供了本地化的中文日誌查詢能力。通過自然語言交互和結構化輸出，它降低了智能體處理日誌的門檻。
更多細節與源碼，請訪問項目主頁：
https://github.com/anyuer678/dsh-logtimeline
