软件界面 HTML 原型生成

目的

把「界面样版 + 文字说明」转化为可直接打开、可交互的单文件 HTML 界面原型，并支持在此基础上按截图标注反复迭代。

产出形态固定为：单个 .html 文件，内联 CSS 与原生 JS，零外部依赖（无 CDN、无框架、无图片资源），双击即可在浏览器打开演示。

何时使用

• 用户给出参考截图 / 样例页面 + 字段与规则说明，要求生成界面
• 用户描述一个后台功能（列表、表单、弹框、主从结构），要求做出原型
• 用户发来带红框标注的截图 + 一句修改指令，要求调整既有原型
• 用户提出「加个页面说明」「按样板改配色」「按钮统一缩小」这类界面层调整

命名样板库

技能内置一批已命名的成品样板。使用规则：

1. 用户说「用『XX』样板生成……」时，按下方索引表找到入口文件并读取，以该样板的布局、配色、组件尺寸为准
2. 用户没指定样板时，默认用 assets/template.html 通用骨架
3. 用户新上传样板要求入库时，用 scripts/add_template.py --add 登记（自动清洗并刷新下表）
4. 样板与 references/design-system.md 冲突时，样板优先

<!-- TEMPLATES:BEGIN -->
| 样板名 | 类型 | 入口文件 | 说明 |
|---|---|---|---|
| 经典列表+弹框 | html | assets/templates/classic-list-modal.html | 标准列表页（顶栏/查询条/吸顶表头/分页）+ 新增·编辑·查看弹框 + 基本信息|附件 页签 + 左右明细结构 + 页面说明 |
| 鲲鹏索引+详情 | html | assets/templates/kp-index-detail.html | 左侧紧凑索引列表（序号/编码/名称/规格/可用 + 更多查询 + 分页 + 拖拽调宽）+ 右侧复用经典表单，按钮 复制/新增/编辑/审核/删除 |
| 视觉参考截图 | png | assets/templates/multi-page-shots | 列表 / 新增 / 编辑 / 查看 / 单页面 / 页面说明 六张参考截图，用于视觉风格对齐 |
| 单页面样式 | html | assets/templates/单页面样式.html | 左侧紧凑索引列表（序号/编码/名称/规格/可用 + 筛选 + 分页 + 拖拽调宽）+ 右侧详情表单的单页主从结构，按钮 复制/新增/编辑/审核/删除。V1.0 快照 |
| 多页面样式 | html | assets/templates/多页面样式.html | 列表页（查询条/创建日期范围/吸顶表头/分页）+ 新增·编辑·查看弹框（同构、数据回显、查看态只读）+ 基本信息|附件 页签 + 左右明细结构 + 审核/停用按钮体系。V1.0 快照，早于「页面说明」区块 |
<!-- TEMPLATES:END -->

常用管理命令：

S=<skill目录>/scripts/add_template.py
python $S --list                                    # 列出全部样板
python $S --add --file "<源文件>" --name "<样板名>" --desc "<说明>" --tags "标签1,标签2"
python $S --add --file a.png --file b.png --name "<样板名>"   # 多文件（截图组）自动存为目录
python $S --rename <key> --name "<新名>"             # 重命名
python $S --remove <key>                            # 移除

--add 的语义
- 同名即原地更新（不改 key、不产生重复条目）；只更新描述可重跑一次 --add
- 入库自动清洗：去预览残留标记（data-page-node-id / data-pnid-children / data-dm-ref / data-sp-bindable 及 __dm_* 样式块）+ 去预览工具注入的重复空控件
- 中文名直接做 key 与文件名，用 --rename 改名；样板名不要重名或前缀重叠，否则引用时会歧义

工作流程

第 1 步 · 拆解需求

从文字说明中提取并按需向用户确认：

1. 页面类型：列表页 / 表单页 / 列表+弹框 / 主从索引详情
2. 数据模型：字段清单（名称、类型、是否必填、唯一性）、枚举值
3. 控件类型：能枚举的一律用下拉；参照字段用「输入框 + 放大镜」；状态用「是/否」文字
4. 明细结构：一对多的子表、版本表、左右结构
5. 交互与规则：查询条件、行选择方式、按钮显隐、状态流转、审核/停用约束、删除限制、默认生成规则
6. 菜单上下文：系统名、模块名、面包屑路径

需求中的矛盾或缺口（例如「不允许删除」却要求删除按钮）要显式标出并询问，不要自行取舍。

第 2 步 · 解析样版

从参考截图/样例页面读取：

• 布局骨架（顶栏 / 面包屑 / 卡片 / 查询条 / 表格 / 分页 / 页签 / 弹框）
• 配色（主色、语义色、行状态色）——样版优先于默认规范
• 组件尺寸（按钮高度、圆角、字号、内距）
• 列的顺序与文案

第 3 步 · 选骨架

优先级：用户指定样板 > 命名样板库中的同类型样板 > assets/template.html 通用骨架。

从选定样板取对应区块改造，模式选择见 references/layout-patterns.md：

第 4 步 · 生成

• 单文件，内联样式与脚本；.html 文件名用 <功能名>-界面原型.html
• 演示数据构造 20 条以上，覆盖「可用 / 停用 / 已审核 / 未审核」各种状态，便于演示分页与按钮显隐
• 实现可交互逻辑：查询过滤、行选择、按钮显隐、分页、弹框增删改查、保存校验、toast 反馈
• 视觉与交互细则遵循 references/design-system.md
• 不要给输入框写占位提示文字（除非用户要求）

第 5 步 · 自检与交付

python <skill目录>/scripts/check_html.py <生成的.html>

必须无 ERROR（JS 语法、重复 id、标签开合、外部资源、占位符）。
然后调用 present_files 交付并打开预览，附一段说明：改了什么、文件路径、可选后续动作。
最后把进展追加到 <workspace>/.workbuddy/memory/YYYY-MM-DD.md。

迭代修改

用户发来带标注的截图 + 一句指令时：

1. 先读取磁盘上的最新文件（用户可能已手动改过或重命名）
2. 只改指令涉及的元素，不顺手重构
3. 多处改动优先用原子化补丁脚本一次性应用（见 references/iteration-workflow.md §2），避免中间态被覆盖
4. 改完即跑自检脚本，再用 present_files 交付

资源导航

硬性约束

• 单文件零依赖：不得引入 CDN、外部字体、外链图片
• 只做清单内的东西：字段严格按用户给定的清单与顺序实现，不自行添加字段分组标题（如「基本信息/审计信息」）、分区、统计卡片、说明文案、额外状态字段。用户说「不要画蛇添足」就是指这个——字段平铺即可。按钮体系可以套样板，字段不行。
• 配色统一：全页只用一个主色体系；改主色时全局同步（logo 渐变、聚焦光晕、标签、分页选中、高亮条）
• 弹框无底部按钮：所有操作集中在弹框头部
• 列表按钮规格 .btn-sm：高 26px，列表页与弹框头部统一
• 列表首列固定为序号列：位于复选框列之后，width:52px;text-align:center;color:#6b7280；序号跨页连续（(curPage-1)*pageSize+idx+1），列数变化时同步空行 colspan
• 表头吸顶 + 分页固定：长列表必须做到
• 停用记录字体转红，整行置灰不可点
• 审核保护：已审核记录禁止编辑与删除；不可用物料禁止审核
• 交付前必跑自检脚本；有 ERROR 不交付