数据截至 2026-08-18(上游 commit 24a14b76e14a)

给模型装眼睛:DOM 树 → 带编号的可交互元素清单

30 秒导读: LLM 读不懂一张渲染出来的网页,它只会读文本。这一章讲 Nanobrowser 怎么把一整棵活的 DOM 树"翻译"成模型能读的一小段文本——一份形如 [5]<button>Submit /> 的带编号可交互元素清单。那个编号 highlightIndex 是全章的主角:它是模型与真实 DOM 之间的桥接编号,模型只要说"点 5 号",系统就能凭编号找回那个真实的 <button>。

本章只讲感知:页面怎么变成文本。至于模型说了"点 5 号"之后,点击/输入如何真正落到那个元素上,是下一章的事;注入进页面的那段文本如何被安全包裹(防提示注入),留给第 4 章。

1. 这是什么(零基础也能懂)

一句话定义

感知层 = 给模型装眼睛。 它把浏览器里一张活生生的网页,压缩成一段模型读得懂的纯文本清单,并给每个"能点/能填"的元素编上号。

它要解决的问题

想象你要让 AI 去操作一个网页。网页在浏览器里是一棵庞大的 DOM 树——几千个节点、样式、脚本、看不见的容器。可 LLM 的输入只是文本,它:

看不到渲染后的画面(纯文本模型没有像素);
就算把整段 HTML 塞给它,也太长(几十万 token,烧钱又超窗口),而且噪音太大(布局 div、隐藏节点、追踪脚本全混在一起)。

所以需要有人先替模型"看一眼",把页面里真正能交互的东西挑出来,排成一份短清单。这份清单要满足两个矛盾的要求:够短(省 token)、又够全(别漏掉按钮)。

用起来什么样

模型最终读到的不是 HTML,而是这样一段东西(简化示例):

[Start of page]
[0]<a href=/home>Home />
[1]<button type=submit>Search />
[2]<input placeholder=Search... />
	Some plain text that is not clickable
[3]<a>Sign in />
[End of page]

每行开头的 [数字] 就是 highlightIndex。模型想搜索,就输出一个动作 { click_element: { index: 1 } }——它永远只跟编号打交道,从不碰真实的 DOM 节点。

一句话直觉

把它当成"给盲人报菜单": 服务员(感知层)把一整桌看不见的菜(DOM),念成一份带序号的菜单("1 号红烧肉、2 号青菜……")。顾客(LLM)只说"我要 2 号",服务员再凭"2 号"去端那盘真菜。序号就是盲人和真菜之间唯一的桥。

2. 顶层全景(它大概怎么转)

主线:从一棵 DOM 到一段文本

整条流水线跨越两个世界:页面世界(注入进网页里跑的 JS)和 后台世界(扩展的 service worker 里跑的 TypeScript)。数据在两界之间以一份"扁平 JSON"传递。

后台世界 (TypeScript)                     页面世界 (注入的 JS)
─────────────────────                     ────────────────────
getClickableElements()
   │
   ├─ injectBuildDomTreeScripts() ──注入──► buildDomTree.js
   │                                            │
   │  chrome.scripting.executeScript ──调用──► window.buildDomTree(args)
   │                                            │  遍历 document.body
   │                                            │  · 判定可交互 → 发 highlightIndex
   │                                            │  · (可选) 在页面上画高亮框
   │                                            ▼
   │  ◄──────── 返回扁平 JSON {rootId, map} ────┘
   ▼
_constructDomTree()   把扁平 map 重建成对象树
   │                  同时填 selectorMap: {highlightIndex → 节点}
   ▼
DOMState { elementTree, selectorMap }
   │
   ▼
clickableElementsToString()   把树渲染成 [index]<tag …/> 文本
   │
   ▼
buildBrowserStateUserMessage()  拼上 scroll/tab 信息, 包裹后送给 LLM

怎么读这张图: 从上往下是一次感知的完整流程。左半边(后台 TypeScript)负责调度和重建,右半边(页面 JS)负责真正接触 DOM。中间那根"返回扁平 JSON"是两个世界唯一的接缝——因为注入脚本和后台不能直接共享对象,只能传可序列化的 JSON。

