桌面应用跨平台【免费下载链接】nativeToolkit for building native desktop apps项目地址https://gitcode.com/gh_mirrors/ze/native点击查看免费下载导读Native SDKZig 实现的跨平台桌面应用工具包仓库根目录见 README.md为每个启用自动化的应用内嵌一个自动化服务器——无论是原生渲染retained-canvas / gpu_surface应用还是 WebView 壳应用。它通过.zig-cache/native-sdk-automation/下的文件型 IPC文件投递箱协议dropbox protocol工作专为冒烟测试、带 GUI 会话的 CI 校验与快速运行时巡检设计可读取可访问性快照、沿真实输入路径驱动 retained 组件、生成确定性的参考渲染截图、做就绪/状态断言并完成桥接bridge往返。本文基于 skill-data/automation/SKILL.md并结合 src/automation/ 的源码实现给出完整、可复制的实操指南。注意这不是浏览器 DOM 自动化。它报告的是运行时/窗口/组件状态驱动 retained-canvas 组件并可以要求运行时重载或派发桥接请求。若要测试可选的 WebView 路径的 DOM请使用前端框架的测试或对 dev server 使用浏览器自动化工具。自动化能验证什么、不能验证什么能验证启用自动化的应用已启动并发布readytrue运行时加载了预期的应用名、源码类型与窗口元数据主窗口存在且处于聚焦/打开状态JavaScript↔Zig 桥接可通过native automate bridge完成一次请求往返内建窗口/WebView 命令可被冒烟测试驱动运行时接受重载请求retained-canvasgpu_surface视图的真实像素native automate screenshot view-label通过确定性 CPU 参考渲染器把视图当前 canvas 帧渲染成 PNG 产物。同一场景的两次抓取字节一致因此截图可支撑 golden-image 或“UI 是否变化”的检查。不能验证WebView 内容的截图screenshot仅覆盖gpu_surfacecanvas 视图没有 DOM/WebView 像素捕获任意 DOM 查询与点击浏览器网络断言。从快照数据模型src/automation/snapshot.zig看快照内容由Input结构体承载窗口Window、视图ViewInfo区分gpu_surface与webview两种kind、组件Widget、命令与应用菜单目录commands/menus、托盘trays、音频/视频播放状态audio/video以及诊断信息Diagnostics。这决定了“能验证”的边界正是快照里被明确建模的那些状态。前置条件如何启用自动化用-Dautomationtrue构建并运行应用。生成的示例通常直接暴露该选项zig build run -Dplatformmacos -Dautomationtrue仓库示例可能有专门步骤zig build run-webview -Dplatformmacos -Dautomationtrue zig build test-webview-smoke -DplatformmacosRunner 必须把自动化服务器传入RuntimeOptions对应 src/runtime/api.zig 中的automation: ?automation.Server字段const server native_sdk.automation.Server.init(io, .zig-cache/native-sdk-automation, My App); var runtime native_sdk.Runtime.init(.{ .platform my_platform, .automation server, });Server.init的签名见 src/automation/server.zig三个参数分别是io、投递箱目录默认.zig-cache/native-sdk-automation和用于标识的 title。未用-Dautomationtrue构建的应用通常会忽略自动化文件——自动化是编译期门控的没开选项的应用不创建投递箱目录、不发布快照、不消费命令。命令一览CLI 总入口是native automate command仓库构建版为zig-out/bin/native automate command命令表定义在 tools/native-sdk/automation.zignative automate wait native automate assert gpu_nonblanktrue rolebutton nameReset native automate assert --absent error event native automate list native automate snapshot native automate reload native automate screenshot inbox-canvas native automate screenshot inbox-canvas 2 native automate widget-action canvas 2 press native automate widget-click canvas 3 native automate widget-hold canvas 3 native automate widget-context-press canvas 3 native automate widget-drag canvas 4 0.25 0.82 native automate widget-wheel canvas 5 18 native automate widget-key canvas tab native automate widget-key canvas cmdc native automate widget-pinch canvas 1.5 native automate widget-pinch canvas 0.5 120 80 native automate profile on native automate profile off native automate bridge {id:smoke,command:native.ping,payload:{source:automation}}Action枚举src/automation/protocol.zig是这套命令的协议面reload、wait、resize、screenshot、bridge、native_command、widget_action、widget_click、widget_hold、widget_context_press、widget_context_menu、widget_drag、widget_wheel、widget_key、widget_pinch、menu_command、shortcut、tray_action、focus_view、focus_next_view、focus_previous_view、profile、provenance。对应 CLI 的usage文本在 tools/native-sdk/automation.zig。标准工作流从启动到驱动组件以自动化模式启动应用。native automate wait阻塞直到snapshot.txt出现readytrue。用native automate assert pattern ...做状态检查或用native automate snapshot目检应用/窗口/源码元数据。native automate list查看窗口摘要。native automate bridge ...做桥接往返检查。native automate widget-action view-label widget-id action [value]驱动 retained canvas 组件动作。set_text走的是与真实键入完全相同的输入路径聚焦 → 全选 → 文本输入事件因此 TEA 应用的on_input镜像会收到编辑、模型状态与屏幕上的字段保持一致——它不是只写表现层。native automate widget-click view-label widget-id驱动指针式 retained 组件路由。widget-hold view-label widget-id以同一路径驱动按下并保持——指针按下、保留的 hold 定时器触发、然后释放被抑制——所以on_holdMsg 可被真实驱动目标没有on_hold时退化为真实长按的点击。widget-context-press view-label widget-id是次键点击弹出组件的上下文菜单或当路由未声明菜单时立即派发on_hold。native automate widget-drag view-label widget-id start-x-ratio end-x-ratio [start-y-ratio end-y-ratio]用于连续指针控件比例为 0..1 的视图内相对坐标。native automate widget-wheel view-label widget-id delta-y用于 retained 组件滚动输入。滚轮目标必须是可交互/可滚动的组件——普通布局列或文本节点不是滚轮目标应瞄准快照中出现的 scroll/list 组件 id。失败会以命名原因出现在快照里error eventautomation.widget_wheel nameWheelTargetUnknown|WheelTargetNotInteractive|WheelTargetHasEmptyBounds detailcommand args。native automate widget-key view-label key [text]向聚焦的 retained 组件发送键盘输入。key 支持修饰键和弦——cmda、cmdc、cmdv、cmdx、ctrlshiftarrowleftcmd在所有平台上都映射为主快捷键修饰键——因此全选/复制/剪切/粘贴和 shift 扩展选择都可驱动复制之后快照中组件行会显示实时选区selectiona..b复制文本落到真实系统剪贴板macOS 上即pbpaste可读。native automate widget-pinch view-label scale [x y]对 gpu-surface 视图驱动触控板捏合手势运行时派发真实的pinch_begin/pinch_change/pinch_end平台事件其中一次 change 携带scale - 1。scale是手势的最终乘法缩放——累积手势缩放1 delta的乘积精确落在这上面——1.5放大 50%0.5缩到一半。可选锚点为视图局部坐标点默认视图中心。应用通过 pinch 通道听到它Options.on_pinch/ TS core 的pinchMsg。native automate screenshot view-label [scale]把指定gpu_surface视图的 canvas 抓成screenshot-view-label.pngCLI 打印产物路径并等待文件出现。驱动应用菜单命令前先检查快照的command id...目录与app-menu/app-menu-item行证明运行中的应用加载了预期的app.zon或 runner 声明。然后用native automate menu-command id派发与真实菜单选择相同的.menu_command平台事件该动词仍是原始事件注入器因此快照的收到记录才是验证注册的方式。native automate tray-action item-id用于主状态项或native automate tray-action status-item-id item-id用于显式项。两者都通过真实菜单栏点击发出的同一平台事件选择下拉行命令源.tray。活跃项以tray #status-id title... visible... itemsN加后续tray-item #item-id ...行出现在snapshot.txt中——菜单栏位于所有窗口捕获之外因此这是每个模型驱动项的自动化证据。未知 id 对会以automation.tray_action进入派发错误环。native automate reload请求 WebView 重载。native automate profile on开启分阶段帧计时开启期间snapshot.txt携带一条frame_profile行给出流水线各阶段rebuild、layout、reconcile、emit、a11y、plan、patch、encode、present、host_decode、host_draw的滚动 p50/p90/max 微秒数每阶段带生命周期采样数stage_n。驱动一些交互后用native automate snapshot | grep -o frame_profile.*读取帧时间花在哪里profile off停止记录并移除该行。开启即开启一个新的采样窗口。底层协议中命令由Command.parse解析src/automation/protocol.zigwire 字符串与Action枚举一一对应快照侧FrameProfileStage与FrameProfile结构src/automation/snapshot.zig承载 profile 数据。快照断言automate assert优先用native automate assert而不是snapshot | grep链它会轮询所以不需要 sleep失败输出自带证据每个缺失模式 快照尾部。native automate assert gpu_nonblanktrue rolebutton nameReset count: 0 native automate assert --timeout-ms 10000 4 open native automate assert --absent error event dispatch_errors[1-9]语义每个参数都是必须匹配snapshot.txt中某处的正则。命令以 100ms 间隔轮询直到全部匹配然后退出 0。--timeout-ms n限定轮询时间默认 30000。超时打印每个未匹配模式的missing: pattern、快照最后 20 行并以非零退出——CI 友好无需包装脚本。--absent反转整个调用每个模式必须不匹配轮询直到消失。要同时断言存在与不存在运行两次调用。支持的正则子集字面量、.、后置*?、行锚点^/$、字符类[a-z]/[^0-9]以及\d \w \s含大写取反。不支持分组与交替——改为传多个模式。用单引号包裹模式让 shell 不动、$和\d。从实现看tools/native-sdk/automation.zigassert 的实现参数是轮询间隔assert_poll_interval_ms 100、默认超时assert_default_timeout_ms 30_000、失败尾部行数assert_tail_lines 20、模式上限assert_max_patterns 32。正则匹配器是一个小型自研 grep 式子集matchesPattern/matchHere/matchRepeat/atomMatches/escapeMatches/classMatches配套单元测试见 tools/native-sdk/automation.zig例如count: \d匹配status count: 42 open、.*true$匹配gpu_nonblanktrue、无效模式*x、a\、[abc、^*被拒绝。截图与确定性语义screenshot view-label [scale]要求运行时通过确定性 CPU 参考渲染器栅格化视图当前的 retained canvas 帧——与 Linux 软件呈现相同的像素路径——并发布为无压缩 PNG.zig-cache/native-sdk-automation/screenshot-view-label.png。文件原子写入临时文件 rename因此其存在即表示 PNG 完整publishScreenshot实现见 src/automation/server.zig先写.tmp再 rename 到位。确定性语义截图默认按 scale 1 渲染与显示器的 backing scale 无关因此同一台机器上未变化的场景每次抓取都产生字节一致的 PNG。显式传 scale如2可获得高 DPI 像素尺寸。截图使用实时 retained 场景包括实时设计 token 与平台文本测量macOS 上为 CoreText布局与屏幕上一致。字形由参考渲染器用内置字体面栅格化而非平台字体光栅化所以截图是确定性的布局/结构/颜色信号而非平台字体渲染信号。跨机器字节一致仅在文本度量确定性的地方null 平台的估算器有保证。在带原生文本测量提供者的平台上文本宽度可能随 OS 版本变化因此应在同一台机器上比较截图或断言属性尺寸、变化/未变化而非跨机器的精确字节。OS 级捕获macOS 的screencapture -x不能替代在无屏幕录制权限的 shell 中它退出 0 却静默返回只有壁纸、没有应用窗口的图片。若你 shell 出去做真实像素捕获先验证图片非空白/非壁纸再信任它automate screenshot 语义快照才是可靠组合。安全边界截图文件名通过protocol.screenshotFileName生成src/automation/protocol.zig标签名中[A-Za-z0-9._-]之外的字节被替换为-且标签上限max_screenshot_label_bytes 64保证文件名永远无法逃出自动化目录测试验证../evil→screenshot-..-evil.png、a/b→screenshot-a-b.png。桥接冒烟测试模式请求必须是带 ID、command、payload 的 JSONnative automate bridge {id:smoke,command:native.ping,payload:{source:automation}}自动化以 originzero://inline发送请求。应用的桥接策略必须允许该 origin否则调用会被permission_denied拒绝。打包资产 origin 下应用代码通常允许zero://app自动化冒烟测试只在需要时添加zero://inline。典型native.pinghandler 的响应形状{id:smoke,ok:true,result:{message:pong,count:1}}命令失败时检查桥接错误码unknown_command无已注册 handler 或命令名错误。permission_deniedorigin 或权限策略阻止了它。handler_failedZig handler 返回错误或无效 JSON。payload_too_large请求超过桥接限制。CLI 侧bridge会先删除旧的bridge-response.txt、发送命令、再等待响应产物出现tools/native-sdk/automation.zig响应由Server.publishBridgeResponse写入src/automation/server.zig。文件协议投递箱里有什么默认目录是.zig-cache/native-sdk-automation/相对于 CLI 的当前工作目录解析——请从应用项目目录应用启动处运行native automate。该目录由运行中的应用创建CLI 从不创建从错误 cwd 发出的命令会响亮失败error: no automation dir at abs path而不是排队进一个没有应用读取的目录每条排队命令都会打印它写入的绝对目录——命令看似没动静时检查这一行。文件清单snapshot.txt应用名、就绪状态、源码类型、源码大小、窗口元数据、可访问性摘要。readytrue行还携带protocolnCLI/应用握手协议版本不是自己的时 CLI 拒绝快照——以及向存活应用排队命令——并同时命名两个版本修复办法是重建过时的一侧并对比native version、dispatch_errorstotal与dropped_trace_recordstotal最近的降级 handler/update 错误以error eventtag nameErrorName timestamp_ns...行出现——handler 错误不再退出应用因此用 grep 来发现它发生。profile on激活时一条frame_profile stage_p50_us... stage_p90_us... stage_max_us... stage_n...行跟随头部给出分阶段帧计时。头部还携带markup_watcharmed|off——标记热重载 watch 是否已武装仅当应用以.markup带watch_path与io接线、或通过fragment_watch注册了编译片段时才武装——即 Debug 开发构建。windows.txt窗口列表。command.txt历史遗留单槽command-n.txtCLI 写入、运行时消费的命令输入。当前协议是编号队列command-n.txt条目取代了会因快速连续写入而互相覆盖的单槽command.txt。槽位单条进入应用每呈现一帧消费一条native automate command会等待运行中的应用消费它成功时打印delivered action - dir——它拒绝/响亮失败而不是静默覆盖未消费命令应用永不消费时以非零退出。bridge-response.txt最近一次桥接响应。screenshot-view-label.pnggpu_surface 视图的确定性参考渲染 PNG由screenshot命令写入。运行时轮询命令队列处理完一条命令后写入done以删除队列条目文件作为消费确认见 src/automation/server.zig 的takeCommand。快照头部由snapshot.writeText手写src/automation/snapshot.zigreadytrue protocol0x... framen commandsn runtime_uptime_nsn dispatch_errorsn dropped_trace_recordsn publisher_pidn markup_watcharmed|off。publisher_pid是发布应用的 pid——投递箱文件跨构建与运行持久存在因此 CLI 在信任快照前用实时进程表校验它发布者已死或缺失即视为陈旧文件响亮地作为 stale 服务而非当前状态snapshotLiveness/pidIsAlivetools/native-sdk/automation.zig。协议指纹与版本握手protocol字段是 CLI↔应用握手发布应用在构建时烘焙自己的协议指纹src/automation/protocol.zig 的fingerprint对协议表面描述的 comptime Wyhash并在每个快照头部盖章CLI 拒绝指纹不是自己的快照——因此过时的native二进制驱动新构建的应用或反之会响亮失败并命名两个指纹而不是静默读取昨天的状态。semantic_epoch当前为 4src/automation/protocol.zig是layoutDescription看不到的语义变更的逃生舱如同字节的语义断裂、快照文本格式变更、动词拼写变更。若报告协议不匹配或快照无协议版本native二进制与应用由不同框架版本构建——重建过时一侧过时的zig-out/binCLI 副本是经典原因native version打印该二进制构建自的 commit。陈旧实例守卫自动化动词在发布应用的进程早于zig-out/bin中最新的二进制构建时就打印响亮警告——旧一次运行遗留的实例在冒充新构建。杀掉它并重新启动新二进制再信任任何快照warnStaleInstanceIfDetectabletools/native-sdk/automation.zig。命令队列的诚实性sendCommandtools/native-sdk/automation.zig贯彻三条诚实规则目录不存在就响亮拒绝应用创建绝不 CLI 创建对已在其他协议上的存活发布者拒绝排队队列满max_queued_commands 8src/automation/protocol.zig时以消费节奏重试约 10s 后响亮拒绝并命名深度绝不覆盖。条目以独占创建声明flags.exclusive命名竞争失败则重扫队列取下一序号因此背靠背或并发调用永不互相覆盖。消费以“文件被删除”为确认awaitCommandConsumed约 10s 预算消费通常只需一个呈现帧耗尽预算意味着应用退出、冻结或停止呈现——这正是诊断信息。调试自动化失败若native automate wait超时且完全没有snapshot 文件它会打印一条教学式错误命名它监视的自动化目录并指向-Dautomationtrue与工作目录——从这条消息开始排查。否则确认应用仍在运行。确认它是以-Dautomationtrue构建的。确认 runner 把automation传入了Runtime.init。检查.zig-cache/native-sdk-automation/snapshot.txt。删除.zig-cache/native-sdk-automation/中的陈旧文件并重启应用。用更多追踪运行例如zig build run -Dtraceall。若 CLI 报告自动化协议不匹配或快照无协议版本native与应用由不同框架版本构建——重建过时一侧。若snapshot说没有应用连接自动化目录可能还不存在应用可能运行在不同的工作目录应用可能是未开自动化的构建应用可能还没到达运行时启动。若桥接自动化失败检查命令名拼写检查应用 handler 注册检查桥接策略 origin 是否含zero://inline检查运行时权限检查 handler 返回有效 JSON。命令看似没动静检查排队命令打印的绝对目录行——应用从不消费时CLI 会在约 10s 后以error: the app never consumed action响亮失败。CI 与冒烟测试用自动化获得最小的集成置信度zig build test-webview-smoke -Dplatformmacos一个好的冒烟测试以-Dautomationtrue与-Djs-bridgetrue构建示例。在可 GUI 的会话中启动应用。等待就绪。验证快照元数据用相关模式automate assert。发送native.ping。若应用启用内建窗口/WebView 则驱动它们。超时或桥接响应异常即失败。以native init --full脚手架的应用会把上述流程作为.github/workflows/ci.yml打包零配置默认脚手架跳过 CI一个 null-platformzig build test任务加一个 Linux Xvfb 冒烟任务——启动二进制、运行automate wait、用automate assert断言快照、并检查非空的automate screenshot产物。扩展那个文件而不是手写 grep 链。不要用自动化做穷尽式 UI 测试——它是运行时与桥接冒烟层。相关集成证据可见仓库测试 src/runtime/automation_liveness_tests.zig 与 src/runtime/automation_snapshot.zig。补充说明自动化是编译期门控的未以-Dautomationtrue构建的应用忽略自动化文件。截图只覆盖 retained-canvasgpu_surface视图WebView 像素不被捕获。WebView DOM 交互有意排除在本文件型自动化层之外。需要应用架构、桥接策略、打包与调试上下文时使用native skills get core --full。若需要会话级记录/回放record/replaynative automate record --out session.journal -- app command...与native automate replay session.journal [--verify|--no-verify] -- app command...可用tools/native-sdk/automation.zig通过NATIVE_SDK_SESSION_RECORD/NATIVE_SDK_SESSION_REPLAY环境变量武装应用 runner。赞分享桌面应用跨平台【免费下载链接】nativeToolkit for building native desktop apps项目地址https://gitcode.com/gh_mirrors/ze/native点击查看免费下载相关推荐Native SDK Web 引擎选型、应用打包与运行时调试实战指南Native SDK Web 引擎选型、应用打包与运行时调试实战指南 本文以 ze/nativeNative SDK面向桌面端原生应用的构建工具包仓库内文桌面应用跨平台Proton Native 调试指南使用 react-devtools 调试桌面应用Proton Native 调试指南使用 react devtools 调试桌面应用 本指南围绕 Proton Native 官方调试文档 docs/deb桌面应用前端UI组件Native SDK 完全指南用 TypeScript 与声明式 Markup 构建零运行时原生桌面应用Native SDK 完全指南用 TypeScript 与声明式 Markup 构建零运行时原生桌面应用 Native SDK 是一套面向原生桌面应用开发的完桌面应用跨平台上一篇Operator SDK v1.28.0 版本深度解析依赖升级、Ansible 修复与 Scorecard 非 root 化改造下一篇免费网盘直链下载助手八大网盘一键获取下载地址的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Native SDK 自动化指南：用 `native automate` 驱动、断言与调试桌面应用运行时
桌面应用跨平台【免费下载链接】nativeToolkit for building native desktop apps项目地址https://gitcode.com/gh_mirrors/ze/native点击查看免费下载导读Native SDKZig 实现的跨平台桌面应用工具包仓库根目录见 README.md为每个启用自动化的应用内嵌一个自动化服务器——无论是原生渲染retained-canvas / gpu_surface应用还是 WebView 壳应用。它通过.zig-cache/native-sdk-automation/下的文件型 IPC文件投递箱协议dropbox protocol工作专为冒烟测试、带 GUI 会话的 CI 校验与快速运行时巡检设计可读取可访问性快照、沿真实输入路径驱动 retained 组件、生成确定性的参考渲染截图、做就绪/状态断言并完成桥接bridge往返。本文基于 skill-data/automation/SKILL.md并结合 src/automation/ 的源码实现给出完整、可复制的实操指南。注意这不是浏览器 DOM 自动化。它报告的是运行时/窗口/组件状态驱动 retained-canvas 组件并可以要求运行时重载或派发桥接请求。若要测试可选的 WebView 路径的 DOM请使用前端框架的测试或对 dev server 使用浏览器自动化工具。自动化能验证什么、不能验证什么能验证启用自动化的应用已启动并发布readytrue运行时加载了预期的应用名、源码类型与窗口元数据主窗口存在且处于聚焦/打开状态JavaScript↔Zig 桥接可通过native automate bridge完成一次请求往返内建窗口/WebView 命令可被冒烟测试驱动运行时接受重载请求retained-canvasgpu_surface视图的真实像素native automate screenshot view-label通过确定性 CPU 参考渲染器把视图当前 canvas 帧渲染成 PNG 产物。同一场景的两次抓取字节一致因此截图可支撑 golden-image 或“UI 是否变化”的检查。不能验证WebView 内容的截图screenshot仅覆盖gpu_surfacecanvas 视图没有 DOM/WebView 像素捕获任意 DOM 查询与点击浏览器网络断言。从快照数据模型src/automation/snapshot.zig看快照内容由Input结构体承载窗口Window、视图ViewInfo区分gpu_surface与webview两种kind、组件Widget、命令与应用菜单目录commands/menus、托盘trays、音频/视频播放状态audio/video以及诊断信息Diagnostics。这决定了“能验证”的边界正是快照里被明确建模的那些状态。前置条件如何启用自动化用-Dautomationtrue构建并运行应用。生成的示例通常直接暴露该选项zig build run -Dplatformmacos -Dautomationtrue仓库示例可能有专门步骤zig build run-webview -Dplatformmacos -Dautomationtrue zig build test-webview-smoke -DplatformmacosRunner 必须把自动化服务器传入RuntimeOptions对应 src/runtime/api.zig 中的automation: ?automation.Server字段const server native_sdk.automation.Server.init(io, .zig-cache/native-sdk-automation, My App); var runtime native_sdk.Runtime.init(.{ .platform my_platform, .automation server, });Server.init的签名见 src/automation/server.zig三个参数分别是io、投递箱目录默认.zig-cache/native-sdk-automation和用于标识的 title。未用-Dautomationtrue构建的应用通常会忽略自动化文件——自动化是编译期门控的没开选项的应用不创建投递箱目录、不发布快照、不消费命令。命令一览CLI 总入口是native automate command仓库构建版为zig-out/bin/native automate command命令表定义在 tools/native-sdk/automation.zignative automate wait native automate assert gpu_nonblanktrue rolebutton nameReset native automate assert --absent error event native automate list native automate snapshot native automate reload native automate screenshot inbox-canvas native automate screenshot inbox-canvas 2 native automate widget-action canvas 2 press native automate widget-click canvas 3 native automate widget-hold canvas 3 native automate widget-context-press canvas 3 native automate widget-drag canvas 4 0.25 0.82 native automate widget-wheel canvas 5 18 native automate widget-key canvas tab native automate widget-key canvas cmdc native automate widget-pinch canvas 1.5 native automate widget-pinch canvas 0.5 120 80 native automate profile on native automate profile off native automate bridge {id:smoke,command:native.ping,payload:{source:automation}}Action枚举src/automation/protocol.zig是这套命令的协议面reload、wait、resize、screenshot、bridge、native_command、widget_action、widget_click、widget_hold、widget_context_press、widget_context_menu、widget_drag、widget_wheel、widget_key、widget_pinch、menu_command、shortcut、tray_action、focus_view、focus_next_view、focus_previous_view、profile、provenance。对应 CLI 的usage文本在 tools/native-sdk/automation.zig。标准工作流从启动到驱动组件以自动化模式启动应用。native automate wait阻塞直到snapshot.txt出现readytrue。用native automate assert pattern ...做状态检查或用native automate snapshot目检应用/窗口/源码元数据。native automate list查看窗口摘要。native automate bridge ...做桥接往返检查。native automate widget-action view-label widget-id action [value]驱动 retained canvas 组件动作。set_text走的是与真实键入完全相同的输入路径聚焦 → 全选 → 文本输入事件因此 TEA 应用的on_input镜像会收到编辑、模型状态与屏幕上的字段保持一致——它不是只写表现层。native automate widget-click view-label widget-id驱动指针式 retained 组件路由。widget-hold view-label widget-id以同一路径驱动按下并保持——指针按下、保留的 hold 定时器触发、然后释放被抑制——所以on_holdMsg 可被真实驱动目标没有on_hold时退化为真实长按的点击。widget-context-press view-label widget-id是次键点击弹出组件的上下文菜单或当路由未声明菜单时立即派发on_hold。native automate widget-drag view-label widget-id start-x-ratio end-x-ratio [start-y-ratio end-y-ratio]用于连续指针控件比例为 0..1 的视图内相对坐标。native automate widget-wheel view-label widget-id delta-y用于 retained 组件滚动输入。滚轮目标必须是可交互/可滚动的组件——普通布局列或文本节点不是滚轮目标应瞄准快照中出现的 scroll/list 组件 id。失败会以命名原因出现在快照里error eventautomation.widget_wheel nameWheelTargetUnknown|WheelTargetNotInteractive|WheelTargetHasEmptyBounds detailcommand args。native automate widget-key view-label key [text]向聚焦的 retained 组件发送键盘输入。key 支持修饰键和弦——cmda、cmdc、cmdv、cmdx、ctrlshiftarrowleftcmd在所有平台上都映射为主快捷键修饰键——因此全选/复制/剪切/粘贴和 shift 扩展选择都可驱动复制之后快照中组件行会显示实时选区selectiona..b复制文本落到真实系统剪贴板macOS 上即pbpaste可读。native automate widget-pinch view-label scale [x y]对 gpu-surface 视图驱动触控板捏合手势运行时派发真实的pinch_begin/pinch_change/pinch_end平台事件其中一次 change 携带scale - 1。scale是手势的最终乘法缩放——累积手势缩放1 delta的乘积精确落在这上面——1.5放大 50%0.5缩到一半。可选锚点为视图局部坐标点默认视图中心。应用通过 pinch 通道听到它Options.on_pinch/ TS core 的pinchMsg。native automate screenshot view-label [scale]把指定gpu_surface视图的 canvas 抓成screenshot-view-label.pngCLI 打印产物路径并等待文件出现。驱动应用菜单命令前先检查快照的command id...目录与app-menu/app-menu-item行证明运行中的应用加载了预期的app.zon或 runner 声明。然后用native automate menu-command id派发与真实菜单选择相同的.menu_command平台事件该动词仍是原始事件注入器因此快照的收到记录才是验证注册的方式。native automate tray-action item-id用于主状态项或native automate tray-action status-item-id item-id用于显式项。两者都通过真实菜单栏点击发出的同一平台事件选择下拉行命令源.tray。活跃项以tray #status-id title... visible... itemsN加后续tray-item #item-id ...行出现在snapshot.txt中——菜单栏位于所有窗口捕获之外因此这是每个模型驱动项的自动化证据。未知 id 对会以automation.tray_action进入派发错误环。native automate reload请求 WebView 重载。native automate profile on开启分阶段帧计时开启期间snapshot.txt携带一条frame_profile行给出流水线各阶段rebuild、layout、reconcile、emit、a11y、plan、patch、encode、present、host_decode、host_draw的滚动 p50/p90/max 微秒数每阶段带生命周期采样数stage_n。驱动一些交互后用native automate snapshot | grep -o frame_profile.*读取帧时间花在哪里profile off停止记录并移除该行。开启即开启一个新的采样窗口。底层协议中命令由Command.parse解析src/automation/protocol.zigwire 字符串与Action枚举一一对应快照侧FrameProfileStage与FrameProfile结构src/automation/snapshot.zig承载 profile 数据。快照断言automate assert优先用native automate assert而不是snapshot | grep链它会轮询所以不需要 sleep失败输出自带证据每个缺失模式 快照尾部。native automate assert gpu_nonblanktrue rolebutton nameReset count: 0 native automate assert --timeout-ms 10000 4 open native automate assert --absent error event dispatch_errors[1-9]语义每个参数都是必须匹配snapshot.txt中某处的正则。命令以 100ms 间隔轮询直到全部匹配然后退出 0。--timeout-ms n限定轮询时间默认 30000。超时打印每个未匹配模式的missing: pattern、快照最后 20 行并以非零退出——CI 友好无需包装脚本。--absent反转整个调用每个模式必须不匹配轮询直到消失。要同时断言存在与不存在运行两次调用。支持的正则子集字面量、.、后置*?、行锚点^/$、字符类[a-z]/[^0-9]以及\d \w \s含大写取反。不支持分组与交替——改为传多个模式。用单引号包裹模式让 shell 不动、$和\d。从实现看tools/native-sdk/automation.zigassert 的实现参数是轮询间隔assert_poll_interval_ms 100、默认超时assert_default_timeout_ms 30_000、失败尾部行数assert_tail_lines 20、模式上限assert_max_patterns 32。正则匹配器是一个小型自研 grep 式子集matchesPattern/matchHere/matchRepeat/atomMatches/escapeMatches/classMatches配套单元测试见 tools/native-sdk/automation.zig例如count: \d匹配status count: 42 open、.*true$匹配gpu_nonblanktrue、无效模式*x、a\、[abc、^*被拒绝。截图与确定性语义screenshot view-label [scale]要求运行时通过确定性 CPU 参考渲染器栅格化视图当前的 retained canvas 帧——与 Linux 软件呈现相同的像素路径——并发布为无压缩 PNG.zig-cache/native-sdk-automation/screenshot-view-label.png。文件原子写入临时文件 rename因此其存在即表示 PNG 完整publishScreenshot实现见 src/automation/server.zig先写.tmp再 rename 到位。确定性语义截图默认按 scale 1 渲染与显示器的 backing scale 无关因此同一台机器上未变化的场景每次抓取都产生字节一致的 PNG。显式传 scale如2可获得高 DPI 像素尺寸。截图使用实时 retained 场景包括实时设计 token 与平台文本测量macOS 上为 CoreText布局与屏幕上一致。字形由参考渲染器用内置字体面栅格化而非平台字体光栅化所以截图是确定性的布局/结构/颜色信号而非平台字体渲染信号。跨机器字节一致仅在文本度量确定性的地方null 平台的估算器有保证。在带原生文本测量提供者的平台上文本宽度可能随 OS 版本变化因此应在同一台机器上比较截图或断言属性尺寸、变化/未变化而非跨机器的精确字节。OS 级捕获macOS 的screencapture -x不能替代在无屏幕录制权限的 shell 中它退出 0 却静默返回只有壁纸、没有应用窗口的图片。若你 shell 出去做真实像素捕获先验证图片非空白/非壁纸再信任它automate screenshot 语义快照才是可靠组合。安全边界截图文件名通过protocol.screenshotFileName生成src/automation/protocol.zig标签名中[A-Za-z0-9._-]之外的字节被替换为-且标签上限max_screenshot_label_bytes 64保证文件名永远无法逃出自动化目录测试验证../evil→screenshot-..-evil.png、a/b→screenshot-a-b.png。桥接冒烟测试模式请求必须是带 ID、command、payload 的 JSONnative automate bridge {id:smoke,command:native.ping,payload:{source:automation}}自动化以 originzero://inline发送请求。应用的桥接策略必须允许该 origin否则调用会被permission_denied拒绝。打包资产 origin 下应用代码通常允许zero://app自动化冒烟测试只在需要时添加zero://inline。典型native.pinghandler 的响应形状{id:smoke,ok:true,result:{message:pong,count:1}}命令失败时检查桥接错误码unknown_command无已注册 handler 或命令名错误。permission_deniedorigin 或权限策略阻止了它。handler_failedZig handler 返回错误或无效 JSON。payload_too_large请求超过桥接限制。CLI 侧bridge会先删除旧的bridge-response.txt、发送命令、再等待响应产物出现tools/native-sdk/automation.zig响应由Server.publishBridgeResponse写入src/automation/server.zig。文件协议投递箱里有什么默认目录是.zig-cache/native-sdk-automation/相对于 CLI 的当前工作目录解析——请从应用项目目录应用启动处运行native automate。该目录由运行中的应用创建CLI 从不创建从错误 cwd 发出的命令会响亮失败error: no automation dir at abs path而不是排队进一个没有应用读取的目录每条排队命令都会打印它写入的绝对目录——命令看似没动静时检查这一行。文件清单snapshot.txt应用名、就绪状态、源码类型、源码大小、窗口元数据、可访问性摘要。readytrue行还携带protocolnCLI/应用握手协议版本不是自己的时 CLI 拒绝快照——以及向存活应用排队命令——并同时命名两个版本修复办法是重建过时的一侧并对比native version、dispatch_errorstotal与dropped_trace_recordstotal最近的降级 handler/update 错误以error eventtag nameErrorName timestamp_ns...行出现——handler 错误不再退出应用因此用 grep 来发现它发生。profile on激活时一条frame_profile stage_p50_us... stage_p90_us... stage_max_us... stage_n...行跟随头部给出分阶段帧计时。头部还携带markup_watcharmed|off——标记热重载 watch 是否已武装仅当应用以.markup带watch_path与io接线、或通过fragment_watch注册了编译片段时才武装——即 Debug 开发构建。windows.txt窗口列表。command.txt历史遗留单槽command-n.txtCLI 写入、运行时消费的命令输入。当前协议是编号队列command-n.txt条目取代了会因快速连续写入而互相覆盖的单槽command.txt。槽位单条进入应用每呈现一帧消费一条native automate command会等待运行中的应用消费它成功时打印delivered action - dir——它拒绝/响亮失败而不是静默覆盖未消费命令应用永不消费时以非零退出。bridge-response.txt最近一次桥接响应。screenshot-view-label.pnggpu_surface 视图的确定性参考渲染 PNG由screenshot命令写入。运行时轮询命令队列处理完一条命令后写入done以删除队列条目文件作为消费确认见 src/automation/server.zig 的takeCommand。快照头部由snapshot.writeText手写src/automation/snapshot.zigreadytrue protocol0x... framen commandsn runtime_uptime_nsn dispatch_errorsn dropped_trace_recordsn publisher_pidn markup_watcharmed|off。publisher_pid是发布应用的 pid——投递箱文件跨构建与运行持久存在因此 CLI 在信任快照前用实时进程表校验它发布者已死或缺失即视为陈旧文件响亮地作为 stale 服务而非当前状态snapshotLiveness/pidIsAlivetools/native-sdk/automation.zig。协议指纹与版本握手protocol字段是 CLI↔应用握手发布应用在构建时烘焙自己的协议指纹src/automation/protocol.zig 的fingerprint对协议表面描述的 comptime Wyhash并在每个快照头部盖章CLI 拒绝指纹不是自己的快照——因此过时的native二进制驱动新构建的应用或反之会响亮失败并命名两个指纹而不是静默读取昨天的状态。semantic_epoch当前为 4src/automation/protocol.zig是layoutDescription看不到的语义变更的逃生舱如同字节的语义断裂、快照文本格式变更、动词拼写变更。若报告协议不匹配或快照无协议版本native二进制与应用由不同框架版本构建——重建过时一侧过时的zig-out/binCLI 副本是经典原因native version打印该二进制构建自的 commit。陈旧实例守卫自动化动词在发布应用的进程早于zig-out/bin中最新的二进制构建时就打印响亮警告——旧一次运行遗留的实例在冒充新构建。杀掉它并重新启动新二进制再信任任何快照warnStaleInstanceIfDetectabletools/native-sdk/automation.zig。命令队列的诚实性sendCommandtools/native-sdk/automation.zig贯彻三条诚实规则目录不存在就响亮拒绝应用创建绝不 CLI 创建对已在其他协议上的存活发布者拒绝排队队列满max_queued_commands 8src/automation/protocol.zig时以消费节奏重试约 10s 后响亮拒绝并命名深度绝不覆盖。条目以独占创建声明flags.exclusive命名竞争失败则重扫队列取下一序号因此背靠背或并发调用永不互相覆盖。消费以“文件被删除”为确认awaitCommandConsumed约 10s 预算消费通常只需一个呈现帧耗尽预算意味着应用退出、冻结或停止呈现——这正是诊断信息。调试自动化失败若native automate wait超时且完全没有snapshot 文件它会打印一条教学式错误命名它监视的自动化目录并指向-Dautomationtrue与工作目录——从这条消息开始排查。否则确认应用仍在运行。确认它是以-Dautomationtrue构建的。确认 runner 把automation传入了Runtime.init。检查.zig-cache/native-sdk-automation/snapshot.txt。删除.zig-cache/native-sdk-automation/中的陈旧文件并重启应用。用更多追踪运行例如zig build run -Dtraceall。若 CLI 报告自动化协议不匹配或快照无协议版本native与应用由不同框架版本构建——重建过时一侧。若snapshot说没有应用连接自动化目录可能还不存在应用可能运行在不同的工作目录应用可能是未开自动化的构建应用可能还没到达运行时启动。若桥接自动化失败检查命令名拼写检查应用 handler 注册检查桥接策略 origin 是否含zero://inline检查运行时权限检查 handler 返回有效 JSON。命令看似没动静检查排队命令打印的绝对目录行——应用从不消费时CLI 会在约 10s 后以error: the app never consumed action响亮失败。CI 与冒烟测试用自动化获得最小的集成置信度zig build test-webview-smoke -Dplatformmacos一个好的冒烟测试以-Dautomationtrue与-Djs-bridgetrue构建示例。在可 GUI 的会话中启动应用。等待就绪。验证快照元数据用相关模式automate assert。发送native.ping。若应用启用内建窗口/WebView 则驱动它们。超时或桥接响应异常即失败。以native init --full脚手架的应用会把上述流程作为.github/workflows/ci.yml打包零配置默认脚手架跳过 CI一个 null-platformzig build test任务加一个 Linux Xvfb 冒烟任务——启动二进制、运行automate wait、用automate assert断言快照、并检查非空的automate screenshot产物。扩展那个文件而不是手写 grep 链。不要用自动化做穷尽式 UI 测试——它是运行时与桥接冒烟层。相关集成证据可见仓库测试 src/runtime/automation_liveness_tests.zig 与 src/runtime/automation_snapshot.zig。补充说明自动化是编译期门控的未以-Dautomationtrue构建的应用忽略自动化文件。截图只覆盖 retained-canvasgpu_surface视图WebView 像素不被捕获。WebView DOM 交互有意排除在本文件型自动化层之外。需要应用架构、桥接策略、打包与调试上下文时使用native skills get core --full。若需要会话级记录/回放record/replaynative automate record --out session.journal -- app command...与native automate replay session.journal [--verify|--no-verify] -- app command...可用tools/native-sdk/automation.zig通过NATIVE_SDK_SESSION_RECORD/NATIVE_SDK_SESSION_REPLAY环境变量武装应用 runner。赞分享桌面应用跨平台【免费下载链接】nativeToolkit for building native desktop apps项目地址https://gitcode.com/gh_mirrors/ze/native点击查看免费下载相关推荐Native SDK Web 引擎选型、应用打包与运行时调试实战指南Native SDK Web 引擎选型、应用打包与运行时调试实战指南 本文以 ze/nativeNative SDK面向桌面端原生应用的构建工具包仓库内文桌面应用跨平台Proton Native 调试指南使用 react-devtools 调试桌面应用Proton Native 调试指南使用 react devtools 调试桌面应用 本指南围绕 Proton Native 官方调试文档 docs/deb桌面应用前端UI组件Native SDK 完全指南用 TypeScript 与声明式 Markup 构建零运行时原生桌面应用Native SDK 完全指南用 TypeScript 与声明式 Markup 构建零运行时原生桌面应用 Native SDK 是一套面向原生桌面应用开发的完桌面应用跨平台上一篇Operator SDK v1.28.0 版本深度解析依赖升级、Ansible 修复与 Scorecard 非 root 化改造下一篇免费网盘直链下载助手八大网盘一键获取下载地址的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
