withOhm

Ohm (withOhm)

一句話總結： withOhm 是一個位於你的應用程式（或 Cursor）與 OpenAI/Anthropic 等服務之間的代理 — 它會重放位元組完全相同的請求，讓你免費取得結果，而不是再次向模型付費；它會在合規控管下擷取公開網頁內容；並提供你一份可稽核、具密碼學收據的統一帳單，取代多份不透明的供應商發票。

針對浪費在重複推論上的計量管道：OpenAI 相容的入口、Redis 提示重放、合規網頁擷取、SSO 組織租戶，以及企業級乾淨帳本。對企業而言，同一條管道是 AI 支出的混沌治理器（典型切入點：docs/GEM_POSITION.md）。Cursor/MCP 是選用用戶端。

精確重放命中不消耗上游 token。跨供應商一致性。在地性 — Redis 邊緣讀取。重放與稽核價值。 將任何 OpenAI 相容用戶端（或 Ohm Agent Shell）指向單一 base 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 處於 pre-seed 且尚未取得動能，這是刻意的設計，而非疏漏的結果。完整表格與來源規則：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）是 pre-traction 時期投入的方向 — 請同時解讀階段數字與紀律，而非只看其中一項。

自行驗證

文字很廉價；每一項承載關鍵的宣稱都附帶可驗證它的指令。

宣稱	驗證方式
管道已上線（雙平面）	curl -s https://api.withohm.dev/health && curl -s https://api.withohm.dev/ready
命中會重放並以命中計費	傳送相同 body 兩次；第二次回應帶有 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 workflow history

本機開發者契約（穩定）

角色	位址	備註
公開用戶端入口	http://localhost:8081/v1	Rust 邊緣。將 OpenAI 軟體開發套件指向此處。
內部控制平面	http://localhost:8080	Python FastAPI。Rust 在快取未命中時代理至此。請勿將此交給陌生人。
驗證	Authorization: Bearer <ohm-api-key>	本機啟動金鑰：sk-at-dev（見 .env）。
BYOK	X-Ohm-Upstream-Key: <provider-key>	在快取未命中時，gpt/claude 需要此項，除非使用 env 或企業受管金鑰。
模型選擇	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。

Release smoke 會驗證健康狀態、mock miss/hit、OpenAI miss/hit（當有金鑰時）、Rust 平面標頭，以及用量計數器。Railgun smoke 會驗證 BYOK 標頭、seat_plus_meters，以及 checkout 端點形狀。

Cursor / MCP

本機 stdio MCP 加上透過 streamable HTTP 的無狀態遠端 MCP（MCP 2026-07-28 無狀態核心）。公開 base：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.

串流與容錯移轉的誠實說明

• 非串流 chat completions：Rust 邊緣在回傳 body 之前，可能會重試 Python 上游（主要然後備援 URL）。快取寫入發生在完整回應成功之後。
• 串流 chat completions：首個位元組前的容錯移轉已出貨。 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 規範下限定用途。整個 repo 必須維持在此框架內 — 見 docs/LEGAL.md。

當 fetch_web_context 為 true 時，用戶端必須傳送：

• 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）	元搜尋 + 公開頁面擷取 → 去識別化的 markdown/JSON，供 fetch_web_context 使用
src/at_utility/compliance/	用途矩陣、URL 閘門、robots.txt、PII 去識別化
src/ohm_mcp/	Cursor MCP 附加（ohm_fetch_web、ohm_usage、ohm_chat）
Redis 主節點 / 副本	快取 + RL；GET 在副本/讀取器、SET 在主節點 — docs/REDIS_MESH.md
infra/	Terraform + Kubernetes：單區域 EKS（mesh 保留在旗標之後）
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