@eeymoo/ai-coding-sync

AI-Coding-Sync

基于 Bun + TypeScript 的命令行工具，用于通过 WebDAV 在多台设备之间同步 AI 编码工具配置与工作目录。

它面向 .claude、.cursor、.opencode 等 AI 开发工具场景，支持多 profile、源目录类型与部署方式分离的同步模型（sourceType + deployMode）、远程锁、安全扫描、钩子扩展与配置校验。

为什么需要它

如果你会在多台设备之间切换开发环境，通常会遇到这些问题：

Claude / Cursor / OpenCode 配置分散在不同机器
提示词、agents、skills、插件配置难以统一
手工复制容易遗漏，且不安全
同步过程中缺少冲突控制与审计能力

ai-coding-sync 旨在提供一个统一的 CLI，同步这些 AI coding 配置，并尽量保持：

可配置
可审计
可扩展
对多设备友好

核心特性

WebDAV 同步后端
- 使用 WebDAV 作为远程存储
- 适合自建 NAS、坚果云、Nextcloud 等场景
二维同步模型
- sourceType：描述 .ai-coding-sync 下源目录是否为 Git 仓库，可取 auto / git / file
- deployMode：描述部署到目标位置时使用 link（ln -s）或 copy（cp）
- 组合后形成 git/file × link/copy 的 2×2 同步矩阵
多 profile 配置
- 支持不同设备、不同工作环境使用不同配置
- 可覆盖 sourceType、deployMode、strategy、conflict、webdav 等选项
多 mapping 管理
- 可同时同步多个本地目录到远端不同路径
- 每个 mapping 可独立配置 profile / sourceType / deployMode / ignore / hooks
安全与诊断
- 敏感信息扫描
- 日志脱敏
- 默认敏感文件忽略
- doctor 环境诊断
- 配置 schema 校验
并发控制
- 基于 WebDAV 锁文件的分布式锁
- 支持 TTL 与重试机制
- 降低多设备同时写入冲突风险
可扩展自动化
- 支持 pre-sync / post-sync / on-conflict hooks
- 便于接入自定义脚本流程

技术栈

Runtime: Bun
Language: TypeScript
Validation: Zod
Test: Bun test
Docs: TypeDoc
Lint / Format: ESLint + Prettier

安装

前置要求

Bun
一个可用的 WebDAV 服务端
macOS / Linux / 其他类 Unix 环境优先

安装依赖

bun install

本地开发运行

bun run dev -- --help

作为 CLI 使用

项目已在 package.json 中声明 bin：

{
  "bin": {
    "ai-coding-sync": "./src/index.ts"
  }
}

如需全局或本地链接，可按 Bun/包管理器常规方式处理。

快速开始

1. 初始化配置

bun run dev -- init

2. 查看状态

bun run dev -- status

3. 执行同步

bun run dev -- sync

4. 推送或拉取

bun run dev -- push
bun run dev -- pull

配置说明

项目使用统一配置文件描述 WebDAV、profiles、mappings、hooks 等内容。

配置能力概览

syncId：标识当前设备
webdav：远端地址、认证与请求选项
profiles：按场景覆盖主配置，可定义默认 sourceType 与 deployMode
mappings：定义源目录、目标目录与远端目录的同步关系，并可单独覆盖源类型与部署方式
ignoreGlobal：全局忽略规则
hooks：同步生命周期钩子

示例配置

{
  "version": "1",
  "syncId": "macbook-pro",
  "webdav": {
    "endpoint": "https://dav.example.com",
    "auth": {
      "type": "env",
      "username": "your-name",
      "password": null
    },
    "remoteRoot": "/ai-coding-sync",
    "options": {
      "depth": "infinity",
      "verifySsl": true,
      "timeout": 10000,
      "maxRetries": 2,
      "concurrency": 4
    }
  },
  "profiles": {
    "work": {
      "sourceType": "git",
      "deployMode": "link",
      "strategy": "two-way",
      "conflict": "backup"
    },
    "personal": {
      "sourceType": "file",
      "deployMode": "copy",
      "strategy": "push-only"
    }
  },
  "mappings": [
    {
      "name": "claude",
      "sourcePath": "~/.ai-coding-sync/claude",
      "local": "~/.claude",
      "remotePath": "/configs/claude",
      "profile": "work",
      "respectGitignore": true
    },
    {
      "name": "cursor",
      "sourcePath": "~/.ai-coding-sync/cursor",
      "local": "~/.cursor",
      "remotePath": "/configs/cursor",
      "sourceType": "auto",
      "deployMode": "copy",
      "ignore": ["*.log", "*.tmp"]
    }
  ],
  "ignoreGlobal": [".DS_Store", "*.swp", "*.tmp"],
  "hooks": {
    "pre-sync": null,
    "post-sync": null,
    "on-conflict": null
  }
}

