Niskle Hub 互联方案（PC 端）

协议前置：本方案实现 01-互联协议规范-v1.md（下称「协议」）。协议是唯一真相源，本文只写 PC 端（Rust Host） 的落地方式，不重新定义端点、信封、错误码、操作名与事件主题。凡本文与协议冲突，以协议为准，并按文末 ⚠️ 协议待修订 清单回改协议。

• 目标代码库：D:\Work\FrameFace（Tauri 2 + Rust edition 2024 + TypeScript）

• 交付范围：协议 §13 的 P0–P3（全部在 Hub 侧，可只用 curl / 探针脚本独立验证）

• 不在范围：头显端 Niskle Link（P4–P7）；媒体面（串流）全部不做，只按要求预留形状与端口预算

• --

1. 目标与非目标

1.1 目标

1.2 非目标（明确不做，避免读者误判范围）

1.3 端口预算（协议 §15.5）

FrameCast（37020/37021）、SlimeVR（6969、21110、21112）、OSC（9000/9001/9003）、Link MJPEG（18980）一律不动。

1.4 编译期门控的取舍

不加 cargo feature，只用运行时配置 enabled 开关（默认 false）。理由：加 feature 会让 verify-commands.ps1、CI 与安装包需要两套构建路径，收益只是省几 MB 二进制。默认关闭 + 显式开启已经满足「不默认暴露」。

---

2. 架构落点

2.1 分层：core/ 与 host_app/（协议 §15.2 的硬要求）

产品路线已经明确：Link 将来是头显端串流接收端，Hub 是 PC 端串流服务端（对标 Virtual Desktop）。VD 的 PC 端是常驻服务，所以控制面核心逻辑不依赖 Tauri AppHandle，能被任意宿主进程承载。

        头显 Niskle Link（Android / Compose）
                 │  HTTP/1.1 + SSE ，Authorization: Bearer <token>
                 ▼
┌────────────────────── NiskleHub.exe（可信边界，SECURITY_BOUNDARIES.md:27） ──────────────────────┐
│  host_app/  ──适配──▶  core/                                                                    │
│  TauriHost             transport/  registry/  auth/  ops/  events/  policy/                     │
│  （AppHandle、          （tokio 监听、  （OPS 表、  （配对、 （处理器、（总线、 （锁、             │
│   State<Arc<…>>）        HTTP/SSE）    capabilities）令牌）  只调 host） 节流）  限流）           │
│       │                     │                                                                   │
│       │                     │  core 只认识 RemoteHost 抽象（core/host.rs）                       │
│       ▼                     ▼                                                                   │
│  ┌── 管理器（仅 host_app 能碰）────────────────────────────────────────────────────────────┐    │
│  │ EngineManager ──▶ \\.\pipe\FrameFace.Engine.v1（32 深队列，溢出丢最旧，:23,419-422）      │    │
│  │ SlimeVrManager ──▶ java -jar slimevr.jar（stop 会 taskkill /F /IM java.exe /T，:231-236）│    │
│  │ VrcftRuntime   ──▶ NiskleHubVrcft.exe                                                  │    │
│  │ updates::download_and_install ──▶ NSIS（基本不返回，updates.rs:136-138）                 │    │
│  └────────────────────────────────────────────────────────────────────────────────────────┘    │
│        │                                                                                        │
│        └──▶ Tauri 事件 frameface://status / frameface://remote-activity ──▶ 桌面 WebView         │
└──────────────────────────────────────────────────────────────────────────────────────────────────┘
   （未来）host_service/ ← Windows 服务宿主，复用同一份 core/，协议与两端实现都不用改

本期宿主决定：服务跑在 Tauri 应用进程内，在 lib.rs 的 setup 里、EngineManager::start 之后启动（lib.rs:142-159）。理由见协议 §15.4：本期目标（在 VR 里操作 Hub）本身就要求 Hub 正在运行——用户在用面捕时 Hub 必然是开着的。现在直接做服务会带来多进程、开机自启、权限提升与多一个攻击面，收益为零。

2.2 启动顺序与关闭

2.3 运行时模型

2.4 依赖规则与强制手段

强制手段（三层，成本递增）：

1. 门控脚本（本期就做）：tools/verify-commands.ps1 新增第 7 项——扫 src/remote/core/**/*.rs，命中 use tauri、tauri::、AppHandle、State<、Manager、Emitter、WebviewWindow、windows_sys、crate::engine_manager、crate::slimevr_manager、crate::vrcft_runtime、crate::updates、crate::upload、crate::named_pipe 任一即 problems++。它挂在 check-release.ps1:25-40 里，所以这是发布门而不只是本地提示。

