markstream-install

Markstream のインストール

「アプリに markstream を追加する」または「壊れた markstream のインストールを修正する」タスクで、このスキルを使用します。

依存関係を選択する前に、references/scenarios.md を読んでください。

ワークフロー

1. 対象フレームワークと CSS スタックを検出します。
   • package.json、アプリのエントリファイル、Tailwind または UnoCSS の設定、およびリポジトリが SSR またはストリーミング重視かどうかを確認します。
   • ホストアプリに一致するパッケージを選択します: markstream-vue、markstream-vue2、markstream-react、markstream-angular、または markstream-svelte。
   • markstream-svelte は Svelte 5 アプリにのみ使用してください。
2. 要求された機能に一致する最小のピアセットをインストールします。
   • ユーザーが実際に必要とする機能のピアのみを追加します。選択したパッケージの peerDependencies を確認してください。ピアの可用性はレンダラーによって異なります。
   • Vue 3 のフェンス付きコードは組み込みレンダラーを自動的に使用します。強化された File/Diff サーフェスには stream-diffs を追加し、自動の <pre><code> フォールバックには省略するか、render-code-blocks-as-pre を設定してプレーンなパスを強制します。
   • インフォグラフィックのフェンスが必要な場合にのみ、@antv/infographic と setInfographicLoader(...) を追加します。
   • デフォルトですべてのオプションのピアをインストールしないでください。
   • Vue 3 の強化されたコードブロックのプリロードには、markstream-vue の preloadCodeBlockRuntime を使用します。アプリケーションが意図的にランタイムコントローラーを所有している場合は、その高度な API を stream-diffs から直接インポートします。
3. CSS の順序を修正します。
   • リセットスタイルを Markstream スタイルの前に配置します。
   • Tailwind または UnoCSS プロジェクトでは、@import 'markstream-*/index.css' layer(components); を使用します。
   • CSS を注入するためにレンダラーのインポートに依存しないでください。パッケージの CSS サブパスを明示的にインポートします。
   • 数式が有効な場合は katex/dist/katex.min.css をインポートします。
4. 最小の動作するレンダー例を追加します。
   • 静的または低頻度のレンダリングには content を使用します。
   • 長い AI 会話、スレッド復元、または vue-virtual-scroller などの既存のメッセージ仮想化ツールを備えた Vue 3 アプリでは、単純なレンダラーで済ませないでください。MarkstreamVirtualTimeline または useMarkstreamVirtualAdapter() を使用し、docs/guide/performance.md に従ってください。
   • Vue 3 では、低レベルのプロパティを調整する前に、サーフェスごとにレンダラーの mode を選択します。
     • mode="chat": AI チャットまたは SSE 出力。軽量バッチ、fade=false、max-live-nodes=0、smooth-streaming="auto"。
     • mode="docs": リッチなドキュメントサーフェス。デフォルトモード、より大きなバッチ、ツールチップ、フェード。
     • mode="minimal": 軽量な非チャットサーフェス。
     • Vue 3 (Nuxt を含む) では、smooth-streaming が出力ペーシングを制御し、fade が不透明度を制御します。これらは同時に有効にできます。mode="chat" は軽量なデフォルトとして fade=false を維持します。テキストの段階的な表示が必要な場合は fade を追加し、アニメーションコストのほうが重要な場合はオフのままにします。
     • 通常のフェンス付きコードは組み込みレンダラーを使用し、インストールされている場合は stream-diffs によって強化されます。強制されたプレーンなパスには render-code-blocks-as-pre を、スコープされたアプリケーション所有のレンダラーには setCustomComponents(customId, { code_block: ... }) を使用します。
   • 他の Markstream パッケージでのストリーミング AI チャットには、content と組み込みのスムーズストリーミングから始めます。
     • 自動モードがデフォルトです: smoothStreaming="auto" / smooth-streaming="auto"。
     • 自動ペーシングは typewriter=true または maxLiveNodes <= 0 / max-live-nodes <= 0 の場合に有効になります。
     • typewriter は点滅カーソルのみを制御し、デフォルトは false です。
     • fade はノードの進入とストリーミングテキストのフェードアニメーションを制御し、デフォルトは true です。
     • 高頻度のスムーズストリームでは、フェードのスタッキングを避けるために fade=false / :fade="false" / [fade]="false" を検討してください。
   • ストリーミングと履歴の復元: チャット UI では、同じレンダラーがストリーミングを開始し、後に final が true になると履歴に切り替わります。
     • Vue 3 ストリーミング: mode="chat"、final、段階的な表示のためのオプションの fade、カーソルのためのオプションの typewriter。
     • Vue 3 の復元/完了したチャット履歴: 同じチャット行で mode="chat" を維持します。:smooth-streaming="false"、typewriter=false を使用し、フェードは独立して選択します。ストリーミング中と履歴表示中の両方で有効のままにしてもかまいません。
     • 軽量な非チャットの復元コンテンツには mode="minimal" を使用し、mode="docs" はリッチなドキュメントサーフェスにのみ使用します。
     • 他のパッケージのストリーミング: smoothStreaming="auto" / smooth-streaming="auto"、fade=false、typewriter=true。
     • 他のパッケージの履歴復元: smoothStreaming=false / smooth-streaming=false、fade=true、typewriter=false。
     • 他のパッケージのオプションポリシー: smoothStreaming={isStreaming ? 'auto' : false}、fade={!isStreaming}。これは必須の組み合わせではありません。
   • nodes + final は、ワーカーでの事前パース、共有 AST ストア、またはカスタム AST 制御にのみ使用します。
   • Vue 3 では、高頻度ストリームでの軽量カーソルに typewriter="simple" を使用します。カーソルが複雑なインラインレイアウトに従う必要がある場合にのみ、精密モードを使用します。
   • 仮想化されていない Vue 3 チャットスクローラーには、markstream-vue/utils から useStickToBottom をインポートします。トークンごとにスムーズな scrollIntoView() アニメーションを開始するのではなく、コンテンツ更新後に scheduleScrollToBottom() を呼び出します。長い混在タイムラインには、stick-to-bottom="auto" を指定した MarkstreamVirtualTimeline を使用します。
   • nodes での手動ペーシングには、useSmoothMarkdownStream を使用します: チャンクを enqueue() し、完了時に finish() を呼び出し、visible からレンダリングし、最終パースの前に caughtUp を待ちます。
   • デフォルトのハードニングを維持します: HTML ポリシーはデフォルトで safe になり、Mermaid はデフォルトで厳格モードで実行されます。
