Abduction Learning — アブダクション語学学習（非公式ファンメイド）

今井むつみ『アブダクション英語学習法』の学び方を、ブラウザだけで実践するための練習帳です。 著者・出版社とは無関係の非公式プロジェクトで、本文・例文・登場人物は一切収録していません。使っているのは「手順の構造」と、基本動詞13語・前置詞 at / in / on という語のリストだけです。

できること

1. 例文を出力する（STEP 1） — 似た意味の語（listen & hear など）を選び、ジャンル・レベル・副詞の有無を指定してAIに例文だけを出させる。AIには「頼むまで意味の解説をしない」という指示が常に付く。
2. 比較・検討して仮説を立てる（STEP 2） — 例文の語句をドラッグでマークして比較表（対象ごと／共通・固有／タグ別）を作る。S/V/O/C を自分でタグ付けする構文分析。仮説は v1, v2 … と版を重ね、「？」で不確かさを残せる。
3. 仮説を検証する（STEP 3） — 母語で試験文を書き、①②③の位置にどの語が出るかを予想してからAIに訳させる翻訳テスト。「〜するつもりだ」のような枠を当てるフレームテスト。
4. まとめ・出力 — スキーマを気づきノートに保存し、自分の場面で文を書いて相棒コメントをもらう。

画面ではこれらの用語は使わず、案内役が語りかけるセリフ調で「例文 → 見比べる → 仮説 → 訳して確かめる → まとめ」と進みます。本を読んでいなくても使えます。

続ける仕掛け: 探究を始めたりカードを進めたりするとポイントが入り、レベルが上がります。日ごとの連続記録（ストリーク）もホームに出ます。どちらも保存したデータから計算するので、バックアップと一緒に移ります。

その他: 読み上げ（ブラウザ内蔵音声、無料）、生成文の文法チェックと「？」旗、生成モデル・日時の記録、JSONバックアップ。

使い方

学習データはすべてブラウザ内（IndexedDB）に保存されます。サーバーは持ちません。

AIの接続先は設定画面のタブで選びます。開いているタブが使われます。

タブ	内容
無料枠	運営者が用意した安価なモデルを、1日の回数制限つきで無料で使う（下記の Worker を配置した場合のみ）
Anthropic / OpenAI / Gemini	自分のAPIキーを入れる。キーはブラウザの localStorage にだけ保存され、各社のAPIへ直接送られる

無料枠（共有キー）の仕組みと制限

静的サイトには秘密を置けないため、共有キーは Cloudflare Worker（無料枠）に置き、サイトはその Worker 経由で呼び出します。リポジトリのシークレットをビルドに埋め込む方式は、キーが公開JSに含まれて誰でも取り出せてしまうので採用していません。

無料枠は AI の呼び出し回数ではなく、探究の数で数えます。 始めた探究には AI 呼び出しの枠をまとめて確保するので、探究の途中で上限に達することは、ふつうはありません（例外は下の「1日の費用」に達した日だけです）。

Worker が掛けている制限（worker/wrangler.toml で変更可）:

• 端末ごと（ブラウザの匿名ID）: 初めて使う日は探究 5 つ、2日目からは1日 3 つ — 初日は探究を何度か経験してもらい、2日目以降も語の組を変えて続けられる
• IPごと: 1日 10 つ — 匿名IDを消して初日の枠を取り直されるのを鈍らせる
• 全体: 1日 330 つ — 数による予備の歯止め。平均 $0.009/探究（docs/model-bench-2026-09.md）で約 $3
  • IPごとの上限もかかるので、330 に届くには少なくとも 33 のIPが要る
• 1日の費用: $3 まで — 運営者の支払額はこれで止める
  • 呼び出しの前に、その呼び出しの最悪の費用（入力はシステムプロンプト・本文・スキーマの UTF-8 バイト数をトークン数とみなし、出力はトークン上限まで使ったとする）を単価（PRICE_INPUT_PER_M / PRICE_OUTPUT_PER_M）で見積もって予約し、応答後にプロバイダが返した使用量で実費に置き換える
  • 今日の実費と実行中の予約の合計にその呼び出しの予約を足して $3 を超えるなら、呼び出しを送らない。並行して呼ばれても超えない
  • 新しい探究は $2.50 で締め切り、残りの $0.50 は始まっている探究に回す（平均で約 55 探究ぶん）
  • モデルを変えるときは単価も一緒に変える。単価が未設定なら Worker は呼び出しを送らず 503 を返す
