第 8 章 测试、CI/CD、代码审查与协作
8.1 CI、CD 与测试的分工
测试检查行为是否符合预期,CI 自动运行已有的检查,CD 把通过门禁的制品交付到目标环境。
我踩过的坑
- 把 Job 说成“具体执行命令的层”,以为“合并 main 才跑”要用外部事件,还以为装了 CI 就会自动测接口。
- 两次“CI 绿了却没跑到测试”。第一次 Workflow 只做
py_compile;改成unittest discover后收集 60 个,却静默跳过 pytest 风格的测试函数与 fixture,同仓用 pytest 能发现 66 个。 - CI 跑不起来时我怀疑过 DeepSeek 审查模型欠费。GitHub Actions 配额和调用审查模型的 API 账单是两笔成本,workflow 连 runner 都没启动时,审查请求根本没发生。
正确理解
- 只配 CI 不写测试,CI 不会自己知道业务接口该怎样工作,它只执行我写好的检查。
- Workflow → Job → Step:Workflow 定义整条流水线和触发条件;Job 是能独立调度、和其他 Job 并行的单元,先后关系用
needs表达;Step 是同一个 Job 里依次执行的命令或 Action。命令由 Step 执行,不是 Job。 - “main 有新提交就跑”用
push加分支过滤即可,另有pull_request、workflow_run等触发事件。 - 门禁让便宜的检查尽早失败。有些集成测试依赖构建产物,放在构建之后也合理,不是“测试必须全在构建前”。
- CI 绿了,还要看日志里实际执行的测试命令、收集数、跳过数,和仓库预期的测试清单对不对得上。审查模型的 CI 跑不起来,按排队、checkout、依赖、模型请求、评论写回的顺序查,也别把本地跑通的模型审查说成 CI 通过。
8.2 单测、集成与 E2E
单测、集成和真实 E2E 各自证明不同的东西,谁也不能替谁下结论。
正确理解
- 单测证明局部逻辑,集成测试证明几个组件能协作,真实 E2E 和产品验收证明用户拿到了预期结果。单测绿了,不能证明外部平台已经收到 Trace。
- 缺凭据或没有 Redis、跑不了集成测试时,写“环境不足,未验证”,不能算通过,也不能算逻辑失败。
- 写入型测试用隔离数据或本轮 run_id,删除前列出要清理的对象、备份路径和恢复办法。曾经发生过测试清理把真实计时记录一起删掉。
- 用户自己把数据改对,只解决了这一次的症状,不代表程序没有边界缺陷。合法输入、非法输入的提示、合法边界的计算要分别判定,用一组合法和非法样本做回归。
- Headless 和交互模式加载的扩展、工作流可能不同。某旧版扩展在没有 UI 时会主动关掉浏览器审阅流程,所以测试要写明运行模式;CLI 能搜索成功,不代表交互弹窗和用户确认链路验收过了。
- UI 截图看着正常,但测试要求的 Mock 任务根本没加载,就等于没测到目标场景。先断言 Mock 数据和 DOM 里的任务数、日期、网络响应都在,再截图看布局。
动手前检查
- 这轮测试删除的数据,能证明只属于本轮吗?
- 环境不足的用例,是否记为“未验证”而不是“通过”?
- 测试运行模式(Headless 或交互)写清了吗?
合并后的回归要定位实际阶段(待学习)
合并前后调用次数不同,先分清是前置查询新增了,还是后置规则变了。给断言明确的阶段和业务结果,保留普通输入和例外输入的对照。集成夹具按稳定标识从配置里取模型或供应商,并断言这项存在。一次从列表第一项取夹具再替换模型名,配置调序后配错了组合,测试失败反映的是夹具变了。
8.3 质量门禁、覆盖率和回归集
覆盖率说明测试执行到哪些代码,不说明断言是否真的检查了正确性。
我踩过的坑
- 把单元测试当作金字塔顶层,回答“上层全部回归、下层挑重要的”。
- 讲回归测试只说“测老功能”,没想到公共函数变更会沿调用链影响其他功能。
正确理解
- 测试金字塔:单元测试在底层,数量多、跑得快、定位准;集成测试在中间;E2E 在顶层,覆盖关键用户流程,但环境成本高。比例按产品风险定,不是固定公式。
- 回归测试是改完之后重跑已有的行为检查,可以包括单测、集成和 E2E,不是另一层测试。便宜的单测尽量全跑,昂贵的集成和 E2E 按影响面、风险和预算挑,但不能只测新功能不管旧行为。
- 重要 Bug 修好后加进回归集,复杂场景再补边界值和关键失败路径。
- lint、类型检查和单测谁更快,要看真实项目和 CI 数据。
- 两种检查测试是否有效的方法:变更覆盖率(Diff Coverage)看新改的代码被执行了多少,避免历史覆盖率掩盖新增盲区;突变测试(Mutation Testing)故意改掉关键条件,看现有断言能不能抓到。突变测试成本高,可以先用在核心逻辑上。两者都替代不了真实用户路径的验收。
- 门禁的数字要带条件看。旧个人 AIHOT 实验里,第一次 Gate 检出 2 个圈复杂度超限和 1 个失败断言,针对性修复后报告 579 个测试通过、变更行覆盖 93%。这只说明当时的规则和测试过了门槛,替代不了业务需求、用户体验、权限和部署验证;门禁自己的覆盖率参数和测试范围也要有单测。
- 评分器读 JSON 证据之前,要先检查来源文件本身。一次个人 Agent 代码审查用了打开后
fstat、O_NOFOLLOW、有界读取、严格 UTF-8/JSON 校验、关闭 fd,防止 symlink、超大文件、编码损坏污染 Gate 账本。O_NOFOLLOW一般不保护所有父路径,目录可能被替换时,要用基于目录 fd 的方案。(来自一次子代理审查报告,未复跑。) - 评估账本的输入有非法 UTF-8 时,要拒绝,并证明原文件一个字节都没变。测试不只看有没有抛异常,还要比对落盘哈希、有没有半写、索引状态。失败路径的数据保护要和成功路径一样严格。
检查结果与阻断条件分开(待学习)
把无规则、缺测量、符合、违规分开。只有反对样本时,仍可检查明确要避开的区间。没有证据时保留空评分,构建是否继续由调用方按契约决定。必须豁免一种提示时,用明确的列表限制范围,新出现或未识别的缺口沿用原保护。测试分别覆盖正常通过、没有足够证据、真实违规和应拦的未知提示,也确认独立 CLI 与真实构建入口的退出行为。
8.4 Secrets、Cache 与 Artifact
三者分别是输入凭据、可复用的中间产物、本次运行的输出。
| 类型 | 用途 |
|---|---|
| Secrets(输入凭据) | 流水线用的 Token、密码,按权限提供,不写进源码和普通日志 |
| Cache(复用中间产物) | 缓存可重建的依赖、构建中间结果,减少重复工作 |
| Artifact(本次输出) | 保存此次运行的报告、包、截图供后续 Job 或人下载 |
我踩过的坑
- 只记住三件套名称,没理解“输入凭据 / 重用 / 输出”的不同,也分不清 CI Secrets 和容器运行时的 Secret。
正确理解
- CI 平台的 Secret 通常通过表达式或运行环境交给 Step;容器的 Secret 常通过挂载文件交给服务,不是同一套实现。
- 日志自动掩码挡不住误打印或换了编码的凭据。用最小权限、短期凭据,日志里不输出敏感值。
校验最终产物和真实写入位置(待学习)
开源检查分开查当前源码、Git 历史、图片和最终安装包。曾在 Swift 发布可执行文件里发现源码搜索没找到的本机路径,来自调试信息和资源回退代码。按同一产物重新扫描后才确认这类命中消失。命中为零只覆盖本轮检查项。
测试安装命令时,除临时工作目录和 HOME,还要查包管理器的缓存与全局前缀。例如 npm 全局安装应确认前缀和目标目录也在隔离范围内。实际运行后核对写到哪里、预期文件是否存在、完成输出有没有出现。退出码为零时也可能停在交互选择器。
8.5 Issue、PR 与分支复审
Issue 说清问题,PR 说清改动和证据,独立分支隔离未完成的工作。
我踩过的坑
- 2026-09-15 我反馈:额度快重置时会同时交给 Agent 多个任务,有的显示已完成,隔天测试才发现代码没进 main。问题不在 worktree,而在“改好分支”和“交付到目标分支”被混成一个状态。
- AI 加快了代码产出,也挤掉了我深入理解细节的时间。提交 PR 前,我要能讲清业务背景、调用链、影响范围和测试证据。
Issue 与 PR
- Issue 记录复现步骤、目标和验收标准;PR 记录实际修改、测试结果和风险。
- 动手前先读仓库规则、主分支和调用链,在独立分支或 worktree 里改。审查时看需求有没有覆盖全、边界有没有考虑、证据是否充分。
- 自我审查不能只在本次 PR 打一次勾。反复发现的漏项可以转成提交前检查项,但检查表要跟项目更新。
- 有效的二次检查包括:用户强调的限制是否还在、改过的文件有没有回读、测试证据是否对应提交的版本、索引和链接和状态是否同步、已知风险是否记录。
先查再撤的最短命令索引(待复习):git status --short --branch 查工作树和分支;git diff 看未暂存差异,git diff --cached 看本次待提交内容;git log --oneline -10 与 git show <commit> 查历史。撤销暂存和丢弃正文是不同动作,已共享提交通常用新反向提交恢复。旧速查里“没 push 可以随便 reset”“reflog 一定能救回”的说法不能照搬,未提交内容仍需先保全。Git历史速查。
有依赖的 PR
- 有依赖的 PR:子 PR 可基于父 PR 分支,独立功能从最新主分支开始。父 PR 更新、改写历史或以 Squash 合并后,要核对每层的新基础提交、祖先关系和独立 diff,可用
range-diff比较,或受控地用rebase --onto重放子分支提交再重新验证。 - 显示“可合并”和旧的 CI 结果,都不能证明子分支已经在新的父版本上验证过。
--force-with-lease比直接强推安全,但仍会改写远端历史,只在获得授权的个人分支上用,主干不强推。- 待补:父 PR Squash 合并后怎样保持子 PR 的 diff 干净,要按真实的 Git 历史判断是否需要重建提交。
秘密与 .gitignore
- 在公开源码里发现硬编码密钥,不能因为“公开能看到”就拿去调用验证。应通过拥有者或平台的安全披露渠道报告,由有权限的人核对暴露范围、撤销或轮换、清理历史并审计使用记录。秘密只要在 Git 历史里出现过,删掉当前代码也不等于风险消失。
.gitignore不影响已经被跟踪的文件和历史。停止跟踪、清理当前提交、处理远端历史是三件事,要分别核对,并且不能误伤无关改动。
交付状态
- 任务收尾要说明改动所在分支、对应 PR、已完成的验证,以及是否还等合并或冲突处理。未合并的改动要有可回查的归宿,不能只报“完成”,也不能为凑完成状态擅自合并或删除。
- 封存记录说收尾规则已经写进正式规范,不等于所有历史分支都已经逐一核验过。
Worktree 软链接、规范落地和交接模板的具体故障,案例见附录 A.8.1、A.8.2、A.8.3。
来源
旧库 90-归档/20-个人/20-草稿箱/AI规范优化收件箱-已归档.md 第 3241—3246 行的用户原话;AI规范优化收件箱-20260923-最终封存.md 第 9—10 行的后续处理记录。
确认 Agent 和构建跑在正确的仓库(待学习)
外部任务入口成功触发后,先核对实际挂载的仓库、分支和工作目录。某次入口能回消息,但挂的仍是另一仓库。环境面板与触发入口是否消费同一份配置,需要用实际任务确认。
复用依赖前核对当前工作区的锁文件与构建根目录。曾有 worktree 通过依赖软链接跑过类型和单测,构建器却拒绝根目录外的链接。改在该 worktree 按锁文件安装后构建通过。三种验证结果分别记录。
复用时仍需核对的边界(待学习)
触发入口还要分清新版 Cloud 与 Legacy:面板发布成功,不证明集成入口消费了这份配置。2026-11-04 的排查中,Linear 仍走 Legacy;旧环境具体绑定尚未核实,不能用新版设置替它作证。
8.6 安全重构的接口兼容
先保留已有接口行为,再逐步迁移调用方。
我踩过的坑
- 以为改完上游输出就算完成,没想到旧的下游可能解析失败,或者悄悄走进默认业务分支。
正确理解
- 拆分大的 types 文件时,先让
index.ts继续 re-export 原有类型,验证没问题后再逐步迁移旧的 import。 - 图片对象有
source_url(原图)和archive_url(归档图)两个地址。归档图曾短时间不可读,导致多模态调用返回 400。当时的做法是默认仍然“归档优先”,只让这一处多模态调用显式改成“原图优先”,并实测原图可用。 preferred_url从属性改成preferred_url(priority=...)方法后,旧调用处要补上括号,并测试“地址缺失”和“优先级”组合出的四种情况。- 新字段的契约还没确认时,先保持旧行为,新路由默认关闭。某个环境里 1,382 个单测通过,不等于灰度已经验收。
- 跨服务新增字段的一种发布顺序:先让消费者同时接受旧数据缺字段和新数据带字段,再让生产者逐步输出新字段,真实语义启用前保留默认关闭的开关。例如旧事件只有
name,新事件增加display_name,兼容窗口内不能因升级生产者就停发旧消费者需要的字段。 - 消费者要测试新旧版本混跑、消息重放和迟到任务。破坏性变更按“扩展—迁移—收缩”推进,必要时双读或短期双写,并准备版本指标和回退计划。
- 回滚前先查哪些消费者已经用了新字段、数据有没有落库。代码回退不会撤销已经产生的副作用,见第 6.9 节。
- 删除“已停用的服务”也要沿依赖层逐层检查。旧的翻译或摘要入口可能已经停用,但内部的解析、翻译实现仍被其他业务调用,Embedding 生成层也可能还在给图片搜索用。
- 先分清对外接口层、共享实现层、生成与存储层,搜出真实调用方和动态注册的入口,验证迁移后的功能正常,再分阶段删除。
- 批量处理的规则可以共享,但每个输入的期望、实际结果、评分、错误和证据要分开保存;预览和真实请求要用同一份结果。
来源
旧 Wiki 10-wiki/personal/wiki/concepts/发布顺序(消费者优先).md 和历史 2026-07-26 代码链路草稿。旧例子未重新验证今天的分布式服务版本。
字段不再使用,不等于现在就能删(待学习)。旧提问是“后端已经不用一个请求字段了,为什么不能直接删掉?”调用方可能依赖字段生成类型或做表单校验。先保持名称、类型和默认值,在接口文档标 deprecated,并说明不再影响业务;核对所有调用方不再依赖后再删除。标废弃本身不等于运行时拒收旧请求。
来源:后端-Python与接口实践。
批量路径替换要覆盖测试和动态加载(历史踩坑)。原记录提醒:只匹配 from 会漏掉 lazy(() => import(...)) 与 vi.mock(...)。迁移后要核对业务 import 与 mock 指向同一模块,否则测试可能误用真实 API;搜索旧路径时也要查这两类调用。
来源:工具-开发工作流。
8.7 TDD 的纵向切片
一次只推进一个可验证的用户行为,而不是先写一堆测试再写一堆实现。
2026-09 的 bigpowers 第三方 develop-tdd Skill 提供了一个反面例子:先批量写 10 个互不对应的测试,再一次写完 10 段实现,表面上走过 Red/Green,但失败时很难判断哪项业务需求真的被落实。
正确理解
- TDD 以一个可验证的行为为单位:先写一个失败的测试,再写最小实现,重跑通过后走一遍真实用户路径,然后才进入下一块。
- 测试关注输入、输出、数据库和 UI 这些外部契约;权限、异步取消和视觉布局,还需要集成测试或页面上的证据。
- 第三方 Skill 里“只在特性分支工作、禁止动 main”的规定,不是本仓库的授权规则。借鉴它的测试方法即可,不照搬它的目录和角色限制。
来源
旧第三方源码快照 20-个人/20-调研报告/bigpowers-技能源码/develop-tdd/SKILL.md 和 REFERENCE.md,原项目仓库 bigpowers。不代表本人仓库已接入该 Skill。
本章原始笔记
8.8 隔离工作树,也要隔离依赖与验证组合(待学习)
worktree 只隔离文件。按当前锁文件建立环境,核对解释器和 Shell;无关 SDK 类型错或 Bash 空数组差异,先在未改基线复现。绝对软链接在本机可用,也可能让干净克隆或构建器失败;类型、单测与构建分别验。
多个 PR 同改一函数,文本合并成功不代表导入、单位和阈值仍兼容。保留各自分支,临时组合跑双方回归;只能证明该组合,不冒充最终合并或线上验收。
来源与当时边界
8.9 异步测试等可观察结果,不猜 flush 次数(待学习)
固定一次 flush 不证明真实异步读取和状态提交结束,长 setTimeout 也不能说明正确。按行数、saved、轮询选择等条件等待;账号切换等旧请求结束再做负断言。立即反馈仍立即测,不能全部延后。30 个负载下独立进程通过只提供稳定性证据,不保证永不波动。
来源与当时边界
8.10 安装命令按原样执行,再验真实 MCP 协议(待学习)
Git 安装不带分支会落默认分支,包还在功能分支时,配置语法正确也启动不了;基础 CLI 装好也不代表可选 MCP SDK 已装。干净环境按原命令执行,再用 stdio 客户端 list_tools 和一次调用,分别记录安装、启动、协议和 GUI。预览分支已跑通协议,默认命令失败、三个 GUI 未测,盲选偏好或文档分数不能抹掉这些条件。