2. 命名陷阱同样入脚本：core 是内置 crate 名，core/ 里的代码若写 use core::… 会解析到内置 core 而不是本模块。脚本额外拦 src/remote/** 里的裸 use core::，写法定为 use crate::remote::core::…。

3. 评审清单（现在写进 AGENTS.md）：core/ 的任何 PR 出现 tauri 字样即拒。将来真正新建 host_service/ 时，把 core/ 提升为独立 crate（remote-core，path 依赖），用编译器而不是 grep 来保证——那时边界才有实际收益，现在加 crate 只会增加构建与目录复杂度。

为什么不用「core 只暴露 trait 给 Tauri 调」的反向做法：桌面 UI 的 35 个命令（commands.rs:14-306）已经在用 State<'_, Arc<EngineManager>>，让它们改走 trait object 会改掉命令参数表，收益只是形式上的对称。桌面命令直接调管理器，只额外取 core 的资源锁（§5.4），是改动最小的正确解。

---

3. 操作注册表（单一真相源）

协议 §11.4 的教训明确：命令名在 4 个文件 + Engine 枚举 + 前端字面量里手工同步，必然漂移（contracts/ipc-v1-command.schema.json:32 漏了 total_max_frames，而 protocol.cpp:468-474 接受它、engine_manager.rs:459-461 发送它）。所以远程操作的元数据只有一份。

3.1 数据结构（core/registry/mod.rs）

pub enum Effect { Read, Write, Action }
pub enum Resource { Engine, Vrcft, Body, Update, None }   // 协议 §7.2 资源组

pub struct OpSpec {
    pub op: &'static str,          // 协议 §12.1 的点分 id，如 "tracking.start"
    pub group: &'static str,       // "hub" | "tracking" | "face" | ...
    pub title: &'static str,       // 中文标题，两端文案以它为准
    pub effect: Effect,
    pub confirm: bool,             // 协议 §9.4
    pub since: u32,                // 协议 §11.2 铁律 3：必填
    pub deprecated: bool,
    pub args: &'static str,        // 裁剪 JSON Schema 子集，单行字符串
    pub resource: Resource,
    pub core: &'static str,        // 对应 RemoteHost 适配方法名（供脚本校验）
    pub handler: fn(&OpsCtx, &serde_json::Value) -> Result<serde_json::Value, CoreError>,
}

pub static OPS: &[OpSpec] = &[ /* 每个 op 一条 */ ];
pub static GROUP_META: &[GroupSpec] = &[ /* id / title / order */ ];
pub static EVENTS: &[EventSpec] = &[ /* topic / title / since / default_hz / max_hz */ ];
pub static RESERVED_OPS: &[ReservedOp] = &[ /* 协议 §12.3 的 6 个 stream.* 占位 */ ];

五个设计取舍：

1. 表是 static 而不是运行时构造。门控脚本按行读的就是它；运行时拼出来的表脚本看不见。

2. handler 用函数指针而不是闭包/trait object。fn 指针可以放进 static；闭包需要 Box<dyn Fn>，只能 OnceLock 惰性初始化，且脚本无法静态提取。

3. args 存单行** JSON 字符串，不存嵌套结构体。脚本要按 OpSpec { 到单独一行的 } 切分条目（§3.5），多行嵌套字面量的大括号会把切分弄碎。排版约束写进文件头注释**：OpSpec { 独占一行、每个字段一行、} 独占一行、args 的 JSON 写成单行——多行的话脚本就切不开条目。

4. core 字段显式声明适配方法名。Rust 没有反射，这是「注册表 op ↔ 宿主方法」可校验的唯一方式。

5. Resource::None 是显式值而不是 Option。读操作与 app.*、client.* 明确不参与资源锁，后来者「顺手」给读操作加锁的路径也就不存在。

3.2 预留命名空间（协议 §6.3 / §12.3）

脚本守卫（§3.5 第 8 项）：OPS 中不出现 op: "stream.；RESERVED_OPS 的 id 集合与协议 §12.3 的 6 个完全一致；两张表的 op 不相交。

3.3 GET /v1/capabilities 完全由注册表生成

core/registry/capabilities.rs 只做一件事：遍历 OPS/GROUP_META/EVENTS 拼出协议 §6.2 的 JSON。

