マニュアル解説アプリビルダー

Manual Explainer（マニュアル解説アプリビルダー）

マニュアルから、自己完結型のHTML「レッスンアプリ」を構築します。 各ページは画像として表示され、各ステップは中国語・韓国語・英語でナレーション（ブラウザのテキスト読み上げ、文単位のハイライト付き）され、学習者はいつでも ✋ 打断提问（中断して質問） を押せます。 これにより、ナレーションが文の途中で一時停止し、学習者の現在位置を認識した質問パネルが開き、マニュアルから [p.N] ページリンク付きで回答し、 ▶ 继续讲解（続ける） で中断した文から再開します。

アプリの品質は、ほぼステップ2（理解）とステップ3（レッスン設計）に依存します。スクリプトは機械的な処理を担当します。

ワークフロー

1. 抽出（Extract）

SK=<このスキルのディレクトリ>
python $SK/scripts/extract_manual.py "/mnt/user-data/uploads/<ファイル名>" /home/claude/mx

対応フォーマット：pdf、pptx、ppt、docx、doc（すべてPDFを経由するため、ページ番号が画像と一致します）。出力先 /home/claude/mx：content.md（[[pN]] マーカー付き全文、pptxの発表者ノート、docxの見出しアウトライン）、content.json、pages/pN.jpg。印刷されたレポートには image_heavy_pages とマスキングされた機密情報の数が表示されます。

PPTXスライドが、スライド横のテキストボックスにノートがある大きな画像1枚構成の場合、抽出プログラムはその画像をネイティブ解像度でページ画像として使用します（warnings に報告）。これによりスライドがより大きく鮮明に表示されます。

ファイルが添付されていない場合は、ファイルの提供を依頼してください。ファイルがスキャンされたPDFでテキストがない場合（total_chars が0に近い）、ページ画像を目で読み、あなた自身が知っている情報から knowledge を作成してください。

2. マニュアルを完全に理解する — 設計の前に

content.md を最初から最後まで読んでください（長い場合は view でチャンクごとに読んでください）。その後、すべての image_heavy ページ、およびテキストが図、画面、パネル、配線図、表、ボタン配置を参照しているページのページ画像を view で確認してください。これらのビジュアルはマニュアルの核心であることが多く、テキスト抽出では見落とされます。

動作モデルを構築し、メモを /home/claude/mx/notes.md に保存してください。

• 製品/プロセスとは何か、読者は誰か、読者はその後何ができるようになる必要があるか
• 実際の構造：セットアップ→通常操作→設定→メンテナンス→トラブルシューティング、またはマニュアルが実際に使用している構造
• すべての手順とその順序、前提条件、期待される結果
• すべての警告 / 注意 / 危険通知（これらは、意味において一字一句そのままレッスンに反映されなければなりません）
• スペックと数値（圧力、電圧、タイミング、制限値）とそのページ
• 学習者が知っておくべき用語（→ 用語集）
• 矛盾点、ギャップ、不明瞭な点 — 推測せずに、最後にユーザーにその旨を伝えてください

3. レッスンを設計 → /home/claude/mx/lesson.json

正確なフォーマットとナレーションルールについては、references/lesson_schema.md を参照してください。 設計原則：

• 読み上げるのではなく、教える。 必ずしもページ順ではなく、学習者が最初に必要とするものの順序で並べてください。標準的なサイズ：3〜10章、各章2〜8ステップ、1つのアイデアにつき1ステップ。
• 各ステップは、最も関連性の高いページ画像（image）を表示し、すべての補足ページを page_refs にリストします。
• ナレーションは 理由 と 何が問題になるか を説明し、ページ画像に表示されているものを指し示し、話されるように書かれています。
• すべての安全警告を、該当するステップの warning に引き継いでください。
• 各章に1〜3問の実務で重要なことに関するクイズ問題（手順の順序、制限値、警告）— 雑学ではありません。
• knowledge = content.md のクリーニングされた全文で、[[pN]] マーカーが付いたもの（ページのヘッダー/フッターと繰り返される定型文は削除し、表は保持）。重要な図版の簡単な説明を、該当するページマーカーの下に追加してください（チューターがそれらについても回答できるように）。
• カバレッジチェック： 表紙、目次、空白ページ、法的ページを除き、すべてのページが何らかのステップの image または page_refs に含まれている必要があります。ビルドレポートに uncovered_pages が表示されます。実際のコンテンツを含むページのギャップを修正してください。
• 言語（デフォルト：中文 / 한국어 / English）： すべてのレッスンを3言語で構築します — "languages": ["zh","ko","en"] — これにより、学習者はアプリのヘッダーでいつでも切り替えられます。language（デフォルト）は、ユーザーがあなたに話しかけている言語に設定してください。ユーザーが明示的に依頼した場合のみ、言語数を減らしてください。すべての表示テキスト（タイトル、ナレーション、箇条書き、警告、クイズ、用語集）は、{"zh":…,"ko":…,"en":…} オブジェクトになります。1つでも欠けているとビルドは実行を拒否します。各言語は、他の2つの言語の直訳ではなく、ネイティブに話されるように書き、警告はすべての言語で同等に厳格にしてください。knowledge はマニュアルの元の言語のままにしてください — チューターはそれを読み、選択された言語で回答します。 マニュアルに表示されている画面上のラベル（ボタン名、アラームコード）は、すべての言語で最初に登場するときはそのまま保持してください。
• 長いマニュアルの場合は、最初にデフォルト言語でレッスンを書き、カバレッジを確認してから、他の2つの言語をフィールドごとに追加してください。

