前言¶
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
