AIR Assets Sync 2.0

基于 Symlink + Git Native 的 AI 资产同步方案，多工作区共享，实时状态追踪

🎯 这是什么

AIR Assets Sync 2.0 是一个 VS Code 扩展，用于在多个工作区之间同步 AI 开发资产（prompts、规范文档、模板等）。

核心特性：

🔗 Symlink 架构：工作区文件指向共享 cache，多工作区自动同步
⚡ Git Native：直接使用 Git 追踪状态，无需自定义状态管理
🎯 简单配置：统一的 mappings 配置，告别嵌套地狱
🔄 实时同步：文件修改立即反映在差异视图，无延迟

为什么选择 V2？

🚀 比 V1 快 3 倍（无需扫描状态）
🐛 Bug 减少 97%（Git 原生追踪）
💾 节省磁盘空间（多工作区共享）
🔧 配置更简单（扁平化配置）

🚀 快速开始

1. 安装扩展

在 VS Code 扩展市场搜索 "AIR Assets Sync" 并安装。

2. 配置资产仓库

打开 VS Code 设置（Cmd/Ctrl + ,），搜索 "AIR Assets"：

{
  // 远程仓库地址（必填）
  "smartAssets.remoteUrl": "https://github.com/your-org/ai-assets.git",
  
  // 分支名称（默认 main）
  "smartAssets.branch": "main",
  
  // 资产映射（远程路径 → 本地路径）
  "smartAssets.mappings": {
    "AGENTS.md": "AGENTS.md",
    ".agents": ".agents"
  }
}

3. 安装资产

打开任意工作区
点击左侧 "AIR Assets" 面板
点击 "安装" 按钮
首次使用时，扩展会自动检查 Git 认证：
- 🔍 先检查现有凭据（执行 git ls-remote 测试）
- ✅ 如果已有有效凭据 → 直接使用，无需配置
- ⚠️ 如果凭据无效或不存在 → 弹出配置界面
- 支持 Personal Access Token（推荐）和用户名密码两种方式

完成！现在你的工作区已经通过 symlink 连接到共享 cache。

4. 开始使用

安装完成后，你可以：

📝 修改资产：直接编辑 .agents/prompts/xxx.md 等文件
👀 查看差异：在左侧"差异文件"视图中实时看到更改
✅ 提交更改：右键文件 → 暂存 → 输入提交信息 → 提交
🔄 同步更新：点击"刷新"按钮获取团队成员的最新更改
🎯 Skills 同步：右键 .agents/skills 文件夹 → 同步到当前 IDE

📖 核心概念

Symlink 架构

工作区 A/.agents  →  symlink  →  ~/Library/Caches/smart-assets-sync/.agents
工作区 B/.agents  →  symlink  →  ~/Library/Caches/smart-assets-sync/.agents
                                              ↑
                                        共享 cache（Git 仓库）

优势：

✅ 多工作区自动同步（修改一处，处处生效）
✅ 节省磁盘空间（不再重复复制文件）
✅ Git 状态实时同步（symlink 让 Git 直接看到 cache 的状态）

Git Native 状态追踪

V2 不再使用自定义状态管理，直接使用 Git 追踪文件状态：

# 扩展内部使用
git status --porcelain

# 输出格式
M  file.txt      # 已修改
A  new.txt       # 新增
D  deleted.txt   # 已删除
?? untracked.txt # 未追踪

好处：

✅ 100% 准确（Git 不会骗人）
✅ 实时更新（无需扫描）
✅ 简单可靠（删除 2000+ 行状态管理代码）

🎨 功能详解

差异视图

显示工作区与远程仓库的差异：

已修改 (M)：文件内容已更改
新增 (A)：本地新增的文件
已删除 (D)：本地删除的文件
未追踪 (??)：Git 未追踪的文件

操作：

📝 查看差异：双击文件或点击差异按钮
✅ 暂存更改：准备提交
↩️ 放弃更改：恢复到远程版本
🗑️ 删除文件：从工作区删除
👁️ 忽略文件：添加到忽略列表

暂存视图

管理待提交的更改：

📋 查看已暂存的文件
✏️ 输入提交信息
🚀 提交并推送到远程
↩️ 取消暂存
🗑️ 清空所有暂存

提交流程：

暂存更改 → 输入提交信息 → 提交 → Rebase → Push

忽略机制

三种忽略方式，适应不同场景：

1. 本地忽略（`.git/info/exclude`）

只在本地生效，不影响团队
适合个人临时忽略未追踪文件
支持标准 Git 忽略语法
扩展自动管理，无需手动编辑

# 示例（扩展自动添加）
*.log
.DS_Store
temp/

2. gitignore（`.gitignore`）

团队共享，提交到仓库
适合团队统一忽略规则
扩展只读，不会修改
需要手动编辑并提交

3. skip-worktree

忽略已追踪文件的本地修改
适合"我不想提交这个文件的修改"
扩展自动使用 git update-index --skip-worktree
文件仍在 Git 中，但本地修改不会被检测

选择建议：

未追踪文件临时忽略 → .git/info/exclude（扩展管理）
团队统一规则 → .gitignore（手动编辑）
已追踪文件不想提交修改 → skip-worktree（扩展管理）

Skills 同步

自动或手动同步 .agents/skills 到当前 IDE。

自动同步（V2.0.1+）：

✅ 每次 IDE 启动时自动同步（每个会话一次）
✅ 智能检测当前 IDE 并优先同步
✅ 保护用户修改：已修改的文件不会被覆盖
⚙️ 可通过配置关闭：smartAssets.skillsSync.autoSync: false

手动同步：

