下面是可直接交给执行 AI 的 **`update.md`**。
它不是重新设计系统，而是**进入 Phase-2：协议验证与优化阶段**的明确任务分解。

目标非常明确：

> **让仿真从“能运行”升级为“可解释 + 可优化 + 可移植 STM32WL”。**

---

# `update.md`

---

# LoRa Gradient Routing 仿真工程

## Phase-2 更新任务（Validation & Optimization）

---

# 0. 当前状态

项目已完成：

* 仿真框架 ✅
* 协议运行 ✅
* 自动测试 ✅
* 基础统计 ✅

当前问题：

```
PDR 偏低
大量节点直连 Sink
信道竞争严重
```

说明：

```text
系统功能正确，但协议行为尚未被验证与解释。
```

---

# 1. Phase-2 目标

执行 AI 必须将项目升级为：

```
Self-Explaining Simulation
```

即：

* 能解释性能来源
* 能定位瓶颈
* 能指导参数优化
* 能评估 STM32 可移植风险

---

# 2. 新增目录结构

必须新增：

```
sim/
├── analysis/
│   ├── validation_report.md
│   ├── topology_export.json
│   ├── timeseries.csv
│   └── plots/
│
├── analysis_tools/
│   ├── topology.py
│   ├── convergence.py
│   ├── channel_analysis.py
│   └── reliability_analysis.py
```

---

# 3. 必须新增的 Metrics（核心）

扩展 `metrics.py`。

---

## 3.1 路由稳定性指标

新增统计：

```python
route_changes[node_id]
parent_history[node_id]
cost_history[node_id]
```

计算：

```
route_change_rate =
    total_parent_changes / sim_time
```

验收标准：

```
收敛后 ≈ 0
```

---

## 3.2 Hop 分布

统计：

```
hop_count_per_packet
```

输出：

```
hop_histogram
```

必须证明：

```
存在 hop ≥ 2
```

否则判定：

```
多跳未形成
```

---

## 3.3 信道利用率（必须）

Channel 记录：

```
busy_time
idle_time
collision_time
```

计算：

```
channel_utilization =
    busy_time / total_time
```

输出：

| 利用率    | 判断  |
| ------ | --- |
| <30%   | 健康  |
| 30–60% | 可接受 |
| >70%   | 拥塞  |

---

## 3.4 丢包原因分解（非常重要）

新增 loss 分类：

```
LOSS_COLLISION
LOSS_NO_ROUTE
LOSS_RETRY_EXCEEDED
LOSS_CHANNEL_BUSY
```

输出比例。

---

# 4. 拓扑导出功能

新增：

```
analysis/topology_export.json
```

格式：

```json
{
  "nodes":[
    {"id":1,"x":10,"y":22,"cost":3,"parent":0}
  ]
}
```

用于：

* 外部绘图
* 拓扑检查
* 论文图生成

---

# 5. 时间序列记录

生成：

```
analysis/timeseries.csv
```

字段：

```
time,
avg_cost,
route_changes,
channel_utilization,
pdr_window
```

采样周期：

```
1s
```

---

# 6. 自动生成验证报告

必须自动生成：

```
analysis/validation_report.md
```

包含以下章节。

---

## 6.1 Topology Analysis

输出：

* parent tree
* hop distribution
* unreachable nodes

结论字段：

```
MULTIHOP_FORMED = TRUE/FALSE
```

---

## 6.2 Convergence Analysis

绘制：

```
time vs avg_cost
time vs route_changes
```

计算：

```
convergence_time
```

定义：

```
route_changes < threshold 持续30s
```

---

## 6.3 Channel Analysis

输出：

```
collision_rate
channel_utilization
tx_attempt_distribution
```

判断：

```
NETWORK_STATE:
    LIGHT_LOAD
    SATURATED
```

---

## 6.4 Reliability Breakdown

表格：

| 原因             | 比例 |
| -------------- | -- |
| collision      |    |
| retry_exceeded |    |
| no_route       |    |

---

## 6.5 STM32 Transfer Risk

自动生成：

| 项                       | Risk         |
| ----------------------- | ------------ |
| airtime realism         | LOW/MED/HIGH |
| ACK timeout safety      |              |
| channel saturation risk |              |

---

# 7. 参数扫描系统（新增）

新增：

```
analysis_tools/parameter_sweep.py
```

扫描参数：

```
HELLO_PERIOD ∈ [5,10,20]
DATA_PERIOD ∈ [20,40,60]
BACKOFF_MAX ∈ [1,2,4]
```

输出：

```
sweep_results.csv
```

包含：

```
PDR
avg_delay
collision_rate
utilization
```

---

# 8. 新测试（必须新增）

---

## test_multihop_exists.py

断言：

```python
assert max_hop >= 2
```

---

## test_route_stability.py

断言：

```
route_change_rate < threshold
```

---

## test_channel_not_saturated.py

断言：

```
utilization < 0.7
```

---

# 9. 禁止事项

执行 AI 禁止：

```
❌ 修改 routing 算法
❌ 修改 cost 函数
❌ 引入新协议
```

当前阶段只允许：

```
观察 + 测量 + 分析
```

---

# 10. Phase-2 验收标准

全部满足：

* [ ] 自动生成 validation_report.md
* [ ] 网络形成多跳
* [ ] 收敛时间可测量
* [ ] 信道利用率可计算
* [ ] 丢包原因可分解
* [ ] 新 tests 全通过

---

# 11. 完成后提交内容

执行 AI 必须输出：

```
analysis/
 ├── validation_report.md
 ├── topology_export.json
 ├── timeseries.csv
 └── plots/*.png
```

---

# 12. Phase-2 完成意义

完成后将获得：

```
协议行为模型（Behavior Model）
```

这一步完成后才允许进入：

```
STM32WL 移植阶段
```

---

# 13. 下一阶段（仅说明）

Phase-3 将进行：

```
MAC 优化
负载感知 routing
参数自动推导
```

但当前禁止提前实施。

---

**执行优先级（严格顺序）：**

```
1 metrics扩展
2 topology导出
3 timeseries记录
4 validation_report生成
5 新测试
6 参数扫描
```

---

完成 Phase-2 后，将仿真结果提交用于协议级评估。