架构设计
了解 DocsJS 核心架构和设计决策。
三层架构
DocsJS 采用 PicGo 风格的三层架构：
┌─────────────────────────────────────────────────────────────────────┐
│ 平台层 │
│ CLI + API + GUI + 配置管理 + 插件注册 │
├─────────────────────────────────────────────────────────────────────┤
│ 适配器层 │
│ DOCX 解析器 ←→ DocumentAST ←→ HTML/MD/JSON 渲染器 │
├─────────────────────────────────────────────────────────────────────┤
│ 核心引擎 │
│ AST v2 + 管道 + 插件编排器 + 安全 │
└─────────────────────────────────────────────────────────────────────┘平台层
顶层提供用户界面：
- CLI - 批处理命令行工具
- API - REST 和编程接口
- GUI - 可视化编辑器和管理界面
- 配置管理 - 配置处理行为
- 插件注册 - 发现和管理插件
适配器层
中间层处理格式转换：
DOCX 解析器
将 .docx 文件解析为内部 AST：
- 提取文档结构
- 解析样式和格式
- 处理嵌入资源（图片、图表）
- 保留语义元素
DocumentAST
核心抽象语法树：
- 框架无关的表示
- 保留所有文档语义
- 支持增量更新
- 支持高效转换
渲染器
将 AST 转换为输出格式：
- HTML 渲染器 - Web 就绪输出
- Markdown 渲染器 - 文档友好格式
- JSON 渲染器 - 编程访问
核心引擎
基础层驱动所有功能：
AST v2
增强的抽象语法树：
ts
interface DocumentNode {
type: string;
children?: DocumentNode[];
attributes?: Record<string, unknown>;
content?: string;
}管道
处理管道编排转换：
- 解析 - 将输入转换为 AST
- 转换 - 应用修改
- 渲染 - 生成输出
- 导出 - 准备最终结果
插件编排器
管理插件生命周期：
- 注册和验证
- 钩子执行
- 权限强制
- 错误处理
安全
内置安全措施：
- 插件沙箱
- 权限系统
- 内容净化
- 资源限制
数据流
输入 (DOCX/HTML/剪贴板)
↓
┌─────────────────┐
│ 解析器 │ → beforeParse/afterParse 钩子
└─────────────────┘
↓
┌─────────────────┐
│ AST │ → beforeTransform/afterTransform 钩子
└─────────────────┘
↓
┌─────────────────┐
│ 渲染器 │ → beforeRender/afterRender 钩子
└─────────────────┘
↓
┌─────────────────┐
│ 导出器 │ → beforeExport/afterExport 钩子
└─────────────────┘
↓
输出 (HTML/MD/JSON)关键设计决策
1. AST 中心
所有操作通过 AST 进行：
- 单一数据源
- 支持强大的转换
- 便于调试
- 支持增量更新
2. 插件优先
可扩展性是核心设计：
- 8 个生命周期钩子
- 细粒度权限
- 沙箱执行
- 丰富的上下文 API
3. 配置驱动
通过配置文件控制行为：
- 预构建常见用例
- 可定制特定需求
- 运行时可切换
- 可组合设置
4. 安全意识
安全不是事后考虑：
- 最小权限原则
- 沙箱插件执行
- 内容净化
- 审计能力
性能考虑
- 流式处理 - 高效处理大文档
- 缓存 - 缓存解析结果
- 懒加载 - 按需加载插件
- Tree Shaking - 只包含需要的代码