@openprd/cli 0.1.10 → 0.1.18

package/skills/openprd-diagram-review/references/explanation-svg-patterns.md

@@ -0,0 +1,131 @@
+# Explanation SVG Patterns
+
+## Purpose
+
+Use explanation SVGs when the user needs to understand a relationship before they need a formal artifact. These diagrams are optimized for comprehension in the conversation, not for approval gates.
+
+An explanation SVG should reduce text. The preferred shape is:
+
+1. One sentence conclusion
+2. One compact SVG
+3. Up to three short notes or open questions
+
+## When To Use
+
+Use an explanation SVG for:
+
+- state transitions
+- before / after comparisons
+- current state to target state paths
+- cause and effect chains
+- responsibility or boundary splits
+- risk propagation
+- decision trees
+- trade-off comparisons
+- requirement scenarios with multiple actors or steps
+
+Do not use an explanation SVG for:
+
+- a single factual answer
+- exact command output or error text
+- legal, security, or compliance wording that must be precise
+- proof of implementation
+- visual acceptance evidence
+- formal PRD review sign-off
+
+## Visual Grammar
+
+- Keep the canvas compact, usually 900 to 1200 px wide.
+- Use 2 to 5 main nodes.
+- Put short labels inside nodes; keep supporting text outside the SVG.
+- Use arrows to show direction, not paragraphs.
+- Use dashed outlines for scope or uncertainty.
+- Use muted gray for background or irrelevant history.
+- Use green/teal for target, current, or healthy path.
+- Use amber/red only for risk, blockage, or failure.
+- Keep labels in the user's language. For zh-CN, use Simplified Chinese.
+
+## Pattern Library
+
+### Two-Side Comparison
+
+Use when explaining why two approaches feel different.
+
+```svg
+<svg viewBox="0 0 980 360" role="img" aria-label="两种方案对比">
+  <rect x="24" y="28" width="440" height="290" rx="18" fill="#f8fafc" stroke="#cbd5e1" stroke-dasharray="8 6"/>
+  <rect x="516" y="28" width="440" height="290" rx="18" fill="#ecfdf5" stroke="#14b8a6" stroke-dasharray="8 6"/>
+  <text x="52" y="76" font-size="24" font-weight="700" fill="#1f2937">文字优先</text>
+  <text x="544" y="76" font-size="24" font-weight="700" fill="#065f46">图解优先</text>
+  <rect x="76" y="132" width="280" height="76" rx="12" fill="#fff7ed" stroke="#fdba74"/>
+  <text x="216" y="164" text-anchor="middle" font-size="20" font-weight="700" fill="#7c2d12">先解释很多概念</text>
+  <text x="216" y="192" text-anchor="middle" font-size="16" fill="#9a3412">用户自己拼结构</text>
+  <rect x="568" y="132" width="280" height="76" rx="12" fill="#d1fae5" stroke="#10b981"/>
+  <text x="708" y="164" text-anchor="middle" font-size="20" font-weight="700" fill="#065f46">先看到关系</text>
+  <text x="708" y="192" text-anchor="middle" font-size="16" fill="#047857">文字只补结论</text>
+  <path d="M356 170 H568" stroke="#64748b" stroke-width="3" marker-end="url(#arrow)"/>
+  <defs>
+    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L0,6 L9,3 z" fill="#64748b"/>
+    </marker>
+  </defs>
+</svg>
+```
+
+### State Transition
+
+Use when explaining how the current state moves to a future state, and whether history matters.
+
+```svg
+<svg viewBox="0 0 1080 360" role="img" aria-label="状态转移说明">
+  <rect x="34" y="40" width="1012" height="250" rx="22" fill="#ffffff" stroke="#cbd5e1" stroke-dasharray="8 6"/>
+  <rect x="90" y="130" width="230" height="88" rx="14" fill="#f1f5f9" stroke="#cbd5e1"/>
+  <text x="205" y="164" text-anchor="middle" font-size="21" font-weight="700" fill="#64748b">过去状态</text>
+  <text x="205" y="194" text-anchor="middle" font-size="16" fill="#94a3b8">不一定重要</text>
+  <rect x="424" y="130" width="230" height="88" rx="14" fill="#ccfbf1" stroke="#14b8a6"/>
+  <text x="539" y="164" text-anchor="middle" font-size="21" font-weight="700" fill="#0f766e">当前状态</text>
+  <text x="539" y="194" text-anchor="middle" font-size="16" fill="#0f766e">决策起点</text>
+  <rect x="758" y="130" width="230" height="88" rx="14" fill="#dcfce7" stroke="#22c55e"/>
+  <text x="873" y="164" text-anchor="middle" font-size="21" font-weight="700" fill="#166534">未来状态</text>
+  <text x="873" y="194" text-anchor="middle" font-size="16" fill="#15803d">下一步结果</text>
+  <path d="M320 174 H424" stroke="#cbd5e1" stroke-width="3" marker-end="url(#mutedArrow)"/>
+  <path d="M654 174 H758" stroke="#0f766e" stroke-width="5" marker-end="url(#greenArrow)"/>
+  <text x="706" y="214" text-anchor="middle" font-size="17" fill="#0f766e">关键转移</text>
+  <defs>
+    <marker id="mutedArrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L0,6 L9,3 z" fill="#cbd5e1"/>
+    </marker>
+    <marker id="greenArrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L0,6 L9,3 z" fill="#0f766e"/>
+    </marker>
+  </defs>
+</svg>
+```
+
+### Boundary Map
+
+Use when explaining what belongs in scope, what is adjacent, and what remains outside.
+
+```svg
+<svg viewBox="0 0 980 420" role="img" aria-label="范围边界说明">
+  <rect x="46" y="44" width="888" height="310" rx="24" fill="#f8fafc" stroke="#94a3b8" stroke-dasharray="9 7"/>
+  <text x="76" y="90" font-size="24" font-weight="700" fill="#334155">本次范围</text>
+  <rect x="120" y="142" width="220" height="92" rx="14" fill="#dbeafe" stroke="#3b82f6"/>
+  <text x="230" y="178" text-anchor="middle" font-size="20" font-weight="700" fill="#1d4ed8">核心问题</text>
+  <text x="230" y="207" text-anchor="middle" font-size="16" fill="#2563eb">必须解决</text>
+  <rect x="380" y="142" width="220" height="92" rx="14" fill="#dcfce7" stroke="#22c55e"/>
+  <text x="490" y="178" text-anchor="middle" font-size="20" font-weight="700" fill="#166534">可执行动作</text>
+  <text x="490" y="207" text-anchor="middle" font-size="16" fill="#15803d">这轮落地</text>
+  <rect x="640" y="142" width="220" height="92" rx="14" fill="#fff7ed" stroke="#f59e0b"/>
+  <text x="750" y="178" text-anchor="middle" font-size="20" font-weight="700" fill="#92400e">开放问题</text>
+  <text x="750" y="207" text-anchor="middle" font-size="16" fill="#b45309">需要确认</text>
+  <text x="490" y="300" text-anchor="middle" font-size="18" fill="#64748b">边界外内容只记录，不混成本次失败</text>
+</svg>
+```
+
+## Copy Rules
+
+- The sentence before the diagram should state the takeaway, not repeat every label.
+- The notes after the diagram should explain only what the user must decide or notice.
+- Avoid file names, function names, raw route codes, schema names, and internal gate names unless the user asked for implementation detail.
+- Do not hide uncertainty inside the diagram. Use "待确认" or a dashed node when a claim is inferred.

package/skills/openprd-discovery-loop/SKILL.md

@@ -173,8 +173,8 @@ hook harness 还会写入：
 
 - 使用 `openprd tasks <path> --change <id>` 查看进度和下一个依赖已满足的任务
 - 当某项任务已经可以通过自己的 `verify` 命令完成时，使用 `openprd tasks <path> --change <id> --advance --verify --item <task-id>`
-- 使用 `openprd change <path> --apply --change <id>` 把完成的 change specs 推进到 `openprd/specs`
-- 使用 `openprd change <path> --archive --change <id>` 把完成的 change 文件移动到 `openprd/archive/changes`
+- 使用 `openprd change <path> --apply --change <id>` 把完成的 change specs 推进到 `.openprd/specs`
+- 使用 `openprd change <path> --archive --change <id>` 把完成的 change 文件移动到 `.openprd/archive/changes`
 - 当任务或 discovery pass 改动了基线文档、文件说明书或文件夹 README 时，运行 `openprd standards <path> --verify`
 - 在声明单个任务完成前，运行本任务最小足够验证并留下 evidence；在阶段收口或声明整体实现就绪前，运行 `openprd quality <path> --verify`；当某个已验证修复应该沉淀为项目级复用经验时，运行 `openprd quality <path> --learn --from <report>`
 - 如果任务被依赖阻塞，先完成更早的任务 id；不要人工跳过依赖顺序

package/skills/openprd-frontend-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openprd-frontend-design
-description: 为 OpenPrd 的界面、页面、视觉、样式和前端体验任务提供设计资产框架、前置门禁和实现前方向评审规则。
+description: 为 OpenPrd 的界面、页面、视觉、样式和前端体验任务提供设计资产框架、审美立意、反 AI 味门禁和实现前方向评审规则。
 ---
 
 # OpenPrd Frontend Design
