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
@@ -2,11 +2,11 @@

 ## 先走通用户任务

-用一条主要路径说明：从哪里进入、识别哪个对象、作出什么决定、执行哪个动作、看到什么结果。只展开当前范围相关的分支，不为一个小表单设计整个产品流程。
+先用一条主要路径把任务讲清楚：用户从哪里进来，认出哪个对象，要做什么决定，执行哪个动作，最后看到什么结果。只展开和这次范围有关的分支，不为了一个小表单去设计整个产品的流程。

-浏览、比较、选择和编辑是不同任务。列表用适合比较的身份、数据或预览；只读详情不默认铺满禁用输入框；用户明确进入编辑后再显示需要的控件。需要连续批量配置的工作表可以持续编辑，但必须有一致的对象与保存语义。
+浏览、比较、选择和编辑是四种不同的任务。列表里放方便比较的东西：对象的身份、数据或预览。只读的详情页不要默认铺满禁用的输入框，等用户明确要编辑了，再显示需要的控件。要连续批量填写的表格可以一直处于编辑状态，但改的是哪个对象、什么时候算保存，全表要一致。

-同一对象与动作沿用统一名称。品牌表达可以改变外观，不随意改变返回、关闭、保存、删除等熟悉动作的含义。
+同一个对象、同一个动作，在各处用同一个名字。品牌可以改变它们的外观，但返回、关闭、保存、删除这些用户熟悉的动作，意思不能随便改。

 ## 对象身份

@@ -46,17 +46,17 @@

 每个可见动作都要有真实结果：数据变化、明确范围的预览、可观察的任务状态、导航，或者复制、下载这类本地结果。没有写入能力就不显示写操作，不用长期禁用的按钮占位；当前状态不允许的菜单项直接隐藏，不留无法解释的灰色图标。

-帮助文案只解释界面推断不出的规则、限制和风险；先修正标题、默认值或结构，不用长说明弥补流程混乱。使用原生或已有可靠控件，保持标签、焦点、键盘操作与可访问名称；校验和重要状态不只用颜色或悬停提示表达。
+帮助文案只解释从界面上看不出来的规则、限制和风险；流程乱的时候，先改标题、默认值或结构，不靠一大段说明来补。控件用原生的或项目里已有的可靠控件，标签、焦点、键盘操作和可访问名称都保留；校验结果和重要的状态，不能只用颜色或悬停提示来表示。

 ## 表单与提交

-只收集当前任务必需且无法可靠带入的信息。系统已知的值合理预填，需要用户判断的值保留可编辑性；数据属于其他对象时说明来源，不能悄悄改写源对象。
+只让用户填这次任务必须要、系统又没法可靠带出来的信息。系统已经知道的值先填好；需要用户判断的值，填好了也要能改。数据来自别的对象时，说明它是从哪里来的，不能悄悄改掉源头上的那一份。

-相关字段形成清楚的提交边界。一次用户意图只提交一次，处理中防止重复操作；结果即时生效时不再增加无意义的保存。
+哪些字段是一起提交的，要让人看得出来。用户想做一件事，就只提交一次，处理的过程中不让重复点；改了就立刻生效的地方，不再多放一个“保存”按钮。

-只有字段依赖、错误代价或任务长度确实需要时，才增加步骤、预览、草稿或额外确认。行内编辑适合简单独立字段；复杂关联编辑进入能容纳完整任务的表面。
+只有字段之间有先后依赖、填错的代价很高，或者任务确实很长时，才加步骤、预览、草稿或额外的确认。简单、独立的字段适合在行内直接改；互相关联的复杂编辑，放到装得下整个任务的弹窗、侧面板或页面里。

-校验在能够修正的位置显示原因和修正方式。提交失败保留输入、当前对象和位置；返回上一步或从源数据编辑返回时维持流程连续性。
+校验信息显示在用户能改的那个地方，写清楚错在哪里、怎么改。提交失败时，用户填的内容、当前的对象和所在的位置都要留着；退回上一步，或者去改完源数据再回来，流程要能接着往下走。

 ## 按范围表达状态

@@ -70,9 +70,9 @@
 | 后台长任务 | 给对象明确的排队、处理中、完成或失败状态及必要进度 |
 | 加载或提交失败 | 在相应范围解释原因和恢复动作，不要求用户重新寻找对象 |

