docs: rewrite README and AGENTS.md etc..

docs/design/architecture.md

@@ -2,11 +2,13 @@
 
 ## 1. 目标与定位
 
-一个**只关注网络层**的线路质量面板：单体面板（Backend）+ 轻量节点（Probe、Agent）+ 长连接 RPC + 任务下发。核心能力：
+只关注网络层的线路质量面板：单体面板（Backend）、轻量节点（Probe、Agent）、长连接 RPC 与任务下发。
 
-- 在**若干 Probe**（家宽等需要观测的出口，可以有多个）与**多台海外 VPS Agent**（10 几台）之间，采集**最原始的逐包、逐事件数据**；哪些 Probe 连哪些 Agent 由面板决定（自动全连，也可以手动选择）；
-- 由 Backend 的分析层推算：**如果在某条线路上部署 REALITY 类、Hysteria2 类或 Minecraft 服务，体验会怎样**，并对多条线路排序和对比；
-- **主机层信息只上报只读的汇总数字**（2026-10 起，由用户确认放开）：Agent 和 Probe 读 `/proc` 得到 CPU 占用、内存、根分区、网卡累计流量与瞬时网速、运行时长，不采集 CPU 型号、主机名、网卡名和任何 IP，不采集进程；Probe 的上报可以在 `probe.json` 里关掉（`reporting.host_stats: false`）。展示页用卡片画出每个 Agent 和 Probe 的主机状态，线路单独放在卡片下面的面板里。节点只在连接面板时自报粗粒度的系统、架构和构建信息（版本、tag、提交、构建时间），用于展示和更新；国家和运营商由 Backend 用节点的来源地址查询，节点自己不访问任何外部服务。展示页看不到任何 IP。Agent 和 Probe 仍然是**纯采集器**，不具备 SSH、远程执行、终端、文件读写、自更新等能力：更新由节点宿主机上的更新器完成，节点进程只往数据目录放面板转来的发布清单和更新请求。
+- 采集：多个 Probe（家宽等需要观测的出口）与多台海外 VPS Agent 之间记录逐包、逐事件的原始数据。哪些 Probe 连哪些 Agent 由面板决定，默认全连，也可以手动选择。
+- 分析：Backend 的分析层推算在某条线路上部署 REALITY 类、Hysteria2 类或 Minecraft 服务的体验，并对多条线路排序和对比。
+- 主机状态：Agent 和 Probe 读取 `/proc`，上报 CPU 占用、内存、根分区、网卡累计流量与瞬时网速、运行时长这类汇总数字。不采集 CPU 型号、主机名、网卡名、IP 和进程。Probe 的上报可在 `probe.json` 中用 `reporting.host_stats: false` 关闭。展示页以卡片呈现每个节点的主机状态，线路在卡片下方的面板中。
+- 构建信息：节点连接面板时自报系统、架构和构建信息（版本、tag、提交、构建时间），用于展示和更新。国家和运营商由 Backend 依据节点来源地址查询，节点不访问任何外部服务，展示页不含任何 IP。
+- 节点边界：Agent 和 Probe 是纯采集器，没有 SSH、远程执行、终端、文件读写和自更新。更新由节点宿主机上的更新器完成，节点进程只把面板转来的发布清单和更新请求写入数据目录。
 
 ## 2. 拓扑
 