@@ -12,11 +12,14 @@ description: 为 OpenPrd 的界面、页面、视觉、样式和前端体验任
 - 让 Agent 在动手实现前，先有一套稳定的前端设计资产和判断顺序。
 - 避免界面任务默认收敛成同一种安全解。
 - 避免“没素材硬做”“事实没核实就写页面”“看起来好看但空心”的情况。
+- 让每个界面先有明确审美主张和记忆点，而不是只套默认模板、堆卡片或复用通用 AI 风格。
 
 ## 先读这些文件
 
 - `.openprd/design/README.md`
 - `.openprd/design/templates/README.md`
+- `skills/openprd-frontend-design/references/design-asset-contract.md`
+- `skills/openprd-frontend-design/references/direction-engine.md`
 
 如果当前工作区本来就有现成前端结构，或你明确需要偏离模板默认组合，再读：
 
@@ -39,16 +42,17 @@ description: 为 OpenPrd 的界面、页面、视觉、样式和前端体验任
 
 1. 先判断这是不是前端体验任务。
 2. 选一个 `lens`，明确这次界面的视觉判断角度。
-3. 选一个 `theme`、一个 `layout skeleton` 和一个 `recipe`。
-4. 如果页面会写具体产品事实，先补 `facts-sheet.md`。
-5. 如果页面依赖品牌素材、产品图、界面图、图库或插图，先补 `asset-spec.md`。
-6. 如果这类页面没有真实图片就会空心，先补 `image-preflight.md`。
-7. 如果用户还没有给参考方向，先补 `direction-plan.md`，明确 3 个异源方向。
-8. 用户选定方向后，再补 `selected-direction.md`，把选中的 lens、theme、layout、组件和风险锁定。
-9. 如果用户已经给了效果图、设计稿、参考截图或其他明确参考图，先把它视为主参考源：优先锁定它的版式、层级、主视觉和关键路径；`starter / lens / theme / layout` 只作为实现加速器，不作为高于参考图的裁决源。
-10. 如果当前是空白工作区的前端/页面冷启动，而且用户原话已经给了明确的页面主题、模块范围或“直接实现”的意图，优先运行 `openprd run . --context --message <用户原话>`，不要先跑不带 message 的 `run --context`。
-11. 跑完 `design-starter` 后，立即进入 `Patch Mode`：把生成的入口文件当成稳定基座，在同一路径里细化结构、内容、样式和交互。
-12. 最后再进入验证，并用 `.openprd/design/checklists/ui-quality-gate.md` 做自检。
+3. 写清本次审美立意：页面解决什么问题、服务谁、气质要偏哪一端、受什么技术/可访问性约束、用户第一眼应该记住什么。
+4. 选一个 `theme`、一个 `layout skeleton` 和一个 `recipe`，并说明它们如何服务上面的审美立意。
+5. 如果页面会写具体产品事实，先补 `facts-sheet.md`。
+6. 如果页面依赖品牌素材、产品图、界面图、图库或插图，先补 `asset-spec.md`，并记录字体、色彩、动效、背景/表面这些审美资产。
+7. 如果这类页面没有真实图片就会空心，先补 `image-preflight.md`。
+8. 如果用户还没有给参考方向，先补 `direction-plan.md`，明确 3 个异源方向；每个方向都要有不同审美主张和记忆点。
+9. 用户选定方向后，再补 `selected-direction.md`，把选中的 lens、theme、layout、组件、审美主张、记忆点和风险锁定。
+10. 如果用户已经给了效果图、设计稿、参考截图或其他明确参考图，先把它视为主参考源：优先锁定它的版式、层级、主视觉和关键路径；`starter / lens / theme / layout` 只作为实现加速器，不作为高于参考图的裁决源。
+11. 如果当前是空白工作区的前端/页面冷启动，而且用户原话已经给了明确的页面主题、模块范围或“直接实现”的意图，优先运行 `openprd run . --context --message <用户原话>`，不要先跑不带 message 的 `run --context`。
+12. 跑完 `design-starter` 后，立即进入 `Patch Mode`：把生成的入口文件当成稳定基座，在同一路径里细化结构、内容、样式和交互。
+13. 最后再进入验证，并用 `.openprd/design/checklists/ui-quality-gate.md` 和 `.openprd/design/anti-slop.md` 做自检。
 
 ## 空白工作区快路径
 
@@ -67,6 +71,9 @@ description: 为 OpenPrd 的界面、页面、视觉、样式和前端体验任
 - 对 blank static prototype，如果 prompt 已经给了页面主题和模块范围，优先把它们带进 `design-starter` 的 `--brief` 与 `--sections`，让 starter 直接落真实首版，并顺手把基础文档和说明书从模板态拉成当前事实，而不是先生成整页占位再手工回填。
 - 对 blank static prototype，如果当前轮是用户直接给任务，优先让 `openprd run . --context --message <用户原话>` 参与当前请求解析，而不是只看空白工作区自身状态。
 - 如果用户已经给了效果图、设计稿、参考截图或其他明确参考图，默认把它当成这轮实现的主约束；只有现有 starter、theme、layout 足够接近时才复用它们，否则以参考图为准，不强行套库。
+- 没有明确参考图时，不要直接落回紫白渐变、白底卡片堆叠、通用 SaaS hero、Inter/Roboto/Arial/system-ui 默认字体栈，或“浅色留白 + 少量点缀色”的安全解；先写出更具体的气质和记忆点。
+- 选择 theme 时优先用有角色分工的字体、色彩、表面、动效和密度体系；如果必须使用中性字体或克制配色，要说明这是为扫描效率、品牌限制或可访问性服务，而不是偷懒。
+- 动效、背景、纹理、阴影和装饰只能强化本次审美主张，不能替代信息层级、真实素材或任务完成路径。
 - 对 blank static prototype，如果页面不依赖外部产品事实、品牌素材或真实图片，允许并建议在 active design artifacts 里直接写清：`无外部产品事实依赖`、`当前无品牌素材依赖`、`真实图片不是页面成立前提`；这类页面不该因为“没有更多证据可查”而一直停在 `待填写 / pending`。
 - 对旅游、导览、展览、博物馆、城市、自然观察、馆藏、案例展示这类页面，默认先把“真实图片大概率是页面成立前提”写进判断里；除非你已经有明确降级方案，否则不要顺手补 `--no-real-images`。
 - 跑完 `design-starter` 后，立即替换生成入口文件里的 `title`、首屏文案、CTA 和所有 `[占位]` 文案；除非真的需要额外结构，不要再回头整页阅读模板文件。
@@ -91,27 +98,34 @@ description: 为 OpenPrd 的界面、页面、视觉、样式和前端体验任
 - “Patch 已完成”的最低标准是：入口文件本体已经真正改完，主要占位或“待补”文案已去掉，已准备好的真实图片或参考约束已经映射进页面，相关 active design artifacts 也已同步。
 - 只做规划、下载素材、补合同、写说明或口头承诺“准备开始改”都不算 `Patch Mode` 完成。
 
-## 五个硬门
+## 六个硬门
 
-### 1. Facts Before Assumptions
+### 1. Aesthetic Direction Before Coding
+
+- 编码前先回答：用途、用户、气质、约束、差异化记忆点。
+- 气质可以极简、工业、编辑、复古未来、自然有机、精致奢华、玩具感、艺术几何、温暖邀请、克制工具感等，但必须和任务、受众、内容资产一致。
+- 大胆不等于花，克制不等于空；复杂度要匹配审美主张。强叙事页面允许更强动效和视觉层次，工具型页面则用密度、对齐、状态和扫描效率体现设计。
+- 不要把“好看”当方向；要能说出这个页面最想让人记住的一件事。
+
+### 2. Facts Before Assumptions
 
 - 涉及产品名、版本号、发布时间、规格、价格、引用数据、榜单、排名、地点或政策时，不要凭记忆写页面。
 - 先核实，再写入 `.openprd/design/active/facts-sheet.md`。
 - 核实不到就标成 `待确认`，而不是自己补一个像真的答案。
 
-### 2. Assets Before Decoration
+### 3. Assets Before Decoration
 
 - 对品牌页、发布页、内容页、deck、招商页、展览页、产品页来说，logo、产品图、UI 图、图表素材、品牌色和字体都属于一等资产。
 - 先写 `.openprd/design/active/asset-spec.md`，再决定版式。
 - 不要把“先做个好看壳子”当成默认路径。
 
-### 3. Real Images Before Placeholder Harmony
+### 4. Real Images Before Placeholder Harmony
 
 - 如果任务属于旅游、展览、内容、科普、发布、品牌故事、馆藏、案例展示等场景，先判断真实图片是不是内容成立的必要条件。
 - 必要时在 `.openprd/design/active/image-preflight.md` 记录：是否需要真实图、计划来源、风险和降级方案。
 - 页面还没有真实图片时，不要用大片灰块假装已经准备好了内容。
 
-### 4. Three Directions Must Be Heterogeneous
+### 5. Three Directions Must Be Heterogeneous
 
 - 没有明确参考图时，不要只出三张“有细微差异的同一种安全解”。
 - 3 个方向至少来自 3 类不同生成逻辑：
