@nntoan/bb-browser 0.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+<div align="center">
+
+# bb-browser
+
+### BadBoy Browser
+
+**Your browser is the API. No keys. No bots. No scrapers.**
+
+[![npm](https://img.shields.io/npm/v/bb-browser?color=CB3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/bb-browser)
+[![Node.js](https://img.shields.io/badge/Node.js-18+-339933?logo=node.js&logoColor=white)](https://nodejs.org)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+[English](README.md) · [中文](README.zh-CN.md)
+
+</div>
+
+---
+
+You're already logged into Twitter, Reddit, YouTube, Zhihu, Bilibili, LinkedIn, GitHub — bb-browser lets AI agents **use that directly**.
+
+```bash
+bb-browser site twitter/search "AI agent"       # search tweets
+bb-browser site zhihu/hot                        # trending on Zhihu
+bb-browser site arxiv/search "transformer"       # search papers
+bb-browser site eastmoney/stock "茅台"            # real-time stock quote
+bb-browser site boss/search "AI engineer"        # search jobs
+bb-browser site wikipedia/summary "Python"       # Wikipedia summary
+bb-browser site youtube/transcript VIDEO_ID      # full transcript
+bb-browser site stackoverflow/search "async"     # search SO questions
+```
+
+**103 commands across 36 platforms.** All using your real browser's login state. [Full list →](https://github.com/epiral/bb-sites)
+
+## The idea
+
+The internet was built for browsers. AI agents have been trying to access it through APIs — but 99% of websites don't offer one.
+
+bb-browser flips this: **instead of forcing websites to provide machine interfaces, let machines use the human interface directly.** The adapter runs `eval` inside your browser tab, calls `fetch()` with your cookies, or invokes the page's own webpack modules. The website thinks it's you. Because it **is** you.
+
+| | Playwright / Selenium | Scraping libs | bb-browser |
+|---|---|---|---|
+| Browser | Headless, isolated | No browser | Your real Chrome |
+| Login state | None, must re-login | Cookie extraction | Already there |
+| Anti-bot | Detected easily | Cat-and-mouse | Invisible — it IS the user |
+| Complex auth | Can't replicate | Reverse engineer | Page handles it itself |
+
+## Quick Start
+
+### Install
+
+```bash
+npm install -g bb-browser
+```
+
+### Use
+
+```bash
+bb-browser site update        # pull community adapters
+bb-browser site recommend     # see which adapters match your browsing habits
+bb-browser site zhihu/hot     # go
+```
+
+### OpenClaw (no extension needed)
+
+If you use [OpenClaw](https://openclaw.ai), bb-browser runs directly through OpenClaw's built-in browser — no Chrome extension or daemon required:
+
+```bash
+bb-browser site reddit/hot --openclaw
+bb-browser site xueqiu/hot-stock 5 --openclaw --jq '.items[] | {name, changePercent}'
+```
+
+Skill on ClawHub: [bb-browser-openclaw](https://clawhub.ai/yan5xu/bb-browser)
+
+### Chrome Extension (standalone mode)
+
+For use without OpenClaw (Claude Code MCP, standalone CLI):
+
+1. Download from [Releases](https://github.com/epiral/bb-browser/releases/latest)
+2. Unzip → `chrome://extensions/` → Developer Mode → Load unpacked
+
+### MCP (Claude Code / Cursor)
+
+```json
+{
+  "mcpServers": {
+    "bb-browser": {
+      "command": "npx",
+      "args": ["-y", "bb-browser", "--mcp"]
+    }
+  }
+}
+```
+
+## 36 platforms, 103 commands
+
+Community-driven via [bb-sites](https://github.com/epiral/bb-sites). One JS file per command.
+
+| Category | Platforms | Commands |
+|----------|-----------|----------|
+| **Search** | Google, Baidu, Bing, DuckDuckGo, Sogou WeChat | search |
+| **Social** | Twitter/X, Reddit, Weibo, Xiaohongshu, Jike, LinkedIn, Hupu | search, feed, thread, user, notifications, hot |
+| **News** | BBC, Reuters, 36kr, Toutiao, Eastmoney | headlines, search, newsflash, hot |
+| **Dev** | GitHub, StackOverflow, HackerNews, CSDN, cnblogs, V2EX, Dev.to, npm, PyPI, arXiv | search, issues, repo, top, thread, package |
+| **Video** | YouTube, Bilibili | search, video, transcript, popular, comments, feed |
+| **Entertainment** | Douban, IMDb, Genius, Qidian | movie, search, top250 |
+| **Finance** | Xueqiu, Eastmoney, Yahoo Finance | stock, hot stocks, feed, watchlist, search |
+| **Jobs** | BOSS Zhipin, LinkedIn | search, detail, profile |
+| **Knowledge** | Wikipedia, Zhihu, Open Library | search, summary, hot, question |
+| **Shopping** | SMZDM | search deals |
+| **Tools** | Youdao, GSMArena, Product Hunt, Ctrip | translate, phone specs, trending products |
+
+## 10 minutes to add any website
+
+```bash
+bb-browser guide    # full tutorial
+```
+
+Tell your AI agent: *"turn XX website into a CLI"*. It reads the guide, reverse-engineers the API with `network --with-body`, writes the adapter, tests it, and submits a PR. All autonomously.
+
+Three tiers of adapter complexity:
+
+| Tier | Auth method | Example | Time |
+|------|-------------|---------|------|
+| **1** | Cookie (fetch directly) | Reddit, GitHub, V2EX | ~1 min |
+| **2** | Bearer + CSRF token | Twitter, Zhihu | ~3 min |
+| **3** | Webpack injection / Pinia store | Twitter search, Xiaohongshu | ~10 min |
+
+We tested this: **20 AI agents ran in parallel, each independently reverse-engineered a website and produced a working adapter.** The marginal cost of adding a new website to the agent-accessible internet is approaching zero.
+
+## What this means for AI agents
+
+Without bb-browser, an AI agent's world is: **files + terminal + a few APIs with keys.**
+
+With bb-browser: **files + terminal + the entire internet.**
+
+An agent can now, in under a minute:
+
+```bash
+# Cross-platform research on any topic
+bb-browser site arxiv/search "retrieval augmented generation"
+bb-browser site twitter/search "RAG"
+bb-browser site github search rag-framework
+bb-browser site stackoverflow/search "RAG implementation"
+bb-browser site zhihu/search "RAG"
+bb-browser site 36kr/newsflash
+```
+
+Six platforms, six dimensions, structured JSON. Faster and broader than any human researcher.
+
+## Also a full browser automation tool
+
+```bash
+bb-browser open https://example.com
+bb-browser snapshot -i                # accessibility tree
+bb-browser click @3                   # click element
+bb-browser fill @5 "hello"            # fill input
+bb-browser eval "document.title"      # run JS
+bb-browser fetch URL --json           # authenticated fetch
+bb-browser network requests --with-body --json  # capture traffic
+bb-browser screenshot                 # take screenshot
+```
+
+All commands support `--json` output, `--jq <expr>` for inline filtering, and `--tab <id>` for concurrent multi-tab operations.
+
+```bash
+bb-browser site xueqiu/hot-stock 5 --jq '.items[] | {name, changePercent}'
+# {"name":"云天化","changePercent":"2.08%"}
+# {"name":"东芯股份","changePercent":"-7.60%"}
+
+bb-browser site info xueqiu/stock   # view adapter args, example, domain
+```
+
+## Daemon configuration
+
+The daemon binds to `localhost:19824` by default. You can customize the host with `--host`:
+
+```bash
+bb-browser daemon --host 127.0.0.1    # IPv4 only (fix macOS IPv6 issues)
+bb-browser daemon --host 0.0.0.0      # listen on all interfaces (for Tailscale / ZeroTier remote access)
+```
+
+## Architecture
+
+```
+AI Agent (Claude Code, Codex, Cursor, etc.)
+       │ CLI or MCP (stdio)
+       ▼
+bb-browser CLI ──HTTP──▶ Daemon ──SSE──▶ Chrome Extension
+                                              │
+                                              ▼ chrome.debugger (CDP)
+                                         Your Real Browser
+```
+
+## Fork sync strategy for English-localized forks
+
+If your fork keeps English runtime text while upstream still updates Chinese text, avoid direct long-lived manual edits during every sync.
+
+This repo includes an overlay-based approach:
+
+1. Merge upstream first.
+2. Re-apply English string overlay (`pnpm overlay:english`).
+3. Validate (`pnpm lint && pnpm test`).
+4. Push sync result.
+
+The overlay rules live in:
+- `tools/english-overlay/rules.json`
+- `tools/english-overlay/apply.mjs`
+
+For automation, use workflow:
+- `.github/workflows/sync-upstream-overlay.yml`
+
+This reduces merge conflicts because your localization is generated after merge, not hand-resolved in every conflicting hunk.
+
+Example conflict pattern and resolution:
+
+- Upstream changes:
+  - `"错误：缺少 URL 参数"` → `"错误：缺少 url 参数（必填）"`
+- Fork direct-edit approach:
+  - same line was changed to `"Error: missing URL argument"`
+  - next upstream merge can conflict on this hunk.
+- Overlay approach:
+  1. merge upstream Chinese changes first
+  2. run `pnpm overlay:english`
+  3. overlay rewrites to your English form again
+
+This keeps sync friction low and avoids repeated manual conflict resolution on translated strings.
+
+## Publish release to your own npm registry (forks)
+
+Workflow `.github/workflows/publish.yml` now supports custom registry publish.
+
+Manual run (`workflow_dispatch`) inputs:
+- `tag_name` (required)
+- `registry_url` (default: `https://registry.npmjs.org`)
+- `dist_tag` (default: `latest`)
+
+Set one of these secrets in your fork:
+- `NPM_TOKEN` (preferred)
+- or `NODE_AUTH_TOKEN`
+
+Examples:
+- npmjs: `registry_url=https://registry.npmjs.org`
+- GitHub Packages: `registry_url=https://npm.pkg.github.com`
+
+If your registry requires scoped packages, update `name` in `package.json` (for example `@your-scope/bb-browser`) before publishing.
+
+## License
+
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,196 @@
+<div align="center">
+
+# bb-browser
+
+### 坏孩子浏览器 BadBoy Browser
+
+**你的浏览器就是 API。不需要密钥，不需要爬虫，不需要模拟。**
+
+[![npm](https://img.shields.io/npm/v/bb-browser?color=CB3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/bb-browser)
+[![Node.js](https://img.shields.io/badge/Node.js-18+-339933?logo=node.js&logoColor=white)](https://nodejs.org)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+[English](README.md) · [中文](README.zh-CN.md)
+
+</div>
+
+---
+
+你已经登录了微博、知乎、B站、小红书、Twitter、GitHub、LinkedIn — bb-browser 让 AI Agent **直接用你的登录态**。
+
+```bash
+bb-browser site twitter/search "AI agent"       # 搜索推文
+bb-browser site zhihu/hot                        # 知乎热榜
+bb-browser site arxiv/search "transformer"       # 搜论文
+bb-browser site eastmoney/stock "茅台"            # 实时股票行情
+bb-browser site boss/search "AI 工程师"           # 搜职位
+bb-browser site wikipedia/summary "Python"       # 维基百科摘要
+bb-browser site youtube/transcript VIDEO_ID      # YouTube 字幕全文
+bb-browser site stackoverflow/search "async"     # 搜 StackOverflow
+```
+
+**36 个平台，103 个命令，全部用你真实浏览器的登录态。** [完整列表 →](https://github.com/epiral/bb-sites)
+
+## 核心理念
+
+互联网是为浏览器构建的。AI Agent 一直试图通过 API 访问它 — 但 99% 的网站不提供 API。
+
+bb-browser 翻转了这个逻辑：**不是让网站适配机器，而是让机器使用人的界面。** adapter 在你的浏览器 tab 里跑 `eval`，用你的 Cookie 调 `fetch()`，或者直接调用页面的 webpack 模块。网站以为是你在操作。因为**就是你**。
+
+| | Playwright / Selenium | 爬虫库 | bb-browser |
+|---|---|---|---|
+| 浏览器 | 无头、隔离环境 | 没有浏览器 | 你的真实 Chrome |
+| 登录态 | 没有，要重新登录 | 偷 Cookie | 已经在了 |
+| 反爬检测 | 容易被识别 | 猫鼠游戏 | 无法检测 — 它就是用户 |
+| 复杂鉴权 | 无法复制 | 需要逆向 | 页面自己处理 |
+
+## 快速开始
+
+### 安装
+
+```bash
+npm install -g bb-browser
+```
+
+### 使用
+
+```bash
+bb-browser site update        # 拉取社区适配器
+bb-browser site recommend     # 看看哪些和你的浏览习惯匹配
+bb-browser site zhihu/hot     # 开搞
+```
+
+### OpenClaw（无需安装扩展）
+
+如果你使用 [OpenClaw](https://openclaw.ai)，bb-browser 可以直接通过 OpenClaw 内置浏览器运行，不需要额外安装 Chrome 扩展或 daemon：
+
+```bash
+bb-browser site reddit/hot --openclaw
+bb-browser site xueqiu/hot-stock 5 --openclaw --jq '.items[] | {name, changePercent}'
+```
+
+ClawHub Skill: [bb-browser-openclaw](https://clawhub.ai/yan5xu/bb-browser)
+
+### Chrome 扩展（独立模式）
+
+不使用 OpenClaw 时（Claude Code MCP、独立 CLI）需要安装扩展：
+
+1. 从 [Releases](https://github.com/epiral/bb-browser/releases/latest) 下载 zip
+2. 解压 → `chrome://extensions/` → 开发者模式 → 加载已解压的扩展程序
+
+### MCP 接入（Claude Code / Cursor）
+
+```json
+{
+  "mcpServers": {
+    "bb-browser": {
+      "command": "npx",
+      "args": ["-y", "bb-browser", "--mcp"]
+    }
+  }
+}
+```
+
+## 36 个平台，103 个命令
+
+社区驱动，通过 [bb-sites](https://github.com/epiral/bb-sites) 维护。每个命令一个 JS 文件。
+
+| 类别 | 平台 | 命令 |
+|------|------|------|
+| **搜索引擎** | Google、百度、Bing、DuckDuckGo、搜狗微信 | search |
+| **社交媒体** | Twitter/X、Reddit、微博、小红书、即刻、LinkedIn、虎扑 | search、feed、thread、user、notifications、hot |
+| **新闻资讯** | BBC、Reuters、36氪、今日头条、东方财富 | headlines、search、newsflash、hot |
+| **技术开发** | GitHub、StackOverflow、HackerNews、CSDN、博客园、V2EX、Dev.to、npm、PyPI、arXiv | search、issues、repo、top、thread、package |
+| **视频平台** | YouTube、B站 | search、video、transcript、popular、comments、feed |
+| **影音娱乐** | 豆瓣、IMDb、Genius、起点中文网 | movie、search、top250 |
+| **财经股票** | 雪球、东方财富、Yahoo Finance | stock、hot-stock、feed、watchlist、search |
+| **求职招聘** | BOSS直聘、LinkedIn | search、detail、profile |
+| **知识百科** | Wikipedia、知乎、Open Library | search、summary、hot、question |
+| **消费购物** | 什么值得买 | search |
+| **实用工具** | 有道翻译、GSMArena、Product Hunt、携程 | translate、手机参数、热门产品 |
+
+## 10 分钟，CLI 化任何网站
+
+```bash
+bb-browser guide    # 完整教程
+```
+
+跟你的 AI Agent 说：*「帮我把 XX 网站 CLI 化」*。它会读 guide，用 `network --with-body` 抓包逆向，写 adapter，测试，然后提 PR 到社区仓库。全程自动。
+
+三种 adapter 复杂度：
+
+| 层级 | 认证方式 | 代表 | 耗时 |
+|------|----------|------|------|
+| **Tier 1** | Cookie（直接 fetch） | Reddit、GitHub、V2EX | ~1 分钟 |
+| **Tier 2** | Bearer + CSRF token | Twitter、知乎 | ~3 分钟 |
+| **Tier 3** | Webpack 注入 / Pinia store | Twitter 搜索、小红书 | ~10 分钟 |
+
+实测：**20 个 AI Agent 并发运行，每个独立逆向一个网站并产出可用的 adapter。** 将一个新网站纳入 Agent 可访问范围的边际成本趋近于零。
+
+## 对 AI Agent 意味着什么
+
+没有 bb-browser，AI Agent 的世界是：**文件系统 + 终端 + 少数有 API key 的服务。**
+
+有了 bb-browser：**文件系统 + 终端 + 整个互联网。**
+
+一个 Agent 现在可以在一分钟内：
+
+```bash
+# 跨平台调研任何话题
+bb-browser site arxiv/search "retrieval augmented generation"
+bb-browser site twitter/search "RAG"
+bb-browser site github search rag-framework
+bb-browser site stackoverflow/search "RAG implementation"
+bb-browser site zhihu/search "RAG"
+bb-browser site 36kr/newsflash
+```
+
+六个平台，六个维度，结构化 JSON。比任何人类研究员都快、都广。
+
+## 同时也是完整的浏览器自动化工具
+
+```bash
+bb-browser open https://example.com
+bb-browser snapshot -i                # 可访问性树
+bb-browser click @3                   # 点击元素
+bb-browser fill @5 "hello"            # 填写输入框
+bb-browser eval "document.title"      # 执行 JS
+bb-browser fetch URL --json           # 带登录态的 fetch
+bb-browser network requests --with-body --json  # 抓包
+bb-browser screenshot                 # 截图
+```
+
+所有命令支持 `--json` 输出、`--jq <expr>` 内联过滤、和 `--tab <id>` 多标签页并发操作。
+
+```bash
+bb-browser site xueqiu/hot-stock 5 --jq '.items[] | {name, changePercent}'
+# {"name":"云天化","changePercent":"2.08%"}
+# {"name":"东芯股份","changePercent":"-7.60%"}
+
+bb-browser site info xueqiu/stock   # 查看 adapter 参数、示例、域名
+```
+
+## Daemon 配置
+
+Daemon 默认绑定 `localhost:19824`，可通过 `--host` 自定义监听地址：
+
+```bash
+bb-browser daemon --host 127.0.0.1    # 仅 IPv4（解决 macOS IPv6 问题）
+bb-browser daemon --host 0.0.0.0      # 监听所有网卡（用于 Tailscale / ZeroTier 跨机器访问）
+```
+
+## 架构
+
+```
+AI Agent (Claude Code, Codex, Cursor 等)
+       │ CLI 或 MCP (stdio)
+       ▼
+bb-browser CLI ──HTTP──▶ Daemon ──SSE──▶ Chrome 扩展
+                                              │
+                                              ▼ chrome.debugger (CDP)
+                                         你的真实浏览器
+```
+
+## 许可证
+
+[MIT](LICENSE)