# 安装与运维

远程 RunBridge 浏览器无需配置本机 Playwright MCP，按[远程浏览器与持续预览](../user-guide/RunBridge远程浏览器与持续预览.md)填写私有访问文件和资源。以下 Playwright/Browscreen 配置适用于本机后端。

简体中文 | [English](安装与运维.en.md) · [项目首页](../../README.md)

已有环境出现问题时，先看[常见问题速查与处理](常见问题速查与处理.md)；命令被异常残留阻塞时，从“环境未释放”条目按顺序处理。

## 从 GitHub 安装与卸载

0.12.3 的 Git 版本包含宿主入口、浏览器入口和 CDP 初始化文件。用户无需构建插件、下载源码、运行 `link-host` 或允许插件安装构建脚本。在 DSH 的插件管理页填写 `https://github.com/Pegasus-Yang/DSH-Test-Plugin.git#v0.12.3`，安装后启用即可。

终端安装时，先正常停止现有 DSH，再在 DSH 源码目录执行；独立安装的 CLI 可去掉 `pnpm`：

```sh
pnpm dsh plugin --profile web add github:Pegasus-Yang/DSH-Test-Plugin#v0.12.3
pnpm dsh web
```

更换本插件的已有安装来源时，先通过同一 profile 的 `remove dsh-test-plugin` 移除旧包，再 `add` 新版本，完成后才启动。自定义 `DSH_HOME` 在安装和启动时保持一致。

