Skip to content

AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.

Improve infographic selection and simplify diagram design docs

tianma-ifedc755a1802b
diff --git a/apps/web/src/components/InfographicEditorPane.tsx b/apps/web/src/components/InfographicEditorPane.tsx
index adc86616..f21b4513 100644
--- a/apps/web/src/components/InfographicEditorPane.tsx
+++ b/apps/web/src/components/InfographicEditorPane.tsx
@@ -180,7 +180,6 @@ export default function InfographicEditorPane({ memo, repository, readOnly, onBa
const [error, setError] = useState<string | null>(null);
const [renderError, setRenderError] = useState<string | null>(null);
const [previewReady, setPreviewReady] = useState(false);
- const [directEditAvailable, setDirectEditAvailable] = useState(false);
const [ready, setReady] = useState(false);
const [savedSnapshot, setSavedSnapshot] = useState(JSON.stringify([memo.title ?? "", parsed?.syntax ?? ""]));
const containerRef = useRef<HTMLDivElement>(null);
@@ -211,26 +210,64 @@ export default function InfographicEditorPane({ memo, repository, readOnly, onBa
useEffect(() => {
setPreviewReady(false);
- if (!syntax.trim()) { instanceRef.current?.destroy(); instanceRef.current = null; setRenderError(null); setDirectEditAvailable(false); return; }
+ if (!syntax.trim()) { instanceRef.current?.destroy(); instanceRef.current = null; setRenderError(null); return; }
let cancelled = false;
const timer = window.setTimeout(() => {
- void import("@antv/infographic").then(({ Infographic, DblClickEditText, parseSyntax, getTemplate }) => {
+ void import("@antv/infographic").then(({ Infographic, Interaction, DblClickEditText, SelectHighlight, parseSyntax, getTemplate }) => {
if (cancelled || !containerRef.current) return;
const parsedSyntax = parseSyntax(syntax);
if (parsedSyntax.errors.length || !parsedSyntax.options.template || !getTemplate(parsedSyntax.options.template)) {
setRenderError(parsedSyntax.errors[0]?.message ?? t("infographic.invalidSyntax"));
- setDirectEditAvailable(false);
instanceRef.current?.destroy(); instanceRef.current = null;
return;
}
try {
instanceRef.current?.destroy();
const visualTextEditable = !readOnly && Boolean(parseSimpleForm(syntax) || editableOfficialData(syntax, parsedSyntax));
- setDirectEditAvailable(visualTextEditable);
+ class SelectGraphicElement extends Interaction {
+ name = "select-graphic-element";
+ private svg: SVGSVGElement | null = null;
+ private handleClick = (event: MouseEvent) => {
+ if (!(event.target instanceof Element)) return;
+ if (event.target.closest('[contenteditable="true"]')) return;
+ const text = event.target.closest('foreignObject[data-element-type="title"], foreignObject[data-element-type="desc"], foreignObject[data-element-type="item-label"], foreignObject[data-element-type="item-desc"]');
+ const shape = event.target.closest('[data-element-type="shape"], [data-element-type="item-icon"], [data-element-type="edit-area"]');
+ let target = text ?? shape ?? event.target.closest("rect, ellipse, circle, path, polygon, polyline, line, image, text");
+ if (shape?.getAttribute("data-element-type") === "shape") {
+ let group = shape.parentElement;
+ while (group && group.parentElement?.getAttribute("data-element-type") !== "items-group") group = group.parentElement;
+ if (group) target = group;
+ }
+ if (target) this.interaction.select([target as Parameters<typeof this.interaction.select>[0][number]], event.shiftKey ? "toggle" : "replace");
+ else this.interaction.clearSelection();
+ };
+ private handleKeyDown = (event: KeyboardEvent) => {
+ if (event.key === "Escape") this.interaction.clearSelection();
+ };
+ override init(options: Parameters<(typeof DblClickEditText)["prototype"]["init"]>[0]) {
+ super.init(options);
+ const svg = options.editor.getDocument();
+ this.svg = svg;
+ svg.addEventListener("click", this.handleClick);
+ document.addEventListener("keydown", this.handleKeyDown);
+ }
+ override destroy() {
+ this.svg?.removeEventListener("click", this.handleClick);
+ document.removeEventListener("keydown", this.handleKeyDown);
+ }
+ }
const instance = new Infographic({
container: containerRef.current, width: "100%", height: "100%",
editable: visualTextEditable,
- ...(visualTextEditable ? { interactions: [new DblClickEditText()], plugins: [] } : {}),
+ ...(visualTextEditable ? { interactions: [new SelectGraphicElement(), new DblClickEditText(), new SelectHighlight()], plugins: [] } : {}),
+ });
+ if (visualTextEditable) instance.on("selection:change", ({ previous, next }: { previous: Element[]; next: Element[] }) => {
+ for (const element of previous) element.classList.remove("edgeever-infographic-selected-text");
+ for (const element of next) {
+ if (["title", "desc", "item-label", "item-desc"].includes((element as HTMLElement).dataset.elementType ?? "")) {
+ element.classList.add("edgeever-infographic-selected-text");
+ }
+ }
});
if (visualTextEditable) instance.on("options:change", (payload: VisualTextChange) => {
const nextSyntax = applyVisualTextChange(syntax, payload) ?? applyOfficialVisualTextChange(syntax, payload, parsedSyntax);
@@ -379,7 +416,7 @@ export default function InfographicEditorPane({ memo, repository, readOnly, onBa
</div>
</div>}
</section>
- <section className="min-h-0 overflow-auto bg-slate-50 p-4"><h2 className="mb-1 text-sm font-medium text-slate-600">{t("infographic.preview")}</h2>{directEditAvailable && <p className="mb-3 text-xs text-slate-500">{t("infographic.doubleClickText")}</p>}<div className="min-h-[420px] rounded-xl border border-slate-200 bg-white p-4 shadow-sm"><div ref={containerRef} className="min-h-[380px] w-full" />{!syntax.trim() && <p className="pt-32 text-center text-sm text-slate-400">{t("infographic.noPreview")}</p>}{renderError && <p role="alert" className="text-sm text-red-600">{renderError}</p>}</div></section>
+ <section className="min-h-0 overflow-auto bg-slate-50 p-4"><div className="min-h-[420px] rounded-xl border border-slate-200 bg-white p-4 shadow-sm"><div ref={containerRef} className="min-h-[380px] w-full" />{!syntax.trim() && <p className="pt-32 text-center text-sm text-slate-400">{t("infographic.noPreview")}</p>}{renderError && <p role="alert" className="text-sm text-red-600">{renderError}</p>}</div></section>
</div>
</div>;
}
diff --git a/apps/web/src/styles/globals.css b/apps/web/src/styles/globals.css
index 718ccbf8..d0e5a7e8 100644
--- a/apps/web/src/styles/globals.css
+++ b/apps/web/src/styles/globals.css
@@ -7,6 +7,11 @@
@tailwind components;
@tailwind utilities;
+.edgeever-infographic-selected-text {
+ outline: 2px solid #3384f5;
+ outline-offset: 2px;
+}
+
@keyframes edgeever-token-created {
0% {
opacity: 0;
diff --git a/docs/visual-diagram-notes.md b/docs/visual-diagram-notes.md
index 4606f7d8..864ff9bc 100644
--- a/docs/visual-diagram-notes.md
+++ b/docs/visual-diagram-notes.md
@@ -1,122 +1,23 @@
# Visual Diagram Notes Design
-This document records the technical choices and design decisions behind EdgeEver visual diagram notes (mind maps, flowcharts, and architecture diagrams). It is a reference for future development, review, and cross-platform work.
+EdgeEver has two graphic-note paths: mind maps, flowcharts, and architecture diagrams use `DiagramDocument`; infographics use AntV Infographic syntax. They are stored separately and are not converted automatically.
-## What IR means
+## Diagram notes
-IR stands for Intermediate Representation. It is the structured source of truth between user editing operations and a concrete rendering engine. It stores node and edge semantics, coordinates, and dimensions without binding the note to X6, Mermaid, or a platform UI.
+`DiagramDocument` is the source of truth for editable diagrams. It stores nodes, edges, necessary layout, and semantics rather than X6 view state. `kind` distinguishes `mind-map`, `flowchart`, and `architecture`; `schemaVersion` governs format changes. Architecture boundaries and connection types, along with mind-map hierarchy, are part of the document.
-```text
-User operations → Diagram IR → X6 / Mermaid / exporters
-```
+Web and desktop edit with AntV X6. Android, iOS, and public shares render the same IR read-only. A Base64URL-encoded IR lives in the persisted Markdown's `edgeever-diagram-v1` comment. The Mermaid diagram in the body supports reading outside EdgeEver and fallback when IR parsing fails; it is not the editing canvas. Mermaid code blocks in ordinary notes are a separate feature.
-This abstraction provides three immediate benefits:
+Parsing and validation live in [`diagram.ts`](../packages/shared/src/diagram.ts), semantic compilation and layout in [`diagram-layout.ts`](../packages/shared/src/diagram-layout.ts), and cross-platform read-only rendering in [`diagram-view.ts`](../packages/shared/src/diagram-view.ts). Native apps remain read-only until they can safely edit the same IR.
-- The same diagram can be rendered by different engines on different platforms.
-- Visual, layout, or rendering-library changes do not require migrating the note's meaning.
-- Data can be validated before rendering, rejecting dangling edges, invalid containment, and unsupported node types.
+## Infographics
-The persisted document uses `schemaVersion` to distinguish formats: `1` for mind maps and flowcharts, `2` for architecture diagrams, which add semantic components, system boundaries, connection types, and bidirectional relationships. The Markdown envelope comment is always `edgeever-diagram-v1` and does not change with `schemaVersion`.
+An infographic is a separate note type whose source is AntV Infographic's declarative syntax. The syntax directly holds its template, theme, and data. `InfographicDocument` stores it in an `edgeever-infographic-v1` comment; EdgeEver does not duplicate those fields in another generic IR. Each note type has its own parser.
-MCP and the compile path use a separate semantic graph without coordinates. The server then generates sizes, coordinates, and edge identities into the persisted document. The agent protocol does not carry X6 or canvas state.
+Presenting a diagram note through Infographic would require an explicit `DiagramDocument → Infographic` conversion that identifies lost layout or interaction data. Existing notes should not be migrated until a bidirectional mapping is validated.
-## Boundary with infographic notes
+## AI and MCP
-An infographic is a separate note type, outside `DiagramIr` and `DiagramDocument`. Its native source is AntV Infographic's declarative syntax, wrapped in an independent `InfographicDocument` and stored in an `edgeever-infographic-v1` Markdown comment. `schemaVersion` versions EdgeEver's envelope, not the Infographic template or syntax. The syntax already expresses template, theme, and data, so EdgeEver does not duplicate it in a generic visual IR.
+Diagram AI and MCP accept a coordinate-free semantic graph, which the server validates and lays out. `create_diagram_memo` creates a diagram note, `get_diagram` reads its semantic graph, and `update_diagram` applies incremental changes with `expectedRevision` to prevent overwrites. Its default `reflow=preserve` keeps existing layout; `reflow=all` is reserved for an explicitly requested full relayout. The generic `update_memo` does not directly replace diagram content.
-Mind maps, flowcharts, and architecture diagrams therefore keep EdgeEver's semantic IR as their source of truth and use X6 for drawing and editing. Infographics drive the AntV Infographic renderer directly from their syntax. Separate parsers identify the two envelopes; neither note type should parse or save the other's document. AI changes to visual diagrams operate on the semantic graph, while AI generation or changes to infographics choose an AntV template and produce matching data.
-
-If a visual diagram later needs an Infographic presentation, add an explicit `DiagramIr → Infographic` projection and document which nodes, edges, coordinates, or authored layout cannot be preserved. That projection must not become the diagram note's source of truth in reverse. Existing notes should not be migrated automatically without a validated bidirectional semantic mapping.
-
-## IR and rendering-engine decoupling
-
-One of the IR's central benefits is preserving EdgeEver's freedom to choose its underlying rendering engines. The IR answers “what does this diagram mean?”, while an adapter answers “how does this engine draw it?”:
-
-```text
- ┌→ X6 Adapter → Web / desktop editing; first-party viewing and public share
-Diagram IR ────────┼→ Mermaid Adapter → portable envelope, rich-text embedded diagrams, IR-parse fallback
- ├→ Export Adapter → SVG / PNG
- └→ MCP Tools → AI reading and modification
-```
-
-This separation does not erase differences between engines. Node coordinates, dimensions, containment, and connection directions still carry layout meaning, and renderers may support different capabilities. Explicit adapters isolate those differences instead of pretending that all engines are equivalent.
-
-The IR should contain stable business semantics and necessary layout facts, such as “this is a database,” “it belongs to the backend boundary,” and “a service accesses it through a data connection.” X6 SVG paths, internal events, view instances, and temporary selection state must stay out of the IR; otherwise engine coupling has merely moved into the persisted format.
-
-## Current data model
-
-The persisted IR is a `DiagramDocument` with `schemaVersion`, `kind` (`mind-map` / `flowchart` / `architecture`), optional `theme`, and, for mind maps, optional `structure`. A node contains `id`, `label`, `x`, `y`, `width`, `height`, and `shape`; optional `parentId` (mind-map topic hierarchy, or containment inside an architecture boundary) and `resourceIcon` (architecture resource appearance). An edge has required `id`, `source`, and `target`, with optional `label`, `kind`, and `bidirectional` fields.
-
-A diagram is stored as portable Markdown. Its body contains a Mermaid fallback, while a trailing `edgeever-diagram-v1` comment carries the Base64URL-encoded JSON IR. The IR is the source of truth for lossless editing. The Mermaid fence is a projection, not the live canvas: first-party clients, including public share, parse the IR and draw with AntV X6. The fence remains so the note stays readable as ordinary Markdown outside EdgeEver, and when the IR comment fails to parse.
-
-User-authored ` ```mermaid ` code blocks in ordinary rich-text notes are a separate product feature. They do not use this IR and are not visual-diagram notes.
-
-Parsing and validation live in [`packages/shared/src/diagram.ts`](../packages/shared/src/diagram.ts). Semantic-graph compilation and automatic layout live in [`packages/shared/src/diagram-layout.ts`](../packages/shared/src/diagram-layout.ts). The read-only X6 adapter is [`packages/shared/src/diagram-view.ts`](../packages/shared/src/diagram-view.ts) (`diagramDocumentToX6Cells`), reused by Android, iOS, and public share. The Web / desktop editor consumes the same IR but has its own interactive node mapping.
-
-## Why AntV X6
-
-Visual diagram notes need an editable canvas: selection, dragging, zooming, connections, undo and redo, keyboard controls, automatic layout, and PNG/SVG export. AntV X6 supplies that canvas kernel; it is not the product model for any one diagram type. Mind maps, flowcharts, and architecture diagrams share the same engine. Their differences live in IR semantics and EdgeEver's node and edge customization.
-
-The IR answers “what does this diagram mean?”; the X6 adapter answers “how do we draw it and let the user edit it?” X6 internals, coordinate conventions, and view instances therefore stay out of the persisted format. Adopting a second engine for one diagram type would also import another state manager, coordinate system, interaction model, and data format, leaving two canvases to maintain.
-
-Android and iOS read-only viewers, and public share, reuse the same X6 adapter (`diagramDocumentToX6Cells` plus a non-interactive `Graph`). The Web / desktop editor uses the same IR and engine with an interactive mapping of its own. First-party canvases no longer split between X6 on Web and Mermaid on mobile. Mermaid remains the portable envelope, the renderer for embedded rich-text diagrams, and the fallback when IR parsing fails.
-
-This does not mean rendering every node as the same X6 rectangle. X6 is only the underlying engine; icons, SVG markup, shapes, ports, colors, boundaries, and connection semantics are customized by EdgeEver per diagram type.
-
-## Cross-platform rendering boundary
-
-| Surface | Capability | Rendering path |
-| --- | --- | --- |
-| Web / PWA / desktop | Create, edit, auto-layout, revision history, and PNG/SVG export | IR → AntV X6 |
-| Android app | Semantic read-only view with complete IR preservation | IR → AntV X6 (read-only Graph in the note WebView) |
-| iOS app | Semantic read-only view with complete IR preservation | IR → AntV X6 (read-only Graph in WKWebView) |
-| Public share of a visual diagram note | Read-only view of the same IR | IR → AntV X6 (read-only Graph) |
-| Ordinary rich-text notes, including embedded ` ```mermaid ` blocks | Create, edit, share, HTML / print / WeChat copy | TipTap; Mermaid code blocks stay Mermaid |
-| Invalid or unreadable IR comment | Degraded read of the same visual diagram note | Mermaid fence in the Markdown body |
-
-The native apps currently hide regular rich-text editing, double-tap editing, and AI rewriting for visual diagram notes. Those paths cannot represent diagram IR and could overwrite a structured diagram with plain text. Users can read, sync, share, and inspect history in the apps, while editing remains available on Web and desktop.
-
-An early mobile viewer used the Mermaid fence because AntV X6 was not yet wrapped in the native WebViews. That dual-track is historical. First-party canvases, including public share, render visual diagram notes from IR through X6. Embedded Mermaid diagrams in ordinary rich-text notes remain a separate feature and keep using the Mermaid renderer.
-
-## Agreed design principles
-
-- Diagram semantics belong to the IR; the rendering engine is not the data source.
-- First-party canvases render visual diagram notes from IR through X6. Embedded ` ```mermaid ` blocks in ordinary rich-text notes stay on Mermaid. The persisted Mermaid fence on a visual diagram note is only a portable envelope and a degraded fallback, not the live canvas.
-- Architecture components must communicate their purpose visually; names are supplementary.
-- `parentId` is containment: topic hierarchy on a mind map, a system boundary on an architecture diagram. A system boundary is not a normal connectable business node.
-- `theme` and a mind map's `structure` are presentation choices on the document, not engine-private state.
-- Web and native apps consume the same persisted data rather than platform-specific diagram copies.
-- New versions should keep old diagrams readable. Format evolution is managed through `schemaVersion`; the envelope comment stays `edgeever-diagram-v1`.
-- Native apps remain read-only until a touch editor can safely read and write the same IR.
-
-## MCP and AI-generated diagrams
-
-For MCP and AI, the semantic graph is the stable tool protocol. An AI can work with it instead of producing X6 internals, SVG, or an entire Mermaid document. It can therefore perform a local request such as “add a Redis cache between the API and database” while preserving the user's other nodes and layout decisions.
-
-There are three diagram MCP tools:
-
-- `create_diagram_memo` accepts a semantic graph: node identities, labels, types, containment, and connections, plus optional `theme`, `structure`, and `layout.direction`. The server generates edge identities, node dimensions, coordinates, deterministic layout, and architecture boundary geometry, then compiles a persisted `DiagramDocument`. Layout direction is a compile hint and is not stored on the document. Results return the semantic graph, not the encoded persistence payload.
-- `get_diagram` returns only the semantic graph and memo revision by default, without coordinates or dimensions; node geometry is included only when `includeLayout` is true.
-- `update_diagram` accepts incremental operations on that one tool: `add_node`, `update_node`, `remove_node`, `add_edge`, `update_edge`, and `remove_edge`. It uses `expectedRevision` to prevent concurrent overwrites and supports `dryRun` previews. The default `reflow=preserve` keeps unaffected authored layout; `reflow=all` is only for an explicit full relayout. Moving a node into a boundary or changing mind-map hierarchy is `update_node` with `parentId`, not a separate MCP tool.
-
-The generic `update_memo` tool cannot replace diagram content. There is no `replace_diagram_ir`, and no standalone validate or apply-layout tool: validation happens when the server applies operations, and layout is controlled by `reflow`.
-
-The recommended flow is:
-
-```text
-get_diagram
- → AI produces incremental operations
- → optional dryRun preview
- → update_diagram (preserve layout by default)
- → server validates types, references, and containment, then writes a new revision
-```
-
-AI should modify semantics by default, with deterministic layout handling coordinates. Use `reflow=all` or change `theme` / `structure` only when the user explicitly wants a full relayout or a presentation change.
-
-An IR can still become a liability if it mirrors X6 too closely, lacks useful semantics, changes versions frequently, or lets AI overwrite a whole diagram without validation. The schema should therefore remain small, stable, versioned, validated, and friendly to incremental operations.
-
-## Future direction
-
-Full native editing should continue to use the same IR and separately address touch selection, dragging, connections, zooming, keyboard avoidance, and large-diagram performance. Whether that editor uses X6 in a WebView or a native canvas should be decided through prototypes and performance testing without changing the persisted format.
-
-HTML / print / WeChat copy of a visual diagram note still go through the generic rich-text pipeline when that pipeline is used, because those actions currently snapshot TipTap HTML rather than the X6 canvas. Native share-as-image has the same gap. Align those exports with a read-only X6 snapshot before considering any change to the Markdown envelope. PNG / SVG export from the diagram editor already comes from X6.
+Infographic AI selects an AntV template and generates matching data; people can refine text on the canvas. Each path retains its own source of truth instead of persisting a rendered result.
diff --git a/docs/visual-diagram-notes.zh-CN.md b/docs/visual-diagram-notes.zh-CN.md
index b062f817..188410fc 100644
--- a/docs/visual-diagram-notes.zh-CN.md
+++ b/docs/visual-diagram-notes.zh-CN.md
@@ -1,122 +1,23 @@
# 可视化图表笔记设计说明
-本文记录 EdgeEver 可视化图表笔记(思维导图、流程图、架构图)的技术选型与方案决策,供后续开发、评审和跨端适配参考。
+EdgeEver 有两条图形笔记路径:思维导图、流程图和架构图使用 `DiagramDocument`;信息图使用 AntV Infographic 语法。两者独立保存,不自动互转。
-## IR 是什么
+## 图形笔记
-IR(Intermediate Representation,中间表示)是图表的结构化事实来源,位于“用户编辑操作”和“具体渲染引擎”之间。它保存节点、连线、坐标、尺寸和语义,但不绑定 X6、Mermaid 或某个平台 UI。
+`DiagramDocument` 是可编辑图形的事实来源,保存节点、连线、必要布局和语义,而非 X6 视图状态。`kind` 区分 `mind-map`、`flowchart`、`architecture`;`schemaVersion` 管理格式演进。架构图的系统边界和连接类型、思维导图的层级关系也保存在文档中。
-```text
-用户操作 → Diagram IR → X6 / Mermaid / 导出器
-```
+Web 和桌面端用 AntV X6 编辑;Android、iOS 和公开分享用同一份 IR 只读绘制。持久化 Markdown 的 `edgeever-diagram-v1` 注释保存 Base64URL 编码的 IR,正文中的 Mermaid 图表用于外部阅读及 IR 解析失败时降级,不是编辑画布。普通笔记内的 Mermaid 代码块属于独立功能。
-这层抽象带来三个直接收益:
+解析与校验见 [`diagram.ts`](../packages/shared/src/diagram.ts),语义图编译及布局见 [`diagram-layout.ts`](../packages/shared/src/diagram-layout.ts),跨端只读绘制见 [`diagram-view.ts`](../packages/shared/src/diagram-view.ts)。原生 App 在能安全读写同一 IR 前保持只读。
-- 同一份图表可以在不同端由不同引擎渲染。
-- 更换外观、布局或渲染库时,不需要迁移笔记的业务含义。
-- 数据可以先验证再渲染,避免悬空连线、非法父子关系和错误节点类型进入编辑器。
+## 信息图
-持久化文档用 `schemaVersion` 区分格式:思维导图和流程图为 `1`,架构图为 `2`,后者增加语义组件、系统边界、连线类型和双向关系。Markdown 信封注释名始终是 `edgeever-diagram-v1`,不随 `schemaVersion` 改名。
+信息图是独立笔记类型,以 AntV Infographic 的声明式语法为源文件;模板、主题和数据直接写在该语法中。`InfographicDocument` 用 `edgeever-infographic-v1` 注释保存它,EdgeEver 不再复制一套同义的通用 IR。两种笔记由各自的解析器处理。
-MCP 与编译路径另有一层不含坐标的语义图;服务端再生成尺寸、坐标和连线标识,写入持久化文档。Agent 协议不携带 X6 或画布状态。
+若将来要用 Infographic 展示图形笔记,需要显式的 `DiagramDocument → Infographic` 转换,并说明无法保留的布局或交互信息;在验证双向映射前,不迁移既有笔记。
-## 与信息图笔记的边界
+## AI 与 MCP
-信息图是另一种笔记类型,不属于上述 `DiagramIr` / `DiagramDocument`。它以 AntV Infographic 的声明式语法作为原生源文件,包在独立的 `InfographicDocument` 中,并用 `edgeever-infographic-v1` Markdown 注释保存。`schemaVersion` 管理 EdgeEver 的信封格式;它不表示 Infographic 模板或语法版本。信息图的模板、主题和数据由该语法表达,EdgeEver 不再复制一份同义的通用图形 IR。
+图形笔记的 AI / MCP 输入是不含坐标的语义图,由服务端校验并生成布局。`create_diagram_memo` 创建图形笔记,`get_diagram` 读取语义图,`update_diagram` 用增量操作修改,并通过 `expectedRevision` 防止覆盖;默认 `reflow=preserve`,只有明确要求整图重排时才用 `reflow=all`。通用 `update_memo` 不直接覆盖图形笔记内容。
-因此,思维导图、流程图、架构图仍以 EdgeEver 的语义 IR 为事实来源,经 X6 绘制和编辑;信息图由 AntV Infographic 语法直接驱动其渲染器。两种信封由各自的解析器识别,不能把另一种笔记的内容当成自己的文档解析或保存。AI 修改图形笔记应改语义图,AI 生成或修改信息图则选择 AntV 模板并生成相应数据。
-
-如果将来需要用 Infographic 呈现某张图形笔记,应添加明确的 `DiagramIr → Infographic` 投影,并说明哪些节点、连线、坐标或手工布局无法保留。该投影不能反向成为图形笔记的事实来源;在有经过验证的双向语义映射之前,不自动迁移已有笔记。
-
-## IR 与绘图引擎解耦
-
-IR 的核心价值之一,是让 EdgeEver 保留对底层绘图引擎的选择权。IR 负责回答“这张图表达什么”,适配器负责回答“当前引擎如何把它画出来”:
-
-```text
- ┌→ X6 Adapter → Web / 桌面交互编辑;自有客户端阅读与公开分享
-Diagram IR ────────┼→ Mermaid Adapter → 可移植信封、富文本嵌入图表、IR 解析失败时的降级
- ├→ Export Adapter → SVG / PNG
- └→ MCP Tools → AI 读取与修改
-```
-
-这种解耦并不代表不同引擎之间不存在差异。节点坐标、尺寸、容器关系和连线方向仍具有布局含义,各渲染器也可能支持不同能力,因此需要明确的适配层。目标是隔离差异,而不是假设所有引擎完全等价。
-
-IR 中应保存稳定的业务语义和必要布局,例如“这是数据库”“它位于后端边界中”“服务通过数据连接访问它”。X6 的 SVG Path、内部事件、视图实例、临时选择状态等引擎细节不应进入 IR,否则只是把强耦合转移到了持久化格式中。
-
-## 当前数据模型
-
-持久化 IR 是 `DiagramDocument`,包含 `schemaVersion`、`kind`(`mind-map` / `flowchart` / `architecture`)、可选 `theme`,思维导图还可带 `structure`。节点包含 `id`、`label`、`x`、`y`、`width`、`height`、`shape`;可选 `parentId`(思维导图的主题层级,或架构图中位于系统边界内)和 `resourceIcon`(架构图资源外观)。连线包含必填的 `id`、`source`、`target`,并可携带 `label`、`kind` 和 `bidirectional`。
-
-图表保存为一份可移植 Markdown:正文包含 Mermaid 降级视图,末尾的 `edgeever-diagram-v1` 注释保存 Base64URL 编码的 JSON IR。IR 是无损编辑的事实来源。Mermaid fence 是投影,不是实时画布:自有客户端(含公开分享)解析 IR 后由 AntV X6 绘制。保留 fence 是为了让笔记在 EdgeEver 之外的普通 Markdown 中仍可读,以及 IR 注释解析失败时仍能降级显示。
-
-普通富文本笔记里用户手写的 ` ```mermaid ` 代码块是独立功能,不走这套 IR,也不是可视化图表笔记。
-
-解析和校验集中在 [`packages/shared/src/diagram.ts`](../packages/shared/src/diagram.ts)。语义图编译与自动布局在 [`packages/shared/src/diagram-layout.ts`](../packages/shared/src/diagram-layout.ts)。只读画布的 X6 适配器在 [`packages/shared/src/diagram-view.ts`](../packages/shared/src/diagram-view.ts)(`diagramDocumentToX6Cells`),供 Android、iOS 与公开分享复用;Web / 桌面编辑器使用同一 IR,但有自己的可交互节点映射。
-
-## 为什么使用 AntV X6
-
-可视化图表笔记需要一块可编辑画布:选择、拖拽、缩放、连线、撤销重做、键盘操作、自动布局和 PNG/SVG 导出。AntV X6 提供的是这套画布内核,而不是某一种图表类型的产品模型。思维导图、流程图和架构图共用同一引擎,差异落在 IR 语义和 EdgeEver 的节点、连线定制上。
-
-IR 负责回答“这张图表达什么”,X6 适配器负责回答“当前如何把它画出来并让用户改”。因此不把 X6 内部状态、坐标约定或视图实例写进持久化格式。如果为某一类图表另选引擎,会同时引入另一套状态管理、坐标体系、交互约定和数据格式,并让两套画布长期并存。
-
-Android、iOS 的只读查看和公开分享复用同一套 X6 适配器(`diagramDocumentToX6Cells` 加不可交互的 `Graph`)。Web / 桌面编辑器走同一 IR 和同一引擎,但使用可交互的编辑器映射。自有客户端画布不再按「Web 用 X6、移动端用 Mermaid」分轨。Mermaid 仍用于可移植信封、富文本嵌入图表,以及 IR 解析失败时的降级。
-
-这并不意味着把所有节点画成同一种 X6 矩形。X6 只是底层引擎;图标、SVG 标记、形状、端口、配色、边界和连线语义均由 EdgeEver 按图表类型定制。
-
-## 跨端渲染边界
-
-| 场景 | 能力 | 渲染路径 |
-| --- | --- | --- |
-| Web / PWA / 桌面端 | 创建、编辑、自动布局、历史版本、PNG/SVG 导出 | IR → AntV X6 |
-| Android App | 语义化只读查看,完整保留 IR | IR → AntV X6(笔记 WebView 中的只读 Graph) |
-| iOS App | 语义化只读查看,完整保留 IR | IR → AntV X6(WKWebView 中的只读 Graph) |
-| 图形笔记的公开分享 | 同一份 IR 的只读查看 | IR → AntV X6(只读 Graph) |
-| 普通富文本笔记,含嵌入的 ` ```mermaid ` 代码块 | 创建、编辑、分享、HTML / 打印 / 微信复制 | TipTap;Mermaid 代码块仍走 Mermaid |
-| IR 注释无效或无法解析 | 同一张图形笔记的降级阅读 | Markdown 正文中的 Mermaid fence |
-
-原生 App 暂不开放普通富文本编辑、双击编辑或 AI 改写入口,因为这些路径无法表达图表 IR,可能把结构化图表覆盖成普通文本。用户可在 App 中阅读、同步、分享和查看历史版本,在 Web 或桌面端完成图表编辑。
-
-移动端早期用 Mermaid fence 看图,是因为原生 WebView 尚未封装 AntV X6。那条双轨已经是历史。自有客户端画布(含公开分享)由 IR 经 X6 绘制图形笔记。普通富文本里嵌入的 Mermaid 图表是独立功能,继续走 Mermaid 渲染器。
-
-## 已确定的设计原则
-
-- 图表语义由 IR 决定,渲染引擎不是数据源。
-- 自有客户端画布由 IR 经 X6 绘制图形笔记。普通富文本里的 ` ```mermaid ` 代码块仍走 Mermaid。图形笔记里持久化的 Mermaid fence 只是可移植信封和降级路径,不是实时画布。
-- 架构组件必须“看外观就知道用途”,名称只是补充。
-- `parentId` 表示包含关系:思维导图是主题层级,架构图是系统边界;系统边界不是可连线的普通业务节点。
-- `theme` 与思维导图的 `structure` 属于文档上的呈现选择,不是引擎私有状态。
-- Web 与原生 App 使用同一份持久化数据,不维护平台专属图表副本。
-- 新版本优先保持旧图可读;格式演进通过 `schemaVersion` 明确管理,信封注释名保持 `edgeever-diagram-v1`。
-- 在原生触控编辑器能够安全读写同一 IR 之前,App 保持只读。
-
-## MCP 与 AI 生成图表
-
-对于 MCP 和 AI,语义图是稳定的工具协议:Agent 不必生成 X6 内部配置、SVG 或整张 Mermaid 源码,因此可以理解和执行“在 API 与数据库之间增加 Redis 缓存”这类局部修改,同时保留用户已经调整好的其他节点和布局。
-
-当前图表 MCP 工具只有三个:
-
-- `create_diagram_memo` 接收语义图:节点标识、名称、类型、容器关系与连接关系,以及可选的 `theme`、`structure` 和 `layout.direction`。服务端生成连线标识、节点尺寸、坐标、确定性布局和架构边界几何,再编译为持久化 `DiagramDocument`。布局方向只是编译提示,不写入持久化文档。返回语义图,不返回编码后的持久化载荷。
-- `get_diagram` 默认只返回语义图和笔记 revision,不含坐标与尺寸;只有 `includeLayout` 为 true 时才附带节点几何。
-- `update_diagram` 在同一工具上接收增量操作 `add_node` / `update_node` / `remove_node` / `add_edge` / `update_edge` / `remove_edge`。用 `expectedRevision` 防止并发覆盖,支持 `dryRun` 预览。默认 `reflow=preserve`,保留未受影响节点的已有布局;仅在明确要求整图重排时使用 `reflow=all`。移入系统边界或调整思维导图层级,是 `update_node` 的 `parentId`,不是单独的 MCP 工具。
-
-通用的 `update_memo` 不允许直接覆盖图表正文。没有 `replace_diagram_ir`,也没有独立的校验或自动布局工具:校验发生在服务端应用操作时,布局由 `reflow` 控制。
-
-推荐流程是:
-
-```text
-get_diagram
- → AI 生成增量操作
- → 可选 dryRun 预览
- → update_diagram(默认保留布局)
- → 服务端校验类型、引用和容器关系后写入新版本
-```
-
-AI 默认改语义层;确定性布局算法负责坐标。只有用户明确要求整图重排或调整外观时,才使用 `reflow=all` 或修改 `theme` / `structure`。
-
-Schema 应保持小而稳定、可版本化、可校验,并继续走增量操作。如果格式过度贴近 X6、语义过少、版本频繁变化,或允许不经校验地覆盖整张图,IR 就会变成新的耦合点。
-
-## 后续演进方向
-
-如果要实现原生 App 完整编辑,应继续复用同一 IR,并单独设计触控选择、拖拽、连线、缩放、键盘避让和大图性能。是否复用 X6 WebView 或开发原生画布,应通过原型和性能测试决定,而不应改变已保存的数据格式。
-
-图形笔记的 HTML / 打印 / 微信复制若走通用富文本管道,仍会快照 TipTap HTML 而不是 X6 画布。原生端的图片分享同样如此。应先让这些导出与只读 X6 快照对齐,再考虑改动 Markdown 信封。图表编辑器里的 PNG / SVG 导出已经直接来自 X6。
+信息图的 AI 选择 AntV 模板并生成对应数据,人工可在画布上微调文字。两条路径都保留各自的事实来源,不把渲染结果当作持久化文档。