@ia-ccun/idea-plugin-share 0.0.79 → 0.0.80

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ia-ccun/idea-plugin-share",
-  "version": "0.0.79",
+  "version": "0.0.80",
   "description": "IntelliJ IDEA 插件分发包：把 zip 放进 plugins/ 目录，npm publish 后内网 npm i 即可获取",
   "bin": {
     "idea-plugin": "bin/idea-plugin.js"

package/plugins/GPT-Vis-ai.zip

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: package/plugins/GPT-Vis-ai.zip
+size: 36625824 bytes
+sha256: bbb6a40d26027442cfbbc2bddbdb0ce34f76f6f4ca595ab1f8e9c2fbb5849745

package/plugins/GPT-Vis/346/234/254/345/234/260/351/203/250/347/275/262/346/211/213/345/206/214.md

@@ -0,0 +1,538 @@
+# GPT-Vis 本地部署手册
+
+> AntV GPT-Vis 三件套在本机的完整搭建、接入、排障手册
+> 最后更新：2026-10-29
+
+---
+
+## 0. TL;DR
+
+本机跑着三个进程、占两个端口：
+
+| 进程 | 端口 | 目录 | 作用 |
+|---|---|---|---|
+| Next.js 站点 | 3000 | `~/icode/GPT-Vis/site` | 文档 + 26 种图表交互示例（给人看） |
+| chart-render-server | 3001 | `~/icode/chart-render-server` | SSR 渲染 API，出 PNG（给 MCP 调） |
+| mcp-server-chart | stdio | npx 拉起 | MCP 协议层，转发到 3001 |
+
+启动：
+
+```bash
+# 渲染服务（MCP 依赖它，必须先起）
+cd ~/icode/chart-render-server && npm start        # → http://localhost:3001
+
+# 站点（可选，只是看示例用）
+cd ~/icode/GPT-Vis/site && npm run dev            # → http://localhost:3000
+```
+
+MCP 配置（已生效）：`~/.aicode-cli/agent/mcp.json` → `mcp-server-chart` 项，
+端点被 wrapper 脚本 `~/.aicode-cli/agent/bin/mcp-chart-server.sh` 钉死为
+`http://localhost:3001/render`。
+
+---
+
+## 1. GPT-Vis 是什么
+
+[antvis/GPT-Vis](https://github.com/antvis/GPT-Vis) 是面向 LLM 应用的 AI 原生可视化库，
+**不止是 UI 组件**，核心是一套让大模型能吐出来的图表语法。
+
+仓库由三块组成，本地部署时用途完全不同：
+
+| 组成 | 位置 | 本机用途 |
+|---|---|---|
+| 库本体 `@antv/gpt-vis` | 仓库根 `src/` | 构建产物供站点 / 自己的项目引用 |
+| 文档站点 | 仓库 `site/` | Next.js 16 静态站，看文档和 26 个图表示例 |
+| SSR 绑定 `@antv/gpt-vis-ssr` | 仓库 `bindings/gpt-vis-ssr/` | Node 里无头渲染成 PNG |
+
+### 能力
+
+- **26 种图表**：G2 引擎 20 种（area / bar / boxplot / column / dual-axes / funnel /
+  histogram / line / liquid / pie / radar / sankey / scatter / summary / table /
+  treemap / venn / violin / waterfall / word-cloud）+ G6 引擎 6 种
+  （fishbone-diagram / flow-diagram / indented-tree / mindmap / network-graph /
+  organization-chart）
+- **3 套主题**：`default`（亮）/ `dark` / `academy`
+- **两种输入**：JS 对象配置，或类 Markdown 的 DSL 语法
+- **流式渲染**：`isVisSyntax()` 判断缓冲区是否是图表语法，LLM 边吐边画
+
+### DSL 语法长这样
+
+```
+vis line
+data
+  - time 2020
+    value 100
+  - time 2021
+    value 120
+title My Chart
+```
+
+解析后等价于 `{ type: 'line', data: [...], title: 'My Chart' }`。
+`data` / `categories` / `series` / `children` / `nodes` / `edges` 解析成数组，
+`style` 解析成嵌套对象，值自动转 number / boolean（要保留字符串就加引号）。
+
+---
+
+## 2. 环境快照
+
+| 组件 | 版本 |
+|---|---|
+| Node.js | v24.21.0（要求 ≥ 20） |
+| npm | 11.19.0 |
+| pnpm | 12.11.2（要求 ≥ 8，CI 用 9） |
+| Next.js | 16.4.3（Turbopack） |
+| React | 19.2.3 |
+| `@antv/gpt-vis` | 1.0.2 |
+| `@antv/gpt-vis-ssr` | 0.3.8 |
+| `@antv/mcp-server-chart` | 0.9.10 |
+
+> ⚠️ Node 24 默认把 unhandled rejection 当致命错误直接杀进程。
+> 渲染服务必须加 `--unhandled-rejections=warn`，见 §7.3。
+
+---
+
+## 3. 部署
+
+### 3.1 克隆 + 构建库本体
+
+上游默认分支已经叫 `ai`（不是 `main`）：
+
+```bash
+cd ~/icode
+git clone --depth 1 https://github.com/antvis/GPT-Vis.git
+cd GPT-Vis
+
+pnpm install        # 装依赖（root）
+pnpm build          # father build → dist/{esm,cjs,umd}
+```
+
+产物：
+
+```
+dist/esm/index.js       # ESM（package.json 的 module 字段）
+dist/cjs/index.js       # CommonJS
+dist/umd/index.min.js   # UMD，2.2 MB / gzip 653 KB
+```
+
+**必须先构建库，站点才能装**——站点通过 `"@antv/gpt-vis": "file:.."` 引用父目录，
+解析的是父目录 `package.json` 里的 `module: dist/esm/index.js`。
+
+其他常用脚本：
+
+```bash
+pnpm dev            # 开发构建，只出 ESM，快
+pnpm test           # vitest
+pnpm lint:ts        # eslint
+pnpm format         # prettier
+```
+
+### 3.2 文档站点
+
+```bash
+cd ~/icode/GPT-Vis/site
+npm install         # file:.. 会把父目录软链进 node_modules
+npm run dev         # → http://localhost:3000
+```
+
+页面：
+
+| 路径 | 内容 |
+|---|---|
+| `/` | 首页 |
+| `/docs` | 文档（安装、语法、示例代码） |
+| `/examples` | 示例画廊 |
+| `/examples/<id>` | 单个图表详情，26 个 id 见 §5 |
+
+**生产构建**：
+
+```bash
+cd ~/icode/GPT-Vis/site
+npm run build       # → site/out/（33 个静态页）
+```
+
+⚠️ `site/next.config.ts` 里是 `output: 'export'`，所以 **`npm start` 用不了**
+（仓库 DEPLOYMENT.md 那段是错的，Next 16 的静态导出不支持 `next start`）。
+实测报错：`Error: "next start" does not work with "output: export" configuration. Use "npx serve@latest out" instead.`
+用任意静态服务器托管 `out/`：
+
+```bash
+cd site/out && npx serve@latest out      # Next 官方推荐
+cd site/out && python3 -m http.server 3002  # 或 nginx / caddy
+```
+
+> ⚠️ 静态托管时 `/examples/line-chart` 这种路由要落到 `.html` 文件，
+> 纯静态服务器一般靠目录索引或 rewrite 规则处理。
+
+### 3.3 SSR 渲染服务（chart-render-server）
+
+本机已有这个项目：`~/icode/chart-render-server`，Express + `@antv/gpt-vis-ssr`，
+把图表渲染成 PNG 存到 `public/charts/`，返回图片 URL。
+
+```
+server.js            # 业务逻辑
+public/charts/       # 渲染出来的 PNG
+package.json
+```
+
+接口：
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| POST | `/render` | 渲染图表 → `{success, resultObj}` |
+| GET | `/healthz` | 探活 → `{"ok":true}` |
+| GET | `/charts/<file>.png` | 取渲染结果 |
+
+启动：
+
+```bash
+cd ~/icode/chart-render-server
+npm start           # → http://localhost:3001
+```
+
+（端口 3001 是 2026-10-29 调整的，原默认 3000 与站点冲突。）
+
+冒烟测试：
+
+```bash
+curl -s http://localhost:3001/healthz
+curl -s -X POST http://localhost:3001/render \
+  -H "Content-Type: application/json" \
+  -d '{"type":"line","data":[{"time":"2025-05","value":512},{"time":"2025-06","value":1024}]}'
+# {"success":true,"resultObj":"http://localhost:3001/charts/1793243083369-e2d615c9.png"}
+```
+
+---
+
+## 4. 接入 MCP
+
+### 4.1 链路
+
+```
+AI 客户端
+  │  MCP stdio (JSON-RPC)
+  ▼
+mcp-server-chart (npx)
+  │  POST {type, ...options, source:"mcp-server-chart"}
+  ▼
+chart-render-server :3001
+  │  @antv/gpt-vis-ssr → g2-ssr / g6-ssr
+  ▼
+PNG 落盘 public/charts/ → 返回图片 URL
+```
+
+MCP 把返回的 URL 当文本交给模型，模型用 `![](url)` 渲染成图。
+
+### 4.2 配置文件
+
+`~/.aicode-cli/agent/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "mcp-server-chart": {
+      "command": "/Users/jianjiang/.aicode-cli/agent/bin/mcp-chart-server.sh",
+      "args": [],
+      "lifecycle": "lazy-keep-alive",
+      "env": {
+        "VIS_REQUEST_SERVER": "http://localhost:3001/render"
+      }
+    }
+  }
+}
+```
+
+wrapper 脚本 `~/.aicode-cli/agent/bin/mcp-chart-server.sh`：
+
+```sh
+#!/bin/sh
+# Wrapper for @antv/mcp-server-chart: force the chart API endpoint.
+# The Deck app spawns MCP servers from a cached spec (stale VIS_REQUEST_SERVER),
+# so pin the endpoint here instead of relying on the config's env block.
+export VIS_REQUEST_SERVER="http://localhost:3001/render"
+exec npx -y @antv/mcp-server-chart "$@"
+```
+
+> 为什么要有 wrapper：Deck / 桌面端会**缓存 MCP spec**再拉起子进程，
+> 配置文件里的 `env` 改动可能不生效，wrapper 里 `export` 才稳。
+
+### 4.3 关键环境变量
+
+| 变量 | 作用 | 默认 |
+|---|---|---|
+| `VIS_REQUEST_SERVER` | 自定义渲染服务地址（**不是网页地址**） | `https://antv-studio.alipay.com/api/gpt-vis` |
+| `SERVICE_ID` | 服务标识，用于生成记录 | 无 |
+| `DISABLED_TOOLS` | 逗号分隔的禁用工具名 | 无 |
+
+### 4.4 地图工具要关掉
+
+`generate_district_map` / `generate_path_map` / `generate_pin_map` 三个工具走的是
+另一套报文 `{serviceId, tool, input, source}`，而本地 `/render` 只认 `type`，
+会返回 `Missing 'type' field.`。
+
+```json
+"env": {
+  "VIS_REQUEST_SERVER": "http://localhost:3001/render",
+  "DISABLED_TOOLS": "generate_district_map,generate_path_map,generate_pin_map"
+}
+```
+
+### 4.5 验证 MCP 通了
+
+```bash
+{
+  printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}'
+  sleep 1
+  printf '%s\n' '{"jsonrpc":"2.0","method":"notifications/initialized"}'
+  sleep 1
+  printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"generate_line_chart","arguments":{"type":"line","data":[{"time":"2025-05","value":512},{"time":"2025-06","value":1024}]}}}'
+  sleep 25
+} | VIS_REQUEST_SERVER=http://localhost:3001/render npx -y @antv/mcp-server-chart
+```
+
+预期返回：
+
+```json
+{"content":[{"type":"text","text":"http://localhost:3001/charts/1793243098450-74981eda.png"}]}
+```
+
+---
+
+## 5. 图表类型支持矩阵
+
+| 图表 | 站点示例 id | MCP 工具 | SSR 支持 |
+|---|---|---|---|
+| 面积图 | area-chart | `generate_area_chart` | ✅ area |
+| 条形图 | bar-chart | `generate_bar_chart` | ✅ bar |
+| 箱线图 | boxplot | `generate_boxplot_chart` | ✅ boxplot |
+| 柱状图 | column-chart | `generate_column_chart` | ✅ column |
+| 双轴图 | dual-axes | `generate_dual_axes_chart` | ✅ dual-axes |
+| 鱼骨图 | fishbone-diagram | `generate_fishbone_diagram` | ✅ fishbone-diagram |
+| 流程图 | flow-diagram | `generate_flow_diagram` | ✅ flow-diagram |
+| 漏斗图 | funnel-chart | `generate_funnel_chart` | ✅ funnel |
+| 直方图 | histogram | `generate_histogram_chart` | ✅ histogram |
+| 折线图 | line-chart | `generate_line_chart` | ✅ line |
+| 水波图 | liquid-chart | `generate_liquid_chart` | ✅ liquid |
+| 思维导图 | mindmap | `generate_mind_map` | ✅ mind-map |
+| 网络图 | network-graph | `generate_network_graph` | ✅ network-graph |
+| 组织架构图 | organization-chart | `generate_organization_chart` | ✅ organization-chart |
+| 饼图 | pie-chart | `generate_pie_chart` | ✅ pie |
+| 雷达图 | radar-chart | `generate_radar_chart` | ✅ radar |
+| 桑基图 | sankey-diagram | `generate_sankey_chart` | ✅ sankey |
+| 散点图 | scatter-chart | `generate_scatter_chart` | ✅ scatter |
+| 表格 | table | —（MCP 用 spreadsheet） | ✅ spreadsheet |
+| 树图 | treemap | `generate_treemap_chart` | ✅ treemap |
+| 韦恩图 | venn-diagram | `generate_venn_chart` | ✅ venn |
+| 小提琴图 | violin-chart | `generate_violin_chart` | ✅ violin |
+| 瀑布图 | waterfall-chart | `generate_waterfall_chart` | ✅ waterfall |
+| 词云 | wordcloud | `generate_word_cloud_chart` | ✅ word-cloud |
+| 指标卡 | summary | — | ❌ 仅浏览器端 |
+| 缩进树 | indented-tree | — | ❌ 仅浏览器端 |
+| 行政区地图 | — | `generate_district_map` | ❌ 需另配 |
+| 路径地图 | — | `generate_path_map` | ❌ 需另配 |
+| 钉钉地图 | — | `generate_pin_map` | ❌ 需另配 |
+
+- 库本体：**26** 种（20 个 G2 + 6 个 G6）
+- SSR：**24** 种
+- MCP：**27** 个工具（24 个 SSR 图表 + 3 个地图）
+
+---
+
+## 6. 渲染 API 契约
+
+### 6.1 请求
+
+```http
+POST /render
+Content-Type: application/json
+
+{
+  "type": "line",
+  "data": [...],
+  "title": "可选标题",
+  "theme": "default | dark | academy",
+  "width": 600,
+  "height": 400,
+  "style": { "texture": "default | rough" },
+  "source": "mcp-server-chart"
+}
+```
+
+`type` 决定用哪个渲染器；`source` 是 MCP 客户端自动加的，忽略即可。
+
+### 6.2 响应
+
+```json
+{ "success": true,  "resultObj": "http://localhost:3001/charts/xxx.png" }
+{ "success": false, "errorMessage": "Unknown chart type: xxx" }
+```
+
+出错也返回 **HTTP 200**，靠 `success` 字段判断——所以别只看 HTTP 状态码。
+
+### 6.3 数据形状速查
+
+| 类型 | data 形状 |
+|---|---|
+| 常规统计图（line / bar / pie / area …） | `[{x, y}]`，字段名随意，如 `{"time":"2025-05","value":512}` |
+| tree 系列（mind-map / organization-chart / treemap） | `{"name":"根","children":[{"name":"子"}]}`，最多 3 层 |
+| graph 系列（network-graph / flow-diagram） | `{"nodes":[{"name":"A"}],"edges":[{"source":"A","target":"B"}]}` |
+| word-cloud | `[{"word":"AI","value":100}]` |
+| spreadsheet | 二维数据（对应库里的 `table`） |
+
+> ⚠️ network-graph / flow-diagram 的 `data` 必须是 `{nodes, edges}`，
+> 传别的形状会报 `Cannot read properties of undefined (reading 'map')`。
+
+---
+
+## 7. 日常运维
+
+### 7.1 启停
+
+```bash
+# 渲染服务
+cd ~/icode/chart-render-server
+npm start                          # 前台
+pkill -f "server.js"               # 停
+
+# 站点
+cd ~/icode/GPT-Vis/site
+npm run dev                        # 前台
+pkill -f "next dev"               # 停
+
+# 站点生产构建 + 静态托管
+npm run build && cd out && python3 -m http.server 3002
+```
+
+### 7.2 日志位置
+
+| 内容 | 位置 |
+|---|---|
+| 站点运行日志 | 前台终端；后台跑时自己重定向，如 `> /tmp/gpt-vis-dev.log` |
+| **浏览器端报错** | 浏览器 F12 Console。静态导出站没有服务端日志，图表错误只在这 |
+| Next dev 的浏览器报错转发 | 站点终端里 `[browser] ...` 前缀的行（Next 16 dev 特性） |
+| 渲染服务日志 | `~/icode/chart-render-server/server.log`（`npm start` 时是终端；nohup 重定向到 `/tmp/chart-render-server.log`） |
+| Next 构建诊断 | `~/icode/GPT-Vis/site/.next/diagnostics/build-diagnostics.json` |
+| Next dev 性能 trace | `~/icode/GPT-Vis/site/.next/trace` |
+| npm 安装日志 | `~/.npm/_logs/` |
+| pnpm store | `~/.local/share/pnpm/store` |
+
+### 7.3 已知稳定性问题
+
+**渲染服务会被 g2-ssr 的异步异常打死。** Node 24 默认 unhandled rejection = 崩溃，
+一个失败请求可能在响应发出后把整个进程带走，之后所有 MCP 调用都是 ECONNREFUSED。
+
+已处理：`package.json` 的 start 脚本加了 `--unhandled-rejections=warn`。
+
+```json
+"start": "PORT=3001 node --unhandled-rejections=warn server.js"
+```
+
+**站点 dev 下有 G6 销毁竞态**：StrictMode 双挂载时 `destroy()` 早于异步 `draw()`，
+控制台报 `Cannot read properties of undefined (reading 'draw')` +
+`[G6 v5.1.1] The graph instance has been destroyed`。
+来自 `@antv/g6/esm/runtime/graph.js:917` 的 `this.context.element.draw(...)` 无空值保护。
+不影响页面显示，仅 dev 出现，静态产物里没有。
+
+### 7.4 健康检查
+
+```bash
+curl -s http://localhost:3001/healthz                    # {"ok":true}
+curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/   # 站点 200
+```
+
+---
+
+## 8. 故障排查
+
+| 症状 | 原因 | 处理 |
+|---|---|---|
+| MCP 报 `success` undefined / `Error (undefined)` | `VIS_REQUEST_SERVER` 指到了网页而不是渲染 API | 改成 `http://localhost:3001/render` |
+| MCP 报 `Missing 'type' field.` | 地图工具走了另一套报文 | 加 `DISABLED_TOOLS` 关掉 3 个地图工具 |
+| MCP `ECONNREFUSED` | 渲染服务没起，或被 g2-ssr 异步异常打死 | `npm start` 重起；确认启动参数带 `--unhandled-rejections=warn` |
+| 改了 mcp.json 但端点没变 | 客户端缓存了 MCP spec | 用 wrapper 脚本 `export` 钉死端点 |
+| 站点 `Module not found: '@antv/gpt-vis'` | 库本体没构建 | 根目录 `pnpm build` 后重装 site 依赖 |
+| 站点 `/examples/xxx` 500 `missing param in generateStaticParams` | URL 的 id 写错了 | 用 §5 里的真实 id（如 `line-chart`，不是 `line`） |
+| `npm start` 报 `"next start" does not work with "output: export"` | 站点是静态导出 | `npx serve out` 托管 `site/out/` |
+| 渲染报 `Unknown chart type: xxx` | type 用了 MCP 工具名 | 用图表类型名（`mind-map` 不是 `mind_map`） |
+| 渲染报 `reading 'map'` | network-graph / flow-diagram 的 data 形状错 | 传 `{nodes, edges}` |
+| 端口起不来 EADDRINUSE | 3000/3001 被占 | `lsof -nP -iTCP -sTCP:LISTEN \| grep node` |
+
+---
+
+## 9. 在自己的项目里用这个库
+
+只想画图、不需要 MCP 的话，直接装 npm 包，不用 clone：
+
+```bash
+npm install @antv/gpt-vis
+```
+
+```js
+import { GPTVis } from '@antv/gpt-vis';
+
+const gptVis = new GPTVis({
+  container: 'container',   // string | HTMLElement
+  width: 600,
+  height: 400,
+  theme: 'default',         // 'default' | 'dark' | 'academy'
+  wrapper: false,           // true = 带 Chart/Code 切换 + 下载/复制/缩放的外壳
+  locale: 'zh-CN',
+});
+
+gptVis.render({
+  type: 'line',
+  data: [
+    { time: '2020', value: 100 },
+    { time: '2021', value: 120 },
+  ],
+});
+
+gptVis.destroy();
+```
+
+流式渲染（LLM 边生成边画）：
+
+```js
+import { GPTVis, isVisSyntax } from '@antv/gpt-vis';
+
+const gptVis = new GPTVis({ container: 'container', width: 600, height: 400 });
+let buffer = '';
+
+function onToken(token) {
+  buffer += token;
+  if (isVisSyntax(buffer)) gptVis.render(buffer);  // 直接传 DSL 字符串
+}
+```
+
+---
+
+## 10. 目录索引
+
+```
+~/icode/GPT-Vis/                  # 上游 clone，默认分支 ai
+├── src/                          # 库源码（26 种图表）
+├── site/                         # Next.js 16 站点
+│   ├── app/{docs,examples}/
+│   └── out/                      # npm run build 产物
+├── bindings/gpt-vis-ssr/         # SSR 绑定（只读参考，本机用的是 npm 包）
+├── public/, evaluations/, skills/
+└── CLAUDE.md                     # 仓库开发说明
+
+~/icode/chart-render-server/      # 本机自建渲染服务
+├── server.js                     # Express + gpt-vis-ssr
+├── public/charts/                # PNG 输出目录
+├── package.json                  # start: PORT=3001 node --unhandled-rejections=warn server.js
+└── server.log
+
+~/.aicode-cli/agent/mcp.json                        # MCP 配置
+~/.aicode-cli/agent/bin/mcp-chart-server.sh         # 端点 wrapper
+```
+
+---
+
+## 11. 参考
+
+- 上游仓库：https://github.com/antvis/GPT-Vis
+- 官方站点：https://gpt-vis.antv.vision
+- MCP 服务：https://github.com/antvis/mcp-server-chart
+- SSR 绑定：https://github.com/antvis/GPT-Vis/tree/main/bindings/gpt-vis-ssr
+- 仓库自带开发说明：`~/icode/GPT-Vis/CLAUDE.md`