baoyu-url-to-markdown

URL 轉 Markdown

透過 baoyu-fetch CLI（Chrome CDP + 站點專用轉接器）擷取任何網址，並轉換為乾淨的 Markdown。

使用者輸入工具

當此技能提示使用者時，請依下列工具選用規則（優先順序）：

1. 優先使用內建的使用者輸入工具，由當前代理執行環境提供，例如 AskUserQuestion、request_user_input、clarify、ask_user 或任何等效工具。
2. 備援：若無此類工具，則發送編號的純文字訊息，要求使用者回覆每個問題的選擇編號或答案。
3. 批次處理：若工具支援單次呼叫多個問題，則將所有適用問題合併為一次呼叫；若僅支援單一問題，則依優先順序逐一詢問。

以下具體的 AskUserQuestion 參考僅為範例 — 請在其他執行環境中替換為當地等效工具。

CLI 設定

重要：CLI 原始碼已置於 {baseDir}/scripts/lib。scripts/package.json 僅安裝第三方執行時期依賴。

代理執行指示：

1. 確定此 SKILL.md 檔案所在的目錄路徑為 {baseDir}
2. 解析 ${BUN} 執行環境：若已安裝 bun → bun；否則建議安裝 Bun
3. 若 {baseDir}/scripts/node_modules 不存在，則執行 ${BUN} install --cwd {baseDir}/scripts
4. ${READER} = {baseDir}/scripts/baoyu-fetch
5. 將本文件中所有 ${READER} 替換為解析後的值

偏好設定（EXTEND.md）

依優先順序檢查 EXTEND.md — 第一個找到的生效：