• 探究1つにつき AI 呼び出し 60 回まで（ふつうは 15〜30 回）。始めた探究は 3 日間、日をまたいでも続けられる
• モデル固定・出力トークン上限・入力文字数上限
• アプリのシステムプロンプト署名を持つ要求だけ受け付ける（汎用プロキシとして使えない）
• 配信元オリジンの制限

新しく始められる探究の数と1日の費用は、日本時間の0時にリセットされます。 上限に達すると、探究を始める画面と最初の例文の生成時にその旨が表示されます。 自分のキーに切り替えれば続けられます。

運営者の設定手順

1. Cloudflare アカウント（無料）を作り、API トークン（Workers 編集権限）とアカウントIDを控える。
2. GitHub リポジトリの Settings → Secrets and variables → Actions に以下を登録する。
   • Secrets: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, PROVIDER_API_KEY（共有するAPIキー）, RESEND_API_KEY, FEEDBACK_TO（下記「ご意見フォーム」）
   • Variables: PROXY_ENABLED = true, PROVIDER（anthropic / openai / gemini）, MODEL（既定は gpt-5.6-luna。選定の根拠は docs/model-bench-2026-09.md）
3. Actions の「Deploy」を target worker で実行すると（CI が通った後に） Worker が配置され、https://abduction-learning-proxy.<account>.workers.dev のURLが出る。
4. そのURLを Variables の PROXY_URL に登録し、「Deploy」を target pages で再実行する。

worker/wrangler.toml の ALLOWED_ORIGINS は自分の Pages のURLに合わせてください。

Worker のログを見る

Worker のログは Cloudflare の Workers Logs に残ります（worker/wrangler.toml の [observability]）。 無料プランでは3日間・1日20万件まで保持されるので、監視していなかった時間の障害も後から追えます。

• 後から見る: Cloudflare ダッシュボードの Workers & Pages → abduction-learning-proxy → Observability（Logs）。 ログはフィールドごとに絞り込めます。たとえば event が generate_quota（429。scope が device / ip / global / inquiry / budget）、 provider_failed（AI の失敗。status と error）、feedback_failed（ご意見メールの送信失敗）、exception（捕まえていない例外）。 すべてのリクエストに event = request の行（route・status・ms）が1行ずつ出ます。
• いま流れているものを見る: pnpm --filter abduction-learning-proxy exec wrangler tail（--format json も可）。 こちらはコマンドを止めると何も残りません。

ログには IP・探究や意見の本文・メールアドレス・APIキーを出しません。端末IDは短いハッシュ（deviceTag）だけです。 Cloudflare が自動で残す呼び出しログ（invocation logs）はリクエストヘッダー（IP を含む）を記録するので、切ってあります。

リンクを共有したときのカード（og:image など）は https://<owner>.github.io/<repo>/ を前提に絶対URLで組み立てます。独自ドメインで公開する場合は Variables に SITE_URL（例 https://example.com/）を登録してください。画像は scripts/og-image.svg を直して pnpm og-image で public/og-image.png を作り直します。

閲覧数

GitHub Pages にはアクセスログがないため、ページが開かれた回数は Cloudflare Web Analytics で数えます。 Cookie を使わず、個人を特定する情報を持たないビーコンです。本番ビルドで Variables に CF_BEACON_TOKEN があるときだけ index.html に入り、開発サーバーとテストでは読み込まれません。 有効なときは、トップページの「このアプリについて」にその旨を表示します。

設定手順:

1. Cloudflare ダッシュボードの Analytics & Logs → Web Analytics → Add a site で、ホスト名に yanasehiroki.github.io を入れる（DNS が Cloudflare にないので JS スニペット方式になる）。
2. 表示されるスニペットの "token": "..." の値を、GitHub の Variables に CF_BEACON_TOKEN として登録する。
3. Actions の「Deploy」を target pages で実行する。

#/ 以降の画面遷移は細かく取れないので、見るのは主に訪問数・参照元（X からは t.co）・国・端末です。広告ブロッカーを使う人の分は数えられません。

ご意見フォーム

ヘッダーの「ご意見」から、使い方の質問・不具合・要望を送れます（Worker を配置した場合のみ表示）。 送信内容は Worker から Resend 経由で運営者にメールで届き、どこにも保存されません。 送り主がメールアドレスを書いた場合はそれが Reply-To になるので、届いたメールにそのまま返信すればやり取りできます。 いま開いている画面・UIの言語・使っているAIの種類・ブラウザも一緒に送られます（探究の内容とAPIキーは送りません。フォーム内で送り主にも見せています）。

