docs(env): .env 冻结最终口径 —— 基础键已定、以后不准改(不加/不改/不删)
主人 2026-10-06 二次收口:只求『统一不新增』且『基础键已定好、以后不准改』。 - AGENTS §10 与 design/13 §2.1 同步改写:新配置一律走 $DATA_DIR/config/** + 代码默认值; 既有基础键与 env: tag 保持现状(不迁移/不改默认值/不删键);E6 作废 - 新增一条判据:模板与代码若出现差异 ⇒ 那是**事故**(有人动了被冻结的东西),要回退而不是同步文档
This commit is contained in:
1 parent
ffe2518bf4
commit
9c9a6d26c9
1 file changed
+5
-1
@@ -68,7 +68,11 @@
|
||||
- 🔴 **日志必须标来源**:模块/子功能用 `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` 冻结为「只保证最小化功能可跑」的引导面(主人 2026-10-06 红线,**取代**原协同 `E6` 的「新键立即同步模板」)**:**新增/调整配置一律不再进 `.env` / `.env.example`**;调优、门槛、上限、开关类参数走 **`$DATA_DIR/config/**`(面板可改)+ 代码默认值**。① 新键**不得**新增到模板(确属最小化引导必需者,须主人明确批准);② 既有引导键在代码里的默认值变了,模板**仍须如实更新**(冻结不等于让文档说谎);③ **既有键与既有代码里的 `env:` tag 一律保持现状**(主人 2026-10-06 明确:只要求「**以后别再加新键**」,**不要求迁出**已有键 —— 迁移项已撤销);④ 自查命令(代码键 ↔ 模板键)从此改为「**报告差异**」而不是「必须无差异」:差异若属调优类,必须能在 `design/13 §2.1` 找到它的正当去处。历史事故留存:曾因「模板迟迟没进 HEAD」导致钉住模板同步的测试在 **HEAD 上**红(见 `开发习惯与约定 §7`),该教训在冻结后不再适用。
|
||||
- 🔴 **`.env` 冻结(主人 2026-10-06,二次收口后为最终口径)**:`.env` 只保证「**最小化功能可跑**」——**基础键已经定好了,以后不准改**(**不加、不改、不删**;模板 `.env.example` 与 `.env` 同进退)。
|
||||
① **新配置一律不进 `.env`**:调优/门槛/上限/开关类参数走 **`$DATA_DIR/config/**`(面板可改)+ 代码默认值**;
|
||||
② **既有基础键与既有 `env:` tag 保持现状**(不迁移、不改默认值、不删键);
|
||||
③ 原协同 `E6`「新 env 键必须同步 `.env.example`」**作废**;
|
||||
④ **凡文档里写「新增 env 键须同步 `.env.example`」的段落一律是过期文本**,按本条改正(口径全文见 `design/13 §2.1`)。
|
||||
- 🔴 **每次模块/功能改动「前」与「后」都推仓库**(用户红线,留恢复误操作余地):改动前若工作树有未推改动,先 `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)再出证据;③ 出现「整机变慢/命令不动」先查**是不是自己刚起的压测进程**,再怀疑工具链。
|
||||
- 🔴 **仓库根产物卫生(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`」,且必须在**整树验收通过之后**执行(对齐「后端常驻」红线:换产物不留空窗)。
|
||||
|
||||
Reference in new issue
Block a user