Tool Sync

工具同步

ToolSync是每个开发工具的本地附加资产（extensions, mcp, skills）扫描， 使工具之间的配置相似 独立同步程序是。

从传统的“以工具内部插件为中心”模式转换为“以外部编排器为中心”模式。

核心结构

• 独立CLI/守护程序： toolsync-cli
• 独立GUI： toolsync-cli gui （本地Web UI）
• 按工具扫描主页： extensions, mcp, skills, toolsync-meta.json
• 保存同步根状态：

- snapshots/ - registry.json - plans/ - logs/ - reports/ - backups/

同步目标

• 扩展列表和资产
• MCP元数据和文件夹资产
• Skills元数据和文件夹资产
• Theme元数据（editorTheme, terminalTheme)
• 允许的环境变量键（allowEnvKeys)

不集中存储/复制秘密值原文。

安装

1）基于存储库运行

npm install
npm run compile
node ./out/toolsync-cli.js init

2）全局运行（可选）

npm install -g .
toolsync-cli init

基本命令

toolsync-cli init
toolsync-cli snapshot
toolsync-cli plan
toolsync-cli apply [toolId]
toolsync-cli sync
toolsync-cli daemon
toolsync-cli daemon --plan-only
toolsync-cli gui
toolsync-cli status
toolsync-cli report
toolsync-cli rollback

通用选项：

--sync-root=
   # 기본값: ~/ToolSync

GUI选项：

toolsync-cli gui --host=127.0.0.1 --port=17321 --no-open

GUI提供的功能：

1. 选择正在使用的软件（复选框）
2. 按工具布线
3. Root/Extensions/MCP/Skills路径导航/选择（文件夹选择支持MacOS主对话框）
4. 选择同步范围（Extensions/MCP/Skills/Themes/Env）
5. 同步范围预设按钮（MCP만, 전체, 테마만)
6. 保存设置并立即运行同步

自动循环

daemon重复以下循环：

1. 检测工具文件夹更改（marker）
2. 收集snapshot
3. 创建registry/plan
4. 必要时应用
5. 记录日志/报告

默认生命周期： loopIntervalSec=30

配置文件

初始化时 /config.json将创建。

示例：

{
  "tools": [
    {
      "id": "vscode",
      "root": "~/.vscode",
      "extensionsDir": "extensions",
      "mcpDir": "mcp",
      "skillsDir": "skills",
      "metadataFile": "toolsync-meta.json"
    },
    {
      "id": "cursor",
      "root": "~/.cursor",
      "extensionsDir": "extensions",
      "mcpDir": "mcp",
      "skillsDir": "skills",
      "metadataFile": "toolsync-meta.json"
    }
  ],
  "allowEnvKeys": ["LANG", "LC_ALL", "TERM", "TZ"],
  "syncScope": {
    "extensions": true,
    "mcp": true,
    "skills": true,
    "themes": true,
    "env": true
  },
  "loopIntervalSec": 30,
  "applyRetryCount": 1,
  "applyRetryDelaySec": 3,
  "logMaxSizeKb": 512,
  "logKeepArchives": 5,
  "reportTailLines": 100
}

工具元数据文件

每个工具根的 toolsync-meta.json是基于文件夹的难以同步项目的元数据存储库。

示例：

{
  "extensions": ["publisher.sample-ext"],
  "mcp": ["local-stdio-server"],
  "skills": ["qa-check"],
  "editorTheme": "One Dark Pro",
  "terminalTheme": "Solarized Dark",
  "env": {
    "LANG": "en_US.UTF-8"
  }
}

故障响应

• 应用前自动备份： /backups/
• 重试失败： applyRetryCount, applyRetryDelaySec
• 回滚： toolsync-cli rollback
• 诊断报告： toolsync-cli report

生产交付项

/
  config.json
  state.json
  snapshots/
  registry.json
  plans/
  logs/
    runtime.log
    errors.ndjson
    archive/
  reports/
  backups/

现有VS Code Extension

现有的基于扩展的工作流（src/extension.ts）用于兼容目的。 新的操作标准是独立的CLI/守护程序。

构建/打包

• 编译： npm run compile
• VSIX打包（传统）： npm run package
• CLI快速运行：

- npm run cli:init - npm run cli:sync - npm run cli:daemon - npm run cli:gui