万相 Wanxiang

万相是一个由 Agent 驱动的开放式可视化后台服务。它把文本或截图转换为可交互的教学微场景、SVG/HTML 视觉解释、专业关系图或公式产物。

万相不是桌面 App，也不依赖固定场景模板。通用大模型负责理解问题和选择工具，MCP 工具负责提供专业能力，Verifier 负责协议与安全校验。

核心特点

• 开放产物：支持 HTML、内联 SVG、CSS 和本地 JavaScript，不受固定图表类型限制。

• Agent 工具循环：模型可以按需获取风格指南、调用外部 MCP 工具，再创建视觉产物。

• MCP 可扩展：通过 VIS_MCP_SERVERS 动态发现其他 MCP 服务。

• 风格与语义分离：内置 textbook、blueprint、minimal、chalk 四套视觉风格。

• 安全沙箱：默认禁止外部资源、网络请求、存储、内联事件和动态执行。

• 两种使用方式：HTTP 后台服务，或由 Agent 直接启动的 stdio MCP 服务。

• 跨平台：启动器支持 macOS 和 Windows，自动准备隔离 Python 环境。

Related MCP server: Visual QA MCP

工作原理

文本 / 截图
    ↓
理解问题与教学意图
    ↓
发现并按需调用可视化 MCP 工具
    ↓
生成开放 HTML / 关系图 / 公式 Artifact
    ↓
协议、安全和完整性校验
    ↓
返回可渲染的 Artifact JSON

万相不会把所有内容都转成关系图。几何模拟、嵌套结构、函数图像、交互实验和自定义 SVG 都可以由 Agent 自然生成。

环境要求

• Node.js 20+

• Python 3.11+

• 可选：支持 OpenAI Chat Completions 的多模态模型

NVM 只负责管理 Node.js 版本；服务启动使用 npx。

快速启动

1. 配置模型

export VIS_AGENT_BASE_URL=https://api.kimi.com/coding/v1
export VIS_AGENT_API_KEY=你的密钥
export VIS_AGENT_MODEL=k3.1-pro
export VIS_AGENT_REASONING_EFFORT=low

也可以复制 .env.example 为 .env 后填写。.env 已被 Git 忽略。

未配置模型时，HTTP 服务会进入本地降级模式，只返回原始内容视图；截图理解需要配置多模态模型。

2. 启动 HTTP 服务

npx -y github:yourlarok/wanxiang start

默认监听 127.0.0.1:8765。指定端口：

npx -y github:yourlarok/wanxiang start --port 9000

首次启动会在 ~/.wanxiang/.venv 创建隔离 Python 环境并安装依赖。可通过 WANXIANG_HOME 修改数据目录。

检查环境：

npx -y github:yourlarok/wanxiang doctor

3. 调用 HTTP API

curl http://127.0.0.1:8765/health

curl -X POST http://127.0.0.1:8765/v2/visualizations \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "张量形状为(2,3)，分别说明 axis=0、1、2 插入维度是什么意思",
    "preference": "interactive",
    "style": "textbook"
  }'

返回示例结构：

{
  "version": "2.0",
  "artifact_type": "html",
  "title": "张量插入维度的三个位置",
  "explanation": "通过嵌套框理解新增长度为 1 的轴。",
  "style": "textbook",
  "html": {
    "body": "...",
    "css": "...",
    "javascript": "...",
    "document": "<!doctype html>..."
  },
  "verification": {
    "passed": true,
    "checks": ["HTML/CSS/JavaScript 安全校验通过"]
  }
}

html.document 可以在无同源权限的 iframe 沙箱中直接渲染：

<iframe sandbox="allow-scripts" srcdoc="..."></iframe>

不要给生成的 iframe 添加 allow-same-origin，也不要关闭其内容安全策略。

由 Agent 通过 MCP 使用

启动 stdio MCP 服务：

npx -y github:yourlarok/wanxiang mcp

MCP 客户端配置示例：

{
  "mcpServers": {
    "wanxiang": {
      "command": "npx",
      "args": ["-y", "github:yourlarok/wanxiang", "mcp"]
    }
  }
}

提供的工具：

• visualize：根据文本或 base64 图片生成视觉产物。

• list_visual_styles：获取视觉风格和设计令牌。

模型环境变量需要在启动 MCP 服务的环境中提供。

接入其他 MCP 工具

VIS_MCP_SERVERS 是 JSON 数组。以下示例接入 Generative UI MCP：

export VIS_MCP_SERVERS='[{"name":"generative-ui","command":"npx","args":["-y","generative-ui-mcp"]}]'

启动后，万相会动态发现外部工具，并以 mcp__服务名__工具名 的形式提供给 Agent。Agent 可以先获取设计规范或计算结果，再调用万相的 create_*_artifact 工具生成统一产物。

外部 MCP 服务应由你自行审核；万相不会默认安装未经确认的第三方服务。

视觉风格

风格只决定视觉语言，不限制 Agent 选择什么图形。

安全边界

• HTML 不允许 script、iframe、外部资源和内联事件。

• CSS 不允许 @import、url() 和表达式。

• JavaScript 不允许网络、存储、动态执行、访问宿主页面。

• 产物必须包含简明解释，关系图必须验证节点与边引用。

• 模型密钥只从环境变量或本地 .env 读取，不写入 Artifact。

当前 Verifier 以协议、安全和结构校验为主；视觉截图评审与教学效果评分仍需后续增强。

本地开发

git clone https://github.com/yourlarok/wanxiang.git
cd wanxiang
npm ci
npm run doctor
npm start

直接启动 Python 服务：

cd server
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --host 127.0.0.1 --port 8765

当前限制

• 复杂开放 HTML 的首次生成可能需要较长时间，取决于模型和工具调用次数。

• 启动器按 Windows 与 macOS 设计；不同企业安全策略仍可能影响 MCP 子进程。

• 外部 MCP 工具的质量、权限和可用性由各服务自身决定。

License

MIT