ShareX Feature Specifications

上传器插件系统规范

架构概述

多实例提供程序目录：

• 将 IUploaderPlugin 重命名为 IUploaderProvider，并支持多个类别
• 将提供程序（类型）与实例（已配置的条目）分离
• ProviderCatalog：用于注册提供程序类型的静态目录
• InstanceManager：用于管理实例生命周期、持久化和默认选择的单例
• 模型：支持 JSON 序列化的 UploaderInstance、InstanceConfiguration
• UI：ProviderCatalogViewModel、CategoryViewModel、UploaderInstanceViewModel
• 完整的 CRUD 操作：从目录添加、复制、重命名、移除、设为默认
• 跨类别支持：同一提供程序（例如 S3）可用于图像、文本和文件

提供程序参考：

• ImgurProvider：支持图像和文本类别
• AmazonS3Provider：支持图像、文本和文件类别

持久化：%AppData%/XerahS/uploader-instances.json

动态插件系统

架构：

• 纯动态加载：宿主应用中没有编译时插件引用。
• 隔离：每个插件使用一个 PluginLoadContext（AssemblyLoadContext）。
• 共享依赖项：从宿主上下文共享框架程序集（Avalonia、Newtonsoft.Json）。
• 静态生命周期：静态 PluginLoader 可防止上下文被过早垃圾回收。
• 动态 UI：插件通过 IUploaderProvider.GetConfigView 提供配置视图。

组件：

• PluginDiscovery：扫描 Plugins/ 文件夹中的 plugin.json 清单。
• PluginLoader：加载程序集并实例化提供程序。
• ProviderCatalog：用于注册内置和动态提供程序的中央目录。

插件示例：

• ShareX.Imgur.Plugin：支持 OAuth2 的图像上传。
• ShareX.AmazonS3.Plugin：上传到 S3 存储桶（图像/文本/文件）。

文件类型路由（计划中）

目标：

• 根据文件扩展名进行确定性路由
• 防止冲突（同一类别中不得有重叠的文件类型）
• 将“所有文件类型”设为互斥选项
• UI 显示可用和被阻止的文件类型

数据模型新增内容：

• FileTypeScope 类（AllFileTypes 标志 + FileExtensions 列表）
• UploaderInstance.FileTypeRouting 属性
• IUploaderProvider.GetSupportedFileTypes() 方法

路由逻辑：

1. Exact extension match (e.g., .png → Imgur)
2. "All File Types" fallback
3. No match → error/notification

UI 功能：

• 带冲突检测的文件类型选择器
• 对已分配类型显示禁用的复选框
• 工具提示显示阻止某类型的实例
• 实时验证

实施阶段：

1. 扩展数据模型
2. 路由引擎 + 验证
3. 提供程序元数据
4. UI（文件类型选择器、冲突警告）
5. 集成上传工作流

全自动化工作流（路径 B——计划中）

目标：实现端到端自动化，达到与 ShareX 功能对等

所需组件：

1. 任务系统（约 600 LOC）

   • WorkflowTask.cs——带生命周期管理的异步自动化引擎
   • TaskInfo.cs——任务元数据和状态
   • TaskManager.cs——带并发控制的队列编排
   • TaskStatus.cs——状态枚举和作业类型

2. 工作流配置（约 200 LOC）

   • AfterCaptureTasks 标志：AddImageEffects、AnnotateImage、SaveImageToFile、UploadImageToHost 等
   • AfterUploadTasks 标志：CopyURLToClipboard、OpenURL、ShortenURL、ShowQRCode、ShowNotification
   • UploadInfoParser——基于模板的剪贴板格式（%url%、%filename%、%time% 等）

3. 上传集成（约 150 LOC）

   • UploadResult 模型，包含 URL/ThumbnailURL/DeletionURL/ShortenedURL
   • 用于错误处理的 UploaderErrorManager
   • 进度跟踪事件
   • 带备用上传器的重试逻辑

4. 上传后自动化（约 100 LOC）

   • URL 缩短集成
   • 使用自定义格式复制到剪贴板
   • 打开浏览器
   • 生成 QR 码
   • 通知系统

5. UI 集成（约 150 LOC）

   • 上传期间显示进度指示器
   • Toast 通知
   • 上传历史面板
   • 任务列表视图

实现阶段：

1. 核心任务系统（WorkflowTask、TaskManager）
2. 上传工作流集成
3. 上传后自动化（剪贴板、通知）
4. 热键 → 全自动化接线
5. 进度 UI 和历史记录

总工作量：约 1,200 LOC，8-12 小时

阻碍因素：

• 注释编辑器会阻塞操作（模态）。需要为“快速捕获+上传”和“编辑器模式”分别设置独立的工作流路径
• 全程需要采用 async/await 模式（ShareX 使用线程）
• 上传提供程序需要 UploadAsync 方法签名

已交付路径 A（最小实现）：

• 基本的 WorkflowTask 结构
• 上传提供程序接线
• 上传后简单地将“复制 URL”操作写入剪贴板
• 热键 → 捕获 → 上传 → URL 工作流

路径 B 新增内容：

