web-clipper

Web Clipper

目標：「ウェブ記事の保存」を、その場限りの手作業ではなく、安定したワークフローにします。

このスキルで解決する問題

次の2種類のタスクに対応します。

1. 記事1件の保存

   • 記事の URL を入力
   • タイトル、要約、公開日、本文を抽出
   • ユーザーが指定したディレクトリに Markdown として保存

2. 複数記事の保存

   • インデックスページ、アーカイブページ、特集ページ、著者のホームページを入力
   • ユーザーの指定に応じて、先頭から N 件、人気記事、最新記事、または指定した記事を取得
   • ローカルに一括保存

成功率を優先する実行戦略

以下の順序で進めてください。逆順にしないでください。

初回使用時の依存関係の確認

このスキルを zip で他の人に共有した場合は、ラッパーを使用してください。メインスクリプトを直接実行しないでください。

初回実行時は、まず次を実行します。

bash <web-clipper-root>/scripts/run_web_clipper.sh --help

注意：このコマンドは副作用を伴います。

最初に bootstrap を実行し、デフォルトの clipping ディレクトリと、現在のプロジェクト内の .web-clipper/EXTEND.md を作成する場合があります。

ラッパーは最初に scripts/bootstrap.sh を呼び出し、次の処理を自動で行います。

1. Python 3 が使用可能か確認
2. Python 3 が見つからない場合、自動インストールを試行
3. メインスクリプトが完全か確認
4. デフォルトの clipping ディレクトリを自動作成
5. 初回実行時に、現在のプロジェクト内に .web-clipper/EXTEND.md を書き込み

デフォルトでは、「現在のコマンドが実行されているディレクトリ」を対象プロジェクトのルートディレクトリとして扱います。

そのため、対象 vault のルートディレクトリからラッパーを実行してください。サブディレクトリで不用意に実行しないでください。

自動インストールに失敗した場合は、ユーザーに次の点を明確に伝えてください。

• 問題が発生しているのは Python ランタイムであり、ウェブページの取得処理ではないこと
• 現在のプラットフォームで推奨されるインストールコマンド
• インストール完了後、ラッパーを再実行すればよいこと

ユーザーが保存先ディレクトリを指定していない場合は、次の優先順位で選びます。

1. 現在のプロジェクトの .web-clipper/EXTEND.md にある default_output_dir
2. 現在のリポジトリ内の 00_收件箱/Clippings/
3. 現在の作業ディレクトリ内の Clippings/

パス A：静的な直接取得

対象：

• 公開ウェブページ
• ログイン不要
• 記事ページの HTML に本文または構造化 JSON が直接含まれている
• Substack／一般的なブログ／シンプルな CMS

手順：

• まず scripts/run_web_clipper.sh を呼び出す
• 1件の場合：URL を直接取得
• 複数件の場合：まずスクリプトにインデックスページから記事リンクを静的に抽出させる

パス A2：Metaso Reader API へのフォールバック

対象：

• 静的な直接取得に失敗する場合（WeChat 公式アカウント、スクレイピング対策のあるサイトなど）
• スクリプトで article body not found が報告される場合
• 追加のインストールは不要で、API Key の設定のみ必要

手順：

• スクリプトは自動的に Metaso Reader API にフォールバックします
• 環境変数 METASO_API_KEY の設定が必要です
• API は画像リンクを含む構造化 Markdown を返します
• WeChat 公式アカウントや 163 など、スクレイピング対策のあるサイトで効果的です

METASO_API_KEY が設定されていない場合、この方法はスキップされ、パス B／C に進みます。

パス B：ブラウザーでリンクを補完

対象：

• インデックスページが遅延読み込みされる
• 静的 HTML に一部の記事リンクしか表示されない
• 先頭から N 件を取得するためにページのスクロールが必要
• ページ構造が特殊で、スクリプトではリンクを確実に収集できない

手順：

1. browser でインデックスページを開く
2. 十分な数の記事 URL が集まるまでページをスクロールする
3. ページ上で JS を実行し、重複を除いた記事 URL の一覧を返す
4. URL の一覧を一時的な txt ファイルに書き込む
5. scripts/run_web_clipper.sh --url-file ... を呼び出して一括保存する

この方法は重要です。リンクの取得はブラウザーが担当し、本文の保存はスクリプトが担当します。

パス C：ブラウザーで本文を直接抽出

対象：

• 1件の記事ページの静的取得がブロックされる
• web_fetch がブロックされる
• スクリプトで本文の取得に失敗するが、ブラウザーではレンダリング後のページを正常に開ける

手順：

• browser で記事ページを開く
• evaluate を使って DOM またはページ内の埋め込み JSON から本文を抽出する
• Markdown を組み立てる
• write を使ってファイルに保存する

パス A と B のどちらも安定しない場合に限り、パス C を使用してください。C は処理が複雑ですが、成功率が高いためです。

入力内容の確認ルール

ユーザーから説明がない場合は、次の4点を優先して確認してください。