設定手順:

1. 運営者の受信用メールアドレスで Resend のアカウント（無料: 1日100通・月3,000通）を作り、API キーを発行する。 独自ドメインは不要です。送信元の [email protected] は、Resend アカウントのアドレス宛てにだけ送れる制限があり、この用途ではそれで足ります。
2. GitHub の Secrets に RESEND_API_KEY（発行したキー）と FEEDBACK_TO（Resend アカウントのアドレス）を登録し、Actions の「Deploy」を target worker で実行する。 アドレスはリポジトリに書かず Secret に置くので、公開リポジトリでも漏れません。

迷惑な大量送信への対策（worker/wrangler.toml で変更可）: 1 IP につき1日 5 通、全体で1日 50 通、本文 4,000 字まで。人には見えない入力欄（ハニーポット）を埋めたボットの送信は、成功したふりをして捨てます。

無料枠を支える

無料枠の上限（全体で1日に始められる探究の数）は、運営者が出せる額から決めています。 無料枠が利用者全体で尽きたときだけ、GitHub Sponsors と Ko-fi での支援を案内します（アプリの #/support）。 支払いは Webhook で Worker に届き、手数料を除いた額が自動で全体の上限に上乗せされ、案内はその場で消えます。 見返りはなく、支援しても本人の1日の回数は増えません。増えるのは全体の上限です。 デポジット済みのAPIキーの提供はお受けしていません。自分のキーで使うことも、原資を使わない支援になります。

方針と理由、運営者の設定手順（Variables の SUPPORT_GITHUB / SUPPORT_KOFI、Secrets の KOFI_VERIFICATION_TOKEN / SPONSORS_WEBHOOK_SECRET）は docs/funding.md にあります。

開発

pnpm install
pnpm dev

main に push すると GitHub Actions が GitHub Pages に配信します（リポジトリの Settings → Pages で Source を "GitHub Actions" にしてください）。

モデルの比較（無料枠のモデル選定）

#/bench はナビゲーションに出ない開発用ページです。 設定画面に入れた各社のキーを使い、listen & hear の例文セット（10文 × 2語を並列生成）＋文法チェック＋翻訳テストを候補モデルごとに同条件で実行し、応答時間・トークン数・1回あたりの費用と、審判モデルによる採点（文法・自然さ・訳の質・「頼むまで解説しない」の遵守）を表にします。 結果は「Copy Markdown」で貼り付けられます。 2026年9月の実測は docs/model-bench-2026-09.md にあります。

テスト

pnpm test

ロジック（Vitest）、画面（Playwright で実ブラウザ）、無料枠の Worker（workerd 上の Durable Object）を通しで実行します。AI は一度も呼びません。 個別に走らせるときは pnpm test:unit / pnpm test:ui / pnpm test:worker。 詳細は docs/testing.md にあります。

ヘルプのスクリーンショット

ヘルプ（#/help）のスクリーンショットは pnpm shots で撮り直します（AI は呼びません）。 画面を変えたら実行してください。 手順は docs/help-screenshots.md にあります。

技術

Vite + React + TypeScript、Tailwind CSS v4、shadcn/ui（Base UI）、Dexie（IndexedDB）、Anthropic TypeScript SDK / OpenAI・Gemini REST（JSON Schema 構造化出力）、Cloudflare Workers + Durable Objects（共有キーの回数制限）。

共同開発・フォーク

パブリックリポジトリなので、共同開発したい方も、フォークして続きを開発したい方も大歓迎です（非営利に限ります。条件は下の「ライセンス」を見てください）。 Issue や Pull Request をお気軽にどうぞ。

ライセンス

PolyForm Noncommercial License 1.0.0（全文は LICENSE）。

• 非営利なら、使う・改変する・改変したものを配布することができます。営利目的での利用はできません。
• 配布するときは出所を明記してください。 LICENSE の Required Notice: の行（オリジナルの著作権者とリポジトリの URL）とライセンスの条文（または URL）を、配布物に必ず含めます。
• 「Abduction Learning」の名前とアイコン・ロゴはオリジナル専用です。 改変版を配布するときは別の名前とアイコンにし、オリジナル（またはその公認版）と誤解されないようにしてください。

このライセンスに切り替える前に公開した版は、当時の MIT License のままです。