Metadata-Version: 2.4
Name: surge-system
Version: 0.4.2
Summary: SURGE - 分布式动态任务系统
Home-page: https://github.com/hirakawaakano-cell/surge
Author: Hirakawa Akano
License: MIT
Project-URL: Homepage, https://github.com/hirakawaakano-cell/surge
Project-URL: Repository, https://github.com/hirakawaakano-cell/surge
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# SURGE — Scalable Universal Runtime for Group Execution

分布式动态任务执行系统 | MIT License

---

## 一句话

终端即插即用，任务动态拆解，全网资源共享，无人干预自主协同。

---

## 快速开始（仿真器，无需硬件）

```bash
git clone https://github.com/your-org/surge
cd surge

# 运行基础场景（5个终端入列、选举、任务分配、终端死亡重分配）
python sim/simulator.py --scenario basic --speed 10

# 计算卸荷场景（弱算力终端拆分大任务到多个计算节点）
python sim/simulator.py --scenario compute

# 监视器场景（带地面站的手动指挥）
python sim/simulator.py --scenario monitor

# 运行所有场景
python sim/simulator.py --scenario all

# 查看监视器界面
python sim/monitor_ui.py
```

## 核心特性

- **零出厂预设**：密钥首次上电时自生成，无任何预烧录秘密
- **全参数可配置**：所有权重、阈值、策略运行时可改，无需重编译
- **随进随出**：终端加入/退出不中断系统，任务自动重分配
- **计算拆分**：弱终端将大计算卸荷到多终端协同
- **借调存储**：中间结果可在其他终端暂存，满时自动迁移
- **多通信介质**：WiFi/蓝牙/LoRa/CAN/以太网自适应
- **即下即用**：固件 `make flash` 烧录后自动入网

## 架构

```
监视器（可选）  ──→  主机  ←──→  辅机  ←──→  从机1..N
                      │
            蓝牙/WiFi/LoRa/CAN/以太网
                      │
           ┌──────────┼──────────┐
       从机2        从机3      从机N
```

## 项目结构

```
surge/
├── docs/                     # 技术文档
│   └── 系统方案.md             # 完整技术方案
├── src/                      # 嵌入式C实现
│   ├── core/                 # 协议 + 信息池 + 配置
│   ├── security/             # 密钥自生成 + 加密
│   ├── interpreter/          # .mydrone 脚本解释器
│   ├── scheduler/            # 任务调度 + 计算拆分
│   ├── comms/                # 通信抽象层
│   └── terminal/             # 终端主运行时
├── sim/                      # Python仿真平台
│   ├── simulator.py          # 主仿真器
│   ├── virtual_terminal.py   # 虚拟终端
│   └── monitor_ui.py         # 监视器界面
├── scripts/                  # 工具
│   ├── config_gen.py         # 配置生成器
│   └── flash_tool.py         # 固件烧录工具
├── tests/                    # 单元测试
├── CMakeLists.txt
├── Makefile
└── README.md
```

## 使用

### 生成自定义配置

```bash
# 交互式
python scripts/config_gen.py --interactive

# 预设
python scripts/config_gen.py --preset drone --json my_config.json

# 参数覆盖
python scripts/config_gen.py --set join_policy 0 --set heartbeat_interval 500
```

### 烧录固件

```bash
# ESP32
python scripts/flash_tool.py --port COM3 --platform esp32 --firmware build/surge_esp32.bin

# 扫描并批量烧录
python scripts/flash_tool.py --platform esp32 --all
```

## 许可

MIT License — 自由使用、修改、分发。

## 贡献

欢迎提交 Issue 和 Pull Request。开发路线图见 `docs/系统方案.md` 第19章。