優先順序	路徑	範圍
1	.baoyu-skills/baoyu-url-to-markdown/EXTEND.md	專案
2	${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-url-to-markdown/EXTEND.md	XDG
3	$HOME/.baoyu-skills/baoyu-url-to-markdown/EXTEND.md	使用者家目錄

結果	動作
找到	讀取、解析、套用設定
未找到	必須執行首次設定（見下方）— 請勿靜默建立預設值

EXTEND.md 支援：預設下載媒體、預設輸出目錄。

首次設定 ⛔ 阻塞

當 EXTEND.md 未找到時，你必須使用 AskUserQuestion 收集偏好設定，然後才建立 EXTEND.md。絕不以靜默預設值建立 EXTEND.md。產生過程會阻塞直到設定完成。將三個問題批次合併為一次呼叫：

• Q1 — 媒體（標題「媒體」）：「如何處理頁面中的圖片與影片？」
  • 「每次詢問（建議）」— 每次儲存後提示
  • 「一律下載」— 下載至本機 imgs/ 和 videos/
  • 「絕不下載」— 保留遠端網址
• Q2 — 輸出（標題「輸出」）：「預設輸出目錄？」
  • 「url-to-markdown（建議）」— 儲存至 ./url-to-markdown/{domain}/{slug}.md
  • 使用者可選擇「其他」並輸入自訂路徑
• Q3 — 儲存（標題「儲存」）：「偏好設定儲存位置？」
  • 「使用者（建議）」— ~/.baoyu-skills/（所有專案）
  • 「專案」— .baoyu-skills/（僅此專案）

回答後，寫入 EXTEND.md，確認「偏好設定已儲存至 [路徑]」，然後繼續。

完整範本：references/config/first-time-setup.md。

支援的鍵值

鍵	預設值	值	說明
download_media	ask	ask / 1 / 0	ask = 每次提示，1 = 一律下載，0 = 絕不下載
default_output_dir	空	路徑或空	預設輸出目錄（空 = ./url-to-markdown/）

EXTEND.md → CLI 對應：

EXTEND.md 鍵	CLI 參數	備註
download_media: 1	--download-media	需同時設定 --output
default_output_dir: ./posts/	代理建構 --output ./posts/{domain}/{slug}.md	代理產生路徑，非直接旗標

值優先順序：CLI 參數 → EXTEND.md → 技能預設值。

使用方式

# 預設：無頭模式擷取，Markdown 輸出至 stdout
${READER} <url>

# 儲存至檔案
${READER} <url> --output article.md

# 儲存並下載媒體
${READER} <url> --output article.md --download-media

# 等待互動（登入/CAPTCHA）— 自動偵測並繼續
${READER} <url> --wait-for interaction --output article.md

# 等待互動 — 手動控制（按 Enter 繼續）
${READER} <url> --wait-for force --output article.md

# JSON 輸出
${READER} <url> --format json --output article.json

# 強制指定轉接器
${READER} <url> --adapter youtube --output transcript.md

選項

選項	說明
<url>	要擷取的網址
--output <path>	輸出檔案路徑（預設：stdout）
--format <type>	輸出格式：markdown（預設）或 json
--json	--format json 的簡寫
--adapter <name>	強制轉接器：x、youtube、hn 或 generic（預設：自動偵測）
--headless	強制無頭模式 Chrome（不顯示視窗）
--wait-for <mode>	互動等待模式：none（預設）、interaction 或 force
--wait-for-interaction	--wait-for interaction 的別名
--wait-for-login	--wait-for interaction 的別名
--timeout <ms>	頁面載入逾時（預設：30000）
--interaction-timeout <ms>	登入/CAPTCHA 等待逾時（預設：600000 = 10 分鐘）
--interaction-poll-interval <ms>	互動檢查輪詢間隔（預設：1500）
--download-media	下載圖片/影片至本機 imgs/ 和 videos/，並改寫 Markdown 連結。需搭配 --output
--media-dir <dir>	下載媒體的基礎目錄（預設：與 --output 目錄相同）
--cdp-url <url>	重複使用現有的 Chrome DevTools Protocol 端點
--browser-path <path>	自訂 Chrome/Chromium 執行檔路徑
--chrome-profile-dir <path>	Chrome 使用者資料目錄（預設：BAOYU_CHROME_PROFILE_DIR 環境變數或 ./baoyu-skills/chrome-profile）
--debug-dir <dir>	寫入除錯產出（document.json、markdown.md、page.html、network.json）

代理品質閘門

關鍵：將預設的無頭模式擷取視為暫定結果。某些網站在無頭模式下呈現不同，可能靜默回傳低品質內容而不會導致 CLI 失敗。

每次無頭模式執行後，請檢查儲存的 Markdown。完整檢查清單、復原工作流程及擷取模式表格請參閱 references/quality-gate.md。當執行結果可疑或使用者詢問登入/CAPTCHA 處理時，請務必閱讀。

輸出路徑產生

代理必須建構輸出檔案路徑 — baoyu-fetch 不會自動產生路徑。

演算法：

1. 從 EXTEND.md 的 default_output_dir 或預設 ./url-to-markdown/ 決定基礎目錄
2. 從網址中提取網域（例如 example.com）
3. 從網址路徑或頁面標題產生 slug（kebab-case，2-6 個單詞）
4. 建構：{base_dir}/{domain}/{slug}/{slug}.md — 每個網址有獨立目錄，媒體檔案保持隔離
5. 衝突解決：附加時間戳 {slug}-YYYYMMDD-HHMMSS/{slug}-YYYYMMDD-HHMMSS.md

將建構的路徑傳遞給 --output。媒體檔案（--download-media）會儲存在 Markdown 檔案旁的子目錄中，保持每個網址的資產獨立。

轉接器與媒體

請參閱 references/adapters.md 了解轉接器目錄（X、YouTube、Hacker News、通用）、各轉接器備註、媒體下載流程（ask / 一律 / 絕不）以及 JSON 輸出結構。在回答轉接器相關問題或處理媒體提示前，請先閱讀。

環境變數

變數	說明
BAOYU_CHROME_PROFILE_DIR	Chrome 使用者資料目錄（亦可使用 --chrome-profile-dir）

疑難排解：找不到 Chrome → 使用 --browser-path。逾時 → 增加 --timeout。登入/CAPTCHA → --wait-for interaction。除錯 → 使用 --debug-dir 檢查擷取的 HTML 和網路記錄。

擴充支援

透過 EXTEND.md 自訂設定。路徑與支援的鍵值請參閱上方偏好設定章節。