# 已知陷阱(全文) > 这份文件是 `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 `(保留磁盘文件)。 规则齐全不等于没被跟踪 —— 断言要查**两件事**:规则在、且 `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` —— 时红时绿,且方向完全错。