build-prototype

构建原型

构建一个可丢弃但外观完整的整体界面模型，让用户在实现前确定结构、关系和行为。

将产品层与决策层分开：prototype.html 保存规范的产品界面和流程；临时的 compare.html 则在具体情境下解决用户当前的问题。根据决策所需的范围来限定比较内容，可以是一个组件、一个界面，也可以是一段简短流程。

如果不确定用户需要在哪种设备上打开预览，只询问一次：他们只会在运行此任务的电脑上查看，还是也会在另一台设备上查看。如果宿主支持非阻塞式提问，就使用该方式；否则，先完成不依赖访问设备的构建，再提问。不要根据执行宿主推断查看设备，也不要将未回答视为用户已作出选择。根据可用环境选择执行和托管方式；不要指定特定平台。

对于局部比较请求，直接进入比较一项决策，并将构建和验证限制在该决策范围内。整体界面清单、评审和保留要求适用于原型，不适用于这个中间产物。

设置工作投入程度

接受 effort=standard 或 effort=high。如果省略参数，推荐并使用 standard。

无论投入程度如何，都必须通过同一项基础完成门槛：产出外观完整的界面，涵盖所有请求的界面和相关状态，确保预期交互和重置路径可用，在浏览器中检查每个相关视口，修复检查中发现的每个可重现缺陷，并提供用户可打开的地址。在 standard 下，门槛保持不变。

• standard 以通过基础门槛作为完整结果。
• high 先通过相同的基础门槛，再通过评审并迭代收敛，与可检查的当前产品或参考对象实现高度视觉匹配。如果宿主支持子 Agent，则指派一名全新的评审子 Agent，以高级模型投入程度进行审计，并向其提供参考对象和候选产物，但不提供构建者的审查结果。否则，将构建与验证分为独立阶段，并报告评审独立性或模型投入程度方面的限制。如果无法检查参考对象，则报告视觉等效性未经验证，并仅用额外一轮来增强布局的稳健性。

以原型为依据

以请求和对话内容为范围依据。如果有，请阅读 GLOSSARY.md、docs/decisions/README.md 中的相关主题，以及仅当请求或先前交接明确指出某项工作单元规范时才阅读该规范。不要搜索规范。

将现有产品和设计系统作为依据进行检查。使用其中的规范术语、界面语言、设计令牌和组件；否则，使用用户的语言和模板中简洁完整的样式。只有当用户需要在基线方案与候选方案之间作选择时，才将基线方案纳入评审。明确指出冲突，不要擅自解决。

保持已确认的关系不变。除非用户正在重新考虑这种关系，否则应让浮层、抽屉和模态框保持与其来源界面的关联。

构建一个规范的产品界面

将屏幕清单作为可修正的草稿展示，并立即开始构建，无需等待批准。

将 templates/shell.html 复制到一个临时的独立 HTML 文件中，并在其中构建所有产品屏幕。保留并遵循模板中的约定注释；它负责评审界面、产品像素边界、屏幕和状态语义，以及视口行为。此文件中每个产品屏幕只保留一个规范版本。

将单击即可完成的更改和临时更改作为产品交互实现，无论它们看起来有何不同。仅将重要的多步骤结果、强制数据或错误，以及不易直接触达的结构设为选择器预设。交互进入或离开已声明的预设时，同步选择器。

将项目令牌原样复制到 :root；如果不存在令牌文件，则提取现有的设计语言。如果项目提供深色调色板，则将其复制到 .sh-theme-dark，以显示 shell 的主题切换控件；如果项目没有深色调色板，就让原型不带主题控件，而不是凭空设计深色模式。使用这些令牌为每个屏幕设置样式，并在 data-component 中标记设计系统的组件名称；仅在没有对应组件时才使用 new:Name。

使用逼真的虚拟内容，包括符合实际长度的名称、合理的文案、不规则数字，以及仅与场景相关的边缘情况。切勿使用 lorem ipsum。不要加入真实数据、API、延迟、生产环境路由或状态连接、框架、构建步骤或网络依赖。

原生应用模型使用手机外框；移动优先原型从模板的窄视口开始，其类负责模拟响应式行为。

评审并完善

