# 正文提取与上层结构化处理
正文提取有两条命令，分工按**页面上有没有表格**来分：
- `extract_structured_data` 读取页面正文纯文本，并可附带链接列表。命令名称中的 structured 不表示服务会自动调用大模型生成业务 JSON。
- `extract_markdown` 把页面（或页面上某个元素）转成 Markdown，**表格按 GFM 表格输出**。
两条都不调用大模型、不做业务字段提取，也不写数据库。
## 纯文本：调用示例
```json
{
"id": 1001,
"method": "extract_structured_data",
"params": {
"query": "读取文章内容",
"extractLinks": true
}
}
```
发送到 `POST /playwright/command`。响应的 `data` 包含：
| 字段 | 当前实现 |
| --- | --- |
| `query` | 回显请求中的 query，不执行语义筛选 |
| `text` | 当前页主文档的 `document.body.innerText`，最多前 20,000 个 JavaScript 字符单元 |
| `links` | extractLinks 为 true 时返回链接文字和 href；链接文字最多前 80 个字符单元 |
接口读取当前文档，不自动翻页、不自动展开折叠内容，也不自动拼接所有 iframe 的正文。网页内容较长时，不能把此次返回当作全文。
## 对照源码
`CommandTable` 将 query 和 extractLinks 传给 `PlaywrightService.extractStructuredData(...)`。服务：
1. 获取当前任务的 Page。
2. 暂时隐藏 `playwright-highlight-container`，防止高亮编号进入正文。
3. 读取并截取 `document.body.innerText`，恢复高亮层。
4. 按需读取 `a[href]` 的文字和绝对链接。
5. 用统一响应体返回结果。
它没有模型请求、业务字段提取或数据库存储。**它也不做 HTML 到 Markdown 的转换**——需要 Markdown 时用下一节的 `extract_markdown`，那是另一条命令、另一套实现。
## 转成 Markdown：`extract_markdown`
`extract_structured_data` 的正文取自 `document.body.innerText`，而 `innerText` **按单元格把表格摊平**：表头格与数据格交替出现，列与列的对应关系只能靠位置猜，`colspan`/`rowspan` 直接丢失。在面积、金额、数量这类数字上，读出来每个数字都在，配错列却看不出来。
`extract_markdown` 返回真正的 Markdown，表格是 GFM 表格——表头一行、分隔行、数据各一行，行列关系是显式的。
```json
{
"id": 1001,
"method": "extract_markdown",
"params": {
"selector": "table.detail",
"includeLinks": false
}
}
```
| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `id` | 是 | 任务 ID |
| `selector` | 否 | CSS 选择器。**不传时转整个 ``**；给了就只转命中的**第一个**元素 |
| `frame` | 否 | 选择器落在跨域 iframe 里时指定 frame：序号，或 URL / name 子串（与 `get_element_count` 同一套取值） |
| `includeLinks` | 否 | 为 true 时另附页面链接清单，格式与 `extract_structured_data` 一致 |
| `maxChars` | 否 | 返回上限，默认 20000 个字符单元 |
响应的 `data` 包含：
| 字段 | 当前实现 |
| --- | --- |
| `markdown` | 转换后的 Markdown；超过上限时截断到 `maxChars` |
| `length` | **截断前**的全长，用它判断是不是真的读全了 |
| `truncated` | 是否被截断 |
| `source` | 这次转的是什么：`body`，或请求里给的选择器 |
| `url` / `title` | 当前页面的地址与标题，免去再单独调用一次 |
| `links` | `includeLinks` 为 true 时返回，格式同上 |
转换结果形如（对齐用的空格由转换器排版产生，不影响语义）：
```markdown
| 地类 | 面积(公顷) |
|------|----------|
| 农用地 | 187.9883 |
| 建设用地 | 2.8867 |
| 未利用地 | 0.3431 |
```
几处边界值得写清：
- **读的是 DOM，不是像素**。表格如果是图片（扫描件、`![]()
` 截图），这条命令读不到东西，要用 `get_element_screenshot` 加 `ocr_image`。
- **不自动展开折叠内容，也不拼接所有 iframe 的正文**。内容在跨域 iframe 里时传 `frame`；`selector` 为空只转该 frame 的 ``。
- **返回可能被截断**，判据是 `data.truncated` 与 `data.length`，不是「`data.markdown` 看起来到结尾了」。
- 选择器一个都没匹配到时命令失败并给出选择器原文，不会静默返回空 Markdown。
### 对照源码
`CommandTable` 读取 selector、frame、includeLinks、maxChars 并调用 `PlaywrightService.extractMarkdown(...)`：
```java
put("extract_markdown", (svc, id, a) -> svc.extractMarkdown(id, optStr(a, "selector"), optStr(a, "frame"),
optBool(a, "includeLinks"), a.getInteger("maxChars")));
```
服务侧先把 HTML 取出来——不传选择器取 `document.body.innerHTML`，传了就取命中元素的 `outerHTML`——再交给转换器：
```java
public RespBodyVo extractMarkdown(Long browserId, String selector, String frame, boolean includeLinks,
Integer maxChars) {
BrowserInstance inst = INSTANCES.get(browserId);
if (inst == null) {
return notFound(browserId);
}
int limit = maxChars == null || maxChars <= 0 ? DEFAULT_MARKDOWN_MAX_CHARS : maxChars;
try {
Frame target = frameOf(inst, frame);
String html;
String source;
if (selector == null || selector.trim().isEmpty()) {
Object body = target.evaluate("() => document.body ? document.body.innerHTML : ''");
html = body == null ? "" : String.valueOf(body);
source = "body";
} else {
Locator locator = target.locator(selector);
if (locator.count() == 0) {
return RespBodyVo.fail("extract_markdown 失败：选择器没有匹配到元素: " + selector);
}
Object outer = locator.first().evaluate("el => el.outerHTML");
html = outer == null ? "" : String.valueOf(outer);
source = selector;
}
String markdown = HtmlMarkdown.toMarkdown(html);
int length = markdown.length();
boolean truncated = length > limit;
Kv kv = Kv.by("markdown", truncated ? markdown.substring(0, limit) : markdown).set("length", length)
.set("truncated", truncated).set("source", source).set("url", inst.page.url())
.set("title", inst.page.title());
if (includeLinks) {
kv.set("links", linksIn(target));
}
return RespBodyVo.ok(kv);
} catch (IllegalArgumentException e) {
return RespBodyVo.fail("extract_markdown 失败：" + e.getMessage());
} catch (PlaywrightException e) {
return RespBodyVo.fail("extract_markdown 失败：" + briefMessage(e.getMessage()));
}
}
```
转换本身在一个与浏览器无关的工具类里，可以单独测：先用 jsoup 把 HTML 解析成规整的 DOM 并摘掉不该进正文的节点，再交给转换器。
```java
public class HtmlMarkdown {
/** 高亮层是 get_browser_state 画的,不属于页面内容,转 Markdown 前要摘掉 */
private static final String HIGHLIGHT_CONTAINER_ID = "playwright-highlight-container";
/** 这些标签里的文本是脚本/样式,不是给人读的正文 */
private static final String NON_CONTENT_SELECTOR = "script, style, noscript, template, head";
public static String toMarkdown(String html) {
if (html == null || html.isEmpty()) {
return "";
}
Document doc = Jsoup.parse(html);
doc.select(NON_CONTENT_SELECTOR).remove();
doc.select("#" + HIGHLIGHT_CONTAINER_ID).remove();
Element body = doc.body();
String source = body != null && !body.html().isEmpty() ? body.html() : doc.html();
FlexmarkHtmlConverter converter = FlexmarkHtmlConverter.builder().build();
return tidy(converter.convert(source));
}
}
```
三处非显然的取舍：
- **为什么要先过一遍 jsoup**：`