══════════════════════════════════════════════════════════════
    作 品 介 紹
    名 稱 ： penink-agent ・ 會自己修 F12 報錯的網頁除錯 Agent
    類 型 ： AI Agent 框架・自動除錯工具（100% 免費・開源，MIT 授權）
    官 網 ： https://wh-penink.pages.dev/projects/penink-agent/
    技 術 ： Python / OpenAI 相容 tool calling / 本機 LLM / 瀏覽器 console 捕捉
    平 台 ： macOS・Linux・Windows（需本機 LLM 服務與 Chrome）
══════════════════════════════════════════════════════════════


一、這是什麼
──────────────────────────────────────────────────────────────
penink-agent 是一套「模組化 web 除錯 agent」：做網頁專案時，
它會自己打開真瀏覽器、抓下 F12 的報錯（console error、uncaught
exception、404／網路失敗），診斷根因、動手改程式，再重載頁面
驗證——一路修到「零錯誤」才收工。

  核心特色
  ＊ 真的會修，不是只嘴巴說：內建 tool loop（list / read /
    search / write / edit / run），一路改檔到錯誤清空
  ＊ 真瀏覽器驗證：借用 brow 共享瀏覽器座（CDP），載入頁面後
    回傳 console 錯誤＋網路失敗，改完立刻重測
  ＊ 可擴充的插件架構：每個能力是一個「插件模組」，掛一個
    manifest.json 就多一張卡片、開關、工具
  ＊ 網頁管理台：逐專案開關插件、一鍵除錯、即時看執行紀錄
  ＊ 本機模型：跑本機 llama-server，資料不外流、不用 API key
  ＊ 可接自己的控制台：內建 wh-console 後台同步（軌道一）

  第一個插件：F12 除錯醫生（console_doctor）
  抓 console 錯誤、診斷、修到零錯誤——本專案的第一個模組。


二、製作過程
──────────────────────────────────────────────────────────────
  開發思路（先把「讀懂錯誤」做對，才談「自動修」）
  1. 本機 LLM 客戶端 core/llm.py
      用 OpenAI 相容格式打本機 llama-server，支援原生 tool
      calling，讓模型自己決定要讀哪個檔、改哪一行。
  2. 工具與路徑監獄 core/tools.py
      Registry＋內建工具（list/read/search/write/edit/run），
      所有路徑限定在專案根內，避免 agent 亂跑。
  3. Agent 主迴圈 core/loop.py
      Claude 風格 tool loop：模型要工具就給、拿到結果再想，
      步數用盡時誠實總結（不假裝完成）。
  4. 系統提示 prompts/system.md
      寫明「修復要恢復功能，不是只讓錯誤消失」，並教它認新工具。
  5. 插件模組 plugins/console_doctor/
      把「抓 console → 診斷 → 修 → 重測」包成一個模組，
      manifest.json 一放，管理台自動長出卡片。
  6. 管理台 web/api.py
      Starlette／uvicorn：overview、插件開關（落地 projects.json）、
      背景跑修復任務、即時回傳 log 尾巴。
  7. 驗證
      pytest 共 16 項（核心＋整合），整合測試真的打管理台
      （8100）與共享瀏覽器座（8090），驗證整條鏈路。

  技術筆記
  ・ 「壞站」示範 examples/demo-site 內建三種真 bug：引用不存在
    的 lib/missing.js（404）、取不到 grandTotal 元素（TypeError）、
    fetch('/data.json') 檔案不存在（404）。
  ・ 管理台與控制台雙向同步採「最後寫入者勝」，本地剛改的開關
    有 120 秒不被覆蓋的保護期。
  ・ 全程不含任何金鑰、帳號、API key。


三、使用教學
──────────────────────────────────────────────────────────────
  ① 準備
     ・ 本機 LLM：跑 hauhau fast（8086）或 hauhau smart（8087），
       至少一個在線。
     ・ 共享瀏覽器座：browsim（port 8090，提供 /console 捕捉）。
  ② 命令列（最快）
       cd penink-agent
       ./agent.py list          # 列出專案與插件開關
       ./agent.py demo-site     # 直接跑修復任務（示範壞站）
  ③ 網頁管理台
       ~/.penink-pilot/venv/bin/python web/api.py   # → http://127.0.0.1:8100
       打開後：左邊專案、右邊插件開關卡片；按「開始除錯」會在
       背景跑並即時顯示 log。
  ④ 驗收（示範壞站）
       cd examples/demo-site && git checkout -- . && rm -f data.json
       cd ../.. && ./agent.py demo-site
       agent 會逐一修掉三個 bug，直到捕捉回空陣列。
  ⑤ 加一個自己的模組
       新增 plugins/<模組>/manifest.json（id/name/icon/description/
       tools）＋ __init__.py 寫 tools(root, reg)，再到 projects.json
       某專案的 plugins 加上 "<模組>": true，管理台立刻多一張卡片。


四、注意事項（重要）
──────────────────────────────────────────────────────────────
  ＊ 共享分頁：console_doctor 使用的是 brow 共享瀏覽器座，跑修復時
    會暫時把分頁導到你的測試網址；跑完再 brow nav 回去即可。
  ＊ 模型是本機 Qwen，偶爾會做「保守修復」（例如只包 null 檢查）。
    系統提示已要求「恢復功能而非讓錯誤消失」，仍建議瞄一眼執行
    紀錄確認改法。
  ＊ projects.json 會被管理台直接改寫；手改時別在它跑的當下存檔。
  ＊ 需要三件本機服務：llama-server、browsim、以及一個有
    starlette/uvicorn/pytest 的 Python 環境（本機用
    ~/.penink-pilot/venv）。
  ＊ 授權為 MIT，可自由使用、修改、散佈、商用（見 LICENSE）。


五、保存資訊
──────────────────────────────────────────────────────────────
  本資料夾內容即專案完整原始碼：

      agent.py            CLI 入口：./agent.py <project-id> [任務]
      core/               引擎（llm / tools / loop）
      prompts/system.md   系統提示
      plugins/            插件模組（目前：console_doctor）
      web/                管理台（api.py + 前端 + 圖標 + 執行紀錄）
      examples/demo-site/ 內建示範壞站（三種真 bug）
      projects.json       專案清單與插件開關
      tests/              pytest（核心 11 + 整合 5）
      README.md           完整文件
      LICENSE             MIT 授權

  本機開發：
      ~/.penink-pilot/venv/bin/python -m pytest tests/ -q   # 16 passed

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