@@ -34,8 +36,8 @@
    更新（Agent、Probe、Backend）：面板登记 CI 签名的清单 → 管理端确认 → 节点（Backend 先备份数据库）有序退出 → systemd Pull=always 拉最新镜像重启
 ```
 
-- **线路（line）** = 一对（Probe，Agent）。可以有多个 Probe（身份由 Probe 自己生成并用加入令牌注册，可以吊销、删除），每个 Probe 连接多个 Agent，每个 Agent 同时服务多个 Probe；一条线路的数据按 `line:<probe_id>` 单独存放，互不混合。对外的线路 id 是 `<agent_id>~<probe_id>`。
-- **目标任务（target）** = 某个 Agent → 指定的 IP:端口（ICMP、TCP/TLS 建连），只能访问 Agent 本地允许的网段。
+- 线路（line）：一对（Probe，Agent）。可以有多个 Probe（身份由 Probe 自己生成并用加入令牌注册，可以吊销、删除），每个 Probe 连接多个 Agent，每个 Agent 同时服务多个 Probe；一条线路的数据按 `line:<probe_id>` 单独存放，互不混合。对外的线路 id 是 `<agent_id>~<probe_id>`。
+- 目标任务（target）：某个 Agent → 指定的 IP:端口（ICMP、TCP/TLS 建连），只能访问 Agent 本地允许的网段。
 
 ## 3. 数据链路
 
@@ -58,9 +60,9 @@
 
 | 主题 | 要点 | 文档 |
 | --- | --- | --- |
-| 节点框架 | 注册、身份、连接、RPC、可靠上报、状态同步、宿主都由与业务无关的 **Fleet** 提供；MoShiro 只写业务，其他产品也能复用 | [../backend/fleet/README.md](../../backend/fleet/README.md) |
+| 节点框架 | 注册、身份、连接、RPC、可靠上报、状态同步、宿主都由与业务无关的 Fleet 提供；MoShiro 只写业务，其他产品也能复用 | [Fleet 文档](../../backend/fleet/README.md) |
 | 注册与身份 | 使用 `fleet-enroll` 和加入令牌自动注册，之后用签名认证；Probe 用自己的身份直连面板，Agent 列表由面板下发 | [enrollment.md](../security/enrollment.md) |
-| 更新 | 只接受发布密钥签名的清单，更新策略由节点本地决定，失败自动回滚。CI 对镜像 digest 签名；Backend 和一行脚本装的节点由宿主机上的 `moshiro-update` 验签、按 digest 拉取、失败回滚；Podman Quadlet 装的 Agent、Probe 更简单：节点有序退出，systemd 用 `--pull always` 重新拉最新镜像，节点自己不下载、不验证清单；纯二进制节点的更新是待办（[TODO.md](../../TODO.md)） | [deployment.md](../ops/deployment.md) |
+| 更新 | 只接受发布密钥签名的清单，更新策略由节点本地决定，失败自动回滚。CI 对镜像 digest 签名；Backend 和一行脚本装的节点由宿主机上的 `moshiro-update` 验签、按 digest 拉取、失败回滚；Podman Quadlet 装的 Agent、Probe 更简单：节点有序退出，systemd 用 `--pull always` 重新拉最新镜像，节点自己不下载、不验证清单；纯二进制节点的更新见[路线图](../roadmap.md) | [deployment.md](../ops/deployment.md) |
 | 任务模型 | `Task = {kind, target, params, schedule}`；持续采集、按需测试、目标任务统一建模；下发“期望任务集”，由节点自行调和 | [measurement.md](measurement.md) |
 | 采集扩展 | Kind 由积木组合声明；采集密度靠参数调整；原始块自描述 | [measurement.md](measurement.md) |
 | 统计扩展 | 指标注册制：少数几种累加器 + 统计算子；一行 `MetricDef` 就是一个新指标 | [analysis.md](analysis.md) |
@@ -91,15 +93,15 @@ Backend：不自动，只有管理员点「更新并重启」；退出之前先
 
 ### 4.1 回显的四个时间戳
 
-回显类 Kind 记录 `t1..t4`（Probe 发出、Agent 收到、Agent 回复、Probe 收到）。借此可以扣除 Agent 的处理耗时得到 RTT，可以分别判断上行和下行的丢包，并在去除时钟偏移和漂移后，得到**每个方向各自的抖动**，不需要两端时钟同步。
+回显类 Kind 记录 `t1..t4`，用于扣除 Agent 处理耗时、分别判断上下行丢包和计算各方向的抖动，不要求两端时钟同步。推导见 [measurement.md](measurement.md) 第 3.4 节。
 
 ### 4.2 NAT / CGNAT 适配
 
-所有连接和 UDP 流都由 Probe 发起；Agent 把回复发往请求的**实际源地址**。会话以 `session_id` 和 MAC 认证，不绑定五元组，NAT 映射变化后自动跟随新地址。持续的 UDP 回显本身就起到保活作用。
+所有连接和 UDP 流都由 Probe 发起；Agent 把回复发往请求的实际源地址。会话以 `session_id` 和 MAC 认证，不绑定五元组，NAT 映射变化后自动跟随新地址。持续的 UDP 回显本身就起到保活作用。
 
 ## 5. 安全边界：纯采集
 
-> 这一节是现状。「Backend 被攻破、节点被入侵」之后的威胁模型、现有的几处缺口（例如 Probe 会拨 Backend 给的任意地址、测量数据没有产生者签名）和每项的状态，见 [security.md](../security/security.md)；预握手敲门、Probe 自己生成密钥、操作员集合与服务器身份已经实现。
+> 本节描述现状。Backend 或节点被攻破后的威胁模型、现有缺口（例如 Probe 会拨 Backend 给的任意地址、测量数据没有产生者签名）及状态见 [security.md](../security/security.md)。
 
 ```text
 Agent / Probe 能做的   执行编译在二进制中的 Kind；监听和访问本地配置允许的端口与网段；受本地硬上限约束
