源码教程：DOM、页面状态与元素读取

    put("get_browser_state",
        (svc, id, a) -> svc.getBrowserState(id, a.getBoolean("highlight"), a.getInteger("viewportExpansion"),
            a.getBoolean("includeElements"), a.getInteger("maxElements"), a.getBoolean("includeFrames"),
            a.getBoolean("strictSnapshot")));

  public RespBodyVo getBrowserState(Long browserId, Boolean highlight, Integer viewportExpansion,
      Boolean includeElements, Integer maxElements, Boolean includeFrames, Boolean strictSnapshot) {
    return getBrowserStateAttempt(browserId, highlight, viewportExpansion, includeElements, maxElements,
        includeFrames, Boolean.TRUE.equals(strictSnapshot), 1);
  }

    put("list_frames", (svc, id, a) -> svc.listFrames(id, a.getBoolean("refresh")));

  public RespBodyVo listFrames(Long browserId, Boolean refresh) {
    BrowserInstance inst = INSTANCES.get(browserId);
    if (inst == null) {
      return notFound(browserId);
    }
    boolean rebuild = refresh == null || refresh;
    if (rebuild) {
      try {
        recordSnapshot(inst, DomService.getFrameState(inst.page, false, 0));
      } catch (PlaywrightException e) {
        return RespBodyVo.fail("list_frames 失败：读取页面 frame 失败（" + briefMessage(e.getMessage()) + "）");
      }
    }
    List<Kv> frames = frameList(inst.domState);
    if (frames.isEmpty()) {
      // 快照不是带 frame 的那种时,至少把 frame 的 URL/名称给出来,别让调用方以为「一个 frame 都没有」
      for (DomService.FrameNode node : DomService.frameTree(inst.page)) {
        Kv item = Kv.by("index", frames.size()).set("url", safeFrameUrl(node.frame))
            .set("name", safeFrameName(node.frame)).set("isMain", node.parentIndex < 0).set("depth", node.depth);
        if (node.parentIndex >= 0) {
          item.set("parentIndex", node.parentIndex);
        }
        frames.add(item);
      }
    }
    Kv data = Kv.by("count", frames.size()).set("frames", frames)
        .set("note", "index 0 是主 frame;跨域 iframe 也能读到 URL(这是识别它的主要依据)。"
            + "要读 iframe 里的元素用 get_browser_state 的 includeFrames:true");
    return RespBodyVo.ok(data);
  }

    put("get_page_snapshot", (svc, id, a) -> svc.getPageSnapshot(id, a.getBoolean("includeConsole"),
        a.getBoolean("includeRequests"), optStr(a, "requestFilter")));

  public RespBodyVo getPageSnapshot(Long browserId, Boolean includeConsole, Boolean includeRequests,
      String requestFilter) {
    BrowserInstance inst = INSTANCES.get(browserId);
    if (inst == null) {
      return notFound(browserId);
    }
    Kv kv = Kv.by("url", inst.page.url()).set("title", safeTitle(inst.page)).set("tabs", tabs(inst))
        .set("dialog", inst.lastDialog).set("loading", isPageLoading(inst));
    if (includeConsole != null && includeConsole) {
      kv.set("logs", new ArrayList<>(inst.consoleLogs));
      kv.set("errors", new ArrayList<>(inst.pageErrors));
    }
    if (includeRequests != null && includeRequests) {
      kv.set("requests", filterRequests(inst, requestFilter));
    }
    return RespBodyVo.ok(kv);
  }

    put("diff_dom_text",
        (svc, id, a) -> svc.diffDomText(id, a.getBoolean("highlight"), a.getInteger("viewportExpansion")));

  public RespBodyVo diffDomText(Long browserId, Boolean highlight, Integer viewportExpansion) {
    BrowserInstance inst = INSTANCES.get(browserId);
    if (inst == null) {
      return notFound(browserId);
    }
    String previous = inst.lastDomText;
    RespBodyVo current = buildState(inst, highlight, viewportExpansion);
    if (!current.isOk() || !(current.getData() instanceof Kv)) {
      return current;
    }
    Kv data = (Kv) current.getData();
    String text = data.getStr("text");
    Kv diff = Kv.by("url", data.get("url")).set("title", data.get("title")).set("tabs", data.get("tabs"));
    if (previous == null) {
      diff.set("first", true).set("changed", true).set("added", firstLines(text)).set("removed", new ArrayList<>());
      return RespBodyVo.ok(diff);
    }
    Map<String, Integer> before = countLines(previous);
    Map<String, Integer> after = countLines(text);
    List<String> added = new ArrayList<>();
    List<String> removed = new ArrayList<>();
    for (Map.Entry<String, Integer> entry : after.entrySet()) {
      int delta = entry.getValue() - before.getOrDefault(entry.getKey(), 0);
      for (int i = 0; i < delta && added.size() < MAX_DIFF_LINES; i++) {
        added.add(entry.getKey());
      }
    }
    for (Map.Entry<String, Integer> entry : before.entrySet()) {
      int delta = entry.getValue() - after.getOrDefault(entry.getKey(), 0);
      for (int i = 0; i < delta && removed.size() < MAX_DIFF_LINES; i++) {
        removed.add(entry.getKey());
      }
    }
    diff.set("first", false).set("changed", !added.isEmpty() || !removed.isEmpty());
    diff.set("added", added).set("removed", removed);
    return RespBodyVo.ok(diff);
  }

    put("get_interactive_map", (svc, id, a) -> svc.getInteractiveMap(id));

  public RespBodyVo getInteractiveMap(Long browserId) {
    BrowserInstance inst = INSTANCES.get(browserId);
    if (inst == null) {
      return notFound(browserId);
    }
    if (inst.domState == null) {
      // 以前这里直接失败,要求调用方「先调 get_browser_state」——多一次往返,而且很容易漏。
      // 索引本来就是本命令的产物,自己建一次快照即可(不落盘,不产生截图/文本垃圾文件)。
      RespBodyVo built = buildState(inst, false, 0);
      if (!built.isOk()) {
        return built;
      }
    }
    List<Kv> items = interactiveElements(inst);
    return RespBodyVo.ok(Kv.by("count", items.size()).set("elements", items)
        .set("source", "get_browser_state 快照(索引与 click_element_by_index / input_text / "
            + "check_element_by_index 等按索引命令共用)"));
  }

    put("get_form_state", (svc, id, a) -> svc.getFormState(id, optStr(a, "selector"), a.getBoolean("includeHidden"),
        a.getInteger("max")));

  public RespBodyVo getFormState(Long browserId, String selector, Boolean includeHidden, Integer max) {
    BrowserInstance inst = INSTANCES.get(browserId);
    if (inst == null) {
      return notFound(browserId);
    }
    JSONObject args = new JSONObject();
    args.put("selector", selector);
    args.put("includeHidden", includeHidden != null && includeHidden);
    args.put("max", max == null || max <= 0 ? 200 : max);
    Object result;
    try {
      result = inst.page.evaluate(FORM_STATE, args);
    } catch (PlaywrightException e) {
      return RespBodyVo.fail("get_form_state 失败：" + briefMessage(e.getMessage()));
    }
    if (!(result instanceof Map)) {
      return RespBodyVo.fail("get_form_state 失败：页面没有返回表单信息");
    }
    Kv data = new Kv();
    data.putAll((Map) result);
    data.set("url", safeUrl(inst.page));
    data.set("scope", selector == null || selector.isBlank() ? "document" : selector);
    return RespBodyVo.ok(data);
  }

    put("extract_structured_data",
        (svc, id, a) -> svc.extractStructuredData(id, optStr(a, "query"), optBool(a, "extractLinks")));

  public RespBodyVo extractStructuredData(Long browserId, String query, boolean extractLinks) {
    BrowserInstance inst = INSTANCES.get(browserId);
    if (inst == null) {
      return notFound(browserId);
    }
    try {
      Object text = inst.page
          .evaluate("() => {" + " const c = document.getElementById('playwright-highlight-container');"
              + " const prev = c ? c.style.display : null;" + " if (c) c.style.display = 'none';"
              + " const t = document.body ? document.body.innerText.slice(0, 20000) : '';"
              + " if (c) c.style.display = prev || '';" + " return t; }");
      Kv kv = Kv.by("query", query).set("text", text);
      if (extractLinks) {
        kv.set("links", linksIn(inst.page.mainFrame()));
      }
      return RespBodyVo.ok(kv);
    } catch (PlaywrightException e) {
      return RespBodyVo.fail("extract_structured_data 失败：" + briefMessage(e.getMessage()));
    }
  }

  /** 页面链接清单:文本截到 80 字符,`href` 用解析后的绝对地址 */
  private static Object linksIn(Frame frame) {
    return frame.evaluate("() => Array.from(document.querySelectorAll('a[href]'))"
        + ".map(a => ({text: (a.innerText || '').trim().slice(0, 80), href: a.href}))");
  }

    put("extract_markdown", (svc, id, a) -> svc.extractMarkdown(id, optStr(a, "selector"), optStr(a, "frame"),
        optBool(a, "includeLinks"), a.getInteger("maxChars")));

  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()));
    }
  }