@@ -119,10 +133,11 @@ description: 为 OpenPrd 的界面、页面、视觉、样式和前端体验任
   - `reference-transfer`：从真实世界成熟范式迁移结构方法
   - `design-lens`：基于某种明确设计哲学从头重构
 - 每个方向都要写清：为什么它和另外两版不同、适合什么场景、主要风险是什么。
+- 每个方向还要写清：审美主张是什么、用户会记住什么、它避免了哪种通用 AI 模板味。
 
-### 5. Theme Lock Before Build
+### 6. Theme Lock Before Build
 
-- 一旦方向已选，先锁定 `lens + theme + layout + component set`，再进入编码。
+- 一旦方向已选，先锁定 `lens + theme + layout + component set + aesthetic direction + memory point`，再进入编码。
 - 不要在实现中途临时发明颜色、阴影、边角体系或组件结构。
 - 如果实现过程中发现现有 theme 或 layout 不够用，先补库，再继续写页面。
 
@@ -131,13 +146,14 @@ description: 为 OpenPrd 的界面、页面、视觉、样式和前端体验任
 这套框架不是“参考图收藏夹”，而是 Agent 可执行的设计骨架：
 
 - `lenses/`：这次站在哪种设计判断角度看页面
-- `themes/`：色彩、字体、密度、圆角、阴影、边框和留白规则
+- `themes/`：色彩、字体、密度、圆角、阴影、边框、留白、动效和表面规则
 - `layouts/`：页面骨架
 - `components/`：高频结构块
 - `recipes/`：按任务类型打包的默认方案
 - `checklists/`：实现前后自检
 - `assets/`：允许反复复用的背景、表面、图案和位图资产说明
 - `templates/`：可直接开工的页面模板，减少空白工作区从 0 到 1 的犹豫
+- `anti-slop.md`：反模板化检查，拦住紫白渐变、通用字体、卡片堆叠和没有语境的装饰
 
 ## 什么时候必须补 active artifacts
 
@@ -146,16 +162,24 @@ description: 为 OpenPrd 的界面、页面、视觉、样式和前端体验任
 - 内容图是不是页面成立前提不明确时：必须补 `image-preflight.md`
 - 没有明确参考方向且要做新界面时：必须补 `direction-plan.md`
 - 用户已经选定方向并准备实现时：必须补 `selected-direction.md`
+- 方向、主题或模板里出现通用 AI 味时：必须先用 `anti-slop.md` 改写审美主张，再进入实现
+- 开发新功能出现新入口、按钮、tab、卡片、空态或工具格时：必须补 `asset-spec.md` 的“功能图标”行——先复用项目已有图标体系；项目没有时按最佳实践路由选型（UI 图标 Phosphor，落码 Lucide/Tabler/React Icons，AI 品牌 LobeHub Icons，技术栈 Tech Icons，功能图标/插画 iconfont），登记图标名、来源和用途后再接入实现。这是默认动作，不等用户提出；只有语义确实不需要图标或用户明确说不要时才跳过，并在收口说明原因
 
 ## 和现有视觉流程怎么配合
 
 - 这份 skill 发生在实现前，用来约束“先决定怎么做”。
 - `imagegen` 仍然负责出候选效果图。
+- logo、icon、avatar、badge、贴纸、空态插画、单物件 UI 位图等开发素材，如果后续要接入 UI 并需要透明背景，默认走一条完整的图标资产链路：先出 3 个差异足够大的独立素材候选方向，全部使用纯 `#00ff00` 绿幕、无文字、无 UI 容器、主体居中且留足裁切边距；用户选定前不写项目文件。选定后先用源图顺序或 contact sheet 确认选中图，再保留绿幕源图、抠透明 PNG/WebP、裁切居中、导出 384px 或多尺寸资产，并按真实入口位置分别调显示比例。接入后同步写回 `.openprd/design/active/asset-spec.md` 和 `selected-direction.md`，记录选中方向、资产路径、接入位置和验证结果。
 - `openprd visual-prepare` 负责把整板、多对象或网格参考图整理成可实现的 reference-set。
 - `openprd visual-compare` 负责实现后的视觉证据，而不是替代这份设计前置判断。
+- `visual-compare` 每次都会返回 `chatEmbed` markdown；生成证据板后必须把 `![视觉证据: ...](路径)` 直接嵌入最终回复，让证据在对话流里可见，不要只报告文件路径。`openprd dev-check` 触达界面文件且最近 24 小时没有证据板时会输出视觉证据提醒，收口前按提醒补齐。
+- 视觉证据不仅看像不像，还要看选定的气质、记忆点、字体/色彩/动效/表面层级有没有被实现保住。
+- 卡片宽度、间距、留白、对齐、颜色、圆角、字号、按钮和图标这类轻量 UI 可视优化，不需要自动升级成 3 方向方案评审；但只要最终会被用户看见，收口时就要有 `visual-compare` 的修改前后图、局部焦点证据板、截图实测证据板或对齐辅助线证据板。构建通过、打包成功、`dev-check` 通过和单张截图都不能替代视觉证据。
+- 新功能或改动里只要出现同构列表、卡片、网格或表格，就默认把容器轨道以及相同文案类型/相同组件槽位的对齐纳入验收；Agent 应截真实页面、叠辅助线，同时量卡片外框、列宽、行顶等容器轨道，以及标题、副标题、描述、标签、状态、价格、按钮、图标、操作区等内部内容槽位的 x/y/宽高/baseline spread，并用 `openprd visual-compare . --board <alignment-board.json>` 生成对齐证据。只量外框、列宽或行顶不算完整对齐验收。
+- 单个 logo、icon、avatar、badge、按钮图形或图片裁切需要判断内部居中、视觉重心或偏心时，默认使用 `openprd visual-compare . --board <centering-board.json>` 生成内部居中证据板；Agent 要先裁出目标元素，再用类似 Canvas 的像素 mask 量画布中心、主体外接框中心和视觉重心偏移。证据板必须显示红色画布中心线、绿色主体外接框、黄色视觉重心点和 offset 数值；单张截图或主观“看起来居中”不算完整验收。
 
 ## 输出要求
 
 - 对用户说明方向时，用人话描述气质、信息组织、视觉重心和适用场景。
-- 对实现说明时，明确写出选中的 lens、theme、layout 和关键组件。
+- 对实现说明时，明确写出选中的 lens、theme、layout、关键组件、审美主张、记忆点，以及主动避开的模板化风险。
 - 若因素材缺失、事实未确认或方向未选定而暂不实现，要直说卡点在哪里。

package/skills/openprd-frontend-design/references/design-asset-contract.md

@@ -14,6 +14,7 @@
 | 品牌资产 | logo、品牌色、字体、口号、icon 风格 | 先写进 `asset-spec.md`，没有就说明缺口 |
 | 内容资产 | 产品图、场景图、摄影图、插图、图表、馆藏图、案例图 | 先写进 `asset-spec.md` 或 `image-preflight.md` |
 | 参考资产 | 用户给的效果图、设计稿、参考截图、参考站点局部 | 先写进 `asset-spec.md` 或 `selected-direction.md`，并声明它是不是主参考源 |
+| 审美资产 | 字体组合、色彩角色、动效节奏、背景/表面、纹理、构图记忆点 | 先写清审美主张；缺失时从 `anti-slop.md` 和主题库中选，不要临场套通用 AI 风格 |
 | 布局资产 | 这次要用的 layout skeleton | 从 `.openprd/design/layouts/` 选，不临场发明 |
 | 组件资产 | 这次要用的 hero、stat、feature-grid、timeline 等 | 优先用 `.openprd/design/components/` 里已有结构 |
 
@@ -23,6 +24,9 @@
 - 没拿到真实内容图却先做内容型页面的大面积版式。
 - 用户已经给了效果图，却还把样式库默认风格当成更高优先级。
 - 一边实现一边临时发明主题、组件和布局体系。
+- 没有品牌或参考图约束时，默认使用紫白渐变、蓝紫光晕、玻璃卡、白底卡片堆叠或通用 SaaS hero。
+- 把 Inter、Roboto、Arial 或 system-ui 当成默认审美答案；如果确实需要中性字体，要说明它服务于密度、系统一致性或可访问性。
+- 用动效、渐变、纹理、阴影或装饰覆盖事实、素材、任务路径缺口。
 
 ## 完成标准
 
@@ -32,3 +36,5 @@
 - 方向差异写进 `direction-plan.md`
 - 选中方向写进 `selected-direction.md`
 - 若已有用户参考图，要明确记录它是否是当前实现的主参考源
+- 审美主张、气质端点、字体/色彩/动效/表面选择和记忆点已写进方向说明
+- 已用 `anti-slop.md` 排除通用 AI 模板味，或说明为什么当前任务必须使用克制中性方案

package/skills/openprd-frontend-design/references/direction-engine.md

@@ -3,23 +3,43 @@
 ## 目标
 
 让 3 个候选方向真的来自不同思路，而不是安全解的三个轻微变体。
+每个方向都必须先有审美主张，再有页面骨架；不要先套模板，再给模板找理由。
 
 ## 前提
 
 - 如果用户已经给了确认效果图、设计稿或明确参考图，先不要强行再出 3 个方向；先吸收它的版式、层级、主视觉和关键路径。
 - 这时方向引擎的任务变成：找最接近该参考图的 starter / theme / layout 作为实现加速器；如果库里没有接近项，也允许偏离默认组合，以参考图为准。
 
+## 审美立意输入
+
+每个方向先回答 5 个问题：
+
+- 用途：这个界面解决什么问题，用户为什么打开它。
+- 受众：用户是来快速完成工作、被说服、浏览内容，还是沉浸探索。
+- 气质：选择一个明确端点，例如克制极简、工业工具感、编辑杂志感、复古未来、自然有机、精致奢华、玩具感、艺术几何、温暖邀请、密集控制台。
+- 约束：框架、性能、可访问性、真实素材、品牌资产、信息密度和移动端限制。
+- 记忆点：用户看完后应该记住的一件视觉或交互特征。
+
+## 反模板化约束
+
+- 不要默认使用紫白渐变、蓝紫光晕、玻璃卡片、白底圆角卡片堆叠、通用 SaaS hero 或“左文案右插图”的安全布局。
+- 不要默认把 Inter、Roboto、Arial 或 system-ui 当成审美选择；除非品牌或系统限制要求，否则要用更有角色分工的标题/正文字体组合。
+- 不要让 3 个方向共享同一个视觉重心、同一组卡片、同一套浅色留白，只换色或换图。
+- 不要用装饰性纹理、阴影、动效、渐变来掩盖事实、素材或信息层级缺失。
+- 如果必须采用克制中性方案，说明它服务的是扫描效率、可访问性或用户工作流，而不是“先做个安全版”。
+
 ## 方向类型
 
 ### 1. Contrast
 
-- 主动拉开明暗、密度、节奏、叙事方式或视觉温度。
+- 主动拉开明暗、密度、节奏、叙事方式、视觉温度或动效强度。
 - 适合用户没有明确风格、但需要先看到差异时。
 
 ### 2. Reference Transfer
 
 - 从真实世界成熟范式中迁移结构方法。
 - 借的是组织方式、信息优先级和节奏，不是照着抄外观。
+- 参考来源可以是杂志目录、展陈导览、控制台、奢侈品目录、工具面板、游戏 HUD、报纸版式或专业仪表盘，但必须抽象成 OpenPRD 自己的设计语言。
 
 ### 3. Design Lens
 
@@ -29,18 +49,23 @@
 ## 每个方向至少回答
 
 - 这个方向的视觉主张是什么
+- 它的气质端点是什么
+- 用户会记住什么
 - 它为什么和另外两版不一样
 - 它更适合什么任务和用户
 - 它最大的风险是什么
+- 它主动避开了哪种通用 AI 模板味
 
 ## 不合格示例
 
 - 三版都只是浅色留白加不同插图
 - 三版都只是按钮颜色不同
 - 三版都共享同一布局和同一视觉重心，只是文案换序
+- 三版都用紫色渐变、玻璃卡、白底卡片阵列或同一个通用字体栈
+- 方向说明只写“现代、简洁、高级”，没有具体气质和记忆点
 
 ## 合格示例
 
-- 一版强调沉浸式主视觉和少量强信号
-- 一版强调编辑感和内容节奏
-- 一版强调密度、扫描效率和操作导向
+- 一版强调沉浸式主视觉和少量强信号，记忆点是首屏里的真实产品或场景状态。
+- 一版强调编辑感和内容节奏，记忆点是标题字体、图文节拍和章节式浏览。
+- 一版强调密度、扫描效率和操作导向，记忆点是稳定控制台结构、清晰状态和可反复使用的工具感。

package/skills/openprd-harness/SKILL.md

@@ -28,6 +28,7 @@ description: 驱动 OpenPrd 工作区完成从澄清到 handoff 的主流程。
    - 如果用户没有给 ID，但明确描述了某个已有需求、change、task 或 work unit，先把这段描述交给 `openprd run <path> --context --message <用户原话>` 做显式对象解析，不要先默认拿当前 active change
 6. 需求复杂度先交给 `$openprd-requirement-intake` 分流；不要按固定关键词判断。它会根据影响面、未知数、决策成本和验证成本判断需求类型，并保留内部路由码对照：直接处理=L0、现有功能优化=L1、新功能/新流程方案=L2；默认把路由码并进“需求类型：直接处理（L0）”这类标签里，只有内部排障确实受益时才额外补“内部路由码”
    - 如果需求涉及界面、页面、视觉、样式或前端体验，先判断是否属于“大界面改动”：会改变信息架构、页面布局、主视觉、关键路径、核心组件密度/层级，或用户需要先选设计方向。大界面改动在需求分流后、进入实现或 PRD 定稿前，先走视觉方案评审。
+   - 如果只是卡片宽度、间距、留白、对齐、颜色、圆角、字号、按钮或图标等轻量 UI 可视优化，仍按 L0/L1 小范围修正推进，不自动升级成大界面方案评审；但它是用户可见变化，动手前要有一句审美意图和记忆点，收口必须补 `visual-compare`、`focus-board`、`verification-board` 或 `alignment-board` 证据，并检查气质、层级、颜色、字号、间距和表面角色是否成立。只要界面里有同构列表、卡片、网格或表格，就把相同文案类型/相同组件槽位的对齐当作默认验收项，不等用户先投诉。build、package 和 `dev-check` 不能替代视觉证据。
    - 任何界面、页面、视觉、样式或前端体验任务在进入实现前，都要额外读取 `$openprd-frontend-design`，并优先检查 `.openprd/design/active/` 下是否已经补齐 `facts-sheet / asset-spec / image-preflight / direction-plan / selected-direction`。
    - 如果用户已经给了效果图、设计稿、参考截图或其他明确参考图，先把它视为主参考源；只有现有 starter、theme、layout 足够接近时才复用，不接近就允许偏离默认组合，不要为了套库把页面做成另一种样式。
    - 如果 `design-starter` 之后需要整页重写，默认先写 sibling draft，再覆盖回 `index.html`；不要让入口文件在 rewrite 过程中出现空窗。
@@ -35,14 +36,14 @@ description: 驱动 OpenPrd 工作区完成从澄清到 handoff 的主流程。
    - 把最后一批必要的查事实、查图、读模板动作放在口头宣布之前做完；一旦已经说“开始覆盖入口文件”或“开始整页重写”，下一步必须出现真实写文件动作；不能继续只读浏览、长时间压图或停在口头承诺。
    - 如果用户目标是把工作转成可学习、可复用、可回看、可教学或可沉淀的材料，先按期望产物形态判断是否需要 `$openprd-learning-review`：需要章节结构、证据锚点、图文讲解、检索练习、工作示例或长期阅读体验时，优先用 `openprd learn <path> --topic <主题>` 生成学习包骨架、阅读器和证据清单；不要用关键词表触发，普通 Markdown 只能作为辅助讲义。
 7. 如果用户是在规划、分析、架构评审，或问“怎么改”“会动哪些文件”，保持只读并基于证据回答
-8. 实现任务完成代码修改后、最终回复前，针对本轮实际 touched code files 运行 `openprd dev-check <path> <file...>` 或 `node scripts/openprd-dev-check.mjs <path> <file...>`：700 行以内正常；701-1500 行需留意；超过 1500 行说明后续改动成本较高。若出现需要关注的文件，最终回复必须以 **后续建议** 为标题，用 Markdown 表格列出影响位置、关注程度、规模信号、为什么需要关注、本次处理和后续建议，并按 🔴 → 🟠 → 🟡 排序
+8. 实现任务完成代码修改后、最终回复前，针对本轮实际 touched code files 运行 `openprd dev-check <path> <file...>` 或 `node scripts/openprd-dev-check.mjs <path> <file...>`：700 行以内正常；701-1500 行需留意；超过 1500 行说明后续改动成本较高。自动优化开启（默认）时，命中需要关注的文件先在本轮直接完成高内聚低耦合拆分（不丢功能、行为不变、拆完重跑测试），最终回复以 **OpenPRD 自动优化报告** 为标题复用 dev-check 表格（列：影响对象、问题级别、源文件规模、优化原因、本次处理结果、后续建议）并附开关确认一句话；关闭后（`openprd dev-check <path> --auto-refactor off`）以 **后续建议** 为标题输出推荐表格（列：影响对象、关注程度、规模信号、预警原因、本次处理结果、后续建议）。两种模式都按 🔴 → 🟠 → 🟡 排序
 9. 执行过程中发现新代码后缀、豁免路径、命令别名、项目约定或用户偏好时，不要中途打断当前任务。工具识别补全和减少重复打扰这类高置信低风险项可自动补齐并记录；用户偏好、项目协作规矩和 OpenPrd 默认行为先沉淀为候选，收工时运行 `openprd grow <path> --review` 集中确认
 10. 维护 OpenPrd 本身时，只要新增或修改配置类能力（阈值、规则、识别、豁免、命令别名、环境差异、用户偏好或策略开关），默认先做 grow-aware 自检：高置信应可成长时直接纳入 `openprd grow` 体系；不确定时主动询问用户是否做成可成长配置
-11. 用户要求生成图片、封面图、配图、海报、插画、图标、贴纸、头像、banner、主视觉/KV、运营图、效果图、视觉稿、mockup、先看样子或先确认设计方向时，默认直接调用 `imagegen`，也就是 Codex 原生 Image 2，产出图片；除非用户明确指定 HTML、SVG、CSS、Canvas、代码稿或可编辑矢量/source artifact，不要改用临时 HTML/SVG/CSS 再截图。OpenPrd 的 `review.html` 只用于需求评审，不能替代图片或效果图生成；只有实际发生 `imagegen` 调用后，才能汇报生图结果、失败或限流。生图结果先当候选效果图，不要默认登记到 `.openprd/harness/visual-reviews/`；如果用户还要继续做实现，主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现
-12. 大界面改动进入实现前，先按用户目标、信息架构变化、视觉决策成本和验证风险判断是否需要视觉方案评审：已有界面时用 Codex Computer Use 进入产品内对应功能并截当前真实界面；冷启动没有现有界面时基于已确认 PRD、用户群体、第一版切片和视觉目标生成设计 brief；再调用 `imagegen`（Codex 原生 Image 2）至少生成 3 个不同设计思想方向；把效果图横向拼接成一张大图，左上角标注 1/2/3，先作为候选效果图展示；主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现；只有确认后才把选定方向、整张图或其中子图整理到 `.openprd/harness/visual-reviews/`，未确认前不要进入大 UI 实现
-   - 3 个方向不能只是同一种安全解的轻微变化。至少要在 `.openprd/design/active/direction-plan.md` 里区分不同生成逻辑、适用场景和主要风险。
-   - 一旦用户确认方向，先在 `.openprd/design/active/selected-direction.md` 锁定选中的 lens、theme、layout 和组件，再进入编码。
-13. 界面、页面、视觉、样式或前端体验任务中，如果已经有确认参考图、设计稿、图片资产、截图或用户给图且进入实现阶段，阶段性完成后先截实现图，再运行 `openprd visual-compare <path> --reference <效果图> --actual <实现截图>`。如果一张参考图里有多个子图、网格或对象，先运行 `openprd visual-prepare <path> --reference <效果图> --grid <列>x<行>` 或 `--boxes <plan.json>`，生成 reference-set、contact sheet 和 compare-plan，再逐项对比。如果没有明确参考图，先判断新建界面还是修改既有界面：新建界面回到实现前 3 方向方案评审，修改既有界面动手前先截修改前截图，完成后用同一入口、视口、账号和数据状态截修改后截图，再运行 `openprd visual-compare <path> --before <修改前截图> --after <修改后截图>`。需要审局部细节时，再补 `openprd visual-compare <path> --board <focus-board.json>`；如果局部变化需要放到同一张证据板里审阅，默认优先把局部变化组合成一张 `focus-board` 再统一验收；并行跑了多个优化方向时，再补 `openprd visual-compare <path> --board <parallel-board.json>`。默认输出 JPG 到 `.openprd/harness/visual-reviews/`；查看合成图后继续复刻或自检，直到没有明显视觉差异或意外漂移；如果用户后续说“跟效果图”“不一致”“好丑”“复刻”，至少先产出一份视觉证据图。对 `design-starter -> Patch Mode` 的静态首页而言，真正完成还包括：入口文件本体已经改完、主要占位已清掉、已准备好的真实图片或参考约束已经落进页面，不是只补合同或只下载素材。
+11. 用户要求生成图片、封面图、配图、海报、插画、图标、贴纸、头像、banner、主视觉/KV、运营图、效果图、视觉稿、mockup、先看样子或先确认设计方向时，默认直接调用 `imagegen`，也就是 Codex 原生 Image 2，产出图片；Image 2 是工具路径，不是审美豁免，生成前先写清用途、受众、气质、约束和记忆点，并用 anti-slop 避免默认紫白/蓝紫渐变、通用字体、白底卡片堆叠和无语境装饰；除非用户明确指定 HTML、SVG、CSS、Canvas、代码稿或可编辑矢量/source artifact，不要改用临时 HTML/SVG/CSS 再截图。OpenPrd 的 `review.html` 只用于需求评审，不能替代图片或效果图生成；只有实际发生 `imagegen` 调用后，才能汇报生图结果、失败或限流。生图结果先当候选效果图，不要默认登记到 `.openprd/harness/visual-reviews/`；如果用户还要继续做实现，主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现
+12. 大界面改动进入实现前，先按用户目标、信息架构变化、视觉决策成本和验证风险判断是否需要视觉方案评审：已有界面时用 Codex Computer Use 进入产品内对应功能并截当前真实界面；冷启动没有现有界面时基于已确认 PRD、用户群体、第一版切片、视觉目标、气质端点和记忆点生成设计 brief；再调用 `imagegen`（Codex 原生 Image 2）至少生成 3 个不同设计思想方向；把效果图横向拼接成一张大图，左上角标注 1/2/3，先作为候选效果图展示；主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现；只有确认后才把选定方向、整张图或其中子图整理到 `.openprd/harness/visual-reviews/`，未确认前不要进入大 UI 实现
+   - 3 个方向不能只是同一种安全解的轻微变化。至少要在 `.openprd/design/active/direction-plan.md` 里区分不同生成逻辑、适用场景、审美主张、记忆点和主要风险。
+   - 一旦用户确认方向，先在 `.openprd/design/active/selected-direction.md` 锁定选中的 lens、theme、layout、组件、审美主张和记忆点，再进入编码。
+13. 界面、页面、视觉、样式或前端体验任务中，如果已经有确认参考图、设计稿、图片资产、截图或用户给图且进入实现阶段，阶段性完成后先截实现图，再运行 `openprd visual-compare <path> --reference <效果图> --actual <实现截图> --locale <zh-CN|en>`。如果一张参考图里有多个子图、网格或对象，先运行 `openprd visual-prepare <path> --reference <效果图> --grid <列>x<行>` 或 `--boxes <plan.json>`，生成 reference-set、contact sheet 和 compare-plan，再逐项对比。如果没有明确参考图，先判断新建界面还是修改既有界面：新建界面回到实现前 3 方向方案评审，修改既有界面动手前先截修改前截图，完成后用同一入口、视口、账号和数据状态截修改后截图，再运行 `openprd visual-compare <path> --before <修改前截图> --after <修改后截图> --locale <zh-CN|en>`。需要审局部细节时，再补 `openprd visual-compare <path> --board <focus-board.json> --locale <zh-CN|en>`；如果局部变化需要放到同一张证据板里审阅，默认优先把局部变化组合成一张 `focus-board` 再统一验收；并行跑了多个优化方向时，再补 `openprd visual-compare <path> --board <parallel-board.json> --locale <zh-CN|en>`。如果只是轻量 UI 可视优化，至少留下修改前后自检图、截图实测证据板或对齐辅助线证据板，并检查本轮审美意图和记忆点是否成立；新功能或改动包含同构列表、卡片、网格、表格时，默认补 `openprd visual-compare <path> --board <alignment-board.json> --locale <zh-CN|en>`，把真实截图、辅助线和相同槽位 spread 放到同一张证据板里；只跑 build、package、`dev-check` 或只看单张截图，都不能宣称视觉已完成。默认输出 JPG 到 `.openprd/harness/visual-reviews/`；查看合成图后继续复刻或自检，直到结构、气质、层级、字体/色彩/表面角色和记忆点都没有明显差异或意外漂移；如果用户后续说“跟效果图”“不一致”“好丑”“复刻”，至少先产出一份视觉证据图。对 `design-starter -> Patch Mode` 的静态首页而言，真正完成还包括：入口文件本体已经改完、主要占位已清掉、已准备好的真实图片或参考约束已经落进页面，不是只补合同或只下载素材。
 14. 实现任务新增或修改文件时，做文档影响检查：缺失的 `docs/basic/`、文件说明书、文件夹 README 要补齐；受影响的已有文档要更新；涉及后端、脚本、Agent、工具链、服务或数据处理变更时，把 CLI 与 API 视为同级接入面，更新 `docs/basic/backend-structure.md` 中的命令入口、输出契约、`help`/`doctor`/`dry-run`/`status`、接口协议与不适用说明
    - 如果这轮实现补充了新的前端设计主题、布局骨架、组件 recipe 或 anti-slop 规则，同步更新 `.openprd/design/` 与 `docs/basic/frontend-guidelines.md`，不要只留在代码里。
 15. 长时间实现任务使用 `openprd loop <path> --plan --change <id>`，并且只有当前用户消息明确要求开发、继续任务、深度调研、对标复刻或提交时，才为每个 loop 任务启动一个全新 agent 会话
@@ -53,8 +54,10 @@ description: 驱动 OpenPrd 工作区完成从澄清到 handoff 的主流程。
 20. 用户要求日志、链路追踪、业务成本护栏、免费额度、滥用防护、评估执行环境、冒烟覆盖、性能基线、极端场景、HTML 质量评估报告或项目级经验 Skill 时，路由到 `$openprd-quality`
 21. 用户需要可视化说明，或系统/产品形态仍不清晰时，在进入需求定稿前路由到 `$openprd-diagram-review`
 22. 默认保持 Codex hooks 轻量。除非项目明确需要完整工具级遥测，否则 `openprd setup/update` 使用 `--hook-profile lite`；默认 `lite` 会保留 `Stop` 收工回顾，用于在本轮结束前提醒是否值得沉淀项目经验，并要求 Agent 用“本次情况 / 准备整理成的经验 / 以后如何复用 / 只保留在当前项目里”的结构化人话向用户确认
-23. hook 会强制阻断几类场景：需求入口未完成就写实现、外部证据不足就直接改第三方集成、skill/AGENTS 变更未先可视化确认、以及敏感信息场景下直接读原始 vault 文件
-24. 当 `doctor` 报告生成引导漂移时，读取 `.openprd/harness/drift-report.json`
+23. hook 会强制阻断几类场景：需求入口未完成就写实现、外部证据不足就直接改第三方集成、skill/AGENTS 变更未先可视化确认、敏感信息场景下直接读原始 vault 文件，以及未经当前用户明确批准的云端热修复、生产远端写入、业务兜底、写死逻辑或缓存补行
+24. 即使用户已经授权实现，也不自动授权云端热修复、生产远端写入、客户端/服务端补业务数据、接口临时插入业务行、缓存补行、硬编码或写死逻辑。发现这类路径时先停下，说明为什么标准源码/迁移/配置路径不够、影响范围、回滚方式、本地同步计划和验证方式；只有用户明确说允许热修复、允许临时兜底或允许写死后才执行。
+25. 当 `doctor` 报告生成引导漂移时，读取 `.openprd/harness/drift-report.json`
+26. `openprd run . --context` 会返回 `runtimeEnvironment`。先按 `.openprd/harness/runtime-environment.json` 和 install manifest 的 `platformCapabilityPacks` 判断当前对话是在 Codex、Claude Code 还是 Cursor，再启用对应能力；Codex Image 2、Computer Use、Codex-owned browser window、对话协同画布和当前线程文本桥接都必须有当前 surface 或 hook/session 证据，不能只凭 Codex CLI 或配置文件存在来启用。当前线程桥接只在 Codex App 明确提供线程发送工具时使用；画布图片仍以导出路径或 Markdown 图片引用作为证据，不宣称网页能自动直发附件。
 
 ## 主工作流
 
@@ -94,10 +97,10 @@ description: 驱动 OpenPrd 工作区完成从澄清到 handoff 的主流程。
   - `openprd loop <path> --finish --item <task-id> --commit`
   - 让 `.openprd/harness/feature-list.json`、`progress.md`、`agent-sessions.jsonl`、`loop-state.json` 和 `loop-prompts/` 成为持久实现状态；feature list 里的 execution strategy 会为 worker shard 标注 `write-scope`、`owner-role`、`local-verify` 和 `integration-owner`
   - 只有在当前用户消息明确要求开发、继续任务、深度调研、对标复刻或提交时，才运行 `openprd loop <path> --run`
-  - 代码修改完成后、最终回复前，运行 `openprd dev-check <path> <file...>`；需要关注的文件必须在最终回复里以 **后续建议** 表格说明影响位置、关注程度、规模信号、为什么需要关注、本次处理和后续建议，并按 🔴 → 🟠 → 🟡 排序
-  - 用户只是要求生成图片、封面图、配图、海报、插画、图标、贴纸、头像、banner、主视觉/KV、运营图、效果图、视觉稿、mockup 或先看样子时，默认调用 `imagegen`（Codex 原生 Image 2）生成图片；除非用户明确指定 HTML/SVG/CSS/Canvas/代码稿，不要生成临时 HTML 再截图；未调用 `imagegen` 前，不要声称生图已完成、失败或限流。生图结果先当候选效果图，不要默认纳入验收
-  - 大界面改动不直接开工：先按用户目标、信息架构变化、视觉决策成本和验证风险判断方案评审形态；已有界面时用 Codex Computer Use 打开产品内对应功能并截图，冷启动没有现有界面时用已确认 PRD、用户群体、第一版切片和视觉目标生成设计 brief；再用 `imagegen`（Codex 原生 Image 2）生成至少 3 个设计方向，横向拼接成一张带 1/2/3 序号的大图作为候选效果图给用户确认；主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现；只有确认后，再把它作为实现参考图进入后续任务
-  - 如果已有确认参考效果图、图片资产、设计稿、截图或用户给图并进入实现阶段，阶段性完成后必须生成实现截图，并用 `openprd visual-compare <path> --reference <效果图> --actual <实现截图>` 输出 JPG 视觉对比图；如果参考图里有多个子图、网格或对象，先运行 `openprd visual-prepare <path> --reference <效果图> --grid <列>x<行>` 或 `--boxes <plan.json>`，检查 contact sheet 后按 compare-plan 逐项对比；如果局部细节更重要，再补 `--board <focus-board.json>` 输出局部焦点证据板；如果没有明确参考图，先判断新建界面还是修改既有界面：新建界面先完成 3 方向方案评审，修改既有界面动手前先生成修改前截图，完成后生成修改后截图，并用 `openprd visual-compare <path> --before <修改前截图> --after <修改后截图>` 输出 JPG 自检图；如果并行试了多个优化方向，再补 `--board <parallel-board.json>` 输出并行实验证据板。未查看对比图、或对比图仍有明显差异/漂移时，不要声称界面视觉完成；如果用户后续说“跟效果图”“不一致”“好丑”“复刻”，至少先产出一份视觉证据图
+  - 代码修改完成后、最终回复前，运行 `openprd dev-check <path> <file...>`；自动优化开启（默认）时需要关注的文件先本轮完成拆分，再以 **OpenPRD 自动优化报告** 表格呈现（列：影响对象、问题级别、源文件规模、优化原因、本次处理结果、后续建议）并附开关确认；关闭后以 **后续建议** 表格呈现（列：影响对象、关注程度、规模信号、预警原因、本次处理结果、后续建议）。两种模式都按 🔴 → 🟠 → 🟡 排序
+  - 用户只是要求生成图片、封面图、配图、海报、插画、图标、贴纸、头像、banner、主视觉/KV、运营图、效果图、视觉稿、mockup 或先看样子时，默认调用 `imagegen`（Codex 原生 Image 2）生成图片；Image 2 是工具路径，不是审美豁免，生成前先写清用途、受众、气质、约束和记忆点；除非用户明确指定 HTML/SVG/CSS/Canvas/代码稿，不要生成临时 HTML 再截图；未调用 `imagegen` 前，不要声称生图已完成、失败或限流。生图结果先当候选效果图，不要默认纳入验收
+  - 大界面改动不直接开工：先按用户目标、信息架构变化、视觉决策成本和验证风险判断方案评审形态；已有界面时用 Codex Computer Use 打开产品内对应功能并截图，冷启动没有现有界面时用已确认 PRD、用户群体、第一版切片、视觉目标、气质端点和记忆点生成设计 brief；再用 `imagegen`（Codex 原生 Image 2）生成至少 3 个设计方向，横向拼接成一张带 1/2/3 序号的大图作为候选效果图给用户确认；每个方向都要有具体审美主张和 anti-slop 自检；主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现；只有确认后，再把它作为实现参考图进入后续任务
+  - 如果已有确认参考效果图、图片资产、设计稿、截图或用户给图并进入实现阶段，阶段性完成后必须生成实现截图，并用 `openprd visual-compare <path> --reference <效果图> --actual <实现截图> --locale <zh-CN|en>` 输出 JPG 视觉对比图；如果参考图里有多个子图、网格或对象，先运行 `openprd visual-prepare <path> --reference <效果图> --grid <列>x<行>` 或 `--boxes <plan.json>`，检查 contact sheet 后按 compare-plan 逐项对比；如果局部细节更重要，再补 `--board <focus-board.json>` 输出局部焦点证据板；如果没有明确参考图，先判断新建界面还是修改既有界面：新建界面先完成 3 方向方案评审，修改既有界面动手前先生成修改前截图，完成后生成修改后截图，并用 `openprd visual-compare <path> --before <修改前截图> --after <修改后截图> --locale <zh-CN|en>` 输出 JPG 自检图；如果并行试了多个优化方向，再补 `--board <parallel-board.json>` 输出并行实验证据板；如果新功能或改动包含同构列表、卡片、网格、表格，或用户反馈没对齐/排版漂移，再补 `--board <alignment-board.json>` 输出对齐辅助线证据板。未查看对比图，或对比图仍有明显结构、气质、层级、字体/色彩/表面角色、记忆点差异/漂移时，不要声称界面视觉完成；如果用户后续说“跟效果图”“不一致”“好丑”“复刻”，至少先产出一份视觉证据图
   - `openprd loop <path> --finish` 前，先完成文档影响检查并更新缺失或过期的 `docs/basic/`、文件说明书和文件夹 README；涉及后端、脚本、Agent、工具链、服务或数据处理变更时，同步评估 CLI 与 API 两个接入面
   - 声称单个任务完成前，只运行本任务最小足够验证，并通过 `--evidence`、测试报告或任务 metadata 留下 task-scoped evidence；不要在每个任务里反复运行 `openprd quality <path> --verify` 或全局 `openprd run <path> --verify`
   - 阶段收口、全部任务完成、handoff/commit/release/publish 前，再运行 `openprd quality <path> --verify` 并审阅生成的 HTML 质量评估报告，检查场景标签、必需 EVO 门禁、日志、业务护栏、冒烟覆盖、任务完整性、性能基线、极端场景和知识缺口
@@ -146,9 +149,12 @@ description: 驱动 OpenPrd 工作区完成从澄清到 handoff 的主流程。
 - 使用：
   - `openprd synthesize <path> --title ... --owner ... --problem ... --why-now ...`
 - 如果草稿仍然稀疏，明确说明还缺什么