部件一句话职责

部件	干什么	在哪个文件
`getClickableElements`	感知层对外的入口,返回 `DOMState`	`browser/dom/service.ts:93`
`buildDomTree.js`	注入页面、遍历真实 DOM、分配 `highlightIndex`、可选画高亮	`chrome-extension/public/buildDomTree.js:1`
`_constructDomTree`	把页面返回的扁平 JSON 重建成对象树,并填 `selectorMap`	`browser/dom/service.ts:408`
`DOMElementNode`	树里每个元素节点的类,承载 `highlightIndex` 等状态	`browser/dom/views.ts:68`
`clickableElementsToString`	把树渲染成 `[index]<tag attrs>text />` 文本(省 token 的核心)	`browser/dom/views.ts:210`
`selectorMap`	`Map<highlightIndex, 节点>`——编号回查真实节点的桥	`browser/dom/views.ts:559`
`buildBrowserStateUserMessage`	把元素清单 + 滚动信息 + tab 列表拼成给 LLM 的 state 消息	`agent/prompts/base.ts:29`

桥接编号:highlightIndex 是什么

在往下钻之前先钉死一个概念,后面全靠它:

highlightIndex 是模型与真实 DOM 之间的桥接编号。 它在两个地方各出现一次,把两个世界缝在一起:

在给模型的文本里,它是每行开头的 [5]——模型能读、能引用的唯一句柄;

在 selectorMap 里,它是 key——系统凭它 selectorMap.get(5) 拿回真实的 DOMElementNode。

模型永远不知道 xpath、CSS selector 这些"真地址",它只认这个整数。真地址是系统的事(03 章用它去点击)。

3. 核心原理(逐个机制,由浅入深)

3.1 把脚本注入页面:两个世界怎么通信

要解决的小问题: 后台的 TypeScript 想遍历页面 DOM,但它跑在 service worker 里,根本碰不到网页的 document。怎么办?

思路: 把一段 JS 注入到目标标签页里去跑。那段 JS 能直接访问 document,遍历完把结果序列化成 JSON 传回后台。这就是 buildDomTree.js 存在的理由——它是"派到页面里的侦察兵"。

先看入口。_buildDomTree 对 about:blank/chrome:// 这类特殊页直接返回一棵空 body(省事、也点不了),否则先注入脚本、再执行它:

// browser/dom/service.ts:136 —— 先注入,再在页面上下文里调用它
await injectBuildDomTreeScripts(tabId);

const mainFrameResult = await chrome.scripting.executeScript({
  target: { tabId },
  func: args => window.buildDomTree(args),  // 在页面里跑
  args: [{ showHighlightElements, focusHighlightIndex: focusElement,
           viewportExpansion, startId: 0, startHighlightIndex: 0, debugMode }],
});

injectBuildDomTreeScripts(service.ts:596)不傻注:它先用 scriptInjectedFrames(service.ts:582)检查 window.buildDomTree 是否已经存在,只往还没注入的 frame 注,避免重复注入和重复高亮。

注入脚本本身把自己挂到 window.buildDomTree 上(buildDomTree.js:1),接收一组参数——其中 startId 和 startHighlightIndex 是为跨 iframe 拼接预留的起始计数器(见 §3.5)。

关键细节: 注入脚本的返回值必须是纯 JSON(可序列化)。所以它绝不能返回真实 DOM 节点对象,只能返回一份"扁平字典" { rootId, map }——map 里每个节点用字符串 id 互相引用(children: ["3","4"]),而不是对象指针。重建成真正的对象树是后台的活(§3.4)。

3.2 哪些元素算"可交互",谁配得到编号

要解决的小问题: 一个页面几千个节点,只有一小撮是"能点能填"的。怎么判定,并且只给它们发编号?

思路: 遍历每个元素时,层层过滤。核心判定链在页面脚本里:

// buildDomTree.js:1384 —— 只有可见 + 顶层(或菜单容器)才检查可交互
nodeData.isVisible = isElementVisible(node);
if (nodeData.isVisible) {
  nodeData.isTopElement = isTopElement(node);        // 没被别的元素盖住
  const role = node.getAttribute('role');
  const isMenuContainer = role === 'menu' || role === 'menubar' || role === 'listbox';
  if (nodeData.isTopElement || isMenuContainer) {
    nodeData.isInteractive = isInteractiveElement(node);   // 真能交互吗
    nodeWasHighlighted = handleHighlighting(nodeData, node, parentIframe, isParentHighlighted);
  }
}

isInteractiveElement(buildDomTree.js:541)是个厚重的判定器:标签白名单(button/a/input…)、role、可交互的鼠标指针样式(doesElementHaveInteractivePointer,buildDomTree.js:611)、甚至尝试用 getEventListeners 探测有没有绑定事件监听器(buildDomTree.js:735)。重点看: 它想尽办法回答"人能不能点它",而不只看标签名。

真正发号在 handleHighlighting。 这里藏着两个关键的"省号"规则:

// buildDomTree.js:1183 —— 谁配得到 highlightIndex
function handleHighlighting(nodeData, node, parentIframe, isParentHighlighted) {
  if (!nodeData.isInteractive) return false;         // ① 不可交互,直接不发号

  let shouldHighlight = false;
  if (!isParentHighlighted) {
    shouldHighlight = true;                            // 父节点没被高亮 → 我可以高亮
  } else {
    // ② 父节点已经高亮了:只有我是"独立的交互"才另发号(否则父子重复)
    shouldHighlight = isElementDistinctInteraction(node);
  }

  if (shouldHighlight) {
    nodeData.isInViewport = isInExpandedViewport(node, viewportExpansion);
    if (nodeData.isInViewport || viewportExpansion === -1) {   // ③ 只给视口内的发号
      nodeData.highlightIndex = highlightIndex++;      // ← 发号!编号自增
      // …可选:在页面上画高亮框
    }
  }
  return false;
}

三条"省号"规则,直接决定了清单的干净程度:

规则	效果	位置
不可交互不发号	布局 div、纯文本不进清单	`buildDomTree.js:1184`
父已高亮 + 子非独立交互 → 子不发号	避免一个链接里外层 `<a>` 和内层 `<span>` 都发号	`buildDomTree.js:1192`
视口外不发号(除非 `viewportExpansion === -1`)	只报当前看得见的,清单随滚动而变	`buildDomTree.js:1206`

关键细节: 编号是遍历顺序(DFS,基本对应视觉从上到下)递增的,highlightIndex++。所以同一个页面不滚动、不变化,编号是稳定的;一旦页面变了,编号会重排——这也是为什么每一步都要重新感知,不能缓存旧编号。

3.3 DOMElementNode:承载编号的节点

要解决的小问题: 后台需要一个类来表示"树里的一个元素",既装 DOM 信息,又装感知层加的状态(编号、是否在视口、是否是新出现的)。

DOMElementNode(views.ts:68)就是这个类。它的字段里,和感知直接相关的是:

字段	含义
`tagName` / `attributes`	标签名和属性(渲染清单时用)
`highlightIndex`	桥接编号;`null` 表示这个节点没进清单
`isInteractive` / `isTopElement` / `isInViewport`	上一节那三道判定的结果
`children` / `parent`	树结构指针
`isNew`	这个可交互元素相对上一步是不是新出现的

isNew 是个有意思的设计——源码注释直说了它的用意:

// views.ts:86 —— isNew 用来告诉模型"状态怎么变了"
/*
### State injected by the browser context.
The idea is that the clickable elements are sometimes persistent from the
previous page -> tells the model which objects are new/_how_ the state has changed
*/
isNew: boolean | null;

渲染时,新元素前缀会带个 *(*[5]<…>),让模型一眼看出"这个是这一步才冒出来的"(见 §3.4 的 highlightIndicator)。

3.4 clickableElementsToString:把树压成省 token 的文本

要解决的小问题: 有了对象树,怎么渲染成那份又短又全的清单?这是整章工程含量最高的一步,核心是省 token。

思路: 深度优先遍历这棵树,只为有 highlightIndex 的节点输出一行;其余节点只贡献它们的可见文本。看主循环:

// views.ts:224 —— 只有带 highlightIndex 的节点才生成一行
if (node.highlightIndex !== null) {
  const text = node.getAllTextTillNextClickableElement();   // 收集它自己的文字
  // …组装 attributesHtmlStr(见下)…
  const highlightIndicator = node.isNew ? `*[${node.highlightIndex}]` : `[${node.highlightIndex}]`;
  let line = `${depthStr}${highlightIndicator}<${node.tagName}`;
  if (attributesHtmlStr) line += ` ${attributesHtmlStr}`;
  if (text) line += `>${trimmedText}`;
  line += ' />';                                             // 收尾,注释说这是"1 token"
  formattedText.push(line);
}

一行的格式就是 [缩进][index]<tag 属性>文本 />。depthStr 用制表符表示层级,让模型能感知嵌套关系。

取文本的巧思: getAllTextTillNextClickableElement(views.ts:184)收集一个可交互元素的文字时,碰到下一个带编号的子元素就停——这样父子不会重复收同一段文字。对应地,渲染纯文本节点时,若它"有一个带编号的祖先"(hasParentWithHighlightIndex,views.ts:42)就跳过,只输出那些不属于任何可交互元素的游离文本(views.ts:328)。

真正的省 token 重头戏——属性三连去噪: 属性(href、aria-label…)最占字数,所以只保留白名单里的,再做三层裁剪:

步骤	做什么	位置
白名单过滤	只保留 `DEFAULT_INCLUDE_ATTRIBUTES` 里的属性	`views.ts:5`、`views.ts:236`
值去重	多个属性值完全相同时(且长度>5),只留 `includeAttributes` 里最先出现的那个	`views.ts:241`
role 冗余去除	`role` 和标签名一样(如 `<button role=button>`)就删掉 role	`views.ts:274`
文本冗余去除	`aria-label`/`placeholder`/`title` 和元素文本一样,就删掉(别报两遍)	`views.ts:279`
单值截断	每个属性值用 `capTextLength(value, 15)` 截到 15 字符	`views.ts:292`

那段"值去重"逻辑,源码作者自己在注释里坦白它是经验之谈:

// views.ts:241 —— 相同属性值只留一个,省 token
// If value of any of the attributes is the same as ANY other value attribute
// only include the one that appears first in includeAttributes
// WARNING: heavy vibes, but it seems good enough for saving tokens

DEFAULT_INCLUDE_ATTRIBUTES(views.ts:5)本身就是精挑的一串:title/type/name/role/value/placeholder/aria-label/href 等——都是**帮模型判断"这是什么控件、干嘛用"**的高信息属性,布局用的 class/style 一律不进。

3.5 selectorMap:编号回查真实节点的桥

要解决的小问题: 模型输出"点 5 号"后,系统怎么从 5 找回那个真实的 DOMElementNode?

思路: 在重建树的同时,顺手建一张编号 → 节点的哈希表。这就是 selectorMap(类型 Map<number, DOMElementNode>,views.ts:559)。

重建发生在 _constructDomTree(service.ts:408),两趟遍历:第一趟把每个扁平 JSON 节点 _parse_node(service.ts:463)成对象,顺便登记进 selectorMap;第二趟按 children id 把父子指针连起来:

// service.ts:416 —— 第一趟:建节点,带 highlightIndex 的登记进 selectorMap
for (const [id, nodeData] of Object.entries(jsNodeMap)) {
  const [node] = _parse_node(nodeData);
  if (node === null) continue;
  nodeMap[id] = node;
  if (node instanceof DOMElementNode && node.highlightIndex != null) {
    selectorMap.set(node.highlightIndex, node);   // ← 桥的另一端在这里搭好
  }
}

到这里,桥的两端都齐了:

        给 LLM 的文本                     selectorMap (系统私有)
        ─────────────                     ───────────────────
        [5]<button>Submit />   ◄── 5 ──►  5 → DOMElementNode{tagName:'button', xpath:…}
             ▲                                        ▲
        模型能读、能引用的                     系统能凭它拿到真地址
        唯一句柄                            (xpath/CSS,交给 03 章去点)

getClickableElements 最终把 { elementTree, selectorMap } 打包成 DOMState(service.ts:109、views.ts:557)返回。至此感知完成:一份人读的文本 + 一张机读的回查表,共享同一套 highlightIndex。

3.6 跨 iframe:拼一棵完整的树

要解决的小问题: 页面里嵌了 iframe(尤其跨域的),主 frame 的脚本进不去它的 document,里面的按钮会漏掉。怎么补?

思路: 主 frame 遍历时,进不去的 iframe 会在节点上留个 error 属性。后台检测到这些"可见却加载失败"的 iframe,逐个单独注入脚本去它自己的 frame 里跑一遍,再把结果缝回主树。

关键点是编号不能撞车。所以每个子 frame 的 buildDomTree 都从"上一个 frame 用到的最大编号 + 1"开始数——这就是 startId/startHighlightIndex 参数的用途:

// service.ts:253 —— 每个子 frame 从上一个 frame 的最大编号之后继续
args: [{
  showHighlightElements, focusHighlightIndex: focusElement, viewportExpansion,
  startId: maxNodeId + 1,
  startHighlightIndex: maxHighlightIndex + 1,   // 编号接着往下,不重复
  debugMode,
}],

缝合发生在 constructFrameTree(service.ts:212):它把子 frame 的 map 并进主 map(service.ts:278),再把子 frame 的根节点 id push 进对应 iframe 节点的 children(service.ts:291)。"对应哪个 iframe 节点" 靠 _locateMatchingIframeNode(service.ts:335)按尺寸/名字/URL/标题匹配——先严格匹配,失败再退回近似匹配(service.ts:367)。

关键细节: 只对"真的失败且可见"的 iframe 补跑——_visibleIFramesFailedLoading(service.ts:388)会滤掉 1×1 的追踪 iframe 和已标记 skipped 的。加载成功的 iframe 在主 frame 那一趟就已经遍历过了,不重复处理,避免双重编号和双重高亮。

3.7 可选:在页面上画高亮框

要解决的小问题: 开发调试或开视觉模型时,想在真实网页上把每个编号可视化。

这纯属旁支副作用,不影响给模型的文本。highlightElement(buildDomTree.js:125)在页面里创建一个 id='playwright-highlight-container' 的浮层容器,给每个编号元素画一个彩框 + 一个写着编号的小标签。handleHighlighting 里当 focusHighlightIndex >= 0 时只高亮那一个(聚焦模式),否则全画(buildDomTree.js:1210)。

事后 removeHighlights(service.ts:510)按那个容器 id 和 browser-user-highlight-id 属性把它们清掉。记住:高亮是给人看的,编号才是给模型用的——两者共享同一个 highlightIndex,但没有高亮框模型照样能工作。

4. 从清单到 state 消息:拼给 LLM 的最后一步

有了 clickableElementsToString 产出的文本,还要拼上"页面的其余上下文",才是模型真正收到的一条消息。这一步在 buildBrowserStateUserMessage(agent/prompts/base.ts:29)。

它做三件事,分层拼装:

① 拿元素清单,并附上滚动信息。 滚动信息告诉模型"上面/下面还有没有内容",引导它决定要不要翻页:

// prompts/base.ts:31 —— 渲染清单 + 计算滚动百分比
const rawElementsText = browserState.elementTree.clickableElementsToString(context.options.includeAttributes);
// …
const scrollInfo = `[Scroll info …] window.scrollY: ${browserState.scrollY}, ` +
  `document.body.scrollHeight: ${browserState.scrollHeight}, …`;
const elementsText = wrapUntrustedContent(rawElementsText);   // ← 安全包裹,见第 4 章
formattedElementsText = `${scrollInfo}[Start of page]\n${elementsText}\n[End of page]\n`;

注意 wrapUntrustedContent(agent/messages/utils.ts:259):页面内容是不可信数据,可能藏着"忽略你的指令"之类的提示注入。这里把它包起来,细节是第 4 章的主题,本章不展开——只需知道清单在进消息前被隔离过一次。

