withOhm

官方

AI traffic control plane (chaos governor): Redis prompt replay, compliant web ingest, SSO org ledger, Agent Shell. BYOK OpenAI-compatible ingress. Cursor optional; MCP is a compatibility client.

GitHub

你可以用 withOhm MCP 做什么？

重放缓存提示 — 让您的AI重新发送相同的请求，并获得字节完全一致的响应，带有X-AT-Cache: HIT，按命中计费，而非新的模型调用。
验证加密收据 — 让您的助手使用verify_receipt.py检查任何响应上带签名的X-Ohm-Receipt JWS，以证明命中是真实的，而非声称的。
获取公共网页上下文 — 使用ohm_fetch_web检索公共页面，返回为经过编辑的markdown/JSON，并强制执行web_purpose和web_compliance_ack等合规标志。
检查用量和计费 — 查询ohm_usage以查看跨ohm_cache_hit、ohm_cache_miss和ohm_web_fetch计量器的计量消耗，以及跨租户节省估算。
通过代理聊天 — 使用ohm_chat通过一个基础URL向任何提供商（OpenAI、Anthropic、Google等）发送兼容OpenAI的请求，并通过X-Ohm-Upstream-Key实现BYOK。

文档

Ohm (withOhm)

一句话概括： withOhm 是一个位于你的应用（或 Cursor）与 OpenAI/Anthropic 等之间的代理 —— 它会重放字节完全相同的请求而无需再次向模型付费，在合规管控下获取公开网页上下文，并给你一份可审计、带加密收据的统一账单，而不是多份不透明的供应商发票。

针对浪费的、重复推理的计量管道：OpenAI 兼容入口、Redis 提示词重放、合规网页摄取、SSO 组织租户，以及企业级干净账本。对企业而言，同样的管道是 AI 支出的混沌治理器（典型楔入场景：docs/GEM_POSITION.md）。Cursor/MCP 是可选的客户端。

精确重放命中不消耗上游 token。跨供应商一致性。本地性 —— Redis 边缘读取。重放与审计价值。 将任何 OpenAI 兼容客户端（或 Ohm Agent Shell）指向一个基础 URL。保留你的密钥或使用托管池。租用管道；治理混沌。

网站： https://www.withohm.dev · API： https://api.withohm.dev/v1 · 工作台： /workbench · 架构： docs/ARCHITECTURE.md · 愿景： docs/VISION.md · 企业版： docs/ENTERPRISE_CHAOS.md · Gem： docs/GEM_POSITION.md · 关怀审计： docs/CARE_AUDIT.md —— 这是应用于每一项公开声明的真相维护准则；在评判工程与牵引力之比之前，请先阅读它。

许可证： MIT（见 LICENSE + NOTICE）。源码开放；托管式 withOhm 管道仍然是商业计量服务。包/密钥名称可能仍显示为 at-utility / sk-at-*（遗留的 AT 前缀）；产品名称是 withOhm。

阶段，坦率地说

不粉饰：withOhm 处于种子前且尚无牵引力，这是有意为之，而非疏漏所致。完整表格和溯源规则：docs/STATUS.md。

事实	现状
版本	`0.1.2`
设计伙伴	10 团队目标中的 0（docs/DESIGN_PARTNERS.md —— "从零开始"）
机构融资	无；尚未注册成立（docs/distribution/INVESTOR_INTRO_TARGETS.md）
区域	单一（`us-east-1`）；无合同 SLA
自动化测试覆盖率	`tests/` 中 30 个文件、215+ 个测试函数（`pytest -q`，每次推送均运行 CI）

工程与审计纪律（测试、签名收据、INSPECTION.md、docs/CARE_AUDIT.md）是种子前阶段投入时间的成果 —— 请将阶段数字与纪律结合起来阅读，而不是只看其中任何一项。

自行验证

文字很廉价；每一项承重的声明都附带可验证它的命令。

声明	验证方式
管道已启动（两个平面）	`curl -s https://api.withohm.dev/health && curl -s https://api.withohm.dev/ready`
命中会被重放并按命中计费	发送两次相同请求体；第二次响应包含 `X-AT-Cache: HIT` + `X-AT-Billed-USD`
命中是加密性的，而非声称的	命中响应携带 `X-Ohm-Receipt`（签名 JWS）—— 验证：`python scripts/verify_receipt.py "<receipt>"`（docs/RECEIPTS.md）
签名密钥是公开的	`curl -s https://api.withohm.dev/.well-known/http-message-signatures-directory`
已发布的限制与拒绝事项	`curl -s https://api.withohm.dev/v1/public/honesty` —— 我们不会做什么，以及证明每一项的端点
跨租户节省计数器	`curl -s https://api.withohm.dev/v1/public/stats`（始终为 `estimate_only: true`）
审核路径每晚针对生产环境运行	Golden path 工作流历史

本地开发者契约（稳定）

角色	地址	说明
公共客户端入口	`http://localhost:8081/v1`	Rust 边缘。将 OpenAI SDK 指向此处。
内部控制平面	`http://localhost:8080`	Python FastAPI。缓存未命中时 Rust 代理此处。不要将此地址交给陌生人。
认证	`Authorization: Bearer <ohm-api-key>`	本地引导密钥：`sk-at-dev`（见 `.env`）。
BYOK	`X-Ohm-Upstream-Key: <provider-key>`	除非使用环境变量或企业托管密钥，否则 gpt/claude 缓存未命中时必需。
模型选择	JSON 字段 `model`	`mock` 保持本地；`gpt-` / `o` → OpenAI；`claude-` → Anthropic；`gemini-` → Google；`deepseek-` → DeepSeek；`kimi-` / `moonshot-` → Moonshot；`glm-` → Z.ai；`qwen` → Qwen；`grok-` → xAI（均为 OpenAI 兼容，BYOK）。

