wangyukun/remote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
84 Commits 6 Branches 0 Tags 1.3 MiB
3b219a442d
Commit Graph

84 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
郑博文
3b219a442d test(tools): cursor_proof + proof_common 抽取 + rel_mouse 适配 v5/双屏与污染修复 
4b 光标覆盖层验收（V-D1/D3/D6/D7）+ 4a 建议 2 的公共库沉淀：

- proof_common.ps1：抽 landscape/rel_mouse 已验证的观测面 helper
  （唤醒只从证明过的隐藏态、正向配对判隐藏、N25 唯一临时文件、按文案取按钮、
  静置门控 + SetCursorPos 读回自校验、内存预检、R-7 新鲜守卫）。
  老 proof 本轮**不迁移**（改 4 个已验证脚本而不全重跑=假绿风险，登记下轮卫生项）
- cursor_proof.ps1：真机判据
  V-D1 截图青簇质心 vs CursorMarker 映射 ±6px（含近原点 (48,48)，Some(0,0)≠None 由单测+golden 锁）
  V-D3 静止桌面跳转后 900ms 内标记跟随（覆盖 500ms 保活重发带新鲜 cursor）
  V-D7 指针进左侧副屏负 X → agent 折叠 None → 无青簇（本机双屏白送的真实判据）
  reject 阶段 V-D6：旧 v4 APK 连 v5 agent → 屏幕出「协议版本不一致」+ detail client=4,server=5
  实测全绿：4 点偏差 ≤0.6px、跟随 0.5px、副屏无簇、拒绝判据命中
- rel_mouse_phone_proof.ps1：适配 v5 + 修两处 harness 缺陷（都是本轮回归实测逼出的）
  ① HUD v4 断言→v5（PROTO_LABEL 配对）；② V-B2 R7 期望值从写死 1920 派生
     改为按实时桌面 / 动态算（桌面已漂到 2560x1440，旧写死值假报 575px，
     违反 AGENTS.md 坐标期望按当前分辨率重算）
  ③ 模式守卫改为无条件 Set-Mode relative（旧 HUD.Contains(绝对) 在 HUD 读空时
     静默跳过，上一轮 throw 残留的 relative_mode=false 污染了整个 step2——
     绝对模式 DOWN 发绝对移动是正确产品行为，被 2c 误读成 teleport）
  ④ Set-Mode 唤醒 miss 并入 try 预算（原来单次重读即 throw，烧掉整脚本）+ 失败截图证据
  实测：R7 误差 1px、2c maxJump=0、长按右键 0→1、全链路绿
 2026-11-02 12:39:23 +08:00
郑博文
45daba5419 chore(android): 4b 版本落账（HUD v5 标签 + APK versionCode 5） 
- PROTO_LABEL 4→5：与 common::PROTO_VERSION 的人工同步义务（R5 显示要求），
  rel_mouse_phone_proof 的 HUD v5 断言与之配对（R-5 同源注释写明）
- versionCode 4→5、versionName 0.1-phase4b：真机验收跑的就是这个包，
  dumpsys 版本号是 proof 判「装没装对」的唯一依据（R-7 的 APK 侧对应物）
 2026-11-02 12:38:40 +08:00
郑博文
efcaeaad26 test(android): 光标映射 8 例 + 帧头拆包 golden bytes 6 例 
4b/V-D1 的单元侧判据（跨端契约 + 映射语义）：
- CursorMarkerTest：中心/满量程/(0,0) 合法/1:1 恒等映射；null、尺寸未就绪、
  越界全分支返回 null。origin_maps_not_treated_as_none 锁最危险的错——
  把左上角误当无光标（协议用 Option 的全部理由）
- RustBridgeTest：goldenHeader 逐字节手抄（与 android-ffi 写端测试同一组常数对拍），
  锁 [25]/[26..28]/[28..30] 三个新偏移 + 有符号 i16 + 截断缓冲防御 + 空载荷边界
- R-8 反向验证：读偏移 26→27 后 4 例坐标测试确实红（已改回）；
  CursorMarker 边界 >= 改 <= 后 origin 用例确实红（已改回）
JVM 全量 60 passed / 0 failed（--rerun-tasks 新鲜跑，XML 时间戳核对）。
 2026-11-02 11:05:24 +08:00
郑博文
9a6f6962d2 feat(android): v5 光标标记层（拆包迁移 FrameCodec + CursorMarker + Overlay + 接线） 
4b 手机端「看得见远端鼠标」的实现（协议 v5 的消费端）：

- RustBridge：Frame 增 cursor: Pair<Int,Int>?（可空 Pair 忠实映射 Option<(i16,i16)>，
  杜绝「x 有 y 无」非法态）；拆包逻辑连同字节 reader 迁到顶层 FrameCodec——
  RustBridge object 带 init{loadLibrary}，测试里不可达，抽成无 native 的顶层 object
  才能把跨端偏移放进 JVM 单测（核过 Rust 一端≠核过 Kotlin 另一端）
- CursorMarker.mapToView：桌面坐标→视图坐标等比映射（letterbox 下线性等比，
  与 RelPointer 同一套比例）；null/尺寸未就绪/越界一律返回 null（不画），
  绝不用 (0,0) 当缺省——那会把「无光标」和「光标在左上角」抹平成一样
- CursorOverlayView：SurfaceView 的上层兄弟视图（surface 合成在窗口之下，
  同视图无法自叠加）；双描边圆环+青色中心点（兼作 proof V-D1 的颜色特征码，
  UI 层绘制不经 H.264，screencap 里颜色精确）；volatile + postInvalidate 跨线程；
  不消费触摸（覆盖整个 stage，若吃事件会同时废掉远端操作和黑边唤出）
- MainActivity：解码循环每帧喂 cursorOverlay.updateCursor(f.cursor)（放解码前，
  光标是帧头字段与解码成败无关）；cleanupSession 与 disconnect 两条收尾路径同改
  清标记（R-5 同源，旧会话光标留着会冒充新会话）

assembleDebug BUILD SUCCESSFUL（Canvas API 编译过）；JVM 60 passed。
 2026-11-02 11:05:09 +08:00
郑博文
4379b01d41 refactor(android-ffi): 抽 pack_frame_header 并加写端字面量对拍单测 
步骤 4 的跨端契约闭环：把 30 字节头构造从 nativeNextFrame 内联提取成纯函数，
写端只有一条路径（消除内联/函数两处并存 = R-5 同源漂移）。

新增 host 可跑的 3 条单测（#[cfg(test)]，进 --workspace --exclude linux-agent 口径）：
- header_bytes_match_the_declared_layout：逐字节手抄常数，与 Kotlin 侧
  RustBridgeTest.goldenHeader 是同一组——两侧各握一份手抄，改任一偏移另一侧必红
  （只锁读端有盲区：Kotlin 字面量若本身抄错 Rust 布局会跟着一起错还全绿）
- none_cursor_writes_zero_flag_and_zero_coords：None 分支 has=0 且坐标字节不残留脏值
- negative_coords_keep_bit_pattern：i16 负坐标位模式忠实
android-ffi 在 host(gnu) cargo test 可编译可跑，实测 3 passed。
 2026-11-02 11:04:51 +08:00
