oil-ui-pro 0.15.4 → 0.22.2（上游 ui.oiloil.org 正式包）＋记 P0-98 跨盘 rename 坑

- oil-ui-pro 升到 0.22.2：references 13→28 份（新增 16、删 imagery.md）、assets 增 cards/（22 组）与 fonts/、SKILL.md 顶层五步结构未改名。 - 升级路径：官方 `npx github:oil-oil/oil-cli update` 稳定失败（error=replace、报「检查目录权限」）。真身为 EXDEV —— 解压在 os.tmpdir()（C 盘）、技能目录在 E 盘，Windows 上 rename 不能跨盘； CLI 的 catch 把非 CliError 原生异常一律兜底成 replaceFailed，真错误一个字不吐。做法＝借其 prepare() 只做下载+校验，再 cp 到同盘 stage、rename 交换；官方命令复验 up_to_date。 - 回归：product-planning 按名引用的 visual-review.md／tools.md／design-direction.md／style-explorer.md 全部健在；命名闸门 2061｜0｜27。 - session-mechanism/references/pitfalls.md 新增 P0-98（含通则：更新器把原生错误兜底成指错方向的人话）。
2026-10-14 10:21:46 +08:00
1 parent 053a6a6723
commit d9445b5888
@@ -1,154 +1,38 @@
-# 视觉评审协议
+# 视觉评审派发协议 (主 Agent 专用)

-## 评审者的独立性
+主 Agent 用这份文件派发独立评审。打分标准和检查规则在 [评审手册](reviewer-manual.md) 里，由评审者读；主 Agent 不读，只按下面的清单交接。

-选择能实际看图的隔离执行者，不固定供应商、模型价格或参数规模。遵循用户的模型偏好和预算，不假定更贵必然更懂设计。
+## 1. 什么时候该派发？触发什么模式？

-首次评审与后续独立复查均使用新上下文。只传当前版本的必要证据，不继承制作对话，也不将旧评审粘进去。主 Agent 保留历史，用于判断建议是否反复和修改是否有效。
+当你完成了一个关键页面、设计方案或改动后，按以下清单触发对应的评审子 Agent：

-没有隔离看图能力时，主 Agent 可以直接检查当前画面，但不能称为独立评审。不能看图时只给结构或源码诊断，不根据文件名猜测画面。
-
-## 交接内容
-
-| 提供 | 不提供 |
+| 你做了什么改动 | 子 Agent 的提示词 (Prompt) 模板 |
 | --- | --- |
-| 用户任务、受众、交付范围和目标设备 | 制作者的论证、已经投入的时间 |
-| 已确定的方向、品牌与不可改变约束 | 源码、实现细节与技术借口 |
-| 当前版本截图，注明页面、状态与逻辑视口 | 旧版本截图、旧评分和旧评审结论 |
-| 已实际查看的必要参考与其用途 | 预设问题清单、希望评审者赞同的答案 |
-| 需要评估的可见状态或过程证据；三处基本动效（主操作反馈、一处状态切换、首次出场）和动效记忆点，各一段 3–5 秒录屏或开始、中间、结束三帧，并写明触发它的动作 | “必须给到某个分数”等通过暗示 |
+| 探索了新界面，或推翻现状重新设计（重塑） | `请读取 references/reviewer-manual.md，按照【全新界面与改版评审】标准，评审这些截图，并给出 1-10 的打分。` |
+| **给已有界面评审**：在已有界面上整理、升级、润色或扩展 | `请读取 references/reviewer-manual.md，按照【存量已有界面润色评审】标准，对比提供的现状规范，指出偏离点。不打分。` |
+| 小改动、单处间距或颜色微调 | **无需派发子 Agent**，主 Agent 结合上下文自行核对即可。 |

-有记忆点时，评审单独回答：这一刻是否让人记住，动作和结果能否一眼对上。有动效证据时，再回答：各处动效是不是同一种手感，是否从被操作的地方出发、朝同一个方向、彼此接得上；指出各动各的、生硬或多余的地方。只有静态截图时，评审记录写明记忆点和动效没有评审。
+模板里的路径换成本 Skill 目录下的绝对路径：子 Agent 的工作目录不是本目录。

