mcpField
S
ShareX Architecture and Porting

ShareX Architecture and Porting

github.com/sharex开发34258 次安装今天更新
代码仓库

关于 ShareX Architecture and Porting

这份开发技能文档说明 XerahS 的架构与移植规则，包括平台抽象边界和 Avalonia 解决方案结构，供移植 ShareX 后端代码的贡献者参考。

主要功能

  1. 01平台抽象要求
  2. 02移植 ShareX 代码的规则
  3. 03建议的 Avalonia 项目结构
  4. 04历史版本对照指南

适用场景

  1. 01将原生代码与共享逻辑分离
  2. 02在 UI 开发前规划后端模块
  3. 03将实现与指定提交进行比较

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/sharex/xerahs --skill sharex-architecture-and-porting

安装后在 Claude Code 中输入/sharex-architecture-and-porting确认已加载。

详细介绍

平台抽象和原生代码规则

所有特定于平台的功能都必须通过平台抽象接口隔离。

XerahS.Platform.* 项目之外的代码不得引用：

  • NativeMethods
  • NativeConstants、NativeEnums、NativeStructs
  • Win32 P/Invoke
  • System.Windows.Forms
  • Windows 专用句柄或消息

禁止在 Common、Core、Uploaders、Media 或其他后端项目中直接调用 Windows API。

必需的架构

在 XerahS.Platform.Abstractions 中定义平台中立的接口。

在 XerahS.Platform.Windows 中实现 Windows 功能。

为未来的平台创建存根实现：

  • XerahS.Platform.Linux
  • XerahS.Platform.MacOS
仅限 Windows 的功能

如果某项功能仅适用于 Windows：

  • 仍必须通过抽象接口定义。
  • Windows 提供具体实现。
  • 其他平台提供存根实现，且应：
    • 抛出 PlatformNotSupportedException，或
    • 记录警告后安全地不执行任何操作。

UI 和工作流必须检测功能是否可用，并停用或隐藏不受支持的功能。

迁移现有 ShareX 代码的规则

只有完全不包含以下引用的文件，才可以直接迁移：

  • NativeMethods 或相关原生辅助代码
  • WinForms 类型
  • Windows 专用互操作

如果文件混合了逻辑和原生调用：

  • 将纯逻辑提取到 Common 或 Core。
  • 将原生代码移至 XerahS.Platform.Windows。
  • 将调用点替换为接口调用。

原生方法名称和签名应保持为 Windows 专用内容，不得泄漏到共享层。

执行规则

迁移 ShareX.HelpersLib 时，引用以下内容的文件：

  • NativeMethods.cs
  • NativeMethods_Helpers.cs
  • NativeMessagingHost.cs
  • DWM、钩子、剪贴板或输入 API

必须视为平台代码，不得整体复制。

主要目标和迁移规则

  • 主要目标：先迁移 ShareX 后端，再设计 Avalonia UI，以此构建 XerahS。
  • 检查 C:\Users\liveu\source\repos\ShareX Team\ShareX，了解现有的非 UI 逻辑，并在拟定 Avalonia 解决方案和项目后，将其复制到此仓库中复用。
  • 不要复用 WinForms 或任何 WinForms UI 代码；只能复制非 UI 方法和数据模型。
  • 在明确开始 UI 设计阶段之前，优先迁移后端。

Avalonia 解决方案提案（基于 ShareX 分析）

  • 先从最简单的后端库开始，再逐步迁移到更复杂的模块。
  • 建议的结构：
    • XerahS.Common：共享辅助代码、序列化和实用工具。
    • XerahS.Core：任务设置、工作流和应用级服务。
    • XerahS.Uploaders：上传器、配置、OAuth 和 HTTP 辅助代码。
    • XerahS.History：历史记录模型和持久化。
    • XerahS.Indexer：文件索引和搜索。
    • XerahS.ImageEffects：滤镜／效果处理流水线。
    • XerahS.Media：编码、缩略图和 FFmpeg 集成。
    • XerahS.ScreenCapture：捕获引擎和平台抽象。
    • XerahS.Platform.*：特定于操作系统的实现（先支持 Windows，其他平台稍后支持）。
    • XerahS.App 和 XerahS.UI：Avalonia UI 和视图模型（待后端就绪后再处理）。

历史比较与一致性

当被要求确保与某个特定历史提交保持功能一致，或“使其与提交 X 完全相同”时：

  1. 不要反复调用 git：避免在会话期间反复查询 git 历史记录中的文件内容。
  2. 创建 ref 目录：创建一个临时文件夹（例如 src/XerahS/ref）。
  3. 下载参考文件：使用 git show <commit_hash>:<file_path> > src/XerahS/ref/<commit_short>_<filename>，核实相关文件在该提交中的状态。
  4. 在本地比较：对当前本地文件与下载的参考文件进行差异比较和分析。
  5. 清理：任务完成并核实后，删除 ref 目录，除非另有指示。

这样可以减少 git 命令开销，并为一致性检查提供稳定的参考点。

评论

支持 Markdown