mcpField
R
realtime-sync

realtime-sync

github.com/oakoss開発20101 回インストール10 週間前に更新
リポジトリ

realtime-sync について

分散したクライアントとサーバーをつなぐリアルタイム同期アーキテクチャ向けのスキルです。WebTransport、トランザクショナルアウトボックス、CRDTによる共同編集、プレゼンス、AIトークンストリームの処理を扱います。

主な機能

  1. 01WebTransportの双方向・単方向ストリーム
  2. 02トランザクショナルアウトボックス同期
  3. 03CRDTによる共同編集
  4. 04プレゼンスとシーケンス追跡
  5. 05AIストリームのバッチ処理とバックプレッシャー

活用シーン

  1. 01リアルタイム共同編集UIの設計
  2. 02信頼性の高いDBからクライアントへの更新計画
  3. 03プレゼンスとメッセージ欠落への対応
  4. 04画面の揺れを抑えたAIトークンストリームの描画

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/oakoss/agent-skills --skill realtime-sync

インストール後、Claude Code で/realtime-syncを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
ai-stream-orchestration.md
crdt-collaboration.md
pubsub-delivery.md
undo-redo.md
webtransport.md

詳細

リアルタイム同期

概要

分散クライアントとサーバー間の、高並行性かつレイテンシー50ms未満の同期を設計します。WebTransport（HTTP/3）の双方向ストリーミング、データベースと同期の整合性を保つトランザクショナル・アウトボックスパターン、共同編集のためのCRDT、AIトークンストリームのオーケストレーションを扱います。

基本原則は、データベースを信頼できる唯一の情報源とすること（リアルタイムチャネルは通知を行い、永続化はしません）、CRDTで同時編集時のロックをなくすこと、高頻度ストリームによるUIのちらつきをバックプレッシャー管理で防ぐことです。

使用する場面： リアルタイムの共同作業UI、pub/subメッセージング、WebTransport/WebSocket接続、ライブAIトークンストリーム、プレゼンス管理、CRDTによる競合解決、マルチプレイヤーアプリケーション。

使用しない場面： バッチ処理パイプライン、静的コンテンツ配信、リアルタイム要件のないリクエスト／レスポンスAPI、オフライン専用アプリケーション。

クイックリファレンス

パターンアプローチ主なポイント
WebTransportnew WebTransport(url) + await readyHTTP/3で多重化します。新規プロジェクトではWebSocketの代替となります
双方向ストリームtransport.createBidirectionalStream()リクエスト／レスポンス用の { readable, writable } を返します
単方向ストリームtransport.createUnidirectionalStream()一方向のプッシュ用に WritableStream を直接返します
データグラムtransport.datagrams.writable高頻度の状態更新向けに、UDPのような信頼性のない配信を行います
接続統計transport.getStats()smoothedRtt、bytesSent、packetsLost を返します
トランザクショナル・アウトボックス1つのトランザクション内でDB書き込みとアウトボックスへの挿入を行いますCDCワーカーがチャネルに送信し、状態のずれを防ぎます
シーケンス追跡すべてのメッセージにシーケンスIDを付与します再接続時に巻き戻し、取りこぼしたメッセージを取得します
CRDTによる共同作業Yjs（テキスト）またはAutomerge（JSON状態）ロックなしで競合のない同時編集を実現します
CRDTアウェアネスy-protocols/awareness モジュールカーソル、選択範囲、ユーザーのプレゼンスを追跡します
CRDTの元に戻す／やり直しtrackedOrigins を指定した Y.UndoManager選択的な元に戻す操作のため、ローカルユーザーの操作のみを追跡します
プレゼンスハートビートベースのユーザー追跡ゾンビクライアントを確実にクリーンアップするため、エピデミックブロードキャストを使います
AIストリームのバッチ処理トークン描画に requestAnimationFrame を使用します高頻度の更新によるUIのちらつきを防ぎます
バッファリングとバッチ処理同期によってトリガーされる更新に useTransition を使用します同期が集中している間、緊急性の低い再レンダリングを遅延させます
バックプレッシャーバッファーサイズの上限を設定し、強制フラッシュしますトークンの到着が描画より速い場合のメモリ蓄積を防ぎます
WebSocketフォールバックまずWebTransportのサポートを検出します企業のファイアウォールではUDP/HTTP/3がブロックされる場合があります
シリアライズProtocol BuffersまたはMessagePack100Hz以上のストリームではJSON.stringifyを避けます
Web WorkerトランスポートWeb Worker内でWebTransportを処理しますUIスレッドのブロックを防ぎます
チャネルの多重化1つのソケットで複数のチャネルをサブスクライブしますすべてのサブスクリプションで単一のトランスポート接続を共有します

よくある間違い

間違い正しいパターン
リアルタイムメッセージを主要な信頼できる情報源として使う状態はデータベースに保存し、リアルタイム通知は変更を知らせるために使う
高頻度ストリーム（100Hz以上）で JSON.stringify を使うシリアライズには Protocol Buffers または MessagePack を使う
クライアントがメッセージを取りこぼしたときのシーケンスのずれを無視するSequence ID と、クライアント側で巻き戻す仕組みを実装する
並行アクセスにグローバルロックを実装する競合のない共同作業には Optimistic UI と CRDT を使う
多重化が必要な新規プロジェクトでも WebSockets を使い続ける双方向の多重化ストリームには WebTransport（HTTP/3）を使う
上限のない履歴によって CRDT ドキュメントが肥大化する履歴が不要なフィールドにはスナップショット（LWW）を使う
アンマウント時に WebTransport ストリームを閉じ忘れるトランスポートのクラッシュを防ぐため、ストリームを明示的に閉じる
yjs から Awareness をインポートするimport { Awareness } from 'y-protocols/awareness' を使う
UndoManager の追跡対象の origin として ydoc.clientID を使うdoc.transact() に渡すカスタムトランザクション origin を使う
AI のトークンを受信するたびに React が再レンダリングされるrequestAnimationFrame でトークンをまとめ、フレームごとに一度だけフラッシュする
WebTransport の closed プロミスを処理しない予期しない切断を検出するため、transport.closed を監視する

委任

local-first スキルが利用可能な場合は、ローカルファーストアーキテクチャの判断、同期エンジンの比較、クライアントストレージの選定を委任してください。 electricsql スキルが利用可能な場合は、ElectricSQL のシェイプベースの Postgres 同期パターンを委任してください。

  • トランスポートプロトコルの選択肢とレイテンシのベンチマークを調査する：Explore エージェントを使って WebTransport、SSE、WebSocket のトレードオフを比較します
  • CDC パイプラインを使ったトランザクショナル・アウトボックスパターンを実装する：Task エージェントを使ってデータベーストリガー、アウトボックステーブル、バックグラウンドワーカーを設定します
  • 共同編集のリアルタイムアーキテクチャを設計する：Plan エージェントを使って CRDT 戦略、プレゼンス管理、競合解決のフローを策定します
  • 複数ストリームに対応する AI オーケストレーションコンポーネントを構築する：Task エージェントを使ってバックプレッシャーに対応した並列トークンストリームのレンダリングを実装します
  • リアルタイム接続のライフサイクル管理を監査する：Review エージェントを使ってストリームのリーク、クリーンアップ漏れ、再接続処理を確認します

参考資料

コメント

Markdown 対応