• 带并发限制的完整任务队列
• 完善的 AfterCapture/AfterUpload 流水线
• 带百分比/速度/预计剩余时间的进度跟踪
• 支持自定义格式的通知系统
• 带备用上传器的上传重试逻辑
• 持久化任务历史记录
• 用于任务监控和管理的 UI

注释子系统规范

阶段 1：核心注释模型（已完成）

项目： XerahS.Annotations 创建的文件： 10 个文件（约 800 LOC）

已实现的注释类型：

• EditorTool 枚举：Select、Rectangle、Ellipse、Arrow、Line、Text、Number、Spotlight、Crop、Pen
• Annotation 抽象基类，支持渲染、命中测试和边界计算
• 具体类型：RectangleAnnotation、EllipseAnnotation、LineAnnotation、ArrowAnnotation、TextAnnotation、NumberAnnotation（自动递增）、SpotlightAnnotation（聚焦效果）、CropAnnotation（带调整大小手柄）

技术特性：

• Avalonia DrawingContext 渲染
• 可配置的命中测试（基于容差）
• 支持颜色/描边宽度
• 用于图层排序的 Z-index
• 手动距离计算（兼容 Avalonia API）
• 使用 FormattedText 渲染文本，并支持粗体/斜体

阶段 2：画布控件和完整功能集

为 XerahS 实现注释子系统，使用 Avalonia 和 Skia 替换 WinForms 和 System.Drawing。必须支持 ShapeType 枚举中列出的所有功能。

设计核心抽象

• 在 XerahS 中定义 BaseShape，包含位置、大小、颜色、边框粗细和命中测试等属性。
• 为所有 ShapeType 值创建对应的 Avalonia 实现（RegionRectangle、RegionEllipse、RegionFreehand、DrawingRectangle、DrawingEllipse、DrawingFreehand、DrawingFreehandArrow、DrawingLine、DrawingArrow、DrawingTextOutline、DrawingTextBackground、DrawingSpeechBalloon、DrawingStep、DrawingMagnify、DrawingImage、DrawingImageScreen、DrawingSticker、DrawingCursor、DrawingSmartEraser、EffectBlur、EffectPixelate、EffectHighlight、ToolSpotlight、ToolCrop、ToolCutOut）。每种实现都必须继承 BaseShape，并实现自定义渲染逻辑。
• 提供形状专属属性，例如箭头方向、模糊半径、像素大小和高亮颜色，并设置适当的默认值。

渲染和效果

• 使用 Avalonia 的 DrawingContext 和 Skia 替代 GDI+ 绘图。实现形状和文本的矢量绘制。对于效果（模糊、像素化、高亮），使用 Skia 图像滤镜或自定义像素着色器，仅在形状边界内应用效果。
• 实现聚光灯工具：将所选矩形以外的画布调暗，并可选择应用模糊或椭圆效果。
• 实现放大镜绘制：在圆形或矩形形状内，渲染底层位图的放大部分。

交互

• 创建 RegionCaptureView 控件，用于捕获鼠标和触摸事件、绘制用于调整大小或移动形状的控制柄，并支持多形状编辑。
• 实现键盘快捷键，以切换工具（例如箭头工具、文本工具、效果工具），并取消或确认操作。
• 提供形状工具栏（使用 XAML），用于选择绘图、效果和工具类型；包含用于更改颜色、粗细、字体和效果参数的控件。

形状管理

• 移植 ShapeManager，以管理形状集合、排序、选择和移除。提供撤销/重做功能，并支持复制/粘贴形状。
• 在 AnnotationOptions 对应项中保存用户偏好设置（颜色、大小、箭头方向、模糊半径、像素大小等），并在应用启动时加载，在应用退出时保存。

图像插入和贴纸支持

• 集成文件选择器，以便插入外部图像（DrawingImage 和 DrawingImageScreen）。
• 提供贴纸面板和光标印章支持；允许用户导入自定义贴纸。

智能橡皮擦

• 分析 SmartEraserDrawingShape，并实现基于蒙版的橡皮擦，以恢复擦除路径下方的原始截图像素。

裁剪和抠图工具

• 实现裁剪和抠图工具，以修改画布位图并相应调整现有形状。
• 确保支持非破坏性编辑，允许用户还原或调整裁剪边界。

区域捕获集成

• 使用 Avalonia 构建新的 RegionCaptureWindow，以替代 RegionCaptureForm。处理显示器选择、上次区域回显、屏幕取色器、标尺以及 RegionCaptureMode 和 RegionCaptureAction 中定义的其他捕获模式。
• 提供从捕获 → 标注 → 上传的无缝工作流，并集成现有任务运行器。

跨平台注意事项

• 避免引用 System.Drawing 或 WinForms；绘图仅使用 Avalonia 和 Skia。
• 通过 AGENTS.md 中定义的核心平台层，使用平台抽象服务（例如剪贴板、文件对话框）。
• 确保 Windows、macOS 和 Linux 上的行为一致；对于无法支持的操作系统专属功能，实现存根或回退方案。

测试

• 为每种形状和效果编写单元测试和 UI 测试，验证渲染、命中测试、配置持久化以及撤销/重做操作的行为。
• 提供手动测试脚本，以验证各受支持平台上的标注工作流。