@jackwener/opencli 1.1.1 → 1.2.0

package/CONTRIBUTING.md

@@ -40,6 +40,11 @@ strategy: public      # public | cookie | header
 browser: false        # true if browser session is needed
 
 args:
+  query:
+    positional: true
+    type: str
+    required: true
+    description: Search keyword
   limit:
     type: int
     default: 20
@@ -76,7 +81,7 @@ cli({
   domain: 'www.mysite.com',
   strategy: Strategy.COOKIE,
   args: [
-    { name: 'query', required: true, help: 'Search query' },
+    { name: 'query', positional: true, required: true, help: 'Search query' },
     { name: 'limit', type: 'int', default: 10, help: 'Max results' },
   ],
   columns: ['title', 'url', 'date'],
@@ -118,6 +123,39 @@ opencli <site> <command> --limit 3 -f json
 opencli <site> <command> -v
 ```
 
+## Arg Design Convention
+
+Use **positional** for the primary, required argument of a command (the "what" — query, symbol, id, url, username). Use **named options** (`--flag`) for secondary/optional configuration (limit, format, sort, page, filters, language, date).
+
+**Rule of thumb**: Think about how the user will type the command. `opencli xueqiu stock SH600519` is more natural than `opencli xueqiu stock --symbol SH600519`.
+
+| Arg type | Positional? | Examples |
+|----------|-------------|----------|
+| Main target (query, symbol, id, url, username) | ✅ `positional: true` | `search '茅台'`, `stock SH600519`, `download BV1xxx` |
+| Configuration (limit, format, sort, page, type, filters) | ❌ Named `--flag` | `--limit 10`, `--format json`, `--sort hot`, `--location seattle` |
+
+Do **not** convert an argument to positional just because it appears first in the file. If the argument is optional, acts like a filter, or selects a mode/configuration, it should usually stay a named option.
+
+YAML example:
+```yaml
+args:
+  query:
+    positional: true     # ← primary arg, user types it directly
+    type: str
+    required: true
+  limit:
+    type: int            # ← config arg, user types --limit 10
+    default: 20
+```
+
+TS example:
+```typescript
+args: [
+  { name: 'query', positional: true, required: true, help: 'Search query' },
+  { name: 'limit', type: 'int', default: 10, help: 'Max results' },
+]
+```
+
 ## Testing
 
 See [TESTING.md](./TESTING.md) for the full guide and exact test locations.

package/README.md

@@ -9,7 +9,7 @@
 [![Node.js Version](https://img.shields.io/node/v/@jackwener/opencli?style=flat-square)](https://nodejs.org)
 [![License](https://img.shields.io/npm/l/@jackwener/opencli?style=flat-square)](./LICENSE)
 
-A CLI tool that turns **any website** or **Electron app** into a command-line interface — Bilibili, Zhihu, 小红书, Twitter/X, Reddit, YouTube, Antigravity, and [many more](#built-in-commands) — powered by browser session reuse and AI-native discovery.
+A CLI tool that turns **any website**, **Electron app**, or **local CLI tool** into a command-line interface — Bilibili, Zhihu, 小红书, Twitter/X, Reddit, YouTube, Antigravity, `gh`, `docker`, and [many more](#built-in-commands) — powered by browser session reuse and AI-native discovery.
 
 **Built for AI Agents**: Simply configure an instruction in your global `AGENT.md` or `.cursorrules` guiding the AI to execute `opencli list` via Bash to discover available tools. Register your favorite local CLIs (`opencli register mycli`), and the AI will automatically learn how to invoke all your tools perfectly!
 
@@ -25,6 +25,7 @@ Turn ANY Electron application into a CLI tool! Recombine, script, and extend app
 - [Quick Start](#quick-start)
 - [Built-in Commands](#built-in-commands)
   - [Desktop App Adapters](#desktop-app-adapters)
+- [External CLI Hub](#external-cli-hub)
 - [Download Support](#download-support)
 - [Output Formats](#output-formats)
 - [For AI Agents (Developer Guide)](#for-ai-agents-developer-guide)
@@ -127,8 +128,8 @@ Run `opencli list` for the live registry.
 | **notion** | `status` `search` `read` `new` `write` `sidebar` `favorites` `export` | Desktop |
 | **discord-app** | `status` `send` `read` `channels` `servers` `search` `members` | Desktop |
 | **v2ex** | `hot` `latest` `topic` `daily` `me` `notifications` | Public / Browser |
-| **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` | Browser |
-| **antigravity** | `status` `send` `read` `new` `dump` `extract-code` `model` `watch` | Desktop |
+| **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` `earnings-date` | Browser |
+| **antigravity** | `status` `send` `read` `new` `dump` `extract-code` `model` `watch` `serve` | Desktop |
 | **chatgpt** | `status` `new` `send` `read` `ask` | Desktop |
 | **xiaohongshu** | `search` `notifications` `feed` `user` `download` `creator-notes` `creator-note-detail` `creator-notes-summary` `creator-profile` `creator-stats` | Browser |
 | **apple-podcasts** | `search` `episodes` `top` | Public |
@@ -140,7 +141,7 @@ Run `opencli list` for the live registry.
 | **bbc** | `news` | Public |
 | **bloomberg** | `main` `markets` `economics` `industries` `tech` `politics` `businessweek` `opinions` `feeds` `news` | Public / Browser |
 | **ctrip** | `search` | Browser |
-| **github** | `search` | Public |
+| **devto** | `top` `tag` `user` | Public |
 | **arxiv** | `search` `paper` | Public |
 | **wikipedia** | `search` `summary` | Public |
 | **hackernews** | `top` | Public |
@@ -160,6 +161,7 @@ Run `opencli list` for the live registry.
 | **stackoverflow** | `hot` `search` `bounties` `unanswered` | Public |
 | **steam** | `top-sellers` | Public |
 | **weread** | `shelf` `search` `book` `highlights` `notes` `notebooks` `ranking` | Browser |
+| **douban** | `search` `top250` `subject` `marks` `reviews` | Browser |
 
 > **Bloomberg note**: The RSS-backed Bloomberg listing commands (`main`, section feeds, `feeds`) work without a browser. `bloomberg news` is for standard Bloomberg story/article pages that your current Chrome session can already access. Audio and some other non-standard pages may fail, and OpenCLI does not bypass Bloomberg paywall or entitlement checks.
 
@@ -198,9 +200,6 @@ Each desktop adapter has its own detailed documentation with commands reference,
 | **ChatWise** | Multi-LLM client (GPT-4, Claude, Gemini) | [Doc](./docs/adapters/desktop/chatwise.md) |
 | **Notion** | Search, read, write Notion pages | [Doc](./docs/adapters/desktop/notion.md) |
 | **Discord** | Discord Desktop — messages, channels, servers | [Doc](./docs/adapters/desktop/discord.md) |
-| **Feishu** | 飞书/Lark Desktop via AppleScript | [Doc](./docs/adapters/desktop/feishu.md) |
-| **WeChat** | 微信 Desktop via AppleScript + Accessibility | [Doc](./docs/adapters/desktop/wechat.md) |
-| **NeteaseMusic** | 网易云音乐 Desktop via CEF/CDP | [Doc](./docs/adapters/desktop/neteasemusic.md) |
 
 ## Download Support
 
@@ -230,11 +229,11 @@ brew install yt-dlp
 
 ```bash
 # Download images/videos from Xiaohongshu note
-opencli xiaohongshu download --note-id abc123 --output ./xhs
+opencli xiaohongshu download abc123 --output ./xhs
 
 # Download Bilibili video (requires yt-dlp)
-opencli bilibili download --bvid BV1xxx --output ./bilibili
-opencli bilibili download --bvid BV1xxx --quality 1080p  # Specify quality
+opencli bilibili download BV1xxx --output ./bilibili
+opencli bilibili download BV1xxx --quality 1080p  # Specify quality
 
 # Download Twitter media from user
 opencli twitter download elonmusk --limit 20 --output ./twitter

package/README.zh-CN.md

@@ -9,7 +9,7 @@
 [![Node.js Version](https://img.shields.io/node/v/@jackwener/opencli?style=flat-square)](https://nodejs.org)
 [![License](https://img.shields.io/npm/l/@jackwener/opencli?style=flat-square)](./LICENSE)
 
-OpenCLI 将任何网站或 Electron 应用（如 Antigravity）变成命令行工具 — B站、知乎、小红书、Twitter/X、Reddit、YouTube 等[多种站点与应用](#内置命令) — 复用浏览器登录态，AI 驱动探索。
+OpenCLI 将任何网站、本地 CLI 或 Electron 应用（如 Antigravity）变成命令行工具 — B站、知乎、小红书、Twitter/X、Reddit、YouTube，以及 `gh`、`docker` 等[多种站点与工具](#内置命令) — 复用浏览器登录态，AI 驱动探索。
 
 **专为 AI Agent 打造**：只需在全局 `.cursorrules` 或 `AGENT.md` 中配置简单指令，引导 AI 通过 Bash 执行 `opencli list` 来检索可用的 CLI 工具及其用法。随后，将你常用的 CLI 列表整合注册进去（`opencli register mycli`），AI 便能瞬间学会自动调用相应的本地工具！
 
@@ -27,6 +27,7 @@ CLI all electron！现在支持把所有 electron 应用 CLI 化，从而组合
 - [快速开始](#快速开始)
 - [内置命令](#内置命令)
   - [桌面应用适配器](#桌面应用适配器)
+- [外部 CLI 枢纽](#外部-cli-枢纽)
 - [下载支持](#下载支持)
 - [输出格式](#输出格式)
 - [致 AI Agent（开发者指南）](#致-ai-agent开发者指南)
@@ -42,6 +43,7 @@ CLI all electron！现在支持把所有 electron 应用 CLI 化，从而组合
 - **CLI All Electron** — 支持把所有 electron 应用（如 Antigravity Ultra）CLI 化，让 AI 控制自己！
 - **多站点覆盖** — 覆盖 B站、知乎、小红书、Twitter、Reddit，以及多种桌面应用
 - **零风控** — 复用 Chrome 登录态，无需存储任何凭证
+- **外部 CLI 枢纽** — 统一发现、自动安装、透传执行 `gh`、`docker`、`kubectl` 等本地 CLI
 - **自修复配置** — `opencli setup` 检查 Browser Bridge 连通性；`opencli doctor` 诊断 daemon、扩展和浏览器连接状态
 - **AI 原生** — `explore` 自动发现 API，`synthesize` 生成适配器，`cascade` 探测认证策略
 - **动态加载引擎** — 声明式的 `.yaml` 或者底层定制的 `.ts` 适配器，放入 `clis/` 文件夹即可自动注册生效
@@ -127,8 +129,8 @@ npm install -g @jackwener/opencli@latest
 | **notion** | `status` `search` `read` `new` `write` `sidebar` `favorites` `export` | 桌面端 |
 | **discord-app** | `status` `send` `read` `channels` `servers` `search` `members` | 桌面端 |
 | **v2ex** | `hot` `latest` `topic` `daily` `me` `notifications` | 公开 / 浏览器 |
-| **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` | 浏览器 |
-| **antigravity** | `status` `send` `read` `new` `dump` `extract-code` `model` `watch` | 桌面端 |
+| **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` `earnings-date` | 浏览器 |
+| **antigravity** | `status` `send` `read` `new` `dump` `extract-code` `model` `watch` `serve` | 桌面端 |
 | **chatgpt** | `status` `new` `send` `read` `ask` | 桌面端 |
 | **xiaohongshu** | `search` `notifications` `feed` `user` `download` `creator-notes` `creator-note-detail` `creator-notes-summary` `creator-profile` `creator-stats` | 浏览器 |
 | **apple-podcasts** | `search` `episodes` `top` | 公开 |
@@ -140,7 +142,7 @@ npm install -g @jackwener/opencli@latest
 | **bbc** | `news` | 公共 API |
 | **bloomberg** | `main` `markets` `economics` `industries` `tech` `politics` `businessweek` `opinions` `feeds` `news` | 公共 API / 浏览器 |
 | **ctrip** | `search` | 浏览器 |
-| **github** | `search` | 公共 API |
+| **devto** | `top` `tag` `user` | 公开 |
 | **arxiv** | `search` `paper` | 公开 |
 | **wikipedia** | `search` `summary` | 公开 |
 | **hackernews** | `top` | 公共 API |
@@ -160,25 +162,45 @@ npm install -g @jackwener/opencli@latest
 | **stackoverflow** | `hot` `search` `bounties` `unanswered` | 公开 |
 | **steam** | `top-sellers` | 公开 |
 | **weread** | `shelf` `search` `book` `highlights` `notes` `notebooks` `ranking` | 浏览器 |
+| **douban** | `search` `top250` `subject` `marks` `reviews` | 浏览器 |
 
 > **Bloomberg 说明**：Bloomberg 的 RSS 列表命令（`main`、各栏目 feed、`feeds`）无需浏览器即可使用。`bloomberg news` 适用于当前 Chrome 会话本身就能访问的标准 Bloomberg 文章页。音频页和部分非标准页面可能失败，OpenCLI 也不会绕过 Bloomberg 的付费墙、登录或权限校验。
 
+### 外部 CLI 枢纽
+
+OpenCLI 也可以作为你现有命令行工具的统一入口，负责发现、自动安装和纯透传执行。
+
+| 外部 CLI | 描述 | 示例 |
+|----------|------|------|
+| **gh** | GitHub CLI | `opencli gh pr list --limit 5` |
+| **obsidian** | Obsidian 仓库管理 | `opencli obsidian search query="AI"` |
+| **docker** | Docker 命令行工具 | `opencli docker ps` |
+| **kubectl** | Kubernetes CLI | `opencli kubectl get pods` |
+| **readwise** | Readwise / Reader CLI | `opencli readwise login` |
+
+**零配置透传**：OpenCLI 会把你的输入原样转发给底层二进制，保留原生 stdout / stderr 行为。
+
+**自动安装**：如果你运行 `opencli gh ...` 时系统中还没有 `gh`，OpenCLI 会优先尝试通过系统包管理器安装，然后自动重试命令。
+
+**注册自定义本地 CLI**：
+
+```bash
+opencli register mycli
+```
+
 ### 桌面应用适配器
 
 每个桌面适配器都有自己详细的文档说明，包括命令参考、启动配置与使用示例：
 
 | 应用 | 描述 | 文档 |
 |-----|-------------|-----|
-| **Cursor** | 控制 Cursor IDE — Composer、对话、代码提取等 | [README](./src/clis/cursor/README.md) |
-| **Codex** | 在后台（无头）驱动 OpenAI Codex CLI Agent | [README](./src/clis/codex/README.md) |
-| **Antigravity** | 在终端直接控制 Antigravity Ultra | [README](./src/clis/antigravity/README.md) |
-| **ChatGPT** | 自动化操作 ChatGPT macOS 桌面客户端 | [README](./src/clis/chatgpt/README.md) |
-| **ChatWise** | 多 LLM 客户端（GPT-4、Claude、Gemini） | [README](./src/clis/chatwise/README.md) |
-| **Notion** | 搜索、读取、写入 Notion 页面 | [README](./src/clis/notion/README.md) |
-| **Discord** | Discord 桌面版 — 消息、频道、服务器 | [README](./src/clis/discord-app/README.md) |
-| **Feishu** | 飞书/Lark 桌面版 (AppleScript 驱动) | [README](./src/clis/feishu/README.md) |
-| **WeChat** | 微信 Mac 桌面端 (AppleScript + 无障碍接口) | [README](./src/clis/wechat/README.md) |
-| **NeteaseMusic** | 网易云音乐 (CEF/CDP 驱动) | [README](./src/clis/neteasemusic/README.md) |
+| **Cursor** | 控制 Cursor IDE — Composer、对话、代码提取等 | [Doc](./docs/adapters/desktop/cursor.md) |
+| **Codex** | 在后台（无头）驱动 OpenAI Codex CLI Agent | [Doc](./docs/adapters/desktop/codex.md) |
+| **Antigravity** | 在终端直接控制 Antigravity Ultra | [Doc](./docs/adapters/desktop/antigravity.md) |
+| **ChatGPT** | 自动化操作 ChatGPT macOS 桌面客户端 | [Doc](./docs/adapters/desktop/chatgpt.md) |
+| **ChatWise** | 多 LLM 客户端（GPT-4、Claude、Gemini） | [Doc](./docs/adapters/desktop/chatwise.md) |
+| **Notion** | 搜索、读取、写入 Notion 页面 | [Doc](./docs/adapters/desktop/notion.md) |
+| **Discord** | Discord 桌面版 — 消息、频道、服务器 | [Doc](./docs/adapters/desktop/discord.md) |
 
 ## 下载支持
 
@@ -208,11 +230,11 @@ brew install yt-dlp
 
 ```bash
 # 下载小红书笔记中的图片/视频
-opencli xiaohongshu download --note-id abc123 --output ./xhs
+opencli xiaohongshu download abc123 --output ./xhs
 
 # 下载B站视频（需要 yt-dlp）
-opencli bilibili download --bvid BV1xxx --output ./bilibili
-opencli bilibili download --bvid BV1xxx --quality 1080p  # 指定画质
+opencli bilibili download BV1xxx --output ./bilibili
+opencli bilibili download BV1xxx --quality 1080p  # 指定画质
 
 # 下载 Twitter 用户的媒体
 opencli twitter download elonmusk --limit 20 --output ./twitter

package/SKILL.md

@@ -39,7 +39,7 @@ Browser commands require:
 
 > **Note**: You must be logged into the target website in Chrome before running commands. Tabs opened during command execution are auto-closed afterwards.
 
-Public API commands (`hackernews`, `github search`, `v2ex`) need no browser.
+Public API commands (`hackernews`, `v2ex`) need no browser.
 
 ## Commands Reference
 
@@ -83,8 +83,10 @@ opencli xueqiu feed                      # 我的关注 timeline
 opencli xueqiu hot --limit 10            # 雪球热榜
 opencli xueqiu search "特斯拉"            # 搜索 (query positional)
 
-# GitHub (public)
-opencli github search "cli"              # 搜索仓库 (query positional)
+# GitHub (via gh External CLI)
+opencli gh repo list                     # 列出仓库 (passthrough to gh)
+opencli gh pr list --limit 5             # PR 列表
+opencli gh issue list                    # Issue 列表
 
 # Twitter/X (browser)
 opencli twitter trending --limit 10      # 热门话题
@@ -176,9 +178,11 @@ opencli antigravity status              # 检查 CDP 连接
 opencli antigravity send "hello"        # 发送文本到当前 agent 聊天框
 opencli antigravity read                # 读取整个聊天记录面板
 opencli antigravity new                 # 清空聊天、开启新对话
+opencli antigravity dump               # 导出 DOM 和快照调试信息
 opencli antigravity extract-code        # 自动抽取 AI 回复中的代码块
 opencli antigravity model claude        # 切换底层模型
 opencli antigravity watch               # 流式监听增量消息
+opencli antigravity serve --port 8082  # 启动 Anthropic 兼容代理
 
 # Barchart (browser)
 opencli barchart quote --symbol AAPL     # 股票行情
@@ -218,8 +222,9 @@ opencli weread ranking --limit 10        # 排行榜
 opencli jimeng generate --prompt "描述"  # AI 生图
 opencli jimeng history --limit 10        # 生成历史
 
-# Grok (Desktop)
-opencli grok ask "问题"                  # 提问 Grok (text positional)
+# Grok (default + explicit web)
+opencli grok ask --prompt "问题"         # 提问 Grok（兼容默认路径）
+opencli grok ask --prompt "问题" --web   # 显式 grok.com consumer web UI 路径
 
 # HuggingFace (public)
 opencli hf top --limit 10                # 热门模型

package/dist/browser/cdp.d.ts

@@ -25,13 +25,13 @@ export declare class CDPBridge {
     }): Promise<IPage>;
     close(): Promise<void>;
     /** Send a CDP command with timeout guard (P0 fix #4) */
-    send(method: string, params?: any, timeoutMs?: number): Promise<any>;
+    send(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
     /** Listen for a CDP event */
-    on(event: string, handler: (params: any) => void): void;
+    on(event: string, handler: (params: unknown) => void): void;
     /** Remove a CDP event listener */
-    off(event: string, handler: (params: any) => void): void;
+    off(event: string, handler: (params: unknown) => void): void;
     /** Wait for a CDP event to fire (one-shot) */
-    waitForEvent(event: string, timeoutMs?: number): Promise<any>;
+    waitForEvent(event: string, timeoutMs?: number): Promise<unknown>;
 }
 declare function selectCDPTarget(targets: CDPTarget[]): CDPTarget | undefined;
 declare function scoreCDPTarget(target: CDPTarget, preferredPattern?: RegExp): number;

package/dist/browser/cdp.js

@@ -9,6 +9,7 @@
  */
 import { WebSocket } from 'ws';
 import { wrapForEval } from './utils.js';
+import { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
 import { clickJs, typeTextJs, pressKeyJs, waitForTextJs, scrollJs, autoScrollJs, networkRequestsJs, } from './dom-helpers.js';
 const CDP_SEND_TIMEOUT = 30_000; // 30s per command
 export class CDPBridge {
@@ -35,7 +36,8 @@ export class CDPBridge {
         }
         return new Promise((resolve, reject) => {
             const ws = new WebSocket(wsUrl);
-            const timeout = setTimeout(() => reject(new Error('CDP connect timeout')), opts?.timeout ?? 10000);
+            const timeoutMs = (opts?.timeout ?? 10) * 1000; // opts.timeout is in seconds
+            const timeout = setTimeout(() => reject(new Error('CDP connect timeout')), timeoutMs);
             ws.on('open', () => {
                 clearTimeout(timeout);
                 this._ws = ws;
@@ -163,14 +165,22 @@ class CDPPage {
     }
     async getCookies(opts = {}) {
         const result = await this.bridge.send('Network.getCookies', opts.url ? { urls: [opts.url] } : {});
-        const cookies = Array.isArray(result?.cookies) ? result.cookies : [];
-        return opts.domain
-            ? cookies.filter((cookie) => typeof cookie.domain === 'string' && cookie.domain.includes(opts.domain))
+        const cookies = isRecord(result) && Array.isArray(result.cookies) ? result.cookies : [];
+        const domain = opts.domain;
+        return domain
+            ? cookies.filter((cookie) => isCookie(cookie) && cookie.domain.includes(domain))
             : cookies;
     }
-    async snapshot(_opts) {
-        // CDP doesn't have a built-in accessibility tree equivalent without additional setup
-        return '(snapshot not available in CDP mode)';
+    async snapshot(opts = {}) {
+        const snapshotJs = generateSnapshotJs({
+            viewportExpand: opts.viewportExpand ?? 800,
+            maxDepth: Math.max(1, Math.min(Number(opts.maxDepth) || 50, 200)),
+            interactiveOnly: opts.interactive ?? false,
+            maxTextLength: opts.maxTextLength ?? 120,
+            includeScrollInfo: true,
+            bboxDedup: true,
+        });
+        return this.evaluate(snapshotJs);
     }
     // ── Shared DOM operations (P1 fix #5 — using dom-helpers.ts) ──
     async click(ref) {
@@ -182,13 +192,20 @@ class CDPPage {
     async pressKey(key) {
         await this.evaluate(pressKeyJs(key));
     }
+    async scrollTo(ref) {
+        return this.evaluate(scrollToRefJs(ref));
+    }
+    async getFormState() {
+        return (await this.evaluate(getFormStateJs()));
+    }
     async wait(options) {
         if (typeof options === 'number') {
             await new Promise(resolve => setTimeout(resolve, options * 1000));
             return;
         }
-        if (options.time) {
-            await new Promise(resolve => setTimeout(resolve, options.time * 1000));
+        if (typeof options.time === 'number') {
+            const waitTime = options.time;
+            await new Promise(resolve => setTimeout(resolve, waitTime * 1000));
             return;
         }
         if (options.text) {
@@ -211,7 +228,7 @@ class CDPPage {
             quality: options.format === 'jpeg' ? (options.quality ?? 80) : undefined,
             captureBeyondViewport: options.fullPage ?? false,
         });
-        const base64 = result.data;
+        const base64 = isRecord(result) && typeof result.data === 'string' ? result.data : '';
         if (options.path) {
             const fs = await import('node:fs');
             const path = await import('node:path');
@@ -222,7 +239,8 @@ class CDPPage {
         return base64;
     }
     async networkRequests(includeStatic = false) {
-        return this.evaluate(networkRequestsJs(includeStatic));
+        const result = await this.evaluate(networkRequestsJs(includeStatic));
+        return Array.isArray(result) ? result : [];
     }
     async tabs() {
         return [];
@@ -249,9 +267,18 @@ class CDPPage {
     async getInterceptedRequests() {
         const { generateReadInterceptedJs } = await import('../interceptor.js');
         const result = await this.evaluate(generateReadInterceptedJs('__opencli_xhr'));
-        return result || [];
+        return Array.isArray(result) ? result : [];
     }
 }
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isCookie(value) {
+    return isRecord(value)
+        && typeof value.name === 'string'
+        && typeof value.value === 'string'
+        && typeof value.domain === 'string';
+}
 // ── CDP target selection (unchanged) ──
 function selectCDPTarget(targets) {
     const preferredPattern = compilePreferredPattern(process.env.OPENCLI_CDP_TARGET);
@@ -311,8 +338,6 @@ function scoreCDPTarget(target, preferredPattern) {
         score += 120;
     if (title.includes('discord'))
         score += 120;
-    if (title.includes('netease'))
-        score += 120;
     if (url.includes('antigravity'))
         score += 100;
     if (url.includes('codex'))
@@ -325,8 +350,6 @@ function scoreCDPTarget(target, preferredPattern) {
         score += 100;
     if (url.includes('discord'))
         score += 100;
-    if (url.includes('netease'))
-        score += 100;
     return score;
 }
 function compilePreferredPattern(raw) {

package/dist/browser/daemon-client.d.ts

@@ -36,4 +36,5 @@ export declare function isExtensionConnected(): Promise<boolean>;
  * Retries up to 3 times with 500ms delay for transient failures.
  */
 export declare function sendCommand(action: DaemonCommand['action'], params?: Omit<DaemonCommand, 'id' | 'action'>): Promise<unknown>;
-export declare function listSessions(): Promise<any[]>;
+export declare function listSessions(): Promise<BrowserSessionInfo[]>;
+import type { BrowserSessionInfo } from '../types.js';

package/dist/browser/dom-helpers.js

@@ -10,8 +10,21 @@ export function clickJs(ref) {
     return `
     (() => {
       const ref = ${safeRef};
-      const el = document.querySelector('[data-ref="' + ref + '"]')
-        || document.querySelectorAll('a, button, input, [role="button"], [tabindex]')[parseInt(ref, 10) || 0];
+      // 1. data-opencli-ref (set by snapshot engine)
+      let el = document.querySelector('[data-opencli-ref="' + ref + '"]');
+      // 2. data-ref (legacy)
+      if (!el) el = document.querySelector('[data-ref="' + ref + '"]');
+      // 3. CSS selector
+      if (!el && ref.match(/^[a-zA-Z#.\\[]/)) {
+        try { el = document.querySelector(ref); } catch {}
+      }
+      // 4. Numeric index into interactive elements
+      if (!el) {
+        const idx = parseInt(ref, 10);
+        if (!isNaN(idx)) {
+          el = document.querySelectorAll('a, button, input, select, textarea, [role="button"], [tabindex]:not([tabindex="-1"])')[idx];
+        }
+      }
       if (!el) throw new Error('Element not found: ' + ref);
       el.scrollIntoView({ behavior: 'instant', block: 'center' });
       el.click();
@@ -26,13 +39,31 @@ export function typeTextJs(ref, text) {
     return `
     (() => {
       const ref = ${safeRef};
-      const el = document.querySelector('[data-ref="' + ref + '"]')
-        || document.querySelectorAll('input, textarea, [contenteditable]')[parseInt(ref, 10) || 0];
+      // 1. data-opencli-ref (set by snapshot engine)
+      let el = document.querySelector('[data-opencli-ref="' + ref + '"]');
+      // 2. data-ref (legacy)
+      if (!el) el = document.querySelector('[data-ref="' + ref + '"]');
+      // 3. CSS selector
+      if (!el && ref.match(/^[a-zA-Z#.\\[]/)) {
+        try { el = document.querySelector(ref); } catch {}
+      }
+      // 4. Numeric index into typeable elements
+      if (!el) {
+        const idx = parseInt(ref, 10);
+        if (!isNaN(idx)) {
+          el = document.querySelectorAll('input, textarea, [contenteditable="true"]')[idx];
+        }
+      }
       if (!el) throw new Error('Element not found: ' + ref);
       el.focus();
-      el.value = ${safeText};
-      el.dispatchEvent(new Event('input', { bubbles: true }));
-      el.dispatchEvent(new Event('change', { bubbles: true }));
+      if (el.isContentEditable) {
+        el.textContent = ${safeText};
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+      } else {
+        el.value = ${safeText};
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+        el.dispatchEvent(new Event('change', { bubbles: true }));
+      }
       return 'typed';
     })()
   `;

package/dist/browser/dom-snapshot.d.ts

@@ -0,0 +1,86 @@
+/**
+ * DOM Snapshot Engine — Advanced DOM pruning for LLM consumption.
+ *
+ * Inspired by browser-use's multi-layer pruning pipeline, adapted for opencli's
+ * Chrome Extension + CDP architecture. Runs entirely in-page via Runtime.evaluate.
+ *
+ * Pipeline:
+ *   1. Walk DOM tree, collect visibility + layout + interactivity signals
+ *   2. Prune invisible, zero-area, non-content elements
+ *   3. SVG & decoration collapse
+ *   4. Shadow DOM traversal
+ *   5. Same-origin iframe content extraction
+ *   6. Bounding-box parent-child dedup (link/button wrapping children)
+ *   7. Paint-order occlusion detection (overlay/modal coverage)
+ *   8. Attribute whitelist filtering
+ *   9. Table-aware serialization (markdown tables)
+ *  10. Token-efficient serialization with interactive indices
+ *  11. data-ref annotation for click/type targeting
+ *  12. Hidden interactive element hints (scroll-to-reveal)
+ *  13. Incremental diff (mark new elements with *)
+ *
+ * Additional tools:
+ *   - scrollToRefJs(ref) — scroll to a data-opencli-ref element
+ *   - getFormStateJs()  — extract all form fields as structured JSON
+ */
+export interface SnapshotOptions {
+    /** Extra pixels beyond viewport to include (default 800) */
+    viewportExpand?: number;
+    /** Maximum DOM depth to traverse (default 50) */
+    maxDepth?: number;
+    /** Only emit interactive elements and their landmark ancestors */
+    interactiveOnly?: boolean;
+    /** Maximum text content length per node (default 120) */
+    maxTextLength?: number;
+    /** Include scroll position info on scrollable containers (default true) */
+    includeScrollInfo?: boolean;
+    /** Enable bounding-box parent-child dedup (default true) */
+    bboxDedup?: boolean;
+    /** Traverse Shadow DOM roots (default true) */
+    includeShadowDom?: boolean;
+    /** Extract same-origin iframe content (default true) */
+    includeIframes?: boolean;
+    /** Maximum number of iframes to process (default 5) */
+    maxIframes?: number;
+    /** Enable paint-order occlusion detection (default true) */
+    paintOrderCheck?: boolean;
+    /** Annotate interactive elements with data-opencli-ref (default true) */
+    annotateRefs?: boolean;
+    /** Report hidden interactive elements outside viewport (default true) */
+    reportHidden?: boolean;
+    /** Filter ad/noise elements (default true) */
+    filterAds?: boolean;
+    /** Serialize tables as markdown (default true) */
+    markdownTables?: boolean;
+    /** Previous snapshot hash set (JSON array of hashes) for diff marking (default null) */
+    previousHashes?: string | null;
+}
+/**
+ * Generate JS to scroll to an element identified by data-opencli-ref.
+ * Completes the snapshot→action loop: snapshot identifies `[3]<button>`,
+ * caller can then `scrollToRef('3')` to bring it into view.
+ */
+export declare function scrollToRefJs(ref: string): string;
+/**
+ * Generate JS to extract all form field values from the page.
+ * Returns structured JSON: { forms: [{ id, action, fields: [{ tag, type, name, value, ... }] }] }
+ */
+export declare function getFormStateJs(): string;
+/**
+ * Generate JavaScript code that, when evaluated in a page context via CDP
+ * Runtime.evaluate, returns a pruned DOM snapshot string optimised for LLMs.
+ *
+ * The snapshot output format:
+ *   [42]<button type=submit>Search</button>
+ *   |scroll|<div> (0.5↑ 3.2↓)
+ *     *[58]<a href=/r/1>Result 1</a>
+ *     [59]<a href=/r/2>Result 2</a>
+ *
+ * - `[id]` — interactive element with backend index for targeting
+ * - `*` prefix — newly appeared element (incremental diff)
+ * - `|scroll|` — scrollable container with page counts
+ * - `|shadow|` — Shadow DOM boundary
+ * - `|iframe|` — iframe content
+ * - `|table|` — markdown table rendering
+ */
+export declare function generateSnapshotJs(opts?: SnapshotOptions): string;