anarlog windows 插件权限体系解析：Tauri 命令 ACL 参考与实践指南
【免费下载链接】anarlogOpen source Granola AI Alternative项目地址: https://gitcode.com/GitHub_Trending/hy/anarlog
本篇技术指南围绕 anarlog 桌面端windows（tauri-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-occluded | window_show/window_hide/window_destroy/window_navigate/window_emit_navigate/window_is_exists/window_is_occluded |
| WebView 健康检查 | allow-webview-health-ack/allow-webview-health-ready | webview_health_ack/webview_health_ready |
| 窗口帧动画 | allow-window-set-frame-animated/allow-window-save-frame/allow-window-restore-frame-animated | window_set_frame_animated/window_save_frame/window_restore_frame_animated |
| 窗口宽度扩展 | allow-window-expand-width/allow-window-restore-width | window_expand_width/window_restore_width |
| Dock 图标 | allow-set-show-app-in-dock | 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 | floating_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-state | live_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_state | windows:allow-floating-bar-current-state | windows:deny-floating-bar-current-state | 查询悬浮条当前状态 |
floating_bar_hide | windows:allow-floating-bar-hide | windows:deny-floating-bar-hide | 隐藏悬浮条 |
floating_bar_show | windows:allow-floating-bar-show | windows:deny-floating-bar-show | 显示悬浮条 |
floating_bar_update | windows:allow-floating-bar-update | windows:deny-floating-bar-update | 更新悬浮条状态 |
floating_bar_update_amplitude | windows:allow-floating-bar-update-amplitude | windows:deny-floating-bar-update-amplitude | 更新悬浮条音频振幅 |
live_caption_current_state | windows:allow-live-caption-current-state | windows:deny-live-caption-current-state | 查询实时字幕状态 |
live_caption_hide | windows:allow-live-caption-hide | windows:deny-live-caption-hide | 隐藏实时字幕 |
live_caption_show | windows:allow-live-caption-show | windows:deny-live-caption-show | 显示实时字幕 |
live_caption_update | windows:allow-live-caption-update | windows:deny-live-caption-update | 更新实时字幕状态 |
remove_fake_window | windows:allow-remove-fake-window | windows:deny-remove-fake-window | 移除 fake window（默认未启用） |
set_fake_window_bounds | windows:allow-set-fake-window-bounds | windows:deny-set-fake-window-bounds | 设置 fake window 边界（默认未启用） |
set_show_app_in_dock | windows:allow-set-show-app-in-dock | windows:deny-set-show-app-in-dock | 控制 Dock 中是否显示应用图标 |
webview_health_ack | windows:allow-webview-health-ack | windows:deny-webview-health-ack | 应答 WebView 健康检查 |
webview_health_ready | windows:allow-webview-health-ready | windows:deny-webview-health-ready | 标记 WebView 健康检查就绪 |
window_destroy | windows:allow-window-destroy | windows:deny-window-destroy | 销毁窗口 |
window_emit_navigate | windows:allow-window-emit-navigate | windows:deny-window-emit-navigate | 向窗口发出导航事件 |
window_expand_width | windows:allow-window-expand-width | windows:deny-window-expand-width | 扩展窗口宽度 |
window_hide | windows:allow-window-hide | windows:deny-window-hide | 隐藏窗口 |
window_is_exists | windows:allow-window-is-exists | windows:deny-window-is-exists | 查询窗口是否存在 |
window_is_occluded | windows:allow-window-is-occluded | windows:deny-window-is-occluded | 查询窗口是否被遮挡 |
window_navigate | windows:allow-window-navigate | windows:deny-window-navigate | 窗口内导航到指定路径 |
window_restore_frame_animated | windows:allow-window-restore-frame-animated | windows:deny-window-restore-frame-animated | 动画恢复已保存的窗口帧 |
window_restore_width | windows:allow-window-restore-width | windows:deny-window-restore-width | 恢复扩展前的窗口宽度 |
window_save_frame | windows:allow-window-save-frame | windows:deny-window-save-frame | 保存当前窗口帧 |
window_set_frame_animated | windows:allow-window-set-frame-animated | windows:deny-window-set-frame-animated | 按锚点动画设置窗口帧 |
window_show | windows:allow-window-show | windows: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实现把枚举映射为窗口 label：main、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?calendarEventId=123&record=true形式的 URL 解析为{ path: "/app/new", search: {...} }，单元测试navigate_from_str` 验证了这一解析逻辑。
4.2 WebView 健康检查：ack 与 ready
allow-webview-health-ack与allow-webview-health-ready背后是插件内建的 WebView 探活机制。核心状态WebviewHealthState（lib.rs）维护pending（待应答的探针注册表）与recovering（恢复中窗口集合）：
register：为窗口生成自增registration_id与 UUIDrequest_id，同一窗口只允许一个探针在途，恢复期间不允许注册；acknowledge：只有request_id完全匹配的应答才会解除挂起状态（对应webview_health_ack命令）；begin_recovery/ready：进入恢复流程后阻塞新探针，webview_health_ready命令负责标记恢复完成。
前端配合逻辑位于 js/index.ts：init()中监听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_animated（commands.rs）接收anchor（TopRight/TopLeft/BottomRight/BottomLeft/Center）、width、height，基于可见帧计算目标位置（屏幕边距固定为8.0），保存帧后调用set_frame_animated做动画过渡；主窗口还会临时置顶（set_always_on_top(true)）。window_save_frame将当前帧存入SavedFrames状态（Mutex<HashMap<String, SavedFrame>>），window_restore_frame_animated取回帧并动画恢复，同时取消主窗口的置顶。window_expand_width（commands.rs）参数较丰富：expansion_px（扩展像素）、max_current_width（最大宽度上限，可选）、check_monitor_space（是否检查显示器右侧剩余空间）、expand_left（向左扩展还是向右）、restore_on_close（是否记录以便恢复）。非 macOS 平台直接通过set_size调整物理尺寸，macOS 平台则在主线程通过 objc2 操作NSWindow的 frame；WindowExpansions状态以Vec<(old_w, new_w, expand_left)>记录历史，window_restore_width弹栈还原。
4.4 悬浮录音条（floating bar）与实时字幕（live caption）
floating_bar_*四个命令对应 floating_bar.rs：FloatingBarState携带amplitude、title、status（Recording/Error）、color_scheme（Light/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.rs，LiveCaptionState包含text、opacity、width、line_count、position（六种位置枚举）与minimized；layout模块将宽度约束在 260～640px、行数约束在 1～4 行，并按 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是崩溃恢复流程的一部分，若被 deny，WebView 探活将无法闭环，建议保留在默认集中。
七、参考文件速查
- 权限参考主文档：plugins/windows/permissions/autogenerated/reference.md
- 默认权限集源定义：plugins/windows/permissions/default.toml
- 权限文件 JSON Schema：plugins/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），仅供参考
