feat(ai-gateway): add Token Forge traffic policy

README.md

@@ -55,6 +55,7 @@ Web 端采用 **Astro + TypeScript + Preact Islands**，首期生成静态 HTML
 - 接入 AI：先读 [AI 成本与安全](./docs/ai-safety-and-cost.md)。
 - 实现 AI 调用：遵循 [AI Gateway v1 合同](./docs/ai-gateway-contract-v1.md)。
 - Token Forge AI 规划：遵循 [AI 任务拆分](./docs/token-forge-ai-planning.md)。
+- Token Forge AI 成本边界：遵循 [流量与成本策略](./docs/token-forge-ai-traffic-policy.md)。
 - Token Forge 本地导出：遵循 [Markdown / GitHub Issue 导出](./docs/token-forge-export.md)。
 - Token Forge 正式页面：遵循 [页面与事件合同](./docs/token-forge-page.md)。
 - Token Forge 当前顺序与 Beta 门槛：遵循 [优先路线图](./docs/token-forge-roadmap.md)。
@@ -104,5 +105,8 @@ Score-only 的确定性 SVG 下载，Incident Detective MVP 六个任务全部
 缺失字段、厂商扩展、SMART 不可用和冲突信号。P3-002 已上线浏览器端只读解析工作台和
 Parse Result v1。P3-003 已增加序列号、WWN、主机名、IP 与常见 Secret 的本地脱敏预览，
 以及不含自由文本的 Boundary Projection v1；URL、日志和 Analytics 进一步收窄为固定元数据，
-AI 与导出尚未启用，现有结果仍不构成厂商保修判断。Token Forge 下一步是 P4-004，为生产
-AI 建立预算、限流和熔断边界；完整顺序以 Token Forge 优先路线图为准。
+AI 与导出尚未启用，现有结果仍不构成厂商保修判断。P4-004 已为 Token Forge 建立按最坏
+两次 Provider 尝试预留的 Token/微美元预算、匿名用户与全局限流、并发和熔断状态机，
+快照不含输入正文；它目前仍是 Provider-neutral 的离线核心。Token Forge 下一步是 P1-008，
+为该状态机接入原子持久化、真实 Provider 与页面模板降级；完整顺序以 Token Forge 优先
+路线图为准。

TODO.md

@@ -81,7 +81,7 @@
   - 验收：只访问公开 GitHub 固定 API Origin；不要求 Token；明确显示读取、忽略、截断和未知计数；超时、限流、私有/无效仓库或疑似 Secret 时保留 P1-002 模板路径。
 
 - [ ] **P1-008 [L] 接通受预算保护的生产 AI 规划**
-  - 依赖：P4-004。
+  - 依赖：P4-004（已完成）。
   - 产物：服务端 AI Gateway 端点、Provider Adapter、页面 AI 增强入口、流式或明确等待状态和模板降级。
   - 验收：浏览器不含密钥；AI 只接收版本化 allowlist 投影；预算、超时、限流、无效响应和熔断均保留可导出的模板计划；响应重新通过全部确定性合同。
 
@@ -166,15 +166,21 @@
   - Production：`https://lab.margrop.net`。
   - 验收：Custom Domain、HTTPS、首页、核心内容和 `robots.txt` 在线检查通过；生产发布保持手动触发。
 - [ ] **P4-003 [M] 为 Token Forge 建立不采集输入正文的 Analytics**
-- [ ] **P4-004 [M] 建立 Token Forge AI 日/用户预算、限流与熔断**
+- [x] **P4-004 [M] 建立 Token Forge AI 日/用户预算、限流与熔断**
+  - 产物：`token-forge-ai-policy-v1`、匿名用户/Lab/全站三层 Token 与微美元日预算、滑动
+    限流、并发预留、熔断状态机、可验证隐私快照和 Gateway 安全失败映射。
+  - 验收：Provider 调用前覆盖最多两次尝试的最坏成本；可信成功结算退回差额，失败或预留
+    超时全额计费；重复请求不重复预留；半开只允许一个探针；快照不包含目标、Prompt、仓库
+    URL、路径、正文、原始网络标识或 Provider 错误；无网络、存储和日志副作用。
 - [ ] **P4-005 [S] 为博客生成 Token Forge 统一 CTA 片段**
 - [ ] **P4-006 [S] 在博客导航突出 Token Forge 入口**
 - [ ] **P4-007 [M] 建立 Labs 首页与 Token Forge 的 SEO、Open Graph 和 sitemap**
 - [ ] **P4-008 [M] 复盘 Token Forge 打开率、运行率、导出率、失败原因和 GitHub 点击率**
 
 ## 推荐下一项任务
 
