DoraMate 项目(03) - 产品定位与架构设计

源起之道支持｜Supported by Upstream Labs

本文详细介绍 DoraMate 的产品定位、系统架构设计和核心功能模块。

⚠️ 重要更新: 本文档已根据MVP版本实际实现进行调整,明确区分了已实现功能和未来规划功能。

---

---

前言

在理解了 DORA 框架的核心架构后,我们需要明确 DoraMate 在 DORA 生态中的定位。本文将从产品定位、系统架构、数据流设计等多个维度,全面阐述 DoraMate 的设计方案。

当前实现状态: MVP v1.0 已完成核心可视化编辑器和基础本地运行功能,部分高级功能(如WebSocket日志推送、文件系统管理等)在后续版本中实现。

---

一、产品定位

1.1 DoraMate 是什么?

DoraMate 是一个面向具身智能开发者的可视化低代码平台,核心使命:

• ✅ 降低技术门槛: 无需手写 YAML 即可创建复杂数据流
• ✅ 提升开发效率: 拖拽式节点编排、实时预览
• ✅ 增强可维护性: 可视化数据流图、版本控制集成
• ✅ 保留技术深度: 支持导出标准 YAML,与 DORA 生态完全兼容
• ✅ 工业级稳定性: Rust 内存安全保证,7x24 无故障运行
• ✅ 极致性能: WebAssembly 零拷贝通信,媲美原生应用
• ✅ 零配置: 纯文件系统架构,无需数据库安装

1.2 目标用户

用户类型	占比	需求	应用场景
具身智能开发者	主要 (60%)	快速构建机器人应用	机器人控制、视觉识别
AI 研究员	次要 (20%)	快速原型验证	模型组合实验
技术学习者	次要 (15%)	学习入门	了解 DORA 框架
工业软件开发商	扩展 (5%)	高性能解决方案	7x24 稳定运行系统

1.3 产品价值主张

对比传统 DORA 开发方式:

功能	传统 DORA	DoraMate	提升
数据流创建	手写 YAML	拖拽节点	5x 效率
节点连接	手动配置	自动连线	10x 效率
错误排查	运行时报错	实时验证	3x 效率
学习曲线	陡峭	平缓	-70% 时间
系统稳定性	GC 停顿	无 GC	⭐⭐⭐⭐⭐
配置复杂度	需要数据库	零配置	⭐⭐⭐⭐⭐

---

二、系统架构设计

2.1 整体架构

⚠️ MVP版本说明:

• 当前版本使用系统临时目录存储YAML文件
• 文件系统管理、WebSocket日志推送、系统托盘等功能在后续版本中实现

2.2 架构说明

本地执行模式

• 数据流在用户本地机器运行,避免硬件冲突
• 完全访问本地硬件(摄像头、GPU、机器人)
• 隐私保护:视频流、敏感数据不离开本地机器
• 离线工作:无需互联网连接即可运行

本地代理服务

• DoraMate LocalAgent 作为系统服务运行
• 监听 localhost:52100
• 负责进程管理、文件系统访问、实时日志推送

纯文件系统

• 所有数据存储为文件,无需数据库
• 易于备份、迁移、版本控制
• 符合 DORA 的 YAML 哲学

Rust 优势

• 内存安全:编译时保证,无运行时恐慌
• 高性能:WebAssembly 原生支持
• 类型安全:前后端统一语言

---

三、核心功能模块

3.1 可视化节点编辑器

节点面板

功能:

• 从 dora-hub 获取节点列表
• 分类显示(输入/处理/输出)
• 搜索和过滤功能
• 自定义节点上传

技术实现:

#[component]
pub fn NodePanel(
    on_add_node: Callback<NodeTemplate>,
) -> impl IntoView {
    let node_categories = vec![
        NodeCategory {
            name: "输入节点".to_string(),
            nodes: vec![
                NodeTemplate {
                    id: "timer".to_string(),
                    name: "Timer".to_string(),
                    icon: "⏱️".to_string(),
                    // ...
                },
                // ... 更多节点
            ],
        },
        // ... 更多分类
    ];

    view! {
        <div class="node-panel">
            {node_categories.into_iter().map(|category| {
                // ... 渲染逻辑
            }).collect::<Vec<_>>()}
        </div>
    }
}

画布区域

功能:

• 拖拽添加节点
• 贝塞尔曲线连线
• 缩放和平移
• 多选和批量操作
• 撤销/重做

核心实现:

