Jan 向量数据库插件的 Tauri 权限体系：vector-db 权限参考文档深度解析

本文以 Jan 仓库中 src-tauri/plugins/tauri-plugin-vector-db/permissions/autogenerated/reference.md 权限参考文档为主体，完整讲解 vector-db 插件的默认权限集、全部 allow/deny 权限标识符及其对应的 Tauri 命令；结合插件的 Rust 源码与 Guest JS API，说明每个权限背后实际开放的底层能力，以及应用如何在 capability 配置中启用、裁剪这些权限。读完后你可以准确理解 Jan RAG 检索链路的权限边界，并会针对自定义窗口或最小权限场景配置 vector-db:* 权限。

参考文档的来源与定位

reference.md 是 Tauri v2 插件权限系统的自动生成参考文档，位于 permissions/autogenerated/reference.md。它与同目录下各命令的 TOML 文件（如 chunk_text.toml）一样，头部带有“Automatically generated - DO NOT EDIT!”标记，且每个 TOML 都声明了 "$schema" = "../../schemas/schema.json"，指向 schemas/schema.json。这意味着：

• 文档内容跟随插件源码中的命令注册（#[tauri::command]）自动重新生成，开发者不应手工修改；
• 文档中每一条 vector-db:allow-* / vector-db:deny-* 标识符都在对应 TOML 中有精确的 commands.allow / commands.deny 定义；
• 它是编写 capability 文件时的权威速查表——你在 JSON 里能引用的每一个权限字符串，都必须出自这份表格。

reference.md 的组织结构分为两部分：Default Permission（默认权限集）和 Permission Table（完整权限表）。下面逐一展开。

默认权限集：vector-db:default

文档第一部分声明了插件的默认权限集，即引用 "vector-db:default" 时一次性放开的 11 个权限：

allow-get-status
allow-create-collection
allow-insert-chunks
allow-create-file
allow-search-collection
allow-delete-chunks
allow-delete-file
allow-delete-collection
allow-chunk-text
allow-list-attachments
allow-get-chunks

这一声明的机器可读形式在同目录的 default.toml 中：

[default]
description = "Default permissions for the vector-db plugin"
permissions = [
  "allow-get-status",
  "allow-create-collection",
  "allow-insert-chunks",
  "allow-create-file",
  "allow-search-collection",
  "allow-delete-chunks",
  "allow-delete-file",
  "allow-delete-collection",
  "allow-chunk-text",
  "allow-list-attachments",
  "allow-get-chunks",
]

从这 11 个权限可以读出一个清晰的产品意图：Jan 的向量数据库插件覆盖了 RAG（检索增强生成）的完整生命周期——探测 ANN 可用性（get_status）、建集合（create_collection）、登记附件文件（create_file）、写入分块与向量（insert_chunks）、语义检索（search_collection）、列举附件（list_attachments）、按区间读取分块（get_chunks）、以及三级删除（delete_chunks / delete_file / delete_collection），再加上纯本地的文本分块工具（chunk_text）。默认集“全量放行”符合桌面主应用的信任模型：主窗口需要端到端使用本地知识库。

Jan 的主应用也确实这样做了。在 capabilities/default.json 中，主窗口（"windows": ["main"]）的权限数组包含 "vector-db:default"（第 28 行），与 "rag:default"、"llamacpp:default" 等插件默认集并列，且该 capability 还开放了 remote.urls: ["http://*"] 供远程页面调用。也就是说，Jan 官方配置并未做细粒度裁剪，而是直接引用默认集；reference.md 的价值在于：当你想为某个窗口（例如独立的日志窗口、系统监控窗口，见同目录的 logs-window.json、system-monitor-window.json）或第三方嵌入场景做最小权限授权时，可以基于权限表精确挑选条目。

完整权限表（Permission Table）

文档第二部分是一张两列权限表（Identifier / Description），HTML 表格共含 14 组权限，每组由一个 allow 与一个 deny 构成。这里完整继承为 Markdown 表格，描述均取自原文档：

