Kernel Design

WutherCore 内核设计

适用版本：0.3.1-rc.1
文档状态：随代码演进，更新于 2026-07-22
目标读者：准备理解、集成或扩展 WutherCore 的开发者

WutherCore 是一个可组合的跨平台 Rust 代理内核。它把配置、入站、解析、路由、策略选择、出站协议、透明接管、管理 API、观测和持久化拆成独立 crate，再由 wuther-core 统一装配成可运行进程。

本文解释“系统为什么这样设计、一次流量如何穿过内核、各模块如何协作”。它不是字段字典，也不承诺所有第三方协议组合都已验证。使用配置时请查阅配置指南，确认实际能力时请查阅功能矩阵。代码与测试始终是最终事实来源。

1. 阅读路线

不同读者不需要从头读到尾：

你想解决的问题	建议章节
快速建立系统心智模型	系统全景、一次连接如何通过内核
修改 YAML 或默认值	配置编译
新增协议或传输层	出站与传输、扩展指南
修改路由、规则集或进程匹配	路由与规则集
排查 DNS、Fake IP 或流量回环	解析系统、安全与失败语义
维护 TUN、TPROXY、REDIRECT	透明接管
集成 Dashboard 或宿主应用	管理 API、平台边界
理解启动、停止和资源所有权	进程生命周期

2. 系统全景

WutherCore 的核心不是某个协议，而是一条稳定的连接处理流水线：

flowchart LR
    Config["YAML 配置"] --> Compiler["core-config\nProfile + 校验 + 编译"]
    Compiler --> Plan["RuntimePlan"]

    App["应用或设备流量"] --> Inbound["core-inbound / core-capture"]
    Inbound --> Runtime["core-runtime"]
    Runtime --> Resolver["core-resolver"]
    Runtime --> Route["core-route + core-ruleset"]
    Runtime --> Select["GroupSelector + core-smart"]
    Select --> Outbound["core-outbound + core-reality"]
    Outbound --> Network["目标网络"]

    Feeds["core-feeds"] -.热更新节点.-> Runtime
    Store["core-store"] <--> Runtime
    Runtime --> Observe["core-observe"]
    API["core-api"] <--> Runtime
    Mesh["core-mesh"] -.仲裁宿主资源.-> Inbound

这条流水线围绕三个稳定对象展开：

RuntimePlan：配置编译后的只读运行计划。
InboundMetadata / FlowContext：一次流量的规范化上下文。
RouteDecision + OutboundAdapter：选路结果与统一出站接口。

模块可以扩展，但这三层契约应保持清晰。配置模型不应直接渗入协议握手，平台命令不应进入路由引擎，管理 API 也不应绕过 Runtime 修改内部状态。

3. 设计目标与边界

3.1 设计目标

可解释配置：用户 YAML 先补全默认值、校验引用，再编译为 RuntimePlan；check 和 explain 能在启动前暴露结果。
模块可替换：DNS、路由、规则集、选择器、出站和 Capture 都有明确边界。
跨平台但不掩盖差异：普通代理路径尽量一致；系统路由、虚拟网卡和进程识别留在平台模块中。
失败时状态明确：未知分组、未加载订阅、缺失 UDP 能力等情况优先阻断，不静默回退到 DIRECT。
可观察、可恢复：连接、流量、选择理由和错误可通过日志/API 获取；系统网络修改必须有清理路径。
嵌入友好：内核 crate 可以被 CLI、Android 宿主或未来其他前端复用。

3.2 非目标

仓库不提供桌面、Web 或移动端 GUI。
不把 Mihomo/Clash 的所有内部结构复制为本项目架构。
不承诺任意协议与任意传输层都能自由组合。
不代替宿主系统完成 Android 权限申请、VpnService 生命周期或应用界面。
不以“兼容接口”为理由暴露密钥、内部资源标识或不安全热切换能力。

3.3 核心不变量

以下规则比单个实现细节更重要：

用户配置必须先编译成功，Runtime 不消费半校验的 YAML。
Capture 创建的路由、防火墙、接口和 fwmark 必须由同一生命周期释放。
代理节点域名、订阅和规则集拉取不能被再次捕获形成自循环。
DNS Hijack、独立 DNS listener 和 Runtime 必须共享同一解析状态。
订阅尚未加载或路由引用失效时，不允许无声直连。
API 的公开模型不能泄露凭据、命令环境或宿主私有协调键。

