在我们的项目中，omni-core（代码中对应 crate 模块名 omni_core）是作为我们本地优先架构的核心 Rust 底座基础库。
它作为一个独立的 Rust Crate，位于项目子目录 src-tauri/omni_core/ 下，并作为 Cargo Workspace 成员被 Tauri 主工程引入。下面为您梳理它的使用方法以及内部核心函数清单。
一、 omni_core 该如何使用？
我们可以直接在 Rust 侧将其当做常规库进行函数调用，也可以作为 Tauri 的 IPC 命令直接从前端（JS）侧跨端调用。
1. 基础库声明与依赖引入
在 src-tauri/Cargo.toml 中，已通过本地路径将其声明为依赖项：
[dependencies]
omni_core = { path = "omni_core" }
在主工程的 Rust 代码中，只需声明 use omni_core::{fts, storage}; 即可开始调用。
2. Tauri 框架一键点火初始化
在 src-tauri/src/main.rs 中，通过链式调用 init_omni_core() 完成初始化：
use omni_core::OmniCoreExt;
tauri::Builder::default()
.init_omni_core() // 一行代码注入 OpenDAL 共享 Operator 状态并注册 IPC 命令
.setup(|app| { ... })
3. Rust 中的常规函数调用
在主程序 src-tauri/src/lib.rs 中，您可以直接从应用 State 中获取并操作这些服务。例如，执行带乐观锁的文件写入：
// 1. 从状态机中获取 SharedOperator 存储算子
let op = app_handle.state::<storage::SharedOperator>();
// 2. 构造乐观锁存储服务
let storage_service = storage::OptimisticStorageService::new(op.inner.clone());
// 3. 执行条件乐观锁安全写入
storage_service.write_with_optimistic_lock(
"notes/my_note.md",
data_bytes,
&storage::EntityTag(expected_etag)
).await?;
二、 omni_core 都包含哪些核心函数？
omni_core 底座由三大核心模块构成。以下是公开（pub）的主要函数及结构体清单：
1. 统一接入模块: lib.rs
OmniCoreExt<R>::init_omni_core(self) -> Self
- 功能：Tauri Builder 扩展方法。初始化内存引擎作为默认的本地 OpenDAL 共享算子状态，并自动注册 download_remote_db 和 upload_local_db 跨端网络同步 Command。
2. 全文检索分词模块: fts.rs
该模块提供 SQLite FTS 5 的中文分词接口（Jieba 引擎集成）与检索式清洗防护。
JiebaTokenizer::new(stopwords_raw: &str) -> Self
- 功能：基于传入的停用词文本构建一个包含结巴分词引擎的分词器实例。
register_jieba_tokenizer(conn: &Connection, tokenizer: Box<JiebaTokenizer>) -> Result<()>
- 功能：核心 FFI 绑定函数。向指定的 SQLite 数据库连接注册名为 jieba 的自定义中文分词器，且将 x_destroy 析构钩子安全挂载到 SQLite 生命周期，规避内存泄漏。
escape_fts5_query(input: &str) -> String
- 功能：防御性检索式过滤哨兵。安全清洗或转义用户在输入框中填写的 AND、OR、NOT 关键字和未配对的双引号，防止 SQLite FTS 5 MATCH 解析崩溃。
delete_fts_record(conn: &Connection, id: i64, old_title: &str, old_content: &str) -> Result<()>
- 功能：通过向 contentless 虚拟表发送 delete 动作指令，物理移除旧分词倒排索引 Posting 记录。
update_fts_record(conn: &Connection, id: i64, old_title: &str, old_content: &str, new_title: &str, new_content: &str) -> Result<()>
- 功能：在单次原子事务中组合删除旧记录和插入新记录，安全更新虚拟表的索引记录。
3. 存储与多端同步模块: storage.rs
该模块提供基于 OpenDAL 的网络流式上传、双层防抖拓扑构建、文件路径并发锁、乐观锁校验与冲突数据自动沙箱隔离。
build_defensive_webdav_operator(endpoint: &str, root: &str, username: &str, token: &str) -> Result<Operator, Error>
- 功能：基于 Rustls 物理构建 WebDAV 客户端。自动包裹单次 I/O 最长挂起 15 秒的 TimeoutLayer，以及在故障时以 避让因子重试最多 4 次的 RetryLayer，确保网络抖动自愈。
upload_file_with_memory_shield(op: &Operator, remote_path: &str, mut source_file: File) -> Result<(), Error>
- 功能：并发分块流式上传（8 MB 分块、4 路并发）。在堆上以 shrink_to_fit 进行强力内存收缩释放，保证超大文件传输时内存开销在常数级。
preserve_conflict_fork(op: &Operator, original_path: &str, dirty_data: &[u8]) -> Result<String, OmniCoreError>
- 功能：防覆盖沙箱。当乐观锁条件冲突触发熔断时，将本地脏数据自动输出到 .conflict.[UUID].[ext] 沙箱冲突隔离路径中。
OptimisticStorageService（并发与乐观锁存储接口）：
OptimisticStorageService::new(op: Operator) -> Self
- 功能：根据指定的存储算子构建高并发防冲突服务，内部自动初始化 PathLockManager（路径级别读写锁管理器，用 RwLock 协调写排他）。
compute_etag(&self, relative_path: &str) -> Result<EntityTag, OmniCoreError>
- 功能：获取或计算文件的唯一 ETag 指纹（未提供 ETag 时，将计算数据大小和自定义 Checksum 生成特征码）。
write_with_optimistic_lock(&self, relative_path: &str, data: Vec<u8>, expected_etag: &EntityTag) -> Result<EntityTag, OmniCoreError>
- 功能：校验磁盘/云端文件的当前 ETag 与 expected_etag 是否匹配。如果不匹配，抛出 ConditionNotMatch 乐观锁冲突错误，阻断并上报冲突；如果一致，执行排他写入，并返回新产生的 ETag。
Tauri 专属的跨端命令（可直接通过 invoke 在前端执行）：
download_remote_db(app_handle, state, remote_path)
- 功能：将远程的 SQLite 数据库备份安全地流式下载到本地 App 专属数据目录下，返回绝对路径。
upload_local_db(state, local_file_path, remote_path)
- 功能：读取本地的 SQLite 数据库文件，以常数级内存占用将其流式同步至 WebDAV/S 3 远端备份路径。
如果您需要查看这些函数的使用样例，可以前往 src-tauri/tests/fts_tests.rs 以及 src-tauri/tests/lock_conflict_tests.rs，里面有详细的集成用例演示。