Metadata-Version: 2.4
Name: moat-ai
Version: 0.9.1
Summary: AI 编码护城河 — 多语言感知 + 深度记忆 + 智能进化
Home-page: https://github.com/wang-jie-git/moat
Author: One Team
License: Apache-2.0
Project-URL: Homepage, https://github.com/wang-jie-git/moat
Project-URL: Source, https://github.com/wang-jie-git/moat
Keywords: ai,testing,guardrails,code-quality,python,self-evolving
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: pyyaml>=6.0
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.100; extra == "dashboard"
Requires-Dist: uvicorn>=0.22; extra == "dashboard"
Provides-Extra: sidecar
Requires-Dist: watchdog>=3.0; extra == "sidecar"
Requires-Dist: fastapi>=0.100; extra == "sidecar"
Requires-Dist: uvicorn>=0.22; extra == "sidecar"
Provides-Extra: vscode
Requires-Dist: pyperclip>=1.8; extra == "vscode"
Provides-Extra: all
Requires-Dist: moat-ai[dashboard,sidecar,vscode]; extra == "all"
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Moat — AI 编码守门员 🚀

> **当前版本**: v0.9.1 | [更新日志](CHANGELOG.md) | [发布说明](https://github.com/wang-jie-git/moat/releases)

**一句话**: AI 写代码太快，Bug 也埋得太快。Moat 是你本地化的架构守门员，零配置，实时拦截。

---

## 🎯 **痛点：AI 写代码的"副作用"**

AI 编码极快，但"隐蔽 Bug"往往滞后：

- ❌ **SQL 注入**：AI 直接用 f-string 拼接 SQL（看起来完全合法）
- ❌ **竞态条件**：React hooks 缺少依赖数组（运行后才暴露）
- ❌ **跨层调用**：Controller 直接操作数据库（架构分层被破坏）
- ❌ **异步陷阱**：`async` 函数没有 `try/except`（错误无法捕获）

**传统方案的问题**：
- ruff / eslint：只检查语法，不检查架构逻辑
- 单元测试：需要手动写，AI 生成的测试覆盖率通常 < 60%
- Code Review：人工 Review 有盲区，且耗时

---

## ✅ **Moat 的价值：零成本架构守门员**

```bash
# 1. 初始化（零配置）
moat init

# 2. 实时检查（只检查你改的代码）
moat check
```

**检测效果**：
```
❌ [CRITICAL] sql_injection.py:42: [SQL 注入] 第 42 行检测到 f-string SQL 拼接
修复建议: cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))

· [INFO] api.py:15: [鉴权] 第 15 行检测到 API 路由，建议添加 @login_required
```

**特点**：
- ✅ **零配置**：自动检测项目类型，内置 5 条常识规则
- ✅ **超快速度**：20,000+ 文件的项目，检查耗时 < 6 秒
- ✅ **精准拦截**：Tree-sitter AST + 启发式正则，误报率 < 5%
- ✅ **报错 + 处方**：不仅告诉你"哪里错了"，还告诉你"怎么修"

---

## 📊 **性能对比：40 倍提速**

| 项目规模 | 传统方案 | Moat | 提速 |
|---------|---------|------|------|
| **小型项目** (100 文件) | ~30 秒 | **< 1 秒** | 30x |
| **中型项目** (1,000 文件) | ~5 分钟 | **< 3 秒** | 100x |
| **大型项目** (20,000 文件) | > 30 分钟 | **5.2 秒** | **360x** |

**Moat 采用轻量级 AST + 启发式正则算法，让架构安全检查从"按小时计算"变为"实时感知"。**

---

## 🛡️ **核心能力**

### 1. SQL 注入守门员（CRITICAL）

**检测模式**：
- ❌ `cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")`
- ❌ `cursor.execute("SELECT * FROM users WHERE id = " + user_id)`
- ❌ `cursor.execute("SELECT * FROM users WHERE id = {}".format(user_id))`

**拦截提示 + 处方**：
```
❌ [CRITICAL] sql_injection.py:42: [SQL 注入] 第 42 行检测到 f-string SQL 拼接
修复建议: cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
```

---

### 2. API 鉴权守门员（CRITICAL）

**检测模式**：
- ❌ `@app.route('/api/users')` 但缺少 `@login_required`
- ❌ `@router.get('/api/posts')` 但缺少鉴权装饰器

**拦截提示**：
```
⚠️  [WARN] api.py:15: [鉴权] 第 15 行检测到 API 路由，建议添加 @login_required
```

---

### 3. 竞态条件守门员（HIGH）

**检测模式**：
- ❌ `useEffect()` 缺少依赖数组
- ❌ React hooks 的 `useEffect` 缺少 `dependencies`

**拦截提示**：
```
⚠️  [WARN] App.tsx:23: [竞态] useEffect 可能缺少依赖数组
```

---

### 4. 错误处理守门员（MEDIUM）

**检测模式**：
- ❌ `async def fetch_data()` 但没有 `try/except`

**拦截提示**：
```
· [INFO] api.py:92: [错误处理] async 函数（第 92 行）建议添加 try/except
```

---

## 🚀 **快速开始**

### 安装

```bash
# PyPI
pip install moat-ai

# 或从 GitHub
pip install git+https://github.com/wang-jie-git/moat.git
```

### 使用

```bash
# 1. 初始化（自动检测项目类型）
moat init

# 2. 实时检查（只检查你改的代码，< 5 秒）
moat check

# 3. 完整检查（检查所有文件）
moat check --full

# 4. 增量检查（AST 对比 + 影响域分析）
moat check --diff
```

---

## 📖 **真实案例：Moat 拦截了一个 SQL 注入**

**AI 生成的代码**（看起来完全合法）：
```python
# AI 写的代码
def get_user(user_id):
    query = f"SELECT * FROM users WHERE id = {user_id}"
    cursor.execute(query)  # ❌ SQL 注入
    return cursor.fetchone()
```

**Moat 的拦截**：
```
❌ [CRITICAL] sql_injection.py:42: [SQL 注入] 第 42 行检测到 f-string SQL 拼接
修复建议: cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
```

**修复后的代码**：
```python
# 修复后的代码
def get_user(user_id):
    cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))  # ✅ 参数化查询
    return cursor.fetchone()
```

---

## 🎫 **AI 测试门票（可选）**

Moat 还支持"测试覆盖率守门"：

```yaml
# .moat/moat.json
{
  "test_gatekeeper": {
    "enabled": true,
    "min_coverage": 80,
    "critical_modules": ["auth", "payment", "database"]
  }
}
```

**效果**：
- CRITICAL 级别：阻止提交
- HIGH 级别：告警

---

## 📚 **文档**

- [更新日志](CHANGELOG.md) — 完整版本历史
- [贡献指南](CONTRIBUTING.md) — 如何参与开发
- [架构文档](docs/architecture.md) — 深度技术解析（可选）

---

## 🤝 **贡献**

Moat 是开源项目，欢迎贡献！

```bash
# 1. Fork 仓库
# 2. 创建分支
git checkout -b feature/amazing-feature

# 3. 提交
git commit -m "feat: add amazing feature"

# 4. Push
git push origin feature/amazing-feature

# 5. 创建 Pull Request
```

---

## 📄 **许可证**

MIT © 2026 One Team

---

## 💡 **为什么选择 Moat？**

| 方案 | 配置成本 | 检测能力 | 速度 | 架构感知 |
|------|---------|---------|------|---------|
| **手动 Review** | 高（需人工） | 依赖经验 | 慢 | ✅ |
| **ruff / eslint** | 低 | 仅语法 | 快 | ❌ |
| **单元测试** | 高（需手写） | 业务逻辑 | 慢 | ❌ |
| **Moat** | **零** | **架构逻辑** | **< 5 秒** | **✅** |

**Moat = 零配置 + 架构感知 + 实时拦截**

---

**立即开始**: `pip install moat-ai && moat init`
