[argszero]

Summary

Add the key-pool routing & failover strategy section to docs/architecture.md per host rant 2026-08-14T22:03:24 (key 池路由与故障转移策略定案 — 粘性选择 + 健康检查 + 有限切换).

Changes (docs/architecture.md, v0.1 → v0.2):

• New subsection 4.2.1 路由与故障转移策略 under §4.2 Key 池, recording the 7 finalized rules:
  1. Random initial selection — first request for model M picks a random healthy key
  2. Sticky — subsequent requests from that user reuse the same key until unavailable
  3. Unavailability determination — key delisted (deleted/paused) or erroring (upstream error / auth failure / quota exhausted)
  4. Silent failover — on unavailability, silently pick the next healthy key (no interruption)
  5. Switch limit — at most 3 switches per routing; if all fail → error "该模型暂无可用 key"
  6. Health marking — an erroring in-use key is marked unhealthy for 5 seconds (excluded from selection)
  7. Health-first — always prefer currently healthy keys (unhealthy keys rejoin after the 5s cooldown)
• Worked example: A requests M → random B1 → sticky reuse → B1 errors → silent B2 (1st) → B2 errors → B3 (2nd) → success; if all 3 fail → error

Related Issue

No issue — host rant 2026-08-14T22:03:24 (argszero/aitokenpool).

Changes

• 功能/修复说明：architecture doc gains routing & failover strategy (v0.2)
• 涉及配置/数据结构的改动已同步示例文件：N/A — docs only

Tests

• cargo test 全部通过 (1 passed)
• cargo fmt --check 通过
• 新增/更新了单元测试（如适用）：N/A — docs-only change

Checklist

• 分支命名符合约定：docs/key-routing
• Commit message 使用 Conventional Commits：docs(arch): routing & failover strategy — random/sticky/health, max 3 switches (v0.2)
• 单一职责，改动最小化