@@ -108,15 +110,15 @@ Agent / Probe 能做的   执行编译在二进制中的 Kind；监听和访问
                       也推不出恶意更新（更新清单必须由发布密钥签名，节点宿主机上的更新器用本机公钥验签，并且只认本机配置的镜像仓库）
 ```
 
-- **本地硬上限**写在节点本机的配置文件中，Backend 下发的任务如果超出，节点直接拒绝：允许访问的目标网段（默认为空，即不开放目标任务）、总码率和包速率上限、允许监听的端口。
-- **构建期强制**：常驻节点进程使用 `BannedSymbols.Node.txt`，禁用 `System.Diagnostics.Process`、`Assembly.Load*`、`NativeLibrary.Load`、`HttpClient`，以及 `ConfigStore` 以外的文件写入 API，详见 [project-layout.md](../dev/project-layout.md) 第 7 节。
-- **权限分离**：注册（`fleet-enroll`，一次性运行）、采集（`moshiro-agent` / `moshiro-probe`）、更新是不同的进程。容器节点里，采集进程在容器内以 UID 1654 运行（只读文件系统、不带额外能力），更新由宿主机上 root 运行的 `moshiro-update` 完成：它只读取节点放进 `update/` 的普通文件、复制到自己的临时目录后验签，状态写在节点只读的 `update-status/`；采集进程改写不了自己的二进制，更新器也读不到节点身份私钥。纯二进制节点的更新是待办（见 [TODO.md](../../TODO.md)）。
-- **容器运行**：Agent、Probe 的镜像基于 Alpine（musl，NativeAOT），宿主机用 rootful podman 加 systemd 运行：UID/GID 1654、只读文件系统、`--cap-drop all`、`no-new-privileges`、`/tmp` 用 tmpfs；配置和身份放在挂载的数据目录里。
-- **最小权限运行**：非 root 用户；只在需要时授予 `CAP_NET_RAW`（ICMP）；默认端口都高于 1024，不需要 `CAP_NET_BIND_SERVICE`，只有在 Agent 本地显式开启 443 时才授予。
-- **身份**：节点使用本地生成的 ECDSA P-256 密钥对签名认证（Agent 和 Probe 都自己生成；Probe 有两把独立的密钥，一把连面板、一把连 Agent），Backend 只存公钥，数据库泄露也无法冒充节点。
-- **防放大**：未认证的包静默丢弃；回复长度与请求相等；每个流按声明速率限速；使用重放窗口。
-- **容器里的主机指标**：容器里的 Agent 通过只读挂载宿主机的 `/proc`、`/sys`、根目录和 `/etc/os-release`（环境变量 `HOST_PROC`、`HOST_SYS`、`HOST_ROOT`）读取宿主机的资源占用和系统名；读不到的项返回空值，不会退回去读容器自己的数据。Probe 的 compose 也一样挂载这几项。
-- **自身状态**：节点上报进程内的计数（会话数、包速率、队列、丢弃数）；Agent 另外每隔几秒用 `moshiro.host` 上报一份主机资源占用的汇总数字（可以在 `agent.json` 里用 `reporting.host_stats = false` 整个关掉），最新值实时推给展示页，Backend 每分钟存一个样本（默认保留 7 天，`retention.host_days`）。
+- 本地硬上限写在节点本机的配置文件中，Backend 下发的任务如果超出，节点直接拒绝：允许访问的目标网段（默认为空，即不开放目标任务）、总码率和包速率上限、允许监听的端口。
+- 构建期强制：常驻节点进程使用 `BannedSymbols.Node.txt`，禁用 `System.Diagnostics.Process`、`Assembly.Load*`、`NativeLibrary.Load`、`HttpClient`，以及 `ConfigStore` 以外的文件写入 API，详见 [project-layout.md](../dev/project-layout.md) 第 7 节。
+- 权限分离：注册（`fleet-enroll`，一次性运行）、采集（`moshiro-agent` / `moshiro-probe`）、更新是不同的进程。容器节点里，采集进程在容器内以 UID 1654 运行（只读文件系统、不带额外能力），更新由宿主机上 root 运行的 `moshiro-update` 完成：它只读取节点放进 `update/` 的普通文件、复制到自己的临时目录后验签，状态写在节点只读的 `update-status/`；采集进程改写不了自己的二进制，更新器也读不到节点身份私钥。纯二进制节点的更新见[路线图](../roadmap.md)。
+- 容器运行：Agent、Probe 的镜像基于 Alpine（musl，NativeAOT），宿主机用 rootful podman 加 systemd 运行：UID/GID 1654、只读文件系统、`--cap-drop all`、`no-new-privileges`、`/tmp` 用 tmpfs；配置和身份放在挂载的数据目录里。
+- 最小权限运行：非 root 用户；只在需要时授予 `CAP_NET_RAW`（ICMP）；默认端口都高于 1024，不需要 `CAP_NET_BIND_SERVICE`，只有在 Agent 本地显式开启 443 时才授予。
+- 身份：节点使用本地生成的 ECDSA P-256 密钥对签名认证（Agent 和 Probe 都自己生成；Probe 有两把独立的密钥，一把连面板、一把连 Agent），Backend 只存公钥，数据库泄露也无法冒充节点。
+- 防放大：未认证的包静默丢弃；回复长度与请求相等；每个流按声明速率限速；使用重放窗口。
+- 容器里的主机指标：容器里的 Agent 通过只读挂载宿主机的 `/proc`、`/sys`、根目录和 `/etc/os-release`（环境变量 `HOST_PROC`、`HOST_SYS`、`HOST_ROOT`）读取宿主机的资源占用和系统名；读不到的项返回空值，不会退回去读容器自己的数据。Probe 的 compose 也一样挂载这几项。
+- 自身状态：节点上报进程内的计数（会话数、包速率、队列、丢弃数）；Agent 另外每隔几秒用 `moshiro.host` 上报一份主机资源占用的汇总数字（可以在 `agent.json` 里用 `reporting.host_stats = false` 整个关掉），最新值实时推给展示页，Backend 每分钟存一个样本（默认保留 7 天，`retention.host_days`）。
 
 ## 6. 可扩展性目标
 
@@ -142,10 +144,10 @@ Kind 目录编译在二进制中，节点不接受远程下发代码（安全边
 
 | # | 决策 | 理由 |
 | --- | --- | --- |
-| D1 | 只关注网络层；节点是纯采集器，没有远程执行能力 | 由用户确认；防止权限泄露 |
-| D2 | 拓扑为多个 Probe 连接多个 Agent（10+）；线路 = (Probe, Agent)，数据按 Probe 隔离 | 由用户确认 |
+| D1 | 只关注网络层；节点是纯采集器，没有远程执行能力 | 防止权限泄露 |
+| D2 | 拓扑为多个 Probe 连接多个 Agent（10+）；线路 = (Probe, Agent)，数据按 Probe 隔离 | 拓扑需求 |
 | D3 | Agent 用加入令牌自动注册，之后用密钥对签名认证 | 批量部署省事；Backend 不保存可用于冒充节点的秘密 |
-| D4 | Probe 直连 Backend：身份、Agent 列表（期望状态 `probe_agents`）、状态和更新都走这条链路，测量仍然只走 Probe → Agent（2026-10 由「Probe 不认识 Backend、经 Agent 同步列表」改成直连，因为面板本来就要对外暴露，直连让更新和管理少一跳）。哪些 Probe 连哪些 Agent 由面板决定，`fleet.auto_link` 打开时两两连，也可以手动选择，Probe 始终主动拨出 | 新增 Agent 后自动覆盖，不需要改 Probe 配置；Probe 的版本、更新和线路都能在面板上管理 |
+| D4 | Probe 直连 Backend：身份、Agent 列表（期望状态 `probe_agents`）、状态和更新都走这条链路，测量仍然只走 Probe → Agent。哪些 Probe 连哪些 Agent 由面板决定，`fleet.auto_link` 打开时两两连，也可以手动选择，Probe 始终主动拨出 | 新增 Agent 后自动覆盖，不需要改 Probe 配置；Probe 的版本、更新和线路都能在面板上管理 |
 | D5 | 只采集逐包、逐事件的原始数据，解释全部放在 Backend | 模型和指标可以事后重算；采集端最轻 |
 | D6 | 统一的任务模型 + 期望任务集调和 | 新增任务类型时协议不变 |
 | D7 | Kind 由积木组合声明；原始块自描述 | 调整密度或新增采集方法只改一处 |
@@ -155,20 +157,18 @@ Kind 目录编译在二进制中，节点不接受远程下发代码（安全边
 | D11 | API 分为 public / admin / agent 三层；实时数据用 SSE | 前端只读场景足够；反向代理和 CDN 更友好 |
 | D12 | 单仓库，三个独立项目加 Web（展示端、管理端）；契约以 C# 代码为真源 | 改一处，编译期即可发现不一致 |
 | D13 | Probe/Agent 运行时只依赖 BCL；.NET 10 NativeAOT | 轻量 |
-| D14 | 节点机制抽成与业务无关的 Fleet 框架，放在同一仓库的 `backend/fleet/` 目录，暂不独立（由用户确认；不设拆分时间表，需要时再评估；不使用 PublicApiAnalyzers） | 可复用；不引用任何 `MoShiro.*` 的约束由 `ArchitectureTests` 在构建时检查 |
+| D14 | 节点机制抽成与业务无关的 Fleet 框架，放在同一仓库的 `backend/fleet/` 目录，暂不独立（不设拆分时间表，需要时再评估；不使用 PublicApiAnalyzers） | 可复用；不引用任何 `MoShiro.*` 的约束由 `ArchitectureTests` 在构建时检查 |
 | D15 | 注册独立为 `fleet-enroll` 工具；常驻进程不包含注册代码 | 常驻进程去掉 HttpClient，边界更纯 |
-| D16 | 更新与业务进程分离：发布密钥签名、本地策略、健康确认与回滚。已实现：宿主机 `moshiro-update`（Backend、脚本装的节点，清单里是镜像 digest），Quadlet 节点则靠退出后由 systemd 重新拉镜像；纯二进制节点的更新见 [TODO.md](../../TODO.md) | 面板被攻破时也无法推送恶意二进制 |
-| D17 | Probe 支持 OpenWrt：正式支持 `linux-musl-x64`、`linux-musl-arm64`；armv7 视工具链验证结果决定；MIPS 不支持，改为在局域网设备上运行 Probe | 由用户确认；NativeAOT 不支持 MIPS |
-| D18 | 默认测量端口不使用 443：控制 7443/tcp，QUIC Datagram 数据 7443/udp，TCP 数据 7444/tcp；443 只在 Agent 本地显式开启时才允许使用 | 由用户确认；避免与 VPS 上的真实服务冲突；结果会记录实际端口 |
-| D19 | 展示查询最细 1s：最近 1 小时来自内存热层，更早的数据来自 10s/1m/5m/1h 各层，现场合并；时间段内的汇总由累加器精确合并得出 | 由用户确认；5 分钟、15 分钟这类视图足够精细且快 |
-| D20 | 时序响应采用列式格式（`t[]` + `values{}`，时间轴使用 Unix 毫秒） | 由用户确认；体积小，可以直接交给图表库 |
+| D16 | 更新与业务进程分离：发布密钥签名、本地策略、健康确认与回滚。已实现：宿主机 `moshiro-update`（Backend、脚本装的节点，清单里是镜像 digest），Quadlet 节点则靠退出后由 systemd 重新拉镜像；纯二进制节点的更新见[路线图](../roadmap.md) | 面板被攻破时也无法推送恶意二进制 |
+| D17 | Probe 支持 OpenWrt：正式支持 `linux-musl-x64`、`linux-musl-arm64`；armv7 视工具链验证结果决定；MIPS 不支持，改为在局域网设备上运行 Probe | NativeAOT 不支持 MIPS |
+| D18 | 默认测量端口不使用 443：控制 7443/tcp，QUIC Datagram 数据 7443/udp，TCP 数据 7444/tcp；443 只在 Agent 本地显式开启时才允许使用 | 避免与 VPS 上的真实服务冲突；结果会记录实际端口 |
+| D19 | 展示查询最细 1s：最近 1 小时来自内存热层，更早的数据来自 10s/1m/5m/1h 各层，现场合并；时间段内的汇总由累加器精确合并得出 | 5 分钟、15 分钟这类视图足够精细且快 |
+| D20 | 时序响应采用列式格式（`t[]` + `values{}`，时间轴使用 Unix 毫秒） | 体积小，可以直接交给图表库 |
 | D21 | 国家和运营商只由 Backend 向 IP 归属服务查询（缺省 `https://ip.007995.xyz`，可关闭），只查公网地址；节点不访问任何外部服务；公开接口不返回 IP、城市、ASN | 客户的防火墙常常要审计节点的出站连接；访客拿不到敏感信息（有测试保证） |
 | D22 | 构建信息（版本、tag、提交、构建时间）由节点自报，访客是否可见由设置 `site.show_build` 控制（默认关）；提交号只在管理端 | 展示页可以选择不暴露版本；管理员能看出哪个节点没升级 |
