@thincoder/core 0.10.5 → 0.10.6

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to the core package are documented here.
 Format: Keep a Changelog · 中文 · 号在发布时定（CalVer——见 `docs/RELEASE.md` §4）。
 
+## [0.10.6] — 2026-10-13
+
+> 0.10.5 → 0.10.6（月内 +1——发布时定号；P0 热修）
+
+### Fixed
+
+- **核包 `files` 白名单补 `browser/`**（P0——0.10.5 装机缺该目录 ⇒ CLI 装后启动崩（`ERR_MODULE_NOT_FOUND`）：`tools/browser.mjs:13-15` ∥ `permission.mjs:16` 引 `../browser/*` 而白名单未列；台账 #1362）。发布守则教训：白名单须覆盖运行时引用闭包——发布预检现只对根 `.mjs` ∥ `prompts/` ∥ `tool-docs/` 计数（引闭包断言待另轮补，已登记）。
+
 ## [0.10.5] — 2026-10-13
 
 > 0.10.4 → 0.10.5（月内 +1——发布时定号）

package/browser/actions.mjs

@@ -0,0 +1,163 @@
+/**
+ * browser/actions.mjs — 基线八动作实现（navigate / snapshot / click / type / evaluate / wait / screenshot / close）
+ * （BROWSER-TOOL.md §2.2 ∥ §2.4；KD-10：click / type 内部选型**不迁** Input 域——对外语义零回归）。
+ *
+ * 会话能力一律经句柄取（`h.call` / `h.evalRaw` / `h.takeSnapshot` / `h.ensureSession` / `h.pageError` /
+ * `h.step` / `h.sleep` …）——本档不 import `session.mjs`（DAG 单向，§5 拆分决定）。
+ * 硬超时（§2.9）：wait 的谓词帽（`timeoutMs`：缺省 30s · 上限 120s）语义零变——动作预算 = 谓词帽 + 15s
+ * 余量（`queue.mjs` 预算表）；轮询循环标 `wait poll` 步名（卡点可诊断——N-BT10）。
+ */
+import { DEFAULT_MAX, clickExpression, typeExpression, truncateText, waitExpression } from "./snapshot.mjs"
+
+export const WAIT_TIMEOUT_DEFAULT = 30_000
+export const WAIT_TIMEOUT_MAX = 120_000
+export const WAIT_POLL_MS = 150
+export const NETWORK_QUIET_MS = 500
+export const MAX_EVAL_CHARS = 8_000
+
+function normalizeHttpUrl(value) {
+  const raw = String(value ?? "")
+  let url
+  try { url = new URL(raw) } catch { url = null }
+  if (!url || (url.protocol !== "http:" && url.protocol !== "https:")) {
+    throw new Error(`navigate requires an http/https url — got "${raw}"`)
+  }
+  return url.toString()
+}
+
+function jsonOf(value) {
+  if (value === undefined) return "undefined"
+  try { return JSON.stringify(value) ?? String(value) }
+  catch { return String(value) }
+}
+
+/** navigate（§2.2）：http/https 限；回执 = `[navigate] <final-url>` + 内联新页快照（省一轮 snapshot）。 */
+async function actNavigate(args, ctx, h) {
+  const url = normalizeHttpUrl(args.url)
+  h.assertHostAllowed(url, ctx) // 静态参数面先检——被拦的 host 不得起浏览器（§3.2「不执行」）
+  await h.ensureSession(args)
+  await h.call("Page.navigate", { url })
+  await h.waitForReady()
+  const snap = await h.takeSnapshot({ max: DEFAULT_MAX })
+  return `[navigate] ${snap.url}\n${snap.text}`
+}
+
+/** snapshot（§2.2）：引用清单（生成 / 复用 / 标记——§2.3）。 */
+async function actSnapshot(args, ctx, h) {
+  await h.ensureSession(args)
+  const snap = await h.takeSnapshot({ selector: args.selector ?? null, max: args.max ?? DEFAULT_MAX })
+  return snap.text
+}
+
+/** click（§2.2）：DOM 级语义激活（`el.click()`——KD-10）；导航判据 = URL 变化 ⇒ `[navigated]` / `[no navigation]`。 */
+async function actClick(args, ctx, h) {
+  await h.ensureSession(args)
+  const info = await h.pageInfo()
+  h.assertHostAllowed(info.url, ctx)
+  const entry = h.resolveRef(args.ref)
+  const res = await h.evalRaw(clickExpression(entry.selector, entry.tag))
+  if (!res?.found || res.tag) throw h.pageError(`ref ${args.ref} is stale (was "${entry.name}") — run snapshot again`)
+  if (res.disabled) throw h.pageError(`ref ${args.ref} is disabled ("${entry.name}")`)
+  const out = [`[click] ${args.ref} "${entry.name}"`]
+  const landed = await h.waitForUrlChange(info.url)
+  if (landed) {
+    await h.waitForReady()
+    const snap = await h.takeSnapshot({ max: DEFAULT_MAX })
+    out.push(`[navigated] ${snap.url}`, snap.text)
+  } else {
+    out.push("[no navigation]")
+  }
+  return out.join("\n")
+}
+
+/** type（§2.2）：写值（原生 value setter + input/change）；password 目标 ⇒ 值不回显（N-BT4）。 */
+async function actType(args, ctx, h) {
+  await h.ensureSession(args)
+  const info = await h.pageInfo()
+  h.assertHostAllowed(info.url, ctx)
+  const entry = h.resolveRef(args.ref)
+  const text = String(args.text)
+  const res = await h.evalRaw(typeExpression(entry.selector, entry.tag, text, args.clear === true))
+  if (!res?.found || res.tag) throw h.pageError(`ref ${args.ref} is stale (was "${entry.name}") — run snapshot again`)
+  if (res.fillable === false) {
+    throw h.pageError(`ref ${args.ref} is not a fillable field ("${entry.name}", <${entry.tag}>) — use snapshot to pick an input/textarea`)
+  }
+  if (res.disabled) throw h.pageError(`ref ${args.ref} is disabled ("${entry.name}")`)
+  return `[type] ${args.ref} "${entry.name}" ← ${text.length} chars${res.password ? " (hidden)" : ""}`
+}
+
+/** evaluate（§2.2）：页面上下文 JS；异常 ⇒ `Error: evaluate failed: <message>`；回执受 8000 字符上限（N-BT3）。 */
+async function actEvaluate(args, ctx, h) {
+  await h.ensureSession(args)
+  const info = await h.pageInfo()
+  h.assertHostAllowed(info.url, ctx)
+  let value
+  try {
+    value = await h.evalRaw(String(args.expression))
+  } catch (e) {
+    if (e?.browserAbort || e?.sessionLost) throw e // 预算中止 / 外部关闭 ⇒ 原样上报（不裹进页面异常句）
+    throw h.pageError(`evaluate failed: ${e?.message ?? e}`)
+  }
+  return `[evaluate @ ${info.url}] ${truncateText(jsonOf(value), MAX_EVAL_CHARS, "narrow the expression")}`
+}
+
+function waitPredicate(args) {
+  if (args.networkIdle === true) return { kind: "networkIdle", value: null, label: "networkIdle" }
+  for (const kind of ["selector", "text", "url"]) {
+    const value = args[kind]
+    if (typeof value === "string" && value !== "") return { kind, value, label: `${kind} ${JSON.stringify(value)}` }
+  }
+  // 工具层已校验互斥（§2.2）——此处兜底（直调会话面时同样不悬挂）
+  throw new Error("wait requires exactly one of selector|text|url|networkIdle")
+}
+
+/** wait（§2.2）：四选一谓词 + 150ms 轮询；networkIdle = 事件在飞归零后静默 500ms。 */
+async function actWait(args, ctx, h) {
+  await h.ensureSession(args)
+  const pred = waitPredicate(args)
+  const wanted = Number(args.timeoutMs)
+  const timeoutMs = Math.max(1, Math.min(Number.isFinite(wanted) && wanted > 0 ? wanted : WAIT_TIMEOUT_DEFAULT, WAIT_TIMEOUT_MAX))
+  const started = Date.now()
+  return h.step("wait poll", async () => {
+    for (;;) {
+      if (pred.kind === "networkIdle") {
+        const net = h.networkState()
+        if (net.inflight.size === 0 && Date.now() - net.lastEventAt >= NETWORK_QUIET_MS) break
+      } else if (await h.evalRaw(waitExpression(pred.kind, pred.value)) === true) break
+      if (Date.now() - started >= timeoutMs) throw h.pageError(`wait timed out after ${timeoutMs}ms (${pred.label})`)
+      await h.sleep(WAIT_POLL_MS)
+    }
+    return `[wait] ${pred.label} — ok after ${Date.now() - started}ms`
+  })
+}
+
+/** screenshot（§2.2）：PNG 落盘返路径（KD-6——模型经 read_image 查看）。 */
+async function actScreenshot(args, ctx, h) {
+  await h.ensureSession(args)
+  const shot = await h.call("Page.captureScreenshot", {
+    format: "png",
+    ...(args.fullPage === true ? { captureBeyondViewport: true } : {}),
+  })
+  if (typeof shot?.data !== "string") throw new Error("screenshot failed: the browser returned no image data")
+  const saved = await h.saveShot(Buffer.from(shot.data, "base64"))
+  return `[screenshot] ${saved.path} (${saved.bytes} bytes)`
+}
+
+/** close（§2.2）：幂等——无会话 ⇒ `[close] no browser session`（成功态）。 */
+async function actClose(args, ctx, h) {
+  if (!h.connection()) return "[close] no browser session"
+  await h.closeSession()
+  return "[close] browser session closed"
+}
+
+/** 基线八动作分发表（会话档并入总表——§5）。 */
+export const ACTIONS = {
+  navigate: actNavigate,
+  snapshot: actSnapshot,
+  click: actClick,
+  type: actType,
+  evaluate: actEvaluate,
+  wait: actWait,
+  screenshot: actScreenshot,
+  close: actClose,
+}

