lijianfei.com

自 Anthropic 推出 Claude Artifacts 以来，以交互式画板、可编辑幻灯片、动态设计系统与数据仪表盘为代表的视觉交付形态，彻底颠覆了以往纯文本与散装代码片段的原型构思方式。然而在长期的工程实战中，这种封闭在 claude.ai 云端 SaaS 容器内的交互机制始终让我感到束手束脚：生成的原型既无法直接读取我本地工程里的真实数据表与组件库，也无法纳入 Git 版本控制；每次想要对画板做微调，只能在网页端来回复制粘贴 Prompt，或者被困在缓慢的云端重新生成等待中。

最近，我深度研读并上手了由 Jim Liu（宝玉）开源的 baoyu-design（GitHub 开源仓库：JimLiu/baoyu-design）。它没有重复造轮子去写一套粗糙的 HTML 模板生成器，而是完成了一项极具巧思的系统级逆向与解耦重构：将 Anthropic 原生 Claude Design 的完整 Artifact 运行时机制与前端可视化编辑器整体剥离并离线化，封装成标准的 Agent Skills 协议。无论是在 Cursor、Claude Code、Codex 还是 DeepSeek Harness 中，本地 Agent 都能直接在工程磁盘上创建符合原生规范的幻灯片、多画板设计画布、设计系统与实时数据看板；配合其自研的零依赖本地 HTTP 伺服总线与双向视觉评论流（Send to agent），我与 Agent 实现了在本地 localhost 画布上的毫秒级双向人机协同。在本文中，我将以第一视角深入剖析 baoyu-design 的底层离线架构、双向同步协议与工程实现细节。

一、 破局云端围墙：从 SaaS 孤岛到本地“文件即状态”

在 claude.ai 的云端沙箱中，一个 Artifact 本质上是托管在远端服务器上的一组虚拟内存状态或临时数据库记录。用户虽然能在网页端直观预览与操作，但一旦离开浏览器，这些成果便与本地工程开发流彻底脱节。

baoyu-design 的核心设计哲学非常纯粹：将所有交互式交付物彻底还原为本地磁盘上的普通文件，以文件系统作为单一事实来源（Single Source of Truth）。

在 2.0 乃至最新的 2.3 版本中，项目全面归档了早期生成单文件 HTML 的粗糙模式，将能力重塑为 4 个标准的本地 Artifact 技能与 1 个图表工程规范：

为了让这一整套体系在本地无缝运转，baoyu-design 构建了一个三层解耦的工程体系：

flowchart TD
    subgraph AgentLayer ["Agent 运行时与宿主层"]
        IDE["本地编码环境<br/>(Cursor / Claude Code / Codex / DSH)"]
        LLM["推理大模型<br/>(Claude Opus 5.5 / Sonnet / DeepSeek)"]
        IDE <--> LLM
    end

    subgraph FileSystem ["工程文件系统 (Single Source of Truth)"]
        DesignDir["本地设计目录 (designs/<slug>/)"]
        ProjectDir["project/ 核心产物"]
        JSONIndex["结构索引 (canvas.json / deck.json)"]
        MarkupFiles["组件与页面 (*.dc.html / slides/*.html)"]
        AssetsDir["assets/ 资源哈希存储 (SHA-256)"]
        CommentsFile["comments.json (双向人机评论串)"]
        
        DesignDir --> ProjectDir
        ProjectDir --> JSONIndex
        ProjectDir --> MarkupFiles
        ProjectDir --> AssetsDir
        DesignDir --> CommentsFile
    end

    subgraph RuntimeBridge ["本地 Artifact 伺服总线 (artifact.mjs)"]
        CLI["本地 CLI / RPC 调度入口"]
        MicroServer["无依赖 HTTP 微服务 (server.mjs)"]
        SSEHub["文件监听与 SSE 热重载中枢"]
        CommentLoop["__comments 长轮询等待总线"]
        
        CLI --> MicroServer
        MicroServer --> SSEHub
        MicroServer --> CommentLoop
    end

    subgraph BrowserUI ["本地可视化编辑器 (localhost:PORT)"]
        VisualCanvas["交互画布 / 幻灯片放映 / 属性检查器"]
        TweaksPanel["实时 CSS Tweaks & 变量面板"]
        CommentPin["图纸坐标级评论浮层 (Comment Pin)"]
        ExportEngine["Chromium / PptxGenJS 导出管道"]
        
        VisualCanvas --> TweaksPanel
        VisualCanvas --> CommentPin
        VisualCanvas --> ExportEngine
    end

    IDE -- "文件写入与命令调用" --> CLI
    CLI -- "更新与写入" --> ProjectDir
    MicroServer -- "读取与原子写回" --> ProjectDir
    SSEHub -- "推送变更事件 (changeSeq)" --> VisualCanvas
    VisualCanvas -- "GUI 改动回写 (POST publish)" --> MicroServer
    CommentPin -- "Send to agent 触发" --> CommentLoop
    CommentLoop -- "唤醒 Agent 会话" --> IDE