4. 配置编译：从用户意图到 RuntimePlan

core-config 把面向用户的 version: 1 YAML 转换为稳定的运行时输入：

flowchart LR
    Text["YAML 文本"] --> Parse["serde_yaml -> UserConfig"]
    Parse --> Version["版本检查"]
    Version --> Defaults["应用 Profile 默认值"]
    Defaults --> Normalize["短写法、节点 URI、兼容规则集归一化"]
    Normalize --> Validate["引用、平台、监听与安全校验"]
    Validate --> Compile["编译 groups / route / listen"]
    Compile --> Plan["RuntimePlan"]

入口位于 core_config::load_from_str 和 load_from_path。当前只接受配置版本 1，流程固定为：反序列化、版本检查、Profile 默认值、编译与交叉校验。

RuntimePlan 包含：

已解析的 Mixed/API 监听地址；
标准化后的订阅、节点和策略组；
已展开的路由步骤与规则集声明；
Resolver、Capture、Smart、UI 和 Mesh 配置；
进程识别模式与日志配置。

4.1 为什么需要编译层

如果每个运行时模块都直接解释 YAML，会出现不同默认值、不同错误语义和热路径分支。编译层让复杂度集中在启动前：

字符串节点 URI 在进入 Runtime 前变成 ParsedNode；
route.preset 在进入 RouteEngine 前展开；
策略组引用在启动前确认；
listen.share 和监听地址共同决定是否需要 API 密钥；
不支持的平台 Capture 组合在修改系统状态前被拒绝。

4.2 Profile 的职责

desktop、router、server 和 mobile 只提供默认值，不是四套独立运行时。用户显式字段覆盖 Profile，最终行为以 wuther-core explain 输出为准。

wuther-core check config.yaml
wuther-core explain config.yaml
wuther-core run -c config.yaml

完整字段与示例见配置指南和 examples/。

5. 进程生命周期

顶层装配位于 crates/wuther-core/src/main.rs 的 cmd_run。构造顺序刻意安排，避免监听器抢跑或宿主资源冲突：

sequenceDiagram
    participant CLI as wuther-core
    participant Mesh as MeshSupervisor
    participant Runtime as Runtime
    participant Manager as Feed/Ruleset/URLTest
    participant Capture as CaptureSupervisor
    participant Listener as DNS/Mixed/API

    CLI->>CLI: 加载 RuntimePlan，初始化 tracing/watchdog
    CLI->>Mesh: 声明端口、路由、接口和防火墙资源
    Mesh-->>CLI: preflight + 初始快照
    CLI->>Runtime: 构造 Store、RulesetIndex 与 Runtime
    CLI->>Manager: 启动规则集、订阅与周期探测
    CLI->>Capture: 事务化启动透明接管（可选）
    CLI->>Listener: 启动 DNS、Mixed 和 API
    Listener-->>CLI: 等待 Ctrl-C 或 Mesh fail-stop
    CLI->>Capture: 停止并恢复系统状态
    CLI->>Mesh: 逆序释放宿主资源
    CLI->>Runtime: 停止后台任务并落盘

5.1 启动阶段

加载配置并初始化日志。
安装独立 watchdog；Tokio 心跳停止时写入诊断文件。
执行权限和 Capture/Mesh 诊断。
让 MeshSupervisor 先检查固定监听端口与宿主网络资源冲突。
打开 redb Store；失败时记录告警并以内存模式继续。
创建共享 RulesetIndex，再构造 Runtime。
启动规则集管理器、URLTest、连接摘要和订阅管理器。
按配置启动 Capture；涉及自动路由、TPROXY 或 REDIRECT 时采用 fail-closed。
最后启动独立 DNS、Mixed 入站与 API。

5.2 停止阶段

停止顺序优先恢复宿主网络：Capture → Mesh → Feeds → Runtime → listener tasks。即便普通监听可以继续工作，Capture 清理失败也不能被当作普通告警忽略，因为系统路由或防火墙可能仍处于修改状态。

6. 一次连接如何通过内核

6.1 统一入站上下文

Mixed、TUN、TPROXY 和 REDIRECT 的协议细节不同，但进入 Runtime 前都转换为 InboundMetadata。它描述：

TCP 或 UDP；
源地址与目标地址；
原始域名、Fake IP 反查域名或嗅探域名；
可选进程名、进程路径和 L7 协议；
入站地址、DNS 模式和强制直连原因。

