Only Dev VSCode 插件

一个强大的 VSCode 插件，用于在项目中创建和管理开发专用文件。通过创建 .only-dev 目录，您可以在开发时使用修改过的文件，而不会影响原始文件。

✨ 功能特性

核心功能

• ✅ 创建开发文件：在资源管理器中右键点击任何文件，快速创建对应的开发文件
• ✅ 自动添加到.gitignore：创建的.only-dev目录会自动添加到.gitignore
• ✅ 快速切换：在编辑器中快速切换原始文件和开发文件
• ✅ 文件对比：使用 VSCode 的 diff 视图对比原始文件和开发文件的差异
• ✅ 差异高亮：在编辑器中自动高亮显示与原始文件的差异行

文件管理

• 📁 文件列表视图：在侧边栏显示所有开发文件的树形视图，支持快速访问
• 🔍 搜索功能：快速搜索开发文件
• 📊 统计信息：在状态栏显示文件数量、大小、修改状态等统计信息
• 🗑️ 清理功能：自动清理未使用的开发文件（原始文件已删除）

批量操作

• 🔄 批量同步：批量同步开发文件到原始文件
• 🗑️ 清理孤立文件：自动检测并清理原始文件已删除的开发文件

同步策略

• 🔄 多种同步模式：支持手动、自动、询问三种同步策略
• 💾 自动备份：同步前自动备份原始文件，支持恢复
• ⚙️ 灵活配置：可配置同步时机和备份保留天数
• 👁️ 同步预览：同步前预览所有更改，支持逐行选择保留的内容
• 📈 差异统计：显示详细的差异统计信息（新增、删除、修改行数）

高级功能

• 📝 模板支持：创建开发文件时使用模板，支持变量替换
• 🔀 文件重命名/移动支持：原始文件重命名或移动时自动更新开发文件路径
• 🔗 Git 集成：检查 Git 状态，提交前提醒检查开发文件
• 💾 配置导出/导入：导出和导入开发文件配置，方便项目迁移
• 📜 文件历史：记录所有同步操作历史，支持查看、回滚和对比历史版本
• 🔔 文件变更通知：原始文件更新时自动通知，支持查看差异和合并选项

用户体验

• ⌨️ 快捷键支持：常用操作都有快捷键
• 📋 命令面板：所有功能都可通过命令面板访问
• 🎯 上下文菜单：在资源管理器和文件树中添加了右键菜单
• 📊 状态栏增强：显示统计信息和模式状态

🚀 快速开始

创建开发文件

方法一：右键菜单

1. 在资源管理器中右键点击文件
2. 选择"Only Dev: 创建开发文件"
3. 插件会自动在.only-dev目录下创建对应的文件并打开

方法二：命令面板

1. 按 Cmd+Shift+P (Mac) 或 Ctrl+Shift+P (Windows/Linux)
2. 输入 "Only Dev: 创建开发文件"
3. 选择要创建的文件

方法三：快捷键

• 在编辑器中按 Cmd+Shift+N (Mac) 或 Ctrl+Shift+N (Windows/Linux)

切换文件

方法一：编辑器标题栏

• 点击编辑器标题栏的切换按钮

方法二：快捷键

• 按 Cmd+Shift+D (Mac) 或 Ctrl+Shift+D (Windows/Linux)

方法三：命令面板

• 运行 "Only Dev: 打开对应的开发文件"

对比文件

方法一：快捷键

• 按 Cmd+Shift+C (Mac) 或 Ctrl+Shift+C (Windows/Linux)

方法二：命令面板

• 运行 "Only Dev: 对比文件"

方法三：文件树

• 在文件树中右键点击文件，选择"对比文件"

查看开发文件列表

1. 在侧边栏找到 "Only Dev" 视图
2. 展开 "开发文件" 树
3. 可以看到所有开发文件及其状态：
   • 🟢 正常文件
   • 🟡 已修改（开发文件比原始文件新）
   • ⚠️ 孤立文件（原始文件已删除）

⌨️ 快捷键

快捷键	功能
Cmd+Shift+D (Mac) Ctrl+Shift+D (Win/Linux)	切换原始文件/开发文件
Cmd+Shift+C (Mac) Ctrl+Shift+C (Win/Linux)	对比文件
Cmd+Shift+N (Mac) Ctrl+Shift+N (Win/Linux)	创建开发文件

📋 命令列表

所有命令都可以通过命令面板 (Cmd+Shift+P / Ctrl+Shift+P) 访问：

文件操作

• Only Dev: 创建开发文件 - 为当前文件创建开发版本
• Only Dev: 打开对应的开发文件 - 在原始文件和开发文件之间切换
• Only Dev: 对比文件 - 使用 diff 视图对比文件

批量操作

• Only Dev: 批量同步到原始文件 - 批量同步开发文件

管理功能