硬规则：capabilities.rs 里出现的任何 op 名字面量都等于给规范开了第二个真相源。 由单测 capabilities_are_registry_derived（集合相等）与脚本（检查该文件不出现 "xxx.yyy" 形式字符串）双重保证。

3.4 Tauri 命令保持薄适配

commands.rs 的 35 个命令名、返回类型、前端可见参数名一个都不改（commands.rs:14-306）。函数体加一行取锁：

#[tauri::command]
pub fn start_tracking(manager: State<'_, Arc<EngineManager>>) -> Result<TrackingStatus, String> {
    let _guard = host_app::lock(Resource::Engine).map_err(|e| e.to_string())?;
    manager.send("start_tracking", None)
}

要点：

• 返回值类型保持一致（Result<TrackingStatus, String>），CoreError 经 Display 转字符串，前端 friendlyError 路径零改动。

• 参数表也不变。这是选择「单例锁」而非「注入 State<RemoteHandle>」的直接原因（§5.4）。verify-commands.ps1:31-41 只提取函数名，所以即便将来加参数也不会打破门控，但本期不引入这个变量。

• SlimeVrManager 与 VrcftRuntime 改成 Arc<T>。它们现在是裸值 .manage(...)（lib.rs:94-95），TauriHost 需要共享所有权。改动点收敛在 6 处：lib.rs:38,94,95,167 与 commands.rs:157,175,292,294,301 的 app.state::<SlimeVrManager>() / app.state::<VrcftRuntime>()，把类型参数换成 Arc<...>。lib.rs:93 的 Arc<EngineManager> 已是 Arc，不动。

• 不新增 mod 到两个正则块里。mod remote; 只加在 lib.rs:3-11 的模块列表末尾，写进 use commands::{...}（lib.rs:15-24）或 generate_handler![...]（lib.rs:96-132）都会被脚本按裸标识符提取，判成「注册了但不存在的命令」。

3.5 新增一个 op 的代价

评审清单（这就是 code review 的全部内容）：① effect 是不是最小权限（只读别写成 action）；② 有没有副作用需要 confirm: true（协议 §9.4 五条之外，「不可逆 / 杀进程 / 删数据」一类都要加）；③ since 填的是不是首次发布的协议版本（填错等于破坏兼容性，协议 §11.2）；④ args 是否只用 type/properties/required/items/enum/minimum/maximum（oneOf/$ref/pattern 不在协议子集里）；⑤ 有没有误暴露协议 §12.2 排除的命令；⑥ core/ 里有没有出现 tauri；⑦ 有没有顺手动了 stream.* 或 37100–37199。

3.6 扩展 tools/verify-commands.ps1

现有 5 项检查（:53-168）全部保留，新增第 6–8 项，全部累加到同一个 $problems（最后 :171 赋给 $script:CommandSurfaceProblems，check-release.ps1:35 读它）。

第 6 项：注册表自洽。 因为 Get-QuotedList（:47）会把任何 "小写标识符" 当命令名，注册表的排版只能是 §3.1 那一种，脚本按行切分而不是嵌套匹配大括号：

# 6. 远程操作注册表：op/since/effect/core/group/confirm 必须齐全且自洽。
#    注册表按 §3.1 的排版写（`OpSpec {` 独占一行、`}` 独占一行、args 单行），所以脚本按行切分：
$entries = @(); $current = $null
foreach ($line in [IO.File]::ReadAllLines($registryRs)) {
    if ($line -match '^\s*OpSpec\s*\{\s*$') { $current = ''; continue }
    if ($null -ne $current) {
        if ($line -match '^\s*\},?\s*$') { $entries += $current; $current = $null; continue }
        $current += $line + "`n" } }
# 逐条断言：op 唯一且形如 group.verb；since 存在；effect 存在；group 与 op 前缀一致；
#           core 指向的 fn 在 host_app/host.rs 里存在；op 前缀不得为 stream.。
# 全局断言：协议 9.4 的 body.start / body.stop / capture.clear / update.install / client.revoke
#           必须 confirm:true；error.rs 的错误码必须落在协议 4.4 的 10 个之内；
#           RESERVED_OPS 必须正好是协议 12.3 的 6 个 stream.*，且不得与 OPS 相交。

第 7 项：core/ 依赖宿主即失败（协议 §15.2）。

# 7. core/ 不得依赖宿主（协议 15.2）。扫 src/remote/core/**/*.rs，命中任一即 problems++：
#    use tauri / tauri:: / AppHandle / State< / Emitter / WebviewWindow / windows_sys /
#    crate::engine_manager / crate::slimevr_manager / crate::vrcft_runtime / crate::updates /
#    crate::upload / crate::named_pipe。
#    同时禁止 src/remote/** 出现裸 `use core::`（core 是内置 crate 名，必须写 crate::remote::core::…）。

