内容
# 漂移卫士
[](https://github.com/漂移卫士/driftguard/actions/workflows/ci.yml)
**在集成破坏之前捕获API和模式更改。**
> **开始托管试用（无需信用卡）：** [**driftguard.org/start**](https://driftguard.org/start?utm_source=github&utm_medium=readme&utm_campaign=dg-readme-trial) — 完整专业版在一个端点，约2分钟。
> **10分钟MCP漂移实验室：** [Dev.to教程](https://dev.to/kioiek/catch-mcp-tool-schema-drift-in-10-minutes-live-demo-optional-watch-4ao2?utm_source=github&utm_medium=readme&utm_campaign=dg-readme-tutorial) · [ToolSchema工具包](https://github.com/kioie/toolschema-kit)
漂移卫士比较本地JSON合约（免费CLI和MCP客户端）并在需要时运行定时检查，当您需要始终在线的 **API合约监控** 和 **合约可观察性** 时，在 **[托管专业版/团队](https://driftguard.org/pricing)** 上使用。
使用 **模式漂移CI** （`compare_json`，GitHub Actions）在合并之前；在使用 **MCP工具目录漂移** 检测生产环境时使用托管监视。
> **非完全自主托管：** 此仓库是客户端层（差异+ MCP连接器）。监控管道是托管服务 - 请参阅 [OPEN_CORE.md](OPEN_CORE.md)。
### 不要混淆
许多项目共享名称 **漂移卫士**。此仓库（[漂移卫士/driftguard](https://github.com/漂移卫士/driftguard)）是 **API和MCP模式漂移** 监控 - 规范产品： [driftguard.org](https://driftguard.org).
- **[npm `driftguard`](https://www.npmjs.com/package/driftguard)** — UI linter（sjamcox），不是模式漂移。
- **[npm `driftguard-mcp`](https://www.npmjs.com/package/driftguard-mcp)** — 会话漂移MCP（jschoemaker），不是合约监控。
- **[getdriftguard](https://www.npmjs.com/package/driftguard-cli)** — npm用户`driftguard`下的API模式CLI；不同供应商和范围。
- **GitHub组织/ ML库** — 各种`driftguard`仓库（GitOps，Python ML等）；在集成之前请验证`漂移卫士/driftguard`或driftguard.org。
有关`@漂移卫士`作用域的npm发布路径，请参阅 [docs/DISCOVERY.md](docs/DISCOVERY.md) 和 [docs/npm-org-chase.md](docs/npm-org-chase.md)。
---
## 为什么选择此仓库？
| | **此仓库（OSS客户端）** | **托管漂移卫士** |
|---|---|---|
| **目标** | 本地测试，集成代理 | 生产环境监控 |
| **差异JSON模式** | ✅ CLI + MCP | ✅ + 历史记录 |
| **解析mcp.json预览** | ✅ 离线 | ✅ + 自动导入 |
| **连续检查** | ❌ | ✅ cron + 队列 |
| **MCP工具/列表轮询** | ❌ | ✅ |
| **警报和控制台** | ❌ | ✅ |
使用OSS客户端进行 **尝试和集成**。当需要 **始终在线的监控** 时升级。
**CI:** 单文件启动器 - [examples/workflows/driftguard-starter.yml](examples/workflows/driftguard-starter.yml) · GitLab - [docs/GITLAB_CI.md](docs/GITLAB_CI.md) · GitHub Marketplace路径 - [docs/GITHUB_MARKETPLACE.md](docs/GITHUB_MARKETPLACE.md)
---
## 快速入门
```bash
npx @漂移卫士/driftguard@latest version
npx @漂移卫士/driftguard@latest diff '{"id":1,"email":"a@b.com"}' '{"id":1}'
# 如果存在破坏性更改，则退出1
```
在npm上的`@漂移卫士`可用之前，请克隆并构建 - 请参阅 [docs/QUICKSTART.md](docs/QUICKSTART.md#1-install)。
### CLI
与上述相同的命令；从本地克隆使用`npm run check -- diff …`在`npm run build`之后。
### MCP服务器（Cursor，Claude，Windsurf）
请参阅 [docs/QUICKSTART.md](docs/QUICKSTART.md)， [examples/mcp-client-config.json](examples/mcp-client-config.json)和 [examples/AGENTS-snippet.md](examples/AGENTS-snippet.md)以获取消费者仓库。
**从本地克隆** （在`npm run build`之后）：
```json
{
"mcpServers": {
"driftguard": {
"command": "node",
"args": ["/absolute/path/to/driftguard/dist/mcp/server.js"]
}
}
}
```
**或通过npx** （无需克隆 - 从 [examples/mcp-client-config.json](examples/mcp-client-config.json) 复制）：
```json
{
"mcpServers": {
"driftguard": {
"command": "npx",
"args": ["-y", "@漂移卫士/driftguard@0.3.3", "mcp"]
}
}
}
```
在`env`下为监控工具添加`"DRIFTGUARD_API_KEY": "dg_…"`.
---
## MCP工具
| 工具 | API密钥 | 目的 |
|------|---------|---------|
| `compare_json` | 无 | 本地前后JSON模式差异 |
| `parse_mcp_config` | 无 | 从mcp.json预览监视URL（无创建） |
| `hosted_info` | 无 | 离线与托管矩阵，试用/定价链接 |
| `explain_drift` | 无 | 破坏性更改的修复提示 |
| `register_watch` | **专业版** | 持续监控 |
| `check_watch` | **专业版** | 立即检查 |
| `list_watches` | **专业版** | 列出监视 |
| `list_drift_events` | **专业版** | 漂移历史记录 |
| `suggest_watches` | **专业版** | 导入mcp.json + 可选创建 |
| `assert_coverage` | **专业版** | CI门控 - 依赖项必须被监视 |
**代理：** 阅读 [SYSTEM_PROMPT.md](SYSTEM_PROMPT.md) 以获取何时使用的指南。
---
## CI集成
固定客户端版本并遵循 **钩子 → 预览 → 试用 → 门控** 的流程：
```yaml
# 1. 钩子（免费）
- uses: 漂移卫士/driftguard/.github/actions/drift-diff@v0.3.3
with:
before: '{"id":1}'
after: '{"id":1,"name":"x"}'
# 2. 预览（免费 - 链接到控制台，非阻塞）
- uses: 漂移卫士/driftguard/.github/actions/drift-coverage-preview@v0.3.3
with:
files-json: '[{"path":"mcp.json","content":"..."}]'
# 3. 门控（专业版API密钥 - 阻止直到所有依赖项被监视）
- uses: 漂移卫士/driftguard/.github/actions/drift-coverage@v0.3.3
with:
api-key: ${{ secrets.DRIFTGUARD_API_KEY }}
files-json: '...'
```
完整模型： [docs/CI.md](docs/CI.md)
---
1. **尝试离线** - `compare_json`，`parse_mcp_config` 在Cursor（无需注册）
2. **开始试用** - [driftguard.org/start](https://driftguard.org/start) （完整专业版在一个端点）
3. **添加API密钥** - 在MCP环境中设置 `DRIFTGUARD_API_KEY` → 监控工具解锁
4. **团队** - [定价](https://driftguard.org/pricing) 以获取更多监视，审计导出，SSO
**高级（罕见）：** 使用 `DRIFTGUARD_API` 覆盖托管URL（默认为 `https://driftguard.org`）。非默认值需要 `DRIFTGUARD_ALLOW_CUSTOM_API=1` - 否则客户端固定到官方主机，以免恶意MCP配置泄露您的API密钥。
---
## 项目结构
```
src/core/ # 模式推断 + 差异（MIT）
src/cli/ # driftguard diff | mcp
src/mcp/ # MCP服务器（本地 + 托管代理）
examples/ # MCP客户端配置模板
docs/ # 文档中心，快速入门，参考
AGENTS.md # 代理贡献指南
SYSTEM_PROMPT.md # 代理工具参考
server.json # MCP注册表元数据
OPEN_CORE.md # 公共与托管边界
```
---
## 对于AI代理
| 文档 | 用途 |
|-----|-----|
| [docs/README.md](docs/README.md) | 文档中心 - 支柱，OSS与托管，导航 |
| [SYSTEM_PROMPT.md](SYSTEM_PROMPT.md) | 工具矩阵，决策流程，配置 |
| [docs/getting-started.md](docs/getting-started.md) | 进步式上线流程 |
| [docs/reference/](docs/reference/README.md) | MCP + CLI参考索引 |
| [docs/CI.md](docs/CI.md) | 版本固定的CI路径（Actions，npx，assert） |
| [AGENTS.md](AGENTS.md) | 编辑此仓库 |
| [docs/QUICKSTART.md](docs/QUICKSTART.md) | 设置步骤 |
在运行时调用MCP工具 **`hosted_info`** 以获取当前URL和功能矩阵。
---
## 设计
品牌套件： [docs/DESIGN.md](docs/DESIGN.md)
## 贡献
[CONTRIBUTING.md](CONTRIBUTING.md) - 仅限公共客户端。
## 许可证
MIT - [LICENSE](LICENSE)。仅适用于此仓库；托管服务是单独的。
