Beads 圈复杂度追踪体系：基于 gocyclo 的生产代码复杂度基线、diff 报告与增量护栏实战

Beads 圈复杂度追踪体系：基于 gocyclo 的生产代码复杂度基线、diff 报告与增量护栏实战

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads

本文是一份围绕 Beads 仓库中engdocs/COMPLEXITY_TRACKING.md展开的工程实践指南。Beads 是一个为编码 Agent 提供记忆增强的开源项目（Go 实现），其代码库横跨cmd/、internal/、backend/、issueops/等数十个包，其中不乏复杂度逼近甚至超过 70 的大型函数。为了在不打断日常开发节奏的前提下系统性地跟踪这一指标，仓库引入了基于 gocyclo v0.6.0 的圈复杂度（Cyclomatic Complexity）报告实验：通过明确的生产代码白名单、稳定的基线快照与按"包/函数/文件"键匹配的 diff 机制，把复杂度从一次性的静态审计，变成可持续观察、可增量约束的工程信号。读完本文，你将掌握：如何安装并运行该报告体系、如何解读 baseline 快照与 PR 增量报告、如何在本地用check模式对新增/回退的高复杂度函数进行护栏验证，以及该实验设计背后与仓库 CI 约定的契合点。

一、实验背景：为什么 Beads 要单独跟踪复杂度

Beads 的代码量相当可观：仓库根目录的 Go 文件与cmd/bd/、internal/、backend/、issueops/、schema/、format/等目录共同构成生产代码主体，其中 CLI 命令、存储适配、issue 工作流、同步引擎等模块天然包含大量分支逻辑。从engdocs/complexity-baseline.txt快照可以看到，当前被追踪的最复杂函数包括：

• main gatherUpdateInput（cmd/bd/update_input.go，复杂度 73）
• main gatherListInput（cmd/bd/list_input.go，复杂度 72）
• beads FindBeadsDir（internal/beads/beads.go，复杂度 66）
• tracker (*Engine).doPull（internal/tracker/engine.go，复杂度 64）
• sqlbuild BuildIssueFilterClauses（internal/storage/sqlbuild/filter.go，复杂度 58）

这些函数的高复杂度大多来自长参数列表、多分支的输入收集逻辑以及并发/同步的边界处理，属于"历史累积的复杂度"。对这种既有复杂度，直接设置一个强制的 CI 门禁会立刻卡死所有合入，既不现实也不公平。因此文档将这项实验定位为opt-in（自愿启用）的报告机制：先建立信号、建立基线，再逐步讨论是否提升为强制门禁。

二、分析器与报告脚本的安装与快速上手

1. 安装 gocyclo（一次性）

报告依赖github.com/fzipp/gocyclo，版本被脚本显式锁定为 v0.6.0（见 scripts/ci/complexity.sh 中的GOCYCLO_VERSION）：

go install github.com/fzipp/gocyclo/cmd/gocyclo@v0.6.0

脚本启动时会先检查gocyclo是否存在于 PATH，缺失时直接输出安装指引并退出（complexity.sh），对应测试 scripts/complexity_script_test.go 专门验证了这一"缺失工具时的明确报错"行为。

2. 四种运行模式与对应 Make 目标

脚本支持四种模式，文档给出命令，Makefile 则提供了三个封装目标（Makefile）：

报告输出按复杂度降序排列，默认只显示 Top 50（COMPLEXITY_TOP）。关于diff模式文档特别说明：它通过git archive提取 base ref 的代码快照后再扫描，并使用稳定的包/函数/文件键做对比，因此即使行号发生了移动，也不会被误判为"新函数"——这是文件级归因（file-level attribution），本质上是一个信号而非合并门禁（COMPLEXITY_TRACKING.md）。

3. 可覆盖的环境变量

以下变量可在命令行前临时设置，用于本地实验（complexity.sh）：

COMPLEXITY_THRESHOLD=30 # 报告门槛，必须为整数，脚本会做合法性校验 COMPLEXITY_TOP=50 # 报告显示的函数数量上限 COMPLEXITY_BASELINE=... # 基线文件路径，默认 engdocs/complexity-baseline.txt COMPLEXITY_BASE_REF=origin/main # diff 模式的对比基准 git ref COMPLEXITY_TOOL=gocyclo # 分析器可执行文件名，测试中用于注入 fake 分析器

