1仕組みと動作原理

単一投稿のプレーンテキスト取得の優先ルートは、ログイン不要・APIキー不要でfxtwitterミラーAPIを直接curlし、tweet.textから全文を取得する方式です（ドキュメントにはfull_textキーは存在しないと明記）——このルートは認証情報ゼロ・設定ゼロであり、2026-08-30よりJinaに代わりデフォルトとなりました。

twitter-reader/SKILL.md

works direct, and returns the **full note_tweet body in `tweet.text`** (the `full_text` key does not exist; a 2,324-char long-form announcement came back complete):

ドキュメントにはエージェントが（スクリプト化せず）直接実行可能な `curl -sS --max-time 20 "https://api.fxtwitter.com/<user>/status/<id>" | python3 -c ...` というレシピが記載されており、ミラーAPIが構造化JSONを返した後はcreated_atとtextの2フィールドのみを抽出します。これが本スキルにおける「単一投稿の読み取り」に対する実際の実装であり、ページスクレイピングや公式API呼び出しを行わず、サードパーティミラーに依存しています。

X Articles（画像付き長文）のメインルートはfetch_article.pyが担当します：まず `uv run --with twitter-cli` を用いてPyPIパッケージtwitter-cliをその場でインストール・実行し、`twitter article` サブコマンドでauthor/metrics/articleTextを含む構造化YAMLを取得します。

twitter-reader/scripts/fetch_article.py

def run_twitter_cli(url: str) -> dict: """Fetch article data using twitter-cli via uv run.""" cmd = ["uv", "run", "--with", "twitter-cli", "twitter", "article", url]

実行ごとにuvによってtwitter-cliが一時的に解決・インストールされ（バージョンは固定されていません）、出力はparse_yaml_output内のyaml.safe_loadでパースされてdataフィールドが取得されます。メタデータ（createdAtLocal/author/metrics{likes,retweets,bookmarks}/articleTitle/articleText）はこのサードパーティCLIの独自出力フォーマットに完全に依存しており、本リポジトリ自体はTwitter APIへの直接接続を実装していません。

本文（画像含む）はJina Reader（r.jina.ai）を介して取得されます：JINA_API_KEYが存在すればBearerヘッダーを付与し、なければ匿名でアクセスします。その後「Markdown Content:」マーカーで本文を切り出し、Jinaが失敗した場合はtwitter-cliが返したarticleTextにフォールバックします。

twitter-reader/scripts/fetch_article.py

api_key = os.getenv("JINA_API_KEY", "") jina_url = f"https://r.jina.ai/{url}" cmd = ["curl", "-s", jina_url] if api_key: cmd.extend(["-H", f"Authorization: Bearer {api_key}"])

ドキュメントには、匿名でのr.jina.aiによるx.comへのアクセスは第三者の濫用により断続的な全体403拒否（2026-08-30の実測記録）に見舞われると明記されており、Jinaは「利用可能だが信頼性は低い」本文ソースと位置付けられています。ここでのAPIキーは必須ではなく任意指定の最適化です。

画像のローカル保存が本スクリプトの中核的な付加価値です：取得したMarkdownから正規表現でpbs.twimg.com/mediaリンクを抽出 → 重複排除して ?format=jpg&name=large に統一 → curlでattachments/日付-著者-タイトル/ 配下に順次ダウンロード → 本文内のリモート画像URLを正規表現でローカルの相対パスに置換します。

twitter-reader/scripts/fetch_article.py

pattern = r'https://pbs\.twimg\.com/media/[^\s\)"\']+'

extract_image_urlsはpbs.twimg.com/mediaプレフィックスのみを認識し、ダウンロード対象をTwitterの画像CDNに限定します。download_imagesは `curl -sL url -o filepath` でディスクに保存し（タイムアウトなし、順次実行、01-image.jpg… の連番命名）、replace_image_urlsですべてのリモートURLをattachments/... のローカル相対参照に書き換えることで、オフラインでのMarkdown閲覧を保証します。

出力規則：YYYY-MM-DD-タイトル.md（YAML frontmatter：source/author/date/likes/retweets/bookmarks を含む）+ 同名の添付ファイルディレクトリ。日付はcreatedAtLocalの先頭10文字を採用し、タイトルと著者はsanitize_filenameでサニタイズの上60文字に切り詰めます。

twitter-reader/scripts/fetch_article.py

