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

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