根因指标

1. 模块性（Newman’s Q）

理论：Newman 2004，图社区检测。

度量依赖图分解为独立聚类的程度。将实际模块内边密度与具有相同度序列的随机图进行比较。

Q = (1/m) × Σ [A_ij - k_out_i × k_in_j / m] × δ(c_i, c_j)

• 范围：[-0.5, 1.0]。Q > 0.3 = 显著的模块化结构。
• 不可刷分：添加无用的边会使图趋近随机分布，从而降低 Q。只有真正的模块化重构才能提升 Q。
• 语言公平：适用于任何图。同时使用导入边和调用边。
• 替代：耦合 + 内聚 + 上帝文件 + 热点（这些都是低 Q 的症状）。

2. 无环性

理论：Martin 2003，无环依赖原则。

度量循环依赖的缺失程度。循环使构建顺序不确定、变更传播不可预测、测试困难。

• 计算方式：Tarjan 的 SCC 算法统计包含多于 1 个成员的强连通分量。
• 归一化：score = 1 / (1 + cycle_count)——使用 sigmoid 函数，因为计数无上界。
• 本质：A 依赖 B，B 依赖 A——两者都无法被独立理解或测试。

3. 深度

理论：Lakos 1996，层次化与分层架构。

度量 DAG 中最长的依赖链。深链意味着底层的变更会逐层传播。

• 计算方式：从入口点出发的迭代最长路径 DFS。
• 归一化：score = 1 / (1 + depth / 8)——中点为 8（深度 8 = 分数 0.5）。
• 与 Q 独立：一个图可以具有完美的模块性，但仍然存在 20 个模块顺序依赖的链。

4. 均衡性（Gini 系数）

理论：Gini 1912，最初来自经济学（财富不均衡）。

度量复杂度在函数间的分布均匀程度。一个代码库中如果一个上帝函数的圈复杂度 CC=200，其余所有函数 CC=2，则 Gini 值高。如果所有函数 CC=5-10，则 Gini 值低。

Sort values ascending.
G = Σ (2i - n - 1) × x_i / (n × Σ x_i)

• 分数：1 - G（Gini 越低 = 均衡性越好 = 分数越高）。
• 重要性：上帝文件是 AI 代理混淆的第一大来源。当 40% 的复杂度集中在一个文件中时，代理无法有效推理。

5. 冗余度

理论：Kolmogorov 复杂度——实际代码与最小等价代码之间的差距。

综合死函数（未被任何调用点引用）和重复函数（函数体哈希相同）。

R = (dead_count + duplicate_count) / total_functions
score = 1 - R

• 本质：每一行死代码或重复代码都是结构性浪费——增加了 AI 代理的搜索空间，却对行为没有任何贡献。

为什么恰好是 5 个？

一个带有属性节点的有向图具有以下独立的结构属性：

维度	捕获的内容	属于
模块性	边的聚类	边
无环性	环形边	边
深度	边链长度	边
均衡性	节点属性集中度	节点
冗余度	多余的节点	节点

3 个边属性 + 2 个节点属性 = 总共 5 个。再增加更多要么重叠（熵与 Gini 重叠），要么度量静态分析之外的内容（运行时行为）。