
# 六道门与浏览器验收：用 UI Design Agent Kit 做一个 3D 乐高积木工厂

## 摘要

AI 生成界面已经不难，难的是证明它"能用"。本文用一个可玩的 3D 乐高积木工厂，拆解 UI Design Agent Kit 的六道门工作流：方向稿、素材清单、原型、设计契约、浏览器验收、调用留痕。文章给出 WorkBuddy 的接入命令、积木网格与支撑规则的具体实现、验收清单，以及这套方法明确管不到的地方。适合正在用 AI 写前端、希望把"看起来能跑"变成"可以检查"的开发者。

## 一、背景：生成速度之外，真正的瓶颈是验收

用 AI 写 UI 的流程，通常是这样的：描述需求，AI 输出一版页面，看着不错，继续提修改。几轮之后，页面能跑，但没人说得清三件事：

1. 哪些设计决策是确认过的，哪些是 AI 自己加的。
2. 桌面之外的状态有没有检查过，比如手机宽度、键盘操作、减少动效、错误态。
3. 交付物除了代码，还有什么。运行命令、素材来源、已知限制，往往一样都没有。

2026 年 10 月，我把自己开源的项目 UI Design Agent Kit 提交到 WorkBuddy「1024 造物挑战」。为了验收这套工作流，我用它做了个 3D 乐高积木工厂，作为可玩的案例。积木案例的线上页面名是「积木小工坊」，下文按工作流的六道门展开。第一版很快就动起来了，但它同样卡在上述三个问题里。于是我用这套有确认节点的工作流重做了一遍。

工作流展厅：<https://agent.kcos.club/>
积木案例：<https://agent.kcos.club/demos/brick-workshop/>
仓库地址：<https://github.com/muzimu217/ui-design-agent-kit>（案例在 `demo/brick-workshop`）

