Jan MLX 插件的 Tauri 权限体系：默认权限集、命令清单与 macOS 本地推理的权限边界

本文以 Jan 项目中 MLX 插件的权限参考文档为核心，系统讲解 tauri-plugin-mlx 的默认权限集（Default Permission Set）构成、八组 allow/deny 权限标识符与底层命令的一一映射，以及权限声明如何与 capabilities 配置、Rust 命令实现和前端 JS 封装协同工作。读完本文，你将能准确理解 Jan 在 Apple Silicon（macOS）平台上管理 MLX 模型子进程时的权限边界，并知道如何按需要为插件收紧或放宽特定命令的调用权限。

插件与权限模型概述

MLX 插件是 Jan 中负责在 macOS 上启动、查询和回收 mlx-server 子进程的 Tauri 插件。从 lib.rs 可以看到，插件通过 Builder::new("mlx") 注册，名称即为 mlx，因此前端调用命令时的 invoke 标识统一为 plugin:mlx|<命令名>（例如 guest-js/index.ts 中的 'plugin:mlx|load_mlx_model'）。

Tauri 的权限机制要求每个命令默认不可调用，必须通过 capability 文件显式授予。权限参考文档 reference.md 定义了该插件的 Default Permission：一个名为 mlx:default 的权限集，将插件全部 8 个命令打包为一个授权单元。

默认权限集：mlx:default 包含什么

参考文档的 "Default Permission" 一节声明，默认权限集 "Default permissions for the MLX plugin" 包含以下 8 个权限标识符：

• allow-cleanup-mlx-processes
• allow-load-mlx-model
• allow-unload-mlx-model
• allow-is-mlx-process-running
• allow-get-mlx-random-port
• allow-find-mlx-session-by-model
• allow-get-mlx-loaded-models
• allow-get-mlx-all-sessions

这与插件根目录下的 default.toml 完全一致：

[default]
description = "Default permissions for the MLX plugin"
permissions = [
    "allow-cleanup-mlx-processes",
    "allow-load-mlx-model",
    "allow-unload-mlx-model",
    "allow-is-mlx-process-running",
    "allow-get-mlx-random-port",
    "allow-find-mlx-session-by-model",
    "allow-get-mlx-loaded-models",
    "allow-get-mlx-all-sessions",
]

而在 capabilities/mlx.json 中，Jan 的授权配置为：

{
  "identifier": "mlx",
  "description": "MLX plugin permissions (Apple Silicon / macOS only)",
  "windows": ["main"],
  "platforms": ["macOS"],
  "permissions": ["mlx:default"]
}

这段配置说明了三件事：mlx:default 权限集仅授予 main 窗口；仅在 macOS 平台生效（与 MLX 运行在 Apple Silicon 的约束一致）；粒度是"整组授予"，即一次授权即解锁全部 8 个命令。

权限表全解析：16 个标识符与 8 个命令的映射

参考文档的 "Permission Table" 以 allow/deny 成对形式列出了 16 个标识符。每个命令对应一个 allow-* 与一个 deny-* 标识符，描述均为 "Enables/Denies the <命令> command without any pre-configured scope"（启用/禁用该命令，且不携带任何预配置 scope）。完整映射如下：

权限标识符（前缀 mlx:）	对应命令	命令功能	源码实现
allow/deny-cleanup-mlx-processes	cleanup_mlx_processes	批量终止所有 MLX 服务进程	cleanup.rs
allow/deny-find-mlx-session-by-model	find_mlx_session_by_model	按 model_id 查找会话	process.rs
allow/deny-get-mlx-all-sessions	get_mlx_all_sessions	获取全部活跃会话	process.rs
allow/deny-get-mlx-loaded-models	get_mlx_loaded_models	获取已加载模型 ID 列表	process.rs
allow/deny-get-mlx-random-port	get_mlx_random_port	获取未被占用的随机端口	process.rs
allow/deny-is-mlx-process-running	is_mlx_process_running	检查指定 PID 进程是否存活	process.rs
allow/deny-load-mlx-model	load_mlx_model	启动一个 MLX 服务子进程并等待就绪	commands.rs
allow/deny-unload-mlx-model	unload_mlx_model	优雅终止指定 PID 的子进程	commands.rs

这 8 个标识符的定义由 Tauri 代码生成工具写入 permissions/autogenerated/commands/ 目录下的 TOML 文件（文件头部标注 "Automatically generated - DO NOT EDIT!"）。以 load_mlx_model.toml 为例：

[[permission]]
identifier = "allow-load-mlx-model"
description = "Enables the load_mlx_model command without any pre-configured scope."
commands.allow = ["load_mlx_model"]

[[permission]]
identifier = "deny-load-mlx-model"
description = "Denies the load_mlx_model command without any pre-configured scope."
commands.deny = ["load_mlx_model"]

其中 commands.allow / commands.deny 就是 Tauri 权限机制的核心字段：它把逻辑上的权限标识符绑定到真实的后端命令白名单/黑名单上。由于所有命令都不涉及文件路径或资源范围，参考文档才统一说明 "without any pre-configured scope"——这些权限只有"允许/拒绝"两态，不存在路径 scope 之类的细化维度。

八个命令的行为细节

理解了"权限 → 命令"的映射后，下面结合源码逐组说明每个命令的实际行为，这决定了你在 capability 中授予它们时实际放开了什么能力。

load_mlx_model：进程生命周期管理的入口

load_mlx_model 是最核心的写操作权限。其 Tauri 命令包装器（commands.rs）先从 Tauri 的 resource_dir 定位捆绑的二进制 resources/bin/mlx-server，再委托给与 AppHandle 解耦的核心实现 load_mlx_model_impl。核心流程包括：

