Metadata-Version: 2.3
Name: seerapi-solaris
Version: 106.1.0
Summary: 支持Unity端解析的赛尔号客户端数据解析/整理工具
Keywords: seerapi
Author: Nattsu39
Author-email: Nattsu39 <Nattsu39@outlook.com>
License: MIT License
         
         Copyright (c) 2025 SeerAPI
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: anycrc>=1.3.5
Requires-Dist: click>=8.2.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: openapi-pydantic>=0.5.1
Requires-Dist: pydantic>=2.11.7
Requires-Dist: pydantic-settings>=2.10.1
Requires-Dist: seerapi-models>=106.1.0,<107.0.0
Requires-Dist: sqlmodel>=0.0.24
Requires-Dist: tqdm>=4.67.1
Requires-Dist: xmltodict>=1.0.2
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/SeerAPI/seerapi
Project-URL: Repository, https://github.com/SeerAPI/seerapi
Description-Content-Type: text/markdown

<div align="center">

# Solaris
~~[序外执行者（不吃香菜版）](https://www.bilibili.com/video/BV17g411b75m)~~</br>
赛尔号客户端数据解析/整理工具

[![Python](https://img.shields.io/badge/python->=3.10-blue.svg)](https://python.org)
[![Version](https://img.shields.io/badge/version-0.1.0-green.svg)](./pyproject.toml)

</div>

## 简介

Solaris 是 SeerAPI 的核心部分，用于解析和整理赛尔号三平台（Flash、HTML5、Unity）客户端数据。通过标准化的数据处理流程，将原始客户端数据转换为 [seerapi-models](https://github.com/SeerAPI/seerapi/tree/main/packages/seerapi-models) 定义的标准结构，并输出为 JSON 文件、数据库记录和相关资源文件。

## 功能特性

- 🎮 **多平台支持**: 支持 Flash、HTML5、Unity 三个平台的数据解析
- 📊 **数据标准化**: 将客户端原始数据转换为标准化格式
- 🗃️ **多格式输出**: 支持带 Schema 的 JSON 表格、SQLite 数据库输出
- 🔧 **模块化架构**: 基于插件式的解析器和分析器架构，易于扩展
- ⚡ **命令行接口**: 提供简洁易用的 CLI 工具

## 安装

确保你的 Python 版本 >= 3.10，然后安装 Solaris。

```bash
pip install seerapi-solaris

# 如果你使用 uv
uv add seerapi-solaris
```

## 使用方法

Solaris 提供了两个主要命令：`parse` 和 `analyze`。

### 基本用法

```bash
# 查看帮助
uv run solaris --help

# 查看版本
uv run solaris --version
```

### 数据解析 (parse)

将Unity客户端二进制数据文件解析为中间格式：

```bash
# 基本解析
solaris parse --source-dir /path/to/client/data --output-dir /path/to/output

# 查看可用的解析器
solaris parse --list-parsers

# 使用自定义解析器包
solaris parse --package-name my.custom.parsers
```

### 数据分析 (analyze)

将解析后的数据进行分析并输出为最终格式：

```bash
# 输出为 JSON 格式（默认）
solaris analyze --source-dir ./source --json-output-dir ./data --schema-output-dir ./schema

# 输出为数据库格式
solaris analyze --output-mode db --db-url solaris.db

# 同时输出 JSON 和数据库
solaris analyze --output-mode all

# 指定 API 信息
solaris analyze --api-url https://api.example.com --api-version v1beta

# 查看可用的分析器
solaris analyze --list-analyzers
```

## 命令参数详解

### parse 命令

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--source-dir` | `source` | 客户端数据源目录 |
| `--output-dir` | `output` | 解析结果输出目录 |
| `--package-name` | `solaris.parse.parsers` | 解析器包名（可多个） |
| `-l, --list-parsers` | - | 显示所有可用解析器 |

### analyze 命令

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `-w, --source-dir` | 环境变量或 `./source` | 数据源目录 |
| `-m, --output-mode` | `json` | 输出模式：json/db/all |
| `--json-output-dir` | `data` | JSON 文件输出目录 |
| `--schema-output-dir` | `schema` | JSON Schema 输出目录 |
| `-d, --db-url` | `solaris.db` | 数据库文件路径 |
| `--api-url` | 环境变量 | API 基础 URL |
| `--api-version` | 环境变量 | API 版本号 |
| `--package-name` | `solaris.analyze.analyzers` | 分析器包名（可多个） |
| `-l, --list-analyzers` | - | 显示所有可用分析器 |

## 环境变量

Solaris 支持通过环境变量进行配置：

```bash
# 数据源基础目录
export SOLARIS_DATA_BASE_DIR="/path/to/data"

# API 配置
export SOLARIS_API_URL="https://api.example.com"
export SOLARIS_API_VERSION="v1beta"

# 下列环境变量无法通过命令行指定

# 在仅设置SOLARIS_DATA_BASE_DIR的情况下，各分类数据源目录为  SOLARIS_DATA_BASE_DIR/[patch|html5|unity|flash]
# 设置下列变量以指定单个分类的目录
export SOLARIS_DATA_PATCH_DIR="/path/to/patch"
export SOLARIS_DATA_HTML5_DIR="/path/to/html5"
export SOLARIS_DATA_UNITY_DIR="/path/to/unity"
export SOLARIS_DATA_FLASH_DIR="/path/to/flash"

# 在输出中添加源信息
export SOLARIS_API_DATA_SOURCE="https://github.com/example/data.git"
export SOLARIS_API_DATA_VERSION="v1beta"
export SOLARIS_API_PATCH_SOURCE="https://example.com/patch"
export SOLARIS_API_PATCH_VERSION="v1beta"
```

## 项目结构

```
packages/solaris/
├── solaris/
│   ├── analyze/          # 数据分析模块
│   ├── cli/              # 命令行接口
│   │   ├── analyze.py    # analyze 命令实现
│   │   └── parse.py      # parse 命令实现
│   ├── parse/            # 数据解析模块
│   ├── settings.py       # 配置管理
│   ├── typing.py         # 类型定义
│   └── utils.py          # 工具函数
├── docs/                 # 开发文档
│   ├── PARSER_GUIDE.md
│   ├── ANALYZER_GUIDE.md
│   └── README.md
└── pyproject.toml
```

## 输出格式

### JSON 输出
- **数据文件**: 结构化的 JSON 表格，包含解析后的游戏数据
- **Schema 文件**: 对应的 JSON Schema 定义，用于数据验证
- **元数据**: API 版本、URL 等元信息

### 数据库输出
- **SQLite 数据库**: 包含所有解析数据的单一数据库文件

## 开发

### 环境要求

- Python >= 3.10
- 依赖管理：使用 `uv` 或 `pip`

### 代码风格

项目使用 Ruff 进行代码格式化和检查：

```bash
# 安装开发依赖
uv sync

# 代码检查
uv run ruff check .

# 代码格式化
uv run ruff format .
```

### 扩展开发

#### 添加新的解析器

1. 在 `solaris/parse/parsers/` 下创建新模块
2. 继承 `BaseParser` 类
3. 实现 `parse()` 方法

#### 添加新的分析器

1. 在 `solaris/analyze/analyzers/` 下创建新模块
2. 继承 `BaseAnalyzer` 类
3. 实现数据分析逻辑

## 贡献

目前该项目的parser只有寥寥几个，欢迎提交更多的parser！

## 许可证

本项目基于 [MIT License](LICENSE) 开源。