• Only Dev: 清理孤立文件 - 清理原始文件已删除的开发文件
• Only Dev: 搜索开发文件 - 搜索开发文件
• Only Dev: 显示统计信息 - 显示开发文件统计信息
• Only Dev: 显示差异统计 - 显示当前文件的详细差异统计
• Only Dev: 同步预览 - 同步前预览所有更改并选择要同步的内容
• Only Dev: 查看文件历史 - 查看文件的同步历史记录

配置功能

• Only Dev: 导出配置 - 导出开发文件配置
• Only Dev: 导入配置 - 导入开发文件配置
• Only Dev: 切换开发模式 - 启用/禁用开发模式
• Only Dev: 检查Git状态 - 检查 Git 状态并提醒

⚙️ 配置选项

在 VSCode 设置中可以配置以下选项：

基本设置

• onlyDev.enabled (boolean, 默认: true) - 是否启用 Only Dev 插件
• onlyDev.showNotifications (boolean, 默认: true) - 是否显示通知
• onlyDev.showStats (boolean, 默认: true) - 是否在状态栏显示统计信息

同步设置

• onlyDev.autoSync (boolean, 默认: false) - 是否自动同步开发文件到原始文件
• onlyDev.syncStrategy (string, 默认: "manual") - 同步策略：
  • "manual" - 手动同步（不自动同步）
  • "auto" - 自动同步（保存时自动同步）
  • "ask" - 询问同步（保存时询问是否同步）

备份设置

• onlyDev.enableBackup (boolean, 默认: true) - 同步前是否自动备份原始文件
• onlyDev.backupDaysToKeep (number, 默认: 7) - 备份文件保留天数

差异高亮

• onlyDev.highlightDiff (boolean, 默认: true) - 是否高亮显示与原始文件的差异

模板设置

• onlyDev.useTemplate (boolean, 默认: false) - 创建开发文件时是否使用模板

• onlyDev.templates (object, 默认: {}) - 文件模板配置

  模板配置示例：

  {
    "onlyDev.templates": {
      "default": "${originalContent}\n\n// 开发版本 - ${date}",
      "*.ts": "// 开发版本: ${fileName}\n// 创建时间: ${datetime}\n\n${originalContent}",
      "custom": "// 自定义模板\n${originalContent}"
    }
  }
  

  支持的模板变量：

  • ${originalContent} - 原始文件内容
  • ${fileName} - 文件名
  • ${fileNameWithoutExt} - 不含扩展名的文件名
  • ${extension} - 文件扩展名
  • ${directory} - 文件目录
  • ${date} - 当前日期
  • ${time} - 当前时间
  • ${datetime} - 当前日期时间
  • ${timestamp} - ISO 时间戳
  • ${year}, ${month}, ${day} - 年月日

同步预览设置

• onlyDev.useSyncPreview (boolean, 默认: false) - 同步前是否显示预览界面

文件变更通知

• onlyDev.notifyOnOriginalChange (boolean, 默认: true) - 原始文件更新时是否通知

历史记录设置

• onlyDev.historyDaysToKeep (number, 默认: 30) - 历史记录保留天数

其他设置

• onlyDev.confirmDelete (boolean, 默认: true) - 删除文件前是否确认
• onlyDev.autoRename (boolean, 默认: true) - 原始文件重命名时是否自动更新开发文件路径
• onlyDev.promptBeforeCommit (boolean, 默认: true) - Git 提交前是否提醒检查开发文件

📁 文件树视图

在侧边栏的 "Only Dev" 视图中，您可以：

• 查看所有开发文件：以树形结构显示所有开发文件
• 查看文件状态：
  • 正常文件：原始文件存在且未修改
  • 已修改：开发文件比原始文件新
  • 孤立文件：原始文件已删除
• 快速操作：右键点击文件可以：
  • 打开文件
  • 对比文件
  • 同步到原始文件（仅已修改文件）
  • 查看历史记录
• 批量操作：选择多个文件进行批量操作

🔄 同步策略说明

Manual（手动）

• 不会自动同步
• 需要手动运行同步命令
• 适合需要完全控制同步时机的场景

Auto（自动）

• 保存开发文件时自动同步到原始文件
• 同步前会自动创建备份（如果启用了备份）
• 适合频繁同步的场景

Ask（询问）

• 保存开发文件时会询问是否同步
• 结合 autoSync 配置使用
• 适合需要确认的场景

💾 备份功能

当启用备份功能时，每次同步前都会自动备份原始文件：

• 备份文件保存在 .only-dev-backups 目录
• 备份文件名包含时间戳
• 可以配置备份保留天数
• 定期自动清理旧备份

👁️ 同步预览功能

同步预览功能允许您在同步前查看所有更改，并逐行选择要保留的内容：

使用同步预览

1. 启用预览模式：在设置中启用 onlyDev.useSyncPreview
2. 触发预览：
   • 从文件树中右键点击已修改文件，选择"同步到原始文件"
   • 或运行命令 "Only Dev: 同步预览"
