Jan 的 tauri-plugin-llamacpp 权限体系详解47 个本地 LLM 推理权限的完整参考与生成机制【免费下载链接】janJan is an open source alternative to ChatGPT that runs 100% offline on your computer.项目地址: https://gitcode.com/GitHub_Trending/ja/jan本文基于 Jan 仓库中src-tauri/plugins/tauri-plugin-llamacpp/permissions/autogenerated/reference.md这份自动生成的权限参考文档展开系统梳理 llamacpp 插件的全部 47 个默认权限、allow/deny 成对授权的命名规范并对照 build.rs、lib.rs 与能力配置capabilities说明这些权限是如何被生成、注册并下发给各窗口的。读完后你可以精确掌握 Jan 本地推理层前端调用后端命令的授权边界以及如何在 Tauri 插件中排查“命令 not allowed”类运行时问题。一、这份权限参考文档定位在哪一层Jan 是一个完全在本地运行的离线聊天应用其本地 LLM 推理能力由 Tauri 插件tauri-plugin-llamacpp提供前端 web-app 通过invoke调用 Rust 侧命令完成 llama.cpp 后端进程的加载/卸载、推理服务路由router管理、GGUF 模型元数据解析以及推理后端backend的安装、校验与更新。由于 Tauri 的安全模型要求「每条命令默认不可达除非被能力文件显式授权」插件必须为每个可调用命令生成一组权限标识符permission identifier。reference.md正是 Tauri 插件构建脚本自动生成文件头部标注Automatically generated风格的产物位于 permissions/autogenerated/reference.md的权限清单它回答三个问题默认权限集llamacpp:default包含哪些权限每个权限标识符如llamacpp:allow-load-llama-model对应哪条 Rust 命令、语义是什么allow 与 deny 的成对关系每个命令恰好对应一个allow-*和一个deny-*标识符。二、Default Permission默认权限集完整清单参考文档开头的 “Default Permission” 一节声明llamacpp插件的默认权限集即llamacpp:default包含 47 个权限。与默认集一一对应的源文件是 permissions/default.toml其中按功能分为五组注释即分组依据2.1 进程清理组Cleanup权限标识符对应命令作用llamacpp:allow-cleanup-llama-processescleanup_llama_processes清理残留的 llama 进程该命令实现位于 src/cleanup.rs并在 lib.rs 中通过pub use cleanup::cleanup_llama_processes;对外导出供应用主进程复用。2.2 LlamaCpp 服务与 Router 组20 个这一组是插件的核心运行时能力覆盖推理会话的加载、路由管理与进程探活权限标识符对应命令作用llamacpp:allow-load-llama-modelload_llama_model加载 GGUF 模型并启动/接入推理会话llamacpp:allow-unload-llama-modelunload_llama_model卸载模型、释放会话llamacpp:allow-start-routerstart_router启动 router 模式推理服务llamacpp:allow-stop-routerstop_router停止 routerllamacpp:allow-try-graceful-stop-routertry_graceful_stop_router尝试优雅停止 routerllamacpp:allow-force-kill-router-treeforce_kill_router_tree强杀 router 进程树llamacpp:allow-get-router-infoget_router_info获取 router 运行信息llamacpp:allow-reload-router-modelsreload_router_models重新加载 router 上的模型列表llamacpp:allow-router-slots-idlerouter_slots_idle查询 router 空闲 slotllamacpp:allow-router-healthrouter_health探活 router 健康状态llamacpp:allow-adopt-routeradopt_router接管一个已存在的 router 实例llamacpp:allow-get-devicesget_devices枚举 GPU/CPU 设备信息llamacpp:allow-generate-api-keygenerate_api_key生成本地推理服务的 API Keyllamacpp:allow-is-process-runningis_process_running判断指定进程是否在运行llamacpp:allow-ensure-session-readyensure_session_ready确保目标模型所在会话就绪llamacpp:allow-get-random-portget_random_port获取随机可用端口llamacpp:allow-find-session-by-modelfind_session_by_model按模型查找会话llamacpp:allow-get-loaded-modelsget_loaded_models列出已加载模型llamacpp:allow-get-all-sessionsget_all_sessions列出全部会话llamacpp:allow-get-session-by-modelget_session_by_model按模型名取会话router 相关命令的实现在 src/router.rs 与 src/commands.rs 中build.rs 的注释将其标注为 “Router-mode commands (Phase 1)”。2.3 GGUF 模型元数据组4 个权限标识符对应命令作用llamacpp:allow-read-gguf-metadataread_gguf_metadata读取 GGUF 文件的元数据张量、架构等llamacpp:allow-estimate-kv-cache-sizeestimate_kv_cache_size估算 KV Cache 内存占用用于显存/内存规划llamacpp:allow-get-model-sizeget_model_size获取模型文件大小llamacpp:allow-is-model-supportedis_model_supported判断当前后端是否支持该模型这组命令位于 src/gguf/commands.rs在 lib.rs 中以gguf::commands::前缀注册。2.4 后端管理组Backend Management14 个权限标识符对应命令作用llamacpp:allow-map-old-backend-to-newmap_old_backend_to_new将旧版后端标识映射为新标识llamacpp:allow-get-local-installed-backendsget_local_installed_backends列出本机已安装的后端llamacpp:allow-list-supported-backendslist_supported_backends列出受支持的后端清单llamacpp:allow-determine-supported-backendsdetermine_supported_backends根据当前机器环境判定可用后端llamacpp:allow-get-supported-featuresget_supported_features获取后端支持的特性如 flash attention 等llamacpp:allow-is-cuda-installedis_cuda_installed检测 CUDA 是否安装llamacpp:allow-find-latest-version-for-backendfind_latest_version_for_backend查找某后端的最新版本llamacpp:allow-prioritize-backendsprioritize_backends对候选后端排序/定优先级llamacpp:allow-parse-backend-versionparse_backend_version解析后端版本字符串llamacpp:allow-check-backend-for-updatescheck_backend_for_updates检查后端是否有更新llamacpp:allow-remove-old-backend-versionsremove_old_backend_versions移除旧版本后端llamacpp:allow-validate-backend-stringvalidate_backend_string校验version/backend字符串格式llamacpp:allow-should-migrate-backendshould_migrate_backend判定是否需要迁移后端llamacpp:allow-handle-setting-updatehandle_setting_update处理设置变更并触发的后端联动这些命令集中在 src/backend.rs。与之配合的依赖分析逻辑例如运行时库校验位于 src/deps_analyzer.rs。2.5 后端路径与下载组Backend Path Download8 个权限标识符对应命令作用llamacpp:allow-get-backend-dirget_backend_dir获取后端的安装目录llamacpp:allow-get-backend-exe-pathget_backend_exe_path获取后端可执行文件路径llamacpp:allow-check-backend-installedcheck_backend_installed检查后端是否已安装llamacpp:allow-verify-backend-installationverify_backend_installation校验后端安装的完整性llamacpp:allow-fetch-remote-supported-backendsfetch_remote_supported_backends拉取远端受支持后端清单llamacpp:allow-build-backend-download-itemsbuild_backend_download_items构造后端下载任务项llamacpp:allow-fetch-backend-checksumsfetch_backend_checksums获取后端包的校验和llamacpp:allow-verify-file-sha512verify_file_sha512校验下载文件的 SHA-512 指纹其中fetch_backend_checksums与verify_file_sha512是下载完整性链路的最后两道关口先拉取远端公布的校验和再对本地文件做 SHA-512 比对防止损坏或被篡改的后端包被执行。三、Permission Tableallow / deny 成对授权规范参考文档的 “Permission Table” 一节约 94 行表格逐条给出每个权限的 Identifier 与 Description。其模式高度规整命名规范llamacpp:allow|deny-snake_case 命令名转 kebab-case。例如命令check_backend_for_updates对应llamacpp:allow-check-backend-for-updates与llamacpp:deny-check-backend-for-updates两个标识符语义allow-*表示“无预置 scope 地启用该命令”deny-*表示“无预置 scope 地拒绝该命令”。由于本插件的命令均不涉及作用域scope参数权限粒度就是“整条命令开或关”与 Rust 命令一一对应47 个命令 × 2 94 个权限标识符与表格行数一致。这一规整性来自 Tauri 插件的生成机制每条权限同时落盘为独立的 TOML 文件。以 permissions/autogenerated/commands/load_llama_model.toml 为例其内容为$schema ../../schemas/schema.json [[permission]] identifier allow-load-llama-model description Enables the load_llama_model command without any pre-configured scope. commands.allow [load_llama_model] [[permission]] identifier deny-load-llama-model description Denies the load_llama_model command without any pre-configured scope. commands.deny [load_llama_model][permissions/autogenerated/commands/](https://link.gitcode.com/i/e922d0e46858851d5c23b9ca0538d5a1)目录下共有 29 个这样的文件每文件覆盖该目录下命令的 allow/deny 对配合 permissions/schemas/schema.json 供编辑器做 schema 校验。四、生成机制COMMANDS 名单、命令注册与三重一致性守卫理解这份参考文档的可靠性关键在 build.rs。它维护一份COMMANDS: [str]名单47 条分组注释与 default.toml 完全一致然后交给 Tauri 插件构建器fn main() { tauri_plugin::Builder::new(COMMANDS).build(); }tauri_plugin::Builder会在构建期自动生成permissions/autogenerated/下的命令 TOML、reference.md参考文档与 schema——这就是为什么参考文档标题声明“自动生成的默认权限集”手工编辑它没有意义正确做法是修改build.rs与default.toml。命令真正对外暴露则在 src/lib.rsinit()函数用Builder::new(llamacpp)构建插件invoke_handler(tauri::generate_handler![...])中按cleanup::、commands::、backend::、gguf::commands::四个模块前缀登记全部 47 个命令并在setup阶段把LlamacppState注入应用状态管理。更值得注意的是 lib.rs 末尾的permission_tests模块它把“文档/权限/注册三方一致”做成了编译期可执行的测试every_registered_command_has_a_permission解析generate_handler[断言每条命令的allow-*条目都在默认权限集中标识符通过allow- 下划线转连字符构造如allow-verify-file-sha512两份名单均用include_str!直接内嵌源码文本做静态比对无需启动应用即可在cargo test中运行。从源码结构看这三处名单generate_handler!、build.rs COMMANDS、default.toml与本文第二部分列出的 47 项完全锁步reference.md只是它们的文档化投影。五、权限如何落地到窗口capabilities 能力文件Tauri 中“插件有权限”不等于“某个窗口能用”最终授权由能力capability文件完成。Jan 主应用在 src-tauri/capabilities/ 下按窗口拆分授权capabilities/default.json作用于main窗口与 capabilities/desktop.json 都整体引用llamacpp:default即一次性授予上文的完整 47 项默认权限集保证主界面可以做模型加载、router 管理、后端更新等全部本地推理操作capabilities/system-monitor-window.json系统监控窗口则只做最小化选授llamacpp:allow-get-devices与llamacpp:allow-read-gguf-metadata两条——监控窗口只需要设备信息和模型元数据不应触碰进程清理或后端下载类权限。这正是 Tauri 权限体系的用武之地同一个插件主窗口拿默认全集辅助窗口拿只读子集攻击面随窗口职责收窄。前端侧的调用入口在 guest-js/index.ts它从tauri-apps/api/core导入invoke封装各命令调用并附带normalizeLlamacppConfig等参数规范化逻辑例如check_for_updates缺省为true、timeout缺省 600 秒、models_max缺省 1与插件 npm 包 package.json 中声明的janhq/tauri-plugin-llamacpp-api依赖tauri-apps/api 2.0.0-beta.6共同构成前端 API 层。六、检索与维护视角如何使用这份参考文档对开发者而言这份reference.md有三个实用入口排查权限错误当 web-app 侧调用抛出not allowed或Command not found时先在本表中反查命令对应的allow-*标识符再确认目标窗口的 capability 文件如 capabilities/default.json是否包含llamacpp:default或对应的单条权限审计最小权限核对某窗口实际被授了哪些llamacpp:*权限判断是否存在“监控窗口能强杀 router”这类越权配置当前仓库中 system-monitor-window 只授了只读两项符合最小化原则理解命令边界每个allow-*行的 Description 直接指出其绑定的 Rust 命令名可据此跳转 src/ 下对应模块commands.rs、backend.rs、gguf/、router.rs、process.rs、device.rs阅读实现例如ensure_session_ready与router_health的探活/就绪语义、estimate_kv_cache_size的内存估算逻辑等均能在此找到对应源码。需要说明的是本文所有权限标识符、命令名与分组均以当前仓库中的 permissions/autogenerated/reference.md、permissions/default.toml 与 build.rs 为准该插件为 Tauri v2 架构tauri-apps/api 2.0.0-beta.6其权限模型default 集 按命令 allow/deny 成对 capability 按窗口授权与仓库中其他插件tauri-plugin-hardware、tauri-plugin-rag、tauri-plugin-vector-db等保持同一范式可参照同一方法阅读各自的权限文档。【免费下载链接】janJan is an open source alternative to ChatGPT that runs 100% offline on your computer.项目地址: https://gitcode.com/GitHub_Trending/ja/jan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考