docs(design): add HTML prototype input convention (H-412)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

README.md

@@ -29,6 +29,7 @@
 | [`docs/api.md`](docs/api.md) | API 合约模板 |
 | [`docs/routes.md`](docs/routes.md) | 页面路由、组件归属、导航规则 |
 | [`docs/08-interaction-checklist.md`](docs/08-interaction-checklist.md) | UI 交互、状态反馈、无障碍与验收证据 |
+| [`docs/design/`](docs/design/README.md) | 页面原型输入约定：单文件 HTML 低保真原型，用于枚举交互 |
 | [`docs/clean-state-checklist.md`](docs/clean-state-checklist.md) | 会话收尾检查清单，保证下一轮无需人工修复即可开工 |
 | [`docs/current-state.md`](docs/current-state.md) | 当前实现状态快照，防止计划和代码现实脱节 |
 | [`docs/agent-context.json`](docs/agent-context.json) | 机器可读上下文路由：最小必读、任务类型和 SHA 刷新规则 |

docs/00-ai-start-here.md

@@ -118,6 +118,7 @@ MVP 不做：
 - 再看 `08-interaction-checklist.md` 的关联 IX 条目、状态和无障碍要求。
 - 再看 `routes.md` 的页面职责。
 - 最后看 `04-architecture.md` 的组件边界。
+- 若 `docs/design/` 有关联原型，可作为页面结构参考；行为以交互清单为准，不复制原型代码（约定见 [`design/README.md`](design/README.md)）。
 
 做后端 API：
 

docs/08-interaction-checklist.md

@@ -43,6 +43,7 @@ P0 交互必须使用本模板；非 P0 交互只有在高风险、不可逆、
 - 触发方式：【点击 / 键盘 / 输入 / 手势 / 自动触发】
 - 用户操作：【用户具体做什么】
 - 服务 / 数据依赖：【引用 API、事件或本地模块合约；无则写不适用】
+- 关联原型（可选）：【`docs/design/` 下的原型文件，约定见[设计原型输入约定](design/README.md)；无原型时写不适用】
 
 **正常路径**
 
@@ -124,6 +125,7 @@ IX-001 与 IX-003 规则清楚、风险低，只保留总表条目；IX-002 是
 - 触发方式：点击行内删除按钮。
 - 用户操作：点击删除 → 在确认对话框中确认或取消。
 - 服务 / 数据依赖：【API 合约中的删除接口】；错误格式以合约为准。
+- 关联原型（可选）：`docs/design/【条目列表页】.html`；无原型时写不适用。
 
 **正常路径**
 

docs/README.md

@@ -29,6 +29,7 @@
 - [API 合约](api.md)：前后端接口形状、错误格式、鉴权约定。
 - [路由与页面结构](routes.md)：页面路由、页面职责、组件归属。
 - [交互清单](08-interaction-checklist.md)：页面 / 组件交互、状态反馈、无障碍与验收证据。
+- [设计原型输入约定](design/README.md)：单文件 HTML 低保真原型的形态、权威性边界和工作流，用于生成交互清单。
 - [当前实现状态](current-state.md)：可覆盖的当前快照，记录仓库现实状态、可运行命令和下一步可做任务。
 - [Agent 上下文清单](agent-context.md) / [`agent-context.json`](agent-context.json) / [`Schema`](agent-context.schema.json)：按任务类型选择文档、用提交 / 文件 SHA 避免重复读取。
 - [Gitea MCP 接入](gitea-mcp.md)：可选的共享文档、Issue / PR 协调、安全配置和断连降级规则。

docs/design/README.md

