工作原理
ATM 是面向 AI 编程 Agent 的 本地优先网关。它发现各工具的原生配置，按你选择的路由写回配置，并把用量记录留在本机。
请求路径
Agent -> 原生配置 -> 当前路由
|
+-> 普通 API 供应商
| ATM 不在请求路径上；之后从本地历史读取用量。
|
+-> ATM Gateway @ 127.0.0.1:4317
atm key -> 身份 -> 策略 -> 上游供应商
响应流 -> 请求日志 -> 用量聚合
网关流水线
当 Agent 走 ATM Gateway 时，单次请求按下面流程处理：
| 步骤 | 发生什么 |
|---|---|
| 1 | 网关在 127.0.0.1:4317 接收支持的模型请求路径。 |
| 2 | 从请求头读取并鉴权 atm-... key。 |
| 3 | 解析请求身份：employee、agent、parent agent、key 与 policy。 |
| 4 | 请求协议限定候选供应商必须属于同一应用族。 |
| 5 | 绑定策略选出 (provider, model) 目标。 |
| 6 | 熔断器可能跳过不健康供应商，并尝试兼容的 fallback。 |
| 7 | ATM 使用本地保存的 Provider key 调用上游。 |
| 8 | 响应流式回写给 Agent，然后写入请求日志与用量聚合。 |
路由规则
身份与路由分离。atm-... key 表示谁发起请求；策略决定请求去哪里。轮换 key 不改变路由，修改策略也不会让已有 key 失效。
策略只能在同一应用族内工作。Claude 策略指向 Claude 兼容供应商，Codex 指向 Responses 兼容供应商，Gemini 指向 Gemini 兼容供应商。ATM 不会把请求跨族路由成 Agent 不期望的响应形状。
内置 Default 策略始终使用配置的默认目标。内置 Test 策略用于验证路由行为。自定义策略可以按权重调度，也可以按 coding、reasoning、long-context、vision 等意图标签选择目标。
用量与存储
Usage 合并两个本地数据源：
- 网关日志：所有经过 ATM Gateway 的请求。
- 本地历史扫描：Claude Code、Codex、Gemini CLI、OpenClaw、Cursor 等工具自己记录的直连请求。
扫描器只读。它解析各工具的 transcript 或 session 文件，提取时间、模型、Token 数、项目归属，以及可用时的 workspace 归属。
ATM 自有状态全部在 ~/.atm/ 下。主 SQLite 数据库存储 Provider、Agent、已签发 key 的前缀、策略、请求日志和用量聚合。Provider key 由 macOS Keychain 加密。atm-... key 原值只在签发时返回一次，不会落盘。
本地边界
| 边界 | 行为 |
|---|---|
| 网关监听 | 仅回环：127.0.0.1:4317。 |
| Provider 调用 | 仅当 Agent 请求需要上游模型时发起出站 HTTPS。 |
| 更新 | 只在手动检查更新时发生。 |
| 请求数据 | 只写入本地数据库。 |
| 备份 | 迁移、配置重置和批量编辑前写到 ~/.atm/backups/。 |