package/browser/cdp.mjs

@@ -0,0 +1,161 @@
+/**
+ * browser/cdp.mjs — CDP 传输客户端（零第三方——N-BT1：Node ≥ 24 原生 WebSocket）。
+ *
+ * 形沿 `scripts/console-walkthrough.mjs:133-141` 的实证客户端（id 派发 ∥ 事件派发）——本文档把它
+ * 拆成类以承载多动作会话（connect / call / on / close），并加 HTTP 面 `/json/new` 取标签页。
+ * `WebSocketImpl` = 注入缝（缺省 `globalThis.WebSocket`；单元测试注假传输——缺省回落真实现，`??`）。
+ *
+ * 错误语义：CDP 回 `{ error: { message } }` ⇒ 拒以 `Error(message)`（BROWSER-TOOL.md §5）。
+ * 帽（§2.9 三层帽——层二 / 层三）：`call` 缺省帽 15s（任何未显式配帽的调用也不悬挂）；`connectCdp` open 帽
+ * 10s；`/json/new` fetch 帽 5s——动作内调用另随动作控制器（session 侧接线，预算先行）。
+ * 断连面：WS `onclose` / `onerror` ⇒ 拒在飞命令**并通知订阅者**（session 据此复位会话态——§2.10 源②）。
+ */
+
+/** `call` 缺省兜底帽（§2.9 层三——未显式配帽的调用同样有界）。 */
+export const DEFAULT_CALL_TIMEOUT_MS = 15_000
+/** `connectCdp` open 帽（§2.9 层二）。 */
+export const CONNECT_TIMEOUT_MS = 10_000
+/** `/json/new` fetch 帽（§2.9 层二）。 */
+export const NEWTAB_TIMEOUT_MS = 5_000
+
+/** 与浏览器标签页的一条 CDP 连接。 */
+export class CdpClient {
+  constructor(ws) {
+    this._ws = ws
+    this._nextId = 0
+    this._pending = new Map()
+    this._listeners = new Map()
+    this._disconnects = []
+    this.closed = false
+    ws.onmessage = (ev) => this._onMessage(ev)
+    ws.onclose = () => this._die(new Error("CDP connection closed"))
+    ws.onerror = () => this._die(new Error("CDP connection error"))
+  }
+
+  _onMessage(ev) {
+    let msg
+    try { msg = JSON.parse(ev.data) } catch { return } // 非 JSON 帧（调试器噪声）忽略
+    if (msg.id !== undefined && this._pending.has(msg.id)) {
+      const p = this._pending.get(msg.id)
+      this._pending.delete(msg.id)
+      if (msg.error) p.reject(new Error(msg.error.message ?? JSON.stringify(msg.error)))
+      else p.resolve(msg.result ?? {})
+      return
+    }
+    const handlers = msg.method ? this._listeners.get(msg.method) : null
+    if (!handlers) return
+    for (const handler of handlers) {
+      try { handler(msg.params ?? {}, msg.method) } catch { /* 订阅者自担——一条订阅抛错不打断派发 */ }
+    }
+  }
+
+  /** 连接断（WS close/error）单点：通知订阅者（先）⇒ 拒在飞命令（同一因由实例——§2.10）。 */
+  _die(error) {
+    if (this.closed) return
+    this.closed = true
+    for (const handler of this._disconnects) {
+      try { handler(error) } catch { /* 订阅者自担 */ }
+    }
+    this._abortAll(error)
+  }
+
+  _abortAll(error) {
+    for (const pending of this._pending.values()) pending.reject(error)
+    this._pending.clear()
+  }
+
+  /** 订阅断连（会话健康接线——§2.10 源②）；返回退订函数。 */
+  onDisconnect(handler) {
+    this._disconnects.push(handler)
+    return () => { this._disconnects = this._disconnects.filter((h) => h !== handler) }
+  }
+
+  /** 发一条 CDP 命令，解析其 result（失败拒以 `Error`）；缺省帽 15s（§2.9 层三）。 */
+  call(method, params = {}, { timeoutMs = DEFAULT_CALL_TIMEOUT_MS } = {}) {
+    if (this.closed) return Promise.reject(new Error("CDP client is closed"))
+    const id = ++this._nextId
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._pending.delete(id)
+        const error = new Error(`${method} did not respond within ${timeoutMs}ms`)
+        error.cdpTimeout = true
+        reject(error)
+      }, timeoutMs)
+      timer.unref?.() // 挂死型调用不吊住宿主进程（命令真返回时在 settle 里清钟）
+      const settle = (fn, value) => { clearTimeout(timer); this._pending.delete(id); fn(value) }
+      this._pending.set(id, { resolve: (v) => settle(resolve, v), reject: (e) => settle(reject, e) })
+      try { this._ws.send(JSON.stringify({ id, method, params })) }
+      catch (e) { settle(reject, e) }
+    })
+  }
+
+  /** 订阅 CDP 事件（无 id 帧）；返回退订函数。 */
+  on(method, handler) {
+    const list = this._listeners.get(method) ?? []
+    list.push(handler)
+    this._listeners.set(method, list)
+    return () => this._listeners.set(method, (this._listeners.get(method) ?? []).filter((h) => h !== handler))
+  }
+
+  close() {
+    if (this.closed) return
+    this.closed = true
+    this._abortAll(new Error("CDP client closed"))
+    try { this._ws.close() } catch { /* 已断开 */ }
+  }
+}
+
+/**
+ * 连标签页调试地址（open 帽 10s——§2.9 层二）。
+ * @param {string} wsUrl `webSocketDebuggerUrl`
+ * @param {{WebSocketImpl?: Function, openTimeoutMs?: number}} [opts] 注入缝 ∥ open 帽
+ */
+export async function connectCdp(wsUrl, { WebSocketImpl, openTimeoutMs = CONNECT_TIMEOUT_MS } = {}) {
+  const Impl = WebSocketImpl ?? globalThis.WebSocket
+  if (typeof Impl !== "function") {
+    throw new Error("no WebSocket implementation available — Node >= 24 required (CDP transport is stdlib-only)")
+  }
+  const ws = new Impl(wsUrl)
+  await new Promise((resolve, reject) => {
+    let settled = false
+    const finish = (fn, value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      fn(value)
+    }
+    const timer = setTimeout(
+      () => finish(reject, new Error(`failed to connect to CDP at ${wsUrl} (no response within ${openTimeoutMs}ms)`)),
+      openTimeoutMs,
+    )
+    timer.unref?.()
+    ws.onopen = () => finish(resolve)
+    ws.onerror = () => finish(reject, new Error(`failed to connect to CDP at ${wsUrl}`))
+  })
+  return new CdpClient(ws)
+}
+
+/** 开一张标签页并取其调试地址（`PUT /json/new`，GET 兜底——walkthrough `:131-132` 同式；fetch 帽 5s）。 */
+export async function newTabWebSocketUrl(port, { host = "127.0.0.1", fetchImpl = globalThis.fetch, timeoutMs = NEWTAB_TIMEOUT_MS } = {}) {
+  const url = `http://${host}:${port}/json/new?about:blank`
+  let timer = null
+  const deadline = new Promise((_, reject) => {
+    timer = setTimeout(
+      () => reject(new Error(`browser did not answer /json/new within ${timeoutMs}ms (port ${port})`)),
+      timeoutMs,
+    )
+    timer.unref?.()
+  })
+  const fetchTab = async (init) => (await fetchImpl(url, init)).json()
+  try {
+    let tab
+    try { tab = await Promise.race([fetchTab({ method: "PUT" }), deadline]) }
+    catch { tab = await Promise.race([fetchTab(), deadline]) } // GET 兜底（同帽——到点即拒，不悬挂）
+    if (!tab?.webSocketDebuggerUrl) {
+      throw new Error(`browser did not return a debuggable tab from /json/new (port ${port})`)
+    }
+    return tab.webSocketDebuggerUrl
+  } finally {
+    if (timer) clearTimeout(timer)
+  }
+}

