opencli-browser-sitemap

opencli-browser-sitemap

當 opencli browser open 或 opencli browser analyze 回傳 sitemap.available: true，或是使用者要求使用網站的 sitemap 時，請使用此 Skill。

Sitemap 屬於先驗知識，而非最終事實。它的作用是減少盲目點擊，但絕不可凌駕於瀏覽器的實時狀態之上。

---

Consumption Loop

1. 執行或重複使用 opencli browser <session> state 以取得當前頁面狀態。
2. 僅讀取最小限度的相關 sitemap 檔案：
   • SITE.md：用於整體網站定位與概觀。
   • 對應當前狀態的 pages/<page-id>.md。
   • 對應使用者目標的 workflows/<task-id>.md。
   • 僅在遭遇阻礙或工作流發出警告時，才讀取 pitfalls.md。
3. 優先採用工作流中的 Best path。若其中指定了轉接器（如 opencli twitter post），請優先使用該指令，而非直接進行原生瀏覽器操作。
4. 若轉接器不可用或執行失敗，請切換至 Fallback path 的瀏覽器工作流。
5. 每次完成導覽或變更狀態的操作後，重新整理 state 並比對工作流的 state_signature。
6. 若實際情況與預期不符，應以實際頁面為準，繼續探索，並在在地端撰寫過期註記（stale note）或草稿修補（draft patch）。
7. 若操作復原程序包含 adapter_health_update: <adapter> -> suspect|broken，請更新引用該轉接器的在地覆蓋工作流（local overlay workflow），讓後續 Agent 能直接走 fallback 路徑。

---

Lookup Order

先讀取在地覆蓋檔（local overlay），再讀取全域種子檔（global seed）：

~/.opencli/sites/<site>/sitemap/    # 在地覆蓋檔 (local overlay)
sitemaps/<site>/                    # 全域種子檔 (repo seed，頂層)

若檔案具備相同的穩定 ID，在地檔案的優先權高於全域檔案。

切勿將大型 sitemap 完整載入上下文。若目錄檔案過多，請先列出檔名，再僅讀取需要的頁面或工作流。

---

Trust Reality Rule

若 sitemap 標示某個按鈕、URL、路由或 API 應該存在，但瀏覽器畫面上卻未顯示：

• 重新執行帶有語意錨點（semantic anchors）的 state 或 find。
• 檢查登入狀態、語系（locale）、視埠（viewport）、A/B 測試或路由狀態是否有差異。
• 只要有安全的路徑可循，就以實際頁面為準繼續操作。
• 在在地覆蓋檔中，將該 sitemap 項目標記為過期（stale）。

絕不要因為「sitemap 寫著應該可行」就盲目持續點擊。

---

Stale / Draft Notes

當你發現資料偏差（drift）時，請在相關頁面/工作流檔案下方，或在地覆蓋目錄中的草稿檔寫入簡短的在地註記：

Stale note:
- observed_at: YYYY-MM-DD
- current_url:
- expected:
- actual:
- next_probe:

除非目前的任務明確要求撰寫 sitemap 或提交 repo PR，否則切勿直接修改全域種子檔案。

Adapter Health Write-Back

當轉接器執行失敗，且 sitemap 的操作或工作流指示你更新轉接器健康狀態時：

1. 在 ~/.opencli/sites/<site>/sitemap/workflows/ 下找到其 Best path 引用該轉接器指令的在地工作流檔案。
2. 若在地工作流不存在，請先將對應的全域工作流複製到在地覆蓋目錄中；在執行瀏覽器任務期間，絕不要直接編輯全域種子檔。
3. 依指示將 adapter_health 設定為 suspect 或 broken。
4. 新增簡短的過期註記，包含觀察到的錯誤、當前 URL 及時間戳記。
5. 繼續執行瀏覽器的備用路徑（fallback path）。

此回寫機制構成了記憶循環：當前 Agent 只需回退一次，後續 Agent 就不會浪費回合去重試已知有疑慮的轉接器。

---

Output Discipline

回報進度時，內容應包含：

• 所選路徑：轉接器最佳路徑（adapter best path）或瀏覽器備用路徑（browser fallback）。
• 達成的檢查點：當前 URL / 狀態簽章（state signature）。
• Sitemap 健康狀況：原樣使用（used as-is）、已標記過期（stale marked）或缺少工作流（missing workflow）。

請保持回報內容聚焦於任務本身，切勿摘要整份 sitemap。