Beads CI 测试面审计：从 4362 个 Go 测试到分级验证体系的工程实践

Beads CI 测试面审计从 4362 个 Go 测试到分级验证体系的工程实践【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads本文基于 Beads 仓库 engdocs/CI_TEST_SURFACE_AUDIT.md 审计快照撰写聚焦仓库当前的测试资产盘点、CI 工作流拓扑与差距分析。适合需要理解本地命令 ≠ CI 契约问题、或正在为大型 Go 仓库规划分级 CI 体系的工程师阅读。一、审计背景为什么一个仓库需要测试面审计Beads 是一个用 Go 编写、以 Dolt 为存储引擎的轻量级 Issue 追踪器仓库根目录 README.md 将其定位为 A memory upgrade for your coding agent。随着代码库增长到包含嵌入式 Dolt 引擎、代理服务器模式、MCP 集成、npm 包装层与网站等多个交付面测试资产的数量和种类快速膨胀而 CI 却没有围绕单一规范性测试契约组织。engdocs/CI_TEST_SURFACE_AUDIT.md就是针对这一状况的审计快照snapshot而非最终 CI 策略。它的数据来源包括origin/main某提交、Makefile、scripts/test*.sh、.buildflags、.test-skip、.github/workflows/*.yml以及通过git ls-files、go list、rg得出的测试文件清单。审计的用意是从第一性原理出发搞清楚仓库能验证什么、CI 现在实际验证了什么、下一步该清理什么。二、测试面总览69 个包、610 个测试文件、4362 个测试函数审计首先给出了一个量化的测试面全貌测试面当前规模 / 命令CI 状态Go 包go list ./...共 69 个包核心 PR/main CI 直接运行go test而非scripts/test.shGo 测试文件610 个*_test.go主要通过 Linux/macOS 的./...覆盖含排除项与 build tagGo 测试函数4362 个func Test...声明PR/main CI 使用-short并跳过^TestEmbeddedGo 基准测试46 个func Benchmark...声明仅本地/手动运行嵌入式 Dolt 测试157 个TestEmbedded*声明风险路径上条件性启用 20 分片 CI 矩阵main push/merge queue 始终运行integration 标签测试31 个带integrationbuild tag 的文件仅夜间全量横扫部分 Docker 套件在 PR CI 运行MCP Python 包uv run pytest、uv run ruff、uv run mypy已文档化/配置build/publish 工作流未运行这些检查npm 包npm test、npm run test:integration、npm run test:all发布流程未运行包测试网站npm run build、npm run typecheck部署工作流仅在 main push 时构建typecheck 未被 CI 使用核心结论在改动 CI 机制之前应先定义命名的验证层级tier并让每个层级映射到一个仓库自有的命令。当前本地文档、Make 目标、包装脚本和 Actions 任务各自描述了重叠但不同的契约这正是审计要暴露的核心问题。三、本地测试面从 .buildflags 到 Make 目标3.1 规范构建标记.buildflags.buildflags 是普通本地 shell 脚本的构建标记来源其行为如下默认CGO_ENABLED1除非调用方已显式设置导出BEADS_BUILD_TAGSgms_pure_go向GOFLAGS追加-tagsgms_pure_go幂等重复 source 无副作用。文件注释解释了原因go-mysql-server 在 cgo 下默认链接 ICU而 Beads 从不使用 SQL REGEXP因此始终以gms_pure_go标签构建让正则表达式走 Go 标准库而非 ICU 路径详见 engdocs/ICU-POLICY.md。正常发布路径是 CGO 启用 纯 Go 正则ICU 路径只是可选的维护者路径。3.2 Make 目标清单目标命令路径用途make buildgo build -tags $(BUILD_TAGS) ./cmd/bd以gms_pure_go构建本地bd二进制make testTEST_COVER1 ./scripts/test.sh带覆盖率与.test-skip处理的本地默认套件make test-icu-path./scripts/test-icu-path.sh ./...可选的 ICU 正则路径非正常验证make test-full-cgo别名到make test-icu-path已废弃的兼容目标make test-regressiongo test -tagsregression,$(BUILD_TAGS) ./tests/regression/...对照基线发布版的差分回归套件make test-upgrade构建后运行scripts/upgrade-smoke-test.sh上一版本升级冒烟门禁make test-cross-version构建后运行scripts/cross-version-smoke-test.sh跨版本升级冒烟覆盖make test-migration构建后运行scripts/migration-test/run.sh跨存储时代的迁移保真度测试框架make benchgo test -bench. ./internal/storage/dolt/完整 Dolt 基准套件make bench-quick更短的基准运行-benchtime100ms本地性能迭代make fmt-checkgofmt -l .格式门禁make check-docs构建无 CGO 二进制然后运行scripts/check-doc-flags.shCLI 文档 flag 新鲜度此外从 Makefile 可以看到面向 CI 的包装目标make ci-pr-core、make ci-pr-policy、make ci-pr-lint分别调用 scripts/ci/pr-core.sh、scripts/ci/pr-policy.sh、[scripts/ci/pr-lint.sh)make ci-package-mcp/make ci-package-npm则分别调用 scripts/ci/package-mcp.sh 与 [scripts/ci/package-npm.sh]。3.3 Go 测试运行器scripts/test.shscripts/test.sh 是 engdocs/TESTING.md 推荐的本地包装器。它会source.buildflags与scripts/ci/lib/test-env.sh读取.test-skip并将组合出的-skip正则传给go test默认执行go test -timeout 25m ./...审计快照写作时为 3m后经测量上调脚本注释记录了cmd/bd是最慢包、默认套件约 1090 秒测试时间的事实支持-v、-timeout、-run、包参数与额外-skipTEST_COVER1时启用-covermodeatomic -coverprofile覆盖率BEADS_TEST_SHARED_SERVER1时可启动一个共享的 Dolt 测试服务器把原本 8~16 个并发 dolt 进程收敛为 1 个当测试范围包含cmd/bd时会预构建一次bd二进制并导出BEADS_TEST_BD_BINARY避免每个子进程测试各自go buildCI 侧则由主工作流用预构建产物提供同一快速路径。审计时点.test-skip仅含注释、没有生效的跳过模式。四、构建标签与特殊测试模式构建标签 / 模式观测到的测试面当前命令默认 CGO gms_pure_go大多数 Go 测试./scripts/test.sh、make test、PR Linux/macOS 任务!cgo3 个测试文件仅被 CI 的纯 Gocmd/bd任务部分覆盖cgo186 个测试文件CGO 启用时覆盖含常规 Linux/macOS CIintegration31 个提及integration的测试文件夜间广扫部分 PR 任务regression2 个测试文件make test-regression、regression 工作流e2e1 个测试文件未观察到常规 CI 门禁scripttests1 个测试文件未观察到常规 CI 门禁chaos1 个测试文件未观察到常规 CI 门禁regression discovery1 个测试文件仅手动/专用testing.Short()出现在 25 个测试文件中。主 PR Linux/macOS 矩阵以-short运行因此即使 build tag 被选中部分慢测试或外部路径测试也会在此被有意跳过。五、嵌入式 Dolt 测试面条件性 20 分片矩阵嵌入式 Dolt 测试进程内 Dolt 引擎、无需服务器从 PR/核心矩阵中拆出CI 核心 Linux/macOS 使用-skip ^TestEmbedded.github/scripts/ci-embedded-tier.sh 决定是否运行完整嵌入式覆盖build-embedded预构建/tmp/bd-embedded-test、/tmp/embeddeddolt-test、/tmp/bd-cmd-testrace 启用test-embedded-storage通过 .github/scripts/embedded-storage-test-shard.sh 把internal/storage/embeddeddolt的Test*排除TestConformance分 5 片设置BEADS_TEST_EMBEDDED_DOLT1test-embedded-cmd通过 .github/scripts/embedded-test-shard.sh 把cmd/bd的TestEmbedded*分 20 片。分层检测器tier detector在以下情况运行完整嵌入式覆盖push 到mainmerge queuePR 触及cmd/、internal/、tests/、scripts/、.github/scripts/、.github/workflows/、Go 模块/构建输入、根级 agent/发布文档或任何*.go文件。文档/元数据-only 的 PR 则跳过嵌入式矩阵。六、发布与迁移测试面发布相关的本地脚本独立于常规 Go 测试运行器脚本 / 目标范围scripts/upgrade-smoke-test.sh上一版本升级场景覆盖数据、模式、角色、doctor 与变更scripts/cross-version-smoke-test.sh旧版本创建数据后候选版本的可读性scripts/migration-test/run.sh丰富的迁移数据集、快照、保真度检查与配方发现tests/regression/...对照tests/regression/BASELINE_VERSION的差分 CLI/存储行为这些套件有价值但在当前 CI 中并非一个统一的发布门禁。七、非 Go 包测试面区域可用本地命令当前问题integrations/beads-mcpuv run pytest、uv run pytest --covbeads_mcp tests/、uv run ruff check src/beads_mcp、uv run mypy src/beads_mcp、uv build测试/lint/typecheck 已文档化但未在发布前运行npm-packagenpm test、npm run test:integration、npm run test:all发布工作流发布时不运行包测试websitenpm run build、npm run typecheck部署工作流仅在 main push 构建与链接检查typecheck 未运行PR 无网站门禁plugins/beads清单文件与生成插件资产版本一致性已检查但无明显插件清单/schema 门禁从 integrations/beads-mcp/pyproject.toml 可以看到[tool.mypy]、[tool.ruff]、[tool.pytest.ini_options]等配置节npm-package/package.json 则定义了test、test:integration、test:all三个脚本。八、当前 GitHub Actions 工作流拓扑8.1 拆分后的 PR/Main 工作流原先单体的ci.yml已按层级/领域拆分工作流文件均位于 .github/workflows/pr.ymlPR 与 merge queue 基线。拥有 Linux 构建产物阶段、PR policy/core/lint 包装任务、兼容性 policy/lint 任务、消费 Linux 产物的包门禁、存储域/uow 测试以及聚合检查PR / CI Gate / Requiredpr-risk.ymlPR 与 merge queue 风险任务。拥有嵌入式 Dolt 风险检测、嵌入式 build/storage/cmd 分片、Nix flake 冒烟以及聚合检查PR Risk / CI Gate / Requiredmain.ymlpush 到main的分支健康。重跑基线包装器、包门禁、Linux/macOS 短覆盖、Windows 冒烟、嵌入式 Dolt、Nix、存储域/uow以及升级后的 Linux 无 short 集成分片。按显示名保留的关键任务Build Artifacts运行make ci-pr-policy、make ci-pr-lint构建bd-linux-gms-pure并上传带校验和的 run-scoped 产物Check build-tag policy运行scripts/check-build-tags.sh与scripts/check-go-install-guidance.shCheck cmd/bd pure-Go tests compile (CGO_ENABLED0)CGO 禁用的 cmd/bd 构建、测试二进制编译与聚焦纯 Go 测试子集Check version consistency、Check no duplicate migration versions、Check doc flags freshness以及仅 PR 的Check for .beads changesPR Policy (wrapper timing)、PR Core (wrapper timing)、PR Lint (wrapper timing)Package Gate (MCP)、Package Gate (npm)、Package Gate (website)Test (storage domain uow)Build (Embedded Dolt)、Test (Embedded Dolt Storage N/5)、Test (Embedded Dolt Cmd N/20)、Test (Proxied Dolt Cmd N/15)、Test (Embedded Dolt Conformance)、Test (Server Dolt Conformance)、Test (Server Dolt Full Suite N/16)聚合必需检查候选PR / CI Gate / Required与PR Risk / CI Gate / Requiredpr-risk.yml 中通过ci-gate任务与.github/scripts/ci-gate.sh评估仅 main 的平台与集成任务Test (ubuntu-latest)、Test (macos-latest)、Test (Windows - smoke)、Main Linux integration packages (N/6)、Main Linux integration cmd/bd (N/8)Check formatting、Lint、Test Nix Flake。8.2 其他工作流工作流触发主要验证regression.ymlpush 到 main、PR 到 main、手动检测器在 push/manual、PR 标签run-regression或风险路径上运行 regression测试命令为go test -tagsregression,gms_pure_go -timeout20m -v ./tests/regression/...cross-version-smoke.yml标签、PR、手动PR 测试最近 5 个发布标签测试最近 30 个经scripts/upgrade-smoke-test.shmigration-test.yml标签、手动构建候选并运行scripts/migration-test/run.sh非 PR/main 门禁nightly.yml每日调度、手动go test -v -race -tagsintegration,gms_pure_go -coverprofilecoverage.out -timeout30m ./...且BEADS_TEST_SKIPdolt检查覆盖率 ≥ 30%nix-build.ymlPR/push 触及 Nix 或 Go 模块文件、手动nix build .#default --print-build-logsdeploy-docs.ymlpush 到 main 触及website/**或scripts/generate-llms-full.sh、手动npm ci、生成llms-full.txt、npm run build、内部链接检查、非阻塞外部链接检查、部署 Pagesrelease.yml标签、从标签手动GoReleaser、原生 macOS 构建、macOS 嵌入式冒烟、发布 attestations/SBOM、Homebrew 公式更新、PyPI 构建/发布、npm 发布test-pypi.yml手动构建 MCP 包并发布到 TestPyPIupdate-flake-lock.yml每周、手动更新flake.lock、范围检查 diff、开 PRupdate-vendor-hash.yml针对go.mod/go.sum的 Dependabotpull_request_target更新default.nixvendor hash 并推送到 dependabot 分支九、差距分析审计揭示的七个问题P0-1缺少统一的 CI 契约没有任何单一权威来源定义 PR、main push、nightly 与 release 各自必须通过的检查工作流隐式编码了这一契约。后果是agent 与维护者不读多个工作流文件就无法回答合并前必须通过什么或哪个本地命令可复现这个状态检查。P0-2本地与 CI 的 Go 命令分叉本地文档推荐make test/scripts/test.shPR CI 却直接运行带-race、-short、-skip ^TestEmbedded的go test。后果scripts/test.sh的 skip/timeout/coverage/共享服务器行为不是 PR 契约make test无法忠实复现 PR CItesting.Short()边界属于 CI 行为但在本地测试文档中并不显眼。P1-1无 CGO 覆盖不完整CI 有一个聚焦的 CGO 禁用 cmd/bd 编译/运行任务但该子集之外的!cgo测试没有明显的完整 no-CGO./...任务。后果聚焦子集之外的 server-mode/no-CGO 回归可能逃出主 PR 门禁。P1-2集成测试覆盖碎片化部分 Docker 支撑的 Dolt 套件在 PR CI 运行宽泛的integration标签在 nightly 运行且明确跳过 Docker Dolt 测试多个慢路径被-short抑制。后果这也许是有意为之但契约未文档化——难以区分不值得占用 PR 时间与意外未被覆盖。P1-3发布门禁分散在多个工作流Regression、cross-version smoke、迁移保真、发布构建、PyPI、npm、Homebrew 发布是触发条件各异的独立工作流。后果tag 时验证存在但发布阻断顺序与重跑策略没有以单一发布门禁文档或工作流摘要呈现。P1-4非 Go 包测试不是 CI 门禁MCP Python 包、npm 包装层、网站各有本地测试或检查但当前工作流大多只构建或发布这些产物未在发布前或触及相应路径的 PR 上运行其完整本地验证。后果包特定回归可绕过包自身的测试直达发布/发布工作流。P2-1Windows 仅冒烟Windows CI 构建并运行version与help但不运行 Go 测试。后果Windows 特定的文件系统、路径、shell 与 CGO 行为依赖有限覆盖。这或许是合理的权衡但应成为显式层级并配备已知负责人与逃生阀。值得注意的是pr.yml 已出现若干聚焦的 Windows 任务如Test (Windows) cmd/bd liveness regression、Test (Windows) doltversion package、Worktree remove boundary (Windows)、Test (Windows) dbproxy server package说明仓库正以精准小任务而非全矩阵的方式补 Windows 覆盖。P2-2基准与性能回归检查仍靠手动基准测试与生产形态的复现工具已有文档但没有工作流捕获基准产物或运行带标签的性能检查。后果性能敏感变更依赖人类/agent 自律而非可重复的 CI 路径。P2-3现有文档存在漂移engdocs/TESTING.md声称包装脚本与 CI 一致但 PR CI 使用直接go testengdocs/LINTING.md声称 CI 可能不会因已知 lint 问题失败而工作流使用标准golangci-lintaction 且无显式非失败退出码更早的 staged 审计文档包含过时的测试计数。后果过时文档隐藏了实际契约削弱清理工作的效果。十、路线图从审计到可复现的分级 CIPhase 1命名层级将本审计转化为带显式层级的 CI 策略文档层级用途示例触发本地命令pr-core必需的快速 PR 信号每次 PR/main push待定义pr-risk风险路径的额外检查Go/storage/scripts/workflow 变更待定义nightly-full昂贵的宽泛扫描调度/手动待定义release-gate发布前必须通过标签/手动发布待定义package-gatesPython/npm/website 路径检查路径门控的 PR 与发布待定义perf-manual基准证据手动或标签待定义然后让每个状态检查名称包含其层级。配套文档 engdocs/CI_CLEANUP_PLAN.md 已给出更细的层级模型pr-core/pr-policy/pr-lint/pr-risk-*/main-*/measure-*/nightly-*/release-*并明确了包装约定scripts/ci/下的 shell 脚本是命令政策的单一事实来源Make 目标只是别名.test-skip不进入 CI它只是本地人工优化文件。Phase 2新增可复现的 CI 包装命令为每个层级添加仓库自有的包装脚本或 Make 目标例如make test-pr-core、make test-pr-risk、make test-nocgo、make test-integration-nightly、make test-release-gate。不要让 workflow YAML 成为命令政策唯一存在的地方。Phase 3让当前 PR CI 与包装器对齐层级命令就绪后让 PR/main 工作流调用这些命令。通过在同一底层命令外包裹 gotestsum/JUnit 输出等方式保留有用的 CI 专属行为而非维护另一套测试定义。Phase 4填补包特定缺口添加路径门控检查MCP 运行uv run ruff check、uv run mypy、uv run pytestnpm 包先npm ci再npm run test:all网站对触及website/**的 PR 运行npm ci、npm run typecheck、npm run build与内部链接检查插件在现有版本脚本之外验证清单 JSON 与版本一致性。Phase 5合理化昂贵覆盖决策并文档化哪些 integration 标签测试必须 PR 门控nightly 是否继续使用BEADS_TEST_SKIPdolt或 Docker 支撑的 Dolt 挂起是否已解决到足以拆分并重新启用哪些发布迁移路径必须阻断 tag 而非手动运行哪些 Windows 测试值得加入而不使矩阵不稳定。Phase 6增加 CI 可观测性为每个层级捕获足够产物以便免重跑调试失败Go 测试的 JUnit可行处、按层级的覆盖率产物、嵌入式分片的选中测试列表、包测试日志、以及链接 regression/cross-version/migration/publish 检查的发布门禁摘要。十一、立即可执行的下一步维护者就层级命名达成一致后将本审计压缩为更短的docs/CI.md策略按顶层测试名拆分cmd/bd的 no-short Linux 集成车道——首次包分片运行显示cmd/bd占据墙钟尾部重复测量确认加法式 PR 包装任务保留当前必需 PR 行为后将其提升为必需增加 no-CGO 全包编译/测试门禁或显式文档化为何聚焦的 cmd/bd 子集已足够在动主 Go 矩阵前先添加路径门控的 MCP、npm 包与网站检查在直接工作流命令被替换期间保持engdocs/TESTING.md与包装命令对齐。延伸阅读本审计的配套策略层文档是 engdocs/CI_CLEANUP_PLAN.md本地测试实践见 engdocs/TESTING.mdGo 测试入口见 scripts/test.sh构建标记见 .buildflags工作流定义见 .github/workflows/pr.yml、.github/workflows/pr-risk.yml、.github/workflows/main.yml、.github/workflows/nightly.yml、.github/workflows/regression.yml。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考