InboundMetadata::flow_context() 生成 FlowContext，由 ListenerHandler 统一调用 Runtime。这样 Capture 不需要复制路由、选择和连接记账逻辑。

6.2 TCP 数据路径

sequenceDiagram
    participant App as 应用
    participant In as Mixed/Capture
    participant Handler as ListenerHandler
    participant DNS as Resolver
    participant Route as RouteEngine
    participant Group as GroupSelector
    participant Out as OutboundAdapter
    participant Obs as Observe

    App->>In: TCP 流量
    In->>Handler: InboundMetadata
    Handler->>DNS: 解析或 Fake IP 反查（按需）
    Handler->>Route: FlowContext
    Route-->>Handler: Direct / Block / Group
    Handler->>Group: 在组内选择可用节点
    Group-->>Handler: 节点与选择理由
    Handler->>Out: dial_tcp(DialContext)
    Handler->>Obs: 打开连接记录
    Out-->>App: 双向转发并累计流量

Runtime 的选路顺序还受 API 可调模式影响：

mode=direct：强制 DIRECT。
mode=global：强制使用 route.final。
mode=rule：交给 RouteEngine 按编译顺序匹配。

如果决策指向不存在的分组、订阅节点尚未加载、节点未注册或组内没有候选，Runtime 返回 BLOCK。这是防泄漏策略，不是普通降级。

6.3 UDP 数据路径

UDP 没有单一长连接字节流。Capture 或 SOCKS5 UDP 把数据报与五元组交给 Runtime，Runtime 只从声明 UDP 能力的出站中选择，并由会话表维护回包路径、超时和 NAT 状态。若组内没有 UDP 能力节点，拨号返回 Unsupported，不会把 UDP 偷偷改成 TCP 或直连。

7. Workspace 与 crate 边界

Crate	主要职责	不应承担
`wuther-core`	CLI、启动顺序、组件装配和退出	协议握手与匹配算法
`core-config`	YAML 模型、Profile、迁移、校验、`RuntimePlan`	网络 I/O
`core-inbound`	Mixed、HTTP/SOCKS5、REALITY/VLESS 入站与权限探测	节点选择
`core-runtime`	连接编排、组选择、健康检查、连接桥接	平台命令拼装
`core-route`	`FlowContext`、规则执行、嗅探结果匹配	规则集下载
`core-ruleset`	外部规则集解析、编译、索引和刷新	最终出站拨号
`core-resolver`	DNS、缓存、Fake IP、Hosts、策略和独立服务	通用代理路由
`core-outbound`	统一出站接口、协议、传输与 socket 保护	顶层配置加载
`core-reality`	REALITY 客户端/服务端传输与伪装回落	内层代理协议
`core-capture`	TUN、TPROXY、REDIRECT、平台路由与防火墙	协议握手
`core-feeds`	订阅拉取、解析、过滤、缓存和热更新	路由决策
`core-fetch`	避开自捕获的受控 HTTP/1.1 拉取	通用浏览器 HTTP 客户端
`core-smart`	可解释的节点评分、学习、Pin/Avoid	节点协议实现
`core-api`	原生 `/v1` 与兼容接口、鉴权和服务保护	直接操作系统网络
`core-observe`	日志、指标、连接表、流量与 watchdog	业务选路
`core-store`	redb 持久化与异步批量写入	业务策略
`core-process`	跨平台进程反查与短期缓存	路由规则本身
`core-mesh`	网络后端抽象、资源仲裁和生命周期监督	具体 GUI 或控制面

依赖关系不是传统的严格分层。core-runtime 是组合中心，core-capture 与 core-outbound 也需要共享 Resolver、RulesetIndex 和 socket 保护状态。新增跨 crate 依赖时，应先回答：它是配置编译、运行时编排、协议细节还是平台资源所有权？

8. 关键运行时契约

8.1 RuntimePlan

RuntimePlan 是配置层与运行时层之间的边界。新增用户字段通常需要经历：

model::UserConfig → Profile 默认值 → 编译/校验 → RuntimePlan → 消费模块。

不要让消费模块重新猜测用户省略字段的含义。

8.2 FlowContext 与 RouteDecision

FlowContext 只携带匹配所需事实：host、IP、端口、网络类型、进程、规则集元数据和可选 L7 协议。RouteEngine::decide 返回：

