修：draw-ui / oil-motion 原被当子模块指针收录 ⇒ 改为正常文件入库（两份内容原先对别人是空的）

一、问题（本轮实测）
`draw-ui` 与 `oil-motion` 目录里**各自带一个内嵌 `.git`** ⇒ 上一次提交把它们记成了 **gitlink（子模块指针）**
⇒ 仓库里只存了一个不属于任何远端的 commit id，**别人克隆下来这两份是空的** ✗（`git status` 显示 ` m draw-ui` / ` m oil-motion` ＝ 子模块内容有改动）。

二、处置（可回退）
· 把两处的 `.git` **挪走**（⛔ 不是删除）⇒ `归档/内嵌git-20261008/{draw-ui,oil-motion}.git`；
· `git rm --cached` 掉那两个 gitlink，再 `git add` 两个目录 ⇒ **按正常文件入库**（内容才真的进仓库）。

三、副作用（如实记）
挪走 `.git` 后，这两个技能**不能再原地 `git pull` 取上游更新**（要更新得重新拉一份覆盖）；
如需恢复其本地仓库，把 `归档/内嵌git-20261008/` 里的 `.git` 挪回原处即可。

draw-ui/references/api-key-setup.md

@@ -0,0 +1,52 @@
+# API Key 配置与业务读取
+
+已有宿主安全配置或可信运行环境注入时直接复用。首次在桌面填写或更换 Key 时使用随附统一页面，不能用“已支持环境变量”或终端隐藏输入代替页面接入。只为用户选择的外部服务配置；内置能力、离线处理和已有官方登录不要求额外 Key。
+
+## 首次配置
+
+将当前 SKILL.md 所在绝对目录记为 `SKILL_DIR`。页面需要 Node.js 22.18+，首次在组件目录安装锁定依赖：
+
+```bash
+npm --prefix "$SKILL_DIR/scripts/credential-ui" ci --ignore-scripts
+node "$SKILL_DIR/scripts/credential-ui/src/profile.ts" status default
+node "$SKILL_DIR/scripts/credential-ui/src/profile.ts" setup default
+```
+
+先查 status：退出码 0 表示当前业务凭据可读取，2 表示缺失，1 表示配置或系统后端失败。缺失或用户要求更换时才启动 setup，把返回的本机链接展示给用户，由用户亲自填写保存。不要自动操作真实 Key 页面，不让用户贴进聊天。
+
+页面不回填原值；已有项留空保留，替换需要用户确认。只把 `saved` 当作全部保存成功；`partial`、超时和中断后先重新查状态，再补未完成项。配置成功仅证明保存和可读取，实际 API 可用性以业务调用为准。
+
+## 服务与用途绑定
+
+| 配置名 | 业务环境变量 | 系统凭据引用 |
+| --- | --- | --- |
+| default | `ZENMUX_API_KEY` | `draw-ui/zenmux/default` |
+| openai | `OPENAI_API_KEY` | `draw-ui/openai/default` |
+
+`default` 是脚本已有默认适配器，并不授权调用收费服务。用户选另一适配器时，同时选择对应配置名与业务参数，不能只换 Key。服务真实名称、接口和数据范围见原有依赖说明；以上变量名保留程序兼容。
+
+一个服务的图片和视频共用同一 Key，不重复创建。多个服务各用独立声明；需要同页填写时用组件的 `configure-page` 组合所选声明，见[组件说明](../scripts/credential-ui/README.md)。不要求填写用户没有使用的服务。
+
+## 运行业务
+
+通过以下入口运行本 Skill 的真实脚本，`--` 后保留原业务参数：
+
+```bash
+node "$SKILL_DIR/scripts/credential-ui/src/profile.ts" run default -- python3 "$SKILL_DIR/scripts/generate_image.py" --provider zenmux --type wide --name dashboard --prompt "页面设计要求"
+```
+
+环境变量优先；缺失时仅从系统库读取当前配置所需的 Key，并只注入可信业务子进程。参数、普通文件和状态输出都不含 Key。使用页面保存的凭据后，后续云端业务命令同样经 run 入口执行，不能只启动配置页后直接运行一个仍仅读环境变量的程序。`--help` 示例只检查业务用法，不表示已调用服务。
+
+系统后端分别为 macOS 钥匙串、Windows 凭据管理器、Linux Secret Service。Linux 需要 secret-tool、用户 D-Bus 和已解锁的桌面凭据服务；缺少后端时停止，不自动安装、解锁或降级明文。当前 macOS 组件有原生假凭据验证；Windows/Linux 适配仍需实机验收。CI、容器与远程服务器使用已有 Secret 注入，不把本机页面开放到网络。
+
+原配置不自动迁移或删除；页面保存不代表旧明文文件已经清理。已有程序专用配置、账号或不同凭据引用按其原流程保留，不跨账号覆盖。凭据属于当前系统用户；正常流程不将其传入对话，不代表对同用户任意代码执行的强隔离。
+
+## 验证
+
+```bash
+npm --prefix "$SKILL_DIR/scripts/credential-ui" run check
+npm --prefix "$SKILL_DIR/scripts/credential-ui" run build
+npm --prefix "$SKILL_DIR/scripts/credential-ui" test
+```
+
+测试使用假后端覆盖正式页面、同页 HTTP 保存、业务变量读取、部分失败恢复和脱敏；不操作用户真实页面。原生测试 `npm run test:native` 仅创建随机测试引用并清理，不验证实际服务额度或业务效果。

draw-ui/references/calibration.md

