penink-pilot

作 品 介 紹

名 稱 ： penink-pilot ・ 讓 AI「駕駛」瀏覽器的瀏覽器

類 型 ： AI Agent 工具・MCP Server（100% 免費・開源，MIT 授權）

官 網 ： https://wh-penink.pages.dev/projects/penink-pilot/

技 術 ： Python / Chrome DevTools Protocol (CDP) / MCP

平 台 ： macOS・Windows・Linux（需本機 Chrome）

一、這是什麼

penink-pilot 是一套「瀏覽器駕駛員」：只要安裝在任何一個 AI

agent 或桌面 agent（Claude Desktop、opencode、Cursor…）上，

AI 就會像 OpenAI Codex 一樣，打開你電腦裡真實的 Chrome、

前往任何網站、讀取網頁、點擊、輸入、按 Enter、捲動、多分頁

操作、執行 JavaScript、截圖確認——一切都是「真人等級」的

操作，不是模擬器。

核心特色

• 真實 Chrome：開出可見視窗，你可以先登入任何網站
• 結構化頁面快照：把整頁整理成「編號元素清單＋內文」，

AI 不靠圖片也能精準掌握頁面狀態

• 真實滑鼠事件：用座標點擊元素中心，SPA / React 都能吃
• 完整工具組：導覽、點擊、輸入、按鍵、捲動、選單、分頁、

任意 JS、截圖……共 23 支 pilot_* 工具

• 標準 MCP：Agent 社群的共通協定，裝上就能用
• 開箱即用：不需要 API key、不需要付費、不寄送任何資料
• 登入永續：瀏覽器設定檔獨立保存，登入狀態下次續用

二、製作過程

開發思路（先讓「讀」對，才有「操控」可言）

1. CDP 底座 cdp.py

用最短的程式碼接上 Chrome DevTools Protocol 的

WebSocket，負責發送／接收指令，支援 browser 與分頁

兩層通訊。

2. 瀏覽器管理 chrome.py

自動尋找本機 Chrome／Chromium，用獨立 profile 啟動

一個「駕駛艙」，等待 debug 埠就緒。

3. 網頁側 JS js.py

注入三小段 JS：掃描可互動元素並標上編號、依編號

重新定位座標、幫輸入框聚焦。

4. 動作翻譯 pilot.py

把 navigate / snapshot / click / type / scroll /

screenshot / 分頁管理 全部翻譯成 CDP 指令。

5. MCP 外殼 server.py

把高階動作包成 23 支 pilot_* 工具，任何 agent 都能呼叫。

6. 驗證

寫了一組 e2e 測試，真的開 headless Chrome，驗證

「導覽→快照→輸入→點擊→讀回 DOM→截圖」整條鏈路。

技術筆記

• 點擊不是 JS click()，而是用 CDP Input.dispatchMouseEvent

送出「真實」滑鼠事件，hover / 拖曳 / SPA 狀態都正常。

• 輸入用 Input.insertText，中文與特殊字元不會壞掉。
• 全程不含任何金鑰、帳號、API key，乾淨開源。

三、使用教學

① 安裝

pip install penink-pilot

若系統找不到 Chrome，設定環境變數 CHROME_PATH 指向

Chrome 執行檔。

② 掛進 agent（三選一）

• Claude Desktop：把 examples/claude_desktop_config.json

的內容貼進 claude_desktop_config.json

• opencode：貼進 opencode.json（也附範例）
• 其他 MCP 桌面 agent：依該軟體 MCP 設定方式，命令列

打 penink-pilot 即可

③ 開始使用（AI 會自動這樣做）

1. pilot_navigate("https://你要去的網站")

2. pilot_snapshot() ← 取得頁面所有元素編號

3. pilot_click(編號) ← 點擊

4. pilot_type(編號, "內容", enter=True) ← 輸入

5. pilot_screenshot() ← 截圖確認

④ 常用指令

pilot_new_tab / pilot_switch_tab / pilot_list_tabs

pilot_evaluate(JS) / pilot_press("Enter")

pilot_scroll("down", 400) / pilot_back / pilot_reload

pilot_stop 關瀏覽器（登入狀態會保留）

四、注意事項（重要）

• 版權與隱私：本工具不收集、不寄送任何網頁或輸入資料，

所有網頁內容只存在你自己的 Chrome 裡。

• AI 到底操控了什麼，你全程看得到——瀏覽器是可見的，

隨時可以直接接手。

• 「編號 ref」在每次 pilot_snapshot 後重新產生，頁面一

變動就要重新 snapshot 再操作。

• 登入狀態存在本機 profile 資料夾，若想「完全乾乾淨淨」

重來，刪除對應的 penink-pilot profile 即可。

• 授權為 MIT，可自由使用、修改、散佈、商用（見 LICENSE）。

五、保存資訊

本資料夾內容即專案完整原始碼：

penink_pilot/ 套件主體（cdp / chrome / js / pilot / server）

tests/ e2e 自動測試（可直接 pytest）

examples/ Claude Desktop 與 opencode 設定範例

pyproject.toml 打包與依賴（mcp + websockets）

README.md 完整文件

LICENSE MIT 授權

本機開發：

pip install -e ".[dev]"

pytest tests/

文件完成・以上為公開資訊，不含任何私密資料