planet/docs/plans/frontend-ai-playground-development-plan.md

AI Playground Development Plan

目标

这份计划用于统一 aiprovider、backend AI facade、Playground 页面，以及后续 BGP / 告警 / 数据源健康 等 AI 入口的演进方向。

当前原则：

• aiprovider 继续作为独立模型网关
• backend 继续作为稳定业务入口
• frontend 负责测试台和业务 UI
• 先做“可控、可验证、可解释”的 AI 能力，再逐步引入 agent/tool calling

当前已完成

1. AI 网关基础层

已完成：

• 独立 aiprovider 服务
• backend -> aiprovider -> model provider 调用链
• provider/status 与 situational-awareness/analyze 稳定接口
• X-Request-ID 透传
• 轻量超时与重试
• MiniMax / Anthropic-compatible / OpenAI-compatible / Ollama 适配

相关文件：

• backend/app/api/v1/ai.py
• backend/app/services/ai_client.py
• aiprovider/main.py
• aiprovider/provider_service.py
• docs/technical/agents-aiprovider.md

2. 本地运行与配置打通

已完成：

• planet.sh 启动链路纳入 aiprovider
• planet.sh 启动完成后输出 Playground 入口
• docker-compose.yml 为 aiprovider 加入 env_file
• backend/.env 与 aiprovider/.env 两侧 service token 对齐
• Playground 状态缓存，避免页面切换时每次都重新请求 provider 状态

相关文件：

• planet.sh
• docker-compose.yml
• backend/.env.example
• aiprovider/.env.example

3. Playground UI 基础版

已完成：

• 新增前端路由 /playground
• 左侧 Provider 状态 + 测试说明
• 右侧 请求 / 结果 Tabs
• Provider 状态 支持手动刷新
• 测试说明 支持折叠
• 内部区域采用细滚动条
• 页面布局开始遵循“单屏工作区 + 模块内部滚动”规范

相关文件：

• frontend/src/pages/Playground/Playground.tsx
• frontend/src/App.tsx
• frontend/src/components/AppLayout/AppLayout.tsx
• frontend/src/index.css

4. 前端布局规范沉淀

已完成：

• 把“一屏工作区、主模块优先、模块内部滚动”的规范文档化
• 明确 BGP 页面为当前参考实现

相关文件：

• docs/technical/frontend-layout-guidelines.md
• frontend/src/pages/BGP/BGP.tsx

当前限制

1. Playground 还是 prompt playground，不是 agent playground

当前 Playground 的 观察项 / 目标 / 约束条件 都是人工输入。

模型现在拿到的是：

• 你手工输入的结构化字段
• 后端传递的少量静态上下文

模型现在拿不到：

• 实时 BGP 事件
• 真实告警列表
• 数据源健康状态
• 自动检索结果
• tool calling / skills / 自主取数

2. situational-awareness/analyze 还是通用提示词接口

当前更适合：

• 测试链路
• 测试模型输出风格
• 验证不同 provider 是否正常返回

当前还不适合：

• 直接当真实态势系统主入口
• 让用户手工维护长期分析模板
• 代替专用业务研判接口

3. 还没有可验证的真实业务输入注入

目前最缺的是：

• 从业务系统自动整理“事实输入”
• 再把这些事实喂给 AI

而不是继续让用户在 Playground 手工输入真实事件摘要。

短期计划

Phase A: Playground 收敛为稳定测试台

目标：

• 保持 Playground 简洁可用
• 不再继续堆“高级参数”

工作项：

• 继续微调左侧 Provider 状态 与 测试说明 的空间策略
• 保持 请求 / 结果 为单一主工作区
• 不引入盲填式高级字段
• 统一滚动条、卡片、溢出行为

完成标准：

• 笔记本视口下依然可用
• 各模块标题可见
• 主要阅读区始终是右侧 Tabs

Phase B: BGP AI 简报

目标：

• 不再依赖手工填写“观察项”
• 让系统自动把真实 BGP 数据注入 AI
• 让 BGP 页面逐步从“摘要汇总”升级为“证据驱动的区域态势分析”

建议实现：

• 新增专用后端接口，例如：
  • POST /api/v1/ai/bgp/brief
• 后端自动读取：
  • incidents summary
  • anomalies
  • recent events
  • collector coverage summary
• 后端将结构化事实注入 context / observations
• 前端在 BGP 页面增加“生成 AI 简报”

当前阶段说明：

• 第一版 BGP AI 简报 允许先落地为“值班摘要生成器”
• 也就是先把 incidents / anomalies / events / collector coverage 自动注入
• 允许模型先做事实摘要、风险归纳、建议动作

但这不应被视为 Phase B 的最终形态。