郑博文
8eed1e20e1 feat(viewer-core,android-ffi): v5 光标字段透传到 FFI（帧头 25→30 字节） 
主控链路把协议帧头的光标坐标交给 Kotlin：
- viewer-core::Frame 增 cursor: Option<(i16,i16)>，From 实现透传；
  契约测试改为 Some((640,480)) 并断言透传——丢它=标记永不显示且丢法是静默的
- android-ffi 定长头 25→30：尾部追加 [has_cursor 1][x i16 LE 2][y i16 LE 2]，
  放末尾保证 Kotlin 既有偏移量（0/1/9/17/21）全部不移动
- None → has=0 且坐标字节恒 0（无意义）；Some 分支显式写两坐标，
  杜绝「Some 但忘写坐标」的编辑事故（文件头注释同步 30 字节布局）
- R-5 同源检查：RustBridge.kt 的 FRAME_HEADER_LEN=25 与拆头偏移是本次协议变更的
  同步改动点，Kotlin 侧在下一提交完成（同一循环、相邻提交）
 2026-11-02 10:39:19 +08:00
郑博文
ad46fc805b feat(agent-core): ScreenCapturer 新增 pointer_state 默认实现并接入帧头 
v5 光标字段在平台无关会话层的接缝（4b/Q4=A：Linux 实装另立循环）：

- trait 新增 pointer_state()，默认实现返回 None + 会话期一次性日志——
  与 InputInjector::text() 未实现先例同款纪律（异常路径必须可见，且不逐帧刷屏）
- encode_send 增 cursor 参数，两条发送路径（新帧/静止强制 IDR）都传入
- 静止保活重发分支：split 出的旧帧头沿用会让标记冻住（画面静止≠指针静止），
  与 seq/ts_ms 同规重建 cursor
- 新增单测锁默认实现契约（None 且 panic-free，Linux/X11 端真实形态）
- linux-agent 不强制实现（cargo build --workspace 复验编译通过）
 2026-11-02 10:36:47 +08:00
郑博文
b1ac32175c feat(agent): v5 光标采样接入帧头（GetCursorInfo + 折叠规则 + dump 观测列） 
采集端把远端光标位置填进每帧帧头，供主控端画标记（4b 解决看不见远端鼠标）。

- fold_cursor 纯函数承载全部折叠判定：隐藏(CURSOR_SHOWING 未置位)/
  越出采集画面 [0,w)x[0,h)（副屏负坐标区，Q5=A）/超 i16 范围（防截断成
  看似合法的错坐标）→ None；坐标语义单一来源在被控端
- sample_cursor 只负责 Win32 读数（cbSize 契约注释）与失败/越界留痕
  （会话期各只打一条日志，可见后果但不逐帧刷屏）
- 采样点在 emit! 宏（唯一发送入口）：新帧/静止 500ms 保活重发/强制 IDR
  三条路径天然全覆盖，帧头 cursor 与 ts_ms 同刻
- 前提：agent 的 per-monitor DPI 感知（3b/D2）保证 ptScreenPos 是物理像素
- agent crate 首批单测 4 例（界内含原点/隐藏/五类越界/i16 上界），
  mutation 反向验证（>= 改 > 后越界用例确实红）
- dump_stream 帧表加光标列，Windows 端实测（本机同回环）：
  界内 Some(1000,600) 精确、副屏 -960 折叠 None、None->Some(300,250) 恢复
  全部 PASS；期间发现有人操控真鼠标，探针已改静置门控+读回自校验设计
 2026-11-02 10:32:09 +08:00
郑博文
98b4f03cff feat(common): 协议 v5 帧头新增光标字段 cursor 
4b 光标覆盖层的协议地基：VideoFrameHeader 尾部追加 Option<(i16,i16)>，
携带本帧发送时刻的远端光标物理像素坐标（None=隐藏/离屏/未实现三态折叠）。
解决「看不见远端鼠标」——相对模式下用户不知道指针在哪、轻点会落在哪。

- 字段追加改变 bincode 线格式，PROTO_VERSION 4→5，v4 旧端由握手显式拒绝（既有机制）
- v4 守卫按 v3 先例降为下界锚点，最新一代用精确等号守卫
- 新增 3 测试：Option 往返（含 i16 边界与负值）、尾部追加不扰动既有字段、
  None 紧凑性（Some 比 None 恰多 4 字节，证明光标未被固定宽度白占）
- agent/agent-core/viewer-core 构造点补占位 cursor: None（真实采样下一步接入），
  保证本提交全 workspace 可编译
 2026-11-02 10:11:23 +08:00
郑博文
e96502f888 test(tools): 4a 横屏验收脚本 + 既有 proof 适配自动隐藏与同源缺陷修复 
新增 landscape_proof.ps1：V-C1~C7 判据（自动横屏 <=2s、旋转零中断、
动画桌面下 >=45fps、控制条自动隐藏、黑边唤出零远端泄漏、四按钮可点、
方向四态循环、表单竖屏）。方向判定只解析 Display: mDisplayId=0 块内
cur=WxH——这台 vivo 无 mRotation= 行，且 dumpsys 里有常驻 1080x2400 的
虚拟屏，匹配首个 cur= 会在已横屏时误报未旋转（探针实测踩过）。

横屏自动隐藏与既有 proof 的判据自冲突（HUD 随控制条 GONE，RTT= 读不到
被误判断线/未连接），三个 proof 统一加「确认隐藏态才走黑边唤醒」：
phone_chain_proof、ime_chinese_proof、rel_mouse_phone_proof。

修 rel_mouse_phone_proof 两处：
- 2c 基线判据：横屏滑动 768px 的残余相对事件成批延迟落地，旧的「两次
  读数相等」被突发间隙骗过（实测假失败 351/1418px）。改为 6 读数沉降 +
  4 次采样判漂移 + 绝对泄漏点特征比对。
- step 4 靶窗启动缺 3 个 Mandatory 参数，子进程瞬间失败退出（3b 起一直
  如此，右键落在裸屏幕中心，靠近违反 R-11「不得注入他人窗口」）。现按
  契约启动并把指针停在自家窗口内。

R-5 同源排查：靶窗结果目录固定路径 + 启动时删自己的 stop.flag，会让
上一轮失败遗留的靶窗永远收不到退休信号、继续抢前台并写脏 received.txt
（实测收到 abc\nabc）。5 个 proof 统一改每轮唯一目录（\47512 后缀）。

ime_chinese_proof 的切换键标定失效：设备 IME 已换成搜狗（原为讯飞），
旧坐标 (146,2096) 静默点空。IME 按键视图对 uiautomator 不可见、无法机械
标定，按 R-9 转人工确认，不硬凑自动化。
 2026-11-01 21:58:19 +08:00
郑博文
cff7fc8ab3 feat(android): 横屏远控（自动方向 + 控制条自动隐藏 + 黑边唤出） 
竖屏看 16:9 桌面太小（用户 2026-11-01 反馈）。探针实测（docs/output/
2026-11-01-landscape-probe/）：App 级 setRequestedOrientation 在这台 vivo
上有效（761ms），且旋转只触发 surfaceChanged、不销毁 surface、不断会话、
横屏 fps=58~60——所以不需要 TextureView（探针另测 TextureView 掉 30~37%
帧率）、不需要任何解码器重建配合，旧 S3 作废。

