ui-mockup

通过迭代设计和实现脚手架，为音频插件创建 WebView UI 模型图。

<quick_start>

1. 检查是否存在美学库（阶段 0）
2. 通过分层问题收集需求（阶段 1-3）
3. 调用 ui-design-agent 生成模型图
4. 持续迭代，直到用户批准
5. 生成实现文件 </quick_start>

生成 2 个设计文件，以便快速迭代 - `v[N]-ui.yaml` - 机器可读的设计规范 - `v[N]-ui-test.html` - 可在浏览器中测试的模型图 在用户通过阶段 5.5 的决策菜单批准设计之前，禁止进入阶段 B 仅在阶段 A 获得批准后生成 5 个实现文件 - `v[N]-ui.html` - 生产用 HTML - `v[N]-PluginEditor.h` - C++ 头文件样板 - `v[N]-PluginEditor.cpp` - C++ 实现样板 - `v[N]-CMakeLists.txt` - WebView 构建配置 - `v[N]-integration-checklist.md` - 实现步骤 plugins/[PluginName]/.ideas/mockups/

<context_detection> <standalone_mode>

• 不存在 .continue-here.md 文件
• 独立生成模型图
• 跳过状态更新 </standalone_mode>

<workflow_mode>

• 文件 plugins/[PluginName]/.continue-here.md 存在且包含 current_stage 字段
• 每个阶段结束后更新工作流状态 </workflow_mode>

检查 .continue-here.md 是否存在，以确定运行模式。如果存在，则更新状态文件。如果不存在，则跳过状态更新。 </context_detection>

检查 `.claude/aesthetics/manifest.json` 是否存在。如果存在，使用 jq 统计美学方案数量。 美学库中找到 {N} 个已保存的美学方案。

你希望如何开始 UI 设计？

1. 从美学模板开始 - 应用已保存的视觉系统
2. 从头开始 - 创建自定义设计
3. 列出所有美学方案 - 决定前浏览库

选择（1-3）：_

- 选项 1：显示清单中的美学方案及其元数据（名称、风格、颜色、来源）。调用 ui-template-library 技能并执行 "apply" 操作。跳转到阶段 4，使用生成的模型图。 - 选项 2：继续到阶段 1（加载上下文）。 - 选项 3：调用 ui-template-library 技能并执行 "list" 操作，显示预览，然后返回菜单。 - 如果没有美学方案：直接跳转到阶段 1。

请参阅 references/aesthetic-integration.md，了解完整的集成详情。

从创意简报中加载上下文并提取需求。 请参阅 `references/phase-details.md`，了解提取流程。 请参阅 `references/context-extraction.md#example-extracting-from-creative-brief`，查看示例。 根据创意简报的内容（UI 细节丰富、有限或为空）调整初始提示词。 请参阅 `references/phase-details.md`，了解提示词模板。 分析第 1 层（关键）、第 2 层（视觉）和第 3 层（润色）需求中的缺口。 请参阅 `references/phase-details.md`，了解各层级的定义。 请参阅 `references/design-questions.md`，了解问题模板。 在询问用户之前，计算建议的窗口尺寸。 请参阅 `references/phase-details.md`，了解计算步骤。 请参阅 `references/layout-validation.md` 第 2 节，查看公式。 根据已发现的缺口，使用 AskUserQuestion 生成恰好 4 个问题。 请参阅 `references/phase-details.md`，了解规则和问题格式。 请参阅 `references/design-questions.md#example-question-batches`，查看模板。 使用 AskUserQuestion 呈现决策选项：定稿、继续提问或补充上下文。 根据选择跳转到阶段 4、返回阶段 2，或收集自由文本。 请参阅 `references/phase-details.md`，了解菜单格式和路由方式。 通过 Task 工具调用 ui-design-agent，生成 YAML 和测试 HTML。

在调用提示词中包含：

• 收集到的所有需求（布局、控件、颜色等）
• 质量要求：“设计必须达到售价 50–200 美元的商业音频插件水准——决策要经过精心考量，不能采用默认设置”

调用摘要请参阅 references/phase-details.md。 完整协议请参阅 references/delegation-protocols.md。

关键：只有用户选择选项 2（Finalize），才会执行阶段 6-10 已创建 Mockup v[N] 设计（2 个文件）

