@jackwener/opencli 1.4.1 → 1.5.0

package/docs/guide/plugins.md

@@ -32,11 +32,98 @@ Plugins live in `~/.opencli/plugins/<name>/`. Each subdirectory is scanned at st
 
 ```bash
 opencli plugin install github:user/repo
+opencli plugin install github:user/repo/subplugin   # install specific sub-plugin from monorepo
 opencli plugin install https://github.com/user/repo
 ```
 
 The repo name prefix `opencli-plugin-` is automatically stripped for the local directory name. For example, `opencli-plugin-hot-digest` becomes `hot-digest`.
 
+## Plugin Manifest (`opencli-plugin.json`)
+
+Plugins can include an `opencli-plugin.json` manifest file at the repo root to declare metadata:
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "opencli": ">=1.0.0",
+  "description": "My awesome plugin"
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `name` | Plugin name (overrides repo-derived name) |
+| `version` | Semantic version |
+| `opencli` | Required opencli version range (e.g. `>=1.0.0`, `^1.2.0`) |
+| `description` | Human-readable description |
+| `plugins` | Monorepo sub-plugin declarations (see below) |
+
+The manifest is optional — plugins without one continue to work exactly as before.
+
+## Monorepo Plugins
+
+A single repository can contain multiple plugins by declaring a `plugins` field in `opencli-plugin.json`:
+
+```json
+{
+  "version": "1.0.0",
+  "opencli": ">=1.0.0",
+  "description": "My plugin collection",
+  "plugins": {
+    "polymarket": {
+      "path": "packages/polymarket",
+      "description": "Prediction market analysis",
+      "version": "1.2.0"
+    },
+    "defi": {
+      "path": "packages/defi",
+      "description": "DeFi protocol data",
+      "version": "0.8.0",
+      "opencli": ">=1.2.0"
+    },
+    "experimental": {
+      "path": "packages/experimental",
+      "disabled": true
+    }
+  }
+}
+```
+
+### Installing
+
+```bash
+# Install ALL enabled sub-plugins from a monorepo
+opencli plugin install github:user/opencli-plugins
+
+# Install a SPECIFIC sub-plugin
+opencli plugin install github:user/opencli-plugins/polymarket
+```
+
+### How It Works
+
+- The monorepo is cloned once to `~/.opencli/monorepos/<repo>/`
+- Each sub-plugin gets a symlink in `~/.opencli/plugins/<name>/` pointing to its subdirectory
+- Command discovery works transparently — symlinks are scanned just like regular directories
+- Disabled sub-plugins (with `"disabled": true`) are skipped during install
+- Sub-plugins can specify their own `opencli` compatibility range
+
+### Updating
+
+Updating any sub-plugin from a monorepo pulls the entire repo and refreshes all sub-plugins:
+
+```bash
+opencli plugin update polymarket   # updates the monorepo, refreshes all
+```
+
+### Uninstalling
+
+```bash
+opencli plugin uninstall polymarket   # removes just this sub-plugin's symlink
+```
+
+When the last sub-plugin from a monorepo is uninstalled, the monorepo clone is automatically cleaned up.
+
 ## Version Tracking
 
 OpenCLI records installed plugin versions in `~/.opencli/plugins.lock.json`. Each entry stores the plugin source, current git commit hash, install time, and last update time. `opencli plugin list` shows the short commit hash when version metadata is available.

package/docs/zh/guide/electron-app-cli.md

