# RegistrationTool 类技术文档

**包路径:** `com.axis.innovators.box.register.RegistrationTool`  
**主要功能:** 工具箱组件注册中心、功能分类管理器  
**作者:** tzdwindows 7

---

## 1. 概述

`RegistrationTool` 是 **Axis Innovators Box** 的功能调度核心。它负责管理主程序中所有的工具项（`ToolItem`）及其所属的分类（`ToolCategory`）。通过该类，开发者可以将各种功能模块（如调试工具、编程环境、AI 推理等）注册到主界面的工具栏中。

该类不仅内置了丰富的系统工具，还为外部插件提供了一套标准的扩展接口，支持基于命名空间的工具注册逻辑。

## 2. 核心职责

*   **功能分类管理:** 将相似功能的工具组织在 `ToolCategory` 下（如“调试工具”、“AI工具”）。
*   **工具项路由:** 定义点击工具图标后的具体行为（通过 `AbstractAction` 实现窗口弹出或逻辑执行）。
*   **插件扩展支持:** 提供 API 允许插件在加载时动态注入自定义工具。
*   **唯一性校验:** 确保每个注册项拥有唯一的 `UUID` 和注册名称（Registered Name），防止冲突。
*   **平台适配:** 在初始化时根据 `BuildInformation` 检查操作系统兼容性（主要针对 Windows）。

## 3. 内置工具分类

在 Windows 系统环境下，`RegistrationTool` 默认初始化以下分类及工具：

### 3.1 调试工具 (Debug Tools)
*   **Frida 注入工具:** 使用 Frida 框架对目标进程进行脚本注入。

### 3.2 编程工具 (Programming Tools)
*   **JarApi 查看器:** 反射查看 JAR 包内的方法定义及其注解。
*   **C 语言编辑器:** 智能化的 C 语言编译与编辑环境。
*   **多语言在线执行:** 支持多种编程语言的实时在线运行，具备无限循环检测机制。
*   **数据库管理:** 跨平台的数据库管理客户端。
*   **Linux 终端:** 启动一个真实的 Linux 终端模拟环境。
*   **MySQL 控制台:** 模拟 MySQL 命令行交互界面。

### 3.3 AI 工具 (AI Tools)
*   **本地 AI 执行工具:** 在本地运行开源大语言模型（LLM）。支持自动加载 **CUDA** 硬件加速库（通过 `LM` 类）。

### 3.4 系统工具 (System Tools)
*   **任务栏主题设置:** 深度定制 Windows 任务栏的外观、颜色和透明度。

---

## 4. 插件扩展机制

`RegistrationTool` 支持插件化扩展，插件可以通过以下方法将自己的工具分类注册到主程序中：

```java
public void addToolCategory(ToolCategory toolCategory, 
                            PluginDescriptor pluginDescriptor, 
                            String registeredName)
```

**命名空间规则:**  
为了防止不同插件之间的工具冲突，系统会自动使用 `插件注册名:工具注册名` 的格式生成全局唯一的标识符。

---

## 5. API 接口说明

### 5.1 注册方法

| 方法 | 描述 |
| :--- | :--- |
| `addToolCategory(ToolCategory, String)` | 注册一个新的工具分类（系统级使用）。 |
| `addToolCategory(ToolCategory, PluginDescriptor, String)` | **插件专用接口**。通过插件描述符注册分类。 |

### 5.2 查询方法

| 方法 | 描述 |
| :--- | :--- |
| `ToolCategory getToolCategory(UUID id)` | 根据 UUID 获取分类对象。 |
| `UUID getUUID(String registeredName)` | 根据注册名称（如 "system:debugTools"）获取其 UUID。 |
| `List<ToolCategory> getToolCategories()` | 获取当前所有已注册的分类列表。 |

---

## 6. 关键技术约束：注册时机

**生命周期限制:**  
`RegistrationTool` 的注册操作具有严格的时机限制：**必须在应用主窗口启动（`run` 方法执行完毕）之前完成。**

*   如果在主窗口已处于显示状态（`main.isWindow()` 为 `true`）时尝试添加工具，系统会通过日志记录 `logger.warn("Wrong time to add tools")` 并拒绝注册。
*   这种设计确保了 UI 在渲染初期能获得完整的工具树，避免动态修改 UI 导致的线程竞争或布局闪烁。

---

## 7. 错误处理

如果在注册过程中检测到**重复的注册名称**，该类会抛出 `RegistrationError`。这是一种致命错误，旨在提醒开发者工具标识符冲突，必须在开发阶段解决。

## 8. 示例代码：添加简单工具

```java
ToolCategory myCategory = new ToolCategory("我的工具", "icon.png", "说明");
myCategory.addTool(new ToolItem("弹窗演示", "btn.png", "点击会弹出消息", 100, new AbstractAction() {
    @Override
    public void actionPerformed(ActionEvent e) {
        JOptionPane.showMessageDialog(null, "你好，这是注册工具！");
    }
}));

// 注册到系统
registrationTool.addToolCategory(myCategory, "my_custom_tools");
```

---
*文档生成时间: 2026-01-02*