读懂 sentrux 质量信号：0 到 10000 分的 5 个根因指标（模块化、无环、深度、均衡、冗余）新手全解
【免费下载链接】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
sentrux 是一个实时架构传感器（Real-time Architectural Sensor），用纯 Rust 编写，专为 AI Agent 时代的代码库打造。它的核心产物是一个0–10000 的连续质量信号分（quality signal）——没有 A–F 等级，没有百分比，只有 5 个"根因指标"（模块化、无环、深度、均衡、冗余）的几何平均。这篇文章带你从零读懂这个分数是怎么算出来的，以及每个指标到底在度量什么。
为什么要用"根因指标"而不是 20 个代理指标？
新手最容易困惑的问题：为什么一个架构健康度要靠 5 个指标，而不是几十项检查？
sentrux 的设计哲学（详见 docs/quality-signal-design.md）回答得很干脆：
- 代理指标测的是"症状"——耦合率、死代码占比、函数长度……AI Agent 可以靠"表面功夫"刷高它们（加一堆假 import 提升内聚、把一切设为 public 消灭"死代码"），指标涨了，代码没变好。
- 根因指标测的是"结构本身"——它们只能靠真正的架构改进来提升，无法被"作弊"。
- 5 个指标恰好是完备的：把代码库看成一个有向图（文件是节点、依赖是边），图论 + 信息论告诉我们它恰好有 5 个相互独立的结构性性质——3 个关于边（模块化、无环、深度），2 个关于节点（均衡、冗余）。再加指标只会重复计量。
0 到 10000 分是怎么算出来的？
计算分四步，核心逻辑全部在 sentrux-core/src/metrics/root_causes.rs：
- 算 5 个原始值：Newman 模块化 Q、环路数量（Tarjan 强连通分量）、最长依赖链深度、复杂度基尼系数、冗余比例；
- 归一化到 [0, 1]：每项各自映射成"1 = 完美"的分值；
- 取几何平均：
质量信号 = (模块化 × 无环 × 深度 × 均衡 × 冗余)^(1/5)； - × 10000 展示：GUI 显示
Quality 7342这样的整数（见 health_display.rs 分数渲染），MCP 接口同样返回 0–10000 的整数给 AI Agent。
两个值得新手记住的设计点：
- 为什么是几何平均？这是纳什社会福利定理（1950）的结论：几何平均是唯一满足"帕累托最优 + 对称 + 独立"的聚合方式。实际效果是——刷高一项、砸烂另一项，总分不会涨。想提分就必须全面改进架构，这正是 AI Agent 反馈环想要逼出来的行为。
- 为什么不用 A–F 等级？等级制造人为边界（0.79 = B，0.81 = A），Agent 会围着边界"卡分"而不是真改进。连续分值下，每 +1 分都是等价的真实进步，分数会在边际收益趋近于零时自然收敛——就像梯度下降。
5 个根因指标逐个拆解
① 模块化（Modularity / Newman's Q）：模块间是否"该连的才连"
- 衡量什么：依赖图能否干净地拆成若干"内部紧密、外部松散"的簇。
- 算法来源：Newman 2004 社区发现。把模块内实际边数和"同样连接度下的随机图"对比，超出越多说明模块化越好。
- 关键判读：Q > 0.3 = 有明显模块化结构，Q > 0.6 = 结构优秀，Q ≤ 0 = 比随机图还乱。
- 归一化：
score = (Q + 0.5) / 1.5，把 [-0.5, 1] 线性拉到 [0, 1]。 - 为什么无法作弊：往里塞没用的边只会让图更像随机图、把 Q 拉低；只有真正的模块化重构才能提分。
- 代码位置：compute_modularity_q。它同时使用 import 边和调用边，所以即使像 Swift 这样隐式导入的语言也能公平度量。
🎯典型病症：god file（扇出超标的大杂烩文件）、跨模块依赖满天飞。
② 无环（Acyclicity）：依赖里有没有"死循环"
- 衡量什么：循环依赖（A 依赖 B，B 又依赖 A）的数量。
- 算法来源：Robert C. Martin 2003 的 ADP（无环依赖原则）+ Tarjan 1972 强连通分量算法数出 >1 成员的环。
- 归一化：
score = 1 / (1 + 环数)——0 个环 = 满分 10000；每多一个环，分数衰减。 - 为什么是"根因"：有环意味着两个模块无法被独立理解、独立构建、独立测试——这是结构上的不可能，不是风格偏好。
🎯典型病症：两个模块互相引用，构建顺序都定不下来。GUI 会直接在 CYCLES 区域列出具体是哪几个文件成环（draw_cycles）。
③ 深度（Depth）：依赖链条有多长
- 衡量什么：DAG 中最长的依赖链层数。
- 算法来源：Lakos 1996 的层级化（levelization）分层架构理论；实现是从入口点出发的最长路径 DFS。
- 归一化：
score = 1 / (1 + 深度 / 8)——深度 8 时恰好 0.5 分，深度越浅分越高。 - 为什么和模块化独立：一个图可以模块化满分，却同时存在一条 20 个模块首尾相接的依赖链——改底层时改动会层层传导，深度度量的正是这个"正交"维度。
🎯典型病症：改一个底层配置，要连带动 10 层。
④ 均衡（Equality / Gini 系数）：复杂度有没有集中成"上帝函数"
- 衡量什么：所有函数的圈复杂度分布有多平均。一个 CC=200 的上帝函数 + 一堆 CC=2 的小函数 → 基尼系数高（集中）；所有函数 CC 都在 5–10 → 基尼系数低（均衡）。
- 算法来源：Gini 1912，经济学里量财富不平等的系数，这里量复杂度不平等。
- 归一化：
score = 1 - 基尼系数，越平均分越高。 - 为什么重要：上帝文件/函数是 AI Agent 混乱的头号来源——当一个文件承载了 40% 的复杂度，Agent 根本无法对它做有效推理。
🎯典型病症：健康面板里的 GOD FILES、complex_functions 列表，都是它在报警。
⑤ 冗余（Redundancy）：有多少代码是"白写"的
- 衡量什么：无用代码占总函数数的比例 =（无死调用点的死函数 + 函数体哈希完全相同的重复函数）/ 总函数数。
- 算法来源：Kolmogorov 复杂度——实际代码与"最小等价代码"之间的差距。
- 归一化：
score = 1 - 冗余比例，零浪费 = 满分。 - 为什么是"根因"：每一行死代码/重复代码都在扩大 AI Agent 的搜索空间却不贡献任何行为，删掉它必然让代码库变好。
🎯典型病症：Agent 反复"发明"了同一个工具函数，散落在全库各处。
一眼看懂：5 个指标速查表
| 指标 | 度量对象 | 理论来源 | 原始值 → 归一化 | 越低分代表…… |
|---|---|---|---|---|
| 模块化 | 边（聚类） | Newman 2004 | Q ∈ [-0.5,1] → (Q+0.5)/1.5 | 模块边界模糊、依赖乱飞 |
| 无环 | 边（环） | Martin ADP + Tarjan SCC | 环数 → 1/(1+环数) | 存在循环依赖 |
| 深度 | 边（链长） | Lakos 1996 | 深度 → 1/(1+深度/8) | 依赖链条过长 |
| 均衡 | 节点（分布） | Gini 1912 | 基尼系数 → 1-G | 复杂度集中在上帝函数 |
| 冗余 | 节点（浪费） | Kolmogorov | 冗余比 → 1-R | 死代码/重复函数多 |
归一化与几何平均的完整实现见 compute_root_cause_scores，入口是 compute_health——它从扫描快照一次性产出整份健康报告。
拿到分数后怎么用？三步上手
第一步：安装并跑一次
# macOS brew install sentrux/tap/sentrux # Linux curl -fsSL https://raw.githubusercontent.com/sentrux/sentrux/main/install.sh | sh sentrux check . # CI 友好：通过退出码 0，失败退出码 1第二步：找到"瓶颈项"。几何平均的数学性质决定了：分数最低的那一项，就是对总分拖累最大的维度。比如Quality 6772，展开后若equality只有 4100，那就先拆分上帝函数，而不是去优化其他项。
第三步：接入 AI Agent，闭环反馈。通过 MCP 协议（9 个工具：scan、health、session_start、session_end、check_rules等），Agent 可以在会话开始时存基线、结束时对比分数，退化即报警：
Agent: session_start() → { "quality_signal": 7342 } ... Agent 写了 500 行代码 ... Agent: session_end() → { "pass": false, "signal_before": 7342, "signal_after": 6891, "summary": "Quality degraded during this session" }MCP 返回的root_causes会告诉你每一项的分值和原始值，diagnostics直接点名该修哪些文件、哪些函数——Agent 据此改进，重新扫描，分数上涨，循环往复，直到边际改进趋近于零自然收敛。这就是"传感器 → 信号 → 控制器 → 执行器"的完整控制回路（MCP 处理器实现）。
新手常见疑问 FAQ
Q1：7342 分到底算好还是差？没有"及格线"。分数是连续量，价值在于趋势（delta over time）——同一项目今天 7342、明天 7410，就是真实的改进。跨语言绝对值会有差异（Swift 和 Java 的项目量纲不同），但趋势可比。
Q2：为什么不用熵（entropy）来度量分布？早期版本确实包含 Shannon 熵，后来被砍掉了：熵和基尼系数在同一维度上重复计量，而且"熵越高越好"和热力学直觉相反，容易误导。基尼系数更直观、对异常值更敏感，一个维度保留一个指标即可（详见 设计文档 的 Equality 一节）。
Q3：它对不同语言公平吗？公平。5 个指标都跑在依赖图上而非语法上——有 import 用 import 边（Java/Go/Rust），import 隐式就用调用边（Swift），Newman's Q 对任何图都成立。52 种语言通过 tree-sitter 插件接入（plugins/），主二进制里零语言知识。
Q4：AI Agent 能"刷分"吗？理论上很难。5 项指标各自不可单独作弊，几何平均又惩罚"顾此失彼"。设计文档明确把ungameable（不可博弈）作为信号的一级要求：想提分，唯一路径就是真正改进架构。
总结
- sentrux 质量信号 =5 个根因指标的几何平均 × 10000：模块化、无环、深度、均衡、冗余；
- 每一项只测结构、不测症状，无法靠表面功夫刷分；
- 分数没有边界和等级，最低分项 = 最大改进空间，分数会自然收敛；
- 配合 MCP 接入 AI Agent 后，"扫描 → 分数 → 改进 → 重扫"的反馈环才真正闭合——这正是 AI Agent 能递归自我改进代码质量的前提。
想深挖理论细节（控制论基础、纳什聚合、跨语言公平性），完整设计见 docs/quality-signal-design.md。
【免费下载链接】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），仅供参考
