Reseezhang/ue-log-reader

ue-log-reader

version
license
ds desktop
tests

DeepSeek Harness 插件：UE（Unreal Engine）日志速读卡。用户在对话中说「分析一下日志」「刚闪退了看看日志」，模型自动调用 uelog 工具扫描 UE 项目 Saved/Logs/ 下的日志（支持标准 UE 日志与 Android 真机 adb logcat 格式），流式解析 + 聚合去重后渲染成一张速读卡片，并提供一键复制的缺陷单摘要。

架构沿用 vizcb-codeblock-visualizer 已跑通的「Host 路由 + Client 工具调用节点卡片（tool.call.toolview keyed uelog）+ 提示词 section」三件套。

功能

- uelog 模型工具：扫描日志（显式文件或缺省最新），流式逐行解析（数百 MB 不爆内存，默认只解析尾部 200MB），按「类别 + 归一化消息」聚合去重（同一报错刷 N 遍 = 1 条 × N），提取崩溃原因 + 前 10 帧堆栈 + 引擎版本；返回 JSON 摘要给模型做文字回答
- 速读卡（tool.call.toolview keyed uelog，渲染在 uelog 工具调用节点上）：文件头（名称/体积/时间跨度/版本）+ 统计色块（Fatal/Error/Ensure/Warn，点击筛选）+ Top 问题列表（悬停显示首条原文）+ 可折叠崩溃详情（等宽字体）
- 动作按钮：复制缺陷摘要（生成纯文本缺陷单：版本/时间/崩溃/堆栈前 5 帧/高频问题）、打开日志目录（系统文件管理器定位）
- 失败可见化：未找到日志 / 路径越界 / 解析失败等一律显示明确原因，绝不静默空白
- 安全：显式路径必须落在 projectRoot/logRoots 内（resolve + 包含性校验，含 URL 编码变体）；只读操作，不写不改日志目录；扫描限流 + 串行化 + 同路径在途去重；结果按「路径+mtime+size+maxBytes」缓存

前置条件

- DeepSeek Harness 桌面版 2.x（web profile 亦可），profile 的 dsh.profile.bundles 已含 @deepseek-ai/dsh-base 与 @deepseek-ai/dsh-web-app（默认即有）
- 一个可写的 UE 项目根目录（含 Saved/Logs/）
- 自测（可选）需要 Node.js 24+

安装

方式 A —— 一键安装脚本（推荐）

1. 获取源码（git clone / 下载 zip）
2. 在仓库根目录运行（复制插件 + 写入 bundles）：
powershell -ExecutionPolicy Bypass -File install-uelog.ps1
其他 profile：
powershell -ExecutionPolicy Bypass -File install-uelog.ps1 -ProfileName web
3. 重启 DeepSeek Harness

方式 B —— 手动复制

1. 把 ue-log-reader 目录复制到目标 profile 的 node_modules/
2. 在 profile 的 package.json 的 dsh.profile.bundles 追加 "ue-log-reader"
3. 重启

方式 C —— 作为 npm/git 依赖安装

在目标 profile 的 package.json 中加入依赖并注册 bundle（随后 pnpm install）：

{
"dependencies": {
"ue-log-reader": "github:Reseezhang/ue-log-reader"
},
"dsh": {
"profile": {
"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "ue-log-reader"]
}
}
}

本插件零运行时依赖：解析用 Node 内置模块，@deepseek-ai/dsh-tools 由宿主 profile 提供，无需 npm install。

配置

默认值见 lib/index.js 的 DEFAULTS。在 profile 级 cordis.patch.yml 按 id 覆盖：

- id: ue-log-reader
config:
projectRoot: "D:/Projects/MyGame"   # UE 项目根目录（必配；缺省退回工作区根）
logRoots: []                        # 额外允许的日志根目录（如 adb pull 拉取的真机日志目录）
maxBytes: 209715200                 # 单文件扫描上限（默认 200MB，超过只解析尾部）
maxTopIssues: 15                    # Top 问题列表上限
scanRateMax: 6                      # 扫描全局限流（10s 窗口内最大次数）

使用

1. 重启 DeepSeek Harness
2. 在对话里说「分析一下日志」或「刚闪退了，看看日志」
3. 模型调用 uelog 工具（未指定文件时扫 /Saved/Logs/ 最新日志；只有 -backup- 历史日志时自动选最新历史日志并标注「历史日志」）
4. 速读卡出现在 uelog 工具调用节点上：统计色块点击筛选、崩溃详情可展开、复制缺陷摘要 一键生成缺陷单文本、打开日志目录 定位文件
5. 文字回复里模型只给结论与建议（最可能的根因、建议提交人），不贴长堆栈；要写缺陷单时点卡片上的「复制缺陷摘要」按钮

真机日志（Android adb logcat）

插件自动识别 logcat 格式（threadtime/time/brief/raw 变体，含 ANSI 颜色码），UE 日志行（LogNet: Warning: ...）按 UE 级别解析，非 UE 行按 logcat 优先级分级（F→Fatal / E→Error / W→Warning），并支持 Fatal signal 崩溃块（#00 pc 0x... 堆栈帧，取前 10 帧）。

1. 抓取真机日志到文件（任选其一）：
adb logcat -d > device.log      # 导出当前缓冲区后退出（推荐）
adb logcat > device.log         # 实时重定向，Ctrl+C 停止

2. 把文件放到 /Saved/Logs/ 下，或配置 logRoots 指向的目录，文件名以 .log 结尾
3. 对话里说「分析一下日志」→ 自动扫最新日志（卡片头会标注 logcat 徽标表示真机格式）
4. 也可直接说「分析一下 D:/任意位置/device.log」传显式绝对路径——默认要求位于 projectRoot/logRoots 内；真机 log 常在 Saved/Logs 之外，开启 allowAnyPath: true 后任意位置的绝对路径均可（相对路径仍受包含性约束，防 ../ 穿越）

提示：真机 release 包崩溃堆栈是内存地址（libUE4.so + 0x...），符号化（转成函数名）需要匹配构建的 .so/dSYM 符号表，属二期能力，当前显示地址帧。

仓库自带 samples/device-sample.logcat.log 样例（含 UE 行嵌入/聚合去重/Fatal signal 崩溃），可复制到 Saved/Logs 快速验证 logcat 路径。

路由

| 路由 | 说明 |
|---|---|
| POST /uelog/scan | { file?, maxBytes? } → 摘要 JSON（缓存/限流/在途去重） |
| POST /uelog/reveal | { path } → 系统文件管理器定位 |
| GET /uelog/debug | 自检状态 |

自测

node --test

node --test 全量用例（解析 + 宿主编排）；解析用例零依赖可直接跑，集成用例在插件未安装时自动跳过。

卸载

删掉 profile package.json bundles 里的 ue-log-reader 条目 + 删除插件目录 + 重启。

相关项目

- vizcb-codeblock-visualizer —— 把模型输出的 svg/html/mermaid 渲染为图表卡片 + present-files 文件预览（本插件的架构母版）