Identifier	Description
vector-db:allow-chunk-text	Enables the chunk_text command without any pre-configured scope.
vector-db:deny-chunk-text	Denies the chunk_text command without any pre-configured scope.
vector-db:allow-create-collection	Enables the create_collection command without any pre-configured scope.
vector-db:deny-create-collection	Denies the create_collection command without any pre-configured scope.
vector-db:allow-create-file	Enables the create_file command without any pre-configured scope.
vector-db:deny-create-file	Denies the create_file command without any pre-configured scope.
vector-db:allow-delete-chunks	Enables the delete_chunks command without any pre-configured scope.
vector-db:deny-delete-chunks	Denies the delete_chunks command without any pre-configured scope.
vector-db:allow-delete-collection	Enables the delete_collection command without any pre-configured scope.
vector-db:deny-delete-collection	Denies the delete_collection command without any pre-configured scope.
vector-db:allow-delete-file	Enables the delete_file command without any pre-configured scope.
vector-db:deny-delete-file	Denies the delete_file command without any pre-configured scope.
vector-db:allow-get-chunks	Enables the get_chunks command without any pre-configured scope.
vector-db:deny-get-chunks	Denies the get_chunks command without any pre-configured scope.
vector-db:allow-get-status	Enables the get_status command without any pre-configured scope.
vector-db:deny-get-status	Denies the get_status command without any pre-configured scope.
vector-db:deny-insert-chunks	Denies the insert_chunks command without any pre-configured scope.
vector-db:allow-list-attachments	Enables the list_attachments command without any pre-configured scope.
vector-db:deny-list-attachments	Denies the list_attachments command without any pre-configured scope.
vector-db:allow-memory-clear	Enables the memory_clear command without any pre-configured scope.
vector-db:deny-memory-clear	Denies the memory_clear command without any pre-configured scope.
vector-db:allow-memory-index	Enables the memory_index command without any pre-configured scope.
vector-db:deny-memory-index	Denies the memory_index command without any pre-configured scope.
vector-db:allow-memory-search	Enables the memory_search command without any pre-configured scope.
vector-db:deny-memory-search	Denies the memory_search command without any pre-configured scope.
vector-db:allow-search-collection	Enables the search_collection command without any pre-configured scope.
vector-db:deny-search-collection	Denies the search_collection command without any pre-configured scope.

“without any pre-configured scope” 的措辞值得注意：当前版本的 vector-db 命令不带 scope（范围）参数，权限开关是命令级的二值授权，而不是像文件系统插件那样按路径 scope 细分。这与源码一致——commands.rs 中所有命令的参数均为业务参数（collection、file_id、嵌入向量等），没有 Tauri scope 注入。

权限到命令的三层调用链

每条权限标识符最终保护的是一个 Tauri 命令。在 Jan 中，这条链路分三层：

1. Guest JS 层：guest-js/index.ts（npm 包名 @janhq/tauri-plugin-vector-db-api，见 package.json）导出强类型函数，通过 invoke('plugin:vector-db|<command>') 发起调用。例如：

export async function searchCollection(
  collection: string,
  queryEmbedding: number[],
  limit: number,
  threshold: number,
  mode?: SearchMode,   // 'auto' | 'ann' | 'linear'
  fileIds?: string[]
): Promise<SearchResult[]> {
  return await invoke('plugin:vector-db|search_collection', {
    collection, queryEmbedding, limit, threshold, mode, fileIds,
  })
}

2. 命令注册层：Rust 侧 lib.rs 中 Builder::new("vector-db") 声明插件名，invoke_handler 注册了 11 个命令：create_collection、insert_chunks、create_file、search_collection、delete_chunks、delete_file、delete_collection、chunk_text、get_status、list_attachments、get_chunks。插件前缀 vector-db: 即由此而来，权限表中的命令名与这里一一对应。

3. 实现层：commands.rs 中每个 #[tauri::command] 通过 State<'_, VectorDBState> 拿到基础目录，再委托给 db.rs 操作 SQLite（含 sqlite-vec 向量扩展）。

各命令被权限保护后的实际参数与语义（取自 commands.rs 签名）：

命令（受保护标识符）	参数	说明
get_status	无	探测 sqlite-vec 是否可用，返回 { ann_available: bool }（commands.rs#L26-L65）
create_collection	name: String, dimension: usize	按嵌入维度创建集合；ANN 不可用时降级为线性检索并打印告警
create_file	collection: String, file: FileInput{path, name?, type?, size?}	在集合中登记附件，返回 AttachmentFileInfo
insert_chunks	collection, file_id, chunks: Vec<{text, embedding}>	写入文本分块及其向量
search_collection	collection, query_embedding: Vec<f32>, limit: usize, threshold: f32, mode: Option<'auto'|'ann'|'linear'>, file_ids: Option<Vec<String>>	向量相似度检索，可按附件 id 过滤
list_attachments	collection, limit: Option<usize>	列举附件及其 chunk_count
get_chunks	collection, file_id, start_order: i64, end_order: i64	按分块顺序区间读取原文分块
delete_chunks	collection, ids: Vec<String>	按 id 批量删除分块
delete_file	collection, file_id	删除某附件的全部分块
delete_collection	collection	直接删除集合对应的 SQLite 文件（commands.rs#L172-L183）
chunk_text	text: String, chunk_size: usize, chunk_overlap: usize	纯文本分块，不访问状态，返回分块数组

