SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场workflow-spec-to-mockup

workflow-spec-to-mockup

设计与创作

查看项目

更新于 11-04 21:59

技能介绍

用途

该技能是一个工作流技能，目标是将一份包含界面意图的规范（UI-bearing canonical spec）转化为一个经过评审、可交互、多视图的 HTML 原型应用（mockup）。每个规范生成一个原型；如果用户选择跳过原型，则不生成。整个工作流在计划工作或生产代码之前停止，不产出任务、故事、计划或实现代码。

适用场景：产品负责人、业务分析师或设计师希望在排期或构建之前，点击浏览一个带有界面的规范。相邻路线包括：原始想法 → workflow-planned-work --mode=idea-to-spec；规范加计划工作 → workflow-planned-work（spec-to-tasks）；指定行为到构建 → workflow-implement-spec；纯后端规范 → 不适用原型。

主要能力与流程

工作流按以下顺序执行，并带有质量门控：

  1. 原型范围门控（第一步）：在读取、分析或调用其他技能之前，先运行 work-item --mode=mockup 的第 0 步，询问用户是否要生成原型。答案在整个运行中记录一次，后续步骤复用。如果用户跳过，则记录 Mockup: SKIPPED by user，并继续执行设计规范、设计评审和 UI 评审门控（标记为 N/A，因为没有原型可评审），最后收尾。
  2. 分类/路由检查：确认规范路径存在；检查规范是否携带界面意图层（视图清单、信息优先级、容器角色、导航图、可观察状态、每个故事的动作流）。缺少则在规范上运行 spec [mode=update]，或在设计规范中推断并标记 INFERRED。纯后端规范则停止。
  3. 设计规范（$design-spec，核心）：生成与技术无关的 UI 规范，其中第一步（Step 0a）写入 Journey Report（UX-1）和设计权威记录（UX-2）。旅程优先：任何线框图、方向草稿、令牌表或原型 HTML 都必须在 Journey Report 之后。
  4. 设计评审（$work-item --mode=review --type=design，门控）：评审设计规范，要求 PASS 或 WARN，包括 UI/UX 原则通过、M1–M7 门控和 design_spec: 回链；发现的问题修复后重新评审。
  5. 原型构建与探索（$work-item --mode=mockup --explore，核心）：复用第 0 步的答案，生成 N 个方向草稿，记录用户选择（或记录豁免/自动选择原因），然后构建完整的多视图原型应用，要求每个视图、导航边、组件和状态（空、加载、错误优先）齐全，并连通每个主要旅程的完整演示。该步骤还负责渲染每个视图的证据（html-export --to=png，必需），并设置规范的 mockup: 前置元数据链接。
  6. UI 评审（$ui-design --mode=review，门控）：对最终原型文件进行评审，走查每个主要旅程（UX-8），检查 UI-* / DD-* / CL-* 发现，修复后重新评审；要求无未解决 FAIL。
  7. 收尾（$workflow-end，门控）：检查所有结果门控，打印回顾。$watzup 为可选，仅在其注册条件满足时运行。

使用方式

通过技能调用方式触发，例如在支持的环境中调用 $skill-name 加载并执行。工作流开始时需要先读取注册表 workflows.workflow-spec-to-mockup，调用 $start-workflow workflow-spec-to-mockup 解析模式、预动作和指纹。然后按阶段创建待办事项（todo），每个阶段一个 todo，按顺序列出该阶段的所有出现，包括条件/可选出现，保留出现 ID、角色和屏障组。使用原生 todo 工具或等效的持久账本。

在 Codex 兼容环境中：调用 $skill-name: 加载注册的 .agents/skills/<name>/SKILL.md 并使用 Codex 工具执行；无需单独的 Skill 工具或 Claude 模式切换。作者编写 .claude/**；镜像自动生成。

主要命令示例（资料中出现的）：$design-spec、$work-item --mode=review --type=design --fix-loop、$work-item --mode=mockup --explore、$ui-design --mode=review、$workflow-end、$watzup。

质量门控与证据

必须满足的门控包括：

  • Journey Report 优先（UX-1）：设计规范的第 0a 节 Journey Report 先于所有其他设计输出；推断的关键声明需与用户确认，或记录为 INFERRED — unconfirmed。
  • 设计权威读取（UX-2）：在设计规范头部记录。
  • 设计规范评审收敛（review-converged）：PASS 或 WARN，发现修复并重新评审。
  • 方向选择：在 tmp/design/<run>/ 下渲染 N 个主旅程关键视图的草稿，并在 direction-approved.md 中记录用户原话选择（Selection: USER）、单选项、自动选择（含原因）或豁免。用户可被询问时绝不自动选择；“继续”“看起来不错”或沉默不算选择。
  • 可发布的多视图原型应用：每个规范一个自包含原型，所有必需视图、导航边、组件和状态齐全，每个主要旅程连通完整演示；静态或断开的屏幕不合格。
  • 渲染证据：对最终原型的旅程视图运行 html-export --to=png；退出码 0 = 每视图渲染证据；4 = 修复并重新渲染；3 = 不可验证并给出设置指引，绝不安装；1/2 或其他 = 工具故障，不可验证。只有运行报告 report.json 的 files[] 中列出的文件才算。
  • 旅程走查（UX-8）：$ui-design --mode=review 的走查日志和可追溯性矩阵无未服务步骤、无孤立元素，发现修复并重新评审，UI/UX 门控报告无未解决 FAIL。
  • 规范链接：规范的伴随工件前置元数据（design_spec: / mockup:）指向设计规范和最终原型；仅前置元数据，规范正文不动。
  • 运行关闭（run-closed）：$workflow-end 检查所有结果门控（仅顶层运行）。

限制与注意事项

  • 不产出任务、故事、计划或生产代码。
  • 纯后端规范不适用原型，应停止并说明原因。
  • 一个规范一次运行；多个规范则每个规范一个原型；3 个及以上规范时，设计规范可每个规范一个子代理，但探索选择仍由用户逐个进行。
  • 用户可被询问时，方向选择绝不能自动回答或并行化；自动选择仅限记录的原型所有者路径：无提问工具、草稿无法展示、提问工具出错。
  • 评审循环：第 1 轮零开放发现退出（LOW 可推迟）；第 2 轮零 CRITICAL/HIGH/MEDIUM，LOW 记录为推迟；最多 3 轮评审；无进展时通过询问用户升级。
  • 工件放置：草稿、渲染、产品事实和运行笔记放在 tmp/design/<run>/ 下（<run> = YYMMDD-HHmm-<slug>）；设计规范放在团队工件根（默认 team-artifacts/，可由 docs/project-config.json 的 docsRoots.teamArtifacts.path 覆盖）；最终原型放在 work-item --mode=mockup 规范源输出路径，即同一团队工件根下的 design-specs/——绝不能放在业务规范根内，那里只存放规范。
  • 工作流门控固定；其他步骤可在记录原因和证据后灵活调整顺序。
  • 协议指南按条件应用：设计独特性门控（DD-1 到 DD-8）、增量持久化、会话目标账本、子代理返回契约等。

交接内容

关闭时交接：规范路径、设计规范路径、最终原型路径、所选方向及其 Selection: 行（引自 direction-approved.md）或 Mockup: SKIPPED by user、每个主要旅程的走查结论、渲染证据或 NOT VERIFIABLE、低于 80% 置信度的开放问题，以及下一路线——workflow-planned-work（spec-to-tasks）用于计划工作，或 workflow-implement-spec 用于构建。