- OrientationPolicy（AUTO/LANDSCAPE/PORTRAIT/SYSTEM）纯逻辑 + 10 单测，
  常量值经 javap 对 android-34 核实；已做 mutation 反向验证（AUTO 判定
  > 改 >= 时方屏用例确实红）。
- 表单页强制竖屏；连接成功按策略设方向（默认 AUTO：远端宽>高即横屏）。
- 横屏 immersive + 状态行压 36dp + 控制条 3s 无操作自动隐藏。
- 唤出区 = letterbox 黑边（stage 在隐藏态消费画面外触摸）。刻意不用
  底部边缘带：R7 回归实测那种带会吃掉远端桌面底部 ~11%（Windows 任务栏
  就在那里），点任务栏会变成唤出菜单。黑边不属于 SurfaceView，零冲突。
- 竖屏永不隐藏（裁决只针对横屏空间不足）。
 2026-11-01 21:57:49 +08:00
郑博文
1a6c3f15a2 test(tools): 3b 真机验收脚本 + 修正 IME proof 的按钮定位 
rel_mouse_phone_proof.ps1 覆盖 V-B1a（相对位移方向/符号/不跳变）、V-B2（切绝对
模式后 R7 重测）、V-B3（长按出右键、拖拽不出）。

三处 harness 教训（都已写进脚本注释，避免下次重踩）：
1. uiautomator 不暴露 SurfaceView，裸 SurfaceView 塌成 android.view.View；
   按 16:9 宽高比识别视频视图，并断言比例，避免静默抓错节点。
2. 上一段滑动的相对事件可能在 SetCursorPos 之后才落地，制造出 15px/298px 的
   假跳变。判据前必须先等链路静默、并要求基线两次读数一致。
3. ime_chinese_proof 用「第一个 Button」当键盘按钮——3b 在按钮栏上方插入了
   灵敏度行，第一个 Button 变成了减号，proof 报「IME not shown」。
   改为按文案匹配，与位置无关。
 2026-10-31 17:35:18 +08:00
郑博文
aede7b6c3c test(android): 相对鼠标/长按右键纯逻辑单测 17 例 
覆盖 V-B1 判据对应的行为，不是「跑通就算」：
- 慢速小幅不丢位移（10 次 0.3px 必须发出 3px）
- 负值向远离零取整（-0.7 取 -1，向零截断会让反向慢滑丢位移）
- 撞边不积债（回滑立即发出，不因补偿而空转）
- i16 越界 clamp 而非回绕
- 长按三条判据：够久、没动、非双指

已做 mutation 反向验证：把期望 3 改成 4 后测试确实红，改回后绿（断言非空转）。
 2026-10-31 17:35:11 +08:00
郑博文
7c3b6b3e93 feat(android): 相对鼠标模式 + 灵敏度 + 长按右键 + 修复表单 IME 残留 
相对模式（默认）：手指滑动按增量移动远端指针，DOWN 不发绝对移动——轻点落在
远端指针当前位置，不再「手指落下指针跳到脚下」。换算基准为视图全宽=桌面全宽
（灵敏度 1.0），慢速滑动用小数累积取整，逐次 toInt() 会静默吞掉位移。

长按右键（Q5=A）：>=500ms 且位移 <12dp；触发后抑制本次 ACTION_UP 的左键，
否则一次长按会「先右键再左键」把菜单立刻点掉。超过 slop 立即转拖拽并取消计时，
所以拖窗口不会弹菜单。双指右键路径保持不变。

真机暴露并修复（N19）：切到远控面板后软键盘仍绑在已隐藏的表单 EditText 上
（dumpsys 里 mServedView 指向 EditText、mInputShown=true），键盘盖住面板底部
按钮栏，**所有按钮点不动**——3b 新增的模式/灵敏度按钮把它暴露出来。改为对每个
表单输入框显式 hideSoftInputFromWindow。

新增右键计数器：长按后紧跟的 ACTION_UP 会覆盖一行式诊断文本，验收脚本读不到
「长按右键」；计数器持久且能区分长按/双指来源。
 2026-10-31 17:35:11 +08:00
郑博文
3773a0851c feat(viewer-core,android-ffi): 相对位移上行链路 + 桌面像素级 proof 
viewer-core 新增 send_mouse_rel（零位移不占消息：手指静止时 ACTION_MOVE
每帧都发，空事件只会白占 QUIC 帧）。
android-ffi 新增 nativeSendMouseRel，JNI 符号 13 -> 14，Int 入参 clamp 到 i16
而不是回绕（回绕会让指针跳到屏幕另一侧）。

新增 examples/rel_mouse_proof：走完整链路（viewer-core -> QUIC -> agent 注入
-> GetCursorPos 读回）验证 V-B1a/b/c。判据是「位移恰好等于请求值」，不是
「大概动了」——因为被推翻的 MOUSEEVENTF_MOVE 方案正是「看起来能动但比例错」。
运行前后记录并还原光标位置，不污染桌面状态。
 2026-10-31 17:35:02 +08:00
郑博文
2022bbcca0 feat(agent-core): InputInjector 新增 mouse_move_rel 默认实现与分发 
默认实现不注入但打印日志（与 v3 的 text() 同一条纪律）：Linux/X11 后端本轮
未实现相对移动，用户用相对模式操作 Linux 被控端时「指针纹丝不动」不能是静默的。

相对事件不得被降级成绝对移动——单测显式断言默认实现不产生任何注入调用
（否则 Linux 端会把「相对增量」当成「绝对坐标」解释，指针乱跳）。
 2026-10-31 17:35:02 +08:00
郑博文
78ac9d9972 feat(agent): 相对鼠标注入（读光标+增量+clamp 绝对注入）+ 显式 DPI 感知 
注入实现刻意**不用** SendInput(MOUSEEVENTF_MOVE)：实测该路径的 dx 不是
像素而是 mickey，会被「指针加速」与「DPI 缩放」双重放大——本机 dx=1 走 0px、
dx=20 走 41px、dx=100 走 309px，且倍率随用户系统设置与机器变化，无法标定。
改为「GetCursorPos + 增量 + clamp + 绝对注入」，实测 1:1 精确（±1/2/3/5/17/100
四次重复全部等于请求值），撞边后回滑立即响应、不积步数债。

同时显式设 PER_MONITOR_AWARE_V2：实测本机 agent.exe 虽是 per-monitor，
但那是注册表 AppCompatFlags\\Layers 里一条**路径绑定**的 HIGHDPIAWARE 覆盖
造成的（同一 exe 复制到 %TEMP% 启动即变 UNAWARE），换机器/换构建路径即失效。
UNAWARE 时 GetCursorPos 返回逻辑坐标（1536x864）而采集是物理像素（1920x1080），
clamp 上界与增量尺度都会错。设置失败时区分「已被外部设定」与「真正降级」并分别报日志。
 2026-10-31 17:34:54 +08:00
郑博文
39af42e1b3 feat(common): 协议 v4 新增 MouseMoveRel 相对鼠标事件 
v4 新增 InputEvent::MouseMoveRel{dx,dy}，单位为被控端桌面物理像素，
语义是「把远端指针从当前位置移动 (dx,dy)」，越界由被控端 clamp。