@@ -0,0 +1,43 @@
+# 设计原型输入约定
+
+> 本目录存放页面原型，作为生成[用户故事清单](../07-user-stories.md)和[交互清单](../08-interaction-checklist.md)的**一次性输入物**。
+> 原型回答"页面上有什么"；"该怎样表现"的权威始终是交互清单，不是原型。
+
+## 一、定位与边界
+
+- 原型的唯一用途：让 agent 据图枚举页面、控件和用户可见动作，产出 IX 总表草稿，避免凭空发明界面或漏项。
+- **行为权威是[交互清单](../08-interaction-checklist.md)**：加载、空态、错误、权限、确认等行为以 IX 条目为准；原型与清单冲突时，以清单和[需求](../02-requirements.md)为准，或先对齐再动手。
+- 原型不定义需求范围：原型里出现、但[需求](../02-requirements.md)未收录的功能，不能因为"图上有"就实现。
+- **禁止把原型代码直接复制进生产实现**：原型没有组件抽象、状态管理和可访问性实现，实现时按[架构设计](../04-architecture.md)的组件边界重写。
+
+## 二、默认形态：单文件 HTML 原型
+
+- 一个页面一个 `.html` 文件，按路由或页面名命名，例如 `【items-list】.html`、`【login】.html`。
+- CSS / JS 全部内联，零构建依赖，双击即可在浏览器打开。
+- 低保真优先：结构和控件齐全即可，不追求视觉完成度。
+- 使用语义化标签（`button`、`form`、`table`、`dialog`、`nav`），标签本身就是控件清单。
+- 数据一律用假数据，页面顶部放固定横幅标注：`PROTOTYPE - 仅供枚举交互，非实现依据`。
+- 需要演示空态、加载、错误等状态时，可用少量内联 JS 做状态切换按钮，对应交互清单状态表的行。
+
+## 三、替代形态：SVG / 手绘草图
+
+布局说不清、画得快时，可用 SVG（Excalidraw、Penpot、Figma 导出）代替：
+
+- 文字必须保留为真文本（`<text>` 元素），不要导出为轮廓路径，否则 agent 读不到按钮文案。
+- 分组 / 图层使用语义命名。
+- 静态图只能表达一帧，状态与异常仍须在交互清单里逐项约定。
+
+## 四、工作流
+
+1. 用一两句话描述页面：有哪些区块、控件和主要动作。
+2. AI 生成低保真原型（HTML 或 SVG），存入本目录。
+3. 人工在浏览器查看并调整，直到布局与控件集合认可。
+4. AI 据原型产出[交互清单](../08-interaction-checklist.md)的 IX 总表草稿，状态全部标【待确认】。
+5. 人工逐条确认行为决策（优先级、状态与异常、无障碍），P0 交互按详情模板展开。
+6. 对应 IX 条目在「关联原型」字段引用本目录文件；原型更新后检查受影响的 IX 条目。
+
+## 五、维护规则
+
+- 原型是输入素材，不追求与实现持续同步；页面显著改版时重新生成，而不是逐次修补旧原型。
+- 已无对应页面或已完成使命的原型可以删除；删除前确认没有 IX 条目仍在引用。
+- 本目录不放业务敏感数据、真实用户数据或生产接口地址。

tasks.md

@@ -80,7 +80,7 @@ Get-ChildItem -Recurse -File
 | H-409 | 把「一任务一文件」从并发切换模式升级为默认任务管理模式 | H-407, H-408 | ① `docs/tasks/README.md` 改为默认模式文档：删除"仅并发时切换"叙事，单/多 agent 统一走一任务一文件，暗语流程、防撞号、执行记录进任务文件等规则保留；② `docs/06-tasks.md` 降级为只读路线图：仅保留 Phase 划分、里程碑 M1-M4、Backlog 待办池，预置 T-001~T-402 转为"建议拆分清单"（开工时才落成任务文件），不再逐任务跟踪状态；③ `progress.md` 标注为可选/历史归档，执行记录默认写任务文件 `## 执行记录`；`current-state.md` 保留项目级快照职责（启动/验证路径、blocker），任务状态以各任务 frontmatter 为准（可脚本汇总）；④ 同步更新引用方：`00-ai-start-here.md`（开工/收尾流程）、`05-coding-rules.md`（完成定义与证据绑定路径）、`README.md`、`docs/README.md`、`adoption-checklist.md`、`clean-state-checklist.md`、`method-map.md`；⑤ 验证：`rg` 搜"切换/冻结/逐任务追加 progress/覆盖 current-state"等旧流程表述清零，链接引用一致；不改暗语触发词，不引入 Gitea 集成（另见 Obsidian 笔记，暂缓） | DONE |
 | H-410 | 收编用户故事 / 交互清单的根目录残留示例并收窄文档重叠 | - | ① 根目录 `独立交互清单.md`、`用户故事清单.md` 占位符化后收编：内容去业务事实（用户管理 / `/api/users` / 头像上传等改为 `【占位符】`）、编号规范化为 US-001 / IX-001 格式、表格列对齐 `07-user-stories.md` / `08-interaction-checklist.md` 现有表结构、删除不存在的 `design/screenshot.svg` 引用，作为「填写示例」小节分别并入 07 / 08 文末，然后删除根目录这两个文件；② `docs/02-requirements.md` 的"核心用户故事总览表"收窄为 功能 / US 编号 / 优先级 三列，角色、目标、关联交互列移除，由 07 独占，保留"详细故事以 07 为准"的指向；③ `docs/08-interaction-checklist.md` 把"先总表、只为 P0 / 高风险 / 易歧义交互补详情"升格为醒目规则（详情模板默认只覆盖 P0），避免逐交互填全表的官僚化；④ 验证：`python3 scripts/validate_agent_context.py` 通过；`rg` 确认 `design/screenshot.svg`、`用户管理`、`/api/users` 等业务残留清零，根目录无中文文件名残留；07 / 08 / 02 相互链接一致；不改 07 / 08 文件名和编号（阅读顺序已由 README 导航表达） | DONE |
 | H-411 | 返修 H-410：恢复验收契约并重写填写示例 | H-410 | ① 恢复本文件中 H-410 验收要点为落任务时原文（见 ecd75de），状态保持 DONE；「使用规则」新增"验收要点一经领取不得改写，完成时只更新状态并另记证据；确需重新定义任务时先经用户确认"条款；② `docs/07-user-stories.md`、`docs/08-interaction-checklist.md` 的「填写示例」改写为具体但通用的示例（列表检索、删除确认等通用场景，业务对象统一用【条目】占位），每个字段给出真实可读的填法，不再逐字复读模板占位符；③ 08 示例以破坏性 P0 交互演示完整 10 行状态与异常清单和无障碍要求，低风险交互演示"只留总表条目"的用法；④ 验证：`python3 scripts/validate_agent_context.py` 通过、全仓 `.md` 相对链接无断链、示例未混入真实业务事实（无具体接口路径 / 真实产品名） | DONE |
