docs(agents): traps 14-18(假检查/预览顺序/观察到的 context/协议降级/范围退化)
This commit is contained in:
@@ -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
@@ -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` 取下来。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user