为什么必须升版本：bincode 按位置编码枚举判别符，新增变体会改变其后
变体的编号，旧端会静默错解成别的输入事件。v4 后旧 v3 端由 Auth 握手
显式拒绝（已用 v3 二进制实测：client=3, server=4）。

为什么单位是像素而不是归一化增量：AuthOk 已下发桌面宽高，主控端换算
一次即可；被控端拿到像素可直接与 GetCursorPos 同尺度相加，少一次取整。

单测锁住：版本号、负值往返（i16 全范围）、与绝对 MouseMove 不混淆。
 2026-10-31 17:34:47 +08:00
郑博文
114e8431a6 test(android-3a): 连接生命周期 proof 入仓 + 四个 proof 的主机默认值跟上环境 
新增 tools\connect_lifecycle_proof.ps1（V-A1a/A1b/A2/A3/A4/A5 + 一键重连，
含 keep-awake、tap 前唤醒、期望文案码点从 Kotlin 源提取）。
四个既有 proof 的 -PhoneIp 默认值 .180 -> .110（2026-10-31 办公网实测；
stale 默认值曾静默吃掉一次 proof 运行，注释写明 DHCP 需按需传参）。
capture_evidence 的 192.168.1.199 保持不变——那是 V5 故意不可达的路径。
 2026-10-31 15:57:57 +08:00
郑博文
3891c970eb fix(android): 等待中的取消入口落在面板按钮上（连接后表单被隐藏） 
真机 V-A1b 实测发现：startConnect() 切到远控面板后，表单上的按钮不可见，
「点取消」没有可点的目标。把底部按钮在 connecting 态显示为「取消」并共享
cancelConnect() 一条路径（两个入口一个语义），成功后复位为「断开」。
APK 重装后 proof step 3/4 通过（连接已取消文案 + 3.9s 回表单）。
 2026-10-31 15:54:48 +08:00
郑博文
bb3cf6b09b test(android): JUnit 测试基础设施 + 19 个纯逻辑单测（3a/U7，Q3=A 批准） 
仅 testImplementation junit:4.13.2（测试作用域，不进 APK，runtime deps 仍空）；
versionName→0.1-phase3a。覆盖：WinScancode 映射表（右 Shift 非扩展/UNKNOWN 落 null/
F 键值钉死待 U6）、ConnectErrorText（每类中文非空、编号契约、未知不猜）、
planBackspaces（(0,0)/(after>0)/截断 64）。含 mutation 反向验证：断言写反即红。
 2026-10-31 13:30:07 +08:00
郑博文
718b66617f feat(android): 连接状态机 + 取消/断线回表单 + 错误中文映射 + HUD fps（3a） 
- ConnectFailure(kind,detail) + ConnectErrorText：编号→中文可执行提示，原始英文第二行
- sessionGeneration 代际：取消/断开/退出作废在途回调；等待中按钮变「取消」即时回表单
- 断线可见：取帧 null 回表单显示原因 + 「重新连接」（修「冻结在已连接」）；destroy 只在 UI 线程
- BACK 语义补连接中：取消而非关 Activity（修悬挂会话）
- 键盘按钮可见时收起（补唯一收起入口）
- HUD 1s 窗口 fps；触摸/按键诊断去坐标去内容（V-A5，proof 不依赖这些字符串）
- RemoteInputConnection 退格决策抽纯函数 planBackspaces（为 JVM 单测，语义不变）
 2026-10-31 13:30:07 +08:00
郑博文
f28db050fb feat(android-ffi): nativeLastErrorKind 出口带错误分类（3a） 
LAST_ERROR 槽位改存 (kind, detail)，新增 nativeLastErrorKind()；FFI 契约
kind 先取、message 后取（消息读走清空槽位）。kind 编号与 viewer_core::
ConnectErrorKind::code 一致，跨 FFI 只传整数。JNI 符号 12→13 全部导出（字节扫描核）。
 2026-10-31 13:29:48 +08:00
郑博文
4eb82f9779 feat(viewer-core): 连接失败分类 + 短预算×有限重拨（3a/U8） 
ConnectErrorKind（Resolve/Timeout/Refused/Auth/Version/Other）在 Rust 侧分类，
Kotlin 只做编号→文案映射。分级预算：第一拨握手 5s（快速判不可达）、重拨拨 8s
（接住 agent 串行 accept 的僵尸释放 ~10.2s）、认证 11s、全程 14s 封顶。
is_retryable 只对 Timeout/Refused 重拨；Resolve/Auth/Version 确定性失败不拖慢。

判据演进（偏差 D2/D3，用户 2026-10-31 裁决方案①）：单次 5s 总预算在串行 accept
架构下把合法排队压断（text proof 实爆），故改重拨。不可达 32s→~13s 且全程可取消；
僵尸重连第一拨 5s 失败第二拨 10.2s 自动成功（桌面 e2e 实测）。9 单测锁分类/预算/重拨。
 2026-10-31 13:29:48 +08:00
郑博文
99ffffa393 test(android-2b): 真机 emoji 人工验收工具 + 链路 proof 参数化主机地址 
V7 设备侧此前转人工，原因是 IME 的 emoji 面板对 uiautomator 不可见、adb 无法
驱动。工具只负责准备接收窗口并读回**实际到达的码元**，点 emoji 由人完成——
判据仍是真实字节，不是截图。

真机实测通过：靶窗收到 U+D83D U+DE02 -> U+1F602，两个 code unit 相邻成对、
无 U+FFFD。这证明手机 IME 把增补平面字符作为一次 commitText 送出，协议 v3
保住了代理对相邻性。至此 V7 双侧都有证据。

同时修掉 phone_chain_proof 里硬编码的 192.168.1.180：本机 LAN 地址变成
192.168.1.110 后，表单连接打向旧地址超时，看起来像产品缺陷，实为脚本过期。
改为从 -PhoneIp 参数逐字符生成 keyevent，并在断言里比对实际输入值。
 2026-10-31 11:08:16 +08:00
郑博文
8993a38658 fix(android): BACK 键改用自测键盘可见性——isAcceptingText 会让会话永远断不掉 
真机实测（vivo S6 + 讯飞，2026-10-30）：软键盘已隐藏、mInputShown=false，
但 imm.isAcceptingText 仍返回 true——只要 InputConnection 还绑着它就是 true。
原先用它判断「先关键盘还是先断会话」，后果是第一次 BACK 空转，第二次也进不来
（我们已 return true），会话再也断不掉。这不是推测，是完整链路 proof 跑到
step 5 时实测失败的。

改为自测：比较根窗口可见区域与窗口高度，被 IME 吃掉超过 15% 视为可见；
用 OnGlobalLayoutListener 被动跟踪（没有公开 API 能直接查询，API 34 上
getInputMethodWindowVisibleHeight 也不是公开接口）。阈值用比例不用固定像素。

验证：diag 依次显示「键盘可见」→「键盘隐藏」→ 会话断开回表单；
随后完整链路 proof 与中文 proof 均复跑通过。

同时修正 phone_chain_proof 的 V4 断言：uiautomator 属性顺序是 text= 在
class= 之前，原正则要求反序，导致打印空表单行仍判 PASS（假绿）。
空 EditText 的 text 会回显 hint，所以判据改为比对实际输入值。
 2026-10-30 13:31:28 +08:00
