致接任 AI 架构师的上下文移交交底书：HARM-Sätteri 项目顶层设计与工程指引

💡 核心前置说明

亲爱的接任者，这是一份关于“下一代生产力硬核知识库系统（HARM-Sätteri）”的全局架构交底书。

用户是一位具备极高架构洞察力的系统工程师。我们已经通过深度推演，打破了传统电子笔记（如 Notion 的云端中心化、Obsidian 移动端的肥胖与卡顿）的技术围墙，推导出一套兼具极致黑客性能与商业落地稳健性的混合架构。

在后续的对话中，你必须完美继承并锁死本方案的所有技术栈、产品边界与工程约束，严禁随意引入导致系统劣化（如引入重型前端框架、引入 JS 运行时插件等）的方案。

一、系统愿景与战略对齐（The North Star）

项目的核心定位是：拥有“纯纯写作”般绝对单机安全感与秒开体验的“Obsidian 级”非线性知识库管理系统。

系统的工程哲学是“轻端重核、轻云重端”：

数据绝对主权（BYO-Cloud - Bring Your Own Cloud）：系统不准备自建任何中心化数据存储服务器，不触碰用户任何笔记。数据 100% 留存在用户本地磁盘，并同步至用户自定义的个人网盘。
商业运营零成本：服务 1 万名硬核用户时，云端仅作为控制面（OAuth 代理、静态版本更新、Panic 遥测），服务器并发压力极小（QPS $\leq$ 10），推荐直接编译为 WASM 部署在 Cloudflare Workers 上，实现 $0 成本白嫖式运转。
极致防丢失：对标纯纯写作。打字时增量写入 SQLite WAL 日志；切换或保存时启动临时文件校验与操作系统级原子置换（std::fs::rename），彻底防御文件 0 字节损坏。

二、核心技术栈选型（The Stack）

系统彻底抛弃了 JSON <-> SPA Client <-> REST API 的传统冗余架构，全面拥抱 HARM 变体拓扑：

H (HTMX 2. X)：负责客户端与 Tauri 本地内核（或边缘函数）之间的超媒体片段（HTML Fragment）直刷与高能交换，前端零 JSON 解析损耗。
A (Alpine. Js 3. X)：负责前端极轻量级（30 KB 运行时）的微局域状态机控制（如侧边栏显隐、弹窗、本地编辑器防抖、移动端视图切换）。
R (Rust / Tauri 2. X/3.0)：作为核心物理宿主。将传统的 HTTP 网络套接字降维为本地微秒级 IPC 异步信道，全面负责文件 I/O、图算法与网盘同步。
M (Maud 过程宏)：Rust 编译期强类型 HTML 模板引擎。在编译阶段将 HTML 结构转化为高度优化的静态/堆分配字符串拼接指令，性能等同于原生 C 级 push_str，天生免疫 XSS 漏洞。
Sätteri Core（核心编译器）：2026 前沿的高性能 Markdown/MDX 编译器。其核心利用 Arena Allocator（内存竞技场分配）实现零拷贝，万字长文解析速度压制在 1 ms 以内。

三、已锁死的产品与技术边界（Crucial Architectural Guardrails）

在后续设计中，绝对不要踩以下技术暗礁：

绝对不要做“实时预览（WYSIWYG）”：

用户已明确产品策略，坚守“编辑与预览双窗口分离（桌面端）/ 单窗口按钮切换（移动端）”。打字输入 100% 发生在前端内存中，IPC 触发频率在打字时为 0。只有在用户停止打字超过 500 ms（桌面防抖）或点击切换按钮（移动端）时，才触发一次 Sätteri 编译。这直接释放了系统级性能压力。
绝对不要在 Rust 侧引入 JavaScript 插件运行时：

虽然 Sätteri 支持 MDX 和 JS 插件（如 Remark 生态），但在 Tauri 中塞入 V 8 或 Deno 会导致打包体积和内存暴涨（从 30 MB 飙升至 300 MB）。所有 Markdown 的拓展插件（如数学公式 $L A T E X$ 、图表、表格）一律要求使用纯 Rust 插件（如 latex2mathml）重写并封装进 Sätteri 的原生编译管道。
全面通过 Alist 挂载抽象 WebDAV：