4. ビルド（Build）

python $SK/scripts/build_app.py /home/claude/mx/lesson.json /home/claude/mx /mnt/user-data/outputs/<名前>-讲解.html

ビルドはレッスンを検証し（LESSON ERROR の場合は修正して再実行）、機密情報を再度マスキングし、ページ画像を約14.5 MiBの予算内に収め（公開ページは16 MB未満に抑える必要があります）、レポートを出力します。画像はWebP形式で、同一ページは1回だけ保存されます。ステップ画像は常に埋め込まれ、最もシャープに保たれます（最大1800px、拡大はなし）。page_refs にのみリストされているページは小さく埋め込まれ、収まらないものはテキストのみの引用として表示されます。非常に長いマニュアル（数百ページ）の場合は、ステップ画像を明確で必須のページに限定してください。 ページ画像（スクリーンショット、スライドテキスト）内に表示される資格情報はテキストスキャンで検出されません。ビルド前に pages/pN.jpg で黒く塗りつぶしてください。 1つのマニュアルのためにテンプレートのロジックを手動で編集しないでください。lesson.json を変更してください。

5. 提供（Deliver）

• Artifactツールが存在する場合（claude.ai）： capabilities: {"sample": {}} とファビコン 📘 を付けてHTMLを公開してください。sample により、アプリ内のチューターがClaudeに質問できます。他のcapabilitiesは宣言しないでください。
• その他の環境（Claude Code、Cowork、Artifactツールがない場合）： HTMLファイルを提示してください。プレーンファイルとして開かれた場合、質問パネルはマニュアルを検索し、最も関連性の高い元のパッセージをページ番号とともに表示するフォールバック機能を使用します。

その後、ユーザーの言語で簡潔に回答してください：章リストを1〜2行で、使用方法（▶ 再生、✋ いつでも中断、キーボード：Space / ← → / Q）、最初の質問でClaudeの使用許可を求めること、およびマニュアルで見つけたギャップや矛盾点があればそれについて。

6. 反復（Iterate）

変更（「第3章をもう少し詳しく」「再生速度が速すぎる」「トラブルシューティングの章を追加」など）については、lesson.json を編集し、再ビルドして、同じアーティファクトに再公開してください（その url を渡してください）。

セキュリティ（企業文書）

マニュアルには、アカウント名、デフォルトパスワード、認証情報付きIP、ライセンスキー、顧客データが含まれる場合があります。

• 両方のスクリプトは、パスワード、トークン、キー、秘密鍵、認証情報付き接続文字列を自動的にマスキングします。これらの値をナレーション、箇条書き、またはあなたの返信にコピーしないでください。N個のアイテムがマスキングされたことと、その種類のみを報告してください。
• マニュアルのデフォルト認証情報が手順の一部である場合（例：「管理者として初期パスワードでログイン」）、そのステップを説明し、そのページを指し示してください（「初期パスワードはマニュアル12ページ、または管理者にお問い合わせください」） — 値を記載する代わりに。
• マニュアルを外部サービスにアップロードしないでください。すべての処理はローカルおよび公開ページ内で実行されます。

アプリの機能（ユーザーからの質問に答えるため）

• ヘッダー：タイトル、言語切り替え（中文 / 한국어 / EN — 切り替えても現在のステップは保持され、レッスン中または質問パネル内でも機能）、🔊 音声パネル、速度 0.8〜1.5倍、進行状況バー。
• 音声：アプリはブラウザの音声をランク付けし、最も自然なものを自動選択します（Edge "Natural/Online" ニューラル音声 > Apple Enhanced/Premium > Google音声 > その他）。🔊 パネルに一覧表示され（★ = 自然）、プレビュー機能があり、言語ごとに選択を記憶します。ロボット音声しかない場合はその旨を表示し、Edge / Google音声 / 拡張音声のダウンロードを提案します。録音済み音声は不可能です。公開ページはTTSサービスを呼び出せず、音声はサイズ制限を超えます。
• コンテンツ引き出し（モバイルでは ☰）：章、ステップ（訪問済みはマーク付き）、クイズ、用語集。
• ステップカード：ページ画像、タイトル、重要ポイント、警告、現在の文がハイライトされたナレーション、ページチップ。
• 🖼 大スライドモード（デフォルトON）：コンテンツは ☰ 引き出しに移動し、スライドが狭いテキスト列の横の画面高さ全体に表示されます（狭い画面では縦に積み重なります）。切り替えはビューアごとに記憶されます。
• ページビューア（スライド、ページチップ、[p.N]リンクをタップ）：ピンチ/マウスホイールで最大6倍ズーム、ドラッグでパン、ダブルタップでズーム、− ⤢ + ボタン、‹ › で埋め込まれたすべてのページをめくる、キーボード + − 0 ← → Esc。縦長の電話では、横向きにするよう提案します。
• 自動再生はステップをまたいで続き、各章のクイズで停止します。
• ✋ 質問パネル：現在位置を示すコンテキスト行、提案チップ（もう一度 / もっと簡単に / 例を挙げて / なぜ重要か / よくある間違い）、クリック可能な [p.N] 付きのストリーミング回答、停止ボタン、▶ 続けるで中断した文から再開。
• 位置、音声、速度はビューアごとに記憶されます。
• 音声はビューアのブラウザ/OSに依存します。一致する音声がない場合でも、アプリはハイライト表示で読み上げ時間を進めます。