把 47% 的 SVG 坐标算力从大模型手里拿走:剖析 Answer me with HTML 的单文件引擎、STE100 质检与 WebCodecs 视频管线
让编程 Agent 直接手写一页带架构图的 HTML 来解释复杂技术问题,看起来很美,实际用起来却总是慢得让人抓狂——模型把将近一半的输出 Token 都消耗在了推算 SVG 路径坐标和重复编写 CSS 样式表上,而且画出来的箭头还经常偏到空白处。最近我把 GitHub 上已收获 6,500+ Star 的开源项目 QingYunA/answer-me-with-html(v0.6.2,MIT 协议)完整拉到本地做了一轮源码拆解与实机测试,发现它走了一条非常清醒的工程路线:把“说什么”留给大模型,把“怎么排版、怎么算图、怎么守住安全边界”全部下沉给一个打包好的本地 Node CLI。
在这套架构下,大模型只需要输出一份平均约 612 个 Token 的扩展 Markdown 稿件,剩余的 47% SVG 坐标、15% CSS 与 17% HTML 骨架全部由 1.1 MB 的零依赖单文件引擎 am.mjs 在百毫秒内确定性算出并封装。我在本机 Mac(Node v23.6.0)上实测渲染一份包含 6 个面板、2 张时序图与 1 张 Dagre 拓扑图的示例稿件,从进程冷启动到写出 180 KB 离线单文件 HTML 仅耗时 0.148 秒。更值得细读的,是它隐藏在背后的动态规划“照片墙”排版器、ASD-STE100 中英文受控写作质检、四层零信任安全隔离,以及直接在浏览器里用 WebCodecs 导出 VP9+Opus 视频的确定性渲染引擎。
[!NOTE] 源码审计基线与本机实测说明
本文所有模块路径、数据结构、阈值常量与渲染观测,均对照自开源仓库 QingYunA/answer-me-with-html(tagv0.6.2/ commit997479b,MIT 协议)。仓库核心目录src/共包含125个源码与样式文件、合计21,431行代码,通过scripts/build.mjs打包为skills/answer-me-with-html/scripts/am.mjs(约1.1 MB)随 Skill 分发。我在本机 macOS(Node.js
v23.6.0)的实测记录:未执行npm install直接运行仓库自带的预打包产物node skills/answer-me-with-html/scripts/am.mjs render examples/tcp.md -o /tmp/test-tcp2.html --no-open,冷启动总耗时0.148s,生成180 KB零外部依赖 HTML;运行am.mjs video examples/video-tcp.md --voice off --no-open生成124 KB含 3 个场景、13 个节拍、总长87.3s的可交互视频播放器;若直接运行npm test,未安装node_modules时测试套件会因缺少@dagrejs/dagre等开发依赖而失败,这恰好印证了其生产分发策略——用户终端无需执行npm install,仅凭 Node >= 20 即可零依赖运行打包后的am.mjs。
一、算力卸载与角色切分:为什么只让模型写 21% 的内容?
很多开发者在尝试让 Agent 输出可视化报告(GenUI / HTML Explainer)时,往往习惯在 Prompt 里要求模型“直接生成美观的响应式 HTML 与 SVG”。原作者在 bench/README.md 中对 9 份模型手写 HTML 与 9 份 Markdown 稿件做了精确的 Token 拆解(以 Claude Sonnet 5.5 分词器实测,语料存入 bench/corpus/tokens.json),揭示了直接生成 HTML 的算力浪费真相:
| 产出模块 | 手写 HTML 平均占比 | Answer me with HTML 分工边界 |
|---|---|---|
| SVG 图形坐标与路径 | 47% | 卸载给 @dagrejs/dagre 与自研几何引擎确定性计算 |
| CSS 样式表与主题变量 | 15% | 卸载给 CLI 内置主题系统(blueprint / shadcn / paper) |
| HTML 骨架与容器标签 | 17% | 卸载给 sheet / doc 模板与安全外壳生成器 |
| 核心正文与语义拓扑 | 21% | 保留给大模型:以扩展 Markdown 声明式撰写 |
这种分工带来的不仅是输出 Token 从平均 4,893 降至 612(减少 8 倍),更把整个工具链变成了一条可验证、可局部修补、完全离线运行的编译流水线:
原作者同时非常坦诚地指出了一个容易被忽略的账单细节(bench/README.md):在轻上下文环境(约 2.5 万 Token 上下文)中,使用该 Skill 后输出 Token 从 4,932 降至 1,007(少 4.9x)、耗时从 31s 降至 12s(快 2.6x),但单次总费用仅从 0.091 美元 降至 0.077 美元(省 15%);而在重上下文环境(约 8.6 万 Token 上下文)中费用才从 0.220 美元 降至 0.138 美元(省 37%)。原因在于输出 Token 只占总账单的 55%,而首次载入约 4,000 Token 的 SKILL.md 会增加一次 Prompt Cache 写入开销——只有在多轮会话缓存命中后,以及生成 3b1b 风格解释视频(输出 Token 从 27,839 降至 1,566,少 17.8x,耗时从 202s 降至 17s)时,成本与延时优势才会被彻底放大。
[!TIP]
esbuild延迟加载黑科技:470 KBTemml 的零启动惩罚
我在审计打包脚本scripts/build.mjs时注意到一个极克制的性能细节:项目支持将 LaTeX 数学公式在编译期渲染为无需前端 JS 的 MathML Core,为此引入了470 KB的temml。如果直接把temml打进主包,哪怕只渲染一篇纯文本问答,Node V8 每次冷启动都要编译这470 KB代码。作者在scripts/build.mjs中写了一个名为temml-as-string的自定义 esbuild 插件,把压缩后的temml.min.js作为字符串常量封入包内;运行时只有当src/math.js的mayHaveMath()检测到正文中确实存在成对公式定界符(且排除$5 and $10、$PATH:$HOME等误伤场景)时,才通过node:vm的runInThisContext按需编译求值。这正是 CLI 能做到148 ms冷启动的关键之一。
二、声明式组件矩阵、Dagre 避障自愈与“照片墙”动态规划排版
在 src/components/index.js 中,引擎内置了 14 种语义组件(callout、kv、timeline、annot、tree、limits、chart、sequence、flow、state、er、class、api、ask)以及 html / svg 两种原始逃生通道。大模型不需要关心像素坐标,只需要用接近自然语言的语法声明节点和关系。
1. 不止于 Dagre:后置几何撞车检测与方向试探推荐
很多同类工具直接调用 @dagrejs/dagre 算出坐标就结束了,但 Dagre 经常会把某条长边直接穿过另一个无关节点的方框,或者压在另一条边的标签文字上。我在 src/components/flow-check.js 中看到了一个非常聪明的补救机制 crossingWarnings():
- 提取平滑折线采样点:由于
flow.js渲染时会用smoothPath把直角折弯切成圆角弧线,检测器不是粗暴测 Dagre 原始顶点,而是调用curvePoints()计算最终绘制曲线。 - 双维度内缩碰撞检测:将所有非端点节点边界内缩
NODE_INSET = 2px、所有其他边标签矩形内缩LABEL_INSET = 1px,逐段调用segmentHits()检查是否有连线穿胸而过。 - 试探性正交重排(Speculative Relayout):一旦发现穿插,CLI 不会盲目给出空洞警告,而是立刻在内存里将布局方向正交翻转(
TB <-> LR)再试算一次!只有当正交方向确实能做到0穿插时,才向 Agent 精确建议```flow LR draws this diagram without crossings;否则建议拆分为概览图与细节图。
此外,flow、api 等组件原生支持在行首添加 +(新增)、-(移除)、~(变更)前缀,自动生成带计数栏与 Before / Changes / After 切换开关的架构演化图,极其适合用来评审重构方案。
2. 纯 JS 动态规划“照片墙”排版器 (src/runtime/layout-plan.js)
传统 CSS Grid 面对长短不一的面板时,要么留出难看的底部空白黑洞,要么把宽时序图硬塞进窄列导致文字溢出。src/runtime/layout-plan.js 用不足 190 行无外部依赖的纯函数实现了一个动态规划(DP)网格布局器 planLayout():
- 预采样插值高度:页面加载时,浏览器适配器先对每个面板在不同候选宽度下采样
{ w, h },DP 求解器通过线性插值估算任意列宽下的实际高度。 - 单列最多堆叠 2 个面板:通过
splits(len)枚举一行内各列容纳 1 个或 2 个连续面板的组合(受MAX_COLUMNS = 6限制),在STEP = 10px步长下搜索最小代价分配,代价函数同时惩罚列高差产生的“空白面积浪费”(waste / 1000)与偏离作者span提示的误差(PREF_WEIGHT = 0.15)。 - 图表比例尺带约束(Scale Band):为了让同一块画板上的多张架构图字号、大小保持视觉协调,求解器尝试不同的缩放带下界
BAND_LOS = [0.75, 0.85, 0.95, 1](上限固定BAND_RATIO = 1.25倍,全局区间[0.75, 1.25]),防止一张小图被放大到 1.25 倍而另一张宽图被挤成 0.5 倍的蚂蚁字。
三、把 ASD-STE100 航空维修规范搬进中文 Agent 质检 (src/lint/ste.js)
受 Andrej Karpathy 曾提及的“用受控英语规范约束大模型写作”启发,src/lint/ste.js 内置了一套机器可执行的中英文写作质量拦截器(默认 style: 80 仅警告,style: strict 直接阻断生成)。我在源码里核对了它针对中文、英文与多语种的精确规则:
- 硬性句长与段落红线:中文说明性句子上限 45 字、操作步骤(有序列表)上限 35 字;英文分别限制为 25 词与 20 词;单个自然段最多 6 句话(
MAX_SENTENCES = 6),超过即触发paragraph-length。 - 中式 AI 腔与轻动词黑名单 (
src/lint/wordlist.zh.js):直接点名拦截“赋能、抓手、闭环、打通、全方位、多维度、深度融合、显著提升、至关重要、综上所述、值得注意的是、底层逻辑、颗粒度、方法论”以及“下面我将 / 希望对你有帮助”等无意义废话;同时捕获“进行XX”“加以XX”“做出XX”等轻动词冗余,并拦截单句出现 3 个及以上“的”字的结构链(de-chain)。 - 端点歧义与常见错别字拦截:比如
10倍以上、5天以内这类容易引发边界争议的描述,会精确提示“明确端点:大于 / 不小于”;“登陆/帐号/阀值/布署”直接建议改写为规范用字。 - 跨语种精确避坑:通过
src/han-forms.js中 300 多组繁简独占字对(如这這、门門、数數)无配置区分简繁体;针对包含假名的日文文本自动跳过中文的字链检查(因为日文“基本的”“具体的”属于合法形容动词词尾);甚至通过src/bidi.js为希伯来语等 RTL 页面隔离嵌入的 LTR 技术术语与 SVG 文本锚点。
我直接在本地用管道喂了一段典型“AI 腔废话”给 am.mjs lint -,实测输出非常干脆利落:
STE 7 warnings (fix the draft and run again):
L5 [word] not recommended: "以上" → name the endpoint: 大于 / 不小于, 小于 / 不大于
L5 [cliche] cliché "赋能" → delete it or state a concrete fact
L5 [cliche] cliché "打通" → delete it or state a concrete fact
L5 [cliche] cliché "全方位" → delete it or state a concrete fact
L5 [cliche] cliché "显著提升" → delete it or state a concrete fact
L5 [cliche] cliché "综上所述" → delete it or state a concrete fact
L5 [cliche] cliché "底层逻辑" → delete it or state a concrete fact
更妙的是 证据豁免机制:被双引号/书名号包裹的引用原话(QUOTED)、行内代码、数学公式、删除线反例以及表格里标记 no / ✗ 的行都会自动跳过 STE 检查——大模型可以放心引用日志、报错和反面示例,不会被误伤。
四、四层零信任防御:当不可信草稿与真实本地仓库共处一室
在设计让 Agent 读取本地代码库并渲染单文件 HTML 的工具时,最容易出事故的往往不是渲染本身,而是两个隐蔽风险:其一,Agent 在引用真实代码时不小心把 .env、私钥或 Token 嵌进了可分享的 HTML 里;其二,模型在文档里写了一段恶意或畸形的原生 HTML/SVG,打开文件时执行了脚本或悄悄向外发起了网络请求。
answer-me-with-html 在这方面建立了一套非常严密的纵深防御堆栈:
逐层拆解这四道防线的实现代码,可以看到作者在工程细节上的老道:
- L1 文件边界与密钥熔断 (
src/code.js):代码块支持src=path lines=18-30 hl=22直接引用仓库真实代码,从根源消灭模型手抄代码产生的“行号幻觉”。为防止越权读取,引擎先用localPath()校验相对路径,再用realpathSync()追踪真实物理路径,彻底堵死符号链接(Symlink)逃逸出当前工作目录;同时通过SECRET_FILE(拦截.env、.pem、id_rsa、.sqlite等)、SECRET_DIR(拦截.git、.ssh、.aws、.kube)以及SECRET_TEXT正则(拦截sk-ant-、AKIA...、ghp_...、eyJ...JWT 与带密码的 URL)三重熔断。 - L2 Markdown AST 与标签级净化 (
src/raw-html.js):即使允许在文本中混写有限 HTML,过滤层也会先把NEVER列表(script、iframe、style、svg、math等 22 个危险或破坏布局的标签)直接转义为纯文本展示,把<host>这类常见占位符温和地按原样文本显示而不是被浏览器吃掉;对保留标签剥离一切on*事件、srcdoc、formaction,并先解码十六进制/十进制 HTML 实体再拦截javascript:与vbscript:伪协议。 - L3 零外连 SHA-256 强制沙盒 (
src/csp.js):生成的每一页 HTML 都在<head>中强行注入极度苛刻的 CSP 策略:
default-src 'none'; script-src 'sha256-...' ...; style-src 'unsafe-inline'; img-src data:; font-src data:; media-src data:; connect-src 'self'; form-action 'none'; base-uri 'none'。
这意味着只有 CLI 自己生成的内联脚本可以通过 SHA-256 哈希校验并执行,哪怕用户显式使用了html逃生围栏塞入<script>,浏览器也会在底层直接拒绝运行(CLI 渲染时也会提前打印行号警告);任何外链图片或远程字体同样无法发出网络请求,所有本地图片必须内联为data:URI,实现真正的单文件断网可看与隐私零泄漏。 - L4 能力令牌与防 DNS 重绑定 (
src/serve.js):当使用am serve --lan或--tailscale把页面投屏到手机或平板查看时,服务端每次启动都会生成随机密钥写入0600权限的serve.json,为每个页面签发不可枚举的 HMAC-SHA256 路径/p/<token>/<file>(重启即全部吊销),并且严格校验 HTTPHost请求头只放行环回地址与显式允许的局域网 IP / Tailscale MagicDNS 域名,彻底阻断 DNS Rebinding 攻击。甚至连热更新注入的LIVE_SCRIPT_BODY哈希,都在离线渲染阶段就被预先钉扎进了cspMeta()之中。
五、信封化 #am-source 与浏览器 WebCodecs 视频管线
除了静态可读,answer-me-with-html 还有两个让我觉得设计品味极佳的闭环机制:
1. 双向反馈与 am patch 原地微创手术
传统对话里,AI 给出一份长方案,人类想修改其中第三部分,往往需要重新生成整份文件或者手动去改代码。在这套系统里,每个生成页面都具备一套双向交互协同飞轮:
- 去锚定偏见的
ask决策组件 (src/components/ask.js):Agent 可以在面板里嵌入单选/多选决策卡片(甚至在选项下嵌套:::语法的架构对比预览图)。源码特意注释并强制实现:所有选项初始状态一律保持未选中(仅给 Agent 推荐项打上data-suggested徽标),防止人类因为默认勾选而盲目确认。 - 状态持久与
am patch原位重织 (src/page.js&src/patch.js):每个 HTML 页面尾部都隐藏了一个<textarea id="am-source" hidden readonly>,完整封存着原始 Markdown(同时内嵌了图片data:URI 与引用代码切片)。人类在浏览器点选ask、给面板写批注或划词标记后,点击右下角 Reply 按钮即可生成一段结构化 Markdown 回复贴回给 Agent;Agent 随后只需运行am patch page.html --panel "缓存方案",即可精准替换对应##小节并原位覆写 HTML。更贴心的是,前端reply.js使用题干文本(keyOf(ask))而非面板编号作为localStorage(或am serve服务端PUT /r/...)的状态键,因此am patch重排面板顺序或增删章节后,人类之前填好的答案依然完好无损。
2. 确定性 render(t) 与零 ffmpeg 的浏览器内视频编码 (src/video/)
am video 把 3Blue1Brown 风格的讲解动画也压进了同一套 Markdown 语法中:每个 ## 面板是一幕场景(Scene),> 开头的行是逐拍旁白(Beat),旁白中用 [节点名] 包裹的词会自动触发镜头缩放聚焦与黄色字幕高亮;相邻场景出现同名节点时自动执行 0.9 秒 跨场景形变动画(TIMING.transition = 0.9)。
语音合成方面,引擎提供了 5 条全覆盖路径:--voice elevenlabs、本地兼容 OpenAI Speech 协议的服务(如 Qwen3-TTS)、任意命令行 TTS(如 AM_TTS_CMD='edge-tts ...')、系统自带语音(macOS say / Linux espeak-ng),以及离线 --audio-map 音频映射;生成的音频统一混音封装进 <audio id="amv-audio" src="data:audio/wav;base64,...">。
最令人惊艳的是它的视频导出双引擎 (src/video/export.js):由于播放器暴露了完全确定性的 render(t) 渲染函数(任意时间戳 t 必定绘出完全一致的画面),--mp4 可以通过 Chrome DevTools Protocol(无需 Playwright / Puppeteer 重型依赖)逐帧截图通过管道喂给 ffmpeg 压制 H.264;而 --webm 与页面内的 Export 按钮则完全不需要 ffmpeg——它直接利用现代浏览器的 WebCodecs API(视频编码 VP9,音频编码 Opus)结合项目手写的纯 JS 容器封装器 src/video/webm.js,直接在页面内部完成 1080p30 音视频编码,再以 1 MiB 切片(WEBM_SLICE = 1_048_572)通过 base64 回传给 CLI 写盘。
六、值得关注的局限性与落地建议
把整套代码库过了一遍之后,我也发现几个在实际工程落地中需要注意的边界与取舍:
[!WARNING] 实战落地避坑提示
- “高频模式”对 Prompt Cache 的双刃剑效应:仓库 README 推荐在全局规则里开启
always-on高频模式,但结合bench/README.md的实测账单可知,每次新会话冷加载约4,000Token 的SKILL.md会抬高首轮缓存写入成本;对于单轮只问一句命令的简单对话,建议保持按需触发,把高频模式限定在架构评审、协议对比与长方案设计会话中。am serve的安全上下文限制了浏览器直出 WebM:am.mjs video --webm依赖浏览器的 WebCodecs API,而浏览器规定 WebCodecs 仅在file://、127.0.0.1/localhost或https://安全上下文中可用;如果你通过am serve --lan在局域网纯 HTTP 环境下用手机打开播放器,点击页面内 Export 按钮会无法调用硬件编码,此时需要改用--public-url https://...反代或在桌面端直接导出。- Dagre 拓扑复杂度上限:虽然
flow-check.js能在直角穿插时给出正交翻转建议,但当单张flow图节点超过 15~20 个且存在密集交叉回边时,Dagre 的层级布局不可避免会出现跨层绕线。遵守作者在警告信息里的建议——拆分为“概览图 + 子模块细节图”,才是保持图面清爽的正解。
总体而言,Answer me with HTML 非常精准地切中了当下 Agent 交互中最痛的“阅读带宽瓶颈”。它没有去卷花哨的在线画布或重型 React 前端,而是用一份 1.1 MB 的零依赖单文件 CLI,把算力卸载、几何避障、受控写作、CSP 沙盒、双向修补与 WebCodecs 视频全套打穿——对于任何正在构建 Coding Agent Skill 或本地智能体工作流的人来说,它的工程克制感与安全意识都非常值得对照源码细读一遍。
原文链接与参考资料
- 项目主仓库:QingYunA/answer-me-with-html - GitHub
- 官方网站与主题目录:Answer me with HTML Official Site
- 基准测试与 Token 拆解报告:Benchmark: ask for HTML directly vs Answer me with HTML
- 中文与多语言受控写作参考:Simplified Technical Chinese Wordlist · ASD-STE100 Specification
- 核心底层依赖:dagrejs/dagre · Temml (TeX to MathML) · Marked Markdown Parser