-- 生成 `spec.md` 和 tasks 时默认使用简体中文；必要专有名词、品牌名、命令名、路径、字段名和 API 术语可以保留原文
+- 生成 `spec.md` 和 tasks 时跟随用户当前主语言；无法判断时用简体中文兜底。必要专有名词、品牌名、命令名、路径、字段名和 API 术语可以保留原文
 - `synthesize` 生成 `review.html` 后，必须把 HTML 路径告诉用户，并自动打开它（或紧接着运行 `openprd review <path> --open`）
 - 评审页里的需求关系图、需求流程图和重点摘要不要靠 HTML 截断；`openprd synthesize` 生成版本快照后，不要直接把 review 给用户确认。必须先用 `openprd review-presentation <path> --template` 查看展示文案契约，让 Agent 按 `reviewPresentation` 写短文案，再用 `openprd review-presentation <path> --presentation <json> --write --fail-on-violation` 校验并写回。脚本通过后会写入校验元信息并重渲染可确认 review.html；超限时按脚本返回的 jsonPath 和字数限制重新提炼，不手工改快照、不裁剪原文
+- L1/L2 需求涉及界面、页面或交互时，review-presentation 写入前先补交互方向评审：用 `imagegen`（Codex 原生 Image 2）生成 3 个差异足够大的交互稿方向，图片保存到 `.openprd/design/active/`，再把每个方向的 `id/title/image/summary/tradeoff` 写入 `reviewPresentation.designDirections.directions[]`（title 15 字内、summary/tradeoff 30 字内）。review.html 会渲染 3 方向评审卡片，用户点“选这个方向”后回传 `openprd review <path> --mark confirmed --direction <id>` 命令；选定方向会记录进评审状态，后续实现必须按选定方向推进。不涉及界面时不要携带 designDirections 字段
+- 用户想在交互稿上圈选、批注或做视觉级反馈时，引导走画布评审协同：画布右栏顶部“评审协同”区显示当前 7 步流程位置，“导入评审方向”会把当前 review 的 designDirections 连图带说明摆上画布（已选定方向会标出），用户圈选批注后用“发送给 Codex”回传反馈
+- 用户问“现在到哪一步了”“接下来做什么”“OpenPrd 到底是干嘛的”时，先运行 `openprd guide <path>`：它按工作区状态输出 7 步流程（需求澄清 → 需求摘要 → 评审确认 → 交互方向选择 → 任务拆解 → 实现执行 → 验证收口）、当前位置和下一步动作，用它的输出向用户解释，不要口头即兴复述流程
 - 把生成的 `review.html` 当作首选稳定评审 artifact。默认 approval policy 是 `decision-points`：当前 lane 仍需要人类决策时，请用户先评审问题定义、范围、主流程、风险和开放问题，再运行带精确 `--version`、`--digest`、`--work-unit` 的 `openprd review <path> --mark confirmed`。L2 下先确认对话内 requirement 摘要，再写回确认事实、classify/synthesize，并进入这一步 review。若用户一开始已经明确要求直接做，并显式表示“不需要进行任何确认”，lane 才可进入 `silent-record`；单纯的“请帮我实现/继续实现”或“不要评审”都不触发这个豁免。进入 `silent-record` 后也只允许记录当前精确匹配的稳定 artifact，不能借机替别的版本补确认。review 记录完成且 tasks 就绪后，如果用户刚刚确认的是现有功能优化（L1）的 mini-plan、范围边界或正式产品边界，后续承接要写成“已确认，我按这个继续”，不要写成“确认，我们就按这个……”这种像再次索取确认的句子；如果用户原始意图已经明确要求实现，可直接继续执行；否则先输出执行确认清单，列出本轮目标、将执行内容、不做事项、验证方式和已知风险，再请求明确执行授权，不能只要求用户回复一句确认
 - 在 L2 的 requirement 摘要确认前，不要承诺“确认后我就开始实现”；正确顺序是：先确认摘要，再写回事实、进入 classify/synthesize/review，review 和 tasks 就绪后才谈执行。
 
@@ -159,8 +165,8 @@ description: 驱动 OpenPrd 工作区完成从澄清到 handoff 的主流程。
   - 流程 / 旅程确认
   - 需求定稿前的可视化评审
 - 当需求属于大界面改动时，在 PRD 定稿或实现开工前先走“视觉方案评审”：
-  - 已有界面时用 Codex Computer Use 进入产品内对应功能，截取当前真实界面；冷启动没有现有界面时，基于已确认 PRD、用户群体、第一版切片和视觉目标生成设计 brief
-  - 用 `imagegen`（Codex 原生 Image 2）基于截图或设计 brief 至少产出 3 个不同设计思想方向
+  - 已有界面时用 Codex Computer Use 进入产品内对应功能，截取当前真实界面；冷启动没有现有界面时，基于已确认 PRD、用户群体、第一版切片、视觉目标、气质端点和记忆点生成设计 brief
+  - 用 `imagegen`（Codex 原生 Image 2）基于截图或设计 brief 至少产出 3 个不同设计思想方向，每个方向都要有具体审美主张和 anti-slop 自检
   - 将 3 张效果图横向拼接为一张大图，每张左上角标注 1/2/3，先作为候选效果图展示给用户
   - 主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现；只有确认后才把选定方向、整张图或其中子图整理到 `.openprd/harness/visual-reviews/`
   - 未确认方向前，不进入大 UI 实现或声称方案已定
@@ -199,7 +205,7 @@ description: 驱动 OpenPrd 工作区完成从澄清到 handoff 的主流程。
 - 当方案形态仍不清晰时，优先先 review 再进入需求定稿
 - 当界面改动比较大、用户需要先选方向、或页面信息架构/主视觉会明显变化时，优先先做 3 方向候选效果图评审，再进入实现
 - 当用户目标是把本次工作转成可学习、可复用、可回看、可教学或可沉淀的材料时，先按期望产物是否需要章节结构、证据锚点、图文讲解、检索练习、工作示例或长期阅读体验来判断；需要时优先调用 `openprd learn .` 生成学习包和阅读器，不要用关键词表触发，普通 Markdown 只能作为辅助讲义
-- 用户要求生成图片、封面图、配图、海报、插画、图标、贴纸、头像、banner、主视觉/KV、运营图、效果图、视觉稿、mockup 或先看样子时，优先调用 `imagegen`（Codex 原生 Image 2）；只有实际发生 `imagegen` 调用后，才能汇报生图结果、失败或限流。生图结果先当候选效果图，并主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现。界面任务进入实现阶段时，已有确认参考图用 `openprd visual-compare --reference/--actual` 生成左右对比 JPG；如果参考图是一张整板、网格图或多对象组合，先运行 `openprd visual-prepare --reference <效果图> --grid <列>x<行>` 或 `--boxes <plan.json>` 整理 reference-set，再逐项对比；没有参考图时先判断新建界面还是修改既有界面，新建界面先完成 3 方向方案评审，修改既有界面用 `openprd visual-compare --before/--after` 生成修改前后自检 JPG；局部细节优先补 `--board <focus-board.json>`，并行优化方向优先补 `--board <parallel-board.json>`，共同作为视觉就绪判断依据。用户后续如果说“跟效果图”“不一致”“好丑”“复刻”，至少先产出一份视觉证据图
+- 用户要求生成图片、封面图、配图、海报、插画、图标、贴纸、头像、banner、主视觉/KV、运营图、效果图、视觉稿、mockup 或先看样子时，优先调用 `imagegen`（Codex 原生 Image 2）；Image 2 是工具路径，不是审美豁免，生成前先写清用途、受众、气质、约束和记忆点；只有实际发生 `imagegen` 调用后，才能汇报生图结果、失败或限流。生图结果先当候选效果图，并主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现。界面任务进入实现阶段时，已有确认参考图用 `openprd visual-compare --reference/--actual` 生成左右对比 JPG；如果参考图是一张整板、网格图或多对象组合，先运行 `openprd visual-prepare --reference <效果图> --grid <列>x<行>` 或 `--boxes <plan.json>` 整理 reference-set，再逐项对比；没有参考图时先判断新建界面还是修改既有界面，新建界面先完成 3 方向方案评审，修改既有界面用 `openprd visual-compare --before/--after` 生成修改前后自检 JPG；局部细节优先补 `--board <focus-board.json>`，并行优化方向优先补 `--board <parallel-board.json>`，同构列表/卡片/网格/表格优先补 `--board <alignment-board.json>`，共同作为视觉就绪判断依据。visual evidence 同时检查气质、层级、字体/色彩/表面角色和记忆点，不只检查截图是否存在。用户后续如果说“跟效果图”“不一致”“好丑”“复刻”，至少先产出一份视觉证据图
 - 遇到 blocker 时，优先把阻塞条件显式暴露出来，而不是悄悄补脑
 
 ## 禁止行为

package/skills/openprd-quality/SKILL.md

@@ -30,11 +30,11 @@ description: 评估 OpenPrd 的可观测性、业务成本与滥用护栏、评
 - 生成界面视觉对比图：
   - `openprd visual-prepare <path> --reference <效果图> --grid <列>x<行>`
   - `openprd visual-prepare <path> --reference <效果图> --boxes <plan.json>`
