Vole/docs/acceptance.md

验收边界

只报告实际执行的检查。结果记录在对应 CI、PR 或 benchmark 运行中，本文维护验证范围。

兼容验收遵循 Mihomo 兼容原则：验证与 Mihomo listener 和官方协议 server 的互通，性能优化综合评估吞吐、CPU、内存和丢包率的收益与代价。字段对照用于记录支持范围与差异，不要求逐字段行为相等。性能达标须依据当次明确的内存预算、目标负载及实测结果判断，不能仅凭连接成功或配置解析通过。

层次	验证内容
离线 / 纯内存	配置、协议编解码、取消、生命周期、内存与 FFI 所有权
平台编译	各目标构建、CLI 基本运行、库文件和发布归档
原生消费者	C/Swift/JNI 等真实宿主的加载、调用与资源释放
容器互通	Mihomo listener 与官方协议 server、真实双向流量、认证、支持模式的 UDP 与关闭行为
压力	实际吞吐、CPU、内存峰值、丢包、DNS 完成数及退出清理
设备 / 发布	真机 TUN、物理出口、权限、生命周期、签名安装及商店要求

协议互通先验证握手、认证、双向数据、关闭与资源清理。吞吐、CPU、内存和丢包率独立记录， 不以压力阈值判定互通失败；全部互通完成后，再单独进行压力验收与性能优化。

编译不替代原生消费者或设备验证；模拟器、Wintun 与 UWP 分别验收。 Linux RSS 不等于 Apple Network Extension physical footprint。 性能结果须同时给出输入、目标负载和实际负载，保留失败与丢包情况。

性能采纳标准

所有平台与构建使用统一的内存策略和 benchmark 预算，内存统一使用 MiB：

• 1 Gbps：≤43 MiB（45,088,768 bytes）。
• 2 Gbps：≤45 MiB（47,185,920 bytes）。

每档使用单一内存门槛，不再区分硬上限与优化目标。

内存策略不按平台或编译模式切换，CLI 与 FFI 共用同一实现。

真实 iOS/tvOS VPN 扩展仍以整个 Network Extension 进程的 physical footprint 验收， 包含 Core、宿主桥接与扩展运行时。 上述数值是项目按负载划分的验收预算，不声明为各设备的系统限额，也不能只计算 Rust heap。 Linux 压力使用 RSS；Linux 结果只作优化筛选，不替代真机扩展验收。 其他平台记录承载 Core 的整个后台进程及实际指标口径，排除独立负载客户端和原站。 不同平台和测量指标的数值不直接混合排名。

定速压力使用既有 Linux 原生 TUN 环境。冷启动、配置和 GeoData 更新、负载、收尾及 Stop 都应覆盖；未执行的生命周期场景单独标明，不从一次压力结果推导。 测试执行完成不代表达到验收门槛。

性能对照使用相同输入、负载和重复次数的普通 Release 构建，分别比较吞吐/QPS 中位数 与同平台进程内存峰值。Linux 保留原压力负载和 RSS 观察逻辑，覆盖 exec 至退出/reap， 包括启动、负载、drain 和 Stop；heaptrack 等仪器开销、tracked heap 和 wait4 读数 不能替代这一验收口径。

