sentrux/sentrux

Health: D dead code F (29%), cohesion D (23%) duplication C, comments D (2%)

Architecture: B levelization A, distance A blast radius B (22 files), attack surface A

Test Coverage: B (72%) 28 tested, 11 untested 6 test files, 39 source files

## 那个没人谈论的问题 您开始使用 Claude Code 或 Cursor 进行项目开发。第一天如同魔法。Agent 编写整洁的代码，理解您的意图，快速交付功能。 然后，有些东西变了。 Agent 开始臆造不存在的函数。它将新代码放在错误的位置。它在昨天触碰过的文件中引入 bug。您要求一个简单的功能，它却破坏了其他三样东西。您花在修复 agent 输出上的时间比亲自编写的时间还多。 每个人都认为是 AI 变笨了。**其实并没有。** 是您的代码库变糟了。 实际上发生了什么：当您使用 IDE 时，您能看到文件树。您打开文件。您在脑海中构建了架构模型 —— 哪个模块负责什么，它们如何连接，事物归属于何处。您是掌舵者。每一次编辑都通过了您对整体的理解。 然后 AI agent 将我们转移到了终端。Agent 在每次会话中修改数十个文件。您看到一连串的 `Modified src/foo.rs` —— 但您失去了空间感知能力。您看不到那个文件在依赖图中的位置。您看不到它刚刚创建了一个循环。您看不到现在有三个模块依赖于一个本应是内部的文件。许多开发者让 AI agent 构建整个应用程序，却从未打开过文件浏览器。 **您已经失去了控制。而您甚至还没意识到。** 每一次 AI 会话都在悄然降解您的架构。相同的函数名，不同的用途，散落在各处。不相关的代码堆在同一个文件夹里。依赖关系纠缠成一团乱麻。当 agent 搜索您的项目时，它找到二十个冲突的匹配项 —— 然后选错了那个。每次会话都让混乱更甚。每次混乱都让下一次会话更难。 这就是 AI 辅助开发不可告人的秘密：**AI 生成代码的能力越强，您的代码库变得越难以驾驭。** 传统的答案 —— *"先规划架构，再让 AI 实现"* —— 听起来没错，但没抓到重点。像 GitHub 的 [Spec Kit](https://github.com/github/spec-kit) 这样的工具尝试了这种方法：在编写代码之前生成详细的规格和计划。但在实践中，它[重造了瀑布流](https://blog.scottlogic.com/2025/11/26/putting-spec-kit-through-its-paces-radical-idea-or-reinvented-waterfall.html) —— 制造了如海的 markdown 文档，却对实际产出的代码毫无可见性。没有反馈回路。无法检测实现是否偏离了规格。没有任何形式的结构分析。规格进去，代码写出来，没人检查产出了什么。 反正这也不是任何人实际使用 AI agent 的方式。您快速原型设计。您通过对话迭代。您跟随灵感。您让创造心流驱动代码。这种创造心流正是 AI agent 强大的原因。也正是它摧毁代码库的原因。 **您不需要更好的计划。您需要更好的传感器。** ## 解决方案 **sentrux 是那个缺失的反馈回路。** 每一个能规模化运行的系统都有一个：一个观测现实的传感器，一个定义“好”的规格，和一个修正偏差的执行器。编译器闭合了关于语法的反馈回路。测试套件闭合了关于行为的回路。Linter 闭合了关于风格的回路。 但是架构 —— 这个改动适合系统吗？这个抽象会随着代码库增长引发问题吗？—— 没有传感器，也没有执行器。只有人类能判断。而人类跟不上机器速度的代码生成。 **sentrux 在架构层面闭合了回路。** 它实时监视您的代码库 —— 不是 diff，不是终端输出 —— 而是*实际的结构*。每一个文件。每一个依赖。每一个架构关系。可视化为一个随着 agent 编写代码而实时更新的交互式树状图。 14 个健康维度。从 A 到 F 评级。毫秒级计算。 当架构退化时，您能立即看到 —— 而不是等到两周后一切崩坏却没人记得是哪次会话导致的时候。 sentrux 给您传感器。您的规则给您规格。Agent 是执行器。**回路闭合。**

