AIR Assets / Smart Assets Sync

基于 symlink + cache Git 仓库的 AI 资产同步扩展。

TL;DR

你想了解什么	先看哪里
当前代码入口	`src/extension.ts`
核心调度	`src/services/SyncCoordinator.ts`
文档现状	`docs/README.md`
新同步架构需求与实施计划	`docs/new-sync-architecture.md` / `docs/superpowers/plans/2026-04-30-new-sync-architecture.md`
AI 路由地图	`AGENTS.md`

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

当前代码事实

扩展显示名是 AIR Assets，仓库文档常用名是 Smart Assets Sync。
默认 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. 安装

打开工作区
打开左侧 AIR Assets 面板
先在 配置映射 视图完成 remoteUrl、projectType 和映射配置
执行 smartAssets.install，或在 配置映射 视图执行 installAll
扩展会检查 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。

待归档（一键 AI 归档）

待归档 视图与 资产列表 / 差异文件 / 配置映射 平级，列出缓存 Git 仓库 openspec/changes/（缓存侧 openspec/{projectType}/changes/）下当前用户已提交的 change 目录，排除 openspec/changes/archive/；以「change 目录 → 子目录 → 文件」树形展示，视图顶层显示当前用户名（git config user.name）。

归档一个 change

在 change 目录节点上右键：

菜单	行为
📦 一键 AI 归档	把渲染后的提示词发送到 Copilot Chat（Agent 模式）执行，由 Chat 当前选中的模型完成归档（模型在 Chat 的模型选择器里切换，含 BYOK）
📋 一键复制归档提示词	只把渲染结果写进剪贴板，不依赖 Copilot —— 订阅不可用或想用别的 AI 时走这条
复制目录名 / 相对路径 / 绝对路径、在文件管理器中显示	常规取路径操作

默认模板：

请帮忙使用 openspec-archive-change 技能，归档 {relativePath}

占位符 {dirName}（change 目录名）与 {relativePath}（相对工作区根的路径）在每次触发时实时替换，改模板见 smartAssets.pendingArchive.copyTemplate。

说明：

「一键 AI 归档」只对 change 目录节点出现，且要求「标准 VS Code + 已安装 Copilot 扩展」
归档动作依赖 openspec-archive-change 技能，而技能只在 Chat 面板里可用，所以这个入口会打开 Chat 并直接发送提示词。Copilot 订阅过期或配额耗尽时，失败原因会直接显示在对话里，而不是静默失败
当前 IDE 没有 Chat 能力时（部分 VS Code fork），插件会降级为把提示词复制到剪贴板并提示
安装 / 刷新 / 提交 / 迁移后，「待归档」列表会自动刷新；也可用视图标题栏的刷新按钮

ITCM 集成（工单信息 + 附件下载）

取代原先的 get-itcm-info skill。整条链路不依赖 LLM，也不依赖任何外部 agent。

入口：`ITCM 信息` 视图（位于「待归档」上方）

操作	说明
获取 ITCM 信息…	输入纯数字 `instanceId` → 取票面信息 → 拉附件清单 → 有附件才下载（无附件直接停在信息态；`autoDownload` 关掉则只列清单）
下载附件	对当前工单重跑下载，或先问工单号
打开下载目录	在系统文件管理器中定位 `{工作区}/openspec/docs/ITCM_documents/{instanceId}`
复制工单信息	一键复制完整工单信息 + 附件相对路径（如果有），按钮在「获取 ITCM 信息」旁边
刷新信息视图	重置为初始态（清空当前工单信息），不是重新获取

视图里每个附件节点会显示大小 / 失败原因；已成功落盘的附件可直接点开。

两条链路（端点不同，必须分别配置）

用途	端点	配置项
取票面信息（`instance_info`）	MCP：`{serverUrl}`（JSON-RPC，先 `initialize` → `tools/list` → `tools/call`）	`smartAssets.itcm.serverUrl`
取附件清单 + 下载	REST：`{apiBaseUrl}` + `getFileinfo` / `getFileStream`	`smartAssets.itcm.apiBaseUrl`

两个端点不能互相推导（一个是 /vivid/mcp/itcm-server，一个是 /vivid/api/mcp/），所以必须分别填写。每次拉附件清单时，日志会记录实际使用的 REST 基础地址，配错时一眼可见。

工具名与参数名都不硬编码：先 tools/list 拿 inputSchema，再从中挑工具、推导参数名（必要时用 smartAssets.itcm.infoToolName 指定）。服务端改名后插件不用重新发包。

信息展示模板（字段变化不用发包）

smartAssets.itcm.infoTemplate 是一个字符串模板，占位符写服务端 instance_info 的字段名：

标题：{Title}
描述：{Description}
UAT 日期：{UATDate}

每行渲染成一个树节点；找不到的字段会原样保留 {OldField}，一眼就能看出模板该更新了。

模板没覆盖到的字段不会丢：它们被收进一个可折叠的「其它字段（N）」分组（键：值，含嵌套对象的 JSON），展开就能看到全貌。不想看这个分组时把 smartAssets.itcm.showAllFields 关掉。

附件落盘

固定 openspec/docs/ITCM_documents/{instanceId} —— 不提供配置项，避免改到同步面（copyMappings 的目标目录）里被覆盖，也避免每个人的位置不一致。

