lambda-alpha-labs/Graphenium
GitHub: lambda-alpha-labs/Graphenium
一款面向 AI 编程代理的本地架构门禁工具，通过 AST 解析和 Datalog 策略引擎在代码变更落地前拦截架构边界违规。
Stars: 21 | Forks: 3
**Graphenium 是一个用于 AI 编程代理的本地、预检 linter 和外部架构门禁。**
它通过机械性地拦截违反模块边界、绕过服务层或引入架构漂移的代码变更，对 AI 助手（如 Claude Code、 Cursor、 Aider 和 Grok）强制执行结构合规性。
标准的开发者工具帮助代理查找文件。而 Graphenium 则旨在防止代理制造架构债务。
```
Without Graphenium (Vibe-Coding) With Graphenium (Containment)
-------------------------------- -----------------------------
Agent edits files blindly Agent validates design pre-flight
Agent ignores architectural layers Graphenium blocks direct boundary violations
Constraints decay in long chats External Datalog engine enforces strict rules
Reviewer hunts for bypassed layers Reviewer gets deterministic scope-creep audits
CI checks only test passing CI fails on architectural drift
```
二进制文件：`gm`
Schema：`0.2.0`
状态：AST + Stack Graphs 解析器已稳定，预检策略引擎已稳定，遥测覆盖层为实验性功能
## Graphenium 存在的意义：遏制缺口
AI 编程代理在局部修改方面效率极高，但它们存在**结构性盲目和上下文衰减**的问题。在长时间的聊天会话中，代理会忘记你的系统指令，并倾向于选择阻力最小的路径（例如，为了通过局部测试，直接在 HTTP controller 中编写原始的数据库调用）。
依赖像 `CLAUDE.md` 或系统 prompt 这样的“软性”防护栏来维护设计模式是行不通的。当上下文窗口爆满时，这些约束就会被丢弃。
Graphenium 建立了**外部工程治理**。它在 LLM 上下文之外运作，将架构边界视为严格的、已编译的契约。
```
graph TD
A[Agent Declares Design Spec] --> B[Graphenium Pre-Flight Check]
B -->|Violation: Block| C[Reject with structural hints]
B -->|Pass: Authorize| D[Agent Implements Code]
D --> E[Graphenium Post-Edit Audit]
E -->|Scope Creep| F[Fail Build / Block PR]
E -->|Compliant| G[Approve for human review]
```
## 核心技术生命周期：先设计后验证
Graphenium 对代理强制执行明确的三步编译器循环：
1. **声明意图（预检 Spec）：** 在修改任何代码之前，代理会将其计划的修改（类、方法和依赖项）注册到虚拟规划工作区中。
2. **传递性策略求解：** Graphenium 的引擎运行本地的 Datalog 求解器来分析提议的虚拟 AST。如果设计绕过了中间架构层或使用了被禁用的 symbol，Graphenium 将拦截该计划并提供结构性反馈。
3. **事后合规审计：** 在代理编写完代码后，Graphenium 会解析物理修改，确保代理没有触碰声明范围之外的文件，没有引入计划外的依赖项，并且确实实现了其声明的 spec。
## 快速开始
```
# 初始化 workspace
# 使用标准项目默认值生成 .grapheniumignore
gm init
# 构建本地 AST 和 Stack Graphs 索引（无需 LLM 密钥）
gm run . --no-semantic --no-viz
# 诊断 codebase 健康状况和 import resolution
gm doctor --graph graphenium-out/graph.json --resolution
# 分析结构邻域
gm query "authentication flow" --budget 2000
# 为 AI coding agents 启动 MCP server
gm serve --graph graphenium-out/graph.json --watch
```
## 安装说明
```
# 从本地 checkout
cargo install --locked --path .
# 或使用平台安装程序
curl -fsSL https://raw.githubusercontent.com/lambda-alpha-labs/Graphenium/main/install.sh | sh
```
*需要 Rust 1.81 或更高版本。Tree-sitter 语法会被编译并打包。*
## 核心技术能力
### 1. AST 验证的来源（事实与启发式）
大多数 AI 开发者工具使用 LLM 来猜测模块之间的依赖关系，这会导致幻觉。Graphenium 使用 Tree-sitter 和 Stack Graphs 建立了一个由编译器证明为真的索引。每个关系都带有明确的来源：
* `EXTRACTED` **（AST 证明）：** 由编译器支持的事实（import、类型继承、显式 call 签名）。
* `INFERRED` **（启发式）：** 强制代理去验证的语义线索。
* `AMBIGUOUS` **（冲突）：** 标识符冲突迫使代理停止并直接检查源文件。
### 2. Datalog 驱动的策略求解
静态 linter 可以检查直接的 import，但它们对多跳架构绕过视而不见。Graphenium 通过将你的代码库结构编译为逻辑事实并运行嵌入式 **Datalog 推理引擎**（`src/analyze/query.rs` & `stdlib.dl`）解决了这个问题。
它使用一阶逻辑和不动点迭代，在无限数量的依赖跳转中从数学上证明边界违规。
### 3. 声明式结构治理
在 commit 时或在 CI 中强制执行系统设计边界。你可以在仓库根目录的 `.graphenium/policy.json` 中声明规则：
```
{
"rules": [
{
"type": "forbidden_dependency",
"from_pattern": "src/controllers/**",
"to_pattern": "src/db/**",
"reason": "Controllers must use services, not access DB directly"
},
{
"type": "strict_layering",
"layers": [
"src/serve/**",
"src/analyze/**",
"src/extract/**",
"src/model/**"
],
"reason": "Respect tiered architecture: serve -> analyze -> extract -> model"
}
]
}
```
使用 `gm check --plan
--strict` 在 CI 中运行预检策略检查和事后合规审计。
## 语言支持
Graphenium 支持包含 Rust、 Python、 Go、 JavaScript、 TypeScript、 Java、 C、 C++ 和 C# 的混合代码库。
C# 项目通过解析 `.sln` 和 `.csproj` 获得了构建边界感知能力，使 Graphenium 能够将 assembly、namespace 和项目引用建模为结构边界。
## MCP 设置
将 Graphenium 直接集成到代理的执行循环中。对于从项目目录启动 MCP 的工具，请使用 `scripts/graphenium-mcp` 启动器（仅在缺少索引时重新构建，保持启动瞬间完成）。
```
install -m 755 scripts/graphenium-mcp ~/.local/bin/graphenium-mcp
```
### Claude Code
```
claude mcp add graphenium --scope user -- gm serve --graph /path/to/graphenium-out/graph.json --watch
```
### Grok
在 `~/.grok/config.toml` 中配置：
```
[mcp_servers.graphenium]
command = "/Users//.local/bin/graphenium-mcp"
args = []
enabled = true
```
### Cursor
添加到 `~/.cursor/mcp.json`：
```
{
"mcpServers": {
"graphenium": {
"command": "gm",
"args": ["serve", "--graph", "/path/to/graphenium-out/graph.json", "--watch"]
}
}
}
```
## 详细文档地图
| 文档 | 用途 |
|---|---|
| [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md) | 安装、初始代码库索引和 MCP 设置。 |
| [`docs/AI_SETUP.md`](docs/AI_SETUP.md) | 逐步的助手设置手册。 |
| [`docs/AGENT_WORKFLOWS.md`](docs/AGENT_WORKFLOWS.md) | 遏制工作流：预检、编辑中规划和验证。 |
| [`docs/CI_AND_GOVERNANCE.md`](docs/CI_AND_GOVERNANCE.md) | 在 CI pipeline 中强制执行架构策略。 |
| [`docs/COMMAND_REFERENCE.md`](docs/COMMAND_REFERENCE.md) | 完整的 CLI 语法和配置参数。 |
| [`docs/MCP_TOOLS.md`](docs/MCP_TOOLS.md) | MCP 客户端的行为规范。 |
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | 索引 pipeline、C# 项目引用和 Datalog 评估。 |
| [`docs/TRUST_MODEL.md`](docs/TRUST_MODEL.md) | AST 证明与启发式置信度的底层细节。 |
| [`docs/BENCHMARKING.md`](docs/BENCHMARKING.md) | 性能指标：延迟、token 预算和扩展限制。 |
| [`docs/COMPARISON.md`](docs/COMPARISON.md) | 为什么 Graphenium 不同于 grep、AST 工具和 GraphRAG。 |
| [`docs/HARNESS_ADAPTER.md`](docs/HARNESS_ADAPTER.md) | 将 Graphenium 的结构引擎作为库嵌入。 |
| [`docs/SECURITY.md`](docs/SECURITY.md) | 本地优先保证和机密排除规则。 |
## 联系与企业版
* Issue 和功能请求：[GitHub Issues](https://github.com/lambda-alpha-labs/Graphenium/issues)
* 安全报告：security@graphenium.dev
* 设计合作伙伴、企业试点和合作：hello@graphenium.dev
## 许可证
MIT。详见 [`docs/LICENSE.md`](docs/LICENSE.md)。标签：AI代码审查, AI编程助手, IPv6支持, SOC Prime, 云安全监控, 代码规范, 可视化界面, 开发工具, 架构治理, 通知系统, 静态分析