SDK 架构总览

本文档从全局视角呈现 sdk/ 作为私有混合核心的完整架构，整合 Logger、MDX-Compiler、Script-Runtime 三个基础库的职责边界与协作关系。

SDK 整体定位

sdk/ 是整个 memory-sync monorepo 的 私有混合核心（Private Mixed Core），也是共享内部能力的唯一事实来源。它不是一个供外部直接安装的独立 npm 包——它的存在是为了将 memory-sync 工具链的核心逻辑从 cli/ 命令入口层中抽离出来，形成清晰的分层架构。

在当前仓库结构中，sdk/ 承担以下核心职责：

• 拥有 Rust crate tnmsd 的实际 workspace 路径和 facade 定义
• 提供 npm 包 @truenine/memory-sync-sdk 作为内部消费者（cli/、mcp/、gui/）的统一依赖入口
• 负责 Prompt Service 的实现（基于 MDX-Compiler）、Schema 生成以及最小化的 TypeScript loader 入口
• 编排 Logger、MDX-Compiler、Script-Runtime 三类基础能力；其中 Logger / Script-Runtime 的 TypeScript facade 已内联到 sdk/src/libraries/*，sdk/* 保留 Rust crate 与发布壳层

消费者依赖方向是单向的：cli/、mcp/、gui/ 都依赖 sdk/。在 sdk/ 下游，MDX-Compiler 仍完整保留在 sdk/，而 Logger / Script-Runtime 已形成”sdk/src/libraries/* 作为 TypeScript 事实来源 + sdk/* 作为 Rust crate / wrapper 发布层”的分层。这种边界确保了核心逻辑不会散落在多个入口中，也避免了 cli/ 再次成为隐式的事实来源。

为什么还保留 Libraries 层

sdk/ 仍然有存在价值，但它现在主要承载 Rust-first 的 crate、本地 NAPI 制品和对外发布 wrapper，而不再默认承担全部 TypeScript 事实来源。它们覆盖了 memory-sync 工具链中性能最关键的路径：

将这些能力下沉到独立的 Rust crate 中，使得 gui/（Tauri 应用）可以直接调用 crate 而无需 NAPI 开销，同时也让每个库可以独立演进和测试。当前只有 Logger / Script-Runtime 的 TypeScript facade 回收到了 sdk/src/libraries/*；md-compiler 仍完整保留在 sdk/。

三库角色定位

依赖关系详解

Logger — 基础设施层

Logger 是整个依赖树的 叶子节点之一（另一个是 Script-Runtime），不依赖任何其他 workspace library。当前 sdk/src/native_logger.rs 是 Rust 事实来源，而 sdk/src/libraries/logger.ts 保留对外发布的 TypeScript facade。

提供的能力：

被谁依赖：SDK 本身（ConfigLoader、RuntimeEnvironment 使用 logger 输出配置和运行时信息）、MDX-Compiler（编译过程中的日志记录）。

详细 API 参考 → Logger 日志库

MDX-Compiler — 编译层

MDX-Compiler 位于依赖树的中层，仅依赖 Logger，被 SDK 的 Prompt Service 直接使用。

提供的能力：

为什么依赖 Logger：编译过程的各个阶段（Parser、Expression Eval、Component Process 等）需要结构化日志来输出编译进度、警告和诊断错误。这些日志通过 Logger 的 Markdown 格式输出，确保终端可读且 AI 可解析。

运行时结构：公开包入口默认使用 Native Binding（Rust/NAPI）；src/compiler/ 保留 TypeScript 参考流水线，用于源级测试、调试和实现对照。

详细 API 参考 → MDX-Compiler 编译器

Script-Runtime — 运行时层

Script-Runtime 是依赖树中的 另一个叶子节点，与其他两个 library 无依赖关系。

提供的能力：

为什么独立于其他库：Script-Runtime 的职责域是 运行时模块加载和路径安全，这与 MDX-Compiler 的 编译期转换 属于完全不同的阶段。此外，路径验证涉及安全敏感操作（防路径遍历），将其作为独立 crate 可以接受更严格的审计和测试覆盖。Logger 的日志能力对 Script-Runtime 来说不是必需的——它通过 stderr 直接传递错误信息给调用方。

详细 API 参考 → Script-Runtime

数据流说明

场景 1：CLI 执行命令的完整流程

当用户通过 tnmsc CLI 执行一条命令时，数据流经所有三层 library：

场景 2：MCP Server 处理请求

MCP Server 作为轻量消费者，主要使用 SDK 的 Prompt Service 能力：

构建流程说明

SDK 的构建是一个多阶段的有序流水线，从 Rust 源码到最终的 npm 制品：

# 显式初始化本地开发环境
pnpm run bootstrap
 
# Rust workspace 构建
cargo build --workspace --exclude memory-sync-gui --release
 
# CLI schema 与 npm 包装层
pnpm -F @truenine/memory-sync-cli run build

cargo build --workspace --exclude memory-sync-gui --release

pnpm -F @truenine/memory-sync-cli run build

pnpm -C gui build
pnpm -C doc run build

代码组织结构

目录树

memory-sync/
├── sdk/                                    # 私有混合核心
│   ├── src/
│   │   ├── index.ts                       # 公共 API 入口
│   │   ├── core/
│   │   │   └── native-binding-loader.ts   # 统一绑定加载器
│   │   ├── libraries/                        # 内联 TypeScript facade
│   │   │   ├── logger.ts                     # Logger TS facade (re-export)
│   │   │   └── script-runtime/               # Script-Runtime TS facade (re-export)
│   │   ├── adaptors/                      # 输出适配器
│   │   ├── prompts.ts                     # Prompt 服务 (使用 md-compiler)
│   │   ├── ConfigLoader.ts                # 配置加载 (使用 logger)
│   │   └── runtime-environment.ts         # 运行时环境 (使用 logger)
│   ├── Cargo.toml                         # Rust crate 定义 (tnmsd)
│   └── Cargo.lock                         # Rust 依赖锁文件
│
├── sdk/src/ 内部库结构                   # Rust-first 内部库
│   ├── libraries/                            # TypeScript facade
│   │   ├── logger.ts                         # Logger TS facade (re-export)
│   │   └── script-runtime/                   # Script-Runtime TS facade (re-export)
│   │
│   ├── md-compiler/                          # 编译器
│   │   ├── compiler/                         # 编译器组件
│   │   │   ├── parser.ts                     # MDX → MDAST (unified)
│   │   │   ├── expression-eval.ts            # 表达式求值
│   │   │   ├── jsx-expression-eval.ts        # JSX 表达式求值
│   │   │   ├── component-processor.ts        # 组件处理器
│   │   │   ├── component-registry.ts         # 组件注册表
│   │   │   ├── export-parser.ts              # 导出元数据解析
│   │   │   ├── jsx-converter.ts              # JSX → Markdown
│   │   │   └── transformer.ts               # AST 转换编排
│   │   ├── components/                       # 内置组件
│   │   │   └── Md.ts                         # <Md> 条件渲染组件
│   │   ├── globals/                          # 全局作用域定义
│   │   ├── toml.ts                           # TOML 构建
│   │   └── errors/                           # 错误类型体系
│   │
│   ├── native_md_compiler/                   # Rust 编译器核心
│   │   ├── lib.rs                            # NAPI compile_mdx_to_md
│   │   ├── parser.rs                         # MDX 解析
│   │   ├── expression_eval.rs                # 表达式求值
│   │   ├── mdx_to_md.rs                      # MDX→MD 转换
│   │   ├── transformer.rs                    # AST 转换
│   │   ├── serializer.rs                     # 序列化
│   │   └── toml_artifact.rs                  # TOML 构建
│   │
│   ├── native_logger.rs                      # Logger Rust 核心
│   └── native_script_runtime.rs              # Script-Runtime Rust 核心

关键文件职责映射

设计决策与权衡

为什么选择 Rust-first？

Rust 的所有权系统和零成本抽象意味着这些热路径代码在编译后接近 C 语言性能，同时保持了内存安全保证。

为什么仍然保留 TypeScript 参考层？

以 MDX-Compiler 为例，src/compiler/ 仍然是完整的 TypeScript 参考流水线；而公开包入口是否加载 native binding，则由各 library 的入口层决定。

为什么把 NAPI Binding 加载逻辑统一到 sdk/？

这项整合已经完成。此前三个 library 各自维护平台映射、本地候选路径、CLI 包查找、缓存和错误聚合逻辑；现在这些共性逻辑统一收敛到了 sdk/src/core/native-binding-loader.ts。

各包自己的入口文件只保留“这个包独有的东西”，例如 binding validator、可选方法别名映射、Logger 适配器工厂或 Script-Runtime 的 Worker 路径逻辑。

logger/src/index.ts
md-compiler/src/native-binding.ts
script-runtime/src/index.ts

每个文件都要各自维护：
- 平台后缀映射
- 本地 .node 候选路径
- CLI 平台包探测
- 缓存与错误聚合

sdk/src/core/native-binding-loader.ts
  ├── 平台映射
  ├── 候选路径探测
  ├── CLI 平台包扫描
  └── 缓存与错误格式化

logger/src/index.ts
  └── validator + ILogger adapter

md-compiler/src/native-binding.ts
  └── env flag gate + validator

script-runtime/src/index.ts
  └── validator + optionalMethods + worker path

多包 vs 单包的权衡

当前采用 多包分离 + SDK 统一编排 的方案：

当前方案的结论：逻辑分离带来的工程收益大于多包管理的额外开销。Turbo 的增量构建和 pnpm 的 workspace 协议已经很好地缓解了多包管理的痛点。

未来演进方向

可能的进一步整合点

1. 错误体系标准化（中优先级）

   • 当前 MDX-Compiler 有完善的 CompilerDiagnosticError 体系
   • Logger 有 LoggerDiagnosticInput/Record 类型
   • 可考虑建立跨库的统一错误码命名空间（如 TNMSC_ 前缀）

2. Shared Scope Context（低优先级）

   • 当前各库各自维护 scope/context 对象
   • 可考虑一个统一的 SdkContext 类型，包含 logger instance、globalScope、path validator 等

性能优化机会

新库扩展指南

当需要在 sdk/ 下添加新的 workspace library 时，遵循以下约定：

sdk/new-lib/
├── src/
│   ├── lib.rs          # Rust 核心（如有 native 需求）
│   └── index.ts        # TypeScript 入口 / 绑定层
├── Cargo.toml          # workspace crate 定义
└── package.json        # npm 包定义（name: @truenine/<name>）

快速导航