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, ...}。對代理來說，這總是比搜尋文件更好。

在回退到原始 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 慣例來源或儲存

下一步去哪裡

如果你即將…	載入此技能
臨時驅動即時瀏覽器（無可用適配器，或原型開發）	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 會給你瀏覽器證據和適配器原始碼路徑。請先這樣做。