opencli-usage

opencli-usage

OpenCLI 将任何网站、Electron 桌面应用或外部 CLI 转化为统一的 opencli <site> <command> 界面，代理无需屏幕抓取即可驱动。此技能是导航层——一旦知道要做什么，就加载下面的专门技能之一。

三大支柱

• 适配器命令 — opencli <site> <command> [...]。内置适配器位于 clis/，用户适配器位于 ~/.opencli/clis/。每个适配器由一种策略（PUBLIC | COOKIE | INTERCEPT | UI | LOCAL）支持，指示是否需要 Chrome 会话。
• 浏览器驱动 — opencli browser * 子命令（open、state、click、type、select、find、extract、network 等），用于在没有适配器覆盖任务时进行临时交互和抓取。参见 opencli-browser。
• 当前标签绑定 — opencli browser <session> bind 将用户已打开/登录的 Chrome 标签附加到该浏览器会话。后续命令使用 opencli browser <session> ...。使用前请参见 opencli-browser；绑定的会话仍会阻止标签突变。
• 外部 CLI 透传 — opencli gh、opencli docker、opencli vercel 等。通过 opencli external install <name>（从 external-clis.yaml 自动安装）或 opencli external register <name>（自带）管理。

安装

# npm 全局安装
npm install -g @jackwener/opencli          # 二进制文件：opencli，需要 Node >= 21
opencli doctor                              # 在浏览器相关操作前运行（见下文）

# 从源码安装
git clone git@github.com:jackwener/OpenCLI.git
cd OpenCLI && npm install
npx tsx src/main.ts <command>               # 相同界面，无需全局安装

opencli doctor 打印结构化的 DoctorReport——守护进程状态、扩展连接、版本检查以及实时浏览器连接探测。范围狭窄：它诊断浏览器桥接（守护进程 + 扩展 + Chrome 连接）。PUBLIC / LOCAL 适配器、opencli list、validate、verify、插件命令和外部 CLI 透传不需要它通过——只有 COOKIE / INTERCEPT / UI 适配器和 opencli browser * 子命令需要。标志：-v（详细）。

按命令类型的先决条件

opencli list 上的策略标签	需要什么
PUBLIC	无需任何东西——纯 HTTP，无浏览器。
COOKIE	Chrome 登录到目标网站 + 从 Chrome 网上应用店 安装的 OpenCLI 扩展。命令从您的实时会话中捕获凭据——无需重新登录。
INTERCEPT	与 COOKIE 相同，外加 opencli 打开一个自动化窗口以捕获签名请求。
UI	与 COOKIE 相同，完整的 DOM 交互。
LOCAL	无需浏览器；与本地/开发端点通信。

Electron 桌面应用（cursor、codex、chatwise、discord-app、doubao-app、antigravity、chatgpt-app）通过 CDP 路由到正在运行的应用——与登录浏览器相同的无 cookie 流程。确保在调用前应用正在运行。

发现已安装的内容——不要阅读此文件，运行命令

opencli list                    # 表格，按站点分组
opencli list -f json            # 机器可读；通过管道传递给 jq 或您的代理
opencli list | grep -i twitter  # 查找特定站点的命令
opencli <site> --help           # 查看该站点的命令和标志
opencli <site> <command> --help # 查看位置参数和命令特定标志

不要硬编码适配器列表——有 100 多个站点，数量每周都在变化。opencli list -f json 是事实来源；它为每个命令输出一个条目，包含 {site, name, aliases, description, strategy, browser, args, columns, ...}。对于代理来说，这总是比在文档中 grep 更好。

在回退到原始 opencli browser 命令处理高变化认证站点之前，检查站点适配器是否已公开工作流。例如，ChatGPT 网页有更高级别的命令用于对话读取和 Deep Research 结果提取；通过 opencli chatgpt --help 或 opencli list -f json 发现当前界面。

通用标志（适用于所有适配器命令）

标志	效果
-f, --format <fmt>	table（TTY 中默认）· yaml（非 TTY 中默认）· json· plain· md· csv。当需要特定格式时显式传递；代理几乎总是需要 -f json。
-v, --verbose	调试日志 + 失败时的堆栈跟踪；同时为进程设置 OPENCLI_VERBOSE=1。

命令特定标志（--limit、--tab、--filter 等）不是通用的——请查阅 <site> <command> --help。

输出格式

• json — 美化打印，2 空格缩进。代理的默认选择。
• plain — 为聊天式命令打印单个主要字段（response/content/text/value）。适用于通过管道传递给其他工具。
• yaml — 当输出不是 TTY 且未显式指定 -f 时的回退。
• table — 彩色编码，按站点分组；面向人类。
• md、csv — 直接的表格转储。