这种架构彻底击碎了传统 AI 生成工具中“代码是代码，原型是原型”的界限。Agent 产出的不再是不可维护的一锤子买卖代码，而是一套包含元数据索引、组件模块与静态资源的现代前端工程包。

二、 剖析本地桥梁：artifact.mjs 的零依赖 RPC 与自托管微服务

在 claude.ai 内部，Artifact 的渲染依赖于 Anthropic 复杂的云端容器、对象存储和后端服务。如果本地化需要用户运行庞大的 Docker 容器或执行耗时繁杂的 npm install 构建流程，其落地门槛将不可接受。

我在仔细剖析 skills/claude-design/scripts/artifact.mjs 与 server.mjs 的源码后发现，作者团队采用了极其克制而高超的工程选型：全部基于 Node.js 原生标准库（Node 20+，看板需 Node 22+）实现，预编译打包，零三方运行时依赖。

1. 原子化 CLI 命令与轻量微服务驱动

artifact.mjs 向上对 Agent 暴露标准化的 JSON-RPC 接口，向下自建轻量 HTTP 伺服体系：

# 启动本地编辑器后台服务并自动分配可用端口，输出访问 URL
node skills/claude-design/scripts/artifact.mjs open designs/app-wireframe

# 执行静态语法、布局边界与无障碍对比度合规校验
node skills/claude-design/scripts/artifact.mjs check designs/app-wireframe

# 以哈希内容寻址方式上传素材并返回虚拟 /_blob/<id> 地址
node skills/claude-design/scripts/artifact.mjs upload designs/app-wireframe hero.png

# 阻塞式等待人类通过编辑器派发的评论指令（带超时熔断）
node skills/claude-design/scripts/artifact.mjs comments designs/app-wireframe --wait

当执行 open 命令时，脚本通过 spawn 派生一个完全解耦的后台 Node 进程，将运行时状态写入设计目录同级的 .artifact-server.json（记录 PID、端口、启动时间与 Token），并通过标准 Unix 信号或 HTTP 终端安全受控关闭，彻底杜绝了僵尸进程遗留。

2. 内容寻址存储（CAS）与虚拟 Blob 路由

在 Web 前端开发中，图片和字体引用经常因相对路径错乱导致资源 404。baoyu-design 借用了 Git 的内容寻址思想：

• 当调用 upload 上传本地文件时，底层计算其二进制内容的 SHA-256，取前 32 位十六进制字符串作为虚拟 ID；
• 文件被转存为 project/assets/<id>.<ext>，并在内置的 index.json 中维护 MIME 类型映射；
• 在 HTML 标记中，统一以 /_blob/<id> 形式无缝引用。本地微服务通过拦截 /_blob/ 路径，向浏览器输出带有 Cache-Control: private, max-age=31536000, immutable 的高速缓存响应。相同的文件无论被复制多少次，在磁盘与内存中始终只有一份。

3. 严格的静态 AST 质检守门员（check 机制）

很多 LLM 在生成 HTML/CSS 时，极易产生非闭合标签、超高 z-index 污染、硬编码行高溢出或无意义的空标签。artifact.mjs 内置了一套极速 AST 与正则校验引擎：

