══════════════════════════════════════════════════════════════
    作 品 介 紹
    名 稱 ： 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/

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