值得注意的是，所有涉及数据文件的命令都以 state.base_dir 为根：state.rs 中 VectorDBState::new() 将基础目录固定为系统数据目录下的 Jan/data/db，每个 collection 映射为该目录下独立的一个 SQLite 文件。因此“放开 allow-* 权限”的实质风险面是本机 Jan 数据目录中的向量库文件，而不是任意路径——这也是为什么 Tauri 权限系统无需再叠加路径 scope。

三个默认集之外的 memory-* 权限

对照可见：权限表共 14 组，而默认集只有 11 组，多出的是 allow-memory-clear、allow-memory-index、allow-memory-search 三组 memory_* 权限。从当前源码结构看，lib.rs 的 invoke_handler 并未注册 memory_clear、memory_index、memory_search 命令，commands.rs 中也不存在对应实现。可以推断这组权限来自插件早期的“memory”接口命名，后来被 collection/file/chunk 模型取代；由于权限生成器按历史命令清单产出，它们仍保留在参考表中。实践含义是：引用这三个 allow-* 不会报错，但也无法解锁任何当前存在的命令；新代码只应使用默认集中的 11 个权限。

在 capability 中使用与裁剪权限

理解了默认集与完整表之后，配置方式就很简单。Tauri v2 中权限只在 capability 文件（本项目为 src-tauri/capabilities/*.json）中生效，核心字段是 windows（作用窗口）、permissions（权限数组）与可选的 remote.urls。基于 reference.md 的速查，几种典型写法：

1. 完整功能（Jan 官方做法）——直接引用默认集：

{
  "identifier": "rag-enabled-window",
  "windows": ["main"],
  "permissions": ["vector-db:default"]
}

2. 只读检索窗口——只放行读取与探测类命令：

{
  "identifier": "rag-read-only",
  "windows": ["some-window"],
  "permissions": [
    "vector-db:allow-get-status",
    "vector-db:allow-list-attachments",
    "vector-db:allow-search-collection",
    "vector-db:allow-get-chunks"
  ]
}

3. 显式拒绝——利用 deny-* 标识符（Tauri 遵循 deny 优先的求值规则）：

{
  "identifier": "no-write-rag",
  "windows": ["some-window"],
  "permissions": [
    "vector-db:default",
    "vector-db:deny-insert-chunks",
    "vector-db:deny-delete-collection"
  ]
}

由于命令不带 scope，“最小权限”的粒度就是单条命令。比如 delete_collection 会直接删除磁盘上的 SQLite 文件（commands.rs#L172-L183），在只读或协作场景中是首先考虑 deny 的候选；get_status 与 chunk_text 则相对无害，前者仅做临时探测表，后者是纯内存文本切分。

小结

vector-db 插件的权限参考文档是 Jan 本地 RAG 能力的安全契约层：

• reference.md 列出 14 组 allow/deny 权限标识符，其中 11 组由 default.toml 聚合成 vector-db:default 默认集；
• 权限标识符经 lib.rs 注册的 invoke_handler 映射到 commands.rs 的具体命令，前端统一通过 guest-js/index.ts 的类型化 API（plugin:vector-db|* 通道）调用；
• Jan 主窗口在 capabilities/default.json 中以 "vector-db:default" 全量启用；自定义窗口可依据本文的权限表做只读或禁止写入的裁剪；
• 表中的三组 memory-* 权限在现行命令注册中已无对应实现，属于生成器保留的历史条目，新配置不应依赖它们。

相关源码入口：插件 Rust 实现 src-tauri/plugins/tauri-plugin-vector-db/src/、权限定义 permissions/、能力声明 src-tauri/capabilities/default.json，以及消费该 Guest API 的扩展 extensions/vector-db-extension/src/index.ts（其单测见 extensions/vector-db-extension/src/index.test.ts）。