soia-pkm-clip-x
把 X 上有價值的內容沉澱到 Obsidian vault，構建可檢索的知識資產。
定位
X 的原生 UI 不利於長期回看：thread 散在時間線、Article 排版亂、連結易失效、搜尋弱。本 skill 把 X 上的優質長內容一鍵沉澱進 Obsidian：
- thread 完整 unroll
- X Article 取全量
content.blocks - 元數據齊全（作者、metrics、媒體直鏈、created_at）
- frontmatter 主題雙鏈，方便 MOC 聚合
- 多語言識別（zh / en / ja / ko）
前置依賴
-
Obsidian vault（任意結構）
-
Python 3，純 stdlib（無第三方依賴，歸檔單條推文）
-
可選：
pip install telethon（僅 MTProto 同步用） -
設置環境變數：
export OBSIDIAN_VAULT=~/Documents/MyVault # 可選：自定義歸檔子目錄（預設 "Articles"） export OBSIDIAN_ARTICLES="Articles" # 可選：段標題語言，預設 zh（中文），設 en 用英文標題 export X_ARCHIVE_LANG=zh
核心 API：fxtwitter
把 X URL 裡的 x.com 換成 api.fxtwitter.com，直接 GET 回 JSON。無需 X API key、無需登入、零成本。
| 關鍵欄位 | 用途 |
|---|---|
tweet.text / tweet.raw_text.text | 推文正文 |
tweet.article.title | X Article 標題 |
tweet.article.content.blocks[] | Article 長文 blocks |
tweet.replying_to_status | 上一條推文（thread 回溯） |
tweet.quote | 引用的推文 |
tweet.media[] | 媒體（圖/影片直鏈） |
tweet.created_timestamp | UNIX 時間戳 |
tweet.views / likes / bookmarks / retweets | metrics |
兜底：fxtwitter 失敗 → cdn.syndication.twimg.com 公開端點。
觸發詞
| 使用者說 | 呼叫 |
|---|---|
| 「歸檔這條 X：URL」 / 「archive this：URL」 | archive_x.py <URL>，非中文內容預設自動補譯文（見下方工作流第 4 步），不用額外說「翻譯」 |
| 「整理一下這條 thread：URL」 | 同上，強制 thread 回溯 |
| 「同步我的電報收藏」 + 給 JSON 路徑 | sync_telegram_export.py <path> --dry-run 先看，確認後實跑 |
| 「用 API 同步電報」（已有憑證） | sync_telegram_saved.py |
工作流（預設歸檔）
- 解析 URL → handle + status_id
- 調腳本
archive_x.py <URL> - 腳本檢查 vault 是否已歸檔（按 frontmatter
url:欄位）- 已存在 → 輸出 SKIP，退出
- 否則 → 抓 fxtwitter，寫入 vault
- AI 之後補：
- 1 句話中文
## 摘要 - 1-3 個
topics雙鏈 +people雙鏈 - 非中文內容（
language不是 zh）：預設把## 中文譯文段補成完整譯文，不用使用者額外說「翻譯」。要求意譯不直譯——讀起來要像人寫的中文，不是機器翻譯腔；專有名詞、產品名、程式碼/指令/API 參數保留英文原文，只翻譯敘述性文字和說明
- 1 句話中文
- 「我的看法」段永遠留空給使用者
Telegram 同步兩條路徑
A. JSON 匯出（推薦，零風險）
Telegram Desktop
→ Settings → Advanced → Export Telegram data
→ 勾「私聊」+ 選 JSON 格式
→ 得到 result.json
python3 sync_telegram_export.py <result.json> --dry-run # 看清單
python3 sync_telegram_export.py <result.json> # 實跑
自動按 URL 去重、自動跳過已歸檔。每月匯出一次即可增量同步。
B. MTProto API（高階，國內慎用）
需要：
https://my.telegram.org/auth申請 api_id / api_hash- 跑
generate_telegram_session.py拿 session_string - 住宅 IP（中國大陸使用者必須 HK/JP 住宅段，機房 IP 必觸發 ERROR）
⚠️ 國內使用者優先使用方案 A。my.telegram.org 建立 app 在大陸幾乎必踩 IP 風控，反覆嘗試會觸發帳號級 24-72h 凍結。
檔案命名
<YYYY-MM-DD>-X-<handle>-<title前 50 字>.md
例：
2026-05-24-X-cyrilXBT-How-to-Organize-Your-Obsidian-Vault.md2026-05-29-X-ObsidianOtaku-保存版AIエージェントのためのObsidian活用術.md
同日同作者多條 → 末尾加 -<status_id 後 6 位>。
輸出 frontmatter
---
tags: [文章摘抄]
source: X
url: https://x.com/<handle>/status/<id>
author: <顯示名>
handle: "@<handle>"
published_at: YYYY-MM-DD HH:mm
captured_at: YYYY-MM-DD HH:mm
language: zh / en / ja / ko
type: tweet / thread / article
topics: ["[[xxx]]", ...] # AI 填
people: ["[[xxx]]", ...] # AI 填
media: [...] / 0
content_complete: true
metrics:
views: N
likes: N
bookmarks: N
---
邊界與異常
| 場景 | 處理 |
|---|---|
| fxtwitter 返回 404 | 推文被刪/私密，建議查 archive.org |
| fxtwitter 5xx | 重試 1 次，失敗兜底 syndication 端點 |
| URL 非 x.com / twitter.com | 拒絕，建議用 Web Clipper |
| 推文文字空且無 article 且無 media | 警告：「純轉推/純回覆，可能無獨立內容」 |
| 同日同作者檔名重複 | 末尾加 -<status_id 後 6 位> |
| 影片媒體 | frontmatter media[] 記 mp4 直鏈，不內嵌 |
命令列參考
# 歸檔單條
python3 archive_x.py <URL>
python3 archive_x.py <URL> --force # 覆蓋已歸檔
python3 archive_x.py <URL> --vault /path/to/vault # 覆蓋環境變數
# Telegram JSON 匯出同步
python3 sync_telegram_export.py <result.json>
python3 sync_telegram_export.py <result.json> --dry-run
python3 sync_telegram_export.py <result.json> --since 2026-06-01
python3 sync_telegram_export.py <result.json> --limit 30
# MTProto 同步（需先 setup）
python3 generate_telegram_session.py # 一次性
python3 sync_telegram_saved.py --dry-run
python3 sync_telegram_saved.py --days 30
python3 sync_telegram_saved.py --all