@jackwener/opencli 0.1.0 → 0.1.2

package/SKILL.md

@@ -1,47 +1,47 @@
 ---
 name: opencli
-description: "OpenCLI — Make any website your CLI. Zero setup, AI-powered. Turn any website into CLI commands via Chrome browser."
+description: "OpenCLI — Make any website your CLI. Zero risk, AI-powered, reuse Chrome login."
 version: 0.1.0
 author: jackwener
-tags: [cli, browser, web, mcp, playwright, bilibili, zhihu, twitter, github, v2ex, hackernews, 哔哩哔哩, 知乎, AI, agent]
+tags: [cli, browser, web, mcp, playwright, bilibili, zhihu, twitter, github, v2ex, hackernews, reddit, xiaohongshu, AI, agent]
 ---
 
 # OpenCLI
 
-> Make any website your CLI. 操控 Chrome 无风控风险，复用登录，CLI 化全部网站。
+> Make any website your CLI. Reuse Chrome login, zero risk, AI-powered discovery.
 
-## 安装
+## Install & Run
 
 ```bash
-cd ~/code/ai-native-cli
-npm install
-```
-
-## 使用方式
+# npm global install (recommended)
+npm install -g @jackwener/opencli
+opencli <command>
 
-```bash
-# 通过 npx 运行（推荐）
+# Or from source
+cd ~/code/opencli && npm install
 npx tsx src/main.ts <command>
 
-# 或者构建后运行
-npm run build && node dist/main.js <command>
+# Update to latest
+npm update -g @jackwener/opencli
 ```
 
-## 前置要求
+## Prerequisites
 
-浏览器命令需要：
-1. Chrome 浏览器正在运行
-2. 安装 [Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm) 扩展
-3. 点击扩展图标批准连接
+Browser commands require:
+1. Chrome browser running **(logged into target sites)**
+2. [Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm) extension
+3. Configure `PLAYWRIGHT_MCP_EXTENSION_TOKEN` (from extension settings) in your MCP config
 
-公共 API 命令（hackernews、github search）无需浏览器。
+> **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.
 
-### 数据查询
+## Commands Reference
+
+### Data Commands
 
 ```bash
-# Bilibili
+# Bilibili (browser)
 opencli bilibili hot --limit 10          # B站热门视频
 opencli bilibili search --keyword "rust"  # 搜索视频
 opencli bilibili me                       # 我的信息
@@ -50,70 +50,115 @@ opencli bilibili history --limit 20       # 观看历史
 opencli bilibili feed --limit 10          # 动态时间线
 opencli bilibili user-videos --uid 12345  # 用户投稿
 
-# 知乎
+# 知乎 (browser)
 opencli zhihu hot --limit 10             # 知乎热榜
 opencli zhihu search --keyword "AI"      # 搜索
+opencli zhihu question --id 34816524     # 问题详情和回答
+
+# 小红书 (browser)
+opencli xiaohongshu search --keyword "美食"  # 搜索笔记
+opencli xiaohongshu notifications             # 通知（mentions/likes/connections）
+opencli xiaohongshu feed --limit 10           # 推荐 Feed
 
-# GitHub
+# GitHub (trending=browser, search=public)
 opencli github trending --limit 10       # GitHub Trending
-opencli github search --keyword "cli"    # 搜索仓库（无需浏览器）
+opencli github search --keyword "cli"    # 搜索仓库
 
-# Twitter/X
+# Twitter/X (browser)
 opencli twitter trending --limit 10      # 热门话题
 
-# V2EX
+# Reddit (browser)
+opencli reddit hot --limit 10            # 热门帖子
+opencli reddit hot --subreddit programming  # 指定子版块
+
+# V2EX (public)
 opencli v2ex hot --limit 10              # 热门话题
 opencli v2ex latest --limit 10           # 最新话题
+opencli v2ex topic --id 1024             # 主题详情
+
+# Hacker News (public)
+opencli hackernews top --limit 10        # Top stories
+
+# BBC (public)
+opencli bbc news --limit 10             # BBC News RSS headlines
+
+# 微博 (browser)
+opencli weibo hot --limit 10            # 微博热搜
+
+# BOSS直聘 (browser)
+opencli boss search --query "AI agent"  # 搜索职位
 
-# Hacker News
-opencli hackernews top --limit 10        # 热门故事（无需浏览器）
+# YouTube (browser)
+opencli youtube search --query "rust"   # 搜索视频
+
+# Yahoo Finance (browser)
+opencli yahoo-finance quote --symbol AAPL  # 股票行情
+
+# Reuters (browser)
+opencli reuters search --query "AI"     # 路透社搜索
+
+# 什么值得买 (browser)
+opencli smzdm search --keyword "耳机"    # 搜索好价
+
+# 携程 (browser)
+opencli ctrip search --query "三亚"      # 搜索目的地
 ```
 