@@ -0,0 +1,47 @@
+# 测量与还原校准
+
+视觉判断负责选区、主体、构图和字体层级；程序负责尺寸、坐标、颜色统计与偏差。先确认原图尺寸与 CSS 逻辑视口的映射，截图像素不能直接当作 CSS 像素。
+
+## 选择验证范围
+
+- 浏览器页面精准还原：执行下方完整流程，字段和命令按 [测量与采集接口](reference-measurement.md) 使用。
+- 组件局部修改：只标注目标区域和必要的相邻锚点，可复用已核对的基线，不要求重新标注整页。
+- 只有图片或非 DOM 渲染：保留图像测量，使用接口文档的图片比较分支；小程序、canvas 等使用对应工具取证，不伪造浏览器元数据。
+
+## 实现前建立基线
+
+1. 选择少量关键锚点：区块起点、容器边距、重复网格、标题与素材容器。按原图像素填写区域清单；浏览器还原同时填写预计选择器、页面地址、视口和截图条件。
+2. 运行 `measure_reference.py`，打开标注图确认范围，再检查颜色与几何统计。选区不准先修清单；程序不会自动识别正确边界。
+3. 从统计选择少量公共变量和布局约束。浏览器还原运行 `prepare_capture.py` 生成首轮采集文件，将测量事实、推断和实现选择分开记入 `round-notes.md`，再编写布局与样式。
+
+测量时保留这些区别：
+
+| 对象 | 判断方式 |
+| --- | --- |
+| 色面 | 在内部避开文字、摄影和高光；同时看中位数与分位数，波动大时检查渐变或污染，不把每个采样值变成 CSS 变量 |
+| 重复组件 | 比较宽度与间距分布；小幅采样波动可归为公共规格，明显不同的比例应保留，不先假定等宽 |
+| 文字 | 元素外框、文本行盒和可见字形分别判断；字形框不参与 DOM 外框比较，不能靠缩短标题块宽度修复字形差异 |
+| 装饰与素材 | 斜切边界与正文几何分开；图片按既定容器比例、主体位置和遮挡范围检查，规格冲突时回到素材流程 |
+
+## 实现后采集与验收
+
+1. 启动本地服务并核对项目身份。端口冲突时保留原进程、另选端口并更新基线；启动失败不继续导航。静态 HTML 可用接口文档的 `--preflight` 检查，退出码为 0 才继续；动态应用按项目实际身份标记核对。
+2. 按宿主浏览器流程打开目标页面，核对实际 URL、标题、视口和 DPR。每轮重新读取，不假定模拟设置跨导航或会话保留；页面身份不符时停止交互，截图条件不符时重新设置并采集。
+3. 等待字体和图片完成，检查本轮替换资源是否真正更新；背景图、视频和 canvas 需额外检查。冻结动画或等待稳定状态，采集期间不改变页面、滚动、视口或资源状态。
+4. 在主文档执行本轮 `collect.js`，将真实元数据与截图保存为 `capture.json`、`candidate.png`。元数据中的 `full_page` 和 `screenshot_scale` 必须来自实际截图选项，再运行 `verify_capture.py`。
+5. 读取诊断与偏差报告，在目标显示尺寸下目视复核并实际操作。程序检查通过只表示采集前提成立，不证明没有遮挡、字体正确或交互可用。
+
+人工与操作验收集中检查：
+
+- 元素实际显示，内部布局与外框一致，素材没有遮挡文字、控件或导航。
+- 真正用于字符渲染的字体、字重、行高和换行符合参考；CSS 候选列表与字体加载完成不能证明选中了原字体。
+- 主要操作、失败反馈、长内容和响应式切换正常；切换后复核导航、换行与内容高度。
+- Logo、细字和素材边缘按最终显示大小及目标 DPR 检查，不能依靠长页缩略图。240×80 CSS 区域在 DPR 2 下需要 480×160 的设备像素截图才能作为该分辨率的证据。
+
+## 修正与复验
+
+引用 `geometry.md` 的区域名，在 `round-notes.md` 记录本轮假设、调整变量及观察到的收益与退步。连续区块同向偏移时，先查最早发生偏移的位置；调整顺序为页面宽度与容器 → 字体与换行 → 间距 → 素材裁切与装饰，不给后续区块逐个打位移补丁。
+
+下一轮从同一测量结果生成新目录，重新采集，并通过 `--previous` 比较前轮报告。参考图、标注或截图条件改变时重新测量建立基线，不沿用前后改善结论；条件失败时保留原始记录，修正后重采，不改派生文件绕过检查。
+
+像素差异和几何偏差帮助定位变化，不转换成“还原度百分比”。摄影、近似字体和品牌原稿缺失造成的差异单独说明。最终结论同时依据局部画面、程序报告和真实操作；案例与轮次记录留在任务目录。

draw-ui/references/full-page.md