第 8 项：反向告警（不失败）——列出 host_app/host.rs 里从未被任何注册表条目引用的方法，防死代码堆积。只作 warning，否则内部辅助方法会造成假失败。

3.7 防漂移的第二道闸：contracts/remote-v1-ops.json

ipc-v1-command.schema.json 的教训是「规范与实现已经漂移，且没有可执行校验点」。所以：

• 该文件是生成物（不是手写规范），内容 = GET /v1/capabilities 的 operations + events，头部写 "generated_by": "core/registry/mod.rs — 不要手改"。

• Rust 单测 ops_snapshot_matches_registry 比对注册表与快照，不一致即失败并打印 diff。

• tools/remote_api_probe.py 运行时把真实响应与快照比对，不一致即探针失败。

这样「规范」与「实现」之间第一次有了可执行校验点，漂移会在提交前炸掉。

---

4. 模块与文件清单

全部位于 apps/frameface-ui/src-tauri/src/remote/（新建目录）。core/ 不 import tauri，host_app/ 不写业务判断（§2.4）。

4.1 remote/core/（纯逻辑，未来可整体搬进服务）

4.2 remote/host_app/（Tauri 宿主适配层）

4.3 其它仓库文件

---

5. 关键实现要点

5.1 HTTP 服务装配与依赖（本方案最重要的选型修正）

决策：不用 hyper 的 server feature，用 tokio::net::TcpListener + httparse 手写 HTTP/1.1。

理由是硬的：解包 hyper-1.11.0.crate 核对它的 Cargo.toml：

server = ["dep:httpdate", "dep:pin-project-lite", "dep:smallvec"]
[dependencies.httpdate]
version = "1.0"; optional = true

而 httpdate 在 .cargo-home 中出现 0 次、在 Cargo.lock 中出现 0 次（它只被 hyper 的 server feature 需要，当前工程只通过 reqwest 用 hyper 的 client 侧）。结论：hyper 的 server feature 无法离线构建；axum 依附它，同样不可用。

手写在这份协议下不是妥协，因为协议把所有难点都排除掉了：

依赖清单（P0 一次性加进 Cargo.toml，逐项核对过缓存与 lock）：

关键机制：edition 2024 默认 resolver = "3"，Cargo.lock 是 feature-minimal 的（只为当前启用的 feature 记录节点）。所以「把已在 lock 里的 crate 提为直接依赖」不需要重新解析、可离线完成；但任何新启用的 feature 只要拉到 lock 里没有的可选依赖，构建就会直接失败。上表每个 feature 都按这条规则核过。

几个代价明确的坑：① Content-Length 要先校验存在且 ≤65536 再分配缓冲，否则 Content-Length: 999999999 就能 OOM；② 头部缓冲上限 8 KiB，超过直接 400 关连接；③ 一律按字节处理，UTF-8 只在 JSON 解析处出现；④ 每个响应显式写 Content-Type: application/json; charset=utf-8 与 Cache-Control: no-store，SSE 例外；⑤ Connection: close 后要 shutdown() 写端再 drop，否则客户端可能读到 RST 而不是 EOF。

升级路径（记录备用）：一旦有网络把 httpdate 加入缓存与索引，transport/http.rs 可整体换成 hyper_util::server::conn::auto::Builder + service_fn，业务代码（router/registry/ops）零改动——这正是把 HTTP 细节全关进一个文件的收益。

5.2 SSE 响应体

/v1/events 响应头：HTTP/1.1 200 OK、Content-Type: text/event-stream、Cache-Control: no-store、Connection: keep-alive、Transfer-Encoding: chunked，随后立即写 retry: 3000\n\n。

5.3 状态变化检测与节流

TrackingStatus（contracts.rs:159-174）里 timestamp_ms 与 sequence 每个 tick 都变，逐字段比较整结构 = 永远「变了」。

1. contracts.rs 给 TrackingStatus、TrackingCapabilities、PerformanceStats、FrameCastMetrics、CaptureStatus 加 #[derive(PartialEq)]（纯派生，不改字段，不影响 commands.rs 返回类型）。

