diff --git a/AGENTS.md b/AGENTS.md index daf6513..57e3b60 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -70,6 +70,8 @@ - 🔴 **用户侧 API 文档随实现更新**:每实现/变更一个 REST 端点、WS 事件、admin API,**立即同步更新 `Docs/api-client.md`**(用户侧跨平台客户端 API 文档),供后期原生客户端开发;契约变更版本化。 - 🔴 **`.env.example` 与实现同步(同一类固定动作,2026-10-04 登记为协同 `E6`)**:每**新增 / 改名 / 删除**一个 env 键(`env:"…"`、`os.Getenv/LookupEnv("…")`、自定义 env helper、Go const 形式的 env 名),**立即同步 `.env.example`** —— 键名必须与代码**逐字一致**、值一律占位符、**绝不写真实凭据**;已废弃但未删除的键在模板里**显式标注「未接线,配了不生效」**。否则照模板部署的新实例会**漏配且静默失效**。自查命令(代码键 ↔ 模板键,`comm -23/‑13` 必须只剩已说明的噪声):见 `DevDocs/开发习惯与约定.md` 与协同清单 `E6` 条目。 - 🔴 **每次模块/功能改动「前」与「后」都推仓库**(用户红线,留恢复误操作余地):改动前若工作树有未推改动,先 `git push origin dev` 存一个干净基线;改动完成验收通过后,立即 `git commit` + `git push origin dev` 存档。**绝不攒一堆改动到阶段末一次性推**——坏操作可随时 `git reset`/`rebase` 到任一推过的 commit 回滚。每个模块/功能提交(或里程碑归档)后均 `git push origin dev` 同步远端。 -- 🔴 **压测纪律(2026-10-04 实测事故,必守)**:子代理做负载/竞态验证时**不许**用无界进程风暴占机(如 `yes` ×30、`sleep` 风暴)—— 实测一次「`yes` 没杀干净」把 12 核占满约 **15 分钟**,期间所有 `go build/test` 近乎停滞,并把工具链误判成死锁。规矩:① 负载**限核**(`GOMAXPROCS`/单包并行/`-p`)或**限时**(几分钟级),优先用「可控对抗条件 + 注入时钟 + 门控」而不是堆进程;② 压测结束**必须确认无残留进程**(`Get-Process yes` 之类计数为 0)再出证据;③ 出现「整机变慢/命令不动」先查**是不是自己刚起的压测进程**,再怀疑工具链。:`go build ./cmd/cyrene/...` 这类**单 main 包**命令会把可执行文件写到**当前工作目录** ⇒ 实测**静默覆盖**了正在用的发布产物 `cyrene.exe`(且不带 `-ldflags "-s -w"`,体积 39.3 MB → 49.1 MB)。规矩:**子代理一律不许跑会在仓库根产出可执行文件的构建** —— 只跑 `go build ./...`(多包 ⇒ 丢弃产物)、`go build ./<非 main 包>/...`、`go vet`、`go test`。**换二进制只允许**「`scripts\ctrl.bat build`(唯一权威构建,带 strip)+ **一次** `restart`」,且必须在**整树验收通过之后**执行(对齐「后端常驻」红线:换产物不留空窗)。 +- 🔴 **压测纪律(2026-10-04 实测事故,必守)**:子代理做负载/竞态验证时**不许**用无界进程风暴占机(如 `yes` ×30、`sleep` 风暴)—— 实测一次「`yes` 没杀干净」把 12 核占满约 **15 分钟**,期间所有 `go build/test` 近乎停滞,并把工具链误判成死锁。规矩:① 负载**限核**(`GOMAXPROCS`/单包并行/`-p`)或**限时**(几分钟级),优先用「可控对抗条件 + 注入时钟 + 门控」而不是堆进程;② 压测结束**必须确认无残留进程**(`Get-Process yes` 之类计数为 0)再出证据;③ 出现「整机变慢/命令不动」先查**是不是自己刚起的压测进程**,再怀疑工具链。 +- 🔴 **仓库根产物卫生(2026-10-04 实测事故,必守)**:`go build ./cmd/cyrene/...` 这类**单 main 包**命令会把可执行文件写到**当前工作目录** ⇒ 实测**静默覆盖**了正在用的发布产物 `cyrene.exe`(且不带 `-ldflags "-s -w"`,体积 39.3 MB → 49.1 MB)。规矩:**子代理一律不许跑会在仓库根产出可执行文件的构建** —— 只跑 `go build ./...`(多包 ⇒ 丢弃产物)、`go build ./<非 main 包>/...`、`go vet`、`go test`。**换二进制只允许**「`scripts\ctrl.bat build`(唯一权威构建,带 strip)+ **一次** `restart`」,且必须在**整树验收通过之后**执行(对齐「后端常驻」红线:换产物不留空窗)。 +- 🔴 **等待子代理:不许用长 `WaitFor` 阻塞回合(主人 2026-10-04 反馈)**:主会话在 `WaitFor` 里等子代理时,**主人无法给任何补充输入** —— 等于把主人锁在门外。规矩:**派完就结束回合**(子代理的完成通知会自动唤醒主会话);确需同回合内等,**单次 `WaitFor` ≤ 60s**,且只用于「马上就要用它的结果」;等待期间若有并行工作,**先做工作再结束回合**,不要空等。 - 🔴 **遇到开发文档冲突 / 意义不明 / 规格矛盾时**:**阻塞会话**,用 `AskUserQuestion` 询问主人,**不得自行猜测**;文档清、不冲突则自主推进。 - 🔴 阶段验证:后端 `go build ./...` + `go vet ./...` + `go test ./...` 全绿 + windows/darwin 交叉编译;前端(M9+)`tsc --noEmit` + `vite build` 通过。