fix：重构网络模块并补上文档

.gitignore

@@ -39,3 +39,7 @@ os/loongarch.log
 
 # Local notes
 os/可能的改进.md
+
+# Local agent guidance
+**/AGENTS.md
+docs/superpowers/

docs/pr_recorde/network_rearchitecture_new_main.md

@@ -0,0 +1,25 @@
+# ✨ Feature / 新功能
+
+## 🚀 描述 (Description)
+
+本次拉取请求在 `new-main` 上落实网络模块重构，主要改进如下：
+
+- 收口网络协议栈运行时：新增 `NetworkStack` 门面，将 smoltcp socket set、active interface runtime、loopback link 和 poll 推进统一放到 `os/src/net/stack.rs`。
+- 清理 socket/syscall 边界：`SocketFile` 的读写、可读可写、recvfrom、sendto、drop 等路径改为经 `NetworkStack` 操作协议栈；网络 syscall 不再直接访问 `SOCKET_SET`、`NET_IFACE` 或 `smoltcp::socket::{tcp, udp}`。
+- 拆分设备与接口职责：VirtIO net 初始化只注册 `NetDevice`，接口创建统一由网络子系统入口负责；`NetworkInterface` 不再直接实现 `Driver`，改由 `NetDriverHandle` 作为兼容桥。
+- 显式建模 loopback：新增 `LoopbackNetDevice`，默认网络初始化确保 `lo` 存在；`NullNetDevice` 不再承担 loopback 语义。
+- 更新网络文档：补齐 `document/net/` 面向读者的模块文档，并恢复/补充 `document/net/`、`document/arch/*/network_rearchitecture.md` 中的施工记录。
+- 清理本地协作文件：`.gitignore` 忽略各处 `AGENTS.md` 和 `docs/superpowers/` 草稿目录；补充 unused 类告警忽略标签，避免重构期间被旧未使用告警阻塞。
+
+本记录基于以下提交：
+
+- `2d93e1d chore: 忽略本地代理与草稿文档`
+- `16b161f docs: 更新网络重构文档`
+- `11ca651 fix: 忽略未使用告警`
+- `37cc37e fix: 收口网络协议栈运行时`
+- `4ad26a9 fix: 拆分网络设备与接口`
+- `e1281ae fix: 修正文档空行`
+
+## 🔗 关联 Issue
+
+暂无关联 Issue。

document/SUMMARY.md

@@ -24,7 +24,14 @@
 
 # 网络
 
-- [网络实现指南](net/network_implementation_guide.md)
+- [网络模块概览](net/README.md)
+  - [整体架构](net/architecture.md)
+  - [设备与接口](net/device_and_interface.md)
+  - [协议栈运行时](net/stack_runtime.md)
+  - [Socket 与 syscall](net/socket_syscall.md)
+  - [Loopback 与 poll](net/loopback_poll.md)
+  - [测试与排查](net/testing.md)
+  - [网络实现指南](net/network_implementation_guide.md)
   - [netperf / netserver 测试说明](net/netperf.md)
 
 # 同步原语
@@ -101,11 +108,13 @@
 - [用户栈布局](arch/riscv/stack_layout.md)
 - [多核启动](arch/riscv/smp_boot.md)
 - [核间中断 (IPI)](arch/riscv/ipi.md)
+- [网络重构说明](arch/riscv/network_rearchitecture.md)
 
 ## LoongArch64
 
 - [LoongArch64](arch/loongarch/README.md)
   - [启动与用户态运行修复总结（comix-1 当前分支）](arch/loongarch/bringup_userland.md)
+  - [网络重构说明](arch/loongarch/network_rearchitecture.md)
 
 
 ---

document/arch/loongarch/network_rearchitecture.md

@@ -0,0 +1,9 @@
+# LoongArch 网络重构说明
+
+LoongArch 网络重构不需要在网络核心中引入架构差异。架构层只负责 syscall 分发、trap 上下文和用户指针访问前置条件。
+
+## 规则
+
+- syscall 号和参数寄存器差异只放在 `os/src/arch/loongarch/`。
+- `os/src/kernel/syscall/network.rs` 接收架构无关的参数值。
+- 网络核心不得根据 LoongArch 条件编译分叉。

document/arch/riscv/network_rearchitecture.md

@@ -0,0 +1,9 @@
+# RISC-V 网络重构说明
+
+RISC-V 网络重构不需要在网络核心中引入架构差异。架构层只负责 syscall 分发、trap 上下文和用户指针访问前置条件。
+
+## 规则
+
+- syscall 号和参数寄存器差异只放在 `os/src/arch/riscv/`。
+- `os/src/kernel/syscall/network.rs` 接收架构无关的参数值。
+- 网络核心不得根据 RISC-V 条件编译分叉。

document/net/README.md