@@ -0,0 +1,49 @@
+# 完整落地页与长图
+
+## 页面范围优先于画布比例
+
+完整桌面落地页保持桌面内容宽度，向下展开至页脚。用户明确只要首屏时才缩小范围。竖向长图不是移动端页面，也不是把所有模块挤进一张3:4海报。
+
+先列出有序区块及各自用途，再估计页面高度。按业务选择必要内容：价值说明、产品或服务、使用流程、可信证据、常见问题和主要转化入口等；这些不是强制模块套餐。没有材料时不虚构客户评价、销量或认证，可使用明确标注的示例或合理省略。
+
+为每个区块给一个稳定ID，记录内容和统一的设计规则。导航只在顶部出现，页脚只在结尾出现。完整输出必须覆盖已承诺的所有区块。
+
+内容区块清单不是视觉模板。围绕选定构思安排阅读节奏，主视觉、重点说明、细节列表和结尾应有不同的分量；不要让所有区块都变成居中标题、等宽卡片和同样的上下留白。保持字体、组件与对齐体系一致，不代表各区块的构图必须相同。
+
+## 根据工具能力选择生成方式
+
+先检查当前接口的尺寸支持；本 Skill 脚本的比例预设不等于任意长图能力。不要反复尝试未经确认的超长尺寸。
+
+- 工具支持所需长画布且文字可读：直接生成完整长页，再核对区块和返回尺寸。
+- 长度超出能力或一次生成会让正文过小：在区块边界分段。每段保持相同像素宽度、逻辑桌面宽度、字体、内容容器和组件尺度，不包含设备外框。
+
+分段时先生成并检查第一段，把统一规则和必要参考用于后续片段。段落高度由内容决定，不把每段都当成独立首屏。每次提示明确本段ID、包含哪些区块、是否含导航/页脚，边界不重复标题或装饰。模型对比时两边必须采用相同的分段计划；共享规则和参考输入，不能把某一方生成结果喂给另一方。
+
+生成多段涉及额外计费时，遵循当前任务已授权的数量和成本范围。不要将一张长页的承诺静默扩成无限重试。
+
+## 组装与检查
+
+分段图先目视确认接缝处的背景、内容容器、间距和尺度，再用 `scripts/assemble_page.py` 组装。程序检查顺序、数量、格式和等宽，不会判断审美，也不会通过缩放掩盖宽度不一致。
+
+在任务目录写入清单。`expected_sections` 是生成前确定的片段ID顺序，`sections` 按相同顺序列出实际图片；路径相对于清单文件解析：
+
+```json
+{
+  "expected_sections": ["intro", "details", "closing"],
+  "sections": [
+    {"id": "intro", "image": "parts/intro.png"},
+    {"id": "details", "image": "parts/details.png"},
+    {"id": "closing", "image": "parts/closing.png"}
+  ]
+}
+```
+
+```bash
+python3 scripts/assemble_page.py --manifest /path/to/page.json --output /path/to/full-page.png
+```
+
+只拼接没有重复或重叠内容的分段，不自动裁切、不拉伸、不补生成内容。宽度不一致、缺段、重复ID、顺序不符或输出已存在时失败并保留原图；需要替换已有输出时才使用 `--force`。
+
+组装后实际打开整张长图检查完整性，再按目标逻辑宽度逐段检查文字与组件。交付完整长图、分段原图和实现说明，不能只交一组散图或首屏。
+
+若随后还原代码，以完整预览作为参考，按 [测量与校准](calibration.md) 建立基线，再进入目标平台实现流程。

draw-ui/references/generation.md

@@ -0,0 +1,37 @@
+# 生成工具与接口边界
+
+工具选择以主流程为准。本文件说明可选服务适配器与图片输入边界；适配器名称不代表通用设计流程依赖特定宿主。
+
+外部服务凭据按 [API Key 配置与业务读取](api-key-setup.md) 接入。以下示例的 SKILL_DIR 是本 Skill 的绝对目录；已通过配置页保存的凭据须由包装入口注入。命令显式使用 bash，避免下载压缩包安装时丢失可执行权限。
+
+脚本默认使用 ZenMux，默认模型为 `openai/gpt-image-2`；可用 `--model` 显式覆盖。调用前按当前服务目录确认用户指定的模型ID，遇到歧义先解析，不猜测收费版本。
+
+```bash
+node "$SKILL_DIR/scripts/credential-ui/src/profile.ts" run default -- bash "$SKILL_DIR/scripts/ask_draw.sh" --type wide --name "dashboard" --prompt "页面提示词"
+node "$SKILL_DIR/scripts/credential-ui/src/profile.ts" run default -- bash "$SKILL_DIR/scripts/ask_draw.sh" --frame /path/to/reference.png --type wide --name "dashboard" --prompt "保留固定区域的页面提示词"
+```
+
+| 参数 | 作用 |
+| --- | --- |
+| `--type` | `ultrawide` 21:9、`wide` 16:9、`classic` 4:3、`square` 1:1、`portrait` 3:4；默认wide |
+| `--frame` / `--ref` | 固定框架参考图 / 可重复传入的参考图 |
+| `--name` / `-o` | 文件名 / 输出路径 |
+| `--model` | 模型ID覆盖 |
+| `--provider` | `zenmux` 或 `codex`，后者是脚本保留的 OpenAI Responses API 适配器名称 |
+| `--mode` | `normal`、`replicate`、`frame-lock`、`asset-redraw` |
+
+`portrait` 是画布预设，不能直接代表真实手机视口或完整长页。脚本的 ZenMux OpenAI 分支使用 `generate_images/edit_image` 时未传比例参数；返回尺寸不能由 `--type` 或元数据中的 `aspect_ratio` 推断。需要精确尺寸时使用宿主已有、已确认支持尺寸参数的调用方式；完成后读取实际图片尺寸。不要为修正比例而拉伸图片。
+
+优先通过已有安全凭据管理在运行时注入环境变量，不新建明文凭据文件。ZenMux 密钥兼容脚本的查找顺序：`ZENMUX_API_KEY`、项目及上层 `.env.local`、`~/.config/see/api_key`。使用其他宿主的 ZenMux 工具时沿用其安全凭据管理，不复制密钥或新建明文副本。
+
+OpenAI Responses API 适配器通过 `--provider codex` 选择，读取 `OPENAI_IMAGE_API_KEY` 或 `OPENAI_API_KEY`，不复用宿主登录凭据。Windows 使用 `scripts/ask_draw.ps1`，macOS/Linux 使用 `scripts/ask_draw.sh`。需要设置密钥时按 API Key 配置文档复用现成入口或展示固定页面，不输出密钥值。选择 `--provider codex` 时使用 `run openai` 包装；默认适配器使用 `run default`。
+
+生图成功会输出 `output_path` 和 `metadata_path`。实际打开并检查文件；记录使用的模型、提示词、参考、真实尺寸和待修正项。已有文件应使用新路径保留，不静默覆盖。
+
+失败时保留原始错误与有效产物。鉴权、余额、参数或型号错误先解决原因；只对明确暂时性错误做有上限、已授权的重试，不把所有断连都认作正常现象。对结果不满意的重画属于新的生成，不伪装成网络重试。
+
+## 参考图能力核验
+
+用户提供视觉参考时，分别核验模型、服务接口和当前脚本能否接收图片。脚本没有参考图参数不等于模型不支持；先查对应服务官方接口，再决定是否通过已有SDK或任务内适配器传入。未实际提交图片时，只能称为文字提炼参考，不能说模型看过原图。
+
+ZenMux的OpenAI兼容接口公开支持POST /images/edits；本地参考图优先使用multipart/form-data上传实际文件，文件字段为image[]；JSON请求使用images数组，每项为image_url，可传base64 data URL。不要误用generations接口或将路径字符串冒充图像输入。区分请求封装、传输形式与模型能力，按当前接口返回验证成功，不能根据一种格式的失败断言整个模型不支持参考图。当前具体模型仍需校验，并检查响应。接口依据：https://zenmux.ai/docs/api/openai/create-image-edit.html 。模型对比按 [UI 设计与验收](ui-design.md) 固定输入。