RouteDecision::Direct；
RouteDecision::Block；
RouteDecision::Group(name)；
同时返回命中规则类型和原始规则文本，供日志/API 解释。

路由引擎不直接打开 socket，也不决定组内具体节点。

8.3 OutboundAdapter

所有出站通过 OutboundAdapter 暴露统一能力：名称、协议、TCP/UDP 支持和拨号方法。节点协议解析与 Adapter 构造集中在 core-outbound::registry，Runtime 只持有注册表中的 trait object。

出站 socket 在 connect 前应用 protect、fwmark 或物理接口绑定，以避免 TUN/TPROXY 自循环。节点域名通过 Runtime 注入的 Resolver 解析，而不是任由协议实现调用系统 DNS。

8.4 CaptureEngine 与 CaptureSupervisor

平台实现遵循 Capture Engine 契约，CaptureSupervisor 负责：

从配置构造 CapturePlan；
预检查并安装平台状态；
持有 fwmark、路由、接口和防火墙的生命周期；
将捕获到的流量交给 Runtime；
启动失败时回滚，停止时逆序清理。

平台代码可以局部使用 unsafe 调用 ioctl、Wintun 或系统 FFI，但必须限制在审计过的边界并带安全说明。

8.5 NetworkBackend 与 MeshSupervisor

core-mesh 为未来的组网后端定义统一资源声明和生命周期。监督器会检查接口、监听端口、路由、DNS 与防火墙资源冲突，并发布安全快照。

当前公共基础设施已接入宿主资源仲裁和 /v1/mesh/status，但主程序尚未注册具体产品后端。配置中出现 Tailscale 相关模型，不应被理解为所有 LocalAPI、userspace 或 tsnet 产品能力都已完成。

9. 主要子系统

9.1 入站

core-inbound 的 Mixed listener 在同一 TCP 端口识别 HTTP 代理与 SOCKS5，并支持 SOCKS5 UDP ASSOCIATE。透明代理入站由 core-capture 承载，两者最终都使用 ListenerHandler。

REALITY/VLESS 入站是独立协议路径：core-reality 终止已认证的 REALITY TLS 1.3 流，并把未认证探测转发到伪装目标；内层 VLESS 由 core-inbound 处理。REALITY 传输本身不依赖 XHTTP 或具体内层代理协议。

9.2 路由与规则集

core-route 按 RuntimePlan.route.steps 顺序匹配。Matcher 包括域名、后缀、关键字、CIDR、端口/范围、网络、进程、规则集、L7 协议以及 AND/OR 组合。

core-ruleset 负责把外部格式转换为统一的匹配程序。当前代码覆盖 Mihomo YAML/TXT/MRS、sing-box JSON/SRS 与内联规则；无法安全保持语义的字段应在解析或配置编译时显式报错。

同一 RulesetIndex 被 RouteEngine 和 Capture 的地址集查询共享，避免“路由命中一套规则、透明接管使用另一套规则”。

9.3 解析系统与 Fake IP

Resolver 包含：

多上游和 group 策略；
乐观缓存与 singleflight；
Hosts、域名策略和 fallback；
IPv4/IPv6 Fake IP 池；
Fake IP 与真实域名映射；
UDP/TCP 独立 DNS 服务；
代理节点使用的 bootstrap 解析。

DNS Hijack 出站、Capture 和 resolver.listen 共享同一个 DnsService，因此缓存和 Fake IP 映射一致。除非显式选择 system 模式，解析失败不应静默落到系统 DNS。

9.4 策略组与 Smart

RouteEngine 只决定“进入哪个组”；GroupSelector 再执行 manual、load balance、URLTest 或 Smart 选择。选择时会考虑：

手动选择和持久化状态；
URLTest 的存活与延迟；
UDP 能力；
prefer / avoid；
Smart 统计、粘性、Pin 和临时回避。

Smart 当前是可解释的启发式评分与历史学习系统，不是已经训练好的通用机器学习模型。每次选择可以输出候选分数和理由；未来模型只能作为受控扩展，不能绕过能力过滤和失败保护。

9.5 透明接管

Capture 负责把原本不会主动连接代理端口的流量送入内核：