-新评审者需要理解任务约束，不能只凭一张图自由改题。参考图用于说明方向或质量基线，精准还原任务除外，不作为要求照抄的目标。
+## 2. 派发前，主 Agent 要准备的“交接清单”

-截图文件必须能被评审者访问。交接前确认文件属于当前版本；长页同时提供整体与必要局部，细节图不能替代整体构图。交互只能依据提供的状态与过程证据判断，单张截图不能证明提交或键盘行为正确。
+调用宿主提供的隔离执行能力时，必须提供以下物料：
+- **必给**：当前版本的截图/录屏（注明设备视口）、用户原始任务、设计边界和约束；有方向卡时，再给北极星那一句。方向卡里其他需要评审知道的硬性约束，例如品牌要求每屏出现字标，摘成一句写进约束，不交整张方向卡。
+- **如果有**：现有项目的色彩规范、组件约束（存量老项目必须给）；方向卡的选色记录，即“色彩”一栏里颜色来自这个产品的什么那一句；项目里有 `DESIGN.md` 或同类设计文档时，存量润色评审整份给出并以它为标准，新界面与改版评审只把其中的品牌资产和“不要做”摘进约束。
+- **截图工具的默认做法提示**：`report.json` 里 `lint` 字段的提示原样给出；你决定保留的项，每项附一句理由。
+- **不给**：源代码、为自己的做法辩护的说明、之前评审打过的分数（评分要独立）。

-## 可直接使用的评审任务
+截图必须属于当前版本，且能被评审者访问；这一轮没有改到的状态和动效，可以沿用上一轮的证据文件，交接时注明哪些是沿用的。长页同时提供整页与必要局部；细节图不能替代整体构图。

-> 根据提供的用户任务、设计方向、约束和当前画面评审设计。先用一两句话说出这个画面想成为什么体裁和风格；再说出它属于什么品类，举出这个品类里两三个风格最鲜明的产品，说出它们在首屏和控件上通常怎么做。画面违背这些共识的地方，判断是有意的偏离，还是没认出品类；同时看画面是不是某个标杆的复制，遮住名字还能不能认出是另一家。再设想这一体裁里顶尖的设计团队会怎样完成同一任务，可以举一两类真实可参照的作品；然后指出当前画面与那个标准之间差距最大的一到三处。先看主构图、阅读顺序、主视觉和内容与操作的关系，再看排版、空间、色彩和细节。留意过度、夸张或一看就是模型生成的做法并扣分，例如首屏左边大标题、右边说明或图片的默认分栏，无来由的渐变与发光，处处圆角卡片，表情符号图标、随意给文字上色、空泛或晦涩的比喻式文案。画面里多个元素同时争当主角、处处都在用力，也算问题；反过来，处处及格却没有一处让人记住，也指出来，并说出最值得集中发力的位置。留意重复的线框：同一处分隔叠了好几条线，留白已经分开的地方又加线，或者每个层级都画一遍线，让画面发碎。承担风格和结构的线不算问题。单侧的彩色边线（引文、提示、反馈、当前项左边的一条色条）也算问题。画面上的制作说明，例如“示例”“待核实”“示意图”“未接入”，也列进可以直接删掉的文字。体裁指产品本身，例如展览落地页；借用的其他媒介只是风格来源，不按“像不像那个媒介”评判，也不为了更像而建议补上更多部件。如果是工具、后台，或画廊、商店、信息流这类让人浏览挑选的页面，再说出一屏能看到几个对象、第一排内容离顶部多远、主动作离当前对象有多远，并和这一体裁里最好的产品比较密度。另外单独列出两类小问题：可以直接删掉的文字，以及对齐、圆角、阴影、标点、状态这类看得出的细节瑕疵；表格和列表要放大看，各列的行线和基线是否对齐。每处问题写清位置、观察、影响和可执行的调整方向，必要时给伪代码或属性关系，不写含糊的散文。敢下判断，给出有主见的建议，不退回安全、容易的做法。区分可观察缺陷与风格偏好；没有明显问题时直接说明，不为凑数提出修改。最后按 10 分制打分，表示当前画面离顶尖水准还有多远。只提供评审，不修改文件，不启动其他评审者。未看到或无法验证的内容明确说明。
+动效不用逐项备证据：取证那一次的录屏一并交给评审就够。评审能自己打开页面时，把页面地址也给它，录屏里看不清的它会自己操作一遍。
+没有隔离、能看图的执行者时，主 Agent 按同一手册自检，交付时写明“未独立评审”；没有实际画面时不打视觉分。