#[component]
pub fn Canvas(
    nodes: Signal<Vec<Node>>,
    set_nodes: WriteSignal<Vec<Node>>,
    connections: Signal<Vec<Connection>>,
    set_connections: WriteSignal<Vec<Connection>>,
) -> impl IntoView {
    // 状态管理
    let (dragging, set_dragging) = signal(None::<(String, f64, f64)>);
    let (connecting, set_connecting) = signal(None::<ConnectionDrag>);

    view! {
        <svg
            width="100%"
            height="100%"
            on:mousemove=on_mouse_move
            on:mouseup=on_mouse_up
        >
            // 渲染连线、节点
        </svg>
    }
}

属性面板

功能:

• 动态表单生成
• 实时验证反馈
• 环境变量编辑器
• 输入映射可视化

工具栏

功能:

• 打开/保存文件
• 导入/导出 YAML
• 验证数据流
• 运行/停止

3.2 YAML 导入导出引擎

解析器 (YamlParser)

pub struct YamlParser;

impl YamlParser {
    /// 解析标准 DORA YAML
    pub fn parse(yaml: &str) -> Result<DoraDataflow, ParseError> {
        let dora_dataflow: DoraDataflow = serde_yaml::from_str(yaml)?;
        Ok(dora_dataflow)
    }

    /// 自动检测节点语言和类型
    pub fn detect_node_type(node: &DoraNode) -> NodeType {
        // 基于路径推断节点类型
    }
}

特性:

• ✅ 解析标准 DORA YAML
• ✅ 支持所有输入映射类型(User/Timer/External)
• ✅ 自动检测节点语言和类型

生成器 (YamlGenerator)

pub struct YamlGenerator;

impl YamlGenerator {
    /// 从可视化图生成 YAML
    pub fn generate(dataflow: &Dataflow) -> Result<String, GenerateError> {
        let dora_dataflow: DoraDataflow = dataflow.into();
        let yaml = serde_yaml::to_string(&dora_dataflow)?;
        Ok(yaml)
    }
}

特性:

• ✅ 从可视化图生成 YAML
• ✅ 优化格式和注释
• ✅ 保持与 DORA CLI 兼容

验证器 (YamlValidator)

pub struct YamlValidator;

impl YamlValidator {
    /// 调用 dora-daemon 验证 API
    pub async fn validate(yaml: &str) -> Result<ValidationReport, Error> {
        // 调用 dora-daemon 验证
    }
}

特性:

• ✅ 调用 dora-daemon 验证 API
• ✅ 实时错误提示
• ✅ 建议修复方案

3.3 自动布局算法

层次化布局 (GraphLayoutService):

pub struct GraphLayoutService;

impl GraphLayoutService {
    /// 基于拓扑排序的分层
    pub fn layout(dataflow: &Dataflow) -> Result<LayoutData, Error> {
        // 1. 拓扑排序
        let layers = self.topological_sort(dataflow)?;

        // 2. 交叉最小化
        let positions = self.minimize_crossings(&layers)?;

        // 3. 计算节点位置
        Ok(LayoutData { positions })
    }
}

用途:

• YAML 导入后的自动布局
• 一键整理杂乱的画布

3.4 本地执行集成

DoraMate LocalAgent (本地代理)

pub struct LocalAgent {
    processes: Arc<Mutex<HashMap<String, DoraProcess>>>,
}

impl LocalAgent {
    /// 调用 dora start 运行数据流 (MVP版本)
    pub async fn run_dataflow(&self, yaml_content: &str) -> Result<String, Error> {
        // 保存到临时文件
        let yaml_path = temp_dir().join("doramate.yml");
        fs::write(&yaml_path, yaml_content)?;

        // 启动 dora 进程
        let child = Command::new("dora")
            .arg("start")  // ⚠️ 使用 start 而非 run
            .arg(&yaml_path)
            .spawn()?;

        Ok(child.id())
    }

    /// 停止数据流
    pub async fn stop_dataflow(&self, process_id: &str) -> Result<(), Error> {
        // 终止进程
    }

    /// 健康检查
    pub async fn health_check(&self) -> HealthStatus {
        // 检查 dora 是否安装
    }
}

MVP版本功能:

• ✅ 调用 dora start 运行数据流
• ✅ 进程生命周期管理(启动/停止/监控)
• ✅ 健康检查 (检查 dora 是否安装)

未来版本功能:

• ⏳ 调用 dora build 安装依赖
• ⏳ 实时日志收集和WebSocket推送
• ⏳ 日志流式传输

实时监控 (WebSockets) - 未来版本