draw-ui/references/html-reconstruction.md

@@ -0,0 +1,44 @@
+# HTML 与微信小程序实现
+
+沿用已有设计说明，并按 [测量与校准](calibration.md) 固定参考基线。组件与素材的划分使用主流程；需要裁图、重绘或透明素材时转到 [素材流程](reference-assets.md)。
+
+## 独立 HTML
+
+用语义 HTML、CSS 与必要的 JavaScript 建立页面。采用正常文档流、Grid 或 Flex 组织区块，重复组件共用样式；不要用整图背景或大量任意定位承载正文与操作。完整长页先覆盖所有区块。
+
+交互对应真实用途，覆盖主要操作及其状态。视觉演示没有后端能力时，明确演示边界，不伪造提交成功或可用服务。
+
+## 微信小程序
+
+直接使用目标项目的文件模型，不先生成 HTML 再机械转换：
+
+| 文件 | 职责 |
+| --- | --- |
+| `*.wxml` | 结构、卡片、控件与文字 |
+| `*.wxss` | 布局、rpx 尺寸、字体和视觉样式 |
+| `*.ts`／`*.js` | 页面数据、状态与交互 |
+| `${miniprogramRoot}/assets/` | 独立图片素材，沿用项目目录约定 |
+
+优先使用现有组件和图标。简单装饰用 WXSS；复杂插画使用质量足够的独立素材，是否重绘由素材流程判断。
+
+资源路径从配置中的 `miniprogramRoot` 解析。例如该值为 `miniprogram/` 时，文件放在 `miniprogram/assets/`，WXML 引用：
+
+```xml
+<image class="hero" src="/assets/hero.png" mode="aspectFit" />
+<image class="banner" src="/assets/banner.png" mode="widthFix" />
+```
+
+`aspectFit` 用于固定容器内完整显示主体；`widthFix` 用于按宽度保持图片比例。每次只选一个合法 mode，明确容器宽度与页面重排方式。
+
+小程序渲染必须在微信开发者工具或对应真机环境验证，普通浏览器只能验证 HTML 原型。自动化能力可使用 `miniprogram-automator`；固定设备预设、页面视口与 DPR，截图仅取与参考一致的页面区域，排除状态栏、胶囊和工具栏。像素对比走校准文档的非 DOM 分支，交互仍在小程序内实际操作；模拟器与真机结果分开记录。
+
+## 排版实现要点
+
+| 项目 | 实现时关注 |
+| --- | --- |
+| 字体 | 标题、正文、导航分别匹配家族和字重；使用实际可用字体并配置 fallback，近似字体注明差异 |
+| 文本块 | 同时调整字号、行高、容器宽度和换行；必要时按词组拆分，不只匹配单行高度 |
+| 细字与颜色 | 对照字距、文字灰度、按钮居中；不以模糊阴影模拟生成字形噪声 |
+| 图片与装饰 | 明确容器比例、主体位置与窄屏裁切；斜边等装饰不改变正文的布局基准 |
+
+校准次序、采集命令与验收项目以校准文档为准。实现文件只记录本项目取舍，不另建同义检查表。

draw-ui/references/reference-assets.md

