> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 解析报告文件

Midscene 的 HTML 报告文件记录了单个 Agent 运行过程中的完整信息，用以回放和调试。

从 v1.7.0 开始，你可以把报告文件中的原始截图和 JSON 数据提取出来，或者把报告转录为 Markdown，方便其他工具继续消费这些内容。

`split` 和 `to-markdown` 会将图片导出到 `screenshots/`，自动复用重复图片。使用导出结果中的图片路径即可。

## 示例

你可以把报告文件解析为这样一份 Markdown 文件：

```markdown
# Act - 搜索并播放 Midscene 相关的视频

- Execution start: 2026-04-08T02:13:04.795Z
- Task count: 21

## 1. Plan - 点击顶部的搜索框以激活输入
- Status: finished
- Start: 2026-04-08T02:13:04.845Z
- End: 2026-04-08T02:13:15.296Z
- Cost(ms): 10451
- Screen size: 2880 x 1536

![task-1](./screenshots/<image-1>.jpeg)

### Recorder
- #1 type=screenshot, ts=2026-04-08T02:13:15.296Z, timing=after-calling

![task-1](./screenshots/<image-2>.jpeg)

## 2. Locate - 顶部带有“李维刚的日常”占位文字的搜索输入框
- Status: finished
- Start: 2026-04-08T02:13:15.305Z
- End: 2026-04-08T02:13:15.306Z
- Cost(ms): 1
- Screen size: 2880 x 1536
- Locate center: (1489, 71)

.....
```

进一步，你可以结合 [Remotion Skill](https://www.remotion.dev/docs/ai/skills?utm_source=midscenejs) 解析这份 Markdown 文件，并生成一个个性化的回放视频。

视频生成结果如下：

<video src="https://lf3-static.bytednsdoc.com/obj/eden-cn/vhaeh7vhabf/midscene-replay.mp4" height="300" controls></video>

## 使用命令行工具解析

报告解析工具包含在各个平台的命令行工具中，例如 `@midscene/web`、`@midscene/android` 等，对应的子命令为 `report-tool`。

将报告文件提取为 JSON 格式，并导出对应截图到 `output-data` 目录：

```shell
npx @midscene/web report-tool --action split --htmlPath ./midscene_run/report/puppeteer-2026/index.html --outputDir ./output-data
```

将报告文件转换为 Markdown 格式，并输出到 `output-markdown` 目录：

```shell
npx @midscene/web report-tool --action to-markdown --htmlPath ./midscene_run/report/puppeteer-2026/index.html --outputDir ./output-markdown
```

将多个报告文件合并为一份汇总报告：

```shell
npx @midscene/web report-tool --action merge-html \
  --htmlReport ./midscene_run/report/case-a/index.html \
  --htmlReport ./midscene_run/report/case-b.html \
  --outputDir ./merged --outputName all-cases
```

每多合并一份报告就重复一次 `--htmlReport`。`--outputDir` 和 `--outputName` 都是可选项，留空时合并后的报告会写入 Midscene 默认的报告目录、并生成自动文件名。已存在同名文件时使用 `--overwrite` 进行覆盖。

## 使用 JavaScript SDK 解析

如果你希望在代码里控制报告解析，可以使用 `@midscene/core` 提供的 `splitReportFile`、`reportFileToMarkdown` 和 `mergeReportFiles`。

```ts
import {
  mergeReportFiles,
  reportFileToMarkdown,
  splitReportFile,
} from '@midscene/core';

const splitResult = splitReportFile({
  htmlPath: './midscene_run/report/puppeteer-2026/index.html',
  outputDir: './output-data',
});
console.log(splitResult.executionJsonFiles);

const markdownResult = await reportFileToMarkdown({
  htmlPath: './midscene_run/report/puppeteer-2026/index.html',
  outputDir: './output-markdown',
});
console.log(markdownResult.markdownFiles);

const mergedResult = mergeReportFiles({
  htmlPaths: [
    './midscene_run/report/case-a/index.html',
    './midscene_run/report/case-b.html',
  ],
  outputDir: './merged',
  outputName: 'all-cases',
});
console.log(mergedResult.mergedReportPath);
```

`splitReportFile`、`reportFileToMarkdown` 和 `mergeReportFiles` 的用途不同：

- `splitReportFile` 会产出“原始对象”对应的 JSON 文件（每个 execution 一个 `*.execution.json`），内容是 `ReportActionDump` 的原始结构化数据，同时会导出截图文件。返回值中的 `executionJsonFiles` 和 `screenshotFiles` 都是生成后的文件路径列表。
- `reportFileToMarkdown` 会把同一份报告转成更易读、便于给其他工具继续处理的 Markdown 文本，并导出 Markdown 里引用到的截图。返回值里的 `markdownFiles` 对应 Markdown 文件路径。
- `mergeReportFiles` 会把多份报告合并成一份汇总 HTML 报告，是 [`ReportMergingTool`](/zh/reference.md#new-reportmergingtool) 的轻量封装：会自动从每份源报告里读取 `groupName` 作为 `testTitle`/`testDescription`，省去了手工准备 `reportAttributes` 的步骤。命令行多次调用或多个测试用例产生多份报告后，使用它进行汇总最为合适。

## 关于 JSON 和 Markdown 的内容字段

解析得到的 JSON 和 Markdown 数据结构可能会随着 Midscene 版本演进而变化，请以实际转换结果为准。