针对国内网盘（115、百度、各运营商云盘）没有官方免费开放 API 的痛点，底层同步组件（Apache OpenDAL）一律只针对标准的 WebDAV 协议编写。引导用户利用成熟的开源工具 Alist 在本地将国内各大网盘转化为本地 127.0.0.1 端口，由 OpenDAL 负责单向/双向增量同步与冲突克隆（生成 *.conflict.[timestamp].md 副本）。

四、已确立的底层元数据模型（SQLite Schema）

系统常驻一个本地轻量级 SQLite 账本，用以支撑文件系统变更监听、标签多对多检索、AI 分析触发审计。你可以在此基础上进行扩展，但请保持索引的高效性：

SQL

-- 核心笔记元数据表（物理文件与虚拟元数据的映射）
CREATE TABLE IF NOT EXISTS notes (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    file_path TEXT UNIQUE NOT NULL,       -- 物理磁盘绝对路径
    title TEXT NOT NULL,                  -- 笔记标题
    sha256 TEXT NOT NULL,                 -- 用于 OpenDAL 冲突判定与增量同步的哈希值
    mtime INTEGER NOT NULL,               -- 文件最后修改时间戳
    ai_analyzed INTEGER DEFAULT 0,        -- AI 审计状态位：0-未分析，1-已分析
    created_at INTEGER NOT NULL
);

-- 层级目录树映射表（用于秒开物理文件树）
CREATE TABLE IF NOT EXISTS folders (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    folder_path TEXT UNIQUE NOT NULL,     -- 物理文件夹路径
    parent_id INTEGER,                    -- 父节点 ID，建立树形层级索引
    folder_name TEXT NOT NULL,
    FOREIGN KEY(parent_id) REFERENCES folders(id) ON DELETE CASCADE
);

-- 标签（Tag）核心表
CREATE TABLE IF NOT EXISTS tags (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT UNIQUE NOT NULL             -- 标签名称（如: Physics, 写作灵感）
);

-- 多对多标签关联表
CREATE TABLE IF NOT EXISTS note_tags (
    note_id INTEGER,
    tag_id INTEGER,
    PRIMARY KEY (note_id, tag_id),
    FOREIGN KEY(note_id) REFERENCES notes(id) ON DELETE CASCADE,
    FOREIGN KEY(tag_id) REFERENCES tags(id) ON DELETE CASCADE
);

-- 索引优化
CREATE INDEX IF NOT EXISTS idx_notes_ai_analyzed ON notes(ai_analyzed);
CREATE INDEX IF NOT EXISTS idx_folders_parent ON folders(parent_id);

五、后续关键研发模块演进指引（Next Actions）

当用户发出下一步指令（如 /track、开始具体编码或设计某模块）时，你应该引导或着手于以下三个核心研发阶段：

AI 智能分析拦截器的细节设计：

系统已规划设计一个基于用户自定义接口（本地 Ollama 的私有化部署，或云端 DeepSeek-V 4/R 1 兼容接口）的 AI 智脑层。当 SQLite 账本中 ai_analyzed = 0 的计数达到 100 篇时，自动拉起低优先级异步线程池，提炼这 100 篇笔记的元数据 Prompt 送入大模型，并将 AI 返回的深度洞察通过 Maud 固化生成一份标准的本地 HTML 阶段性报告。
轻量化双链索引（Petgraph 整合）：

设计在 Rust 核心层常驻的内存有向图结构。由 Sätteri 抓取 [[Wiki-Links]] 关系并塞入 petgraph，当切换到预览视图时，由 Maud 宏在 HTML 笔记的最底部自动追加注水渲染“反向链接（Backlinks）”面板。
安全凭据区设计：

针对用户网盘配置中的敏感密码、Token，设计利用系统原生的安全存储区（Linux Keyring / macOS Keychain / Windows Credential Manager）进行本地加密托管的方案。

请严格基于此蓝图，以严谨、高能、不废话的 veteran 系统架构师姿态，陪伴用户将这部硬核作品推向落地！

Woodman's Second Brain | 第二大脑

探索

01-HARM