dsh-logtimeline

<strong>🐳 dsh-logtimeline</strong> <em>Query local log files with Chinese natural-language time expressions — LogTimeline for DeepSeek Harness.</em>

<a href="README.zh.md"><strong>简体中文</strong></a> | <a href="README.md">English</a>

---

Ask 「昨天下午」「3小时前」「凌晨12点」「上周三 14:00-15:00」 — get the matching log lines, the resolved time range, and ERROR/WARN/INFO level stats. Fully offline. Logs never leave the machine.

Why

Coding agents constantly need to answer "what happened around 3pm yesterday?". Generic log tools make you hand-write grep pipelines and timestamp math. log_query resolves the fuzzy Chinese time expression for you and returns structured, machine-readable matches the agent can reason over directly — no parsing prose out of terminal output.

Features

🕐 Chinese time parsing	Absolute dates (2026-07-03, 7月3日 09:15), relative (3小时前, 昨天, 上周三), fuzzy windows (下午, 凌晨), hour ranges (14:00-15:00) — each with a confidence score
📄 Multi-format logs	Auto-detected timestamp formats, UTF-8/GBK encoding fallback, streaming filter (no full-file load, ~2.4s per 300k lines)
🔒 Offline by default	Zero third-party Python dependencies; log contents never leave the machine
🧩 Structured output	Canonical JSON (time_range, filter, lines, stats) rendered as readable text for the model, spill-safe under the harness's 50KB inline budget

Install

Prerequisites: a dsh profile (web or headless) + Python 3.9+ on the machine (on Windows, the py launcher is auto-detected when python is missing).

Local / development (from a checkout):

git clone https://github.com/anyuer678/dsh-logtimeline.git
dsh plugin --profile web add file:/path/to/dsh-logtimeline

Community install — once listed in awesome-dsh-plugin, install via the plugin market (GitHub-only plugins are supported):

dsh plugin --profile web add dshmarket
# then: Settings → Plugin Market → search "dsh-logtimeline" → one-click install

Compatibility: tested against @deepseek-ai/[email protected] (current harness release line, e.g. [email protected]).

Usage

Tell the agent to use the tool — no special syntax needed:

用 log_query 查一下 demo.log 里 2026-07-03 的 ERROR 情况

// log_query(time_text: "2026-07-03", files: ["demo.log"])
{
  "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} */ ]
  }
}

Parameters

Parameter	Type	Description
time_text	string (required)	Chinese natural-language time, e.g. 「昨天下午」「3小时前」
files	string[]	Log file paths (absolute or workspace-relative)
dir	string	Directory to scan recursively
pattern	string	Glob when dir is set (default *.log)
max_lines	number	Max lines returned (default 500; 0 = stats only; capped at 5000)
since	string	RFC3339 absolute-time fallback when time_text fails to parse
timezone	string	IANA timezone name, e.g. Asia/Shanghai

The tool runs in offline mode by default: it filters precisely (its unique value), and leaves root-cause reasoning to the agent itself.

Architecture

…