1. 1件か複数件か
2. 何件取得するか
3. どこに保存するか
4. 本文のみ取得するか、frontmatter のメタデータも残すか

デフォルト値：

• 1件の場合：1件を取得
• 複数件の場合：ユーザーが「先頭から数件／先頭から20件／人気記事」と指定していれば、その要望に従います。件数の指定がない場合は、まず質問してください
• 出力形式：Markdown + YAML frontmatter
• デフォルトの保存先：ユーザーが指定していない場合は、既存の clipping ディレクトリに保存します。現在把握している一般的なパスは 00_收件箱/Clippings/ です

推奨コマンド

1件

WEB_CLIPPER_ROOT="<web-clipper-root>"
bash "$WEB_CLIPPER_ROOT/scripts/run_web_clipper.sh" \
  --url "<文章URL>" \
  --mode single \
  --output-dir "<输出目录>"

複数件、リンクを静的に収集

WEB_CLIPPER_ROOT="<web-clipper-root>"
bash "$WEB_CLIPPER_ROOT/scripts/run_web_clipper.sh" \
  --url "<索引页URL>" \
  --mode batch \
  --count 20 \
  --output-dir "<输出目录>"

複数件、まずブラウザーでリンクを収集してから保存

WEB_CLIPPER_ROOT="<web-clipper-root>"
bash "$WEB_CLIPPER_ROOT/scripts/run_web_clipper.sh" \
  --url-file /tmp/article_urls.txt \
  --mode batch \
  --count 20 \
  --output-dir "<输出目录>"

ユーザーが --output-dir を明示的に指定していない場合、ラッパーはまず .web-clipper/EXTEND.md のデフォルトディレクトリを読み込みます。設定がない場合は、00_收件箱/Clippings/ または Clippings/ に自動でフォールバックします。

ブラウザーで URL を収集する際に推奨する JS

静的ページですべてのリンクを取得できない場合は、browser.act(kind="evaluate") で次のような処理を実行します。

async () => {
  const collect = () => [
    ...new Set(
      Array.from(document.querySelectorAll('a[href*="/p/"]'))
        .map((a) => a.href)
        .filter((h) => !h.includes("/comments")),
    ),
  ];

  let urls = collect();
  for (let i = 0; i < 8 && urls.length < 20; i++) {
    window.scrollTo(0, document.body.scrollHeight);
    await new Promise((r) => setTimeout(r, 1500));
    urls = collect();
  }
  return urls;
};

その後、結果を /tmp/article_urls.txt に書き込みます。1行につき URL を1つ記載してください。

出力要件

記事ごとに Markdown ファイルを1つ出力します。推奨する構成は次のとおりです。

---
title: "..."
author: "..."
source: "..."
archive: "..."
published: "YYYY-MM-DD"
clipped: "ISO时间"
tags:
  - clipping
---

# 标题

> 摘要

正文...

ファイル名

デフォルト形式：

YYYY-MM-DD 标题.md

日付がない場合は、次を使用します。

unknown-date 标题.md

失敗時の対応

複数記事の取得に失敗した場合は、「失敗しました」の一言で終わらせないでください。次の順序で確認してください。

1. インデックスページが遅延読み込みされ、静的な取得では一部のリンクしか取得できていないか
2. 記事ページが公開されているか
3. 記事本文が body_html などの構造化 JSON に含まれていないか
4. 本文の抽出にブラウザーでのレンダリングが必要か

どの段階で問題が発生したか、ユーザーに明確に伝えてください。

• リンクの収集に失敗
• 本文の抽出に失敗
• ファイルの書き込みに失敗

現在、成功を確認済みのサイトのパターン

Substack

確認済み：

• アーカイブページから記事 URL を収集できます
• 記事ページに埋め込まれた JSON フィールド body_html から本文を抽出できます
• Obsidian Clippings への保存に適しています

この種のサイトでは、まずスクリプトで一括処理してください。アーカイブページが遅延読み込みされる場合は、ブラウザーを使って URL の収集を補完します。

WeChat 公式アカウント

確認済み：

• 静的な直接取得は、スクレイピング対策によりブロックされます（認証ページが表示されます）
• Metaso Reader API（パス A2）を使うと安定して取得でき、完全な Markdown と画像リンクが返されます
• 環境変数 METASO_API_KEY の設定が必要です

完了報告

完了後は、簡潔に結果を報告してください。冗長な説明は不要です。

已保存到: <目录或文件路径>
类型: clipping / Markdown
理由: 已按要求完成单篇或批量文章收藏

複数記事のタスクの場合は、さらに次の行を追加してください。

• 成功 X 件
• 失敗 Y 件

このスキルを使わないケース

次のような場合は、このスキルを無理に使用しないでください。

• ユーザーが求めているのが要約、書き換え、翻訳であり、記事の保存ではない
• ユーザーがログイン後のコンテンツを取得したいが、利用可能なログイン状態がない
• ユーザーがサイト全体のページをクローラーでアーカイブしたい
• ユーザーが求めているのがブラウザー自動テストであり、記事の保存ではない