企业官网建设流程全解析

sentrux MCP九大工具API详解：scan、health、evolution、dsm、test_gaps完整参考手册

【免费下载链接】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 是一个纯 Rust 编写的实时架构传感器（Architectural Sensor），通过 MCP 协议把代码结构健康度直接喂给 AI Agent，帮助其形成"扫描 → 改进 → 复扫"的反馈闭环。本文详解 sentrux MCP 服务器的九大工具 API（scan、health、session_start、session_end、rescan、check_rules、evolution、dsm、test_gaps），并给出典型调用流程，方便你把架构传感器快速接入 Claude Code、Cursor 等 MCP 客户端。

一、sentrux MCP服务器是什么？

MCP（Model Context Protocol）服务器让 AI Agent 可以像调用本地函数一样调用分析工具。sentrux 通过sentrux --mcp命令启动服务器，从 stdin 读取 JSON-RPC 请求、向 stdout 返回结果，所有分析都在本地完成，零网络调用。

核心实现位于 sentrux-core/src/app/mcp_server/mod.rs：

• 工具注册：所有工具以ToolDef形式注册在 registry.rs，schema、handler、授权等级集中定义，单一注册点
• 统一调度：dispatch()统一处理许可证校验、缓存失效与执行，Agent 看到的每个工具返回结构一致
• 状态缓存：McpState缓存扫描快照、健康报告，避免重复扫描同一目录

接入方式只需在 MCP 客户端配置中加一段 JSON（见 claude-plugin/.mcp.json）：

{ "mcpServers": { "sentrux": { "command": "sentrux", "args": ["--mcp"] } } }

二、九大工具速览

💡 注意：源码中 evolution 工具实际注册名为git_stats（见 handlers_evo.rs），文档与 README 常以 evolution 称呼它。

三、基础工具：scan 与 rescan

scan：必须第一步调用

scan是唯一带必填参数的工具——传入项目目录的绝对路径。它触发全量扫描并返回：

• quality_signal：0–10000 的连续质量信号（几何均值，越大越好）
• files/lines/import_edges：规模与依赖边数

实现见 handlers.rs 的 scan_def()。所有后续工具都依赖scan写入的缓存状态，未扫描直接调用会收到 "No scan data. Call 'scan' first." 的提示。

rescan：轻量刷新

改完代码后不必重新scan，直接调rescan即可基于上次目录重新计算指标，返回新的quality_signal与文件数，适合在 Agent 迭代循环中高频使用。

四、health：一个分数，五大根因

health是 sentrux 的"真分数"工具：不返回一堆散落指标，而是给一个质量信号 + 瓶颈定位。返回结构：

• quality_signal：综合得分
• bottleneck：最弱根因（如modularity），告诉 Agent 该往哪使劲
• root_causes：modularity（模块化）、acyclicity（无环性）、depth（深度）、equality（均衡性）、redundancy（冗余）五项的得分与原始值
• total_import_edges/cross_module_edges：耦合规模

五项根因的设计细节可参考 docs/quality-signal-design.md。

五、会话治理：session_start / session_end

这是让 AI Agent 形成闭环的关键组合拳，工作流在 README.zh-CN.md 中有完整示例：

1. scan后调用session_start，把当前健康指标存为基线
2. Agent 自由写码
3. 调用session_end自动复扫并对比，返回pass、signal_before/after、signal_delta、coupling_change、cycles_change与violations

一句话总结结果："Quality degraded during this session"还是"Quality stable or improved"，Agent 据此决定是继续还是回头修复。

六、check_rules：把架构决策写成约束

在项目中放一个.sentrux/rules.toml，即可声明约束（最大环数、耦合等级上限、禁"上帝文件"、分层顺序、禁止的依赖边界等），check_rules会返回pass、rules_checked、violation_count及逐条违规详情（规则名、严重级别、涉及文件）。

免费版最多检查 3 条规则，超出部分会返回truncated提示；Pro 版无限制。CLI 等价命令为sentrux check .，适合放进 CI。

七、evolution（git_stats）：Git 历史风险画像

基于 git 历史分析，可选参数days控制回溯窗口（默认 90 天）。返回：

• commits_analyzed/files_with_churn：改动量
• single_author_ratio：单人作者占比 → 换算bus_factor_solo_files（巴士因子风险）
• coupling_pairs_found：变更耦合（总是一起改的文件对）
• hotspot_count：churn × 复杂度交叉得出的热点数

它是"原始数据而非分数"，适合回答"哪里又热又复杂、谁的知识在单点"。Pro 版额外返回top_hotspots文件级明细。

八、dsm：依赖矩阵一眼看出"倒挂"

dsm（Design Structure Matrix，设计结构矩阵）输出 NxN 依赖矩阵的统计视图，可选参数format（stats默认 /text输出 ASCII 矩阵）。核心字段：

• above_diagonal/below_diagonal：上三角边越多，说明"下层依赖上层"的倒挂越多
• interpretation：直接给出人话结论，如 "Clean layering: all dependencies flow downward"
• clusters/level_breaks：自然聚簇与分层断点

对应指标实现位于 sentrux-core/src/metrics/dsm/mod.rs。

九、test_gaps：零测试的高危文件

test_gaps交叉比对测试文件、import 图与复杂度，返回coverage_score、coverage_ratio、untested等汇总；Pro 版返回riskiest_untested（按风险排序的 Top-N，limit默认 20）与test_files_detail（每个测试文件实际覆盖了谁）。对 Agent 来说这是"下一步该补哪些测试"的直接答案。

十、典型调用顺序清单

scan(path) # 建立快照与质量信号 ↓ session_start() # 存档基线 ↓ （Agent 写码） session_end() # 复扫对比，检测退化 ↓ （如需深入定位） health / dsm / git_stats / test_gaps # 按 bottleneck 深挖 ↓ check_rules() # 校验架构约束，收尾

配套技能文件 claude-plugin/skills/scan/SKILL.md 中也内置了这套扫描→健康度→会话治理的推荐顺序，可直接供 Claude Code 参考。

写在最后

sentrux 的 MCP 九大工具遵循一个设计哲学：scan 建基线，health 给方向，会话工具管闭环，evolution / dsm / test_gaps 做深挖，check_rules 守边界。把sentrux --mcp接入你的 Agent，等于给 AI 装上了架构"传感器"——它不再只看到Modified src/foo.rs这样的流水账，而是真正知道每一次改动让质量信号涨了还是跌了。想从源码构建？克隆仓库后执行cargo build --release即可（仓库地址：https://gitcode.com/gh_mirrors/se/sentrux ）。

【免费下载链接】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