baoyu-danger-x-to-markdown

X to Markdown

將 X 內容轉換為 Markdown：

• 推文/串文 → 帶有 YAML 前置資料的 Markdown
• X 文章 → 完整內容擷取

使用者輸入工具

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

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

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

腳本目錄

腳本位於 scripts/ 子目錄中。

路徑解析：

1. {baseDir} = 此 SKILL.md 所在的目錄
2. 腳本路徑 = {baseDir}/scripts/main.ts
3. 解析 ${BUN_X} 執行環境：如果已安裝 bun → bun；如果可用 npx → npx -y bun；否則建議安裝 bun

同意要求

在進行任何轉換之前，檢查並取得同意。

同意流程

步驟 1：檢查同意檔案

# macOS
cat ~/Library/Application\ Support/baoyu-skills/x-to-markdown/consent.json

# Linux
cat ~/.local/share/baoyu-skills/x-to-markdown/consent.json

步驟 2：如果 accepted: true 且 disclaimerVersion: "1.0" → 顯示警告並繼續：

警告：使用逆向工程 X API。接受日期：<acceptedAt>

步驟 3：如果缺少或版本不符 → 顯示免責聲明：

免責聲明

此工具使用逆向工程的 X API，非官方 API。

風險：
- 若 X 變更 API 可能失效
- 不提供任何保證或支援
- 可能導致帳號限制
- 使用風險自負

接受條款並繼續？

使用 AskUserQuestion 搭配選項：「是，我接受」|「否，我拒絕」

步驟 4：接受後 → 建立同意檔案：

{
  "version": 1,
  "accepted": true,
  "acceptedAt": "<ISO 時間戳>",
  "disclaimerVersion": "1.0"
}

步驟 5：拒絕後 → 輸出「使用者拒絕。結束。」並停止。

偏好設定（EXTEND.md）

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

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

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

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

首次設定（阻塞操作）

關鍵：當未找到 EXTEND.md 時，你必須使用 AskUserQuestion 詢問使用者偏好，然後再建立 EXTEND.md。絕對不要在未詢問的情況下使用預設值建立 EXTEND.md。這是阻塞操作 — 在設定完成之前，不得進行任何轉換。

使用 AskUserQuestion 在一次呼叫中提出所有問題：

問題 1 — 標題：「媒體」，問題：「如何處理推文中的圖片和影片？」

• 「每次詢問（建議）」— 儲存 Markdown 後，詢問是否下載媒體
• 「總是下載」— 總是將媒體下載到本機 imgs/ 和 videos/ 目錄
• 「從不下載」— 在 Markdown 中保留原始遠端網址

問題 2 — 標題：「輸出」，問題：「預設輸出目錄？」

• 「x-to-markdown（建議）」— 儲存到 ./x-to-markdown/{username}/{tweet-id}.md
• （使用者可選擇「其他」來輸入自訂路徑）

問題 3 — 標題：「儲存」，問題：「偏好設定儲存位置？」

• 「使用者（建議）」— ~/.baoyu-skills/（所有專案）
• 「專案」— .baoyu-skills/（僅此專案）

使用者回答後，在選擇的位置建立 EXTEND.md，確認「偏好設定已儲存至 [路徑]」，然後繼續。

完整參考：references/config/first-time-setup.md

支援的鍵值

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

值優先順序：

1. CLI 參數（--download-media、-o）
2. EXTEND.md
3. 技能預設值

使用方式

${BUN_X} {baseDir}/scripts/main.ts <url>
${BUN_X} {baseDir}/scripts/main.ts <url> -o output.md
${BUN_X} {baseDir}/scripts/main.ts <url> --download-media
${BUN_X} {baseDir}/scripts/main.ts <url> --json

選項

選項	說明
<url>	推文或文章網址
-o <path>	輸出路徑
--json	JSON 輸出
--download-media	將圖片/影片資源下載到本機 imgs/ 和 videos/，並將 Markdown 連結改寫為本機相對路徑
--login	僅重新整理 Cookie

支援的網址

• https://x.com/<user>/status/<id>
• https://twitter.com/<user>/status/<id>
• https://x.com/i/article/<id>

輸出

---
url: "https://x.com/user/status/123"
author: "Name (@user)"
tweetCount: 3
coverImage: "https://pbs.twimg.com/media/example.jpg"
---

內容...

檔案結構：x-to-markdown/{username}/{tweet-id}/{content-slug}.md

啟用 --download-media 時：

• 圖片儲存到 Markdown 檔案旁的 imgs/
• 影片儲存到 Markdown 檔案旁的 videos/
• Markdown 媒體連結改寫為本機相對路徑

媒體下載流程

根據 EXTEND.md 中的 download_media 設定：

設定	行為
1（總是）	使用 --download-media 標記執行腳本
0（從不）	不使用 --download-media 標記執行腳本
ask（預設）	遵循下方的每次詢問流程

每次詢問流程

1. 不帶 --download-media 執行腳本 → 儲存 Markdown
2. 檢查儲存的 Markdown 中是否有遠端媒體網址（圖片/影片連結中的 https://）
3. 如果未找到遠端媒體 → 完成，無需提示
4. 如果找到遠端媒體 → 使用 AskUserQuestion：
   • 標題：「媒體」，問題：「下載 N 個圖片/影片到本機檔案？」
   • 「是」— 下載到本機目錄
   • 「否」— 保留遠端網址
5. 如果使用者確認 → 再次使用 --download-media 執行腳本（覆寫 Markdown 為本機連結）

驗證

1. 環境變數（建議）：X_AUTH_TOKEN、X_CT0
2. Chrome 登入（備用）：自動開啟 Chrome，在本機快取 Cookie

擴充支援

透過 EXTEND.md 進行自訂設定。請參閱偏好設定章節了解路徑和支援的選項。