---
name: soloforge-prototype-spec
description: 把真实原型素材转成按端、按页可实现和可验收的 UI 约束。
when: 原型说明 / prototype_spec / 涉及前端时
---

# 原型说明

## 适用性

在任务涉及前端，且存在图片、HTML、设计文件、视频、可运行原型或用户确认的文字交互规格时使用。没有视觉素材时仍可记录交互与数据契约，但视觉结论必须标待确认，不能臆造。

本文档的定位是索引+差异+契约层：视觉、文案与结构保真的权威是原型素材本身，文档不承担像素级复现；每页必须给出实现阶段可直接打开的对照锚点，实现与审查据此回到素材逐项对照。

## 事实输入

- 用户提供的原型素材及其版本、来源和可见状态。
- 需求端清单、已确认的项目目录和页面范围。
- 路由、数据字段、权限和异常分支等上游契约。
- `template.md` 和 `examples.md`。

## 关键决策

- 哪些页面属于本期、哪些状态必须覆盖、哪些视觉值可精确读取。
- 提取手段分级：有源码或可运行原型时，颜色、尺寸、文案和结构一律从源码或运行时读取，不得靠图像近似；仅图片素材时才允许近似标注并安排人工校对。
- 素材证据表的具体位置必须构成实现对照锚点（源码文件路径+行号区间、可运行原型的启动方式+端口+路由，或图片文件路径）；锚点打不开时按素材缺口处理，不得用文字描述顶替。
- 素材之间冲突时，以用户指定的权威版本为准，不能自行拼接。

- 表单形态判定决策树：列表页内新增/编辑/详情→右抽屉（列表上下文可对照）；多步向导→整页；需 URL 深链（分享/刷新保持/外部跳入）→整页；轻量确认/扫码/凭证预览→小窗；高频重复维护→行内编辑。嵌套限制：禁止抽屉套抽屉。
- 表单类页面实现前先出 ASCII 字段级草图对齐（字段清单/分组/列布局），对齐后再实现；「已填未保存关闭」须弹确认（dirty 守卫）。

## 产出方法

1. 按已确认的端目录和页面拆分，一页一份说明。
2. 默认路径为 `docs/analyze/{端目录}/pages/{页面}-原型说明.md`；brownfield 或自定义 project map 服从解析后的权威路径和目录命名。
3. 引用共享设计系统，只提取本页实际使用或偏离的约束；再完成布局、组件数据、交互状态、异常、响应式、无障碍和动效。
4. 每条重要约束标明素材类型与具体来源位置。
5. 把无法从素材确认的内容列为待确认项，不写成事实。

## 禁止项

- 不得从其他产品、组件库默认值或个人审美补视觉规则。
- 不得用通用登录页、通用表格等示例骨架替代真实页面。
- 不得省略空态、错误态、加载态、权限态和不可用态。
- 不得把多个端或多个页面合并成一份模糊说明。

## 交付自检

- 每个本期页面都有独立文件并归属正确端目录。
- 交互事件能落到前后状态、数据变化和失败反馈。
- 精确值、近似值和未知值区分清楚。
- 每页素材证据表含可直接打开的实现对照锚点；有源码或运行素材时未使用图像近似推断。
- 共享约束与页面级差异分开，没有为填表重复抄整套 token。
- 页面与需求、路由和数据字段可追溯。

## 权威验证

编辑后先处理 quick 反馈，再调用 `sf_verify action="full" task_id="当前任务ID" artifact="prototype_spec"`。full 通过后仍需在实现和测试阶段按页做交互与视觉验收。

素材证据表锚点与页面元数据路由行会被确定性机制消费：锚点源码集内容指纹并入验证输入摘要（原型源码变更会使下游证据失效），build 域 UI-STRUCT-CONSIST 据锚点与路由声明定位原型页/实现页并对照文案、表格列、操作按钮三特征——锚点路径须可直接解析，路由行须写实现侧真实路由。


## 交付前对抗审查

`sf_verify` 通过只证明结构/编译/测试层；语义质量（承接正确性、异常/并发/权限/边界是否可靠、是否含空话或无法证伪的承诺）须经独立对抗审查。advance/deliver 前用 `sf_review action="start" task_id="当前任务ID" artifact="<本产物 kind>"` 发起 per_artifact 审查，用**独立 session/subagent**（非产出本产物的同一会话）执行返回的 prompt、submit findings，按 next_step 完成 K 次独立采样与闭环。deliver 会阻断未完成/未闭环的审查；活跃豁免与被驳回 error 会被注入审查 focus 供独立复核。