visualknowledge 0.1.0

package/README.md

@@ -0,0 +1,115 @@
+# VisualKnowledge
+
+Interactive AI Chat with Visualization — 用可视化方式与 AI 对话，让复杂概念一目了然。
+
+## 功能特性
+
+- **流式对话** — 基于 Claude API 的实时流式响应，打字机效果逐字呈现
+- **内联图表渲染** — AI 回复中的 Mermaid 图表、HTML 可视化与文字自然交叉排列，而非堆叠在底部
+- **多主题支持** — 深色 / 浅色主题一键切换
+- **Markdown 完整支持** — 代码高亮、表格、引用块、列表等
+- **一键启动** — `npx visualknowledge` 即用，无需手动克隆或配置环境
+- **隐私优先** — 所有数据本地处理，无远程追踪
+- **端口自动检测** — 默认端口被占用时自动递增寻找可用端口
+- **优雅退出** — Ctrl+C 干净终止所有子进程，无残留
+
+## 快速开始
+
+### 方式一：npx（推荐）
+
+```bash
+npx visualknowledge
+```
+
+首次运行会自动下载依赖并打开浏览器。之后只需一条命令即可启动。
+
+### 方式二：本地运行
+
+**前置要求：**
+
+- Python 3.10+
+- Node.js 16+（仅用于 npx 启动方式）
+- Flask、Anthropic SDK（`pip install flask anthropic`）
+- 设置环境变量 `ANTHROPIC_API_KEY`
+
+**启动：**
+
+```bash
+# 克隆仓库
+git clone https://github.com/user/VisualKnowledge.git
+cd VisualKnowledge
+
+# 安装 Python 依赖
+pip install flask anthropic
+
+# 设置 API Key
+export ANTHROPIC_API_KEY=your-key-here
+
+# 启动服务
+python server.py
+# 或使用 npx 启动脚本
+node bin/visualknowledge.js
+```
+
+浏览器自动打开 `http://localhost:5000`。
+
+### 命令行选项
+
+| 选项 | 说明 |
+|------|------|
+| `-p, --port <port>` | 指定起始端口（默认 5000） |
+| `--no-open` | 启动后不自动打开浏览器 |
+| `-h, --help` | 显示帮助信息 |
+| `-v, --version` | 显示版本号 |
+
+```bash
+npx visualknowledge -p 8080          # 使用端口 8080
+npx visualknowledge --no-open       # 不自动打开浏览器
+```
+
+## 技术栈
+
+| 层 | 技术 |
+|----|------|
+| 前端 | 原生 HTML / CSS / JavaScript（SPA） |
+| 后端 | Python Flask + Anthropic SDK |
+| 可视化 | Mermaid.js + 自定义 HTML 渲染器 |
+| 分发 | npm（Node.js bootstrap 脚本） |
+| 数据库 | SQLite（本地存储） |
+
+## 项目结构
+
+```
+VisualKnowledge/
+├── index.html              # 前端 SPA（聊天界面 + 渲染引擎）
+├── server.py               # Flask 后端（API + 流式响应）
+├── package.json            # npm 包配置（npx 支持）
+├── bin/
+│   └── visualknowledge.js  # npx 入口脚本（环境检测 + 进程管理）
+├── skills/
+│   └── visualize.py        # 可视化技能提示词
+└── static/                 # 静态资源
+```
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `ANTHROPIC_API_KEY` | API 密钥 | （必填） |
+| `ANTHROPIC_BASE_URL` | API 基础 URL | `https://open.bigmodel.cn/api/anthropic` |
+| `ANTHROPIC_MODEL` | 模型名称 | `GLM-5V-Turbo` |
+
+## 未来方向
+
+- [ ] **多模型支持** — 接入 OpenAI、Gemini 等更多 LLM 后端，通过配置切换
+- [ ] **对话历史持久化** — 支持多会话管理、搜索历史记录、导出对话
+- [ ] **插件系统** — 可扩展的技能/插件架构，用户自定义可视化模板
+- [ ] **协作模式** — 多人实时共享画板，同步查看和编辑可视化内容
+- [ ] **离线模式** — 本地 LLM（Ollama）集成，完全离线使用
+- [ ] **移动端适配** — 响应式布局优化，PWA 支持
+- [ ] **更多图表类型** — ECharts/D3.js 集成，支持更丰富的数据可视化
+- [ ] **国际化** — 多语言界面支持
+
+## License
+
+MIT

