UI Design Agent Kit
语言说明（R106-05）：本 README 为完整版（含能力配置、素材检索、贡献与社区节）；
README.en.md 是面向研究者的精简英文版，仅保留方法论、证据与论文入口。
简体中文 | English
专门为 UI 设计而设：从口语需求到可验证界面的项目级 AI 设计工作流。
整理需求 · 查找素材 · 确认设计 · 实现交互 · 浏览器验收。
不是通用编码助手，也不是应用脚手架——技能路由、六道门与验收纪律全部围绕"界面质量"这一件事闭环。
快速开始 ·
线上展厅 ·
产品案例 ·
使用说明 ·
交付标准
工作流成果展厅：展示已收录案例、入口与验证记录，不充当可执行 AI 客户端。
工作流把控：一条有确认节点的 UI 设计与实现流程——真实交付记录逐步回放（睿耳案例 18 步骤），每个节点有状态、有产物、有证据路径，未过门不前进。
产品介绍视频（2 分 45 秒）：由仓库 video-production/ 的 Remotion + three.js 管线渲染，先学最好的界面，再交付有证据的产品。
[!IMPORTANT]
这个仓库维护的是一个 UI 设计智能体工作流：通过 AI 调用技能、编排工具，帮人类设计更好的 UI——不是产品运行时，也不是研究项目本体。
- 是：智能体指令层（23 技能 + 六道门确认工作流）、验证纪律（五级证据等级、131 项测试（2026-10-08 复核，以 npm test 实际输出为准）、浏览器实测）、可迁移提示词工厂、12 个有证据的线上案例。
- 不是：独立 AI 客户端、运行时引擎、Figma 同步工具（设计契约走 designContracts 钉版通道）、IDE 替代品。
- 研究线（人工监督研究 RQ-A、测量仪器与语料）已独立建仓，不在本仓目录下（2026-10-02 裁定）——定位与身份时间线见 docs/identity-and-direction.md。
demo 与 showcase 是已明确收录的教学与验收案例。案例截图证明对应页面的当次检查结果，不代表所有生成任务都已通过验收；主工具包不提供模型服务、账户、付费素材或后台业务接口。
接入 13 个主流 AI 宿主（一层转换）
本工作流不绑定单一宿主：Codex、Claude Code、Cursor、Gemini CLI、GitHub Copilot、Windsurf、Cline、OpenCode、ZCode、DeepSeek Harness、OpenClaw、WorkBuddy、Hermes 都走同一条三层接入——宿主怎么换，工作流不变。每家的真实官方图标、逐条命令与特化步骤，见线上展厅的接入工作台（agent.kcos.club，本地预览：showcase/products/）。
-
装 Kit（一次性，任意目录；本仓要求 Node ≥ 20.18.1）：
npm install -g github:muzimu217/ui-design-agent-kit
-
进你的项目，一条命令接入（幂等，可重复执行）：
uak-init # 自动探测宿主：.codex/ → codex；CLAUDE.md → claude；否则 other
uak-init --host codex # 或显式指定宿主
自动完成：lean 提示词导出至目标项目 .agents/uak-prompt.md → AGENTS.md 幂等接入区块 → MCP 配置步骤清单（不替你改宿主配置）。支持 --dry-run 预览与 --check 自检。
-
按宿主特化最后一步（只有一步，且只是"指个路"）：各家指令文件名不同——CLAUDE.md、.cursor/rules/、GEMINI.md、.github/copilot-instructions.md 等，都只放一行指针指向 AGENTS.md 或 .agents/uak-prompt.md，不复制第二份内容（避免双源漂移）。
接入后在该宿主里用一句口语需求开工即可（示例见 docs/usage.md）。
宿主仍需自备模型服务、MCP 配置与技能目录——缺什么，接入说明会列清楚，不会假装已连接。
首任务建议说「Express」：一屏方向稿 + 有界预授权，10 分钟拿到第一张验收截图。
决策背景见 docs/adr/0003-universal-host-compat.md；只要单文件提示词、不要落盘接入时，仍可用 npm run prompt:build 产出完整版/lean 版导出。
画布工作台（流水线可视化）
六道门流水线本身也有可视化视图——npm run canvas:build 生成三件离线自包含页（离线可开、零依赖）：
- 门径画布：六阶段四泳道流水线，门状态三色、证据嵌入、搜索/缩放/回放；
- 需求解析链路：原始口语 → 解析摘要 → 理解验证 → 六步决策抽屉，黑盒步骤自动标黄；
- 工作台入口：三卡入口 + 门径状态 + 产物墙（排序视图+六维完成度徽章）。
验收命令 npm run canvas:check（playwright 实测：WCAG 对比度 / 键盘 Tab 序列 / 17 档宽度横向溢出扫描 / 别名可见性 / console 回执）。线上展厅的「画布工作台」页签即这三件产物的构建时快照。规划详见 docs/canvas-workbench-plan.md。
视频线的音效打点表同样可验：npm run sfx:check 校验 video-production/src/sfx-cues.json 的每个音效点是否落在真实场景边界、轨道声明是否有效、密度是否超标——知识卡里的音效参数由此变成可执行断言，而不是散文描述。
为什么需要它
大多数 UI 生成把需求、设计决策和验收证据混在一段对话里。
UI Design Agent Kit 把它们拆成可确认的流程：
🧭 从口语到可执行方案
把一句日常描述整理成需求摘要、第一版范围、关键问题和完整开发提示词。
用户确认目标后，再进入实现阶段。
🔍 素材有证据
按用途检索官网、文档、素材库和参考案例，记录候选来源、使用位置和授权边界。
不可达、低分或未验证的来源不会自动进入实现。
✨ 设计有契约
把 Mission、语义 token、Do/Don't 规则、动效参数和响应式约束写成可检查契约。
界面不是只交一段好看的感觉。
🧪 交付有证据
用真实浏览器检查桌面、移动、键盘、错误态和减少动效模式。
结果、已知问题和限制写入产品 README，而不是只留下代码。
从一句话到可验收界面
-
描述需求
用日常语言说明产品、用户、核心流程和限制；不确定的部分交给可填写模板。
-
联网调研
查找相似产品、官方文档、素材来源和界面参考，先确认方向再动手。
-
冻结计划
输出信息架构、视觉方向、组件清单、动效规则、技术栈和验收方法，等待确认。
-
实现与检查
按契约实现界面，用浏览器采集截图，修复 P0/P1 问题并保留证据。
-
写产品 README
记录功能、截图、运行方法、限制、素材来源和验证结果，让成果可被复用。
在本项目的 AI 对话中可以直接开始：
$ui-design-agent 我想把采购申请集中起来，看谁还没处理。先整理第一版需求，由你联网找参考，再给我完整开发提示词，先不要开发。
不知道如何开头时，使用可填写模板。
不只是生成一屏 UI
产品案例
每个产品 README 都独立记录自己的界面、运行方法和边界。
| 产品 | 类型 | 文档 |
|---|
| 库存运营台 | 库存列表与详情，演示数据 | 查看 |
| Tempo 今日节奏 | 本机任务管理与专注计时 | 查看 |
| 积木小工坊 | 3D 自由拼搭与小挑战 | 查看 |
| NODEGRID | 虚构云节点网络可视化 | 查看 |
| 地铁跑酷（展厅名：地铁疾行） | 三车道 3D 跑酷 | 查看 |
| FORMA One | 虚构手机配置与购买路径演示 | 查看 |
| 睿耳 RuiEar | AI 耳机概念产品页，3D 配色切换与开合盖动画 | 查看 |
| 曜石 12 Pro | 双机型配置与意向清单演示 | 查看 |
| 曜时 X1 | 虚构智能腕表展示 | 查看 |
| 一舟札记 | 虚构作者与文章阅读演示 | 查看 |
| 竹与墨 | 水墨风技术博客演示 | 查看 |
生成的产品默认放在仓库外的独立工作区；这里只保留已明确收录的案例。根目录不导入产品运行代码。
提示词入口
需要迁移到其他智能体时，生成单文件提示词：
npm ci --ignore-scripts
npm run prompt:build
产物位于 output/ui-design-agent.system.md。单独导入提示词不会自动安装其他平台的 MCP 或 skills；目标环境仍需接入工具，缺失时按提示词中的替代流程执行。
工作流架构
flowchart TB
Request["口语需求 / 模板"]
Scout["联网调研<br/>产品参考 · 素材 · 文档"]
Plan["冻结计划<br/>范围 · 设计契约 · 验收"]
Build["界面实现<br/>HTML/CSS/JS 或项目技术栈"]
Verify["浏览器验证<br/>桌面 · 移动 · 键盘 · 动效"]
Delivery["产品 README<br/>截图 · 限制 · 来源"]
Request --> Scout
Scout --> Plan
Plan -->|用户确认| Build
Build --> Verify
Verify -->|发现问题| Build
Verify -->|通过| Delivery
主提示词保持单一维护源，视频流程由 Remotion 提示词承接，工具配置集中在 .codex/config.toml。
快速开始
需要 Node.js 20.18.1+、npm，以及一个能读取项目指令的 AI 宿主。
git clone https://github.com/muzimu217/ui-design-agent-kit.git
cd ui-design-agent-kit
npm ci --ignore-scripts
npm run verify
npm test
给现有项目接入（uak-init，推荐）
已经有自己的项目？在目标项目根运行：
uak-init # 全局安装后直接可用（装法见上"接入 13 个主流 AI 宿主"）
未全局安装时用仓库路径直跑：node <uak 仓库路径>/scripts/uak-init.mjs --uak <uak 仓库路径>。
自动完成：宿主探测（codex/claude/other）→ lean 提示词导出至目标项目
.agents/uak-prompt.md → AGENTS.md 幂等标记段 → MCP 配置步骤清单
（不替你改宿主配置）。支持 --dry-run 预览与 --check 自检。首个任务建议走 Express 档：
首轮说「Express」，一屏方向稿 + 有界预授权，10 分钟拿到第一张验收截图。
宿主支持矩阵
13 个宿主的接线方式、真实官方图标与逐家特化步骤，见接入工作台
（线上展厅 agent.kcos.club，本地：showcase/products/）。按接线类别速览：
| 接线类别 | 宿主 | 说明 |
|---|
| AGENTS.md 原生 | Codex CLI · OpenCode · ZCode | uak-init 一条命令，接入区块直接生效 |
| 指针文件 | Claude Code · Gemini CLI · GitHub Copilot · Windsurf · Cline | uak-init 后在各家规则/指引文件里挂一行指针 |
| 规则注入 | Cursor | uak-init 后把 .agents/uak-prompt.md 存为 .cursor/rules/uak.mdc |
| 自定义指令 / 插件 | DeepSeek Harness · OpenClaw · WorkBuddy · Hermes | 把 .agents/uak-prompt.md 按各家机制粘入对应位置 |
第一次使用会发生什么
首轮不会直接写代码：agent 会先整理需求、检索真实参考素材，然后呈交一份
"方向稿"（布局关系 + 参考来源 + 三个风格旋钮）等你确认；你确认后才进入
原型与实现，每轮产出都附浏览器实测证据。想要更轻的起步，直接说"先出一版
再改"也可——协议内有微修通道与显式弃权条款。
许可：自研指令层按 Apache-2.0 发布（根 LICENSE）；上游 vendored
skills 各自带许可，逐条钉版见
来源锁定与第三方声明。
然后在项目会话中描述需求。联网、浏览器和生图能力取决于当前宿主的实际工具，不因安装指令而自动获得。
更多常见问题（宿主/MCP 示例/为什么先出方向稿/评测可信度）见 FAQ。
验证
安装完成后依次运行，勿让 npm ci 与测试同时执行：
npm run verify
npm test
npm run doctor
npm run doctor:mcp
doctor 只检查本地配置；doctor:mcp 会访问公开服务并启动配置中的本地 MCP，进行只读调用，不登录付费服务。它不证明某个实际应用已通过视觉验收。
评测场景覆盖产品类型、动效参数、不可用工具、减少动效、长列表和视频转场。它们是可重复执行的行为评测规范；单元测试只检查结构，不代表已经逐场景运行了生成任务。最新批次的真实执行报告（覆盖率、通过率与失败分析）见评测扩量报告。
能力配置
| 能力 | 本项目配置 |
|---|
| Motion 官方文档、CSS 弹簧生成 | 已配置公开 MCP |
| Context7 文档检索 | 已配置公开 MCP |
| shadcn 组件检索 | 固定版本本地 MCP |
| Playwright 浏览器操作 | 固定版本、隔离无头会话 |
| uak-design-system、uak-visual-critique、uak-design-thinking、jiejoe-design + motion / GSAP×8 / Remotion×6 官方 skills | 23 个已安装项目级 skill（2026-10-16 anatomy 整包引入）；三个 uak-* 为 2026-09-30 本地化改名（原 ui-ux-pro-max / impeccable / Emil 三技能），改编范围见 THIRD_PARTY_NOTICES.md |
| Remotion | 6 个官方 skills + 本地视频编排提示词；不安装已废弃的官方 MCP |
| Three.js / R3F / Rapier | 按需运行库路由与验收规范；不在 kit 根目录安装运行库 |
| Blender 建模与 GLB 导出 | 可选本地 CLI / 第三方 Blender MCP 路由；未安装或配置 Blender MCP |
| Motion+、Figma | 配置已预留，默认关闭，未进行登录 |
| Google Stitch（UI 原型生成） | 可选 MCP，默认关闭；API key 走环境变量 STITCH_API_KEY，不内联；免费额度与调用结果需逐次验证 |
项目配置位于 .codex/config.toml，skill 位于 .agents/skills。没有改动全局模型、权限或 MCP 配置，也没有启用自动 hooks。
素材检索
素材检索遵循候选排序规范：
- 明确用途：先确定素材在界面中的位置、尺寸、情感目标和授权边界。
- 按优先级检索：从官网、官方文档、开放素材库和高可信来源开始。
- 少量候选：保留足够比较的候选，而不是无边界堆链接。
- 结构化评分：把 MCP 或浏览器结果交给
npm run material:rank -- --input <candidate-json>。
- 保留证据：记录来源、访问时间、用途和风险；不可达或低分来源进入 secondary 区。
长期目标、五步迭代循环与定时任务机制见目标与迭代机制，逐轮记录见迭代日志，思维链质量监控见质量监控。
Contributing
Issues、bug 报告、功能建议、文档改进和 Pull Request 都欢迎。
较大改动建议先开 issue 对齐范围。修改仓库指令时，请从 AGENTS.md 和主提示词开始，避免创建第二份长系统提示词。
报告问题 ·
查看开放 Issues
社区
本项目已获得 LINUX DO 社区收录与认可，感谢社区的支持与讨论。
访问 LINUX DO 社区
许可
自研指令层按 Apache-2.0 发布（根 LICENSE）。上游 vendored skills
保留各自许可，逐条钉版（含 revision 与修改记录）见来源锁定与第三方声明；再分发条款以各条目为准。
从口语需求开始。把界面和证据一起交付。
快速开始
需求 · 设计 · 实现 · 验收