生成的文件：

• v[N]-ui.yaml（设计规范）
• v[N]-ui-test.html（可在浏览器中测试的 Mockup）

你想怎么做？

1. 迭代 - 优化设计、调整布局
2. 完成 - 验证一致性并完成 Mockup
3. 保存为模板 - 添加到美学库以便重复使用
4. 其他

请选择（1-4）：_

- 选项 1（迭代）：收集优化反馈，返回阶段 2 并生成新版本（v2、v3 等），调用全新的 ui-design-agent 实例（使用全新上下文）。 - 选项 2（完成）：进入阶段 5.6（自动更新 brief），Mockup 是 UI 部分的事实依据，无需用户交互；brief 同步后继续执行阶段 6-10。 - 选项 3（保存为模板）：调用 ui-template-library 技能并执行“save”操作，保存后返回阶段 5.5 菜单。 - 选项 4（其他）：处理自定义请求（在浏览器中测试、验证约束等）。

<iteration_guidance> 收集选项 1（迭代）的反馈时：

如果用户提出具体修改（“改成垂直布局”“添加一个电平表”“换成蓝色”）：

• 将这些作为明确要求传递给新的 ui-design-agent 实例

如果用户提出笼统的改进请求（“做得更好”“改进一下”“润色一下”）：

• 询问具体要关注哪些方面：“你希望我重点优化哪些方面？（布局、颜色、间距、控件）”
• 如果用户回答“全部”或“整体质量”：要求优化现有元素（间距、色彩协调性、控件样式），而不是添加新元素 </iteration_guidance>

详细路由说明请参阅 references/decision-menus.md#phase-5-5-design-decision-menu。

根据最终确定的 Mockup 自动更新创意 brief。 由阶段 5.5 中选择“完成”触发。 无需用户交互。 协议请参阅 `references/phase-details.md`。 - 用户已在阶段 5.5 确认设计（选择了选项 2：完成） - 阶段 A 的文件已存在（`v[N]-ui.yaml`、`v[N]-ui-test.html`） - YAML 中存在最终确定标记

防护措施的实现请参阅 references/phase-b-enforcement.md。

通过 Task 工具调用 ui-finalization-agent，生成 5 个实现文件。 调用摘要请参阅 `references/phase-details.md`。 完整协议请参阅 `references/delegation-protocols.md`。 ui-finalization-agent 成功返回后，显示完成菜单。 格式和路由请参阅 `references/decision-menus.md#completion-menu`。

<orchestration_protocol> <delegation_rules> 此技能绝不会直接生成 Mockup 文件。所有文件生成工作都必须委派给子 Agent。

1. 编排器：收集需求（阶段 0-3.5） 2. 编排器：通过 Task 工具调用 ui-design-agent 3. ui-design-agent：生成 YAML 和测试 HTML，提交更改并返回 JSON 4. 编排器：解析 JSON，显示阶段 5.5 菜单 5. 如果选择迭代：编排器调用全新的 ui-design-agent 6. 如果选择完成：编排器更新 brief（阶段 5.6） 7. 编排器：通过 Task 工具调用 ui-finalization-agent 8. ui-finalization-agent：生成 5 个文件，提交更改并返回 JSON 9. 编排器：解析 JSON，显示完成菜单

执行要求详见 references/delegation-protocols.md。 </delegation_rules>

</orchestration_protocol> <state_management> 子 Agent 会将其阶段结果更新到 .continue-here.md。编排器会检查 JSON 报告中的 stateUpdated 标志。

子 Agent 返回 stateUpdated: true 后，验证实际状态内容是否与预期值一致（不能只检查布尔标志）。

读取 .continue-here.md，解析 YAML，并检查特定字段是否与 JSON 报告中的值一致。如果不一致，则提供状态恢复菜单。

完整的状态架构和验证流程请参阅 references/state-tracking.md。 </state_management>

<iteration_protocol> 每次迭代都在全新的 Agent 上下文中运行。用户选择“迭代”后，编排器会收集反馈，并调用版本号递增的全新 ui-design-agent。全新上下文可避免迭代设计时上下文窗口膨胀。 </iteration_protocol>

<error_handling>