郑博文
9792662181 test(android-2b): 真机中文候选词 proof——拼音组词经 commitText 落到 Windows 
V6 的判据是「手机中文输入法能把汉字送进远端」，此前只能靠人手点候选词。
实测发现两条关键事实，决定了 proof 的可行形态：
1. adb keyevent 相当于物理键盘输入，中文 IME **不组词**，字母原样透传到
   Activity.onKeyDown——所以驱动候选词必须用 adb input text（走 IME）。
2. IME 自己的按键视图对 uiautomator 不可见（dump 里只有我们 App 的 15 个节点），
   中/英切换按钮读不到坐标，只能按截图标定一次点击位；且该按钮**有状态**，
   于是写成幂等重试：先试，只收到字母才翻转模式再来一次。

跑通结果：讯飞拼音 nihao + 空格 -> commitText 2u -> 靶窗收到 U+4F60 U+597D。
这补上了方案风险 R1（vivo ROM + 第三方中文 IME 行为未观测）的核心一环。
 2026-10-30 13:15:27 +08:00
郑博文
0089ae86e1 test(android-2b): 真机 IME 提交 proof 与字节安全证据采集 
ime_commit_proof 补上 phone_chain_proof 没覆盖的那半段：IME **显示**状态下
按键被输入法消费，只有 RemoteInputConnection.commitText 能到达我们——这正是
方案风险 R1（vivo ROM + 第三方中文 IME 行为未观测）此前唯一没有证据的点。
真机实测：mInputShown=true、mHaveConnection=true、状态栏 commit 2u、
Windows 靶窗收到 Hi（讯飞把首字母自动大写，属输入法行为，不是链路缺陷）。
back 键第一次只关键盘不断会话，也在这支脚本里断言。

shot.ps1 / capture_evidence.ps1：PS 5.1 的 '>' 以 UTF-16 写文件，
'adb exec-out screencap -p > x.png' 产出的 9 张证据图首字节全是 FF FE，
全部不可用；改为设备内 screencap 落地再 pull，并校验 PNG 签名。

V5 等待预算 30s→50s：不可达 IP 实测 32s 才回表单报 timed out，
预算过小会把「仍在超时中」误判成验收失败。
 2026-10-30 13:06:08 +08:00
郑博文
9f0b0742a8 feat(android): 键盘事件双通道 + 手机到 Windows 全链路 proof 
真机暴露出 IME/按键通道的缺口，一并补上并证明：
1. RemoteInputConnection.sendKeyEvent 与 Activity.onKeyDown 都先处理**可打印**
   unicodeChar（走 v3 Text 通道），再退到扫描码查表。原先只查表：软键盘发的是
   keyCode=UNKNOWN + unicodeChar，查不到表就被当未映射键吞掉，字整个丢了。
   门槛排除控制值（Enter/Tab）——远端应用要的是按键事件而非 WM_CHAR。
2. onKeyDown/onKeyUp 补齐硬键与物理键盘路径（阶段 2 验收里的软键盘按键），
   repeatCount>0 只发一次 down，避免长按把远端消息队列刷爆。
   isAutorepeat() 是 @hide，改用公开的 getRepeatCount()（javap 核实）。
3. getUnicodeChar() 返回的是单个 UTF-16 code unit 而非码点，注释按此改正：
   BMP 外字符由 IME commitText 成对送达，不经这条路。

tools/phone_chain_proof.ps1：手机按键 -> v3 Text -> agent SendInput -> 自有
Windows 靶窗自报内容，全链路一次跑通（真机 vivo S6 实测 abc 到位、ENTER 走
scan 28、BACK 断开回表单、表单 UI 重连成功）。要点：
- 靶窗必须自报窗口句柄（pid+hwnd 两行），Get-Process 取 MainWindowHandle 有竞态；
- 不能用 keybd_event(VK_MENU) 破前台锁：ALT 之后的首个字符被当菜单助记键吞掉，
  实测三个字符只剩 b；改用 AttachThreadInput + SetForegroundWindow，不合成按键；
- 退役遗留靶窗只能 touch 已存在的 stop.flag：新建会命中即将启动那次的停止路径，
  靶窗刚起就自杀（实测 pid 报了又消失）；
- adb 进度信息走 stderr，PS 5.1 + ErrorActionPreference=Stop 会当终止错误，
  按 build-android.ps1 同款办法临时放宽并只看退出码。
- 表单填字用 keyevent 而非 adb input text：设备只有第三方中文 IME，text 注入会被
  组词（ASCII 句点变 U+3002）。跑前记录并禁用原 IME，finally 精确还原。
 2026-10-30 12:58:36 +08:00
郑博文
a93430dd3f chore(tools): 2b 注入 proof 路径随仓库位置推导，缺失参数报错文案改正 
proof 脚本原先硬编码 D 盘绝对路径，换机器就失效；仓库内已有同约定
（build-android.ps1 用 \ 推导），此处对齐。
text_check 的报错文案说「为空」，实际触发条件是 --units 缺失，改正。
 2026-10-30 12:21:19 +08:00
郑博文
79e3e77c97 fix(android): windowSoftInputMode=adjustPan——软键盘弹出不再踢掉会话 
默认 adjustResize 会缩小窗口高度，SurfaceView 随之收到 surfaceDestroyed，
而现有回调把 surfaceDestroyed 当作「断开」处理——等于用户一点键盘输入，
2a 验收过的会话就自己断了。真机首验前先做这道防御；adjustPan 只平移窗口，
不改变 surface 尺寸。合并后的 manifest 已核对（android:windowSoftInputMode 存在）。
 2026-10-30 12:17:20 +08:00
郑博文
8ffe19cd5f test(agent-core): v3 分发路径单测——默认后端不 panic、截断契约、空输入 
新功能必须带测试，agent-core 此前无测试模块，v3 新增的 text 默认实现与
截断分支正好落在盲区里：

- 后端不实现 text() 时（Linux/X11 的真实形态）必须被正常调用且不 panic；
- 超 MAX_TEXT_UNITS 必须以截断后的长度到注入侧，未超限原样；
- 空 Text 仍会下发到后端——被控端不假设对端守规矩，线格式输入按不可信处理。
 2026-10-30 12:11:28 +08:00
郑博文
936986a940 test(android-2b): 文本注入真边界工具——viewer-core 直发 Text，靶窗自报收到内容 
text_check 走的是产品同一条路径（Session::send_text → v3 线格式 → agent
SendInput KEYEVENTF_UNICODE），手机掉线也能先把 Windows 半段验实。
参数是十进制 code unit 列表而不是自然语言字符串：命令行到 Rust 的编码往返
会引入与本轮无关的变量，由 PowerShell 从 .NET 字符串取 char[] 更忠实。

proof 脚本刻意用自有 WinForms 靶窗而非记事本：Win11 记事本所有标签页同进程，
本机当时开着用户文档，往里注入等于改用户文件。靶窗自报文本（写文件），
判据不依赖截图和 OCR。注入前后各断言一次前台窗口——SendInput 打的是前台，
靶窗不在前台时的注入会进别的应用，宁可失败也不误注入。
 2026-10-30 12:09:48 +08:00
