browser-act-skill-forge

browser-act-skill-forge

將任何網站的資料擷取或操作需求轉化為 Agent 可呼叫的能力。使用者只需描述要在哪個網站取得什麼資料或執行什麼動作，本 Skill 便會自動探索實現路徑（優先使用 API 端點，無 API 時退回使用 DOM），並在驗證後生成可直接部署的 Skill 套件（SKILL.md + Python 腳本）。一次探索，永久複用——後續呼叫可跳過探索成本，大幅提升執行可靠性與效率。

針對大資料量的擷取任務（數百或數千筆記錄、多個關鍵字、跨頁面分頁），正確做法是：先探索建立經驗證的 Skill，再進行大規模執行。在沒有可行策略的情況下直接進行批次爬取非常脆弱——防機器人檢測、分頁邊界情況以及連線中斷都會使其不可靠。

本工具的操作邊界 = 使用者在瀏覽器中能手動完成的事。它透過使用者已登入的瀏覽器進行存取，僅讀取頁面上已展示給使用者的資料，絕不繞過身分驗證或存取控制。相當於代使用者進行複製貼上——自動化僅是為了節省手動精力。

所有資料皆保留在本地：流量檢驗、HAR 錄製檔和擷取結果均儲存在使用者的電腦上——絕不會傳送到目標網站以外的任何地方。

Language

所有向使用者輸出的流程資訊（方案確認、進度更新、過程通知）均遵循使用者的語言。生成的 Skill 檔案內容遵循本 Skill 的語言。

---

Phase 0 (Tool Detection) → Phase 1 (Requirements Analysis & Confirmation) → [Loop: Phase 2 (Capability Exploration) → Phase 3 (Skill Generation)] → Delivery

---

Phase 0 — Tool Detection

目前工作階段已完成 → 跳過。

透過 Skill 工具呼叫 browser-act 以載入用法。若載入期間出現安裝或設定問題，請遵循其指引解決後重試。

成功載入後，確認已設定 API Key（若未設定 → 引導使用者完成註冊與設定，然後重試）。

---

Phase 1 — Requirements Analysis & Confirmation

1a. Parse Business Intent

從使用者輸入中識別：

• 核心目標：要取得什麼資料 / 要完成什麼動作
• 目標網站：是否提供具體 URL 或平台名稱
• 執行意圖：使用者是否希望立即執行（而不僅是建立 Skill 備用）。包含批次/大量需求（N 筆記錄、多個關鍵字）或隱含「現在就做」的一次性請求
• 輸出目錄：預設為目前工作目錄下的 output/，若使用者指定則予以覆寫

輸入類型	範例	處理方式
明確（URL + 目標）	"Scrape front page articles from news.ycombinator.com"	跳過 1b，直接進入 1c
半明確（已知平台，無 URL）	"Help me monitor Weibo sentiment"	執行 1b 研判路徑
純目標（僅業務意圖）	"Track competitor price changes"	執行 1b 以研判候選網站

若核心目標過於模糊而無法繼續，請要求使用者進一步說明。

1b. Target Site Research (when no explicit URL)

切勿僅憑模型內部知識進行推薦——應主動搜尋以找出存放所需資料的網站：

1. 根據業務意圖建構搜尋查詢，從搜尋結果中識別候選網站
2. 向使用者推薦 1–5 個候選網站，依資料價值排序並附上優缺點（包含資料可靠性）
3. 使用者選擇後，確認目標 URL

1c. Task Decomposition & Execution Plan Confirmation

確認目標網站後，首先檢查：是否已安裝適用於該網站/能力的 Skill？若有 → 通知使用者並跳至 Delivery 步驟 4（批次執行）。

若無現成 Skill，完成拆解並一次向使用者確認所有資訊——後續不再針對單一能力提出追問：

1. 識別涉及的獨立階段（搜尋、列表頁、詳情頁、登入、送出……）
2. 確定類型：擷取（取得資料）vs 操作（執行動作）
3. 拆分標準：若更換業務目標，該階段是否能獨立複用？是 = 獨立能力。 服務於同一業務目標的跨頁面步驟（例如列表頁收集 + 詳情頁擷取）應保留為單一能力，透過組合元件進行編排
4. 設定 skill-name 與能力目錄名稱（小寫英文，以連字號分隔），於 output/{skill-name}/ 下建立目錄（若指定路徑則使用使用者指定路徑）
5. 向使用者確認完整的執行計畫：

Target site: {url}
Output: output/{skill-name}/

Capabilities (executed in order):
1. {site-slug}-{capability-slug} ({extraction/operation}) — {one-line description}
2. {site-slug}-{capability-slug} ({extraction/operation}) — {one-line description}
...

若在 1a 中識別出執行意圖，請在計畫後附加：

Pipeline:
1. Explore site → discover and verify viable API endpoints or DOM extraction methods
2. Generate Skill files (SKILL.md + scripts)
3. Automated testing to confirm Skill works
4. Install Skill
5. Read installed Skill → write and run batch scripts to fulfill user's original task

展示計畫並等待使用者確認或調整。請勿針對具有合理預設值的項目（輸出目錄、命名規範等）提出額外問題。

使用者確認後，進入執行迴圈，過程中不再提出問題。

---