方式	典型平台	核心机制
TUN	Windows、Linux、macOS、Android	虚拟网卡、用户态或系统栈、路由管理
TPROXY	Linux / 部分 Android root	保留原目标地址的透明 socket 与策略路由
REDIRECT	Linux / 部分 Android root	防火墙重定向 TCP，UDP 通常配合其他路径
VpnService FD	Android	宿主创建 VPN，并把文件描述符交给内核

Capture 是系统状态修改器，不只是一个 listener。任何新平台实现都必须覆盖：权限检查、安装、部分失败、停止、重复停止、进程崩溃后的诊断和与其他 VPN 的冲突。

9.6 出站与传输

core-outbound 把节点模型映射为协议 Adapter，并复用 TCP、TLS、WebSocket、HTTP、HTTP/2、gRPC、XHTTP、QUIC 等传输组件。具体协议能否使用某种传输，必须由协议实现和配置校验共同决定。

已实现协议范围以功能矩阵为准。新增协议不能只完成“成功握手”，还需要处理：

TCP 与 UDP 能力声明；
DNS、socket protect、fwmark 和接口绑定；
认证失败、超时、EOF 和取消；
敏感字段日志脱敏；
与服务端版本的可重复互操作测试。

9.7 订阅与拉取

core-feeds 支持订阅格式嗅探、解析、过滤、重命名、去重、磁盘缓存和周期刷新。更新通过 FeedSink 注入 Runtime；Runtime 会替换该 provider 的旧节点，并重建引用 provider 的组，同时保留其他 provider。

core-fetch 是低频订阅/规则集场景的受控 HTTP/1.1 客户端。它在创建 socket 时应用物理接口绑定和保护，支持 HTTPS、重定向、超时、gzip/br 与响应体上限，从而避免透明代理自循环和解压炸弹。

9.8 管理 API

core-api 同时提供原生 /v1 与常用 Clash/Mihomo 兼容接口。API 通过 Runtime、CaptureSupervisor、MeshSupervisor 和 FeedManager 的受控方法读取或修改状态，不直接拼装平台命令。

重要安全约束：

非 loopback 监听必须配置 ui.secret；
普通请求使用 Bearer 或 x-api-secret；
query token 仅用于浏览器受限的 WebSocket/SSE；
CORS、限流、请求体上限、超时和安全响应头在服务层统一处理；
无法安全热切换的 allow-lan / tun.enable 返回 501，不伪装成功。

端点列表与鉴权方式见管理 API。

9.9 观测与持久化

core-observe 提供 tracing、LogBus、原子指标、连接表、带流量统计的双向 copy 和独立 watchdog。日志热路径避免同步磁盘写入；连接表通过 guard 管理打开、累计和关闭。

core-store 使用 redb 保存 Smart 节点统计、域名最佳节点、失败冷却、Pin、手动组选择和订阅元数据。写入可以经异步 writer 合并，Store 不可用时 Runtime 明确降级为内存模式。

9.10 进程识别

core-process 根据平台从 TCP/UDP 连接反查进程信息，并用短 TTL 缓存降低系统调用成本。find-process-mode 默认为 off；只有 strict 或 always 才构造 finder。阻塞型平台查询由调用方放入 blocking pool，不能占用 Tokio reactor。

10. 状态、并发与热更新

WutherCore 以 Tokio 承载异步 I/O，但不会把所有状态塞进一个全局 async 锁。

10.1 状态分类

类型	示例	策略
启动后只读	`RuntimePlan`、RouteEngine 主结构	直接共享或 `Arc`
低频可变	出站注册表、组、API mutable config	`parking_lot::RwLock`
高频独立计数	流量、路由次数、节点统计	原子或分片结构
生命周期状态	Capture、Mesh、Feed manager	supervisor/handle 所有权
持久化状态	Smart、Pin、手动选择	redb + 批量异步写

10.2 热更新原则

Feed 更新先形成完整 provider 快照，再替换注册表与受影响分组。
规则集管理器编译完成后更新共享索引，读取侧不解释原始文件。
API 只允许修改明确声明的运行时字段。
需要重建 listener、路由表或 TUN 的字段不伪装成热更新。

10.3 任务所有权

每个长期任务都应有明确 owner：FeedManager 管订阅任务，RulesetManager 管规则集任务，CaptureSupervisor 管平台接管，MeshSupervisor 管组网后端，Runtime 管内部 writer 与连接状态。Drop 不是系统网络清理的唯一依赖；关键停止路径必须显式 await 并报告错误。

