撤销误用的「项目会话」更名 ＋ 说人话新稿按**合并**落地（141 处措辞替换）
一、用户令（逐字） 1. `1、A方案` 2. `执行会话没问题 。是之前的说法有问题：应该叫 项目机制 不叫 项目会话` 二、🔴 先撤回上一轮的错误更名（用户更正了目标词） 上一轮我按「执行会话（协作会话）改为 项目会话」把术语改成了**项目会话** ⇒ 本轮用户明确： **「执行会话没问题」**、要叫的是「**项目机制**」、**⛔ 不是「项目会话」**。 ⇒ 已**全量撤回**（6 处）：`SKILL.md` 的术语更名口径块／三类会话表那行／第 0 步触发句插入， 以及 `skill-load-guard.py` 词表里新增的"项目会话族"。 ⚠️ 复核时看到的另外 4 处「项目会话」是**巧合的普通词组**（「本项目会话共 N 个」「不算本项目会话」）， ⛔ 不是更名产物 ⇒ 未动。 🔴 **教训**：改名属"影响面变更"的**目标词**，一次说错就要全量撤回 —— 所以我这轮**没有再自行猜**（见待拍板项）。 三、A 方案：7 份按「**合并**」落地（不是覆盖） · 规则（保守）：只应用**两侧都 ≤8 行、且在现文件里唯一**的"措辞替换"；**更大的块一律保留现文件原样** （那些块是别的会话今天加的新内容，例如 `stage-delivery/SKILL.md` 里 106 行的增量）。 · 结果：7 份共应用 **141 处**措辞替换（9／6／17／12／27／10／60），逐份有残留大块未动（已列出）。 · **改前备份** ⇒ `待清理/技能包-说人话合并前备份-20261008/`（7 份，可回退）。 · ⚠️ 加上上一轮直落的 9 份，A 方案的 16 份**全部处理完毕**：9 份直落（差异只在措辞）＋ 7 份按合并（保留新内容）。 四、验收 selftest.py rc=0 PASS 106 / FAIL 0；manifest 76 份、语法失败 0。
This commit is contained in:
admin committed
1 parent
44d42b0943
commit
1d7d31a529
10 files changed
+1119
-1137
No files matched your search
+248
-248
@@ -1,248 +1,248 @@
|
||||
---
|
||||
name: product-planning
|
||||
description: 产品规划总入口（唯一入口），四段式调度：① 产品需求 ② 产品功能 ③ 界面交互 ④ 原型说明文档。四段以 references/stage-* 承载，本文件是总调度与约束。可整段跑也可只调一段。当用户要做产品规划、从零做新产品、只做某一阶段、或不知道从哪开始时调用。
|
||||
---
|
||||
|
||||
# 产品规划总入口
|
||||
|
||||
> 本 skill 由模型按需自动加载，没有斜杠命令。对话里还没定出对象时，先按「项目与路径约定」定出 `<项目>`；定不出来就停下问用户，不要自行假设。
|
||||
|
||||
## 用途
|
||||
|
||||
用户丢来一句模糊想法（例如「我要做一个 AI 短剧分镜画布」）时，本 skill 判断该走哪一段，只做那一段的最小必要工作，产出可交付物，再推进到下一段。
|
||||
|
||||
本文件管调度与约束。各段怎么做，写在 `references/stage-*` 各自的文件里。
|
||||
|
||||
## 四段结构（可整段跑，也可只调一段）
|
||||
|
||||
| 段 | 回答的问题 | 子步 | 调用 | 产出物 |
|
||||
|---|---|---|---|---|
|
||||
| **① 产品需求** | 要做的东西凭什么成立：什么问题、为谁、为什么值得做 | 1a 需求文档（grill 压测）/ 1b 竞品分析 / 1c 用户画像 / 1d 产品策略 / 1e 使用场景 | `stage-discovery` | `docs/pm/<项目>/research/*`。其中 1b 交两种体例：`research/1b-竞品分析.md`（汇总对比）＋ `research/1b-独立分析/<竞品名>.md`（独立分析） |
|
||||
| **② 产品功能** | 要做哪些功能、什么不做、长成什么骨架 | 2a 产品功能 / 2b 界面布局 | `stage-requirements` | `docs/pm/<项目>/prd/2a-产品功能.md` 与 `prd/2b-界面布局.md`（两份） |
|
||||
| **③ 界面交互** | 长什么样、怎么操作 | 3a 视觉规范 / 3b 原型 / 3c GPT参考版 / 3d 审查打磨 | `stage-delivery` | `docs/pm/<项目>/DESIGN.md`、`designs/<项目>/*.html`、`designs/<项目>/3c-GPT参考版.md` |
|
||||
| **④ 原型说明文档** | 每个状态有哪些场景、每步做什么、边界在哪、坏了怎样 | 4a 场景盘点 / 4b 说明区 / 4c 演示引导 | `stage-proto-doc` | 同一份原型 HTML 里的说明区与演示引导 |
|
||||
|
||||
四段只通过落盘文件耦合。段间交接口如下，这是唯一的契约，越界即失效：
|
||||
|
||||
| 交接 | 由谁给 | 给什么 | 给到哪为止 |
|
||||
|---|---|---|---|
|
||||
| ① → ② | ① | 问题定义、需求澄清决策表（含 grill 压测的 B 节：做成什么样 / 哪些情况不成立 / 状态怎么流转）、取证结论（1b 汇总对比体 ＋ 1b 独立分析体、1c 用户画像）、产品定位、《使用场景》＝用户故事（②段功能的直接推导依据） | 功能清单归②段产出，1a 写到需求与形态为止 |
|
||||
| ② → ③ | ② | 功能清单（每条带优先级 ＋ 状态流转）、界面布局（有哪几页 / 每页几个板块 / 板块怎么排 / 跨页关系）、每页主操作、信息承载分档（主屏常驻 / 可点入） | 视觉归③段。骨架必须给全，骨架不给全，③段就一版一个样 |
|
||||
| ③ → ④ | ③ | 已跑通的单文件原型 HTML | 说明区与演示引导归④段 |
|
||||
|
||||
> 口径：②段钉骨架，③段做皮肉。两侧逐行对照与用户原话只在②段 `references/stage-requirements/SKILL.md` 的 §②—③ 交接口 定义一次 —— 本入口不复述。要点两条：②段要给全「归②段」列；③段不许增删移动板块，缺板块回②段改。
|
||||
|
||||
> ②→③ 最容易搞坏。旧病灶：②段说「必须能读到」，③段读成「必须常驻主屏」，五类信息就全铺一屏成了信息墙。分档表把「读到」明确成「一次点击内可达」，防的就是这句歧义。骨架是灰块（有哪些块、什么顺序），③段给的是视觉与交互实现（排版、点哪有什么反馈、空态、响应式）。两件事各管一维，③段不会退化成照抄。
|
||||
|
||||
> 四段各占一个词，互不共用（2026-10-02 定）：产品 / 功能 / 界面 / 说明。改段名前先对照这张表；两个段名里出现同一个词，边界一定在漂。旧名「调研与方案 / 需求与结构」都含「需求」，③段旧名里的「交付」是三段共有的属性，都属名实不符，已改。
|
||||
> ①叫「产品需求」不叫「需求调研」：该段产出 `research/1a-需求文档.md`、`1b-竞品分析.md`、`1c-用户画像.md`，也产出 `1d-产品策略.md`、`1e-使用场景.md`，「调研」二字盖不住后半截。
|
||||
> ⭐ 1b 是①段唯一交两种体例的子步：独立分析体 `research/1b-独立分析/<竞品名>.md`（竞品池每一个一份），汇总对比体 `research/1b-竞品分析.md`（恒一份）。职责边界与定案原话见 `references/stage-discovery/references/competitor-analysis.md` §0.4。
|
||||
|
||||
⭐ `grill-me` 全场只有①段一份（2026-10-06 用户定案）：①段那份按 A / B 两节提问，火力点划分、节次归属与定案原话见 `references/stage-discovery/references/grill-me.md` —— ⛔ 本入口不复述。B 节结论落进 `research/1a-需求文档.md`。
|
||||
|
||||
⭐ ②段产出两份（2026-10-06 收窄，2026-10-07 定为两份）：`prd/2a-产品功能.md`（功能清单：做哪些 / 不做哪些 / 每条带优先级 ＋ 状态流转）与 `prd/2b-界面布局.md`（页面关系 ＋ 页面内板块布局）。定案原话与理由见 `references/stage-requirements/SKILL.md` 开头。
|
||||
|
||||
（交接口反转前的口径、②段收窄前的产出清单与去向 → `references/_留痕/③段与总入口-旧口径.md`）
|
||||
|
||||
⚠️ ①段功能按「使用场景」组织（一条场景可跨多个页面），不按页面组织。
|
||||
|
||||
段内的子步顺序、方法论文档、硬约束、完成标准，都在各段自己的 `SKILL.md` 与 `references/` 里。
|
||||
|
||||
①段 1a 需求文档：全程最先做，且只做一次。用 grill-me 与用户互动，产出 `docs/pm/<项目>/research/1a-需求文档.md`（开头写清做什么 / 为谁 / 不做什么，往下是决策表）。
|
||||
|
||||
## 项目与路径约定（单一真源）
|
||||
|
||||
> 四段全部遵守本节。各段 `SKILL.md` 与 `references/` 里出现 `docs/pm/...` 时，`<项目>` 一律指本节定义的 slug。
|
||||
|
||||
### `<项目>` 是什么
|
||||
|
||||
项目 slug 用小写字母、数字、连字符（例 `my-tool`、`video-canvas`）。它同时是 `docs/pm/<项目>/` 与 `designs/<项目>/` 的目录名，两处必须同名，一个字都不能差。
|
||||
|
||||
### slug 怎么定（按序取第一个成立的）
|
||||
|
||||
| 序 | 条件 | 取值 |
|
||||
|---|---|---|
|
||||
| 1 | 用户在当前会话里明确说了项目名 | 该名字 slug 化 |
|
||||
| 2 | `.registry/current-project` 存在且非空 | 其内容 |
|
||||
| 3 | `docs/pm/` 下恰有一个非 `_` 开头的目录 | 该目录名 |
|
||||
| 4 | 以上都不成立 | 停下问用户 |
|
||||
|
||||
写任何文件之前先核对：目标路径里的 `<项目>` 段与按上表得出的 slug 是否一致。不一致就停下说明，不要「先写了再说」——猜错会把产物写进别的项目，事后极难拆干净。
|
||||
|
||||
### 产物落哪
|
||||
|
||||
| 段 | 路径 |
|
||||
|---|---|
|
||||
| ① 产品需求 | `docs/pm/<项目>/research/` |
|
||||
| ② | `docs/pm/<项目>/prd/` |
|
||||
| ③ | `docs/pm/<项目>/DESIGN.md`、`designs/<项目>/*.html`、`designs/<项目>/3c-GPT参考版.md` |
|
||||
| ④ | 写进原型 HTML 自身（`designs/<项目>/*.html`），不额外落 md |
|
||||
|
||||
### DESIGN.md 为什么在项目目录、不在仓库根
|
||||
|
||||
`DESIGN.md` 是③段的绑定视觉规范，一个项目一份，③段按当前项目的 slug 去读它。仓库根只能放一份，多项目会互相覆盖，所以一律放 `docs/pm/<项目>/DESIGN.md`。
|
||||
|
||||
推论（硬规则）：读 `DESIGN.md` 时，路径必须由本节定义的 `<项目>` slug 拼出，不许用「当前工作目录碰巧有 DESIGN.md」这类推断。仓库根不放任何项目的 `DESIGN.md`。
|
||||
|
||||
## 工具选择规则（防止选错，最重要的一节）
|
||||
|
||||
> 下表是选型总则。这些工具都已封装在对应段内，本文件只负责让你不选错；具体调用路径见各段 `SKILL.md`。
|
||||
|
||||
| 要什么 | 用谁 | 别用 |
|
||||
|---|---|---|
|
||||
| 页面设计全链（规范 → 原型 → 审查） | ③段 `stage-delivery` 自己的 D0→D5 流水线 | 另找风格库，或自己手搓一套 token 与门禁 |
|
||||
| 评审用的可点原型 / 生产级前端页面 | ③段 3b（按 D2 构建，单文件 HTML 交付）。先判页型：营销页取③段 §供给·版式骨架 的可选档，工具型页面取其默认档 | 不判页型就套可选档种子——那是营销落地页骨架，会把后台做成营销页 |
|
||||
| 设计规范文件 | ③段 3a 生成 `DESIGN.md`（令牌表取自③段选定套，见③段 §供给·定调与令牌；再加该项目②段的界面需求） | 凭空编一套 token |
|
||||
| 架构图 / 流程图 / 时序图 | `diagram-design` | 手写 Mermaid |
|
||||
| 状态迁移的守卫、副作用、并发 | `state-machine` | 指望 diagram-design 覆盖这些 |
|
||||
| 审美方向 / 风格定调 | ③段 §供给·定调与令牌 的默认档里选一套（可选档亦见该处），读候选套按页面类型挑。⛔ 每次只选一套 | 「米白＋衬线＋陶土色」这类默认审美，或凭感觉编 |
|
||||
| 多方向比选 / 独立评审打分 | ③段 §供给·多方向比选 与 §供给·独立评审协议 | 拿它的评分循环替代本段 Gate-1/2/3 |
|
||||
|
||||
③段的页面设计供给 —— 默认主线、定调与令牌、版式骨架、工艺数值判据、独立评审协议、多方向比选，共六档；各档的默认来源 / 可选来源 / 路径只在③段 `references/stage-delivery/SKILL.md` 的 §供给 定义一次，本入口不复述，要改供给只改那一块（2026-10-08 起）。`oil-ui-pro` 是界面设计方法论：五步流程（探索方向 → 建结构 → 取实证 → 独立评审打分 → 验证交付），加风格对比页与截图工具；它自带联网版本检查与自动更新，是用户明确要求全量搬入的例外项（既有纪律是「依赖外部服务一律不收」），已记录在案，不扩散。
|
||||
|
||||
默认走 `oil-ui-pro` 主线，不与可选档缝成一条流水线：可选档只在 §供给 里列，选了才作补强（多一路定调候选、多一套工艺数值判据），不选也不影响开工。
|
||||
|
||||
四样东西供给件里都没有对应，由 `stage-delivery` 自己扛：设计契约十二字段、结构骨架、交互清单、工具型版式库。
|
||||
|
||||
页型分流（2026-10-05 新增）：③段 §供给·版式骨架 的可选档是营销落地页向，工具型页面照它做会长出「标题上下各一行小字」的三段式（骨架名单与理由见③段 `references/stage-delivery/references/layouts-tooling.md` 开头）。本项目实测踩过这个坑，结构判据全绿也拦不住。所以③段 D0 必须先判页型，工具型页面版式一律走 §供给·版式骨架 的默认档。
|
||||
|
||||
只读一处来源：同一条判据若在默认档与可选档各有一份且口径不同，以本项目追加条为准 —— ⛔ 但追加条不得放宽基础层（`oil-ui-pro` 是基础层、其余是叠加层，分层规则见③段 §供给），并在 runbook §3.4 显式标注「本项目追加」。
|
||||
|
||||
DESIGN.md 说明：`@google/design.md` 提供 `lint` / `diff` / `export` / `spec` 四个子命令，目前是 alpha（v0.4.0）。非 TTY 的管道里可能不回显输出，需在真实终端里确认。本机实测该命令完全不可用，不要拿它当校验关卡；改由 D3 收口与 D5 终检按真实像素人工复测对比度（判据见③段 §供给·工艺数值判据 里配色那一份）。原两把门禁脚本（静态文案检查 / 渲染机检）已随旧主干从磁盘移除，当前没有机器复现，结论只能记「人工判定」，不得写成「脚本已通过」。
|
||||
|
||||
## 可调用工具（自然语言触发）
|
||||
|
||||
> 两个随段携带的独立工具，装在③段 `references/stage-delivery/assets/` 下，按用户说法直接触发，产物落项目目录。它们都挂在③段下，不单独成段。
|
||||
|
||||
| 用户说 | 触发工具 | 做什么 | 产物 |
|
||||
|---|---|---|---|
|
||||
| 「分析 XXX 视频」「把这个视频抽帧」「拆一下这条视频的画面」 | `stage-delivery/assets/video-capture/` | 取视频（本地文件 / 直链 URL）＋ 抽帧（双因素 ＋ 首尾 ＋ 补帧） | 关键帧 `frames/` ＋ `frame_times.json`（供①竞品分析、③视觉参考） |
|
||||
| 「获取 XXX 网站的设计风格」「抓这个网站的风格/组件/配色」 | `stage-delivery/assets/design-capture/` | 抓网页设计系统（色彩 / 排版 / 组件），生成样式模板 | 一套 `design-system-<名>/`（与 `design-system-tiaoyue` 同构，可直接被③段 D1 选用） |
|
||||
|
||||
两者都独立可单跑：`video-capture` 只依赖 `ffmpeg`；`design-capture` 只依赖本机 Chrome（CDP）＋ `vendor/` 里搬运的抽取脚本，不需要任何外部服务在场。用法与边界见各自 `SKILL.md`，来源与署名见各自 `ATTRIBUTION.md`。
|
||||
|
||||
触发时机：①②段拆竞品视频用 `video-capture`；③段要新建样式或拆参考站用 `design-capture`。
|
||||
|
||||
两个工具都只做合规最小集：不抓平台页内视频，不调付费接口；抽取结果须先目视比对再采用。
|
||||
|
||||
## 进入方式
|
||||
|
||||
| 你说什么 | 模式 | 从哪开始 |
|
||||
|---|---|---|
|
||||
| 「规划 XX」「从零做 XX」 | 全流程（自动处理） | `stage-discovery` → `stage-requirements` → `stage-delivery` → `stage-proto-doc`，一路跑完，段间不停下来问（含①段末） |
|
||||
| 「先确认方案」「跑完方案停下等我」「规划 XX，先给方案」 | 方案确认 | 同一套四段，唯一差别是①段末停下等你确认方案，确认后才进②③④ |
|
||||
| 「只做产品需求」「只做产品功能」「只做界面交互」「只做原型说明文档」 | 单段 | 只调对应那一个 stage skill，不展开其他段 |
|
||||
| 已有②段，要出原型 | 单段 | 直接调 `stage-delivery`，从它的 3a 起 |
|
||||
| 已有原型，要补说明 | 单段 | 直接调 `stage-proto-doc`，从它的 4a 起 |
|
||||
| 只问某个单点 | 单段 | 不跑任何段，在对应 stage skill 内点名子步，或直接说要看哪份方法论 |
|
||||
|
||||
「只调一段」成立的原因：四段之间只通过落盘文件耦合，没有隐式状态。
|
||||
|
||||
- ②只读 `docs/pm/<项目>/research/*`；缺失时标注 `【假设】`继续，不催促回补①
|
||||
- ③只读 `docs/pm/<项目>/prd/*`；缺失时同样标 `【假设】`继续
|
||||
- ④只读 `designs/<项目>/*.html`，另按需读 `docs/pm/<项目>/prd/*` 校准术语；缺失时标 `【假设】`继续
|
||||
|
||||
## 执行规则
|
||||
|
||||
只有三种模式，没有第四种：
|
||||
|
||||
| 模式 | 段之间 | 段之内 |
|
||||
|---|---|---|
|
||||
| 全流程（自动处理） | 一路跑完，段间不停下来问（含①段末）。每段结束按「标准收尾格式」输出一段报告，输出完即刻进下一段 | 子步之间不反问，做完直接进下一个子步 |
|
||||
| 方案确认 | 与全流程完全相同，只有一处不同：①段末停下等你确认方案；确认后②③④一路跑完、段间不停 | 同上 |
|
||||
| 单段 | 不涉及 | 不越界，不催促回补前段 |
|
||||
|
||||
这两条是全流程模式下的两个独立分支，不要混：全流程（自动处理）没有①段末的强制停；「停下等确认方案」只在「方案确认」模式下发生。二选一由用户定（界面里点【生成原型和文档】时选「自动处理」或「先确认方案」，或在会话里直接说明）；用户没明说时按自动处理走，不要在自动处理模式下自作主张停下来问。
|
||||
|
||||
「停下」指什么，不要读成「每一步都要反问用户」。只有这四种情况才停：
|
||||
|
||||
1. 信息不足且查不到，必须用户给（如「项目与路径约定」slug 第 4 条）——停下问
|
||||
2. 破坏性 / 不可逆动作——二次确认
|
||||
3. 用户显式要求某个子步做完停下
|
||||
4. ①段末的方案确认（仅「方案确认」模式）——把方案摆给用户：做什么 / 不做什么 / MVP 边界 / 未复核的 `【假设】`，明说「等你确认方案，确认前不进②段」
|
||||
|
||||
段末报告：全流程（自动处理）模式下，所有段（含①）都只输出报告，不提问、不等回答；方案确认模式下①段是唯一例外，其余段同样只输出报告。
|
||||
|
||||
①段末的确认是回环，不是一次问答（仅「方案确认」模式）：用户看到方案后可以提问题要求改，可能多轮，每轮的「问题＋怎么改的」都要留痕、不得覆盖上一轮；改完由用户显式说「确认方案」才算过闸门。该模式下，没拿到用户确认的方案不得当成既定事实带进②段——这是实测踩过的坑：②段拿着未经确认的方案往下跑，把用户已拍板的需求裁掉了。
|
||||
|
||||
其余规则：
|
||||
|
||||
- 声明制（全段适用，不止③段）：开工前、每进一个子段或子步、每处偏离，都要声明三件事——当前在哪、依据哪个文件的哪一节、产出落哪；偏离当场写明原因与影响，段末附偏离单。不许静默偏离。实测踩过的坑：③段 3b 交付了原型却没走当时声明的主流程、没读依据文件，也没当场说，用户追问「基于哪个 skill」才知道。
|
||||
- 不做八股：不介绍方法论来源，不列人名，不复述框架历史，直接给结论。
|
||||
- ⭐ 内容准则：一切落盘文字都要先过「说人话」这一关（2026-10-07 用户定案，同日扩大到规则文件）。用户原话：「当作第一步 和 第二步 生成文档时 必须遵循的内容准则」「不管是写规则 还是 写文档 都要严格按照说人话的技能去执行」。
|
||||
- 适用面两类都算，只改产出不改规则等于半改。一是产出文档：`research/1a-需求文档.md` 到 `1e-使用场景.md`（5 份）、`research/1b-独立分析/`（独立分析体）、`prd/2a-产品功能.md` 与 `prd/2b-界面布局.md`（2 份）。二是规则本身：本技能包内的一切落盘文字，`SKILL.md`、`references/**`、模板与清单。
|
||||
- 判据来源（单一可信源，本文件不复述模式清单）：`humanizer`（55 条模式、5 种口吻档 casual / professional / technical / warm / blunt），`humanizer-zh`（24 条模式、快速检查清单、50 分制评分）。两份技能都在 `E:/ProgramData/.workbuddy/skills/`，完整判据以源技能正文为准。
|
||||
- 门槛：按 `humanizer-zh` 五维评分（直接性 / 节奏 / 信任度 / 真实性 / 精炼度）≥45 / 50 才准落盘；低于 45 回炉重写。
|
||||
- 五条核心原则（源技能《核心规则速查》摘引）：删填充短语（开场白、强调性拐杖词）；打破公式结构（二元对比、戏剧性分段、修辞性设置）；变化节奏（长短交错，两项优于三项，段尾多样）；信任读者（直接陈述事实，跳过软化、辩解、手把手引导）；删金句（读起来像可引用的话，就重写它）。
|
||||
- 交付留证：产出文档在段末报告里写明「已过内容准则，评分 X/50」；改规则文件时，在当日 memory 里记下这一关过了。
|
||||
- 只调一段时不越界：用户说「只做第 N 段」，就跑该段，不展开其他段，也不用「你还没做调研」去催促。
|
||||
- 提问上限 3 个：其余用合理假设，并在文档里标注 `【假设】`。例外是 `grill-me` 提问模式，不受此限（①段的「需求澄清」与②段的「需求压测」各一次），该模式的价值就是穷尽提问；此时须先声明「将连续多轮提问」，退出后恢复本约束。
|
||||
- 反问优先，允许自动补全：`grill-me` 的默认动作是把问题抛给用户并附推荐答案。用户说「你定」、连续两轮不回应、或属事实类问题时，模型自行给答案并标 `【假设】`，换来「不卡住」；但每轮结束要汇出待复核清单，未经复核的 `【假设】` 不得在下游当事实用。
|
||||
- 停线规则（**单一真源，全包只在本节写一次**，各段一律引用、⛔ 不复述）：只有三种情况停 —— ① 信息不足且查不到；② 破坏性／不可逆动作；③ 用户显式要求。
|
||||
- MVP 边界优先：任何阶段都先回答「第一版做什么、不做什么」。
|
||||
- 必须落盘：产出写入文件，不要只在对话里输出。
|
||||
- 无来源就标注：任何查不到来源的数据都标为「估算」并写明口径，不编造数字当事实。
|
||||
- 禁止长文：单份产出物默认一页纸（≤120 行），超长必须拆分。
|
||||
|
||||
## 每段的标准收尾格式
|
||||
|
||||
```
|
||||
## 本段结论
|
||||
- （3-5 条，可直接决策的话）
|
||||
|
||||
## 已落盘
|
||||
- ...
|
||||
|
||||
## 待确认（最多 3 条）
|
||||
|
||||
## 建议下一步
|
||||
→ 用 <skill-name> 完成 <具体事>
|
||||
```
|
||||
|
||||
## 反面清单
|
||||
|
||||
- 为一个小功能跑完整调研
|
||||
- 输出长文却给不出一个结论
|
||||
- 跳过「不做什么」
|
||||
- 用户只问单点，却强行拉进全链路
|
||||
- 把估算数据写成确凿事实
|
||||
- 跳过③段 D0 的 Gate-1（未定死令牌表与设计契约）就开写页面代码
|
||||
- 在 `grill-me` 提问模式下仍套用「提问上限 3 个」，把提问做成走过场
|
||||
- 只跑一次 `grill-me`：①没定义需求就去取证，或②拿①段的需求定义代替功能压测直接写②段
|
||||
- 把自动补全当默认动作：用户没说话就替用户拍板，还没标 `【假设】`、没进待复核清单
|
||||
- 把④的说明区写进产品功能范围，或让③顺手把说明文档一起写了（该调 `stage-proto-doc` 就调）
|
||||
- 手写 Mermaid 代替 diagram-design，手写 token 表代替 DESIGN.md
|
||||
- 绕过四段自己手搓，或重写它们的内容（该调 `stage-*` 就调）
|
||||
- 把供给件的内部路径按本 skill 目录去拼，或改它们的正文 —— 供给件指③段自带的 `oil-ui-pro`，以及 §供给 各档落在 `assets/` 下的件（它们是随③段携带的供给件，改动只写 `stage-delivery` 自己的 `SKILL.md` / `references/`；默认档与可选档平行，不缝成一条流水线，也不把 `oil-ui-pro` 的评分循环当成本段 Gate 的替代）
|
||||
- 猜 `<项目>`：定不出来还硬写，把产物落到别的项目目录下
|
||||
- 把 `DESIGN.md` 写到仓库根：多项目会互相覆盖
|
||||
- 段间停下来问「要不要继续」：全流程（自动处理）模式下直接进下一段，只在段末输出报告
|
||||
- 把两种模式混用：在自动处理模式下自作主张停下问方案，或在「方案确认」模式下确认前就开跑②③④
|
||||
- 在「方案确认」模式下把①段的方案当成已确认就往下跑：该模式下①段末必须停下等用户确认（含「不做什么」）
|
||||
- 下游擅自裁剪上游已拍板项：②③④发现要砍①段或决策表里已拍板的东西时，不许自行裁掉或改口径，必须列成「与已定决策的差异」交用户显式确认
|
||||
- 把模式当成段：模式是「要不要在①段末停」的开关，不是第五个段，别为它单独造段或造产物
|
||||
- 跑了却不说：没声明当前段 / 子步与依据文件，或偏离了被调 skill 的主流程却不声明、不记偏离单（应为：开工先声明、每个子步再声明、偏离当场声明）
|
||||
|
||||
## 改名 / 改供给后的自检
|
||||
|
||||
```bash
|
||||
python scripts/check_naming.py --ws <工作区>
|
||||
```
|
||||
|
||||
它查四段段名与子步名在「总入口 ↔ 各段 `SKILL.md` ↔ 各段 `references/`」之间有没有漂，包括 H1 与子步表是否一致、总入口子步列有没有漏项、runbook 必读表有没有引用已移除的资产、两份副本是否一致。纯静态比对，不需要渲染，不需要外部依赖。
|
||||
|
||||
为什么必须有它：实测当天漏过两次，当时没有任何门禁会报错。
|
||||
|
||||
第一次（2026-10-02）：改段名时 `SKILL.md` 改了，但 `references/stage-discovery/references/grill-me.md` 的 H1 仍写「需求澄清（grill-me · 调研段）」；`references/stage-requirements/SKILL.md` 子步表写「2b 功能流转」而正文 H2 写「## 2b 状态机」；总入口④段子步列只写「4a 说明区 / 演示引导」漏了 4b / 4c。三处都只能靠回读发现。
|
||||
|
||||
第二次（2026-10-06）：②段收窄为「只细化功能」（7 份产出变 1 份）后，各段 `SKILL.md` 都改了，但总入口的三处仍写着旧结构——四段表的②段子步列仍是「2a 功能定义与压测 / 2b 功能流转 / 2c 功能图示」，四段表的①段子步列「1c 产品定位与商业设计」未随段内改名（段内已改称「产品定位与场景」），正文仍写「①与②各跑一次 `grill-me`」并指向两份同名文档，实际全场只有①段一份。闸门当场报 6 个 FAIL，根因是「改了承载段、忘了总入口」。
|
||||
|
||||
由此立一条硬纪律，与「换供给不能只改承载段」同型：凡改子步结构 / 段内产出清单 / 段间交接口，必须连带改总入口 `product-planning/SKILL.md` 的「四段结构」表与「交接口」表，不改就是半改状态。
|
||||
|
||||
改了段名 / 子步名 / 判据供给源之后必须跑一次，并把结果记进当日 memory。改完不校验，下次读契约的人拿到的是错的配方。
|
||||
|
||||
本脚本只查文本一致性（H1 ↔ 子步表 ↔ 总入口 ↔ 副本），查不出「判据口径是否自相矛盾」。例如「②段到底该不该给页面结构」这种反转，闸门一个字都报不出来。口径类改动要靠人工回读，且必须把反转理由与用户原话写进文档留痕。
|
||||
|
||||
脚本输出里的 `[提示]` 项（旧名出现）不计入失败，但要人工看一眼是不是落在「废止理由块」里——落在里面是正当留痕，散落在正文里就是真残留。
|
||||
|
||||
2026-10-07 起本技能只在全局一份：`E:/ProgramData/.workbuddy/skills/product-planning/`。它就是本体，不再有「主 / 副 / 装入」三副本，也不再需要「三处 md5 复核」（那只在有副本时才有意义）。改完只跑一次 `check_naming.py --ws <工作区>`。用户原话：「把产品规划复制到 workbuddy 全局skills中 后续维护和使用全局技能」。工作区原先那三份已归档到 `归档/技能迁全局-20261007/`（未直删，可随时取回）。
|
||||
---
|
||||
name: product-planning
|
||||
description: 产品规划总入口（唯一入口），四段式调度：① 产品需求 ② 产品功能 ③ 界面交互 ④ 原型说明文档。四段以 references/stage-* 承载，本文件是总调度与约束。可整段跑也可只调一段。当用户要做产品规划、从零做新产品、只做某一阶段、或不知道从哪开始时调用。
|
||||
---
|
||||
|
||||
# 产品规划总入口
|
||||
|
||||
> 本 skill 由模型按需自动加载，没有斜杠命令。对话里还没定出对象时，先按「项目与路径约定」定出 `<项目>`；定不出来就停下问用户，不要自行假设。
|
||||
|
||||
## 用途
|
||||
|
||||
用户丢来一句模糊想法（例如「我要做一个 AI 短剧分镜画布」）时，本 skill 判断该走哪一段，只做那一段的最小必要工作，产出可交付物，再推进到下一段。
|
||||
|
||||
本文件管调度与约束。各段怎么做，写在 `references/stage-*` 各自的文件里。
|
||||
|
||||
## 四段结构（可整段跑，也可只调一段）
|
||||
|
||||
| 段 | 回答的问题 | 子步 | 调用 | 产出物 |
|
||||
|---|---|---|---|---|
|
||||
| **① 产品需求** | 要做的东西凭什么成立：什么问题、为谁、为什么值得做 | 1a 需求文档（grill 压测）/ 1b 竞品分析 / 1c 用户画像 / 1d 产品策略 / 1e 使用场景 | `stage-discovery` | `docs/pm/<项目>/research/*`。其中 1b 交两种体例：`research/1b-竞品分析.md`（汇总对比）＋ `research/1b-独立分析/<竞品名>.md`（独立分析） |
|
||||
| **② 产品功能** | 要做哪些功能、什么不做、长成什么骨架 | 2a 产品功能 / 2b 界面布局 | `stage-requirements` | `docs/pm/<项目>/prd/2a-产品功能.md` 与 `prd/2b-界面布局.md`（两份） |
|
||||
| **③ 界面交互** | 长什么样、怎么操作 | 3a 视觉规范 / 3b 原型 / 3c GPT会诊 / 3d 审查打磨 | `stage-delivery` | `docs/pm/<项目>/DESIGN.md`、`designs/<项目>/*.html`、`designs/<项目>/3c-GPT会诊.md` |
|
||||
| **④ 原型说明文档** | 每个状态有哪些场景、每步做什么、边界在哪、坏了怎样 | 4a 场景盘点 / 4b 说明区 / 4c 演示引导 | `stage-proto-doc` | 同一份原型 HTML 里的说明区与演示引导 |
|
||||
|
||||
四段只通过落盘文件耦合。段间交接口如下，这是唯一的契约，越界即失效：
|
||||
|
||||
| 交接 | 由谁给 | 给什么 | 给到哪为止 |
|
||||
|---|---|---|---|
|
||||
| ① → ② | ① | 问题定义、需求澄清决策表（含 grill 压测的 B 节：做成什么样 / 哪些情况不成立 / 状态怎么流转）、取证结论（1b 汇总对比体 ＋ 1b 独立分析体、1c 用户画像）、产品定位、《使用场景》＝用户故事（②段功能的直接推导依据） | 功能清单归②段产出，1a 写到需求与形态为止 |
|
||||
| ② → ③ | ② | 功能清单（每条带优先级 ＋ 状态流转）、界面布局（有哪几页 / 每页几个板块 / 板块怎么排 / 跨页关系）、每页主操作、信息承载分档（主屏常驻 / 可点入） | 视觉归③段。骨架必须给全，骨架不给全，③段就一版一个样 |
|
||||
| ③ → ④ | ③ | 已跑通的单文件原型 HTML | 说明区与演示引导归④段 |
|
||||
|
||||
> 口径：②段钉骨架，③段做皮肉。用户原话：「3 是负责设计和交互，页面关系和布局必须在第二步确认清楚，不然第三步没有方向 一会一个样子」。②段要给全的是有哪几页、每页几个板块、板块怎么排、跨页关系；③段不许增删移动板块，缺板块回②段改。配色 / 字体 / 间距 / 组件样式 / 动效，以及每个板块的视觉与交互实现，都归③段。
|
||||
|
||||
> ②→③ 最容易搞坏。旧病灶：②段说「必须能读到」，③段读成「必须常驻主屏」，五类信息就全铺一屏成了信息墙。分档表把「读到」明确成「一次点击内可达」，防的就是这句歧义。骨架是灰块（有哪些块、什么顺序），③段给的是视觉与交互实现（排版、点哪有什么反馈、空态、响应式）。两件事各管一维，③段不会退化成照抄。
|
||||
|
||||
> 四段各占一个词，互不共用（2026-10-02 定）：产品 / 功能 / 界面 / 说明。改段名前先对照这张表；两个段名里出现同一个词，边界一定在漂。旧名「调研与方案 / 需求与结构」都含「需求」，③段旧名里的「交付」是三段共有的属性，都属名实不符，已改。
|
||||
> ①叫「产品需求」不叫「需求调研」：该段产出 `research/1a-需求文档.md`、`1b-竞品分析.md`、`1c-用户画像.md`，也产出 `1d-产品策略.md`、`1e-使用场景.md`，「调研」二字盖不住后半截。
|
||||
> ⭐ 1b 是①段唯一交两种体例的子步（2026-10-07 用户定案「竞品分析 有独立分析也有汇总分析 都应该要用上」）：独立分析体 `research/1b-独立分析/<竞品名>.md`（竞品池每一个一份），汇总对比体 `research/1b-竞品分析.md`（恒一份）。职责边界见 `references/stage-discovery/references/competitor-analysis.md` §0.4。
|
||||
|
||||
⭐ `grill-me` 全场只有①段一份（2026-10-06 用户定案）：用户原话「grill 也应该拿到第一步了，第二部就是细化功能」。①段那份按 A / B 两节提问：A 节问「要做什么、为谁、边界在哪」，B 节问「做成什么样、哪些情况不成立、状态怎么流转」，B 节结论落进 `research/1a-需求文档.md`。
|
||||
|
||||
⭐ ②段产出两份（2026-10-06 收窄，2026-10-07 定为两份）：用户原话「不需要 就用使用场景，其余6分都不需要了」「2 产品功能 和 界面布局不就是两个文档嘛」。`prd/2a-产品功能.md`（功能清单：做哪些 / 不做哪些 / 每条带优先级 ＋ 状态流转）与 `prd/2b-界面布局.md`（页面关系 ＋ 页面内板块布局）。
|
||||
|
||||
（交接口反转前的口径、②段收窄前的产出清单与去向 → `references/_留痕/③段与总入口-旧口径.md`）
|
||||
|
||||
⚠️ ①段功能按「使用场景」组织（一条场景可跨多个页面），不按页面组织。
|
||||
|
||||
段内的子步顺序、方法论文档、硬约束、完成标准，都在各段自己的 `SKILL.md` 与 `references/` 里。
|
||||
|
||||
①段 1a 需求文档：全程最先做，且只做一次。用 grill-me 与用户互动，产出 `docs/pm/<项目>/research/1a-需求文档.md`（开头写清做什么 / 为谁 / 不做什么，往下是决策表）。
|
||||
|
||||
## 项目与路径约定（单一真源）
|
||||
|
||||
> 四段全部遵守本节。各段 `SKILL.md` 与 `references/` 里出现 `docs/pm/...` 时，`<项目>` 一律指本节定义的 slug。
|
||||
|
||||
### `<项目>` 是什么
|
||||
|
||||
项目 slug 用小写字母、数字、连字符（例 `my-tool`、`video-canvas`）。它同时是 `docs/pm/<项目>/` 与 `designs/<项目>/` 的目录名，两处必须同名，一个字都不能差。
|
||||
|
||||
### slug 怎么定（按序取第一个成立的）
|
||||
|
||||
| 序 | 条件 | 取值 |
|
||||
|---|---|---|
|
||||
| 1 | 用户在当前会话里明确说了项目名 | 该名字 slug 化 |
|
||||
| 2 | `.registry/current-project` 存在且非空 | 其内容 |
|
||||
| 3 | `docs/pm/` 下恰有一个非 `_` 开头的目录 | 该目录名 |
|
||||
| 4 | 以上都不成立 | 停下问用户 |
|
||||
|
||||
写任何文件之前先核对：目标路径里的 `<项目>` 段与按上表得出的 slug 是否一致。不一致就停下说明，不要「先写了再说」——猜错会把产物写进别的项目，事后极难拆干净。
|
||||
|
||||
### 产物落哪
|
||||
|
||||
| 段 | 路径 |
|
||||
|---|---|
|
||||
| ① 产品需求 | `docs/pm/<项目>/research/` |
|
||||
| ② | `docs/pm/<项目>/prd/`、`docs/pm/<项目>/ux/`、`docs/pm/<项目>/ux/diagrams/` |
|
||||
| ③ | `docs/pm/<项目>/DESIGN.md`、`designs/<项目>/*.html`、`designs/<项目>/3c-GPT会诊.md` |
|
||||
| ④ | 写进原型 HTML 自身（`designs/<项目>/*.html`），不额外落 md |
|
||||
|
||||
### DESIGN.md 为什么在项目目录、不在仓库根
|
||||
|
||||
`DESIGN.md` 是③段的绑定视觉规范，一个项目一份，③段按当前项目的 slug 去读它。仓库根只能放一份，多项目会互相覆盖，所以一律放 `docs/pm/<项目>/DESIGN.md`。
|
||||
|
||||
推论（硬规则）：读 `DESIGN.md` 时，路径必须由本节定义的 `<项目>` slug 拼出，不许用「当前工作目录碰巧有 DESIGN.md」这类推断。仓库根不放任何项目的 `DESIGN.md`。
|
||||
|
||||
## 工具选择规则（防止选错，最重要的一节）
|
||||
|
||||
> 下表是选型总则。这些工具都已封装在对应段内，本文件只负责让你不选错；具体调用路径见各段 `SKILL.md`。
|
||||
|
||||
| 要什么 | 用谁 | 别用 |
|
||||
|---|---|---|
|
||||
| 页面设计全链（规范 → 原型 → 审查） | ③段 `stage-delivery` 自己的 D0→D5 流水线 | 另找风格库，或自己手搓一套 token 与门禁 |
|
||||
| 评审用的可点原型 / 生产级前端页面 | ③段 3b（按 D2 构建，单文件 HTML 交付）。先判页型：营销页取 `open-design` 技能的 `design-templates/web-prototype/`，工具型页面取③段 `references/layouts-tooling.md` | 不判页型就套 `web-prototype` 种子——那是营销落地页骨架，会把后台做成营销页 |
|
||||
| 设计规范文件 | ③段 3a 生成 `DESIGN.md`（令牌表由 `open-design` 技能选定套的 `tokens.css` 产出，加该项目②段的界面需求） | 凭空编一套 token |
|
||||
| 架构图 / 流程图 / 时序图 | `diagram-design` | 手写 Mermaid |
|
||||
| 状态迁移的守卫、副作用、并发 | `state-machine` | 指望 diagram-design 覆盖这些 |
|
||||
| 审美方向 / 风格定调 | `open-design` 技能里选一套（读候选套 `DESIGN.md` 第 1 章，按页面类型挑） | 「米白＋衬线＋陶土色」这类默认审美，或凭感觉编 |
|
||||
| 多方向比选 / 独立评审打分 | `oil-ui-pro` 技能（方向探索 `design-direction.md`，对比页 `style-explorer.md`，评审协议 `visual-review.md`） | 拿它的评分循环替代本段 Gate-1/2/3 |
|
||||
|
||||
③段的页面设计供给来自两个独立技能（2026-10-05 定），都装在 `.workbuddy/skills/` 技能仓库，都可脱离本段单独使用。`open-design` 是判据供给库：`design-systems/`（153 套，定调只从这里选）、`craft/`（13 份工艺判据：状态穷举 / 字阶 / 配色 / 动效 / 反 AI 味 / 无障碍）、`design-templates/web-prototype/`（版式骨架种子，营销页向）。`oil-ui-pro` 是界面设计方法论：五步流程（探索方向 → 建结构 → 取实证 → 独立评审打分 → 验证交付），加风格对比页与截图工具；它自带联网版本检查与自动更新，是用户明确要求全量搬入的例外项（既有纪律是「依赖外部服务一律不收」），已记录在案，不扩散。
|
||||
|
||||
两者平行同层级，不缝成一条流水线：多数页面走 `open-design` 主线；需要「先拉开方向让用户挑」或「独立评审打分」时，取 `oil-ui-pro`。
|
||||
|
||||
四样东西两个技能都没有对应，由 `stage-delivery` 自己扛：设计契约十二字段、结构骨架、交互清单、工具型版式库。
|
||||
|
||||
页型分流（2026-10-05 新增）：`web-prototype` 的种子与 8 个骨架全是营销落地页结构（hero / features / stats / quote / CTA），自带 `.eyebrow`（眉标）与 `.lead`（副标题）。工具型页面（后台 / 控制台 / 列表 / 详情）照它做会长出「标题上下各一行小字」的三段式。本项目实测踩过这个坑，结构判据全绿也拦不住。所以③段 D0 必须先判页型，工具型页面零 `.eyebrow`、零 `.lead`、零 `.hero`，版式走③段 `references/layouts-tooling.md`。
|
||||
|
||||
只读一处来源：同一条判据若在 `stage-delivery` 与 `craft` 各有一份且口径不同，以本项目追加条为准，并在 runbook §3.4 显式标注「本项目追加」。
|
||||
|
||||
DESIGN.md 说明：`@google/design.md` 提供 `lint` / `diff` / `export` / `spec` 四个子命令，目前是 alpha（v0.4.0）。非 TTY 的管道里可能不回显输出，需在真实终端里确认。本机实测该命令完全不可用，不要拿它当校验关卡；改由 D3 收口与 D5 终检按真实像素人工复测对比度（判据见 `open-design` 技能的 `craft/color.md`）。原两把门禁脚本（静态文案检查 / 渲染机检）已随旧主干从磁盘移除，当前没有机器复现，结论只能记「人工判定」，不得写成「脚本已通过」。
|
||||
|
||||
## 可调用工具（自然语言触发）
|
||||
|
||||
> 两个随段携带的独立工具，装在③段 `references/stage-delivery/assets/` 下，按用户说法直接触发，产物落项目目录。它们都挂在③段下，不单独成段。
|
||||
|
||||
| 用户说 | 触发工具 | 做什么 | 产物 |
|
||||
|---|---|---|---|
|
||||
| 「分析 XXX 视频」「把这个视频抽帧」「拆一下这条视频的画面」 | `stage-delivery/assets/video-capture/` | 取视频（本地文件 / 直链 URL）＋ 抽帧（双因素 ＋ 首尾 ＋ 补帧） | 关键帧 `frames/` ＋ `frame_times.json`（供①竞品分析、③视觉参考） |
|
||||
| 「获取 XXX 网站的设计风格」「抓这个网站的风格/组件/配色」 | `stage-delivery/assets/design-capture/` | 抓网页设计系统（色彩 / 排版 / 组件），生成样式模板 | 一套 `design-system-<名>/`（与 `design-system-tiaoyue` 同构，可直接被③段 D1 选用） |
|
||||
|
||||
两者都独立可单跑：`video-capture` 只依赖 `ffmpeg`；`design-capture` 只依赖本机 Chrome（CDP）＋ `vendor/` 里搬运的抽取脚本，不需要 open-design daemon 在场。用法与边界见各自 `SKILL.md`，来源与署名见各自 `ATTRIBUTION.md`。
|
||||
|
||||
触发时机：①②段拆竞品视频用 `video-capture`；③段要新建样式或拆参考站用 `design-capture`。
|
||||
|
||||
两个工具都只做合规最小集：不抓平台页内视频，不调付费接口；抽取结果须先目视比对再采用。
|
||||
|
||||
## 进入方式
|
||||
|
||||
| 你说什么 | 模式 | 从哪开始 |
|
||||
|---|---|---|
|
||||
| 「规划 XX」「从零做 XX」 | 全流程（自动处理） | `stage-discovery` → `stage-requirements` → `stage-delivery` → `stage-proto-doc`，一路跑完，段间不停下来问（含①段末） |
|
||||
| 「先确认方案」「跑完方案停下等我」「规划 XX，先给方案」 | 方案确认 | 同一套四段，唯一差别是①段末停下等你确认方案，确认后才进②③④ |
|
||||
| 「只做产品需求」「只做产品功能」「只做界面交互」「只做原型说明文档」 | 单段 | 只调对应那一个 stage skill，不展开其他段 |
|
||||
| 已有②段，要出原型 | 单段 | 直接调 `stage-delivery`，从它的 3a 起 |
|
||||
| 已有原型，要补说明 | 单段 | 直接调 `stage-proto-doc`，从它的 4a 起 |
|
||||
| 只问某个单点 | 单段 | 不跑任何段，在对应 stage skill 内点名子步，或直接说要看哪份方法论 |
|
||||
|
||||
「只调一段」成立的原因：四段之间只通过落盘文件耦合，没有隐式状态。
|
||||
|
||||
- ②只读 `docs/pm/<项目>/research/*` 与 `docs/pm/<项目>/strategy/*`；缺失时标注 `【假设】`继续，不催促回补①
|
||||
- ③只读 `docs/pm/<项目>/prd/*` 与 `docs/pm/<项目>/ux/state-machine.md`；缺失时同样标 `【假设】`继续
|
||||
- ④只读 `designs/<项目>/*.html`，另按需读 `docs/pm/<项目>/prd/*` 与 `docs/pm/<项目>/ux/state-machine.md` 校准术语；缺失时标 `【假设】`继续
|
||||
|
||||
## 执行规则
|
||||
|
||||
只有三种模式，没有第四种：
|
||||
|
||||
| 模式 | 段之间 | 段之内 |
|
||||
|---|---|---|
|
||||
| 全流程（自动处理） | 一路跑完，段间不停下来问（含①段末）。每段结束按「标准收尾格式」输出一段报告，输出完即刻进下一段 | 子步之间不反问，做完直接进下一个子步 |
|
||||
| 方案确认 | 与全流程完全相同，只有一处不同：①段末停下等你确认方案；确认后②③④一路跑完、段间不停 | 同上 |
|
||||
| 单段 | 不涉及 | 不越界，不催促回补前段 |
|
||||
|
||||
这两条是全流程模式下的两个独立分支，不要混：全流程（自动处理）没有①段末的强制停；「停下等确认方案」只在「方案确认」模式下发生。二选一由用户定（界面里点【生成原型和文档】时选「自动处理」或「先确认方案」，或在会话里直接说明）；用户没明说时按自动处理走，不要在自动处理模式下自作主张停下来问。
|
||||
|
||||
「停下」指什么，不要读成「每一步都要反问用户」。只有这四种情况才停：
|
||||
|
||||
1. 信息不足且查不到，必须用户给（如「项目与路径约定」slug 第 4 条）——停下问
|
||||
2. 破坏性 / 不可逆动作——二次确认
|
||||
3. 用户显式要求某个子步做完停下
|
||||
4. ①段末的方案确认（仅「方案确认」模式）——把方案摆给用户：做什么 / 不做什么 / MVP 边界 / 未复核的 `【假设】`，明说「等你确认方案，确认前不进②段」
|
||||
|
||||
段末报告：全流程（自动处理）模式下，所有段（含①）都只输出报告，不提问、不等回答；方案确认模式下①段是唯一例外，其余段同样只输出报告。
|
||||
|
||||
①段末的确认是回环，不是一次问答（仅「方案确认」模式）：用户看到方案后可以提问题要求改，可能多轮，每轮的「问题＋怎么改的」都要留痕、不得覆盖上一轮；改完由用户显式说「确认方案」才算过闸门。该模式下，没拿到用户确认的方案不得当成既定事实带进②段——这是实测踩过的坑：②段拿着未经确认的方案往下跑，把用户已拍板的需求裁掉了。
|
||||
|
||||
其余规则：
|
||||
|
||||
- 声明制（全段适用，不止③段）：开工前、每进一个子段或子步、每处偏离，都要声明三件事——当前在哪、依据哪个文件的哪一节、产出落哪；偏离当场写明原因与影响，段末附偏离单。不许静默偏离。实测踩过的坑：③段 3b 交付了原型却没走当时声明的主流程、没读依据文件，也没当场说，用户追问「基于哪个 skill」才知道。
|
||||
- 不做八股：不介绍方法论来源，不列人名，不复述框架历史，直接给结论。
|
||||
- ⭐ 内容准则：一切落盘文字都要先过「说人话」这一关（2026-10-07 用户定案，同日扩大到规则文件）。用户原话：「当作第一步 和 第二步 生成文档时 必须遵循的内容准则」「不管是写规则 还是 写文档 都要严格按照说人话的技能去执行」。
|
||||
- 适用面两类都算，只改产出不改规则等于半改。一是产出文档：`research/1a-需求文档.md` 到 `1e-使用场景.md`（5 份）、`research/1b-独立分析/`（独立分析体）、`prd/2a-产品功能.md` 与 `prd/2b-界面布局.md`（2 份）。二是规则本身：本技能包内的一切落盘文字，`SKILL.md`、`references/**`、模板与清单。
|
||||
- 判据来源（单一可信源，本文件不复述模式清单）：`humanizer`（55 条模式、5 种口吻档 casual / professional / technical / warm / blunt），`humanizer-zh`（24 条模式、快速检查清单、50 分制评分）。两份技能都在 `E:/ProgramData/.workbuddy/skills/`，完整判据以源技能正文为准。
|
||||
- 门槛：按 `humanizer-zh` 五维评分（直接性 / 节奏 / 信任度 / 真实性 / 精炼度）≥45 / 50 才准落盘；低于 45 回炉重写。
|
||||
- 五条核心原则（源技能《核心规则速查》摘引）：删填充短语（开场白、强调性拐杖词）；打破公式结构（二元对比、戏剧性分段、修辞性设置）；变化节奏（长短交错，两项优于三项，段尾多样）；信任读者（直接陈述事实，跳过软化、辩解、手把手引导）；删金句（读起来像可引用的话，就重写它）。
|
||||
- 交付留证：产出文档在段末报告里写明「已过内容准则，评分 X/50」；改规则文件时，在当日 memory 里记下这一关过了。
|
||||
- 只调一段时不越界：用户说「只做第 N 段」，就跑该段，不展开其他段，也不用「你还没做调研」去催促。
|
||||
- 提问上限 3 个：其余用合理假设，并在文档里标注 `【假设】`。例外是 `grill-me` 提问模式，不受此限（①段的「需求澄清」与②段的「需求压测」各一次），该模式的价值就是穷尽提问；此时须先声明「将连续多轮提问」，退出后恢复本约束。
|
||||
- 反问优先，允许自动补全：`grill-me` 的默认动作是把问题抛给用户并附推荐答案。用户说「你定」、连续两轮不回应、或属事实类问题时，模型自行给答案并标 `【假设】`，换来「不卡住」；但每轮结束要汇出待复核清单，未经复核的 `【假设】` 不得在下游当事实用。
|
||||
- 停线规则（**单一真源，全包只在本节写一次**，各段一律引用、⛔ 不复述）：只有三种情况停 —— ① 信息不足且查不到；② 破坏性／不可逆动作；③ 用户显式要求。
|
||||
- MVP 边界优先：任何阶段都先回答「第一版做什么、不做什么」。
|
||||
- 必须落盘：产出写入文件，不要只在对话里输出。
|
||||
- 无来源就标注：任何查不到来源的数据都标为「估算」并写明口径，不编造数字当事实。
|
||||
- 禁止长文：单份产出物默认一页纸（≤120 行），超长必须拆分。
|
||||
|
||||
## 每段的标准收尾格式
|
||||
|
||||
```
|
||||
## 本段结论
|
||||
- （3-5 条，可直接决策的话）
|
||||
|
||||
## 已落盘
|
||||
- ...
|
||||
|
||||
## 待确认（最多 3 条）
|
||||
|
||||
## 建议下一步
|
||||
→ 用 <skill-name> 完成 <具体事>
|
||||
```
|
||||
|
||||
## 反面清单
|
||||
|
||||
- 为一个小功能跑完整调研
|
||||
- 输出长文却给不出一个结论
|
||||
- 跳过「不做什么」
|
||||
- 用户只问单点，却强行拉进全链路
|
||||
- 把估算数据写成确凿事实
|
||||
- 跳过③段 D0 的 Gate-1（未定死令牌表与设计契约）就开写页面代码
|
||||
- 在 `grill-me` 提问模式下仍套用「提问上限 3 个」，把提问做成走过场
|
||||
- 只跑一次 `grill-me`：①没定义需求就去取证，或②拿①段的需求定义代替功能压测直接写②段
|
||||
- 把自动补全当默认动作：用户没说话就替用户拍板，还没标 `【假设】`、没进待复核清单
|
||||
- 把④的说明区写进产品功能范围，或让③顺手把说明文档一起写了（该调 `stage-proto-doc` 就调）
|
||||
- 手写 Mermaid 代替 diagram-design，手写 token 表代替 DESIGN.md
|
||||
- 绕过四段自己手搓，或重写它们的内容（该调 `stage-*` 就调）
|
||||
- 把两个页面设计技能（`open-design` / `oil-ui-pro`）的内部路径按本 skill 目录去拼，或改它们的正文（它们是技能仓库里的供给技能，改动只写 `stage-delivery` 自己的 `SKILL.md` / `references/`；两个技能平行同层级，不缝成一条流水线，也不把 `oil-ui-pro` 的评分循环当成本段 Gate 的替代）
|
||||
- 猜 `<项目>`：定不出来还硬写，把产物落到别的项目目录下
|
||||
- 把 `DESIGN.md` 写到仓库根：多项目会互相覆盖
|
||||
- 段间停下来问「要不要继续」：全流程（自动处理）模式下直接进下一段，只在段末输出报告
|
||||
- 把两种模式混用：在自动处理模式下自作主张停下问方案，或在「方案确认」模式下确认前就开跑②③④
|
||||
- 在「方案确认」模式下把①段的方案当成已确认就往下跑：该模式下①段末必须停下等用户确认（含「不做什么」）
|
||||
- 下游擅自裁剪上游已拍板项：②③④发现要砍①段或决策表里已拍板的东西时，不许自行裁掉或改口径，必须列成「与已定决策的差异」交用户显式确认
|
||||
- 把模式当成段：模式是「要不要在①段末停」的开关，不是第五个段，别为它单独造段或造产物
|
||||
- 跑了却不说：没声明当前段 / 子步与依据文件，或偏离了被调 skill 的主流程却不声明、不记偏离单（应为：开工先声明、每个子步再声明、偏离当场声明）
|
||||
|
||||
## 改名 / 改供给后的自检
|
||||
|
||||
```bash
|
||||
python scripts/check_naming.py --ws <工作区>
|
||||
```
|
||||
|
||||
它查四段段名与子步名在「总入口 ↔ 各段 `SKILL.md` ↔ 各段 `references/`」之间有没有漂，包括 H1 与子步表是否一致、总入口子步列有没有漏项、runbook 必读表有没有引用已移除的资产、两份副本是否一致。纯静态比对，不需要渲染，不需要外部依赖。
|
||||
|
||||
为什么必须有它：实测当天漏过两次，当时没有任何门禁会报错。
|
||||
|
||||
第一次（2026-10-02）：改段名时 `SKILL.md` 改了，但 `references/stage-discovery/references/grill-me.md` 的 H1 仍写「需求澄清（grill-me · 调研段）」；`references/stage-requirements/SKILL.md` 子步表写「2b 功能流转」而正文 H2 写「## 2b 状态机」；总入口④段子步列只写「4a 说明区 / 演示引导」漏了 4b / 4c。三处都只能靠回读发现。
|
||||
|
||||
第二次（2026-10-06）：②段收窄为「只细化功能」（7 份产出变 1 份）后，各段 `SKILL.md` 都改了，但总入口的三处仍写着旧结构——四段表的②段子步列仍是「2a 功能定义与压测 / 2b 功能流转 / 2c 功能图示」，四段表的①段子步列「1c 产品定位与商业设计」未随段内改名（段内已改称「产品定位与场景」），正文仍写「①与②各跑一次 `grill-me`」并指向两份同名文档，实际全场只有①段一份。闸门当场报 6 个 FAIL，根因是「改了承载段、忘了总入口」。
|
||||
|
||||
由此立一条硬纪律，与「换供给不能只改承载段」同型：凡改子步结构 / 段内产出清单 / 段间交接口，必须连带改总入口 `product-planning/SKILL.md` 的「四段结构」表与「交接口」表，不改就是半改状态。
|
||||
|
||||
改了段名 / 子步名 / 判据供给源之后必须跑一次，并把结果记进当日 memory。改完不校验，下次读契约的人拿到的是错的配方。
|
||||
|
||||
本脚本只查文本一致性（H1 ↔ 子步表 ↔ 总入口 ↔ 副本），查不出「判据口径是否自相矛盾」。例如「②段到底该不该给页面结构」这种反转，闸门一个字都报不出来。口径类改动要靠人工回读，且必须把反转理由与用户原话写进文档留痕。
|
||||
|
||||
脚本输出里的 `[提示]` 项（旧名出现）不计入失败，但要人工看一眼是不是落在「废止理由块」里——落在里面是正当留痕，散落在正文里就是真残留。
|
||||
|
||||
2026-10-07 起本技能只在全局一份：`E:/ProgramData/.workbuddy/skills/product-planning/`。它就是本体，不再有「主 / 副 / 装入」三副本，也不再需要「三处 md5 复核」（那只在有副本时才有意义）。改完只跑一次 `check_naming.py --ws <工作区>`。用户原话：「把产品规划复制到 workbuddy 全局skills中 后续维护和使用全局技能」。工作区原先那三份已归档到 `归档/技能迁全局-20261007/`（未直删，可随时取回）。
|
||||
@@ -1,377 +1,384 @@
|
||||
---
|
||||
name: stage-delivery
|
||||
description: 产品规划第③段，界面交互。设计工程供给默认来自 oil-ui-pro（方法主线与独立评审）加本段自带样式库（定调与令牌），另有可选供给档（本段自带、可选择使用；供给关系见正文 §供给）：先落设计契约与令牌表（Gate-1 硬闸），再构建页面，再收口/动效/终检（Gate-2/3），中途加一轮 GPT 参考版。判据结构为「正向目标为主、禁令只留最关键三条」。当用户要做 UI 规范、设计系统、页面原型、交互动效、界面审查、视觉打磨，或说"只做界面交互"时调用。
|
||||
---
|
||||
|
||||
# ③ 界面交互
|
||||
|
||||
回答两个问题：长什么样、怎么操作。产出 `docs/pm/<项目>/DESIGN.md` 与 `designs/<项目>/*.html`。
|
||||
|
||||
> 段名为什么是「界面交互」（2026-10-02 定）：
|
||||
> 删「交付」：①②③都产出落盘文件，「交付」是三段共有的属性，不是③的专属；④段也在交付（原型的说明区），留着会让人以为③管完就结束了。
|
||||
> 补「交互」：本段原先只讲「长什么样」，可 3b 原型硬要求每个按钮、每个跳转都真能走（`:236`），3c 的参考版对照也要逐项看空态 / 加载 / 错误 / 反馈（`:148`、`:150`）。交互判据一直在做，却没有名字，补上才与本段实际职责相符。
|
||||
> 与④段的界：③造物（界面与交互本身），④描述物（说明区与演示引导）。
|
||||
|
||||
> `<项目>` 按 `product-planning` 的「项目与路径约定」定；定不出来就停下问用户，不许猜。`DESIGN.md` 放项目目录，不放仓库根，避免多项目互相覆盖。
|
||||
|
||||
## 供给（唯一权威处 · 改供给只改这一块）
|
||||
|
||||
> 🔴 ③段的供给关系**只在本块定义一次**。本文件其余章节、`references/execution-runbook.md`、`references/layouts-tooling.md`、以及总入口 `product-planning/SKILL.md`，提到供给时一律**引用本块的行名**（写成「见 §供给·定调与令牌」这样，行名就取下面那张表的左列），⛔ 不许再复述「谁是默认、路径在哪、装了才有」。
|
||||
> 改了供给 ⇒ 只改本块，然后跑 `scripts/check_naming.py`；发现别处有复述 ⇒ 删掉、改成引用。
|
||||
> ⚠️ 边界：本块管「有哪几档、谁默认、路径从哪个根起」。各档内部的具体篇目（如可选档工艺判据下的某一篇）属执行细节，留在 `references/execution-runbook.md` 各步里 —— 那些不算复述，改档不会牵动它们。
|
||||
> ⚠️ 为什么立这一块（2026-10-08 用户定）：此前这一个事实被复述约 40 处，改一次（默认主线由 `open-design` 换成 `oil-ui-pro`）动三份文件 17 处，仍然漏掉 13 处口径 —— 那是复述式写法必然的代价。单一可信源才拦得住漏改。
|
||||
|
||||
| 供给位 | 默认来源 | 可选来源 | 管什么 | 用在哪 |
|
||||
|---|---|---|---|---|
|
||||
| 方法主线 | `oil-ui-pro`（全局技能，按技能名引用） | 无 | 方向探索 → 建结构 → 取实证 → 独立评审打分 → 验证交付 | 全段；3a / 3d 最重 |
|
||||
| 定调与令牌 | 自带样式库 `assets/design-systems/<选定一套>/`（随段携带，现 1 套 `design-system-tiaoyue`） | `assets/open-design/design-systems/<选定一套>/`（153 套） | 调性、全套令牌、组件形态。⚠️ **能力边界（2026-10-08 实测补充）**：自带样式库实测只到**调色板级** —— 语义色 / 圆角 / 字体栈 / 按钮与输入框令牌；**几何与版式不在包内**（栏宽、项高、内衬、间距、组件尺寸一律没有），参考 `design-system.html` 里也**不含源站的界面骨架**。⛔ 不许把「供给在位」读成「已经有设计系统了」；要几何就**回源站实测**或另找来源，拿不到就在 3d 里明说无来源 | 3a 的 D1 |
|
||||
| 版式骨架 | `references/layouts-tooling.md`（工具型页面用） | `assets/open-design/design-templates/web-prototype/`（营销页向；工具型⛔ 不许套） | 工具型九档的名单与判读见 `references/layouts-tooling.md` §0（⛔ 本块不复述名单；2026-10-08 追加「导航栏」一档 = §4.9） | 3b |
|
||||
| 工艺数值判据 | `references/execution-runbook.md` §3.4 ＋ `references/layouts-tooling.md` §5.5 | `assets/open-design/craft/`（13 份） | 字阶 / 配色 / 状态齐备 / 动效纪律 / 反 AI 味 / 无障碍。⚠️ **未选可选档时，后四项（反 AI 味 / 无障碍 / 动效纪律 / 表单校验）没有供给来源** ⇒ 必须在 `3d-审查报告.md` 里逐项显式记为**本段证据缺口**（写「无供给来源，本项未判」），⛔ 不许默不作声地跳过、也⛔ 不许拿别的判据冒充它过了 | 3a 判据、3d 终检 |
|
||||
| 独立评审协议 | `oil-ui-pro` 的 `references/visual-review.md` ＋ `references/tools.md` | 无 | 没看过制作过程的评审打分 ＋ 截图取证 | 3d |
|
||||
| 多方向比选 | `oil-ui-pro` 的 `references/design-direction.md` ＋ `references/style-explorer.md` | 无 | 方向卡与风格对比页 | 3a 按需 |
|
||||
|
||||
> 🔴 供给是**分层**的（2026-10-08 用户定案）：`oil-ui-pro` 是**基础层** —— 视觉与体验的底线判据都出自它；其余各档（定调与令牌 / 版式骨架 / 工艺数值判据 / 本段自有的 `execution-runbook.md` 与 `layouts-tooling.md`）都是**叠加层**：可以在它之上叠加更多设计规范，只许**更严、更具体**，⛔ 不许**放宽或推翻**基础层。叠加层与基础层冲突 ⇒ **以基础层为准**。
|
||||
|
||||
> ⭐ 可选来源只有一处：`open-design` —— **随段携带的本地裁剪件**（源 `nexu-io/[email protected]`，Apache-2.0；署名与裁剪说明见 `assets/open-design/ATTRIBUTION.md`，装在 `assets/open-design/`）。它是**独立技能、可选择使用**：选了才用，不选不影响本段开工。
|
||||
|
||||
`open-design`（上面那张表的可选来源）给三处，都在 `assets/open-design/` 下：
|
||||
|
||||
1、`design-systems/<选定一套>/`：`DESIGN.md` 定调性 ＋ `tokens.css` 给全套数值（圆角与阴影在这里）＋ `components.html` 给组件形态。
|
||||
|
||||
2、`craft/`：字号刻度 / 配色配额 / 状态齐备 / 动效纪律 / 反 AI 味 / 无障碍。
|
||||
|
||||
3、`design-templates/web-prototype/`：种子 `assets/template.html` ＋ 8 个版式骨架 ＋ 自查清单。
|
||||
|
||||
⭐ 选了自带的 `design-system-tiaoyue` 时怎么读（⚠️ 套内命名与 `open-design` 不同形，别按 `DESIGN.md` 去找）：
|
||||
|
||||
| 要什么 | 套内路径 |
|
||||
|---|---|
|
||||
| 入口（规范总纲、生成时的参考范围） | `assets/design-systems/design-system-tiaoyue/SKILL.md` |
|
||||
| 令牌（含暗色一套） | 同目录 `assets/tokens.css` ＋ `assets/tokens-dark.css`（色值原始记录 `assets/brand.json`） |
|
||||
| 组件形态 | 同目录 `references/components.md` ＋ `references/design-system.html`（组件族清单 `references/library.json`） |
|
||||
| 已知冲突 / 取舍记录 | 同目录 `references/known-conflicts.md` ＋ `references/capture-notes.md` |
|
||||
|
||||
> ⚠️ 路径怎么找：自带件一律按**段内相对路径**引用（`assets/open-design/...`、`assets/design-systems/...`），⛔ 不按绝对路径爬、⛔ 不写死 `../` 层数；`oil-ui-pro` 按技能名引用（宿主按名加载，与物理位置无关）。
|
||||
> 🔴 定调来源唯一：每次设计只选一套，默认与可选**不混用**（混用 = 没有调性）。套名与选择理由写进 `DESIGN.md`。
|
||||
> ⛔ 判据正文仍只在本段（`references/execution-runbook.md` 与 `references/layouts-tooling.md`）。⚠️ 供给是分层的，分层定义见 §供给：`oil-ui-pro` 是**基础层**，本段自有判据是**叠加层**；同一条判据两处都有且口径不同时，⛔ 本段不许放宽基础层，只许更严、更具体，并在 runbook §3.4 标注「本项目追加」。
|
||||
> ⛔ 不许把 `oil-ui-pro` 的评分循环当成 D 阶段的替代：它是评审方法，Gate-1/2/3 该过还得过。
|
||||
> ⛔ 不动用可选来源时，⛔ 不许凭感觉编一套顶上（那正是本项目反复踩的坑）；craft 独有的那几项（反 AI 味 / 无障碍 / 表单校验 / 动效纪律）明说「本次无供给来源」。
|
||||
> ⚠️ `oil-ui-pro` 自带联网版本检查与自动更新（每次使用会连 `ui.oiloil.org`，发现新版用 `npx` 覆盖自身目录）。这是本项目收录时用户明确要求全量搬入的例外项，与「依赖外部服务一律不收」的既有纪律冲突，记录在案，不扩散到其他技能。想关掉设环境变量 `OIL_NO_UPDATE_CHECK=1`。
|
||||
> 供给件都不依赖付费云 / MCP / API Key 才能用于设计：`open-design` 去掉那些之后剩下的全是静态 md / css / html（其 daemon、云模型服务、`packages/components` 的 tsx 未收录）；`oil-ui-pro` 的设计方法宿主中立、离线可用（联网仅用于版本检查）。
|
||||
> 冲突处以 §供给·方法主线（基础层）为准；本段自有判据与 `DESIGN.md` 是叠加层，只许更严，⛔ 不许与基础层相反。供给件的价值在给正向目标、给方法。
|
||||
|
||||
> 为什么换掉原来的主干（2026-10-02 用户定案）：原主干 `ui-page-design` 已从磁盘移除，③段只剩规则壳，壳里又全是减法型判据，机检能判「不违规」却判不出「好看」，18 轮回改把页面越推越白。换供给的同时必须换判据结构：正向目标为主，禁令只留最关键的。
|
||||
|
||||
> ⭐⭐ 本段在②段给定的骨架里做视觉与交互（2026-10-06 用户定案）。
|
||||
>
|
||||
> 口径：②段钉骨架，③段做皮肉。
|
||||
>
|
||||
> 🔴 「②段管什么、本段管什么」的完整清单（含两侧逐行对照）只在②段 `references/stage-requirements/SKILL.md`
|
||||
> 的 §②—③ 交接口 定义一次 —— ⛔ 本文件不复述那张表，免得两处漂。用户原话也放在那一节，此处不再抄。
|
||||
>
|
||||
> 🔴 旧口径站不住的地方：它把「有哪几页」留在本段，于是本段做一版一个样，②段手里没有任何东西能判断本段改得对不对。
|
||||
> ⭐ 本段拿到的骨架是冻结的：⛔ 不许新增 / 移动 / 删除板块。缺板块要回②段改②段（见「硬约束」的对应禁令）。
|
||||
>
|
||||
> 仍在本段手里的两个字段（它们在给定骨架之内决定怎么摆得好看）：
|
||||
> - `必要内容`（减法）：⚠️ 口径已调整。它不再决定哪些内容上屏（那是②段分档表的活），而是核对②段给的信息是否都在骨架里有落点；⛔ 本段不得以它为由增删信息档位。
|
||||
> - `结构骨架`（加法）：⚠️ 口径已调整。它不再独立决定几个区块，而是把②段给的板块清单翻译成具体的骨架档 / 列宽 / 密度目标（骨架档选哪个、密度多少，仍是本段的活）。
|
||||
>
|
||||
> ⛔ 本段不许回头改②段的骨架（那是②段）；⛔ 也不许无视②段骨架自己另起一套。判据：D0 里的页面清单与每页板块，必须与②段《界面布局》逐条对得上；对不上就停下来问②段要哪一版。
|
||||
|
||||
顺序 3a → 3b → 3c → 3d。先有规范再出原型，不许反过来；原型能点通后先取一份外部参考版，再收口打磨。
|
||||
|
||||
> 照 `references/execution-runbook.md` 逐步走。那是本段的固化执行手册：按 D 阶段排的必读表、每步验收判据、脚本跑法、偏离单格式、完成标准清单都在里面。本文件写规则，手册写顺序与验收。
|
||||
> 开工前先声明、每进一个子步再声明、偏离当场声明（三字段：当前子步 / 依据文件 + 小节号 / 产出落点）。这条不可商量。
|
||||
|
||||
## 子步与产物
|
||||
|
||||
| ③段子步 | 做什么 | 产物 | 闸 |
|
||||
|---|---|---|---|
|
||||
| 3a 视觉规范 | 定契约（减法 + 加法）→ 定调（选定设计系统）→ 落令牌表〔方法主线按 `oil-ui-pro` 的方向探索走；要拉开方向让用户挑时用它的对比页〕 | 设计契约 + 令牌表 → `DESIGN.md` | Gate-1 方向门 |
|
||||
| 3b 原型 | 按模板种子 + 版式骨架构建 | `designs/<项目>/<原型>.html` | — |
|
||||
| 3c GPT 参考版 | 让 GPT 按需求＋风格**独立生成一版当参照物**（本段特有，两个设计技能都不覆盖） | `3c-GPT参考版.md` | — |
|
||||
| 3d 审查与打磨 | 收口 → 动效 → 终检〔按 `oil-ui-pro` 的评审协议做一轮独立评审打分〕 | file:line 清单 + `3d-审查报告.md` | Gate-2 / Gate-3 |
|
||||
|
||||
挡位开工前定一次，默认标准：纯原型可降快速（定契约 → 定调 → 构建 → 终检）；常规页面走标准（全跑）；对外页面走严格（三闸全开 + 中间产物落盘）。
|
||||
`Gate-1` 与 `Gate-3` 是硬闸，任何挡位都不可跳，哪怕只做原型，也要打开看一眼。
|
||||
|
||||
## 三条铁律（只留不可省略的）
|
||||
|
||||
| # | 铁律 | 违反后果 |
|
||||
|---|---|---|
|
||||
| 1 | 先定死，再写码。未产出设计契约与令牌表前，禁止写任何组件代码；禁止边写边调样式。 | 返工、风格漂移 |
|
||||
| 2 | 状态穷举。`loading / empty / error / success / disabled / 无权限` 逐项给结论（判据见 §供给·工艺数值判据）。 | 上线即翻车（最高频漏项） |
|
||||
| 3 | 不渲染不算完。交付前必须在真实环境渲染一次并肉眼确认。 | 裁切/重叠/失效控件逃过检查 |
|
||||
|
||||
> 禁令就这三条，其余一律去 §供给·工艺数值判据 里查（默认档按本段两份的对应章节；可选档按其工艺篇目，逐篇见 §供给·工艺数值判据）。
|
||||
> ⛔ 不在本文件里抄写禁令清单。抄了就变两份，两份必然漂；更要紧的是，抄禁令会把正向目标挤出视野，这正是改版前③段只剩「不要什么」、页面越改越白的根因。
|
||||
> 一条例外（本项目特有，供给件里没有）：结构性容器靠底色差 + 阴影分层，不挂围合边框（来源：本项目 E-62 / E-63 实测）。当选定设计系统写「卡片描边」时，以本条为准。
|
||||
> 限载：同一时刻只读 1~2 份供给原文，用完释放。这条不再单列铁律，但仍是硬约束（可选档定调候选与工艺判据份数都不小，全读必然互相稀释）。
|
||||
|
||||
## 必读（限载：一次只读 1~2 份，用完释放）
|
||||
|
||||
| 环节 | 取哪些供给位（定义见 §供给） |
|
||||
|---|---|
|
||||
| 3a 方法主线 | §供给·方法主线 |
|
||||
| 3a 定调 | §供给·定调与令牌（默认档；要用可选档就在 `DESIGN.md` 写明理由）。入口 / 令牌 / 组件形态按 §供给 里的「套内怎么读」取 |
|
||||
| 3a 判据 | §供给·工艺数值判据（本项目追加条在 `references/execution-runbook.md` §3.4） |
|
||||
| 3a 多方向比选（按需） | §供给·多方向比选 |
|
||||
| 3b 构建 | §供给·版式骨架 ＋ §供给·工艺数值判据（工具型只取默认档） |
|
||||
| 3d 独立评审 | §供给·独立评审协议 |
|
||||
| 3d 终检 | §供给·工艺数值判据 ＋ §供给·版式骨架 |
|
||||
|
||||
> ⚠️ 3b 只取 §供给·版式骨架 的默认档。可选档那套（`web-prototype`）是营销落地页向，只在判「要不要套它的流程」时读。
|
||||
> ⚠️ 本表只写「哪一步取哪个供给位」，⛔ 不写路径、不写默认判断 —— 那些只在 §供给 定义一次。
|
||||
> 本段 `references/` 只放流程规则，⛔ 不放风格；随段携带的样式风格一律放 `assets/design-systems/<套>/`（🔴 2026-10-07 用户令两条：「把 `design-system-tiaoyue` 整合到 `product-planning` 作为一种样式风格」＋「后续可以添加多种风格，每次只能选择一种进行设计」⇒ 只把「不放风格」这条放宽到 `assets/`，`references/` 仍不放）。
|
||||
> ⚠️ 续加新风格时的硬要求：目录名与可选档同形（`assets/design-systems/<套名>/`），套内自带入口文件（`SKILL.md` 或 `DESIGN.md`）；⛔ 不许改已入套的文件内容，原样搬入、只在本文件登记去向。
|
||||
> 🔴 定调来源唯一（两档见 §供给·定调与令牌）：每次设计只选一套，⛔ 不许混用两档（混用 = 没有调性）。套名与选择理由写进 `DESIGN.md`。
|
||||
> 既有项目中凡引用旧风格来源（`minimalist-ui` / 皮肤族 / `ui-ux-pro-max` 检索结果）的 `DESIGN.md` 行，重跑 3a 时一律改写为选定套 + 留痕对照。
|
||||
|
||||
## 3a 视觉规范（定契约 + 定调 + Gate-1）
|
||||
|
||||
第 0 步 · 供给核对（每轮必做，防漂移）：按 §供给 逐档核对在位 —— 默认档必核，可选档**选了才核**（其可选来源那三处，见 §供给 表）。核完把选定套名与 `DESIGN.md` 里记录的上次套名比对。
|
||||
|
||||
- 一致 → 直接定契约。
|
||||
- 不一致或供给缺失 → 先停下报告，⛔ 不许拿别的套顶上，也不许凭记忆写风格。把差异列成「供给变更清单」，在会话里向用户呈现并确认后，再改 `DESIGN.md`，把新套名与清单写进修订记录。
|
||||
- 本步存在的理由：`DESIGN.md` 是上一次供给状态下产出的。供给换了却没核对，就会长期拿着旧调性当准绳。
|
||||
|
||||
D0 锚需求：按 `references/execution-runbook.md` §2.1 的契约模板产出设计契约（十二个字段）。字段清单与逐条判据以 §2.1 为准 —— ⛔ 本文件不重复列，免得两处漂。
|
||||
|
||||
> ⭐⭐ 第十二字段「交互清单」是 2026-10-02 新增，段名改名的直接后果（段名从「界面与交付」改成「界面交互」，但「交互」在流程里此前没有落点：可点通在 3b、查反馈在 3c、动效在 3d，三处各判一部分，谁也不负责整体）。
|
||||
> 它写什么：逐个可点元素一行，四列——元素（哪个）｜触发（点了/输了/滚到哪，发生什么）｜反馈（状态怎么变、给什么提示、多久消失）｜何时不可点（哪些条件下 `:disabled`，条件是什么）。
|
||||
> 它不写：动效参数（归 3d 按 §供给·工艺数值判据）、视觉样式（归令牌表）、状态六项的有无判定（归下一字段 `状态覆盖`，本字段只写「这个元素可点时点了会怎样」）。
|
||||
> 为什么是契约字段而不是新子步：交互一旦单独成文，就会与 `必要内容`、`状态覆盖` 三处互相矛盾——这正是记忆里「同一事实多处落点必然打架」的病。收进契约 = 一个字段、一处裁决、一个门禁。
|
||||
> 判定「漏没漏」：页面里每一个能点的东西都必须在这张表里出现。表里没有 ⇒ 它不该可点（改成静态文本，或回 D0 补进 `必要内容` 再点）。
|
||||
|
||||
D1 定调：从 §供给·定调与令牌 的默认档里选一套；要用可选档就从可选档里选（⛔ 每次只选一套，两档不混用），不凭感觉编，也不全读：
|
||||
|
||||
- 怎么选：按本项目的页面类型挑。读候选套 `DESIGN.md` 的第 1 章 `Visual Theme & Atmosphere`，认准写明该类的那一句（工具型数据密集界面 ⇒ 认 `data-dense, enterprise` 这类描述）。可选档的候选分两代模板（A 组 / B 组章节名不同），按自己那套的章节读，不必统一。
|
||||
- ⚠️ 选了自带库那套（`design-system-tiaoyue`）时：套内没有 `DESIGN.md` ⇒ 读它自己的 `SKILL.md`（规范总纲 ＋ 生成时的参考范围）＋ `references/known-conflicts.md`（已知取舍）；入口 / 令牌 / 组件形态按 §供给 里那张「套内怎么读」表取，⛔ 别按可选档那套的三件套去找。
|
||||
- 选定后读三件：`DESIGN.md`（调性 + 色值 + 字号刻度 + 间距刻度 + 动效基调）→ `tokens.css`（圆角与阴影只有这里）→ `components.html`（组件实际长相）。
|
||||
- 要换风格 ⇒ 下一轮重跑 D1 重选一套，旧套留痕（用户 2026-10-07：「后续可以添加多种风格，每次只能选择一种进行设计」）。
|
||||
- 没找到匹配的套 ⇒ 换一个类型词再挑一次；仍不行就直说「未找到匹配」，不许拿泛化结果当结论落盘。
|
||||
- ⚠️ 工具型页面的版式不在可选档的模板里（可选档是营销页向；骨架名单与理由见 `references/layouts-tooling.md` 开头）。工具型页面的版式由 D0 的 `结构骨架` 字段决定，不从模板抄。
|
||||
|
||||
- 产出令牌表：色值 / 字体（标题字体是关键项）/ 间距两档（主刻度 `4/8/16/24/32/64` 供布局 + 控件层微网格 `2/4/6/8/12` 仅供按钮内衬、徽章内衬、图标间隙、开关与进度轨微几何）/ 圆角 / 字阶定值表（七档各一个 px，不是区间）/ 高度层级（每层都有多层叠层值）/ 布局脚手架（骨架档落到具体列宽 + 窄屏变化）/ 组件规格（按钮三档 + 卡片两档 + 输入框 + 徽章的具体高度与内衬；实底底色 ≥2 种）/ 动效基调——全部为具体值，禁止「待定」，每档只许一个定值
|
||||
|
||||
落盘 `docs/pm/<项目>/DESIGN.md`：令牌表内容并入本项目既有的三层 token 结构（primitive → semantic → component；组件只引语义层、语义层只引 primitive），设计契约作首节。`DESIGN.md` 是原型的绑定规范，原型只许引它的 token。
|
||||
|
||||
Gate-1 方向门（硬闸，不可跳）——按本表逐项自检（字段定义与填写位见 `references/execution-runbook.md` §2.1；⛔ 供给件没这一项，十二字段只能在此判）：
|
||||
|
||||
| 检查项 | 通过条件 |
|
||||
|---|---|
|
||||
| 设计契约 | 十二个字段全部填写，无一为空或「待定」；有重复项时重复项的信息量已逐条列出次级信息 |
|
||||
| 页型判定（2026-10-05 新增） | 已写出「营销页还是工具型页面」+ 依据；工具型页面的 D0 里零 `.eyebrow` / 零 `.lead` / 零 `.hero` |
|
||||
| 结构骨架（加法面） | 骨架档 / 区块划分 / 密度目标三者已写；区块 ≥2 个且每个有文字标题；`必要内容` 每条都有归属区块 |
|
||||
| 交互清单（加法面，2026-10-02 新增） | 页面上每一个可点元素都在表里（元素 / 触发 / 反馈 / 何时不可点 四列齐全）；表里没有的可点元素为 0 |
|
||||
| 状态覆盖 | 六个状态逐项有结论（勾选，或「不适用 + 理由」） |
|
||||
| 令牌表 | 色值 / 字体 / 间距两档且适用面已分开写 / 圆角 / 阴影全为具体值 |
|
||||
| 字阶定值表 | 七档每档一个 px 定值（不是区间）；相邻档差 ≥2px；每档只许一个定值 |
|
||||
| 高度层级 | 每层都有多层叠层值；同层级同值 |
|
||||
| 布局脚手架 | 骨架档已落到具体列宽；窄屏变化写具体 |
|
||||
| 组件规格 | 按钮三档 + 卡片两档 + 输入框 + 徽章均为具体值；同一父区块内主档 ≤1；实底底色 ≥2 种 |
|
||||
| 供给核对（本项目附加） | 按 §供给 逐档核对在位（默认档必核，可选档选了才核）；选定套名与 `DESIGN.md` 记录一致；不一致则变更清单已确认并写入修订记录 |
|
||||
| 反 slop | 无紫→粉渐变、标题未用禁用字体、强调色已写明允许位置 |
|
||||
| 拒绝清单 | ≥3 条，且每条可判定 |
|
||||
| token 引用完整性（本项目附加） | 语义层只引 primitive、组件层只引语义层、无孤立 token |
|
||||
|
||||
任一项不过 → 停在 3a 补齐，不进 3b。
|
||||
|
||||
> 对比度门槛见 §供给·工艺数值判据 里配色那一份（数值登记在 `references/execution-runbook.md` §3.4 的数值判据段），由终检阶段按真实像素复测（静态算不准 CSS 变量叠加后的结果）。
|
||||
> 已知环境问题：`npx @google/design.md lint` 在本机完全不可用（alpha + clack 交互库，非 TTY 管道下静默且 exit 0）。不要拿它当校验关卡，也不要因它无输出就认为通过。
|
||||
|
||||
## 3b 原型（构建）
|
||||
|
||||
> ⛔ 开工前先判页型（2026-10-05 新增，硬前置）：写下「本页是营销页还是工具型页面，依据是什么」。
|
||||
> 两种页型的目的不同，骨架不能通用：营销页目的是说服（主张 → 论据 → CTA），工具型页面目的是完成一件工作（数据 + 操作）。
|
||||
> 判别口径：要用户「下决心去做某事」⇒ 营销页；要用户「把这件事做完」⇒ 工具型页面。⚠️ 判不准时按工具型处理（默认取严）。
|
||||
> 判不出来不许进 3b，停下来回改 D0 的 `结构骨架`。
|
||||
> 🔴 为什么这条是硬前置：§供给·版式骨架 可选档那套的种子 `assets/template.html` 是营销落地页骨架，自带 `.eyebrow`（眉标）与 `.lead`（副标题）。不判页型就照种子做，会得到「标题上方一行小字 + 大标题 + 下方一行灰色小字」的三段式——那是 2026-10-05 用户实测指出「像实习生画的」的唯一根因，而且结构判据全绿（判据判类名合法性，判不出「这不是工具界面的排版」）。页型不判，后面换什么设计系统都救不回来。
|
||||
|
||||
要选可选档时，可按它那份 `SKILL.md`（§供给·版式骨架 的可选档）的六步走：读种子 → 把 `assets/template.html` 复制成 `index.html` 并替换 `:root` 令牌 → 先定版式节奏再粘骨架 → 填充 → 自查 P0/P1/P2 → 落盘。不选它就按默认档（`references/layouts-tooling.md`）的骨架与落地自检走。两条路线都要求「先选定一个明确的美学方向再写码」，与铁律 1 同向。
|
||||
|
||||
- ⭐ 工具型页面先判形态，再挑骨架（2026-10-02 新增）：读 §供给·版式骨架 的默认档。本项目是工具型数据密集界面，可选档那套是营销页向、与本项目不匹配（名单与理由见 `references/layouts-tooling.md` 开头）。
|
||||
⚠️ 两份工具型文件的分工（2026-10-05 补）：本技能 `references/layouts-tooling.md` 给可粘贴 HTML 骨架 + 逐条判据正文（§5.5），是默认档；选了可选档时，它那份 `tooling.md` 另给四形态判定句 + 通用红线纲要，只作指路。⛔ 判据只在 `layouts-tooling.md` 展开，`tooling.md` 只指路，两处展开必然漂。
|
||||
形态判定一句话：页面上能数出「并列的同类记录」⇒ 列表型（工具型默认首选）；数不出、页面围绕单个对象展开 ⇒ 详情型；主操作要在两个工作面之间来回 ⇒ 侧区型。
|
||||
⛔ 不许拿营销页骨架顶替工具型，那是「没做形态判定」的默认行为，等于退回 18 轮前的病根。判不出形态就去改 D0 的 `结构骨架` 字段，⛔ 不许随手挑一个。
|
||||
- 不许从零手写 `<section>`：先挑最接近的骨架粘进去再改。用了可选档时，可选档那套的 `layouts.md` 开头的类清单（`section` / `container` / `card` / `btn-primary` / `grid-3` …）必须在种子 `template.html` 的 `<style>` 里存在；缺哪个就补进 `<style>`，⛔ 不许在标签上内联一堆临时样式。
|
||||
- 输出形态：单文件 HTML、自包含、双击可开（与 `web-prototype` 的产出契约一致：只有 `index.html` 一个文件），含全部适用状态，不许有死按钮。
|
||||
|
||||
重大改版必须复制副本再改（`X.html` → `X v2.html`），不许覆盖旧版，旧版留在磁盘上以便对比。这是本项目的附加纪律（版本管理主线需要可追溯），供给件未涉及。
|
||||
|
||||
交付前必须实测（本步硬关卡）：用 `browser-harness` skill 按清单逐个真点，以 D0 契约的「交互清单」为唯一清单（⛔ 不用自己临场编的顺序）：每行按「触发 → 反馈」实跑一遍，四态（空 / 加载 / 错误 / 失败重试）都要走到；回报控制台报错原文与「点了没反应」的元素清单。
|
||||
|
||||
> 交互清单在这一步才第一次被验证：Gate-1 只判「表写全了没」，判不了「真能跑」。清单与实现对不上，就是清单错了或实现错了，二者必居其一，都要在 `3d-审查报告.md` 里留痕，不许静默改表。
|
||||
|
||||
> 脚本查不出死按钮（即便脚本在位，它也只判溢出 / 对比度 / 状态可见性 / 点击目标尺寸，判不了「元素没绑事件」）。未跑实测不得进 3c，也不得报完成。
|
||||
> 实测一律走 `browser-harness`（浏览器入口 9333），禁用 Trae 自带浏览器工具。
|
||||
|
||||
## 3c GPT 参考版（必做）
|
||||
|
||||
触发点：原型初稿出完、3b 的浏览器实测过了，立刻做本步；做完才许进 3d。
|
||||
|
||||
做什么：用 `browser-harness` skill 打开 `chatgpt.com`，把**需求（②段）＋ 设计风格（`DESIGN.md` 的定调与令牌）**交给 GPT，让它按自己的理解**生成一版 HTML 当参考** —— ⛔ 不是让它审查我们的稿（GPT 最好的用法是「给需求和设计风格、让它生成一版」，不是「让它挑我们的毛病」）。取回后与本段方案逐块对照，取长补短。③段前三步全是本地确定性检查、没有外部视角；让外部模型独立出一版，比让它评论我们的稿更能暴露「我们没想到的做法」。
|
||||
|
||||
执行步骤：
|
||||
|
||||
1. 沿用用户已登录的浏览器会话打开 `chatgpt.com`。不要新建账号、不要代填密码、不要碰设置页。
|
||||
2. **在消息里内联需求与风格**：把②段的「功能清单 ＋ 界面布局」要点、`DESIGN.md` 的定调一句话与令牌表（主色 / 底色 / 字体 / 间距刻度 / 圆角 / 字阶 / 密度）逐段贴进去。⛔ 不要上传我们的原型 HTML —— 那会把它锚在我们的做法上，拿到的就不是独立版本了。
|
||||
3. 发这段提问模板：
|
||||
|
||||
```
|
||||
你是资深产品设计师。请按下面这份「需求 ＋ 设计风格」，独立设计并给出一个可运行的单文件 HTML
|
||||
（内联 CSS，不要外链任何资源），作为我们的参考版本。
|
||||
|
||||
需求：<②段的功能清单 ＋ 界面布局>
|
||||
设计风格：<DESIGN.md 的定调 ＋ 令牌表：主色/底色/字体/间距刻度/圆角/字阶/密度>
|
||||
|
||||
要求：这是工具型页面（数据 ＋ 操作，不是营销落地页）；把主要页面的形态都做出来；
|
||||
状态（空 / 加载 / 错误 / 禁用）要落地；页面要能在浏览器里真实打开。
|
||||
|
||||
请在代码之前先用三句话说明：你把主视觉放在哪、为什么这么排、和你见过的同类产品有什么不同。
|
||||
```
|
||||
|
||||
4. 等回答出完再取（停止生成按钮消失或出现复制按钮），把 HTML 与那三句话原文取回，不要读一半就走；回答被截断就先让它分页给全再取。
|
||||
5. 落盘 `designs/<项目>/3c-GPT参考版.md`，三段式：提问原文（含贴进去的需求与风格）→ 模型回答原文（含三句话说明 ＋ 完整 HTML，HTML 放代码块）→ **对照表**。
|
||||
|
||||
对照表固定四列：
|
||||
|
||||
| # | 参考版的做法（原文摘句 / 截图） | 我方处置 | 理由 | 若采纳，落在哪 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | ... | 采纳 / 不采纳 / 待议 | 对照 `DESIGN.md`、②段与基础层（`oil-ui-pro`）说清 | 文件 + 选择器 |
|
||||
|
||||
功能作用：让一个不带本项目上下文的模型独立出一版，给我们一个「别人会怎么做」的参照物 —— 比让它评论我们的稿更能补盲区。
|
||||
|
||||
输入边界：只传②段需求与 `DESIGN.md` 的定调 / 令牌；不传密钥、真实用户数据、内网地址、`.env`。⛔ 不传我们的原型 HTML（会锚住它）。一次只做一份参考。
|
||||
|
||||
异常情况：登录失效 / 人机验证 / 网络不通 / 回答被截断时，不要假装跑过。退路是把提问模板（含需求与风格文本）交给用户，由用户在自己浏览器里问，再把回答粘回来落盘。仍然取不到时，在 `3c-GPT参考版.md` 里写明「本轮未取得参考版」，并在本段收尾时明示，未取得不等于已通过。
|
||||
|
||||
处置纪律：参考版不是命令，是参照物。采纳要给理由；与 `DESIGN.md`、②段或基础层（`oil-ui-pro`）冲突的，写清为什么不采纳。采纳项在 3d 之前改完，并回到 3b 的实测清单把这些改动再点一遍。
|
||||
|
||||
## 3d 审查与打磨（收口 + 动效 + 终检 + Gate-2/3）
|
||||
|
||||
### 收口（管「写得对不对」）
|
||||
|
||||
对照 §供给·工艺数值判据 逐条过（默认档：本段 `references/execution-runbook.md` 的验收判据 ＋ `references/layouts-tooling.md` §5.5；选了可选档另按其终检清单 P0 / P1 / P2 三级与字阶 / 配色 / 状态齐备 / 动效四份数值判据）。先机器、后人工：
|
||||
|
||||
> ⚠️ 本段收口一律人工过（2026-10-02 用户定案「不重要的相关内容都删」）：checklist 人工过 ＋ 渲染截图 ＋ DOM 取值，三项缺一不可。
|
||||
> ⛔ 判据来源：§供给·工艺数值判据（默认档 ＋ 选了才用的可选档），本项目追加条见 runbook §3.4。
|
||||
> ⛔ 结论只能写「人工判定」，⛔ 不许写「已通过」（人工过就是人工过，不借机升格）。要指向交付的单文件，不要指向多文件开发目录。
|
||||
|
||||
### 动效（可跳过）
|
||||
|
||||
按 §供给·工艺数值判据 里动效那一份先答动效三问：① 它传达什么信息？② 删掉会丢失什么？③ 是不是为了「看起来高级」？答不出就不加。
|
||||
|
||||
- 工具型页面（仪表盘 / 后台 / 编辑器 / 工作台）⛔ 不做**逐区块**的入场编排（每个区块各套一次淡入上移）；首次进入的**一次**协调出场按 §供给·方法主线 的最简档做，用户一天开几十次的高频页可整段省去。本项目的版本管理界面属工具型；判不准时按工具型处理
|
||||
- 弹簧用 Damping / Response 二参数（Damping 保持 0.8–1.0、Response 0.3–0.4s；低于 0.7 会明显「蹦」）
|
||||
- CSS 无法用真弹簧时用 `cubic-bezier(0.32, 0.72, 0, 1)`，不得用 `linear` / `ease` / `ease-in-out` 做过渡曲线
|
||||
- 交互过渡禁 `@keyframes animation`（不可中断，反向操作会跳帧），用 `transition` 或 WAAPI
|
||||
- 只动 `transform` / `opacity`，不动 `width`/`height`/`top`/`left`；禁止 `scale(0)` 起手（用 `scale(0.95)` + opacity）
|
||||
- 退出比进入快（进 300ms / 出 200ms）；同屏动效元素 ≤2 个且有 40–80ms 错峰
|
||||
- `prefers-reduced-motion` 必须处理
|
||||
|
||||
### 终检（管「能不能交」）
|
||||
|
||||
过 §供给·工艺数值判据 里那几项（终检清单 P0/P1 ＋ 状态穷举 ＋ 反 AI 味，⛔ 不在本文件抄清单）＋ 动效三问 ＋ 交互清单逐行复测（表里每一行的「触发」与「反馈」都要真发生过，且与实现一致），并真渲染一次：
|
||||
|
||||
```bash
|
||||
# 本机 Chrome 无头截图（2026-10-02 实测可用；门禁脚本补上后仍以脚本为准）
|
||||
"/c/Program Files/Google/Chrome/Application/chrome.exe" --headless=new --no-sandbox --disable-gpu \
|
||||
--hide-scrollbars --window-size=1440,900 --virtual-time-budget=3000 \
|
||||
--screenshot="<Windows 绝对路径>/P1.png" \
|
||||
"file:///<原型绝对路径，中文需 URL 编码>#/p/xxx"
|
||||
```
|
||||
|
||||
- ⚠️ 两条坑：`--screenshot` 必须给 Windows 绝对路径（给相对路径会写进 Chrome 安装目录，回来找不到）；中文文件名要 URL 编码
|
||||
- 在 `1440x900` 与 `390x844` 两个视口各截一张；对外评审 / 交付留档只用视口帧，整页长图仅自检。⛔ 混用会出事：实测把长图交出去，移动端是 1:7.1 的长条，外部评估只能按长条理解布局，「首屏有没有主次」「坐得下几行」根本没被评审到
|
||||
- 结构与排版仍要量（字号档数与相邻档差 / 正文档承载占比 / 标题大纲 / 按钮高度与实底分档 / 列对齐 / 对齐锚点 / 浮层可见关闭出口唯一）：脚本缺失期间靠 DOM 取值人工量，结果直接抄进 `3d-审查报告.md` 的结构核对表。⛔ 不许目测截图下结论
|
||||
- 「无法判定」一律按未通过对待（「判不了」≠「没问题」）：浮层类在未打开态必然判不了，必须按 Gate-3 的打开态复测口径，手工打开每个浮层再数一遍并留痕
|
||||
- 本项目的状态由路由与演示开关驱动，不用 `?state=`；状态可见性由 `browser-harness` 实测承担
|
||||
|
||||
### Gate-2 完成门
|
||||
|
||||
全部 `阻断` 项清零，`建议` 项逐条有结论：修掉，或显式写「已知不修 + 原因」。不接受「基本没问题」「应该差不多」「剩余都是小问题」。每条要么修，要么留痕。
|
||||
|
||||
### Gate-3 交付门（硬闸，任何挡位不可跳）
|
||||
|
||||
真实渲染后（浏览器打开，非只看代码）肉眼过八项：裁切 / 重叠 / 失真 / 失效控件 / 缺状态 / 响应式破损 / 控制台报错 / 字体回退异常。渲染截图已代劳其中的溢出与响应式破损，其余仍需人眼（截图查不出「点了没反应」）。
|
||||
|
||||
### 审计报告落盘
|
||||
|
||||
`designs/<项目>/3d-审查报告.md`，固定七节：范围 + 挡位 + 阻断项表 + 建议项表 + 状态覆盖核对表 + 结构核对表 + Gate 结论（含「本轮是否跑了脚本」一句）。
|
||||
|
||||
## 硬约束
|
||||
|
||||
- ⭐⭐ 骨架冻结，不许动板块（2026-10-06 用户定案）：页面清单、每页板块、板块排列、跨页关系由②段《界面布局》定死。
|
||||
⛔ 本段不许新增 / 移动 / 删除 / 合并板块。做不下来 / 觉得缺板块 ⇒ 回②段改《界面布局》，⛔ 不许就地加一块，就地加会让②段与原型不一致，下一个读原型的人拿到的是错的骨架。
|
||||
可动的是板块内的视觉与交互实现（怎么排版好看、点哪有什么反馈、空态怎么呈现、响应式怎么变）。
|
||||
⛔ 不许无视②段骨架另起一套。D0 的页面清单与每页板块必须与②段《界面布局》逐条对得上；对不上就停下来问②段要哪一版。
|
||||
- 声明制：开工前、每进一个子步、每处偏离，都要声明（当前子步 / 依据文件 + 小节号 / 产出落点）。不许静默偏离。段末必须附偏离单，没有偏离单不得报完成。
|
||||
- 供给关系只在 §供给 定义一次（默认档 / 可选档 / 路径都在那张表里）。⛔ 本文件其余章节、`references/` 两份、总入口 `product-planning/SKILL.md`，提到供给一律引用 §供给 的行名，不许复述。冲突处以 §供给·方法主线（基础层）为准，本段自有判据是叠加层。不许跳过 Gate-1 或 Gate-3。
|
||||
⚠️ 不选可选档时不需要回落 —— 默认档本来就不靠它，照 §供给 走完即可；可选档独有的那几项（反 AI 味 / 无障碍 / 表单校验 / 动效纪律）在没选它时明说「本次无供给来源」，⛔ 不许凭感觉编。
|
||||
- 页型先判再动手（2026-10-05 新增）：3a 的 D0 必须写出「营销页 / 工具型页面 + 依据」。工具型页面零 `.eyebrow` / 零 `.lead` / 零 `.hero`，三者已从种子删除或降级为 `body.is-marketing` 专用。⛔ 判不出页型不许进 3b。
|
||||
- §供给·版式骨架 的可选档种子是营销落地页骨架：⛔ 工具型页面不许直接套用其版式节奏与标题区结构；版式走默认档。这是一处「照供给做反而错」的例外，必须显式绕开。
|
||||
- 先定死，再写码：设计契约与令牌表未落笔，不许写任何组件代码。
|
||||
- 限载：一次只读 1~2 份供给原文，用完释放（可选档定调候选与工艺判据份数都不小，全读必然互相稀释）。
|
||||
- 不许覆盖旧版：重大改版先复制副本再改（`X.html` → `X v2.html`），旧版留在磁盘上以便对比。
|
||||
- 3a 必须在 3b 之前，规范是原型的输入。
|
||||
- 门禁脚本只作校验，不是原型生成工具。出原型只用 3b（脚本当前缺失，见 3d 的「门禁脚本现状」）。
|
||||
- 原型必须可点通：每个按钮、每个跳转都真能走，不许留死链。可点通的清单就是 D0 契约的「交互清单」，清单之外的可点元素 = 未登记元素，必须回 D0 补登记或改成静态，⛔ 不许「清单没写但先做着」。
|
||||
- 交互清单是唯一交互真相源（2026-10-02 新增）：段名已改为「界面交互」，故交互判据只许写在契约第十二字段里。3b 实测、3c 参考版、3d 终检都引用同一张表，⛔ 任何一处另立一份交互清单（另建文档、另写章节、另做交互规范）都算第二真相源，这正是记忆里「同一事实多处落点必然打架」的成因。
|
||||
- 3b 交付前必须用 `browser-harness` 跑实测；脚本查不出死按钮，未跑实测不得进 3c，不得报完成。
|
||||
- 3c GPT 参考版必做：原型初稿 + 实测过后立刻做，不许用「我觉得没问题」代替。参考版原文（三句话说明 ＋ 完整 HTML）必须落盘，不得伪造或转述失真；未取得参考版时要在 `3c-GPT参考版.md` 与收尾里明示，未取得不等于已通过。贴进去的需求与风格文本先脱敏。
|
||||
- Gate-2 / Gate-3 不许口头通过：阻断项要么修完，要么留痕；「未取得审查」不等于已通过。
|
||||
- 原型的说明区与演示引导不是本段的事：各状态下的「场景 / 从左到右流程图 / 步骤说明 / 演示引导」由第④段 `stage-proto-doc` 负责。3d 完就交付原型本身。
|
||||
- `DESIGN.md` 落 `docs/pm/<项目>/`，不放仓库根。
|
||||
- 段内子步之间不反问，做完直接进下一个子步。停线规则（哪几种情况停、怎么判）见 `product-planning` 的「执行规则」—— ⛔ 本段不复述，免得两处漂。
|
||||
- `<项目>` 按 `product-planning` 的「项目与路径约定」定；定不出来就停下问用户，不许猜。
|
||||
|
||||
## 完成标准
|
||||
|
||||
- 声明制走完：开工、每个子步、每处偏离都有声明；偏离单已附，无静默偏离
|
||||
- 挡位已声明（快速 / 标准 / 严格）
|
||||
- 页型已判（营销页 / 工具型页面 + 依据）；工具型页面零 `.eyebrow` / 零 `.lead` / 零 `.hero`，且 `layouts-tooling.md` §5.5 五条逐条过完（含「标题区零从属小字」的 DOM 取值核对）
|
||||
- `docs/pm/<项目>/DESIGN.md` 存在，含设计契约（十二个字段，含结构骨架、交互清单与重复项的信息量）与令牌表（三层 token 结构，含组件规格、容器与对齐锚点、浮层只许一个可见关闭出口，全为具体值），且 Gate-1 全部自检项结果写在文件末尾
|
||||
- 原型 HTML 单文件自包含、双击可开，含全部适用状态（状态穷举六项逐条有结论）
|
||||
- 原型经真实渲染验证过，控制台无报错
|
||||
- 每个按钮都经 `browser-harness` 真点过，有实测回报（含控制台报错原文与死按钮清单）
|
||||
- 静态收口已过（脚本在位 ⇒ 已跑且阻断清零、有输出留档；脚本缺失 ⇒ 已按 checklist 人工过，并在报告中写明「未跑脚本 + 原因」）
|
||||
- 渲染终检已过（溢出 0 / 对比度按真实像素达标 / 结构与排版量测无阻断且无「无法判定」项 / 两个视口的截图都存进 `_gate_shots/`），或已写明为何不适用。量测数字以 DOM 取值与脚本输出为准，不得用「目测」代替
|
||||
- 每个浮层都手工打开数过可见关闭出口（`== 1`），`Esc`/点遮罩能关、焦点锁在层内且关闭后回到触发按钮，结论连同触发路径写进 `3d-审查报告.md`。「代码里看着只有一个」不算
|
||||
- 对外提交/交付留档的截图只用视口帧（`_gate_shots/<视口>.png`）；`_full/` 下的长图不得作为评审输入
|
||||
- `designs/<项目>/3c-GPT参考版.md` 存在，含提问原文、参考版原文（三句话 ＋ 完整 HTML）与四列对照表（采纳项已改完并复测）；未取到参考版的已明示
|
||||
- `designs/<项目>/3d-审查报告.md` 存在，含阻断/建议两张表 + 状态覆盖核对 + Gate-2/3 结论
|
||||
- Gate-2 与 Gate-3 均已通过（书面结论，非口头）
|
||||
- 重大改版：旧版文件仍在磁盘上，且收尾给出新旧差异（改了什么 / 为什么 / 代价）
|
||||
|
||||
## 反面清单
|
||||
|
||||
- ⛔ 就地增删板块（2026-10-06 新增）：觉得骨架不合适就自己加一块 / 挪一块 / 删一块。骨架归②段，要改回②段改，本段只能动板块内的视觉与交互实现；就地改会让②段与原型不一致
|
||||
- ⛔ 无视②段骨架另起一套（2026-10-06 新增）：D0 的页面清单与每页板块必须与②段《界面布局》逐条对得上
|
||||
- 先出原型再补规范（违反铁律 1）
|
||||
- 违反限载：一次把全部定调候选或工艺判据原文读进上下文（一次只许 1~2 份）
|
||||
- 不判页型就照 `web-prototype` 种子做，会把后台做成营销页（标题上下各一行小字）；或拿 `layouts.md` 的营销骨架顶替工具型版式
|
||||
- 只画了 success 态就当状态齐了（违反铁律 3）
|
||||
- 跳过 Gate-1 或 Gate-3；或拿「我觉得还行」当 Gate-2 结论
|
||||
- 在无脚本时把「没跑」写成「已过」；或从零手写 `<section>` 不套骨架、把临时样式内联在标签上
|
||||
- 覆盖旧版：重大改版直接改原文件，把可对比的旧版弄丢
|
||||
- 把 `DESIGN.md` 写到仓库根（多项目会互相覆盖）
|
||||
- 原型里有死按钮或空链接；只用脚本判过就当实测过（脚本查不出死按钮）
|
||||
- 拿默认配色和系统字体糊一个「能看」的界面交差
|
||||
- 跳过 3c GPT 参考版直接进 3d；或直接把我们的原型 HTML 传给它（那样拿到的是它的改编、不是独立参考版）；或回答没出完就取走当完整版
|
||||
- 把参考版当命令照抄，改坏与 `DESIGN.md` 的一致性；或伪造「GPT 做了……」却拿不出参考版原文
|
||||
- 把「未取得外部审查」当已通过
|
||||
- 工具型页面做**逐区块**的入场编排；用 `linear`/`ease` 做过渡曲线；用 `@keyframes` 做交互过渡
|
||||
- 越界回头改②段的功能取舍（那是第②段）——⚠️ 但「骨架缺板块」是例外：必须回②段改，⛔ 不许就地在原型里加
|
||||
- 顺手把原型说明文档 / 演示引导写了（那是第④段 `stage-proto-doc`）
|
||||
|
||||
## 待补（2026-10-02 登记 · 2026-10-06 更新）
|
||||
|
||||
- ~~`execution-runbook.md` 的必读表全部指向已不存在的文件~~：已于 2026-10-02 修复（用户定案「第三部分用 open-design」后执行）。原 D0/D3/D4/D5 四行引用的 `ui-page-design/references/0X_*.md` 与 `vendor/*` 已全部重接：`D0 → runbook §2.1`（十二字段留在本项目）｜`D0 判据 → craft/state-coverage.md`｜`D1 → open-design/design-systems/ 选套`｜`D2 → design-templates/web-prototype/`｜`D3 → craft/typography.md` + `typography-hierarchy.md`｜`D4 → craft/animation-discipline.md`｜`D5 → checklist.md` + `craft/anti-ai-slop.md` + `craft/accessibility-baseline.md`。
|
||||
同时做了一次能力去向盘点（判据逐条归属，不做适配搬运）：craft 接住 6 类（状态穷举 / 字阶 / 配色 / 动效 / 反 AI 味 / 无障碍与表单校验）；接不住 3 项，必须留在本项目 —— 设计契约十二字段 / 结构骨架 / 交互清单；5 份 vendor（`ui-ux-pro-max`／`frontend-design`／`apple-design`／`anti-ui-slop`／`web-design-guidelines`）无需保留。
|
||||
⛔ 修复后的纪律：判据来源必须单一可查。某条判据若在 runbook 与 craft 各有一份且口径不同，以本项目追加条为准，并在 §3.4 显式标注「本项目追加」。
|
||||
- ~~工具型页面的版式库~~：已于 2026-10-02 补齐。新建 `references/layouts-tooling.md`，四类形态各给一份可判定骨架：行式列表 / 表格式清单 / 详情面板 / 主从侧区。每类带形态判定句（判不出形态就去改 D0 `结构骨架`）＋ 可机械核对的判定要点（如「一屏可见行数 ≥6」「数字列右对齐」「表头必须写判据来源」「未跑必须能作为取值存在」）。已接进三处：3b 正文（形态判定先行）｜runbook §1 必读表 D2 行（工具型另读）｜runbook「⛔ 四样 craft 接不住」表（第四行）。
|
||||
⭐ 红线：⛔ 不许拿营销页骨架顶替工具型，那是「没做形态判定」的默认行为，等于退回 18 轮前的病根。
|
||||
- ~~①②段的同型改造~~：已于 2026-10-02 完成。四段已改名为「①产品需求 / ②产品功能 / ③界面交互 / ④原型说明文档」，并各自重划了子步职责（见 `product-planning` 的四段表与交接口表）。
|
||||
- ⛔ 骨架归属已于 2026-10-06 反转：本节原口径是「页面结构归本段，唯一落点是 D0」；用户定案改为「②段钉骨架，③段做皮肉」（原话：页面关系和布局必须在第二步确认清楚，不然第三步没有方向 一会一个样子）。⇒ `必要内容` / `结构骨架` 两个字段口径已调整，从「本段独立裁决」改为「在②段给定骨架之内决定视觉与交互实现」。详见本文件开头「⭐⭐ 页面骨架不归本段了」块。
|
||||
---
|
||||
name: stage-delivery
|
||||
description: 产品规划第③段，界面交互。设计工程供给来自 open-design（设计系统定调 + 工艺规约给数值判据 + 原型模板给版式）：先落设计契约与令牌表（Gate-1 硬闸），再构建页面，再收口/动效/终检（Gate-2/3），中途加一轮 GPT 独立会诊。判据结构为「正向目标为主、禁令只留最关键三条」。当用户要做 UI 规范、设计系统、页面原型、交互动效、界面审查、视觉打磨，或说"只做界面交互"时调用。
|
||||
---
|
||||
|
||||
# ③ 界面交互
|
||||
|
||||
回答两个问题：长什么样、怎么操作。产出 `docs/pm/<项目>/DESIGN.md` 与 `designs/<项目>/*.html`。
|
||||
|
||||
> 段名为什么是「界面交互」（2026-10-02 定）：
|
||||
> 删「交付」：①②③都产出落盘文件，「交付」是三段共有的属性，不是③的专属；④段也在交付（原型的说明区），留着会让人以为③管完就结束了。
|
||||
> 补「交互」：本段原先只讲「长什么样」，可 3b 原型硬要求每个按钮、每个跳转都真能走（`:236`），3c 会诊专查空态 / 加载 / 错误 / 反馈（`:148`、`:150`）。交互判据一直在做，却没有名字，补上才与本段实际职责相符。
|
||||
> 与④段的界：③造物（界面与交互本身），④描述物（说明区与演示引导）。
|
||||
|
||||
> `<项目>` 按 `product-planning` 的「项目与路径约定」定；定不出来就停下问用户，不许猜。`DESIGN.md` 放项目目录，不放仓库根，避免多项目互相覆盖。
|
||||
|
||||
本段的页面设计供给来自两个独立技能，都装在 `.workbuddy/skills/` 技能仓库里，都可脱离本段单独使用：
|
||||
|
||||
| 技能 | 它是什么 | 本段取它什么 |
|
||||
|---|---|---|
|
||||
| `open-design`（⚠️ 工作区级，全局没有） | 网页 App 设计判据供给库：153 套设计系统（定调与令牌）＋ 13 份工艺判据 ＋ 35 个版式骨架 | 定调 + 数值判据 + 版式骨架（本段默认主线） |
|
||||
| `oil-ui-pro`（✅ 全局级） | 界面设计方法论：五步流程（探索方向 → 建结构 → 取实证 → 独立评审打分 → 验证交付）＋ 风格对比页与截图工具 | 方向探索 + 对比页 + 独立评审打分（做多方向比选或要独立评审时；`open-design` 缺位时也由它顶） |
|
||||
| 本段自带样式库（✅ 随段携带） | `assets/design-systems/<选定一套>/` —— 样式风格库，可续加；当前 1 套：`design-system-tiaoyue`（跳跃视界规范 + 277 个自有组件族） | 定调 + 令牌 + 组件形态，与 `open-design` 那 153 套同权；⛔ 二者每次只选一套 |
|
||||
|
||||
> ⭐ 两个技能平行同层级，可分别独立使用。本段按任务取用，不把它们缝成一条流水线：多数页面走 `open-design` 主线（快、判据硬）；需要「先拉开几个方向让用户挑」或「要一个没看过制作过程的评审打分」时，取 `oil-ui-pro` 的方法与工具。
|
||||
> ⛔ 判据正文仍只在本段（`references/execution-runbook.md` 与 `references/layouts-tooling.md`）。两个技能都只是素材与方法，不是规范权威。同一条判据两处都有且口径不同时，以本段为准，并在 runbook §3.4 标注「本项目追加」。
|
||||
> ⛔ 不许把 `oil-ui-pro` 的评分循环当成 D 阶段的替代：它是评审方法，本段的 Gate-1/2/3 该过还得过。
|
||||
> ⚠️ `oil-ui-pro` 自带联网版本检查与自动更新（每次使用会连 `ui.oiloil.org`，发现新版用 `npx` 覆盖自身目录）。这是本项目收录时用户明确要求全量搬入的例外项，与「依赖外部服务一律不收」的既有纪律冲突，记录在案，不扩散到其他技能。想关掉设环境变量 `OIL_NO_UPDATE_CHECK=1`。
|
||||
|
||||
`open-design` 的三处供给各管一件事：
|
||||
|
||||
| 供给 | 路径（技能内） | 管什么 | 在哪一环用 |
|
||||
|---|---|---|---|
|
||||
| 设计系统（正向目标 · 调性） | `open-design/design-systems/<选定一套>/` | `DESIGN.md` 定调性 ＋ `tokens.css` 给全套数值（圆角与阴影在这里）＋ `components.html` 给组件形态 | 3a 定调、落令牌表 |
|
||||
| 工艺规约（正向判据 · 数值） | `open-design/craft/` | 字号刻度 / 配色配额 / 状态齐备 / 动效纪律 / 反 AI 味 / 无障碍 | 3a 判据、3d 终检 |
|
||||
| 原型模板（正向形态 · 版式） | `open-design/design-templates/web-prototype/` | 种子 `assets/template.html` ＋ 8 个版式骨架 ＋ 自查清单 | 3b 构建 |
|
||||
|
||||
`open-design`（上面那张表的可选来源）给三处，都在 `assets/open-design/` 下：
|
||||
|
||||
1、`design-systems/<选定一套>/`：`DESIGN.md` 定调性 ＋ `tokens.css` 给全套数值（圆角与阴影在这里）＋ `components.html` 给组件形态。
|
||||
|
||||
2、`craft/`：字号刻度 / 配色配额 / 状态齐备 / 动效纪律 / 反 AI 味 / 无障碍。
|
||||
|
||||
3、`design-templates/web-prototype/`：种子 `assets/template.html` ＋ 8 个版式骨架 ＋ 自查清单。
|
||||
|
||||
⭐ 选了自带的 `design-system-tiaoyue` 时怎么读（⚠️ 套内命名与 `open-design` 不同形，别按 `DESIGN.md` 去找）：
|
||||
|
||||
| 要什么 | 套内路径 |
|
||||
|---|---|
|
||||
| 入口（规范总纲、生成时的参考范围） | `assets/design-systems/design-system-tiaoyue/SKILL.md` |
|
||||
| 令牌（含暗色一套） | 同目录 `assets/tokens.css` ＋ `assets/tokens-dark.css`（色值原始记录 `assets/brand.json`） |
|
||||
| 组件形态 | 同目录 `references/components.md` ＋ `references/design-system.html`（组件族清单 `references/library.json`） |
|
||||
| 已知冲突 / 取舍记录 | 同目录 `references/known-conflicts.md` ＋ `references/capture-notes.md` |
|
||||
|
||||
> ⚠️ 路径怎么找：自带件一律按**段内相对路径**引用（`assets/open-design/...`、`assets/design-systems/...`），⛔ 不按绝对路径爬、⛔ 不写死 `../` 层数；`oil-ui-pro` 按技能名引用（宿主按名加载，与物理位置无关）。
|
||||
> 🔴 定调来源唯一：每次设计只选一套，默认与可选**不混用**（混用 = 没有调性）。套名与选择理由写进 `DESIGN.md`。
|
||||
> ⛔ 判据正文仍只在本段（`references/execution-runbook.md` 与 `references/layouts-tooling.md`）。⚠️ 供给是分层的，分层定义见 §供给：`oil-ui-pro` 是**基础层**，本段自有判据是**叠加层**；同一条判据两处都有且口径不同时，⛔ 本段不许放宽基础层，只许更严、更具体，并在 runbook §3.4 标注「本项目追加」。
|
||||
> ⛔ 不许把 `oil-ui-pro` 的评分循环当成 D 阶段的替代：它是评审方法，Gate-1/2/3 该过还得过。
|
||||
> ⛔ 不动用可选来源时，⛔ 不许凭感觉编一套顶上（那正是本项目反复踩的坑）；craft 独有的那几项（反 AI 味 / 无障碍 / 表单校验 / 动效纪律）明说「本次无供给来源」。
|
||||
> ⚠️ `oil-ui-pro` 自带联网版本检查与自动更新（每次使用会连 `ui.oiloil.org`，发现新版用 `npx` 覆盖自身目录）。这是本项目收录时用户明确要求全量搬入的例外项，与「依赖外部服务一律不收」的既有纪律冲突，记录在案，不扩散到其他技能。想关掉设环境变量 `OIL_NO_UPDATE_CHECK=1`。
|
||||
> 供给件都不依赖付费云 / MCP / API Key 才能用于设计：`open-design` 去掉那些之后剩下的全是静态 md / css / html（其 daemon、云模型服务、`packages/components` 的 tsx 未收录）；`oil-ui-pro` 的设计方法宿主中立、离线可用（联网仅用于版本检查）。
|
||||
> 冲突处以 §供给·方法主线（基础层）为准；本段自有判据与 `DESIGN.md` 是叠加层，只许更严，⛔ 不许与基础层相反。供给件的价值在给正向目标、给方法。
|
||||
|
||||
> 为什么换掉原来的主干（2026-10-02 用户定案）：原主干 `ui-page-design` 已从磁盘移除，③段只剩规则壳，壳里又全是减法型判据，机检能判「不违规」却判不出「好看」，18 轮回改把页面越推越白。换供给的同时必须换判据结构：正向目标为主，禁令只留最关键的。
|
||||
|
||||
> ⭐⭐ 本段在②段给定的骨架里做视觉与交互（2026-10-06 用户定案）。
|
||||
>
|
||||
> 口径：②段钉骨架，③段做皮肉。
|
||||
>
|
||||
> | 归②段（本段⛔ 不许动） | 归本段（②段⛔ 不许写） |
|
||||
> |---|---|
|
||||
> | 有哪几页 | 配色 / 字体 / 间距 / 组件样式 / 动效 |
|
||||
> | 每页几个板块、板块怎么排 | 每个板块的视觉实现（怎么好看、怎么对齐、什么层次） |
|
||||
> | 跨页关系（怎么跳转） | 每个板块的交互行为（点哪、什么反馈、何时不可点） |
|
||||
> | 每页主操作 | 状态与空态的具体呈现 |
|
||||
> | 每条信息在哪一档（主屏常驻 / 可点入） | 响应式怎么变 |
|
||||
>
|
||||
> 用户原话：「3 是负责设计和交互，页面关系和布局必须在第二步确认清楚，不然第三步没有方向 一会一个样子」。
|
||||
>
|
||||
> 🔴 旧口径站不住的地方：它把「有哪几页」留在本段，于是本段做一版一个样，②段手里没有任何东西能判断本段改得对不对。用户看到的现象就是「一会一个样子」。
|
||||
> ⭐ 本段拿到的骨架是冻结的：⛔ 不许新增 / 移动 / 删除板块。缺板块要回②段改②段（见「硬约束」的对应禁令）。
|
||||
>
|
||||
> 仍在本段手里的两个字段（它们在给定骨架之内决定怎么摆得好看）：
|
||||
> - `必要内容`（减法）：⚠️ 口径已调整。它不再决定哪些内容上屏（那是②段分档表的活），而是核对②段给的信息是否都在骨架里有落点；⛔ 本段不得以它为由增删信息档位。
|
||||
> - `结构骨架`（加法）：⚠️ 口径已调整。它不再独立决定几个区块，而是把②段给的板块清单翻译成具体的骨架档 / 列宽 / 密度目标（骨架档选哪个、密度多少，仍是本段的活）。
|
||||
>
|
||||
> ⛔ 本段不许回头改②段的骨架（那是②段）；⛔ 也不许无视②段骨架自己另起一套。判据：D0 里的页面清单与每页板块，必须与②段《界面布局》逐条对得上；对不上就停下来问②段要哪一版。
|
||||
|
||||
顺序 3a → 3b → 3c → 3d。先有规范再出原型，不许反过来；原型能点通后先会诊，再收口打磨。
|
||||
|
||||
> 照 `references/execution-runbook.md` 逐步走。那是本段的固化执行手册：按 D 阶段排的必读表、每步验收判据、脚本跑法、偏离单格式、完成标准清单都在里面。本文件写规则，手册写顺序与验收。
|
||||
> 开工前先声明、每进一个子步再声明、偏离当场声明（三字段：当前子步 / 依据文件 + 小节号 / 产出落点）。这条不可商量。
|
||||
|
||||
## 子步与产物
|
||||
|
||||
| ③段子步 | 做什么 | 产物 | 闸 |
|
||||
|---|---|---|---|
|
||||
| 3a 视觉规范 | 定契约（减法 + 加法）→ 定调（选定设计系统）→ 落令牌表〔多方向比选时取 `oil-ui-pro` 的方向探索与对比页〕 | 设计契约 + 令牌表 → `DESIGN.md` | Gate-1 方向门 |
|
||||
| 3b 原型 | 按模板种子 + 版式骨架构建 | `designs/<项目>/<原型>.html` | — |
|
||||
| 3c GPT 会诊 | 外部独立视角（本段特有，两个设计技能都不覆盖） | `3c-GPT会诊.md` | — |
|
||||
| 3d 审查与打磨 | 收口 → 动效 → 终检〔要独立评审打分时取 `oil-ui-pro` 的评审协议〕 | file:line 清单 + `3d-审查报告.md` | Gate-2 / Gate-3 |
|
||||
|
||||
挡位开工前定一次，默认标准：纯原型可降快速（定契约 → 定调 → 构建 → 终检）；常规页面走标准（全跑）；对外页面走严格（三闸全开 + 中间产物落盘）。
|
||||
`Gate-1` 与 `Gate-3` 是硬闸，任何挡位都不可跳，哪怕只做原型，也要打开看一眼。
|
||||
|
||||
## 三条铁律（只留不可省略的）
|
||||
|
||||
| # | 铁律 | 违反后果 |
|
||||
|---|---|---|
|
||||
| 1 | 先定死，再写码。未产出设计契约与令牌表前，禁止写任何组件代码；禁止边写边调样式。 | 返工、风格漂移 |
|
||||
| 2 | 状态穷举。`loading / empty / error / success / disabled / 无权限` 逐项给结论（判据见 `craft/state-coverage.md`）。 | 上线即翻车（最高频漏项） |
|
||||
| 3 | 不渲染不算完。交付前必须在真实环境渲染一次并肉眼确认。 | 裁切/重叠/失效控件逃过检查 |
|
||||
|
||||
> 禁令就这三条，其余一律去供给源查：反 AI 味 → `craft/anti-ai-slop.md`｜字号与层级 → `craft/typography.md` / `typography-hierarchy.md`｜配色配额 → `craft/color.md`｜动效 → `craft/animation-discipline.md`｜无障碍 → `craft/accessibility-baseline.md`｜表单校验 → `craft/form-validation.md`。
|
||||
> ⛔ 不在本文件里抄写禁令清单。抄了就变两份，两份必然漂；更要紧的是，抄禁令会把正向目标挤出视野，这正是改版前③段只剩「不要什么」、页面越改越白的根因。
|
||||
> 一条例外（本项目特有，craft 里没有）：结构性容器靠底色差 + 阴影分层，不挂围合边框（来源：本项目 E-62 / E-63 实测）。当选定设计系统写「卡片描边」时，以本条为准。
|
||||
> 限载：同一时刻只读 1~2 份供给原文，用完释放。这条不再单列铁律，但仍是硬约束（`design-systems/` 有 153 套、`craft/` 有 13 份，全读必然互相稀释）。
|
||||
|
||||
## 必读（限载：一次只读 1~2 份，用完释放）
|
||||
|
||||
| 环节 | 读什么 |
|
||||
|---|---|
|
||||
| 3a 定调 | `open-design/design-systems/<选定一套>/DESIGN.md` ＋ 同目录 `tokens.css`；`components.html` 按需 |
|
||||
| 3a 判据 | `open-design/craft/typography.md` ＋ `craft/color.md`（其余一次一份，按需） |
|
||||
| 3a 多方向比选（按需） | 需要「拉开几个方向让用户挑」时，取 `oil-ui-pro` 的 `references/design-direction.md` ＋ `references/style-explorer.md`（对比页模板与生成器） |
|
||||
| 3b 构建 | `open-design/design-templates/web-prototype/SKILL.md` ＋ 同目录 `references/layouts.md`（⚠️ 不在本技能 `references/` 下，该目录只有 execution-runbook.md）；工具型页面另读两份：本技能 `references/layouts-tooling.md`（HTML 骨架与落地自检）＋ `open-design/design-templates/web-prototype/references/tooling.md`（四形态判定句与通用红线纲要） |
|
||||
| 3d 独立评审（按需） | 要「一个没看过制作过程的评审打分」时，取 `oil-ui-pro` 的 `references/visual-review.md`（协议）＋ `references/tools.md`（截图与对比取证） |
|
||||
| 3d 终检 | `open-design/design-templates/web-prototype/references/checklist.md` ＋ `craft/state-coverage.md` |
|
||||
|
||||
> 定调来源唯一，每次只选一套。可选套来自两处，⛔ 每次设计只选其中一套、不许混用两套（混用 = 没有调性）：
|
||||
> ① `open-design/design-systems/`（⚠️ 工作区级，153 套）；
|
||||
> ② 🔴 本段自带样式库 `assets/design-systems/`（✅ 随段携带、可续加；当前 1 套：`design-system-tiaoyue`）。
|
||||
> 套名与选择理由写进 `DESIGN.md`。既有项目中凡引用旧风格来源（`minimalist-ui` / 皮肤族 / `ui-ux-pro-max` 检索结果）的 `DESIGN.md` 行，重跑 3a 时一律改写为选定套 + 留痕对照。
|
||||
> 本段 `references/` 只放流程规则，⛔ 不放风格；随段携带的样式风格一律放 `assets/design-systems/<套>/`（🔴 2026-10-07 用户令两条：「把 `design-system-tiaoyue` 整合到 `product-planning` 作为一种样式风格」＋「后续可以添加多种风格，每次只能选择一种进行设计」⇒ 只把「不放风格」这条放宽到 `assets/`，`references/` 仍不放）。
|
||||
> ⚠️ 续加新风格时的硬要求：目录名与 open-design 同形（`assets/design-systems/<套名>/`），套内自带入口文件（`SKILL.md` 或 `DESIGN.md`）；⛔ 不许改已入套的文件内容，原样搬入、只在本文件登记去向。
|
||||
|
||||
## 3a 视觉规范（定契约 + 定调 + Gate-1）
|
||||
|
||||
第 0 步 · 供给核对（每轮必做，防漂移）：确认技能仓库里的供给仍在位（`open-design/` 下 `design-systems/<选定套>/` 存在、`craft/` 存在、`design-templates/web-prototype/` 存在；`oil-ui-pro/` 入口 `SKILL.md` 存在；🔴 若上轮选的是自带库那套，另核 `assets/design-systems/<套>/SKILL.md` 仍在位），并把选定套名与 `DESIGN.md` 里记录的上次套名比对。
|
||||
|
||||
- 一致 → 直接定契约。
|
||||
- 不一致或供给缺失 → 先停下报告，⛔ 不许拿别的套顶上，也不许凭记忆写风格。把差异列成「供给变更清单」，在会话里向用户呈现并确认后，再改 `DESIGN.md`，把新套名与清单写进修订记录。
|
||||
- 本步存在的理由：`DESIGN.md` 是上一次供给状态下产出的。供给换了却没核对，就会长期拿着旧调性当准绳。
|
||||
|
||||
D0 锚需求：按 `references/execution-runbook.md` 里的契约模板产出设计契约（十二个字段）——页面职责（谁 + 多久 + 干什么）、主用户、主操作（全页唯一）、必要内容（减法）、重复项的信息量（行式列表 / 卡片网格逐条列次级信息）、结构骨架（加法：骨架档 + 区块划分 + 密度目标）、交互清单（加法，见下）、状态覆盖六项逐条、组件来源（优先沿用）、响应式行为（写布局怎么变，不写「自适应」）、明确拒绝的模式、验收标准（可观察可判定）。
|
||||
|
||||
> ⭐⭐ 第十二字段「交互清单」是 2026-10-02 新增，段名改名的直接后果（段名从「界面与交付」改成「界面交互」，但「交互」在流程里此前没有落点：可点通在 3b、查反馈在 3c、动效在 3d，三处各判一部分，谁也不负责整体）。
|
||||
> 它写什么：逐个可点元素一行，四列——元素（哪个）｜触发（点了/输了/滚到哪，发生什么）｜反馈（状态怎么变、给什么提示、多久消失）｜何时不可点（哪些条件下 `:disabled`，条件是什么）。
|
||||
> 它不写：动效参数（归 3d 按 `craft/animation-discipline.md`）、视觉样式（归令牌表）、状态六项的有无判定（归下一字段 `状态覆盖`，本字段只写「这个元素可点时点了会怎样」）。
|
||||
> 为什么是契约字段而不是新子步：交互一旦单独成文，就会与 `必要内容`、`状态覆盖` 三处互相矛盾——这正是记忆里「同一事实多处落点必然打架」的病。收进契约 = 一个字段、一处裁决、一个门禁。
|
||||
> 判定「漏没漏」：页面里每一个能点的东西都必须在这张表里出现。表里没有 ⇒ 它不该可点（改成静态文本，或回 D0 补进 `必要内容` 再点）。
|
||||
|
||||
D1 定调：从 `open-design/design-systems/` 或本段自带 `assets/design-systems/` 里选一套（⛔ 每次只选一套），不凭感觉编，也不全读：
|
||||
|
||||
- 怎么选：按本项目的页面类型挑。读候选套 `DESIGN.md` 的第 1 章 `Visual Theme & Atmosphere`，认准写明该类的那一句（工具型数据密集界面 ⇒ 认 `data-dense, enterprise` 这类描述）。153 套分两代模板（A 组 / B 组章节名不同），按自己那套的章节读，不必统一。
|
||||
- ⚠️ 选了自带库那套（`design-system-tiaoyue`）时：套内没有 `DESIGN.md` ⇒ 读它自己的 `SKILL.md`（规范总纲 ＋ 生成时的参考范围）＋ `references/known-conflicts.md`（已知取舍）；入口 / 令牌 / 组件形态按上面那张「怎么读」表取，⛔ 别按 open-design 的三件套去找。
|
||||
- 选定后读三件：`DESIGN.md`（调性 + 色值 + 字号刻度 + 间距刻度 + 动效基调）→ `tokens.css`（圆角与阴影只有这里）→ `components.html`（组件实际长相）。
|
||||
- 要换风格 ⇒ 下一轮重跑 D1 重选一套，旧套留痕（用户 2026-10-07：「后续可以添加多种风格，每次只能选择一种进行设计」）。
|
||||
- 没找到匹配的套 ⇒ 换一个类型词再挑一次；仍不行就直说「未找到匹配」，不许拿泛化结果当结论落盘。
|
||||
- ⚠️ 工具型页面的版式不在模板里：`web-prototype/references/layouts.md` 那 8 个骨架是落地页 / 营销页向（hero / features / stats / quote / cta / log / pricing）。工具型页面只适用其中 Layout 7 日志列表与 Layout 8 对比表，其余套上去会把后台做成营销页。工具型页面的版式由 D0 的 `结构骨架` 字段决定，不从模板抄。
|
||||
|
||||
- 产出令牌表：色值 / 字体（标题字体是关键项）/ 间距两档（主刻度 `4/8/16/24/32/64` 供布局 + 控件层微网格 `2/4/6/8/12` 仅供按钮内衬、徽章内衬、图标间隙、开关与进度轨微几何）/ 圆角 / 字阶定值表（七档各一个 px，不是区间）/ 高度层级（每层都有多层叠层值）/ 布局脚手架（骨架档落到具体列宽 + 窄屏变化）/ 组件规格（按钮三档 + 卡片两档 + 输入框 + 徽章的具体高度与内衬；实底底色 ≥2 种）/ 动效基调——全部为具体值，禁止「待定」，每档只许一个定值
|
||||
|
||||
落盘 `docs/pm/<项目>/DESIGN.md`：令牌表内容并入本项目既有的三层 token 结构（primitive → semantic → component；组件只引语义层、语义层只引 primitive），设计契约作首节。`DESIGN.md` 是原型的绑定规范，原型只许引它的 token。
|
||||
|
||||
Gate-1 方向门（硬闸，不可跳）——按本表逐项自检（字段定义与填写位见 `references/execution-runbook.md` §2.1；⛔ craft 无对应，十二字段只能在此判）：
|
||||
|
||||
| 检查项 | 通过条件 |
|
||||
|---|---|
|
||||
| 设计契约 | 十二个字段全部填写，无一为空或「待定」；有重复项时重复项的信息量已逐条列出次级信息 |
|
||||
| 页型判定（2026-10-05 新增） | 已写出「营销页还是工具型页面」+ 依据；工具型页面的 D0 里零 `.eyebrow` / 零 `.lead` / 零 `.hero` |
|
||||
| 结构骨架（加法面） | 骨架档 / 区块划分 / 密度目标三者已写；区块 ≥2 个且每个有文字标题；`必要内容` 每条都有归属区块 |
|
||||
| 交互清单（加法面，2026-10-02 新增） | 页面上每一个可点元素都在表里（元素 / 触发 / 反馈 / 何时不可点 四列齐全）；表里没有的可点元素为 0 |
|
||||
| 状态覆盖 | 六个状态逐项有结论（勾选，或「不适用 + 理由」） |
|
||||
| 令牌表 | 色值 / 字体 / 间距两档且适用面已分开写 / 圆角 / 阴影全为具体值 |
|
||||
| 字阶定值表 | 七档每档一个 px 定值（不是区间）；相邻档差 ≥2px；每档只许一个定值 |
|
||||
| 高度层级 | 每层都有多层叠层值；同层级同值 |
|
||||
| 布局脚手架 | 骨架档已落到具体列宽；窄屏变化写具体 |
|
||||
| 组件规格 | 按钮三档 + 卡片两档 + 输入框 + 徽章均为具体值；同一父区块内主档 ≤1；实底底色 ≥2 种 |
|
||||
| 供给核对（本项目附加） | 三处供给已确认在位；选定套名与 `DESIGN.md` 记录一致；不一致则变更清单已确认并写入修订记录 |
|
||||
| 反 slop | 无紫→粉渐变、标题未用禁用字体、强调色已写明允许位置 |
|
||||
| 拒绝清单 | ≥3 条，且每条可判定 |
|
||||
| token 引用完整性（本项目附加） | 语义层只引 primitive、组件层只引语义层、无孤立 token |
|
||||
|
||||
任一项不过 → 停在 3a 补齐，不进 3b。
|
||||
|
||||
> 对比度门槛按 `open-design/craft/color.md`（正文 4.5:1 / 大字 3:1 / UI 组件 3:1），由终检阶段按真实像素复测（静态算不准 CSS 变量叠加后的结果）。
|
||||
> 已知环境问题：`npx @google/design.md lint` 在本机完全不可用（alpha + clack 交互库，非 TTY 管道下静默且 exit 0）。不要拿它当校验关卡，也不要因它无输出就认为通过。
|
||||
|
||||
## 3b 原型（构建）
|
||||
|
||||
> ⛔ 开工前先判页型（2026-10-05 新增，硬前置）：写下「本页是营销页还是工具型页面，依据是什么」。
|
||||
> 两种页型的目的不同，骨架不能通用：营销页目的是说服（主张 → 论据 → CTA），工具型页面目的是完成一件工作（数据 + 操作）。
|
||||
> 判别口径：要用户「下决心去做某事」⇒ 营销页；要用户「把这件事做完」⇒ 工具型页面。⚠️ 判不准时按工具型处理（默认取严）。
|
||||
> 判不出来不许进 3b，停下来回改 D0 的 `结构骨架`。
|
||||
> 🔴 为什么这条是硬前置：`open-design` 的种子 `assets/template.html` 是营销落地页骨架，自带 `.eyebrow`（眉标）与 `.lead`（副标题）。不判页型就照种子做，会得到「标题上方一行小字 + 大标题 + 下方一行灰色小字」的三段式——那是 2026-10-05 用户实测指出「像实习生画的」的唯一根因，而且结构判据全绿（判据判类名合法性，判不出「这不是工具界面的排版」）。页型不判，后面换什么设计系统都救不回来。
|
||||
|
||||
按 `open-design/design-templates/web-prototype/SKILL.md` 的六步走：读种子 → 把 `assets/template.html` 复制成 `index.html` 并替换 `:root` 令牌 → 先定版式节奏再粘骨架 → 填充 → 自查 P0/P1/P2 → 落盘。它的路线是「先选定一个明确的美学方向再写码」，与铁律 1 同向。
|
||||
|
||||
- ⭐ 工具型页面先判形态，再挑骨架（2026-10-02 新增）：读 `references/layouts-tooling.md`。本项目是工具型数据密集界面，而 `web-prototype/references/layouts.md` 那 8 个骨架是落地页 / 营销页向（hero / features / stats / quote / cta / log / pricing），只有 Layout 7 日志列表与 Layout 8 对比表沾得上。
|
||||
⚠️ 两份工具型文件的分工（2026-10-05 补）：`open-design/.../web-prototype/references/tooling.md` 给四形态判定句 + 通用红线纲要；本技能 `references/layouts-tooling.md` 给可粘贴 HTML 骨架 + 逐条判据正文（§5.5）。⛔ 判据只在后者展开，前者只指路，两处展开必然漂。
|
||||
形态判定一句话：页面上能数出「并列的同类记录」⇒ 列表型（工具型默认首选）；数不出、页面围绕单个对象展开 ⇒ 详情型；主操作要在两个工作面之间来回 ⇒ 侧区型。
|
||||
⛔ 不许拿营销页骨架顶替工具型，那是「没做形态判定」的默认行为，等于退回 18 轮前的病根。判不出形态就去改 D0 的 `结构骨架` 字段，⛔ 不许随手挑一个。
|
||||
- 不许从零手写 `<section>`：先挑最接近的骨架粘进去再改。`open-design/design-templates/web-prototype/references/layouts.md` 开头的类清单（`section` / `container` / `card` / `btn-primary` / `grid-3` …）必须在种子 `template.html` 的 `<style>` 里存在；缺哪个就补进 `<style>`，⛔ 不许在标签上内联一堆临时样式。
|
||||
- 输出形态：单文件 HTML、自包含、双击可开（与 `web-prototype` 的产出契约一致：只有 `index.html` 一个文件），含全部适用状态，不许有死按钮。
|
||||
|
||||
重大改版必须复制副本再改（`X.html` → `X v2.html`），不许覆盖旧版，旧版留在磁盘上以便对比。这是本项目的附加纪律（版本管理主线需要可追溯），open-design 未涉及。
|
||||
|
||||
交付前必须实测（本步硬关卡）：用 `browser-harness` skill 按清单逐个真点，以 D0 契约的「交互清单」为唯一清单（⛔ 不用自己临场编的顺序）：每行按「触发 → 反馈」实跑一遍，四态（空 / 加载 / 错误 / 失败重试）都要走到；回报控制台报错原文与「点了没反应」的元素清单。
|
||||
|
||||
> 交互清单在这一步才第一次被验证：Gate-1 只判「表写全了没」，判不了「真能跑」。清单与实现对不上，就是清单错了或实现错了，二者必居其一，都要在 `3d-审查报告.md` 里留痕，不许静默改表。
|
||||
|
||||
> 脚本查不出死按钮（即便脚本在位，它也只判溢出 / 对比度 / 状态可见性 / 点击目标尺寸，判不了「元素没绑事件」）。未跑实测不得进 3c，也不得报完成。
|
||||
> 实测一律走 `browser-harness`（浏览器入口 9333），禁用 Trae 自带浏览器工具。
|
||||
|
||||
## 3c GPT 会诊（必做）
|
||||
|
||||
触发点：原型初稿出完、3b 的浏览器实测过了，立刻做本步；做完才许进 3d。
|
||||
|
||||
做什么：用 `browser-harness` skill 打开 `chatgpt.com`，把原型交给 GPT 做一轮独立审查，专挑设计与交互的毛病，把回答取回来逐条处置。③段前三步全是本地确定性检查，没有外部视角，这一步补的正是它补不了的那块。
|
||||
|
||||
执行步骤：
|
||||
|
||||
1. 沿用用户已登录的浏览器会话打开 `chatgpt.com`。不要新建账号、不要代填密码、不要碰设置页。
|
||||
2. 用附件上传原型 HTML 文件（`designs/<项目>/<原型>.html`）。不要把上万字符的代码粘进输入框，会被截断或打字超时，且拿不回完整上下文。
|
||||
3. 随附件发这段提问模板：
|
||||
|
||||
```
|
||||
你是资深产品设计师。请按下面这份「需求 ＋ 设计风格」，独立设计并给出一个可运行的单文件 HTML
|
||||
（内联 CSS，不要外链任何资源），作为我们的参考版本。
|
||||
|
||||
需求：<②段的功能清单 ＋ 界面布局>
|
||||
设计风格：<DESIGN.md 的定调 ＋ 令牌表：主色/底色/字体/间距刻度/圆角/字阶/密度>
|
||||
|
||||
要求：这是工具型页面（数据 ＋ 操作，不是营销落地页）；把主要页面的形态都做出来；
|
||||
状态（空 / 加载 / 错误 / 禁用）要落地；页面要能在浏览器里真实打开。
|
||||
|
||||
请在代码之前先用三句话说明：你把主视觉放在哪、为什么这么排、和你见过的同类产品有什么不同。
|
||||
```
|
||||
|
||||
4. 等回答出完再取（停止生成按钮消失或出现复制按钮），把回答原文取回，不要读一半就走。
|
||||
5. 落盘 `designs/<项目>/3c-GPT会诊.md`，三段式：提问原文（含附件文件名）→ 模型回答原文 → 处置表。
|
||||
|
||||
处置表固定四列：
|
||||
|
||||
| # | 模型建议（原文摘句） | 判定 | 理由 | 落地位置 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | ... | 采纳 / 不采纳 / 待议 | 对照 `DESIGN.md` 与②段说清 | 文件 + 选择器 |
|
||||
|
||||
功能作用：引入一个不在本项目上下文里的外部视角，补自己看不见的盲区。
|
||||
|
||||
输入边界：只传原型 HTML 与必要的产品背景；不传密钥、真实用户数据、内网地址、`.env`。代码里若有 token 或接口地址，先替换成占位符再上传。一次只审一份原型。
|
||||
|
||||
异常情况：登录失效 / 人机验证 / 网络不通 / 回答被截断时，不要假装跑过。退路是把提问模板和原型文件路径交给用户，由用户在自己浏览器里问，再把回答粘回来落盘。仍然取不到时，在 `3c-GPT会诊.md` 里写明「本轮未取得外部审查」，并在本段收尾时明示，未取得不等于已通过。
|
||||
|
||||
处置纪律：模型建议不是命令。采纳要给理由，与 `DESIGN.md` 或②段冲突的写清为什么不采纳。采纳项在 3d 之前改完，并回到 3b 的实测清单把这些改动再点一遍。
|
||||
|
||||
## 3d 审查与打磨（收口 + 动效 + 终检 + Gate-2/3）
|
||||
|
||||
### 收口（管「写得对不对」）
|
||||
|
||||
对照 `open-design/design-templates/web-prototype/references/checklist.md`（P0 / P1 / P2 三级）＋ `craft/` 的四份数值判据（`typography.md` / `color.md` / `state-coverage.md` / `animation-discipline.md`）逐条过。先机器、后人工：
|
||||
|
||||
> ⚠️ 本段收口一律人工过（2026-10-02 用户定案「不重要的相关内容都删」）：checklist 人工过 ＋ 渲染截图 ＋ DOM 取值，三项缺一不可。
|
||||
> ⛔ 判据来源：`craft/checklist.md` ＋ `craft/anti-ai-slop.md` ＋ `craft/accessibility-baseline.md` ＋ `craft/color.md`（对比度），本项目追加条见 runbook §3.4。
|
||||
> ⛔ 结论只能写「人工判定」，⛔ 不许写「已通过」（人工过就是人工过，不借机升格）。要指向交付的单文件，不要指向多文件开发目录。
|
||||
|
||||
### 动效（可跳过）
|
||||
|
||||
按 `open-design/craft/animation-discipline.md` 先答动效三问：① 它传达什么信息？② 删掉会丢失什么？③ 是不是为了「看起来高级」？答不出就不加。
|
||||
|
||||
- 工具型页面（仪表盘 / 后台 / 编辑器 / 工作台）禁止入场编排，用户一天开几十次，每次播一遍是折磨。本项目的版本管理界面属工具型；判不准时按工具型处理
|
||||
- 弹簧用 Damping / Response 二参数（Damping 保持 0.8–1.0、Response 0.3–0.4s；低于 0.7 会明显「蹦」）
|
||||
- CSS 无法用真弹簧时用 `cubic-bezier(0.32, 0.72, 0, 1)`，不得用 `linear` / `ease` / `ease-in-out` 做过渡曲线
|
||||
- 交互过渡禁 `@keyframes animation`（不可中断，反向操作会跳帧），用 `transition` 或 WAAPI
|
||||
- 只动 `transform` / `opacity`，不动 `width`/`height`/`top`/`left`；禁止 `scale(0)` 起手（用 `scale(0.95)` + opacity）
|
||||
- 退出比进入快（进 300ms / 出 200ms）；同屏动效元素 ≤3 个且有 30–50ms 错峰
|
||||
- `prefers-reduced-motion` 必须处理
|
||||
|
||||
### 终检（管「能不能交」）
|
||||
|
||||
过 checklist 的 P0/P1 ＋ `craft/state-coverage.md`（状态穷举）＋ `craft/anti-ai-slop.md`（反 AI 味，⛔ 不在本文件抄清单）＋ 动效三问 ＋ 交互清单逐行复测（表里每一行的「触发」与「反馈」都要真发生过，且与实现一致），并真渲染一次：
|
||||
|
||||
```bash
|
||||
# 本机 Chrome 无头截图（2026-10-02 实测可用；门禁脚本补上后仍以脚本为准）
|
||||
"/c/Program Files/Google/Chrome/Application/chrome.exe" --headless=new --no-sandbox --disable-gpu \
|
||||
--hide-scrollbars --window-size=1440,900 --virtual-time-budget=3000 \
|
||||
--screenshot="<Windows 绝对路径>/P1.png" \
|
||||
"file:///<原型绝对路径，中文需 URL 编码>#/p/xxx"
|
||||
```
|
||||
|
||||
- ⚠️ 两条坑：`--screenshot` 必须给 Windows 绝对路径（给相对路径会写进 Chrome 安装目录，回来找不到）；中文文件名要 URL 编码
|
||||
- 在 `1440x900` 与 `390x844` 两个视口各截一张；对外评审 / 交付留档只用视口帧，整页长图仅自检。⛔ 混用会出事：实测把长图交出去，移动端是 1:7.1 的长条，外部评估只能按长条理解布局，「首屏有没有主次」「坐得下几行」根本没被评审到
|
||||
- 结构与排版仍要量（字号档数与相邻档差 / 正文档承载占比 / 标题大纲 / 按钮高度与实底分档 / 列对齐 / 对齐锚点 / 浮层可见关闭出口唯一）：脚本缺失期间靠 DOM 取值人工量，结果直接抄进 `3d-审查报告.md` 的结构核对表。⛔ 不许目测截图下结论
|
||||
- 「无法判定」一律按未通过对待（「判不了」≠「没问题」）：浮层类在未打开态必然判不了，必须按 Gate-3 的打开态复测口径，手工打开每个浮层再数一遍并留痕
|
||||
- 本项目的状态由路由与演示开关驱动，不用 `?state=`；状态可见性由 `browser-harness` 实测承担
|
||||
|
||||
### Gate-2 完成门
|
||||
|
||||
全部 `阻断` 项清零，`建议` 项逐条有结论：修掉，或显式写「已知不修 + 原因」。不接受「基本没问题」「应该差不多」「剩余都是小问题」。每条要么修，要么留痕。
|
||||
|
||||
### Gate-3 交付门（硬闸，任何挡位不可跳）
|
||||
|
||||
真实渲染后（浏览器打开，非只看代码）肉眼过八项：裁切 / 重叠 / 失真 / 失效控件 / 缺状态 / 响应式破损 / 控制台报错 / 字体回退异常。渲染截图已代劳其中的溢出与响应式破损，其余仍需人眼（截图查不出「点了没反应」）。
|
||||
|
||||
### 审计报告落盘
|
||||
|
||||
`designs/<项目>/3d-审查报告.md`，固定七节：范围 + 挡位 + 阻断项表 + 建议项表 + 状态覆盖核对表 + 结构核对表 + Gate 结论（含「本轮是否跑了脚本」一句）。
|
||||
|
||||
## 硬约束
|
||||
|
||||
- ⭐⭐ 骨架冻结，不许动板块（2026-10-06 用户定案）：页面清单、每页板块、板块排列、跨页关系由②段《界面布局》定死。
|
||||
⛔ 本段不许新增 / 移动 / 删除 / 合并板块。做不下来 / 觉得缺板块 ⇒ 回②段改《界面布局》，⛔ 不许就地加一块，就地加会让②段与原型不一致，下一个读原型的人拿到的是错的骨架。
|
||||
可动的是板块内的视觉与交互实现（怎么排版好看、点哪有什么反馈、空态怎么呈现、响应式怎么变）。
|
||||
⛔ 不许无视②段骨架另起一套。D0 的页面清单与每页板块必须与②段《界面布局》逐条对得上；对不上就停下来问②段要哪一版。
|
||||
- 声明制：开工前、每进一个子步、每处偏离，都要声明（当前子步 / 依据文件 + 小节号 / 产出落点）。不许静默偏离。段末必须附偏离单，没有偏离单不得报完成。
|
||||
- 设计工程供给默认是 `open-design`（三处：设计系统 / 工艺规约 / 原型模板，按需取用）；冲突处以本段与 `DESIGN.md` 为准。不许跳过 Gate-1 或 Gate-3。
|
||||
⚠️ `open-design` 不可得时（它只在工作区级，别的工作区可能没有）⇒ 见上方「不可得时的回落」：由 `oil-ui-pro` 顶方向探索与评审，但定调与工艺数值判据会没有来源，⛔ 不许凭感觉编。
|
||||
- 页型先判再动手（2026-10-05 新增）：3a 的 D0 必须写出「营销页 / 工具型页面 + 依据」。工具型页面零 `.eyebrow` / 零 `.lead` / 零 `.hero`，三者已从种子删除或降级为 `body.is-marketing` 专用。⛔ 判不出页型不许进 3b。
|
||||
- `open-design` 的 `web-prototype` 种子是营销落地页骨架：⛔ 工具型页面不许直接套用其版式节奏与标题区结构；版式走本技能 `references/layouts-tooling.md`。这是一处「照供给做反而错」的例外，必须显式绕开。
|
||||
- 先定死，再写码：设计契约与令牌表未落笔，不许写任何组件代码。
|
||||
- 限载：一次只读 1~2 份供给原文，用完释放（`design-systems/` 153 套、`craft/` 13 份，全读必然互相稀释）。
|
||||
- 不许覆盖旧版：重大改版先复制副本再改（`X.html` → `X v2.html`），旧版留在磁盘上以便对比。
|
||||
- 3a 必须在 3b 之前，规范是原型的输入。
|
||||
- 门禁脚本只作校验，不是原型生成工具。出原型只用 3b（脚本当前缺失，见 3d 的「门禁脚本现状」）。
|
||||
- 原型必须可点通：每个按钮、每个跳转都真能走，不许留死链。可点通的清单就是 D0 契约的「交互清单」，清单之外的可点元素 = 未登记元素，必须回 D0 补登记或改成静态，⛔ 不许「清单没写但先做着」。
|
||||
- 交互清单是唯一交互真相源（2026-10-02 新增）：段名已改为「界面交互」，故交互判据只许写在契约第十二字段里。3b 实测、3c 会诊、3d 终检都引用同一张表，⛔ 任何一处另立一份交互清单（另建文档、另写章节、另做交互规范）都算第二真相源，这正是记忆里「同一事实多处落点必然打架」的成因。
|
||||
- 3b 交付前必须用 `browser-harness` 跑实测；脚本查不出死按钮，未跑实测不得进 3c，不得报完成。
|
||||
- 3c GPT 会诊必做：原型初稿 + 实测过后立刻做，不许用「我觉得没问题」代替。回答原文必须落盘，不得伪造或转述失真；未取得外部审查时要在 `3c-GPT会诊.md` 与收尾里明示，未取得不等于已通过。上传前先脱敏。
|
||||
- Gate-2 / Gate-3 不许口头通过：阻断项要么修完，要么留痕；「未取得审查」不等于已通过。
|
||||
- 原型的说明区与演示引导不是本段的事：各状态下的「场景 / 从左到右流程图 / 步骤说明 / 演示引导」由第④段 `stage-proto-doc` 负责。3d 完就交付原型本身。
|
||||
- `DESIGN.md` 落 `docs/pm/<项目>/`，不放仓库根。
|
||||
- 段内子步之间不反问，做完直接进下一个子步。只有三种情况停：信息不足且查不到、破坏性/不可逆动作、用户显式要求。
|
||||
- `<项目>` 按 `product-planning` 的「项目与路径约定」定；定不出来就停下问用户，不许猜。
|
||||
|
||||
## 完成标准
|
||||
|
||||
- 声明制走完：开工、每个子步、每处偏离都有声明；偏离单已附，无静默偏离
|
||||
- 挡位已声明（快速 / 标准 / 严格）
|
||||
- 页型已判（营销页 / 工具型页面 + 依据）；工具型页面零 `.eyebrow` / 零 `.lead` / 零 `.hero`，且 `layouts-tooling.md` §5.5 五条逐条过完（含「标题区零从属小字」的 DOM 取值核对）
|
||||
- `docs/pm/<项目>/DESIGN.md` 存在，含设计契约（十二个字段，含结构骨架、交互清单与重复项的信息量）与令牌表（三层 token 结构，含组件规格、容器与对齐锚点、浮层只许一个可见关闭出口，全为具体值），且 Gate-1 全部自检项结果写在文件末尾
|
||||
- 原型 HTML 单文件自包含、双击可开，含全部适用状态（状态穷举六项逐条有结论）
|
||||
- 原型经真实渲染验证过，控制台无报错
|
||||
- 每个按钮都经 `browser-harness` 真点过，有实测回报（含控制台报错原文与死按钮清单）
|
||||
- 静态收口已过（脚本在位 ⇒ 已跑且阻断清零、有输出留档；脚本缺失 ⇒ 已按 checklist 人工过，并在报告中写明「未跑脚本 + 原因」）
|
||||
- 渲染终检已过（溢出 0 / 对比度按真实像素达标 / 结构与排版量测无阻断且无「无法判定」项 / 两个视口的截图都存进 `_gate_shots/`），或已写明为何不适用。量测数字以 DOM 取值与脚本输出为准，不得用「目测」代替
|
||||
- 每个浮层都手工打开数过可见关闭出口（`== 1`），`Esc`/点遮罩能关、焦点锁在层内且关闭后回到触发按钮，结论连同触发路径写进 `3d-审查报告.md`。「代码里看着只有一个」不算
|
||||
- 对外提交/交付留档的截图只用视口帧（`_gate_shots/<视口>.png`）；`_full/` 下的长图不得作为评审输入
|
||||
- `designs/<项目>/3c-GPT会诊.md` 存在，含提问原文、模型回答原文与逐条处置（采纳项已改完并复测）；未取到外部审查的已明示
|
||||
- `designs/<项目>/3d-审查报告.md` 存在，含阻断/建议两张表 + 状态覆盖核对 + Gate-2/3 结论
|
||||
- Gate-2 与 Gate-3 均已通过（书面结论，非口头）
|
||||
- 重大改版：旧版文件仍在磁盘上，且收尾给出新旧差异（改了什么 / 为什么 / 代价）
|
||||
|
||||
## 反面清单
|
||||
|
||||
- ⛔ 就地增删板块（2026-10-06 新增）：觉得骨架不合适就自己加一块 / 挪一块 / 删一块。骨架归②段，要改回②段改，本段只能动板块内的视觉与交互实现；就地改会让②段与原型不一致
|
||||
- ⛔ 无视②段骨架另起一套（2026-10-06 新增）：D0 的页面清单与每页板块必须与②段《界面布局》逐条对得上
|
||||
- 先出原型再补规范（违反铁律 1）
|
||||
- 违反限载：一次把全部 `design-systems/` 或 `craft/` 原文读进上下文（一次只许 1~2 份）
|
||||
- 不判页型就照 `web-prototype` 种子做，会把后台做成营销页（标题上下各一行小字）；或拿 `layouts.md` 的营销骨架顶替工具型版式
|
||||
- 只画了 success 态就当状态齐了（违反铁律 3）
|
||||
- 跳过 Gate-1 或 Gate-3；或拿「我觉得还行」当 Gate-2 结论
|
||||
- 在无脚本时把「没跑」写成「已过」；或从零手写 `<section>` 不套骨架、把临时样式内联在标签上
|
||||
- 覆盖旧版：重大改版直接改原文件，把可对比的旧版弄丢
|
||||
- 把 `DESIGN.md` 写到仓库根（多项目会互相覆盖）
|
||||
- 原型里有死按钮或空链接；只用脚本判过就当实测过（脚本查不出死按钮）
|
||||
- 拿默认配色和系统字体糊一个「能看」的界面交差
|
||||
- 跳过 3c GPT 会诊直接进 3d，或只把代码片段贴进对话框、回答没出完就取走当完整建议
|
||||
- 把模型建议当命令照抄，改坏与 `DESIGN.md` 的一致性；或伪造「GPT 说……」却拿不出回答原文
|
||||
- 把「未取得外部审查」当已通过
|
||||
- 工具型页面做入场编排；用 `linear`/`ease` 做过渡曲线；用 `@keyframes` 做交互过渡
|
||||
- 越界回头改②段的功能取舍（那是第②段）——⚠️ 但「骨架缺板块」是例外：必须回②段改，⛔ 不许就地在原型里加
|
||||
- 顺手把原型说明文档 / 演示引导写了（那是第④段 `stage-proto-doc`）
|
||||
|
||||
## 待补（2026-10-02 登记 · 2026-10-06 更新）
|
||||
|
||||
- ~~`execution-runbook.md` 的必读表全部指向已不存在的文件~~：已于 2026-10-02 修复（用户定案「第三部分用 open-design」后执行）。原 D0/D3/D4/D5 四行引用的 `ui-page-design/references/0X_*.md` 与 `vendor/*` 已全部重接：`D0 → runbook §2.1`（十二字段留在本项目）｜`D0 判据 → craft/state-coverage.md`｜`D1 → open-design/design-systems/ 选套`｜`D2 → design-templates/web-prototype/`｜`D3 → craft/typography.md` + `typography-hierarchy.md`｜`D4 → craft/animation-discipline.md`｜`D5 → checklist.md` + `craft/anti-ai-slop.md` + `craft/accessibility-baseline.md`。
|
||||
同时做了一次能力去向盘点（判据逐条归属，不做适配搬运）：craft 接住 6 类（状态穷举 / 字阶 / 配色 / 动效 / 反 AI 味 / 无障碍与表单校验）；接不住 3 项，必须留在本项目 —— 设计契约十二字段 / 结构骨架 / 交互清单；5 份 vendor（`ui-ux-pro-max`／`frontend-design`／`apple-design`／`anti-ui-slop`／`web-design-guidelines`）无需保留。
|
||||
⛔ 修复后的纪律：判据来源必须单一可查。某条判据若在 runbook 与 craft 各有一份且口径不同，以本项目追加条为准，并在 §3.4 显式标注「本项目追加」。
|
||||
- ~~工具型页面的版式库~~：已于 2026-10-02 补齐。新建 `references/layouts-tooling.md`，四类形态各给一份可判定骨架：行式列表 / 表格式清单 / 详情面板 / 主从侧区。每类带形态判定句（判不出形态就去改 D0 `结构骨架`）＋ 可机械核对的判定要点（如「一屏可见行数 ≥6」「数字列右对齐」「表头必须写判据来源」「未跑必须能作为取值存在」）。已接进三处：3b 正文（形态判定先行）｜runbook §1 必读表 D2 行（工具型另读）｜runbook「⛔ 四样 craft 接不住」表（第四行）。
|
||||
⭐ 红线：⛔ 不许拿营销页骨架顶替工具型，那是「没做形态判定」的默认行为，等于退回 18 轮前的病根。
|
||||
- ~~①②段的同型改造~~：已于 2026-10-02 完成。四段已改名为「①产品需求 / ②产品功能 / ③界面交互 / ④原型说明文档」，并各自重划了子步职责（见 `product-planning` 的四段表与交接口表）。
|
||||
- ⛔ 骨架归属已于 2026-10-06 反转：本节原口径是「页面结构归本段，唯一落点是 D0」；用户定案改为「②段钉骨架，③段做皮肉」（原话：页面关系和布局必须在第二步确认清楚，不然第三步没有方向 一会一个样子）。⇒ `必要内容` / `结构骨架` 两个字段口径已调整，从「本段独立裁决」改为「在②段给定骨架之内决定视觉与交互实现」。详见本文件开头「⭐⭐ 页面骨架不归本段了」块。
|
||||
⚠️ 待核：`references/execution-runbook.md` 的 D0 段仍写着旧口径（「独立推导几个页面」），需同步改。另，`gate-<段号>-<段名>.md` 本项目从未建立，属存量缺口。
|
||||
@@ -1,424 +1,423 @@
|
||||
# ③段执行手册（固化流程）
|
||||
|
||||
`SKILL.md` 写规则，本文件写照着走的顺序与验收。跑③段时按本文件逐步走；任何一步偏离，必须当场声明并记入第 6 节偏离单。
|
||||
|
||||
> 本手册为什么存在：③段 3b 交付了原型，却走了别的主流程、没读依据文件、执行时也没声明，用户直到追问「基于哪个 skill」才知道。所以第一条是声明制，第二条是逐步写明依据哪个文件的哪一节。
|
||||
> ③段的设计工程供给默认是 `oil-ui-pro` 技能（方法主线与独立评审）加本段自带样式库（定调与令牌）；`open-design` 是可选档，随本段携带，选了才用（定义只在本段 `SKILL.md` 的 §供给 里，本手册不重复；2026-10-08 用户定案：默认从 open-design 改成 oil-ui-pro）。供给一律按段内相对路径或技能名引用，不写死绝对路径与 `../` 层数（位置一变就失效且不报错）。流程规则与契约字段留在本手册与 `SKILL.md`。两者分工见第 1 节末的「⛔ 四样必须留在本项目」。
|
||||
|
||||
---
|
||||
|
||||
## 0. 声明制（核心，唯一不可商量的一条）
|
||||
|
||||
开工前先输出一段流程声明，四个字段：
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 当前段与子步 | 例：③段 / 3b 原型（D2 构建） |
|
||||
| 主干与挡位 | 例：供给 `oil-ui-pro` ＋ 自带样式库 / 挡位「标准」（或「快速」） |
|
||||
| 依据文件 | 本步照的是哪个文件的哪一节，写精确路径 + 小节号 |
|
||||
| 产出落点 | 本步会写哪个文件 |
|
||||
|
||||
每进一个子步重发一次这四行（子步之间不反问，但必须声明）。
|
||||
|
||||
偏离时当场声明：
|
||||
|
||||
```
|
||||
偏离：<原要求> → <实际做法>；原因：…；影响：…
|
||||
```
|
||||
|
||||
并记入第 6 节。不许静默偏离，不许事后补说。
|
||||
|
||||
---
|
||||
|
||||
## 1. 必须加载的文件（按阶段加载，用完释放）
|
||||
|
||||
> ⚠️ 2026-10-02 已重接必读源。原必读表指向 `ui-page-design/references/02_~05_*.md` 与 `vendor/*`，该目录实测已不在磁盘上（工作区与全局技能根两处都查过），照旧表走 D0 读不到任何一份必读文档。现改为引本段自带件 `assets/open-design/`（段内相对路径）与技能 `oil-ui-pro`（按技能名）。
|
||||
> 改动原则：判据类全部交出去，只保留 craft 没有对应的东西。
|
||||
|
||||
开工前必读供给的位置与分工：默认档是 `oil-ui-pro`（入口 `SKILL.md`）＋ 本段自带样式库 `assets/design-systems/`；选了可选档时，另读它的 `craft/README.md`（读一份就知道有哪些规约、怎么按需取）。定义与行名见本段 `SKILL.md` §供给。
|
||||
|
||||
其余不许一次全读。同一时刻只读 1~2 份，用完释放；`design-systems/` 153 套、`craft/` 13 份全读必然互相稀释。
|
||||
|
||||
> 下文凡出现 `open-design/...` 的路径，一律指本段**随段携带的自带件** `assets/open-design/...`（独立技能、可选择使用）；不选它就按默认主线走（`oil-ui-pro` 方法 ＋ 自带样式库定调 ＋ 本段自家 `execution-runbook.md` 与 `layouts-tooling.md` 判据），craft 独有的那几项明说「本次无供给来源」。
|
||||
|
||||
| 阶段 | 读什么 | 为什么 |
|
||||
|---|---|---|
|
||||
| D0 | 本文件 §2.1（设计契约十二字段） | craft 无对应 —— 字段清单是本项目的东西，只在这里 |
|
||||
| D0 判据 | `craft/state-coverage.md` | 状态六项的逐项判据 |
|
||||
| D0 页型（2026-10-05 新增） | 本文件 §2.1 步 6（先判页型：营销页 / 工具型） | 挑版式骨架之前必须先判。判错页型 = 拿营销骨架做后台，是「标题上下两行小字」的唯一根因 |
|
||||
| D1 | §供给·定调与令牌 的选定档（⛔ **文件名按该套实际有的读**，见 §2.2 的「D1 读什么」）；定调来自选套，不来自检索脚本 | 定调**必须**取到版式与组件结构，⛔ 只取色值/圆角/间距不算取用选定套（判据见 §2.2 末） |
|
||||
| D1 多方向比选（按需） | `oil-ui-pro` 的 `references/design-direction.md` + `references/style-explorer.md` | 要「拉开几个方向让用户挑」时的方向卡与对比页（另一技能，平行取用） |
|
||||
| D2 | §供给·版式骨架：默认档读本技能 `references/layouts-tooling.md`（HTML 骨架与落地自检）；选了可选档另读它自己的 `SKILL.md` + `references/layouts.md`（营销页）＋ `references/tooling.md`（四形态判定句与通用红线纲要） | 「先选定美学方向再写码」＋ 版式骨架。⭐ 可选档是营销页向、工具型不适用（骨架名单与理由见 `references/layouts-tooling.md` 开头）；工具型版式只用默认档，不许拿营销页顶替。⚠️ 两份工具型文件是「骨架 vs 纲要」分工，判据不重写（判据正文在 `layouts-tooling.md`） |
|
||||
| D3 | `craft/typography.md` + `typography-hierarchy.md`（+ 按需 `color.md`） | 字阶定值表与层级判据（取代原 `03_视觉与骨架规则.md`） |
|
||||
| D4 | `craft/animation-discipline.md` | 动效三问、弹簧二参数（取代原 `04_动效与手势规则.md`） |
|
||||
| D5 | `design-templates/web-prototype/references/checklist.md` + `craft/anti-ai-slop.md` + `craft/accessibility-baseline.md` | 终检清单、反 AI 味、无障碍底线（取代原 `05_审计门禁与输出格式.md`）。⚠️ 工具型页面必须过 checklist 的 `P0-A 标题区纪律`（2026-10-05 新增，五条） |
|
||||
| D5 独立评审（按需） | `oil-ui-pro` 的 `references/visual-review.md` + `references/tools.md` | 要「没看过制作过程的评审打分」时的协议与截图取证（不替代本段 Gate） |
|
||||
| 每步 | `docs/pm/<项目>/DESIGN.md` | 本项目绑定规范；原型只许引它的 token |
|
||||
|
||||
⛔ 四样东西 craft 没有对应，必须留在本项目（本文件 / `SKILL.md` / `references/layouts-tooling.md` 里）：
|
||||
|
||||
| 留什么 | 为什么 craft 接不住 |
|
||||
|---|---|
|
||||
| 设计契约十二字段 | craft 是通用工艺，不定义字段清单；D0 字段是本项目的产物 |
|
||||
| 结构骨架（骨架档 / 区块划分 / 密度目标） | 实测 grep 全部 craft 只有零散的 layout 提及，无成体系的骨架规则 |
|
||||
| 交互清单（契约第十二字段） | 同上 —— 交互的判据在 craft 里只散见于 `state-coverage` 与表单章，不构成一份逐元素清单 |
|
||||
| 工具型版式库（档位名单与判读见 `references/layouts-tooling.md` §0，⛔ 此处不复述） | 可选档那套是营销页向（骨架名单与理由见 `references/layouts-tooling.md` 开头），工艺判据里对版式只有零散提及、不成体系。工具型数据密集界面的版式无现成来源 ⇒ 本项目自建 `references/layouts-tooling.md`（2026-10-08 追加矩阵型 / 对照型 / 流水线型 / 时间线型四档，其中流水线型含 AI 产出区的硬判据） |
|
||||
|
||||
定调来源唯一（两档见 §供给·定调与令牌）：默认档从自带样式库选一套；选了可选档就从可选档选（153 套），按候选套 `DESIGN.md` 第 1 章 `Visual Theme & Atmosphere` 认准类型词。⛔ 两档不混用。
|
||||
本 skill 的 `references/` 只放流程规则（契约字段 ＋ 执行顺序 ＋ 门禁），不放任何风格底子。既有项目 `DESIGN.md` 里凡引用旧风格来源（`ui-ux-pro-max` / `minimalist-ui` / 皮肤族）的行，重跑 3a 时一律改写为「选定套名 ＋ 留痕对照」。
|
||||
|
||||
已整体移除的 vendor，不必再找：`ui-ux-pro-max`（被 153 套设计系统取代）、`frontend-design`（D1 已改选设计系统）、`apple-design`（动效已由 `craft/animation-discipline.md` 覆盖）、`anti-ui-slop`（按本项目收录标准「依赖外部服务」整体移除，判据由 `craft/anti-ai-slop.md` 接管）、`web-design-guidelines`。
|
||||
⚠️ 判据一旦落进本项目的条款，就不再依赖原出处的存续。上面五份的可执行内容已在 `SKILL.md` 铁律、`craft/` 与本文件里，删掉原出处不影响执行。
|
||||
|
||||
---
|
||||
|
||||
## 2. 3a 视觉规范（D0 锚需求 + D1 定调 + Gate-1）
|
||||
|
||||
### 2.0 供给核对（步 −1，每轮必做）
|
||||
|
||||
`open-design` 是随段携带的本地裁剪版（源 `nexu-io/[email protected]`，Apache-2.0），上游更新不会自动跟进来；而本项目的 `DESIGN.md` 是上一次供给状态下产出的。不核对就长期拿旧调性当准绳：换套后门禁判不过，却不知道哪条变了。
|
||||
|
||||
| 步 | 动作 | 验收判据 |
|
||||
|---|---|---|
|
||||
| −1 | 确认三处供给仍在位：`design-systems/`（并记录本项目选定套名）、`craft/`、`design-templates/web-prototype/` 都存在 | 三处都在位；`DESIGN.md` 记录的上次套名已找到 |
|
||||
| −1b | 套名一致 → 直接进 D0 | 开工声明里写一句「选定套 `<套名>`，与项目记录一致」 |
|
||||
| −1c | 套名不一致或供给缺失 → 停下报告，不许拿别的套顶上，也不许凭记忆写风格 | 产出供给变更清单（逐条：变了什么 → 本项目现状 → 要改什么），在会话里呈现并获用户确认后才改 `DESIGN.md` |
|
||||
|
||||
> 不要静默跳过：一致也要在开工声明里写一句套名；不一致必须停下，这是硬闸。
|
||||
|
||||
### 2.1 D0 锚需求 → 设计契约
|
||||
|
||||
> ⭐⭐ 口径（2026-10-06 用户定案）：骨架归②段，本段做皮肉。
|
||||
> 两侧完整对照只在②段 `SKILL.md` 的 §②—③ 交接口 定义一次（本手册不重复那张表，理由与用户原话见那一节）。
|
||||
> ②段《界面布局》里的页面清单、每页板块、板块排列、跨页关系就是骨架定稿。本段不许增删移动板块，要改回②段改。本段在给定骨架内决定视觉与交互实现。
|
||||
> ⛔ 仍归本段的：见 §②—③ 交接口 的「归③段」列。
|
||||
|
||||
读②段时取四样：骨架（页面清单 ＋ 每页板块 ＋ 排列 ＋ 跨页关系）、必须在界面上发生什么、红线、禁用条件与状态流转。
|
||||
骨架是冻结输入，其余三样是功能约束。
|
||||
|
||||
按本节清单产出设计契约，十二个字段：页面职责（「让<谁>在<多久>内<完成什么>」）、主用户、主操作（全页唯一，写了两个就该拆页）、必要内容（核对面）、重复项的信息量（行式列表 / 卡片网格时逐条列出：每个重复项除「主标识 ＋ 动作」外必须带 ≥1 条次级信息）、结构骨架（翻译面：把②段板块清单翻成骨架档 ＋ 列宽 ＋ 密度目标）、交互清单（2026-10-02 新增：逐个可点元素一行，四列「元素 / 触发 / 反馈 / 何时不可点」；动效参数归 3d、视觉样式归令牌表、「这个状态有没有」归下一字段状态覆盖）、状态覆盖六项逐条、组件来源（优先沿用既有）、响应式行为（写布局怎么变，不写「自适应」）、明确拒绝的模式（≥3 条可判定）、验收标准（可观察可判定）。
|
||||
|
||||
两个字段的分工（2026-10-06 调整）：`必要内容` 是核对面，`结构骨架` 是翻译面。
|
||||
|
||||
> `结构骨架`（翻译面）怎么落（规则留在本手册，craft 无对应：实测 `craft/` 只有零散 layout 提及，不构成骨架规则）：
|
||||
> ⭐ 输入是②段的板块清单，本字段做的是翻译，不是发明。
|
||||
> ① 骨架档：单列 / 主区＋侧区 / 主区＋侧区＋辅助区，选一档并写清理由。有 ≥3 个并列目的地且宽屏 ≥1024 时优先侧栏，但侧栏是项目级取舍，不许写死成「必须没有」。
|
||||
> ② 板块落位：把②段给的板块按顺序放进骨架档，每块给一个文字标题（页面 ≥2 个带文字标题的板块）。
|
||||
> ③ 密度目标：宽松（24–96）/ 标准（16–64）/ 密集（8–32），同一页面不得混用两档。
|
||||
> ⛔ 不许在②段板块清单之外加块，缺板块回②段改。
|
||||
> 板块先分、内容后放，顺序反了就只能得到一张平铺的长条。
|
||||
|
||||
> `必要内容`（核对面）的判据不变，但用途变了。
|
||||
> 判定标准仍是模板里那句「只留缺了就做不成事的」。
|
||||
> 逐条问：这条内容删掉，主操作还做得成吗？做得成，它就不该主屏常驻（②段分档表已定档位）。
|
||||
> ⚠️ 本段不得以 `必要内容` 为由增删②段已定的信息档位。档位归②段，本段只做落位核对。
|
||||
> 本段该做的是：核对②段的「主屏常驻 / 可点入」分档，在本段自己的视觉与交互实现里兑现它（常驻的零点击可见、可点入的一次点击可达）。
|
||||
> 危险信号：`必要内容` 与②段分档表逐条对不上（条数差很多、档位被改）→ 停下来说明，不自行改档。
|
||||
> 反面样例（本项目真实踩过）：版本列表的 `必要内容` 只该有「`vN` ＋ 语义名 ＋ `第 N/5 步` ＋ 状态徽章 ＋ 时间戳 ＋ 行尾当前动作」，实际却把每行那句解释性长文案（「目录建好了，还没有登记原始需求。」）也当成必备内容渲染上去，于是每行多出一整句、页面变成信息墙。
|
||||
|
||||
| 步 | 动作 | 验收判据 |
|
||||
|---|---|---|
|
||||
| 0 | 读②段《界面布局》，把骨架当冻结输入取走 | 页面清单与每页板块逐条抄进契约，未增删移动 |
|
||||
| 1 | 产出设计契约 | 十二个字段全填，无空、无「待定」；有重复项时「重复项的信息量」已逐条列出次级信息；交互清单覆盖页面上每一个可点元素 |
|
||||
| 2 | 状态覆盖逐项给结论 | 六项要么勾选，要么写「不适用 ＋ 理由」 |
|
||||
| 3 | 核对②段分档表：每条信息的「主屏常驻 / 可点入」 | 与②段分档表逐条对得上；档位未被本段改动（要改回②段） |
|
||||
| 4 | 落 `结构骨架`：把②段板块清单翻成骨架档 ＋ 列宽 ＋ 密度目标 | 骨架档给了理由；板块 ≥2 个且每个有文字标题；板块清单来自②段、未新增；密度目标只取一档 |
|
||||
| 5 | 自检块间距 ≥ 块内间距的 2 倍 | 块间 32/64、块内 8/12/16，比值 ≥2（写进令牌表） |
|
||||
| 6 | 判页型（2026-10-05 新增，D2 之前必做）：写一句「本页是营销页还是工具型页面，依据是什么」 | 结论明确且给了依据。判不出来不许进 D2，停下来回改 `结构骨架` |
|
||||
|
||||
> ⭐⭐ 步 6「判页型」是 2026-10-05 新增，补的是一处从未有过落点的缺口。
|
||||
> 病灶实测：本项目原型长出「标题上方一行小字眉标 → 大标题 → 下方一行灰色副标题」的三段式。
|
||||
> 根因不在③段执行：`open-design` 的种子 `assets/template.html` 是营销落地页骨架，CSS 里自带 `.eyebrow`（眉标）与 `.lead`（副标题），`layouts.md` 的 8 个骨架里有 6 个在用，而当时的 checklist 甚至明令保留（「Lead text under 56 ch … don't override」）。
|
||||
> 于是照种子做 = 结构全绿 ＋ 排版难看：判据判的是「类名合法」，判不出「这不是工具界面的排版」。页型不判，后面用什么设计系统、怎么打磨都救不回来。
|
||||
>
|
||||
> 两个页型的目的不同，骨架因此不能通用：
|
||||
> - 营销页（落地页 / 首页 / 定价页）：目的是说服，走「主张 → 论据 → CTA」，可用 hero / eyebrow / lead。
|
||||
> - 工具型页面（后台 / 控制台 / 列表 / 详情 / 看板 / 表单）：目的是完成一件工作，走「数据 ＋ 操作」，零 `.eyebrow`、零 `.lead`、零 `.hero`（三者已在种子中删除或降级为 `body.is-marketing` 专用）。
|
||||
>
|
||||
> 判别口径：页面要用户「下决心去做某事」是营销页；要用户「把这件事做完」是工具型页面。
|
||||
> ⚠️ 判不准时按工具型处理（默认取严）。
|
||||
|
||||
### 2.2 D1 定调 → 令牌表
|
||||
|
||||
> 🔴 **D1 读什么（2026-10-08 补 · 本节的硬前置）** —— 定调要取**三样**，⛔ 只取数值不算取用选定套：
|
||||
>
|
||||
> 1. **数值**：选定套的 `tokens.css`（色值／圆角／间距／按钮／卡片／输入框）。
|
||||
> 2. **版式结构**：选定套里记「外壳怎么分（侧栏／顶栏／主区）」「内容区用列表还是卡片网格」的那份。
|
||||
> 3. **组件族**：选定套里列组件族与样张的那份。
|
||||
>
|
||||
> ⛔ **文件名随档而异，按该套目录里实际有的读**：本包默认档那套（`assets/design-systems/design-system-tiaoyue/`）
|
||||
> 给组件的是 `references/components.md`（组件族）＋ `references/design-system.html`（样张），
|
||||
> 它**没有** `components.html` —— 那是**可选档 153 套**的命名。
|
||||
> 🔴 2026-10-08 实测事故：D1 步骤原写 `components.html` ⇒ 在默认档里**按名字找不到** ⇒ 那一次只取到了
|
||||
> 色值与圆角，**版式结构与组件族整层漏掉** ⇒ 做出的界面「用了它的样式、没有它的排版」。
|
||||
> ⇒ 判据：`DESIGN.md` §2.5 组件规格**每一行都要写出处**（取自哪个族／哪个结构），⛔ 只写数值不写出处即判**未取用**。
|
||||
|
||||
从 `assets/open-design/design-systems/`（153 套）选一套，不凭感觉编、不全读：
|
||||
|
||||
| 步 | 动作 | 验收判据 |
|
||||
|---|---|---|
|
||||
| 1 | 按本项目的页面类型挑候选（工具型数据密集界面 ⇒ 认 `data-dense, enterprise` 这类描述） | 已列出 2~3 个候选套名 |
|
||||
| 2 | 读候选套 `DESIGN.md` 第 1 章 `Visual Theme & Atmosphere`，认准写明该类的那一句 | 选定一个套名，理由写进会话声明 |
|
||||
| 3 | 选定后读三件：`DESIGN.md`（调性 / 色值 / 字号刻度 / 间距刻度 / 动效基调）→ `tokens.css`（圆角与阴影只有这里）→ `components.html`（组件实际长相） | 三件读过，数值来源可指认 |
|
||||
| 4 | 没找到匹配的套 ⇒ 换一个类型词再挑一次；仍不行就直说「未找到匹配」 | 不许把泛化结果当结论落盘 |
|
||||
|
||||
> ⚠️ 153 套分两代模板（A 组 / B 组章节名不同），按自己那套的章节读，不必统一。
|
||||
> ⚠️ 工具型页面的版式不在可选档的模板里（可选档是营销页向；骨架名单与理由见 `references/layouts-tooling.md` 开头）。工具型版式由 D0 的 `结构骨架` 决定，不从模板抄。
|
||||
|
||||
产出令牌表：风格名、来源（选定套名 ＋ 套的章节）、浅深色色值、字体（标题字体是关键项）、间距两档（主刻度 `4/8/16/24/32/64` 供布局，控件层微网格 `2/4/6/8/12` 仅供按钮内衬、徽章内衬、图标间隙、开关与进度轨微几何）、圆角（按组件类各一个值）、字阶定值表（七档各一个 px，不是区间）、高度层级（每层都有多层叠层值）、布局脚手架（骨架档落到具体列宽 ＋ 窄屏变化）、组件规格（按钮三档 ＋ 卡片两档 ＋ 输入框 ＋ 徽章的具体高度 / 内衬 / 字号）、动效基调。全部为具体值，禁止「待定」；每档只许一个定值。
|
||||
|
||||
> 数值判据来自 `craft`：`typography.md`（刻度）、`typography-hierarchy.md`（层级行为）、`color.md`（配额与对比度，正文 4.5:1 / 大字 3:1 / UI 组件 3:1）。这三条定「怎么定」，选定套的 `tokens.css` 定「定成多少」。（⚠️ 对比度这三个数值只在本行登记一次，③段别处提到一律引本行，⛔ 不复述。）
|
||||
|
||||
> 字阶必须是定值表，不是区间。实测病灶：令牌表写「标签 12–13px」，代码落到 12.5px —— 既不在刻度上，又与正文档（14px）只差 1.5px，两档合计承载 68% 文字却拉不开层次。相邻档差 ≥2px，且每一档要承载 ≥40% 文字节点，否则等于没有分档。
|
||||
> 间距为什么要有第二档：实测某页 55% 的 padding 落在 `3/5/9px`，全是按钮内衬与徽章内衬；只有一套主刻度时，例外会变成主路径。微网格取偶数，`3px` / `5px` 等于没有网格。
|
||||
|
||||
> 组件规格是「草稿感」的分水岭。同一屏里按钮高度不一、内衬不一、字号不一，观感立刻散。分档靠填充色 ＋ 高度，不靠字号；同一父区块内主档 ≤1 个（多步流程每步 ≤1 个）；实底按钮底色至少 2 种（全是同一个实底色，等于没有分档）；卡片内衬只许两档（密卡 / 宽松卡），同层级卡片圆角与内衬必须同值。
|
||||
|
||||
### 2.3 落盘 `docs/pm/<项目>/DESIGN.md`
|
||||
|
||||
令牌表内容并入本项目既有的三层 token 结构：`primitive → semantic → component`。组件层只引语义层，语义层只引 primitive，无孤立 token。设计契约作首节。
|
||||
|
||||
`DESIGN.md` 是原型的绑定规范，原型只许引用它的 token。放项目目录、不放仓库根。
|
||||
|
||||
### 2.4 Gate-1 方向门（硬闸，任何挡位不可跳）
|
||||
|
||||
按 `SKILL.md` 的 Gate-1 自检表逐项自检，并把结果写在 `DESIGN.md` 末尾：
|
||||
|
||||
| # | 检查项 | 通过条件 |
|
||||
|---|---|---|
|
||||
| 1 | 设计契约 | 十二个字段全部填写，无一为空或「待定」；有重复项时「重复项的信息量」逐条列出次级信息；交互清单四列齐全，且表外的可点元素为 0 |
|
||||
| 1b | 页型判定（本项目附加，2026-10-05 新增） | 已写出「营销页 / 工具型页面 ＋ 依据」；工具型页面的 D0 里零 `.eyebrow` / 零 `.lead` / 零 `.hero` |
|
||||
| 2 | 结构骨架（翻译面，2026-10-06 口径调整） | 骨架档 / 板块落位 / 密度目标三者已写；板块 ≥2 个且每个有文字标题；板块清单来自②段、逐条对得上、未新增；②段分档表的每条信息都有落位 |
|
||||
| 2b | 骨架未漂（本项目附加，2026-10-06 新增） | D0 的页面清单与每页板块与②段《界面布局》逐条对得上；本段未增删移动任何板块 |
|
||||
| 3 | 状态覆盖 | 六个状态逐项有结论（勾选，或「不适用 ＋ 理由」） |
|
||||
| 4 | 令牌表 | 色值 / 字体 / 间距两档且适用面已分开写 / 圆角 / 阴影全为具体值 |
|
||||
| 4b | 字阶定值表 | 七档每档一个 px 定值（不是区间）；相邻档差 ≥2px；每档只许一个定值 |
|
||||
| 4c | 高度层级 | 每层都有多层叠层值；同层级同值 |
|
||||
| 4d | 布局脚手架 | 骨架档已落到具体列宽；窄屏变化写具体 |
|
||||
| 5 | 组件规格 | 按钮三档 + 卡片两档 + 输入框 + 徽章均为具体值；同一父区块内主档 ≤1；实底底色 ≥2 种 |
|
||||
| 6 | 反 slop | 无紫→粉渐变、标题未用禁用字体、强调色已写明允许位置 |
|
||||
| 7 | 拒绝清单 | ≥3 条，且每条可判定 |
|
||||
| 8 | token 引用完整性（本项目附加） | 语义层只引 primitive、组件层只引语义层、无孤立 token |
|
||||
| 9 | 分档兑现（本项目附加，2026-10-06 口径调整） | ②段分档表每条信息的「主屏常驻 / 可点入」在实现里兑现（常驻零点击可见、可点入一次点击可达）；档位未被本段改动（要改回②段） |
|
||||
| 10 | 供给核对（本项目附加） | 三处供给已确认在位；选定套名与 `DESIGN.md` 记录一致；不一致时供给变更清单已获用户确认并写入修订记录 |
|
||||
|
||||
任一项不过 → 停在 3a 补齐，不进 3b。
|
||||
|
||||
> 对比度怎么算：静态按 CSS 变量叠加后的计算值不可靠，须在 D5 渲染阶段按真实像素复测（门槛数值见本手册 §3.4 的数值判据段，判据出自 `craft/color.md`）。
|
||||
> 不许拿 `npx @google/design.md lint` 当关卡（本机实测完全不可用：alpha ＋ clack 交互库，非 TTY 管道下静默且 exit 0，见 `SKILL.md`）。也不要因它无输出就认为通过。
|
||||
|
||||
---
|
||||
|
||||
## 3. 3b 原型（D2 构建）
|
||||
|
||||
### 3.1 读谁、照什么走
|
||||
|
||||
读 `assets/open-design/design-templates/web-prototype/SKILL.md`，按它「先选定一个明确的美学方向（允许极端，但必须自洽）再写码」的路线构建。方向定死在 `DESIGN.md` 的令牌表里，不许边写边调样式（铁律 1）。
|
||||
|
||||
### 3.2 工作形态 vs 交付形态（本项目已知偏离，每次都要声明）
|
||||
|
||||
- `web-prototype` 的默认产出是单文件 HTML、自包含、双击可开。这也是交付形态，最终必须满足
|
||||
- 本项目的原型用 React + Babel 多文件开发（`index.html` ＋ 若干 `.jsx`），经 HTTP 服务预览（`file://` 下 Babel 取不到外部 `.jsx`，会静默失败）
|
||||
- 编排：开发期按多文件走 ＋ HTTP 预览，3b 收尾时内联成单文件交付
|
||||
- 无宿主工具可代劳，内联必须手工做：把 React / ReactDOM / Babel 用本仓本地副本内联（保离线），把每个 `<script type="text/babel" src="…">` 换成内联 `<script type="text/babel" data-presets="react">`，并去掉所有 unpkg CDN 引用。这是一处持续偏离，每次都要声明。
|
||||
|
||||
内联后必须自检三条：无 `unpkg` 残留、无 `src="v2/`（外部 jsx 引用）残留、根部挂载点仍在。任一不满足即构建失败。
|
||||
|
||||
### 3.3 输出红线（命中即返工）
|
||||
|
||||
来源：数值判据取 `craft/`（`typography.md` ＋ `color.md` ＋ `accessibility-baseline.md`），反 AI 味取 `craft/anti-ai-slop.md`，版式自查取 `web-prototype/references/checklist.md`。下列判据不在 craft 里重复抄写，只写本项目追加的那几条。
|
||||
|
||||
- 间距只用令牌表登记的刻度值；确需中间值（如紧凑表格行高）在令牌表登记，不许临时拍。刻度外值混用是「廉价感」的主要来源（判据见 `craft/typography.md`）
|
||||
- 数字列用 `font-variant-numeric: tabular-nums`（否则刷新时宽度跳动，表格跟着抖）
|
||||
- 禁单层死黑重阴影，用多层叠层 ＋ 1px 半透明边框。层级按内容需要，不设人为上限；判的是「同层级是否同值」，不是「层级总数是否超标」
|
||||
- 强调色全屏面积 ≤5%（判据见 `craft/color.md`）；状态色只用红绿黄三系，不做装饰
|
||||
- 标题禁用 Inter / Roboto / Arial / `system-ui`（正文可用）；中文字重别超 600（`craft/typography.md`）
|
||||
- ⭐ 结构四条（本项目追加，craft 无对应）：① 区块 ≥2 个且每个有文字标题（图标 / 徽章 / 分组容器不替代标题），标题不跳级；② 实际在用字号档 4–6 档且相邻档差 ≥2px，正文档落在 14–16；③ 块间距 ≥ 块内间距的 2 倍；④ 按钮有主次分档且同屏主档 ≤1（多步流程每步 ≤1），分档靠填充色 ＋ 高度
|
||||
- 反 AI 味逐条过 → `craft/anti-ai-slop.md`。⚠️ 「卡片墙」判的是「同一圆角 ＋ 同一阴影 ＋ 所有模块视觉权重完全相同」的等权卡片墙，不是「用了卡片」。有主次、有分组、层级不同的卡片是合法结构手段，别把卡片当禁区整片封掉
|
||||
- 状态穷举六项 → `craft/state-coverage.md`（loading / empty / error / success / disabled / 无权限，逐项判据在那份）
|
||||
- 布局 Grid 管栅格、Flex 管行内对齐；移动优先，断点 `<640` / `640–1024` / `>1024`
|
||||
- 防溢出三件套：grid 写 `minmax(0,1fr)`（不是 `1fr`）、flex 子项加 `min-width:0`、表格 / 代码块外层 `overflow-x:auto`
|
||||
- 交互态齐全：`hover` / `active` / `focus-visible` 三态都要写，焦点环不许被 `outline:none` 抹掉（`craft/accessibility-baseline.md`）
|
||||
- 规范 HTML：非空元素显式闭合、属性双引号
|
||||
- 文件名要有描述性；集中放 `designs/<项目>/`，不散落仓库根
|
||||
|
||||
### 3.4 本项目附加纪律（`open-design` 未涉及）
|
||||
|
||||
- 🔴 与 §供给·方法主线（**基础层**）的口径：本项目只许在它之上**收严 / 具体化**，⛔ 不许放宽或推翻（2026-10-08 用户定案「oil 是基础，在这个基础上可以叠加其他设计规范」）。当前收严项登记如下 ——
|
||||
1、强调色占屏面积：本项目比基础层更严。
|
||||
⚠️ 反过来：想把本项目的某项**放宽**到基础层之上（例如允许更多字号档、更多同屏动效），那不算叠加 —— ⛔ 不行，得先回基础层改。
|
||||
- 重大改版必须复制副本再改（`X.html` → `X v2.html`），不许覆盖旧版。旧版留在磁盘上以便对比（版本管理主线需要可追溯）
|
||||
- 原型里的状态由路由 ＋ 演示开关驱动，不是 `?state=` URL 参数；实测时按这个来
|
||||
|
||||
### 3.5 实测硬关卡（未过不得进 3c）
|
||||
|
||||
用 `browser-harness` skill，以 D0 契约的「交互清单」为唯一清单逐个真点：每行按「触发 → 反馈」实跑；空 / 加载 / 错误 / 失败重试四态都要走到；回报控制台报错原文与「点了没反应」的元素清单。
|
||||
|
||||
- ⛔ 本步是唯一的可点通过道。不许因「没有自动机检」就跳过或降级；实测不过就不许进 3c
|
||||
- 实测一律走 `browser-harness`（浏览器入口 9333），禁用 Trae 自带浏览器工具
|
||||
- React 受控输入用 `fill_input(selector, text)` 填，不要用 `type_text()`（后者绕过框架监听器，提交按钮会一直是禁用态）
|
||||
- 测前禁缓存（`Network.setCacheDisabled`），否则会读旧 `.jsx`
|
||||
- 顺序也是关卡：3a 未过 Gate-1 不进 3b；未跑实测不得进 3c
|
||||
|
||||
---
|
||||
|
||||
## 4. 3c GPT 参考版（必做，顺序在 3d 之前）
|
||||
|
||||
触发点：3b 原型初稿和实测都过了，立刻做。步骤、提问模板、四列对照表、输入边界、异常情况见 `SKILL.md` §3c，不在此重复。
|
||||
|
||||
为什么必须有这一步：3a / 3b 全是本地确定性检查，没有外部视角；让外部模型**独立出一版**，给的是「别人会怎么做」的参照物，这一步补的正是自己看不见的那块。
|
||||
|
||||
三道不可松的口子：① **不传我们的原型 HTML**（传了就是让它改编我们的稿，拿不到独立版本）—— 只内联②段需求与 `DESIGN.md` 的定调 / 令牌；② 等回答出完再取原文，不许读一半；③ 贴文本前脱敏（密钥、真实数据、内网地址换占位符）。
|
||||
|
||||
取不到时：不许假装跑过。落盘写明「本轮未取得参考版」，并在段末明示 —— 未取得不等于已通过。
|
||||
|
||||
处置：参考版不是命令，是参照物。采纳要给理由；与 `DESIGN.md`、②段或基础层（`oil-ui-pro`）冲突的，写清为什么不采纳。采纳项在 3d 之前改完，并回到 3b 的实测清单把这些改动再点一遍。
|
||||
|
||||
---
|
||||
|
||||
## 5. 3d 审查与打磨（D3 收口 + D4 动效 + D5 终检 + Gate-2/3）
|
||||
|
||||
### 5.1 D3 收口（管"写得对不对"）
|
||||
|
||||
对照 `assets/open-design/design-templates/web-prototype/references/checklist.md` + `assets/open-design/craft/typography.md` / `typography-hierarchy.md` / `color.md` / `accessibility-baseline.md` 逐条过。
|
||||
|
||||
> 🔴 本步一律人工过（2026-10-02 用户定案：不重要的相关内容一律删，不建替代脚本）。判据有三处来源，不许跳过任一处：
|
||||
> ① `SKILL.md` 的 Gate-1 自检表 ｜ ② `craft/` 四份规约 ｜ ③ 下列本项目追加判据。
|
||||
|
||||
本项目追加判据（craft 无对应，必须留在这里）：
|
||||
|
||||
- 结构四条：① 区块 ≥2 个且每个有文字标题，标题不跳级 ｜ ② 实际在用字号档 4–6 档、相邻档差 ≥2px、正文档落在 14–16 ｜ ③ 块间距 ≥ 块内间距的 2 倍 ｜ ④ 按钮有主次分档且同屏主档 ≤1
|
||||
- ⭐ 工具型页面五条（本项目追加，2026-10-05）：标题区零从属小字 ｜ 导航带标签 ｜ 并列卡有主次 ｜ 分组不靠边框 ｜ 无假控件。逐条判据与机械核对法在 `references/layouts-tooling.md` §5.5，不在此重复展开
|
||||
⚠️ 其中「标题区零从属小字」与 `web-prototype/references/checklist.md` 的 `P0-A` 是同一判据的两处落点：checklist 管「怎么写」，本节管「怎么量」，口径一致，判据正文只在 `layouts-tooling.md` §5.5.1
|
||||
- 间距只用令牌表登记的刻度值，确需中间值先登记
|
||||
- 数字列用 `font-variant-numeric: tabular-nums`（否则刷新时宽度跳动）
|
||||
- 禁单层死黑重阴影，用多层叠层；层级按内容需要，判的是「同层级是否同值」，不是「层级总数超标」
|
||||
- 防溢出三件套：grid 写 `minmax(0,1fr)`、flex 子项加 `min-width:0`、表格 / 代码块外层 `overflow-x:auto`
|
||||
- 交互态齐全：`hover` / `active` / `focus-visible` 三态都写，焦点环不许被 `outline:none` 抹掉
|
||||
|
||||
> ⚠️ 判据以「内联后的交付单文件」为准。扫多文件开发目录会出幻影阻断（片段文件里当然找不到 CSS 里才有的规则）。本地曾实测整目录扫出 9 条幻影阻断。
|
||||
|
||||
### 5.2 D4 动效（可跳过）
|
||||
|
||||
按 `craft/animation-discipline.md` 先答动效三问：① 它传达什么信息？② 删掉会丢失什么？③ 是不是为了「看起来高级」？答不出就不加。
|
||||
|
||||
- 工具型页面（仪表盘 / 后台 / 编辑器 / 工作台）⛔ 不做**逐区块**的入场编排（每个区块各套一次淡入上移）；首次进入的**一次**协调出场按 §供给·方法主线 的最简档做，用户一天开几十次的高频页可整段省去。本项目的版本管理界面属工具型；判不准时按工具型处理
|
||||
- 弹簧用 Damping / Response 二参数（Damping 保持 0.8–1.0、Response 0.3–0.4s；低于 0.7 会明显「蹦」）
|
||||
- CSS 无法用真弹簧时用 `cubic-bezier(0.32, 0.72, 0, 1)`；过渡曲线不得用 `linear` / `ease` / `ease-in-out`
|
||||
- 交互过渡禁 `@keyframes animation`（不可中断，反向操作会跳帧），用 `transition` 或 WAAPI
|
||||
- 只动 `transform` / `opacity`，不动 `width` / `height` / `top` / `left`；禁止 `scale(0)` 起手（用 `scale(0.95)` ＋ opacity）
|
||||
- 退出比进入快（进 300ms / 出 200ms）；同屏动效元素 ≤2 个且有 40–80ms 错峰
|
||||
- `prefers-reduced-motion` 必须处理
|
||||
|
||||
### 5.3 D5 终检（管"能不能交"）
|
||||
|
||||
过 `craft/state-coverage.md`（状态穷举）＋ `craft/anti-ai-slop.md`（反 AI 味）＋ `web-prototype/references/checklist.md`（P0/P1）＋ 动效三问 ＋ 交互清单逐行复测，并真渲染一次。
|
||||
|
||||
> 🔴 渲染复测用本机 Chrome 无头截图（2026-10-02 实测可用）：
|
||||
>
|
||||
> ```bash
|
||||
> "/c/Program Files/Google/Chrome/Application/chrome.exe" --headless=new --no-sandbox --disable-gpu \
|
||||
> --hide-scrollbars --window-size=1440,900 --virtual-time-budget=3000 \
|
||||
> --screenshot="<Windows 绝对路径>/P1.png" \
|
||||
> "file:///<原型绝对路径，中文需 URL 编码>#/p/xxx"
|
||||
> ```
|
||||
> ⚠️ 两条坑：`--screenshot` 必须给 Windows 绝对路径（给相对路径会写进 Chrome 安装目录，回来找不到）；中文文件名要 URL 编码。
|
||||
> ⛔ 脚本缺失期间，截图只替代「看得见的」那部分：溢出与响应式破损能看出来，对比度 / 状态可见性 / 点击目标尺寸 / 死按钮判不了，那些仍按 5.1 的人工判据 ＋ 3b 的 `browser-harness` 实测走。
|
||||
> 截图两种形状，用途不许混：
|
||||
>
|
||||
> | 形状 | 尺寸 | 用途 |
|
||||
> |---|---|---|
|
||||
> | 视口帧 | 1440×900 / 390×844 | 对外评审、提交外部评估、交付留档一律用这张 |
|
||||
> | 整页长图 | 视口宽 × 整页高 | 仅自检「整页有没有塌」，不对外 |
|
||||
>
|
||||
> ⚠️ 混用会出事（本项目实测踩过）：把长图当参考图交出去，移动端是 1:7.1 的长条、桌面端 1440×1429，「首屏」这个信息整个丢失。外部评估只能按长条理解布局，「首屏有没有主次」「坐得下几行」根本没被评审到。
|
||||
>
|
||||
> 两个视口都要截（`1440x900` 与 `390x844`），只截桌面端等于没测响应式。
|
||||
>
|
||||
> 结构与排版仍要量（脚本缺失期间靠 DOM 取值人工量）：字号档数与相邻档差 / 正文档承载占比 / 标题大纲 / 按钮高度与实底分档 / 列对齐 / 对齐锚点 / 浮层可见关闭出口唯一。⛔ 不许目测截图下结论，取值结果直接抄进 `3d-审查报告.md` 的结构核对表。
|
||||
>
|
||||
> 本项目是 hash 驱动路由，hash 接在文件名后（`<原型>.html#/p/xxx`）；不接就渲染到空壳视图，截图与数字全是假的。
|
||||
>
|
||||
> 「无法判定」一律按未通过对待（「判不了」≠「没问题」）：浮层类在未打开态必然判不了，必须按 Gate-3 的打开态复测口径，用 `browser-harness`（复用同一页签）逐个打开浮层再数可见关闭出口，与 `Esc` / 点遮罩 / 焦点锁三条一起留痕。
|
||||
|
||||
契约里写了数字的，逐条取值回填（`05` §二 第 11 项，阻断级）
|
||||
|
||||
脚本不认识项目自定义选择器（`.ver-row` 之类），所以契约里的数字 —— 首屏条数、单条行高、承载占比、面积占比、对比度比值 —— 没有任何一道机检会替你核。它们是全篇最像「已经验过」的一类内容。
|
||||
|
||||
- 用 `browser-harness` 或 DOM 取值，按契约声明的视口量（本项目是 `1440×900` 与 `390×844`）；`browser-harness` 必须复用同一个页签（`list_tabs()` → `switch_tab()` → `goto_url()`，不要 `new_tab()`）
|
||||
- 回填的是实测值，不是复述契约值；把「契约值 / 实测值」并排列进 `3d-审查报告.md` 的结构核对表
|
||||
- 不得目测，不得沿用上一版数字
|
||||
- 契约没声明判据的档位（例如本项目窄屏的行高）如实记为证据缺口，不要临时编一个阈值凑上
|
||||
- 反面案例（`DESIGN` §8.10 E-18）：某轮契约写「单个版本行高 ≤96px / 1440×900 首屏 ≥5 行」，是凭印象写的，真渲染才发现是 118px / 3 行，两个数字同时不达标，而当时没有任何门禁会报它
|
||||
|
||||
### 5.4 Gate-2 完成门
|
||||
|
||||
全部 `阻断` 项清零，`建议` 项逐条有结论：修掉，或显式写「已知不修 ＋ 原因」。
|
||||
不接受「基本没问题」「应该差不多」「剩余都是小问题」。每条要么修，要么留痕。
|
||||
|
||||
### 5.5 Gate-3 交付门（硬闸，任何挡位不可跳）
|
||||
|
||||
真实渲染后（浏览器打开，非只看代码）肉眼过八项：裁切 / 重叠 / 失真 / 失效控件 / 缺状态 / 响应式破损 / 控制台报错 / 字体回退异常。
|
||||
|
||||
> 🔴 **2026-10-08 追加两条硬要求 —— 起因是本项目实测事故：五道闸门全绿，界面仍然难看。**
|
||||
>
|
||||
> **① 「看过」必须有落盘记录。** `oil-ui-pro` 的评分闭环（截图 → 评审 → 修改；10 分制、目标 9 分、默认最多三轮）
|
||||
> 的结果要写进 `3d-审查报告.md`。⛔ **不许用「自检脚本 N 项全绿」顶替「看过并满意」** ——
|
||||
> 脚本量的是一致性与完整性（结构漂没漂、控件死没死、语法炸没炸、行数退没退化），**没有一条量「像不像给人用的」**。
|
||||
> 上述那八项肉眼项也全是「有没有坏」，「丑」不在其中。
|
||||
>
|
||||
> **② 人工项必须给机检实现，否则不许打勾。** 凡挂在本门或 §7 完成标准里的判据，要么给出可跑的取值
|
||||
> （脚本 / DOM 取值命令），要么在该条后面写死「**本条无机检**」。
|
||||
> 🔴 **⛔ 不许在没有取值手段的条目上打 ✅** —— 本项目实测：收口清单里「§5.5 五条逐条过完 ✅ 自检机核」
|
||||
> 这一格是**假的**（那五条当时零覆盖），而它正是「全绿却难看」的开关。
|
||||
无头截图已代劳其中的溢出与响应式破损，其余仍需人眼（截图查不出「点了没反应」，那靠 3b 的 `browser-harness` 实测）。
|
||||
|
||||
落盘 `designs/<项目>/3d-审查报告.md`，按 `05` §五的模板：范围 ＋ 挡位 ＋ 阻断项表 ＋ 建议项表 ＋ 状态覆盖核对表 ＋ Gate 结论。
|
||||
|
||||
---
|
||||
|
||||
## 6. 偏离单（本段收尾必须附）
|
||||
|
||||
| # | 原要求（文件:小节） | 实际做法 | 原因 | 影响 | 处置 |
|
||||
|---|---|---|---|---|---|
|
||||
| | | | | | 已修 / 持续偏离 / 待用户裁定 |
|
||||
|
||||
本项目长期挂账的偏离（每次执行都要重新声明状态）：
|
||||
|
||||
| # | 项 | 状态 |
|
||||
|---|---|---|
|
||||
| A1 | `web-prototype` 默认产出单文件 HTML；本项目开发期用 React+Babel 多文件，交付时手工内联成单文件（无宿主工具可代劳：`super_inline_html` / `present_fs_item_for_download` 在 Trae 都不存在） | 持续偏离，3b 收尾做内联并自检三条 |
|
||||
| A2 | 宿主下载 / 预览工具不存在（`SendUserFile` / Claude Preview MCP） | 按 `SKILL.md` 适配注记：改 Write 落盘 ＋ `browser-harness` 实测 |
|
||||
| A3 | 实测必须用 `browser-harness`（浏览器入口 9333），禁用 Trae 自带浏览器工具 | 项目既定约束，优先级高于手册的通用说法 |
|
||||
| A4 | 预览服务端口用 4311（`python -m http.server 4311 --directory designs`） | 与 9333 不冲突：4311 是服务，9333 是自动化浏览器入口 |
|
||||
|
||||
没有偏离单就不得报完成。
|
||||
|
||||
---
|
||||
|
||||
## 7. 完成标准（逐条可核对）
|
||||
|
||||
- [ ] 声明制走完：开工、每个子步、每处偏离都有声明；挡位已声明（快速 / 标准 / 严格）
|
||||
- [ ] 第 1 节必读表已按阶段取用；同一时刻只读 1~2 份，未一次性全读（限载）
|
||||
- [ ] 供给核对做过：三处供给在位、选定套名与 `DESIGN.md` 记录一致；不一致时供给变更清单已获用户确认并写入修订记录
|
||||
- [ ] `docs/pm/<项目>/DESIGN.md` 存在，含设计契约（十二个字段，含结构骨架、交互清单与重复项的信息量）与令牌表（三层 token 结构，含组件规格 ＋ 字阶定值表 ＋ 高度层级 ＋ 布局脚手架（含容器与对齐锚点）＋ 浮层只许一个可见关闭出口，全为具体值）
|
||||
- [ ] 骨架未漂（2026-10-06 口径调整）：D0 的页面清单与每页板块与②段《界面布局》逐条对得上；本段未增删移动任何板块
|
||||
- [ ] 分档已兑现：②段分档表每条信息的「主屏常驻 / 可点入」在实现里兑现；档位未被本段改动
|
||||
- [ ] `结构骨架` 已落：骨架档给了理由；板块 ≥2 个且每个有文字标题；板块清单来自②段；密度目标只取一档
|
||||
- [ ] 页型已判（营销页 / 工具型，给了依据）；工具型页面零 `.eyebrow` / 零 `.lead` / 零 `.hero`，且 `layouts-tooling.md` §5.5 五条逐条过完（含「标题区零从属小字」的 DOM 取值）—— **每条都要附取值记录（DOM 取值输出或截图编号）**；给不出取值的条目改写为「本条无机检」，⛔ 不许打 ✅
|
||||
- [ ] **视觉评分有落盘记录**（`oil-ui-pro` 10 分制、目标 9 分、最多三轮）；未跑就写「未跑视觉评分」并说明原因，⛔ 不许留空、⛔ 不许拿脚本全绿顶替
|
||||
- [ ] **供给能力边界已核对**：自带样式库只到调色板级 ⇒ 几何与版式的来源已写明（源站实测 / 另找 / 明说无来源）；未选可选档时，反 AI 味 / 无障碍 / 动效纪律 / 表单校验四项已记为证据缺口
|
||||
- [ ] Gate-1 全部自检项结果写在 `DESIGN.md` 末尾，无一项不过
|
||||
- [ ] 原型 HTML 单文件自包含、双击可开，内联自检三条通过（无 unpkg / 无外部 jsx 引用 / 挂载点在）
|
||||
- [ ] 状态穷举六项逐条有结论（`05` §三第 1 项）
|
||||
- [ ] 每个按钮、每个跳转都用 `browser-harness` 真点过，含空 / 加载 / 错误 / 失败重试四态，并回报控制台报错原文与「点了没反应」清单
|
||||
- [ ] `designs/<项目>/3c-GPT参考版.md` 存在，含提问原文、参考版原文、四列对照表；未取到已明示
|
||||
- [ ] D3 收口已按 5.1 三处判据人工过完：Gate-1 自检表 ＋ `craft/` 四份规约 ＋ 本项目追加判据，阻断项清零（取值结果已抄进报告）
|
||||
- [ ] D5 终检已真渲染：`1440x900` 与 `390x844` 两个视口各截一张，视口帧已留档；横向溢出 0 / 对比度不达标 0 / 结构与排版阻断 0，且无「无法判定」项（DOM 取值已抄进报告）
|
||||
- [ ] 每个浮层都手工打开数过可见关闭出口（`== 1`）＋ `Esc` / 点遮罩能关、焦点锁在层内且关闭后回到触发按钮；结论与触发路径已写进 `3d-审查报告.md`
|
||||
- [ ] 对外提交 / 交付留档的截图只用视口帧；`_full/` 长图未作为评审输入
|
||||
- [ ] 契约里每个写出来的数字都已实测回填（首屏条数 / 行高 / 承载占比 / 面积占比 / 对比度比值），「契约值 / 实测值」并排列出；未回填即阻断；契约未声明判据的档位已记为证据缺口
|
||||
- [ ] `designs/<项目>/3d-审查报告.md` 存在，含阻断 / 建议两张表 ＋ 状态覆盖核对 ＋ 结构核对（数字抄自脚本输出，非「目测」）＋ Gate-2/3 结论
|
||||
- [ ] Gate-2 与 Gate-3 均已通过（书面结论，非口头）
|
||||
- [ ] 重大改版：旧版文件仍在磁盘上，且收尾给出新旧差异（改了什么 / 为什么 / 代价）
|
||||
- [ ] 偏离单已附，且无静默偏离
|
||||
# ③段执行手册（固化流程）
|
||||
|
||||
`SKILL.md` 写规则，本文件写照着走的顺序与验收。跑③段时按本文件逐步走；任何一步偏离，必须当场声明并记入第 6 节偏离单。
|
||||
|
||||
> 本手册为什么存在：③段 3b 交付了原型，却走了别的主流程、没读依据文件、执行时也没声明，用户直到追问「基于哪个 skill」才知道。所以第一条是声明制，第二条是逐步写明依据哪个文件的哪一节。
|
||||
> ③段的设计工程供给是 `open-design` 技能，按技能名引用，不写死相对路径（技能位置一变就失效且不报错）。流程规则与契约字段留在本手册与 `SKILL.md`。两者分工见第 1 节末的「⛔ 四样必须留在本项目」。
|
||||
|
||||
---
|
||||
|
||||
## 0. 声明制（核心，唯一不可商量的一条）
|
||||
|
||||
开工前先输出一段流程声明，四个字段：
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 当前段与子步 | 例：③段 / 3b 原型（D2 构建） |
|
||||
| 主干与挡位 | 例：供给 `open-design` / 挡位「标准」（或「快速」） |
|
||||
| 依据文件 | 本步照的是哪个文件的哪一节，写精确路径 + 小节号 |
|
||||
| 产出落点 | 本步会写哪个文件 |
|
||||
|
||||
每进一个子步重发一次这四行（子步之间不反问，但必须声明）。
|
||||
|
||||
偏离时当场声明：
|
||||
|
||||
```
|
||||
偏离：<原要求> → <实际做法>；原因：…；影响：…
|
||||
```
|
||||
|
||||
并记入第 6 节。不许静默偏离，不许事后补说。
|
||||
|
||||
---
|
||||
|
||||
## 1. 必须加载的文件（按阶段加载，用完释放）
|
||||
|
||||
> ⚠️ 2026-10-02 已重接必读源。原必读表指向 `ui-page-design/references/02_~05_*.md` 与 `vendor/*`，该目录实测已不在磁盘上（工作区与全局技能根两处都查过），照旧表走 D0 读不到任何一份必读文档。现改为直接引 `open-design` 技能（按技能名引用，不写死相对路径）。
|
||||
> 改动原则：判据类全部交出去，只保留 craft 没有对应的东西。
|
||||
|
||||
开工前必读两个页面设计技能的位置与分工：`open-design/craft/README.md`（读一份就知道有哪些规约、怎么按需取），以及本段 `SKILL.md` 的两技能分工表。
|
||||
|
||||
其余不许一次全读。同一时刻只读 1~2 份，用完释放；`design-systems/` 153 套、`craft/` 13 份全读必然互相稀释。
|
||||
|
||||
> 下文凡出现 `open-design/...` 的路径，一律指本段**随段携带的自带件** `assets/open-design/...`（独立技能、可选择使用）；不选它就按默认主线走（`oil-ui-pro` 方法 ＋ 自带样式库定调 ＋ 本段自家 `execution-runbook.md` 与 `layouts-tooling.md` 判据），craft 独有的那几项明说「本次无供给来源」。
|
||||
|
||||
| 阶段 | 读什么 | 为什么 |
|
||||
|---|---|---|
|
||||
| D0 | 本文件 §2.1（设计契约十二字段） | craft 无对应 —— 字段清单是本项目的东西，只在这里 |
|
||||
| D0 判据 | `craft/state-coverage.md` | 状态六项的逐项判据 |
|
||||
| D0 页型（2026-10-05 新增） | 本文件 §2.1 步 6（先判页型：营销页 / 工具型） | 挑版式骨架之前必须先判。判错页型 = 拿营销骨架做后台，是「标题上下两行小字」的唯一根因 |
|
||||
| D1 | 选定套 `DESIGN.md` + `tokens.css` + `components.html`；可选 `craft/color.md` | 定调来自选套，不来自检索脚本 |
|
||||
| D1 多方向比选（按需） | `oil-ui-pro` 的 `references/design-direction.md` + `references/style-explorer.md` | 要「拉开几个方向让用户挑」时的方向卡与对比页（另一技能，平行取用） |
|
||||
| D2 | `open-design/design-templates/web-prototype/SKILL.md` + 同目录 `references/layouts.md`（营销页）／工具型页面另读两份：本技能 `references/layouts-tooling.md`（HTML 骨架与落地自检）＋ `open-design/design-templates/web-prototype/references/tooling.md`（四形态判定句与通用红线纲要） | 「先选定美学方向再写码」＋ 版式骨架。⭐ 落地页那 8 个骨架不适用于工具型（hero/features/stats/quote/cta/log/pricing），工具型版式只在本项目那份里，不许拿营销页顶替。⚠️ 两份工具型文件是「骨架 vs 纲要」分工，判据不重写（判据正文在 `layouts-tooling.md`） |
|
||||
| D3 | `craft/typography.md` + `typography-hierarchy.md`（+ 按需 `color.md`） | 字阶定值表与层级判据（取代原 `03_视觉与骨架规则.md`） |
|
||||
| D4 | `craft/animation-discipline.md` | 动效三问、弹簧二参数（取代原 `04_动效与手势规则.md`） |
|
||||
| D5 | `design-templates/web-prototype/references/checklist.md` + `craft/anti-ai-slop.md` + `craft/accessibility-baseline.md` | 终检清单、反 AI 味、无障碍底线（取代原 `05_审计门禁与输出格式.md`）。⚠️ 工具型页面必须过 checklist 的 `P0-A 标题区纪律`（2026-10-05 新增，五条） |
|
||||
| D5 独立评审（按需） | `oil-ui-pro` 的 `references/visual-review.md` + `references/tools.md` | 要「没看过制作过程的评审打分」时的协议与截图取证（不替代本段 Gate） |
|
||||
| 每步 | `docs/pm/<项目>/DESIGN.md` | 本项目绑定规范；原型只许引它的 token |
|
||||
|
||||
⛔ 四样东西 craft 没有对应，必须留在本项目（本文件 / `SKILL.md` / `references/layouts-tooling.md` 里）：
|
||||
|
||||
| 留什么 | 为什么 craft 接不住 |
|
||||
|---|---|
|
||||
| 设计契约十二字段 | craft 是通用工艺，不定义字段清单；D0 字段是本项目的产物 |
|
||||
| 结构骨架（骨架档 / 区块划分 / 密度目标） | 实测 grep 全部 craft 只有零散的 layout 提及，无成体系的骨架规则 |
|
||||
| 交互清单（契约第十二字段） | 同上 —— 交互的判据在 craft 里只散见于 `state-coverage` 与表单章，不构成一份逐元素清单 |
|
||||
| 工具型版式库（行式列表 / 表格式清单 / 详情面板 / 主从侧区） | `web-prototype/references/layouts.md` 的 8 个骨架是落地页／营销页向；craft 里零散提及不成体系。工具型数据密集界面的版式无任何现成来源 ⇒ 本项目自建 `references/layouts-tooling.md` |
|
||||
|
||||
定调来源唯一：从 `open-design/design-systems/` 选一套（153 套），按候选套 `DESIGN.md` 第 1 章 `Visual Theme & Atmosphere` 认准类型词。
|
||||
本 skill 的 `references/` 只放流程规则（契约字段 ＋ 执行顺序 ＋ 门禁），不放任何风格底子。既有项目 `DESIGN.md` 里凡引用旧风格来源（`ui-ux-pro-max` / `minimalist-ui` / 皮肤族）的行，重跑 3a 时一律改写为「选定套名 ＋ 留痕对照」。
|
||||
|
||||
已整体移除的 vendor，不必再找：`ui-ux-pro-max`（被 153 套设计系统取代）、`frontend-design`（D1 已改选设计系统）、`apple-design`（动效已由 `craft/animation-discipline.md` 覆盖）、`anti-ui-slop`（按本项目收录标准「依赖外部服务」整体移除，判据由 `craft/anti-ai-slop.md` 接管）、`web-design-guidelines`。
|
||||
⚠️ 判据一旦落进本项目的条款，就不再依赖原出处的存续。上面五份的可执行内容已在 `SKILL.md` 铁律、`craft/` 与本文件里，删掉原出处不影响执行。
|
||||
|
||||
---
|
||||
|
||||
## 2. 3a 视觉规范（D0 锚需求 + D1 定调 + Gate-1）
|
||||
|
||||
### 2.0 供给核对（步 −1，每轮必做）
|
||||
|
||||
`open-design` 是外部供给，会被上游更新，而本项目的 `DESIGN.md` 是上一次供给状态下产出的。不核对就长期拿旧调性当准绳：换套后门禁判不过，却不知道哪条变了。
|
||||
|
||||
| 步 | 动作 | 验收判据 |
|
||||
|---|---|---|
|
||||
| −1 | 确认三处供给仍在位：`design-systems/`（并记录本项目选定套名）、`craft/`、`design-templates/web-prototype/` 都存在 | 三处都在位；`DESIGN.md` 记录的上次套名已找到 |
|
||||
| −1b | 套名一致 → 直接进 D0 | 开工声明里写一句「选定套 `<套名>`，与项目记录一致」 |
|
||||
| −1c | 套名不一致或供给缺失 → 停下报告，不许拿别的套顶上，也不许凭记忆写风格 | 产出供给变更清单（逐条：变了什么 → 本项目现状 → 要改什么），在会话里呈现并获用户确认后才改 `DESIGN.md` |
|
||||
|
||||
> 不要静默跳过：一致也要在开工声明里写一句套名；不一致必须停下，这是硬闸。
|
||||
|
||||
### 2.1 D0 锚需求 → 设计契约
|
||||
|
||||
> ⭐⭐ 口径（2026-10-06 用户定案）：骨架归②段，本段做皮肉。
|
||||
> 两侧完整对照只在②段 `SKILL.md` 的 §②—③ 交接口 定义一次（本手册不重复那张表，理由与用户原话见那一节）。
|
||||
> ②段《界面布局》里的页面清单、每页板块、板块排列、跨页关系就是骨架定稿。本段不许增删移动板块，要改回②段改。本段在给定骨架内决定视觉与交互实现。
|
||||
> 理由（用户原话）：「页面关系和布局必须在第二步确认清楚，不然第三步没有方向 一会一个样子」。
|
||||
> ⛔ 仍归本段的：配色 / 字体 / 间距 / 组件样式 / 动效 / 板块内的排版与交互行为 / 响应式。
|
||||
|
||||
读②段时取四样：骨架（页面清单 ＋ 每页板块 ＋ 排列 ＋ 跨页关系）、必须在界面上发生什么、红线、禁用条件与状态流转。
|
||||
骨架是冻结输入，其余三样是功能约束。
|
||||
|
||||
按本节清单产出设计契约，十二个字段：页面职责（「让<谁>在<多久>内<完成什么>」）、主用户、主操作（全页唯一，写了两个就该拆页）、必要内容（核对面）、重复项的信息量（行式列表 / 卡片网格时逐条列出：每个重复项除「主标识 ＋ 动作」外必须带 ≥1 条次级信息）、结构骨架（翻译面：把②段板块清单翻成骨架档 ＋ 列宽 ＋ 密度目标）、交互清单（2026-10-02 新增：逐个可点元素一行，四列「元素 / 触发 / 反馈 / 何时不可点」；动效参数归 3d、视觉样式归令牌表、「这个状态有没有」归下一字段状态覆盖）、状态覆盖六项逐条、组件来源（优先沿用既有）、响应式行为（写布局怎么变，不写「自适应」）、明确拒绝的模式（≥3 条可判定）、验收标准（可观察可判定）。
|
||||
|
||||
两个字段的分工（2026-10-06 调整）：`必要内容` 是核对面，`结构骨架` 是翻译面。
|
||||
|
||||
> `结构骨架`（翻译面）怎么落（规则留在本手册，craft 无对应：实测 `craft/` 只有零散 layout 提及，不构成骨架规则）：
|
||||
> ⭐ 输入是②段的板块清单，本字段做的是翻译，不是发明。
|
||||
> ① 骨架档：单列 / 主区＋侧区 / 主区＋侧区＋辅助区，选一档并写清理由。有 ≥3 个并列目的地且宽屏 ≥1024 时优先侧栏，但侧栏是项目级取舍，不许写死成「必须没有」。
|
||||
> ② 板块落位：把②段给的板块按顺序放进骨架档，每块给一个文字标题（页面 ≥2 个带文字标题的板块）。
|
||||
> ③ 密度目标：宽松（24–96）/ 标准（16–64）/ 密集（8–32），同一页面不得混用两档。
|
||||
> ⛔ 不许在②段板块清单之外加块，缺板块回②段改。
|
||||
> 板块先分、内容后放，顺序反了就只能得到一张平铺的长条。
|
||||
|
||||
> `必要内容`（核对面）的判据不变，但用途变了。
|
||||
> 判定标准仍是模板里那句「只留缺了就做不成事的」。
|
||||
> 逐条问：这条内容删掉，主操作还做得成吗？做得成，它就不该主屏常驻（②段分档表已定档位）。
|
||||
> ⚠️ 本段不得以 `必要内容` 为由增删②段已定的信息档位。档位归②段，本段只做落位核对。
|
||||
> 本段该做的是：核对②段的「主屏常驻 / 可点入」分档，在本段自己的视觉与交互实现里兑现它（常驻的零点击可见、可点入的一次点击可达）。
|
||||
> 危险信号：`必要内容` 与②段分档表逐条对不上（条数差很多、档位被改）→ 停下来说明，不自行改档。
|
||||
> 反面样例（本项目真实踩过）：版本列表的 `必要内容` 只该有「`vN` ＋ 语义名 ＋ `第 N/5 步` ＋ 状态徽章 ＋ 时间戳 ＋ 行尾当前动作」，实际却把每行那句解释性长文案（「目录建好了，还没有登记原始需求。」）也当成必备内容渲染上去，于是每行多出一整句、页面变成信息墙。
|
||||
|
||||
| 步 | 动作 | 验收判据 |
|
||||
|---|---|---|
|
||||
| 0 | 读②段《界面布局》，把骨架当冻结输入取走 | 页面清单与每页板块逐条抄进契约，未增删移动 |
|
||||
| 1 | 产出设计契约 | 十二个字段全填，无空、无「待定」；有重复项时「重复项的信息量」已逐条列出次级信息；交互清单覆盖页面上每一个可点元素 |
|
||||
| 2 | 状态覆盖逐项给结论 | 六项要么勾选，要么写「不适用 ＋ 理由」 |
|
||||
| 3 | 核对②段分档表：每条信息的「主屏常驻 / 可点入」 | 与②段分档表逐条对得上；档位未被本段改动（要改回②段） |
|
||||
| 4 | 落 `结构骨架`：把②段板块清单翻成骨架档 ＋ 列宽 ＋ 密度目标 | 骨架档给了理由；板块 ≥2 个且每个有文字标题；板块清单来自②段、未新增；密度目标只取一档 |
|
||||
| 5 | 自检块间距 ≥ 块内间距的 2 倍 | 块间 32/64、块内 8/12/16，比值 ≥2（写进令牌表） |
|
||||
| 6 | 判页型（2026-10-05 新增，D2 之前必做）：写一句「本页是营销页还是工具型页面，依据是什么」 | 结论明确且给了依据。判不出来不许进 D2，停下来回改 `结构骨架` |
|
||||
|
||||
> ⭐⭐ 步 6「判页型」是 2026-10-05 新增，补的是一处从未有过落点的缺口。
|
||||
> 病灶实测：本项目原型长出「标题上方一行小字眉标 → 大标题 → 下方一行灰色副标题」的三段式。
|
||||
> 根因不在③段执行：`open-design` 的种子 `assets/template.html` 是营销落地页骨架，CSS 里自带 `.eyebrow`（眉标）与 `.lead`（副标题），`layouts.md` 的 8 个骨架里有 6 个在用，而当时的 checklist 甚至明令保留（「Lead text under 56 ch … don't override」）。
|
||||
> 于是照种子做 = 结构全绿 ＋ 排版难看：判据判的是「类名合法」，判不出「这不是工具界面的排版」。页型不判，后面用什么设计系统、怎么打磨都救不回来。
|
||||
>
|
||||
> 两个页型的目的不同，骨架因此不能通用：
|
||||
> - 营销页（落地页 / 首页 / 定价页）：目的是说服，走「主张 → 论据 → CTA」，可用 hero / eyebrow / lead。
|
||||
> - 工具型页面（后台 / 控制台 / 列表 / 详情 / 看板 / 表单）：目的是完成一件工作，走「数据 ＋ 操作」，零 `.eyebrow`、零 `.lead`、零 `.hero`（三者已在种子中删除或降级为 `body.is-marketing` 专用）。
|
||||
>
|
||||
> 判别口径：页面要用户「下决心去做某事」是营销页；要用户「把这件事做完」是工具型页面。
|
||||
> ⚠️ 判不准时按工具型处理（默认取严）。
|
||||
|
||||
### 2.2 D1 定调 → 令牌表
|
||||
|
||||
> 🔴 **D1 读什么（2026-10-08 补 · 本节的硬前置）** —— 定调要取**三样**，⛔ 只取数值不算取用选定套：
|
||||
>
|
||||
> 1. **数值**：选定套的 `tokens.css`（色值／圆角／间距／按钮／卡片／输入框）。
|
||||
> 2. **版式结构**：选定套里记「外壳怎么分（侧栏／顶栏／主区）」「内容区用列表还是卡片网格」的那份。
|
||||
> 3. **组件族**：选定套里列组件族与样张的那份。
|
||||
>
|
||||
> ⛔ **文件名随档而异，按该套目录里实际有的读**：本包默认档那套（`assets/design-systems/design-system-tiaoyue/`）
|
||||
> 给组件的是 `references/components.md`（组件族）＋ `references/design-system.html`（样张），
|
||||
> 它**没有** `components.html` —— 那是**可选档 153 套**的命名。
|
||||
> 🔴 2026-10-08 实测事故：D1 步骤原写 `components.html` ⇒ 在默认档里**按名字找不到** ⇒ 那一次只取到了
|
||||
> 色值与圆角，**版式结构与组件族整层漏掉** ⇒ 做出的界面「用了它的样式、没有它的排版」。
|
||||
> ⇒ 判据：`DESIGN.md` §2.5 组件规格**每一行都要写出处**（取自哪个族／哪个结构），⛔ 只写数值不写出处即判**未取用**。
|
||||
|
||||
从 `assets/open-design/design-systems/`（153 套）选一套，不凭感觉编、不全读：
|
||||
|
||||
| 步 | 动作 | 验收判据 |
|
||||
|---|---|---|
|
||||
| 1 | 按本项目的页面类型挑候选（工具型数据密集界面 ⇒ 认 `data-dense, enterprise` 这类描述） | 已列出 2~3 个候选套名 |
|
||||
| 2 | 读候选套 `DESIGN.md` 第 1 章 `Visual Theme & Atmosphere`，认准写明该类的那一句 | 选定一个套名，理由写进会话声明 |
|
||||
| 3 | 选定后读三件：`DESIGN.md`（调性 / 色值 / 字号刻度 / 间距刻度 / 动效基调）→ `tokens.css`（圆角与阴影只有这里）→ `components.html`（组件实际长相） | 三件读过，数值来源可指认 |
|
||||
| 4 | 没找到匹配的套 ⇒ 换一个类型词再挑一次；仍不行就直说「未找到匹配」 | 不许把泛化结果当结论落盘 |
|
||||
|
||||
> ⚠️ 153 套分两代模板（A 组 / B 组章节名不同），按自己那套的章节读，不必统一。
|
||||
> ⚠️ 工具型页面的版式不在模板里：`web-prototype/references/layouts.md` 那 8 个骨架是落地页 / 营销页向，工具型页面只适用 Layout 7 日志列表与 Layout 8 对比表；其余套上去会把后台做成营销页。工具型版式由 D0 的 `结构骨架` 决定，不从模板抄。
|
||||
|
||||
产出令牌表：风格名、来源（选定套名 ＋ 套的章节）、浅深色色值、字体（标题字体是关键项）、间距两档（主刻度 `4/8/16/24/32/64` 供布局，控件层微网格 `2/4/6/8/12` 仅供按钮内衬、徽章内衬、图标间隙、开关与进度轨微几何）、圆角（按组件类各一个值）、字阶定值表（七档各一个 px，不是区间）、高度层级（每层都有多层叠层值）、布局脚手架（骨架档落到具体列宽 ＋ 窄屏变化）、组件规格（按钮三档 ＋ 卡片两档 ＋ 输入框 ＋ 徽章的具体高度 / 内衬 / 字号）、动效基调。全部为具体值，禁止「待定」；每档只许一个定值。
|
||||
|
||||
> 数值判据来自 `craft`：`typography.md`（刻度）、`typography-hierarchy.md`（层级行为）、`color.md`（配额与对比度，正文 4.5:1 / 大字 3:1 / UI 组件 3:1）。这三条定「怎么定」，选定套的 `tokens.css` 定「定成多少」。
|
||||
|
||||
> 字阶必须是定值表，不是区间。实测病灶：令牌表写「标签 12–13px」，代码落到 12.5px —— 既不在刻度上，又与正文档（14px）只差 1.5px，两档合计承载 68% 文字却拉不开层次。相邻档差 ≥2px，且每一档要承载 ≥40% 文字节点，否则等于没有分档。
|
||||
> 间距为什么要有第二档：实测某页 55% 的 padding 落在 `3/5/9px`，全是按钮内衬与徽章内衬；只有一套主刻度时，例外会变成主路径。微网格取偶数，`3px` / `5px` 等于没有网格。
|
||||
|
||||
> 组件规格是「草稿感」的分水岭。同一屏里按钮高度不一、内衬不一、字号不一，观感立刻散。分档靠填充色 ＋ 高度，不靠字号；同一父区块内主档 ≤1 个（多步流程每步 ≤1 个）；实底按钮底色至少 2 种（全是同一个实底色，等于没有分档）；卡片内衬只许两档（密卡 / 宽松卡），同层级卡片圆角与内衬必须同值。
|
||||
|
||||
### 2.3 落盘 `docs/pm/<项目>/DESIGN.md`
|
||||
|
||||
令牌表内容并入本项目既有的三层 token 结构：`primitive → semantic → component`。组件层只引语义层，语义层只引 primitive，无孤立 token。设计契约作首节。
|
||||
|
||||
`DESIGN.md` 是原型的绑定规范，原型只许引用它的 token。放项目目录、不放仓库根。
|
||||
|
||||
### 2.4 Gate-1 方向门（硬闸，任何挡位不可跳）
|
||||
|
||||
按 `SKILL.md` 的 Gate-1 自检表逐项自检，并把结果写在 `DESIGN.md` 末尾：
|
||||
|
||||
| # | 检查项 | 通过条件 |
|
||||
|---|---|---|
|
||||
| 1 | 设计契约 | 十二个字段全部填写，无一为空或「待定」；有重复项时「重复项的信息量」逐条列出次级信息；交互清单四列齐全，且表外的可点元素为 0 |
|
||||
| 1b | 页型判定（本项目附加，2026-10-05 新增） | 已写出「营销页 / 工具型页面 ＋ 依据」；工具型页面的 D0 里零 `.eyebrow` / 零 `.lead` / 零 `.hero` |
|
||||
| 2 | 结构骨架（翻译面，2026-10-06 口径调整） | 骨架档 / 板块落位 / 密度目标三者已写；板块 ≥2 个且每个有文字标题；板块清单来自②段、逐条对得上、未新增；②段分档表的每条信息都有落位 |
|
||||
| 2b | 骨架未漂（本项目附加，2026-10-06 新增） | D0 的页面清单与每页板块与②段《界面布局》逐条对得上；本段未增删移动任何板块 |
|
||||
| 3 | 状态覆盖 | 六个状态逐项有结论（勾选，或「不适用 ＋ 理由」） |
|
||||
| 4 | 令牌表 | 色值 / 字体 / 间距两档且适用面已分开写 / 圆角 / 阴影全为具体值 |
|
||||
| 4b | 字阶定值表 | 七档每档一个 px 定值（不是区间）；相邻档差 ≥2px；每档只许一个定值 |
|
||||
| 4c | 高度层级 | 每层都有多层叠层值；同层级同值 |
|
||||
| 4d | 布局脚手架 | 骨架档已落到具体列宽；窄屏变化写具体 |
|
||||
| 5 | 组件规格 | 按钮三档 + 卡片两档 + 输入框 + 徽章均为具体值；同一父区块内主档 ≤1；实底底色 ≥2 种 |
|
||||
| 6 | 反 slop | 无紫→粉渐变、标题未用禁用字体、强调色已写明允许位置 |
|
||||
| 7 | 拒绝清单 | ≥3 条，且每条可判定 |
|
||||
| 8 | token 引用完整性（本项目附加） | 语义层只引 primitive、组件层只引语义层、无孤立 token |
|
||||
| 9 | 分档兑现（本项目附加，2026-10-06 口径调整） | ②段分档表每条信息的「主屏常驻 / 可点入」在实现里兑现（常驻零点击可见、可点入一次点击可达）；档位未被本段改动（要改回②段） |
|
||||
| 10 | 供给核对（本项目附加） | 三处供给已确认在位；选定套名与 `DESIGN.md` 记录一致；不一致时供给变更清单已获用户确认并写入修订记录 |
|
||||
|
||||
任一项不过 → 停在 3a 补齐，不进 3b。
|
||||
|
||||
> 对比度怎么算：静态按 CSS 变量叠加后的计算值不可靠，须在 D5 渲染阶段按真实像素复测（判据见 `craft/color.md`：正文 4.5:1 / 大字 3:1 / UI 组件 3:1）。
|
||||
> 不许拿 `npx @google/design.md lint` 当关卡（本机实测完全不可用：alpha ＋ clack 交互库，非 TTY 管道下静默且 exit 0，见 `SKILL.md`）。也不要因它无输出就认为通过。
|
||||
|
||||
---
|
||||
|
||||
## 3. 3b 原型（D2 构建）
|
||||
|
||||
### 3.1 读谁、照什么走
|
||||
|
||||
读 `open-design/design-templates/web-prototype/SKILL.md`，按它「先选定一个明确的美学方向（允许极端，但必须自洽）再写码」的路线构建。方向定死在 `DESIGN.md` 的令牌表里，不许边写边调样式（铁律 1）。
|
||||
|
||||
### 3.2 工作形态 vs 交付形态（本项目已知偏离，每次都要声明）
|
||||
|
||||
- `web-prototype` 的默认产出是单文件 HTML、自包含、双击可开。这也是交付形态，最终必须满足
|
||||
- 本项目的原型用 React + Babel 多文件开发（`index.html` ＋ 若干 `.jsx`），经 HTTP 服务预览（`file://` 下 Babel 取不到外部 `.jsx`，会静默失败）
|
||||
- 编排：开发期按多文件走 ＋ HTTP 预览，3b 收尾时内联成单文件交付
|
||||
- 无宿主工具可代劳，内联必须手工做：把 React / ReactDOM / Babel 用本仓本地副本内联（保离线），把每个 `<script type="text/babel" src="…">` 换成内联 `<script type="text/babel" data-presets="react">`，并去掉所有 unpkg CDN 引用。这是一处持续偏离，每次都要声明。
|
||||
|
||||
内联后必须自检三条：无 `unpkg` 残留、无 `src="v2/`（外部 jsx 引用）残留、根部挂载点仍在。任一不满足即构建失败。
|
||||
|
||||
### 3.3 输出红线（命中即返工）
|
||||
|
||||
来源：数值判据取 `craft/`（`typography.md` ＋ `color.md` ＋ `accessibility-baseline.md`），反 AI 味取 `craft/anti-ai-slop.md`，版式自查取 `web-prototype/references/checklist.md`。下列判据不在 craft 里重复抄写，只写本项目追加的那几条。
|
||||
|
||||
- 间距只用令牌表登记的刻度值；确需中间值（如紧凑表格行高）在令牌表登记，不许临时拍。刻度外值混用是「廉价感」的主要来源（判据见 `craft/typography.md`）
|
||||
- 数字列用 `font-variant-numeric: tabular-nums`（否则刷新时宽度跳动，表格跟着抖）
|
||||
- 禁单层死黑重阴影，用多层叠层 ＋ 1px 半透明边框。层级按内容需要，不设人为上限；判的是「同层级是否同值」，不是「层级总数是否超标」
|
||||
- 强调色全屏面积 ≤5%（判据见 `craft/color.md`）；状态色只用红绿黄三系，不做装饰
|
||||
- 标题禁用 Inter / Roboto / Arial / `system-ui`（正文可用）；中文字重别超 600（`craft/typography.md`）
|
||||
- ⭐ 结构四条（本项目追加，craft 无对应）：① 区块 ≥2 个且每个有文字标题（图标 / 徽章 / 分组容器不替代标题），标题不跳级；② 实际在用字号档 ≥3 档且相邻档差 ≥2px，正文档落在 14–16；③ 块间距 ≥ 块内间距的 2 倍；④ 按钮有主次分档且同屏主档 ≤1（多步流程每步 ≤1），分档靠填充色 ＋ 高度
|
||||
- 反 AI 味逐条过 → `craft/anti-ai-slop.md`。⚠️ 「卡片墙」判的是「同一圆角 ＋ 同一阴影 ＋ 所有模块视觉权重完全相同」的等权卡片墙，不是「用了卡片」。有主次、有分组、层级不同的卡片是合法结构手段，别把卡片当禁区整片封掉
|
||||
- 状态穷举六项 → `craft/state-coverage.md`（loading / empty / error / success / disabled / 无权限，逐项判据在那份）
|
||||
- 布局 Grid 管栅格、Flex 管行内对齐；移动优先，断点 `<640` / `640–1024` / `>1024`
|
||||
- 防溢出三件套：grid 写 `minmax(0,1fr)`（不是 `1fr`）、flex 子项加 `min-width:0`、表格 / 代码块外层 `overflow-x:auto`
|
||||
- 交互态齐全：`hover` / `active` / `focus-visible` 三态都要写，焦点环不许被 `outline:none` 抹掉（`craft/accessibility-baseline.md`）
|
||||
- 规范 HTML：非空元素显式闭合、属性双引号
|
||||
- 文件名要有描述性；集中放 `designs/<项目>/`，不散落仓库根
|
||||
|
||||
### 3.4 本项目附加纪律（`open-design` 未涉及）
|
||||
|
||||
- 🔴 与 §供给·方法主线（**基础层**）的口径：本项目只许在它之上**收严 / 具体化**，⛔ 不许放宽或推翻（2026-10-08 用户定案「oil 是基础，在这个基础上可以叠加其他设计规范」）。当前收严项登记如下 ——
|
||||
1、强调色占屏面积：本项目比基础层更严。
|
||||
⚠️ 反过来：想把本项目的某项**放宽**到基础层之上（例如允许更多字号档、更多同屏动效），那不算叠加 —— ⛔ 不行，得先回基础层改。
|
||||
- 重大改版必须复制副本再改（`X.html` → `X v2.html`），不许覆盖旧版。旧版留在磁盘上以便对比（版本管理主线需要可追溯）
|
||||
- 原型里的状态由路由 ＋ 演示开关驱动，不是 `?state=` URL 参数；实测时按这个来
|
||||
|
||||
### 3.5 实测硬关卡（未过不得进 3c）
|
||||
|
||||
用 `browser-harness` skill，以 D0 契约的「交互清单」为唯一清单逐个真点：每行按「触发 → 反馈」实跑；空 / 加载 / 错误 / 失败重试四态都要走到；回报控制台报错原文与「点了没反应」的元素清单。
|
||||
|
||||
- ⛔ 本步是唯一的可点通过道。不许因「没有自动机检」就跳过或降级；实测不过就不许进 3c
|
||||
- 实测一律走 `browser-harness`（浏览器入口 9333），禁用 Trae 自带浏览器工具
|
||||
- React 受控输入用 `fill_input(selector, text)` 填，不要用 `type_text()`（后者绕过框架监听器，提交按钮会一直是禁用态）
|
||||
- 测前禁缓存（`Network.setCacheDisabled`），否则会读旧 `.jsx`
|
||||
- 顺序也是关卡：3a 未过 Gate-1 不进 3b；未跑实测不得进 3c
|
||||
|
||||
---
|
||||
|
||||
## 4. 3c GPT 会诊（必做，顺序在 3d 之前）
|
||||
|
||||
触发点：3b 原型初稿和实测都过了，立刻做。步骤、提问模板、四列处置表、输入边界、异常情况见 `SKILL.md` §3c，不在此重复。
|
||||
|
||||
为什么必须有这一步：3a / 3b 全是本地确定性检查，没有外部视角，这一步补的正是它补不了的那块。
|
||||
|
||||
三道不可松的口子：① 用附件上传原型 HTML，不许把上万字符代码粘进输入框；② 等回答出完再取原文，不许读一半；③ 上传前脱敏（密钥、真实数据、内网地址换占位符）。
|
||||
|
||||
取不到时：不许假装跑过。落盘写明「本轮未取得外部审查」，并在段末明示 —— 未取得不等于已通过。
|
||||
|
||||
处置：采纳要给理由，与 `DESIGN.md` 或②段冲突的写清为什么不采纳。采纳项在 3d 之前改完，并回到 3b 的实测清单把这些改动再点一遍。
|
||||
|
||||
---
|
||||
|
||||
## 5. 3d 审查与打磨（D3 收口 + D4 动效 + D5 终检 + Gate-2/3）
|
||||
|
||||
### 5.1 D3 收口（管"写得对不对"）
|
||||
|
||||
对照 `open-design/design-templates/web-prototype/references/checklist.md` + `craft/typography.md` / `typography-hierarchy.md` / `color.md` / `accessibility-baseline.md` 逐条过。
|
||||
|
||||
> 🔴 本步一律人工过（2026-10-02 用户定案：不重要的相关内容一律删，不建替代脚本）。判据有三处来源，不许跳过任一处：
|
||||
> ① `SKILL.md` 的 Gate-1 自检表 ｜ ② `craft/` 四份规约 ｜ ③ 下列本项目追加判据。
|
||||
|
||||
本项目追加判据（craft 无对应，必须留在这里）：
|
||||
|
||||
- 结构四条：① 区块 ≥2 个且每个有文字标题，标题不跳级 ｜ ② 实际在用字号档 ≥3 档、相邻档差 ≥2px、正文档落在 14–16 ｜ ③ 块间距 ≥ 块内间距的 2 倍 ｜ ④ 按钮有主次分档且同屏主档 ≤1
|
||||
- ⭐ 工具型页面五条（本项目追加，2026-10-05）：标题区零从属小字 ｜ 导航带标签 ｜ 并列卡有主次 ｜ 分组不靠边框 ｜ 无假控件。逐条判据与机械核对法在 `references/layouts-tooling.md` §5.5，不在此重复展开
|
||||
⚠️ 其中「标题区零从属小字」与 `web-prototype/references/checklist.md` 的 `P0-A` 是同一判据的两处落点：checklist 管「怎么写」，本节管「怎么量」，口径一致，判据正文只在 `layouts-tooling.md` §5.5.1
|
||||
- 间距只用令牌表登记的刻度值，确需中间值先登记
|
||||
- 数字列用 `font-variant-numeric: tabular-nums`（否则刷新时宽度跳动）
|
||||
- 禁单层死黑重阴影，用多层叠层；层级按内容需要，判的是「同层级是否同值」，不是「层级总数超标」
|
||||
- 防溢出三件套：grid 写 `minmax(0,1fr)`、flex 子项加 `min-width:0`、表格 / 代码块外层 `overflow-x:auto`
|
||||
- 交互态齐全：`hover` / `active` / `focus-visible` 三态都写，焦点环不许被 `outline:none` 抹掉
|
||||
|
||||
> ⚠️ 判据以「内联后的交付单文件」为准。扫多文件开发目录会出幻影阻断（片段文件里当然找不到 CSS 里才有的规则）。本地曾实测整目录扫出 9 条幻影阻断。
|
||||
|
||||
### 5.2 D4 动效（可跳过）
|
||||
|
||||
按 `craft/animation-discipline.md` 先答动效三问：① 它传达什么信息？② 删掉会丢失什么？③ 是不是为了「看起来高级」？答不出就不加。
|
||||
|
||||
- 工具型页面（仪表盘 / 后台 / 编辑器 / 工作台）禁止入场编排：用户一天开几十次，每次播一遍是折磨。本项目的版本管理界面属工具型；判不准时按工具型处理
|
||||
- 弹簧用 Damping / Response 二参数（Damping 保持 0.8–1.0、Response 0.3–0.4s；低于 0.7 会明显「蹦」）
|
||||
- CSS 无法用真弹簧时用 `cubic-bezier(0.32, 0.72, 0, 1)`；过渡曲线不得用 `linear` / `ease` / `ease-in-out`
|
||||
- 交互过渡禁 `@keyframes animation`（不可中断，反向操作会跳帧），用 `transition` 或 WAAPI
|
||||
- 只动 `transform` / `opacity`，不动 `width` / `height` / `top` / `left`；禁止 `scale(0)` 起手（用 `scale(0.95)` ＋ opacity）
|
||||
- 退出比进入快（进 300ms / 出 200ms）；同屏动效元素 ≤3 个且有 30–50ms 错峰
|
||||
- `prefers-reduced-motion` 必须处理
|
||||
|
||||
### 5.3 D5 终检（管"能不能交"）
|
||||
|
||||
过 `craft/state-coverage.md`（状态穷举）＋ `craft/anti-ai-slop.md`（反 AI 味）＋ `web-prototype/references/checklist.md`（P0/P1）＋ 动效三问 ＋ 交互清单逐行复测，并真渲染一次。
|
||||
|
||||
> 🔴 渲染复测用本机 Chrome 无头截图（2026-10-02 实测可用）：
|
||||
>
|
||||
> ```bash
|
||||
> "/c/Program Files/Google/Chrome/Application/chrome.exe" --headless=new --no-sandbox --disable-gpu \
|
||||
> --hide-scrollbars --window-size=1440,900 --virtual-time-budget=3000 \
|
||||
> --screenshot="<Windows 绝对路径>/P1.png" \
|
||||
> "file:///<原型绝对路径，中文需 URL 编码>#/p/xxx"
|
||||
> ```
|
||||
> ⚠️ 两条坑：`--screenshot` 必须给 Windows 绝对路径（给相对路径会写进 Chrome 安装目录，回来找不到）；中文文件名要 URL 编码。
|
||||
> ⛔ 脚本缺失期间，截图只替代「看得见的」那部分：溢出与响应式破损能看出来，对比度 / 状态可见性 / 点击目标尺寸 / 死按钮判不了，那些仍按 5.1 的人工判据 ＋ 3b 的 `browser-harness` 实测走。
|
||||
> 截图两种形状，用途不许混：
|
||||
>
|
||||
> | 形状 | 尺寸 | 用途 |
|
||||
> |---|---|---|
|
||||
> | 视口帧 | 1440×900 / 390×844 | 对外评审、提交外部评估、交付留档一律用这张 |
|
||||
> | 整页长图 | 视口宽 × 整页高 | 仅自检「整页有没有塌」，不对外 |
|
||||
>
|
||||
> ⚠️ 混用会出事（本项目实测踩过）：把长图当参考图交出去，移动端是 1:7.1 的长条、桌面端 1440×1429，「首屏」这个信息整个丢失。外部评估只能按长条理解布局，「首屏有没有主次」「坐得下几行」根本没被评审到。
|
||||
>
|
||||
> 两个视口都要截（`1440x900` 与 `390x844`），只截桌面端等于没测响应式。
|
||||
>
|
||||
> 结构与排版仍要量（脚本缺失期间靠 DOM 取值人工量）：字号档数与相邻档差 / 正文档承载占比 / 标题大纲 / 按钮高度与实底分档 / 列对齐 / 对齐锚点 / 浮层可见关闭出口唯一。⛔ 不许目测截图下结论，取值结果直接抄进 `3d-审查报告.md` 的结构核对表。
|
||||
>
|
||||
> 本项目是 hash 驱动路由，hash 接在文件名后（`<原型>.html#/p/xxx`）；不接就渲染到空壳视图，截图与数字全是假的。
|
||||
>
|
||||
> 「无法判定」一律按未通过对待（「判不了」≠「没问题」）：浮层类在未打开态必然判不了，必须按 Gate-3 的打开态复测口径，用 `browser-harness`（复用同一页签）逐个打开浮层再数可见关闭出口，与 `Esc` / 点遮罩 / 焦点锁三条一起留痕。
|
||||
|
||||
契约里写了数字的，逐条取值回填（`05` §二 第 11 项，阻断级）
|
||||
|
||||
脚本不认识项目自定义选择器（`.ver-row` 之类），所以契约里的数字 —— 首屏条数、单条行高、承载占比、面积占比、对比度比值 —— 没有任何一道机检会替你核。它们是全篇最像「已经验过」的一类内容。
|
||||
|
||||
- 用 `browser-harness` 或 DOM 取值，按契约声明的视口量（本项目是 `1440×900` 与 `390×844`）；`browser-harness` 必须复用同一个页签（`list_tabs()` → `switch_tab()` → `goto_url()`，不要 `new_tab()`）
|
||||
- 回填的是实测值，不是复述契约值；把「契约值 / 实测值」并排列进 `3d-审查报告.md` 的结构核对表
|
||||
- 不得目测，不得沿用上一版数字
|
||||
- 契约没声明判据的档位（例如本项目窄屏的行高）如实记为证据缺口，不要临时编一个阈值凑上
|
||||
- 反面案例（`DESIGN` §8.10 E-18）：某轮契约写「单个版本行高 ≤96px / 1440×900 首屏 ≥5 行」，是凭印象写的，真渲染才发现是 118px / 3 行，两个数字同时不达标，而当时没有任何门禁会报它
|
||||
|
||||
### 5.4 Gate-2 完成门
|
||||
|
||||
全部 `阻断` 项清零，`建议` 项逐条有结论：修掉，或显式写「已知不修 ＋ 原因」。
|
||||
不接受「基本没问题」「应该差不多」「剩余都是小问题」。每条要么修，要么留痕。
|
||||
|
||||
### 5.5 Gate-3 交付门（硬闸，任何挡位不可跳）
|
||||
|
||||
真实渲染后（浏览器打开，非只看代码）肉眼过八项：裁切 / 重叠 / 失真 / 失效控件 / 缺状态 / 响应式破损 / 控制台报错 / 字体回退异常。
|
||||
|
||||
> 🔴 **2026-10-08 追加两条硬要求 —— 起因是本项目实测事故：五道闸门全绿，界面仍然难看。**
|
||||
>
|
||||
> **① 「看过」必须有落盘记录。** `oil-ui-pro` 的评分闭环（截图 → 评审 → 修改；10 分制、目标 9 分、默认最多三轮）
|
||||
> 的结果要写进 `3d-审查报告.md`。⛔ **不许用「自检脚本 N 项全绿」顶替「看过并满意」** ——
|
||||
> 脚本量的是一致性与完整性（结构漂没漂、控件死没死、语法炸没炸、行数退没退化），**没有一条量「像不像给人用的」**。
|
||||
> 上述那八项肉眼项也全是「有没有坏」，「丑」不在其中。
|
||||
>
|
||||
> **② 人工项必须给机检实现，否则不许打勾。** 凡挂在本门或 §7 完成标准里的判据，要么给出可跑的取值
|
||||
> （脚本 / DOM 取值命令），要么在该条后面写死「**本条无机检**」。
|
||||
> 🔴 **⛔ 不许在没有取值手段的条目上打 ✅** —— 本项目实测：收口清单里「§5.5 五条逐条过完 ✅ 自检机核」
|
||||
> 这一格是**假的**（那五条当时零覆盖），而它正是「全绿却难看」的开关。
|
||||
无头截图已代劳其中的溢出与响应式破损，其余仍需人眼（截图查不出「点了没反应」，那靠 3b 的 `browser-harness` 实测）。
|
||||
|
||||
落盘 `designs/<项目>/3d-审查报告.md`，按 `05` §五的模板：范围 ＋ 挡位 ＋ 阻断项表 ＋ 建议项表 ＋ 状态覆盖核对表 ＋ Gate 结论。
|
||||
|
||||
---
|
||||
|
||||
## 6. 偏离单（本段收尾必须附）
|
||||
|
||||
| # | 原要求（文件:小节） | 实际做法 | 原因 | 影响 | 处置 |
|
||||
|---|---|---|---|---|---|
|
||||
| | | | | | 已修 / 持续偏离 / 待用户裁定 |
|
||||
|
||||
本项目长期挂账的偏离（每次执行都要重新声明状态）：
|
||||
|
||||
| # | 项 | 状态 |
|
||||
|---|---|---|
|
||||
| A1 | `web-prototype` 默认产出单文件 HTML；本项目开发期用 React+Babel 多文件，交付时手工内联成单文件（无宿主工具可代劳：`super_inline_html` / `present_fs_item_for_download` 在 Trae 都不存在） | 持续偏离，3b 收尾做内联并自检三条 |
|
||||
| A2 | 宿主下载 / 预览工具不存在（`SendUserFile` / Claude Preview MCP） | 按 `SKILL.md` 适配注记：改 Write 落盘 ＋ `browser-harness` 实测 |
|
||||
| A3 | 实测必须用 `browser-harness`（浏览器入口 9333），禁用 Trae 自带浏览器工具 | 项目既定约束，优先级高于手册的通用说法 |
|
||||
| A4 | 预览服务端口用 4311（`python -m http.server 4311 --directory designs`） | 与 9333 不冲突：4311 是服务，9333 是自动化浏览器入口 |
|
||||
|
||||
没有偏离单就不得报完成。
|
||||
|
||||
---
|
||||
|
||||
## 7. 完成标准（逐条可核对）
|
||||
|
||||
- [ ] 声明制走完：开工、每个子步、每处偏离都有声明；挡位已声明（快速 / 标准 / 严格）
|
||||
- [ ] 第 1 节必读表已按阶段取用；同一时刻只读 1~2 份，未一次性全读（限载）
|
||||
- [ ] 供给核对做过：三处供给在位、选定套名与 `DESIGN.md` 记录一致；不一致时供给变更清单已获用户确认并写入修订记录
|
||||
- [ ] `docs/pm/<项目>/DESIGN.md` 存在，含设计契约（十二个字段，含结构骨架、交互清单与重复项的信息量）与令牌表（三层 token 结构，含组件规格 ＋ 字阶定值表 ＋ 高度层级 ＋ 布局脚手架（含容器与对齐锚点）＋ 浮层只许一个可见关闭出口，全为具体值）
|
||||
- [ ] 骨架未漂（2026-10-06 口径调整）：D0 的页面清单与每页板块与②段《界面布局》逐条对得上；本段未增删移动任何板块
|
||||
- [ ] 分档已兑现：②段分档表每条信息的「主屏常驻 / 可点入」在实现里兑现；档位未被本段改动
|
||||
- [ ] `结构骨架` 已落：骨架档给了理由；板块 ≥2 个且每个有文字标题；板块清单来自②段；密度目标只取一档
|
||||
- [ ] 页型已判（营销页 / 工具型，给了依据）；工具型页面零 `.eyebrow` / 零 `.lead` / 零 `.hero`，且 `layouts-tooling.md` §5.5 五条逐条过完（含「标题区零从属小字」的 DOM 取值）
|
||||
- [ ] Gate-1 全部自检项结果写在 `DESIGN.md` 末尾，无一项不过
|
||||
- [ ] 原型 HTML 单文件自包含、双击可开，内联自检三条通过（无 unpkg / 无外部 jsx 引用 / 挂载点在）
|
||||
- [ ] 状态穷举六项逐条有结论（`05` §三第 1 项）
|
||||
- [ ] 每个按钮、每个跳转都用 `browser-harness` 真点过，含空 / 加载 / 错误 / 失败重试四态，并回报控制台报错原文与「点了没反应」清单
|
||||
- [ ] `designs/<项目>/3c-GPT会诊.md` 存在，含提问原文、模型回答原文、四列处置表；未取到已明示
|
||||
- [ ] D3 收口已按 5.1 三处判据人工过完：Gate-1 自检表 ＋ `craft/` 四份规约 ＋ 本项目追加判据，阻断项清零（取值结果已抄进报告）
|
||||
- [ ] D5 终检已真渲染：`1440x900` 与 `390x844` 两个视口各截一张，视口帧已留档；横向溢出 0 / 对比度不达标 0 / 结构与排版阻断 0，且无「无法判定」项（DOM 取值已抄进报告）
|
||||
- [ ] 每个浮层都手工打开数过可见关闭出口（`== 1`）＋ `Esc` / 点遮罩能关、焦点锁在层内且关闭后回到触发按钮；结论与触发路径已写进 `3d-审查报告.md`
|
||||
- [ ] 对外提交 / 交付留档的截图只用视口帧；`_full/` 长图未作为评审输入
|
||||
- [ ] 契约里每个写出来的数字都已实测回填（首屏条数 / 行高 / 承载占比 / 面积占比 / 对比度比值），「契约值 / 实测值」并排列出；未回填即阻断；契约未声明判据的档位已记为证据缺口
|
||||
- [ ] `designs/<项目>/3d-审查报告.md` 存在，含阻断 / 建议两张表 ＋ 状态覆盖核对 ＋ 结构核对（数字抄自脚本输出，非「目测」）＋ Gate-2/3 结论
|
||||
- [ ] Gate-2 与 Gate-3 均已通过（书面结论，非口头）
|
||||
- [ ] 重大改版：旧版文件仍在磁盘上，且收尾给出新旧差异（改了什么 / 为什么 / 代价）
|
||||
- [ ] 偏离单已附，且无静默偏离
|
||||
@@ -1,13 +1,11 @@
|
||||
# 工具型版式库（工具型数据密集界面 · 本项目追加）
|
||||
|
||||
> ⛔ 本文件是 `stage-delivery` 自己的东西。
|
||||
> ⭐ 「可选档那套为什么不能用于工具型」的骨架名单与理由只在本节写一次（§供给·版式骨架 只登记结论）；
|
||||
> ③段 `SKILL.md`、`references/execution-runbook.md`、总入口 `product-planning/SKILL.md` 提到它时一律引本节，⛔ 不复述名单。
|
||||
> 可选档的 `layouts.md` 那 8 个骨架是落地页 / 营销页向（hero / features / stats / quote / cta / log / pricing），
|
||||
> ⛔ 本文件是 `stage-delivery` 自己的东西。`open-design/design-templates/web-prototype/references/layouts.md`
|
||||
> 的 8 个骨架是落地页 / 营销页向（hero / features / stats / quote / cta / log / pricing），
|
||||
> 工具型页面只适用其中 Layout 7 日志列表与 Layout 8 对比表。
|
||||
> 其余套上去会把后台做成营销页 —— 这是「版式与判据同源」的必然结果，不是审美问题。
|
||||
>
|
||||
> 工艺数值判据（§供给·工艺数值判据）不给版式；8 骨架不给工具型。
|
||||
> `craft/` 是通用工艺，不给版式；8 骨架不给工具型。
|
||||
> 工具型页面的版式在本项目只有这一份来源，它是③段「正向目标」的最后一块空缺。
|
||||
|
||||
---
|
||||
@@ -104,7 +102,7 @@
|
||||
⑤ 它是**行式列表的四条判定要点之一**，不是跨全站的第一原则。与「像不像参照物」冲突时，
|
||||
先问「这条页面的主操作是扫行吗」—— 不是，就不适用。
|
||||
- 每行必须带主标识（`v12` 这类短标或标题），⛔ 不许整行只有一句描述。
|
||||
- 状态用 `tag` 不用整行底色。整行着色 ⇒ 该行不再是"可读的记录"而是"一条告警"。（⚠️ 与 §4 的「当前项」不是一回事：那是**选中态**，用整块浅底，不是记录状态。）
|
||||
- 状态用 `tag` 不用整行底色。整行着色 ⇒ 该行不再是"可读的记录"而是"一条告警"。
|
||||
|
||||
---
|
||||
|
||||
@@ -215,9 +213,9 @@
|
||||
<p class="meta">元素</p>
|
||||
<p style="margin: 2px 0 0;">登记新版本按钮</p>
|
||||
</div>
|
||||
<div class="card-flat" style="padding: 10px 12px; background: color-mix(in srgb, var(--accent) 12%, #fff);">
|
||||
<div class="card-flat" style="padding: 10px 12px; border-left: 3px solid var(--accent);">
|
||||
<p class="meta">元素 · 当前</p>
|
||||
<p style="margin: 2px 0 0; font-weight: 600;">导出登记台账</p>
|
||||
<p style="margin: 2px 0 0;">导出登记台账</p>
|
||||
</div>
|
||||
<div class="card-flat" style="padding: 10px 12px;">
|
||||
<p class="meta">元素</p>
|
||||
@@ -244,9 +242,8 @@
|
||||
判定要点：
|
||||
|
||||
- 左区可收窄但不可隐藏（`min-width` 保底）—— ⛔ 不许做成抽屉或浮层，工具型页面要能同时看到两面的对应关系。
|
||||
- 当前项用**元素自身**表达：整块浅底（`background` 铺满）＋ 字重加重 ＋ 状态词「当前」，⛔ 不用 `border-left` 或 `inset` 左侧色条。
|
||||
（单侧彩色边条标状态的禁令，权威在 oil-ui-pro 视觉语言的反模型默认清单 —— 此处只落工具型写法，不复述那份清单。）
|
||||
⭐ 这是「状态修饰不参与分族」的正面用法：状态修饰（如 `is-current`）不参与分族，`card-flat` 才是分族键 —— 两者不能混进同一个分组键。
|
||||
- 当前项用 `border-left` 指示（3px 实底），⛔ 不用底色铺满。
|
||||
⭐ 这是「状态修饰不参与分族」的正面用法：`border-left` 属状态修饰，`card-flat` 才是分族键 —— 两者不能混进同一个分组键。
|
||||
- 右区必须与左区当前项对应，⛔ 不许左区选中变了右区不动。
|
||||
|
||||
---
|
||||
@@ -356,11 +353,11 @@
|
||||
|
||||
## 5. 通用红线（工具型专属 · 五条 = 本项目判据正文）
|
||||
|
||||
> 本节是③段工具型判据的唯一定稿处。§供给·版式骨架 可选档里的 `tooling.md`
|
||||
> 本节是③段工具型判据的唯一定稿处。`open-design/design-templates/web-prototype/references/tooling.md`
|
||||
> 的「通用红线」只是纲要指路（它管所有工具型页面的形态判定），逐条判据与实测反例以本节为准。
|
||||
> ⛔ 两边不重复展开 —— 同一判据两处展开必然漂。
|
||||
|
||||
- ⛔ 不做**逐区块**的入场编排（每个区块各套一次淡入上移 —— §供给·方法主线 把它列为模型默认）。首次进入的**一次**协调出场按 §供给·方法主线 的最简档做，高频工具页（一天开几十次）可整段省去；⛔ 不用 `linear` / `ease` 做编排。详见 §供给·工艺数值判据 里动效那一份。
|
||||
- ⛔ 不做入场编排。工具型页面一进来就该是可读的工作面，不用 `linear` / `ease` 做元素入场。详见 `craft/animation-discipline.md`。
|
||||
- ⛔ 不为"好看"加装饰区块。判据用 D0 的 `必要内容`：删掉它，主操作还做得成吗 —— 答得出"做得成" ⇒ 不上屏。
|
||||
- ⛔ 不把落地页当默认骨架。挑骨架前必须先过 §0 的形态判定；判不出形态就去改 D0 的 `结构骨架` 字段，⛔ 不许随手挑一个。
|
||||
- ⛔ 标题区零从属小字（详见 §5.5.1）。
|
||||
@@ -394,14 +391,9 @@
|
||||
> ⛔ 这不能一律判红 —— 得逐条回答上表两问。放行的事实条必须同时满足：① 是数据不是句子；② 与该对象的主操作按钮同属一个视觉单元（同行或紧邻），而不是独占了标题的第二行。
|
||||
> ✅ 若事实条独占标题下方一整行（如本原型首版），仍判不过 ⇒ 把它挪到与主操作同行。
|
||||
|
||||
### 5.5.2 导航栏的判据是「名字常驻可读」，不是「栏有多宽」（2026-10-08 订正）
|
||||
### 5.5.2 导航栏不许只有图标（治法：「默认带标签，折叠才收」）
|
||||
|
||||
> 🔴 **订正原因（本项目实测事故，2026-10-08）**：原文写「主导航默认必须带文字标签（宽 ~240–280px），⛔ 不许一上手就是 52px 纯图标栏」——
|
||||
> 它把**手段（栏宽 240–280px）当成了目的（名字常驻可读）**。于是出现了一个「判据判不过、但产品上完全成立」的形态：
|
||||
> **64px 药丸图标栏 ＋ 图标 24 ＋ 2 字短名常驻**（源站 `www.tiaoyue.com` 的 `app-sidebar` 就是这个，实测栏 64 ／ 项 56×78 ／ 名字 12px 常驻）。
|
||||
> 更坏的是它引发了**反向事故**：为了"合规"，执行者把标签设成 `display:none`（宽屏只留图标 ＋ 悬停提示）——
|
||||
> 表面上写成"64px 图标栏"，实际比原文的反例更狠（连折叠态的展开入口都没有）。**判据的漏洞被拿去当成了通行证。**
|
||||
> ⚠️ 同型警戒：凡"拿某个数值当判据"的条目，先问一句**那个数值是目的还是手段**；是手段就把它写成可判的实质。
|
||||
实证：「sidebar becomes **a wall** and needs grouping or a different model」（>15 项时）；「**Collapsible Sidebars** …… shrinks to just 64px, **hiding the text labels and showing only the icons**」—— 只图标是折叠态，不是默认态。
|
||||
|
||||
实证（原文引用保留）：「sidebar becomes **a wall** and needs grouping or a different model」（>15 项时）；「**Collapsible Sidebars** …… shrinks to just 64px, **hiding the text labels and showing only the icons**」—— 只图标是折叠态，不是默认态。
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ description: 产品规划第①段，产品需求。五个子步依次产出五
|
||||
|
||||
🔴 用户原话：「禁止出现之前确定的以外的文档，除非用户明确要求」。
|
||||
不许自行新增第 6 份。实测栽过：某轮因为"用户点名了参考产品"就自作主张多产了一份《参考实装拆解》，用户反复看到"冒出来的不相关的文档"。"参考产品怎么做的"属 1b 竞品分析的取材范围，写进本份里，不另立一份。
|
||||
⭐ `1b-独立分析/` 子目录不算"第 6 份"：它是 1b 的既定体例之一（定案原话见 `references/competitor-analysis.md` §0.4）。它的份数由竞品池决定，不由人临时加。除此之外仍只许上面那五份。
|
||||
⭐ `1b-独立分析/` 子目录不算"第 6 份"：它是 1b 的既定体例之一（2026-10-07 用户定案：「竞品分析 有独立分析也有汇总分析 都应该要用上，谁说只有一份竞品分析了」）。它的份数由竞品池决定，不由人临时加。除此之外仍只许上面那五份。
|
||||
✅ 门禁可查：`check_naming.py` 扫 `research/` 顶层的实际文件名，出现白名单外的文件名即报红（子目录天然放行）。
|
||||
|
||||
## 本段职责（2026-10-06 重划）
|
||||
@@ -58,7 +58,12 @@ description: 产品规划第①段，产品需求。五个子步依次产出五
|
||||
|
||||
本子步不受"提问上限 3 个"约束，把需求问清楚正是它的全部价值。进入前先声明"接下来会连续多轮提问"。这是本段唯一例外（详见 `references/grill-me.md`）。
|
||||
|
||||
⭐ `grill-me` 全场只有本段这一份（2026-10-06 用户定案，原话见 `references/grill-me.md` 开头）。本份按 A / B 两节提问，火力点划分与节次归属见 `references/grill-me.md` —— ⛔ 本文件不复述。
|
||||
⭐ `grill-me` 全场只有本段这一份（2026-10-06 用户定案：「grill-me 也应该拿到第一步了，第二步就是细化功能」）。本份按 A / B 两节提问：
|
||||
|
||||
| 节 | 火力点 | 原归属 |
|
||||
|---|---|---|
|
||||
| A 节 | 要做什么、为谁、边界在哪 | ①段 |
|
||||
| B 节 | 做成什么样、哪些情况不成立、状态怎么流转 |②段|
|
||||
|
||||
> 不许再加回②段一份。②段从 2026-10-06 起只细化功能，不再反问需求，反问在这里一次性做完。
|
||||
> ⚠️ 合并的代价要说清：两个火力点合到一处，提问量必然变大。用"分节提问"解决，不许因为量大就省略 B 节——跳了 B 节等于把功能压测整个删掉。
|
||||
@@ -71,11 +76,11 @@ description: 产品规划第①段，产品需求。五个子步依次产出五
|
||||
| 竞品拆解 · 独立分析 | `references/competitor-analysis.md` §11 | `docs/pm/<项目>/research/1b-独立分析/<竞品名>.md`（竞品池里每一个一份） |
|
||||
| 竞品拆解 · 汇总对比 | `references/competitor-analysis.md` §1—§10 | `docs/pm/<项目>/research/1b-竞品分析.md`（恒一份） |
|
||||
|
||||
1b 交两种体例。职责边界、份数与定案原话见 `references/competitor-analysis.md` §0.4 —— ⛔ 本文件不复述。只交一种 ⇒ 1b 没做完。
|
||||
1b 交两种体例（2026-10-07 用户定案：「竞品分析 有独立分析也有汇总分析 都应该要用上，谁说只有一份竞品分析了」）。职责边界与数量见 `references/competitor-analysis.md` §0.4。只交一种 ⇒ 1b 没做完。
|
||||
|
||||
> 🔴 写作口径（2026-10-07 补 · 用户报障逐字：「生成的文档并没有说人话，还是我手动要求的」）
|
||||
> 本段产出是给人看的文档，不是模型味的总结。落笔前读一遍其中一份：
|
||||
> 技能库 `humanizer-zh`（中文版）或会话技能包里的
|
||||
> 技能库 `humanizer-zh`（中文版，24 类 AI 写作模式）或会话技能包里的
|
||||
> `session-mechanism/references/作业规矩/04-去AI味与说话方式.md`（会话场景加固版，带交付前清单与质量评分）。
|
||||
> 定稿前按它的「交付前快速清单」过一遍。
|
||||
> 高频 AI 味一律禁：三段式排比连用、空转评价（「具有重要意义」「值得关注」）、以「…着」结尾的肤浅分析、模糊归因（「业内人士认为」）、过度加粗、把一句话拆成内联标题垂直列表。
|
||||
@@ -178,7 +183,9 @@ description: 产品规划第①段，产品需求。五个子步依次产出五
|
||||
> 分界线一句话：①段回答「要解决什么问题、用户怎么用它」，②段回答「要做哪些功能、长成什么骨架」。
|
||||
> 判据：一份文档若主体是功能条目的有无与优先级、页面与板块骨架 → 归②；若主体是问题、用户、取证与取舍理由 → 归①。
|
||||
> ⚠️ 2026-10-06 边界更新：②段从"不给页面结构"改为"给骨架"，页面关系与页面内板块布局必须在②段确认。
|
||||
> 修订后分工与用户原话：只在②段 `references/stage-requirements/SKILL.md` 的 §②—③ 交接口 定义一次，本段不复述。
|
||||
> 理由（用户原话）：「3 是负责设计和交互，页面关系和布局必须在第二步确认清楚，不然第三步没有方向，一会一个样子」。
|
||||
> 修订后分工：②段钉骨架（有哪几页、每页几个板块、板块怎么排、跨页关系）｜③段做皮肉（视觉规范 + 交互 + 状态，不许动骨架）。
|
||||
> 配色 / 字体 / 间距 / 组件样式 / 动效仍归③段，②段不许写这些。
|
||||
|
||||
## 硬约束
|
||||
|
||||
@@ -193,7 +200,7 @@ description: 产品规划第①段，产品需求。五个子步依次产出五
|
||||
- 区分事实与假设：来自检索或访谈的标 `【事实】`，推断的标 `【假设】`。1d/1e 的每条结论必须能追到 1b/1c 的某份文件或 `1a-需求文档.md` 的某一行；追不到的按假设处理。
|
||||
- ⭐ 1a 与 2a 的分工不许混（2026-10-02 段名对齐，2026-10-06 更新）：1a 定「问题与边界 + 形态与状态」（要做的东西凭什么成立、做成什么样），2a 定「功能与取舍」（要做哪些功能、哪些明确不做、页面骨架怎么排）。1a 不许写功能清单（那是 2a），2a 不许重开需求（那是 1a，含 2026-10-06 从②段合并进来的 B 节压测）。
|
||||
- ⭐ B 节合并后 `grill-me` 只此一份（2026-10-06）：②段不再有独立的 `grill-me.md` 与 `grill-decisions.md`，其二者的内容（做成什么样 / 状态怎么流转 / 哪些情况不成立）全部落进 `1a-需求文档.md`。不许把 B 节再挪回②段。
|
||||
- 段内子步之间不反问，做完直接进下一个子步。停线规则（哪几种情况停、怎么判）见 `product-planning` 的「执行规则」—— ⛔ 本段不复述，免得两处漂。
|
||||
- 段内子步之间不反问，做完直接进下一个子步。只有三种情况停：信息不足且查不到、破坏性/不可逆动作、用户显式要求（见 `product-planning` 的「执行规则」）。
|
||||
- `<项目>` 按 `product-planning` 的「项目与路径约定」定；定不出来就停下问用户，不许猜。
|
||||
|
||||
## 完成标准
|
||||
@@ -204,7 +211,7 @@ description: 产品规划第①段，产品需求。五个子步依次产出五
|
||||
- ⭐ 1b 两种体例都交了（2026-10-07 新增）：`research/1b-竞品分析.md`（汇总对比体）且 `research/1b-独立分析/` 下竞品池每一个一份（独立分析体）——只交一种 ⇒ 1b 没做完
|
||||
- ⭐ 目录里不出现白名单外的任何文件（第 6 份须有用户明确要求；`1b-独立分析/` 子目录是 1b 既定体例，不算第 6 份）
|
||||
- 1d/1e 每条结论都标了来源（哪份取证文件或本表哪一行，或 `【假设】`）
|
||||
- ⭐ 五份都过了「说人话」内容准则（源技能、判据与门槛见 `product-planning` 的「执行规则」内容准则条）；段末报告须写明"已过内容准则，评分 X/50"
|
||||
- ⭐ 五份都过了「说人话」内容准则（源技能 `humanizer` / `humanizer-zh`，门槛 ≥45/50）——口径见 `product-planning` 的「执行规则」内容准则条；段末报告须写明"已过内容准则，评分 X/50"
|
||||
|
||||
## 反面清单
|
||||
|
||||
@@ -215,14 +222,14 @@ description: 产品规划第①段，产品需求。五个子步依次产出五
|
||||
- 只做 A 节、跳过 B 节（2026-10-06 新增）：B 节即原②段的功能压测，跳过它等于把压测整个删掉，接口会带着没压测过的需求直接进②段与原型
|
||||
- 在 B 节把页面结构写死（2026-10-06 新增）：B 节只给粗粒度形态（有哪几页、大概几个板块）；精确板块清单与布局图归②段的《界面布局》
|
||||
- 产出白名单外的第 6 份文档（2026-10-06 新增）：不许因为"用户点名了某个参考产品/某份素材"就另立文档，写进 `1b-竞品分析.md` 里
|
||||
- 1b 只交汇总对比体、把独立分析省掉（2026-10-07 新增）：两份体例都要交（见 `references/competitor-analysis.md` §0.4）。也不许把独立体写成仓库取证记录，它必须按方法论 §11 的七节答产品面（用途 / 场景 / 能力 / 机制 / 强弱 / 对我们）
|
||||
- 1b 只交汇总对比体、把独立分析省掉（2026-10-07 新增）：用户定案「竞品分析有独立分析也有汇总分析 都应该要用上」。也不许把独立体写成仓库取证记录，它必须按方法论 §11 的七节答产品面（用途 / 场景 / 能力 / 机制 / 强弱 / 对我们）
|
||||
- 改本技能包的规则文件、却不过「说人话」这一关（2026-10-07 新增）：规则和产出同一把尺子，不许只给产出上锁、自己用另一套腔调写规则——口径见 `product-planning` 的「执行规则」内容准则条
|
||||
- 没有取证就直接写策略
|
||||
- 把 11 个子步全跑一遍充数
|
||||
- 事实与假设混在一起不标注
|
||||
- 拿"frontier 为空 / 无遗留未决项"当闭合声明，而正文里还挂着未经确认的假设——只读首屏的人会误读成需求已澄清
|
||||
- 凭空给 Importance / Satisfaction 打分：没有任何数据源支撑的数字，不许出现在交付物里
|
||||
- 五份没过「说人话」内容准则就落盘 —— 口径与门槛见 `product-planning` 的「执行规则」内容准则条
|
||||
- 五份没过「说人话」内容准则就落盘（带 AI 腔：夸张意义 / 三段式强凑 / 破折号滥用 / 模糊归因 / 通用乐观结尾）——门槛 ≥45/50，见 `product-planning` 的「执行规则」内容准则条
|
||||
- 把推演出来的用户画像当用研结论进 1c——三个 JTBD 若都追不到一句用户原话，那是自证不是用研
|
||||
- 越界去写②段、出原型或写原型说明文档（那是第②③④段）
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ description: 产品规划第②段，产品功能。只做一件事：把①段
|
||||
>
|
||||
> 与①段的分界：①回答「要解决什么问题、用户怎么用它」，②回答「要做哪些功能、长成什么骨架」。判据看文档主体 —— 主体是功能条目的有无与优先级、页面与板块骨架，归②；主体是问题、用户、取证与取舍理由，归①。
|
||||
>
|
||||
> ⭐ 2026-10-06 用户定案：本段收窄为「只细化功能」。2026-10-07 用户定案「2 产品功能 和 界面布局不就是两个文档嘛」，两件事各成一份：产品功能（做什么）＋ 界面布局（长什么样）。（①段侧的定案原话与 grill 归属见 `stage-discovery`，本段不复述。）
|
||||
> ⭐ 2026-10-06 用户定案：本段收窄为「只细化功能」。2026-10-07 用户定案「2 产品功能 和 界面布局不就是两个文档嘛」，两件事各成一份：产品功能（做什么）＋ 界面布局（长什么样）。用户原话：「不需要 就用使用场景，其余6分都不需要了，grill 也应该拿到第一步了，第二部就是细化功能」。
|
||||
>
|
||||
> 本段就这两份：`prd/2a-产品功能.md`（功能清单）＋ `prd/2b-界面布局.md`（页面骨架）。
|
||||
>
|
||||
@@ -20,29 +20,21 @@ description: 产品规划第②段，产品功能。只做一件事：把①段
|
||||
>
|
||||
> （历史：本段收窄前的产出清单与其去向 → `_留痕/②段-已删除产出与方法论.md`）
|
||||
|
||||
## ⭐⭐ ②—③ 交接口（唯一权威处 · 改边界只改这一块 · 2026-10-06 用户定案）
|
||||
|
||||
> 🔴 「②段管什么、③段管什么」**只在本节定义一次**。本段其余章节、总入口 `product-planning/SKILL.md`、
|
||||
> `stage-discovery` 与 `stage-delivery` 的 `SKILL.md`、③段 `references/execution-runbook.md` 与
|
||||
> `references/layouts-tooling.md`，提到这条边界时一律**引用本节的行名**，⛔ 不许再复述清单。
|
||||
> 为什么立这一块：同型的复述病已经造成过真事故 —— 停线规则被三段写成「三种、②段写成「四种」，
|
||||
> 两边长期漂着而没有任何门禁会报。单一可信源才拦得住。
|
||||
> 用户原话（本节的唯一出处，别处不再抄）：「3 是负责设计和交互，页面关系和布局必须在第二步确认清楚，不然第三步没有方向 一会一个样子」。
|
||||
## ⭐⭐ ②—③ 交接口（2026-10-06 用户定案）
|
||||
|
||||
口径：②段钉骨架，③段做皮肉。
|
||||
|
||||
| 归②段（必须在本段定死） | 归③段（⛔ ②段不许写） |
|
||||
| 归②段（必须在本段确认） | 归③段（⛔ 不许②段写） |
|
||||
|---|---|
|
||||
| 有哪几页 | 配色 / 字体 / 间距 / 组件样式 / 动效 |
|
||||
| 每页几个板块、板块怎么排 | 每个板块的视觉实现（怎么好看、怎么对齐、什么层次） |
|
||||
| 跨页关系（怎么跳转） | 每个板块的交互行为（点哪、什么反馈、何时不可点） |
|
||||
| 每页的主操作是什么 | 状态与空态的具体呈现 |
|
||||
| 每条信息在哪一档承载（主屏常驻 / 可点入） | 响应式怎么变 |
|
||||
| 有哪几页 | 配色 |
|
||||
| 每页几个板块 | 字体 |
|
||||
| 板块怎么排 | 间距 |
|
||||
| 跨页关系（怎么跳转） | 组件样式 |
|
||||
| 每页的主操作是什么 | 动效 |
|
||||
| 每条信息在哪一档承载（主屏常驻 / 可点入） | 具体的视觉实现 |
|
||||
|
||||
> ⭐ 骨架是判断基准，必须在②段定死。旧口径把「有哪几页」留在③段，结果就是③段做一版一个样，②段无从判断改得对不对。
|
||||
> ⛔ 交给③段时骨架是冻结的：③段不许新增 / 移动 / 删除板块，缺板块要回②段改。
|
||||
> 「归③段」那一列的六个词就是本段的**零视觉词红线**：本段其余章节与 `references/create-prd.md` 提到它时，
|
||||
> 一律写成「见 §②—③ 交接口 的『归③段』列」，⛔ 不再逐处抄这六个词。
|
||||
> ⛔ 交给③段时骨架是冻结的：③段不许新增 / 移动 / 删除板块，缺板块要回②段改（见 `stage-delivery` 的对应禁令）。
|
||||
|
||||
## 本段职责（2026-10-06 按「只细化功能」重划）
|
||||
|
||||
@@ -107,7 +99,7 @@ description: 产品规划第②段，产品功能。只做一件事：把①段
|
||||
|
||||
> ⭐ 拆成两份是 2026-10-07 的用户定案。旧写法一份装两半，同一件事要写两遍（比如 `header / side / footer` 既像页面框架又像页内板块）；拆开后各自只写自己那一侧，正好逼着把边界写明确。
|
||||
> 🔴 防重写规则（拆开后必须守）：页面级框架（`header / side / footer`）只在 `2b` 写一次；`2a` 的功能条目里只许出现「跨哪些页面」，⛔ 不许描述页面长什么样。
|
||||
> ⚠️ 粒度：本段给灰块框图（有哪些块、什么顺序），⛔ 不给视觉（颜色、字体、间距、圆角、层次）。视觉类六词（见 §②—③ 交接口 的『归③段』列），本段（含布局）仍不许写。
|
||||
> ⚠️ 粒度：本段给灰块框图（有哪些块、什么顺序），⛔ 不给视觉（颜色、字体、间距、圆角、层次）。配色 / 字体 / 间距 / 组件样式 / 动效，本段（含布局）仍不许写。
|
||||
> ⚠️ 旧 `ux/diagrams/system-architecture.html` 画的是系统组件之间的关系，属实现视角，已改名。本段要的是页面与板块，属产品视角，⛔ 不许再叫「系统架构」。
|
||||
|
||||
## 硬约束
|
||||
@@ -121,10 +113,10 @@ description: 产品规划第②段，产品功能。只做一件事：把①段
|
||||
- ⭐ 每条功能必须能追回①段《使用场景》（`1e-使用场景.md`）：追不回的功能就要么补一条场景、要么砍掉。这是本段唯一的功能有无判据，代替凭空打分。
|
||||
- ⭐ 状态流转写在功能条目里，⛔ 不再单独成文（2026-10-06）：每个功能条目自带「状态流转」字段。六项治理照旧全覆盖（失败恢复路径、持久化范围、并发冲突、幂等、超时迁移目标、不可逆操作二次确认），只是落点从独立文档移进功能条目。
|
||||
- ⭐ 状态挂不到任何功能上的中间态，要么删掉，要么补一个功能条目让它服务。
|
||||
- ⭐ 骨架必须给全（2026-10-06）：②段的《界面布局》必须给全 §②—③ 交接口 的「归②段」列那几样，逐条对应。⛔ 缺任何一样，③段就没有方向。
|
||||
- ⭐ 骨架必须给全（2026-10-06）：②段的《界面布局》必须给出 —— 页面清单 ＋ 页面流转 ＋ 每页板块清单与排列 ＋ 每页主操作 ＋ 每条信息在「主屏常驻 / 可点入」哪一档。⛔ 缺任何一样，③段就没有方向。
|
||||
- 信息承载分档的判据：「删掉它，主操作还做得成吗」—— 答「做得成」就只能进「可点入」。⛔ 「能读到」= 可点入，不等于主屏常驻；不许以「②段要求能读到」为由把信息留在主屏。
|
||||
- ⛔ 本段（含布局）不许写视觉（六词清单见 §②—③ 交接口 的『归③段』列），一个字都不许出现。
|
||||
- 段内不反问，做完直接往下走。停线规则（哪几种情况停、怎么判）见 `product-planning` 的「执行规则」—— ⛔ 本段不复述，免得两处漂。
|
||||
- ⛔ 本段（含布局）不许写视觉：配色 / 字体 / 间距 / 组件样式 / 动效，一个字都不许出现。
|
||||
- 段内不反问，做完直接往下走。只有四种情况停：信息不足且查不到、破坏性 / 不可逆动作、用户显式要求、①段末的方案确认（仅「方案确认」模式，见 `product-planning` 的「执行规则」）。
|
||||
- `<项目>` 按 `product-planning` 的「项目与路径约定」定；定不出来就停下问用户，不许猜。
|
||||
|
||||
## 完成标准
|
||||
@@ -133,11 +125,11 @@ description: 产品规划第②段，产品功能。只做一件事：把①段
|
||||
- ②段的「不做 / 移出」清单逐条对照过①段已拍板项，差异行为 0 或每一行都已获用户显式确认（附对照条目数，不得只写「无冲突」）
|
||||
- 功能清单每条带齐「功能名 / 来自哪条场景 / 优先级 / 状态流转 / 验收要点 / 跨哪些页面」六字段；⛔ 追不回①段场景的条目为 0
|
||||
- 状态流转六项治理全覆盖（失败恢复 / 持久化 / 并发 / 幂等 / 超时 / 不可逆二次确认），且落在功能条目内
|
||||
- 《界面布局》给全 §②—③ 交接口 的「归②段」列（含分档判据回答）
|
||||
- ⛔ 全文零视觉词（六词清单见 §②—③ 交接口 的『归③段』列）
|
||||
- 《界面布局》给全五样：页面清单 ＋ 页面流转 ＋ 每页板块与排列 ＋ 每页主操作 ＋ 每条信息的分档（含判据回答）
|
||||
- ⛔ 全文零视觉词（配色 / 字体 / 间距 / 组件样式 / 动效）
|
||||
- 每条假设都有归宿（三选一，无第四种）；凡依据假设的功能 / 状态流转 / 分档，条目里都带上了假设状态标注
|
||||
- 本段所有「待确认 / 暂缓」条目都带齐 复核人 / 复核时机 / 结论落点 三字段
|
||||
- ⭐ 两份都过了「说人话」内容准则（源技能、判据与门槛见 `product-planning` 的「执行规则」内容准则条）；段末报告须写明「已过内容准则，评分 X/50」
|
||||
- ⭐ 两份都过了「说人话」内容准则（源技能 `humanizer` / `humanizer-zh`，门槛 ≥45/50）—— 口径见 `product-planning` 的「执行规则」内容准则条；段末报告须写明「已过内容准则，评分 X/50」
|
||||
|
||||
## 反面清单
|
||||
|
||||
@@ -153,11 +145,11 @@ description: 产品规划第②段，产品功能。只做一件事：把①段
|
||||
- ⛔ 骨架给不全（2026-10-06）：只给页面清单、不给每页板块与排列，或只给布局、不给跨页关系 —— ③段拿不到方向，就会一版一个样
|
||||
- ⛔ 把某条信息标为「主屏常驻」却答不上「缺了主操作就做不成事」：按判据应归「可点入」
|
||||
- 状态流转只画正常路径，不管失败与并发；或状态挂不到任何功能条目上（凭空中间态）
|
||||
- ⛔ 在本段写视觉（清单见 §②—③ 交接口）—— 那是③段
|
||||
- ⛔ 在本段写视觉（配色 / 字体 / 间距 / 组件样式 / 动效）—— 那是③段
|
||||
- 越界去出原型或写说明文档（那是第③④段）
|
||||
- 把 `【假设】` 原样带进②段当既定事实；或假设已被实现却从不回填状态
|
||||
- 只写「暂缓」而不给复核人 / 复核时机 / 结论落点 —— 等于让这条永远挂着
|
||||
- ⛔ 两份没过「说人话」内容准则就落盘 —— 口径与门槛见 `product-planning` 的「执行规则」内容准则条
|
||||
- ⛔ 两份没过「说人话」内容准则就落盘（带 AI 腔：夸张意义 / 三段式强凑 / 破折号滥用 / 模糊归因 / 通用乐观结尾）—— 门槛 ≥45/50，见 `product-planning` 的「执行规则」内容准则条
|
||||
- ⛔ 改本技能包的规则文件、却不过「说人话」这一关（2026-10-07）：规则和产出同一把尺子 —— 口径见 `product-planning` 的「执行规则」内容准则条
|
||||
|
||||
## 本段读什么、守什么
|
||||
|
||||
@@ -12,9 +12,9 @@
|
||||
| # | 写什么 | 判据 |
|
||||
|---|---|---|
|
||||
| 一 | 功能清单 —— 做哪些、不做哪些、每条什么优先级 | 每条能追回①段《使用场景》（`1e-使用场景.md`） |
|
||||
| 二 | 界面布局 —— 与「归②段」列逐条对应（清单见 `SKILL.md` §②—③ 交接口） | ③段拿着它就有方向 |
|
||||
| 二 | 界面布局 —— 有哪几页、每页几个板块、板块怎么排、跨页关系 | ③段拿着它就有方向 |
|
||||
|
||||
> 不写：视觉（六词清单见 `SKILL.md` §②—③ 交接口 的『归③段』列）、需求取证（归①段）、grill 反问（归①段）、用户故事（归①段《使用场景》（`1e-使用场景.md`））。
|
||||
> 不写：视觉（配色 / 字体 / 间距 / 组件样式 / 动效）、需求取证（归①段）、grill 反问（归①段）、用户故事（归①段《使用场景》（`1e-使用场景.md`））。
|
||||
|
||||
## 一、功能清单
|
||||
|
||||
@@ -73,10 +73,11 @@
|
||||
|
||||
### 必须给全的五样（缺一样③段就没方向）
|
||||
|
||||
「归②段」那一列就是这五样，逐条一一对应（定义见 `SKILL.md` §②—③ 交接口）。两条操作细节补充：
|
||||
|
||||
1. 每页板块给到 wireframe 灰块粒度 —— 有几个块、从上到下什么顺序，⛔ 不含视觉。
|
||||
2. 页面流转要写清「谁跳到谁、什么条件下」，⛔ 不写「用户可自由导航」这类空话。
|
||||
1. 页面清单 —— 有哪几页，每页一句话说清干什么
|
||||
2. 页面流转 —— 页与页怎么连（谁跳到谁、什么条件下）
|
||||
3. 每页的板块清单与排列 —— 有几个块、从上到下什么顺序（灰块粒度，不含视觉）
|
||||
4. 每页的主操作 —— 唯一那个推进动作是什么
|
||||
5. 每条信息的分档 —— 主屏常驻 / 可点入（见下）
|
||||
|
||||
### 信息承载分档（判据只有一条）
|
||||
|
||||
@@ -113,9 +114,9 @@
|
||||
|
||||
## 四、通用要求
|
||||
|
||||
- 写给人看：短句、少术语，能读给不熟悉项目的人听懂。落盘前必须过「说人话」内容准则（源技能、门槛与五条核心原则见 `product-planning` 的「执行规则」内容准则条）。
|
||||
- 写给人看：短句、少术语，能读给不熟悉项目的人听懂。落盘前必须过「说人话」内容准则（源技能 `humanizer` / `humanizer-zh`，门槛 ≥45/50；五条核心原则与口径见 `product-planning` 的「执行规则」内容准则条）。
|
||||
- 每条都能追来源：功能追①段场景，假设带状态标注，判据给一句话。
|
||||
- 全文零视觉词（六词清单见 `SKILL.md` §②—③ 交接口 的『归③段』列），一个字都不许出现。
|
||||
- 全文零视觉词：配色 / 字体 / 间距 / 组件样式 / 动效，一个字都不许出现。
|
||||
- 保留修订记录：改了实现必须回填条款正文，不能只在修订记录里写。
|
||||
|
||||
## 落盘
|
||||
@@ -129,4 +130,4 @@
|
||||
- [ ] 优先级没填数字，只用 P0 / P1 / P2 加一句可复述的判据
|
||||
- [ ] 「不做」清单与①段已拍板项逐条对照，并给出对照过的条目数
|
||||
- [ ] 界面布局五样给全（页面清单 / 页面流转 / 每页板块清单与排列 / 每页主操作 / 信息分档）
|
||||
- [ ] 全文零视觉词（见 `SKILL.md` §②—③ 交接口 的『归③段』列）
|
||||
- [ ] 全文零视觉词（配色 / 字体 / 间距 / 组件样式 / 动效）
|
||||
@@ -66,8 +66,7 @@ agent_created: true
|
||||
|
||||
> **判据（一句话）**：**用户说了触发句 ⇒ 第 0 步是先加载本技能，然后才动手。⛔ 没有"我大概知道"这条捷径。**
|
||||
|
||||
**触发句（命中任一条即须加载）**：`使用项目会话完成 X 目标`（🔴 **2026-10-08 用户令的现行写法** —— 原话「用法改为输入 使用项目会话完成目标：XXXXX」）／
|
||||
`使用任务会话完成 X 目标` ／ `使用执行会话完成 X 目标` ／ `继续 X 目标` ／
|
||||
**触发句（命中任一条即须加载）**：`使用任务会话完成 X 目标` ／ `使用执行会话完成 X 目标` ／ `继续 X 目标` ／
|
||||
`用执行会话完成 X` ／ `派任务会话` ／ `建任务会话` ／ 任何"让我去把某个目标做完/接着做"的表述。
|
||||
|
||||
**⛔ 禁止的三种"跳过理由"**（都真实发生过）：
|
||||
@@ -110,19 +109,9 @@ agent_created: true
|
||||
| 角色 | **谁创建它** | 它干什么 | 怎么停 |
|
||||
|---|---|---|---|
|
||||
| **主会话** | 用户手动开 | 管目标与方向、**派活** | 用户关窗 |
|
||||
| **项目会话**（🔴 **2026-10-08 用户令更名**；旧称**任务会话**，更旧称**执行会话**／协作会话） | 🔴 **派活产生** —— 主会话判缺口后登记自动化 → 宿主到点拉起（⛔ **不是常驻建的**） | 一棒一线、一次一件，做完即上报 | 做完自止 |
|
||||
| **任务会话**（旧称执行会话） | 🔴 **派活产生** —— 主会话判缺口后登记自动化 → 宿主到点拉起（⛔ **不是常驻建的**） | 一棒一线、一次一件，做完即上报 | 做完自止 |
|
||||
| **检查会话** | 🔴 **常驻程序** `collabd.py`（`maybe_spawn_check_agent()`，六道闸） | 核对结果／目标，缺口再派活 | 做完自止 |
|
||||
|
||||
> 🔴🔴 **术语更名（2026-10-08 用户令 · ⛔ 全包按本块读）**
|
||||
> 用户原话：「**把会话技能中 执行会话（协作会话）改为 项目会话**」＋「**用法改为输入 使用项目会话完成目标：XXXXX**」。
|
||||
> ⇒ **三个词指的是同一个角色**：**项目会话**（现行）＝ 任务会话（旧称）＝ 执行会话／协作会话（更旧称）。
|
||||
> · **新写的文字一律用「项目会话」**；读旧文碰到另两个词 ⇒ 就是它，⛔ 不必困惑、⛔ 也别改回去。
|
||||
> · 🔴 **机器前缀 `[执行]` 暂不变** —— 它是**角色解析与看板**的键（`parse_session_name` ／ `board.py::_role_of_title` ／
|
||||
> 在跑的排期名都靠它）⇒ 要不要连前缀一起改成 `[项目]`，属于影响面变更，**正在等用户拍板**。
|
||||
> · ⚠️ **全量更名尚未做完**（实测 **416 处 / 22 个文件**）—— 机制自己的规矩就是"改名不能盲替换"，按三类走：
|
||||
> ① 注释／文档 ⇒ 可直接改；② `selftest.py` 的 `@case` 标题 ⇒ 改了会断 `-k` 用例引用；③ 看板显示文案 ⇒ 用户可见、且带字面判据。
|
||||
> ⇒ **在那之前，本条口径就是唯一读法**（同 10-02 那次「旧正文按本块读」的做法）。
|
||||
|
||||
**三条线各归各的（⛔ 别混谈）**
|
||||
|
||||
1. **派活线**：主会话 → 任务会话。排期名 `[执行]-[<类别>]-<具体>`。🔴 **不受总开关影响**（开关只挡常驻）。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# manifest · 包内文件清单
|
||||
|
||||
> 生成方式：逐文件 `compile()` / `json.loads` ＋ md5 ｜ **最近一次全量重算：2026-10-08 22:11 （术语更名：执行会话／任务会话 ⇒ 项目会话（第一屏口径块 ＋ 触发词表））**
|
||||
> 生成方式：逐文件 `compile()` / `json.loads` ＋ md5 ｜ **最近一次全量重算：2026-10-08 22:22 （撤销误用的项目会话更名；说人话新稿按合并落地（141 处措辞替换））**
|
||||
> ⚠️ **2026-10-05 局部增量**：`references/pitfalls.md`（P0-77 拆条 ＋ P0-73/P0-77 压缩）与
|
||||
> `scripts/goalctl.py`（`--switch-goal` 确认闸 ＋ 旧目标归档）两行的 md5/大小已按当天实测值更新；**其余行仍是 10-04 基线**。
|
||||
> ⛔ 本表**不含** `install.log`（运行日志）与 `references/manifest.md`（自引用，写完即失真）。
|
||||
@@ -113,7 +113,7 @@
|
||||
|
||||
| 包内路径 | 字节 | md5 | 语法检查 |
|
||||
|---|---|---|---|
|
||||
| `SKILL.md` | 116169 | `951654aaebece3caab35caaf349ae98b` | — |
|
||||
| `SKILL.md` | 114635 | `c779fd78f61458b62cec99e9e103a4fc` | — |
|
||||
| `assets/board-launch.py.tpl` | 4355 | `7e9dfe1c4845f20dbb89f599d80e167b` | — |
|
||||
| `assets/board-render-probe.js` | 14398 | `a21bd1905b34537436ce778c6bfbc288` | — |
|
||||
| `assets/board.html` | 151811 | `c597cd7f21543542e9cdbe486c5ccd79` | — |
|
||||
@@ -171,7 +171,7 @@
|
||||
| `scripts/hooks/prompt-guards.py` | 9332 | `0aa1d1fdd2bf5a40cda2e60d7a785534` | ok |
|
||||
| `scripts/hooks/reply-style-guard.py` | 13200 | `e044f5d3e52ae94775dfba2090e7ae8e` | ok |
|
||||
| `scripts/hooks/session-log-guard.py` | 24636 | `4dd13b24d541d1afc7b4874dba6bb1eb` | ok |
|
||||
| `scripts/hooks/skill-load-guard.py` | 30517 | `332379fcd1edaff6794cfa994f664b30` | ok |
|
||||
| `scripts/hooks/skill-load-guard.py` | 29994 | `2450b93b4bac87cf9e99697703efa78f` | ok |
|
||||
| `scripts/hooks/stop-dialog-guard.py` | 51240 | `3e0791e42f41c37438601a9d2314dd8e` | ok |
|
||||
| `scripts/hooks/supervise-ensure-hook.py` | 14308 | `dc6f62584a8384baba0a1f2460828013` | ok |
|
||||
| `scripts/hooks/wb-result-hook.py` | 37199 | `2d4f694acd031222bf03b98a859b6e90` | ok |
|
||||
|
||||
@@ -148,10 +148,7 @@ TRIGGERS = (
|
||||
# · 「按规则来」族：用户没说"规则"，他说的是"会话技能里没告诉你自决策的规则嘛"（**反问**，含"规则"但那是质问不是点名）
|
||||
# ⇒ 结果：技能从未被强制加载 ⇒ 助手靠记忆干活 ⇒ 把"要不要建任务会话"当待拍板项反复问。
|
||||
# 🔴 教训：**词表只覆盖"点名方法论"，漏了"点名派活"** —— 而后者才是本技能的主入口。
|
||||
'使用项目会话', '使用任务会话', '使用执行会话', '使用协作会话',
|
||||
'项目会话完成', '任务会话完成', '执行会话完成',
|
||||
# 🔴 2026-10-08 用户令：**执行会话／任务会话 ⇒ 项目会话**（用法「使用项目会话完成目标：XXXXX」）。
|
||||
# ⛔ 三个词都留在词表里 —— 用户与新会话都可能用旧词，**收窄词表＝把已授权的触发句漏掉**（本项目栽过）。
|
||||
'使用任务会话', '使用执行会话', '使用协作会话', '任务会话完成', '执行会话完成',
|
||||
'继续完成目标', '继续目标', '继续完成之前', '继续之前的',
|
||||
'会话技能', '会话机制', '创建任务会话', '建任务会话',
|
||||
'派任务会话', '任务会话', '执行会话', '协作会话', '多会话',
|
||||
@@ -172,12 +169,10 @@ _LOAD_RULES = ('按规则来', '按规则做', '按作业规则', '遵守规则'
|
||||
# 🔴 为什么单列一族：这三族**目标技能不同**，⛔ 不能混在一个 if 里 ——
|
||||
# 命中"使用任务会话完成目标"的人，要的是**会话机制本体**（怎么建排期／怎么派活／
|
||||
# 自决策白名单在 `references/02-功能优先协作协议.md`），⛔ 不是决策方法论。
|
||||
_LOAD_SESSION = ('使用项目会话', '使用任务会话', '使用执行会话', '使用协作会话',
|
||||
'项目会话完成', '任务会话完成', '执行会话完成',
|
||||
_LOAD_SESSION = ('使用任务会话', '使用执行会话', '使用协作会话', '任务会话完成', '执行会话完成',
|
||||
'继续完成目标', '继续目标', '继续完成之前', '继续之前的',
|
||||
'会话技能', '会话机制', '创建任务会话', '建任务会话',
|
||||
'派任务会话', '任务会话', '执行会话', '协作会话', '多会话',
|
||||
'项目会话', '创建项目会话', '派项目会话') # 🔴 2026-10-08 加：见上
|
||||
'派任务会话', '任务会话', '执行会话', '协作会话', '多会话')
|
||||
|
||||
# 🔴🔴 2026-10-07 「点名族」＝ TRIGGERS 里**除派活族外的全部**（决策方法族 ＋ 作业规则/排版族）。
|
||||
# 用途：命中任意一个 ⇒ 写 `<ws>/.workbuddy/.load-pending` 待办，交给 `stop-dialog-guard.py`
|
||||
|
||||
Reference in new issue
Block a user