@jackwener/opencli 0.1.0 → 0.1.1

package/README.md

@@ -1,66 +1,144 @@
 # OpenCLI
 
-> **Make any website your CLI.** 操控 Chrome 无风控风险，复用登录，CLI 化全部网站。
+> **Make any website your CLI.**  
+> Zero risk · Reuse Chrome login · AI-powered discovery
 
-OpenCLI 是一个 AI Native 的 CLI 工具，通过 Chrome 浏览器 + Playwright MCP Bridge 扩展，将任何网站变成命令行工具。
+[中文文档](./README.zh-CN.md)
 
-## ✨ 特性
+[![npm](https://img.shields.io/npm/v/@jackwener/opencli)](https://www.npmjs.com/package/@jackwener/opencli)
 
-- 🌐 **CLI 化全部网站** — 支持 Bilibili、知乎、GitHub、Twitter、V2EX、Hacker News 等
-- 🔐 **零风控风险** — 复用 Chrome 已登录状态，无需存储密码
-- 🤖 **AI Native** — AI agent 可直接探索网站并自动生成新命令
-- 📝 **声明式 YAML** — 用 YAML 定义 pipeline，无需写代码
-- 🔌 **TypeScript 扩展** — 复杂场景用 TS 编写适配器
+OpenCLI turns any website into a command-line tool by bridging your Chrome browser through [Playwright MCP](https://github.com/nichochar/playwright-mcp). No passwords stored, no tokens leaked — it just rides your existing browser session.
 
-## 🚀 快速开始
+## ✨ Highlights
+
+- 🌐 **25+ commands, 8 sites** — Bilibili, Zhihu, GitHub, Twitter/X, Reddit, V2EX, Xiaohongshu, Hacker News
+- 🔐 **Account-safe** — Reuses Chrome's logged-in state; your credentials never leave the browser
+- 🤖 **AI Agent ready** — `explore` discovers APIs, `synthesize` generates adapters, `cascade` finds auth strategies
+- 📝 **Declarative YAML** — Most adapters are ~30 lines of YAML pipeline
+- 🔌 **TypeScript escape hatch** — Complex adapters (XHR interception, GraphQL) in TS
+
+## 🚀 Quick Start
+
+### Install via npm (recommended)
+
+```bash
+npm install -g @jackwener/opencli
+```
+
+Then use directly:
 
 ```bash
-# 安装依赖
-cd ~/code/ai-native-cli && npm install
+opencli list                              # See all commands
+opencli hackernews top --limit 5          # Public API, no browser
+opencli bilibili hot --limit 5            # Browser command
+opencli zhihu hot -f json                 # JSON output
+```
 
-# 列出所有命令
+### Install from source
+
+```bash
+git clone git@github.com:jackwener/opencli.git
+cd opencli && npm install
 npx tsx src/main.ts list
+```
+
+### Update
 
-# 公共 API（无需浏览器）
-npx tsx src/main.ts hackernews top --limit 10
-npx tsx src/main.ts github search --keyword "typescript"
+```bash
+# npm global
+npm update -g @jackwener/opencli
+
+# Or reinstall to latest
+npm install -g @jackwener/opencli@latest
+```
 
-# 浏览器命令（需要 Chrome + Playwright MCP Bridge 扩展）
-npx tsx src/main.ts bilibili hot --limit 10
-npx tsx src/main.ts zhihu hot --limit 10
-npx tsx src/main.ts twitter trending --limit 10
+## 📋 Prerequisites
+
+Browser commands need:
+1. **Chrome** running **and logged into the target site** (e.g. bilibili.com, zhihu.com, xiaohongshu.com)
+2. **[Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm)** extension installed
+3. Configure `PLAYWRIGHT_MCP_EXTENSION_TOKEN` (from the extension settings page) in your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest", "--extension"],
+      "env": {
+        "PLAYWRIGHT_MCP_EXTENSION_TOKEN": "<your-token>"
+      }
+    }
+  }
+}
 ```
 
-## 📋 前置要求
+Public API commands (`hackernews`, `github search`, `v2ex`) need no browser at all.
 
-浏览器命令需要：
-1. Chrome 浏览器正在运行
-2. 安装 [Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm) 扩展
-3. 首次使用时点击扩展图标批准连接
+> **⚠️ Important**: Browser commands reuse your Chrome login session. You must be logged into the target website in Chrome before running commands. If you get empty data or errors, check your login status first.
 
-## 📦 内置命令
+## 📦 Built-in Commands
 
-| 站点 | 命令 | 说明 | 模式 |
-|------|------|------|------|
-| bilibili | hot, search, me, favorite, history, feed, user-videos | 热门 / 搜索 / 个人 / 收藏 / 历史 / 动态 / 投稿 | 🔐 浏览器 |
-| zhihu | hot, search | 热榜 / 搜索 | 🔐 浏览器 |
-| github | trending, search | Trending / 搜索 | 🔐 / 🌐 公共 |
-| twitter | trending | 热门话题 | 🔐 浏览器 |
-| v2ex | hot, latest | 热门 / 最新 | 🔐 浏览器 |
-| hackernews | top | 热门故事 | 🌐 公共 API |
+| Site | Commands | Mode |
+|------|----------|------|
+| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `user-videos` | 🔐 Browser |
+| **zhihu** | `hot` `search` `question` | 🔐 Browser |
+| **xiaohongshu** | `search` `notifications` `feed` | 🔐 Browser |
+| **twitter** | `trending` | 🔐 Browser |
+| **reddit** | `hot` | 🔐 Browser |
+| **github** | `trending` `search` | 🔐 / 🌐 |
+| **v2ex** | `hot` `latest` `topic` | 🌐 Public |
+| **hackernews** | `top` | 🌐 Public |
 
-## 🎨 输出格式
+## 🎨 Output Formats
 
 ```bash
