fs-sync

一个与 Node.js fs 兼容的跨端文件系统库：内置本地缓存，支持将文件自动双向同步到 WebDAV、GitHub、Gitee、RemoteStorage 等远端目标，并提供可插拔的冲突解决与 Provider 扩展机制。

本项目已完成 设计文档 + 可运行的 TypeScript 脚手架（核心实现 + 四个真实 Provider），并通过 77 项单元测试与严格类型检查。

实现状态

• ✅ FS 兼容层 + 本地缓存层（Memory / IndexedDB 双后端，统一 StorageAdapter）
• ✅ 同步引擎（三路差异检测、双向 push/pull/remove、防回声、基线续做）
• ✅ 冲突检测与可插拔解决（lastWriteWins / keepLocal / keepRemote / manual / threeWayMerge，保留落败方副本）
• ✅ 事件总线（statechange / progress / conflict / synced）
• ✅ SyncProvider 抽象 + MemoryProvider 参考实现（同时用作测试远端）
• ✅ 内置真实 Provider：WebDavProvider / GitHubProvider / GiteeProvider / RemoteStorageProvider（零运行时依赖，基于可注入的 FetchLike）

特性

• fs 兼容 API：readFile / writeFile / mkdir / readdir / stat / rename / unlink / rm …，跨端一致。
• 双运行环境：浏览器（IndexedDB 本地缓存）与 Node.js（磁盘）同一套 API。
• 本地优先：离线可读写，联网后自动后台同步。
• 多目标双向同步：可同时挂载多个远端 Provider。
• 冲突解决：默认"最后写入获胜"，策略可插拔（保留双方副本防丢失）。
• 可扩展：实现统一 SyncProvider 接口即可接入任意兼容 fs 的同步目标。

文档导航

| 文档 | 内容 | | --- | --- | | docs/requirements.md | 需求文档：背景、目标、功能/非功能需求、边界与用例、验收标准 | | docs/architecture.md | 架构说明：分层、运行环境适配、同步状态机、数据流、部署形态 | | docs/api.md | 接口文档：FS 兼容接口、StorageAdapter、SyncProvider、ConflictResolver、事件（含 TS 类型定义） | | docs/design.md | 设计文档：本地缓存数据模型、同步引擎算法、冲突检测与解决、Provider 扩展机制 |

核心概念速览

应用代码
  └─ fs 兼容层 (readFile/writeFile/...)
       ├─ 本地缓存层 (StorageAdapter: IndexedDB / 磁盘)
       └─ 同步引擎 (Differ + Executor + ConflictResolver + BaselineStore)
            └─ SyncProvider (WebDAV / GitHub / Gitee / RemoteStorage / 自定义)

• 本地缓存层：环境无关抽象 StorageAdapter，维护目录树、文件内容与元数据（path/mtime/size/contentHash/version）。
• 同步引擎：基于元数据差异检测驱动双向同步；状态机 idle → detecting → pushing/pulling → resolving → finalizing，支持幂等、重试、断点续传。
• Provider：远端统一接口 SyncProvider（authenticate/list/pull/push/remove/stat）。
• 冲突：本地与远端均修改且无共同祖先时触发；默认 lastWriteWins，可插拔 keepLocal/keepRemote/manual/threeWayMerge。

快速开始

npm install
npm test        # 运行 77 项单元测试（Vitest）
npm run build   # 严格类型检查（tsc --noEmit）

使用示例（已可运行）

import { createFsSync, WebDavProvider } from 'fs-sync';

const fs = createFsSync({
  storage: 'memory', // 浏览器中改用 'indexeddb'
  providers: [
    new WebDavProvider({
      name: 'dav',
      baseUrl: 'https://dav.example.com/remote.php/dav/files/user',
      username: 'u',
      password: 'p',
    }),
  ],
  conflictResolver: 'lastWriteWins',
});

fs.on('conflict', (c) => console.warn('冲突:', c.path));
fs.on('synced', (r) => console.log('已同步', r));

await fs.writeFile('/notes/a.txt', 'hello world');
const txt = await fs.readFile('/notes/a.txt', { encoding: 'utf8' });
await fs.syncNow(); // 推送到远端

内置 Provider

| Provider | 说明 | 认证 | | --- | --- | --- | | WebDavProvider | Nextcloud / ownCloud / 坚果云 / Apache mod_dav | 基本认证或 Bearer | | GitHubProvider | GitHub 仓库（Contents + Git Trees API） | Personal Access Token | | GiteeProvider | Gitee 仓库（REST v5，接口同 GitHub） | access_token | | RemoteStorageProvider | remoteStorage 协议（Unhosted） | Bearer（OAuth） |

import { GitHubProvider, GiteeProvider, RemoteStorageProvider } from 'fs-sync';

new GitHubProvider({ owner: 'me', repo: 'notes', token: 't', branch: 'main', basePath: 'docs' });
new GiteeProvider({ owner: 'me', repo: 'notes', token: 't' });
new RemoteStorageProvider({ baseUrl: 'https://storage.example.com/user', token: 't' });

所有 Provider 均零运行时依赖，通过可注入的 FetchLike 传输层实现，默认使用全局 fetch（Node 18+ / 浏览器均可）；测试时可注入自定义 fetch 做离线验证。

实现自定义 Provider

任意"兼容 node fs 的远端"只需实现 SyncProvider 接口即可接入，无需改动核心：

import type { SyncProvider, RemoteMeta, FileMeta, ListOptions } from 'fs-sync';
// 实现 authenticate / list / pull / push / remove / stat

参考 src/providers/MemoryProvider.ts（最小样例）或 src/providers/WebDavProvider.ts / GitContentsProvider.ts / RemoteStorageProvider.ts（真实协议实现）。具体协议调用要点见 docs/design.md §4（WebDAV 走 PROPFIND/GET/PUT/DELETE，GitHub/Gitee 走 Contents API，RemoteStorage 走文件夹列举 + ETag）。

测试覆盖

| 测试文件 | 覆盖内容 | 用例数 | | --- | --- | --- | | test/hash.test.ts | 内容哈希与编解码工具 | 6 | | test/path.test.ts | POSIX 路径归一化 | 3 | | test/storage.test.ts | MemoryStorage 与 IndexedDbStorage 一致性（fake-indexeddb） | 16 | | test/fs.test.ts | FsSync 的 fs 兼容 API | 12 | | test/conflict.test.ts | 五种冲突策略 | 8 | | test/sync.test.ts | 双向推送/拉取/删除同步、防回声、冲突、双客户端收敛、事件 | 9 | | test/webdav.test.ts | WebDavProvider：认证/增删查改/列举 + 端到端同步 | 7 | | test/github.test.ts | GitHubProvider：sha/etag、basePath 映射 + 端到端同步 | 6 | | test/gitee.test.ts | GiteeProvider：access_token 查询参数 + 端到端同步 | 4 | | test/remotestorage.test.ts | RemoteStorageProvider：递归目录列举/stat + 端到端同步 | 6 |

路线图

| 阶段 | 内容 | 状态 | | --- | --- | --- | | M1 | FS 兼容层 + 本地缓存层（浏览器/Node） | ✅ 已实现 | | M2 | 同步引擎（差异检测、双向、重试、状态机） | ✅ 已实现 | | M3 | 冲突检测与可插拔解决 | ✅ 已实现 | | M4 | 内置 Provider（WebDAV / GitHub / Gitee / RemoteStorage） | ✅ 已实现（含端到端测试） | | M5 | 事件总线、可观测性与文档完善 | ✅ 事件总线已实现；文档已完成 |

许可证

待定（建议 MIT）。