# Sophon Chakcy 插件管理系统使用文档

## 系统概述

Sophon Chakcy 是一个基于 Sophon SAIL 的插件化目标检测框架，核心是动态插件管理系统，而非具体的检测算法。YOLOv8 仅作为预置的插件示例，系统支持任意检测算法的插件化扩展。

### 核心特性

- **动态插件加载**：运行时根据名称动态加载对应检测器
- **统一配置管理**：集中管理所有插件配置
- **资源虚拟化**：支持 SQLite VFS 打包模型和配置
- **模块化设计**：插件间互相独立，易于扩展和维护

## 核心架构

```text
sophon_chakcy/
├── get_detector.py      # 核心插件管理器
├── __init__.py         # 工具函数
└── build.py            # 插件打包工具
```

## 关键组件解析

### 1. 插件管理器 (get_detector.py)

```python
def get_detector(name: str, is_vfs: bool = False):
    """核心插件加载函数
    
    Args:
        name: 插件名称（在config.json中定义）
        is_vfs: 是否从VFS加载资源
        
    Returns:
        tuple: (检测器类, 配置字典)
    """
```

**工作原理：**

1. 根据插件名称查找 `config.json` 中的配置
2. 动态导入对应的 Python 模块
3. 加载插件配置文件
4. 返回检测器类和配置对象

### 2. 配置文件结构

```json
{
  "model_map": {
    "yolov8": {
      "name": "yolov8",
      "module": "YOLOv8.yolov8_detector",  # 模块导入路径
      "config": "configs/yolov8_config.json"  # 插件配置文件
    }
  }
}
```

## 插件接口开发指南

### 插件接口规范

每个插件必须提供以下接口：

#### 1. 配置类（必需）

```python
from dataclasses import dataclass
from typing import Dict, Any

@dataclass
class PluginConfig:
    """插件配置基类"""
    bmodel_path: str
    classes: list
    
    @classmethod
    def from_dict(cls, data: Dict[str, Any]) -> "PluginConfig":
        """从字典创建配置对象"""
        return cls(**data)
```

#### 2. 检测器类（必需）

```python
class Detector:
    """插件检测器基类"""
    
    def __init__(self, config_dict: Dict[str, Any], is_vfs: bool = False, 
                 vfs_path: str = "./application.svfs", dev_id: int = 0,
                 conf_thresh: float = 0.25, nms_thresh: float = 0.7):
        """
        初始化检测器
        
        Args:
            config_dict: 配置字典
            is_vfs: 是否使用VFS
            vfs_path: VFS文件路径
            dev_id: 设备ID
            conf_thresh: 置信度阈值
            nms_thresh: NMS阈值
        """
        self.config = PluginConfig.from_dict(config_dict)
        # 其他初始化逻辑...
    
    def detect_single_image(self, image_path: str, output_dir: str = "./results") -> list:
        """单张图像检测接口"""
        pass
    
    def detect_images_in_directory(self, input_dir: str, output_dir: str = "./results"):
        """批量图像检测接口"""
        pass
```

### 创建新插件的完整流程

#### 步骤1：创建插件目录结构

```text
my_detector/
├── __init__.py
├── my_detector.py      # 主检测器文件
├── preprocess.py       # 预处理模块（可选）
├── postprocess.py      # 后处理模块（可选）
└── utils.py           # 工具函数（可选）
```

#### 步骤2：实现检测器类

