Files
knowledge-governance/docs/agents/traps.md
T
姚章浩 96ac67e744 docs(agents): traps 补 5 条、CHANGELOG 记这批 CI 改动的改了什么与怎么验收
新增陷阱(只追加、不复用旧号):
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 全绿。
2026-10-12 00:11:10 +08:00

208 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 已知陷阱(全文)
> 这份文件是 `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 明确禁止。