Markdown Cloud Sync

一个支持同步Markdown文件到第三方OSS的VSCode插件，支持阿里云OSS、腾讯云COS和七牛云KODO。

🚀 功能特性

• 多云支持: 支持阿里云OSS、腾讯云COS、七牛云KODO
• 自动同步: 保存Markdown文件时自动上传到云存储
• 智能分类: 支持Front Matter、目录结构、自定义规则分类
• 可视化界面: 活动栏云存储视图，状态栏同步状态
• 搜索功能: 支持按文件名、路径、分类搜索云端文件
• 批量操作: 支持批量同步工作区文件
• 配置管理: 图形化配置界面，支持连接测试

📦 安装使用

1. 安装插件

# 从源码编译安装
git clone <repository-url>
cd markdown-cloud-sync
npm install
npm run compile

2. 配置云存储

方法1：配置向导（推荐）

1. 打开命令面板 (Ctrl+Shift+P)
2. 运行 "Markdown Cloud Sync: 配置云存储"
3. 按照向导完成配置，支持：
   • 智能提示和默认值
   • 输入验证
   • 配置完成后直接测试连接

方法2：快速导入

1. 复制配置示例（见 config-examples.md）
2. 修改为你的实际配置
3. 运行 "Markdown Cloud Sync: 从剪贴板导入配置"

方法3：查看和管理配置

• 查看配置: "Markdown Cloud Sync: 查看当前配置"
• 导出配置: "Markdown Cloud Sync: 导出配置到剪贴板"
• 测试连接: "Markdown Cloud Sync: 测试连接"

3. 开始使用

• 自动同步: 编辑并保存Markdown文件即可自动同步
• 手动同步: 右键点击文件选择"上传到云存储"
• 查看云端文件: 点击活动栏云存储图标
• 搜索文件: 在云存储视图中点击🔍按钮或按Ctrl+F搜索
• 下载文件: 点击云端文件自动下载到 .vsossdocs 目录
• 打开下载文件夹: 点击📁按钮快速打开下载目录
• 配置管理: 在云存储视图中点击"⚙️ 云存储配置"快速管理配置

⚙️ 配置说明

云存储配置

在VSCode设置中配置以下参数：

分类策略

• frontmatter: 从Markdown文件的Front Matter中读取分类
• directory: 根据文件所在目录确定分类
• custom: 使用自定义规则确定分类

📝 使用示例

Front Matter分类

---
category: 技术
title: 我的技术文档
---

# 技术文档内容

目录结构分类

docs/
├── 技术/
│   └── api.md
├── 学习/
│   └── notes.md
└── 工作/
    └── tasks.md

🛠️ 开发指南

项目结构

src/
├── extension.ts          # 插件入口文件
├── types.ts             # TypeScript类型定义
├── Configuration.ts     # 配置管理
├── OSSClient.ts         # 云存储客户端封装
├── CategoryManager.ts   # 分类管理
├── SyncManager.ts       # 同步管理
└── CloudFileProvider.ts # 云文件树视图提供者

开发环境设置

# 安装依赖
npm install

# 编译代码
npm run compile

# 监听模式
npm run watch

# 运行测试
npm test

调试插件

1. 按 F5 启动调试
2. 在新窗口中测试插件功能
3. 查看输出面板的日志信息

🔧 高级功能

批量同步

运行命令 "Markdown Cloud Sync: 同步工作区" 可以批量同步所有Markdown文件。

分类管理

• 导出分类索引: 备份分类配置
• 导入分类索引: 恢复分类配置
• 自定义分类规则: 根据文件名或内容关键词分类

云存储文件管理

• 查看云端文件列表
• 搜索云端文件（按文件名、路径、分类）
• 下载云端文件到专门的 .vsossdocs 目录
• 删除云端文件
• 按分类浏览文件
• 快速打开下载文件夹

下载功能说明

• 下载目录: 所有下载的文件保存在工作区根目录的 .vsossdocs 文件夹中
• 目录结构: 保持云端文件的目录结构，避免文件冲突
• 自动创建: 下载时自动创建必要的子目录
• 版本控制: .vsossdocs 目录已添加到 .gitignore，不会被提交到版本控制
• 快速访问: 通过视图标题栏的📁按钮快速打开下载文件夹

🐛 故障排除

常见问题

连接失败

• 检查Access Key和Secret是否正确
• 确认存储桶权限设置
• 验证网络连接

上传失败

• 检查存储桶是否存在
• 确认文件权限
• 查看详细错误日志

分类不生效

• 检查分类策略配置
• 确认Front Matter格式正确
• 验证目录结构

腾讯云COS配置问题

• 确保Bucket名称格式为 bucket-appid（包含完整的AppID）
• 检查SecretId和SecretKey是否正确
• 确认存储桶权限设置

日志查看

运行 "Markdown Cloud Sync: 显示日志" 命令查看详细日志信息。

📄 许可证

MIT License

🎯 插件核心设计思路

🎯 插件核心设计思路

这个插件的核心目标是让用户在VSCode内就能便捷地管理Markdown文档，并安全地同步到云端。其核心工作流程可以概括为：