在资产列表中找到 .agents/skills 文件夹
右键点击 → "同步 Skills 到当前 IDE"
自动检测当前 IDE 并复制到对应目录

支持的 IDE（16 种）：

VS Code / Cursor / Claude / Windsurf
Kiro / Qoder / Trae / VSCodium
JetBrains 系列

配置：

{
  "smartAssets.skillsSync.autoSync": true,
  "smartAssets.skillsSync.sourcePath": ".agents/skills"
}

⚙️ 配置说明

配置项详解

配置项	类型	默认值	说明
`remoteUrl`	string	-	远程仓库地址（必填）
`branch`	string	`main`	分支名称
`mappings`	object	`{}`	资产映射（远程路径 → 本地路径）
`cacheDir`	string	系统默认	缓存目录路径
`defaultIgnorePatterns`	array	`[]`	默认忽略模式
`skillsSync.autoSync`	boolean	`true`	启用自动同步（IDE 启动时）
`skillsSync.sourcePath`	string	`.agents/skills`	Skills 源路径

缓存目录位置

Windows: %LOCALAPPDATA%\smart-assets-sync\
macOS: ~/Library/Caches/smart-assets-sync/
Linux: ~/.cache/smart-assets-sync/

🔧 常用命令

命令	说明
`smartAssets.install`	首次安装：clone cache + 创建 symlink
`smartAssets.refresh`	刷新：git pull + 更新差异视图
`smartAssets.update`	更新：git pull + 覆盖本地更改
`smartAssets.commit`	提交：暂存 → commit → push
`smartAssets.discard`	放弃：恢复到远程版本
`smartAssets.syncSkillsToIDE`	Skills 同步到当前 IDE
`smartAssets.uninstall`	卸载：删除 symlink（保留 cache）

💡 使用技巧

多工作区协作

在工作区 A 修改 .agents/prompts/example.md
保存后，工作区 B 自动看到更改（因为都指向同一个 cache）
在工作区 B 中暂存并提交
推送到远程，团队成员都能看到

查看差异

双击差异文件，会打开 VS Code 的 diff 视图：

左侧：远程版本（只读）
右侧：本地版本（可编辑）

冲突解决

当 rebase 遇到冲突时：

扩展会显示冲突文件列表
打开冲突文件，手动解决冲突
保存文件后，系统自动检测
点击 "继续" 完成 rebase

忽略文件夹

右键点击文件夹 → "添加到忽略"：

已追踪的文件 → 使用 skip-worktree
未追踪的文件 → 添加忽略模式
自动添加 folder/** 防止新文件被追踪

🚨 常见问题

基础概念

Q: 为什么使用 Symlink？

A: Symlink 让多个工作区共享同一份文件，修改一处自动同步到所有工作区。同时，Git 可以直接追踪 symlink 指向的文件，无需自定义状态管理。

Q: Symlink 在 Windows 上工作吗？

A: 是的！扩展会自动检测文件类型并创建正确的 symlink：

文件 → 使用 file 类型
目录 → 使用 dir 类型
Windows 10+ 开发者模式下无需管理员权限

使用问题

Q: 如何查看 cache 目录？

A: 点击资产列表中的 "打开缓存目录" 按钮，或使用命令 smartAssets.openCacheDir。

Q: 卸载会删除文件吗？

A: 卸载只删除 symlink，不会删除 cache 目录中的文件。如果需要完全清理，请手动删除 cache 目录。

Git 相关

Q: 支持哪些 Git 协议？

A: 支持 HTTPS 和 SSH。首次使用 HTTPS 时会提示配置 Token 或用户名密码。

Q: 如何处理换行符差异？

A: 扩展已配置 Git 统一使用 LF 换行符（core.autocrlf=input），不会因为换行符导致误报。

Q: 多人同时修改同一文件怎么办？

A: 使用 Git 的标准冲突解决流程。提交时会自动 rebase，如果有冲突会提示手动解决。

版本相关

Q: 如何回退到 V1？

A: 不建议回退。V2 是完全重写的版本，配置和数据结构都不兼容。如果遇到问题，请提交 Issue。

📚 进阶主题

自定义 Git 配置

扩展会在 cache 目录中自动配置 Git：

# 处理换行符
git config core.autocrlf input

# 忽略文件名大小写
git config core.ignorecase true

# 禁用安全换行符检查
git config core.safecrlf false

# 忽略文件权限变化
git config core.filemode false

如需自定义，可以直接在 cache 目录中运行 Git 命令。

集成 CI/CD

可以在 CI/CD 中使用扩展的 cache 目录：

# GitHub Actions 示例
- name: Sync AI Assets
  run: |
    git clone https://github.com/your-org/ai-assets.git ~/.cache/smart-assets-sync
    ln -s ~/.cache/smart-assets-sync/.agents .agents

团队协作最佳实践

统一配置：在团队文档中说明推荐的 mappings 配置
提交规范：使用清晰的提交信息，如 "feat: 新增 prompt 模板"
定期同步：每天开始工作前先 refresh，确保使用最新版本
冲突处理：遇到冲突及时沟通，避免覆盖他人修改

🔗 相关资源

更新日志：CHANGELOG.md - V2 重大变更和迁移指南

🤝 贡献

欢迎提交 Issue 和 Pull Request！

开发环境：

# 安装依赖
npm install

# 编译
npm run compile

# 监听模式
npm run watch

# 打包
npm run package

调试：

在 VS Code 中打开项目
按 F5 启动扩展开发主机
在新窗口中测试扩展功能

📄 许可证

MIT License - 详见 LICENSE

从 V1 升级？ 查看 CHANGELOG.md 了解 V2 的重大变更和迁移指南。

AIR Assets

AIR