把 47% 的 SVG 坐标算力从大模型手里拿走:剖析 Answer me with HTML 的单文件引擎、STE100 质检与 WebCodecs 视频管线

把 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(tag v0.6.2 / commit 997479b,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 倍),更把整个工具链变成了一条可验证、可局部修补、完全离线运行的编译流水线:

Answer me with HTML 角色分工与数据流管线

原作者同时非常坦诚地指出了一个容易被忽略的账单细节(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 KB Temml 的零启动惩罚
我在审计打包脚本 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():

  1. 提取平滑折线采样点:由于 flow.js 渲染时会用 smoothPath 把直角折弯切成圆角弧线,检测器不是粗暴测 Dagre 原始顶点,而是调用 curvePoints() 计算最终绘制曲线。
  2. 双维度内缩碰撞检测:将所有非端点节点边界内缩 NODE_INSET = 2px、所有其他边标签矩形内缩 LABEL_INSET = 1px,逐段调用 segmentHits() 检查是否有连线穿胸而过。
  3. 试探性正交重排(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 在这方面建立了一套非常严密的纵深防御堆栈:

Answer me with HTML 四层零信任安全与离线隔离堆栈

逐层拆解这四道防线的实现代码,可以看到作者在工程细节上的老道:

  1. 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)三重熔断。
  2. L2 Markdown AST 与标签级净化 (src/raw-html.js):即使允许在文本中混写有限 HTML,过滤层也会先把 NEVER 列表(script、iframe、style、svg、math 等 22 个危险或破坏布局的标签)直接转义为纯文本展示,把 <host> 这类常见占位符温和地按原样文本显示而不是被浏览器吃掉;对保留标签剥离一切 on* 事件、srcdoc、formaction,并先解码十六进制/十进制 HTML 实体再拦截 javascript: 与 vbscript: 伪协议。
  3. 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,实现真正的单文件断网可看与隐私零泄漏。
  4. L4 能力令牌与防 DNS 重绑定 (src/serve.js):当使用 am serve --lan 或 --tailscale 把页面投屏到手机或平板查看时,服务端每次启动都会生成随机密钥写入 0600 权限的 serve.json,为每个页面签发不可枚举的 HMAC-SHA256 路径 /p/<token>/<file>(重启即全部吊销),并且严格校验 HTTP Host 请求头只放行环回地址与显式允许的局域网 IP / Tailscale MagicDNS 域名,彻底阻断 DNS Rebinding 攻击。甚至连热更新注入的 LIVE_SCRIPT_BODY 哈希,都在离线渲染阶段就被预先钉扎进了 cspMeta() 之中。

五、信封化 #am-source 与浏览器 WebCodecs 视频管线

除了静态可读,answer-me-with-html 还有两个让我觉得设计品味极佳的闭环机制:

1. 双向反馈与 am patch 原地微创手术

传统对话里,AI 给出一份长方案,人类想修改其中第三部分,往往需要重新生成整份文件或者手动去改代码。在这套系统里,每个生成页面都具备一套双向交互协同飞轮:

Answer me with HTML 双向人机协同与原地增量补丁飞轮
  • 去锚定偏见的 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] 实战落地避坑提示

  1. “高频模式”对 Prompt Cache 的双刃剑效应:仓库 README 推荐在全局规则里开启 always-on 高频模式,但结合 bench/README.md 的实测账单可知,每次新会话冷加载约 4,000 Token 的 SKILL.md 会抬高首轮缓存写入成本;对于单轮只问一句命令的简单对话,建议保持按需触发,把高频模式限定在架构评审、协议对比与长方案设计会话中。
  2. 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://... 反代或在桌面端直接导出。
  3. Dagre 拓扑复杂度上限:虽然 flow-check.js 能在直角穿插时给出正交翻转建议,但当单张 flow 图节点超过 15~20 个且存在密集交叉回边时,Dagre 的层级布局不可避免会出现跨层绕线。遵守作者在警告信息里的建议——拆分为“概览图 + 子模块细节图”,才是保持图面清爽的正解。

总体而言,Answer me with HTML 非常精准地切中了当下 Agent 交互中最痛的“阅读带宽瓶颈”。它没有去卷花哨的在线画布或重型 React 前端,而是用一份 1.1 MB 的零依赖单文件 CLI,把算力卸载、几何避障、受控写作、CSP 沙盒、双向修补与 WebCodecs 视频全套打穿——对于任何正在构建 Coding Agent Skill 或本地智能体工作流的人来说,它的工程克制感与安全意识都非常值得对照源码细读一遍。


原文链接与参考资料