메뉴
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），再逐段把原逻辑加回定位。