package/bin/visualknowledge.js

@@ -0,0 +1,396 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const { spawn, exec } = require('child_process');
+const net = require('net');
+const os = require('os');
+const path = require('path');
+
+// ─── Constants ───────────────────────────────────────────────
+const PKG_VERSION = require('../package.json').version;
+const DEFAULT_PORT = 5000;
+const MAX_PORT_RETRIES = 10;
+const READY_TIMEOUT_MS = 15_000;
+const SHUTDOWN_TIMEOUT_MS = 3000;
+
+// ─── CLI Argument Parsing (T006) ─────────────────────────────
+function parseArgs(argv) {
+  const opts = {
+    port: DEFAULT_PORT,
+    noOpen: false,
+    help: false,
+    version: false,
+  };
+  const args = argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--port' || a === '-p') {
+      opts.port = parseInt(args[++i], 10);
+      if (isNaN(opts.port) || opts.port < 1 || opts.port > 65535) {
+        console.error('✗ Invalid port number. Must be between 1-65535.');
+        process.exit(1);
+      }
+    } else if (a === '--no-open') {
+      opts.noOpen = true;
+    } else if (a === '--help' || a === '-h') {
+      opts.help = true;
+    } else if (a === '--version' || a === '-v') {
+      opts.version = true;
+    } else if (a.startsWith('-')) {
+      console.error(`✗ Unknown option: ${a}`);
+      console.error('Run with --help for usage information.');
+      process.exit(1);
+    }
+  }
+  return opts;
+}
+
+function printHelp() {
+  console.log(`
+  VisualKnowledge v${PKG_VERSION}
+
+  Usage:
+    npx visualknowledge [options]
+
+  Options:
+    -p, --port <port>   Specify starting port (default: ${DEFAULT_PORT})
+    --no-open           Do not auto-open browser after startup
+    -h, --help          Show this help message
+    -v, --version       Show version number
+
+  Examples:
+    npx visualknowledge              # Start on default port 5000
+    npx visualknowledge -p 8080      # Start on port 8080
+    npx visualknowledge --no-open    # Start without opening browser
+`.trimStart() + '\n');
+}
+
+// ─── Terminal Output Helpers ──────────────────────────────────
+const OK = '✓';
+const FAIL = '✗';
+const WARN = '⚠';
+
+function banner() {
+  console.log(`\n  VisualKnowledge v${PKG_VERSION}\n`);
+}
+
+// ─── T003: Node.js Version Check ──────────────────────────────
+function checkNodeVersion() {
+  const ver = process.versions.node;
+  const major = parseInt(ver.split('.')[0], 10);
+  if (major < 16) {
+    console.log(`${FAIL} Node.js version too old`);
+    console.log(`    Installed: v${ver}`);
+    console.log(`    Required: >= 16.0.0\n`);
+    console.log('  Fix: Upgrade Node.js from https://nodejs.org/');
+    process.exit(1);
+  }
+  console.log(`${OK} Node.js v${ver}`);
+  return true;
+}
+
+// ─── T004: Python Detection ───────────────────────────────────
+function findPython() {
+  return new Promise((resolve) => {
+    // Try python3 first, then python
+    const candidates = process.platform === 'win32' ? ['python', 'py'] : ['python3', 'python'];
+    let idx = 0;
+
+    function tryNext() {
+      if (idx >= candidates.length) {
+        resolve(null);
+        return;
+      }
+      const cmd = candidates[idx++];
+      exec(`${cmd} --version`, (err, stdout, stderr) => {
+        // python outputs version to stderr on some platforms
+        const output = (stdout || stderr || '').trim();
+        if (!err && output.toLowerCase().startsWith('python')) {
+          resolve({ command: cmd, output });
+        } else {
+          tryNext();
+        }
+      });
+    }
+
+    tryNext();
+  });
+}
+
+async function checkPython() {
+  const py = await findPython();
+  if (!py) {
+    console.log(`${FAIL} Python 3.10+ not found`);
+    console.log('\n  Fix: Install Python 3.10+ from https://www.python.org/downloads/\n'
+      + '       Or via: brew install python@3.10  (macOS)\n'
+      + '                sudo apt install python3.10  (Ubuntu)\n');
+    process.exit(1);
+  }
+
+  // Parse version from output like "Python 3.10.12"
+  const match = py.output.match(/(\d+\.\d+(\.\d+)?)/);
+  const verStr = match ? match[1] : '0.0';
+  const parts = verStr.split('.').map(Number);
+  const [major, minor] = parts;
+
+  if (major < 3 || (major === 3 && minor < 10)) {
+    console.log(`${FAIL} Python version too old`);
+    console.log(`    Installed: ${verStr}`);
+    console.log(`    Required: >= 3.10.0\n`);
+    console.log('  Fix: Upgrade Python from https://www.python.org/downloads/');
+    process.exit(1);
+  }
+
+  console.log(`${OK} Python ${verStr}`);
+  return py.command;
+}
+
+// ─── T005: Python Dependency Check ────────────────────────────
+function checkDeps(pythonCmd) {
+  return new Promise((resolve) => {
+    const script = `
+import importlib, sys
+missing = []
+for pkg in ('flask', 'anthropic'):
+    try:
+        importlib.import_module(pkg.replace('-', '_'))
+    except ImportError:
+        missing.append(pkg)
+if missing:
+    print('MISSING:' + ','.join(missing))
+    sys.exit(1)
+else:
+    print('OK')
+`;
+    const child = spawn(pythonCmd, ['-c', script], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: process.env,
+    });
+
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', (d) => { stderr += d; });
+    child.on('close', (code) => {
+      if (code !== 0) {
+        const missing = (stdout.match(/MISSING:(.+)/) || [])[1];
+        if (missing) {
+          console.log(`${FAIL} Missing Python dependencies:`);
+          missing.split(',').forEach((dep) => {
+            console.log(`      - ${dep.trim()}`);
+          });
+          console.log(`\n  Fix: pip install ${missing}\n`);
+        } else {
+          console.log(`${FAIL} Dependency check failed`);
+          if (stderr.trim()) console.log(`    ${stderr.trim()}`);
+        }
+        process.exit(1);
+      }
+      console.log(`${OK} Dependencies OK (flask, anthropic)`);
+      resolve(true);
+    });
+  });
+}
+
+// ─── T007 + T013 + T014: Port Detection ──────────────────────
+function findAvailablePort(startPort, maxRetries) {
+  return new Promise((resolve, reject) => {
+    let attempt = 0;
+
+    function tryPort(port) {
+      attempt++;
+      if (attempt > maxRetries) {
+        reject(new Error('NO_PORTS'));
+        return;
+      }
+
+      const server = net.createServer();
+      server.once('error', () => {
+        console.log(`${WARN} Port ${port} in use, trying ${port + 1}...`);
+        tryPort(port + 1);
+      });
+      server.once('listening', () => {
+        server.close(() => resolve(port));
+      });
+
+      server.listen(port, '0.0.0.0');
+    }
+
+    tryPort(startPort);
+  });
+}
+
+// ─── T010: Cross-platform Browser Opening ────────────────────
+function openBrowser(url) {
+  let cmd;
+  switch (process.platform) {
+    case 'darwin': cmd = `open "${url}"`; break;
+    case 'win32': cmd = `start "" "${url}"`; break;
+    default: cmd = `xdg-open "${url}"`; break;
+  }
+
+  exec(cmd, (err) => {
+    if (err) {
+      console.log(`${WARN} Could not open browser automatically`);
+      console.log(`    Please navigate manually to: ${url}\n`);
+    }
+  });
+}
+
+// ─── T008: Python Flask Subprocess Launch ────────────────────
+function startServer(pythonCmd, port) {
+  const serverDir = path.resolve(__dirname, '..');
+
+  const child = spawn(pythonCmd, ['server.py', '--port', String(port)], {
+    cwd: serverDir,
+    stdio: 'inherit',
+    env: process.env,
+    detached: false,
+  });
+
+  return child;
+}
+
+// ─── T009: Server Ready Detection ─────────────────────────────
+function waitForReady(child, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error('READY_TIMEOUT'));
+    }, timeoutMs);
+
+    // Collect stdout to detect ready signal
+    let output = '';
+    const origWrite = process.stdout.write.bind(process.stdout);
+
+    // We use stdio:'inherit' so we can't intercept stdout directly.
+    // Instead, we wait briefly and assume success if the process is still running.
+    setTimeout(() => {
+      clearTimeout(timer);
+      if (!child.killed && child.exitCode === null) {
+        resolve(true);
+      } else {
+        reject(new Error('SERVER_EXIT'));
+      }
+    }, 2000); // Flask starts quickly; 2s is enough for local launch
+  });
+}
+
+// ─── T016 + T017 + T018: Graceful Shutdown ───────────────────
+function setupShutdownHandlers(child) {
+  let shuttingDown = false;
+
+  function shutdown(signal) {
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    console.log(`\n${signal} received, shutting down...`);
+
+    if (child && !child.killed && child.exitCode === null) {
+      // Send SIGTERM (or equivalent on Windows)
+      try {
+        process.kill(child.pid, process.platform === 'win32' ? undefined : 'SIGTERM');
+      } catch (_) {
+        // Process may have already exited
+      }
+
+      // Force kill after timeout
+      setTimeout(() => {
+        if (!child.killed) {
+          try { child.kill('SIGKILL'); } catch (_) {}
+        }
+        process.exit(0);
+      }, SHUTDOWN_TIMEOUT_MS);
+    } else {
+      process.exit(0);
+    }
+  }
+
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+}
+
+// ─── T011: Main Flow Assembly ─────────────────────────────────
+async function main() {
+  const opts = parseArgs(process.argv);
+
+  if (opts.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (opts.version) {
+    console.log(`VisualKnowledge v${PKG_VERSION}`);
+    process.exit(0);
+  }
+
+  // Banner
+  banner();
+
+  // Environment checks (T003-T005)
+  checkNodeVersion();
+  const pythonCmd = await checkPython();
+  await checkDeps(pythonCmd);
+
+  // Port detection (T007 + T013 + T014)
+  let actualPort;
+  try {
+    actualPort = await findAvailablePort(opts.port, MAX_PORT_RETRIES);
+    console.log(`${OK} Port ${actualPort} available`);
+  } catch (err) {
+    if (err.message === 'NO_PORTS') {
+      console.log(`\n${FAIL} No available port in range ${opts.port}-${opts.port + MAX_PORT_RETRIES - 1}\n`);
+      console.log('  Fix: Stop other services using these ports,\n'
+        + '       or use --port to specify a different start port.\n');
+      process.exit(2); // Exit code 2 per contract
+    }
+    throw err;
+  }
+
+  // Start Python server (T008)
+  console.log('\n  Starting server...');
+  const child = startServer(pythonCmd, actualPort);
+
+  // Setup graceful shutdown (T016-T018)
+  setupShutdownHandlers(child);
+
+  // Wait for server ready (T009)
+  try {
+    await waitForReady(child, READY_TIMEOUT_MS);
+  } catch (err) {
+    if (err.message === 'READY_TIMEOUT') {
+      console.log(`${FAIL} Server failed to start within ${READY_TIMEOUT_MS / 1000}s`);
+      process.exit(1);
+    }
+    if (err.message === 'SERVER_EXIT') {
+      console.log(`${FAIL} Server exited unexpectedly`);
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  // Build URL with actual port (T015)
+  const url = `http://localhost:${actualPort}`;
+
+  // Open browser unless --no-open (T010 + E1 fix)
+  if (!opts.noOpen) {
+    openBrowser(url);
+  }
+
+  // Output access address
+  console.log(`\n  → ${url}\n`);
+
+  // Keep process alive — Python child runs via inherit stdio
+  child.on('exit', (code) => {
+    if (code !== 0 && code !== null) {
+      console.log(`${WARN} Server exited with code ${code}`);
+    }
+    process.exit(code || 0);
+  });
+}
+
+// Run
+main().catch((err) => {
+  console.error(`${FAIL} Unexpected error: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1 @@
+{"name": "visualknowledge", "version": "0.1.0", "description": "Interactive AI Chat with Visualization - one-click launch via npx", "bin": {"visualknowledge": "./bin/visualknowledge.js"}, "files": ["bin/", "index.html", "server.py", "skills/"], "keywords": ["ai", "chat", "visualization", "claude", "mermaid"], "license": "MIT", "engines": {"node": ">=16"}, "repository": {"type": "git", "url": "https://github.com/user/VisualKnowledge"}}

package/server.py

@@ -0,0 +1,145 @@
+import json
+import os
+import sys
+import logging
+from flask import Flask, request, Response, jsonify, send_from_directory
+from anthropic import Anthropic
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'skills'))
+from visualize import get_skill_prompt
+
+# 配置日志
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s [%(levelname)s] %(name)s: %(message)s'
+)
+logger = logging.getLogger('server')
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+app = Flask(__name__, static_folder=os.path.join(BASE_DIR, 'static'))
+
+API_BASE_URL = os.environ.get(
+    'ANTHROPIC_BASE_URL', 'https://open.bigmodel.cn/api/anthropic'
+)
+API_KEY = os.environ.get(
+    'ANTHROPIC_AUTH_TOKEN',
+    os.environ.get('ANTHROPIC_API_KEY', '')
+)
+MODEL = os.environ.get('ANTHROPIC_MODEL', 'GLM-5V-Turbo')
+
+SKILL_PROMPT = get_skill_prompt()
+
+SYSTEM_PROMPT = f"""你是一个优秀的AI助手，擅长用直观的可视化方式解释复杂概念。
+
+{SKILL_PROMPT}
+
+### Mermaid 图表（简单关系图使用）
+
+对于简单的关系图、时序图、饼图等，可以使用 ```mermaid 代码块。
+
+```mermaid
+graph TD
+    A[输入] --> B[处理]
+    B --> C[输出]
+```
+
+### 回答风格
+- 先用简洁语言解释核心概念
+- **涉及架构、流程、数据变换、神经网络结构、算法步骤等，必须优先使用 ```html 可视化**
+- 简单的关系图可以用 ```mermaid
+- 代码块前后可以有文字说明
+- 最后给出总结要点"""
+
+
+@app.route('/')
+def index():
+    resp = send_from_directory(os.path.join(BASE_DIR, 'frontend'), 'index.html')
+    resp.headers['Cache-Control'] = 'no-cache, no-store, must-revalidate'
+    resp.headers['Pragma'] = 'no-cache'
+    resp.headers['Expires'] = '0'
+    return resp
+
+
+@app.route('/api/models', methods=['GET'])
+def get_models():
+    models = {
+        'current': MODEL,
+        'available': [
+            MODEL,
+            os.environ.get('ANTHROPIC_DEFAULT_HAIKU_MODEL', 'GLM-4.5-air'),
+            os.environ.get('ANTHROPIC_DEFAULT_OPUS_MODEL', 'GLM-5.1'),
+        ]
+    }
+    return jsonify(models)
+
+
+@app.route('/api/chat', methods=['POST'])
+def chat():
+    data = request.json or {}
+    messages = data.get('messages', [])
+    model = data.get('model', MODEL)
+
+    if not messages:
+        return jsonify({'error': 'No messages provided'}), 400
+
+    if not API_KEY:
+        logger.error("API key is not configured")
+        return jsonify({'error': 'API key is not configured'}), 500
+
+    client = Anthropic(api_key=API_KEY, base_url=API_BASE_URL)
+
+    def generate():
+        full_response = ""
+        try:
+            with client.messages.stream(
+                model=model,
+                max_tokens=8000,
+                system=SYSTEM_PROMPT,
+                messages=messages,
+            ) as stream:
+                for event in stream:
+                    if event.type == 'content_block_delta':
+                        if hasattr(event.delta, 'text'):
+                            delta_text = event.delta.text
+                            full_response += delta_text
+                            payload = json.dumps(
+                                {'type': 'text', 'content': delta_text},
+                                ensure_ascii=False
+                            )
+                            yield f"data: {payload}\n\n"
+
+            logger.info(f"Full response length: {len(full_response)} chars")
+
+        except Exception as e:
+            import traceback
+            logger.error(f"Chat error: {e}\n{traceback.format_exc()}")
+            payload = json.dumps(
+                {'type': 'error', 'message': str(e)},
+                ensure_ascii=False
+            )
+            yield f"data: {payload}\n\n"
+
+        yield "data: [DONE]\n\n"
+
+    resp = Response(generate(), mimetype='text/event-stream')
+    resp.headers['Cache-Control'] = 'no-cache'
+    resp.headers['X-Accel-Buffering'] = 'no'
+    resp.headers['Connection'] = 'keep-alive'
+    return resp
+
+
+if __name__ == '__main__':
+    import sys
+    import io
+    import argparse
+
+    parser = argparse.ArgumentParser(description='VisualKnowledge Server')
+    parser.add_argument('--port', type=int, default=5000, help='Port to listen on (default: 5000)')
+    args = parser.parse_args()
+
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+    print(f"🚀 Claude Chat 启动中...")
+    print(f"   API: {API_BASE_URL}")
+    print(f"   模型: {MODEL}")
+    print(f"   地址: http://localhost:{args.port}")
+    app.run(host='0.0.0.0', port=args.port, debug=True)

package/skills/visualize.py

@@ -0,0 +1,161 @@
+SKILLS = {
+    "transformer_architecture": {
+        "name": "Transformer 架构图",
+        "trigger": ["transformer", "注意力机制", "attention", "encoder-decoder", "自注意力", "self-attention"],
+        "description": "展示 Transformer 完整架构的数据流"
+    },
+    "neural_network_flow": {
+        "name": "神经网络流程图",
+        "trigger": ["神经网络", "前向传播", "反向传播", "cnn", "卷积", "池化", "全连接"],
+        "description": "展示神经网络各层数据处理流程"
+    },
+    "attention_detail": {
+        "name": "注意力机制详解",
+        "trigger": ["qkv", "query key value", "注意力计算", "注意力权重", "softmax"],
+        "description": "详细展示 Q/K/V 计算过程"
+    },
+    "generic_pipeline": {
+        "name": "通用流程图",
+        "trigger": ["流程", "步骤", "过程", "pipeline", "workflow"],
+        "description": "通用多步骤流程图"
+    }
+}
+
+
+def get_skill_prompt():
+    return """## 可视化 Skill 系统
+
+系统支持三种可视化：```html（优先）、```mermaid、```svg。所有复杂可视化必须优先用 HTML。SVG 仅在特殊需要时使用。
+
+### HTML 可视化规范（最重要！）
+
+#### 1. 布局规则
+- **只用 Flexbox 和 Grid，绝对不要用 position:absolute 或手算坐标**
+- 水平排列：`display:flex; align-items:center; gap:16px; flex-wrap:wrap`
+- 垂直排列：`display:flex; flex-direction:column; gap:12px`
+- 居中：`justify-content:center`
+- 禁止：position:absolute、硬编码像素坐标、负 margin
+
+#### 2. 整体结构
+```html
+<div style="max-width:860px;margin:0 auto;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif">
+  <h2 style="text-align:center;font-size:18px;margin-bottom:20px;color:inherit">标题</h2>
+  <!-- 水平行 -->
+  <div style="display:flex;align-items:center;justify-content:center;gap:16px;flex-wrap:wrap">
+    <div class="block">模块A</div>
+    <span style="color:inherit;opacity:0.3">→</span>
+    <div class="block">模块B</div>
+  </div>
+</div>
+```
+
+#### 3. 方块样式（用 CSS class）
+```css
+.block{
+  border-radius:10px; padding:12px 18px; text-align:center;
+  border:1.5px solid; min-width:120px;
+  transition:all .2s; cursor:pointer;
+}
+.block:hover{ filter:brightness(1.15); transform:translateY(-1px); }
+.block .title{ font-size:13px; font-weight:700; }
+.block .dim{ font-size:10px; opacity:0.4; margin-top:4px; font-family:monospace; }
+```
+
+#### 4. 配色（低透明度填充 + 主色边框）
+| 用途 | 主色 | 用法 |
+|------|------|------|
+| 强调/输入/输出 | #d97706 | fill:#d9770612; border:#d97706 |
+| 注意力/计算 | #2563eb | fill:#2563eb12; border:#2563eb |
+| 归一化/残差 | #16a34a | fill:#16a34a12; border:#16a34a |
+| FFN/Value | #7c3aed | fill:#7c3aed12; border:#7c3aed |
+| Query/Wo | #e11d48 | fill:#e11d4812; border:#e11d48 |
+| Key | #0d9488 | fill:#0d948812; border:#0d9488 |
+| 辅助/通用 | #475569 | fill:#47556912; border:#475569 |
+
+#### 5. 箭头和连线
+- 水平箭头用文字 `→` 或 `⟶`（opacity:0.3），不要画 SVG 线条
+- 垂直箭头用 `↓` 或 `⬇`，放在 flex-column 的 gap 中
+- 简单直接，不要复杂化
+
+#### 6. 主题适配
+- 背景色用 `transparent`（跟随页面主题）
+- 文字颜色用 `color:inherit`（自动适配深浅色）
+- 方块填充用低透明度（`#d9770612` 即 hex+alpha），深浅色都好看
+
+#### 7. 交互
+- `.block:hover` 加 `filter:brightness(1.15)` 和 `transform:translateY(-1px)` 微动画
+- 可选：点击展开详情（用 `<details><summary>` 原生 HTML）
+
+### 高质量 HTML 示例（Transformer 数据流）
+
+```html
+<div style="max-width:860px;margin:0 auto;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;color:inherit;background:transparent">
+<style>
+.b{border-radius:10px;padding:12px 18px;text-align:center;border:1.5px solid;min-width:120px;transition:all .2s;cursor:pointer}
+.b:hover{filter:brightness(1.15);transform:translateY(-1px)}
+.b .t{font-size:13px;font-weight:700}
+.b .d{font-size:10px;opacity:.4;margin-top:4px;font-family:monospace}
+.row{display:flex;align-items:center;justify-content:center;gap:14px;flex-wrap:wrap;margin-bottom:16px}
+.col{display:flex;flex-direction:column;align-items:center;gap:8px;margin-bottom:16px}
+.arrow{font-size:18px;opacity:.25;color:inherit}
+.sec{font-size:11px;opacity:.4;font-weight:600;margin-bottom:6px;text-align:center}
+.c-amber{background:#d9770612;border-color:#d97706}
+.c-blue{background:#2563eb12;border-color:#2563eb}
+.c-green{background:#16a34a12;border-color:#16a34a}
+.c-purple{background:#7c3aed12;border-color:#7c3aed}
+.c-rose{background:#e11d4812;border-color:#e11d48}
+.c-teal{background:#0d948812;border-color:#0d9488}
+.c-slate{background:#47556912;border-color:#475569}
+.c-orange{background:#ea580c12;border-color:#ea580c}
+</style>
+
+<h2 style="text-align:center;font-size:18px;margin-bottom:20px">Transformer 架构 — 数据流</h2>
+
+<div class="sec">输入处理</div>
+<div class="row">
+  <div class="b c-slate"><div class="t">输入序列</div><div class="d">"我 喜欢 AI"</div></div>
+  <span class="arrow">→</span>
+  <div class="b c-amber"><div class="t">Token Embedding</div><div class="d">词→向量 512维</div></div>
+  <span class="arrow">→</span>
+  <div class="b c-orange"><div class="t">位置编码</div><div class="d">sin/cos</div></div>
+  <span class="arrow">→</span>
+  <div class="b c-amber" style="border-style:dashed"><div class="t">输入表示</div></div>
+</div>
+
+<span class="arrow">↓</span>
+
+<div class="sec">编码器 × N 层</div>
+<div class="col">
+  <div class="b c-blue" style="min-width:340px"><div class="t">多头自注意力</div><div class="d">Q·Kᵀ/√d → softmax → ·V</div></div>
+  <span class="arrow">↓</span>
+  <div class="b c-green" style="min-width:340px"><div class="t">Add & LayerNorm</div><div class="d">残差连接 + 层归一化</div></div>
+  <span class="arrow">↓</span>
+  <div class="b c-purple" style="min-width:340px"><div class="t">前馈网络 FFN</div><div class="d">512 → 2048 → 512</div></div>
+  <span class="arrow">↓</span>
+  <div class="b c-green" style="min-width:340px"><div class="t">Add & LayerNorm</div></div>
+</div>
+
+<span class="arrow">↓</span>
+
+<div class="sec">输出</div>
+<div class="row">
+  <div class="b c-slate"><div class="t">Linear</div><div class="d">512 → vocab</div></div>
+  <span class="arrow">→</span>
+  <div class="b c-amber"><div class="t">Softmax</div></div>
+  <span class="arrow">→</span>
+  <div class="b c-rose"><div class="t">预测输出</div></div>
+</div>
+</div>
+```
+
+### 可用的 Skill 类型
+- **Transformer 架构图** (transformer_architecture): transformer, attention, 自注意力
+- **神经网络流程图** (neural_network_flow): 神经网络, CNN, 卷积, 池化
+- **注意力机制详解** (attention_detail): QKV, 注意力权重, softmax
+- **通用流程图** (generic_pipeline): 流程, 步骤, pipeline
+
+### 使用规则
+1. 涉及架构/流程/数据变换/神经网络结构/算法步骤 → **必须用 ```html**
+2. 简单关系图/时序图/饼图 → 用 ```mermaid
+3. 每个可视化要包含维度信息和简要说明，文字全部中文
+4. **布局口诀：flex 排列不手算，方块用 class 样式，箭头用文字符号，颜色低透明度**"""