DearTs Framework 开发技能

概述

DearTs 是一个基于 SDL3 + ImGui 的现代 C++20 应用程序框架，参考 ImHex 设计理念，提供完整的模块化架构。

核心特性：

• C++20 (Concepts, Ranges, std::format)
• SDL3 + ImGui 2.13.3 (Docking, Multi-viewport)
• 类型安全事件总线 (EventBus)
• Result<T, E> 错误处理
• Content Registry (ImHex 风格命令/工具/设置系统)
• 多视图停靠窗口系统
• 插件架构 (API 版本检查，动态加载)
• 异步日志 (liblogger)
• 任务管理器 (TaskManager)
• 配置管理 (ConfigManager)

快速开始

1. 项目结构

DearTs/
├── core/              # 核心系统
│   ├── app/           # 应用生命周期
│   ├── events/        # 事件总线
│   ├── ui/            # ImGui 集成、视图
│   ├── content/       # Content Registry
│   ├── tasks/         # 任务管理
│   ├── plugin/        # 插件系统
│   └── config/        # 配置管理
├── plugins/           # 插件实现
│   └── builtin/       # 内置插件
└── main/gui/          # 入口

2. 创建应用

#include "core/app/application.h"

class MyApp : public DearTs::Core::Application {
    bool on_initialize() override {
        LOG_INFO("Application starting");
        return true;
    }

    void on_render() override {
        ImGui::Begin("Hello");
        ImGui::Text("Hello DearTs!");
        ImGui::End();
    }
};

int main() {
    MyApp app;
    return app.run();
}

3. 创建插件

#include "core/plugin/plugin.h"

class MyPlugin : public IPlugin {
public:
    PluginInfo get_info() const override {
        return PluginInfo{
            .name = "MyPlugin",
            .author = "You",
            .description = "My plugin",
            .version = "1.0.0",
            .api_version = "1.0.0"
        };
    }

    Result<void, std::string> on_load() override {
        // 注册命令、视图
        ContentRegistry::Commands::register_handler(
            "my.action", "My Action", []() { /* ... */ }
        );
        ContentRegistry::Views::add<MyView>();
        return Result::ok();
    }
};

// 注册插件
PluginManager::instance().add_builtin(
    std::make_unique<MyPlugin>()
);

4. 核心系统快速示例

事件系统:

// 订阅
EventBus::Token token = EventBus::instance().subscribe<Event>(
    [](const Event& e) { /* handle */ }
);

// 发布
EventBus::instance().publish(Event{ ... });
// Token RAII 自动取消订阅

配置管理:

ConfigScope cfg("app.window");
cfg.set("width", 1280);
int width = cfg.get_or<int>("width", 1280);

// 加载/保存 JSON
ConfigManager::instance().load_from_file("config.json");
ConfigManager::instance().save_to_file("config.json");

任务管理:

auto task = TaskManager::instance().launch(
    "Loading File",
    [](const auto& cancel) {
        for (int i = 0; i < 100 && !cancel; i++) {
            // do work
        }
    }
);

日志:

LOG_INFO("Loading: {}", filename);
LOG_ERROR("Failed: {}", error);

核心系统架构

1. 应用生命周期

UNINITIALIZED → INITIALIZING → RUNNING ←→ PAUSED
                            ↓         ↓
                         STOPPING ←──┘
                            ↓
                        STOPPED

2. 插件生命周期

未加载 (Unloaded)
    ↓ add_builtin() / load_from_file()
已加载 (Loaded)
    ↓ enable()
已启用 (Enabled)
    ↓ disable()
已加载 (Loaded)
    ↓ unload()
未加载 (Unloaded)

3. 数据流

用户操作
    ↓
ContentRegistry::Commands::invoke()
    ↓
EventBus::publish(Event)
    ↓
插件事件处理器
    ↓
UI 更新 / 后台任务

构建和运行

构建

# Configure
cmake -B build -DCMAKE_BUILD_TYPE=Release

# Build
cmake --build build --config Release

# Run
./build/bin/DearTsApp.exe

依赖

• CMake 3.20+
• C++20 编译器 (MSVC 2022 / GCC 11+ / Clang 13+)
• SDL3
• ImGui 2.13.3+
• nlohmann/json
• fmtlib

