Introduction¶

During development and debugging with DeepSeek Harness (DSH) agents, they often need to answer questions such as “What happened yesterday afternoon?” General-purpose log tools usually require manually writing grep pipelines and complex date calculation logic.

The dsh-logtimeline plugin solves this problem. It uses locally running Python scripts to parse Chinese natural-language time expressions (such as “3小时前” and “上周三”) and returns matching log results as structured JSON, enabling direct agent reasoning.

Plugin Overview¶

dsh-logtimeline is an adapter plugin for the LogTimeline project within the DeepSeek Harness ecosystem. By invoking the built-in Python CLI, it enables fully local log filtering and statistics.

Core Features¶

Chinese time parsing
Supports absolute dates (2026-07-03), relative time (3小时前), fuzzy windows (下午), and time spans (14:00-15:00), and returns a parsing confidence score.
Multi-format log support
Automatically detects timestamp formats, supports UTF-8 and GBK encoding fallback, and uses a streaming filtering mechanism to avoid loading entire files.
Offline by default
The plugin has no third-party Python dependencies. Log content is parsed locally only and is neither uploaded nor leaked.
Structured output
Returns standard JSON format containing time_range (time range), filter (filter statistics), and lines (matched log lines), fitting DSH’s 50KB line budget.

Installation and Enabling¶

Prerequisites:
* DeepSeek Harness is installed, and a web or headless profile is configured.
* Python 3.9+ is installed in the system environment (on Windows, if the python command is not configured, the py launcher is used automatically).
* The required DSH tools version is @deepseek-ai/dsh-tools@0.1.0-rc.6.

Installation command:

dsh plugin --profile web add file:/path/to/dsh-logtimeline

Typical Usage¶

In a DSH session, simply instruct the agent to use the log_query tool. No special syntax is required.

Example instruction:
Use log_query to check the ERROR entries in demo.log for 2026-07-03.

Example response:

{
  "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} */
    ]
  }
}

Parameter description:
* time_text (string, required): A Chinese natural-language time expression, such as “昨天下午”.
* files (string[]): Log file paths (absolute paths or workspace-relative paths).
* dir (string): Directory to scan recursively.
* pattern (string): Glob pattern to use when the dir parameter is set (default *.log).
* max_lines (number): Maximum number of lines to return (default 500, capped at 5000; set to 0 to return statistics only).
* since (string): RFC3339 absolute time fallback when parsing time_text fails.
* timezone (string): IANA timezone name, such as Asia/Shanghai.

Use Cases and Considerations¶

Use cases:
* Quick log troubleshooting in local development environments.
* Scenarios that require structured data for further processing by agents.

Considerations:
1. Use with caution in production: The plugin states that it has not undergone production-grade hardening and is not suitable for mission-critical business environments.
2. Security features:
* The plugin does not handle API keys and makes no external network requests.
* It reads only the files or dir paths specified by the agent. Operations are read-only and do not modify files.
* It automatically removes control characters and ANSI escape sequences from log lines.
3. License: Uses the GPL-3.0 license.

Summary¶

dsh-logtimeline provides DSH with local Chinese log query capabilities. Through natural-language interaction and structured output, it lowers the barrier for agents to process logs.

For more details and source code, visit the project homepage:
https://github.com/anyuer678/dsh-logtimeline

dsh-logtimeline: Local Log Query Plugin