From dfac06bbeb3ad8049eb8157537ef1a31ab616d2a Mon Sep 17 00:00:00 2001
From: AskaEth <i@yeij.top>
Date: Sun, 25 Oct 2026 00:09:56 +0800
Subject: [PATCH] =?UTF-8?q?docs(agents):=20=E8=AE=B0=E4=B8=8B=20internal/w?=
 =?UTF-8?q?ebui/dist/.gitkeep=20=E5=8D=A0=E4=BD=8D=E4=B8=8D=E5=8F=AF?=
 =?UTF-8?q?=E5=88=A0=EF=BC=88=E5=B9=B2=E5=87=80=20checkout=20=E5=8F=AF?=
 =?UTF-8?q?=E6=9E=84=E5=BB=BA=E7=9A=84=E5=89=8D=E6=8F=90=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index d8d0678..a9dab26 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -81,6 +81,6 @@
 - 🔴 **等待子代理：不许用长 `WaitFor` 阻塞回合（主人 2026-10-04 反馈）**：主会话在 `WaitFor` 里等子代理时，**主人无法给任何补充输入** —— 等于把主人锁在门外。规矩：**派完就结束回合**（子代理的完成通知会自动唤醒主会话）；确需同回合内等，**单次 `WaitFor` ≤ 60s**，且只用于「马上就要用它的结果」；等待期间若有并行工作，**先做工作再结束回合**，不要空等。
 - 🔴 **遇到开发文档冲突 / 意义不明 / 规格矛盾时**：**阻塞会话**，用 `AskUserQuestion` 询问主人，**不得自行猜测**；文档清、不冲突则自主推进。
 - 🔴 阶段验证：后端 `go build ./...` + `go vet ./...` + `go test ./...` 全绿 + windows/darwin 交叉编译；前端（M9+）`tsc --noEmit` + `vite build` 通过。
-- 🔴 **换二进制前先确认前端是否变更（2026-10-05 登记）**：`scripts\ctrl.bat build` **只跑 `go build`，不含前端**。若本次改动触及 `frontend/web/**`，必须先在 `frontend/web` 跑 `npm run build`（会把 `dist` 拷到 `internal/webui/dist`），**再** `ctrl.bat build` + **一次** `restart`；否则后端产物里带的是旧前端。反过来：**纯前端改动不需要重启后端**（运行时优先读磁盘 `frontend/web/dist`），刷新浏览器即可。
+- 🔴 **换二进制前先确认前端是否变更（2026-10-05 登记）**：🔴 **`internal/webui/dist/.gitkeep` 是 `git add -f` 追踪的占位文件，不要删、不要 `git rm --cached`** —— 它让**干净 checkout / 新 worktree** 能直接 `go build ./...`（`//go:embed all:dist` 在空目录上会编译失败）；真实产物仍被 `.gitignore` 的 `dist/` 忽略，`frontend/web/copy-dist.mjs` 已在构建末尾保证把它写回来。删掉它会同时打坏编译与前端拷贝链。`scripts\ctrl.bat build` **只跑 `go build`，不含前端**。若本次改动触及 `frontend/web/**`，必须先在 `frontend/web` 跑 `npm run build`（会把 `dist` 拷到 `internal/webui/dist`），**再** `ctrl.bat build` + **一次** `restart`；否则后端产物里带的是旧前端。反过来：**纯前端改动不需要重启后端**（运行时优先读磁盘 `frontend/web/dist`），刷新浏览器即可。
 - 🔴 **裁定必须带完成状态（2026-10-05 登记）**：凡是给主人 / 给安卓端的裁定、承诺、回执，**每一条都必须标注「已完成 / 在办 / 未开始」**；标「已完成」须附 commit 号或验收证据，且**完成后回原条目处补记「已完成 + commit」**——不得只在别处口头称完成。**禁止把「未验证」表述成「已修好」**。
 - 🔴 **提交一律逐文件 `git add <显式路径>`（2026-10-05 实测事故）**：**禁止**在「同一目录下有多路在途切片」时用 `git add -A -- <目录>` —— 实测它会**把别的子代理的在途文件一起吞进提交**（本次误把 237 的 `sessionenv.go` 提交并推了）。修复套路：`git reset --soft HEAD~1` → `git restore --staged <误入文件>` → 重新 commit → `git push --force-with-lease origin dev`（工作树内容不丢）。