publishport-opencli 1.0.0

package/dist/src/browser/fingerprint.js

@@ -0,0 +1,82 @@
+function J(q){let j=q>>>0;return()=>{j|=0;j=j+1831565813|0;let z=Math.imul(j^j>>>15,1|j);z=z+Math.imul(z^z>>>7,61|z)^z;return((z^z>>>14)>>>0)/4294967296}}function P(q,j){return j[Math.floor(q()*j.length)%j.length]}const L=[4,8,12,16],T=[8,8,16],U=[{width:1920,height:1080},{width:1536,height:864},{width:1440,height:900},{width:2560,height:1440}],V=[{vendor:"Google Inc. (NVIDIA)",renderer:"ANGLE (NVIDIA, NVIDIA GeForce RTX 3060 Direct3D11 vs_5_0 ps_5_0, D3D11)"},{vendor:"Google Inc. (Intel)",renderer:"ANGLE (Intel, Intel(R) UHD Graphics 630 Direct3D11 vs_5_0 ps_5_0, D3D11)"},{vendor:"Google Inc. (AMD)",renderer:"ANGLE (AMD, AMD Radeon RX 6600 Direct3D11 vs_5_0 ps_5_0, D3D11)"},{vendor:"Apple",renderer:"Apple GPU"},{vendor:"Google Inc. (Intel)",renderer:"ANGLE (Intel, Intel(R) Iris(TM) Plus Graphics Direct3D11 vs_5_0 ps_5_0, D3D11)"}];export function resolveFingerprint(q,j={}){const z=J(q),Q=j.spoof===!0,X=P(z,V),K=(G,H)=>G!==void 0?G:Q?H:void 0,F={enabled:!0,seed:q};if(j.timezone)F.timezone=j.timezone;if(j.locale)F.locale=j.locale;if(j.userAgent)F.userAgent=j.userAgent;if(j.platform)F.platform=j.platform;const Z=K(j.hardwareConcurrency,P(z,L));if(Z!==void 0)F.hardwareConcurrency=Z;const $=K(j.deviceMemory,P(z,T));if($!==void 0)F.deviceMemory=$;const A=K(j.screen,P(z,U));if(A!==void 0)F.screen=A;const B=K(j.webglVendor,X.vendor);if(B)F.webglVendor=B;const D=K(j.webglRenderer,X.renderer);if(D)F.webglRenderer=D;if(j.canvasNoise!==void 0?j.canvasNoise:Q)F.canvasNoise=!0;return F}export function randomSeed(){return Math.floor(Math.random()*4294967295)>>>0||1}export function generateFingerprintJs(q){if(!q.enabled)return"";return`
+(() => {
+  const _p = EventTarget.prototype, _k = '__ppfp';
+  if (_p[_k]) return;
+  try { Object.defineProperty(_p, _k, { value: true, enumerable: false, configurable: true }); } catch {}
+  const C = ${JSON.stringify({languages:q.locale?[q.locale,q.locale.split("-")[0]].filter(Boolean):null,language:q.locale??null,platform:q.platform??null,userAgent:q.userAgent??null,hardwareConcurrency:q.hardwareConcurrency??null,deviceMemory:q.deviceMemory??null,screen:q.screen??null,webglVendor:q.webglVendor??null,webglRenderer:q.webglRenderer??null,canvasNoise:q.canvasNoise===!0,seed:q.seed>>>0})};
+  const def = (obj, prop, get) => { try { Object.defineProperty(obj, prop, { get, configurable: true }); } catch {} };
+
+  // navigator 软信号
+  try {
+    if (C.userAgent) def(Object.getPrototypeOf(navigator) || navigator, 'userAgent', () => C.userAgent);
+    if (C.platform) def(navigator, 'platform', () => C.platform);
+    if (C.hardwareConcurrency != null) def(navigator, 'hardwareConcurrency', () => C.hardwareConcurrency);
+    if (C.deviceMemory != null) def(navigator, 'deviceMemory', () => C.deviceMemory);
+    if (C.language) def(navigator, 'language', () => C.language);
+    if (C.languages) { const l = Object.freeze(C.languages.slice()); def(navigator, 'languages', () => l); }
+  } catch {}
+
+  // 屏幕分辨率
+  try {
+    if (C.screen) {
+      def(screen, 'width', () => C.screen.width);
+      def(screen, 'height', () => C.screen.height);
+      def(screen, 'availWidth', () => C.screen.width);
+      def(screen, 'availHeight', () => C.screen.height - 40);
+    }
+  } catch {}
+
+  // WebGL vendor/renderer（覆盖 UNMASKED_* 与常规 VENDOR/RENDERER）
+  try {
+    if (C.webglVendor || C.webglRenderer) {
+      const patchGL = (proto) => {
+        if (!proto || proto.__ppgl) return;
+        try { Object.defineProperty(proto, '__ppgl', { value: true, enumerable: false }); } catch {}
+        const orig = proto.getParameter;
+        proto.getParameter = function (p) {
+          // 37445 UNMASKED_VENDOR_WEBGL, 37446 UNMASKED_RENDERER_WEBGL,
+          // 7936 VENDOR, 7937 RENDERER
+          if ((p === 37445 || p === 7936) && C.webglVendor) return C.webglVendor;
+          if ((p === 37446 || p === 7937) && C.webglRenderer) return C.webglRenderer;
+          return orig.call(this, p);
+        };
+      };
+      if (window.WebGLRenderingContext) patchGL(WebGLRenderingContext.prototype);
+      if (window.WebGL2RenderingContext) patchGL(WebGL2RenderingContext.prototype);
+    }
+  } catch {}
+
+  // Canvas 指纹噪声：给读像素结果加确定性微扰，打散 hash 又肉眼无差。
+  try {
+    if (C.canvasNoise) {
+      let s = (C.seed ^ 0x9e3779b9) >>> 0;
+      const rnd = () => { s = (s + 0x6d2b79f5) | 0; let t = Math.imul(s ^ (s >>> 15), 1 | s); t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t; return ((t ^ (t >>> 14)) >>> 0) / 4294967296; };
+      const jitter = (data) => {
+        for (let i = 0; i < data.length; i += 4) {
+          if (rnd() < 0.02) {
+            data[i] = Math.max(0, Math.min(255, data[i] + (rnd() < 0.5 ? -1 : 1)));
+          }
+        }
+      };
+      const origGetImageData = CanvasRenderingContext2D.prototype.getImageData;
+      CanvasRenderingContext2D.prototype.getImageData = function (...a) {
+        const r = origGetImageData.apply(this, a);
+        try { jitter(r.data); } catch {}
+        return r;
+      };
+      const origToDataURL = HTMLCanvasElement.prototype.toDataURL;
+      HTMLCanvasElement.prototype.toDataURL = function (...a) {
+        try {
+          const ctx = this.getContext('2d');
+          if (ctx && this.width && this.height) {
+            const img = origGetImageData.call(ctx, 0, 0, this.width, this.height);
+            jitter(img.data);
+            ctx.putImageData(img, 0, 0);
+          }
+        } catch {}
+        return origToDataURL.apply(this, a);
+      };
+    }
+  } catch {}
+})();
+`}