参考文档

📘 核心 API 手册（优先阅读）

文档	说明	用途
config_manager_api.md	ConfigManager 完全手册	配置管理、层级键、JSON 持久化
logger_api.md	Logger 完全手册	日志记录、文件输出、级别控制
task_manager_api.md	TaskManager 完全手册	异步任务、进度跟踪、任务取消
plugin_system_api.md	Plugin System 完全手册	插件开发、生命周期、API 集成

📕 其他参考文档

核心系统:

• result_type.md - Result<T, E> 类型详解
• event_system.md - EventBus 事件系统
• content_registry.md - Content Registry 详解
• ui_system.md - UI 系统（视图、停靠窗口）

应用层:

• application_api.md - Application 类 API
• task_system.md - 任务系统详解
• plugin_system.md - 插件系统详解

集成指南:

• sdl3_init.md - SDL3 初始化指南
• imgui_integration.md - ImGui 集成指南
• cmake_config.md - CMake 配置详解
• logging_guide.md - 日志系统使用指南

📙 示例和模板

插件示例:

• plugins/builtin/

  - 内置插件完整实现

• plugins/builtin/include/views/

  - 视图示例

代码模板:

• assets/app_template.cpp

  - 应用程序模板

• assets/view_template.cpp

  - 视图模板

• assets/plugin_template.cpp

  - 插件模板

• assets/cmake_template.txt

  - CMake 模板

渲染示例:

• examples/SDL3_ImGui_Hybrid_Rendering.md

  - SDL3 + ImGui 混合渲染

• examples/interactive_sdl_render.md

  - 交互式 SDL 渲染

常见任务快速索引

任务	查阅文档
创建插件	plugin_system_api.md
管理配置	config_manager_api.md
异步任务	task_manager_api.md
添加日志	logger_api.md
事件系统	event_system.md
注册命令	content_registry.md
创建视图	ui_system.md
错误处理	result_type.md
CMake 配置	cmake_config.md

开发最佳实践

✅ DO

1. 使用 Result<T, E> 处理错误

   Result<Data, std::string> load() {
       if (error) return Result::err("Failed");
       return Result::ok(data);
   }
   

2. 使用 RAII 管理资源

   • EventBus::Token (自动取消订阅)
   • ConfigScope (自动前缀)
   • 智能指针

3. 查看 API 文档而非源码

   • 4 个核心 API 手册在

     references/

   • 每个手册都有完整示例

4. 使用 Content Registry

   ContentRegistry::Commands::register_handler("id", "Name", callback);
   ContentRegistry::Views::add<MyView>();
   

❌ DON'T

1. 不要用异常做控制流 - 使用 Result<T, E>
2. 不要忘记 API 版本 - 插件必须匹配
3. 不要使用全局状态 - 存储在插件成员或 ConfigManager
4. 不要手动管理资源 - 让 RAII 处理

技能使用场景

此技能在以下场景自动激活：

• 创建基于 SDL3 + ImGui 的 C++ 应用
• 实现类型安全的事件系统
• 开发插件系统
• 创建多视图停靠窗口
• 使用 Result 类型错误处理
• 使用 ConfigManager 管理配置
• 使用 TaskManager 执行异步任务
• 使用 Logger 记录日志
• 开发 UI 插件（视图、命令、工具）
• 查看 DearTs API 文档

项目资源

文档

• 项目文档:

  docs/

• 插件快速开始:

  plugins/QUICKSTART.md

• 插件用户指南:

  docs/plugin_system_guide.md

架构图

• 14 个高分辨率架构图:

  docs/diagrams/

• 包括：生命周期、类关系、事件流程、渲染管线等

外部链接

• SDL3 文档: https://wiki.libsdl.org/SDL3/
• ImGui GitHub: https://github.com/ocornut/imgui
• ImHex GitHub: https://github.com/WerWolv/ImHex
• CMake 文档: https://cmake.org/documentation/
• C++ 参考: https://en.cppreference.com/w/cpp

---

技能版本: 3.0.0 最后更新: 2025-12-30 框架版本: DearTs Framework 1.0.0