-接下来只做 **P1-007**：把已经完成的公开 GitHub 仓库摘要适配器接入 Token Forge 页面，
-形成“可选仓库 URL → 受限只读摘要 → 覆盖/未知项 → 模板计划”的可用闭环。仓库不可用、
-限流、超时、疑似 Secret 或输入无效时必须保留无需网络的模板结果；不得要求用户提供
-GitHub Token，不得提前接入真实 AI。每次仍只处理一个任务。
+接下来只做 **P1-008**：为 P4-004 状态机接入服务端原子持久化、不可逆匿名用户键、固定
+Provider/模型/价格表和所有 Provider 尝试的可信成本结算，再把 P1-004 AI 增强接到页面。
+浏览器不得持有密钥、价格或结算字段；预算、限流、熔断、超时、Provider 与输出失败都必须
+保留可导出的 P1-002 模板计划。Preview 验证后仍由人工触发 Production 发布，每次仍只
+处理一个任务。

apps/api/README.md

@@ -8,4 +8,7 @@
 - 公开 GitHub 仓库的受限读取；
 - 不含正文的调用元数据。
 
-服务端不得成为确定性解析和脱敏的唯一实现，也不得记录用户输入正文。P0-006 确认合同后再选择运行时。
+服务端不得成为确定性解析和脱敏的唯一实现，也不得记录用户输入正文。P4-004 已提供
+Token Forge 的 Provider-neutral 流量策略与可序列化快照；P1-008 选择运行时时必须为它
+提供原子持久化、服务端匿名用户键、固定价格表和所有 Provider 尝试的可信结算。完整边界见
+[Token Forge AI 流量与成本策略](../../docs/token-forge-ai-traffic-policy.md)。

docs/ai-gateway-contract-v1.md

@@ -109,17 +109,26 @@ P2-005 的 `incident-detective.case-proposal-v1` 操作只发送 ID、主题、
 Payload、内部答案、canonical attempt 或评分规则；输出只能进入人工审核，不能自动发布。
 详见[受约束案例生成与审核](./incident-detective-case-generation.md)。
 
+P4-004 为 `token-forge.plan-v1` 增加 Provider-neutral 的准入状态机。它在 Provider 调用前
+按最多两次尝试预留 56,000 可计费 Token 和 $0.10，执行匿名用户、Lab、全站三层日预算、
+滑动限流、并发与熔断；成功后按所有尝试的可信汇总用量退款，失败或预留超时按全额计费。
+固定数值、快照隐私和 P1-008 接入要求见
+[Token Forge AI 流量与成本策略](./token-forge-ai-traffic-policy.md)。
+
 ## Fixture 与验证
 
 - `ai-gateway-request.valid.json`
 - `ai-gateway-response.valid.json`
+- `token-forge-ai-policy.valid.json`
 
 测试使用内存中的合成 Adapter，覆盖公共 Schema、服务端控制字段、请求/响应/Token 上限、超时、限流、暂时不可用、无效模型结构、秘密回流、Provider 错误隔离和 HTTP 映射。没有真实 Provider、真实仓库内容或真实凭据。
 
 ## 已知限制
 
-- 没有 HTTP 路由、身份识别、限流存储、日预算存储和部署配置；
+- 没有 HTTP 路由、匿名身份派生、策略快照的原子持久化和部署配置；
 - 没有具体 Provider Adapter、模型选择、SDK 或精确 Tokenizer；
 - 通用请求 Schema 不能替代每个操作的输入 Schema；
 - Gateway 自身的最小秘密检测不能替代 P0-007 和各操作的允许字段脱敏；
-- `request_id` 目前只是合同字段，幂等缓存需要未来服务端状态实现。
+- 通用 Gateway 的 `request_id` 仍没有响应缓存；Token Forge 策略只提供 24 小时有限去重；
+- P4-004 不读取模型价格，也不汇总 Provider 尝试；P1-008 必须在服务端完成这两项后才能
+  提交可信结算。

docs/ai-safety-and-cost.md

@@ -21,3 +21,8 @@
 至少限制：单请求输入、单请求输出、IP/匿名会话频率、Lab 日预算、全站日预算、最大并发和 Provider 超时。
 
 预算耗尽时，样例模式和确定性核心继续可用。日志只记录 Lab ID、模型代号、耗时、Token 数、状态和粗粒度错误码。
