fde2e-bu 0.0.0 → 1.2.0

package/src/mcp/bridge.mjs

@@ -0,0 +1,208 @@
+// 桥通道 HTTP 客户端（task 3.1 execute 面）——传输事实对齐 plugins/dsh/plugin/lib/
+// bridge.js（同一 omni 派发通道，此处为 CLI 独立分发的精简移植，非 import：
+// cli 不进 pnpm workspace、零依赖独立包）。
+//
+//   POST {BU_BRIDGE_SERVER|http://127.0.0.1:8788}/api/cmd
+//   Content-Type: application/json
+//   { "profileId": "...", "command": {...完整 om-adapter/0.7 命令} }
+//
+// 认证（可选内部令牌面，仅回环来源生效）：请求头 x-omni-internal（令牌）＋
+// x-omni-bound-profile（会话绑定 profileId）——来自环境变量 BU_INTERNAL_TOKEN /
+// BU_BOUND_PROFILE_ID，缺省不发送。r1 P1-5：只在 server URL host ∈ 回环集
+// （127.0.0.1 / ::1 / localhost）时附头；非回环目标不带令牌头（body 照发——
+// 无认证被 401 是服务端正确拒绝），并 stderr 一行提示（每进程一次）。
+//
+// 回执归一双形状（conformance golden C1/C2/C3，判据：payload.ok===true 且无 reply
+// 字段 ⇒ 形状 A＝AdapterReply 本体直返（真实服务端形态）；有 reply ⇒ 形状 B 历史包装）：
+//   - 成功（两形状）→ { ok:true, reply:<AdapterReply> }
+//   - 失败 → { ok:false, code, message, retryable? }（code 仅放行 /^E_[A-Z0-9_]+$/，
+//     其余折损 E_PROTOCOL——不自造错误码；E_AUTH＝传输层本地映射码）
+//
+// 超时预算（对表 dsh/Hermes 同款口径）：batch 缺省 305s（300s 批次+5s 余量）；
+// 显式 timeoutMs ⇒ max(1s, min(timeoutMs,300s))+5s（C3：低于 1s 按 1s 计，防止
+// 100ms 被算成 5.1s 这种「显式值反而比底价还小」的倒挂）；其余缺省 15s。
+// 客户端主动切断＝结果未知 ⇒ E_TIMEOUT retryable:false（勿盲目重发）。
+
+const CODE_SHAPE = /^E_[A-Z0-9_]+$/;
+const RETRYABLE_CODES = new Set(['E_TIMEOUT', 'E_SELECTOR_NOT_FOUND', 'E_OFFLINE']);
+const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
+const DEFAULT_BATCH_TIMEOUT_MS = 305_000;
+const MAX_COMMAND_TIMEOUT_MS = 300_000;
+const MIN_EXPLICIT_TIMEOUT_MS = 1_000; // C3 底价：显式 timeoutMs 不得低于 1s
+const TRANSPORT_MARGIN_MS = 5_000;
+export const DEFAULT_SERVER = 'http://127.0.0.1:8788';
+
+/** 环境变量配置面（task 指定四变量）。 */
+export function bridgeEnv(env = process.env) {
+  return {
+    server: env.BU_BRIDGE_SERVER || DEFAULT_SERVER,
+    profileId: env.BU_BRIDGE_PROFILE_ID || '',
+    internalToken: env.BU_INTERNAL_TOKEN || '',
+    boundProfileId: env.BU_BOUND_PROFILE_ID || '',
+  };
+}
+
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+// ---------- r1 P1-5：内部令牌仅回环发送 ----------
+
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', '[::1]', 'localhost']); // [::1]＝Node URL.hostname 对 IPv6 保留方括号
+let tokenNoticeShown = false; // stderr 提示每进程一次（长连 serve 不刷屏）
+
+/** server URL host 是否回环（解析失败/无 host＝非回环，fail-closed 不发令牌）。 */
+export function isLoopbackServer(server) {
+  let url;
+  try {
+    url = new URL(String(server));
+  } catch {
+    return false;
+  }
+  return LOOPBACK_HOSTS.has(url.hostname);
+}
+
+function noticeTokenSuppressed(host) {
+  if (tokenNoticeShown) return;
+  tokenNoticeShown = true;
+  try {
+    process.stderr.write(`fde2e-bu: 内部令牌仅回环发送——目标 ${host} 非回环，未附加 x-omni-internal/x-omni-bound-profile（无认证预期 401）\n`);
+  } catch { /* stderr 不可写（测试捕获态）时静默 */ }
+}
+
+function failureFrom(src) {
+  const code = typeof src.code === 'string' && CODE_SHAPE.test(src.code) ? src.code : 'E_PROTOCOL';
+  const envelope = {
+    ok: false,
+    code,
+    message: typeof src.message === 'string' && src.message !== '' ? src.message : `桥命令失败（${code}）`,
+    retryable: typeof src.retryable === 'boolean' ? src.retryable : RETRYABLE_CODES.has(code),
+  };
+  if (isRecord(src.detail)) envelope.detail = src.detail;
+  return envelope;
+}
+
+/**
+ * /api/cmd 回执包络归一（成功双形状/失败/包裹失败）——与 conformance golden 对齐。
+ * @returns {{ok:true, reply:object} | {ok:false, code:string, message:string, retryable:boolean, detail?:object}}
+ */
+export function normalizeEnvelope(payload) {
+  if (!isRecord(payload)) {
+    return { ok: false, code: 'E_PROTOCOL', message: '桥服务回执不是 JSON 对象', retryable: false };
+  }
+  if (payload.ok === true) {
+    if ('reply' in payload) {
+      const reply = payload.reply;
+      if (isRecord(reply) && reply.ok === false) return failureFrom(reply); // 包裹失败 → 外层失败
+      return { ok: true, ...(reply !== undefined ? { reply } : {}) };
+    }
+    return { ok: true, reply: payload }; // 形状 A：本体直返，整体作 reply 透传
+  }
+  if (payload.ok === false) return failureFrom(payload);
+  return { ok: false, code: 'E_PROTOCOL', message: '桥服务回执包络不识别（缺 ok 布尔字段）', retryable: false };
+}
+
+/** 单命令等待预算（毫秒）。 */
+export function budgetMsFor(command, settings = {}) {
+  const base = settings.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  const want = command?.timeoutMs;
+  const explicit = typeof want === 'number' && Number.isFinite(want) && want > 0 ? want : null;
+  if (command?.cmd === 'batch') {
+    if (explicit !== null) return Math.max(MIN_EXPLICIT_TIMEOUT_MS, Math.min(explicit, MAX_COMMAND_TIMEOUT_MS)) + TRANSPORT_MARGIN_MS;
+    return settings.batchTimeoutMs ?? DEFAULT_BATCH_TIMEOUT_MS;
+  }
+  if (explicit !== null) return Math.max(base, Math.min(explicit, MAX_COMMAND_TIMEOUT_MS) + TRANSPORT_MARGIN_MS);
+  return base;
+}
+
+/**
+ * 派发一条命令（execute 通道）。
+ * @param {object} settings { server, profileId, internalToken?, boundProfileId?, fetchImpl? }
+ * @param {object} command 完整 om-adapter/0.7 命令
+ * @returns {Promise<object>} 归一包络
+ */
+export async function dispatchCommand(settings, command) {
+  const url = `${settings.server.replace(/\/+$/, '')}/api/cmd`;
+  const headers = { 'content-type': 'application/json' };
+  // r1 P1-5：令牌头仅回环 host 附加；非回环目标不带（防内部令牌发往任意主机）
+  if ((settings.internalToken || settings.boundProfileId) && isLoopbackServer(settings.server)) {
+    if (settings.internalToken) headers['x-omni-internal'] = settings.internalToken;
+    if (settings.boundProfileId) headers['x-omni-bound-profile'] = settings.boundProfileId;
+  } else if (settings.internalToken || settings.boundProfileId) {
+    let host = String(settings.server);
+    try { host = new URL(host).host || host; } catch { /* 非 URL 形态原样展示 */ }
+    noticeTokenSuppressed(host);
+  }
+  const body = { profileId: settings.profileId, command };
+  const timeoutMs = budgetMsFor(command, settings);
+  const controller = new AbortController();
+  const deadline = setTimeout(() => controller.abort(new Error('deadline')), timeoutMs);
+  // C3（P2-8）：预算计时必须覆盖响应体读取——此前 finally 在 fetch 返回后立即
+  // clearTimeout，服务端先回头再慢吞吞吐 body 时会永久挂住。现统一在 body 解析
+  // 之后 clear，切断一律 E_TIMEOUT retryable:false（结果未知，勿盲目重发）。
+  const timeoutEnvelope = () => ({
+    ok: false,
+    code: 'E_TIMEOUT',
+    message: `客户端预算耗尽主动切断（${timeoutMs}ms）——结果未知：命令可能已在执行甚至已成功，先复核页面状态再决定是否重发`,
+    retryable: false,
+  });
+  try {
+    let response;
+    try {
+      const fetchImpl = settings.fetchImpl ?? globalThis.fetch;
+      response = await fetchImpl(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+    } catch (err) {
+      if (controller.signal.aborted) return timeoutEnvelope();
+      return { ok: false, code: 'E_OFFLINE', message: `桥服务不可达（${url}）：${err?.message ?? err}`, retryable: true };
+    }
+    let payload = null;
+    try {
+      payload = await response.json();
+    } catch {
+      payload = null;
+      if (controller.signal.aborted) return timeoutEnvelope(); // 读 body 超预算（fetch 已返回但 body 未完）
+    }
+    if (!isRecord(payload)) {
+      if (response.status >= 500) {
+        return { ok: false, code: 'E_OFFLINE', message: `桥服务 HTTP ${response.status}（非 JSON 回执）`, retryable: true };
+      }
+      return { ok: false, code: 'E_PROTOCOL', message: `桥服务回执不是 JSON 包络（HTTP ${response.status}）——检查 BU_BRIDGE_SERVER 指向 browser-bridge 派发入口`, retryable: false };
+    }
+    if (!('ok' in payload) && (response.status === 401 || response.status === 403)) {
+      return {
+        ok: false,
+        code: 'E_AUTH',
+        message: `桥服务 HTTP ${response.status}（鉴权被拒：BU_INTERNAL_TOKEN 缺失/不匹配，或经公网入口——x-omni-internal 仅回环来源生效；403＝BU_BOUND_PROFILE_ID 与 profileId 不一致）`,
+        retryable: false,
+      };
+    }
+    return normalizeEnvelope(payload);
+  } finally {
+    clearTimeout(deadline);
+  }
+}
+
+/** GET {server}/healthz（status/doctor 探活；离线/超时返回 null）。 */
+export async function fetchHealthz(server, { timeoutMs = 4000, fetchImpl } = {}) {
+  const url = `${server.replace(/\/+$/, '')}/healthz`;
+  const controller = new AbortController();
+  const deadline = setTimeout(() => controller.abort(new Error('deadline')), timeoutMs);
+  try {
+    const impl = fetchImpl ?? globalThis.fetch;
+    const res = await impl(url, { signal: controller.signal });
+    let body = null;
+    try {
+      body = await res.json();
+    } catch {
+      body = null;
+    }
+    return { ok: res.status >= 200 && res.status < 300, status: res.status, url, body };
+  } catch {
+    return { ok: false, status: 0, url, body: null };
+  } finally {
+    clearTimeout(deadline);
+  }
+}

package/src/mcp/commands-snapshot.json

@@ -0,0 +1,340 @@
+{
+  "$doc": {
+    "意图": "browser-bridge 契约层机器可读命令清单（宿主适配层按此声明工具参数；语义骨架见 SKILL.core.md）。",
+    "真源": "packages/protocol/src（constants.js COMMANDS + validate.js COMMAND_SPECS）——本文件是生成物，禁止手改；再生成＝node plugins/contracts/browser-bridge/scripts/gen-contract-commands.mjs",
+    "注意": "required/optional 只是字段名白名单；取值域/二选一分支（如 windowClose 的 windowId|taskId 恰一、imageExtract 的 css|ref 恰一）以 packages/protocol/src/validate.js 与 constraints.json 为准。"
+  },
+  "protocolVersion": "om-adapter/0.7",
+  "commands": [
+    {
+      "cmd": "batch",
+      "required": [
+        "steps"
+      ],
+      "optional": [
+        "continueOnError",
+        "snapshotAfter",
+        "snapshotPerStep",
+        "timeoutMs",
+        "targetTabId",
+        "targetWindowId"
+      ],
+      "summary": "一次往返跑一串动作（≤50 步、整批 ≤300s、单步 ≤30s）；只在中间结果不改变后续决策时用；外放/窗口/邮箱/媒体族禁入批。"
+    },
+    {
+      "cmd": "open",
+      "required": [
+        "url"
+      ],
+      "optional": [
+        "waitSelector",
+        "timeoutMs",
+        "targetTabId",
+        "targetWindowId"
+      ],
+      "summary": "导航到 url 并等加载完成；waitSelector 出现才回执；返回落点 url/title（导航后复检风控）。"
+    },
+    {
+      "cmd": "read",
+      "required": [],
+      "optional": [
+        "selector",
+        "targetTabId",
+        "targetWindowId"
+      ],
+      "summary": "读元素值/文本（表单控件读 value，其余读 innerText）；无 selector 读整页可见文本。"
+    },
+    {
+      "cmd": "snapshot",
+      "required": [],
+      "optional": [
+        "targetTabId",
+        "targetWindowId"
+      ],
+      "summary": "给可交互元素打 data-om-ref=\"@N\" 标并回几何/命中信息；ref 仅下一次命令有效，每次 snapshot 重排。"
+    },
+    {
+      "cmd": "click",
+      "required": [
+        "target"
+      ],
+      "optional": [
+        "waitSelector",
+        "timeoutMs",
+        "targetTabId",
+        "targetWindowId"
+      ],
+      "summary": "点击目标：元素级合成事件为主通道，custom element/闭 ShadowDOM 走 CDP 坐标信任点击，回执带 hit（实际点到了什么）。"
+    },
+    {
+      "cmd": "fill",
+      "required": [
+        "target",
+        "text"
+      ],
+      "optional": [
+        "inputMode",
+        "timeoutMs",
+        "targetTabId",
+        "targetWindowId"
+      ],
+      "summary": "清空后整体设值并派发 input/change（text:\"\"＝清空）；目标在闭 ShadowDOM 内或为自定义元素宿主时自动下钻内部输入框；inputMode 可选拟人节奏。"
+    },
+    {
+      "cmd": "paste",
+      "required": [
+        "target",
+        "text"
+      ],
+      "optional": [
+        "html",
+        "timeoutMs",
+        "targetTabId",
+        "targetWindowId"
+      ],
+      "summary": "DataTransfer＋ClipboardEvent 通道粘贴（富文本编辑器用）；html 走 text/html 受限通道；闭 ShadowDOM 内编辑器可达。"
+    },
+    {
+      "cmd": "insertText",
+      "required": [
+        "text"
+      ],
+      "optional": [
+        "targetTabId",
+        "targetWindowId"
+      ],
+      "summary": "Input.insertText 无焦点点插入文本。"
+    },
+    {
+      "cmd": "press",
+      "required": [
+        "key"
+      ],
+      "optional": [
+        "targetTabId",
+        "targetWindowId"
+      ],
+      "summary": "按键/组合键（CDP 信任键盘事件，组件库认）；键名封闭表见协议包 constraints，不可解析报 E_BAD_KEY。"
+    },
+    {
+      "cmd": "scroll",
+      "required": [],
+      "optional": [
+        "target",
+        "x",
+        "y",
+        "deltaY",
+        "deltaX",
+        "ticks",
+        "timeoutMs",
+        "targetTabId",
+        "targetWindowId"
+      ],
+      "summary": "滚轮逐格派发（页面自身滚动物理生效）；优先用它而非 press PageDown；target 先滚到元素居中再在其中心滚。"
+    },
+    {
+      "cmd": "upload",
+      "required": [
+        "target",
+        "files"
+      ],
+      "optional": [
+        "timeoutMs",
+        "targetTabId",
+        "targetWindowId"
+      ],
+      "summary": "两段式上传：资产 URL→下载落地→设文件输入框；target 支持 css/ref/text/role（point 不支持）；来源白名单见协议包 constraints（BU＝本机优先）。"
+    },
+    {
+      "cmd": "waitFor",
+      "required": [],
+      "optional": [
+        "selector",
+        "urlPattern",
+        "timeoutMs",
+        "targetTabId",
+        "targetWindowId"
+      ],
+      "summary": "等 selector 出现或 url 匹配正则（至少给一个）；完成后复检风控。"
+    },
+    {
+      "cmd": "screenshot",
+      "required": [],
+      "optional": [
+        "quality",
+        "maxWidth",
+        "targetTabId",
+        "targetWindowId"
+      ],
+      "summary": "当前页 WebP 截图（quality 默认 60，可限 maxWidth）。"
+    },
+    {
+      "cmd": "getState",
+      "required": [
+        "host"
+      ],
+      "optional": [],
+      "summary": "探测 host 登录态三态 loggedIn/loggedOut/unknown（cookie 信号启发式，不返回 cookie 值）。"
+    },
+    {
+      "cmd": "windowCreate",
+      "required": [
+        "url"
+      ],
+      "optional": [
+        "name",
+        "width",
+        "height",
+        "status",
+        "taskId",
+        "sessionId",
+        "friendlyName"
+      ],
+      "summary": "开独立 popup 窗口（默认 1280×800）；返回 windowId/tabId 供 targetTabId/targetWindowId 复用；可带 taskId/sessionId/friendlyName 软关联。"
+    },
+    {
+      "cmd": "windowClose",
+      "required": [],
+      "optional": [
+        "windowId",
+        "taskId"
+      ],
+      "summary": "关窗释放（幂等）；windowId 与 taskId 二选一至少其一；任务收尾必调。"
+    },
+    {
+      "cmd": "windowList",
+      "required": [],
+      "optional": [],
+      "summary": "托管窗口全量清单（taskId/windowId/tabId/state/url/status/sessionId）；执行浏览器任务前先查；非本会话窗口不要动。"
+    },
+    {
+      "cmd": "screencastStart",
+      "required": [],
+      "optional": [
+        "format",
+        "quality",
+        "maxWidth",
+        "maxHeight",
+        "everyNthFrame",
+        "push",
+        "tabId"
+      ],
+      "summary": "帧流推流开始（webp/jpeg，everyNthFrame ≤60）——云端/视窗观测面，非日常面。"
+    },
+    {
+      "cmd": "screencastStop",
+      "required": [],
+      "optional": [
+        "tabId"
+      ],
+      "summary": "帧流推流停止。"
+    },
+    {
+      "cmd": "mediaStore",
+      "required": [
+        "artifactId",
+        "operationId"
+      ],
+      "optional": [
+        "name",
+        "timeoutMs"
+      ],
+      "summary": "媒体资产入库登记（artifactId/operationId 均 UUID；租约/体量约束见协议包 constraints）。"
+    },
+    {
+      "cmd": "imageExtract",
+      "required": [
+        "targetTabId",
+        "selector"
+      ],
+      "optional": [
+        "source",
+        "maxBytes",
+        "timeoutMs"
+      ],
+      "summary": "抽取页面图片元素内容；selector 为 MediaSelector（css/ref 恰一，比 ElementSelector 窄）；需显式 targetTabId。"
+    },
+    {
+      "cmd": "windowFocus",
+      "required": [
+        "windowId"
+      ],
+      "optional": [],
+      "summary": "聚焦指定托管窗口（BU 插件保留命令）。"
+    },
+    {
+      "cmd": "windowBounds",
+      "required": [
+        "windowId"
+      ],
+      "optional": [
+        "width",
+        "height",
+        "left",
+        "top",
+        "state"
+      ],
+      "summary": "调整/读取托管窗口尺寸、位置、状态（normal/minimized/maximized/fullscreen）（BU 插件保留命令）。"
+    },
+    {
+      "cmd": "windowUpdateMeta",
+      "required": [
+        "windowId"
+      ],
+      "optional": [
+        "name",
+        "status"
+      ],
+      "summary": "更新托管窗口展示名/状态等元数据（BU 插件保留命令）。"
+    },
+    {
+      "cmd": "mailboxSend",
+      "required": [
+        "to",
+        "body"
+      ],
+      "optional": [
+        "type",
+        "meta",
+        "replyTo"
+      ],
+      "summary": "向收件方发留言（to＝'*'|'master'|绑定 id；body ≤64KB；type 缺省 note）（BU 插件保留命令）。"
+    },
+    {
+      "cmd": "mailboxPoll",
+      "required": [],
+      "optional": [
+        "mailbox",
+        "since",
+        "until",
+        "limit",
+        "offset",
+        "from",
+        "type",
+        "q",
+        "order",
+        "unreadOnly",
+        "view"
+      ],
+      "summary": "拉取留言（mailbox/since/from/type/q/order/unreadOnly 过滤；单次 ≤200 条）（BU 插件保留命令）。"
+    },
+    {
+      "cmd": "mailboxClear",
+      "required": [
+        "mailbox"
+      ],
+      "optional": [],
+      "summary": "清空指定信箱（BU 插件保留命令）。"
+    },
+    {
+      "cmd": "mailboxMarkRead",
+      "required": [
+        "mailbox"
+      ],
+      "optional": [
+        "upToSeq"
+      ],
+      "summary": "标记信箱已读（可 upToSeq 截止）（BU 插件保留命令）。"
+    }
+  ]
+}