1. 参数校验：二进制路径不存在返回 BINARY_NOT_FOUND，模型文件不存在返回 MODEL_FILE_NOT_FOUND（见 error.rs 的错误码枚举）；
2. 命令行组装：传入 --model、--port、--model-id；当 config.ctx_size > 0 时追加 --ctx-size；当环境变量中存在 MLX_API_KEY 时追加 --api-key（commands.rs）；
3. 就绪探测：并发读取子进程 stdout/stderr，匹配 "http server listening"、"server is listening"、"server started"、"ready to accept" 等日志关键字判定服务就绪；
4. 超时回收：在 timeout（秒）内未就绪则 kill 子进程并返回 MODEL_LOAD_TIMED_OUT，details 中附带超时时长与 stderr 内容；
5. 会话登记：成功就绪后以 PID 为键将 MlxBackendSession{child, info} 写入共享会话表 MlxState（state.rs），SessionInfo 记录 pid、port、model_id、model_path、is_embedding、api_key。

unload_mlx_model 与 cleanup_mlx_processes：优雅终止的两档粒度

• unload_mlx_model（commands.rs）按 PID 从会话表中移除指定进程，在 Unix/macOS 上先发送 SIGTERM，等待 5 秒后未退出再升级 SIGKILL（process.rs 的 graceful_terminate_process）；若 PID 不存在也返回成功，行为幂等；
• cleanup_mlx_processes（cleanup.rs）则是全量版本：遍历会话表逐个 SIGTERM，等待窗口缩短为 2 秒，超时后 SIGKILL。它通常用于应用退出前的进程回收。

从源码结构看，两个命令共享同一套信号终止逻辑，差异仅在作用范围与超时时长。

会话查询类命令：只读能力

• is_mlx_process_running：基于 sysinfo 检查 PID 是否存活；若进程已死，会顺带从会话表中清理该条目（process.rs）——这是一个"查询兼垃圾回收"的副作用；
• get_mlx_random_port：收集会话表中已占用的端口，交给 jan_utils::generate_random_port 生成不冲突的随机端口（process.rs），保证多模型并发加载时端口互不碰撞；
• find_mlx_session_by_model：按 model_id 精确匹配，返回 Option<SessionInfo>，前端可用它判断"模型是否已加载"以复用已有会话；
• get_mlx_loaded_models / get_mlx_all_sessions：分别返回所有已加载 model_id 列表和完整的 SessionInfo 数组（含端口、模型路径、api_key），是前端模型管理界面的数据来源。

前端 JS 封装层

插件在 guest-js/index.ts 中导出了与 8 个后端命令一一对应的 7 个 TypeScript 函数（cleanup_mlx_processes 未在此文件导出，直接由应用层按需调用）：

export async function loadMlxModel(
  modelId: string,
  modelPath: string,
  port: number,
  cfg: MlxConfig,
  envs: Record<string, string>,
  isEmbedding: boolean = false,
  timeout: number = 600
): Promise<SessionInfo> {
  const config = normalizeMlxConfig(cfg)
  return await invoke('plugin:mlx|load_mlx_model', {
    modelId, modelPath, port, config, envs, isEmbedding, timeout,
  })
}

注意 normalizeMlxConfig 会把非法 ctx_size 兜底为 0（即不传 --ctx-size），timeout 默认 600 秒。这些函数内部的每次 invoke 都会经过 Tauri 的 IPC 权限网关：如果当前 capability 没有授予对应命令的 allow 权限，调用会在前端直接失败，根本不会到达 Rust 侧。

权限配置实践：如何按需收紧

理解了默认权限集的打包方式后，可以归纳 Jan 当前对 MLX 插件的授权策略与可选的收紧方式：

• 现状（整组授权）：mlx.json 授予 mlx:default，等效于对 main 窗口一次性放开全部 8 个命令。由于平台限定为 macOS，非 Mac 环境下该 capability 不生效，权限本身不会造成跨平台风险；
• 按需裁剪（可推断的扩展方式）：Tauri 允许在 capability 的 permissions 数组中改用细粒度标识符，例如只授予 "mlx:allow-get-mlx-loaded-models" 与 "mlx:allow-find-mlx-session-by-model" 两个只读查询权限，同时不授予 allow-load-mlx-model，即可实现"只能查看、不能加载模型"的受限窗口；反过来，对某个非 main 窗口声明 "mlx:deny-load-mlx-model" 也能显式拒绝该命令；
• 错误模型作为纵深防线：即便权限放行，Rust 侧仍会进行二进制路径、模型文件存在性、加载超时、内存不足（stderr 中出现 "out of memory" 等关键字会映射为 OutOfMemory 错误码，见 error.rs）等运行时校验。权限控制"能不能调"，错误模型控制"调了之后会发生什么"，两层机制相互独立。

小结

tauri-plugin-mlx 的权限参考文档虽由代码生成工具产出，但它精确刻画了 Jan 对 macOS 本地推理进程的管理面：mlx:default 默认权限集将"加载、卸载、存活检查、随机端口、会话查询、批量清理"八类命令打包授权；每个命令都有 allow/deny 成对标识符且无 scope 维度；而 capabilities/mlx.json 中的 windows/platforms 约束进一步把授权范围收敛到 macOS 主窗口。对于需要在 Jan 之上做二次开发或审计权限边界的开发者，这条"reference.md → default.toml → autogenerated/commands/*.toml → capability JSON → Rust 命令实现"的链路就是完整的溯源路径。