@@ -0,0 +1,70 @@
+# 参考素材与透明度验收
+
+## 确定素材是否可用
+
+先检查原始文件、项目资源和局部裁图的清晰度、背景与边缘；合格就复用。素材有效像素应覆盖最终显示需求，例如 150 CSS px 宽、DPR 2 的标识至少需要 300 有效像素宽，大面积留白不算图形分辨率。插值放大不会恢复细节。
+
+品牌标识优先原始 SVG 或高清文件；缺少原稿且任务已授权重建时才使用实际 Logo 参考，锁定轮廓、字样与图文比例，不重新设计品牌。生成 PNG 和 SVG 包裹位图都不能冒称原始矢量文件。
+
+## 确需生成时
+
+1. 明确输入用途：整页提供布局上下文，局部图提供主体参考，需要保留内容的原图是编辑目标。实际图片输入的核验按 [生成工具](generation.md) 处理。
+2. 按容器确定宽高比、主体位置、裁切余量和像素需求；写清保留与变化范围。被遮挡内容的补全属于推断，不承诺恢复原图。
+3. 沿用主流程选定的工具生成。大插画、Logo 与小图标分开；只有确需统一风格且能规则切割的小图标才合成素材板，明确行列数、留白和不重叠。
+4. 保留原始输出与提示词，再将可用版本放回页面，检查实际尺度、裁切和遮挡。只完成素材检查时不声称页面还原通过。
+
+提示词按需填写，不固定品牌、风格或背景色：
+
+```text
+任务：从参考图重建独立的[素材对象]，用于[页面容器]。
+保留：[轮廓、姿态、视角、颜色、字样或构图关系]。
+改变或移除：[页面正文、控件、外框、指定背景]；保留[素材内部需要的环境]。
+规格：[宽高比、主体位置、必须完整的部分、裁切余量、目标像素]。
+背景：[真实透明／指定纯色／保留环境]，根据用途和当前工具能力选择。
+输出：只包含该素材，不添加无关文字或页面 UI。
+```
+
+## 透明度检查
+
+需要透明时，仅使用实际接口支持的参数请求真实 alpha。当前调用链没有结论可先尝试；同一任务已验证失败且调用方式未变时，不逐素材重复试。保留失败原图与检测结果；只有明确可修正的问题才至多重试一次，之后使用已授权后处理或报告限制。
+
+对原始输出及后处理结果分别运行（依赖 Pillow）：
+
+```bash
+python3 scripts/check_asset_alpha.py /path/to/asset.png --require-transparency
+```
+
+- 返回码 2：没有有效透明像素或整图不可见，不作为透明素材交付。
+- 返回码 0：同时存在透明像素和可见内容，只通过结构检查；仍需检查背景是否完整移除、主体有无误删、细线和毛发是否残留色边。
+
+PNG 扩展名、RGBA 模式、画入的棋盘格都不能证明透明；调色板透明元数据也应由程序识别。透明度少量通过不等于边缘质量通过，直接透明与后处理透明分别记录。
+
+## 条件性后处理
+
+仅在需要且当前任务及生成 Skill 允许时使用。背景色应避开主体颜色，也可采用可靠分割方案；照片内部环境需要保留时不要一并删除。以下参数是起点，先检查样本，不作为全部素材的默认值：
+
+| 素材条件 | 可选处理 | 重点检查 |
+| --- | --- | --- |
+| 白底上的深色标识或细线 | 白底转 alpha | 主体浅色部分与抗锯齿白边；细线避免收缩边缘 |
+| 主体与单色背景可明确分离 | 按背景色抠图 | 同色主体、半透明区域与残留色边；主体含绿时不用绿幕 |
+| 毛发、柔光或背景与主体混色严重 | 可靠分割、重新准备素材或拆层 | 是否损失细节，简单阈值是否足够 |
+
+白底示例：
+
+```bash
+python3 scripts/prepare_image_asset.py input-white.png output-alpha.png --alpha --threshold 248 --feather 10 --padding 16
+```
+
+主体不含绿色时的绿幕示例：
+
+```bash
+python3 scripts/prepare_image_asset.py input-green.png output-alpha.png --key-color '#00ff00' --key-threshold 28 --feather 12 --despill --padding 10
+```
+
+输出使用新路径，保留输入。`--no-trim` 保留画布，`--edge-contract` 会收缩边缘，仅在样本确认需要时使用；`--despill` 针对绿色污染。后处理完成后重新检查 alpha，并在目标深浅底、实际显示尺寸下查看边缘。
+
+## 放回页面与交付
+
+文件属性由程序检查，主体、品牌拼写、构图和裁切由实际画面判断。尺寸或构图不适合容器时回到规格，不靠反复移动图片修补互相冲突的裁切。混合模式不会改变源文件透明度，使用时还须检查堆叠上下文与矩形底色。
+
+独立保存资产并注明来源、尺寸、背景、适用底色与重建差异；细字和边缘的页面验收按 [测量与校准](calibration.md) 执行。

draw-ui/references/reference-measurement.md