-### 管理命令
+### Management Commands
 
 ```bash
-opencli list                # 列出所有可用命令
-opencli list --json         # JSON 格式输出
-opencli validate            # 验证所有 CLI 定义
-opencli validate bilibili   # 验证指定站点
+opencli list                # List all commands
+opencli list --json         # JSON output
+opencli validate            # Validate all CLI definitions
+opencli validate bilibili   # Validate specific site
 ```
 
-### AI 工作流（为 AI Agent 设计）
+### AI Agent Workflow
 
 ```bash
-opencli explore <url>                 # 探索网站，生成 API 发现成果物
-opencli synthesize <site>             # 从探索成果物合成候选 CLI
-opencli generate <url> --goal "hot"   # 一键：探索 → 合成 → 注册
-opencli verify <site/name> --smoke    # 验证 + Smoke 测试
+# Deep Explore: network intercept → response analysis → capability inference
+opencli explore <url> --site <name>
+
+# Synthesize: generate evaluate-based YAML pipelines from explore artifacts
+opencli synthesize <site>
+
+# Generate: one-shot explore → synthesize → register
+opencli generate <url> --goal "hot"
+
+# Strategy Cascade: auto-probe PUBLIC → COOKIE → HEADER
+opencli cascade <api-url>
+
+# Verify: smoke-test a generated adapter
+opencli verify <site/name> --smoke
 ```
 
-## 输出格式
+## Output Formats
 
-所有命令支持 `--format` / `-f` 选项：
+All commands support `--format` / `-f`:
 
 ```bash
-opencli bilibili hot -f table   # 默认表格
-opencli bilibili hot -f json    # JSON
+opencli bilibili hot -f table   # Default: rich table
+opencli bilibili hot -f json    # JSON (pipe to jq, feed to AI agent)
 opencli bilibili hot -f md      # Markdown
 opencli bilibili hot -f csv     # CSV
 ```
 
-## 调试
+## Verbose Mode
 
 ```bash
-opencli bilibili hot -v         # 显示 pipeline 每步详情
+opencli bilibili hot -v         # Show each pipeline step and data flow
 ```
 
-## 创建新的 CLI 适配器
+## Creating Adapters
 
-### YAML 方式（声明式，推荐）
+### YAML Pipeline (declarative, recommended)
 
-在 `src/clis/<site>/<name>.yaml` 创建文件：
+Create `src/clis/<site>/<name>.yaml`:
 
 ```yaml
 site: mysite
 name: hot
-description: Hot topics on mysite
+description: Hot topics
 domain: www.mysite.com
 strategy: cookie        # public | cookie | header | intercept | ui
 browser: true
@@ -130,11 +175,13 @@ pipeline:
   - evaluate: |
       (async () => {
         const res = await fetch('/api/hot', { credentials: 'include' });
-        return await res.json();
+        const d = await res.json();
+        return d.data.items.map(item => ({
+          title: item.title,
+          score: item.score,
+        }));
       })()
 
-  - select: data.items
-
   - map:
       rank: ${{ index + 1 }}
       title: ${{ item.title }}
@@ -145,9 +192,24 @@ pipeline:
 columns: [rank, title, score]
 ```
 