package/dist/src/browser/html-tree.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Client-side HTML → structured tree serializer.
+ *
+ * Returned as a JS string that gets passed to `page.evaluate`. The expression
+ * walks the DOM subtree rooted at the first selector match (or documentElement
+ * when no selector is given) and emits a compact `{tag, attrs, text, children}`
+ * tree for agents to consume instead of re-parsing raw HTML.
+ *
+ * Text handling: `text` is the concatenated text of direct text children only,
+ * whitespace-collapsed. Nested element text is left inside `children[].text`.
+ * Ordering between text and elements is not preserved — agents that need it
+ * should fall back to raw HTML mode.
+ *
+ * Budget knobs let the caller bound the output on large pages — previously an
+ * unscoped `get html --as json` could return a giant tree. Callers set any
+ * combination of `depth` / `childrenMax` / `textMax`; each hit is reported in
+ * the `truncated` envelope so agents know to narrow their selector or raise
+ * the budget.
+ *
+ * Compound controls (date / time / datetime-local / month / week / select /
+ * file) gain a `compound` field so agents inspecting the JSON tree see the
+ * full contract — date format, full option list (up to cap) with selections
+ * preserved for options beyond the cap, file `accept` and `multiple`. Without
+ * this wiring agents repeatedly guess values on these controls from the raw
+ * attributes, which is the failure mode compound.ts was built to eliminate.
+ */
+import { type CompoundInfo } from './compound.js';
+export interface BuildHtmlTreeJsOptions {
+    /** CSS selector to scope the tree; unscoped = documentElement */
+    selector?: string | null;
+    /** Max depth below the root (0 = root only, no children). Omit = unlimited. */
+    depth?: number | null;
+    /** Max element children per node before the rest get dropped. Omit = unlimited. */
+    childrenMax?: number | null;
+    /** Max chars of direct text per node before truncation. Omit = unlimited. */
+    textMax?: number | null;
+}
+/**
+ * Returns a JS expression string. When evaluated in a page context the
+ * expression resolves to either
+ *   `{selector, matched, tree, truncated}` on success, or
+ *   `{selector, invalidSelector: true, reason}` when `querySelectorAll`
+ *   throws a `SyntaxError` for an unparseable selector.
+ *
+ * Callers must branch on `invalidSelector` to convert it into the CLI's
+ * `invalid_selector` structured error; otherwise the browser-level exception
+ * would bubble out of `page.evaluate` and bypass the structured-error
+ * contract that agents rely on.
+ */
+export declare function buildHtmlTreeJs(opts?: BuildHtmlTreeJsOptions): string;
+export interface HtmlNode {
+    tag: string;
+    attrs: Record<string, string>;
+    text: string;
+    children: HtmlNode[];
+    /**
+     * Rich view for date/select/file controls. Omitted for non-compound elements
+     * so agents can rely on `compound != null` as a signal.
+     */
+    compound?: CompoundInfo;
+}
+export interface HtmlTreeTruncationInfo {
+    /** At least one element child was dropped because depth budget was hit. */
+    depth?: true;
+    /** Count of element children dropped across the tree due to `childrenMax`. */
+    children_dropped?: number;
+    /** Count of nodes whose `text` was cut to `textMax`. */
+    text_truncated?: number;
+}
+export interface HtmlTreeResult {
+    selector: string | null;
+    matched: number;
+    tree: HtmlNode | null;
+    truncated?: HtmlTreeTruncationInfo;
+}

package/dist/src/browser/html-tree.js

@@ -0,0 +1,61 @@
+import{COMPOUND_INFO_JS as K}from"./compound.js";export function buildHtmlTreeJs(k={}){const z=k.selector?JSON.stringify(k.selector):"null",B=Number.isFinite(k.depth)&&k.depth>=0?String(k.depth):"null",G=Number.isFinite(k.childrenMax)&&k.childrenMax>=0?String(k.childrenMax):"null",H=Number.isFinite(k.textMax)&&k.textMax>=0?String(k.textMax):"null";return`(() => {
+  ${K}
+  const selector = ${z};
+  const maxDepth = ${B};
+  const maxChildren = ${G};
+  const maxText = ${H};
+  let matches;
+  if (selector) {
+    try { matches = document.querySelectorAll(selector); }
+    catch (e) {
+      return { selector: selector, invalidSelector: true, reason: (e && e.message) || String(e) };
+    }
+  } else {
+    matches = [document.documentElement];
+  }
+  const matched = matches.length;
+  const root = matches[0] || null;
+  const trunc = { depth: false, children_dropped: 0, text_truncated: 0 };
+  function serialize(el, depth) {
+    if (!el || el.nodeType !== 1) return null;
+    const attrs = {};
+    for (const a of el.attributes) attrs[a.name] = a.value;
+    let text = '';
+    for (const n of el.childNodes) {
+      if (n.nodeType === 3) text += n.nodeValue;
+    }
+    text = text.replace(/\\s+/g, ' ').trim();
+    if (maxText !== null && text.length > maxText) {
+      text = text.slice(0, maxText);
+      trunc.text_truncated++;
+    }
+    const children = [];
+    if (maxDepth === null || depth < maxDepth) {
+      const childEls = [];
+      for (const n of el.childNodes) if (n.nodeType === 1) childEls.push(n);
+      const keep = maxChildren === null ? childEls.length : Math.min(childEls.length, maxChildren);
+      for (let i = 0; i < keep; i++) {
+        const child = serialize(childEls[i], depth + 1);
+        if (child) children.push(child);
+      }
+      if (maxChildren !== null && childEls.length > maxChildren) {
+        trunc.children_dropped += childEls.length - maxChildren;
+      }
+    } else {
+      // Budget hit: we're at max depth. Count any element children we would have visited.
+      for (const n of el.childNodes) if (n.nodeType === 1) { trunc.depth = true; break; }
+    }
+    const node = { tag: el.tagName.toLowerCase(), attrs, text, children };
+    const compound = compoundInfoOf(el);
+    if (compound) node.compound = compound;
+    return node;
+  }
+  const tree = root ? serialize(root, 0) : null;
+  const truncatedOut = {};
+  if (trunc.depth) truncatedOut.depth = true;
+  if (trunc.children_dropped > 0) truncatedOut.children_dropped = trunc.children_dropped;
+  if (trunc.text_truncated > 0) truncatedOut.text_truncated = trunc.text_truncated;
+  const envelope = { selector: selector, matched: matched, tree: tree };
+  if (Object.keys(truncatedOut).length > 0) envelope.truncated = truncatedOut;
+  return envelope;
+})()`}