卸载可以使用插件管理页，也可以在正常停止宿主后执行 `pnpm dsh plugin --profile web remove dsh-test-plugin`。0.9.1 的自动预览不改写 MCP 的 profile 配置：停用或卸载时，仍运行的 MCP 恢复原始参数；停服后直接 CLI 卸载，再启动只会读取原来的 MCP 配置。报告、用例工作区和保存的插件偏好保留。0.9.0 及以前留下的预览覆盖仍按[旧版残留恢复](常见问题速查与处理.md#f15-卸载后的预览配置残留)一次处理。

## 锁定环境

当前插件 0.12.3 使用公开 DSH SDK **0.2.1-alpha.3**，兼容核对的宿主源码提交为 `571902028a`；原生审核与真实运行验证见 0.12.2 的[宿主升级适配验收](../project/DSH宿主升级适配验收.md)，0.12.3 的公开依赖与干净构建验证见 [CI 公开依赖安装验收](../project/CI公开依赖安装验收.md)。

录像功能使用公开 npm `@deepseek-ai/dsh@0.2.1-alpha.1`、正式 PyPI `browscreen[video]==0.3.0` 完成隔离安装和浏览器验收，详见[录像验收记录](../project/浏览器录像与报告验收.md)。下文的宿主源码提交是此前开发与历史实测基线。

此前开发与旧验收使用 Node.js 22.22.3、pnpm 11.7.0、本地 DeepSeek Harness 0.2.1-alpha.1（提交5badb15009ae1756c3afe0ae0cef1faafc290ccc）、Playwright MCP 0.0.68、匹配的 Chromium 146.0.7680.0（revision 1212）。仅支持native工具模式，同批最大并发1。MCP自己的Playwright依赖由锁文件确定，与报告验收脚本使用的Playwright版本分别记录。

使用 `node scripts/install-browser.mjs` 安装MCP自身锁定的浏览器版本，不与验收脚本的Playwright版本混用。系统Chrome在本机曾因更新器继承输出管道导致browser.close迟迟不结算；测试MCP因此采用独立Chromium，不修改系统浏览器。

0.9.1 的开发依赖使用公开 npm 的 DSH SDK，首次开发按 README 安装依赖即可。仅调试未发布宿主改动时可选使用 `link-host`，该脚本只在插件项目内链接宿主已构建的包。`start-host` 为开发辅助脚本，读取本机已有模型配置；没有配置时请先在 Harness 中设置模型，不要把密钥写进示例或 Git。

`link-host` 会留下未在清单中声明的宿主源码链接，随后执行 `pnpm install --frozen-lockfile` 也不能证明这些链接已消失。交付前应从待验证提交创建项目目录之外的独立副本，在没有 `node_modules`、宿主链接和本机配置的环境中冻结安装，并按 `.github/workflows/ci.yml` 依次完成构建、`dist` 一致性、宿主入口真实导入、类型、单元/集成回归与安装包检查。构建后再执行测试，避免测试读取正在重建的 `dist`。

## 配置

在当前 profile 的 `cordis.patch.yml` 中配置，默认位置是 `~/.dsh/profiles/web/cordis.patch.yml`。以下 patch 更新安装包已经注册的 `harness-test`，并添加专用 MCP；路径替换为自己的用例工作区，不要求插件源码目录。如果已有名为 playwright 的专用 MCP，应复用它，不要重复注册。仅执行接口测试可省略整个 `insert` 段。

```yaml
- id: tools
  config:
    mode: native
- id: agent-loop
  config:
    maxParallelToolCalls: 1
- id: harness-test
  config:
    workspace: /绝对路径/test-workspace
    outputRoot: /绝对路径/test-workspace/artifacts/runs
- insert:
    - id: test-playwright
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: playwright
        transport: stdio
        command: pnpm
        args: ['dlx', '@playwright/mcp@0.0.68', '--headless', '--browser', 'chromium', '--isolated']
        toolCallTimeoutMs: 60000
        failOnStartupError: true
```

在 Harness 源码目录执行 `pnpm dsh web --port 3080`，使用空闲端口；已有服务需正常停止后重新启动。独立 CLI 使用 `dsh web --port 3080`。保留原有模型、认证及其他启动参数，打开宿主输出的访问地址。0.12.3 的文件命令读取当前对话的工作目录；选择目标工作区后，应进入该工作区的对话执行。仅无工作目录的历史会话使用配置的 `workspace` 作为输入边界；设置页高级处置证据继续使用该配置。`outputRoot` 独立决定运行及报告保存位置，重启时保持不变。

为测试使用专用MCP实例；运行期间不要在其他会话共享操作该浏览器。工具名必须采用mcp__playwright__前缀；更换MCP或宿主版本后需重验返回格式、早退、审批、取消和清理。

| 配置 | 默认值 | 说明 |
| --- | --- | --- |
| workspace | 进程工作目录 | 无 cwd 的历史会话输入目录及设置页高级处置证据边界；有 cwd 的对话文件命令使用其自身工作区 |
| outputRoot | artifacts/runs绝对路径 | 运行数据与隔离标记；重启必须保持不变 |
| stepTimeoutMs | 180000 | 业务动作和审批等待共同上限，毫秒 |
| cleanupTimeoutMs | 60000 | 每个清理动作及其审批的上限 |
| cancelGraceMs | 10000 | 取消后等待在途结算的独立期限 |
| maxRevisions | 10 | 一个批次最多10次动态修订 |

所有预算为有限正数。模型轮次与路由沿用当前 Agent；结束前最多补充两次继续指导。输出目录需可写；写入错误停止新动作，不把错误报告成成功。

## 构建与打包

发布新版本须在完成该版本实现、文档与验收并提交后，创建和同步对应的 `v<版本号>` 附注标签。历史版本索引、操作步骤及核对方法见[版本发布与Git标签](版本发布与Git标签.md)。

在插件项目根目录执行，后续构建固定使用同一个包名：

```sh
pnpm typecheck
pnpm build
pnpm test:unit
pnpm test:integration
pnpm pack --out artifacts/package/dsh-test-plugin.tgz
```

随后在本地 DeepSeek Harness 源码目录执行公开 profile 插件命令（已安装独立 `dsh` CLI 时可用 `dsh` 替代 `pnpm dsh`）：

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

不设置 `DSH_HOME` 时安装到当前用户的默认 DSH home；隔离验证时须在安装及启动命令中使用同一个 `DSH_HOME`。本地 tgz 是 profile 的 `file:` 依赖来源，不是安装后就能随意删除的临时文件；保留当前清单引用的包，成功迁移到新路径后再清理旧包。后续统一使用 `dsh-test-plugin.tgz`，历史验收记录中的不同文件名只描述当时产物。

包内包含dist、使用/部署文档、README、许可证、示例及插件patch、图标和本地化元数据；宿主模块为peer依赖，由相同版本的Harness提供。正式发布前须查阅开发进度中打包安装的实测结论，不把构建成功等同于干净环境安装成功。

`pnpm build` 构建宿主插件入口、`dsh.client` 浏览器模块和 CDP 初始化文件。升级须重启同一 profile 的宿主并刷新页面；无需删除或改写历史会话。Git 发行必须提交最新 `dist`，`pnpm verify:package` 检查清单声明的入口文件；CI 重建后用 `git diff --exit-code -- dist` 检查产物一致性。仓库没有 `prepare` 等安装生命周期脚本，避免 Git 来源构建授权成为普通用户的安装前置条件。

### 构建报 TS2307，找不到 DSH 宿主模块

如果类型检查或导入插件提示 `Cannot find module` / `Cannot find package '@deepseek-ai/…'`，先在独立干净副本中执行 `pnpm install --frozen-lockfile` 复现。常规构建只依赖清单声明的公开 SDK；缺少运行时 peer 时核对 `package.json` 与锁文件，保留严格类型检查，不使用宿主源码链接掩盖发行检查失败。

仅调试未发布宿主改动时，在插件项目根目录执行，替换为本机已构建的 DSH 源码目录。`.local/host.json` 只记录路径，文件存在不代表链接仍然存在：

```sh
node scripts/link-host.mjs /绝对路径/deepseek-harness
pnpm typecheck
pnpm build
pnpm pack --out artifacts/package/dsh-test-plugin.tgz
```

链接脚本不构建宿主。若链接后仍提示模块或类型声明缺失，请先按 DSH 自身文档完成其依赖安装和构建，再重试。不要通过关闭严格类型检查、添加假的模块声明或打包旧 `dist` 来绕过错误；`pnpm pack` 本身不会执行本项目的构建，必须先确认 `pnpm build` 成功。

同路径、同版本重新打包时，实测 pnpm 11.7.0 可能显示安装成功却继续复用旧内容。开发版本更新请在新包生成后依次执行下面的 remove/add 命令，再重启服务；不要仅凭 `Already up to date` 判断已加载新代码。

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

完成 `remove` 和 `add` 后再启动宿主。0.8.0 至 0.9.0 曾启用自动预览的 profile 会保留 Playwright 的初始化文件引用；在只卸载、尚未重装时启动，可能报 `Init page file does not exist`。公开 `remove` 不撤销对 MCP 的预览配置修改。只卸载不重装时，先备份并按[卸载后的预览配置残留](常见问题速查与处理.md#f15-卸载后的预览配置残留)恢复 MCP；不要删除整个 profile 或运行目录。

`dsh plugin --profile web add` 会把插件加入该profile的 `package.json` 中 `dsh.profile.bundles`，由包内 `cordis.patch.yml` 注册插件。用户profile的patch没有单独的 `harness-test` 条目不代表未加载，不要重复插入。更新安装包后重启使用同一profile的Web服务，并刷新网页。带参数命令变成普通聊天时，应检查插件版本是否包含命令参数声明；自然语言入口为 `/test`，文字文件入口为 `/test-run`。

### 安装报 ENOENT，指向已删除的旧安装包

如果命令安装的是 `dsh-test-plugin.tgz`，报错却指向 `dsh-test-plugin-plan-review.tgz` 等旧文件，原因是 web profile 的 `package.json` 和 `pnpm-lock.yaml` 仍引用旧的 `file:` 依赖。实测 pnpm 11.7.0 在更新这个依赖时会尝试读取已删除的旧包；新包存在也可能失败。这发生在包管理阶段，不代表插件代码加载失败。

确认新 tgz 已生成后，在 Harness 源码目录依次执行：

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

`remove` 按包名解除旧依赖及其 bundle 登记，`add` 从新包重新安装并登记；不删除会话、测试记录或整个 profile，也不需要恢复旧文件名、手改锁文件或清空 pnpm 缓存。使用自定义 `DSH_HOME` 时，两条命令必须指定相同值。安装成功后，重启对应 profile 的宿主并刷新网页，让运行中的进程加载新代码。

## 通过设置页启用预览与录像（推荐）

0.12.3 使用已安装的本机 Browscreen 0.3.x 命令。首次通过 uv 安装 `browscreen[video]==0.3.0`（Python ≥3.14），进入“设置 → 测试插件 → 浏览器预览与录像”，启用并点击“检测安装”，选择采集端口和 MCP 后保存。默认命令是 `browscreen`，高级设置可以填完整可执行文件路径。完整安装、点击步骤、字段示例和排错表见[浏览器实时预览一步一步配置](../user-guide/浏览器实时预览一步一步配置.md)。之后直接使用 `/test` 或 `/test-plan`，无需源码目录、单独启动服务或增加预览提示词。

录像需要 `video` extra（PyAV 及 H.264 编码器）。安装命令及详细操作见[浏览器录像与报告](../user-guide/浏览器录像与报告.md)。勾选“录制浏览器操作视频”并保存即可；独立开关默认关闭，不要求开启浮窗。纯接口及无 CDP 任务不启动采集。检测安装只检查 CLI 版本；缺少视频依赖时在当前测试进度给出安装命令，预览也开启时仅尝试一次预览回退，不自动安装。

### 首次注册一个可编辑的 MCP

已有可用的本机 Playwright MCP 时复用它。没有时，在当前 Web profile 的 `cordis.patch.yml` 中注册；普通 home 是 `~/.dsh/profiles/web/cordis.patch.yml`。保留原文件已有条目，在 YAML 列表末尾添加以下内容，替换为本机真实 CLI 路径；不要同时注册第二个相同 `serverName`：

```yaml
- insert:
    - id: mcp-playwright
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: playwright
        transport: stdio
        command: node
        args:
          - /绝对路径/DeepseekHarnessTestPlugin/node_modules/@playwright/mcp/cli.js
          - --headless
          - --browser
          - chromium
          - --isolated
        toolCallTimeoutMs: 60000
        failOnStartupError: true
```

配置写入 profile 后，正常重启 DSH Web 服务并刷新页面。只需注册 MCP，无需手工添加 CDP 初始化脚本、`preview` 或 `DSH_TEST_PREVIEW_DIR`；设置页启用后插件会处理这些内容。使用 `pnpm dlx @playwright/mcp@版本` 的既有实例同样保留其命令和版本，不会被自动升级；更换 MCP 版本仍需重新验证兼容性。

**不要用命令行 `--patch` 固定这两个条目的配置来配合设置页。** 宿主会拒绝覆盖高优先级命令行/home overlay 的 profile 写入。需要保留的 `workspace`、`outputRoot`、MCP 参数等应移到当前可编辑的 profile；只移与此功能相关的条目，保留模型和认证配置。插件只修改用户选中的兼容 MCP，保留它的其他参数、环境变量和 JSON 浏览器配置。

### 保存和生效

预览字段位于插件条目的 `browserPreview`。它使用 DSH 的 volatile 设置，保存不会重载测试插件，也不会立即重新连接 MCP。下一次 `/test`、`/test-plan`、`/test-run` 或 `/test-data` 开始前读取新配置；首次接入通过 Cordis 的运行配置拦截与 MCP 自身的重启生命周期生效，不把预览 `--config` 或环境变量写入 profile。生成 JSON 保留用户的浏览器配置和初始化脚本，插件初始化文件采用运行目录中的独立副本。预览和录像均关闭后下一次准备、切换 MCP、停用或卸载插件会解除接入；宿主整体关闭时不额外重启正在退出的 MCP。不要与其他会话共享操作选中的浏览器。仅修改采集端口时不必重新连接已经正确接入的 MCP。

首次安装插件仍需重启宿主加载新代码；后续设置页保存不需要重启 DSH。偏好保存至当前 profile，刷新和正常重启后保留。设置字段为 `enabled`、`recordingEnabled`（默认 false）、`browscreenExecutable`、`port` 和 `mcpId`。提供设置偏好时优先使用它，包括显式关闭；开发或显式部署也可提供下文的新 `preview` 运行配置。

安装检测使用 DSH 宿主 PATH，与另一个终端可能不同；找不到时填写 `uv tool dir --bin` 所示目录内的 `browscreen` 完整路径。稳定版本范围为 `>=0.3.0,<0.4.0`。版本查询限 5 秒，启动至有效首帧限 60 秒；失败后不会随进度轮询反复重启。设置页主动检测或当前浏览器测试按需提示，配置错误只停用展示，不改变业务断言或解除资源隔离。

## 浏览器实时预览（可选）

本节说明新 CLI 方式的显式部署配置。普通用户优先使用设置页；两种入口不用同时配置，都由插件按需管理自己的采集进程。

步骤图无需额外配置，Web 插件前端由安装包自动装载。画面预览需要单独配置 Browscreen 接入；只在当前运行实际持有浏览器上下文、页面 CDP 可达且有效首帧到达后自动打开浮窗。API、无 CDP、连接失败或没有首帧均保持关闭。

先在 DSH 宿主安装命令，运行时无需 uv 或源码项目：

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

宿主 PATH 需要能找到 `browscreen`，也可以在配置中指定完整可执行文件路径。插件不自动安装、下载或升级依赖。

在插件工作区创建 `.local/browser-preview/`，保存 `mcp-preview.json`；初始化文件使用本项目已构建的文件，也可使用安装包中的 `dist/cdp-publisher.cjs`：

```json
{
  "browser": {
    "initPage": ["/绝对路径/DeepseekHarnessTestPlugin/dist/cdp-publisher.cjs"],
    "launchOptions": { "args": ["--enable-automation", "--remote-debugging-port=0"] }
  }
}
```

当前 MCP 的 ESM 初始化文件加载有限制，必须使用 `.cjs`。`--enable-automation` 用于允许公开 CDP 命令读取真实调试端口；只加入启用预览的专用测试浏览器。不要填入一个猜测的固定 CDP 端口，也不要改用系统 Chrome。

`--remote-debugging-port=0` 表示让系统分配空闲端口，适配默认仅使用调试 pipe 的 MCP 版本。插件从当前浏览器公开命令行指定的临时目录读取 DevToolsActivePort，再交付实际端口；设置页会自动补充这些参数，无需用户操作。0.0.68 与 0.0.80 的真实 CDP/画面接入均已验证。

在已有 patch 上更新相同实例，替换路径和空闲服务端口：

```yaml
- id: harness-test
  config:
    preview:
      workDir: /绝对路径/DeepseekHarnessTestPlugin/.local/browser-preview
      browscreenUrl: http://127.0.0.1:8000
      browscreenExecutable: browscreen
      previewEnabled: true
      recordingEnabled: false
- id: test-playwright
  config:
    args: ['/绝对路径/DeepseekHarnessTestPlugin/node_modules/@playwright/mcp/cli.js', '--headless', '--browser', 'chromium', '--isolated', '--config', '/绝对路径/DeepseekHarnessTestPlugin/.local/browser-preview/mcp-preview.json']
    env:
      DSH_TEST_PREVIEW_DIR: /绝对路径/DeepseekHarnessTestPlugin/.local/browser-preview
```

显式配置中 `previewEnabled` 默认 true，`recordingEnabled` 默认 false；只录像时设置前者 false、后者 true。录像按运行/实例写入 `evidence/browser-<ID>.mp4`，不会写到共享 CDP 目录。正常 SIGTERM 收尾使用当前清理剩余期限；超过期限封存录像失败并强制结束。报告生成前等待媒体结算，紧急封存后迟到视频不改写结果。

`workDir` 和 MCP 的 `DSH_TEST_PREVIEW_DIR` 必须一致。插件与浏览器使用同一运行/实例身份交付 CDP；不同宿主使用不同目录和 Browscreen 端口。`browscreenExecutable` 省略时默认为 `browscreen`。`browscreenUrl` 决定本机监听地址和端口，插件在有效 CDP 后直接启动命令；没有复用外部服务的隐式模式。端口占用时提示换端口，不接管或终止占用进程。

预览通过 DSH 的认证同源路由读取 PNG，用户浏览器无需访问服务端 localhost。该接法只支持本机 Browscreen HTTP 根地址。关闭浮窗不关闭浏览器；测试结束或上下文释放时撤销画面，释放插件启动的采集服务。预览错误不进入测试结果。

首版只验收单活动页面，多标签时停用画面，避免显示错误目标；未接入鼠标轨迹。App 或其他无 CDP 的执行环境不会因此创建画面浮窗，本轮没有新增 App 执行适配器。

### 已升级插件，但执行网页用例没有浮窗

无需增加“打开预览”等提示词；仍使用 `/test` 或 `/test-plan` 执行用例。0.12.3 优先在设置页启用，下一次测试会准备选中的 MCP；手工接法则检查实际启动的 profile/patch 是否同时包含插件的 `preview`、MCP 的 `--config` 初始化文件和 `DSH_TEST_PREVIEW_DIR`。仅开启 headless 浏览器或另起一个 Browscreen 服务，不能完成当前页面 CDP 的交付。

更新已有 MCP 时使用其实际 ID；例如原实例为 `mcp-playwright`，上例中的 `test-playwright` 必须替换为 `mcp-playwright`。启动 patch 生效后，正常重启宿主并刷新页面。采集服务由插件按需启动和回收，无需另起服务。

开发脚本的自动接入只作用于它创建的隔离 home，不会改动 `~/.dsh` 的默认 Web profile。历史运行已经结束时不会补开实时画面，需在后续运行中查看；已有资源隔离按原处置流程处理，启用预览不会解除隔离。

## 隔离开发环境

以下脚本从源码项目运行，不包含在发行包中。完成依赖安装、link-host、build 和浏览器安装后，在插件根目录运行 `node scripts/start-host.mjs`。默认加载本地 `dist/index.js`，创建 `.local/dsh-home`，使用宿主已构建的 `apps/cli/lib/bin.js`，监听 13379。

脚本从现有源 home 读取 `.credentials.yaml` 的凭据引用及 web patch 的 `llm-pi-ai` / `agent-default-model` 配置，不复制全部模型配置或内联凭据记录；其他模型配置方式请按宿主流程配置。源码路径保存在 `.local/host.json`，认证访问地址保存在 `.local/host-state.json`，不要公开这些本地配置。

开发脚本默认使用本机 `browscreen`，预览目录按 DSH 端口区分，采集服务使用 DSH 端口加一。它不探测相邻源码项目，不安装依赖；检测和启动仍等待有效 CDP，浮窗等待有效首帧。设置 `DSH_TEST_PREVIEW=0` 时关闭预览；API 测试不启动采集进程。

| 环境变量 | 用途 |
| --- | --- |
| `DSH_CREDENTIAL_HOME` | 模型配置及凭据引用来源，默认 `~/.dsh` |
| `DSH_TEST_HOME` | 隔离 home，默认 `.local/dsh-home` |
| `DSH_TEST_PORT` | 端口，默认 `13379` |
| `DSH_TEST_OUTPUT` | 运行记录目录，默认 `artifacts/runs` |
| `DSH_TEST_INSTALLED=1` | 使用已安装到隔离 home 的 bundle，而非直接插入本地 dist |
| `DSH_MCP_TRACE=1` | 记录 MCP 消息元数据，不记录正文 |
| `DSH_TEST_STATE` | 本机认证状态文件路径；同时用于区分日志和 overlay 路径 |
| `DSH_BROWSCREEN_EXECUTABLE` | 已安装的 Browscreen 可执行文件，默认 `browscreen`，可指定完整路径 |
| `DSH_TEST_PREVIEW=0` | 开发环境禁用画面接入，保留进度面板 |
| `DSH_TEST_SETTINGS=1` | 将验证用插件与 MCP 放到可编辑的隔离 profile，配合 `DSH_TEST_PREVIEW=0` 验证设置页接入；不修改默认用户 profile |

## 停止与隔离处置

0.8.2 起，环境状态和释放入口移到“设置 → 测试插件 → 测试环境”。普通对话不显示全局隔离提示；测试命令被隔离阻塞时，仅在发起命令的对话中说明原因，引导先进入设置处理再重新执行。在设置页可查看隔离持续时间；超过已有 `cleanupTimeoutMs` 时提示可能异常卡住。用户确认旧操作停止后，可主动关闭测试专用浏览器并释放。关闭、预览收尾或状态校验失败时保留隔离并显示原因；不会因时间超限自动删除标记。完整步骤见[测试环境卡住怎么办](../user-guide/测试环境卡住怎么办.md)。

DSH 原生“停止生成”按钮禁止后续业务派发，在途全部结算后在发起会话进入原生清理轮次。清理中也可使用原生审批。收尾超限、必要资源清理未完成或重建发现未结算调用会持久隔离；重启不会自行解除。迟到结果仅审计，不回改结果。

解除前必须核实外部动作停止、重置受影响环境并记录证据。项目内创建处置JSON：

```json
{
  "operator": "实际操作者",
  "external_stopped": true,
  "environment_reset": true,
  "details": "实际检查和重置过程",
  "evidence": {"日志或截图路径": "实际位置"}
}
```

进入“设置 → 测试插件 → 测试环境”，展开“高级处置：提交实际处置证据”，在文件输入框填写 `相对路径/处置.json`（路径相对插件的 `workspace`），勾选处置确认并点击“提交证据并解除隔离”。插件校验文件声明和当前隔离编号，保存 `release-*.json` 审计后解除门禁。此操作接受操作者对实际处置的声明，不能替代外部检查；不得为了继续测试虚填true或直接删除quarantine.json。重启恢复识别已处置运行的审计记录。

开发脚本 `node scripts/stop-host.mjs` 默认仅停止 `.local/host-state.json` 所记录宿主及其进程树，保存 `.local/reset-proof.json`；可用 `DSH_TEST_STATE`、`DSH_TEST_PROOF` 指定本任务另一隔离宿主状态与处置文件；它不是通用生产运维接口。调试代理 `DSH_MCP_TRACE=1` 只记录MCP消息ID、名称、大小和时间，不记录消息正文。调试文件全部忽略，不进入包或Git。

报告可整体复制；路径为相对附件路径。新运行还保存 `actual-steps.json` 和 `manual-cases.md`；重建生成带 `-rebuilt` 的独立文件，导出失败可从已保存账本重新生成，详见[实际步骤与手工用例](../user-guide/实际步骤与手工用例.md)。JSONL中间损坏拒绝重建，尾部损坏标记中断。原始报告和记录保持原貌；重建写入独立文件。截图没有自动视觉脱敏，分发前按实际页面内容检查。

## 网页报告入口

Web部署自动复用可选的webServer和connection服务，通过原生工具结果和最终回复提供报告链接，通过/test-reports提供受当前登录态保护的静态报告与附件；无需新增端口或独立服务。只允许GET/HEAD及限定的报告文件，拒绝越界路径和符号链接逃逸，HTML使用sandbox策略与宿主页面隔离。没有这些Web服务时不会启动额外服务，仍保留本地静态HTML。更新插件后重启宿主并刷新网页。

## 原生计划审核依赖

0.4.0 新增 `/test-plan`，要求当前 Agent 的有效命令目录提供宿主原生 `/plan`，并组合 `exit_plan_mode` 与用户问题审核通道。官方 Web 标准预设已提供这些组件；自定义预设需要按宿主规范组合。`planMode` 在 Web 的隔离组内部，插件经官方命令注册器进入，不直接读取隔离服务。未提供此能力时 `/test-plan` 返回明确错误，原有 `/test` 和 `/test-run` 不依赖它。

等待用户审核不受测试步骤超时限制；停止未批准的计划不会执行外部动作或浏览器清理。宿主重启后的未结算运行仍按现有隔离与人工处置规则处理，不自动恢复执行。