+
+Token Forge 的固定数值、先预留后结算、匿名用户键、熔断和持久化要求见
+[AI 流量与成本策略](./token-forge-ai-traffic-policy.md)。成本预留必须覆盖一次 Gateway
+请求内的全部 Provider 尝试；只有服务端汇总的可信实际 Token 与微美元成本可以触发退款，
+失败、进程中断或预留过期均按全额计费。

docs/token-forge-ai-planning.md

@@ -84,6 +84,17 @@ AI Gateway 的 Provider Request 不包含 `provider`、`model`、`system_prompt`
 
 模板输入也会在本地脱敏，所以降级计划不会把导致 AI 拒绝的 Secret 原样写回 Prompt。
 
+## 生产流量边界
+
+P4-004 已提供 `token-forge.plan-v1` 专属的日 Token/微美元预算、匿名用户滑动限流、并发
+预留与熔断状态机。每次生产调用必须在 Provider 前预留最多两次尝试的最坏成本；成功后按
+所有尝试的可信汇总用量结算，任意失败或预留超时则保留全额预留。准入拒绝映射为现有
+Gateway 错误码，P1-004 继续返回完整模板计划。
+
+策略核心不包含 Provider、端点、匿名身份派生或持久化。P1-008 必须按
+[AI 流量与成本策略](./token-forge-ai-traffic-policy.md) 接入原子状态存储后，才能把本
+模块连接到正式页面。
+
 ## 测试范围
 
 测试使用内存中的合成 Adapter 和合成公开仓库摘要，覆盖：
@@ -101,6 +112,6 @@ AI Gateway 的 Provider Request 不包含 `provider`、`model`、`system_prompt`
 
 - 尚无真实 Provider Adapter、服务端操作注册表或 HTTP API；
 - Token Forge 正式页面当前只接入确定性模板，AI 路径仍未连接；
-- 未实现用户级/每日预算、持久化限流或熔断；
+- 用户级/每日预算、限流和熔断已有离线状态机，但尚无生产端点与原子持久化；
 - 自然语言护栏不能替代最小权限与人工确认；
 - 导出边界由 P1-005 另行实现。

docs/token-forge-ai-traffic-policy.md

