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（含通则：更新器把原生错误兜底成指错方向的人话）。
This commit is contained in:
admin committed
1 parent
053a6a6723
commit
d9445b5888
126 files changed
+10345
-1401
No files matched your search
@@ -1,55 +1,50 @@
|
||||
# 工具
|
||||
|
||||
本目录自带的程序按下面的写法调用，不需要读源码；加 `--help` 打印同样的说明。
|
||||
本目录自带的程序不需要读源码。这里只写什么时候用和最常用的几条命令；全部选项、动作写法和输出文件见各自的 `--help`，写错时报错会给出照抄就能用的写法。
|
||||
|
||||
宿主有自己的浏览器工具时，查看页面、走查流程照常用。要交出下面这几样标准证据时，优先用这里的截图工具：它开一个独立的临时浏览器，不碰用户自己浏览器里的数据。本机缺 Node 22，或者没有 Chrome、Chromium、Edge 时，退回宿主工具，交出同样的几样东西。不为截图另写 Playwright 或浏览器协议脚本。
|
||||
宿主有自己的浏览器工具时，查看页面、走查流程照常用。要交证据时优先用这里的截图工具：它开一个独立的临时浏览器，不碰用户自己浏览器里的数据。本机缺 Node 22，或者没有 Chrome、Chromium、Edge 时，退回宿主工具，交出同样的证据。任务或项目已经指定了截图工具时，照用它。
|
||||
|
||||
## 截图和录屏
|
||||
|
||||
### 什么时候截，截多少
|
||||
|
||||
截图分两种用途，不要混在一起：
|
||||
|
||||
- **看一眼**：改完一批，想看效果。只截当前这一屏，一条命令。把一批改动攒在一起改完再截，不是每改一处截一次；页面没有变，就不重复截。
|
||||
- **取证**：用 `--evidence` 一次取齐状态图、并排图、遮字图、2 倍图和录屏。只在两个时候做：送评审之前，交付之前。方向首屏那一轮每个方向只截一张，不取证。
|
||||
|
||||
每一轮评审只重新取这一轮改动影响到的证据。没有动过的状态和动效，沿用上一轮的文件，交接时注明哪些是沿用的；拿不准有没有被影响到，例如改了共享样式，就重取那一项。
|
||||
|
||||
### 常用命令
|
||||
|
||||
```text
|
||||
node <skill>/scripts/shoot.mjs <页面地址或 HTML 文件> [选项]
|
||||
```
|
||||
|
||||
本地文件会用一个只监听本机的临时服务器打开。地址里带 `?` 或 `&` 时加引号，例如 `"http://127.0.0.1:3000/?state=done"`；更省事的是用 `--states`。同名文件会直接覆盖，不需要额外参数。
|
||||
|
||||
| 要什么 | 加上 |
|
||||
| --- | --- |
|
||||
| 每个状态各一张，再拼成并排图 | `--states idle,running,done,error --sheet` |
|
||||
| 同时要遮掉全部文字的版本 | 再加 `--mask` |
|
||||
| 200% 截图 | `--zoom 2` |
|
||||
| 手机和桌面各一套 | `--size 390x844,1280x900`（默认只有 390x844） |
|
||||
| 整页长图 | `--full` |
|
||||
| 截图前先操作几步 | `--steps "click .open; wait 300"` |
|
||||
| 主操作录屏，外加开始、中间、结束三帧 | `--record --steps "drag .handle 0 -80; wait 400; click .start" --hold 1500` |
|
||||
| 看一眼桌面效果 | `--size desktop`；不写时是手机 390x844 |
|
||||
| 操作几步再截 | `--steps "click .open; wait 300"` |
|
||||
| 送评审或交付前取证 | `--evidence --states idle,done --steps "send: click .send"` |
|
||||
| 落地页录一段从头滚到底 | `--record --steps "scroll 600; scroll 600; scroll 600"`，按页面长度多写几步 |
|
||||
| 截图还原：和参考图比对 | `--compare 参考.png --size <参考的逻辑尺寸>` |
|
||||
| 给用户指出问题：在元素上画框、标编号 | `--mark "1=.page-head .btn; 2=.toggle-row" --full` |
|
||||
|
||||
`--steps` 里的动作用分号隔开：`click 选择器`、`hover 选择器`、`drag 选择器 横向位移 纵向位移`、`type 选择器 文字`、`key 按键`、`scroll 纵向位移`、`wait 毫秒`。
|
||||
状态靠地址参数进入，所以页面要能用 `?state=<名字>` 直接打开每个状态。其余选项、选择器和动作的写法、输出文件和 `report.json` 的结构：运行 `node <skill>/scripts/shoot.mjs --help`。拿不准写法时先加 `--dry-run` 检查，不会启动浏览器。同时开着很多任务、截图超时的时候，加 `--timeout-scale 2`。
|
||||
|
||||
结果写进 `--out` 指定的目录，默认是 `./shots`：每个状态一张 `<状态>.png`，遮字版是 `<状态>-masked.png`，并排图是 `sheet.png` 和 `sheet-masked.png`，录屏是 `record.mp4` 和 `motion-start/mid/end.jpg`。每张图都会检查控制台错误、横向溢出和没加载出来的图片，命令最后一行给出结论，明细在 `report.json`。录屏需要本机装了 ffmpeg，没有时只留三帧。
|
||||
### 看结果
|
||||
|
||||
检查报出接口 401、404 这类和画面无关的错误时（例如访客状态下的登录接口），在交付说明里记一行就行，不为了让检查通过去改登录、接口这类业务代码。
|
||||
交给评审前先自己看一眼：默认状态是不是已经加载完，遮字版有没有把图形也一起盖掉。证据有错先重截，再交给评审。汇总里提示录屏和截图不一致时，静止的终态以截图为准，再单独重录那一段核对过渡。画面是空的 WebGL 截图不能当证据。
|
||||
|
||||
截图前先自己看一眼结果：默认状态是不是已经加载完，遮字版有没有把图形也一起盖掉。证据有错先重截，再交给评审。
|
||||
每张截图还会查一组能从页面样式里直接判断的问题，命令输出里以“默认做法提示”列出：
|
||||
|
||||
- **要改的可读性问题**：文字对比度不达标、正文小于 13px、多行正文行高过紧、首屏里停在透明状态的内容。
|
||||
- **改掉或写出理由**：有色底上的灰字、正文行太长，以及模型默认做法：标题上方的眉标和编号标签、彩色单侧边线、渐变文字、卡片里套卡片、表情符号当图标、中文界面里的英文大写标签、标题离上文比离下文还近。保留的项，在交付说明里写出它怎样服务方向。
|
||||
|
||||
检查会误报，例如真实的步骤编号、确实需要的标签；误报在交付说明里写一句。它只认得写法，判断不了好不好看：提示清零之后，仍要自己看截图。检查报出接口 401、404 这类和画面无关的错误时，在交付说明里记一行，不为了让检查通过去改登录、接口这类业务代码。
|
||||
|
||||
## 写可操作的小样
|
||||
|
||||
小样要能用地址参数直接打开每个状态，例如 `?state=done`，截图工具和评审都靠它。一个组件或一个页面只写一个文件，不要每个状态复制一份。
|
||||
方向探索阶段的首屏不做交互，用不到这一节；选定方向后做完整页面时再用。存量项目照用项目自己的技术栈。
|
||||
|
||||
颜色、字号、间距、圆角先定成十来个 CSS 变量，后面一律引用变量；同一个组件的样式用原生 CSS 嵌套写在一起。不引入 Tailwind 或 Sass 这类需要构建的工具。
|
||||
|
||||
状态和交互用 Alpine.js 写在 HTML 属性上，不手写一长段切换显示的脚本：
|
||||
|
||||
1. 复制到任务目录：`cp <skill>/assets/vendor/alpine.min.js <任务目录>/vendor/`
|
||||
2. 页面里引用：`<script defer src="vendor/alpine.min.js"></script>`
|
||||
3. 状态集中放在一个 `x-data` 里，初始状态读地址参数：
|
||||
|
||||
```html
|
||||
<main x-data="{ state: new URLSearchParams(location.search).get('state') || 'idle', amount: 40 }">
|
||||
<p x-show="state === 'done'">做好了</p>
|
||||
<input type="range" min="20" max="80" x-model.number="amount">
|
||||
<button @click="state = 'running'">开始</button>
|
||||
</main>
|
||||
```
|
||||
|
||||
放进对比页时，在 manifest 里给这个候选加 `"interactive": true`。生成器会把任务目录里引用到的 CSS 和 JS 文件内联进对比页，不用手动合并。
|
||||
|
||||
存量项目里照用项目自己的技术栈，不引入 Alpine.js。
|
||||
一个组件或一个页面只写一个文件，用地址参数切换状态，不要每个状态复制一份。颜色、字号、间距、圆角先定成十来个 CSS 变量，后面一律引用变量，不引入需要构建的工具。表单、切换、展开这类状态用 Alpine.js 写在 HTML 属性上：把 `<skill>/assets/vendor/alpine.min.js` 复制到任务目录的 `vendor/` 再引用，状态集中在一个 `x-data` 里，初始状态读地址参数。手势跟手、物理模拟、Canvas 和 WebGL 绘制放进单独的 JS 模块，每帧更新的数据不放进 Alpine 的状态。
|
||||
Reference in new issue
Block a user