2. events/status.rs 提供显式比较 semantically_equal(a, b)：逐字段列出 engine/framecast/vrcft/face_tracking/eye_tracking/tracking_enabled/capabilities/performance/framecast_metrics/capture/last_error，故意排除 timestamp_ms 与 sequence。逐字段写全而不是「整体比较再排除」，是为了让以后新增字段时被迫做决定：漏加 = 该字段变化不上报（联调能发现），比整体比较的沉默失效更安全。

3. 节流才是真正的限速器。performance.fps/inference_ms/cpu_usage_percent/tracking_quality 每帧都在变，变化检测只能消掉 timestamp_ms/sequence 造成的假变化，不会把推送降到接近零；真正的上限由 hz 保证。

4. 推给桌面 WebView 的 frameface://status 不节流（保持现有行为），节流只作用于 SSE——远程不改变桌面 UI 的实时性。

5.4 按资源串行化（约束 4 的正面回应）

现状：互斥只写在前端（slimevrBusy 在 main.ts:740,2041-2078，pairingInProgress 在 main.ts:1256-1291），Rust 侧完全没有。头显与桌面同时点「启动体感追踪」会双份 kill_orphan_servers() 互相杀对方刚拉起的进程。

// core/policy/locks.rs
pub struct ResourceLocks { held: Mutex<HashMap<Resource, LockState>> }
pub struct ResourceGuard { resource: Resource }        // Drop 即释放
pub fn acquire(resource: Resource) -> Result<ResourceGuard, CoreError>;   // 不排队，立即 busy
static LOCKS: OnceLock<ResourceLocks> = OnceLock::new();  // 单进程单例（刻意的）

四条行为写得再清楚也不过：

1. 不排队，立即 busy（协议 §7.2）。这是刻意的：Engine 队列溢出丢最旧（engine_manager.rs:419-422），排队等于让远程请求悄悄挤掉桌面用户自己的操作。

2. 桌面 UI 也走同一把锁。这才是「下沉到 Rust」的全部意义——不是给远程单开一把锁，而是让 commands.rs 也经过它。改造后前端的 slimevrBusy 降级为纯 UI 反馈（防连点、显示 loading），不再是正确性边界。

3. 前端 busy 标志不删除，改为可被远程置位。新增 Tauri 事件 frameface://remote-activity，payload {"resources":["body"]}；main.ts 加一个监听，远程持锁时把 slimevrBusy = true、释放时置回。这样「头显正在启动体感追踪」实时反映到桌面开关的 loading 态。删掉标志会带来双击重复提交，所以这里是保留并同步，不是退役。

4. 单例锁优于注入 State。用 static LOCKS 让 commands.rs 的参数表一字不改（§3.4）；进程内只有一份锁集合，语义上就是单例。

5. 锁的泄漏面要封住。ResourceGuard::drop 释放；LockState 另记 started: Instant，超过 300 s 视为陈旧并强制释放 + 记 warning——防的是 abort/进程外异常导致的永久死锁。

5.5 每客户端限流与 retry_after_ms 契约

retry_after_ms 遵守协议 §4.3 的契约：缺省 500 ms、上限 3000 ms。error.rs 在构造 CoreError 时统一钳制：min(3000, max(0, value.unwrap_or(500)))。算法：令牌桶等待 ceil((1 - tokens) / rate * 1000)，向上取整到 50 ms 倍数，最小值 100；锁冲突按资源组给经验值（engine 200、vrcft 500、body 3000、update 3000）。

因为 Link 会「自动重试一次」（协议 §4.3），锁的持有时间要与 retry_after_ms 相称：body.* 里 SlimeVrManager::start 会先 server_ports_busy() 探测、必要时 kill_orphan_servers()（内含 800 ms sleep，slimevr_manager.rs:231-237）再 spawn，整体可能接近 3 s。见 §9 风险 6。

5.6 配对、重配对与自我注销

配对码（协议 §5.3）：6 位数字（format!("{code:06}")，字符串截断会漏前导零）；TTL 用 Instant 120 s（不用 SystemTime——用户改系统时钟不该延长有效期）；成功即 take() 整段 session；失败计数到 5 立即作废整段 session（不是只锁一会儿）；只在内存（Zeroizing<String>，drop 清零）；日志与信标里都不出现配对码（core/auth/pairing.rs 里不出现日志宏，错误消息只写「配对码错误（剩余 N 次）」）；session 上不加 #[derive(Debug)]，防 {:?} 意外打日志。展示路径：PC 端专用命令返回 {code, expires_at_ms}，不经由任何 HTTP 响应回传配对码。

client.id 重配对语义（协议 §5.2）：client.id 由 Link 生成且永不变更。Hub 收到已存在的 client.id 时：