flowchart TD
    A[用户操作MD文件] --> B[插件监听文件变动]
    B --> C[读取OSS配置]
    C --> D[调用对应云存储API]
    D --> E{同步是否成功?}
    E -- 是 --> F[更新本地分类索引]
    E -- 否 --> G[提示用户错误]
    F --> H[云端存储与分类一致]

🔧 插件详细功能规划

在核心流程的基础上，以下是插件需要实现的具体功能模块：

1. 云存储配置管理

• 多云支持：支持主流的对象存储服务，如阿里云OSS、腾讯云COS（CloudBase Toolkit底层支持）和七牛云KODO等。
• 统一配置界面：在VSCode设置中提供图形化配置，主要参数包括：
  • accessKeyId 和 accessKeySecret
  • 存储桶名称 (bucket)
  • 接入端点 (endpoint)
  • 存储根目录 (rootPath)
• 配置验证：提供“验证连接”按钮，测试配置是否正确。

2. 文档分类体系

• 分类规则：支持用户按项目、标签或自定义目录对文档进行分类。
• 分类标识：可通过以下方式实现：
  • Front Matter：在Markdown文件头部添加category字段。
  • 目录映射：将本地特定目录映射为云端分类。
• 分类索引：插件维护一个本地的categories.json索引文件，记录文件与分类的对应关系，并同步至云端。

3. 文件同步机制

• 自动同步：利用VSCode API监听文件onDidSave事件，保存时自动上传。
• 手动同步：在资源管理器右键菜单中添加“上传到云存储”和“从云存储下载”命令。
• 冲突处理：基于文件最后修改时间解决编辑冲突，必要时提示用户。

4. 用户界面与交互

• 活动栏视图：在VSCode活动栏添加云朵图标，展示云存储状态、文件树和分类。
• 状态栏提示：在状态栏显示同步状态（如“同步完成”或“同步失败”）。
• 通知与日志：通过VSCode的通知机制提示操作结果，并输出详细的日志到“输出”面板。

💡 技术实现关键点

1. 插件工程化

• 使用yo code脚手架工具初始化项目。
• 使用vsce工具进行插件打包和发布。

2. 核心代码模块

• 扩展入口 (extension.ts)：负责注册命令、视图提供者和事件监听。
• 云存储客户端 (OSSClient.ts)：封装不同云服务的SDK，提供统一的上传、下载、列出文件接口。
• 配置管理器 (Configuration.ts)：使用VSCode的workspace.getConfiguration读取和管理配置。
• 分类管理器 (CategoryManager.ts)：处理分类逻辑和索引维护。
• 树视图提供者 (CloudFileProvider.ts)：实现vscode.TreeDataProvider，在侧边栏显示云端文件。

3. 代码示例概览

以下是一些关键代码结构的示意：

A. 插件激活与配置读取

// 扩展激活函数
export function activate(context: vscode.ExtensionContext) {
    // 读取配置
    const config = vscode.workspace.getConfiguration('markdownCloudSync');
    const ossConfig = {
        accessKeyId: config.get('accessKeyId'),
        accessKeySecret: config.get('accessKeySecret'),
        bucket: config.get('bucket'),
        endpoint: config.get('endpoint'),
        rootPath: config.get('rootPath')
    };
    
    // 初始化云存储客户端
    const ossClient = new OSSClient(ossConfig);
    
    // 注册命令，例如同步当前文件
    const syncCommand = vscode.commands.registerCommand('markdownCloudSync.syncCurrentFile', async (fileUri) => {
        // 同步逻辑
    });
    context.subscriptions.push(syncCommand);
}

B. 云存储客户端封装 (以阿里云OSS为例)

import OSS from 'ali-oss';

export class OSSClient {
    private client: OSS;
    
    constructor(config: any) {
        this.client = new OSS({
            region: config.region,
            accessKeyId: config.accessKeyId,
            accessKeySecret: config.accessKeySecret,
            bucket: config.bucket
        });
    }
    
    async uploadFile(localPath: string, cloudPath: string): Promise<void> {
        try {
            await this.client.put(cloudPath, localPath);
        } catch (error) {
            vscode.window.showErrorMessage(`上传失败: ${error.message}`);
        }
    }
    
    // 其他方法：downloadFile, listFiles, deleteFile 等
}

C. 文件保存自动同步

// 监听文档保存事件
vscode.workspace.onDidSaveTextDocument((document) => {
    // 判断是否为markdown文件
    if (document.languageId === 'markdown' && document.uri.scheme === 'file') {
        // 获取该文件的分类
        const category = getFileCategory(document.uri);
        // 执行上传
        vscode.commands.executeCommand('markdownCloudSync.uploadFile', document.uri, category);
    }
});

🚀 进阶功能建议

当基础功能实现后，可以考虑以下进阶功能提升用户体验：

• 增量同步：只同步文件修改的部分，提升大文件同步效率。
• 多目录绑定：允许将本地多个不同目录绑定到同一个云存储的不同分类下。
• 操作回滚：提供简单的版本管理，允许用户撤销上一次的同步操作。
• 模板生成：结合分类，提供不同的Markdown文档模板。

希望这个详细的设计方案能帮助你更好地规划这个VSCode插件。如果你对某个具体功能点的实现细节有进一步疑问，我很乐意继续为你解答。