# 使用说明

简体中文 | [English](使用说明.en.md) · [项目首页](../../README.md)

本文适用于 0.12.3，包含实际步骤与手工用例、当前对话工作区文件读取和独立账本下载。

遇到命令未启动、环境残留或预览异常，先看[常见问题速查与处理](../deployment/常见问题速查与处理.md)。

底部面板默认显示当前步骤、结算进度和耗时，完整步骤通过“查看全部步骤”展开；长文字、折叠和多实例显示见[执行步骤与进度显示](执行步骤与进度显示.md)。

## 用截图认识功能

可以按“描述任务 → 审核计划 → 看进度与画面 → 查看报告”的顺序认识插件。下方用例截图来自 **0.11.2 的真实 GitLab 运行**，展示无需账号的登录页检查和 Markdown 接口集合；设置截图用于说明字段位置。先按[GitLab 测试要求与本地调试](GitLab测试要求与本地调试.md)准备环境；实际步骤和耗时可能不同。

| 想了解什么 | 去哪里看 |
| --- | --- |
| 开始之前，怎么检查它准备做什么 | [计划全文和审核按钮](#先审核再执行) |
| 现在做到哪一步，已经花了多久 | [当前步骤和完整列表](#步骤进度耗时与实时画面) |
| 浏览器没有窗口，怎样看到它正在操作的网页 | [实时画面和预览设置](#步骤进度耗时与实时画面) |
| 怎样回看浏览器操作视频 | [录像开关、报告播放和下载](浏览器录像与报告.md) |
| 测试为什么通过，实际采集到了什么 | [报告及实际值与预期](#查看报告) |

## 命令

第一次启用浏览器浮窗，请按[浏览器实时预览一步一步配置](浏览器实时预览一步一步配置.md)操作：安装 Browscreen 命令，在“设置 → 测试插件”检测安装，保存启用、命令路径、端口和 Playwright 选择，之后继续使用下面的命令即可。设置修改在下一次测试生效，API 或无 CDP 任务不会出现空浮窗。

| 命令 | 用途 |
| --- | --- |
| `/test <描述>` | 在当前对话分析并生成计划，校验通过后直接执行，无需确认 |
| `/test-plan <描述>` / `/test-plan --file <路径>` | 审核任务或 TXT/Markdown 用例的文字步骤后执行 |
| `/test-run <文件路径>` | 读取 TXT 或 Markdown 用例，规划通报后执行 |
| `/test-data <CSV路径> <模板或--file 路径>` | 展开参数，审核所有实例的原文、参数和步骤后执行 |

其他操作直接在界面完成：查看状态用输入框上方的进度区；停止用 DSH 原生“停止生成”；报告重建用运行结束后的“重建报告”或“设置 → 测试插件 → 测试报告”；异常处置和证据提交用“设置 → 测试插件 → 测试环境”。只有上表四个斜杠命令。

自然语言用例请直接输入：

```text
/test 访问 http://127.0.0.1:8929/users/sign_in，断言页面存在用户名输入框、密码输入框和 Sign in 登录按钮
```

`/test-run` 接受已保存的 TXT 或 Markdown 文件路径，不能在其后直接填写自然语言任务。在网页命令菜单选择命令后继续输入对应参数再提交。命令处理结果应显示为DSH命令记录；普通聊天中的模型总结不能代替插件运行记录和报告。

## 文件用例与 CSV 参数化

第一次使用 CSV，先看[CSV 参数文件使用手册](CSV参数文件使用手册.md)：可直接复制完整示例，并逐项了解列名、占位符、引号、空值和审核操作。

```text
/test-run examples/gitlab/login-page.txt
/test-run .local/gitlab/本次标记/api.md
/test-plan --file .local/gitlab/本次标记/ui_filters.md
/test-data .local/gitlab/本次标记/pagination.csv --file examples/gitlab/pagination-parameterized.md
```

以上示例逐条运行。后面三条先按[GitLab 指导文档](GitLab测试要求与本地调试.md)准备数据并填写 CSV，使用真实生成目录替换“本次标记”；公开网页/接口模板中的占位参数不能直接执行。文件均为 UTF-8，可用引号包裹含空格的路径。文件入口按发起命令的当前对话工作区解析；没有工作目录信息的历史会话才回退到插件配置的 `workspace`。

例如，先把 `/你的目录/DSH-Testing` 添加到 DSH，在这个工作区内新建或打开对话，并把 `ui.md` 放在目录根部。`/test-run ui.md` 与 `/test-run /你的目录/DSH-Testing/ui.md` 均读取这一个文件。仅添加其他工作区不会改变原对话的目录；应进入目标工作区的对话。绝对路径也必须位于当前对话工作区内；上级目录和指向外部的符号链接仍会被拒绝。文件找不到时，错误会给出实际查找路径和工作区，先核对这两个位置。

`/test-plan --file` 和 `/test-data` 的 CSV、用例文件遵循同一规则。TXT 每个非空行一条用例；Markdown（`.md` 或 `.markdown`）最外层列表项各一条，有序、无序均可，嵌套列表、表格和代码块留在所属用例内。列表外说明作为共享背景展示，不另算用例；代码块中的列表不算用例。完整示例见上述文件。

CSV 首行为参数名，例如：

```csv
base_url,project_id,page,expected_count
http://127.0.0.1:8929,<本次接口项目ID>,1,1
http://127.0.0.1:8929,<本次接口项目ID>,4,0
```

先把 `<本次接口项目ID>` 换成当前准备的接口项目数字 ID；每个用例依次使用全部数据行。一条分页模板配两行数据得到两个实例，指导文档的完整四行得到四个实例。`${project_id}` 等占位符按列名替换，支持重复引用，不执行表达式、不递归替换参数值里的占位符。CSV 支持带引号的逗号、换行和转义双引号；参数值保留前导零、空字符串和空格。空白行忽略，合法空字段记录保留。缺失参数列、重复/空表头、列数错误、无数据会在启动前提示；额外列保留供审核。

`/test-data` 始终进入原生 plan 模式。审核页列出原始命令、来源文件、原始用例数、CSV 数据行数、执行实例总数，以及每个实例的来源用例、数据行、所有参数、完整展开任务、拆分思路和步骤。模型不能删除或合并导入实例，也不能替你修改 CSV 值。可要求修改文字步骤并重新审核；更改用例文件或 CSV 后，应取消当前草案并重新提交，因为本次运行使用读取快照。

批准前不访问目标。批准后仍在同一对话逐实例串行执行，工具参数和定位留到当前步骤决定。报告按实例统计，支持按来源用例、数据行筛选；“用例来源与参数”展示对应原文、参数和展开任务。报告下载的计划保留完整输入快照；运行目录额外包含 `input.json`。原始输入与运行分析分别保留。

## 在当前对话查看执行过程

新建会话后可直接输入 `/test <任务与预期>`，无需先发送普通聊天。命令把真实任务提交给当前 Agent，会话由 DSH 正常保存和命名。执行过程就是普通对话：计划说明、浏览器调用、工具结果、审批、追问和最终总结均保留在本会话中。已完成工具可能按宿主默认行为折叠，可点击展开或查看“轨迹”。

`/test` 只把用户描述拆解为文字步骤和检查点，不在规划时指定工具、选择器、能力类型、输出Schema、字段路径或比较器。`/test-run <文件路径>` 读取文字文件后在当前对话规划执行。测试模式只作用于发起会话，结束后撤销，普通后续聊天不受测试工具约束。其他新会话不会出现历史报告浮层。

点击原生“停止生成”按钮停止业务动作；在途结算后，本会话会出现原生收尾轮次，执行冻结的清理，最后给出取消或错误结果及报告。不能证明在途结算时不运行清理，而是封存结果并隔离共享环境。

### 步骤进度、耗时与实时画面

输入区上方突出当前步骤，显示运行阶段、已结算数量和实际耗时；点击“查看全部步骤（数量）”可展开整个批次的滚动列表，点击条目可看完整文字、检查点和原因。规划中没有步骤时显示待确定状态，等待审核时不高亮尚未执行的第一步。“已结算”不是通过比例，时间包含模型思考和人工等待，结束后停止计时。列表底部的“查看准备、清理及完整详情”打开原生侧边栏；会话标题旁的“测试进度”入口仍可使用，原生审核接管输入区时也能查看详情。折叠、长文字和多实例编号见[执行步骤与进度显示](执行步骤与进度显示.md)。

下图正在打开 GitLab 登录页。“0 / 2 步已结算”表示本轮两步尚未结算，右侧是整轮耗时，操作文字下面是本步耗时；后面的控件检查会复用页面观察。

![GitLab 登录页检查：当前第一步、0/2 步已结算、总耗时与本步耗时](images/GitLab当前步骤.png)

点击“查看全部步骤”后可以看到完整列表。下图是运行结束后的列表，每一步都有状态和用时；步骤多时在列表内滚动查看。

![GitLab 登录页检查完成后的完整步骤列表，展示步骤名称、状态和耗时](images/GitLab完整步骤.png)

配置 [浏览器实时预览](../deployment/安装与运维.md#浏览器实时预览可选) 后，只有当前测试页面 CDP 可达且 Browscreen 有有效首帧时，才自动出现“浏览器实时画面”浮窗。纯 API、未配置或没有 CDP 的任务不会出现空浮窗；此功能不增加 App 测试支持。画面只读，浏览器仍可无头运行。按钮显示“隐藏实时画面”时，点击即可关闭画面；变为“显示实时画面”后，再点击即可重新打开。同一对话最多显示一个画面浮窗。使用浮窗自身的关闭按钮也会同步按钮状态，本轮不会反复自动弹出；测试结束自动关闭。

下面展示完整 DSH 页面：实时浮窗叠加在对话页面上，执行记录和输入框上方的步骤列表仍然可见。浮窗里是测试浏览器实际打开的页面，底部显示帧编号和采集时间；可以拖动标题栏移动窗口，拖动右下角调整大小。

![完整 DSH 页面：实时浮窗展示 GitLab 登录页，同时可见原始规划、调用、步骤与耗时](images/GitLab浏览器实时画面.png)

首次使用，到“设置 → 测试插件 → 浏览器预览与录像”勾选启用、检测安装、选择浏览器并保存。配置一次后，正常输入测试命令即可。逐项填写方法见[配置指南](浏览器实时预览一步一步配置.md#3-进入设置检测并保存)。

![浏览器实时预览设置：启用、检测安装、采集端口、Playwright 浏览器和保存按钮](images/浏览器实时预览设置.jpg)

当前只支持单活动页面；多标签时停用画面，以免显示错误目标。服务断连或截图失败时给出连接状态，不把旧图片冒充实时画面。预览失败只影响展示，不把测试改为失败，也不延长已有执行预算。

### 浏览器操作录像

0.12.3 支持 Browscreen 0.3.x 录像。先安装 `browscreen[video]==0.3.0`，在“设置 → 测试插件 → 浏览器预览与录像”勾选“录制浏览器操作视频”并保存。开关独立于实时预览，默认关闭；四个测试命令共用此设置，关闭浮窗或网页后仍录制，宿主服务需保持运行。

测试结束后，在报告选择对应浏览器实例，点击“操作录像”，播放、拖动时间轴或下载 MP4。每个实例保留自己的片段；接口实例没有视频入口、截图对话框或空媒体占位。依赖或收尾失败时给出提示，不修改业务断言。详细安装步骤、部分录像说明和完整目录离线保存见[浏览器录像与报告](浏览器录像与报告.md)。

## 先审核再执行

```text
/test-plan 访问 http://127.0.0.1:8929/users/sign_in，断言页面存在用户名输入框、密码输入框和 Sign in 登录按钮
```

需要宿主已启用 `dsh-plan-mode` 和原生用户审核通道。插件通过官方 `commands.execute(agent, "/plan", ...)` 进入 plan 模式，仍在当前对话分析描述；规划阶段禁止浏览器、API和命令执行。

模型先用 `test_submit_plan` 保存草案，再通过原生 `exit_plan_mode` 展示“计划待审”卡片。点击“查看全文”审核业务短句及文字检查点；选择“要求修改”后在对话中输入修改意见，模型更新草案并重新展示审核。只有批准当前草案才冻结为 `plan.json` 并开始执行；直接关闭 plan 模式不能跳过审核。等待审核不计入执行超时，原生“停止生成”按钮可以取消，取消前未执行则不派发清理工具。

下面是 GitLab 登录页检查的实际计划全文：先看原始任务，再对照拆分思路、操作步骤和每步检查点。

![GitLab 登录页检查的原生计划全文：任务、拆分思路、步骤和文字检查点](images/GitLab计划全文.png)

看完后，在原生“计划待审”卡片点击“同意执行”；需要调整时点击“要求修改”。仅查看全文不会开始访问网页。

![GitLab 用例的原生计划待审卡片：查看全文、要求修改和同意执行](images/GitLab计划审核.png)

`/test` 保持生成计划后直接执行。`/test-run` 读取 TXT、Markdown 后通报文字计划并执行。三种入口都复用相同采集、断言、账本和报告链路。

## 文字规划与逐步执行

例如“打开 GitLab 登录页，检查用户名输入框、密码输入框和 Sign in 按钮”可拆为：

1. 访问本机 GitLab 登录页。
2. 采集登录表单，检查三个控件都存在。

规划通报和审核卡片按“原始任务、拆分思路、步骤清单”展示。原始任务由插件保留，拆分思路用一两句说明动作顺序和检查目的，方便对照；不展开详细推理。网站结构、点击位置、请求参数、输出字段和比较器在执行到当前步骤时再分析，不要求用户提前知道未知页面细节。

模型用 `test_define_step` 设置当前步骤的能力和目标范围，不需要填写输出Schema；观察和操作页面后直接通过 `test_capture` 绑定采集位置，输出类型由采集方式自动登记。纯API可直接收集完整响应对象。当前步骤的每个文字检查点用 `test_bind_check` 关联可信观察和比较器，预期仍来自原文和文字清单。检查可以复用前一步观察，不重复发送请求。每项检查都要有程序计算结果，不能只口头判定通过。

原始文字计划保留在 plan.json，具体执行定义保存在实例的 effective_steps，账本记录 step_defined、capture_configured、check_bound。报告可展开“原始文字步骤与检查点”对照实际执行记录。`/test-plan` 审核文字后执行，`/test` 直接执行，原始输入与本次运行分析分别保留。

## 纯接口测试示例

```text
/test-run .local/gitlab/本次标记/api.md
```

先运行 `pnpm gitlab:prepare`，再使用终端打印的真实目录替换“本次标记”。文件中的三条接口用例向本机 GitLab 发送 GET，检查专用项目身份、Issue 分页及预期 404。每次响应可供多个检查复用，无需为每个检查重复请求。不调用 Playwright，不初始化浏览器，也不产生浏览器截图；附件保留接口响应。当前接口采集支持 GET JSON，不支持 POST 或自定义请求体。

## 查看测试报告

最终回复会提供 **查看测试报告** 链接与完整保存位置，链接指向本机 DSH 的 HTTP 端口，可直接在浏览器查看。报告是静态 HTML：直接打开 `artifacts/runs/<运行ID>/report.html` 也能查看，不需要专门报告服务。复制整个运行目录可保留相对路径证据附件。

报告需要重新生成时：

1. 当前运行结束后，在进度区或完整详情中点击“重建报告”，完成后点击“查看重建报告”。
2. 想找旧运行时，进入“设置 → 测试插件 → 测试报告”。
3. 填写实际运行 ID，例如报告中的 `run-…`。留空时只使用当前所选对话的报告，绝不回退到另一个对话的最近报告。
4. 点击“重建报告”，等待“查看重建报告”链接出现后打开。运行 ID 可从原报告或输出目录名称中找到。

仍在执行的测试不能重建。中断记录可按已保存事实重建，会明确标记不完整，不会补执行步骤。重建不调用模型或业务工具，原记录不被覆盖，生成 `report-rebuilt.html`、`results-rebuilt.json`、`actual-steps-rebuilt.json` 和 `manual-cases-rebuilt.md`。

网页访问复用 DSH 登录保护，服务关闭后 HTTP 链接不可用，但本地 HTML 仍可打开。无 Web 服务时保留本地路径。若通过远程代理访问 DSH，请将报告链接的本机地址替换为实际 DSH 地址，报告路径保持不变。

## 动态检查、扩展与结果

模型可通过test_propose_checkpoint提交已有来源支持的追加断言，必须显式列出适用实例、required、插入边界和post_hoc。只允许向未终结实例的未来边界追加，不可改原步骤；新增来源、业务写动作或扩权需要重新提交经确认的计划。实例记录自身有效修订和必需集合，已结束实例不追溯改判。

其他插件沿用 DSH 官方事件、工具及审批扩展点；0.3.0 不再暴露旧独立执行器的 `testRunner.hook`。

报告按准备/业务/清理展示清晰步骤，包含实际/预期、来源操作数ID、工具调用、附件摘要。可按case、data和状态筛选。必要断言FAIL与必要清理ERROR会同时保留，主状态取ERROR。未开始的取消实例仍计入总数。

## 实际步骤与手工用例

新运行自动保存每个浏览器业务操作的简短说明和真实调用；每个用例/数据实例单独从 1 编号，重试与失败保留。报告有记录时默认显示“实际步骤”，可下载当前实例或完整批次的运行记录与 Markdown 手工用例。准备和业务收尾另列，插件自动复位关闭不占编号；纯接口记录请求与检查，不出现浏览器媒体。运行报告中未定义的中间预期标明待补充。手工 Markdown 只保留名称、用户原文、前置、实际步骤和收尾；步骤中合并真实数据与地址，没有预期时留空，不含本轮状态、证据或实际结果。详见[实际步骤与手工用例](实际步骤与手工用例.md)。

## 查看报告

报告默认打开“测试用例”：左侧按名称、用例、数据集和状态筛选，右侧有新增记录时默认打开实际步骤，也可切换原步骤、断言和附件。步骤可展开工具调用和采集调整记录；断言中的“查看证据”跳转到本次实际响应或截图。概览按真实用例状态统计，并区分断言通过数与已执行数；取消、阻塞及未执行不会计为通过。运行信息包含起止时间、配置与原始数据入口。总耗时包含规划，步骤耗时为步骤时间之和，两者用途不同。

下图是 GitLab Markdown 接口集合实际生成的报告：顶部看三个实例的结果，左侧选择用例，右侧查看实际操作及检查。

![GitLab 接口报告：三例通过、实际步骤、总耗时、断言和附件入口](images/GitLab接口测试报告.png)

切换到“断言”，可以看到项目搜索的 HTTP 状态码、响应数量、ID、路径及可见性的实际值与预期。点击“查看证据”继续核对采集依据，不能只看模型的一句“通过”。

![GitLab 项目搜索断言：实际值、固定预期、比较结果和证据入口](images/GitLab接口断言.png)

报告按调用身份和下载内容保存一份内嵌数据，展开时显示完整脱敏依据；截图继续内嵌，可放大及下载。事件账本改为独立 events.jsonl 文件并流式下载，不再压缩后重复内嵌 HTML；提供原始账本下载，不生成新的压缩下载文件。在线账本与录像沿用认证报告签发的文件专用只读地址，磁盘原件不保存票据。

离线保存请复制完整 `run-…` 目录：单独 HTML 可以查看结论、步骤、断言及内嵌截图和运行记录 JSON 下载；手工 Markdown 下载也需要独立文件，账本下载与 MP4 回放需要同目录内的原始文件。重建仍保留原件，生成独立 -rebuilt 文件。

明确的简单数字条件（如“不为0”“状态码为200”）在绑定断言时检查数值和比较器一致性，不能用数字字符串或不同预期替代。此检查不在规划阶段生成操作参数，也不是对任意自然语言的完整语义验证。

## 对话语言

模型面向用户的简短分析摘要、规划说明、步骤进度、工具调用说明、追问和最终结论，优先跟随 DSH 已保存的 `locale.preference`。宿主没有显式偏好（例如浏览器自动选择语言）时，沿用用户当前输入语言。当前中文任务默认简体中文，URL、代码、字段名和原始响应保留原样。插件通过宿主公开设置接口读取偏好，不修改 DSH 设置，也不改写历史消息。

常见断言预期在运行时直接填写原文，例如 agent 或 200，不需要 JSON 引号包装；类型由明确数字条件和可信观察确定。复杂对象或数组才使用 JSON。检查按文字清单的顺序结算，不能用动态追加检查覆盖尚未绑定的既定检查。

## 规划结束后没有执行

只有文字分析还不等于插件保存了计划。普通测试会提醒模型提交一次，提醒不重置规划预算；再次结束而未提交时，记录未执行错误并结束会话，不长期停在 0/0。需要补充信息时按原生问题提示回答；计划审核等待用户确认，不自动批准。