保留显示名的原因：client.rename（协议 §12.1）是 PC 端的用户操作，若重配对采用请求里的 name，用户改的名字会被头显的默认名覆盖。⚠️ 见文末协议待修订第 3 条。

POST /v1/unpair（协议 §3.2）：鉴权后删除自己那条记录并立即吊销令牌；实现方式是给每条记录一个 epoch，删除即 epoch += 1，在途请求与 SSE 连接在下一个检查点失效（只从表里删掉的话，已建立的 SSE 会继续收数据）。

5.7 令牌存储

5.8 配置持久化

5.9 /v1/info 与 addresses（协议 §3.1、§10.4）

/v1/info 的字段集合是封闭的，只返回协议 §3.1 那 10 个：

addresses 的枚举与排序（host 侧 GetAdaptersAddresses，windows-sys features Win32_NetworkManagement_IpHelper/Win32_Networking_WinSock/Win32_Foundation；该 crate 唯一依赖 windows-link 已在缓存与 lock 中，不引入新 crate）：

不返回：操作系统版本、用户名、已配对设备名与数量、网络接口详情、路径、密钥（协议 §3.1 底部）。单测 info_field_set_is_closed 用严格键集合断言守住这条边界。

5.10 监听范围与防火墙

5.11 UDP 信标（协议 §10.1）

5.12 notice 服务端半边（协议 §8.3）

协议把 notice 的展示规则分给了两端。Hub 只负责服务端那两行，客户端规则（3 s、sticky 30 s、最多 1 条 sticky、队列 ≤4）属 Link：

notice 的来源（本期）：status.last_error 的变化、SlimeVr 启停结果、更新进度、能力清单变化。前端 toast（main.ts:345,351-364 已有 TOAST_DURATION_MS = 3000 与文本去重计数）无法被 Rust 看到——见文末 ⚠️ 第 7 条。

5.13 错误映射

core/error.rs 是唯一做映射的地方，向上给出 CoreError { code, message, field, retry_after_ms }：

这里有一处已知的技术债：底层返回 String（commands.rs 全部是 Result<_, String>），所以 P0–P1 的映射只能基于稳定前缀匹配。不为「优雅」把管理器返回类型改成 thiserror 枚举——那会改掉 commands.rs 签名与前端错误处理，超出授权。正确顺序是：P1 先把上表的字符串常量集中到 error.rs 一处（便于将来整体替换成类型化错误），P5+ 再单独评审类型化改造。

HTTP 状态码严格按协议 §4.4，不自创；错误码集合由脚本（§3.6 第 6 项）锁死为封闭集。

---

6. 与既有代码的接线点（完整清单）