@@ -0,0 +1,109 @@
+# 测量与采集接口
+
+依赖 Python 3.10+ 与 Pillow。执行顺序以 [测量与校准](calibration.md) 为准；本文件只定义输入、命令和输出。文件路径相对各自清单目录解析，测量、轮次和验收报告均使用新的输出目录。
+
+## 区域清单
+
+在任务目录保存 `regions.json`。使用原图像素；看到的是缩略图时，先按原图实际宽高分别换算坐标。
+
+```json
+{
+  "reference": "reference.png",
+  "css_viewport_width": 1024,
+  "expected": {
+    "url": "http://127.0.0.1:4187/",
+    "title": "示例页面",
+    "viewport": {"width": 1024, "height": 900},
+    "dpr": 1,
+    "full_page": true,
+    "screenshot_scale": "css"
+  },
+  "regions": [
+    {"name": "background", "kind": "color", "box": [20, 20, 100, 40], "inset": 2},
+    {"name": "card-a", "box": [40, 200, 280, 320], "group": "cards", "selector": ".card:nth-child(1)"},
+    {"name": "card-b", "box": [344, 200, 280, 320], "group": "cards", "selector": ".card:nth-child(2)"},
+    {"name": "title-ink", "box": [40, 90, 420, 70], "box_type": "ink", "selector": "h1"}
+  ]
+}
+```
+
+| 字段 | 含义 |
+| --- | --- |
+| `name` | 区域唯一名称 |
+| `box` | 原图像素的 `[x, y, width, height]`，整数且不得越界，不是右下角坐标 |
+| `kind` | `box`（默认）记录几何；`color` 统计框内颜色 |
+| `box_type` | `element` 为元素外框，`ink` 为可见字形，`sample` 为采样区；默认随 kind 选择 element 或 sample |
+| `inset` | 颜色采样向内避开的像素数，不得使区域变空 |
+| `group` | 同一横向重复结构，至少两个元素框，不混入字形或采样框 |
+| `selector` | 实现后定位主文档元素的 CSS 选择器；测量可省略，准备 DOM 采集至少需要一个 |
+| `css_viewport_width` | 实现视口约定，用于建立比例；不证明原页面的视口或 DPR。仅测图且未知时可省略 |
+| `expected` | 浏览器采集条件；仅测图可省略。视口宽度必须与 CSS 映射一致 |
+
+`expected.screenshot_scale` 为 `css` 或 `device`，后者按 DPR 输出像素。截图宽度必须等于原图宽度；例如原图宽 2048、CSS 视口宽 1024 时可用 DPR 2 与 device。视口截图还须与原图等高；完整长页由 `full_page: true` 明确。
+
+颜色只统计完全不透明的像素，并报告排除数量；半透明素材需另行确定合成背景。
+
+## 命令与产物
+
+以下路径为示例，占位目录需替换为本次任务路径。脚本不启动浏览器；`--preflight` 是会访问本地 HTTP 页面身份的可选检查。
+
+| 阶段 | 命令 | 主要输出 |
+| --- | --- | --- |
+| 测量 | `python3 scripts/measure_reference.py --manifest /task/regions.json --out-dir /task/measurement-01` | `measurements.json` 与自包含标注图 `annotations.svg` |
+| 准备采集 | `python3 scripts/prepare_capture.py --measurements /task/measurement-01/measurements.json --out-dir /task/round-01` | `run.json`、`collect.js`、`capture-plan.json`、`round-notes.md` |
+| 本地静态页预检 | `python3 scripts/verify_capture.py --manifest /task/round-01/run.json --preflight` | 服务地址、重定向与 HTML 标题检查 |
+| 验收 | `python3 scripts/verify_capture.py --manifest /task/round-01/run.json --out-dir /task/round-01/report` | `verification.json`、`geometry.md`、分区图片差异 |
+
+后续轮次用同一 `measurements.json` 准备新目录；验收命令增加 `--previous /task/round-01/report/verification.json` 可比较前轮。`verify_html_mockup.sh` 是 verify_capture 的薄封装，参数相同，不负责打开浏览器。
+
+`measurements.json` 保存原图尺寸与摘要、原始坐标、归一化比例、可选 CSS 映射、RGB 中位数与 10%／90% 分位数、网格尺寸和间距分布。`annotations.svg` 用于核对人工选区，不代表自动识别边界。
+
+`run.json` 绑定同一参考图、测量摘要、预期条件和待采集文件；`capture-plan.json` 供核对目标。记录实现取舍用 `round-notes.md`，不另抄坐标表。
+
+## 浏览器采集数据
+
+读取生成的 `collect.js`，在浏览器主文档上下文求值，不能在 Node.js 全局执行。表达式只读页面，不访问网络或读取表单值；返回以下数据：
+
+- `url`、`title`、`viewport`、`dpr`、`document_height`、`fonts_ready`、`images_ready`。
+- 绑定的 `measurement_sha256`、各区域的 `elements`（选择器、状态、文档 CSS 坐标外框与计算样式），以及图片 `assets`。
+- 宿主另从真实截图选项补充 `full_page`、`screenshot_scale`，将完整对象保存为 `capture.json`；同次截图保存为 `candidate.png`。
+
+采集状态为 `measured`、`missing`、`ambiguous`、`hidden`、`unmeasurable` 或 `invalid_selector`。选择器必须唯一；离开视口但仍在文档流中的元素可测量。iframe、Shadow DOM、canvas 和小程序不在此采集器范围内。
+
+关键图片可在区域清单中增加 `expected_assets`，以同名区域关联，selector 必须指向 img：
+
+```json
+{"expected_assets": {"logo": {"src": "http://127.0.0.1:4187/assets/logo-v2.png", "natural_width": 2048}}}
+```
+
+采集的 `src` 来自 currentSrc，另有 `natural_width`、`natural_height`、`version`（来自 data-version）。验收逐字段匹配；复用相同路径与尺寸时需增加可靠的版本标记或另验内容哈希，路径相同不能证明图片更新。背景图等非 img 资源由宿主额外检查。
+
+## 报告与失败语义
+
+- 标注越界、区域无效、颜色没有不透明样本、输出目录已存在：退出码 2，不自动裁短错误框或覆盖旧轮次。
+- 准备时缺少条件、没有选择器、映射不符或参考图已变：退出码 2，修正源清单后重新测量。
+- 页面身份、渲染条件、截图尺寸或基线不一致：验收拒绝；保留原始采集与错误，不能当成通过。
+- 元素采集不完整：保存诊断报告并以退出码 2 结束。`visual_only`（字形或采样区）和 `reference_only`（无选择器）不计算 DOM 外框误差。
+- 相同基线与采集条件下，前后报告用 `reduced`、`increased`、`unchanged`、`unavailable` 表示最大绝对 CSS 偏差的变化，不设通用审美通过阈值。
+
+## 只有截图或非 DOM 渲染
+
+只有两张图片时使用文件比较，不伪造采集数据：
+
+```bash
+python3 scripts/compare_mockup.py --reference /task/reference.png --candidate /task/candidate.png --out-dir /task/image-report --prefix screen
+```
+
+可增加 `--clip header:0,0,1024,80`，坐标为图片像素。默认拒绝宽高不一致；长页显式增加 `--allow-height-difference` 后仅比较共同坐标，保留高度差与未匹配尾部，缺失完整分区不计分。宽度不一致始终停止，不自动拉伸。该分支不提供浏览器身份或交互验证。
+
+已有真实浏览器截图及元数据、但没有区域测量时，可手写 `run.json`：填写 `reference`、`candidate`、`capture_metadata` 与上方同结构的 `expected`。可选 `allow_height_difference`、`clips` 和 `section_positions`；后者为区域名到 CSS y 坐标的映射，与元数据 `sections: [{"name":"hero","y":80}]` 对照。该分支使用 verify_capture，但不支持 `--previous` 的自动元素比较。
+
+## 可选的竖向色带扫描
+
+适合阈值判断的平坦色带可在区域清单中增加：
+
+```json
+{"vertical_scans": [{"name": "light-band-left", "x": 10, "y": 300, "height": 500, "min_channel": 175, "max_channel_spread": 45, "min_run": 20}]}
+```
+
+脚本寻找各通道不低于 `min_channel`、通道最大差不超过 `max_channel_spread`、长度至少为 `min_run` 的不透明连续区间，结束坐标不包含尾像素。多个横坐标可帮助定位斜边；命中也可能是文字或插画高光，不能自动认定为区块边界。