• Agent 失败：提供错误菜单（重试／手动修复／调试／取消）。
• 验证失败：Agent 返回 validationPassed: false，此时提供错误菜单。
• 状态更新失败：Agent 返回 stateUpdated: false，此时提供状态恢复菜单（验证／手动更新／仍然继续）。 </error_handling> </orchestration_protocol>

<versioning_strategy> 模式：v1、v2、v3……每个版本分别保存。

用途：探索布局而不丢失工作成果、对设计进行 A/B 测试、保留历史记录以便回滚。

文件命名：全部 7 个文件均以版本号为前缀（例如，v2-ui.html、v2-PluginEditor.h）。

实现：除非用户指定其他版本，否则 Stage 3（GUI）使用最新版本。

文件管理详情请参阅 references/versioning.md。 </versioning_strategy>

<success_criteria> <design_phase>

• 生成符合用户要求的 YAML 规范
• 浏览器测试 HTML 可正常工作（交互控件、参数消息）
• 视觉质量达到商业标准（设计经过精心构思，而非使用默认样式）
• 设计文件已提交到 git
• .continue-here.md 已更新版本信息（如果处于工作流模式）
• 已向用户展示 Phase 5.5 决策菜单
• 设计已获批准，或用户通过改进建议继续迭代 </design_phase>

<implementation_phase>

• 已生成全部 7 个文件并保存到 .ideas/mockups/
• 生产用 HTML 已完成（无占位符）
• C++ 样板代码与 YAML 结构一致（参数绑定正确）
• 已生成并锁定 parameter-spec.md（仅限 v1）
• 实现文件已提交到 git
• .continue-here.md 已更新最终确认状态（如果处于工作流模式） </implementation_phase> </success_criteria>

<integration_points> <invoked_by>

• /dream 命令——创意简报之后、实现之前
• plugin-workflow 技能——Stage 0 期间（UI 设计阶段）
• plugin-improve 技能——重新设计现有插件 UI 时
• 自然语言：“为 [PluginName] 设计 UI”“为压缩器创建模型图” </invoked_by>

<always_invokes>

• ui-design-agent 子 Agent（Phase 4-5.45）——设计迭代必需
• ui-finalization-agent 子 Agent（Phase 6-10.5）——实现文件必需 </always_invokes>

<also_invokes>

• ui-template-library 技能（用户保存美学风格时） </also_invokes>

- `plugins/[Name]/.ideas/mockups/v[N]-*.{yaml,html,h,cpp,txt,md}`（7 个文件） - `plugins/[Name]/.ideas/parameter-spec.md`（如果是 v1 且文件尚不存在） - `PLUGINS.md`——标记 UI 已设计（如果处于工作流模式） - `.continue-here.md`——更新工作流状态（如果处于工作流模式） - Stage 1（基础阶段）——缺少 parameter-spec.md 时无法继续 - Stage 3（GUI）——没有获批的 UI 模型图时无法实现

<reference_documentation> 渐进式披露——到达特定阶段时加载参考资料：

• 阶段 0： references/aesthetic-integration.md - 美学库集成
• 阶段 1： references/context-extraction.md - 创意简报提取
• 阶段 2-3： references/design-questions.md - 问题模板和分级
• 阶段 2.5： references/layout-validation.md - 尺寸计算公式
• 阶段 4-5.45： references/delegation-protocols.md - 子 Agent 调用
• 阶段 5.5： references/decision-menus.md - 菜单格式和路由
• 阶段 5.6： references/state-tracking.md - 简报同步协议
• 阶段 6-10： references/phase-b-enforcement.md - 阶段 B 防护
• 反模式： references/common-pitfalls.md - 应避免的事项

技术细节：

• references/html-generation.md - 生产环境 HTML 规则
• references/browser-testing.md - 浏览器测试工作流
• references/cmake-configuration.md - WebView 构建设置
• references/cpp-boilerplate-generation.md - C++ 模板生成
• references/ui-design-rules.md - 设计约束和模式
• references/versioning.md - 文件管理 </reference_documentation>

<template_assets>

• assets/ui-yaml-template.yaml - YAML 结构
• assets/webview-boilerplate.md - C++ 集成模板
• assets/integration-checklist-template.md - 集成指南
• assets/parameter-spec-template.md - 参数规范格式 </template_assets>