11. 安全与失败语义

11.1 输入边界

YAML、节点 URI、订阅、规则集、DNS 响应和 API 请求都不可信。解析器需要：

大小、深度、时间和重定向上限；
清楚的字段路径与错误原因；
对不支持语义显式拒绝；
不在错误或日志中回显密钥、订阅和私钥。

11.2 网络防泄漏

未解析的分组和未加载订阅默认 BLOCK。
节点域名使用内核 Resolver 的 bootstrap 路径。
出站 socket 在 connect 前 protect、mark 或绑定物理接口。
Capture 修改系统状态失败时，自动路由/TPROXY/REDIRECT 路径 fail-closed。
API 暴露到非本机地址时强制密钥。
Fake IP 映射、DNS Hijack 与业务 Resolver 共享状态。

11.3 资源恢复

Capture 与 Mesh 使用“声明 → 预检查 → 安装 → 持有 → 逆序释放”的模型。启动失败后如果清理重试仍失败，主进程拒绝继续以“普通代理”模式运行，因为宿主系统可能已留下半安装状态。

11.4 可诊断性

watchdog 使用独立系统线程和同步文件 I/O，不依赖 Tokio 或 tracing。即使 runtime 卡死，仍能输出心跳停滞、死锁与线程栈线索。普通运行错误应优先通过结构化日志、连接表和 /v1 调试接口呈现。

12. 平台边界

平台	普通代理	透明接管	进程识别	关键限制
Windows	HTTP/SOCKS5	Wintun + 系统路由	IP Helper API	管理员权限、多网卡和其他 VPN 冲突
Linux	HTTP/SOCKS5	TUN、TPROXY、REDIRECT	`/proc`	root/CAP_NET_ADMIN、防火墙与策略路由
macOS	HTTP/SOCKS5	系统 TUN/utun 与路由	libproc	权限、系统扩展和 VPN 共存
Android	宿主决定	VpnService FD；root 路径可扩展	系统 API或 `/proc`	宿主负责权限、FD 生命周期和 socket protect

“存在代码路径”不等于已覆盖所有系统版本。透明代理回归必须在真实平台验证启动、流量、网络切换、退出和异常恢复。

13. 扩展指南

13.1 新增出站协议

在配置节点模型与 URI/订阅解析中定义字段。
实现 OutboundAdapter，准确声明 TCP/UDP 能力。
在 registry 中构造 Adapter。
复用统一 Resolver、socket protect 与传输组件。
覆盖成功、认证失败、超时、取消、关闭和敏感日志测试。
更新功能矩阵和可运行示例。

13.2 新增路由条件

定义用户输入和错误语义。
编译为 RouteMatcher，不要在热路径解释 YAML。
明确多字段的 AND/OR 和规则顺序。
必要时扩展 FlowContext，但避免塞入协议私有状态。
为 inline、外部规则集与 /v1/route/check 增加测试。

13.3 新增 Capture 平台或方式

实现 Engine 生命周期与平台诊断。
把接口、路由、fwmark、防火墙和端口声明给资源仲裁层。
将权限探测与实际安装分开。
保证安装幂等、部分失败可回滚、停止可重试。
证明出站、DNS、订阅和规则集拉取不会自捕获。
用真实系统测试网络切换与非正常退出。

13.4 新增配置字段或 API

配置字段必须走完整的 UserConfig → defaults → RuntimePlan → consumer 路径。API 字段则需要独立公开模型、鉴权判断、输入上限和兼容策略。不要直接序列化包含凭据的内部结构。

14. 测试与验收

14.1 基础仓库检查

cargo fmt --all --check
cargo check --workspace --all-targets
cargo test --workspace
python scripts/check-repository.py

14.2 分层验证

层次	重点
配置单元测试	默认值、引用、错误路径、迁移和安全门禁
协议单元/集成测试	握手、错误输入、TCP/UDP、关闭和超时
Runtime 测试	规则顺序、组选择、订阅热更新和 fail-closed
规则集夹具	YAML/TXT/JSON/MRS/SRS 语义与版本兼容
API 测试	鉴权、脱敏、限流、兼容接口和状态修改
平台测试	TUN/TPROXY/REDIRECT 安装、流量与恢复
端到端测试	Mixed、URLTest、真实数据转发和退出