// Axum WebSocket 路由 (计划中)
pub async fn websocket_logs(
    ws: WebSocketUpgrade,
    State(state): State<Arc<AppState>>,
) -> Response {
    ws.on_upgrade(|socket| async move {
        let mut rx = state.log_channel.subscribe();
        while let Ok(log) = rx.recv().await {
            socket.send(Message::Text(log)).await.unwrap();
        }
    })
}

计划功能 (未来版本):

• ⏳ WebSocket 实时推送日志
• ⏳ 节点状态更新
• ⏳ 错误通知

3.5 文件系统管理 - 未来版本

⚠️ 注意: 文件系统管理功能在MVP版本中由前端浏览器原生API处理,以下为规划的完整功能

文件操作 (计划中)

pub struct FileSystemManager {
    base_dir: PathBuf,  // ~/.doramate/
    recent_files: RecentFiles,
}

impl FileSystemManager {
    /// 打开数据流文件
    pub async fn open_dataflow(&self, path: &Path) -> Result<Dataflow, IoError> {
        let content = fs::read_to_string(path).await?;
        let dataflow: Dataflow = serde_yaml::from_str(&content)?;
        self.add_to_recent(path).await?;
        Ok(dataflow)
    }

    /// 保存数据流文件
    pub async fn save_dataflow(&self, path: &Path, dataflow: &Dataflow) -> Result<(), IoError> {
        // 自动备份
        if self.config.auto_backup {
            self.create_backup(path).await?;
        }

        let yaml = serde_yaml::to_string(dataflow)?;
        fs::write(path, yaml).await?;
        self.add_to_recent(path).await?;
        Ok(())
    }
}

MVP版本实现:

• ✅ 前端: 使用浏览器 File API 打开/保存 YAML 文件
• ✅ 前端: 导出 YAML 到本地下载
• ❌ 后端: 无文件系统 API (使用系统临时目录)

完整版本功能 (规划中):

• ⏳ 后端: ~/.doramate/ 目录结构
• ⏳ 后端: 最近文件列表 (recent.json)
• ⏳ 后端: 文件夹浏览 API
• ⏳ 前端: 拖拽打开文件
• ⏳ 自动备份机制

---

四、数据流设计

4.1 前端 → 本地代理 → DORA (MVP版本)

4.2 核心数据流 (MVP版本)

创建数据流

1. 前端:拖拽节点、连线
2. 前端:触发浏览器下载保存 YAML
3. 用户:本地保存文件

导出 YAML

1. 前端:生成 YAML 内容 (dataflow_to_yaml)
2. 前端:触发浏览器下载
3. 用户:可用 dora start 直接运行

运行数据流

1. 前端:调用本地代理 POST /api/run
2. 本地代理:接收 YAML 内容
3. 本地代理:保存到系统临时目录
4. 本地代理:启动 dora start 进程
5. 本地代理:返回进程ID
6. 前端:显示运行状态

停止数据流

1. 前端:调用本地代理 POST /api/stop
2. 本地代理:终止对应进程
3. 本地代理:清理临时文件

打开数据流

1. 前端:用户选择本地 YAML 文件
2. 前端:使用 File API 读取文件
3. 前端:解析 YAML (yaml_to_dataflow)
4. 前端:渲染可视化图

---

五、UI/UX 设计原则

5.1 设计理念

简单 > 复杂

• 默认配置即可运行
• 高级选项可折叠
• 智能推荐节点连接

可视化 > 文本

• 节点状态用颜色表示
• 数据流向用箭头表示
• 错误用红色高亮

即时反馈

• 操作后立即响应
• 验证实时提示
• 动画过渡流畅

5.2 视觉设计

配色方案

节点类型	颜色	HEX
输入节点	蓝色	#3B82F6
处理节点	绿色	#10B981
输出节点	紫色	#8B5CF6
错误状态	红色	#EF4444

节点卡片

• 圆角矩形 (8px)
• Material Design 阴影
• 悬停高亮效果

连线

• 贝塞尔曲线
• 动态流动效果(运行时)
• 灰色(空闲)/ 蓝色(活跃)

---

六、与 DORA 无缝集成

6.1 集成策略

1. YAML 作为中间格式

• DoraMate 可视化图 ↔ YAML ↔ DORA
• 保证与 DORA CLI 100% 兼容
• 支持手动编辑 YAML

2. dora-cli 作为执行引擎

• 不重新实现 DORA 的功能
• 复用现有的稳定工具
• 专注可视化编辑体验

