读懂 sentrux 质量信号：0 到 10000 分的 5 个根因指标（模块化、无环、深度、均衡、冗余）新手全解

读懂 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/sentruxsentrux 是一个实时架构传感器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 B0.81 AAgent 会围着边界卡分而不是真改进。连续分值下每 1 分都是等价的真实进步分数会在边际收益趋近于零时自然收敛——就像梯度下降。5 个根因指标逐个拆解① 模块化Modularity / Newmans 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 依赖 BB 又依赖 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 系数复杂度有没有集中成上帝函数衡量什么所有函数的圈复杂度分布有多平均。一个 CC200 的上帝函数 一堆 CC2 的小函数 → 基尼系数高集中所有函数 CC 都在 5–10 → 基尼系数低均衡。算法来源Gini 1912经济学里量财富不平等的系数这里量复杂度不平等。归一化score 1 - 基尼系数越平均分越高。为什么重要上帝文件/函数是 AI Agent 混乱的头号来源——当一个文件承载了 40% 的复杂度Agent 根本无法对它做有效推理。典型病症健康面板里的 GOD FILES、complex_functions 列表都是它在报警。⑤ 冗余Redundancy有多少代码是白写的衡量什么无用代码占总函数数的比例 无死调用点的死函数 函数体哈希完全相同的重复函数/ 总函数数。算法来源Kolmogorov 复杂度——实际代码与最小等价代码之间的差距。归一化score 1 - 冗余比例零浪费 满分。为什么是根因每一行死代码/重复代码都在扩大 AI Agent 的搜索空间却不贡献任何行为删掉它必然让代码库变好。典型病症Agent 反复发明了同一个工具函数散落在全库各处。一眼看懂5 个指标速查表指标度量对象理论来源原始值 → 归一化越低分代表……模块化边聚类Newman 2004Q ∈ [-0.5,1] → (Q0.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 处理器实现。新手常见疑问 FAQQ17342 分到底算好还是差没有及格线。分数是连续量价值在于趋势delta over time——同一项目今天 7342、明天 7410就是真实的改进。跨语言绝对值会有差异Swift 和 Java 的项目量纲不同但趋势可比。Q2为什么不用熵entropy来度量分布早期版本确实包含 Shannon 熵后来被砍掉了熵和基尼系数在同一维度上重复计量而且熵越高越好和热力学直觉相反容易误导。基尼系数更直观、对异常值更敏感一个维度保留一个指标即可详见 设计文档 的 Equality 一节。Q3它对不同语言公平吗公平。5 个指标都跑在依赖图上而非语法上——有 import 用 import 边Java/Go/Rustimport 隐式就用调用边SwiftNewmans Q 对任何图都成立。52 种语言通过 tree-sitter 插件接入plugins/主二进制里零语言知识。Q4AI 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），仅供参考