性能结论必须来自可重复基准，不在设计文档中写未经验证的固定数字。优化前先确定热路径和基线，并同时观察吞吐、p99、内存、任务数和错误率。

15. 当前限制与演进方向

当前仍处于 1.0 之前，主要限制包括：

配置与 API 尚未承诺长期稳定；
协议、传输和服务端版本组合需要更多互操作测试；
透明代理依赖真实系统状态，CI 不能覆盖全部路径；
Android 需要宿主应用完成系统生命周期；
choose: chain 当前在配置编译期拒绝；
Smart 是启发式和历史学习系统，通用 ML 模型仍是演进方向；
Mesh 已有资源仲裁基础设施，但具体产品后端尚未在主程序注册。

路线图以工程完成标准而不是日期排序，详见 ROADMAP。

16. 源码导航

主题	入口
CLI 与启动顺序	`crates/wuther-core/src/main.rs`
配置加载	`crates/core-config/src/loader.rs`
RuntimePlan 编译	`crates/core-config/src/runtime_plan.rs`
Runtime 组合	`crates/core-runtime/src/engine.rs`
统一入站处理	`crates/core-runtime/src/listener_handler.rs`
路由决策	`crates/core-route/src/engine.rs`
出站接口	`crates/core-outbound/src/adapter.rs`
出站注册	`crates/core-outbound/src/registry.rs`
Resolver	`crates/core-resolver/src/resolver.rs`
Capture 生命周期	`crates/core-capture/src/supervisor.rs`
Mesh 生命周期	`crates/core-mesh/src/supervisor.rs`
API 服务	`crates/core-api/src/server.rs`
功能现状	功能矩阵
排错	排错手册

17. 术语表

术语	含义
Mixed	同一端口同时接受 HTTP 代理和 SOCKS5
Capture	将系统或设备流量透明送入内核的 TUN/TPROXY/REDIRECT 等路径
RuntimePlan	用户配置补全并校验后的运行时计划
FlowContext	路由匹配所需的标准连接上下文
RouteDecision	`DIRECT`、`BLOCK` 或某个策略组
OutboundAdapter	所有出站协议共享的拨号接口
RulesetIndex	已编译外部规则集的共享查询索引
Fake IP	为域名分配的虚拟地址，用于透明接管后恢复域名语义
URLTest	对节点执行周期探测并记录存活/延迟
Smart	基于统计、偏好、粘性和用户控制的可解释节点选择
fail-closed	关键状态不确定时停止或阻断，而不是绕过保护继续运行

设计文档的职责是解释稳定边界和关键决策。字段细节进入配置/API 文档，完成度进入功能矩阵，未来工作进入路线图；这样读者可以先理解系统，再按需要深入实现，而不会把历史设想误当成当前承诺。

Uh oh!

Kernel Design

WutherCore 内核设计

1. 阅读路线

2. 系统全景

3. 设计目标与边界

3.1 设计目标

3.2 非目标

3.3 核心不变量

4. 配置编译：从用户意图到 RuntimePlan

4.1 为什么需要编译层

4.2 Profile 的职责

5. 进程生命周期

5.1 启动阶段

5.2 停止阶段

6. 一次连接如何通过内核

6.1 统一入站上下文

6.2 TCP 数据路径

6.3 UDP 数据路径

7. Workspace 与 crate 边界

8. 关键运行时契约

8.1 RuntimePlan

8.2 FlowContext 与 RouteDecision

8.3 OutboundAdapter

8.4 CaptureEngine 与 CaptureSupervisor

8.5 NetworkBackend 与 MeshSupervisor

9. 主要子系统

9.1 入站

9.2 路由与规则集

9.3 解析系统与 Fake IP

9.4 策略组与 Smart

9.5 透明接管

9.6 出站与传输

9.7 订阅与拉取

9.8 管理 API

9.9 观测与持久化

9.10 进程识别

10. 状态、并发与热更新

10.1 状态分类

10.2 热更新原则

10.3 任务所有权

11. 安全与失败语义

11.1 输入边界

11.2 网络防泄漏

11.3 资源恢复

11.4 可诊断性

12. 平台边界

13. 扩展指南

13.1 新增出站协议

13.2 新增路由条件

13.3 新增 Capture 平台或方式

13.4 新增配置字段或 API

14. 测试与验收

14.1 基础仓库检查

14.2 分层验证

15. 当前限制与演进方向

16. 源码导航

17. 术语表

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

WutherCore