cat552/dsh-agent-quality-diagnosis

dsh-agent-quality-diagnosis

dsh-agent-quality-diagnosis 是一个 DSH Web 插件，用于把当前会话的事件日志转换为 agent 工作的执行质量报告。它补充 DSH Trajectory：Trajectory 展示事件账本，本插件回答当前是否仍有阻塞交付的问题，以及哪条具体动作可以关闭问题。

当前插件是 MVP，已提供：

- 通过 dsh-better-sidebar 注册 质量诊断 tab；
- Host API 读取 ctx.sessions.get(sessionId).events 并生成 tool-call 级报告；
- Host 报告不可用时回退到 Web runtime 摘要；
- ready、needs_action 或 blocked 状态的用户可读报告；
- 报告顶部的主行动建议；
- 带对象、动作、可选命令或相关命令、完成标准和可复制 Agent 继续处理指令的待处理动作；
- 独立的已解决记录和观察项分区，中途发生但后来修好的问题不会阻塞交付；
- 和上次缓存报告对比后显示本次关闭的问题；
- 用户可读影响、折叠证据和 Markdown 报告；
- 在浏览器本地缓存最近一次生成的报告；
- 侧边栏 tab 中的手动重新分析、复制报告、复制命令和复制 Agent 指令操作；
- 面向项目的 defaultVerificationCommand Host 配置；
- 可复制的证据定位信息，包含规则 id、事件序号、工具名、call id 和证据文本；
- 浏览器错误兜底，tab 渲染异常不会影响当前会话；
- 不修改 agent-loop、subagent 调度、工具权限或模型调用。

安装

先在 web profile 安装 dsh-better-sidebar：

pnpm dsh plugin --profile web add dsh-better-sidebar@latest

从本仓库路径安装该插件：

pnpm dsh plugin --profile web add link:/path/to/your/dsh-agent-quality-diagnosis

重启或刷新 DSH Web 后，在侧边栏中打开 质量诊断。

界面截图

以下截图展示报告总览、指标摘要、问题详情以及可复制的待处理动作和证据。

| 总览 | 报告摘要 |
| --- | --- |
| 质量诊断总览 | 报告摘要 |

| 问题详情 | 待处理动作和证据 |
| --- | --- |
| 问题详情 | 待处理动作和证据 |

可选 Host 配置：

- id: agent-quality-diagnosis
name: 'dsh-agent-quality-diagnosis'
config:
defaultVerificationCommand: 'pnpm run check'

诊断信号

Host 会话事件报告会检测：

- 失败工具调用；
- 连续重复工具调用；
- 文件修改后没有后续成功验证结果；
- 验证失败后没有后续通过验证；
- 删除、敏感信息访问、外部网络命令、权限变更等高风险操作。

Web runtime 回退报告会检测：

- 失败或被终止的后台任务；
- 等待用户授权或输入的 agent；
- 仍在运行、等待、失败或被终止的协作结果；
- 可能表示重复分工的相同 subagent 标题；
- 长时间运行的 worker。

边界

报告输出的是启发式诊断信号，不是绝对质量评分。每条 finding 都带用户可读影响、行动建议、置信度和可展开证据，方便用户判断误报。

总体状态只统计 open finding。工具失败后有后续成功重试、验证失败后有后续通过验证，或高风险操作存在 allowed-once 审批记录时，对应问题会进入已解决分区。重复尝试和非敏感风险操作默认作为观察项；只有持续失败或缺少交付所需授权证据时才进入待处理动作。

高风险操作的原始命令只作为相关命令展示，不作为建议重新执行的命令。Agent 指令会要求先补充授权、影响范围和回滚说明，再继续任何高风险操作。

所有分析都在插件内本地运行。插件不会上传 session log，也不会改变执行行为。如果 DSH 会话事件字段变化，更新 src/analyzer/trace-builder.ts；规则逻辑保留在 src/rules/ 下。

本地检查

插件位于主 workspace 包列表之外，因此自带轻量检查：

pnpm run check
pnpm exec tsc -p tsconfig.json
pnpm exec vitest run --config vitest.config.ts
node --check lib\index.js
node --check lib\client.js

演示报告

使用内置样例 session 生成 Markdown 报告：

pnpm run demo:report
pnpm run demo:report -- fixtures/missing-verification-session.json

这些 fixture 覆盖正常会话、失败工具调用、修改后未验证、失败工具后成功、验证失败后复验通过几类情况。

浏览器冒烟验证

使用已链接的 web profile 启动 DSH Web，然后在有工具调用的会话中打开 质量诊断：

$env:DSH_HOME=''
pnpm dsh --profile web

Host 路由可用时，tab 应显示 Host 会话事件指标。Host 路由失败时，tab 应显示 Web runtime 回退报告和 Host 错误提示。
处理开放问题后再次重新分析；如果上次缓存报告中该问题仍是开放状态，tab 应在 本次已关闭 中展示关闭记录。
展开证据行应提供可复制定位信息，可粘贴到 Trajectory 搜索或问题记录中。