元表現: 読解ガイド係 / StudyGuide ブロック詳細
本文を1文ずつに分けて、区切り・訳・語句の説明を付けて返すブロック。受け取るのは本文だけで、学習者の事情は一切渡されません。
抽象度 Lv.4(技術用語+システム上のやりとりまで/製品名・ライブラリ名は書かない)本文を受け取り、1文ずつに分けて、区切り・訳・語句の説明を付けて返すブロック。 このアプリの中心的な成果物を作る場所で、外部の言語モデルを使う。
ただし、このブロックが受け取るのは本文だけ。 誰が使うのか、過去に何を出題したか、どの語を覚えたかは一切渡されない。
2. 処理オーケストレーション → 3. 読解ガイド生成 → 2番へ返す → 6番(材料の1つとして)/7番(保存される)
6番より前でなければならない。6番(単語テスト)は読解ガイドを材料の1つとして受け取る。 本文だけからでも問題は作れるが、読解ガイドがあると「その文の中でどう使われているか」を踏まえられる。
2番から本文以外を渡していないのは意図的。 過去の出題履歴や習得状態を渡せば、3番の出力も履歴に引きずられる。 3番には「この本文を、初めて読む中1に説明する」ことだけをさせ、学習者ごとの事情は4・5・6に閉じ込めている。 その結果、同じ本文からは(モデルのゆらぎを除けば)誰に対しても同じ読解ガイドが出る。
2-3で真っ先に開始されるのも、ここが一番遅いから。待ち時間を他の読み出しで埋めている。
| 工程 | 主体 | やりとりの内容 | 方向 |
|---|---|---|---|
| 3-1 | 2番本体 → 3番本体 | 本文(それ以外は渡されない) | → |
| 3-2 | 3番本体(内部) | 指示書・本文・受け取る書式を組み立てる | ↻ |
| 3-3 | 3番本体 → 外部モデル | 指示書+本文+書式の指定+利用者を表す印 | → |
| 3-4 | 外部モデル → 3番本体 | 文ごとの原文・区切り入り・訳・説明 | ← |
| 3-5 | 3番本体(内部) | 書式に合っているかの点検 | ↻ |
| 3-6 | 3番本体(内部) | 文番号を1から振り直す | ↻ |
| 3-7 | 3番本体 → 2番本体 | 読解ガイド一式 | ← |
3-1 2番から本文だけが渡される。本のタイトルもページ番号も、利用者が誰かも渡されない。3番は「この英文を説明せよ」以上の文脈を持たない。
技術的には HTTPではなく関数呼び出し。引数は本文の文字列1つと、外部へ添えるための32桁の識別子だけ。3番には専用のパスが無いので、外から /api/... で直接呼ぶことはできない。
3-2 3番本体は、あらかじめ用意された指示書(中1向けに、どう説明するかの決め事)と、受け取った本文を組み立てる。同時に、返してほしい形も用意する。「文ごとに、原文と、区切りを入れた形と、訳と、説明を1〜6項目」という決まった枠。この組み立ては自分の中だけの処理。
技術的には 送るメッセージを2つの役割に分ける。system=前提として常に効かせる指示書、user=今回の入力(本文)。分けておくと、本文の中にたまたま命令のような文が混じっていても、指示側と取り違えにくくなる。あわせて、返してほしいJSONの型を用意する。
3-3 外部モデルへ送る。2-2で作られた利用者を表す印も一緒に添える。
技術的には HTTPSでJSONをPOSTする。「推論にかける手間=中」「返す量=中」を指定。やり取りを相手側に保存しない設定にし、2番が作った32桁の識別子を添える。
3-4 モデルから、枠に沿った形で返ってくる。自由な文章ではなく、最初に指定した項目に分かれた状態で返る。
技術的には 型どおりのJSONが返る。文の配列で、各文が通し番号・原文・区切りを入れた形・訳・説明(1〜6項目)を持つ。
3-5 返ってきたものが枠に合っているかを点検する。説明が0項目だったり7項目以上だったり、訳が空だったりすれば、受け取り自体が失敗になる。3番には作り直しの仕組みがない。(6番にはある。)合わなければそのまま止まる。
技術的には 受け取ったJSONを型に当てはめて検証する。配列が空、説明が0項目または7項目以上、訳が空文字 ── どれもこの時点で例外になる。3番は作り直しをしないので、例外はそのまま2番へ上がり、最終的にブラウザへは 500 が返る。
3-6 点検を通ったら、文の番号を1から順に振り直す。モデルが付けてきた番号は使わない。地味な工程だが、これがないと後段が壊れる。
技術的には 配列の並び順に沿って、通し番号を1から付け直す。モデルが付けてきた番号は捨てる。音声の取得が GET /api/guides/{id}/speech?sentence=3 のように、番号をクエリ文字列の鍵として使うため、1から抜けなく並んでいることが前提になっている。番号が飛べば、押した文と違う音声が鳴る。
3-7 2番へ返す。2番はこれを6番の材料にし、7番に保存させる。
技術的には 関数の戻り値として2番へ返すだけ。3番はファイルに何も書かない。
主体が3つなので、この図は画面の幅に収まります
| どこで失敗するか | 何が起きるか |
|---|---|
| 3-3/3-4 のモデル呼び出し | 例外が上がり、2番を通って 500「英文読解ガイドを生成できませんでした」 |
| 3-5 の点検 | 同上(500)。作り直しはしない |
| いずれの場合も | 6番も7番も走らない。ページは作られない。並行して走っていた4・5の読み出しは無駄になる |
利用者の画面にどう出るか、再試行の導線があるかは未確認。
※ この解説は、2026年8月14日時点の studyguide のプログラムを読んで作成しました。
※ 抽象度は Lv.4 で統一しています。通信の方式・データの形式・認証のしくみ・ステータスコードまでは書き、製品名やライブラリ名、関数名までは踏み込みません(そこは Lv.5)。
※ 工程の番号は全体図の番号と対応しています。全体図はこちら。