展示前先渲染并检查产物。在浏览器中测试每个屏幕、已声明状态、交互入口和重置路径，以及相关视口。使用当前测试框架支持的方法运行最终 HTML，并提供用户可打开的地址。在产品像素区域之外的对话中说明差异、原因和评审指南。展示产物和可修正的屏幕草稿，逐个讲解界面屏幕，并询问需要修改哪些内容。不要以完成交接的方式结束尚未结束的评审。

对于 high，从两个相互独立的角度进行审查。将参考界面与原型在屏幕、状态和视口坐标一致的条件下进行比较，检查排版、间距、对齐、换行、溢出和资源处理。另一个角度则使用逼真的长内容或不规则内容，压力测试布局和交互恢复。对每个可能造成实质影响的不匹配，记录其精确坐标、观察到的证据和复现路径。如果有新的评审子 Agent 可用，让其复现这些候选问题；剔除无法复现的问题，并持续修正已验证的问题，直到没有可复现的实质性不匹配为止。 修正后，重新渲染对应坐标，以及共享了已更改令牌、组件或 shell 行为的其他屏幕或状态。在对话中报告审查覆盖范围，以及任何未经验证的坐标或保真度结论。

比较一项决策

对于一项尚未解决的视觉或交互决策，将 templates/comparison-shell.html 复制到临时文件 compare.html。明确具体的用户情境，并渲染最多三个备选方案，提供足以做出判断的上下文即可。 一个片段可能就够了；一个流程可能需要几个相关视图。比较范围独立于原型的屏幕清单。 在出现决策时创建比较，而不是为每个产品屏幕各创建一次，并将无关的产品工作保留在原型中。

保留模板的样式和契约注释；它负责比较控件，并确保产品导航位于备选方案内部。除 决定性选项外，固定内容、数据、周边布局、行为和已确认元素。评审者一次只会看到一个备选方案并在它们之间切换，因此请在相同状态和视口坐标下验证每个备选方案，而不只是验证比较打开时显示的那个方案。仅渲染并验证判断所需的交互、状态和尺寸，然后分享可运行的比较并询问用户如何选择。

用户做出选择后，在同一个 prototype.html 中将结果应用到受影响的产品 UI 和流程，并在那里验证受影响的行为。集成后删除临时比较，然后继续原型评审或塑形会话。为下一项决策创建新的比较；不要收集以往的比较，也不要将 compare.html 升格为最终交付物。如果尚未构建原型，请记录选择并丢弃比较，不要仅为演示集成而构建整个产品。

保留已批准的结果

工作文件应保持为临时文件；评审仍在进行时，不要在 docs/specs/ 下写入任何内容。一旦每个屏幕都已获批准或明确延期，就将成本低廉、由 Agent 选择的默认值保留为可覆盖的假设。对于已批准界面尚未确定的重要行为，应询问或明确延期，并将其影响记录为剩余风险，不要因此重新开启无关的屏幕评审。

当所有与实现相关的重要产品决策都已确定或明确延期，并且所有由 Agent 选择的成本低廉的默认值都已标记为可覆盖的假设后，复用已识别的工作单元文件夹，或创建一个 kebab-case slug。将已确认的行为与明确标记的假设和延期事项一并记录在 docs/specs/<slug>/spec.md 中，创建或更新塑形阶段所用的同一份稳定产品契约。实施前，记录或保留其用户可见结果、已批准范围、可观察的验收标准、已确定的约束及其理由、假设、不允许触碰的区域及原因、延期事项、风险和准备事项。在 ## Setup before implementation 标题下，逐行列出实施所需的每项仓库外工作，例如供应商账户、已签发的密钥或控制台或 DNS 设置，并说明所需事项、它所服务的结果，以及一个无需依赖规范所交付工作即可观察到的完成条件。如果不需要任何事项，则写 None.，且绝不要写入机密值。省略预测的文件、函数、代码结构、技术层和实施步骤。将已批准的界面保存并链接为 docs/specs/<slug>/prototype.html。绝不要根据源顺序或视觉上的邻近关系推断导航、顺序或行为。

仅将用户确认的、可复用的、非显而易见的权衡取舍，从规范提升到项目决策契约中。

丢弃中间产物；已批准的原型是参考，不是生产代码。