soia-pkm-clip-x

O que soia-pkm-clip-x faz?

Arquive o conteúdo valioso do X em seu vault Obsidian, construindo um ativo de conhecimento pesquisável.

Posicionamento

A UI nativa do X não é ideal para revisão posterior: threads se espalham pela timeline, artigos têm formatação confusa, links quebram facilmente e a busca é fraca. Esta skill captura conteúdo de alta qualidade do X e o arquiva diretamente no Obsidian:

• Thread completa e expandida
• Artigo X com todos os content.blocks
• Metadados completos (autor, métricas, links diretos de mídia, created_at)
• Double links de tópicos no frontmatter, facilitando agregação MOC
• Detecção de idioma (zh / en / ja / ko)

Pré-requisitos

• Vault Obsidian (qualquer estrutura)

• Python 3, apenas stdlib (sem dependências de terceiros para arquivar um tweet individual)

• Opcional: pip install telethon (apenas para sincronização MTProto)

• Configure as variáveis de ambiente:

  export OBSIDIAN_VAULT=~/Documents/MyVault
  # Opcional: subdiretório de arquivamento personalizado (padrão "Articles")
  export OBSIDIAN_ARTICLES="Articles"
  # Opcional: idioma dos títulos das seções, padrão zh (chinês), use en para títulos em inglês
  export X_ARCHIVE_LANG=zh
  

API Principal: fxtwitter

Substitua x.com na URL do X por api.fxtwitter.com e faça um GET para obter JSON diretamente. Sem chave de API do X, sem login, sem custo.

Campo-chave	Uso
tweet.text / tweet.raw_text.text	Corpo do tweet
tweet.article.title	Título do Artigo X
tweet.article.content.blocks[]	Blocos de texto longo do Artigo
tweet.replying_to_status	Tweet anterior (retrocesso de thread)
tweet.quote	Tweet citado
tweet.media[]	Mídia (links diretos de imagem/vídeo)
tweet.created_timestamp	Timestamp UNIX
tweet.views / likes / bookmarks / retweets	Métricas

Fallback: se fxtwitter falhar → endpoint público cdn.syndication.twimg.com.

Palavras de Ativação

O usuário diz	Ação
"Arquive este X: URL" / "archive this: URL"	archive_x.py <URL>; conteúdo não-chinês ganha tradução automática (veja passo 4 do fluxo abaixo), sem necessidade de pedir "traduza"
"Organize esta thread: URL"	Mesmo que acima, força retrocesso de thread
"Sincronize meus favoritos do Telegram" + informar caminho do JSON	sync_telegram_export.py <path> --dry-run primeiro para revisar, depois executa de fato após confirmação
"Sincronize Telegram via API" (já com credenciais)	sync_telegram_saved.py

Fluxo de Trabalho (Arquivamento Padrão)

1. Parseia URL → handle + status_id
2. Executa script archive_x.py <URL>
3. Script verifica se já arquivado no vault (pelo campo url: no frontmatter)
   • Já existe → exibe SKIP, encerra
   • Caso contrário → obtém dados via fxtwitter, escreve no vault
4. AI então complementa:
   • Resumo de 1 frase em chinês sob ## 摘要
   • 1-3 double links topics + double links people
   • Conteúdo não-chinês (language diferente de zh): traduz integralmente a seção ## 中文译文 para chinês, sem que o usuário peça "traduza". Exige tradução livre, não literal — que soe como chinês natural escrito por humano, não como tradução automática; nomes próprios, nomes de produtos, códigos/comandos/parâmetros de API permanecem em inglês, apenas o texto narrativo e explicações são traduzidos
5. Seção "Minha opinião" sempre deixada em branco para o usuário

Sincronização do Telegram: Dois Caminhos

A. Exportação JSON (Recomendado, Sem Risco)

Telegram Desktop
  → Configurações → Avançado → Exportar dados do Telegram
  → Marcar "Mensagens privadas" + Selecionar formato JSON
  → Obter result.json

python3 sync_telegram_export.py <result.json> --dry-run   # Ver lista
python3 sync_telegram_export.py <result.json>             # Executar

Deduplica automaticamente por URL, pula itens já arquivados. Exporte uma vez por mês para sincronização incremental.

B. API MTProto (Avançado, Use com Cuidado na China)

Requer:

• https://my.telegram.org/auth para solicitar api_id / api_hash
• Executar generate_telegram_session.py para obter session_string
• IP residencial (usuários na China continental DEVEM usar IP residencial de HK/JP; IP de datacenter certamente causará ERROR)

⚠️ Usuários na China priorizem o método A. Criar app em my.telegram.org quase sempre esbarra em bloqueio de IP na China continental; tentativas repetidas podem resultar em congelamento da conta por 24-72h.

Nomenclatura de Arquivos

<YYYY-MM-DD>-X-<handle>-<primeiros 50 caracteres do título>.md

Exemplo:

• 2026-05-24-X-cyrilXBT-How-to-Organize-Your-Obsidian-Vault.md
• 2026-05-29-X-ObsidianOtaku-保存版AIエージェントのためのObsidian活用術.md

Múltiplos arquivos do mesmo autor no mesmo dia → sufixo -<últimos 6 dígitos do status_id>.

Frontmatter de Saída

---
tags: [文章摘抄]
source: X
url: https://x.com/<handle>/status/<id>
author: <nome de exibição>
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]]", ...]   # Preenchido pela AI
people: ["[[xxx]]", ...]   # Preenchido pela AI
media: [...] / 0
content_complete: true
metrics:
  views: N
  likes: N
  bookmarks: N
---

Limites e Exceções

Cenário	Tratamento
fxtwitter retorna 404	Tweet deletado/privado, sugira consultar archive.org
fxtwitter 5xx	Tentar 1 vez, falhar e usar fallback do endpoint syndication
URL não é x.com / twitter.com	Recusar, sugerir usar Web Clipper
Texto do tweet vazio, sem article e sem media	Aviso: "Puro retweet/resposta, pode não ter conteúdo independente"
Nome de arquivo duplicado mesmo dia/mesmo autor	Sufixo -<últimos 6 dígitos do status_id>
Mídia de vídeo	media[] no frontmatter grava link direto mp4, não incorpora

Referência de Linha de Comando

# Arquivar tweet único
python3 archive_x.py <URL>
python3 archive_x.py <URL> --force                  # Sobrescrever já arquivado
python3 archive_x.py <URL> --vault /path/to/vault   # Sobrescrever variável de ambiente

# Sincronizar exportação JSON do 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

# Sincronizar MTProto (requer setup prévio)
python3 generate_telegram_session.py    # Uma vez
python3 sync_telegram_saved.py --dry-run
python3 sync_telegram_saved.py --days 30
python3 sync_telegram_saved.py --all