docs(agents): traps 14-18(假检查/预览顺序/观察到的 context/协议降级/范围退化)

This commit is contained in:
姚章浩
2026-10-12 11:15:18 +08:00
parent 164dc2f72c
commit 75a6085844
2 changed files with 102 additions and 1 deletions
+31
View File
@@ -72,6 +72,37 @@ python3 -c "import json;d=json.load(open('ci-report.json'));print(d['overall_sta
# 期望:success 14
```
### 改了什么(第二轮审查修正)
审查(GPT,第二轮)在**通用模板**与**预览发布顺序**上又找出 6 处,逐条修完并补了负例:
- **P0 通用模板的 Python 检查是空跑** → `templates/ci-gate.py` 的 `deps-install/format/static/build/tests`
对 Python 现在**真的执行**(`uv sync` / `uv run ruff` / `compileall` / `uv run pytest`);
工具缺失 ⇒ 明确失败(`工具缺失:uv(…不空跑)`),不再"没写检查所以返回成功"。
前端测试**进程退出码也算判据**:报告写 pass 但进程退出 1 ⇒ 红(实测过)。
前端框架不再写死 vitest:读 `scripts/test-scope.json` 的声明,认不出来 ⇒ 明确失败。
通用清单补了 `security`(密钥扫描 + 依赖漏洞),工具缺失/输出解析不了 ⇒ 红。
- **P0 预览发布早于报告完整验证** → 预览逻辑移进 `.gitea/scripts/ci_preview.py`:**先**调
`ci_report.verify()`(与上报同一份核对逻辑),有问题就**一个 publish 请求都不发**;
通过后才打包(断言包内有 `index.html`、无 `.` 根成员)→ POST → 报告里每个地址都探测 200。
`scripts/ci_preview_negative_test.py` 用**假 bridge 记录请求**证明:10 个坏报告分支 publish 次数都是 0,
合规报告正好 1 次。
- **P1 提交范围可能漏查** → `.gitea/scripts/ci_gate.py` 以**准确 Git 范围**为准(push 事件用
`before..after`,新分支用 `after --not --remotes`),事件声明的条数与列表/Git 范围不一致 ⇒ 拒绝;
列表被截断但 Git 范围可用 ⇒ 以 Git 为准并写明;空范围、浅克隆取不到 `before`、列表提交不在检出里
⇒ 全部拒绝;手工运行只核 HEAD 但**写明**这一点。`--self-test` 覆盖 11 个分支。
`.gitea/scripts/ci_checkout.sh` 顺带把事件 `before` 也取下来(否则范围算不出来)。
- **P1 合并必需检查可以为空** → `adopt-existing.py` 的必需 context 只能来自**明确策略**
(`--require-context` 或仓库里的 `.gitea/required-contexts.txt`);两个都没有 / 文件是空的 ⇒ 拒绝合并,
**不再用"体检观察到的状态"顶替**。同时核对 PR 目标分支 == 默认分支、`state=open`、head 仓库就是本仓。
`--self-test-chain`(假 Gitea + 真实 `merge_pr()`)证明 13 个分支里只有"策略齐 + 必需 context 全 success
+ 完整获批 SHA + base/state/来源都对"才发出 merge 请求。
- **P1 协议被静默降级** → 检出逻辑移进 `.gitea/scripts/ci_checkout.sh`,remote 直接用
`GITHUB_SERVER_URL` 原样拼接并**断言没有降级**(https 不许变 http)、URL 里不许带凭据、
检出必须等于事件完整 SHA。`--print-remote` 可本地验证协议保留。
仍未做/未验证(见文末"未部署"):本地检查通过 ≠ 远端 CI 已跑通;两仓**均未推送**。
## [0.1.0] - 2026-10-10
### 改了什么
+71 -1
View File
@@ -205,4 +205,74 @@ remote,令牌来自 `secrets.GITHUB_TOKEN`)。
**修法**:只收"干净字符"的口令段(`[A-Za-z0-9+/=_\-]{6,}`),并对命中值做占位符判定
(`${...}`、`<...>`、`***`、`changeme`…)。见 `scripts/check_secrets.py` 的 `RULES` 与 `--self-test`。
**反例**:为了让门禁变绿去放宽/注释规则 —— 那是降低规则换绿灯,规范 §4.2 明确禁止。
**反例**:为了让门禁变绿去放宽/注释规则 —— 那是降低规则换绿灯,规范 §4.2 明确禁止。
---
### trap-14|"这个语言我没写检查" = 假报成功(通用模板的 Python 门禁空跑)
**症状**:通用模板套到一个 Python 项目上,`deps-install / format / static / build / tests` 五项**全绿**,
但一个 Python 检查都没跑 —— 函数体只打印一句话就 `return SUCCESS`。
**根因**:模板最初只为 Go+Node 写实现,Python 分支留了"占位返回成功"。占位返回成功不是"还没做",
是**假报成功**:它会让人以为这个项目被检查过。审查是靠"模拟一个 Python 项目,看那五项是不是真的执行了"
才发现的 —— 只看 YAML/看代码是看不出来的。
**判据**:每一门识别到的语言都必须**真的执行**;工具缺失、依赖没按锁装、输出解析不了 ⇒ **失败**。
**修法**:`uv sync --frozen` / `uv run ruff format --check` / `compileall` / `uv run pytest`;
`need()` 找不到工具就抛错(转成 FAILURE)。前端同理:测试**进程退出码非零**必须红
(报告写 pass 不算数),框架按 `test-scope.json` 声明,认不出来就失败。
### trap-15|预览放在"报告核对"之前 = 发出去就收不回来
**症状**:预览步骤只读 `overall_status` + `commit_sha` 就发布;完整报告核对在后面的通知步骤。
报告缺项时,**预览已经发出去了**,几分钟后才报错 —— 那时 URL 可能已经被人打开/转群。
**根因**:把"发布"当成"通知"的一环。预览是**不可撤回**的对外动作,不能排在质量结论之前。
**判据**:发布前必须调用**同一份**核对逻辑(`ci_report.verify()`),有任何问题 ⇒ **一个 publish 请求都不发**。
**修法**:`.gitea/scripts/ci_preview.py` 内部先核对再发布;`scripts/ci_preview_negative_test.py`
用假 bridge **数请求**证明坏报告 0 次、好报告 1 次。
### trap-16|用"观察到的 context"代替"要求哪些检查"
**症状**:合并前没指定必需 context 时,脚本拿"体检时在该仓看到过哪些状态"当必需列表。
**根因**:`combined state` 只报"报过状态的都成功",一个**无关**的检查成功就能让它变成 `success`。
于是"没跑过必需检查"的 PR 会被合进去。
**判据**:要求哪些检查只能来自**明确策略**(`--require-context` 或 `.gitea/required-contexts.txt`);
策略缺失或为空 ⇒ 拒绝合并(空不等于"没有要求")。
**修法**:见 `scripts/adopt-existing.py` 的 `resolve_required_contexts()` 与 `--self-test-chain`
(假 Gitea + 真实 `merge_pr()`,断言 merge 请求发没发)。同时核对 base 分支/PR 状态/head 仓库。
### trap-17|remote 协议被"顺手"拼成 http
**症状**:注释说"保留服务端给的协议",代码却是 `git remote add origin "http://${HOSTPORT}/..."` ——
服务端给的是 https 时会**静默降级**成 http(凭据与产物走明文)。
**根因**:把 `${SRV#*://}` 取出来的 host:port 再拼一个固定的 scheme。取 host 的动作本身就把协议丢了。
**判据**:remote 直接用 `GITHUB_SERVER_URL` 原样拼,并**断言**最终 scheme 与服务端一致;
未知 scheme 直接拒绝;URL 里不许带凭据。
**修法**:`.gitea/scripts/ci_checkout.sh`(`--print-remote` 可本地验证协议保留);
YAML 里只调用它,不再内联这套拼接。
### trap-18|范围校验回退成"最近 N 条"或"接受截断的列表"
**症状**:范围算不出来时退化成 `git log -n 5`(和历史无关),或直接采信事件负载里那串 commits。
**根因**:事件负载里的 commits **可能是截断的**(实测:声明 6 条、列表只给 1 条),
浅克隆里 `before` 可能根本不存在 —— 两种都会让"本次改动"少核几条,而且全绿。
**判据**:以**准确 Git 范围**为准(push 用 `before..after`,新分支用 `after --not --remotes`);
事件声明条数与 Git 范围不一致 / 空范围 / 浅克隆取不到 before / 列表提交不在检出里 ⇒ 全部**拒绝**;
手工运行比不出范围时只核 HEAD,但必须**写明**。
**修法**:`.gitea/scripts/ci_gate.py` 的 `resolve_scope()`(`--self-test` 11 个分支)+
检出脚本顺带把事件 `before` 取下来。