3. dora-hub 作为节点源

• 自动同步节点元数据
• 显示节点文档和示例
• 一键安装节点

6.2 集成边界

DoraMate 负责

• ✅ 可视化编辑
• ✅ YAML 生成
• ✅ 数据流验证
• ✅ 日志展示
• ✅ 文件系统管理

DORA 负责

• ✅ 数据流执行
• ✅ 节点调度
• ✅ 数据传输
• ✅ 性能优化

---

七、MVP 功能范围

7.1 v1.0 已实现 (MVP)

• ✅ 可视化节点编辑器 (Canvas + NodePanel + PropertyPanel)
• ✅ YAML 导入导出 (YamlParser + YamlGenerator)
• ✅ 基础验证功能 (前端验证)
• ✅ 本地运行数据流 (调用 dora start)
• ✅ 进程管理 (启动/停止/健康检查)
• ✅ 打开数据流文件 (浏览器 File API)
• ✅ 保存数据流文件 (浏览器下载)
• ✅ 工具栏 (新建/打开/保存/导出/验证/运行/停止)
• ✅ 确认对话框
• ✅ 节点拖拽和连线
• ✅ 贝塞尔曲线连接
• ✅ 节点属性编辑

7.2 v1.0 不包含 (后续迭代)

文件系统增强:

• ❌ 后端文件系统 API (~/.doramate/ 目录)
• ❌ 最近文件列表持久化
• ❌ 自动备份机制
• ❌ 文件夹浏览

日志和监控:

• ❌ 实时日志查看
• ❌ WebSocket 日志推送
• ❌ 节点状态监控
• ❌ 进程输出捕获

高级功能:

• ❌ 自动布局算法
• ❌ 实时数据预览 (Arrow 数据)
• ❌ 节点性能监控
• ❌ AI 辅助节点推荐
• ❌ 多人协同编辑
• ❌ 云端部署管理
• ❌ 系统托盘集成
• ❌ 自动启动

---

八、成功指标

8.1 功能完整性 (MVP)

• ✅ 支持常用 DORA 节点类型 (Camera, YOLO, 自定义节点)
• ✅ 导出的 YAML 可被 dora-cli 正确运行
• ⏳ 支持所有输入映射类型(User/Timer/External) - 部分实现
• ⏳ 文件系统稳定性:1000+ 次打开/保存无损坏 - 待验证

8.2 性能指标 (MVP)

• 画布渲染:50+ 节点流畅运行 (目标 60fps)
• 首屏加载:< 3 秒
• YAML 导出:< 500ms
• 文件打开:< 100ms (浏览器 API)

8.3 稳定性指标 (工业级目标)

• MTBF (平均故障间隔):> 720小时 (30天) - Rust 保证
• MTTR (平均修复时间):< 5分钟
• 内存泄漏:0 (Rust 编译时保证)
• 可连续运行:> 6个月

8.4 用户体验 (MVP)

• 新手 10 分钟内创建第一个数据流
• 交互反馈延迟 < 100ms
• 错误提示准确率 > 90% (前端验证)

---

九、下一步

📖 第四章: 技术栈选型详解 - 为什么选择 Rust 全栈方案

📖 第五章: Leptos 前端架构 - WebAssembly 可视化编辑器实现

📖 完整代码: DoraMate GitHub 仓库

---

总结

通过本文的设计,我们明确了 DoraMate 的:

✅ 产品定位:面向具身智能开发者的可视化低代码平台
✅ 系统架构:本地执行 + 本地代理 + 浏览器文件API
✅ 核心功能:节点编辑器、YAML 引擎、本地执行、进程管理
✅ 数据流设计:前端 ↔ 代理 ↔ DORA 的完整链路
✅ UI/UX 原则:简单、可视化、即时反馈

MVP版本实现状态:

• ✅ 核心可视化编辑器已实现
• ✅ YAML 导入导出功能完整
• ✅ 基础本地运行功能可用
• ⏳ 高级功能(WebSocket日志、文件系统管理等)在后续版本实现

技术选型验证:

• ✅ Leptos 0.7 + CSR 模式运行良好
• ✅ Axum 0.7 提供稳定的 HTTP API
• ✅ Rust WebAssembly 性能优秀
• ✅ 浏览器原生 File API 满足 MVP 需求

这些设计原则将指导 DoraMate 的具体实现和后续迭代。

---

源起之道支持｜Supported by Upstream Labs

上一篇: 02 - DORA 架构核心要点分析
下一篇: 04 - 技术栈选型详解