diff --git a/README.md b/README.md index efcfb4b..634485b 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,67 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/jackwener/OpenCLI) · [上游 README](https://github.com/jackwener/OpenCLI/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 + # OpenCLI -> **Convert any website into a CLI & run Browser Use on your logged-in Chrome.** -> Turn websites, browser sessions, Electron apps, and local tools into deterministic interfaces for humans and AI agents. -> Or run Browser Use against any page — navigate, fill forms, click, extract, automate. +> **把任意网站变成 CLI & 在你的登录态浏览器上跑 Browser Use。** +> 把网站、浏览器会话、Electron 应用和本地工具，统一变成适合人类与 AI Agent 使用的确定性接口。 +> 或者在任意页面上跑 Browser Use —— 导航、填表单、点击、抓取、自动化。 -[![中文文档](https://img.shields.io/badge/docs-%E4%B8%AD%E6%96%87-0F766E?style=flat-square)](./README.zh-CN.md) +[![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 gives you one surface for three different kinds of automation: +OpenCLI 可以用同一套 CLI 做三类事情： -- **Use built-in adapters** for sites like Bilibili, Zhihu, Xiaohongshu, Reddit, HackerNews, Twitter/X, and [many more](#built-in-commands). -- **Let AI Agents operate any website** — install the `opencli-browser` skill in your AI agent (Claude Code, Cursor, etc.), and it can navigate, click, type/fill, extract, and inspect any page through your logged-in browser via `opencli browser` primitives. -- **Write new adapters** end-to-end with `opencli browser` + the `opencli-adapter-author` skill, which guides from first recon through field decoding, code, and `opencli browser verify`. +- **直接使用现成适配器**：B站、知乎、小红书、Twitter/X、Reddit、HackerNews 等 [100+ 站点](#内置命令) 开箱即用。 +- **让 AI Agent 操作任意网站**：在你的 AI Agent（Claude Code、Cursor 等）中安装 `opencli-browser` skill，Agent 就能用你的已登录浏览器导航、点击、输入/填充、提取任意网页内容。 +- **把新网站写成 CLI**：用 `opencli browser` 原语 + `opencli-adapter-author` skill，从站点侦察、API 发现、字段解码到 `opencli browser verify` 一条龙。 -It also works as a **CLI hub** for local tools such as `gh`, `docker`, `longbridge`, `tg`, `discord`, `wx`, `ntn` (Notion), and other binaries you register yourself, plus **desktop app adapters** for Electron apps like Cursor, Trae CN, Codex, Antigravity, ChatGPT, and Trae SOLO. +除了网站能力，OpenCLI 还是一个 **CLI 枢纽**：你可以把 `gh`、`docker`、`longbridge`、`tg`、`discord`、`wx`、`ntn`（Notion）等本地工具统一注册到 `opencli` 下，也可以通过桌面端适配器控制 Cursor、Trae CN、Codex、Antigravity、ChatGPT、Trae SOLO 等 Electron 应用。 -## Quick Start +## 快速开始 -### 1. Install OpenCLI +### 1. 安装 OpenCLI -For desktop use, start with **OpenCLIApp**. It bundles the OpenCLI runtime, -keeps the managed `opencli` command installed, and gives you a system tray UI -for setup, diagnostics, updates, browser-login keepalive, and Web → Markdown. +如果你是在自己的电脑上使用，优先安装 **OpenCLIApp**。它会内置 +OpenCLI runtime，帮你安装 / 修复受管理的 `opencli` 命令，并提供系统托盘 +UI 来做环境诊断、更新、浏览器登录态保活和网页转 Markdown。 -**Option A — OpenCLIApp (recommended for macOS / Windows):** -Download the latest app from , install it, then -open the app once and use the System page to install or repair the `opencli` -command. +**方式 A — OpenCLIApp（macOS / Windows 推荐）：** +从 下载最新版 App，安装后打开一次，在 +System 页面安装或修复 `opencli` 命令。 -**Option B — npm global install (CLI-only / CI / servers):** -OpenCLI requires **Node.js >= 20** when installed through npm. +**方式 B — npm 全局安装（纯 CLI / CI / 服务器）：** +通过 npm 安装时，OpenCLI 要求 **Node.js >= 20**。 ```bash node --version npm install -g @jackwener/opencli ``` -### 2. Install the Browser Bridge Extension +### 2. 安装 Browser Bridge 扩展 -OpenCLI connects to Chrome/Chromium through a lightweight Browser Bridge extension plus a small local daemon. The daemon auto-starts when needed. +OpenCLI 通过轻量 Browser Bridge 扩展和本地微型 daemon 与 Chrome/Chromium 通信。daemon 会按需自动启动。 -**Option A — Chrome Web Store (recommended):** -Install **OpenCLI** from the [Chrome Web Store](https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk). +**方式 A — Chrome Web Store（推荐）：** +在 [Chrome Web Store](https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk) 安装 **OpenCLI** 扩展。 -**Option B — Manual install:** -1. Download the latest `opencli-extension-v{version}.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. +**方式 B — 手动安装：** +1. 到 GitHub [Releases 页面](https://github.com/jackwener/opencli/releases) 下载最新的 `opencli-extension-v{version}.zip`。 +2. 解压后打开 `chrome://extensions`，启用 **开发者模式**。 +3. 点击 **加载已解压的扩展程序**，选择解压后的目录。 -### 3. Verify the setup +### 3. 验证环境 ```bash opencli doctor ``` -### 4. Optional: name your Chrome profile - -Each Chrome profile runs its own OpenCLI extension instance. If you use multiple Chrome profiles, list the connected profiles and assign local aliases: - -```bash -opencli profile list -opencli profile rename work -opencli profile use work -opencli --profile work browser main state -``` - -With only one connected profile, OpenCLI uses it automatically. With multiple connected profiles and no default, OpenCLI asks you to choose instead of guessing. - -### 5. Run your first commands +### 4. 跑第一个命令 ```bash opencli list @@ -77,38 +69,38 @@ opencli hackernews top --limit 5 opencli bilibili hot --limit 5 ``` -## For Humans +## 给人类用户 -Use OpenCLI directly when you want a reliable command instead of a live browser session: +如果你只是想稳定地调用网站或桌面应用能力，主路径很简单： -- `opencli list` shows every registered command. -- `opencli ` runs a built-in or generated adapter. -- `opencli external register mycli` exposes a local CLI through the same discovery surface. -- `opencli doctor` helps diagnose browser connectivity. +- `opencli list` 查看当前所有命令 +- `opencli ` 调用内置或生成好的适配器 +- `opencli external register mycli` 把本地 CLI 接入同一发现入口 +- `opencli doctor` 处理浏览器连通性问题 -## Extending OpenCLI +## 扩展 OpenCLI -If you want to add your own commands, start with the [Extending OpenCLI guide](./docs/guide/extending-opencli.md). README keeps this short; the guide covers the directory layout, source-control model, and install commands. +如果你想新增自己的命令，先看 [扩展 OpenCLI](./docs/zh/guide/extending-opencli.md)。README 只保留入口；目录结构、源码管理方式和安装命令放在文档里。 -| Need | Recommended path | -|------|------------------| -| Keep personal website commands in your own Git repo | `opencli plugin create` + `opencli plugin install file://...` | -| Quickly draft a private local adapter | `opencli browser init /` in `~/.opencli/clis/` | -| Modify an official adapter locally | `opencli adapter eject ` + `opencli adapter reset ` | -| Publish or install third-party commands | `opencli plugin install github:user/repo` | -| Wrap an existing local binary | `opencli external register ` | +| 需求 | 推荐路径 | +|------|----------| +| 把个人网站命令放在自己的 Git repo | `opencli plugin create` + `opencli plugin install file://...` | +| 快速写一个本机私人 adapter | `opencli browser init /`，放在 `~/.opencli/clis/` | +| 本地修改官方 adapter | `opencli adapter eject ` + `opencli adapter reset ` | +| 发布或安装第三方命令 | `opencli plugin install github:user/repo` | +| 包装已有本机 binary | `opencli external register ` | -## For AI Agents +## 给 AI Agent -OpenCLI's browser commands are designed to be used by AI Agents — not run manually. Install skills into your AI agent (Claude Code, Cursor, etc.), and the agent operates websites on your behalf using your logged-in Chrome session. +OpenCLI 的 browser 命令是给 AI Agent 用的——不是手动执行的。把 skill 安装到你的 AI Agent（Claude Code、Cursor 等）中，Agent 就能用你的已登录 Chrome 会话替你操作网站。 -### Install skills (also refreshes existing installs) +### 安装 skill（同时也用于更新） ```bash npx skills add jackwener/opencli ``` -Or install only what you need: +或只装需要的 skill： ```bash npx skills add jackwener/opencli --skill opencli-adapter-author @@ -119,80 +111,83 @@ npx skills add jackwener/opencli --skill opencli-sitemap-author npx skills add jackwener/opencli --skill opencli-usage ``` -### Which skill to use +### 选择哪个 skill -| Skill | When to use | Example prompt to your AI agent | -|-------|------------|-------------------------------| -| **opencli-adapter-author** | Write a reusable adapter for a new site or add a command to an existing site | "Write an adapter for douyin trending" / "Make a command that grabs the top posts from this page" | -| **opencli-autofix** | Repair a broken adapter when a built-in command fails | "`opencli zhihu hot` is returning empty — fix it" | -| **opencli-browser** | Drive a real Chrome page ad-hoc — navigate, fill forms, click, extract | "Help me check my Xiaohongshu notifications" / "Help me fill out this form" / "Use browser commands to scrape this page" | -| **opencli-browser-sitemap** | Consume site sitemap context while driving a browser task | "Use the sitemap to navigate this website without blind clicking" | -| **opencli-sitemap-author** | Create or update site sitemap knowledge for browser agents | "Record the stable workflow you just discovered for this site" | -| **opencli-usage** | Quick reference for all OpenCLI commands and sites | "What commands does OpenCLI have for Twitter?" | +| Skill | 适用场景 | 你对 AI Agent 说的话 | +|-------|---------|-------------------| +| **opencli-adapter-author** | 为新站点写可复用适配器，或给已有站点添加命令 | "帮我做一个抖音热门的适配器" / "帮我做一个抓取这个页面热帖的命令" | +| **opencli-autofix** | 内置命令失败时修复已有适配器 | "`opencli zhihu hot` 返回空了，修一下" | +| **opencli-browser** | 实时驱动 Chrome 页面——导航、填表单、点击、抓取 | "帮我看看小红书的通知" / "帮我填一下这个表单" / "用浏览器命令抓取这个页面" | +| **opencli-browser-sitemap** | 使用站点 sitemap 上下文来操作浏览器任务 | "用 sitemap 帮我少走弯路地操作这个网站" | +| **opencli-sitemap-author** | 创建或更新面向浏览器 Agent 的站点 sitemap | "把刚发现的稳定流程记录到这个站点的 sitemap" | +| **opencli-usage** | 所有命令和站点的快速参考 | "OpenCLI 有哪些 Twitter 相关的命令？" | -### How it works +### 工作原理 -Once `opencli-browser` is installed, your AI agent can: +安装 `opencli-browser` skill 后，你的 AI Agent 可以： -1. **Navigate** to any URL using your logged-in browser -2. **Read** page content via structured DOM snapshots (not screenshots) -3. **Interact** — click buttons, fill forms, select options, press keys -4. **Extract** data from the page or intercept network API responses -5. **Wait** for elements, text, or page transitions +1. **导航**到任意 URL，使用你的已登录浏览器 +2. **读取**页面内容——通过结构化 DOM 快照（不是截图） +3. **交互**——点击按钮、填写表单、选择选项、按键 +4. **提取**页面数据或拦截网络 API 响应 +5. **等待**元素、文本或页面跳转 -The agent handles all the `opencli browser` commands internally — you just describe what you want done in natural language. +Agent 在内部自动处理所有 `opencli browser` 命令——你只需用自然语言描述想做的事。 -**Skill references:** -- [`skills/opencli-browser/SKILL.md`](./skills/opencli-browser/SKILL.md) — drive Chrome ad-hoc (navigate, fill forms, click, extract) -- [`skills/opencli-browser-sitemap/SKILL.md`](./skills/opencli-browser-sitemap/SKILL.md) — use sitemap context while driving a browser task -- [`skills/opencli-sitemap-author/SKILL.md`](./skills/opencli-sitemap-author/SKILL.md) — create or update site sitemap knowledge -- [`skills/opencli-adapter-author/SKILL.md`](./skills/opencli-adapter-author/SKILL.md) — write a new adapter end-to-end -- [`skills/opencli-autofix/SKILL.md`](./skills/opencli-autofix/SKILL.md) — repair broken adapters -- [`skills/opencli-usage/SKILL.md`](./skills/opencli-usage/SKILL.md) — command and site reference +**Skill 参考文档：** +- [`skills/opencli-browser/SKILL.md`](./skills/opencli-browser/SKILL.md) — 实时驱动 Chrome（导航、填表单、点击、抓取） +- [`skills/opencli-browser-sitemap/SKILL.md`](./skills/opencli-browser-sitemap/SKILL.md) — 操作浏览器任务时消费 sitemap 上下文 +- [`skills/opencli-sitemap-author/SKILL.md`](./skills/opencli-sitemap-author/SKILL.md) — 创建或更新站点 sitemap 知识 +- [`skills/opencli-adapter-author/SKILL.md`](./skills/opencli-adapter-author/SKILL.md) — 给新站点写适配器，全流程 +- [`skills/opencli-autofix/SKILL.md`](./skills/opencli-autofix/SKILL.md) — 修复已有适配器 +- [`skills/opencli-usage/SKILL.md`](./skills/opencli-usage/SKILL.md) — 命令和站点参考 -Available browser commands include `open`, `state`, `click`, `type`, `fill`, `select`, `keys`, `wait`, `get`, `find`, `extract`, `frames`, `screenshot`, `scroll`, `back`, `eval`, `network`, `tab list`, `tab new`, `tab select`, `tab close`, `init`, `verify`, and `close`. +`browser` 可用命令包括：`open`、`state`、`click`、`type`、`fill`、`select`、`keys`、`wait`、`get`、`find`、`extract`、`frames`、`screenshot`、`scroll`、`back`、`eval`、`network`、`tab list`、`tab new`、`tab select`、`tab close`、`init`、`verify`、`close`。 -`opencli browser` commands require a `` positional immediately after `browser`. `opencli browser work open ` and `opencli browser work tab new [url]` both return a target ID. Use `opencli browser work tab list` to inspect target IDs, then pass `--tab ` to route a command to a specific tab. `tab new` creates a new tab without changing the default browser target; only `tab select ` promotes that tab to the default target for later untargeted commands in the same session. +`opencli browser` 命令必须紧跟一个 `` 位置参数。`opencli browser work open ` 和 `opencli browser work tab new [url]` 都会返回 target ID。`opencli browser work tab list` 用来查看当前已存在 tab 的 target ID，再通过 `--tab ` 把命令明确路由到某个 tab。`tab new` 只会新建 tab，不会改变默认浏览器目标；只有显式执行 `tab select `，才会把该 tab 设为同一 session 后续未指定 target 的默认目标。 -## Writing a new adapter +## 为新站点写适配器 -When the site you need is not yet covered, use the `opencli-adapter-author` skill end-to-end: +当你需要的网站还没覆盖时，用 `opencli-adapter-author` skill，全流程： -1. **Recon** the site and pick a pattern (SPA / SSR / JSONP / Token / Streaming). -2. **Discover** the right endpoint — network inspection, initial state, bundle search, token trace, or interceptor fallback. -3. **Pick auth** — `PUBLIC` / `COOKIE` / `INTERCEPT` / `UI` / `LOCAL`. -4. **Decode** response fields and design output columns. -5. `opencli browser recon analyze ` → `opencli browser recon init /` → write adapter → `opencli browser recon verify /`. -6. Site knowledge persists to `~/.opencli/sites//` so the next adapter for the same site starts from context. +1. **侦察**站点，分类 pattern（SPA / SSR / JSONP / Token / Streaming） +2. **发现** endpoint——network 精读、initial state、bundle 搜索、token 溯源，或 interceptor 兜底 +3. **定认证**——`PUBLIC` / `COOKIE` / `INTERCEPT` / `UI` / `LOCAL` +4. **字段解码** + 设计输出列 +5. `opencli browser recon analyze ` → `opencli browser recon init /` → 写适配器 → `opencli browser recon verify /` +6. 站点知识沉到 `~/.opencli/sites//`，下次同站点直接吃缓存 -## Configuration +## 配置 -| Variable | Default | Description | -|----------|---------|-------------| -| `OPENCLI_PROFILE` | — | Browser Bridge profile alias/contextId to use when multiple Chrome profiles are connected | -| `OPENCLI_WINDOW` | command default | Set to `foreground` or `background` to override Browser Bridge window placement. Browser-backed commands also accept `--window `. | -| `OPENCLI_BROWSER_CONNECT_TIMEOUT` | `45` | Seconds to wait for browser connection | -| `OPENCLI_BROWSER_COMMAND_TIMEOUT` | `60` | Seconds to wait for a single browser command | -| `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) | -| `DEBUG_SNAPSHOT` | — | Set to `1` for DOM snapshot debug output | +| 变量 | 默认值 | 说明 | +|------|--------|------| +| `OPENCLI_WINDOW` | 命令默认值 | 设为 `foreground` 或 `background` 来覆盖 Browser Bridge 窗口位置。浏览器型命令也支持 `--window ` | +| `OPENCLI_BROWSER_CONNECT_TIMEOUT` | `45` | 浏览器连接超时（秒） | +| `OPENCLI_BROWSER_COMMAND_TIMEOUT` | `60` | 单个浏览器命令超时（秒） | +| `OPENCLI_CDP_ENDPOINT` | — | Chrome DevTools Protocol 端点，用于远程浏览器或 Electron 应用 | +| `OPENCLI_CDP_TARGET` | — | 按 URL 子串过滤 CDP target（如 `detail.1688.com`） | +| `OPENCLI_VERBOSE` | `false` | 启用详细日志（`-v` 也可以） | +| `DEBUG_SNAPSHOT` | — | 设为 `1` 输出 DOM 快照调试信息 | -`opencli browser *` requires an explicit `` positional, uses a foreground browser window by default, and keeps that session's tab lease until `opencli browser close` or idle cleanup. Browser-backed adapters use a background adapter window and release one-shot tab leases by default. Interactive adapters can declare `siteSession: 'persistent'` to keep a stable site tab for continuity; pass `--site-session ephemeral` for a one-shot tab. +Browser Bridge daemon 与扩展的通信端口固定为 `localhost:19825`，不再支持通过 `OPENCLI_DAEMON_PORT` 配置自定义端口。 -## Built-in Commands +`opencli browser *` 必须紧跟一个 `` 位置参数，默认使用前台窗口，并保留该 session 的 tab lease，直到你手动执行 `opencli browser close` 或等空闲超时。浏览器型 adapter 默认使用后台 adapter 窗口并在命令结束后释放一次性 tab lease；如果需要调试最终页面，可以传 `--window foreground --keep-tab true`。 -| Site | Commands | -|------|----------| -| **xiaohongshu** | `search` `ask` `note` `comments` `feed` `user` `download` `publish` `follow` `unfollow` `notifications` `creator-notes` `creator-notes-summary` `creator-note-detail` `creator-profile` `creator-stats` | -| **bilibili** | `hot` `search` `history` `feed` `ranking` `download` `comments` `dynamic` `favorite` `following` `follow` `unfollow` `me` `subtitle` `summary` `video` `user-videos` | +## 内置命令 + +运行 `opencli list` 查看完整注册表。 + +| 站点 | 命令 | +|------|------| +| **xiaohongshu** | `search` `ask` `note` `comments` `notifications` `feed` `user` `saved` `liked` `download` `publish` `follow` `unfollow` `creator-notes` `creator-note-detail` `creator-notes-summary` `creator-profile` `creator-stats` | +| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `subtitle` `summary` `video` `comments` `dynamic` `ranking` `following` `follow` `unfollow` `user-videos` `download` | | **zhihu** | `hot` `search` `question` `download` `follow` `like` `favorite` `comment` `answer` | | **hackernews** | `top` `new` `best` `ask` `show` `jobs` `search` `user` | | **hltv** | `search` `player-summary` `player-matches` `player-form` `player-map-pool` `player-vs-team` `player-teammate-impact` `player-duel` `match-map` `match-series` `team-matches` `team-map-pool` `event-matches` | | **geogebra** | `eval` `add-point` `add-line` `add-circle` `add-polygon` `triangle` `hexagon` `list` `info` | -| **linkedin** | `connect` `inbox` `job-detail` `jobs-preferences` `post-analytics` `posts` `profile-experience` `profile-projects` `profile-read` `profile-analytics` `safe-send` `search` `services-read` `sent-invitations` `thread-snapshot` `timeline` `salesnav-search` `salesnav-inbox` `salesnav-message` `salesnav-thread` | -| **reddit** | `hot` `frontpage` `popular` `search` `subreddit` `read` `user` `user-posts` `user-comments` `upvote` `upvoted` `save` `saved` `comment` `subscribe` | -| **twitter** | `trending` `search` `timeline` `tweets` `lists` `list-tweets` `list-create` `list-delete` `list-add` `list-add-batch` `list-remove` `list-remove-batch` `bookmarks` `post` `download` `profile` `article` `like` `likes` `notifications` `reply` `reply-dm` `thread` `follow` `unfollow` `followers` `following` `block` `unblock` `bookmark` `unbookmark` `delete` `hide-reply` `accept` | +| **linkedin** | `connect` `inbox` `job-detail` `jobs-preferences` `post-analytics` `posts` `profile-experience` `profile-projects` `profile-read` `profile-analytics` `safe-send` `search` `people-search` `services-read` `sent-invitations` `thread-snapshot` `timeline` `salesnav-search` `salesnav-inbox` `salesnav-message` `salesnav-thread` | +| **reddit** | `hot` `frontpage` `popular` `search` `subreddit` `read` `user` `user-posts` `user-comments` `upvote` `save` `comment` `subscribe` `saved` `upvoted` | +| **twitter** | `trending` `search` `timeline` `tweets` `lists` `list-tweets` `list-create` `list-delete` `list-add` `list-add-batch` `list-remove` `list-remove-batch` `bookmarks` `profile` `thread` `following` `followers` `notifications` `post` `reply` `delete` `like` `likes` `article` `follow` `unfollow` `bookmark` `unbookmark` `download` `accept` `reply-dm` `block` `unblock` `hide-reply` | | **claude** | `ask` `send` `new` `status` `read` `history` `detail` | | **gemini** | `new` `ask` `image` `deep-research` `deep-research-result` | | **notebooklm** | `status` `list` `open` `current` `get` `history` `summary` `note-list` `notes-get` `source-list` `source-get` `source-fulltext` `source-guide` | @@ -201,100 +196,154 @@ When the site you need is not yet covered, use the `opencli-adapter-author` skil | **slock** | `message-send` `message-read` `message-search` `channel-list` `channel-info` `channel-create` `channel-members` `channel-join` `task-list` `task-create` `task-claim` `task-status` `task-convert` `task-delete` `thread-list` `thread-follow` `attachment-upload` `attachment-download` `bookmark-add` `inbox` `dm-list` `server-list` `server-use` `whoami` | | **huodongxing** | `events` | -Curated highlights — **[→ see all 100+ supported sites & commands](./docs/adapters/index.md)** (douyin / weibo / spotify / 1688 / quark / nowcoder / google-scholar / hupu / xianyu / weread / weread-official / xiaoyuzhou / Chess.com / and more). +精选清单 — **[→ 查看全部 100+ 站点和命令](./docs/adapters/index.md)**（小红书 / B站 / 知乎 / Twitter / Reddit / 抖音 / 微博 / 微信读书 / 小宇宙 / 1688 / 夸克 / Spotify / 牛客 / arxiv / Chess.com / Bilibili / 等）。 -## CLI Hub +### 外部 CLI 枢纽 -Unified passthrough for your existing command-line tools. Run `opencli ...` for any of: +把现有命令行工具统一接入 `opencli ...`： `gh` · `docker` · `vercel` · `wrangler` · `obsidian` · `longbridge` · `lark-cli` · `ntn(notion)` · `dws(DingTalk Workspace)` · `wecom-cli(企业微信)` · `tg(tg-cli)` · `discord(discord-cli)` · `wx(wx-cli)` -Register your own with `opencli external register `; list everything with `opencli external list`. +注册自定义本地 CLI：`opencli external register `；查看所有：`opencli external list`。 -**Desktop app adapters** (Electron, via CDP): Cursor / Trae CN / Codex / Antigravity / ChatGPT App / ChatWise / Qoder / Discord / Doubao / Trae SOLO — see [`docs/adapters/desktop/`](./docs/adapters/desktop/). +**桌面应用适配器**（Electron，通过 CDP）：Cursor / Trae CN / Codex / Antigravity / ChatGPT App / ChatWise / Qoder / Discord / Doubao / Trae SOLO — 详见 [`docs/adapters/desktop/`](./docs/adapters/desktop/)。 -## Download Support +## 下载支持 -OpenCLI supports downloading images, videos, and articles from supported platforms. +OpenCLI 支持从各平台下载图片、视频和文章。 -| Platform | Content Types | Notes | -|----------|---------------|-------| -| **xiaohongshu** | Images, Videos | Downloads all media from a note | -| **rednote** | Images, Videos | Downloads all media from a signed rednote note URL | -| **bilibili** | Videos | Requires `yt-dlp` installed | -| **twitter** | Images, Videos | From user media tab or single tweet | -| **douban** | Images | Poster / still image lists | -| **pixiv** | Images | Original-quality illustrations, multi-page | -| **1688** | Images, Videos | Downloads page-visible product media from item pages | -| **xiaoyuzhou** | Audio, Transcript | Downloads episode audio and transcript JSON/text with local credentials | -| **zhihu** | Articles (Markdown) | Exports with optional image download | -| **weixin** | Articles (Markdown) | WeChat Official Account articles | +### 支持的平台 -For video downloads, install `yt-dlp` first: `brew install yt-dlp` +| 平台 | 内容类型 | 说明 | +|------|----------|------| +| **小红书** | 图片、视频 | 下载笔记中的所有媒体文件 | +| **B站** | 视频 | 需要安装 `yt-dlp` | +| **Twitter/X** | 图片、视频 | 从用户媒体页或单条推文下载 | +| **Pixiv** | 图片 | 下载原始画质插画，支持多页作品 | +| **1688** | 图片、视频 | 下载商品页中可见的商品素材 | +| **小宇宙** | 音频、转录 | 使用本地凭证下载单集音频和转录 JSON / 文本 | +| **知乎** | 文章（Markdown） | 导出文章，可选下载图片到本地 | +| **微信公众号** | 文章（Markdown） | 导出微信公众号文章为 Markdown | +| **豆瓣** | 图片 | 下载电影条目的海报 / 剧照图片 | + +### 前置依赖 + +下载流媒体平台的视频需要安装 `yt-dlp`： ```bash +# 安装 yt-dlp +pip install yt-dlp +# 或者 +brew install yt-dlp +``` + +### 使用示例 + +```bash +# 下载小红书笔记中的图片/视频 opencli xiaohongshu download "https://www.xiaohongshu.com/search_result/?xsec_token=..." --output ./xhs opencli xiaohongshu download "https://xhslink.com/..." --output ./xhs opencli rednote download "https://www.rednote.com/search_result/?xsec_token=..." --output ./rednote + +# 下载B站视频（需要 yt-dlp） opencli bilibili download BV1xxx --output ./bilibili +opencli bilibili download BV1xxx --quality 1080p # 指定画质 + +# 下载 Twitter 用户的媒体 opencli twitter download elonmusk --limit 20 --output ./twitter + +# 下载单条推文的媒体 +opencli twitter download --tweet-url "https://x.com/user/status/123" --output ./twitter + +# 下载豆瓣电影海报 / 剧照 +opencli douban download 30382501 --output ./douban + +# 下载 1688 商品页中的图片 / 视频素材 opencli 1688 download 841141931191 --output ./1688-downloads + +# 下载小宇宙单集音频 opencli xiaoyuzhou download 69b3b675772ac2295bfc01d0 --output ./xiaoyuzhou + +# 下载小宇宙单集转录 opencli xiaoyuzhou transcript 69dd0c98e2c8be31551f6a33 --output ./xiaoyuzhou-transcripts + +# 导出知乎文章为 Markdown +opencli zhihu download "https://zhuanlan.zhihu.com/p/xxx" --output ./zhihu + +# 导出并下载图片 +opencli zhihu download "https://zhuanlan.zhihu.com/p/xxx" --download-images + +# 导出微信公众号文章为 Markdown +opencli weixin download --url "https://mp.weixin.qq.com/s/xxx" --output ./weixin ``` -`opencli xiaoyuzhou download` and `transcript` require local Xiaoyuzhou credentials in `~/.opencli/xiaoyuzhou.json`. +`opencli xiaoyuzhou download` 和 `transcript` 需要本地小宇宙凭证：`~/.opencli/xiaoyuzhou.json`。 -## Output Formats -All built-in commands support `--format` / `-f` with `table` (default), `json`, `yaml`, `md`, and `csv`. + +## 输出格式 + +所有内置命令都支持 `--format` / `-f`，可选值为 `table`、`json`、`yaml`、`md`、`csv`。 +`list` 命令也支持同样的格式参数，同时继续兼容 `--json`。 ```bash -opencli bilibili hot -f json # Pipe to jq or LLMs -opencli bilibili hot -f csv # Spreadsheet-friendly -opencli bilibili hot -v # Verbose: show pipeline debug steps +opencli list -f yaml # 用 YAML 列出命令注册表 +opencli bilibili hot -f table # 默认：富文本表格 +opencli bilibili hot -f json # JSON（适合传给 jq 或者各类 AI Agent） +opencli bilibili hot -f yaml # YAML（更适合人类直接阅读） +opencli bilibili hot -f md # Markdown +opencli bilibili hot -f csv # CSV +opencli bilibili hot -v # 详细模式：展示管线执行步骤调试信息 ``` -## Exit Codes +## 退出码 -opencli follows Unix `sysexits.h` so CI / scripts can branch on failure mode: `0` success, `66` empty result, `69` Browser Bridge down, `75` timeout, `77` auth required, `78` config error, `130` Ctrl-C. Full reference: [docs/guide/exit-codes.md](./docs/guide/exit-codes.md). +opencli 遵循 Unix `sysexits.h`，CI / 脚本可按失败模式分支：`0` 成功、`66` 无数据、`69` Browser Bridge 未连接、`75` 超时、`77` 需要认证、`78` 配置错误、`130` Ctrl-C。完整参考：[docs/zh/guide/exit-codes.md](./docs/zh/guide/exit-codes.md)。 -## Plugins +## 插件 -Extend OpenCLI with community-contributed adapters: +通过社区贡献的插件扩展 OpenCLI。插件使用与内置命令相同的 JS 格式，启动时自动发现。 ```bash -opencli plugin install github:user/opencli-plugin-my-tool -opencli plugin list -opencli plugin update --all -opencli plugin uninstall my-tool +opencli plugin install github:user/opencli-plugin-my-tool # 安装 +opencli plugin list # 查看已安装 +opencli plugin update my-tool # 更新到最新 +opencli plugin update --all # 更新全部已安装插件 +opencli plugin uninstall my-tool # 卸载 ``` -| Plugin | Type | Description | -|--------|------|-------------| -| [opencli-plugin-github-trending](https://github.com/ByteYue/opencli-plugin-github-trending) | JS | GitHub Trending repositories | -| [opencli-plugin-hot-digest](https://github.com/ByteYue/opencli-plugin-hot-digest) | JS | Multi-platform trending aggregator | -| [opencli-plugin-juejin](https://github.com/Astro-Han/opencli-plugin-juejin) | JS | 稀土掘金 (Juejin) hot articles | -| [opencli-plugin-vk](https://github.com/flobo3/opencli-plugin-vk) | JS | VK (VKontakte) wall, feed, and search | +当 plugin 的版本被记录到 `~/.opencli/plugins.lock.json` 后，`opencli plugin list` 也会显示对应的短 commit hash。 -See [Plugins Guide](./docs/guide/plugins.md) for creating your own plugin. +| 插件 | 类型 | 描述 | +|------|------|------| +| [opencli-plugin-github-trending](https://github.com/ByteYue/opencli-plugin-github-trending) | JS | GitHub Trending 仓库 | +| [opencli-plugin-hot-digest](https://github.com/ByteYue/opencli-plugin-hot-digest) | JS | 多平台热榜聚合 | +| [opencli-plugin-juejin](https://github.com/Astro-Han/opencli-plugin-juejin) | JS | 稀土掘金热门文章 | +| [opencli-plugin-vk](https://github.com/flobo3/opencli-plugin-vk) | JS | VK (VKontakte) 动态、信息流和搜索 | -## Testing +详见 [插件指南](./docs/zh/guide/plugins.md) 了解如何创建自己的插件。 -See **[TESTING.md](./TESTING.md)** for how to run and write tests. +## 常见问题排查 -## Troubleshooting +- **"Extension not connected" 报错** + - 确保你已从 [Chrome Web Store](https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk) 安装 OpenCLI 扩展，且在 `chrome://extensions` 中**已启用**。 +- **"attach failed: Cannot access a chrome-extension:// URL" 报错** + - 其他 Chrome/Chromium 扩展（如 youmind、New Tab Override 或 AI 助手类扩展）可能产生冲突。请尝试**暂时禁用其他扩展**后重试。 +- **返回空数据，或者报错 "Unauthorized"** + - Chrome/Chromium 里的登录态可能已经过期。请打开当前页面，在新标签页重新手工登录或刷新该页面。 +- **Node API 错误 / 缺少 `fetch` / 旧 Node 启动即崩** + - OpenCLI 要求 **Node.js >= 20**。先执行 `node --version`，如果版本过低先升级，再重试命令。 +- **Daemon 问题** + - 检查 daemon 状态：`curl localhost:19825/status` + - 查看扩展日志：`curl localhost:19825/logs` -- **"Extension not connected"** — Ensure the Browser Bridge extension is installed from the [Chrome Web Store](https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk) and **enabled** in `chrome://extensions`. -- **"attach failed: Cannot access a chrome-extension:// URL"** — Another extension may be interfering. Try disabling other extensions temporarily. -- **Empty data or 'Unauthorized' error** — Your Chrome/Chromium login session may have expired. Navigate to the target site and log in again. -- **Node API errors / missing `fetch` / startup crash on old Node** — OpenCLI requires **Node.js >= 20**. Run `node --version`, upgrade Node if needed, then retry. -- **Daemon issues** — Check status: `curl localhost:19825/status` · View logs: `curl localhost:19825/logs` ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=jackwener/opencli&type=Date)](https://star-history.com/#jackwener/opencli&Date) + + ## License [Apache-2.0](./LICENSE)