郑博文
6c28a3f7e3 feat(android): 阶段 2b——连接界面 + IME 文本通道 + 控制键扫描码 
两态 UI：连接态是 host/port/code 表单（原生 View 零依赖，intent extras 保留且
优先，构建脚本不受影响），成功后切远控态。只存 host/port；验证码不落盘（用户裁决）。
返回键分态：IME 显示时先收键盘，否则断开回表单——否则一次返回关键盘又杀会话。

IME 走 P1：onCheckIsTextEditor + BaseInputConnection 子类。commitText 整段
经 v3 Text 通道上行（char[]→GetCharArrayRegion，UTF-16 无损）；控制键映射
Set-1 扫描码（值与 viewer/keymap.rs 同源，右 Shift 按官方文档不置 extended）。
composing 不上远端（U4），getText* 回空串——本地没有也不伪造远端缓冲区。

键盘按钮显式 showSoftInput，不自动弹（vivo 行为不一致 + 挡画面）。
RemoteSurfaceView 补 isFocusableInTouchMode：没有它触摸态拿不到焦点，
InputConnection 根本不会建立（2a 弹不出键盘的根因之一）。
 2026-10-30 11:51:01 +08:00
郑博文
55cc8edbc1 fix(agent): 文本注入改为单次 SendInput 批量——按官方文档消除事件被打散的风险 
实读 Keyboard Input Overview 后修正两处凭记忆的实现：
1. 原文承诺「单次调用的事件不会被其他输入插入」，此前拆成 down 批 + up 批
   两次调用，两次之间可能夹进真实键鼠事件，代理对存在被拆开的风险。合并为
   一次提交（全部 down 紧接全部 up）。
2. KEYBDINPUT 文档「只能与 KEYEVENTF_KEYUP 组合」那句按推断写成结论；
   改为如实标注为推断，并写明真机失败时的退路（只发 UNICODE|KEYUP 单事件）。
 2026-10-30 11:41:54 +08:00
郑博文
174a3f8ac0 feat(viewer-core,android-ffi): 主控端文本上行与 JNI 入口 
Session::send_text 收 &[u16] 而不是 &str：整条链（Java 字符串 → JNI → 线格式 →
Windows 注入）的原生表示都是 UTF-16，任何一次 UTF-8 往返都有损，故中间层不做转换。
空输入与超限在本层拦掉，超限走 clamp_text_units 并打日志。

nativeSendText 的参数用 char[]（JObject 收再转 JCharArray），经 GetCharArrayRegion
按 u16 直接拷贝。不用 JString + get_string：jni 0.21 那条路走 Modified-UTF-8，
IME 提交边界的落单代理项会在往返里丢。JNI 取数失败必须 eprintln，不能静默——
用户对着远端打字最坏的情况是「看起来发送了」。
 2026-10-30 11:41:53 +08:00
郑博文
5075888861 feat(agent): v3 文本注入用 KEYEVENTF_UNICODE，一次批量提交成对代理项 
Windows 侧按官方 KEYBDINPUT 语义实现：置 KEYEVENTF_UNICODE 时 wVk 必须为 0、
wScan 即要送出的字符，系统合成 VK_PACKET 经 TranslateMessage 产出 WM_CHAR。
down 批与 up 批分两次 SendInput，且让同一段文本的 code unit 在输入队列里相邻，
使代理对能被远端合成一个字符（最终由真机 emoji 验收定论）。

agent-core 的 InputInjector::text 用默认实现记日志而非静默忽略：Linux 后端
本轮不做文本注入（X11 需 keysym/XKB 映射，另立循环），但用户对着 Linux
被控端打字不能「什么都没发生还没痕迹」。Windows 端走自己的 handle()，
不经 agent-core，故超限截断日志在两侧同源补齐。
日志只打长度，不打用户输入内容。
 2026-10-30 11:29:25 +08:00
郑博文
38df106fb6 feat(common): 协议 v3——新增 InputEvent::Text 文本注入通道 
安卓软键盘的中文候选词结果不是扫描码，扫描码通道对中文天然不通，必须
另开一条按字符注入的通道。载体选 Vec<u16>（UTF-16 code unit）而非 String：
Windows 注入侧与 Java 字符串原生都是 UTF-16，中间任何一次 UTF-8 往返都会
把 IME 提交边界的落单代理项变成替换字符。

InputEvent 因携带 Vec 不再是 Copy，调用方改用 clone；三端必须同步升级，
旧端由 Auth 握手显式拒绝（这正是 PROTO_VERSION 递增的目的）。
新增 6 个单测覆盖 roundtrip、落单代理项、上限边界与 1MiB 长度闸共存。
 2026-10-30 11:29:13 +08:00
郑博文
5079d33b0a fix(agent): 显式 max_idle_timeout=10s——强杀主控端后 10 秒内可重连 
问题（实测复现）
串行 accept 下，主控端被强杀（force-stop，非正常 close）时 QUIC 连接
不会立即消亡：agent 还在向死连接发帧，新连接只能排队，要等 quinn 默认
idle 超时（约 30s）才能建立。表现为「杀掉 App 重开，一直连不上」。

修法
TransportConfig 显式设 max_idle_timeout=10s。正常会话每 500ms 一个 Ping
永不触发该超时，只回收死连接。10s = 20 个 Ping 周期，抗抖动余量足够。

验证（vivo S6 实测）
- 会话1 auth ok -> force-stop App -> 立即重连
- 10.2s 后 peer connected + auth ok（修复前 ~30s）
 2026-10-30 10:38:04 +08:00
郑博文
fe558a1c1e feat(android): 状态栏触摸诊断通道（vivo logcat 被限流的对策） 
本机（vivo S6 + 办公 Windows）logcat 只能抓到 4 行，App 日志完全不可靠，
排查触摸/坐标问题时没有任何可用通道。

- RemoteSurfaceView 加 onDebug 回调：ACTION_DOWN/MOVE/UP 的视图坐标与
  发出的 norm 归一化坐标实时上报
- MainActivity 统一 refreshStatus()：连接态 + 帧数/RTT + 最近触摸合并成
  一处刷新（原来 8 处各自 statusView.text 互相覆盖，且引用过已删的 showHint）
- 删掉临时步骤标记与 lastMeasureInfo（诊断价值已被 onDebug 覆盖）

实测：状态栏正确显示 UP view=(643,222) norm=(39017,23968) 1080x607，
据此确认了 letterbox 视图尺寸与归一化换算全对，把排查焦点正确引向
agent 注入侧（VIRTUALDESK，已另行修复）。
 2026-10-30 10:35:21 +08:00
郑博文
6a6f989595 fix(agent): 绝对坐标注入去掉 VIRTUALDESK——注入空间与采集空间对齐 
根因（实测确认）
capture 用 EnumOutputs(0) 只采**主屏**，AuthOk 报告的 width/height 也是主屏；
但 input 注入带 MOUSEEVENTF_VIRTUALDESK，归一化 0..=65535 被映射到**整个虚拟
桌面**。双显示器机器上虚拟桌面（主屏 2560x1440 + 副屏 1920x1080 在左）比主屏
宽得多，手机画面与指针位置系统性错位——点主屏任务栏，指针落到别处。
单显示器时两个空间重合，所以桌面 viewer 联调从未暴露。

修法
MOUSEEVENTF_ABSOLUTE 不带 VIRTUALDESK 时，0..=65535 恰好映射到主显示器，
与采集空间一致。协议注释「鼠标坐标为虚拟桌面归一化」的语义由「整个虚拟桌面」
修正为「被采集的输出」——桌面 viewer 是绝对定位透传，行为不变。

验证（vivo S6 -> 本机双屏，修复后）
- 手机拖微信标题栏：窗口跟随手指移动（drag-before/after 截图对比）
- App 状态栏 norm 坐标与视图坐标换算一致（view=(643,222) norm=(39017,23968)）
 2026-10-30 10:30:53 +08:00
郑博文
5047618c01 feat(android): 触摸映射 + letterbox 显示（阶段 2a 代码部分） 
问题：阶段 1 的 SurfaceView 用 MATCH_PARENT，2560x1440 的视频被拉进
1080x2400 竖屏，画面变形。变形状态下手指位置与远端指针不再一一对应，
触摸映射无从谈起。所以两者必须一起做。

新增 RemoteSurfaceView
- onMeasure 按视频宽高比 letterbox：视图尺寸 = 画面尺寸，黑边不属于视图，
  触摸天然只在画面内产生事件，坐标归一化到 0..=65535 才准确
- 手势：单指轻点=左键、单指拖动=左键拖拽、双指轻点=右键、双指滑动=滚轮
- 刻意不做「手指即光标」的绝对跟随：手指会完全挡住目标，精细操作不可用
- 边界处理：进入拖拽后落下第二指，先抬起左键再切双指手势，
  否则远端会留下一个被按住未释放的按键

协议侧（不改线格式，只加只读查询）
- viewer-core::Session 记录 AuthOk 的桌面尺寸，新增 desktop_size()
- android-ffi 新增 nativeDesktopSize(handle) -> i64（高32=宽，低32=高）
- RustBridge.desktopSize() 拆包
- 尺寸必须在建解码器之前拿到：等首帧再改视图尺寸会触发重新测量，
  把刚创建的解码器 surface 打掉

MainActivity
- 接入 RemoteSurfaceView.Listener；连接成功后先取尺寸设宽高比，再起解码线程
- 返回键 = 断开（不退出 App，便于重连）；去掉阶段 1 的双击断开
  （双击现在语义上是「两次左键点击」，会和远端交互冲突）

验证：cargo build --workspace 通过；cargo test 全绿（common 20 + viewer-core 3）。
真机手势验收待手机重新连接后补。
 2026-10-30 09:51:38 +08:00
郑博文
f119300a57 feat(agent): 串行多会话——会话结束不再退出进程 
问题（阶段 2 的硬阻塞）
accept() 只接一次，会话结束进程退出。阶段 1 一次验收看不出来，
但阶段 2 要反复测试输入，每测一次都要手动重启被控端。
（即公共阻碍清单里的 P5，此前判断为「只影响调试效率」，
 现在它阻塞迭代，提前做掉。）

改动
1. main：会话体抽成 serve_session()，外层 accept 循环。
   会话失败（含认证失败）只记日志不退出进程。
   明确不做并发多会话：DXGI Desktop Duplication 每个输出仅允许一个
   活动实例，第二个 DuplicateOutput 会让第一个收到 ACCESS_LOST。
2. 认证失败路径补 conn.closed() 等待（agent-core 已有同款修复，
   此处同源补齐 = 手册 §6.1 第 1 条）：否则客户端只看到 connection
   lost 而不是 AuthFail。
3. capture 循环加 tx.receiver_count()==0 守卫。
   只靠「send 失败退出」不够——桌面完全静止时那个分支根本不发送，
   线程会永远持有 duplication，下一个会话的 DuplicateOutput 直接失败
   （表现为新会话黑屏）。agent-core 同源修复。
4. 会话收尾：finish 流 + drop 接收端 + 等采集线程退出（2s 超时）后才
   返回，调用方才 accept 下一个连接。

验证（连续两个会话，中间不重启 agent）
  会话1：收到帧 40/40，结论 ✅
  agent 存活：✅
  会话2：收到帧 40/40，结论 ✅
  日志：session closed -> waiting for next connection -> peer connected
        -> auth ok；stderr 有 [capture] no receiver, stop 证明线程真退出
 2026-10-30 09:31:44 +08:00
郑博文
58bb66f4c2 feat(android): 阶段 1 安卓主控 App 工程（已真机验收出画面） 
Kotlin 层三个文件（刻意零第三方依赖，纯 View 布局——阶段 1 只验证链路）：
- RustBridge.kt：android-ffi 的 JNI 声明 + 帧头拆解（25 字节定长头 + Annex-B 载荷）
- H264Decoder.kt：MediaCodec 同步模式 + Surface 直出；内置两条实测教训——
  只用 getInputBuffer(i)（Exynos Quirk）、awaitingIdr 状态机（R-3 跳帧断参考链）
- MainActivity.kt：连接/解码循环/触摸绝对坐标映射；断开顺序遵守
  「先停解码线程 join 后 destroy」的 FFI 纪律

构建链（build-android.ps1，一条命令：cargo ndk -> .so -> gradle assembleDebug -> 安装启动）：
- 路径自适应（ 定位仓库根），local.properties 自动生成
- gradle.properties 固定 JDK 17，不动全局 JAVA_HOME

真机验收（vivo S6 / 192.168.1.163 -> PC / 192.168.1.180:47800）：
- agent 日志：peer connected + auth ok, desktop 2560x1440
- 手机截图：Windows 桌面（WPS 文件列表）已渲染在 SurfaceView 上
  证据：evidence/screen-connected.png（本地，不入库）

已知环境限制（记录在个人层 baseline）：本机 Windows 防火墙的 agent.exe
程序级放行规则对 UDP 入站不生效（临时关防火墙即通），QQPC 驱动级防护
静默拦 TCP 入站（管理员无法停止/杀死）。阶段 2 前需落定长期方案：
端口级防火墙规则或换开发机。
 2026-10-29 19:59:43 +08:00
郑博文
64d497e577 test(viewer-core): headless_check 增加 --host，可指定被控端地址 
默认仍 127.0.0.1。加 --host 后能用局域网 IP 跑同一验收，
便于排查「桌面通、手机不通」这类只影响入站路径的问题
（注：本机回环连接不经过防火墙，只有跨主机连接才验证防火墙路径）。
 2026-10-29 19:18:11 +08:00
郑博文
44767ed370 feat(android-ffi): viewer-core 的 JNI 薄层，arm64 交叉编译通过（QUIC 栈上手机的第一道关） 
方案变更说明（A2 落地修正）：原裁决选 UniFFI，但实查 Maven Central 与
maven.mozilla.org 均无 uniffi Kotlin 运行时构件（404），自编译发布成本超过收益。
改为裸 JNI：阶段 0（真机）已验证该链路，接口刻意保持窄（连接/取帧/发输入/销毁），
将来若引入 UniFFI 只替换本层。

线程与锁纪律（决定接口形态）：
- nativeNextFrame 等帧期间不持会话锁（clone Arc<Session> 后即释放），
  桌面静止 500ms 帧间隔不会卡住 UI 线程的输入调用
