ghost-him/zerolaunch-rs/plugin-real-verify

plugin-real-verify — 插件改动真机验证

铁律：插件改动（Rust / UI / i18n / manifest 任一）必须走完 构建 → 验产物 → 安装 → 真实操作 → 可观测结果核对 五步。只把改动文件拷进已安装目录、不打包不安装，或只有离线 harness（happy-dom 之类）结论，都不算验证完成。

宿主侧（ZeroLaunch-rs 本体）UI 验证见 dev-verify-cdp。

1. 构建产物

在插件仓库根目录执行打包脚本（内部会 cargo build --release 后打 zip）：

python package.py            # 无系统 Python 时：uv run python package.py
python package.py --no-build # 只复用现有产物、仅验证打包时

产物落在 dist/。纯 UI / i18n 改动也必须真跑一次打包——它是唯一能暴露打包脚本与 zip 布局回归的环节。

2. 校验产物（构建与安装之间最容易漏的一步）

unzip -l dist/<zip>                                  # 期望：manifest.toml 在根、bin/<exe>、ui/、i18n/，DLL 在根
unzip -o -q dist/<zip> -d /tmp/zipcheck && grep -c <本次新增的符号> /tmp/zipcheck/ui/<面板文件>

符号计数用于证明「装进去的确实是这次构建的产物」，而不是上一次的包。

3. 安装（真实路径）

宿主侧入口：设置 → 插件管理 → 从本地文件安装（zip；旁边另有「从目录安装」）。链路是：@tauri-apps/plugin-dialog 原生文件对话框（窗口类 #32770）→ 应用内预检确认弹窗 → plugin_install_local；已安装同名插件时会再弹「是否覆盖」。

• 不要让脚本用 SendKeys 驱动原生对话框：实测 AppActivate 返回 True 但按键落点不可控（一次静默失败、一次把对话框关掉）。也不要仅凭 UIA「找不到该窗口」就断言对话框没开——UIA 的 TreeScope::Children 在该对话框上有盲区，而 EnumWindows 能枚举到它。
• 优先让用户自己点、自己装；若必须自动化，用下面的等价回退并在汇报里写明用的是回退路径：

# 回退：按 zip 原布局解包到插件目录
unzip -o dist/<zip> -d "$USERPROFILE/.ZeroLaunch-rs/plugins/<plugin-id>/"

• 生效方式：宿主按 URL 缓存插件 ESM 模块。`Page.reload` 搜索窗口即可清掉面板模块缓存，比重启宿主快。拖拽安装走 webview 级 onDragDropEvent（OS 级事件，CDP 造不出来）。

4. 模拟用户操作（真实事件）

CDP 连接与启动流程见 dev-verify-cdp。插件面板相关的额外要点：

• 必须开焦点仿真：Emulation.setFocusEmulationEnabled { enabled: true }，否则 focus() 不落地、键盘事件打到 DIV 上，面板键盘处理永不触发。
• 进面板：全局热键（OS 级）CDP 打不到，用触发词唤醒——把 value 写入搜索框 + 派发 input 事件 → 等防抖 → 在候选列表上按真实 Enter。
• 面板在 Shadow DOM：.third-party-panel-host → shadowRoot → 面板内部选择器（如 #<前缀>-input、.ev-item 这类由插件约定的类名，以其前端源码为准）。
• 面板内输入用 Input.insertText（等价真实键入）；尽量不用「改 value + 派发事件」。
• 不要钩 `window.__TAURI_INTERNALS__.invoke`：该属性不可写，赋值静默失效，会让你误判「动作没触发」。断言副作用，不要断言调用。
• 焦点相关行为必须实测 document.activeElement：真实点击不可聚焦的列表项后焦点会回到 BODY，挂在输入框上的键盘处理整片失效——「点击后快捷键无效」这类问题只能靠实测定位。

5. 可观测结果核对

• 面板渲染文本（插件面板提示语、条目内容）与动作执行后的副作用。
• 资源管理器：先取基线，只核对/清理自己新开的窗口：

``powershell (New-Object -ComObject Shell.Application).Windows() | ForEach-Object { $_.LocationURL } ` 只读，**绝不要 .Quit()`**（Win11 单进程多标签会连带关掉用户其它窗口）。

• 浏览器：用窗口标题变化判断是否真的导航，不要只看进程是否存在。
• 日志：插件 %USERPROFILE%\.ZeroLaunch-rs\plugin-logs\<plugin-id>.log；宿主 %USERPROFILE%\.ZeroLaunch-rs\logs\。
• 安装生效的旁证：候选列表里插件的描述文案取自已安装包的 manifest.toml，描述变了即说明装的是新包。

6. 原生窗口取证（UIA 看不见时用它）

Add-Type @"
using System;using System.Text;using System.Runtime.InteropServices;
public class W {
  [DllImport("user32.dll")] public static extern bool EnumWindows(EnumWindowsProc cb, IntPtr l);
  public delegate bool EnumWindowsProc(IntPtr h, IntPtr l);
  [DllImport("user32.dll")] public static extern int GetWindowText(IntPtr h, StringBuilder s, int n);
  [DllImport("user32.dll")] public static extern int GetClassName(IntPtr h, StringBuilder s, int n);
  [DllImport("user32.dll")] public static extern bool IsWindowVisible(IntPtr h);
  [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
  [DllImport("user32.dll")] public static extern IntPtr SendMessage(IntPtr h, uint m, IntPtr w, IntPtr l);
}
"@
$fg = [W]::GetForegroundWindow()
$cb = [W+EnumWindowsProc]{ param($h,$l)
  if ([W]::IsWindowVisible($h)) {
    $t = New-Object System.Text.StringBuilder 512; [void][W]::GetWindowText($h,$t,512)
    $c = New-Object System.Text.StringBuilder 256; [void][W]::GetClassName($h,$c,256)
    if ($t.ToString() -or $c.ToString() -eq '#32770') { "hwnd=$($h.ToInt64()) class=$($c.ToString()) title='$($t.ToString())' fg=$($h -eq $fg)" }
  }
  return $true
}
[void][W]::EnumWindows($cb,[IntPtr]::Zero)
# 关闭自己打开的对话框（WM_CLOSE=0x0010）：SendMessage($h, 0x0010, 0, 0)

跑 PowerShell 时建议 -NoProfile -WindowStyle Hidden（必要时 -EncodedCommand 传 UTF-16LE base64），避免控制台抢前台干扰被测窗口。

7. 汇报判据

• 产物：打包脚本输出路径、zip 内文件清单（含新增符号计数）、安装方式（用户手动 / UI 装 / 解压回退）。
• 真机现象：面板渲染文本、真实按键后的副作用（资源管理器路径、浏览器标题）、对应日志行。
• 回归：改动相邻的既有按键/动作各跑一次（例：动了 Ctrl+Enter 必须复验 Enter）。
• 离线 harness 结论只算补充证据，不能替代真机验证。

8. 清理清单

1. 关掉自己打开的资源管理器窗口与外部程序；删临时标记目录与 /tmp 解包目录。
2. 若动过插件安装目录：还原为已发布内容；若是用户刻意安装新包，保持安装态不动并在汇报里说明。
3. 停掉本次启动的 dev 实例（按 dev-verify-cdp 的清理顺序，确认无残留进程与端口占用）；用户正在使用的实例保留并说明。
4. 仓库里不留一次性脚本；dist/ 产物可留（已 gitignore）。
5. 发版提醒：版本号需在 manifest.toml、Cargo.toml、git tag 三处一致。