同步模型

项目中的同步行为由两个正交维度组成，而不是单一 mode：

`sourceType`

用于描述 .ai-coding-sync 下对应源目录的类型。

`auto`

自动检测源目录是否为 Git 仓库：如果存在 .git，则按 git 处理；否则按 file 处理。

`git`

显式声明源目录是 Git 仓库。

适合：

配置本身就放在仓库中
希望保留版本历史、分支和提交上下文
需要以仓库状态辅助同步策略

`file`

显式声明源目录只是普通文件目录，不依赖 Git 元数据。

适合：

普通配置目录
不需要仓库语义的同步内容
想直接管理纯文件结构的场景

`deployMode`

用于描述如何把 .ai-coding-sync 下的 sourcePath 源目录部署到 local 目标位置。

`link`

使用 ln -s 将目标位置连接到源目录。

适合：

希望所有真实内容都集中保存在 .ai-coding-sync 中
目标位置只是一个入口
希望修改源目录后立即在目标位置生效

`copy`

使用 cp 将源目录内容复制到目标位置，不依赖软链接。

适合：

不希望使用软链接
目标程序对符号链接兼容性一般
希望目标位置保留实体文件副本

组合关系

默认建议把所有真实配置放在 ~/.ai-coding-sync/<mapping-name> 之类的源目录中，再通过 sourcePath -> local 的方式进行部署。

最终同步行为是一个 2×2 矩阵：

git + link
git + copy
file + link
file + copy

CLI 命令

基本命令

Command	Description
`init`	初始化配置并测试首轮连接
`sync`	执行默认双向同步流程
`push`	将本地内容推送到远端
`pull`	将远端内容拉取到本地
`status`	查看同步状态与映射信息
`doctor`	诊断环境、配置与依赖问题
`config get <key>`	读取配置项
`config set <key> <value>`	修改配置项

全局选项

Option	Description
`--profile <name>`	使用指定 profile
`--source-type <type>`	覆盖源目录类型（auto/git/file）
`--deploy-mode <mode>`	覆盖部署方式（link/copy）
`--dry-run`	预览操作，不执行真实写入
`--force`	跳过部分保护性确认
`--yes`	自动确认提示
`--verbose`	输出更详细日志

示例

bun run dev -- status
bun run dev -- sync --profile work
bun run dev -- sync --source-type auto --deploy-mode link
bun run dev -- push --dry-run
bun run dev -- doctor --verbose
bun run dev -- config get webdav.endpoint
bun run dev -- config set syncId macbook-pro

常见使用场景

同步 Claude Code 配置

bun run dev -- sync --profile work

只预览变更，不真正上传

bun run dev -- push --dry-run

多设备使用不同 profile

bun run dev -- sync --profile personal
bun run dev -- sync --profile work

项目结构

src/
├── cli/          # CLI 路由与命令解析
├── config/       # 配置加载、schema 校验、变量插值
├── credentials/  # 凭证来源与解析
├── hooks/        # 生命周期钩子
├── output/       # 输出与进度展示
├── security/     # 敏感信息扫描与脱敏
├── sync/         # File / Git / Link 三种同步模式
├── utils/        # 通用工具与错误模型
├── webdav/       # WebDAV 客户端与锁管理
├── index.ts      # CLI 入口
└── types.ts      # 核心类型定义

test/
├── cli.test.ts
├── config-*.test.ts
├── credentials*.test.ts
├── security.test.ts
├── sync*.test.ts
├── webdav*.test.ts
└── docs-ci.test.ts

开发

常用命令

bun run typecheck
bun run lint
bun run lint:fix
bun run format
bun run format:check
bun test
bun run test:coverage
bun run docs
bun run docs:check
bun run check

一次性完整检查

bun run check

该命令会依次执行：

TypeScript 类型检查
ESLint 检查
Prettier 格式检查
TypeDoc 文档校验
Bun test 测试

文档

生成 API 文档

bun run docs

校验文档生成是否正常

bun run docs:check

生成结果位于：

docs/

项目已包含 GitHub Pages 发布流程，可将 TypeDoc 输出直接发布为文档站点。

测试覆盖率

当前项目测试覆盖率目标为 90%+。

当前已记录覆盖率：

Functions: 98.26%
Lines: 93.35%

如需更新，请运行：

bun run test:coverage

当前状态

当前版本已经具备：

CLI 基础命令
配置 schema 与加载能力
WebDAV 客户端与锁机制
File / Git / Link 三种同步模式
安全扫描与日志脱敏
文档与测试基础设施

后续可以继续增强：

Windows 支持
更完整的 init 向导体验
更细粒度的冲突解决策略
更丰富的远程状态对比与预览输出

License

This project is licensed under the MIT License. See LICENSE for details.

Notes

This project was primarily created and iterated with AI-assisted development workflows.