三、生产代码白名单：分析输入范围是如何被显式锁定的

scripts/ci/complexity.sh的一个关键设计是显式 shipped-code 白名单。脚本的scan()函数（complexity.sh）只对以下输入运行分析器：

1. 仓库根目录下的所有*.go文件（顶层文件，如beads.go、claim.go、schema/schema.go等）；
2. 以下目录：cmd、internal、backend、beadserrors、format、issueops、journalops、memoryops、schema、plugins、integrations、release-gates。

同时，分析过程有两道排除防线：

• gocyclo 的-ignore正则：(_test\.go$|\.gen\.go$|generated|(^|/)conformance/)，在分析器层面排除测试文件、生成文件与backend/conformance/；
• 脚本内的 awk 二次过滤：再次按_test.go、.gen.go、generated、backend/conformance/前缀对分析结果做防御性剔除（complexity.sh）。

之所以"双保险"，是因为脚本还要支持向git archive出来的 base 快照目录注入 fake 分析器输出，第二次过滤可以兜住自定义/伪造分析器带来的脏数据（脚本注释明确说明了这一点）。

把范围做得如此明确，是为了防止fixtures、测试工具和其他非生产代码树悄悄改变信号：如果允许tools/、test/、tests/或backend/conformance/参与统计，那么一个仅修改测试夹具的 PR 也可能让"复杂度"数值跳动，污染对生产代码质量的判断（COMPLEXITY_TRACKING.md）。

对应的行为在 scripts/complexity_script_test.go 的TestComplexityScriptReportFiltersAndComparesBaseline中有完整验证：fixture 输出中低于阈值的main Small、测试文件里的main TestHelper、以及backend/conformance/check.go里的main Conformance都必须被过滤掉，而backend/live.go中的main Backend属于backend/白名单，必须保留在报告中。

四、基线快照：复杂度历史的"账本"

当前快照保存在 engdocs/complexity-baseline.txt，文件头部的两行注释说明了生成方式与门槛：

# Cyclomatic complexity baseline (generated by scripts/ci/complexity.sh update) # Threshold: 30 (only shipped production functions at or above it are tracked)

基线文件共记录 80 条函数记录（阈值 30 及以上），每条记录格式为：

复杂度 包名 函数签名 文件路径:起始行:列

例如：

73 main gatherUpdateInput cmd/bd/update_input.go:43:1 66 beads FindBeadsDir internal/beads/beads.go:757:1 64 tracker (*Engine).doPull internal/tracker/engine.go:324:1 58 sqlbuild BuildIssueFilterClauses internal/storage/sqlbuild/filter.go:64:1 51 main validateGraphApplyPlan cmd/bd/graph_apply.go:524:1 49 doltserver Start internal/doltserver/doltserver.go:1228:1 38 formula (*Formula).Validate internal/formula/types.go:564:1 37 config Initialize internal/config/config.go:56:1

基线的一个核心价值是**"按包、函数、文件对比，而不是按行号对比"**：check模式在读取基线时会把文件:行:列中的行号剥掉，仅以包 函数 文件三元组作为键（complexity.sh），因此无害的行号漂移不会制造"伪回归"。

五、report、diff与check三种模式的原理与判据

1. report：快照现状，永不失败

report只输出"当前阈值以上的函数列表 + 相对基线的增量摘要"，任何情况下都不会以非零状态退出（除非分析器缺失）。它同时附带一份"changed functions"清单，列出相对COMPLEXITY_BASE_REF有改动且属于白名单的 Go 文件中所包含的高复杂度函数（complexity.sh）。

2. diff：跨 ref 的四分类变化

diff模式（complexity.sh）对 base 快照以threshold 0进行全量扫描，再与当前代码（同样以 0 门槛扫描）做键匹配，最终输出四类变化：

• new:—— 当前达到阈值、base 中不存在的函数；
• regressed:—— 当前复杂度高于 base 的同键函数，附注(baseline N)；
• improved:—— 复杂度下降且 base 原本在阈值以上的函数；
• deleted:—— 从 base 中消失、且 base 值本身在阈值以上的函数。

