Skip to content

设计 ​

这些页面解释 jsMind V2 为什么是现在这样、各层如何配合,不是上手手册。想查某个功能怎么用,请看指南。

相关设计文章:

  • 布局系统 — 坐标系统、盒模型、布局流程、间距规则
  • 主题系统 — 主题数据驱动、tone、覆盖链、阴影合并
  • 混合边系统 — 树用直接字段,额外关系用边

jsMind v2 分六层,自底向上:model → serialization → arranger → view → application → CLI。

1. 分层 ​

CLI         jsMind 命令入口,参数解析、退出码、无头浏览器封装
application JsMind 门面、JmMindChangeCoordinator(被动观察)、JmCommander(主动指令)
view        渲染:Shadow DOM 隔离、节点/连线/展开器、主题变量、导出图片
arranger    纯计算布局:喂入节点尺寸 → 算出坐标。零 DOM 依赖
serialization JSON/FreeMind 读写、校验器(22 个错误码)
model       JmMind / JmNode / JmEdge / JmNodeContent / style / theme 类型体系

2. 数据流 ​

Agent 路径(文件 → 命令行) ​

JSON 文件 → serialization.deserialize → JmMind
    → CLI 命令 (add-child / set-text / ...) 直接操作 JmMind API
    → serialization.serialize → JSON 文件
    → validate → 校验失败则回滚

人交互路径(浏览器) ​

用户操作 → JmMind API (moveNode / addChildNode / ...)
    → JmMindChangeCoordinator.onNodeMoved / onNodeAdded / ...
    → view.settle(重排 + 重绘)

导出路径 ​

JmCommander.exportImage() → JmViewHandle.capture()
    → captureShadowContent: 克隆 DOM → SVG foreignObject → canvas → Blob

3. 双通道 ​

应用层有两条通往视图的通道,判断标准是「这个操作改不改模型」:

调用方 → JmCommander → JmViewHandle → JmView      (命令:导出、pan/zoom)
模型变更 → JmMindChangeCoordinator → JmView        (反应:节点增删改)

改模型的必须走第二条。 折叠、移动、改文字、改样式——数据是真相,视图是投影。把模型变更塞进 Commander 会产生第二条修改入口,和 AI 走 CLI 的路径分叉。

不改模型的走第一条。 平移、缩放、导出——只改变观察方式,不改变任何节点。JmViewHandle 是视图向应用层暴露的窄接口(当前只有 capture(),未来加 pan/zoom/centerOn)。

4. 关键决策 ​

决策理由
磁盘格式用扁平表diff 干净,增量定位 O(1),与 edges 同构,无深递归
LLM 交互用嵌套树大纲和目录树是 LLM 训练数据的天然形式
渲染用 SVG + foreignObject矢量无损缩放、贝塞尔天然支持、文字排版交给浏览器
Shadow DOM 无条件启用样式隔离是硬需求:自包含 HTML 可能被嵌进任何网页
样式用 CSS 自定义属性几何继承给宿主一次搞定,颜色继承给单节点单独覆盖
arranger 零 DOM 依赖布局测试在 Node 里跑,不需要浏览器
校验器独立于序列化器CLI 不需要加载完整 mind 就能 validate
v1 adapter 排最后等 schema 冻结,前期写等于拿会变的模型写转换器

5. 文件索引 ​

层核心文件
modelsrc/model/mind.ts, src/model/data/node.ts, src/model/data/edge.ts, src/model/data/node-content.ts, src/model/data/style.ts
serializationsrc/serialization/json.ts, src/serialization/freemind.ts, src/serialization/serializer.ts, src/serialization/validation.ts, src/serialization/serializer-factory.ts
arrangersrc/arranger/mindmap.ts
viewsrc/view/index.ts, src/view/node.ts, src/view/edge.ts, src/view/shadow.ts, src/view/export.ts, src/view/handle.ts
applicationsrc/application/jsmind.ts, src/application/mind-change-coordinator.ts, src/application/commander.ts
CLIsrc/cli/index.ts, src/cli/io.ts, src/cli/browser.ts, src/cli/commands/*.ts

本文档由 AI 协助生成 / This documentation was prepared with AI assistance