anarlog windows 插件权限体系解析：Tauri 命令 ACL 参考与实践指南

anarlog windows 插件权限体系解析Tauri 命令 ACL 参考与实践指南【免费下载链接】anarlogOpen source Granola AI Alternative项目地址: https://gitcode.com/GitHub_Trending/hy/anarlog本篇技术指南围绕 anarlog 桌面端windowstauri-plugin-windows插件自动生成的权限参考文档展开系统讲解该插件的默认权限集、全部命令权限标识Identifier及其与底层 Tauri command 的对应关系并结合源码说明每个权限背后控制的窗口生命周期、WebView 健康检查、悬浮录音条floating bar、实时字幕live caption与窗口帧动画等能力。读完本文你将能准确理解capabilities/*.json中windows:allow-*/windows:deny-*权限项的语义并能够按最小权限原则自行裁剪或扩展窗口插件的授权范围。一、reference.md 的定位一份自动生成的权限总表plugins/windows/permissions/autogenerated/reference.md位于autogenerated目录文件头没有人工维护的痕迹与目录下commands/*.toml每个命令一个权限定义文件一样是 Tauri 插件构建流程自动产出的产物commands/*.toml文件内部明确标注了# Automatically generated - DO NOT EDIT!见 floating_bar_show.toml、webview_health_ack.toml。这份文档由两个部分组成Default Permission默认权限集声明了插件默认授予的 24 个allow-*权限源定义位于 default.toml。Permission Table权限表完整列出 26 个命令的allow-*与deny-*权限标识共 52 项描述均为 Enables/Denies the xxx command without any pre-configured scope无需任何预配置 scope 即直接启用/拒绝某命令。permissions/schemas/schema.json给出了这些权限文件的 JSON Schema 契约一个权限文件可以包含default默认权限集、set权限集合、permission内联权限三类定义每个Permission由identifier、commands.allow、commands.deny组成并且Commands定义中明确「deny 优先」——当同一命令同时出现在 allow 与 deny 中时默认按拒绝处理Denied command, which takes priority。二、默认权限集开箱即用的 24 项能力default.toml的[default]段声明了插件默认权限集合共 24 项[default] description Default permissions for the plugin permissions [ allow-window-show, allow-window-hide, allow-window-destroy, allow-window-navigate, allow-window-emit-navigate, allow-window-is-exists, allow-window-is-occluded, allow-webview-health-ack, allow-webview-health-ready, allow-window-set-frame-animated, allow-window-save-frame, allow-window-restore-frame-animated, allow-window-expand-width, allow-window-restore-width, allow-set-show-app-in-dock, allow-floating-bar-show, allow-floating-bar-hide, allow-floating-bar-update, allow-floating-bar-update-amplitude, allow-floating-bar-current-state, allow-live-caption-show, allow-live-caption-hide, allow-live-caption-update, allow-live-caption-current-state, ]按功能分组解读这 24 项能力分组默认权限对应命令窗口生命周期allow-window-show/allow-window-hide/allow-window-destroy/allow-window-navigate/allow-window-emit-navigate/allow-window-is-exists/allow-window-is-occludedwindow_show/window_hide/window_destroy/window_navigate/window_emit_navigate/window_is_exists/window_is_occludedWebView 健康检查allow-webview-health-ack/allow-webview-health-readywebview_health_ack/webview_health_ready窗口帧动画allow-window-set-frame-animated/allow-window-save-frame/allow-window-restore-frame-animatedwindow_set_frame_animated/window_save_frame/window_restore_frame_animated窗口宽度扩展allow-window-expand-width/allow-window-restore-widthwindow_expand_width/window_restore_widthDock 图标allow-set-show-app-in-dockset_show_app_in_dock悬浮录音条allow-floating-bar-show/allow-floating-bar-hide/allow-floating-bar-update/allow-floating-bar-update-amplitude/allow-floating-bar-current-statefloating_bar_show/floating_bar_hide/floating_bar_update/floating_bar_update_amplitude/floating_bar_current_state实时字幕allow-live-caption-show/allow-live-caption-hide/allow-live-caption-update/allow-live-caption-current-statelive_caption_show/live_caption_hide/live_caption_update/live_caption_current_state值得注意的一个细节默认集中不包含allow-remove-fake-window与allow-set-fake-window-bounds。这两个 fake window 相关命令虽然出现在权限表中但需要使用者显式allow才会生效属于默认关闭的能力。三、权限表26 个命令 × allow/deny 全量标识reference.md 的 Permission Table 覆盖了plugins/windows/permissions/autogenerated/commands/目录下全部 26 个命令的权限标识每个命令对应一个.toml定义allow-cmd与deny-cmd两个标识。下表完整继承并整理了全部 52 项权限标识命令allow 标识deny 标识说明floating_bar_current_statewindows:allow-floating-bar-current-statewindows:deny-floating-bar-current-state查询悬浮条当前状态floating_bar_hidewindows:allow-floating-bar-hidewindows:deny-floating-bar-hide隐藏悬浮条floating_bar_showwindows:allow-floating-bar-showwindows:deny-floating-bar-show显示悬浮条floating_bar_updatewindows:allow-floating-bar-updatewindows:deny-floating-bar-update更新悬浮条状态floating_bar_update_amplitudewindows:allow-floating-bar-update-amplitudewindows:deny-floating-bar-update-amplitude更新悬浮条音频振幅live_caption_current_statewindows:allow-live-caption-current-statewindows:deny-live-caption-current-state查询实时字幕状态live_caption_hidewindows:allow-live-caption-hidewindows:deny-live-caption-hide隐藏实时字幕live_caption_showwindows:allow-live-caption-showwindows:deny-live-caption-show显示实时字幕live_caption_updatewindows:allow-live-caption-updatewindows:deny-live-caption-update更新实时字幕状态remove_fake_windowwindows:allow-remove-fake-windowwindows:deny-remove-fake-window移除 fake window默认未启用set_fake_window_boundswindows:allow-set-fake-window-boundswindows:deny-set-fake-window-bounds设置 fake window 边界默认未启用set_show_app_in_dockwindows:allow-set-show-app-in-dockwindows:deny-set-show-app-in-dock控制 Dock 中是否显示应用图标webview_health_ackwindows:allow-webview-health-ackwindows:deny-webview-health-ack应答 WebView 健康检查webview_health_readywindows:allow-webview-health-readywindows:deny-webview-health-ready标记 WebView 健康检查就绪window_destroywindows:allow-window-destroywindows:deny-window-destroy销毁窗口window_emit_navigatewindows:allow-window-emit-navigatewindows:deny-window-emit-navigate向窗口发出导航事件window_expand_widthwindows:allow-window-expand-widthwindows:deny-window-expand-width扩展窗口宽度window_hidewindows:allow-window-hidewindows:deny-window-hide隐藏窗口window_is_existswindows:allow-window-is-existswindows:deny-window-is-exists查询窗口是否存在window_is_occludedwindows:allow-window-is-occludedwindows:deny-window-is-occluded查询窗口是否被遮挡window_navigatewindows:allow-window-navigatewindows:deny-window-navigate窗口内导航到指定路径window_restore_frame_animatedwindows:allow-window-restore-frame-animatedwindows:deny-window-restore-frame-animated动画恢复已保存的窗口帧window_restore_widthwindows:allow-window-restore-widthwindows:deny-window-restore-width恢复扩展前的窗口宽度window_save_framewindows:allow-window-save-framewindows:deny-window-save-frame保存当前窗口帧window_set_frame_animatedwindows:allow-window-set-frame-animatedwindows:deny-window-set-frame-animated按锚点动画设置窗口帧window_showwindows:allow-window-showwindows:deny-window-show显示窗口每个.toml的写法非常简洁例如 floating_bar_show.toml# Automatically generated - DO NOT EDIT! $schema ../../schemas/schema.json [[permission]] identifier allow-floating-bar-show description Enables the floating_bar_show command without any pre-configured scope. commands.allow [floating_bar_show] [[permission]] identifier deny-floating-bar-show description Denies the floating_bar_show command without any pre-configured scope. commands.deny [floating_bar_show]四、权限背后的命令实现源码级解读权限标识最终约束的是插件注册的 Tauri command。windows插件的全部命令在 lib.rs 中通过tauri_specta的collect_commands!统一注册包括window_show、floating_bar_*、live_caption_*、webview_health_*等 26 个同时在 make_specta_builder 中收集了Navigate、WindowDestroyed、OpenTab、VisibilityEvent、WebviewHealthCheck、FloatingBarStop、FloatingBarOpenMain、FloatingBarOverlayState、FloatingBarOverlayAmplitude、LiveCaptionOverlayState、FloatingBarSettingsChange等事件定义。前端侧则由 bindings.gen.ts 生成类型安全的命令代理例如commands.windowShow(window)实际执行TAURI_INVOKE(plugin:windows|window_show, { window })。4.1 窗口生命周期与导航commands.rs 中window_show、window_hide、window_destroy、window_navigate、window_emit_navigate、window_is_exists、window_is_occluded七个命令共享同一个窗口标识参数AppWindow。AppWindow定义在 v1.rs是一个带 serde tag 的枚举#[serde(tag type, content value)] pub enum AppWindow { #[serde(rename main)] Main, #[serde(rename composer)] Composer, #[serde(rename note)] Note(String), }AppWindow::Display实现把枚举映射为窗口 labelmain、composer、note-{id}FromStr反向解析时note-前缀之后任意非空字符串都解析为笔记窗口这与前端 js/index.ts 中定义的WindowLabel联合类型main | composer | floating | floating-bar | live-caption | \note-${string} | calendar | settings保持一致。window_navigate接收一个路径字符串而window_emit_navigate接收结构化的Navigate事件——Navigate的FromStr实现见 [events.rs](https://link.gitcode.com/i/3c0396d6d30b7d7a9da1c23b2fdb344d)能把anarlog://anarlog.so/app/new?calendarEventId123recordtrue形式的 URL 解析为{ path: /app/new, search: {...} }单元测试navigate_from_str 验证了这一解析逻辑。4.2 WebView 健康检查ack 与 readyallow-webview-health-ack与allow-webview-health-ready背后是插件内建的 WebView 探活机制。核心状态WebviewHealthStatelib.rs维护pending待应答的探针注册表与recovering恢复中窗口集合register为窗口生成自增registration_id与 UUIDrequest_id同一窗口只允许一个探针在途恢复期间不允许注册acknowledge只有request_id完全匹配的应答才会解除挂起状态对应webview_health_ack命令begin_recovery/ready进入恢复流程后阻塞新探针webview_health_ready命令负责标记恢复完成。前端配合逻辑位于 js/index.tsinit()中监听webviewHealthCheck事件收到后立即调用commands.webviewHealthAck(payload.requestId)应答随后调用commands.webviewHealthReady()声明就绪。lib.rs 中webview_health_acknowledges_only_the_current_request、webview_health_allows_only_one_probe_per_window、webview_health_recovery_starts_once_and_blocks_probes三个单元测试锁定了这套语义——权限粒度上ack与ready被拆成两个独立标识方便只放行应答、不放行恢复等细粒度控制。4.3 窗口帧动画与宽度扩展window_set_frame_animatedcommands.rs接收anchorTopRight/TopLeft/BottomRight/BottomLeft/Center、width、height基于可见帧计算目标位置屏幕边距固定为8.0保存帧后调用set_frame_animated做动画过渡主窗口还会临时置顶set_always_on_top(true)。window_save_frame将当前帧存入SavedFrames状态MutexHashMapString, SavedFramewindow_restore_frame_animated取回帧并动画恢复同时取消主窗口的置顶。window_expand_widthcommands.rs参数较丰富expansion_px扩展像素、max_current_width最大宽度上限可选、check_monitor_space是否检查显示器右侧剩余空间、expand_left向左扩展还是向右、restore_on_close是否记录以便恢复。非 macOS 平台直接通过set_size调整物理尺寸macOS 平台则在主线程通过 objc2 操作NSWindow的 frameWindowExpansions状态以Vec(old_w, new_w, expand_left)记录历史window_restore_width弹栈还原。4.4 悬浮录音条floating bar与实时字幕live captionfloating_bar_*四个命令对应 floating_bar.rsFloatingBarState携带amplitude、title、statusRecording/Error、color_schemeLight/Dark、opacity、实时字幕相关字段以及可选的transcript_bubbles气泡列表。实现按平台分叉macOS 通过swift_rs调用_floating_bar_show/_floating_bar_hide/_floating_bar_update/_floating_bar_update_amplitude原生 Swift 实现对应swift-lib/FloatingBarManager.swift等原生面板其他平台则用 label 为floating-bar的WebviewWindow承载加载app/floating-bar页面按layout模块紧凑高度 38px、展开 360×430计算尺寸并锚定在工作区右上角屏幕边距 8px同时通过set_content_protected(true)与exclude_from_capture将其排除在录屏之外。live_caption_*命令对应 live_caption.rsLiveCaptionState包含text、opacity、width、line_count、position六种位置枚举与minimizedlayout模块将宽度约束在 260640px、行数约束在 14 行并按 6 种锚点计算窗口原点顶栏偏移 18px、屏幕边距 12px。五、在应用中的实际配置capabilities 与默认集的关系权限标识通过 Tauri capabilities 文件注入到实际窗口。anarlog 桌面端的主 capability 文件 apps/desktop/src-tauri/capabilities/default.json 中windows插件的授权由两段构成windows:default, windows:allow-floating-bar-show, windows:allow-floating-bar-hide, windows:allow-floating-bar-update, windows:allow-floating-bar-update-amplitude, windows:allow-floating-bar-current-state, windows:allow-live-caption-current-state,windows:default一次性引入默认权限集的全部 24 项紧随其后的windows:allow-floating-bar-*等是显式重申在默认集已包含的情况下是冗余但无害的。这种「默认集 显式追加」的组合方式意味着只要默认集中存在某项能力前端即可直接调用对应命令无需在 capability 中重复声明而allow-remove-fake-window、allow-set-fake-window-bounds这类默认集之外的权限则必须显式列出才能生效。六、裁剪与加固建议按需裁剪默认集如果产品形态不需要悬浮录音条或实时字幕可在 default.toml 中移除对应的allow-floating-bar-*、allow-live-caption-*权限或在 capability 中改用更严格的 windows 权限组合缩小命令暴露面。利用 deny 优先语义schema 约定同一命令同时出现 allow/deny 时按拒绝处理可用来对特定窗口做「默认放行、个别拒绝」的例外管理。注意平台差异floating_bar_current_state在 macOS 平台返回None原生面板不维护 Rust 侧状态live caption 在非 macOS 平台update实际执行隐藏逻辑见 live_caption.rs 的平台分叉配置权限时应结合目标平台的真实行为。保留 WebView 健康检查权限webview_health_ack/webview_health_ready是崩溃恢复流程的一部分若被 denyWebView 探活将无法闭环建议保留在默认集中。七、参考文件速查权限参考主文档plugins/windows/permissions/autogenerated/reference.md默认权限集源定义plugins/windows/permissions/default.toml权限文件 JSON Schemaplugins/windows/permissions/schemas/schema.json单命令权限示例plugins/windows/permissions/autogenerated/commands/floating_bar_show.toml命令注册与状态管理plugins/windows/src/lib.rs命令实现plugins/windows/src/commands.rs事件定义与解析plugins/windows/src/events.rs悬浮条 / 实时字幕面板plugins/windows/src/window/floating_bar.rs、plugins/windows/src/window/live_caption.rs前端命令代理与初始化plugins/windows/js/bindings.gen.ts、plugins/windows/js/index.ts桌面端 capability 配置apps/desktop/src-tauri/capabilities/default.json【免费下载链接】anarlogOpen source Granola AI Alternative项目地址: https://gitcode.com/GitHub_Trending/hy/anarlog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考