151 lines
12 KiB
Markdown
151 lines
12 KiB
Markdown
# 七阶段流水线细则
|
||
|
||
SKILL.md 是路由，本文是执行手册。每阶段给出：输入 → 动作（含确切命令）→ 产物 → 验收。命令中 `<SKILL>` = le-app-design 目录，`<RUN>` = 本次运行目录，`<DEP_UIUX>` / `<DEP_FD>` / `<DEP_IMP>` = S0 解析出的三个上游路径（读 `<RUN>/deps.json` 的 `deps.*.path`）。
|
||
|
||
## S0 依赖门
|
||
|
||
**动作**
|
||
```bash
|
||
mkdir -p <RUN>
|
||
python3 <SKILL>/scripts/check_deps.py --out <RUN>/deps.json
|
||
```
|
||
|
||
**验收**：exit 0 且 deps.json 的 `ok=true`。任一依赖 `alive=false` → 向用户输出缺失项、原因（`check` 字段）与安装指引（`install` 字段），**终止运行**。deps.json 是后续所有阶段的路径来源，不要手写上游路径。
|
||
|
||
## S1 产品理解
|
||
|
||
**动作**：从用户输入提炼并写 `<RUN>/BRIEF.md`，包含：
|
||
|
||
- 产品：一句话说清这是什么、解决什么
|
||
- 受众与场景：谁、在什么场景用（决定 impeccable 模式与 frontend-design 的取材世界）
|
||
- 核心任务：用户打开它要完成的最重要 1–3 件事
|
||
- 平台形态：移动 Web（默认 390×844）/ 桌面 / 响应式；明确「Web 高保真原型」是交付形态
|
||
- 模式归属：Persuade / Operate / Read / Experience 四选一（impeccable 按表面而非产品选模式：App 内页=Operate，落地页=Persuade，阅读页=Read，作品展示=Experience）
|
||
- 范围：本次做哪些屏/页面，明确排除什么
|
||
|
||
信息不足且**影响方向**才问用户（用结构化选项，别开放式问卷）；否则写明「假设：…」直接做。多次触达同一项目时先读已有 BRIEF.md，增量更新而非重写。
|
||
|
||
**验收**：BRIEF.md 落盘，模式归属有理由。
|
||
|
||
## S2 视觉探索 — frontend-design（方向先行）
|
||
|
||
**动作**
|
||
1. 宿主有 Skill 工具 → 调它装载 `frontend-design`；没有 → Read `<DEP_FD>/SKILL.md` 全文（两路等价，装载即调用）。
|
||
2. 立即记账：`python3 <SKILL>/scripts/log_call.py frontend-design --run-dir <RUN> --note S2-load --load <DEP_FD>/SKILL.md`
|
||
3. 以其「设计总监」立场产出 `<RUN>/design-plan.md`：
|
||
- **题材世界**：从产品自己的世界取材（subject matter 是差异化来源），写明方向一句话
|
||
- **色板**：4–6 个具名 hex（`--纸面 #FDFDF8` 式命名）
|
||
- **字体**：选型 + 角色，说明为何不是默认脸
|
||
- **布局**：一句话概念 + 每屏 ASCII 线框 + 对齐策略
|
||
- **原则**：这个产品独有的 3–5 条
|
||
- **两遍法第二遍**：对照其「AI 味特征清单」逐条自检；发现默认味 → 写明改了什么、为什么
|
||
4. （可选调研模式）方向成形前可用 pro-max `--domain style|color|typography` 检索选项当情绪板（记账 note=S2-research）——**只供参考不做决定**，此阶段禁止 `--design-system`。
|
||
|
||
**验收**：design-plan.md 四要素齐全 + 自检一节存在 + 记账在案；方向不来自品类匹配。
|
||
|
||
## S3 设计规范 — ui-ux-pro-max（系统后行）
|
||
|
||
**动作**：把已定方向编撰成规范 + 硬约束校验：
|
||
|
||
```bash
|
||
# 主调用：用方向关键词（不是品类词）驱动系统生成；dials 按方向调
|
||
python3 <SKILL>/scripts/log_call.py ui-ux-pro-max --run-dir <RUN> --note S3-design-system -- \
|
||
python3 <DEP_UIUX>/scripts/search.py "<方向关键词>" --design-system --persist \
|
||
-p "<项目名>" --output-dir <项目根> [--variance N --motion N --density N]
|
||
|
||
# 硬约束校验（按需，全部记账）：对比度/触控/排版/相关 UX 规则
|
||
python3 <SKILL>/scripts/log_call.py ui-ux-pro-max --run-dir <RUN> --note S3-ux-check -- \
|
||
python3 <DEP_UIUX>/scripts/search.py "<如 contrast touch target>" --domain ux
|
||
```
|
||
|
||
**两条规则**：
|
||
- **硬约束否决权**：frontend-design 定的 hex/字号若不达标（WCAG/HIG/MD 数据为准），**改值不改方向**；每处修改记入 design-plan 决策记录。
|
||
- **目录回弹降级（操作化判据）**：生成结果命中以下任意两条即判回弹、不采用该 MASTER——①Style 名与方向关键词无词面或语义关联（如「练习本手写」→ Swiss/Helvetica）；②色板命中 AI-tell 家族（暖奶油底、默认靛蓝/紫系、近黑+酸绿）且与 design-plan 色板无共享主色；③关键 Effects/Anti-patterns 与方向的手感相反（如手绘方向得到 corporate/rational）。降级后：design-plan 的 token 表即规范 + pro-max 逐项校验补硬约束，决策记录写明命中哪两条。方向的独特性优先于系统的便利性。
|
||
|
||
**验收**：MASTER.md 存在且与方向一致，或降级路径已记录；校验检索在账本；design-plan 决策记录含 S3 的改值/降级条目。
|
||
|
||
## 停点 1
|
||
|
||
把 BRIEF（要点）、design-plan（方向 + ASCII + 色板 + 原则）、MASTER 要点或 S3 降级说明展示给用户，明确请求确认或调整意见，**终止回合**。用户豁免（已说「一口气跑完」）→ 跳过继续。
|
||
|
||
## S4 高保真构建（a 首屏 → 停点 1.5 → b 全量）
|
||
|
||
**S4a 首屏**
|
||
1. Read `<DEP_IMP>/reference/craft-floor.md` 并记账：
|
||
`python3 <SKILL>/scripts/log_call.py impeccable --run-dir <RUN> --note S4-craft-floor --load <DEP_IMP>/reference/craft-floor.md`
|
||
2. 只构建**主界面一屏**（真实内容 + 规范 tokens + design-plan 个性），390×844 截一张。
|
||
|
||
**停点 1.5（首屏确认）**：截图发到对话请用户确认方向落地；豁免时跳过停顿但截图必须发出。**终止回合**；这一站是「盲盒阀门」——成品首见从 S5 之后提前到构建开头。
|
||
|
||
**S4b 全量**
|
||
1. 构建：默认无构建链的 HTML/CSS/JS（单文件优先，可拆 CSS/JS 文件）。硬性要求：
|
||
- token 来自 MASTER.md（或降级时的 design-plan token 表），不发明规范之外的美学量
|
||
- 布局与个性按 design-plan；SVG 图标（真图标库或手绘一致笔画），禁 emoji 图标
|
||
- craft-floor 全条目施工时遵守（尤其：eyebrow 是 ban；嵌套卡片必错；elevation 声明一次；浏览器表面——selection/caret/scrollbar/focus ring/表格数字——从色板定制）
|
||
- 交互真实可用（点击/切换/滚动行为写 JS），不是静态画片
|
||
- pro-max Pre-Delivery 逐条过：44px 触控、4.5:1 对比、focus ring、reduced-motion、375px 无横滚
|
||
2. 截图口径（统一）：**390×844 主档 + 375 兼容档各至少一张**；移动 Web 任务免桌面档（body 居中列已保证桌面不破）。按 craft-floor「一次看一批」：Read 截图找问题 → 修完一批 → 再截。编排器无法亲验截图图像时，交 S5 Assessment A 首个看图。
|
||
3. **显隐与布局断言用渲染事实（computed display / getBoundingClientRect），不信 hidden 属性**——id/类选择器的 display 会压过 [hidden]（实测翻车：两页堆叠渲染而属性检查全绿）。
|
||
|
||
**验收**：原型可打开（`file://` 直开无 console error 级问题）、双档截图在 `<RUN>/`、craft-floor 关键项肉眼过。
|
||
|
||
## S5 设计审查 — impeccable
|
||
|
||
**动作**
|
||
1. 上下文装载：
|
||
```bash
|
||
python3 <SKILL>/scripts/log_call.py impeccable --run-dir <RUN> --note S5-context -- \
|
||
sh <DEP_IMP>/scripts/impeccable context --target <原型主文件>
|
||
```
|
||
按 context 输出的指令行事（它可能要求 init/PRODUCT.md——轻量原型按其 SCOPED_EXISTING_ALLOWED 通道走，不阻塞）。
|
||
2. Read `<DEP_IMP>/reference/critique.md` 并记账（`--load`）。**按 critique.md 原文执行**，特别注意其 Hard Invariants：
|
||
- 双独立 sub-agent：Assessment A（设计评审）/ Assessment B（detect + 浏览器证据）。ZCode/Claude Code 用 Agent 工具并行派发，两者互不可见对方输出；Codex 有 spawn_agent 先问一次；都没有才单上下文顺序跑并打 `⚠️ DEGRADED` 横幅
|
||
- **派发模板要点**（子代理看不到主上下文，prompt 必须自带全部材料）：
|
||
- A 传：目标文件路径、BRIEF/design-plan 路径、全部截图路径（要求「真正看图」）、四模式与受众摘要、输出契约（specificity/十启发式表/认知负荷/情绪/P0-P3/persona）
|
||
- B 传：经 log_call 包裹的 detect 命令全文（注明 exit 0=clean / 2=findings 属成功）、截图清点、误报核对要求（对源码实算）、fallback signal 原文案
|
||
- B 的 CLI 扫描：
|
||
```bash
|
||
python3 <SKILL>/scripts/log_call.py impeccable --run-dir <RUN> --note S5-detect -- \
|
||
sh <DEP_IMP>/scripts/impeccable detect --json <原型目录或主文件>
|
||
```
|
||
（exit 0=clean，2=有 findings；只传 markup 文件）
|
||
- 浏览器证据：无浏览器自动化时用 headless Chrome 截图代替并在 Run Notes 声明 fallback
|
||
- 快照持久化 + trend：按 critique.md 的 `critique-storage write/trend` 执行并记账
|
||
3. 出完整报告：方法横幅、启发式评分表（0–4 ×10，适用 max 规范化）、Design Specificity、P0–P3 优先问题、persona 红旗、Run Notes。
|
||
|
||
**验收**：报告完整落 `<RUN>/critique-report.md`（同时按 critique.md 在聊天中交付全文）、detect 结果在账本、快照已写（或记明原因）。
|
||
|
||
## 停点 2
|
||
|
||
展示审查报告**并附修复前后关键截图**，四选一：全部 / Top 3 / 仅 P0–P1 / 保持现状（跳过 S6 直接 S7，报告照出）。**终止回合**；豁免规则同停点 1（豁免时默认修 P0+P1，并在审查报告末尾补字面行 `Questions skipped: 停点2经用户豁免（默认修复 P0+P1）`，满足 impeccable critique 的收尾契约）。
|
||
|
||
## S6 优化迭代
|
||
|
||
**动作**：按用户选定范围修（P0/P1 无用户明示保留也必修）→ 复跑 detect（记账，note=S6-redetect）至 exit 0（=0 findings；残留项逐一记明理由）→ 复截图核对修复效果。修复遵守 S4 的同一套约束（token/设计/craft-floor），不许「修着修着」脱离体系。
|
||
|
||
**验收**：detect 清零或残留有据；前后截图对比留档 `<RUN>/`。
|
||
|
||
## S7 交付 + 验收门
|
||
|
||
**动作**
|
||
```bash
|
||
# 完整流程：默认三方门，pro-max 计履职前缀（S2-research 不混门）
|
||
python3 <SKILL>/scripts/evidence_report.py --run-dir <RUN> \
|
||
--out <RUN>/INTEGRATION-REPORT.md --title "<项目代号> 集成证据" \
|
||
--require "ui-ux-pro-max:S3-,frontend-design:S2-,impeccable" \
|
||
--artifact <原型主文件> --artifact <RUN>/shot-<主档>.png --artifact <RUN>/design-plan.md
|
||
# 仅审查路由：--require "impeccable"；局部修改：--require "impeccable[,frontend-design]"
|
||
# 系统路径（非降级）另加 --artifact design-system/<slug>/MASTER.md；
|
||
# slug 由上游按 -p 项目代号生成（小写连字符），跑完 S3 用 ls design-system/ 确认实际目录名
|
||
```
|
||
|
||
向用户交付：原型入口（`file://` 路径，可交互）、关键截图、INTEGRATION-REPORT 判定与调用统计、审查分数与修复摘要、运行目录索引。**FAIL 时不宣称完成**，把缺口（哪个门没过/哪个产物缺失）说清楚。
|
||
|
||
## 全程通用约束
|
||
|
||
- **note 命名规范**（验收门的履职前缀依赖它）：`S2-load`（frontend-design 装载）、`S2-research`（可选调研，不计入门）、`S3-design-system` / `S3-ux-check` / `S3-typography-check`（pro-max 履职）、`S4-craft-floor`、`S5-context` / `S5-critique-playbook` / `S5-detect`、`S6-redetect`。
|
||
- 每次对上游的调用都过 `log_call.py`，`--run-dir` 显式传（缺省会另建 `<时间戳>-run` 目录，账本裂成两份、验收门读空账本 FAIL）；失败调用也要留痕。
|
||
- 不修改三个上游目录的任何文件；PYTHONDONTWRITEBYTECODE 已由脚本注入。
|
||
- 运行目录是本次任务的唯一工作痕迹区：BRIEF / design-plan / 截图 / 报告全进 `<RUN>`；MASTER.md 在项目根（上游约定位置，slug 跑完 S3 后 `ls design-system/` 确认实际目录名）。
|
||
- 用户豁免只作用于停点，不作用于铁律与验收门；豁免停点 1.5 时首屏截图仍须发出。
|