5. カスタマイズはスコープ内に保ちます。
   • タスクでオーバーライドが必要な場合は、customId / custom-id とスコープされた setCustomComponents(...) を優先します。
6. 検証します。
   • 最小の関連するビルド、型チェック、テスト、またはドキュメントビルドコマンドを実行します。
   • どのピアがインストールされたか、CSS がどこにあるか、リポジトリが後で nodes を採用すべきかどうかを報告します。

デフォルトの選択

• 「すべてインストールする」より、最小限の依存パッケージセットを優先してください。
• Vue 3 では、リッチなドキュメント向けのデフォルト設定を使用する場合に限り、mode を省略してください。
• Vue 3、Vue 2、React、Svelte、Angular のすべてで組み込みのスムーズストリーミングが利用できるようになったため、現在はほとんどの場合に content を優先してください。
• 別のレイヤーがパースや AST 変換を担当する場合に限り、nodes に切り替えてください。
• すでにメッセージを仮想化している Vue 3 アプリでは、マウントする行の管理を外側の仮想化機構に任せてください。アイテムの高さをレンダラーの DOM の高さではなく metrics.totalHeight から取得するよう、Markstream の仮想スクロール連携を使用してください。
• ストリーミングに content を使う場合、typewriter または max-live-nodes <= 0 では、スムーズストリーミング（smooth-streaming="auto"）がデフォルトで有効です。生のチャンク間隔を維持するには、:smooth-streaming="false" を設定してください。
• ストリーミングと履歴の復元では、レンダラーモードを一定に保ってください。Vue 3 ではフェードはペーシングと独立しているため、ストリーミング中も有効にできます。他のパッケージ向けにフェードを無効にする保守的なストリーミング例は、API 上の制約ではありません。これらのアダプターには、Vue 3 の有界フェード実装がまだ採用されていません。Vue 3 の例は docs/guide/ai-chat-streaming.md を参照してください。
• CSS の読み込み順は、後から整理するものではなく、インストールの重要な一部として扱ってください。
• SSR を含むリクエストでは、ブラウザー専用の依存パッケージをクライアント専用の境界で明示的に制御してください。
• ユーザーが信頼できるレガシー互換性を明示的に必要としていない限り、HTML や Mermaid のセキュリティに関するデフォルト設定を緩めないでください。
• すべての Markstream パッケージで、拡張コードブロックには stream-diffs を使用します。現行バージョンには stream-monaco も Shiki の直接統合もありません。
• 直接使用する CodeBlockNode とトップレベルのレンダラー設定では、同じ codeBlockOptions / CodeBlockOptions の契約を使用します。コンポーネントの外観に関する設定は codeBlockProps に置き、そこに実行時オプションをネストしないでください。
• Vue 3 では、上流の @pierre/diffs の WorkerPoolManager を setStreamDiffsWorkerPool(...) から注入すると、大きなコードブロックのハイライトをメインスレッド外で実行できます。ホスト側で独自のバンドラーを使ってプールを構築し、@pierre/diffs を直接の依存パッケージとして追加してください。これは Vue 3 限定の拡張機能であり、他のフレームワーク向けパッケージでは公開されていません。
• 互換性のために必要な場合は、アプリ全体のデフォルト設定をむやみに変更せず、信頼できる対象範囲にオプトアウトを限定し、htmlPolicy / html-policy="trusted" と mermaidProps.isStrict = false を使用してください。

便利なドキュメント

• docs/guide/installation.md
• docs/guide/usage.md
• docs/guide/performance.md
• docs/guide/troubleshooting.md
• docs/guide/component-overrides.md