Xのブックマークから自動でObsidianに取り込みたい！#day1コタ

project: XブックマークからObsidian連携ツール仕様書 overview: title: "Xブックマーク→Obsidian インテグレーション仕様書" description: | ユーザーがX（旧Twitter）で保存したブックマークを、自動的にObsidian Vault内のMarkdownファイルとして 取り込み・更新するためのツール仕様。Obsidianで管理するノートに「タイトル」「日時」「本文」「メタ情報」 を反映し、定期実行や手動実行で最新のブックマークを同期できることを目指す。 goals: - Xのブックマークを一元管理し、Obsidian Vault内で読める形式に変換・保存する - 既存のブックマークが更新されても重複ファイルを作らず、内容を差分管理できる - 取得したブックマークを検索・タグ付けしやすいMarkdown形式で保存する - ユーザーが手動またはスケジュール実行で同期処理を実行できる components: - name: "X API クライアントモジュール" description: | TweepyやRequestsを利用して、X Developer APIからユーザーのブックマークを取得する。 OAuth2またはOAuth1.0aを用いて認証し、「/2/bookmarks」エンドポイントを呼び出す。 - name: "データ整形モジュール" description: | 取得したAPIレスポンス（JSON）をパースし、必要なフィールドを抜き出してMarkdownテキストに変換する。 メタ情報（投稿日時、ツイートURL、ユーザー名など）をYAML Front Matter形式で付与。 - name: "ファイル管理モジュール" description: | Obsidian Vault配下の指定フォルダに対して、Markdownファイルを新規作成・更新・削除する。 すでに取り込んだブックマークはIDまたはURLハッシュをキーとして管理し、重複を防ぐ。 - name: "スケジューラー／CLIモジュール" description: | ユーザーが手動で実行するCLIコマンド、あるいは定期実行用のスケジューラ（cron／GitHub Actions）で 同期処理を自動的に行う。設定ファイルで実行間隔やVaultフォルダパスを指定可能。 authentication: method: "OAuth2 (推奨) または OAuth1.0a" details: - OAuth2: - 認証フロー: 「Bearer Token」を使用したアプリケーションレベル認証 - 必要情報: - BEARER_TOKEN（環境変数または設定ファイル保存） - OAuth1.0a: - 認証フロー: ユーザーキー・ユーザーシークレット・アクセストークン・アクセストークンシークレット - 必要情報: - API_KEY, API_SECRET_KEY, ACCESS_TOKEN, ACCESS_TOKEN_SECRET api_endpoints: - endpoint: "/2/users/:id/bookmarks" method: GET params: - user.fields: "id,username" - tweet.fields: "created_at,author_id,text,entities" - expansions: "author_id" - max_results: 50 - pagination_token: "ページネーショントークン" - pagination: description: | ブックマークが50件を超える場合、response.meta.next_token によるページネーションを実装。 すべてのブックマークを取得するまでループ実行する。 data_mapping: - field: "tweet.id" description: "ツイートID。Obsidianファイル名やフロントマターの一意キーとして利用する。" - field: "tweet.text" description: "ツイート本文。Markdown本文として保存。" - field: "tweet.created_at" description: "ツイート作成日時。Front Matter の date フィールドに変換する。" - field: "includes.users[].username" description: "ツイート投稿者のユーザー名。Front Matter の author/handle に設定する。" - field: "tweet.entities.urls[]" description: "ツイート内のURL。Front Matter の source_urls などで配列として保持する。" - custom_field: "bookmark_retrieved_at" description: "ブックマークを取得した日時を記録。API呼び出し時刻を挿入。" file_structure: root: "<Obsidian_Vault>/BookmarkedTweets/" pattern: "{created_at:yyyy-MM-dd_HHmm}_{tweet.id}.md" front_matter: | --- title: "Bookmark: {author_username} / {tweet.id}" date: "{tweet.created_at}" author: "{author_username}" tweet_url: "https://twitter.com/{author_username}/status/{tweet.id}" retrieved_at: "{bookmark_retrieved_at}" tags: - bookmark - twitter --- body_template: | {tweet.text} {% if urls %} {% for url in urls %} - [{{ url }}]({{ url }}) {% endfor %} {% endif %} {% if media %} {% for m in media %} ![media]({{ m.media_url }}) {% endfor %} {% endif %} workflow: - step: "環境変数/設定ファイル読み込み" details: | - X_API_KEY, X_API_SECRET, BEARER_TOKEN 等を環境変数または設定ファイル(~/.config/bookmark_sync.yaml)から読み込む。 - OBSIDIAN_VAULT_PATH（Vaultルートパス）、TARGET_FOLDER ("BookmarkedTweets") を取得。 - step: "X API でブックマーク一覧取得" details: | 1. 認証情報を使い、/2/users/:id/bookmarks をコール。 2. ページネーションありの場合は next_token を繰り返し利用し、全件取得。 3. 各ツイートデータに必要なフィールド（text, id, created_at, includes.users[].username, entities.urls）を抽出。 - step: "ローカルキャッシュ／DB参照 (ID比較)" details: | - これまでに取り込んだ tweet.id をキャッシュファイル（例: cache/bookmarks.cache.json）で保持。 - 新規に取得したIDとキャッシュを突き合わせ、すでに取り込まれたものはスキップ。 - 更新があったツイート（例: 本文の変更など）は前回取り込んだMarkdownファイルを上書き。 - step: "Markdownファイル生成・更新" details: | - ファイル名を "{created_at}_{tweet.id}.md" の形式で決定。 - Front Matter と 本文テンプレートをレンダリングして文字列生成。 - Vault配下の指定フォルダに書き出し (UTF-8)。 - step: "キャッシュファイル更新" details: | - 取り込み済み ID と更新日時を cache/bookmarks.cache.json に保存。 - 次回実行時に重複チェックと更新チェックに使用する。 configuration: config_file: "~/.config/bookmark_sync.yaml" example: X: api_key: "YOUR_X_API_KEY" api_secret: "YOUR_X_API_SECRET" bearer_token: "YOUR_BEARER_TOKEN" user_id: "1234567890" ob_vault: path: "/Users/username/ObsidianVault" target_folder: "BookmarkedTweets" sync: max_results: 50 schedule: cron: "0 * * * *" or: github_actions_workflow: ".github/workflows/bookmark_sync.yml" error_handling: - missing_auth: condition: "環境変数 or 設定ファイルに認証情報がない" action: "エラーメッセージを表示し、処理を中断" - api_rate_limit: condition: "HTTP 429 レスポンス" action: | - retry_after ヘッダーを確認し、指定秒数分 sleep - リトライ回数が上限に到達したらログに記録して終了 - network_error: condition: "ネットワーク接続失敗" action: "指定回数リトライし、Fail時はログに詳細を出力して終了" - file_io_error: condition: "Markdown書き込み／ディレクトリ作成失敗" action: "エラーログ出力 → 処理を続行できない場合は終了" scheduling: options: - type: "cron" description: "Linux/macOS の cron に登録して指定間隔で実行" example: "0 * * * * /usr/local/bin/python3 /path/to/bookmark_sync.py" - type: "GitHub Actions" description: "GitHub リポジトリで workflow を使い、定期実行" example: | name: "Bookmark Sync" on: schedule: - cron: "0 * * * *" jobs: sync: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Set up Python uses: actions/setup-python@v4 with: python-version: "3.x" - name: Install dependencies run: pip install -r requirements.txt - name: Run bookmark sync env: X_API_KEY: ${{ secrets.X_API_KEY }} X_API_SECRET: ${{ secrets.X_API_SECRET }} BEARER_TOKEN: ${{ secrets.BEARER_TOKEN }} OBSIDIAN_VAULT_PATH: ${{ secrets.OBSIDIAN_VAULT_PATH }} run: python3 bookmark_sync.py logging: level: "INFO" log_file: "/var/log/bookmark_sync.log" format: "[%(asctime)s] %(levelname)s: %(message)s" retention: "30 days" security: - "環境変数またはGitHub Secretsで認証情報を管理" - "Vaultパスワードやトークンをコード内にハードコーディングしない" - "ファイルI/O時にパス・ファイル名のサニタイズを行い、ディレクトリトラバーサルを防ぐ" dependencies: python: - "Python>=3.8" - "tweepy>=4.0" - "PyYAML>=5.4" - "requests>=2.25" node (代替実装時): - "node>=14" - "axios>=0.21" - "js-yaml>=4.0" - "cron>=1.8" deployment: steps: - name: "リポジトリをクローン" command: "git clone https://github.com/username/bookmark-sync.git" - name: "Python環境構築" commands: - "cd bookmark-sync" - "python3 -m venv venv" - "source venv/bin/activate" - "pip install -r requirements.txt" - name: "設定ファイル配置" description: "~/.config/bookmark_sync.yaml に必要情報を記入" - name: "Cron登録例" command: | (crontab -l 2>/dev/null; echo "0 * * * * /usr/local/bin/python3 /home/user/bookmark-sync/bookmark_sync.py") | crontab - - name: "GitHub Actions 設定" description: "リポジトリに .github/workflows/bookmark_sync.yml を追加" future_extensions: - "Obsidian 内でタグやリンクを自動付与するプラグイン連携" - "ブックマーク削除検知機能（Obsidianファイルを自動で削除/アーカイブ）" - "他のソーシャルブックマークサービス（Pocket, Pinboard）への対応" - "GUI ランチャーアプリ化（Electron / Tauri など）" - "Obsidian Live Sync プラグインを使ったリアルタイム反映"