以 threshold 0 扫描 base 的意义在于：一个原本 25 分、本轮涨到 31 分的函数，应该被判定为regressed（跨线回退），而不是无法归因的new。对应测试 scripts/complexity_script_test.go 验证了Crossing（25→31，regressed）、Gone（deleted）与Drop（58→10，improved）三类判定，同时确认低于阈值的Quiet不会被误报。

3. check：面向未来 CI 的本地护栏

check模式复用同样的键匹配逻辑，但对"新增被追踪函数"或"相对基线回退"两种情况返回退出码 1（complexity.sh）。注意两个限定：

• 它只对比本地基线文件，不依赖 git ref；
• 只有当基线文件不存在时，check才会立即失败并提示先运行update（complexity.sh）。

因此，check适合作为本地开发时的自检命令，或者在维护者就"哪些既有复杂度可接受、基线应以多快速度降低"达成共识之后，被提升为真正的 CI 强制检查（这正是文档所述的设计意图：COMPLEXITY_TRACKING.md）。目前报告目标与必需的 PR 检查是刻意分离的。

对应测试 scripts/complexity_script_test.go 验证了"基线 30、当前 31 时 check 必须失败且输出 regressed 解释"。

六、刷新基线：update 模式与版本管理注意事项

当一批重构落地、大量函数被拆分后，需要显式刷新基线快照：

./scripts/ci/complexity.sh update

update模式（complexity.sh）会重新运行扫描，把注释头与新的过滤结果整体覆写到基线文件，并打印写入的函数数量。由于基线文件被纳入版本控制（engdocs/complexity-baseline.txt），刷新动作本质上是一次有意的、需要 code review 的变更，这保证了"基线的降低"是团队决策的产物，而不是随机的状态漂移。

七、与 CI 工作流的衔接：PR 中的 advisory 报告作业

在仓库的 .github/workflows/pr.yml 中，complexity-report作业完整落地了"报告必跑、失败不阻塞"的 advisory 语义：

1. Set up Go与Install gocyclo两个步骤都设置了continue-on-error: true与超时上限，分析器安装失败不会拖垮作业；
2. Generate complexity report步骤以if: always()保证无论前置步骤成败都会执行，内部用set +e捕获脚本退出码，并将报告写入complexity-report.txt作为 CI artifact 上传；
3. 若报告不可用，Annotate unavailable complexity report步骤会通过::warning::输出一条警告注解，而不是报错。

对这条 CI 约定的约束同样有测试守护：scripts/ci_workflow_test.go 断言 complexity 作业必须使用COMPLEXITY_BASE_REF=origin/main运行complexity.sh diff、所有步骤均需 bounded/best-effort，且ci-gate绝不能依赖该 advisory 作业（ci-gate的Needs不得包含complexity-report）。这与文档"报告目标刻意与必需 PR 检查分离"的定位完全一致——测量先行，门禁留待未来。

八、本地实验建议与阅读入口

1. 首次体验：安装 gocyclo 后运行make ci-complexity，对照 engdocs/complexity-baseline.txt 观察当前 Top 50 高复杂度函数分布（cmd/bd/的输入收集函数与internal/storage/的过滤/事务函数是两大高发区）。
2. PR 增量自查：COMPLEXITY_BASE_REF=origin/main make ci-complexity-diff，重点看自己改动涉及的函数是否出现regressed。
3. 本地护栏实验：make ci-complexity-check，尝试向某个被追踪函数加一个分支再运行，观察其以退出码 1 失败并打印regressed行。
4. 深入源码：报告脚本主体见 scripts/ci/complexity.sh；脚本行为测试见 scripts/complexity_script_test.go；CI 作业定义见 .github/workflows/pr.yml；基线快照见 engdocs/complexity-baseline.txt；Make 封装见 Makefile。

需要说明的适用前提：该体系默认 gocyclo v0.6.0 已安装、仓库为 Go 模块且包含上述白名单目录；若本地缺少origin/mainref，diff的 base 对比会降级为仅输出全量报告并给出提示（complexity.sh），而report/check/update不受影响。这套"白名单 + 稳定键基线 + advisory 报告"的组合，为 Beads 在不引入强制门禁的前提下持续观察代码复杂度演化提供了可复制的工程模板。

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads