diff --git a/AGENTS.md b/AGENTS.md
index f39c440..0a69ace 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -173,6 +173,15 @@ Linux（`build-linux.js`）：
 - 仓库 `.npmrc` 指向 npmmirror，GitHub runner 在境外拉不动，工作流用 `npm_config_registry` 与 `ELECTRON_MIRROR` 覆盖回官方源。新增构建步骤时别把这两个环境变量漏掉。
 - 新增集成套件后要同步加进工作流的套件列表，单测里有断言按 `src/_test/electron/` 的实际文件逐个核对，漏加会直接失败。
 - 标签名必须等于 `v` + `package.json` 的 `version`，且标签要指向被构建的那个提交。
+- 下载完整日志要仓库管理员权限，所以失败详情都转成 `::error` 注解。改这几步时别把注解去掉，否则没有管理员权限的人只能看到「exit code 1」。
+- runner 上 `chrome-sandbox` 拿不到 root:root 4755，集成测试必须带 `--no-sandbox`。这个开关只属于 CI，不要带进构建产物。
+- runner 自带字体极少，工作流装了 Liberation 与 Noto CJK。界面文案是中文，缺 CJK 字体会渲染成豆腐块，版式测量也跟着偏。
+
+Linux 上首次跑测试暴露过三类只在该平台成立的问题，新写代码时留意：
+
+- `mtimeMs` 在 ext4/APFS 带亚毫秒小数，`Date.now()` 只到整毫秒。直接相减，刚落盘的文件年龄是负数，「超过宽限期就回收」的逻辑永远不触发。比较前先 `Math.floor`。
+- 集成夹具要走网络时，代理只能读 `HTTPS_PROXY`，不能写死本机端口，否则 CI 上直接 ECONNREFUSED。
+- 版式类断言的容差不要写死字符数，按实际渲染出的每行字数算。字体集不同，同一行的字数就不同，写死的数字换个平台就假失败。
 
 ## 仓库