@@ -0,0 +1,21 @@
+# 网络模块概览
+
+网络模块负责把内核网卡设备、接口配置、smoltcp 协议栈、VFS socket 文件和网络 syscall 连接起来。
+
+## 源码入口
+
+- `os/src/device/net/`：网卡设备抽象和 VirtIO/loopback/null 设备。
+- `os/src/net/interface.rs`：接口注册表、接口配置和 smoltcp interface 兼容工厂。
+- `os/src/net/stack.rs`：`NetworkStack` 门面和协议栈运行时状态。
+- `os/src/net/socket.rs`：`SocketFile`、fd/socket 映射、UDP per-fd 队列和兼容实现。
+- `os/src/kernel/syscall/network.rs`：网络 syscall ABI 层。
+
+## 文档导航
+
+- `architecture.md`：整体分层和依赖方向。
+- `device_and_interface.md`：设备注册、接口对象和中断兼容桥。
+- `stack_runtime.md`：smoltcp runtime、poll、socket set 和 loopback link。
+- `socket_syscall.md`：SocketFile、fd 映射、syscall errno 边界。
+- `loopback_poll.md`：显式 loopback 和 poll/select 唤醒。
+- `testing.md`：验证矩阵和常见排查。
+- `network_implementation_guide.md`：维护指南。

document/net/architecture.md

@@ -0,0 +1,34 @@
+# 网络架构
+
+## 目标模型
+
+```text
+device/net NetDevice
+        |
+        v
+net::register_net_device()
+        |
+        v
+NetworkInterface registry
+        |
+        v
+NetworkStack runtime
+        |
+        v
+SocketFile / syscall ABI
+```
+
+依赖方向只能自上而下或通过明确门面调用。设备层不理解 socket，syscall 层不理解 smoltcp 的内部 socket set。
+
+## 当前边界
+
+- `NetworkStack` 是协议栈状态宿主，持有 smoltcp socket set、active interface runtime、loopback link，并提供 TCP/UDP/socket 文件级 API。
+- `NetworkInterface` 是控制面接口对象，保存名称、MAC、IP 地址、网关和兼容中断状态。
+- `SocketFile` 是 VFS 文件对象，保存 fd 相关逻辑状态，如 local/remote endpoint、flags、shutdown 状态、UDP per-fd 接收队列。
+- `kernel::syscall::network` 只负责用户参数、fd table、sockaddr 编解码和 errno。
+
+## 兼容点
+
+- 当前仍是单 active smoltcp runtime，多接口 runtime 需要后续引入真正的 `StackSocketId` 和接口路由。
+- `SocketHandle` 仍包装 smoltcp handle，作为旧路径兼容类型。
+- `NetworkInterface::create_smoltcp_interface()` 暂时保留为 runtime 初始化工厂。

document/net/device_and_interface.md

@@ -0,0 +1,43 @@
+# 设备与接口
+
+## 设备层
+
+`os/src/device/net/` 只负责网卡数据面：
+
+- `net_device.rs` 定义 `NetDevice`、`NetDeviceError` 和 VirtIO net 设备实现。
+- `virtio_net.rs` 初始化 VirtIO net 设备，并调用网络子系统注册入口。
+- `loopback.rs` 提供显式 loopback 设备。
+- `null_net.rs` 仅作为空设备/占位实现，不表示 loopback。
+
+设备层不得直接依赖 IP、网关、socket、syscall 或 smoltcp socket set。
+
+## 注册路径
+
+真实网卡初始化后调用：
+
+```rust
+crate::net::register_net_device(device)
+```
+
+该入口负责：
+
+- 注册底层 `NetDevice`。
+- 创建 `NetworkInterface`。
+- 把接口加入 `NETWORK_INTERFACE_MANAGER`。
+- 通过 `NetDriverHandle` 注册中断兼容桥。
+
+## 接口层
+
+`NetworkInterface` 保存控制面状态：
+
+- interface name，如 `eth0`、`lo`。
+- MAC address。
+- IP CIDR 列表。
+- IPv4 gateway。
+- 兼容中断开关和最后中断时间。
+
+`NetworkInterface` 不应直接实现 `Driver`。中断体系仍需要 `Driver` 时，使用 `NetDriverHandle`。
+
+## Loopback
+
+默认网络初始化会确保 `lo` 存在。无真实 NIC 时，`lo` 作为 active runtime 接口，配置 `127.0.0.1/8` 且不配置默认网关。

document/net/loopback_poll.md

@@ -0,0 +1,23 @@
+# Loopback 与 poll
+
+## Loopback 模型
+
+`lo` 是显式接口，不再由 `NullNetDevice` 隐式承担。无真实 NIC 时，默认配置创建 `LoopbackNetDevice`，接口名为 `lo`，地址为 `127.0.0.1/8`。
+
+当前仍是单 active smoltcp runtime，因此有真实 NIC 时，127/8 frame 通过 `net::stack` 内部 loopback link 消费；后续多 runtime 可以把 `lo` 升级为独立 smoltcp interface。
+
+## Poll 模型
+
+协议栈推进集中在 `NetworkStack::poll()`：
+
+- smoltcp poll。
+- loopback link bounded drain。
+- UDP per-port dispatch 到 per-fd queue。
+- TCP pending close reaping。
+- poll/select waiter wakeup。
+
+`poll_until_empty()` 仅作为 loopback/netperf 兼容包装保留，不应成为新的主路径。
+
+## 中断协作
+
+网络中断兼容桥只记录事件和唤醒 waiter，不直接维护另一份协议栈状态。需要处理收包时，由进程上下文中的 poll/read/write/connect 等路径推进 `NetworkStack`。