feat(infographic-markdown): add new plugin for JS render to Markdown

- Add infographic_markdown.py (English) and infographic_markdown_cn.py (Chinese) - AI-powered infographic generator using AntV library - Renders SVG on frontend and embeds as Markdown Data URL image - Supports 18+ infographic templates (lists, charts, comparisons, etc.) Docs: - Add plugin README.md and README_CN.md - Add docs detail pages (infographic-markdown.md) - Update docs index pages with new plugin - Add 'JS Render to Markdown' pattern to plugin development guides - Update copilot-instructions.md with new advanced development pattern Version: 1.0.0
2026-01-05 17:29:52 +08:00
parent 28d55c1469
commit 6de0d6fbe4
11 changed files with 2155 additions and 5 deletions
--- a/docs/development/plugin-guide.md
+++ b/docs/development/plugin-guide.md
@@ -235,6 +235,125 @@ llm_response = await generate_chat_completion(
 )
 ```

+### 4.4 JS Render to Markdown (Data URL Embedding)
+
+For scenarios requiring complex frontend rendering (e.g., AntV charts, Mermaid diagrams) but wanting **persistent pure Markdown output**, use the Data URL embedding pattern:
+
+#### Workflow
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  1. Python Action                                             │
+│     ├── Analyze message content                               │
+│     ├── Call LLM to generate structured data (optional)       │
+│     └── Send JS code to frontend via __event_call__           │
+├──────────────────────────────────────────────────────────────┤
+│  2. Browser JS (via __event_call__)                           │
+│     ├── Dynamically load visualization library                │
+│     ├── Render SVG/Canvas offscreen                           │
+│     ├── Export to Base64 Data URL via toDataURL()             │
+│     └── Update message content via REST API                   │
+├──────────────────────────────────────────────────────────────┤
+│  3. Markdown Rendering                                        │
+│     └── Display ![description](data:image/svg+xml;base64,...) │
+└──────────────────────────────────────────────────────────────┘
+```
+
+#### Python Side (Send JS for Execution)
+
+```python
+async def action(self, body, __event_call__, __metadata__, ...):
+    chat_id = self._extract_chat_id(body, __metadata__)
+    message_id = self._extract_message_id(body, __metadata__)
+    
+    # Generate JS code
+    js_code = self._generate_js_code(
+        chat_id=chat_id,
+        message_id=message_id,
+        data=processed_data,
+    )
+    
+    # Execute JS
+    if __event_call__:
+        await __event_call__({
+            "type": "execute",
+            "data": {"code": js_code}
+        })
+```
+
+#### JavaScript Side (Render and Write-back)
+
+```javascript
+(async function() {
+    // 1. Load visualization library
+    if (typeof VisualizationLib === 'undefined') {
+        await new Promise((resolve, reject) => {
+            const script = document.createElement('script');
+            script.src = 'https://cdn.example.com/lib.min.js';
+            script.onload = resolve;
+            script.onerror = reject;
+            document.head.appendChild(script);
+        });
+    }
+    
+    // 2. Create offscreen container
+    const container = document.createElement('div');
+    container.style.cssText = 'position:absolute;left:-9999px;';
+    document.body.appendChild(container);
+    
+    // 3. Render visualization
+    const instance = new VisualizationLib({ container });
+    instance.render(data);
+    
+    // 4. Export to Data URL
+    const dataUrl = await instance.toDataURL({ type: 'svg', embedResources: true });
+    
+    // 5. Cleanup
+    instance.destroy();
+    document.body.removeChild(container);
+    
+    // 6. Generate Markdown image
+    const markdownImage = `![Chart](${dataUrl})`;
+    
+    // 7. Update message via API
+    const token = localStorage.getItem("token");
+    await fetch(`/api/v1/chats/${chatId}/messages/${messageId}/event`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${token}`
+        },
+        body: JSON.stringify({
+            type: "chat:message",
+            data: { content: originalContent + "\n\n" + markdownImage }
+        })
+    });
+})();
+```
+
+#### Benefits
+
+- **Pure Markdown Output**: Standard Markdown image syntax, no HTML code blocks
+- **Self-Contained**: Images embedded as Base64 Data URL, no external dependencies
+- **Persistent**: Via API write-back, images remain after page reload
+- **Cross-Platform**: Works on any client supporting Markdown images
+
+#### HTML Injection vs JS Render to Markdown
+
+| Feature | HTML Injection | JS Render + Markdown |
+|---------|----------------|----------------------|
+| Output Format | HTML code block | Markdown image |
+| Interactivity | ✅ Buttons, animations | ❌ Static image |
+| External Deps | Requires JS libraries | None (self-contained) |
+| Persistence | Depends on browser | ✅ Permanent |
+| File Export | Needs special handling | ✅ Direct export |
+| Use Case | Interactive content | Infographics, chart snapshots |
+
+#### Reference Implementations
+
+- `plugins/actions/js-render-poc/infographic_markdown.py` - AntV Infographic + Data URL
+- `plugins/actions/js-render-poc/js_render_poc.py` - Basic proof of concept
+
 ---

 ## 5. Best Practices & Design Principles
--- a/docs/development/plugin-guide.zh.md
+++ b/docs/development/plugin-guide.zh.md
@@ -199,7 +199,124 @@ async def background_job(self, chat_id):
    pass
 ```