@@ -0,0 +1,188 @@
+# 给新 Electron 应用生成 CLI
+
+这篇文档是把一个新的 Electron 桌面应用接入 OpenCLI 的**中文入口指南**。
+
+如果你需要更完整的背景和标准流程，继续看：
+- [Chrome DevTools Protocol（中文）](/zh/advanced/cdp)
+- [CLI-ifying Electron Applications（英文深度版）](/advanced/electron)
+- [TypeScript 适配器开发指南（英文）](/developer/ts-adapter)
+
+## 这篇文档适合什么场景
+
+当目标应用满足下面条件时，用这套流程：
+- 应用是 **Electron**，或者至少能暴露可用的 **CDP（Chrome DevTools Protocol）** 端口
+- 可以通过 `--remote-debugging-port=<port>` 启动
+- 你希望控制的是桌面应用本身，而不是它背后的公开 HTTP API
+
+如果应用**不是** Electron，或者不暴露 CDP，就不要硬套这套方案。那种情况应改用原生桌面自动化方案。可参考 [英文版说明](/advanced/electron#non-electron-pattern-applescript)。
+
+## 最短落地路径
+
+### 1. 先确认它是不是 Electron
+
+macOS 下常见检查方式：
+
+```bash
+ls /Applications/AppName.app/Contents/Frameworks/Electron\ Framework.framework
+```
+
+如果存在，通常就可以继续尝试 CDP。
+
+### 2. 带 CDP 端口启动应用
+
+```bash
+/Applications/AppName.app/Contents/MacOS/AppName --remote-debugging-port=9222
+```
+
+然后把 OpenCLI 指到这个端口：
+
+```bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"
+```
+
+### 3. 先做 5 个基础命令
+
+建议一个新 Electron 适配器先实现这 5 个命令：
+
+- `status.ts` —— 确认 CDP 连通
+- `dump.ts` —— 导出 DOM / snapshot，先做逆向再写逻辑
+- `read.ts` —— 读取当前上下文
+- `send.ts` —— 往真实编辑器里输入并发送
+- `new.ts` —— 新建会话 / 标签页 / 文档
+
+这是最稳妥的基线，因为它先把“能连上、能看见、能读、能写、能重置状态”这 5 件核心事情打通了。
+
+## 推荐开发顺序
+
+### 第一步：先做 `status`
+
+目标不是功能，而是先证明：
+- CDP 真的连上了
+- 你连到的是对的窗口/标签页
+- 应用当前页面确实可读
+
+如果 `status` 都不稳定，先不要继续往下做。
+
+### 第二步：做 `dump`
+
+**不要猜 selector。**
+
+先把这些导出来：
+- `document.body.innerHTML`
+- accessibility snapshot
+- 稳定属性：`data-testid`、`role`、`aria-*` 等
+
+然后再决定：
+- 消息列表在哪
+- 输入框在哪
+- 按钮在哪
+- 当前会话容器在哪
+
+### 第三步：做 `read`
+
+只读真正需要的区域，不要把整个页面文本都塞出来。
+
+常见目标：
+- 对话消息区
+- 当前线程内容
+- 当前编辑器历史
+- 当前文档主区域
+
+### 第四步：做 `send`
+
+很多 Electron 应用的输入框是 React 控制组件，直接改 `.value` 往往没用。
+
+更稳妥的方式通常是：
+- 先 focus 到可编辑区域
+- 能用时优先 `document.execCommand('insertText', false, text)`
+- 最后用真实按键提交，比如 `Enter`、`Meta+Enter`
+
+### 第五步：做 `new`
+
+很多桌面应用的新建动作其实更适合走快捷键，而不是点按钮。
+
+典型模式：
+
+```ts
+const isMac = process.platform === 'darwin';
+await page.pressKey(isMac ? 'Meta+N' : 'Control+N');
+await page.wait(1);
+```
+
+## 文件一般怎么放
+
+一个 TypeScript 桌面适配器，通常结构是：
+
+```text
+src/clis/<app>/status.ts
+src/clis/<app>/dump.ts
+src/clis/<app>/read.ts
+src/clis/<app>/send.ts
+src/clis/<app>/new.ts
+src/clis/<app>/utils.ts
+```
+
+当基础能力稳定后，再继续加：
+- `ask`
+- `history`
+- `model`
+- `screenshot`
+- `export`
+
+## 加完适配器后，还应该补什么文档
+
+至少补这几项：
+- `docs/adapters/desktop/` 下的适配器说明页
+- 命令列表和示例
+- 如何带 `--remote-debugging-port` 启动
+- 需要哪些环境变量
+- 平台限制和注意事项
+
+可以参考这些现成文档：
+- `docs/adapters/desktop/codex.md`
+- `docs/adapters/desktop/chatwise.md`
+- `docs/adapters/desktop/notion.md`
+- `docs/adapters/desktop/discord.md`
+
+## 常见问题
+
+### CDP 能连，但命令不稳定
+
+常见原因：
+- 连错窗口或标签页
+- 页面还没渲染完
+- selector 是猜的，不是从 `dump` 里找出来的
+- 输入框是受控组件，直接赋值不生效
+
+### 应用看起来像 Chromium，但就是不好控
+
+有些桌面应用虽然嵌了 Chromium，但并不真正暴露可用的 CDP 接口。
+这种情况不要强行走 Electron 方案，应该换到非 Electron 的桌面自动化方案。
+
+### 这个应用其实也有网页版本，还要不要做 Electron 适配器
+
+如果网页版本已经足够稳定，浏览器适配器通常更简单。
+只有当**桌面应用才是真正的集成面**时，再优先做 Electron 适配器。
+
+## 推荐阅读顺序
+
+如果你从零开始：
+
+1. 先看这篇
+2. 再看 [CLI-ifying Electron Applications（英文深度版）](/advanced/electron)
+3. 再看 [Chrome DevTools Protocol（中文）](/zh/advanced/cdp)
+4. 再看 [TypeScript Adapter Guide（英文）](/developer/ts-adapter)
+5. 最后找一个现成桌面适配器文档照着做
+
+## 最后一个实践建议
+
+不要一上来就做很大的命令面。
+
+先把下面 5 个做稳：
+- `status`
+- `dump`
+- `read`
+- `send`
+- `new`
+
+这 5 个稳定了，再往外扩，成本最低，返工也最少。

package/docs/zh/guide/getting-started.md

@@ -38,3 +38,4 @@ opencli bilibili hot -f csv     # CSV
 - [Browser Bridge 设置](/zh/guide/browser-bridge)
 - [所有适配器](/zh/adapters/)
 - [开发者指南](/zh/developer/contributing)
+- [给新 Electron 应用生成 CLI](/zh/guide/electron-app-cli)

package/docs/zh/guide/plugins.md

@@ -32,11 +32,76 @@ Plugins 存放在 `~/.opencli/plugins/<name>/`。每个子目录都会在启动
 
 ```bash
 opencli plugin install github:user/repo
+opencli plugin install github:user/repo/subplugin   # 安装 monorepo 中的指定子插件
 opencli plugin install https://github.com/user/repo
 ```
 
 如果仓库名带 `opencli-plugin-` 前缀，本地目录会自动去掉这个前缀。例如 `opencli-plugin-hot-digest` 会变成 `hot-digest`。
 
+## 插件清单 (`opencli-plugin.json`)
+
+插件可以在仓库根目录放置 `opencli-plugin.json` 来声明元数据：
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "opencli": ">=1.0.0",
+  "description": "我的插件"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `name` | 插件名称（覆盖从仓库名推导的名称） |
+| `version` | 语义化版本 |
+| `opencli` | 所需的 opencli 版本范围（如 `>=1.0.0`、`^1.2.0`） |
+| `description` | 描述 |
+| `plugins` | Monorepo 子插件声明（见下文） |
+
+清单文件是可选的——没有它的插件依然可以正常工作。
+
+## Monorepo 插件
+
+一个仓库可以通过在 `opencli-plugin.json` 中声明 `plugins` 字段来包含多个插件：
+
+```json
+{
+  "version": "1.0.0",
+  "opencli": ">=1.0.0",
+  "description": "我的插件合集",
+  "plugins": {
+    "polymarket": {
+      "path": "packages/polymarket",
+      "description": "预测市场分析",
+      "version": "1.2.0"
+    },
+    "defi": {
+      "path": "packages/defi",
+      "description": "DeFi 协议数据",
+      "version": "0.8.0"
+    },
+    "experimental": {
+      "path": "packages/experimental",
+      "disabled": true
+    }
+  }
+}
+```
+
+```bash
+# 安装 monorepo 中的全部子插件
+opencli plugin install github:user/opencli-plugins
+
+# 安装指定子插件
+opencli plugin install github:user/opencli-plugins/polymarket
+```
+
+- Monorepo 只 clone 一次到 `~/.opencli/monorepos/<repo>/`
+- 每个子插件通过 symlink 出现在 `~/.opencli/plugins/<name>/`
+- 更新任何子插件会拉取整个 monorepo 并刷新所有子插件
+- 卸载最后一个子插件时，monorepo 目录会被自动清理
+
 ## 版本追踪
 
 OpenCLI 会把已安装 plugin 的版本记录到 `~/.opencli/plugins.lock.json`。每条记录会保存 plugin source、当前 git commit hash、安装时间，以及最近一次更新时间。只要有这份元数据，`opencli plugin list` 就会显示对应的短 commit hash。

package/extension/package.json

@@ -6,6 +6,7 @@
   "scripts": {
     "dev": "vite build --watch",
     "build": "vite build",
+    "package:release": "node scripts/package-release.mjs",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {

package/extension/scripts/package-release.mjs

@@ -0,0 +1,179 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const extensionDir = path.resolve(__dirname, '..');
+const repoRoot = path.resolve(extensionDir, '..');
+
+function parseArgs(argv) {
+  const args = { outDir: path.join(repoRoot, 'extension-package') };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--out' && argv[i + 1]) {
+      const outDir = argv[++i];
+      args.outDir = path.isAbsolute(outDir)
+        ? outDir
+        : path.resolve(process.cwd(), outDir);
+    }
+  }
+  return args;
+}
+
+async function exists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isLocalAsset(ref) {
+  return typeof ref === 'string'
+    && ref.length > 0
+    && !ref.startsWith('http://')
+    && !ref.startsWith('https://')
+    && !ref.startsWith('//')
+    && !ref.startsWith('chrome://')
+    && !ref.startsWith('chrome-extension://')
+    && !ref.startsWith('data:')
+    && !ref.startsWith('#');
+}
+
+function addLocalAsset(files, ref) {
+  if (isLocalAsset(ref)) files.add(ref);
+}
+
+function collectManifestEntrypoints(manifest) {
+  const files = new Set(['manifest.json']);
+
+  addLocalAsset(files, manifest.background?.service_worker);
+  addLocalAsset(files, manifest.action?.default_popup);
+  addLocalAsset(files, manifest.options_page);
+  addLocalAsset(files, manifest.devtools_page);
+  addLocalAsset(files, manifest.side_panel?.default_path);
+
+  for (const ref of Object.values(manifest.icons ?? {})) addLocalAsset(files, ref);
+  for (const ref of Object.values(manifest.action?.default_icon ?? {})) addLocalAsset(files, ref);
+  for (const contentScript of manifest.content_scripts ?? []) {
+    for (const jsFile of contentScript.js ?? []) addLocalAsset(files, jsFile);
+    for (const cssFile of contentScript.css ?? []) addLocalAsset(files, cssFile);
+  }
+  for (const page of manifest.sandbox?.pages ?? []) addLocalAsset(files, page);
+  for (const overridePage of Object.values(manifest.chrome_url_overrides ?? {})) addLocalAsset(files, overridePage);
+  for (const entry of manifest.web_accessible_resources ?? []) {
+    for (const resource of entry.resources ?? []) addLocalAsset(files, resource);
+  }
+  if (manifest.default_locale) files.add('_locales');
+
+  return [...files];
+}
+
+async function collectHtmlDependencies(relativeHtmlPath, files, visited) {
+  if (visited.has(relativeHtmlPath)) return;
+  visited.add(relativeHtmlPath);
+
+  const htmlPath = path.join(extensionDir, relativeHtmlPath);
+  const html = await fs.readFile(htmlPath, 'utf8');
+  const attrRe = /\b(?:src|href)=["']([^"'#?]+(?:\?[^"']*)?)["']/gi;
+
+  for (const match of html.matchAll(attrRe)) {
+    const rawRef = match[1];
+    const cleanRef = rawRef.split('?')[0];
+    if (!isLocalAsset(cleanRef)) continue;
+
+    const resolvedRelativePath = cleanRef.startsWith('/')
+      ? cleanRef.slice(1)
+      : path.posix.normalize(path.posix.join(path.posix.dirname(relativeHtmlPath), cleanRef));
+
+    addLocalAsset(files, resolvedRelativePath);
+    if (resolvedRelativePath.endsWith('.html')) {
+      await collectHtmlDependencies(resolvedRelativePath, files, visited);
+    }
+  }
+}
+
+async function collectManifestAssets(manifest) {
+  const files = new Set(collectManifestEntrypoints(manifest));
+  const htmlPages = [];
+
+  if (manifest.action?.default_popup) {
+    htmlPages.push(manifest.action.default_popup);
+  }
+  if (manifest.options_page) htmlPages.push(manifest.options_page);
+  if (manifest.devtools_page) htmlPages.push(manifest.devtools_page);
+  if (manifest.side_panel?.default_path) htmlPages.push(manifest.side_panel.default_path);
+  for (const page of manifest.sandbox?.pages ?? []) htmlPages.push(page);
+  for (const overridePage of Object.values(manifest.chrome_url_overrides ?? {})) htmlPages.push(overridePage);
+
+  const visited = new Set();
+  for (const htmlPage of htmlPages) {
+    if (isLocalAsset(htmlPage)) {
+      await collectHtmlDependencies(htmlPage, files, visited);
+    }
+  }
+
+  return [...files];
+}
+
+async function copyEntry(relativePath, outDir) {
+  const fromPath = path.join(extensionDir, relativePath);
+  const toPath = path.join(outDir, relativePath);
+  const stats = await fs.stat(fromPath);
+
+  if (stats.isDirectory()) {
+    await fs.cp(fromPath, toPath, { recursive: true });
+    return;
+  }
+
+  await fs.mkdir(path.dirname(toPath), { recursive: true });
+  await fs.copyFile(fromPath, toPath);
+}
+
+async function findMissingEntries(baseDir, entries) {
+  const missingEntries = [];
+  for (const relativePath of entries) {
+    const absolutePath = path.join(baseDir, relativePath);
+    if (!(await exists(absolutePath))) {
+      missingEntries.push(relativePath);
+    }
+  }
+  return missingEntries;
+}
+
+async function main() {
+  const { outDir } = parseArgs(process.argv.slice(2));
+  const manifestPath = path.join(extensionDir, 'manifest.json');
+  const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+
+  const requiredEntries = await collectManifestAssets(manifest);
+  const missingEntries = await findMissingEntries(extensionDir, requiredEntries);
+
+  if (missingEntries.length > 0) {
+    console.error('Missing files referenced by the extension package:');
+    for (const missingEntry of missingEntries) console.error(`- ${missingEntry}`);
+    process.exit(1);
+  }
+
+  await fs.rm(outDir, { recursive: true, force: true });
+  await fs.mkdir(outDir, { recursive: true });
+
+  for (const relativePath of requiredEntries) {
+    await copyEntry(relativePath, outDir);
+  }
+
+  // Guard against regressions where manifest entry files (e.g. action.default_popup)
+  // are accidentally omitted from the packaged directory.
+  const packagedEntrypoints = collectManifestEntrypoints(manifest);
+  const missingPackagedEntrypoints = await findMissingEntries(outDir, packagedEntrypoints);
+  if (missingPackagedEntrypoints.length > 0) {
+    console.error('Packaged extension is missing files referenced by manifest.json:');
+    for (const missingEntry of missingPackagedEntrypoints) console.error(`- ${missingEntry}`);
+    process.exit(1);
+  }
+
+  console.log(`Extension package prepared at ${path.relative(repoRoot, outDir) || outDir}`);
+}
+
+await main();

