@jackwener/opencli 1.6.9 → 1.7.0

package/README.md

@@ -1,34 +1,36 @@
 # OpenCLI
 
-> **Make any website, Electron App, or Local Tool your CLI.**
-> Zero risk · Reuse Chrome/Chromium login · AI-powered discovery · Universal CLI Hub
+> **Turn websites, browser sessions, Electron apps, and local tools into deterministic interfaces for humans and AI agents.**
+> Reuse your logged-in browser, automate live workflows, and crystallize repeated actions into reusable CLI commands.
 
 [![中文文档](https://img.shields.io/badge/docs-%E4%B8%AD%E6%96%87-0F766E?style=flat-square)](./README.zh-CN.md)
 [![npm](https://img.shields.io/npm/v/@jackwener/opencli?style=flat-square)](https://www.npmjs.com/package/@jackwener/opencli)
 [![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**, **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.
+OpenCLI gives you one surface for three different kinds of automation:
 
-**Built for AI Agents** — Load the [`opencli-operate` skill](./skills/opencli-operate/SKILL.md) to give any AI agent (Claude Code, Cursor) direct browser control. Operate any website, then crystallize those interactions into reusable CLI commands. Configure `opencli list` in your `AGENT.md` or `.cursorrules` so the AI auto-discovers all available tools.
+- **Use built-in adapters** for sites like Bilibili, Zhihu, Xiaohongshu, Reddit, HackerNews, Twitter/X, and [many more](#built-in-commands).
+- **Drive a live browser directly** with `opencli browser` when an AI agent needs to click, type, extract, or inspect a page in real time.
+- **Generate new adapters** from real browser behavior with `explore`, `synthesize`, `generate`, and `cascade`.
 
-**CLI Hub** — Register any local CLI (`opencli register mycli`) so AI agents can discover and call it alongside built-in commands. Auto-installs missing tools via your package manager (e.g. if `gh` isn't installed, `opencli gh ...` runs `brew install gh` first then re-executes seamlessly).
+It also works as a **CLI hub** for local tools such as `gh`, `docker`, and other binaries you register yourself, plus **desktop app adapters** for Electron apps like Cursor, Codex, Antigravity, ChatGPT, and Notion.
 
-**CLI for Electron Apps** — Turn any Electron application into a CLI tool. Recombine, script, and extend apps like Antigravity Ultra from the terminal. AI agents can now control other AI apps natively.
+## Why OpenCLI
 
 ---
 
 ## Highlights
 
 - **CLI All Electron** — CLI-ify apps like Antigravity Ultra! Now AI can control itself natively.
-- **Browser Automation** — `operate` gives AI agents direct browser control: click, type, extract, screenshot — any interaction, fully scriptable.
+- **Browser Automation** — `browser` gives AI agents direct browser control: click, type, extract, screenshot — any interaction, fully scriptable.
 - **Website → CLI** — Turn any website into a deterministic CLI: 70+ pre-built adapters, or crystallize your own with `opencli record`.
 - **Account-safe** — Reuses Chrome/Chromium logged-in state; your credentials never leave the browser.
 - **Anti-detection built-in** — Patches `navigator.webdriver`, stubs `window.chrome`, fakes plugin lists, cleans ChromeDriver/Playwright globals, and strips CDP frames from Error stack traces. Extensive anti-fingerprinting and risk-control evasion measures baked in at every layer.
-- **AI Agent ready** — `explore` discovers APIs, `synthesize` generates adapters, `cascade` finds auth strategies, `operate` controls the browser directly.
+- **AI Agent ready** — `explore` discovers APIs, `synthesize` generates adapters, `cascade` finds auth strategies, `browser` controls the browser directly.
 - **External CLI Hub** — Discover, auto-install, and passthrough commands to any external CLI (gh, obsidian, docker, etc). Zero setup.
 - **Self-healing setup** — `opencli doctor` diagnoses and auto-starts the daemon, extension, and live browser connectivity.
-- **Dynamic Loader** — Simply drop `.ts` or `.yaml` adapters into the `clis/` folder for auto-registration.
+- **Dynamic Loader** — Simply drop `.ts` adapters into the `clis/` folder for auto-registration.
 - **Zero LLM cost** — No tokens consumed at runtime. Run 10,000 times and pay nothing.
 - **Deterministic** — Same command, same output schema, every time. Pipeable, scriptable, CI-friendly.
 - **Broad coverage** — 79+ sites across global and Chinese platforms (Bilibili, Zhihu, Xiaohongshu, Reddit, HackerNews, and more), plus desktop Electron apps via CDP.
@@ -37,90 +39,156 @@ A CLI tool that turns **any website**, **Electron app**, or **local CLI tool** i
 
 ## Quick Start
 
-### 1. Install Browser Bridge Extension
+### 1. Install OpenCLI
 
-> OpenCLI connects to your browser through a lightweight **Browser Bridge** Chrome/Chromium extension + micro-daemon (zero config, auto-start).
+```bash
+npm install -g @jackwener/opencli
+```
 
-1. Go to the GitHub [Releases page](https://github.com/jackwener/opencli/releases) and download the latest `opencli-extension.zip`.
-2. Unzip the file and open `chrome://extensions`, enable **Developer mode** (top-right toggle).
-3. Click **Load unpacked** and select the unzipped folder.
+### 2. Install the Browser Bridge Extension
+
+OpenCLI connects to Chrome/Chromium through a lightweight Browser Bridge extension plus a small local daemon. The daemon auto-starts when needed.
 
-### 2. Install OpenCLI
+1. Download the latest `opencli-extension.zip` from the GitHub [Releases page](https://github.com/jackwener/opencli/releases).
+2. Unzip it, open `chrome://extensions`, and enable **Developer mode**.
+3. Click **Load unpacked** and select the unzipped folder.
 
-**Install via npm (recommended)**
+### 3. Verify the setup
 
 ```bash
-npm install -g @jackwener/opencli
+opencli doctor
+```
 
-# Install AI skills for Claude Code / Cursor
-npx skills add jackwener/opencli
+### 4. Run your first commands
+
+```bash
+opencli list
+opencli hackernews top --limit 5
+opencli bilibili hot --limit 5
 ```
 
-### 3. Verify & Try
+## For Humans
+
+Use OpenCLI directly when you want a reliable command instead of a live browser session:
+
+- `opencli list` shows every registered command.
+- `opencli <site> <command>` runs a built-in or generated adapter.
+- `opencli register mycli` exposes a local CLI through the same discovery surface.
+- `opencli doctor` helps diagnose browser connectivity.
+
+## For AI Agents
+
+Use two different entry points depending on the task:
+
+- [`skills/opencli-explorer/SKILL.md`](./skills/opencli-explorer/SKILL.md): the entry point for creating new adapters — supports both fully automated generation (`opencli generate <url>`) and manual exploration workflows.
+- [`skills/opencli-browser/SKILL.md`](./skills/opencli-browser/SKILL.md): the low-level control surface for live browsing, debugging, and manual intervention.
+
+Install the packaged skills with:
 
 ```bash
-opencli doctor          # Check extension + daemon connectivity
-opencli daemon status   # Check daemon state (PID, uptime, memory)
+npx skills add jackwener/opencli
 ```
 
-**Try it out:**
+Or install only what you need:
 
 ```bash
-opencli list                           # See all commands
-opencli hackernews top --limit 5       # Public API, no browser needed
-opencli bilibili hot --limit 5         # Browser command (requires Extension)
+npx skills add jackwener/opencli --skill opencli-usage
+npx skills add jackwener/opencli --skill opencli-browser
+npx skills add jackwener/opencli --skill opencli-explorer
+npx skills add jackwener/opencli --skill opencli-oneshot
 ```
 
-### 4. Browser Automation — Make Websites Accessible for AI Agents
+In practice:
 
-Point your AI agent (Claude Code, Cursor) to [`skills/opencli-operate/SKILL.md`](./skills/opencli-operate/SKILL.md). It has everything needed — full command reference, examples, and workflow.
+- start with `opencli-explorer` when the agent needs a reusable command for a site (it covers both automated and manual flows)
+- use `opencli-browser` when the agent needs to inspect or steer the page directly
 
-Available commands: `open`, `state`, `click`, `type`, `select`, `keys`, `wait`, `get`, `screenshot`, `scroll`, `back`, `eval`, `network`, `init`, `verify`, `close`.
+Available browser commands include `open`, `state`, `click`, `type`, `select`, `keys`, `wait`, `get`, `screenshot`, `scroll`, `back`, `eval`, `network`, `init`, `verify`, and `close`.
 
-### Update
+## Core Concepts
 
-```bash
-npm install -g @jackwener/opencli@latest
-```
+### `browser`: live control
 
-### Install AI Skills
+Use `opencli browser` when the task is inherently interactive and the agent needs to operate the page directly.
 
-OpenCLI provides [skills](./skills/) for AI agents (Claude Code, etc.):
+### Built-in adapters: stable commands
 
-```bash
-# Install all OpenCLI skills
-npx skills add jackwener/opencli
+Use site-specific commands such as `opencli hackernews top` or `opencli reddit hot` when the capability already exists and you want deterministic output.
 
-# Or install specific skills
-npx skills add jackwener/opencli --skill opencli-usage      # Command reference
-npx skills add jackwener/opencli --skill opencli-operate     # Browser automation for AI agents
-npx skills add jackwener/opencli --skill opencli-explorer    # Adapter development guide
-npx skills add jackwener/opencli --skill opencli-oneshot     # Quick command reference
-```
+### `explore` / `synthesize` / `generate`: create new CLIs
 
----
+Use these commands when the site you need is not covered yet:
 
-### For Developers
+- `explore` inspects the page, network activity, and capability surface.
+- `synthesize` turns exploration artifacts into evaluate-based YAML adapters.
+- `generate` runs the verified generation path and returns either a usable command or a structured explanation of why completion was blocked or needs human review.
 
-**Install from source**
+### `cascade`: auth strategy discovery
 
-```bash
-git clone git@github.com:jackwener/opencli.git && cd opencli && npm install && npm run build && npm link
-```
+Use `cascade` to probe fallback auth paths such as public endpoints, cookies, and custom headers before you commit to an adapter design.
 
-**Load Source Browser Bridge Extension**
+### CLI Hub and desktop adapters
 
-1. Open `chrome://extensions` and enable **Developer mode** (top-right toggle).
-2. Click **Load unpacked** and select the `extension/` directory from this repository.
+OpenCLI is not only for websites. It can also:
 
----
+- expose local binaries like `gh`, `docker`, `obsidian`, or custom tools through `opencli <tool> ...`
+- control Electron desktop apps through dedicated adapters and CDP-backed integrations
 
 ## Prerequisites
 
 - **Node.js**: >= 20.0.0 (or **Bun** >= 1.0)
-- **Chrome or Chromium** running **and logged into the target site** (e.g. bilibili.com, zhihu.com, xiaohongshu.com, goofish.com).
+- **Chrome or Chromium** running and logged into the target site for browser-backed commands
+
+> **Important**: Browser-backed commands reuse your Chrome/Chromium login session. If you get empty data or permission-like failures, first confirm the site is already open and authenticated in Chrome/Chromium.
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENCLI_DAEMON_PORT` | `19825` | HTTP port for the daemon-extension bridge |
+| `OPENCLI_WINDOW_FOCUSED` | `false` | Set to `1` to open automation windows in the foreground (useful for debugging) |
+| `OPENCLI_BROWSER_CONNECT_TIMEOUT` | `30` | Seconds to wait for browser connection |
+| `OPENCLI_BROWSER_COMMAND_TIMEOUT` | `60` | Seconds to wait for a single browser command |
+| `OPENCLI_BROWSER_EXPLORE_TIMEOUT` | `120` | Seconds to wait for explore/record operations |
+| `OPENCLI_CDP_ENDPOINT` | — | Chrome DevTools Protocol endpoint for remote browser or Electron apps |
+| `OPENCLI_CDP_TARGET` | — | Filter CDP targets by URL substring (e.g. `detail.1688.com`) |
+| `OPENCLI_VERBOSE` | `false` | Enable verbose logging (`-v` flag also works) |
+| `OPENCLI_DIAGNOSTIC` | `false` | Set to `1` to capture structured diagnostic context on failures |
+
+## Update
+
+```bash
+npm install -g @jackwener/opencli@latest
+
+# If you use the packaged OpenCLI skills, refresh them too
+npx skills add jackwener/opencli
+```
+
+Or refresh only the skills you actually use:
+
+```bash
+npx skills add jackwener/opencli --skill opencli-usage
+npx skills add jackwener/opencli --skill opencli-browser
+npx skills add jackwener/opencli --skill opencli-explorer
+npx skills add jackwener/opencli --skill opencli-oneshot
+```
+
+## For Developers
+
+Install from source:
+
+```bash
+git clone git@github.com:jackwener/opencli.git
+cd opencli
+npm install
+npm run build
+npm link
+```
+
+To load the source Browser Bridge extension:
 
-> **⚠️ Important**: Browser commands reuse your Chrome/Chromium login session. You must be logged into the target website in Chrome or Chromium before running commands. If you get empty data or errors, check your login status first.
+1. Open `chrome://extensions` and enable **Developer mode**.
+2. Click **Load unpacked** and select this repository's `extension/` directory.
 
 ## Built-in Commands
 
@@ -135,6 +203,7 @@ git clone git@github.com:jackwener/opencli.git && cd opencli && npm install && n
 | **zhihu** | `hot` `search` `question` `download` `follow` `like` `favorite` `comment` `answer` |
 | **amazon** | `bestsellers` `search` `product` `offer` `discussion` `movers-shakers` `new-releases` |
 | **1688** | `search` `item` `assets` `download` `store` |
+| **gitee** | `trending` `search` `user` |
 | **gemini** | `new` `ask` `image` `deep-research` `deep-research-result` |
 | **yuanbao** | `new` `ask` |
 | **notebooklm** | `status` `list` `open` `current` `get` `history` `summary` `note-list` `notes-get` `source-list` `source-get` `source-fulltext` `source-guide` |
@@ -251,9 +320,9 @@ opencli plugin uninstall my-tool
 
 | Plugin | Type | Description |
 |--------|------|-------------|
-| [opencli-plugin-github-trending](https://github.com/ByteYue/opencli-plugin-github-trending) | YAML | GitHub Trending repositories |
+| [opencli-plugin-github-trending](https://github.com/ByteYue/opencli-plugin-github-trending) | TS | GitHub Trending repositories |
 | [opencli-plugin-hot-digest](https://github.com/ByteYue/opencli-plugin-hot-digest) | TS | Multi-platform trending aggregator |
-| [opencli-plugin-juejin](https://github.com/Astro-Han/opencli-plugin-juejin) | YAML | 稀土掘金 (Juejin) hot articles |
+| [opencli-plugin-juejin](https://github.com/Astro-Han/opencli-plugin-juejin) | TS | 稀土掘金 (Juejin) hot articles |
 | [opencli-plugin-vk](https://github.com/flobo3/opencli-plugin-vk) | TS | VK (VKontakte) wall, feed, and search |
 
 See [Plugins Guide](./docs/guide/plugins.md) for creating your own plugin.
@@ -266,7 +335,7 @@ See [Plugins Guide](./docs/guide/plugins.md) for creating your own plugin.
 
 ```bash
 opencli explore https://example.com --site mysite   # Discover APIs + capabilities
-opencli synthesize mysite                            # Generate YAML adapters
+opencli synthesize mysite                            # Generate TS adapters
 opencli generate https://example.com --goal "hot"   # One-shot: explore → synthesize → register
 opencli cascade https://api.example.com/data         # Auto-probe: PUBLIC → COOKIE → HEADER
 ```

package/README.zh-CN.md

@@ -1,128 +1,183 @@
 # OpenCLI
 
-> **把任何网站、本地工具、Electron 应用变成能够让 AI 调用的命令行！**  
-> 零风控 · 复用 Chrome/Chromium 登录 · AI 自动发现接口 · 全能 CLI 枢纽
+> **把网站、浏览器会话、Electron 应用和本地工具，统一变成适合人类与 AI Agent 使用的确定性接口。**  
+> 复用浏览器登录态，先自动化真实操作，再把高频流程沉淀成可复用的 CLI 命令。
 
 [![English](https://img.shields.io/badge/docs-English-1D4ED8?style=flat-square)](./README.md)
 [![npm](https://img.shields.io/npm/v/@jackwener/opencli?style=flat-square)](https://www.npmjs.com/package/@jackwener/opencli)
 [![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 将任何网站、本地 CLI 或 Electron 应用（如 Antigravity）变成命令行工具 — B站、知乎、小红书、Twitter/X、Reddit、YouTube，以及 `gh`、`docker` 等[多种站点与工具](#内置命令) — 复用浏览器登录态，AI 驱动探索。
+OpenCLI 可以用同一套 CLI 做三类事情：
 
-**专为 AI Agent 打造**：加载 [`opencli-operate` skill](./skills/opencli-operate/SKILL.md)，赋予 AI Agent（Claude Code、Cursor 等）直接操控浏览器的能力——操作任意网站，并将这些交互沉淀为可复用的 CLI 命令。在 `AGENT.md` 或 `.cursorrules` 中配置 `opencli list`，AI 即可自动发现并调用所有可用工具。
+- **直接使用现成适配器**：B站、知乎、小红书、Twitter/X、Reddit、HackerNews 等 [79+ 站点](#内置命令) 开箱即用。
+- **直接驱动浏览器**：用 `opencli browser` 让 AI Agent 实时点击、输入、提取、截图、检查页面状态。
+- **把新网站生成成 CLI**：通过 `explore`、`synthesize`、`generate`、`cascade` 从真实页面行为推导出新的适配器。
 
-**opencli 支持 CLI 化所有 electron 应用！最强大更新来袭！**
-CLI all electron！现在支持把所有 electron 应用 CLI 化，从而组合出各种神奇的能力。
-如果你在使用诸如 Antigravity Ultra 等工具时觉得不够灵活或难以扩展，现在通过 OpenCLI 把他 CLI 化，轻松打破界限。
-现在，**AI 可以自己控制自己**！结合 cc/openclaw 就可以远程控制任何 electron 应用！无限玩法！！
+除了网站能力，OpenCLI 还是一个 **CLI 枢纽**：你可以把 `gh`、`docker` 等本地工具统一注册到 `opencli` 下，也可以通过桌面端适配器控制 Cursor、Codex、Antigravity、ChatGPT、Notion 等 Electron 应用。
 
----
+## 为什么是 OpenCLI
 
-## 亮点
+- **同一个心智模型**：网站、浏览器自动化、Electron 应用、本地 CLI 都走同一个入口。
+- **复用真实会话**：浏览器命令直接使用你已经登录的 Chrome/Chromium，而不是重新造一套认证。
+- **输出稳定**：适配器命令返回固定结构，适合 shell、脚本、CI 和 AI Agent 工具调用。
+- **面向 AI Agent**：`browser` 负责实时操作，`explore` 负责探索接口，`synthesize` 负责生成适配器，`cascade` 负责探测认证路径。
+- **运行成本低**：已有命令运行时不消耗模型 token。
+- **天然可扩展**：既能用内置能力，也能注册本地 CLI，或直接往 `clis/` 丢 `.ts` 适配器。
 
-- **CLI All Electron** — 支持把所有 electron 应用（如 Antigravity Ultra）CLI 化，让 AI 控制自己！
-- **浏览器自动化** — `operate` 赋予 AI Agent 直接操控浏览器的能力：点击、输入、提取、截图，任意交互皆可脚本化
-- **网页转 CLI** — 将任意网站变成确定性命令行工具：79+ 预置适配器，或用 `opencli record` 沉淀自己的操作
-- **多站点覆盖** — 79+ 站点，横跨全球与中国平台（B站、知乎、小红书、Reddit、HackerNews 等），并支持通过 CDP 控制桌面 Electron 应用
-- **零风控** — 复用 Chrome/Chromium 登录态，无需存储任何凭证
-- **外部 CLI 枢纽** — 统一发现、自动安装、透传执行 `gh`、`docker` 等本地 CLI
-- **自修复配置** — `opencli doctor` 自动启动 daemon，诊断扩展和浏览器连接状态
-- **AI 原生** — `explore` 自动发现 API，`synthesize` 生成适配器，`cascade` 探测认证策略，`operate` 直接控制浏览器
-- **零 LLM 成本** — 运行时不消耗任何 token，跑一万次不花一分钱
-- **确定性** — 同一命令永远返回同一结构，可管道化、可脚本化、CI 友好
+## 快速开始
 
-## 前置要求
+### 1. 安装 OpenCLI
 
-- **Node.js**: >= 20.0.0
-- **Chrome 或 Chromium** 浏览器正在运行，且**已登录目标网站**（如 bilibili.com、zhihu.com、xiaohongshu.com、goofish.com）
+```bash
+npm install -g @jackwener/opencli
+```
 
-> **⚠️ 重要**：大多数命令复用你的 Chrome/Chromium 登录状态。运行命令前，你必须已在 Chrome 或 Chromium 中打开目标网站并完成登录。如果获取到空数据或报错，请先检查你的浏览器登录状态。
+### 2. 安装 Browser Bridge 扩展
 
-OpenCLI 通过轻量化的 **Browser Bridge** Chrome/Chromium 扩展 + 微型 daemon 与浏览器通信（零配置，自动启动）。
+OpenCLI 通过轻量 Browser Bridge 扩展和本地微型 daemon 与 Chrome/Chromium 通信。daemon 会按需自动启动。
 
-### Browser Bridge 扩展配置
+1. 到 GitHub [Releases 页面](https://github.com/jackwener/opencli/releases) 下载最新的 `opencli-extension.zip`。
+2. 解压后打开 `chrome://extensions`，启用 **开发者模式**。
+3. 点击 **加载已解压的扩展程序**，选择解压后的目录。
 
-你可以选择以下任一方式安装扩展：
+### 3. 验证环境
 
-**方式一：下载构建好的安装包（推荐）**
-1. 到 GitHub [Releases 页面](https://github.com/jackwener/opencli/releases) 下载最新的 `opencli-extension.zip`。
-2. 解压后在 Chrome 或 Chromium 中打开 `chrome://extensions`，启用右上角的 **开发者模式**。
-3. 点击 **加载已解压的扩展程序**，选择解压后的文件夹。
+```bash
+opencli doctor
+```
 
-**方式二：加载源码（针对开发者）**
-1. 同样在 `chrome://extensions` 开启 **开发者模式**。
-2. 点击 **加载已解压的扩展程序**，选择本仓库代码树中的 `extension/` 文件夹。
+### 4. 跑第一个命令
 
-完成！运行任何 opencli 浏览器命令时，后台微型 daemon 会自动启动与浏览器通信。无需配 API Token，零代码配置。
+```bash
+opencli list
+opencli hackernews top --limit 5
+opencli bilibili hot --limit 5
+```
 
-> **Tip**：后续诊断和 daemon 管理：
-> ```bash
-> opencli doctor            # 检查扩展和 daemon 连通性
-> opencli daemon status     # 查看 daemon 状态
-> opencli daemon stop       # 停止 daemon
-> ```
+## 给人类用户
 
-## 快速开始
+如果你只是想稳定地调用网站或桌面应用能力，主路径很简单：
 
-### npm 全局安装（推荐）
+- `opencli list` 查看当前所有命令
+- `opencli <site> <command>` 调用内置或生成好的适配器
+- `opencli register mycli` 把本地 CLI 接入同一发现入口
+- `opencli doctor` 处理浏览器连通性问题
 
-```bash
-npm install -g @jackwener/opencli
+## 给 AI Agent
 
-# 安装 AI Skills（Claude Code / Cursor）
-npx skills add jackwener/opencli
-```
+按任务类型，AI Agent 有两个不同入口：
 
-直接使用：
+- [`skills/opencli-explorer/SKILL.md`](./skills/opencli-explorer/SKILL.md)：适配器创建入口，支持全自动生成（`opencli generate <url>`）和手动探索两种流程。
+- [`skills/opencli-browser/SKILL.md`](./skills/opencli-browser/SKILL.md)：底层控制入口，适合实时操作页面、debug 和人工介入。
+
+安装全部 OpenCLI skills：
 
 ```bash
-opencli list                              # 查看所有命令
-opencli list -f yaml                      # 以 YAML 列出所有命令
-opencli hackernews top --limit 5          # 公共 API，无需浏览器
-opencli bilibili hot --limit 5            # 浏览器命令
-opencli zhihu hot -f json                 # JSON 输出
-opencli zhihu hot -f yaml                 # YAML 输出
+npx skills add jackwener/opencli
 ```
 
-### 从源码安装（面向开发者）
+或只装需要的 skill：
 
 ```bash
-git clone git@github.com:jackwener/opencli.git
-cd opencli 
-npm install
-npm run build
-npm link      # 链接到全局环境
-opencli list  # 可以在任何地方使用了！
+npx skills add jackwener/opencli --skill opencli-usage
+npx skills add jackwener/opencli --skill opencli-browser
+npx skills add jackwener/opencli --skill opencli-explorer
+npx skills add jackwener/opencli --skill opencli-oneshot
 ```
 
-### 更新
+实际使用上：
 
-```bash
-npm install -g @jackwener/opencli@latest
-```
+- 需要把某个站点收成可复用命令时，优先走 `opencli-explorer`（涵盖自动和手动两种路径）
+- 需要直接检查页面、操作页面时，再走 `opencli-browser`
+
+`browser` 可用命令包括：`open`、`state`、`click`、`type`、`select`、`keys`、`wait`、`get`、`screenshot`、`scroll`、`back`、`eval`、`network`、`init`、`verify`、`close`。
+
+## 核心概念
+
+### `browser`：实时操作
+
+当任务本身就是交互式页面操作时，使用 `opencli browser` 直接驱动浏览器。
 
-### 浏览器自动化 — 让 AI Agent 直接控制浏览器
+### 内置适配器：稳定命令
 
-将 [`skills/opencli-operate/SKILL.md`](./skills/opencli-operate/SKILL.md) 指向你的 AI Agent（Claude Code、Cursor），即可开箱即用，内含完整命令参考与使用示例。
+当某个站点能力已经存在时，优先使用 `opencli hackernews top`、`opencli reddit hot` 这类稳定命令，而不是重新走一遍浏览器操作。
 
-可用命令：`open`、`state`、`click`、`type`、`select`、`keys`、`wait`、`get`、`screenshot`、`scroll`、`back`、`eval`、`network`、`init`、`verify`、`close`。
+### `explore` / `synthesize` / `generate`：生成新的 CLI
 
-### 安装 AI Skills
+当你需要的网站还没覆盖时：
 
-OpenCLI 提供 [skills](./skills/) 供 AI Agent（Claude Code 等）使用：
+- `explore` 负责观察页面、网络请求和能力边界
+- `synthesize` 负责把探索结果转成 evaluate-based YAML 适配器
+- `generate` 负责跑通 verified generation 主链路，最后要么给出可直接使用的命令，要么返回结构化的阻塞原因 / 人工介入结果
+
+### `cascade`：认证策略探测
+
+用 `cascade` 去判断某个能力应该优先走公开接口、Cookie 还是自定义 Header，而不是一开始就把适配器写死。
+
+### CLI 枢纽与桌面端适配器
+
+OpenCLI 不只是网站 CLI，还可以：
+
+- 统一代理本地二进制工具，例如 `gh`、`docker`、`obsidian`
+- 通过专门适配器和 CDP 集成控制 Electron 桌面应用
+
+## 前置要求
+
+- **Node.js**: >= 20.0.0
+- 浏览器型命令需要 Chrome 或 Chromium 处于运行中，并已登录目标网站
+
+> **重要**：浏览器型命令直接复用你的 Chrome/Chromium 登录态。如果拿到空数据或出现权限类失败，先确认目标站点已经在浏览器里打开并完成登录。
+
+## 配置
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `OPENCLI_DAEMON_PORT` | `19825` | daemon-extension 通信端口 |
+| `OPENCLI_WINDOW_FOCUSED` | `false` | 设为 `1` 时 automation 窗口在前台打开（适合调试） |
+| `OPENCLI_BROWSER_CONNECT_TIMEOUT` | `30` | 浏览器连接超时（秒） |
+| `OPENCLI_BROWSER_COMMAND_TIMEOUT` | `60` | 单个浏览器命令超时（秒） |
+| `OPENCLI_BROWSER_EXPLORE_TIMEOUT` | `120` | explore/record 操作超时（秒） |
+| `OPENCLI_CDP_ENDPOINT` | — | Chrome DevTools Protocol 端点，用于远程浏览器或 Electron 应用 |
+| `OPENCLI_CDP_TARGET` | — | 按 URL 子串过滤 CDP target（如 `detail.1688.com`） |
+| `OPENCLI_VERBOSE` | `false` | 启用详细日志（`-v` 也可以） |
+| `OPENCLI_DIAGNOSTIC` | `false` | 设为 `1` 时在失败时输出结构化诊断上下文 |
+
+## 更新
 
 ```bash
-# 安装所有 OpenCLI skills
+npm install -g @jackwener/opencli@latest
+
+# 如果你在用打包发布的 OpenCLI skills，也一起刷新
 npx skills add jackwener/opencli
+```
+
+如果你只装了部分 skill，也可以只刷新自己在用的：
+
+```bash
+npx skills add jackwener/opencli --skill opencli-usage
+npx skills add jackwener/opencli --skill opencli-browser
+npx skills add jackwener/opencli --skill opencli-explorer
+npx skills add jackwener/opencli --skill opencli-oneshot
+```
+
+## 面向开发者
 
-# 或安装特定 skill
-npx skills add jackwener/opencli --skill opencli-usage      # 命令参考
-npx skills add jackwener/opencli --skill opencli-operate     # 浏览器自动化（AI Agent 专用）
-npx skills add jackwener/opencli --skill opencli-explorer    # 适配器开发指南
-npx skills add jackwener/opencli --skill opencli-oneshot     # 快速命令参考
+从源码安装：
+
+```bash
+git clone git@github.com:jackwener/opencli.git
+cd opencli
+npm install
+npm run build
+npm link
 ```
 
+加载源码版 Browser Bridge 扩展：
+
+1. 打开 `chrome://extensions` 并启用 **开发者模式**
+2. 点击 **加载已解压的扩展程序**，选择本仓库里的 `extension/` 目录
+
 ## 内置命令
 
 运行 `opencli list` 查看完整注册表。
@@ -188,6 +243,7 @@ npx skills add jackwener/opencli --skill opencli-oneshot     # 快速命令参
 | **google** | `news` `search` `suggest` `trends` | 公开 |
 | **amazon** | `bestsellers` `search` `product` `offer` `discussion` `movers-shakers` `new-releases` | 浏览器 |
 | **1688** | `search` `item` `assets` `download` `store` | 浏览器 |
+| **gitee** | `trending` `search` `user` | 公开 / 浏览器 |
 | **gemini** | `new` `ask` `image` `deep-research` `deep-research-result` | 浏览器 |
 | **spotify** | `auth` `status` `play` `pause` `next` `prev` `volume` `search` `queue` `shuffle` `repeat` | OAuth API |
 | **notebooklm** | `status` `list` `open` `current` `get` `history` `summary` `note-list` `notes-get` `source-list` `source-get` `source-fulltext` `source-guide` | 浏览器 |
@@ -383,7 +439,7 @@ opencli plugin uninstall my-tool                            # 卸载
 # 1. Deep Explore — 网络拦截 → 响应分析 → 能力推理 → 框架检测
 opencli explore https://example.com --site mysite
 
-# 2. Synthesize — 从探索成果物生成 evaluate-based YAML 适配器
+# 2. Synthesize — 从探索成果物生成 evaluate-based TS 适配器
 opencli synthesize mysite
 
 # 3. Generate — 一键完成：探索 → 合成 → 注册

package/dist/clis/_shared/common.d.ts

@@ -6,3 +6,6 @@
  * Matches the signature of lodash.clamp and Rust's clamp.
  */
 export declare function clamp(value: number, min: number, max: number): number;
+export declare function clampInt(raw: unknown, fallback: number, min: number, max: number): number;
+export declare function normalizeNumericId(value: unknown, label: string, example: string): string;
+export declare function requireNonEmptyQuery(value: unknown, label?: string): string;

package/dist/clis/_shared/common.js

@@ -1,6 +1,7 @@
 /**
  * Shared utilities for CLI adapters.
  */
+import { ArgumentError } from '@jackwener/opencli/errors';
 /**
  * Clamp a numeric value to [min, max].
  * Matches the signature of lodash.clamp and Rust's clamp.
@@ -8,3 +9,24 @@
 export function clamp(value, min, max) {
     return Math.max(min, Math.min(value, max));
 }
+export function clampInt(raw, fallback, min, max) {
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed)) {
+        return fallback;
+    }
+    return clamp(Math.floor(parsed), min, max);
+}
+export function normalizeNumericId(value, label, example) {
+    const normalized = String(value ?? '').trim();
+    if (!/^\d+$/.test(normalized)) {
+        throw new ArgumentError(`${label} must be a numeric ID`, `Pass a numeric ${label}, for example: ${example}`);
+    }
+    return normalized;
+}
+export function requireNonEmptyQuery(value, label = 'query') {
+    const normalized = String(value ?? '').trim();
+    if (!normalized) {
+        throw new ArgumentError(`${label} cannot be empty`);
+    }
+    return normalized;
+}

package/dist/clis/bilibili/hot.js

@@ -0,0 +1,35 @@
+import { cli } from '@jackwener/opencli/registry';
+cli({
+    site: 'bilibili',
+    name: 'hot',
+    description: 'B站热门视频',
+    domain: 'www.bilibili.com',
+    args: [
+        { name: 'limit', type: 'int', default: 20, help: 'Number of videos' },
+    ],
+    columns: ['rank', 'title', 'author', 'play', 'danmaku'],
+    pipeline: [
+        { navigate: 'https://www.bilibili.com' },
+        { evaluate: `(async () => {
+  const res = await fetch('https://api.bilibili.com/x/web-interface/popular?ps=\${{ args.limit }}&pn=1', {
+    credentials: 'include'
+  });
+  const data = await res.json();
+  return (data?.data?.list || []).map((item) => ({
+    title: item.title,
+    author: item.owner?.name,
+    play: item.stat?.view,
+    danmaku: item.stat?.danmaku,
+  }));
+})()
+` },
+        { map: {
+                rank: '${{ index + 1 }}',
+                title: '${{ item.title }}',
+                author: '${{ item.author }}',
+                play: '${{ item.play }}',
+                danmaku: '${{ item.danmaku }}',
+            } },
+        { limit: '${{ args.limit }}' },
+    ],
+});

package/dist/clis/bluesky/feeds.d.ts

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