# 🛡️ Blind Auditor - MCP 服务器
"编程 -> 审计 -> 修复 -> 再次审计 -> 通过."
Blind Auditor 是一个基于 MCP (Model Context Protocol) 协议构建的**强制性代码审计系统**。它通过独创的**"思维隔离" (Thinking Isolation)** 机制，强制 AI 智能体 (Agent) 在输出最终代码前，必须先进入一个独立的"审计时空"进行自我审查。
## 🧠 核心理念：思维隔离
传统的 AI 编码往往是"生成即输出"，错误和偏见容易被带入。Blind Auditor 引入了一个中间层：
1. **拦截 (Intercept)**: 当智能体想要输出代码时，必须先提交给 Blind Auditor。
2. **隔离 (Isolate)**: Blind Auditor 并不直接返回结果，而是注入一段**强制性系统指令**，迫使智能体暂停当前人格，切换为"冷面审计员" (Ruthless Auditor)。
3. **审查 (Audit)**: 在这个隔离的上下文中，智能体必须根据预设的 `rules.json` 对刚才生成的代码进行逐行扫描。
4. **放行 (Release)**: 只有当审计评分达标（默认 > 80分）且无严重 (Critical) 问题时，代码才会被解锁并返回给用户。
## 🎯 核心特性
- **🛡️ 零信任架构**: 默认不信任智能体生成的初稿，必须经过审计。
- **💰 零额外成本**: 复用宿主 IDE 的当前会话模型，无需额外的 API Key。
- **⚖️ 去偏见机制**: 通过提示词 (Prompt) 注入强制切换视角，打破生成的惯性思维。
- **📏 强合规植入**: 将团队代码规范（`rules.json`）硬性植入生成流程，比单纯的提示词更有效。
- **🔄 自动修复闭环**: 审计失败时自动触发"修复-重提交"循环，直到合规或达到最大重试次数。
---
## 🚀 快速开始
### 1. 环境准备
本项目需要 Python 3.10+ 和 [uv](https://docs.astral.sh/uv/)。
```bash
# 安装 uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh
# 进入项目目录
cd blind-auditor
# 安装依赖（自动创建虚拟环境）
uv sync
```
### 2. 配置审计规则 (`rules.json`)
在项目根目录创建或编辑 `rules.json`。这是审计员的"法典"。
```json
{
"project_name": "MyCoreProject",
"strict_mode": true,
"max_retries": 3,
"rules": [
{
"id": "SEC-001",
"severity": "CRITICAL",
"description": "严禁在代码中硬编码任何 API Key、密码或敏感 Token。",
"weight": 50
},
{
"id": "PERF-001",
"severity": "WARNING",
"description": "避免在循环中进行数据库查询或 IO 操作。",
"weight": 15
},
{
"id": "STYLE-001",
"severity": "PREFERENCE",
"description": "使用 snake_case 命名变量。",
"weight": 5
}
]
}
```
**配置字段说明**:
- `severity` (严重程度):
- `CRITICAL`: 致命错误。只要发现一个，审计直接不通过 (Fail)。扣分通常很高。
- `WARNING`: 警告。扣分中等，积累多了会导致不通过。
- `PREFERENCE`: 风格偏好。扣分较少。
- `weight` (权重): 该规则违规时的扣分值（总分 100 分）。
### 3. 配置 IDE (Antigravity / Cursor / Windsurf)
#### 步骤 A: 添加系统提示词 (关键)
为了让智能体知道必须使用此工具，请在 `.cursorrules` 或 IDE 的系统提示词 (System Prompt) 设置中添加以下指令：
```markdown
# Blind Auditor Protocol
**CRITICAL INSTRUCTION**:
You are integrated with the **Blind Auditor MCP**.
Whenever you generate code for a user request, you **MUST NOT** output the code block directly to the user.
**Execution Protocol**:
1. **Draft**: Generate the code internally in your thought process.
2. **Submit**: Call the `submit_draft` tool with your code and language.
3. **Obey**: The tool will return a strict "Audit Instruction". You MUST follow it exactly to audit your own code.
4. **Finalize**: Only when the tool returns "✅ AUDIT PASSED" can you display the final code to the user.
**Prohibited**:
- Do NOT output code blocks before passing the audit.
- Do NOT skip the audit step for "simple" changes.
```
#### 步骤 B: 配置 MCP 服务器
在您的 MCP 客户端配置文件 (如 `claude_desktop_config.json` 或 IDE 设置) 中添加：
**注意**：请将 `/path/to/your/blind-auditor` 替换为您克隆此仓库的实际绝对路径。
```json
{
"mcpServers": {
"blind-auditor": {
"command": "uv",
"args": ["run", "--directory", "/path/to/your/blind-auditor", "blind-auditor"]
}
}
}
```
---
## 🔧 工具详解
### 1. `submit_draft` (提交草稿)
提交代码草稿。
- **输入**: `code` (代码内容), `language` (语言)
- **行为**: 锁定会话，返回强制审计指令。
### 2. `submit_audit_result` (提交审计结果)
提交您的审计结论。
- **输入**:
- `passed` (bool): 您认为是否通过。
- `issues` (list): 发现的问题列表。
- `score` (int): 0-100 的评分。
- **行为**:
- 如果 `score < 80`，强制标记为 `passed=False`。
- 如果通过，解锁代码。
- 如果失败，增加重试计数，要求智能体修复后再次提交。
### 3. `reset_session` (重置会话)
重置状态，清除重试计数。
---
## 🔁 工作流图解
```mermaid
graph TD
User["用户请求"] --> Agent
Agent["智能体生成草稿"] -->|1. submit_draft| MCP
MCP -->|2. 注入审计指令| Agent
subgraph Isolation ["Thinking Isolation (思维隔离层)"]
Agent -->|3. 自我审查| Agent
Agent -->|4. submit_audit_result| MCP
end
MCP -->|5. 判定结果| Decision{"通过?"}
Decision -->|否 - 发现问题| Retry["重试计数 +1"]
Retry -->|未超限| Fix["智能体修复代码"]
Fix -->|再次提交| Agent
Decision -->|是 - 评分 >= 80| Final["✅ 输出最终代码"]
Retry -->|已超限| Force["⚠️ 强制输出 - 带警告"]
```
## ❓ 常见问题排查 (Troubleshooting)
**Q: 智能体总是直接输出代码，不调用工具怎么办？**
A: 请检查系统提示词 (System Prompt) 是否配置正确。必须明确告诉智能体"禁止直接输出代码"。你也可以在对话中手动提醒："请先通过 Blind Auditor 审计"。
**Q: 为什么即使我给代码打了 100 分，还是显示失败？**
A: 检查 `rules.json` 中是否有 `CRITICAL` 级别的规则被触发（虽然逻辑上智能体应该扣分，但有时智能体会由着性子来）。目前的逻辑主要依赖智能体传入的 `score`，但如果 `passed` 传了 `True` 而 `score < 80`，系统会强制驳回。
**Q: 支持哪些编程语言？**
A: 理论上支持所有语言。Blind Auditor 本身不解析代码语法，而是依赖智能体的理解能力去匹配 `rules.json` 中的描述。
---
## 🛠️ 开发指南
```bash
# 运行服务器
uv run blind-auditor
# 或直接使用 Python 模块运行
uv run python -m src.main
# 调试模式 (输出到 stderr)
# 可以在 src/main.py 中查看 print 语句
```
## 📄 许可证
MIT License
