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

11 KiB
Raw Blame History

已知陷阱(全文)

这份文件是 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 明确禁止。