🛡️ MeterGate (v1.0.0)

是什么：一个零遥测 (No Telemetry)、100% 离线、MIT 开源无付费墙的本地 AI Agent 安全防火墙、一手 Token 对账台账与官方单价成本估算网关与标准 MCP (JSON-RPC 2.0) 中间件。
解决什么：

• 首要痛点·一手事实：按「模型 ID × 方向」（发出 prompt tokens / 收到 completion tokens / 缓存命中 cached tokens）一手计量你的 Agent 到底烧了多少 Token，与各厂商 Dashboard 的官方 usage 响应 100% 对齐，永不过期、永不失真；
• 派生价值·两级账本：在 Token 台账之上叠加 OpenAI / Anthropic / DeepSeek 官方公开单价推算成本（已对账真实花费与未回填预估分离，内置 30 天价目表保鲜守护）；
• 安全防线·三层阻断：实时拦截「提示注入 + .env 密钥偷跑」的致命三角，并支持导出一张高清晒单海报图 (SVG / HTML)。
  怎么零风险用起来 (O1 · O4)：免 Git 一行命令 pipx install metergate 或 uvx metergate serve --mode observe 先以「观察模式（只记账抓证据、0% 误拦风险）」跑一周，看到真实拦截证据后再一键开启阻断！

🔒 首屏五大安心承诺（Trust Signals · O5）

📌 前置定位与能力边界声明（决定使用前必读 · B5 & O3）

• ✅ 什么时候该装我：① 不知道 Claude Code / Cursor / OpenClaw 每天在哪个模型上烧了多少 Token（发出 vs 收到 vs 缓存命中），想要能与厂商 Dashboard 严格对账；② 担心 .env、sk-*、AKIA*、SSH 私钥外泄给外部模型或第三方 MCP 插件；③ 想先用「观察模式」无感摸清 Agent 行为底细。
• ❌ 什么时候别装我（已知盲区与边界）：① 单机单实例定位（上限 32 并发在途请求），不适合多租户团队共享或公网高并发集群；② 第二层（heuristic_concept_ngram_scorer）是轻量启发式概念簇+N-gram 规则，不是神经网络大模型推理，完全避开概念词表的零样本隐喻改写可能漏过；③ 不解析图片像素或 PDF 二进制流隐写。

⚡ 30 秒免 Git 安装 & 零风险「观察模式」体验 (O1 · O4 · B2 · B3)

方式一：uvx 或 pipx 一行命令启动（无需 git clone · O1）

# 1. 使用 pipx 安装（或直接用 uvx 免安装运行）
pipx install metergate

# 2. 先以「观察模式 (observe)」零风险启动：只记账、只记录越权证据，绝不阻断你的 Agent！
metergate serve --mode observe --port 8787

方式二：一行命令接管已有 Agent，并用自己的请求实测 (B2 · B3)

# 一行命令在当前终端同时接管 Claude Code / OpenAI SDK / Codex CLI / LangChain
eval "$(metergate serve --export-env)"

# 用你自己的话跑一次真实请求，立刻在 http://127.0.0.1:8787/console 看到记录
metergate demo --prompt "请帮我检查这段日志里的测试密钥 sk-live-myownkey99887766554433221100"

方式三：导出一张可晒单的日报海报图 (O6)

# 导出一张展示「帮我拦了什么、省了多少钱」的 SVG 海报图或独立 HTML
metergate report --format svg --output ./my_agent_report.svg
metergate report --format html --output ./my_agent_report.html

🤖 维度一：面向 AI Agent（机器消费者与推荐者）的检索与接入 (O1 ~ O3 · A1 ~ A6)

MeterGate 完整覆盖 Agent 选型时的三大信息源：包管理器索引 (PyPI / pipx / uvx)、MCP 目录站 (Official MCP Registry / Smithery / PulseMCP) 与 仓库内选型决策契约 (/llms.txt & /.well-known/metergate.json)：

Claude Desktop / Cursor / Windsurf 免安装 uvx MCP 挂载配置 (O1 & O2)

{
  "mcpServers": {
    "metergate": {
      "command": "uvx",
      "args": ["metergate", "serve", "--mcp-stdio"]
    }
  }
}

📊 维度二：两级对账体系 —— 一级 Token 事实与二级成本推算 (R-TOKEN-METER-01 · B1 · O7)

1. 为什么把 Token 用量升级为产品一等指标？

• 传统「按单价算钱」的痛点不够锐利：成本是「二手推算」，强依赖价目表 (model_catalog.json)，存在厂商临时调价、阶梯折扣与缓存折扣档位、动态计费三重失真风险，难以做到 100% 准确对账。
• Token 用量是唯一可严格对账的「一手事实」：每个 LLM API 响应（OpenAI / Anthropic / DeepSeek）都自带官方 usage 字段（prompt_tokens / completion_tokens / cached_tokens），与各厂商后台 Dashboard 完全一致，永不过期、永不失真。
• 驱动行动更具体：「不知道哪个模型消耗了多少 Token」比「不知道花了多少钱」更能驱动行动——清楚知道哪些任务在消耗大量 Prompt Token，才能精准将低价值长上下文任务降级到便宜模型！

2. 两级结构：一级 Token 事实 × 二级成本推算

• 一级事实（Token 台账）：按「模型 ID × 方向」两个维度计量：发出 Token (prompt_tokens) 与收到 Token (completion_tokens)，并单独区分缓存命中 Token (cached_tokens)。
• 二级推算（派生价值）：在 Token 台账之上叠加官方公开单价折算估算成本，保留「已对账真实花费 (actual_reconciled_usd)」与「未回填预估花费 (estimated_unreconciled_usd，标注 [估算])」严格分离，并由 30 天单价表保鲜检查 (catalog_freshness) 保障价目表时效。

model_catalog.json 仅收录真实、公开可核对的官方模型单价（单位：USD / 1K tokens），为二级成本推算提供依据：

🧰 日常主入口与高级运维命令收敛 (M-03 · B6 · O6)

关于基准自测的诚实说明 (M-12 & R4)：metergate benchmark 使用仓库内置的 18 条合成回归语料与 19 条三类对抗性回归语料（自测语料、非第三方验证），仅用于验证代码修改后规则未发生退化及测量本机单跳延迟，不代表对未知攻击的通用拦截率。

🛠️ 提需求 & 专属定制 (M-15)

• 👉 想让我帮你改一版？发到这里：直接前往本仓库 GitHub Issues 选择「需求建议」或「专属定制与改装意向」模板提交即可！

☕ 打赏支持 & 更多省时间工具 (M-13 & M-14)

• 💖 打赏支持作者：欢迎通过 GitHub Sponsors 或访问下方站点打赏支持开源开发。
• 🔗 更多省时间工具：访问 https://00112238.xyz 获取作者开发的全部开源效率与自动化工具集。