AI Helper 页面检查工具 —— query_page 与 list_structure
一个 AI 助手的好坏取决于它能看到什么。AI Helper 不靠对页面的模糊描述工作 —— 它拥有工具来查看真实的 DOM 以及你现有的 JustZix 库。这篇文章介绍两个检查工具:query_page 和 list_structure。
起始上下文
你发送的每条消息都已经携带页面 URL、标题和一个 HTML 片段。对于简单的请求来说,那就足够了。但片段终归是片段 —— 为了得到一个精确的选择器,模型常常需要更仔细地查看页面的某个具体部分。这正是检查工具的用途。
query_page —— 查看实时 DOM
模型传入一个 CSS 选择器;工具针对当前页面运行它,并返回匹配数量加上匹配项的 HTML。
@@JZ_TOOL@@ {"tool": "query_page", "args": {"selector": "header .nav"}} @@END@@
result:
matches: 1
html: "<nav class=\"nav\"> ... </nav>"这把猜测变成了检查。模型不必为一个它想象出来的结构写 CSS,而是可以确认实际存在的东西:.nav 是否存在、是有一个还是五个、子元素带着什么类、按钮是不是在一个包裹元素里。有了这些,它写出的选择器就会瞄准真实的页面。
模型如何使用它
- 确认一个元素存在 —— 查询选择器,检查计数不为零。
- 收窄一个选择器 —— 先宽泛地开始,读取返回的 HTML,然后查询更具体的东西。
- 检查唯一性 —— 计数为 1 意味着选择器很具体;计数为 30 意味着对于一个有针对性的修复来说它太宽泛了。
- 读取结构 —— 在写一个
:has()或后代选择器之前先看清父/子关系。
在一个智能体轮次中,模型可能多次调用 query_page,边学边精炼 —— 全部在 8 步预算之内。
list_structure —— 读取你现有的规则
第二个工具看的不是页面,而是你的 JustZix 库。list_structure 返回你的文件夹、分组和规则,连同它们的 id。
@@JZ_TOOL@@ {"tool": "list_structure", "args": {}} @@END@@
result:
folders:
- id: f_12 "News sites"
groups:
- id: g_3 "Layout fixes"
rules:
- id: r_88 "Hide sidebar ads"
- id: r_90 "Wider article column"模型为什么需要这个:
- 避免重复 —— 如果一条类似的规则已经存在,模型可以把你指向它,而不是再做一条。
- 把新东西放得合理 —— 一条用于新闻站点的新规则可以放进你现有的「News sites」文件夹,而不是把零散的规则到处散落。
- 使用真实的 id ——
create_group和create_rule需要一个父 id;list_structure就是那些 id 的来源。
它是只读的。看到你的结构和改变它不是一回事 —— 创建一个文件夹、分组或规则仍然需要 create 工具以及你的明确确认。
为什么按需检查胜过把整个页面倒出去
一个显而易见的替代方案是事先把整个页面 HTML 发给模型。AI Helper 故意不这样做。按需检查出于真实的原因更胜一筹:
| 把整个页面倒出去 | 按需检查 |
|---|---|
| 每条消息都有巨大的 token 成本 | 只为查询的内容付费 |
| 模型淹没在无关的标记里 | 模型看到真正重要的部分 |
| 现代页面可能超出上下文窗口 | 有针对性的片段总能放得下 |
| 页面变化后就过时了 | 每次查询都读取当前的 DOM |
一个现代 Web 应用可以有数百千字节的 HTML。把它全部塞进上下文既慢又贵,而且常常适得其反 —— 信号被噪声埋没。一次针对 .cookie-banner 的聚焦 query_page 恰好给模型它需要的那几行。
新鲜度也很重要
页面不是静态的。菜单会打开,模态框会出现,内容会延迟加载。因为 query_page 在被调用的那一刻运行,模型读取的是此刻的 DOM —— 包括你最初打开聊天时还不存在的元素。一次性的页面倒出做不到这一点。
检查为工作流提供养料
这些工具是更大的智能体式工作流的第一步:用 query_page 和 list_structure 检查,在 TEMP 面板中测试,请你验证,然后持久化。良好的检查正是让后续步骤准确的原因 —— 选择器之所以正确,是因为模型真的看过了。
另请参阅
按需检查正是让 AI Helper 既精确又便宜的原因。下载 JustZix,添加一个密钥,让它查看一个棘手的元素。
为这篇文章评分
暂无评分 — 成为第一个。