chore: initial import

prd/PM审核报告.md

@@ -0,0 +1,93 @@
+## PM 审核报告
+
+### 总体评级：B
+
+**评级说明**：PRD 整体结构完整，用户旅程覆盖较全，AC 基本满足 SMART 原则，商业化闭环有框架但缺乏财务量化。存在 1 处 P0 级范围不一致、1 处 P0 级错误码冲突，以及工期估算严重偏乐观的问题。建议在进入 TechLead 评审前修复 P0/P1 问题。
+
+---
+
+### 优点
+
+1. **用户旅程覆盖完整**：主流程（监控看板、配置审计回滚、告警处置）+ 异常流程（自愈失败、告警飙升、回滚失败）+ 边缘流程（无人处理告警、数据源丢失、误触发变更）全部覆盖，并配有 F-1~F-8 的独立失败路径表。
+2. **AC 量化程度高**：12 条 AC 中，90% 以上包含明确的数值约束（如 <2s、<3s、30s、90 天、50 条规则、100 条/页），可直接转化为 QA 测试用例。
+3. **In/Out of Scope 边界清晰**：明确排除了下游大模型监控、基础设施层监控、AI 自动扩缩容、外部监控系统整合，避免范围蔓延。
+4. **技术约束明确**：统一 Go 1.22+ / 标准库 net/http / pgx / go-redis，禁止引入 Gin/Echo；支持独立运行与集成运行双模式；数据库表名强制 `ai_ops_` 前缀，减少集成冲突。
+5. **发布策略安全**：分 4 阶段上线，自愈规则强制"沙盒模式"验证（>=10 次模拟），并设计了一键关闭自愈的权限开关，风险控制意识强。
+6. **竞品分析有价值**：对 LiteLLM、Sub2API、NewAPI、FreeRide 的对标分析到位，差距分析直接转化为产品机会点。
+
+---
+
+### 发现问题（按严重度分类）
+
+#### P0 — 阻塞性问题（必须修复后才能进入开发）
+
+| 编号 | 问题 | 影响 | 位置 |
+|------|------|------|------|
+| P0-1 | **范围冲突：供应商智能切换未在 PRD 正文 In Scope 中明确纳入，但功能清单将其作为 Phase 3 核心模块（3.4，含 16+ 个任务）** | 该功能涉及自动路由变更、供应商探测、Fallback 链管理，本质上属于"自动化配置变更/扩容决策"，与 Out of Scope 第 3 条"不做自动扩容决策"存在擦边风险；且 In Scope 第 1 条明确"不含下游大模型服务"，而供应商切换直接依赖下游供应商接口。若不加明确界定，开发阶段极易产生范围争议。 | PRD §3 In Scope / 功能清单 模块 3.4 |
+| P0-2 | **错误码不一致**：PRD 场景 F 与 AC-8 规定回滚失败错误码为 `OPS_AUD_4101`，但功能清单 3.3.2 使用 `AUDIT_ROLLBACK_TARGET_LOST` | 接口契约冲突，前后端/QA 无法对齐，将导致集成测试失败。 | PRD §4 场景 F、§5 AC-8 / 功能清单 3.3.2 |
+| P0-3 | **工期估算严重偏离实际**：功能清单列出 138 个任务，总估算仅 18 人天（平均每个任务不足 1 小时），未包含联调、集成测试、Bug 修复、文档、评审、返工时间 | 该估算极可能导致项目延期、资源不足、质量下降。按行业常规，Go 后端 + 前端 + 测试的完整交付，138 个任务至少需要 6~8 周（30~40 人天）以上。 | 功能清单 "任务估算汇总" |
+| P0-4 | **自愈动作"重启实例"在功能清单中遗漏具体任务**：PRD AC-6 明确列出"重启实例"为可选自愈动作之一，但功能清单 3.1.2 的自愈执行后端任务仅覆盖"切换备用路由、限流、触发脚本"，未提及"重启实例"的实现任务 | 功能遗漏，QA 无法验收该自愈动作。 | PRD §5 AC-6 / 功能清单 3.1.2 |
+
+#### P1 — 重要问题（强烈建议修复）
+
+| 编号 | 问题 | 影响 | 位置 |
+|------|------|------|------|
+| P1-1 | **双重失败判定线**：PRD §2 定义"开发期间任何一周内告警噪声率 >20% 或自愈规则误触发导致生产事故，即判定失败"；§8.3 又定义"上线 30 天内 MTTR 未下降至 <20min / 自动化覆盖率 <30% / 噪声率 >15% / 自愈误触发 1 次"进入救援模式 | 两条判定线的时间边界（开发期 vs 上线后）、指标阈值（20% vs 15%）、触发条件不统一，团队无法判断应以哪条为准。 | PRD §2 成功定义、§8.3 失败判定线 |
+| P1-2 | **In Scope 使用"包括但不限于"**：第 1 条"包含但不限于：gateway/..." | "包括但不限于"是范围管理中的高风险词汇，为后续需求蔓延留下口子。应改为封闭列表，或明确"仅包含以下模块"。 | PRD §3 In Scope #1 |
+| P1-3 | **通知渠道定义不一致**：PRD AC-4 要求"Webhook、邮件、飞书/企业微信至少 2 种"，但功能清单 2.3.2 和 3.4.3 出现了"钉钉"，且备份切换链为 Webhook→邮件→飞书→企微 | 若最终未实现钉钉，功能清单需同步删除；若实现，PRD AC-4 需更新。 | PRD §5 AC-4 / 功能清单 2.3.2、3.4.3 |
+| P1-4 | **AC-7 "审计日志必须不可篡改"缺乏技术实现定义**：未说明是通过 WORM 存储、哈希链、数字签名还是仅通过数据库层禁止 UPDATE/DELETE 来实现 | QA 无法验证"不可篡改"，不同实现方式的成本和合规等级差异巨大。 | PRD §5 AC-7 |
+| P1-5 | **AC-8 "操作前值有效"定义模糊**：未明确"有效"的判定标准（非空？JSON 可解析？符合当前 Schema？） | 可能导致回滚接口在边界情况下行为不一致。 | PRD §5 AC-8 |
+| P1-6 | **级联故障回退（F-6）未在 AC 中体现**：PRD §6 F-6 描述自愈级联故障时"自动恢复上一步操作前的状态"，但 AC-6 仅提到"若未解除则升级为人工告警"，未要求验证级联回退能力 | 功能清单 3.1.3 有任务，但 AC 缺失，QA 无法据此验收。 | PRD §6 F-6 / §5 AC-6 |
+| P1-7 | **容量预测算法缺乏可测试标准**：AC-9 要求"按当前增长率预测触达资源上限时间"，但注明"仅供参考，不自动执行扩容"，且未定义预测准确率、置信区间或最大可接受偏差 | "仅供参考"导致该功能无法被 QA 有效验收，开发完成后可能沦为无法量化的"演示功能"。 | PRD §5 AC-9 |
+| P1-8 | **缺少 UI/UX 最低兼容性要求**：PRD 和功能清单均未规定浏览器支持范围、移动端适配策略、最低分辨率 | 前端工程师缺乏约束，可能在交付后因兼容性问题返工。 | PRD 全文 |
+| P1-9 | **角色权限矩阵过粗**：AC-12 仅定义 3 个角色的一句话权限，缺少页面级/API 级权限对照表（如"运维人员能否导出审计日志？""查看者能否导出 CSV？"） | 功能清单 G1 中"管理员（可管理用户）"超出了 PRD 定义（PRD 未提用户管理），进一步加剧不一致。 | PRD §5 AC-12 / 功能清单 G1 |
+
+#### P2 — 改进建议（建议纳入后续迭代）
+
+| 编号 | 问题 | 建议 |
+|------|------|------|
+| P2-1 | 商业化闭环缺少 ROI 量化模型 | 补充"当前运维人力成本 = X 人月 × Y 元/人月，目标释放 40% 后节省 Z 元/月"的计算示例，使北极星指标与财务指标挂钩。 |
+| P2-2 | 竞品分析中的技术设计模式未融入 PRD 正文 | 将 `CustomBatchLogger`、`DigestEntry`、`DualCache` 等设计模式从竞品分析报告迁移到 PRD 技术约束或架构建议章节，避免设计阶段遗漏。 |
+| P2-3 | 发布策略缺少阶段门控的量化验收标准 | 阶段 2 进入阶段 3 的条件目前是"无 P1 以上告警 72h"，建议补充"告警噪声率 <10%""通知渠道成功率 >95%"等可量化门控。 |
+| P2-4 | 未定义生产部署拓扑 | 建议明确是单集群还是多集群部署，自愈动作"重启实例"在 K8s 与裸金属环境下的实现差异巨大。 |
+| P2-5 | 审计日志 90 天保留期未评估存储成本 | 高并发场景下全量 JSON 审计日志的存储量可能极大，建议补充日志压缩/归档策略或存储成本上限。 |
+| P2-6 | PRD 自检清单声称"没有使用优化、支持、友好、尽量、快速等模糊词"，但正文中仍存在"等""等相关指标"等模糊表述 | 建议将 In Scope 中的"等"字去除，改为封闭列表；功能清单中的"等相关能力"也需同步清理。 |
+
+---
+
+### 改进建议（优先级排序）
+
+1. **立即修复 P0 问题**：
+   - 在 PRD §3 In Scope 中明确加入"供应商智能切换（含健康探测、Fallback 链、策略化路由）"或将其移入 Out of Scope；若纳入，需在 AC 中补充对应的验收标准。
+   - 统一回滚失败错误码为 `OPS_AUD_4101`，功能清单同步修正。
+   - 重新进行工时估算，建议采用"任务 × 复杂度系数 + 联调缓冲（20%）+ 风险缓冲（15%）"的方式，输出 30~40 人天的 realistic estimate。
+   - 在功能清单 3.1.2 中补充"重启实例"自愈动作的实现任务（如调用 K8s API 或主机 agent）。
+
+2. **本周内修复 P1 问题**：
+   - 合并/统一失败判定线，建议按"上线后 30 天"为统一时间窗口，阈值取更严格的版本（噪声率 <15%）。
+   - 删除 In Scope 中的"包括但不限于"，改为封闭枚举；如确需扩展，规定"新增范围需经 PM+TechLead 双签"。
+   - 明确 AC-4 通知渠道的最终列表（是否含钉钉），并同步更新功能清单的备用切换链。
+   - 在 AC-7 中补充"不可篡改"的实现方式（建议：数据库层禁止 UPDATE/DELETE + 应用层只追加写入）。
+   - 补充 UI 最低兼容性要求（如：Chrome/Firefox/Edge 最新 2 个版本，最小宽度 1280px）。
+   - 细化角色权限矩阵到 API 级别，建议以表格形式列出各角色对关键接口的 CRUD 权限。
+
+3. **TechLead 阶段前补充**：
+   - 将竞品分析中的设计模式建议提炼为 PRD 架构约束章节（如告警批量化、摘要窗口、双缓存机制）。
+   - 为容量预测（AC-9）补充可测试标准，例如"预测值与实际值的平均绝对百分比误差（MAPE）<30%"或至少提供趋势方向判断准确率。
+   - 明确生产部署拓扑（K8s vs 裸金属 vs 混合），影响自愈动作设计。
+
+---
+
+### 审核结论
+
+| 维度 | 评分 | 说明 |
+|------|------|------|
+| 用户旅程完整性 | A- | 主/异/边缘流程全覆盖，但级联回退未在 AC 中闭环 |
+| AC 可测试性 | B+ | 大部分量化精确，但"仅供参考""有效""不可篡改"等不可测试 |
+| In/Out of Scope 清晰度 | B | 主体清晰，但"包括但不限于"和供应商切换造成范围争议 |
+| 成功指标与失败判定 | B- | 指标量化，但存在双重标准，时间边界模糊 |
+| 商业化闭环 | B- | 有框架但缺 ROI 量化，外部收益链条弱 |
+| 功能清单一致性 | C+ | 与 PRD 存在错误码冲突、渠道不一致、任务遗漏、估算失真 |
+| 模糊词汇控制 | B+ | 主体控制良好，"等"字和"包括但不限于"需清理 |
+
+**建议行动**：修复 P0-1~P0-4 后，可进入 TechLead 评审；P1 问题建议在技术方案评审前同步闭环。

prd/PRD.md

@@ -0,0 +1,461 @@
+# 智能运维系统 PRD
+
+> 版本：v1.0
+> 负责人：PM
+> 目标读者：TechLead、QA、SRE、运营人员
+> 状态：待 TechLead 评审
+
+---
+
+## 1. 概述
+
+### 一句话价值
+通过自动化监控、告警辅助决策、故障自愈与配置变更管理，将立交桥平台的运维从人工排查转为机器主导的实时保障，降低 MTTR、减少人工成本、提升运行稳定性。
+
+### 用户问题
+1. 当前运维严重依赖人工定期检查日志，问题发现与处置耗时过长，MTTR 超过 30 分钟。
+2. 告警规则缺乏分类与阈值动态调整，导致要么漏告警、要么误告警爆炸。
+3. 故障发生时无自动恢复机制，必须等待运维人员手动参与，产生可避免的服务中断。
+4. 配置变更无审计追溯能力，回滚窗口不明确，引发过多次生产故障。
+5. 规模扩张中缺乏量化的容量管理视角，出现无计划的资源短缺。
+
+### 业务意义
+- 从 Demo 级运维向生产级运维过渡，建立可重复、可审计、可回滚的运维体系。
+- 在人员规模不增的前提下，支撑接入商家数、API 调用量与 Token 数量级的增长。
+
+---
+
+## 2. 目标
+
+### 业务目标
+1. 将平台核心故障 MTTR 从 >30min 压缩至 <10min。
+2. 自动化处理覆盖 P1/P2 级告警事件的 60%以上（含自愈和故障匿离）。
+3. 告警噪声率降低至 5% 以下（误告警 / 总告警数）。
+4. 实现 100% 生产配置变更的审计追溯，回滚时间窗口 <5min。
+
+### 用户目标
+| 用户 | 目标 |
+|---|---|
+| SRE | 不再 7x24 手动守候日志，告警可触达、可分类、可动作化 |
+| 运营人员 | 缺陷发现后能在同一平台完成定位、分析、处置，无需切换多套工具 |
+| 平台管理员 | 对任何配置变更能看到影响范围、执行记录、快速回滚能力 |
+| 技术负责人 | 获取量化的运维健康度指标，支撑容量与稳定性决策 |
+
+### 成功定义
+- 必要条件：运维主控台可访问、监控数据可查、告警规则可配。
+- 充分条件：自愈规则生效、告警噪声率 <5%、审计日志完整。
+- 失败判定：开发期间任何一周内告警噪声率 >20%或自愈规则误触发导致生产事故，即判定失败。
+
+---
+
+## 3. 范围
+
+### In Scope
+1. 立交桥平台本身的运行时监控（不含下游大模型服务），包含但不限于：
+   - gateway/ 请求量、延迟、错误率、降级/稳定性规则命中率
+   - supply-api/ 供应商健康状态与审计异常
+   - platform-token-runtime/ 令牌耗尽、资源约束触发、异常恢复周期
+2. 告警规则引擎：多维度阈值、分级告警（P0/P1/P2/P3）、告警抑制与聚合。
+3. 故障自愈引擎：自动重启、切换路由、限流、隔离异常节点。
+4. **供应商智能切换（In Scope）**：含供应商健康探测、故障时的多级 Fallback 切换、策略化路由调度、切换后的健康状态监测与回滚。
+5. 配置管理与审计：配置变更审计日志、版本化、回滚。
+6. 容量视图：以 Token 数量、QPS、响应延迟、资源利用率为核心指标的容量主板。
+7. 日志/指标查询与下钻：支持按时间范围、服务、错误码、用户维度筛选。
+
+### Out of Scope
+1. 下游大模型服务的监控与告警（如 OpenAI、Claude 本身的稳定性）。
+2. 基础设施层监控（如物理机器 CPU/内存/磁盘，由云厂商或 Prometheus Node Exporter 覆盖）。
+3. **AI 负载预测/自动规模扩缩（本阶段仅提供容量视图与阈值提示，不做自动扩容决策）。**
+   - 供应商智能切换（如故障时切换到备用供应商）属于故障应对策略，In Scope。
+   - 自动规模扩缩（如 K8s HPA 类似的自动扩缩容决策）属于资源调度策略，Out of Scope。
+4. 外部监控系统（如 Datadog、New Relic）的整合，仅提供标准 Prometheus 格式接口供自取。
+
+### 假设与依赖
+1. 假设已有 Prometheus 或类似时序数据库存储指标，可接受定期 PromQL 查询。
+2. 假设平台日志已统一格式化，可通过标准化查询接口读取。
+3. 假设 gateway/internal/metrics/ 与 gateway/internal/alert/ 现有模块的接口契约在本项目中可延续或克隆。
+4. 依赖 supply-api/ 的供应商健康检查接口与审计日志接口。
+5. 依赖 platform-token-runtime/ 的运行时状态与异常恢复状态接口。
+
+---
+
+## 4. 用户场景
+
+### 主流程
+
+#### 场景 A：监控实时看板查看平台健康状态
+1. SRE 登录运维主控台。
+2. 首页展示实时 QPS、平均延迟、P99 延迟、错误率、活跃供应商数量、异常告警数量。
+3. SRE 点击任意指标卡片，下钻至分钟级趋势图与按服务/路径/供应商的分布。
+4. 如果某指标超过预设阈值，卡片变红并显示最近 3 条相关告警摘要。
+
+#### 场景 B：配置审计与回滚
+1. 平台管理员修改供应商接口地址或路由规则。
+2. 系统自动记录操作人、操作前后值、时间戳、IP 地址，并生成唯一审计 ID。
+3. 管理员可以在审计日志中搜索该变更。
+4. 发现变更引发异常后，管理员在审计页面选择该记录执行回滚，系统在 60 秒内恢复原值并验证恢复后状态。
+
+#### 场景 C：告警接收与处置
+1. 监控引擎检测到 P1 告警触发条件（如某供应商错误率 >10%持续 2min）。
+2. 告警在 30 秒内通过配置的通知渠道（Webhook/邮件/飞书/企业微信）发送给负责人。
+3. 自愈引擎判断该 P1 告警是否存在已配置自愈动作：
+   - 若有：执行自愈（如切换备用供应商、限流、重启异常实例），并在事件中记录动作结果。
+   - 若无：仅发送通知，等待人工处理。
+4. SRE 在控台中对该告警进行确认/忽略/规避，并填写处置结果。
+5. 告警事件自动关闭或转为持续告警，根据反馈调整当前期的实时效果。
+
+### 异常流程
+
+#### 场景 D：自愈动作失败
+1. 自愈引擎尝试执行自愈动作（如切换供应商接口）。
+2. 动作执行失败（API 返回非 200 或超时）。
+3. 系统在 10 秒内尝试重试 1 次，若仍失败，停止自动尝试并升级为 P0 人工告警（电话/短信）。
+4. 记录失败原因与日志，保留事件状态供人工排查。
+
+#### 场景 E：告警飙升（波浪式告警）
+1. 某基础故障导致成百上千个服务实例同时触发告警。
+2. 告警引擎检测到同一资源/服务在 1 分钟内触发 >20 条告警。
+3. 自动触发聚合：生成一条 "集群告警"，将细节收拢为附件，停止单条通知爆炸。
+4. SRE 在控台中批量确认/忽略/属于同一根因的告警。
+
+#### 场景 F：回滚失败
+1. 管理员发起回滚。
+2. 回滚目标值已被后续修改覆盖（关联记录不存在或已被删除）。
+3. 系统拒绝执行，返回明确错误码 `OPS_AUD_4101`（回滚目标不存在）。
+4. 记录回滚失败事件，告警通知技术负责人。
+
+### 边缘流程
+
+#### 场景 G：无人处理的持续告警
+1. P2 告警持续 2 小时未被确认。
+2. 系统自动将该告警升级为 P1，并通知上级负责人。
+
+#### 场景 H：监控数据源丢失
+1. 指标采集器在 5 分钟内未收到任何新数据点。
+2. 控制台显示 "数据源丢失"标识，不显示过期数据，触发 P2 级别的内部告警。
+3. 恢复后自动补入缺失时段的空值标记，不伪造数据。
+
+#### 场景 I：运维人员误触发配置变更
+1. 管理员提交一个将某供应商日请求上限从 10000 降为 10 的变更。
+2. 系统检测到该变更带来的影响面 > 预设阈值（比如触发将导致 90% 流量被拒绝）。
+3. 在审计日志中标记该变更为 "高风险"，并在执行前弹窗警告管理员需要二次确认。
+
+### 用户故事
+
+- 作为 SRE，我希望在午夜收到有效告警而不是噪音，以便在 10 分钟内完成定位和处置，避免影响生产。
+- 作为运营人员，我希望能在同一个控制台查看所有服务的健康状态和日志，而不需要登录多套系统。
+- 作为平台管理员，我希望任何配置变更都有日志和回滚能力，让我在发生问题时能快速恢复而不会黄乱找原始值。
+- 作为技术负责人，我希望看到量化的运维健康指标，以便在要求增量资源时有数据支撑。
+
+---
+
+## 5. 验收标准（AC）
+
+### AC-1 实时监控看板
+- 当访问运维主控台时，首页加载时间 <2s。
+- 首页必须显示以下 6 个指标数值：当前 QPS、平均响应延迟(ms)、P99 响应延迟(ms)、5xx 错误率(%)、活跃供应商数量、未关闭告警数量。
+- 每个指标卡片需在数据更新后 15s 内刷新显示。
+
+### AC-2 指标下钻
+- 点击任何指标卡片后，页面展示该指标过去 1 小时的分钟级趋势图。
+- 趋势图支持按 `service`（gateway/supply-api/platform-token-runtime）、`path`（URL path）、`supplier`（供应商 ID）维度下钻分割。
+- 下钻结果查询时间 <3s。
+
+### AC-3 告警规则配置
+- 控制台支持创建、编辑、启用、禁用告警规则。
+- 单条规则必须包含：规则名称、监控指标、阈值类型（>、<、=、匹配正则）、持续时间(min)、级别（P0/P1/P2/P3）、通知渠道。
+- 规则变更后 30s 内生效，无需重启服务。
+- 最少支持同时运行 50 条告警规则。
+
+### AC-4 告警通知触达
+- P0/P1 级告警必须在触发后 30s 内完成通知发送。
+- P2 级告警必须在 120s 内完成通知发送。
+- 通知渠道必须支持 Webhook、邮件、飞书/企业微信至少 2 种。
+- 通知模板必须包含：告警级别、规则名称、触发时间、当前值、阈值、事件 ID、查看链接。
+
+### AC-5 告警聚合与抑制
+- 当同一资源/服务在 1 分钟内触发 >20 条告警时，系统必须自动生成 1 条集群告警，停止单条通知爆炸。
+- 集群告警的通知内容必须包含：累计数量、涉及规则列表、时间范围。
+- 抑制周期：同一规则同一目标在 5 分钟内只发送 1 次告警（除非级别升级）。
+
+### AC-6 自动自愈
+- 系统必须支持为每个告警规则配置可选的自愈动作：无、切换备用路由、限流、重启实例、触发程序化脚本。
+- 自愈动作必须在告警触发后 60s 内执行完成（含重试 1 次的时间）。
+- 自愈执行结果（成功/失败/拒绝）必须记录在告警事件中。
+- 自愈动作触发后，监控必须在 2 分钟内评估是否解除告警条件，若未解除则升级为人工告警。
+
+### AC-7 配置审计日志
+- 任何对生产配置的增、删、改操作必须在 1s 内生成审计日志记录。
+- 审计日志必须包含：唯一 ID、操作人、操作类型、目标资源类型与 ID、操作前值(JSON)、操作后值(JSON)、时间戳(到毫秒)、IP 地址、请求 ID。
+- 审计日志必须不可篡改，存储保留期 >=90 天。
+- 控制台必须支持按时间范围、操作人、资源类型、关键词筛选查询，结果返回时间 <3s。
+
+### AC-8 配置回滚
+- 对于任何审计日志记录，只要目标资源仍存在且操作前值有效，必须支持执行回滚。
+- 回滚执行时间必须 <60s，并在执行前显示所有会被覆盖的子资源列表。
+- 回滚必须生成新的审计记录，关联原始操作 ID。
+- 回滚失败时必须返回明确错误码，不得静默失败。
+
+### AC-9 容量主板
+- 容量主板必须显示过去 7 天的 Token 数量、QPS、P99 延迟、各供应商资源利用率趋势。
+- 必须对每个服务标出当前负载等级：正常/警告/过载，判定依据可配置阈值。
+- 提供 "按当前增长率预测触达资源上限时间"的算法结果（仅供参考，不自动执行扩容）。
+
+### AC-10 日志/指标查询
+- 控制台必须支持按时间范围、服务名称、HTTP 状态码、错误码、用户 ID、供应商 ID、关键词筛适日志。
+- 日志查询结果支持分页，单页最大 100 条，首页返回时间 <3s。
+- 支持将日志结果导出为 CSV 文件，单次导出上限 10000 条。
+
+### AC-11 监控数据保存
+- 原始指标数据必须保留 >=7 天，用于短期查询与告警评估。
+- 分钟级聚合数据必须保留 >=30 天，用于趋势分析。
+- 小时级聚合数据必须保留 >=90 天，用于容量规划与月度报告。
+
+### AC-12 角色与权限
+- 必须支持以下角色及其基本权限控制：
+  - 查看者：可查看监控看板、日志、告警事件，不可修改配置。
+  - 运维人员：可确认/忽略/规避告警，可管理告警规则，不可执行回滚。
+  - 管理员：可执行所有操作，包括回滚与高风险变更确认。
+
+---
+
+## 6. 边缘情况与失败路径
+
+| 编号 | 边缘/失败场景 | 系统行为 | 人工介入时机 |
+|---|---|---|---|
+| F-1 | 自愈动作重试均失败 | 停止自动尝试，升级为 P0 人工告警 | 立即，电话/短信通知 |
+| F-2 | 告警通知渠道失效（如 Webhook 8xx/5xx） | 记录发送失败，使用备用渠道（邮件→飞书→短信） | 三次切换后仍失败，通知 TechLead |
+| F-3 | 回滚目标已不存在 | 拒绝回滚，返回错误码 `OPS_AUD_4101` | 需要运维人员手动修复或联系开发人员 |
+| F-4 | 指标采集器连续 5min 无数据 | 显示数据源丢失标识，触发内部 P2 告警 | 检查采集器/网络/存储状态 |
+| F-5 | 审计日志存储满盘/写入失败 | 丢弃非关键字段或改为异步上报，不阻断业务操作 | 存储计量触发预警，SRE 扩容或清理 |
+| F-6 | 自愈动作触发后形成级联故障（如切换路由后导致新节点故障） | 自动恢复上一步操作前的状态（回退），然后升级为人工告警 | 立即，电话通知 |
+| F-7 | 监控数据库丢失（全面中断） | 控制台进入只读/降级模式，告警引擎依赖本地缓存持续运行 | 立即，检查存储层 |
+| F-8 | 实时看板指标计算结果超时 | 显示上次成功结果并标注时间戳，不等待当前请求 | 检查查询引擎性能或检索时间范围 |
+
+---
+
+## 7. 上线与运营准备
+
+### 发布策略
+- 阶段 1：监控看板 + 日志/指标查询。只提供可视化，不触发任何自动动作。
+- 阶段 2：告警规则引擎 + 通知渠道，告警只通知、不执行自愈。
+- 阶段 3：自愈引擎 + 审计回滚。
+- 阶段 4：容量主板与高级分析。
+
+### 灰度与回滚
+- 每个阶段必须在单个可控集群部署 >=72h，无 P1 以上告警才进入下一环境。
+- 自愈规则必须通过 "沙盒模式"验证：先在非生产环境模拟触发 10 次以上，确认动作结果符合预期后才允许关联生产告警规则。
+- 回滚能力必须在发布前进行 1 次演练，涉及至少 3 个不同资源类型。
+- 如阶段 3 中自愈规则出现误触发导致生产事故，立即停用自愈引擎（通过权限开关），所有告警退化为仅通知模式。
+
+### 埋点与监控
+- 必须实现以下事件埋点：
+  - `运维控制台页面加载`、`指标下钻`、`日志查询执行`、`告警规则创建/编辑/删除`、`告警确认/忽略/规避`、`自愈动作执行`、`自愈失败`、`回滚执行`、`回滚失败`。
+- 必须对自身监控层（指标采集器、告警引擎、通知发送器）进行健康检查，检查失败时触发内部 P2 告警。
+
+### FAQ（预先准备）
+| 问题 | 答案 |
+|---|---|
+| 告警通知没收到怎么办？ | 检查通知渠道配置中的接收地址/密钥；检查通知日志中的发送结果与失败原因。 |
+| 自愈动作为什么没有触发？ | 确认规则中已开启自愈动作并选择了具体动作；确认沙盒测试已通过。 |
+| 回滚为什么报错 `OPS_AUD_4101`？ | 该配置在变更后已被删除或覆盖，无法找到操作前状态，需要手动恢复。 |
+| 数据看板为什么卡住？ | 检查页面顶部是否有 "数据源丢失"标识；尝试缩小时间范围或筛选条件。 |
+| 如何避免误触发自愈规则？ | 在非生产环境测试自愈规则 10 次以上并验证结果正确后才关联生产告警规则。 |
+
+---
+
+## 8. 商业化与价值闭环
+
+### 收益路径
+1. 内部效益：减少运维人员 7x24 值班压力，释放人力至产品功能开发。
+2. 外部收益：提升平台 SLA 从 99.5% 至 99.9%，支撑企业客户签约与续费。
+3. 成本节省：将运维人工时长每月减少 40% 以上，可量化计算为节省人力成本。
+
+### 北极星指标
+- 平台核心故障 MTTR（从 >30min 到 <10min）。
+- 自动化处理覆盖率（目标 >=60%）。
+- 告警噪声率（目标 <5%）。
+
+### 失败判定线
+- 上线 30 天内 MTTR 未下降至 <20min。
+- 自动化覆盖率 <30%。
+- 告警噪声率 >15%。
+- 自愈规则误触发导致 1 次生产故障事件。
+任意一项触发，即进入救援模式。
+
+### 止损条件
+- 自愈引擎误触发导致 2 次以上生产事故：立即锁定自愈功能，退回仅通知模式，启动事故复盘。
+- 监控数据丢失超过 24h：停用依赖监控数据的自动化规则，级联退化至人工处理。
+
+---
+
+## 9. 依赖与风险
+
+### 技术依赖
+| 依赖 | 风险等级 | 备选方案 |
+|---|---|---|
+| Prometheus 或类似时序数据库 | 高 | 支持 VictoriaMetrics / Thanos 作为替代后端，提供存储适配层，不锁死单一存储 |
+| 通知渠道（Webhook/邮件/飞书） | 中 | 必须支持多渠道且自动切换，单渠道不得作为唯一依赖 |
+| 审计日志存储 | 中 | 主存储失败时转至本地文件缓存 + 异步上报，不阻断业务 |
+| supply-api/ 审计接口 | 中 | 如接口不可用，运维平台自己写审计记录，后续补同步 |
+
+### 业务风险
+1. 自愈规则设计不当导致正常流量被掩断或重定向，影响客户请求。
+2. 告警规则过于敏感或缺乏抑制，导致噪音爆炸，运营人员麻木对待真实故障。
+3. 回滚操作不当导致配置状态更深层次的损坏，如回滚了一个依赖于新配置的下游变更。
+4. 审计日志丢失导致故障定责和合规审查受阻。
+
+### 缓解措施
+1. 自愈规则必须经历 "沙盒模式"验证才能生效。
+2. 所有自愈动作支持通过权限开关一键关闭，关闭后所有告警退化为仅通知。
+3. 回滚执行前显示子资源影响范围，必须经二次确认。
+4. 审计日志存储采用主备双写，存储期 >=90 天。
+
+---
+
+## 10. 技术栈与集成约束
+
+### 统一技术栈
+本项目必须与立交桥主项目保持一致：
+- **语言**: Go 1.22+
+- **HTTP框架**: 标准库 `net/http` + 自定义中间件（禁止引入 Gin/Echo 等第三方框架，保持与 gateway/ 和 supply-api/ 的一致性）
+- **数据库**: PostgreSQL 15+ ，驱动 `jackc/pgx/v5`
+- **缓存**: Redis，客户端 `redis/go-redis/v9`
+- **配置**: YAML + Viper，环境变量覆盖敏感字段
+- **日志/审计**: 结构化日志，审计事件模型与 supply-api/ 一致
+- **错误码**: `{SOURCE}_{CATEGORY}_{CODE}` 格式，例如 `OPS_ALT_4001`
+- **健康检查**: `/actuator/health` 、 `/actuator/health/live` 、 `/actuator/health/ready`
+- **测试**: Go testing + testify，覆盖率门槛 domain ≥ 70%、service/handler ≥ 80%
+
+### 独立运行与集成运行
+本系统必须同时支持两种运行模式：
+
+| 模式 | 特征 | 部署方式 | 适用场景 |
+|------|------|---------|---------|
+| **独立运行** | 自有 `cmd/ai-ops/main.go`，独立数据库 schema，独立 docker-compose | `docker-compose up` 或单独容器 | 外部用户只需要运维能力，不想接入立交桥全套 |
+| **集成运行** | 作为 Go module 被 `gateway/` 或 `supply-api/` 引入，共享数据库连接池和配置，通过内部接口注册 | 编译时作为子模块编译，运行时挂载到立交桥主进程 | 立交桥用户希望获得一体化运维能力 |
+
+**集成约束**:
+- 独立运行时，系统必须提供完整的 HTTP API 和管理后台。
+- 集成运行时，系统必须提供 `IntegrationPlugin` 接口，允许主程序通过配置开关启用/禁用各模块。
+- 数据库 schema 必须使用独立的 `ai_ops_` 前缀，避免与主项目表名冲突。
+- 配置文件必须支持分离加载：独立运行时读取自己的 `config.yaml`，集成运行时合并到主项目配置。
+
+### NewAPI / Sub2API 适配支持
+本系统的核心能力必须能够对接 NewAPI 和 Sub2API 系统：
+- **监控数据推送**: 提供 Prometheus 格式的 `/metrics` 接口，NewAPI/Sub2API 可通过 Prometheus scrape 获取运维数据。
+- **告警回调**: 支持 Webhook 告警通知，NewAPI/Sub2API 可配置接收本系统的告警事件。
+- **自愈脚本扩展**: 自愈动作中的"触发程序化脚本"支持调用 NewAPI/Sub2API 的管理 API（如切换供应商、限流配置、重启实例）。
+- **独立部署时**: 通过配置文件指定 NewAPI/Sub2API 的管理端点地址和鉴权信息，本系统通过适配层与之交互。
+- **集成部署时**: 若立交桥 gateway/ 已接入 NewAPI/Sub2API，本系统通过 gateway/ 的内部路由接口操作上游状态。
+
+### 对外接口契约
+- 必须提供 OpenAPI 3.0 接口文档，确保 NewAPI/Sub2API 开发者可以独立接入。
+- 接口路径前缀默认为 `/api/v1/ai-ops/`，集成运行时可通过配置改为 `/internal/ai-ops/` 。
+
+---
+
+## 11. 阶段门控结论
+
+### 当前状态
+- 需求范围已明确界定，In Scope / Out of Scope 清晰。
+- 验收标准已精确到可测试粒度，包含时间、数值、错误码、状态等维度。
+- 异常流程、边缘流程、失败路径已全面覆盖。
+- 上线策略、灰度方案、回滚路径、埋点检查已明确。
+- 技术栈与集成约束已明确（统一 Go 标准库、独立/集成双模式、NewAPI/Sub2API 适配）。
+- 北极星指标与失败判定线已量化。
+- 依赖与风险已识别，缓解措施已制定。
+
+### 门控结论
+可进入 TechLead 阶段。
+
+> 备注：TechLead 阶段需要完成的事项
+> 1. 确认现有 gateway/internal/metrics/ 与 gateway/internal/alert/ 的契约可延续性。
+> 2. 确认存储层技术选型（Prometheus / VictoriaMetrics / 自建时序库）。
+> 3. 确认通知渠道具体实现方案（Webhook / 飞书 / 邮件）。
+> 4. 确认审计日志与回滚是否复用 supply-api/ 既有审计能力还是独立实现。
+> 5. 确认角色权限体系是否复用平台统一认证系统。
+
+---
+
+## 自检清单
+
+- [x] 已明确真实目标，不是只复述功能
+- [x] 已写清 In Scope / Out of Scope
+- [x] 每个 AC 都可被 QA 或测试用例直接验证
+- [x] 已覆盖异常流、边缘流与失败路径
+- [x] 已补齐上线、运营、监控、回滚要求
+- [x] 已定义商业化/价值闭环
+- [x] 已明确成功指标与失败判定线
+- [x] 已明确当前可进入 TechLead 阶段
+- [x] 没有使用"优化、支持、友好、尽量、快速"等模糊词替代明确要求
+
+---
+---
+
+## 附：供应商智能切换（参考 FreeRide 思路）
+
+### 背景
+
+[FreeRide](https://github.com/openclaw/skills/tree/main/skills/shaivpidadi/free-ride) 是 OpenClaw 的一个 Skill 插件，核心功能：
+- 实时拉取 OpenRouter 免费模型列表，按 ELO 评分排序
+- 自动选择最强模型作为主模型
+- 配置 5 个高质量备用模型作为 Fallback 链
+- 主模型限速 → 自动切换下一个，用户无感知
+- 非破坏性配置更新，只改 model 相关字段
+
+FreeRide 的设计哲学（自动选择 + 智能降级）对 AI-Ops 的供应商切换场景有直接参考价值。
+
+### 智能供应商切换 vs FreeRide
+
+| 维度 | FreeRide | AI-Ops 供应商切换 |
+|------|----------|-------------------|
+| **目标用户** | 个人用户/极客 | 企业运维团队 |
+| **模型来源** | OpenRouter 免费模型 | 多供应商中转 API |
+| **核心价值** | 零成本用最强模型 | 供应商故障无感切换 |
+| **Failover 粒度** | 模型级别 | 供应商级别 |
+| **切换策略** | 固定轮询 | 成本优先/质量优先/延迟优先/手动 |
+| **监控告警** | 无 | 多渠道告警 + 运维大盘 |
+| **用量统计** | 无 | 成本分摊到部门/项目 |
+| **自愈能力** | 仅切换 | 切换 + 通知 + 锁定 + 升级 |
+
+### 供应商切换策略
+
+| 策略 | 决策依据 | 适用场景 |
+|------|----------|----------|
+| **成本优先** | input_cost + output_cost 最低 | 预算敏感型业务 |
+| **质量优先** | 最近 24h 成功率最高 | 高可用要求业务 |
+| **延迟优先** | 最近 probe 响应时间最低 | 低延迟要求业务 |
+| **手动** | 每次切换需人工确认 | 高风险变更管控 |
+
+### 设计约束（继承 HLD）
+
+- 切换后冷却期默认 300s，防止震荡（同一供应商反复切换）
+- 每次切换写入审计日志（切换时间、原供应商、目标供应商、切换原因）
+- 供应商配置更新采用原子替换（写临时文件 → 验证 → 原子替换），防止配置损坏
+- 切换执行后立即验证新供应商可服务性，失败则回退并升级告警
+
+### 参考实现
+
+供应商探针任务（每 5 分钟执行）：
+```go
+type SupplierProbe struct {
+    SupplierID  string    `json:"supplier_id"`
+    ProbeAt     time.Time `json:"probe_at"`
+    LatencyMs   int       `json:"latency_ms"`
+    ErrorRate   float64   `json:"error_rate"`    // 0.0~1.0
+    ELOHistory  []float64 `json:"elo_history"`  // 最近7天 ELO 趋势
+}
+```
+
+供应商 Fallback 链配置：
+```go
+type SupplierChain struct {
+    Model       string   `json:"model"`
+    Primary     string   `json:"primary"`     // 主供应商ID
+    Fallbacks   []string `json:"fallbacks"`  // 备用供应商列表（按优先级排序）
+    CooldownSec int      `json:"cooldown_sec"` // 冷却秒数，默认300
+    Strategy    string   `json:"strategy"`   // cost/quality/latency/manual
+}
+```
+

prd/competitor-analysis.md

@@ -0,0 +1,272 @@
+# AI-Ops 智能运维 — 竞品分析报告
+
+## 1. 竞品范围
+
+| 竞品 | 项目地址 | 技术栈 | 相关能力 |
+|-------|---------|--------|---------|
+| **LiteLLM** | berriai/litellm | Python/FastAPI | 告警系统（SlackAlerting）、健康检查、自动路由、容灾切换 |
+| **Sub2API** | Wei-Shaw/sub2api | Go/Gin/Ent | 基础代理健康、用量统计 |
+| **NewAPI / OneAPI** | Calcium-Ion/new-api | Go/Gin/GORM | 渠道监控、状态切换 |
+
+---
+
+## 2. 核心能力对标
+
+### 2.1 告警系统
+
+#### LiteLLM SlackAlerting（实现最完整）
+
+LiteLLM 的告警系统是当前开源 LLM Gateway 中最成熟的，其核心设计包括：
+
+**告警类型（12+种）**:
+```python
+class AlertType(str, Enum):
+    # LLM 相关
+    llm_exceptions = "llm_exceptions"          # LLM 调用异常
+    llm_too_slow = "llm_too_slow"              # 响应超时
+    llm_requests_hanging = "llm_requests_hanging"  # 请求悬停
+    # 资源与成本
+    budget_alerts = "budget_alerts"            # 预算超支
+    spend_reports = "spend_reports"            # 消耗报告
+    failed_tracking_spend = "failed_tracking_spend"  # 成本跟踪失败
+    # 数据库
+    db_exceptions = "db_exceptions"            # 数据库异常
+    # 运营报告
+    daily_reports = "daily_reports"            # 每日运营报告
+    # 部署与模型
+    cooldown_deployment = "cooldown_deployment"    # 部署冷却
+    new_model_added = "new_model_added"         # 新模型上线
+    # 故障与容灾
+    outage_alerts = "outage_alerts"             # 模型故障
+    region_outage_alerts = "region_outage_alerts"  # 区域故障
+    fallback_reports = "fallback_reports"       # 容灾切换报告
+```
+
+**关键技术细节**:
+- **批量化与性能优化**: 采用 `CustomBatchLogger` 基类，告警批量发送（10秒或超过 X 事件触发），避免高并发下的性能瓶颈
+- **消息摘要（Digest）模式**: 支持按 `(alert_type, model, api_base)` 聚合告警，默认 24h 窗口期，避免滥发
+- **多渠道分发**: 支持按告警类型路由到不同 Webhook，如 `alert_to_webhook_url = {AlertType.outage_alerts: "#ops-channel", AlertType.budget_alerts: "#finance-channel"}`
+- **告警阈值细分**: 悬停检测阈值可配置（默认 300s），故障检测分为 minor（5 次错误）和 major（10 次错误）
+- **区域故障检测**: 同一区域内 2+ 模型报告错误时触发 region_outage_alerts
+- **告警 TTL 缓解**: budget_alert_ttl=24h，outage_alert_ttl=1min，防止重复骚扰
+
+**健康检查端点**:
+- `/health` — 综合健康（可选择性检查已配置模型）
+- `/health/liveliness` / `/health/liveness` — 进程存活
+- `/health/readiness` — 依赖就绪（Redis、DB、Cache）
+- `/health/services?service=datadog` — 第三方服务健康
+- `/health/history` — 历史健康状态
+- `/health/latest` — 最新健康状态
+- `/health/backlog` — 请求队列积压
+- `/health/test_connection` — 测试特定模型连通性
+
+#### Sub2API / NewAPI / OneAPI
+- Sub2API: 仅提供基础代理状态查询，无结构化告警系统
+- NewAPI/OneAPI: 有渠道状态监控，支持切换上游，但缺乏自动化告警和根因分析
+
+### 2.2 自动路由与容灾
+
+#### LiteLLM Router Strategy
+LiteLLM 提供多种路由策略：
+- **lowest_latency**: 选择响应最快的部署
+- **lowest_cost**: 选择成本最低的部署
+- **lowest_tpm_rpm**: 选择 TPM/RPM 最低的部署
+- **least_busy**: 选择当前负载最低的部署
+- **auto_router**: 基于语义路由（使用 `SemanticRouter` 和向量编码器匹配请求到最适合的模型）
+- **budget_limiter**: 按 key/team 限制预算
+
+**容灾机制**:
+- **Cooldown**: 当部署连续失败时自动进入 cooldown 状态，暂时从路由池中移除
+- **Fallback**: 主模型失败时自动切换到备用模型
+- **Retries**: 配置重试次数和策略
+
+### 2.3 成本跟踪
+
+#### LiteLLM Cost Tracking
+- 维护 `model_prices_and_context_window_backup.json` 主数据库，包含所有支持模型的 input_cost_per_token / output_cost_per_token
+- 支持分层定价（tiered_pricing）、批量定价（batch pricing）、音频 token 定价
+- 每次请求完成后计算并记录成本
+- 支持自定义成本覆盖
+
+#### Sub2API Pricing Service
+- 从 LiteLLM 上游镜像 `model_prices_and_context_window.json`
+- 支持模型家族回退（如 gpt-5.3 未知时回退到 gpt-5.1）
+- 本地 fallback 文件缓存
+- 支持动态价格字段优先级
+
+---
+
+## 3. 差距分析（我们的机会）
+
+| 能力维度 | 竞品现状 | 我们的机会 |
+|---------|---------|---------|
+| **告警渠道** | LiteLLM 仅支持 Slack/Webhook，无企微/钉钉/飞书 | 全面支持中国企业常用渠道 +通用 Webhook |
+| **根因分析** | 竞品仅提供原始错误数据，无自动根因分析 | AI 驱动的根因分析，自动归类故障类型 |
+| **自愈能力** | LiteLLM 仅有 cooldown 和 fallback，无可编程自愈 | 可编程自愈脚本，支持自定义操作（切换供应商、限流、重启） |
+| **智能升级** | 竞品告警阈值是静态配置 | 基于历史数据自动建议/调整阈值 |
+| **多维度健康** | LiteLLM 健康检查偏重连通性 | 连通性 + 配额 + 延迟 + 错误率 + 成功率综合健康指标 |
+| **运维大盘** | LiteLLM 有 daily_reports，但无运维大盘概念 | 统一运维大盘，汇总所有指标与异常 |
+| **预测性运维** | 竞品均为事后告警 | 基于趋势预测的预警（如配额耗尽预测、故障趋势预测） |
+
+---
+
+## 4. 对产品规划的影响
+
+### 强化方向
+
+1. **告警系统设计参考 LiteLLM 的多类型分类**，但扩展为 15+ 种类型，增加：
+   - 配额耗尽预警（监测余额趋势）
+   - 响应时间 P99 突变预警
+   - 模型质量跳水预警
+   - 安全异常预警（密钥泄露、异常访问模式）
+
+2. **批量化与摘要机制**参考 LiteLLM 的 `CustomBatchLogger` 和 DigestEntry 设计：
+   - 告警批量发送（含压缩）
+   - 按 (alert_type, model, api_base) 聚合
+   - 可配置摘要窗口（默认 24h，支持 5min/1h/24h）
+
+3. **健康检查端点**参考 LiteLLM 的多层级设计：
+   - `/health` 综合健康
+   - `/health/live` 进程存活
+   - `/health/ready` 依赖就绪
+   - `/health/backlog` 队列积压
+   - `/health/test_connection` 模型连通性测试
+
+4. **自愈能力**超越竞品：
+   - LiteLLM 的 cooldown 只是"移除故障节点"，我们应提供"程序化自愈"，允许用户配置自定义动作
+   - 参考 LiteLLM 的 fallback 机制，但增加"智能切换策略"（根据成本/质量/位置综合决策）
+
+### 新增差异化能力
+
+5. **AI 驱动的根因分析**：竞品不具备，是核心差异化
+6. **运维大盘概念**：竞品无统一运维视图，我们应提供类似 Grafana Dashboard 的一体化运维大盘
+7. **预测性运维**：基于时序分析的预警，而不是事后告警
+
+---
+
+## 5. 对技术规划的影响
+
+### 应引入的设计模式
+
+| 设计模式 | 来源 | 应用场景 |
+|---------|------|---------|
+| **CustomBatchLogger** | LiteLLM | 告警事件批量处理，避免高并发下的 IO 瓶颈 |
+| **DualCache** | LiteLLM | 告警状态缓存（内存 + Redis），确保告警可靠性 |
+| **DigestEntry** | LiteLLM | 告警聚合，避免滥发 |
+| **AlertType + AlertTypeConfig** | LiteLLM | 可扩展的告警类型系统，支持按类型配置不同策略 |
+| **OutageModel + ProviderRegionOutageModel** | LiteLLM | 故障状态机，支持模型级和区域级故障检测 |
+| **DeploymentMetrics** | LiteLLM | 每部署的运行时指标（failed_request, latency_per_output_token） |
+| **Cooldown 机制** | LiteLLM | 故障部署自动移除，作为自愈动作的一种 |
+
+### 技术避坑
+
+1. **不重复造轮子**: LiteLLM 的告警系统已经很成熟，我们不需要重新设计整套机制，而是将其思想迁移到 Go 技术栈，并增加本地化适配
+2. **性能优先**: LiteLLM 的批量处理机制是关键，告警系统不能成为性能瓶颈
+3. **可观测性**: 参考 LiteLLM 的健康端点设计，确保所有依赖都有对应的就绪检查
+
+---
+
+## 附：FreeRide — OpenClaw 自动模型切换插件（市场调研）
+
+### 1. 基本信息
+
+| 项目 | 内容 |
+|-----|------|
+| **名称** | FreeRide |
+| **类型** | OpenClaw Skill（插件） |
+| **定位** | 自动模型选择 + Fallback 链管理 |
+| **技术栈** | Shell + OpenClaw 原生 API |
+| **开源地址** | `openclaw/skills/tree/main/skills/shaivpidadi/free-ride` |
+| **安装方式** | `/learn @openclaw/freeride` |
+
+### 2. 核心功能
+
+```
+FreeRide 做的事：
+1. 实时拉取 OpenRouter 免费模型列表（30+ 免费模型）
+2. 按社区 ELO 评分排序，选出当前最强免费模型
+3. 将最强模型设为主模型
+4. 自动配置 5 个高质量备用模型作为 Fallback 链
+5. 主模型限速 → 自动切换下一个，用户无感知
+6. 只修改 openclaw.json 中的 model 相关字段，不触碰其他配置
+```
+
+### 3. 实测数据
+
+- **每日完成**：200~500+ 次高质量对话
+- **覆盖场景**：写文章、代码调试、数据分析、日常聊天
+- **成本**：零（全部使用 OpenRouter 免费额度）
+
+### 4. 技术分析
+
+#### 4.1 设计哲学
+
+| 维度 | FreeRide | LiteLLM | 我们的 AI-Ops |
+|-----|---------|---------|--------------|
+| **目标用户** | 个人用户/极客 | 企业 | 企业运维团队 |
+| **模型来源** | OpenRouter 免费模型 | 任意 OpenAI兼容API | 多供应商中转 |
+| **核心价值** | 零成本用最强模型 | 企业级稳定性 | 供应商智能切换 + 运维自动化 |
+| **Failover 机制** | 简单的模型列表轮询 | cooldown + fallback + retries | 智能化 failover + 自愈 |
+
+#### 4.2 技术亮点
+
+**亮点1：实时模型排行**
+```bash
+# FreeRide 实时拉取 OpenRouter 免费模型，按 ELO 排序
+curl -s "https://openrouter.ai/models?free=true" | jq '.data | sort_by(.rating) | reverse'
+```
+→ **借鉴点**：可用类似思路监控各供应商的模型质量变化，自动发现"性价比突变"模型
+
+**亮点2：非破坏性配置更新**
+```bash
+# FreeRide 只更新 model 相关的 key
+jq ".model = \"$BEST_MODEL\"" openclaw.json > tmp.json && mv tmp.json openclaw.json
+```
+→ **借鉴点**：热切换配置时，先写入临时文件再原子替换，避免损坏配置文件
+
+**亮点3：Fallback 链自动编排**
+```bash
+# FreeRide 默认配置 5 个备用模型
+FALLBACK_MODELS="model_a,model_b,model_c,model_d,model_e"
+```
+→ **借鉴点**：供应商层面也可以做类似的多级 fallback，而不是单层 failover
+
+#### 4.3 不足与局限
+
+| 问题 | 说明 |
+|-----|------|
+| **无监控告警** | FreeRide 没有告警概念，模型挂了用户需要自己发现 |
+| **无用量统计** | 没有成本追踪，不知道花了多少钱 |
+| **无自愈脚本** | 只是切换模型，不能执行重启/通知等操作 |
+| **依赖 OpenRouter** | 只适合 OpenRouter，中国用户无法直接使用 |
+| **免费模型质量不稳定** | OpenRouter 免费模型 ELO 排名波动大，不适合企业生产 |
+
+### 5. 对 AI-Ops 的借鉴
+
+#### 5.1 可复用的设计
+
+| FreeRide 思路 | AI-Ops 如何借鉴 |
+|--------------|----------------|
+| 实时模型排行 | **供应商模型质量监控**：定时拉取各中转的模型列表，按响应速度/成功率排序 |
+| Fallback 链 | **多级降级策略**：主供应商 → 备供应商 → 降级回复（而不是简单的一层 failover） |
+| 非破坏性配置 | **配置热切换规范**：所有配置更新走原子替换，不直接改原文件 |
+| 限速自动切换 | **速率限制自适应**：监控各供应商 TPM/QPM 限制，预估耗尽时间并提前切换 |
+
+#### 5.2 AI-Ops 应超越 FreeRide 的地方
+
+```
+FreeRide 做到了：        AI-Ops 应做到：
+✅ 模型自动切换         ✅ 供应商整体健康度评估（不止模型）
+✅ Fallback 链          ✅ 切换策略可配置（成本优先/质量优先/延迟优先）
+❌ 无监控告警           ✅ 多渠道告警（企微/飞书/钉钉/Slack）
+❌ 无用量统计           ✅ 成本分摊到部门/项目/用户
+❌ 无自愈能力           ✅ 可编程自愈（切换 + 通知 + 锁定 + 升级）
+❌ 无运维大盘           ✅ 统一运维视图（健康/配额/成本/故障）
+```
+
+### 6. 结论
+
+FreeRide 是一个优秀的**个人用户工具**，核心价值是"零成本 + 自动切换"。它的设计哲学（自动选择 + 智能降级）对 AI-Ops 有参考价值，但企业级需求（监控/告警/成本/自愈）是它完全不覆盖的领域。
+
+**AI-Ops 的差异化定位**：不做 FreeRide 的企业版，而是做一个有**自愈能力的智能运维平台**，FreeRide 的思路是其中一个模块（供应商切换策略）。
+