package/dist/src/browser/html-tree.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Browser module — public API re-exports.
+ *
+ * This barrel replaces the former monolithic browser.ts.
+ * External code should import from './browser/index.js' (or './browser.js' via Node resolution).
+ */
+export { Page } from './page.js';
+export { BrowserBridge } from './bridge.js';
+export { CDPBridge } from './cdp.js';
+export { getDaemonHealth } from './daemon-client.js';
+export type { DaemonHealth } from './daemon-client.js';
+export { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
+export { generateStealthJs } from './stealth.js';
+export type { DomSnapshotOptions } from './dom-snapshot.js';

package/dist/src/browser/index.js

@@ -0,0 +1 @@
+export{Page}from"./page.js";export{BrowserBridge}from"./bridge.js";export{CDPBridge}from"./cdp.js";export{getDaemonHealth}from"./daemon-client.js";export{generateSnapshotJs,scrollToRefJs,getFormStateJs}from"./dom-snapshot.js";export{generateStealthJs}from"./stealth.js";

package/dist/src/browser/managed-chrome.d.ts

@@ -0,0 +1,89 @@
+/**
+ * [pp-only] 托管 Chrome 生命周期：为托管 profile 自起/复用/关闭独立 Chrome 实例。
+ *
+ * 原理：每个托管 profile 有自己的 user-data-dir + 固定 CDP 端口。命令执行时
+ * probe 端口——已在跑直接连；没在跑就用发现的 Chrome 可执行文件带
+ * --user-data-dir --remote-debugging-port 拉起（Chrome 136+ 只允许对
+ * 非默认 user-data-dir 开调试端口，所以这是唯一姿势，也是我们要的隔离）。
+ * 关闭走 CDP Browser.close，优雅且免 pid 跟踪。
+ *
+ * 红线：绝不 --headless——真窗口、真指纹是产品的反风控根基。
+ */
+import { type ManagedProfileEntry, type ProxyConfig, type FingerprintConfig } from './profile.js';
+/** 按平台发现 Chrome/Chromium 可执行文件。OPENCLI_CHROME_PATH 可显式覆盖。 */
+export declare function discoverChromePath(): string | null;
+export declare function managedEndpoint(entry: ManagedProfileEntry): string;
+export declare function isManagedChromeRunning(entry: ManagedProfileEntry): Promise<boolean>;
+/**
+ * 主入口：确保托管 profile 的 Chrome 在跑并返回 CDP endpoint。
+ * 已在跑 → 直接复用；没在跑 → 拉起并等就绪。
+ * 「探测→拉起→等就绪」整段按 profile 互斥（进程内 Promise 去重 + 跨进程文件锁），
+ * 保证任一时刻同一 profile 只有一路真正执行启动。
+ */
+export declare function ensureManagedChrome(name: string, entry: ManagedProfileEntry): Promise<string>;
+/** 通过 CDP Browser.close 优雅关闭托管 Chrome。返回是否真的关了（本来没跑返回 false）。 */
+export declare function stopManagedChrome(entry: ManagedProfileEntry): Promise<boolean>;
+export type ManagedProfileOpts = {
+    browserPath?: string;
+    label?: string;
+    proxy?: ProxyConfig;
+    fingerprint?: FingerprintConfig;
+    webrtc?: boolean;
+    clean?: boolean;
+};
+/** 对话框/CLI 传入的原始配置。fingerprint.enabled 时若缺 timezone/locale 且有代理，
+ *  会实探代理出口 geo 自动补齐（一致性卫生）。 */
+export type ManagedConfigInput = {
+    label?: string;
+    proxy?: ProxyConfig;
+    webrtc?: boolean;
+    clean?: boolean;
+    fingerprint?: {
+        enabled: boolean;
+        /** true = 没显式给的软信号用 seed 随机补全；false = 只用显式给的项 */
+        spoof?: boolean;
+        seed?: number;
+        timezone?: string;
+        locale?: string;
+        userAgent?: string;
+        platform?: string;
+        /** 逐项可调的软信号（对话框预设填充或用户手改） */
+        hardwareConcurrency?: number;
+        deviceMemory?: number;
+        screen?: {
+            width: number;
+            height: number;
+        };
+        webglVendor?: string;
+        webglRenderer?: string;
+        canvasNoise?: boolean;
+    };
+};
+/**
+ * 把配置输入解析成落盘用的 ManagedProfileOpts。
+ * 时区/语言等一律用调用方显式传入的值——绝不背着用户自动探测代理 geo 去改写，
+ * 错误的时区/语言可能触发平台风控封号。要「按代理地区填」是 UI 层显式动作
+ * （测试代理后由用户选择应用），不在这里默默做。
+ */
+export declare function resolveManagedOpts(input: ManagedConfigInput): Promise<{
+    opts: ManagedProfileOpts;
+}>;
+export declare function createManagedProfile(name: string, opts?: ManagedProfileOpts): Promise<ManagedProfileEntry>;
+/**
+ * 更新已存在托管 profile 的配置（label/proxy/fingerprint/webrtc/clean），保留 userDataDir/port。
+ * 传入的字段为「整体替换」：proxy/fingerprint 传 null 表示清除。改动需重启该环境生效，
+ * 若正在运行会先关闭它。
+ */
+export declare function updateManagedProfileConfig(name: string, patch: {
+    label?: string | null;
+    proxy?: ProxyConfig | null;
+    fingerprint?: FingerprintConfig | null;
+    webrtc?: boolean;
+    clean?: boolean;
+}): Promise<{
+    entry: ManagedProfileEntry;
+    wasRunning: boolean;
+}>;
+export declare function removeManagedProfile(name: string, opts?: {
+    keepData?: boolean;
+}): Promise<void>;

package/dist/src/browser/managed-chrome.js

@@ -0,0 +1 @@
+import{execFileSync as R}from"node:child_process";import*as B from"node:fs";import*as W from"node:path";import{request as x}from"node:http";import{WebSocket as T}from"ws";import{probeCDP as q,launchDetachedApp as v}from"../launcher.js";import{withBrowserSessionLock as C}from"../browser-session-lock.js";import{CommandExecutionError as O}from"../errors.js";import{log as J}from"../logger.js";import{addManagedProfile as M,getManagedProfile as N,listManagedProfiles as _,managedProfilesBaseDir as w,removeManagedProfileEntry as b,updateManagedProfile as A}from"./profile.js";import{proxyServerFlag as D}from"./proxy-test.js";import{resolveFingerprint as E,randomSeed as P}from"./fingerprint.js";const f=500,L=20000,j=9301,k=9399;function F(K){for(const H of K)try{B.accessSync(H,B.constants.X_OK);return H}catch{}return null}function g(K){for(const H of K)try{const Q=R("which",[H],{encoding:"utf-8",stdio:"pipe"}).trim();if(Q)return Q}catch{}return null}export function discoverChromePath(){const K=process.env.OPENCLI_CHROME_PATH?.trim();if(K)return K;if(process.platform==="darwin")return F(["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome","/Applications/Chromium.app/Contents/MacOS/Chromium","/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"]);if(process.platform==="win32"){const H=process.env.ProgramFiles??"C:\\Program Files",Q=process.env["ProgramFiles(x86)"]??"C:\\Program Files (x86)",Y=process.env.LOCALAPPDATA??"";return F([W.join(H,"Google","Chrome","Application","chrome.exe"),W.join(Q,"Google","Chrome","Application","chrome.exe"),...Y?[W.join(Y,"Google","Chrome","Application","chrome.exe")]:[],W.join(H,"Microsoft","Edge","Application","msedge.exe"),W.join(Q,"Microsoft","Edge","Application","msedge.exe")])}return g(["google-chrome-stable","google-chrome","chromium","chromium-browser","microsoft-edge-stable"])}function G(K,H,Q=5000){return new Promise((Y,Z)=>{const V=new URL(H),$=x({hostname:V.hostname,port:V.port,path:V.pathname+V.search,method:K,timeout:Q},(z)=>{const U=[];z.on("data",(X)=>U.push(Buffer.isBuffer(X)?X:Buffer.from(X)));z.on("end",()=>{const X=Buffer.concat(U).toString("utf8");if((z.statusCode??0)<200||(z.statusCode??0)>=300){Z(Error(`HTTP ${z.statusCode}: ${X.slice(0,200)}`));return}try{Y(X?JSON.parse(X):null)}catch{Y(X)}})});$.on("error",Z);$.on("timeout",()=>$.destroy(Error(`请求 ${H} 超时`)));$.end()})}export function managedEndpoint(K){return`http://127.0.0.1:${K.port}`}export async function isManagedChromeRunning(K){return q(K.port)}const m=["--no-first-run","--no-default-browser-check","--disable-background-networking","--disable-component-update","--disable-sync","--disable-domain-reliability","--disable-breakpad","--disable-client-side-phishing-detection","--no-pings","--no-service-autorun","--password-store=basic","--disable-features=Translate,OptimizationHints,MediaRouter,AutofillServerCommunication,InterestFeedContentSuggestions,CalculateNativeWinOcclusion"];function d(K){const H=[`--user-data-dir=${K.userDataDir}`,`--remote-debugging-port=${K.port}`,"--remote-allow-origins=*"];if(K.clean!==!1)H.push(...m);if(K.webrtc!==!1)H.push("--force-webrtc-ip-handling-policy=disable_non_proxied_udp");if(K.proxy)H.push(`--proxy-server=${D(K.proxy)}`);if(K.fingerprint?.enabled&&K.fingerprint.locale)H.push(`--lang=${K.fingerprint.locale}`);H.push("about:blank");return H}function u(K){const H=K.fingerprint?.enabled?K.fingerprint.timezone:void 0;return H?{TZ:H}:void 0}async function y(K,H){const Q=Date.now()+L;while(Date.now()<Q){if(await q(K,1000))return;await new Promise((Y)=>setTimeout(Y,f))}throw new O(`托管 Chrome「${H}」已启动但 ${L/1000}s 内 CDP 端口 ${K} 未就绪`,"浏览器可能启动缓慢，稍后重试；或检查该端口是否被其它进程占用。")}async function S(K){try{const H=await G("GET",`${K}/json`);if(!(Array.isArray(H)&&H.some((Y)=>Y.type==="page")))await G("PUT",`${K}/json/new?about:blank`)}catch(H){J.debug(`[managed-chrome] ensurePageTarget 失败（非致命）：${H instanceof Error?H.message:H}`)}}const I=new Map;export async function ensureManagedChrome(K,H){const Q=managedEndpoint(H),Y=I.get(K);if(Y)return Y;if(await q(H.port)){J.debug(`[managed-chrome] profile「${K}」已在端口 ${H.port} 运行`);await S(Q);return Q}const Z=I.get(K);if(Z)return Z;const V=C(async()=>{if(await q(H.port)){J.debug(`[managed-chrome] profile「${K}」等锁期间已被拉起，直接复用`);await S(Q);return Q}const $=H.browserPath??discoverChromePath();if(!$)throw new O("找不到可用的 Chrome/Chromium 浏览器。","安装 Google Chrome，或用 OPENCLI_CHROME_PATH 环境变量指定可执行文件路径。");B.mkdirSync(H.userDataDir,{recursive:!0});J.debug(`[managed-chrome] 拉起 profile「${K}」：${$} 端口 ${H.port}${H.proxy?" (代理)":""}`);await v($,d(H),`托管 profile ${K}`,u(H));await y(H.port,K);await S(Q);return Q},`launch-${K}`).finally(()=>I.delete(K));I.set(K,V);return V}export async function stopManagedChrome(K){if(!await q(K.port))return!1;const Q=(await G("GET",`${managedEndpoint(K)}/json/version`))?.webSocketDebuggerUrl;if(!Q)throw Error(`端口 ${K.port} 上的 CDP 端点没有暴露 browser target`);await new Promise((Z,V)=>{const $=new T(Q),z=setTimeout(()=>{$.close();V(Error("CDP Browser.close 超时"))},1e4);$.on("open",()=>{$.send(JSON.stringify({id:1,method:"Browser.close",params:{}}))});$.on("close",()=>{clearTimeout(z);Z()});$.on("error",(U)=>{clearTimeout(z);V(U)})});const Y=Date.now()+5000;while(Date.now()<Y){if(!await q(K.port,500))break;await new Promise((Z)=>setTimeout(Z,200))}if(process.platform!=="win32"){const Z=W.join(K.userDataDir,"SingletonLock"),V=Date.now()+15000;while(Date.now()<V){try{B.lstatSync(Z)}catch{return!0}await new Promise(($)=>setTimeout($,200))}J.warn(`[managed-chrome] Chrome 端口已释放但 15s 内 SingletonLock 未消失：${Z}`)}return!0}async function h(K){return!await q(K,500)}async function l(){const K=new Set(_().map(({entry:H})=>H.port));for(let H=j;H<=k;H++){if(K.has(H))continue;if(await h(H))return H}throw Error(`托管 profile 端口区间 ${j}-${k} 已耗尽`)}export async function resolveManagedOpts(K){const H={};if(K.label)H.label=K.label;if(K.proxy)H.proxy=K.proxy;if(K.webrtc===!1)H.webrtc=!1;if(K.clean===!1)H.clean=!1;if(K.fingerprint?.enabled){const Q=K.fingerprint,Y=Q.seed??P();H.fingerprint=E(Y,{timezone:Q.timezone,locale:Q.locale,userAgent:Q.userAgent,platform:Q.platform,spoof:Q.spoof,hardwareConcurrency:Q.hardwareConcurrency,deviceMemory:Q.deviceMemory,screen:Q.screen,webglVendor:Q.webglVendor,webglRenderer:Q.webglRenderer,canvasNoise:Q.canvasNoise})}return{opts:H}}export async function createManagedProfile(K,H={}){const Q=await l(),Y=W.join(w(),K.trim()),Z={userDataDir:Y,port:Q,...H.browserPath?{browserPath:H.browserPath}:{},...H.label?{label:H.label}:{},...H.proxy?{proxy:H.proxy}:{},...H.fingerprint?{fingerprint:H.fingerprint}:{},...H.webrtc===!1?{webrtc:!1}:{},...H.clean===!1?{clean:!1}:{},createdAt:new Date().toISOString()};M(K,Z);B.rmSync(Y,{recursive:!0,force:!0});B.mkdirSync(Y,{recursive:!0});return Z}export async function updateManagedProfileConfig(K,H){const Q=N(K);if(!Q)throw Error(`托管 profile "${K}" 不存在`);const Y=H.webrtc!==void 0?H.webrtc:Q.webrtc,Z=H.clean!==void 0?H.clean:Q.clean,V={userDataDir:Q.userDataDir,port:Q.port,...Q.browserPath?{browserPath:Q.browserPath}:{},...Q.createdAt?{createdAt:Q.createdAt}:{},...H.label!==void 0?H.label?{label:H.label}:{}:Q.label?{label:Q.label}:{},...H.proxy!==void 0?H.proxy?{proxy:H.proxy}:{}:Q.proxy?{proxy:Q.proxy}:{},...H.fingerprint!==void 0?H.fingerprint?{fingerprint:H.fingerprint}:{}:Q.fingerprint?{fingerprint:Q.fingerprint}:{},...Y===!1?{webrtc:!1}:{},...Z===!1?{clean:!1}:{}};let $=!1;try{$=await stopManagedChrome(Q)}catch(z){J.warn(`[managed-chrome] 更新前关闭 profile「${K}」失败（继续）：${z instanceof Error?z.message:z}`)}A(K,V);return{entry:V,wasRunning:$}}async function c(K){const H=Date.now()+15000;let Q=0;while(Date.now()<H){try{B.rmSync(K,{recursive:!0,force:!0,maxRetries:3,retryDelay:100})}catch{}await new Promise((Y)=>setTimeout(Y,300));if(!B.existsSync(K)){if(++Q>=2)return}else Q=0}throw new O(`数据目录未能删净（浏览器可能仍在退出中）：${K}`,"等浏览器窗口完全关闭后再删一次即可。")}export async function removeManagedProfile(K,H={}){const Q=N(K);if(!Q)throw Error(`托管 profile "${K}" 不存在`);try{await stopManagedChrome(Q)}catch(Y){J.warn(`[managed-chrome] 关闭 profile「${K}」失败（继续删除）：${Y instanceof Error?Y.message:Y}`)}if(!H.keepData){const Y=w(),Z=W.resolve(Q.userDataDir);if(Z.startsWith(Y+W.sep))await c(Z);else J.warn(`[managed-chrome] user-data-dir 不在 ${Y} 下，跳过数据删除：${Z}`)}b(K)}

package/dist/src/browser/network-cache.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Persistent cache for browser network captures.
+ *
+ * The live capture buffer (JS interceptor / daemon ring) can be cleared
+ * by navigation or lost between CLI invocations. Agents still need
+ * stable references to request bodies after running other commands,
+ * so every `browser network` call snapshots its results to disk.
+ *
+ * Layout: <cacheDir>/browser-network/<session>.json
+ * Entries expire after DEFAULT_TTL_MS (24h).
+ */
+export declare const DEFAULT_TTL_MS: number;
+export interface CachedNetworkEntry {
+    key: string;
+    url: string;
+    method: string;
+    status: number;
+    /** Full body size in chars (may exceed stored body length when truncated). */
+    size: number;
+    ct: string;
+    body: unknown;
+    /**
+     * Truncation signals use snake_case so `--raw` (which emits cache entries
+     * verbatim) matches the agent-facing contract used by list / --detail.
+     */
+    body_truncated?: boolean;
+    body_full_size?: number;
+    timestamp?: number;
+}
+export interface NetworkCacheFile {
+    version: 1;
+    session: string;
+    savedAt: string;
+    entries: CachedNetworkEntry[];
+}
+export declare function getCachePath(session: string, baseDir?: string): string;
+export declare function saveNetworkCache(session: string, entries: CachedNetworkEntry[], baseDir?: string): void;
+export interface LoadOptions {
+    baseDir?: string;
+    ttlMs?: number;
+    now?: number;
+}
+export interface LoadResult {
+    status: 'ok' | 'missing' | 'expired' | 'corrupt';
+    file?: NetworkCacheFile;
+    ageMs?: number;
+}
+export declare function loadNetworkCache(session: string, opts?: LoadOptions): LoadResult;
+export declare function findEntry(file: NetworkCacheFile, key: string): CachedNetworkEntry | null;

package/dist/src/browser/network-cache.js

@@ -0,0 +1 @@
+import*as z from"node:fs";import*as V from"node:os";import*as O from"node:path";export const DEFAULT_TTL_MS=86400000;function W(){return process.env.OPENCLI_CACHE_DIR||O.join(V.homedir(),".opencli","cache")}export function getCachePath(B,q=W()){const G=B.replace(/[^a-zA-Z0-9_-]+/g,"_");return O.join(q,"browser-network",`${G}.json`)}export function saveNetworkCache(B,q,G){const J=getCachePath(B,G);z.mkdirSync(O.dirname(J),{recursive:!0});const I={version:1,session:B,savedAt:new Date().toISOString(),entries:q};let H;try{H=z.openSync(J,z.constants.O_WRONLY|z.constants.O_CREAT|z.constants.O_TRUNC,384);z.fchmodSync(H,384);z.writeFileSync(H,JSON.stringify(I),"utf8")}finally{if(H!==void 0)z.closeSync(H)}}export function loadNetworkCache(B,q={}){const G=getCachePath(B,q.baseDir);let J;try{J=z.readFileSync(G,"utf-8")}catch{return{status:"missing"}}let I;try{const K=JSON.parse(J);if(!K||K.version!==1||!Array.isArray(K.entries))return{status:"corrupt"};I=K}catch{return{status:"corrupt"}}const H=q.ttlMs??DEFAULT_TTL_MS,R=q.now??Date.now(),Q=Date.parse(I.savedAt);if(!Number.isFinite(Q))return{status:"corrupt"};const N=R-Q;if(N>H)return{status:"expired",file:I,ageMs:N};return{status:"ok",file:I,ageMs:N}}export function findEntry(B,q){return B.entries.find((G)=>G.key===q)??null}

package/dist/src/browser/network-cache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/network-key.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Stable keys for network capture entries.
+ *
+ * Agents reference entries by key (e.g. `UserTweets`, `GET api.x.com/1.1/home`)
+ * instead of array index, so the mapping survives new captures.
+ *
+ * Rules:
+ *   GraphQL (URL contains `/graphql/`): key = operationName derived from URL path
+ *                                       (the segment after a 22-char query id, or the last segment)
+ *   Everything else: key = `METHOD host+pathname`
+ *
+ * On collision assignKeys suffixes duplicates as `base#2`, `base#3`, ... —
+ * the first occurrence stays bare (there is no `#1`).
+ */
+export interface KeyableRequest {
+    url: string;
+    method: string;
+}
+export declare function deriveKey(req: KeyableRequest): string;
+export declare function assignKeys<T extends KeyableRequest>(requests: T[]): Array<T & {
+    key: string;
+}>;

package/dist/src/browser/network-key.js

@@ -0,0 +1 @@
+export function deriveKey(j){const w=F(j.url);if(!w)return`${j.method.toUpperCase()} ${G(j.url,120)}`;const A=w.pathname;if(A.includes("/graphql/")){const z=E(A);if(z)return z}return`${j.method.toUpperCase()} ${w.host}${A}`}export function assignKeys(j){const w=new Map,A=[];for(const z of j){const B=deriveKey(z),C=w.get(B)??0;w.set(B,C+1);const D=C===0?B:`${B}#${C+1}`;A.push({...z,key:D})}return A}function E(j){const w=j.split("/").filter(Boolean),A=w.indexOf("graphql");if(A<0)return null;const z=w.slice(A+1);if(z.length===0)return null;if(z.length===1)return z[0];return z[1]||z[0]}function F(j){try{return new URL(j)}catch{return null}}function G(j,w){return j.length<=w?j:`${j.slice(0,w-1)}…`}

package/dist/src/browser/network-key.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/page.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Page abstraction — implements IPage by sending commands to the daemon.
+ *
+ * All browser operations are ultimately 'exec' (JS evaluation via CDP)
+ * plus a few native Chrome Extension APIs (tabs, cookies, navigate).
+ *
+ * IMPORTANT: After goto(), we remember the page identity (targetId) returned
+ * by the navigate action and pass it to all subsequent commands. This ensures
+ * page-scoped operations target the correct page without guessing.
+ */
+import type { BrowserCookie, BrowserDownloadWaitResult, BrowserEvaluateFunction, ScreenshotOptions } from '../types.js';
+import { BasePage } from './base-page.js';
+/**
+ * Page — implements IPage by talking to the daemon via HTTP.
+ */
+export declare class Page extends BasePage {
+    private readonly session;
+    readonly contextId?: string | undefined;
+    private readonly windowMode?;
+    private readonly surface;
+    private readonly siteSession?;
+    private readonly _idleTimeout;
+    constructor(session: string, idleTimeout?: number, contextId?: string | undefined, windowMode?: "foreground" | "background" | undefined, surface?: 'browser' | 'adapter', siteSession?: "ephemeral" | "persistent" | undefined);
+    /** Active page identity (targetId), set after navigate and used in all subsequent commands */
+    private _page;
+    private _networkCaptureUnsupported;
+    private _networkCaptureWarned;
+    /** Helper: spread session into command params */
+    private _sessionOpts;
+    /** Helper: spread session + page identity into command params */
+    private _cmdOpts;
+    goto(url: string, options?: {
+        waitUntil?: 'load' | 'none';
+        settleMs?: number;
+    }): Promise<void>;
+    /** Get the active page identity (targetId) */
+    getActivePage(): string | undefined;
+    /** Bind this Page instance to a specific page identity (targetId). */
+    setActivePage(page?: string): void;
+    private _markUnsupportedNetworkCapture;
+    evaluate<T = unknown>(js: string): Promise<T>;
+    evaluate<Args extends unknown[], T>(fn: BrowserEvaluateFunction<Args, T>, ...args: Args): Promise<Awaited<T>>;
+    getCookies(opts?: {
+        domain?: string;
+        url?: string;
+    }): Promise<BrowserCookie[]>;
+    /** Release the current browser session lease in the extension */
+    closeWindow(): Promise<void>;
+    tabs(): Promise<unknown[]>;
+    newTab(url?: string): Promise<string | undefined>;
+    closeTab(target?: number | string): Promise<void>;
+    selectTab(target: number | string): Promise<void>;
+    /**
+     * Capture a screenshot via CDP Page.captureScreenshot.
+     */
+    screenshot(options?: ScreenshotOptions): Promise<string>;
+    startNetworkCapture(pattern?: string): Promise<boolean>;
+    readNetworkCapture(): Promise<unknown[]>;
+    waitForDownload(pattern?: string, timeoutMs?: number): Promise<BrowserDownloadWaitResult>;
+    /**
+     * Set local file paths on a file input element via CDP DOM.setFileInputFiles.
+     * Chrome reads the files directly from the local filesystem, avoiding the
+     * payload size limits of base64-in-evaluate.
+     */
+    setFileInput(files: string[], selector?: string): Promise<void>;
+    insertText(text: string): Promise<void>;
+    frames(): Promise<Array<{
+        index: number;
+        frameId: string;
+        url: string;
+        name: string;
+    }>>;
+    evaluateInFrame(js: string, frameIndex: number): Promise<unknown>;
+    cdp(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    handleJavaScriptDialog(accept: boolean, promptText?: string): Promise<void>;
+    /** CDP native click fallback — called when JS el.click() fails */
+    protected tryNativeClick(x: number, y: number): Promise<boolean>;
+    /** Precise click using DOM.getContentQuads/getBoxModel for inline elements */
+    clickWithQuads(ref: string): Promise<void>;
+    nativeClick(x: number, y: number): Promise<void>;
+    nativeType(text: string): Promise<void>;
+    nativeKeyPress(key: string, modifiers?: string[]): Promise<void>;
+}

package/dist/src/browser/page.js

@@ -0,0 +1,15 @@
+import{sendCommand as L,sendCommandFull as Y}from"./daemon-client.js";import{buildEvaluateExpression as $}from"./utils.js";import{saveBase64ToFile as N}from"../utils.js";import{generateStealthJs as j,generateBeforeUnloadGuardJs as O}from"./stealth.js";import{waitForDomStableJs as U}from"./dom-helpers.js";import{BasePage as R}from"./base-page.js";import{classifyBrowserError as _}from"./errors.js";import{log as h}from"../logger.js";function J(A){const G=(A instanceof Error?A.message:String(A)).toLowerCase();return G.includes("unknown action")&&G.includes("network-capture")||G.includes("network capture")&&G.includes("not supported")}function z(A){const D=A instanceof Error?A.message:String(A);return D.includes("stale page identity")||/^Page not found:\s*\S+\s*$/.test(D)}export class Page extends R{session;contextId;windowMode;surface;siteSession;_idleTimeout;constructor(A,D,G,H,V="browser",Q){super();this.session=A;this.contextId=G;this.windowMode=H;this.surface=V;this.siteSession=Q;this._idleTimeout=D}_page;_networkCaptureUnsupported=!1;_networkCaptureWarned=!1;_sessionOpts(){return{session:this.session,surface:this.surface,...this.contextId&&{contextId:this.contextId},...this._idleTimeout!=null&&{idleTimeout:this._idleTimeout},...this.windowMode&&{windowMode:this.windowMode},...this.siteSession&&{siteSession:this.siteSession}}}_cmdOpts(){return{session:this.session,surface:this.surface,...this.contextId&&{contextId:this.contextId},...this._page!==void 0&&{page:this._page},...this._idleTimeout!=null&&{idleTimeout:this._idleTimeout},...this.windowMode&&{windowMode:this.windowMode},...this.siteSession&&{siteSession:this.siteSession}}}async goto(A,D){try{await L("exec",{code:O(),...this._cmdOpts()})}catch{}let G;try{G=await Y("navigate",{url:A,...this._cmdOpts()})}catch(H){if(!z(H)||this._page===void 0)throw H;this._page=void 0;G=await Y("navigate",{url:A,...this._cmdOpts()})}if(G.page)this._page=G.page;this._lastUrl=A;if(D?.waitUntil!=="none"){const H=D?.settleMs??1000,Q={code:`${j()};
+${U(H,Math.min(500,H))}`,...this._cmdOpts()};try{await L("exec",Q)}catch(W){const K=_(W);if(K.kind!=="target-navigation")throw W;try{await new Promise((X)=>setTimeout(X,K.delayMs));await L("exec",Q)}catch(X){if(_(X).kind!=="target-navigation")throw X}}}else try{await L("exec",{code:j(),...this._cmdOpts()})}catch{}}getActivePage(){return this._page}setActivePage(A){this._page=A;this._lastUrl=null}_markUnsupportedNetworkCapture(){this._networkCaptureUnsupported=!0;if(this._networkCaptureWarned)return;this._networkCaptureWarned=!0;h.warn("Browser Bridge extension does not support network capture; continuing without it. Explore output may miss API endpoints until you reload or reinstall the extension.")}async evaluate(A,...D){const G=$(A,D);try{return await L("exec",{code:G,...this._cmdOpts()})}catch(H){const V=_(H);if(V.kind!=="target-navigation")throw H;await new Promise((Q)=>setTimeout(Q,V.delayMs));return L("exec",{code:G,...this._cmdOpts()})}}async getCookies(A={}){const D=await L("cookies",{...this._sessionOpts(),...A});return Array.isArray(D)?D:[]}async closeWindow(){try{await L("close-window",{...this._sessionOpts()})}catch{}finally{this._page=void 0;this._lastUrl=null;this._networkCaptureUnsupported=!1;this._networkCaptureWarned=!1}}async tabs(){const A=await L("tabs",{op:"list",...this._sessionOpts()});return Array.isArray(A)?A:[]}async newTab(A){const D=await Y("tabs",{op:"new",...A!==void 0&&{url:A},...this._sessionOpts()});this._lastUrl=null;return D.page}async closeTab(A){const D={op:"close",...this._sessionOpts()};if(typeof A==="number")D.index=A;else if(typeof A==="string")D.page=A;else if(this._page!==void 0)D.page=this._page;const G=await L("tabs",D),H=typeof G?.closed==="string"?G.closed:void 0;if(H&&H===this._page||!H&&(A===void 0||A===this._page)){this._page=void 0;this._lastUrl=null}}async selectTab(A){const D=await Y("tabs",{op:"select",...typeof A==="number"?{index:A}:{page:A},...this._sessionOpts()});if(D.page)this._page=D.page;this._lastUrl=null}async screenshot(A={}){const D=await L("screenshot",{...this._cmdOpts(),format:A.format,quality:A.quality,fullPage:A.fullPage,width:A.width,height:A.height});if(A.path)await N(D,A.path);return D}async startNetworkCapture(A=""){if(this._networkCaptureUnsupported)return!1;try{await L("network-capture-start",{pattern:A,...this._cmdOpts()});return!0}catch(D){if(!J(D))throw D;this._markUnsupportedNetworkCapture();return!1}}async readNetworkCapture(){if(this._networkCaptureUnsupported)return[];try{const A=await L("network-capture-read",{...this._cmdOpts()});return Array.isArray(A)?A:[]}catch(A){if(!J(A))throw A;this._markUnsupportedNetworkCapture();return[]}}async waitForDownload(A="",D=30000){return await L("wait-download",{pattern:A,timeoutMs:D,...this._cmdOpts()})}async setFileInput(A,D){if(!(await L("set-file-input",{files:A,selector:D,...this._cmdOpts()}))?.count)throw Error("setFileInput returned no count — command may not be supported by the extension")}async insertText(A){if(!(await L("insert-text",{text:A,...this._cmdOpts()}))?.inserted)throw Error("insertText returned no inserted flag — command may not be supported by the extension")}async frames(){const A=await L("frames",{...this._cmdOpts()});return Array.isArray(A)?A:[]}async evaluateInFrame(A,D){const G=$(A);return L("exec",{code:G,frameIndex:D,...this._cmdOpts()})}async cdp(A,D={}){return L("cdp",{cdpMethod:A,cdpParams:D,...this._cmdOpts()})}async handleJavaScriptDialog(A,D){await this.cdp("Page.handleJavaScriptDialog",{accept:A,...D!==void 0&&{promptText:D}})}async tryNativeClick(A,D){try{await this.nativeClick(A,D);return!0}catch{return!1}}async clickWithQuads(A){const D=JSON.stringify(A),G=`[data-opencli-ref="${A.replace(/"/g,"\\\"")}"]`;await this.evaluate(`
+      (() => {
+        const el = document.querySelector('[data-opencli-ref="' + ${D} + '"]');
+        if (el) el.scrollIntoView({ behavior: 'instant', block: 'center' });
+        return !!el;
+      })()
+    `);try{const H=await this.cdp("DOM.getDocument",{}),V=await this.cdp("DOM.querySelectorAll",{nodeId:H.root.nodeId,selector:G});if(!V.nodeIds?.length)throw Error("DOM node not found");const Q=V.nodeIds[0];try{const W=await this.cdp("DOM.getContentQuads",{nodeId:Q});if(W.quads?.length){const K=W.quads[0],X=(K[0]+K[2]+K[4]+K[6])/4,Z=(K[1]+K[3]+K[5]+K[7])/4;await this.nativeClick(Math.round(X),Math.round(Z));return}}catch{}try{const W=await this.cdp("DOM.getBoxModel",{nodeId:Q});if(W.model?.content){const K=W.model.content,X=(K[0]+K[2]+K[4]+K[6])/4,Z=(K[1]+K[3]+K[5]+K[7])/4;await this.nativeClick(Math.round(X),Math.round(Z));return}}catch{}}catch{}await this.evaluate(`
+      (() => {
+        const el = document.querySelector('[data-opencli-ref="' + ${D} + '"]');
+        if (!el) throw new Error('Element not found: ' + ${D});
+        el.click();
+        return 'clicked';
+      })()
+    `)}async nativeClick(A,D){await this.cdp("Input.dispatchMouseEvent",{type:"mouseMoved",x:A,y:D});await this.cdp("Input.dispatchMouseEvent",{type:"mousePressed",x:A,y:D,button:"left",clickCount:1});await this.cdp("Input.dispatchMouseEvent",{type:"mouseReleased",x:A,y:D,button:"left",clickCount:1})}async nativeType(A){await this.cdp("Input.insertText",{text:A})}async nativeKeyPress(A,D=[]){let G=0;for(const H of D){if(H==="Alt")G|=1;if(H==="Ctrl"||H==="Control")G|=2;if(H==="Meta")G|=4;if(H==="Shift")G|=8}await this.cdp("Input.dispatchKeyEvent",{type:"keyDown",key:A,modifiers:G});await this.cdp("Input.dispatchKeyEvent",{type:"keyUp",key:A,modifiers:G})}}

package/dist/src/browser/page.test.d.ts

@@ -0,0 +1 @@
+export {};