# crosspak

**Repository Path**: JiXieShi_STARSS/crosspak

## Basic Information

- **Project Name**: crosspak
- **Description**: **跨语言统一数据包构造与解析库**  
C++ 核心 + Python 绑定，一套代码，多语言无缝使用。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-14
- **Last Updated**: 2026-04-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# crosspak

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/Python-3.6+-blue.svg)](https://www.python.org/)
[![C++](https://img.shields.io/badge/C++-17-orange.svg)](https://isocpp.org/)

**跨语言统一数据包构造与解析库**  
C++ 核心 + Python 绑定，一套代码，多语言无缝使用。

## ✨ 特性

- ✅ **统一接口**：C++ 与 Python 提供完全一致的 API 风格
- ✅ **任意类型支持**：bool, char, int8/16/32/64, float, double, string, bytes
- ✅ **变长数据包**：内置长度前缀，支持动态负载
- ✅ **帧同步与校验**：同步头 + 负载长度 + CRC16 校验 + 可选帧尾
- ✅ **粘包/丢包处理**：状态机解析器，自动从字节流中恢复完整帧
- ✅ **跨平台**：Windows / Linux / macOS
- ✅ **易分发**：Python 包可打包为标准 Wheel

## 📦 安装

### Python 用户

```bash
pip install crosspak
```

### C++ 用户

```bash
git clone https://github.com/jixishi/crosspak.git
cd crosspak
mkdir build && cd build
cmake .. -DBUILD_TESTS=ON
cmake --build . -- -j
```

## 🚀 快速开始

### Python 示例

```python
import crosspak as cp

# 1. 构造数据包
pkt = cp.Packet()
pkt.write_int32(42)
pkt.write_float(3.14)
pkt.write_string("Hello, crosspak!")

# 2. 构建带帧同步的完整帧
builder = cp.FrameBuilder()
frame = builder.build_frame(pkt)   # 返回 bytes

# 3. 模拟接收端，处理粘包/丢包
parser = cp.FrameParser()
# 模拟一个混杂了残帧和完整帧的字节流
stream = b'\x00\x01' + frame[:10] + frame + b'\xFF'
packets = parser.parse(stream)

for p in packets:
    val = p.read_int32()
    f = p.read_float()
    s = p.read_string()
    print(f"Received: {val}, {f:.2f}, '{s}'")
```

### C++ 示例

```cpp
#include <crosspak/packet.h>
#include <crosspak/frame_builder.h>
#include <crosspak/frame_parser.h>
#include <iostream>

int main() {
    using namespace crosspak;

    // 1. 构造数据包
    Packet pkt;
    pkt.writeInt32(42);
    pkt.writeFloat(3.14f);
    pkt.writeString("Hello, crosspak!");

    // 2. 构建帧
    FrameBuilder builder;
    auto frame = builder.buildFrame(pkt);

    // 3. 模拟接收，解析
    FrameParser parser;
    auto packets = parser.parse(frame.data(), frame.size());

    for (auto& p : packets) {
        int32_t i = p.readInt32();
        float f = p.readFloat();
        std::string s = p.readString();
        std::cout << "Received: " << i << ", " << f << ", " << s << std::endl;
    }
    return 0;
}
```

## 📐 协议格式

```
┌────────────┬────────────┬───────────────┬────────────┬──────────────┐
│ Sync Word  │  Payload   │  Payload CRC  │   Footer   │   End Flag   │
│  (2 bytes) │  Length    │   (if any)    │ (Optional) │  (Optional)  │
│   0xAA55   │ (2/4 bytes)│               │            │              │
└────────────┴────────────┴───────────────┴────────────┴──────────────┘
```

- **同步头**：固定 `0xAA55`（小端），用于帧对齐。
- **负载长度**：2 字节无符号整数（可配置为 4 字节），表示后续负载的字节数。
- **负载**：由 `Packet` 序列化生成的二进制数据。
- **CRC16**：对负载部分的 CRC16-CCITT 校验值（可选）。
- **帧尾**：可选的 2 字节结束标志（如 `0x55AA`）。

## 📚 API 参考

### C++ 类

| 类名 | 主要方法 |
|------|----------|
| `Packet` | `writeBool`, `writeInt32`, `writeFloat`, `writeString`, `readBool`, `readInt32`, `readFloat`, `readString`, `data()`, `clear()` |
| `FrameBuilder` | `buildFrame(const Packet&)` → `std::vector<uint8_t>` |
| `FrameParser` | `parse(const uint8_t*, size_t)` → `std::vector<Packet>` |

### Python 类

| 类名 | 主要方法 |
|------|----------|
| `crosspak.Packet` | 与 C++ 同名方法，`data()` 返回 `bytes` |
| `crosspak.FrameBuilder` | `build_frame(packet)` → `bytes` |
| `crosspak.FrameParser` | `parse(data: bytes)` → `List[Packet]` |

详细 API 文档请参见 [Wiki](https://github.com/jixishi/crosspak/wiki)。

## 🛠 从源码构建

### 前置要求

- CMake ≥ 3.12
- C++17 编译器 (GCC, Clang, MSVC)
- (可选) Ninja 构建系统
- (Python 绑定) Python ≥ 3.6, pybind11

### 仅构建 C++ 库

```bash
git clone https://github.com/yourname/crosspak.git
cd crosspak
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -- -j
```

### 构建 Python 绑定 (并生成 Wheel)

```bash
pip install build   # 使用 PEP 517 构建工具
cd bindings/python
python -m build
```

生成的 `.whl` 文件位于 `dist/` 目录，可直接安装：

```bash
pip install dist/crosspak-*.whl
```

## 🧪 运行测试

### C++ 单元测试

```bash
cd build
cmake --build . --target test_crosspak
./tests/test_crosspak
```

### Python 测试

```bash
# 设置 PYTHONPATH 或先安装 wheel
python tests/test_crosspak.py
```

## 🤝 贡献

欢迎贡献代码、报告问题或提出新功能建议！请参考 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 📄 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。