UISpec Generator

作者（？）碎碎念[必看]

这是一个高度依赖Deepseek v4 Flash进行开发的项目，从需求书、开发计划书到实际的执行和修改——甚至这个README的主体部分——几乎全部由AI完成，我在里面只起到了一个灵感提供者的作用——甚至不是思路提供者，因为我对前端和后端都不熟，谈何思路呢。

因此，如果您在这个项目里发现各种逻辑混乱、架构不稳、或者其他什么AI屎山——请原谅，这毕竟只是一个对于写程序有那么一点点兴趣的文科生为了满足自己粗劣的“想写点有用的东西”的愿望，从而借助AI工具搞出来的自己也不一定看得懂的黑箱罢了。

虽然这么说，但我也尽力验证了它的基本功能是能跑的通的——写一个.uispec文件，告诉AI这个文件的地址，让它帮你生成一个.html文件以做预览，从而确认文件本身能让AI理解如何布局游戏UI。这也是我一开始想要做的：一个给帮我做游戏的Agent用来理解我脑子里飞着的那些UI布局的工具。至少目前看来，这个功能是实现了。

以上。再次请求您的原谅。即使要喷，也请轻喷。虽然做得这么烂的东西，真的有人会正眼看一下吗，更不用说喷了……

---

规格驱动的 UI 原型生成插件，运行于 DeepSeek Harness（DSH）。

用一份 YAML 描述界面（设计令牌、布局、组件、交互），插件完成 解析 → 校验 → LLM 生成 → 落盘 全流程，输出自包含的 HTML 原型：

schema_version: "1.0"
ui:
  name: inventory
  style_tokens:
    colors:
      background: "#1a120b"
      accent: "#d4af37"
  layout:
    type: vertical
    regions:
      title: { component: title_label }
  components:
    title_label:
      type: text
      text: "背包"

---

功能简介

能力	说明	触发方式
YAML 解析	自写子集解析器，语法错误带行列号定位	/uispec parse <file>
校验	结构/类型/颜色/引用完整性检查，错误聚合输出，引用问题为警告不阻断	/uispec validate <file>
LLM 生成	流式调用（思考统计、token 用量、截断检测），提示词模板可配置	/uispec llm <file>
一键生成	完整流水线并写入 <名称>_preview.html	/uispec generate <file>
模型工具	Agent 可直接调用，无需人工输入命令	模型工具 uispec_generate
文件监听	轮询 + 防抖，.uispec 变更自动重新生成	/uispec watch <file|dir>
诊断	展示路径解析基准与目录条目，排查"找不到文件"	/uispec diag

特点：

• 零 npm 运行时依赖：解析器与校验器为纯 JS 自写（约 800 行），错误信息面向使用者；
• 设计令牌（颜色/字体/间距/圆角）自动映射为 CSS 变量，生成结果稳定可控；
• 输出为可再生构建产物，命名规则 inventory.uispec → inventory_preview.html。

UISpec 语法简介

顶层结构

schema_version: "1.0"   # 语法版本（必填）
ui:
  name: string           # 界面名称（必填）
  description: string    # 可选说明
  style_tokens: {}       # 全局设计令牌（colors/fonts/spacing/corner_radius 等）
  layout: {}             # 布局树：vertical | horizontal | grid，regions 嵌套
  components: {}         # 组件定义：button / panel / text / image / grid / grid_cell
  interactions: {}       # 可选交互描述

支持的 YAML 子集（v1.0）

支持：块映射、块序列（- item）、单行 flow 映射/序列（{ a: b }、[x, y]）、引号字符串、裸标量（字符串/整数/小数/布尔/null）、行内与整行注释、CRLF。

不支持（报明确错误）：跨行 flow、多行标量（|、>）、锚点/别名、标签（!!str）、文档分隔符（---）、Tab 缩进。

注意：# 前有空格即视为注释，十六进制颜色必须加引号（如 "#d4af37"），与标准 YAML 一致。

校验规则

• 硬错误（阻止生成）：schema_version 缺失或非 "1.0"；ui.name 非空；layout.type 非法；未知组件类型；颜色非 #hex/CSS 关键字/已定义令牌；size 格式错误。
• 警告（不阻止）：布局/子组件/网格引用未定义组件；交互引用未定义目标；已定义但未引用的颜色令牌。

完整示例见 samples/inventory.uispec 与 samples/shop.uispec。

文件架构