少数命令通过 cmd.defaultFormat 覆盖默认值（例如聊天命令默认为 plain），因此在阅读 --help 之前不要假设。

环境变量

变量	默认值	用途
OPENCLI_BROWSER_CONNECT_TIMEOUT	45	等待浏览器桥接的秒数。
OPENCLI_BROWSER_COMMAND_TIMEOUT	60	每个命令的超时时间。
OPENCLI_CDP_ENDPOINT	—	手动 CDP 端点覆盖（开发/远程 Chrome/Electron）。
OPENCLI_CACHE_DIR	~/.opencli/cache	网络捕获 + 浏览器状态缓存。
OPENCLI_WINDOW	命令特定	foreground 或 background 浏览器窗口模式。
OPENCLI_VERBOSE	false	详细日志记录（也由 -v 触发）。

自我修复

当适配器命令因站点更改（选择器漂移、API 轮换、响应模式变化）而失败时，使用 --trace retain-on-failure 重新运行。错误信封包含指向 summary.md 的 trace 块；仅从该摘要修补 adapterSourcePath 并重试。最多 3 轮修复。完整流程见 opencli-autofix。

编写自己的适配器

双路径存储：

• 私有：~/.opencli/clis/<site>/<command>.js — 无需构建步骤，热可用，在公共包中不可见。
• 公共/PR：clis/<site>/<command>.js — 用于上游贡献；需要构建。

脚手架和验证：

opencli browser init <site>/<command>   # 生成骨架
opencli validate [target]               # 对加载的注册表进行语义检查（描述、域、管道步骤名称、func|pipeline|_lazy 存在性、参数重复）——无网络，无浏览器
opencli verify [target] [--smoke]       # 使用合成参数运行命令
opencli browser verify <site>/<command> # 在桥接内进行端到端冒烟测试

适配器仅导入 @jackwener/opencli/registry 和 @jackwener/opencli/errors。columns 必须与 func 返回的对象键一一对应（名称和顺序）。完整工作流见 opencli-adapter-author。

插件

插件是从 git 拉取的第三方扩展，与主适配器注册表分开：

opencli plugin install github:user/repo    # 安装
opencli plugin list [-f json]              # 查看已安装
opencli plugin update [name] | --all       # 保持最新
opencli plugin uninstall <name>
opencli plugin create <name>               # 搭建新插件

外部 CLI 透传

包装外部命令行工具，以便通过相同的 opencli … 入口点发现和调用它们：

opencli external install gh    # 根据 external-clis.yaml 通过 brew/apt/npm 自动安装
opencli external register my-tool \
    --binary my-tool \
    --install "npm i -g my-tool" \
    --desc "我的内部 CLI"
opencli external list
opencli gh pr list --limit 5   # 透传；stdio 继承，退出码传播
opencli docker ps

内置条目位于 src/external-clis.yaml；用户覆盖和添加位于 ~/.opencli/external-clis.yaml。常见内置：gh、docker、vercel、lark-cli、longbridge、dws、wecom-cli、obsidian、ntn、tg(tg-cli)、discord(discord-cli)、wx(wx-cli)。

某些官方 CLI 使用 shell 脚本安装程序而不是无 shell 的包管理器命令。没有 install 配置的条目（例如 ntn）必须从其主页手动安装后才能透传使用。

Shell 补全

opencli completion bash   # 也支持：zsh, fish
# -> 脚本输出到 stdout；根据 shell 约定 source 或保存

下一步去哪里

如果您即将…	加载此技能
临时驱动实时浏览器（无可用适配器，或原型设计）	opencli-browser
编写新适配器，或为现有站点添加命令	opencli-adapter-author
在命令失败后修复损坏的适配器	opencli-autofix
将搜索/查找/研究请求路由到正确的适配器	smart-search

曾经存在的命令

以下命令在 PR #1094 整合中被移除——不要尝试调用它们：

• opencli explore <url> — 已被 opencli browser network + opencli browser find 用于实时 API 发现，以及 opencli-adapter-author 工作流用于捕获所取代。
• opencli record <url> — 已移除；手动捕获现在位于 opencli browser network --detail 中。
• opencli web read / opencli desktop * 作为顶级组 — 已合并到各自的适配器中（opencli web read 仍然作为 web 适配器的 read 命令存在，但没有独立的 web / desktop 顶级组命令）。

不要

• 不要将此技能的命令列表粘贴到您的计划中；它会过时。相反，在任务开始时调用 opencli list -f json。
• 不要假设每个适配器都需要浏览器——策略 PUBLIC 和 LOCAL 不需要。检查 strategy 字段。
• 不要从失败的适配器静默回退到手写 fetch——--trace retain-on-failure 为您提供浏览器证据和适配器源路径。先这样做。