-同一范围不同时表达互相矛盾的状态。局部请求不清空整页，进度不重复堆叠，等待结果不伪装成空集合。
+同一个区域里不要同时出现互相矛盾的状态。只请求一小块数据时不清空整页，进度提示不叠好几层，还在等结果的时候不显示成“没有数据”。

-占位布局应接近实际内容，不制造额外滚动。已有数据刷新时保持结果、数量与查询条件的对应关系；快速连续操作后只呈现当前意图对应的结果。
+占位的骨架要和实际内容的样子接近，不能比实际内容多出一段滚动。已有数据在刷新时，结果、数量和查询条件三者要对得上；用户连续快速操作时，只显示最后一次操作对应的结果。

 ## 模型在交互上的默认做法

@@ -80,15 +80,15 @@

 | 默认做法 | 换成 |
 | --- | --- |
-| 首页开头四张指标卡，数字没有比较基准，也引不出动作 | 首页回答“现在该处理什么”，见设计方向的“产品界面” |
+| 首页开头四张指标卡，数字没有比较基准，也引不出动作 | 首页回答“现在该处理什么”，见 [工作区骨架](direction-workspace.md) |
 | 可撤销的操作也弹确认框 | 直接执行并提供撤销；只有不可撤销的操作才确认，见“动作层级” |
 | 所有反馈都用角落里的浮动提示，包括错误 | 反馈出现在触发的位置；错误留在原处直到解决。浮动提示只用于离开视线的结果，例如已复制、已发送 |
 | 一加载就整页转圈 | 保留已有内容，只在变化的区域标示更新，见“按范围表达状态”和下文数字 |
 | 空状态只有一张插图和“暂无数据” | 说明为什么空、下一步做什么，给一个能直接开始的动作；能导入或预填示例就提供 |
 | 字段一字排开，用占位文字当标签，提交后才一起报错 | 标签常驻在输入框上方，按任务分组；离开字段时校验，提交出错时聚焦到第一个错误并说明怎么改；少数可选字段标“选填”，不给满屏必填项加星号 |
 | 按钮禁用，却不说为什么；每行末尾一排图标按钮；必要按钮只在悬停时出现 | 按“动作层级”重排：主操作一个，管理操作进“更多”，触屏和键盘都能到达 |
-| 详情和设置默认用弹窗 | 按任务选择弹窗、侧面板或完整页面，见布局与视口的“选择承载方式” |
-| 表格所有列等宽、居中 | 按“列表、表格与详情”删掉答不出用途的列；对齐方式见视觉语言的“细节” |
+| 详情和设置默认用弹窗 | 按任务选择弹窗、侧面板或完整页面，见空间、滚动与浮层的“选择承载方式” |
+| 表格所有列等宽、居中 | 按“列表、表格与详情”删掉答不出用途的列；对齐方式见视觉自查与精修的“细节” |
 | 按回车才搜索，无结果时只写“无结果” | 输入即筛选（请求较重时防抖 150–300ms）；无结果时保留查询，给出放宽条件或清除的入口 |
 | 一两个字段也拆成多步向导 | 只有步骤之间确实依赖时才分步；否则一页完成，并能看到全部范围 |
 | 保存后跳回列表，看不出刚改的是哪一条 | 回到原位置，把刚改动的对象高亮 1–2 秒 |
@@ -104,8 +104,8 @@

 ## 确认与完成

-需要等待结果的操作有可观察的生命周期。提交后保留对象与反馈；同步完成后再呈现成功，失败时保留恢复入口。
+要等一会儿才有结果的操作，从提交到结束的每个阶段都要让人看得见。提交以后，对象和反馈留在原处；等真的完成了再显示成功，失败了要留一个能重试或恢复的入口。

-可以关闭表面的后台任务，应已转为可持续观察的任务状态。关闭窗口不是取消请求；没有真实取消能力时，不把关闭或取消描述成已撤回操作。
+任务在后台跑、窗口可以先关掉的，关掉以后要有地方能继续看到它的进展。关闭窗口不等于取消请求；系统并不能真的取消时，不要把“关闭”或“取消”说成操作已经撤回。

-关键保存从界面重新读取或重新进入验证。模拟原型可以演示状态，但交付时明确模拟边界，不声称真实数据已写入。
+重要的保存要验证：重新读取一次，或者退出再进来，看数据是不是真的在。原型里可以用模拟数据演示各种状态，但交付时要说清楚哪些是模拟的，不能说真实数据已经写进去了。