Community Session Doctor plugin for DeepSeek Harness

[wsjwu58-cmd]

非官方项目，由社区独立开发和维护；不属于 DeepSeek 官方仓库或发行版。

项目地址：https://github.com/wsjwu58-cmd/dsh-session-doctor

Session Doctor 是什么

Session Doctor 是面向 DeepSeek Harness 的 Session 诊断集成。它用于解释 Agent 为什么停止、反复失败、持续重试、上下文持续增长，或在进程中断后留下不完整的 JSONL 日志。

它重放已持久化的 Session 事件，生成带版本的结构化诊断报告：报告包含发现类别、影响级别、有限的事件序号证据、指标与建议代码，方便 CLI、Web UI 或自动化工具继续处理。诊断和聚类均为只读，不会修改被检查的 Session。

主要功能

• 确定性诊断：覆盖重复失败的工具调用、未变化的失败循环、密集工具错误、Provider 重试风暴、达到 token 上限的回合、持续的精确上下文增长，以及中断的执行。
• 跨 Session 聚类：按照探测器、问题类别和建议代码聚合重复发现，帮助定位最常出现、最值得优先排查的问题；不会据此推断 Session 间的因果关系。
• 有界 LLM 根因分析（RCA）：Web UI 可在诊断完成后，使用调用方明确选择的模型生成结构化假设。RCA 只使用安全的事件摘要，不会发送原始模型消息、工具参数、调用 id 或 Provider 不透明负载；该操作会消耗模型 token。
• 显式 JSONL 尾部修复：仅在使用 --repair 时修复最后一条被撕裂的 JSONL 记录，保留有效的逻辑事件前缀；不会覆盖已经提交但内容损坏的记录。

截图

上图展示了 Session 诊断页：发现项会标出影响级别、类别、证据事件序号、可比较的标量指标与建议代码。

与 DeepSeek Harness 的集成方式

模块	作用
packages/runtime-diagnostics/session-doctor	诊断引擎、报告类型、内置探测器、RCA 安全投影与聚类
packages/bundle/doctor	doctor profile、CLI、JSONL 读取与显式修复
packages/client/ui-session-doctor	Session 的 Web 诊断页面
packages/api/session-controller	Web 诊断与 RCA 所需的 Host Remote 方法

从源码运行

当前 Web 与 RCA 路径依赖对应的 DeepSeek Harness Host/API 源码接口，因此建议从源码运行：

git clone https://github.com/wsjwu58-cmd/dsh-session-doctor.git
cd dsh-session-doctor
pnpm install
pnpm run build

诊断单个 Session：

pnpm dsh --profile doctor <session-id>

输出 JSON、跨 Session 聚类和显式修复：

pnpm dsh --profile doctor <session-id> --json
pnpm dsh --profile doctor --cluster --json
pnpm dsh --profile doctor <session-id> --repair --json

启动 Web UI：

pnpm dsh web

启动后，在 Session 页面打开“诊断”标签页。确定性诊断不会调用模型，也不会向 Session 追加事件；“分析根因”需要当前 Session 有可用模型选择。

当前限制

• 这是社区维护的源码快照，不是官方 DeepSeek release；在对应上游 API 发布前，尚不能作为已发布 npm 版本的即插即用插件安装。
• 目前探测器不会自动判断提示词或模型质量、语义进展、错误文件定位、子代理爆炸，或有效/浪费 token 比例。
• 完整 Web replay 需要安装仓库要求的 Playwright 浏览器。

反馈

欢迎反馈 DeepSeek Harness、Node.js 与操作系统版本、使用的 profile，以及诊断报告中的发现类别或建议代码。请不要上传包含 API Key、原始模型消息、工具参数或其他敏感信息的 Session JSONL。

[moonquake2004]

Thanks — the payload-free design here is the part worth copying. Reading
packages/runtime-diagnostics/session-doctor/src/types.ts, DiagnosisReportV1
carries version, subject, analysis, findings and limitationCodes, and each
DiagnosisFindingV1 keeps id, detector{id,version}, category, impact, basis
(observed/heuristic), bounded evidence (seq + type), scalar metrics and a
recommendationCode. Versioning the report and versioning each detector is more
discipline than most of us started with.

Where we overlap: other tools in this family emit a machine-readable report per run —
dsh-doctor and zoahdev/dsh-plugin-doctor already agree on a small shape,
{"ok": bool, "checks": [{"name", "status", "detail"}]}, with lowercase
pass|warn|fail|skip. CI and support scripts can already read those; today
--profile doctor --json gives them findings instead. The gap is mostly vocabulary:
impact is info|warning|error rather than status, and the finding's text is a
locale-owned recommendationCode, so nothing in the report reads as detail.

No new format needed — the projection is detector.id → name,
impact → status (error→fail, warning→warn, info→pass), a rendered
sentence → detail, plus a tool field for provenance. Worth considering: basis: "heuristic" findings probably should not land on fail, since they are inferred
rather than observed. Happy to compare notes if that is useful.

[wsjwu58-cmd]

Thanks — this is a helpful comparison.

I agree that DiagnosisReportV1 should remain the canonical, versioned diagnostic report, while a separate compatibility projection could make it easier for CI and support scripts to consume results alongside existing Doctor tools.

The semantic edge cases you called out are important: info does not necessarily mean a successful check, and heuristic findings should not be promoted to fail as if they were directly observed. If I add an adapter, I would want it to preserve that distinction rather than flatten it away.

I will first compare the existing report consumers and the two check schemas you mentioned. A separate optional output or projection seems more appropriate than changing the current report format. Thanks again for the concrete mapping.

[moonquake2004]

Thanks — that is exactly the distinction worth preserving.

If it helps, the projection is mechanical and additive: detector.id → name, impact → status (error→fail, warning→warn, and info→skip rather than pass, since as you say info is not a successful check), the rendered sentence → detail, plus a tool id for provenance. basis: "heuristic" reads better surfaced in detail than promoted to fail. The shape we consume is pinned in dsh-doctor's docs/doctor-contract.md (§ minimal compatible subset: {ok, checks:[{name,status,detail}]} with lowercase status).

Nothing here implies a change to DiagnosisReportV1 — a separate opt-in projection is what we would read.