工单没有附件时不会创建目录、不会发下载请求（空目录会让「下载过没有」无从判断）
文件名清洗（去掉路径分隔符与非法字符，杜绝路径穿越）
可选的下载域名白名单（allowedDownloadHosts）
单文件 200MB / 单次 200 个上限
逐文件容错：单个失败不中断，结束后汇总提示

令牌与 MCP

access/refresh token 存 SecretStorage（OS 凭据库），元数据存 globalState；令牌不会落到任何明文文件
后台定时保活：按 smartAssets.itcm.tokenKeepAliveIntervalSeconds（默认 60 秒）巡检，令牌进入提前刷新窗口就静默换一次。用户点按钮时拿到的是现成令牌，不用等刷新；两次真正发起的刷新之间有 3 分钟冷却，避免把 Keycloak 打成定时器
smartAssets.itcm.registerMcpServer 默认关闭：插件自己已经能取信息 + 下附件，注册 MCP 只是给「在聊天里让 AI 调 ITCM 工具」留的口子。需要时打开即可，与令牌保活无关

配置项

配置项	默认值	说明
`smartAssets.remoteUrl`	`""`	远程 Git 仓库地址
`smartAssets.branch`	`main`	远程分支
`smartAssets.releaseNoteBranch`	`release-note-meta`	启动期 release note 检查优先使用的轻量分支；失败时回退到 `smartAssets.branch`
`smartAssets.workspaceRoot`	`""`	多根工作区时可显式指定根目录
`smartAssets.projectType`	`""`	项目类型；用于 `{projectType}` 模板、skills 业务目录选择，以及 GitHub Agents 的 `View` / `Mobility` / `Workflow` 远端目录选择
`smartAssets.mappings`	`{}`	symlink 映射：远程路径 -> 工作区本地路径
`smartAssets.rulesIdeMapping`	`{}`	IDE -> rules 文件路径；共享 rules 模板正文支持 `{ide}` / `{skillsPath}` 占位符
`smartAssets.copyMappings`	`{}`	远程路径 -> 本地 copy 目标；内置 GitHub Agents 默认会按 `projectType` 从 `UniSync/agents/View`、`UniSync/agents/Mobility` 或 `UniSync/agents/Workflow` 复制到 `.github/agents`
`smartAssets.cacheDir`	系统默认缓存目录	自定义 cache 路径
`smartAssets.defaultIgnorePatterns`	内置默认列表	写入 `.git/info/exclude` 的默认模式
`smartAssets.skillsSync.autoSync`	`true`	激活时每会话自动执行一次分发维护；实际执行前仍会经过工作区启用状态与目标存在性判断
`smartAssets.skillsSync.mappings`	内置 IDE 映射	IDE -> skills 目录
`smartAssets.statusPollingInterval`	`60`	轮询更新徽章的间隔（秒）
`smartAssets.pendingArchive.copyTemplate`	`请帮忙使用 openspec-archive-change 技能，归档 {relativePath}`	「待归档」视图的归档提示词模板，`{dirName}` / `{relativePath}` 实时替换；「一键 AI 归档」与「一键复制归档提示词」共用
`smartAssets.itcm.keycloakBaseUrl`	`https://keycloak.com`	Keycloak 基础地址（据此派生 `/auth` 与 `/token`）
`smartAssets.itcm.clientId`	`user-service`	Keycloak public client（PKCE，无 client_secret）
`smartAssets.itcm.serverUrl`	`https://domain.com/vivid/mcp/itcm-server`	ITCM 的 MCP 端点（取工单信息用）
`smartAssets.itcm.apiBaseUrl`	`https://domain.com/vivid/api/mcp/`	ITCM 的 REST 基础地址（附件清单与下载用），与 MCP 端点不是同一路径
`smartAssets.itcm.infoTemplate`	内置 8 行模板	工单信息展示模板，占位符 `{字段名}`；字段变化改这里即可
`smartAssets.itcm.infoToolName`	`""`	显式指定取信息的 MCP 工具名；留空则自动挑选
`smartAssets.itcm.showAllFields`	`true`	是否在信息行下方加一个可折叠的「其它字段（N）」分组，展示模板未覆盖的字段
`smartAssets.itcm.allowedDownloadHosts`	`[]`	附件下载域名白名单；留空表示不限制
`smartAssets.itcm.autoDownload`	`true`	获取信息后是否自动下载全部附件
`smartAssets.itcm.registerMcpServer`	`false`	是否把 ITCM 注册为 VS Code 的 MCP 服务器供其它 agent 调用
`smartAssets.itcm.tokenKeepAliveIntervalSeconds`	`60`	令牌后台保活巡检间隔（秒），最小 15
`smartAssets.itcm.allowInsecureTls`	`true`	是否跳过 TLS 证书校验（内网自签证书场景）

当前命令面

以 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
smartAssets.pendingArchive.archiveWithCopilot / copyFromTemplate / refresh（视图右键入口，命令面板中隐藏）
smartAssets.itcm.signIn / signOut / refreshToken / showStatus
smartAssets.itcm.fetchInfo / downloadAttachments / openDownloadDir / refreshInfoView
smartAssets.itcm.openFile / copyInfo

说明：

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

AIR Assets

AIR