dsh-super-code 0.3.11 → 0.4.0

package/builtin/skills/oil-ui/references/tools.md

@@ -0,0 +1,75 @@
+# 工具
+
+本目录自带的程序不需要读源码，命令里的 `<skill>` 换成本 Skill 的安装目录。这里只写什么时候用和最常用的几条命令；全部选项、动作写法和输出文件见各自的 `--help`，写错时报错会给出照抄就能用的写法。
+
+需要生成文件时，先按 [任务工作区](workdir.md) 确定过程输出和各工具的命令目录。没有项目约定时用 `.oil-ui/<任务名>`；显式输出路径始终优先，截图和正式图片处理还有各自的 cwd 要求。
+
+宿主有自己的浏览器工具时，查看页面、走查流程照常用。要交证据时优先用这里的截图工具：它开一个独立的临时浏览器，不碰用户自己浏览器里的数据。本机缺 Node 22，或者没有 Chrome、Chromium、Edge 时，退回宿主工具，交出同样的证据。任务或项目已经指定了截图工具时，照用它。
+
+## 截图和录屏
+
+### 什么时候截，截多少
+
+截图分两种用途，不要混在一起：
+
+- **看一眼**：改完一批，想看效果。只截当前这一屏，一条命令。把一批改动攒在一起改完再截，不是每改一处截一次；页面没有变，就不重复截。
+- **取证**：只在送评审之前、交付之前，保留足以判断的标准视口图；常规单页应用一次截取桌面与手机标准视口（`--size desktop,mobile`），并用 `--steps` 验证 1–2 个代表交互状态即可收尾。交互状态直接用 `--steps "click ..."` 触发，不要在页面代码里为了截图专门开发 `?state=<名字>` 地址参数路由；带 `sticky` 顶栏或 `100vh`/`resize` 监听的工作台不要加 `--full`（`fullPage: true`），避免产生空白拼接伪影，也不要对每个局部卡片逐一单拍。需要比较状态时加 `--sheet`，需要遮字时加 `--mask`。方向首屏那一轮每个方向只截一张，不取整套证据。
+
+动效默认用 `--frames` 生成带时间的序列图，或让评审者打开页面直接操作。只有确实要判断正常速度下的手感、且评审能播放视频时才用 `--record`，不为交付而录屏。确实需要整套证据时用 `--evidence --frames <帧数>`；满足上述录屏条件才加 `--record`。
+
+每一轮评审只重新取这一轮改动影响到的证据。没有动过的状态和动效，沿用上一轮的文件，交接时注明哪些是沿用的；拿不准有没有被影响到，例如改了共享样式，就重取那一项。评审者只提出扩大覆盖、却说不清哪条判断缺少依据时，不补图也不加一轮。
+
+### 常用命令
+
+```text
+node <skill>/scripts/shoot.mjs index.html --size desktop,mobile --out shots
+```
+
+| 要什么 | 加上 |
+| --- | --- |
+| 同时截桌面与手机标准视口 | `index.html --size desktop,mobile --out shots`（单端看一眼用 `--size desktop`；不写时是手机 390x844；只看整体版式可加 `--thumb`） |
+| 一次截完多个候选并出并排图 | 直接传候选目录（如 `explore`）或多个 HTML 文件，同一次浏览器会话截完并自动出 `sheet.png` |
+| 只看改过的局部组件或区域 | `--selector ".card"`，自动滚入视口并只截该元素区域 |
+| 操作几步再截 | `--steps "click .open; wait 300"` |
+| 需要核对长页滚动动效 | `--frames 8 --steps "scroll 600; scroll 600; scroll 600"`，按页面长度多写几步；录屏条件见上文 |
+| 给用户指出问题：在元素上画框、标编号 | `--mark "1=.page-head .btn; 2=.toggle-row"` |
+| 看清一段过渡 | `--frames 8 --steps "click .open"`，只出带时间的序列图；录屏条件见上文 |
+| 把几张图拼成一张对比图，不需要页面 | `--stitch a.png --label 修改前 --stitch b.png --label 修改后` |
+| 按共有元素统一比例并裁同一区域 | `--stitch a.png --match-width 240 --stitch b.png --match-width 300 --crop "0,0,800,600"`；以首图元素宽为准，裁切坐标在统一比例后；已知倍数时各图改用 `--scale`，完整写法见 `--help` |
+
+交互、保存、提交和失败恢复从页面真实入口开始，用 `--steps "click .open; fill #name \"内容\"; drag .card 120 0"` 或宿主浏览器真实点击，必要时连续填写、点击和等待到结果。保存后刷新或重新进入读回，失败后恢复到可重试状态；保留能对应实际结果的截图或操作记录，无法执行就写明未验证。其余选项、选择器和动作的写法、输出文件和 `report.json` 的结构：运行 `node <skill>/scripts/shoot.mjs --help`。拿不准写法时先加 `--dry-run` 检查，不会启动浏览器。超时会自动放宽时限重跑一次，仍失败时照报错里的命令重跑。
+
+### 检索和下载真实素材
+
+在项目工作目录运行，后续命令也在同一目录，搜索结果的编号才接得上：
+
+```text
+node <skill>/scripts/curate-media.mjs search "<关键词>" --kind texture --limit 6 --sheet --dir candidates
+node <skill>/scripts/curate-media.mjs search "<一组词> | <另一组词>" --sheet --dir candidates
+node <skill>/scripts/curate-media.mjs preview V1,T2 --sheet --dir candidates
+node <skill>/scripts/curate-media.mjs fetch C1,T2 --dir assets --sheet
+node <skill>/scripts/curate-media.mjs fetch V3 --dir <不上线的参考图目录>
+node <skill>/scripts/curate-media.mjs fetch T2 --maps all --resolution 1k --dir assets
+```
+
+`--kind` 支持 `all|texture|design|photo|blueprint|map|plate|science|video`。信源包括材质库、欧美与日本的博物馆和图书馆馆藏、NASA，各类别对应哪些信源见 `--help`。`all` 交错取各信源；用 `|` 可一次搜几组词。关键词多用英文，东亚题材可直接用中日文，简体搜不到时换繁体或日文写法。
+
+结果存入 `.curate-cache.json`，编号跨次搜索保留。每项 `use` 说明用途：`page` 可放进页面（CC BY/BY-SA 要署名），`check` 先看来源页，`reference` 不能放进页面；`--use page` 只留第一种。
+
+`search --sheet` 和 `preview` 出带编号、用途和原图尺寸的联系表 PNG，直接读这张图挑选，不要只看标题；同时给每项算 `look`（四边色、是否浅色纸底、哪些区域干净可压字等），并出 HTML 联系表。`fetch --sheet` 出本地联系表并检查真实宽高、完整解码；视频自动截首帧 poster。
+
+贴图默认下载 1k Diffuse，`--maps all` 拉取 Diffuse、Roughness、OpenGL Normal JPG 并校验大小与 MD5；使用与许可见 [配图](media.md#真实贴图与科学工程素材)。下载及 poster 自动写入同目录 `SOURCES.md`，兼容 `fetch "<URL>" --out assets/<文件名> --note "来源说明"`。全部选项见 `node <skill>/scripts/curate-media.mjs --help`。
+
+### 看结果
+
+交给评审前先自己看一眼：默认状态是不是已经加载完，遮字版有没有把图形也一起盖掉。证据有错先重截，再交给评审。汇总里提示录屏或序列图和截图不一致时，静止的终态以截图为准，再单独查看那一段操作或补序列图核对过渡。序列图能判断状态与变化，不能据此宣称正常速度下的手感已验证。画面是空的 WebGL 截图不能当证据。
+
+截图和取证优先用这里的截图工具。确实要自己写浏览器脚本（例如 Puppeteer 或 Playwright）时，启动参数加 `--use-mock-keychain --password-store=basic`，并用临时的用户数据目录；否则在 macOS 上会反复弹出钥匙串授权窗口，打断用户。
+
+每张截图还会查 4 项可读性与渲染硬问题（文字对比度不达标、正文小于 11px、多行正文行高过紧、首屏里停在透明状态的内容），命令输出里以“默认做法提示”列出并写进 `report.json` 的 `lint`。提示清零之后，仍要自己看截图。检查报出接口 401、404 这类和画面无关的错误时，在交付说明里记一行，不为了让检查通过去改登录、接口这类业务代码。
+
+## 写可操作的小样
+
+方向探索阶段的首屏不做交互，用不到这一节；选定方向后做完整页面时再用。存量项目优先沿用已安装的组件库、图标库、样式体系与技术栈。新建项目按用户约束、技术栈和主要交互选择组件基础，原生控件、轻量基础组件或完整组件库均可，不强制引入完整库；已有工程或交付约定优先于下面的独立 HTML 小样做法。
+
+没有工程约束、交付独立小样时，默认一个入口 `index.html`，优先将 HTML、`<style>` 与 `<script>` 内聚在单文件中，服从项目与交付约定。颜色、字号、间距、圆角先定成少量 CSS 变量，后面一律引用变量；独立小样不额外引入构建链。可用原生脚本或轻量库实现真实筛选、切换与详情交互。正式入口 HTML 的本地依赖放到同目录的 `vendor/` 再引用，过程小样及其依赖才放任务目录。

package/builtin/skills/oil-ui/references/ux-review.md

@@ -0,0 +1,23 @@
+# 轻量 UX 走查派发（主 Agent 专用）
+
+## 默认什么时候派
+
+新界面有主要操作流程（填表提交、多步流程、会保存东西的操作），或用户要求独立验证可用性时，交付前派一个全新的 UX 子 Agent 做轻量走查，和视觉评审同一轮。纯视觉小改动、方向首屏、没有可操作流程的页面和只有静态画面的评审不派。界面好不好看与任务是否符合直觉，分开验收。
+
+## 交接什么
+
+评审者按 [轻量 UX 走查](ux-reviewer.md) 执行，主 Agent 不读这份评审手册，只交接下面的材料。
+
+必给当前页面入口、主视口、必要的测试凭据或测试文件、安全边界；有运行方式限制也写清。主视口用于说明使用场景，走查者可以使用不同大小的窗口；窗口不同本身不算问题，主 Agent 不为此补做整套检查，只有问题本身与尺寸有关时才在主视口复现。不给原始 `TASK.md`、具体用户案例、预期操作路径、源代码、设计说明或历史问题。提示词用：
+
+`请读取 references/ux-reviewer.md，按照【轻量 UX 走查】执行。只通过真实页面理解产品和用户目标，自主选择一条主要路径操作，记录实际观察到的体验障碍。页面地址、主视口和必要测试材料如下；窗口可不同，仅尺寸相关的问题需要在主视口复现。`
+
+模板路径换成本 Skill 目录下的绝对路径。子 Agent 必须能操作真实页面；只能看截图或源码时，改交静态 UX 走查并标明，不说任务已经走通。它给出的产品理解、任务和路径都是它的观察结果，不是主 Agent 预先布置的脚本。
+
+主 Agent 在走查记录里留下这次隔离调用的标识（子 Agent ID、会话 ID 或运行目录）和证据位置；宿主不暴露标识时，保留能区分主 Agent 与评审者的独立上下文和操作记录。只有主 Agent 自述、无法核对独立执行者的，按自检处理，写明“未完成独立 UX 走查”，不称子 Agent 已评审。
+
+## 收到报告以后
+
+先把每条问题分成可复现的产品问题、测试工具或数据问题、仍待验证的推测；先排除后两类，不用制作意图反驳观察。保留实际路径和证据，修的是入口、反馈、上下文和恢复方式，不只补一段说明。
+
+轻量走查修正后不强制再派 UX 子 Agent；主 Agent 自己完成保存、刷新读回、失败恢复等功能验证，评审报告不能替代这一步。UX 子 Agent 能发现可观察的操作障碍，但不代表真实用户，也不据此推断真实用户成功率、满意度或耗时。

package/builtin/skills/oil-ui/references/ux-reviewer.md

@@ -0,0 +1,10 @@
+# 轻量 UX 走查（UX 子 Agent 专用）
+
+只通过真实页面或可操作的高保真原型观察，不读页面源码、开发工具、原始任务或设计说明，不猜测制作组别。没有可操作环境时明确改报“静态 UX 走查”。
+
+1. 先看页面，再用自己的话写下：这是什么产品、谁会用、最可能来完成什么。不要等待主 Agent 给任务，不把界面上的功能清单逐项当作任务清单。
+2. 从可见内容里选一条你认为最重要的路径，从真实入口走到可观察结果。每一步记“看到什么 → 为什么这样操作 → 实际发生什么”；不知道下一步时先按当前理解尝试，不故意表现迷路，也不替产品找补。
+3. 标记**卡住**（走不下去）、**走错**（动作结果与预期不符，需要退回）、**犹豫**（需要猜或停下来比较）。再记操作后是否知道正在等待、已经完成或失败，以及反馈是否出现在动作附近。不要用操作耗时推断真人效率。
+4. 只报告影响主要任务的关键问题，最多 3 条。每条分开写：**观察到的事实**（位置、操作、结果和截图/状态证据）、**原因推断**、**建议达到的结果**。事实与工具限制分不清时标为待复现，不断言是产品缺陷。
+
+输出先写产品理解、自己选择的任务、完成 / 部分完成 / 未完成及实际路径，再写关键问题和没验证什么。声音、触觉和真机手感没法验证时不当作通过。不打审美分，不声称代表真实用户，不给真实用户成功率、满意度或耗时结论。

package/builtin/skills/oil-ui/references/visual-language.md

@@ -0,0 +1,103 @@
+# 视觉语言
+
+## 目录导航
+
+- [从整体到局部](#从整体到局部)
+- [焦点与空间](#焦点与空间)
+- [字体与内容](#字体与内容)（含 [可读性是交付门槛](#可读性是交付门槛)）
+- [色彩与表面](#色彩与表面)
+- [控件与图标](#控件与图标)
+
+## 从整体到局部
+
+先看信息的焦点、构图和内容的疏密，再调空间、排版、色彩和细节。前一步已经把问题解决了，就不为了显得用心再往上加样式。
+
+项目里现成的视觉变量、组件和参考，能用就用。没有现成标准时，只定义眼下用得到的几种文字、颜色和间距，不凭空造一整套设计系统。
+
+每次修改都要说得出：哪个看得见的元素有问题，问题出在它和谁的关系上，打算怎么调，调完应该好在哪里。看源码能证明样式不一致，证明不了画面变好了。
+
+## 焦点与空间
+
+- 每个区域都要让人一眼认出最重要的那条信息或那个动作，其余信息靠更小的字、更轻的字重、更低的对比或靠边的位置退到后面；不让几种强调同时抢注意力。
+- 同一种关系用同一种间距，一组之内紧一些，组和组之间松一些。
+- 留白是用来分组、突出重点和控制节奏的。工具界面不为了显得空旷而砍掉必要的信息，品牌页面也不必把首屏塞满。
+- 不对称的版式、跨出边界的图形和很大的文字，都可以用来表达选定的方向，但局部要对得齐，阅读顺序要清楚；有意做成的不对称，不当成错误去改。
+- 区域之间怎么排由父布局管，组件只管自己里面的空间。同一段距离，不要由好几层样式各加一遍。
+- 分隔线和边框不要重复。每条线只做一件事：同一处分隔不叠双线、单线再加一个框；留白已经分开的地方不再补线；不要每个层级都画一遍线。线的粗细对应层级，例如粗线分版面、细线分栏，全页一致。线本身是风格的一部分时照样保留，只删重复的那些。
+
+## 字体与内容
+
+- 把文字分成标题、正文、辅助信息、标签和数据几种角色，每种角色的样式固定下来，层级之间的差别要够大；换不换行、留多少空间，按真实内容的长度来定。
+- 用产品实际的语言检查字形、字重和回退字体。英文样例好看，不代表中文排出来也成立；中英文混排时，看基线是否对齐、两种字看起来是否一样重。
+- 正文的行长和行高，按读起来舒服来定；密集的表格是给人扫视和比较的，不照搬文章的排版。需要上下比较或滚动变化的数字用等宽数字，独立的大字和居中的金额输入按字形好看选。
+- 重要的名称和说明，不用固定高度去裁。确实要截断时，留一个能看到完整内容的入口，并且别让相近的名称截断以后分不出谁是谁。
+- 先把具体的产品内容写出来，再调布局。按钮上写按下去会发生什么；讲产品好在哪里时写真实的用途，不用空泛的口号、编造的背书或没有意义的英文来填版面。
+
+### 可读性是交付门槛
+
+字号与行高在真实视口、实际字体和 100% 阅读尺寸下判断，缩略图只能用来判断构图。阅读型页面的中文正文通常从 16–18px 起步，产品界面正文 14–16px，每天长时间使用的高密度工具可以到 13–14px；正文无单位行高 1.6–1.75；操作文字通常 14–16px。它们是起点，不是跨产品的死规定。不要靠 9–12px 的说明、低对比细字或压缩行高营造“精致”。信息太多先删冗余、调层级或重排。
+
+多行中文标题通常先用 1.2–1.35 的行高，按真实字形检查。不要照搬英文大写海报的极紧行高，不把标题高度固定为单行，不用负外边距挤压后续内容。展示字确需更紧时，必须看过每个支持视口的实际换行并确认字形不碰撞。
+
+中文断行要主动控制：`text-wrap: pretty` 或 `balance` 只能减少孤字，不能消除。数字和单位（38 秒、47 分钟）、“不会”这类不可拆的词用不换行包起来；首屏说明、页边批注这类短段落按语义手动断句。行末只剩一两个字，或者词被拆到两行，都算缺陷。
+
+**窄幅展示字（Condensed / Compressed）**：只用于展示标题和极短的编号标签；它牺牲横向辨识度，正文和长阅读用常规宽度的字体。
+
+验收时看长标题、两到三行正文、中英混排、数字单位与字体回退；在窄屏和放大阅读后检查行间、上下区块及按钮内部。文字重叠、截断关键信息或被相邻区域压住属于未完成。先修行高、内容驱动高度和容器伸缩，再考虑减小字号。
+
+### 示例数据要像真的
+
+示例数据会暴露模板感，即使视觉层已经很好。要避开：整数指标（1,000 位用户、+10%）、张三李四和示例公司、每条都是“2 小时前”、写着“标题”“描述”的占位字、页面上反复出现的“了解更多”“立即开始”。真实数据是不整齐的：1,238 位用户、+1.83%，时间有“刚刚”“昨天 16:12”“3 月 14 日”；名字有长有短，顺带验证长名字的排版。按钮说出具体动作，例如“保存草稿”“周二发送”。一页上有很多演示（组件目录、模板库、功能展示）时，让它们共用一个具体的虚构场景：同一个产品、同一批人、同一组文件和数字，演示之间互相呼应，比各自编一条“示例标题”可信得多；不要把库名、技术栈当成演示内容。
+
+## 色彩与表面
+
+每种颜色都有固定的用处：文字、背景、动作、选中或状态。品牌色和表示状态的颜色可以同时存在，但重要的状态不能只靠颜色来区分。
+
+边框、阴影、材质和渐变要和方向一致，并且真的在帮忙：分出层次、带出氛围，或者让人认出品牌。紫色、圆角和渐变都不是禁用项；出问题的是没有理由地到处重复、主次不分，或者不适合这个任务。
+
+不要给每张普通卡片都配上不同的强调色、粗边框和重阴影。套在里面的轮廓，要和外面的容器协调。
+
+表面层级可以用色温和色相的偏移来区分，不只靠明暗。配色怎样选，见 [设计方向](design-direction.md) 的“定色彩”；这一节只管颜色怎样用。
+
+质感按调性的完成度取用，不混用：
+- 精致一端：公差小、层次细，具体手段从这个方向的生成引擎里找。
+- 粗粝一端：手工和印刷留下的痕迹，从这个方向的生成引擎里找，不套一组固定的道具。
+
+**单色与双色体系**：除了多级中性灰加一种强调色，也可以全页只用一种主色和一种底色，次级信息、边框和禁用态都由主色按透明度或和底色混合派生。
+
+**正反色块交替**：长页面各区块可以在深底亮字与浅底深字之间以硬边直接切换，不用渐变过渡，形成清楚的段落停顿。
+
+在实际的背景上看一遍文字、控件的边界、焦点和选中态是否看得清，背景是图片、半透明或会动的时候尤其要看。项目已有可访问性要求的，照它来；读内容和做基本操作，都不该让人靠猜。
+
+## 控件与图标
+
+需要通用图标时默认选一套成熟图标库，存量项目优先沿用已安装的库。统一视觉尺寸、线宽和与文字的对齐，不混用字符、Emoji 和不同风格的图标充当导航或操作标识；文字中的标点和有语义的箭头不因此变成必须替换的图标。品牌专属素材按真实身份处理，不给每个标题都硬配一个图标。
+
+能点的东西要让人看得出能点，点了要有反馈。默认、按下、聚焦、选中、禁用和处理中是不同的意思，样子也要不同；只在鼠标悬停时才出现的入口，触屏和键盘也要有办法到达。状态变化时，点击区域不变大变小，也不挤动旁边的布局。
+
+控件是一套语法：圆角、描边、字重、阴影、按下时的位移、选中的表达和状态图标，在按钮、输入、标签、开关和空状态之间用同一套逻辑。组件库提供基础结构与交互，仍需按设计系统调整字号、间距、颜色和密度，保留语义与可访问行为。方向不只贯穿整页，也贯穿每个控件；仅换组件库的主色，不能代替这些设计决定。
+
+陌生图标配可见文字；纯图标按钮仍需可访问名称。箭头符号有含义：↗ 表示打开新页面或外部链接，提交、检查这类原地动作不用它。静态标签和装饰不要伪装成按钮，行内按钮不要误触外层卡片动作。
+
+### 图标库也会趋同
+
+模型的默认是 Lucide 或 Heroicons：24px、2px 描边、圆头端点。库本身没有问题，问题是每个方向都用同一套、同一种摆法。图标和字体一样是方向的一部分，在方向卡里写明用哪一套、什么粗细和端点，或者干脆不用。
+
+| 方向的气质 | 可以考虑 | 特点 |
+| --- | --- | --- |
+| 精致、编辑、奢侈 | Phosphor 的 Thin 或 Light，Iconoir | 细描边，配细字重的衬线或无衬线 |
+| 工业、仪器、企业工具 | Carbon，Material Symbols 的 Sharp，Radix Icons | 直角端点、网格严格；Radix 专为 15px 的紧凑界面设计 |
+| 友好、圆润、消费 | Phosphor 的 Fill 或 Duotone，MingCute | 圆角端点，实心或双色 |
+| 中文产品，需要大量业务图标 | IconPark，Remix Icon | 覆盖面广；IconPark 能调描边粗细、端点和主题 |
+| 需要连续调粗细和填充 | Material Symbols | 可变字体，填充、字重、光学尺寸都能连续调节 |
+| 像素、游戏、复古 | Pixelarticons | 像素网格 |
+| 品牌标志 | Simple Icons | 各品牌标志的矢量形状 |
+
+用 Iconify 可以按名称取到上面大多数库的单个 SVG。
+
+- **一个产品只用一套。** 需要补缺时，挑描边、端点和圆角一致的，统一成相同的画布尺寸和描边宽度。
+- **粗细跟字重走。** 图标描边接近同尺寸正文的笔画粗细：细字配 1–1.5px，粗黑体配 2px 以上或实心。图标尺寸约为字号的 1–1.25 倍，按视觉中心和文字对齐，不按外框。
+- **能不用就不用。** 编辑类方向常用字符本身：→ ↗ ※ §、编号、缩写。只在能加快识别的地方用图标。
+- **品牌时刻手绘。** 核心动作、空状态这类少数位置，可以用方向自己的线条语言画专属的线条图标或小插图；通用动作仍用库。角色、道具和场景这类主视觉不靠手画 SVG，见 [素材](media.md)。
+- **小样内联。** 自包含小样只内联用到的 SVG，不引用图标字体或 CDN。存量项目沿用已有的库，换库属于改版。
+- **核对许可。** 多数是 MIT、Apache 或 ISC；SF Symbols 只能用在 Apple 平台的界面里，不能用于网页；需要署名的库按要求署名。

package/builtin/skills/oil-ui/references/visual-review.md

@@ -0,0 +1,35 @@
+# 视觉评审派发协议 (主 Agent 专用)
+
+主 Agent 用这份文件派发独立评审。打分标准和检查规则在 [评审手册](reviewer-manual.md) 里，由评审者读；主 Agent 不读，只按下面的清单交接。调用方已指定领域标准时，把它和任务模式一并交接；冲突的检查项按领域覆盖，是否打分与是否只读仍由任务决定。
+
+## 1. 什么时候该派发？触发什么模式？
+
+当你完成了一个关键页面、设计方案或改动后，按以下清单触发对应的评审子 Agent：
+
+| 你做了什么改动 | 子 Agent 的提示词 (Prompt) 模板 |
+| --- | --- |
+| 探索了新界面，或推翻现状重新设计（重塑） | `请读取 references/reviewer-manual.md，按照【全新界面与改版评审】标准，评审这些截图，并给出 1-10 的打分。` |
+| **给已有界面评审**：在已有界面上整理、升级、润色或扩展 | `请读取 references/reviewer-manual.md，按照【存量已有界面润色评审】标准，对比提供的现状规范，指出偏离点。不打分。` |
+| 小改动、单处间距或颜色微调 | **无需派发子 Agent**，主 Agent 结合上下文自行核对即可。 |
+
+模板里的路径换成本 Skill 目录下的绝对路径：子 Agent 的工作目录不是本目录。派发时在模板末尾统一加：`先看代表画面的整体构图、文字可读性和主操作是否可见，再按对应标准评审；现有证据足以判断时不追加取证，不要求全语言、全页面、全状态截图。`
+
+## 2. 派发前，主 Agent 要准备的“交接清单”
+
+调用宿主提供的隔离执行能力时，必须提供以下物料：
+- **必给**：按 [工具](tools.md) 的默认范围选出的当前版本截图及按需取得的动效证据（注明设备视口）、用户原始任务、设计边界和约束；有方向卡时，再给北极星那一句。方向卡里其他需要评审知道的硬性约束，例如品牌要求每屏出现字标，摘成一句写进约束，不交整张方向卡。
+- **如果有**：现有项目的色彩规范、组件约束（存量老项目必须给）；方向卡的选色记录，即“色彩”一栏里颜色来自这个产品的什么那一句；项目里有 `DESIGN.md` 或同类设计文档时，存量润色评审整份给出并以它为标准，新界面与改版评审只把其中的品牌资产和“不要做”摘进约束。
+- **不给**：源代码、为自己的做法辩护的说明、之前评审打过的分数（评分要独立）。
+
+证据必须属于当前版本，且能被评审者访问；这一轮没有改到的状态和动效，可以沿用上一轮的证据文件，交接时注明哪些是沿用的。长页提供能看清整体节奏的整页图；文字或关键细节无法判断时，只补对应局部，细节图不能替代整体构图。
+
+动效不用逐项备证据：交已有序列图，或给评审能直接操作的页面地址；录屏只按 [工具](tools.md) 的条件取用，不为每个状态补录。只有现有证据无法支持结论时，才让它补看对应操作，不重走已经能判断的流程。
+没有隔离、能看图的执行者时，主 Agent 仍不读手册，结合实际截图按所属领域入口自查，交付时写明“未独立评审”；没有实际画面时不打视觉分。
+
+## 3. 主 Agent 如何处理子 Agent 的反馈
+
+子 Agent 返回报告后，按以下原则修改：
+- **第一条是“重做”**：回到方向卡，重定被点名区块的骨架或主视觉，不逐条修补。
+- **按清单顺序改**：问题清单从影响最大的一条往下改；“保留”那一行记进设计说明，改的时候对照，别把它修平。
+- **落到具体调整**：把子 Agent 的高层要求（如“太挤”“层级不清”）落成间距、字号和阴影的实际调整。子 Agent 提议更改用户锁定的品牌色或大框架时，写一句理由后不采纳。
+- **防止死循环**：如果双方审美意见陷入僵持、来回横跳且无可见收益，保留你认为最佳的版本并停止循环。

package/builtin/skills/oil-ui/references/workdir.md

@@ -0,0 +1,64 @@
+# 任务工作区
+
+把过程文件和正式交付分开。`.oil-ui` 是项目里的本地工作区，不是交付目录，也不是另一套设计规范。
+
+## 优先级与边界
+
+- 用户指定的输出路径和项目已有约定优先。项目已经规定 `_work/`、`shots/` 或其他过程目录时沿用，不另建 `.oil-ui`，也不迁移旧文件。
+- 没有约定时，从项目根目录使用 `.oil-ui/<任务名>`。任务名用简短、可辨认的名称；同名目录属于别的任务时加后缀，不覆盖。
+- 真实代码、正式测试、最终文档和线上引用的资产仍写用户项目。页面、构建配置、样式和脚本不得引用 `.oil-ui`。
+- 不把凭据、未脱敏的用户数据或令牌写进工作区。不自动清理历史任务；删除、迁移和对外上传仍需授权。
+
+## 开始任务
+
+先读项目的 `AGENTS.md`、`DESIGN.md` 或同类规范，再决定工作目录。没有这些文件不影响开始。只有确定使用 `.oil-ui` 时，才检查并准备下面的目录；项目已有其他过程目录约定时不创建它。
+
+`.oil-ui` 已存在但不是目录，或者它是指向别处的符号链接时，不往里写，说明冲突并由用户决定。已是普通目录时复用，不清空。每个任务使用独立子目录，继续同一任务时才复用该子目录。
+
+使用 `.oil-ui` 且 `.gitignore` 不存在时写入：
+
+```gitignore
+*
+!.gitignore
+```
+
+它只忽略过程文件，不修改项目根目录的 `.gitignore`。已有这个文件但内容不同时保留原文，并告诉用户过程文件可能出现在 Git 状态里。需要提交的证据或文档应明确放到项目正式位置，不改变忽略规则。
+
+## 过程文件放哪
+
+按实际需要创建子目录，不为形式完整创建空目录：
+
+- `explore/`：候选方案、调研、未确认的设计草稿和临时小样。
+- `assets/`：原始素材、中间变体和素材缓存。
+- `shots/`：截图、录屏和评审证据。
+- `logs/`：命令日志和临时输出。
+
+需要长期保存的正式测试、设计规范和交付文档不藏在这里。进行中的迁移状态留在任务目录；规范条目的确认与推断按存量项目的规则标记，不把推断写成用户确认。
+
+## 工具的命令目录与输出
+
+不是所有工具都一律从任务目录运行。根据页面资源和 HTML 引用基准选择命令目录，过程输出统一放进任务目录。显式 `--out`、`--dir`、`--cache` 和其他输出参数始终优先，不重新解释。
+
+- **截图与录屏**：用 `--root <项目根>` 明确静态服务根，并用 `--out .oil-ui/<任务名>/shots` 指定输出。这样嵌套页面仍能加载项目共享资源，截图则留在工作区；`--root` 只决定服务范围，不决定截图输出位置。
+- **素材检索**：从任务目录运行 `curate-media.mjs`，默认 `assets/` 和 `.curate-cache.json` 就会留在任务目录。显式 `--dir` 指向其他位置时，工具可能回退读取该目录或父目录的已有缓存；需要任务隔离时，同时显式指定本任务的 `--cache .curate-cache.json`，需要共享时再复用旧缓存。
+- **对比页**：候选放在任务目录的 `explore/`，`build_explorer.py` 会默认把 `style-explorer.html` 生成在旁边。
+- **生图**：最终结果要成为页面资产时，用 `--out` 直接写到项目正式资产目录。
+- **图片处理**：需要复制正式 `srcset` 时，从项目根目录运行 `prep-image.mjs` 并输出到正式资产目录。它的片段按命令目录计算，不要从任务目录复制相对路径到正式页面。
+
+工具选项见 [工具](tools.md)。中间原图可以留在工作区，但最终 HTML 及其依赖只能引用项目正式位置里的文件。
+
+## 存量项目续作
+
+未确认的方向草稿和进行中的迁移状态留在工作区。项目已有设计规范文件的读取、确认、推断标记、更新和入口按该文件及项目约定执行，不把过程草稿当成项目规范，也不另写一套重复规则。
+
+## 交付检查与停止
+
+交付前核对最终改动，不只看命令是否成功：
+
+- `git diff` 中只有正式交付、必要的规范更新和用户要求的文件。`git status` 里的过程文件只能作为未跟踪项保留，不能加入提交；`.oil-ui/.gitignore` 是允许保留的工作区配置。
+- 已有不同忽略规则导致过程文件出现在未跟踪项时，列出来并说明，不为了消除提示而删除、迁移或改写规则。
+- 正式代码和页面没有 `.oil-ui` 引用，所引用的资产都存在于项目正式位置。
+- 项目根目录没有意外新增的候选、截图或缓存；旧文件没有被移动或删除。
+- 交付说明给出正式文件和工作区证据的位置，并运行项目相应检查。
+
+现有约定和工具已经能完成时，不新增目录管理程序。只有真实任务反复出现建错目录、覆盖任务或误交付时，才把初始化或检查做成脚本。