内容
<p align="center">
<h1 align="center">数据新鲜度校验</h1>
<p align="center">
<strong>用于AI代理的数据新鲜度验证。</strong>
<br />
防止您的代理使用过时的数据。
</p>
<p align="center">
<a href="https://github.com/Sudhan30/freshprobe/actions/workflows/ci.yml"><img src="https://github.com/Sudhan30/freshprobe/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
<a href="https://goreportcard.com/report/github.com/Sudhan30/freshprobe"><img src="https://goreportcard.com/badge/github.com/Sudhan30/freshprobe" alt="Go Report Card" /></a>
<a href="https://github.com/Sudhan30/freshprobe/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Sudhan30/freshprobe" alt="License" /></a>
<a href="https://github.com/Sudhan30/freshprobe/releases"><img src="https://img.shields.io/github/v/release/Sudhan30/freshprobe" alt="Release" /></a>
<img src="https://img.shields.io/badge/go-1.25-blue" alt="Go Version" />
</p>
</p>
---
> *"我要求我的代理检查航班价格。它给我提供了选项。我预订了一个。但价格在3小时前就已经改变了。"*
AI代理经常在不知道的情况下根据过时的数据采取行动。金融代理查询了47分钟前的缓存报价。支持机器人告诉客户他们的订单不存在，因为CRM尚未同步。RAG管道自信地用昨天的文档回答。
**freshprobe** 位于您的代理和外部世界之间。在代理采取行动之前，它会询问：*这些数据是否足够新鲜？* 答案始终是确定的JSON判决：**FRESH**、**STALE** 或 **UNKNOWN**。
```
$ freshprobe check https://api.example.com/v2/quotes
{
"verdict": "STALE",
"confidence": 0.94,
"endpoint": "https://api.example.com/v2/quotes",
"freshness": {
"data_age_seconds": 2847,
"freshness_score": 0.12,
"cache_control": "max-age=3600"
},
"liveness": {
"status": "DEGRADED",
"latency_p50_ms": 342,
"latency_p95_ms": 1847,
"body_size_bytes": 4096,
"error_rate": 0.03
},
"redirects": {
"total_hops": 1,
"final_url": "https://api-v2.example.com/quotes",
"has_redirect": true
},
"nist_mapping": {
"ai_rmf_function": "MEASURE",
"control": "MS-2.6-001"
}
}
```
单个Go二进制文件。无依赖。运行为CLI、MCP服务器或HTTP微服务。
## 为什么这很重要
| 问题 | 成本 |
|---------|------|
| 电商代理使用6个月前的产品数据 | [损失500万美元以上的收入](https://www.informatica.com/) |
| 企业RAG具有重叠的刷新基础设施 | 每年浪费34万美元 |
| 由于数据质量问题导致的AI项目失败 | [60%以上的失败（Gartner）](https://www.gartner.com/) |
与崩溃触发警报不同，过时的数据会产生**自信、格式良好、完全错误**的响应。 在多代理管道中链接几个这样的管道，每个组件都报告绿色，而输出却灾难性地错误。
## 安装
**Go安装（推荐）：**
```bash
go install github.com/Sudhan30/freshprobe/cmd/freshprobe@latest
```
**Docker：**
```bash
docker run --rm ghcr.io/sudhan30/freshprobe:latest check https://example.com
```
**从源代码：**
```bash
git clone https://github.com/Sudhan30/freshprobe.git && cd freshprobe && make build
./bin/freshprobe --version
```
**GitHub Releases：** 从[Releases](https://github.com/Sudhan30/freshprobe/releases)下载适用于Linux、macOS和Windows的预编译二进制文件。
## 快速开始
```bash
# 基本新鲜度检查
freshprobe check https://api.example.com/data
# 可读输出
freshprobe check https://api.example.com/data --output text
# 内容指纹：检测数据是否实际更改
freshprobe check https://api.example.com/data --repeat 3 --interval 2s
# 检查新鲜度策略
freshprobe check https://api.example.com/data --policy-dir ./policies --policy financial-data
# 批量检查多个端点
freshprobe batch https://api1.example.com https://api2.example.com https://cdn.example.com
# 持续监控（Ctrl+C停止）
freshprobe watch https://api.example.com/data --interval 30s --output text
# 仅在判决更改时提醒（FRESH -> STALE）
freshprobe watch https://api.example.com/data --interval 1m --on-change --output text
# 查看端点的探测历史
freshprobe history https://api.example.com/data --limit 20 --output text
```
## 六个验证信号
| 信号 | 检查内容 |
|--------|---------------|
| **HTTP缓存头** | 解析`Last-Modified`、`Cache-Control`、`Age`、`ETag`、`Date`、`Expires`。计算0.0至1.0的新鲜度得分 |
| **端点活跃度** | 测量响应延迟（P50/P95/P99）、状态码、主体大小、降级模式 |
| **内容指纹** | 对重复探测的响应体进行SHA-256哈希，以检测过时缓存 |
| **TLS证书健康状况** | 证书有效性、剩余天数、OCSP stapling状态 |
| **DNS解析时间** | DNS查找延迟作为基础设施健康状况信号 |
| **重定向链分析** | 跟踪301/302/307/308跳转，检测过时的CDN配置 |
## 三种部署模式
### CLI
```bash
freshprobe check <url> [flags]
freshprobe batch <urls...> [flags]
freshprobe watch <url> --interval 30s [flags]
freshprobe history <url> --limit 20
```
### MCP服务器（适用于AI代理）
将以下内容添加到您的AI工具配置中：
<details>
<summary><strong>Claude Desktop / Claude Code</strong></summary>
```json
{
"freshprobe": {
"type": "stdio",
"command": "freshprobe",
"args": ["serve", "--mode", "mcp", "--policy-dir", "/path/to/policies", "--stateless"]
}
}
```
</details>
<details>
<summary><strong>Cursor</strong></summary>
在`.cursor/mcp.json`中：
```json
{
"mcpServers": {
"freshprobe": {
"command": "freshprobe",
"args": ["serve", "--mode", "mcp", "--stateless"]
}
}
}
```
</details>
<details>
<summary><strong>VS Code (Copilot)</strong></summary>
在`.vscode/mcp.json`中：
```json
{
"servers": {
"freshprobe": {
"type": "stdio",
"command": "freshprobe",
"args": ["serve", "--mode", "mcp", "--stateless"]
}
}
}
```
</details>
这为AI代理公开了三个工具：
| 工具 | 描述 |
|------|-------------|
| `freshprobe_check` | 探测单个端点。返回JSON判决 |
| `freshprobe_batch` | 并发探测多个端点 |
| `freshprobe_policy` | 检查端点是否符合命名的新鲜度策略 |
### HTTP服务器
```bash
freshprobe serve --mode http --addr :8080
```
```
POST /api/v1/check {"url": "https://..."}
POST /api/v1/batch {"urls": ["https://...", "https://..."]}
POST /api/v1/policy {"url": "https://...", "policy_name": "api-realtime"}
GET /healthz
GET /metrics # Prometheus-compatible metrics
```
## 策略（代码中的新鲜度）
在YAML中定义每个域的新鲜度阈值：
```yaml
version: "1"
policies:
financial-data:
name: "金融数据"
domains: ["*.market.*", "*.trading.*"]
max_staleness: "30s"
min_freshness_score: 0.9
max_latency_p95_ms: 200
require_tls: true
min_tls_days_left: 30
require_changing: true
api-standard:
name: "标准API"
domains: ["api.*"]
max_staleness: "5m"
min_freshness_score: 0.6
max_latency_p95_ms: 2000
require_tls: true
```
当探测违反策略时：
```json
{
"policy_result": {
"policy_name": "金融数据",
"passed": false,
"violations": [
{"check": "max_staleness", "expected": "<= 30s", "actual": "2m15s"},
{"check": "max_latency_p95", "expected": "<= 200 ms", "actual": "847 ms"}
]
}
}
```
包含四个内置策略：`api-realtime`、`api-standard`、`static-content`、`financial-data`。
## 持续监控
```bash
# 监视端点，打印每次探测
freshprobe watch https://api.example.com/quotes --interval 30s --output text
# 仅在判决更改时打印（FRESH -> STALE转换）
freshprobe watch https://api.example.com/quotes --interval 1m --on-change --output text
# 运行10次探测并退出
freshprobe watch https://api.example.com/quotes --count 10 --interval 5s
```
示例输出：
```
Watching https://api.example.com/quotes every 30s
[14:22:01] FRESH conf=0.90 score=0.87 p95=142ms
[14:22:31] FRESH conf=0.90 score=0.85 p95=156ms
[14:23:01] STALE conf=0.85 score=0.22 p95=1847ms [FRESH -> STALE]
```
## Prometheus指标
HTTP服务器公开`/metrics`，采用Prometheus兼容的文本格式：
```
freshprobe_probes_total 142
freshprobe_verdict_total{verdict="FRESH"} 98
freshprobe_verdict_total{verdict="STALE"} 31
freshprobe_verdict_total{verdict="UNKNOWN"} 13
freshprobe_latency_p95_seconds 0.234000
freshprobe_freshness_score 0.7200
```
## 比较
| 功能 | freshprobe | Uptime Kuma | Gatus | freshcontext-mcp |
|---------|-----------|-------------|-------|-----------------|
| **目的** | AI代理的数据新鲜度 | 停机监控 | 健康仪表盘 | Web提取时间戳 |
| **知道数据是否过时** | 是（缓存头 + 指纹） | 否（仅检查HTTP状态） | 否（仅检查响应断言） | 部分（时间戳，无验证） |
| **MCP服务器** | 是（3个工具） | 否 | 否 | 是 |
| **策略引擎** | 是（YAML，按域） | 否 | 是（YAML条件） | 否 |
| **持续监控** | 是（`watch`命令） | 是（仪表盘） | 是（仪表盘） | 否 |
| **Prometheus指标** | 是 | 否（基于推送） | 是 | 否 |
| **部署** | 单个二进制文件 | Docker + DB | 单个二进制文件 | npm包 |
## 架构
```
+------------------+
| freshprobe |
| 单个二进制文件 |
+--------+---------+
|
+--------------+--------------+
| | |
+----+----+ +----+----+ +-----+-----+
| CLI | | MCP | | HTTP |
| （cobra）| | （stdio）| | （net/http）|
+---------+ +---------+ +-----------+
| | |
+--------------+--------------+
|
+--------+---------+
| 探测引擎 |
| |
| HTTP头 |
| 延迟P50/95/99 |
| 内容SHA-256 |
| TLS/OCSP |
| DNS时间 |
| 重定向链 |
+--------+---------+
|
+--------------+--------------+
| | |
+----+----+ +----+----+ +-----+-----+
| 判决 | | 策略 | | 存储 |
| 引擎 | | 引擎 | | SQLite / |
| | | （YAML）| | 无状态 |
+---------+ +---------+ +-----------+
```
## Kubernetes部署
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: freshprobe
spec:
replicas: 1
selector:
matchLabels: { app: freshprobe }
template:
metadata:
labels: { app: freshprobe }
spec:
containers:
- name: freshprobe
image: ghcr.io/sudhan30/freshprobe:latest
args: ["serve", "--mode", "http", "--addr", ":8080",
"--policy-dir", "/etc/freshprobe/policies", "--stateless"]
ports:
- containerPort: 8080
resources:
requests: { cpu: 50m, memory: 64Mi }
limits: { cpu: 200m, memory: 128Mi }
readinessProbe:
httpGet: { path: /healthz, port: 8080 }
livenessProbe:
httpGet: { path: /healthz, port: 8080 }
```
## Claude Code插件
```
/plugin install github:Sudhan30/freshprobe
```
安装后，询问Claude：
- *"交易API是否返回新鲜数据？*
- *"在运行批量作业之前检查所有端点*
- *"此API是否符合我们的实时SLA？*
## 开发
```bash
make build # 构建二进制文件
make test # 运行测试并启用竞争检测
make lint # go vet
make cross # 交叉编译（linux，macOS，Windows）
make docker # Docker构建
```
## 贡献
参见[CONTRIBUTING.md](CONTRIBUTING.md)。高价值领域：
- 特定领域的策略包（医疗保健，天气，金融）
- WebSocket/gRPC/GraphQL探测信号
- OpenTelemetry集成
- Homebrew公式
## 许可证
MIT。参见[LICENSE](LICENSE)。
---
<p align="center">
如果freshprobe帮助您的代理做出更好的决策， <a href="https://github.com/Sudhan30/freshprobe">请给它一个星星</a>。
</p>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器