菜单
ZeroWeb 专属工程方法论。在本仓编写、审查或重构涉及样式/布局/字体/渲染/IPC/存储/测试的 Rust 代码，或排查性能问题、做兼容性修复时使用——内容是从 docs/learnings/ 157 篇踩坑记录中提炼的跨条目不变式。
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/leizongmin/ZeroWeb --skill zeroweb-guidelines命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| name | zeroweb-guidelines |
| description | ZeroWeb 专属工程方法论。在本仓编写、审查或重构涉及样式/布局/字体/渲染/IPC/存储/测试的 Rust 代码，或排查性能问题、做兼容性修复时使用——内容是从 docs/learnings/ 158 篇踩坑记录中提炼的跨条目不变式。 |
本 skill 是 docs/learnings/ 踩坑记录的方法论蒸馏层：只收录被多篇独立记录印证的跨条目不变式，不重复单条记录的细节。需要某条规则的原始证据/细节时，按子系统到 INDEX.md（脚本生成，勿手改）检索原文。
lei-code-guidelines（行为层）之上，不复述其行为规则。ZeroWeb 中一切来自网页的输入（HTML/CSS/JS 传值）都是不可信输入。#1/#2（解析拒绝）、#21（外部尺寸封顶）属于 AGENTS.md「不可简化」清单中的信任边界校验，#16 属于防数据丢失——不得以「简单至上」「不为不可能场景写错误处理」为由放宽这三类。
以下场景可临时放宽（合入 main 前必须恢复，放宽结束自动恢复全部）：
任何场景下不可放宽：#1、#2、#16、#21（信任边界与数据丢失）。
每日 rally cronjob 按 docs/rally/learning-maintenance.md 自动维护。
解析 CSS 值时，通用 parser（长度、颜色）接受的范围总是比具体属性的 grammar 宽。跨属性/shorthand 边界后，必须按消费方 grammar 再收紧：未知 token 必须整体拒绝而非静默忽略，重复组件按 grammar 判定（text-decoration-line 允许重复、颜色不允许），delimiter 数量与空段必须校验，跨 longhand 的 shorthand（place-*）要逐侧验证。
裸 starts_with(keyword) 会把更长的 ident 拆成「关键字 + 剩余」，非法语法因此被接受。匹配 keyword 后必须确认后续是 token 边界；分段语法局部成功后不得忽略尾部输入。
layout、paint、raster 各自维护同一度量的副本必然分叉。任何改变 used font size/度量的功能，必须同时核对 shaping size、layout fragment width、paint consumed advance、raster size 四处；度量路径与 shaping 路径必须同源（以 hmtx 精确值为准，hinting 取整会在逐字符累计后变成可见误差）。
FontLoader 只解析 primary face 的 feature descriptor 会让 secondary face 用错 descriptor；不同 face 的 descriptor/size-adjust/unicode-range 会产生不同 glyph 序列，必须进入对应 face 的决策与 cache key。
键过宽 → 缓存不生效；键缺输入 → 静默错误结果。缓存键必须覆盖全部影响输出的元数据（face descriptor、fallback chain、axes），并按真实消费层次分组（如「字体链+字号 → 字符」两级结构）。
CPU/GPU、headless/native、JS-shim/native-DOM 每多一对双路径，就多一个静默分叉面。测试若只验证两条线的交集（CPU 软件渲染正确 + GPU 无头单图元正确），用户实际走的路径（GPU 窗口 + 合成器多进程）仍可能是错的。必须建立跨路径等价断言，像素级对比是唯一可靠锚点。
blit、脏矩形、缓存帧优化会改变混合操作序列；半透明混合不满足结合律，「看起来一样」不算数。必须与全量渲染做逐像素等价对比再合入。
新增字段不会自动穿过显式转换边界（TextFragment → InlineLayoutFragment → PaintFragment → stored path）。加字段时必须审计所有转换路径，只测单一入口会让其他路径静默丢字段。
进程/pass 内稳定的开关（环境变量、配置）不允许出现在逐节点、逐 run、逐 glyph 循环里。在公开入口读一次，把值传进递归 helper；或用进程级快照机制。本项目已因此消掉多个 >3% 的 getenv 热点。
循环内任何 char_indices().nth(pos)、全树 collect、每 IFC 全文档扫描都会把 O(n) 放大成 O(n²)；昂贵子树扫描应先判断有无消费方，无消费方直接跳过；大对象穿越递归优先借用（Box/Cow）或 Arc 共享，不做深拷贝。
共享主机有频率漂移，整页时间证明不了收益。性能改动必须用固定 CPU 微基准对照、A/B 正反序双跑排除漂移、PNG SHA-256（或逐像素）验证渲染零变化。三者缺一就容易把噪声当收益。
独立 bin（zero-renderer、zero-compositor）不在测试包依赖树里，cargo test -p X 不会重编它们。spawn 陈旧二进制会产出稳定的假绿/假红，症状伪装成代码回归。测试前显式 cargo build peer 或用 CARGO_BIN_EXE 注入；spawn 查找链要完整（env → CARGO_BIN_EXE → exe 上溯 → PATH）且找不到时显式报错，不静默回退。
生产者高频发完整快照（ViewPainted、输入帧）而消费者只能处理有限帧时，逐帧处理会堆积过期工作。单槽 latest-wins 邮箱保持最终语义不变并消除 N-1 次重复转换。
只更新状态、不终止卡死进程、不切换帧来源，会把一次慢帧放大为永久空白。跨进程链路的超时机制必须同时提供「杀掉无响应进程」和「回退 legacy/可用路径」两个出口；空闲后再产帧的合法场景不能误判超时。
等待特定响应时把无关消息塞回同一队列，会让循环不再阻塞、单核自旋，目标响应即使到达也读不到。无关消息应进独立局部队列，退出等待后再恢复。
原子 rename 只保证单次替换无半文件，不解决多进程内存副本的 lost update——共享目录 ≠ 共享所有权。跨进程持久化必须确立单一 writer，其他方走 IPC。事务系统内 get/add/put/delete/cursor 必须共享同一套 mutation 可见性判断（latest view），各操作重复实现不完整检查必然分叉。
断言「快照序号变化」会被空白首帧满足；断言图元非空会放过格式错误；读对比文件前必须确认它是新鲜产物（orphan stale PNG / 缺资源的 webfont 都会造成假绿或假红）。断言要落在真实 DOM 状态、消费方可解析的内容上。
code-trace 只是假设，A/B 零效果时继续猜「大概是字体墙」会指向完全错误的函数。reftest 修复前先 REFTEST_DEBUG=1 make reftest-oracle 读 ZW 实际输出的 origin/size/color，再用 probe 确认执行路径。
Rust test harness 在同进程并行跑用例。持有进程级全局资源（FD 计数、全局单例、持久化设置文件、空闲端口）的测试，必须复用同一把跨模块锁或显式串行；多进程 fixture 动态资源要验证完整闭包再导入。
字体路径、路径分隔符、端口机制因平台而异，只适配单平台 = 其他平台假失败；跑 GPU/性能基准前先探测能力并与 baseline 的 platform_class/cpu_model 匹配，不匹配标 INCONCLUSIVE，不更新共享 baseline。fixture 路径用 concat!(env!("CARGO_MANIFEST_DIR"), ...) 编译期拼接，不依赖进程 cwd。
JS 传入的 f32/u32 推导出的尺寸/偏移/半径，使用前必须有界；f32→i32 是饱和而非回绕，饱和到 i32::MAX 后的加减必然 overflow panic。像素缓冲区大小恒用 usize 域 + saturating_mul/checked_mul。所有开 socket 的旁路复用统一资源预算，防止 FD 耗尽。
Send + Sync 回调想跨调用缓存状态，只能存纯值类型（String/数字/纯值 map）——Document、StyleSystem 等含 Cell/Rc/回调的复合类型天生不是 Send。向既有算法传入扩展数据结构时，必须保持原解析路径输出不变，新逻辑在「扩展未改变主结果」守卫下启用。
必要的 spec 合规/安全修复常在热路径上顺手引入 2–16x 回归，全量周期性门禁要一周后才暴露（canvas stroke mask 16.7x、worker terminate 轮询 8.8x、CSP 源列表 2.1x——三例同模式、不同根因）。触碰 parser/热路径的修复合入前跑定向测量（ZERO_WEB_BENCH_CRATES=<crate> make bench-gate）；预计算/缓存优化还要复核同对象其他基准（parse/check 互为约束），检查路径省的钱不能在解析路径输光。
renderer/worker 进程内任何「页面 JS 正在等结果」的新 IPC 消息类型（命令、求值、托管类），处理路径必须挂在 reader 线程路由或独立托管线程上，不得只挂主循环 dispatch_message——主循环会被同步 automation/脚本执行长期占住，挂在其上的消息永远轮不到，形成跨进程三方互等死锁（页面 JS 等响应 ↔ 主循环等 JS 执行 ↔ 命令排队），且死锁侧无任何日志，症状是端到端测试 20s 超时。SW 求值下放 renderer 即因此死锁；响应/命令同走 reader 线程旁路是不依赖主循环的正确基线。
WebView 等嵌入宿主暴露给 JS shim 的能力桥（__zw_* callback/hook、contentWindow API 暴露）缺失、上下文错位（client id/referrer/相对 URL 基准不按当前 global 解析）或未按每个脚本执行入口武装（独立 execute_script 不触发 begin-script hook）时，页面侧对象停在 stale 状态或 API 缺失——症状伪装成时序/超时问题，等待和加超时只会掩盖缺失的发现通道。新桥面必须对照页面 runtime 契约逐项核对存在性、client 上下文与武装时机（SW registration 发现桥、Cache API iframe 上下文、投影轮询重装三例同模式）；排查时断言要读底层 manager 状态而非页面侧缓存投影。
js_dom_shim 中凡对象可能是 _makeProxy/_wrapHandle 产物，「属性读」即 get trap + 可能的 host 回调往返（__zw_*，µs 级），不是纯内存访问——代码看起来是纯 JS，成本完全不可见，扫描循环随条目累积二次方放大成文件级 Timeout（R350：Range-mutations 五用例 90s 只跑 28%，单操作微基准却全部「便宜」）。写 shim 扫描循环前必须先问：每条目读什么、读几次、读的对象属于哪个域；恒定键（尤其另一对象的键）必须读一次提出循环外（trap 域这是 50x 级差异，非常规微优化）；前置守卫本身含昂贵读（如 parentNode 上行）时改为「便宜键比对命中后才做守卫验证」。
验证方法陷阱：单段微基准可能全部「不慢」（缓存/短路掩盖组合效应），需用等价轻量实现整体替换做 A/B 得到总量差（native 11.46ms vs stub 0.10ms），再逐段把原逻辑加回定位。