release: bump version to 0.28.1

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

@@ -0,0 +1,361 @@
+# 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. 在输出结构中单独增加：
+   - 区域态势
+   - 证据来源
+   - 观测偏差说明
+   - 缺失区域证据