# dsh-agent-quality-diagnosis

[English](README.md) | 中文

`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`：

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

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

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

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

## 界面截图

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

| 总览 | 报告摘要 |
| --- | --- |
| ![质量诊断总览](assets/overview.png) | ![报告摘要](assets/report-summary.png) |

| 问题详情 | 待处理动作和证据 |
| --- | --- |
| ![问题详情](assets/finding-detail.png) | ![待处理动作和证据](assets/actions-and-evidence.png) |

可选 Host 配置：

```yaml
- 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 包列表之外，因此自带轻量检查：

```powershell
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 报告：

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

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

## 浏览器冒烟验证

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

```powershell
$env:DSH_HOME='<path-to-your-dsh-home>'
pnpm dsh --profile web
```

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