-### TypeScript 方式（编程式，更灵活）
+For public APIs (no browser):
+
+```yaml
+strategy: public
+browser: false
+
+pipeline:
+  - fetch:
+      url: https://api.example.com/hot.json
+  - select: data.items
+  - map:
+      title: ${{ item.title }}
+  - limit: ${{ args.limit }}
+```
 
-在 `src/clis/<site>/<name>.ts` 创建并在 `clis/index.ts` 中 import：
+### TypeScript Adapter (programmatic)
+
+Create `src/clis/<site>/<name>.ts` and import in `clis/index.ts`:
 
 ```typescript
 import { cli, Strategy } from '../../registry.js';
@@ -159,72 +221,86 @@ cli({
   args: [{ name: 'keyword', required: true }],
   columns: ['rank', 'title', 'url'],
   func: async (page, kwargs) => {
+    await page.goto('https://www.mysite.com');
     const data = await page.evaluate(`
-      async () => {
-        const res = await fetch('/api/search?q=${kwargs.keyword}', { credentials: 'include' });
+      (async () => {
+        const res = await fetch('/api/search?q=${kwargs.keyword}', {
+          credentials: 'include'
+        });
         return await res.json();
-      }
+      })()
     `);
     return data.items.map((item, i) => ({
-      rank: i + 1,
-      title: item.title,
-      url: item.url,
+      rank: i + 1, title: item.title, url: item.url,
     }));
   },
 });
 ```
 
-## Pipeline 步骤参考
-
-| 步骤 | 说明 | 示例 |
-|------|------|------|
-| `navigate` | 导航到 URL | `navigate: https://example.com` |
-| `fetch` | HTTP 请求（使用浏览器 cookie） | `fetch: { url: "...", params: { q: "${{ args.keyword }}" } }` |
-| `evaluate` | 执行 JavaScript | `evaluate: \| (async () => { ... })()` |
-| `select` | 选取 JSON 路径 | `select: data.items` |
-| `map` | 映射字段 | `map: { title: "${{ item.title }}" }` |
-| `filter` | 过滤 | `filter: item.score > 100` |
-| `sort` | 排序 | `sort: { by: score, order: desc }` |
-| `limit` | 限制数量 | `limit: ${{ args.limit }}` |
-| `snapshot` | 获取页面快照 | `snapshot: { interactive: true }` |
-| `click` | 点击元素 | `click: ${{ ref }}` |
-| `type` | 输入文本 | `type: { ref: "@1", text: "hello" }` |
-| `wait` | 等待 | `wait: 2` 或 `wait: { text: "loaded" }` |
-| `press` | 按键 | `press: Enter` |
-
-## 模板语法
-
-使用 `${{ expression }}` 进行模板替换：
+**When to use TS**: XHR interception (小红书), cookie extraction (Twitter ct0), Wbi signing (Bilibili), auto-pagination, complex data transforms.
+
+## Pipeline Steps
+
+| Step | Description | Example |
+|------|-------------|---------|
+| `navigate` | Go to URL | `navigate: https://example.com` |
+| `fetch` | HTTP request (browser cookies) | `fetch: { url: "...", params: { q: "..." } }` |
+| `evaluate` | Run JavaScript in page | `evaluate: \| (async () => { ... })()` |
+| `select` | Extract JSON path | `select: data.items` |
+| `map` | Map fields | `map: { title: "${{ item.title }}" }` |
+| `filter` | Filter items | `filter: item.score > 100` |
+| `sort` | Sort items | `sort: { by: score, order: desc }` |
+| `limit` | Cap result count | `limit: ${{ args.limit }}` |
+| `intercept` | Declarative XHR capture | `intercept: { trigger: "navigate:...", capture: "api/hot" }` |
+| `tap` | Store action + XHR capture | `tap: { store: "feed", action: "fetchFeeds", capture: "homefeed" }` |
+| `snapshot` | Page accessibility tree | `snapshot: { interactive: true }` |
+| `click` | Click element | `click: ${{ ref }}` |
+| `type` | Type text | `type: { ref: "@1", text: "hello" }` |
+| `wait` | Wait for time/text | `wait: 2` or `wait: { text: "loaded" }` |
+| `press` | Press key | `press: Enter` |
+
+## Template Syntax
 
 ```yaml
-# 引用参数
+# Arguments with defaults
 ${{ args.keyword }}
 ${{ args.limit | default(20) }}
 
-# 引用当前 item（在 map/filter 中）
+# Current item (in map/filter)
 ${{ item.title }}
 ${{ item.data.nested.field }}
 
-# 索引（从 0 开始）
+# Index (0-based)
 ${{ index }}
 ${{ index + 1 }}
 ```
 
