dsh-loghud

简体中文 | English

dsh-loghud 是面向 DeepSeek Harness 0.1.0-rc.8 的 Web 插件，用于监控本地 Java 和 Spring 应用错误。它会把 Java 运行时异常、Spring 启动及依赖注入错误、MyBatis、数据库、Redis 和 HTTP/MVC 错误整理成有界、去重的错误卡片。

AI 解释完全由用户手动触发。检测到错误时，插件不会自动调用模型。

当前 V0.1 主要面向 Java/Spring 生态。通用回退规则能够保留尚未分类的 Java 异常链，但暂不承诺支持 Python、Node.js、Go、原生程序崩溃或任意文本日志。

界面预览

DeepSeek Harness 目前仍处于 developer preview。该插件将所有 @deepseek-ai/* 依赖锁定在同一 RC 版本，并且只使用公开的 Cordis 服务、Tool 事件、Terminal、LLM Streaming、Web 路由和 Client Slot。

功能

• 识别 Spring IOC、MyBatis、MySQL/数据库、Redis、Spring MVC、Java 运行时和应用启动错误。
• 提取根异常、核心消息、文件、行号、方法、目标对象和端口等信息。
• 使用稳定指纹合并重复错误，并记录出现次数和最近发生时间。
• 按 Session 隔离活动错误、已解决历史和项目健康状态。
• 通过 SSE 向浏览器推送合并后的状态更新。
• 支持中英文界面、明暗主题、键盘操作和可拖动悬浮面板。
• AI 诊断按需调用，并在发送前遮盖常见密钥和凭据。

日志采集模式

• 普通 Harness Shell（tool-result）：tools/result 是只读的最终结果，因此命令结束后才会更新 HUD。
• Harness 后台任务：关联 pwsh 或 Shell 返回的任务句柄及最终 job_output；中间轮询和无关 PowerShell 命令不会改变项目健康状态。
• 增量模式（streaming-tool）：让 Agent 使用 loghud_run，或直接调用该工具。命令通过官方 Terminal 服务运行，增量输出会持续送入采集器。

插件不会替换或修改 Harness 原生 Shell。界面会明确显示当前采集方式。

安装

从源码构建

需要 Node.js 22.19 或更高版本以及 pnpm。

pnpm install
pnpm check
pnpm pack
dsh plugin --profile web add ./dsh-loghud-0.1.0.tgz
dsh --profile web --dump-config

从 npm 安装

发布到 npm 后可以使用：

dsh plugin --profile web add dsh-loghud@0.1.0

配置输出中应当包含已启用的 dsh-loghud patch。随后正常启动 Harness 并打开 Coding Session。

LogHUD 徽标和面板标题均可拖动，浏览器会记住其位置。也可以使用 Alt 加方向键移动面板，或在设置中恢复默认位置。界面及按需 AI 解释会跟随浏览器语言；中文环境会要求模型使用简体中文，同时保留代码标识符原文。

配置

enabled: true
enableAiAnalysis: true       # 仅允许手动触发，不会自动调用
maxErrorContextLines: 120
maxResolvedHistory: 50
secretRedaction: true
beginnerFriendly: true

缺少 Terminal 服务时，只会禁用 loghud_run，命令结束后的结果检测仍可使用。缺少 LLM 路由时，只会禁用 AI 诊断，本地错误卡片不会受到影响。没有兼容的 storageDomain 时，状态会保存在进程内存中，并保持有界。

错误识别与健康状态

解析器链覆盖 Spring IOC、MyBatis、MySQL/数据库、Redis、Spring MVC、Java 运行时异常、应用启动失败和通用 Java 异常回退。它会将包装异常链归并到有效根因，对动态噪声进行规范化，生成稳定的 SHA-256 指纹，并累计重复出现次数。

健康状态定义如下：

• UNKNOWN：尚未观察到受支持的命令。
• HEALTHY：已成功观察命令，且当前没有活动错误。
• BROKEN：当前存在活动错误卡片。

自动恢复范围刻意保持严格：只有同一命令族再次出现 Spring 启动成功标记，且没有错误退出时，才会解决此前相关的启动错误。其他错误不会猜测因果关系。

AI 诊断与隐私

AI 诊断按钮点击前不会调用模型。一次用户操作最多发起一次诊断请求，同一错误版本的并发请求会被合并。

发送给模型的内容仅包含结构化错误摘要、异常链、有限上下文和命令类型。启用敏感信息遮盖后，Bearer Token、JWT、密码、API Key、URL 凭据、私钥和常见 Secret 环境变量会在发送前被替换。AI 超时、取消或返回错误不会删除本地错误记录。

HTTP 与 SSE 接口

所有 Session ID 和错误指纹都会在路由入口进行校验。

• GET /api/loghud/:sessionId/snapshot
• GET /api/loghud/:sessionId/events (SSE)
• POST /api/loghud/:sessionId/diagnose
• POST /api/loghud/:sessionId/resolve
• POST /api/loghud/:sessionId/clear-resolved
• POST /api/loghud/:sessionId/clear

更多信息请参阅架构说明、技术可行性、限制说明、验证记录和示例工程。

开发与验证

pnpm typecheck
pnpm test
pnpm build
pnpm pack:check

许可证

本项目使用 MIT License。