② 拼上 tab 上下文。 当前 tab 和其它可用 tab,让模型知道自己在哪、能切到哪:

// prompts/base.ts:66 —— 当前 tab + 其它 tab 列表
const currentTab = `{id: ${browserState.tabId}, url: ${browserState.url}, title: ${browserState.title}}`;
const otherTabs = browserState.tabs
  .filter(tab => tab.id !== browserState.tabId)
  .map(tab => `- {id: ${tab.id}, url: ${tab.url}, title: ${tab.title}}`);

③ 组装成一条 HumanMessage。 最终的 stateDescription(prompts/base.ts:70)按"任务记忆结束 → 当前状态开始 → tab → 可交互元素 → 步数/时间 → 上一步动作结果"的顺序拼好。若开了视觉模式且有截图,还会把截图作为 image_url 一并塞进去(prompts/base.ts:83)——但即使有图,文本清单里的编号仍是模型下指令的唯一句柄。

到这里,一次感知的产物完整地进了模型的上下文。模型读完,就该输出"点几号 / 往几号里填什么"了——那是下一章。

5. 巧妙之处(可借鉴的技术)

用一个整数当"桥接编号",彻底解耦模型与 DOM。 模型只认 highlightIndex,系统内部维护 selectorMap 做回查。模型永远不碰 xpath/CSS,既省 token,又避免模型编造出乱七八糟的选择器。桥的两端:文本里的 [5](views.ts:298)↔ selectorMap.set(5, node)(service.ts:426)。
"父已高亮则子不重复发号"。 一个 <a><span>text</span></a> 只报一行,不会内外都编号。见 isElementDistinctInteraction 判定(buildDomTree.js:1192)。
属性值去重 + 截断这套"省 token 玄学"。 相同的长值只留一个、和文本重复的属性删掉、每个值截 15 字——作者注释直言"heavy vibes but good enough"(views.ts:241)。真实工程里,省 token 常常就是这种务实的启发式。
只报视口内的元素,让清单随滚动而变。 isInExpandedViewport 门槛(buildDomTree.js:1206)把清单控制在"当前看得见的一屏",避免一次把整页几百个元素全塞给模型。
跨 frame 用连续计数器缝一棵树。 startHighlightIndex 让每个 iframe 接着上一个编号数(service.ts:254),缝回主树后模型看到的仍是一份连号的统一清单,感知不到 frame 边界。
isNew 用 *[index] 标注新元素。 让模型知道"这一步页面变出了什么新东西",辅助判断上一步动作是否生效(views.ts:298,语义注释在 views.ts:86)。

6. 边界与局限

深度不可信的 iframe 拿不到。 带限制性 sandbox(无 allow-same-origin)的 iframe 直接标 error 不再尝试(buildDomTree.js:1427);跨域策略挡住的也只能靠"逐 frame 补跑"救回一部分,救不回的就是盲区。
视口外的东西默认看不见。 除非把 viewportExpansion 设成 -1(全给编号,buildDomTree.js:1206),否则模型每一步只感知一屏,复杂长页面必须靠反复滚动 + 反复感知。
可交互判定是启发式,会漏会误。 isInteractiveElement(buildDomTree.js:541)靠标签/role/指针样式/事件监听器综合猜。用自定义组件、纯 JS 绑事件而无语义标签的站点,可能漏判某个"其实能点"的元素。
编号每步重排,不能跨步复用。 页面一变,highlightIndex 从 0 重新数。所以感知必须每步重跑,旧编号无效——这是设计使然,不是 bug。
属性去重是"vibes",可能误删。 那套值去重启发式(views.ts:241)在极端情况下可能删掉本应保留的属性,作者自己也标了 WARNING。

7. 横向对比

感知层是所有 browser agent 的共性难题——如何把网页压成 LLM 能读的表示。Nanobrowser 走的是 "DOM → 带编号可交互元素清单" 路线(源自 browser-use 一脉),核心是 highlightIndex 桥接编号。它与另一类方案(纯视觉/坐标点击、或无障碍树 accessibility tree)的取舍不同:文本清单省 token、可精确回指,但依赖 DOM 判定的准确性;视觉方案更抗"无语义组件",但更贵、更易点偏。