---
+### 4.3 JS 渲染并嵌入 Markdown (Data URL 嵌入)
+
+对于需要复杂前端渲染（如 AntV 图表、Mermaid 图表）但希望结果**持久化为纯 Markdown 格式**的场景，推荐使用 Data URL 嵌入模式：
+
+#### 工作流程
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  1. Python Action                                             │
+│     ├── 分析消息内容                                           │
+│     ├── 调用 LLM 生成结构化数据（可选）                         │
+│     └── 通过 __event_call__ 发送 JS 代码到前端                 │
+├──────────────────────────────────────────────────────────────┤
+│  2. Browser JS (通过 __event_call__)                          │
+│     ├── 动态加载可视化库                                       │
+│     ├── 离屏渲染 SVG/Canvas                                    │
+│     ├── 使用 toDataURL() 导出 Base64 Data URL                  │
+│     └── 通过 REST API 更新消息内容                             │
+├──────────────────────────────────────────────────────────────┤
+│  3. Markdown 渲染                                             │
+│     └── 显示 ![描述](data:image/svg+xml;base64,...)           │
+└──────────────────────────────────────────────────────────────┘
+```
+
+#### Python 端（发送 JS 执行）
+
+```python
+async def action(self, body, __event_call__, __metadata__, ...):
+    chat_id = self._extract_chat_id(body, __metadata__)
+    message_id = self._extract_message_id(body, __metadata__)
+    
+    # 生成 JS 代码
+    js_code = self._generate_js_code(
+        chat_id=chat_id,
+        message_id=message_id,
+        data=processed_data,
+    )
+    
+    # 执行 JS
+    if __event_call__:
+        await __event_call__({
+            "type": "execute",
+            "data": {"code": js_code}
+        })
+```
+
+#### JavaScript 端（渲染并回写）
+
+```javascript
+(async function() {
+    // 1. 加载可视化库
+    if (typeof VisualizationLib === 'undefined') {
+        await new Promise((resolve, reject) => {
+            const script = document.createElement('script');
+            script.src = 'https://cdn.example.com/lib.min.js';
+            script.onload = resolve;
+            script.onerror = reject;
+            document.head.appendChild(script);
+        });
+    }
+    
+    // 2. 创建离屏容器
+    const container = document.createElement('div');
+    container.style.cssText = 'position:absolute;left:-9999px;';
+    document.body.appendChild(container);
+    
+    // 3. 渲染可视化
+    const instance = new VisualizationLib({ container });
+    instance.render(data);
+    
+    // 4. 导出为 Data URL
+    const dataUrl = await instance.toDataURL({ type: 'svg', embedResources: true });
+    
+    // 5. 清理
+    instance.destroy();
+    document.body.removeChild(container);
+    
+    // 6. 生成 Markdown 图片
+    const markdownImage = `![图表](${dataUrl})`;
+    
+    // 7. 通过 API 更新消息
+    const token = localStorage.getItem("token");
+    await fetch(`/api/v1/chats/${chatId}/messages/${messageId}/event`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${token}`
+        },
+        body: JSON.stringify({
+            type: "chat:message",
+            data: { content: originalContent + "\n\n" + markdownImage }
+        })
+    });
+})();
+```
+
+#### 优势
+
+- **纯 Markdown 输出**：结果是标准的 Markdown 图片语法，无需 HTML 代码块
+- **自包含**：图片以 Base64 Data URL 嵌入，无外部依赖
+- **持久化**：通过 API 回写，消息重新加载后图片仍然存在
+- **跨平台**：任何支持 Markdown 图片的客户端都能显示
+
+#### HTML 注入 vs JS 渲染嵌入 Markdown
+
+| 特性 | HTML 注入 | JS 渲染 + Markdown 图片 |
+|------|----------|------------------------|
+| 输出格式 | HTML 代码块 | Markdown 图片 |
+| 交互性 | ✅ 支持按钮、动画 | ❌ 静态图片 |
+| 外部依赖 | 需要加载 JS 库 | 无（图片自包含） |
+| 持久化 | 依赖浏览器渲染 | ✅ 永久可见 |
+| 文件导出 | 需特殊处理 | ✅ 直接导出 |
+| 适用场景 | 交互式内容 | 信息图、图表快照 |
+
+#### 参考实现
+
+- `plugins/actions/js-render-poc/infographic_markdown.py` - AntV 信息图 + Data URL
+- `plugins/actions/js-render-poc/js_render_poc.py` - 基础概念验证

 ## 5. 最佳实践与设计原则

--- a/docs/plugins/actions/index.md
+++ b/docs/plugins/actions/index.md
@@ -77,6 +77,16 @@ Actions are interactive plugins that:

    [:octicons-arrow-right-24: Documentation](summary.md)

+-   :material-image-text:{ .lg .middle } **Infographic to Markdown**
+
+    ---
+
+    AI-powered infographic generator that renders SVG and embeds it as Markdown Data URL image.
+
+    **Version:** 1.0.0
+
+    [:octicons-arrow-right-24: Documentation](infographic-markdown.md)
+
 </div>

 ---
--- a/docs/plugins/actions/index.zh.md
+++ b/docs/plugins/actions/index.zh.md
@@ -77,6 +77,16 @@ Actions 是交互式插件，能够：

    [:octicons-arrow-right-24: 查看文档](summary.md)

+-   :material-image-text:{ .lg .middle } **信息图转 Markdown**
+
+    ---
+
+    AI 驱动的信息图生成器，渲染 SVG 并以 Markdown Data URL 图片嵌入。
+
+    **版本：** 1.0.0
+
+    [:octicons-arrow-right-24: 查看文档](infographic-markdown.zh.md)
+
 </div>

 ---
--- a/docs/plugins/actions/infographic-markdown.md
+++ b/docs/plugins/actions/infographic-markdown.md
@@ -0,0 +1,120 @@
+# Infographic to Markdown
+
+> **Version:** 1.0.0 | **Author:** Fu-Jie
+
+AI-powered infographic generator that renders SVG on the frontend and embeds it directly into Markdown as a Data URL image.
+
+## Overview
+
+This plugin combines the power of AI text analysis with AntV Infographic visualization to create beautiful infographics that are embedded directly into chat messages as Markdown images.
+
+### Key Features
+
+- :robot: **AI-Powered**: Automatically analyzes text and selects the best infographic template
+- :bar_chart: **Multiple Templates**: Supports 18+ infographic templates (lists, charts, comparisons, etc.)
+- :framed_picture: **Self-Contained**: SVG/PNG embedded as Data URL, no external dependencies
+- :memo: **Markdown Native**: Results are pure Markdown images, compatible everywhere
+- :arrows_counterclockwise: **API Writeback**: Updates message content via REST API for persistence
+
+### How It Works
+
+```mermaid
+graph TD
+    A[User triggers action] --> B[Python extracts message content]
+    B --> C[LLM generates Infographic syntax]
+    C --> D[Frontend JS loads AntV library]
+    D --> E[Render SVG offscreen]
+    E --> F[Export to Data URL]
+    F --> G[Update message via API]
+    G --> H[Display as Markdown image]
+```
+
+## Installation
+
+1. Download `infographic_markdown.py` (English) or `infographic_markdown_cn.py` (Chinese)
+2. Navigate to **Admin Panel** → **Settings** → **Functions**
+3. Upload the file and configure settings
+4. Use the action button in chat messages
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `SHOW_STATUS` | bool | `true` | Show operation status updates |
+| `MODEL_ID` | string | `""` | LLM model ID (empty = use current model) |
+| `MIN_TEXT_LENGTH` | int | `50` | Minimum text length required |
+| `MESSAGE_COUNT` | int | `1` | Number of recent messages to use |
+| `SVG_WIDTH` | int | `800` | Width of generated SVG (pixels) |
+| `EXPORT_FORMAT` | string | `"svg"` | Export format: `svg` or `png` |
+
+## Supported Templates
+
+| Category | Template | Description |
+|----------|----------|-------------|
+| List | `list-grid` | Grid cards |
+| List | `list-vertical` | Vertical list |
+| Tree | `tree-vertical` | Vertical tree |
+| Tree | `tree-horizontal` | Horizontal tree |
+| Mind Map | `mindmap` | Mind map |
+| Process | `sequence-roadmap` | Roadmap |
+| Process | `sequence-zigzag` | Zigzag process |
+| Relation | `relation-sankey` | Sankey diagram |
+| Relation | `relation-circle` | Circular relation |
+| Compare | `compare-binary` | Binary comparison |
+| Analysis | `compare-swot` | SWOT analysis |
+| Quadrant | `quadrant-quarter` | Quadrant chart |
+| Chart | `chart-bar` | Bar chart |
+| Chart | `chart-column` | Column chart |
+| Chart | `chart-line` | Line chart |
+| Chart | `chart-pie` | Pie chart |
+| Chart | `chart-doughnut` | Doughnut chart |
+| Chart | `chart-area` | Area chart |
+
+## Usage Example
+
+1. Generate some text content in the chat (or have the AI generate it)
+2. Click the **📊 Infographic to Markdown** action button
+3. Wait for AI analysis and SVG rendering
+4. The infographic will be embedded as a Markdown image
+
+## Technical Details
+
+### Data URL Embedding
+
+The plugin converts SVG graphics to Base64-encoded Data URLs:
+
+```javascript
+const svgData = new XMLSerializer().serializeToString(svg);
+const base64 = btoa(unescape(encodeURIComponent(svgData)));
+const dataUri = "data:image/svg+xml;base64," + base64;
+const markdownImage = `![description](${dataUri})`;
+```
+
+### AntV toDataURL API
+
+```javascript
+// Export as SVG (recommended)
+const svgUrl = await instance.toDataURL({
+    type: 'svg',
+    embedResources: true
+});
+
+// Export as PNG
+const pngUrl = await instance.toDataURL({
+    type: 'png',
+    dpr: 2
+});
+```
+
+## Notes
+
+1. **Browser Compatibility**: Requires modern browsers with ES6+ and Fetch API support
+2. **Network Dependency**: First use requires loading AntV library from CDN
+3. **Data URL Size**: Base64 encoding increases size by ~33%
+4. **Chinese Fonts**: SVG export embeds fonts for correct display
+
+## Related Resources
+
+- [AntV Infographic Documentation](https://infographic.antv.vision/)
+- [Infographic API Reference](https://infographic.antv.vision/reference/infographic-api)
+- [Infographic Syntax Guide](https://infographic.antv.vision/learn/infographic-syntax)
--- a/docs/plugins/actions/infographic-markdown.zh.md
+++ b/docs/plugins/actions/infographic-markdown.zh.md
@@ -0,0 +1,120 @@
+# 信息图转 Markdown
+
+> **版本:** 1.0.0 | **作者:** Fu-Jie
+
+AI 驱动的信息图生成器，在前端渲染 SVG 并以 Data URL 图片格式直接嵌入到 Markdown 中。
+
+## 概述
+
+这个插件结合了 AI 文本分析能力和 AntV Infographic 可视化引擎，生成精美的信息图并以 Markdown 图片格式直接嵌入到聊天消息中。
+
+### 主要特性
+
+- :robot: **AI 驱动**: 自动分析文本并选择最佳的信息图模板
+- :bar_chart: **多种模板**: 支持 18+ 种信息图模板（列表、图表、对比等）
+- :framed_picture: **自包含**: SVG/PNG 以 Data URL 嵌入，无外部依赖
+- :memo: **Markdown 原生**: 结果是纯 Markdown 图片，兼容任何平台
+- :arrows_counterclockwise: **API 回写**: 通过 REST API 更新消息内容实现持久化
+
+### 工作原理
+
+```mermaid
+graph TD
+    A[用户触发动作] --> B[Python 提取消息内容]
+    B --> C[LLM 生成 Infographic 语法]
+    C --> D[前端 JS 加载 AntV 库]
+    D --> E[离屏渲染 SVG]
+    E --> F[导出为 Data URL]
+    F --> G[通过 API 更新消息]
+    G --> H[显示为 Markdown 图片]
+```
+
+## 安装
+
+1. 下载 `infographic_markdown.py`（英文版）或 `infographic_markdown_cn.py`（中文版）
+2. 进入 **管理面板** → **设置** → **功能**
+3. 上传文件并配置设置
+4. 在聊天消息中使用动作按钮
+
+## 配置选项
+
+| 参数 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `SHOW_STATUS` | bool | `true` | 是否显示操作状态 |
+| `MODEL_ID` | string | `""` | LLM 模型 ID（空则使用当前模型） |
+| `MIN_TEXT_LENGTH` | int | `50` | 最小文本长度要求 |
+| `MESSAGE_COUNT` | int | `1` | 用于生成的最近消息数量 |
+| `SVG_WIDTH` | int | `800` | 生成的 SVG 宽度（像素） |
+| `EXPORT_FORMAT` | string | `"svg"` | 导出格式：`svg` 或 `png` |
+
+## 支持的模板
+
+| 类别 | 模板名称 | 描述 |
+|------|----------|------|
+| 列表 | `list-grid` | 网格卡片 |
+| 列表 | `list-vertical` | 垂直列表 |
+| 树形 | `tree-vertical` | 垂直树 |
+| 树形 | `tree-horizontal` | 水平树 |
+| 思维导图 | `mindmap` | 思维导图 |
+| 流程 | `sequence-roadmap` | 路线图 |
+| 流程 | `sequence-zigzag` | 折线流程 |
+| 关系 | `relation-sankey` | 桑基图 |
+| 关系 | `relation-circle` | 圆形关系 |
+| 对比 | `compare-binary` | 二元对比 |
+| 分析 | `compare-swot` | SWOT 分析 |
+| 象限 | `quadrant-quarter` | 四象限图 |
+| 图表 | `chart-bar` | 条形图 |
+| 图表 | `chart-column` | 柱状图 |
+| 图表 | `chart-line` | 折线图 |
+| 图表 | `chart-pie` | 饼图 |
+| 图表 | `chart-doughnut` | 环形图 |
+| 图表 | `chart-area` | 面积图 |
+
+## 使用示例
+
+1. 在聊天中生成一些文本内容（或让 AI 生成）
+2. 点击 **📊 信息图转 Markdown** 动作按钮
+3. 等待 AI 分析和 SVG 渲染
+4. 信息图将以 Markdown 图片形式嵌入
+
+## 技术细节
+
+### Data URL 嵌入
+
+插件将 SVG 图形转换为 Base64 编码的 Data URL：
+
+```javascript
+const svgData = new XMLSerializer().serializeToString(svg);
+const base64 = btoa(unescape(encodeURIComponent(svgData)));
+const dataUri = "data:image/svg+xml;base64," + base64;
+const markdownImage = `![描述](${dataUri})`;
+```
+
+### AntV toDataURL API
+
+```javascript
+// 导出 SVG（推荐）
+const svgUrl = await instance.toDataURL({
+    type: 'svg',
+    embedResources: true
+});
+
+// 导出 PNG
+const pngUrl = await instance.toDataURL({
+    type: 'png',
+    dpr: 2
+});
+```
+
+## 注意事项
+
+1. **浏览器兼容性**: 需要现代浏览器支持 ES6+ 和 Fetch API
+2. **网络依赖**: 首次使用需要从 CDN 加载 AntV Infographic 库
+3. **Data URL 大小**: Base64 编码会增加约 33% 的体积
+4. **中文字体**: SVG 导出时会嵌入字体以确保正确显示
+
+## 相关资源
+
+- [AntV Infographic 官方文档](https://infographic.antv.vision/)
+- [Infographic API 参考](https://infographic.antv.vision/reference/infographic-api)
+- [Infographic 语法规范](https://infographic.antv.vision/learn/infographic-syntax)