-  - `openprd visual-compare <path> --reference <效果图> --actual <实现截图>`
-  - `openprd visual-compare <path> --before <修改前截图> --after <修改后截图>`
-  - `openprd visual-compare <path> --board <focus-board.json|parallel-board.json>`
+  - `openprd visual-compare <path> --reference <效果图> --actual <实现截图> --locale <zh-CN|en>`
+  - `openprd visual-compare <path> --before <修改前截图> --after <修改后截图> --locale <zh-CN|en>`
+  - `openprd visual-compare <path> --board <focus-board.json|parallel-board.json|verification-board.json|alignment-board.json> --locale <zh-CN|en>`
 - 大界面改动的实现前方案评审：
-  - 先按用户目标、信息架构变化、视觉决策成本和验证风险判断方案评审形态；已有界面时用 Codex Computer Use 截取产品内当前功能截图，冷启动没有现有界面时用已确认 PRD、用户群体、第一版切片和视觉目标生成设计 brief；再用 `imagegen`（Codex 原生 Image 2）生成至少 3 个设计方向，并保存横向拼接评审大图到 `.openprd/harness/visual-reviews/`
+  - 先按用户目标、信息架构变化、视觉决策成本和验证风险判断方案评审形态；已有界面时用 Codex Computer Use 截取产品内当前功能截图，冷启动没有现有界面时用已确认 PRD、用户群体、第一版切片、视觉目标、气质端点和记忆点生成设计 brief；再用 `imagegen`（Codex 原生 Image 2）生成至少 3 个设计方向，并保存横向拼接评审大图到 `.openprd/harness/visual-reviews/`
 - 基于已审查报告生成或刷新项目级经验：
   - `openprd quality <path> --learn --from <candidate-dir|report-id-or-json>`
 - 审查执行中发现的配置、规则候选或 user-local 偏好：
@@ -57,8 +57,9 @@ description: 评估 OpenPrd 的可观测性、业务成本与滥用护栏、评
 - 可观测性：前端、后端、agent 工具、异步任务和错误路径能否通过共享 trace/request/task/error id 串起来
 - 业务成本与滥用护栏：免费、试用、消耗型资源、AI 调用、第三方 API、下载、存储等路径是否有额度、负向验证、监控、报警和止损
 - 评估执行环境：冒烟测试、功能覆盖、正常性能和极端数据场景是否存在并持续维护
-- 视觉评审证据：大界面改动进入实现前，应存在 3 方向效果图横向评审大图和用户选定方向；涉及界面视觉实现且已有参考效果图时，确认 `.openprd/harness/visual-reviews/` 下存在本次 `openprd visual-compare` 输出的“效果图 / 实现截图”JPG，并且 Agent 已基于合成图复核差异；如果参考图是一张整板、网格图或多对象候选图，进一步确认已存在 `openprd visual-prepare` 产出的 reference-set、contact sheet 与 compare-plan 或 board 模板，并且 contact sheet 已被检查。没有参考图时先区分新建界面和修改既有界面，新建界面确认实现前 3 方向方案评审已完成，修改既有界面确认存在“修改前 / 修改后”JPG，并已检查预期变化和未改区域漂移；当验收关注局部细节时，确认存在“局部焦点证据板”；当并行跑了多个优化方向时，确认存在“并行实验证据板”
-- HTML 质量评估报告：`.openprd/quality/reports/` 下的人类审查产物是否存在，且足以支持就绪判断
+- 视觉评审证据：大界面改动进入实现前，应存在 3 方向效果图横向评审大图和用户选定方向；每个方向应有明确用途、受众、气质端点、审美主张、记忆点和 anti-slop 自检。涉及界面视觉实现且已有参考效果图时，确认 `.openprd/harness/visual-reviews/` 下存在本次 `openprd visual-compare` 输出的“效果图 / 实现截图”JPG，并且 Agent 已基于合成图复核差异；如果参考图是一张整板、网格图或多对象候选图，进一步确认已存在 `openprd visual-prepare` 产出的 reference-set、contact sheet 与 compare-plan 或 board 模板，并且 contact sheet 已被检查。没有参考图时先区分新建界面和修改既有界面，新建界面确认实现前 3 方向方案评审已完成，修改既有界面确认存在“修改前 / 修改后”JPG，并已检查预期变化和未改区域漂移；当验收关注局部细节时，确认存在“局部焦点证据板”；当并行跑了多个优化方向时，确认存在“并行实验证据板”；当普通截图、Computer/Browser/Playwright 实测截图作为视觉证据时，确认存在“截图实测证据板”；当新功能或改动包含同构列表、卡片、网格或表格，或用户反馈没有对齐/排版漂移时，确认存在“对齐辅助线证据板”，并检查标题、标签、描述、状态、操作区等相同槽位的 x/y/宽高 spread 是否低于阈值。这些证据不只查有无图片，还要查气质、层级、字体/色彩/动效/表面角色和记忆点是否成立。
+- 轻量 UI 可视优化：卡片宽度、间距、留白、对齐、颜色、圆角、字号、按钮或图标等小改仍属于用户可见变化。质量审查时至少确认存在修改前后视觉对比、局部焦点证据板、截图实测证据板或对齐辅助线证据板，并且本轮审美意图、气质、层级和记忆点已被复核；同构列表、卡片、网格或表格即使用户没有主动提出“对齐”，也要把相同文案类型/相同组件槽位的对齐作为默认验收项；build、package、`dev-check`、单元测试或单张原始截图都不能替代视觉收口证据。
+- HTML 质量评估报告：`.openprd/quality/reports/` 下的人类审查产物是否存在，且足以支持就绪判断；报告目录按 `reports.retentionMaxReports`（默认 60）自动清理旧 eval 报告，index 保留的最新条目不受影响，不要依赖已被清理的历史报告路径
 - 项目经验沉淀：已验证修复是否应该先生成当前项目内的项目经验候选；若值得保留，先用“本次观察到的情况 / 计划保留的经验 / 以后怎么复用 / 只保留在当前项目里”的结构化人话询问用户，再沉淀为 `.openprd/knowledge/skills/` 下可复用的项目经验
 - 自我成长：配置缺口、文件识别、命令习惯或用户偏好优先沉淀为 `.openprd/growth` 候选，经用户确认后固化；不要把个人偏好混进项目共享质量经验
 
@@ -89,8 +90,9 @@ description: 评估 OpenPrd 的可观测性、业务成本与滥用护栏、评
 - `openprd quality <path> --verify` 生成 advisory 报告时，仍要认真阅读 HTML，不得只看命令退出结果。
 - `openprd run <path> --verify` 若显示 `taskReady=true` 且 `workspaceReady=false`，不能宣称整体工作区就绪；先明确区分“当前任务通过，工作区待关注”，再列出未通过门禁。
 - 若只剩 `feature-coverage`，说明是任务账本或覆盖证据未收口，不要把本次功能表述成失败。
-- 大界面改动缺少实现前 3 方向效果图评审或用户未确认方向时，不要进入大 UI 实现，也不要声称方案已定。
-- UI 任务有参考图但缺少 visual-compare 输出时，不要宣称视觉实现完成；如果参考图是一张整板、网格图或多对象组合，但缺少 `visual-prepare` 的 reference-set / contact sheet / compare-plan，也不要把整板盲比当成充分验收；没有参考图时先判断新建界面还是修改既有界面，新建界面缺少 3 方向方案评审、修改既有界面缺少修改前后截图对比时，都不要宣称视觉自检完成；局部细节本该单独审却没有局部焦点证据板时，不要把整屏图当成充分验收；并行跑了多个优化方向却没有并行实验证据板时，不要只凭口头结论收尾；如果对比图仍有明显偏差或漂移，先返工而不是把差异留给用户发现。
+- 大界面改动缺少实现前 3 方向效果图评审、缺少审美主张/记忆点，或用户未确认方向时，不要进入大 UI 实现，也不要声称方案已定。
+- UI 任务有参考图但缺少 visual-compare 输出时，不要宣称视觉实现完成；如果参考图是一张整板、网格图或多对象组合，但缺少 `visual-prepare` 的 reference-set / contact sheet / compare-plan，也不要把整板盲比当成充分验收；没有参考图时先判断新建界面还是修改既有界面，新建界面缺少 3 方向方案评审、修改既有界面缺少修改前后截图对比时，都不要宣称视觉自检完成；局部细节本该单独审却没有局部焦点证据板时，不要把整屏图当成充分验收；并行跑了多个优化方向却没有并行实验证据板时，不要只凭口头结论收尾；普通截图或 Computer/Browser/Playwright 实测截图没有截图实测证据板时，不要把原始截图当成视觉收口；同构列表、卡片、网格或表格缺少对齐辅助线证据板时，不要宣称相同槽位已经对齐；如果对比图仍有明显结构、气质、层级、字体/色彩/表面角色、记忆点偏差或漂移，先返工而不是把差异留给用户发现。
+- 轻量 UI 可视优化缺少视觉证据或审美复核时，可以说代码或构建已处理，但不要说“界面已经优化完成”。
 - 最终回复必须列出未通过的必需 EVO 门禁；如果某门禁被判定不适用，要说明它是当前场景可选或已有明确豁免。
 
 ## 经验 Skill 规则