@@ -0,0 +1,133 @@
+# Token Forge AI 流量与成本策略
+
+P4-004 为 `token-forge.plan-v1` 定义 Provider-neutral 的预算、滑动限流、并发预留和熔断
+核心。实现位于 `@margrop-labs/ai-gateway/token-forge-policy`，只操作经过验证的内存状态，
+不创建 HTTP 端点、Provider Adapter、密钥、数据库或部署配置。
+
+策略合同由
+[`token-forge-ai-policy-v1.schema.json`](../schemas/token-forge-ai-policy-v1.schema.json)
+约束。P1-008 必须先通过这层准入，再调用 Provider；任一拒绝都沿用 AI Gateway 的安全失败
+信封并保留确定性模板计划。
+
+## 固定硬边界
+
+| 边界 | 默认硬上限 |
+| --- | ---: |
+| 单个 Gateway 请求可计费 Token | 56,000 |
+| 单个 Gateway 请求成本 | $0.10 |
+| 匿名用户每日 Token | 224,000 |
+| Token Forge 每日 Token | 2,240,000 |
+| 全站每日 Token | 5,600,000 |
+| 匿名用户每日成本 | $0.25 |
+| Token Forge 每日成本 | $5.00 |
+| 全站每日成本 | $10.00 |
+| 匿名用户 / Token Forge / 全站每日请求 | 12 / 200 / 400 |
+| 60 秒内匿名用户 / Token Forge / 全站请求 | 2 / 20 / 40 |
+| 匿名用户 / Token Forge / 全站并发 | 1 / 4 / 6 |
+| 预留有效期 | 60 秒 |
+| 连续失败后熔断 | 5 次 |
+| 熔断打开时间 | 60 秒 |
+| 半开探针 | 1 个 |
+
+微美元是整数成本单位：`1 USD = 1,000,000 microUSD`，避免浮点金额累计误差。56,000
+Token 覆盖 AI Gateway 最多两次 Provider 尝试的最坏情况，而不是只覆盖最终成功的一次。
+P1-008 的服务端价格表必须用固定模型价格和最大尝试次数计算预留 Token 与预留成本；浏览器
+不能提交价格、模型、预留额或结算用量。
+
+运行配置只能收紧 Schema 中的预算、频率、并发和失败阈值，不能扩大上述硬边界。若调整真实
+模型、最大尝试次数或价格，必须先验证单次成本上限仍覆盖最坏情况，再发布配置。
+
+## 匿名用户边界
+
+策略层只接受形如 `anon_<32-64 个安全字符>` 的 `actor_key`。它必须由 P1-008 在服务端
+通过签名匿名会话或带密钥的不可逆摘要派生，不能使用原始 IP、Cookie、User-Agent、邮箱或
+仓库标识。密钥、原始标识与映射关系不得进入策略快照。
+
+`actor_key` 是滥用控制标识，不是登录账户，也不能用于跨产品画像。公开响应不会返回它。
+
+## 准入、预留与结算
+
+每个请求执行以下状态机：
+
+1. 验证固定 `lab_id`、`operation`、UUID、匿名用户键、服务端时间和预留额；
+2. 清理过期预留与限流窗口，拒绝时间回退和重复 `request_id`；
+3. 依次检查熔断、滑动限流、并发和 UTC 日预算；
+4. 在调用 Provider 前，按最坏情况同时预留 Token 和微美元，并增加请求次数；
+5. 成功后用服务端汇总的所有 Provider 尝试实际 Token 与成本结算，退回未使用差额；
+6. Gateway 失败、进程中断或 60 秒未结算时保留全额预留，防止通过崩溃、超时或重试绕过
+   成本上限；
+7. 实际用量超过预留时失败关闭、保留全额预留，并把该次执行记为熔断失败。
+
+重复请求 ID 不会再次预留。已结算 ID 保留 24 小时的有限去重标记；重复结算是幂等空操作。
+日请求数不会因成功结算而退回，避免用大量低 Token 请求绕过频率边界。
+
+## 熔断
+
+以下调用后失败会增加连续失败数：
+
+- Provider 限流或预算拒绝；
+- Provider 超时或不可用；
+- Provider 响应无效、截断或超大小；
+- 输出命中安全策略；
+- Gateway 内部失败。
+
+连续 5 次后，`token-forge.plan-v1` 熔断 60 秒。到期后只允许一个半开探针：成功则关闭并
+清零连续失败；失败或预留超时则重新打开。输入合同错误和请求体超限不代表 Provider
+故障，不计入熔断。
+
+## 安全失败映射
+
+| 内部拒绝 | Gateway 错误码 | 页面行为 |
+| --- | --- | --- |
+| 日 Token、成本或请求预算耗尽 | `budget_exhausted` | 保留模板计划 |
+| 滑动限流或并发已满 | `rate_limited` | 保留模板计划，可稍后重试 |
+| 熔断已打开或探针占用 | `provider_unavailable` | 保留模板计划，可稍后重试 |
+| 时间回退、无效上下文或重复 ID | `invalid_request` | 保留模板计划 |
+
+公共失败只包含错误码、是否可稍后重试、最多 3,600 秒的 `retry_after_seconds` 和
+`attempt_count: 0`。内部作用域、匿名用户键、原始错误、请求正文和预算快照不会返回浏览器。
+
+## 状态与持久化边界
+
+策略快照只允许：
+
+- UTC 日桶中的 Token、微美元和请求计数；
+- 不可逆匿名用户键；
+- 请求 UUID、时间戳和预留数值；
+- 限流时间戳与熔断状态。
+
+快照有 256 KiB 上限、字段白名单、记录数上限和时间单调校验。目标、Prompt、计划、仓库
+URL、Owner、文件路径、正文、IP、Cookie、User-Agent、Provider 原始错误和密钥都不在合同
+内。
+
+P4-004 只提供可序列化状态机。P1-008 必须在单个原子持久化边界内完成“读取快照 → 准入或
+结算 → 写回快照”，否则多实例并发会突破预算。刚完成连接、部署或迁移时也不能把空内存
+Ledger 当成生产预算存储。
+
+## 验证
+
+合成测试覆盖：
+
+- 策略 Schema、未知字段、硬上限和作用域顺序；
+- Token、微美元、请求、滑动窗口和并发边界；
+- 成功退款、失败全额计费、超时预留和重复请求；
+- 关闭、打开、单探针半开、恢复和重新打开；
+- 快照恢复、时间回退、敏感字段缺失和安全 Gateway 失败；
+- 无网络、日志或持久化副作用。
+
+测试不使用真实用户标识、仓库内容、Provider、价格、密钥或生产数据。
+
+## P1-008 接入清单
+
+P1-008 仍需完成：
+
+1. 选择服务端运行时和原子持久化适配器；
+2. 通过服务端秘密派生可轮换匿名用户键；
+3. 固定 Provider、模型、指令、价格表和最大尝试次数；
+4. 在每次 Provider 调用前预留所有尝试的最坏成本；
+5. 汇总每次 Provider 尝试的可信可计费用量后结算；
+6. 把预算、限流和熔断失败接回 P1-004 的模板降级；
+7. 使用合成 Provider 做并发、重启、跨 UTC 日期和故障恢复测试；
+8. 经过 Preview 验证后再由人工触发 Production 发布。
+
+在这八项完成前，正式页面不得调用真实模型。

docs/token-forge-roadmap.md

@@ -21,9 +21,10 @@ Token Forge 已有版本化输入/计划合同、确定性模板、公开 GitHub
 Provider-neutral AI 规划核心、Markdown / GitHub Issue 导出核心和可用的 Alpha 页面。
 
 当前页面已接通“输入 → 本地模板 → 导出”路径和可选的公开仓库覆盖证据；仓库失败不会
-阻断模板。AI 规划尚未进入正式页面，用户还不能编辑、锁定和重排计划，也没有面向 Coding
-Agent 的完整执行包、生产 AI 预算、端到端质量基准或真实转化数据。因此 MVP 核心虽已存在，
-产品闭环仍未完成。
+阻断模板。P4-004 已提供 Provider-neutral 的生产 AI 日 Token/微美元预算、匿名用户限流、
+并发预留和熔断状态机，但尚无原子持久化、真实 Provider 和页面入口。用户还不能编辑、锁定
+和重排计划，也没有面向 Coding Agent 的完整执行包、端到端质量基准或真实转化数据。因此
+MVP 核心虽已存在，产品闭环仍未完成。
 
 ## 执行顺序
 
@@ -50,6 +51,9 @@ Agent 的完整执行包、生产 AI 预算、端到端质量基准或真实转
 P1-008 必须依赖 P4-004，不能先上线无预算边界的真实模型调用。P4-003 只能在核心产品闭环稳定
 后接入，避免为了收集数据提前扩大隐私面。
 
+P1-007 与 P4-004 已完成；当前唯一推荐任务是 P1-008。P4-004 的内存状态机不能直接视为
+生产限流存储，P1-008 必须先提供原子持久化与可信的全尝试成本结算。
+
 ## “特别完善”的完成门槛
 
 只有同时满足以下五类门槛，Token Forge 才视为达到当前战略要求：

labs/token-forge/README.md

@@ -57,6 +57,12 @@ Token Forge 现为仓库唯一产品开发主线。公开仓库接入、生产 A
 任务去重规则。Secret 输入、超时、不可用或无效输出都会整体丢弃，并返回 P1-002 模板计划。
 P1-004 仍不接真实 Provider、HTTP API 或页面。
 
+[P4-004 AI 流量与成本策略](../../docs/token-forge-ai-traffic-policy.md) 已增加匿名用户、
+Token Forge 与全站三层日 Token/微美元预算、60 秒滑动限流、并发预留和熔断状态机。它
+按最多两次 Provider 尝试预留最坏成本，成功后退款，失败或预留超时全额计费；快照不含
+目标、Prompt、仓库 URL、路径或正文。当前仍没有生产 Provider、端点和原子持久化，
+P1-008 完成前页面保持模板模式。
+
 ## Markdown / GitHub Issue 导出
 
 [P1-005 导出核心](../../docs/token-forge-export.md) 只接收通过 v1 合同的结构化计划，生成

labs/token-forge/fixtures/token-forge-ai-policy.valid.json

@@ -0,0 +1,35 @@
+{
+  "schema_version": "1.0",
+  "lab_id": "token-forge",
+  "operation": "token-forge.plan-v1",
+  "max_request_billable_tokens": 56000,
+  "max_request_cost_microusd": 100000,
+  "daily_budgets": {
+    "actor_tokens": 224000,
+    "lab_tokens": 2240000,
+    "site_tokens": 5600000,
+    "actor_cost_microusd": 250000,
+    "lab_cost_microusd": 5000000,
+    "site_cost_microusd": 10000000,
+    "actor_requests": 12,
+    "lab_requests": 200,
+    "site_requests": 400
+  },
+  "rate_limit": {
+    "window_seconds": 60,
+    "actor_requests": 2,
+    "lab_requests": 20,
+    "site_requests": 40
+  },
+  "concurrency": {
+    "actor_in_flight": 1,
+    "lab_in_flight": 4,
+    "site_in_flight": 6
+  },
+  "circuit_breaker": {
+    "consecutive_failures": 5,
+    "open_seconds": 60,
+    "half_open_requests": 1
+  },
+  "reservation_ttl_seconds": 60
+}