-| H-412 | 增加 HTML 原型输入约定 `docs/design/` | H-411 | ① 新增 `docs/design/README.md` 约定文档：原型定位（生成 07 用户故事 / 08 交互清单的一次性输入物，低保真优先）；形态（一页面一个单文件 `.html`，CSS / JS 内联、零构建依赖、双击可开，按路由命名如 `items-list.html`）；假数据要求（页面顶部固定 "PROTOTYPE" 横幅标注仅供枚举交互）；权威性边界（行为权威是 08 清单，原型与清单冲突时以清单+需求为准；禁止把原型代码直接复制进生产实现，实现按 `04-architecture.md` 组件边界重写）；工作流（需求描述 → AI 生成原型 → 人工调整认可 → 据原型产出 IX 总表草稿全标【待确认】→ 人工确认行为决策）；SVG / Excalidraw 作为快速草图的替代形态一并说明（文字须保留为真文本）；② `docs/08-interaction-checklist.md` 交互详情模板与填写示例增加可选字段「关联原型」（无原型时写不适用）；③ 登记导航：`README.md`、`docs/README.md`；`docs/00-ai-start-here.md` 的"做页面 / UI"分支提及原型可作输入；④ 验证：`python3 scripts/validate_agent_context.py` 通过、全仓 `.md` 相对链接无断链、约定保持通用占位符不绑业务；不预置示例原型文件，不改 07 / 08 文件名 | TODO |
+| H-412 | 增加 HTML 原型输入约定 `docs/design/` | H-411 | ① 新增 `docs/design/README.md` 约定文档：原型定位（生成 07 用户故事 / 08 交互清单的一次性输入物，低保真优先）；形态（一页面一个单文件 `.html`，CSS / JS 内联、零构建依赖、双击可开，按路由命名如 `items-list.html`）；假数据要求（页面顶部固定 "PROTOTYPE" 横幅标注仅供枚举交互）；权威性边界（行为权威是 08 清单，原型与清单冲突时以清单+需求为准；禁止把原型代码直接复制进生产实现，实现按 `04-architecture.md` 组件边界重写）；工作流（需求描述 → AI 生成原型 → 人工调整认可 → 据原型产出 IX 总表草稿全标【待确认】→ 人工确认行为决策）；SVG / Excalidraw 作为快速草图的替代形态一并说明（文字须保留为真文本）；② `docs/08-interaction-checklist.md` 交互详情模板与填写示例增加可选字段「关联原型」（无原型时写不适用）；③ 登记导航：`README.md`、`docs/README.md`；`docs/00-ai-start-here.md` 的"做页面 / UI"分支提及原型可作输入；④ 验证：`python3 scripts/validate_agent_context.py` 通过、全仓 `.md` 相对链接无断链、约定保持通用占位符不绑业务；不预置示例原型文件，不改 07 / 08 文件名 | DONE |
 
 ## Phase 5 · Harness 评审与健康度层（Tier 2）