verify-docs.ps1 会校验 docs/** 里反引号包裹的路径真实存在，所以新文档引用的路径要先落地。

---

7. 安全清单（默认启用前的逐项检查）

---

8. 测试与验证

8.1 单元测试（cargo test --offline，core/ 内 #[cfg(test)]，无需 Tauri 即可跑）

8.2 集成探针 tools/remote_api_probe.py

沿用 tools/*_probe.py 的既有 house style（参照 slimevr_bridge_probe.py、framecast_status_probe.py）：仅标准库（argparse/json/socket/sys/time/urllib.request/threading）、无第三方依赖、main() -> int、sys.exit(main())、顶部中文 docstring 写清「用途 / 用法」、参数用 argparse。

行为（按顺序）：配对 → 拉能力清单 → 逐个调用 read 操作 → 短暂订阅 SSE → 输出 pass/fail 表。

python tools/remote_api_probe.py --pair --code 042317 --host 192.168.1.10
python tools/remote_api_probe.py --token-file %TEMP%\niskle-token.txt --reads --sse 5
python tools/remote_api_probe.py --beacon 10          # 监听 37022 十秒
python tools/remote_api_probe.py --json --out report.json

安全约束（写进 docstring）：

• 默认只调用 effect == "read" 的操作；--allow-write 才调 write；

• action 类一律要求 --allow-action 且用 --op 逐个显式指定；

• body.stop / body.start 不会自动调用（会 taskkill /F /IM java.exe /T，slimevr_manager.rs:231-236），要调它们得同时给 --allow-action --op body.stop --yes-kill-java；

• 令牌缓存文件权限收紧（Windows 用 icacls），打印时只显示前 6 位。

附加检查（对齐协议新增内容）：--reads 会顺带断言 /v1/info 的键集合封闭、port 与实际连接端口一致、addresses 非空且都是私有地址；--sse 会统计首帧延迟、平均间隔（验证 hz 节流）、retry: 只出现一次、keepalive 计数。

表格列：op | effect | HTTP | code | ms | verdict，外加汇总（ops 总数、read 通过数、能力快照 sha256）。失败项打印原始响应体（截断 2 KiB）。

8.3 要留存的证据

---

9. 风险与未决问题

---

10. 分阶段实施

对齐协议 §13。P0–P3 全部在 Hub 侧，不依赖 Link，每阶段结束都能用 curl / 探针留证据。分层（§2.1）在 P0 一次性建好，之后每阶段只往 core/ 加东西——这样 P4–P7 与未来的服务化都不会返工。

P0 — 配对 + 令牌 + RPC 骨架 + hub.status + 分层落地

P1 — 能力清单 + hub/tracking/face 全量 + 串行化 + 限流

P2 — SSE 事件流（status + notice）

P3 — UDP 信标 + 网络策略 + 顺带修 21112

P4–P7（Link 端）与媒体面（串流）不在本方案范围。

---

11. AI 实现提示词

你将在 Windows 上的真实仓库 D:\Work\FrameFace 里实现「Niskle Hub 局域网控制面」的 P0 + P1。
这是 Tauri 2 + Rust（edition 2024）桌面项目的 Rust Host 部分。

【第一步：先只读，不要改任何文件】
读完先复述一遍你理解的约束，再动手：
1. C:\Users\Administrator\Desktop\Niskle互联方案\01-互联协议规范-v1.md  ← 唯一真相源
   重点：§0.1 §3 §3.1 §3.2 §4 §5 §6 §6.3 §7 §8.3 §9 §10.1 §10.4 §12.1 §12.3 §15.2 §15.5
2. C:\Users\Administrator\Desktop\Niskle互联方案\02-Niskle Hub 互联方案（PC 端）.md ← 设计依据
   重点：§2.2 §2.4 §3 §5 §6
3. apps/frameface-ui/src-tauri/src/{commands.rs,lib.rs,engine_manager.rs,contracts.rs,upload.rs}
4. apps/frameface-ui/src-tauri/{Cargo.toml,build.rs,permissions/frameface-control.toml}
5. tools/verify-commands.ps1 与 tools/slimevr_bridge_probe.py（探针 house style）、AGENTS.md

【绝对不可破坏的不变式】
A. tools/verify-commands.ps1 必须继续通过（tools/check-release.ps1 会跑它）。命令面只允许新增
   remote_begin_pairing / remote_cancel_pairing / remote_status 三个，并同步进 lib.rs 的
   use commands::{...} 与 generate_handler![...]、build.rs 的 AppManifest::commands、
   permissions/frameface-control.toml 的 commands.allow、main.ts 的 invoke 字面量。命令名必须小写 snake_case。
B. commands.rs 既有 35 个 #[tauri::command] 的命令名、返回类型（仍是 Result<_, String>）与前端可见参数名
   一个字符都不能改。只允许在函数体开头加一行取资源锁，再照原样调用管理器。
C. build.rs 里不得新增任何其它带引号的小写字符串——verify-commands.ps1 用正则 "([a-z][a-z0-9_]*)" 提取，
   多余引号串会被当成命令名。同理不要往 lib.rs 那两个块里加任何标识符。
D. 离线构建：$env:CARGO_HOME='D:\Work\FrameFace\.cargo-home'; cd apps\frameface-ui\src-tauri; cargo build --offline
   只能加：tokio（features 仅 rt,rt-multi-thread,net,time,sync,io-util；绝对不要 macros 或 signal）、
   httparse、sha2、subtle、base64、rand、zeroize。不要加 axum / hyper / tungstenite / tiny_http / rcgen /
   hmac / aes-gcm / qrcode —— 缓存里没有。注意 hyper 的 server feature 需要 httpdate，而它在 .cargo-home
   与 Cargo.lock 中都不存在，所以 HTTP 必须用 tokio::net::TcpListener + httparse 手写（方案 §5.1）。
E. 不要动 main.ts 里 2 秒的 get_tracking_status 轮询与 150ms 的骨骼轮询。
F. 不要用任何破坏性的 git / 文件命令；工作区有大量未提交的用户改动。不要 git add/commit/checkout/reset。

【架构硬要求（协议 §15.2）】
把模块分成两层，且 core/ 里**绝对不能出现 tauri**（不能 use tauri、不能出现 AppHandle/State</
Emitter/WebviewWindow/windows_sys，也不能引 crate::engine_manager / slimevr_manager / vrcft_runtime /
updates / upload / named_pipe）。core/ 只能通过 core/host.rs 里的 RemoteHost trait 与 DTO 访问外部世界；
host_app/ 实现该 trait 并负责所有 Tauri、windows-sys、注册表、PowerShell 相关代码。
注意 `core` 与内置 crate 同名：必须写 use crate::remote::core::…，不能写 use core::…。
本期宿主仍是 Tauri 应用（协议 §15.4），但分层现在就要建好，未来加 host_service/ 时只搬 core/。

【P0 交付】
- remote/core/ 与 remote/host_app/ 两层骨架；RemoteHost trait。
- GET /v1/info：字段集合严格等于协议 §3.1 的 10 个，不多不少。addresses 由 host 枚举本机可用 IPv4
  （跳过回环/非 Up，物理网卡私有地址在前、APIPA 最后），port 用实际绑定端口回读。
- POST /v1/pair：6 位配对码，TTL 120 秒，一次性，最多 5 次尝试，只在内存，绝不进日志与信标。
  若 client.id 已存在 → 视为同一设备重新配对：吊销旧令牌、签发新令牌、不新增条目、保留 Hub 端已存显示名。
- POST /v1/unpair：鉴权后立即吊销自己的令牌（在途请求与 SSE 也要失效）。
- POST /v1/rpc 支持 hub.status / hub.performance / hub.info。
- 令牌：32 字节随机 → base64url；只存 sha256 十六进制；subtle 常量时间比较；最多 16 个客户端。
- 配置写 %APPDATA%\FrameFace\remote.json，原子替换（.tmp + fs::rename）；port 若落在 37100–37199 必须拒绝；
  配置里不存在 beacon_port（信标端口固定 37022）。instance_id 复用 upload::install_id()，不要新建第二个 id。

【P1 交付】
- core/registry/mod.rs 是唯一真相源：每条 OpSpec 含 op/group/title/effect/confirm/since/args/resource/core/handler。
  GET /v1/capabilities 完全由它生成，capabilities.rs 里不得出现任何 op 名字面量。排版硬约束：
  `OpSpec {` 独占一行、每个字段一行、`}` 独占一行、args 的 JSON 必须单行（脚本按行切分）。
- 实现 hub / tracking / face 三个分组的全部 op（协议 §12.1），含 tracking.set_eye_enabled 在
  capabilities.eye_tracking == false 时返回 unavailable。不实现其它分组。
- RESERVED_OPS 登记协议 §12.3 的 6 个 stream.*，但不出现在清单里、被调用时返回 unknown_op；
  清单里不返回 streaming 对象。
- ResourceLocks：engine / vrcft / body / update 四组，同组已有操作在途则立即返回 busy + retry_after_ms
  （缺省 500、上限 3000），不排队。桌面 UI 命令走同一把锁。前端 slimevrBusy 保留为纯 UI 状态。
- 每客户端限流：在途 ≤4、20 次/秒，超限返回 busy + retry_after_ms，绝不静默丢弃。
- 扩展 tools/verify-commands.ps1：注册表自洽检查（since/effect/core 方法存在/group 前缀/§9.4 五条 confirm/
  错误码封闭集/stream.* 不得进 OPS/RESERVED_OPS 齐全）+ core/ 不得依赖宿主 + 禁止裸 use core::。
  必须继续累加到同一个 $problems / $script:CommandSurfaceProblems。
- 新增 tools/remote_api_probe.py（仅标准库，main() -> int，中文 docstring 写用途与用法），默认只调
  effect == read 的操作；body.start / body.stop 必须在 --allow-action --op --yes-kill-java 同时给出时才调用。

【必须报告】
1. 完整跑一次并贴出 .\tools\verify-commands.ps1 与 .\tools\check-release.ps1 的输出与退出码。
2. 贴出 cargo build --offline 与 cargo test --offline 的结果。
3. 给出 curl.exe 的 P0 三条命令与真实响应；以及 grep -rn "tauri" src/remote/core/ 的输出（应为空）。
4. 明确列出「你没能验证的东西」（例如：真实头显、真机防火墙行为、无管理员权限下的防火墙规则、
   公用网络检测在你机器上的实际取值、多网卡 addresses 的真实排序、未在真机跑过的并发时序）。不要假装验证过。
5. 列出你为避免破坏 A–F 而做的每一处妥协。

---

附：⚠️ 协议待修订 汇总