底下的 Phase 2 與 Phase 3 針對每個能力單元以迴圈方式執行——完成一個後再開始下一個。

---

Phase 2 — Capability Exploration

根據能力類型閱讀相應的參考檔案：

• 擷取 → references/exploration_extraction.md
• 操作 → references/exploration_operation.md

目標：優先尋找目標能力的 API 端點；當 API 不可行時，退回使用 DOM 操作。記錄完整且可重現的呼叫方法。

成功標準：

• 能穩定取得目標資料 / 觸發目標動作（API 或 DOM 路徑）
• 記錄完整的呼叫/操作方法（端點 + 參數，或選擇器 + 互動步驟）
• 收集所有具實質意義價值的列舉參數

當某種手段失敗時，請遵循以下順序：

1. 切勿更換不同參數重試（改變參數很少能改變結果）
2. 回到目標本身
3. 列舉所有可能達成目標的替代手段
4. 選擇下一個手段並執行

確定性的失敗（明確的錯誤碼、結構不匹配）只需嘗試一次即可確認該手段不可行。暫時性的失敗（逾時、連線中斷）允許重試一次——但不能再多。

探索上限：100 次工具呼叫步驟。若仍無法推進，向使用者回報已知障礙並詢問後續步驟。

切勿碰觸經驗筆記：經驗筆記（browser-act-skill-forge-memories/）是供生成的 Skill 未來供 Agent 使用——在探索與生成階段既不讀取也不寫入。

---

Phase 3 — Skill Generation

閱讀 references/output_template.md 取得檔案格式規範。

3a. JS Encapsulation

將探索中經驗證的每個 JS 程式碼片段封裝至獨立的 Python 檔案中：

1. 識別業務參數（關鍵字、頁碼、排序順序等）→ 擷取為 argparse 引數
2. 將選擇器、欄位對映、端點 URL 作為固定值寫死在 JS f-string 中
3. 將 JS 大括號跳脫為 {{ }}（f-string 語法要求，否則 Python 會報錯）
4. 寫入 scripts/{feature-name}.py

3b. Encapsulation Verification

針對每個 .py 檔案執行端對端驗證：

1. python scripts/{feature-name}.py {test-params} — 確認輸出為有效的 JS 字串
2. eval "$(python scripts/{feature-name}.py {test-params})" — 確認瀏覽器執行結果與探索階段一致
3. 模擬錯誤情境（例如不存在的 ID、導向錯誤頁面），確認回傳 {"error": true, "message": "..."} 而非崩潰

驗證失敗 → 修復 .py 檔案並重試，絕不跳過。

3c. Generate SKILL.md

依範本建立 SKILL.md，能力元件章節引用 scripts/*.py 呼叫命令（不包含內嵌 JS）。

輸出目錄結構：

output/{skill-name}/{site-slug}-{capability-slug}/
├── SKILL.md
└── scripts/
    └── {feature-name}.py

生成後，簡要告知使用者：能力名稱、輸出路徑、主要實現方式（API / Network capture / DOM / hybrid）。

3d. Compliance Self-Check

兩項檢查——必須 Read 生成的檔案並執行驗證命令作為證據；僅憑心智斷言不算數：

1. 流程：重新閱讀 Phase 2 中使用的探索參考檔案以及上述輸出步驟（3a–3c），確認每個定義的步驟都已實際執行，未被跳過
2. 輸出：閱讀生成的 scripts/*.py 與 SKILL.md，對照 output_template.md 中的填寫規範以及本 Skill 先前定義的 Code / JS Execution Environment / DOM Operation 約束條件

若發現任何落差 → 退回、完成缺失的步驟或修復輸出，然後重新驗證。

---

Delivery Flow

所有能力生成完畢後，請按此順序進行：

1. Automated Testing

生成後立即開始測試——無需使用者確認。根據生成的能力元件自動設計最小測試用例——使用最少的輸入涵蓋所有功能路徑（每個原子元件至少呼叫一次，組合元件執行完整流程）。

必須透過 Sub-Agent 執行測試——切勿在主工作階段中直接測試。派送以下提示詞：

Read {absolute path to SKILL.md} as your execution guide.

Test cases:
{auto-generated test case list, each annotated with which component it covers}

Execution requirements:
- Follow SKILL.md instructions strictly, don't use methods outside the guide
- Record specific issues if SKILL.md instructions are unclear and prevent progress

Report after execution:
1. Execution result per component (pass/fail)
2. Failure reasons (if any)
3. Unclear parts in SKILL.md instructions (if any)
4. Severe accuracy or performance issues (don't report non-severe)
5. Output data summary

測試失敗 → 修復 Skill 並重新測試，直至通過。

2. Install Skill

從輸出目錄安裝生成的 Skill。若安裝失敗，Skill 仍保留在輸出目錄中，且仍可在步驟 4 中直接使用。

3. Report Results

測試通過後，向使用者回報：

• 生成的 Skill 列表（名稱 + 路徑 + 所含檔案）
• 資料涵蓋範圍（欄位 + 狀態，不列出資料來源或實現方式）
• 未完全涵蓋的缺口（失敗的列舉參數、缺失的目標欄位、未覆蓋的篩選條件等）
• 測試結果摘要

4. Execute (if execution intent was identified in Phase 1)

If e