freshprobe (Sudhan30)

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微服务运行。

为什么这很重要

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

安装

去安装（推荐）：

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

六个验证信号

三种部署模式

命令行界面

freshprobe check  [flags]
freshprobe batch  [flags]
freshprobe watch  --interval 30s [flags]
freshprobe history  --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代理提供了三种工具：

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": " 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     |
                    |   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.