ue-log-reader

Readme

# ue-log-reader

![version](https://img.shields.io/badge/version-0.3.4-4F8CFF)
![license](https://img.shields.io/badge/license-MIT-34D399)
![ds desktop](https://img.shields.io/badge/DSH%20Desktop%202.0.4%20verified-F59E0B)
![tests](https://img.shields.io/badge/tests-36%20passing-34D399)

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

架构沿用 [vizcb-codeblock-visualizer](https://github.com/Reseezhang/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 —— 一键安装脚本（推荐）

```sh
# 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`）：

```jsonc
{
  "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 覆盖：

```yaml
- 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` 工具（未指定文件时扫 `<projectRoot>/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. 抓取真机日志到文件（任选其一）：
   ```sh
   adb logcat -d > device.log      # 导出当前缓冲区后退出（推荐）
   adb logcat > device.log         # 实时重定向，Ctrl+C 停止
   ```
2. 把文件放到 `<projectRoot>/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` | 自检状态 |

## 自测

```sh
node --test
```

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

## 卸载

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

## 相关项目

- [vizcb-codeblock-visualizer](https://github.com/Reseezhang/vizcb-codeblock-visualizer) —— 把模型输出的 svg/html/mermaid 渲染为图表卡片 + present-files 文件预览（本插件的架构母版）