RESEARCH_OMNI

【核心机制拆解】

omni_core 作为“五体一端 (Omni-Stack)”的核心引擎，本质上是一个基于 Rust 运行时的高性能本地数据调度与状态中枢。其底层流转逻辑严格遵循 Local-First 与 BYOS 原则，核心功能与实现架构分为以下三个核心维度：

统一存储抽象层 (BYOS / OpenDAL 驱动)

实现方式：底座封装 Apache OpenDAL，将本地物理路径、用户自建 WebDAV、或私有云存储统一抽象为 Operator。
当前功能：屏蔽物理介质差异，提供块级/流式无缝读写，实现真正的数据所有权本地化。

跨语言零拷贝通信桥 (Tauri ⇄ Robyn ⇄ HTMX)

实现方式：抛弃重型 JSON 序列化，底层在 Rust 侧采用 Bincode 压缩或通过裸指针共享内存（Unix Domain Socket）。
当前功能：将 Rust 捕获的本地数据高速喂给 Python (Robyn) 后端，或直接作为 Tauri IPC 的 Payload。配合前端 HTMX 直接消费纯 HTML 片段，完全绕过 React/Vue 复杂的客户端状态机。

极简动态模板与色彩管道 (Minijinja 胶水层)

实现方式：内嵌 Rust 编写的 Minijinja 动态解析器，深度融合类似 NvChad 的 HSL/Hex 色彩映射逻辑。
当前功能：实现微秒级的本地 HTML 模板渲染与主题热重载，将样式与数据在服务端/本地端一次性绑定。

【极简代码骨架】

以下为 omni_core 剔除业务逻辑后的纯净底座接口：

// omni_core/src/storage.rs
use opendal::{Operator, services::Fs};
use std::sync::Arc;
use std::path::Path;
 
pub struct OmniStorage {
    operator: Arc<Operator>,
}
 
impl OmniStorage {
    // 初始化本地优先存储底座 (BYOS)
    pub fn new<P: AsRef<Path>>(root_path: P) -> Result<Self, opendal::Error> {
        let mut builder = Fs::default();
        builder.root(&root_path.as_ref().to_string_lossy());
        
        let operator = Operator::new(builder)?.finish();
        Ok(Self { operator: Arc::new(operator) })
    }
 
    // 零拷贝流式读取，直接向 Robyn/HTMX 传输
    pub async fn read_local_file(&self, path: &str) -> Result<Vec<u8>, opendal::Error> {
        let buffer = self.operator.read(path).await?.to_vec();
        Ok(buffer)
    }
}
 
// omni_core/src/bridge.rs
// 供 Tauri Command 或 Robyn FFI 直接调用的极简数据接口
#[cfg(feature = "tauri_bridge")]
#[tauri::command]
pub async fn fetch_core_render(payload_path: String) -> Result<String, String> {
    // 模拟 Minijinja 与 OpenDAL 融合后产出的动态片段
    // 返回带有 HTMX 属性的纯 HTML 字符串
    let dynamic_html = format!(
        r#"<div id="omni-node" hx-swap="outerHTML" class="theme-accent">Local Data Block: {}</div>"#, 
        payload_path
    );
    Ok(dynamic_html)
}

【物理踩坑记录与优化方向】

1. 跨语言边界内存泄漏 (Rust FFI -> Python Robyn)

灾难表现：当 Robyn 高频调用 omni_core 的 C-FFI 接口读取大文件时，Rust 侧通过 Box::into_raw 传递的裸指针在 Python 虚拟机中由于 GC 无法追踪，导致 RSS 内存持续飙升，触发系统 OOM 强杀。

防御代码：必须建立显式的内存归还守护机制。

#[no_mangle]
pub unsafe extern "C" fn free_omni_buffer(ptr: *mut u8, len: usize, cap: usize) {
    if !ptr.is_null() {
        // 重新夺回所有权，依靠 Rust 作用域结束自动 Drop 释放内存
        let _ = Vec::from_raw_parts(ptr, len, cap); 
    }
}

优化方向：后续全面转向 PyO3 的 PyBytes 零拷贝视图，将内存生命周期与 Python 运行时上下文强绑定。

2. 多进程并发文件锁死 (BYOS 冲突)

灾难表现：当前端 Tauri 主进程与后台 Robyn 异步拉取任务同时通过 OpenDAL 修改同一个本地配置文件时，由于缺乏进程间锁，极易引发 PermissionDenied 崩溃或导致文件损坏（全零写）。

防御方案：引入 fs2 库实现 advisory file lock（建议性文件锁）。

use fs2::FileExt;
use std::fs::File;
 
pub fn lock_local_config(file: &File) -> std::io::Result<()> {
    file.lock_exclusive() // 阻塞直到获取排他锁
}

优化方向：下阶段在 omni_core 中加入极简的 WAL（预写日志）机制，确保 BYOS 架构在遭遇突发断电或强杀进程时的事务原子性。

3. 包体积与编译时间膨胀

灾难表现：由于 opendal 默认启用了过多的云端后端（如 AWS S3、Azure Blob 等），导致编译出的本地二进制单体体积突破 90MB，严重违背极简架构初衷。

优化方向：必须在 Cargo.toml 中显式剔除默认特性，实施外科手术式精准裁剪。

[dependencies]
# 严禁直接使用 opendal = "x"
opendal = { version = "0.45", default-features = false, features = ["services-fs", "services-webdav"] }

Woodman's Second Brain | 第二大脑

探索

RESEARCH_OMNI_CORE.md