- destroy 前必须先停解码线程，Kotlin 侧顺序纪律保证（已登记风险清单）
- 句柄 = Box 裸指针（永不为 0），destroy 后置 0

帧返回约定：byte[] = [keyframe 标志 1][seq 8][ts 8][w 4][h 4][Annex-B payload]，
定长 25 字节头，Kotlin 切片零 JNI 往返。

viewer-core 适配：Session.frames 改 Arc<tokio Mutex>，next_frame 取 &self，
使解码线程与输入线程可并发借用同一 Session。

验证：
- 桌面 cargo build -p android-ffi 零警告
- cargo ndk -t arm64-v8a --release：quinn/ring/rustls 交叉编译全部通过
  （消除阶段 1 最大未知：QUIC 栈能否编到 Android）
- libandroidffi.so 4.2MB，10 个 Java_com_verify_remote_RustBridge_* 符号导出正确
 2026-10-29 18:27:34 +08:00
郑博文
34df7b070b feat(viewer-core): 新增安卓主控的连接/协议/收帧层（阶段 1 桌面验证通过） 
定位（2026-10-29 方案裁决 A1-A4）：
纯 Rust、平台无关，只做「怎么连 + 收发什么」——QUIC 会话、协议 v2 认证、
视频帧流、输入上行、Ping/Pong、KeyFrameReq。解码/渲染/触摸全在 Kotlin 侧，
本 crate 不碰像素、不依赖 openh264（dev-dependency 仅验证工具用）。

设计要点
- PeerTarget::Direct 是唯一的连接形态；不做中继、不定义 Relay 变体
  （《多平台架构设计》§6.1 裁决）。将来设备码+打洞只换 connect() 内部。
- 帧经容量 2 的 mpsc 交付，**不丢帧**：跳帧决策属于看得到解码器状态的消费方
  （Kotlin），Rust 层丢帧会重演 R-3 教训（跳帧断参考链）。
- insecure_skip_verify=false 时明确报错而非静默放行——证书钉扎登记在方案
  阶段 4，安全红线不允许默默降级。
- 双流结构与桌面 viewer 一致（流1 认证+视频，流2 输入+控制），入会即请求 IDR。

验证（headless，桌面→桌面 127.0.0.1）
- 单测 3 passed（帧契约、默认配置、strict-verify 显式报错）
- examples/headless_check：300 帧，seq 违例 0、keyframe 标志不符 0、
  解码成功 300/300、RTT 路径工作（RTT=1ms 出现）
- 全 workspace 回归：common 20 passed，构建全绿
 2026-10-29 18:14:27 +08:00
郑博文
1837658c85 test(agent): dump_stream 增加 --save，可导出裸 H.264 码流供外部解码器验证 
目的
安卓主控方案的唯一高风险未知项是「agent 发出的码流能否被 MediaCodec 解码」。
要验证它，需要一份脱离 QUIC/自定义帧头的**裸 Annex-B 码流文件**，供手机端
或任何标准解码器直接读取。

改动
- 新增 --save <路径>：把各帧载荷按到达顺序拼接成 Annex-B 文件
- 存的是**载荷**而非完整帧：外部解码器只认标准 Annex-B，不认识本项目的
  长度前缀与 bincode 帧头，故不能存 encode_video_frame 的输出
- 保存时打印字节数与 IDR 数量，便于快速判断样本是否可用

不做的事
不引入独立的码流解析库，IDR 统计复用文件内已有的起始码扫描逻辑，
避免为一次性诊断工具增加依赖。

验证
cargo build --workspace 退出码 0；cargo test --workspace --exclude linux-agent 全绿。
实际使用：导出 90 帧、437823 字节、含 2 个 IDR，该文件已用于安卓 MediaCodec
兼容性验证（vivo S6 / Exynos 硬解，87/89 帧解出）。
 2026-10-29 16:13:58 +08:00
郑博文
6e83bda8b8 perf(agent): 关键帧周期从 4s/10s 统一到 1s，缩短丢帧后的兜底恢复窗口 
背景
协议 v2 与 vendor nvenc 补丁之后，KeyFrameReq 已成为**真正生效**的恢复主路径
（此前 NVENC 缺 FORCEIDR 标志，请求被静默忽略）。因此周期 IDR 的角色变了：
从「唯一恢复手段」降级为「兜底手段」，只用于防「请求连续丢失」这种极端情况。
既然是兜底，就没必要配得那么长。

问题：三处周期不一致，且都过长
- agent/src/capture.rs NVENC：gop_len = 240 帧 @60fps = 4 秒
- agent/src/capture.rs 软编：    intra_period = 300 帧 @60fps = 5 秒
- agent-core/src/lib.rs Linux：  intra_period = 300 帧 @30fps = **10 秒**

同一产品在三种编码后端上的恢复等待时间差 2.5 倍，且 Linux 端最差。

改动
- 新增 agent/src/capture.rs::INTRA_PERIOD_FRAMES = 60（Windows 两个编码器共用）
- agent-core 的 EncoderSettings::default() 改为按 max_fps 推导（1 秒对应帧数），
  避免以后调帧率时周期又漂移

代价
IDR 是整帧内编码，实测一次约 95-120KB，而 P 帧约 3-10KB。1 秒一次 IDR 约
增加 0.8Mbps 开销，在 5Mbps 码率下可接受。

验证（dump_stream 观察 150 帧）
  [  0] seq=0   IDR   ← 首帧
  [ 60] seq=60  IDR   ← 间隔精确 60 帧
  [120] seq=120 IDR
@60fps 即每 1 秒一个自动 IDR，与 gop_len=60 配置一致。
 2026-10-28 16:35:44 +08:00
郑博文
8410a8de2a docs: 记录「不做中继」的最终裁决（2026-10-28） 
背景：公司决定不提供中继服务器，中继方案从「暂缓」变为「排除」。

《多平台架构设计.md》
- §6 从「⚠️ 必须现在拍板」改为「✅ 已裁决」，保留原始分析但标注结论
- 新增 §6.1 裁决内容：不做中继、不预留中继接口、IPv6 一等公民、
  连接层边界仍要做
- 新增 §6.2 澄清一件常被混淆的事：**连接层边界 ≠ 中继接口**
  - 连接层边界（把「怎么连」与「连上干什么」分开）：要做，与中继无关，
    因为连接方式确定会变（IP→设备码）、安卓端要复用、解码逻辑要可单测
  - 中继接口（Path::Relay 这类类型预留）：不做。中继已排除，这些变体
    永远不会被构造，只会产生 dead_code 警告——零收益的预留就是纯负担
- 新增 §6.3 对产品的影响：明确哪些网络环境连不上，并说明这不是 bug
  而是已知边界，UI 必须给出可执行提示
- §10 第 1 条标记为已裁决

《打洞与信令设计.md》
- 状态更新为「已合入 main（703eb64）」
- 补充裁决确认，指向 §6.1/§6.2

补充事实：此前代码中并不存在 PathProvider / Path::Relay，唯一提到 relay 的
signaling.rs:7 是在声明「本协议不含中继」。因此本次是「确认不留」而非
「拆除预留」。
 2026-10-28 16:35:32 +08:00