Files
knowledge-governance/docs/agents/traps.md
T
姚章浩 5f3a71cade
build / build (push) Successful in 26s
feat(version): 版本号唯一来源 = CHANGELOG.md,并要求写清改了什么与怎么验收
背景:本仓此前没有任何版本/构建元信息 —— 没有 ldflags 注入、也没有产物可读的
版本号,"线上跑的是哪个提交"答不出来;"这次改了什么、怎么验收"也没有载体。

落地:
- CHANGELOG.md:**版本号的唯一来源**(正本 §6.1:版本号只准有一处)。刻意不放
  VERSION 文件、也不靠 git tag —— CI 是 `git fetch --depth 50`,取不到 tag,
  `git describe` 会静默退化。每个已发布版本必须有两节:### 改了什么 与 ### 怎么验收。
- scripts/version.py:从 CHANGELOG 顶部解析版本号;解析不到即非 0 退出(构建据此失败)。
- scripts/check_changelog.py:结构自检(两节齐、带日期、版本号不重复且严格递减、
  小节不为空),带 --self-test 反向自检。
- internal/version:三个构建期注入变量 + 契约测试(注入的号必须等于 CHANGELOG 顶部)。
- Makefile:build 带 -ldflags 注入;verify 增加 changelog-check 与 version-contract。
- Dockerfile:ARG VERSION/COMMIT_SHA/BUILD_TIME + ldflags(未透传时落 dev —— 故意显眼,
  好过看起来正常的假版本号)。
- CI:新增「版本与变更记录契约」步,并显式断言契约测试真的 PASS(被跳过的断言等于没有断言)。
- docs/提交规范.md(ci_gate.py 的报错文案一直在指它)、docs/agents/traps.md(7 条实测陷阱)。

验证(都真跑过):
- make version → 0.1.0;make changelog-check → 合规
- make version-contract → PASS;注入 9.9.9(CHANGELOG 里没有)→ FAIL(反向自检)
- 删掉真实 CHANGELOG 的「怎么验收」小节 → 报红(对真实文件做,不只是夹具)
- go build ./... 与 go vet ./internal/version/... 通过

未做(会与在审 PR #2 冲突,待其合并后在 main 上补):
- GET /version 端点(internal/httpapi/server.go)与 cmd/api 的 -version 开关
- compose.yaml 透传 build args(当前由 compose 构建的镜像会报 dev)

⚠️ 未跑 make verify 全量(含 go test ./... 与前端),CI 是本次的测试证据。
2026-10-10 18:13:24 +08:00

5.6 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 —— 时红时绿,且方向完全错。