Skip to content

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

docs: define diagram and infographic format boundary

tianma-ifea129b1736c0
diff --git a/docs/visual-diagram-notes.md b/docs/visual-diagram-notes.md
index 4292490d..4606f7d8 100644
--- a/docs/visual-diagram-notes.md
+++ b/docs/visual-diagram-notes.md
@@ -20,6 +20,14 @@ The persisted document uses `schemaVersion` to distinguish formats: `1` for mind
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.
+## Boundary with infographic notes
+
+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.
+
+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?”:
diff --git a/docs/visual-diagram-notes.zh-CN.md b/docs/visual-diagram-notes.zh-CN.md
index a8384984..b062f817 100644
--- a/docs/visual-diagram-notes.zh-CN.md
+++ b/docs/visual-diagram-notes.zh-CN.md
@@ -20,6 +20,14 @@ IR(Intermediate Representation,中间表示)是图表的结构化事实来
MCP 与编译路径另有一层不含坐标的语义图;服务端再生成尺寸、坐标和连线标识,写入持久化文档。Agent 协议不携带 X6 或画布状态。
+## 与信息图笔记的边界
+
+信息图是另一种笔记类型,不属于上述 `DiagramIr` / `DiagramDocument`。它以 AntV Infographic 的声明式语法作为原生源文件,包在独立的 `InfographicDocument` 中,并用 `edgeever-infographic-v1` Markdown 注释保存。`schemaVersion` 管理 EdgeEver 的信封格式;它不表示 Infographic 模板或语法版本。信息图的模板、主题和数据由该语法表达,EdgeEver 不再复制一份同义的通用图形 IR。
+
+因此,思维导图、流程图、架构图仍以 EdgeEver 的语义 IR 为事实来源,经 X6 绘制和编辑;信息图由 AntV Infographic 语法直接驱动其渲染器。两种信封由各自的解析器识别,不能把另一种笔记的内容当成自己的文档解析或保存。AI 修改图形笔记应改语义图,AI 生成或修改信息图则选择 AntV 模板并生成相应数据。
+
+如果将来需要用 Infographic 呈现某张图形笔记,应添加明确的 `DiagramIr → Infographic` 投影,并说明哪些节点、连线、坐标或手工布局无法保留。该投影不能反向成为图形笔记的事实来源;在有经过验证的双向语义映射之前,不自动迁移已有笔记。
+
## IR 与绘图引擎解耦
IR 的核心价值之一,是让 EdgeEver 保留对底层绘图引擎的选择权。IR 负责回答“这张图表达什么”,适配器负责回答“当前引擎如何把它画出来”:
diff --git a/packages/shared/src/diagram-layout.ts b/packages/shared/src/diagram-layout.ts
index 62eb5981..1ef29507 100644
--- a/packages/shared/src/diagram-layout.ts
+++ b/packages/shared/src/diagram-layout.ts
@@ -76,6 +76,8 @@ export type DiagramIrNodeType =
| "external"
| "boundary";
+// Product semantics for mind maps, flowcharts, and architecture diagrams.
+// AntV Infographic syntax is a separate, renderer-native document format.
export type DiagramIr = {
kind: DiagramKind;
theme?: DiagramTheme;
diff --git a/packages/shared/src/infographic.test.mjs b/packages/shared/src/infographic.test.mjs
index 4a73b46c..c290bc1c 100644
--- a/packages/shared/src/infographic.test.mjs
+++ b/packages/shared/src/infographic.test.mjs
@@ -1,4 +1,5 @@
import { describe, expect, test } from "bun:test";
+import { createDefaultDiagramDocument, parseDiagramDocument, serializeDiagramDocument } from "./diagram.ts";
import {
createDefaultInfographicDocument,
getInfographicSummary,
@@ -23,4 +24,13 @@ describe("infographic note format", () => {
expect(parseInfographicDocument("<!-- edgeever-infographic-v1:broken -->")).toBeNull();
expect(getInfographicSummary("regular note")).toEqual({ infographic: false });
});
+
+ test("infographic syntax and visual diagram IR keep separate envelopes", () => {
+ const infographic = serializeInfographicDocument({ schemaVersion: 1, syntax: "infographic sequence-steps-simple\ndata\n sequences\n - label 开始" });
+ const diagram = serializeDiagramDocument(createDefaultDiagramDocument("flowchart"));
+ expect(parseInfographicDocument(infographic)?.syntax).toContain("sequence-steps-simple");
+ expect(parseDiagramDocument(infographic)).toBeNull();
+ expect(parseDiagramDocument(diagram)?.kind).toBe("flowchart");
+ expect(parseInfographicDocument(diagram)).toBeNull();
+ });
});
diff --git a/packages/shared/src/infographic.ts b/packages/shared/src/infographic.ts
index 125cb87b..d9858643 100644
--- a/packages/shared/src/infographic.ts
+++ b/packages/shared/src/infographic.ts
@@ -6,6 +6,7 @@ const COMMENT = /<!--\s*edgeever-infographic-v1:([A-Za-z0-9_-]+)\s*-->/;
export type InfographicDocument = {
schemaVersion: typeof INFOGRAPHIC_SCHEMA_VERSION;
+ // AntV Infographic's native source, separate from the visual diagram IR.
syntax: string;
};