dsh-browser-playwright-codex 0.5.4 → 0.6.0

package/lib/tool.js

@@ -3,7 +3,8 @@ import { defineTool } from '@deepseek-ai/dsh-tools';
 import { BlockAssembler, createUserMessage } from '@deepseek-ai/dsh-llm';
 import { BrowserError } from "./errors.js";
 import { registeredSuffixes } from "./contract.js";
-import { getEnabled, publishGates } from "./runtime-state.js";
+import { getEnabled, publishGates, publishLoginSites } from "./runtime-state.js";
+import { summarizeLoginSites } from "./login-sites.js";
 import { isCdpMethodAllowed, cdpDenialMessage } from "./cdp-policy.js";
 import { SCREENSHOT_SCHEMA, SNAPSHOT_SCHEMA, TABS_SCHEMA } from "./tool-schemas.js";
 import { parseJsonText, extractionPrompt } from "./extract.js";
@@ -68,11 +69,37 @@ export function apply(ctx, config) {
         return id === undefined ? 'anonymous' : String(id);
     };
     /** Acquire the calling session's live browser session. */
+    /**
+     * Publish the "which sites look logged in" summary for the settings card. Throttled, and
+     * every failure is swallowed: this is a display nicety and must never slow down or break an
+     * action. Nothing here is model-visible — it travels only to the settings route.
+     */
+    let lastLoginPublish = 0;
+    const publishLogins = (session) => {
+        const now = Date.now();
+        if (now - lastLoginPublish < 5000)
+            return;
+        lastLoginPublish = now;
+        void session
+            .cookieJar()
+            .then(async (rows) => {
+            publishLoginSites(summarizeLoginSites(rows, 'live', now, {
+                visited: session.visitedHosts(),
+                titles: await session.siteTitles(),
+            }));
+        })
+            .catch(() => {
+            /* display-only: a failed cookie read must not surface as a tool failure */
+        });
+    };
     const acquire = (exec) => {
         if (!getEnabled()) {
             throw new BrowserError('DISABLED', 'dsh-browser-playwright-codex is disabled; open Settings → Plugins → 浏览器 and turn it on to use the browser');
         }
-        return ctx.browser.acquire(ownerFor(exec), exec.signal);
+        return ctx.browser.acquire(ownerFor(exec), exec.signal).then((session) => {
+            publishLogins(session);
+            return session;
+        });
     };
     const services = () => {
         const out = {};
@@ -137,46 +164,69 @@ export function apply(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: p('click'),
-        description: 'Click the element with the given ref from the latest snapshot and return the new snapshot. ' +
-            'Refs go stale after navigation or DOM changes — take a fresh ' +
-            p('snapshot') +
-            ' if a ref fails. ' +
-            'Prefer ref when the snapshot has one; for a target shown WITHOUT a ref (plain text, e.g. generic "设置", or a menu item ' +
-            p('hover') +
-            ' just revealed), pass text instead, copied exactly as rendered — a revealed item may need ' +
-            p('hover') +
-            ' first to stay on screen. ' +
-            'IRON RULE: after the click, verify in the returned snapshot that the intended effect actually happened (URL, selection, toast, dialog, new content). ' +
-            'A click can also succeed without changing this page: when the snapshot shows no change, check ' +
+        description: 'Click the target from the latest snapshot — or reveal it without clicking (mode:"hover") — and return the new snapshot. ' +
+            'Best target first: `ref` when the snapshot has one; `text`, a visible label copied exactly as rendered, for a target shown WITHOUT a ref; `x`+`y` viewport CSS pixels only as a last resort (canvas-drawn hit areas). Refs go stale after navigation or DOM changes: take a fresh snapshot if a ref fails. ' +
+            'mode:"hover" only REVEALS content and never activates: use it when a control hides content until the pointer rests on it, especially when the snapshot lacks an element the page obviously should have. A hover returning only means the pointer moved: read the note comparing the actionable ref count before and after; new refs mean pre-hover refs are stale, so act from the NEW refs before an unrelated click closes the menu. If that note reports no new refs, do NOT repeat the hover and do NOT fall back to raw coordinates — hover the parent/container or the sibling that owns the menu, otherwise use a visible alternative or tell the user. ' +
+            'precise:true takes a ref click down the geometric path instead: the element is scrolled into view and clicked at its exact centre through native input, with no screenshot measuring, no devicePixelRatio guesswork. It is the FALLBACK, not a routine alternative — use it only after a ref click reports the element is not actionable, or that the click could not be delivered. ' +
+            'IRON RULE: verify the effect in the returned snapshot (URL, selection, toast, dialog, new content). No change may still be success: check ' +
             p('tabs') +
-            ' for a new tab (a target="_blank" link) before concluding failure, and treat a same-page overlay or popup, URL unchanged and no new tab, as success — the returned snapshot is the evidence: compare its refs and content with the pre-click snapshot. ' +
-            'The snapshot may open with a landing note naming what received the click: if that is not your target, the click was intercepted — treat it as failed and retarget. ' +
-            'If there was no visible effect, do NOT blindly repeat the click and do NOT fall back to ' +
-            p('click_at') +
-            ' raw coordinates — inspect the visible state for the blocker or interception, resolve it, then retry the most direct semantic action. ' +
-            'If the click raises a native dialog, it stays PENDING and this call returns immediately with the dialog text instead of the page tree — answer it with ' +
+            ' for a new tab (a target="_blank" link) before concluding, and treat a same-page overlay as success. ' +
+            'The landing note names what received the click: if that is not your target the click was intercepted — treat it as failed and retarget; do NOT blindly repeat it and do NOT throw raw coordinates at it, but inspect the visible state for the blocker or interception first, resolve that, then retry the most direct semantic action. ' +
+            'A native dialog stays PENDING and this returns immediately with the dialog text; this tool cannot accept it — ' +
             p('dialog') +
-            '. This tool has no way to accept a dialog: accepting is a separate, deliberate call.',
+            ' is a separate, deliberate call.',
         parameters: {
             ref: {
                 type: 'string',
-                description: 'Element ref (e.g. e12) from the latest snapshot. Use this whenever the snapshot has a ref for the target.',
+                description: 'Element ref (e.g. e12) from the latest snapshot. Preferred whenever the snapshot has one.',
             },
             text: {
                 type: 'string',
-                description: 'Visible label of a target shown WITHOUT a ref (plain text, e.g. generic "搜索设置"). Copied exactly as the snapshot renders it; the first visible element whose own text matches is clicked and the landing note names it.',
+                description: 'Visible label of a target shown WITHOUT a ref, copied exactly as the snapshot renders it; the first visible element whose own text matches is used and the note names it.',
+            },
+            x: {
+                type: 'integer',
+                description: 'Viewport x in CSS pixels, with y: a raw click, mode "click" only, last resort.',
+            },
+            y: {
+                type: 'integer',
+                description: 'Viewport y in CSS pixels, with x: a raw click, mode "click" only, last resort.',
+            },
+            mode: {
+                type: 'string',
+                enum: ['click', 'hover'],
+                description: 'click (default) activates the target; hover only reveals it.',
+            },
+            precise: {
+                type: 'boolean',
+                description: 'Ref clicks only: click the geometric centre through native input instead of the standard click.',
             },
         },
         output: { schema: SNAPSHOT_SCHEMA, render: renderSnapshotValue },
         async execute(args, exec) {
             const session = await acquire(exec);
-            if (args.ref !== undefined && args.ref !== '') {
-                return snapshotValue(await session.click(args.ref, exec.signal));
+            const mode = args.mode ?? 'click';
+            if (mode !== 'click' && mode !== 'hover') {
+                throw new BrowserError('PARAM_MISSING', 'browser_click takes mode "click" or "hover", got: ' + String(args.mode));
+            }
+            const ref = args.ref !== undefined && args.ref !== '' ? args.ref : undefined;
+            const text = args.text !== undefined && args.text !== '' ? args.text : undefined;
+            const point = typeof args.x === 'number' && typeof args.y === 'number' ? { x: args.x, y: args.y } : undefined;
+            if (mode === 'hover') {
+                if (ref !== undefined)
+                    return snapshotValue(await session.hover(ref, exec.signal));
+                if (text !== undefined)
+                    return snapshotValue(await session.hoverText(text, exec.signal));
+                throw new BrowserError('PARAM_MISSING', 'browser_click with mode "hover" needs a ref from the latest snapshot, or the visible text label of a trigger that has no ref');
             }
-            if (args.text !== undefined && args.text !== '') {
-                return snapshotValue(await session.clickText(args.text, exec.signal));
+            if (ref !== undefined) {
+                return snapshotValue(args.precise === true ? await session.clickAtRef(ref, exec.signal) : await session.click(ref, exec.signal));
             }
-            throw new BrowserError('PARAM_MISSING', 'browser_click needs either a ref from the latest snapshot or the visible text label of a target that has no ref');
+            if (text !== undefined)
+                return snapshotValue(await session.clickText(text, exec.signal));
+            if (point !== undefined)
+                return snapshotValue(await session.clickAt(point.x, point.y, exec.signal));
+            throw new BrowserError('PARAM_MISSING', 'browser_click needs a target: a ref from the latest snapshot, the visible text label of a target that has no ref, or both x and y viewport coordinates');
         },
     }));
     ctx.tools.register(defineTool({
@@ -207,71 +257,10 @@ export function apply(ctx, config) {
             return snapshotValue(await session.resolveDialog(args.accept, args.promptText, exec.signal));
         },
     }));
-    ctx.tools.register(defineTool({
-        name: p('click_at'),
-        description: 'Precise native click, two modes. Ref mode (prefer it): pass ref — the element is scrolled into view, awaited for geometry stability, and clicked at its exact geometric centre through native input: no screenshot measuring, no devicePixelRatio guesswork. ' +
-            'Raw mode: pass x/y viewport CSS pixels to click a raw point with no element involvement. ' +
-            'This is the FALLBACK, not a routine alternative: try ' +
-            p('click') +
-            ' (including its text mode) first, and use ref mode only after a click reports the element is not actionable or the click could not be delivered. Raw x/y is a last resort for targets no ref resolves (canvas-drawn hit areas): raw clicks still return a landing note saying what they hit, so re-snapshot and confirm. ' +
-            'IRON RULE: verify the effect in the returned snapshot; if nothing changed, do NOT repeat blindly and do NOT throw more raw coordinates at it — find the blocker or interception first, then retry the most direct semantic action. ' +
-            'The snapshot may open with a landing note naming what received the click, or — when an intercepted ref-mode target had to fall back to a bare click at its centre — a CAUTION note: if the click was intercepted, treat it as failed and retarget.',
-        parameters: {
-            ref: {
-                type: 'string',
-                description: 'Element ref (e.g. e12) from the latest snapshot. If given, its geometric centre is clicked; x/y are ignored.',
-            },
-            x: { type: 'integer', description: 'Raw-mode viewport x in CSS pixels (required only when ref is omitted).' },
-            y: { type: 'integer', description: 'Raw-mode viewport y in CSS pixels (required only when ref is omitted).' },
-        },
-        output: { schema: SNAPSHOT_SCHEMA, render: renderSnapshotValue },
-        async execute(args, exec) {
-            const session = await acquire(exec);
-            if (args.ref !== undefined && args.ref !== '') {
-                return snapshotValue(await session.clickAtRef(args.ref, exec.signal));
-            }
-            if (typeof args.x !== 'number' || typeof args.y !== 'number') {
-                throw new BrowserError('PARAM_MISSING', 'browser_click_at needs a ref, or both x and y viewport coordinates');
-            }
-            return snapshotValue(await session.clickAt(args.x, args.y, exec.signal));
-        },
-    }));
-    ctx.tools.register(defineTool({
-        name: p('hover'),
-        description: 'Hover the element with the given ref — or, for a trigger the snapshot gave no ref, the visible element whose own label equals text — and return the new snapshot. ' +
-            'Hover only REVEALS content and never activates anything: use ' +
-            p('click') +
-            ' to open, select or submit. Use it when a control hides content until the pointer rests on it (submenus, dropdowns, account menus, tooltips, previews, chart values, player controls) — and especially when the snapshot lacks an element the page obviously should have. ' +
-            'Prefer ref when the snapshot has one; use text only for a label shown WITHOUT a ref, copied exactly as rendered. Do not hover plain links/buttons you mean to activate, and never hover "just in case". ' +
-            'A hover returning only means the pointer moved: the snapshot opens with a note comparing the actionable ref count before and after — read it. New refs mean the revealed content is in this snapshot and pre-hover refs are stale, so pick from the NEW refs and act before any unrelated click closes the menu. ' +
-            'IRON RULE: if the note reports no new refs and what you expected is still missing, do NOT repeat the hover and do NOT fall back to ' +
-            p('click_at') +
-            ' raw coordinates — hover the parent/container or the sibling that owns the menu; if that also reveals nothing, hover is not implemented here, so use a visible alternative or tell the user.',
-        parameters: {
-            ref: {
-                type: 'string',
-                description: 'Element ref (e.g. e12) from the latest snapshot. Use this whenever the snapshot has a ref for the trigger.',
-            },
-            text: {
-                type: 'string',
-                description: 'Visible label of a trigger shown WITHOUT a ref (plain text, e.g. generic "设置"). Copied exactly as the snapshot renders it; the first visible element whose own text matches is hovered and the note names it.',
-            },
-        },
-        output: { schema: SNAPSHOT_SCHEMA, render: renderSnapshotValue },
-        async execute(args, exec) {
-            const session = await acquire(exec);
-            if (args.ref !== undefined && args.ref !== '') {
-                return snapshotValue(await session.hover(args.ref, exec.signal));
-            }
-            if (args.text !== undefined && args.text !== '') {
-                return snapshotValue(await session.hoverText(args.text, exec.signal));
-            }
-            throw new BrowserError('PARAM_MISSING', 'browser_hover needs either a ref from the latest snapshot or the visible text label of a trigger that has no ref');
-        },
-    }));
     ctx.tools.register(defineTool({
         name: p('fill'),
         description: 'Replace the value of the input or select referenced by the latest snapshot. ' +
+            '`value` is accepted as an alias of `text`. ' +
             'For <select> elements the text selects the matching option label. ' +
             'IRON RULE: after filling, verify in the returned snapshot that the field actually holds the value. ' +
             'Frameworks can silently reject or transform input (controlled components, contenteditable editors, ' +
@@ -284,12 +273,27 @@ export function apply(ctx, config) {
             'say so) — understand why it was ignored, then act.',
         parameters: {
             ref: { type: 'string', required: true, description: 'Input or select ref (e.g. e7) from the latest snapshot.' },
-            text: { type: 'string', required: true, description: 'Exact value to fill, or option label for selects.' },
+            text: {
+                type: 'string',
+                description: 'Exact value to fill, or option label for selects. (In browser_click, `text` is a label to click instead.)',
+            },
+            value: { type: 'string', description: 'Alias of `text`; if both are given, `text` wins.' },
         },
         output: { schema: SNAPSHOT_SCHEMA, render: renderSnapshotValue },
         async execute(args, exec) {
+            // `text` deliberately is NOT `required: true` here, even though in practice you must give it
+            // (or `value`). The parameter DSL is a flat property map whose only requiredness is
+            // per-property, so it cannot express "exactly one of text/value" — the `oneOf` the compiled
+            // JSON Schema supports is value-level, not object-level. The requirement is therefore
+            // enforced below, before a session is acquired (a malformed call must not launch a browser),
+            // and the message names both spellings. 2026-10-16: a reviewing model passed `value` first
+            // and only got `invalid arguments: missing required property "text"` — no way forward.
+            const value = args.text ?? args.value;
+            if (value === undefined) {
+                throw new BrowserError('PARAM_MISSING', 'browser_fill needs the value to type: pass `text` (alias `value`). The `text` here is the value you type — for a visible label to click, use browser_click instead.');
+            }
             const session = await acquire(exec);
-            return snapshotValue(await session.fill(args.ref, args.text, exec.signal));
+            return snapshotValue(await session.fill(args.ref, value, exec.signal));
         },
     }));
     ctx.tools.register(defineTool({

package/lib/types.d.ts

@@ -2,6 +2,7 @@
  * Domain types for the browser capability: snapshots, sessions, providers.
  * @module dsh-browser-playwright-codex/types
  */
+import type { CookieRow } from './login-sites.ts';
 /** Page load condition a navigation waits for. */
 export type LoadState = 'load' | 'domcontentloaded' | 'networkidle';
 /** One snapshot element. Refs identify actionable elements for later calls. */
@@ -191,6 +192,18 @@ export interface BrowserSession {
     } | undefined, signal?: AbortSignal): Promise<ScreenshotCapture>;
     /** Extract the page's bounded data: text, links, forms, frames. */
     pageData(): Promise<unknown>;
+    /**
+     * Read this session's cookies for display-only login inference. Implementations must drop
+     * `value` before returning: the inference only needs names, domains and lifetime.
+     */
+    cookieJar(): Promise<readonly CookieRow[]>;
+    /**
+     * Registrable domains of the pages this browser has open, used to attribute cookies to the site
+     * that was visited rather than to whoever set them.
+     */
+    visitedHosts(): string[];
+    /** Page titles by registrable domain, for display only; empty when nothing is open. */
+    siteTitles(): Promise<Map<string, string>>;
     /** Evaluate one JavaScript expression and return its JSON result. */
     evaluate(expression: string, signal?: AbortSignal): Promise<unknown>;
     /** Click the element whose visible text matches, by semantic locator. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-browser-playwright-codex",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Browser automation for DeepSeek Harness: fill in forms, scrape lists and work across tabs in real pages, using the logins you already have. Runs in a visible window that stays quiet when minimised, and stops for sign-ins, CAPTCHAs and native dialogs instead of confirming for you.",
   "license": "MIT",
   "type": "module",
@@ -37,10 +37,12 @@
     "README.md",
     "CHANGELOG.md",
     "SECURITY.md",
+    "NOTICE.md",
     "locale"
   ],
   "scripts": {
     "build": "node node_modules/typescript/bin/tsc -p tsconfig.json",
+    "typecheck": "node node_modules/typescript/bin/tsc -p tsconfig.tests.json",
     "test": "node --test \"tests/*.test.ts\"",
     "test:scenarios": "node --test tests/scenarios.test.ts tests/tool-scenarios.test.ts",
     "test:live": "node --test tests/live-smoke.test.ts",
@@ -50,7 +52,8 @@
     "cost": "node node_modules/tsx/dist/cli.mjs scripts/measure-prompt-cost.mjs",
     "format": "node node_modules/prettier/bin/prettier.cjs --write \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.mjs\"",
     "format:check": "node node_modules/prettier/bin/prettier.cjs --check \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.mjs\"",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "npm run build && npm run typecheck && npm test && npm run verify && npm run preflight",
+    "preflight": "node scripts/preflight.mjs ."
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "*",

package/scripts/preflight.mjs

@@ -0,0 +1,192 @@
+/**
+ * 发版前置审计（preflight）：把"文档对世界说的话"和"包里到底装了什么"一次查干净。
+ *
+ * 为什么有这个脚本（2026-10-11，用户第二次因此不满）：
+ *   之前是"只改点不看面"—— 修了 README 的 npm 说法，却没查 SECURITY 的计数、NOTICE 的路径、
+ *   发帖草稿里的数字、以及"文档引用的文件/行号在重构后是否还存在"。用户的原话是
+ *   「你能不能检查清楚再发新版本啊，别给我检查出来又一堆 bug」。所以这份检查挂在 `prepublishOnly`
+ *   上：**不通过就发不出去**，而不是等用户事后发现。
+ *
+ * 三类输出，语义严格区分：
+ *   ✗ 必须修   —— 硬错误（文件读不到、清单缺项、路径/行号/链接失效、测试失败、计数与实测不符）
+ *   ？ 待确认 —— 可能是历史、上游或有意为之（例如 "published since v0.5.1"、上游插件的旧包名）
+ *   ✓ 已一致   —— 已经核对过的基线数字
+ *
+ * 规则刻意收窄避免噪声（第一版误报过：把 IP 当版本号、把上游文档的版本当我们的、把竞品的工具数
+ * 当我们的、把"三个闸门合计 127 token"这个子项当成总成本）。
+ *
+ * 用法: node preflight.mjs [项目根]     退出码: 0 通过 / 2 有硬错误
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = resolve(process.argv[2] ?? join(dirname(fileURLToPath(import.meta.url)), '..'))
+const problems = []
+const confirm = []
+const ok = []
+
+const readOrThrow = (rel) => {
+  const p = join(root, rel)
+  if (!existsSync(p)) throw new Error('读不到文件（硬错误，不许当通过）：' + rel)
+  return readFileSync(p, 'utf8')
+}
+
+// ── A. 包里装了什么 ───────────────────────────────────────────────────────────
+const packed = new Set(
+  JSON.parse(
+    execFileSync('npm', ['pack', '--dry-run', '--json'], { cwd: root, encoding: 'utf8', shell: true }),
+  )[0].files.map((f) => f.path),
+)
+// 这些是"用户从 npm 装到之后必须能看到"的文件：许可证与归属声明（NOTICE）、安全说明、变更记录、
+// 以及让 Gradle 式的 loader 能挂载的 cordis.patch.yml。2026-10-11 的审计就是靠这份清单抓到
+// NOTICE.md 一直没进包（npm 只会自动带上 LICENSE，不会带 NOTICE）。
+const SHOULD_SHIP = [
+  'package.json',
+  'README.md',
+  'CHANGELOG.md',
+  'SECURITY.md',
+  'NOTICE.md',
+  'LICENSE',
+  'cordis.patch.yml',
+  'locale/en.json',
+  'locale/zh.json',
+]
+for (const f of SHOULD_SHIP) if (!packed.has(f)) problems.push('包里缺文件：' + f)
+if (![...packed].some((p) => p.startsWith('lib/'))) problems.push('包里没有 lib/（插件实际加载的就是它）')
+if ([...packed].some((p) => p.startsWith('src/') || p.startsWith('tests/'))) problems.push('包里不该有 src/ 或 tests/')
+if ([...packed].some((p) => p.endsWith('.bak'))) problems.push('包里有 .bak 残渣')
+ok.push('包内 ' + packed.size + ' 个文件；已确认含 lib/、locale/、cordis.patch.yml，且不含 src/tests/.bak')
+
+// ── B. 基线数字（来自命令本身，不是文档自述） ─────────────────────────────────
+const pkg = JSON.parse(readOrThrow('package.json'))
+const cost = execFileSync('npm', ['run', 'cost'], { cwd: root, encoding: 'utf8', shell: true })
+const toolCount = Number((cost.match(/工具数[:：]\s*(\d+)/) ?? [])[1])
+const chars = Number((cost.match(/字符总数[:：]\s*(\d+)/) ?? [])[1])
+const tokens = Number((cost.match(/粗估 token[:：]\s*~?(\d+)/) ?? [])[1])
+if (!toolCount || !chars || !tokens) problems.push('拿不到 npm run cost 的数字')
+else ok.push('成本基线：' + toolCount + ' 工具 / ' + chars + ' 字符 / ~' + tokens + ' token/轮')
+
+const suite = execFileSync('node', ['--test', 'tests/*.test.ts'], { cwd: root, encoding: 'utf8', shell: true })
+const n = (re) => Number((suite.match(re) ?? [])[1])
+if (n(/ℹ fail (\d+)/) > 0) problems.push('测试有失败：' + n(/ℹ fail (\d+)/) + ' 条')
+else
+  ok.push(
+    '测试：' + n(/ℹ tests (\d+)/) + ' / pass ' + n(/ℹ pass (\d+)/) + ' / fail 0 / skipped ' + n(/ℹ skipped (\d+)/),
+  )
+
+// ── C. 文档断言 ───────────────────────────────────────────────────────────────
+const docFiles = []
+const walk = (dir) => {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (e.name === 'node_modules' || e.name === '.git') continue
+    const p = join(dir, e.name)
+    if (e.isDirectory()) walk(p)
+    else if (e.name.endsWith('.md')) docFiles.push(relative(root, p).replace(/\\/g, '/'))
+  }
+}
+walk(root)
+const HISTORY = new Set(['CHANGELOG.md'])
+/** 上游项目（被借鉴的那个插件）自己的文档：里面出现旧包名/旧版本是对的。 */
+const UPSTREAM_DOCS = new Set([
+  'PLUGIN-README.md',
+  'codex-rules.md',
+  'patches/README.md',
+  'docs/articles/focus-stealing.md',
+])
+const current = docFiles.filter((f) => !HISTORY.has(f))
+
+const basenames = new Set()
+for (const dir of ['', 'src', 'lib', 'scripts', 'tests', 'locale', 'patches', 'docs', 'docs/articles']) {
+  const abs = dir ? join(root, dir) : root
+  if (!existsSync(abs)) continue
+  for (const e of readdirSync(abs, { withFileTypes: true })) if (e.isFile()) basenames.add(e.name)
+}
+
+for (const f of docFiles) {
+  const text = readOrThrow(f)
+  const currentDoc = current.includes(f)
+  text.split('\n').forEach((line, i) => {
+    const where = f + ':' + (i + 1)
+    const historical = /(since|since v|起|之前|以后|published|发布|历史|历史值|for the record|v0[.]4)/i.test(line)
+
+    // C1. 看起来是"本包版本"的数字
+    if (currentDoc && !historical) {
+      const notOurs =
+        /(Node|node|playwright-core|upstream|上游|Chenyu|Codex|scan of|扫描|dsh-plugin-vet|electron)/i.test(line)
+      for (const m of line.matchAll(/\bv(\d+\.\d+\.\d+)\b/g)) {
+        if (notOurs) break
+        if (m[1] !== pkg.version)
+          confirm.push(where + ' 提到版本 v' + m[1] + '（当前 ' + pkg.version + '）→ ' + line.trim().slice(0, 80))
+      }
+    }
+
+    // C2. 写死的工具数：只有当这句在说"我们"时才核对（竞品对照说的是别人）
+    const tc = line.match(/\b(\d{2})\s*(?:个)?\s*(?:browser_\*?\s*)?(?:tools|工具)/i)
+    if (currentDoc && tc && Number(tc[1]) >= 10) {
+      const aboutUs = /(我们|this package|本包|registered|注册)/i.test(line)
+      const aboutThem = /(同类|竞品|其它|其他|competitor|alternative|更轻)/i.test(line)
+      if (aboutUs && !aboutThem && Number(tc[1]) !== toolCount)
+        problems.push(where + ' 写死工具数 ' + tc[1] + '（实测 ' + toolCount + '）')
+    }
+
+    // C3. 写死的总成本：只核对"总计/常驻"这类句子，且量级要像总数（≈127 这种子项不算）
+    const tk = line.match(/\b(\d[\d,]{2,6})\s*(?:tokens?|token)/i)
+    if (currentDoc && tk) {
+      const value = Number(tk[1].replace(/,/g, ''))
+      const aboutTotal = /(常驻|总计|合计|resident|per turn|每轮)/i.test(line)
+      if (aboutTotal && value >= 500 && Math.abs(value - tokens) > 200)
+        problems.push(where + ' 写死的总 token 数 ' + tk[1] + '（实测 ~' + tokens + '）')
+    }
+
+    // C4. 旧包名：.state.json 是刻意保留的；上游文档里出现是对的
+    if (
+      /dsh-browser-playwright(?!-codex)/.test(line) &&
+      !UPSTREAM_DOCS.has(f) &&
+      !/\.state\.json/.test(line) &&
+      !/(上游|upstream|Chenyu)/i.test(line)
+    ) {
+      confirm.push(where + ' 出现旧包名（确认语境）→ ' + line.trim().slice(0, 80))
+    }
+
+    // C5. 反引号里的仓库路径
+    for (const m of line.matchAll(/`([A-Za-z0-9._/-]+\.(?:md|ts|js|mjs|cjs|json|yml|yaml))`/g)) {
+      const p = m[1]
+      if (!p.includes('/') || p.startsWith('~') || p.startsWith('http')) continue
+      const abs = p.startsWith('.') ? resolve(root, f, '..', p) : join(root, p)
+      if (existsSync(abs)) continue
+      if (basenames.has(p.slice(p.lastIndexOf('/') + 1)))
+        problems.push(where + ' 路径写错：`' + p + '`（文件在本仓库，但不在这个位置）')
+    }
+
+    // C6. 「文件:行号」引用
+    for (const m of line.matchAll(/([A-Za-z0-9_./-]+\.(?:ts|js|mjs|cjs|json|yml))[^\n]{0,12}?[:(]\s*~?:?(\d{3,5})/g)) {
+      const abs = join(root, m[1].replace(/^\.\//, ''))
+      if (!existsSync(abs)) continue
+      const lines = readFileSync(abs, 'utf8').split('\n').length
+      if (Number(m[2]) > lines)
+        problems.push(where + ' 行号越界：' + m[1] + ':' + m[2] + '（该文件现在 ' + lines + ' 行）')
+    }
+  })
+  // C7. markdown 相对链接
+  for (const m of readOrThrow(f).matchAll(/\]\(([^)#\s]+)(?:#[^)]*)?\)/g)) {
+    const target = m[1]
+    if (/^(https?:|mailto:)/.test(target) || target.startsWith('#')) continue
+    if (!existsSync(resolve(root, f, '..', target))) problems.push(f + ' markdown 链接失效：' + target)
+  }
+}
+
+// ── 输出 ─────────────────────────────────────────────────────────────────────
+console.log('=== ✗ 必须修（硬错误）===')
+console.log(problems.length ? problems.map((p) => '  ✗ ' + p).join('\n') : '  （无）')
+console.log('')
+console.log('=== ？ 待确认（历史 / 上游 / 有意为之）===')
+const uniqueConfirm = [...new Set(confirm)]
+console.log(uniqueConfirm.length ? uniqueConfirm.map((c) => '  ？ ' + c).join('\n') : '  （无）')
+console.log('')
+console.log('=== ✓ 已核对 ===')
+console.log(ok.map((o) => '  ✓ ' + o).join('\n'))
+console.log('')
+console.log('结论：' + problems.length + ' 处硬错误、' + uniqueConfirm.length + ' 处待确认。')
+process.exitCode = problems.length ? 2 : 0