GemDesign 高保真原型

它解决什么问题

拿到需求文档后，工程师往往要手写一整页 HTML：结构、样式、布局全靠手调，没有规范约束，保存到协作平台也没有统一入口；改一版就要重新走一遍，预览和生成脱节。GemDesign Skill 把这件事压缩成一条流水线：你只负责描述页面，技能负责按规范产出 HTML、校验、保存，并立刻在本地服务器上看到流式渲染结果。

它如何工作

技能的核心是一个串行的 CLI 工作流：

• 生成：按 GemDesign Page Spec 产出高保真 HTML，再经 CLI 校验后才允许保存；
• 保存：通过 gemdesign CLI 将页面写入平台，支持新建、修改、查看已有页面；
• 预览：CLI 内置的本地服务器（默认 4056 端口，被占则顺延）对正在生成的 HTML 做实时流式预览，配合 fileWatcher 监听 .html 变更。

在开始任何页面工作之前，技能强制按顺序完成三道硬门禁：

1. 验证并安装 CLI，确认版本是最新；
2. 验证登录：执行 gemdesign auth whoami 拿到用户信息，拿不到令牌就直接停下来，绝不允许先写 HTML；
3. 清理环境：先清理上次会话遗留的空项目目录，再配置 htmlWorkdir（如 gemdesign server workdir --path ./output）。这两个操作的顺序不可颠倒——清理逻辑会删除没有项目子目录的空工作目录，先配置再清理会把刚建好的目录直接删掉，导致后续 app 创建跳过本地目录、服务器拒绝启动，出现“页面已生成但画布空白”的问题。

进入工作流后，本地服务器的启动时机同样有约束：必须在 app 已创建或复用（gemdesign app create / gemdesign app use）之后才能启动，因为服务器是从 app 派生出的项目子目录里提供页面；而且每次启动前必须先 gemdesign server stop 终止残留进程，并主动打开浏览器——页面要在生成的同时被看到，这是不可协商的步骤。

适用边界与注意点

• 需要 GemDesign 平台的账号和令牌，令牌从平台「个人中心」获取；未登录时技能不会做任何页面生成工作。
• 页面形态以 GemDesign Page Spec 为准，不是任意 HTML 都能落盘保存。
• 批量生成适合有完整需求文档的场景；零散的单点修改同样支持。
• 服务进程、端口和浏览器预览都依赖可用的本地环境，远程无浏览器环境下预览环节会受阻。