planet/docs/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](/home/ray/dev/linkong/planet/backend/app/api/v1/ai.py)
- [backend/app/services/ai_client.py](/home/ray/dev/linkong/planet/backend/app/services/ai_client.py)
- [aiprovider/main.py](/home/ray/dev/linkong/planet/aiprovider/main.py)
- [aiprovider/provider_service.py](/home/ray/dev/linkong/planet/aiprovider/provider_service.py)
- [docs/agents/aiprovider.md](/home/ray/dev/linkong/planet/docs/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](/home/ray/dev/linkong/planet/planet.sh)
- [docker-compose.yml](/home/ray/dev/linkong/planet/docker-compose.yml)
- [backend/.env.example](/home/ray/dev/linkong/planet/backend/.env.example)
- [aiprovider/.env.example](/home/ray/dev/linkong/planet/aiprovider/.env.example)

### 3. Playground UI 基础版

已完成：

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

相关文件：

- [frontend/src/pages/Playground/Playground.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/Playground/Playground.tsx)
- [frontend/src/App.tsx](/home/ray/dev/linkong/planet/frontend/src/App.tsx)
- [frontend/src/components/AppLayout/AppLayout.tsx](/home/ray/dev/linkong/planet/frontend/src/components/AppLayout/AppLayout.tsx)
- [frontend/src/index.css](/home/ray/dev/linkong/planet/frontend/src/index.css)

### 4. 前端布局规范沉淀

已完成：

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

相关文件：

- [docs/frontend/frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/frontend/frontend-layout-guidelines.md)
- [frontend/src/pages/BGP/BGP.tsx](/home/ray/dev/linkong/planet/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. 在输出结构中单独增加：
   - 区域态势
   - 证据来源
   - 观测偏差说明
   - 缺失区域证据