le-app-design v1.0.0：统一 App 设计工坊——真实集成并调用三上游的编排器。ui-ux-pro-max（MIT，search.py 设计系统/规范检索）+ frontend-design（Apache-2.0，Skill 工具装载的视觉 design lead）+ impeccable（Apache-2.0，CLI 检测器+playbook 审查）；三机制保证真集成可验证：check_deps 硬依赖门（缺即终止）、log_call 证据账本（调用落 calls.jsonl 含装载 sha256）、evidence_report 验收门（三方各 ≥1 成功调用才 PASS）；S0–S7 流水线含两个回合终止停点与轻量任务路由；E2E 已真跑（习惯打卡 App 双屏原型）：7 条真实调用留账、双独立 sub-agent 评审 26/36 + detect 2 findings、修复 3×P1 后字阶清零、交互复测 4/4、验收门 PASS；上游三件补装 ~/.codex/skills，仓库 README 同步
This commit is contained in:
leroy
@@ -0,0 +1,142 @@
|
||||
# 七阶段流水线细则
|
||||
|
||||
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 设计规范 — ui-ux-pro-max
|
||||
|
||||
**动作**
|
||||
```bash
|
||||
# 主调用：生成并持久化设计系统（MASTER.md 是后续 token 的唯一来源）
|
||||
python3 <SKILL>/scripts/log_call.py ui-ux-pro-max --run-dir <RUN> --note S2-design-system -- \
|
||||
python3 <DEP_UIUX>/scripts/search.py "<产品类型> <行业> <2-3 风格关键词>" \
|
||||
--design-system --persist -p "<项目名>" --output-dir <项目根>
|
||||
|
||||
# 定向补充（按需，每次独立记账）：
|
||||
python3 <SKILL>/scripts/log_call.py ui-ux-pro-max --run-dir <RUN> --note S2-ux -- \
|
||||
python3 <DEP_UIUX>/scripts/search.py "<关注点，如 bottom nav touch target>" --domain ux
|
||||
python3 <SKILL>/scripts/log_call.py ui-ux-pro-max --run-dir <RUN> --note S2-stack -- \
|
||||
python3 <DEP_UIUX>/scripts/search.py "<实现关键词>" --stack html-tailwind
|
||||
```
|
||||
|
||||
遵守上游 Query Contract：一次查询一个主导意图、2–5 个有效词；结果空/跑题重试一次更窄的写法，再不行如实说「无验证匹配」。
|
||||
|
||||
**产物**：`<项目根>/design-system/<slug>/MASTER.md`（+ 查询输出摘要）。
|
||||
|
||||
**验收**：MASTER.md 存在且 calls.jsonl 有 exit=0 的 S2 记录。已有 MASTER.md 时上游默认跳过覆盖——读它再决定是否需要 `--force`（须用户同意）。
|
||||
|
||||
## S3 视觉探索 — frontend-design
|
||||
|
||||
**动作**
|
||||
1. 宿主有 Skill 工具 → 调它装载 `frontend-design`；没有 → Read `<DEP_FD>/SKILL.md` 全文（两路等价，后者不是降级——装载即调用）。
|
||||
2. 立即记账：`python3 <SKILL>/scripts/log_call.py frontend-design --run-dir <RUN> --note S3-load --load <DEP_FD>/SKILL.md`
|
||||
3. 以其「设计总监」立场产出 `<RUN>/design-plan.md`：
|
||||
- **色板**：4–6 个具名 hex（`--bg-deep #0E1B2C` 这样命名）
|
||||
- **字体**：选型 + 各自角色（display/body/数字…），说明为何不是默认脸
|
||||
- **布局**：一句话概念 + 每屏 ASCII 线框 + 对齐策略
|
||||
- **原则**：这个产品独有的 3–5 条，从题材世界取材（frontend-design：subject matter 是差异化来源）
|
||||
- **两遍法第二遍**：对照其「AI 味特征清单」（cream+terracotta、暗底酸绿、报纸 hairline、SaaS 卡片套件、eyebrow/中点连接串等）逐条自检；发现默认味 → 写明改了什么、为什么
|
||||
- **决策记录**：与 MASTER.md 的冲突及裁决（按 SKILL.md 裁决表：a11y/触控/平台规则 pro-max 赢；美学自由轴 frontend-design 赢；craft-floor ban 红线）
|
||||
|
||||
**验收**：design-plan.md 四要素齐全 + 自检一节存在 + 记账在案。
|
||||
|
||||
## 停点 1
|
||||
|
||||
把 BRIEF（要点）、MASTER（风格/色/字/反模式摘要）、design-plan（ASCII + 色板 + 原则 + 决策记录）展示给用户，明确请求确认或调整意见，**终止回合**。用户豁免（已说「一口气跑完」）→ 跳过继续。
|
||||
|
||||
## S4 高保真构建
|
||||
|
||||
**动作**
|
||||
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. 构建：默认无构建链的 HTML/CSS/JS（单文件优先，可拆 CSS/JS 文件）。硬性要求：
|
||||
- token 全部来自 MASTER.md（色/字/间距/圆角/阴影），不发明 system 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 无横滚
|
||||
3. 截图核对（headless Chrome，找不准路径先 `ls /Applications | grep -i chrome`）：
|
||||
```bash
|
||||
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
|
||||
--headless=new --disable-gpu --screenshot=<RUN>/shot-mobile.png \
|
||||
--window-size=390,844 file://<绝对路径>
|
||||
```
|
||||
移动 390×844 + 桌面 1440×900 至少各一张；按 craft-floor「一次看一批」：Read 截图找问题 → 修完一批 → 再截。
|
||||
|
||||
**验收**：原型可打开（`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` 横幅
|
||||
- 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 / 保持现状。**终止回合**；豁免规则同停点 1（豁免时默认修 P0+P1）。
|
||||
|
||||
## S6 优化迭代
|
||||
|
||||
**动作**：按用户选定范围修（P0/P1 无用户明示保留也必修）→ 复跑 detect（记账，note=S6-redetect）至 exit 0（=0 findings；残留项逐一记明理由）→ 复截图核对修复效果。修复遵守 S4 的同一套约束（token/设计/craft-floor），不许「修着修着」脱离体系。
|
||||
|
||||
**验收**：detect 清零或残留有据；前后截图对比留档 `<RUN>/`。
|
||||
|
||||
## S7 交付 + 验收门
|
||||
|
||||
**动作**
|
||||
```bash
|
||||
python3 <SKILL>/scripts/evidence_report.py --run-dir <RUN> \
|
||||
--out <RUN>/INTEGRATION-REPORT.md --title "<任务名> 集成证据" \
|
||||
--artifact <原型主文件> --artifact <RUN>/shot-mobile.png \
|
||||
--artifact <项目根>/design-system/<slug>/MASTER.md --artifact <RUN>/design-plan.md
|
||||
```
|
||||
|
||||
向用户交付：原型入口（`file://` 路径，可交互）、INTEGRATION-REPORT 判定与三方统计、审查分数与修复摘要、运行目录索引。**FAIL 时不宣称完成**，把缺口（哪个上游 0 成功调用/哪个产物缺失）说清楚。
|
||||
|
||||
## 全程通用约束
|
||||
|
||||
- 每次对上游的调用都过 `log_call.py`，`--note` 标阶段（S2-design-system / S5-detect…），失败调用也要留痕。
|
||||
- 不修改三个上游目录的任何文件；PYTHONDONTWRITEBYTECODE 已由脚本注入。
|
||||
- 运行目录是本次任务的唯一工作痕迹区：BRIEF / design-plan / 截图 / 报告全进 `<RUN>`；MASTER.md 在项目根（上游约定位置）。
|
||||
- 用户豁免只作用于停点，不作用于铁律与验收门。
|
||||
@@ -0,0 +1,29 @@
|
||||
# 跨 Runtime 适配
|
||||
|
||||
CLI 调用（check_deps / log_call / 上游两个 CLI）在所有 runtime 完全一致——它们只依赖 python3 与 sh。差异只在两处：frontend-design 怎么装载、critique 的双 sub-agent 怎么派。
|
||||
|
||||
## 适配矩阵
|
||||
|
||||
| Runtime | frontend-design 装载 | critique 双评审 | 备注 |
|
||||
|---|---|---|---|
|
||||
| ZCode | Skill 工具（首选）或 Read 原文 | Agent 工具并行派 A/B 两个子代理 | 全功能路径，E2E 验证即在此环境跑 |
|
||||
| Claude Code | Skill 工具（首选）或 Read 原文 | Task/Agent 工具并行派 A/B | 同上 |
|
||||
| Codex | Read 原文全文（一等路径） | 有 `spawn_agent`：按 critique.md 的 Codex 门**先问用户一次**再派；无则顺序跑 + `⚠️ DEGRADED` 横幅 | 上游需先装进 `~/.codex/skills/`（见 README） |
|
||||
| OpenCode | Read 原文全文（一等路径） | 有 sub-agent 工具就派，无则降级横幅 | 同 Codex 逻辑 |
|
||||
| MausBot / 其它 | Read 原文全文（一等路径） | 无 sub-agent 则降级横幅 | 限制：见下 |
|
||||
|
||||
「一等路径」的含义：frontend-design 是纯指导型 Skill，官方机制就是把它的 SKILL.md 全文装进执行上下文并照做。Read 原文 + `log_call.py --load` 记 sha256，与 Skill 工具装载等效且可审计——**不是降级**。降级只发生在 critique 的双评审（impeccable 自己的定义，见其 critique.md Hard Invariants）。
|
||||
|
||||
## 已知限制（如实告知用户，不静默吞掉）
|
||||
|
||||
1. **impeccable detect 只读 web markup**（HTML/JSX 等）。原生 Swift/Kotlin 源码扫不出东西——纯原生方案 critique 走 Assessment A 单评审（这是上游定义的完整方法，非降级）。本 Skill 交付形态固定为 Web 高保真原型，不受影响。
|
||||
2. **impeccable 二进制按平台分发**（本机 darwin-arm64 已带）。换机器跑 check_deps 会立刻发现缺 `scripts/impeccable` 或其 bin/ 子目录——按报告里的安装指引处理；上游 README 说明二进制会在首跑时按平台下载。
|
||||
3. **截图依赖本机 Chrome**。找不到时 S4/S5 的截图核对降级为 craft-floor 逐条人工核对 + 在 INTEGRATION-REPORT 的 Run Notes 声明，不静默跳过。
|
||||
4. **Windows**：impeccable 用 `scripts/impeccable.cmd`，python3 可能叫 `python`——check_deps/liveness 若失败按报告指引调整；其余逻辑不变。
|
||||
5. **上游版本漂移**：check_deps 记录的是路径 + 活性，不锁版本。上游大版本更新导致 playbook 接口变化时（如 critique.md 的命令名变了），S5 会暴露失败——按失败模式处理并报告，不猜测新接口。
|
||||
|
||||
## 路径解析优先级（check_deps 的顺序）
|
||||
|
||||
`$LE_APP_DESIGN_DEP_ROOTS`（冒号分隔，自定义安装位）→ `~/.agents/skills`（首选默认，与 impeccable SKILL.md 自引用路径一致）→ `~/.zcode/skills` → `~/.codex/skills` → `~/.claude/skills`。
|
||||
|
||||
同一机器多份副本时取优先级最高的一份并在 deps.json 记录实际路径；S2/S5 的命令一律用该路径，不硬编码。
|
||||
Reference in New Issue
Block a user