• 容器与流式布局约束：检测画板是否满足 expand: "fill" 的弹性页面规范，禁止在移动端画板外层滥用固定像素死高度；
• 排版与无障碍色彩对比度：自动计算文本颜色与背景色的明度对比度，对未达到 WCAG 4.5:1 的灰度说明文字抛出警告；
• 资源完整性：全局扫描所有 /_blob/ 引用，确保每个引用的资源在 project/assets/ 下真实存在，杜绝首屏白块与裂图。

[!NOTE] 质检协议的设计原则
check 阶段只做“语法和约束的确定性校验”，完全不加载浏览器内核进行繁重的无头渲染。只有当静态检查完全通过（problems: 0）时，Agent 才会停止迭代并将访问链接交给用户，在保证交付质量的同时节约了宝贵的 Token 与推理时长。

三、 双向交互闭环：“Send to agent”与文件状态机

以往的 AI 辅助设计最痛苦的痛点莫过于：单向生成的不可持续性。
Agent 生成了一份漂亮的画板，用户肉眼发现主标题距离副标题太近，或者想要换个品牌主色。在传统模式下，用户只能用自然语言重新描述给 AI，AI 很容易“改好了间距，却把原本正确的其他排版改乱”；而如果用户直接在代码编辑器里手工改，下一次让 AI 增加新模块时，AI 往往会覆写用户的改动。

baoyu-design 依托其强大的双向状态同步协议，完美破解了这一死局：