-如果有同类的优秀作品截图，更好的做法是把它们和当前画面放在一起，例如四张专业作品加一张当前截图，请评审者按完成度和品味排序并说明差距。有视觉基线的比较比“想象顶尖团队”更稳定。这些作品是基线和情绪板，不是要照抄的目标。
+## 3. 主 Agent 如何处理子 Agent 的反馈

-用“顶尖团队会怎么做”作为参照，是为了拉高标准、让建议有方向，不是要求照抄某个作品。评审只给方向和具体修改点，不自己重做页面；让评审者直接重做通常时间和成本都会翻倍。
-
-主 Agent 在任务后附实际材料。没有真实材料时不能原样发送模板并让评审者自行想象。
-
-评审同时核对设计北极星是否在构图、字体、素材和交互中形成呼应，突破是否增强主题，以及是否用冗余文字和层层容器掩盖薄弱的主视觉。阅读尺寸下的文字碰撞、过小正文和错误裁切应直接指出；不要仅凭整体缩略图判定可读性通过。
-
-## 给已有界面评审
-
-在已有项目里润色界面时，评审的标准是这个产品自己的设计规范，不是评审者心里的理想风格。规范管“用什么”：哪些颜色、字号、间距、组件；[视觉语言](visual-language.md) 里关于层级、对齐、留白、文字和减法的判断管“怎么用得好”，照常使用。
-
-什么时候用，由 SKILL.md 步骤 4 决定：润色一整页或多页之后，或者用户要求评审现有界面、没有要求重新设计时。单个元素的小改动不评审；用户要求改版或重新探索时，用上面的正常评审。
-
-### 先确定规范
-
-1. **有成文规范时以它为准。** 设计文档、设计变量（颜色、字号、间距、圆角、阴影）、组件库文档或组件目录。
-2. **没有成文规范时，从现有实现里读出来。** 看设计变量文件和主题配置、共享组件和它们的变体、同类页面的做法，整理一份简短的现状规范：字体和字号层级、每种颜色的用途、间距和圆角、按钮与表单等关键组件的样子、用哪套图标。实现里本来就不一致的，比如三种按钮，以多数用法为准，少数用法记为待统一。
-3. **规范本身有问题时说出来。** 不在评审里悄悄绕开，单独列出，交给用户决定。
-
-优化 UI 时做过规范体检、重新建立了规范的，以选定的新规范为准，见 [存量项目](existing-project.md) 的“规范体检”。
-
-### 交给评审者
-
- 当前版本的截图，注明页面、状态和逻辑视口。
- 规范：有成文规范时给相关文件或摘录；没有时给整理好的现状规范，再附两三张用了同样组件的其他页面截图，作为一致性的参照。
- 不能动的清单：品牌、字体、主色、组件库、全局导航，以及用户指定保留的部分。
- 用户任务和受众。
-
-和正常评审一样，不给源码、制作过程和旧版截图。
-
-### 评审任务
-
-> 根据提供的设计规范、不能改动的清单、用户任务和当前画面，评审这个已有界面。先读规范，再看画面。第一部分，逐条列出画面偏离规范的地方：用了规范以外的颜色、字号、间距或圆角，同类组件长得不一样，没用已有组件而是另做了一个。第二部分，在规范范围内指出最影响完成度的三处问题，依据是层级、对齐、留白、文字、状态和减法这些设计判断。每条建议都要能用现有的设计变量和组件做到；确实需要新增变量或组件时，单独列出并说明理由。不建议更换品牌色、字体、组件库或整体布局。另外列出可以直接删掉的文字，以及对不齐、间距不一这类细节瑕疵。每处写清位置、观察和调整方向。只提供评审，不修改文件，不打分，不启动其他评审者。未看到或无法验证的内容明确说明。
-
-### 处理结果
-
- 只做一轮。改完由主 Agent 和基线做前后对比，不为分数复查。
- 偏离规范的问题优先改，改在共享的设计变量和组件上，不在单个页面上覆盖。
- 需要扩展规范或违背规范的建议，不直接采纳，连同理由交给用户决定。
-
-## 首稿通常怎样被改好
-
-首稿即使方向不同，也常常共用同一套模板骨架。交付对比页时推荐一轮独立评审，由用户决定是否执行；执行时它是把方向拉开的主要手段，不能因为方向卡已经不同就跳过某个方向。叙事页面（落地页、品牌页、活动页）最常见、也最有效的几类改法：
-
- 删掉装在卡片里的产品界面小组件，把位置让给主视觉。
- 把一个元素放大到结构级别，其余元素为它退后。
- 用一个主视觉撑起画面。它从方向的生成引擎里来，不套现成的装置。
- 砍掉重复的标签和并列的按钮，只留一个主动作。
- 让图像参与版面结构，而不是装在盒子里。
-
-这些改法不要搬到产品界面上。工具、后台和 App 常见的有效改法是：
-
- 删掉解释界面的文字：列说明、区块副标题、“卡片顶边对应……”这类说明、和状态标签重复的提示框。
- 压缩页面头部，把高度还给工作区；页面标题缩成一行。
- 把用户最怕错过的属性放大，例如等待时长、超时、欠费，让它在整页里最先被看到。
- 提高密度，直到一屏能看到足够多的对象用于比较。
- 同一个状态只表达一次，删掉重复的徽章、色块和提示。
-
-画廊、商店、信息流这类浏览内容的页面，常见的有效改法是：
-
- 删掉顶部的口号和解释页面用途的段落。
- 把第一排内容提到首屏，让内容本身成为主角。
- 把标题、导航和筛选合进顶部一到两行。
- 让缩略图的比例和排列成为版式本身，不再给每张卡片加多余的边框和说明。
-
-## 反馈格式
-
-先用短段落说明当前画面如何表达任务与方向。随后按影响列问题，每项包含：
-
- 位置：页面、区域、状态或元素。
- 观察与证据：实际看到了什么；不能只说“普通”“不高级”。
- 影响：妨碍了识别、任务完成、视觉焦点或选定方向中的哪一项。
- 建议：可执行的调整，必要时提供布局示意或属性关系；不猜不存在的文件与行号。
- 验证：修改后应检查什么，并指出是否只是主观偏好。
-
-10 分制评分用来驱动循环：主 Agent 以 9 分为完成目标，但不向评审者透露这个目标。分数必须附带具体差距，只有数字的评审不算有效。同一评审模型的前后分数可以比较；不同模型的数值不直接比较，也不把分数当作审美事实。分数高但用户不喜欢时，以用户判断为准。
-
-## 多个方向时加一次横向评审
-
-逐个评审只能看出每个方向自身的问题，看不出方向之间的趋同。多个方向都修改完后，再派一个新的评审者，同时看所有方向的整页截图，只回答一个问题：哪些区块在不同方向里本质上是同一个东西（结构、组件或版式相同，只是换了颜色和字体）？逐条列出区块和涉及的方向。被点名的区块，按各自方向的生成引擎重做。
-
-## 任务走查：让评审者真的去用
-
-视觉评审看的是截图，看不出流程问题：入口找不到、出错后回不去、第二次用还是一样慢。新界面或改动了操作流程时，在视觉评审之外，再派一个新的执行者做任务走查。它必须能操作真实页面，例如浏览器自动化或可点击的原型，不看代码和制作过程。没有这种能力时，由主 Agent 按同样的方法自己走一遍，并标明不是独立走查。
-
-交给它：
-
- 3–5 个真实任务，用用户的话写，不提界面上的按钮名称。写“把上周没回复的三个客户标成待跟进”，不写“点击筛选按钮，选择未回复”。每个任务写清怎样算完成。
- 目标设备、入口地址和需要的测试数据。
- 故障场景怎么触发：提交失败、断网、空数据、慢响应。
-
-它要做的：
-
- 每个任务从入口开始，记录每一步看到了什么、为什么选这里。需要猜的地方记为“犹豫”，点错又退回的记为“走错”，走不下去的记为“卡住”。
- 每个任务再做一次“第二次使用”：有没有更短的路径，能不能只用键盘完成。
- 至少在一个任务里制造失败，看输入是否保留、能否原地恢复。
- 在窄屏上把最主要的任务再走一遍。
-
-输出按严重程度排序：卡住、走错、犹豫、多余的步骤。每条附截图和步骤编号，写清当时预期什么、实际发生了什么。不打审美分，也不提视觉建议。
-
-所有核心任务都能在没有提示的情况下完成，并且每处犹豫都有对应的修改或保留理由，走查才算通过。任务走查和视觉评分是两条线：一边分数高，不能抵消另一边的问题。
-
-## 评审改流程和加新功能的方案
-
-存量项目里改流程和加新功能的方案，比的是做法，不打分，也不问顶尖团队会怎样设计画面。交给评审者：用户的话写成的任务、每个方案的方案卡、各自差别最大的那一帧或本地地址、现状基线。不给制作过程。
-
-> 根据提供的任务、方案卡和画面，评审这几个存量项目里的方案。先说出这几个方案是不是真的不同的做法：入口和步数都相同、只是画面不同的，指出是哪几个。再对每个方案，按任务从入口走到结果，指出哪一步还在让用户伺候界面，而不是在做决定：找入口、重复填写系统已知的值、为了确认而确认、来回切换页面。然后列出方案里属于补丁的部分：加提示、加引导、加确认、加说明，却没有让步骤、要记住的事或要切换的页面变少。最后指出每个方案最可能失败的场景。每条写清位置、观察和调整方向。只提供评审，不修改文件，不打分，不启动其他评审者。未看到或无法验证的内容明确说明。
-
-能操作真实页面时，另按上面的“任务走查”走一遍，选定前后各一次，比较步数和卡住、走错、犹豫的次数。
-
-## 主 Agent 如何处理反馈
-
-先处理任务阻碍、内容错误与明显视觉层级问题，再处理有依据的精修。将接受的反馈映射到实际实现；用户指定的风格不能被评审者随意替换。
-
-评审单独列出的“可以直接删掉的文字”默认照删；只有删了会影响理解时才保留，并在记录里写一句理由。
-
-多个评审对不同方向给出同一条建议时，分别在每个方向里找它自己的落地形式，不用一种实现套到所有方向上。
-
-建议违反用户约束、仅表达另一种偏好或缺乏证据时，可以不采纳并保留简短理由。为了更像借用的媒介而增加部件、线框或装饰的建议，先对照北极星判断，通常不采纳。一次完成相关改动后集中取证；不每改一个细节就重新派发。
-
-记录版本、已接受改动、未解决问题与检查结果。保持相当的视口、内容和状态进行前后比较；后续独立评审只看当前版本，前后收益由主 Agent 检查，重大主观取舍由用户判断。
-
-出现持续换风格、互相推翻或细节调整无可见收益时停止美学循环，保留最符合任务与方向的版本。停止不能掩盖仍然存在的功能缺陷或未经验证的部分。
+子 Agent 返回报告后，按以下原则修改：
+- **第一条是“重做”**：回到方向卡，重定被点名区块的骨架或主视觉，不逐条修补。
+- **按清单顺序改**：问题清单从影响最大的一条往下改；“保留”那一行记进设计说明，改的时候对照，别把它修平。
+- **提升条目同样要做**：精致度、设计感和动效的提升不是可选建议，和问题一样按清单做；做不了的在交付说明里写明原因。
+- **默认照删**：子 Agent 列出的“可以直接删掉的无用文字”照删，除非会产生功能歧义。
+- **落到具体调整**：把子 Agent 的高层要求（如“太挤”“层级不清”）落成间距、字号和阴影的实际调整。子 Agent 提议更改用户锁定的品牌色或大框架时，写一句理由后不采纳。
+- **防止死循环**：如果双方审美意见陷入僵持、来回横跳且无可见收益，保留你认为最佳的版本并停止循环。