from at_utility_sdk import openai_client, LOCAL_BASE_URL

client = openai_client(
    "sk-at-dev",
    base_url=LOCAL_BASE_URL,
    upstream_api_key="sk-proj-...",
)
completion = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)

快速开始（Docker Compose）

cd <repo-root>   # e.g. clone of iwasinnam2/ohm
copy .env.example .env
# Edit .env: set OPENAI_API_KEY for local env-fallback; keep OPENAI_BASE_URL=https://api.openai.com/v1
docker compose --profile rust up --build -d
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\release_smoke.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\railgun_smoke.ps1

云端 / 代理原生运行（无需 Docker）：见 AGENTS.md。

发布冒烟测试断言健康状态、模拟未命中/命中、OpenAI 未命中/命中（存在密钥时）、Rust 平面头部以及用量计数器。Railgun 冒烟测试断言 BYOK 头部、seat_plus_meters 以及结账端点形态。

Cursor / MCP

本地 stdio MCP 外加一个基于流式 HTTP 的无状态远程 MCP（MCP 2026-07-28 无状态核心）。公共基础地址：https://api.withohm.dev/v1。合作伙伴：docs/LAUNCH_GTM.md · https://www.withohm.dev/design-partners

pip install withohm-mcp
# monorepo dev alternative: pip install -e ".[mcp]"
# stdio (Cursor local attach): set OHM_API_KEY (required). Optional: OHM_UPSTREAM_KEY, OHM_BASE_URL
# Plugin: .cursor-plugin/ + mcp.json — see docs/CURSOR.md

# Remote (stateless streamable HTTP at /mcp, default port 8091):
#   OHM_MCP_TRANSPORT=http ohm-mcp     (or: ohm-mcp-http)
# Auth is per-request: clients send `Authorization: Bearer sk-at-*`
# (falls back to OHM_API_KEY env). Host allowlist: OHM_MCP_ALLOWED_HOSTS.

流式与故障转移的诚实说明

非流式聊天补全：Rust 边缘可能会在返回响应体之前重试 Python 上游（主 URL 然后备用 URL）。缓存写入发生在完整响应成功之后。
流式聊天补全：首字节前故障转移已发布。 Python 平面会主动打开上游流，如果流在首字节前死亡则重试一次，若两次尝试均失败则返回真实的 HTTP 错误（而非带 200 错误帧的流）；Rust 边缘在连接错误或首字节前 5xx 时回退，并逐块转发 token 流（边缘不缓冲）。首字节之后无需客户端重连即可进行流中供应商切换不受支持 —— 关键路径请规划重连或使用非流式。

环境规则

实时密钥只能放在 .env 中（已被 gitignore）。
.env.example 绝不能包含实时的 OpenAI 或 Stripe 密钥。
更改 .env 后，重建容器：docker compose up -d --force-recreate gateway。
OPENAI_BASE_URL 必须是 https://api.openai.com/v1，绝不能是网站主机名 platform.openai.com。

法律边界（强制要求）

网页摄取仅限公开内容，且用途受限，符合英国 GDPR/CMA 和美国 CFAA/CCPA 规范。整个仓库必须保持在此框架内 —— 见 docs/LEGAL.md。

当 fetch_web_context 为真时，客户端必须发送：

web_purpose —— public_web_retrieval、business_catalog、public_company_info、job_listings 之一
web_compliance_ack: true —— 确认仅限公开内容，不做线索收集/档案记录/受限访问
terms_ack / dpa_ack: true —— 绑定 docs/legal/ 模板
可选 cache_control: "no_store" —— 跳过 Redis 写入以保护机密提示词

查看实时策略：GET /v1/compliance/policy。模板：条款、DPA、上游检查清单，位于 docs/legal/ 下。

架构

层	角色
`gateway-rs`（`:8081`）	公共边缘：Redis 序列化协议缓存、代理、平面头部
Python 网关（`:8080`）	OpenAI 兼容 API、供应商、速率限制、计量、租户、合规门控
摄取工作器（`:8090`）	元搜索 + 公开页面抓取 → 供 `fetch_web_context` 使用的脱敏 markdown/JSON
`src/at_utility/compliance/`	用途矩阵、URL 门控、robots.txt、PII 脱敏
`src/ohm_mcp/`	Cursor MCP 挂载（`ohm_fetch_web`、`ohm_usage`、`ohm_chat`）
Redis 主 / 副本	缓存 + 限流；GET 走副本/读节点，SET 走主节点 —— docs/REDIS_MESH.md
`infra/`	Terraform + Kubernetes：单区域 EKS（网格在标志后面保留）
`site/`	营销 + 文档 + 自助 `/billing`

租户与计费

引导密钥 sk-at-dev 可在本地使用。自助服务：POST /v1/billing/checkout（网站 /billing）。运维：使用管理员密钥签发（AT_ADMIN_API_KEYS）：

curl.exe -s -X POST http://localhost:8080/v1/admin/tenants `
  -H "Authorization: Bearer sk-at-dev" `
  -H "Content-Type: application/json" `
  -d "{\"plan\":\"payg\",\"label\":\"design-partner-1\",\"terms_ack\":true,\"dpa_ack\":true}"

已暂停的租户（POST /v1/admin/tenants/{id}/status 且 {"status":"suspended"}，或 Stripe 取消 webhook）将收到 HTTP 403。

计量写入持久的每日账本密钥，并在设置 stripe_customer_id 时同步 Stripe Billing Meters（ohm_web_fetch、ohm_cache_hit、ohm_cache_miss）。

账本： 客户向供应商付款（BYOK）。客户向 Ohm 支付席位费 + 计量费。可选：pip install -e ".[billing]"。

测试

pip install -e ".[dev,billing]"
pytest -q