1. 项目概述：当 Agent 不再“硬写”，可视化生成如何真正落地
最近在几个技术社区里刷到不少开发者吐槽：“写了个 Agent，逻辑跑得飞快，一到输出 HTML 就卡住——不是标签闭合错，就是 SVG 坐标算偏了，ThreeJS 场景初始化失败三次，最后干脆 return '请稍候' 敷衍了事。”这背后不是能力问题，而是开发范式没跟上。标题里那句“别再让 AI 硬写”，说的正是当前 Agent 开发中最隐蔽、最消耗精力的断层：语义理解与结构化呈现之间的鸿沟。你让 Agent 想清楚“用户要一个可旋转的地球仪，带城市光点和昼夜分界线”，它能调用工具、查经纬度、算太阳角度；但让它直接拼出<canvas>初始化代码、ThreeJS 的OrbitControls配置、SVG 中<g transform="rotate(...)的嵌套层级？这就不是推理问题，是结构约束建模缺失的问题。
我过去两年带过 7 个跨行业 Agent 项目，从工业设备状态看板到儿童编程教学助手，凡是最终交付质量高、迭代速度快的，无一例外都绕开了“让 LLM 直接生成完整 HTML/JS”的老路。他们用的不是更贵的模型，而是把“可视化生成”拆解成三层：意图解析层 → 结构模板层 → 渲染执行层。比如用户说“画一只骑自行车的鹈鹕”，Agent 不会去生成 200 行 SVG path 数据，而是识别出“主体（鹈鹕）+ 动作（骑行）+ 载具（自行车）+ 风格（简笔/拟真）”，然后从预置的 SVG 组件库中组合<g id="pelican">和<g id="bicycle">，再通过 CSS transform 或 SVG animate 控制相对运动。这种做法实测下来，HTML 生成准确率从 63% 提升到 98%，ThreeJS 场景首次加载成功率从 41% 提升到 94%，最关键的是——调试时间下降 70%。这篇文章不讲大道理，只分享我们团队已在线上稳定运行 11 个月的可视化生成方案，包含完整的架构图、5 类典型场景的实现细节、3 个避坑极深的实操心得，以及一套可直接复用的轻量级模板引擎。无论你是刚接触 Agent 的前端工程师，还是正在搭建企业级智能体平台的架构师，只要你的 Agent 需要向用户展示图形、图表、3D 模型或交互界面，这篇内容就值得你花 22 分钟读完并动手试一遍。
2. 核心设计思路：为什么放弃“LLM 直出 HTML”，转向结构化生成
2.1 “硬写 HTML”的三大不可解困局
很多团队最初都尝试过让大模型直接输出 HTML 片段，理由很朴素：“它连论文都能写，写个网页有啥难？”但实际跑起来，很快就会撞上三堵墙，而且每堵墙都很难靠调高 temperature 或换更强模型来突破。
第一堵墙是结构完整性失控。HTML 不是纯文本，它是一棵严格的 DOM 树。LLM 在 token 级别生成时，无法保证<div>和</div>的嵌套深度完全匹配。我们曾用 GPT-4-turbo 处理一个含 4 层嵌套的仪表盘需求，生成结果中 62% 的 case 存在标签错位——最典型的是<svg>标签被截断在中间，浏览器解析直接报错。这不是模型能力问题，而是其自回归生成机制与树形结构约束的根本冲突：模型每次只预测下一个 token，而 DOM 的合法性需要全局上下文验证。
第二堵墙是渲染上下文缺失。ThreeJS 场景初始化依赖 WebGL 上下文、相机参数、光照设置、材质加载状态等十余个强耦合变量。让 LLM 在 prompt 里记住“renderer.setSize(window.innerWidth, window.innerHeight)必须在window.addEventListener('resize', ...)之前调用”，就像让一个人边背圆周率边骑独轮车——理论上可行，实践中必然翻车。我们做过对照实验：对同一 3D 模型加载需求，LLM 直出 JS 的平均调试次数是 8.7 次；而采用结构化生成后，平均只需 1.2 次（主要是路径配置错误）。
第三堵墙是安全与可控性真空。直接执行 LLM 生成的<script>标签？等于给未知代码开了白名单。哪怕加了 CSP 策略，也无法阻止它注入fetch('/api/user?token='+document.cookie)这类隐蔽请求。更现实的风险是：某次模型更新后，它开始习惯性在 SVG 中添加<foreignObject>标签嵌入 HTML，而你的目标浏览器（如某些国产政企定制版）根本不支持该特性，导致整个图表白屏。这种风险无法通过 prompt 工程规避，只能靠架构层面的沙箱隔离。
提示：不要试图用“让模型自我校验 HTML 合法性”来解决。我们测试过让 LLM 先生成 HTML，再用另一个调用检查闭合标签——结果发现，校验模型自己也会犯错，且两次调用间存在 230ms 平均延迟，对实时交互场景不可接受。
2.2 结构化生成的三层架构：意图 → 模板 → 渲染
我们最终落地的方案，核心是把“生成可视化内容”这个黑盒，拆解为三个职责清晰、可独立演进的模块：
意图解析层（Intent Parser）：接收用户自然语言指令，输出标准化的结构化描述。例如“把销售额按季度画成 3D 柱状图，柱子高度代表金额，颜色深浅代表同比增长率”，会被解析为：
{ "type": "3d_bar_chart", "data": {"source": "sales_q1_q4", "x_axis": "quarter", "y_axis": "amount"}, "style": {"height_mapping": "y", "color_mapping": "growth_rate"}, "interaction": ["rotate", "zoom"] }这层不碰任何 HTML/JS，只做语义归一化。我们用微调后的 Qwen2-1.5B 完成此任务，准确率 92.3%，比通用大模型高 17 个百分点，因为训练数据全部来自内部 2000+ 条真实业务指令。
模板编译层（Template Compiler）：将结构化描述映射到预定义的可视化模板。每个模板是一个 JSON Schema + Handlebars 模板的组合。以 SVG 柱状图为例，模板文件
bar_chart_svg.json定义了：- 输入 schema：必须包含
data,width,height,bar_gap字段； - 渲染逻辑：用 Handlebars 循环生成
<rect>，自动计算 y 坐标（{{height}} - {{value}} * {{scale}}），并绑定:hoverCSS 类； - 安全边界：禁止任何
{{#if}}嵌套超过 2 层，禁用{{@root}}访问全局变量。
- 输入 schema：必须包含
渲染执行层（Renderer Executor）：在严格沙箱中执行编译后的模板，输出纯净 HTML/JS。我们用 Web Worker +
DOMPurify实现：Worker 加载模板引擎，DOMPurify 过滤所有onerror、javascript:等危险属性，最终只返回<svg>或<div id="threejs-container">这类安全节点。整个过程耗时稳定在 45±8ms，比直出方案快 3.2 倍。
这套架构的关键优势在于：每一层都可单独替换、灰度发布、AB 测试。上周我们把意图解析层从 Qwen2 换成 DeepSeek-V3，只改了 3 行 API 调用代码，其他两层完全无感；而如果当初是直出 HTML，换模型意味着要重写全部 prompt 和后处理逻辑。
2.3 为什么选 HTML/SVG/ThreeJS 作为输出靶点
看到热搜词里反复出现 HTML、SVG、ThreeJS，可能有人会问：为什么不统一用 Canvas 或 WebGL 自研渲染器？答案很实在：生态成本与交付效率的平衡点。
HTML 是事实标准，无需额外 runtime。一个<div class="chart">可以被任何现代框架（React/Vue/Svelte）无缝集成，CSS 可以直接覆盖样式，开发者零学习成本。我们服务的某银行客户，其前端团队明确要求“所有 Agent 输出必须是原生 HTML 片段”，因为他们的微前端架构禁止动态加载外部 JS。
SVG 则是矢量图形的黄金分割线。它天生支持 CSS 动画、无障碍访问（<title>和aria-label）、缩放不失真，且文件体积小。对比 Canvas：画 100 个图标，SVG 用 10KB 代码搞定，Canvas 需要 300 行 JS + 图片资源；对比 PNG：SVG 可以用 CSSfilter: drop-shadow()实现阴影，而 PNG 需要设计师导出新图。我们统计过，Agent 生成的图表中，78% 是静态或简单交互动效，SVG 完全胜任。
ThreeJS 的选择则源于它的“抽象水位”恰到好处。它封装了 WebGL 的复杂性（着色器编译、缓冲区管理），又保留了足够控制力（可直接操作Mesh、Material）。更重要的是，它有海量成熟插件：OrbitControls处理旋转缩放，GLTFLoader加载 3D 模型，CSS2DRenderer叠加 HTML 标签。我们不需要 Agent 去写gl.drawElements()，只要告诉它“加载 model.glb，启用阴影，添加环境光”，ThreeJS 就能完成剩下 90% 的工作。
注意：不要迷信“最新技术”。我们曾评估过 WebGPU，虽然性能提升明显，但目前 Chrome 支持率仅 82%，且调试工具链不成熟。对业务系统而言，稳定压倒一切。
3. 核心实现细节：从零搭建可视化生成流水线
3.1 意图解析层：如何让 Agent 看懂“画一只骑自行车的鹈鹕”
意图解析不是简单的关键词提取，而是构建领域语义图谱。以 SVG 生成为例，我们定义了三类核心实体：
- 主体（Subject）：可独立存在的视觉元素，如
pelican、bicycle、earth。每个主体关联一组 SVG 路径数据（存于assets/svg/subjects/目录），并标注关键锚点（head_center、wheel_center等）。 - 关系（Relation）：描述主体间空间或动作关系，如
riding_on、standing_on、flying_above。每种关系对应预设的 SVG 变换规则，例如riding_on会自动计算bicycle的transform="translate(x,y)"，使pelican的wheel_center与bicycle的wheel_center对齐。 - 修饰（Modifier）：影响视觉表现的属性，如
cartoon_style、realistic_shading、monochrome。它们不改变结构，只触发 CSS 类或 SVG filter 应用。
解析流程分四步：
实体识别：用 spaCy 的中文 NER 模型识别名词短语，结合自建同义词库（如“鹈鹕”→“bird”、“火烈鸟”→“flamingo”）归一化。对“骑自行车”这类动宾结构，用依存句法分析提取
riding（谓词）和bicycle（宾语）。关系抽取：基于规则 + 小模型。规则处理高频模式（如“X 在 Y 上”→
standing_on），小模型（微调的 TinyBERT）处理模糊表达（如“鹈鹕和自行车一起出现”→next_to）。结构组装：将识别出的实体、关系、修饰组合成 AST（抽象语法树）。例如“卡通风格的鹈鹕骑在红色自行车上”生成：
{ "subject": {"id": "pelican", "modifier": "cartoon_style"}, "relation": {"type": "riding_on", "target": "bicycle"}, "target": {"id": "bicycle", "modifier": "red_color"} }Schema 校验：用 JSON Schema 验证 AST 是否符合预定义结构。若缺少必要字段（如
target），触发追问：“请问自行车是什么颜色的？”
这套流程在内部测试集上达到 89.6% 的 F1 值。最关键的技巧是：永远不假设用户指令完整。我们强制 Agent 在解析后生成一句自然语言确认，如“我将为您生成一只卡通风格的鹈鹕，它正骑在一辆红色自行车上，对吗？”。这看似多一步，却避免了 63% 的返工——因为用户常会说“等等，自行车应该是蓝色的”。
3.2 模板编译层：Handlebars + JSON Schema 的安全组合
模板不是写死的 HTML 字符串，而是带约束的可编程组件。以 ThreeJS 地球仪模板为例，其核心文件globe_3js.hbs结构如下：
<div id="{{container_id}}" style="width:{{width}}px;height:{{height}}px;"></div> <script type="module"> import * as THREE from 'https://cdn.jsdelivr.net/npm/three@0.160.1/examples/jsm/Three.module.js'; import { OrbitControls } from 'https://cdn.jsdelivr.net/npm/three@0.160.1/examples/jsm/controls/OrbitControls.js'; import { GLTFLoader } from 'https://cdn.jsdelivr.net/npm/three@0.160.1/examples/jsm/loaders/GLTFLoader.js'; const scene = new THREE.Scene(); scene.background = new THREE.Color({{background_color}}); // ... 初始化代码省略 // 关键：所有动态值都来自 JSON Schema 校验后的输入 const loader = new GLTFLoader(); loader.load('{{model_url}}', (gltf) => { scene.add(gltf.scene); // 自动添加昼夜分界线 {{#if show_day_night_line}} const lineGeometry = new THREE.BufferGeometry().setFromPoints([ new THREE.Vector3(0, 0, 0), new THREE.Vector3({{sun_x}}, {{sun_y}}, {{sun_z}}) ]); // ... {{/if}} }); </script>配套的globe_3js.schema.json定义了严格约束：
{ "type": "object", "required": ["container_id", "width", "height", "model_url"], "properties": { "container_id": {"type": "string", "pattern": "^[a-z][a-z0-9_]{2,20}$"}, "width": {"type": "integer", "minimum": 300, "maximum": 2000}, "height": {"type": "integer", "minimum": 200, "maximum": 1500}, "model_url": {"type": "string", "format": "uri"}, "show_day_night_line": {"type": "boolean"}, "sun_x": {"type": "number", "multipleOf": 0.1}, "background_color": {"type": "string", "pattern": "^#([0-9A-F]{3}){1,2}$"} } }编译时，系统先用 AJV 库校验输入 JSON 是否符合 schema，再传入 Handlebars 渲染。这种设计带来三大收益：
- 安全兜底：
container_id的正则确保不会生成id="';alert(1)//"这类 XSS 注入； - 类型保障：
width必须是整数，避免parseInt("300px")返回 NaN 导致 ThreeJS 报错； - 文档即契约：schema 文件本身就是 API 文档，前端调用方无需阅读 JS 代码就能知道需要传什么。
我们为常用场景建立了 12 个模板库，覆盖 SVG 图表（折线/柱状/饼图）、ThreeJS 场景（地球仪/建筑模型/产品展示）、HTML 组件（进度条/卡片/表格）。每个模板都有单元测试，用 Puppeteer 截图比对渲染结果，确保升级不破环。
3.3 渲染执行层：Web Worker + DOMPurify 的沙箱实践
渲染不是简单地innerHTML = templateResult，而是一套受控的执行环境。我们的 Worker 代码精简到 127 行，核心逻辑只有三步：
- 预加载资源：Worker 启动时，预加载 Handlebars 引擎和 DOMPurify 库（CDN 缓存，首屏耗时 < 20ms）。
- 沙箱执行：调用
new Function('data', 'return' + template + '')执行模板，传入校验后的 data。注意：这里不用eval，因为Function构造函数作用域更干净，且可被 CSP 策略限制。 - 净化输出：用 DOMPurify 的
sanitize()方法过滤结果，配置项如下：const clean = DOMPurify.sanitize(dirty, { ALLOWED_TAGS: ['svg', 'path', 'circle', 'rect', 'text', 'g', 'div', 'canvas'], ALLOWED_ATTR: ['id', 'class', 'fill', 'stroke', 'd', 'cx', 'cy', 'r', 'x', 'y', 'width', 'height', 'viewBox'], FORBID_TAGS: ['script', 'iframe', 'object', 'embed'], FORBID_ATTR: ['onerror', 'onload', 'javascript:', 'data:text/html'] });
这个沙箱的关键设计是：所有 ThreeJS 渲染代码都在 Worker 内部执行，但最终只返回 HTML 字符串，绝不返回THREE.Scene实例或WebGLRenderingContext。这样既保证了渲染逻辑的完整性，又杜绝了内存泄漏和跨域风险。
实测数据显示，Worker 方案比主线程渲染快 40%，因为避免了主线程阻塞。更重要的是，当某个模板存在无限循环（如{{#each items}}{{#each items}}...）时，Worker 会超时终止（我们设了 300ms 硬限制），而主线程卡死会导致整个页面无响应。
3.4 模板库建设：如何积累可复用的可视化资产
模板不是写一次就完事，它需要持续运营。我们的模板库管理遵循“三阶沉淀法”：
第一阶：业务驱动沉淀。每个新需求上线后，PM 必须填写《模板复用评估表》，回答三个问题：1）该可视化是否会在未来 3 个月内被复用？2）其结构是否可参数化（如柱状图的 X/Y 轴字段名）？3）是否有通用交互（hover 提示、点击跳转）？若两个以上为“是”，则进入模板评审流程。
第二阶：原子化拆解。一个“销售看板”模板，会被拆成 5 个原子组件：
header_card.hbs（标题+时间范围）、kpi_metric.hbs（关键指标）、trend_chart.hbs（趋势图）、geo_map.hbs（地理分布）、product_list.hbs（产品列表）。每个原子组件独立测试、独立版本号（如v1.2.0），可被任意组合。第三阶：效果反哺。我们在每个模板中埋点，记录：1）渲染耗时；2）用户 hover/click 热区；3）3 秒内关闭率。数据反馈到设计团队，指导优化。例如，
trend_chart.hbs的初始版本用 SVG<line>画折线，但热力图显示用户 82% 的交互集中在数据点上，于是我们升级为<circle>+<text>显示数值，点击率提升 3.7 倍。
目前模板库已积累 47 个生产级模板，复用率达 68%。新需求平均开发时间从 3.2 人日降至 0.7 人日。最典型的案例是某车企的“电池健康度报告”，原本需 5 天开发，复用gauge_chart.hbs（仪表盘）、battery_3d.hbs（3D 电池模型）、timeline.hbs（时间轴）三个模板，2 天即上线。
4. 实操全流程：以“生成骑自行车的鹈鹕 SVG”为例
4.1 完整调用链路与耗时分解
我们以热搜词中那个魔性的例子“generate an svg of a pelican riding a bicycle”为蓝本，走一遍端到端流程。整个链路共 7 个环节，总耗时 312ms（P95），各环节耗时如下表：
| 环节 | 操作 | 耗时（ms） | 关键说明 |
|---|---|---|---|
| 1. 用户输入 | HTTP POST 到 Agent API | 12 | 网络传输，含 JWT 鉴权 |
| 2. 意图解析 | Qwen2-1.5B 推理 + NER 校验 | 89 | GPU 推理，batch size=1 |
| 3. 模板匹配 | 查找pelican_riding_bicycle.svg模板 | 3 | 内存哈希查找，O(1) |
| 4. 输入校验 | AJV 校验 JSON Schema | 17 | CPU 密集，但数据量小 |
| 5. 模板编译 | Handlebars 渲染 | 41 | Worker 内执行，无 IO |
| 6. 输出净化 | DOMPurify 过滤 | 28 | 配置精简，仅保留 SVG 标签 |
| 7. 响应返回 | HTTP 200 + SVG 字符串 | 12 | Gzip 压缩后仅 2.1KB |
全程无外部网络请求（模板和模型权重均本地缓存），因此稳定性极高。我们监控了线上 30 天数据，P99 耗时 420ms，错误率 0.03%（主要为输入超长触发截断）。
4.2 模板文件详解：pelican_riding_bicycle.svg
这个模板是 SVG 原子化设计的典范。它不包含任何具体鹈鹕或自行车的路径数据，而是引用预置的 SVG 组件：
<svg xmlns="http://www.w3.org/2000/svg" width="{{width}}" height="{{height}}" viewBox="0 0 {{width}} {{height}}"> <!-- 背景 --> <rect width="100%" height="100%" fill="{{background_color}}" /> <!-- 自行车组件：从 assets/svg/components/bicycle.svg 加载 --> <g id="bicycle" transform="translate({{bicycle_x}}, {{bicycle_y}}) scale({{bicycle_scale}})"> {{> components/bicycle}} </g> <!-- 鹈鹕组件：从 assets/svg/components/pelican.svg 加载 --> <g id="pelican" transform="translate({{pelican_x}}, {{pelican_y}}) scale({{pelican_scale}})"> {{> components/pelican}} </g> <!-- 关系绑定：鹈鹕的脚部锚点与自行车踏板对齐 --> <script type="application/ecmascript"><![CDATA[ // 此脚本在浏览器中执行，用于动态调整位置 // 确保 pelican 的 foot_center 与 bicycle 的 pedal_center 重合 const pelican = document.getElementById('pelican'); const bicycle = document.getElementById('bicycle'); const footOffset = {{pelican_foot_offset}}; const pedalOffset = {{bicycle_pedal_offset}}; const dx = pedalOffset.x - footOffset.x; const dy = pedalOffset.y - footOffset.y; pelican.setAttribute('transform', `translate(${dx}, ${dy}) scale(${pelican.getAttribute('scale')})` ); ]]></script> </svg>配套的pelican_riding_bicycle.schema.json约束了所有动态参数：
{ "type": "object", "required": ["width", "height", "background_color"], "properties": { "width": {"type": "integer", "minimum": 200, "maximum": 1200}, "height": {"type": "integer", "minimum": 150, "maximum": 800}, "background_color": {"type": "string", "pattern": "^#([0-9A-F]{3}){1,2}$"}, "bicycle_x": {"type": "number", "multipleOf": 0.1}, "bicycle_y": {"type": "number", "multipleOf": 0.1}, "bicycle_scale": {"type": "number", "minimum": 0.5, "maximum": 2.0}, "pelican_x": {"type": "number", "multipleOf": 0.1}, "pelican_y": {"type": "number", "multipleOf": 0.1}, "pelican_scale": {"type": "number", "minimum": 0.5, "maximum": 2.0}, "pelican_foot_offset": {"type": "object", "properties": {"x": {"type": "number"}, "y": {"type": "number"}}}, "bicycle_pedal_offset": {"type": "object", "properties": {"x": {"type": "number"}, "y": {"type": "number"}}} } }这个设计的精妙之处在于：SVG 的静态部分（路径）与动态部分（位置、缩放）完全分离。设计师可以专注优化components/pelican.svg的美术效果，而工程师只需调整pelican_x/y参数即可改变构图，双方零耦合。
4.3 前端集成：如何在 React/Vue 项目中调用
生成的 SVG 不是孤立的字符串，而是可直接挂载的 DOM 节点。以下是在主流框架中的集成方式：
React 示例（使用 useEffect）：
function PelicanChart() { const [svgContent, setSvgContent] = useState<string>(''); useEffect(() => { // 调用 Agent 可视化 API fetch('/api/v1/visualize', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ "template": "pelican_riding_bicycle", "input": { "width": 600, "height": 400, "background_color": "#f0f8ff", "bicycle_x": 200, "bicycle_y": 250, "pelican_x": 180, "pelican_y": 180, "pelican_scale": 1.2 } }) }) .then(res => res.text()) .then(svg => setSvgContent(svg)) .catch(err => console.error('Render failed:', err)); }, []); // 使用 dangerouslySetInnerHTML，但内容已由 DOMPurify 净化 return <div className="chart-container" dangerouslySetInnerHTML={{ __html: svgContent }} />; }Vue 示例（使用 v-html）：
<template> <div class="chart-container" v-html="svgContent"></div> </template> <script setup> import { ref, onMounted } from 'vue'; const svgContent = ref(''); onMounted(() => { fetch('/api/v1/visualize', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ "template": "pelican_riding_bicycle", "input": { "width": 600, "height": 400, "background_color": "#f0f8ff" } }) }) .then(res => res.text()) .then(svg => svgContent.value = svg) .catch(err => console.error('Render failed:', err)); }); </script>关键注意事项：
- 永远不要用
innerHTML直接赋值未净化的内容。即使你信任自己的 Agent，也要防住上游数据污染（如用户上传的 CSV 中含恶意字段）。 - 设置容器宽高。SVG 的
viewBox是比例尺，实际显示大小由父容器width/height决定。我们强制要求模板输入中指定width/height，并在 CSS 中设.chart-container { width: 100%; height: 400px; }。 - 处理加载状态。我们建议在
svgContent为空时显示骨架屏（skeleton），而非空白。实测用户耐心阈值是 300ms，超过则感知卡顿。
4.4 性能优化实战：从 312ms 到 189ms 的关键改进
上线初期，P95 耗时是 312ms，用户反馈“有轻微卡顿”。我们通过火焰图定位到三个瓶颈，并针对性优化：
瓶颈1：意图解析的 GPU 显存拷贝。Qwen2 模型输出 logits 后，需将 token IDs 拷贝回 CPU 再解码。我们改用
transformers的streamer接口，边推理边流式解码，节省 42ms。瓶颈2：Handlebars 模板重复编译。每次请求都调用
Handlebars.compile(template)，而模板文件不变。我们改为启动时预编译所有模板到内存 Map 中，键为模板名，值为编译后的函数，节省 37ms。瓶颈3：DOMPurify 的冗余配置。默认配置允许
style属性，但我们的 SVG 模板从不生成内联样式，禁用后节省 29ms。
优化后 P95 降至 189ms，用户调研显示“流畅感显著提升”。更关键的是，这些优化全部在服务端完成，前端无需任何改动——这就是分层架构的价值：性能问题在对应层解决，不污染上下游。
5. 常见问题与独家排查技巧
5.1 典型问题速查表
| 问题现象 | 可能原因 | 排查步骤 | 解决方案 |
|---|---|---|---|
| SVG 渲染后空白 | 1）viewBox与width/height不匹配2）DOMPurify 过滤了必要属性（如 fill）3）模板中引用了不存在的组件 | 1）检查返回的 SVG 字符串，确认viewBox="0 0 W H"中 W/H 与width/height一致2）在 Worker 中临时关闭 DOMPurify，查看原始输出 3） ls assets/svg/components/确认文件存在 | 1）统一用width/height计算viewBox2）在 ALLOWED_ATTR中添加缺失属性3）模板中用 {{#if (file-exists "components/bicycle.svg")}}做存在性检查 |
| ThreeJS 场景黑屏 | 1）renderer.setSize()未在window.resize事件中调用2）模型 URL 404 或 CORS 错误 3） GLTFLoader版本与模型不兼容 | 1）在模板中搜索setSize，确认有window.addEventListener('resize', ...)2）用浏览器 DevTools 的 Network 标签页检查模型请求 3）用 glTF Validator 检查模型 | 1）模板中强制包含 resize 监听器 2）在模板编译前校验 model_url可访问性（HEAD 请求）3）模板中指定 GLTFLoader版本，如https://cdn.jsdelivr.net/npm/three@0.160.1/examples/jsm/loaders/GLTFLoader.js |
| 文字乱码（如“鹈鹕”显示为方块） | 1）SVG 中未声明字体族 2）浏览器未安装对应中文字体 3） <text>标签未设置font-family | 1）检查 SVG 中<text>是否有font-family="sans-serif"2）在模板中添加 <style>text { font-family: "PingFang SC","Microsoft YaHei",sans-serif; }</style> | 1）所有模板强制内联基础 CSS 2）用 @font-face加载 WebFont（需 CDN 支持） |
| 交互失效（hover/click 无反应） | 1）pointer-events: none覆盖了 SVG 元素2）事件监听器绑定在错误的父节点 3） z-index层级被遮挡 | 1）用 DevTools 检查元素 computed styles 2）确认事件监听器在 document.getElementById('container')上绑定3）检查父容器是否有 overflow: hidden | 1）模板中为可交互元素显式设置pointer-events: auto2）在模板末尾添加标准事件绑定脚本： <script>document.getElementById('{{container_id}}').addEventListener('click', ...)</script> |
5.2 三个血泪教训：那些文档里不会写的坑
教训一：不要在 SVG 模板中用<use>引用外部符号（<symbol>）
初版pelican_riding_bicycle.svg为了复用，把鹈鹕路径定义在<defs>中的<symbol id="pelican">，再用<use href="#pelican">引用。结果上线后发现：Chrome 正常，Safari 15.6 下href不生效，显示为空白。根本原因是 Safari 对外部href的 CORS 策略更严格。解决方案是彻底放弃<use>，改用<g>包裹路径数据，虽然体积增大 15%，但 100% 兼容。
**教训二：Three
