@@ -60,7 +60,7 @@
| `net_config.h` | 配置宏定义（最大 Socket 数、超时时间等） |
| `net_types.h` | 类型定义（地址结构、Socket 控制块等） |
| `net_socket.h` | BSD Socket API 头文件，含 `net_msg_t` 消息类型定义 |
| `net_socket.c` | API 核心实现：消息队列处理与线程安全封装、内部 `_sock()` 版本；另含 L3 pending 化 recv、Trap 22 周期对账（200ms，去抖+冷却，只剩 ①②） |
| `net_socket.c` | API 核心实现：消息队列处理与线程安全封装、内部 `_sock()` 版本；另含 L3 pending 化 recv、Trap 22 周期对账（200ms，去抖+冷却，①②⑤ ）
| `net_listener.c` （ ） **监听生命周期 ** （ `net_listener_try` / `net_listener_clear` / `net_listener_retry_tick` （ ） `net_listener_pump` （唯一重建入口，100ms） `net_listener_settle` （沉降/隔离 100ms/400ms）；内部头，模拟器不编译 |
| `net_select.h` | select/poll API 头文件 |
| `net_select.c` | select/poll 实现（仅 MCU 端编译） |
@@ -153,7 +153,7 @@ sequenceDiagram
| 规则 | 说明 |
|------|------|
| * * `netTask` 外（任意应用任务）** | 公共 API：`net_send()` / `net_recv()` / `net_recv_to()` / `net_accept()` / `net_connect()` / `net_close()` / `net_listen()` ，及自愈 `net_relisten()` / `net_resync_listen()` ——请求入队列，netTask 串行执行，调用方阻塞等回执 |
| * * `netTask` 外（任意应用任务）** | 公共 API：`net_send()` / `net_recv()` / `net_recv_to()` / `net_accept()` / `net_connect()` / `net_close()` / `net_listen()` ——请求入队列，netTask 串行执行，调用方阻塞等回执。**自愈无显式 API**（N34 阶段1： `net_relisten()` / `net_resync_listen()` 已退役，静默回收/监听失位由对账⑤与 pump 自动认领，见 §3.6） |
| * * `netTask` 内** | 内部 API `net_send_sock()` / `net_recv_sock()` / `net_close_sock()` / `net_listen_locked()` |
| * * `net_socket()` / `net_bind()` ** | 直接调用，无需队列；实际在就绪屏障后的服务任务（timeSyncTask / ftpTask / uiTask）中创建监听 |
| * * `net_poll()` 和 `net_process_messages()` ** | 必须在 `netTask` 主循环调用；`net_process_messages()` 每轮先跑 **4 个非阻塞 tick ** （D10 重监听重试 → L3 挂起 recv 完成 → Trap 22 对账 200ms → N-32 监听器 pump 100ms），再处理队列 |
@@ -176,7 +176,7 @@ int net_close_sock(net_sock_t *p_sock);
- **`netTask` 不可向自身发消息**： `netTask` 中直接调 `net_send()` 会死锁（等待自己处理消息），必须在 `netTask` 中使用 `net_send_sock()` 等内部版本
- **阻塞 recv 不再独占 netTask（ ） `net_recv()` / `net_recv_to()` **登记挂起请求后返回 ** （每 fd 至多一个，禁止覆盖——覆盖即丢失前调用方通知 = 永久挂死）；完成由 `net_pending_tick()` 按主循环节拍检查（①数据 ②到点 ③断连，看门狗 1s）并经任务通知唤醒调用方——等待期间调用方在自己上下文睡通知，netTask 零占用（消除 E-02 头阻塞）。副作用：`buf` 指针须保持有效至返回；close / 网络重建 / 陈旧重同步会**显式取消并通知**（`NET_ERR_CONNRESET` 等），调用方永不挂死
- **队列阻塞语义**：只有 `osMessageQueuePut` 失败（8 长度固定队列，极端情形）时公共 API 阻塞；recv 挂起等待**不计入**队列占用（完成前队列中无消息滞留）
- **哪些操作要求 netTask 已运行**：`net_listen()` / `net_accept()` / `net_connect()` / `net_send()` / `net_recv()` / `net_close()` / `net_relisten()` / `net_resync_listen()` `net_socket()` / `net_bind()` 为直接调用，但同样建议屏障后；**`net_can_accept ()` / `net_can_read()` 是纯 RAM 读控制块**（§10.1），不入队、不等回执，**任意任务可安全周期调用**（用途 = 门控，把"无谓的 RPC"降为 0）
- **哪些操作要求 netTask 已运行**：`net_listen()` / `net_accept()` / `net_connect()` / `net_send()` / `net_recv()` / `net_close()` 全经消息队列 → 只能在就绪屏障后的任务调用；`net_socket()` / `net_bind()` 为直接调用，但同样建议屏障后；**`net_listener_armed ()` / `net_can_read()` 是纯 RAM 读控制块**（§10.1），不入队、不等回执，**任意任务可安全周期调用**（用途 = 门控，把"无谓的 RPC"降为 0）
### 3.6 芯片/本层状态对账与重监听自愈（Trap 09 / 22 / 23）
@@ -186,7 +186,7 @@ int net_close_sock(net_sock_t *p_sock);
|---|---|---|---|
| * * `auto_relisten` ** | 数据通道正常 EOF / DISCONNECT | 重开 + 重新 LISTEN，回 LISTENING；应用层无需 close/重 listen | `net_listen()` 置位；`net_close()` 清 |
| **D10 非阻塞重监听重试 ** | 重开失败（Trap 09：芯片 close 后需沉降） | 单次尝试失败即登记待重试，每轮到点重试；超时限放弃并记 `relisten give up` | 重试间隔 30ms / 时限 2s（自首次尝试）；同 fd 有在途挂起 recv 时跳过（L3 保险，防毁在途连接） |
| **Trap 22 周期对账 ** | 芯片丢 CONNECT/DISCONNECT 中断（快速复连）；或静默回收 Socket（ 两 类**失同步：① 本层 ESTABLISHED 而芯片已断 → 按断开处理；② 本层 LISTENING 而芯片已握手 → 补 accept（ ） **1s 冷却 ** （防"刚 open 未生效"瞬态重建风暴） |
| **Trap 22 周期对账 ** | 芯片丢 CONNECT/DISCONNECT 中断（快速复连）；或静默回收 Socket（ 三 类**失同步：① 本层 ESTABLISHED 而芯片已断 → 按断开处理；② 本层 LISTENING 而芯片已握手 → 补 accept；⑤ 本层 ESTABLISHED 而芯片已静默回收回 LISTEN（ `net_resync_listen` 的语义并入； ③④ 已移交 pump） **1s 冷却 ** （防"刚 open 未生效"瞬态重建风暴） |
| **N-32 监听器 pump ** （**唯一重建入口**） | 监听型 fd 的芯片状态与本层不一致（会话结束待重建 / 本层状态滞后） | 每 100ms 检查监听型 fd：芯片失位即重建（`net_listener_try` ）；本层 CLOSED 而芯片**正在** LISTEN 时**只做状态重同步**、不发芯片命令 | 周期 100ms；连续 2 次失配（≈200ms）+ 动手后 1s 冷却；其它位置只置事实、不做重建动作 |
| **Trap 23 排渣隔离 ** | 异常释放（芯片 TIMEOUT，如客户端中止上传）：在途数据落进 RX 缓冲，直接复监听 → 下条连接把 ~2048B 残渣当自己的数据读走（上传静默截断）；正常 FIN 释放亦有残留 DISCONNECT 收尾问题 | 复监听前沉降/隔离：持续排空 RX 残渣 + 主动 close + 排空中断，等芯片回 CLOSED/TCP_CLOSED 才 open+listen；到期强制放行 | 沉降等级（`net_listener_settle` ）：异常释放 QUARANTINE **400ms ** / 正常释放 GRACEFUL **100ms ** （ **800ms ** 强制放行（**必须 < 2s 时限**，否则监听被放弃） |
@@ -875,20 +875,20 @@ int net_accept(int sockfd, struct net_sockaddr *addr, int *addrlen);
> 单连接模式：监听 Socket 在 CONNECT 后**自身即数据通道**（§5.1）。`net_accept` 失败时若状态为 CLOSED 且 `auto_relisten` 开启，内部触发**非阻塞**重监听（失败交重试轮询，§3.6）。中断丢失也不会让监听死亡——对账在 200ms 内修正"本层 LISTENING 而芯片监听消失"等失同步。
#### net_can_accept / net_can_read - 就绪门控（**纯 RAM 读，不走消息队列**）
#### net_listener_armed / net_can_read - 就绪门控（**纯 RAM 读，不走消息队列**）
``` c
int net_can_accept ( int sockfd ) ; /* 1 = 有连接可接受 ； 无 */
int net_can_read ( int sockfd ) ; /* 1 = 应发一次 recv；
int net_listener_armed ( int sockfd ) ; /* 1 = 监听器在服役，值得发起 accept ； 跳过本轮 */
int net_can_read ( int sockfd ) ; /* 1 = 应发一次 recv；
```
| 项 | 说明 |
|------|------|
| 代价 | **零 RPC ** ：只读 Socket 控制块（`net_get_sock()` ），不入队、不等 netTask 回执 → 任意任务上下文可安全周期调用，**不被 netTask 忙碌程度拖住** |
| `net_can_accept ` 判据 | `state == ESTABLISHED` ，与 `net_accept_locked()` 严格等价（单连接模型：监听 Socket 自身在 CONNECT 后转数据通道 ）
| `net_listener_armed ` 判据 | `ESTABLISHED` （ `LISTENING` ，或 `CLOSED + auto_relisten` **且 RX 有残留 ** （ `net_can_accept()` 只认 `ESTABLISHED` ，会把监听服役窗口全挡掉、丢 CONNECT 探针从不运行——N34 阶段1 已退役，其 ESTABLISHED 放行态并入本函数，勿再引入 ）
| `net_can_read` 判据 | `ESTABLISHED` → 看 `readable` ； `ESTABLISHED` 一律返 1**（必须让上层 recv 一次拿到 EOF/错误并复位自身状态，门掉它会把"连接已消失"永久藏住）；描述符失效也返 1（让 recv 报 BADF 走既有错误分支） |
| 用途 | **门控 ** ：无活时跳过 `net_accept()` /`net_recv()` ——两者内部都是 `osMessageQueuePut(osWaitForever)` + `xTaskNotifyWait(portMAX_DELAY)` ，**均无上界**（队列深 8 且与 FTP/timeSync 共享） |
| ⚠ 不可作为唯一判据 | `readable` 只由 RECV_OK 中断置位，而 §3.6 的三类 对账**不含**"芯片 RX 非空但 `readable=0` " → 中断丢失时 `net_can_read()` 恒返 0。**调用方必须保留低频兜底 recv**（`ui_net_sink.c` 每 32 轮无条件收一次，教训见 `docs/子系统设计/看门狗设计说明.md` §11.5 第 1 条） |
| ⚠ 不可作为唯一判据 | `readable` 只由 RECV_OK 中断置位，而 §3.6 的对账**不含**"芯片 RX 非空但 `readable=0` " → 中断丢失时 `net_can_read()` 恒返 0。**调用方必须保留低频兜底 recv**（`ui_net_sink.c` 每 32 轮无条件收一次，教训见 `docs/子系统设计/看门狗设计说明.md` §11.5 第 1 条） |
| 竞态 | netTask 是唯一写者，单字读；最坏"晚一轮发现"（ `net_poll()` ）或"扑空"（ `NET_ERR_WOULDBLOCK` ），均无副作用 |
| 模拟器端 | `net_socket_sim.c` 同名实现**恒返回 1**——Winsock 本就非阻塞、无 RPC 成本，恒 1 使门控在模拟器上逐位等价于改前行为 |
@@ -979,21 +979,14 @@ int net_sock_state(int sockfd);
跨任务只读快照（单字节读）；描述符无效/未占用返回 -1；值可能滞后 netTask 最新状态。用于**状态轮询**（客户端等 ESTABLISHED，§5.2），不替代 accept/connect。
**net_resync_listen — 断连重同步（仅修 MCU 侧 ） **
**net_resync_listen / net_relisten — 已退役（N34 阶段1，勿再引入 ） **
``` c
int net_resync_listen ( int sockfd ) ;
```
两者曾是"应用层手动自愈"入口：`net_resync_listen()` 只修 MCU 侧状态（D14 静默回收），`net_relisten()` 无条件芯片侧 open+listen。现状：
适用场景（D14）：对端 FIN 后芯片**静默回收** Socket 回监听且**不发 DISCONNECT 中断** → 本层滞留 ESTABLISHED，新连接字节被旧会话吞掉。须**确认连接已死**（如控制通道超时中止后）再调；只把本层状态改回 LISTENING 并取消本 fd 挂起 recv， 。
- **静默回收**由对账⑤自动认领（§3.6：本层 ESTABLISHED 而芯片 0x05/0x01 → RESYNC 语义，≤400ms 去抖 + 1s 冷却，纪律"不发芯片命令"原样保留在认领动作内）——应用无需判定"连接是否已死"，也就消除了"误判活连接调 resync 把活连接标成监听态"的 footgun
- **监听重建**由 pump（100ms 周期，唯一重建入口）/ D10（30ms 重试）单一所有者负责——`net_relisten()` 对健康监听器反而是 footgun（无条件 open→USE→close 自毁 ~1s，原注释自认）。
**net_relisten — 无条件重新监听 **
``` c
int net_relisten ( int sockfd ) ;
```
TCP 监听型 Socket：芯片侧 open+listen（D10 非阻塞重试）。芯片侧已在监听时：首次 open 失败 → close 重建 → 监听短暂中断 ~1s；两种情形都收敛到"监听器确定在位"。用途：代次号变化后显式重建（见 `docs/子系统设计/网络配置说明.md` §4）、应用判定连接已死需确定性监听。正常流无需（auto_relisten + 对账已覆盖）。返回 0 成功 / -1 失败。
生产调用者本就为零（仅板级测试 Phase 13，已改由自动机制接管）。历史实现见 `net_socket.c` git 历史。
**net_getsockname — 获取 Socket 本地地址（IP+端口） **
@@ -1011,14 +1004,14 @@ Socket 已创建或已绑定时可用；port 为 0（动态分配）时返回已
void net_process_messages ( void ) ;
```
处理其他任务投递的请求（send/recv/connect/accept/close/**resync-listen / relisten** ）。每次调用先跑 4 个**非阻塞** tick，再取队列消息（0 超时出队）：
处理其他任务投递的请求（send/recv/connect/accept/close）。每次调用先跑 4 个**非阻塞** tick，再取队列消息（0 超时出队）：
1. **D10 重监听重试 ** （ `net_listener_retry_tick` ）：断连后监听器恢复的到点重试（30ms 间隔 / 2s 时限，§3.6）
2. **L3 挂起 recv 完成检查 ** （ `net_pending_tick` ）：按 ①数据 ②到点 ③断连 检查每个挂起请求并通知调用方（看门狗 1s）
3. **Trap 22 芯片/本层对账 ** （ `net_reconcile_tick` ）：200ms 周期修正**两 类**失同步（①②，§3.6）
3. **Trap 22 芯片/本层对账 ** （ `net_reconcile_tick` ）：200ms 周期修正**三 类**失同步（①②⑤ ，§3.6）
4. **N-32 监听器 pump ** （ `net_listener_pump` ）：100ms 周期，**唯一重建入口**（③④；本层 CLOSED 而芯片在听时只重同步，不发芯片命令，§3.6）
> `net_msg_t.timeout_ms`： （ 含 `NET_MSG_RESYNC_LISTEN`（仅 MCU 侧状态）与 `NET_MSG_RELISTEN`（芯片侧重监听 ）。
> `net_msg_t.timeout_ms`： （ 仅 6 种（send/recv/close/connect/listen/accept）——自愈类消息 `NET_MSG_RESYNC_LISTEN` / `NET_MSG_RELISTEN` 已随 API 退役删除（N34 阶段1 ）。
#### net_send_sock - 发送数据（内部版本）
@@ -1289,10 +1282,9 @@ if (len < 0 && net_get_errno() == NET_ERR_WOULDBLOCK) {
（ `ui_net_sink` 曾在 EOF 时无条件 `net_close` ，表现为 7003 答完一帧即断连、
端口随后"连接被拒"。）
**芯片静默回收（D14， ** ：对端发 FIN 后，芯片可能**自行把 Socket 回收回 LISTEN 且不发 DISCONNECT 中断** → 本层滞留 ESTABLISHED，应用继续往死连接上读写，新连接的字节被旧会话吞掉。两种处理：
**芯片静默回收（D14， ** ：对端发 FIN 后，芯片可能**自行把 Socket 回收回 LISTEN 且不发 DISCONNECT 中断** → 本层滞留 ESTABLISHED，应用继续往死连接上读写，新连接的字节被旧会话吞掉。
1. **等对账自愈（默认，推荐） ** ：§3.6 对账 ≤200ms 发现"本层 ESTABLISHED 而芯片已回收" → 按断开处理 → 自动重监听；等待期间该端口实际可接新连接（芯片侧已 LISTEN），新连接经对账补 accept 被本层感知 。
2. **显式重同步（需立即对齐时） ** ：确认会话已死（如控制通道超时中止）后调 `net_resync_listen(fd)` ——只修 MCU 侧状态 + 取消挂起 recv，
**无需应用处理（N34 阶段1 起） ** ：对账⑤自动认领此形态（§3.6：≤400ms 去抖 + 1s 冷却）→ RESYNC 语义只修本层状态 + 取消本 fd 挂起 recv，**不发任何芯片命令**（发 close/重监听会摧毁芯片侧健康监听器 → 连接永拒，run8 实证 170s 拒绝）。等待期间该端口实际可接新连接（芯片侧已 LISTEN），新连接经对账补 accept 被本层感知。原显式 API `net_resync_listen(fd)` 已退役——"应用判定连接已死"这一步本身就是误判源（对活连接调用会把活连接标成监听态） 。
⚠ 切勿用**单次**芯片状态读决定重建：单次读可能落在"刚 open 未生效"瞬态，曾致监听反复重建直至 `relisten give up` （
@@ -1380,7 +1372,7 @@ CH395F 底层驱动返回的状态码（`ch395f_get_cmd_status()` 或 `ch395f_po
**问题：哪些操作要求 netTask 已运行？ **
`net_listen()` / `net_accept()` / `net_connect()` / `net_send()` / `net_recv()` / `net_close()` / `net_relisten()` / `net_resync_listen()` `net_socket()` / `net_bind()` 为直接调用，但同样建议在屏障后。
`net_listen()` / `net_accept()` / `net_connect()` / `net_send()` / `net_recv()` / `net_close()` 全部经消息队列 → 只能在**netTask 已运行的上下文**（就绪屏障后的服务任务）调用；内核启动前的代码禁调任何 FreeRTOS/CMSIS-RTOS API，网络监听建立天然在内核启动后。`net_socket()` / `net_bind()` 为直接调用，但同样建议在屏障后。
**问题：消息队列由谁创建？在哪里创建？ **
@@ -1403,7 +1395,7 @@ CH395F 底层驱动返回的状态码（`ch395f_get_cmd_status()` 或 `ch395f_po
| 场景 | 修复前症状 | 机制 | 生产验证（2026-09-23）
|---|---|---|---|
| **Trap 22 ** 快速复连丢中断 → 监听静默死亡 | 待机后 UI `:7003` 快速复连 2/10 且**永久**拒连；FTP `:21` 100ms 间隔自第 29 轮死亡；设备日志**无报错**（状态静默滞留） | 周期对账 `net_reconcile_tick()` （ `net_listener_pump()` （ ， `handle_disconnect_event` 只置沉降事实、不再自行重建 | `:7003` 10/10； `:21` 100ms/0ms/600ms 各 50/50； ； （
| **Trap 22 ** 快速复连丢中断 → 监听静默死亡 | 待机后 UI `:7003` 快速复连 2/10 且**永久**拒连；FTP `:21` 100ms 间隔自第 29 轮死亡；设备日志**无报错**（状态静默滞留） | 周期对账 `net_reconcile_tick()` （ ⑤ ） `net_listener_pump()` （ ， `handle_disconnect_event` 只置沉降事实、不再自行重建 | `:7003` 10/10； `:21` 100ms/0ms/600ms 各 50/50； ； （
| **Trap 23 ** 中止后首笔复连上传被静默截断 ≤2048B 并误报 226 成功 | RST/FIN 中止上传 → 紧接着的首笔上传"收"到 ~2KB 残留后判结束回 226 → 客户端以为成功 = **静默数据损坏 ** （第二笔起正常） | 异常释放（TIMEOUT）预重监听隔离：`net_drain_chip_rx()` 分块排空 RX 残渣 + 主动 close + 排空中断 + 等 CLOSED/TCP_CLOSED（ ，
| **Trap 21 ** （ ） **结论：非缺陷 ** （芯片 RX 缓冲即窗口，对端填满是常态）；判据改为脚本层 STEP + 客户端内容校验（RET SHA-256），虚警工具归档（`MDK-ARM/retracted_bench_20260922/` ， × ×
@@ -1415,6 +1407,7 @@ CH395F 底层驱动返回的状态码（`ch395f_get_cmd_status()` 或 `ch395f_po
| 日期 | 变更 |
|------|------|
| 2026-10-13 | **N34 阶段1 API 面收敛 ** （审计见 `docs/网络/N34-自愈审计/README.md` ）：删除手动自愈 API `net_relisten()` / `net_resync_listen()` （生产零调用；后者语义并入对账**⑤**——本层 ESTABLISHED 而芯片 0x05/0x01 静默回收 → RESYNC 只修本层，§3.6 对账由两类扩为三类①②⑤；前者与 pump/D10 重叠且对健康监听器是 footgun）与 `net_can_accept()` （只认 ESTABLISHED 的旧门控挡死丢 CONNECT 探针，监听门控统一 `net_listener_armed()` ，§10.1 门控节改写）；`NET_MSG_RESYNC_LISTEN` / `NET_MSG_RELISTEN` 消息类型删除；timeSync 会话收尾不再 `net_close` （同 fd 续 accept，监听跨会话常驻）；lftpd 应用层阻塞重试退役（就绪屏障已消除 Trap 09 启动形态） |
| 2026-10-12 | **N-32 监听生命周期模块化 + 单一所有者 ** ：监听生命周期抽为 `net_listener.c` （§2.2 文件表新增该行，真机专属）；主循环自愈 tick 由 3 个增至 **4 个 ** （新增 `net_listener_pump` ， ， `net_reconcile_tick` 对账收窄为 ①②，③④ 移交 pump；`handle_disconnect_event` / `handle_timeout_event` 改为 `net_listener_settle(GRACEFUL 100ms / QUARANTINE 400ms)` **只置事实 ** 、不再自行重建；§3.3 / §3.6（四层自愈 → **五层 ** ） `docs/子系统设计/网络Socket监听生命周期设计说明.md` §10 |
| 2026-10-10 | 新增 * * `net_can_accept()` / `net_can_read()` 就绪门控 API**（§10.1）：纯 RAM 读控制块、**不走消息队列、不等 netTask 回执**，供实时性敏感任务在发 RPC 前判断"有没有活"（动因 = `ui_net_sink_poll()` 每 10 ms 一次 `net_accept` 把 uiTask 拖成最坏 ≈50 ms；原拟登记 N-19 / C7，当日结案不入登记簿；设计与实测见 `docs/子系统设计/看门狗设计说明.md` §11（原分析文档已并入该节））；§3.5 补"netTask 运行要求"例外条；⚠ 记录两条使用约束——**不可作为唯一判据**（`readable` 只由 RECV_OK 中断置位，须保留低频兜底 recv）与**模拟器后端恒返 1**（`net_socket_sim.c` ，
| 2026-09-23 | 同步 L3 pending 化、D10 非阻塞重监听、Trap 22 对账、Trap 23 排渣隔离后的现状：新增 `net_recv_to` / `net_sock_state` / `net_resync_listen` / `net_relisten` （§10.1）及 `net_getsockname` ；§3 新增 3.6（对账与自愈四机制）、3.3/3.5 改写（recv 挂起模型、队列语义、netTask 运行要求）；§4/§5 示例更新（监听由就绪屏障后服务任务建立、`net_sock_state` 轮询）；§10.2 改述 `net_process_messages()` 每轮节奏（重监听重试 → 挂起 recv 完成 → 200ms 对账 → 队列），补 `timeout_ms` /新消息类型说明；新增 §11.2 分片阻塞读（`net_recv_to` ）；§12.1/12.3/12.4/12.9 更新，新增 §12.10（自愈行为数据与排障判据，含 Trap 21 结案） |
