diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c37825b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,51 @@
+# graph-viewer
+
+通用**时序知识图谱查看组件**。喂给它符合格式的 `{nodes, edges}`，就能渲染力导向图——不绑定任何特定后端。最初为 [Graphiti](https://github.com/getzep/graphiti) 可视化而生，但数据源完全可插拔。
+
+- 单文件 UMD、纯 ES5（React.createElement，无 JSX、无需 babel）→ **Safari/旧浏览器友好**
+- 依赖：`react@18` + `react-dom@18` + `react-force-graph-2d@1.29`（UMD 全局）
+- ⚠️ react-force-graph-2d UMD 本身用到 `Object.entries/flat/padStart` 等 ES2017+ API；老 WebKit(Safari<12) 需配 `compat-shim.js`（见部署示例）
+
+## 数据契约（标准 Neo4j 风格）
+```js
+{
+  nodes: [{ id, labels:[], properties:{ entity_type?, name?, description? } }],
+  edges: [{ id, source, target, type?, properties?:{ keywords?, valid_at?, invalid_at? } }]
+}
+```
+- 节点按 `entity_type`(或末位 label)自动着色；标签取 `properties.name || id`
+- 边显示 `keywords`(或 `type`)文字（缩放 >1.1x 时）；`invalid_at` 非空 → 灰色虚线（bi-temporal 失效关系）
+- 点节点/边 → 右侧详情面板
+
+## 三种数据来源
+```html
+<script src="vendor/react.production.min.js"></script>
+<script src="vendor/react-dom.production.min.js"></script>
+<script src="vendor/react-force-graph-2d.min.js"></script>
+<script src="graph-viewer.js"></script>
+<div id="g" style="height:600px"></div>
+<script>
+// ① 内联数据
+GraphViewer.mount(document.getElementById('g'), { data: {nodes:[...],edges:[...]} });
+// ② 任意返回 {nodes,edges} 的 API URL
+const gv = GraphViewer.mount(el, { api: 'https://your-host/api/graph?group_id=x&limit=200' });
+gv.setData(newData);   // 动态换数据
+</script>
+```
+### ③ iframe + postMessage（宿主页面动态喂图）
+```html
+<!-- 被嵌页已加载 graph-viewer 且开启 listenPostMessage(默认开) -->
+<iframe id="f" src="viewer.html" width="100%" height="800"></iframe>
+<script>
+document.getElementById('f').contentWindow.postMessage(
+  { type:'gv-data', data:{ nodes:[...], edges:[...] } }, '*');
+</script>
+```
+
+## 文件
+- `graph-viewer.js` — 组件本体（UMD，暴露 `window.GraphViewer.mount(el, opts)`）
+- `demo.html` — 用法示例（内联 + API 两种）
+- `compat-shim.js` — 可选，旧 Safari 补 Object.entries/flat/padStart 等
+
+## License
+MIT