draw-ui/references/software-reconstruction.md

@@ -0,0 +1,31 @@
+# 现有软件实现
+
+## 接入项目
+
+沿用已有设计说明，先按 [测量与校准](calibration.md) 确定参考基线，再检查目标路由、组件树、技术栈、样式系统与项目规范。默认在现有架构内实现；用户明确要求独立原型或没有可用项目时，使用 [HTML 实现](html-reconstruction.md)。
+
+按实际差异选择最小改动：现有组件能够表达时调整布局和设计变量；重复结构或状态需要变化时修改组件；图片缺失时进入 [素材流程](reference-assets.md)。不因截图复杂就重建整套组件库。
+
+## 实现约束
+
+- 沿用项目的数据加载、路由、状态管理、样式和测试方式；TypeScript 项目保持类型完整。
+- 用业务含义命名组件，区分可复用展示内容与交互状态；普通图标使用项目已有图标库。
+- 保留语义按钮与链接、输入标签、键盘焦点、对比度和必要的减少动态效果支持。
+- 覆盖真实内容、加载、空结果、错误及关键操作；长文本、列表增长与窄屏不能破坏布局。
+- 素材按项目已有资源方式导入，容器明确尺寸、宽高比、裁切与响应式行为。装饰图使用空 alt；承载独立信息的图片提供准确替代文本。
+
+例如，项目支持静态资源导入时：
+
+```tsx
+import heroUrl from "@/assets/hero.png";
+
+export function HeroIllustration() {
+  return <img className="heroIllustration" src={heroUrl} alt="" />;
+}
+```
+
+## 验证与交付
+
+截图采集、偏差比较和跨轮修正统一使用校准流程，不另建截图循环。运行项目已有且与改动相关的类型检查、lint、测试和构建；静态检查不能代替实际操作。
+
+交付目标路由与修改文件、已验证的操作及视口、剩余视觉差异和检查失败原因。页面应属于项目正常组件树，不能依靠整张截图背景或仅有默认状态的控件通过验收。

draw-ui/references/ui-design.md