package/extension/src/background.ts

@@ -51,6 +51,8 @@ function connect(): void {
       clearTimeout(reconnectTimer);
       reconnectTimer = null;
     }
+    // Send version so the daemon can report mismatches to the CLI
+    ws?.send(JSON.stringify({ type: 'hello', version: chrome.runtime.getManifest().version }));
   };
 
   ws.onmessage = async (event) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "publishConfig": {
     "access": "public"
   },
@@ -19,17 +19,20 @@
   },
   "scripts": {
     "dev": "tsx src/main.ts",
+    "dev:bun": "bun src/main.ts",
     "build": "npm run clean-dist && tsc && npm run clean-yaml && npm run copy-yaml && npm run build-manifest",
     "build-manifest": "node dist/build-manifest.js",
     "clean-dist": "node scripts/clean-dist.cjs",
     "clean-yaml": "node scripts/clean-yaml.cjs",
     "copy-yaml": "node scripts/copy-yaml.cjs",
     "start": "node dist/main.js",
+    "start:bun": "bun dist/main.js",
     "postinstall": "node scripts/postinstall.js || true",
     "typecheck": "tsc --noEmit",
     "lint": "tsc --noEmit",
     "prepublishOnly": "npm run build",
     "test": "vitest run --project unit",
+    "test:bun": "bun vitest run --project unit",
     "test:adapter": "vitest run --project adapter",
     "test:all": "vitest run",
     "test:e2e": "vitest run --project e2e",

package/scripts/postinstall.js

@@ -195,6 +195,16 @@ function main() {
       console.error(`Warning: Could not install shell completion: ${err.message}`);
     }
   }
