Web Log Capture

持續攔截 Chrome 的 HTTP(S) 與 WebSocket 流量 → in-memory ring buffer → 由 Claude Code skill (web-log-parse) 透過 HTTP 查詢解析。

設計目的：當你在 debug 一個前端、想知道「剛剛那個 API 回什麼」、「那個 ws frame 收到什麼 payload」時，不必開 DevTools 一筆筆撈，可以直接跟 Claude 說「幫我看剛剛打 api.foo.com 的 POST」，由 skill 自動 query。

元件

web-log/
├── extension/        Chrome MV3 extension
│   ├── manifest.json
│   ├── background.js     webRequest + chrome.debugger（HTTP body + WebSocket frames）
│   ├── popup.html
│   └── popup.js          開關 / filter rules / buffer 狀態
├── collector/        Node.js HTTP server（localhost:9999）
│   ├── server.js         in-memory ring buffer，預設 2 GiB
│   └── package.json
└── skills/           Claude Code skills
    ├── web-log-parse/SKILL.md    查詢 / 解析 buffer 內封包
    └── web-log-watch/            阻塞等待特定封包出現後返回
        ├── SKILL.md
        └── scripts/wait-for.sh

你會抓到什麼

來源	內容	備註
`webRequest`	所有 HTTP(S) request：method、headers、request body、response headers、status	Chrome API 限制看不到 response body
`debugger`	HTTP response body	透過 chrome.debugger attach，需 Network domain
`websocket`	WebSocket open / handshake / 每個 frame（含 payload）/ close / error	同樣透過 chrome.debugger

不會抓到：

chrome://、devtools://、Chrome Web Store 等特權頁面
已經有人 attach DevTools 的 tab（同時間只能有一個 debugger）
原生 TCP/UDP（瀏覽器看不到）
WebRTC media frames（只看得到 signaling）

安裝與啟動

1. clone repo

git clone <repo-url> ~/project/web-log
cd ~/project/web-log

需求：Node.js ≥ 18（只用內建 module，不需 npm install）。

2. 啟動 collector

cd collector
node server.js

可選環境變數：

變數	預設	說明
`WEB_LOG_PORT`	`9999`	listen port
`WEB_LOG_MAX_BYTES`	`2147483648`（2 GiB）	ring buffer 上限，超過丟最舊

範例：限制 512 MiB：

WEB_LOG_MAX_BYTES=$((512*1024*1024)) node server.js

💡 不想手動啟動也可以：裝好 skills（步驟 4）後，當你直接叫 Claude「看剛剛的 web log」而 collector 沒在跑，skill 會偵測到 collector offline，提醒你並詢問要不要幫你在背景啟動；你答應後它就會自動跑起 node collector/server.js，確認起來後再繼續查詢。詳見 skills/web-log-parse/SKILL.md。

3. 載入 Chrome extension

chrome://extensions → 右上開啟「開發人員模式」
「載入未封裝項目」→ 選 ~/project/web-log/extension
點 extension 圖示打開 popup → 按 Start capturing

4. 安裝 skills（給 Claude Code 用）

ln -s ~/project/web-log/skills/web-log-parse ~/.claude/skills/web-log-parse
ln -s ~/project/web-log/skills/web-log-watch ~/.claude/skills/web-log-watch

web-log-parse — 查詢 / 解析。「幫我看剛剛的 web log」「找 5xx」
web-log-watch — 阻塞等待。「等到 /login POST 出現再繼續」「等 ws 收到 ready 訊息」

兩個 skill 在動作前都會先檢查 collector 狀態；collector 沒啟動時不會默默失敗，而是提醒你並詢問是否幫你在背景啟動（同意後才動手）。所以你大多時候不必自己先去開 collector。

使用

設定 capture filter

打開 extension popup，編輯 rules：

欄位	範例	說明
`action`	`allow` / `deny`	命中時的行為
`host`	`api.foo.com`	host 子字串
`pathPrefix`	`/v1/`	pathname 前綴
`method`	`POST`	HTTP method（WebSocket 用 `WS`）
`urlRegex`	`\.json$`	完整 URL regex

判斷邏輯：rules 由上往下檢查，第一個所有條件都命中的 rule 決定 allow / deny；都沒命中就走 defaultAction。

同一條 rule 的多個欄位是 AND（全部要符合才算命中）。host / pathPrefix / urlRegex 是子字串或 regex，留空 = 不檢查那個欄位。

範例 1：只抓自家 API 的 POST（最常用）

「我在 debug 自己後端，其他 GA / Sentry / 廣告流量都不要抓」

#	action	host	path	method	urlRegex
default	deny
1	allow	`api.foo.com`		`POST`

效果：只有 *api.foo.com* 的 POST 進 buffer，其他全部 drop。

範例 2：抓全站但排除靜態檔與第三方追蹤

「想看 page 全貌但別被 CSS/JS 跟 GA 洗版」

#	action	host	urlRegex
default	allow
1	deny		`\.(png\|jpg\|gif\|webp\|svg\|css\|js\|woff2?\|map)(\?.*)?$`
2	deny	`google-analytics.com`
3	deny	`doubleclick.net`
4	deny	`sentry.io`

範例 3：只抓 WebSocket

「只在 debug 即時推播，HTTP 全部不要」

#	action	host	path	method	urlRegex
default	deny
1	allow				`^wss?://`

範例 4：抓兩個 host，且每個 host 限定 path

「prod API 全收，staging 只看 /v2 新版」

#	action	host	path
default	deny
1	allow	`api.prod.foo.com`
2	allow	`api.stg.foo.com`	`/v2/`

範例 5：排除某個吵的 endpoint，其餘 API 都收

「/heartbeat 一秒打三次很煩」

