soia-pkm-clip-x

Que fait soia-pkm-clip-x ?

Capturez le contenu de valeur sur X et versez-le dans votre coffre Obsidian pour construire des connaissances réutilisables.

Positionnement

L'interface native de X n'est pas adaptée à une relecture à long terme : les threads se perdent dans la timeline, la mise en page des articles est confuse, les liens se brisent et la recherche est faible. Ce skill permet d'archiver en un clic le meilleur contenu long de X dans Obsidian :

• déroulement complet des threads
• extraction intégrale du content.blocks des X Articles
• métadonnées complètes (auteur, métriques, liens directs média, created_at)
• frontmatter et liens bidirectionnels vers les topics, pour une agrégation facile via MOC
• détection multilingue (zh / en / ja / ko)

Prérequis

• Un coffre Obsidian (structure libre)

• Python 3, avec stdlib uniquement (aucune dépendance tierce pour un tweet simple)

• Optionnel : pip install telethon (uniquement pour la synchro MTProto)

• Définir les variables d'environnement :

  export OBSIDIAN_VAULT=~/Documents/MonCoffre
  # Optionnel : sous-répertoire d'archivage (par défaut "Articles")
  export OBSIDIAN_ARTICLES="Articles"
  # Optionnel : langue des titres de section, par défaut zh (chinois), mettre en pour titres en anglais
  export X_ARCHIVE_LANG=zh
  

API principale : fxtwitter

Remplacez x.com par api.fxtwitter.com dans l'URL X, et faites un GET pour obtenir du JSON. Pas de clé d'API X, pas de connexion, zéro coût.

Champ clé	Usage
tweet.text / tweet.raw_text.text	Corps du tweet
tweet.article.title	Titre de l'article X
tweet.article.content.blocks[]	Blocs de texte long de l'article
tweet.replying_to_status	Tweet précédent (remontée de thread)
tweet.quote	Tweet cité
tweet.media[]	Médias (liens directs image/vidéo)
tweet.created_timestamp	Timestamp UNIX
tweet.views / likes / bookmarks / retweets	Métriques

Fallback : si fxtwitter échoue → endpoint public cdn.syndication.twimg.com.

Mots déclencheurs

Ce que dit l'utilisateur	Action
« Archive ce X : URL » / « archive this : URL »	archive_x.py <URL>. Pour les contenus non chinois, une traduction complète est ajoutée automatiquement (voir étape 4 du workflow ci-dessous), sans avoir à demander « traduis ».
« Déroule ce thread : URL »	Idem, forcer la remontée du thread
« Synchronise mes messages Telegram sauvegardés » + chemin JSON	sync_telegram_export.py <path> --dry-run pour prévisualiser, puis exécution après confirmation
« Synchronise Telegram via API » (si déjà configuré)	sync_telegram_saved.py

Workflow (archivage par défaut)

1. Analyser l'URL → handle + status_id
2. Lancer le script archive_x.py <URL>
3. Le script vérifie si l'URL existe déjà dans le coffre (via le champ url: du frontmatter)
   • Déjà présent → affiche SKIP, sortie
   • Sinon → récupère fxtwitter, écrit dans le coffre
4. L'IA ajoute ensuite :
   • 1 phrase de résumé en chinois sous ## 摘要
   • 1 à 3 liens bidirectionnels topics + people
   • Contenu non chinois (quand language n'est pas zh) : traduire intégralement le texte en chinois sous la section ## 中文译文, sans que l'utilisateur ait à demander « traduis ». Exiger une traduction idiomatique, pas littérale — le résultat doit sembler écrit par un humain, sans aura de traduction automatique ; les noms propres, noms de produits, code/commandes/paramètres d'API restent en anglais, seuls les textes narratifs et explicatifs sont traduits.
5. La section « Mon avis » reste toujours vide, à la main de l'utilisateur

Synchronisation Telegram : deux méthodes

A. Export JSON (recommandé, zéro risque)

Telegram Desktop
  → Paramètres → Avancé → Exporter les données Telegram
  → Cocher « Discussions privées » + choisir le format JSON
  → Obtenir le fichier result.json

python3 sync_telegram_export.py <result.json> --dry-run   # Voir la liste
python3 sync_telegram_export.py <result.json>             # Exécuter

Déduplication automatique par URL, ignore les contenus déjà archivés. Une exportation par mois suffit pour une synchronisation incrémentale.

B. API MTProto (avancé, à utiliser avec prudence en Chine)

Nécessite :

• Aller sur https://my.telegram.org/auth pour obtenir api_id / api_hash
• Lancer generate_telegram_session.py pour obtenir la session_string
• Une IP résidentielle (les utilisateurs en Chine continentale doivent utiliser une IP résidentielle HK/JP ; les IP de datacenter déclenchent obligatoirement une ERREUR)

⚠️ Les utilisateurs chinois privilégient la méthode A. Créer une application sur my.telegram.org depuis la Chine continentale déclenche presque à coup sûr le filtrage IP, et les tentatives répétées peuvent geler le compte pendant 24 à 72 heures.

Nommage des fichiers

<YYYY-MM-DD>-X-<handle>-<50 premiers caractères du titre>.md

Exemples :

• 2026-05-24-X-cyrilXBT-Comment-Organiser-Votre-Coffre-Obsidian.md
• 2026-05-29-X-ObsidianOtaku-保存版AIエージェントのためのObsidian活用術.md

Pour plusieurs entrées du même auteur le même jour → ajouter -<6 derniers caractères du status_id> à la fin.

Frontmatter de sortie

---
tags: [文章摘抄]
source: X
url: https://x.com/<handle>/status/<id>
author: <Nom affiché>
handle: "@<handle>"
published_at: AAAA-MM-JJ HH:mm
captured_at: AAAA-MM-JJ HH:mm
language: zh / en / ja / ko
type: tweet / thread / article
topics: ["[[xxx]]", ...]   # Rempli par l'IA
people: ["[[xxx]]", ...]   # Rempli par l'IA
media: [...] / 0
content_complete: true
metrics:
  views: N
  likes: N
  bookmarks: N
---

Limites et exceptions

Scénario	Traitement
fxtwitter retourne 404	Tweet supprimé/privé → suggérer archive.org
fxtwitter 5xx	Réessayer 1 fois, fallback sur l'endpoint syndication
URL non x.com / twitter.com	Refus, suggérer un Web Clipper
Texte du tweet vide, pas d'article, pas de média	Avertir : « Simple retweet / simple réponse, peut-être sans contenu propre »
Nom de fichier en conflit (même auteur, même jour)	Ajouter -<6 derniers caractères du status_id> en fin
Vidéo média	Noter le lien mp4 dans le frontmatter media[], sans intégration

Référence en ligne de commande

# Archiver un tweet simple
python3 archive_x.py <URL>
python3 archive_x.py <URL> --force                  # Écraser un archivage existant
python3 archive_x.py <URL> --vault /chemin/vers/coffre   # Surcharger la variable d'environnement

# Synchronisation export JSON Telegram
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

# Synchro MTProto (nécessite configuration préalable)
python3 generate_telegram_session.py    # Une fois
python3 sync_telegram_saved.py --dry-run
python3 sync_telegram_saved.py --days 30
python3 sync_telegram_saved.py --all