penink-agent

作 品 介 紹

名 稱 ： 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

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