## 安装 **第一步 —— 安装二进制文件** ``` brew install sentrux/tap/sentrux ``` 或者 ``` curl -fsSL https://raw.githubusercontent.com/sentrux/sentrux/main/install.sh | sh ``` 纯 Rust 编写。单一二进制文件。无运行时依赖。通过 tree-sitter 插件支持 23 种语言。 **第二步 —— 运行** ``` sentrux # open the GUI — live treemap of your project sentrux /path/to/project # open GUI scanning a specific directory sentrux check . # check rules (CI-friendly, exits 0 or 1) sentrux gate --save . # save baseline before agent session sentrux gate . # compare after — catches degradation ``` **第三步 —— 连接到您的 AI agent（可选）** 通过 [MCP](https://modelcontextprotocol.io) 让您的 agent 实时访问结构健康状况。 Claude Code: ``` /plugin marketplace add sentrux/sentrux /plugin install sentrux ``` Cursor / Windsurf / OpenCode / OpenClaw / 任何 MCP 客户端 —— 添加到您的 MCP 配置中： ``` { "mcpServers": { "sentrux": { "command": "sentrux", "args": ["--mcp"] } } } ``` **从源码构建 / 升级 / 故障排除** ``` # 从源码构建 git clone https://github.com/sentrux/sentrux.git cd sentrux && cargo build --release # 升级 brew update && brew upgrade sentrux # 或者重新运行 curl install — 它总是拉取最新的 release ``` **Linux GPU 问题？** 如果应用无法启动，sentrux 会自动尝试多种 GPU 后端（Vulkan → GL → fallback）。您也可以强制指定一个： ``` WGPU_BACKEND=vulkan sentrux # force Vulkan WGPU_BACKEND=gl sentrux # force OpenGL ``` ## MCP server **Agent 工作流** ``` Agent: scan("/Users/me/myproject") → { structure_grade: "B", architecture_grade: "B", files: 139 } Agent: session_start() → { status: "Baseline saved", grade: "B" } ... agent writes 500 lines of code ... Agent: session_end() → { pass: false, grade_before: "B", grade_after: "C", summary: "Architecture degraded during this session" } ``` 15 个工具：`scan` · `health` · `architecture` · `coupling` · `cycles` · `hottest` · `evolution` · `dsm` · `test_gaps` · `check_rules` · `session_start` · `session_end` · `rescan` · `blast_radius` · `level` ## 规则引擎 定义架构约束。在 CI 中执行。让 agent 知晓边界。 **示例 `.sentrux/rules.toml`** ``` [constraints] max_cycles = 0 max_coupling = "B" max_cc = 25 no_god_files = true [[layers]] name = "core" paths = ["src/core/*"] order = 0 [[layers]] name = "app" paths = ["src/app/*"] order = 2 [[boundaries]] from = "src/app/*" to = "src/core/internal/*" reason = "App must not depend on core internals" ``` ``` sentrux check . # ✓ 所有 rules 通过 — Structure: B Architecture: B ``` ## 支持的语言 通过 [tree-sitter](https://tree-sitter.github.io/) 插件内置支持 23 种语言： Rust · Python · JavaScript · TypeScript · Go · C · C++ · Java · Ruby · C# · PHP · Bash · HTML · CSS · SCSS · Swift · Lua · Scala · Elixir · Haskell · Zig · R · GDScript **插件系统** —— 添加社区支持的任何语言，或创建您自己的： ``` sentrux plugin list # see installed plugins sentrux plugin add # install a community plugin sentrux plugin init my-lang # scaffold a new language plugin ``` 插件使用带有简单查询文件的 tree-sitter 语法 —— 与 Neovim/Helix 相同的方法。 缺少某种语言？[提出 issue](https://github.com/sentrux/sentrux/issues) 或提交插件 PR。 ## 哲学 **人类的角色正在改变 —— 从编写代码转变为治理代码。** 在 AI 之前所有重要的工程实践 —— 文档、测试、成文的架构、快速反馈回路 —— 现在的重要性呈指数级增长。跳过测试，反馈回路就无法闭合。跳过架构约束，漂移就会以机器速度复合。这里有个陷阱：如果 agent 不知道“整洁”长什么样，您就无法用 agent 来清理混乱。 sentrux 建立于三个信念之上： **1. Human-in-the-loop 不可妥协。** AI agent 强大但有限。它们无法同时把握大局和细节。人类必须能够随时看到 agent 对整体在做什么 —— 不仅仅是它触碰了哪个文件，而是那个文件对架构意味着什么。sentrux 让这成为可能。 **2. 验证比生成更有价值。** 生成一个正确的解法比验证一个更难（P vs NP 背后的直觉）。您不需要在编码上胜过机器。您需要在评估上胜过它 —— 指定“正确”长什么样，识别输出何时偏离，判断方向是否正确。sentrux 将架构判断转化为机器可读的评级和约束。 **3. 好的系统让好的结果不可避免。** 设计良好的系统约束行为，使正确的事情成为容易的事情。在衰退发布之前将其阻断的质量门禁。编码您的架构决策的规则引擎。让结构腐朽无法被忽视的可视化地图。实践没有改变。忽视它们的代价已变得无法承受。 *一旦您有了一个有效的反馈回路，您就不会再回去手动做了。不是因为您不能。是因为不再有意义。*

_{AI agent 以机器速度编写代码。如果没有结构化治理，代码库也会以机器速度衰退。
sentrux 就是那个治理者。}

[MIT License](LICENSE)

标签：AI代码生成, Anchore, AV绕过, Claude, CVE检测, FastAPI, LLM开发工具, MCP集成, Python安全, Rust, 云安全监控, 代码健康度, 代码审查, 代码质量评分, 可视化界面, 威胁情报, 开发者工具, 技术债务, 架构可视化, 测试覆盖率, 网络流量审计, 软件架构, 通知系统, 静态分析