-## 环境变量
-
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `OPENCLI_BROWSER_CONNECT_TIMEOUT` | 30 | 浏览器连接超时（秒） |
-| `OPENCLI_BROWSER_COMMAND_TIMEOUT` | 45 | 命令执行超时（秒） |
-| `OPENCLI_BROWSER_EXPLORE_TIMEOUT` | 120 | Explore 超时（秒） |
-| `OPENCLI_EXTENSION_LOCK_TIMEOUT` | 120 | 扩展锁超时（秒） |
-| `PLAYWRIGHT_MCP_EXTENSION_TOKEN` | — | 自动批准扩展连接 |
-
-## 错误排查
-
-| 错误 | 解决方案 |
-|------|----------|
-| `npx not found` | 安装 Node.js: `brew install node` |
-| `Timed out connecting to browser` | 1) 确认 Chrome 已打开 2) 安装 Playwright MCP Bridge 扩展 3) 点击扩展图标批准 |
-| `Extension lock timed out` | 等待其他 opencli 命令完成，浏览器命令需串行运行 |
-| `Request timed out` | 增大 `OPENCLI_BROWSER_COMMAND_TIMEOUT` 或检查网络 |
+## 5-Tier Authentication Strategy
+
+| Tier | Name | Method | Example |
+|------|------|--------|---------|
+| 1 | `public` | No auth, Node.js fetch | Hacker News, V2EX |
+| 2 | `cookie` | Browser fetch with `credentials: include` | Bilibili, Zhihu |
+| 3 | `header` | Custom headers (ct0, Bearer) | Twitter GraphQL |
+| 4 | `intercept` | XHR interception + store mutation | 小红书 Pinia |
+| 5 | `ui` | Full UI automation (click/type/scroll) | Last resort |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENCLI_BROWSER_CONNECT_TIMEOUT` | 30 | Browser connection timeout (sec) |
+| `OPENCLI_BROWSER_COMMAND_TIMEOUT` | 45 | Command execution timeout (sec) |
+| `OPENCLI_BROWSER_EXPLORE_TIMEOUT` | 120 | Explore timeout (sec) |
+| `OPENCLI_EXTENSION_LOCK_TIMEOUT` | 120 | Extension lock timeout (sec) |
+| `PLAYWRIGHT_MCP_EXTENSION_TOKEN` | — | Auto-approve extension connection |
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| `npx not found` | Install Node.js: `brew install node` |
+| `Timed out connecting to browser` | 1) Chrome must be open 2) Install MCP Bridge extension 3) Click to approve |
+| `Extension lock timed out` | Another opencli command is running; browser commands run serially |
+| `Target page context` error | Add `navigate:` step before `evaluate:` in YAML |
+| Empty table data | Check if evaluate returns JSON string (MCP parsing) or data path is wrong |

package/dist/bilibili.d.ts

@@ -1,13 +1,14 @@
 /**
  * Bilibili shared helpers: WBI signing, authenticated fetch, nav data, UID resolution.
  */
+import type { IPage } from './types.js';
 export declare function stripHtml(s: string): string;
 export declare function payloadData(payload: any): any;
-export declare function wbiSign(page: any, params: Record<string, any>): Promise<Record<string, string>>;
-export declare function apiGet(page: any, path: string, opts?: {
+export declare function wbiSign(page: IPage, params: Record<string, any>): Promise<Record<string, string>>;
+export declare function apiGet(page: IPage, path: string, opts?: {
     params?: Record<string, any>;
     signed?: boolean;
 }): Promise<any>;
-export declare function fetchJson(page: any, url: string): Promise<any>;
-export declare function getSelfUid(page: any): Promise<string>;
-export declare function resolveUid(page: any, input: string): Promise<string>;
+export declare function fetchJson(page: IPage, url: string): Promise<any>;
+export declare function getSelfUid(page: IPage): Promise<string>;
+export declare function resolveUid(page: IPage, input: string): Promise<string>;

package/dist/browser.d.ts

@@ -2,10 +2,11 @@
  * Browser interaction via Playwright MCP Bridge extension.
  * Connects to an existing Chrome browser through the extension's stdio JSON-RPC.
  */
+import type { IPage } from './types.js';
 /**
  * Page abstraction wrapping JSON-RPC calls to Playwright MCP.
  */
-export declare class Page {
+export declare class Page implements IPage {
     private _send;
     private _recv;
     constructor(_send: (msg: string) => void, _recv: () => Promise<any>);
@@ -39,6 +40,7 @@ export declare class PlaywrightMCP {
     private _waiters;
     private _lockAcquired;
     private _initialTabCount;
+    private _page;
     connect(opts?: {
         timeout?: number;
     }): Promise<Page>;

package/dist/browser.js

@@ -8,6 +8,14 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { formatSnapshot } from './snapshotFormatter.js';
+// Read version from package.json (single source of truth)
+const __browser_dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_VERSION = (() => { try {
+    return JSON.parse(fs.readFileSync(path.resolve(__browser_dirname, '..', 'package.json'), 'utf-8')).version;
+}
+catch {
+    return '0.0.0';
+} })();
 const EXTENSION_LOCK_TIMEOUT = parseInt(process.env.OPENCLI_EXTENSION_LOCK_TIMEOUT ?? '120', 10);
 const EXTENSION_LOCK_POLL = parseInt(process.env.OPENCLI_EXTENSION_LOCK_POLL_INTERVAL ?? '1', 10);
 const CONNECT_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_CONNECT_TIMEOUT ?? '30', 10);
@@ -37,7 +45,18 @@ export class Page {
         if (result?.content) {
             const textParts = result.content.filter((c) => c.type === 'text');
             if (textParts.length === 1) {
-                const text = textParts[0].text;
+                let text = textParts[0].text;
+                // MCP browser_evaluate returns: "[JSON]\n### Ran Playwright code\n```js\n...\n```"
+                // Strip the "### Ran Playwright code" suffix to get clean JSON
+                const codeMarker = text.indexOf('### Ran Playwright code');
+                if (codeMarker !== -1) {
+                    text = text.slice(0, codeMarker).trim();
+                }
+                // Also handle "### Result\n[JSON]" format (some MCP versions)
+                const resultMarker = text.indexOf('### Result\n');
+                if (resultMarker !== -1) {
+                    text = text.slice(resultMarker + '### Result\n'.length).trim();
+                }
                 try {
                     return JSON.parse(text);
                 }
@@ -106,6 +125,7 @@ export class PlaywrightMCP {
     _waiters = [];
     _lockAcquired = false;
     _initialTabCount = 0;
+    _page = null;
     async connect(opts = {}) {
         await this._acquireLock();
         const timeout = opts.timeout ?? CONNECT_TIMEOUT;
@@ -124,6 +144,7 @@ export class PlaywrightMCP {
                 this._proc.stdout.setMaxListeners(20);
             const page = new Page((msg) => { if (this._proc?.stdin?.writable)
                 this._proc.stdin.write(msg); }, () => new Promise((res) => { this._waiters.push(res); }));
+            this._page = page;
             this._proc.stdout?.on('data', (chunk) => {
                 this._buffer += chunk.toString();
                 const lines = this._buffer.split('\n');
@@ -146,7 +167,7 @@ export class PlaywrightMCP {
             const initMsg = jsonRpcRequest('initialize', {
                 protocolVersion: '2024-11-05',
                 capabilities: {},
-                clientInfo: { name: 'opencli', version: '0.1.0' },
+                clientInfo: { name: 'opencli', version: PKG_VERSION },
             });
             this._proc.stdin?.write(initMsg);
             // Wait for initialize response, then send initialized notification
@@ -174,12 +195,33 @@ export class PlaywrightMCP {
     }
     async close() {
         try {
+            // Close tabs opened during this session (site tabs + extension tabs)
+            if (this._page && this._proc && !this._proc.killed) {
+                try {
+                    const tabs = await this._page.tabs();
+                    const tabStr = typeof tabs === 'string' ? tabs : JSON.stringify(tabs);
+                    const allTabs = tabStr.match(/Tab (\d+)/g) || [];
+                    const currentTabCount = allTabs.length;
+                    // Close tabs in reverse order to avoid index shifting issues
+                    // Keep the original tabs that existed before the command started
+                    if (currentTabCount > this._initialTabCount && this._initialTabCount > 0) {
+                        for (let i = currentTabCount - 1; i >= this._initialTabCount; i--) {
+                            try {
+                                await this._page.closeTab(i);
+                            }
+                            catch { }
+                        }
+                    }
+                }
+                catch { }
+            }
             if (this._proc && !this._proc.killed) {
                 this._proc.kill('SIGTERM');
                 await new Promise((res) => { this._proc?.on('exit', () => res()); setTimeout(res, 3000); });
             }
         }
         finally {
+            this._page = null;
             this._releaseLock();
         }
     }

package/dist/cascade.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Strategy Cascade: automatic strategy downgrade chain.
+ *
+ * Probes an API endpoint starting from the simplest strategy (PUBLIC)
+ * and automatically downgrades through the strategy tiers until one works:
+ *
+ *   PUBLIC → COOKIE → HEADER → INTERCEPT → UI
+ *
+ * This eliminates the need for manual strategy selection — the system
+ * automatically finds the minimum-privilege strategy that works.
+ */
+import { Strategy } from './registry.js';
+import type { IPage } from './types.js';
+interface ProbeResult {
+    strategy: Strategy;
+    success: boolean;
+    statusCode?: number;
+    hasData?: boolean;
+    error?: string;
+    responsePreview?: string;
+}
+interface CascadeResult {
+    bestStrategy: Strategy;
+    probes: ProbeResult[];
+    confidence: number;
+}
+/**
+ * Probe an endpoint with a specific strategy.
+ * Returns whether the probe succeeded and basic response info.
+ */
+export declare function probeEndpoint(page: IPage, url: string, strategy: Strategy, opts?: {
+    timeout?: number;
+}): Promise<ProbeResult>;
+/**
+ * Run the cascade: try each strategy in order until one works.
+ * Returns the simplest working strategy.
+ */
+export declare function cascadeProbe(page: IPage, url: string, opts?: {
+    maxStrategy?: Strategy;
+    timeout?: number;
+}): Promise<CascadeResult>;
+/**
+ * Render cascade results for display.
+ */
+export declare function renderCascadeResult(result: CascadeResult): string;
+export {};