@@ -0,0 +1,86 @@
+# UI 设计与验收
+
+## 先确定视觉构思
+
+先理解用户的浏览与操作顺序，选择一个主要视觉手法，再组织内容。需要品牌表达而方向未定时，可在文字或草图中比较两个有实质差异的方向，选定后生成；不强制多轮提问或额外候选图。已有明确方向就沿用。
+
+构思应回答：第一眼注意什么，为什么适合该产品，以及如何贯穿页面。用具体构图、文字形态、照片视角、比例或色彩关系表达，不能只有“高级、温暖、专业”。业务清单决定内容是否完整，不能直接决定页面长什么样。
+
+| 界面 | 设计重点 |
+| --- | --- |
+| 品牌官网 | 主视觉与文字的关系，跨区块节奏和一致的品牌表达 |
+| 后台／工作台 | 核心判断与操作突出，主分析、辅助指标、待办和记录有不同分量；特色来自信息组织与组件细节 |
+| 移动产品 | 内容、导航与主操作比例适当，小空间中仍保留清楚的字体和状态层级 |
+| 游戏界面 | 世界观通过插画、配色和图标进入界面，任务、数值与控件保持可读可操作 |
+
+展示数据可用表格或图表，反复浏览同类对象用稳定列表，需要比较时才并列。不要把“侧栏＋指标卡＋折线＋表格”当成默认答案，也不为避开模板禁用合理组件。
+
+允许有目的的大小对比、非对称、错位、重叠与特殊裁切，说明它们如何通过布局、遮罩、字体或独立素材实现，以及窄屏如何处理。效率不等于省略视觉设计，容易实现也不等于删除特色。
+
+## 保存简短设计说明
+
+说明保存实现决定，提示词只传影响当前图像的重点。小任务可写在回复中，不强制多份配置；已有说明直接补充。
+
+| 内容 | 必要决定 |
+| --- | --- |
+| 目标与范围 | 用户任务、主操作、单屏或完整长页、必须出现的区块 |
+| 视觉构思 | 主要手法、第一眼焦点、与内容的关系和跨区块延续方式 |
+| 视口与画布 | CSS 逻辑宽高、滚动方向、输出像素或比例、安全区域 |
+| 结构与规则 | 内容顺序、对齐基准、重复组件、可用字体、字号、间距、HEX 颜色与阴影 |
+| 素材 | 用途、容器比例、裁切方式及与正文的边界；分类按主流程 |
+| 内容变化 | 长标题、更多列表项、窄屏、固定区域与关键操作状态 |
+
+没有既有规范时选择少量自洽规则，例如可调整的 4／8 间距基准、正文与可选标题字体、少量字号和圆角；不把它们固定为所有产品的套餐。字体需有现实可用来源，不能依赖模型生成的特殊字形。
+
+逻辑视口、文档高度和生成像素分别记录。移动端 390×844 的逻辑视口可以生成更大图片，但不能把生成图的 1024 像素宽当作手机布局宽；桌面长页数千像素的高度也不是桌面视口高度。
+
+生成前核对示例数据与内容空间：数量和分母、金额、日期是否一致；指定内容能否以合理控件尺寸显示。放不下时区分首屏与滚动内容，不用极小文字塞满，也不虚构客户成绩或认证。
+
+## 组织提示词
+
+| 任务 | 主线 | 模型可以探索什么 |
+| --- | --- | --- |
+| 新品牌或视觉探索 | 一个与内容相关的类比／概念，加必要内容与少量视觉锚点 | 构图、比例、图像和区块节奏 |
+| 密集业务界面 | 核心任务、内容关系、准确示例数据和组件约束 | 信息编排及视觉细节 |
+| 延展或还原 | 实际参考图、保留范围与允许变化的区域 | 仅在约定范围内变化 |
+
+类比应描述体验或组织方式，而非堆叠风格名；例如音乐工作台可以启发复杂信息的编排。若“杂志”“生活方式”带入无关静物、纸纹或口号，移除歧义，不继续堆修饰词。参考字体拆成字形、字重、比例与间距，不把英文字体类别直接翻译为中文宋体或手写字。
+
+以正面效果为主，只加入当前任务必要的限制。构思未成立时不锁死每个区块的列数与坐标；明确尺寸只用于可用性和一致性。提示词保持聚焦，不设没有接口证据的固定字数上限。默认生成正视页面；用户没有要求展示图时，不添加设备外壳、透视或页面外装饰。
+
+可选骨架，不要求逐项填写：
+
+```text
+对象与任务：[谁在什么设备上完成什么操作]。
+范围与画布：[单屏／滚动／完整长页、逻辑视口、输出像素或比例]。
+视觉构思：[主要手法、焦点及与业务的关系]。
+内容：[区域顺序、必要文案与准确示例数据]。
+规则与边界：[可用字体、HEX 配色、关键尺寸、素材范围、保留与变化]。
+适配：[影响当前画面的长文本、窄屏和固定区域处理]。
+```
+
+隐藏交互与其他状态保留在设计说明中，不要求全部画进一张图。栅格设计稿的文字仍是像素，“可编辑组件”只表示后续实现分工。完整长页按 [长页生成](full-page.md) 组织，避免无限增长的提示词。
+
+## 多状态与模型对比
+
+先记录相邻状态之间的动作、数据变化与控件状态，重复组件和导航沿用同一规则。奖励、数量与进度从同一记录推导，取消或错误不得提前更新结果。
+
+- 多屏总览用于看流程，先确认每格文字可读，再逐格核对状态与下一步操作；不能代替可运行原型。
+- 单张延展从已检查的同一基础图生成；只有测试连续编辑时才串联上一张，并记录累积变化。
+- 模型对比冻结提示词、参数与参考图片字节及顺序；有图与纯文字分组。共享生成的基础图需标明来源，双方获得相同输入；不能单独重画失败方挑样本，也不把一次质量或速度结果推广成永久结论。
+
+## 检查与迭代
+
+实际打开生成结果，在对应逻辑视口尺度检查：
+
+| 检查 | 判断依据 |
+| --- | --- |
+| 范围与内容 | 区块和页脚完整；文案、数值、日期及状态正确，无擅自承诺的业务能力 |
+| 视觉构思 | 焦点与表达可辨认，特色来自具体设计关系；内容齐全不抵消构图平庸 |
+| 层级与可读性 | 核心信息及主操作明显，字号、对比度与触控区域合理，颜色不独自承担状态含义 |
+| 一致性 | 字体、按钮、行高、图标线宽与对齐形成统一规则，各区块仍可有不同构图 |
+| 实现边界 | 图片不吞掉正文与操作，能说明长文本、更多数据及窄屏的处理方式 |
+
+每轮指出一个主要问题、应保留的特色与要改变的变量，再比较解决了什么、损失了什么。明确区分可验证缺陷与审美偏好；更整齐不一定更好，斜切或夸张比例本身也不是缺陷。纹理、颗粒和光晕只在明确风格需要时使用，不作为提升设计感的通用补丁。
+
+连续出现模板布局时先检查参考是否真正传入、类比是否误导、内容清单是否提前锁死结构。探索阶段可暂减非关键样本并标明省略项，最终恢复完整需求并复查。迭代遵循任务的数量与成本授权，保留版本；视觉质量由实际对照和用户反馈判断，图片审阅不证明交互与响应式已经实现。