+
+  // ── Browser Bridge setup hint ───────────────────────────────────────
+  console.log('');
+  console.log('  \x1b[1mNext step — Browser Bridge setup\x1b[0m');
+  console.log('  Browser commands (bilibili, zhihu, twitter...) require the extension:');
+  console.log('  1. Download: https://github.com/jackwener/opencli/releases');
+  console.log('  2. Open chrome://extensions → enable Developer Mode → Load unpacked');
+  console.log('');
+  console.log('  Then run \x1b[36mopencli doctor\x1b[0m to verify.');
+  console.log('');
 }
 
 main();

package/src/browser/cdp.ts

@@ -12,6 +12,7 @@ import { WebSocket, type RawData } from 'ws';
 import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
 import type { BrowserCookie, IPage, ScreenshotOptions, SnapshotOptions, WaitOptions } from '../types.js';
+import type { IBrowserFactory } from '../runtime.js';
 import { wrapForEval } from './utils.js';
 import { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
 import { generateStealthJs } from './stealth.js';
@@ -47,7 +48,7 @@ interface RuntimeEvaluateResult {
 
 const CDP_SEND_TIMEOUT = 30_000;
 
-export class CDPBridge {
+export class CDPBridge implements IBrowserFactory {
   private _ws: WebSocket | null = null;
   private _idCounter = 0;
   private _pending = new Map<number, { resolve: (val: unknown) => void; reject: (err: Error) => void; timer: ReturnType<typeof setTimeout> }>();

package/src/browser/discover.ts

@@ -13,17 +13,22 @@ export { isDaemonRunning };
 /**
  * Check daemon status and return connection info.
  */
-export async function checkDaemonStatus(): Promise<{
+export async function checkDaemonStatus(opts?: { timeout?: number }): Promise<{
   running: boolean;
   extensionConnected: boolean;
+  extensionVersion?: string;
 }> {
   try {
     const port = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts?.timeout ?? 2000);
     const res = await fetch(`http://127.0.0.1:${port}/status`, {
       headers: { 'X-OpenCLI': '1' },
+      signal: controller.signal,
     });
-    const data = await res.json() as { ok: boolean; extensionConnected: boolean };
-    return { running: true, extensionConnected: data.extensionConnected };
+    const data = await res.json() as { ok: boolean; extensionConnected: boolean; extensionVersion?: string };
+    clearTimeout(timer);
+    return { running: true, extensionConnected: data.extensionConnected, extensionVersion: data.extensionVersion };
   } catch {
     return { running: false, extensionConnected: false };
   }