快速参考
vsync 命令和常用模式的快速参考指南和速查表。
命令概览
| 命令 | 说明 | 常用选项 |
|---|---|---|
init | 初始化配置 | --user |
sync | 同步配置 | --dry-run, --prune, --user, -y |
plan | 预览同步计划 | --user |
status | 检查同步状态 | --user |
list | 列出配置 | skills, mcp, --user |
clean | 从目标移除 | --from-source, --user, -y |
import | 从项目导入 | --user |
常见工作流
首次设置
# Project 层级设置
vsync init
vsync sync
# User 层级设置
vsync init --user
vsync sync --user日常同步
# 1. 在源工具中编辑配置
vim ~/.claude/skills/my-skill/SKILL.md
# 2. 同步到目标
vsync sync同步前预览
# 检查将要更改什么
vsync plan
# 或使用 dry-run
vsync sync --dry-run
# 如果满意，应用
vsync sync清理旧配置
# 安全: 仅从目标移除
vsync clean skill/old-skill
# 严格镜像（删除额外项）
vsync sync --prune同步模式
Safe 模式（默认）
vsync sync- ✅ 创建新项
- ✅ 更新现有项
- ❌ 从不删除
Prune 模式
vsync sync --prune- ✅ 创建新项
- ✅ 更新现有项
- ⚠️ 删除源中不存在的项
配置层级
Project 层级
# 默认行为
vsync init # 创建 .vsync.json
vsync sync # 同步项目配置用于: 团队配置、项目特定集成
User 层级
# 添加 --user 标志
vsync init --user # 创建 ~/.vsync.json
vsync sync --user # 同步全局配置用于: 个人偏好、全局技能
命令示例
init
# 项目配置
vsync init
# 用户配置
vsync init --usersync
# Safe 同步
vsync sync
# Prune 模式
vsync sync --prune
# Dry run
vsync sync --dry-run
# 用户级
vsync sync --user
# 跳过确认
vsync sync -yplan
# 预览更改
vsync plan
# 用户级计划
vsync plan --userstatus
# 检查同步状态
vsync status
# 用户级状态
vsync status --userlist
# 列出所有
vsync list
# 列出 skills
vsync list skills
# 列出 MCP 服务器
vsync list mcp
# 用户级
vsync list --userclean
# 从目标移除单个项
vsync clean skill/old-skill
# 交互式选择
vsync clean
# 也从源删除（危险！）
vsync clean skill/old-skill --from-source
# 用户级
vsync clean --user
# 跳过确认
vsync clean skill/old-skill -yimport
# 从另一个项目导入
vsync import ../other-project
# 导入到用户级
vsync import ../other-project --user配置文件快速参考
.vsync.json
{
"version": "1.0.0",
"level": "project",
"source_tool": "claude-code",
"target_tools": ["cursor", "opencode", "codex"],
"sync_config": {
"skills": true,
"mcp": true
},
"use_symlinks_for_skills": false,
"language": "en"
}关键设置
| 设置 | 值 | 说明 |
|---|---|---|
source_tool | claude-code, cursor, opencode, codex | 您的配置源 |
target_tools | 工具数组 | 同步目标 |
sync_config.skills | true/false | 启用 Skills 同步 |
sync_config.mcp | true/false | 启用 MCP 同步 |
use_symlinks_for_skills | true/false | 使用符号链接 (v1.2+) |
language | en/zh | CLI 语言（仅用户级） |
工具特定格式
MCP 环境变量
| 工具 | 语法 | 示例 |
|---|---|---|
| Claude Code | ${VAR} | ${API_KEY} |
| Cursor | ${env:VAR} | ${env:API_KEY} |
| OpenCode | {env:VAR} | {env:API_KEY} |
| Codex | 无插值 | 直接值 |
配置文件位置
| 工具 | Project | User |
|---|---|---|
| Claude Code | .mcp.json | ~/.claude.json |
| Cursor | mcp.json | ~/.cursor/mcp.json |
| OpenCode | opencode.json(c) | ~/.opencode/opencode.json |
| Codex | config.toml | ~/.codex/config.toml |
常用模式
团队协作
# 1. 提交配置到 git
git add .vsync.json
git commit -m "feat: add vsync config"
# 2. 团队成员克隆并同步
git clone <repo>
cd <repo>
vsync syncCI/CD 集成
# GitHub Actions
- name: Sync configs
run: npx @nicepkg/vsync sync --yes迁移工作流
# 1. 从旧项目导入
vsync import ../old-project
# 2. 查看计划
vsync plan
# 3. 同步到目标
vsync sync退出代码
| 代码 | 含义 |
|---|---|
0 | 成功 |
1 | 发生错误 |
获取帮助
# 一般帮助
vsync --help
# 命令帮助
vsync sync --help
# 版本
vsync --version常见问题
权限被拒绝
# 检查目录权限
ls -la ~/.cursor/
# 在 Windows 上: 以管理员身份运行以使用符号链接找不到配置
# 解决方案: 先初始化
vsync init未检测到工具
# 解决方案: 创建工具目录
mkdir -p ~/.cursor
vsync init相关资源
Last updated on