Rust 引擎

Rust 引擎 是一款可选的高性能执行引擎。它通过 N-API 调用原生二进制，绕过标准的事件循环限制，从而在巨型文档项目中显著加速 I/O 密集型负载，并提供多线程文件读取与子进程编排能力。

Rust 引擎目前以 实验性预览 的形式发布，面向企业级规模而生。当文档中包含成千上万的 Markdown 文件与冗长的 Git 日志，并因此带来编译瓶颈时，它能大显身手。

配置

要启用原生 Rust 加速，只需在 docmd.config.json 中将 engine 指令设置为 "rust"。

{
  "title": "全局 API 注册中心",
  "engine": "rust",
  "src": "docs",
  "out": "site"
}

适用场景与闪光点

Rust 引擎针对特定的编译瓶颈而生。在以下场景中能带来显著的效率提升：

• 巨型仓库（1000+ 文件）：通过 Tokio 编排的异步并行文件系统访问，让单体项目受益巨大。
• 密集的 Git 元数据采集：在数百个页面上提取深层 commit log 需要大量子进程派生；Rust 引擎处理 git:log 任务比 JavaScript 快达 1.24×。
• CI/CD 中的冷启动加速：在没有热缓存的环境下，原始文件读取吞吐能直接缩短总处理时间。真实基准显示 冷构建提速约 25%，热构建提速约 17%。

支持的设备与平台包

该引擎执行的是预编译的机器码，因此需要为宿主机架构准备专门的原生二进制。基础包 @docmd/engine-rust 会在启动时惰性加载匹配当前平台的二进制。

目前发布的平台包如下：

能力与战略性限制

要物尽其用，需要先理解它的架构权衡。引擎在 I/O 密集型操作上极强，但在跨边界序列化时会产生开销。

双重序列化代价详解

docmd 核心调度器与原生 Rust 引擎之间的通信，依赖字符串化的 JSON 跨越 N-API 运行时边界：

JS Worker -> JSON.stringify() -> NAPI 边界 -> Serde 反序列化 -> [Rust 任务] -> Serde 序列化 -> NAPI 边界 -> JSON.parse()

对 I/O 密集型操作（如查询 Git 历史、读取磁盘缓冲）来说，处理时间节省的部分远超字符串转换的代价。

但对高度迭代、CPU 密集型的任务（如 search:index 这种全文搜索索引）来说，序列化往返所消耗的 CPU 比任务本身还要多。一来一回序列化大数组内容会让 Rust 实现比 Node 原生 JIT 的字符串处理更慢。

因此，对于语义搜索流水线，JavaScript 引擎仍然是推荐的运行时。请在大型 Git 与文件管理负载上有选择地启用 Rust 引擎。

插件与 API 集成

插件与构建生命周期钩子可以通过 @docmd/api 直接与 Rust 引擎交互。API 层充当安全边界，在强制执行严格任务白名单的同时编排高吞吐的原生 I/O：

import { resolveEngine, discoverFiles, readFilesBatch, getGitLog } from '@docmd/api';

// 解析已配置引擎或最佳可用引擎（优先尝试 Rust，回退到 JS）
const engine = await resolveEngine(['rust', 'js']);

// 在庞大的目录树中批量发现文件
const files = await discoverFiles(engine, './docs', ['.md', '.mdx']);

// 绕过 Node 事件循环的高性能并行多线程批量读取
const fileContents = await readFilesBatch(engine, files.map(f => f.path));

// 快速多线程提取 Git 提交日志历史
const gitLogs = await getGitLog(engine, files.map(f => f.path), 10);