markstream-migration

Markstream の移行

リポジトリですでに Markdown をレンダリングしていて、Markstream を安全に導入する場合、または既存の markstream-vue 1.x 統合を 2.x にアップグレードする場合に、このスキルを使用します。

移行ルートの選択

コードを変更する前に、package.json、ロックファイル、インポート、レンダラーのプロパティを確認してください。

• リポジトリがすでに markstream-vue 1.x に依存している場合は、references/vue-1x-to-2x.md を読み、ルート B に従ってください。MarkdownCodeBlockNode や InternalParseOptions のように、他のアダプターにも現れる可能性がある共通の名前だけでルートを決めず、パッケージの依存関係を確認してください。
• それ以外で、react-markdown、markdown-it、marked、または別のレンダラーを Markstream パッケージに置き換える場合は、references/adoption-checklist.md を読み、ルート A に従ってください。
• 両方に該当する場合は、まず 1.x から 2.x へのパッケージと API のアップグレードを完了してから、個別のレンダラー置き換えを導入タスクとして監査してください。

ルート A：別のレンダラーから Markstream に移行する

1. リポジトリで現在使われているレンダラーを調査します。
   • Markdown レンダラー、プラグインチェーン、生 HTML の処理、セキュリティ用 props、カスタムレンダラーを検索します。
   • 変更対象となる呼び出し箇所をすべて列挙します。
2. 移行の種類を分類します。
   • direct：文字列を受け取るレンダラーの単純な置き換えです。
   • renderer-custom：カスタムレンダラーはありますが、パーサーの作業は限定的です。
   • plugin-heavy：remark、rehype、markdown-it、またはその他の変換処理が多いパイプラインです。
   • security-heavy：許可リストまたは禁止リスト、URL の書き換え、サニタイズ、または生 HTML のポリシーが関わります。
3. まずレンダラーを置き換えます。
   • 適切な Markstream パッケージと CSS を導入します。
   • Markstream の CSS はパッケージの CSS サブパスからインポートします。レンダラーのインポートによるスタイル注入には依存しないでください。
   • Markstream 独自の高度な機能を追加する前に、ユーザーに見える動作を維持します。
   • 以前のレンダラーが広範な生 HTML や Mermaid の loose-mode HTML ラベルを許可していたかどうかを確認してから、同等性を主張します。
4. カスタムレンダラーを移行します。
   • 組み込みノードレンダラーを、スコープを限定したノードタイプのオーバーライドに変換します。
   • React では、パーサーが処理するタグにはレンダラーローカルの streamingComponents を、サニタイズ済み HTML の props を持つコンポーネントには htmlComponents を優先します。組み込みノードのオーバーライドや共有の互換性登録には setCustomComponents を使用します。
   • Svelte または Angular では、マッピングに共有登録が不要な場合、レンダラーローカルの customComponents 入力を優先します。
   • 信頼できるタグ形式のコンテンツには、customHtmlTags を優先します。
   • 以前のパイプラインでトークンや AST の変換が本当に必要な場合に限り、parseOptions.preTransformTokens、postTransformTokens、または postTransformNodes を使用します。
5. 差分を正直に確認します。
   • 1 対 1 の同等性がない場合は、それを主張しないでください。
   • 手動確認が引き続き必要なパーサー、プラグイン、セキュリティ、または HTML の動作を明示します。
6. nodes に進む前に、レンダラーモードとスムーズなストリーミングを検討します。
   • Vue 3 では、AI/SSE 出力には mode="chat"、リッチなドキュメント表示には mode="docs"、軽量な非チャット表示には mode="minimal" を選びます。
   • アプリが content をストリーミングし、ペース調整だけが必要な場合は、smooth-streaming="auto"（デフォルト）が処理するため、nodes は不要です。
   • アプリでカスタム AST 制御、ワーカーによる事前解析、または高頻度の構造更新が必要な場合に限り、nodes に移行します。
   • Vue 3（Nuxt を含む）では、smooth-streaming は出力のペースを制御し、fade は不透明度を制御します。両方を同時に有効にできます。mode="chat" では、軽量なデフォルトとして fade=false が維持されます。テキストを徐々に表示したい場合は fade を追加し、アニメーションの負荷を優先する場合は無効のままにします。ホスト側でそのポリシーが必要でない限り、Vue 3 への移行時に従来の :fade="!isStreaming" バインディングを引き継がないでください。
   • ストリーミングと履歴の再表示：チャット UI を移行する場合は、同じチャット行で mode="chat" を維持し、ペース調整やアニメーションの props を切り替えます。Vue 3 のストリーミングでは、mode="chat"、final、必要に応じて fade を使用します。Vue 3 の完了済みチャット履歴では、mode="chat" を維持し、ペース調整が不要な場合は :smooth-streaming="false" を使用して、fade は個別に選択します。別のリッチなドキュメント表示に限り、mode="docs" を使用します。