• 整体验收必须满足对应负载的内存门槛，协议数据正确性、取消与资源清理必须保持；不能用吞吐或丢包改善抵消内存超限。
• 吞吐、CPU、内存和丢包率都允许渐进式改进，不要求一次修改达到全部目标、各项同步改善或单项绝对不退步，不设单次改善幅度下限。不固定指标优化顺序，按实测瓶颈和综合收益选择下一步。
• 允许指标之间的合理取舍，结合改善幅度、代价、实际完成量和运行间波动评估；综合收益为正的阶段性改进可以采纳。减少实际负载或业务未完成导致的 CPU、内存下降不能算作优化收益。
• 当前组合和所有受影响组合均需完成相同输入、负载下的回归，不能只凭目标组合的结果采纳。涉及内存增长时仍须满足对应内存门槛；降低内存但尚未达标的阶段性改进也可采纳，超限 FAIL 保留。采纳改进与整体验收分别判断，未达标项不改签为通过。
• Linux 压力与横向对比均覆盖纯 TCP、纯 UDP、混合 TCP/UDP 三种业务；每种业务独立记录与验收。不支持 UDP 的协议只验收纯 TCP，其他口径明确标记不适用。
• Linux 定速压力在 1 Gbps 下内存须 ≤43 MiB。性能不设独立的绝对容量轴，以实际吞吐 ≥950 Mbps、适用的 UDP 交付丢包率 ≤1% 作为默认参考，满足即性能通过，不再专项优化。完整性和测量独立验收：纯 TCP 要求已发送业务字节与接收字节、校验和一致，无超时、断流或未完成流；TCP 重传独立记录。期限内交付缺口不能单独归因为永久丢失或 Core 缺陷，须先区分 Core、对端与测试工具。
• 性能对照客户端固定为 Vole 和 Mihomo。1 Gbps 未达到默认性能参考时，补测同协议组合、服务端、流量类型、输入和负载的 Mihomo；逐指标采用较容易达到的标准，达到后也认为性能通过，不再专项优化。Mihomo 与 Mihomo listener 或官方服务端存在兼容问题时，照常统计并比较吞吐、CPU、内存和丢包率，兼容问题及内容错误独立记录。官方客户端仅作源码技术参考，不作为测试对照客户端。
• 吞吐按实际写入和读到的字节统计，包含错误内容及错误返回前的部分 I/O；内容校验失败只记录首错和累计错误，继续压力收发。数据正确性与吞吐计数分开，错误数据不计为完整、正确交付。对照须保留匹配输入、真实 TUN、实际负载窗口、进程观测、正常 Stop/join 及清理证据；缺测明确记录，不伪造数值。初期逐指标参考为吞吐下限 min(950 Mbps, Mihomo 实测吞吐)、UDP 丢包率上限 max(1%, Mihomo 实测丢包率)；CPU 继续记录。Vole 内存仍须 ≤43 MiB，自身数据正确性、TCP 完整交付、实际窗口、DNS 与正常退出清理要求保持；不能用性能通过豁免这些门禁。旧复合负载标记包含此前吞吐目标时，不将其 false 当作实际窗口无效；使用实际活动窗和收发计数判断。历史 FAIL/ERROR、兼容问题与实际身份保留，不追溯改签。
• 每个精确协议组合、流量类型和负载窗口优先争取达到或优于匹配 Mihomo，独立生产候选的优化尝试最多20轮。达到适用参考即停止该项性能优化；同一候选的重复、原版对照、纯观测及仅编译／内存测试不重复计轮。经多轮仍不能达到目标时，可记录结论提前结束；20轮是上限，不要求为凑数做满。
• 结束上述优化阶段后，允许与匹配 Mihomo 最高相对10%差距：吞吐下限为 min(950 Mbps, 0.9 × Mihomo 实测吞吐)，UDP丢包率上限为 max(1%, min(100%, 1.1 × Mihomo 实测丢包率))。这是相对比例，不是增加10个百分点；Mihomo丢包率为0时仍沿用1%较容易参考。必须保留独立候选及真实TUN结果的轮次证据、结束原因、严格结果与降级阶段；没有适用证据不自动放宽。内存、数据／来源、TCP完整交付、实际窗口、DNS、测量与Stop／清理门槛不放宽，历史FAIL／ERROR不重写。
• 2 Gbps 用于内存过载验收，内存须 ≤45 MiB；吞吐、CPU 和丢包率只记录，不设吞吐及丢包门槛。允许通过掐连接、丢包、断连和限制队列大小等方式保护内存。仍须完成真实 TUN 的完整压力窗口，并验证已接收内容、源地址、观测有效性和退出清理；提前结束或没有实际流量不能代替压力验收。
• UDP 交付丢包率以实际发送与唯一有效接收的数据报数计算，按上下行发送包数加权汇总，同时保留两个方向的独立计数和含错误、重复数据的原始收包数。丢包在固定收尾后统计；吞吐仅统计活动窗口，不把漏发算作丢包。iOS/tvOS 吞吐负载根据真机与链路能力校准，内存预算保持一致。

当前默认压力档位仅 1 Gbps，2 Gbps 后续单独验证。完整性、性能参考、内存、实际完成量、负载窗口、CPU、UDP loss、DNS 完成数、测量有效性及退出/join/资源清理分别记录。2 Gbps 下的超时、丢包、断连和未完成量保留原始状态，不因允许过载保护而改签为完整交付；Vole 自身的错误内容或源地址仍使验收失败。测量成功不等于业务成功，编译、配置解析或连接成功不代替压力验收。显式安排的 3 Gbps 专项沿用 ≤45 MiB 的内存过载标准；历史结果保留当时语义，不追溯改签。

过载保护应遵循运行时资源策略的资源所有权、局部容量、取消和同步 Stop 边界。

核心测试入口见 tests，平台与发布入口见 scripts。 网络互通和压力由独立容器测试工具执行，结果与结论统一保存在 benchmark 工程， 遵守 测试隔离。设备要求见 TUN 平台层 与 Windows VPN。