Lavish-axi 总体架构解析：CLI、本地服务器与沙箱 iframe 如何协同工作

Lavish-axi 总体架构解析CLI、本地服务器与沙箱 iframe 如何协同工作【免费下载链接】lavish-axiHTML is the new markdown. Lavish is the new editor for your HTML artifacts.项目地址: https://gitcode.com/gh_mirrors/la/lavish-axiLavish-axiLavish Editor是一个本地优先的 HTML 产物协作编辑器采用「CLI 本地服务器 沙箱 iframe」三层架构Agent 写好 HTML 文件后用lavish-axi 文件一条命令在本地浏览器打开用户可以直接圈选元素、批注文本、编辑 Mermaid 白板再通过长轮询把反馈送回给 Agent。整个闭环不依赖云端本文带你快速看懂这三层是如何协同的。整体架构一次反馈是如何流动的Lavish 的协作回路可以拆成 4 步Agent 产出产物Agent 按用户请求生成一个 HTML 文件计划、对比表、架构图、报告等CLI 打开评审界面lavish-axi html-file确保本地服务器在运行并在浏览器中打开该文件的评审页用户做标注在页面里点选元素、选中文字批注、排队提示词或把布局问题从收件箱里批量加入队列Agent 轮询取回lavish-axi poll html-file长轮询等待用户一提交反馈就原路返回给 Agent。这个流程在 README 的 How It Works 一节中有完整的 ASCII 流程图核心设计是**「文件路径即身份」**会话以 HTML 文件的路径为键sessionKey 用规范路径的 sha256 前 16 位作键Agent 无需处理任何不透明 ID直接说文件名即可。第一层CLI 与后台服务器的进程模型CLI 是整个架构的入口源码入口为 cli.js核心命令有命令作用lavish-axi html-file打开或恢复一个评审会话openCommandlavish-axi poll html-file长轮询等待用户反馈pollCommandlavish-axi export / share导出单文件 HTML / 发布到第三方托管lavish-axi stop关闭后台服务器它的关键设计是「一个后台服务器服务所有会话」CLI 以分离detached方式拉起lavish-axi server子进程startServer然后轮询/health接口拿到{ ok, app, version }才认为就绪之后每次调用 CLI都会先探测本机是否已有同版本服务器ensureServer有则复用、版本旧则优雅替换因此多个 Agent 在同一台机器上可以共享同一个服务器和同一份会话状态会话状态统一存放在~/.lavish-axi/state.json可用LAVISH_AXI_STATE_DIR改服务器空闲 30 分钟自动退出零云依赖。服务器本体是 server.js约 3000 行的 Express 应用它承担三个角色评审页服务、产物文件服务器、反馈事件总线基于 WebSocket 的实时通道 EventEmitter长轮询。第二层沙箱 iframe —— 产物如何被安全地打开打开评审页后页面结构是「外框 内嵌 iframe」外框chrome 页由 createChromeHtml 生成负责对话面板、批注卡片、发送按钮等 UI内嵌的 iframe 指向/artifact/:key/index.html加载的就是 Agent 写的那个 HTML 文件本身。安全隔离是这层的核心规则很清晰iframe 使用sandbox属性allow-scripts allow-forms allow-popups等没有allow-same-origin产物脚本拿不到外框 DOM 的任何特权内外通信只能走postMessage。为了让产物可批注服务器在产物响应时只做一处注入——injectLavishSdk 在/body前追加一个script src/sdk.js?key...标签。这个小 SDKartifact-sdk.js在 iframe 内提供元素/文本批注、DOM 快照、渲染期布局体检以及白板和表格语义解析。这个最小注入原则带来一个重要好处保存在磁盘上的 HTML 文件与直接双击打开时渲染效果完全一致Lavish 不往产物里塞任何设计系统或标记。一个有趣的延伸如果你要求 Agent 输出可编辑的 Mermaid 白板渲染出的每张 Mermaid 图都会被 SDK 替换成内嵌的 Excalidraw 画布点击即可解锁编辑实现见 whiteboard-core.js、whiteboard-store.js编辑摘要随反馈送回后Agent 只需更新产物里的 Mermaid 源码——源码始终是权威导出文件仍然是普通 Mermaid。第三层长轮询反馈回路 —— 把用户的话送回 Agent这是三层协同的最后一公里设计上有几个值得新手理解的点排队与送达分离用户在批注卡片或对话面板里提交的内容先进入服务器队列浏览器立即显示已排队气泡poll命令返回时反馈即被消费所以 Agent 端拿到后要完整读取响应轮询是有独占性的同一会话同一时刻只有一个poll持有者第二个并发poll会收到类型化错误而不是静默等待响应字段顺序是契约prompts、artifact_failures、next_step都排在可能很大的dom_snapshot之前即使 Agent 截断输出用户的原话和下一步指令也不会丢断线不丢反馈poll 被中断或超时后重跑是安全的队列里的反馈一直保留到真正交付为止。布局问题收件箱Layout issues也走同一条路SDK 在 iframe 内被动体检产物溢出、文字被裁切、遮挡等问题只进收件箱、永不主动唤醒 Agent——只有用户点击Queue selected fixes把问题批量入队后才会作为一条普通反馈随发送到达 Agent。这是刻意的被动检测设计避免自动修复的来回折腾。安全边界本地服务器不是免检通道虽然默认只监听127.0.0.1Lavish 仍给本地服务器加了两道全局中间件Host 头白名单拒绝任何Host缺失或不属于本服务器的请求用于防御 DNS rebinding 攻击Origin/Referer 守卫所有会改变状态的接口提交反馈、上传附件、发布分享等只接受来自自家评审页的同源请求无头请求的 CLI 控制通道则不受影响。另外会话键是派生而非秘密知道文件路径就等于知道会话键所以任何接口都不把持有键当作授权依据。附件上传也做了内容寻址id 是文件内容的 sha256 尺寸配额 参考计数清理路径完全由服务器决定客户端无法指向任意文件。关键模块路径速查模块职责src/cli.js全部 CLI 命令、服务器拉起与探测逻辑src/server.jsExpress 服务器、评审页与产物路由src/html-transform.js产物 SDK 注入唯一改动点src/artifact-sdk.jsiframe 内批注/快照/布局体检 SDKsrc/session-store.js会话状态、反馈队列与文件路径会话键src/layout-warnings.js布局问题生命周期指纹、状态机src/export-bundle.js本地资源内联的导出/分享打包src/whiteboard-core.jsMermaid → Excalidraw 白板核心总结三层各司其职CLI是 Agent 侧的唯一接口负责会话编排与反馈交付零安装即可npx -y lavish-axi运行本地服务器是所有会话共享的中枢负责状态持久化、实时事件与安全边界沙箱 iframe让任意 Agent 产出的 HTML 在隔离环境里既活着可交互、可批注又安全无同源特权且不改一个字节地保存。三者通过「文件路径做身份 postMessage 通信 长轮询交付」串成一个完整的 Human-AI 评审闭环——这正是 Lavish 把HTML is the new markdown落地的方式。想继续深入了解可以阅读 AGENTS.md 中的架构章节与 README.md 的完整 CLI 参考。【免费下载链接】lavish-axiHTML is the new markdown. Lavish is the new editor for your HTML artifacts.项目地址: https://gitcode.com/gh_mirrors/la/lavish-axi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考