-| D23 | 零信任方向：信任锚点从 Backend 移到操作员 passkey（操作员集合，节点安装时固定创世指纹和属主）；Probe 自己生成密钥；Agent 的 TCP 端口预握手敲门；敏感能力以后放进独立 extension，用属主 passkey 签名的能力令牌授权。不做进程沙箱（节点是 1 核 1 GB 的小机器），代码风险靠 PR 评审 | 由用户确认；做法和各缺口的状态见 [security.md](../security/security.md)、[access.md](../security/access.md) |
+| D23 | 零信任方向：信任锚点从 Backend 移到操作员 passkey（操作员集合，节点安装时固定创世指纹和属主）；Probe 自己生成密钥；Agent 的 TCP 端口预握手敲门；敏感能力以后放进独立 extension，用属主 passkey 签名的能力令牌授权。不做进程沙箱（节点是 1 核 1 GB 的小机器），代码风险靠 PR 评审 | 做法和各缺口的状态见 [security.md](../security/security.md)、[access.md](../security/access.md) |
 
-## 9. 仍待确认
+## 9. 未决事项
 
-待确认事项：
-
-1. **告警**：首版不包含，是否需要预留 Webhook？
-2. **与真实服务共用 443**（例如 SNI 分流）：首版不做，默认使用非 443 端口；以后如有需要再评估。
+- 告警：首版不包含，是否预留 Webhook 见[路线图](../roadmap.md)。
+- 与真实服务共用 443（例如 SNI 分流）：默认使用非 443 端口，需要时再评估。