uispec_plugin/
├── deploy/                     # 部署插件（装入 DSH profile 的文件）
│   ├── index.js                # 常规 Cordis 插件：命令/工具/监听/生成全流程
│   ├── parser.js               # 解析器模块副本（src 规范源的带导出版）
│   ├── validator.js            # 校验器模块副本
│   └── package.json            # 部署包清单（type: module）
├── src/                        # 规范源文件（可独立测试）
│   ├── yamlSubsetParser.js     # YAML 子集解析器（含行列号与字段位置追踪）
│   └── uispecValidator.js      # 校验器（错误聚合 + 字段路径 + 行列号）
├── tests/                      # Node 断言测试（零依赖）
│   ├── parser.test.js          # 25 项
│   └── validator.test.js       # 18 项
├── samples/                    # 示例：inventory / shop（合法）、broken / invalid（错误演示）
├── ProgressFiles/              # 开发计划与语法基线文档
├── README.md
└── LICENSE

安装方式

环境要求：DeepSeek Harness（web profile 形态）运行中的部署；LLM 走 Harness 的模型路由（无需自备 API Key）。

部署级安装（推荐，所有会话可用、重启不丢）

1. 将 deploy/ 下的四个文件复制到 profile 插件目录：

   # Windows 示例：web profile 位于 %USERPROFILE%\.dsh\profiles\web\
   mkdir %USERPROFILE%\.dsh\profiles\web\uispec-plugin
   copy deploy\index.js deploy\parser.js deploy\validator.js deploy\package.json ^
     %USERPROFILE%\.dsh\profiles\web\uispec-plugin\
   

2. 在 %USERPROFILE%\.dsh\profiles\web\cordis.patch.yml 追加补丁行：

   - insert:
       - id: uispec-generator
         name: './uispec-plugin/index.js'
   

3. 重启 dsh web，全部会话即可使用 /uispec 命令与 uispec_generate 模型工具。

卸载：删除补丁行与 uispec-plugin/ 目录，重启。

开发方式（可选）

• 在会话中通过 DSH 的动态插件工具（cordis_define / cordis_run）加载，适合开发迭代
• 动态插件随进程重启消失。

使用方式

/uispec help                      显示帮助
/uispec parse <file.uispec>       解析并报告结构摘要
/uispec validate <file.uispec>    校验（0 错误才允许生成）
/uispec llm <file.uispec>         生成并预览原始文本
/uispec generate <file.uispec>    完整流程：解析→校验→LLM→提取→写文件
/uispec watch <file|dir>          监听变更自动重新生成
/uispec watch off                 停止监听
/uispec diag                      路径解析诊断

• 路径规则：相对路径基于 DSH 的 sandboxPolicy.workspaceRoot 解析；
• 模型工具：uispec_generate(file) —— 对 Agent 说"生成 xxx.uispec 的预览"即可自动触发；
• 输出：默认写入 outputDir（project.config.json 配置），目录不存在时回退到源文件同目录；输出为可再生产物，建议加入 .gitignore。

配置（project.config.json，可选）

放在 workspaceRoot 下，uispec 段覆盖默认值：

{
  "uispec": {
    "provider": "deepseek",
    "model": "deepseek-chat",
    "maxTokens": 32768,
    "outputDir": "output",
    "watchIntervalMs": 1000,
    "debounceMs": 500,
    "promptTemplate": "你是一个 UI 生成器。根据用户提供的 UISpec 数据，生成一个自包含的 HTML/CSS 原型。要求：使用 CSS Grid/Flex 布局，保留所有组件和样式。只输出 HTML 代码，不要 Markdown 围栏。"
  }
}

配置项	默认	说明
provider / model	未设置 → 部署默认模型	显式指定 LLM 路由；思考模型占用输出预算时建议改用 deepseek-chat
maxTokens	32768	输出上限；过小会导致"思考吞没输出"（0 文本或被截断）
outputDir	output	生成目录；不存在时回退到源文件同目录
watchIntervalMs / debounceMs	1000 / 500	监听轮询间隔与防抖
promptTemplate	内置模板	生成质量不满意时可覆盖

故障排查

现象	处理
找不到文件	路径基准是 workspaceRoot；用 /uispec diag 查看实际基准与目录条目
LLM 返回 0 文本 / 输出被截断	思考模型占满 maxTokens：调大 maxTokens 或配置非思考模型
生成文件带 ```html 围栏	提取器自动剥离；异常时可自定义 promptTemplate
watch 不触发	变更检测基于 fs version 令牌；/uispec watch 查看监听状态

已知限制（v1.0）

• 单文件模式：无跨文件引用、无共享令牌库；
• 输出仅 HTML（.tsx / .svg 为后续预留）；
• 配置仅支持 workspaceRoot 下的 project.config.json。

开发与测试

node tests/parser.test.js     # 25 项：合法示例 + 8 个语法错误行列号 + 位置追踪
node tests/validator.test.js  # 18 项：全部校验规则 + 错误聚合 + 行列号

src/ 下的规范源文件是解析器/校验器的唯一事实来源，deploy/ 中的模块副本与其保持同步。

许可

MIT