# 常见问题速查与处理

[项目首页](../../README.md) · [使用说明](../user-guide/使用说明.md) · [安装与运维](安装与运维.md)

适用于 **0.12.3**，更新日期：2026-10-15。先按现象找到对应条目，按步骤处理，再检查“恢复标准”。本文依据当前实现和此前验收中发现的问题整理；旧版本的提示位置可能不同。

## 先找到你的问题

| 你看到的现象 | 看这里 |
| --- | --- |
| `/test` 没有开始，提示“环境尚未释放”“已隔离”或“浏览器释放未获确认” | [F01 环境未释放](#f01-环境未释放) |
| 提示“已有测试使用共享浏览器”，另一个对话不能开始 | [F02 共享环境被占用](#f02-共享环境被占用) |
| 点了释放但失败、超时，或按钮不可用 | [F03 释放失败或不可用](#f03-释放失败或不可用) |
| 找不到浏览器资源归属，或需要手工清理外部资源 | [F04 手工处置与证据释放](#f04-手工处置与证据释放) |
| 浏览器在运行，但没有实时画面浮窗 | [F05 预览没有出现](#f05-预览没有出现) |
| 设置保存失败、目录错误、没有可选浏览器 | [F06 预览配置问题](#f06-预览配置问题) |
| 设置里没有“测试插件”，命令变成普通聊天，升级后界面没变 | [F07 插件未加载或仍是旧版](#f07-插件未加载或仍是旧版) |
| GitHub 安装成功，启用时报 `harness-test (dsh-test-plugin): failed to import` | [F07 GitHub 安装入口缺失](#github-安装后启用报-failed-to-import) |
| `/test-run` 提示文件不存在、路径越界或用例读取错误 | [F08 命令和输入文件问题](#f08-命令和输入文件问题) |
| 报告大、重建失败或提示快照损坏 | [F18 账本与报告保存问题](#f18-账本与报告保存问题) |
| 构建报 `TS2307`、找不到 `@deepseek-ai/…` | [F09 构建缺少宿主依赖](#f09-构建缺少宿主依赖) |
| 安装报 `ENOENT`，却指向一个旧 tgz；重新打包仍像旧代码 | [F10 安装包引用或缓存问题](#f10-安装包引用或缓存问题) |
| DSH 网页打不开，或启动提示端口被占用 | [F11 服务和端口问题](#f11-服务和端口问题) |
| 一直等待计划、审批、工具返回或清理 | [F12 执行长时间等待](#f12-执行长时间等待) |
| 断言看起来通过了，最终却是 ERROR 或 INCONCLUSIVE | [F13 结果与预期不同](#f13-结果与预期不同) |
| 报告链接打不开、401，或附件丢失 | [F14 报告访问问题](#f14-报告访问问题) |
| 卸载后启动反复报 `Init page file does not exist`，路径指向插件的 `cdp-publisher.cjs` | [F15 卸载后的预览配置残留](#f15-卸载后的预览配置残留) |
| 录像提示缺少 PyAV、没有视频入口，或播放器/下载失败 | [F16 录像无法生成或播放](#f16-录像无法生成或播放) |

## F01 环境未释放

**现象：** 新的 `/test` 无法开始，提示环境未释放、已隔离或浏览器释放未获确认。早期版本曾出现命令已经失败、空白对话却没有显示错误的情况；0.8.2 会在发起测试命令的对话中给出提示。

**原因：** 上一次测试的动作没有结算，或必要资源没有确认清理。插件保留 `quarantine.json`，阻止下一次运行继续使用同一个环境。这次新测试尚未开始。

**处理步骤：**

1. 如果旧测试还在运行，先回到它的原对话，点击原生“停止生成”按钮，等待停止、工具返回和收尾结果。该按钮只停止当前对话。
2. 确认旧测试和其他外部操作已停止，测试专用浏览器没有被其他任务使用。
3. 点击 DSH 的 **设置 → 测试插件 → 测试环境**，查看原因；需要时展开“查看遗留测试”核对运行编号。
4. 点击“处理并释放”，阅读说明，勾选“我已确认旧测试及其他外部操作已停止，允许关闭测试专用浏览器”。
5. 点击“确认关闭并释放”。宿主出现工具审批时，按实际操作意图处理；等待浏览器关闭和预览停止完成。
6. 看到“测试环境已释放”后，关闭设置，回到对话，重新发送原来的 `/test` 命令。插件不会自动重试。

**恢复标准：** 设置显示已释放，重新进入设置后显示“测试环境已就绪，无需释放”；新的测试不再被同一隔离记录阻塞。后续业务是否通过，仍以新运行的结果为准。

若按钮不可用或释放失败，继续看 [F03](#f03-释放失败或不可用)。完整图解见[测试环境卡住怎么办](../user-guide/测试环境卡住怎么办.md)。

### 这几个操作不能代替释放

| 操作 | 实际效果 |
| --- | --- |
| 刷新网页、换一个对话 | 不会清理旧外部动作，也不会解除共享环境隔离 |
| 重启 DSH | 会重新检查遗留运行；没有结算的运行仍可能被隔离 |
| 等到超过 1 分钟 | 默认清理超时阈值是 60000 毫秒；超过后只提示可能卡住，不自动解除 |
| 关闭提示或关闭预览浮窗 | 只关闭对应界面，不释放测试浏览器或隔离 |
| 删除 `quarantine.json`、运行目录，或换一个 `outputRoot` | 会丢失或绕过处置依据，无法证明外部资源已经停止；不要用它来恢复运行 |

旧测试结果和报告保留原样；释放成功不会把旧 ERROR 改成 PASS。

## F02 共享环境被占用

**现象：** 提示“已有测试使用共享浏览器，请先结束或停止该测试”，但设置中不一定有隔离记录。

**处理步骤：**

1. 找到正在执行测试的原对话，查看输入框上方的进度区或标题旁的“测试进度”。
2. 等它正常结束；需要停止时，在该对话点击原生“停止生成”，等待在途操作与清理完成。
3. 原测试结束且没有隔离后，再在另一个对话开始用例。结束后出现隔离，则按 [F01](#f01-环境未释放) 处理。

**恢复标准：** 新测试不再提示共享环境被占用。

当前仍按共享环境串行运行。新建两个对话并不等于拥有两个独立测试浏览器；[多对话并行测试方案](../design/多对话并行测试优化方案.md) 是后续优化，尚未实现。

## F03 释放失败或不可用

在“设置 → 测试插件 → 测试环境”中按具体提示处理：

| 提示或现象 | 操作 |
| --- | --- |
| “确认关闭并释放”是灰色 | 先实际确认旧操作停止，再勾选确认框；若页面另有不可用原因，先处理该原因 |
| 当前测试或释放操作尚未结束 | 在原对话停止测试并等待收尾；已有释放操作在途时，等待它结算，不连续点释放 |
| 当前对话轮次尚未结束 | 等当前对话空闲后，再进行释放 |
| 请先打开一个对话 | 关闭设置，打开一个空闲对话，再返回设置操作；原生关闭工具需要通过该对话执行 |
| 没有可用的 Playwright 关闭工具 | 检查专用 Playwright MCP 的连接和当前 Agent 的工具配置，恢复可用后重试；无法恢复时看 [F04](#f04-手工处置与证据释放) |
| 浏览器关闭失败、审批被拒绝 | 查看原生工具结果，确认失败原因，处理连接或审批问题后重试；隔离仍保留 |
| 释放操作超时或已取消 | 浏览器关闭结果没有确认；先等待在途操作结算并检查 MCP，不重复派发。迟到成功不会自动解除这次隔离 |
| 隔离状态已变化 | 关闭本次确认，重新进入设置，核对当前记录后重新确认；旧确认不能释放新记录 |
| 无法读取测试环境状态 | 先检查 DSH 连接及登录状态，再重新进入设置；状态读取失败时不要猜测已释放 |
| 隔离记录、时间异常，或未能确认浏览器资源归属 | 保存记录并核对实际外部环境，按 [F04](#f04-手工处置与证据释放) 处理 |

如果在途工具始终不结算，先保存错误信息与运行编号；正常停止对应 DSH 服务，核实专用 MCP、浏览器及其他外部任务是否确实退出，再启动原 profile 并重新查看环境。重启用于恢复连接和服务，不表示隔离已解除。

**恢复标准：** 出现明确释放成功结果，设置重新读取后就绪；不能只依据关闭弹窗、浏览器窗口消失或超时结束判断。

## F04 手工处置与证据释放

**适用情况：** 自动浏览器关闭工具不可用、无法确认资源归属，或残留涉及接口任务、App 等其他外部资源。页面释放按钮只处理已确认归属的专用 Playwright 浏览器及本插件预览，不是所有外部环境的通用清理按钮。

### 第一步：先实际停止和检查资源

1. 保存遗留运行编号、错误信息及对应运行目录。
2. 找到这次测试实际使用的专用进程、连接或外部任务。正常停止对应任务，确认在途操作已经结束；需要环境重置时，执行该测试环境自己的重置流程。
3. 若 DSH 或专用 MCP 无法正常工作，正常停止对应服务后检查其子进程是否残留。只处理能够确认属于本次测试的资源；不要用 `killall` 清理所有浏览器、Node 或 Python 进程。
4. 保存实际检查、退出和重置的日志或截图。重新启动同一 DSH profile 时，保留原来的 `workspace` 和 `outputRoot`。

接口请求或 App 操作已经产生的外部影响，需要按实际系统的处理方式核实；关闭 Playwright 不能撤销它们。本插件目前没有新增 App 执行适配器。

### 第二步：填写处置文件

在插件配置的 **workspace** 内创建 `故障处置/环境释放.json`。下面是未完成的模板，故意保留 `false`；先完成上面的实际操作，再填写真实信息并将对应确认改为 `true`：

```json
{
  "operator": "填写实际操作者",
  "external_stopped": false,
  "environment_reset": false,
  "details": "填写实际检查、停止与重置过程，以及确认结果",
  "evidence": {
    "日志路径": "填写实际保存位置",
    "截图路径": "填写实际保存位置；没有截图时可删除此项"
  }
}
```

`external_stopped` 表示旧外部操作确实停止；`environment_reset` 表示受影响环境已经处置并恢复到可再次运行的状态。不能仅为通过校验就把它们改成 `true`。不适用的附件字段可以删除，但证据应记录实际核查依据。

### 第三步：提交证据并重试

进入“设置 → 测试插件 → 测试环境”，展开“高级处置：提交实际处置证据”：

1. 在文件输入框填写 `故障处置/环境释放.json`。
2. 阅读并勾选“我已停止旧任务、重置外部环境，并填写实际处置证据”。
3. 点击“提交证据并解除隔离”。

界面会校验声明和当前隔离编号、保存 `release-*.json` 处置审计，再解除隔离。它不会替你停止外部进程；路径相对插件的 `workspace`，不能使用工作区外的文件。提示“需提供外部停止、环境重置、操作者与处置证据”时，检查实际处置是否完成以及字段是否齐全。

**恢复标准：** 页面明确显示已记录处置证据并解除隔离；设置重新读取后就绪，再手动重发测试命令。旧测试结果保持不变。

如果 `quarantine.json` 本身连 JSON 语法都无法解析，设置页的证据提交也会拒绝操作。先备份原文件与运行目录，交由维护者依据真实记录修复文件，再按正常处置流程释放；不要凭空填写运行编号或隔离开始时间。

## F05 预览没有出现

**先判断是否已经执行网页动作。** 正在规划、等待 `/test-plan` 审核、运行接口测试、没有当前页面 CDP、测试已经结束时，没有实时浮窗是预期行为。

网页已开始操作却没有画面时：

1. 打开“设置 → 测试插件”，确认启用了浏览器实时预览，目录、端口和专用 Playwright 已选择并保存。
2. 查看设置中的接入说明，以及测试进度/实时画面的不可用原因。
3. 按原因在设置页“检测安装”，核对 Browscreen 命令位置与版本、采集端口、CDP 连通性和首帧。相关操作见 [F06](#f06-预览配置问题)。
4. 若用例打开多个页面，按用例需要保持一个活动页面；当前版本不自动选择多个标签中的目标。
5. 如果本轮曾手动关闭浮窗，有有效画面时点击测试进度里的“实时画面”重新打开。本轮不会反复自动弹出。

**恢复标准：** 页面 CDP 可达且第一张有效画面到达后，浮窗出现并继续更新。无需给用例增加“打开预览”的提示词，也无需为正常的设置页接入另开终端启动 Browscreen。

只在下一次测试确认新的预览设置。详细配置及逐项排查见[浏览器实时预览一步一步配置](../user-guide/浏览器实时预览一步一步配置.md)。

## F06 预览配置问题

| 现象 | 处理步骤 | 恢复标准 |
| --- | --- | --- |
| 设置检测找不到命令 | 先安装 Browscreen；用 `uv tool dir --bin` 找入口，必要时在高级设置填写完整路径 | 检测显示安装版本和命令位置 |
| 终端可用但 DSH 找不到 | 宿主 PATH 可能不同；填写实际可执行文件完整路径，不能填项目文件夹、`uv run` 或额外参数 | 设置页检测成功，下一次运行可启动采集 |
| 不支持版本、入口错误或查询超时 | 在宿主执行同一入口的 `version`；安装稳定版本 `>=0.3.0,<0.4.0`，基线为 0.3.0，Python 要求 ≥3.14 | 5 秒内得到有效版本且检测成功 |
| Playwright 下拉框为空或实例不兼容 | 按[首次注册说明](安装与运维.md#首次注册一个可编辑的-mcp)配置本机 `stdio`、`serverName: playwright` 的 Chromium MCP | 下拉框有兼容实例，可选择并保存 |
| 保存失败、配置被 patch 固定 | 将相关插件/MCP 配置放在可编辑 Web profile；处理命令行或 home overlay 的优先级，保留其他配置 | 保存明确成功，重新进入设置后值仍在 |
| 设置在别的页面有、当前页面没有 | 核对当前启动使用的 profile 和 `DSH_HOME`，不要把另一个 profile 的设置当成当前设置 | 在实际使用的 Web profile 中能读取已保存值 |
| 采集端口被占用 | 查询该端口的进程，改用空闲端口并保存；只停止确认属于自己的服务 | 下一次测试可以启动采集服务并收到有效画面 |

首次在 **DSH 宿主电脑** 安装：

```sh
uv tool install --force --python 3.14 'browscreen[video]==0.3.0' \
  -i http://mirrors.aliyun.com/pypi/simple/ \
  --trusted-host mirrors.aliyun.com
```

在 **启动 DSH 的终端** 检查：

```sh
browscreen version
uv tool dir --bin
```

以默认采集端口为例，只查询占用情况，不停止任何进程：

```sh
lsof -nP -iTCP:13390 -sTCP:LISTEN
```

DSH 网页端口、Browscreen 采集端口、浏览器 CDP 端口是三回事。不要猜 CDP 端口或手写一个固定地址；当前页面的 CDP 由插件从兼容 Playwright MCP 自动取得。

启动至首帧超过 60 秒、进程退出或采集停止时，当前浏览器测试会提示原因。不会随轮询无限重启，不复用占用端口上的未知服务。修正后在当前测试结束后重新执行；预览失败不改业务断言或解除隔离，普通聊天和无 CDP 测试没有全局安装提醒。

## F07 插件未加载或仍是旧版

**现象：** 没有“测试插件”设置、找不到测试命令、带参数命令被当成普通聊天，或升级后仍出现旧版常驻隔离提醒。

1. 确认安装的是 0.12.3，并且安装到了正在运行的 Web profile；自定义 `DSH_HOME` 时安装与启动须使用同一个值。
2. 按[安装更新流程](安装与运维.md#构建与打包)安装实际构建的包，不要只构建源码就认为运行中的插件已经更新。
3. 正常停止并启动同一 DSH Web 服务，再刷新网页；不要删除 profile 或历史对话。
4. 检查设置中是否出现“测试插件”，命令菜单能否识别 `/test`。正常新对话没有隔离提醒；环境状态到设置中查看。

**恢复标准：** 设置入口与命令菜单均存在；测试命令按当前版本处理，失败时会显示该对话的错误提示。

此前旧版曾因命令缺少参数声明，把带参数输入分流成普通聊天，该问题已修复。若当前实际安装仍表现如此，先核对运行包和 profile。安装器提示 `Already up to date` 也不能证明进程正在使用新代码，继续看 [F10](#f10-安装包引用或缓存问题)。

### GitHub 安装后启用报 failed to import

0.9.0 及以前只验证过本地构建的 tgz；Git 仓库忽略了 `dist`，也没有安装构建脚本。DSH 能读取 `cordis.patch.yml` 并登记插件，但 `package.json.main` 指向的 `dist/index.js` 不存在，启用时无法导入。仅确认“安装成功”不足以确认插件能运行。

Git 版本自 0.9.1 起包含构建产物，安装不运行插件构建脚本。先正常停止原服务，通过同一 profile 移除旧包，再安装 `github:Pegasus-Yang/DSH-Test-Plugin#v0.12.3` 并重新启动；插件管理页使用 `https://github.com/Pegasus-Yang/DSH-Test-Plugin.git#v0.12.3`。无需运行 `link-host`、复制其他电脑的调试文件或修改 pnpm 的构建脚本授权。

核对实际安装目录的 `package.json` 版本为 0.12.3，且 `dist/index.js`、`dist/client.js`、`dist/cdp-publisher.cjs` 存在。默认目录为 `~/.dsh/profiles/web/node_modules/dsh-test-plugin/`。恢复标准包括启用成功、出现测试设置和命令、实际用例能产生进度与报告；若版本和文件都正确仍失败，保留宿主终端的完整导入错误进一步排查。

## F08 命令和输入文件问题

| 现象 | 正确用法 |
| --- | --- |
| 把自然语言写在 `/test-run` 后面 | 自然语言使用 `/test <任务描述>`；`/test-run` 后面是已保存的 TXT 或 Markdown 文件路径 |
| 文件不存在、路径是目录 | 核对错误中的实际查找路径和工作区，再检查名称与扩展名；不能把目录当成用例文件 |
| 已添加工作区，相对路径找不到且目录内绝对路径也被拒绝 | 旧版本固定使用插件配置的 workspace，默认可能是宿主启动目录。升级到 0.12.3 后，进入目标工作区的对话执行；相对路径和目录内绝对路径使用同一工作区边界 |
| 输入路径越界或符号链接被拒绝 | 用例及 CSV 文件放进发起命令的对话工作区；仅无 cwd 的历史会话回退到插件 workspace。绝对路径、上级路径和符号链接均按实际目录校验 |
| 设置页高级处置证据路径越界 | 处置证据仍放进插件配置的 workspace；此设置页操作沿用原有边界 |
| 路径中有空格 | 给完整文件路径加引号，例如 `/test-run "用例目录/登录 用例.md"` |
| 用例文件无法读取 | 文件使用 UTF-8；TXT 每个非空行一条，Markdown 每个最外层列表项一条 |
| CSV 缺列、重复表头或没有数据 | 核对第一行参数名、每行列数和模板占位符，按[CSV 用法](../user-guide/使用说明.md#文件用例与-csv-参数化)修正 |

例如，下列命令分别适用于自然语言和文件用例：

```text
/test 访问ceshiren.com，搜索 agent，打开第一条结果，断言帖子的点赞数不为0
/test-run examples/ceshiren-cases.txt
```

**恢复标准：** 输入校验通过，进入规划或审核；路径和格式错误不会启动业务操作。

## F09 构建缺少宿主依赖

**现象：** `pnpm build` 或类型检查报 `TS2307: Cannot find module '@deepseek-ai/…'`，或测试收集时报 `Cannot find package '@deepseek-ai/dsh-scope'` 等导入错误。

常规开发使用公开 npm SDK。在项目目录之外的独立干净副本中先执行 `pnpm install --frozen-lockfile`，再运行构建、宿主入口导入和回归。0.12.3 已补齐缺少的运行时 peer 开发依赖；若仍缺包，保留完整导入链并核对清单与锁文件。已有 `link-host` 残留可能掩盖问题，不能用重新链接源码替代发行验证，见 [CI 公开依赖安装验收](../project/CI公开依赖安装验收.md)。

仅在调试未发布宿主改动时，在 **测试插件项目根目录** 链接已构建的 DSH，路径替换为本机实际目录：

```sh
node scripts/link-host.mjs /绝对路径/deepseek-harness
pnpm typecheck
pnpm build
```

若仍缺少模块或类型声明，先按 DSH 自己的说明完成宿主依赖安装和构建，再重新链接。`.local/host.json` 存在只代表路径曾被记录，不代表链接完整；链接脚本不会替你构建宿主。

**恢复标准：** 类型检查和构建均成功，再执行 `pnpm pack`。打包本身不会自动执行本项目构建；不要打包旧 `dist` 或关闭严格类型检查来绕过错误。

## F10 安装包引用或缓存问题

**现象：** 新 tgz 明明存在，安装却报找不到旧 tgz；或同路径重新打包后安装器认为已经是最新，实际仍使用旧内容。

1. 在插件项目中确认最新构建成功，再生成并保留新的 `dsh-test-plugin.tgz`。
2. 备份当前 profile 的 `package.json`、`pnpm-lock.yaml` 和 `cordis.patch.yml`，保留运行记录。默认 profile 在 `~/.dsh/profiles/web/`；自定义 home 按实际位置查找。
3. 在 **DSH 源码根目录** 通过公开 CLI 依次解除旧插件依赖，再安装新包；把下方路径换成自己的实际路径：

```sh
pnpm dsh plugin --profile web remove dsh-test-plugin
pnpm dsh plugin --profile web add /绝对路径/artifacts/package/dsh-test-plugin.tgz
```

4. 安装成功后，正常重启同一 profile 的 DSH 并刷新页面。核对安装版本和设置入口。

曾启用自动预览的 profile，在 `remove` 与 `add` 之间可能仍引用插件的初始化文件。升级时完成两条命令后再启动；若只卸载、不重装，按 [F15](#f15-卸载后的预览配置残留) 恢复 MCP 配置。

**恢复标准：** 安装成功，当前 profile 指向存在的新包，实际页面呈现对应版本行为。

此问题发生在 profile 的 `file:` 依赖引用或包内容复用阶段。不要删除整个 profile、手改锁文件或清空全部缓存；也不要删除 profile 仍引用的 tgz。新安装失败时按备份和[安装与运维](安装与运维.md#安装报-enoent指向已删除的旧安装包)核查旧来源。

## F11 服务和端口问题

**现象：** DSH 网页打不开、连接断开，或启动报 `EADDRINUSE`。

1. 检查启动终端是否仍在运行，以及是否报告了启动错误。使用宿主本次输出的正确访问地址和原有登录流程。
2. 查询实际网页端口；下方只读命令以本机 `3080` 为例：

```sh
lsof -nP -iTCP:3080 -sTCP:LISTEN
```

3. 若端口被另一服务占用，使用空闲端口；若是你自己的旧 DSH，先在它的启动终端按 `Ctrl+C` 正常停止，等退出后再用原来的启动参数启动。后台启动的实例需先核实 PID、完整启动命令和归属，再正常终止该实例。
4. 重启时保留原 `DSH_HOME`、profile、模型配置、`workspace`、`outputRoot` 及其他必要参数；不要同时启动两个争用同一端口的实例。

**恢复标准：** 服务明确就绪，网页正常连接，测试插件设置可以读取。服务恢复后仍有隔离，就按 [F01](#f01-环境未释放) 处理。

项目的 `scripts/stop-host.mjs` 只用于有对应状态文件的隔离开发宿主，不是任何 DSH 服务的通用停止命令。不要将已过期的验收 PID 直接复制到终止命令中。

## F12 执行长时间等待

先查看进度区的当前步骤、耗时和原生工具/审批记录：

| 等待位置 | 处理 |
| --- | --- |
| 模型要求补充动作、输入或预期 | 在当前对话补充缺少的信息 |
| `/test-plan` 等待审核 | 阅读计划并批准、要求修改或取消；等待审核没有执行网页动作 |
| 工具审批等待 | 展开原生审批，按实际操作意图批准或拒绝 |
| 工具一直没有返回 | 检查目标网页/API、MCP 连接和工具错误；需要停止时在原对话点击原生“停止生成”，等待在途结算 |
| 必要清理迟迟不结束 | 等收尾结果；若超时并进入隔离，按 [F01](#f01-环境未释放) 或 [F03](#f03-释放失败或不可用) 处理 |

默认业务步骤上限 `stepTimeoutMs` 为 180000 毫秒（3 分钟），清理上限 `cleanupTimeoutMs` 为 60000 毫秒（1 分钟），取消后等待在途结算的 `cancelGraceMs` 为 10000 毫秒（10 秒）。以实际配置为准，业务步骤的工具审批等待也计入步骤预算；计划审核等待不受业务步骤超时限制。

**恢复标准：** 运行继续推进，或明确结算为停止/错误并给出后续处置状态。不要把扩大超时当作清理残留的方法。

## F13 结果与预期不同

**现象：** 页面打开成功或某些断言通过，最终报告仍是 ERROR、FAIL 或 INCONCLUSIVE。

1. 查看报告的失败步骤、实际值、预期值和证据，而不只看模型的文字总结。
2. `FAIL` 表示相应断言不满足；`ERROR` 可能来自必要动作、必要输出或清理失败。即使业务断言通过，必要浏览器清理失败仍会得到 ERROR，并可能隔离环境。
3. `INCONCLUSIVE` 表示相关证据不足，不能当成通过。修正定位或采集问题后，以原有明确预期重新执行。
4. 资源问题先按 [F01](#f01-环境未释放) 清理；业务问题按实际证据修正任务/实现，不通过更改旧结果或删除证据解决。

**恢复标准：** 新运行有完整可信证据，断言和必要清理均按实际结果结算。预览画面可见并不能证明用例 PASS。

## F14 报告访问问题

**现象：** 报告链接无法打开、HTTP 401，或复制 HTML 后截图丢失。

1. HTTP 报告使用当前 DSH 服务和登录态。401 时先恢复该服务的正常登录；服务重启换端口后，使用当前页面给出的报告入口。
2. 想重建报告时，运行结束后在进度区点击“重建报告”；历史运行进入“设置 → 测试插件 → 测试报告”填写运行 ID 后重建。ID 留空只使用当前所选对话的报告。活动测试先等待结算；中断记录会按已保存事实生成不完整报告。
3. 也可在本机打开 `outputRoot/<运行ID>/report.html`。转移或离线查看时复制整个运行目录，保留 `evidence/` 等相对附件。
4. 重建报账本损坏时，保留 `events.jsonl` 与原始文件，交由维护者核查；不要随意删掉中间事件来得到通过结果。

**恢复标准：** 报告与对应附件能打开，运行编号及结果与原记录一致。重建生成独立文件，不重跑业务、不调用模型，也不覆盖原始报告。

## F15 卸载后的预览配置残留

0.9.1 已改为只接入 MCP 运行配置，新接入不会产生下述持久残留。以下恢复步骤用于 0.9.0 及以前已写入的覆盖。升级不会把旧 profile 内容假定为可直接删除，仍需先核对原始配置。

**现象：** 执行 `pnpm dsh plugin --profile web remove dsh-test-plugin` 后，启动终端反复出现下面的错误；DSH 可能已经打印网页地址，但浏览器 MCP 无法连接：

```text
Error: Init page file does not exist: /绝对路径/dsh-home/profiles/web/node_modules/dsh-test-plugin/dist/cdp-publisher.cjs
```

**原因：** 0.8.0 至 0.9.0 的自动预览接入通过宿主配置编辑器持久化 Playwright 的 `--config` 和 `DSH_TEST_PREVIEW_DIR`。生成的 JSON 在 `browser.initPage` 中引用已安装插件的 `dist/cdp-publisher.cjs`。公开 `remove` 命令移除包依赖和 bundle 登记，没有撤销插件对另一个 MCP 条目的配置修改。包被删除后，该引用失效，宿主连接重试会再次打印同一错误。这是预览接入的卸载恢复缺口，不是清空 pnpm 缓存可以解决的问题。

**只是升级插件：** 停止原服务，完成 `remove` 和新包的 `add` 后，再启动相同 profile。若新包已安装仍报告旧路径，按下方步骤核对实际初始化文件，不要创建空的替代文件来跳过检查。

**只卸载插件、不重装：**

1. 在 DSH 的启动终端按 `Ctrl+C`，等待服务退出。
2. 备份当前 profile 的 `cordis.patch.yml`。默认位置是 `~/.dsh/profiles/web/cordis.patch.yml`；使用自定义 `DSH_HOME` 时找对应文件。保留会话、模型配置和运行记录。
3. 打开这个 YAML 文件，找到选中 Playwright MCP 的覆盖条目。自动接入的条目通常同时包含 `args` 中的 `--config`、指向 `.browser-preview/<插件实例ID>/mcp-preview-*.json` 的路径，以及 `env.DSH_TEST_PREVIEW_DIR`。它可能位于原有 `insert` 注册之后；两个条目使用同一个 MCP ID，是注册与覆盖的关系。
4. 打开 `--config` 指向的 JSON，核对 `browser.initPage` 是否包含报错中指向已卸载插件的完整路径。只认这条已确认的插件路径，保留用户自己的初始化脚本和其他配置。
5. 选择与现有配置匹配的恢复方式：

| 核对结果 | 恢复方式 |
| --- | --- |
| 生成 JSON 只含插件初始化脚本及新增的 `--enable-automation`、`--remote-debugging-port=0`；覆盖与原始 MCP 仅相差该 `--config` 和预览环境变量 | 删除这条预览覆盖，保留原来的 MCP `insert` 注册。核对恢复后的命令、版本、参数与原始配置一致 |
| 生成 JSON 含用户配置，或覆盖还有其他修改 | 不删除整条覆盖或整个 JSON。只从 `browser.initPage` 数组删除已确认失效的插件路径，保留其他初始化脚本、网络和浏览器配置；移除该 MCP 的 `env.DSH_TEST_PREVIEW_DIR` |

6. 保存文件，使用原来的 home、profile 和启动参数重新启动 DSH。若重新安装插件，原有 `harness-test` 偏好可以保留，之后由设置页重新接入预览。

**恢复标准：** Playwright MCP 可以初始化并列出浏览器工具；终端不再出现同一初始化文件缺失错误。网页能打开不等于 MCP 已恢复；一次业务用例是否通过仍需单独验证。

不需要删除整个 `artifacts`、profile、历史会话或截图；这些文件是否存在不是启动失败的依据。生成配置文件只在仍被 MCP 引用时影响启动，先恢复引用，再决定是否保留旧预览产物。关闭预览开关仅影响下一次测试的采集，不会撤销已经持久化的 MCP 接入，不能代替上述卸载恢复步骤。

## F16 录像无法生成或播放

录像自 0.10.0 提供；旧的 `v0.9.2` 标签没有录像开关。升级到 `v0.12.3`，核对实际安装包，重启同一 profile 并刷新页面。

| 现象 | 处理步骤 | 恢复标准 |
| --- | --- | --- |
| 提示找不到 Browscreen 或不支持版本 | 在 DSH 宿主安装稳定 0.3.x；执行设置里同一入口的 `version`，必要时填写完整路径 | “检测安装”显示实际命令位置及支持的版本 |
| 提示“视频录制依赖不可用”、缺少 PyAV 或 libx264 | 执行下方带 `[video]` 的安装命令；核对设置指向这个工具环境，保存后重新运行 | 当前浏览器用例正常归档 MP4，缺依赖提示消失 |
| “检测安装”成功，实际录像仍失败 | 该按钮只查命令和版本；仍需视频依赖。先按上行安装，再核对实际录制错误 | 新运行收到完整或明确的部分收尾，不把 CLI 检测成功当作试录成功 |
| 报告没有“操作录像” | 核对录像开关已保存、测试在保存后开始，并实际使用兼容浏览器/唯一页面 CDP；API 实例没有入口是正常的 | 对应浏览器实例有可播放归档时出现入口；API 仍无媒体区域 |
| 提示提前终止或收尾失败 | 查看记录的具体原因、目录权限及磁盘空间。使用原生停止并等待收尾，避免强杀宿主 | 新运行有经过检查的录像；旧文件的失败说明保留 |
| 文件缺失、大小变化或播放器打不开 | 复制整个运行目录，检查 `evidence/browser-….mp4`；使用支持 H.264 的浏览器，如 Chrome。不要只搬 HTML | 从完整目录打开报告能播放，视频归属正确 |
| 在线视频地址过期、服务重启后不播放 | 重新打开已登录的报告页取得新地址；文件专用地址有效 24 小时，不能作为永久分享链接 | 报告重新加载后可播放与拖动 |
| 点击下载失败 | 使用当前插件重新生成的报告；在线下载应返回 MP4 附件。历史文件可直接从运行目录复制 | “下载视频”保存该实例的 MP4 |

在运行 DSH 的电脑执行：

```sh
uv tool install --force --python 3.14 'browscreen[video]==0.3.0' \
  -i http://mirrors.aliyun.com/pypi/simple/ \
  --trusted-host mirrors.aliyun.com
browscreen version
```

插件不会自动下载依赖。预览同时开启时，已识别的录制准备失败只允许一次预览回退；缺依赖提醒仍保留。只开启录像时不会回退成空浮窗。缺录像不等于业务断言失败，录像存在也不等于测试通过。

录制不会覆盖规划阶段或补录已经结束的运行。重建报告只读取归档事实；对缺失视频无法重新生成内容。完整点击步骤见[浏览器录像与报告](../user-guide/浏览器录像与报告.md)。

## F18 账本与报告保存问题

0.12.3 已优化报告和日志。旧运行的原 HTML 不会自动改写；安装更新包后，通过进度区或设置页“重建报告”生成独立 -rebuilt 文件。旧版内嵌状态日志也可以读取，重建不会访问网站、运行模型或重新执行步骤。

| 现象 | 处理 |
| --- | --- |
| 旧 HTML 很大、打开慢 | 更新插件后重建，原报告仍保留；不要通过删除失败调用或断言来缩小记录 |
| 单独 HTML 的账本下载或视频打不开 | 复制整个 run-… 目录，包括 events.jsonl、checkpoints/、evidence/ 和数据文件；单 HTML 仍能查看已内嵌的结论和步骤 |
| 在线日志或录像链接过期 | 重新打开经过宿主认证的报告获取新票据；不把带票据链接保存到公共文档 |
| 提示“已提交快照缺失或损坏” | 先备份整个目录；核对是否复制遗漏最近两份检查点，尝试从原运行目录重新复制。文件确实损坏时保留错误，不能修改哈希、覆盖提交记录或伪造完整状态 |
| 提示序号不连续或 JSONL 中间损坏 | 保留原件及错误位置，不删除中间事件绕过校验；仍可只读查看已有原报告，但不能把不可信重建标成成功 |
| 末尾截断、进程中断 | 重建会保留已保存事实并标“不完整”，未知调用不会改判成功；外部环境未确认释放时按环境恢复流程处置 |
| 重建正在读大文件，想取消 | 关闭请求或页面会取消读取并关闭文件流；重新进入设置后可再次发起，原件保留 |

新保存方式正常只保留两份已提交检查点。更早的全量状态副本被回收属于预期行为，原始执行事件和证据持续保留；不要手工删除应保留的最新文件。释放步骤明确失败时会立即隔离，安装了插件但没有发起测试的普通对话不增加常驻提示。

## 仍无法恢复时，先保留这些信息

- 插件版本、DSH 版本、发生时间、实际使用的 profile 和 `DSH_HOME`。
- 原始测试命令、页面/工具的完整错误文字，以及问题发生在哪一步。
- 运行编号；`outputRoot` 下对应的 `results.json`、`events.jsonl`、checkpoints/、报告，以及存在时的 `quarantine.json` 和 `release-*.json`。
- 相关 MCP 的实例名、工具调用编号和实际检查/处置记录。

日志和证据可能带有网页内容或认证信息。向维护者提供材料前移除密钥、Cookie、认证访问地址及与故障无关的个人内容；本机私有状态文件不要直接附到公开问题中。

历史问题与验证范围见[开发与验收记录](../project/开发进度.md)、[隔离恢复验收](../project/隔离提示与确认释放验收.md)和[设置释放与按需提示验收](../project/设置释放与按需提示验收.md)。