dsh-browser-playwright-codex 0.5.1

package/scripts/dsh-browser-verify.mjs

@@ -0,0 +1,475 @@
+#!/usr/bin/env node
+/**
+ * dsh-browser-verify — 一条命令跑完 dsh-browser-playwright-codex 的快照取名/折叠与
+ * click/hover 两种定位模式的回归。改任何取名规则或工具说明后必须跑通它。
+ *
+ * 跑法（包内即自包含，无需 _deps）:
+ *   node scripts/dsh-browser-verify.mjs [--live]
+ *   --live  额外在 news.baidu.com 上采样真实页面的统计（会联网）
+ * 退出码 0 = 全绿；1 = 有失败项。
+ *
+ * 期望值不写死在这里：工具面从 src/contract.ts 推导，所以新增或调整工具时
+ * 只有 contract.ts 需要改，这份脚本不会因为"数字过期"而假报警。
+ *
+ * 读 lib/，但**必须先 build**：npm run verify 会先跑 npm run build，直接
+ * node scripts/... 跑则会撞上最后一组检查（lib/ 不旧于 src/）。
+ *
+ * 为什么不像测试那样用 tsx 直读 src/：tsx（esbuild keepNames）会把传给
+ * page.evaluate 的函数包成 __name(...)，而页面里没有这个符号 ——
+ * "ReferenceError: __name is not defined"，悬停/文字定位这类页面侧函数会全部
+ * 失效。lib/ 是编译产物，没有这层包裹，也正好是宿主真正加载的东西。
+ */
+import http from 'node:http'
+import { readdirSync, statSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { Config as ConfigSchema, PlaywrightProvider } from '../lib/playwright.js'
+import { renderSnapshot } from '../lib/snapshot-render.js'
+import { getEffectiveEngine, setSnapshotEngine } from '../lib/runtime-state.js'
+
+// 验收必须只看代码，不看这台机器上用户的选择。
+// 设置页的「页面识别方式」存在 ~/.dsh/dsh-browser-playwright.state.json，运行时状态层
+// 允许用 DSH_BROWSER_STATE_FILE 把它指向别处（src/runtime-state.ts 里为测试留的开关）。
+// 指向一个不存在的文件 = engine 回到配置默认值 legacy，本脚本的期望值就是按它写的。
+// 不隔离的话：用户把开关拨到「智能模式」，这份 57 项验收就会假失败（2026-10-01 实测）。
+// 注意 [1]–[7] 因此都跑在兼容模式下；智能模式由 [8] 显式切过去跑（隔离状态文件里切，
+// 不碰用户的真实选择）。
+process.env.DSH_BROWSER_STATE_FILE = path.join(os.tmpdir(), 'dsh-browser-verify-state-isolated.json')
+
+let pass = 0
+const failures = []
+function check(name, ok, detail) {
+  if (ok) {
+    pass += 1
+    console.log('  ok   ' + name)
+  } else {
+    failures.push(name)
+    console.log('  FAIL ' + name + (detail ? ' :: ' + detail : ''))
+  }
+}
+function has(tree, fragment) {
+  return tree.indexOf(fragment) !== -1
+}
+function lineAfter(tree, fragment) {
+  const lines = tree.split('\n')
+  const i = lines.findIndex((l) => l.includes(fragment))
+  return i >= 0 ? lines[i + 1] || '' : '(not found)'
+}
+
+const HTML = `<!doctype html><html><head><meta charset="utf-8"><title>v</title></head><body>
+<h1>verify</h1>
+<a href="/1"><span>折叠链接</span></a>
+<a href="/2"><div><span>多层折叠</span></div></a>
+<a href="/3"><h3>标题链接</h3></a>
+<button value="v">按钮文字</button>
+<input type="button" value="输入按钮">
+<select><option>甲</option><option selected>乙</option></select>
+<a href="/4"><img src="x.png" alt="图标链接"></a>
+<a href="/5"><img src="x.png" alt="图标"><span>图文链接</span></a>
+<a href="/6">尾<span>前</span></a>
+<button><span>多段</span><span>按钮</span></button>
+<a href="/7"><span aria-hidden="true">装饰</span><span>真名</span></a>
+<table><tr><td>单元格</td></tr></table>
+<button id="reveal">显示详情</button>
+<button id="closebtn" aria-label="关闭弹层"><span>×</span></button>
+<div id="detail" style="display:none">详情 <a href="/d">详情链接</a></div>
+<span id="settings">设置</span>
+<div id="panel" style="display:none"><a href="/a">菜单甲</a><a href="/b">菜单乙</a></div>
+<div id="contentsWrap" style="display:contents"><a href="/dc">内容链接</a></div>
+<span class="dup">重复项</span><span class="dup">重复项</span>
+<button id="del">删除记录</button><div id="row">记录存在</div>
+<button id="ask">弹提示</button>
+<script>
+document.getElementById('settings').addEventListener('mouseenter', () => { document.getElementById('panel').style.display = 'block'; });
+document.getElementById('settings').addEventListener('mouseleave', () => { document.getElementById('panel').style.display = 'none'; });
+document.getElementById('reveal').addEventListener('click', () => {
+  document.getElementById('detail').style.display = 'block';
+  document.getElementById('reveal').textContent = '详情已显示';
+});
+document.getElementById('closebtn').addEventListener('click', () => { document.title = 'closed'; });
+document.getElementById('del').addEventListener('click', () => {
+  if (window.confirm('确定删除这条记录吗？')) { document.getElementById('row').style.display = 'none'; }
+});
+document.getElementById('ask').addEventListener('click', () => { window.alert('操作成功'); });
+</script></body></html>`
+
+// [8] 用的页面：故意在输入框与按钮之前排两个「可交互但不可见」的元素。
+// 这正是旧版智能模式会整体错位的形态：DOM 侧按文档顺序给每一个可交互元素编号
+// （含隐藏的），aria 树里只有可见节点，于是后面每个 ref 都错位一格 ——
+// 实测 2026-10-02 在 dsh-plugin.market 上就是这样把「输入框」指成了一个 0×0 的隐藏链接。
+const ARIA_HTML = `<!doctype html><html><head><meta charset="utf-8"><title>v</title></head><body>
+<h1>aria</h1>
+<button id="evil" style="display:none" onclick="document.title='HIDDEN-WRONG'">隐藏按钮</button>
+<a href="#x" hidden>隐藏链接</a>
+<span id="settings2">设置</span>
+<label for="field">昵称</label>
+<input id="field" placeholder="在这里输入">
+<button id="ok">ARIA 提交</button>
+<p id="res">(未点)</p>
+<script>
+document.getElementById('ok').addEventListener('click', () => {
+  document.getElementById('res').textContent = 'ARIA-CLICK-OK';
+});
+</script></body></html>`
+
+const server = http.createServer((req, res) => {
+  res.setHeader('content-type', 'text/html; charset=utf-8')
+  res.end(req.url && req.url.startsWith('/aria') ? ARIA_HTML : HTML)
+})
+await new Promise((r) => server.listen(0, '127.0.0.1', r))
+const URL_ = 'http://127.0.0.1:' + server.address().port + '/'
+const ARIA_URL_ = URL_ + 'aria'
+const provider = new PlaywrightProvider(
+  ConfigSchema({ launch: { headless: true, persistent: false, navigationTimeoutMs: 20000 }, idleTimeoutMs: 0 }),
+)
+const session = await provider.acquire('verify')
+
+console.log('[1] 快照取名与折叠')
+const s0 = await session.navigate(URL_, 'load')
+const tree = renderSnapshot(s0)
+check(
+  '折叠直接子节点 (a>span)',
+  has(tree, 'link "折叠链接" [ref=') && !lineAfter(tree, 'link "折叠链接"').includes('折叠链接'),
+)
+check('折叠多层包裹 (a>div>span)', has(tree, 'link "多层折叠" [ref=') && !has(tree, 'generic "多层折叠"'))
+check('标题链接折叠 (有意取舍)', has(tree, 'link "标题链接" [ref=') && !has(tree, 'heading "标题链接"'))
+check('<button> 取文字不取 value', has(tree, 'button "按钮文字" [ref=') && !has(tree, 'button "v" [ref='))
+check('<input type=button> 取 value', has(tree, 'button "输入按钮" [ref='))
+check('<select> 显示当前选项', has(tree, 'combobox "乙" [ref=') && has(tree, 'option "甲" [ref='))
+check('纯图标链接折叠 img', has(tree, 'link "图标链接" [ref=') && !has(tree, 'img "图标链接"'))
+check('图文链接保留 img', has(tree, 'link "图文链接" [ref=') && has(tree, 'img "图标"'))
+check('自身+子孙文字合并', has(tree, 'link "尾 前" [ref='))
+check('多段文字折叠干净', has(tree, 'button "多段 按钮" [ref=') && !has(tree, 'generic "多段"'))
+check('aria-hidden 子文字被跳过', has(tree, 'link "真名" [ref=') && !has(tree, '装饰'))
+check('表格行不从单元格取名', has(tree, 'row [ref=') && has(tree, 'cell "单元格"'))
+check('display:contents 容器继续下钻（0×0 不得剪掉子树）', has(tree, 'link "内容链接" [ref='))
+
+console.log('[2] 悬停：ref 模式 / text 模式 / 错误路径')
+const settingsRef = (function find(ns) {
+  for (const n of ns) {
+    if (n.ref && n.name === '设置') return n.ref
+    const h = find(n.children || [])
+    if (h) return h
+  }
+})(s0.nodes)
+check('「设置」确实没有 ref', settingsRef === undefined)
+const h1 = await session.hoverText('设置')
+check('text 模式悬停成功且指出目标', has(h1.landingNote || '', '设置') && /\+\d+/.test(h1.landingNote || ''))
+function treeHas(nodes, name) {
+  return (nodes || []).some((n) => n.name === name || treeHas(n.children, name))
+}
+check('悬停揭示出菜单项', treeHas(h1.nodes, '菜单甲'))
+const h2 = await session.hoverText('重复项')
+check('同名时提示 FIRST of N', has(h2.landingNote || '', 'FIRST of 2'))
+let hoverErr = ''
+try {
+  await session.hoverText('不存在的标签')
+} catch (e) {
+  hoverErr = e.code
+}
+check('找不到时报 HOVER_TARGET_NOT_FOUND', hoverErr === 'HOVER_TARGET_NOT_FOUND')
+
+console.log('[3] 点击：ref 模式 / text 模式 / 错误路径')
+const revealRef = (function find(ns) {
+  for (const n of ns) {
+    if (n.ref && n.name === '显示详情') return n.ref
+    const h = find(n.children || [])
+    if (h) return h
+  }
+})(s0.nodes)
+const c1 = await session.clickText('显示详情')
+check('text 模式点击让页面真的变', (c1.totalRefs || 0) > (s0.totalRefs || 0) && has(renderSnapshot(c1), '详情已显示'))
+const c2 = await session.click(revealRef)
+check('ref 模式仍可用', has(renderSnapshot(c2), '[ref='))
+const c3 = await session.clickText('重复项')
+check('同名点击提示 FIRST of 2', has(c3.landingNote || '', 'FIRST of 2'))
+let clickErr = ''
+try {
+  await session.clickText('不存在的按钮')
+} catch (e) {
+  clickErr = e.code
+}
+check('找不到时报 CLICK_TARGET_NOT_FOUND', clickErr === 'CLICK_TARGET_NOT_FOUND')
+let ariaNote = ''
+let ariaHit = false
+try {
+  ariaNote = (await session.clickText('关闭弹层')).landingNote || ''
+  ariaHit = true
+} catch (e) {
+  ariaNote = 'ERR ' + String(e.message || e)
+}
+const ariaEffect = await session.evaluate('document.title')
+check(
+  'text 模式能按 aria-label 命中（且真的点到了）',
+  ariaHit && ariaEffect === 'closed',
+  ariaNote.slice(0, 90) + ' | title=' + ariaEffect,
+)
+
+const leftover = await session.evaluate("document.querySelectorAll('[data-dsh-label-target]').length")
+check('页面无 label 残留', leftover === 0)
+
+console.log('[4] 原生弹窗：挂起 + 独立工具回应')
+const findRef = (ns, name) => {
+  for (const n of ns) {
+    if (n.ref && n.name === name) return n.ref
+    const h = findRef(n.children || [], name)
+    if (h) return h
+  }
+  return undefined
+}
+const rowDisplay = () => session.evaluate("getComputedStyle(document.getElementById('row')).display")
+
+// a) 没有待处理弹窗时，回应必须被拒
+let noDlgErr = ''
+try {
+  await session.resolveDialog(true)
+} catch (e) {
+  noDlgErr = e.code || String(e.message).slice(0, 40)
+}
+check('没有待处理弹窗时拒绝回应（NO_DIALOG）', noDlgErr === 'NO_DIALOG', noDlgErr)
+
+// b) 触发弹窗：动作不卡死，弹窗如实上报为待处理，且还没人决定
+const sDel = await session.snapshot({})
+const delRef = findRef(sDel.nodes, '删除记录')
+const t0 = Date.now()
+const pendSnap = await session.click(delRef)
+const elapsed = Date.now() - t0
+const pendNote = pendSnap.dialogNote || ''
+check('触发弹窗的动作不卡死（<3s）', elapsed < 3000, elapsed + 'ms')
+check(
+  '弹窗如实上报为待处理',
+  /confirm/i.test(pendNote) && /PENDING/i.test(pendNote) && pendNote.includes('确定删除这条记录吗'),
+  pendNote.slice(0, 120),
+)
+// 注意：弹窗挂起期间页面被阻塞，这里**不能**去碰页面（rowDisplay 会卡死）。
+// "还没人决定"改在取消之后验证：记录仍在即证明期间没有发生任何接受。
+
+// c) 挂起期间取快照必须立刻返回（不能去碰被阻塞的页面）
+const tBlock = Date.now()
+const blockedSnap = await session.snapshot({})
+const t1ms = Date.now() - tBlock
+check('挂起期间快照立刻返回（<2s）', t1ms < 2000, t1ms + 'ms')
+check(
+  '挂起期间的快照也提示待处理',
+  /PENDING/i.test(blockedSnap.dialogNote || ''),
+  (blockedSnap.dialogNote || '').slice(0, 90),
+)
+
+// d) 取消 → 页面解锁，动作未执行
+const disSnap = await session.resolveDialog(false)
+check('取消后写明 DISMISSED', /DISMISSED/.test(disSnap.landingNote || ''), (disSnap.landingNote || '').slice(0, 110))
+check('取消后记录还在', (await rowDisplay()) !== 'none')
+const afterDismiss = await session.snapshot({})
+check('取消后页面解锁（快照可用）', (afterDismiss.totalRefs || 0) > 0)
+
+// F1~F4：红队发现的三类「卡死 / 绕过守门」，逐条固化成用例
+const withTimeout = (p, ms, tag) =>
+  Promise.race([p, new Promise((_, rej) => setTimeout(() => rej(new Error('TIMEOUT ' + tag)), ms))])
+let ct1 = null
+try {
+  ct1 = await withTimeout(session.clickText('删除记录'), 6000, 'clickText')
+} catch (e) {
+  ct1 = { dialogNote: 'ERR ' + String(e.message || e).slice(0, 40) }
+}
+check('F1 clickText 自己触发弹窗时不卡死', !/TIMEOUT/.test(ct1.dialogNote || ''), (ct1.dialogNote || '').slice(0, 90))
+await session.resolveDialog(false).catch(() => {})
+
+const sF = await session.snapshot({})
+await session.click(findRef(sF.nodes, '删除记录'))
+let swRes = ''
+try {
+  await withTimeout(session.switchTab(0), 5000, 'switchTab')
+  swRes = 'no-throw'
+} catch (e) {
+  swRes = e.code || String(e.message).slice(0, 24)
+}
+check('F2 挂起时 switchTab 被拒而不是卡死', swRes === 'DIALOG_PENDING', swRes)
+let otRes = ''
+try {
+  await withTimeout(session.openTab(URL_, 'load'), 5000, 'openTab')
+  otRes = 'no-throw'
+} catch (e) {
+  otRes = e.code || String(e.message).slice(0, 24)
+}
+check('F3 挂起时 openTab 被拒而不是卡死', otRes === 'DIALOG_PENDING', otRes)
+let ctbRes = ''
+try {
+  await withTimeout(session.closeTab(0), 5000, 'closeTab')
+  ctbRes = 'no-throw'
+} catch (e) {
+  ctbRes = e.code || String(e.message).slice(0, 24)
+}
+check('F4 挂起时 closeTab 被拒（不得隐式取消）', ctbRes === 'DIALOG_PENDING', ctbRes)
+check('F4 之后弹窗仍然挂起（没被偷偷取消）', /PENDING/.test((await session.snapshot({})).dialogNote || ''))
+await session.resolveDialog(false)
+
+// e) 再弹一次 → 接受 → 动作真的执行
+const sDel2 = await session.snapshot({})
+await session.click(findRef(sDel2.nodes, '删除记录'))
+const accSnap = await session.resolveDialog(true)
+check('接受后写明 ACCEPTED', /ACCEPTED/.test(accSnap.landingNote || ''), (accSnap.landingNote || '').slice(0, 110))
+check('接受后动作真的执行了（记录被删）', (await rowDisplay()) === 'none')
+
+// f) alert 同样挂起、同样要独立回应
+const sAsk = await session.snapshot({})
+await session.click(findRef(sAsk.nodes, '弹提示'))
+const askSnap = await session.snapshot({})
+check(
+  'alert 同样挂起上报',
+  /alert/i.test(askSnap.dialogNote || '') && /PENDING/i.test(askSnap.dialogNote || ''),
+  (askSnap.dialogNote || '').slice(0, 90),
+)
+await session.resolveDialog(true)
+check('alert 回应后页面解锁', ((await session.snapshot({})).totalRefs || 0) > 0)
+
+// F7：畸形信号不得遗弃 promise（旧实现会 unhandledRejection 崩宿主 / 卡死）
+const sSig = await session.snapshot({})
+let sig7 = 'ok'
+try {
+  await withTimeout(session.click(findRef(sSig.nodes, '删除记录'), true), 6000, 'bogusSignal')
+} catch (e) {
+  sig7 = 'ERR ' + String(e.message).slice(0, 30)
+}
+check('F7 畸形信号不卡死也不崩', sig7 === 'ok', sig7)
+await session.resolveDialog(false).catch(() => {})
+
+// F6：persistent 模式下多个会话共享同一页，别人的挂起弹窗不得被接管
+const fakePage = {}
+provider.pendingDialogs.set(fakePage, { dialog: null, type: 'confirm', message: 'x', owner: 'owner-A' })
+check('F6 别的 owner 拿不到别人的挂起弹窗', provider.takePendingDialog(fakePage, 'owner-B') === undefined)
+check('F6 本人 owner 可以拿到', (provider.takePendingDialog(fakePage, 'owner-A') || {}).owner === 'owner-A')
+provider.pendingDialogs.delete(fakePage)
+
+console.log('[5] 工具面：新增 browser_dialog，删除 acceptDialog')
+const toolMod = await import('../lib/tool.js')
+const contractMod = await import('../lib/contract.js')
+const reg = []
+const toolConfig = toolMod.Config({})
+// The plugin checks its own surface against contract.ts at load time, so the
+// fake registry has to answer schemas() the way the real one does.
+toolMod.apply(
+  {
+    browser: { acquire: async () => ({}) },
+    get: () => undefined,
+    tools: { register: (t) => reg.push(t), schemas: () => reg },
+  },
+  toolConfig,
+)
+const expectedTools = contractMod.registeredToolNames(toolConfig.toolPrefix, {
+  allowEvaluate: toolConfig.allowEvaluate,
+  allowCdp: toolConfig.allowCdp,
+  extractConfigured: toolConfig.extract?.provider !== undefined && toolConfig.extract?.model !== undefined,
+  registerDisabledTools: toolConfig.registerDisabledTools,
+})
+const byName = (n) => reg.find((t) => t.name === n)
+check('存在 browser_dialog', byName('browser_dialog') !== undefined)
+check(
+  'browser_dialog 有 accept 参数',
+  !!byName('browser_dialog') && !!(byName('browser_dialog').parameters.properties || {}).accept,
+)
+check(
+  'browser_click 不再有 acceptDialog',
+  !!byName('browser_click') && !('acceptDialog' in (byName('browser_click').parameters.properties || {})),
+)
+check(
+  '工具面与 contract 一致（' + expectedTools.length + ' 个）',
+  reg.length === expectedTools.length && expectedTools.every((n) => byName(n) !== undefined),
+  'count=' + reg.length + ' expected=' + expectedTools.length,
+)
+
+const t1 = await session.tabs()
+check(
+  'tabs 每项带 active 且只有一个 true',
+  t1.every((t) => typeof t.active === 'boolean') && t1.filter((t) => t.active).length === 1,
+)
+const activeBefore = (t1.find((t) => t.active) || {}).index
+await session.openTab(URL_ + '?second', 'load')
+const t2 = await session.tabs()
+const activeNow = (t2.find((t) => t.active) || {}).index
+check(
+  '新开的标签页成为 active',
+  t2.length === t1.length + 1 && activeNow === t2.length - 1 && activeNow !== activeBefore,
+)
+
+if (process.argv.includes('--live')) {
+  console.log('[7] 真实页面采样 (news.baidu.com)')
+  try {
+    const live = await session.navigate('https://news.baidu.com/', 'load')
+    const t = renderSnapshot(await session.snapshot({}))
+    const unnamed = t
+      .split('\n')
+      .filter((l) =>
+        /^- (link|button|menuitem|tab|combobox|textbox|checkbox|radio|switch|option|slider|spinbutton) \[ref=/.test(
+          l.trim(),
+        ),
+      ).length
+    console.log('  info refs=' + live.totalRefs + ' chars=' + t.length + ' unnamedActionable=' + unnamed)
+    check('真实页可快照', live.totalRefs > 0)
+  } catch (e) {
+    console.log('  info 联网采样失败: ' + String(e.message || e).slice(0, 120))
+  }
+}
+
+console.log('[6] CDP：绑定调用真的能发出命令')
+// 这条用例是回归闸门：CDPSession.send 是原型方法，一旦被解绑成裸函数，
+// 整条 CDP 链路会以 "Cannot read properties of undefined (reading '_channel')" 失败。
+const cdpReply = await session
+  .cdp('DOM.getDocument', { depth: 1 }, undefined)
+  .then((reply) => (reply === null || typeof reply !== 'object' ? null : reply.root))
+  .catch(() => null)
+check('session.cdp 允许的方法可用（绑定调用）', cdpReply !== null && cdpReply.nodeName === '#document')
+
+// ---------------------------------------------------------------------------
+// [8] 智能模式（aria 引擎）端到端：ref 必须指回它命名的那个元素
+// ---------------------------------------------------------------------------
+// 上面 [1]–[7] 全跑在兼容模式下（隔离状态文件 + engine 默认 legacy）。这一段把开关
+// 切到 aria，检查的是 2026-10-02 修掉的那个真 bug：ref 可能「名字对一个元素、解析到
+// 另一个元素」。运行时状态层每次取快照都重读开关，所以这里切完立刻生效；
+// 状态文件是隔离的临时文件，不碰用户真实的选择。
+console.log('[8] 智能模式（aria 引擎）端到端')
+setSnapshotEngine('aria')
+check('运行时开关可切到 aria', getEffectiveEngine() === 'aria', getEffectiveEngine())
+
+const ariaSnap = await session.navigate(ARIA_URL_, 'load')
+const ariaTree = renderSnapshot(ariaSnap)
+// engineNote 只在「读不出来、退回兼容模式」时出现：它缺席 + 树里有 textbox，
+// 才说明这一步真的走了智能模式，而不是悄悄回退（回退现在会明说，见 snapshotValue）。
+check(
+  '智能模式读得出来（未回退，且明说规则未触发）',
+  ariaSnap.engineNote === undefined && has(ariaTree, 'textbox'),
+  ariaSnap.engineNote ?? ariaTree.slice(0, 160),
+)
+const ariaBtnLine = ariaTree.split('\n').find((l) => l.includes('button "ARIA 提交"'))
+const ariaBtnRef = ariaBtnLine === undefined ? null : ((ariaBtnLine.match(/ref=([^\]\s]+)/) ?? [])[1] ?? null)
+check('树里能找到「ARIA 提交」的 ref', ariaBtnRef !== null, ariaBtnLine ?? '(no line)')
+if (ariaBtnRef !== null) {
+  const afterClick = renderSnapshot(await session.click(ariaBtnRef, undefined))
+  check('按 ref 点击命中它命名的那个元素', has(afterClick, 'ARIA-CLICK-OK'), afterClick.slice(0, 200))
+  // 排在它前面的隐藏按钮如果被「按位置」错配走这个 ref，就会触发它的处理函数。
+  check('没有把点击落到排在前面的隐藏元素上', !has(afterClick, 'HIDDEN-WRONG'))
+}
+setSnapshotEngine('legacy')
+
+await provider.dispose()
+server.close()
+
+// [7] lib/ 是宿主真正加载的产物：源码改完没 build，跑绿了也是白跑。
+console.log('[7] lib/ 与 src/ 同步（宿主加载 lib/）')
+const stale = []
+for (const file of readdirSync(new URL('../src', import.meta.url))) {
+  if (!file.endsWith('.ts') || file.endsWith('.d.ts')) continue
+  const src = statSync(new URL('../src/' + file, import.meta.url)).mtimeMs
+  const built = statSync(new URL('../lib/' + file.replace(/\.ts$/, '.js'), import.meta.url), {
+    throwIfNoEntry: false,
+  })
+  if (built === undefined || built.mtimeMs < src) stale.push(file.replace(/\.ts$/, '.js'))
+}
+check('lib/ 不旧于 src/（旧了就先 npm run build）', stale.length === 0, stale.join(', '))
+
+console.log('')
+console.log(
+  failures.length === 0
+    ? '全部通过 (' + pass + ' 项)'
+    : '失败 ' + failures.length + ' 项 / 共 ' + (pass + failures.length) + ' 项: ' + failures.join(', '),
+)
+process.exit(failures.length === 0 ? 0 : 1)

package/scripts/measure-prompt-cost.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * measure-prompt-cost —— 常驻 prompt 成本体检。
+ *
+ * 工具 schema 是随系统提示每轮常驻的：这个脚本把它量出来，改动前后各跑一次，
+ * 就知道这次改动有没有偷偷加税。和 doctor 一样，它不碰浏览器，只组装工具面。
+ *
+ * 用法:  node node_modules/tsx/dist/cli.mjs scripts/measure-prompt-cost.mjs
+ *        （或 npm run cost）
+ *
+ * 三行分别对应三种"默认"，别混：
+ *   ① 配置默认值（Config({})，不含任何补丁层）
+ *   ② 出厂 bundle 层 —— 本包 cordis.patch.yml 里给 browser-tool 的配置，
+ *      也就是 profile 挂上这个 bundle 后真正生效的那份。两个闸门默认关闭，
+ *      所以这一行正常情况下应当与 ① 相同；包里的默认值一改，它自己跟着变。
+ *   ③ 全量注册（再加 registerDisabledTools: true）
+ *
+ * 注意：唯一会抬高这个数字的动作是「注册新工具」。文档、脚本、git 都不进 prompt。
+ *
+ * 测量实现放在 scripts/prompt-cost.mjs：脚本与文档守卫测试（tests/docs-consistency）
+ * 共用一份，免得两边各写一遍再各自漂移。
+ */
+import { CONFIG_DEFAULTS, shippedConfig, everythingConfig, measureSurface, approxTokens } from './prompt-cost.mjs'
+
+function report(label, { rows, total }) {
+  console.log('')
+  console.log(label)
+  console.log('  工具数: ' + rows.length + '   wire 字符总数: ' + total + '   粗估 token: ~' + approxTokens(total))
+  console.log('  最贵的 5 个:')
+  for (const [name, wire, desc] of rows.slice(0, 5)) {
+    console.log('    ' + name.padEnd(26) + ' wire ' + String(wire).padStart(5) + '  (描述 ' + desc + ')')
+  }
+  return total
+}
+
+console.log('常驻 prompt 成本体检（工具 schema 每轮都在系统提示里）')
+const t0 = report('① 配置默认值 Config({})', await measureSurface(CONFIG_DEFAULTS))
+const shipped = shippedConfig()
+const t1 = report(
+  '② 出厂 bundle 层（cordis.patch.yml：allowEvaluate=' +
+    shipped.allowEvaluate +
+    ', allowCdp=' +
+    shipped.allowCdp +
+    '）',
+  await measureSurface(shipped),
+)
+const t2 = report('③ 全量注册（registerDisabledTools: true，再加 extract）', await measureSurface(everythingConfig()))
+
+console.log('')
+console.log(
+  '② → ③ 的差 = 被能力开关挡住、没有关掉的那些 schema：' +
+    (t2 - t1) +
+    ' 字符 ≈ ' +
+    approxTokens(t2 - t1) +
+    ' token/轮。',
+)
+console.log('想让这个数字更小，就在 cordis.patch.yml 里把用不上的能力关掉（关掉即不注册）。')

package/scripts/prompt-cost.mjs

@@ -0,0 +1,73 @@
+/**
+ * prompt-cost — 「工具面常驻成本」的**唯一测量实现**。
+ *
+ * 为什么单独成模块：这个测量既被 `measure-prompt-cost.mjs`（给人看的 CLI）用，也被文档守卫测试
+ * （`tests/docs-consistency.test.ts`）用。两份实现各自漂移过一次了（cost 脚本的标签被注释骗到），
+ * 所以这里只留一份。
+ *
+ * 它只做一件事：组装工具面、读 `ctx.tools.schemas()` 的 wire 尺寸。
+ * **不 acquire 会话、不开浏览器** —— 所以测试里也能直接跑。
+ */
+import { Context } from '@deepseek-ai/cordis'
+import ToolRuntime from '@deepseek-ai/dsh-tools'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import BrowserRuntime from '../src/service.ts'
+import { PlaywrightProvider } from '../src/playwright.ts'
+import * as browserTool from '../src/tool.ts'
+import { bundleConfig } from './shipped-gates.mjs'
+
+/** Launch config for the throwaway context (no page is ever opened, so this is inert). */
+const PW_CONFIG = {
+  launch: {
+    channel: 'chrome',
+    headless: true,
+    viewport: { width: 1280, height: 800 },
+    navigationTimeoutMs: 5000,
+    ignoreHTTPSErrors: false,
+  },
+  idleTimeoutMs: 0,
+  maxSessions: 2,
+  snapshot: { maxNodes: 200, maxNameLength: 120, maxTextLength: 300 },
+}
+
+/** `Config({})`: the schema defaults, before any patch layer. */
+export const CONFIG_DEFAULTS = {
+  toolPrefix: 'browser_',
+  allowEvaluate: false,
+  allowCdp: false,
+  registerDisabledTools: false,
+  maxWaitMs: 60000,
+  interactiveOnlyDefault: false,
+}
+
+/** The shipped bundle layer: Config defaults plus this package's `cordis.patch.yml`. */
+export function shippedConfig() {
+  return { ...CONFIG_DEFAULTS, ...bundleConfig() }
+}
+
+/** Everything registered: gated tools stay registered while off, which also pulls in `extract`. */
+export function everythingConfig() {
+  return { ...shippedConfig(), registerDisabledTools: true }
+}
+
+/** Assemble one tool surface and return its per-schema wire sizes. */
+export async function measureSurface(config) {
+  const root = new Context()
+  await root.plugin(SystemPrompt)
+  await root.plugin(ToolRuntime)
+  await root.plugin(BrowserRuntime)
+  root.browser.registerProvider(new PlaywrightProvider(PW_CONFIG))
+  browserTool.apply(root, config)
+  const rows = root.tools
+    .schemas()
+    .map((s) => [
+      s.name,
+      JSON.stringify({ name: s.name, description: s.description, parameters: s.parameters }).length,
+      s.description.length,
+    ])
+    .sort((a, b) => b[1] - a[1])
+  return { rows, total: rows.reduce((n, r) => n + r[1], 0) }
+}
+
+/** The rough per-turn token estimate the docs quote: characters / 3.6, rounded. */
+export const approxTokens = (chars) => Math.round(chars / 3.6)

package/scripts/shipped-gates.mjs

@@ -0,0 +1,43 @@
+/**
+ * shipped-gates — 「出厂包里那两个闸门到底是什么值」，只此一份实现。
+ *
+ * 为什么要单独成模块：这段逻辑被注释骗过一次（2026-10-02）。包里 0.4.7 起两个闸门都是
+ * false，而 cordis.patch.yml 里同时写着「怎么开启」的注释示例 —— 里面先出现一行
+ * `allowEvaluate: true`。一个不剥注释的正则会匹配到**注释**，于是 cost 脚本把出厂层
+ * 报成 "两个都开着 / 22 工具 ≈ 4842"，而真实是 "都关着 / 20 工具 ≈ 4176"。
+ * 抽出来之后：脚本用它、守卫测试也用它（并对着一份独立解析比对），谁改坏了都会当场失败。
+ */
+import { readFileSync } from 'node:fs'
+
+/**
+ * Read the shipped bundle layer: what a deployment actually gets.
+ *
+ * Comment lines are stripped first, and that is not cosmetic: the file documents the
+ * opt-in snippet, so a naive regex matches the *example* `allowEvaluate: true` inside a
+ * comment. Attribute lines inside comments are documentation, not configuration.
+ *
+ * @param {URL} [patchUrl] - defaults to this package's cordis.patch.yml.
+ * @returns {{ allowEvaluate: boolean, allowCdp: boolean }}
+ */
+export function bundleConfig(patchUrl = new URL('../cordis.patch.yml', import.meta.url)) {
+  const yml = readFileSync(patchUrl, 'utf8')
+  const code = stripComments(yml)
+  const row = code.split(/\n(?=\s*- id: )/).find((block) => block.includes('dsh-browser-playwright-codex/tool')) ?? ''
+  if (row === '') throw new Error('cordis.patch.yml: no dsh-browser-playwright-codex/tool row found')
+  const flag = (name) => new RegExp(name + ':\\s*(true|false)').exec(row)?.[1] === 'true'
+  return { allowEvaluate: flag('allowEvaluate'), allowCdp: flag('allowCdp') }
+}
+
+/**
+ * Drop `#` comments (full-line and trailing) so documentation examples cannot be read
+ * as configuration. Exported so a guard test can compare an independent parse.
+ * @param {string} yml
+ * @returns {string}
+ */
+export function stripComments(yml) {
+  return yml
+    .split('\n')
+    .map((line) => line.replace(/\s+#.*$/, ''))
+    .filter((line) => !/^\s*#/.test(line))
+    .join('\n')
+}