AgentSkillsCN

sync

与Supabase、Loro CRDT和IndexedDB实时同步。当在src/lib/sync/中处理文件时使用。

SKILL.md
--- frontmatter
name: sync
description: Real-time sync with Supabase, Loro CRDT, and IndexedDB. Use when working on files in src/lib/sync/.

Sync Guidelines

Core Principles

  1. •Server is source of truth - IndexedDB is a cache
  2. •All ops kept forever - no pruning, enables full audit trail
  3. •Shallow snapshots for fast start - performance only, not compaction
  4. •Encryption at rest - server sees encrypted blobs + plaintext version metadata

Persistence Flow

EventIndexedDBServer
Local changeImmediateThrottled (~2s)
Tab hidden/closeImmediateFlush pending
Cold startLoad snapshot → usableBackground sync

Critical Rules

  1. •IndexedDB writes immediate - crash safety
  2. •Server pushes throttled - use lodash-es throttle, ~2s
  3. •Encrypt before storage - never plaintext in IndexedDB or server
  4. •Version vector plaintext - enables server filtering without decryption
  5. •has_unpushed flag critical - server must send ops (not snapshot) if client has local changes
  6. •Flush on visibility change - don't lose data on tab switch

Key Details

  • •loro-mirror auto-commits on setState() - no manual debouncing
  • •subscribeLocalUpdates fires after each commit with binary update
  • •Snapshot refresh: ops > 1000 OR bytes > 1MB (not time-based)

Conflict Resolution

Loro handles automatically: last-write-wins per field, set union for arrays.

UI States

  • •Saved - all pushed
  • •Saving... - pending in buffer
  • •Offline - can't reach server