OQPush – OpenQuant 策略推送插件

OQPush 是一个 VS Code 扩展，用于连接本地 OpenQuant 策略项目和 OpenQuant 管理后端。它提供安全的文件加密/解密、推送/拉取操作以及无缝的工作区集成。

功能特性

• 推送策略 – 加密并推送本地策略文件到 OpenQuant 后端
• 拉取策略 – 从 OpenQuant 后端拉取并解密策略文件
• 单文件推送/拉取 – 右键单个文件进行快速推送或拉取
• 增量上传 – 智能检测文件变更，仅上传修改的文件（基于 mtime + size）
• 文件删除检测 – 自动检测本地删除的文件并同步到后端
• 文件加密 – 对所有推送文件自动进行 AES 加密
• 保存时自动推送 – 保存文件时自动推送策略（可配置延迟）
• 侧边栏操作区 – Push / Pull 按钮与配置项一目了然
• .openquantignore 支持 – 自定义忽略模式（类似 .gitignore）
• 智能文件扫描 – 使用默认忽略模式智能过滤文件
• OpenToken 认证 – 基于 Token 的安全认证（无需 secret-id/secret-key）
• 状态栏集成 – 实时显示上传/下载进度和状态
• 密钥管理 – 使用 VS Code 密钥存储 API 安全存储/删除密码
• 详细日志 – 可配置日志级别用于调试和监控

快速开始

1. 配置 OpenToken

打开命令面板 (Ctrl+Shift+P / Cmd+Shift+P) 并运行：

OQPush: Configure OpenToken

输入您的 OpenQuant OpenToken（格式：OpenQuant@{salt}/{random}）。

2. （可选）保存密码

避免每次都输入策略密码，运行：

OQPush: Configure Password

3. 配置文件模式（可选）

默认情况下，OQPush 使用智能忽略模式（.git、node_modules 等）。在工作区根目录创建 .openquantignore 文件来自定义模式（类似 .gitignore）。

其他行为如保存时自动推送可通过 VS Code 设置配置——参见下方的扩展设置。

4. 推送或拉取

推送策略 (Ctrl+Alt+U)：

• 智能检测文件变更（增量上传）
• 自动检测已删除文件并同步
• 使用策略密码加密
• 推送到 OpenQuant 后端

拉取策略 (Ctrl+Alt+D)：

• 从 OpenQuant 后端拉取
• 使用策略密码解密
• 覆盖本地文件（需确认）

侧边栏按钮：

• 侧边栏顶部的 Push / Pull 按钮快速执行推送或拉取

单文件推送/拉取（右键菜单）：

• 右键文件 → 推送文件/拉取文件
• 右键空白处 → 拉取所有文件

扩展设置

OQPush 贡献以下设置（在 VS Code 设置中的 OQPush 下可见）：

命令

系统要求

• VS Code 1.106.0 或更高版本
• 有效的 OpenQuant OpenToken
• 策略密码（用于加密/解密）

技术细节

.openquantignore 文件

.openquantignore 文件类似 .gitignore —— 将其放置在工作区根目录以定义自定义忽略模式：

• 以 # 开头的行是注释
• 空行将被忽略
• 支持通配符模式（*、**、?）
• 目录模式以 / 结尾

默认忽略模式

启用 useDefaultIgnore 时，以下内容将自动被排除：

• 版本控制：.git/、.gitignore、.gitattributes
• 依赖目录：node_modules/、bower_components/、vendor/
• 编辑器配置：.vscode/、.idea/、*.swp、.DS_Store
• Python：__pycache__/、*.py[cod]、venv/、.venv/
• 构建输出：dist/、build/、out/、target/
• 日志和临时：*.log、logs/、*.tmp、temp/、tmp/
• 环境配置：.env、.env.local、.env.*.local

保存时自动推送

启用后，OQPush 会在文件保存后自动推送策略：

• 遵循 .openquantignore 模式
• 通过 pushDelay 防抖（默认 2000ms）避免频繁推送
• 仅对工作区根目录内的文件触发

认证流程

1. OpenToken 包含用于密码加密的 salt
2. Password + salt → encrypted_word
3. encrypted_word + OpenToken → API 认证
4. 文件内容在上传前使用 AES 加密

增量上传与文件删除检测

OQPush 支持智能增量上传，优化推送性能：

• 文件变更检测：基于文件的 mtime（修改时间）和 size（文件大小）双重判断
• 增量上传：仅上传发生变更的文件，跳过未修改的文件
• 删除检测：对比本地文件与上一次推送状态，自动检测已删除的文件
• 状态持久化：使用 VSCode workspaceState 存储文件状态快照（基于工作区路径的 MD5 hash）
• 首次推送提示：首次推送时会提示用户确认

工作流程：

1. 扫描工作区文件，收集当前文件状态
2. 与历史状态对比，识别变更和删除
3. 先调用删除 API 同步已删除的文件
4. 再上传发生变更的文件

侧边栏视图

OQPush 提供侧边栏视图，方便快速操作：

• Push / Pull 按钮：一键执行推送或拉取
• 配置项平铺：Open Token、加密密码、自动推送、推送延迟
• 切换自动推送：一键开启/关闭保存时自动推送
• 设置推送延迟：通过 QuickPick 选择预设延迟时间（0ms/1s/2s/3s/5s/10s）
• 配置来源识别：显示配置作用域（工作区文件夹/工作区/全局）
• 智能配置更新：优先更新工作区配置，支持跨工作区独立设置

错误处理

OQPush 为常见问题提供详细的错误消息，支持多种服务端错误响应格式：

服务端错误格式支持：

• 新格式：{ code, message, data } - 优先使用服务端返回的 message 字段
• FastAPI 格式：{ detail: "error message" } 或 { detail: { error_code, message } }
• 其他通用格式：{ error, message }

常见错误提示：

• 缺失或无效的 OpenToken
• 策略不存在（strategy not found）
• 网络连接问题
• API 速率限制（支持 Retry-After）
• 客户端和 Web 端密码不匹配

发布说明

0.0.4

• 增强 API 错误处理，支持服务端新格式 { code, message, data }
• 优化配置管理，移除冗余代码和重复默认值
• 改进错误消息提示，直接显示服务端返回的错误信息

0.0.3

• 添加侧边栏图标
• 优化 API 基础 URL 配置

0.0.2

• 新增单文件推送/拉取功能（右键菜单）
• 新增增量上传功能（仅上传变更文件）
• 新增文件删除检测（自动同步已删除文件）
• 新增侧边栏控制面板（快速切换自动推送、设置延迟）
• 优化推送流程，提升性能
• 新增文件状态持久化（支持多工作区）

0.0.1

• 初始发布，包含推送/拉取策略功能
• 基于 OpenToken 的认证
• 文件加密/解密支持
• 状态栏集成
• 安全的密码存储