AIR Assets / Smart Assets Sync

基于 symlink + cache Git 仓库的 AI 资产同步扩展。当前代码版本为 2.10.1，以 src/ 和 package.json 为准。

TL;DR

一句话：扩展会把远程资产仓库 clone 到本地共享 cache，再把工作区里的映射路径创建为 symlink；所有状态、暂存、冲突都以 cache 仓库里的 Git 状态为准。

当前代码事实

• 扩展显示名是 AIR Assets，仓库文档常用名是 Smart Assets Sync。
• 当前版本是 2.10.1。
• 默认 cache 目录名是 smart-assets-sync。
• 状态来源是 git status --porcelain，由 GitStatusTracker 解析。
• 刷新流程是 git pull --rebase --autostash，并包含暂存恢复与 stash 冲突处理。
• Skills Sync、Rules Inject、Copy 分发都会在激活后每会话自动执行一次。
• 配置映射 视图是当前推荐的主配置入口，用来编辑 workspaceRoot、projectType 和 4 组映射，并承载迁移与一键安装入口。

核心架构

workspace path -> symlink -> local shared cache -> git repository

主要模块：

• src/extension.ts: 激活、命令注册、树视图、自动分发同步
• src/services/SyncCoordinator.ts: 所有同步操作的统一入口
• src/services/core/*: symlink、cache、git、status
• src/services/sync/*: install / refresh / update / commit / discard / skills sync
• src/services/ignore/*: .git/info/exclude 与 skip-worktree
• src/views/*: Asset / Diff / Staged / Conflict / Ignored 视图

快速开始

1. 配置

{
  "smartAssets.remoteUrl": "https://github.com/your-org/ai-assets.git",
  "smartAssets.branch": "main",
  "smartAssets.projectType": "VIEW",
  "smartAssets.mappings": {
    "openspec/{projectType}/changes": "openspec/changes",
    "openspec/{projectType}/specs": "openspec/specs",
    "openspec/{projectType}/config.yaml": "openspec/config.yaml"
  }
}

可选配置：

{
  "smartAssets.cacheDir": "",
  "smartAssets.workspaceRoot": "",
  "smartAssets.projectType": "VIEW",
  "smartAssets.rulesIdeMapping": {},
  "smartAssets.copyMappings": {},
  "smartAssets.skillsSync.autoSync": true
}

2. 配置映射视图

配置映射 视图集中管理以下内容：

• workspaceRoot
• projectType
• mappings
• skillsSync.mappings
• rulesIdeMapping
• copyMappings

视图内支持：

• 编辑配置项
• 新增 / 删除映射行
• 刷新项目类型列表
• 执行 一键安装全部同步
• 执行 迁移到新同步架构

说明：

• 首次进入项目时，即使 remoteUrl 或 projectType 尚未完成配置，扩展也会继续激活，方便直接进入该视图补配置
• 当 projectType 变更导致现有 symlink 目标可能失效时，视图会提示重新执行一键安装

3. 安装

1. 打开工作区
2. 打开左侧 AIR Assets 面板
3. 先在 配置映射 视图完成 remoteUrl、projectType 和映射配置
4. 执行 smartAssets.install，或在 配置映射 视图执行 installAll
5. 扩展会检查 Git 认证、初始化 cache、clone 仓库、再创建 symlink

安装前会统一执行两类检查：

• 配置是否完整
• cache 是否仍为旧目录结构

如果 cache 仍为旧结构，安装会被阻断，并提示先执行“迁移到新同步架构”。

4. 日常操作

• 修改资产文件：直接编辑工作区里的映射路径
• 查看差异：看 差异文件 视图
• 提交更改：先暂存，再执行 commitStagedChanges
• 同步远程：执行 refresh
• 编辑同步映射：打开 配置映射 视图
• 同步 Skills：执行 syncSkillsToIDE
• 一键安装全部同步：执行 installAll

5. Rules 模板占位符

共享 rules 模板正文现在支持官方占位符：

{ide}
{skillsPath}

例如：

python3 {skillsPath}/skill-tracker/scripts/log_skill.py code-review --meta source_ide={ide}

分发到不同 IDE 时会自动渲染为对应 IDE key 和 smartAssets.skillsSync.mappings 中配置的 skills 目录；若当前 IDE 没有配置 skills 映射，则 {skillsPath} 兜底为 .github/skills。

当 smartAssets.rulesIdeMapping 启用了 copilot 时，插件会自动把旧的 smartAssets.skillsSync.mappings.copilot 修正为 .github/skills。

配置项

当前命令面

以 package.json 和 src/extension.ts 为准，当前高频入口包括：

• smartAssets.install
• smartAssets.refresh
• smartAssets.update
• smartAssets.stageChanges
• smartAssets.unstageChanges
• smartAssets.commitStagedChanges
• smartAssets.discardChanges
• smartAssets.syncSkillsToIDE
• smartAssets.installAll
• smartAssets.migrateToNewArchitecture
• smartAssets.uninstall

说明：

• rebase 恢复相关的代码注册名是 smartAssets.continueRefresh / smartAssets.abortRefresh
• package.json 中仍保留 smartAssets.continue / smartAssets.abort 的贡献项
• 遇到这类不一致时，以代码实现为准

开发

npm run watch
npm run compile
npm run lint
npm run test:unit
npm run test:integration

文档说明

• AGENTS.md：AI 路由页
• docs/README.md：文档索引，标记哪些是当前可参考文档、哪些是历史遗留
• docs/new-sync-architecture.md：新同步架构需求收敛稿
• 仓库里仍保留不少 V1 / 迁移期文档；使用前请先核对代码

许可证

MIT License - 详见 LICENSE