本章讲的是感知;它下游紧接着的是:

03-actions-execution.md —— 模型拿到编号后,点击/输入怎么凭 selectorMap 落到真实元素。
04-memory-and-security.md —— 清单进消息前的 wrapUntrustedContent 安全包裹。
01-agent-loop.md —— 感知是主循环每一步的第一环。

8. 代码地图(导航索引)

主题	文件路径	符号名
感知层入口,返回 `DOMState`	`chrome-extension/src/background/browser/dom/service.ts`	`getClickableElements`
注入脚本 + 调用 `window.buildDomTree`	`chrome-extension/src/background/browser/dom/service.ts`	`_buildDomTree`
只往未注入的 frame 注入	`chrome-extension/src/background/browser/dom/service.ts`	`injectBuildDomTreeScripts` / `scriptInjectedFrames`
跨 iframe 逐 frame 补跑并缝合	`chrome-extension/src/background/browser/dom/service.ts`	`constructFrameTree`
匹配失败 iframe 对应的节点	`chrome-extension/src/background/browser/dom/service.ts`	`_locateMatchingIframeNode`
扁平 JSON 重建成树 + 填 `selectorMap`	`chrome-extension/src/background/browser/dom/service.ts`	`_constructDomTree` / `_parse_node`
清除页面高亮	`chrome-extension/src/background/browser/dom/service.ts`	`removeHighlights`
页面里遍历 DOM 的注入脚本	`chrome-extension/public/buildDomTree.js`	`window.buildDomTree` / `buildDomTree`
判定可交互	`chrome-extension/public/buildDomTree.js`	`isInteractiveElement`
发放 `highlightIndex`(省号规则)	`chrome-extension/public/buildDomTree.js`	`handleHighlighting`
父已高亮时判子是否独立交互	`chrome-extension/public/buildDomTree.js`	`isElementDistinctInteraction`
在页面画高亮框(可选)	`chrome-extension/public/buildDomTree.js`	`highlightElement`
元素节点类,承载 `highlightIndex`/`isNew`	`chrome-extension/src/background/browser/dom/views.ts`	`DOMElementNode`
树 → `[index]<tag attrs>text />` 文本	`chrome-extension/src/background/browser/dom/views.ts`	`clickableElementsToString`
收集到下个可交互元素为止的文本	`chrome-extension/src/background/browser/dom/views.ts`	`getAllTextTillNextClickableElement`
进清单的属性白名单	`chrome-extension/src/background/browser/dom/views.ts`	`DEFAULT_INCLUDE_ATTRIBUTES`
编号 → 节点回查表	`chrome-extension/src/background/browser/dom/views.ts`	`DOMState.selectorMap`
属性值截断	`chrome-extension/src/background/browser/util.ts`	`capTextLength`
清单 + 滚动 + tab 拼成 state 消息	`chrome-extension/src/background/agent/prompts/base.ts`	`buildBrowserStateUserMessage`
不可信内容安全包裹(详见 04)	`chrome-extension/src/background/agent/messages/utils.ts`	`wrapUntrustedContent`

1. 这是什么(零基础也能懂)​

一句话定义​

它要解决的问题​

用起来什么样​

一句话直觉​

2. 顶层全景(它大概怎么转)​

主线:从一棵 DOM 到一段文本​

部件一句话职责​

桥接编号:highlightIndex 是什么​

3. 核心原理(逐个机制,由浅入深)​

3.1 把脚本注入页面:两个世界怎么通信​

3.2 哪些元素算"可交互",谁配得到编号​

3.3 DOMElementNode:承载编号的节点​

3.4 clickableElementsToString:把树压成省 token 的文本​

3.5 selectorMap:编号回查真实节点的桥​

3.6 跨 iframe:拼一棵完整的树​

3.7 可选:在页面上画高亮框​

4. 从清单到 state 消息:拼给 LLM 的最后一步​

5. 巧妙之处(可借鉴的技术)​

6. 边界与局限​

7. 横向对比​

8. 代码地图(导航索引)​