![乐高积木工厂桌面工作区：左侧积木盒、中间 3D 搭建区、右侧工具与状态](https://developer.qcloudimg.com/http-save/yehe-11827391/3ad282747e29aa377ddba58b87156a48.png)

*图 1：桌面工作区。24×24 底板，当前作品 40 块积木。*

## 二、工作流：六道门分别管什么

Kit 的核心是一条把"需求、设计决策、验收证据"拆开的流水线。仓库里叫六道门，A 到 E 是用户停点，F 是留痕门。

| 门 | 必交产物 | 进入下一阶段的条件 |
|---|---|---|
| A 方向稿 | 布局关系、参考来源、三个风格旋钮 | 用户确认方向 |
| B 素材清单 | 候选来源、使用位置、授权边界 | 用户选定素材 |
| C 原型 | 无代码原型（生成图 / 素材拼板）或关键界面截图 | 用户确认结构 |
| D 契约 | `DESIGN.md`：Mission、语义 token、Do/Don't、动效参数、验收门 | L 级或新动效面时强制；本项目属于该档 |
| E 验收 | 桌面、移动、键盘、减少动效截图与问题清单 | 用户判定这一轮是否通过 |
| F 调用留痕 | MCP 与工具调用记录 | 非用户停点，只要求留痕 |

配套的规则比表格更重要：

- **一门一呈交**。方向、素材、实现不能打包成一次"你看看"。
- **裁决只覆盖它回应的门**。"风格可以"不等于素材选定，"继续"不等于验收通过。
- **不确定是否触发门，就问用户**。代理不能自己判定豁免。
- **没过门不产出下一阶段的东西**。在门 A 待决时写代码，属于流程 P0。

流程看起来重。它把返工挪到了前面。

## 三、接入 WorkBuddy：克隆仓库，跑一条接入命令

Kit 不绑定宿主。Codex、Claude Code、Cursor、Gemini CLI、GitHub Copilot、Windsurf、Cline、OpenCode、ZCode、DeepSeek Harness、OpenClaw、WorkBuddy、Hermes，共 13 个宿主走同一条接入路径。

前置条件有三个：Kit 需要 Node.js 20.18.1 以上；积木 demo 需要 Node 20.19+（20 系）、22.12+（22 系）或 24 及以上；目标项目根要有 `.git`。

先把仓库克隆到本地并装依赖：

```bash
git clone https://github.com/muzimu217/ui-design-agent-kit.git
cd ui-design-agent-kit
npm ci --ignore-scripts
```

然后在你的项目根执行：

```bash
node /path/to/ui-design-agent-kit/scripts/uak-init.mjs \
  --uak /path/to/ui-design-agent-kit \
  --host other
```

WorkBuddy 用 `--host other`。这条命令做四件事：

1. 探测宿主。`--host` 显式指定时以参数为准；不指定时，存在 `.codex/` 按 Codex 处理，存在 `CLAUDE.md` 按 Claude 处理，否则落到 `other`。
2. 把 lean 版提示词导出到项目的 `.agents/uak-prompt.md`。
3. 幂等写入 `AGENTS.md` 的接入区块，重复执行不会产生第二份。
4. 列出 MCP 配置步骤，并写入 `.agents/uak-mcp-setup.md`。它不修改宿主配置。

需要预览或自检时，分别加 `--dry-run` 和 `--check`。

> ⚠️ 仓库 README 还给了一条全局安装的写法。本文按仓库内脚本这条路径写，命令和参数以实际仓库为准。

WorkBuddy 属于"自定义指令 / 插件"这一类宿主。把 `.agents/uak-prompt.md` 粘到 WorkBuddy 对应的自定义指令或插件入口即可。入口名称随客户端版本变化，以实际安装的版本为准。这里只保留一份提示词，其他位置只放指针，避免双源漂移。

![WorkBuddy 客户端：顶部切到设计，选择网站设计](https://developer.qcloudimg.com/http-save/yehe-11827391/a6cf9641ba12ff8e563688aa6dc12455.png)

*图 2：WorkBuddy 客户端。顶部切到「设计」，选「网站设计」，在输入框里描述需求。*

接入后的第一条需求可以这样写：

```text
$ui-design-agent 我想做一个浏览器里的 3D 乐高积木工厂。
用户可以选砖、改色、在底板上搭建，作品能存本机、能导出 JSON 和 PNG。
先整理第一版需求，联网找参考，给我方向稿和开发提示词，先不要写代码。
```

最后一句是硬约束。门 A 阶段，代理只能交方向稿，不能起项目、装依赖、下载素材。

## 四、实现：四个工程决策

### 4.1 程序化几何，不引入模型资产

12 种积木全部由代码生成，砖型、颜色、缩略图共用同一套几何定义。收益是包体小、授权干净、缩略图和画布不会对不上；代价是造型只能做到"积木感"，做不到真实注塑件的细节。

### 4.2 离散网格加支撑规则

积木的领域模型很短：

```ts
export const BOARD_SIZE = 24;
export const MAX_HEIGHT = 36;
export const MAX_BRICKS = 400;
export const LAYER_HEIGHT = 0.32;

export interface Brick {
  id: string;
  type: BrickTypeId;
  color: string;
  x: number;
  y: number;
  z: number;
  rotation: 0 | 1 | 2 | 3;
}
```

落点必须在整数网格上。放置前检查目标格是否被占用、下方有没有支撑。斜坡和拱形采用保守包围盒，看起来是斜的或空的，碰撞仍按完整方块计算。

这是一个明确取舍：**不模拟真实结构承重**，只保证搭建规则自洽。真要做承重，需要引入物理引擎和更细的碰撞体，复杂度会上一个量级，收益对这个作品不明显。

### 4.3 状态、渲染、动画分开

React 管状态，Three.js 管渲染，Motion 管过渡。放置确认用短弹簧反馈；开启减少动效时，直接进入最终姿态。

撤销/重做使用 `past / present / future` 三段历史，上限 100 步。所有编辑都改同一个文档结构，避免"画布改了、存档没改"。

### 4.4 本机存档与可导出

存档键为 `brick-workshop.workspace.v1`，存放在当前浏览器。导入文件限制 2 MB，最多保留 20 件作品。JSON 带版本号，读取时逐字段校验；校验失败时不覆盖原存档，只返回错误。

浏览器清缓存、换设备、换访问地址，作品都可能丢。能导出 JSON，至少能把作品带走。

## 五、验收：把状态一个个跑一遍

门 E 的验收不只看一张主界面截图。实际检查项包括：

| 维度 | 检查内容 |
|---|---|
| 布局 | 1440×900、1280×800、768×1024、390×844、320×740，页面级横向溢出 |
| 键盘 | Tab 顺序、焦点恢复、Escape 关闭弹窗 |
| 动效 | 减少动效模式下是否真的停止动画 |
| 异常 | 空状态、导入失败、存档损坏、WebGL 不可用 |
| 触控 | 普通工具与色板等主要触控目标 ≥44px；验收记录为可见按钮约 44px |

结果写进产品 README 和验收记录。截图能证明的，是"这一次检查长这样"，不代表所有生成任务都通过。这个边界必须写清楚。

![乐高积木工厂手机端：积木盒移到下方，画布重新构图](https://developer.qcloudimg.com/http-save/yehe-11827391/35e901479425b629b67d420973695842.png)

*图 3：390×844 手机端。639px 以下积木盒从左侧移到下方。*

测试口径要分开：

- Kit 侧：README 记录 131 项测试，2026-10-08 复核，以 `npm test` 实际输出为准。
- 积木 demo：展示站构建记录里，125 项规则/状态测试通过。
- 构建检查：在 `demo/brick-workshop` 目录下跑 `npm run typecheck` 和 `npm run build`。

两个测试数字不是同一口径，不能混着引用。

![六道门工作流与真实交付记录回放](https://developer.qcloudimg.com/http-save/yehe-11827391/5c6e069947446898b23180c53655d762.png)

*图 4：六道门工作流与真实交付记录回放。*

## 六、四个容易踩的坑

**把"先出一版"当成默认动作。**
门 A、门 B 看起来拖节奏，但跳过之后，方向不对就是全部重写。把"先不要写代码"写进第一句提示词，代理才没有偷跑的空间。

**宿主指令文件不统一。**
Codex 读 `AGENTS.md`，Claude Code 读 `CLAUDE.md`，Cursor 读 `.cursor/rules/`。每换一个宿主就多一份提示词副本，很快对不上。现在的做法是只维护 `.agents/uak-prompt.md`，其他文件只放一行指针。

**手机端不是桌面缩小。**
639px 以下，积木盒从左侧移到下方。展开积木盒会真实压缩画布高度，相机需要重新构图。这个问题在桌面上完全看不出来。

**AI 会写出"看起来合理"的代码。**
动画参数写死、焦点没有恢复、错误态只做 `console.log`，这些代码能跑，也能通过肉眼检查。要靠设计契约和测试兜住。

## 七、边界

| 能做 | 不能做 |
|---|---|
| 把口语需求整理成可确认的方向稿 | 替你做产品决策 |
| 联网找参考，记录来源与授权 | 提供模型服务、账户或付费素材 |
| 用设计契约约束实现 | 替代 Figma 或设计系统 |
| 用真实浏览器留下验收证据 | 保证每个生成任务都通过 |
| 接入 13 个宿主，保持同一套流程 | 替宿主安装 MCP 或 skills |

补充两点：

- 积木 demo 是仓库内的独立案例，源码未单独授予开源许可证。Kit 的自研指令层按 Apache-2.0 发布，上游 skills 各按自己的许可处理，逐条钉版在 `tooling/sources.lock.json`。
- 3D 性能与设备有关。低端机、老浏览器、WebGL 不可用时，页面会给出失败提示和重试入口。

## 八、小结

乐高积木工厂是个小作品：12 种砖、24 × 24 底板、400 块上限。它证明不了多大的事，只证明一件事：AI 写界面可以有一套可检查的流程。这次 1024 提交的是这套流程，积木工厂是它的验收案例。

如果你也在用 AI 写 UI，可以先试三步：

1. 第一句话加"先不要写代码"，只要方向稿。
2. 让代理交素材清单，写清来源和授权。
3. 验收固定查四项：手机宽度、键盘、减少动效、错误态。

作品入口：<https://agent.kcos.club/demos/brick-workshop/>
仓库入口：<https://github.com/muzimu217/ui-design-agent-kit>


AI 生成界面已经不难，难的是证明它"能用"。本文用一个可玩的 3D 乐高积木工厂，拆解 UI Design Agent Kit 的六道门工作流：方向稿、素材清单、原型、设计契约、浏览器验收、调用留痕。文章给出 WorkBuddy 的接入命令、积木网格与支撑规则的具体实现、验收清单，以及这套方法明确管不到的地方。适合正在用 AI 写前端、希望把"看起来能跑"变成"可以检查"的开发者。

六道门与浏览器验收：用 UI Design Agent Kit 做一个 3D 乐高积木工厂

人工智能

UIDesignAgentKit通过六道门工作流，将AI生成界面从"看起来能跑"升级为"可检查、可验收"。以3D乐高积木工厂为案例，展示方向稿、素材清单、原型、设计契约、浏览器验收、调用留痕的全流程落地，配套接入命令、实现规则与验收清单，适合AI前端开发者参考。

代码解释

WorkBuddy 

OpenClaw

GitHub

Agent

ReAct 

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

六道门与浏览器验收：用 UI Design Agent Kit 做一个 3D 乐高积木工厂-腾讯云开发者社区-腾讯云

六道门与浏览器验收：用 UI Design Agent Kit 做一个 3D 乐高积木工厂

六道门与浏览器验收：用 UI Design Agent Kit 做一个 3D 乐高积木工厂

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