UI 自动化的固定坐标，必须绑一条可机检的前提断言 · v1
一句话律：硬编码坐标都有隐含前提（面板是关的 / 窗口是最大化的 / 输入框是空的）。前提不成立时坐标不会报错，它会落在别的东西上并照常执行。 所以坐标不能单独存在，必须和一条能当场校验的断言绑在一起。
为什么它比”坐标写错”危险一个量级
坐标写错是响亮的失败——点了个空白处，什么都没发生，你立刻知道。
前提不成立是安静的成功——点击、输入、Ctrl+A+Delete 全都正常执行了，只是执行在别的控件上。脚本一路绿灯跑完，产物参数正常，你要么很久以后才发现，要么根本发现不了。
实测最贵的一次：右侧文档面板开着时，输入框坐标 (3670,990) 实际落在文档编辑器里，一次 Ctrl+A + Delete 把一份 18KB 的 PLAN.md 清成了 101 字节。脚本没有任何异常输出。
实证
Codex 教程录屏项目，两批素材各自独立复现：
| 事故 | 前提是什么 | 前提不成立时坐标落在哪 |
|---|---|---|
| PLAN.md 被清空 18KB→101B | 右侧文档面板已关闭 | 文档编辑器 |
| 同根因第二次：确认语被打进 PLAN.md | 同上 | 同上 |
| 整段一声不响退出，什么都没打印 | Codex 在录制屏上最大化 | 窗口外的桌面背景（读到深色 → 判成”AI 还在跑”） |
| 段 13 连着两次没跑起来 | 输入框是空的 | 输入框有内容时发送键从浅灰变深，和”停止方块”一样暗 |
| ”找不到窗口” | 窗口没被最小化过 | 最小化窗口 GetWindowRect 只有 160×28，被按最小尺寸过滤的枚举漏掉 |
| 侧栏项目条目点错行 | 侧栏滚动在顶部 | 别的项目 |
共同点：没有一条是坐标本身算错了。
操作规则
-
每个坐标常量旁边写死它的前提，并把前提做成可机检的断言，不是注释里的一句提醒。注释拦不住三周后的自己。
-
断言写在动作之前。
ensure_layout()必须先于clear_box()，顺序反了就是清空文档——这条是用一份被删的文件换来的。 -
断言优先选位置无关的像素特征。本项目用”按钮区域最暗像素”一个量同时判三件事：
< 250：按钮确实在这个坐标上（面板开着的话这里是纯白）< 100：按钮是停止方块（AI 在跑）≈ 140：按钮是箭头（空闲）
好判据的标准是跟视图无关。试过”和参考图比对”，会因为视图切换（新建任务页 ↔ 对话页）产生难以解释的误判。
-
破坏性操作前必须过断言——Ctrl+A + Delete、拖放、点”确认”/“删除”/“提交”。非破坏性动作可以只在开头过一次。
-
窗口类前提要校验矩形，不能只发一条消息就当成功。
ShowWindow(SW_RESTORE)不保证回到最大化：窗口如果中途被人手动动过，restore 出来的是普通尺寸，所有基于”最大化”的坐标同时失效。发完SW_MAXIMIZE再读回 rect 比一遍。 -
应用状态机不要靠单次点击推断。本例要开一个挂在指定项目上的空白任务：只点侧栏项目条目 → 进它已有的对话；只点”新建任务” → 项目是空的。正解是三步组合（新建任务 → 选项目 → 搜索过滤到一条 → 点它），并用像素校验结果。
边界
- 坐标由程序当场探测时不适用（读控件 rect、找蓝色链接块、按标题找窗口）。那类失败会返回
None，是响亮的失败，不需要额外断言。这条只针对硬编码常量。 - 断言本身也可能有隐含前提（“按钮亮度”这条的前提就是”输入框是空的”）。断言要写清自己的适用条件，否则只是把问题推后一层。
- 这条不反对硬编码坐标。UI 自动化里硬编码往往是最稳的做法，代价就是这一条断言。
同族
- 自动化产出双重验收_机器验参数人眼验内容_v1 —— 一体两面：那条管”结果对不对”（事后抽帧），本条管”动作发生在对的上下文里”（事前断言）。能写成断言的就别只靠事后抽帧，人眼关是兜底不是第一道防线。
- Windows下编码与DPI的所见非真相 —— 同源的”环境隐式转换”：DPI 缩放悄悄改比例，面板开合悄悄改布局，都是”看起来对，实际不对”。
验证状态
⭐⭐ 二次验证
- 首验：Codex 教程实战六 19 段录制（
ensure_layout()面板前提、按钮亮度的”输入框须为空”前提） - 二验：Codex 教程清单 2/3/4 三项目 19 段录制（清空 PLAN.md ×2、窗口未最大化整段静默退出、最小化窗口枚举不到、侧栏行错位）
两次跨不同项目、不同界面版面独立复现。尚未在录屏以外的域验证，第三次验证应当来自别的 UI 自动化场景。
关联文档
- 2026-08-01_Codex教程清单2-4_三项目19段录屏复盘（本律来源案例，含完整事故清单）
- 2026-07-31_Codex教程实战六_自动化录屏19段复盘（首验案例）
- 自动化产出双重验收_机器验参数人眼验内容_v1（一体两面）
- Windows下编码与DPI的所见非真相（同源：环境隐式转换）
- 代码资产索引（humancast 工具登记处）
- 04_方法论与洞察索引