sentrux源码剖析二Quality Signal设计原理——Newmans Q、Tarjan SCC、Gini与几何平均的控制论闭环【免费下载链接】sentruxReal-time architectural sensor that helps AI agents close the feedback loop, enabling recursive self-improvement of code quality. Pure Rust.项目地址: https://gitcode.com/gh_mirrors/se/sentruxsentrux 是一款纯 Rust 编写的实时架构传感器它的核心使命是让 AI Agent 闭合反馈回路把代码库当作一张依赖图来度量输出一个 0–10000 的连续Quality Signal质量信号再把这个信号通过 MCP 协议喂给 AI Agent驱动它对代码架构做递归式自我改进。本文是源码剖析系列的第二篇我们深入 metrics 模块拆解 Newmans Q、Tarjan SCC、Gini 系数与几何平均这四个数学工具是如何协同起来构成一个不可作弊的控制论闭环的。完整设计思想记录在 docs/quality-signal-design.md 中。为什么传统的代码质量评分行不通先问一个反直觉的问题为什么不用 A–F 字母等级也不用 20 个代理指标sentrux 的设计文档给出了三个否定的答案传统做法致命缺陷字母等级A–F制造人为边界AI 会卡线优化0.79 和 0.81 被区别对待而不是真改进20 个代理指标耦合率、函数长度等度量的是症状而非根因AI 可以伪造 import、拆分函数来刷分只看测试套件测试验证的是行为输出对不对不验证结构组织好不好sentrux 的哲学来自控制论Wiener 1948、钱学森的工程控制论一个能收敛到真改进的反馈回路其信号必须满足四个性质——单调真改进信号必涨、平滑小变化只产生小变化、不可作弊刷信号刷系统、可观测静态数据即可算出。▲ sentrux 主界面实时 treemap 依赖边左侧面板即为下文详解的五维根因指标而根因指标的定义方式非常克制把代码库建模为一张有向图G (V, E)V 是文件带大小、复杂度属性E 是依赖import 边 call 边。图论与信论告诉我们这张图恰好只有5 个相互独立的结构性质——3 个边性质 2 个节点性质。这就是 Quality Signal 的全部原料。五个根因指标逐一拆解数学原理核心实现集中在 root_causes.rs下面按源码顺序讲解。1️⃣ 模块化 QNewmans Q依赖图有多抱团理论出处Newman 2004 的社区发现。Q 值衡量模块内部实际边的密度与相同度数序列的随机图做对比Q (1/m) × Σ [A_ij − k_out_i × k_in_j / m] × δ(c_i, c_j)实现见 compute_modularity_q。它的精妙之处在于三点有向图版本分别统计每个节点的出度 k_out 和入度 k_in模块划分零配置直接取文件的父目录作为模块module_of(path)无需手工标注双语料公平同时使用 import 边和 call 边去重合并。Swift 这类隐式模块作用域的语言即使 import 边为 0调用图依然能让 Q 值有意义。Q 0.3 视为显著模块化结构。为什么它不可作弊因为加一条无用的跨模块边只会让图更接近随机图反而拉低 Q——只有真正的模块化解耦才能提升它。归一化score (Q 0.5) / 1.5。2️⃣ 无环性Tarjan SCC 强连通分量计数理论出处Martin 2003 的 ADP无环依赖原则。A 依赖 B、B 又依赖 A意味着构建顺序未定义、变更传播不可预测——这是结构性不可能不是风格偏好。sentrux 用 Tarjan 强连通分量算法找出所有成员数 1的 SCC 作为环见 tarjan_sccs 迭代版实现。一个工程细节值得注意源码实现是迭代式DFS用显式dfs_stack模拟递归避免大型项目递归爆栈状态封装在 TarjanState 中。归一化用了 sigmoid 形式的score 1 / (1 cycle_count)——0 环即满分1 个环得 0.5环越多分数平滑衰减。3️⃣ 深度最长依赖链有多长理论出处Lakos 1996 的层级化架构。从入口点或 fan-in 0 的根节点出发用迭代版最长路径 DFS 求 DAG 中的最长依赖链见 compute_max_depth 与 longest_path_dfs。它和 Q 是正交的一个图可以模块化完美高 Q但仍有 20 个模块首尾相接的长链——底层的每次改动都要穿透所有层。归一化同样用 sigmoidscore 1 / (1 depth / 8)深度 8 对应 0.5 分是唯二的两个需要中点参数的指标。4️⃣ 均衡性Gini 系数复杂度是否集中在上帝函数理论出处Gini 1912经济学里的财富不平等度量被巧妙移植到代码。直觉当 40% 的复杂度集中在一个文件里时AI Agent 无法有效推理它。Gini 0 表示所有函数圈复杂度完全均等Gini → 1 表示一个上帝函数独吞一切。实现见 gini_coefficient对每个函数的圈复杂度排序后代入经典公式无函数级数据时自动降级为按文件行数计算保证任何项目都有值可算。归一化即直接取反score 1 − G。设计文档还解释了为何移除了香农熵熵度量的正是分布集中度与 Gini 双重计数同一维度而 Gini 对异常值更敏感、方向更直觉。5️⃣ 冗余度死代码 重复代码占比理论出处Kolmogorov 复杂度——实际代码与最小等价代码的差距。公式极简R (dead_count duplicate_count) / total_functions。死函数判定见 collect_dead_functions排除 public API、方法、测试与隐式入口点重复函数则用函数体哈希分组collect_duplicate_groups。每一行死代码/重复代码都是结构性的浪费只增大 AI 的搜索空间却不贡献任何行为。归一化score 1 − R。几何平均让指标刷分在数学上失效五维得分各自归一化到 [0, 1] 后如何聚合成一个数答案在 compute_root_cause_scoresquality_signal (modularity × acyclicity × depth × equality × redundancy)^(1/5)几何平均的选择不是拍脑袋而是Nash 社会福利定理1950的结论它是唯一同时满足以下三条的聚合函数——Pareto 最优所有维度都变好信号必变好对称性五个根因地位平等没有权重偏袒独立性无关维度不影响结果。工程意义非常直白把某一个指标刷到 1.0、同时把另一个拖垮几何平均不会涨。想让信号显著上升唯一的路是提升所有因子——这恰好把 AI Agent 逼向真正的架构改进堵死了刷分路线。最后一步是展示层信号被放大为0–10000 的整数Quality 7342配合像素块进度条与红→黄→绿连续渐变色渲染见 draw_quality_signal。没有字母等级、没有百分比、没有任何人为边界——每一分的提升都是实打实的进步。▲ 实况Claude Code 构建 FastAPI 项目质量分数 3121 与五维分解实时更新控制论闭环如何跑起来MCP 接口与收敛行为信号算出来后反馈回路就转起来了sentrux传感器→ quality_signal信号→ AI Agent控制器→ 代码变更执行器→ 代码库系统→ sentruxMCP 端health工具的实现见 handle_health它返回quality_signal、五个根因分数并自动用min_by找出得分最低的维度作为 bottleneck瓶颈——告诉 AI改进空间最大的地方在哪里Pro 版还会附带 diagnostics精确指出该修哪些文件和函数。由此产生的收敛行为与机器学习中的梯度下降神似第 1 轮signal 0.58 → 发现 equality 最低0.35→ 拆分 CC75 的上帝函数 → 0.63第 2 轮modularity 最低 → 提取共享接口、削减跨模块依赖 → 0.69第 3 轮redundancy 最低 → 删除 8 个死函数 → 0.74……边际收益递减……第 N 轮每次改动收益 0.005 →自然收敛注意没有考到 A 就停的人为停止点——收敛发生在边际改进趋近于零时这正是连续信号 几何平均设计的回报。设计文档把这套体系的理论家谱总结为一张表Wiener 控制论反馈架构、Nash 博弈几何平均最优性、Newman 图论Q、Tarjan1972环检测、Gini1912不平等度量、Lakos1996层级化、Lyapunov 稳定性1892反馈系统收敛保证。写在最后Quality Signal 不是一个拍脑袋的分数而是对 Kolmogorov 复杂度差距的最佳可计算近似分解为 5 个独立图论维度3 边 2 节点用 Nash 最优的几何平均聚合专为控制论反馈回路中的稳定收敛而设计。5 个指标中 3 个归一化零参数2 个 sigmoid 中点来自经验整体把可解释性做到了极致。如果你想继续深挖建议按这条源码路径走一遍compute_health总装入口→ root_causes.rs五维计算与聚合→ mcp_server/handlers.rs信号如何喂给 AI Agent。下一篇源码剖析我们来看它的演化分析evo与 What-if 模拟是如何构建的。【免费下载链接】sentruxReal-time architectural sensor that helps AI agents close the feedback loop, enabling recursive self-improvement of code quality. Pure Rust.项目地址: https://gitcode.com/gh_mirrors/se/sentrux创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考