7. 検証して要約します。
   • 関連する最小限のテストまたはビルドを実行します。
   • 直接置き換えられる箇所、TODO、残る検証作業を報告します。

ルート B：markstream-vue 1.x から 2.x へのアップグレード

1. 現在の統合範囲を固定します。
   • インストール済みの markstream-vue のバージョンと、パッケージマネージャーによる解決結果を記録します。
   • 古いコードブロック依存関係、レンダラーの値、プロパティ、公開型、ランタイムヘルパー、プレビューのハンドラー、パーサーの直接インポートを確認します。
   • 現在の動作を保証するために必要な、最小限のビルド、型チェック、SSR、コードブロックの確認項目を特定します。
2. いずれかのリリース系列を選びます。
   • 調整済みのベータ系列が公開され、next がその世代を解決するようになってから使用するか、安定版のリリース後に markstream-vue@2 を使用します。
   • マニフェストを編集する前に、レジストリのバージョンと dist-tag を確認します。リポジトリ内のバージョン更新だけでは、パッケージをインストールできることの証明にはなりません。
   • アプリケーションで使用するアダプターだけをインストールします。パーサーまたはコアは、アプリケーションから直接インポートする場合にのみ追加します。
   • パッケージは同じプレリリース世代にそろえ、互いに関係のないベータ版を混在させないでください。
3. references/vue-1x-to-2x.md に記載された、必要な依存関係と API の変更だけを適用します。
   • 以前のコードブロックランタイムを両方削除します。サポート対象の monacoOptions / codeBlockMonacoOptions フィールドを共通の codeBlockOptions 契約に合わせて名前変更し、サポート対象外の Monaco 専用フィールドは削除します。
   • 拡張コードブロックまたは差分ブロックが必要な場合にのみ stream-diffs を追加します。それ以外の場合は、プレーンなフォールバックを使用します。
   • ドキュメントに記載された 2.x の破壊的変更で変更が必要な場合を除き、既存の Markdown、図、数式、HTML ポリシー、ワーカー、CSS、ストリーミング、仮想化の設定は維持します。
4. 移行後の動作を検証し、ロールバック手段を残します。
   • 必要に応じて、パッケージの解決、公開型、プレビューペイロードの利用側、通常のフェンスと差分フェンス、テーマ、レスポンシブな差分レイアウト、SSR またはパック済みインストールを確認します。
   • 以前の系列に戻すための、正確な 1.x バージョンまたは旧 dist-tag を報告します。

デフォルトの判断

• まずレンダラーを切り替え、ストリーミングの最適化はその後に行います。
• 既存の Markstream バージョンのアップグレードを、レンダラー採用に伴う全面的な書き換えとして扱わないでください。
• 1.x から 2.x への移行では、ドキュメントに記載されたコードブロックとパーサーの変更以外、アプリケーションの動作を維持します。
• 調整済みのベータ系列は、同じプレリリース世代にそろえます。また、依存関係を変更する前にロールバック方法を明確にします。
• スムーズなストリーミングは、「コンテンツのみ」と「ノードへの全面移行」の中間的な選択肢です。AST を制御しなくても、表示される出力を段階的に表示できます。
• HTML やセキュリティ規則が関わる場合は、機能の同等性より安全性を優先します。
• 曖昧な主張ではなく、明示的な TODO を優先します。
• 対象フレームワークがコンポーネントマップを公開している場合は、レンダラー内のコンポーネントマップを優先します。
• 現在のスタックが Markstream では直接再現できない変換に大きく依存している場合は、移行を推奨しません。
• 信頼された従来の動作を維持する必要がある場合は、デフォルト設定を全体的に弱めるのではなく、スコープを限定した htmlPolicy / html-policy="trusted" と mermaidProps.isStrict = false を使用します。

参照先として役立つドキュメント

• docs/guide/migration-2-0.md
• docs/guide/react-markdown-migration.md
• docs/guide/react-markdown-migration-cookbook.md
• docs/guide/ai-chat-streaming.md
• docs/guide/installation.md
• docs/guide/component-overrides.md
• docs/guide/advanced.md