```python
# my_detector/my_detector.py
import os
import numpy as np
from dataclasses import dataclass
from typing import List, Dict, Any

import sophon_chakcy.sail as sail
from .preprocess import Preprocessor
from .postprocess import Postprocessor

@dataclass
class MyDetectorConfig:
    """自定义检测器配置"""
    bmodel_path: str
    classes: List[str]
    input_size: tuple = (640, 640)
    mean: List[float] = None
    std: List[float] = None
    
    @classmethod
    def from_dict(cls, data: Dict[str, Any]) -> "MyDetectorConfig":
        return cls(**data)

class Detector:
    """自定义检测器实现"""
    
    def __init__(self, config_dict: Dict[str, Any], is_vfs: bool = False,
                 vfs_path: str = "./application.svfs", dev_id: int = 0,
                 conf_thresh: float = 0.25, nms_thresh: float = 0.7):
        
        # 解析配置
        self.config = MyDetectorConfig.from_dict(config_dict)
        
        # 加载模型
        if is_vfs:
            from sqlite_vfs.core import SQLiteVFS
            vfs = SQLiteVFS(vfs_path)
            bmodel_bytes = vfs.read_file(self.config.bmodel_path)
            bmodel_size = vfs.get_file_info(self.config.bmodel_path)["file_size"]
            self.net = sail.Engine(bmodel_bytes, bmodel_size, dev_id, sail.IOMode.SYSO)
        else:
            self.net = sail.Engine(self.config.bmodel_path, dev_id, sail.IOMode.SYSO)
        
        # 初始化组件
        self.preprocessor = Preprocessor(self.config)
        self.postprocessor = Postprocessor(
            conf_thresh=conf_thresh,
            nms_thresh=nms_thresh,
            classes=self.config.classes
        )
        
        # 其他初始化...
        print(f"插件 '{self.__class__.__name__}' 初始化完成")
    
    def detect_single_image(self, image_path: str, output_dir: str = "./results"):
        """实现单图检测逻辑"""
        # 1. 读取图像
        # 2. 预处理
        # 3. 推理
        # 4. 后处理
        # 5. 返回结果
        pass
    
    def detect_images_in_directory(self, input_dir: str, output_dir: str = "./results"):
        """实现批量检测逻辑"""
        for img_file in os.listdir(input_dir):
            img_path = os.path.join(input_dir, img_file)
            self.detect_single_image(img_path, output_dir)
```

#### 步骤3：创建插件配置文件
```json
// configs/my_detector_config.json
{
  "bmodel_path": "models/my_model.bmodel",
  "classes": ["cat", "dog", "person"],
  "input_size": [640, 640],
  "mean": [0.485, 0.456, 0.406],
  "std": [0.229, 0.224, 0.225]
}
```

#### 步骤4：注册插件

修改 `config.json` 添加新插件：

```json
{
  "model_map": {
    "yolov8": {
      "module": "YOLOv8.yolov8_detector",
      "config": "configs/yolov8_config.json"
    },
    "my_detector": {
      "module": "my_detector.my_detector",
      "config": "configs/my_detector_config.json"
    },
    "faster_rcnn": {
      "module": "faster_rcnn.detector",
      "config": "configs/faster_rcnn_config.json"
    }
  }
}
```

#### 步骤5：测试插件

```bash
# 使用新插件
python main.py --name my_detector --input ./test.jpg
```

### 插件打包与部署

#### 1. 打包工具详解 (build.py)

构建工具执行以下任务：

1. **读取配置**：解析 `config.json` 中的所有插件配置
2. **打包模块**：将插件模块打包到 SQLite 模块库
3. **打包资源**：将模型和配置文件打包到 VFS
4. **生成部署包**：创建完整的可部署包

#### 2. 打包命令

```bash
# 基本打包
python -m sophon_chakcy.build

# 自定义输出路径
python -m sophon_chakcy.build --vfs_path my_app.svfs --mbank_path my_plugins.mbank

# 详细日志
python -m sophon_chakcy.build --verbose
```

#### 3. 部署结构

```text
部署目录/
├── main.py                    # 主程序（使用VFS和模块库）
├── application.svfs          # 虚拟文件系统
│   ├── config.json
│   ├── configs/yolov8_config.json
│   ├── configs/my_detector_config.json
│   ├── models/yolov8n.bmodel
│   └── models/my_model.bmodel
└── plugins.mbank             # Python模块库
    ├── YOLOv8
    ├── my_detector
    └── faster_rcnn
```