package/browser/clipboard.mjs

@@ -0,0 +1,142 @@
+/**
+ * browser/clipboard.mjs — 剪贴板动作（read / write / copy / paste）∥ Browser 域授权 ∥ 页侧表达式
+ * （BROWSER-TOOL.md §3.5 ∥ §2.2 clipboard ∥ N-BT9）。
+ *
+ * 路径（KD-13）：CDP 无剪贴板直控方法 ⇒ 页面 API（`navigator.clipboard`）+ Browser 域按 origin 惰性授予；
+ * `write` 页面拒 / 非安全上下文 ⇒ 回落 `document.execCommand('copy')` 隐藏 textarea 面（再败才报错）。
+ * copy / paste = 真加速键（平台分支：darwin ⇒ Meta+C/V；win32 / linux ⇒ Ctrl+C/V——受信按键直驱浏览器复制 / 粘贴）。
+ * 隐私（N-BT9）：read 回执上限 8000 字符 + 截断标记；write 回执不回显文本；剪贴板内容不落盘、不写日志（本档零 fs 面）。
+ */
+import { pressSequence } from "./input.mjs"
+import { truncateText } from "./snapshot.mjs"
+
+export const CLIPBOARD_MAX_CHARS = 8_000
+export const CLIPBOARD_OPS = ["read", "write", "copy", "paste"]
+/** `Browser.setPermission` 取的描述符名（实测在册可用——PermissionDescriptor ≠ PermissionType）。 */
+export const CLIPBOARD_PERMISSION_DESCRIPTORS = ["clipboard-read", "clipboard-write"]
+/** `Browser.grantPermissions` 取的权限枚举（PermissionType——回落面，两法同名不同名面，实测在案）。 */
+export const CLIPBOARD_PERMISSIONS = ["clipboardReadWrite", "clipboardSanitizedWrite"]
+
+const mark = (kind) => `/*thincoder-browser:${kind}*/`
+
+/** 授权缓存（§3.5：会话内按 origin 缓存——close / 换 origin 重授；键 = 连接身份）。 */
+let grantCache = { client: null, origins: new Set() }
+/** 无头焦点模拟缓存（§3.5：会话内一次性——仅剪贴板动作触发，不进其他动作路径）。 */
+let focusCache = { client: null, done: false }
+
+/** 无头焦点适配：`document.hasFocus()` 为假 ⇒ `Emulation.setFocusEmulationEnabled`（一次/会话）。 */
+async function ensureFocusEmulation(h) {
+  const client = h.connection()
+  if (client && focusCache.client === client && focusCache.done) return
+  let hasFocus = true
+  try { hasFocus = (await h.evalRaw("document.hasFocus()")) === true } catch { hasFocus = true } // 页不可读 ⇒ 不模拟
+  if (!hasFocus) await h.call("Emulation.setFocusEmulationEnabled", { enabled: true })
+  focusCache = { client, done: true }
+}
+
+/**
+ * 按当前页 origin 惰性授予（§3.5）：`setPermission` 两权（描述符名）→ 方法缺 / 拒 ⇒ `grantPermissions`
+ * 回落（PermissionType 枚举）→ 再败明示错。实测（本机 Edge）：`setPermission` 只认描述符名
+ * （`clipboard-read` / `clipboard-write`）；PermissionType 名在该方法上被拒（版本 / 名面漂移——回落层兜住）。
+ */
+async function ensureClipboardPermission(h, origin) {
+  const client = h.connection()
+  if (grantCache.client !== client) grantCache = { client, origins: new Set() }
+  if (grantCache.origins.has(origin)) return
+  try {
+    for (const name of CLIPBOARD_PERMISSION_DESCRIPTORS) {
+      await h.call("Browser.setPermission", { permission: { name }, setting: "granted", origin })
+    }
+  } catch (e) {
+    try {
+      await h.call("Browser.grantPermissions", { permissions: CLIPBOARD_PERMISSIONS, origin })
+    } catch (e2) {
+      throw h.pageError(`clipboard permission failed — setPermission: ${e?.message ?? e}; grantPermissions fallback: ${e2?.message ?? e2}`)
+    }
+  }
+  grantCache.origins.add(origin)
+}
+
+/** 当前页 origin（授权键）；无真实页 origin（about:blank 等）⇒ 明示拒（不静默降级）。 */
+async function pageOrigin(h) {
+  const info = await h.pageInfo()
+  let origin = null
+  try { origin = new URL(info.url).origin } catch { origin = null }
+  if (!origin || origin === "null") throw h.pageError(`clipboard requires an http/https page origin — current page is "${info.url}"`)
+  return origin
+}
+
+/** 页侧写表达式：`navigator.clipboard.writeText` → 失败回落 `document.execCommand('copy')` 隐藏 textarea。 */
+function clipboardWriteExpression(text) {
+  return `${mark("clipboard-write")}(async function () {
+  var text = ${JSON.stringify(text)}
+  try {
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      await navigator.clipboard.writeText(text)
+      return { ok: true, via: 'navigator.clipboard' }
+    }
+  } catch (e) { /* 页面拒 / 非安全上下文 ⇒ 走 execCommand 回落 */ }
+  try {
+    var ta = document.createElement('textarea')
+    ta.value = text
+    ta.setAttribute('readonly', '')
+    ta.style.position = 'fixed'
+    ta.style.opacity = '0'
+    document.body.appendChild(ta)
+    ta.select()
+    var ok = false
+    try { ok = document.execCommand('copy') } finally { document.body.removeChild(ta) }
+    return ok ? { ok: true, via: 'execCommand' } : { ok: false, message: 'document.execCommand("copy") returned false' }
+  } catch (e2) { return { ok: false, message: String((e2 && e2.message) || e2) } }
+})()`
+}
+
+/** 页侧读表达式：`navigator.clipboard.readText()`（安全上下文限定——非安全上下文给引导句）。 */
+function clipboardReadExpression() {
+  return `${mark("clipboard-read")}(async function () {
+  try {
+    if (!navigator.clipboard || !navigator.clipboard.readText) {
+      return { ok: false, message: 'navigator.clipboard.readText is unavailable — a secure context (https or localhost) is required' }
+    }
+    var text = await navigator.clipboard.readText()
+    return { ok: true, text: String(text == null ? '' : text) }
+  } catch (e) { return { ok: false, message: String((e && e.message) || e) } }
+})()`
+}
+
+/** 加速键序列（§3.5 平台分支）：darwin ⇒ Meta+C/V；win32 / linux ⇒ Ctrl+C/V。 */
+export function acceleratorSequence(op, platform = process.platform) {
+  const modifier = platform === "darwin" ? "Meta" : "Control"
+  const key = op === "copy" ? "c" : "v"
+  return pressSequence({ key, modifiers: [modifier] }).commands
+}
+
+/** clipboard（§2.2）：op ∈ read / write / copy / paste；write 必填 text；copy / paste 可携 ref 聚焦。 */
+async function actClipboard(args, ctx, h) {
+  const op = String(args.op ?? "")
+  if (!CLIPBOARD_OPS.includes(op)) throw new Error(`unknown clipboard op "${op}" — ops: ${CLIPBOARD_OPS.join(", ")}`)
+  await h.ensureSession(args)
+  await ensureFocusEmulation(h)
+  const origin = await pageOrigin(h)
+  await ensureClipboardPermission(h, origin)
+  if (op === "write") {
+    const text = String(args.text)
+    const res = await h.evalRaw(clipboardWriteExpression(text))
+    if (!res?.ok) throw h.pageError(`clipboard write failed: ${res?.message ?? "the page rejected the write"}`)
+    return `[clipboard] write ← ${text.length} chars` // 不回显文本（N-BT9）
+  }
+  if (op === "read") {
+    const res = await h.evalRaw(clipboardReadExpression())
+    if (!res?.ok) throw h.pageError(`clipboard read failed: ${res?.message ?? "the page rejected the read"}`)
+    const text = String(res.text ?? "")
+    const body = text ? `\n${truncateText(text, CLIPBOARD_MAX_CHARS, `clipboard reads are capped at ${CLIPBOARD_MAX_CHARS} chars`)}` : ""
+    return `[clipboard] read (${text.length} chars)${body}`
+  }
+  let target = null
+  if (typeof args.ref === "string" && args.ref !== "") target = await h.focusRef(args.ref)
+  for (const cmd of acceleratorSequence(op)) await h.call(cmd.method, cmd.params)
+  return `[clipboard] ${op}${target ? ` → ${target.label}` : ""}`
+}
+
+/** 剪贴板分发表（会话档并入总表——§5）。 */
+export const CLIPBOARD_ACTIONS = { clipboard: actClipboard }