AIR Assets / Smart Assets Sync

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

TL;DR

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

当前代码事实

• 扩展显示名是 AIR Assets，仓库文档常用名是 Smart Assets Sync。
• 当前版本是 2.10.3。
• 默认 cache 目录名是 smart-assets-sync。
• 状态来源是 git status --porcelain，由 GitStatusTracker 解析。
• 刷新流程是 git pull --rebase --autostash，并包含暂存恢复与 stash 冲突处理。
• 启动时会优先检查 release note；远端不可用时会回退到主同步分支或本地缓存。
• 激活期自动分发只会在工作区已显式启用后运行；copy / rules / skills 都会先检查对应激活目标是否已存在，再继续写入。
• 配置映射 视图是当前推荐的主配置入口，用来编辑 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.releaseNoteBranch": "release-note-meta",
  "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. 启动期 Release Note 提示

从 2.10.3 开始，插件新增了启动期 release note 提示能力。

• 当工作区已经显式启用 AIR Assets 后，插件激活时会检查远端最新 release note
• 默认优先读取轻量分支 smartAssets.releaseNoteBranch，默认值为 release-note-meta
• 如果该分支不存在、探测失败或读取超时，会自动回退到 smartAssets.branch 或本地缓存
• 当远端 release note 比本地缓存更新时，会弹出提示并展示最新内容，提醒你尽快更新资产

这个能力的目标是让用户在打开 IDE 时就能看到最新资产说明，同时尽量降低对主分支的读取成本。

6. 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