#	action	host	path
default	deny
1	deny	`api.foo.com`	`/heartbeat`
2	allow	`api.foo.com`

⚠️ 順序很重要：deny /heartbeat 必須在 allow host=api.foo.com 之前，否則會先被 allow 命中。

從 CLI 設定（extension 每 5 秒會自動 sync 回來）

# 對應範例 1
curl -X POST http://127.0.0.1:9999/config \
  -H 'Content-Type: application/json' \
  -d '{
    "rules": [
      {"action": "allow", "host": "api.foo.com", "method": "POST"}
    ],
    "defaultAction": "deny"
  }'

# 查目前生效的 rules
curl -s http://127.0.0.1:9999/config | jq .

透過 Claude 查詢（web-log-parse）

直接用自然語言，skill 會打 collector API：

「看最近 20 筆」
「找 api.foo.com 的 POST」
「找 5xx」
「剛才那個 /v1/login 的 response body 是什麼？」
「看 WebSocket 收到的 frame」
「client 送出去的 ws message」

等到特定封包出現再繼續（web-log-watch）

讓 Claude 阻塞等待，命中後拿到 matched events 接著實作下一步：

「等使用者登入完，拿到 /login response 後再繼續實作」
「等 WebSocket 收到含 "type":"ready" 的 frame 才開始 client 端 code」
「等任何 5xx 出現就停下來幫我看」

底層腳本：

skills/web-log-watch/scripts/wait-for.sh \
  --host api.foo.com --method POST --path /login --timeout 180
# exit 0 + JSON matched events / exit 124 timeout / exit 2 collector offline

Flags：--host --method --path --url --status（regex）--source --kind --direction --contains（payload 文本 grep）--timeout（秒，0=永遠）--interval（poll 間隔）--limit。

直接打 API

Method	Path	用途
`GET /status`	buffer 狀態 + 目前 rules
`GET /events?...`	查詢事件，預設 summary
`GET /event/:idx`	完整事件（含 body）
`POST /clear`	清空 buffer
`GET /config`	取得 capture rules
`POST /config`	設定 rules / maxBytes
`POST /ingest`	extension 在用，一般不需要

/events query：host method path urlContains status（regex）since（ISO）source（webRequest/debugger/websocket）kind（open/handshake/frame/close/error）direction（sent/received）limit（≤5000）order（asc/desc）summary=0 拿完整資料。

範例：

# 最近 10 筆 WebSocket frame
curl -s 'http://127.0.0.1:9999/events?source=websocket&kind=frame&limit=10' | jq .

# 拿單筆完整內容
curl -s 'http://127.0.0.1:9999/event/123' | jq .

Retention / 記憶體控制

Buffer 是 純記憶體，process 結束就清空，不寫硬碟
達到 maxBytes 時自動丟最舊（/status.totalDropped 會累加）
單筆 response/payload 超過 256 KiB 在 extension 端就 truncate（避免單筆占爆 buffer）
清空：curl -X POST http://127.0.0.1:9999/clear 或 popup 的 Clear 鈕

安全與隱私

Collector 只 listen 127.0.0.1
Authorization / Cookie / Set-Cookie 會原樣記錄到 buffer，但 skill 預設展示時 mask（除非你明確要求展開）
不要對著有敏感資料的環境長時間開著；要清空就按 Clear
Buffer 在 RAM，重開 collector 就消失

開發者守則

Extension 改完 background.js 要回 chrome://extensions 按 reload
Collector 改完 server.js 直接重啟（buffer 會清掉）
Log schema 看 skills/web-log-parse/SKILL.md 的 Event schema 段

疑難排解

症狀	原因 / 解法
popup 顯示 `⚠️ collector offline`	collector 沒起 → `cd collector && node server.js`
抓不到 response body	那個 tab 有人 attach DevTools；關掉 DevTools 或換 tab
抓不到 WebSocket frame	同上；或這個 ws 在 chrome:// 頁面
Chrome 上方一直彈「DevTools 正在 debug 此分頁」	chrome.debugger API 的限制，無解；介意請只在開發時用
`totalDropped` 一直增加	buffer 滿了 → 加大 `WEB_LOG_MAX_BYTES` 或縮 filter 範圍

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
collector		collector
extension		extension
skills		skills
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Web Log Capture

元件

你會抓到什麼

安裝與啟動

1. clone repo

2. 啟動 collector

3. 載入 Chrome extension

4. 安裝 skills（給 Claude Code 用）

使用

設定 capture filter

範例 1：只抓自家 API 的 POST（最常用）

範例 2：抓全站但排除靜態檔與第三方追蹤

範例 3：只抓 WebSocket

範例 4：抓兩個 host，且每個 host 限定 path

範例 5：排除某個吵的 endpoint，其餘 API 都收

從 CLI 設定（extension 每 5 秒會自動 sync 回來）

透過 Claude 查詢（web-log-parse）

等到特定封包出現再繼續（web-log-watch）

直接打 API

Retention / 記憶體控制

安全與隱私

開發者守則

疑難排解

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Web Log Capture

元件

你會抓到什麼

安裝與啟動

1. clone repo

2. 啟動 collector

3. 載入 Chrome extension

4. 安裝 skills（給 Claude Code 用）

使用

設定 capture filter

範例 1：只抓自家 API 的 POST（最常用）

範例 2：抓全站但排除靜態檔與第三方追蹤

範例 3：只抓 WebSocket

範例 4：抓兩個 host，且每個 host 限定 path

範例 5：排除某個吵的 endpoint，其餘 API 都收

從 CLI 設定（extension 每 5 秒會自動 sync 回來）

透過 Claude 查詢（web-log-parse）

等到特定封包出現再繼續（web-log-watch）

直接打 API

Retention / 記憶體控制

安全與隱私

開發者守則

疑難排解

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages