From 834ef3683ec388aed45d5bd3f8925ab3587f83d7 Mon Sep 17 00:00:00 2001 From: AskaEth Date: Sun, 4 Oct 2026 17:14:56 +0800 Subject: [PATCH] =?UTF-8?q?docs(agents):=20=E9=93=81=E5=BE=8B=20=C2=A710?= =?UTF-8?q?=20=E5=A2=9E=E3=80=8C.env.example=20=E4=B8=8E=E5=AE=9E=E7=8E=B0?= =?UTF-8?q?=E5=90=8C=E6=AD=A5=E3=80=8D=E5=9B=BA=E5=AE=9A=E5=8A=A8=E4=BD=9C?= =?UTF-8?q?=EF=BC=88E6=20=E7=9A=84=E6=A0=B9=E6=B2=BB=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 与「改帧就同步 api-client.md」同一类：新增/改名/删除任何 env 键即同步模板；键名逐字一致、值一律占位符、废弃键显式标注。附自查口径（键集合 comm 差值只许剩已说明噪声）。 --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 0f84ae7..8fb07e4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -68,6 +68,7 @@ - 🔴 **日志必须标来源**：模块/子功能用 `internal/logger.WithSource`/`Scoped`（`source=module/subfeature`）标注，跨模块可追溯定位；**禁止无来源裸日志**。 - 🔴 **客户端 API 契约先行**：REST `/api/v1` + WS `/ws` + admin `/api/v1/admin/*` 统一**版本化契约**，供跨平台客户端（Web/移动/IM bridge）接入与治理；JSON 响应 `{data}` / `{error:{code,message}}`。 - 🔴 **用户侧 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 实测事故，必守）**：`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`」，且必须在**整树验收通过之后**执行（对齐「后端常驻」红线：换产物不留空窗）。 - 🔴 **遇到开发文档冲突 / 意义不明 / 规格矛盾时**：**阻塞会话**，用 `AskUserQuestion` 询问主人，**不得自行猜测**；文档清、不冲突则自主推进。