Phase B 后续还需要补齐：

• prefix geography 证据注入
  • iptoasn
  • opengeofeed
  • nro_delegated
• 基于 affected_regions 与 prefix geography 的区域聚合
• 区分“真实区域热度”与“collector coverage 偏差”
• 对高风险 prefix / ASN 给出更明确的国家、城市、运营商归属线索
• 让 AI 输出明确回答：
  • 哪些区域正在异常升温
  • 哪些结论只是观测站偏差
  • 当前还缺哪些区域证据

完成标准：

• 用户不需要手工录入 BGP 观察项
• AI 输出能明确区分“事实”和“研判”
• AI 不只是复述总量和最近几条事件，还能利用 prefix geography 与 affected regions 做区域态势判断
• 输出中能明确指出：
  • 高风险区域
  • 区域证据来源
  • collector coverage 偏差对判断的影响

Phase C: 告警 / 数据源健康 AI 简报

目标：

• 复用同样模式，扩展到其他模块

建议入口：

• Alerts 页面：异常与告警摘要
• DataSources 页面：采集失败与健康状态总结

原则：

• 每个业务页优先做“专用 AI 简报”
• 不优先做“万能大聊天框”

中期计划

1. Assessment Layer

目标：

• 不只返回自由文本
• 返回结构化的 assessment

建议输出字段：

• summary
• key_risks
• evidence
• recommendations
• confidence
• missing_data

这样后续才能：

• 持久化
• 回看
• 对比不同时间的 AI 结论
• 在 Earth / Dashboard / BGP 页面稳定展示

2. Evidence-first Runtime

目标：

• 所有 AI 分析先取真实数据，再调模型

原则：

• 先 evidence
• 再 prompt
• 最后才是自由生成

优先要做的不是更强聊天，而是：

• 更稳定的数据注入
• 更一致的事实模板
• 更清晰的结果结构

3. 按页面提供专用入口

目标：

• 让 AI 成为业务视图的一部分，而不是孤立 playground

优先顺序建议：

1. BGP AI 简报
2. Alerts AI 简报
3. DataSources 健康研判
4. Dashboard 总览总结

长期计划

1. Tool Calling / Agent Runtime

只有在以下基础稳定后再推进：

• 数据源健康信号稳定
• BGP / Alerts / Datasource evidence 注入稳定
• assessment 结构稳定

长期可做能力：

• AI 调用受控工具查询业务数据
• AI 调用检索/web search 做外部验证
• AI 生成建议而不是直接修改系统
• 审核后触发受控动作

2. 受控动作与闭环

潜在方向：

• 根据健康异常生成修复建议
• 根据态势变化生成处理建议
• 进入 review queue
• 审批后执行
• 验证结果并形成闭环

3. 多模块统一 AI 体验

长期目标不是一个孤立 Playground，而是：

• 每个业务页都有自己的 AI 入口
• 共享统一的 backend AI facade
• 共享统一的 assessment 结构
• 共享统一的 evidence 注入与审计链路

设计决策总结

为什么保留 aiprovider

因为它已经很好地承担了：

• provider 适配
• 协议兼容
• service token 边界
• 独立重启与部署

因此短期内不建议把它并回 backend。

为什么 Playground 不做成万能聊天页

因为当前更需要的是：

• 稳定测试链路
• 可验证业务输入
• 专用分析入口

而不是一个泛化但没有真实数据支撑的聊天框。

为什么优先做专用 AI 简报

因为：

• 数据可以自动注入
• 用户心智更清晰
• 输出更容易结构化
• 更容易校验事实与研判是否一致

下一步建议

按优先级建议接下来这样做：

1. 稳住 Playground 当前布局，不再大幅重做
2. 在 BGP 页面新增专用 “AI 简报” 入口
3. 后端新增 BGP brief 专用接口，自动注入真实数据
4. 补齐 BGP brief 的区域态势证据层
5. 把 AI 输出逐步从自由文本升级为结构化 assessment

BGP Brief 后续子项

为避免把“已有 AI 简报”误判成“区域分析已完成”，这里单独记录 BGP brief 的后续 backlog：

1. 把高风险 prefix 命中的 iptoasn / opengeofeed / nro_delegated 结果注入 brief context
2. 按国家/城市聚合 active incidents、anomalies、affected prefixes，生成区域热点事实层
3. 把 collector coverage 与区域热点并排注入，避免模型把观测偏差误判成区域风险
4. 对高风险 ASN / prefix 追加归属线索，如国家、城市、可能运营商或注册区域
5. 在输出结构中单独增加：
   • 区域态势
   • 证据来源
   • 观测偏差说明
   • 缺失区域证据