3. 选择更改：
   • 在预览界面中，您可以看到原始文件、开发文件和合并结果
   • 对于每一行更改，可以选择：
     • ◀ 接受原始版本
     • ⬌ 接受两者（修改行会保留两行）
     • ▶ 接受开发版本
4. 批量操作：
   • 点击"全部接受原始"或"全部接受开发"快速选择所有更改
5. 执行同步：点击"同步更改"按钮完成同步

预览界面说明

预览界面分为四列：

• 原始文件：显示原始文件内容
• 合并结果：显示根据您的选择生成的最终结果
• 操作按钮：每行更改都有选择按钮
• 开发文件：显示开发文件内容

📜 文件历史功能

文件历史功能记录所有同步操作，支持查看、回滚和对比历史版本：

查看历史记录

1. 从命令面板：运行 "Only Dev: 查看文件历史"
2. 从文件树：右键点击文件，选择"查看历史"
3. 选择历史记录：从列表中选择要查看的记录

历史记录操作

对于每条历史记录，您可以：

• 查看：打开历史版本文件（如果有备份）
• 回滚：将文件恢复到该历史版本
• 对比：对比两个历史版本之间的差异

历史记录信息

每条历史记录包含：

• 操作时间
• 操作类型（同步、创建、删除、修改）
• 文件路径
• 差异统计信息（如果有）
• 备份文件路径（如果有）

📈 差异统计功能

差异统计功能提供详细的文件差异分析：

查看差异统计

1. 从命令面板：运行 "Only Dev: 显示差异统计"
2. 统计信息包括：
   • 新增行数
   • 删除行数
   • 修改行数
   • 总差异行数
   • 差异百分比

差异统计显示位置

• 在文件历史记录中显示
• 在同步预览界面显示
• 通过命令查看当前文件的详细统计

🔔 文件变更通知

当原始文件被更新时，插件会自动检测并通知您：

通知功能

1. 自动检测：插件会监听所有开发文件对应的原始文件
2. 差异分析：当原始文件更新时，自动计算与开发文件的差异
3. 通知选项：
   • 查看差异：打开 diff 视图对比文件
   • 合并更改：选择合并方式
     • 使用原始文件（覆盖开发文件）
     • 使用开发文件（覆盖原始文件）
     • 手动合并（打开 diff 视图）
   • 忽略：暂时忽略通知

配置通知

在设置中可以配置：

• onlyDev.notifyOnOriginalChange：是否启用文件变更通知

📝 模板使用

创建模板

在设置中配置模板：

{
  "onlyDev.templates": {
    "default": "${originalContent}\n\n// 开发版本",
    "*.js": "// 开发版本: ${fileName}\n${originalContent}",
    "*.ts": "// 开发版本\n// 创建时间: ${datetime}\n\n${originalContent}"
  }
}

使用模板

1. 启用 onlyDev.useTemplate
2. 创建开发文件时会自动应用模板
3. 模板会根据文件扩展名匹配，如果没有匹配则使用 default 模板

🔗 Git 集成

插件会检查 Git 状态：

• 在提交前提醒检查开发文件
• 显示未提交的文件列表
• 可以配置是否启用提醒

📊 统计信息

状态栏会显示：

• 总文件数
• 已修改文件数
• 孤立文件数
• 总文件大小

点击状态栏可以查看详细统计信息。

🛠️ 项目集成

构建脚本示例

在您的项目中，可以创建构建脚本来使用.only-dev文件：

package.json (Node.js 项目)

{
  "scripts": {
    "dev": "node scripts/dev-builder.js",
    "build": "node scripts/prod-builder.js"
  }
}

dev-builder.js 示例

const fs = require('fs');
const path = require('path');

function getFile(filePath) {
  const devPath = path.join('.only-dev', filePath);
  if (fs.existsSync(devPath)) {
    return devPath;
  }
  return filePath;
}

// 使用开发文件
const config = getFile('src/config.js');

📦 导出/导入配置

导出配置

1. 运行命令 "Only Dev: 导出配置"
2. 选择保存位置
3. 配置文件包含所有开发文件的路径和元数据

导入配置

1. 运行命令 "Only Dev: 导入配置"
2. 选择配置文件
3. 配置会被导入到当前项目

🐛 故障排除

文件树不显示

• 确保已打开工作区
• 检查是否有 .only-dev 目录
• 尝试刷新文件树（右键点击视图标题）

差异高亮不工作

• 检查 onlyDev.highlightDiff 设置
• 确保原始文件和开发文件都存在

同步不工作

• 检查同步策略设置
• 确保原始文件存在
• 检查文件权限

📄 许可证

MIT

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📝 更新日志

v1.0.0

• ✨ 初始版本
• ✅ 基础功能：创建、切换、同步开发文件
• ✅ 文件对比和差异高亮
• ✅ 文件树视图
• ✅ 批量操作
• ✅ 备份功能
• ✅ 模板支持
• ✅ Git 集成
• ✅ 配置导出/导入
• ✅ 同步预览功能
• ✅ 文件历史记录
• ✅ 差异统计功能
• ✅ 文件变更通知