AI导哈

数据新鲜度验证工具

freshprobe是一款用于验证AI代理数据新鲜度的工具，确保代理不会基于过时数据采取行动。

  • by Sudhan30
  • Go
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 Sudhan30/freshprobe

使用说明

freshprobe

Data freshness verification for AI agents.
Stop your agents from acting on stale data.

“我让我的经纪人查一下航班价格。它给了我选择。我订了一个。票价3小时前就变了。”

人工智能代理经常在不知情的情况下对过时的数据采取行动。一位金融代理查询47分钟前的缓存报价。支持机器人告诉客户他们的订单不存在，因为CRM尚未同步。RAG管道自信地回答了昨天的文档。

freshprobe 位于你的代理人和外部世界之间。在代理采取行动之前，它会问： 这些数据足够新鲜吗？ 答案总是一个确定性的JSON判断： 新鲜, 陈腐的，或 未知.

$ 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"
  }
}

Single Go二进制。没有依赖关系。作为CLI、MCP服务器或HTTP微服务运行。

为什么这很重要

问题 成本
电子商务代理使用了6个月前的产品数据 500万美元+收入损失
具有重叠刷新基础设施的企业RAG 每年浪费34万美元
数据质量问题导致AI项目失败 60%以上的失败案例（Gartner）

与触发警报的崩溃不同，过时的数据会产生 自信、格式正确、完全错误的回答将其中一些链接到多代理管道中，每个组件都报告为绿色，而输出却出现了灾难性的错误。

安装

去安装（推荐）：

go install github.com/Sudhan30/freshprobe/cmd/freshprobe@latest

Docker：

docker run --rm ghcr.io/sudhan30/freshprobe:latest check https://example.com

来源：

git clone https://github.com/Sudhan30/freshprobe.git && cd freshprobe && make build
./bin/freshprobe --version

GitHub发布： 从以下网址下载适用于Linux、macOS和Windows的预构建二进制文件 发布.

快速启动

# Basic freshness check
freshprobe check https://api.example.com/data

# Human-readable output
freshprobe check https://api.example.com/data --output text

# Content fingerprinting: detect if data actually changes
freshprobe check https://api.example.com/data --repeat 3 --interval 2s

# Check against a freshness policy
freshprobe check https://api.example.com/data --policy-dir ./policies --policy financial-data

# Batch check multiple endpoints
freshprobe batch https://api1.example.com https://api2.example.com https://cdn.example.com

# Continuous monitoring (Ctrl+C to stop)
freshprobe watch https://api.example.com/data --interval 30s --output text

# Only alert on verdict changes (FRESH -> STALE)
freshprobe watch https://api.example.com/data --interval 1m --on-change --output text

# View probe history for an endpoint
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装订状态
DNS解析时间 DNS查找延迟作为基础设施健康信号
重定向链分析 跟踪301/302/307/308跳，检测过时的CDN配置

三种部署模式

命令行界面

freshprobe check <url> [flags]
freshprobe batch <urls...> [flags]
freshprobe watch <url> --interval 30s [flags]
freshprobe history <url> --limit 20

MCP服务器（用于AI代理）

添加到您的AI工具配置中：

Claude Desktop / Claude Code 
{
  "freshprobe": {
    "type": "stdio",
    "command": "freshprobe",
    "args": ["serve", "--mode", "mcp", "--policy-dir", "/path/to/policies", "--stateless"]
  }
}
Cursor

在 .cursor/mcp.json:

{
  "mcpServers": {
    "freshprobe": {
      "command": "freshprobe",
      "args": ["serve", "--mode", "mcp", "--stateless"]
    }
  }
}
VS Code (Copilot)

在 .vscode/mcp.json:

{
  "servers": {
    "freshprobe": {
      "type": "stdio",
      "command": "freshprobe",
      "args": ["serve", "--mode", "mcp", "--stateless"]
    }
  }
}

这为AI代理提供了三种工具：

工具 说明
freshprobe_check 探测单个端点。返回JSON判断结果
freshprobe_batch 同时探测多个端点
freshprobe_policy 根据命名的新鲜度策略检查端点

HTTP服务器

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中定义每个域的新鲜度阈值：

version: "1"
policies:
  financial-data:
    name: "Financial Data"
    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: "Standard API"
    domains: ["api.*"]
    max_staleness: "5m"
    min_freshness_score: 0.6
    max_latency_p95_ms: 2000
    require_tls: true

当探测器违反政策时：

{
  "policy_result": {
    "policy_name": "Financial Data",
    "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.

持续监测

# Watch an endpoint, print every probe
freshprobe watch https://api.example.com/quotes --interval 30s --output text

# Only print when verdict changes (FRESH -> STALE transitions)
freshprobe watch https://api.example.com/quotes --interval 1m --on-change --output text

# Run 10 probes and exit
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]

普罗米修斯指标

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 正常运行时间Kuma Gatus freshcontext mcp
目的 AI代理的数据新鲜度 正常运行时间监控 运行状况仪表板 Web提取时间戳
知道数据已过时 是（缓存头+指纹识别） 否（仅检查HTTP状态） 不（仅检查响应断言） 部分（时间戳，无验证）
MCP服务器 是（3个工具） 否 否 是
策略引擎 是（YAML，每个域） 否 是（YAML条件） 否
持续监测 是的(watch 命令） 是（仪表板） 是
普罗米修斯指标 是 否（基于推送） 是 否
部署 单二进制 Docker+DB 单二进制 npm包

建筑

                    +------------------+
                    |   freshprobe     |
                    |   single binary  |
                    +--------+---------+
                             |
              +--------------+--------------+
              |              |              |
         +----+----+   +----+----+   +-----+-----+
         |   CLI   |   |   MCP   |   |   HTTP    |
         | (cobra) |   | (stdio) |   | (net/http)|
         +---------+   +---------+   +-----------+
              |              |              |
              +--------------+--------------+
                             |
                    +--------+---------+
                    |   Probe Engine   |
                    |                  |
                    | HTTP headers     |
                    | Latency P50/95/99|
                    | Content SHA-256  |
                    | TLS/OCSP        |
                    | DNS timing       |
                    | Redirect chains  |
                    +--------+---------+
                             |
              +--------------+--------------+
              |              |              |
         +----+----+   +----+----+   +-----+-----+
         | Verdict |   | Policy  |   |   Store   |
         | Engine  |   | Engine  |   | SQLite /  |
         |         |   | (YAML)  |   | Stateless |
         +---------+   +---------+   +-----------+

Kubernetes部署

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代码插件

/plugin install github:Sudhan30/freshprobe

安装后，询问Claude：

  • “交易API是否返回新数据？”
  • “运行批处理作业之前，请检查所有端点”
  • “此API是否符合我们的实时SLA？”

发展

make build       # Build binary
make test        # Run tests with race detector
make lint        # go vet
make cross       # Cross-compile (linux, macOS, Windows)
make docker      # Docker build

贡献

看 贡献.md高价值区域：

  • 特定领域（医疗保健、天气、金融）的政策包
  • WebSocket/gRPC/GraphQL探测信号
  • OpenTetry集成
  • 自制配方

许可证

MIT。看 许可证.

If freshprobe helps your agents make better decisions, give it a star.

相关 MCP