96ac67e744
新增陷阱(只追加、不复用旧号):
trap-8 gofmt -l 列出文件时退出码仍是 0(只看退出码=假绿);
trap-9 tar -C dir . 产生 . 根成员 ⇒ 预览 404 而流水线显示成功;
trap-10 依赖清单被静默改写(-mod=mod、缺锁回落 npm install);
trap-11 汇总把"未运行/被跳过"当"通过";
trap-12 事件 SHA 与检出 SHA 不一致;
trap-13 密钥扫描规则过宽 ⇒ 永远的假红,最后被人整条注释掉。
(trap-13 来自实做:第一版规则用很宽的字符类抓口令段,把 postgres://{u.quote(...)} 这类
模板表达式和 *** 脱敏也当成密钥,四条全是假阳性。收窄口径并把这些形状钉进良性对照防回归。)
AGENTS.md 的现状表需要同步(写着"main 已启用分支保护",实测 GET /branch_protections = [])——
该文件受写入保护,本次未改,修正稿另存待批准后应用。
验证:python3 scripts/check_changelog.py 结构自检通过;make verify 全绿。
208 lines
11 KiB
Markdown
208 lines
11 KiB
Markdown
# 已知陷阱(全文)
|
||
|
||
> 这份文件是 `AGENTS.md` 第 4 节那张索引的**全文**。拆成两份是有原因的:
|
||
> `AGENTS.md` 作为"工作区指令"会被自动加载,而**指令有字节预算** —— 超出的部分会被
|
||
> **静默截断**,没有任何报错。索引留在指令文件里(一行一条,一眼扫到),全文放这里。
|
||
>
|
||
> 纪律:**只追加、不重排、不复用旧号** —— 编号会被代码注释、测试、文档引用(形如"见 trap-3")。
|
||
> 新增一条要改两处:这里加全文 + `AGENTS.md` 的索引表加一行。
|
||
|
||
## trap-1:`.gitignore` 对**已入库**的文件无效
|
||
|
||
**症状**:规则明明写了 `__pycache__/`,`git ls-files` 里却仍有 8 个
|
||
`scripts/__pycache__/*.pyc`。
|
||
|
||
**根因**:`.gitignore` 只影响"未跟踪"的文件。文件一旦进了索引,规则对它就完全不起作用,
|
||
而且**不会有任何提示**。
|
||
|
||
**判据**:`git ls-files | grep -E '__pycache__/|\.pyc$'` 输出非空即是这条。
|
||
|
||
**修法**:规则 + `git rm -r --cached <path>`(保留磁盘文件)。
|
||
规则齐全不等于没被跟踪 —— 断言要查**两件事**:规则在、且 `git ls-files` 里没有。
|
||
|
||
**反例**:只加 `.gitignore` 规则就以为修好了。下次 `git add -A` 时它照样进来。
|
||
|
||
## trap-2:`git rm --cached` 之后跑 `git add -A`,文件会被搬回索引
|
||
|
||
**症状**:执行了 `git rm --cached node_modules`,`git status` 也显示删除了,
|
||
提交后 `git ls-files` 里那个文件**仍在**,净效果为零。
|
||
|
||
**根因**:`--cached` 只从索引移除、**磁盘文件留着**。如果此刻忽略规则**还没生效**
|
||
(本仓当时只写了 `/web/node_modules/`,管不到根级 `node_modules`),
|
||
紧接着的 `git add -A` 会把这个"存在且未被忽略"的文件重新加回索引。
|
||
|
||
**判据**:`git rm --cached X` 后、提交前,先跑 `git check-ignore -v X` ——
|
||
必须命中一条规则,否则 `add -A` 会把它捡回来。
|
||
|
||
**修法**:**先让忽略规则生效,再撤出索引**,并且此后只 `git add <具体文件>`,
|
||
不要用 `-A`。
|
||
|
||
**反例**:把两步写成一条 `git rm --cached X && git add -A && git commit`。
|
||
|
||
## trap-3:用子串判断代替整行判断
|
||
|
||
**症状**:脚本判断"规则已存在"时写 `if "/node_modules/" not in 全文`,
|
||
而文件里已有 `/web/node_modules/` —— **它包含这个子串**,于是误判为"已存在",
|
||
跳过了追加。结果规则根本没加上,而脚本打印"规则已存在"。
|
||
|
||
**根因**:`.gitignore` 的 `/web/node_modules/` 与 `/node_modules/` 语义完全不同
|
||
(前者只管 `web/` 下),但作为字符串是**包含关系**。
|
||
|
||
**判据**:任何"这条规则在不在"的判断,都要对**行集合**做精确比较
|
||
(`{l.strip() for l in lines}`),不要对全文做 `in`。
|
||
|
||
**反例**:`if "xxx" not in text` 这类判断在多条相似规则并存时必然出错。
|
||
|
||
## trap-4:Gitea 合并接口成功时返回**空 body**
|
||
|
||
**症状**:脚本调用合并接口,HTTP 200,但解析 JSON 抛
|
||
`json.decoder.JSONDecodeError: Expecting value: line 1 column 1`,
|
||
看起来像"合并失败",于是重试 —— 而 PR 其实已经合并了。
|
||
|
||
**根因**:Gitea 的 `POST /pulls/{n}/merge` 成功时 body 为空(不是 `{"merged":true}`)。
|
||
把"HTTP 200 + 空 body"当成失败是客户端的问题,不是服务端的问题。
|
||
|
||
**判据**:合并后 **不要**信 POST 的返回,改 `GET /pulls/{n}`,
|
||
要求 `state=closed` + `merged=true` + `merge_commit_sha` 非空。
|
||
|
||
**反例**:在合并接口上做重试。**永不重试** —— 会得到"第二次合并失败"的假故障。
|
||
|
||
## trap-5:CI 检出是 `git fetch --depth 50`,**取不到 tag**
|
||
|
||
**症状**:想让版本号来自 `git describe --tags`,在 CI 上失败或给出误导结果。
|
||
|
||
**根因**:工作流里是 `git fetch -q --depth 50 origin "$BR"`,浅克隆不带 tag。
|
||
`git describe` 要么报 `No names found`,要么退回到一个和预期无关的短 sha。
|
||
|
||
**判据**:任何依赖 tag 或完整历史的步骤,必须在 CI 里显式
|
||
`git fetch --unshallow` 或 `git fetch --tags`;否则就是这条。
|
||
|
||
**修法(本仓采用)**:版本号的唯一来源改为仓库里的 `CHANGELOG.md`
|
||
(`python3 scripts/version.py`),文件一定在,不依赖 tag。
|
||
|
||
**反例**:`VERSION=$(git describe --tags --always)` —— 本地看着正常,CI 上静默退化。
|
||
|
||
## trap-6:act_runner **不会**自动检出代码
|
||
|
||
**症状**:工作流第一步就报找不到文件 / 空工作区。
|
||
|
||
**根因**:本仓的 act_runner 不会替作业做 `git clone`,工作区起始为空。
|
||
|
||
**判据**:工作流里若没有 `git init` + `git remote add` + `git fetch` + `git checkout`,
|
||
就是这条。
|
||
|
||
**修法**:照 `.gitea/workflows/build.yml` 的「检出代码」步写(带 `x-access-token` 的
|
||
remote,令牌来自 `secrets.GITHUB_TOKEN`)。
|
||
|
||
**反例**:以为 runner 会像 GitHub Actions 那样自动 checkout,直接写业务步骤。
|
||
|
||
## trap-7:`grep -q` 在 `pipefail` 下会被 SIGPIPE 谎报失败
|
||
|
||
**症状**:`echo "$OUT" | grep -q 'PASS'` 明明匹配上了,整条命令却返回非 0
|
||
(141),在 `set -o pipefail` 的作业里表现为"检查失败"。
|
||
|
||
**根因**:`grep -q` 一命中就退出并关闭管道,上游 `echo` 随即收到 SIGPIPE,
|
||
整条管道返回 141。
|
||
|
||
**判据**:`set -o pipefail` + `... | grep -q ...` 同时出现即是这条。
|
||
|
||
**修法**:用 `case "$OUT" in *PASS*) ... ;; esac`,或让 `grep` 直接读文件;
|
||
非用管道不可时用 `set +e; set +o pipefail` + `${PIPESTATUS[0]}`。
|
||
|
||
**反例**:`if echo "$x" | grep -q y; then` —— 时红时绿,且方向完全错。
|
||
|
||
## trap-8:`gofmt -l` 列出文件时**退出码仍是 0**(只看退出码=假绿)
|
||
|
||
**症状**:门禁里写着 `gofmt -l .`(或 `step gofmt -l . || fail=1`),格式乱掉的文件明明被列出来了,
|
||
这一步却**通过**。整条门禁全绿,而仓库里躺着一堆没格式化的文件。
|
||
|
||
**根因**:`gofmt -l` 的正常行为就是"列出不合规的文件并返回 0" ——
|
||
它的退出码表达的是"我跑完了",不是"都合规"。用退出码当判据,等于没判。
|
||
|
||
**判据**:任何"输出即问题"的工具(`gofmt -l`、`prettier --list-different`、`git status --porcelain`)
|
||
都必须**判输出是否为空**,不能判退出码。
|
||
|
||
**修法**:`[ -z "$(gofmt -l <文件...>)" ]`,或者像本仓 `scripts/check_format.py` 那样解析输出;
|
||
并且给它一条**故意弄坏的夹具**证明它真的会红(否则"永远返回 0 的校验器"会一路绿灯)。
|
||
|
||
**反例**:`step gofmt -l . || fail=1` —— 生成器里就是这么写的,一直没人发现。
|
||
|
||
## trap-9:`tar -C dir .` 产生 `.` 根成员 ⇒ 预览 404
|
||
|
||
**症状**:打包与上传都成功、通知也发了,点开预览链接却是 404 或报错。
|
||
|
||
**根因**:`tar -czf x.tgz -C dir .` 会把 `.`(以及 `./index.html`)写进成员名。
|
||
严格的解包器要么拒绝整包,要么解出一层多余的 `.`,于是 `index.html` 不在预期的位置上。
|
||
|
||
**判据**:`tar -tzf <包>` 的第一行若是 `.` 或 `./…`,即是这条。
|
||
|
||
**修法**:先 `cd` 进产物目录,再用通配展开成员名(`( cd "$WEB" && { shopt -s dotglob; tar -czf "$TAR" *; } )`),
|
||
并在发之前断言包里真的有 `index.html`(`tar -tzf "$TAR" | grep -qx 'index.html'`)。
|
||
|
||
**反例**:只看"打包成功 / 上传 HTTP 200"就当预览发好了 —— 那两步都不会因为包结构不对而失败。
|
||
|
||
## trap-10:依赖清单被静默改写
|
||
|
||
**症状**:一次 CI 通过之后,`go.mod` / `go.sum` / `package-lock.json` 与提交里的不一样了;
|
||
本地跑一遍还多了/少了几个依赖,没人改过它们。
|
||
|
||
**根因**:两个"顺手"的默认行为 —— `GOFLAGS=-mod=mod`(构建时自动补全/更新 `go.mod`)、
|
||
以及缺锁文件时回落到 `npm install`(按 `package.json` 重算整棵依赖树并重写锁文件)。
|
||
两者都让"依赖清单"变成**运行时产物**,而它本该是人 review 过的契约。
|
||
|
||
**判据**:夹具 = 门禁开始前后对这几个文件取 sha256;任何一步改写了它们 ⇒ 红。
|
||
|
||
**修法**:`GOFLAGS=-mod=readonly`;缺锁**直接失败**(不接受无约束安装);
|
||
`npm ci`(按锁装、锁与 `package.json` 不一致就报错)。见门禁的 `deps-install` 与 `manifests-locked` 两项。
|
||
|
||
**反例**:`if [ -f package-lock.json ]; then npm ci; else npm install; fi` —— 看起来"更健壮",
|
||
实际是给漂移开了后门。
|
||
|
||
## trap-11:汇总把「未运行 / 被跳过」当「通过」
|
||
|
||
**症状**:某个必需检查压根没跑(失败即停的后果、或运行时被 `if:` 跳过),
|
||
汇总却报"全绿";事后看报告,那一项**根本不在报告里**,谁都没发现。
|
||
|
||
**根因**:汇总逻辑只遍历"跑过的项"。没跑的项不出现 ⇒ 集合变小 ⇒ 全绿。
|
||
另一种写法是 `skipped` 与 `success` 一起放行。
|
||
|
||
**判据**:给汇总喂一个"必需项缺失 / 必需项 skipped"的夹具,它**必须**非绿。
|
||
|
||
**修法**:清单里声明必需项集合,汇总按**清单**(不是按结果数组)逐项核对;
|
||
缺项记 `not_run` 并判红;`aggregate()` 只认 `success`。
|
||
不适用要**在清单里声明**(本仓的 `required_in`),不能在运行时悄悄 skip。
|
||
|
||
**反例**:`status = "failure" if any(x == "failure" for x in results) else "success"`。
|
||
|
||
## trap-12:事件 SHA ≠ 检出 SHA
|
||
|
||
**症状**:CI 里跑的是"分支当前 HEAD",而这次运行的事件指向的是**另一个提交**。
|
||
表现是"我刚推的那一步好像没跑",或者更糟 —— 拿新代码的结论去解释旧代码的产物。
|
||
|
||
**根因**:工作流写 `git fetch --depth 50 origin "$BR" && git checkout -B "$BR" FETCH_HEAD`,
|
||
取的是**当时**的分支 HEAD。只要在事件产生之后又有人推了一次(或重跑旧运行),两者就分叉。
|
||
|
||
**判据**:`git rev-parse HEAD` 必须等于 `${GITHUB_SHA}`(**完整** SHA,不是短 sha)。
|
||
不一致 ⇒ 红。
|
||
|
||
**修法**:检出后立刻核对;不一致时改按精确 SHA 取(`git fetch --depth 50 origin "$EVENT_SHA"`),
|
||
再取不到就失败。门禁的 `identity` 项会**再核对一次**(两道,故意的)。
|
||
|
||
**反例**:报告里只写"分支 main 的构建成功" —— 这个结论没有对应的提交。
|
||
|
||
## trap-13:密钥扫描规则过宽 ⇒ 永远的假红
|
||
|
||
**症状**:接入密钥扫描后立刻红,命中全是**正常代码**:`postgres://{u.quote(user)}:{u.quote(password)}@host/db`
|
||
(模板表达式)、`postgres://governance:***@postgres/governance`(脱敏占位)、
|
||
`X-CI-Token: ${BRIDGE_TOKEN}`。
|
||
|
||
**根因**:规则用 `[^@\s]{6,}` 这种"很宽"的字符类去抓口令段,于是把变量插值、脱敏星号、
|
||
模板表达式全部当成密钥。假红一旦出现,人就会把整个检查注释掉 —— 那比没有检查更糟。
|
||
|
||
**判据**:扫描器必须自带**双向夹具**:合成的真密钥要命中,**良性对照要零误报**,
|
||
而良性对照里要**钉住踩过的误报形状**(防回归)。
|
||
|
||
**修法**:只收"干净字符"的口令段(`[A-Za-z0-9+/=_\-]{6,}`),并对命中值做占位符判定
|
||
(`${...}`、`<...>`、`***`、`changeme`…)。见 `scripts/check_secrets.py` 的 `RULES` 与 `--self-test`。
|
||
|
||
**反例**:为了让门禁变绿去放宽/注释规则 —— 那是降低规则换绿灯,规范 §4.2 明确禁止。 |