public class HtmlMarkdown {

  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));
  }
}

    put("get_element_text", (svc, id, a) -> svc.getElementText(id, a.getInteger("index"), optStr(a, "selector"),
        Boolean.valueOf(optBool(a, "canvasOnly")), optStr(a, "frame")));

  public RespBodyVo getElementText(Long browserId, Integer index, String selector, Boolean canvasOnly,
      String frame) {
    BrowserInstance inst = INSTANCES.get(browserId);
    if (inst == null) {
      return notFound(browserId);
    }
    if ((selector == null || selector.isBlank()) && index == null) {
      return RespBodyVo.fail("get_element_text 需要 index 或 selector 之一");
    }
    Locator locator;
    String target;
    if (selector != null && !selector.isBlank()) {
      try {
        locator = locatorIn(inst, frame, selector);
      } catch (IllegalArgumentException e) {
        return RespBodyVo.fail("get_element_text 失败：" + e.getMessage());
      }
      int count = locator.count();
      if (count == 0) {
        return RespBodyVo.fail("get_element_text 没匹配到元素: 选择器 " + selector + frameSuffix(frame));
      }
      target = "选择器 " + selector + frameSuffix(frame);
    } else {
      locator = locatorOf(inst, index);
      if (locator == null) {
        return RespBodyVo.fail("get_element_text 索引越界: " + index + indexHint(inst));
      }
      target = "index=" + index;
    }
    Kv data = new Kv();
    data.set("target", target);
    String text;
    try {
      text = locator.innerText();
      data.set("text", text);
    } catch (PlaywrightException e) {
      return RespBodyVo.fail(actionFailure("get_element_text", e));
    }
    if (Boolean.TRUE.equals(canvasOnly) && (text == null || text.isBlank())) {
      Boolean onlyCanvas = null;
      try {
        Object raw = locator.evaluate("el => { if (!el.querySelector) return null;"
            + " const canvases = el.tagName === 'CANVAS' ? [el] : Array.from(el.querySelectorAll('canvas'));"
            + " if (!canvases.length) return false;"
            + " const textish = Array.from(el.querySelectorAll('*')).filter(n => n.children.length === 0"
            + " && (n.textContent || '').trim().length > 0).length;"
            + " return textish === 0; }");
        onlyCanvas = raw instanceof Boolean ? (Boolean) raw : null;
      } catch (PlaywrightException e) {
        // 诊断取不到不算失败:文字那一段已经如实返回了
        onlyCanvas = null;
      }
      if (onlyCanvas != null) {
        data.set("canvasOnly", onlyCanvas);
        if (Boolean.TRUE.equals(onlyCanvas)) {
          data.set("hint", "这个元素里的内容画在 <canvas> 上(图表 / 地图 / 看板),没有文字节点:"
              + "innerText 必然是空的。改走像素手段(截图后用 OCR),"
              + "或去读同一页面上**同时是文字**的地方(图例、数据面板、十字线浮标对应的 DOM 文本)");
        }
      }
    }
    return RespBodyVo.ok(data);
  }

    put("get_element_html", (svc, id, a) -> svc.getElementHtml(id, reqInt(a, "index")));

  public RespBodyVo getElementHtml(Long browserId, int index) {
    return read(browserId, index, "get_element_html", "html", (locator) -> locator.innerHTML());
  }

    put("get_element_value", (svc, id, a) -> svc.getElementValue(id, reqInt(a, "index")));

  public RespBodyVo getElementValue(Long browserId, int index) {
    return read(browserId, index, "get_element_value", "value", (locator) -> locator.inputValue());
  }

    put("get_element_attribute", (svc, id, a) -> svc.getElementAttribute(id, reqInt(a, "index"), reqStr(a, "name")));

  public RespBodyVo getElementAttribute(Long browserId, int index, String name) {
    return read(browserId, index, "get_element_attribute", "value", (locator) -> locator.getAttribute(name));
  }

    put("get_element_listeners", (svc, id, a) -> svc.getElementListeners(id, a.getInteger("index"),
        optStr(a, "selector"), optStr(a, "frame")));

  public RespBodyVo getElementListeners(Long browserId, Integer index, String selector, String frame) {
    BrowserInstance inst = INSTANCES.get(browserId);
    if (inst == null) {
      return notFound(browserId);
    }
    if ((selector == null || selector.isBlank()) && index == null) {
      return RespBodyVo.fail("get_element_listeners 需要 index 或 selector 之一");
    }
    Locator locator;
    String target;
    if (selector != null && !selector.isBlank()) {
      try {
        locator = locatorIn(inst, frame, selector);
      } catch (IllegalArgumentException e) {
        return RespBodyVo.fail("get_element_listeners 失败：" + e.getMessage());
      }
      target = "selector=" + selector + frameSuffix(frame);
    } else {
      locator = locatorOf(inst, index);
      target = "index=" + index;
      if (locator == null) {
        return RespBodyVo.fail("get_element_listeners 索引越界: " + index + indexHint(inst));
      }
    }
    Kv probe;
    Frame probeFrame = null;
    String elementScript;
    try {
      if (locator.count() == 0) {
        return RespBodyVo.ok(Kv.by("found", false).set("target", target)
            .set("note", "没找到这个元素:选择器/索引可能已经过期,重新 get_browser_state 再试"));
      }
      // CDP 的权威探测需要 frame 与本元素的解析表达式;拿不到就退回启发式,并把结论标成「未知」
      if (selector != null && !selector.isBlank()) {
        probeFrame = frame == null || frame.isBlank() ? inst.page.mainFrame() : frameOf(inst, frame);
      } else {
        probeFrame = frameForIndex(inst, inst.domState, index);
        if (probeFrame == null) {
          probeFrame = inst.page.mainFrame();
        }
      }
      elementScript = elementResolveScript(inst, index, selector);
      probe = ListenerProbe.probe(locator, probeFrame, elementScript);
    } catch (IllegalArgumentException e) {
      return RespBodyVo.fail("get_element_listeners 失败：" + e.getMessage());
    } catch (PlaywrightException e) {
      return RespBodyVo.fail("get_element_listeners 失败：" + briefMessage(e.getMessage()));
    }
    if (!Boolean.TRUE.equals(probe.getBoolean("found"))) {
      return RespBodyVo.ok(Kv.by("found", false).set("target", target)
          .set("note", "没找到这个元素:选择器/索引可能已经过期,重新 get_browser_state 再试"));
    }
    Kv data = Kv.by("found", true).set("target", target).set(probe);
    String note = ListenerProbe.note(probe);
    if (note != null) {
      data.set("note", note);
    }
    return RespBodyVo.ok(data);
  }

    put("get_element_count", (svc, id, a) -> svc.getElementCount(id, reqStr(a, "selector"), optStr(a, "frame")));

  public RespBodyVo getElementCount(Long browserId, String selector, String frame) {
    BrowserInstance inst = INSTANCES.get(browserId);
    if (inst == null) {
      return notFound(browserId);
    }
    try {
      return RespBodyVo.ok(Kv.by("count", frameOf(inst, frame).locator(selector).count()));
    } catch (IllegalArgumentException e) {
      return RespBodyVo.fail("get_element_count 失败：" + e.getMessage());
    } catch (PlaywrightException e) {
      return RespBodyVo.fail("get_element_count 失败：" + briefMessage(e.getMessage()));
    }
  }

    put("get_element_box", (svc, id, a) -> svc.getElementBox(id, reqInt(a, "index")));

  public RespBodyVo getElementBox(Long browserId, int index) {
    BrowserInstance inst = INSTANCES.get(browserId);
    if (inst == null) {
      return notFound(browserId);
    }
    Locator locator = locatorOf(inst, index);
    if (locator == null) {
      return RespBodyVo.fail("get_element_box 索引越界: " + index + indexHint(inst));
    }
    try {
      BoundingBox box = locator.boundingBox();
      if (box == null) {
        return RespBodyVo.fail("get_element_box 失败：元素不可见或没有布局信息");
      }
      return RespBodyVo.ok(Kv.by("x", box.x).set("y", box.y).set("width", box.width).set("height", box.height));
    } catch (PlaywrightException e) {
      return RespBodyVo.fail(actionFailure("get_element_box", e));
    }
  }

    put("is_visible", (svc, id, a) -> svc.isVisible(id, reqInt(a, "index")));

  public RespBodyVo isVisible(Long browserId, int index) {
    return read(browserId, index, "is_visible", "visible", (locator) -> locator.isVisible());
  }

    put("is_enabled", (svc, id, a) -> svc.isEnabled(id, reqInt(a, "index")));

  public RespBodyVo isEnabled(Long browserId, int index) {
    return read(browserId, index, "is_enabled", "enabled", (locator) -> locator.isEnabled());
  }

    put("is_checked", (svc, id, a) -> svc.isChecked(id, reqInt(a, "index")));

  public RespBodyVo isChecked(Long browserId, int index) {
    return read(browserId, index, "is_checked", "checked", (locator) -> locator.isChecked());
  }