md = f"""--- source: {source_url} author: {author.get("name", "")} date: {date_str} likes: {metrics.get("likes", 0)}

generate_markdownがfrontmatterと本文を結合します。本文にローカル画像参照が含まれる場合は、replace_image_urlsで書き換えた後に結合されます。全体として、Obsidianなどのノート環境を想定した「Webページ/ツイート → クリーンなPKMファイル」変換ツールとなっています。

Jinaテキストモードはバイパス（フォールバック）として位置付けられています：fetch_tweet.py（単一取得、JINA_API_KEY必須、HTTPS限定）およびfetch_tweets.sh（bashバッチループ、正規表現でhttp/httpsを許容）はr.jina.aiを直接curlしBearerトークンを透過します。

twitter-reader/scripts/fetch_tweets.sh

for url in "$@"; do if [[ ! "$url" =~ ^https?://(x\.com|twitter\.com)/ ]]; then

このバイパスはSKILL.mdで明確にフォールバックとして位置付けられており（ドキュメントには共有キーの402残高不足やバッチスクリプトが現在利用不可である旨が記載されています）、中核方針は「これに依存しないこと」です。自前の予備経路のリスクをドキュメントに明記している珍しいスキルです。

2コア機能

01ログイン不要の単一投稿全文読み取り（fxtwitter優先ルート）

02X Article長文コンテンツの取得（note_tweetレベルの長文に対応）

03構造化メタデータの取得：著者、日付、likes/retweets/bookmarksのエンゲージメント指標

04本文埋め込み画像のローカルattachmentsディレクトリへの自動一括ダウンロードおよびローカル参照への書き換え

05PKMシステム向けのYAML frontmatter付きMarkdownファイル生成（source/author/date/likes/retweets/bookmarks）

06Jinaテキストモードでの単一/一括取得（fetch_tweet.py / fetch_tweets.sh）とURLホワイトリスト検証

07コンテンツソースのフォールバック耐障害性：Jina失敗時にtwitter-cliのarticleTextへフォールバック、サードパーティ経路の不安定性の実測記録と文書化

3外部依存関係

Kind	Dependency / Endpoint
cli	curl
cli	uv (Python 包管理器)
cli	python3（含内联 -c 解析）
package	twitter-cli（PyPI，uv 现场安装并执行 twitter article 子命令，未 pin 版本）
package	pyyaml
api	Jina Reader API
network	fxtwitter 镜像 API
network	Twitter 图片 CDN（图片下载目标）
network	x.com / twitter.com（被抓取目标，经 fxtwitter/Jina 代理访问）

4推奨統制措置と判定根拠

安全運用のための推奨統制措置

Agent 向け

段階的・都度認可、サンドボックス推奨

管理者向け

承認フロー、ロールバック可能、全履歴監査

判定根拠（ファイルパスと抜粋）

scripts/: ローカルスクリプトまたはコマンドの実行: scripts/fetch_article.py —— `uv run --with pyyaml python scripts/fetch_arti
scripts/ 或 SKILL.md: 外部言語パッケージ依存の動的インストールの宣言
网络端点: 外部ネットワークアクセスの宣言: https://api.fxtwitter.com/<user>/status/<id>（APIキー不要のミラー、SKILL.mdのfxtwitterセクション）
本地工作目录: ファイルの読み書きと成果物の出力: fetch_article.py: <output_dir>/YYYY-MM-DD-<safe_title>.md および <output_dir>/a への書き込み

監査ノート： 調査所見であり、認証ではありません。オレンジ判定は基準表のオレンジ条件2件に文字通り該当するためです：(a) 環境変数の認証情報読み取り——JINA_API_KEYが2つのスクリプトで必須として読み取られ外部送信される（送信先はr.jina.ai本体のみで予測可能であり、Cookie/キーチェーン/ハードコードキーは含まないため上位判定には非該当）；(b) サードパーティのリモートパッケージへの依存——メインルートの実行ごとにuv経由でPyPIからtwitter-cli（バージョン未固定）が動的インストール・実行され、実行コードが本リポジトリの監査対象外かつ.security-scan-passed（本ディレクトリテキストのgitleaks静的スキャン）の対象外。スクリプト自体にはshell=Trueや難読化、隠蔽された外部送信はなく、ダウンロード対象は正規表現でpbs.twimg.comに限定され、キー不要のfxtwitterルートは認証情報ゼロであるためレッド判定よりは下位となります。しかし「リモートパッケージ + 環境変数認証情報」の重複によりグリーン/ブルー判定は成立せず、イエロー判定の「公開API/公式CLIのみで外部送信が予測可能」にも完全には合致しないため、オレンジ（評価後に使用）と判定します。

5二重目の独立検証

[ok] fxtwitter API（api.fxtwitter.com）调用点真实存在 — SKILL.md fxtwitter 段内联 curl 配方原文命中；文档自述 2026-08-30 实测过 2,324 字符 note_tweet 完整返回。仅验证调用点，端点当前可达性未在线复核
[ok] Jina r.jina.ai 调用点真实存在 — 三个脚本各自命中：fetch_tweet.py `jina_api_url = f"https://r.jina.ai/{url}"`、fetch_tweets.sh `curl -s "https://r.jina.ai/${url}"`、fetch_article.py run_jina_api；Bearer 头与 JINA_API_KEY 读取逐处对上
[ok] twitter-cli 依赖真实存在（uv run --with） — fetch_article.py run_twitter_cli 的 argv 原文命中；SKILL.md Quick Start 另以 `uv run --with pyyaml` 启动脚本，与 parse_yaml_output 的 yaml 导入一致
[ok] pbs.twimg.com 图片下载路径真实存在且仅此 CDN — extract_image_urls 正则仅匹配 pbs\.twimg\.com/media/ 前缀；download_images 用 curl -sL 落盘。未发现其他图片域名
[ok] JINA_API_KEY 读取点全覆盖、无硬编码密钥 — grep JINA_|sk- 于 twitter-reader/ 命中仅 3 处 env 读取（无字面量）；全仓库 CHANGELOG 记录 2026-01-05 前后『Removed hardcoded API keys』。SKILL.md 所述『shared key 402 余额尽』系作者侧市场共享 key，仓库内无对应字符串
[ok] URL 校验形态：前缀白名单而非权威解析 — fetch_tweet.py/fetch_article.py 用 startswith(("https://x.com/","https://twitter.com/"))；fetch_tweets.sh 用正则 ^https?://(x\.com|twitter\.com)/。三处均要求主机后紧跟 /，可挡 https://x.com.evil.com 型主机混淆；bash 版放行 http:// 与文档『HTTPS only』表述存在出入（py 版严格）
[ok] 无隐藏脚本/无混淆/无隐蔽外发 — 目录仅 SKILL.md + 3 脚本 + .security-scan-passed 标记；脚本全部为列表式 subprocess，无 shell=True/eval/curl 之外的网络动词；.security-scan-passed 为纯文本记录，无执行作用
[ok] 功能声明与代码能力相符性 — 『长文带图 + 元数据 + 自动下载 + Markdown』在 fetch_article.py 中逐项落实；但核心卖点依赖第三方间歇服务：Jina 匿名被全局 ban 时正文只剩 twitter-cli 的 articleText 兜底（可能不含图），文档已如实标注『Preferred over Jina…』仅针对有图场景——无夸大但有外部依赖边界

6結論

単一投稿取得のゼロコスト経路：ログイン不要・キー不要のfxtwitterミラーを優先し、直接実行可能な完全なcurlレシピをドキュメントに記載

画像付き長文をワンクリックでローカルPKMファイル化：メタデータ + 画像自動ダウンロード + URL書き換え + YAML frontmatterを全自動処理

誠実なドキュメント：メイン/予備経路（Jina）の断続的な全体アクセス禁止や共有キー残高不足などの失敗実績をSKILL.mdに明記しフォールバックを設計、エージェントが不安定な経路をメインとして扱うリスクを防止

極めて最小限の依存関係：curl + uv + 2本の小型スクリプトのみで構成され、重量級ランタイム不要、出力構造も明確（YYYY-MM-DD-タイトル.md + attachments/）

最適な用途： Xの投稿/長文（画像含む）をクリーンなローカルMarkdownに変換し、ノートやPKM、二次加工に活用したい個人またはチーム。Claude Code等のホスト環境。自身のJinaキー（任意）を用意でき、サードパーティミラーやプロキシ経路の利用を許容できるユースケース。

不向きな用途： 返信スレッドやコメント一覧が必要な場合（返信はカウントのみ）、ログイン認証が必要なデータ、サプライチェーンリスクを一切許容できない環境やオフライン環境（twitter-cliがuv経由で都度動的インストールされるため）、Xのスクレイピングを中核業務とする大規模なコンプライアンス重視の収集処理。

Install Agent-Ready

① Verified Mirror 2026-09-06

Option A · Direct DownloadDownload twitter-reader.tar.gz

sha256: 6e441b1396143142…

Option B · Copy Guide for Agent

install.json

Agent はこの JSON ガイドから自動的にダウンロードして検証します。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit 63a65c1fcc.