-opencli bilibili hot -f table   # 默认表格
-opencli bilibili hot -f json    # JSON（适合管道和 AI agent）
+opencli bilibili hot -f table   # Default: rich table
+opencli bilibili hot -f json    # JSON (pipe to jq, feed to AI)
 opencli bilibili hot -f md      # Markdown
 opencli bilibili hot -f csv     # CSV
+opencli bilibili hot -v         # Verbose: show pipeline steps
 ```
 
-## 🔧 创建新命令
+## 🧠 AI Agent Workflow
+
+```bash
+# 1. Deep Explore — discover APIs, infer capabilities, detect framework
+opencli explore https://example.com --site mysite
+
+# 2. Synthesize — generate YAML adapters from explore artifacts
+opencli synthesize mysite
+
+# 3. Generate — one-shot: explore → synthesize → register
+opencli generate https://example.com --goal "hot"
+
+# 4. Strategy Cascade — auto-probe: PUBLIC → COOKIE → HEADER
+opencli cascade https://api.example.com/data
+```
+
+Explore outputs to `.opencli/explore/<site>/`:
+- `manifest.json` — site metadata, framework detection
+- `endpoints.json` — scored API endpoints with response schemas
+- `capabilities.json` — inferred capabilities with confidence scores
+- `auth.json` — authentication strategy recommendations
+
+## 🔧 Create New Commands
+
+See **[SKILL.md](./SKILL.md)** for the full adapter guide (YAML pipeline + TypeScript).
+
+## Releasing New Versions
+
+```bash
+# Bump version
+npm version patch   # 0.1.0 → 0.1.1
+npm version minor   # 0.1.0 → 0.2.0
+npm version major   # 0.1.0 → 1.0.0
+
+# Push tag to trigger GitHub Actions auto-release
+git push --follow-tags
+```
 
-参考 [SKILL.md](./SKILL.md) 了解 YAML 和 TypeScript 两种方式创建新的 CLI 适配器。
+The CI will automatically build, create a GitHub release, and publish to npm.
 
 ## 📄 License
 

package/README.zh-CN.md

@@ -0,0 +1,143 @@
+# OpenCLI
+
+> **把任何网站变成你的命令行工具。**  
+> 零风控 · 复用 Chrome 登录 · AI 自动发现接口
+
+[English](./README.md)
+
+[![npm](https://img.shields.io/npm/v/@jackwener/opencli)](https://www.npmjs.com/package/@jackwener/opencli)
+
+OpenCLI 通过 Chrome 浏览器 + [Playwright MCP Bridge](https://github.com/nichochar/playwright-mcp) 扩展，将任何网站变成命令行工具。不存密码、不泄 token，直接复用浏览器已登录状态。
+
+## ✨ 亮点
+
+- 🌐 **25+ 命令，8 个站点** — B站、知乎、GitHub、Twitter/X、Reddit、V2EX、小红书、Hacker News
+- 🔐 **零风控** — 复用 Chrome 登录态，无需存储任何凭证
+- 🤖 **AI 原生** — `explore` 自动发现 API，`synthesize` 生成适配器，`cascade` 探测认证策略
+- 📝 **声明式 YAML** — 大部分适配器只需 ~30 行 YAML
+- 🔌 **TypeScript 扩展** — 复杂场景（XHR 拦截、GraphQL）可用 TS 编写
+
+## 🚀 快速开始
+
+### npm 全局安装（推荐）
+
+```bash
+npm install -g @jackwener/opencli
+```
+
+直接使用：
+
+```bash
+opencli list                              # 查看所有命令
+opencli hackernews top --limit 5          # 公共 API，无需浏览器
+opencli bilibili hot --limit 5            # 浏览器命令
+opencli zhihu hot -f json                 # JSON 输出
+```
+
+### 从源码安装
+
+```bash
+git clone git@github.com:jackwener/opencli.git
+cd opencli && npm install
+npx tsx src/main.ts list
+```
+
+### 更新
+
+```bash
+# npm 全局更新
+npm update -g @jackwener/opencli
+
+# 或直接安装最新版
+npm install -g @jackwener/opencli@latest
+```
+
+## 📋 前置要求
+
+浏览器命令需要：
+1. **Chrome** 浏览器正在运行，且**已登录目标网站**（如 bilibili.com、zhihu.com、xiaohongshu.com）
+2. 安装 **[Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm)** 扩展
+3. 在 MCP 配置中设置 `PLAYWRIGHT_MCP_EXTENSION_TOKEN`（从扩展设置页获取）：
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest", "--extension"],
+      "env": {
+        "PLAYWRIGHT_MCP_EXTENSION_TOKEN": "<your-token>"
+      }
+    }
+  }
+}
+```
+
+公共 API 命令（`hackernews`、`github search`、`v2ex`）无需浏览器。
+
+> **⚠️ 重要**：浏览器命令复用你的 Chrome 登录状态。运行命令前，你必须已在 Chrome 中登录目标网站。如果获取到空数据或报错，请先检查登录状态。
+
+## 📦 内置命令
+
+| 站点 | 命令 | 模式 |
+|------|------|------|
+| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `user-videos` | 🔐 浏览器 |
+| **zhihu** | `hot` `search` `question` | 🔐 浏览器 |
+| **xiaohongshu** | `search` `notifications` `feed` | 🔐 浏览器 |
+| **twitter** | `trending` | 🔐 浏览器 |
+| **reddit** | `hot` | 🔐 浏览器 |
+| **github** | `trending` `search` | 🔐 / 🌐 |
+| **v2ex** | `hot` `latest` `topic` | 🌐 公共 API |
+| **hackernews** | `top` | 🌐 公共 API |
+
+## 🎨 输出格式
+
+```bash
+opencli bilibili hot -f table   # 默认：表格
+opencli bilibili hot -f json    # JSON（可 pipe 给 jq 或 AI agent）
+opencli bilibili hot -f md      # Markdown
+opencli bilibili hot -f csv     # CSV
+opencli bilibili hot -v         # 详细模式：展示 pipeline 每步数据
+```
+
+## 🧠 AI Agent 工作流
+
+```bash
+# 1. Deep Explore — 网络拦截 → 响应分析 → 能力推理 → 框架检测
+opencli explore https://example.com --site mysite
+
+# 2. Synthesize — 从探索成果物生成 evaluate-based YAML 适配器
+opencli synthesize mysite
+
+# 3. Generate — 一键完成：探索 → 合成 → 注册
+opencli generate https://example.com --goal "hot"
+
+# 4. Strategy Cascade — 自动降级探测：PUBLIC → COOKIE → HEADER
+opencli cascade https://api.example.com/data
+```
+
+探索结果输出到 `.opencli/explore/<site>/`：
+- `manifest.json` — 站点元数据、框架检测结果
+- `endpoints.json` — 评分排序的 API 端点，含响应 schema
+- `capabilities.json` — 推理出的能力及置信度
+- `auth.json` — 认证策略建议
+
+## 🔧 创建新命令
+
+查看 **[SKILL.md](./SKILL.md)** 了解完整的适配器开发指南（YAML pipeline + TypeScript）。
+
+## 版本发布
+
+```bash
+# 升级版本号
+npm version patch   # 0.1.0 → 0.1.1
+npm version minor   # 0.1.0 → 0.2.0
+npm version major   # 0.1.0 → 1.0.0
+
+# 推送 tag，GitHub Actions 自动发 release 并发布到 npm
+git push --follow-tags
+```
+
+## 📄 License
+
+MIT