sequenceDiagram
    autonumber
    actor User as 设计师 / 工程师 (人类)
    participant Editor as 本地可视化编辑器 (localhost)
    participant Server as 本地 HTTP 微服务 (server.mjs)
    participant Disk as 磁盘文件 (project/*.html & comments.json)
    participant Agent as 编码 Agent (Cursor / Claude Code)

    Note over User, Agent: 阶段一：协同初始化与实时推流
    Agent->>Disk: 写入 canvas.json 与 Main.dc.html
    Agent->>Server: 执行 open 命令启动微服务
    Server-->>Agent: 返回 http://localhost:PORT
    Agent->>Editor: 浏览器加载画板视图
    Agent->>Server: 执行 comments --wait 挂起等待反馈

    Note over User, Agent: 阶段二：人类视觉微调与原子持久化
    User->>Editor: 在画布上拖拽组件、修改文案、调整色板
    Editor->>Server: 发起 POST /publish (带 ifMatch 校验)
    Server->>Disk: 原子覆盖写入 project/ 磁盘文件
    Note over Disk: 保持最新修改，零代码覆盖丢失

    Note over User, Agent: 阶段三：图元级打点评论与唤醒回路
    User->>Editor: 按 C 键对组件打点留下批注，勾选 "Send to agent"
    Editor->>Server: 写入批注元数据 (坐标、选区、上下文说明)
    Server->>Disk: 追加写入 comments.json
    Server-->>Agent: 释放 comments --wait 长轮询，返回评论 Threads
    
    Note over User, Agent: 阶段四：Agent 自主理解与修复闭环
    Agent->>Disk: 读取 comments.json 与目标 .dc.html
    Agent->>Disk: 精确重构代码，修复指定图元问题
    Server->>Editor: fs.watch 捕获改动，通过 SSE 推送变更事件
    Editor-->>User: 画布毫秒级热更新，呈现 Agent 修正结果
    Agent->>Server: 调用 comment-resolve 标记批注解决并回填答复
    Editor-->>User: 评论气泡自动收起或标记 Resolved

1. SSE 热重载与原子写回保护

server.mjs 内部建立了一套精密的文件防竞态状态机：

• 当用户在浏览器编辑器中微调时，前端发出 POST /publish 请求。服务端在写入前会对比当前磁盘文件的哈希签名，确保在多面板并发编辑时没有并发脏写；
• 当 Agent 响应提示词修改本地 .dc.html 时，服务端的 fs.watch 监听到文件变化，自动计算文件哈希确认非前端自身回写后，通过 Server-Sent Events（text/event-stream）向浏览器下发包含递增序列号 changeSeq 的 changes 事件，前端实现零刷新的无感更新。

2. 坐标级视觉批注与长轮询调度

在 claude-slides、claude-design 和 claude-design-system 编辑器中，用户按下键盘快捷键 C 即可在画布任意位置、任意组件容器上钉下评论 Pin。
每个评论对象除了包含文字内容外，还包含严格的视口与图元相对坐标。只要勾选 Send to agent，微服务内部由 __comments/agent/wait 维持的长轮询 HTTP 通道立即触发返回。Agent 终端从休眠中被唤醒，直接拿到具有明确图元指向的结构化上下文，直奔问题核心，改完后自动调用 comment-resolve 结项。

这种“人类负责视觉挑刺，AI 负责代码执行，双方在同一套文件上交替落笔”的体验，代表了现代结对编程与辅助设计形态的真正未来。

四、 拒绝 AI 套话：Anthropic 级设计美学与 PPTX 编译黑科技

为什么多数通用 LLM 编写的前端页面总有一种浓浓的“廉价 AI 味”？
因为未经调教的大模型有着严重的视觉偷懒倾向：大面积使用从紫到蓝的弥散渐变背景、左侧带彩色竖条的高亮卡片、浮夸的卡片发光边框，以及充斥全屏的毫无意义的 Emoji。

在研读 skills/claude-design/SKILL.md 与 skills/dataviz/ 的核心规范时，我看到了极其严谨的设计工艺红线（Craft Rules）。

1. 刻入底层提示词的设计审美约束

• 严禁 AI 视觉套路（Anti-AI Tropes）：严禁出现弥散渐变遮罩、左边框卡片、假手机状态栏（Fake Status Bars）与无意义 Emoji。图标优先使用挂载设计系统中的矢量图标或纯手写内联 SVG；
• 拒绝占位符谎言：严禁伪造统计数据与虚假引言，缺失的业务数据必须统一写为结构化占位符（如 [YOUR PRICE]、[28 天转化率]），促使用户补充真实上下文；
• 色彩层级与无障碍严苛度：默认调色板采用经典的 Anthropic 官方审美风格：象牙白（Ivory #FAF9F5）、板岩黑（Slate #141413）与粘土陶红（Clay #D97757）。文本严禁直接继承强调色，必须使用主墨水色（Primary Ink）；
• 数学级调色校验器：dataviz 技能附带了可运行的 validate_palette.js / validate_palette.py。它利用 OKLab 色彩空间计算 $\Delta E$。相邻分类色之间的 CVD 色弱辨识度 $\Delta E \ge 8$，正常视觉底线不得低于 15。一旦运行失败，脚本直接退出并给出量化调优步长。

2. 幻灯片的双模式 PPTX 导出编译管线

在企业级办公场景中，无法导出为本地 Office 格式是阻碍技术选型落地的最大障碍。claude-slides 内置了一套令人惊叹的 PPTX 编译与排版转译管线：

flowchart TD
    subgraph BrowserRuntime ["Chromium 运行时 (浏览器环境)"]
        HTMLSlide["1920×1080 幻灯片 DOM"]
        Inject["注入 window.__genpptx 捕获包"]
        SetupAction["隐藏控制栏 / 替换本地字体 / 移除 CSS 缩放"]
        WaitFont["等待 document.fonts.ready 字体完全就绪"]
        
        HTMLSlide --> Inject
        Inject --> SetupAction
        SetupAction --> WaitFont
    end

    subgraph CaptureModes ["双模捕获引擎"]
        WaitFont --> ModeChoice{"导出模式判断"}
        
        subgraph PixelMode ["像素级保真 (截图模式)"]
            Screenshot["page.screenshot(2×) 高清渲染"]
            PNGExport["导出每页独立无损 PNG"]
            Screenshot --> PNGExport
        end
        
        subgraph EditMode ["原生矢量对象 (可编辑模式)"]
            DOMWalk["深度遍历 DOM 树"]
            StyleParse["解析 computedStyle & 相对位置"]
            TreeToJSON["序列化为带样式的抽象图元 JSON 树"]
            DOMWalk --> StyleParse --> TreeToJSON
        end
        
        ModeChoice -- "高保真展示需求" --> Screenshot
        ModeChoice -- "需要二次排版" --> DOMWalk
    end

    subgraph AssemblyEngine ["Node 侧 PptxGenJS 装配器"]
        CoordCalc["尺寸单位换算 (px ÷ 96 = 英寸, px × 0.75 = pt 字号)"]
        Woff2Decode["内嵌 Google Fonts & 解码 WOFF2 字体"]
        NotesExtract["提取 <aside> 演讲者备注注入幻灯片元数据"]
        BuildPPTX["组装 OpenXML 包并写出 .pptx 文件"]
        
        PNGExport --> CoordCalc
        TreeToJSON --> CoordCalc
        CoordCalc --> Woff2Decode
        Woff2Decode --> NotesExtract
        NotesExtract --> BuildPPTX
    end

这种双轨制的设计思路展现了极高的工程成熟度：需要发给客户直接汇报演示时，使用像素级还原的 2× 截图模式；需要在 PowerPoint 中交给同事二次填词修改时，使用遍历 DOM 树解析出的原生矢量形状与文本框模式，且自动提取 <aside> 标签内的演讲者备忘录！

五、 实战复盘：传统云端 SaaS 与本地 Agent 生产力实测

为了量化评估 baoyu-design 带来的实际开发效率提升，我使用一份真实的技术产品 PRD，分别通过 claude.ai/design 云端界面与本地 Cursor + baoyu-design 技能，构建一套包含 6 页产品架构演示幻灯片与 2 个端侧设计画板的完整方案。

以下是记录的多维度工程指标对比：

为了更直观展示两种模式在综合工序耗时上的差异，我统计了各个环节的用时对比：

xychart-beta
    title "设计交付各阶段工序耗时对比 (秒级)"
    x-axis ["环境准备", "初稿生成", "局部微调", "排障修正", "导出构建", "版本归档"]
    y-axis "耗时 (秒)" 0 --> 120
    bar [45, 80, 110, 95, 60, 40]
    bar [5, 18, 2, 8, 12, 3]

[!TIP] 图表数据解读
图中第一组柱体为传统的云端网页模式，在频繁的微调与排障修正环节，开发者耗费了大量时间与网络延迟和大模型幻觉反复拉扯；而第二组柱体所代表的本地 Agent 协同模式，凭借“即改即显”与精确的断点批注，将繁琐的修补耗时压缩到了极致。

六、 总结与思考：下一代工程化 Agent 技能的演进范式

在完整通读 baoyu-design 的架构实现并在日常开发中重度实践后，我对当前 AI Coding 与 Agent 系统的发展趋势有了三点深刻的体会：

1. 从“聊天机器人”走向“本地进程级协作伙伴”：
   过去的辅助设计工具往往试图把 AI 塞进一个侧边栏做成问答助手。而 baoyu-design 展现了另一种可能：大模型本质上是一个具备代码读写能力的协作者，给它一套规整的本地 CLI、一套标准的文件格式规范，它就能像资深前端工程师一样直接在代码库中落笔。
2. “文件即状态”是工程稳健性的终极护城河：
   无论云端架构多么炫酷，一旦离开网络就全盘瓦解。将状态下沉到 project/ 目录下的纯粹 JSON 与 HTML 中，不仅获得了 Git 版本控制的天然红利，更为不同编辑器插件（Cursor、Claude Code、DeepSeek Harness）之间的无缝切换打下了基石。
3. 人机协同的黄金分割点在“分工”而非“包办”：
   大模型擅长宏观解题、语义抽象与结构搭设，但在像素对齐、审美偏好等微观体验上，人类直觉依然无可替代。baoyu-design 没有执着于让 AI 做到 100% 自动化，而是通过双向评论机制与本地实时编辑器，让人类与 Agent 各司其职、各展所长。

如果你也正因云端设计沙箱的封闭性与高延迟而苦恼，或者正在寻找一款能无缝融入本地 Cursor / Claude Code 工作流的下一代视觉原型系统，baoyu-design 的架构设计与工程实践无疑是一本极具参考价值的教科书级实战范本。

原文链接与参考资料

• baoyu-design GitHub 官方开源仓库：JimLiu/baoyu-design
• DeepSeek Harness 官方插件支持：deepseek-ai/deepseek-harness
• Vercel Labs Agent Skills 标准与 CLI：vercel-labs/skills
• Anthropic Claude Artifacts 官方设计指引与理念：Claude Design Architecture Overview
• PptxGenJS 原生 PowerPoint 生成库：gitbrent/PptxGenJS